@openlfcp/shared-objects 0.1.4 → 0.2.0-beta.1

package/dist/replica.js

@@ -1,11 +1,12 @@
 import * as A from "@automerge/automerge";
 import { fromHex, LfcpError, toHex, } from "@openlfcp/core";
-import { checkChange, checkSaveHeader, parsedOf, unframeChange, unframeSnapshot, } from "./automerge-bytes.js";
-import { checkSnapshotExpansion, MAX_DOCUMENT_DEPTH, SNAPSHOT_LIMITS_FLOOR, } from "./chunk-limits.js";
+import { checkChange, checkSaveHeader, parsedOf, unframeChange, unframeSnapshot, } from "./admission/framing.js";
+import { checkSnapshotExpansion, MAX_DOCUMENT_DEPTH, SNAPSHOT_LIMITS_FLOOR, } from "./admission/limits.js";
+import { referenceHistoryOf } from "./admission/references.js";
+import { admitBatch, admitChange } from "./admission/sequence.js";
 /** The decoded actions that create an object (§11.2). */
 const MAKE_ACTIONS = new Set(["makeMap", "makeList", "makeText", "makeTable"]);
 import { ProfileInvalidError } from "./profile-invalid.js";
-import { referenceHistoryOf } from "./references.js";
 import { ProfileError, parseTask } from "./task.js";
 import { firstPerField, isMap, objectProblems, pointerToken, validateRoot, } from "./validate.js";
 import { deriveActorId, frameProfilePayload, PROFILE_ID } from "./values.js";
@@ -56,8 +57,6 @@ export function resolveFieldConflict(id, field, value) {
         throw new LfcpError("UNSUPPORTED_VALUE", `only a date field can be cleared (§36)`);
     return Object.freeze({ intent: "task.resolve_field_conflict", id, field, value });
 }
-/** §11.4: a refusal for a change whose operations refer outside its causal history. */
-const referenceError = (rule) => new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", `the change's operations refer outside its causal history (§11.4 ${rule})`);
 /** §21: two concurrent objects under one Object ID: OBJECT_ID_COLLISION, a profile error of its own, not PROFILE_INVALID. */
 export class ObjectIdCollisionError extends LfcpError {
     objectId;
@@ -221,6 +220,104 @@ function conflictValueProblems(object, key) {
     }
     return out;
 }
+/**
+ * §99: the Task under `id` of `objects` (the document's `objects` map) with
+ * conflict metadata, or undefined if there is no object or it is not a Task.
+ * Shared by the Shared Objects and the Shared Sections replicas.
+ */
+export function taskView(doc, objects, id) {
+    const stored = objects?.[id];
+    if (objects === undefined || !isMap(stored))
+        return undefined;
+    const object = stored;
+    if (plain(object.type) !== "task")
+        return undefined;
+    const collided = A.getConflicts(objects, id) !== undefined;
+    const problems = storedObjectProblems(doc, object, id);
+    const parsed = parseTask(plain(object), id);
+    const field = (f) => {
+        const values = valuesOf(object, f).map(plain).sort(byJson);
+        return Object.freeze({
+            value: f in object ? plain(object[f]) : undefined,
+            values: Object.freeze(values),
+            conflicted: values.length > 1,
+        });
+    };
+    const keys = (f) => isMap(plain(object[f])) ? Object.keys(plain(object[f])).sort() : [];
+    return Object.freeze({
+        id,
+        status: collided ? "object_id_collision" : problems.length > 0 ? "profile_invalid" : "ready",
+        problems: Object.freeze(problems),
+        task: parsed.valid ? parsed.task : undefined,
+        fields: Object.freeze(Object.fromEntries(SCALAR_FIELDS.map((f) => [f, field(f)]))),
+        tags: Object.freeze(keys("tags")),
+        assignees: Object.freeze(keys("assignees")),
+    });
+}
+/**
+ * §74.1 problems of one object as stored at `/objects/<id>` of `doc`: its
+ * logical values, every collaborative Text in it (§30) and every concurrent
+ * value of its scalar registers (§45), one diagnostic per field. Shared by
+ * every profile whose Tasks are SOP Tasks (SHARED-SECTIONS-PROFILE-01 §2).
+ */
+export function storedObjectProblems(doc, stored, id) {
+    const at = `/objects/${pointerToken(id)}`;
+    const all = [
+        ...objectProblems(plain(stored), id).filter((p) => p.pointer.startsWith(at)),
+        ...textProblems(doc, stored, id),
+        ...conflictValueProblems(stored, id),
+    ];
+    // §74.1: one diagnostic per field, the first in table order over every value.
+    return firstPerField(all.filter((p, i) => all.findIndex((q) => q.pointer === p.pointer && q.diagnostic === p.diagnostic) === i), at);
+}
+/**
+ * Checks one Task intent against `objects`, the stored objects map of
+ * `doc`, before anything is written: §21 no reuse of an Object ID on
+ * create, §74 the Task after the intent is valid, and no Text left in a
+ * field it writes. Throws ProfileError or ObjectIdCollisionError. Shared by
+ * every profile whose Tasks are SOP Tasks (SHARED-SECTIONS-PROFILE-01 §2).
+ */
+export function prepareTaskIntent(doc, objects, intent) {
+    if (intent.intent === "task.create") {
+        const task = intent.task;
+        const id = String(task.id);
+        // §21: a local create never reuses an Object ID this replica already holds.
+        if (id in objects)
+            throw new ObjectIdCollisionError(id);
+        const problems = objectProblems(task, id);
+        if (problems.length > 0)
+            throw new ProfileError(problems);
+        return Object.freeze({
+            id,
+            perform: (o) => {
+                o[id] = scalarize(task, 0); // §53: the whole Task in one change (the object map is depth 0)
+            },
+        });
+    }
+    const id = intent.id;
+    const stored = objects[id];
+    if (!isMap(stored))
+        throw new ProfileError(objectProblems(undefined, id));
+    if (A.getConflicts(objects, id) !== undefined)
+        throw new ObjectIdCollisionError(id);
+    const object = stored;
+    const writes = writesOf(intent);
+    const touched = new Set(writes.map((w) => (w.op === "put" || w.op === "delete" ? w.field : w.set)));
+    const next = candidate(plain(object), writes);
+    const problems = [
+        ...(next.type === "task"
+            ? objectProblems(next, id)
+            : [problem("INVALID_FIELD_TYPE", `/objects/${pointerToken(id)}/type`, "not a Task (§25)")]),
+        // Text in a field this intent writes is replaced by the write.
+        ...textProblems(doc, object, id).filter((p) => !touched.has(unescapeToken(p.pointer.split("/")[3] ?? ""))),
+    ];
+    if (problems.length > 0)
+        throw new ProfileError(problems);
+    return Object.freeze({
+        id,
+        perform: (o) => perform(o[id], writes),
+    });
+}
 function writesOf(intent) {
     const put = (field, value) => ({ op: "put", field, value });
     const del = (field) => ({ op: "delete", field });
@@ -314,7 +411,8 @@ const actorHex = (opts) => toHex(deriveActorId(opts.resource, opts.principal));
  * the change refused): it is rethrown as it is, never turned into
  * INVALID_AUTOMERGE_BYTES, so a crash-loop breaker sees it.
  */
-function isWasmTrap(e) {
+/** A wasm trap (RuntimeError, or a terminated module): fatal, not a refusable change. */
+export function isWasmTrap(e) {
     const trap = globalThis
         .WebAssembly?.RuntimeError;
     if (trap !== undefined && e instanceof trap)
@@ -330,7 +428,19 @@ function isWasmTrap(e) {
  * is: the module is dead, and only a restart recovers. Exported for tests.
  */
 export function applyChecked(doc, bytes) {
+    // The change's good state, captured before the apply: a change the engine
+    // aborts on (D1: a makeTable it cannot write back) stays in the document's
+    // graph (it does not save loadably) or aborts the apply mid-way, so the
+    // document after the error is not a reliable restore source. Rebuilding
+    // from the changes it held before the apply always gives its prior state.
+    //
+    // Do NOT "simplify" this by applying to A.clone(doc) and returning the
+    // original on error: A.clone(doc) gives the clone a NEW actor id, which
+    // breaks local writes (§8 actor check) and changes merge/convergence.
+    // Apply to `doc` itself and restore from `good` only on the error path.
     const before = [...A.getHeads(doc)].sort().join();
+    const actor = A.getActorId(doc);
+    const good = A.getAllChanges(doc);
     try {
         return { next: A.applyChanges(doc, [bytes])[0] };
     }
@@ -338,18 +448,22 @@ export function applyChecked(doc, bytes) {
         if (isWasmTrap(e))
             throw e;
         const error = e instanceof Error ? e : new Error(String(e));
-        let restored;
-        try {
-            [restored] = A.applyChanges(A.init({ actor: A.getActorId(doc) }), A.getAllChanges(doc));
-        }
-        catch (r) {
-            throw new Error(`the replica could not be restored after an Automerge error: ${String(r)}`);
-        }
-        if ([...A.getHeads(restored)].sort().join() !== before)
-            throw new Error("the replica could not be restored after an Automerge error: heads differ");
-        return { restored, error };
+        return { restored: restoreFrom(good, actor, before), error };
     }
 }
+/** Rebuilds a document from the changes it held before an aborted apply (never from the aborted one). */
+function restoreFrom(good, actor, before) {
+    let restored;
+    try {
+        [restored] = A.applyChanges(A.init({ actor }), [...good]);
+    }
+    catch (r) {
+        throw new Error(`the replica could not be restored after an Automerge error: ${String(r)}`);
+    }
+    if ([...A.getHeads(restored)].sort().join() !== before)
+        throw new Error("the replica could not be restored after an Automerge error: heads differ");
+    return restored;
+}
 /**
  * applyChecked for a batch of admitted changes, in one engine call. On any
  * engine error the handle is dropped and the document as it was before is
@@ -357,7 +471,12 @@ export function applyChecked(doc, bytes) {
  * heads it had. Exported for tests.
  */
 export function applyBatchChecked(doc, batch) {
-    const heads = A.getHeads(doc);
+    // The changes held before the batch, the restore source (see applyChecked):
+    // on an abort the caller re-applies the batch one change at a time to isolate
+    // the bad one.
+    const before = [...A.getHeads(doc)].sort().join();
+    const actor = A.getActorId(doc);
+    const good = A.getAllChanges(doc);
     try {
         return {
             next: A.applyChanges(doc, batch.map((c) => c.bytes))[0],
@@ -367,23 +486,9 @@ export function applyBatchChecked(doc, batch) {
         if (isWasmTrap(e))
             throw e;
         const error = e instanceof Error ? e : new Error(String(e));
-        return { restored: restoreWithout(doc, batch, heads), error };
+        return { restored: restoreFrom(good, actor, before), error };
     }
 }
-function restoreWithout(doc, batch, heads) {
-    const out = new Set(batch.map((c) => c.hash));
-    const kept = A.getAllChanges(doc).filter((c) => !out.has(A.decodeChange(c).hash));
-    let restored;
-    try {
-        [restored] = A.applyChanges(A.init({ actor: A.getActorId(doc) }), kept);
-    }
-    catch (r) {
-        throw new Error(`the replica could not be restored after an Automerge error: ${String(r)}`);
-    }
-    if ([...A.getHeads(restored)].sort().join() !== [...heads].sort().join())
-        throw new Error("the replica could not be restored after an Automerge error: heads differ");
-    return restored;
-}
 function loadFailure(e, what) {
     if (e instanceof LfcpError)
         throw e;
@@ -397,8 +502,6 @@ export class SharedObjectsReplica {
     #actor;
     #minSeq;
     #doc;
-    /** §11.4: the document's changes as references read them; null to build again from the document. */
-    #refs = null;
     /** Highest sequence seen per actor (hex). */
     #seqs = new Map();
     /** §11.2: known object depths (object ID → depth below the root), filled as objects appear. */
@@ -409,6 +512,8 @@ export class SharedObjectsReplica {
      * at the view's heads, so the state before a change cannot be asked later.
      */
     #conflicted = new Map();
+    /** §11.4: the document's changes as references read them; null to build again from the document. */
+    #refs = null;
     constructor(doc, opts) {
         this.resource = opts.resource;
         this.#principal = opts.principal;
@@ -428,6 +533,15 @@ export class SharedObjectsReplica {
      * same batch). Refuses an object deeper than MAX_DOCUMENT_DEPTH, or one
      * written into an object the document does not have, before the engine.
      */
+    /** The document as the admission module reads it (§14.1). */
+    #sequences() {
+        this.#refs ??= referenceHistoryOf(this.#doc);
+        return {
+            hasChange: (hash) => A.hasHeads(this.#doc, [hash]),
+            latestSeq: (actor) => this.#seqs.get(actor) ?? 0,
+            references: this.#refs,
+        };
+    }
     #createdDepths(change, prior) {
         const decoded = A.decodeChange(change.bytes);
         const created = new Map();
@@ -682,46 +796,9 @@ export class SharedObjectsReplica {
             collisions: Object.freeze(this.collisions()),
         });
     }
-    #objectProblems(id, stored) {
-        const at = `/objects/${pointerToken(id)}`;
-        const all = [
-            ...objectProblems(plain(stored), id).filter((p) => p.pointer.startsWith(at)),
-            ...textProblems(this.#doc, stored, id),
-            ...conflictValueProblems(stored, id),
-        ];
-        // §74.1: one diagnostic per field, the first in table order over every value.
-        return firstPerField(all.filter((p, i) => all.findIndex((q) => q.pointer === p.pointer && q.diagnostic === p.diagnostic) === i), at);
-    }
     /** §99: the Task under `id` with conflict metadata, or undefined if there is no object or it is not a Task. */
     task(id) {
-        const objects = this.#objects();
-        const stored = objects?.[id];
-        if (objects === undefined || !isMap(stored))
-            return undefined;
-        const object = stored;
-        if (plain(object.type) !== "task")
-            return undefined;
-        const collided = A.getConflicts(objects, id) !== undefined;
-        const problems = this.#objectProblems(id, object);
-        const parsed = parseTask(plain(object), id);
-        const field = (f) => {
-            const values = valuesOf(object, f).map(plain).sort(byJson);
-            return Object.freeze({
-                value: f in object ? plain(object[f]) : undefined,
-                values: Object.freeze(values),
-                conflicted: values.length > 1,
-            });
-        };
-        const keys = (f) => isMap(plain(object[f])) ? Object.keys(plain(object[f])).sort() : [];
-        return Object.freeze({
-            id,
-            status: collided ? "object_id_collision" : problems.length > 0 ? "profile_invalid" : "ready",
-            problems: Object.freeze(problems),
-            task: parsed.valid ? parsed.task : undefined,
-            fields: Object.freeze(Object.fromEntries(SCALAR_FIELDS.map((f) => [f, field(f)]))),
-            tags: Object.freeze(keys("tags")),
-            assignees: Object.freeze(keys("assignees")),
-        });
+        return taskView(this.#doc, this.#objects(), id);
     }
     /**
      * Applies one intent as exactly one Automerge change (§10) and returns it,
@@ -735,39 +812,8 @@ export class SharedObjectsReplica {
         const rootProblems = validateRoot(this.root()).problems.filter((p) => !p.pointer.startsWith("/objects/"));
         if (objects === undefined || rootProblems.length > 0)
             throw new ProfileError(rootProblems.length > 0 ? rootProblems : [problem("INVALID_ROOT", "/", "no root (§15)")]);
-        if (intent.intent === "task.create") {
-            const task = intent.task;
-            const id = String(task.id);
-            // §21: a local create never reuses an Object ID this replica already holds.
-            if (id in objects)
-                throw new ObjectIdCollisionError(id);
-            const problems = objectProblems(task, id);
-            if (problems.length > 0)
-                throw new ProfileError(problems);
-            return this.#commit(intent.intent, [id], (d) => {
-                d.objects[id] = scalarize(task, 0); // §53: the whole Task in one change (the object map is depth 0)
-            });
-        }
-        const id = intent.id;
-        const stored = objects[id];
-        if (!isMap(stored))
-            throw new ProfileError(objectProblems(undefined, id));
-        if (A.getConflicts(objects, id) !== undefined)
-            throw new ObjectIdCollisionError(id);
-        const object = stored;
-        const writes = writesOf(intent);
-        const touched = new Set(writes.map((w) => (w.op === "put" || w.op === "delete" ? w.field : w.set)));
-        const next = candidate(plain(object), writes);
-        const problems = [
-            ...(next.type === "task"
-                ? objectProblems(next, id)
-                : [problem("INVALID_FIELD_TYPE", `/objects/${pointerToken(id)}/type`, "not a Task (§25)")]),
-            // Text in a field this intent writes is replaced by the write.
-            ...textProblems(this.#doc, object, id).filter((p) => !touched.has(unescapeToken(p.pointer.split("/")[3] ?? ""))),
-        ];
-        if (problems.length > 0)
-            throw new ProfileError(problems);
-        return this.#commit(intent.intent, [id], (d) => perform(d.objects[id], writes));
+        const prepared = prepareTaskIntent(this.#doc, objects, intent);
+        return this.#commit(intent.intent, [prepared.id], (d) => prepared.perform(d.objects));
     }
     #commit(message, ids, fn) {
         if (!this.writable)
@@ -800,8 +846,8 @@ export class SharedObjectsReplica {
         if (checked.seq !== this.actorSeq + 1)
             throw new LfcpError("SEQUENCE_REUSE", `actor sequence ${checked.seq} after ${this.actorSeq} (§9)`);
         this.#doc = next;
-        this.#refs?.add(checked.hash, parsedOf(checked));
         this.#noteSeq(checked.actor, checked.seq);
+        this.#refs?.add(checked.hash, parsedOf(checked));
         for (const [id, d] of created)
             this.#depths.set(id, d);
         return Object.freeze({
@@ -846,85 +892,19 @@ export class SharedObjectsReplica {
             seen.add(checked.hash);
             all.push(checked);
         }
-        const index = new Map(all.map((c, i) => [c.hash, i]));
-        const blocking = all.map(() => 0);
-        const unreachable = all.map(() => false);
-        const children = new Map();
-        all.forEach((c, i) => {
-            for (const d of c.deps) {
-                if (A.hasHeads(this.#doc, [d]))
-                    continue;
-                if (index.has(d)) {
-                    blocking[i] = blocking[i] + 1;
-                    children.set(d, [...(children.get(d) ?? []), i]);
-                }
-                else
-                    unreachable[i] = true;
-            }
-        });
-        const seqs = new Map();
-        const latest = (actor) => seqs.get(actor) ?? this.#seqs.get(actor) ?? 0;
-        const admitted = [];
+        // §11.1, §14.1 (the admission module both profiles share), then §11.2:
+        // the depths of the objects a change creates, given the document and
+        // the batch so far.
         const batchDepths = new Map();
-        const duplicates = [];
-        const done = all.map(() => false);
-        const ready = all.flatMap((_, i) => (blocking[i] === 0 && !unreachable[i] ? [i] : []));
-        for (let k = 0; k < ready.length; k++) {
-            const i = ready[k];
-            const c = all[i];
-            done[i] = true;
-            if (A.hasHeads(this.#doc, [c.hash]))
-                duplicates.push(c);
-            else if (c.seq <= latest(c.actor)) {
-                refused.push({
-                    change: c,
-                    error: new LfcpError("ACTOR_EQUIVOCATION", `actor ${c.actor} sequence ${c.seq} already has a different change (§26.2)`),
-                });
-                continue;
-            }
-            else if (c.otherActors.some((a) => latest(a) === 0)) {
-                refused.push({
-                    change: c,
-                    error: new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", `the change names an actor unknown to this document (§11.1)`),
-                });
-                continue;
-            }
-            else if (c.seq !== latest(c.actor) + 1) {
-                refused.push({
-                    change: c,
-                    error: new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", `actor ${c.actor} sequence ${c.seq} skips sequence ${latest(c.actor) + 1} (§14.1)`),
-                });
-                continue;
-            }
-            else {
-                // §11.4: the operations refer only to the change's causal history.
-                const rule = this.#references().check(parsedOf(c));
-                if (rule !== null) {
-                    refused.push({ change: c, error: referenceError(rule) });
-                    continue;
-                }
-                // §11.2: the depths of the objects it creates, given the document and the batch so far.
-                let created;
-                try {
-                    created = this.#createdDepths(c, batchDepths);
-                }
-                catch (e) {
-                    refused.push({ change: c, error: e });
-                    continue;
-                }
-                for (const [id, d] of created)
-                    batchDepths.set(id, d);
-                seqs.set(c.actor, c.seq);
-                this.#references().add(c.hash, parsedOf(c));
-                admitted.push(c);
-            }
-            for (const child of children.get(c.hash) ?? []) {
-                blocking[child] = blocking[child] - 1;
-                if (blocking[child] === 0 && !unreachable[child])
-                    ready.push(child);
-            }
-        }
-        const waiting = all.filter((_, i) => !done[i]);
+        const decided = admitBatch(all, this.#sequences(), (c) => {
+            for (const [id, d] of this.#createdDepths(c, batchDepths))
+                batchDepths.set(id, d);
+        });
+        for (const r of decided.refused)
+            refused.push({ change: r.change, error: r.error });
+        const admitted = [...decided.admitted];
+        const duplicates = [...decided.duplicates];
+        const waiting = [...decided.waiting];
         const before = A.getHeads(this.#doc);
         let applied = admitted;
         if (admitted.length > 0) {
@@ -938,7 +918,7 @@ export class SharedObjectsReplica {
             }
             else {
                 this.#doc = batch.restored;
-                // The index already holds the batch: build it again from the restored document.
+                // The index already holds the batch (admitBatch adds what it admits).
                 this.#refs = null;
                 applied = [];
                 for (const c of admitted) {
@@ -968,40 +948,23 @@ export class SharedObjectsReplica {
             objects: Object.freeze(applied.length > 0 ? this.#objectChanges(before, "remote") : []),
         });
     }
-    /** The reference index of the document (§11.4), built once and kept with it. */
-    #references() {
-        this.#refs ??= referenceHistoryOf(this.#doc);
-        return this.#refs;
-    }
     #receive(change) {
-        if (A.hasHeads(this.#doc, [change.hash]))
+        // §11.1, §14.1 before Automerge sees it (the admission module both
+        // profiles share): Automerge 3.5.0 records a skipping change in its graph
+        // without its operations, so the document no longer saves loadably
+        // (automerge-rs 0.12 aborts), and aborts on an unknown actor. A taken
+        // sequence is an equivocation (or, for our own actor, a lost-state fork, §9).
+        const admission = admitChange(change, this.#sequences());
+        if (admission.kind === "duplicate")
             return Object.freeze({ status: "duplicate", change });
-        const missing = change.deps.filter((d) => !A.hasHeads(this.#doc, [d]));
-        if (missing.length > 0)
+        if (admission.kind === "missing")
             return Object.freeze({
                 status: "missing_dependencies",
                 change,
-                missing: Object.freeze(missing),
+                missing: admission.missing,
             });
-        // Same actor and sequence, different change: an equivocation (or, for our
-        // own actor, a lost-state fork, §9). Checked before Automerge sees it.
-        if (change.seq <= (this.#seqs.get(change.actor) ?? 0))
-            throw new LfcpError("ACTOR_EQUIVOCATION", `actor ${change.actor} sequence ${change.seq} already has a different change (§26.2)`);
-        // §14.1: with every dependency present, the sequence follows the
-        // actor's latest change. Checked before Automerge sees it: Automerge
-        // 3.5.0 records a skipping change in its graph without its operations
-        // and the document no longer saves loadably (automerge-rs 0.12 aborts).
-        // §11.1: every other actor of the change is already an actor of the
-        // document (Automerge aborts on an unknown one).
-        const unknown = change.otherActors.find((a) => !this.#seqs.has(a));
-        if (unknown !== undefined)
-            throw new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", `the change names actor ${unknown}, unknown to this document (§11.1)`);
-        if (change.seq !== (this.#seqs.get(change.actor) ?? 0) + 1)
-            throw new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", `actor ${change.actor} sequence ${change.seq} skips sequence ${(this.#seqs.get(change.actor) ?? 0) + 1} (§14.1)`);
-        // §11.4: the operations refer only to the change's causal history.
-        const rule = this.#references().check(parsedOf(change));
-        if (rule !== null)
-            throw referenceError(rule);
+        if (admission.kind === "held" || admission.kind === "invalid")
+            throw admission.error;
         // §11.2: no object deeper than MAX_DOCUMENT_DEPTH, before the engine.
         const created = this.#createdDepths(change, new Map());
         const before = A.getHeads(this.#doc);
@@ -1013,8 +976,8 @@ export class SharedObjectsReplica {
         }
         const next = applied.next;
         this.#doc = next;
-        this.#refs?.add(change.hash, parsedOf(change));
         this.#noteSeq(change.actor, change.seq);
+        this.#refs?.add(change.hash, parsedOf(change));
         for (const [id, d] of created)
             this.#depths.set(id, d);
         return Object.freeze({

package/dist/sections/admission.d.ts

@@ -0,0 +1,35 @@
+import * as A from "@automerge/automerge";
+import { LfcpError, type ResourceId } from "@openlfcp/core";
+import { type CheckedChange } from "../admission/framing.js";
+/**
+ * The structural admission of SHARED-SECTIONS-PROFILE-01 §14.1 (LFCP-02-017):
+ * rules A1–A5 and the readiness rule of §12.1, decided from the change's own
+ * operations and the objects they write into, in time linear in the change.
+ * It runs after the inherited SOP checks (framing, limits, actor, sequence)
+ * and before the engine applies anything; a refused change is never merged.
+ *
+ * Objects of the document are identified by their path from the root
+ * (Automerge objInfo); objects created by changes admitted earlier in the
+ * same batch, or earlier in the change, by the operation that creates them.
+ */
+/** §14.1: the admission diagnostics, in their order of precedence. */
+export declare const ADMISSION_ORDER: readonly ["INVALID_AUTOMERGE_BYTES", "CHANGE_ACTOR_MISMATCH", "CONTAINER_REPLACED", "CHILDREN_LIST_MUTATED", "PLACEMENT_NOT_ATOMIC", "IMMUTABLE_FIELD_MUTATED", "INVALID_FIELD_TYPE"];
+export type AdmissionDiagnostic = (typeof ADMISSION_ORDER)[number];
+/** A change refused at admission: PROFILE_INVALID with its §14.1 diagnostic. */
+export declare class SectionAdmissionError extends LfcpError {
+    readonly diagnostic: AdmissionDiagnostic;
+    constructor(diagnostic: AdmissionDiagnostic, message: string);
+}
+export declare class SectionAdmission {
+    #private;
+    constructor(doc: A.Doc<unknown>, resource: ResourceId);
+    /** The document with the admitted changes applied. */
+    get document(): A.Doc<unknown>;
+    /**
+     * Admits `change` against its causal history, or throws
+     * SectionAdmissionError. An admitted change is applied to the working
+     * document at once, so the changes after it in the batch see it.
+     */
+    accept(change: CheckedChange): void;
+}
+//# sourceMappingURL=admission.d.ts.map