@rindle/client 0.4.2 → 0.4.4

package/src/mutation-ops.ts

@@ -4,6 +4,8 @@
 // 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
@@ -49,9 +51,13 @@ export interface ServerWriteTx {
 // 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 `yield tx.row(...)` is the one thing that
-// suspends, evaluating to the read row. `yield tx.all([...])` fans reads out (Promise.all on the
-// server, in-order on the client) — order-preserving on both tiers, so the body stays deterministic.
+// 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
@@ -64,34 +70,68 @@ export type ReadEffect = { kind: "row"; table: string; pk: KeyedRow };
  *  to `(KeyedRow | undefined)[]` at runtime (cast it — the generator's single next-type is a row). */
 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 const isoTx: IsoTx = {
-  insert: (table, row) => ({ kind: "insert", table, row }),
-  update: (table, row) => ({ kind: "update", table, row }),
-  upsert: (table, row) => ({ kind: "upsert", table, row }),
-  insertIgnore: (table, row) => ({ kind: "insertIgnore", table, row }),
-  delete: (table, pk) => ({ kind: "delete", table, pk }),
-  row: (table, pk) => ({ kind: "row", table, pk }),
-  all: (effects) => ({ kind: "all", effects }),
-};
+  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
@@ -142,6 +182,34 @@ export function shared<Args, Ctx extends MutatorCtx = MutatorCtx>(
   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 {
@@ -156,13 +224,16 @@ export function isGeneratorMutator(fn: unknown): fn is (...args: never[]) => Mut
 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 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;
@@ -174,14 +245,17 @@ export function driveMutationSync(gen: MutationGen, exec: SyncEffectExec): void
 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 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;

package/src/schema.ts

@@ -8,13 +8,19 @@
 
 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
  *  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. */
+ *  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;
@@ -24,13 +30,18 @@ export type RowOf<C extends AnyCols> = { [K in keyof C]: ColT<C[K]> };
 /** 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 (design 206 Phase 2) it may be omitted from an insert. `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. */
+ *  `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): ColBuilder<T> => ({ type, nullable: () => makeCol<T | null>(type) });
+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");
@@ -40,30 +51,41 @@ 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
-   *  ordinary synced table. */
-  readonly local?: boolean;
+   *  ordinary synced table.
+   *
+   *  `true` ⇒ eligible for the local-persistence plane (durable + cross-tab when the client
+   *  enables `persistLocal`, `207-LOCAL-TABLE-PERSISTENCE-DESIGN.md`). `"session"` ⇒ local but
+   *  EPHEMERAL: outside the plane entirely — never persisted, never replicated across tabs,
+   *  per-client-instance state that empties on reload (201's original behavior) even when
+   *  `persistLocal` is on. Every OTHER locality rule (untracked source, M1/M2 guards, E3/Q1
+   *  wire exclusion) treats both variants identically. */
+  readonly local?: boolean | "session";
 }
 
 /** Options for {@link table}. */
 export interface TableOptions {
   /** Declare a {@link TableMeta.local local-only} table (selection state, draft text, view
    *  prefs, scratch rows): client-authoritative, never synced or rebased. See
-   *  `201-LOCAL-ONLY-TABLES-DESIGN.md`. */
-  local?: boolean;
+   *  `201-LOCAL-ONLY-TABLES-DESIGN.md`. Pass `"session"` for a local table that must stay
+   *  EPHEMERAL and per-tab even when the client enables `persistLocal` — e.g. selection state
+   *  that should not follow the user across tabs or reloads (207 §5.4). */
+  local?: boolean | "session";
 }
 
-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>>;
 };
@@ -79,28 +101,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). */
@@ -113,13 +184,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
@@ -138,13 +221,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.
@@ -154,21 +237,21 @@ 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];
-    if (m.local !== true) {
+    if (!m.local) {
       throw new Error(
         `extendSchema: table "${m.name}" is not local-only — synced tables must be generated from the daemon schema.`,
       );
     }
     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") {
@@ -257,10 +340,10 @@ export type RefinedColsMap<S extends ColsMap, T extends readonly AnyTable[]> = {
  *  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, const T extends readonly RefinableTable<S>[]>(
-  base: Schema<S>,
+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>> {
+): Schema<RefinedColsMap<S, T>, P> {
   const seen = new Set<string>();
   for (const t of opts.tables) {
     const m = t[SCHEMA];
@@ -277,7 +360,7 @@ export function refineSchema<S extends ColsMap, const T extends readonly Refinab
     seen.add(m.name);
     assertRefinementMatches(m, baseMeta);
   }
-  return base as unknown as Schema<RefinedColsMap<S, T>>;
+  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,
@@ -290,7 +373,9 @@ function assertRefinementMatches(m: TableMeta, baseMeta: TableMeta): void {
     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);
+    // Locality must match EXACTLY, including the persisted-vs-session variant (a refinement
+    // flipping `true` ↔ `"session"` would silently change the table's durability).
+    (m.local ?? false) === (baseMeta.local ?? false);
   if (!matches) {
     throw new Error(
       `refineSchema: table "${m.name}" does not match the schema's table of that name — pass the ` +
@@ -301,16 +386,46 @@ function assertRefinementMatches(m: TableMeta, baseMeta: TableMeta): void {
 }
 
 /** 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. */
+ *  reads as non-local). The single locality predicate the backends key off. BOTH variants —
+ *  `true` and `"session"` — are local here; the persisted/ephemeral split matters only to the
+ *  persistence plane ({@link persistedLocalTableNames}). */
 export function isLocalTable<S extends ColsMap>(schema: Schema<S>, table: string): boolean {
-  return schema.tables[table]?.local === true;
+  return Boolean(schema.tables[table]?.local);
 }
 
-/** The set of local-only table names in `schema` (`201-LOCAL-ONLY-TABLES-DESIGN.md` §4). */
+/** The set of local-only table names in `schema` (`201-LOCAL-ONLY-TABLES-DESIGN.md` §4) — BOTH
+ *  variants (`true` and `"session"`); every locality rule except persistence keys off this set. */
 export function localTableNames<S extends ColsMap>(schema: Schema<S>): Set<string> {
   return new Set(Object.keys(schema.tables).filter((n) => schema.tables[n].local));
 }
 
+/** The subset of {@link localTableNames} eligible for the persistence plane — `local: true` only.
+ *  A `local: "session"` table stays outside it: never persisted, never replicated across tabs
+ *  (`207-LOCAL-TABLE-PERSISTENCE-DESIGN.md` §5.4). */
+export function persistedLocalTableNames<S extends ColsMap>(schema: Schema<S>): Set<string> {
+  return new Set(Object.keys(schema.tables).filter((n) => schema.tables[n].local === true));
+}
+
+/** A stable fingerprint of the schema's PERSISTED local tables only — the persistence gate's
+ *  `schemaHash` (`207-LOCAL-TABLE-PERSISTENCE-DESIGN.md` §3.3 / P7). Per `local: true` table:
+ *  `(name, ordered column names + types + optionality, pk columns)`. Column order is kept (rows are
+ *  positional); tables are sorted by name so registration order can't skew it; synced-table AND
+ *  `local: "session"` changes never move it (reshaping an ephemeral table must not wipe durable
+ *  data). The value is the canonical descriptor itself, not a digest — local-table sets are tiny,
+ *  and exactness (no collision can ever skip a P7 clear) beats compactness here. */
+export function localSchemaHash<S extends ColsMap>(schema: Schema<S>): string {
+  // Derived from persistedLocalTableNames — the hash's contract is "fingerprints exactly the
+  // tables the plane persists", so the two must share one predicate, not two copies of it.
+  const tables = [...persistedLocalTableNames(schema)]
+    .sort()
+    .map((n) => {
+      const meta = schema.tables[n];
+      const cols = Object.keys(meta.columns).map((c) => [c, meta.columns[c].type, meta.columns[c].optional === true]);
+      return [n, cols, meta.primaryKey];
+    });
+  return `v1:${JSON.stringify(tables)}`;
+}
+
 // ----------------------------- relationships (FRAGMENT-COMPOSITION-DESIGN §4.2, named edges) -----
 //
 // A relationship is the correlation (`parent.col → child.col`) declared ONCE as a value, so `sub`,
@@ -372,6 +487,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