@earendil-works/chord 1.4.0 → 1.5.0

package/dist/delta/pending.js

@@ -0,0 +1,143 @@
+/** Pending ops past which only "replace with the current value" stays pending. */
+export const MAX_PENDING_OPS = 10_000;
+const EMPTY = { kind: "empty" };
+const REPLACE = { kind: "replace" };
+const NO_OPS = { kind: "ops", ops: [] };
+const REPLACE_TAKE = { kind: "replace" };
+/**
+ * Pending ops of one state for one consumer, in order and raw (never encoded while they wait). `r` drops everything
+ * before it. A leaf op merges into the last pending leaf op on the same path (`a` + `a` joined, `s` replaces `s` or `a`,
+ * `a` after a string `s` appends into it); any other op clears the leaf index. Leaf ops on different paths commute,
+ * except after an ancestor primitive `s`, after which the descendant cannot be written until a structural op clears the
+ * index. Past `MAX_PENDING_OPS` only "replace with the current value" stays pending.
+ *
+ * Ops are only those of Delta's tracker, `diffRevisions()` and `appendText()`; received op arrays and tuples are never
+ * mutated (they feed other consumers too), a merge makes a new tuple.
+ */
+export class PendingOps {
+    #state = EMPTY;
+    /** Queue the ops of one commit. */
+    push(ops) {
+        if (ops.length === 0)
+            return;
+        const state = this.#state;
+        // A batch that starts with `r` (the tracker's and `diffRevisions()`'s only place for it) drops everything
+        // pending, also an overflow, and is kept as received.
+        if (ops[0][0] === "r") {
+            this.#state = { kind: "batch", ops };
+            return;
+        }
+        switch (state.kind) {
+            case "empty":
+                this.#state = { kind: "batch", ops };
+                return;
+            case "batch": {
+                const folding = { kind: "folding", ops: [], leaves: new Map() };
+                this.#state = folding;
+                if (this.#fold(state.ops, folding))
+                    this.#fold(ops, folding);
+                return;
+            }
+            case "folding":
+                this.#fold(ops, state);
+                return;
+            case "replace":
+                return;
+        }
+    }
+    /**
+     * Pending ops after folding; 1 once overflowed (the replacement the owner sends). One batch is counted as received,
+     * so a single commit larger than `MAX_PENDING_OPS` counts in full until a second one arrives and overflows.
+     */
+    get size() {
+        const state = this.#state;
+        if (state.kind === "empty")
+            return 0;
+        return state.kind === "replace" ? 1 : state.ops.length;
+    }
+    /** Hand over everything pending and start empty. */
+    take() {
+        const state = this.#state;
+        this.#state = EMPTY;
+        switch (state.kind) {
+            case "empty":
+                return NO_OPS;
+            case "batch":
+            case "folding":
+                return { kind: "ops", ops: state.ops };
+            case "replace":
+                return REPLACE_TAKE;
+        }
+    }
+    /** Fold `ops` into `folding`; false once the queue overflowed into `replace`. */
+    #fold(ops, folding) {
+        for (const op of ops) {
+            switch (op[0]) {
+                case "r":
+                    folding.ops.length = 0;
+                    folding.leaves.clear();
+                    break;
+                case "a":
+                    if (mergeLeaf(op, folding))
+                        continue;
+                    break;
+                case "s":
+                    if (isPrimitive(op[2])) {
+                        if (mergeLeaf(op, folding))
+                            continue;
+                    }
+                    else if (folding.leaves.size > 0)
+                        folding.leaves.clear();
+                    break;
+                default:
+                    if (folding.leaves.size > 0)
+                        folding.leaves.clear();
+            }
+            folding.ops.push(op);
+            if (folding.ops.length > MAX_PENDING_OPS) {
+                this.#state = REPLACE;
+                return false;
+            }
+        }
+        return true;
+    }
+}
+const isPrimitive = (value) => value === null || typeof value !== "object";
+/**
+ * Merge the leaf op `op` into the last pending leaf op on its path, or index it as that op at the position it is about
+ * to be pushed to. True when merged.
+ */
+function mergeLeaf(op, folding) {
+    const key = pathKey(op[1]);
+    const at = folding.leaves.get(key);
+    if (at !== undefined) {
+        // The index points at leaf ops only.
+        const merged = merge(folding.ops[at], op);
+        if (merged !== undefined) {
+            folding.ops[at] = merged;
+            return true;
+        }
+    }
+    folding.leaves.set(key, folding.ops.length);
+    return false;
+}
+/**
+ * The key of a path in the leaf index. Injective, as merging two distinct paths would lose a write: `["a.b"]` and
+ * `["a", "b"]` are different keys. A number and its string (`1`, `"1"`) may share one: within one index lifetime a
+ * parent is either an array or an object, as changing it is a structural op that clears the index.
+ */
+function pathKey(path) {
+    return JSON.stringify(path);
+}
+/** `next` folded into `previous` (same path), or undefined when they do not fold. */
+function merge(previous, next) {
+    if (next[0] === "s")
+        return next;
+    if (previous[0] === "a")
+        return ["a", previous[1], previous[2] + next[2]];
+    // Only a string set takes an append; the tracker never appends to another primitive.
+    if (typeof previous[2] === "string")
+        return ["s", previous[1], previous[2] + next[2]];
+    return undefined;
+}
+//# sourceMappingURL=pending.js.map

package/dist/delta/pending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending.js","sourceRoot":"","sources":["../../src/delta/pending.ts"],"names":[],"mappings":"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","sourcesContent":["// The pending queue: the ops a slow consumer of one state has not taken yet, folded while they wait.\nimport type { JsonValue } from \"../json.ts\";\nimport type { NonEmptyPath, Op, Path } from \"./index.ts\";\n\n/**\n * What `PendingOps.take()` hands over: the pending ops, folded, or `replace` after an overflow, which the owner of the\n * queue turns into a root replacement with the current value.\n */\nexport type PendingTake = { readonly kind: \"ops\"; readonly ops: readonly Op[] } | { readonly kind: \"replace\" };\n\n/** Pending ops past which only \"replace with the current value\" stays pending. */\nexport const MAX_PENDING_OPS = 10_000;\n\n/** A leaf op: an append, or a set of a primitive. The leaf index points at these only. */\ntype LeafOp = readonly [\"a\", NonEmptyPath, string] | readonly [\"s\", NonEmptyPath, JsonValue];\n\ntype Folding = {\n\treadonly kind: \"folding\";\n\t/** Owned by the queue until `take()` hands it over; never one of the received op arrays. */\n\treadonly ops: Op[];\n\t/** Path key to the position of the last pending leaf op on that path. */\n\treadonly leaves: Map<string, number>;\n};\n\ntype State =\n\t| { readonly kind: \"empty\" }\n\t/** One batch, kept by reference: a consumer that keeps up never pays for folding. */\n\t| { readonly kind: \"batch\"; readonly ops: readonly Op[] }\n\t| Folding\n\t/** Overflowed: nothing more accumulates until `take()` or a batch that starts with `r`. */\n\t| { readonly kind: \"replace\" };\n\nconst EMPTY: State = { kind: \"empty\" };\n\nconst REPLACE: State = { kind: \"replace\" };\n\nconst NO_OPS: PendingTake = { kind: \"ops\", ops: [] };\n\nconst REPLACE_TAKE: PendingTake = { kind: \"replace\" };\n\n/**\n * Pending ops of one state for one consumer, in order and raw (never encoded while they wait). `r` drops everything\n * before it. A leaf op merges into the last pending leaf op on the same path (`a` + `a` joined, `s` replaces `s` or `a`,\n * `a` after a string `s` appends into it); any other op clears the leaf index. Leaf ops on different paths commute,\n * except after an ancestor primitive `s`, after which the descendant cannot be written until a structural op clears the\n * index. Past `MAX_PENDING_OPS` only \"replace with the current value\" stays pending.\n *\n * Ops are only those of Delta's tracker, `diffRevisions()` and `appendText()`; received op arrays and tuples are never\n * mutated (they feed other consumers too), a merge makes a new tuple.\n */\nexport class PendingOps {\n\t#state: State = EMPTY;\n\n\t/** Queue the ops of one commit. */\n\tpush(ops: readonly Op[]): void {\n\t\tif (ops.length === 0) return;\n\t\tconst state = this.#state;\n\t\t// A batch that starts with `r` (the tracker's and `diffRevisions()`'s only place for it) drops everything\n\t\t// pending, also an overflow, and is kept as received.\n\t\tif (ops[0]![0] === \"r\") {\n\t\t\tthis.#state = { kind: \"batch\", ops };\n\t\t\treturn;\n\t\t}\n\t\tswitch (state.kind) {\n\t\t\tcase \"empty\":\n\t\t\t\tthis.#state = { kind: \"batch\", ops };\n\t\t\t\treturn;\n\t\t\tcase \"batch\": {\n\t\t\t\tconst folding: Folding = { kind: \"folding\", ops: [], leaves: new Map() };\n\t\t\t\tthis.#state = folding;\n\t\t\t\tif (this.#fold(state.ops, folding)) this.#fold(ops, folding);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tcase \"folding\":\n\t\t\t\tthis.#fold(ops, state);\n\t\t\t\treturn;\n\t\t\tcase \"replace\":\n\t\t\t\treturn;\n\t\t}\n\t}\n\n\t/**\n\t * Pending ops after folding; 1 once overflowed (the replacement the owner sends). One batch is counted as received,\n\t * so a single commit larger than `MAX_PENDING_OPS` counts in full until a second one arrives and overflows.\n\t */\n\tget size(): number {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"empty\") return 0;\n\t\treturn state.kind === \"replace\" ? 1 : state.ops.length;\n\t}\n\n\t/** Hand over everything pending and start empty. */\n\ttake(): PendingTake {\n\t\tconst state = this.#state;\n\t\tthis.#state = EMPTY;\n\t\tswitch (state.kind) {\n\t\t\tcase \"empty\":\n\t\t\t\treturn NO_OPS;\n\t\t\tcase \"batch\":\n\t\t\tcase \"folding\":\n\t\t\t\treturn { kind: \"ops\", ops: state.ops };\n\t\t\tcase \"replace\":\n\t\t\t\treturn REPLACE_TAKE;\n\t\t}\n\t}\n\n\t/** Fold `ops` into `folding`; false once the queue overflowed into `replace`. */\n\t#fold(ops: readonly Op[], folding: Folding): boolean {\n\t\tfor (const op of ops) {\n\t\t\tswitch (op[0]) {\n\t\t\t\tcase \"r\":\n\t\t\t\t\tfolding.ops.length = 0;\n\t\t\t\t\tfolding.leaves.clear();\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"a\":\n\t\t\t\t\tif (mergeLeaf(op, folding)) continue;\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"s\":\n\t\t\t\t\tif (isPrimitive(op[2])) {\n\t\t\t\t\t\tif (mergeLeaf(op, folding)) continue;\n\t\t\t\t\t} else if (folding.leaves.size > 0) folding.leaves.clear();\n\t\t\t\t\tbreak;\n\t\t\t\tdefault:\n\t\t\t\t\tif (folding.leaves.size > 0) folding.leaves.clear();\n\t\t\t}\n\t\t\tfolding.ops.push(op);\n\t\t\tif (folding.ops.length > MAX_PENDING_OPS) {\n\t\t\t\tthis.#state = REPLACE;\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t\treturn true;\n\t}\n}\n\nconst isPrimitive = (value: JsonValue): boolean => value === null || typeof value !== \"object\";\n\n/**\n * Merge the leaf op `op` into the last pending leaf op on its path, or index it as that op at the position it is about\n * to be pushed to. True when merged.\n */\nfunction mergeLeaf(op: LeafOp, folding: Folding): boolean {\n\tconst key = pathKey(op[1]);\n\tconst at = folding.leaves.get(key);\n\tif (at !== undefined) {\n\t\t// The index points at leaf ops only.\n\t\tconst merged = merge(folding.ops[at] as LeafOp, op);\n\t\tif (merged !== undefined) {\n\t\t\tfolding.ops[at] = merged;\n\t\t\treturn true;\n\t\t}\n\t}\n\tfolding.leaves.set(key, folding.ops.length);\n\treturn false;\n}\n\n/**\n * The key of a path in the leaf index. Injective, as merging two distinct paths would lose a write: `[\"a.b\"]` and\n * `[\"a\", \"b\"]` are different keys. A number and its string (`1`, `\"1\"`) may share one: within one index lifetime a\n * parent is either an array or an object, as changing it is a structural op that clears the index.\n */\nfunction pathKey(path: Path): string {\n\treturn JSON.stringify(path);\n}\n\n/** `next` folded into `previous` (same path), or undefined when they do not fold. */\nfunction merge(previous: LeafOp, next: LeafOp): LeafOp | undefined {\n\tif (next[0] === \"s\") return next;\n\tif (previous[0] === \"a\") return [\"a\", previous[1], previous[2] + next[2]];\n\t// Only a string set takes an append; the tracker never appends to another primitive.\n\tif (typeof previous[2] === \"string\") return [\"s\", previous[1], previous[2] + next[2]];\n\treturn undefined;\n}\n"]}

package/dist/delta/tracker.d.ts

@@ -2,6 +2,10 @@ import type { JsonValue } from "../json.ts";
 import type { Draft } from "./draft.ts";
 import { type Op } from "./index.ts";
 export type { Draft, JsonValue, Op };
+/** Keys of `T` whose value type is exactly `string`: required, and not a string literal type. */
+export type StringKeys<T> = T extends readonly unknown[] ? never : {
+    [Key in keyof T]: string extends T[Key] ? (T[Key] extends string ? Key : never) : never;
+}[keyof T];
 export interface Prepared<T extends object> {
     readonly base: T;
     readonly value: T;
@@ -23,4 +27,12 @@ export interface Tracker<T extends object> {
 }
 /** Take immutable ownership of an alias-free strict-JSON root in O(1). */
 export declare function track<T extends object>(initial: T): Tracker<T>;
+/**
+ * Append `text` to the string at `draft[key]`, costing O(text.length). The change is recorded as one append op
+ * (several appends to the same key in one change join into one op) without comparing the old and new strings. A plain
+ * assignment such as `draft[key] += text` gives the same op, but `prepare()` then has to check that the new string
+ * extends the old one, which reads the whole string: O(length) per change. A plain assignment or deletion of the key in
+ * the same change falls back to that check.
+ */
+export declare function appendText<T extends object>(draft: Draft<T>, key: StringKeys<T>, text: string): void;
 //# sourceMappingURL=tracker.d.ts.map

package/dist/delta/tracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/delta/tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAqC,KAAK,EAAE,EAAyC,MAAM,YAAY,CAAC;AAE/G,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;AAkHrC,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM;IACzC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,KAAK,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,MAAM,CAAC,CAAC,SAAS,MAAM;IACvC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,OAAO,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC;IACvB,KAAK,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,MAAM;IACxC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,WAAW,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;IACzB,cAAc,CAAC,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CACnC;AAmLD,0EAA0E;AAC1E,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE9D"}
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/delta/tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAGN,KAAK,EAAE,EAKP,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;AAErC,iGAAiG;AACjG,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,OAAO,EAAE,GACrD,KAAK,GACL;KAAG,GAAG,IAAI,MAAM,CAAC,GAAG,MAAM,SAAS,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,GAAG,KAAK;CAAE,CAAC,MAAM,CAAC,CAAC,CAAC;AAuHxG,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM;IACzC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,KAAK,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,MAAM,CAAC,CAAC,SAAS,MAAM;IACvC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,OAAO,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC;IACvB,KAAK,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,MAAM;IACxC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,WAAW,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;IACzB,cAAc,CAAC,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CACnC;AAuMD,0EAA0E;AAC1E,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAkBpG"}

package/dist/delta/tracker.js

@@ -1,6 +1,6 @@
 import { copyJson } from "../json.js";
 import { applyImmutableTrusted } from "./apply-immutable-trusted.js";
-import { applyImmutable, overlap, RESERVED_SEGMENTS } from "./index.js";
+import { applyImmutable, overlap, ownedSlice, RESERVED_SEGMENTS, } from "./index.js";
 const NODE = Symbol("chord.delta.overlay.node");
 const PREPARED = new WeakMap();
 const RELEASED = {};
@@ -91,9 +91,20 @@ class ChangeImpl {
         this.#context = undefined;
     }
 }
+/**
+ * Open drafts are tracked so that adopting one change makes its open competitors stale at once. Prepared contexts need
+ * no tracking: `prepare()` releases their overlay, and `adopt()` rejects them by revision.
+ *
+ * The most recent open context is held strongly in `#open`: with one transaction at a time per tracker, the common case,
+ * that is the only one, and it costs no `WeakRef` (each `WeakRef` target survives the scavenges of the current job, and
+ * V8 then pretenures the context allocation site). A second `beginChange()` while one is open moves the older context
+ * into `#competitors` through a `WeakRef`, so a draft the caller drops can be collected. A dropped draft that was never
+ * settled stays held by `#open` until the tracker's next `beginChange()` or `adopt()`: at most one per tracker.
+ */
 class TrackerImpl {
     #owner = {};
-    #contexts = new Set();
+    #open;
+    #competitors;
     #selfRef;
     #value;
     #revision = 0;
@@ -110,13 +121,15 @@ class TrackerImpl {
     }
     beginChange() {
         const context = createContext(this.#selfRef, this.#owner, this.#revision, this.#value, false, this.#value);
-        this.#register(context);
+        if (this.#open !== undefined)
+            this.#demote(this.#open);
+        this.#open = context;
         return new ChangeImpl(context);
     }
     prepareReplace(value) {
+        // Not tracked: materialization below releases the context before this returns, as `prepare()` does.
         const context = createContext(this.#selfRef, this.#owner, this.#revision, value, true, this.#value);
         context.status.value = "prepared";
-        this.#register(context);
         try {
             return materializePrepared(context);
         }
@@ -155,49 +168,90 @@ class TrackerImpl {
         this.#invalidate(context);
     }
     releaseContext(context) {
-        if (context.registryRef !== undefined)
-            this.#contexts.delete(context.registryRef);
+        if (this.#open === context)
+            this.#open = undefined;
+        else if (context.registryRef !== undefined)
+            this.#competitors?.delete(context.registryRef);
         context.registryRef = undefined;
     }
-    #register(context) {
+    #demote(context) {
         const reference = new WeakRef(context);
         context.registryRef = reference;
-        this.#contexts.add(reference);
+        this.#competitors ??= new Set();
+        this.#competitors.add(reference);
         this.#pruneBudget -= 1;
         if (this.#pruneBudget === 0) {
-            this.#prune();
-            this.#pruneBudget = Math.max(256, this.#contexts.size);
-        }
-    }
-    #prune() {
-        for (const reference of this.#contexts) {
-            if (reference.deref() === undefined)
-                this.#contexts.delete(reference);
+            for (const entry of this.#competitors) {
+                if (entry.deref() === undefined)
+                    this.#competitors.delete(entry);
+            }
+            this.#pruneBudget = Math.max(256, this.#competitors.size);
         }
     }
     #invalidate(winner) {
-        for (const reference of this.#contexts) {
+        const open = this.#open;
+        const competitors = this.#competitors;
+        this.#open = undefined;
+        this.#competitors = undefined;
+        this.#pruneBudget = 256;
+        if (open !== undefined)
+            staleCompetitor(open, winner);
+        if (competitors === undefined)
+            return;
+        for (const reference of competitors) {
             const context = reference.deref();
-            if (context === undefined || context === winner)
-                continue;
-            if (context.status.value === "open" || context.status.value === "prepared")
-                context.status.value = "stale";
-            // Adoption must not walk every node touched by a competing draft. Drop the
-            // context's strong overlay references in O(1); externally retained proxies
-            // still see the stale status and are reclaimed with their holders.
-            releaseOverlayReferences(context);
+            if (context !== undefined)
+                staleCompetitor(context, winner);
         }
-        this.#contexts.clear();
-        this.#pruneBudget = 256;
     }
     replacementBase(context) {
         return context.baseRevision === this.#revision ? this.#value : undefined;
     }
 }
+function staleCompetitor(context, winner) {
+    if (context === winner)
+        return;
+    if (context.status.value === "open" || context.status.value === "prepared")
+        context.status.value = "stale";
+    // Adoption must not walk every node touched by a competing draft. Drop the
+    // context's strong overlay references in O(1); externally retained proxies
+    // still see the stale status and are reclaimed with their holders.
+    context.registryRef = undefined;
+    releaseOverlayReferences(context);
+}
 /** Take immutable ownership of an alias-free strict-JSON root in O(1). */
 export function track(initial) {
     return new TrackerImpl(initial);
 }
+/**
+ * Append `text` to the string at `draft[key]`, costing O(text.length). The change is recorded as one append op
+ * (several appends to the same key in one change join into one op) without comparing the old and new strings. A plain
+ * assignment such as `draft[key] += text` gives the same op, but `prepare()` then has to check that the new string
+ * extends the old one, which reads the whole string: O(length) per change. A plain assignment or deletion of the key in
+ * the same change falls back to that check.
+ */
+export function appendText(draft, key, text) {
+    // Trust boundary: JavaScript callers can pass any object and key; the types cover TypeScript callers.
+    const node = draft[NODE];
+    if (node === undefined)
+        throw new TypeError("appendText() needs a draft");
+    assertWritable(node.context);
+    const name = String(key);
+    const current = Array.isArray(nodeBase(node)) || !objectHas(node, name) ? undefined : objectValue(node, name);
+    if (typeof current !== "string")
+        throw new TypeError(`appendText() needs a string at ${JSON.stringify(name)}`);
+    if (text.length === 0)
+        return;
+    // The op and the new value keep the text; a copy, so they never keep a larger string the caller cut it from alive.
+    const owned = ownedSlice(text, 0);
+    const appended = node.appends?.get(name) ?? (hasObjectWrite(node, name) ? undefined : "");
+    setObjectWrite(node, name, current + owned);
+    markDirty(node);
+    if (appended !== undefined) {
+        node.appends ??= new Map();
+        node.appends.set(name, appended + owned);
+    }
+}
 function materializePrepared(context) {
     const operations = ensureOperations(context);
     const base = context.baseValue;
@@ -232,10 +286,10 @@ function createContext(tracker, owner, baseRevision, root, replacement, base) {
         status: { value: "open" },
         root: undefined,
         bases: [],
-        stored: [],
+        stored: undefined,
         dirty: [],
         nodes: [],
-        rawNodes: new WeakMap(),
+        rawNodes: undefined,
         ops: undefined,
         replacement,
         replacementNoop: false,
@@ -298,7 +352,7 @@ const sharedObjectHandler = {
 };
 const sharedArrayHandler = sharedObjectHandler;
 function createNode(context, base, parent, parentKind = 0, parentKey = "", parentSource = undefined, parentPlacement = false) {
-    const existing = context.rawNodes.get(base);
+    const existing = context.rawNodes?.get(base);
     if (existing !== undefined)
         return existing;
     const target = Array.isArray(base) ? [] : {};
@@ -319,7 +373,12 @@ function createNode(context, base, parent, parentKind = 0, parentKey = "", paren
         node.parentSource = parentSource;
     target[NODE] = node;
     node.proxy = new Proxy(target, Array.isArray(base) ? sharedArrayHandler : sharedObjectHandler);
-    context.rawNodes.set(base, node);
+    // The root is never reached again through a child value (tracked values are alias-free), so a change that touches
+    // only the root needs no map.
+    if (parent !== undefined) {
+        context.rawNodes ??= new WeakMap();
+        context.rawNodes.set(base, node);
+    }
     context.nodes.push(node);
     return node;
 }
@@ -332,6 +391,8 @@ function nodeParent(node) {
 function storeValue(context, value) {
     if (!isContainer(value))
         return value;
+    // Created on the first container write: primitive writes never store.
+    context.stored ??= [];
     const index = context.stored.length;
     context.stored.push(value);
     return { index };
@@ -438,6 +499,7 @@ function setProperty(node, property, supplied) {
     const wasDeleted = isObjectDeleted(node, key);
     if (!wasDeleted && !isContainer(stored) && current === stored)
         return true;
+    node.appends?.delete(key);
     setObjectWrite(node, key, stored);
     if (wasDeleted && Object.hasOwn(nodeBase(node), key)) {
         if (node.readded === undefined)
@@ -457,6 +519,7 @@ function deleteProperty(node, property) {
     const key = String(property);
     if (!objectHas(node, key))
         return true;
+    node.appends?.delete(key);
     deleteObjectWrite(node, key);
     node.readded?.delete(key);
     setObjectDeletion(node, key);
@@ -930,13 +993,14 @@ function insertPiece(node, items, start = 0) {
 function insertPlacementPiece(node, values, start = 0) {
     if (values.length === start)
         return [];
-    const storedLength = node.context.stored.length;
+    const storedLength = node.context.stored?.length ?? 0;
     try {
         for (let index = start; index < values.length; index++)
             values[index] = storeValue(node.context, clonePlacement(values[index]));
     }
     catch (error) {
-        node.context.stored.length = storedLength;
+        if (node.context.stored !== undefined)
+            node.context.stored.length = storedLength;
         throw error;
     }
     return [
@@ -1396,7 +1460,7 @@ function cloneNode(node) {
 function cloneStored(value, context) {
     if (!isContainer(value))
         return value;
-    const node = context.rawNodes.get(value);
+    const node = context.rawNodes?.get(value);
     return node === undefined || (!node.dirty && !node.subtreeDirty) ? value : cloneNode(node);
 }
 function clonePlacementNode(node) {
@@ -1420,7 +1484,7 @@ function clonePlacementNode(node) {
 function clonePlacementStored(value, context) {
     if (!isContainer(value))
         return copyJson(value);
-    const node = context.rawNodes.get(value);
+    const node = context.rawNodes?.get(value);
     return node === undefined ? copyJson(value) : clonePlacementNode(node);
 }
 function defineData(target, key, value) {
@@ -1696,6 +1760,11 @@ function hasPlacementAncestor(node) {
 }
 function emitObjectWrite(node, path, operations, key, value) {
     const nextPath = [...path, key];
+    const appended = node.appends?.get(key);
+    if (appended !== undefined) {
+        operations.push(["a", nextPath, appended]);
+        return false;
+    }
     const before = node.readded?.has(key) || !Object.hasOwn(nodeBase(node), key)
         ? undefined
         : nodeBase(node)[key];
@@ -1895,17 +1964,18 @@ function emitChangedValue(operations, path, before, after) {
     if (isContainer(before) && isContainer(after) && equalTrustedJson(before, after))
         return false;
     if (typeof before === "string" && typeof after === "string") {
-        // Slice/equality stays on V8's rope fast path; startsWith scans the entire
-        // accumulated prefix on every append.
+        // O(length): any slice of a rope makes V8 flatten all of it, so this prefix check copies the whole string once per
+        // change, even when the writer only appended. Streaming writers use appendText(), which skips it. The op text gets
+        // a copy of its own, so it does not keep the whole of `after` alive.
         if (after.length > before.length && after.slice(0, before.length) === before) {
-            operations.push(["a", path, after.slice(before.length)]);
+            operations.push(["a", path, ownedSlice(after, before.length)]);
             return true;
         }
         const shared = overlap(before, after, 65_536);
         if (shared > 0) {
             operations.push(["t", path, before.length - shared]);
             if (after.length > shared)
-                operations.push(["a", path, after.slice(shared)]);
+                operations.push(["a", path, ownedSlice(after, shared)]);
             return true;
         }
     }