cvx-kit 0.1.1 → 0.1.3

package/dist/components/foundation/operation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.mjs","names":[],"sources":["../../../src/components/foundation/operation.ts"],"sourcesContent":["import type {\n\tAuditEntryInput,\n\tAuditedRegistry,\n\tAuditedOperation,\n\tAnyCommandMiddleware,\n} from './client'\nimport type {\n\tCommandInput,\n\tCommandHandlerResult,\n\tParseable,\n\tSchemaInput,\n} from './modules/command/command'\n\ntype MaybePromise<T> = T | Promise<T>\nexport type CommandPreparation<Result> =\n\t| { kind: 'replay'; result: unknown }\n\t| { kind: 'execute'; complete?: (result: Result) => MaybePromise<void> }\ntype Parsed<S extends Parseable<unknown>> = ReturnType<S['parse']>\ndeclare const extension: unique symbol\ndeclare const hostContext: unique symbol\nexport type OperationHostContext<Context> = {\n\treadonly [hostContext]?: (context: Context) => void\n}\nexport type OperationExtension<Definition> = Definition extends {\n\treadonly [extension]?: infer Extension\n}\n\t? Extension\n\t: unknown\n\ntype MiddlewareInput<Context, Input, Output, Extension> = {\n\toperation: string\n\tcontext: Context\n\tcommand: Input\n\tnext: keyof Extension extends never\n\t\t? (options?: { context?: Extension }) => Promise<Output>\n\t\t: (options: { context: Extension }) => Promise<Output>\n}\ntype LocalMiddleware<C, I, O, E> = (\n\tinput: MiddlewareInput<C, I, O, E>,\n) => Promise<O>\ntype AuditFor<Aggregate extends string> = Omit<\n\tAuditEntryInput,\n\t'classification' | 'aggregate'\n> & {\n\taggregate: { type: Aggregate; id: string }\n}\nexport type TypedOperation<\n\tContext,\n\tInput extends Parseable<unknown>,\n\tOutput extends Parseable<unknown>,\n\tAggregates extends readonly string[],\n\tExtension,\n> = OperationHostContext<Context> & {\n\treadonly command: Input\n\treadonly result: Output\n\treadonly classification: string\n\treadonly permission?: string\n\t/** Called after permission, inside observation; returns invocation-local hooks. */\n\treadonly prepare?: (\n\t\tcontext: Context,\n\t\tcommand: Parsed<Input>,\n\t) => MaybePromise<CommandPreparation<Parsed<Output>>>\n\t/** Validates stored outputs when result transforms accept a different input shape. */\n\treadonly replayResult?: Parseable<Parsed<Output>>\n\treadonly aggregates?: Aggregates\n\treadonly guard?: (\n\t\tcontext: Context & Extension,\n\t\tcommand: Parsed<Input>,\n\t) => MaybePromise<void>\n\treadonly audit: (\n\t\tresolution: { command: Parsed<Input>; result: Parsed<Output> },\n\t\tcontext: Context,\n\t) => MaybePromise<AuditFor<Aggregates[number]> | null>\n\treadonly [extension]?: Extension\n} & (keyof Extension extends never\n\t\t? {\n\t\t\t\treadonly middleware?: readonly LocalMiddleware<\n\t\t\t\t\tContext,\n\t\t\t\t\tParsed<Input>,\n\t\t\t\t\tSchemaInput<Output>,\n\t\t\t\t\tExtension\n\t\t\t\t>[]\n\t\t\t}\n\t\t: {\n\t\t\t\treadonly middleware: readonly [\n\t\t\t\t\tLocalMiddleware<\n\t\t\t\t\t\tContext,\n\t\t\t\t\t\tParsed<Input>,\n\t\t\t\t\t\tSchemaInput<Output>,\n\t\t\t\t\t\tExtension\n\t\t\t\t\t>,\n\t\t\t\t\t...LocalMiddleware<\n\t\t\t\t\t\tContext & Extension,\n\t\t\t\t\t\tParsed<Input>,\n\t\t\t\t\t\tSchemaInput<Output>,\n\t\t\t\t\t\tRecord<never, never>\n\t\t\t\t\t>[],\n\t\t\t\t]\n\t\t\t})\n\ntype RegistryInput<Context, Operations extends AuditedRegistry> = {\n\t[Key in Extract<keyof Operations, string>]: {\n\t\toperation: Key\n\t\tdefinition: Operations[Key]\n\t\tcontext: Context\n\t\tcommand: CommandInput<Operations, Key>\n\t\tnext: () => Promise<CommandHandlerResult<Operations, Key>>\n\t}\n}[Extract<keyof Operations, string>]\n\ntype StoredOperation<\n\tContext,\n\tInput extends Parseable<unknown>,\n\tOutput extends Parseable<unknown>,\n\tAggregates extends readonly string[],\n\tExtension,\n> = Omit<\n\tTypedOperation<Context, Input, Output, Aggregates, Extension>,\n\t'middleware'\n> &\n\tPick<AuditedOperation, 'middleware'>\n\n/** Binds host context once; each operation infers its own parsed schemas. */\nexport function operationFactory<\n\tContext,\n\tExtension extends Record<string, unknown> = Record<never, never>,\n>() {\n\treturn {\n\t\toperation<\n\t\t\tconst Input extends Parseable<unknown>,\n\t\t\tconst Output extends Parseable<unknown>,\n\t\t\tconst Aggregates extends readonly string[] = readonly string[],\n\t\t>(\n\t\t\tdefinition: TypedOperation<\n\t\t\t\tContext,\n\t\t\t\tInput,\n\t\t\t\tOutput,\n\t\t\t\tAggregates,\n\t\t\t\tExtension\n\t\t\t>,\n\t\t): StoredOperation<Context, Input, Output, Aggregates, Extension> {\n\t\t\t// The kernel selects this definition and parses its input before\n\t\t\t// invoking the heterogeneous middleware registry. Erase only that\n\t\t\t// storage seam; callbacks were checked against these schemas above.\n\t\t\treturn definition as StoredOperation<\n\t\t\t\tContext,\n\t\t\t\tInput,\n\t\t\t\tOutput,\n\t\t\t\tAggregates,\n\t\t\t\tExtension\n\t\t\t>\n\t\t},\n\t\tregistryMiddleware<const Operations extends AuditedRegistry>(\n\t\t\toperations: Operations & { readonly [Key in keyof Operations]: OperationHostContext<Context> },\n\t\t\tmiddleware: (\n\t\t\t\tinput: RegistryInput<Context, Operations>,\n\t\t\t) => Promise<unknown>,\n\t\t): AnyCommandMiddleware {\n\t\t\tfunction ownsDefinition(\n\t\t\t\tinput: Parameters<AnyCommandMiddleware>[0],\n\t\t\t): input is Parameters<AnyCommandMiddleware>[0] &\n\t\t\t\tRegistryInput<Context, Operations> {\n\t\t\t\treturn (\n\t\t\t\t\tObject.prototype.hasOwnProperty.call(\n\t\t\t\t\t\toperations,\n\t\t\t\t\t\tinput.operation,\n\t\t\t\t\t) && operations[input.operation] === input.definition\n\t\t\t\t)\n\t\t\t}\n\t\t\treturn (input) => {\n\t\t\t\tif (!ownsDefinition(input)) {\n\t\t\t\t\tthrow new CommandMiddlewareRegistryError(input.operation)\n\t\t\t\t}\n\t\t\t\treturn middleware(input)\n\t\t\t}\n\t\t},\n\t}\n}\n\nclass CommandMiddlewareRegistryError extends Error {\n\treadonly code = 'COMMAND_MIDDLEWARE_REGISTRY_MISMATCH'\n\tconstructor(operation: string) {\n\t\tsuper(\n\t\t\t`Typed middleware does not own the definition of operation \"${operation}\"`,\n\t\t)\n\t\tthis.name = 'CommandMiddlewareRegistryError'\n\t}\n}\n"],"mappings":"AA2HA,SAAgB,GAGZ,CACH,MAAO,CACN,UAKC,EAOiE,CAIjE,OAAO,CAOR,EACA,mBACC,EACA,EAGuB,CACvB,SAAS,EACR,EAEmC,CACnC,OACC,OAAO,UAAU,eAAe,KAC/B,EACA,EAAM,SACP,GAAK,EAAW,EAAM,aAAe,EAAM,UAE7C,CACA,MAAQ,IAAU,CACjB,GAAI,CAAC,EAAe,CAAK,EACxB,MAAM,IAAI,EAA+B,EAAM,SAAS,EAEzD,OAAO,EAAW,CAAK,CACxB,CACD,CACD,CACD,CAEA,IAAM,EAAN,cAA6C,KAAM,CAClD,KAAgB,uCAChB,YAAY,EAAmB,CAC9B,MACC,8DAA8D,EAAU,EACzE,EACA,KAAK,KAAO,gCACb,CACD"}

package/dist/zod-table.d.mts

@@ -1,4 +1,4 @@
-import { ConvexValidatorFromZod, zid } from "convex-helpers/server/zod4";
+import { ConvexValidatorFromZod, convexToZod, zid, zid as zid$1, zodToConvex } from "convex-helpers/server/zod4";
 import { TableDefinition } from "convex/server";
 import { z } from "zod";
 import { GenericId } from "convex/values";
@@ -23,7 +23,7 @@ type TableBoundaryOptions<Fields extends Shape, ServerFields extends readonly Sh
   publicFields?: PublicFields;
 };
 /** Defines one table and derives its storage, document, write, and DTO boundaries. */
-declare function zodTable<Table extends string, Fields extends Shape, const ServerFields extends readonly ShapeKey<Fields>[] = readonly [], const CommandFields extends readonly ShapeKey<Fields>[] = readonly [], const PublicFields extends readonly ShapeKey<Fields & TimestampShape>[] = readonly []>(tableName: Table, fields: (id: typeof zid) => Fields, options?: TableBoundaryOptions<Fields, ServerFields, CommandFields, PublicFields>): {
+declare function zodTable<Table extends string, Fields extends Shape, const ServerFields extends readonly ShapeKey<Fields>[] = readonly [], const CommandFields extends readonly ShapeKey<Fields>[] = readonly [], const PublicFields extends readonly ShapeKey<Fields & TimestampShape>[] = readonly []>(tableName: Table, fields: (id: typeof zid$1) => Fields, options?: TableBoundaryOptions<Fields, ServerFields, CommandFields, PublicFields>): {
   tableName: Table;
   schema: z.ZodObject<((keyof Fields & "_creationTime") | (keyof Fields & "_id") extends never ? (Fields & {
     createdAt: z.ZodOptional<z.ZodNumber>;
@@ -118,7 +118,7 @@ type TenantShape = typeof tenantShape;
  * trigger forbids reassigning it. Expose it via publicFields only when a DTO
  * genuinely needs it.
  */
-declare function tenantTable<Table extends string, Fields extends Shape, const ServerFields extends readonly ShapeKey<Fields>[] = readonly [], const CommandFields extends readonly ShapeKey<Fields>[] = readonly [], const PublicFields extends readonly ShapeKey<Fields & TenantShape & TimestampShape>[] = readonly []>(tableName: Table, fields: (id: typeof zid) => Fields, options?: TableBoundaryOptions<Fields & TenantShape, readonly (ServerFields[number] | 'tenant')[], CommandFields, PublicFields>): ReturnType<typeof zodTable<Table, Fields & TenantShape, readonly (ServerFields[number] | 'tenant')[], CommandFields, PublicFields>>;
+declare function tenantTable<Table extends string, Fields extends Shape, const ServerFields extends readonly ShapeKey<Fields>[] = readonly [], const CommandFields extends readonly ShapeKey<Fields>[] = readonly [], const PublicFields extends readonly ShapeKey<Fields & TenantShape & TimestampShape>[] = readonly []>(tableName: Table, fields: (id: typeof zid$1) => Fields, options?: TableBoundaryOptions<Fields & TenantShape, readonly (ServerFields[number] | 'tenant')[], CommandFields, PublicFields>): ReturnType<typeof zodTable<Table, Fields & TenantShape, readonly (ServerFields[number] | 'tenant')[], CommandFields, PublicFields>>;
 /**
  * Merges per-module table maps into the application schema map, rejecting
  * duplicate table names across modules — the module-registry combinator for
@@ -171,5 +171,5 @@ declare function zodVariantTable<Table extends string, Schema extends z.ZodType>
 declare function jsonSafeZid<Table extends string>(tableName: Table): z.ZodType<GenericId<Table>, string>;
 type ZodObjectOmit<Schema extends z.ZodObject<any, any>, OmitMask extends z.util.Mask<keyof Schema['shape']>> = Schema extends z.ZodObject<infer ObjectShape, infer Config> ? z.ZodObject<z.util.Flatten<Omit<ObjectShape, Extract<keyof ObjectShape, keyof OmitMask>>>, Config> : never;
 //#endregion
-export { TIMESTAMP_FIELDS, TableBoundaryOptions, createModule, jsonSafeZid, paginated, tenantTable, zodTable, zodVariantTable };
+export { TIMESTAMP_FIELDS, TableBoundaryOptions, convexToZod, createModule, jsonSafeZid, paginated, tenantTable, zid, zodTable, zodToConvex, zodVariantTable };
 //# sourceMappingURL=zod-table.d.mts.map

package/dist/zod-table.mjs

@@ -1,2 +1,2 @@
-import{convexToZod as e,zid as t,zodToConvex as n}from"convex-helpers/server/zod4";import{defineTable as r,paginationOptsValidator as i}from"convex/server";import{z as a}from"zod";const o={createdAt:a.number().optional(),updatedAt:a.number().optional(),archivedAt:a.number().optional()},s=[`createdAt`,`updatedAt`,`archivedAt`];function c(e,i,c={}){let l={...i(t),...o},u=a.object(l).strict(),d=u.extend({_id:t(e),_creationTime:a.number()}),f=a.object(g(l,[...s,...c.serverFields??[]])).strict(),p=f.partial(),_=a.object(h(l,c.commandFields??[])).strict(),v=a.object(h(l,c.publicFields??[])).strict(),y=e=>v.parse(Object.fromEntries(Object.keys(v.shape).map(t=>[t,e[t]])));function b(e){return e?f.omit(e):f}function x(e){return e?p.omit(e):p}return{tableName:e,schema:d,storage:u,insertSchema:f,updateSchema:p,commandInput:_,publicDto:v,toPublicDto:y,table:r(n(u)),insert:b,update:x,tools:{insert:_,update:a.object({data:_.partial(),id:m(e)}).strict(),id:a.object({id:m(e)}).strict()}}}const l={tenant:a.string().min(1)};function u(e,t,n={}){return c(e,e=>({...t(e),...l}),{...n,serverFields:[...n.serverFields??[],`tenant`]})}function d(...e){let t={};for(let n of e)for(let[e,r]of Object.entries(n)){if(e in t)throw Error(`Table "${e}" is declared by more than one module`);t[e]=r}return t}function f(t){return{args:{paginationOpts:e(i)},result:a.object({page:a.array(t),isDone:a.boolean(),continueCursor:a.string(),splitCursor:a.string().nullable().optional(),pageStatus:a.enum([`SplitRecommended`,`SplitRequired`]).nullable().optional()})}}function p(e,t){return{tableName:e,storage:t,insertSchema:t,table:r(n(t))}}function m(e){return a.string().describe(`Convex document id for table "${e}"`)}function h(e,t){return Object.fromEntries(t.map(t=>[t,e[t]]))}function g(e,t){let n=new Set(t);return Object.fromEntries(Object.entries(e).filter(([e])=>!n.has(e)))}export{s as TIMESTAMP_FIELDS,d as createModule,m as jsonSafeZid,f as paginated,u as tenantTable,c as zodTable,p as zodVariantTable};
+import{convexToZod as e,convexToZod as t,zid as n,zid as r,zodToConvex as i,zodToConvex as a}from"convex-helpers/server/zod4";import{defineTable as o,paginationOptsValidator as s}from"convex/server";import{z as c}from"zod";const l={createdAt:c.number().optional(),updatedAt:c.number().optional(),archivedAt:c.number().optional()},u=[`createdAt`,`updatedAt`,`archivedAt`];function d(e,t,n={}){let i={...t(r),...l},s=c.object(i).strict(),d=s.extend({_id:r(e),_creationTime:c.number()}),f=c.object(y(i,[...u,...n.serverFields??[]])).strict(),p=f.partial(),m=c.object(v(i,n.commandFields??[])).strict(),h=c.object(v(i,n.publicFields??[])).strict(),g=e=>h.parse(Object.fromEntries(Object.keys(h.shape).map(t=>[t,e[t]])));function b(e){return e?f.omit(e):f}function x(e){return e?p.omit(e):p}return{tableName:e,schema:d,storage:s,insertSchema:f,updateSchema:p,commandInput:m,publicDto:h,toPublicDto:g,table:o(a(s)),insert:b,update:x,tools:{insert:m,update:c.object({data:m.partial(),id:_(e)}).strict(),id:c.object({id:_(e)}).strict()}}}const f={tenant:c.string().min(1)};function p(e,t,n={}){return d(e,e=>({...t(e),...f}),{...n,serverFields:[...n.serverFields??[],`tenant`]})}function m(...e){let t={};for(let n of e)for(let[e,r]of Object.entries(n)){if(e in t)throw Error(`Table "${e}" is declared by more than one module`);t[e]=r}return t}function h(e){return{args:{paginationOpts:t(s)},result:c.object({page:c.array(e),isDone:c.boolean(),continueCursor:c.string(),splitCursor:c.string().nullable().optional(),pageStatus:c.enum([`SplitRecommended`,`SplitRequired`]).nullable().optional()})}}function g(e,t){return{tableName:e,storage:t,insertSchema:t,table:o(a(t))}}function _(e){return c.string().describe(`Convex document id for table "${e}"`)}function v(e,t){return Object.fromEntries(t.map(t=>[t,e[t]]))}function y(e,t){let n=new Set(t);return Object.fromEntries(Object.entries(e).filter(([e])=>!n.has(e)))}export{u as TIMESTAMP_FIELDS,e as convexToZod,m as createModule,_ as jsonSafeZid,h as paginated,p as tenantTable,n as zid,d as zodTable,i as zodToConvex,g as zodVariantTable};
 //# sourceMappingURL=zod-table.mjs.map

package/dist/zod-table.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"zod-table.mjs","names":[],"sources":["../src/zod-table.ts"],"sourcesContent":["import {\n\ttype ConvexValidatorFromZod,\n\tconvexToZod,\n\tzid,\n\tzodToConvex,\n} from 'convex-helpers/server/zod4'\nimport {\n\tdefineTable,\n\tpaginationOptsValidator,\n\ttype TableDefinition,\n} from 'convex/server'\nimport type { GenericId } from 'convex/values'\nimport { z } from 'zod'\n\ntype Shape = Record<string, z.ZodType>\ntype ShapeKey<Fields extends Shape> = Extract<keyof Fields, string>\n\n/**\n * Opinionated lifecycle timestamps — every table has them, server-owned,\n * always excluded from insert/command boundaries. Maintained by the\n * `timestamps` trigger helper (see cvx-kit/triggers).\n */\nconst timestampShape = {\n\tcreatedAt: z.number().optional(),\n\tupdatedAt: z.number().optional(),\n\tarchivedAt: z.number().optional(),\n} satisfies Shape\n\ntype TimestampShape = typeof timestampShape\n\nexport const TIMESTAMP_FIELDS = [\n\t'createdAt',\n\t'updatedAt',\n\t'archivedAt',\n] as const\n\nexport type TableBoundaryOptions<\n\tFields extends Shape,\n\tServerFields extends readonly ShapeKey<Fields>[],\n\tCommandFields extends readonly ShapeKey<Fields>[],\n\tPublicFields extends readonly ShapeKey<Fields & TimestampShape>[],\n> = {\n\tserverFields?: ServerFields\n\tcommandFields?: CommandFields\n\tpublicFields?: PublicFields\n}\n\n/** Defines one table and derives its storage, document, write, and DTO boundaries. */\nexport function zodTable<\n\tTable extends string,\n\tFields extends Shape,\n\tconst ServerFields extends readonly ShapeKey<Fields>[] = readonly [],\n\tconst CommandFields extends readonly ShapeKey<Fields>[] = readonly [],\n\tconst PublicFields extends readonly ShapeKey<\n\t\tFields & TimestampShape\n\t>[] = readonly [],\n>(\n\ttableName: Table,\n\tfields: (id: typeof zid) => Fields,\n\toptions: TableBoundaryOptions<\n\t\tFields,\n\t\tServerFields,\n\t\tCommandFields,\n\t\tPublicFields\n\t> = {},\n) {\n\tconst shape = { ...fields(zid), ...timestampShape } as Fields &\n\t\tTimestampShape\n\tconst storage = z.object(shape).strict()\n\tconst schema = storage.extend({\n\t\t_id: zid(tableName),\n\t\t_creationTime: z.number(),\n\t})\n\tconst insertSchema = z\n\t\t.object(\n\t\t\tomitShape(shape, [\n\t\t\t\t...TIMESTAMP_FIELDS,\n\t\t\t\t...(options.serverFields ?? ([] as never)),\n\t\t\t] as never),\n\t\t)\n\t\t.strict() as z.ZodObject<\n\t\tOmit<Fields, ServerFields[number] | (typeof TIMESTAMP_FIELDS)[number]>\n\t>\n\tconst updateSchema = insertSchema.partial()\n\tconst commandInput = z\n\t\t.object(pickShape(shape, options.commandFields ?? ([] as never)))\n\t\t.strict()\n\tconst publicDto = z\n\t\t.object(pickShape(shape, options.publicFields ?? ([] as never)))\n\t\t.strict()\n\tconst toPublicDto = (row: z.input<typeof storage>) =>\n\t\tpublicDto.parse(\n\t\t\tObject.fromEntries(\n\t\t\t\tObject.keys(publicDto.shape).map((key) => [\n\t\t\t\t\tkey,\n\t\t\t\t\t(row as Record<string, unknown>)[key],\n\t\t\t\t]),\n\t\t\t),\n\t\t)\n\n\ttype InsertSchema = typeof insertSchema\n\ttype UpdateSchema = typeof updateSchema\n\ttype InsertMask = z.util.Mask<keyof InsertSchema['shape']>\n\ttype UpdateMask = z.util.Mask<keyof UpdateSchema['shape']>\n\n\tfunction insert(): InsertSchema\n\tfunction insert<OmitMask extends InsertMask>(\n\t\tomit: OmitMask,\n\t): ZodObjectOmit<InsertSchema, OmitMask>\n\tfunction insert(omit?: InsertMask) {\n\t\treturn omit ? insertSchema.omit(omit as never) : insertSchema\n\t}\n\n\tfunction update(): UpdateSchema\n\tfunction update<OmitMask extends UpdateMask>(\n\t\tomit: OmitMask,\n\t): ZodObjectOmit<UpdateSchema, OmitMask>\n\tfunction update(omit?: UpdateMask) {\n\t\treturn omit ? updateSchema.omit(omit as never) : updateSchema\n\t}\n\n\treturn {\n\t\ttableName,\n\t\tschema,\n\t\tstorage,\n\t\tinsertSchema,\n\t\tupdateSchema,\n\t\tcommandInput,\n\t\tpublicDto,\n\t\ttoPublicDto,\n\t\ttable: defineTable(zodToConvex(storage)) as TableDefinition<\n\t\t\tConvexValidatorFromZod<typeof storage, 'required'>\n\t\t>,\n\t\tinsert,\n\t\tupdate,\n\t\ttools: {\n\t\t\t// jsonSafeZid (not zid): tool masks feed generated JSON schemas, so\n\t\t\t// ids must present as plain strings while keeping the Id<...> type.\n\t\t\tinsert: commandInput,\n\t\t\tupdate: z\n\t\t\t\t.object({ data: commandInput.partial(), id: jsonSafeZid(tableName) })\n\t\t\t\t.strict(),\n\t\t\tid: z.object({ id: jsonSafeZid(tableName) }).strict(),\n\t\t},\n\t}\n}\n\nconst tenantShape = {\n\ttenant: z.string().min(1),\n} satisfies Shape\n\ntype TenantShape = typeof tenantShape\n\n/**\n * A zodTable whose rows are tenant-owned: injects the server-owned `tenant`\n * field (the tenancy boundary — see cvx-kit/tenancy). Like timestamps, it is\n * excluded from insert/update/command boundaries; handlers stamp it from\n * ctx.tenant, row-level security matches on it, and the tenantOwnership\n * trigger forbids reassigning it. Expose it via publicFields only when a DTO\n * genuinely needs it.\n */\nexport function tenantTable<\n\tTable extends string,\n\tFields extends Shape,\n\tconst ServerFields extends readonly ShapeKey<Fields>[] = readonly [],\n\tconst CommandFields extends readonly ShapeKey<Fields>[] = readonly [],\n\tconst PublicFields extends readonly ShapeKey<\n\t\tFields & TenantShape & TimestampShape\n\t>[] = readonly [],\n>(\n\ttableName: Table,\n\tfields: (id: typeof zid) => Fields,\n\toptions: TableBoundaryOptions<\n\t\tFields & TenantShape,\n\t\treadonly (ServerFields[number] | 'tenant')[],\n\t\tCommandFields,\n\t\tPublicFields\n\t> = {},\n) {\n\treturn zodTable(\n\t\ttableName,\n\t\t(id) => ({ ...fields(id), ...tenantShape }),\n\t\t{\n\t\t\t...options,\n\t\t\tserverFields: [\n\t\t\t\t...((options.serverFields ?? []) as readonly (\n\t\t\t\t\t| ServerFields[number]\n\t\t\t\t\t| 'tenant'\n\t\t\t\t)[]),\n\t\t\t\t'tenant',\n\t\t\t] as never,\n\t\t} as never,\n\t) as ReturnType<\n\t\ttypeof zodTable<\n\t\t\tTable,\n\t\t\tFields & TenantShape,\n\t\t\treadonly (ServerFields[number] | 'tenant')[],\n\t\t\tCommandFields,\n\t\t\tPublicFields\n\t\t>\n\t>\n}\n\n/**\n * Merges per-module table maps into the application schema map, rejecting\n * duplicate table names across modules — the module-registry combinator for\n * domain/table.ts: `defineSchema(createModule(catalogTables, salesTables))`.\n */\nexport function createModule<\n\tconst Maps extends readonly Record<string, TableDefinition<any>>[],\n>(...maps: Maps): UnionToIntersection<Maps[number]> {\n\tconst combined: Record<string, TableDefinition<any>> = {}\n\tfor (const map of maps) {\n\t\tfor (const [tableName, definition] of Object.entries(map)) {\n\t\t\tif (tableName in combined) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Table \"${tableName}\" is declared by more than one module`,\n\t\t\t\t)\n\t\t\t}\n\t\t\tcombined[tableName] = definition\n\t\t}\n\t}\n\treturn combined as UnionToIntersection<Maps[number]>\n}\n\ntype UnionToIntersection<Union> = (\n\tUnion extends unknown\n\t\t? (member: Union) => void\n\t\t: never\n) extends (member: infer Intersection) => void\n\t? Intersection\n\t: never\n\n/**\n * Cursor-pagination boundary schemas bridged from Convex's own validators:\n * `args.paginationOpts` for function args, `result` for the page shape.\n * Pair with `include(...).paginate(opts)` (cvx-kit/auth). The result object\n * is deliberately non-strict — Convex may attach engine fields (splitCursor,\n * pageStatus); the page items themselves are validated against the dto.\n * Note: under row-level security, pages may be SHORTER than numItems when\n * rules reject rows mid-page; cursors remain correct.\n */\nexport function paginated<Dto extends z.ZodType>(dto: Dto) {\n\treturn {\n\t\targs: { paginationOpts: convexToZod(paginationOptsValidator) },\n\t\tresult: z.object({\n\t\t\tpage: z.array(dto),\n\t\t\tisDone: z.boolean(),\n\t\t\tcontinueCursor: z.string(),\n\t\t\tsplitCursor: z.string().nullable().optional(),\n\t\t\tpageStatus: z\n\t\t\t\t.enum(['SplitRecommended', 'SplitRequired'])\n\t\t\t\t.nullable()\n\t\t\t\t.optional(),\n\t\t}),\n\t}\n}\n\n/** Preserves discriminated-union storage while retaining the same table owner. */\nexport function zodVariantTable<Table extends string, Schema extends z.ZodType>(\n\ttableName: Table,\n\tstorage: Schema,\n) {\n\treturn {\n\t\ttableName,\n\t\tstorage,\n\t\tinsertSchema: storage,\n\t\ttable: defineTable(zodToConvex(storage)),\n\t}\n}\n\n/**\n * A zid that presents as a plain string in generated JSON schemas so\n * LLM-tool inputs stay primitive, while keeping the Id type at compile time.\n */\nexport function jsonSafeZid<Table extends string>(tableName: Table) {\n\treturn z\n\t\t.string()\n\t\t.describe(\n\t\t\t`Convex document id for table \"${tableName}\"`,\n\t\t) as unknown as z.ZodType<GenericId<Table>, string>\n}\n\ntype ZodObjectOmit<\n\tSchema extends z.ZodObject<any, any>,\n\tOmitMask extends z.util.Mask<keyof Schema['shape']>,\n> =\n\tSchema extends z.ZodObject<infer ObjectShape, infer Config>\n\t\t? z.ZodObject<\n\t\t\t\tz.util.Flatten<\n\t\t\t\t\tOmit<ObjectShape, Extract<keyof ObjectShape, keyof OmitMask>>\n\t\t\t\t>,\n\t\t\t\tConfig\n\t\t\t>\n\t\t: never\n\nfunction pickShape<\n\tFields extends Shape,\n\tconst Keys extends readonly ShapeKey<Fields>[],\n>(fields: Fields, keys: Keys) {\n\treturn Object.fromEntries(keys.map((key) => [key, fields[key]])) as Pick<\n\t\tFields,\n\t\tKeys[number]\n\t>\n}\n\nfunction omitShape<\n\tFields extends Shape,\n\tconst Keys extends readonly ShapeKey<Fields>[],\n>(fields: Fields, keys: Keys) {\n\tconst omitted = new Set<string>(keys)\n\treturn Object.fromEntries(\n\t\tObject.entries(fields).filter(([key]) => !omitted.has(key)),\n\t) as Omit<Fields, Keys[number]>\n}\n"],"mappings":"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"}
+{"version":3,"file":"zod-table.mjs","names":["zid","zodToConvex","convexToZod"],"sources":["../src/zod-table.ts"],"sourcesContent":["import {\n\ttype ConvexValidatorFromZod,\n\tconvexToZod,\n\tzid,\n\tzodToConvex,\n} from 'convex-helpers/server/zod4'\nimport {\n\tdefineTable,\n\tpaginationOptsValidator,\n\ttype TableDefinition,\n} from 'convex/server'\nimport type { GenericId } from 'convex/values'\nimport { z } from 'zod'\n\n// Use this entry point when deriving validators from kit-owned schemas so\n// the producer and converter consult the same convex-helpers ID registry.\nexport { zid, zodToConvex, convexToZod } from 'convex-helpers/server/zod4'\n\ntype Shape = Record<string, z.ZodType>\ntype ShapeKey<Fields extends Shape> = Extract<keyof Fields, string>\n\n/**\n * Opinionated lifecycle timestamps — every table has them, server-owned,\n * always excluded from insert/command boundaries. Maintained by the\n * `timestamps` trigger helper (see cvx-kit/triggers).\n */\nconst timestampShape = {\n\tcreatedAt: z.number().optional(),\n\tupdatedAt: z.number().optional(),\n\tarchivedAt: z.number().optional(),\n} satisfies Shape\n\ntype TimestampShape = typeof timestampShape\n\nexport const TIMESTAMP_FIELDS = [\n\t'createdAt',\n\t'updatedAt',\n\t'archivedAt',\n] as const\n\nexport type TableBoundaryOptions<\n\tFields extends Shape,\n\tServerFields extends readonly ShapeKey<Fields>[],\n\tCommandFields extends readonly ShapeKey<Fields>[],\n\tPublicFields extends readonly ShapeKey<Fields & TimestampShape>[],\n> = {\n\tserverFields?: ServerFields\n\tcommandFields?: CommandFields\n\tpublicFields?: PublicFields\n}\n\n/** Defines one table and derives its storage, document, write, and DTO boundaries. */\nexport function zodTable<\n\tTable extends string,\n\tFields extends Shape,\n\tconst ServerFields extends readonly ShapeKey<Fields>[] = readonly [],\n\tconst CommandFields extends readonly ShapeKey<Fields>[] = readonly [],\n\tconst PublicFields extends readonly ShapeKey<\n\t\tFields & TimestampShape\n\t>[] = readonly [],\n>(\n\ttableName: Table,\n\tfields: (id: typeof zid) => Fields,\n\toptions: TableBoundaryOptions<\n\t\tFields,\n\t\tServerFields,\n\t\tCommandFields,\n\t\tPublicFields\n\t> = {},\n) {\n\tconst shape = { ...fields(zid), ...timestampShape } as Fields &\n\t\tTimestampShape\n\tconst storage = z.object(shape).strict()\n\tconst schema = storage.extend({\n\t\t_id: zid(tableName),\n\t\t_creationTime: z.number(),\n\t})\n\tconst insertSchema = z\n\t\t.object(\n\t\t\tomitShape(shape, [\n\t\t\t\t...TIMESTAMP_FIELDS,\n\t\t\t\t...(options.serverFields ?? ([] as never)),\n\t\t\t] as never),\n\t\t)\n\t\t.strict() as z.ZodObject<\n\t\tOmit<Fields, ServerFields[number] | (typeof TIMESTAMP_FIELDS)[number]>\n\t>\n\tconst updateSchema = insertSchema.partial()\n\tconst commandInput = z\n\t\t.object(pickShape(shape, options.commandFields ?? ([] as never)))\n\t\t.strict()\n\tconst publicDto = z\n\t\t.object(pickShape(shape, options.publicFields ?? ([] as never)))\n\t\t.strict()\n\tconst toPublicDto = (row: z.input<typeof storage>) =>\n\t\tpublicDto.parse(\n\t\t\tObject.fromEntries(\n\t\t\t\tObject.keys(publicDto.shape).map((key) => [\n\t\t\t\t\tkey,\n\t\t\t\t\t(row as Record<string, unknown>)[key],\n\t\t\t\t]),\n\t\t\t),\n\t\t)\n\n\ttype InsertSchema = typeof insertSchema\n\ttype UpdateSchema = typeof updateSchema\n\ttype InsertMask = z.util.Mask<keyof InsertSchema['shape']>\n\ttype UpdateMask = z.util.Mask<keyof UpdateSchema['shape']>\n\n\tfunction insert(): InsertSchema\n\tfunction insert<OmitMask extends InsertMask>(\n\t\tomit: OmitMask,\n\t): ZodObjectOmit<InsertSchema, OmitMask>\n\tfunction insert(omit?: InsertMask) {\n\t\treturn omit ? insertSchema.omit(omit as never) : insertSchema\n\t}\n\n\tfunction update(): UpdateSchema\n\tfunction update<OmitMask extends UpdateMask>(\n\t\tomit: OmitMask,\n\t): ZodObjectOmit<UpdateSchema, OmitMask>\n\tfunction update(omit?: UpdateMask) {\n\t\treturn omit ? updateSchema.omit(omit as never) : updateSchema\n\t}\n\n\treturn {\n\t\ttableName,\n\t\tschema,\n\t\tstorage,\n\t\tinsertSchema,\n\t\tupdateSchema,\n\t\tcommandInput,\n\t\tpublicDto,\n\t\ttoPublicDto,\n\t\ttable: defineTable(zodToConvex(storage)) as TableDefinition<\n\t\t\tConvexValidatorFromZod<typeof storage, 'required'>\n\t\t>,\n\t\tinsert,\n\t\tupdate,\n\t\ttools: {\n\t\t\t// jsonSafeZid (not zid): tool masks feed generated JSON schemas, so\n\t\t\t// ids must present as plain strings while keeping the Id<...> type.\n\t\t\tinsert: commandInput,\n\t\t\tupdate: z\n\t\t\t\t.object({ data: commandInput.partial(), id: jsonSafeZid(tableName) })\n\t\t\t\t.strict(),\n\t\t\tid: z.object({ id: jsonSafeZid(tableName) }).strict(),\n\t\t},\n\t}\n}\n\nconst tenantShape = {\n\ttenant: z.string().min(1),\n} satisfies Shape\n\ntype TenantShape = typeof tenantShape\n\n/**\n * A zodTable whose rows are tenant-owned: injects the server-owned `tenant`\n * field (the tenancy boundary — see cvx-kit/tenancy). Like timestamps, it is\n * excluded from insert/update/command boundaries; handlers stamp it from\n * ctx.tenant, row-level security matches on it, and the tenantOwnership\n * trigger forbids reassigning it. Expose it via publicFields only when a DTO\n * genuinely needs it.\n */\nexport function tenantTable<\n\tTable extends string,\n\tFields extends Shape,\n\tconst ServerFields extends readonly ShapeKey<Fields>[] = readonly [],\n\tconst CommandFields extends readonly ShapeKey<Fields>[] = readonly [],\n\tconst PublicFields extends readonly ShapeKey<\n\t\tFields & TenantShape & TimestampShape\n\t>[] = readonly [],\n>(\n\ttableName: Table,\n\tfields: (id: typeof zid) => Fields,\n\toptions: TableBoundaryOptions<\n\t\tFields & TenantShape,\n\t\treadonly (ServerFields[number] | 'tenant')[],\n\t\tCommandFields,\n\t\tPublicFields\n\t> = {},\n) {\n\treturn zodTable(\n\t\ttableName,\n\t\t(id) => ({ ...fields(id), ...tenantShape }),\n\t\t{\n\t\t\t...options,\n\t\t\tserverFields: [\n\t\t\t\t...((options.serverFields ?? []) as readonly (\n\t\t\t\t\t| ServerFields[number]\n\t\t\t\t\t| 'tenant'\n\t\t\t\t)[]),\n\t\t\t\t'tenant',\n\t\t\t] as never,\n\t\t} as never,\n\t) as ReturnType<\n\t\ttypeof zodTable<\n\t\t\tTable,\n\t\t\tFields & TenantShape,\n\t\t\treadonly (ServerFields[number] | 'tenant')[],\n\t\t\tCommandFields,\n\t\t\tPublicFields\n\t\t>\n\t>\n}\n\n/**\n * Merges per-module table maps into the application schema map, rejecting\n * duplicate table names across modules — the module-registry combinator for\n * domain/table.ts: `defineSchema(createModule(catalogTables, salesTables))`.\n */\nexport function createModule<\n\tconst Maps extends readonly Record<string, TableDefinition<any>>[],\n>(...maps: Maps): UnionToIntersection<Maps[number]> {\n\tconst combined: Record<string, TableDefinition<any>> = {}\n\tfor (const map of maps) {\n\t\tfor (const [tableName, definition] of Object.entries(map)) {\n\t\t\tif (tableName in combined) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Table \"${tableName}\" is declared by more than one module`,\n\t\t\t\t)\n\t\t\t}\n\t\t\tcombined[tableName] = definition\n\t\t}\n\t}\n\treturn combined as UnionToIntersection<Maps[number]>\n}\n\ntype UnionToIntersection<Union> = (\n\tUnion extends unknown\n\t\t? (member: Union) => void\n\t\t: never\n) extends (member: infer Intersection) => void\n\t? Intersection\n\t: never\n\n/**\n * Cursor-pagination boundary schemas bridged from Convex's own validators:\n * `args.paginationOpts` for function args, `result` for the page shape.\n * Pair with `include(...).paginate(opts)` (cvx-kit/auth). The result object\n * is deliberately non-strict — Convex may attach engine fields (splitCursor,\n * pageStatus); the page items themselves are validated against the dto.\n * Note: under row-level security, pages may be SHORTER than numItems when\n * rules reject rows mid-page; cursors remain correct.\n */\nexport function paginated<Dto extends z.ZodType>(dto: Dto) {\n\treturn {\n\t\targs: { paginationOpts: convexToZod(paginationOptsValidator) },\n\t\tresult: z.object({\n\t\t\tpage: z.array(dto),\n\t\t\tisDone: z.boolean(),\n\t\t\tcontinueCursor: z.string(),\n\t\t\tsplitCursor: z.string().nullable().optional(),\n\t\t\tpageStatus: z\n\t\t\t\t.enum(['SplitRecommended', 'SplitRequired'])\n\t\t\t\t.nullable()\n\t\t\t\t.optional(),\n\t\t}),\n\t}\n}\n\n/** Preserves discriminated-union storage while retaining the same table owner. */\nexport function zodVariantTable<Table extends string, Schema extends z.ZodType>(\n\ttableName: Table,\n\tstorage: Schema,\n) {\n\treturn {\n\t\ttableName,\n\t\tstorage,\n\t\tinsertSchema: storage,\n\t\ttable: defineTable(zodToConvex(storage)),\n\t}\n}\n\n/**\n * A zid that presents as a plain string in generated JSON schemas so\n * LLM-tool inputs stay primitive, while keeping the Id type at compile time.\n */\nexport function jsonSafeZid<Table extends string>(tableName: Table) {\n\treturn z\n\t\t.string()\n\t\t.describe(\n\t\t\t`Convex document id for table \"${tableName}\"`,\n\t\t) as unknown as z.ZodType<GenericId<Table>, string>\n}\n\ntype ZodObjectOmit<\n\tSchema extends z.ZodObject<any, any>,\n\tOmitMask extends z.util.Mask<keyof Schema['shape']>,\n> =\n\tSchema extends z.ZodObject<infer ObjectShape, infer Config>\n\t\t? z.ZodObject<\n\t\t\t\tz.util.Flatten<\n\t\t\t\t\tOmit<ObjectShape, Extract<keyof ObjectShape, keyof OmitMask>>\n\t\t\t\t>,\n\t\t\t\tConfig\n\t\t\t>\n\t\t: never\n\nfunction pickShape<\n\tFields extends Shape,\n\tconst Keys extends readonly ShapeKey<Fields>[],\n>(fields: Fields, keys: Keys) {\n\treturn Object.fromEntries(keys.map((key) => [key, fields[key]])) as Pick<\n\t\tFields,\n\t\tKeys[number]\n\t>\n}\n\nfunction omitShape<\n\tFields extends Shape,\n\tconst Keys extends readonly ShapeKey<Fields>[],\n>(fields: Fields, keys: Keys) {\n\tconst omitted = new Set<string>(keys)\n\treturn Object.fromEntries(\n\t\tObject.entries(fields).filter(([key]) => !omitted.has(key)),\n\t) as Omit<Fields, Keys[number]>\n}\n"],"mappings":"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"}

package/docs/auth.md

@@ -97,6 +97,55 @@ role/organization from that check replaces the JWT's. Verification **fails
 closed**: any error or org mismatch throws `FORBIDDEN`. Omit
 `verifyMembership` to let actions trust the JWT like queries do.
 
+## Resolving org/role from the database (`resolveOrganization`)
+
+Some identity providers issue tokens that carry **no org claims** — custom
+credentials, magic codes, or apps that keep memberships in their own tables.
+For those, configure `resolveOrganization` to derive organization authority
+from the app's own data instead of the JWT.
+
+When configured, the hook is the organization authority — claim parsing is
+skipped entirely. Returning `null` **or throwing** rejects with `FORBIDDEN`
+(fail closed); a missing identity or user is still `UNAUTHENTICATED`; the
+returned `roleSlug` still passes through `mapRole` like a claim would.
+
+The handler must be **action-safe**: in actions the ctx has no `db`, so branch
+on its presence and fall back to an internal query:
+
+```ts
+import { internal } from './_generated/api'
+
+resolveOrganization: async ({ ctx, user }) => {
+  const membership =
+    'db' in ctx
+      ? await ctx.db
+          .query('companyUsers')
+          .withIndex('by_user', (q) => q.eq('userId', user.id))
+          .first()
+      : await ctx.runQuery(internal.memberships.byUser, { userId: user.id })
+  if (!membership || !membership.active) return null   // revoked ⇒ FORBIDDEN
+  return { organizationId: membership.orgId, roleSlug: membership.roleSlug }
+},
+```
+
+Resolver obligations:
+
+- Bind the lookup to the **verified** user — `user.id` (or
+  `identity.subject`), never a caller-influenced or non-unique attribute.
+- Resolve revoked/inactive/expired memberships to `null`, so revocation
+  actually takes effect fail-closed.
+
+Composition: `mapRole` still applies to the returned slug; with tenancy
+configured, `ctx.tenant` derives from the hook's org
+(`security.tenancy.resolve` is unchanged); `verifyMembership` for actions is
+unchanged and receives the hook-resolved `organizationId` — in actions its
+live result supersedes the hook's role/org, exactly as it supersedes claims.
+
+Cost: one DB read per authenticated call (claims are free); actions with
+`verifyMembership` configured also pay the live check. When debugging, note
+that a misconfigured hook surfaces as blanket `FORBIDDEN` — errors are
+swallowed fail-closed, never rethrown.
+
 ## Mutations are structurally trigger-wrapped
 
 When `triggers` (or `wrapDB`) is configured, every `authMutation`,

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/llms.md

@@ -114,6 +114,7 @@ export const { authQuery, authMutation, authAction, adminQuery, adminMutation,
   adminRoles: ['admin'],
   triggers,
   verifyMembership: async ({ userId, organizationId }) => { /* live check; actions only */ },
+  resolveOrganization: async ({ ctx, identity, user }) => { /* org+role from app tables; overrides claims; null/throw ⇒ FORBIDDEN */ },
 })
 
 // convex/foundation.ts

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.1",
+	"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)}`)
 	}