cvx-kit 0.0.1 → 0.0.3

package/dist/triggers.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"triggers.mjs","names":[],"sources":["../src/triggers.ts"],"sourcesContent":["import {\n\tTriggers,\n\ttype Change,\n\ttype Trigger,\n} from 'convex-helpers/server/triggers'\nimport type {\n\tGenericDataModel,\n\tTableNamesInDataModel,\n} from 'convex/server'\n\nexport { Triggers }\nexport type { Change, Trigger }\n\n/**\n * One application-wide mutation interceptor registry. Pass it to\n * createAuthFunctions({ triggers }) so every authMutation/roleMutation/\n * systemMutation runs writes through it — trigger enforcement becomes\n * structural, not a convention.\n */\nexport function createTriggers<\n\tDataModel extends GenericDataModel,\n>(): Triggers<DataModel> {\n\treturn new Triggers<DataModel>()\n}\n\n/**\n * Marks tables as append-only evidence tables: inserts pass, every update or\n * delete throws. The ontology pattern for votes/history/audit-style tables.\n */\nexport function appendOnly<DataModel extends GenericDataModel>(\n\ttriggers: Triggers<DataModel>,\n\t...tables: readonly TableNamesInDataModel<DataModel>[]\n) {\n\tfor (const table of tables) {\n\t\ttriggers.register(table, async (_ctx, change) => {\n\t\t\tif (change.operation !== 'insert') {\n\t\t\t\tthrow new Error(`${table} is append-only`)\n\t\t\t}\n\t\t})\n\t}\n}\n\n/** Forbids hard deletes on the given tables (soft-delete discipline). */\nexport function noDelete<DataModel extends GenericDataModel>(\n\ttriggers: Triggers<DataModel>,\n\t...tables: readonly TableNamesInDataModel<DataModel>[]\n) {\n\tfor (const table of tables) {\n\t\ttriggers.register(table, async (_ctx, change) => {\n\t\t\tif (change.operation === 'delete') {\n\t\t\t\tthrow new Error(`${table} rows cannot be deleted`)\n\t\t\t}\n\t\t})\n\t}\n}\n\n/**\n * Maintains zod-table's opinionated lifecycle timestamps: createdAt and\n * updatedAt on insert, updatedAt on every update. archivedAt stays under\n * application control. Register once per table; writes made through the\n * auth constructors keep these fields correct automatically.\n */\nexport function timestamps<DataModel extends GenericDataModel>(\n\ttriggers: Triggers<DataModel>,\n\t...tables: readonly TableNamesInDataModel<DataModel>[]\n) {\n\tfor (const table of tables) {\n\t\ttriggers.register(table, async (ctx, change) => {\n\t\t\tif (change.operation === 'delete') return\n\t\t\tconst now = Date.now()\n\t\t\tif (change.operation === 'insert') {\n\t\t\t\tconst document = change.newDoc as { createdAt?: number }\n\t\t\t\tif (document.createdAt === undefined) {\n\t\t\t\t\tawait ctx.innerDb.patch(change.id, {\n\t\t\t\t\t\tcreatedAt: now,\n\t\t\t\t\t\tupdatedAt: now,\n\t\t\t\t\t} as never)\n\t\t\t\t}\n\t\t\t\treturn\n\t\t\t}\n\t\t\tconst previous = change.oldDoc as { updatedAt?: number }\n\t\t\tconst current = change.newDoc as { updatedAt?: number }\n\t\t\t// A write that already moved updatedAt (including our own patch)\n\t\t\t// is left alone — this is the recursion guard.\n\t\t\tif (current.updatedAt === previous.updatedAt) {\n\t\t\t\tawait ctx.innerDb.patch(change.id, { updatedAt: now } as never)\n\t\t\t}\n\t\t})\n\t}\n}\n"],"mappings":"0DAmBA,SAAgB,GAES,CACxB,OAAO,IAAI,CACZ,CAMA,SAAgB,EACf,EACA,GAAG,EACF,CACD,IAAK,IAAM,KAAS,EACnB,EAAS,SAAS,EAAO,MAAO,EAAM,IAAW,CAChD,GAAI,EAAO,YAAc,SACxB,MAAU,MAAM,GAAG,EAAM,gBAAgB,CAE3C,CAAC,CAEH,CAGA,SAAgB,EACf,EACA,GAAG,EACF,CACD,IAAK,IAAM,KAAS,EACnB,EAAS,SAAS,EAAO,MAAO,EAAM,IAAW,CAChD,GAAI,EAAO,YAAc,SACxB,MAAU,MAAM,GAAG,EAAM,wBAAwB,CAEnD,CAAC,CAEH,CAQA,SAAgB,EACf,EACA,GAAG,EACF,CACD,IAAK,IAAM,KAAS,EACnB,EAAS,SAAS,EAAO,MAAO,EAAK,IAAW,CAC/C,GAAI,EAAO,YAAc,SAAU,OACnC,IAAM,EAAM,KAAK,IAAI,EACrB,GAAI,EAAO,YAAc,SAAU,CACjB,EAAO,OACX,YAAc,IAAA,IAC1B,MAAM,EAAI,QAAQ,MAAM,EAAO,GAAI,CAClC,UAAW,EACX,UAAW,CACZ,CAAU,EAEX,MACD,CACA,IAAM,EAAW,EAAO,OACR,EAAO,OAGX,YAAc,EAAS,WAClC,MAAM,EAAI,QAAQ,MAAM,EAAO,GAAI,CAAE,UAAW,CAAI,CAAU,CAEhE,CAAC,CAEH"}
+{"version":3,"file":"triggers.mjs","names":[],"sources":["../src/triggers.ts"],"sourcesContent":["import {\n\tTriggers,\n\ttype Change,\n\ttype Trigger,\n} from 'convex-helpers/server/triggers'\nimport type {\n\tGenericDataModel,\n\tTableNamesInDataModel,\n} from 'convex/server'\n\nexport { Triggers }\nexport type { Change, Trigger }\n\n/**\n * One application-wide mutation interceptor registry. Pass it to\n * createAuthFunctions({ triggers }) so every authMutation/roleMutation/\n * systemMutation runs writes through it — trigger enforcement becomes\n * structural, not a convention.\n */\nexport function createTriggers<\n\tDataModel extends GenericDataModel,\n>(): Triggers<DataModel> {\n\treturn new Triggers<DataModel>()\n}\n\n/**\n * Marks tables as append-only evidence tables: inserts pass, every update or\n * delete throws. The ontology pattern for votes/history/audit-style tables.\n */\nexport function appendOnly<DataModel extends GenericDataModel>(\n\ttriggers: Triggers<DataModel>,\n\t...tables: readonly TableNamesInDataModel<DataModel>[]\n) {\n\tfor (const table of tables) {\n\t\ttriggers.register(table, async (_ctx, change) => {\n\t\t\tif (change.operation !== 'insert') {\n\t\t\t\tthrow new Error(`${table} is append-only`)\n\t\t\t}\n\t\t})\n\t}\n}\n\n/** Forbids hard deletes on the given tables (soft-delete discipline). */\nexport function noDelete<DataModel extends GenericDataModel>(\n\ttriggers: Triggers<DataModel>,\n\t...tables: readonly TableNamesInDataModel<DataModel>[]\n) {\n\tfor (const table of tables) {\n\t\ttriggers.register(table, async (_ctx, change) => {\n\t\t\tif (change.operation === 'delete') {\n\t\t\t\tthrow new Error(`${table} rows cannot be deleted`)\n\t\t\t}\n\t\t})\n\t}\n}\n\n/**\n * Post-image tenant invariant for tenantTable rows. Row-level security\n * authorizes a modification against the PRE-image, so ownership must also be\n * enforced against the post-image: inserts must carry a tenant, and updates\n * may never reassign it. Register for every tenant table (same registry that\n * drives createTenantRules).\n */\nexport function tenantOwnership<DataModel extends GenericDataModel>(\n\ttriggers: Triggers<DataModel>,\n\t...tables: readonly TableNamesInDataModel<DataModel>[]\n) {\n\tfor (const table of tables) {\n\t\ttriggers.register(table, async (_ctx, change) => {\n\t\t\tif (change.operation === 'insert') {\n\t\t\t\tconst document = change.newDoc as { tenant?: unknown }\n\t\t\t\tif (\n\t\t\t\t\ttypeof document.tenant !== 'string' ||\n\t\t\t\t\tdocument.tenant.length === 0\n\t\t\t\t) {\n\t\t\t\t\tthrow new Error(`${table} rows require a tenant`)\n\t\t\t\t}\n\t\t\t\treturn\n\t\t\t}\n\t\t\tif (change.operation === 'update') {\n\t\t\t\tconst previous = change.oldDoc as { tenant?: unknown }\n\t\t\t\tconst current = change.newDoc as { tenant?: unknown }\n\t\t\t\tif (previous.tenant !== current.tenant) {\n\t\t\t\t\tthrow new Error(`${table} tenant ownership cannot be reassigned`)\n\t\t\t\t}\n\t\t\t}\n\t\t})\n\t}\n}\n\n/**\n * Maintains zod-table's opinionated lifecycle timestamps: createdAt and\n * updatedAt on insert, updatedAt on every update. archivedAt stays under\n * application control. Register once per table; writes made through the\n * auth constructors keep these fields correct automatically.\n */\nexport function timestamps<DataModel extends GenericDataModel>(\n\ttriggers: Triggers<DataModel>,\n\t...tables: readonly TableNamesInDataModel<DataModel>[]\n) {\n\tfor (const table of tables) {\n\t\ttriggers.register(table, async (ctx, change) => {\n\t\t\tif (change.operation === 'delete') return\n\t\t\tconst now = Date.now()\n\t\t\tif (change.operation === 'insert') {\n\t\t\t\tconst document = change.newDoc as { createdAt?: number }\n\t\t\t\tif (document.createdAt === undefined) {\n\t\t\t\t\tawait ctx.innerDb.patch(change.id, {\n\t\t\t\t\t\tcreatedAt: now,\n\t\t\t\t\t\tupdatedAt: now,\n\t\t\t\t\t} as never)\n\t\t\t\t}\n\t\t\t\treturn\n\t\t\t}\n\t\t\tconst previous = change.oldDoc as { updatedAt?: number }\n\t\t\tconst current = change.newDoc as { updatedAt?: number }\n\t\t\t// A write that already moved updatedAt (including our own patch)\n\t\t\t// is left alone — this is the recursion guard.\n\t\t\tif (current.updatedAt === previous.updatedAt) {\n\t\t\t\tawait ctx.innerDb.patch(change.id, { updatedAt: now } as never)\n\t\t\t}\n\t\t})\n\t}\n}\n"],"mappings":"0DAmBA,SAAgB,GAES,CACxB,OAAO,IAAI,CACZ,CAMA,SAAgB,EACf,EACA,GAAG,EACF,CACD,IAAK,IAAM,KAAS,EACnB,EAAS,SAAS,EAAO,MAAO,EAAM,IAAW,CAChD,GAAI,EAAO,YAAc,SACxB,MAAU,MAAM,GAAG,EAAM,gBAAgB,CAE3C,CAAC,CAEH,CAGA,SAAgB,EACf,EACA,GAAG,EACF,CACD,IAAK,IAAM,KAAS,EACnB,EAAS,SAAS,EAAO,MAAO,EAAM,IAAW,CAChD,GAAI,EAAO,YAAc,SACxB,MAAU,MAAM,GAAG,EAAM,wBAAwB,CAEnD,CAAC,CAEH,CASA,SAAgB,EACf,EACA,GAAG,EACF,CACD,IAAK,IAAM,KAAS,EACnB,EAAS,SAAS,EAAO,MAAO,EAAM,IAAW,CAChD,GAAI,EAAO,YAAc,SAAU,CAClC,IAAM,EAAW,EAAO,OACxB,GACC,OAAO,EAAS,QAAW,UAC3B,EAAS,OAAO,SAAW,EAE3B,MAAU,MAAM,GAAG,EAAM,uBAAuB,EAEjD,MACD,CACA,GAAI,EAAO,YAAc,SAAU,CAClC,IAAM,EAAW,EAAO,OAClB,EAAU,EAAO,OACvB,GAAI,EAAS,SAAW,EAAQ,OAC/B,MAAU,MAAM,GAAG,EAAM,uCAAuC,CAElE,CACD,CAAC,CAEH,CAQA,SAAgB,EACf,EACA,GAAG,EACF,CACD,IAAK,IAAM,KAAS,EACnB,EAAS,SAAS,EAAO,MAAO,EAAK,IAAW,CAC/C,GAAI,EAAO,YAAc,SAAU,OACnC,IAAM,EAAM,KAAK,IAAI,EACrB,GAAI,EAAO,YAAc,SAAU,CACjB,EAAO,OACX,YAAc,IAAA,IAC1B,MAAM,EAAI,QAAQ,MAAM,EAAO,GAAI,CAClC,UAAW,EACX,UAAW,CACZ,CAAU,EAEX,MACD,CACA,IAAM,EAAW,EAAO,OACR,EAAO,OAGX,YAAc,EAAS,WAClC,MAAM,EAAI,QAAQ,MAAM,EAAO,GAAI,CAAE,UAAW,CAAI,CAAU,CAEhE,CAAC,CAEH"}

package/dist/zod-table.d.mts

@@ -106,6 +106,26 @@ declare function zodTable<Table extends string, Fields extends Shape, const Serv
     }, z.core.$strict>;
   };
 };
+declare const tenantShape: {
+  tenant: z.ZodString;
+};
+type TenantShape = typeof tenantShape;
+/**
+ * A zodTable whose rows are tenant-owned: injects the server-owned `tenant`
+ * field (the tenancy boundary — see cvx-kit/tenancy). Like timestamps, it is
+ * excluded from insert/update/command boundaries; handlers stamp it from
+ * ctx.tenant, row-level security matches on it, and the tenantOwnership
+ * 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>>;
+/**
+ * Merges per-module table maps into the application schema map, rejecting
+ * duplicate table names across modules — the module-registry combinator for
+ * domain/table.ts: `defineSchema(createModule(catalogTables, salesTables))`.
+ */
+declare function createModule<const Maps extends readonly Record<string, TableDefinition<any>>[]>(...maps: Maps): UnionToIntersection<Maps[number]>;
+type UnionToIntersection<Union> = (Union extends unknown ? (member: Union) => void : never) extends ((member: infer Intersection) => void) ? Intersection : never;
 /** Preserves discriminated-union storage while retaining the same table owner. */
 declare function zodVariantTable<Table extends string, Schema extends z.ZodType>(tableName: Table, storage: Schema): {
   tableName: Table;
@@ -120,5 +140,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, jsonSafeZid, zodTable, zodVariantTable };
+export { TIMESTAMP_FIELDS, TableBoundaryOptions, createModule, jsonSafeZid, tenantTable, zodTable, zodVariantTable };
 //# sourceMappingURL=zod-table.d.mts.map

package/dist/zod-table.mjs

@@ -1,2 +1,2 @@
-import{zid as e,zodToConvex as t}from"convex-helpers/server/zod4";import{defineTable as n}from"convex/server";import{z as r}from"zod";const i={createdAt:r.number().optional(),updatedAt:r.number().optional(),archivedAt:r.number().optional()},a=[`createdAt`,`updatedAt`,`archivedAt`];function o(o,s,c={}){let d={...s(e),...i},f=r.object(d).strict(),p=f.extend({_id:e(o),_creationTime:r.number()}),m=r.object(u(d,[...a,...c.serverFields??[]])).strict(),h=m.partial(),g=r.object(l(d,c.commandFields??[])).strict(),_=r.object(l(d,c.publicFields??[])).strict(),v=e=>_.parse(Object.fromEntries(Object.keys(_.shape).map(t=>[t,e[t]])));function y(e){return e?m.omit(e):m}function b(e){return e?h.omit(e):h}return{tableName:o,schema:p,storage:f,insertSchema:m,updateSchema:h,commandInput:g,publicDto:_,toPublicDto:v,table:n(t(f)),insert:y,update:b,tools:{insert:g,update:r.object({data:g.partial(),id:e(o)}).strict(),id:r.object({id:e(o)}).strict()}}}function s(e,r){return{tableName:e,storage:r,insertSchema:r,table:n(t(r))}}function c(e){return r.string().describe(`Convex document id for table "${e}"`)}function l(e,t){return Object.fromEntries(t.map(t=>[t,e[t]]))}function u(e,t){let n=new Set(t);return Object.fromEntries(Object.entries(e).filter(([e])=>!n.has(e)))}export{a as TIMESTAMP_FIELDS,c as jsonSafeZid,o as zodTable,s as zodVariantTable};
+import{zid as e,zodToConvex as t}from"convex-helpers/server/zod4";import{defineTable as n}from"convex/server";import{z as r}from"zod";const i={createdAt:r.number().optional(),updatedAt:r.number().optional(),archivedAt:r.number().optional()},a=[`createdAt`,`updatedAt`,`archivedAt`];function o(o,s,c={}){let l={...s(e),...i},u=r.object(l).strict(),d=u.extend({_id:e(o),_creationTime:r.number()}),m=r.object(p(l,[...a,...c.serverFields??[]])).strict(),h=m.partial(),g=r.object(f(l,c.commandFields??[])).strict(),_=r.object(f(l,c.publicFields??[])).strict(),v=e=>_.parse(Object.fromEntries(Object.keys(_.shape).map(t=>[t,e[t]])));function y(e){return e?m.omit(e):m}function b(e){return e?h.omit(e):h}return{tableName:o,schema:d,storage:u,insertSchema:m,updateSchema:h,commandInput:g,publicDto:_,toPublicDto:v,table:n(t(u)),insert:y,update:b,tools:{insert:g,update:r.object({data:g.partial(),id:e(o)}).strict(),id:r.object({id:e(o)}).strict()}}}const s={tenant:r.string().min(1)};function c(e,t,n={}){return o(e,e=>({...t(e),...s}),{...n,serverFields:[...n.serverFields??[],`tenant`]})}function l(...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 u(e,r){return{tableName:e,storage:r,insertSchema:r,table:n(t(r))}}function d(e){return r.string().describe(`Convex document id for table "${e}"`)}function f(e,t){return Object.fromEntries(t.map(t=>[t,e[t]]))}function p(e,t){let n=new Set(t);return Object.fromEntries(Object.entries(e).filter(([e])=>!n.has(e)))}export{a as TIMESTAMP_FIELDS,l as createModule,d as jsonSafeZid,c as tenantTable,o as zodTable,u 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\tzid,\n\tzodToConvex,\n} from 'convex-helpers/server/zod4'\nimport { defineTable, type TableDefinition } 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\tinsert: commandInput,\n\t\t\tupdate: z\n\t\t\t\t.object({ data: commandInput.partial(), id: zid(tableName) })\n\t\t\t\t.strict(),\n\t\t\tid: z.object({ id: zid(tableName) }).strict(),\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":"sIAiBA,MAAM,EAAiB,CACtB,UAAW,EAAE,OAAO,CAAC,CAAC,SAAS,EAC/B,UAAW,EAAE,OAAO,CAAC,CAAC,SAAS,EAC/B,WAAY,EAAE,OAAO,CAAC,CAAC,SAAS,CACjC,EAIa,EAAmB,CAC/B,YACA,YACA,YACD,EAcA,SAAgB,EASf,EACA,EACA,EAKI,CAAC,EACJ,CACD,IAAM,EAAQ,CAAE,GAAG,EAAO,CAAG,EAAG,GAAG,CAAe,EAE5C,EAAU,EAAE,OAAO,CAAK,CAAC,CAAC,OAAO,EACjC,EAAS,EAAQ,OAAO,CAC7B,IAAK,EAAI,CAAS,EAClB,cAAe,EAAE,OAAO,CACzB,CAAC,EACK,EAAe,EACnB,OACA,EAAU,EAAO,CAChB,GAAG,EACH,GAAI,EAAQ,cAAiB,CAAC,CAC/B,CAAU,CACX,CAAC,CACA,OAAO,EAGH,EAAe,EAAa,QAAQ,EACpC,EAAe,EACnB,OAAO,EAAU,EAAO,EAAQ,eAAkB,CAAC,CAAW,CAAC,CAAC,CAChE,OAAO,EACH,EAAY,EAChB,OAAO,EAAU,EAAO,EAAQ,cAAiB,CAAC,CAAW,CAAC,CAAC,CAC/D,OAAO,EACH,EAAe,GACpB,EAAU,MACT,OAAO,YACN,OAAO,KAAK,EAAU,KAAK,CAAC,CAAC,IAAK,GAAQ,CACzC,EACC,EAAgC,EAClC,CAAC,CACF,CACD,EAWD,SAAS,EAAO,EAAmB,CAClC,OAAO,EAAO,EAAa,KAAK,CAAa,EAAI,CAClD,CAMA,SAAS,EAAO,EAAmB,CAClC,OAAO,EAAO,EAAa,KAAK,CAAa,EAAI,CAClD,CAEA,MAAO,CACN,YACA,SACA,UACA,eACA,eACA,eACA,YACA,cACA,MAAO,EAAY,EAAY,CAAO,CAAC,EAGvC,SACA,SACA,MAAO,CACN,OAAQ,EACR,OAAQ,EACN,OAAO,CAAE,KAAM,EAAa,QAAQ,EAAG,GAAI,EAAI,CAAS,CAAE,CAAC,CAAC,CAC5D,OAAO,EACT,GAAI,EAAE,OAAO,CAAE,GAAI,EAAI,CAAS,CAAE,CAAC,CAAC,CAAC,OAAO,CAC7C,CACD,CACD,CAGA,SAAgB,EACf,EACA,EACC,CACD,MAAO,CACN,YACA,UACA,aAAc,EACd,MAAO,EAAY,EAAY,CAAO,CAAC,CACxC,CACD,CAMA,SAAgB,EAAkC,EAAkB,CACnE,OAAO,EACL,OAAO,CAAC,CACR,SACA,iCAAiC,EAAU,EAC5C,CACF,CAeA,SAAS,EAGP,EAAgB,EAAY,CAC7B,OAAO,OAAO,YAAY,EAAK,IAAK,GAAQ,CAAC,EAAK,EAAO,EAAI,CAAC,CAAC,CAIhE,CAEA,SAAS,EAGP,EAAgB,EAAY,CAC7B,IAAM,EAAU,IAAI,IAAY,CAAI,EACpC,OAAO,OAAO,YACb,OAAO,QAAQ,CAAM,CAAC,CAAC,QAAQ,CAAC,KAAS,CAAC,EAAQ,IAAI,CAAG,CAAC,CAC3D,CACD"}
+{"version":3,"file":"zod-table.mjs","names":[],"sources":["../src/zod-table.ts"],"sourcesContent":["import {\n\ttype ConvexValidatorFromZod,\n\tzid,\n\tzodToConvex,\n} from 'convex-helpers/server/zod4'\nimport { defineTable, type TableDefinition } 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\tinsert: commandInput,\n\t\t\tupdate: z\n\t\t\t\t.object({ data: commandInput.partial(), id: zid(tableName) })\n\t\t\t\t.strict(),\n\t\t\tid: z.object({ id: zid(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/** 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":"sIAiBA,MAAM,EAAiB,CACtB,UAAW,EAAE,OAAO,CAAC,CAAC,SAAS,EAC/B,UAAW,EAAE,OAAO,CAAC,CAAC,SAAS,EAC/B,WAAY,EAAE,OAAO,CAAC,CAAC,SAAS,CACjC,EAIa,EAAmB,CAC/B,YACA,YACA,YACD,EAcA,SAAgB,EASf,EACA,EACA,EAKI,CAAC,EACJ,CACD,IAAM,EAAQ,CAAE,GAAG,EAAO,CAAG,EAAG,GAAG,CAAe,EAE5C,EAAU,EAAE,OAAO,CAAK,CAAC,CAAC,OAAO,EACjC,EAAS,EAAQ,OAAO,CAC7B,IAAK,EAAI,CAAS,EAClB,cAAe,EAAE,OAAO,CACzB,CAAC,EACK,EAAe,EACnB,OACA,EAAU,EAAO,CAChB,GAAG,EACH,GAAI,EAAQ,cAAiB,CAAC,CAC/B,CAAU,CACX,CAAC,CACA,OAAO,EAGH,EAAe,EAAa,QAAQ,EACpC,EAAe,EACnB,OAAO,EAAU,EAAO,EAAQ,eAAkB,CAAC,CAAW,CAAC,CAAC,CAChE,OAAO,EACH,EAAY,EAChB,OAAO,EAAU,EAAO,EAAQ,cAAiB,CAAC,CAAW,CAAC,CAAC,CAC/D,OAAO,EACH,EAAe,GACpB,EAAU,MACT,OAAO,YACN,OAAO,KAAK,EAAU,KAAK,CAAC,CAAC,IAAK,GAAQ,CACzC,EACC,EAAgC,EAClC,CAAC,CACF,CACD,EAWD,SAAS,EAAO,EAAmB,CAClC,OAAO,EAAO,EAAa,KAAK,CAAa,EAAI,CAClD,CAMA,SAAS,EAAO,EAAmB,CAClC,OAAO,EAAO,EAAa,KAAK,CAAa,EAAI,CAClD,CAEA,MAAO,CACN,YACA,SACA,UACA,eACA,eACA,eACA,YACA,cACA,MAAO,EAAY,EAAY,CAAO,CAAC,EAGvC,SACA,SACA,MAAO,CACN,OAAQ,EACR,OAAQ,EACN,OAAO,CAAE,KAAM,EAAa,QAAQ,EAAG,GAAI,EAAI,CAAS,CAAE,CAAC,CAAC,CAC5D,OAAO,EACT,GAAI,EAAE,OAAO,CAAE,GAAI,EAAI,CAAS,CAAE,CAAC,CAAC,CAAC,OAAO,CAC7C,CACD,CACD,CAEA,MAAM,EAAc,CACnB,OAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CACzB,EAYA,SAAgB,EASf,EACA,EACA,EAKI,CAAC,EACJ,CACD,OAAO,EACN,EACC,IAAQ,CAAE,GAAG,EAAO,CAAE,EAAG,GAAG,CAAY,GACzC,CACC,GAAG,EACH,aAAc,CACb,GAAK,EAAQ,cAAgB,CAAC,EAI9B,QACD,CACD,CACD,CASD,CAOA,SAAgB,EAEd,GAAG,EAA+C,CACnD,IAAM,EAAiD,CAAC,EACxD,IAAK,IAAM,KAAO,EACjB,IAAK,GAAM,CAAC,EAAW,KAAe,OAAO,QAAQ,CAAG,EAAG,CAC1D,GAAI,KAAa,EAChB,MAAU,MACT,UAAU,EAAU,sCACrB,EAED,EAAS,GAAa,CACvB,CAED,OAAO,CACR,CAWA,SAAgB,EACf,EACA,EACC,CACD,MAAO,CACN,YACA,UACA,aAAc,EACd,MAAO,EAAY,EAAY,CAAO,CAAC,CACxC,CACD,CAMA,SAAgB,EAAkC,EAAkB,CACnE,OAAO,EACL,OAAO,CAAC,CACR,SACA,iCAAiC,EAAU,EAC5C,CACF,CAeA,SAAS,EAGP,EAAgB,EAAY,CAC7B,OAAO,OAAO,YAAY,EAAK,IAAK,GAAQ,CAAC,EAAK,EAAO,EAAI,CAAC,CAAC,CAIhE,CAEA,SAAS,EAGP,EAAgB,EAAY,CAC7B,IAAM,EAAU,IAAI,IAAY,CAAI,EACpC,OAAO,OAAO,YACb,OAAO,QAAQ,CAAM,CAAC,CAAC,QAAQ,CAAC,KAAS,CAAC,EAAQ,IAAI,CAAG,CAAC,CAC3D,CACD"}

package/docs/approvals.md

@@ -0,0 +1,152 @@
+# `cvx-kit/components/approvals` — declarative approval workflows
+
+A self-contained Convex component for human-in-the-loop approval flows:
+declarative step lists (decision / branch / mutation / action / notify) with
+count quorum, maker-checker, expiry, compatibility keys, durable execution via
+a **nested** `@convex-dev/workflow`, and its own audit trail via a **nested**
+`convex-audit-log`. The component never imports host code: tenancy is an
+opaque `scopeRef`, resources are opaque `resourceType`/`resourceRef` strings,
+and callbacks cross the boundary as **function handles**.
+
+## Mounting
+
+```ts
+// convex/convex.config.ts
+import approvals from 'cvx-kit/components/approvals'
+app.use(approvals)
+```
+
+The component mounts its own private `workflow` and `auditLog` children. Do
+**not** re-register those children at the app root under the same identity,
+and never reach into `components.approvals.workflow` / `.auditLog` from host
+code — the `Approvals` client class is the only contract.
+
+```ts
+// convex/approvals.ts — host facade, declared once
+import { Approvals } from 'cvx-kit/components/approvals'
+import { components } from './_generated/api'
+
+export const approvals = new Approvals(components.approvals)
+```
+
+## Defining a workflow — in the owning domain
+
+Workflow *definitions* are business logic and live in the domain that owns the
+resource, not in the root facade:
+
+```ts
+// convex/domain/documents/approval.ts
+import { approvals } from '../../approvals'
+import { internal } from '../../_generated/api'
+
+export const publishApproval = approvals.define({
+  name: 'documentPublish',
+  steps: [
+    approvals.decision('managerDecision', {
+      decisions: ['approved', 'rejected'],
+      quorum: { kind: 'count', approvals: 1 },
+      makerChecker: true,                  // requester cannot decide
+      expiresAfterMs: 7 * 24 * 60 * 60 * 1000,
+    }),
+    approvals.branch('applyDecision', {
+      approvedStepKey: 'publishDocument',
+      rejectedStepKey: 'notifyRejected',
+    }),
+    approvals.mutation('publishDocument', {
+      handler: internal.domain.documents.approval_functions.applyDecision,
+    }),
+    approvals.notify('notifyRejected', {
+      handler: internal.domain.documents.approval_functions.notifyRejected,
+      retry: true,
+    }),
+  ],
+})
+```
+
+### Step kinds
+
+| Step | Runs | Notes |
+|---|---|---|
+| `decision(key, { decisions, quorum, makerChecker?, expiresAfterMs? })` | waits for humans | quorum is `{ kind: 'count', approvals: n }`; expiry resolves the run as `expired` |
+| `branch(key, { approvedStepKey, rejectedStepKey })` | routing | jumps by the preceding decision's outcome |
+| `mutation(key, { handler, retry? })` | internal mutation handle | transactional apply step |
+| `action(key, { handler, retry? })` | internal action handle | side effects (third parties) |
+| `notify(key, { handler, retry? })` | internal action handle | semantically a notification; same contract as action |
+
+Limits (enforced by the component's validators): ≤ 32 steps per workflow,
+≤ 8 decisions per decision step, names ≤ 96 chars, references ≤ 256 chars,
+metadata ≤ 32 entries (keys ≤ 64, values ≤ 512 chars).
+
+### Compatibility keys
+
+`compatibilityKey` (defaults to `name`) versions the workflow shape. Every
+`decide`/`cancel`/`status`/`restart` call sends it, so a run started under an
+old definition cannot be driven by an incompatible new one. When you change a
+workflow's steps in a breaking way, change the key.
+
+## Driving a run
+
+```ts
+// start — from an authMutation, with ctx.actor as the requester
+const { runId } = await publishApproval.start(ctx, {
+  scopeRef: ctx.org.organizationId,        // opaque tenancy
+  resourceType: 'document',
+  resourceRef: documentId,                 // opaque to the component
+  requester: ctx.actor,
+  metadata: { title },                     // bounded string map
+})
+
+// decide — a manager approves or rejects
+await publishApproval.decide(ctx, { runId, decision: 'approved', reason }, ctx.actor)
+
+// observe
+await publishApproval.status(ctx, runId)   // pending | approved | rejected | expired | canceled
+await publishApproval.evidence(ctx, runId) // per-step decision evidence
+await publishApproval.list(ctx, { scopeRef, ... })
+
+// manage
+await publishApproval.cancel(ctx, runId, ctx.actor)
+await publishApproval.restart(ctx, runId)
+await approvals.cleanupAudit(ctx, { olderThanDays: 365, batchSize: 100 })
+```
+
+## Callback handlers — validate everything coming back
+
+Step handlers are **internal** functions (build them with `systemMutation` /
+`systemAction`). They receive `ApprovalCallbackInput`: `{ runId, scopeRef,
+resourceType, resourceRef, metadata?, decision? }` — all opaque strings.
+Because the component cannot know your tables, the handler must re-establish
+trust:
+
+```ts
+export const applyDecision = systemMutation({
+  args: approvalCallbackArgs,
+  handler: async (ctx, input) => {
+    if (input.resourceType !== 'document') throw new Error('WRONG_RESOURCE')
+    const id = ctx.db.normalizeId('documents', input.resourceRef)
+    if (!id) throw new Error('BAD_REF')
+    const document = await ctx.db.get(id)
+    // guard against stale runs: the doc must still point at this run
+    if (document?.approvalRunId !== input.runId) return
+    await ctx.db.patch(id, { reviewState: 'published' })
+  },
+})
+```
+
+That `approvalRunId` check is the idempotency/staleness guard from the origin
+app — copy it.
+
+## Rules and footguns
+
+1. Root facade (`convex/approvals.ts`) instantiates the client; workflow
+   *definitions* live in the owning domain.
+2. Handlers get opaque strings — always `normalizeId`, re-check
+   `resourceType`, and verify the resource still references the run.
+3. `makerChecker: true` means the requester's decisions are rejected — design
+   your UI accordingly.
+4. The component keeps its own audit trail (retention category
+   `approval-protocol`, cleanup via `cleanupAudit`, retention 1–3650 days,
+   batch ≤ 100). Host-side business audit still goes through your command
+   protocol — they are different trails.
+5. Changing steps without changing `compatibilityKey` lets old runs be driven
+   by a new incompatible shape; bump the key on breaking changes.

package/docs/architecture.md

@@ -0,0 +1,124 @@
+# Architecture — the shape of a cvx-kit application
+
+cvx-kit was extracted from a production Convex application (~12k LOC backend).
+This document describes the architecture that application follows and that the
+kit is designed to reproduce: strict ownership boundaries, injected policy,
+portable components, and conventions that are *executable* (enforced by tests)
+rather than aspirational.
+
+## The layers
+
+```
+convex/
+  convex.config.ts        # component mounting — each app.use(x) exactly once
+  schema.ts               # defineSchema(domainTables) — nothing else
+  functions.ts            # createAuthFunctions(...) — the ONLY place raw builders appear
+  foundation.ts           # const { Command, Query, observability } = new Foundation(...)
+  approvals.ts            # const approvals = new Approvals(components.approvals)
+  audit.ts                # writeAuditEntry over convex-audit-log + admin readers
+  triggers.ts             # the single Triggers registry + helper registrations
+  auth.ts / auth.config.ts / http.ts   # identity provider wiring (e.g. WorkOS AuthKit)
+  api/                    # PUBLIC surface — thin adapters only
+    <documents>.ts          #   authQuery/authMutation wrapping domain executors
+  domain/
+    table.ts              # merges per-domain table maps into domainTables
+    shared/               # genuinely cross-entity helpers only
+    <entity>/            # one directory per entity/aggregate
+      schema.ts           #   zodTable declaration (shapes only)
+      table.ts            #   indexes attached to <zodTable>.table
+      constants.ts        #   finite vocabularies (UPPER_SNAKE readonly tuples)
+      commands.ts         #   operation registry + executors (new Command(...))
+      queries.ts          #   domain read logic
+      approval.ts         #   approvals.define(...) workflow definitions
+      *_functions.ts      #   internal callbacks (systemMutation/systemAction)
+```
+
+### Layer rules
+
+1. **`api/` is the only public surface.** It contains no bare `query(` or
+   `mutation(` — only `auth*`/`role*`/`admin*` constructors delegating to
+   domain `execute*` functions. Public functions are adapters: parse, pass
+   `ctx.actor`, project DTOs.
+2. **`domain/<entity>/` owns everything about the entity** — its zod shape,
+   indexes, vocabularies, commands, queries, workflows. Cross-domain reuse
+   goes through `domain/shared/`, never sibling imports of another domain's
+   internals.
+3. **Root files are facades over mounted components.** `foundation.ts`,
+   `approvals.ts`, `audit.ts` configure infrastructure; business definitions
+   stay in the owning domain.
+4. **Internal functions use `systemMutation`/`systemAction`** — never raw
+   `internalMutation(`/`internalAction(` — so triggers and `include` apply to
+   scheduled/callback work too.
+
+## Injection, not import
+
+The kit's central design rule: **library code never imports app singletons**.
+Every kit surface takes its policy as a parameter:
+
+- `createAuthFunctions` receives the generated builders, `getAuthUser`,
+  `mapRole`, `verifyMembership`, `triggers`, `errors`.
+- `Foundation` receives `classifyError`, `writeAudit`, the `enabled` flag.
+- `Approvals` receives only its component reference; host data crosses as
+  opaque validated strings.
+
+The reverse rule holds for components: a portable component must not import
+host domains, generated host APIs, environment configuration, or vendor SDKs
+(WorkOS, Drizzle, Redis…). Host values cross its public API only as
+**validated, bounded, opaque data** — `scopeRef`, `resourceRef`, function
+handles. Component schemas contain only their own records and never mirror a
+private child component's tables.
+
+## Boundaries as schemas
+
+Data crossing any boundary is a zod schema derived from one `zodTable`
+declaration per entity (see `zod-table.md`):
+
+- storage → `defineTable` via `zodToConvex`
+- writes → `insertSchema`/`updateSchema` (server fields and timestamps
+  excluded)
+- commands → `commandInput` (explicit allowlist)
+- clients → `publicDto` + `toPublicDto` (runtime redaction)
+- LLM tools → `tools.*` and `jsonSafeZid`
+
+Everything is `.strict()`. There is exactly one source of truth per entity and
+no boundary that "just trusts" its input.
+
+## Writes as commands
+
+State changes flow through the audited command protocol (see `commands.md`):
+parse input → observe → run handler → parse output → write audit — one
+transaction, rollback-consistent. Classifications and audit derivation are
+type-required per operation. Human-gated changes use the approvals component;
+its apply steps are commands too.
+
+## Conventions worth enforcing with tests
+
+The origin app enforces its architecture with a test suite that raw-globs the
+source and asserts violations — each rule proved against a synthetic fixture
+first so the checker can't silently pass. Highly recommended for consumers:
+
+- **No inline tables/schemas** — `defineTable`/`defineSchema` only in
+  `table.ts`/`schema.ts`.
+- **No inline enums** — `z.enum([...])` with an inline array literal is
+  banned; vocabularies are named `UPPER_SNAKE` tuples in `constants.ts`.
+- **No deep server imports** — components consumed only through their
+  `client.ts` facade; explicit allowlist for exceptions.
+- **No handwritten references** — `makeFunctionReference` banned; use
+  generated `internal`/`api`.
+- **No sibling-domain imports** — a domain reaches another only via
+  `domain/shared/` or the public API.
+- **Facades mount once** — every `app.use(x)` appears exactly once; facades
+  never reach a component's private children.
+- **Component boundary tests** — no host imports, no
+  `process.env`/vendor-SDK references inside `components/*`.
+- **Copyability** — copy the component to a tmpdir with only its package
+  deps, run `tsc`: proves portability continuously.
+
+## Component mounting order
+
+In `convex.config.ts`, mount infrastructure before consumers: auth kit →
+foundation → audit log → approvals → named workflow/workpool instances. Use
+`app.use(x, { name })` when mounting the same component twice; `components.
+<name>` keys off that name. Required env vars can be declared on
+`defineApp({ env: { ... } })` so deploys fail fast — remember to stub them in
+test setup.

package/docs/auth.md

@@ -0,0 +1,167 @@
+# `cvx-kit/auth` — auth-aware function constructors from injected policy
+
+`createAuthFunctions` builds the function constructors your whole backend uses
+in place of raw `query`/`mutation`/`action`. Nothing in the kit imports your
+app's singletons — identity resolution, role vocabulary, membership
+verification, trigger wrapping, and error policy are all **injected** by the
+host. The kit provides the structure; the app provides the policy.
+
+## Setup — declared once per app
+
+```ts
+// convex/functions.ts (the single place constructors are built)
+import { createAuthFunctions, defaultRoleMap } from 'cvx-kit/auth'
+import {
+  action, internalAction, internalMutation, 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,
+  systemMutation, systemAction,
+  include, authenticatedUser,
+} = createAuthFunctions<DataModel>({
+  query, mutation, action, 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
+  },
+})
+```
+
+Every function in the app is then built from these — raw `query`/`mutation`
+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)` |
+| `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.
+
+## What handlers receive on `ctx`
+
+Authenticated constructors extend the ctx with a frozen auth bundle:
+
+- `ctx.identity` — the raw `UserIdentity` (JWT claims)
+- `ctx.user.id` — the synchronized principal id (from `getAuthUser`)
+- `ctx.org` — `{ organizationId, role }`
+- `ctx.role` — the mapped role
+- `ctx.actor` — `{ userId, organizationId, role }` — pass this to audits,
+  approvals, and commands as the canonical actor reference
+- `ctx.include` — the bounded query builder (below)
+
+`systemMutation` gets `include` and trigger wrapping but no auth bundle.
+
+## Role vocabulary is per-app
+
+`mapRole` maps the identity's role slug onto **your** role union; returning
+`null` rejects with `FORBIDDEN`, so unknown roles never pass. The default
+(`defaultRoleMap`) is WorkOS-flavored: `member → writer`, and
+`reader`/`writer`/`admin` pass through.
+
+Supply your own vocabulary via the generic:
+
+```ts
+createAuthFunctions<DataModel, 'viewer' | 'editor' | 'owner'>({
+  mapRole: (slug) => (slug === 'owner' ? 'owner' : slug === 'editor' ? 'editor' : slug ? 'viewer' : null),
+  adminRoles: ['owner'],
+  ...
+})
+```
+
+## Queries/mutations trust the JWT; actions re-verify
+
+Queries and mutations read org and role from the identity token. Actions —
+which can run long and call third parties — additionally call
+`verifyMembership` **live** before the handler runs, and the fresher
+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.
+
+## Mutations are structurally trigger-wrapped
+
+When `triggers` (or `wrapDB`) is configured, every `authMutation`,
+`roleMutation`, and `systemMutation` runs its writes through
+`triggers.wrapDB(ctx)`. Trigger enforcement (timestamps, append-only,
+no-delete, denormalization) is therefore **structural** — a handler cannot
+forget it, because it never sees an unwrapped `ctx.db`. This is the reason raw
+`mutation` must not be used outside `functions.ts`.
+
+## `include()` — every read is bounded
+
+`include` wraps a table query in a fluent selector that (a) picks the first
+matching indexed query and (b) refuses unbounded reads. `execute(limit)`
+rejects limits outside `1..maxRows` (default 100, configurable via
+`maxIncludedQueryRows`).
+
+```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)),
+})
+```
+
+Selector methods:
+
+- `.when(value, select)` — if `value` is non-null and nothing selected yet,
+  use `select(query, value)`.
+- `.matching(indexName, range?, shouldMatch?)` — index selection with an
+  optional guard boolean.
+- `.otherwise(select)` — fallback, returns the raw `Query`.
+- `.resolve()` — selected query or full table scan (escape hatch).
+- `.execute(limit, transform?)` — bounded `take` + optional projection. This
+  is the normal terminal.
+
+## Row-level security and tenancy (optional)
+
+The `security` config adds structural RLS to every `auth*`/`role*`/`admin*`
+constructor — role-level rules (`security.rules`, standalone), tenant
+isolation from a table registry (`security.tenancy`, opt-in), or both
+AND-composed. Queries get a wrapped reader; mutations wrap triggers first,
+then the RLS writer; `system*` stays unwrapped. With tenancy configured, ctx
+gains `ctx.tenant` (actions re-derive it from live verification). Full
+treatment: `tenancy.md`.
+
+## Errors
+
+All rejections go through the injected `ErrorFactory` (default: throws
+`KitError` with codes `UNAUTHENTICATED`, `FORBIDDEN`,
+`INVALID_REQUEST_BOUNDARY`). Hosts with their own error taxonomy adapt it:
+
+```ts
+errors: { throw: (input) => { throw App.errors.from(input) } }
+```
+
+## Rules of thumb
+
+1. Build constructors once in `convex/functions.ts`; import them everywhere
+   else. Raw `_generated/server` builders appear nowhere else.
+2. Public functions: `auth*`/`role*`/`admin*`. Scheduled/internal work:
+   `system*`. Never expose an unauthenticated public function unless it is
+   deliberately anonymous (and then document why).
+3. Reads go through `ctx.include(...)` with an explicit limit.
+4. Use `ctx.actor` as the actor reference in audits and approvals — never
+   re-derive identity in a handler.