@grafloria/element 0.3.19 → 0.3.21

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

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

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