@grafloria/element 0.3.20 → 0.3.22

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

@@ -1,50 +0,0 @@
-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

@@ -1,167 +0,0 @@
-"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

@@ -1,120 +0,0 @@
-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

@@ -1,118 +0,0 @@
-"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

@@ -1,188 +0,0 @@
-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;
-}