@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/sync/batcher.d.ts

@@ -0,0 +1,84 @@
+import type { Op } from '../collab/op';
+/**
+ * Drop every `set` that a later `set` in the same batch overwrites.
+ *
+ * A stable filter: elements are removed, never reordered. Exported because it is worth
+ * testing on its own, and because it is the part that is easy to get wrong.
+ *
+ * RETURNS THE DROPPED OPS TOO, AND THAT IS NOT A CONVENIENCE — IT IS LOAD-BEARING.
+ *
+ * An op that is coalesced away is an op the sender HAS (it is in its log) and the receiver
+ * will NEVER have. Anti-entropy compares frontiers derived from logs, so unless the sender
+ * knows exactly which ops it deliberately withheld, its frontier says "I hold 20 ops" while
+ * the peer holds 1 — a gap indistinguishable from a lost packet, which triggers a full
+ * history REPAIR on the next sync round. And the round after. Forever, because the peer can
+ * never obtain ops that will never be sent.
+ *
+ * That is a silent O(history) resend after EVERY DRAG — the most common interaction there
+ * is. See `SyncAdapter.suppressed`.
+ */
+export declare function coalesce(ops: readonly Op[]): {
+    kept: Op[];
+    dropped: Op[];
+};
+export interface OpBatcherOptions {
+    /**
+     * Where a flushed batch goes. Never called with an empty `kept`.
+     *
+     * `dropped` are the ops COALESCED AWAY — ops the sender holds and the receiver will never
+     * see. The adapter must record them, or its frontier will advertise ops it is never going
+     * to send and every anti-entropy round will try to "repair" the gap. See `coalesce()`.
+     */
+    onFlush: (kept: Op[], dropped: Op[]) => void;
+    /**
+     * How long to accumulate, in ms. 16 ≈ one frame: a drag's pointermoves collapse into
+     * one message per frame, which is the point.
+     *
+     * 0 means "flush on the next macrotask", which for a drag means one message per
+     * pointermove — i.e. no batching at all. It is a legal setting (a test may want it) and
+     * a bad default.
+     */
+    intervalMs?: number;
+    /**
+     * Flush immediately once the queue reaches this many ops, regardless of the timer.
+     * Backpressure: a scripted bulk import can emit ten thousand ops inside one tick, and
+     * an unbounded queue would hand the transport a single ten-megabyte frame.
+     */
+    maxBatch?: number;
+    /** Injectable timer, so tests are deterministic and Node/browser both work. */
+    setTimer?: (cb: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+/**
+ * Accumulates local ops and flushes them as one coalesced, correctly-ordered batch.
+ */
+export declare class OpBatcher {
+    private readonly options;
+    private queue;
+    private timer;
+    private disposed;
+    private readonly intervalMs;
+    private readonly maxBatch;
+    private readonly setTimer;
+    private readonly clearTimer;
+    /** Ops that went in. */
+    queued: number;
+    /** Ops that went out. `queued - sent` is what coalescing saved. */
+    sent: number;
+    /** Flushes performed. */
+    batches: number;
+    constructor(options: OpBatcherOptions);
+    get size(): number;
+    push(op: Op): void;
+    /** Send whatever is queued, right now. Idempotent, and a no-op when empty. */
+    flush(): void;
+    /**
+     * Drop the queue WITHOUT sending.
+     *
+     * Used on disconnect, and it is safe for exactly one reason: the ops are already in the
+     * local log, so the peer will get them from the next anti-entropy round. If they were
+     * not, this would be a silent data-loss hatch.
+     */
+    discard(): void;
+    dispose(): void;
+}

package/src/libs/engine/src/sync/causal-buffer.d.ts

@@ -0,0 +1,81 @@
+import type { DiagramModel } from '../models/DiagramModel';
+import { type Op } from '../collab/op';
+export interface CausalBufferOptions {
+    /**
+     * Hard cap on held ops. A malicious or badly broken peer must not be able to make us
+     * buffer without limit; past the cap we release the oldest held op anyway (it will
+     * apply as a no-op and be logged, which is exactly what would have happened before this
+     * file existed — degraded, but bounded, and counted so it is visible).
+     */
+    maxPending?: number;
+}
+/** Where an op sits: released to the replica, or waiting on a dependency. */
+export interface CausalSplit {
+    /** Ready NOW, in total order. Hand straight to `Replica.receive()`. */
+    ready: Op[];
+    /** Newly held this round (diagnostics). */
+    held: number;
+}
+/**
+ * Holds ops whose entity has not been added yet, and releases them the instant it is.
+ *
+ * Sits BETWEEN the transport and the Replica. Nothing it holds has touched the log, the
+ * clock or the LWW registry — which is the whole point: an op the replica has never seen
+ * is an op that can still be applied later.
+ */
+export declare class CausalBuffer {
+    private readonly diagram;
+    /** Entity ids we have ever seen an `add` for — including ones since deleted. */
+    private readonly known;
+    /** Held ops, keyed by the entity id they are waiting on. */
+    private readonly waiting;
+    /** opIds already held — a duplicate delivery must not double the buffer. */
+    private readonly heldIds;
+    private readonly maxPending;
+    /** Ops force-released because the buffer was full. Should be 0. Watch it. */
+    overflowed: number;
+    constructor(diagram: DiagramModel, options?: CausalBufferOptions);
+    get pendingCount(): number;
+    /**
+     * WE created an entity. Record it — the transport will never tell us about it.
+     *
+     * THE FUZZ FOUND THIS ONE, AND IT IS A PERMANENT HANG, NOT A HICCUP.
+     *
+     * `known` was fed from exactly two places: entities on the diagram at construction, and
+     * `add` ops that arrived from PEERS. A node the local user creates during the session is
+     * in NEITHER — so as far as the buffer was concerned, an entity this peer invented did
+     * not exist.
+     *
+     * Now watch a peer edit it. Bob creates node X. Alice learns about it, drags it, and
+     * sends `set(X, position)`. It arrives at Bob, whose buffer asks "have I seen an `add`
+     * for X?", answers NO, and holds it — waiting for an `add(X)` that is never coming, from
+     * anyone, ever. It cannot come: the only `add(X)` in existence is Bob's OWN, it is
+     * already in Bob's log, and Alice's anti-entropy correctly concludes that Bob already
+     * has it and never echoes it back.
+     *
+     * So Bob's node freezes wherever it was when he made it, Alice watches it move, and the
+     * two documents differ forever — over the single most ordinary interaction in a
+     * collaborative editor: one person moving another person's node. On a healthy transport
+     * it never fires (the `set` cannot overtake an `add` that was never sent), which is
+     * exactly why it took a reordering channel to find it.
+     *
+     * No drain is needed. A peer can only `set` an entity it has learned about, which means
+     * our `add` had already reached it — so nothing can be waiting on an id at the moment we
+     * create it. The registration alone closes the hole.
+     */
+    noteLocal(op: Op): void;
+    /**
+     * Split an arriving batch into what can be applied now and what must wait — and fold in
+     * anything that was already waiting and has just become releasable.
+     */
+    admit(incoming: readonly Op[]): CausalSplit;
+    /** Everything we are still holding — for a status panel, and for the tests. */
+    pending(): Op[];
+    private isReady;
+    /**
+     * Emit a ready op, then drain anything that was waiting on it. Recursive in spirit
+     * (a released `add` can free `set`s, and nothing else) but flat in code.
+     */
+    private release;
+    private hold;
+}

package/src/libs/engine/src/sync/causal-buffer.js

@@ -0,0 +1,199 @@
+"use strict";
+// Wave 9 — Card 5: CAUSAL READINESS.
+//
+// This file closes a hole that Card 0 wrote down and explicitly left open:
+//
+//     "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."                       — op-log.ts, Card 0
+//
+// It is Card 5's, and it is worse than "the op is dropped", because of where the drop
+// happens. Follow one reordered packet through `Replica.receive()`:
+//
+//     set(node n7, position, {x:900})   arrives BEFORE   add(node n7)
+//
+//   1. `log.appendAll()` accepts the `set`. It is new. The log now REMEMBERS it.
+//   2. The LWW gate admits it and STAMPS the register — n7.position now belongs to that
+//      write, at that clock.
+//   3. `applyOp` looks for node n7, does not find it, and returns false. Nothing happens.
+//
+// Now the `add` arrives and the node appears — at its ORIGINAL position, because the
+// `set` that was supposed to move it evaporated in step 3. And it can never be recovered:
+//
+//   • the LOG has already seen it, so a re-delivery is de-duplicated to nothing;
+//   • the LWW REGISTER already belongs to it, so even a re-send would now be REFUSED as
+//     superseded — by itself.
+//
+// One reordered packet, permanent divergence, and every layer below behaves exactly as
+// designed. That is what makes it nasty: there is no bug in the log, no bug in the gate,
+// and no bug in the reducer. The bug is that nothing owns the ORDER.
+//
+// So this does. An op is held until the entity it talks about has been ADDED, and it
+// never reaches the replica until then — no log entry, no stamp, no silent no-op.
+//
+// ---------------------------------------------------------------------------
+// "SEEN", NOT "PRESENT" — and the difference is a hang
+// ---------------------------------------------------------------------------
+//
+// The readiness test is "have we ever seen an `add` for this id", NOT "does this entity
+// exist right now". They differ for a DELETED entity, and getting it wrong is a deadlock:
+// a `set` on a node that a peer legitimately deleted would wait for an `add` that is
+// never coming, sit in the buffer forever, and — because it never reaches the log — get
+// re-requested by every anti-entropy round for the rest of the session. An op for a
+// deleted entity is released immediately and applies as the harmless no-op it is.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CausalBuffer = void 0;
+const op_1 = require("../collab/op");
+/**
+ * Holds ops whose entity has not been added yet, and releases them the instant it is.
+ *
+ * Sits BETWEEN the transport and the Replica. Nothing it holds has touched the log, the
+ * clock or the LWW registry — which is the whole point: an op the replica has never seen
+ * is an op that can still be applied later.
+ */
+class CausalBuffer {
+    constructor(diagram, options = {}) {
+        var _a;
+        this.diagram = diagram;
+        /** Entity ids we have ever seen an `add` for — including ones since deleted. */
+        this.known = new Set();
+        /** Held ops, keyed by the entity id they are waiting on. */
+        this.waiting = new Map();
+        /** opIds already held — a duplicate delivery must not double the buffer. */
+        this.heldIds = new Set();
+        /** Ops force-released because the buffer was full. Should be 0. Watch it. */
+        this.overflowed = 0;
+        this.maxPending = (_a = options.maxPending) !== null && _a !== void 0 ? _a : 10000;
+        // Anything already on the diagram when we start collaborating was, as far as this
+        // peer is concerned, added. Without this, the very first `set` on a pre-existing node
+        // would be held forever waiting for an `add` that happened before the session began.
+        for (const n of diagram.getNodes())
+            this.known.add(n.id);
+        for (const l of diagram.getLinks())
+            this.known.add(l.id);
+        for (const g of diagram.getGroups())
+            this.known.add(g.id);
+    }
+    get pendingCount() {
+        return this.heldIds.size;
+    }
+    /**
+     * WE created an entity. Record it — the transport will never tell us about it.
+     *
+     * THE FUZZ FOUND THIS ONE, AND IT IS A PERMANENT HANG, NOT A HICCUP.
+     *
+     * `known` was fed from exactly two places: entities on the diagram at construction, and
+     * `add` ops that arrived from PEERS. A node the local user creates during the session is
+     * in NEITHER — so as far as the buffer was concerned, an entity this peer invented did
+     * not exist.
+     *
+     * Now watch a peer edit it. Bob creates node X. Alice learns about it, drags it, and
+     * sends `set(X, position)`. It arrives at Bob, whose buffer asks "have I seen an `add`
+     * for X?", answers NO, and holds it — waiting for an `add(X)` that is never coming, from
+     * anyone, ever. It cannot come: the only `add(X)` in existence is Bob's OWN, it is
+     * already in Bob's log, and Alice's anti-entropy correctly concludes that Bob already
+     * has it and never echoes it back.
+     *
+     * So Bob's node freezes wherever it was when he made it, Alice watches it move, and the
+     * two documents differ forever — over the single most ordinary interaction in a
+     * collaborative editor: one person moving another person's node. On a healthy transport
+     * it never fires (the `set` cannot overtake an `add` that was never sent), which is
+     * exactly why it took a reordering channel to find it.
+     *
+     * No drain is needed. A peer can only `set` an entity it has learned about, which means
+     * our `add` had already reached it — so nothing can be waiting on an id at the moment we
+     * create it. The registration alone closes the hole.
+     */
+    noteLocal(op) {
+        if (op.op === 'add')
+            this.known.add(op.id);
+    }
+    /**
+     * Split an arriving batch into what can be applied now and what must wait — and fold in
+     * anything that was already waiting and has just become releasable.
+     */
+    admit(incoming) {
+        const ready = [];
+        let held = 0;
+        // Total order first. An `add` and the `set`s that depend on it routinely arrive in
+        // the SAME batch (a catch-up delta is exactly that), and sorting means the add is
+        // seen first and its dependants never touch the buffer at all.
+        for (const op of [...incoming].sort(op_1.compareOps)) {
+            if (this.isReady(op)) {
+                this.release(op, ready);
+                continue;
+            }
+            switch (this.hold(op)) {
+                case 'held':
+                    held++;
+                    break;
+                case 'overflow':
+                    // Bounded degradation: the buffer is full, so we stop protecting this op and
+                    // let it through as the no-op it will be. That is a genuine (if remote) lost
+                    // edit — hence `overflowed`, which is counted rather than swallowed.
+                    ready.push(op);
+                    break;
+                case 'duplicate':
+                    break;
+            }
+        }
+        return { ready, held };
+    }
+    /** Everything we are still holding — for a status panel, and for the tests. */
+    pending() {
+        const out = [];
+        for (const list of this.waiting.values())
+            out.push(...list);
+        return out.sort(op_1.compareOps);
+    }
+    // -------------------------------------------------------------------------
+    isReady(op) {
+        // An `add` carries its own entity. A diagram-level `set` has no entity to wait on.
+        if (op.op === 'add')
+            return true;
+        if (op.target === 'diagram')
+            return true;
+        return this.known.has(op.id);
+    }
+    /**
+     * Emit a ready op, then drain anything that was waiting on it. Recursive in spirit
+     * (a released `add` can free `set`s, and nothing else) but flat in code.
+     */
+    release(op, out) {
+        out.push(op);
+        if (op.op !== 'add')
+            return;
+        this.known.add(op.id);
+        const freed = this.waiting.get(op.id);
+        if (!freed)
+            return;
+        this.waiting.delete(op.id);
+        // Sorted: the dependants must apply in total order among themselves, or two `set`s on
+        // the same register could land in the wrong sequence. (The LWW gate would catch that
+        // anyway — but relying on the gate to fix an ordering we control ourselves is how you
+        // end up depending on a safety net you have never tested.)
+        for (const f of freed.sort(op_1.compareOps)) {
+            this.heldIds.delete((0, op_1.opId)(f));
+            out.push(f);
+        }
+    }
+    hold(op) {
+        const id = (0, op_1.opId)(op);
+        if (this.heldIds.has(id))
+            return 'duplicate';
+        if (this.heldIds.size >= this.maxPending) {
+            this.overflowed++;
+            return 'overflow';
+        }
+        this.heldIds.add(id);
+        const list = this.waiting.get(op.id);
+        if (list)
+            list.push(op);
+        else
+            this.waiting.set(op.id, [op]);
+        return 'held';
+    }
+}
+exports.CausalBuffer = CausalBuffer;
+//# sourceMappingURL=causal-buffer.js.map

package/src/libs/engine/src/sync/index.d.ts

@@ -0,0 +1,20 @@
+export { SyncAdapter, createSyncSession } from './sync-adapter';
+export type { SyncAdapterOptions, SyncSessionOptions, SyncStats } from './sync-adapter';
+export type { SyncTransport, TransportStatus, Unsubscribe as TransportUnsubscribe } from './transport';
+export type { SyncMessage, HelloMessage, OpsMessage, AwarenessMessage, ByeMessage, AwarenessState, } from './protocol';
+export { isDocumentMessage } from './protocol';
+export { Awareness } from './awareness';
+export type { AwarenessChange, AwarenessOptions, PeerPresence } from './awareness';
+export { VersionVector, deltaFor } from './version-vector';
+export type { ActorFrontier, VersionVectorJSON } from './version-vector';
+export { OpBatcher, coalesce } from './batcher';
+export type { OpBatcherOptions } from './batcher';
+export { CausalBuffer } from './causal-buffer';
+export type { CausalBufferOptions, CausalSplit } from './causal-buffer';
+export { MemoryHub, MemoryTransport } from './transports/memory';
+export { UnreliableHub, mulberry32 } from './transports/unreliable';
+export type { UnreliableOptions } from './transports/unreliable';
+export { BroadcastChannelTransport } from './transports/broadcast-channel';
+export type { BroadcastChannelLike, BroadcastChannelTransportOptions, } from './transports/broadcast-channel';
+export { WebSocketTransport } from './transports/websocket';
+export type { WebSocketLike, WebSocketTransportOptions } from './transports/websocket';

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

@@ -0,0 +1,41 @@
+"use strict";
+// Wave 9 (Collaboration) — Card 5: the transport layer.
+//
+// Card 0 built a Replica that can merge. This makes it MULTIPLAYER: a transport-agnostic
+// SyncAdapter that owns the four things every transport would otherwise get wrong on its
+// own — catch-up after a reconnect, causal readiness, batching, and awareness — plus the
+// presence channel that must never, under any circumstances, enter the op log.
+//
+//   createSyncSession(diagram, transport, { actor })   ← the one call a host makes
+//
+// Transports shipped: in-memory (two panes in one page; the test substrate),
+// BroadcastChannel (real cross-tab multiplayer, no server), WebSocket (proven against a
+// real `ws` server). WebRTC is NOT shipped — see transports/websocket.ts for why.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketTransport = exports.BroadcastChannelTransport = exports.mulberry32 = exports.UnreliableHub = exports.MemoryTransport = exports.MemoryHub = exports.CausalBuffer = exports.coalesce = exports.OpBatcher = exports.deltaFor = exports.VersionVector = exports.Awareness = exports.isDocumentMessage = exports.createSyncSession = exports.SyncAdapter = void 0;
+var sync_adapter_1 = require("./sync-adapter");
+Object.defineProperty(exports, "SyncAdapter", { enumerable: true, get: function () { return sync_adapter_1.SyncAdapter; } });
+Object.defineProperty(exports, "createSyncSession", { enumerable: true, get: function () { return sync_adapter_1.createSyncSession; } });
+var protocol_1 = require("./protocol");
+Object.defineProperty(exports, "isDocumentMessage", { enumerable: true, get: function () { return protocol_1.isDocumentMessage; } });
+var awareness_1 = require("./awareness");
+Object.defineProperty(exports, "Awareness", { enumerable: true, get: function () { return awareness_1.Awareness; } });
+var version_vector_1 = require("./version-vector");
+Object.defineProperty(exports, "VersionVector", { enumerable: true, get: function () { return version_vector_1.VersionVector; } });
+Object.defineProperty(exports, "deltaFor", { enumerable: true, get: function () { return version_vector_1.deltaFor; } });
+var batcher_1 = require("./batcher");
+Object.defineProperty(exports, "OpBatcher", { enumerable: true, get: function () { return batcher_1.OpBatcher; } });
+Object.defineProperty(exports, "coalesce", { enumerable: true, get: function () { return batcher_1.coalesce; } });
+var causal_buffer_1 = require("./causal-buffer");
+Object.defineProperty(exports, "CausalBuffer", { enumerable: true, get: function () { return causal_buffer_1.CausalBuffer; } });
+var memory_1 = require("./transports/memory");
+Object.defineProperty(exports, "MemoryHub", { enumerable: true, get: function () { return memory_1.MemoryHub; } });
+Object.defineProperty(exports, "MemoryTransport", { enumerable: true, get: function () { return memory_1.MemoryTransport; } });
+var unreliable_1 = require("./transports/unreliable");
+Object.defineProperty(exports, "UnreliableHub", { enumerable: true, get: function () { return unreliable_1.UnreliableHub; } });
+Object.defineProperty(exports, "mulberry32", { enumerable: true, get: function () { return unreliable_1.mulberry32; } });
+var broadcast_channel_1 = require("./transports/broadcast-channel");
+Object.defineProperty(exports, "BroadcastChannelTransport", { enumerable: true, get: function () { return broadcast_channel_1.BroadcastChannelTransport; } });
+var websocket_1 = require("./transports/websocket");
+Object.defineProperty(exports, "WebSocketTransport", { enumerable: true, get: function () { return websocket_1.WebSocketTransport; } });
+//# sourceMappingURL=index.js.map

package/src/libs/engine/src/sync/protocol.d.ts

@@ -0,0 +1,74 @@
+import type { ActorId, Op } from '../collab/op';
+import type { VersionVectorJSON } from './version-vector';
+/** Anything a peer publishes about ITSELF that is not a document edit. */
+export interface AwarenessState {
+    /** Human name for the badge. */
+    name?: string;
+    /** CSS colour. Derived deterministically from the actor id when absent. */
+    color?: string;
+    /** Pointer position in WORLD coordinates — never screen: peers have different cameras. */
+    cursor?: {
+        x: number;
+        y: number;
+    } | null;
+    /** Entity ids this peer has selected. */
+    selection?: string[];
+    /** Free-form (a "typing…" flag, a viewport rect for follow-mode, …). */
+    [key: string]: unknown;
+}
+/**
+ * "I have joined." Carries the sender's frontier so an existing peer can push the
+ * newcomer the history it lacks WITHOUT the newcomer having to ask a second time.
+ */
+export interface HelloMessage {
+    t: 'hello';
+    from: ActorId;
+    vv: VersionVectorJSON;
+    /** The sender's presence, so peers see the badge on the join frame, not 5s later. */
+    awareness?: AwarenessState;
+}
+/**
+ * "This is what I have — send me what I am missing."
+ *
+ * The anti-entropy request. Sent on join, on RECONNECT, and periodically (a transport
+ * that can drop a message can drop an op, and the only thing that repairs that is
+ * asking again).
+ */
+export interface SyncMessage_ {
+    t: 'sync';
+    from: ActorId;
+    vv: VersionVectorJSON;
+    /**
+     * Ask the recipient to answer with its OWN `sync` so we can push it what IT lacks.
+     * False on the reply, or two peers ping-pong sync requests forever.
+     */
+    reply: boolean;
+}
+/** A batch of document ops. The only message that reaches the op log. */
+export interface OpsMessage {
+    t: 'ops';
+    from: ActorId;
+    ops: Op[];
+}
+/** Ephemeral presence. NEVER reaches the op log. See the header. */
+export interface AwarenessMessage {
+    t: 'awareness';
+    from: ActorId;
+    /** null ⇒ this peer is gone (an explicit, immediate tombstone; the TTL is the backup). */
+    state: AwarenessState | null;
+    /**
+     * Per-peer sequence. Awareness is last-write-wins PER PEER, and a reordering
+     * transport will hand you an old cursor after a new one — without this, the cursor
+     * jumps backwards. It is not a Lamport clock: peers never compare each other's
+     * awareness, only their own successive samples.
+     */
+    seq: number;
+}
+/** "I am leaving." Best-effort — the TTL is what actually guarantees cleanup. */
+export interface ByeMessage {
+    t: 'bye';
+    from: ActorId;
+}
+export type SyncMessage = HelloMessage | SyncMessage_ | OpsMessage | AwarenessMessage | ByeMessage;
+/** True for the ONE message kind that is allowed to touch the durable log. */
+export declare function isDocumentMessage(msg: SyncMessage): msg is OpsMessage;

package/src/libs/engine/src/sync/protocol.js

@@ -0,0 +1,39 @@
+"use strict";
+// Wave 9 (Collaboration) — Card 5: the wire protocol.
+//
+// Five message kinds, all JSON-safe, all small. The protocol is deliberately
+// transport-agnostic: it says nothing about sockets, rooms, servers or framing. A
+// transport's ONLY job is to move a `SyncMessage` from one peer to the others; every
+// decision that matters — batching, catch-up, causal readiness, awareness lifetime —
+// is made above it, in the SyncAdapter, and is therefore tested once and works for
+// every transport.
+//
+// ---------------------------------------------------------------------------
+// THE ONE LINE THAT MATTERS: AWARENESS IS NOT AN OP
+// ---------------------------------------------------------------------------
+//
+// `ops` and `awareness` are DIFFERENT MESSAGE KINDS, and that is not cosmetic — it is
+// the load-bearing separation in this card.
+//
+// A document op is durable, causally ordered, replayable and persisted forever. A cursor
+// position is none of those things: it is ephemeral, emitted at 60Hz, meaningless five
+// seconds later, and meaningless AT ALL once its author closes the tab. Put a cursor in
+// the op log and you have (a) permanently poisoned the document's history with
+// megabytes of mouse jitter, (b) made "replay the log" reproduce someone's mouse
+// movements from last March, and (c) given every cursor sample a Lamport clock, which
+// pushes every real edit's clock into the millions for no reason whatsoever.
+//
+// So awareness travels on the same WIRE and never touches the LOG. Different lifecycle
+// (last-write-wins per peer, expires on timeout), different delivery guarantee (none —
+// dropping a cursor sample costs you nothing, the next one is 16ms away), different
+// storage (a Map that is emptied when you disconnect).
+//
+// There is a test that asserts precisely this: drive a thousand cursor moves through a
+// live adapter and assert the op log is still EMPTY.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDocumentMessage = isDocumentMessage;
+/** True for the ONE message kind that is allowed to touch the durable log. */
+function isDocumentMessage(msg) {
+    return msg.t === 'ops';
+}
+//# sourceMappingURL=protocol.js.map