@rindle/client 0.4.2 → 0.4.4

package/README.md

@@ -5,174 +5,44 @@ The shared core for the flat-change client: a **typed schema + query builder**,
 the **`Store`**, and the **`Backend`** seam. It talks to no engine directly — pair it with a
 backend such as [`@rindle/wasm`](../wasm) (local, in-process) or a remote (network) backend.
 
-## Schema + queries
-
 ```ts
-import {
-  table,
-  string,
-  number,
-  boolean,
-  json,
-  createSchema,
-  defineRelationships,
-  rel,
-  extendSchema,
-  eq,
-  gt,
-  ilike,
-  or,
-  exists,
-} from "@rindle/client";
+import { table, string, number, createSchema, gt } from "@rindle/client";
 
 const issue = table("issue")
-  .columns({ id: number(), title: string(), priority: number(), meta: json<{ tags: string[] }>() })
-  .primaryKey("id");
-
-const comment = table("comment")
-  .columns({ id: number(), issueId: number(), body: string() })
-  .primaryKey("id");
-
-const schema = createSchema({ tables: [issue, comment] }); // pass to `new Store(schema, backend)`
-
-const rels = defineRelationships({
-  issueComments: rel(issue, comment, { id: "issueId" }),
-});
-```
-
-- **Operators** are named value-functions: `eq / ne / gt / ge / lt / le / like / ilike / inList / …`.
-- **`where`** is a typed proxy — `where.closed(false)`, `where.priority(gt(3))` — with camelCase
-  sugar `whereClosed(false)`. Multiple `where`s are AND-ed.
-- **`or` / `and` / `exists`** are plain top-level functions (no closure): conditions carry their
-  table type, e.g. `where(or(issue.priority(gt(8)), exists(comment, { parent: ["id"], child: ["issueId"] })))`.
-- **Nesting** is `sub(alias, relationship, build?)`, or
-  `sub(alias, childTable, correlation, build?)` when you want to spell the join inline.
-- **Paging / single-row**: `orderBy(col, dir)`, `limit(n)`, `start(cursor, { exclusive })` (cursor
-  paging from a partial row over the sort columns), and `one()`.
-
-The result type flows through: `store.query.issue.sub("comments", …).materialize()` yields an
-`ArrayView` whose `.data` is typed `{ …issue, comments: Comment[] }[]`.
-
-A top-level **`.one()`** flips `materialize()` to a `SingularArrayView` whose `.data` is the single
-row or `null` (the engine caps the query to `limit 1`) — the unwrap is type-level too:
-
-```ts
-const view = store.query.issue.where.id(id).one().materialize();
-view.subscribe((row) => render(row)); // row: Issue | null, not Issue[]
-```
-
-## Named queries + fragments
-
-Remote subscriptions should be named with `defineQuery`. The returned value is callable: it
-validates untrusted args, builds the query, and stamps it with the `(name, args)` wire identity that
-remote backends subscribe to.
-
-Fragments are reusable selections over a table. They compose into named queries with `include`
-(same row) and `sub` (related rows), so a React screen can open one root query while child
-components keep owning their own data declarations.
-
-```ts
-import { defineFragment, defineQuery, newQueryBuilder } from "@rindle/client";
-import type { FragmentData, FragmentRef } from "@rindle/client";
-
-const q = newQueryBuilder(schema);
-
-export const IssueCardFragment = defineFragment(issue, (i) =>
-  i
-    .select("id", "title")
-    .countAs("commentCount", rels.issueComments),
-);
-
-export type IssueCardData = FragmentData<typeof IssueCardFragment>;
-export type IssueCardRef = FragmentRef<typeof IssueCardFragment>;
-
-export const issuesPageQuery = defineQuery(
-  "issuesPage",
-  (raw): { limit: number } => {
-    const limit = Number((raw as { limit?: unknown }).limit);
-    if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new Error("bad limit");
-    return { limit };
-  },
-  ({ limit }) => q.issue.orderBy("id", "asc").limit(limit).include(IssueCardFragment),
-);
-```
-
-`FragmentData<F>` is the local data shape read by the component that owns `F`. `FragmentRef<F>` is
-the opaque token React passes between components; use `fragmentKey(ref)` from `@rindle/client` or
-`@rindle/react` for stable list keys. Passing a fragment directly to `sub(alias, rel, ChildFragment)`
-creates child refs in the React-facing local data. Passing an inline builder such as
-`sub(alias, rel, (q) => q.include(ChildFragment).orderBy(...))` keeps that child payload inline for
-the parent to read.
-
-## Local-only tables
-
-Some UI state should live in the same reactive store as synced data but must never cross the
-wire: selections, draft text, view preferences, scratch rows. Mark those tables as
-**local-only** with `table(name, { local: true })` and include them in the same schema:
-
-```ts
-const issue = table("issue").columns({ id: number(), title: string() }).primaryKey("id");
-const selection = table("selection", { local: true })
-  .columns({ id: number(), issueId: number() })
-  .primaryKey("id");
-
-const schema = createSchema({ tables: [issue, selection] });
-```
-
-Local-only tables are client-authoritative: they are omitted from the normalized schema
-fingerprint, never advertised to the server, never synced, and never rewound during an
-optimistic rebase. `store.query` can join/query them locally, but `newQueryBuilder(schema)`
-(the server/named-query scope) rejects them so a named remote query cannot depend on private
-client state.
-
-Write local state with `store.writeLocal(...)`, not with a replayable mutator:
-
-```ts
-await store.writeLocal((tx) => tx.add("selection", { id: 1, issueId: 42 }));
-```
-
-`writeLocal` accepts only local-only tables and rejects synced tables. Conversely, predicted
-mutators cannot touch local-only tables: the server replays a mutator from `(name, args)` alone,
-so private client state must stay on the direct local-write path.
-
-SQL-first apps usually keep synced tables in a generated file. Do not edit that file to add
-local tables; extend it in hand-written code:
-
-```ts
-// shared/schema.local.ts
-import { extendSchema, number, string, table } from "@rindle/client";
-import { schema as generatedSchema } from "./schema.gen.ts";
-
-export const draft = table("draft", { local: true })
-  .columns({ id: string(), issueId: number(), body: string() })
+  .columns({ id: number(), title: string(), priority: number() })
   .primaryKey("id");
+const schema = createSchema({ tables: [issue] }); // pass to `new Store(schema, backend)`
 
-export const clientSchema = extendSchema(generatedSchema, { tables: [draft] });
-```
-
-Hand `clientSchema` to the browser store. Keep using the generated schema for API-server
-resolution and daemon-facing code; `extendSchema` intentionally accepts only local-only tables,
-so real synced tables still have to come from `rindle schema gen`.
-
-## The Backend seam
-
-A `Backend` emits a per-query `ChangeEvent` stream (`hello` → `snapshot` → `batch`) and accepts
-mutations. The `Store` builds one `ArrayView` per query and routes events to it. The **same**
-`Store` / `ArrayView` / builder work behind a local (WASM) or remote (network) backend — only the
-backend differs.
-
-```ts
-const store = new Store(schema, backend);
-const view = store.query.issue.where.closed(false).materialize();
-view.subscribe(render);
-await store.write((tx) => tx.add("issue", { id: 1, title: "x", priority: 3, meta: { tags: [] } }));
+const view = store.query.issue.where.priority(gt(3)).orderBy("id", "asc").materialize();
+view.subscribe(render); // typed, reference-stable, always == a fresh query
 ```
 
-## Reads
-
-`view.data` is the materialized tree, reference-stable: an update re-projects only what changed, so
-unchanged subtrees keep their object identity (React/Solid memoize on it). JSON columns are parsed
-to objects on read.
+Everything an app builds on lives here:
+
+- the **query builder** (`where` proxies, `or`/`and`/`exists`, `sub`, `orderBy`/`limit`/`start`,
+  `.one()`, `countAs`/`count()`/`groupBy`/`having`, `select`);
+- **named queries & fragments** (`defineQuery`, `defineFragment`, `defineRelationships`/`rel`) —
+  the co-located, waterfall-free composition surface;
+- the **isomorphic-mutator vocabulary** (`defineMutators` → `shared(args, gen)`, `IsoTx`,
+  `MutationGen`, `MutatorCtx`) — one generator body per write, run on both tiers;
+- **local-only tables** (`table(name, { local: true })` + `extendSchema` + `store.writeLocal`) —
+  client-authoritative state that never syncs or rebases.
+
+## Docs
+
+- **[Supported query shapes](https://rindle.sh/docs/supported-queries-ts)** — the honest matrix of
+  what the builder can lower, and the build-time rejections.
+- **[Compose the UI with fragments](https://rindle.sh/docs/fragments)** — `defineQuery` /
+  `defineFragment` / `defineRelationships` in full.
+- **[Isomorphic mutators](https://rindle.sh/docs/mutators)** — the write contract: the op
+  vocabulary, reads, `ctx.user`, the determinism rules.
+- **[The browser client](https://rindle.sh/docs/client)** — this core behind the optimistic synced
+  store, including local-only tables.
+- **[Schema & migrations](https://rindle.sh/docs/schema)** — why the schema is generated from SQL,
+  and the one allowed hand-edit.
+
+Markdown mirrors live at `https://rindle.sh/docs/<slug>.md`; for agents:
+[llms.txt](https://rindle.sh/llms.txt).
 
 ## Build
 

package/dist/index.d.ts

@@ -7,8 +7,8 @@ export * from "./ssr.ts";
 export { resolveChange, subRow } from "./resolve.ts";
 export type { NamedRow, ResolvedChange } from "./resolve.ts";
 export type { KeyedRow, MutationOp, ServerWriteTx } from "./mutation-ops.ts";
-export { driveMutationAsync, driveMutationSync, isGeneratorMutator, isoTx, shared, } from "./mutation-ops.ts";
-export type { ArgSchema, AsyncEffectExec, BatchEffect, IsoTx, MutationGen, MutatorCtx, ReadEffect, SharedMutator, SharedMutatorWithArgs, SyncEffectExec, YieldEffect, } from "./mutation-ops.ts";
+export { defineMutators, driveMutationAsync, driveMutationSync, isGeneratorMutator, isoTx, shared, } from "./mutation-ops.ts";
+export type { ArgSchema, AsyncEffectExec, BatchEffect, IsoTx, IsoTxOf, MutationGen, MutatorCtx, QueryArg, QueryEffect, QueryResultRow, ReadEffect, SharedMutator, SharedMutatorWithArgs, SyncEffectExec, YieldEffect, } from "./mutation-ops.ts";
 export { stableKey } from "./key.ts";
 export { COMPARATOR_VERSION, compareNumber, compareRows, compareString, compareValue } from "./compare.ts";
 export type { Backend, BackendDevObserver, BackendServerDelta, ChangeEvent, ColType, FlatChange, FlatOp, Mutation, MutationEnvelope, NormalizedEvent, NormalizedOp, NormalizedSource, NormalizedTableSchema, OptimisticSource, PathSeg, ProgressFrame, QueryId, RemoteQuery, ResultType, WireNode, WireProjection, WireRel, WireSchema, WireValue, } from "./types.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AAEzB,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE7D,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,MAAM,GACP,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,SAAS,EACT,eAAe,EACf,WAAW,EACX,KAAK,EACL,WAAW,EACX,UAAU,EACV,UAAU,EACV,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE3G,YAAY,EACV,OAAO,EACP,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,OAAO,EACP,UAAU,EACV,MAAM,EACN,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,OAAO,EACP,WAAW,EACX,UAAU,EACV,QAAQ,EACR,cAAc,EACd,OAAO,EACP,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG9F,YAAY,EACV,SAAS,EACT,GAAG,EACH,KAAK,EACL,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,GAAG,EACH,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,aAAa,GACd,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AAEzB,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE7D,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,MAAM,GACP,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,SAAS,EACT,eAAe,EACf,WAAW,EACX,KAAK,EACL,OAAO,EACP,WAAW,EACX,UAAU,EACV,QAAQ,EACR,WAAW,EACX,cAAc,EACd,UAAU,EACV,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE3G,YAAY,EACV,OAAO,EACP,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,OAAO,EACP,UAAU,EACV,MAAM,EACN,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,OAAO,EACP,WAAW,EACX,UAAU,EACV,QAAQ,EACR,cAAc,EACd,OAAO,EACP,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG9F,YAAY,EACV,SAAS,EACT,GAAG,EACH,KAAK,EACL,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,GAAG,EACH,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,aAAa,GACd,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
 // @rindle/client — the backend-agnostic flat-change client core: typed schema, query builder,
 // comparator, Backend seam, and the ArrayView contract. (The ArrayView folding impl + the
 // Store/backend wiring land in later slices.)
-export * from "./schema.js"; // table/columns/primaryKey, createSchema/extendSchema, refineTable/refineSchema, string/number/boolean/json, Col, RowOf, Row, TableDef, tableSpec, SCHEMA
+export * from "./schema.js"; // table/columns/primaryKey, createSchema/extendSchema, refineTable/refineSchema, string/number/boolean/json, Col, RowOf, Row, InsertOf, Insert, insertPlan, insertCell, TableDef, tableSpec, SCHEMA
 export * from "./operators.js"; // eq/ne/gt/ge/lt/le/like/notLike/ilike/notIlike/inList/notInList/is/isNot, and/or, Pred, Cond, Arg
 export * from "./query.js"; // Query, QueryRoot, queries/newQueryBuilder, defineQuery/NamedQuery, exists, notExists, defineFragment/Fragment/FragmentRef/isFragment
 export * from "./view.js"; // ArrayView, SingularArrayView, FlatArrayView, SingularView, ViewTypes
@@ -9,7 +9,7 @@ export * from "./store.js"; // Store, WriteTx, AssembledNode, DehydratedQuery, D
 export * from "./ssr.js"; // createServerStore, ServerStore, OneShotBackend, OneShotQueryFn, OneShotResult, ServerStoreOptions
 export { resolveChange, subRow } from "./resolve.js"; // positional FlatChange → named rows (inverse of the wire encoder)
 // shared (generator) mutator seam — one body, sync on the client + async on the server
-export { driveMutationAsync, driveMutationSync, isGeneratorMutator, isoTx, shared, } from "./mutation-ops.js";
+export { defineMutators, driveMutationAsync, driveMutationSync, isGeneratorMutator, isoTx, shared, } from "./mutation-ops.js";
 export { stableKey } from "./key.js"; // canonical viewKey for an AST (shared with @rindle/react)
 export { COMPARATOR_VERSION, compareNumber, compareRows, compareString, compareValue } from "./compare.js";
 export { CLIENT_MUTATIONS_SCHEMA, CLIENT_MUTATIONS_TABLE, LMID_QUERY_NAME } from "./types.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,0FAA0F;AAC1F,8CAA8C;AAE9C,cAAc,aAAa,CAAC,CAAC,0JAA0J;AACvL,cAAc,gBAAgB,CAAC,CAAC,mGAAmG;AACnI,cAAc,YAAY,CAAC,CAAC,uIAAuI;AACnK,cAAc,WAAW,CAAC,CAAC,uEAAuE;AAClG,cAAc,YAAY,CAAC,CAAC,kEAAkE;AAC9F,cAAc,UAAU,CAAC,CAAC,oGAAoG;AAE9H,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC,CAAC,mEAAmE;AAIzH,uFAAuF;AACvF,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,MAAM,GACP,MAAM,mBAAmB,CAAC;AAe3B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC,CAAC,2DAA2D;AAEjG,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA6B3G,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,0FAA0F;AAC1F,8CAA8C;AAE9C,cAAc,aAAa,CAAC,CAAC,oMAAoM;AACjO,cAAc,gBAAgB,CAAC,CAAC,mGAAmG;AACnI,cAAc,YAAY,CAAC,CAAC,uIAAuI;AACnK,cAAc,WAAW,CAAC,CAAC,uEAAuE;AAClG,cAAc,YAAY,CAAC,CAAC,kEAAkE;AAC9F,cAAc,UAAU,CAAC,CAAC,oGAAoG;AAE9H,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC,CAAC,mEAAmE;AAIzH,uFAAuF;AACvF,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,MAAM,GACP,MAAM,mBAAmB,CAAC;AAmB3B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC,CAAC,2DAA2D;AAEjG,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA6B3G,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/mutation-ops.d.ts

@@ -1,3 +1,5 @@
+import type { Ast } from "./ast.ts";
+import type { ColsMap, InsertOf, PkColsOf, PkMap, PkOf, Schema, UpdateOf } from "./schema.ts";
 import type { WireValue } from "./types.ts";
 /** A keyed row: column name → cell. The ergonomic write shape (validated against the schema at
  *  runtime). JSON columns carry their raw JSON string (a {@link WireValue}), never a parsed object. */
@@ -64,23 +66,60 @@ export type BatchEffect = {
     kind: "all";
     effects: readonly YieldEffect[];
 };
-/** Everything a generator mutator may `yield`: a write {@link MutationOp}, a {@link ReadEffect}, or a
- *  {@link BatchEffect}. */
-export type YieldEffect = MutationOp | ReadEffect | BatchEffect;
+/** A row returned by a {@link QueryEffect}: column name → cell, plus each materialized relationship
+ *  name → its nested row(s) — an array (a plural relationship) or a single row / `null` (a `.one()`
+ *  relationship). Recursive. Presented identically on both tiers (a `view.data` row of the same
+ *  query). */
+export type QueryResultRow = {
+    [key: string]: WireValue | QueryResultRow | QueryResultRow[];
+};
+/** What {@link IsoTx.query} accepts: a query handle whose `.ast()` lowers to the wire {@link Ast} —
+ *  exactly what the typed query builder produces (`newQueryBuilder(schema).<table>…`, the tier-agnostic
+ *  server-scope builder both tiers can construct because it performs no I/O). Structural so the seam
+ *  need not carry the builder's heavy generics. */
+export type QueryArg = {
+    ast(): Ast;
+};
+/** A full-shape read a generator mutator yields — a `where`/`orderBy`/`limit`/join query over the
+ *  state this mutator is mutating (read-your-writes, like {@link ReadEffect} but an arbitrary shape).
+ *  Evaluates to {@link QueryResultRow}`[]` — ALWAYS an array of the matching rows, in the query's
+ *  order, on BOTH tiers (a root `.one()` is not unwrapped here: take `[0]`). The single next-type is
+ *  a row, so cast the yield (`(yield tx.query(q)) as unknown as QueryResultRow[]`), same as `all`. */
+export type QueryEffect = {
+    kind: "query";
+    query: QueryArg;
+};
+/** Everything a generator mutator may `yield`: a write {@link MutationOp}, a point {@link ReadEffect},
+ *  a full-query {@link QueryEffect}, or a {@link BatchEffect} fan-out. */
+export type YieldEffect = MutationOp | ReadEffect | BatchEffect | QueryEffect;
 /** 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`
  *  take a FULL row; `update`/`delete` take the pk columns (`update` adds the columns to change). */
-export interface IsoTx {
-    insert(table: string, row: KeyedRow): MutationOp;
-    update(table: string, row: KeyedRow): MutationOp;
-    upsert(table: string, row: KeyedRow): MutationOp;
-    insertIgnore(table: string, row: KeyedRow): MutationOp;
-    delete(table: string, pk: KeyedRow): MutationOp;
-    row(table: string, pk: KeyedRow): ReadEffect;
+export interface IsoTx<S extends ColsMap = ColsMap, P extends Record<string, string> = PkMap<S>> {
+    /** Insert a FULL row — nullable columns may be omitted (filled `null`, design 206 §6.2/§7). */
+    insert<N extends keyof S & string>(table: N, row: InsertOf<S[N]>): MutationOp;
+    /** Update the row identified by its pk columns (REQUIRED); only the named non-pk columns change. */
+    update<N extends keyof S & string>(table: N, row: UpdateOf<S[N], PkColsOf<S, P, N>>): MutationOp;
+    /** Insert, or fully replace on pk conflict (a FULL row, like {@link IsoTx.insert}). */
+    upsert<N extends keyof S & string>(table: N, row: InsertOf<S[N]>): MutationOp;
+    /** Insert a FULL row, or do nothing if the pk already exists. */
+    insertIgnore<N extends keyof S & string>(table: N, row: InsertOf<S[N]>): MutationOp;
+    /** Delete the row identified by its pk columns. */
+    delete<N extends keyof S & string>(table: N, pk: PkOf<S[N], PkColsOf<S, P, N>>): MutationOp;
+    /** Read one row by primary key (read-your-writes). */
+    row<N extends keyof S & string>(table: N, pk: PkOf<S[N], PkColsOf<S, P, N>>): ReadEffect;
+    /** Run a full query (`where`/`orderBy`/`limit`/join) over the state this mutator is mutating —
+     *  read-your-writes, like {@link row} but for arbitrary shapes. Pass a query from the tier-agnostic
+     *  builder, e.g. `tx.query(q.issue.where("ownerId", "=", ctx.user))` where `q = newQueryBuilder(schema)`.
+     *  The `yield` evaluates to {@link QueryResultRow}`[]` (cast it — the generator's single next-type is a row). */
+    query(query: QueryArg): QueryEffect;
     all(effects: readonly YieldEffect[]): BatchEffect;
 }
-/** The one shared effect factory (stateless — see {@link IsoTx}). */
+/** 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. */
 export declare const isoTx: IsoTx;
 /** 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
@@ -116,6 +155,23 @@ export type SharedMutatorWithArgs<Args, Ctx extends MutatorCtx = MutatorCtx> = S
  *  registered value is byte-for-byte what the client drove before: {@link isGeneratorMutator} still
  *  detects it and it still `satisfies ClientRegistry`. */
 export declare function shared<Args, Ctx extends MutatorCtx = MutatorCtx>(args: ArgSchema<Args>, run: SharedMutator<Args, Ctx>): SharedMutatorWithArgs<Args, Ctx>;
+/** Bind a schema to the mutator authoring surface: `const { shared } = defineMutators(schema)`.
+ *
+ *  The returned `shared` is the schema-typed twin of the bare {@link shared} — its `tx` is an
+ *  {@link IsoTx} parameterized by THIS schema, so `tx.insert`/`update`/`upsert`/`insertIgnore`/`delete`
+ *  check the table name, every column name, each column's value type, nullable-omit on inserts, and
+ *  the exact primary-key columns on `update`/`delete` — all at compile time. It registers identically
+ *  to the bare form (same runtime value, still `satisfies ClientRegistry`, still an isomorphic
+ *  generator the server drives): only the AUTHORING types tighten. `schema` is read for its TYPE only
+ *  (never at runtime). Reads (`yield tx.row(...)`) stay loosely typed — a generator's single
+ *  next-type can't carry a per-table row. */
+/** The typed {@link IsoTx} for a given schema — `IsoTxOf<typeof schema>`. Use it to annotate a helper
+ *  that a mutator body passes its `tx` to (e.g. `const ensureUser = (tx: IsoTxOf<typeof schema>, …)`),
+ *  so the helper gets the same table/column/pk typing the `defineMutators` `shared` callback does. */
+export type IsoTxOf<Sch extends Schema> = Sch extends Schema<infer S, infer P> ? IsoTx<S, P> : never;
+export declare function defineMutators<S extends ColsMap, P extends Record<string, string>>(_schema: Schema<S, P>): {
+    shared<Args, Ctx extends MutatorCtx = MutatorCtx>(args: ArgSchema<Args>, run: (tx: IsoTx<S, P>, args: Args, ctx: Ctx) => MutationGen): SharedMutatorWithArgs<Args, Ctx>;
+};
 /** True iff `fn` is a generator function (a shared/isomorphic mutator) rather than a plain function —
  *  the driver accepts both forms. Detected structurally (native `GeneratorFunction`). */
 export declare function isGeneratorMutator(fn: unknown): fn is (...args: never[]) => MutationGen;
@@ -124,17 +180,21 @@ export declare function isGeneratorMutator(fn: unknown): fn is (...args: never[]
 export interface SyncEffectExec {
     apply(op: MutationOp): void;
     read(table: string, pk: KeyedRow): KeyedRow | undefined;
+    query(q: QueryArg): QueryResultRow[];
 }
 /** Drive a generator mutator SYNCHRONOUSLY (the client, inside the wasm write transaction). Each
- *  yielded write applies immediately; each read is resolved and fed back; a batch runs in order. */
+ *  yielded write applies immediately; each read (point or query) is resolved and fed back; a batch
+ *  runs in order. */
 export declare function driveMutationSync(gen: MutationGen, exec: SyncEffectExec): void;
 /** A tier's ASYNCHRONOUS effect executor (the server transaction): every op is a Promise. */
 export interface AsyncEffectExec {
     apply(op: MutationOp): Promise<void>;
     read(table: string, pk: KeyedRow): Promise<KeyedRow | undefined>;
+    query(q: QueryArg): Promise<QueryResultRow[]>;
 }
 /** Drive a generator mutator ASYNCHRONOUSLY (the server, against the open transaction). Writes are
  *  awaited (harmless: a single interactive Postgres connection serializes statements anyway, and the
- *  daemon backend resolves them instantly), reads suspend, and a batch fans out with `Promise.all`. */
+ *  daemon backend resolves them instantly), reads (point or query) suspend, and a batch fans out with
+ *  `Promise.all`. */
 export declare function driveMutationAsync(gen: MutationGen, exec: AsyncEffectExec): Promise<void>;
 //# sourceMappingURL=mutation-ops.d.ts.map

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

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

package/dist/mutation-ops.js

@@ -3,7 +3,10 @@
 // insertIgnore/delete over a keyed row), not HOW — the server renders dialect SQL and the
 // client applies to its local engine. This lives in `@rindle/client` (the leaf both tiers
 // import); the SQL renderer that consumes it is server-only (`@rindle/api-server`).
-/** The one shared effect factory (stateless — see {@link IsoTx}). */
+/** 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. */
 export const isoTx = {
     insert: (table, row) => ({ kind: "insert", table, row }),
     update: (table, row) => ({ kind: "update", table, row }),
@@ -11,6 +14,7 @@ export const isoTx = {
     insertIgnore: (table, row) => ({ kind: "insertIgnore", table, row }),
     delete: (table, pk) => ({ kind: "delete", table, pk }),
     row: (table, pk) => ({ kind: "row", table, pk }),
+    query: (query) => ({ kind: "query", query }),
     all: (effects) => ({ kind: "all", effects }),
 };
 /** Co-locate a shared (generator) mutator with the validator for its args — pairing the arg SHAPE
@@ -22,6 +26,15 @@ export const isoTx = {
 export function shared(args, run) {
     return Object.assign(run, { args });
 }
+export function defineMutators(_schema) {
+    return {
+        shared(args, run) {
+            // The typed `tx: IsoTx<S, P>` is authoring-only; the driver invokes with the loose `isoTx`
+            // singleton (cast at the call boundary, like the bare `shared`), so the value is registry-shaped.
+            return Object.assign(run, { args });
+        },
+    };
+}
 /** True iff `fn` is a generator function (a shared/isomorphic mutator) rather than a plain function —
  *  the driver accepts both forms. Detected structurally (native `GeneratorFunction`). */
 export function isGeneratorMutator(fn) {
@@ -29,11 +42,14 @@ export function isGeneratorMutator(fn) {
         fn.constructor?.name === "GeneratorFunction");
 }
 /** Drive a generator mutator SYNCHRONOUSLY (the client, inside the wasm write transaction). Each
- *  yielded write applies immediately; each read is resolved and fed back; a batch runs in order. */
+ *  yielded write applies immediately; each read (point or query) is resolved and fed back; a batch
+ *  runs in order. */
 export function driveMutationSync(gen, exec) {
     const run = (eff) => {
         if (eff.kind === "row")
             return exec.read(eff.table, eff.pk);
+        if (eff.kind === "query")
+            return exec.query(eff.query);
         if (eff.kind === "all")
             return eff.effects.map(run);
         exec.apply(eff);
@@ -44,11 +60,14 @@ export function driveMutationSync(gen, exec) {
 }
 /** Drive a generator mutator ASYNCHRONOUSLY (the server, against the open transaction). Writes are
  *  awaited (harmless: a single interactive Postgres connection serializes statements anyway, and the
- *  daemon backend resolves them instantly), reads suspend, and a batch fans out with `Promise.all`. */
+ *  daemon backend resolves them instantly), reads (point or query) suspend, and a batch fans out with
+ *  `Promise.all`. */
 export async function driveMutationAsync(gen, exec) {
     const run = async (eff) => {
         if (eff.kind === "row")
             return exec.read(eff.table, eff.pk);
+        if (eff.kind === "query")
+            return (await exec.query(eff.query));
         if (eff.kind === "all")
             return (await Promise.all(eff.effects.map(run)));
         await exec.apply(eff);

package/dist/mutation-ops.js.map

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