@amalgm/live 0.2.27 → 0.2.28

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":"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"}

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"}

package/dist-cjs/detection/adapter-contract.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * The adapter contract: what it means to serve an entity type.
+ *
+ * An adapter is how a KIND of entity rides the seven realtime rails —
+ * watch, detect, record, send, receive, apply, verify. The entity's
+ * `type` selects its adapter; the rails themselves never change shape
+ * per type. Ratified by entity-model.md ("Type selects the complete
+ * adapter cycle") and entity-implementation.md.
+ *
+ * Axioms:
+ *
+ *  1. ONE ADAPTER PER TYPE, EVERY TYPE ASSIGNED. The alphabet belongs
+ *     to the registry; the adapter map covers it exactly — no type
+ *     unassigned, no type claimed twice. Assigned is not yet
+ *     operational: operational is earned rail by rail, and absence is
+ *     honest.
+ *  2. ADAPTERS OWN BEHAVIOR; THE REGISTRY OWNS IDENTITY. A lawful type
+ *     transition that crosses adapters is a handoff on the same UUID,
+ *     never a rebirth.
+ *  3. ONE SOCKET PER RAIL. A rail's callable surfaces are ratified
+ *     HERE, once, for every adapter (`SOCKETS`). An adapter binds a
+ *     rail's whole socket or binds the rail not at all; a rail whose
+ *     socket is not yet ratified cannot be bound by anyone.
+ *  4. A TRUTH READ NEVER LIES. Every assigned type names its source of
+ *     truth in one sentence, and reading it produces exactly one of
+ *     three honest answers: present, absent, or unsettled.
+ *  5. RAILS ARE HONEST. An unbound rail is absent — never stubbed,
+ *     never defaulted.
+ *  6. THE CONTRACT IS FROZEN GROUND. A descriptor is immutable from
+ *     the moment it loads.
+ *  7. THE BASE ORCHESTRATES; THE ADAPTER SUPPLIES TYPE BEHAVIOR. A
+ *     rail earns a socket only when a real consumer proves that
+ *     behavior differs by type — never for symmetry.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.referenceAdapter = exports.lookFailed = exports.SOCKETS = exports.RAILS = void 0;
+exports.assertAdapter = assertAdapter;
+exports.buildTypeMap = buildTypeMap;
+/** The seven rails, declared once, frozen, in journey order. */
+exports.RAILS = Object.freeze([
+    'watch', 'detect', 'record', 'send', 'receive', 'apply', 'verify',
+]);
+/**
+ * The ratified sockets — for each rail that has one, the exact surfaces
+ * every binding adapter implements. Same names, same shapes, every
+ * type. ONE socket is ratified today (detect), derived from what
+ * production detection actually asks of a type. Watch and record earn
+ * none at this bar (adjudicated 2026-08-03 under axiom 7); apply and
+ * verify join only when the Send/Receive rails exist to derive their
+ * socket from. A socket is ratified from a real consumer or it is not
+ * ratified at all.
+ */
+exports.SOCKETS = Object.freeze({
+    detect: Object.freeze(['truth']),
+});
+/**
+ * Convict a malformed adapter descriptor loudly; return it (typed)
+ * unchanged when lawful.
+ */
+function assertAdapter(adapter) {
+    const isRecord = (value) => typeof value === 'object' && value !== null;
+    const where = isRecord(adapter) && typeof adapter['name'] === 'string' && adapter['name']
+        ? `adapter ${JSON.stringify(adapter['name'])}` : 'adapter';
+    if (!isRecord(adapter) || !Object.isFrozen(adapter)) {
+        throw new Error(`${where}: a descriptor is a frozen object`);
+    }
+    if (typeof adapter['name'] !== 'string' || adapter['name'].length === 0) {
+        throw new Error('adapter: name is a non-empty string');
+    }
+    const { types, rails } = adapter;
+    if (!isRecord(types) || !Object.isFrozen(types) || Object.keys(types).length === 0) {
+        throw new Error(`${where}: types is a frozen, non-empty map of entity type → declared truth`);
+    }
+    for (const [type, truth] of Object.entries(types)) {
+        if (typeof truth !== 'string' || truth.length === 0) {
+            throw new Error(`${where}: type ${JSON.stringify(type)} must declare its source of truth in one sentence`);
+        }
+    }
+    if (!isRecord(rails) || !Object.isFrozen(rails)) {
+        throw new Error(`${where}: rails is a frozen map (empty is honest; a stub is not)`);
+    }
+    for (const [rail, surfaces] of Object.entries(rails)) {
+        if (!exports.RAILS.includes(rail)) {
+            throw new Error(`${where}: ${JSON.stringify(rail)} is not a rail — the rails are ${exports.RAILS.join(', ')}`);
+        }
+        const socket = exports.SOCKETS[rail];
+        if (!socket) {
+            throw new Error(`${where}: rail ${rail} has no ratified socket yet — a socket is ratified in the contract before anyone binds it`);
+        }
+        if (!isRecord(surfaces) || !Object.isFrozen(surfaces)) {
+            throw new Error(`${where}: rail ${rail} must bind a frozen map of its socket's surfaces`);
+        }
+        const bound = Object.keys(surfaces).sort();
+        if (bound.join(',') !== [...socket].sort().join(',')) {
+            throw new Error(`${where}: rail ${rail} binds [${bound.join(', ')}] but its socket is [${socket.join(', ')}] — an adapter implements a rail's whole socket or binds the rail not at all`);
+        }
+        for (const [surface, fn] of Object.entries(surfaces)) {
+            if (typeof fn !== 'function') {
+                throw new Error(`${where}: ${rail}.${surface} must be a function — an unbuilt surface is left absent, never stubbed`);
+            }
+        }
+    }
+    return adapter;
+}
+/**
+ * Build the one type → adapter map, convicting every violation of
+ * axiom 1: an adapter claiming a type outside the alphabet, two
+ * adapters claiming one type, or an alphabet type left unassigned.
+ * Pure — callers own where the alphabet and adapters come from.
+ */
+function buildTypeMap(adapters, alphabet) {
+    const known = new Set(alphabet);
+    const byType = new Map();
+    for (const candidate of adapters) {
+        const adapter = assertAdapter(candidate);
+        for (const type of Object.keys(adapter.types)) {
+            if (!known.has(type)) {
+                throw new Error(`adapter ${adapter.name} claims ${JSON.stringify(type)}, which is not in the registry's alphabet`);
+            }
+            const holder = byType.get(type);
+            if (holder) {
+                throw new Error(`entity type ${JSON.stringify(type)} is claimed by both ${holder.name} and ${adapter.name} — one adapter per type`);
+            }
+            byType.set(type, adapter);
+        }
+    }
+    for (const type of known) {
+        if (!byType.has(type)) {
+            throw new Error(`entity type ${JSON.stringify(type)} has no adapter — every type is assigned`);
+        }
+    }
+    return byType;
+}
+/**
+ * The three-state vocabulary's one shared judgment: what a FAILED look
+ * at ground means. ENOENT and ENOTDIR are the filesystem itself saying
+ * "not there" — honest ABSENCE, a fact. Every other failure means the
+ * LOOK failed, not the ground — UNSETTLED: no conclusion, read again.
+ *
+ * Every truth reader classifies through this one function so no reader
+ * can invent its own idea of absence: mistaking "could not look" for
+ * "not there" is the exact lie axiom 4 forbids. Only present or absent
+ * may produce a conclusion.
+ */
+const lookFailed = (error) => error.code === 'ENOENT' || error.code === 'ENOTDIR'
+    ? { truth: 'absent' }
+    : { truth: 'unsettled', reason: error.code };
+exports.lookFailed = lookFailed;
+/**
+ * The managed-reference adapter: Amalgm's OWN link kind, never
+ * conflated with a filesystem symlink. Its payload is the target
+ * entity's UUID — identity, not an address — and its local rendering as
+ * an ordinary symlink is DERIVED state (entity-model.md, symlink
+ * section). ASSIGNED, NOT YET OPERATIONAL — and that absence is the
+ * honest truth: no rail is bound because the projection lives inside
+ * the registration boundary today; its detect socket is ratified from
+ * that seam when the projection is extracted, never invented ahead of
+ * it.
+ */
+exports.referenceAdapter = Object.freeze({
+    name: 'reference',
+    types: Object.freeze({
+        reference: "its target entity's UUID — identity, not an address; the rendered symlink is derived state",
+    }),
+    rails: Object.freeze({}),
+});
+//# sourceMappingURL=adapter-contract.js.map