@velajs/live-protocol 1.0.0 → 1.1.0

package/dist/index.js

@@ -1,5 +1,914 @@
-export { LIVE_PROTOCOL } from "./version.js";
-export { COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER, LIVE_ERROR_CODES, LIVE_EVENT, RESERVED_EVENT_PREFIX, canonicalLiveFrame, encodeLiveEnvelope, encodeLiveFrame, isClientLiveFrame, isRowOp, isRowOps, isServerLiveFrame, liveEnvelope, readLiveEnvelope } from "./frames.js";
-export { DEFAULT_KEY_FIELD, applyListDelta, encodeListDelta } from "./delta.js";
-export { runProtocolConformance } from "./conformance.js";
-export { DELTA_FIXTURES, FRAME_FIXTURES } from "./fixtures.js";
+//#region src/version.ts
+/**
+* Live-protocol wire version. Bumped ONLY on a breaking wire change (renaming
+* or removing a field, changing a delivery guarantee). Additive changes — new
+* optional fields, new frame types — do NOT bump it: receivers MUST ignore
+* unknown frame `t` values and unknown object fields.
+*
+* A client advertises the version it speaks via the `v` field on its `sub`
+* frame; a server that cannot serve that version replies
+* `{ t: 'error', code: 'unsupported_protocol', fatal: true }`.
+*/
+const LIVE_PROTOCOL = 2;
+//#endregion
+//#region src/frames.ts
+/**
+* The normative frame catalog for Vela live queries.
+*
+* Live frames ride Vela's existing WebSocket envelope `{ event, data }` under
+* the single reserved event name `$live`; the frame itself is the envelope's
+* `data`, discriminated on `t`. Classic gateway events, `ping`→`pong`
+* keepalive, and live frames coexist on one socket. The `$` prefix is reserved
+* for the framework: app gateways must never register a `$…` event.
+*
+* Byte-identical encoding matters: golden fixtures pin the exact wire string
+* for every frame shape, and both the server and the client encode through
+* {@link encodeLiveFrame} / {@link encodeLiveEnvelope} so the two sides cannot
+* drift. Canonical key order is the declaration order of each type below;
+* absent optionals are omitted entirely.
+*/
+/** The reserved envelope event every live frame rides under. */
+const LIVE_EVENT = "$live";
+/**
+* The reserved event-name prefix. The WS dispatcher rejects app gateways that
+* register a `$…` event at bootstrap so live (and future framework) frames can
+* never collide with app events.
+*/
+const RESERVED_EVENT_PREFIX = "$";
+/**
+* HTTP response headers carrying the commit cursor/epoch of the log scope a
+* mutation's invalidations landed in. The client gates optimistic-layer drops
+* on a subscription frame whose `cursor` passes this value (and whose `epoch`
+* matches) — never on HTTP response timing, which races the broadcast.
+*/
+const COMMIT_CURSOR_HEADER = "Vela-Commit-Cursor";
+const COMMIT_EPOCH_HEADER = "Vela-Commit-Epoch";
+/** Default hard limits shared by every live-protocol endpoint. */
+const MAX_LIVE_FRAME_BYTES = 64 * 1024;
+const MAX_PRESENCE_METADATA_BYTES = 4 * 1024;
+const MAX_DELTA_OPS = 1e3;
+/** Well-known `error` frame codes. The code space is open — receivers must tolerate unknown codes. */
+const LIVE_ERROR_CODES = {
+	UNSUPPORTED_PROTOCOL: "unsupported_protocol",
+	DUPLICATE_SUB: "duplicate_sub",
+	UNKNOWN_QUERY: "unknown_query",
+	FORBIDDEN: "forbidden",
+	BAD_ARGS: "bad_args",
+	LIMIT_EXCEEDED: "limit_exceeded",
+	INTERNAL: "internal"
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isCursor = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const isBoundedString = (value, max, allowEmpty = false) => typeof value === "string" && (allowEmpty || value.length > 0) && value.length <= max;
+const isOptionalBoundedString = (value, max) => value === void 0 || isBoundedString(value, max);
+const hasOwn = (value, key) => Object.hasOwn(value, key);
+const hasCursorPair = (value, cursor, epoch) => value[cursor] === void 0 && value[epoch] === void 0 || isCursor(value[cursor]) && isBoundedString(value[epoch], 256);
+/** Structural guard for a single {@link RowOp}. Unknown extra fields are tolerated. */
+const isRowOp = (value) => {
+	if (!isRecord(value) || !isBoundedString(value["key"], 512)) return false;
+	const op = value["op"];
+	if (op === "delete") return true;
+	if (op !== "insert" && op !== "update") return false;
+	if (!isRecord(value["row"]) || !isJsonWithin(value["row"], 65536)) return false;
+	if (op === "insert") {
+		const before = value["before"];
+		return before === null || isBoundedString(before, 512);
+	}
+	return true;
+};
+const isRowOps = (value) => Array.isArray(value) && value.length <= 1e3 && value.every(isRowOp);
+/**
+* Structural guard for a client frame. Frames with an unknown `t` return
+* false — per the forward-compat rule the receiver then ignores the frame.
+*/
+const isClientLiveFrame = (value) => {
+	if (!isRecord(value) || !isJsonWithin(value, 65536)) return false;
+	switch (value["t"]) {
+		case "sub": return isBoundedString(value["sub"], 256) && isBoundedString(value["query"], 256) && hasCursorPair(value, "sinceCursor", "sinceEpoch") && isOptionalBoundedString(value["key"], 128) && value["v"] === 2 && (!hasOwn(value, "args") || isJsonWithin(value["args"], 32 * 1024));
+		case "unsub": return isBoundedString(value["sub"], 256);
+		case "presence": return isBoundedString(value["room"], 512) && (!hasOwn(value, "meta") || isJsonWithin(value["meta"], 4096));
+		default: return false;
+	}
+};
+/** Structural guard for a server frame. Unknown `t` → false (receiver ignores). */
+const isServerLiveFrame = (value) => {
+	if (!isRecord(value) || !isJsonWithin(value, 65536)) return false;
+	switch (value["t"]) {
+		case "ack": return isBoundedString(value["sub"], 256);
+		case "data": return isBoundedString(value["sub"], 256) && hasOwn(value, "snapshot") && hasCursorPair(value, "cursor", "epoch");
+		case "delta": return isBoundedString(value["sub"], 256) && isRowOps(value["ops"]) && hasCursorPair(value, "cursor", "epoch");
+		case "settled": return isBoundedString(value["sub"], 256) && hasCursorPair(value, "cursor", "epoch");
+		case "resume": return isBoundedString(value["sub"], 256) && isCursor(value["cursor"]) && isBoundedString(value["epoch"], 256);
+		case "error": return isOptionalBoundedString(value["sub"], 256) && isBoundedString(value["code"], 128) && isBoundedString(value["message"], 2048, true) && typeof value["fatal"] === "boolean";
+		default: return false;
+	}
+};
+/**
+* Extract the live frame from a parsed WS envelope, or `undefined` when the
+* envelope is not a live envelope. Does NOT validate the frame — pair with
+* {@link isClientLiveFrame} / {@link isServerLiveFrame} on the receiving side.
+*/
+const readLiveEnvelope = (envelope) => {
+	if (!isRecord(envelope) || envelope["event"] !== "$live" || !hasOwn(envelope, "data") || !isJsonWithin(envelope, 65536)) return;
+	return envelope["data"];
+};
+const DANGEROUS_KEYS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+const isJsonWithin = (value, maxBytes) => {
+	if (!isJsonValue(value, /* @__PURE__ */ new WeakSet(), { nodes: 0 }, 0)) return false;
+	try {
+		const serialized = JSON.stringify(value);
+		return serialized !== void 0 && new TextEncoder().encode(serialized).byteLength <= maxBytes;
+	} catch {
+		return false;
+	}
+};
+const isJsonValue = (value, seen, budget, depth) => {
+	budget.nodes += 1;
+	if (budget.nodes > 1e4 || depth > 32) return false;
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (typeof value !== "object" || seen.has(value)) return false;
+	seen.add(value);
+	const values = [];
+	if (Array.isArray(value)) values.push(...value);
+	else {
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) return false;
+		for (const key of Object.keys(value)) {
+			if (DANGEROUS_KEYS.has(key)) return false;
+			values.push(value[key]);
+		}
+	}
+	for (const child of values) if (!isJsonValue(child, seen, budget, depth + 1)) return false;
+	seen.delete(value);
+	return true;
+};
+/** Wrap a frame in the `$live` envelope object. */
+const liveEnvelope = (frame) => ({
+	event: LIVE_EVENT,
+	data: frame
+});
+const CANONICAL_KEYS = {
+	sub: [
+		"t",
+		"sub",
+		"query",
+		"args",
+		"sinceCursor",
+		"sinceEpoch",
+		"key",
+		"v"
+	],
+	unsub: ["t", "sub"],
+	presence: [
+		"t",
+		"room",
+		"meta"
+	],
+	ack: ["t", "sub"],
+	data: [
+		"t",
+		"sub",
+		"snapshot",
+		"cursor",
+		"epoch"
+	],
+	delta: [
+		"t",
+		"sub",
+		"ops",
+		"cursor",
+		"epoch"
+	],
+	settled: [
+		"t",
+		"sub",
+		"cursor",
+		"epoch"
+	],
+	resume: [
+		"t",
+		"sub",
+		"cursor",
+		"epoch"
+	],
+	error: [
+		"t",
+		"sub",
+		"code",
+		"message",
+		"fatal"
+	]
+};
+const ROW_OP_KEYS = [
+	"op",
+	"key",
+	"row",
+	"before"
+];
+const canonicalRowOp = (op) => {
+	const source = op;
+	const out = {};
+	for (const key of ROW_OP_KEYS) if (source[key] !== void 0) out[key] = source[key];
+	return out;
+};
+/**
+* Rebuild a frame with the canonical key order, dropping absent optionals.
+* `JSON.stringify` of the result is the frame's canonical wire form — the one
+* the golden fixtures pin byte-for-byte.
+*/
+const canonicalLiveFrame = (frame) => {
+	const source = frame;
+	const keys = CANONICAL_KEYS[frame.t];
+	if (keys === void 0) throw new Error(`Unknown live frame type: ${String(frame.t)}`);
+	const out = {};
+	for (const key of keys) {
+		const value = source[key];
+		if (value === void 0) continue;
+		out[key] = frame.t === "delta" && key === "ops" ? value.map(canonicalRowOp) : value;
+	}
+	return out;
+};
+/** Canonical JSON encoding of a bare frame (no envelope). */
+const encodeLiveFrame = (frame) => {
+	if (!isClientLiveFrame(frame) && !isServerLiveFrame(frame)) throw new TypeError("Cannot encode an invalid or oversized live frame.");
+	return JSON.stringify(canonicalLiveFrame(frame));
+};
+/** Canonical JSON encoding of the full `$live` envelope — what actually goes on the socket. */
+const encodeLiveEnvelope = (frame) => `{"event":${JSON.stringify(LIVE_EVENT)},"data":${encodeLiveFrame(frame)}}`;
+//#endregion
+//#region src/delta.ts
+/** Default row-identity field. Per-query override rides the `sub` frame's `key`. */
+const DEFAULT_KEY_FIELD = "id";
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const readRowKey = (row, keyField) => {
+	if (!isPlainObject(row)) return void 0;
+	const key = row[keyField];
+	return typeof key === "string" ? key : void 0;
+};
+/**
+* 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 = /* @__PURE__ */ new Map();
+	const order = [];
+	for (const row of rows) {
+		const key = readRowKey(row, keyField);
+		if (key === void 0 || byKey.has(key)) return void 0;
+		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).
+*/
+const encodeListDelta = (previous, next, keyField = "id") => {
+	try {
+		if (!Array.isArray(previous) || !Array.isArray(next)) return void 0;
+		const previousIndex = indexRows(previous, keyField);
+		const nextIndex = indexRows(next, keyField);
+		if (previousIndex === void 0 || nextIndex === void 0) return void 0;
+		if (!survivorsKeepOrder(previousIndex, nextIndex)) return void 0;
+		const ops = [];
+		for (const key of previousIndex.order) if (!nextIndex.byKey.has(key)) ops.push({
+			op: "delete",
+			key
+		});
+		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;
+		}
+		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 === void 0) {
+				ops.push({
+					op: "insert",
+					key,
+					row: nextRow,
+					before: followingSurvivor[index] ?? null
+				});
+				continue;
+			}
+			if (JSON.stringify(previousRow) !== nextFingerprint) ops.push({
+				op: "update",
+				key,
+				row: nextRow
+			});
+		}
+		if (ops.length > next.length) return void 0;
+		return ops;
+	} catch {
+		return;
+	}
+};
+/**
+* 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.
+*/
+const applyListDelta = (current, ops, keyField = "id") => {
+	if (!Array.isArray(current)) return void 0;
+	const rows = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const element of current) {
+		const key = readRowKey(element, keyField);
+		if (key === void 0 || seen.has(key)) return void 0;
+		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) {
+			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;
+			}
+		}
+		next = [...next, op.row];
+	}
+	return next;
+};
+//#endregion
+//#region src/fixtures.ts
+const FRAME_FIXTURES = [
+	{
+		name: "sub (full)",
+		frame: {
+			t: "sub",
+			sub: "s1",
+			query: "todos.list",
+			args: { listId: "l1" },
+			sinceCursor: 42,
+			sinceEpoch: "e-1",
+			key: "id",
+			v: 2
+		},
+		wire: "{\"event\":\"$live\",\"data\":{\"t\":\"sub\",\"sub\":\"s1\",\"query\":\"todos.list\",\"args\":{\"listId\":\"l1\"},\"sinceCursor\":42,\"sinceEpoch\":\"e-1\",\"key\":\"id\",\"v\":2}}"
+	},
+	{
+		name: "sub (minimal)",
+		frame: {
+			t: "sub",
+			sub: "s2",
+			query: "todos.all",
+			v: 2
+		},
+		wire: "{\"event\":\"$live\",\"data\":{\"t\":\"sub\",\"sub\":\"s2\",\"query\":\"todos.all\",\"v\":2}}"
+	},
+	{
+		name: "unsub",
+		frame: {
+			t: "unsub",
+			sub: "s1"
+		},
+		wire: "{\"event\":\"$live\",\"data\":{\"t\":\"unsub\",\"sub\":\"s1\"}}"
+	},
+	{
+		name: "presence",
+		frame: {
+			t: "presence",
+			room: "r1",
+			meta: { name: "kauan" }
+		},
+		wire: "{\"event\":\"$live\",\"data\":{\"t\":\"presence\",\"room\":\"r1\",\"meta\":{\"name\":\"kauan\"}}}"
+	},
+	{
+		name: "ack",
+		frame: {
+			t: "ack",
+			sub: "s1"
+		},
+		wire: "{\"event\":\"$live\",\"data\":{\"t\":\"ack\",\"sub\":\"s1\"}}"
+	},
+	{
+		name: "data",
+		frame: {
+			t: "data",
+			sub: "s1",
+			snapshot: [{
+				id: "a",
+				text: "hi"
+			}],
+			cursor: 7,
+			epoch: "e-1"
+		},
+		wire: "{\"event\":\"$live\",\"data\":{\"t\":\"data\",\"sub\":\"s1\",\"snapshot\":[{\"id\":\"a\",\"text\":\"hi\"}],\"cursor\":7,\"epoch\":\"e-1\"}}"
+	},
+	{
+		name: "data (cold, no cursor)",
+		frame: {
+			t: "data",
+			sub: "s1",
+			snapshot: null
+		},
+		wire: "{\"event\":\"$live\",\"data\":{\"t\":\"data\",\"sub\":\"s1\",\"snapshot\":null}}"
+	},
+	{
+		name: "delta",
+		frame: {
+			t: "delta",
+			sub: "s1",
+			ops: [
+				{
+					op: "delete",
+					key: "a"
+				},
+				{
+					op: "insert",
+					key: "b",
+					row: { id: "b" },
+					before: null
+				},
+				{
+					op: "update",
+					key: "c",
+					row: {
+						id: "c",
+						n: 2
+					}
+				}
+			],
+			cursor: 8,
+			epoch: "e-1"
+		},
+		wire: "{\"event\":\"$live\",\"data\":{\"t\":\"delta\",\"sub\":\"s1\",\"ops\":[{\"op\":\"delete\",\"key\":\"a\"},{\"op\":\"insert\",\"key\":\"b\",\"row\":{\"id\":\"b\"},\"before\":null},{\"op\":\"update\",\"key\":\"c\",\"row\":{\"id\":\"c\",\"n\":2}}],\"cursor\":8,\"epoch\":\"e-1\"}}"
+	},
+	{
+		name: "settled",
+		frame: {
+			t: "settled",
+			sub: "s1",
+			cursor: 9,
+			epoch: "e-1"
+		},
+		wire: "{\"event\":\"$live\",\"data\":{\"t\":\"settled\",\"sub\":\"s1\",\"cursor\":9,\"epoch\":\"e-1\"}}"
+	},
+	{
+		name: "resume",
+		frame: {
+			t: "resume",
+			sub: "s1",
+			cursor: 42,
+			epoch: "e-1"
+		},
+		wire: "{\"event\":\"$live\",\"data\":{\"t\":\"resume\",\"sub\":\"s1\",\"cursor\":42,\"epoch\":\"e-1\"}}"
+	},
+	{
+		name: "error (subscription)",
+		frame: {
+			t: "error",
+			sub: "s1",
+			code: "forbidden",
+			message: "nope",
+			fatal: true
+		},
+		wire: "{\"event\":\"$live\",\"data\":{\"t\":\"error\",\"sub\":\"s1\",\"code\":\"forbidden\",\"message\":\"nope\",\"fatal\":true}}"
+	},
+	{
+		name: "error (connection)",
+		frame: {
+			t: "error",
+			code: "unsupported_protocol",
+			message: "v2 required",
+			fatal: true
+		},
+		wire: "{\"event\":\"$live\",\"data\":{\"t\":\"error\",\"code\":\"unsupported_protocol\",\"message\":\"v2 required\",\"fatal\":true}}"
+	}
+];
+const DELTA_FIXTURES = [
+	{
+		name: "noop",
+		previous: [],
+		next: [],
+		expected: []
+	},
+	{
+		name: "insert into empty",
+		previous: [],
+		next: [{
+			id: "a",
+			n: 1
+		}],
+		expected: [{
+			op: "insert",
+			key: "a",
+			row: {
+				id: "a",
+				n: 1
+			},
+			before: null
+		}]
+	},
+	{
+		name: "insert head",
+		previous: [{ id: "b" }],
+		next: [{ id: "a" }, { id: "b" }],
+		expected: [{
+			op: "insert",
+			key: "a",
+			row: { id: "a" },
+			before: "b"
+		}]
+	},
+	{
+		name: "insert middle",
+		previous: [{ id: "a" }, { id: "c" }],
+		next: [
+			{ id: "a" },
+			{ id: "b" },
+			{ id: "c" }
+		],
+		expected: [{
+			op: "insert",
+			key: "b",
+			row: { id: "b" },
+			before: "c"
+		}]
+	},
+	{
+		name: "insert tail",
+		previous: [{ id: "a" }],
+		next: [{ id: "a" }, { id: "b" }],
+		expected: [{
+			op: "insert",
+			key: "b",
+			row: { id: "b" },
+			before: null
+		}]
+	},
+	{
+		name: "update in place",
+		previous: [{
+			id: "a",
+			n: 1
+		}],
+		next: [{
+			id: "a",
+			n: 2
+		}],
+		expected: [{
+			op: "update",
+			key: "a",
+			row: {
+				id: "a",
+				n: 2
+			}
+		}]
+	},
+	{
+		name: "delete one",
+		previous: [{ id: "a" }, { id: "b" }],
+		next: [{ id: "a" }],
+		expected: [{
+			op: "delete",
+			key: "b"
+		}]
+	},
+	{
+		name: "mixed delete+update+insert",
+		previous: [
+			{
+				id: "a",
+				n: 1
+			},
+			{
+				id: "b",
+				n: 1
+			},
+			{
+				id: "c",
+				n: 1
+			}
+		],
+		next: [
+			{
+				id: "b",
+				n: 2
+			},
+			{
+				id: "d",
+				n: 1
+			},
+			{
+				id: "c",
+				n: 1
+			}
+		],
+		expected: [
+			{
+				op: "delete",
+				key: "a"
+			},
+			{
+				op: "update",
+				key: "b",
+				row: {
+					id: "b",
+					n: 2
+				}
+			},
+			{
+				op: "insert",
+				key: "d",
+				row: {
+					id: "d",
+					n: 1
+				},
+				before: "c"
+			}
+		]
+	},
+	{
+		name: "stacked inserts share an anchor in next order",
+		previous: [{ id: "z" }],
+		next: [
+			{ id: "x" },
+			{ id: "y" },
+			{ id: "z" }
+		],
+		expected: [{
+			op: "insert",
+			key: "x",
+			row: { id: "x" },
+			before: "z"
+		}, {
+			op: "insert",
+			key: "y",
+			row: { id: "y" },
+			before: "z"
+		}]
+	},
+	{
+		name: "custom key field",
+		previous: [{
+			_key: "a",
+			n: 1
+		}],
+		next: [{
+			_key: "a",
+			n: 2
+		}],
+		keyField: "_key",
+		expected: [{
+			op: "update",
+			key: "a",
+			row: {
+				_key: "a",
+				n: 2
+			}
+		}]
+	},
+	{
+		name: "bail: clear list (rule 5)",
+		previous: [{ id: "a" }, { id: "b" }],
+		next: [],
+		expected: null
+	},
+	{
+		name: "bail: near-total change (rule 5)",
+		previous: [{ id: "a" }, { id: "b" }],
+		next: [
+			{ id: "c" },
+			{ id: "d" },
+			{ id: "e" }
+		],
+		expected: null
+	},
+	{
+		name: "bail: previous not array (rule 1)",
+		previous: { id: "a" },
+		next: [{ id: "a" }],
+		expected: null
+	},
+	{
+		name: "bail: next not array (rule 1)",
+		previous: [{ id: "a" }],
+		next: { id: "a" },
+		expected: null
+	},
+	{
+		name: "bail: row missing key (rule 2)",
+		previous: [{ id: "a" }],
+		next: [{ text: "no key" }],
+		expected: null
+	},
+	{
+		name: "bail: non-string key (rule 2)",
+		previous: [{ id: "a" }],
+		next: [{ id: 5 }],
+		expected: null
+	},
+	{
+		name: "bail: scalar row (rule 2)",
+		previous: [{ id: "a" }],
+		next: ["a"],
+		expected: null
+	},
+	{
+		name: "bail: duplicate key in previous (rule 3)",
+		previous: [{ id: "a" }, { id: "a" }],
+		next: [{ id: "a" }],
+		expected: null
+	},
+	{
+		name: "bail: duplicate key in next (rule 3)",
+		previous: [{ id: "a" }],
+		next: [{ id: "a" }, { id: "a" }],
+		expected: null
+	},
+	{
+		name: "bail: survivors reordered (rule 4)",
+		previous: [{ id: "a" }, { id: "b" }],
+		next: [{ id: "b" }, { id: "a" }],
+		expected: null
+	}
+];
+//#endregion
+//#region src/conformance.ts
+/**
+* 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.
+*/
+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 / 4294967296;
+	};
+};
+/**
+* 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() < .25) continue;
+		next.push(random() < .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).
+*/
+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 === void 0) {
+			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 ?? "id";
+		const ops = codec.encodeListDelta(fixture.previous, fixture.next, keyField);
+		if (fixture.expected === null) {
+			if (ops !== void 0) failures.push(`delta "${fixture.name}": expected bail-to-snapshot, got ${JSON.stringify(ops)}`);
+			continue;
+		}
+		if (ops === void 0) {
+			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 === void 0 || !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 === void 0 || !deepEqual(replayed, fixture.next)) failures.push(`delta "${fixture.name}": replaying the same ops was not idempotent`);
+	}
+	const random = makeRandom(24301);
+	for (let caseIndex = 0; caseIndex < 250; caseIndex += 1) {
+		checks += 1;
+		const { previous, next } = generateCase(random, caseIndex);
+		const ops = codec.encodeListDelta(previous, next);
+		if (ops === void 0) {
+			if (encodeListDelta(previous, next) !== void 0) failures.push(`random #${caseIndex}: codec bailed where the reference codec succeeds`);
+			continue;
+		}
+		const merged = codec.applyListDelta(previous, ops);
+		if (merged === void 0 || !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
+	};
+};
+//#endregion
+export { COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER, DEFAULT_KEY_FIELD, DELTA_FIXTURES, FRAME_FIXTURES, LIVE_ERROR_CODES, LIVE_EVENT, LIVE_PROTOCOL, MAX_DELTA_OPS, MAX_LIVE_FRAME_BYTES, MAX_PRESENCE_METADATA_BYTES, RESERVED_EVENT_PREFIX, applyListDelta, canonicalLiveFrame, encodeListDelta, encodeLiveEnvelope, encodeLiveFrame, isClientLiveFrame, isRowOp, isRowOps, isServerLiveFrame, liveEnvelope, readLiveEnvelope, runProtocolConformance };
+
+//# sourceMappingURL=index.js.map