feat(server)!: typed mutations via collection manifest; rename Registry→SyncRegistry (ADR-0010)

SyncRegistry takes a third generic — a collection-row manifest (table → row
type) — so mutation handlers are fully typed with no casts:

  new SyncRegistry<Claims, Env, { messages: Message }>()
    .defineCollection({ table: "messages", pk: "id" })   // pk ∈ keyof Message
    .defineMutation({ collection: "messages", type: "insert",
                      execute: ({ op }) => op.cols.author })  // Message

op.cols is discriminated per op (insert→Row, update→Partial<Row>, delete→none);
pk and the collection name are checked against the manifest. Purely type-level —
runtime dispatch is unchanged (the typed def is erased into the stored MutationDef
at one isolated boundary), so the 139 runtime tests are untouched; correctness is
pinned by type-level tests (tests/registry-types.ts: tsc expect-pass + @ts-expect-error).
The manifest defaults so the untyped `new SyncRegistry<Claims>()` still compiles
(op.cols falls back to unknown). The TS partial-inference wall (can't specify the
row type while inferring the table literal) is why the type lives on the
constructor, not the method — see ADR-0010.

BREAKING: `Registry` is renamed `SyncRegistry` (no compat shim) — the old name
was generic/clashy and the public surface is uniformly Sync* (SyncDurableObject,
runSyncedWrite, registerSync). Update imports and `new SyncRegistry(...)`.

Commands (defineCommand args) deferred to a follow-up.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: grrowl

CHANGELOG.md

@@ -10,6 +10,12 @@ While pre-1.0, the public API may change between 0.x releases.
 
 ### Added
 
+- **Typed mutations** (ADR-0010). `SyncRegistry` takes a third generic — a
+  collection-row manifest — so handlers are fully typed without casts:
+  `new SyncRegistry<TUser, Env, { messages: Message }>()` types `pk` (must be a
+  column) and each handler's `op.cols` per op (`insert`→`Message`,
+  `update`→`Partial<Message>`, `delete`→none). Purely type-level; the untyped
+  two-generic form still works (`op.cols` falls back to `unknown`).
 - **Changelog time-based retention** (ADR-0009). A new `changelogRetentionMs`
   knob (default 2 days) prunes `_sync_changes` rows older than the window, so the
   log is bounded by age, not just key-cardinality. A client reconnecting from
@@ -19,6 +25,10 @@ While pre-1.0, the public API may change between 0.x releases.
 
 ### Changed
 
+- **Renamed `Registry` → `SyncRegistry`.** Breaking, no compat shim. The old
+  name was too generic and clashy; the public surface is uniformly `Sync*`
+  (`SyncDurableObject`, `runSyncedWrite`, `registerSync`). Update your import and
+  `new SyncRegistry(...)`.
 - `registerSync` now reconciles CDC triggers to the registry instead of only
   adding them: triggers for a collection you've removed from the registry are
   dropped on the next `registerSync`, so an orphaned table stops firing capture

README.md

@@ -81,7 +81,7 @@ the milestone sequence.
 ### 1. Define your Durable Object
 
 ```ts
-import { Registry, SyncDurableObject } from "tanstack-do-db-collection"
+import { SyncRegistry, SyncDurableObject } from "tanstack-do-db-collection"
 
 interface Claims { userId: string }
 interface Message { id: string; author: string; content: string; created_at: number }
@@ -102,20 +102,23 @@ export class SessionDO extends SyncDurableObject<Env, Claims> {
       )`)
 
       this.registerSync(
-        new Registry<Claims>()
+        // The third generic is the collection manifest: table → row type. It
+        // types `pk` (must be a column) and every handler's `op` — no casts.
+        new SyncRegistry<Claims, Env, { messages: Message }>()
           .defineCollection({ table: "messages", pk: "id" })
           .defineMutation({
             collection: "messages",
             type: "insert",
             // authorize runs BEFORE the tx (async ok); throw to deny.
+            // op.cols is typed Message here — no cast.
             authorize: ({ user, op }) => {
-              if ((op.cols as Message).author !== user.userId) {
+              if (op.cols.author !== user.userId) {
                 throw new Error("author mismatch")
               }
             },
             // execute runs INSIDE transactionSync — synchronous only.
             execute: ({ op, sql }) => {
-              const m = op.cols as Message
+              const m = op.cols // Message
               sql.exec(
                 "INSERT INTO messages(id, author, content, created_at) VALUES (?, ?, ?, ?)",
                 m.id, m.author, m.content, m.created_at,
@@ -124,7 +127,7 @@ export class SessionDO extends SyncDurableObject<Env, Claims> {
             // afterCommit (optional): fire-and-forget AFTER the commit + receipt —
             // the home for external side effects execute can't do (delete an R2
             // object, enqueue a job). Receives `env`; owns its own idempotency.
-            // afterCommit: async ({ op, env }) => { await env.BUCKET.delete(op.key as string) },
+            // afterCommit: async ({ op, env }) => { await env.BUCKET.delete(op.key) },
           }),
       )
     })

docs/adr/0010-typed-mutations-collection-manifest.md

@@ -0,0 +1,138 @@
+# 0010 — Typed mutations via a collection-row manifest on `SyncRegistry`
+
+**Status:** Accepted. Types the mutation-handler surface introduced by
+[ADR-0007](./0007-author-owned-schema-register-sync.md). Commands
+(`defineCommand`) are explicitly out of scope (a follow-up).
+
+## Context
+
+A mutation handler receives `op.cols` as `Record<string, unknown>` — the wire
+type (`MutOp`, `frames.ts`). So every handler casts: `op.cols as Message`. That
+is repetitive, and it is *a lie to the compiler* — an unchecked assertion with
+no runtime backing. We want `op` typed by the collection's row type **and** the
+op kind:
+
+- `insert` → `cols: Row` (the full row, ADR-0001 D19)
+- `update` → `cols: Partial<Row>` (top-level patch, ADR-0002 C6)
+- `delete` → no `cols` (just `key`)
+
+This is **purely a type-level concern**: runtime dispatch is string-keyed and
+untyped (`mutations.get(\`${collection}:${op.type}\`).execute({ op, … })`), and
+the row type has no runtime presence. So the change touches signatures only —
+zero runtime behaviour change — and is verified by type-level tests.
+
+### The constraint that decided the shape
+
+The natural idea — `.defineCollection<Message>({ table: "messages", pk: "id" })`,
+accumulating `{ messages: Message }` so mutations infer the row from the
+collection name — **cannot compile**, for two converging reasons (both verified
+against `tsc --strict`, see below):
+
+1. **TypeScript has no partial type-argument inference**
+   ([microsoft/TypeScript#26242](https://github.com/microsoft/TypeScript/issues/26242)).
+   The moment you write an explicit `<Message>`, TS stops inferring the other
+   type params, so the table-name literal can't be captured.
+2. **The row type has no runtime witness** in `{ table, pk }` — nothing to infer
+   it *from* — so it must be an explicit annotation somewhere; which trips (1).
+
+A wall probe confirmed it: with `defineCollection<Row, Table extends string = string>`,
+calling `<Message>(…)` widens `Table` to `string`, yielding `Record<string, Message>`
+— collections become indistinguishable.
+
+So the only question is **where the one explicit row annotation lives.** Three
+homes compile (all verified); a fourth (schema) was rejected.
+
+## Options (all compile-tested)
+
+- **A — per mutation:** `.defineMutation<Message>({ collection, type, execute })`,
+  the arg a discriminated union keyed on `type` (so no second inference is
+  needed; `cols` is precise per op). Clean single `<>`, co-located with the
+  handler. **But:** the row type is repeated on every mutation, and nothing ties
+  `collection: "messages"` to `Message` (same trust as `as`, just centralised).
+- **B1 — per collection (curry):** `.defineCollection<Message>()({ table, pk })`.
+  Declared once, co-located, links collection→row, and enforces *define-before-
+  mutate* at compile time. **But:** the `()()` curry on every collection.
+- **B2 — constructor manifest:** `new SyncRegistry<TUser, Env, { messages: Message }>()`,
+  then plain `.defineCollection`/`.defineMutation` with everything inferred. **The
+  only option that types *both* call sites** — `pk` against `keyof Row` and the
+  table/collection names against the manifest, *and* `op.cols` per op — with no
+  curry. **Cost:** the manifest sits apart from the `.defineCollection` calls
+  (TS checks they agree), and you specify `Env` to reach the third slot.
+- **B3 — schema-driven (rejected):** `.defineCollection({ table, pk, schema })`
+  infers `Row` from a [Standard Schema](https://standardschema.dev/) value *and*
+  validates inbound `cols` at runtime. Rejected: it adds no real **safety** — SQL
+  injection is already prevented by parameterised binding (values are never
+  interpolated; identifiers are validated at registration, ADR-0007), and
+  malformed input is already rejectable in `authorize` — while taxing the
+  **write hot path** with a per-mutation validator, against the light/streaming
+  ethos. Input validation, where wanted, belongs in `authorize`.
+
+## Decision
+
+**B2 — the constructor manifest.**
+
+```ts
+class SyncRegistry<TUser = unknown, Env = unknown,
+               TCols extends Record<string, unknown> = Record<string, unknown>> {
+  defineCollection<Name extends keyof TCols & string>(
+    def: { table: Name; pk: PkOf<TCols[Name]> },
+  ): this
+  defineMutation<Name extends keyof TCols & string, T extends RowOp>(
+    def: {
+      collection: Name
+      type: T
+      authorize?:  (ctx: MutationCtx<TUser, Env, OpFor<T, TCols[Name]>>) => void | Promise<void>
+      execute:     (ctx: MutationCtx<TUser, Env, OpFor<T, TCols[Name]>>) => void
+      afterCommit?: (ctx: MutationCtx<TUser, Env, OpFor<T, TCols[Name]>>) => unknown
+    },
+  ): this
+}
+type OpFor<T extends RowOp, Row> =
+  T extends "insert" ? { type: "insert"; key: string; cols: Row }
+  : T extends "update" ? { type: "update"; key: string; cols: Partial<Row> }
+  : { type: "delete"; key: string; cols?: undefined }
+// PkOf<Row> = [keyof Row] extends [never] ? string : keyof Row & string
+```
+
+- **Non-breaking for the untyped path.** `TCols` defaults to
+  `Record<string, unknown>`, so `new SyncRegistry<Claims>()` still compiles; an
+  unannotated collection falls back to `cols: unknown` (the author casts, as
+  today). `PkOf` degrades to `string` when the row is unknown.
+- **Zero runtime change.** The `collections`/`mutations` Maps stay string-keyed;
+  the generic builder casts the typed def into the erased stored
+  `MutationDef` at the storage boundary (one deliberate, isolated `as`).
+  `MutationCtx` gains a third type param `TOp = MutOp` (default preserves
+  existing internal call sites). Dispatch is untouched.
+
+**Why B2 over A and B1.** Over **A**: A re-states the row type per mutation and
+can't check collection↔row; B2 declares it once and types both sides. Over
+**B1**: B1's co-location is nice but forces `()()` on every collection; B2 has no
+curry, and the manifest-apart-from-calls gap is itself type-checked
+(`table extends keyof TCols`). The deciding vote was the `()()` ergonomics
+against B2's single up-front declaration.
+
+## Verification
+
+The four ideas were compiled under `tsc --noEmit --strict` before deciding:
+A and B2 type-check with precise per-op `cols` (insert `Row`, update
+`Partial<Row>`, delete no `cols`); a generic *on `execute`* fails (the param is
+caller-chosen and opaque in the body); the accumulating `defineCollection<Row>`
+widens the table to `string`. These become permanent **type-level tests**
+(`tsc` expect-pass + `@ts-expect-error` expect-fail) alongside the unchanged
+runtime suite.
+
+## Consequences
+
+- Authors declare row types once (the manifest); handlers get precise
+  `op.cols`/`op.key`; the `as Message` casts disappear — including the ones in
+  the README quick-start (added during the README pass as a stopgap).
+- The untyped path is unchanged at runtime and only mildly narrower at compile
+  time (`cols: unknown` vs `Record<string, unknown>`); our own call sites cast,
+  so nothing breaks.
+- Type-level tests join the suite — a new category for this repo.
+
+## Out of scope
+
+- **Typed command `args`** (`defineCommand`). Commands are a different shape
+  (free-form args, not a collection row), and their API status warrants its own
+  review. Deferred to a follow-up.

docs/adr/README.md

@@ -17,3 +17,4 @@ explains the displacement.
 | [0007](./0007-author-owned-schema-register-sync.md) | Author-owned schema; `registerSync` wires the sync | Accepted |
 | [0008](./0008-orphaned-cdc-triggers.md) | Orphaned CDC triggers when a collection is removed | Accepted |
 | [0009](./0009-changelog-time-retention.md) | Changelog time-based retention; reset stale reconnects | Accepted |
+| [0010](./0010-typed-mutations-collection-manifest.md) | Typed mutations via a collection-row manifest on `SyncRegistry` | Accepted |

examples/board/src/worker.ts

@@ -11,7 +11,7 @@
 // `/bump` is a server-side load generator — it mutates random tasks (likely cold
 // ones the caller never loaded) and broadcasts, so the OTHER tab sees move-in.
 
-import { Registry, SyncDurableObject } from "../../../src/server/index.ts"
+import { SyncRegistry, SyncDurableObject } from "../../../src/server/index.ts"
 
 interface Env {
   BOARD_DO: DurableObjectNamespace
@@ -35,7 +35,7 @@ export class BoardDO extends SyncDurableObject<Env, Claims> {
         updated_at INTEGER NOT NULL
       )`)
       this.registerSync(
-        new Registry<Claims>()
+        new SyncRegistry<Claims>()
           .defineCollection({ table: "tasks", pk: "id" })
           .defineMutation({
             collection: "tasks",

examples/chat/src/worker.ts

@@ -4,7 +4,7 @@
 // the real code with no build step for the lib. A published consumer would
 // instead `import { ... } from "tanstack-do-db-collection"`.
 
-import { Registry, SyncDurableObject } from "../../../src/server/index.ts"
+import { SyncRegistry, SyncDurableObject } from "../../../src/server/index.ts"
 
 interface Env {
   SESSION_DO: DurableObjectNamespace
@@ -27,7 +27,7 @@ export class SessionDO extends SyncDurableObject<Env, Claims> {
         created_at INTEGER NOT NULL
       )`)
       this.registerSync(
-        new Registry<Claims>()
+        new SyncRegistry<Claims>()
           .defineCollection({ table: "messages", pk: "id" })
           .defineMutation({
             collection: "messages",

examples/on-demand/src/worker.ts

@@ -2,7 +2,7 @@
 // A GET /seed?room=… endpoint inserts fixed rows so subsets have pre-existing
 // data to load (demonstrating loadSubset fetching, not just live inserts).
 
-import { Registry, SyncDurableObject } from "../../../src/server/index.ts"
+import { SyncRegistry, SyncDurableObject } from "../../../src/server/index.ts"
 
 interface Env {
   ITEMS_DO: DurableObjectNamespace
@@ -30,7 +30,7 @@ export class ItemsDO extends SyncDurableObject<Env, Claims> {
         created_at INTEGER NOT NULL
       )`)
       this.registerSync(
-        new Registry<Claims>()
+        new SyncRegistry<Claims>()
           .defineCollection({ table: "items", pk: "id" })
           .defineMutation({
             collection: "items",

src/server/changes.ts

@@ -52,7 +52,7 @@ export function initSchema(sql: SqlStorage): void {
 /**
  * Install AFTER INSERT/UPDATE/DELETE triggers copying change events into
  * `_sync_changes`. Idempotent. `tbl`/`pk` MUST be validated identifiers
- * (the Registry enforces this) — they are interpolated into DDL.
+ * (the SyncRegistry enforces this) — they are interpolated into DDL.
  *
  * Each statement is passed whole: splitting on `;` would sever the inner
  * `INSERT ...;` from its `END`.
@@ -235,7 +235,7 @@ export function snapshotAll(sql: SqlStorage, tbl: string): Array<Record<string,
 }
 
 /** Current rows for a set of keys, for hydrating deltas. `tbl`/`pk` are
- *  validated identifiers (the Registry enforces this). */
+ *  validated identifiers (the SyncRegistry enforces this). */
 export function hydrateRows(
   sql: SqlStorage,
   tbl: string,

src/server/index.ts

@@ -4,14 +4,15 @@
 // diffs. Imports the workerd runtime (`cloudflare:workers`); not for browsers.
 //
 //   - SyncDurableObject: hibernating-WebSocket base class.
-//   - Registry: defineCollection / defineMutation / defineCommand.
+//   - SyncRegistry: defineCollection / defineMutation / defineCommand.
 
-export { Registry } from "./registry.ts"
+export { SyncRegistry } from "./registry.ts"
 export type {
   CollectionDef,
   CommandCtx,
   CommandDef,
   MutationCtx,
+  OpFor,
   MutationDef,
 } from "./registry.ts"
 export { SyncDurableObject } from "./sync-do.ts"