feat!: object sync-schema — defineSync, closed mutation trio, typed commands (ADR-0014)

[grrowl]

Pre-1.0 breaking change. Replaces the SyncRegistry builder with an object schema, makes commands typed end to end, and adds a multi-DO example. Off main, ahead of the SSR branch.

What changed

Authoring (src/server/registry.ts). new SyncRegistry().defineCollection().defineMutation().defineCommand() → defineSync<User, Env>() → { collection, command, schema }:

const sync = defineSync<Claims, Env>()
export const schema = sync.schema({
  collections: {
    messages: sync.collection<Message>({
      pk: "id",
      mutations: { insert: { authorize, execute }, update: { execute }, delete: { execute } },
    }),
  },
  commands: { clearRoom: sync.command()(({ sql }) => ({ deleted: clearAll(sql) })) },
})
export type Api = typeof schema

• Closed mutation trio. mutations is exactly insert?/update?/delete? — a custom type is structurally unrepresentable (mirrors @tanstack/db's onInsert/onUpdate/onDelete). Supersedes ADR-0001 D11; absorbs ADR-0010's row manifest (the row type lives on the collection, not a third generic).
• Typed commands, end to end. type Api = typeof schema is the whole client contract: new WebSocketTransport<Api>() → typed transport.call.<cmd>(args) proxy + typed sendCall(name, args) (txId via crypto.randomUUID()); doCollectionOptions<Api, "table"> infers the row type.
• Optional Standard Schema slot. zod/valibot/arktype (no validator dependency); validates insert cols + command args at runtime as a gate — the original value flows to handlers, no transforms/defaults applied (see recipes/zod-standard-schema-collections.md).

Runtime dispatch / wire / CDC semantics are unchanged — registerSync compiles the schema value into the same dispatch tables, so the suite passes as-is.

New example: examples/multi-do

Two separate DOs behind one Worker, one transport per DO, a React SyncProvider/useSync keyed by DO so command namespaces never collide, and a client-side cross-DO feed (the DO never joins — ADR-0001).

Commits

1. feat(registry)!: library core + tests + ADR-0014 + CHANGELOG
2. refactor(examples): migrate chat/board/on-demand
3. feat(examples): multi-DO showcase
4. docs: the recipes/ Standard Schema guide

Verification

• tsc --noEmit: 0 errors (src + tests).
• vitest run: 171/171 across 41 files (was 172; one test dropped — "define same collection twice" is now structurally unrepresentable, guard kept defensively, documented in the test + ADR).
• Codex adversarial pass found two issues, both addressed: a commandless schema let transport.call.anything() type-check (fixed via schema overload, proven with a @ts-expect-error probe); Standard Schema discarded the parsed value (resolved as a documented validation gate).
• Example client .tsx files retain pre-existing @tanstack/db dual-copy tsc noise (unrelated to this change).

🤖 Generated with Claude Code