13. Layout: The Three Domains

Requirements

• Path Symmetry: Mandatory resolution of identical paths whether running on the Host or inside the Container, eliminating the need for context-aware path translation.
• The XDG Trinity: Strict adherence to the XDG Base Directory Specification (CONFIG, DATA, CACHE) to ensure standard Linux portability and predictable volume mapping.
• Separation of Permissions: Physical distinction between The Law (Configuration/Core Logic) mounted Read-Only, and The Life (Workspace/Database) mounted Read-Write.
• Federated Lock Geography: Provision of a central coordinate for the lychd.lock file to anchor the deterministic state of the system's organs.
• Shadow Realm Infrastructure: Support for isolated subdirectories within the Lab to facilitate speculative execution and branching during creation rituals.
• Anatomical Persistence: A dedicated region for the Phylactery's (06) chambers, optimized for Copy-on-Write snapshots.
• Cartographic Rigidity: Hardcoded locations for all critical domains to prevent fragmentation of the system's body.

Considered Options

Decision Outcome

The filesystem is organized into Three Domains that govern the existence of the Daemon.

1. The Codex (XDG_CONFIG_HOME)

"The Law." This Domain contains immutable configuration files and user-defined intents. It is mounted Read-Only into the container. The Agent cannot change the Law; only the Magus can modify these scrolls.

This ADR defines where the Codex lives and how it is mounted. The Codex contract (global lychd.toml, runes/ ownership, anchor rules, schema cardinality, and loader validation) is governed by Configuration (12).

• Host Path: ~/.config/lychd/
• Internal Path: ~/.config/lychd/ (Symmetric)

Contents (Codex Taxonomy):

• lychd.toml: Global settings

• Rune Schemas (Anchored Instances):

  • runes/: Validated TOML instance declarations.
    • animator/: Animation root defaults and child anchors.
      • soulstones/: Local infrastructure intent (container-backed providers).
        • llamacpp/: Instances of llama.cpp providers (TOML files).
        • vllm/: Instances of vLLM providers.
        • sglang/: Instances of SGLang providers.
      • portals/: Remote API intent (network-backed providers).
        • openai/: Instances of OpenAI portals.
        • anthropic/: Instances of Anthropic portals.
        • (future anchors live here as additional subdirectories)

Layout Notes:

• The taxonomy above shows common built-in anchors for operator orientation.
• Installed extensions may add additional rune anchors under runes/ while preserving the same directory-based ownership model.
• Loader rules, identity derivation, schema cardinality, and validation doctrine are specified in Configuration (12).

2. The Crypt (XDG_DATA_HOME)

"The Body and Soul." This Domain contains the persistent reality of the system. It is the primary storage volume, subdivided into regions of varying permission levels.

• Host Path: ~/.local/share/lychd/
• Internal Path: ~/.local/share/lychd/ (Symmetric)

Internal Regions:

• lychd.lock: The Federated Lockfile. Living in the root of the Crypt, it pins the exact hashes of all logic.
• core/: Core source code. Mounted Read-Only at runtime to maintain the Security (09) seal.
• extensions/: Private Crypt extension source. Pre-v1 this is assimilable, Forge-composed code rather than a stable third-party plugin ABI. Mounted Read-Only at runtime.
• postgres/: The site of the Phylactery. A dedicated subvolume containing the partitioned database chambers. Mounted Read-Write.
• lab/: The site of Genesis. A Read-Write region containing isolated subdirectories for Shadow Realm branches, allowing the machine to dream of new code without impacting reality.

3. The Forge (XDG_CACHE_HOME)

"The Industrial District." This Domain contains disposable, machine-generated artifacts. It is excluded from backups and snapshots and can be purged at any time.

• Host Path: ~/.cache/lychd/
• Internal Path: Ephemeral (Not typically mounted).

Contents:

• Build artifacts for the physical image.
• Temporary environment manifests used during the Packaging (17) ritual.

The Outlands (External Mounts)

Beyond the Three Domains lies The Outlands—the User's own filesystem. To interact with these regions, the user must explicitly mount an Outland directory. These are mapped to a dedicated internal workspace target.

• Internal Path Target: ~/work/

Container-Side Topology

Inside the container, the layout mirrors the Host Domains via volume mounts. By utilizing identity mapping, the container user accesses the Read-Write paths natively without permission mismatches.

4. Dual-Plane Trust Delta

The layout now separates trusted and untrusted execution geography.

• Vessel mounts trusted Codex and durable control-plane regions. Agents, graph state, LLM calls, routing, validation, and promotion policy stay in this trusted plane.
• Safe creation/control-plane work may remain in Vessel when it does not require arbitrary code execution or risky host mutation. Tomb is chosen by execution risk, not by the word "creation" alone.
• The Tomb mounts only task/workspace/artifact regions with minimal write scope. It is the execution hand for unsafe labor, not an agent home.
• Suggested Tomb regions:
  • ~/.local/share/lychd/tomb/jobs/ — one subdirectory per SAQ job to prevent file collisions between concurrent Ghouls
  • ~/.local/share/lychd/tomb/workspaces/
  • ~/.local/share/lychd/tomb/artifacts/
  • ~/.local/share/lychd/tomb/cache/
• The Tomb must not mount writable Codex, provider secrets, or host trigger/signaling paths. If a Tomb profile needs Codex-shaped facts, it receives no Codex mount by default or a read-only/sanitized projection.
• The Tomb may receive a narrow queue-only SAQ/Postgres credential for execution-plane job claiming, acknowledgement, and retry bookkeeping, but no control-plane database authority.
• The Tomb runs no agent logic, graph runners, or LLM calls. It is a brainless executor. See Workers (14).

5. Authority Matrix

Consequences