@rindle/room 0.5.0

package/build.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Build the rindle-room-wasm crate into this package as a portable ESM artifact by default
+# (--target web): works in browsers/Workers (await init()) and Node (await init(bytes)) — see
+# src/wasm.ts. The same artifact the Durable Object shell will run; the Node test shell
+# drives it unmodified (RINDLE-REALTIME-DESIGN.md §11).
+#
+#   ./build.sh [profile]   # wasm-release (default) | release | dev
+#
+# Produces packages/room/pkg/{rindle_room.js, rindle_room_bg.wasm, rindle_room.d.ts}.
+# Advanced wrappers may override:
+#   RINDLE_WASM_OUT             output directory
+#   RINDLE_WASM_BINDGEN_TARGET  wasm-bindgen target (default: web)
+set -euo pipefail
+
+PROFILE="${1:-wasm-release}"
+TARGET=wasm32-unknown-unknown
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+# The Cargo workspace lives under rust/; the wasm artifact ships into this JS package's pkg/ (which
+# stays at the repo root). Build from rust/ so `-p rindle-room-wasm` and target/ resolve; emit into packages/room/pkg.
+RUST_ROOT="$ROOT/rust"
+OUT="${RINDLE_WASM_OUT:-$ROOT/packages/room/pkg}"
+BINDGEN_TARGET="${RINDLE_WASM_BINDGEN_TARGET:-web}"
+export PATH="$HOME/.cargo/bin:$PATH"
+
+cd "$RUST_ROOT"
+
+# `cargo rustc … --crate-type cdylib`: the lib's default crate-type is `rlib` (native builds
+# must not emit a colliding cdylib, cargo#6313); the `.wasm` artifact needs `cdylib`, requested
+# here just for this wasm32 build. Produces `target/$TARGET/<profile>/rindle_room_wasm.wasm`.
+case "$PROFILE" in
+  dev)     cargo rustc -p rindle-room-wasm                     --target "$TARGET" --crate-type cdylib; WASM="$RUST_ROOT/target/$TARGET/debug/rindle_room_wasm.wasm" ;;
+  release) cargo rustc -p rindle-room-wasm --release           --target "$TARGET" --crate-type cdylib; WASM="$RUST_ROOT/target/$TARGET/release/rindle_room_wasm.wasm" ;;
+  *)       cargo rustc -p rindle-room-wasm --profile "$PROFILE" --target "$TARGET" --crate-type cdylib; WASM="$RUST_ROOT/target/$TARGET/$PROFILE/rindle_room_wasm.wasm" ;;
+esac
+
+wasm-bindgen --target "$BINDGEN_TARGET" --out-dir "$OUT" --out-name rindle_room "$WASM"
+
+if command -v wasm-opt >/dev/null 2>&1 && [ "$PROFILE" != "dev" ]; then
+  # Same binaryen version guard as packages/wasm/build.sh (multi-table export bug < 110
+  # corrupts the reference-types externref table; wasm-bindgen#4528).
+  wo_ver="$(wasm-opt --version 2>/dev/null | grep -oE '[0-9]+' | head -1 || true)"
+  if [ -n "$wo_ver" ] && [ "$wo_ver" -lt 110 ]; then
+    echo "error: wasm-opt (binaryen) version $wo_ver is too old; need >= 110." >&2
+    echo "       binaryen < 110 corrupts the reference-types externref table, so the wasm fails at" >&2
+    echo "       runtime with 'WebAssembly.Table.grow(): failed to grow table by 4'." >&2
+    echo "       Install a newer binaryen: https://github.com/WebAssembly/binaryen/releases" >&2
+    exit 1
+  fi
+  wasm-opt -Oz "$OUT/rindle_room_bg.wasm" -o "$OUT/rindle_room_bg.wasm"
+  echo "wasm-opt -Oz applied"
+fi
+
+echo "built $OUT  (target=$BINDGEN_TARGET, profile=$PROFILE, $(wc -c < "$OUT/rindle_room_bg.wasm") bytes)"

package/dist/authority.d.ts

@@ -0,0 +1,57 @@
+/** One CAS rejection in the authority's `409 conflict` body: the row's authoritative
+ *  current image (`null` = absent), keyed by table + pk cells. */
+export interface AuthorityConflict {
+    table: string;
+    pk: unknown[];
+    current: unknown[] | null;
+}
+/** The apply outcome. Anything else — network failure, a 5xx — is a **throw**: plain
+ *  errors retry (same body, same id; dedup absorbs a landed retry), errors marked
+ *  `fatal: true` (an identity mismatch — same id, different body — or a malformed
+ *  refusal) kill the incarnation loudly instead. */
+export type AuthorityApplyResult = {
+    kind: "ok";
+    applied: boolean;
+    cv?: number;
+} | {
+    kind: "conflict";
+    conflicts: AuthorityConflict[];
+} | {
+    kind: "fenced";
+    currentEpoch?: number;
+};
+export interface RoomAuthority {
+    /** Claim the placement epoch for `doc` (§2.5) — once per shell process, at boot,
+     *  AFTER resubmitting the previous incarnation's unconfirmed batches (their recorded
+     *  epochs must still be current to land). */
+    claimEpoch(doc: string): Promise<number>;
+    /** The authority's ledger lmid per client (0 = none) — the boot probe that lets
+     *  journal replay absorb already-durable mutations as dedup. */
+    lmids(doc: string, clients: string[]): Promise<Record<string, number>>;
+    /** Apply one batch: `body` is the exact journaled `/apply-row-change-txn` body
+     *  string, sent verbatim. */
+    applyRowChangeTxn(body: string): Promise<AuthorityApplyResult>;
+}
+/** An apply error the shell must NOT retry (retrying cannot help; something is wrong
+ *  with the batch or the room, not the network). */
+export interface FatalAuthorityError extends Error {
+    fatal: true;
+}
+export declare function fatalAuthorityError(message: string): FatalAuthorityError;
+export interface HttpAuthorityOptions {
+    /** The API server's apply endpoint (e.g. `http://…/api/rindle/apply-row-change-txn`). */
+    applyUrl: string;
+    /** The epoch-claim endpoint (e.g. `http://…/api/rindle/claim-room-epoch`). */
+    claimUrl: string;
+    /** The lmid-probe endpoint (e.g. `http://…/api/rindle/room-lmids`). */
+    lmidsUrl: string;
+    /** Extra headers on every call — the epoch-bound flush credential rides here. */
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+}
+/** The HTTP [`RoomAuthority`]: the API-server host as the room's sole counterpart
+ *  (§5.3.1). Maps `409 {error:"fenced"}` / `409 {error:"conflict"}` to their results,
+ *  a `500` mentioning a batch-identity mismatch to a fatal error, and anything else
+ *  non-OK to a retryable throw. */
+export declare function httpAuthority(opts: HttpAuthorityOptions): RoomAuthority;
+//# sourceMappingURL=authority.d.ts.map

package/dist/authority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authority.d.ts","sourceRoot":"","sources":["../src/authority.ts"],"names":[],"mappings":"AAcA;kEACkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC3B;AAED;;;oDAGoD;AACpD,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,iBAAiB,EAAE,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B;;iDAE6C;IAC7C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC;oEACgE;IAChE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvE;iCAC6B;IAC7B,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAChE;AAED;oDACoD;AACpD,MAAM,WAAW,mBAAoB,SAAQ,KAAK;IAChD,KAAK,EAAE,IAAI,CAAC;CACb;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAIxE;AAED,MAAM,WAAW,oBAAoB;IACnC,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;mCAGmC;AACnC,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,aAAa,CAsDvE"}

package/dist/authority.js

@@ -0,0 +1,73 @@
+// The room's **write-authority seam** (RINDLE-REALTIME-DESIGN.md §5.3.1): the three
+// calls a flushing room makes against the app's authority — claim a placement epoch at
+// boot (§2.5), probe the durable lmids before journal replay (§3.3, T2's
+// committed-before-crash row), and apply one journaled batch. In every deployment shape
+// the counterpart is the API server's `/apply-row-change-txn` host ([`httpAuthority`]);
+// the P3 gate drives the same interface against an in-process mock, which is what keeps
+// the contract host-independent.
+//
+// The apply takes the **exact composed body string** the shell journaled — never a
+// re-serialized object. One flush id names one immutable byte body forever (§5.3
+// step 4): a retry, a crash-replay resubmission, and the first send all put identical
+// bytes on the wire, which is what makes the authority's `batch_hash` identity check
+// (§8.3, T6) meaningful.
+export function fatalAuthorityError(message) {
+    const e = new Error(message);
+    e.fatal = true;
+    return e;
+}
+/** The HTTP [`RoomAuthority`]: the API-server host as the room's sole counterpart
+ *  (§5.3.1). Maps `409 {error:"fenced"}` / `409 {error:"conflict"}` to their results,
+ *  a `500` mentioning a batch-identity mismatch to a fatal error, and anything else
+ *  non-OK to a retryable throw. */
+export function httpAuthority(opts) {
+    const doFetch = opts.fetch ?? fetch;
+    const headers = { "content-type": "application/json", ...(opts.headers ?? {}) };
+    const post = async (url, body) => doFetch(url, { method: "POST", headers, body });
+    return {
+        async claimEpoch(doc) {
+            const res = await post(opts.claimUrl, JSON.stringify({ doc }));
+            if (!res.ok) {
+                throw new Error(`claim-room-epoch failed: ${res.status} ${await res.text()}`);
+            }
+            const out = (await res.json());
+            if (typeof out.epoch !== "number") {
+                throw fatalAuthorityError("claim-room-epoch returned no epoch");
+            }
+            return out.epoch;
+        },
+        async lmids(doc, clients) {
+            const res = await post(opts.lmidsUrl, JSON.stringify({ doc, clients }));
+            if (!res.ok) {
+                throw new Error(`room-lmids failed: ${res.status} ${await res.text()}`);
+            }
+            const out = (await res.json());
+            return out.lmids ?? {};
+        },
+        async applyRowChangeTxn(body) {
+            const res = await post(opts.applyUrl, body);
+            if (res.status === 409) {
+                const out = (await res.json());
+                if (out.error === "fenced") {
+                    return { kind: "fenced", currentEpoch: out.currentEpoch };
+                }
+                if (out.error === "conflict") {
+                    return { kind: "conflict", conflicts: out.conflicts ?? [] };
+                }
+                throw new Error(`apply-row-change-txn 409: ${JSON.stringify(out)}`);
+            }
+            if (!res.ok) {
+                const text = await res.text();
+                // The §8.3 identity check: same flush id, different body — OUR bug, loud,
+                // never retried (a retry re-sends the same mismatched bytes forever).
+                if (res.status === 500 && text.includes("batch identity")) {
+                    throw fatalAuthorityError(`apply-row-change-txn: ${text}`);
+                }
+                throw new Error(`apply-row-change-txn failed: ${res.status} ${text}`);
+            }
+            const out = (await res.json());
+            return { kind: "ok", applied: out.applied === true, cv: out.cv };
+        },
+    };
+}
+//# sourceMappingURL=authority.js.map

package/dist/authority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authority.js","sourceRoot":"","sources":["../src/authority.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,uFAAuF;AACvF,yEAAyE;AACzE,wFAAwF;AACxF,wFAAwF;AACxF,wFAAwF;AACxF,iCAAiC;AACjC,EAAE;AACF,mFAAmF;AACnF,iFAAiF;AACjF,sFAAsF;AACtF,qFAAqF;AACrF,yBAAyB;AAsCzB,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,MAAM,CAAC,GAAG,IAAI,KAAK,CAAC,OAAO,CAAwB,CAAC;IACpD,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC;IACf,OAAO,CAAC,CAAC;AACX,CAAC;AAcD;;;mCAGmC;AACnC,MAAM,UAAU,aAAa,CAAC,IAA0B;IACtD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC;IACpC,MAAM,OAAO,GAAG,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;IAChF,MAAM,IAAI,GAAG,KAAK,EAAE,GAAW,EAAE,IAAY,EAAqB,EAAE,CAClE,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,OAAO;QACL,KAAK,CAAC,UAAU,CAAC,GAAG;YAClB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;YAC/D,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,4BAA4B,GAAG,CAAC,MAAM,IAAI,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAChF,CAAC;YACD,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuB,CAAC;YACrD,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAClC,MAAM,mBAAmB,CAAC,oCAAoC,CAAC,CAAC;YAClE,CAAC;YACD,OAAO,GAAG,CAAC,KAAK,CAAC;QACnB,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO;YACtB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;YACxE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,CAAC,MAAM,IAAI,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC1E,CAAC;YACD,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuC,CAAC;YACrE,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;QACzB,CAAC;QACD,KAAK,CAAC,iBAAiB,CAAC,IAAI;YAC1B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAC5C,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBACvB,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAI5B,CAAC;gBACF,IAAI,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC3B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC;gBAC5D,CAAC;gBACD,IAAI,GAAG,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;oBAC7B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;gBAC9D,CAAC;gBACD,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACtE,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;gBAC9B,0EAA0E;gBAC1E,sEAAsE;gBACtE,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;oBAC1D,MAAM,mBAAmB,CAAC,yBAAyB,IAAI,EAAE,CAAC,CAAC;gBAC7D,CAAC;gBACD,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC;YACxE,CAAC;YACD,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuC,CAAC;YACrE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,KAAK,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC;QACnE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { initRoomWasm, WasmRoom } from "./wasm.ts";
+export { createRoomShell } from "./shell.ts";
+export type { DownstreamOptions, RoomScopeSpec, RoomShell, RoomShellOptions, UpstreamOptions, WritesOptions, } from "./shell.ts";
+export { journalEntryOutcome, memoryJournal } from "./journal.ts";
+export type { RoomFlushRecord, RoomJournal, RoomJournalEntry } from "./journal.ts";
+export { fatalAuthorityError, httpAuthority } from "./authority.ts";
+export type { AuthorityApplyResult, AuthorityConflict, HttpAuthorityOptions, RoomAuthority, } from "./authority.ts";
+export type { KeyedRow, MutationTx, RoomMutator, RoomMutatorCtx, WireValue, } from "./mutation-tx.ts";
+export { mintRoomToken, verifyRoomToken, RoomTokenError, scopeSpecsHash } from "./token.ts";
+export type { MintRoomTokenOptions, RoomTokenPayload, VerifyRoomTokenOptions, } from "./token.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpE,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,QAAQ,EACR,UAAU,EACV,WAAW,EACX,cAAc,EACd,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5F,YAAY,EACV,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+// @rindle/room — the Rindle Realtime room (P0 read-only follower + P1 lease-gated
+// downstream + P2 shared optimistic writes).
+//
+// Four layers, deliberately separable:
+// - `initRoomWasm` / `WasmRoom` (src/wasm.ts): the wasm room core — rindle-room-wasm
+//   compiled to `pkg/`, host-neutral (the Durable Object shell runs the SAME artifact).
+// - `mintRoomToken` / `verifyRoomToken` (src/token.ts): the §10.1 self-authorizing
+//   signed lease token — minted by the API server (the authority), verified by any
+//   shell via WebCrypto (Node and Workers alike).
+// - `MutationTx` / `RoomJournal` (src/mutation-tx.ts, src/journal.ts): the §5.1 write
+//   plane's two seams — the §4.2 mutator interface (a shared app registry drops in
+//   verbatim) and the pluggable durable sidecar an ack means (§8.1).
+// - `createRoomShell` (src/shell.ts): the Node test shell — upstream ws subscriber of a
+//   live rindled, downstream ws server speaking the `@rindle/remote` protocol verbatim,
+//   gated by the tokens, with lease-TTL enforcement, the `/revoke` control plane, and
+//   the journaled write path.
+export { initRoomWasm, WasmRoom } from "./wasm.js";
+export { createRoomShell } from "./shell.js";
+export { journalEntryOutcome, memoryJournal } from "./journal.js";
+export { fatalAuthorityError, httpAuthority } from "./authority.js";
+export { mintRoomToken, verifyRoomToken, RoomTokenError, scopeSpecsHash } from "./token.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,6CAA6C;AAC7C,EAAE;AACF,uCAAuC;AACvC,qFAAqF;AACrF,wFAAwF;AACxF,mFAAmF;AACnF,mFAAmF;AACnF,kDAAkD;AAClD,sFAAsF;AACtF,mFAAmF;AACnF,qEAAqE;AACrE,wFAAwF;AACxF,wFAAwF;AACxF,sFAAsF;AACtF,8BAA8B;AAE9B,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAS7C,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElE,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAcpE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/journal.d.ts

@@ -0,0 +1,64 @@
+/** One journaled mutation: the wire envelope plus its recorded outcome. Replay applies
+ *  the OUTCOME — a non-applied (`rejected`/`deopt`) entry consumes its mid without
+ *  running the mutator. */
+export interface RoomJournalEntry {
+    clientID: string;
+    mid: number;
+    name: string;
+    args: unknown;
+    /** The connection's authenticated subject at push time (the lease token's `sub`,
+     *  shell-stamped — managed-writes §3.3): recovery is re-invocation, so identity is
+     *  an input that must survive the crash. `""` = an entry journaled before the
+     *  identity plane existed (mutators see it as unauthenticated). */
+    sub: string;
+    /** The recorded verdict (H-iv-b): `"applied"` replays by RE-INVOKING the mutator
+     *  (§3.3 — and against a moved base the re-invocation may legitimately reject or
+     *  DEOPT; the journal record is never rewritten, the shell's recorded-outcome map
+     *  reflects what the replaying incarnation produced); `"rejected"` (final — authz /
+     *  validation / unknown mutator) and `"deopt"` (the §3.3 commit gate refused; the
+     *  client was told to re-route the mutation) both replay as a consumed-mid-no-effect
+     *  WITHOUT running anything — re-judging a deopt could invent effects the client
+     *  already re-routed elsewhere. Absent = a legacy pre-H-iv-b entry: read through
+     *  {@link journalEntryOutcome}. */
+    outcome?: "applied" | "rejected" | "deopt";
+    /** Legacy pre-H-iv-b flag, superseded by {@link outcome} but still WRITTEN (`true`)
+     *  alongside BOTH non-applied outcomes: a legacy reader replays either kind as a
+     *  consumed-mid-no-effect, which is exactly right. */
+    rejected?: boolean;
+}
+/** The ONE reading rule for an entry's verdict across journal generations: `outcome`
+ *  when present, else the legacy `rejected` flag, else applied. */
+export declare function journalEntryOutcome(entry: RoomJournalEntry): "applied" | "rejected" | "deopt";
+/** One journaled flush batch: the room's flush-stream position, the placement epoch it
+ *  was built under, and the EXACT `/apply-row-change-txn` body string — resubmitted
+ *  verbatim, never rebuilt (§5.3 step 4). */
+export interface RoomFlushRecord {
+    seq: number;
+    epoch: number;
+    body: string;
+}
+export interface RoomJournal {
+    /** Append `entries` durably, in order. Resolving is the ack gate (§8.1): the shell
+     *  advances lmid rows only after this resolves. A rejection is fatal to the
+     *  incarnation — an ack that might not survive must never be sent. */
+    append(entries: RoomJournalEntry[]): Promise<void>;
+    /** Every entry ever appended, in append order — the boot-time replay source. */
+    replay(): Promise<RoomJournalEntry[]>;
+    /** Journal one built flush batch, BEFORE its first send. Same durability contract
+     *  as `append`: a rejection is fatal (an unjournaled batch must never reach the
+     *  wire — a retry could otherwise rebuild different bytes under the same id). */
+    appendFlush(record: RoomFlushRecord): Promise<void>;
+    /** The authority settled flush `seq` (committed, deduped, or dead) — drop it. */
+    confirmFlush(seq: number): Promise<void>;
+    /** Unconfirmed flush records in seq order, plus the highest seq ever appended
+     *  (0 = none) — the boot-time resubmission source and the seq seed. */
+    replayFlushes(): Promise<{
+        records: RoomFlushRecord[];
+        maxSeq: number;
+    }>;
+}
+/** An in-process journal: survives incarnations within one shell process (and, handed
+ *  to a second shell, a simulated process crash — the T2 harness). Not durable beyond
+ *  the process, by definition. */
+export declare function memoryJournal(): RoomJournal;
+//# sourceMappingURL=journal.d.ts.map

package/dist/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"AAkBA;;2BAE2B;AAC3B,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd;;;uEAGmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;uCAQmC;IACnC,OAAO,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;IAC3C;;0DAEsD;IACtD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;mEACmE;AACnE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAE7F;AAED;;6CAE6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B;;0EAEsE;IACtE,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,gFAAgF;IAChF,MAAM,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACtC;;qFAEiF;IACjF,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,iFAAiF;IACjF,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC;2EACuE;IACvE,aAAa,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,eAAe,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1E;AAED;;kCAEkC;AAClC,wBAAgB,aAAa,IAAI,WAAW,CA0B3C"}

package/dist/journal.js

@@ -0,0 +1,53 @@
+// The room's pluggable journal (RINDLE-REALTIME-DESIGN.md §2.2, §5.1, §8.1): the
+// durable sidecar an **ack** means. The shell appends mutation ENVELOPES under a group
+// commit and advances the author's lmid row only after `append` resolves — so `acked`
+// survives a room-process crash by construction, replayed by re-invoking the mutators
+// against the freshly re-subscribed base (§3.3; recovery is re-invocation, never effect
+// replay). Each host brings its own durability: the Durable Object shell backs this
+// with per-object transactional storage (P4); the Node test shell defaults to
+// `memoryJournal`, whose durability class is exactly "the shell process" — which is
+// what makes T2's crash matrix a plain test: hand ONE journal to a second shell and
+// the restart-with-journal failure class runs in-process.
+//
+// With P3's write-behind the journal ALSO holds the built flush batches (§5.3 step 4):
+// the exact body bytes are appended BEFORE the first send and dropped once the
+// authority confirms, so a crash-replay resubmits the same immutable body — one flush
+// id names one byte body forever (the §8.3/T6 identity property). Mutation entries
+// still grow without bound here; bounded retention (truncate ≤ the durable watermark)
+// is a host-journal concern (P4's storage journal).
+/** The ONE reading rule for an entry's verdict across journal generations: `outcome`
+ *  when present, else the legacy `rejected` flag, else applied. */
+export function journalEntryOutcome(entry) {
+    return entry.outcome ?? (entry.rejected === true ? "rejected" : "applied");
+}
+/** An in-process journal: survives incarnations within one shell process (and, handed
+ *  to a second shell, a simulated process crash — the T2 harness). Not durable beyond
+ *  the process, by definition. */
+export function memoryJournal() {
+    const log = [];
+    const flushes = new Map();
+    let maxSeq = 0;
+    return {
+        append(entries) {
+            log.push(...entries);
+            return Promise.resolve();
+        },
+        replay() {
+            return Promise.resolve([...log]);
+        },
+        appendFlush(record) {
+            flushes.set(record.seq, record);
+            maxSeq = Math.max(maxSeq, record.seq);
+            return Promise.resolve();
+        },
+        confirmFlush(seq) {
+            flushes.delete(seq);
+            return Promise.resolve();
+        },
+        replayFlushes() {
+            const records = [...flushes.values()].sort((a, b) => a.seq - b.seq);
+            return Promise.resolve({ records, maxSeq });
+        },
+    };
+}
+//# sourceMappingURL=journal.js.map

package/dist/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,uFAAuF;AACvF,sFAAsF;AACtF,sFAAsF;AACtF,wFAAwF;AACxF,oFAAoF;AACpF,8EAA8E;AAC9E,oFAAoF;AACpF,oFAAoF;AACpF,0DAA0D;AAC1D,EAAE;AACF,uFAAuF;AACvF,+EAA+E;AAC/E,sFAAsF;AACtF,mFAAmF;AACnF,sFAAsF;AACtF,oDAAoD;AA+BpD;mEACmE;AACnE,MAAM,UAAU,mBAAmB,CAAC,KAAuB;IACzD,OAAO,KAAK,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAC7E,CAAC;AA6BD;;kCAEkC;AAClC,MAAM,UAAU,aAAa;IAC3B,MAAM,GAAG,GAAuB,EAAE,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IACnD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,OAAO;QACL,MAAM,CAAC,OAAO;YACZ,GAAG,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;YACrB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,MAAM;YACJ,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;QACnC,CAAC;QACD,WAAW,CAAC,MAAM;YAChB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAChC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;YACtC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,YAAY,CAAC,GAAG;YACd,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,aAAa;YACX,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YACpE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QAC9C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/mutation-tx.d.ts

@@ -0,0 +1,79 @@
+import type { WasmRoom } from "./wasm.ts";
+/** A bare wire cell (the client stack's `WireValue`). */
+export type WireValue = number | string | boolean | null;
+/** A row keyed by column name. */
+export type KeyedRow = Record<string, WireValue>;
+/** The §4.2 write handle. Keyed methods are schema-checked; positional methods are the
+ *  raw wire shape (cells in schema column order, pk cells in `primaryKey` order).
+ *  `query` is not available in room mutators yet (it throws) — typed so a client
+ *  registry that uses it still registers, and fails loudly at run time. */
+export interface MutationTx {
+    /** Read one row by primary key (e.g. `tx.row("issue", { id: 1 })`). */
+    row(table: string, pk: KeyedRow): KeyedRow | undefined;
+    /** Insert a FULL row (every column named; missing or unknown columns throw). */
+    insert(table: string, row: KeyedRow): void;
+    /** Update the row identified by the pk columns; only the named non-pk columns
+     *  change. A missing row is a NO-OP (rebase-friendly). */
+    update(table: string, row: KeyedRow): void;
+    /** Insert, or fully replace when the pk already exists (a FULL row, like insert). */
+    upsert(table: string, row: KeyedRow): void;
+    /** Delete the row identified by the pk columns. A missing row is a NO-OP. */
+    delete(table: string, pk: KeyedRow): void;
+    /** NOT SUPPORTED in room mutators yet — throws. (Typed to accept the client
+     *  builder's queries so shared registries typecheck.) */
+    query(query: {
+        ast(): unknown;
+    }): never;
+    get(table: string, pk: WireValue[]): WireValue[] | undefined;
+    add(table: string, row: WireValue[]): void;
+    remove(table: string, row: WireValue[]): void;
+    edit(table: string, oldRow: WireValue[], newRow: (WireValue | undefined)[]): void;
+}
+/** The ambient authorization context a room mutator runs under (managed-writes design
+ *  §3.2). Shell-stamped from the connection's DO-verified lease token — NEVER
+ *  client-supplied — so per-row/per-field rules checked against it are trustworthy.
+ *  The shape deliberately matches the shared-generator drivers' `ctx.user`, so one
+ *  registry body runs identically in all three homes (client / api-server / room). */
+export interface RoomMutatorCtx {
+    /** The authenticated subject (the lease token's `sub`). `""` on replay of an entry
+     *  journaled before the identity plane — treat as unauthenticated. */
+    user: string;
+}
+/** A room mutator: deterministic, replayable — re-invoked on journal replay against
+ *  the freshly re-subscribed base (§3.3), so the same purity rules as a client
+ *  mutator apply (no clock, no randomness, a pure function of `(base, args, ctx)`).
+ *  An auth check against `ctx` re-runs on replay against the freshly rebuilt base —
+ *  a mutation that passed before a crash can replay as rejected if the permission
+ *  row changed in between; that is §3.3's intended rebase behavior. */
+export type RoomMutator = (tx: MutationTx, args: never, ctx: RoomMutatorCtx) => void;
+/**
+ * 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 declare function environmentShortfall(message: string): Error;
+/** Whether `e` was tagged by {@link environmentShortfall}. */
+export declare function isEnvironmentShortfall(e: unknown): boolean;
+/**
+ * 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 declare function assertSyncMutatorReturn(returned: unknown, name: string): void;
+/** One table's positional shape, parsed from the upstream hello. */
+export interface TableShape {
+    columns: string[];
+    /** Indices into `columns`. */
+    primaryKey: number[];
+}
+/** 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 declare function mutationTx(room: WasmRoom, shapes: Map<string, TableShape>): MutationTx;
+//# sourceMappingURL=mutation-tx.d.ts.map

package/dist/mutation-tx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-tx.d.ts","sourceRoot":"","sources":["../src/mutation-tx.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,yDAAyD;AACzD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AACzD,kCAAkC;AAClC,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAEjD;;;2EAG2E;AAC3E,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACvD,gFAAgF;IAChF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3C;8DAC0D;IAC1D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3C,qFAAqF;IACrF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3C,6EAA6E;IAC7E,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1C;6DACyD;IACzD,KAAK,CAAC,KAAK,EAAE;QAAE,GAAG,IAAI,OAAO,CAAA;KAAE,GAAG,KAAK,CAAC;IAExC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,GAAG,SAAS,CAAC;IAC7D,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC3C,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC9C,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,CAAC,SAAS,GAAG,SAAS,CAAC,EAAE,GAAG,IAAI,CAAC;CACnF;AAED;;;;sFAIsF;AACtF,MAAM,WAAW,cAAc;IAC7B;0EACsE;IACtE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;uEAKuE;AACvE,MAAM,MAAM,WAAW,GAAG,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;AAErF;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAI3D;AAED,8DAA8D;AAC9D,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAI1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAgB7E;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,8BAA8B;IAC9B,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AA4BD;qFACqF;AACrF,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,UAAU,CA2HtF"}