@grafloria/element 0.3.20 → 0.3.21

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

@@ -1,84 +0,0 @@
-"use strict";
-// Wave 9 (Collaboration) — Card 0: the operation substrate.
-//
-// The op log is the thing every other collaboration card stands on: CRDT convergence
-// (Card 4), the sync transport (Card 5), anchored comments (Card 6) and presentation
-// mode (Card 7) all consume it. It exists because the engine's TWO existing candidates
-// could not do the job:
-//
-//   • Command.serialize() is WRITE-ONLY — there is no deserializer anywhere in the tree.
-//   • DiagramIncremental is a WHOLE-ENTITY diff — so a concurrent move and rename of the
-//     same node silently throws one of them away.
-//
-// Ops are per-PROPERTY, carry a Lamport clock (causality, not wall time), sort into a
-// total order identical on every peer, and are captured from `trackChange` — the single
-// funnel every mutation in this engine already passes through.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.UndoStack = exports.ReferentialIntegrity = exports.LwwRegistry = exports.Replica = exports.OpCapture = exports.replay = exports.OpLog = exports.OpApplyError = exports.applyEntitySet = exports.applyOp = exports.opId = exports.compareOps = exports.LamportClock = void 0;
-var op_1 = require("./op");
-Object.defineProperty(exports, "LamportClock", { enumerable: true, get: function () { return op_1.LamportClock; } });
-Object.defineProperty(exports, "compareOps", { enumerable: true, get: function () { return op_1.compareOps; } });
-Object.defineProperty(exports, "opId", { enumerable: true, get: function () { return op_1.opId; } });
-var apply_op_1 = require("./apply-op");
-Object.defineProperty(exports, "applyOp", { enumerable: true, get: function () { return apply_op_1.applyOp; } });
-Object.defineProperty(exports, "applyEntitySet", { enumerable: true, get: function () { return apply_op_1.applyEntitySet; } });
-Object.defineProperty(exports, "OpApplyError", { enumerable: true, get: function () { return apply_op_1.OpApplyError; } });
-var op_log_1 = require("./op-log");
-Object.defineProperty(exports, "OpLog", { enumerable: true, get: function () { return op_log_1.OpLog; } });
-Object.defineProperty(exports, "replay", { enumerable: true, get: function () { return op_log_1.replay; } });
-var capture_1 = require("./capture");
-Object.defineProperty(exports, "OpCapture", { enumerable: true, get: function () { return capture_1.OpCapture; } });
-var replica_1 = require("./replica");
-Object.defineProperty(exports, "Replica", { enumerable: true, get: function () { return replica_1.Replica; } });
-var lww_1 = require("./lww");
-Object.defineProperty(exports, "LwwRegistry", { enumerable: true, get: function () { return lww_1.LwwRegistry; } });
-// Card 4. The one invariant a diagram cannot survive breaking, and the undo that knows it
-// is not alone in the room.
-var integrity_1 = require("./integrity");
-Object.defineProperty(exports, "ReferentialIntegrity", { enumerable: true, get: function () { return integrity_1.ReferentialIntegrity; } });
-var undo_1 = require("./undo");
-Object.defineProperty(exports, "UndoStack", { enumerable: true, get: function () { return undo_1.UndoStack; } });
-// ===========================================================================
-// THERE IS NO YJS BINDING, AND THIS IS WHERE YOU WOULD HAVE LOOKED FOR IT
-// ===========================================================================
-//
-// Card 4 asked for "an optional binding to Yjs for teams already standardized on it". It was
-// not built. The reasoning, so that nobody has to reconstruct it:
-//
-// WHAT WOULD IT BUY? Not convergence — we have that. Yjs's Y.Map is a per-key LWW register
-// map, which is exactly, precisely what `LwwRegistry` already is. Adopting Yjs would replace
-// the one part of this system that was already correct, small, and free.
-//
-// The honest answer is INTEROP: a team with a running y-websocket server, y-indexeddb for
-// offline, and y-protocols/awareness for presence could point them at this engine. That is a
-// real thing to want. It is also a TRANSPORT concern, and this engine is already transport-
-// agnostic: a Replica needs nothing but something that can move an array of JSON ops
-// (`onLocalOp` out, `receive()` in). Wave 9's sync card is building exactly that seam. A Yjs
-// binding would not open a door that is already open.
-//
-// AND IT WOULD PUNCH A HOLE. Everything this card actually spent its time on lives ABOVE the
-// register layer, and the mutation matrix proves each piece is load-bearing:
-//
-//     • referential integrity  (a link whose endpoint node is gone must not survive)
-//     • the presence barrier   (a write older than an entity's incarnation is void)
-//     • repair-from-log        (an `add` must not clobber writes newer than itself)
-//     • canonical entity order (Map insertion order is paint order, and it must converge)
-//     • supersession-aware undo
-//
-// Yjs supplies NONE of them. A peer merging through a Y.Doc would hold dangling links,
-// diverge on resurrection, and paint overlapping nodes in a different order — while believing
-// it had converged, because at the register level it HAD. So the binding is either a second,
-// weaker convergence path (a correctness hole, and the worst kind: silent), or it is all five
-// mechanisms re-implemented on top of Y.Doc observers — at which point Yjs is contributing a
-// wire format, in exchange for a hard dependency and a mapping layer to keep in step forever.
-//
-// The one thing Yjs would genuinely add is Y.Text: character-level merge of two people typing
-// in the same node label, where we take last-writer-wins. That is a real gap and it is a
-// SMALL one — a diagram label is a few words, every diagram tool on the market does LWW on it,
-// and if we ever want it, the answer is a text CRDT on that one register, not a document model
-// swap.
-//
-// So: not built. Last wave an agent built a canvas tier, measured it at 8.9× slower than what
-// we had, and deleted its own card; that was the best result of the wave. A roadmap sentence
-// is not a reason.
-//# sourceMappingURL=index.js.map

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

@@ -1,178 +0,0 @@
-import { DiagramModel } from '../models/DiagramModel';
-import { LinkModel } from '../models/LinkModel';
-import type { LwwRegistry } from './lww';
-import { type Op } from './op';
-/**
- * Holds the diagram to its one hard invariant, and buffers the ops that cannot be applied
- * yet.
- *
- * Drives the model directly. Its writes MUST NOT be captured as ops (they are derived, and
- * broadcasting them would race with the very ops they are derived from) — the Replica runs
- * every call into this class with capture suppressed.
- */
-export declare class ReferentialIntegrity {
-    private readonly diagram;
-    private readonly lww;
-    /** Links that logically exist but whose endpoints do not resolve. Held, not destroyed. */
-    private readonly quarantine;
-    /**
-     * portId → nodeId. OUR OWN, not the engine's.
-     *
-     * DiagramModel keeps a portIndex, and it would be the obvious thing to resolve endpoints
-     * through. It cannot be used here, and the reason is a genuine ordering trap:
-     *
-     *     installNode():  nodes.set(id, node)          ← the node is queryable
-     *                     trackChange('nodes', …)      ← CAPTURE FIRES HERE
-     *                     indexNodePorts(node)         ← the port index catches up HERE
-     *
-     *     removeNode():   nodes.delete(id)
-     *                     unindexNodePorts(node)       ← the port index is updated FIRST
-     *                     trackChange('nodes', …)      ← capture fires here
-     *
-     * So on ADD the engine's port index is a beat BEHIND the change event we react to, and on
-     * REMOVE it is a beat AHEAD. Reconciling on the add would find the new node's ports
-     * missing and refuse to release the links waiting for it — for good, since nothing would
-     * ever ask again. An asymmetry like that is exactly the kind of thing that works in every
-     * test and fails in a session.
-     *
-     * The node itself is fully queryable at both moments, so we index from the node and the
-     * ordering stops mattering.
-     */
-    private readonly portOwner;
-    /**
-     * Is the entity order possibly WRONG, and what is the newest presence stamp in each
-     * collection?
-     *
-     * canonicalize() is O(n) even when it changes nothing, and it used to run on every structural
-     * op — which is the other half of what made a bulk load quadratic. But order can only break
-     * one way: an entity APPENDED with a presence stamp OLDER than one already in the collection.
-     * Adds in the ordinary course of events arrive with ever-increasing clocks, so the collection
-     * stays sorted for free and the scan is pure waste. Removals cannot unsort anything.
-     *
-     * So: watch for a stamp that goes backwards, and only then pay for the sort.
-     */
-    private orderDirty;
-    private readonly maxPresence;
-    constructor(diagram: DiagramModel, lww: LwwRegistry);
-    /** Link ids currently held out of the document. Small; usually empty. */
-    get quarantined(): string[];
-    /** Is this link being held out of the document? */
-    isHeld(id: string): boolean;
-    /** The held instance, so a write can still reach a link that is out of the document. */
-    held(id: string): LinkModel | undefined;
-    /**
-     * Force a held link back into the document, endpoints or no endpoints.
-     *
-     * Only for undo: to UNDO the creation of a link that is currently quarantined, the link
-     * has to be in the document for `removeLink()` to be a real mutation that capture can
-     * mint an op from. Without this the undo silently does nothing, the link's presence
-     * register still says "present", and resurrecting its node brings back a link the user
-     * explicitly took back. The following reconcile() re-quarantines it if it is still
-     * orphaned, so this is a keyhole, not a hole.
-     */
-    release(id: string): void;
-    /** Keep the port map and the order watermark current with the ops that change structure. */
-    note(op: Op): void;
-    private indexPorts;
-    /**
-     * Can this op be applied to the document right now?
-     *
-     * Returns `true` when the op was DIVERTED — written into a link this class is holding out
-     * of the document — in which case the caller must not also hand it to applyOp.
-     *
-     * A held link still takes its property writes, through the SAME mutators a live one uses.
-     * An entity that took a different write path in quarantine would drift from a live one, and
-     * the drift would only surface on release, long after anything could point at the cause.
-     */
-    divert(op: Op): boolean;
-    /**
-     * The INCREMENTAL invariant check: only what THIS op could possibly have broken.
-     *
-     * A full sweep after every local edit is O(links), and a local edit stream is n ops long, so
-     * a bulk load — importing a document into a live session — was O(n²). Measured: 2,000 nodes
-     * and 2,000 links took 8.5 SECONDS through a Replica, against ~90ms without one. Nothing
-     * caught it, because no perf gate in this repo drives a Replica. That is the shape of defect
-     * this codebase keeps shipping, and I very nearly shipped another one.
-     *
-     * So each op pays only for what it can actually affect:
-     *
-     *   add node      → only a QUARANTINED link can become live. The quarantine is almost always
-     *                   empty, so this is free. (A live link cannot break when a node ARRIVES.)
-     *   add link      → that one link. O(1).
-     *   remove link   → drop it from the quarantine. O(1).
-     *   remove node   → live links attached to it can be orphaned. O(links) — but deleting a node
-     *                   is a human action, not a loop.
-     *   set ports     → same as removing a node: an endpoint may have vanished.
-     *   set endpoints → that one link. O(1).
-     *
-     * A bulk load is all adds, so it is linear again.
-     */
-    settle(op: Op): void;
-    /**
-     * Re-evaluate the invariant over the WHOLE document.
-     *
-     * Once per BATCH of remote ops, and once at the end of a replay — where the invariant is a
-     * function of the batch's final state, not of the path through it (a link orphaned mid-batch
-     * and re-parented by the end of it was never really orphaned).
-     */
-    reconcile(): void;
-    /**
-     * Evict links that have lost an endpoint — and RE-RESOLVE the cached endpoint node ids of
-     * the survivors.
-     *
-     * That re-resolution is not housekeeping, it is a bug fix. installLink() backfills
-     * sourceNodeId/targetNodeId from the port index exactly once, at install, and only if they
-     * are unset. A link applied BEFORE its node arrived (which the network is entitled to do,
-     * and which a mesh does routinely) indexes nothing and keeps `undefined` node ids FOREVER.
-     * They are in serialize(), so the peers' documents differ — and the renderer resolves port
-     * SIDES through them, so the link is drawn wrong on one peer and right on the other.
-     * Deriving them makes them a function of state, and the arrival order stops mattering.
-     */
-    private evictOrphans;
-    /** Give back the links whose endpoints have come home. */
-    private releaseResolvable;
-    /** One link, either way. */
-    private checkLink;
-    /**
-     * ORDER IS PART OF THE DOCUMENT, and the fuzz is what proved it.
-     *
-     * `serialize()` writes `nodes` as `Array.from(this.nodes.values())` — Map INSERTION order.
-     * And the SVG renderer sorts nodes by `zIndex` with a STABLE sort, so when zIndex ties (the
-     * overwhelmingly common case: nobody sets it, everything is 0) THE ARRAY ORDER IS THE PAINT
-     * ORDER. It decides which of two overlapping nodes is on top.
-     *
-     * Insertion order is a function of the path a peer took, not of the state it arrived at:
-     *
-     *     Alice deletes node `a` and undoes → `a` is re-inserted, so it moves to the END.
-     *     Bob receives the re-add BEFORE the delete → the delete is then refused as superseded,
-     *     Bob never removed anything, and `a` never moves.
-     *
-     * Same ops. Same content, field for field. Different `nodes` array. The two of them paint
-     * overlapping nodes in a different order and save byte-different files. The fuzz caught it on
-     * trial 2 and it would never have occurred to me.
-     *
-     * The fix is the same shape as everything else in this file: DERIVE the order from the
-     * converged state instead of inheriting it from the delivery path. An entity's rank is the
-     * stamp of the write that established its CURRENT INCARNATION. That is identical on every
-     * peer, and in the ordinary case (add a, add b, add c) it reproduces insertion order exactly,
-     * so nothing that was not already broken changes.
-     *
-     * Gated on `orderDirty`, because the sort is O(n) even when it changes nothing and adds
-     * normally arrive with ever-increasing clocks — see the field's comment.
-     */
-    private canonicalizeIfDirty;
-    private order;
-    /** Drop a link from quarantine for good — its presence register says it is gone. */
-    forget(op: Op): void;
-    /** The node that owns a port, IF that node is currently in the document. */
-    private ownerOf;
-    private endpointsResolve;
-    /**
-     * Derive the cached endpoint node ids.
-     *
-     * Assigned directly, NOT through a mutator, and that is deliberate: these are DERIVED
-     * state, not authored state. A trackChange here would emit an op, broadcast a value every
-     * peer can compute for itself, and race with the ops it was derived from.
-     */
-    private resolveEndpoints;
-}