@amalgm/live 0.1.0

package/dist/contracts/resources.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+import { type Checked } from './validate.js';
+export type ResourceName = string;
+export type ParsedResource = {
+    readonly kind: 'table';
+    readonly name: string;
+} | {
+    readonly kind: 'app';
+    readonly appId: string;
+    readonly name: string;
+} | {
+    readonly kind: 'doc';
+    readonly path: string;
+} | {
+    readonly kind: 'files';
+    readonly dir: string;
+};
+/** `doc:<base64url(path)>` for the document at a local path. */
+export declare const docResource: (path: string) => ResourceName;
+/** `files:<base64url(dir)>` for the listing channel of a directory. */
+export declare const filesResource: (dir: string) => ResourceName;
+/** `app:<appId>:<name>` for an app-scoped resource. */
+export declare const appResource: (appId: string, name: string) => ResourceName;
+/**
+ * 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' }
+ */
+export declare function parseResource(resource: unknown): Checked<ParsedResource>;
+/** UTF-8 → unpadded base64url. Portable: no Buffer, no btoa. */
+export declare function encodeBase64Url(text: string): string;
+/** Unpadded base64url → UTF-8, or null when the input is not base64url. */
+export declare function decodeBase64Url(encoded: string): string | null;
+//# sourceMappingURL=resources.d.ts.map

package/dist/contracts/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/contracts/resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAqC,MAAM,eAAe,CAAC;AAEhF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD,gEAAgE;AAChE,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,YAA8C,CAAC;AAE1F,uEAAuE;AACvE,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,YAA+C,CAAC;AAE5F,uDAAuD;AACvD,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,YAAsC,CAAC;AAEjG;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CA6BxE;AAID,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAapD;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoB9D"}

package/dist/contracts/resources.js

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+import { pass, failShape, isNonEmptyString } from './validate.js';
+/** `doc:<base64url(path)>` for the document at a local path. */
+export const docResource = (path) => `doc:${encodeBase64Url(path)}`;
+/** `files:<base64url(dir)>` for the listing channel of a directory. */
+export const filesResource = (dir) => `files:${encodeBase64Url(dir)}`;
+/** `app:<appId>:<name>` for an app-scoped resource. */
+export const appResource = (appId, name) => `app:${appId}:${name}`;
+/**
+ * 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' }
+ */
+export function parseResource(resource) {
+    if (!isNonEmptyString(resource)) {
+        return 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
+                ? failShape(`"doc:${encodeBase64Url('notes.md')}" (base64url of the path)`, `"${resource}" carries invalid base64url`)
+                : pass({ kind: 'doc', path });
+        }
+        case 'files': {
+            const dir = decodeBase64Url(resource.slice('files:'.length));
+            return dir === null
+                ? failShape(`"files:${encodeBase64Url('notes')}" (base64url of the directory)`, `"${resource}" carries invalid base64url`)
+                : pass({ kind: 'files', dir });
+        }
+        case 'app': {
+            const rest = resource.slice('app:'.length);
+            const divider = rest.indexOf(':');
+            if (divider <= 0 || divider === rest.length - 1) {
+                return failShape('"app:<appId>:<name>", e.g. "app:canvas:board"', `"${resource}" is missing the appId or name segment`);
+            }
+            return pass({ kind: 'app', appId: rest.slice(0, divider), name: rest.slice(divider + 1) });
+        }
+        default:
+            return pass({ kind: 'table', name: resource });
+    }
+}
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+/** UTF-8 → unpadded base64url. Portable: no Buffer, no btoa. */
+export 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. */
+export 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/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/contracts/snapshot.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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".
+ */
+import { type Checked } from './validate.js';
+import type { ResourceName } from './resources.js';
+export interface Snapshot {
+    readonly seq: number;
+    /** False when every build attempt raced a write; data is best-effort at this seq. */
+    readonly stable: boolean;
+    readonly resources: Readonly<Record<ResourceName, unknown>>;
+}
+export declare function checkSnapshot(input: unknown): Checked<Snapshot>;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/contracts/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/contracts/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAoC,MAAM,eAAe,CAAC;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;CAC7D;AAID,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAQ/D"}

package/dist/contracts/snapshot.js

@@ -0,0 +1,28 @@
+/**
+ * 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".
+ */
+import { pass, failShape, isRecord, isSeq } from './validate.js';
+const EXAMPLE = '{ seq: 42, stable: true, resources: { tasks: [...] } }';
+export function checkSnapshot(input) {
+    if (!isRecord(input))
+        return failShape(EXAMPLE, `got ${input === null ? 'null' : typeof input}`);
+    if (!isSeq(input.seq))
+        return failShape(EXAMPLE, `seq was ${JSON.stringify(input.seq)}, not a non-negative integer`);
+    if (!isRecord(input.resources)) {
+        return 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 pass({ seq: input.seq, stable, resources: input.resources });
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/contracts/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/contracts/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAgB,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAU/E,MAAM,OAAO,GAAG,wDAAwD,CAAC;AAEzE,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC,OAAO,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;IACjG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC,OAAO,EAAE,WAAW,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;IACrH,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC,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,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist/contracts/validate.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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).
+ */
+export type Checked<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export declare const pass: <T>(value: T) => Checked<T>;
+export declare const fail: <T = never>(error: string) => Checked<T>;
+/**
+ * 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')
+ */
+export declare const failShape: <T = never>(expected: string, problem: string) => Checked<T>;
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const isNonEmptyString: (value: unknown) => value is string;
+/** A strictly increasing wire sequence number: a non-negative safe integer. */
+export declare const isSeq: (value: unknown) => value is number;
+//# sourceMappingURL=validate.d.ts.map

package/dist/contracts/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/contracts/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,OAAO,CAAC,CAAC,IACjB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACxC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,OAAO,CAAC,CAAC,CAA0B,CAAC;AAEvE,eAAO,MAAM,IAAI,GAAI,CAAC,GAAG,KAAK,EAAE,OAAO,MAAM,KAAG,OAAO,CAAC,CAAC,CAA2B,CAAC;AAErF;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,GAAG,KAAK,EAAE,UAAU,MAAM,EAAE,SAAS,MAAM,KAAG,OAAO,CAAC,CAAC,CACvC,CAAC;AAE5C,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CACH,CAAC;AAEvE,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACZ,CAAC;AAEhD,+EAA+E;AAC/E,eAAO,MAAM,KAAK,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACwB,CAAC"}

package/dist/contracts/validate.js

@@ -0,0 +1,25 @@
+/**
+ * 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).
+ */
+export const pass = (value) => ({ ok: true, value });
+export const fail = (error) => ({ ok: false, error });
+/**
+ * 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')
+ */
+export const failShape = (expected, problem) => fail(`expected ${expected} — ${problem}`);
+export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
+/** A strictly increasing wire sequence number: a non-negative safe integer. */
+export const isSeq = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+//# sourceMappingURL=validate.js.map

package/dist/contracts/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/contracts/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAI,KAAQ,EAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAEvE,MAAM,CAAC,MAAM,IAAI,GAAG,CAAY,KAAa,EAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AAErF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAY,QAAgB,EAAE,OAAe,EAAc,EAAE,CACpF,IAAI,CAAC,YAAY,QAAQ,MAAM,OAAO,EAAE,CAAC,CAAC;AAE5C,MAAM,CAAC,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;AAEvE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAAmB,EAAE,CAClE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AAEhD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,KAAc,EAAmB,EAAE,CACvD,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC"}

package/dist/detection/adapter-contract.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+export type Rail = 'watch' | 'detect' | 'record' | 'send' | 'receive' | 'apply' | 'verify';
+/** The seven rails, declared once, frozen, in journey order. */
+export declare const RAILS: readonly Rail[];
+/**
+ * The three honest answers of a truth read (axiom 4):
+ *
+ *   { truth: 'present', version, state }   the complete current truth,
+ *     fingerprinted — equal versions mean equal truth, and equal truth
+ *     is silence
+ *   { truth: 'absent' }                    the ground genuinely is not
+ *     there — a fact, not an error
+ *   { truth: 'unsettled', reason }         changing or unreadable right
+ *     now; read again — never a partial answer
+ */
+export type TruthReading = {
+    readonly truth: 'present';
+    readonly version: string;
+    readonly state?: unknown;
+} | {
+    readonly truth: 'absent';
+} | {
+    readonly truth: 'unsettled';
+    readonly reason?: string | undefined;
+};
+/** The one ratified socket: detect's truth read. */
+export interface DetectSocket {
+    readonly truth: (path: string) => TruthReading;
+}
+/**
+ * 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.
+ */
+export declare const SOCKETS: Readonly<Partial<Record<Rail, readonly string[]>>>;
+/**
+ * A lawful adapter descriptor. The shape is deliberately tiny:
+ *
+ *   name   — the adapter's one name
+ *   types  — { entityType: 'one-sentence source of truth', ... }
+ *   rails  — only rails whose ratified socket the adapter fully
+ *            implements; detect is the only bindable rail today
+ */
+export interface AdapterDescriptor {
+    readonly name: string;
+    readonly types: Readonly<Record<string, string>>;
+    readonly rails: {
+        readonly detect?: DetectSocket;
+    };
+}
+/**
+ * Convict a malformed adapter descriptor loudly; return it (typed)
+ * unchanged when lawful.
+ */
+export declare function assertAdapter(adapter: unknown): AdapterDescriptor;
+/**
+ * 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.
+ */
+export declare function buildTypeMap(adapters: Iterable<unknown>, alphabet: Iterable<string>): Map<string, AdapterDescriptor>;
+/** A failed look at ground, as the host's filesystem reported it. */
+export interface FailedLook {
+    readonly code?: string | undefined;
+}
+/**
+ * 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.
+ */
+export declare const lookFailed: (error: FailedLook) => {
+    readonly truth: "absent";
+} | {
+    readonly truth: "unsettled";
+    readonly reason: string | undefined;
+};
+/**
+ * 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.
+ */
+export declare const referenceAdapter: AdapterDescriptor;
+//# sourceMappingURL=adapter-contract.d.ts.map

package/dist/detection/adapter-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-contract.d.ts","sourceRoot":"","sources":["../../src/detection/adapter-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,MAAM,IAAI,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE3F,gEAAgE;AAChE,eAAO,MAAM,KAAK,EAAE,SAAS,IAAI,EAE/B,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE1E,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,YAAY,CAAC;CAChD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAErE,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC;CACpD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,CA6CjE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAC3B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,GACzB,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAsBhC;AAED,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GACrB,OAAO,UAAU,KAChB;IAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CAGpD,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAM7B,CAAC"}

package/dist/detection/adapter-contract.js

@@ -0,0 +1,162 @@
+/**
+ * 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.
+ */
+/** The seven rails, declared once, frozen, in journey order. */
+export const 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.
+ */
+export const SOCKETS = Object.freeze({
+    detect: Object.freeze(['truth']),
+});
+/**
+ * Convict a malformed adapter descriptor loudly; return it (typed)
+ * unchanged when lawful.
+ */
+export 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 (!RAILS.includes(rail)) {
+            throw new Error(`${where}: ${JSON.stringify(rail)} is not a rail — the rails are ${RAILS.join(', ')}`);
+        }
+        const socket = 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.
+ */
+export 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.
+ */
+export const lookFailed = (error) => error.code === 'ENOENT' || error.code === 'ENOTDIR'
+    ? { truth: 'absent' }
+    : { truth: 'unsettled', reason: error.code };
+/**
+ * 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.
+ */
+export const 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

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-contract.js","sourceRoot":"","sources":["../../src/detection/adapter-contract.ts"],"names":[],"mappings":"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"}

package/dist/detection/classify.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Amalgm's file-type policy: which physical type a piece of file ground
+ * takes. Ratified by entity-model.md ("Formats live underneath the file
+ * types"; text versus binary is an adapter difference, never an
+ * identity difference).
+ *
+ * Classification is an INJECTED policy everywhere it is used — the
+ * registration boundary and its lenses refuse to construct without one
+ * — so it lives in its own file with no other job: one definition,
+ * replaceable whole.
+ *
+ * The rule is the oldest one there is: bytes holding a NUL are not
+ * text. What matters is WHERE that fact comes from. It is not read
+ * here. Detect's single read of a file produces its fingerprint and
+ * this report together, and this policy only names the type that report
+ * implies.
+ *
+ * That is the whole law: A FILE'S HASH AND ITS TYPE DESCRIBE THE SAME
+ * OBSERVED BYTES. A policy that opened the ground itself would be a
+ * second look — and a second look can meet different bytes, or none at
+ * all, leaving a record whose type contradicts the payload beside it.
+ * So this function takes evidence, never a path; it is total, and it
+ * cannot fail.
+ */
+export type FileType = 'file.binary' | 'file.text';
+/** Detect's report on the bytes it hashed — the same read as the fingerprint. */
+export interface ClassifyEvidence {
+    readonly binary: boolean;
+}
+export declare function classifyFile({ binary }: ClassifyEvidence): FileType;
+//# sourceMappingURL=classify.d.ts.map