> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Manifests

> Replay a workspace shell without pretending its rows fit in the carry-on.

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

<br />

## 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.

<br />

## 2. Export and Replay

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
scratch = hb.HeavenBase.from_manifest(manifest, detached=True)
```

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

<br />

## 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.

<br />

## 4. Manifest Shape

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<br />

## 5. Save and Load Files

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<br />

## 6. Replace the Environment

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<br />

## 7. CLI Workflow

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<br />

## 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.

<br />

## 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.

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [Workspace](/features/workspace) — Lifecycle, Context ownership, and durable identity
  * [Backends](/features/backends) — Construction, tags, and routing truth
  * [Extensions](/features/extensions) — Requested roots and activation dependencies
</Tip>

<br />