API index and search · Build metadata

Source snapshot

packages/room/pkg/rindle_room.d.ts

1/* tslint:disable */2/* eslint-disable */34/**5 * One room instance: the upstream-fed base store plus its downstream serving state6 * (materialized queries deduped by `QueryKey`, subscribers addressed by the host's7 * opaque keys) and — once [`enableWrites`](Self::enable_writes) runs — the §5.18 * write plane, with **at most one mutation transaction open at a time** (the room is9 * an actor; the host serializes mutations onto it).10 */11export class WasmRoom {12    private constructor();13    free(): void;14    [Symbol.dispose](): void;15    /**16     * Advance the ledger rows for journal-committed mutations — **the ack** (§5.117     * step 4; call once the journal append resolves). `entries_json` is a JSON array18     * of `{clientID, mid}`. Returns `{"headCv": n}` — drain19     * [`commitAll`](Self::commit_all) to ship the lmid frames — or `{"headCv": null}`20     * when everything was already covered.21     */22    ack(entries_json: string): string;23    /**24     * The ledger row's current value for `clientID` (0 if none) — what the wire has25     * confirmed.26     */27    ackedLmid(client_id: string): number;28    /**29     * The highest mid applied to the head for `clientID` (0 if none) — the dedup30     * watermark; diagnostics and the crash-replay tests read it.31     */32    appliedMid(client_id: string): number;33    /**34     * Apply one upstream `nbatch` frame's `batch` object (JSON text). Returns a status35     * object (JSON text): `{applied: "snapshot", rows}` | `{applied: "live", ops}` |36     * `{applied: "duplicate"}` | `{applied: "staleEpoch", expected, got}`. Throws when37     * the frame is garbage or the apply poisons the store — in both cases the host38     * tears down and re-subscribes under a new epoch (§3.4); there is no repair call.39     *40     * After a `live`/`snapshot` apply, drain the fan-out with41     * [`commitAll`](Self::commit_all).42     */43    apply(batch_json: string): string;44    /**45     * Build the §5.3 net-effect batch from the dirty entries + ledger co-edits.46     * Returns `undefined` when there is nothing to flush, else JSON text47     * `{changes, batchHash, lmids}`: `changes` is the `/apply-row-change-txn`48     * `changes[]` array (ingest shape, old-images = the CAS base chain), `batchHash`49     * the batch identity computed over its canonical bytes, `lmids` the50     * `{clientID, mid}` advances the batch covers. At most one flush may be in51     * flight — resolve with [`flushOk`](Self::flush_ok) or52     * [`flushConflict`](Self::flush_conflict); retries resubmit the SAME journaled53     * body, never a rebuilt one.54     */55    beginFlush(): string | undefined;56    /**57     * Open the transaction for `(clientID, mid)`. Returns `{"begin": "tx"}` (run the58     * mutator, then [`commitMutation`](Self::commit_mutation) or59     * [`rejectMutation`](Self::reject_mutation)) or `{"begin": "dedup"}` (an absorbed60     * redelivery — send nothing). Throws on a mid gap with the exact61     * `mutation gap for …` message the client's recovery keys on — forward it on an62     * `error` frame. At most one transaction may be open.63     *64     * `name`/`args_json` (optional, Slice I-ii) are the wire envelope's mutator name65     * and JSON-text args: should this mid end non-applied, its durable outcome row66     * echoes them on a DEOPT (self-contained re-invoke, mirroring the H-iv-b frame).67     * Omitting them degrades deopt rows to NULL name/args, nothing else.68     */69    beginMutation(client_id: string, mid: number, name?: string | null, args_json?: string | null): string;70    /**71     * Drain every materialized query once and return the fan-out as JSON text:72     * `[{sub, batch}, …]` — one entry per attached subscriber per query with a73     * non-empty net delta, each `batch` stamped with that subscriber's own epoch/seq.74     * Empty array when nothing changed (or the store is no longer live — a dead75     * incarnation must not ship a torn frame).76     */77    commitAll(): string;78    /**79     * Apply the open transaction to the head as one local commit: dirty entries are80     * captured, the applied watermark advances, and every attached query sees the ops.81     * Returns `{"headCv": n}` — drain [`commitAll`](Self::commit_all) and fan out NOW82     * (§5.1 step 2: data fanout is never gated on durability), then journal the83     * envelope and [`ack`](Self::ack) once the append commits. Throws only when the84     * commit tears the head (store poisoned — tear down).85     *86     * Under [`enableWritesV2`](Self::enable_writes_v2) the §3.3 commit gate runs87     * first; a containment violation returns `{"deopt": {reason, table, pk, …}}`88     * instead (`reason`: `"writeOutOfScope"` (+ `op`) | `"joinKeyChanged"`89     * (+ `column`) | `"absentReadUnproven"`): **nothing was applied**, the tx is90     * consumed and the mid burnt exactly like [`rejectMutation`](Self::reject_mutation)91     * (do NOT call it too) — journal the envelope as rejected and [`ack`](Self::ack)92     * as usual, answering the client with a deopt. Under the v1 enable the return is93     * always `{"headCv": n}`, byte-identical to before.94     */95    commitMutation(): string;96    /**97     * The last-applied upstream commit version (`undefined` before the seq-0 snapshot).98     * This is the journal cursor's `cv` half — persist `(epoch, cv)` to resume (§3.3).99     */100    cv(): number | undefined;101    /**102     * How many `(table, pk)` keys are dirty (§5.3 — P3's flush input).103     */104    dirtyLen(): number;105    /**106     * The highest mid the write authority has committed for `clientID` (0 if none) —107     * §8.1's `durable` level.108     */109    durableLmid(client_id: string): number;110    /**111     * Enable the §5.1 write plane over a live store: `owned_json` is a JSON array of112     * the tables mutators may write (§3.2's owned set — must all be in the upstream113     * hello). Registers the `_rindle_client_mutations` ledger; call once, right after114     * the seq-0 snapshot applies and before serving. Idempotence is deliberate-ly NOT115     * provided: enabling twice is a shell bug and throws.116     */117    enableWrites(owned_json: string): void;118    /**119     * Enable the write plane with per-table **scope specs** — the §3.3 room commit120     * gate (H-iv-a). `specs_json` is a JSON array of121     * `{ table, footprintWhere?, writable }` where `writable` is the lease block's122     * `RoomTableSpec.writable` shape (`{kind:"none"}` for a context table,123     * `{kind:"predicate", where?, joinKeyCols}` for a writable one) and124     * `footprintWhere` is the footprint's row-local wire `Condition` for the table125     * (drives the absent-read proof). Predicates compile NOW, loudly — a malformed or126     * non-row-local spec (e.g. a `correlatedSubquery`) throws and nothing is enabled.127     * With the gate armed, [`commitMutation`](Self::commit_mutation) can return a128     * `{"deopt": …}` verdict. Same once-only/live-store rules as129     * [`enableWrites`](Self::enable_writes), which remains the legacy table-granular130     * entry (its gate proves nothing and never deopts).131     */132    enableWritesV2(specs_json: string): void;133    /**134     * The upstream subscription epoch this store was opened under.135     */136    epoch(): number;137    /**138     * The authority rejected the in-flight batch on CAS (§5.4 `flush_conflict`):139     * `conflicts_json` is its `409` body's `conflicts` array —140     * `[{table, pk, current}]`, `current: null` for an absent row. Each conflicted141     * key converges to the authority's image (the local net effect is dropped);142     * everything else stays dirty and retries next flush. Returns143     * `{"headCv": n | null}` — drain [`commitAll`](Self::commit_all) after a144     * non-null cv to ship the corrective frames.145     */146    flushConflict(conflicts_json: string): string;147    /**148     * Whether a §5.3 flush is in flight (diagnostics; the shell also guards).149     */150    flushInFlight(): boolean;151    /**152     * The authority committed the in-flight batch (§5.3 step 6): consumed entries153     * retire (or re-base onto the image just written, if re-dirtied mid-flight),154     * durable watermarks advance, `pending ≤` them retires. Returns155     * `{"retired": n, "dirty": n}` — a non-zero `dirty` means writes landed during156     * the flight; schedule the next flush.157     */158    flushOk(): string;159    /**160     * The room's own commit order — what downstream frames are stamped with and what161     * the shell's `progress {cvMin}` release points are computed from. Advances on162     * every upstream apply and every local commit (see `RoomStore::head_cv`).163     */164    headCv(): number;165    /**166     * Baseline present and not poisoned — the store is serving.167     */168    isLive(): boolean;169    /**170     * A failed apply left this incarnation dead (§3.4): tear down, re-subscribe.171     */172    isPoisoned(): boolean;173    /**174     * Subscribe `sub` to the reserved per-client lmid query (`_rindle/clientLmid`):175     * the room composes the `_rindle_client_mutations WHERE client_id = <clientID>`176     * AST itself — identity comes from the connection's `init`, never client args.177     * Same return shape and envelope rules as [`subscribe`](Self::subscribe).178     */179    lmidSubscribe(sub: string, epoch: number, client_id: string, now_ms: number): string;180    /**181     * How many downstream queries are currently materialized (post-dedup).182     */183    materializationCount(): number;184    /**185     * Open the room's base store from the upstream `nhello` frame's `hello` object186     * (JSON text). `idle_ttl_ms` is the downstream retention grace: a materialized187     * query with no subscribers for that long is reclaimed by [`sweep`](Self::sweep).188     * Rejects malformed hellos loudly — nothing is constructed.189     */190    static open(hello_json: string, idle_ttl_ms: number): WasmRoom;191    /**192     * Applied-but-not-retired mutations (everything, until P3's write-behind).193     */194    pendingLen(): number;195    /**196     * Drop the open transaction's staged ops and consume its mid anyway — the reject197     * path (unknown mutator, mutator threw, staging refusal, a replayed non-applied198     * journal entry). The stream stays contiguous; the eventual [`ack`](Self::ack)199     * advances the ledger with no effects, snapping the author's prediction back.200     *201     * `kind` (`"rejected"` (default) | `"deopt"`) + `reason` are the shell's H-iv-b202     * classification of the verdict: the outcome is RECORDED (Slice I-ii) and its203     * durable row rides the next flush beside the covering lmid co-edit — one204     * authority transaction, so a post-downgrade client resolving through the daemon205     * never reads a burnt non-applied mid as applied. A deopt row echoes the206     * [`beginMutation`](Self::begin_mutation) envelope's `name`/`args`.207     */208    rejectMutation(kind?: string | null, reason?: string | null): void;209    /**210     * Seed the durable watermarks from the write authority's ledger — the boot probe211     * (§3.3; T2's committed-before-crash row). Call after [`enableWrites`] and212     * **before** the journal replay: seeded mids replay as dedup instead of213     * re-invoking. `seeds_json` is a JSON array of `{clientID, lmid}`. Returns214     * `{"headCv": n | null}` — the ledger rows ride a local commit so the client's215     * lmid slice confirms them.216     *217     * [`enableWrites`]: Self::enable_writes218     */219    seedDurable(seeds_json: string): string;220    /**221     * Materialize-on-presentation (§10.1): attach subscriber `sub` (the host's opaque222     * routing key) at `epoch` to the query for this approved wire `Ast` (JSON text) —223     * reusing the pipeline on a `QueryKey` hit. Returns224     * `{queryKey, reused, hello, snapshot}` (JSON text): send `nhello(hello)` then225     * `nbatch(snapshot)` (its `seq` is 0), then this subscriber's entries from each226     * [`commitAll`](Self::commit_all). Re-subscribing an existing `sub` replaces its227     * envelope — pass the bumped `epoch`, exactly as before.228     */229    subscribe(sub: string, epoch: number, ast_json: string, now_ms: number): string;230    /**231     * How many downstream subscribers are currently attached.232     */233    subscriberCount(): number;234    /**235     * Reclaim downstream queries idle past their grace window, on the host's clock.236     * Returns how many were destroyed.237     */238    sweep(now_ms: number): number;239    /**240     * Stage an add of a full-width row (JSON-array text). Clean refusal (throw, head241     * untouched) when the key exists, the table is not owned, or the width is wrong —242     * catch it and reject the mutation.243     */244    txAdd(table: string, row_json: string): void;245    /**246     * Stage an edit to a full-width row (JSON-array text) keyed by its pk cells. The247     * shell resolves partial updates against [`txGet`](Self::tx_get) first — only248     * concrete cells cross this boundary (JSON has no `undefined`). The pk must not249     * change; the row must exist.250     */251    txEdit(table: string, row_json: string): void;252    /**253     * The effective row for `pk_json` (a JSON array of pk cells, `primaryKey` order):254     * the live head under this transaction's own staged writes — read-your-writes for255     * read-dependent mutators, and what the keyed `update`/`delete`/`upsert` layers256     * probe before composing their writes. Returns the row as JSON-array text, or257     * `undefined` when absent.258     */259    txGet(table: string, pk_json: string): string | undefined;260    /**261     * Stage a remove of the row keyed `pk_json` (JSON array of pk cells). The change262     * is composed from the effective row; a missing key is a clean refusal (the keyed263     * `delete` layer no-ops before calling this).264     */265    txRemove(table: string, pk_json: string): void;266    /**267     * Detach subscriber `sub` (unsubscribe, socket close, lease expiry, revocation —268     * the host decides why). Idempotent: returns whether it was attached. Its query269     * stays materialized for `idle_ttl_ms` (a quick re-subscribe is cheap), then270     * [`sweep`](Self::sweep) reclaims it.271     */272    unsubscribe(sub: string, now_ms: number): boolean;273}274275export function __rindle_room_wasm_start(): void;276277export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;278279export interface InitOutput {280    readonly memory: WebAssembly.Memory;281    readonly __rindle_room_wasm_start: () => void;282    readonly __wbg_wasmroom_free: (a: number, b: number) => void;283    readonly wasmroom_ack: (a: number, b: number, c: number) => [number, number, number, number];284    readonly wasmroom_ackedLmid: (a: number, b: number, c: number) => number;285    readonly wasmroom_appliedMid: (a: number, b: number, c: number) => number;286    readonly wasmroom_apply: (a: number, b: number, c: number) => [number, number, number, number];287    readonly wasmroom_beginFlush: (a: number) => [number, number, number, number];288    readonly wasmroom_beginMutation: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number, number];289    readonly wasmroom_commitAll: (a: number) => [number, number];290    readonly wasmroom_commitMutation: (a: number) => [number, number, number, number];291    readonly wasmroom_cv: (a: number) => [number, number];292    readonly wasmroom_dirtyLen: (a: number) => number;293    readonly wasmroom_durableLmid: (a: number, b: number, c: number) => number;294    readonly wasmroom_enableWrites: (a: number, b: number, c: number) => [number, number];295    readonly wasmroom_enableWritesV2: (a: number, b: number, c: number) => [number, number];296    readonly wasmroom_epoch: (a: number) => number;297    readonly wasmroom_flushConflict: (a: number, b: number, c: number) => [number, number, number, number];298    readonly wasmroom_flushInFlight: (a: number) => number;299    readonly wasmroom_flushOk: (a: number) => [number, number, number, number];300    readonly wasmroom_headCv: (a: number) => number;301    readonly wasmroom_isLive: (a: number) => number;302    readonly wasmroom_isPoisoned: (a: number) => number;303    readonly wasmroom_lmidSubscribe: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number, number];304    readonly wasmroom_materializationCount: (a: number) => number;305    readonly wasmroom_open: (a: number, b: number, c: number) => [number, number, number];306    readonly wasmroom_pendingLen: (a: number) => number;307    readonly wasmroom_rejectMutation: (a: number, b: number, c: number, d: number, e: number) => [number, number];308    readonly wasmroom_seedDurable: (a: number, b: number, c: number) => [number, number, number, number];309    readonly wasmroom_subscribe: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number, number];310    readonly wasmroom_subscriberCount: (a: number) => number;311    readonly wasmroom_sweep: (a: number, b: number) => [number, number, number];312    readonly wasmroom_txAdd: (a: number, b: number, c: number, d: number, e: number) => [number, number];313    readonly wasmroom_txEdit: (a: number, b: number, c: number, d: number, e: number) => [number, number];314    readonly wasmroom_txGet: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];315    readonly wasmroom_txRemove: (a: number, b: number, c: number, d: number, e: number) => [number, number];316    readonly wasmroom_unsubscribe: (a: number, b: number, c: number, d: number) => [number, number, number];317    readonly __wbindgen_free: (a: number, b: number, c: number) => void;318    readonly __wbindgen_malloc: (a: number, b: number) => number;319    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;320    readonly __wbindgen_externrefs: WebAssembly.Table;321    readonly __externref_table_dealloc: (a: number) => void;322    readonly __wbindgen_start: () => void;323}324325export type SyncInitInput = BufferSource | WebAssembly.Module;326327/**328 * Instantiates the given `module`, which can either be bytes or329 * a precompiled `WebAssembly.Module`.330 *331 * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.332 *333 * @returns {InitOutput}334 */335export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;336337/**338 * If `module_or_path` is {RequestInfo} or {URL}, makes a request and339 * for everything else, calls `WebAssembly.instantiate` directly.340 *341 * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.342 *343 * @returns {Promise<InitOutput>}344 */345export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;346