@git-stunts/git-warp 12.2.0 → 12.3.0

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/defaultClock.js

@@ -13,6 +13,7 @@ const defaultClock = {
     return performance.now();
   },
   timestamp() {
+    // eslint-disable-next-line no-restricted-syntax -- ClockPort implementation
     return new Date().toISOString();
   },
 };

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

@@ -15,6 +15,7 @@
  */
 
 import defaultCodec from '../utils/defaultCodec.js';
+import nullLogger from '../utils/nullLogger.js';
 import { validateWriterId, buildWriterRef } from '../utils/RefLayout.js';
 import { PatchSession } from './PatchSession.js';
 import { PatchBuilderV2 } from '../services/PatchBuilderV2.js';
@@ -44,8 +45,9 @@ export class Writer {
    * @param {(result: {patch: Object, sha: string}) => void | Promise<void>} [options.onCommitSuccess] - Callback invoked after successful commit with { patch, sha }
    * @param {'reject'|'cascade'|'warn'} [options.onDeleteWithData='warn'] - Policy when deleting a node with attached data
    * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for CBOR serialization (defaults to domain-local codec)
+   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger port
    */
-  constructor({ persistence, graphName, writerId, versionVector, getCurrentState, onCommitSuccess, onDeleteWithData = 'warn', codec }) {
+  constructor({ persistence, graphName, writerId, versionVector, getCurrentState, onCommitSuccess, onDeleteWithData = 'warn', codec, logger }) {
     validateWriterId(writerId);
 
     /** @type {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default} */
@@ -72,6 +74,9 @@ export class Writer {
     /** @type {import('../../ports/CodecPort.js').default|undefined} */
     this._codec = codec || defaultCodec;
 
+    /** @type {import('../../ports/LoggerPort.js').default} */
+    this._logger = logger || nullLogger;
+
     /** @type {boolean} */
     this._commitInProgress = false;
   }
@@ -151,6 +156,7 @@ export class Writer {
       onCommitSuccess: this._onCommitSuccess,
       onDeleteWithData: this._onDeleteWithData,
       codec: this._codec,
+      logger: this._logger,
     });
 
     // Return PatchSession wrapping the builder
@@ -186,6 +192,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

@@ -167,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;
   }
 }
 
@@ -188,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) {
@@ -228,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() {
@@ -312,6 +340,7 @@ export function _maybeRunGC(state) {
       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)',

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

@@ -104,7 +104,7 @@ export async function fork({ from, at, forkName, forkWriterId }) {
 
     // 4. Generate or validate fork name (add random suffix to prevent collisions)
     const resolvedForkName =
-      forkName ?? `${this._graphName}-fork-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+      forkName ?? `${this._graphName}-fork-${Math.random().toString(36).slice(2, 10).padEnd(8, '0')}`;
     try {
       validateGraphName(resolvedForkName);
     } catch (err) {

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;
@@ -245,7 +277,14 @@ export async function _materializeGraph() {
   if (!this._stateDirty && this._materializedGraph) {
     return this._materializedGraph;
   }
-  const state = await this.materialize();
+  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));
   }

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

@@ -22,15 +22,40 @@ import BitmapNeighborProvider from '../services/BitmapNeighborProvider.js';
 
 /** @typedef {import('../types/WarpPersistence.js').CorePersistence} CorePersistence */
 /** @typedef {import('../services/JoinReducer.js').WarpStateV5} WarpStateV5 */
+/** @typedef {import('../types/TickReceipt.js').TickReceipt} TickReceipt */
 
 /**
  * @typedef {{ outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>> }} AdjacencyMap
- * @typedef {{ state: WarpStateV5, stateHash: string, adjacency: AdjacencyMap }} MaterializedResult
+ * @typedef {{ state: WarpStateV5, stateHash: string|null, adjacency: AdjacencyMap }} MaterializedResult
  */
 
 import { buildWriterRef } from '../utils/RefLayout.js';
 import { decodePatchMessage, detectMessageKind } from '../services/WarpMessageCodec.js';
 
+/**
+ * Creates a shallow-frozen public view of materialized state.
+ *
+ * @param {WarpStateV5} state
+ * @returns {WarpStateV5}
+ */
+function freezePublicState(state) {
+  return Object.freeze({ ...state });
+}
+
+/**
+ * Creates a shallow-frozen public materialization result with receipts.
+ *
+ * @param {WarpStateV5} state
+ * @param {TickReceipt[]} receipts
+ * @returns {{state: WarpStateV5, receipts: TickReceipt[]}}
+ */
+function freezePublicStateWithReceipts(state, receipts) {
+  return Object.freeze({
+    state: freezePublicState(state),
+    receipts,
+  });
+}
+
 /**
  * Resolves the effective ceiling from options and instance state.
  *
@@ -107,11 +132,23 @@ export function _buildAdjacency(state) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {import('../services/JoinReducer.js').WarpStateV5} state
- * @param {import('../types/PatchDiff.js').PatchDiff} [diff] - Optional diff for incremental index
+ * @param {import('../types/PatchDiff.js').PatchDiff|{diff?: import('../types/PatchDiff.js').PatchDiff|null}} [optionsOrDiff]
+ *   Either a PatchDiff (legacy positional form) or options object.
  * @returns {Promise<MaterializedResult>}
  * @private
  */
-export async function _setMaterializedState(state, diff) {
+export async function _setMaterializedState(state, optionsOrDiff) {
+  /** @type {import('../types/PatchDiff.js').PatchDiff|undefined} */
+  let diff;
+  if (
+    optionsOrDiff &&
+    typeof optionsOrDiff === 'object' &&
+    Object.prototype.hasOwnProperty.call(optionsOrDiff, 'diff')
+  ) {
+    diff = /** @type {{diff?: import('../types/PatchDiff.js').PatchDiff|null}} */ (optionsOrDiff).diff ?? undefined;
+  } else {
+    diff = /** @type {import('../types/PatchDiff.js').PatchDiff|undefined} */ (optionsOrDiff ?? undefined);
+  }
   this._cachedState = state;
   this._stateDirty = false;
   this._versionVector = vvClone(state.observedFrontier);
@@ -222,7 +259,7 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
     cf.size === frontier.size &&
     [...frontier].every(([w, sha]) => cf.get(w) === sha)
   ) {
-    return this._cachedState;
+    return freezePublicState(this._cachedState);
   }
 
   const writerIds = [...frontier.keys()];
@@ -236,9 +273,9 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
     this._cachedFrontier = frontier;
     this._logTiming('materialize', t0, { metrics: '0 patches (ceiling)' });
     if (collectReceipts) {
-      return { state, receipts: [] };
+      return freezePublicStateWithReceipts(state, []);
     }
-    return state;
+    return freezePublicState(state);
   }
 
   // Persistent cache check — skip when collectReceipts is requested
@@ -259,7 +296,7 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
             await this._restoreIndexFromCache(cached.indexTreeOid);
           }
           this._logTiming('materialize', t0, { metrics: `cache hit (ceiling=${ceiling})` });
-          return state;
+          return freezePublicState(state);
         } catch {
           // Corrupted payload — self-heal by removing the bad entry
           try { await this._seekCache.delete(cacheKey); } catch { /* best-effort */ }
@@ -322,9 +359,12 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
   this._logTiming('materialize', t0, { metrics: `${allPatches.length} patches (ceiling=${ceiling})` });
 
   if (collectReceipts) {
-    return { state, receipts: /** @type {import('../types/TickReceipt.js').TickReceipt[]} */ (receipts) };
+    return freezePublicStateWithReceipts(
+      state,
+      /** @type {TickReceipt[]} */ (receipts),
+    );
   }
-  return state;
+  return freezePublicState(state);
 }
 
 /**
@@ -459,7 +499,7 @@ export async function materializeAt(checkpointSha) {
     codec: this._codec,
   });
   await this._setMaterializedState(state);
-  return state;
+  return freezePublicState(state);
 }
 
 /**