@grafloria/element 0.3.18 → 0.3.19

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/op.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"op.js","sourceRoot":"","sources":["../../../../../../engine/src/collab/op.ts"],"names":[],"mappings":";AAAA,yDAAyD;AACzD,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,yBAAyB;AACzB,8EAA8E;AAC9E,EAAE;AACF,mFAAmF;AACnF,oFAAoF;AACpF,UAAU;AACV,EAAE;AACF,mFAAmF;AACnF,qFAAqF;AACrF,sFAAsF;AACtF,gEAAgE;AAChE,EAAE;AACF,sFAAsF;AACtF,sFAAsF;AACtF,uFAAuF;AACvF,kFAAkF;AAClF,iFAAiF;AACjF,gDAAgD;AAChD,EAAE;AACF,8EAA8E;AAC9E,gFAAgF;AAChF,oFAAoF;AACpF,2BAA2B;AAC3B,EAAE;AACF,8EAA8E;AAC9E,OAAO;AACP,8EAA8E;AAC9E,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,qFAAqF;AACrF,sFAAsF;AACtF,wCAAwC;AACxC,EAAE;AACF,mFAAmF;AACnF,oFAAoF;AACpF,mFAAmF;AACnF,yBAAyB;;;AA8FzB,gCAEC;AAWD,gCAQC;AAGD,oBAEC;AAjCD;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,EAAS;IAClC,OAAO,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC;AAClD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,UAAU,CAAC,CAAK,EAAE,CAAK;IACrC,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;IAClD,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,8EAA8E;IAC9E,kFAAkF;IAClF,mFAAmF;IACnF,iDAAiD;IACjD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,wFAAwF;AACxF,SAAgB,IAAI,CAAC,EAAM;IACzB,OAAO,GAAG,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAa,YAAY;IAGvB,YAA6B,KAAc,EAAE,KAAK,GAAG,CAAC;QAAzB,UAAK,GAAL,KAAK,CAAS;QACzC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;QAC1E,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,8CAA8C;IAC9C,IAAI;QACF,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,IAAY;QAClB,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IAC3C,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF;AA7BD,oCA6BC"}

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