@grafloria/element 0.3.18 → 0.3.19

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

@@ -0,0 +1,47 @@
+import type { ActorId, Op } from './op';
+/** The stamp of the write that currently owns a register. */
+export interface Stamp {
+    clock: number;
+    actor: ActorId;
+}
+/**
+ * Which write currently owns each register.
+ *
+ * The key is (target, id, path) for a property, and (target, id, presence) for whether
+ * the entity exists at all — because an add/remove race is the same kind of race as a
+ * concurrent property write, and deserves the same machinery rather than a special case.
+ */
+export declare class LwwRegistry {
+    private readonly stamps;
+    /**
+     * THE ONE PLACE A REGISTER KEY IS BUILT. Nothing else may construct one.
+     *
+     * The separator is NUL — it cannot occur in a property path, so a property register can
+     * never collide with the presence slot of its own entity. It also RENDERS AS A SPACE in
+     * every editor, terminal and diff, which is how all three of Card 4's new call sites came
+     * to be written with a literal ' ' and to key a map that did not exist. The presence
+     * barrier, the never-seen-yet check and the canonical entity order were ALL dead on
+     * arrival; every unit test passed; and the fuzz found it in one trial. Hence: one builder,
+     * no string literals, and a separator that is stated rather than typed.
+     */
+    private static readonly SEP;
+    private static presenceKey;
+    private static pathKey;
+    private static key;
+    /**
+     * Should this op be applied?
+     *
+     * False when a NEWER write already owns the register — the op is not late, it is
+     * SUPERSEDED, and applying it would move the register backwards. This is the single
+     * check that makes arrival-order application equal to total-order replay.
+     *
+     * Records the stamp as a side effect when the answer is yes: an op that wins now owns
+     * its register.
+     */
+    admit(op: Op): boolean;
+    /** Who currently owns a register — for debugging, and for a UI that shows attribution. */
+    owner(op: Op): Stamp | undefined;
+    /** The stamp that decided whether an entity exists. Undefined if never seen. */
+    presenceOf(target: Op['target'], id: string): Stamp | undefined;
+    get size(): number;
+}

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

@@ -0,0 +1,188 @@
+"use strict";
+// Wave 9 — Card 0: the last-writer-wins register table.
+//
+// ---------------------------------------------------------------------------
+// THIS FILE EXISTS BECAUSE A FUZZ TEST DEMOLISHED MY OWN CLAIM
+// ---------------------------------------------------------------------------
+//
+// op-log.ts originally asserted, in a confident block comment, that a total order plus a
+// deterministic reducer ALREADY gives convergence, and that a CRDT was a later card's
+// problem. That is TRUE — and only true — if every peer REPLAYS THE ENTIRE LOG IN ORDER
+// on every change. No live system does that; it is O(history) per keystroke. A live peer
+// applies each op AS IT ARRIVES, and arrival order is not total order.
+//
+// The 200-trial randomised fuzz found the counterexample in seconds:
+//
+//     Alice sets position=(100,200)   |  Bob sets position=(300,400)      [concurrent]
+//     Alice applies hers, then Bob's  →  (300,400)
+//     Bob applies his, then Alice's   →  (100,200)
+//                                        ^^^^^^^^^ DIVERGED
+//
+// Both peers saw the same two ops. Both applied both. They disagree. And nothing anywhere
+// reports an error — the two users simply see different diagrams forever, which is the
+// precise failure mode a collaboration engine exists to prevent.
+//
+// The fix is the one every CRDT text starts with, and it is small: each REGISTER (an
+// entity's property path) remembers the stamp of the write that last won it. An arriving
+// op that is OLDER than the register's current stamp is REFUSED — not applied and then
+// overwritten, but never applied at all. Incremental application then produces exactly
+// the state a full in-order replay would, which is what makes "apply as they arrive"
+// safe.
+//
+// A stamp is (clock, actor) — the same total order the log sorts by. So "older" means the
+// same thing everywhere, on every peer, which is the entire trick.
+//
+// ---------------------------------------------------------------------------
+// WHAT THIS DOES AND DOES NOT SETTLE
+// ---------------------------------------------------------------------------
+// SETTLED: concurrent writes to the same property (LWW), concurrent writes to different
+// properties of the same entity (no conflict — different registers, both survive), and
+// add/remove races (presence is itself a register).
+//
+// ---------------------------------------------------------------------------
+// CARD 4 SETTLED THE OPEN QUESTION: PRESENCE STAYS LWW.
+// ---------------------------------------------------------------------------
+// Card 0 asked whether an observed-remove set should replace LWW presence, and named the
+// scenario: delete a node while a colleague attaches a link to it. Working that scenario
+// through shows the framing is wrong. `remove node N` and `add link L` write DIFFERENT
+// REGISTERS — they do not race at all. Both apply, on every peer, under LWW and under an
+// OR-set alike, and the link is left dangling either way. AN OR-SET DOES NOT FIX IT.
+//
+// The real defect is a REFERENTIAL INTEGRITY violation ACROSS registers, which no
+// per-register presence policy can address. So LWW presence stays — it is convergent, it
+// is simple, and it is not the bug — and integrity.ts fixes the actual problem, as a
+// DERIVED rule (a link is live iff its endpoints resolve) that needs no op of its own.
+// The full user-facing argument is in the header of integrity.spec.ts.
+//
+// ---------------------------------------------------------------------------
+// WHAT THIS FILE ADDED IN CARD 4: THE PRESENCE BARRIER
+// ---------------------------------------------------------------------------
+// A property write is refused if it is OLDER THAN THE ENTITY'S CURRENT PRESENCE STAMP.
+//
+// This is not tidiness; without it, resurrection diverges, and the fuzz proves it. A node
+// is deleted and later brought back (an undo of the delete is exactly an `add` with a
+// fresh clock). A peer that saw a colleague's property write BEFORE the delete dropped it
+// (the entity was gone). A peer that receives that same write AFTER the resurrection — a
+// partitioned peer, a re-delivery, a mesh relay — finds the entity present again and
+// APPLIES it. Two peers, same ops, different documents, forever, and nothing reports an
+// error.
+//
+// The barrier states the rule that was always implied: a write that predates the entity's
+// current incarnation is not a write to THIS entity. The resurrected node comes back
+// exactly as it was when it was deleted, on every peer, whatever the network did.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LwwRegistry = void 0;
+/** Total order on stamps — identical to compareOps, and it must stay that way. */
+function newer(a, b) {
+    if (a.clock !== b.clock)
+        return a.clock > b.clock;
+    return a.actor > b.actor;
+}
+/**
+ * Which write currently owns each register.
+ *
+ * The key is (target, id, path) for a property, and (target, id, presence) for whether
+ * the entity exists at all — because an add/remove race is the same kind of race as a
+ * concurrent property write, and deserves the same machinery rather than a special case.
+ */
+class LwwRegistry {
+    constructor() {
+        this.stamps = new Map();
+    }
+    static presenceKey(target, id) {
+        const s = LwwRegistry.SEP;
+        return `${target}${s}${id}${s}${s}presence`;
+    }
+    static pathKey(target, id, path) {
+        const s = LwwRegistry.SEP;
+        return `${target}${s}${id}${s}${path}`;
+    }
+    static key(op) {
+        return op.op === 'set'
+            ? LwwRegistry.pathKey(op.target, op.id, op.path)
+            : LwwRegistry.presenceKey(op.target, op.id);
+    }
+    /**
+     * Should this op be applied?
+     *
+     * False when a NEWER write already owns the register — the op is not late, it is
+     * SUPERSEDED, and applying it would move the register backwards. This is the single
+     * check that makes arrival-order application equal to total-order replay.
+     *
+     * Records the stamp as a side effect when the answer is yes: an op that wins now owns
+     * its register.
+     */
+    admit(op) {
+        const key = LwwRegistry.key(op);
+        const incoming = { clock: op.clock, actor: op.actor };
+        // THE PRESENCE BARRIER (Card 4). A property write that predates the entity's CURRENT
+        // INCARNATION is not a write to this entity — it belongs to a version of it that was
+        // deleted. Refuse it, permanently, and identically on every peer, whether or not this
+        // particular peer happened to be holding the entity when the write first went past.
+        //
+        // Without this, RESURRECTION DIVERGES, and the fuzz finds it in a handful of trials.
+        // A node is deleted and later brought back (an undo of a delete is exactly an `add`
+        // with a fresh clock). A peer that saw a colleague's property write BEFORE the delete
+        // dropped it — the entity was gone. A peer that receives that same write AFTER the
+        // resurrection (a partitioned peer, a re-delivery, a mesh relay) finds the entity
+        // present again and APPLIES it. Same ops, two documents, forever, no error anywhere.
+        //
+        // The barrier states the rule that was always implied: a resurrected node comes back
+        // exactly as it was when it was deleted, on every peer, whatever the network did.
+        if (op.op === 'set' && op.target !== 'diagram') {
+            const presence = this.stamps.get(LwwRegistry.presenceKey(op.target, op.id));
+            if (presence && newer(presence, incoming))
+                return false;
+        }
+        // THE PORTS-COLLECTION BARRIER (wave14). Ports are per-port registers now
+        // (`ports.<portId>`), but every log persisted before that — and any old peer still
+        // in the room mid-rollout — writes the LEGACY whole-collection `ports` register,
+        // which asserts the ENTIRE collection at its stamp: every port it lists, and the
+        // absence of every port it does not. So a per-port write OLDER than the newest
+        // whole-collection write is void — it is a write to a collection state that the
+        // whole-collection op has since replaced wholesale — exactly as the presence
+        // barrier above voids writes that predate an entity's incarnation. Without this,
+        // the two register families would be gated independently and a mixed history would
+        // converge to different documents depending on arrival order (the spec drives both
+        // orders). The other direction — a whole-collection write landing OVER newer
+        // per-port writes — cannot be refused here (it is one register claiming many) and
+        // is instead REPAIRED from the log after it applies; see Replica.applyRemote.
+        if (op.op === 'set' && op.path.startsWith('ports.')) {
+            const whole = this.stamps.get(LwwRegistry.pathKey(op.target, op.id, 'ports'));
+            if (whole && newer(whole, incoming))
+                return false;
+        }
+        const current = this.stamps.get(key);
+        if (current && !newer(incoming, current))
+            return false;
+        this.stamps.set(key, incoming);
+        return true;
+    }
+    /** Who currently owns a register — for debugging, and for a UI that shows attribution. */
+    owner(op) {
+        return this.stamps.get(LwwRegistry.key(op));
+    }
+    /** The stamp that decided whether an entity exists. Undefined if never seen. */
+    presenceOf(target, id) {
+        if (target === 'diagram')
+            return undefined;
+        return this.stamps.get(LwwRegistry.presenceKey(target, id));
+    }
+    get size() {
+        return this.stamps.size;
+    }
+}
+exports.LwwRegistry = LwwRegistry;
+/**
+ * THE ONE PLACE A REGISTER KEY IS BUILT. Nothing else may construct one.
+ *
+ * The separator is NUL — it cannot occur in a property path, so a property register can
+ * never collide with the presence slot of its own entity. It also RENDERS AS A SPACE in
+ * every editor, terminal and diff, which is how all three of Card 4's new call sites came
+ * to be written with a literal ' ' and to key a map that did not exist. The presence
+ * barrier, the never-seen-yet check and the canonical entity order were ALL dead on
+ * arrival; every unit test passed; and the fuzz found it in one trial. Hence: one builder,
+ * no string literals, and a separator that is stated rather than typed.
+ */
+LwwRegistry.SEP = '\0';
+//# sourceMappingURL=lww.js.map

package/src/libs/engine/src/collab/lww.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lww.js","sourceRoot":"","sources":["../../../../../../engine/src/collab/lww.ts"],"names":[],"mappings":"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"}

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-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"op-log.js","sourceRoot":"","sources":["../../../../../../engine/src/collab/op-log.ts"],"names":[],"mappings":"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"}

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 {};