footprintjs 9.28.0 → 9.30.0

package/dist/esm/lib/memory/SharedMemory.js

@@ -5,15 +5,31 @@
  * - Each run gets its own namespace (runs/{id}/)
  * - Default values can be initialised and preserved
  * - Accepts commit bundles from TransactionBuffer
+ *
+ * COPY-ON-WRITE (9.29.0 — docs/design/2026-10-copy-on-write-commit.md):
+ * `context` is a GENERATION, and a generation is never edited. Every write —
+ * `applyPatch` (a stage commit), `setValue`, `updateValue` — builds the next
+ * generation by copying the root and the containers on each written path,
+ * shares every other subtree with the generation before it, and swaps. So a
+ * generation a stage captured (its first-touch view, its transaction
+ * buffer's diff base) stays exactly what it was, and a write costs O(what it
+ * wrote), not O(state).
  */
-import { mergeContextWins } from './pathOps.js';
-import { applySmartMerge, getNestedValue, getRunAndGlobalPaths, setNestedValue, updateNestedValue } from './utils.js';
+import { mergeContextWins, ownedRootOf, ownSpine } from './pathOps.js';
+import { getNestedValue, getRunAndGlobalPaths, nextGeneration, setNestedValue, updateNestedValue } from './utils.js';
 export class SharedMemory {
     context = {};
     _defaultValues;
     constructor(defaultValues, initialContext) {
         this._defaultValues = defaultValues;
-        this.context = mergeContextWins(initialContext || {}, defaultValues || {});
+        const seed = mergeContextWins(initialContext || {}, defaultValues || {});
+        // Detached ONCE, here: `mergeContextWins` copies only the top level, so
+        // the seed's nested values are the caller's own objects. Before 9.29.0
+        // the first commit's whole-state clone detached them (and until then a
+        // caller mutating its `initialContext` changed live state with no row);
+        // nothing re-clones the state any more, so the seed is detached at
+        // construction — one clone per runtime, not one per commit.
+        this.context = Object.keys(seed).length > 0 ? structuredClone(seed) : seed;
     }
     /** Gets a clone of the default values. */
     getDefaultValues() {
@@ -23,13 +39,28 @@ export class SharedMemory {
     getRuns() {
         return this.context.runs;
     }
-    /** Updates a value using merge semantics. */
+    /** Updates a value using merge semantics, as a new generation (path copy + swap). */
     updateValue(runId, path, key, value) {
-        updateNestedValue(this.context, runId, path, key, value, this.getDefaultValues());
+        const next = this.ownedPathTo(runId, path, key);
+        updateNestedValue(next, runId, path, key, value, this.getDefaultValues());
+        this.context = next;
     }
-    /** Sets a value using overwrite semantics. */
+    /** Sets a value using overwrite semantics, as a new generation (path copy + swap). */
     setValue(runId, path, key, value) {
-        setNestedValue(this.context, runId, path, key, value, this.getDefaultValues());
+        const next = this.ownedPathTo(runId, path, key);
+        setNestedValue(next, runId, path, key, value, this.getDefaultValues());
+        this.context = next;
+    }
+    /**
+     * A copy of the current generation's root whose containers on the way to
+     * `key` are owned — the in-place helpers above then edit only copies.
+     */
+    ownedPathTo(runId, path, key) {
+        const owned = new WeakSet();
+        const root = ownedRootOf(this.context, owned);
+        const { runPath, globalPath } = getRunAndGlobalPaths(runId, path);
+        ownSpine(root, [...(runPath || globalPath), key], owned);
+        return root;
     }
     /**
      * Reads a value from the store.
@@ -40,13 +71,13 @@ export class SharedMemory {
         const value = runPath ? getNestedValue(this.context, runPath, key) : undefined;
         return typeof value !== 'undefined' ? value : getNestedValue(this.context, globalPath, key);
     }
-    /** Gets the entire state as a JSON object. */
+    /** Gets the entire state as a JSON object — the current generation, by reference. Never mutate it. */
     getState() {
         return this.context;
     }
-    /** Applies a commit bundle from TransactionBuffer. */
+    /** Applies a commit bundle from TransactionBuffer: builds the next generation and swaps it in. */
     applyPatch(overwrite, updates, trace) {
-        this.context = applySmartMerge(this.context, updates, overwrite, trace);
+        this.context = nextGeneration(this.context, updates, overwrite, trace);
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU2hhcmVkTWVtb3J5LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL2xpYi9tZW1vcnkvU2hhcmVkTWVtb3J5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7O0dBT0c7QUFFSCxPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFFaEQsT0FBTyxFQUFFLGVBQWUsRUFBRSxjQUFjLEVBQUUsb0JBQW9CLEVBQUUsY0FBYyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sWUFBWSxDQUFDO0FBRXRILE1BQU0sT0FBTyxZQUFZO0lBQ2YsT0FBTyxHQUEyQixFQUFFLENBQUM7SUFDckMsY0FBYyxDQUFXO0lBRWpDLFlBQVksYUFBdUIsRUFBRSxjQUF3QjtRQUMzRCxJQUFJLENBQUMsY0FBYyxHQUFHLGFBQWEsQ0FBQztRQUNwQyxJQUFJLENBQUMsT0FBTyxHQUFHLGdCQUFnQixDQUFDLGNBQWMsSUFBSSxFQUFFLEVBQUUsYUFBYSxJQUFJLEVBQUUsQ0FBQyxDQUFDO0lBQzdFLENBQUM7SUFFRCwwQ0FBMEM7SUFDMUMsZ0JBQWdCO1FBQ2QsT0FBTyxJQUFJLENBQUMsY0FBYyxDQUFDLENBQUMsQ0FBQyxlQUFlLENBQUMsSUFBSSxDQUFDLGNBQWMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUM7SUFDaEYsQ0FBQztJQUVELCtCQUErQjtJQUMvQixPQUFPO1FBQ0wsT0FBTyxJQUFJLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQztJQUMzQixDQUFDO0lBRUQsNkNBQTZDO0lBQzdDLFdBQVcsQ0FBQyxLQUFhLEVBQUUsSUFBYyxFQUFFLEdBQVcsRUFBRSxLQUFjO1FBQ3BFLGlCQUFpQixDQUFDLElBQUksQ0FBQyxPQUFPLEVBQUUsS0FBSyxFQUFFLElBQUksRUFBRSxHQUFHLEVBQUUsS0FBSyxFQUFFLElBQUksQ0FBQyxnQkFBZ0IsRUFBRSxDQUFDLENBQUM7SUFDcEYsQ0FBQztJQUVELDhDQUE4QztJQUM5QyxRQUFRLENBQUMsS0FBYSxFQUFFLElBQWMsRUFBRSxHQUFXLEVBQUUsS0FBYztRQUNqRSxjQUFjLENBQUMsSUFBSSxDQUFDLE9BQU8sRUFBRSxLQUFLLEVBQUUsSUFBSSxFQUFFLEdBQUcsRUFBRSxLQUFLLEVBQUUsSUFBSSxDQUFDLGdCQUFnQixFQUFFLENBQUMsQ0FBQztJQUNqRixDQUFDO0lBRUQ7OztPQUdHO0lBQ0gsUUFBUSxDQUFDLEtBQWMsRUFBRSxJQUFlLEVBQUUsR0FBWTtRQUNwRCxNQUFNLEVBQUUsVUFBVSxFQUFFLE9BQU8sRUFBRSxHQUFHLG9CQUFvQixDQUFDLEtBQUssRUFBRSxJQUFJLENBQUMsQ0FBQztRQUNsRSxNQUFNLEtBQUssR0FBRyxPQUFPLENBQUMsQ0FBQyxDQUFDLGNBQWMsQ0FBQyxJQUFJLENBQUMsT0FBTyxFQUFFLE9BQU8sRUFBRSxHQUFHLENBQUMsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDO1FBQy9FLE9BQU8sT0FBTyxLQUFLLEtBQUssV0FBVyxDQUFDLENBQUMsQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLGNBQWMsQ0FBQyxJQUFJLENBQUMsT0FBTyxFQUFFLFVBQVUsRUFBRSxHQUFHLENBQUMsQ0FBQztJQUM5RixDQUFDO0lBRUQsOENBQThDO0lBQzlDLFFBQVE7UUFDTixPQUFPLElBQUksQ0FBQyxPQUFPLENBQUM7SUFDdEIsQ0FBQztJQUVELHNEQUFzRDtJQUN0RCxVQUFVLENBQUMsU0FBc0IsRUFBRSxPQUFvQixFQUFFLEtBQW1CO1FBQzFFLElBQUksQ0FBQyxPQUFPLEdBQUcsZUFBZSxDQUFDLElBQUksQ0FBQyxPQUFPLEVBQUUsT0FBTyxFQUFFLFNBQVMsRUFBRSxLQUFLLENBQUMsQ0FBQztJQUMxRSxDQUFDO0NBQ0YiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIFNoYXJlZE1lbW9yeSDigJQgVGhlIHNoYXJlZCBzdGF0ZSBjb250YWluZXIgZm9yIGFsbCBmbG93Y2hhcnQgZXhlY3V0aW9uXG4gKlxuICogTGlrZSBhIHJ1bnRpbWUgaGVhcCB3aXRoIG5hbWVzcGFjZSBpc29sYXRpb246XG4gKiAtIEVhY2ggcnVuIGdldHMgaXRzIG93biBuYW1lc3BhY2UgKHJ1bnMve2lkfS8pXG4gKiAtIERlZmF1bHQgdmFsdWVzIGNhbiBiZSBpbml0aWFsaXNlZCBhbmQgcHJlc2VydmVkXG4gKiAtIEFjY2VwdHMgY29tbWl0IGJ1bmRsZXMgZnJvbSBUcmFuc2FjdGlvbkJ1ZmZlclxuICovXG5cbmltcG9ydCB7IG1lcmdlQ29udGV4dFdpbnMgfSBmcm9tICcuL3BhdGhPcHMuanMnO1xuaW1wb3J0IHR5cGUgeyBNZW1vcnlQYXRjaCwgVHJhY2VFbnRyeSB9IGZyb20gJy4vdHlwZXMuanMnO1xuaW1wb3J0IHsgYXBwbHlTbWFydE1lcmdlLCBnZXROZXN0ZWRWYWx1ZSwgZ2V0UnVuQW5kR2xvYmFsUGF0aHMsIHNldE5lc3RlZFZhbHVlLCB1cGRhdGVOZXN0ZWRWYWx1ZSB9IGZyb20gJy4vdXRpbHMuanMnO1xuXG5leHBvcnQgY2xhc3MgU2hhcmVkTWVtb3J5IHtcbiAgcHJpdmF0ZSBjb250ZXh0OiB7IFtrZXk6IHN0cmluZ106IGFueSB9ID0ge307XG4gIHByaXZhdGUgX2RlZmF1bHRWYWx1ZXM/OiB1bmtub3duO1xuXG4gIGNvbnN0cnVjdG9yKGRlZmF1bHRWYWx1ZXM/OiB1bmtub3duLCBpbml0aWFsQ29udGV4dD86IHVua25vd24pIHtcbiAgICB0aGlzLl9kZWZhdWx0VmFsdWVzID0gZGVmYXVsdFZhbHVlcztcbiAgICB0aGlzLmNvbnRleHQgPSBtZXJnZUNvbnRleHRXaW5zKGluaXRpYWxDb250ZXh0IHx8IHt9LCBkZWZhdWx0VmFsdWVzIHx8IHt9KTtcbiAgfVxuXG4gIC8qKiBHZXRzIGEgY2xvbmUgb2YgdGhlIGRlZmF1bHQgdmFsdWVzLiAqL1xuICBnZXREZWZhdWx0VmFsdWVzKCkge1xuICAgIHJldHVybiB0aGlzLl9kZWZhdWx0VmFsdWVzID8gc3RydWN0dXJlZENsb25lKHRoaXMuX2RlZmF1bHRWYWx1ZXMpIDogdW5kZWZpbmVkO1xuICB9XG5cbiAgLyoqIEdldHMgYWxsIHJ1biBuYW1lc3BhY2VzLiAqL1xuICBnZXRSdW5zKCkge1xuICAgIHJldHVybiB0aGlzLmNvbnRleHQucnVucztcbiAgfVxuXG4gIC8qKiBVcGRhdGVzIGEgdmFsdWUgdXNpbmcgbWVyZ2Ugc2VtYW50aWNzLiAqL1xuICB1cGRhdGVWYWx1ZShydW5JZDogc3RyaW5nLCBwYXRoOiBzdHJpbmdbXSwga2V5OiBzdHJpbmcsIHZhbHVlOiB1bmtub3duKSB7XG4gICAgdXBkYXRlTmVzdGVkVmFsdWUodGhpcy5jb250ZXh0LCBydW5JZCwgcGF0aCwga2V5LCB2YWx1ZSwgdGhpcy5nZXREZWZhdWx0VmFsdWVzKCkpO1xuICB9XG5cbiAgLyoqIFNldHMgYSB2YWx1ZSB1c2luZyBvdmVyd3JpdGUgc2VtYW50aWNzLiAqL1xuICBzZXRWYWx1ZShydW5JZDogc3RyaW5nLCBwYXRoOiBzdHJpbmdbXSwga2V5OiBzdHJpbmcsIHZhbHVlOiB1bmtub3duKSB7XG4gICAgc2V0TmVzdGVkVmFsdWUodGhpcy5jb250ZXh0LCBydW5JZCwgcGF0aCwga2V5LCB2YWx1ZSwgdGhpcy5nZXREZWZhdWx0VmFsdWVzKCkpO1xuICB9XG5cbiAgLyoqXG4gICAqIFJlYWRzIGEgdmFsdWUgZnJvbSB0aGUgc3RvcmUuXG4gICAqIExvb2tzIHVwIGluIHJ1biBuYW1lc3BhY2UgZmlyc3QsIGZhbGxzIGJhY2sgdG8gZ2xvYmFsLlxuICAgKi9cbiAgZ2V0VmFsdWUocnVuSWQ/OiBzdHJpbmcsIHBhdGg/OiBzdHJpbmdbXSwga2V5Pzogc3RyaW5nKTogYW55IHtcbiAgICBjb25zdCB7IGdsb2JhbFBhdGgsIHJ1blBhdGggfSA9IGdldFJ1bkFuZEdsb2JhbFBhdGhzKHJ1bklkLCBwYXRoKTtcbiAgICBjb25zdCB2YWx1ZSA9IHJ1blBhdGggPyBnZXROZXN0ZWRWYWx1ZSh0aGlzLmNvbnRleHQsIHJ1blBhdGgsIGtleSkgOiB1bmRlZmluZWQ7XG4gICAgcmV0dXJuIHR5cGVvZiB2YWx1ZSAhPT0gJ3VuZGVmaW5lZCcgPyB2YWx1ZSA6IGdldE5lc3RlZFZhbHVlKHRoaXMuY29udGV4dCwgZ2xvYmFsUGF0aCwga2V5KTtcbiAgfVxuXG4gIC8qKiBHZXRzIHRoZSBlbnRpcmUgc3RhdGUgYXMgYSBKU09OIG9iamVjdC4gKi9cbiAgZ2V0U3RhdGUoKTogUmVjb3JkPHN0cmluZywgdW5rbm93bj4ge1xuICAgIHJldHVybiB0aGlzLmNvbnRleHQ7XG4gIH1cblxuICAvKiogQXBwbGllcyBhIGNvbW1pdCBidW5kbGUgZnJvbSBUcmFuc2FjdGlvbkJ1ZmZlci4gKi9cbiAgYXBwbHlQYXRjaChvdmVyd3JpdGU6IE1lbW9yeVBhdGNoLCB1cGRhdGVzOiBNZW1vcnlQYXRjaCwgdHJhY2U6IFRyYWNlRW50cnlbXSk6IHZvaWQge1xuICAgIHRoaXMuY29udGV4dCA9IGFwcGx5U21hcnRNZXJnZSh0aGlzLmNvbnRleHQsIHVwZGF0ZXMsIG92ZXJ3cml0ZSwgdHJhY2UpO1xuICB9XG59XG4iXX0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU2hhcmVkTWVtb3J5LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL2xpYi9tZW1vcnkvU2hhcmVkTWVtb3J5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7Ozs7O0dBZ0JHO0FBRUgsT0FBTyxFQUFFLGdCQUFnQixFQUFFLFdBQVcsRUFBRSxRQUFRLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFFdkUsT0FBTyxFQUFFLGNBQWMsRUFBRSxvQkFBb0IsRUFBRSxjQUFjLEVBQUUsY0FBYyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sWUFBWSxDQUFDO0FBRXJILE1BQU0sT0FBTyxZQUFZO0lBQ2YsT0FBTyxHQUEyQixFQUFFLENBQUM7SUFDckMsY0FBYyxDQUFXO0lBRWpDLFlBQVksYUFBdUIsRUFBRSxjQUF3QjtRQUMzRCxJQUFJLENBQUMsY0FBYyxHQUFHLGFBQWEsQ0FBQztRQUNwQyxNQUFNLElBQUksR0FBRyxnQkFBZ0IsQ0FBQyxjQUFjLElBQUksRUFBRSxFQUFFLGFBQWEsSUFBSSxFQUFFLENBQUMsQ0FBQztRQUN6RSx3RUFBd0U7UUFDeEUsdUVBQXVFO1FBQ3ZFLHVFQUF1RTtRQUN2RSx3RUFBd0U7UUFDeEUsbUVBQW1FO1FBQ25FLDREQUE0RDtRQUM1RCxJQUFJLENBQUMsT0FBTyxHQUFHLE1BQU0sQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLENBQUMsTUFBTSxHQUFHLENBQUMsQ0FBQyxDQUFDLENBQUMsZUFBZSxDQUFDLElBQUksQ0FBQyxDQUFDLENBQUMsQ0FBQyxJQUFJLENBQUM7SUFDN0UsQ0FBQztJQUVELDBDQUEwQztJQUMxQyxnQkFBZ0I7UUFDZCxPQUFPLElBQUksQ0FBQyxjQUFjLENBQUMsQ0FBQyxDQUFDLGVBQWUsQ0FBQyxJQUFJLENBQUMsY0FBYyxDQUFDLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQztJQUNoRixDQUFDO0lBRUQsK0JBQStCO0lBQy9CLE9BQU87UUFDTCxPQUFPLElBQUksQ0FBQyxPQUFPLENBQUMsSUFBSSxDQUFDO0lBQzNCLENBQUM7SUFFRCxxRkFBcUY7SUFDckYsV0FBVyxDQUFDLEtBQWEsRUFBRSxJQUFjLEVBQUUsR0FBVyxFQUFFLEtBQWM7UUFDcEUsTUFBTSxJQUFJLEdBQUcsSUFBSSxDQUFDLFdBQVcsQ0FBQyxLQUFLLEVBQUUsSUFBSSxFQUFFLEdBQUcsQ0FBQyxDQUFDO1FBQ2hELGlCQUFpQixDQUFDLElBQUksRUFBRSxLQUFLLEVBQUUsSUFBSSxFQUFFLEdBQUcsRUFBRSxLQUFLLEVBQUUsSUFBSSxDQUFDLGdCQUFnQixFQUFFLENBQUMsQ0FBQztRQUMxRSxJQUFJLENBQUMsT0FBTyxHQUFHLElBQUksQ0FBQztJQUN0QixDQUFDO0lBRUQsc0ZBQXNGO0lBQ3RGLFFBQVEsQ0FBQyxLQUFhLEVBQUUsSUFBYyxFQUFFLEdBQVcsRUFBRSxLQUFjO1FBQ2pFLE1BQU0sSUFBSSxHQUFHLElBQUksQ0FBQyxXQUFXLENBQUMsS0FBSyxFQUFFLElBQUksRUFBRSxHQUFHLENBQUMsQ0FBQztRQUNoRCxjQUFjLENBQUMsSUFBSSxFQUFFLEtBQUssRUFBRSxJQUFJLEVBQUUsR0FBRyxFQUFFLEtBQUssRUFBRSxJQUFJLENBQUMsZ0JBQWdCLEVBQUUsQ0FBQyxDQUFDO1FBQ3ZFLElBQUksQ0FBQyxPQUFPLEdBQUcsSUFBSSxDQUFDO0lBQ3RCLENBQUM7SUFFRDs7O09BR0c7SUFDSyxXQUFXLENBQUMsS0FBYSxFQUFFLElBQWMsRUFBRSxHQUFXO1FBQzVELE1BQU0sS0FBSyxHQUFHLElBQUksT0FBTyxFQUFVLENBQUM7UUFDcEMsTUFBTSxJQUFJLEdBQUcsV0FBVyxDQUFDLElBQUksQ0FBQyxPQUFPLEVBQUUsS0FBSyxDQUFDLENBQUM7UUFDOUMsTUFBTSxFQUFFLE9BQU8sRUFBRSxVQUFVLEVBQUUsR0FBRyxvQkFBb0IsQ0FBQyxLQUFLLEVBQUUsSUFBSSxDQUFDLENBQUM7UUFDbEUsUUFBUSxDQUFDLElBQUksRUFBRSxDQUFDLEdBQUcsQ0FBQyxPQUFPLElBQUksVUFBVSxDQUFDLEVBQUUsR0FBRyxDQUFDLEVBQUUsS0FBSyxDQUFDLENBQUM7UUFDekQsT0FBTyxJQUFJLENBQUM7SUFDZCxDQUFDO0lBRUQ7OztPQUdHO0lBQ0gsUUFBUSxDQUFDLEtBQWMsRUFBRSxJQUFlLEVBQUUsR0FBWTtRQUNwRCxNQUFNLEVBQUUsVUFBVSxFQUFFLE9BQU8sRUFBRSxHQUFHLG9CQUFvQixDQUFDLEtBQUssRUFBRSxJQUFJLENBQUMsQ0FBQztRQUNsRSxNQUFNLEtBQUssR0FBRyxPQUFPLENBQUMsQ0FBQyxDQUFDLGNBQWMsQ0FBQyxJQUFJLENBQUMsT0FBTyxFQUFFLE9BQU8sRUFBRSxHQUFHLENBQUMsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDO1FBQy9FLE9BQU8sT0FBTyxLQUFLLEtBQUssV0FBVyxDQUFDLENBQUMsQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLGNBQWMsQ0FBQyxJQUFJLENBQUMsT0FBTyxFQUFFLFVBQVUsRUFBRSxHQUFHLENBQUMsQ0FBQztJQUM5RixDQUFDO0lBRUQsc0dBQXNHO0lBQ3RHLFFBQVE7UUFDTixPQUFPLElBQUksQ0FBQyxPQUFPLENBQUM7SUFDdEIsQ0FBQztJQUVELGtHQUFrRztJQUNsRyxVQUFVLENBQUMsU0FBc0IsRUFBRSxPQUFvQixFQUFFLEtBQW1CO1FBQzFFLElBQUksQ0FBQyxPQUFPLEdBQUcsY0FBYyxDQUFDLElBQUksQ0FBQyxPQUFPLEVBQUUsT0FBTyxFQUFFLFNBQVMsRUFBRSxLQUFLLENBQUMsQ0FBQztJQUN6RSxDQUFDO0NBQ0YiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIFNoYXJlZE1lbW9yeSDigJQgVGhlIHNoYXJlZCBzdGF0ZSBjb250YWluZXIgZm9yIGFsbCBmbG93Y2hhcnQgZXhlY3V0aW9uXG4gKlxuICogTGlrZSBhIHJ1bnRpbWUgaGVhcCB3aXRoIG5hbWVzcGFjZSBpc29sYXRpb246XG4gKiAtIEVhY2ggcnVuIGdldHMgaXRzIG93biBuYW1lc3BhY2UgKHJ1bnMve2lkfS8pXG4gKiAtIERlZmF1bHQgdmFsdWVzIGNhbiBiZSBpbml0aWFsaXNlZCBhbmQgcHJlc2VydmVkXG4gKiAtIEFjY2VwdHMgY29tbWl0IGJ1bmRsZXMgZnJvbSBUcmFuc2FjdGlvbkJ1ZmZlclxuICpcbiAqIENPUFktT04tV1JJVEUgKDkuMjkuMCDigJQgZG9jcy9kZXNpZ24vMjAyNi0xMC1jb3B5LW9uLXdyaXRlLWNvbW1pdC5tZCk6XG4gKiBgY29udGV4dGAgaXMgYSBHRU5FUkFUSU9OLCBhbmQgYSBnZW5lcmF0aW9uIGlzIG5ldmVyIGVkaXRlZC4gRXZlcnkgd3JpdGUg4oCUXG4gKiBgYXBwbHlQYXRjaGAgKGEgc3RhZ2UgY29tbWl0KSwgYHNldFZhbHVlYCwgYHVwZGF0ZVZhbHVlYCDigJQgYnVpbGRzIHRoZSBuZXh0XG4gKiBnZW5lcmF0aW9uIGJ5IGNvcHlpbmcgdGhlIHJvb3QgYW5kIHRoZSBjb250YWluZXJzIG9uIGVhY2ggd3JpdHRlbiBwYXRoLFxuICogc2hhcmVzIGV2ZXJ5IG90aGVyIHN1YnRyZWUgd2l0aCB0aGUgZ2VuZXJhdGlvbiBiZWZvcmUgaXQsIGFuZCBzd2Fwcy4gU28gYVxuICogZ2VuZXJhdGlvbiBhIHN0YWdlIGNhcHR1cmVkIChpdHMgZmlyc3QtdG91Y2ggdmlldywgaXRzIHRyYW5zYWN0aW9uXG4gKiBidWZmZXIncyBkaWZmIGJhc2UpIHN0YXlzIGV4YWN0bHkgd2hhdCBpdCB3YXMsIGFuZCBhIHdyaXRlIGNvc3RzIE8od2hhdCBpdFxuICogd3JvdGUpLCBub3QgTyhzdGF0ZSkuXG4gKi9cblxuaW1wb3J0IHsgbWVyZ2VDb250ZXh0V2lucywgb3duZWRSb290T2YsIG93blNwaW5lIH0gZnJvbSAnLi9wYXRoT3BzLmpzJztcbmltcG9ydCB0eXBlIHsgTWVtb3J5UGF0Y2gsIFRyYWNlRW50cnkgfSBmcm9tICcuL3R5cGVzLmpzJztcbmltcG9ydCB7IGdldE5lc3RlZFZhbHVlLCBnZXRSdW5BbmRHbG9iYWxQYXRocywgbmV4dEdlbmVyYXRpb24sIHNldE5lc3RlZFZhbHVlLCB1cGRhdGVOZXN0ZWRWYWx1ZSB9IGZyb20gJy4vdXRpbHMuanMnO1xuXG5leHBvcnQgY2xhc3MgU2hhcmVkTWVtb3J5IHtcbiAgcHJpdmF0ZSBjb250ZXh0OiB7IFtrZXk6IHN0cmluZ106IGFueSB9ID0ge307XG4gIHByaXZhdGUgX2RlZmF1bHRWYWx1ZXM/OiB1bmtub3duO1xuXG4gIGNvbnN0cnVjdG9yKGRlZmF1bHRWYWx1ZXM/OiB1bmtub3duLCBpbml0aWFsQ29udGV4dD86IHVua25vd24pIHtcbiAgICB0aGlzLl9kZWZhdWx0VmFsdWVzID0gZGVmYXVsdFZhbHVlcztcbiAgICBjb25zdCBzZWVkID0gbWVyZ2VDb250ZXh0V2lucyhpbml0aWFsQ29udGV4dCB8fCB7fSwgZGVmYXVsdFZhbHVlcyB8fCB7fSk7XG4gICAgLy8gRGV0YWNoZWQgT05DRSwgaGVyZTogYG1lcmdlQ29udGV4dFdpbnNgIGNvcGllcyBvbmx5IHRoZSB0b3AgbGV2ZWwsIHNvXG4gICAgLy8gdGhlIHNlZWQncyBuZXN0ZWQgdmFsdWVzIGFyZSB0aGUgY2FsbGVyJ3Mgb3duIG9iamVjdHMuIEJlZm9yZSA5LjI5LjBcbiAgICAvLyB0aGUgZmlyc3QgY29tbWl0J3Mgd2hvbGUtc3RhdGUgY2xvbmUgZGV0YWNoZWQgdGhlbSAoYW5kIHVudGlsIHRoZW4gYVxuICAgIC8vIGNhbGxlciBtdXRhdGluZyBpdHMgYGluaXRpYWxDb250ZXh0YCBjaGFuZ2VkIGxpdmUgc3RhdGUgd2l0aCBubyByb3cpO1xuICAgIC8vIG5vdGhpbmcgcmUtY2xvbmVzIHRoZSBzdGF0ZSBhbnkgbW9yZSwgc28gdGhlIHNlZWQgaXMgZGV0YWNoZWQgYXRcbiAgICAvLyBjb25zdHJ1Y3Rpb24g4oCUIG9uZSBjbG9uZSBwZXIgcnVudGltZSwgbm90IG9uZSBwZXIgY29tbWl0LlxuICAgIHRoaXMuY29udGV4dCA9IE9iamVjdC5rZXlzKHNlZWQpLmxlbmd0aCA+IDAgPyBzdHJ1Y3R1cmVkQ2xvbmUoc2VlZCkgOiBzZWVkO1xuICB9XG5cbiAgLyoqIEdldHMgYSBjbG9uZSBvZiB0aGUgZGVmYXVsdCB2YWx1ZXMuICovXG4gIGdldERlZmF1bHRWYWx1ZXMoKSB7XG4gICAgcmV0dXJuIHRoaXMuX2RlZmF1bHRWYWx1ZXMgPyBzdHJ1Y3R1cmVkQ2xvbmUodGhpcy5fZGVmYXVsdFZhbHVlcykgOiB1bmRlZmluZWQ7XG4gIH1cblxuICAvKiogR2V0cyBhbGwgcnVuIG5hbWVzcGFjZXMuICovXG4gIGdldFJ1bnMoKSB7XG4gICAgcmV0dXJuIHRoaXMuY29udGV4dC5ydW5zO1xuICB9XG5cbiAgLyoqIFVwZGF0ZXMgYSB2YWx1ZSB1c2luZyBtZXJnZSBzZW1hbnRpY3MsIGFzIGEgbmV3IGdlbmVyYXRpb24gKHBhdGggY29weSArIHN3YXApLiAqL1xuICB1cGRhdGVWYWx1ZShydW5JZDogc3RyaW5nLCBwYXRoOiBzdHJpbmdbXSwga2V5OiBzdHJpbmcsIHZhbHVlOiB1bmtub3duKSB7XG4gICAgY29uc3QgbmV4dCA9IHRoaXMub3duZWRQYXRoVG8ocnVuSWQsIHBhdGgsIGtleSk7XG4gICAgdXBkYXRlTmVzdGVkVmFsdWUobmV4dCwgcnVuSWQsIHBhdGgsIGtleSwgdmFsdWUsIHRoaXMuZ2V0RGVmYXVsdFZhbHVlcygpKTtcbiAgICB0aGlzLmNvbnRleHQgPSBuZXh0O1xuICB9XG5cbiAgLyoqIFNldHMgYSB2YWx1ZSB1c2luZyBvdmVyd3JpdGUgc2VtYW50aWNzLCBhcyBhIG5ldyBnZW5lcmF0aW9uIChwYXRoIGNvcHkgKyBzd2FwKS4gKi9cbiAgc2V0VmFsdWUocnVuSWQ6IHN0cmluZywgcGF0aDogc3RyaW5nW10sIGtleTogc3RyaW5nLCB2YWx1ZTogdW5rbm93bikge1xuICAgIGNvbnN0IG5leHQgPSB0aGlzLm93bmVkUGF0aFRvKHJ1bklkLCBwYXRoLCBrZXkpO1xuICAgIHNldE5lc3RlZFZhbHVlKG5leHQsIHJ1bklkLCBwYXRoLCBrZXksIHZhbHVlLCB0aGlzLmdldERlZmF1bHRWYWx1ZXMoKSk7XG4gICAgdGhpcy5jb250ZXh0ID0gbmV4dDtcbiAgfVxuXG4gIC8qKlxuICAgKiBBIGNvcHkgb2YgdGhlIGN1cnJlbnQgZ2VuZXJhdGlvbidzIHJvb3Qgd2hvc2UgY29udGFpbmVycyBvbiB0aGUgd2F5IHRvXG4gICAqIGBrZXlgIGFyZSBvd25lZCDigJQgdGhlIGluLXBsYWNlIGhlbHBlcnMgYWJvdmUgdGhlbiBlZGl0IG9ubHkgY29waWVzLlxuICAgKi9cbiAgcHJpdmF0ZSBvd25lZFBhdGhUbyhydW5JZDogc3RyaW5nLCBwYXRoOiBzdHJpbmdbXSwga2V5OiBzdHJpbmcpOiB7IFtrZXk6IHN0cmluZ106IGFueSB9IHtcbiAgICBjb25zdCBvd25lZCA9IG5ldyBXZWFrU2V0PG9iamVjdD4oKTtcbiAgICBjb25zdCByb290ID0gb3duZWRSb290T2YodGhpcy5jb250ZXh0LCBvd25lZCk7XG4gICAgY29uc3QgeyBydW5QYXRoLCBnbG9iYWxQYXRoIH0gPSBnZXRSdW5BbmRHbG9iYWxQYXRocyhydW5JZCwgcGF0aCk7XG4gICAgb3duU3BpbmUocm9vdCwgWy4uLihydW5QYXRoIHx8IGdsb2JhbFBhdGgpLCBrZXldLCBvd25lZCk7XG4gICAgcmV0dXJuIHJvb3Q7XG4gIH1cblxuICAvKipcbiAgICogUmVhZHMgYSB2YWx1ZSBmcm9tIHRoZSBzdG9yZS5cbiAgICogTG9va3MgdXAgaW4gcnVuIG5hbWVzcGFjZSBmaXJzdCwgZmFsbHMgYmFjayB0byBnbG9iYWwuXG4gICAqL1xuICBnZXRWYWx1ZShydW5JZD86IHN0cmluZywgcGF0aD86IHN0cmluZ1tdLCBrZXk/OiBzdHJpbmcpOiBhbnkge1xuICAgIGNvbnN0IHsgZ2xvYmFsUGF0aCwgcnVuUGF0aCB9ID0gZ2V0UnVuQW5kR2xvYmFsUGF0aHMocnVuSWQsIHBhdGgpO1xuICAgIGNvbnN0IHZhbHVlID0gcnVuUGF0aCA/IGdldE5lc3RlZFZhbHVlKHRoaXMuY29udGV4dCwgcnVuUGF0aCwga2V5KSA6IHVuZGVmaW5lZDtcbiAgICByZXR1cm4gdHlwZW9mIHZhbHVlICE9PSAndW5kZWZpbmVkJyA/IHZhbHVlIDogZ2V0TmVzdGVkVmFsdWUodGhpcy5jb250ZXh0LCBnbG9iYWxQYXRoLCBrZXkpO1xuICB9XG5cbiAgLyoqIEdldHMgdGhlIGVudGlyZSBzdGF0ZSBhcyBhIEpTT04gb2JqZWN0IOKAlCB0aGUgY3VycmVudCBnZW5lcmF0aW9uLCBieSByZWZlcmVuY2UuIE5ldmVyIG11dGF0ZSBpdC4gKi9cbiAgZ2V0U3RhdGUoKTogUmVjb3JkPHN0cmluZywgdW5rbm93bj4ge1xuICAgIHJldHVybiB0aGlzLmNvbnRleHQ7XG4gIH1cblxuICAvKiogQXBwbGllcyBhIGNvbW1pdCBidW5kbGUgZnJvbSBUcmFuc2FjdGlvbkJ1ZmZlcjogYnVpbGRzIHRoZSBuZXh0IGdlbmVyYXRpb24gYW5kIHN3YXBzIGl0IGluLiAqL1xuICBhcHBseVBhdGNoKG92ZXJ3cml0ZTogTWVtb3J5UGF0Y2gsIHVwZGF0ZXM6IE1lbW9yeVBhdGNoLCB0cmFjZTogVHJhY2VFbnRyeVtdKTogdm9pZCB7XG4gICAgdGhpcy5jb250ZXh0ID0gbmV4dEdlbmVyYXRpb24odGhpcy5jb250ZXh0LCB1cGRhdGVzLCBvdmVyd3JpdGUsIHRyYWNlKTtcbiAgfVxufVxuIl19

package/dist/esm/lib/memory/StageContext.d.ts

@@ -91,6 +91,15 @@ export declare class StageContext {
      * facade path never allocates it.
      */
     private _nestedReads?;
+    /**
+     * Dev mode only: the root keys whose LAST tracked read was served from
+     * committed state — before this stage's first write, when no transaction
+     * buffer exists yet. Such a read is the committed object itself, so an
+     * in-place edit of it moves the buffer's diff base too (copy-on-write,
+     * 9.29.0); {@link warnOnBorrowedMutation} checks these keys even when the
+     * stage wrote them. Never allocated outside `enableDevMode()`.
+     */
+    private _viewReads?;
     /**
      * Has this frame committed at least once? The borrowed-read guard runs on
      * the FIRST commit only — see {@link warnOnBorrowedMutation}. The frame
@@ -304,14 +313,14 @@ export declare class StageContext {
      * and the transaction buffer's diff base ({@link getTransactionBuffer}).
      *
      * WHY A BARE REFERENCE IS SAFE — the invariant this rests on: committed
-     * state is immutable-after-swap. `SharedMemory.applyPatch` routes through
-     * `applySmartMerge`, which `structuredClone`s the current state, mutates
-     * only the clone, and swaps `SharedMemory.context` to it — the object a
-     * stage captured here is never edited afterwards. (`SharedMemory.setValue`/
-     * `updateValue` DO mutate in place, but have no callers during traversal;
-     * every runtime write reaches state through a stage commit's `applyPatch`.)
-     * Holding the reference therefore gives this stage a stable snapshot at
-     * zero cost — no clone, which is the entire point of #13.
+     * state is immutable-after-swap. Every write to `SharedMemory` builds the
+     * NEXT generation and swaps it in (copy-on-write, 9.29.0: `applyPatch` via
+     * `nextGeneration`, and `setValue`/`updateValue` too) — it copies the root
+     * and the containers on each written path, shares the rest, and never
+     * edits a container of the generation a stage captured here. Holding the
+     * reference therefore gives this stage a stable snapshot at zero cost — no
+     * clone, which is the entire point of #13. The transaction buffer's
+     * net-change diff base rests on the same guarantee: it IS this view.
      *
      * WHY FIRST TOUCH, not first write: the pre-#13 eager engine cloned the
      * state into the buffer at the stage's first ACCESS, anchoring both its
@@ -371,7 +380,13 @@ export declare class StageContext {
      *    2. LIVE state via `sharedMemory.getValue` for keys absent from the
      *       snapshot — including its run→global namespace fallback. The eager
      *       engine had this exact live fallback for snapshot-missing keys;
-     *       byte-identity over purity.
+     *       byte-identity over purity. After the stage's first write such a
+     *       value can be the very container the buffer's diff base holds at
+     *       the path (the stage deleted or unset it, or replaced a container
+     *       above it), so the base is detached there first
+     *       (`TransactionBuffer · detachBase`): an in-place edit of the value
+     *       (out of contract) written back is recorded, as on 9.28.0, whose
+     *       base was a clone taken at the first write.
      *
      *  Reads never construct the buffer (#13): a stage that never writes
      *  performs zero clones of the shared state. */
@@ -447,22 +462,34 @@ export declare class StageContext {
      * subflow merge-back into a committed branch parent) other stages have
      * legitimately moved the state they were compared against.
      *
+     * A key the stage DID stage is still checked when its last read came from
+     * committed state ({@link _viewReads} — read before the first write):
+     * that read was the committed object itself, and the buffer's diff base IS
+     * that object (copy-on-write, 9.29.0), so an in-place edit followed by a
+     * write of the key commits NO change — live state keeps the edit, the log
+     * does not. Compared against committed state, not the written value, so a
+     * legitimate write never trips it.
+     *
      * Costs nothing outside `enableDevMode()`.
      */
     private warnOnBorrowedMutation;
+    /** The staged-key half of {@link warnOnBorrowedMutation}: did committed state itself move under a read? */
+    private warnOnCommittedMutation;
     /**
      * Flush staged writes to shared memory and RELEASE the per-stage staging
      * state (#13b).
      *
-     * Commit is the stage's lifecycle end: `buffer` (2 full-state clones) and
-     * `stateView` (a reference that pins one full committed-state GENERATION —
-     * `applySmartMerge` clones + swaps the whole state per commit, so every
-     * stage's view is a distinct object) are only needed DURING execution, as
-     * the read snapshot + net-change diff base. The execution tree retains
-     * every StageContext for the lifetime of the run, so WITHOUT the release
-     * a long loop retains one state generation + two clones per executed
-     * stage — measured O(N²): 563.8MB at N=200 on an agent-style chart; a
-     * 500-iteration agent OOMed a default Node heap (backlog #18).
+     * Commit is the stage's lifecycle end: `buffer` (its working copy and
+     * whatever private copies its reads took) and `stateView` (a reference that
+     * pins one committed-state GENERATION) are only needed DURING execution,
+     * as the read snapshot + net-change diff base. The execution tree retains
+     * every StageContext for the lifetime of the run, so WITHOUT the release a
+     * long loop retains one state generation per executed stage — measured
+     * O(N²) before copy-on-write (9.29.0), when each generation and each
+     * buffer was a whole-state clone: 563.8MB at N=200 on an agent-style
+     * chart; a 500-iteration agent OOMed a default Node heap (backlog #18).
+     * Generations now share every unchanged subtree, but a pinned one still
+     * keeps the containers later commits replaced alive.
      *
      * RE-USE AFTER COMMIT stays correct because both fields re-create lazily:
      * - a later READ re-anchors via {@link firstTouchState} on the CURRENT