cvx-kit 0.1.2 → 0.1.3

package/docs/commands.md

@@ -51,9 +51,13 @@ 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({
+  'documents.rename': typed.operation({
     command: documents.commandInput.extend({ id: zid('documents') }),
     result: z.object({ ok: z.literal(true) }).strict(),
     classification: 'business',
@@ -89,14 +93,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,7 +116,9 @@ 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,
+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`.
 
@@ -150,11 +162,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 +200,119 @@ 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
 
@@ -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/upgrading.md

@@ -1,5 +1,47 @@
 # Upgrading to 0.1.0 — the new way of things
 
+## 0.1.3
+
+Install `convex-helpers` as a direct peer, using one compatible instance:
+
+```sh
+bun add cvx-kit@0.1.3 convex-helpers@0.1.124
+```
+
+The peer range is `>=0.1.123 <0.2.0`. Remove overrides that force a
+separate helper copy and regenerate the installation without discarding
+unrelated dependency choices. This release is validated with Convex 1.45.0,
+Zod 4.5.4, and convex-test 0.0.56.
+
+Existing `Command.operation` and `Command.middleware` remain available.
+For callback inference, use `Command.withContext<MutationCtx>().operation`;
+see `commands.md` for typed middleware and transactional completion.
+
+Result transforms now run once, after middleware. A handler and middleware
+return the result schema's **input** type; audit, completion, and the executor
+receive its **output**. Middleware reading `await next()` sees the unparsed
+handler result. Remove workarounds that compensate for double transforms.
+When storing transformed outputs for replay, supply an output validator as
+`replayResult`; otherwise replay uses the ordinary result schema.
+Executor callers supply the command schema's input type; guards, prepare,
+middleware, and handlers receive its parsed output. For example, a string
+transformed to a number is passed as a string to the executor and observed
+as a number by its callbacks.
+
+Test registration no longer needs a registrar adapter or assertion:
+
+```ts
+import { convexTest } from 'convex-test'
+import { registerFoundation, registerApprovals } from 'cvx-kit/test'
+import schema from './schema'
+
+const t = convexTest(schema, import.meta.glob('./**/*.ts'))
+registerFoundation(t)
+registerApprovals(t)
+```
+
+Both helpers accept an optional custom component path as their second argument.
+
 ## Approvals packaging repair (0.1.x patch)
 
 `cvx-kit@0.1.0` published component schemas as `schema.mjs`, which Convex does

package/docs/zod-table.md

@@ -27,6 +27,28 @@ export const documents = zodTable(
 
 ## What you get back
 
+### Shared ID validation (0.1.3)
+
+Install one compatible `convex-helpers` peer (`>=0.1.123 <0.2.0`) alongside
+cvx-kit. ID metadata lives in a helper-instance registry: copying schemas
+between separately installed helper instances can silently turn an ID into
+`v.any()`. An exact nested dependency previously caused that failure even
+when both helper versions were compatible. Fresh npm and Bun consumer tests
+now exercise storage, command, DTO, and nested ID conversion with a different
+compatible host version.
+
+Prefer the matching kit exports when deriving validators from kit schemas:
+
+```ts
+import { zid, zodToConvex, convexToZod } from 'cvx-kit/zod-table'
+```
+
+Do not force conflicting nested helper copies with overrides or reuse schema
+objects across separate bundles. The upstream converter cannot recognize an
+unregistered foreign ID and does not throw; peer installation prevents the
+supported package graph from creating that ambiguity. Verify critical ID
+validators retain `kind === 'id'` and the expected `tableName` after installation.
+
 | Property | What it is | Where you use it |
 |---|---|---|
 | `table` | `defineTable(...)` from the storage shape | `convex/schema.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cvx-kit",
-	"version": "0.1.2",
+	"version": "0.1.3",
 	"description": "Reusable Convex application kit: foundation kernels, approvals component, zod table boundaries, WorkOS-backed auth function constructors, and audited command protocol.",
 	"type": "module",
 	"license": "MIT",
@@ -92,6 +92,7 @@
 		"typecheck": "tsc --noEmit",
 		"test": "vp test run --exclude test/package-contents.test.mjs",
 		"test:package": "bun run build && vp test run test/package-contents.test.mjs",
+		"test:package:ids": "bun run build && node scripts/test-packed-ids.mjs",
 		"test:package:smoke:bun": "bun scripts/smoke-packed-components.mjs bun",
 		"test:package:smoke:npm": "node scripts/smoke-packed-components.mjs npm",
 		"docs:sync": "rm -f docs/*.md && cp src/docs/*.md docs/",
@@ -101,22 +102,23 @@
 		"release:minor": "npm version minor && git push --follow-tags"
 	},
 	"dependencies": {
-		"@convex-dev/workflow": "0.4.4",
-		"convex-audit-log": "^0.2.0",
-		"convex-helpers": "0.1.122"
+		"@convex-dev/workflow": "0.4.6",
+		"convex-audit-log": "^0.2.0"
 	},
 	"peerDependencies": {
-		"convex": "^1.43.0",
-		"zod": "^4.0.0"
+		"convex-helpers": ">=0.1.123 <0.2.0",
+		"convex": "^1.45.0",
+		"zod": "^4.5.4"
 	},
 	"devDependencies": {
+		"convex-helpers": "0.1.124",
 		"@edge-runtime/vm": "^5.0.0",
-		"convex": "1.43.0",
-		"convex-test": "^0.0.55",
-		"publint": "^0.3.23",
+		"convex": "1.45.0",
+		"convex-test": "^0.0.56",
+		"publint": "^0.3.24",
 		"typescript": "7.0.2",
-		"vite-plus": "0.2.8",
-		"zod": "4.4.3"
+		"vite-plus": "0.3.0",
+		"zod": "4.5.4"
 	},
 	"keywords": [
 		"convex",

package/scripts/extract-changelog.mjs

@@ -11,7 +11,7 @@ if (!version) {
 }
 const changelog = readFileSync(new URL('../CHANGELOG.md', import.meta.url), 'utf8')
 const pattern = new RegExp(
-	String.raw`^## \[${version.replace(/\./g, String.raw`\.`)}\][^\n]*\n([\s\S]*?)(?=^## \[|\Z)`,
+	String.raw`^## \[${version.replace(/\./g, String.raw`\.`)}\][^\n]*\n([\s\S]*?)(?=^## \[|(?![\s\S]))`,
 	'm',
 )
 const match = changelog.match(pattern)

package/scripts/smoke-packed-components.mjs

@@ -18,9 +18,10 @@ if (installer !== 'bun' && installer !== 'npm') {
 const root = join(import.meta.dirname, '..')
 const temporaryRoot = mkdtempSync(join(tmpdir(), 'cvx-kit-smoke-'))
 const fixture = join(temporaryRoot, 'fixture')
-const packageVersion = JSON.parse(
+const packageManifest = JSON.parse(
 	readFileSync(join(root, 'package.json'), 'utf8'),
-).version
+)
+const packageVersion = packageManifest.version
 const tarball = join(temporaryRoot, `cvx-kit-${packageVersion}.tgz`)
 
 function run(command, args, cwd = fixture) {
@@ -72,11 +73,12 @@ try {
 				type: 'module',
 				dependencies: {
 					'cvx-kit': `file:${tarball}`,
-					convex: '1.43.0',
-					zod: '4.4.3',
+					convex: packageManifest.devDependencies.convex,
+					zod: packageManifest.devDependencies.zod,
+					'convex-helpers': packageManifest.devDependencies['convex-helpers'],
 				},
 				devDependencies: {
-					'vite-plus': '0.2.8',
+					'vite-plus': packageManifest.devDependencies['vite-plus'],
 				},
 			},
 			null,
@@ -327,27 +329,26 @@ export const status = query({
 		)
 	}
 
-	let decision
-	let lastError
-	for (let attempt = 0; attempt < 10; attempt += 1) {
-		try {
-			decision = JSON.parse(
-				runConvex('run', 'smoke:decide', JSON.stringify({ runId })),
-			)
-			break
-		} catch (error) {
-			lastError = error
-			const currentStatus = JSON.parse(
-				runConvex('run', 'smoke:status', JSON.stringify({ runId })),
-			)
-			if (currentStatus.state === 'approved') {
-				decision = currentStatus
-				break
-			}
-			await new Promise((resolve) => setTimeout(resolve, 500))
+	// start schedules the workflow; a successful start is not decision readiness.
+	let readyStatus
+	const readyDeadline = Date.now() + 60_000
+	while (Date.now() < readyDeadline) {
+		readyStatus = JSON.parse(
+			runConvex('run', 'smoke:status', JSON.stringify({ runId })),
+		)
+		if (readyStatus?.run.state !== 'pending' ||
+			['failed', 'canceled', 'completed'].includes(readyStatus?.execution?.type)) {
+			throw new Error(`Approval ended before decision readiness: ${JSON.stringify(readyStatus)}`)
 		}
+		if (readyStatus.run.currentStepKey === 'releaseDecision') break
+		await new Promise((resolve) => setTimeout(resolve, 500))
 	}
-	if (!decision) throw lastError
+	if (readyStatus?.run.currentStepKey !== 'releaseDecision') {
+		throw new Error(`Approval did not become decision-ready: ${JSON.stringify(readyStatus)}`)
+	}
+	const decision = JSON.parse(
+		runConvex('run', 'smoke:decide', JSON.stringify({ runId })),
+	)
 	if (decision.state !== 'approved') {
 		throw new Error(`Unexpected decision response: ${JSON.stringify(decision)}`)
 	}

package/scripts/test-packed-ids.mjs

@@ -0,0 +1,157 @@
+import { execFileSync } from 'node:child_process'
+import {
+	mkdtempSync,
+	mkdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const root = join(import.meta.dirname, '..')
+const temporary = mkdtempSync(join(tmpdir(), 'cvx-kit-ids-'))
+const manifest = JSON.parse(
+	readFileSync(join(root, 'package.json'), 'utf8'),
+)
+function run(command, args, cwd) {
+	return execFileSync(command, args, {
+		cwd,
+		encoding: 'utf8',
+		stdio: 'pipe',
+	})
+}
+try {
+	run(
+		'bun',
+		['pm', 'pack', '--destination', temporary, '--ignore-scripts'],
+		root,
+	)
+	for (const installer of ['npm', 'bun']) {
+		const fixture = join(temporary, installer)
+		mkdirSync(fixture)
+		writeFileSync(
+			join(fixture, 'package.json'),
+			JSON.stringify({
+				private: true,
+				type: 'module',
+				dependencies: {
+					'cvx-kit': `file:${join(temporary, `cvx-kit-${manifest.version}.tgz`)}`,
+					'convex-helpers': '0.1.123',
+					convex: manifest.devDependencies.convex,
+					zod: manifest.devDependencies.zod,
+				},
+				devDependencies: {
+					'convex-test': manifest.devDependencies['convex-test'],
+					'vite-plus': manifest.devDependencies['vite-plus'],
+					'@edge-runtime/vm': manifest.devDependencies['@edge-runtime/vm'],
+				},
+			}),
+		)
+		run(installer, ['install', '--ignore-scripts'], fixture)
+		writeFileSync(
+			join(fixture, 'probe.mjs'),
+			`
+import { strict as assert } from 'node:assert'
+import { tenantTable, zodToConvex as kitConverter, zid as kitId } from 'cvx-kit/zod-table'
+import { zid, zodToConvex } from 'convex-helpers/server/zod4'
+import { z } from 'zod'
+const table = tenantTable('children', id => ({
+ parentId: id('parents'), nested: z.object({ parentId: id('parents') }),
+}), { commandFields: ['parentId', 'nested'], publicFields: ['parentId', 'nested'] })
+for (const validator of [
+ zodToConvex(zid('parents')), table.table.validator.fields.parentId,
+ zodToConvex(table.storage).fields.parentId,
+ zodToConvex(table.commandInput).fields.parentId,
+ zodToConvex(table.publicDto).fields.parentId,
+ zodToConvex(table.storage).fields.nested.fields.parentId,
+ kitConverter(kitId('parents')),
+ kitConverter(table.commandInput).fields.nested.fields.parentId,
+ kitConverter(table.publicDto).fields.nested.fields.parentId,
+]) {
+ assert.equal(validator.kind, 'id', 'exported schema lost ID validation')
+ assert.equal(validator.tableName, 'parents')
+}
+`,
+		)
+		run('node', ['probe.mjs'], fixture)
+		for (const testFile of [
+			'command.test.ts',
+			'command-lifecycle.test.ts',
+		]) {
+			const source = readFileSync(join(root, 'test', testFile), 'utf8')
+				.replace(
+					'../src/components/foundation/client',
+					'cvx-kit/components/foundation',
+				)
+				.replace(
+					"const modules = import.meta.glob('./fixture/**/*.ts')",
+					"const modules = { './_generated/server.ts': async () => ({}) }",
+				)
+			writeFileSync(join(fixture, testFile), source)
+		}
+		writeFileSync(
+			join(fixture, 'command-types.ts'),
+			readFileSync(join(root, 'test/command-types.ts'), 'utf8').replace(
+				'../src/components/foundation/client',
+				'cvx-kit/components/foundation',
+			),
+		)
+		writeFileSync(
+			join(fixture, 'registration.test.ts'),
+			`
+import { convexTest } from 'convex-test'
+import { defineSchema, defineTable } from 'convex/server'
+import { v } from 'convex/values'
+import { registerFoundation, registerApprovals } from 'cvx-kit/test'
+import { it } from 'vite-plus/test'
+it('registers concrete and generic backends from the packed package', () => {
+ const modules = { './_generated/server.ts': async () => ({}) }
+ const concrete = convexTest(defineSchema({ items: defineTable({ name: v.string() }) }), modules)
+ const generic = convexTest(undefined, modules)
+ for (const backend of [concrete, generic]) {
+  registerFoundation(backend)
+  registerApprovals(backend)
+  registerFoundation(backend, 'customFoundation')
+  registerApprovals(backend, 'customApprovals')
+ }
+})
+`,
+		)
+		run(
+			join(root, 'node_modules/.bin/tsc'),
+			[
+				'--noEmit',
+				'--strict',
+				'--skipLibCheck',
+				'--target',
+				'es2025',
+				'--module',
+				'esnext',
+				'--moduleResolution',
+				'bundler',
+				'--types',
+				'vite/client',
+				'command-types.ts',
+				'registration.test.ts',
+			],
+			fixture,
+		)
+		run(
+			join(fixture, 'node_modules/.bin/vp'),
+			[
+				'test',
+				'run',
+				'registration.test.ts',
+				'command.test.ts',
+				'command-lifecycle.test.ts',
+			],
+			fixture,
+		)
+		console.log(
+			`${installer}: packed IDs, strict declarations, registration, and command lifecycle pass with host convex-helpers 0.1.123`,
+		)
+	}
+} finally {
+	rmSync(temporary, { recursive: true, force: true })
+}

package/src/test.ts

@@ -6,6 +6,7 @@
  * registers the COMPILED component modules from dist, so dist is the only
  * code the package ships.
  */
+import type { GenericSchema, SchemaDefinition } from 'convex/server'
 import approvalsSchema from '../dist/components/approvals/schema.js'
 import foundationSchema from '../dist/components/foundation/schema.js'
 
@@ -19,7 +20,7 @@ const approvalsModules = import.meta.glob(
 type RegistersComponents = {
 	registerComponent: (
 		name: string,
-		schema: unknown,
+		schema: SchemaDefinition<GenericSchema, boolean>,
 		modules: Record<string, () => Promise<unknown>>,
 	) => void
 }