cvx-kit 0.1.2 → 0.1.4

package/docs/auth.md

@@ -12,30 +12,52 @@ host. The kit provides the structure; the app provides the policy.
 // convex/functions.ts (the single place constructors are built)
 import { createAuthFunctions, defaultRoleMap } from 'cvx-kit/auth'
 import {
-  action, internalAction, internalMutation, internalQuery, mutation, query,
+	action,
+	internalAction,
+	internalMutation,
+	internalQuery,
+	mutation,
+	query,
 } from './_generated/server'
 import type { DataModel } from './_generated/dataModel'
 import { triggers } from './triggers'
 import { authKit } from './auth'
 
 export const {
-  authQuery, authMutation, authAction,
-  roleQuery, roleMutation, roleAction,
-  adminQuery, adminMutation, adminAction,
-  systemQuery, systemMutation, systemAction,
-  include, authenticatedUser,
+	authQuery,
+	authMutation,
+	authAction,
+	roleQuery,
+	roleMutation,
+	roleAction,
+	adminQuery,
+	adminMutation,
+	adminAction,
+	systemQuery,
+	systemMutation,
+	systemAction,
+	include,
+	authenticatedUser,
 } = createAuthFunctions<DataModel>({
-  query, mutation, action, internalQuery, internalMutation, internalAction,
-  getAuthUser: (ctx) => authKit.getAuthUser(ctx),
-  mapRole: defaultRoleMap,          // or your own vocabulary (see below)
-  adminRoles: ['admin'],
-  triggers,                          // every mutation write runs through wrapDB
-  verifyMembership: async ({ userId, organizationId }) => {
-    const memberships = await authKit.workos.userManagement
-      .listOrganizationMemberships({ organizationId, userId, statuses: ['active'] })
-    const m = memberships.data.find((c) => c.userId === userId)
-    return m ? { organizationId: m.organizationId, roleSlug: m.role.slug } : null
-  },
+	query,
+	mutation,
+	action,
+	internalQuery,
+	internalMutation,
+	internalAction,
+	getAuthUser: (ctx) => authKit.getAuthUser(ctx),
+	mapRole: defaultRoleMap, // or your own vocabulary (see below)
+	adminRoles: ['admin'],
+	triggers, // every mutation write runs through wrapDB
+	verifyMembership: async ({ userId, organizationId }) => {
+		const memberships = await authKit.workos.userManagement.listOrganizationMemberships({
+			organizationId,
+			userId,
+			statuses: ['active'],
+		})
+		const m = memberships.data.find((c) => c.userId === userId)
+		return m ? { organizationId: m.organizationId, roleSlug: m.role.slug } : null
+	},
 })
 ```
 
@@ -44,14 +66,14 @@ imports from `_generated/server` appear **only** in this file.
 
 ## The constructor families
 
-| Constructor | Visibility | Auth | Extra |
-|---|---|---|---|
-| `authQuery` / `authMutation` / `authAction` | public | any authenticated org member | actions live-verify membership |
-| `roleQuery(...roles)` / `roleMutation(...)` / `roleAction(...)` | public | listed roles only | factory — call with your roles |
-| `adminQuery` / `adminMutation` / `adminAction` | public | `config.adminRoles` | pre-built `role*(...adminRoles)` |
-| `systemQuery` | internal | none (trusted caller) | include-equipped, RLS-unwrapped |
-| `systemMutation` | internal | none (trusted caller) | still trigger-wrapped |
-| `systemAction` | internal | none | plain internal action |
+| Constructor                                                     | Visibility | Auth                         | Extra                            |
+| --------------------------------------------------------------- | ---------- | ---------------------------- | -------------------------------- |
+| `authQuery` / `authMutation` / `authAction`                     | public     | any authenticated org member | actions live-verify membership   |
+| `roleQuery(...roles)` / `roleMutation(...)` / `roleAction(...)` | public     | listed roles only            | factory — call with your roles   |
+| `adminQuery` / `adminMutation` / `adminAction`                  | public     | `config.adminRoles`          | pre-built `role*(...adminRoles)` |
+| `systemQuery`                                                   | internal   | none (trusted caller)        | include-equipped, RLS-unwrapped  |
+| `systemMutation`                                                | internal   | none (trusted caller)        | still trigger-wrapped            |
+| `systemAction`                                                  | internal   | none                         | plain internal action            |
 
 All are `zCustom*` constructors from convex-helpers, so `args` and `returns`
 take zod schemas directly and compose with `zodTable` masks.
@@ -164,14 +186,16 @@ rejects limits outside `1..maxRows` (default 100, configurable via
 
 ```ts
 export const list = authQuery({
-  args: { ownerId: zid('users').optional(), limit: z.number() },
-  returns: z.array(documents.publicDto),
-  handler: (ctx, args) =>
-    ctx.include(ctx.db.query('documents'))
-      .when(args.ownerId, (q, ownerId) =>
-        q.withIndex('by_owner', (ix) => ix.eq('ownerId', ownerId)))
-      .otherwise((q) => q.withIndex('by_owner'))
-      .execute(args.limit, (rows) => rows.map(documents.toPublicDto)),
+	args: { ownerId: zid('users').optional(), limit: z.number() },
+	returns: z.array(documents.publicDto),
+	handler: (ctx, args) =>
+		ctx
+			.include(ctx.db.query('documents'))
+			.when(args.ownerId, (q, ownerId) =>
+				q.withIndex('by_owner', (ix) => ix.eq('ownerId', ownerId)),
+			)
+			.otherwise((q) => q.withIndex('by_owner'))
+			.execute(args.limit, (rows) => rows.map(documents.toPublicDto)),
 })
 ```
 

package/docs/commands.md

@@ -25,16 +25,13 @@ import { Foundation } from 'cvx-kit/components/foundation'
 import { components } from './_generated/api'
 import { writeAuditEntry } from './audit'
 
-export const { Command, Query, observability } = new Foundation(
-  components.foundation,
-  {
-    observability: {
-      enabled: () => process.env.COMMAND_OBSERVABILITY_ENABLED === 'true',
-      classifyError: (error) => classify(error), // → { outcome: 'denied' | 'failed', errorCode }
-      writeAudit: (ctx, entry) => writeAuditEntry(ctx, entry),
-    },
-  },
-)
+export const { Command, Query, observability } = new Foundation(components.foundation, {
+	observability: {
+		enabled: () => process.env.COMMAND_OBSERVABILITY_ENABLED === 'true',
+		classifyError: (error) => classify(error), // → { outcome: 'denied' | 'failed', errorCode }
+		writeAudit: (ctx, entry) => writeAuditEntry(ctx, entry),
+	},
+})
 ```
 
 Host code consumes the Foundation **only through this facade** — never deep
@@ -51,29 +48,33 @@ operation** — auditing is type-enforced, not opt-in.
 import { z } from 'zod'
 import { Command } from '../../foundation'
 import { documents } from './schema'
+import { zid } from 'cvx-kit/zod-table'
+import type { MutationCtx } from '../../_generated/server'
+
+const typed = Command.withContext<MutationCtx>()
 
 const operations = {
-  'documents.rename': Command.operation({
-    command: documents.commandInput.extend({ id: zid('documents') }),
-    result: z.object({ ok: z.literal(true) }).strict(),
-    classification: 'business',
-    audit: ({ command }) => ({
-      operation: 'documents.rename',
-      actorId: command.actorId,
-      aggregate: { type: 'document', id: command.id },
-      metadata: { title: command.title },
-    }),
-  }),
+	'documents.rename': typed.operation({
+		command: documents.commandInput.extend({ id: zid('documents') }),
+		result: z.object({ ok: z.literal(true) }).strict(),
+		classification: 'business',
+		audit: ({ command }) => ({
+			operation: 'documents.rename',
+			actorId: command.actorId,
+			aggregate: { type: 'document', id: command.id },
+			metadata: { title: command.title },
+		}),
+	}),
 } as const
 
 const commands = new Command<MutationCtx, typeof operations>(operations)
 
 export const executeRename = commands.exec({
-  operation: 'documents.rename',
-  handler: async (ctx, command) => {
-    await ctx.db.patch(command.id, { title: command.title })
-    return { ok: true }
-  },
+	operation: 'documents.rename',
+	handler: async (ctx, command) => {
+		await ctx.db.patch(command.id, { title: command.title })
+		return { ok: true }
+	},
 })
 ```
 
@@ -89,14 +90,20 @@ The public API layer then wraps the executor in an `authMutation` and passes
    Foundation's injected `checkPermission(ctx, { permission, operation })`
    runs; throw to deny. Declaring a permission with no injected checker
    **fails closed** (`COMMAND_PERMISSION_NOT_CONFIGURED`).
-4. **Default guard** — the registry-wide guard passed as the Command's second
+4. **Prepare**, when configured: obtain an invocation-local replay decision
+   or completion closure. Replay validates its durable result, then goes
+   directly to observation, skipping middleware, both guards, handler and audit.
+5. **Middleware and guards** — registry middleware wraps operation middleware,
+   which wraps both guards and the handler. The default guard is the
+   registry-wide guard passed as the Command's second
    argument (`new Command(operations, { guard })`), if any.
-5. **Operation guard** — the operation's own `guard(ctx, command)`:
+   Then the operation's own `guard(ctx, command)` checks
    preconditions like state-machine legality, ownership beyond roles, or
    invariants over the parsed command. Throw to deny — nothing has run yet,
    so a denial is always clean.
-6. **Run the handler**; its return value is parsed through the `result` schema
-   — outputs are validated too.
+6. **Run the handler and unwind middleware**; parse the final chain output
+   through the `result` schema exactly once. Middleware sees schema inputs;
+   audit, completion, and the executor receive validated schema outputs.
 7. **Audit**: call the operation's `audit({ command, result }, ctx)`. If it
    returns non-null, the entry (plus the operation's `classification`) is
    written through the injected `writeAudit` — **in the same transaction** as
@@ -106,8 +113,10 @@ The public API layer then wraps the executor in an `authMutation` and passes
    allowlist throws (`COMMAND_AGGREGATE_NOT_DECLARED`) — the audit
    vocabulary is enforced, not advisory. The per-operation catalog is
    introspectable as `commands.aggregates` for tests.
-8. **Emit the observation**: `{ operation, classification, outcome,
-   errorCode?, durationMs }` — completed, denied, or failed per
+8. **Complete**: await the closure returned by `prepare`, including when audit
+   returns null. A failure propagates inside the observation boundary.
+9. **Emit the observation**: `{ operation, classification, outcome,
+errorCode?, durationMs }` — completed, denied, or failed per
    `classifyError`.
 
 ### Guards and permissions
@@ -150,11 +159,11 @@ a handler in disguise.
 
 ### Middleware — composable, next()-based
 
-For wrap-around concerns (timing, tracing, context enrichment, replay
-wrappers) that two disconnected callbacks can't express, both kernels take
+For wrap-around concerns (timing, tracing, context enrichment) that two
+disconnected callbacks can't express, both kernels take
 Express/TanStack-style middleware. The chain runs **inside** the pipeline's
 invariants: after the permission check, around [guards → handler], before the
-result-schema re-parse, aggregate allowlist, and audit — so middleware can
+result-schema parse, aggregate allowlist, and audit — so middleware can
 never skip authorization, return an invalid result, or desynchronize audit
 from effects.
 
@@ -188,16 +197,122 @@ guard → operation guard → handler. `next()` returns the downstream result;
 middleware, guards, and the handler. Skipping `next()` short-circuits
 (guards and handler never run — the returned value still must satisfy the
 result schema); calling it twice throws `COMMAND_MIDDLEWARE_NEXT_REUSED`.
-Whatever leaves the chain is re-parsed through the operation's strict result
+Whatever leaves the chain is parsed through the operation's strict result
 schema — a middleware cannot fabricate an invalid result.
 
+### Schema-inferred callbacks and context extensions (0.1.3)
+
+`Command.withContext<Ctx>()` binds the host context for operation definitions.
+Its `operation()` infers parsed command fields, validated audit result fields,
+and the declared aggregate vocabulary. Operation middleware is contextual:
+write inline callbacks without `Command.middleware`, whose legacy low-level
+command and result boundary intentionally remains unknown.
+
+```ts
+const typed = Command.withContext<Ctx>()
+const operations = {
+	rename: typed.operation({
+		command: z.object({ title: z.string().transform((value) => value.length) }),
+		result: z.object({ ok: z.boolean() }),
+		classification: 'business',
+		aggregates: ['document'],
+		guard: (ctx, command) => requireTitleLength(ctx, command.title), // number
+		middleware: [
+			async ({ command, next }) => {
+				const result = await next() // { ok: boolean }, before validation
+				logLength(command.title)
+				return result
+			},
+		],
+		audit: ({ command, result }, ctx) => ({
+			operation: 'rename',
+			actorId: ctx.actorId,
+			aggregate: { type: 'document', id: String(command.title) },
+			metadata: { ok: result.ok },
+		}),
+	}),
+}
+const middleware = typed.registryMiddleware(operations, async (input) => {
+	if (input.operation === 'rename') {
+		input.command.title.toFixed() // discriminator retains schema correlation
+	}
+	return input.next()
+})
+const commands = new Command<Ctx, typeof operations>(operations, {
+	middleware: [middleware],
+})
+```
+
+Bind registry middleware to the same registry it describes. A heterogeneous
+registry callback returns a union; narrowing `input.operation` preserves
+the matching `input.command` and `input.next()` result type.
+Reusing it with a different operation definition throws
+`COMMAND_MIDDLEWARE_REGISTRY_MISMATCH` before the typed callback runs.
+
+To propagate a required middleware extension to guards and handlers, use
+`Command.withContext<Ctx, { traceId: string }>()`. Its operations require a
+nonempty middleware tuple; the first layer must pass the declared extension
+to `next({ context: { traceId } })` whenever it runs the downstream chain.
+Later layers, guards and handlers see `Ctx & { traceId: string }`.
+Audit and prepare receive the original context. The original context object
+is not mutated. Short circuits still undergo final result validation.
+
+### Transactional completion and replay (0.1.3)
+
+Use `prepare(ctx, parsedCommand)` for host-owned idempotency. It runs after
+permission and returns either `{ kind: 'replay', result: durableValue }` or
+`{ kind: 'execute', complete: async validatedResult => { ... } }`.
+The completion closure captures per-invocation state, including a fingerprint
+derived from the parsed command and authenticated actor. Do not cache that
+state in a shared context or module variable.
+
+```ts
+prepare: async (ctx, command) => {
+  const key = scopedKey(ctx.actorId, command.idempotencyKey)
+  const fingerprint = fingerprintOf(command)
+  const receipt = await loadReceipt(ctx, key)
+  if (receipt) {
+    if (receipt.fingerprint !== fingerprint) throw new Error('KEY_REUSED')
+    return { kind: 'replay', result: receipt.result }
+  }
+  return {
+    kind: 'execute',
+    complete: async result => {
+      await saveReceipt(ctx, { key, fingerprint, result })
+    },
+  }
+},
+```
+
+Storage, actor/tenant scoping, fingerprint comparison, retention, and conflict
+policy remain host responsibilities. Put authorization required on replay in
+the injected permission checker or prepare lookup; both guards are skipped
+on replay. A permission slug without a checker still fails closed. Ordinary
+middleware short-circuiting is not this replay path and still audits.
+
+Replays are parsed through `result` by default. If that schema transforms its
+input, store the completion callback's validated output and supply
+`replayResult` with an output validator (for example `z.number().int()` when
+`result` transforms a string into a number). This prevents reapplying an input
+transform to an already transformed durable result. An invalid replay fails
+inside observation; successful replay does not invoke completion again.
+
+Completion is awaited after result validation, audit resolution, aggregate
+validation, and audit writing, even on audit-null paths. Errors from prepare,
+replay validation, audit, or completion propagate and are passed to the host's
+error classifier. Observation success means this command finished; the
+enclosing mutation has not necessarily committed yet.
+
 The Query kernel takes the same shape: `new Query({ defaults, middleware,
 execute })` plus per-executor `middleware: [...]`, with `Query.middleware`
 as the typing helper. Kernel middleware runs before executor middleware,
 inside the host's injected `execute` policy.
 
-If any step throws, the Convex transaction rolls back — handler writes and
-audit entry together. Audit and effects can never disagree.
+For atomic rollback, let failures escape the enclosing Convex mutation.
+Catching and swallowing a failure inside that mutation can commit earlier
+business, audit, and completion writes. Rethrow after effects, or use the
+effect-aware `executeResultBoundary` below. External I/O in actions is not
+rolled back; these transaction guarantees concern Convex mutation writes.
 
 ### Dynamic dispatch
 
@@ -205,9 +320,9 @@ audit entry together. Audit and effects can never disagree.
 
 ```ts
 export const executeAny = commands.exec({
-  dispatcher: z.object({ kind: z.enum(OPERATION_KINDS) /* from constants.ts */ }),
-  select: (input) => `documents.${input.kind}` as const,
-  handler,
+	dispatcher: z.object({ kind: z.enum(OPERATION_KINDS) /* from constants.ts */ }),
+	select: (input) => `documents.${input.kind}` as const,
+	handler,
 })
 ```
 
@@ -269,9 +384,9 @@ knowing. Metadata defaults are set at construction and merged per-executor.
    else destructures from it.
 2. Never deep-import the component's `modules/*` or `result.ts` paths from app
    code — the `client.ts` facade is the contract.
-3. The audit callback receives the ctx untyped (`never`); wiring a query ctx
-   into an audited command fails at runtime, not compile time. Commands run in
-   mutations.
+3. Use `Command.withContext<MutationCtx>()` for typed callbacks and construct
+   the Command with a compatible host context. Legacy `Command.operation`
+   keeps its low-level callback signature. Commands with writes run in mutations.
 4. Name operations `domain.verb` and error codes `UPPER_SNAKE` or your
    telemetry silently disappears (see regexes above).
 5. Keep operation registries frozen (`as const`) in the domain's

package/docs/conventions.md

@@ -99,16 +99,16 @@ another file's function to shorten an import.
 
 ### Root files
 
-| File | Contains | Never contains |
-|---|---|---|
-| `convex.config.ts` | `defineApp()`, one `app.use(...)` per component, `defineApp({ env })` declarations, `export default app` | anything else |
-| `schema.ts` | `defineSchema(domainTables)` | table definitions, validators |
-| `functions.ts` | the single `createAuthFunctions<DataModel>()` call and its exported constructors | handlers, business policy beyond the injected config |
-| `triggers.ts` | `createTriggers()`, `timestamps`/`appendOnly`/`noDelete` registrations, calls to per-entity `register<Entity>Triggers` | trigger *logic* for a specific entity (that lives in the entity) |
-| `foundation.ts` | the single `new Foundation(...)`, destructured exports | command definitions |
-| `<component>.ts` | `new <Client>(components.<name>)` + minimal admin plumbing | workflow/business definitions |
-| `http.ts` | routes: verify signature → parse payload → delegate to a domain function | webhook business logic |
-| `crons.ts` | `cronJobs()` declarations targeting `internal.domain.<entity>...` | handler logic |
+| File               | Contains                                                                                                               | Never contains                                                   |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `convex.config.ts` | `defineApp()`, one `app.use(...)` per component, `defineApp({ env })` declarations, `export default app`               | anything else                                                    |
+| `schema.ts`        | `defineSchema(domainTables)`                                                                                           | table definitions, validators                                    |
+| `functions.ts`     | the single `createAuthFunctions<DataModel>()` call and its exported constructors                                       | handlers, business policy beyond the injected config             |
+| `triggers.ts`      | `createTriggers()`, `timestamps`/`appendOnly`/`noDelete` registrations, calls to per-entity `register<Entity>Triggers` | trigger _logic_ for a specific entity (that lives in the entity) |
+| `foundation.ts`    | the single `new Foundation(...)`, destructured exports                                                                 | command definitions                                              |
+| `<component>.ts`   | `new <Client>(components.<name>)` + minimal admin plumbing                                                             | workflow/business definitions                                    |
+| `http.ts`          | routes: verify signature → parse payload → delegate to a domain function                                               | webhook business logic                                           |
+| `crons.ts`         | `cronJobs()` declarations targeting `internal.domain.<entity>...`                                                      | handler logic                                                    |
 
 ### `api/<entity>.ts` — the adapter file
 
@@ -176,7 +176,7 @@ compile. Numeric limits and durations the entity owns also live here.
 ### `domain/<entity>/commands.ts` — every state change
 
 1. The frozen operation registry: `Command.operation({ command, result,
-   classification, audit })` per operation, keys `'<entity>.<verb>'`.
+classification, audit })` per operation, keys `'<entity>.<verb>'`.
 2. One `new Command<Ctx, typeof operations>(operations)`.
 3. Exported executors: `export const execute<Verb><Entity> = commands.exec(...)`.
 4. Private handler helpers at the bottom.
@@ -197,7 +197,7 @@ Handlers call rules; rules never call handlers.
 
 ### `domain/<entity>/shared.ts` — entity-private helpers
 
-Code shared by two or more files *of this entity*. If a second entity needs
+Code shared by two or more files _of this entity_. If a second entity needs
 it, it moves to `domain/shared/` — never a sibling import.
 
 ### `domain/<entity>/actions.ts` — external side effects
@@ -234,25 +234,25 @@ ground: code with one consumer moves back to that consumer.
 
 ## 3. Naming grammar
 
-| Thing | Convention | Example shape |
-|---|---|---|
-| Entity directory | plural camelCase, matches table name | `domain/<entities>/` |
-| Table | plural camelCase | `<entities>` |
-| Fields | camelCase; foreign keys `<other>Id`; timestamps only via the kit | `ownerId`, `archivedAt` |
-| Index | `by_<field>` / `by_<field>_and_<field>`, declaration order, nested paths flattened with `_` | `by_ownerId_and_state_status` |
-| Command operation | `<entity>.<verb>` lowercase dotted; must match `/^[A-Za-z][A-Za-z0-9_.-]{0,159}$/` | `<entities>.approve` |
-| Error code | `UPPER_SNAKE`, matching `/^[A-Z][A-Z0-9_]{0,95}$/`, defined in one owner | `INVALID_REQUEST_BOUNDARY` |
-| Vocabulary tuple | `UPPER_SNAKE_CASE` `as const`; derived type PascalCase singular | `<ENTITY>_STATES` / `<Entity>State` |
-| Domain executor | `execute<Verb><Entity>` | `executeApprove<Entity>` |
-| Rule predicate | `can<Verb>` / `is<Condition>` | `canApprove`, `isTransitionLegal` |
-| Trigger registration | `register<Entity>Triggers(triggers)` | exported from the entity, called in root `triggers.ts` |
-| Internal-callback file | `<purpose>_functions.ts`, sibling of `<purpose>.ts` | `approval_functions.ts` |
-| zodTable export | camelCase plural, same as table | `export const <entities> = zodTable(...)` |
-| DTO schema | `<entity><Purpose>Dto` | `<entity>SummaryDto` |
-| Zod schema value | camelCase noun | `commandInput`, `publicDto` |
-| Type | PascalCase; no `I`/`T` prefixes | `<Entity>State` |
-| Test file | `<subject>.test.ts` in `__tests__/` | `commands.test.ts` |
-| Public function path | `api/<entity>:<fn>` — clients never call a root path | — |
+| Thing                  | Convention                                                                                  | Example shape                                          |
+| ---------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Entity directory       | plural camelCase, matches table name                                                        | `domain/<entities>/`                                   |
+| Table                  | plural camelCase                                                                            | `<entities>`                                           |
+| Fields                 | camelCase; foreign keys `<other>Id`; timestamps only via the kit                            | `ownerId`, `archivedAt`                                |
+| Index                  | `by_<field>` / `by_<field>_and_<field>`, declaration order, nested paths flattened with `_` | `by_ownerId_and_state_status`                          |
+| Command operation      | `<entity>.<verb>` lowercase dotted; must match `/^[A-Za-z][A-Za-z0-9_.-]{0,159}$/`          | `<entities>.approve`                                   |
+| Error code             | `UPPER_SNAKE`, matching `/^[A-Z][A-Z0-9_]{0,95}$/`, defined in one owner                    | `INVALID_REQUEST_BOUNDARY`                             |
+| Vocabulary tuple       | `UPPER_SNAKE_CASE` `as const`; derived type PascalCase singular                             | `<ENTITY>_STATES` / `<Entity>State`                    |
+| Domain executor        | `execute<Verb><Entity>`                                                                     | `executeApprove<Entity>`                               |
+| Rule predicate         | `can<Verb>` / `is<Condition>`                                                               | `canApprove`, `isTransitionLegal`                      |
+| Trigger registration   | `register<Entity>Triggers(triggers)`                                                        | exported from the entity, called in root `triggers.ts` |
+| Internal-callback file | `<purpose>_functions.ts`, sibling of `<purpose>.ts`                                         | `approval_functions.ts`                                |
+| zodTable export        | camelCase plural, same as table                                                             | `export const <entities> = zodTable(...)`              |
+| DTO schema             | `<entity><Purpose>Dto`                                                                      | `<entity>SummaryDto`                                   |
+| Zod schema value       | camelCase noun                                                                              | `commandInput`, `publicDto`                            |
+| Type                   | PascalCase; no `I`/`T` prefixes                                                             | `<Entity>State`                                        |
+| Test file              | `<subject>.test.ts` in `__tests__/`                                                         | `commands.test.ts`                                     |
+| Public function path   | `api/<entity>:<fn>` — clients never call a root path                                        | —                                                      |
 
 The two regexes are enforced at runtime: observability silently drops events
 whose operation/classification/errorCode don't match. The rest is enforced by
@@ -264,14 +264,14 @@ the architecture tests — a naming rule without a test is a wish.
 
 Allowed, per zone (anything not listed is forbidden):
 
-| From | May import |
-|---|---|
-| `api/<entity>.ts` | `functions.ts`, `domain/<entity>/*`, `domain/shared/*`, zod |
-| `domain/<entity>/*` | `functions.ts`, `foundation.ts`, component facades, `domain/shared/*`, own directory, generated `internal`/`api` (references only), kit modules |
-| `domain/shared/*` | kit modules, vendor SDKs (this is the ONLY home for vendor clients) |
-| root facades | kit modules, `components` from generated api |
-| `functions.ts` | `_generated/server` (the only file allowed to) |
-| `components/<name>/**` | its own directory + npm deps only — no host imports, no `process.env` |
+| From                   | May import                                                                                                                                      |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api/<entity>.ts`      | `functions.ts`, `domain/<entity>/*`, `domain/shared/*`, zod                                                                                     |
+| `domain/<entity>/*`    | `functions.ts`, `foundation.ts`, component facades, `domain/shared/*`, own directory, generated `internal`/`api` (references only), kit modules |
+| `domain/shared/*`      | kit modules, vendor SDKs (this is the ONLY home for vendor clients)                                                                             |
+| root facades           | kit modules, `components` from generated api                                                                                                    |
+| `functions.ts`         | `_generated/server` (the only file allowed to)                                                                                                  |
+| `components/<name>/**` | its own directory + npm deps only — no host imports, no `process.env`                                                                           |
 
 Forbidden everywhere: sibling-entity imports, `api/` from `domain/`,
 component internals (anything below a component's client facade),
@@ -286,6 +286,6 @@ component internals (anything below a component's client facade),
 - Zod objects that cross a boundary are `.strict()` — always.
 - `Object.freeze` for registries and long-lived configuration objects.
 - Comments state constraints the code can't (`// Optional only for rows
-  created before <epoch>.`) — never narration of the next line.
+created before <epoch>.`) — never narration of the next line.
 - One entity concept per file; when a file serves two purposes, split it
   along the anatomy in §2.

package/docs/crud.md

@@ -36,11 +36,11 @@ export const create = authMutation({
 
 ## What gets generated
 
-| Operation | Input | Effect | Audit aggregate id |
-|---|---|---|---|
-| `<table>.create` | `commandInput` (strict) + `enrich` stamps | insert | the new row id |
-| `<table>.update` | `{ id, data: commandInput.partial() }` (strict) | patch | the row id |
-| `<table>.archive` | `{ id }` | sets `archivedAt` (soft delete ONLY) | the row id |
+| Operation         | Input                                           | Effect                               | Audit aggregate id |
+| ----------------- | ----------------------------------------------- | ------------------------------------ | ------------------ |
+| `<table>.create`  | `commandInput` (strict) + `enrich` stamps       | insert                               | the new row id     |
+| `<table>.update`  | `{ id, data: commandInput.partial() }` (strict) | patch                                | the row id         |
+| `<table>.archive` | `{ id }`                                        | sets `archivedAt` (soft delete ONLY) | the row id         |
 
 No hard-delete operation is generated — kit doctrine (`noDelete` +
 `archivedAt`).