@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/collab/op-log.d.ts

@@ -0,0 +1,50 @@
+import { DiagramModel } from '../models/DiagramModel';
+import { type Op } from './op';
+/**
+ * An append-only, totally-ordered, de-duplicating op log.
+ *
+ * Kept SORTED rather than merely appended, because "the order ops arrived in" is a
+ * property of the network and "the order ops apply in" must not be.
+ */
+export declare class OpLog {
+    private readonly ops;
+    private readonly seen;
+    /**
+     * Add an op. Returns false if it was already present.
+     *
+     * Idempotence is not a nicety here: every real transport redelivers (a WebSocket
+     * reconnect replays, a peer re-sends on timeout, two peers relay the same op to each
+     * other). An op log that applied a duplicate `add` twice, or double-counted a move,
+     * would diverge on nothing more exotic than a flaky wifi connection.
+     */
+    append(op: Op): boolean;
+    appendAll(ops: Iterable<Op>): Op[];
+    has(op: Op): boolean;
+    /** The ops, in total order. */
+    toArray(): readonly Op[];
+    get size(): number;
+    /** Ops strictly after `clock` — the tail a peer needs to catch up. */
+    since(clock: number): Op[];
+    /** The highest clock in the log — what a peer should observe on catch-up. */
+    maxClock(): number;
+}
+/**
+ * Replay an ordered log into a diagram.
+ *
+ * Sorts defensively rather than trusting the caller: replay determinism is the property
+ * every later card stands on, and it would be silly to lose it because someone handed us
+ * an array in arrival order.
+ *
+ * Card 4: and it ENFORCES THE INVARIANT at the end, because a peer that joins by replaying
+ * a log must arrive exactly where a peer that was in the room the whole time already is. If
+ * integrity only ran in `Replica.receive()`, a log containing "delete a node that had links"
+ * would replay into a document with a dangling link, and the newcomer would be the only one
+ * holding it. One sweep, once, over the final state — the invariant is a function of that
+ * state and of nothing on the way to it.
+ *
+ * NOTE this is the DOCUMENT, not a live peer: the quarantine it builds is discarded with the
+ * temporary registry. A peer that intends to go on editing should be seeded through
+ * `Replica.receive(history)`, which keeps it — and can therefore still bring an orphaned
+ * link back if someone undoes the delete.
+ */
+export declare function replay(diagram: DiagramModel, ops: readonly Op[]): number;

package/src/libs/engine/src/collab/op-log.js

@@ -0,0 +1,167 @@
+"use strict";
+// Wave 9 — Card 0: the log itself, and deterministic replay.
+//
+// ---------------------------------------------------------------------------
+// CONVERGENCE, AND WHAT THIS FILE DOES *NOT* CLAIM
+// ---------------------------------------------------------------------------
+//
+// Card 0 is the substrate: a totally-ordered, replayable log. The merge SEMANTICS
+// (Card 4) build on it. It is worth being exact about what is already guaranteed here,
+// because "we have an op log" is the kind of sentence that quietly gets read as "we
+// have collaboration", and the gap between those is where the silent data loss lives.
+//
+// WHAT IS GUARANTEED HERE:
+//   • A TOTAL ORDER on ops — (lamport clock, actor id) — identical on every peer.
+//   • DETERMINISTIC REPLAY: same start state + same ordered log ⇒ byte-identical
+//     diagram, on any peer, any number of times.
+//   • IDEMPOTENCE: the same op delivered twice is applied once (opId dedupe), because
+//     any real transport will duplicate.
+//
+// WHAT THAT ALREADY BUYS YOU, WITHOUT ANY CRDT MACHINERY: because every peer sorts the
+// same ops into the same sequence and the reducer is deterministic, two peers that have
+// seen the SAME SET of ops hold the SAME diagram — regardless of the order those ops
+// ARRIVED in. That is convergence for the property-register case, and it falls out of
+// the total order rather than being bolted on.
+//
+// The reason it works is the design decision in op.ts: ops are PER-PROPERTY. `set(n1,
+// position)` and `set(n1, metadata.label)` are different registers, so a concurrent
+// move and rename BOTH survive. The engine's existing DiagramIncremental could never do
+// this — it reports `modified: [<the whole node>]`, so whole-entity last-writer-wins
+// silently throws one of the two edits away.
+//
+// WHAT IS *NOT* SETTLED HERE, and belongs to Card 4:
+//   • ADD/REMOVE RACES. Right now presence is decided by the last op on that id in the
+//     total order, which makes it last-writer-wins: a `remove` that sorts after an `add`
+//     wins, and vice versa. That is convergent (every peer agrees) but it is not
+//     necessarily what a USER wants — the literature prefers an observed-remove set,
+//     where a remove only cancels the adds it actually SAW, so a concurrent add
+//     survives a delete it never knew about. Choosing between "remove wins" and
+//     "add wins" is a product decision with real consequences (delete a node while a
+//     colleague is attaching a link to it — what should happen to the link?), and it is
+//     Card 4's to make. It is called out here rather than left as an accident.
+//   • CAUSAL READINESS. An op for an entity that has not arrived yet is currently
+//     DROPPED (applyOp returns false). Under a reliable, ordered transport that cannot
+//     happen; under an unreliable one it can, and the op must be BUFFERED until its
+//     dependency lands. Also Card 4/5.
+//
+// Saying this out loud costs nothing and prevents the next person from believing the
+// log is a merge engine.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpLog = void 0;
+exports.replay = replay;
+const apply_op_1 = require("./apply-op");
+const integrity_1 = require("./integrity");
+const lww_1 = require("./lww");
+const op_1 = require("./op");
+/**
+ * An append-only, totally-ordered, de-duplicating op log.
+ *
+ * Kept SORTED rather than merely appended, because "the order ops arrived in" is a
+ * property of the network and "the order ops apply in" must not be.
+ */
+class OpLog {
+    constructor() {
+        this.ops = [];
+        this.seen = new Set();
+    }
+    /**
+     * Add an op. Returns false if it was already present.
+     *
+     * Idempotence is not a nicety here: every real transport redelivers (a WebSocket
+     * reconnect replays, a peer re-sends on timeout, two peers relay the same op to each
+     * other). An op log that applied a duplicate `add` twice, or double-counted a move,
+     * would diverge on nothing more exotic than a flaky wifi connection.
+     */
+    append(op) {
+        const id = (0, op_1.opId)(op);
+        if (this.seen.has(id))
+            return false;
+        this.seen.add(id);
+        // Insert in order. Ops usually arrive nearly-sorted (clocks advance), so a linear
+        // scan from the end is O(1) amortised in the common case and correct in the worst.
+        let i = this.ops.length;
+        while (i > 0 && (0, op_1.compareOps)(this.ops[i - 1], op) > 0)
+            i--;
+        this.ops.splice(i, 0, op);
+        return true;
+    }
+    appendAll(ops) {
+        const added = [];
+        for (const op of ops)
+            if (this.append(op))
+                added.push(op);
+        return added;
+    }
+    has(op) {
+        return this.seen.has((0, op_1.opId)(op));
+    }
+    /** The ops, in total order. */
+    toArray() {
+        return this.ops;
+    }
+    get size() {
+        return this.ops.length;
+    }
+    /** Ops strictly after `clock` — the tail a peer needs to catch up. */
+    since(clock) {
+        return this.ops.filter((o) => o.clock > clock);
+    }
+    /** The highest clock in the log — what a peer should observe on catch-up. */
+    maxClock() {
+        let max = 0;
+        for (const o of this.ops)
+            if (o.clock > max)
+                max = o.clock;
+        return max;
+    }
+}
+exports.OpLog = OpLog;
+/**
+ * Replay an ordered log into a diagram.
+ *
+ * Sorts defensively rather than trusting the caller: replay determinism is the property
+ * every later card stands on, and it would be silly to lose it because someone handed us
+ * an array in arrival order.
+ *
+ * Card 4: and it ENFORCES THE INVARIANT at the end, because a peer that joins by replaying
+ * a log must arrive exactly where a peer that was in the room the whole time already is. If
+ * integrity only ran in `Replica.receive()`, a log containing "delete a node that had links"
+ * would replay into a document with a dangling link, and the newcomer would be the only one
+ * holding it. One sweep, once, over the final state — the invariant is a function of that
+ * state and of nothing on the way to it.
+ *
+ * NOTE this is the DOCUMENT, not a live peer: the quarantine it builds is discarded with the
+ * temporary registry. A peer that intends to go on editing should be seeded through
+ * `Replica.receive(history)`, which keeps it — and can therefore still bring an orphaned
+ * link back if someone undoes the delete.
+ */
+function replay(diagram, ops) {
+    const lww = new lww_1.LwwRegistry();
+    const integrity = new integrity_1.ReferentialIntegrity(diagram, lww);
+    let applied = 0;
+    // A REMOTE OP IS NOT A LOCAL USER'S WRITE — it is the document already meaning something
+    // new, mirrored from a peer — so the read-only lock (which exists to refuse THIS user's
+    // intent) must not block it. Replaying a log into a LOCKED document is exactly how a
+    // viewer who joins an already-read-only session catches up; honour the lock here and that
+    // viewer receives an empty document and diverges forever. The bypass is scoped to this
+    // apply loop only (runSystemWrite is a synchronous try/finally depth counter, and applyOp
+    // is fully synchronous) — it never reaches a local edit. See models/readonly-lock.ts and
+    // the two remote-apply call sites (here and Replica.receive), the entire allowlist.
+    diagram.runSystemWrite(() => {
+        for (const op of [...ops].sort(op_1.compareOps)) {
+            // The gate's ANSWER is ignored — in TOTAL ORDER it can never refuse anything, because
+            // every register is written oldest-first by construction. What we want is its
+            // book-keeping: the presence stamps, which are what the canonical entity ORDER is
+            // derived from. Without them reconcile() has nothing to sort by and a replayed document
+            // would keep the arbitrary order its ops happened to build, while a live peer holds the
+            // canonical one. replay() stays the dumb, honest primitive it is documented to be.
+            lww.admit(op);
+            if ((0, apply_op_1.applyOp)(diagram, op))
+                applied++;
+            integrity.note(op);
+        }
+        integrity.reconcile();
+    });
+    return applied;
+}
+//# sourceMappingURL=op-log.js.map

package/src/libs/engine/src/collab/op.d.ts

@@ -0,0 +1,120 @@
+import type { SerializedNode } from '../models/NodeModel';
+import type { SerializedLink } from '../models/LinkModel';
+import type { SerializedGroup } from '../models/GroupModel';
+import type { SerializedStroke } from '../models/StrokeModel';
+/** Who made the edit. Stable for the lifetime of a session; distinct per peer. */
+export type ActorId = string;
+/**
+ * The entity kinds a diagram is made of, plus the diagram itself.
+ *
+ * wave10/whiteboard: `stroke` joins the list. Ink is DOCUMENT CONTENT — two people drawing
+ * on the same board must converge — so a stroke is a first-class op target, not annotation
+ * smuggled through a diagram-level `set`. (It very nearly WAS: `trackChange('strokes', …)`
+ * is a diagram-level change event, and without `stroke` in this union the capture layer's
+ * fall-through emitted `set(diagram, strokes, <live StrokeModel>)` — a class instance on the
+ * wire, claiming the whole collection. See capture.ts / apply-op.ts.)
+ */
+export type OpTarget = 'node' | 'link' | 'group' | 'stroke' | 'diagram';
+/**
+ * A property path. Dot-separated for nested registers: 'position', 'size',
+ * 'metadata.label', 'state.locked'.
+ *
+ * THE PATH IS THE REGISTER KEY. Two concurrent writes to the SAME path conflict and
+ * are resolved by last-writer-wins; two writes to DIFFERENT paths of the same entity
+ * do not conflict at all and both survive. This is the whole point (see the header).
+ */
+export type OpPath = string;
+/** JSON-safe value. Ops must survive a network hop and a disk round-trip. */
+export type OpValue = null | boolean | number | string | OpValue[] | {
+    [k: string]: OpValue;
+};
+interface OpBase {
+    /**
+     * Lamport clock. Causality, NOT wall time. Advances past every clock this actor
+     * has observed, so `caused-by` always implies a strictly greater clock.
+     */
+    clock: number;
+    /** Who. Also the deterministic tiebreak when two ops share a clock. */
+    actor: ActorId;
+}
+/** Create an entity. Carries the full serialized form — an add has no prior state to diff against. */
+export interface AddOp extends OpBase {
+    op: 'add';
+    target: Exclude<OpTarget, 'diagram'>;
+    id: string;
+    data: SerializedNode | SerializedLink | SerializedGroup | SerializedStroke;
+}
+/** Remove an entity. */
+export interface RemoveOp extends OpBase {
+    op: 'remove';
+    target: Exclude<OpTarget, 'diagram'>;
+    id: string;
+}
+/** Write one property register. The unit of concurrency. */
+export interface SetOp extends OpBase {
+    op: 'set';
+    target: OpTarget;
+    /** '' for the diagram itself, which is a singleton. */
+    id: string;
+    path: OpPath;
+    /**
+     * The value the register now holds. ABSENT when the op is a clear.
+     *
+     * wave14: this used to be required, and clearing a register (deleteMetadata,
+     * clearFlexItem) emitted `value: undefined` — which this type forbids and which only
+     * crossed the wire because JSON.stringify silently DROPS an undefined key and the
+     * peer's apply happened to read missing-as-undefined. A load-bearing accident. Clears
+     * are now EXPLICIT (`clear: true`), and `undefined` never appears in an emitted op.
+     */
+    value?: OpValue;
+    /**
+     * Explicitly empty the register: the key is deleted, not set to anything. NOT null —
+     * null is a legitimate STORED value (a peer that stores null and a peer that cleared
+     * must not converge on the same document), so it cannot double as the clear sentinel.
+     */
+    clear?: true;
+}
+export type Op = AddOp | RemoveOp | SetOp;
+/**
+ * The value a `set` op writes, with clears normalised to `undefined`.
+ *
+ * BACK-COMPAT lives here and nowhere else: every log persisted before wave14 encodes a
+ * clear as an ABSENT value key (JSON dropped the `undefined`), so `value === undefined`
+ * must read as a clear forever — alongside the explicit `clear: true` new ops carry.
+ */
+export declare function setValueOf(op: SetOp): OpValue | undefined;
+/**
+ * TOTAL ORDER over ops. Every peer must sort the same log into the same sequence, or
+ * "replay converges" is meaningless.
+ *
+ * (clock, actor) is a total order because clocks are integers and actor ids are
+ * distinct strings. The actor tiebreak is arbitrary — it does NOT mean the
+ * lexicographically-larger actor is "righter" — but it is the same arbitrary answer
+ * on every peer, which is the only thing required.
+ */
+export declare function compareOps(a: Op, b: Op): number;
+/** Identity of an op, for idempotent delivery: the same op received twice is one op. */
+export declare function opId(op: Op): string;
+/**
+ * A Lamport clock.
+ *
+ * `tick()` for a local event. `observe(remoteClock)` on receipt, which jumps this
+ * clock past anything the remote had seen — that is what makes the resulting order
+ * respect causality across peers rather than merely within one.
+ */
+export declare class LamportClock {
+    private readonly actor;
+    private value;
+    constructor(actor: ActorId, start?: number);
+    /** The next clock value for a local event. */
+    tick(): number;
+    /**
+     * Fold in a clock we have just seen. After this, our next tick() is guaranteed to
+     * be greater than `seen` — so any op we issue AFTER observing theirs sorts AFTER it,
+     * which is exactly the causality guarantee.
+     */
+    observe(seen: number): void;
+    peek(): number;
+    get actorId(): ActorId;
+}
+export {};

package/src/libs/engine/src/collab/op.js

@@ -0,0 +1,118 @@
+"use strict";
+// Wave 9 (Collaboration) — Card 0: the operation format.
+//
+// ---------------------------------------------------------------------------
+// WHY THIS IS NOT "PROMOTING THE EXISTING COMMAND STREAM", WHICH IS WHAT THE
+// ROADMAP CARD ASKED FOR
+// ---------------------------------------------------------------------------
+//
+// The card says: promote the existing SerializedCommand/CommandManager stream into
+// a semantic op format. Two things are wrong with that premise, and both change the
+// design:
+//
+//   1. THE COMMAND STREAM IS WRITE-ONLY. Every Command implements serialize(), and
+//      there is NO deserializer anywhere in the codebase — not one. You can emit the
+//      bytes and nothing on earth can consume them. (The same defect this project has
+//      found in every single wave: machinery wired to nothing.)
+//
+//   2. COMMANDS AND THE INCREMENTAL DIFF ARE BOTH WHOLE-ENTITY. AddLinkCommand stores
+//      `link.serialize()`; DiagramIncremental reports `modified: [<the whole node>]`.
+//      Whole-entity granularity is FATAL for merge, and quietly so: if you drag a node
+//      while I rename it, whole-entity last-writer-wins throws one of us away. No
+//      error, no conflict — just silently lost work, which is the worst possible
+//      failure mode for a collaboration engine.
+//
+// So an op is PER-PROPERTY. `set(node n1, position, {x,y})` and `set(node n1,
+// metadata.label, "Foo")` are different registers and both survive. That single
+// decision is what makes convergence possible at all, and it is why this is a build
+// rather than a promotion.
+//
+// ---------------------------------------------------------------------------
+// TIME
+// ---------------------------------------------------------------------------
+//
+// Command.timestamp is `Date.now()`. A wall clock is useless here and actively
+// dangerous: two peers' clocks disagree, clocks run backwards (NTP, DST, a VM
+// resuming), and "later" in wall time says nothing about causality. We use a LAMPORT
+// clock — a counter that advances past anything it has seen — so `a → b` (a caused b)
+// always implies `clock(a) < clock(b)`.
+//
+// Lamport gives a PARTIAL order; concurrent ops can share a clock value. We need a
+// TOTAL order (so every peer sorts the log identically), so ties break on actor id.
+// That is arbitrary but it is *stable and identical everywhere*, which is the only
+// property that matters.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LamportClock = void 0;
+exports.setValueOf = setValueOf;
+exports.compareOps = compareOps;
+exports.opId = opId;
+/**
+ * The value a `set` op writes, with clears normalised to `undefined`.
+ *
+ * BACK-COMPAT lives here and nowhere else: every log persisted before wave14 encodes a
+ * clear as an ABSENT value key (JSON dropped the `undefined`), so `value === undefined`
+ * must read as a clear forever — alongside the explicit `clear: true` new ops carry.
+ */
+function setValueOf(op) {
+    return op.clear === true ? undefined : op.value;
+}
+/**
+ * TOTAL ORDER over ops. Every peer must sort the same log into the same sequence, or
+ * "replay converges" is meaningless.
+ *
+ * (clock, actor) is a total order because clocks are integers and actor ids are
+ * distinct strings. The actor tiebreak is arbitrary — it does NOT mean the
+ * lexicographically-larger actor is "righter" — but it is the same arbitrary answer
+ * on every peer, which is the only thing required.
+ */
+function compareOps(a, b) {
+    if (a.clock !== b.clock)
+        return a.clock - b.clock;
+    if (a.actor !== b.actor)
+        return a.actor < b.actor ? -1 : 1;
+    // Same clock AND same actor: an actor never issues two ops at one clock value
+    // (nextClock() increments), so this is unreachable for well-formed logs. Return 0
+    // rather than throwing — a corrupt log should degrade, not explode, and the dedupe
+    // in OpLog will collapse true duplicates anyway.
+    return 0;
+}
+/** Identity of an op, for idempotent delivery: the same op received twice is one op. */
+function opId(op) {
+    return `${op.clock}@${op.actor}`;
+}
+/**
+ * A Lamport clock.
+ *
+ * `tick()` for a local event. `observe(remoteClock)` on receipt, which jumps this
+ * clock past anything the remote had seen — that is what makes the resulting order
+ * respect causality across peers rather than merely within one.
+ */
+class LamportClock {
+    constructor(actor, start = 0) {
+        this.actor = actor;
+        if (!actor)
+            throw new Error('LamportClock requires a non-empty actor id');
+        this.value = start;
+    }
+    /** The next clock value for a local event. */
+    tick() {
+        return ++this.value;
+    }
+    /**
+     * Fold in a clock we have just seen. After this, our next tick() is guaranteed to
+     * be greater than `seen` — so any op we issue AFTER observing theirs sorts AFTER it,
+     * which is exactly the causality guarantee.
+     */
+    observe(seen) {
+        if (seen > this.value)
+            this.value = seen;
+    }
+    peek() {
+        return this.value;
+    }
+    get actorId() {
+        return this.actor;
+    }
+}
+exports.LamportClock = LamportClock;
+//# sourceMappingURL=op.js.map

package/src/libs/engine/src/collab/replica.d.ts

@@ -0,0 +1,188 @@
+import { DiagramModel } from '../models/DiagramModel';
+import { OpLog } from './op-log';
+import { type ActorId, type Op } from './op';
+export interface ReplicaOptions {
+    /** This peer's identity. MUST be unique across peers — the total order depends on it. */
+    actor: ActorId;
+    /** Called with each op this peer produces locally. Hand it to a transport (Card 5). */
+    onLocalOp?: (op: Op) => void;
+    /** Resume the Lamport clock from a persisted tail. */
+    startClock?: number;
+}
+/**
+ * One peer.
+ *
+ * Local edits to `diagram` are captured, appended to `log`, and handed to `onLocalOp`.
+ * Remote ops arrive at `receive()`, are de-duplicated, applied, and NOT echoed back.
+ */
+export declare class Replica {
+    readonly diagram: DiagramModel;
+    private readonly options;
+    readonly log: OpLog;
+    /**
+     * Which write owns each register. THE piece that makes arrival-order application equal
+     * to total-order replay — see lww.ts, and the fuzz test that proved it is not optional.
+     */
+    private readonly lww;
+    private readonly capture;
+    private readonly integrity;
+    private readonly undoStack;
+    /**
+     * Per entity, the highest clock of any `set` the log holds for it.
+     *
+     * The O(1) question "could an `add` that just landed have clobbered a write NEWER than
+     * itself?" — see repair(). Without it the answer costs a scan of the whole log on every
+     * single `add`, which is a per-node cost paid for a case that almost never arises.
+     */
+    private readonly newestSet;
+    /**
+     * nodeId → the port ids each node had BEFORE the log's first op — i.e. at the moment
+     * this replica attached (a snapshot load, or the live document collaboration started
+     * on).
+     *
+     * canonicalizePortOrder() needs it to tell a port ADD from a port UPDATE in the log: a
+     * `ports.<id>` value-write is an add only if the port was not already present, and
+     * presence has to be simulated from somewhere. For a node whose `add` op is in the log,
+     * the op's data is that starting point; for a node that predates the log, this is.
+     * Peers that join from the same snapshot record the same sets, so the derivation stays
+     * identical everywhere — which is the one property canonical order actually needs.
+     */
+    private readonly basePorts;
+    constructor(diagram: DiagramModel, options: ReplicaOptions);
+    get actor(): ActorId;
+    /** The clock to resume from, and the watermark a peer asks us to catch up past. */
+    get clock(): number;
+    /** Links held out of the document because an endpoint node is missing. See integrity.ts. */
+    get quarantinedLinks(): string[];
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /**
+     * Take ops from a peer.
+     *
+     * Returns the ops that were actually NEW to us — which is what you forward to other
+     * peers in a mesh, and which is exactly nothing when the same batch arrives twice.
+     */
+    receive(ops: readonly Op[]): Op[];
+    /**
+     * UNDO MY LAST EDIT — not the last edit.
+     *
+     * The per-actor property is structural: capture only ever sees LOCAL mutations (remote
+     * ops are applied with capture suppressed), so nothing another peer did can be on this
+     * stack to begin with. See undo.ts for what happens when my edit has already been
+     * superseded by someone else's — the short version is that it does nothing, on purpose.
+     */
+    undo(): Op[];
+    redo(): Op[];
+    /**
+     * Group everything `fn` does into ONE undo step.
+     *
+     * Deleting a node with three links is four ops and, without this, four presses of Ctrl-Z.
+     * Grouping is a LOCAL concern — it changes what one keypress takes back, never what goes
+     * on the wire — so two peers may group differently and still converge.
+     */
+    transact<T>(fn: () => T): T;
+    /** Everything we know, in total order — the catch-up payload for a joining peer. */
+    history(): readonly Op[];
+    /**
+     * Card 1: adopt a persisted op-log tail whose EFFECTS ARE ALREADY IN THE MODEL.
+     *
+     * This is `receive()`'s quiet twin, and the difference is the whole point. `receive()` is
+     * for ops the model has not seen: it applies them. `adopt()` is for reopening a saved
+     * document, where the snapshot ALREADY CONTAINS everything the ops did — so it seeds the
+     * log (so a duplicate re-delivery is recognised), the LWW stamps (so a straggling older
+     * write is still refused after a reload) and the repair index, and applies NOTHING.
+     *
+     * Re-applying them would be harmless for content — the reducer's redundant-write guard
+     * would drop every one — but it would bump every version counter and fire a full repaint
+     * for a document that has not changed. Worse, it would make opening a file look like an
+     * edit to anyone watching the model's change events.
+     */
+    adopt(ops: readonly Op[]): void;
+    dispose(): void;
+    /** Track the newest `set` the log holds per entity. See repair(). */
+    private note;
+    /** A local edit: gate it, log it, remember it for undo, broadcast it. */
+    private onLocalOp;
+    /**
+     * Apply an undo's inverse through the model, with capture LIVE — so the op that reaches
+     * the log and the wire is minted by the ordinary local-edit path, with a fresh clock.
+     *
+     * The one thing the undo stack cannot know: the link it is about to act on may be in
+     * QUARANTINE, i.e. not in the document at all. `removeLink()` on a link that is not there
+     * mutates nothing, so capture mints nothing, so the link's presence register still says
+     * "present" — and resurrecting its node would bring back a link the user explicitly took
+     * back. Putting it in the document first makes the removal real. reconcile() re-quarantines
+     * it afterwards if it is still orphaned.
+     */
+    private applyLocalInverse;
+    /** A remote op: buffer it, gate it, apply it, repair what it displaced. */
+    private applyRemote;
+    /**
+     * REBUILD AN ENTITY'S REGISTERS FROM THE LOG.
+     *
+     * An entity's state is not "whatever we applied in the order it arrived". It is:
+     *
+     *     the data of the newest `add` (its current INCARNATION)
+     *       + every `set` on it that is NEWER than that add
+     *
+     * Applied in total order that is the same on every peer, whatever the network did — which
+     * is the entire claim being made. Applying ops AS THEY ARRIVE computes it correctly only if
+     * nothing was lost on the way, and an `add` that lands LATE loses things:
+     *
+     *     Bob holds node C and has been editing it: ports@14, size@15, position@16.
+     *     Alice, elsewhere, deleted C and pressed Ctrl-Z — remove@10, then add@11 carrying her
+     *     snapshot of it.
+     *     Those two reach Bob together, LONG after his own edits.
+     *
+     * Sorted, Bob applies remove@10 (C goes) then add@11 (C returns, as Alice's snapshot). His
+     * own writes at 14, 15, 16 are NEWER than the incarnation — they are not superseded, they
+     * are the truth — but they were applied to a C that no longer exists, and their registers
+     * are already CLAIMED, so re-delivering them changes nothing. Bob is left holding a C that
+     * exists nowhere else in the system, with a log identical to Alice's, and nothing anywhere
+     * reports a problem.
+     *
+     * So after an `add`, the entity is REBUILT: its data, plus every write in the log that is
+     * newer than it, in total order. Both peers then compute the same thing from the same log,
+     * which is what "converges" was supposed to mean all along.
+     *
+     * (My first attempt at this only repaired when the add REPLACED a live entity. The fuzz
+     * kept failing: in the trace above the remove is applied first, so by the time the add
+     * lands there is nothing to replace, and the condition never fired. The question is not
+     * "did I overwrite something" — it is "does the log contain writes newer than this
+     * incarnation".)
+     *
+     * Bounded, not blanket: `newestSet` answers that in O(1), so an `add` for something
+     * genuinely new — every add, essentially always — costs one map lookup.
+     */
+    private repair;
+    /**
+     * Re-apply the per-port writes a LEGACY whole-collection `ports` op just clobbered.
+     *
+     * The whole-collection op asserts every port at its own stamp, but a per-port register
+     * NEWER than it still owns its port. Applying the log's `ports.*` writes newer than the
+     * collection op, in total order, restores exactly those — an add comes back, a newer
+     * removal stays removed, a newer edit re-lands. Both delivery orders then compute the
+     * same collection, which is what the mixed-history spec drives.
+     */
+    private repairPorts;
+    /**
+     * CANONICAL PORT ORDER — integrity.order()'s argument, one level down.
+     *
+     * serialize() writes a node's ports in Map insertion order, and order is part of the
+     * document (the byte oracle sees it; multi-port sides render by it). With per-port
+     * registers, insertion order is a function of ARRIVAL order: two peers that applied
+     * concurrent port adds in a different order hold the same ports in a different
+     * sequence — same content, byte-different files. So the order is DERIVED from the
+     * converged log instead: a port ranks by the stamp of the write that ESTABLISHED its
+     * current incarnation (the first surviving value-write after the last clear), which is
+     * identical on every peer. Ports that predate the log (the node's add op, a snapshot)
+     * have no rank and keep their existing relative order, first — the stable-sort trick
+     * integrity uses for the same problem.
+     *
+     * In the ordinary case — adds with ever-increasing clocks — this reproduces insertion
+     * order exactly and rewrites nothing.
+     */
+    private canonicalizePortOrder;
+    /** An entity of the document, or one integrity is holding aside. */
+    private find;
+}