@rindle/client 0.3.1 → 0.4.3

package/src/mutation-ops.ts

@@ -0,0 +1,264 @@
+// Isomorphic mutation ops — the backend-agnostic "rindle mutation" vocabulary
+// (MUTATORS-ISOMORPHIC plan). A mutator names WHAT it writes (insert/update/upsert/
+// 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`).
+
+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. */
+export type KeyedRow = Record<string, WireValue>;
+
+/** One structured write intent — the discriminated union that mirrors the write half of the client
+ *  `MutationTx` 1:1. Keyed (column-name addressed), so it is independent of column order. */
+export type MutationOp =
+  | { kind: "insert"; table: string; row: KeyedRow } // a FULL row (every column present)
+  | { kind: "upsert"; table: string; row: KeyedRow } // full row; replace non-pk cols on pk conflict
+  | { kind: "insertIgnore"; table: string; row: KeyedRow } // full row; do nothing on pk conflict
+  | { kind: "update"; table: string; row: KeyedRow } // pk cols + the non-pk cols to change
+  | { kind: "delete"; table: string; pk: KeyedRow }; // pk cols only
+
+/** The ASYNC server-side write surface a mutator runs against. Semantically the twin of the client's
+ *  synchronous `MutationTx` write methods — same names, same keyed-row arguments — but every op is a
+ *  Promise so a Postgres backend can execute it live against an open transaction (read-your-writes).
+ *  A rindle/daemon backend resolves writes immediately (accumulate) and serves `row` from committed
+ *  state. `insert` requires every column; `update`/`delete` require the pk columns. */
+export interface ServerWriteTx {
+  /** Insert a FULL row (every column named; missing or unknown columns throw). */
+  insert(table: string, row: KeyedRow): Promise<void>;
+  /** Update the row identified by the pk columns; only the named non-pk columns change. A missing
+   *  row is a NO-OP. */
+  update(table: string, row: KeyedRow): Promise<void>;
+  /** Insert, or fully replace when the pk already exists (a FULL row, like `insert`). */
+  upsert(table: string, row: KeyedRow): Promise<void>;
+  /** Insert a FULL row, or do nothing if the pk already exists (the SQL twin of the client
+   *  `if (!tx.row(pk)) tx.insert(row)` pattern). */
+  insertIgnore(table: string, row: KeyedRow): Promise<void>;
+  /** Delete the row identified by the pk columns. A missing row is a NO-OP. */
+  delete(table: string, pk: KeyedRow): Promise<void>;
+  /** Read one row by primary key, through the OPEN transaction on both backends
+   *  (read-your-writes: live on Postgres; via an interactive mutation session on the daemon,
+   *  DAEMON-INTERACTIVE-TXN-DESIGN.md §5.3). */
+  row(table: string, pk: KeyedRow): Promise<KeyedRow | undefined>;
+}
+
+// --------------------------------------------------------------------------- shared (generator) mutators
+//
+// The isomorphic mutator seam (MUTATORS-ISOMORPHIC plan §"one body, two tiers"): a mutator is a
+// GENERATOR that `yield`s effects instead of an async/sync function. A generator is neither sync nor
+// async — the tier's DRIVER decides — so ONE body runs synchronously against the browser wasm engine
+// AND against a live async Postgres transaction on the server. Writes are `yield`ed and pipelined by
+// the driver (never individually awaited by the body); a read is the thing that suspends. Three read
+// shapes: `yield tx.row(...)` (a point pk read, evaluating to the row), `yield tx.query(builder)` (a
+// full `where`/`orderBy`/`limit`/join query, evaluating to its rows), and `yield tx.all([...])` (a
+// fan-out — Promise.all on the server, in-order on the client). All are order-preserving on both
+// tiers, so the body stays deterministic. Every read is read-your-writes (sees this mutator's own
+// writes-so-far). `tx.query` runs the SAME query engine live queries use (the wasm IVM on the client;
+// `@rindle/query-compiler`'s SQLite SELECT through the open session on the daemon backend).
+
+/** A point read a generator mutator yields; the driver resolves it and feeds the row back through
+ *  `gen.next(row)`. Read-your-writes on every tier: the client reads its local engine, and both
+ *  server backends read the open transaction (the daemon via an interactive mutation session). */
+export type ReadEffect = { kind: "row"; table: string; pk: KeyedRow };
+
+/** A fan-out a generator mutator yields: run several effects "together". The server driver resolves
+ *  them with `Promise.all`; the client driver runs them in array order (already synchronous). Results
+ *  return in the SAME order on both tiers, so the mutator stays deterministic. The `yield` evaluates
+ *  to `(KeyedRow | undefined)[]` at runtime (cast it — the generator's single next-type is a row). */
+export type BatchEffect = { kind: "all"; effects: readonly YieldEffect[] };
+
+/** 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<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}). 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: IsoTx = {
+  insert: (table: string, row: KeyedRow): MutationOp => ({ kind: "insert", table, row }),
+  update: (table: string, row: KeyedRow): MutationOp => ({ kind: "update", table, row }),
+  upsert: (table: string, row: KeyedRow): MutationOp => ({ kind: "upsert", table, row }),
+  insertIgnore: (table: string, row: KeyedRow): MutationOp => ({ kind: "insertIgnore", table, row }),
+  delete: (table: string, pk: KeyedRow): MutationOp => ({ kind: "delete", table, pk }),
+  row: (table: string, pk: KeyedRow): ReadEffect => ({ kind: "row", table, pk }),
+  query: (query: QueryArg): QueryEffect => ({ kind: "query", query }),
+  all: (effects: readonly YieldEffect[]): BatchEffect => ({ kind: "all", effects }),
+} as unknown as 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
+ *  `MutationContext` is a superset of this.) */
+export interface MutatorCtx {
+  user: string;
+}
+
+/** 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. */
+export type MutationGen = Generator<YieldEffect, void, KeyedRow | undefined>;
+
+/** A generator (isomorphic) mutator, shared verbatim by both tiers: the client trusts typed `args`,
+ *  the server parses untrusted args into `Args` before invoking. */
+export type SharedMutator<Args, Ctx extends MutatorCtx = MutatorCtx> = (
+  tx: IsoTx,
+  args: Args,
+  ctx: Ctx,
+) => MutationGen;
+
+/** 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. */
+export interface ArgSchema<Args> {
+  parse(raw: unknown): Args;
+}
+
+/** 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. */
+export type SharedMutatorWithArgs<Args, Ctx extends MutatorCtx = MutatorCtx> = SharedMutator<Args, Ctx> & {
+  args: ArgSchema<Args>;
+};
+
+/** 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`. */
+export function shared<Args, Ctx extends MutatorCtx = MutatorCtx>(
+  args: ArgSchema<Args>,
+  run: SharedMutator<Args, Ctx>,
+): SharedMutatorWithArgs<Args, Ctx> {
+  return Object.assign(run, { args });
+}
+
+/** 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 function defineMutators<S extends ColsMap, P extends Record<string, string>>(_schema: Schema<S, P>) {
+  return {
+    shared<Args, Ctx extends MutatorCtx = MutatorCtx>(
+      args: ArgSchema<Args>,
+      run: (tx: IsoTx<S, P>, args: Args, ctx: Ctx) => MutationGen,
+    ): SharedMutatorWithArgs<Args, Ctx> {
+      // 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 as unknown as SharedMutator<Args, Ctx>, { 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: unknown): fn is (...args: never[]) => MutationGen {
+  return (
+    typeof fn === "function" &&
+    (fn as { constructor?: { name?: string } }).constructor?.name === "GeneratorFunction"
+  );
+}
+
+/** A tier's SYNCHRONOUS effect executor (the browser wasm engine): apply a write, resolve a read —
+ *  both immediate. */
+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 (point or query) is resolved and fed back; a batch
+ *  runs in order. */
+export function driveMutationSync(gen: MutationGen, exec: SyncEffectExec): void {
+  const run = (eff: YieldEffect): KeyedRow | undefined => {
+    if (eff.kind === "row") return exec.read(eff.table, eff.pk);
+    if (eff.kind === "query") return exec.query(eff.query) as unknown as KeyedRow | undefined;
+    if (eff.kind === "all") return eff.effects.map(run) as unknown as KeyedRow | undefined;
+    exec.apply(eff);
+    return undefined;
+  };
+  for (let step = gen.next(); !step.done; step = gen.next(run(step.value)));
+}
+
+/** 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 (point or query) suspend, and a batch fans out with
+ *  `Promise.all`. */
+export async function driveMutationAsync(gen: MutationGen, exec: AsyncEffectExec): Promise<void> {
+  const run = async (eff: YieldEffect): Promise<KeyedRow | undefined> => {
+    if (eff.kind === "row") return exec.read(eff.table, eff.pk);
+    if (eff.kind === "query") return (await exec.query(eff.query)) as unknown as KeyedRow | undefined;
+    if (eff.kind === "all") return (await Promise.all(eff.effects.map(run))) as unknown as KeyedRow | undefined;
+    await exec.apply(eff);
+    return undefined;
+  };
+  for (let step = gen.next(); !step.done; step = gen.next(await run(step.value)));
+}

package/src/schema.ts

@@ -8,32 +8,58 @@
 
 import type { Arg, Cond } from "./operators.ts";
 import { fieldCondition } from "./operators.ts";
-import type { ColType } from "./types.ts";
+import type { ColType, WireValue } from "./types.ts";
 
-/** A column descriptor. `type` drives the comparator + JSON parsing; `__t` is a phantom. */
+/** A column descriptor. `type` drives the comparator + JSON parsing; `__t` is a phantom. A
+ *  nullable column is a `Col<T | null>` — that is the ONLY thing nullability changes at the type
+ *  level, so `RowOf` (and the field-condition factory) widen automatically.
+ *
+ *  `optional` is the runtime companion of that phantom: set by {@link ColBuilder.nullable}, it is
+ *  what the write funnels read to make a nullable column omittable from an insert (filled with
+ *  `null`, design 206 §6.2). It mirrors the engine's `ColumnDef.optional`
+ *  (`pragma_table_info.notnull == 0`); absent ⇒ `NOT NULL` / required. */
 export interface Col<T> {
   readonly type: ColType;
+  readonly optional?: boolean;
   readonly __t?: T;
 }
 export type ColT<X> = X extends Col<infer T> ? T : never;
 export type AnyCols = Record<string, Col<unknown>>;
 export type RowOf<C extends AnyCols> = { [K in keyof C]: ColT<C[K]> };
 
-export const string = (): Col<string> => ({ type: "string" });
-export const number = (): Col<number> => ({ type: "number" });
-export const boolean = (): Col<boolean> => ({ type: "boolean" });
-export const json = <T = unknown>(): Col<T> => ({ type: "json" });
+/** The chainable form returned by the column factories: a {@link Col} plus `.nullable()`.
+ *
+ *  `.nullable()` widens the column's value type to `T | null` — its `Row<…>` field becomes
+ *  `T | null` — and sets the runtime {@link Col.optional} marker so it may be omitted from an insert
+ *  (design 206 §6.2). `rindle schema gen` emits `.nullable()` for every nullable (non-`NOT NULL`) SQL
+ *  column; you can also call it by hand on a local-only table's columns. It is idempotent and stays
+ *  chainable. */
+export interface ColBuilder<T> extends Col<T> {
+  nullable(): ColBuilder<T | null>;
+}
+const makeCol = <T>(type: ColType, optional = false): ColBuilder<T> => ({
+  type,
+  ...(optional ? { optional: true } : null),
+  nullable: () => makeCol<T | null>(type, true),
+});
+
+export const string = <T extends string = string>(): ColBuilder<T> => makeCol<T>("string");
+export const number = <T extends number = number>(): ColBuilder<T> => makeCol<T>("number");
+export const boolean = (): ColBuilder<boolean> => makeCol<boolean>("boolean");
+export const json = <T = unknown>(): ColBuilder<T> => makeCol<T>("json");
 
 /** Metadata key on a {@link TableDef} (a `unique symbol`, so no column name collides). */
 export const SCHEMA: unique symbol = Symbol("rindle.schema");
 
-export interface TableMeta<N extends string = string, C extends AnyCols = AnyCols> {
+export interface TableMeta<N extends string = string, C extends AnyCols = AnyCols, PK extends string = string> {
   readonly name: N;
   readonly columns: C;
-  // Plain `string[]` (NOT `keyof C`): `keyof C` is contravariant, which would make
-  // `TableMeta` non-covariant in `C` and break `TableDef<concrete>` → `AnyTable`. Key
-  // validity is enforced on the `primaryKey()` builder method (`K extends keyof C`).
-  readonly primaryKey: readonly string[];
+  // `PK` is an INDEPENDENT param (a plain string union), NOT `keyof C`: `keyof C` would be
+  // contravariant and make `TableMeta` non-covariant in `C`, breaking `TableDef<concrete>` →
+  // `AnyTable`. Key validity is enforced on the `primaryKey()` builder (`K extends keyof C`); PK is
+  // captured there so the mutator tx can type `update`/`delete` pk args (`PkOf`/`UpdateOf`). The
+  // default `string` erases it (older 2-arg `TableMeta<N, C>` refs still resolve).
+  readonly primaryKey: readonly PK[];
   /** A **local-only** table (`201-LOCAL-ONLY-TABLES-DESIGN.md`): client-authoritative,
    *  never synced/tracked/rebased. The single marker the whole design keys off (§4) — it is
    *  immutable for the table's lifetime (N2) and never crosses the wire (C2). Absent ⇒ an
@@ -49,8 +75,8 @@ export interface TableOptions {
   local?: boolean;
 }
 
-export type TableDef<N extends string, C extends AnyCols> = {
-  readonly [SCHEMA]: TableMeta<N, C>;
+export type TableDef<N extends string, C extends AnyCols, PK extends string = string> = {
+  readonly [SCHEMA]: TableMeta<N, C, PK>;
 } & {
   readonly [K in keyof C]: (arg: Arg<ColT<C[K]>>) => Cond<RowOf<C>>;
 };
@@ -66,28 +92,77 @@ export type AnyTable = TableLike<AnyCols>;
  *  the schema instead of hand-maintaining a parallel twin. */
 export type Row<T extends AnyTable> = RowOf<T[typeof SCHEMA]["columns"]>;
 
+/** Flatten an intersection of mapped types into a single object type (preserving `?`/`readonly`) so
+ *  {@link InsertOf} reads as one clean shape in editor hovers, not `A & B`. */
+type Simplify<T> = { [K in keyof T]: T[K] };
+
+/** True for the top types `unknown`/`any` (`unknown extends any` too), where `[null] extends [T]` is
+ *  vacuously true and so can't tell a `.nullable()` apart. */
+type IsTop<T> = unknown extends T ? true : false;
+
+/** Whether column `X` may be OMITTED from an insert: it admits `null` at the type level — EXCLUDING
+ *  the top types. A bare `json()` is `json<unknown>()`, and `unknown | null` collapses back to
+ *  `unknown`, erasing whether `.nullable()` was applied; treating it as required is the safe
+ *  direction (a `NOT NULL` json column is never wrongly made optional). Declare `json<T>()` to make a
+ *  nullable json column omittable. The runtime companion is `Col.optional` (design 206 §6.2/§7). */
+type InsertOptional<X> = IsTop<ColT<X>> extends true ? false : [null] extends [ColT<X>] ? true : false;
+
+/** The INSERT shape of a column map: {@link RowOf} with every NULLABLE column made OPTIONAL (`?`) —
+ *  it may be omitted and is filled with `null` by both write funnels (design 206 §6.2/§7). `NOT NULL`
+ *  columns stay required. The insert-side twin of {@link RowOf}, mirroring Drizzle's `$inferInsert`
+ *  vs `$inferSelect` split. */
+export type InsertOf<C extends AnyCols> = Simplify<
+  { [K in keyof C as InsertOptional<C[K]> extends true ? never : K]: ColT<C[K]> } & {
+    [K in keyof C as InsertOptional<C[K]> extends true ? K : never]?: ColT<C[K]>;
+  }
+>;
+
+/** The insert type of a table def: `Insert<typeof issue>` → `{ id: string; … assignee?: string | null }`.
+ *  The whole-table ergonomic form of {@link InsertOf} (the insert-side twin of {@link Row}). */
+export type Insert<T extends AnyTable> = InsertOf<T[typeof SCHEMA]["columns"]>;
+
+/** The exact PRIMARY-KEY columns of a table (each typed), required — the identity a `delete`/`row`,
+ *  and the WHERE half of an `update`, take. `PK` is the table's pk-column union (the schema's `__pk`). */
+export type PkOf<C extends AnyCols, PK extends string> = { [K in PK & keyof C]: ColT<C[K & keyof C]> };
+
+/** The UPDATE shape of a table: its {@link PkOf primary-key columns} REQUIRED (they identify the row)
+ *  plus every non-pk column OPTIONAL (`?`) and typed — a nullable one stays `T | null` (settable to
+ *  null), a `NOT NULL` one is `T`. Omitted non-pk columns are left unchanged. */
+export type UpdateOf<C extends AnyCols, PK extends string> = Simplify<
+  PkOf<C, PK> & { [K in Exclude<keyof C, PK>]?: ColT<C[K]> }
+>;
+
+/** The primary-key column union for table `N` of a schema, read from its `__pk` map `P` and narrowed
+ *  to `N`'s actual columns (falling back to all columns when `P` doesn't name `N` — e.g. the loose
+ *  default schema). Feeds {@link PkOf}/{@link UpdateOf} in the typed mutator tx. */
+export type PkColsOf<S extends ColsMap, P extends Record<string, string>, N extends keyof S> = (N extends keyof P
+  ? P[N]
+  : keyof S[N] & string) &
+  keyof S[N] &
+  string;
+
 /** `table("issue").columns({ id: string(), … }).primaryKey("id")`. Pass `{ local: true }` for a
  *  {@link TableMeta.local local-only} table (`201-LOCAL-ONLY-TABLES-DESIGN.md`). */
 export function table<N extends string>(name: N, opts?: TableOptions) {
   return {
     columns<C extends AnyCols>(cols: C) {
       return {
-        primaryKey<K extends keyof C & string>(...keys: K[]): TableDef<N, C> {
-          return makeTableDef<N, C>({ name, columns: cols, primaryKey: keys, local: opts?.local });
+        primaryKey<K extends keyof C & string>(...keys: K[]): TableDef<N, C, K> {
+          return makeTableDef<N, C, K>({ name, columns: cols, primaryKey: keys, local: opts?.local });
         },
       };
     },
   };
 }
 
-function makeTableDef<N extends string, C extends AnyCols>(meta: TableMeta<N, C>): TableDef<N, C> {
+function makeTableDef<N extends string, C extends AnyCols, PK extends string>(meta: TableMeta<N, C, PK>): TableDef<N, C, PK> {
   return new Proxy({} as Record<string | symbol, unknown>, {
     get(_target, prop) {
       if (prop === SCHEMA) return meta;
       if (typeof prop === "string") return (arg: unknown) => fieldCondition(prop, arg);
       return undefined;
     },
-  }) as unknown as TableDef<N, C>;
+  }) as unknown as TableDef<N, C, PK>;
 }
 
 /** Read a table's metadata (columns / PK / name). */
@@ -100,13 +175,25 @@ export type SchemaOf<T extends readonly AnyTable[]> = {
   [E in T[number] as E[typeof SCHEMA]["name"]]: E[typeof SCHEMA]["columns"];
 };
 
+/** name → its primary-key column union, derived from the tables array (the PK captured by the
+ *  `primaryKey(...)` builder). Powers the mutator tx's typed `update`/`delete`/`row` pk args. */
+export type PkMapOf<T extends readonly AnyTable[]> = {
+  [E in T[number] as E[typeof SCHEMA]["name"]]: E[typeof SCHEMA]["primaryKey"][number];
+};
+
 /** name → columns, the resolved schema map carried in the {@link Schema} type. */
 export type ColsMap = Record<string, AnyCols>;
 
-export interface Schema<S extends ColsMap = ColsMap> {
+/** name → (some subset of its column names): the loose shape a {@link Schema}'s pk-map satisfies. The
+ *  fallback when a schema wasn't built through {@link createSchema} — every column could be the pk. */
+export type PkMap<S extends ColsMap> = { [N in keyof S]: keyof S[N] & string };
+
+export interface Schema<S extends ColsMap = ColsMap, P extends Record<string, string> = PkMap<S>> {
   readonly tables: Readonly<Record<string, TableMeta>>;
   /** Phantom carrying name→columns for query-root inference (never read at runtime). */
   readonly __cols: S;
+  /** Phantom carrying name→pk-column-union for the typed mutator tx (never read at runtime). */
+  readonly __pk: P;
 }
 
 /** Table-name prefixes reserved by the engine for SYNTHETIC tables — `__agg_<fnv>` aggregate
@@ -125,13 +212,13 @@ export function isReservedTableName(name: string): boolean {
 
 export function createSchema<const T extends readonly AnyTable[]>(opts: {
   tables: T;
-}): Schema<SchemaOf<T>> {
+}): Schema<SchemaOf<T>, PkMapOf<T>> {
   const tables: Record<string, TableMeta> = {};
   for (const t of opts.tables) {
     const m = t[SCHEMA];
     addTableMeta(tables, m, "createSchema");
   }
-  return { tables } as Schema<SchemaOf<T>>;
+  return { tables } as unknown as Schema<SchemaOf<T>, PkMapOf<T>>;
 }
 
 /** Extend a generated/synced schema with client-authoritative local-only tables.
@@ -141,10 +228,10 @@ export function createSchema<const T extends readonly AnyTable[]>(opts: {
  *  client. The added tables MUST be `table(name, { local: true })`: `extendSchema` deliberately
  *  refuses to append ordinary synced tables, because those need to come from daemon introspection
  *  (`rindle schema gen`) so the server and client cannot drift. */
-export function extendSchema<S extends ColsMap, const T extends readonly AnyTable[]>(
-  base: Schema<S>,
+export function extendSchema<S extends ColsMap, P extends Record<string, string>, const T extends readonly AnyTable[]>(
+  base: Schema<S, P>,
   opts: { tables: T },
-): Schema<S & SchemaOf<T>> {
+): Schema<S & SchemaOf<T>, P & PkMapOf<T>> {
   const tables: Record<string, TableMeta> = { ...base.tables };
   for (const t of opts.tables) {
     const m = t[SCHEMA];
@@ -155,7 +242,7 @@ export function extendSchema<S extends ColsMap, const T extends readonly AnyTabl
     }
     addTableMeta(tables, m, "extendSchema");
   }
-  return { tables } as Schema<S & SchemaOf<T>>;
+  return { tables } as unknown as Schema<S & SchemaOf<T>, P & PkMapOf<T>>;
 }
 
 function addTableMeta(tables: Record<string, TableMeta>, m: TableMeta, caller: "createSchema" | "extendSchema") {
@@ -175,6 +262,118 @@ function addTableMeta(tables: Record<string, TableMeta>, m: TableMeta, caller: "
   tables[m.name] = m;
 }
 
+// ----------------------------- refinement (narrowing generated column types) ---------------------
+//
+// SQL carries a column's KIND (string/number/boolean/json) but not a refinement WITHIN a kind — the
+// element type of `json<T>()`, or a string/number literal union. `refineTable` re-types those
+// columns on a generated `TableDef` (so its field conditions, `rel(...)`s, and `Row<typeof t>` all
+// narrow), and `refineSchema` swaps the refined defs into the generated schema (so query roots and
+// result rows narrow too). Both are runtime-validated IDENTITIES: a refinement narrows the phantom
+// TS type but can never change a column's runtime kind, so the def still matches the daemon's wire
+// schema exactly. Keep refinements in a hand-written module (beside `extendSchema`'s local tables);
+// `schema.gen.ts` stays a pure, wholesale-regenerated artifact.
+
+/** Per-column narrowings for {@link refineTable}: each entry must keep the column's kind and narrow
+ *  its TS type (`Col<T2>` with `T2 extends T`) — `json<Meta>()` on a json column, a literal-union
+ *  `string<"a" | "b">()` on a string column. Kind changes are rejected (cross-kind at compile time,
+ *  same-phantom kind flips like `string()` on a json column at runtime). */
+export type ColRefinements<C extends AnyCols> = {
+  readonly [K in keyof C]?: Col<ColT<C[K]>>;
+};
+
+/** `C` with the columns named in `R` re-typed to their refined `Col`s. */
+export type RefinedCols<C extends AnyCols, R extends ColRefinements<C>> = {
+  [K in keyof C]: K extends keyof R ? (R[K] extends Col<unknown> ? R[K] : C[K]) : C[K];
+};
+
+/** Narrow a generated table's column TYPES without touching its runtime shape.
+ *
+ *  Returns the SAME def, re-typed (identity, after validating that every refined column exists and
+ *  keeps its kind) — so conditions built from it, `rel(...)`s anchored on it, and `Row<typeof t>`
+ *  all see the narrowed types. Pass the result to {@link refineSchema} so query roots narrow too. */
+export function refineTable<N extends string, C extends AnyCols, R extends ColRefinements<C>>(
+  base: TableDef<N, C>,
+  cols: R,
+): TableDef<N, RefinedCols<C, R>> {
+  const meta = base[SCHEMA];
+  for (const [name, col] of Object.entries(cols) as [string, Col<unknown> | undefined][]) {
+    if (col === undefined) continue;
+    const baseCol = meta.columns[name];
+    if (baseCol === undefined) {
+      throw new Error(`refineTable: table "${meta.name}" has no column "${name}".`);
+    }
+    if (col.type !== baseCol.type) {
+      throw new Error(
+        `refineTable: column "${meta.name}.${name}" is ${baseCol.type}, not ${col.type} — a refinement ` +
+          `may only narrow the TS type WITHIN a column's kind, never change the kind itself.`,
+      );
+    }
+  }
+  return base as unknown as TableDef<N, RefinedCols<C, R>>;
+}
+
+/** A table def acceptable to {@link refineSchema} over `Schema<S>`: its NAME must be one of `S`'s
+ *  tables (a def for an unknown table is a compile error at the call site). */
+export type RefinableTable<S extends ColsMap> = {
+  readonly [SCHEMA]: TableMeta<Extract<keyof S, string>, AnyCols>;
+};
+
+/** `S` with each table named in `T` re-typed to that def's (refined) columns. (The inner
+ *  `extends AnyCols` guard is how the checker proves the remapped `SchemaOf<T>[K]` is a column
+ *  map while `T` is still generic; it always holds for a concrete `T`.) */
+export type RefinedColsMap<S extends ColsMap, T extends readonly AnyTable[]> = {
+  [K in keyof S]: K extends keyof SchemaOf<T> ? (SchemaOf<T>[K] extends AnyCols ? SchemaOf<T>[K] : S[K]) : S[K];
+};
+
+/** Swap {@link refineTable}-narrowed table defs into a generated schema, re-typing those tables for
+ *  everything downstream of the schema (`newQueryBuilder`/`queries` roots, store row types).
+ *
+ *  Runtime-validated identity: each def must name a table already in the schema and match its
+ *  runtime shape exactly (same columns, kinds, primary key, and locality) — refinement narrows TS
+ *  types, never what's on the wire. Composes with {@link extendSchema} in either order. */
+export function refineSchema<S extends ColsMap, P extends Record<string, string>, const T extends readonly RefinableTable<S>[]>(
+  base: Schema<S, P>,
+  opts: { tables: T },
+): Schema<RefinedColsMap<S, T>, P> {
+  const seen = new Set<string>();
+  for (const t of opts.tables) {
+    const m = t[SCHEMA];
+    const baseMeta = base.tables[m.name];
+    if (baseMeta === undefined) {
+      throw new Error(
+        `refineSchema: schema has no table "${m.name}" — refinement re-types existing tables only ` +
+          `(add local-only tables with extendSchema).`,
+      );
+    }
+    if (seen.has(m.name)) {
+      throw new Error(`refineSchema: table "${m.name}" is refined twice.`);
+    }
+    seen.add(m.name);
+    assertRefinementMatches(m, baseMeta);
+  }
+  return base as unknown as Schema<RefinedColsMap<S, T>, P>;
+}
+
+/** The refined def must be the same table the schema already carries — identical column set, kinds,
+ *  primary key, and locality — so swapping its TYPE in cannot change any runtime behavior. */
+function assertRefinementMatches(m: TableMeta, baseMeta: TableMeta): void {
+  const cols = Object.keys(m.columns);
+  const baseCols = Object.keys(baseMeta.columns);
+  const matches =
+    cols.length === baseCols.length &&
+    cols.every((c) => baseMeta.columns[c] !== undefined && m.columns[c].type === baseMeta.columns[c].type) &&
+    m.primaryKey.length === baseMeta.primaryKey.length &&
+    m.primaryKey.every((k, i) => baseMeta.primaryKey[i] === k) &&
+    (m.local === true) === (baseMeta.local === true);
+  if (!matches) {
+    throw new Error(
+      `refineSchema: table "${m.name}" does not match the schema's table of that name — pass the ` +
+        `output of refineTable over the SAME generated def (identical columns, kinds, primary key, ` +
+        `and locality).`,
+    );
+  }
+}
+
 /** Whether `table` is a {@link TableMeta.local local-only} table in `schema` (an unknown table
  *  reads as non-local). The single locality predicate the backends key off. */
 export function isLocalTable<S extends ColsMap>(schema: Schema<S>, table: string): boolean {
@@ -247,6 +446,43 @@ export function tableSpec(meta: TableMeta): { columns: string[]; primaryKey: num
   return { columns, primaryKey };
 }
 
+/** A table's insert-completeness plan, derived once from its `Col` markers and shared by BOTH write
+ *  funnels — the client `trackingTx` and the server `renderOp` — so their required-sets can't drift
+ *  (design 206 §6.1/§6.2). A `NOT NULL` column is `required`; a nullable column (`.nullable()` set
+ *  `Col.optional`) may be omitted and is filled with `null` (see {@link insertCell}). PK columns are
+ *  never nullable (introspection forces them non-null), so they are always required. */
+export interface InsertPlan {
+  /** Every column, in wire order. */
+  readonly columns: string[];
+  /** Columns that MUST be present on a full insert — the non-nullable ones. */
+  readonly required: string[];
+  /** The nullable (omittable-to-null) columns, for a fast membership test in the fill. */
+  readonly nullable: ReadonlySet<string>;
+}
+
+/** Derive a table's {@link InsertPlan} from its column markers. */
+export function insertPlan(meta: TableMeta): InsertPlan {
+  const columns = Object.keys(meta.columns);
+  const nullable = new Set(columns.filter((c) => meta.columns[c].optional === true));
+  return { columns, required: columns.filter((c) => !nullable.has(c)), nullable };
+}
+
+/** The cell a full insert writes for column `c`: the given value, or `null` when a nullable column
+ *  is omitted (design 206 §6.2). The caller's completeness check ({@link InsertPlan.required})
+ *  guarantees a non-nullable column is present, so its omission never reaches here. */
+export function insertCell(row: Record<string, WireValue>, c: string): WireValue {
+  return c in row ? row[c] : null;
+}
+
+/** Encode a keyed-row cell to its wire {@link WireValue} for a column KIND — the one place both write
+ *  funnels stringify a `json<T>` object (the typed mutator surface / design 206 §7). An
+ *  already-stringified json value (a `string`) or any non-json cell passes through unchanged, so a
+ *  mutator may pass EITHER a parsed object OR a JSON string. Mirrors `store.positionalize`. */
+export function toCell(v: WireValue | object, type: ColType): WireValue {
+  if (type === "json" && v !== null && typeof v === "object") return JSON.stringify(v);
+  return v as WireValue;
+}
+
 /** The client's per-table flat schema (name + column order + PK indices), the shape a
  *  normalized `hello` advertises (NORMALIZED-CHANGES-DESIGN.md §3). Used to validate a
  *  server hello against the CLIENT's own typed schema so a column-order / PK skew is caught