@grafloria/element 0.3.20 → 0.3.22

package/src/libs/engine/src/sync/sync-adapter.d.ts

@@ -1,243 +0,0 @@
-import type { DiagramModel } from '../models/DiagramModel';
-import { Replica } from '../collab/replica';
-import { type ActorId, type Op } from '../collab/op';
-import { Awareness, type AwarenessState } from './awareness';
-import { type OpBatcherOptions } from './batcher';
-import type { SyncTransport } from './transport';
-import { type VersionVectorJSON } from './version-vector';
-export interface SyncAdapterOptions {
-    /** Batching. `false` sends every op the instant it happens — legal, and a bad idea. */
-    batch?: Omit<OpBatcherOptions, 'onFlush'> | false;
-    /**
-     * Forward ops that were NEW to us on to our other peers.
-     *
-     * OFF by default, because every transport shipped here is a BROADCAST bus — everyone
-     * already got the message, so relaying it doubles the traffic to deliver nothing. Turn
-     * it ON for a point-to-point mesh (WebRTC, a chain of relays) where a peer may be
-     * reachable only through us. It terminates because `Replica.receive()` returns the ops
-     * that were genuinely new, and a re-delivery is new to nobody.
-     */
-    relay?: boolean;
-    /** Periodic anti-entropy, ms. 0 disables it (the tests drive `sync()` by hand). */
-    syncIntervalMs?: number;
-    /** Re-publish our awareness this often so peers do not time us out while we sit still. */
-    heartbeatMs?: number;
-    /** Minimum ms between awareness sends. 60Hz in, ~20Hz out. */
-    awarenessThrottleMs?: number;
-    /** Drop a peer's presence after this long without a word. */
-    awarenessTimeoutMs?: number;
-    /** Injectables, so every timing test is deterministic instead of a race. */
-    setTimer?: (cb: () => void, ms: number) => unknown;
-    clearTimer?: (handle: unknown) => void;
-    setInterval?: (cb: () => void, ms: number) => unknown;
-    clearInterval?: (handle: unknown) => void;
-    now?: () => number;
-}
-/** Counters. Every one of them is something a test asserts on, not decoration. */
-export interface SyncStats {
-    /** Messages handed to the transport. */
-    messagesSent: number;
-    /** Messages taken from the transport. */
-    messagesReceived: number;
-    /** Ops we put on the wire (post-coalescing). */
-    opsSent: number;
-    /** Ops that arrived. */
-    opsReceived: number;
-    /** …of which the log had already seen: duplicate delivery, absorbed. */
-    opsDuplicate: number;
-    /** Ops currently HELD by the causal buffer, waiting for an `add`. */
-    opsHeld: number;
-    /** Anti-entropy rounds we asked for. */
-    syncsRequested: number;
-    /**
-     * Times a peer's frontier turned out to have a HOLE and we resent an actor's history.
-     *
-     * The number that proves the hostile-transport fuzz is not vacuous. If this is 0 after
-     * a thousand lossy trials, the repair path never ran and the test proved nothing.
-     */
-    repairs: number;
-    /** Ops the batcher swallowed because a later write superseded them. */
-    opsCoalesced: number;
-    /** Reconnects observed. */
-    reconnects: number;
-}
-/**
- * Binds one `Replica` to one `SyncTransport`.
- *
- * The replica must be constructed with `onLocalOp` pointing at `adapter.publish` — use
- * {@link createSyncSession}, which does that wiring for you and cannot get it backwards.
- */
-export declare class SyncAdapter {
-    readonly replica: Replica;
-    private readonly transport;
-    private readonly options;
-    readonly awareness: Awareness;
-    private readonly buffer;
-    private readonly vv;
-    /**
-     * Ops we COALESCED AWAY and will therefore never transmit — to anyone, ever.
-     *
-     * They are in our LOG (they really happened) but not in the history we SHARE, so they must
-     * not appear in our frontier or in any catch-up delta we serve. See `sharedHistory()` for
-     * the bug this prevents; it is the difference between "one op per drag" and "the entire
-     * document history, resent on every sync round, forever".
-     */
-    private readonly suppressed;
-    private readonly batcher;
-    private readonly unsubs;
-    private syncTimer;
-    private heartbeatTimer;
-    private awarenessTimer;
-    private awarenessPending;
-    private lastAwarenessSend;
-    private joined;
-    /** Have we ever successfully announced? Distinguishes the first connect from a RECONNECT. */
-    private announced;
-    private disposed;
-    private readonly nowFn;
-    private readonly setTimerFn;
-    private readonly clearTimerFn;
-    private readonly setIntervalFn;
-    private readonly clearIntervalFn;
-    readonly stats: SyncStats;
-    constructor(replica: Replica, transport: SyncTransport, options?: SyncAdapterOptions);
-    get actor(): ActorId;
-    get diagram(): DiagramModel;
-    /** Ops still waiting on an `add` that has not arrived. Should return to 0. */
-    get pendingOps(): Op[];
-    /**
-     * What we tell peers we have.
-     *
-     * THE INVARIANT, and it is worth stating as one because it is the whole correctness
-     * condition of this layer in a single line:
-     *
-     *     frontier() === VersionVector.fromOps(sharedHistory())     — ALWAYS.
-     *
-     * SHARED history, not the local log — an op coalescing withheld is not part of the history
-     * we share with anyone, and advertising it would make every peer chase a hole that can
-     * never be filled. That distinction IS the bug documented on `sharedHistory()`.
-     *
-     * The frontier is a CACHE of that summary, maintained incrementally so we do not rescan
-     * the history on every sync. A cache that disagrees with its source is not a performance
-     * detail; it is a peer lying to the network about what it holds. Claim too much and you
-     * never receive the op you are missing (silent data loss); claim too little and every
-     * round resends an actor's entire history (a silent O(history) amplifier on the flakiest
-     * connections, which is precisely where you can least afford it).
-     *
-     * `sync-adapter.spec.ts` asserts this equality after a full hostile session, which is what
-     * makes it a checked invariant rather than a comment.
-     */
-    frontier(): VersionVectorJSON;
-    /**
-     * Announce ourselves and ask for what we are missing.
-     *
-     * `hello` carries our frontier, so an existing peer can push us the history we lack
-     * without a second round trip — a joining peer should see the document on the first
-     * message, not the third.
-     */
-    join(): void;
-    /** Say goodbye and stop. Best-effort — the peers' TTL is what actually guarantees it. */
-    leave(): void;
-    /**
-     * An anti-entropy round: "here is my frontier; send me what I lack, and tell me yours."
-     *
-     * Called on join, on RECONNECT, and (optionally) on a timer. The timer is not paranoia:
-     * a transport that can drop a message can drop an op, and the ONLY thing that ever
-     * repairs that is asking again.
-     */
-    sync(): void;
-    /** Push any queued local ops onto the wire now. */
-    flush(): void;
-    /**
-     * Our own edits. Wired to `Replica.onLocalOp` — see {@link createSyncSession}.
-     *
-     * The local op is ALREADY in our log and already applied (the Replica did both before
-     * calling us). Our job is only to get it to the others, so a failure to send is not a
-     * failure to edit — it is a divergence the next sync round will close.
-     */
-    publish(op: Op): void;
-    /**
-     * THE LOG AS THE NETWORK SEES IT — our history, minus everything coalescing withheld.
-     *
-     * ---------------------------------------------------------------------------
-     * THE BUG THIS EXISTS TO FIX, WHICH WAS MINE, AND WHICH ONLY THE BROWSER FOUND
-     * ---------------------------------------------------------------------------
-     * A 20-frame drag puts ONE op on the wire and leaves TWENTY in the local log — that is
-     * coalescing working exactly as designed, and the two peers' documents agree perfectly.
-     *
-     * But anti-entropy compares FRONTIERS DERIVED FROM LOGS. So on the next sync round my
-     * frontier said "I hold 20 ops from alice" and the peer's said "I hold 1", and the digest
-     * — which cannot tell a withheld op from a lost one — declared a HOLE and repaired it by
-     * resending my entire history. Measured: `opsSent` went from 1 to 21 on the first sync
-     * after a single drag. And it never settles, because the peer can NEVER obtain the 19 ops
-     * I have deliberately decided never to send. Every sync round, forever, for the rest of
-     * the session, on the most common interaction in the product.
-     *
-     * It is invisible to a convergence oracle — the document is perfectly correct throughout —
-     * and it was invisible to my own frontier-invariant test, which flushed after every single
-     * op and therefore never once coalesced anything while syncing. It took driving a real drag
-     * through a real browser to compose the two.
-     *
-     * THE FIX is a definition, not a patch: THE FRONTIER DESCRIBES THE SHARED LOG. An op we
-     * chose never to transmit is not part of the history we share with anyone, so it is not in
-     * our frontier and it is not in the catch-up delta we serve — to ANY peer, including one
-     * that joins tomorrow. Every peer therefore holds the same shared set, every digest agrees,
-     * and the fast path stays fast.
-     */
-    sharedHistory(): Op[];
-    /**
-     * Publish our cursor / selection / name.
-     *
-     * THROTTLED, not debounced. A debounce would send nothing at all while the mouse keeps
-     * moving — the cursor would only appear once you stopped, which is the exact opposite
-     * of the feature. A throttle sends the newest sample at a bounded rate and drops the
-     * ones in between, which is precisely correct for a value where only the latest matters.
-     */
-    setAwareness(patch: Partial<AwarenessState>): void;
-    private sendAwareness;
-    private send;
-    private sendOps;
-    private onStatus;
-    /**
-     * "Here I am; here is what I have."
-     *
-     * Fired on the first connect and on every RECONNECT, and it is the same two messages
-     * both times — because "I have been away for 30 seconds" and "I have just arrived" are
-     * the same question from the network's point of view, and answering them with one code
-     * path is why the reconnect case cannot rot: it is exercised by every single join.
-     *
-     * Everything both sides did while apart is sitting in their logs. Nothing was lost; it
-     * was only undelivered. `deltaFor` works out exactly what each side missed.
-     */
-    private announce;
-    private onMessage;
-    /** Ship a peer exactly the ops its frontier says it does not have. */
-    private answer;
-    /**
-     * The receive path, in the only order that works.
-     *
-     *   CausalBuffer → Replica → VersionVector → relay
-     *
-     * The buffer FIRST, and that ordering is the load-bearing part: an op that reaches the
-     * Replica before its `add` is logged, stamped, and silently dropped, and no later
-     * delivery can ever resurrect it (the log de-duplicates it, and the LWW gate now refuses
-     * it as superseded by itself). Once it is past the Replica it is too late. See
-     * causal-buffer.ts.
-     */
-    private ingest;
-    private stopTimers;
-    dispose(): void;
-}
-export interface SyncSessionOptions extends SyncAdapterOptions {
-    actor: ActorId;
-    /** Resume the Lamport clock from a persisted tail. */
-    startClock?: number;
-}
-/**
- * Build a Replica and a SyncAdapter, correctly wired to each other.
- *
- * The wiring is one line and it is easy to forget, and forgetting it produces the exact
- * failure this codebase is famous for: everything green, every unit test passing, and not
- * one edit ever reaching the wire — because `onLocalOp` went nowhere.
- */
-export declare function createSyncSession(diagram: DiagramModel, transport: SyncTransport, options: SyncSessionOptions): SyncAdapter;