Workspace Manifests

A manifest remembers how to build the stage; the actors still need their own travel plans.

1. Motivation

Workspace setup often needs to move between a laptop, CI, and production. A manifest captures that reconstructive shell: one Backend construction contract, requested optional extensions, and user Entity schemas with placements. It deliberately excludes stored rows and physical Backend data. That boundary keeps configuration reviewable without turning every export into an accidental database backup.

2. Export and Replay

import heavenbase as hb

ws = hb.HeavenBase("shop", preset="debug")
manifest = ws.to_manifest()
clone = hb.HeavenBase.from_manifest(manifest)

Durable replay creates an absent workspace or opens a compatible registered one. It does not activate the workspace. Use detached=True for a caller-owned facade that should not enter the Context workspace directory:

scratch = hb.HeavenBase.from_manifest(manifest, detached=True)

Detached does not mean temporary storage, automatic cleanup, or relaxed Backend identity checks.

3. Version 2 Construction

Version 2 has one top-level construction envelope and no parallel top-level config.

Kind	Envelope	Replay behavior
Ambient	`{"kind": "ambient"}`	Resolve ordinary workspace defaults
Preset	`{"kind": "preset", "preset": "debug"}`	Resolve the named preset
Backends	`{"kind": "backends", "config": {...}}`	Rebuild the complete Backend map
Runtime	`{"kind": "runtime", "identifiers": {...}}`	Reconnect matching live Backend instances

Runtime identifiers prove Backend identity, not connection configuration. Replay never invents endpoints, credentials, paths, or clients from an identifier.

4. Manifest Shape

kind: heavenbase.workspace.manifest
version: 2
id: shop
construction:
  kind: backends
  config:
    main:
      type: sqlite
      database: shop.db
extensions:
  - database
entities:
  - entity_id: product
    fields:
      object_id: {type: identifier, pk: true}
      name: {type: short-text}

extensions stores requested optional roots. Required and transitive dependencies are recomputed during replay, while extension-owned Entity schemas are rebuilt by their owners. backend_summary may appear as inspection metadata. It never configures or reconnects a Backend.

5. Save and Load Files

manifest = hb.WorkspaceManifest.from_dict(ws.to_manifest())
manifest.save("workspace.yaml")

loaded = hb.WorkspaceManifest.load("workspace.yaml")
restored = loaded.open()

Paths ending in .json use JSON; other paths use YAML. Manifest objects deep-copy nested construction values and serialized mappings, so editing an exported dictionary does not mutate the source object.

6. Replace the Environment

Preset and configured-Backend manifests may replace their complete construction envelope at replay:

production = hb.HeavenBase.from_manifest(
    manifest,
    backends={"main": {"type": "postgres", "database": "shop"}},
)

Replacement is whole-envelope substitution, never recursive merge. The manifest still owns the workspace id, requested extensions, and Entity schemas. Treat explicit Backend maps as sensitive when they contain credentials. Prefer environment-owned replacements when secrets should not travel with the manifest.

7. CLI Workflow

hb ws manifest shop > workspace.yaml
hb ws import workspace.yaml
hb ws activate shop

Import registers the reconstructed workspace and leaves active selection unchanged. Creation and import intentionally have no --active option; activation is a separate decision.

8. Scope and Recovery

Included	Not included
Workspace id	Stored Entity rows
Complete Backend construction envelope	Backend files and databases
Requested optional extension roots	Provider credentials not present in config
User Entity schemas and placements	Live clients and process state
Optional Backend summaries	A cross-environment data migration

After replay, reconnect or re-ingest domain data through its owning API. For example, load the database extension and call ws.database.ingest(...) when external catalog metadata is needed. Version 1 manifests remain readable at the input boundary and are normalized to version 2. New exports always emit version 2.

Summary

A manifest reconstructs a workspace shell, not its rows.
construction is the single Backend replay authority.
Import and activation remain separate operations.
Required dependencies are recomputed from requested optional roots.

Further Exploration

Related resources:

Workspace — Lifecycle, Context ownership, and durable identity
Backends — Construction, tags, and routing truth
Extensions — Requested roots and activation dependencies

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. Motivation

2. Export and Replay

3. Version 2 Construction

4. Manifest Shape

5. Save and Load Files

6. Replace the Environment

7. CLI Workflow

8. Scope and Recovery

Summary

Further Exploration

​1. Motivation

​2. Export and Replay

​3. Version 2 Construction

​4. Manifest Shape

​5. Save and Load Files

​6. Replace the Environment

​7. CLI Workflow

​8. Scope and Recovery

​Summary

​Further Exploration

1. Motivation

2. Export and Replay

3. Version 2 Construction

4. Manifest Shape

5. Save and Load Files

6. Replace the Environment

7. CLI Workflow

8. Scope and Recovery

Summary

Further Exploration