@amalgm/live 0.2.26 → 0.2.28

package/dist-cjs/contracts/docs.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Versioned document writes — the contract for whole-text writers.
+ *
+ * `POST /state/docs/write` (local-live-protocol.md §8) exists so a writer
+ * that read a file, thought, and wrote back does not clobber live edits
+ * that landed in between. `baseHash` is the lowercase sha256 hex of the
+ * EXACT text the writer read; every response's `sha256` chains into the
+ * next write.
+ *
+ * The governing invariant — never a silent winner: any path that durably
+ * discards text preserves it in a sidecar first and surfaces the decision
+ * on the doc event.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSha256Hex = exports.CONFLICT_REASONS = exports.MERGE_OUTCOMES = exports.RETENTION_RING = exports.MAX_DOC_BYTES = void 0;
+exports.checkDocWriteRequest = checkDocWriteRequest;
+const validate_js_1 = require("./validate.js");
+/** Text over this limit is refused with 413. */
+exports.MAX_DOC_BYTES = 2 * 1024 * 1024;
+/** Bases resolve against a ring of recent disk-sync states, per doc. */
+exports.RETENTION_RING = { states: 8, maxTotalBytes: 4 * 1024 * 1024, maxAgeMs: 10 * 60_000 };
+/**
+ * Every outcome states what happens to the losing text in the same breath.
+ *
+ * | outcome        | when                                   | losing text            |
+ * |----------------|----------------------------------------|------------------------|
+ * | `noop`         | incoming === live                      | none exists            |
+ * | `clean`        | base === live                          | none exists            |
+ * | `merged`       | base in retention, no overlapping hunks| both sides land        |
+ * | `conflict`     | overlapping hunks                      | full incoming → sidecar|
+ * | `base-unknown` | base outside the retention window      | live text → sidecar    |
+ * | `overwrite`    | no base sent                           | replaced text → sidecar unless nothing was deleted |
+ */
+exports.MERGE_OUTCOMES = ['noop', 'clean', 'merged', 'conflict', 'base-unknown', 'overwrite'];
+exports.CONFLICT_REASONS = ['overlapping-hunks', 'unversioned-overwrite', 'base-unknown'];
+const REQUEST_EXAMPLE = '{ path: "notes.md", text: "full new contents", baseHash: "9f86d0…" }';
+const isSha256Hex = (value) => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);
+exports.isSha256Hex = isSha256Hex;
+function checkDocWriteRequest(input) {
+    if (!(0, validate_js_1.isRecord)(input))
+        return (0, validate_js_1.failShape)(REQUEST_EXAMPLE, `got ${input === null ? 'null' : typeof input}`);
+    if (!(0, validate_js_1.isNonEmptyString)(input.path)) {
+        return (0, validate_js_1.failShape)(REQUEST_EXAMPLE, `path was ${JSON.stringify(input.path)}, not a non-empty string`);
+    }
+    if (typeof input.text !== 'string')
+        return (0, validate_js_1.failShape)(REQUEST_EXAMPLE, 'text was missing — this is a whole-text write');
+    if (input.baseHash !== undefined && !(0, exports.isSha256Hex)(input.baseHash)) {
+        return (0, validate_js_1.failShape)(REQUEST_EXAMPLE, `baseHash was ${JSON.stringify(input.baseHash)}, not lowercase sha256 hex`);
+    }
+    if (input.baseSeq !== undefined && !(0, validate_js_1.isSeq)(input.baseSeq)) {
+        return (0, validate_js_1.failShape)(REQUEST_EXAMPLE, `baseSeq was ${JSON.stringify(input.baseSeq)}, not a non-negative integer`);
+    }
+    return (0, validate_js_1.pass)(input);
+}
+//# sourceMappingURL=docs.js.map

package/dist-cjs/contracts/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/contracts/docs.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AA2DH,oDAaC;AAtED,+CAAiG;AAEjG,gDAAgD;AACnC,QAAA,aAAa,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAE7C,wEAAwE;AAC3D,QAAA,cAAc,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,EAAE,QAAQ,EAAE,EAAE,GAAG,MAAM,EAAW,CAAC;AAY5G;;;;;;;;;;;GAWG;AACU,QAAA,cAAc,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,CAAU,CAAC;AAG/F,QAAA,gBAAgB,GAAG,CAAC,mBAAmB,EAAE,uBAAuB,EAAE,cAAc,CAAU,CAAC;AAmBxG,MAAM,eAAe,GAAG,sEAAsE,CAAC;AAExF,MAAM,WAAW,GAAG,CAAC,KAAc,EAAmB,EAAE,CAC7D,OAAO,KAAK,KAAK,QAAQ,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAD/C,QAAA,WAAW,eACoC;AAE5D,SAAgB,oBAAoB,CAAC,KAAc;IACjD,IAAI,CAAC,IAAA,sBAAQ,EAAC,KAAK,CAAC;QAAE,OAAO,IAAA,uBAAS,EAAC,eAAe,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;IACzG,IAAI,CAAC,IAAA,8BAAgB,EAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,OAAO,IAAA,uBAAS,EAAC,eAAe,EAAE,YAAY,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IACtG,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAA,uBAAS,EAAC,eAAe,EAAE,+CAA+C,CAAC,CAAC;IACvH,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,IAAA,mBAAW,EAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjE,OAAO,IAAA,uBAAS,EAAC,eAAe,EAAE,gBAAgB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,4BAA4B,CAAC,CAAC;IAChH,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,IAAA,mBAAK,EAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACzD,OAAO,IAAA,uBAAS,EAAC,eAAe,EAAE,eAAe,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAChH,CAAC;IACD,OAAO,IAAA,kBAAI,EAAC,KAAmC,CAAC,CAAC;AACnD,CAAC"}

package/dist-cjs/contracts/events.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * State events — the unit of change on the local wire.
+ *
+ * Every change is an event (local-live-protocol.md §1). Tables and disk are
+ * truth; the event log is a bounded (~15 min) delivery buffer, so a client
+ * that falls off the buffer re-snapshots rather than asking for history.
+ *
+ * `seq` is a strictly increasing integer per runtime. The two optional
+ * Wave 3 fields (`mutationId`, `sharedResourceId`) are additive: legacy
+ * rows omit both keys exactly as before, and validation here accepts both
+ * generations (axiom: additive-only evolution).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNewerThan = exports.isWireOp = exports.WIRE_OPS = void 0;
+exports.checkStateEvent = checkStateEvent;
+const validate_js_1 = require("./validate.js");
+/** The shipped wire operations. `move`/`delta` (realtime-sdk.md §3) ride as contract-specific patches until a wire rev adds them. */
+exports.WIRE_OPS = ['insert', 'update', 'delete', 'replace', 'invalidate'];
+const EXAMPLE = '{ seq: 42, ts: 1719000000000, resource: "tasks", op: "update", id: "t1", patch: {...} }';
+const isWireOp = (value) => typeof value === 'string' && exports.WIRE_OPS.includes(value);
+exports.isWireOp = isWireOp;
+/**
+ * Validate one wire event. Unknown extra keys are preserved untouched —
+ * a newer peer may be speaking an additive extension we do not know yet.
+ */
+function checkStateEvent(input) {
+    if (!(0, validate_js_1.isRecord)(input))
+        return (0, validate_js_1.failShape)(EXAMPLE, `got ${input === null ? 'null' : typeof input}`);
+    if (!(0, validate_js_1.isSeq)(input.seq))
+        return (0, validate_js_1.failShape)(EXAMPLE, `seq was ${JSON.stringify(input.seq)}, not a non-negative integer`);
+    if (typeof input.ts !== 'number')
+        return (0, validate_js_1.failShape)(EXAMPLE, `ts was ${JSON.stringify(input.ts)}, not a number`);
+    if (!(0, validate_js_1.isNonEmptyString)(input.resource))
+        return (0, validate_js_1.failShape)(EXAMPLE, `resource was ${JSON.stringify(input.resource)}, not a name`);
+    if (!(0, exports.isWireOp)(input.op)) {
+        return (0, validate_js_1.failShape)(EXAMPLE, `op was ${JSON.stringify(input.op)}, not one of ${exports.WIRE_OPS.join('|')}`);
+    }
+    return (0, validate_js_1.pass)(input);
+}
+/** Events apply in seq order; equal or older seq means already applied (client obligation, protocol §6). */
+const isNewerThan = (event, appliedSeq) => event.seq > appliedSeq;
+exports.isNewerThan = isNewerThan;
+//# sourceMappingURL=events.js.map

package/dist-cjs/contracts/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/contracts/events.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAsCH,0CASC;AA7CD,+CAAiG;AAGjG,qIAAqI;AACxH,QAAA,QAAQ,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,CAAU,CAAC;AAuBzF,MAAM,OAAO,GAAG,yFAAyF,CAAC;AAEnG,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAmB,EAAE,CAC1D,OAAO,KAAK,KAAK,QAAQ,IAAK,gBAA8B,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AADlE,QAAA,QAAQ,YAC0D;AAE/E;;;GAGG;AACH,SAAgB,eAAe,CAAC,KAAc;IAC5C,IAAI,CAAC,IAAA,sBAAQ,EAAC,KAAK,CAAC;QAAE,OAAO,IAAA,uBAAS,EAAC,OAAO,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;IACjG,IAAI,CAAC,IAAA,mBAAK,EAAC,KAAK,CAAC,GAAG,CAAC;QAAE,OAAO,IAAA,uBAAS,EAAC,OAAO,EAAE,WAAW,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;IACrH,IAAI,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ;QAAE,OAAO,IAAA,uBAAS,EAAC,OAAO,EAAE,UAAU,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,gBAAgB,CAAC,CAAC;IAChH,IAAI,CAAC,IAAA,8BAAgB,EAAC,KAAK,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAA,uBAAS,EAAC,OAAO,EAAE,gBAAgB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC/H,IAAI,CAAC,IAAA,gBAAQ,EAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;QACxB,OAAO,IAAA,uBAAS,EAAC,OAAO,EAAE,UAAU,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,gBAAgB,gBAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACpG,CAAC;IACD,OAAO,IAAA,kBAAI,EAAC,KAA8B,CAAC,CAAC;AAC9C,CAAC;AAED,4GAA4G;AACrG,MAAM,WAAW,GAAG,CAAC,KAAiB,EAAE,UAAkB,EAAW,EAAE,CAAC,KAAK,CAAC,GAAG,GAAG,UAAU,CAAC;AAAzF,QAAA,WAAW,eAA8E"}

package/dist-cjs/contracts/frames/gateway.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Gateway state socket — browser ⇄ Fly gateway
+ * (local-live-protocol.md §4).
+ *
+ * The barrier rule: in bootstrap mode the gateway MUST NOT send
+ * `state.connected` before `state.snapshot`. A browser treats
+ * `state.connected` as "delivery confirmed from here on" — and it is
+ * re-sent on every transport change, so `transport: 'poll'` is how the
+ * client learns it is degraded. Polling is a degraded state, never a
+ * destination: a polling session retries the runtime stream and promotes
+ * back.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POLL_INTERVAL_MS = exports.POLL_PROMOTE_INTERVAL_MS = exports.HEARTBEAT_INTERVAL_MS = exports.COMMAND_LIMITS = exports.CAPABILITY_STATE_COMMAND = void 0;
+exports.checkCommand = checkCommand;
+const validate_js_1 = require("../validate.js");
+/** A client uses socket commands only when `state.connected.capabilities` advertises this. */
+exports.CAPABILITY_STATE_COMMAND = 'state.command.v1';
+/** Commands are a small allowlist, validated and bounded — never an arbitrary method/path. */
+exports.COMMAND_LIMITS = { maxBodyBytes: 4 * 1024 * 1024, maxInFlight: 16 };
+exports.HEARTBEAT_INTERVAL_MS = 25_000;
+/** A polling session retries the runtime stream at this cadence (env AMALGM_STATE_STREAM_PROMOTE_MS). */
+exports.POLL_PROMOTE_INTERVAL_MS = 30_000;
+exports.POLL_INTERVAL_MS = 1_000;
+const COMMAND_EXAMPLE = '{ type: "state.command", requestId: "r1", command: "doc.update", payload: { path, updates } }';
+function checkCommand(input) {
+    if (!(0, validate_js_1.isRecord)(input) || input.type !== 'state.command') {
+        return (0, validate_js_1.failShape)(COMMAND_EXAMPLE, `type was ${(0, validate_js_1.isRecord)(input) ? JSON.stringify(input.type) : typeof input}`);
+    }
+    if (!(0, validate_js_1.isNonEmptyString)(input.requestId)) {
+        return (0, validate_js_1.failShape)(COMMAND_EXAMPLE, `requestId was ${JSON.stringify(input.requestId)}, not a non-empty string`);
+    }
+    if (!(0, validate_js_1.isNonEmptyString)(input.command)) {
+        return (0, validate_js_1.failShape)(COMMAND_EXAMPLE, `command was ${JSON.stringify(input.command)}, not a non-empty string`);
+    }
+    return (0, validate_js_1.pass)(input);
+}
+//# sourceMappingURL=gateway.js.map

package/dist-cjs/contracts/frames/gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.js","sourceRoot":"","sources":["../../../src/contracts/frames/gateway.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAuDH,oCAWC;AAhED,gDAA2F;AAI3F,8FAA8F;AACjF,QAAA,wBAAwB,GAAG,kBAAkB,CAAC;AAE3D,8FAA8F;AACjF,QAAA,cAAc,GAAG,EAAE,YAAY,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,EAAE,WAAW,EAAE,EAAE,EAAW,CAAC;AAE7E,QAAA,qBAAqB,GAAG,MAAM,CAAC;AAC5C,yGAAyG;AAC5F,QAAA,wBAAwB,GAAG,MAAM,CAAC;AAClC,QAAA,gBAAgB,GAAG,KAAK,CAAC;AAsCtC,MAAM,eAAe,GAAG,+FAA+F,CAAC;AAExH,SAAgB,YAAY,CAAC,KAAc;IACzC,IAAI,CAAC,IAAA,sBAAQ,EAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;QACvD,OAAO,IAAA,uBAAS,EAAC,eAAe,EAAE,YAAY,IAAA,sBAAQ,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;IAC/G,CAAC;IACD,IAAI,CAAC,IAAA,8BAAgB,EAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QACvC,OAAO,IAAA,uBAAS,EAAC,eAAe,EAAE,iBAAiB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,0BAA0B,CAAC,CAAC;IAChH,CAAC;IACD,IAAI,CAAC,IAAA,8BAAgB,EAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACrC,OAAO,IAAA,uBAAS,EAAC,eAAe,EAAE,eAAe,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAC5G,CAAC;IACD,OAAO,IAAA,kBAAI,EAAC,KAAoC,CAAC,CAAC;AACpD,CAAC"}

package/dist-cjs/contracts/frames/stream.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Runtime SSE stream frames — `GET /state/stream`
+ * (local-live-protocol.md §3).
+ *
+ * Two modes share one endpoint. Legacy: hello comment → backlog replay →
+ * live events, with the snapshot fetched separately (the race that creates
+ * is closed client-side by the full-snapshot barrier). Ordered-bootstrap
+ * (`bootstrap=1&resources=…`): the server registers the listener FIRST,
+ * then sends the snapshot as the first data frame, then flushes buffered
+ * events past its seq — the snapshot-buries-event race is impossible by
+ * construction because everything travels ordered on one channel.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BOOTSTRAP_SNAPSHOT_TIMEOUT_MS = exports.PING_INTERVAL_MS = void 0;
+/** Sent every 25 seconds. */
+exports.PING_INTERVAL_MS = 25_000;
+/** A bootstrap client falls back to the legacy path when no snapshot frame arrives in time. */
+exports.BOOTSTRAP_SNAPSHOT_TIMEOUT_MS = 5_000;
+//# sourceMappingURL=stream.js.map

package/dist-cjs/contracts/frames/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../../src/contracts/frames/stream.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAgBH,6BAA6B;AAChB,QAAA,gBAAgB,GAAG,MAAM,CAAC;AACvC,+FAA+F;AAClF,QAAA,6BAA6B,GAAG,KAAK,CAAC"}

package/dist-cjs/contracts/frames/tunnel.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Tunnel frames — runtime ⇄ gateway, protocol v2
+ * (local-live-protocol.md §5).
+ *
+ * One outbound WebSocket per runtime. v2 is negotiated per connection: the
+ * runtime's hello carries `protocol_version: 2`; no `hello_ack` means the
+ * peer is v1 and only v1 frames may be sent. Slot arbitration is
+ * hello-driven and identity-based — the decision function itself lives in
+ * `machines/arbitration.ts`; this file owns the wire shapes and constants
+ * both sides must agree on.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasUsableIdentity = exports.CHUNKING = exports.BACKPRESSURE = exports.CLOSE_CODES = exports.CAPABILITY_SHARED_MUTATION = exports.HELLO_INTERVAL_MS = exports.PROTOCOL_VERSION = void 0;
+exports.checkHello = checkHello;
+const validate_js_1 = require("../validate.js");
+exports.PROTOCOL_VERSION = 2;
+/** Sent on connect and every 15s. */
+exports.HELLO_INTERVAL_MS = 15_000;
+/** Advertised in hello acks; only then do upgraded runtimes use additive shared.resource.* / shared.mutation.* frames. */
+exports.CAPABILITY_SHARED_MUTATION = 'shared.mutation.v1';
+exports.CLOSE_CODES = {
+    /** The newcomer won the slot; the old connection is fenced before this close. */
+    replaced: 4000,
+    /** Refused: an older or equal boot_ts lost arbitration. Retry slowly, never stop. */
+    supersededInstance: 4009,
+    unauthorized: 4401,
+};
+exports.BACKPRESSURE = {
+    /** Frames above this queue behind bufferedAmount; control frames always send immediately. */
+    controlMaxBytes: 32 * 1024,
+    /** High-water mark on the socket buffer (AMALGM_TUNNEL_HWM_BYTES). */
+    highWaterMarkBytes: 1024 * 1024,
+    /** Bounded bulk queue (AMALGM_TUNNEL_BULK_MAX_BYTES); overflow drops the response as a 503 res frame — never a silent hang. */
+    bulkMaxBytes: 64 * 1024 * 1024,
+};
+exports.CHUNKING = {
+    /** Raw bodies above this are chunked to v2 peers. */
+    thresholdBytes: 256 * 1024,
+    /** ≤256KB raw per chunk, 0-based indexes. */
+    chunkMaxBytes: 256 * 1024,
+};
+const HELLO_EXAMPLE = '{ type: "hello", instance_id: "a1b2c3d4e5f60718", boot_ts: 1719000000000, runtime_version: "0.1.157", protocol_version: 2, runtime_label: "main" }';
+function checkHello(input) {
+    if (!(0, validate_js_1.isRecord)(input) || input.type !== 'hello') {
+        return (0, validate_js_1.failShape)(HELLO_EXAMPLE, `type was ${(0, validate_js_1.isRecord)(input) ? JSON.stringify(input.type) : typeof input}`);
+    }
+    if (!(0, validate_js_1.isNonEmptyString)(input.runtime_label)) {
+        return (0, validate_js_1.failShape)(HELLO_EXAMPLE, `runtime_label was ${JSON.stringify(input.runtime_label)}, not a non-empty string`);
+    }
+    // Identity fields are additive v2: a v1 hello without them is still a valid hello.
+    return (0, validate_js_1.pass)(input);
+}
+/** Usable identity for arbitration: both fields present and well-formed. Missing/unusable identity falls back to legacy last-connect-wins. */
+const hasUsableIdentity = (hello) => typeof hello.instance_id === 'string' &&
+    /^[0-9a-f]{16}$/.test(hello.instance_id) &&
+    typeof hello.boot_ts === 'number' &&
+    Number.isFinite(hello.boot_ts);
+exports.hasUsableIdentity = hasUsableIdentity;
+//# sourceMappingURL=tunnel.js.map

package/dist-cjs/contracts/frames/tunnel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.js","sourceRoot":"","sources":["../../../src/contracts/frames/tunnel.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAgEH,gCASC;AAvED,gDAA2F;AAE9E,QAAA,gBAAgB,GAAG,CAAC,CAAC;AAClC,qCAAqC;AACxB,QAAA,iBAAiB,GAAG,MAAM,CAAC;AAExC,0HAA0H;AAC7G,QAAA,0BAA0B,GAAG,oBAAoB,CAAC;AAElD,QAAA,WAAW,GAAG;IACzB,iFAAiF;IACjF,QAAQ,EAAE,IAAI;IACd,qFAAqF;IACrF,kBAAkB,EAAE,IAAI;IACxB,YAAY,EAAE,IAAI;CACV,CAAC;AAEE,QAAA,YAAY,GAAG;IAC1B,6FAA6F;IAC7F,eAAe,EAAE,EAAE,GAAG,IAAI;IAC1B,sEAAsE;IACtE,kBAAkB,EAAE,IAAI,GAAG,IAAI;IAC/B,+HAA+H;IAC/H,YAAY,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;CACtB,CAAC;AAEE,QAAA,QAAQ,GAAG;IACtB,qDAAqD;IACrD,cAAc,EAAE,GAAG,GAAG,IAAI;IAC1B,6CAA6C;IAC7C,aAAa,EAAE,GAAG,GAAG,IAAI;CACjB,CAAC;AA4BX,MAAM,aAAa,GACjB,oJAAoJ,CAAC;AAEvJ,SAAgB,UAAU,CAAC,KAAc;IACvC,IAAI,CAAC,IAAA,sBAAQ,EAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC/C,OAAO,IAAA,uBAAS,EAAC,aAAa,EAAE,YAAY,IAAA,sBAAQ,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;IAC7G,CAAC;IACD,IAAI,CAAC,IAAA,8BAAgB,EAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;QAC3C,OAAO,IAAA,uBAAS,EAAC,aAAa,EAAE,qBAAqB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,aAAa,CAAC,0BAA0B,CAAC,CAAC;IACtH,CAAC;IACD,mFAAmF;IACnF,OAAO,IAAA,kBAAI,EAAC,KAA+B,CAAC,CAAC;AAC/C,CAAC;AAED,8IAA8I;AACvI,MAAM,iBAAiB,GAAG,CAAC,KAA2B,EAAW,EAAE,CACxE,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ;IACrC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC;IACxC,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;IACjC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAJpB,QAAA,iBAAiB,qBAIG"}

package/dist-cjs/contracts/index.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * The contracts layer: every wire shape, identity rule, and vocabulary the
+ * protocol documents define — as types, guards, and validators. Nothing in
+ * here performs I/O or holds state; the state machines live in
+ * `../machines`, and the ports a host injects live in `../adapters`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./validate.js"), exports);
+__exportStar(require("./resources.js"), exports);
+__exportStar(require("./events.js"), exports);
+__exportStar(require("./snapshot.js"), exports);
+__exportStar(require("./binding.js"), exports);
+__exportStar(require("./presence.js"), exports);
+__exportStar(require("./docs.js"), exports);
+__exportStar(require("./content.js"), exports);
+__exportStar(require("./frames/stream.js"), exports);
+__exportStar(require("./frames/gateway.js"), exports);
+__exportStar(require("./frames/tunnel.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist-cjs/contracts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;AAEH,gDAA8B;AAC9B,iDAA+B;AAC/B,8CAA4B;AAC5B,gDAA8B;AAC9B,+CAA6B;AAC7B,gDAA8B;AAC9B,4CAA0B;AAC1B,+CAA6B;AAC7B,qDAAmC;AACnC,sDAAoC;AACpC,qDAAmC"}

package/dist-cjs/contracts/presence.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Ephemeral presence — the lane that is allowed to lose data.
+ *
+ * Presence is authenticated and permission-gated but best-effort
+ * (local-live-protocol.md §2, realtime-sdk.md §6): TTL-bound, never
+ * journaled, never replayed after a gap, safe to drop under backpressure.
+ * Re-publishing IS the heartbeat; absence is the default that publishing
+ * re-earns. Identity (`user`) is stamped server-side from the enrolled
+ * account and never read from the client body.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BLOB_BYTES = exports.SERVER_TTL_MS = exports.PUBLISH_INTERVAL_MS = void 0;
+exports.checkPresenceFrame = checkPresenceFrame;
+const validate_js_1 = require("./validate.js");
+/** Clients re-publish while bound and on every position change. */
+exports.PUBLISH_INTERVAL_MS = 10_000;
+/** The server expires any entry not re-published within this window (10s sweep). */
+exports.SERVER_TTL_MS = 30_000;
+/** The surface-defined opaque position blob is capped at 8KB. */
+exports.MAX_BLOB_BYTES = 8 * 1024;
+const EXAMPLE = '{ resource: "doc:...", peers: [{ session: "s1", user: "ada", at: 1719000000000 }] }';
+function checkPresenceFrame(input) {
+    if (!(0, validate_js_1.isRecord)(input))
+        return (0, validate_js_1.failShape)(EXAMPLE, `got ${input === null ? 'null' : typeof input}`);
+    if (!(0, validate_js_1.isNonEmptyString)(input.resource)) {
+        return (0, validate_js_1.failShape)(EXAMPLE, `resource was ${JSON.stringify(input.resource)}, not a name`);
+    }
+    if (!Array.isArray(input.peers))
+        return (0, validate_js_1.failShape)(EXAMPLE, 'peers was not an array');
+    for (const peer of input.peers) {
+        if (!(0, validate_js_1.isRecord)(peer) || !(0, validate_js_1.isNonEmptyString)(peer.session) || !(0, validate_js_1.isNonEmptyString)(peer.user)) {
+            return (0, validate_js_1.failShape)(EXAMPLE, `peer ${JSON.stringify(peer)} is missing session or user`);
+        }
+    }
+    return (0, validate_js_1.pass)(input);
+}
+//# sourceMappingURL=presence.js.map

package/dist-cjs/contracts/presence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.js","sourceRoot":"","sources":["../../src/contracts/presence.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AA2CH,gDAYC;AArDD,+CAA0F;AAE1F,mEAAmE;AACtD,QAAA,mBAAmB,GAAG,MAAM,CAAC;AAC1C,oFAAoF;AACvE,QAAA,aAAa,GAAG,MAAM,CAAC;AACpC,iEAAiE;AACpD,QAAA,cAAc,GAAG,CAAC,GAAG,IAAI,CAAC;AAgCvC,MAAM,OAAO,GAAG,qFAAqF,CAAC;AAEtG,SAAgB,kBAAkB,CAAC,KAAc;IAC/C,IAAI,CAAC,IAAA,sBAAQ,EAAC,KAAK,CAAC;QAAE,OAAO,IAAA,uBAAS,EAAC,OAAO,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;IACjG,IAAI,CAAC,IAAA,8BAAgB,EAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtC,OAAO,IAAA,uBAAS,EAAC,OAAO,EAAE,gBAAgB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC1F,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,IAAA,uBAAS,EAAC,OAAO,EAAE,wBAAwB,CAAC,CAAC;IACrF,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,CAAC,IAAA,sBAAQ,EAAC,IAAI,CAAC,IAAI,CAAC,IAAA,8BAAgB,EAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAA,8BAAgB,EAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACvF,OAAO,IAAA,uBAAS,EAAC,OAAO,EAAE,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IACD,OAAO,IAAA,kBAAI,EAAC,KAAiC,CAAC,CAAC;AACjD,CAAC"}

package/dist-cjs/contracts/resources.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Resource identity — the names of live channels.
+ *
+ * A resource is a named channel over the local wire
+ * (local-live-protocol.md §1). The shipped grammar:
+ *
+ *     tasks                      a well-known singleton table
+ *     app:<appId>:<name>         a per-app named resource
+ *     doc:<base64url(path)>      a live document, addressed by local path
+ *     files:<base64url(dir)>     a directory listing channel
+ *
+ * A shared resource additionally receives a cloud id that never depends on
+ * any user's local path (realtime-sdk.md §2); path-derived ids are for
+ * unshared local resources only. Renaming a materialized file must not
+ * change a shared id — which is exactly why the shared id is not derived
+ * from the path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appResource = exports.filesResource = exports.docResource = void 0;
+exports.parseResource = parseResource;
+exports.encodeBase64Url = encodeBase64Url;
+exports.decodeBase64Url = decodeBase64Url;
+const validate_js_1 = require("./validate.js");
+/** `doc:<base64url(path)>` for the document at a local path. */
+const docResource = (path) => `doc:${encodeBase64Url(path)}`;
+exports.docResource = docResource;
+/** `files:<base64url(dir)>` for the listing channel of a directory. */
+const filesResource = (dir) => `files:${encodeBase64Url(dir)}`;
+exports.filesResource = filesResource;
+/** `app:<appId>:<name>` for an app-scoped resource. */
+const appResource = (appId, name) => `app:${appId}:${name}`;
+exports.appResource = appResource;
+/**
+ * Parse any shipped resource name into its addressed form.
+ *
+ *     parseResource('doc:bm90ZXMubWQ')   → { kind: 'doc', path: 'notes.md' }
+ *     parseResource('app:canvas:board')  → { kind: 'app', appId: 'canvas', name: 'board' }
+ *     parseResource('tasks')             → { kind: 'table', name: 'tasks' }
+ */
+function parseResource(resource) {
+    if (!(0, validate_js_1.isNonEmptyString)(resource)) {
+        return (0, validate_js_1.failShape)(`a resource name like "tasks" or "doc:${encodeBase64Url('notes.md')}"`, `got ${typeof resource}`);
+    }
+    const [prefix] = resource.split(':', 1);
+    switch (prefix) {
+        case 'doc': {
+            const path = decodeBase64Url(resource.slice('doc:'.length));
+            return path === null
+                ? (0, validate_js_1.failShape)(`"doc:${encodeBase64Url('notes.md')}" (base64url of the path)`, `"${resource}" carries invalid base64url`)
+                : (0, validate_js_1.pass)({ kind: 'doc', path });
+        }
+        case 'files': {
+            const dir = decodeBase64Url(resource.slice('files:'.length));
+            return dir === null
+                ? (0, validate_js_1.failShape)(`"files:${encodeBase64Url('notes')}" (base64url of the directory)`, `"${resource}" carries invalid base64url`)
+                : (0, validate_js_1.pass)({ kind: 'files', dir });
+        }
+        case 'app': {
+            const rest = resource.slice('app:'.length);
+            const divider = rest.indexOf(':');
+            if (divider <= 0 || divider === rest.length - 1) {
+                return (0, validate_js_1.failShape)('"app:<appId>:<name>", e.g. "app:canvas:board"', `"${resource}" is missing the appId or name segment`);
+            }
+            return (0, validate_js_1.pass)({ kind: 'app', appId: rest.slice(0, divider), name: rest.slice(divider + 1) });
+        }
+        default:
+            return (0, validate_js_1.pass)({ kind: 'table', name: resource });
+    }
+}
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+/** UTF-8 → unpadded base64url. Portable: no Buffer, no btoa. */
+function encodeBase64Url(text) {
+    const bytes = new TextEncoder().encode(text);
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const a = bytes[i];
+        const b = bytes[i + 1];
+        const c = bytes[i + 2];
+        out += BASE64_ALPHABET[a >> 2];
+        out += BASE64_ALPHABET[((a & 0x03) << 4) | ((b ?? 0) >> 4)];
+        if (b !== undefined)
+            out += BASE64_ALPHABET[((b & 0x0f) << 2) | ((c ?? 0) >> 6)];
+        if (c !== undefined)
+            out += BASE64_ALPHABET[c & 0x3f];
+    }
+    return out;
+}
+/** Unpadded base64url → UTF-8, or null when the input is not base64url. */
+function decodeBase64Url(encoded) {
+    if (encoded.length % 4 === 1)
+        return null;
+    const bytes = [];
+    let buffer = 0;
+    let bits = 0;
+    for (const char of encoded) {
+        const value = BASE64_ALPHABET.indexOf(char);
+        if (value === -1)
+            return null;
+        buffer = (buffer << 6) | value;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes.push((buffer >> bits) & 0xff);
+        }
+    }
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(new Uint8Array(bytes));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=resources.js.map

package/dist-cjs/contracts/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../../src/contracts/resources.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AA4BH,sCA6BC;AAKD,0CAaC;AAGD,0CAoBC;AAhGD,+CAAgF;AAUhF,gEAAgE;AACzD,MAAM,WAAW,GAAG,CAAC,IAAY,EAAgB,EAAE,CAAC,OAAO,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;AAA7E,QAAA,WAAW,eAAkE;AAE1F,uEAAuE;AAChE,MAAM,aAAa,GAAG,CAAC,GAAW,EAAgB,EAAE,CAAC,SAAS,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;AAA/E,QAAA,aAAa,iBAAkE;AAE5F,uDAAuD;AAChD,MAAM,WAAW,GAAG,CAAC,KAAa,EAAE,IAAY,EAAgB,EAAE,CAAC,OAAO,KAAK,IAAI,IAAI,EAAE,CAAC;AAApF,QAAA,WAAW,eAAyE;AAEjG;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,QAAiB;IAC7C,IAAI,CAAC,IAAA,8BAAgB,EAAC,QAAQ,CAAC,EAAE,CAAC;QAChC,OAAO,IAAA,uBAAS,EAAC,wCAAwC,eAAe,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,OAAO,QAAQ,EAAE,CAAC,CAAC;IACrH,CAAC;IACD,MAAM,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACxC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YAC5D,OAAO,IAAI,KAAK,IAAI;gBAClB,CAAC,CAAC,IAAA,uBAAS,EAAC,QAAQ,eAAe,CAAC,UAAU,CAAC,2BAA2B,EAAE,IAAI,QAAQ,6BAA6B,CAAC;gBACtH,CAAC,CAAC,IAAA,kBAAI,EAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAClC,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,GAAG,GAAG,eAAe,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YAC7D,OAAO,GAAG,KAAK,IAAI;gBACjB,CAAC,CAAC,IAAA,uBAAS,EAAC,UAAU,eAAe,CAAC,OAAO,CAAC,gCAAgC,EAAE,IAAI,QAAQ,6BAA6B,CAAC;gBAC1H,CAAC,CAAC,IAAA,kBAAI,EAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QACnC,CAAC;QACD,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,OAAO,IAAI,CAAC,IAAI,OAAO,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChD,OAAO,IAAA,uBAAS,EAAC,+CAA+C,EAAE,IAAI,QAAQ,wCAAwC,CAAC,CAAC;YAC1H,CAAC;YACD,OAAO,IAAA,kBAAI,EAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;QAC7F,CAAC;QACD;YACE,OAAO,IAAA,kBAAI,EAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED,MAAM,eAAe,GAAG,kEAAkE,CAAC;AAE3F,gEAAgE;AAChE,SAAgB,eAAe,CAAC,IAAY;IAC1C,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QACpB,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,GAAG,IAAI,eAAe,CAAC,CAAC,IAAI,CAAC,CAAE,CAAC;QAChC,GAAG,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC;QAC7D,IAAI,CAAC,KAAK,SAAS;YAAE,GAAG,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC;QAClF,IAAI,CAAC,KAAK,SAAS;YAAE,GAAG,IAAI,eAAe,CAAC,CAAC,GAAG,IAAI,CAAE,CAAC;IACzD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,2EAA2E;AAC3E,SAAgB,eAAe,CAAC,OAAe;IAC7C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAC9B,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC;QAC/B,IAAI,IAAI,CAAC,CAAC;QACV,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;YACd,IAAI,IAAI,CAAC,CAAC;YACV,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IACjF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist-cjs/contracts/snapshot.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Snapshots — the resume point of every recovery path.
+ *
+ * A snapshot is the full value of each requested resource, consistent as of
+ * `seq` when `stable` is true (local-live-protocol.md §1). The builder may
+ * race writes; after 3 attempts it serves best-effort data with
+ * `stable: false`. Clients may treat an unstable snapshot like a stable one
+ * — the live stream repairs staleness — but must never cache it as a
+ * consistency proof.
+ *
+ * Recovery rule: every failure path (seq gap beyond the buffer, `reset`
+ * frame, failed backfill) converges on "fetch a snapshot and resume from
+ * its seq".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSnapshot = checkSnapshot;
+const validate_js_1 = require("./validate.js");
+const EXAMPLE = '{ seq: 42, stable: true, resources: { tasks: [...] } }';
+function checkSnapshot(input) {
+    if (!(0, validate_js_1.isRecord)(input))
+        return (0, validate_js_1.failShape)(EXAMPLE, `got ${input === null ? 'null' : typeof input}`);
+    if (!(0, validate_js_1.isSeq)(input.seq))
+        return (0, validate_js_1.failShape)(EXAMPLE, `seq was ${JSON.stringify(input.seq)}, not a non-negative integer`);
+    if (!(0, validate_js_1.isRecord)(input.resources)) {
+        return (0, validate_js_1.failShape)(EXAMPLE, `resources was ${JSON.stringify(input.resources)}, not an object`);
+    }
+    const stable = input.stable !== false; // absent means stable: the field is an additive escape hatch
+    return (0, validate_js_1.pass)({ seq: input.seq, stable, resources: input.resources });
+}
+//# sourceMappingURL=snapshot.js.map

package/dist-cjs/contracts/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/contracts/snapshot.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;AAcH,sCAQC;AApBD,+CAA+E;AAU/E,MAAM,OAAO,GAAG,wDAAwD,CAAC;AAEzE,SAAgB,aAAa,CAAC,KAAc;IAC1C,IAAI,CAAC,IAAA,sBAAQ,EAAC,KAAK,CAAC;QAAE,OAAO,IAAA,uBAAS,EAAC,OAAO,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;IACjG,IAAI,CAAC,IAAA,mBAAK,EAAC,KAAK,CAAC,GAAG,CAAC;QAAE,OAAO,IAAA,uBAAS,EAAC,OAAO,EAAE,WAAW,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;IACrH,IAAI,CAAC,IAAA,sBAAQ,EAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAA,uBAAS,EAAC,OAAO,EAAE,iBAAiB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;IAC/F,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,6DAA6D;IACpG,OAAO,IAAA,kBAAI,EAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist-cjs/contracts/validate.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Shared validation vocabulary for every contract in this package.
+ *
+ * Validators never throw on bad wire data — a peer being wrong is an
+ * expected condition, not an exception (local-live-protocol.md: unknown
+ * frames mean "the other end is older"). They return a `Checked<T>` so
+ * callers must look at the outcome, and every failure message is
+ * example-first: it states what a correct value looks like before saying
+ * what was wrong (see PURPOSE.md axiom on error shape).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSeq = exports.isNonEmptyString = exports.isRecord = exports.failShape = exports.fail = exports.pass = void 0;
+const pass = (value) => ({ ok: true, value });
+exports.pass = pass;
+const fail = (error) => ({ ok: false, error });
+exports.fail = fail;
+/**
+ * Build an example-first failure: `expected` is a correct literal shape,
+ * `problem` names the specific field that broke it.
+ *
+ *     failShape('{ seq: 42, resource: "tasks", op: "update" }',
+ *               'op was "patch", not one of insert|update|delete|replace|invalidate')
+ */
+const failShape = (expected, problem) => (0, exports.fail)(`expected ${expected} — ${problem}`);
+exports.failShape = failShape;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+exports.isRecord = isRecord;
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
+exports.isNonEmptyString = isNonEmptyString;
+/** A strictly increasing wire sequence number: a non-negative safe integer. */
+const isSeq = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+exports.isSeq = isSeq;
+//# sourceMappingURL=validate.js.map

package/dist-cjs/contracts/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/contracts/validate.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAMI,MAAM,IAAI,GAAG,CAAI,KAAQ,EAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAA1D,QAAA,IAAI,QAAsD;AAEhE,MAAM,IAAI,GAAG,CAAY,KAAa,EAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AAAxE,QAAA,IAAI,QAAoE;AAErF;;;;;;GAMG;AACI,MAAM,SAAS,GAAG,CAAY,QAAgB,EAAE,OAAe,EAAc,EAAE,CACpF,IAAA,YAAI,EAAC,YAAY,QAAQ,MAAM,OAAO,EAAE,CAAC,CAAC;AAD/B,QAAA,SAAS,aACsB;AAErC,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE,CAC3E,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAD1D,QAAA,QAAQ,YACkD;AAEhE,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAAmB,EAAE,CAClE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AADnC,QAAA,gBAAgB,oBACmB;AAEhD,+EAA+E;AACxE,MAAM,KAAK,GAAG,CAAC,KAAc,EAAmB,EAAE,CACvD,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAD5D,QAAA,KAAK,SACuD"}