Crypt

"The Codex writes the laws, but the Crypt holds the memories. It is the cold earth in which the Lich rests."

The Crypt is the persistent data volume of the LychD system. While the Codex is immutable configuration, the Crypt is living tissue.

It is physically located at ~/.local/share/lychd (respecting XDG_DATA_HOME).

🧱 The Physical Foundation (Persistence)

The Crypt employs a Decoupled Strategy for persistence. The architecture treats Code (Files) and Data (Database) as separate organs with different preservation needs.

1. Code Persistence (The Body)

Mechanism: Jujutsu-managed repository federation.

The Code (Extensions and Core Source) is managed as a collection of repositories whose local working state is governed through Jujutsu while Git remains the exchange substrate.

• Safety: Every modification is a recorded change. Local intent is visible through jj log; distributed exchange still moves through Git remotes.
• Universality: This works on any filesystem (Ext4, Btrfs, XFS).

2. Data Persistence (The Soul)

Mechanism: Hybrid Snapshots. The Database (Postgres) is binary and fragile. It requires atomic backups. Ideally, it lives on a Btrfs Subvolume for fast rollback of whole body/soul state, but it can function on standard filesystems via pg_dump.

• Immortal Mode (Btrfs): Fast subvolume snapshots for body/soul rollback.
• Mortal Mode (Ext4): Slow SQL dumps. Functional, but heavy.

🗺️ The Cartography of the Crypt

The Crypt is a flat, federated structure. It is not nested inside a single "active" folder.

graph TD
    Crypt[~/.local/share/lychd/]

    Crypt --> Core[core/]
    Crypt --> Lab[lab/]
    Crypt --> Ext[extensions/]
    Crypt --> PG[postgres/]
    Crypt --> Snap[snapshots/]
    Crypt --> Lock[lychd.lock]

    subgraph "Sphere 0: The Self"
        Core -- JJ/Git Repo --> Source[src/]
    end

    subgraph "Sphere I: Workspace"
        Lab -- Scratchpad --> Projects
    end

    subgraph "Sphere III: The Federation"
        Ext -- JJ/Git Repo --> PluginA
        Ext -- JJ/Git Repo --> PluginB
    end

    subgraph "The Phylactery"
        PG --> Data[data/]
    end

    style Crypt fill:#2a2a2a,stroke:#7c4dff,stroke-width:2px
    style PG fill:#1a1a1a,stroke:#ff5252
    style Core fill:#1a1a1a,stroke:#40c4ff
    style Ext fill:#1a1a1a,stroke:#00e5ff

🔮 The Spheres of Creation

To prevent the Lich from destroying itself or the Magus's data, it operates within a Hermetic Seal. The Agent interacts with the world via specific Spheres.

🧪 Sphere I: The Lab (Internal / Read-Write)

Host Path: ~/.local/share/lychd/lab \(\leftrightarrow\) Container Path: ~/.local/share/lychd/lab

The Genesis Sphere. This is the Agent's private scratchpad.

• Usage: Cloning new repos, drafting extensions, running tests.
• Safety: Managed by Jujutsu/Git inside the project folders. Not system-backed.

🌍 Sphere II: The Outlands (External / Read-Write)

Host Path: (User Projects) \(\leftrightarrow\) Container Path: ~/work/...

The Labor Sphere.

• Mounts: The Magus defines external paths (e.g., ~/Projects/MyStartup) to let the Agent work on local code.
• Safety: The VCS Ward. The Agent refuses to touch this sphere unless a recognized repository is present and clean.
• Execution Boundary: Outlands is a workspace geography, not an execution authority. Vessel controls policy and promotion; Tomb receives only task-scoped Outland access when unsafe execution must touch those files.

🧩 Sphere III: The Extensions (Internal / Read-Only)

Host Path: ~/.local/share/lychd/extensions \(\leftrightarrow\) Container Path: ~/.local/share/lychd/extensions

The Living Tissue Sphere.

• Federation: A collection of Jujutsu/Git repositories tracked by lychd.lock.
• Promotion: To install a new extension, the Agent builds it in the Lab, then triggers a Promotion Ritual to move it here and commit the change.

📚 Sphere IV: The Library (External / Read-Only)

Host Path: (External) \(\leftrightarrow\) Container Path: ~/work/library/...

The Reference Sphere.

• Purpose: The Agent can read the Magus's books/docs (RAG), but it is physically barred from modifying them. The Library is a read-only Outland mount, not a separate trusted domain.