7. Snapshots: Atomic State Synchronization

Requirements

• Atomic Consistency: A snapshot must represent a synchronized state of the filesystem (VCS/Lockfile) and the database (Postgres). Restoring one without the other is strictly forbidden.
• Federated Coherence: The strategy must account for the distributed nature of extensions, capturing the exact versions of the Core and all installed organs as a single, unified signature.
• Performance and Immediacy: State capture must be near-instantaneous to minimize system suspension during autonomous creation rituals.
• Hybrid Infrastructure Support: Mandatory utilization of accelerated snapshots on Copy-on-Write (COW) filesystems (e.g., Btrfs) for maximum performance, while maintaining functional fallback compatibility with standard filesystems.
• Integrity of Provenance: Every snapshot must include a manifest that allows the system to verify that the physical body of the Daemon matches the captured instructions before reanimation.

Considered Options

Decision Outcome

A Hybrid Snapshot Strategy governed by a Checkpoint Protocol is adopted. This ensures the Daemon can "blink" its current reality into permanence without risk of corruption.

1. The Checkpoint Protocol (The Freeze)

To guarantee consistency during self-modification, the system defines an atomic "Freeze" ritual that must occur before any destructive operation or state capture.

1. Suspend: The machine's active task queues are paused, ensuring the database is quiet and no new writes are in flight.
2. Lock (The Body Signature): The system scans the Core and all Extensions. It generates a lychd.lock file recording the current VCS Revision Hash of every active repository within the Federation.
3. Snapshot (The Soul): The persistent storage driver executes a data backup synchronized with the generation of the lockfile.
4. Resume: Normal operation continues.

2. Logic Persistence: The Federated Manifest and the Hexadecimal Mandate

Jujutsu (jj) is the exclusive mechanism for versioning the Daemon's logic. Unlike standard Git, which conflates change tracking and snapshots, Jujutsu maintains two distinct identifiers for every state transition: - Change ID (Alphabetic, e.g., qzmzpxyl): A stable identifier that tracks a conceptual task. This ID remains constant across amends, rebases, and modifications. - Commit ID (Hexadecimal, e.g., bc915fcd): An immutable, cryptographic hash of the exact state of the file tree at a frozen moment in time.

3. Data & VCS Coherence: Btrfs Integration

To achieve instant, transactional rollbacks of both memory (database) and mind (version control graph), LychD marries Btrfs Copy-on-Write (COW) subvolumes with Jujutsu's SQLite-backed repository state.

• The Btrfs Subvolume Layout: Both the crypt/ (Postgres application database) and the .jj/ (Jujutsu's internal SQLite state-graph) exist on Btrfs subvolumes.
• Coordinated Blink: When the Checkpoint Protocol is triggered, Btrfs executes a coordinated COW snapshot of both the Postgres tables and the SQLite version-control graph. The entire repository state is physically captured in a single, ACID-compliant database snapshot on disk.

The system abstracts data backup through a Storage Driver Interface, allowing the Lich to adapt its strategy based on the host environment.

• The Btrfs Strategy (Accelerated): If the host filesystem is detected as Btrfs, the database directory is mounted as a subvolume. Snapshots are instant and atomic at the kernel level. The active subvolume is configured with chattr +C (No_COW) to prevent fragmentation during runtime, while the snapshot action utilizes COW for its atomic "blink."
• The Universal Strategy (Fallback): On standard filesystems (Ext4/XFS), the system falls back to standard export mechanisms. While reliable, this method incurs a performance penalty proportional to the size of the memory.
• The ZFS Contingency (Future Evolution): While Btrfs serves as the primary native accelerator, the system recognizes the merit of the Zettabyte File System (ZFS) for high-availability environments. The Storage Driver Interface is architected to eventually embrace ZFS dataset snapshots. This "future-gate" allows the Daemon to leverage ZFS's superior self-healing and "send/receive" capabilities. Because the Checkpoint Protocol is agnostic to the underlying shell commands, adding ZFS support is a matter of logical mapping, not a core re-write.

4. The Rehydration Gate

When a snapshot is restored, the system enforces a strict alignment check before reanimating the Daemon's consciousness.

• Body-Soul Verification: The system compares the captured lychd.lock hexadecimal Commit IDs with the current physical body.
• The Jujutsu Warp: Restoring the code is not a simple file overwrite. The system executes jj edit <Commit_ID>. This physically warps Jujutsu’s working copy commit (@) of the workspace back to the frozen node in the graph, making it active.
• Mandatory Rebirth: If the Cognitive State preserved in the memory belongs to a version of logic newer than the current physical body, the system refuses to reanimate the mind. This triggers a mandatory rebuild/restart to bring the physical substrate into alignment with the restored soul, preventing schema mismatches and cognitive corruption.
• Rehydration Ritual: Restoring a snapshot is the Reanimation of the machine. The storage driver physically resets the database directory using the Btrfs or Postgres snapshot. Simultaneously, the jj edit command aligns the codebase. This ensures the Soul (Data) is physically identical to the moment the Body (Code) was captured, bypassing the risk of schema drift entirely.

Consequences