@git-stunts/git-warp 12.1.0 → 12.2.1

package/src/domain/utils/CachedValue.js

@@ -54,6 +54,12 @@ class CachedValue {
     /** @type {T|null} */
     this._value = null;
 
+    /** @type {Promise<T>|null} */
+    this._inflight = null;
+
+    /** @type {number} */
+    this._generation = 0;
+
     /** @type {number} */
     this._cachedAt = 0;
 
@@ -71,12 +77,33 @@ class CachedValue {
       return /** @type {T} */ (this._value);
     }
 
-    const value = await this._compute();
-    this._value = value;
-    this._cachedAt = this._clock.now();
-    this._cachedAtIso = this._clock.timestamp();
+    if (this._inflight) {
+      return await this._inflight;
+    }
 
-    return value;
+    const generation = this._generation;
+
+    this._inflight = Promise.resolve(this._compute()).then(
+      (value) => {
+        // Ignore stale in-flight completion if cache was invalidated mid-flight.
+        if (generation !== this._generation) {
+          return value;
+        }
+        this._value = value;
+        this._cachedAt = this._clock.now();
+        this._cachedAtIso = this._clock.timestamp();
+        this._inflight = null;
+        return value;
+      },
+      (err) => {
+        if (generation === this._generation) {
+          this._inflight = null;
+        }
+        throw err;
+      },
+    );
+
+    return await this._inflight;
   }
 
   /**
@@ -99,7 +126,9 @@ class CachedValue {
    * Invalidates the cached value, forcing recomputation on next get().
    */
   invalidate() {
+    this._generation += 1;
     this._value = null;
+    this._inflight = null;
     this._cachedAt = 0;
     this._cachedAtIso = null;
   }

package/src/domain/utils/EventId.js

@@ -49,6 +49,9 @@ export function createEventId(lamport, writerId, patchSha, opIndex) {
  * Compares two EventIds lexicographically.
  * Order: lamport -> writerId -> patchSha -> opIndex
  *
+ * SHA tiebreaker uses lexicographic string comparison. This is arbitrary but
+ * deterministic — the specific order doesn't matter as long as all writers agree.
+ *
  * @param {EventId} a
  * @param {EventId} b
  * @returns {number} -1 if a < b, 0 if equal, 1 if a > b
@@ -64,7 +67,7 @@ export function compareEventIds(a, b) {
     return a.writerId < b.writerId ? -1 : 1;
   }
 
-  // 3. Compare patchSha as string
+  // 3. Compare patchSha as string (lexicographic — arbitrary but deterministic)
   if (a.patchSha !== b.patchSha) {
     return a.patchSha < b.patchSha ? -1 : 1;
   }

package/src/domain/utils/LRUCache.js

@@ -34,7 +34,9 @@ class LRUCache {
     if (!this._cache.has(key)) {
       return undefined;
     }
-    // Move to end (most recently used) by deleting and re-inserting
+    // Delete-reinsert maintains insertion order in the underlying Map, which
+    // serves as the LRU eviction order. This is O(1) amortized in V8's Map
+    // implementation despite appearing wasteful (2x Map ops per get).
     const value = /** @type {V} */ (this._cache.get(key));
     this._cache.delete(key);
     this._cache.set(key, value);

package/src/domain/utils/RefLayout.js

@@ -376,6 +376,10 @@ export function buildTrustRecordRef(graphName) {
 /**
  * Parses and extracts the writer ID from a writer ref path.
  *
+ * Returns null for any non-writer ref, including malformed refs. Callers that
+ * need to distinguish "not a writer ref" from "malformed ref" should validate
+ * the ref format separately before calling this method.
+ *
  * @param {string} refPath - The full ref path
  * @returns {string|null} The writer ID, or null if the path is not a valid writer ref
  *

package/src/domain/utils/canonicalStringify.js

@@ -7,10 +7,24 @@
  * - Array elements that are undefined/function/symbol become "null"
  * - Object properties with undefined/function/symbol values are omitted
  *
+ * Throws TypeError on circular references rather than stack-overflowing.
+ *
  * @param {unknown} value - Any JSON-serializable value
  * @returns {string} Canonical JSON string with sorted keys
  */
 export function canonicalStringify(value) {
+  return _canonicalStringify(value, new WeakSet());
+}
+
+/**
+ * Internal recursive helper with cycle detection.
+ *
+ * @param {unknown} value - Any JSON-serializable value
+ * @param {WeakSet<object>} seen - Set of already-visited objects for cycle detection
+ * @returns {string} Canonical JSON string with sorted keys
+ * @private
+ */
+function _canonicalStringify(value, seen) {
   if (value === undefined) {
     return 'null';
   }
@@ -18,26 +32,42 @@ export function canonicalStringify(value) {
     return 'null';
   }
   if (Array.isArray(value)) {
-    // Map elements: undefined/function/symbol -> "null", others recurse
-    const elements = value.map(el => {
-      if (el === undefined || typeof el === 'function' || typeof el === 'symbol') {
-        return 'null';
-      }
-      return canonicalStringify(el);
-    });
-    return `[${elements.join(',')}]`;
+    if (seen.has(value)) {
+      throw new TypeError('Circular reference detected in canonicalStringify');
+    }
+    seen.add(value);
+    try {
+      // Map elements: undefined/function/symbol -> "null", others recurse
+      const elements = value.map(el => {
+        if (el === undefined || typeof el === 'function' || typeof el === 'symbol') {
+          return 'null';
+        }
+        return _canonicalStringify(el, seen);
+      });
+      return `[${elements.join(',')}]`;
+    } finally {
+      seen.delete(value);
+    }
   }
   if (typeof value === 'object') {
-    const obj = /** @type {Record<string, unknown>} */ (value);
-    // Filter out keys with undefined/function/symbol values, then sort
-    const keys = Object.keys(obj)
-      .filter(k => {
-        const v = obj[k];
-        return v !== undefined && typeof v !== 'function' && typeof v !== 'symbol';
-      })
-      .sort();
-    const pairs = keys.map(k => `${JSON.stringify(k)}:${canonicalStringify(obj[k])}`);
-    return `{${pairs.join(',')}}`;
+    if (seen.has(value)) {
+      throw new TypeError('Circular reference detected in canonicalStringify');
+    }
+    seen.add(value);
+    try {
+      const obj = /** @type {Record<string, unknown>} */ (value);
+      // Filter out keys with undefined/function/symbol values, then sort
+      const keys = Object.keys(obj)
+        .filter(k => {
+          const v = obj[k];
+          return v !== undefined && typeof v !== 'function' && typeof v !== 'symbol';
+        })
+        .sort();
+      const pairs = keys.map(k => `${JSON.stringify(k)}:${_canonicalStringify(obj[k], seen)}`);
+      return `{${pairs.join(',')}}`;
+    } finally {
+      seen.delete(value);
+    }
   }
   return JSON.stringify(value);
 }

package/src/domain/utils/matchGlob.js

@@ -46,6 +46,13 @@ export function matchGlob(pattern, str) {
   if (!regex) {
     regex = new RegExp(`^${escapeRegex(pattern).replace(/\\\*/g, '.*')}$`);
     globRegexCache.set(pattern, regex);
+    // Prevent unbounded cache growth. 1000 entries is generous for typical
+    // usage; a full clear is simpler and cheaper than LRU for a regex cache.
+    // Evict after insert so the just-compiled regex survives the clear.
+    if (globRegexCache.size >= 1000) {
+      globRegexCache.clear();
+      globRegexCache.set(pattern, regex);
+    }
   }
   return regex.test(str);
 }

package/src/domain/warp/PatchSession.js

@@ -9,8 +9,8 @@
  * @see WARP Writer Spec v1
  */
 
-import { buildWriterRef } from '../utils/RefLayout.js';
 import WriterError from '../errors/WriterError.js';
+import { buildWriterRef } from '../utils/RefLayout.js';
 
 /**
  * Fluent patch session for building and committing graph mutations.
@@ -60,7 +60,7 @@ export class PatchSession {
    *
    * @param {string} nodeId - The node ID to add
    * @returns {this} This session for chaining
-   * @throws {Error} If this session has already been committed
+   * @throws {WriterError} SESSION_COMMITTED if already committed
    */
   addNode(nodeId) {
     this._ensureNotCommitted();
@@ -75,7 +75,7 @@ export class PatchSession {
    *
    * @param {string} nodeId - The node ID to remove
    * @returns {this} This session for chaining
-   * @throws {Error} If this session has already been committed
+   * @throws {WriterError} SESSION_COMMITTED if already committed
    */
   removeNode(nodeId) {
     this._ensureNotCommitted();
@@ -90,7 +90,7 @@ export class PatchSession {
    * @param {string} to - Target node ID
    * @param {string} label - Edge label/type
    * @returns {this} This session for chaining
-   * @throws {Error} If this session has already been committed
+   * @throws {WriterError} SESSION_COMMITTED if already committed
    */
   addEdge(from, to, label) {
     this._ensureNotCommitted();
@@ -107,7 +107,7 @@ export class PatchSession {
    * @param {string} to - Target node ID
    * @param {string} label - Edge label/type
    * @returns {this} This session for chaining
-   * @throws {Error} If this session has already been committed
+   * @throws {WriterError} SESSION_COMMITTED if already committed
    */
   removeEdge(from, to, label) {
     this._ensureNotCommitted();
@@ -122,7 +122,7 @@ export class PatchSession {
    * @param {string} key - Property key
    * @param {unknown} value - Property value (must be JSON-serializable)
    * @returns {this} This session for chaining
-   * @throws {Error} If this session has already been committed
+   * @throws {WriterError} SESSION_COMMITTED if already committed
    */
   setProperty(nodeId, key, value) {
     this._ensureNotCommitted();
@@ -139,7 +139,7 @@ export class PatchSession {
    * @param {string} key - Property key
    * @param {unknown} value - Property value (must be JSON-serializable)
    * @returns {this} This session for chaining
-   * @throws {Error} If this session has already been committed
+   * @throws {WriterError} SESSION_COMMITTED if already committed
    */
   // eslint-disable-next-line max-params -- direct delegate matching PatchBuilderV2 signature
   setEdgeProperty(from, to, label, key, value) {
@@ -154,7 +154,7 @@ export class PatchSession {
    * @param {string} nodeId - The node ID to attach content to
    * @param {Buffer|string} content - The content to attach
    * @returns {Promise<this>} This session for chaining
-   * @throws {Error} If this session has already been committed
+   * @throws {WriterError} SESSION_COMMITTED if already committed
    */
   async attachContent(nodeId, content) {
     this._ensureNotCommitted();
@@ -170,7 +170,7 @@ export class PatchSession {
    * @param {string} label - Edge label/type
    * @param {Buffer|string} content - The content to attach
    * @returns {Promise<this>} This session for chaining
-   * @throws {Error} If this session has already been committed
+   * @throws {WriterError} SESSION_COMMITTED if already committed
    */
   // eslint-disable-next-line max-params -- direct delegate matching PatchBuilderV2 signature
   async attachEdgeContent(from, to, label, content) {
@@ -199,6 +199,7 @@ export class PatchSession {
    * @example
    * const sha = await patch.commit();
    */
+  // eslint-disable-next-line complexity -- maps multiple commit-failure modes into stable WriterError codes
   async commit() {
     this._ensureNotCommitted();
 
@@ -207,19 +208,6 @@ export class PatchSession {
       throw new WriterError('EMPTY_PATCH', 'Cannot commit empty patch: no operations added');
     }
 
-    const writerRef = buildWriterRef(this._graphName, this._writerId);
-
-    // Pre-commit CAS check: verify ref hasn't moved
-    const currentHead = await this._persistence.readRef(writerRef);
-    if (currentHead !== this._expectedOldHead) {
-      throw new WriterError(
-        'WRITER_REF_ADVANCED',
-        `Writer ref ${writerRef} has advanced since beginPatch(). ` +
-        `Expected ${this._expectedOldHead || '(none)'}, found ${currentHead || '(none)'}. ` +
-        `Call beginPatch() again to retry.`
-      );
-    }
-
     try {
       // Delegate to PatchBuilderV2.commit() which handles the git operations
       const sha = await this._builder.commit();
@@ -228,6 +216,21 @@ export class PatchSession {
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
       const cause = err instanceof Error ? err : undefined;
+      const casError = /** @type {{code?: unknown, expectedSha?: unknown, actualSha?: unknown}|null} */ (
+        (err && typeof err === 'object') ? err : null
+      );
+      if (casError?.code === 'WRITER_CAS_CONFLICT') {
+        const writerRef = buildWriterRef(this._graphName, this._writerId);
+        const expectedSha = typeof casError.expectedSha === 'string' ? casError.expectedSha : this._expectedOldHead;
+        const actualSha = typeof casError.actualSha === 'string' ? casError.actualSha : null;
+        throw new WriterError(
+          'WRITER_REF_ADVANCED',
+          `Writer ref ${writerRef} has advanced since beginPatch(). ` +
+          `Expected ${expectedSha || '(none)'}, found ${actualSha || '(none)'}. ` +
+          'Call beginPatch() again to retry.',
+          cause
+        );
+      }
       if (errMsg.includes('Concurrent commit detected') ||
           errMsg.includes('has advanced')) {
         throw new WriterError('WRITER_REF_ADVANCED', errMsg, cause);
@@ -246,12 +249,15 @@ export class PatchSession {
 
   /**
    * Ensures the session hasn't been committed yet.
-   * @throws {Error} If already committed
+   * @throws {WriterError} SESSION_COMMITTED if already committed
    * @private
    */
   _ensureNotCommitted() {
     if (this._committed) {
-      throw new Error('PatchSession already committed. Call beginPatch() to create a new session.');
+      throw new WriterError(
+        'SESSION_COMMITTED',
+        'PatchSession already committed. Call beginPatch() to create a new session.',
+      );
     }
   }
 }

package/src/domain/warp/Writer.js

@@ -128,12 +128,14 @@ export class Writer {
       const commitMessage = await this._persistence.showNode(expectedOldHead);
       const kind = detectMessageKind(commitMessage);
       if (kind === 'patch') {
-        try {
-          const patchInfo = decodePatchMessage(commitMessage);
-          lamport = patchInfo.lamport + 1;
-        } catch {
-          // Malformed message, start at 1
+        const patchInfo = decodePatchMessage(commitMessage);
+        if (typeof patchInfo.lamport !== 'number' || !Number.isFinite(patchInfo.lamport) || patchInfo.lamport < 1) {
+          throw new WriterError(
+            'E_LAMPORT_CORRUPT',
+            `Malformed Lamport timestamp in commit ${expectedOldHead}: ${JSON.stringify(patchInfo.lamport)}`,
+          );
         }
+        lamport = patchInfo.lamport + 1;
       }
     }
 
@@ -184,6 +186,11 @@ export class Writer {
         'commitPatch() is not reentrant. Use beginPatch() for nested or concurrent patches.',
       );
     }
+    // The `_commitInProgress` flag prevents concurrent commits from the same
+    // Writer instance. The finally block unconditionally resets it to ensure
+    // the writer remains usable after a failed commit. Error classification
+    // (CAS failure vs corruption vs I/O) is handled by the caller via the
+    // thrown error type.
     this._commitInProgress = true;
     try {
       const patch = await this.beginPatch();

package/src/domain/warp/_wiredMethods.d.ts

@@ -249,7 +249,7 @@ declare module '../WarpGraph.js' {
     _resolveCeiling(options?: { ceiling?: number | null }): number | null;
     _buildAdjacency(state: WarpStateV5): { outgoing: Map<string, Array<{ neighborId: string; label: string }>>; incoming: Map<string, Array<{ neighborId: string; label: string }>> };
     _buildView(state: WarpStateV5, stateHash: string, diff?: import('../types/PatchDiff.js').PatchDiff): void;
-    _setMaterializedState(state: WarpStateV5, diff?: import('../types/PatchDiff.js').PatchDiff): Promise<{ state: WarpStateV5; stateHash: string; adjacency: unknown }>;
+    _setMaterializedState(state: WarpStateV5, optionsOrDiff?: import('../types/PatchDiff.js').PatchDiff | { diff?: import('../types/PatchDiff.js').PatchDiff | null }): Promise<{ state: WarpStateV5; stateHash: string; adjacency: unknown }>;
     _materializeWithCeiling(ceiling: number, collectReceipts: boolean, t0: number): Promise<WarpStateV5 | { state: WarpStateV5; receipts: TickReceipt[] }>;
     _persistSeekCacheEntry(cacheKey: string, buf: Buffer, state: WarpStateV5): Promise<void>;
     _restoreIndexFromCache(indexTreeOid: string): Promise<void>;

package/src/domain/warp/checkpoint.methods.js

@@ -9,12 +9,13 @@
 
 import { QueryError, E_NO_STATE_MSG } from './_internal.js';
 import { buildWriterRef, buildCheckpointRef, buildCoverageRef } from '../utils/RefLayout.js';
-import { createFrontier, updateFrontier } from '../services/Frontier.js';
+import { createFrontier, updateFrontier, frontierFingerprint } from '../services/Frontier.js';
 import { loadCheckpoint, create as createCheckpointCommit } from '../services/CheckpointService.js';
 import { decodePatchMessage, detectMessageKind, encodeAnchorMessage } from '../services/WarpMessageCodec.js';
 import { shouldRunGC, executeGC } from '../services/GCPolicy.js';
 import { collectGCMetrics } from '../services/GCMetrics.js';
 import { computeAppliedVV } from '../services/CheckpointSerializerV5.js';
+import { cloneStateV5 } from '../services/JoinReducer.js';
 
 /** @typedef {import('../types/WarpPersistence.js').CorePersistence} CorePersistence */
 
@@ -166,8 +167,28 @@ export async function _loadLatestCheckpoint() {
 
   try {
     return await loadCheckpoint(this._persistence, checkpointSha, { codec: this._codec });
-  } catch {
-    return null;
+  } catch (err) {
+    // "Not found" conditions (missing tree entries, missing blobs) are expected
+    // when a checkpoint ref exists but the objects have been pruned or are
+    // unreachable. In that case, fall back to full replay by returning null.
+    // Decode/corruption errors (e.g., CBOR parse failure, schema mismatch)
+    // should propagate so callers see the real problem.
+    // These string-contains checks match specific error messages from the
+    // persistence layer and codec:
+    //   "missing"          — git cat-file on pruned/unreachable objects
+    //   "not found"        — readTree entry lookup failures
+    //   "ENOENT"           — filesystem-level missing path (bare repo edge case)
+    //   "non-empty string" — readRef/getNodeInfo called with empty/null SHA
+    const msg = err instanceof Error ? err.message : '';
+    if (
+      msg.includes('missing') ||
+      msg.includes('not found') ||
+      msg.includes('ENOENT') ||
+      msg.includes('non-empty string')
+    ) {
+      return null;
+    }
+    throw err;
   }
 }
 
@@ -187,9 +208,11 @@ export async function _loadPatchesSince(checkpoint) {
     const checkpointSha = checkpoint.frontier?.get(writerId) || null;
     const patches = await this._loadWriterPatches(writerId, checkpointSha);
 
-    // Validate each patch against checkpoint frontier
-    for (const { sha } of patches) {
-      await this._validatePatchAgainstCheckpoint(writerId, sha, checkpoint);
+    // Validate ancestry once at the writer tip; chain-order patches are then
+    // transitively valid between checkpointSha and tipSha.
+    if (patches.length > 0) {
+      const tipSha = patches[patches.length - 1].sha;
+      await this._validatePatchAgainstCheckpoint(writerId, tipSha, checkpoint);
     }
 
     for (const p of patches) {
@@ -227,10 +250,16 @@ export async function _validateMigrationBoundary() {
 }
 
 /**
- * Checks if there are any schema:1 patches in the graph.
+ * Checks whether any writer tip contains a schema:1 patch.
+ *
+ * **Heuristic only** — inspects the most recent patch per writer (the tip),
+ * not the full history chain. Older schema:1 patches buried deeper in a
+ * writer's chain will NOT be detected. This is acceptable because migration
+ * typically writes a new tip, so a schema:2+ tip implies the writer has
+ * been migrated.
  *
  * @this {import('../WarpGraph.js').default}
- * @returns {Promise<boolean>} True if schema:1 patches exist
+ * @returns {Promise<boolean>} True if any writer tip is schema:1 (or omits `schema`, treated as legacy v1)
  * @private
  */
 export async function _hasSchema1Patches() {
@@ -267,6 +296,12 @@ export async function _hasSchema1Patches() {
  * Post-materialize GC check. Warn by default; execute only when enabled.
  * GC failure never breaks materialize.
  *
+ * Uses clone-then-swap pattern for snapshot isolation (B63):
+ * 1. Snapshot frontier fingerprint before GC
+ * 2. Clone state, run executeGC on clone
+ * 3. Compare frontier after GC — if changed, discard clone + mark dirty
+ * 4. If unchanged, swap compacted clone into _cachedState
+ *
  * @this {import('../WarpGraph.js').default}
  * @param {import('../services/JoinReducer.js').WarpStateV5} state
  * @private
@@ -287,8 +322,36 @@ export function _maybeRunGC(state) {
     }
 
     if (/** @type {import('../services/GCPolicy.js').GCPolicy} */ (this._gcPolicy).enabled) {
-      const appliedVV = computeAppliedVV(state);
-      const result = executeGC(state, appliedVV);
+      // Snapshot frontier before GC
+      const preGcFingerprint = this._lastFrontier
+        ? frontierFingerprint(this._lastFrontier)
+        : null;
+
+      // Clone state so executeGC doesn't mutate live state
+      const clonedState = cloneStateV5(state);
+      const appliedVV = computeAppliedVV(clonedState);
+      const result = executeGC(clonedState, appliedVV);
+
+      // Check if frontier changed during GC (concurrent write)
+      const postGcFingerprint = this._lastFrontier
+        ? frontierFingerprint(this._lastFrontier)
+        : null;
+
+      if (preGcFingerprint !== postGcFingerprint) {
+        // Frontier changed — discard compacted state, mark dirty
+        this._stateDirty = true;
+        this._cachedViewHash = null;
+        if (this._logger) {
+          this._logger.warn(
+            'Auto-GC discarded: frontier changed during compaction (concurrent write)',
+            { reasons, preGcFingerprint, postGcFingerprint },
+          );
+        }
+        return;
+      }
+
+      // Frontier unchanged — swap in compacted state
+      this._cachedState = clonedState;
       this._lastGCTime = this._clock.now();
       this._patchesSinceGC = 0;
       if (this._logger) {
@@ -348,11 +411,17 @@ export function maybeRunGC() {
  * Explicitly runs GC on the cached state.
  * Compacts tombstoned dots that are covered by the appliedVV.
  *
+ * Uses clone-then-swap pattern for snapshot isolation (B63):
+ * clones state, runs executeGC on clone, verifies frontier unchanged,
+ * then swaps in compacted clone. If frontier changed during GC,
+ * throws E_GC_STALE so the caller can retry after re-materializing.
+ *
  * **Requires a cached state.**
  *
  * @this {import('../WarpGraph.js').default}
  * @returns {{nodesCompacted: number, edgesCompacted: number, tombstonesRemoved: number, durationMs: number}}
  * @throws {QueryError} If no cached state exists (code: `E_NO_STATE`)
+ * @throws {QueryError} If frontier changed during GC (code: `E_GC_STALE`)
  *
  * @example
  * await graph.materialize();
@@ -368,13 +437,30 @@ export function runGC() {
       });
     }
 
-    // Compute appliedVV from current state
-    const appliedVV = computeAppliedVV(this._cachedState);
-
-    // Execute GC (mutates cached state)
-    const result = executeGC(this._cachedState, appliedVV);
+    // Snapshot frontier before GC
+    const preGcFingerprint = this._lastFrontier
+      ? frontierFingerprint(this._lastFrontier)
+      : null;
+
+    // Clone state so executeGC doesn't mutate live state until verified
+    const clonedState = cloneStateV5(this._cachedState);
+    const appliedVV = computeAppliedVV(clonedState);
+    const result = executeGC(clonedState, appliedVV);
+
+    // Verify frontier unchanged (concurrent write detection)
+    const postGcFingerprint = this._lastFrontier
+      ? frontierFingerprint(this._lastFrontier)
+      : null;
+
+    if (preGcFingerprint !== postGcFingerprint) {
+      throw new QueryError(
+        'GC aborted: frontier changed during compaction (concurrent write detected)',
+        { code: 'E_GC_STALE' },
+      );
+    }
 
-    // Update GC tracking
+    // Frontier unchanged — swap in compacted state
+    this._cachedState = clonedState;
     this._lastGCTime = this._clock.now();
     this._patchesSinceGC = 0;
 

package/src/domain/warp/materialize.methods.js

@@ -51,6 +51,30 @@ function scanPatchesForMaxLamport(graph, patches) {
   }
 }
 
+/**
+ * Creates a shallow-frozen public view of materialized state.
+ *
+ * @param {import('../services/JoinReducer.js').WarpStateV5} state
+ * @returns {import('../services/JoinReducer.js').WarpStateV5}
+ */
+function freezePublicState(state) {
+  return Object.freeze({ ...state });
+}
+
+/**
+ * Creates a shallow-frozen public result for receipt-enabled materialization.
+ *
+ * @param {import('../services/JoinReducer.js').WarpStateV5} state
+ * @param {import('../types/TickReceipt.js').TickReceipt[]} receipts
+ * @returns {{state: import('../services/JoinReducer.js').WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}}
+ */
+function freezePublicStateWithReceipts(state, receipts) {
+  return Object.freeze({
+    state: freezePublicState(state),
+    receipts,
+  });
+}
+
 
 /**
  * Materializes the current graph state.
@@ -90,7 +114,12 @@ export async function materialize(options) {
   try {
     // When ceiling is active, delegate to ceiling-aware path (with its own cache)
     if (ceiling !== null) {
-      return await this._materializeWithCeiling(ceiling, !!collectReceipts, t0);
+      const result = await this._materializeWithCeiling(ceiling, !!collectReceipts, t0);
+      if (collectReceipts) {
+        const withReceipts = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}} */ (result);
+        return freezePublicStateWithReceipts(withReceipts.state, withReceipts.receipts);
+      }
+      return freezePublicState(/** @type {import('../services/JoinReducer.js').WarpStateV5} */ (result));
     }
 
     // Check for checkpoint
@@ -190,7 +219,7 @@ export async function materialize(options) {
       }
     }
 
-    await this._setMaterializedState(state, diff);
+    await this._setMaterializedState(state, { diff });
     this._provenanceDegraded = false;
     this._cachedCeiling = null;
     this._cachedFrontier = null;
@@ -225,9 +254,12 @@ export async function materialize(options) {
     this._logTiming('materialize', t0, { metrics: `${patchCount} patches` });
 
     if (collectReceipts) {
-      return { state, receipts: /** @type {import('../types/TickReceipt.js').TickReceipt[]} */ (receipts) };
+      return freezePublicStateWithReceipts(
+        /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (state),
+        /** @type {import('../types/TickReceipt.js').TickReceipt[]} */ (receipts),
+      );
     }
-    return state;
+    return freezePublicState(/** @type {import('../services/JoinReducer.js').WarpStateV5} */ (state));
   } catch (err) {
     this._logTiming('materialize', t0, { error: /** @type {Error} */ (err) });
     throw err;
@@ -242,7 +274,17 @@ export async function materialize(options) {
  * @private
  */
 export async function _materializeGraph() {
-  const state = await this.materialize();
+  if (!this._stateDirty && this._materializedGraph) {
+    return this._materializedGraph;
+  }
+  const materialized = await this.materialize();
+  const state = this._stateDirty
+    ? /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (materialized)
+    : (this._cachedState
+      || /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (materialized));
+  if (!state) {
+    return /** @type {object} */ (this._materializedGraph);
+  }
   if (!this._materializedGraph || this._materializedGraph.state !== state) {
     await this._setMaterializedState(/** @type {import('../services/JoinReducer.js').WarpStateV5} */ (state));
   }