Replace RuntimeHost full state with CAS-backed materialization handles

[flyingrobots]

Parent: #734
Blocked by: #735, #737

Outcome

The default runtime does not require a complete WarpState or visible graph to reside in process memory.

Scope

• Replace RuntimeHost._cachedState and associated full-view caches with MaterializationHandle.
• Define independently addressable roots for nodes, edges, properties, edge births, adjacency, frontier, Roaring indexes, and provenance support.
• Stream patch reduction into git-cas-backed pages.
• Execute bounded readings from the support/page handles.
• Keep an explicit diagnostic whole-state operation only if it is bounded or opt-in.

Proof

• Constrained-memory fixture exceeds process-resident graph capacity.
• Property and neighborhood readings touch only required pages/support.
• Materialization can resume from a retained handle.
• No projection step reconstructs complete ORSets as the normal path.
• Related Out-of-core materialization and streaming reads #136 and End-To-End Graph Streaming Reads And Writes #565 are closed or narrowed based on delivered scope.

[coderabbitai]

🔗 Related PRs

#639 - Guard fresh live observer materialization [merged]
#642 - Close materialization boundary proof [merged]
#708 - Fix live materialization state-cache hits [merged]
#726 - Move graph exports behind v19 public API boundary [merged]
#727 - Expose diagnostics materialization scope helpers [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[flyingrobots]

Acceptance addendum: warm materialization is mandatory\n\nA live repository report says materialization currently takes the cold path on every invocation. This issue is not complete merely because state is represented by handles.\n\nRequired proof:\n- Materialize the same causal coordinate twice and after a fresh Runtime reopen.\n- The second and reopened executions resolve a retained git-cas materialization handle and do not replay/reduce history already covered by that handle.\n- Instrument cache key/coordinate, hit or miss, retained-handle identity, age, logical and physical bytes when available, pages touched, patches replayed, and phase timings.\n- Add a benchmark that reports cold versus warm work. Gate on structural work avoided (zero already-covered patches reduced and no unrelated pages opened), not a flaky wall-clock ratio.\n- A stale or basis-mismatched handle must miss honestly and publish a replacement through git-cas policy; WARP must not maintain a shadow cache.

[flyingrobots]

Confirmed cache-bypass mechanism

The current implementation contains a deterministic repeated-materialization miss:

• RuntimeHost.materialize() sets wantDiff whenever _cachedIndexTree is non-null, which becomes true after the first materialization builds the view index. [cite: src/domain/RuntimeHost.ts#413-418@393f0ed9da8e124763aef5931b2f0a1dda3291cb] [cite: src/domain/RuntimeHost.ts#868-878@393f0ed9da8e124763aef5931b2f0a1dda3291cb]
• MaterializeLiveStrategy.tryResolveSnapshotCache() returns null before even calling getExact() whenever wantDiff is true. [cite: src/domain/services/controllers/MaterializeLiveStrategy.ts#238-249@393f0ed9da8e124763aef5931b2f0a1dda3291cb]
• The existing test explicitly codifies that bypass rather than testing a same-coordinate warm hit with an existing index. [cite: test/unit/domain/services/controllers/MaterializeController.snapshotCache.test.ts#241-265@393f0ed9da8e124763aef5931b2f0a1dda3291cb]

This explains same-process repeated cold replay. Across Runtime reopen, an exact snapshot may be found, but snapshotToMaterializeResult() still rebuilds adjacency from a fully decoded WarpState, while the cache payload itself is stored as encodeWarpFullState; that remains graph-sized hydration rather than bounded page-backed observation. [cite: src/domain/services/controllers/MaterializeSnapshotCacheResult.ts#31-53@393f0ed9da8e124763aef5931b2f0a1dda3291cb] [cite: src/infrastructure/adapters/GitCasWarpStateCacheAdapter.ts#324-359@393f0ed9da8e124763aef5931b2f0a1dda3291cb]

The #738 implementation must first add a regression proving an unchanged indexed coordinate warm-hits without replay, then replace the full-state snapshot contract with retained materialization/page handles. A diff should be needed only for an actual suffix from a compatible predecessor, not merely because an index exists.

[flyingrobots]

Confirmed warm-hit amplification

Even a successful current cache hit is not cheap or bounded:

• _restoreBuffer() accumulates every restored chunk and concatenates the complete payload; _loadSnapshotState() then decodes the full WarpState. [cite: src/infrastructure/adapters/GitCasWarpStateCacheAdapter.ts#240-261@393f0ed9da8e124763aef5931b2f0a1dda3291cb]
• The hit immediately mutates lastAccessedAt, which rewrites the WARP-owned JSON index blob and compare-and-swaps its mutable ref. [cite: src/infrastructure/adapters/GitCasWarpStateCacheAdapter.ts#192-238@393f0ed9da8e124763aef5931b2f0a1dda3291cb] [cite: src/infrastructure/adapters/GitCasWarpStateCacheAdapter.ts#262-268@393f0ed9da8e124763aef5931b2f0a1dda3291cb]
• Converting the hit into a materialization result rebuilds complete adjacency from the decoded state. [cite: src/domain/services/controllers/MaterializeSnapshotCacheResult.ts#41-53@393f0ed9da8e124763aef5931b2f0a1dda3291cb]

Therefore the existing hit path is O(graph) payload hydration plus an O(cache-index) metadata mutation. The immediate same-coordinate bypass fix is worthwhile, but #738 is not complete until ordinary Observers consume page and support handles without full-state decode or adjacency reconstruction.

[flyingrobots]

Existing streaming reducer is projected back into a full graph

The repository already contains most of the node/edge page-reduction mechanism, but the live materialization bridge currently defeats its persistence and memory properties:

• StateSession.close() flushes the two trie-backed OR-Sets and returns their immutable roots. [cite: src/domain/orset/session/StateSession.ts#157-165@393f0ed9da8e124763aef5931b2f0a1dda3291cb]
• MaterializeSessionBridge always opens a fresh session with both roots set to null, then seeds it from every entry and tombstone in the full base WarpState. [cite: src/domain/services/controllers/MaterializeSessionBridge.ts#80-136@393f0ed9da8e124763aef5931b2f0a1dda3291cb]
• After reduction it scans every node/edge element state back into complete in-memory ORSets, copies every property and edge-birth entry, builds complete adjacency, and discards the roots returned by close(). [cite: src/domain/services/controllers/MaterializeSessionBridge.ts#27-77@393f0ed9da8e124763aef5931b2f0a1dda3291cb] [cite: src/domain/services/controllers/MaterializeSessionBridge.ts#138-170@393f0ed9da8e124763aef5931b2f0a1dda3291cb]
• Runtime boot also constructs a process-local PageCache, so page residency is still WARP-owned. [cite: src/domain/warp/RuntimeHostBoot.ts#333-348@393f0ed9da8e124763aef5931b2f0a1dda3291cb]

Implementation direction: make the flushed roots, plus independently paged properties, edge births, frontier, provenance, and index roots, the durable MaterializationHandle; reopen those roots for suffix reduction; stop projecting a normal result back to WarpState. The explicit whole-state diagnostic path may perform that projection under an opt-in bound. @git-stunts/git-cas@6.2.0 already supplies pages, bundles, managed CacheSet, retention witnesses, and cache diagnostics, so WARP should provide schema and causal keys only.

[flyingrobots]

Removal replay currently scans the complete trie

The session reducer has another graph-scale path that must be removed with the materialization-handle work:

• NodeRemove and EdgeRemove retain the target identity, but mutateInSession() passes only observed dots into StateSession. [cite: src/domain/services/JoinReducerSession.ts#333-357@393f0ed9da8e124763aef5931b2f0a1dda3291cb]
• StateSession.removeNodes() / removeEdges() therefore call the trie with no route key. [cite: src/domain/orset/session/StateSession.ts#121-128@393f0ed9da8e124763aef5931b2f0a1dda3291cb]
• TrieCursor.remove() starts at the root and recursively tombstones below it. [cite: src/domain/orset/trie/TrieCursor.ts#120-129@393f0ed9da8e124763aef5931b2f0a1dda3291cb]

A page-backed reducer that retains this API would still perform O(trie) reads for every removal. The session API should accept (element, observedDots) and route directly to the target leaf; join/compaction paths that truly need global scans must remain explicit operations. The warm-work benchmark should include at least one removal and assert bounded page opens.