@rindle/api-server

Request context supplied by the application after authentication. The HTTP adapter or trusted caller owns user; do not populate it from an unverified request body.

A server mutator: a plain async function against the live {@link ServerMutationTx}. Two ways to write one (MUTATORS-ISOMORPHIC): drive it directly (the raw escape hatch — an owner-gated cascade, a NOT EXISTS dedup — plus a returned SqlStatement[]/SqlTxn), OR delegate to a SHARED generator (the SAME body the client predicts) via {@link runSharedMutation}, keeping only the server-only authority (arg parse, principal, policy) in the wrapper.

The minimal arg validator a shared mutator can carry so the SERVER can parse UNTRUSTED wire args before driving it (the client trusts its typed callsites and never calls this). Structural on purpose — a zod schema satisfies it as-is — so @rindle/client stays validator-library-agnostic.

The durable half of the splice for the mapped-table layout: the compacted body followed by whatever chunk rows have not been folded into it yet.

Chunks are ALWAYS the suffix after body — the closing checkpoint rewrites body and drops the chunks it absorbed in ONE transaction — so a reader never observes a torn state where a chunk both is and is not in the body.

An optional request gate. Return false or throw to deny; true and undefined allow. This gate does not add row predicates or replace access checks inside a mutator.

Thrown (wrapping the driver error) by a server tx's DB calls, so the seam can tell an INFRA failure (retry) from a mutator-body throw (business rejection).

Build the {@link RenderIndex} from a typed schema (schema.tables[name] is a TableMeta).

Legacy/private-plane adapter. Kept for existing deployments; its mutation policy is shared with {@link sqlBackend}, so the two transports cannot drift.

Dump every registered named query's wire AST — feeder 1 ("exemplar enumeration") of rindle indices suggest (docs/INDEXING.md applied mechanically to the query set).

Because named queries are FUNCTIONS of (args, ctx), one query can build structurally different ASTs on different args; each exemplar invocation contributes its shape, and shapes that differ only in literal values (a limit, a filter string) dedupe to one entry. A query with no configured exemplars is invoked once with no args. The registry is the app's whole server-side query surface, so the resulting document is the complete static shape set — modulo arg-value-dependent branches, which need an exemplar (or runtime shape recording) to surface.

The resume point a frame implies — what rides an SSE id: line so a reconnecting EventSource hands it straight back as Last-Event-ID. undefined for frames that are not a position.

Wrap a SHARED (generator) mutator with a row-level ACCESS GUARD — the multi-tenant authz twin of {@link sharedApiMutators}. It parses the untrusted wire args, derives the {@link MutatorCtx} principal (the SAME mapping you pass to sharedApiMutators), evaluates predicate against the OPEN mutation txn (so it can READ the rows the write depends on), and throws forbidden (403 — the client's optimistic write snaps back) when access is denied; otherwise it drives the SAME body the client predicts ({@link runSharedMutation}). Use it for the entries that need server-only authority the client cannot predict, OVERRIDING the auto-wrapped default (spread sharedApiMutators(...) first, then the guarded overrides win by key):

const principal = (ctx) => ({ user: requireUser(ctx.user) });
mutators: defineApiMutators({
  ...sharedApiMutators(sharedMutators, principal),
  updateSlide: guardMutator(sharedMutators.updateSlide, principal,
    async (tx, a, { user }) =>
      (await tx.query(q.slide.where.id(a.slideId).where(editableBy(user)).one())) != null,
    { message: "not permitted to edit this slide" }),
}),

The predicate keeps the shared body READ-FREE, so the client's .folded hot paths (drag/keystroke) still fold — the read is server-side only. Return false to deny (→ the default or opts.message forbidden); return true/nothing to allow. To reject with a different status/message (a business rejection, a not-found), throw a {@link RindleApiError} from inside the predicate instead. principal runs before the predicate, so it too may throw forbidden for an anonymous caller.

The one shared effect factory (stateless — see {@link IsoTx}). Its methods just BUILD a {@link MutationOp}, so the single instance serves every schema; the generic {@link IsoTx} view is applied at the authoring site (a json<T> cell is a parsed object here and is stringified by the funnels, {@link toCell }), hence the cast — the runtime shape is schema-agnostic.

The tier-AGNOSTIC effect factory a generator mutator writes against. Every method just BUILDS an effect to yield — it performs no I/O and holds no state, so the single {@link isoTx} instance is shared by every mutator on both tiers; only the driver differs. insert/upsert/insertIgnore require non-nullable columns and permit nullable omissions, which become null. update/delete require the PK columns; update also names the columns to change.

Sign the default epoch-bound flush credential (/room-boot mints one per placement).

Where a mutation runs and who stamps lmid — the seam that makes the mutator authoring surface backend-agnostic (BYO-POSTGRES-LMID-CONTRACT-DESIGN.md §6; MUTATORS-ISOMORPHIC plan). Three implementations ship: {@link sqlBackend} is the preferred managed-SQL path; {@link daemonBackend} keeps the private control-plane compatibility path; and {@link postgresBackend} runs a real interactive PG transaction with confirmation riding the CDC loop down.

The load-bearing invariant is that a mutation ALWAYS advances the client's last_mutation_id:

• runMutation runs the mutator inside the backend's transaction; on success it advances lmid to envelope.mid in the SAME atomic unit (OPTIMISTIC-WRITES-DESIGN.md §8.2); on a BUSINESS rejection it rolls the data back but STILL advances lmid (§2.4 — else the client's pending queue never drains and the optimistic stack wedges).
• reject is the pre-flight path (unknown mutator, failed authorization): NO data, lmid alone.
• An infrastructure failure THROWS from runMutation — never a user rejection (the client retries; mid dedup absorbs any applied prefix).

What a generator mutator IS: yield tx.<op>() on every side effect; a yield tx.row() expression evaluates to the row. Neither sync nor async — the tier's driver decides, which is what lets one body run synchronously on the client and against a live async transaction on the server.

The result of {@link MutationBackend.runMutation}: either the data+lmid committed together, or a business rejection whose data was rolled back but whose lmid still advanced (§2.4).

Thrown by {@link MutationScope.transact} when the transacted body BUSINESS-rejects: the data rolled back and lmid advanced alone (§2.4). Catch it to COMPENSATE an outside-tx side effect (refund the charge), then rethrow or return — the mutation's protocol outcome is already sealed as rejected, so a post-reject throw can't change it. A DB/infra failure is NOT this — it propagates as the raw driver error (the client retries; lmid did not advance).

The context a {@link MutationBackend} needs to run one mutation inside its transaction.

The per-mutation server handle a {@link ScopedMutator} runs against. Code before {@link transact} runs OUTSIDE the transaction; code after a clean transact runs AFTER the commit. The lmid-always-advances invariant is the HARNESS's, not the author's: {@link RindleApiServer.pushMutation} seals the response from this handle's recorded outcome, so an early return, a never-called transact, or a swallowed {@link MutationRejected} still advances lmid and never wedges the client's pending queue.

The minimal per-invocation context a shared mutator sees on BOTH tiers: the acting principal. The server injects its AUTHENTICATED user; the client injects its local user. (The server's own MutationContext is a superset of this.)

The slice of a node-postgres Pool the plugger needs — structural, so pg stays a dependency of the APP, never of this package.

Adapt a node-postgres Pool (or anything pool-shaped) to a {@link PostgresPlugger}: one client per transaction, BEGIN/COMMIT bracketing, ROLLBACK + rethrow on failure.

The query surface a {@link PostgresPlugger} transaction exposes. exec runs one statement; query returns rows keyed by column name (read-your-own-writes inside the txn).

The explicit fleet pin fan-out seam (READ-ROUTER-DESIGN.md §4.2). The api-server resolves each pin's authoritative AST under pinUser and hands the ready {@link MaterializeInput}s here; the implementation (the read router) fans EACH across all live followers. Distinct, on purpose, from a per-viewer materialize (which routes ONE) — a pin-assert always sprays ALL.

A named query to keep permanently materialized (warm with zero subscribers).

The BYO-Postgres {@link MutationBackend} (BYO-POSTGRES-LMID-CONTRACT-DESIGN.md §6.3): one PG transaction runs the mutator's statements and ALWAYS upserts _rindle_client_mutations — the upsert sits outside any acceptance guard by construction, so the §2.4 footgun (a rejection that forgets to advance lmid and wedges the client's pending queue) cannot be written.

Confirmation does NOT come from this call's response: the lmid row rides the same PG commit through CDC → relay → follower and reaches the client in the same coherent release as the data (§8.2 relocated upstream). A rejection's reason still returns on the HTTP reply, but nothing rejection-shaped travels the replication path — the optimistic prediction snaps back when the advanced lmid arrives.

The thin driver adapter that keeps pg / postgres.js out of this package's dependencies (BYO-POSTGRES-LMID-CONTRACT-DESIGN.md §6.2): run fn inside ONE transaction — commit on resolve, roll back on throw. {@link pgPoolPlugger} adapts a node-postgres Pool.

The §4 lifecycle block on a query lease (Slice I-iii): present only when BOTH the realtime lifecycle config is on AND the query is realtime-labeled. doorbell rides EVERY labeled lease (occupancy is counted whether or not the query is room-served — the 1→2 upgrade trigger needs solo watchers subscribed BEFORE any room exists, §4.1); fence rides only a ROOM-SERVED lease (the §4.2/§7.1/§3.3 downgrade surfaces are meaningful only where a room domain exists). The §4.2 fence VALUE (finalFlushSeq) is deliberately NOT here — it arrives with the I-v downgrade response; I-iii only stands up the streams.

One minted SYSTEM-STREAM lease on a query lease's lifecycle block (RINDLE-REALTIME-QUERY- ENABLEMENT §4, Slice I-iii): an ordinary daemon materialization over one of the four _rindle_* lifecycle system tables (registered by the daemon's enable_realtime_lifecycle — rust/rindle-replica/src/mutations.rs), attachable by the EXISTING client subscribe path (present leaseToken on a subscribe frame, exactly like the primary lease). The identity fields (scope/doc/clientId) document the minted AST's predicate — the client keys its retains and its release-time row filters on them.

The room-serve block on a query lease (RINDLE-REALTIME-QUERY-ENABLEMENT §2.1 step 5 / §2.4, slice G-iv-b): present when the named query carries a realtime label naming a configured room profile (302 §5 — declared, not derived; no coverage proof). The G-v client uses it to open the room transport for THIS query beside — never instead of — its daemon session.

It is a dedicated block on purpose: the ROOM ws is a SEPARATE connection this query opens beside its daemon session (never a migration of the daemon session — the daemon ws host is fixed and placed by the affinity ticket). A room-served lease's top-level fields are byte-identical to the daemon-served ones.

The §4.2 downgrade fence on a query lease (Slice I-v): rides a labeled reply whose §4.1 occupancy gate CLOSED (so there is NO realtime block) when the server could drain the room. A SIBLING of realtime, never nested inside it — block-ABSENCE is the downgrade signal, and the fence rides alongside that absence. Its finalFlushSeq is the room's last COMMITTED flush seq; the client's frozen room ghost holds visible until the daemon plane has provably absorbed it (_rindle_room_watermark(doc) ≥ finalFlushSeq). Absent from every non-downgrade reply.

A one-shot SSR read of a named query (SSR-DESIGN.md §6): same (name, args) surface as a lease, but the daemon serializes the current view ONCE and registers no subscriber.

The assembled (nested-by-name) first-paint snapshot the server-side Store seeds + dehydrates (SSR-DESIGN.md §3.3). rows hydrate without an engine; cvMin is their watermark baseline.

The realtime label a registered query carries (stamped by registerQueries from its defineQuery options), or undefined for an unlabeled query. The lease path uses this to derive (room profile, args mapping) for a named query.

The query-shapes document rindle indices suggest consumes: the app's synced tables (name + primary key) and one wire AST per structurally distinct shape a registered query can build.

Rewrite SQLite-style ? positional placeholders to Postgres $1..$n, for mutators written once and run against either backend (pass as {@link PostgresBackendOptions.rewriteSql}). Skips '…' string literals (with '' escapes), "…" quoted identifiers, -- line comments, and non-nested C-style block comments. Do not mix ? and $n styles in one statement.

The realtime LABEL a named query may declare (RINDLE-REALTIME-QUERY-ENABLEMENT-DESIGN.md §2.1): which api-server room PROFILE the query wants to be served from, and how the query's args map to that profile's key args. This is the DECLARATION only — the serve decision (covering proof, lease routing) is the server's, and the final room key is minted server-side by the profile's own key under authoritative ctx, so a label can never place a query in a room the server didn't derive itself. Both tiers import the SAME defineQuery value, so they always agree which profile a query belongs to.

Register a list of co-located client {@link NamedQuerydefineQuery} values as the server's query surface — the bulk, no-boilerplate counterpart to {@link defineApiQueries}. Each query already carries its wire name and a resolve that re-runs its validator on the UNTRUSTED wire args and builds the authoritative Query, so the server just imports every co-located query and hands the list here. The same validated args build a byte-identical AST on both tiers.

The query's AUTHORITATIVE {@link ApiContext} is forwarded as resolve's ctx — so a context-scoped defineQuery (e.g. "my issues") is built from the server's trusted principal, never the client's. A context-free query simply ignores the extra argument.

Use {@link defineApiQueries} instead (or in addition) only when the server must DIVERGE from the client — define a server-specific defineQuery with the same name and register that.

queries: registerQueries<User>([issuesPageQuery, issueDetailQuery, recentCommentsQuery, usersQuery]),

Render one {@link MutationOp} to a {sql, params} for the dialect, or null for a no-op (an update whose row names only pk columns — nothing to SET, matching the client's no-op edit).

Render a point read (tx.row) — SELECT <cols> FROM "T" WHERE <pk> — for read-your-writes.

The unified fleet connection — one URL, one key. A Rindle is BOTH layers at once: the SQL database below and the sync/IVM control plane above, served by a single ingress that routes each request to the right tier. This option derives both from that one origin: the SQL layer ({@link RindleApiServerOptions.database}) at url with token, and the control-plane client ({@link RindleApiServerOptions.daemon}) at the same url — so an application configures "a rindle", not two subsystems.

The derived control-plane client sends the same bearer. A unified ingress is an explicitly merged customer API-server trust tier: it routes SQL to the master and control requests to a follower, while the browser still receives neither credential. Deployments that keep those trust tiers separate pass an explicit {@link RindleApiServerOptions.daemon}; explicit fields always win over this derivation.

Database connection used by the API server's managed SQL path.

intMode defaults to "number" because logical Rindle rows use the JSON-safe {@link WireValue} vocabulary — "bigint" does not survive JSON.stringify, and "string" silently retypes every integer, breaking arithmetic in mutator bodies. The cost is a HARD BOUND: a mutator read of an integer outside ±(2^53 − 1) rejects that mutation rather than silently rounding it. Tables with keys beyond that range (snowflake ids, and so on) must override intMode and have their mutators handle the resulting type. Commit receipts are unaffected — they never decode row values.

{@link RindleRealtimeOptions.lifecycle}. PRESENCE of the block is the opt-in switch (I-iii); the fields below are the Slice I-iv occupancy knobs (§4.1, decisions D4/D6/D7). All optional — lifecycle: {} gets the designed defaults.

The room-boot flush leg (enablement §5): where the placed room's write-behind lands and what credential it presents. urls are the trio's ROUTE PATHS (root-relative — the shell resolves them against the boot call's origin), so an app that overrides routes needs no out-of-band sync; headers ride every flush call verbatim (httpAuthority's headers).

The /room-boot response (RINDLE-REALTIME-DESIGN.md §10.1 — the DO shell's cold-boot callback): the claimed placement epoch, the room's upstream footprint lease, and the flush leg. A cold room boots inert and serves nothing until this returns.

A room-host reply the transport writes VERBATIM (status + JSON body): the daemon's fence/conflict/identity semantics ride specific statuses and body shapes the room's httpAuthority decodes, so this endpoint trio can't run through the throw-on-error result shapes the viewer endpoints use.

One NAMED room profile (§2.1). Rooms are document-scoped, not query-scoped: a profile is what stands up and feeds a room — the flat resolveFootprint promoted to a named, reusable unit. Labeled queries opt into a profile; the wire room key for a named profile is minted SERVER-side as "<profile>/<key>", and /room-boot splits it back to resolve the footprint.

One footprint table's FULL scope spec (slice H-iv-b): byte-compatible with rindle-room-core's TableScopeSpec (scope.rs), the wasm room's enableWritesV2 input. It rides the boot wire (RoomBootResponse.scopes); since slice H-iii the LEASE wire's {@link RoomTableSpec} carries footprintWhere too (the client-side routing proof), so the two shapes are now structurally IDENTICAL — kept as two names because they are two wires with two consumers (the room gate vs the client router).

footprintWhere is computed for EVERY footprint table — context (kind: "none") ones included, because the gate proves ABSENT READS on any readable table with it (§3.1: an absent read is covered only when the footprint predicate is decidable from the pk columns alone and evaluates true on the read key). ABSENT (no exact membership predicate exists) ⇒ no absent read on that table is provable — the room gate fails closed to a deopt.

footprintWhere is EXACT-only — the opposite discipline from the writable where. The writable side ships the WIDENING extraction ({@link tablePredicate}) and that is sound (the held-row set is the real outer bound). The absent-read proof points the other way: it uses footprintWhere to conclude "a row with this pk would have been IN the footprint, so the room's absence is truth's absence" — a WIDENED predicate over-claims exactly there (a root where mixing pk-column conjuncts with a dropped EXISTS, or a correlated child whose own where reads only its pk, would prove an absence the dropped part can contradict). So footprintWhere is emitted ONLY when the membership predicate is exact ({@link exactMembershipPredicate}): every node reading the table is the footprint ROOT (a child node's implicit correlation to its parent is itself a dropped, non-row-local constraint) and the root's where extraction dropped nothing. An unconstrained exact root (the whole table rides the footprint) emits the vacuous-true {type:"and",conditions:[]} — the gate's combinator pins empty-AND = true — so whole-table footprints keep provable absent reads. Child/correlated tables get NO footprintWhere and their absent reads deopt (fail closed); propagating a parent constraint through a pk-covering correlation is a future refinement.

One footprint table's spec on the lease wire (QueryLeaseResponse.realtime.tables): the §2.2 owned/followed split plus §3.2's per-table routing metadata, compiled from the RESOLVED footprint AST at lease time (so key-dependent and non-static profiles compile too).

writable:

• none — a context table (§2.2 "followed"): loaded by the room, never room-written; the daemon stays write-authoritative.
• predicate — a writable table. where is the ROW-LOCAL part of the footprint's predicate for this table (simple column-vs-literal conditions composed with and/or); an ABSENT where means no row-local constraint — every row the room holds for this table is in the writable scope. joinKeyCols are the correlation columns the footprint binds on this table (slice H's "room mutators never write join keys" enforcement input).

Dropping the non-row-local parts (correlated/EXISTS conditions, column-vs-column comparisons) only ever WIDENS the predicate, which is sound here: the room only relays rows the footprint materialized, so the held-row set — not this predicate — is the real outer bound; where is a row-local refinement of it, and a wider refinement can never mark a held footprint row non-writable that the full predicate would have allowed. (An OR with any non-row-local disjunct is dropped WHOLE — keeping only some disjuncts would narrow, which is not sound.)

footprintWhere (H-iii — the lease-wire flip): the EXACT footprint-membership predicate, identical to {@link RoomScopeSpec.footprintWhere} (ONE compiler feeds both wires — the lease's table specs and the boot wire's scopes are now the SAME objects). The client's §3 router consumes it for the pk-membership read proof; it is advisory routing metadata, never a credential (the room gate re-proves engine-side, H-iv).

Run a SHARED generator mutator (the SAME body the client predicts) against a live server transaction (MUTATORS-ISOMORPHIC): bind the tier-agnostic {@link isoTx} factory and drive it — each yielded logical op renders + runs against tx (dialect SQL, per backend), each tx.row suspends for read-your-writes, and tx.all fans out. A server mutator uses this to delegate its write body after parsing untrusted args and applying its server-only authority (principal, policy). A mutator-body throw remains a business rejection; a DB failure propagates as infra.

Mark a mutator as SCOPED so the api-server gives it a {@link MutationScope} (author-controlled tx boundary via scope.transact) rather than running its whole body inside the transaction. Register it alongside the tx-form mutators — it wins by key like any override:

mutators: defineApiMutators({
  ...sharedApiMutators(sharedMutators, sharedCtx),        // tx-form (common case)
  createOrder: scoped(async (scope, raw, ctx) => {        // needs outside-tx work
    const args = createOrder.args.parse(raw);
    const chargeId = await stripe.charge(args.amount, { idempotencyKey: ctx.envelope.mid }); // outside tx
    try {
      await scope.transact(createOrder, args, { ...sharedCtx(ctx), chargeId });              // inside tx
    } catch (e) {
      await stripe.refund(chargeId);                       // compensate — the write rejected
      throw e;
    }
    await sendReceipt(ctx.user);                           // after commit
  }),
}),

A {@link ScopedMutator} tagged by {@link scoped} so the harness invokes it with a {@link MutationScope}. Typed as a BRANDED tx-form {@link ApiMutator} purely so it registers in the mutators record without widening it to a union (which would break contextual inference for every plain tx-form entry). Its true runtime shape is (scope, args, ctx); the tag — not the type — routes it, and it is never actually called as a tx-form mutator.

A SCOPED server mutator (WORK-OUTSIDE-TX): server-only code, ONE scope.transact, optional post-commit code. Register it by wrapping in {@link scoped} — the tag the api-server routes on to hand it a {@link MutationScope} instead of running its whole body inside the transaction.

The write handle a server mutator runs against — the ASYNC twin of the client's MutationTx. It is both the isomorphic {@link ServerWriteTx} logical surface (insert/update/upsert/insertIgnore/ delete/row, rendered to dialect SQL) AND the legacy {@link SqlMutationTx} raw escape hatch. Both implementations run reads through the OPEN transaction (read-your-writes): Postgres executes everything live; the SQL-client and daemon adapters accumulate writes and lazily upgrade to an interactive mutation session at the first read (DAEMON-INTERACTIVE-TXN-DESIGN.md §5).

A deliberately narrow raw-SQL facade exposed by the API server. On {@link ServerMutationTx} it is bound to the open mutation transaction; on {@link MutationScope} each call runs in its own transaction outside the mutation boundary. Column aliases should be unique: positional driver rows are keyed by column name, so a duplicate alias is represented by its last value.

One exemplar invocation for {@link dumpQueryShapes} — the args/user a query is built with. Literal values never matter to the dump (shapes are deduped with literals stripped); what an exemplar buys is BRANCH coverage, so supply one per code path a query function can take (an optional filter present/absent, each enum axis, …).

Co-locate a shared (generator) mutator with the validator for its args — pairing the arg SHAPE with the body that consumes it at ONE site, so neither tier restates it (the client derives its callsite type from Args; the server parses untrusted args through .args). Returns the SAME generator function with an args property attached (Object.assign mutates + returns it), so the registered value is byte-for-byte what the client drove before: {@link isGeneratorMutator} still detects it and it still satisfies ClientRegistry.

Bulk-register a SHARED (generator) mutator registry as server mutators — the mutator twin of {@link registerQueries} (which does the same for co-located defineQuery values). Each shared mutator carries its own arg validator (shared(schema, gen)), so this wraps every one with the UNIVERSAL server triad and nothing else: parse the UNTRUSTED wire args (its .args), map the server {@link MutationContext} to the shared {@link MutatorCtx} principal, and drive the SAME body the client predicts ({@link runSharedMutation}). The point is that a shared mutator whose server run adds NO authority beyond that triad needs no hand-written wrapper.

Server-only AUTHORITY the client cannot predict (a title guard, an owner-gated cascade, a NOT EXISTS dedup) stays an explicit {@link ApiMutator} that OVERRIDES the auto-wrapped default — spread this first, then the overrides win by key:

mutators: defineApiMutators({
  ...sharedApiMutators(sharedMutators, (ctx) => ({ user: requireUser(ctx.user) })),
  createIssue: withTitleGuard(sharedMutators.createIssue), // + server-only policy
  deleteIssue: async (tx, raw, ctx) => { ... },            // raw owner-gated cascade
}),

A generator (isomorphic) mutator, shared verbatim by both tiers: the client trusts typed args, the server parses untrusted args into Args before invoking.

A shared mutator that CARRIES its own arg validator, co-located at the def site (shared(schema, gen)). The client registers it exactly like a bare generator mutator — the .args validator is inert there (typed callsites skip the parse); the server ({@link runSharedMutation }, via the api-server's sharedApiMutators) reads .args to parse untrusted wire args before driving the SAME body.

Merge the durable plane with the live tail.

durable is what the IVM view shows; produced is what a subscription has accumulated (the prefix it joined at, plus every chunk). Both are prefixes of the same response, so the merge is "take the longer" — no diffing, no overlap handling, no ranges.

The length comparison is the whole algorithm, which is why a caller MUST seed its accumulator with the text it joined at: a tail carrying only the chunks it received would read as shorter than the durable text and be discarded. useStreamedText does that for you.

A read/write-split RindleDaemonClient (READ-ROUTER-DESIGN.md §2.1). Writes (executeSqlTxn / rejectMutation / applyRowChangeTxn / migrate) go to the single write-master, UNCHANGED and never through the router; reads (materialize / query / dematerialize, and raw executeSqlRead) go to the read router. Raw reads default to a replica (consistency:"eventual") so they scale off the write-master; pass consistency:"strong" on a read to route it to the master for read-your-writes after a write to the same data. Hand one of these to {@link createRindleApiServer} as daemon to point the reads leg at the router while writes stay on the master — no placement logic enters the api-server.

const daemon = new SplitDaemonClient(
  new HttpRindleDaemonClient({ baseUrl: MASTER_URL, headers: writeAuth }),  // writes → master
  new HttpRindleDaemonClient({ baseUrl: ROUTER_URL, headers: routerAuth }), // reads  → router
);

Run API-server mutators through @rindle/sql-client's explicit mutation facade. Query leases, SSR reads and room control continue to use daemon; only authoritative mutation execution moves to the versioned SQL transport.

A SQL dialect for the logical mutation renderer.

The raw-SQL escape hatch for relational/authority statements a keyed op can't express — an owner-gated cascade, a NOT EXISTS dedup. Prefer tx.sql; exec remains the synchronous compatibility shorthand for a queued tx.sql.execute, and statements is the raw write list.

Headers for the SSE response. x-accel-buffering is the nginx-family opt-out — without it a buffering proxy holds the tokens and hands the user a paragraph at a time.

The value in the mapped status column while a stream is live.

When a checkpoint fires — the FIRST of these wins (§3.1). Checkpoints are serialized, so a slow store degrades to fewer, larger checkpoints, never to a queue of them.

The chunk row's deterministic id: a replayed checkpoint collides with itself and is absorbed by ON CONFLICT DO NOTHING — idempotency without an envelope or a dedup ledger (§3.3).

The chunk table's DDL, for the app's migration. The app owns the message table (this only states the three columns the plane needs on it); the chunk table is entirely protocol-shaped, so it is generated rather than hand-written.

Which columns of the app's own tables the plane reads and writes. Every entry has a default except cancel, error, and host, which are opt-in BY NAMING: the plane never emits SQL against a column the app did not ask it to use.

The escape hatch: persist the checkpoint however the app likes. Retried on throw (§3.3), so it must be idempotent under a repeated (from, seq) — AND under a RE-COVER: an append whose write committed but whose ack was lost leaves the plane believing less than the store holds, so the next append's (from, seq) can OVERLAP text already applied. Apply only the unseen suffix (text.slice(applied - from) when applied > from), or better, return {seq: applied} — the authoritative applied length — and the plane resynchronizes instead of re-covering at all. Return {cancelRequested: true} to tell the producer the reader asked it to stop (§6).

What a checkpoint hands the durable plane when the app supplies its own {@link StreamCommit}.

One frame of a subscription. A subscription always begins with open and always ends with exactly one terminal frame — end, stale, or absent — after which the iterator completes.

stale and absent are the two "you are on the durable plane now" answers, and both are SAFE: the store holds everything below floorSeq and everything through durableSeq, so the reader's IVM view converges without the stream. Neither is an error.

Encode a subscription as an SSE body. Each positional frame carries id: <seq>, so a browser EventSource that drops the connection resumes at exactly the right offset with no application code — its own Last-Event-ID header is the from of the next subscribe ({@link * streamRequestFromHttp}).

The reader must close the EventSource on the end frame: EventSource reconnects on ANY close, including a clean one.

The producer's handle (§2). One writer per stream, by construction.

The open probe's verdict: the message row is missing or already advanced. Not retried — it is a settled statement about the app's data, and retrying re-asks a question already answered.

Optional cross-process transport for the LIVE plane (designs-implemented/LM-STREAM-RELAY-DESIGN.md). Both methods are independently optional; which ones you implement is which topology you built — an addressing adapter (a Durable Object named by streamId, fly-replay) implements only attach; a broadcast adapter (Redis pub/sub, NATS) mirrors with publish and subscribes with attach; a log adapter (Redis Streams, Kafka) appends and replays. Never consulted for the durable plane — checkpoints are unaffected by any of this.

The plane does not trust what attach yields: frames are run through the conform pass ({@link StreamRelayConform}) and any contract violation downgrades the subscription to stale, which already means "you are on the durable plane now". A broken relay costs a reader smooth tokens, never corrupted text — and can never reach the producer.

One frame source arriving over a relay, conformed to the CP §4 contract (designs-implemented/LM-STREAM-RELAY-DESIGN.md §4).

An adapter is app code talking to Redis or a socket, and its frames feed spliceStreamText on a browser — so the plane does not trust them. This pass enforces the frame invariants against the prefix actually delivered and downgrades EVERY violation to a legal stale and nothing else: stale already means "you are on the durable plane now, the store is the whole truth", so a broken relay costs a reader smooth tokens, never corrupted text — and cannot wedge a producer.

Replayed spans (a reconnecting adapter re-delivering what it already sent) are ABSORBED rather than punished — deduping against the delivered prefix is what makes reconnect-replay safe without every adapter hand-rolling it. Spans that overlap the prefix but extend past it pass through whole: the client splices at the frame's own offset, so an exact overlap re-covers and appends.

Pure state, no I/O, no plane: feed maps one incoming frame to 0-2 outgoing frames (a missing open is synthesized at the join offset); end/fail close out a source that finished or threw without a terminal. After a terminal, every method returns [].

Pull a subscribe request out of a fetch-style GET: ?streamId=…&from=…, with Last-Event-ID winning over an explicit from (a reconnecting EventSource knows better than its own URL — the URL is the ORIGINAL join point, the header is where it actually got to).

How a stream ended.

• complete — the model finished.
• cancelled — the reader asked it to stop and the producer honoured it.
• error — the generation threw.
• interrupted — the host went away mid-generation. The one status that implies the store may be short of what was produced.

The app's tables (§5). The app authors and migrates BOTH — the message row is unambiguously app-owned (it has chatId, role, token counts) and the chunk row must be reachable from the app's own query as a related subquery, which a Rindle system table would make awkward. The plane only needs to be told where things live. Use {@link streamChunkTableDdl} for the chunk table's migration.

The message table carries WHATEVER ELSE the app wants; the plane's hard requirements are only:

         constraint that omits one of these turns a seal into an infra failure |

| cancel | truthy-readable, if mapped | read on the checkpoint round-trip (§6) | | error | nullable text, if mapped | compaction writes NULL when there is no error | | host | text, if mapped | written at open with the producer's token; the read-back decides the open race (§5.1) |

body is PLANE-OWNED and always a bare string. Rich content (an array of content blocks, tool calls, attachments) belongs in SIBLING columns the app's own mutators write — flush() orders the text before them. For genuinely multi-block streaming, point message at a per-BLOCK table instead: streamId is just an app key, so one stream per block needs nothing from this plane.

Per-table metadata the renderer needs (all reachable from a TableMeta).

Verify a flush credential's MAC, then its claims; returns the payload or throws. The MAC is checked FIRST — no claim is trusted before it passes.