Module core 

Content-addressed mount core.

ContentAddressedMount is the platform-agnostic implementation of PlatformShell. It speaks heddle: given a thread name, it resolves it to a state via refs::RefManager, pulls the tree root from the object store, and answers filesystem queries by walking the Merkle DAG lazily.

Two-tier write model

Writes don’t go through a generic in-memory page cache that drains to disk on heddle capture. They go straight into heddle’s CAS as soon as the file is closed:

1. Hot tier (in-memory partial buffers). A write(offset, bytes) is keyed by NodeId and accumulates in a single Vec<u8> per open file. Reads of the same node during the buffer’s lifetime serve from the buffer (so a write -> read round-trip in the same FUSE session sees the new bytes immediately).

2. Warm tier (CAS-promoted blobs). When the kernel signals end of file (flush/close), or after an idle threshold (the PromotionPolicy::idle_after window), we hash the buffer, write a blob via the same ObjectStore API that heddle capture uses, and record path -> blob_oid in a per-thread pending tree. The hot buffer is dropped.

3. Pending tree. A BTreeMap<RelPath, PendingEntry> plus a BTreeSet<RelPath> of deletions that overlay the immutable state’s tree. lookup/enumerate/read consult the pending tier first so the mount serves “what the agent just wrote” rather than the parent state.

Crash semantics

The hot tier lives only in process memory; an unclean unmount discards in-flight writes. The warm tier is written to the heddle object store via the same atomic write path that heddle capture uses, so a promoted blob survives a crash even if the surrounding capture() call never completes — the next agent that captures the same content will hit the dedup fast path.

Why this beats a worktree-walk capture

heddle capture from a worktree currently walks every file, hashes its contents, and writes the blob if new. Mount writes do that work during the write itself, so capture-from-mount becomes:

• drain pending tree into a real Tree object
• record State referencing the tree
• update the thread’s HEAD

No worktree walk, no re-hashing, no blob duplication across threads — two agents writing the same import { foo } from 'bar' to two different files write one blob.

Structs

ContentAddressedMount

In-mount overlay: a snapshot-time view of the parent state plus pending writes the agent has issued since.

PromotionPolicy

Tunables for when buffered writes get promoted to CAS.