@rindle/room 0.5.0

package/dist/mutation-tx.js

@@ -0,0 +1,207 @@
+// The room-side MutationTx (RINDLE-REALTIME-DESIGN.md §5.1; OPTIMISTIC-WRITES-DESIGN.md
+// §4.2): the write handle a room mutator runs against, structurally identical to
+// `@rindle/optimistic`'s client MutationTx — the whole point of §4.2's "two registries,
+// one interface" is that an app can register its client mutators in the room VERBATIM
+// (`mutators` from a shared app-def typechecks against `RoomMutator` as-is). Declared
+// locally rather than imported so @rindle/room does not depend on the browser client
+// stack; TS structural typing keeps the two in lockstep at the app's call site.
+//
+// Backing: the wasm room's staged transaction (txGet/txAdd/txEdit/txRemove). Only
+// concrete cells cross the JSON boundary — `undefined` ("leave unchanged") in the
+// positional `edit` and the partial keyed `update` is resolved HERE against the
+// effective row (`txGet`: live head under this tx's own staged writes), the same merge
+// the browser WriteTxn does at its staging boundary. Reads are read-your-writes by
+// construction. Every refusal below (unknown column, width, presence) throws — the
+// shell catches a mutator throw and turns the whole mutation into a reject.
+/**
+ * Tag an error as an ENVIRONMENT shortfall (H-iv-b): the room lacks a capability the
+ * mutation needs (today: `tx.query`), which is a verdict about the ROOM, not the
+ * mutation — the shell classifies it as a DEOPT (the client re-routes the mutation to
+ * the daemon stream, where the capability exists) instead of a FINAL rejection (which
+ * would drop the mutation). Contrast a validation/authz throw: re-routing can't help
+ * those, so they stay `rejected`.
+ */
+export function environmentShortfall(message) {
+    const e = new Error(message);
+    e.roomEnvironmentShortfall = true;
+    return e;
+}
+/** Whether `e` was tagged by {@link environmentShortfall}. */
+export function isEnvironmentShortfall(e) {
+    return (e?.roomEnvironmentShortfall === true);
+}
+/**
+ * Guard against the two mutator shapes that would corrupt silently instead of failing loudly.
+ * A `shared(...)` GENERATOR registered verbatim returns an un-iterated generator — zero writes,
+ * acked as applied (data loss); an ASYNC mutator runs synchronously only to its first `await`,
+ * so later writes land OUTSIDE the committed transaction. Both shells call this on the
+ * mutator's return value inside their try/reject path, so either shape becomes an explicit
+ * rejection with a pointed message. (An adapter that DRIVES a shared generator registry against
+ * the room tx is future work — managed-writes design §8.)
+ */
+export function assertSyncMutatorReturn(returned, name) {
+    if (returned === undefined || returned === null)
+        return;
+    const r = returned;
+    if (typeof r.then === "function") {
+        throw new Error(`mutator \`${name}\` returned a promise — room mutators must be synchronous ` +
+            `(writes after an \`await\` would land outside the transaction)`);
+    }
+    if (typeof r.next === "function") {
+        throw new Error(`mutator \`${name}\` returned a generator — a shared(...) registry cannot register ` +
+            `verbatim as room mutators (nothing would drive it; zero writes would be acked). ` +
+            `Write plain synchronous (tx, args, ctx) mutators for the room bundle.`);
+    }
+}
+function shapeOf(shapes, table) {
+    const s = shapes.get(table);
+    if (!s)
+        throw new Error(`unknown table \`${table}\``);
+    return s;
+}
+/** pk cells (primaryKey order) from a keyed probe — every pk column must be named. */
+function keyedPk(shape, table, pk) {
+    return shape.primaryKey.map((c) => {
+        const name = shape.columns[c];
+        const v = pk[name];
+        if (v === undefined) {
+            throw new Error(`missing primary-key column \`${name}\` for \`${table}\``);
+        }
+        return v;
+    });
+}
+function assertKnownColumns(shape, table, row) {
+    for (const name of Object.keys(row)) {
+        if (!shape.columns.includes(name)) {
+            throw new Error(`unknown column \`${name}\` for \`${table}\``);
+        }
+    }
+}
+/** Build the MutationTx for one open wasm transaction. Valid only while that
+ *  transaction is open — the shell creates one per mutation and never retains it. */
+export function mutationTx(room, shapes) {
+    const getRow = (table, pkCells) => {
+        const text = room.txGet(table, JSON.stringify(pkCells));
+        return text === undefined ? undefined : JSON.parse(text);
+    };
+    /** Resolve `undefined` cells ("leave unchanged") against the effective row; the
+     *  row must exist. Only concrete cells may cross the JSON boundary — a stringified
+     *  `undefined` would silently become `null`. */
+    const resolveCells = (table, shape, cells) => {
+        if (cells.length !== shape.columns.length) {
+            throw new Error(`row width does not match the schema of \`${table}\``);
+        }
+        const pkCells = shape.primaryKey.map((c) => {
+            const v = cells[c];
+            if (v === undefined) {
+                throw new Error(`primary-key cells must be concrete (\`${table}\`)`);
+            }
+            return v;
+        });
+        const current = getRow(table, pkCells);
+        if (cells.every((v) => v !== undefined))
+            return cells;
+        if (current === undefined)
+            return undefined;
+        return cells.map((v, i) => (v === undefined ? current[i] : v));
+    };
+    return {
+        row(table, pk) {
+            const shape = shapeOf(shapes, table);
+            const cells = getRow(table, keyedPk(shape, table, pk));
+            if (cells === undefined)
+                return undefined;
+            const out = {};
+            shape.columns.forEach((name, i) => (out[name] = cells[i]));
+            return out;
+        },
+        insert(table, row) {
+            const shape = shapeOf(shapes, table);
+            assertKnownColumns(shape, table, row);
+            const cells = shape.columns.map((name) => {
+                const v = row[name];
+                if (v === undefined) {
+                    throw new Error(`insert of \`${table}\` is missing column \`${name}\``);
+                }
+                return v;
+            });
+            room.txAdd(table, JSON.stringify(cells));
+        },
+        update(table, row) {
+            const shape = shapeOf(shapes, table);
+            assertKnownColumns(shape, table, row);
+            const pkCells = keyedPk(shape, table, row);
+            const current = getRow(table, pkCells);
+            if (current === undefined)
+                return; // rebase-friendly no-op
+            const cells = shape.columns.map((name, i) => {
+                const v = row[name];
+                return v === undefined ? current[i] : v;
+            });
+            room.txEdit(table, JSON.stringify(cells));
+        },
+        upsert(table, row) {
+            const shape = shapeOf(shapes, table);
+            assertKnownColumns(shape, table, row);
+            const cells = shape.columns.map((name) => {
+                const v = row[name];
+                if (v === undefined) {
+                    throw new Error(`upsert of \`${table}\` is missing column \`${name}\``);
+                }
+                return v;
+            });
+            const pkCells = keyedPk(shape, table, row);
+            if (getRow(table, pkCells) === undefined) {
+                room.txAdd(table, JSON.stringify(cells));
+            }
+            else {
+                room.txEdit(table, JSON.stringify(cells));
+            }
+        },
+        delete(table, pk) {
+            const shape = shapeOf(shapes, table);
+            const pkCells = keyedPk(shape, table, pk);
+            if (getRow(table, pkCells) === undefined)
+                return; // rebase-friendly no-op
+            room.txRemove(table, JSON.stringify(pkCells));
+        },
+        query() {
+            // An environment shortfall, not a mutation verdict: the shell classifies this
+            // throw as a DEOPT so the client re-routes to the daemon stream (H-iv-b).
+            throw environmentShortfall("tx.query is not supported in room mutators yet");
+        },
+        get(table, pk) {
+            shapeOf(shapes, table);
+            return getRow(table, pk);
+        },
+        add(table, row) {
+            const shape = shapeOf(shapes, table);
+            if (row.some((v) => v === undefined)) {
+                throw new Error(`add of \`${table}\`: cells must be concrete`);
+            }
+            if (row.length !== shape.columns.length) {
+                throw new Error(`row width does not match the schema of \`${table}\``);
+            }
+            room.txAdd(table, JSON.stringify(row));
+        },
+        remove(table, row) {
+            const shape = shapeOf(shapes, table);
+            if (row.length !== shape.columns.length) {
+                throw new Error(`row width does not match the schema of \`${table}\``);
+            }
+            room.txRemove(table, JSON.stringify(shape.primaryKey.map((c) => row[c])));
+        },
+        edit(table, _oldRow, newRow) {
+            // The authority composes `old` from its own effective read (the wasm side);
+            // the caller's oldRow is its *prediction* of old — unused here, kept in the
+            // signature for client-registry compatibility.
+            const shape = shapeOf(shapes, table);
+            const resolved = resolveCells(table, shape, newRow);
+            if (resolved === undefined) {
+                throw new Error(`no row with that primary key in \`${table}\``);
+            }
+            room.txEdit(table, JSON.stringify(resolved));
+        },
+    };
+}
+//# sourceMappingURL=mutation-tx.js.map

package/dist/mutation-tx.js.map

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

package/dist/shell.d.ts

@@ -0,0 +1,134 @@
+import { type RoomMutator } from "./mutation-tx.ts";
+import { type RoomJournal } from "./journal.ts";
+import type { RoomAuthority } from "./authority.ts";
+/** The upstream half of the shell's config: where rindled lives and what to follow. */
+export interface UpstreamOptions {
+    /** rindled's public subscription plane, e.g. `ws://127.0.0.1:7601`. */
+    wsUrl: string;
+    /** rindled's private control plane, e.g. `http://127.0.0.1:7600` (lease minting). */
+    controlUrl: string;
+    /** Bearer token for the control plane (required unless rindled runs unauthenticated). */
+    authToken?: string;
+    /** The document footprint — a wire `Ast` (§3.1). What this room follows and serves from. */
+    footprintAst: unknown;
+    /** Lease TTL passed to `/materialize` (rindled's default when omitted). */
+    leaseTtlMs?: number;
+    /** The `init` clientID on the upstream socket (diagnostic identity). */
+    clientId?: string;
+}
+/** The downstream half: how clients are authorized and served (§4/§10.1). */
+export interface DownstreamOptions {
+    /** This room's document id — lease tokens for any other doc are refused. */
+    docId: string;
+    /** Token key ring: `kid` → shared secret (the API server signs with the same ring). */
+    tokenKeys: Record<string, string>;
+    /** Idle grace before an unsubscribed query's pipeline is reclaimed (default 30s). */
+    idleTtlMs?: number;
+    /** Lease-expiry / idle-sweep cadence (default 1s). */
+    sweepIntervalMs?: number;
+    /** How long a revocation keeps refusing pre-revocation tokens (default 30min — set
+     *  it ≥ the longest token TTL the API server mints). */
+    revocationWindowMs?: number;
+    /** The room's private control plane (`POST /revoke`, `GET /stats`). Omit to run
+     *  without one (no revocation surface). */
+    control?: {
+        authToken: string;
+        port?: number;
+    };
+    /** The write plane (§5.1). Omit to run read-only (writes are refused). */
+    writes?: WritesOptions;
+    /** Per-socket downstream send budget in bytes (§9; default 4 MiB). A socket whose
+     *  queued bytes would exceed it is terminated with a gap — re-subscribing is the
+     *  repair. */
+    sendBudgetBytes?: number;
+}
+/** One table's §3.3 scope spec (H-iv-b): an element of the api-server's
+ *  `RoomBootResponse.scopes`, passed VERBATIM to the wasm room's `enableWritesV2`.
+ *  Structurally identical to `@rindle/api-server`'s `RoomScopeSpec` (declared locally —
+ *  the shell must not depend on the api-server package; TS structural typing keeps the
+ *  two in lockstep at the host's threading site). */
+export interface RoomScopeSpec {
+    table: string;
+    /** The footprint's row-local predicate for this table (a wire `Condition`) — drives
+     *  the commit gate's absent-read proof. Absent ⇒ absent reads on this table always
+     *  deopt (fail closed). */
+    footprintWhere?: unknown;
+    writable: {
+        kind: "none";
+    } | {
+        kind: "predicate";
+        where?: unknown;
+        joinKeyCols: string[];
+    };
+}
+/** The §5.1 write plane: the room's own mutator registry over its owned tables. */
+export interface WritesOptions {
+    /** The server registry (§4.2): named mutators run against the shared head. PLAIN
+     *  synchronous `(tx, args, ctx)` functions only — a `shared(...)` GENERATOR registry
+     *  does NOT register verbatim (nothing drives it here; the shell rejects a mutator
+     *  that returns a generator/promise — see `assertSyncMutatorReturn`). */
+    mutators: Record<string, RoomMutator>;
+    /** §3.2's owned set — the only tables mutators may write. Must all be in the
+     *  upstream footprint; followed tables and the ledger are never writable. */
+    ownedTables: string[];
+    /** The §3.3 per-table scope specs from the boot wire (`RoomBootResponse.scopes` —
+     *  H-iv-b). Present ⇒ the write plane enables in v2 GATED mode (`enableWritesV2`):
+     *  staged writes validate against the writable predicates, join-key edits refuse,
+     *  absent reads must prove against `footprintWhere`, context (`kind:"none"`) tables
+     *  become txGet-READABLE, and a violating commit returns a structured DEOPT instead
+     *  of applying. The scopes' writable tables must be a SUBSET of {@link ownedTables}
+     *  (the host's own declaration) — a wider server scope throws at construction, so a
+     *  self-hoster's owned set can never be extended from the wire. Absent ⇒ the v1
+     *  table-granular write plane, byte-identical to before. */
+    scopes?: RoomScopeSpec[];
+    /** The durable sidecar an ack means (§8.1). Defaults to `memoryJournal()` — the
+     *  "survives nothing beyond the process" class; hosts bring their own. */
+    journal?: RoomJournal;
+    /** The journal group-commit window (default 5ms): mutations arriving within it
+     *  share one append, and their acks ride one ledger commit. */
+    groupCommitMs?: number;
+    /** The write authority (§5.3.1) — the API server's `/apply-row-change-txn` host
+     *  (or the P3 gate's mock). Omit to run journal-only (P2 semantics: nothing is
+     *  ever durable upstream). With an authority, the shell claims a placement epoch
+     *  at boot, probes durable lmids before replay, and write-behinds on the flush
+     *  cadence (§5.3). */
+    authority?: RoomAuthority;
+    /** The flush debounce (§5.3; default 250ms, within the design's ≤1s budget). */
+    flushDebounceMs?: number;
+    /** Flush immediately once this many keys are dirty (default 512). */
+    flushDirtyMax?: number;
+}
+export interface RoomShellOptions {
+    upstream: UpstreamOptions;
+    downstream: DownstreamOptions;
+    /** Downstream ws port (default 0 = ephemeral; bound on 127.0.0.1). */
+    port?: number;
+    /** Diagnostic sink (default: silent). */
+    log?: (line: string) => void;
+}
+export interface RoomShell {
+    /** The bound downstream port. */
+    readonly port: number;
+    /** The bound control-plane port (0 when no control plane was configured). */
+    readonly controlPort: number;
+    /** Resolves when the CURRENT incarnation is live (seq-0 snapshot applied);
+     *  immediately if it already is. */
+    awaitLive(): Promise<void>;
+    /** The last-applied upstream commit version, if live. */
+    cv(): number | undefined;
+    /** The upstream subscription epoch of the current incarnation, if any. */
+    upstreamEpoch(): number | undefined;
+    /** This incarnation's downstream bootId (rotates on every re-subscribe). */
+    bootId(): string;
+    /** Fire the write-behind flush now (instead of the debounce) and await its
+     *  settlement — deterministic flushing for tests and drain-before-close. No-op
+     *  without an authority. */
+    flushNow(): Promise<void>;
+    close(): Promise<void>;
+}
+/** Boot a room shell: init the wasm, mint the upstream lease, connect the upstream leg,
+ *  and serve the downstream ws (+ the private control plane, if configured). Returns
+ *  once the ports are bound and the upstream connection is underway — await
+ *  `shell.awaitLive()` for the seed. */
+export declare function createRoomShell(opts: RoomShellOptions): Promise<RoomShell>;
+//# sourceMappingURL=shell.d.ts.map

package/dist/shell.d.ts.map

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