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

package/dist/sections/replica.js

@@ -0,0 +1,1149 @@
+import * as A from "@automerge/automerge";
+import { generateObjectId, isObjectId, LfcpError, toHex, } from "@openlfcp/core";
+import { checkChange, checkSaveHeader, parsedOf, refusedChangeHash, } from "../admission/framing.js";
+import { checkChangeExpansion, checkSnapshotExpansion, SNAPSHOT_LIMITS_FLOOR, } from "../admission/limits.js";
+import { referenceHistoryOf } from "../admission/references.js";
+import { admitBatch } from "../admission/sequence.js";
+import { ProfileInvalidError } from "../profile-invalid.js";
+import { isWasmTrap, prepareTaskIntent, taskView, } from "../replica.js";
+import { frameProfilePayload, isUtcTimestamp, principalRef } from "../values.js";
+import { SectionAdmission } from "./admission.js";
+import { validateSection } from "./schema.js";
+import { deriveTree } from "./tree.js";
+import { deriveSectionActorId, LIST_STYLES, PARENT_KINDS, SECTIONS_PROFILE_ID, } from "./values.js";
+/** A batch refused before commit, with the intent it concerns (SDK-SECTIONS-INTEGRATION-01 §3.6). */
+export class SectionIntentError extends Error {
+    code;
+    /** The index of the refused intent in its batch. */
+    intentIndex;
+    /** The node the refusal concerns, when there is one. */
+    nodeId;
+    constructor(code, message, intentIndex, nodeId) {
+        super(message);
+        this.name = "SectionIntentError";
+        this.code = code;
+        this.intentIndex = intentIndex;
+        this.nodeId = nodeId;
+    }
+}
+/**
+ * §12, §12.3: splits what one change cannot carry. A Text edit or a new
+ * node's text over the Text budget continues in runs at its cursor; a
+ * batch that creates the section writes `ready` in its last change
+ * (§12.1), whatever number of changes it becomes.
+ */
+function expand(intents) {
+    const LIMIT = AUTHORING_BUDGET.textOperations;
+    const runs = (id, deleteCount, insert) => {
+        const out = [];
+        for (let left = deleteCount; left > 0; left -= LIMIT)
+            out.push({ intent: "text.continue", id, deleteCount: Math.min(left, LIMIT), insert: "" });
+        for (let at = 0; at < insert.length; at += LIMIT)
+            out.push({
+                intent: "text.continue",
+                id,
+                deleteCount: 0,
+                insert: insert.slice(at, at + LIMIT).join(""),
+            });
+        return out;
+    };
+    const out = [];
+    let ready = false;
+    for (const intent of intents) {
+        if (intent.intent === "section.create" && intent.ready !== false) {
+            out.push({ ...intent, ready: false });
+            ready = true;
+        }
+        else if (intent.intent === "text.edit" && intent.edits.length === 1) {
+            const e = intent.edits[0];
+            const insert = Array.from(e.insert);
+            if (e.deleteCount + insert.length <= LIMIT)
+                out.push(intent);
+            else {
+                const d0 = Math.min(e.deleteCount, LIMIT);
+                const i0 = insert.slice(0, LIMIT - d0);
+                out.push({ ...intent, edits: [{ index: e.index, deleteCount: d0, insert: i0.join("") }] });
+                out.push(...runs(intent.id, e.deleteCount - d0, insert.slice(i0.length)));
+            }
+        }
+        else if ((intent.intent === "paragraph.create" ||
+            intent.intent === "item.create" ||
+            intent.intent === "raw.create") &&
+            typeof intent.text === "string" &&
+            Array.from(intent.text).length > LIMIT) {
+            const text = Array.from(intent.text);
+            out.push({ ...intent, text: text.slice(0, LIMIT).join("") });
+            out.push(...runs(intent.id, 0, text.slice(LIMIT)));
+        }
+        else
+            out.push(intent);
+    }
+    if (ready)
+        out.push({ intent: "section.mark_ready" });
+    return out;
+}
+/** Intents after which every verified ancestor chain still holds. */
+const KEEPS_CHAINS = new Set([
+    "section.create",
+    "section.set_title",
+    "section.mark_ready",
+    "task.create_in_section",
+    "paragraph.create",
+    "item.create",
+    "raw.create",
+    "node.set_list_style",
+]);
+/** §16.2: what one change may carry. */
+export const AUTHORING_BUDGET = Object.freeze({ textOperations: 8192, createdNodes: 256 });
+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(",");
+/** Rebuilds a section document from the changes it held before an aborted apply. */
+function restoreSection(changes, actor, revision) {
+    let restored;
+    try {
+        [restored] = A.applyChanges(A.init({ actor }), [...changes]);
+    }
+    catch (r) {
+        throw new Error(`the section replica could not be restored after an Automerge error: ${String(r)}`);
+    }
+    if (revisionOf(restored) !== revision)
+        throw new Error("the section replica could not be restored after an Automerge error: heads differ");
+    return restored;
+}
+/**
+ * Applies admitted changes one at a time to `doc`, so a change the engine
+ * aborts on (D1) is isolated. On an abort the working document is rebuilt
+ * from the changes applied so far, never from the aborted one. A wasm trap
+ * is rethrown (isWasmTrap): the module is dead, and only a restart recovers.
+ */
+function applyIsolating(doc, changes) {
+    const actor = A.getActorId(doc);
+    let work = doc;
+    const applied = [];
+    const poisoned = [];
+    for (const c of changes) {
+        const before = { revision: revisionOf(work), changes: A.getAllChanges(work) };
+        try {
+            work = A.applyChanges(work, [c.bytes])[0];
+            applied.push(c);
+        }
+        catch (e) {
+            if (isWasmTrap(e))
+                throw e;
+            work = restoreSection(before.changes, actor, before.revision);
+            poisoned.push(c);
+        }
+    }
+    return { doc: work, applied, poisoned };
+}
+/** Every concurrent value of `map[key]`. */
+function values(map, key) {
+    if (!(key in map))
+        return [];
+    const c = A.getConflicts(map, key);
+    return c === undefined ? [map[key]] : Object.values(c);
+}
+/** PROFILE_INVALID for a Snapshot, with the diagnostic of what refused it. */
+function snapshotRefused(diagnostic, message) {
+    return Object.assign(new LfcpError("PROFILE_INVALID", message), { diagnostic });
+}
+export class SectionReplica {
+    resource;
+    /** The §2 Automerge actor ID. */
+    actorId;
+    #principal;
+    #actor;
+    #minSeq;
+    #doc;
+    /** SOP §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.#minSeq = opts.minSeq ?? 0;
+        this.#principal = opts.principal;
+        this.actorId = deriveSectionActorId(opts.resource, opts.principal);
+        this.#actor = toHex(this.actorId);
+        this.#doc = A.getActorId(doc) === this.#actor ? doc : A.clone(doc, { actor: this.#actor });
+    }
+    /** This actor's latest change sequence in the document (0 when it has none). */
+    get actorSeq() {
+        return this.#sequences().get(this.#actor) ?? 0;
+    }
+    /** SOP §9: whether this replica may write (it is not behind its actor's used sequence). */
+    get writable() {
+        return this.actorSeq >= this.#minSeq;
+    }
+    /**
+     * §12.1: "ready" once the section's `ready` is written, "importing"
+     * before, undefined while the document has no section. Reads one
+     * register; validate() tells whether the section is valid.
+     */
+    sectionState() {
+        const section = this.#doc.section;
+        if (section === null || typeof section !== "object" || A.isImmutableString(section))
+            return undefined;
+        return section.ready === true ? "ready" : "importing";
+    }
+    /** Whether the document holds the change with this hex hash. */
+    hasChange(hash) {
+        return A.hasHeads(this.#doc, [hash]);
+    }
+    /**
+     * SOP §14.1 (G-EP7): the replica rebuilt from its changes minus `exclude`
+     * (change hashes); changes that depend on an excluded one are unapplied
+     * too. An excluded change of this actor is not lost state (§9): the
+     * rebuilt replica writes on from its own sequence.
+     */
+    rebuildWithout(exclude) {
+        const out = new Set(exclude);
+        const kept = A.getAllChanges(this.#doc).filter((c) => !out.has(A.decodeChange(c).hash));
+        return SectionReplica.fromChanges(kept, {
+            resource: this.resource,
+            principal: this.#principal,
+            minSeq: this.writable ? 0 : this.#minSeq,
+        });
+    }
+    /**
+     * This replica merged with a received Snapshot's full save (SOP §13,
+     * §14): every change the save holds is admitted as if received one by
+     * one (the SOP checks and A1–A5, §14.1), on an empty replica of this
+     * actor, so a Snapshot that holds a change admission refuses is
+     * rejected; then this replica's own changes follow, so local work the
+     * Snapshot lacks is kept. The §9 sequence carries over. Throws
+     * PROFILE_INVALID (with the refused change's diagnostic, or
+     * INVALID_AUTOMERGE_BYTES) and keeps this replica unchanged.
+     */
+    mergeSave(save, limits = SNAPSHOT_LIMITS_FLOOR) {
+        const opts = {
+            resource: this.resource,
+            principal: this.#principal,
+            minSeq: Math.max(this.#minSeq, this.actorSeq),
+        };
+        const image = SectionReplica.fromSave(save, opts, limits);
+        const merged = SectionReplica.empty(opts);
+        const r = merged.receiveChanges(image.changes());
+        const refused = r.refused.find((x) => !x.held) ?? r.refused[0];
+        if (refused !== undefined)
+            throw snapshotRefused(refused.diagnostic, `the Snapshot holds a change admission refuses: ${refused.message}`);
+        if (r.waiting.length > 0)
+            throw snapshotRefused("INVALID_AUTOMERGE_BYTES", "the Snapshot holds a change whose dependency it lacks");
+        const own = merged.receiveChanges(this.changes());
+        const lost = own.refused[0];
+        if (lost !== undefined)
+            throw snapshotRefused(lost.diagnostic, `local state does not merge with the Snapshot: ${lost.message}`);
+        return merged;
+    }
+    /** An empty replica of the same actor that keeps the §9 sequence (SNAP-EP reset). */
+    emptied() {
+        return SectionReplica.empty({
+            resource: this.resource,
+            principal: this.#principal,
+            minSeq: Math.max(this.#minSeq, this.actorSeq),
+        });
+    }
+    /** An empty document, for section.create or for receiving. */
+    static empty(opts) {
+        const actor = toHex(deriveSectionActorId(opts.resource, opts.principal));
+        return new SectionReplica(A.init({ actor }), opts);
+    }
+    /** Loads a full save; SOP §13.1 limits unless it is this device's own state. */
+    static fromSave(save, opts, limits = SNAPSHOT_LIMITS_FLOOR) {
+        checkSaveHeader(save);
+        if (limits !== "local-state")
+            checkSnapshotExpansion(save, limits);
+        try {
+            return new SectionReplica(A.load(save), opts);
+        }
+        catch (e) {
+            if (e instanceof LfcpError)
+                throw e;
+            throw new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", `invalid Automerge save: ${String(e)}`);
+        }
+    }
+    /** The replica of an admitted change set; changes missing a dependency are returned unapplied. */
+    static fromChanges(changes, opts) {
+        const checked = [...changes].map((b) => {
+            checkChangeExpansion(b);
+            return checkChange(b);
+        });
+        const [doc] = A.applyChanges(A.init(), checked.map((c) => c.bytes));
+        const unapplied = checked.filter((c) => !A.hasHeads(doc, [c.hash])).map((c) => c.hash);
+        return { replica: new SectionReplica(doc, opts), unapplied };
+    }
+    /**
+     * Receives changes others wrote, as LFCP accepted them (§14.1): each
+     * passes the inherited SOP checks (framing, §11.1 expansion, the signer's
+     * actor when `signer` is given, the sequence check, holding a taken
+     * actor sequence) and the section rules A1–A5 and §12.1, against its
+     * causal history, before the engine applies any. A refused change is
+     * never merged; the changes that depend on it wait.
+     */
+    receiveChanges(items) {
+        const refused = [];
+        const checked = [];
+        const indexOf = new Map();
+        items.forEach((item, index) => {
+            const unit = item instanceof Uint8Array ? { bytes: item } : item;
+            let c;
+            try {
+                c = checkChange(unit.bytes);
+            }
+            catch (e) {
+                // Never decoded: a change refused by the checks is named from its bytes only.
+                refused.push(refusal(index, refusedChangeHash(unit.bytes, e), e, false));
+                return;
+            }
+            if (unit.signer !== undefined &&
+                c.actor !== toHex(deriveSectionActorId(this.resource, unit.signer))) {
+                refused.push({
+                    index,
+                    hash: c.hash,
+                    diagnostic: "CHANGE_ACTOR_MISMATCH",
+                    held: false,
+                    message: `the change's actor ${c.actor} is not the §2 actor of the unit's signer`,
+                });
+                return;
+            }
+            if (indexOf.has(c.hash))
+                return;
+            indexOf.set(c.hash, index);
+            checked.push(c);
+        });
+        const seqs = this.#sequences();
+        this.#refs ??= referenceHistoryOf(this.#doc);
+        const references = this.#refs;
+        // The document's good state, captured before admission applies anything: a
+        // change the engine aborts on (D1: a makeTable it cannot write back)
+        // corrupts the working document, so on an abort this.#doc is rebuilt from
+        // the changes it held here, never from the aborted one.
+        const safe = {
+            revision: this.revision(),
+            actor: A.getActorId(this.#doc),
+            changes: A.getAllChanges(this.#doc),
+        };
+        const admission = new SectionAdmission(this.#doc, this.resource);
+        const decided = admitBatch(checked, {
+            hasChange: (hash) => A.hasHeads(this.#doc, [hash]),
+            latestSeq: (actor) => seqs.get(actor) ?? 0,
+            // SOP §11.4; admitBatch adds what it admits, as the working copy holds it.
+            references,
+        }, (c) => admission.accept(c));
+        for (const r of decided.refused)
+            refused.push(refusal(indexOf.get(r.change.hash) ?? -1, r.change.hash, r.error, r.held));
+        if (decided.admitted.length > 0) {
+            let applied = decided.admitted;
+            try {
+                // The admission applied each admitted change, at its turn, to its working copy.
+                this.#doc = admission.document;
+            }
+            catch (e) {
+                if (isWasmTrap(e))
+                    throw e;
+                // The engine aborted applying an admitted change without a wasm trap
+                // (D1). The working document is corrupt; rebuild this.#doc from the
+                // changes it held before, then re-apply the admitted changes one at a
+                // time, refusing the one the engine rejects (§74.1).
+                this.#doc = restoreSection(safe.changes, safe.actor, safe.revision);
+                const isolated = applyIsolating(this.#doc, decided.admitted);
+                this.#doc = isolated.doc;
+                applied = isolated.applied;
+                for (const c of isolated.poisoned)
+                    refused.push({
+                        index: indexOf.get(c.hash) ?? -1,
+                        hash: c.hash,
+                        diagnostic: "INVALID_AUTOMERGE_BYTES",
+                        held: false,
+                        message: `the engine could not apply the change (${String(e)})`,
+                    });
+                // The admitted changes were added to the reference index and the
+                // sequences; a refused one is not in the document, so rebuild both.
+                this.#refs = null;
+                this.#seqs = undefined;
+            }
+            for (const c of applied)
+                if (c.seq > (seqs.get(c.actor) ?? 0))
+                    seqs.set(c.actor, c.seq);
+        }
+        const hashes = (list) => Object.freeze(list.map((c) => c.hash));
+        return Object.freeze({
+            admitted: hashes(decided.admitted),
+            duplicates: hashes(decided.duplicates),
+            waiting: hashes(decided.waiting),
+            refused: Object.freeze(refused.sort((a, b) => a.index - b.index)),
+        });
+    }
+    /** Each actor's latest sequence number in the document, read once and kept current. */
+    #seqs;
+    #sequences() {
+        if (this.#seqs === undefined) {
+            this.#seqs = new Map();
+            for (const bytes of A.getAllChanges(this.#doc)) {
+                const c = A.decodeChange(bytes);
+                if (c.seq > (this.#seqs.get(c.actor) ?? 0))
+                    this.#seqs.set(c.actor, c.seq);
+            }
+        }
+        return this.#seqs;
+    }
+    /**
+     * 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() {
+        const tree = deriveTree(this.#doc);
+        const root = this.#doc;
+        const section = (root.section ?? {});
+        const nodes = (root.nodes ?? {});
+        const objects = (root.objects ?? {});
+        const placements = (root.placements ?? {});
+        const hidden = new Set(tree.hidden);
+        const titles = values(section, "title").map(str);
+        const out = {};
+        for (const id of Object.keys(nodes).sort()) {
+            if (tree.collisions.includes(id))
+                continue;
+            const n = nodes[id];
+            const kind = str(n.kind) ?? "";
+            const owner = (kind === "task" ? objects[id] : n);
+            const placement = placements[str(n.placement) ?? ""];
+            const text = n.text;
+            out[id] = Object.freeze({
+                kind,
+                parent: str(placement?.parent_id),
+                ...(kind !== "task" && text !== undefined ? { text: String(text) } : {}),
+                ...(n.list_style !== undefined ? { listStyle: str(n.list_style) } : {}),
+                ...(kind === "task" ? { taskId: id } : {}),
+                deleted: str(owner?.lifecycle) === "deleted",
+                hidden: hidden.has(id),
+            });
+        }
+        return Object.freeze({
+            revision: revisionOf(this.#doc),
+            classification: tree.classification,
+            title: Object.freeze({
+                value: str(section.title),
+                conflicts: Object.freeze(titles.length > 1 ? titles.map((t) => t ?? "").sort() : []),
+            }),
+            nodes: Object.freeze(out),
+            order: tree.tree,
+            problems: Object.freeze({
+                recovery: tree.recovery,
+                invalid: tree.invalid,
+                collisions: tree.collisions,
+                retainedConcurrentEdits: tree.retainedConcurrentEdits,
+                scalarConflicts: tree.scalarConflicts,
+            }),
+        });
+    }
+    /**
+     * The Task of a task node (§4.2: stored under `/objects/<id>`, the node's
+     * ID) with its conflict metadata, in the form SharedObjectsReplica.task
+     * gives (SOP §99); undefined if there is no object or it is not a Task.
+     */
+    task(id) {
+        const objects = this.#doc.objects;
+        return taskView(this.#doc, objects !== null && typeof objects === "object" && !A.isImmutableString(objects)
+            ? objects
+            : undefined, id);
+    }
+    /** §3, §4, §14.2. */
+    validate() {
+        return validateSection(this.#doc);
+    }
+    /** §7, §9, §14.3: the effective tree, hidden nodes and structural facts. */
+    tree() {
+        return deriveTree(this.#doc);
+    }
+    /** The document heads, sorted, as one string. */
+    revision() {
+        return revisionOf(this.#doc);
+    }
+    /**
+     * The Shared Objects (by ID) that changes since `revision`, an earlier
+     * revision() of this document, wrote: a Task's fields, conflicts
+     * included, live there and not in its node. From A.diff, without reading
+     * the document; undefined when this document does not hold `revision`
+     * (a rebuild, or another document).
+     */
+    objectsTouchedSince(revision) {
+        const heads = revision === "" ? [] : revision.split(",");
+        if (!A.hasHeads(this.#doc, heads))
+            return undefined;
+        const out = new Set();
+        for (const p of A.diff(this.#doc, heads, A.getHeads(this.#doc))) {
+            const [container, key] = p.path;
+            if (container === "objects" && typeof key === "string")
+                out.add(key);
+        }
+        return [...out].sort();
+    }
+    save() {
+        return A.save(this.#doc);
+    }
+    /** Every change of the document, in causal order. */
+    changes() {
+        return A.getAllChanges(this.#doc);
+    }
+    /** The current state as JSON: scalar strings and Text read as strings. */
+    toJSON() {
+        return plain(this.#doc);
+    }
+    /**
+     * Validates `intents` as one batch and commits them as one change.
+     * Returns null when the batch writes nothing. Throws SectionIntentError,
+     * or ProfileError / ObjectIdCollisionError for a Task the SOP refuses.
+     */
+    commit(intents) {
+        const staged = this.stage(intents);
+        if (staged === null)
+            return null;
+        staged.apply();
+        return staged.change;
+    }
+    /**
+     * Validates `intents` as one batch and prepares their change without
+     * changing this replica: `apply()` adopts it, once the caller has stored
+     * it durably (its Data Unit, outbound entry and checkpoint). A batch that
+     * is never applied leaves the replica as it was. Null when the batch
+     * writes nothing.
+     */
+    stage(intents) {
+        if (intents.length === 0)
+            return null;
+        if (!this.writable)
+            throw new LfcpError("SEQUENCE_REUSE", `the replica is at actor sequence ${this.actorSeq}, behind ${this.#minSeq} already used (SOP §9)`);
+        if (A.getActorId(this.#doc) !== this.#actor)
+            throw new Error("the document actor is not the §2 actor");
+        const affected = new Set();
+        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
+        // the batch changes the section itself (create, ready).
+        const state = { chainOk: new Set(), cursor: new Map() };
+        // structure.resolve is its moves, each one checked after the ones before it.
+        const steps = expand(intents).flatMap((intent) => intent.intent === "structure.resolve"
+            ? intent.moves.map((m) => ({ intent: "node.resolve_placement", ...m }))
+            : [intent]);
+        // §12, §16.2: each change carries at most the budgets; a batch over them
+        // is several changes, one after the other.
+        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;
+            }
+            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();
+        }
+        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})`);
+            }
+            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)
+                    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;
+            },
+        });
+    }
+    /**
+     * Checks one intent against `doc`, the document with the batch so far,
+     * and `state.v`, its validation before the batch; returns its write.
+     */
+    #prepare(doc, state, intent, i, affected, budget) {
+        const refuse = (code, message, node) => {
+            throw new SectionIntentError(code, message, i, node);
+        };
+        if (intent.intent === "section.create") {
+            if (Object.keys(doc).length > 0)
+                refuse("SECTION_EXISTS", "the document already has a root (§4.1)");
+            if (!isObjectId(intent.sectionId))
+                refuse("INVALID_INTENT", "the SectionId is not a canonical UUIDv7 (§3)");
+            checkString(intent.title, "the title", refuse);
+            checkCreatedAt(intent.createdAt, refuse);
+            affected.add(intent.sectionId);
+            const createdBy = principalRef(intent.createdBy);
+            return (d) => {
+                d.profile = S(SECTIONS_PROFILE_ID);
+                d.section = {
+                    id: S(intent.sectionId),
+                    title: S(intent.title),
+                    created_by: S(createdBy),
+                    ...(intent.createdAt === undefined ? {} : { created_at: S(intent.createdAt) }),
+                    children: [],
+                    extensions: {},
+                    ...(intent.ready === false ? {} : { ready: true }),
+                };
+                d.objects = {};
+                d.nodes = {};
+                d.placements = {};
+                d.extensions = {};
+            };
+        }
+        // Every other intent writes into a valid section.
+        state.v ??= validateSection(doc);
+        const v = state.v;
+        if (v.state === "invalid" || v.sectionId === undefined)
+            refuse("SECTION_INVALID", `the document is not a valid section: ${v.problems[0]?.message ?? "no root"}`);
+        const section = doc.section;
+        if (v.state === "importing" && str(section.created_by) !== principalRef(this.#principal))
+            refuse("SECTION_IMPORTING", "the section is being imported by its creator (§12.1)");
+        const sectionId = v.sectionId;
+        if (intent.intent === "section.mark_ready") {
+            if (v.state === "ready")
+                refuse("SECTION_EXISTS", "the section is ready already; ready is written once (§12.1)");
+            if (str(section.created_by) !== principalRef(this.#principal))
+                refuse("SECTION_IMPORTING", "only the section's creator writes ready (§12.1)");
+            affected.add(sectionId);
+            return (d) => {
+                d.section.ready = true;
+            };
+        }
+        if (intent.intent === "section.set_title") {
+            checkString(intent.title, "the title", refuse);
+            affected.add(sectionId);
+            return (d) => {
+                const s = d.section;
+                // §58 (G-SC4): an unchanged value is deleted first so the intent writes.
+                if (str(s.title) === intent.title)
+                    delete s.title;
+                s.title = S(intent.title);
+            };
+        }
+        if (intent.intent === "task.create_in_section" ||
+            intent.intent === "paragraph.create" ||
+            intent.intent === "item.create" ||
+            intent.intent === "raw.create") {
+            const isTask = intent.intent === "task.create_in_section";
+            const id = isTask ? String(intent.task.id) : intent.id;
+            const kind = isTask ? "task" : intent.intent.slice(0, intent.intent.indexOf("."));
+            if (!isObjectId(id))
+                refuse("INVALID_INTENT", `the node ID ${id} is not a canonical UUIDv7 (§3)`, id);
+            if (idInUse(doc, sectionId, id))
+                refuse("ID_IN_USE", `the ID ${id} is already used in the Resource (§3)`, id);
+            const placementId = intent.placementId ?? generateObjectId();
+            if (!isObjectId(placementId))
+                refuse("INVALID_INTENT", "the PlacementId is not a canonical UUIDv7 (§3)", id);
+            if (placementId === id || idInUse(doc, sectionId, placementId))
+                refuse("ID_IN_USE", `the PlacementId ${placementId} is already used (§3)`, id);
+            const listStyle = intent.listStyle;
+            if (listStyle !== undefined &&
+                (!isListStyle(listStyle) || kind === "paragraph" || kind === "raw"))
+                refuse("INVALID_INTENT", "list_style is bullet or ordered, on task and item nodes only (§4.2)", id);
+            const index = insertionIndex(doc, v, sectionId, intent.parent, intent.after, refuse, undefined, state.chainOk);
+            let createdBy;
+            let node;
+            let taskWrite;
+            if (isTask) {
+                const prepared = prepareTaskIntent(doc, doc.objects, {
+                    intent: "task.create",
+                    task: intent.task,
+                });
+                taskWrite = prepared.perform;
+                createdBy = String(intent.task.created_by);
+                node = {
+                    id: S(id),
+                    kind: S("task"),
+                    created_by: S(createdBy),
+                    ...(intent.task.created_at === undefined
+                        ? {}
+                        : { created_at: S(intent.task.created_at) }),
+                    lifecycle: S("active"),
+                    placement: S(placementId),
+                    children: [],
+                    extensions: {},
+                    task_id: S(id),
+                    list_style: S(listStyle ?? "bullet"),
+                };
+            }
+            else {
+                checkString(intent.text, "the text", refuse);
+                checkCreatedAt(intent.createdAt, refuse);
+                createdBy = principalRef(intent.createdBy);
+                budget.text += Array.from(intent.text).length;
+                node = {
+                    id: S(id),
+                    kind: S(kind),
+                    created_by: S(createdBy),
+                    ...(intent.createdAt === undefined ? {} : { created_at: S(intent.createdAt) }),
+                    lifecycle: S("active"),
+                    placement: S(placementId),
+                    children: [],
+                    extensions: {},
+                    text: intent.text,
+                    ...(kind === "item" ? { list_style: S(listStyle ?? "bullet") } : {}),
+                };
+            }
+            budget.nodes += 1;
+            affected.add(id);
+            // A long text continues in later runs (§12.3) from the end of this one.
+            if (!isTask)
+                state.cursor.set(id, intent.text.length);
+            if (intent.parent === sectionId || state.chainOk.has(intent.parent))
+                state.chainOk.add(id);
+            const parent = intent.parent;
+            return (d) => {
+                taskWrite?.(d.objects);
+                d.nodes[id] = node;
+                d.placements[placementId] = {
+                    id: S(placementId),
+                    node_id: S(id),
+                    parent_id: S(parent),
+                    created_by: S(createdBy),
+                };
+                const lane = (parent === sectionId
+                    ? d.section.children
+                    : d.nodes[parent].children);
+                lane.splice(index, 0, S(placementId));
+            };
+        }
+        if (intent.intent === "text.continue") {
+            // §12.3: the next run of a long edit, where the previous one ended.
+            const id = intent.id;
+            const at = state.cursor.get(id);
+            const text = String(doc.nodes[id]?.text ?? "");
+            if (at === undefined)
+                refuse("INVALID_INTENT", `no Text edit of ${id} to continue (§12.3)`, id);
+            const removed = Array.from(text.slice(at)).slice(0, intent.deleteCount).join("");
+            budget.text += intent.deleteCount + Array.from(intent.insert).length;
+            state.cursor.set(id, at + intent.insert.length);
+            affected.add(id);
+            const path = ["nodes", id, "text"];
+            return (d) => A.splice(d, path, at, removed.length, intent.insert);
+        }
+        if (intent.intent === "text.edit" ||
+            intent.intent === "paragraph.split" ||
+            intent.intent === "item.split" ||
+            intent.intent === "node.join") {
+            const id = intent.id;
+            const node = doc.nodes[id];
+            if (node === undefined)
+                refuse("UNKNOWN_NODE", `${id} names no node`, id);
+            if (v.nodes.has(id) || collidedSet(v).has(id))
+                refuse("NODE_IN_CONFLICT", `${id} is invalid or collides (§14.2)`, id);
+            const kind = str(node.kind);
+            if (kind === "task")
+                refuse("INVALID_INTENT", "a task node has no Text (§4.2)", id);
+            const current = String(node.text ?? "");
+            const path = ["nodes", id, "text"];
+            if (intent.intent === "text.edit") {
+                const ranges = rebase(doc, path, intent.base, intent.edits, refuse, id);
+                const lastRange = ranges[ranges.length - 1];
+                if (lastRange !== undefined) {
+                    // A later run of this edit (§12.3) continues after what it inserts.
+                    const shift = ranges
+                        .slice(0, -1)
+                        .reduce((n, r) => n + r.insert.length - (r.to - r.from), 0);
+                    state.cursor.set(id, lastRange.from + shift + lastRange.insert.length);
+                }
+                for (const e of intent.edits) {
+                    checkString(e.insert, "inserted text", refuse);
+                    budget.text += Array.from(e.insert).length + e.deleteCount;
+                }
+                affected.add(id);
+                return (d) => {
+                    // From the end, so earlier positions stay valid.
+                    for (const r of [...ranges].reverse())
+                        A.splice(d, path, r.from, r.to - r.from, r.insert);
+                };
+            }
+            if (intent.intent === "node.join") {
+                const second = intent.second;
+                const other = doc.nodes[second];
+                if (other === undefined)
+                    refuse("UNKNOWN_NODE", `${second} names no node`, second);
+                if (v.nodes.has(second) || collidedSet(v).has(second))
+                    refuse("NODE_IN_CONFLICT", `${second} is invalid or collides (§14.2)`, second);
+                const otherKind = str(other.kind);
+                const sameStyle = kind === "paragraph" ||
+                    values(node, "list_style").join() === values(other, "list_style").join();
+                if (otherKind !== kind || (kind !== "paragraph" && kind !== "item") || !sameStyle)
+                    refuse("INVALID_INTENT", "only two paragraphs, or two items of one list style, join (§10)", id);
+                const kids = (n) => (n.children ?? []).length;
+                if (kids(node) > 0 || kids(other) > 0)
+                    refuse("INVALID_INTENT", "a node with children does not join (§10)", id);
+                if (!adjacent(doc, v, id, second))
+                    refuse("INVALID_INTENT", `${second} is not the visible sibling right after ${id} (§10)`, second);
+                const separator = intent.separator ?? "\n";
+                checkString(separator, "the separator", refuse);
+                const appended = separator + String(other.text ?? "");
+                const at = current.length;
+                budget.text += Array.from(appended).length;
+                affected.add(id);
+                affected.add(second);
+                return (d) => {
+                    A.splice(d, path, at, 0, appended);
+                    // §9, §10: the second node is deleted with a fresh write; its Text stays.
+                    const o = d.nodes[second];
+                    if (str(o.lifecycle) === "deleted")
+                        o.lifecycle = S("active");
+                    o.lifecycle = S("deleted");
+                };
+            }
+            // split: a deletion of the suffix and a new node after this one.
+            if (intent.intent.slice(0, intent.intent.indexOf(".")) !== kind)
+                refuse("INVALID_INTENT", `${intent.intent} on a ${kind} node (§10)`, id);
+            if (values(node, "placement").length !== 1 ||
+                new Set(values(node, "lifecycle")).size !== 1)
+                refuse("NODE_IN_CONFLICT", `${id} has unresolved structure (§10)`, id);
+            const cut = rebase(doc, path, intent.base, [{ index: intent.at, deleteCount: 0, insert: "" }], refuse, id)[0];
+            const suffix = current.slice(cut.from);
+            const placement = doc.placements[str(node.placement)];
+            const parent = str(placement.parent_id);
+            const create = this.#prepare(doc, state, {
+                intent: kind === "item" ? "item.create" : "paragraph.create",
+                id: intent.newId,
+                parent,
+                after: id,
+                text: suffix,
+                createdBy: intent.createdBy,
+                ...(kind === "item"
+                    ? { listStyle: (str(node.list_style) ?? "bullet") }
+                    : {}),
+                ...(intent.placementId === undefined ? {} : { placementId: intent.placementId }),
+            }, i, affected, budget);
+            budget.text += Array.from(suffix).length;
+            affected.add(id);
+            return (d) => {
+                A.splice(d, path, cut.from, current.length - cut.from, "");
+                create(d);
+            };
+        }
+        if (intent.intent === "node.delete" || intent.intent === "node.restore") {
+            const id = intent.id;
+            const node = doc.nodes[id];
+            if (node === undefined)
+                refuse("UNKNOWN_NODE", `${id} names no node`, id);
+            if (v.nodes.has(id) || collidedSet(v).has(id))
+                refuse("NODE_IN_CONFLICT", `${id} is invalid or collides (§14.2)`, id);
+            const isTask = str(node.kind) === "task";
+            const value = intent.intent === "node.delete" ? "deleted" : "active";
+            affected.add(id);
+            return (d) => {
+                const owner = (isTask ? d.objects[id] : d.nodes[id]);
+                // §9: a same-value assignment would be dropped by the binding, so the
+                // other valid value is written first, in the same change.
+                if (str(owner.lifecycle) === value)
+                    owner.lifecycle = S(value === "active" ? "deleted" : "active");
+                owner.lifecycle = S(value);
+            };
+        }
+        if (intent.intent === "node.move" ||
+            intent.intent === "node.resolve_placement" ||
+            intent.intent === "node.set_list_style") {
+            const id = intent.id;
+            const node = doc.nodes[id];
+            if (node === undefined)
+                refuse("UNKNOWN_NODE", `${id} names no node`, id);
+            if (v.nodes.has(id) || collidedSet(v).has(id))
+                refuse("NODE_IN_CONFLICT", `${id} is invalid or collides (§14.2)`, id);
+            const kind = str(node.kind);
+            affected.add(id);
+            if (intent.intent === "node.set_list_style") {
+                if (!isListStyle(intent.listStyle) || (kind !== "task" && kind !== "item"))
+                    refuse("INVALID_INTENT", "list_style is bullet or ordered, on task and item nodes only (§4.2)", id);
+                const style = intent.listStyle;
+                return (d) => {
+                    const n = d.nodes[id];
+                    // §58 (G-SC4): an unchanged value is deleted first so the intent writes.
+                    if (str(n.list_style) === style)
+                        delete n.list_style;
+                    n.list_style = S(style);
+                };
+            }
+            if (intent.intent === "node.move" && values(node, "placement").length !== 1)
+                refuse("NODE_IN_CONFLICT", `${id} has concurrent placements: use node.resolve_placement (§7, §8)`, id);
+            const placementId = intent.placementId ?? generateObjectId();
+            if (!isObjectId(placementId))
+                refuse("INVALID_INTENT", "the PlacementId is not a canonical UUIDv7 (§3)", id);
+            if (idInUse(doc, sectionId, placementId))
+                refuse("ID_IN_USE", `the PlacementId ${placementId} is already used (§3)`, id);
+            const index = insertionIndex(doc, v, sectionId, intent.parent, intent.after, refuse, id);
+            const createdBy = principalRef(this.#principal);
+            const parent = intent.parent;
+            return (d) => {
+                d.placements[placementId] = {
+                    id: S(placementId),
+                    node_id: S(id),
+                    parent_id: S(parent),
+                    created_by: S(createdBy),
+                };
+                const lane = (parent === sectionId
+                    ? d.section.children
+                    : d.nodes[parent].children);
+                lane.splice(index, 0, S(placementId));
+                // §5: the node's register selects the new slot; the old one stays as an anchor.
+                d.nodes[id].placement = S(placementId);
+            };
+        }
+        // A SOP Task intent on a Task of this section (§2).
+        const prepared = prepareTaskIntent(doc, doc.objects, intent);
+        affected.add(prepared.id);
+        return (d) => prepared.perform(d.objects);
+    }
+}
+/** §3: a lone surrogate code point is not valid Unicode. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/**
+ * §10: the Text edits at `base` as UTF-16 ranges of the current Text.
+ * Each position is the current place of the character it stood before at
+ * `base` (an Automerge cursor taken at the base heads); a deleted range
+ * must still hold exactly the text it held then.
+ */
+function rebase(doc, path, base, edits, refuse, node) {
+    const heads = base === "" ? [] : base.split(",");
+    let view;
+    try {
+        if (!heads.every((h) => /^[0-9a-f]{64}$/.test(h)) || !A.hasHeads(doc, heads))
+            throw new Error();
+        view = A.view(doc, heads);
+    }
+    catch {
+        return refuse("STALE_BASE", `the base revision is not in this document (§10)`, node);
+    }
+    const before = String(view.nodes?.[path[1]]?.text ?? "");
+    const scalars = Array.from(before);
+    const utf16 = (scalar) => scalars.slice(0, scalar).join("").length;
+    const now = String(doc.nodes[path[1]].text ?? "");
+    let last = 0;
+    return edits.map((e) => {
+        if (!Number.isInteger(e.index) ||
+            !Number.isInteger(e.deleteCount) ||
+            e.index < last ||
+            e.deleteCount < 0 ||
+            e.index + e.deleteCount > scalars.length)
+            refuse("INVALID_INTENT", "Text edits are sorted, do not overlap and stay within the base Text (§10)", node);
+        last = e.index + e.deleteCount;
+        const position = (scalar) => {
+            try {
+                return A.getCursorPosition(doc, path, A.getCursor(view, path, utf16(scalar)));
+            }
+            catch {
+                return refuse("STALE_BASE", "a Text position cannot be rebased (§10)", node);
+            }
+        };
+        const from = position(e.index);
+        const to = e.deleteCount === 0 ? from : position(e.index + e.deleteCount);
+        const removed = scalars.slice(e.index, e.index + e.deleteCount).join("");
+        if (now.slice(from, to) !== removed)
+            refuse("STALE_BASE", "the deleted Text changed since the base revision (§10)", node);
+        return { from, to, insert: e.insert };
+    });
+}
+/** §10: whether `second` is the visible sibling right after `first`, both unblocked. */
+function adjacent(doc, v, first, second) {
+    const entries = deriveTree(doc, v).tree;
+    const i = entries.findIndex((e) => e.id === first);
+    if (i < 0)
+        return false;
+    const { parent, depth } = entries[i];
+    for (let k = i + 1; k < entries.length; k++) {
+        const e = entries[k];
+        if (e.depth < depth)
+            return false;
+        if (e.parent === parent)
+            return e.id === second;
+    }
+    return false;
+}
+function refusal(index, hash, e, held) {
+    const diagnostic = e.diagnostic ??
+        (held ? "ACTOR_EQUIVOCATION" : (e.code ?? "INVALID_AUTOMERGE_BYTES"));
+    return { index, hash, diagnostic, held, message: e instanceof Error ? e.message : String(e) };
+}
+function checkString(text, what, refuse) {
+    if (typeof text !== "string" || LONE_SURROGATE.test(text))
+        refuse("INVALID_INTENT", `${what} must be a string of valid Unicode (§3)`);
+}
+function checkCreatedAt(at, refuse) {
+    if (at !== undefined && !isUtcTimestamp(at))
+        refuse("INVALID_INTENT", "created_at is not an RFC 3339 UTC timestamp (§3)");
+}
+const collidedSets = new WeakMap();
+/** The collided nodes of a validation as a set, built once per validation. */
+function collidedSet(v) {
+    let set = collidedSets.get(v);
+    if (set === undefined) {
+        set = new Set(v.collided);
+        collidedSets.set(v, set);
+    }
+    return set;
+}
+/** §3: whether `id` already names the section, a node, a placement or an object. */
+function idInUse(doc, sectionId, id) {
+    return (id === sectionId ||
+        id in doc.nodes ||
+        id in doc.placements ||
+        id in doc.objects);
+}
+/**
+ * §6: the physical index in the parent's children list at which a new
+ * placement goes. The parent is the section, or a valid, active,
+ * unconflicted task or item node whose ancestors are too; `after` is a
+ * visible child of it, and the new entry goes right after its selected
+ * placement, keeping every historical slot.
+ */
+function insertionIndex(doc, v, sectionId, parent, after, refuse, moving, 
+/** Nodes whose ancestor chain this batch already verified; unused for a move. */
+chainOk) {
+    const nodes = doc.nodes;
+    const placements = doc.placements;
+    const objects = doc.objects;
+    /** The selected parent of an eligible node, or why it is not eligible. */
+    const eligible = (id) => {
+        const node = nodes[id];
+        if (node === undefined)
+            return { why: "names no node" };
+        if (v.nodes.has(id) || collidedSet(v).has(id))
+            return { why: "is invalid (§14.2)" };
+        const kind = str(node.kind);
+        const owner = kind === "task" ? objects[id] : node;
+        const life = values(owner, "lifecycle").map(str);
+        if (life.length !== 1)
+            return { why: "has a lifecycle conflict (§9)" };
+        if (life[0] !== "active")
+            return { why: "is deleted (§9)" };
+        const selected = values(node, "placement").map(str);
+        if (selected.length !== 1)
+            return { why: "has a placement conflict (§7)" };
+        const placement = placements[selected[0]];
+        if (placement === undefined)
+            return { why: "has no placement" };
+        return { parent: str(placement.parent_id) };
+    };
+    if (parent !== sectionId) {
+        const kind = str(nodes[parent]?.kind);
+        if (kind === undefined || !PARENT_KINDS.has(kind))
+            refuse("INVALID_PARENT", `the parent ${parent} is not the section, a task or an item (§4.2)`, parent);
+        // The parent and every ancestor are eligible, without a cycle (§6, §7).
+        const seen = new Set();
+        let p = parent;
+        while (p !== sectionId) {
+            if (moving === undefined && chainOk?.has(p))
+                break;
+            if (p === moving)
+                refuse("INVALID_PARENT", `${moving} cannot move under itself or its descendant (§6)`, moving);
+            if (seen.has(p))
+                refuse("INVALID_PARENT", `the parent ${parent} is in a cycle (§7)`, parent);
+            seen.add(p);
+            const e = eligible(p);
+            if ("why" in e)
+                refuse("INVALID_PARENT", `the parent's ancestor ${p} ${e.why}`, parent);
+            p = e.parent;
+        }
+        if (moving === undefined)
+            for (const n of seen)
+                chainOk?.add(n);
+    }
+    const lane = (parent === sectionId ? doc.section.children : nodes[parent].children);
+    if (after === null)
+        return 0;
+    if (after === moving)
+        refuse("INVALID_PREDECESSOR", `${after} cannot follow itself (§6)`, after);
+    const e = eligible(after);
+    if ("why" in e || e.parent !== parent)
+        refuse("INVALID_PREDECESSOR", `${after} is not a visible child of ${parent} (§6)`, after);
+    const slot = str(values(nodes[after], "placement")[0]);
+    const at = lane.findIndex((x) => str(x) === slot);
+    if (at < 0)
+        refuse("INVALID_PREDECESSOR", `${after}'s placement is not in the parent's list (§4.3)`, after);
+    return at + 1;
+}
+function plain(value) {
+    if (A.isImmutableString(value))
+        return value.toString();
+    if (Array.isArray(value))
+        return value.map(plain);
+    if (value !== null && typeof value === "object" && !(value instanceof Uint8Array))
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, plain(v)]));
+    return value;
+}
+//# sourceMappingURL=replica.js.map