Storage, blobs, and artifacts

xcsh separates append-only conversation state from large or generated payloads. Session JSON Lines (JSONL) preserves the event graph; blob and artifact stores keep bulky data addressable without inflating every session entry.

How are stored values allocated and resolved?

Storage helpers choose user or project roots, allocate collision-resistant identifiers, and record names separately from content addresses. Text artifacts remain inspectable; binary blobs are externalized and referenced by uniform resource locator (URL)-like identifiers. URL handlers validate the scheme and authority before opening the backing object.

How do resume, fork, and move treat state?

Resume rebuilds context from the selected session leaf. Forking creates a new branch without rewriting the source branch. Moves must update the session reference and its dependent stored values as one operation or leave the original valid; partial copies are not a successful move.

How is filesystem discovery cached?

The scan cache partitions keys by root and discovery options, evicts by freshness policy, and uses a short empty-result recheck so a newly created configuration file is noticed. Mutating code owns invalidation. A new consumer must define its cache key, freshness need, and invalidation points explicitly.

Read packages/coding-agent/src/session for the append-only event graph and packages/coding-agent/src/discovery for the scan cache.

Treat a session reference as durable only after its referenced artifact is readable. A failed move or fork must leave the original graph usable and must not publish a half-written destination. To verify a storage change, create a session with a text artifact and a binary blob, resume its leaf, fork it, and confirm that both branches resolve their own references. Remove only the temporary test root after those reads succeed.