@openlfcp/shared-objects 0.2.0-beta.8 → 0.2.0

package/dist/sections/replica.d.ts

@@ -361,12 +361,6 @@ export declare class SectionReplica {
      * never merged; the changes that depend on it wait.
      */
     receiveChanges(items: readonly (Uint8Array | SectionUnit)[]): SectionReceiveResult;
-    /**
-     * Everything an editor projects, in one synchronous read of one revision:
-     * the title (and its concurrent values), each node, the visible order,
-     * and the problems to show. `revision` is the modelRevision of a commit
-     * receipt and the `base` of text.edit.
-     */
     snapshot(): SectionSnapshot;
     /**
      * The Task of a task node (§4.2: stored under `/objects/<id>`, the node's

package/dist/sections/replica.js

@@ -100,6 +100,8 @@ const S = (s) => new A.ImmutableString(s);
 const str = (v) => A.isImmutableString(v) ? v.toString() : typeof v === "string" ? v : undefined;
 const isListStyle = (s) => typeof s === "string" && LIST_STYLES.includes(s);
 const revisionOf = (doc) => [...A.getHeads(doc)].sort().join(",");
+/** `changes` without those of `batch` (by hash), in their order. */
+const withoutBatch = (changes, batch) => changes.filter((c) => !batch.has(A.decodeChange(c).hash));
 /** Rebuilds a section document from the changes it held before an aborted apply. */
 function restoreSection(changes, actor, revision) {
     let restored;
@@ -391,8 +393,29 @@ export class SectionReplica {
      * and the problems to show. `revision` is the modelRevision of a commit
      * receipt and the `base` of text.edit.
      */
+    /**
+     * The tree and snapshot derived from the document at one revision (its
+     * heads): both are frozen and depend on the document alone, so a read at
+     * the same revision returns them again. Any change to the document
+     * changes its heads, so every path that changes it (commit, apply,
+     * revert, receive, a rebuild) gives a new revision and a new derivation
+     * (soak #11: the status was derived again on every refresh).
+     */
+    #derived;
+    #derivedNow() {
+        const revision = revisionOf(this.#doc);
+        if (this.#derived?.revision !== revision)
+            this.#derived = { revision, tree: deriveTree(this.#doc) };
+        return this.#derived;
+    }
     snapshot() {
-        const tree = deriveTree(this.#doc);
+        const derived = this.#derivedNow();
+        if (derived.snapshot !== undefined)
+            return derived.snapshot;
+        derived.snapshot = this.#snapshotOf(derived.tree);
+        return derived.snapshot;
+    }
+    #snapshotOf(tree) {
         const root = this.#doc;
         const section = (root.section ?? {});
         const nodes = (root.nodes ?? {});
@@ -454,7 +477,7 @@ export class SectionReplica {
     }
     /** §7, §9, §14.3: the effective tree, hidden nodes and structural facts. */
     tree() {
-        return deriveTree(this.#doc);
+        return this.#derivedNow().tree;
     }
     /** The document heads, sorted, as one string. */
     revision() {
@@ -517,6 +540,9 @@ export class SectionReplica {
         if (A.getActorId(this.#doc) !== this.#actor)
             throw new Error("the document actor is not the §2 actor");
         const affected = new Set();
+        // The validation's own document, freed on every exit (#7: an Automerge
+        // document left to the garbage collector holds its whole history in
+        // wasm memory until the collector happens to run).
         let scratch = A.clone(this.#doc);
         // The validation of the document before the batch: nodes the batch
         // creates are valid by construction, so it is computed again only when
@@ -531,106 +557,159 @@ export class SectionReplica {
         const chunks = [[]];
         const used = { text: 0, nodes: 0 };
         let i = -1;
-        for (const step of steps) {
-            if (step.intent !== "text.continue")
-                i = Math.min(i + 1, intents.length - 1);
-            const cost = { text: 0, nodes: 0 };
-            const write = this.#prepare(scratch, state, step, i, affected, cost);
-            if (cost.text > AUTHORING_BUDGET.textOperations || cost.nodes > AUTHORING_BUDGET.createdNodes)
-                throw new SectionIntentError("OVER_BUDGET", `one intent is over the §16.2 budgets (${cost.text} Text operations, ${cost.nodes} nodes)`, i);
-            const current = chunks[chunks.length - 1];
-            if (current.length > 0 &&
-                (used.text + cost.text > AUTHORING_BUDGET.textOperations ||
-                    used.nodes + cost.nodes > AUTHORING_BUDGET.createdNodes)) {
-                chunks.push([write]);
-                used.text = cost.text;
-                used.nodes = cost.nodes;
-            }
-            else {
-                current.push(write);
-                used.text += cost.text;
-                used.nodes += cost.nodes;
+        try {
+            for (const step of steps) {
+                if (step.intent !== "text.continue")
+                    i = Math.min(i + 1, intents.length - 1);
+                const cost = { text: 0, nodes: 0 };
+                const write = this.#prepare(scratch, state, step, i, affected, cost);
+                if (cost.text > AUTHORING_BUDGET.textOperations ||
+                    cost.nodes > AUTHORING_BUDGET.createdNodes)
+                    throw new SectionIntentError("OVER_BUDGET", `one intent is over the §16.2 budgets (${cost.text} Text operations, ${cost.nodes} nodes)`, i);
+                const current = chunks[chunks.length - 1];
+                if (current.length > 0 &&
+                    (used.text + cost.text > AUTHORING_BUDGET.textOperations ||
+                        used.nodes + cost.nodes > AUTHORING_BUDGET.createdNodes)) {
+                    chunks.push([write]);
+                    used.text = cost.text;
+                    used.nodes = cost.nodes;
+                }
+                else {
+                    current.push(write);
+                    used.text += cost.text;
+                    used.nodes += cost.nodes;
+                }
+                scratch = A.change(scratch, { time: 0 }, write);
+                if (step.intent === "section.create" || step.intent === "section.mark_ready")
+                    state.v = undefined;
+                // Only creations keep every verified ancestor chain as it was.
+                if (!KEEPS_CHAINS.has(step.intent))
+                    state.chainOk.clear();
             }
-            scratch = A.change(scratch, { time: 0 }, write);
-            if (step.intent === "section.create" || step.intent === "section.mark_ready")
-                state.v = undefined;
-            // Only creations keep every verified ancestor chain as it was.
-            if (!KEEPS_CHAINS.has(step.intent))
-                state.chainOk.clear();
+        }
+        finally {
+            A.free(scratch);
         }
         const message = intents.map((x) => x.intent).join(",");
         const before = A.getHeads(this.#doc);
-        // On a clone: A.change outdates the handle it is given, and this
-        // replica keeps its own until apply().
-        let next = A.clone(this.#doc, { actor: this.#actor });
-        const parts = [];
-        const partChanges = [];
-        for (const chunk of chunks) {
-            if (chunk.length === 0)
-                continue;
-            const heads = A.getHeads(next).join();
-            next = A.change(next, { message, time: 0 }, (d) => {
-                for (const w of chunk)
-                    w(d);
-            });
-            if (A.getHeads(next).join() === heads)
-                continue;
-            const bytes = A.getLastLocalChange(next);
-            let checked;
-            try {
-                checkChangeExpansion(bytes);
-                checked = checkChange(bytes);
-            }
-            catch (e) {
-                throw new SectionIntentError("OVER_BUDGET", `a change of the batch is larger than one change may be (SOP §11.1: ${e.message})`);
+        // The batch's changes are made on a fork with this replica's §2 actor;
+        // apply() gives #doc the same changes by applyChanges, so #doc keeps its
+        // one Automerge document. (Adopting the fork as #doc kept, through each
+        // object the new document shared with the old one, one old document
+        // alive per unchanged node: a section's memory grew with the number of
+        // Tasks times its history, #7.) The fork is freed on every exit.
+        let work = A.clone(this.#doc, { actor: this.#actor });
+        let handedOver = false;
+        try {
+            const parts = [];
+            const partChanges = [];
+            for (const chunk of chunks) {
+                if (chunk.length === 0)
+                    continue;
+                const heads = A.getHeads(work).join();
+                work = A.change(work, { message, time: 0 }, (d) => {
+                    for (const w of chunk)
+                        w(d);
+                });
+                if (A.getHeads(work).join() === heads)
+                    continue;
+                const bytes = A.getLastLocalChange(work);
+                let checked;
+                try {
+                    checkChangeExpansion(bytes);
+                    checked = checkChange(bytes);
+                }
+                catch (e) {
+                    throw new SectionIntentError("OVER_BUDGET", `a change of the batch is larger than one change may be (SOP §11.1: ${e.message})`);
+                }
+                partChanges.push(checked);
+                parts.push(Object.freeze({
+                    change: checked.bytes,
+                    plaintext: frameProfilePayload(checked.bytes),
+                    hash: checked.hash,
+                    seq: checked.seq,
+                }));
             }
-            partChanges.push(checked);
-            parts.push(Object.freeze({
-                change: checked.bytes,
-                plaintext: frameProfilePayload(checked.bytes),
-                hash: checked.hash,
-                seq: checked.seq,
-            }));
-        }
-        if (parts.length === 0 || A.getHeads(next).join() === before.join())
-            return null;
-        const last = parts[parts.length - 1];
-        const change = Object.freeze({
-            intents: Object.freeze(intents.map((x) => x.intent)),
-            parts: Object.freeze(parts),
-            ...last,
-            affectedNodeIds: Object.freeze([...affected].sort()),
-            modelRevision: revisionOf(next),
-        });
-        const base = revisionOf(this.#doc);
-        const prior = this.#doc;
-        const priorSeqs = this.#seqs === undefined ? undefined : new Map(this.#seqs);
-        let applied = false;
-        return Object.freeze({
-            change,
-            apply: () => {
-                if (applied)
-                    return;
-                if (revisionOf(this.#doc) !== base)
-                    throw new Error("the replica changed since the batch was staged; stage it again");
-                this.#doc = next;
-                if (this.#seqs !== undefined && last.seq > (this.#seqs.get(this.#actor) ?? 0))
-                    this.#seqs.set(this.#actor, last.seq);
-                for (const c of partChanges)
-                    this.#refs?.add(c.hash, parsedOf(c));
-                applied = true;
-            },
-            revert: () => {
-                if (!applied)
+            if (parts.length === 0 || A.getHeads(work).join() === before.join())
+                return null;
+            const last = parts[parts.length - 1];
+            const change = Object.freeze({
+                intents: Object.freeze(intents.map((x) => x.intent)),
+                parts: Object.freeze(parts),
+                ...last,
+                affectedNodeIds: Object.freeze([...affected].sort()),
+                modelRevision: revisionOf(work),
+            });
+            const base = revisionOf(this.#doc);
+            const batch = new Set(partChanges.map((c) => c.hash));
+            const priorSeqs = this.#seqs === undefined ? undefined : new Map(this.#seqs);
+            const fork = work;
+            let forkFreed = false;
+            const freeFork = () => {
+                if (forkFreed)
                     return;
-                if (this.#doc !== next)
-                    throw new Error("the replica changed after the batch was applied; it cannot be reverted");
-                this.#doc = prior;
-                this.#seqs = priorSeqs === undefined ? undefined : new Map(priorSeqs);
-                this.#refs = null;
-                applied = false;
-            },
-        });
+                forkFreed = true;
+                A.free(fork);
+            };
+            let applied = false;
+            handedOver = true;
+            return Object.freeze({
+                change,
+                apply: () => {
+                    if (applied)
+                        return;
+                    if (forkFreed)
+                        throw new Error("the batch could not be applied before; stage it again");
+                    if (revisionOf(this.#doc) !== base)
+                        throw new Error("the replica changed since the batch was staged; stage it again");
+                    try {
+                        try {
+                            this.#doc = A.applyChanges(this.#doc, partChanges.map((c) => c.bytes))[0];
+                            if (revisionOf(this.#doc) !== change.modelRevision)
+                                throw new Error("the batch did not apply as it was staged");
+                        }
+                        catch (e) {
+                            if (isWasmTrap(e))
+                                throw e;
+                            // The document is not trusted after a failed apply: rebuilt from
+                            // the changes the fork held before the batch, never from it.
+                            this.#doc = this.#rebuilt(withoutBatch(A.getAllChanges(fork), batch), base);
+                            throw e;
+                        }
+                    }
+                    finally {
+                        freeFork();
+                    }
+                    if (this.#seqs !== undefined && last.seq > (this.#seqs.get(this.#actor) ?? 0))
+                        this.#seqs.set(this.#actor, last.seq);
+                    for (const c of partChanges)
+                        this.#refs?.add(c.hash, parsedOf(c));
+                    applied = true;
+                },
+                revert: () => {
+                    if (!applied)
+                        return;
+                    if (revisionOf(this.#doc) !== change.modelRevision)
+                        throw new Error("the replica changed after the batch was applied; it cannot be reverted");
+                    // The document as it was before the batch: its changes without the batch's.
+                    this.#doc = this.#rebuilt(withoutBatch(A.getAllChanges(this.#doc), batch), base);
+                    this.#seqs = priorSeqs === undefined ? undefined : new Map(priorSeqs);
+                    this.#refs = null;
+                    applied = false;
+                },
+            });
+        }
+        finally {
+            if (!handedOver)
+                A.free(work);
+        }
+    }
+    /** A document of exactly `changes`, with this replica's §2 actor, at `revision` (checked). */
+    #rebuilt(changes, revision) {
+        const doc = restoreSection(changes, this.#actor, revision);
+        if (A.getActorId(doc) !== this.#actor)
+            throw new Error("the section replica could not be restored: another actor");
+        return doc;
     }
     /**
      * Checks one intent against `doc`, the document with the batch so far,

package/dist/sections/tree.js

@@ -182,19 +182,50 @@ export function deriveTree(doc, validation = validateSection(doc)) {
         validation,
     });
 }
+const summarise = (bytes) => {
+    const c = A.decodeChange(bytes);
+    return {
+        hash: c.hash,
+        deps: c.deps,
+        actor: c.actor,
+        seq: c.seq,
+        ops: c.ops.map((op) => {
+            const o = op;
+            return { obj: o.obj, action: o.action, key: o.key, value: o.value };
+        }),
+    };
+};
 /**
- * §9: the hidden nodes with content changes concurrent with a deletion of
- * the node or of an ancestor, from the change history. A change deletes
- * when the last lifecycle value it writes to an owner (a Task node's Task,
- * another node itself) is "deleted"; content is a node's creation, an
- * operation on its Text, a Task's title or status, or a move of the node
- * (a write to its `placement` register — node.move or node.resolve_placement,
- * §8). Two changes are concurrent when neither is in the other's dependencies.
- * Only a deletion the lifecycle register still holds counts: one a later write
- * to the same register depends on is superseded (deleting the node again clears
- * the attention a concurrent edit raised), while two concurrent deletions both
- * count (baseline.9).
+ * The decoded history of the documents read last, by their heads (a few,
+ * least recently used last out). A change is the same wherever it is, so a
+ * later revision of the same document decodes only the changes since a
+ * revision read before, whose heads it has: decoding the whole history on
+ * every new revision was linear in it, per pass (soak #11).
  */
+const histories = new Map();
+const HISTORIES = 16;
+function historyOf(doc) {
+    const key = [...A.getHeads(doc)].sort().join(",");
+    const known = histories.get(key);
+    if (known !== undefined) {
+        histories.delete(key);
+        histories.set(key, known);
+        return known;
+    }
+    let out;
+    for (const [k, list] of [...histories].reverse()) {
+        const heads = k === "" ? [] : k.split(",");
+        if (A.getMissingDeps(doc, heads).length > 0)
+            continue;
+        out = [...list, ...A.getChangesSince(doc, heads).map(summarise)];
+        break;
+    }
+    out ??= A.getAllChanges(doc).map(summarise);
+    histories.set(key, out);
+    while (histories.size > HISTORIES)
+        histories.delete(histories.keys().next().value);
+    return out;
+}
 function retainedEdits(doc, hidden, parentOf, sectionId) {
     const root = doc;
     const nodes = (root.nodes ?? {});
@@ -226,13 +257,15 @@ function retainedEdits(doc, hidden, parentOf, sectionId) {
         }
     }
     const deps = new Map();
+    // Each change's actor and sequence number, for its vector clock below.
+    const author = new Map();
     const deletes = [];
     // Every lifecycle write (any value), to tell whether a deletion is still held.
     const lifecycleWrites = [];
     const edits = [];
-    for (const bytes of A.getAllChanges(doc)) {
-        const change = A.decodeChange(bytes);
+    for (const change of historyOf(doc)) {
         deps.set(change.hash, change.deps);
+        author.set(change.hash, { actor: change.actor, seq: change.seq });
         const lastLifecycle = new Map();
         const touched = new Set();
         for (const op of change.ops) {
@@ -266,7 +299,51 @@ function retainedEdits(doc, hidden, parentOf, sectionId) {
     }
     if (deletes.length === 0 || edits.length === 0)
         return [];
-    /** Every change `hash` depends on, transitively, memoized. */
+    /**
+     * Each change's vector clock: the highest sequence number of every actor
+     * in its causal history, itself included. When each change of an actor
+     * has that actor's previous change in its history (as Automerge writes
+     * them), `a` is in the history of `b` exactly when b's clock has a's actor
+     * at a's sequence or later: O(history × actors), where a set of ancestors
+     * per change was O(history²) (soak #11: seconds per pass after ~3,000
+     * changes in a section with deleted Tasks). A history where that does not
+     * hold (a change made without its actor's previous one), or one with more
+     * than 32 actors, falls back to the exact sets.
+     */
+    const clocks = new Map();
+    // A clock holds an entry per actor: with many actors (a hostile or unusual
+    // history), the exact sets are cheaper.
+    let regular = new Set([...author.values()].map((x) => x.actor)).size <= 32;
+    for (const start of regular ? deps.keys() : []) {
+        const stack = [start];
+        while (stack.length > 0) {
+            const h = stack[stack.length - 1];
+            if (clocks.has(h)) {
+                stack.pop();
+                continue;
+            }
+            const pending = (deps.get(h) ?? []).filter((d) => deps.has(d) && !clocks.has(d));
+            if (pending.length > 0) {
+                stack.push(...pending);
+                continue;
+            }
+            stack.pop();
+            const clock = new Map();
+            for (const d of deps.get(h) ?? [])
+                for (const [actor, seq] of clocks.get(d) ?? [])
+                    if (seq > (clock.get(actor) ?? 0))
+                        clock.set(actor, seq);
+            const me = author.get(h);
+            if (me !== undefined) {
+                if ((clock.get(me.actor) ?? 0) !== me.seq - 1)
+                    regular = false;
+                if (me.seq > (clock.get(me.actor) ?? 0))
+                    clock.set(me.actor, me.seq);
+            }
+            clocks.set(h, clock);
+        }
+    }
+    /** Every change `hash` depends on, transitively, memoized (the exact fallback). */
     const ancestry = new Map();
     const ancestorsOf = (hash) => {
         const known = ancestry.get(hash);
@@ -286,14 +363,23 @@ function retainedEdits(doc, hidden, parentOf, sectionId) {
         ancestry.set(hash, out);
         return out;
     };
-    const concurrent = (a, b) => a !== b && !ancestorsOf(a).has(b) && !ancestorsOf(b).has(a);
+    /** Whether change `a` is in the causal history of change `b` (a ≠ b). */
+    const before = (a, b) => {
+        if (a === b)
+            return false;
+        if (!regular)
+            return ancestorsOf(b).has(a);
+        const me = author.get(a);
+        return me !== undefined && (clocks.get(b)?.get(me.actor) ?? 0) >= me.seq;
+    };
+    const concurrent = (a, b) => a !== b && !before(a, b) && !before(b, a);
     // §9 (baseline.9): a deletion counts only while the lifecycle register still
     // holds it. A later write to the same register — one that has the deletion in
     // its dependencies — supersedes it, so deleting a node again clears the
     // attention a concurrent edit raised. Two concurrent deletions supersede
     // neither, so both still count (SS86); the writes come from each change's
     // operations, which also keeps a deletion merged after a concurrent one.
-    const heldDeletes = deletes.filter((d) => !lifecycleWrites.some((w) => w.node === d.node && w.hash !== d.hash && ancestorsOf(w.hash).has(d.hash)));
+    const heldDeletes = deletes.filter((d) => !lifecycleWrites.some((w) => w.node === d.node && w.hash !== d.hash && before(d.hash, w.hash)));
     const deletesOf = new Map();
     for (const d of heldDeletes)
         deletesOf.set(d.node, [...(deletesOf.get(d.node) ?? []), d.hash]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlfcp/shared-objects",
-  "version": "0.2.0-beta.8",
+  "version": "0.2.0",
   "description": "SHARED-OBJECTS-PROFILE-01 (org.openlfcp.shared-objects.v1) implementation.",
   "keywords": [
     "openlfcp",
@@ -48,13 +48,13 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "beta"
+    "tag": "latest"
   },
   "dependencies": {
     "@automerge/automerge": "3.5.0",
     "fflate": "0.8.3",
-    "@openlfcp/core": "^0.2.0-beta.8",
-    "@openlfcp/crypto": "^0.2.0-beta.8"
+    "@openlfcp/core": "^0.2.0",
+    "@openlfcp/crypto": "^0.2.0"
   },
   "devDependencies": {
     "fast-check": "4.10.2"