@velajs/live-protocol 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kauan Guesser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @velajs/live-protocol
+
+The normative wire protocol for **Vela live queries** — the single source of truth both the server (`@velajs/vela/live`) and the client (`@velajs/client`) implement against, so the two sides cannot drift.
+
+Zero runtime dependencies. Ships three things:
+
+1. **The frame catalog** — live frames ride Vela's WebSocket envelope under the reserved event `$live`, discriminated on `t`:
+   - client → server: `sub`, `unsub`, `presence`
+   - server → client: `ack`, `data`, `delta`, `settled`, `resume`, `error`
+   - plus the `Vela-Commit-Cursor` / `Vela-Commit-Epoch` HTTP header names used to gate optimistic-update drops.
+2. **The shared keyed-delta codec** — `encodeListDelta(previous, next)` / `applyListDelta(current, ops)` with identical bail-to-snapshot rules on both sides, and an exact-reconstruction guarantee: whenever the encoder does not bail, applying the ops reproduces `next` byte-for-byte, ordering included.
+3. **Golden conformance fixtures** — `runProtocolConformance(codec)` runs byte-exact frame fixtures, pinned delta fixtures, and a seeded randomized sweep. The server and client test suites both call it; a wire change that forgets to update the fixtures fails a test instead of shipping an incompatibility.
+
+## Versioning
+
+`LIVE_PROTOCOL` (currently `1`) bumps only on breaking wire changes. Receivers must ignore unknown frame types and unknown fields; additive changes do not bump the version. Any wire change releases in lockstep: live-protocol → `@velajs/vela` → `@velajs/cloudflare` → `@velajs/client`.
+
+## Delivery semantics (normative summary)
+
+- **At-least-once** frames; keyed delta merge is idempotent, so replay after reconnect is harmless.
+- **Cursor + epoch** identify a position in a *log scope* (one Durable Object on Cloudflare, one process on Node). Epoch mismatch ⇒ full snapshot, never a delta.
+- **`settled`** means the re-run result was byte-identical: no payload, but the cursor still advances (this is what drops optimistic layers for writes that didn't change a query's result).
+- **`resume`** means nothing relevant changed while the client was away: keep the cached value, advance the cursor.
+- Optimistic updates gate on a subscription frame whose `cursor` passes the mutation's `Vela-Commit-Cursor` — never on HTTP response timing, which races the broadcast.
+
+See `vela/LIVE.md` in the main framework repo for the full feature documentation.

package/dist/conformance.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The protocol conformance runner. Both wire endpoints run this in their own
+ * test suites (see `@velajs/testing`'s live harness) so a codec that drifts
+ * from the golden fixtures — or from the shared delta semantics — fails a test
+ * on the offending side.
+ *
+ * Checks, in order:
+ * 1. Frame encoding: `encodeLiveEnvelope(fixture.frame)` is byte-identical to
+ *    the pinned wire string, the wire parses back to a guard-recognized frame,
+ *    and `readLiveEnvelope` extracts it.
+ * 2. Delta fixtures: the codec's `encodeListDelta` produces exactly the pinned
+ *    ops (or bails where the fixture says it must), and for every mergeable
+ *    fixture `applyListDelta` reconstructs `next` exactly — then reapplying
+ *    the same ops changes nothing (at-least-once replay idempotency).
+ * 3. A seeded randomized sweep of generated list pairs asserting the
+ *    exact-reconstruction property on cases the fixtures don't enumerate.
+ */
+import type { RowOp } from './frames';
+/** The two halves a wire endpoint must implement compatibly. */
+export interface DeltaCodec {
+    encodeListDelta: (previous: unknown, next: unknown, keyField?: string) => RowOp[] | undefined;
+    applyListDelta: (current: unknown, ops: readonly RowOp[], keyField?: string) => unknown[] | undefined;
+}
+export interface ConformanceReport {
+    /** Human-readable failure descriptions; empty = conformant. */
+    failures: string[];
+    checks: number;
+}
+/**
+ * Run the full conformance suite against a codec (defaults to the reference
+ * codec in this package — the package's own tests run exactly this).
+ */
+export declare const runProtocolConformance: (codec?: DeltaCodec) => ConformanceReport;

package/dist/conformance.js

@@ -0,0 +1,152 @@
+/**
+ * The protocol conformance runner. Both wire endpoints run this in their own
+ * test suites (see `@velajs/testing`'s live harness) so a codec that drifts
+ * from the golden fixtures — or from the shared delta semantics — fails a test
+ * on the offending side.
+ *
+ * Checks, in order:
+ * 1. Frame encoding: `encodeLiveEnvelope(fixture.frame)` is byte-identical to
+ *    the pinned wire string, the wire parses back to a guard-recognized frame,
+ *    and `readLiveEnvelope` extracts it.
+ * 2. Delta fixtures: the codec's `encodeListDelta` produces exactly the pinned
+ *    ops (or bails where the fixture says it must), and for every mergeable
+ *    fixture `applyListDelta` reconstructs `next` exactly — then reapplying
+ *    the same ops changes nothing (at-least-once replay idempotency).
+ * 3. A seeded randomized sweep of generated list pairs asserting the
+ *    exact-reconstruction property on cases the fixtures don't enumerate.
+ */ import { DEFAULT_KEY_FIELD, applyListDelta, encodeListDelta } from "./delta.js";
+import { encodeLiveEnvelope, isClientLiveFrame, isServerLiveFrame, readLiveEnvelope } from "./frames.js";
+import { DELTA_FIXTURES, FRAME_FIXTURES } from "./fixtures.js";
+const REFERENCE_CODEC = {
+    encodeListDelta,
+    applyListDelta
+};
+const deepEqual = (a, b)=>{
+    if (a === b) return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+        return a.every((value, index)=>deepEqual(value, b[index]));
+    }
+    if (typeof a === 'object' && typeof b === 'object' && a !== null && b !== null) {
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        if (aKeys.length !== bKeys.length) return false;
+        return aKeys.every((key)=>key in b && deepEqual(a[key], b[key]));
+    }
+    return false;
+};
+/** Deterministic LCG so the randomized sweep is reproducible (no Math.random). */ const makeRandom = (seed)=>{
+    let state = seed >>> 0;
+    return ()=>{
+        state = state * 1664525 + 1013904223 >>> 0;
+        return state / 0x1_0000_0000;
+    };
+};
+/**
+ * Generate a mergeable previous/next pair: start from a random keyed list,
+ * then delete a random subset, update random payloads, and insert fresh keys
+ * at random positions — survivor order is preserved by construction, so the
+ * encoder may only bail via the op-count cap (rule 5).
+ */ const generateCase = (random, caseIndex)=>{
+    const previousLength = Math.floor(random() * 8);
+    const previous = [];
+    for(let index = 0; index < previousLength; index += 1){
+        previous.push({
+            id: `k${caseIndex}-${index}`,
+            n: Math.floor(random() * 100)
+        });
+    }
+    const next = [];
+    for (const row of previous){
+        if (random() < 0.25) continue; // delete
+        next.push(random() < 0.4 ? {
+            ...row,
+            n: Math.floor(random() * 100)
+        } : row);
+    }
+    const insertions = Math.floor(random() * 4);
+    for(let index = 0; index < insertions; index += 1){
+        const position = Math.floor(random() * (next.length + 1));
+        next.splice(position, 0, {
+            id: `f${caseIndex}-${index}`,
+            n: Math.floor(random() * 100)
+        });
+    }
+    return {
+        previous,
+        next
+    };
+};
+/**
+ * Run the full conformance suite against a codec (defaults to the reference
+ * codec in this package — the package's own tests run exactly this).
+ */ export const runProtocolConformance = (codec = REFERENCE_CODEC)=>{
+    const failures = [];
+    let checks = 0;
+    for (const fixture of FRAME_FIXTURES){
+        checks += 1;
+        const encoded = encodeLiveEnvelope(fixture.frame);
+        if (encoded !== fixture.wire) {
+            failures.push(`frame "${fixture.name}": encoded wire differs\n  expected ${fixture.wire}\n  actual   ${encoded}`);
+            continue;
+        }
+        const frame = readLiveEnvelope(JSON.parse(fixture.wire));
+        if (frame === undefined) {
+            failures.push(`frame "${fixture.name}": readLiveEnvelope did not recognize the envelope`);
+            continue;
+        }
+        if (!isClientLiveFrame(frame) && !isServerLiveFrame(frame)) {
+            failures.push(`frame "${fixture.name}": decoded frame not recognized by either guard`);
+        }
+    }
+    for (const fixture of DELTA_FIXTURES){
+        checks += 1;
+        const keyField = fixture.keyField ?? DEFAULT_KEY_FIELD;
+        const ops = codec.encodeListDelta(fixture.previous, fixture.next, keyField);
+        if (fixture.expected === null) {
+            if (ops !== undefined) {
+                failures.push(`delta "${fixture.name}": expected bail-to-snapshot, got ${JSON.stringify(ops)}`);
+            }
+            continue;
+        }
+        if (ops === undefined) {
+            failures.push(`delta "${fixture.name}": encoder bailed, expected ${JSON.stringify(fixture.expected)}`);
+            continue;
+        }
+        if (!deepEqual(ops, fixture.expected)) {
+            failures.push(`delta "${fixture.name}": ops differ\n  expected ${JSON.stringify(fixture.expected)}\n  actual   ${JSON.stringify(ops)}`);
+            continue;
+        }
+        const merged = codec.applyListDelta(fixture.previous, ops, keyField);
+        if (merged === undefined || !deepEqual(merged, fixture.next)) {
+            failures.push(`delta "${fixture.name}": apply(previous, ops) did not reconstruct next\n  expected ${JSON.stringify(fixture.next)}\n  actual   ${JSON.stringify(merged)}`);
+            continue;
+        }
+        const replayed = codec.applyListDelta(merged, ops, keyField);
+        if (replayed === undefined || !deepEqual(replayed, fixture.next)) {
+            failures.push(`delta "${fixture.name}": replaying the same ops was not idempotent`);
+        }
+    }
+    const random = makeRandom(0x5eed);
+    for(let caseIndex = 0; caseIndex < 250; caseIndex += 1){
+        checks += 1;
+        const { previous, next } = generateCase(random, caseIndex);
+        const ops = codec.encodeListDelta(previous, next);
+        if (ops === undefined) {
+            // Survivor order is preserved by construction, so only rule 5 may bail.
+            const referenceOps = encodeListDelta(previous, next);
+            if (referenceOps !== undefined) {
+                failures.push(`random #${caseIndex}: codec bailed where the reference codec succeeds`);
+            }
+            continue;
+        }
+        const merged = codec.applyListDelta(previous, ops);
+        if (merged === undefined || !deepEqual(merged, next)) {
+            failures.push(`random #${caseIndex}: apply(previous, ops) != next\n  previous ${JSON.stringify(previous)}\n  next     ${JSON.stringify(next)}\n  ops      ${JSON.stringify(ops)}\n  merged   ${JSON.stringify(merged)}`);
+        }
+    }
+    return {
+        failures,
+        checks
+    };
+};

package/dist/delta.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The shared keyed list-delta codec — BOTH sides of the wire implement the
+ * delta contract through this one module: the server encodes a previous-vs-next
+ * query result into `RowOp`s ({@link encodeListDelta}), the client merges them
+ * into its cached value ({@link applyListDelta}).
+ *
+ * Ported from lunora's `subscription-delivery.ts` (encoder) and
+ * `delta-merge.ts` (merge), with two deliberate changes:
+ *
+ * 1. The key field defaults to `'id'` (Vela/CRUD convention, not lunora's
+ *    `_id`) and is configurable per query.
+ * 2. `insert` ops carry an explicit `before` anchor (the key of the row they
+ *    precede in the authoritative result; `null` = append) instead of
+ *    approximating position via a `_creationTime` heuristic. Because encoder
+ *    and merge live in the same package, this buys the exact-reconstruction
+ *    property the conformance suite enforces: whenever the encoder does not
+ *    bail, `applyListDelta(previous, encodeListDelta(previous, next))` is
+ *    deep-equal to `next`, ordering included.
+ *
+ * Bail-to-snapshot contract (identical on both sides — the server MUST send a
+ * full `data` snapshot and the client MUST fall back to full replacement when
+ * any of these hold):
+ *
+ * 1. previous or next is not an array;
+ * 2. any row is not a plain object carrying a string key (or the value cannot
+ *    be JSON-serialized);
+ * 3. a duplicate key appears in either array;
+ * 4. rows present in BOTH arrays changed relative order (the merge replaces
+ *    survivors in place and never reorders them);
+ * 5. the op count exceeds the next array's length (a near-total change is
+ *    cheaper as a snapshot).
+ *
+ * Op ordering inside a delta: deletes first (previous order), then
+ * inserts/updates (next order) — the merge never sees a transient over-length
+ * list. Merging is idempotent (`insert` on an existing key replaces in place,
+ * `delete` of an absent key is a no-op) so at-least-once replay after a
+ * reconnect is harmless.
+ */
+import type { RowOp } from './frames';
+/** Default row-identity field. Per-query override rides the `sub` frame's `key`. */
+export declare const DEFAULT_KEY_FIELD = "id";
+/**
+ * Diff `previous` vs `next` into row ops, or `undefined` when any bail rule
+ * holds and the caller must send a full snapshot instead.
+ *
+ * An empty array is a valid result (no row-level change — typically the server
+ * catches byte-identical results earlier and sends `settled` instead).
+ */
+export declare const encodeListDelta: (previous: unknown, next: unknown, keyField?: string) => RowOp[] | undefined;
+/**
+ * Merge row ops into a cached array result, returning a NEW array (the input
+ * is never mutated), or `undefined` when the ops cannot be applied cleanly —
+ * the caller then falls back to full replacement and lets the next snapshot
+ * reconcile.
+ *
+ * Idempotent by construction: replaying an op after a snapshot already
+ * delivered its effect changes nothing.
+ */
+export declare const applyListDelta: (current: unknown, ops: readonly RowOp[], keyField?: string) => unknown[] | undefined;

package/dist/delta.js

@@ -0,0 +1,186 @@
+/**
+ * The shared keyed list-delta codec — BOTH sides of the wire implement the
+ * delta contract through this one module: the server encodes a previous-vs-next
+ * query result into `RowOp`s ({@link encodeListDelta}), the client merges them
+ * into its cached value ({@link applyListDelta}).
+ *
+ * Ported from lunora's `subscription-delivery.ts` (encoder) and
+ * `delta-merge.ts` (merge), with two deliberate changes:
+ *
+ * 1. The key field defaults to `'id'` (Vela/CRUD convention, not lunora's
+ *    `_id`) and is configurable per query.
+ * 2. `insert` ops carry an explicit `before` anchor (the key of the row they
+ *    precede in the authoritative result; `null` = append) instead of
+ *    approximating position via a `_creationTime` heuristic. Because encoder
+ *    and merge live in the same package, this buys the exact-reconstruction
+ *    property the conformance suite enforces: whenever the encoder does not
+ *    bail, `applyListDelta(previous, encodeListDelta(previous, next))` is
+ *    deep-equal to `next`, ordering included.
+ *
+ * Bail-to-snapshot contract (identical on both sides — the server MUST send a
+ * full `data` snapshot and the client MUST fall back to full replacement when
+ * any of these hold):
+ *
+ * 1. previous or next is not an array;
+ * 2. any row is not a plain object carrying a string key (or the value cannot
+ *    be JSON-serialized);
+ * 3. a duplicate key appears in either array;
+ * 4. rows present in BOTH arrays changed relative order (the merge replaces
+ *    survivors in place and never reorders them);
+ * 5. the op count exceeds the next array's length (a near-total change is
+ *    cheaper as a snapshot).
+ *
+ * Op ordering inside a delta: deletes first (previous order), then
+ * inserts/updates (next order) — the merge never sees a transient over-length
+ * list. Merging is idempotent (`insert` on an existing key replaces in place,
+ * `delete` of an absent key is a no-op) so at-least-once replay after a
+ * reconnect is harmless.
+ */ /** Default row-identity field. Per-query override rides the `sub` frame's `key`. */ export const DEFAULT_KEY_FIELD = 'id';
+const isPlainObject = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+const readRowKey = (row, keyField)=>{
+    if (!isPlainObject(row)) return undefined;
+    const key = row[keyField];
+    return typeof key === 'string' ? key : undefined;
+};
+/**
+ * Index rows by key preserving order; `undefined` the moment any row is
+ * unkeyable or a key repeats (bail rules 2 and 3 — a duplicated key cannot be
+ * expressed as keyed deltas without silently collapsing rows).
+ */ const indexRows = (rows, keyField)=>{
+    const byKey = new Map();
+    const order = [];
+    for (const row of rows){
+        const key = readRowKey(row, keyField);
+        if (key === undefined || byKey.has(key)) return undefined;
+        byKey.set(key, row);
+        order.push(key);
+    }
+    return {
+        byKey,
+        order
+    };
+};
+/**
+ * True when rows present in BOTH lists keep the same relative order (bail
+ * rule 4): the merge updates survivors in place and never reorders them, so a
+ * survivor that moved cannot be expressed as deltas.
+ */ const survivorsKeepOrder = (previous, next)=>{
+    const survivingPrevious = previous.order.filter((key)=>next.byKey.has(key));
+    const survivingNext = next.order.filter((key)=>previous.byKey.has(key));
+    if (survivingPrevious.length !== survivingNext.length) return false;
+    return survivingPrevious.every((key, index)=>survivingNext[index] === key);
+};
+/**
+ * Diff `previous` vs `next` into row ops, or `undefined` when any bail rule
+ * holds and the caller must send a full snapshot instead.
+ *
+ * An empty array is a valid result (no row-level change — typically the server
+ * catches byte-identical results earlier and sends `settled` instead).
+ */ export const encodeListDelta = (previous, next, keyField = DEFAULT_KEY_FIELD)=>{
+    try {
+        if (!Array.isArray(previous) || !Array.isArray(next)) return undefined;
+        const previousIndex = indexRows(previous, keyField);
+        const nextIndex = indexRows(next, keyField);
+        if (previousIndex === undefined || nextIndex === undefined) return undefined;
+        if (!survivorsKeepOrder(previousIndex, nextIndex)) return undefined;
+        const ops = [];
+        // Deletes first, in previous order.
+        for (const key of previousIndex.order){
+            if (!nextIndex.byKey.has(key)) ops.push({
+                op: 'delete',
+                key
+            });
+        }
+        // The `before` anchor for an insert at position i is the nearest FOLLOWING
+        // survivor in next order (null = append). At merge time, when the insert
+        // applies, the list holds exactly the survivors (in order, updates replace
+        // in place) plus earlier inserts; splicing sequentially before the anchor
+        // therefore reproduces next's ordering exactly — inserts sharing an anchor
+        // stack in emission order, trailing inserts append in emission order.
+        const followingSurvivor = new Array(nextIndex.order.length);
+        let anchor = null;
+        for(let index = nextIndex.order.length - 1; index >= 0; index -= 1){
+            followingSurvivor[index] = anchor;
+            const key = nextIndex.order[index];
+            if (previousIndex.byKey.has(key)) anchor = key;
+        }
+        // Inserts/updates in next order. Each row is fingerprinted with a single
+        // JSON.stringify reused for the changed-row compare; an unserializable row
+        // throws and the whole encode bails to snapshot (rule 2).
+        for (const [index, key] of nextIndex.order.entries()){
+            const nextRow = nextIndex.byKey.get(key);
+            const previousRow = previousIndex.byKey.get(key);
+            const nextFingerprint = JSON.stringify(nextRow);
+            if (previousRow === undefined) {
+                ops.push({
+                    op: 'insert',
+                    key,
+                    row: nextRow,
+                    before: followingSurvivor[index] ?? null
+                });
+                continue;
+            }
+            if (JSON.stringify(previousRow) !== nextFingerprint) {
+                ops.push({
+                    op: 'update',
+                    key,
+                    row: nextRow
+                });
+            }
+        }
+        // Bail rule 5: a near-total change is better sent as one snapshot.
+        if (ops.length > next.length) return undefined;
+        return ops;
+    } catch  {
+        return undefined;
+    }
+};
+/**
+ * Merge row ops into a cached array result, returning a NEW array (the input
+ * is never mutated), or `undefined` when the ops cannot be applied cleanly —
+ * the caller then falls back to full replacement and lets the next snapshot
+ * reconcile.
+ *
+ * Idempotent by construction: replaying an op after a snapshot already
+ * delivered its effect changes nothing.
+ */ export const applyListDelta = (current, ops, keyField = DEFAULT_KEY_FIELD)=>{
+    if (!Array.isArray(current)) return undefined;
+    const rows = [];
+    const seen = new Set();
+    for (const element of current){
+        const key = readRowKey(element, keyField);
+        if (key === undefined || seen.has(key)) return undefined;
+        seen.add(key);
+        rows.push(element);
+    }
+    let next = [
+        ...rows
+    ];
+    for (const op of ops){
+        const existingIndex = next.findIndex((row)=>row[keyField] === op.key);
+        if (op.op === 'delete') {
+            if (existingIndex !== -1) next.splice(existingIndex, 1);
+            continue;
+        }
+        if (existingIndex !== -1) {
+            // Present → replace in place. Covers `update`, and an `insert` whose row
+            // a snapshot already delivered (replay idempotency).
+            next[existingIndex] = op.row;
+            continue;
+        }
+        if (op.op === 'insert' && op.before !== null) {
+            const anchorIndex = next.findIndex((row)=>row[keyField] === op.before);
+            if (anchorIndex !== -1) {
+                next.splice(anchorIndex, 0, op.row);
+                continue;
+            }
+        }
+        // `insert` with a null/missing anchor, or an `update` for a row this page
+        // never held (degraded replay) → append.
+        next = [
+            ...next,
+            op.row
+        ];
+    }
+    return next;
+};

package/dist/fixtures.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Golden wire fixtures — the drift tripwire. The server suite (@velajs/vela)
+ * and the client suite (@velajs/client) both run these through
+ * `runProtocolConformance`, so an encoding change on either side fails a test
+ * instead of surfacing as a production incompatibility.
+ *
+ * `wire` strings are byte-exact: they pin the canonical key order of
+ * `encodeLiveEnvelope`. Do not reformat them.
+ */
+import type { LiveFrame, RowOp } from './frames';
+export interface FrameFixture {
+    name: string;
+    frame: LiveFrame;
+    /** Exact canonical envelope bytes: `encodeLiveEnvelope(frame)` must equal this. */
+    wire: string;
+}
+export declare const FRAME_FIXTURES: FrameFixture[];
+export interface DeltaFixture {
+    name: string;
+    previous: unknown;
+    next: unknown;
+    keyField?: string;
+    /** Expected ops, or `null` when the encoder MUST bail to snapshot. */
+    expected: RowOp[] | null;
+}
+export declare const DELTA_FIXTURES: DeltaFixture[];