cvx-kit 0.0.3 → 0.0.5

package/dist/components/foundation/client.d.mts

@@ -5,7 +5,7 @@ import { Result, ResultBoundary, TransactionMetricsContext, executeResultBoundar
 import { emitSemanticEvent } from "./telemetry.mjs";
 import _default from "./convex.config.mjs";
 declare namespace client_d_exports {
-  export { ApplicationCommand, AuditEntryInput, AuditWriter, AuditedOperation, AuditedRegistry, CommandDefaults, CommandExecution, CommandInput, CommandObservation, CommandRegistry, CommandResult, Foundation, FoundationOptions, Observability, ObservabilityOptions, Parseable, PermissionChecker, Query, QueryExecution, Result, ResultBoundary, TransactionMetricsContext, _default as default, emitSemanticEvent, executeResultBoundary, projectResult };
+  export { ApplicationCommand, AuditEntryInput, AuditWriter, AuditedOperation, AuditedRegistry, CommandDefaults, CommandExecution, CommandInput, CommandObservation, CommandRegistry, CommandResult, Foundation, FoundationOptions, ObservabilityOptions, Parseable, PermissionChecker, QueryExecution, Result, ResultBoundary, TransactionMetricsContext, _default as default };
 }
 /** Shape handed to the injected audit writer; classification comes from the operation. */
 type AuditEntryInput = {
@@ -123,8 +123,12 @@ declare class Foundation<Component extends FoundationComponentApi = FoundationCo
   readonly Command: CommandConstructor;
   readonly Query: typeof Query;
   readonly observability: Observability;
+  /** Typed-failure boundary — see result.ts. Facade-bound like the kernels. */
+  readonly executeResultBoundary: typeof executeResultBoundary;
+  readonly projectResult: typeof projectResult;
+  readonly emitSemanticEvent: typeof emitSemanticEvent;
   constructor(component: Component, options: FoundationOptions);
 }
 //#endregion
-export { ApplicationCommand, AuditEntryInput, AuditWriter, AuditedOperation, AuditedRegistry, CommandDefaults, type CommandExecution, type CommandInput, type CommandObservation, type CommandRegistry, type CommandResult, Foundation, FoundationOptions, Observability, type ObservabilityOptions, type Parseable, PermissionChecker, Query, type QueryExecution, type Result, type ResultBoundary, type TransactionMetricsContext, client_d_exports, _default as default, emitSemanticEvent, executeResultBoundary, projectResult };
+export { ApplicationCommand, AuditEntryInput, AuditWriter, AuditedOperation, AuditedRegistry, CommandDefaults, type CommandExecution, type CommandInput, type CommandObservation, type CommandRegistry, type CommandResult, Foundation, FoundationOptions, type ObservabilityOptions, type Parseable, PermissionChecker, type QueryExecution, type Result, type ResultBoundary, type TransactionMetricsContext, client_d_exports, _default as default };
 //# sourceMappingURL=client.d.mts.map

package/dist/components/foundation/client.mjs

@@ -1,2 +1,2 @@
-import{Command as e}from"./modules/command/command.mjs";import{Observability as t}from"./modules/observability/observability.mjs";import{Query as n}from"./modules/query/query.mjs";import{executeResultBoundary as r,projectResult as i}from"./result.mjs";import{emitSemanticEvent as a}from"./telemetry.mjs";import o from"./convex.config.mjs";var s=class{#e;#t;#n;#r;#i;aggregates;static operation(e){return e}constructor(t,n){this.#t=n.observability,this.#n=n.writeAudit,this.#r=n.checkPermission,this.#i=n.defaults??{},this.aggregates=Object.freeze(Object.fromEntries(Object.entries(t).map(([e,t])=>[e,t.aggregates]))),this.#e=new e({operations:t,execute:e=>this.#a(e)})}exec(e){return this.#e.exec(e)}async#a(e){return this.#t.observe({operation:e.operation,classification:e.definition.classification},async()=>{let t=e.definition.permission;if(t!==void 0){if(!this.#r)throw new l(e.operation);await this.#r(e.context,{permission:t,operation:e.operation})}await this.#i.guard?.(e.context),await e.definition.guard?.(e.context,e.command);let n=await e.run(),r=await e.definition.audit({command:e.command,result:n},e.context);if(r){let t=e.definition.aggregates;if(t&&!t.includes(r.aggregate.type))throw new c(e.operation,r.aggregate.type);await this.#n(e.context,{...r,classification:e.definition.classification})}return n})}},c=class extends Error{code=`COMMAND_AGGREGATE_NOT_DECLARED`;name=`CommandAggregateError`;constructor(e,t){super(`Operation "${e}" audited aggregate type "${t}" outside its declared aggregates`)}},l=class extends Error{code=`COMMAND_PERMISSION_NOT_CONFIGURED`;name=`CommandPermissionError`;constructor(e){super(`Operation "${e}" declares a permission but the Foundation has no checkPermission`)}},u=class{status;Command;Query=n;observability;constructor(e,n){this.status=e.functions.status;let r=new t(n.observability);this.observability=r;let i=n.observability.writeAudit??(()=>void 0),a=n.checkPermission;this.Command=class extends s{constructor(e,t){super(e,{observability:r,writeAudit:i,checkPermission:a,defaults:t})}}}};export{u as Foundation,t as Observability,n as Query,o as default,a as emitSemanticEvent,r as executeResultBoundary,i as projectResult};
+import{Command as e}from"./modules/command/command.mjs";import{Observability as t}from"./modules/observability/observability.mjs";import{Query as n}from"./modules/query/query.mjs";import{executeResultBoundary as r,projectResult as i}from"./result.mjs";import{emitSemanticEvent as a}from"./telemetry.mjs";import o from"./convex.config.mjs";var s=class{#e;#t;#n;#r;#i;aggregates;static operation(e){return e}constructor(t,n){this.#t=n.observability,this.#n=n.writeAudit,this.#r=n.checkPermission,this.#i=n.defaults??{},this.aggregates=Object.freeze(Object.fromEntries(Object.entries(t).map(([e,t])=>[e,t.aggregates]))),this.#e=new e({operations:t,execute:e=>this.#a(e)})}exec(e){return this.#e.exec(e)}async#a(e){return this.#t.observe({operation:e.operation,classification:e.definition.classification},async()=>{let t=e.definition.permission;if(t!==void 0){if(!this.#r)throw new l(e.operation);await this.#r(e.context,{permission:t,operation:e.operation})}await this.#i.guard?.(e.context),await e.definition.guard?.(e.context,e.command);let n=await e.run(),r=await e.definition.audit({command:e.command,result:n},e.context);if(r){let t=e.definition.aggregates;if(t&&!t.includes(r.aggregate.type))throw new c(e.operation,r.aggregate.type);await this.#n(e.context,{...r,classification:e.definition.classification})}return n})}},c=class extends Error{code=`COMMAND_AGGREGATE_NOT_DECLARED`;name=`CommandAggregateError`;constructor(e,t){super(`Operation "${e}" audited aggregate type "${t}" outside its declared aggregates`)}},l=class extends Error{code=`COMMAND_PERMISSION_NOT_CONFIGURED`;name=`CommandPermissionError`;constructor(e){super(`Operation "${e}" declares a permission but the Foundation has no checkPermission`)}},u=class{status;Command;Query=n;observability;executeResultBoundary=r;projectResult=i;emitSemanticEvent=a;constructor(e,n){this.status=e.functions.status;let r=new t(n.observability);this.observability=r;let i=n.observability.writeAudit??(()=>void 0),a=n.checkPermission;this.Command=class extends s{constructor(e,t){super(e,{observability:r,writeAudit:i,checkPermission:a,defaults:t})}}}};export{u as Foundation,o as default};
 //# sourceMappingURL=client.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"client.mjs","names":["#kernel","#observability","#writeAudit","#checkPermission","#defaults","CommandKernelClass","#execute"],"sources":["../../../src/components/foundation/client.ts"],"sourcesContent":["import {\n\tCommand as CommandKernelClass,\n\ttype CommandExecution,\n\ttype CommandInput,\n\ttype CommandRegistry,\n\ttype CommandResult,\n} from './modules/command/command'\nimport {\n\tObservability,\n\ttype ObservabilityOptions,\n} from './modules/observability/observability'\nimport { Query } from './modules/query/query'\n\n/** Shape handed to the injected audit writer; classification comes from the operation. */\nexport type AuditEntryInput = {\n\toperation: string\n\tactorId: string\n\taggregate: { type: string; id: string }\n\tmetadata?: Record<string, unknown>\n\tclassification: string\n}\n\nexport type AuditWriter = (\n\tcontext: never,\n\tentry: AuditEntryInput,\n) => Promise<unknown> | unknown\n\ntype MaybePromise<Value> = Value | Promise<Value>\ntype OperationKey<Operations extends CommandRegistry> = Extract<\n\tkeyof Operations,\n\tstring\n>\n\nexport type AuditedOperation = Readonly<{\n\tcommand: Readonly<{ parse: (value: unknown) => unknown }>\n\tresult: Readonly<{ parse: (value: unknown) => unknown }>\n\tclassification: string\n\t/**\n\t * Permission slug required to execute this operation. Checked through the\n\t * Foundation's injected checkPermission BEFORE guards and the handler;\n\t * declaring a permission without injecting a checker fails closed.\n\t */\n\tpermission?: string\n\t/**\n\t * Per-operation precondition, after the permission check and the registry\n\t * default guard, before the handler. Throw to deny — nothing has run yet.\n\t */\n\tguard?: (context: never, command: never) => MaybePromise<void>\n\t/**\n\t * Allowlist of aggregate types this operation's audit may reference. When\n\t * declared, an audit entry whose aggregate.type is not listed throws —\n\t * the audit vocabulary is enforced, not advisory.\n\t */\n\taggregates?: readonly string[]\n\taudit: (\n\t\tresolution: Readonly<{ command: never; result: never }>,\n\t\tcontext: never,\n\t) => MaybePromise<Omit<AuditEntryInput, 'classification'> | null>\n}>\n\n/** Registry-wide defaults applied to every operation of one Command. */\nexport type CommandDefaults = Readonly<{\n\t/** Runs before every operation's own guard. Throw to deny. */\n\tguard?: (context: never) => MaybePromise<void>\n}>\n\n/** Injected permission policy: throw to deny. Host semantics, kit ordering. */\nexport type PermissionChecker = (\n\tcontext: never,\n\tinput: Readonly<{ permission: string; operation: string }>,\n) => MaybePromise<void>\n\nexport type AuditedRegistry = Readonly<Record<string, AuditedOperation>>\n\nexport type FoundationOptions = Readonly<{\n\tobservability: ObservabilityOptions &\n\t\tReadonly<{\n\t\t\t/**\n\t\t\t * In-transaction audit writer used by Command. Operations that\n\t\t\t * return an audit record get it written here automatically.\n\t\t\t */\n\t\t\twriteAudit?: AuditWriter\n\t\t}>\n\t/**\n\t * Permission policy for operations that declare a `permission`. Runs\n\t * before guards and the handler; throw to deny. An operation with a\n\t * permission but no injected checker fails closed.\n\t */\n\tcheckPermission?: PermissionChecker\n}>\n\ntype FoundationComponentApi = Readonly<{\n\tfunctions: Readonly<{ status: unknown }>\n}>\n\n/**\n * Application command protocol bound to a Foundation instance:\n * validate, observe, execute, and audit. `classification` and `audit()`\n * are mandatory per operation — auditing is type-enforced, not opt-in.\n * Obtain it by destructuring the Foundation: `const { Command } = new Foundation(...)`.\n */\nclass BoundCommand<Context, const Operations extends AuditedRegistry> {\n\treadonly #kernel: CommandKernelClass<Context, Operations>\n\treadonly #observability: Observability\n\treadonly #writeAudit: AuditWriter\n\treadonly #checkPermission: PermissionChecker | undefined\n\treadonly #defaults: CommandDefaults\n\n\t/** Declared aggregate types per operation — introspectable for tests. */\n\treadonly aggregates: Readonly<{\n\t\t[Key in OperationKey<Operations>]: Operations[Key]['aggregates']\n\t}>\n\n\tstatic operation<const Definition extends AuditedOperation>(\n\t\tdefinition: Definition,\n\t): Definition {\n\t\treturn definition\n\t}\n\n\tconstructor(\n\t\toperations: Operations,\n\t\tdeps: {\n\t\t\tobservability: Observability\n\t\t\twriteAudit: AuditWriter\n\t\t\tcheckPermission?: PermissionChecker\n\t\t\tdefaults?: CommandDefaults\n\t\t},\n\t) {\n\t\tthis.#observability = deps.observability\n\t\tthis.#writeAudit = deps.writeAudit\n\t\tthis.#checkPermission = deps.checkPermission\n\t\tthis.#defaults = deps.defaults ?? {}\n\t\tthis.aggregates = Object.freeze(\n\t\t\tObject.fromEntries(\n\t\t\t\tObject.entries(operations).map(([operation, definition]) => [\n\t\t\t\t\toperation,\n\t\t\t\t\tdefinition.aggregates,\n\t\t\t\t]),\n\t\t\t),\n\t\t) as this['aggregates']\n\t\tthis.#kernel = new CommandKernelClass<Context, Operations>({\n\t\t\toperations,\n\t\t\texecute: (execution) => this.#execute(execution),\n\t\t})\n\t}\n\n\texec<const Key extends OperationKey<Operations>>(executor: {\n\t\toperation: Key\n\t\thandler: (\n\t\t\tcontext: Context,\n\t\t\tcommand: CommandInput<Operations, Key>,\n\t\t) => MaybePromise<CommandResult<Operations, Key>>\n\t}) {\n\t\treturn this.#kernel.exec(executor)\n\t}\n\n\tasync #execute<Key extends OperationKey<Operations>>(\n\t\texecution: CommandExecution<Context, Operations, Key>,\n\t): Promise<CommandResult<Operations, Key>> {\n\t\treturn this.#observability.observe(\n\t\t\t{\n\t\t\t\toperation: execution.operation,\n\t\t\t\tclassification: execution.definition.classification,\n\t\t\t},\n\t\t\tasync () => {\n\t\t\t\t// Guards run before the handler: permission → default → operation.\n\t\t\t\tconst permission = execution.definition.permission\n\t\t\t\tif (permission !== undefined) {\n\t\t\t\t\tif (!this.#checkPermission) {\n\t\t\t\t\t\tthrow new CommandPermissionError(execution.operation)\n\t\t\t\t\t}\n\t\t\t\t\tawait this.#checkPermission(execution.context as never, {\n\t\t\t\t\t\tpermission,\n\t\t\t\t\t\toperation: execution.operation,\n\t\t\t\t\t})\n\t\t\t\t}\n\t\t\t\tawait this.#defaults.guard?.(execution.context as never)\n\t\t\t\tawait execution.definition.guard?.(\n\t\t\t\t\texecution.context as never,\n\t\t\t\t\texecution.command as never,\n\t\t\t\t)\n\t\t\t\tconst result = await execution.run()\n\t\t\t\tconst audit = await execution.definition.audit(\n\t\t\t\t\t{ command: execution.command, result } as never,\n\t\t\t\t\texecution.context as never,\n\t\t\t\t)\n\t\t\t\tif (audit) {\n\t\t\t\t\tconst allowed = execution.definition.aggregates\n\t\t\t\t\tif (allowed && !allowed.includes(audit.aggregate.type)) {\n\t\t\t\t\t\tthrow new CommandAggregateError(\n\t\t\t\t\t\t\texecution.operation,\n\t\t\t\t\t\t\taudit.aggregate.type,\n\t\t\t\t\t\t)\n\t\t\t\t\t}\n\t\t\t\t\tawait this.#writeAudit(execution.context as never, {\n\t\t\t\t\t\t...audit,\n\t\t\t\t\t\tclassification: execution.definition.classification,\n\t\t\t\t\t})\n\t\t\t\t}\n\t\t\t\treturn result\n\t\t\t},\n\t\t)\n\t}\n}\n\n/** The audit referenced an aggregate type outside the operation's allowlist. */\nclass CommandAggregateError extends Error {\n\treadonly code = 'COMMAND_AGGREGATE_NOT_DECLARED'\n\treadonly name = 'CommandAggregateError'\n\n\tconstructor(operation: string, aggregateType: string) {\n\t\tsuper(\n\t\t\t`Operation \"${operation}\" audited aggregate type \"${aggregateType}\" outside its declared aggregates`,\n\t\t)\n\t}\n}\n\n/** Fails closed: an operation declared a permission but no checker exists. */\nclass CommandPermissionError extends Error {\n\treadonly code = 'COMMAND_PERMISSION_NOT_CONFIGURED'\n\treadonly name = 'CommandPermissionError'\n\n\tconstructor(operation: string) {\n\t\tsuper(\n\t\t\t`Operation \"${operation}\" declares a permission but the Foundation has no checkPermission`,\n\t\t)\n\t}\n}\n\nexport type ApplicationCommand<\n\tContext,\n\tOperations extends AuditedRegistry,\n> = BoundCommand<Context, Operations>\n\ntype CommandConstructor = {\n\tnew <Context, const Operations extends AuditedRegistry>(\n\t\toperations: Operations,\n\t\tdefaults?: CommandDefaults,\n\t): BoundCommand<Context, Operations>\n\toperation: (typeof BoundCommand)['operation']\n}\n\n/**\n * Host facade for a component that owns no application execution capability.\n * Declared once; the sole source of the command protocol, query kernel, and\n * observability: `const { Command, Query, observability } = new Foundation(...)`.\n */\nexport class Foundation<\n\tComponent extends FoundationComponentApi = FoundationComponentApi,\n> {\n\treadonly status: Component['functions']['status']\n\treadonly Command: CommandConstructor\n\treadonly Query = Query\n\treadonly observability: Observability\n\n\tconstructor(component: Component, options: FoundationOptions) {\n\t\tthis.status = component.functions.status\n\t\tconst observability = new Observability(options.observability)\n\t\tthis.observability = observability\n\t\tconst writeAudit = options.observability.writeAudit ?? (() => undefined)\n\t\tconst checkPermission = options.checkPermission\n\t\tthis.Command = class <\n\t\t\tContext,\n\t\t\tconst Operations extends AuditedRegistry,\n\t\t> extends BoundCommand<Context, Operations> {\n\t\t\tconstructor(operations: Operations, defaults?: CommandDefaults) {\n\t\t\t\tsuper(operations, {\n\t\t\t\t\tobservability,\n\t\t\t\t\twriteAudit,\n\t\t\t\t\tcheckPermission,\n\t\t\t\t\tdefaults,\n\t\t\t\t})\n\t\t\t}\n\t\t}\n\t}\n}\n\nexport type {\n\tCommandExecution,\n\tCommandInput,\n\tCommandRegistry,\n\tCommandResult,\n\tParseable,\n} from './modules/command/command'\nexport { Observability } from './modules/observability/observability'\nexport type {\n\tCommandObservation,\n\tObservabilityOptions,\n} from './modules/observability/observability'\nexport { Query } from './modules/query/query'\nexport type { QueryExecution } from './modules/query/query'\nexport { executeResultBoundary, projectResult } from './result'\nexport type {\n\tResult,\n\tResultBoundary,\n\tTransactionMetricsContext,\n} from './result'\nexport { emitSemanticEvent } from './telemetry'\n\n// Component definition as default export: `import foundation from \"cvx-kit/components/foundation\"` → app.use(foundation)\nexport { default } from \"./convex.config\"\n"],"mappings":"mVAqGA,IAAM,EAAN,KAAsE,CACrE,GACA,GACA,GACA,GACA,GAGA,WAIA,OAAO,UACN,EACa,CACb,OAAO,CACR,CAEA,YACC,EACA,EAMC,CACD,KAAKC,GAAiB,EAAK,cAC3B,KAAKC,GAAc,EAAK,WACxB,KAAKC,GAAmB,EAAK,gBAC7B,KAAKC,GAAY,EAAK,UAAY,CAAC,EACnC,KAAK,WAAa,OAAO,OACxB,OAAO,YACN,OAAO,QAAQ,CAAU,CAAC,CAAC,KAAK,CAAC,EAAW,KAAgB,CAC3D,EACA,EAAW,UACZ,CAAC,CACF,CACD,EACA,KAAKJ,GAAU,IAAIK,EAAwC,CAC1D,aACA,QAAU,GAAc,KAAKC,GAAS,CAAS,CAChD,CAAC,CACF,CAEA,KAAiD,EAM9C,CACF,OAAO,KAAKN,GAAQ,KAAK,CAAQ,CAClC,CAEA,KAAMM,GACL,EAC0C,CAC1C,OAAO,KAAKL,GAAe,QAC1B,CACC,UAAW,EAAU,UACrB,eAAgB,EAAU,WAAW,cACtC,EACA,SAAY,CAEX,IAAM,EAAa,EAAU,WAAW,WACxC,GAAI,IAAe,IAAA,GAAW,CAC7B,GAAI,CAAC,KAAKE,GACT,MAAM,IAAI,EAAuB,EAAU,SAAS,EAErD,MAAM,KAAKA,GAAiB,EAAU,QAAkB,CACvD,aACA,UAAW,EAAU,SACtB,CAAC,CACF,CACA,MAAM,KAAKC,GAAU,QAAQ,EAAU,OAAgB,EACvD,MAAM,EAAU,WAAW,QAC1B,EAAU,QACV,EAAU,OACX,EACA,IAAM,EAAS,MAAM,EAAU,IAAI,EAC7B,EAAQ,MAAM,EAAU,WAAW,MACxC,CAAE,QAAS,EAAU,QAAS,QAAO,EACrC,EAAU,OACX,EACA,GAAI,EAAO,CACV,IAAM,EAAU,EAAU,WAAW,WACrC,GAAI,GAAW,CAAC,EAAQ,SAAS,EAAM,UAAU,IAAI,EACpD,MAAM,IAAI,EACT,EAAU,UACV,EAAM,UAAU,IACjB,EAED,MAAM,KAAKF,GAAY,EAAU,QAAkB,CAClD,GAAG,EACH,eAAgB,EAAU,WAAW,cACtC,CAAC,CACF,CACA,OAAO,CACR,CACD,CACD,CACD,EAGM,EAAN,cAAoC,KAAM,CACzC,KAAgB,iCAChB,KAAgB,wBAEhB,YAAY,EAAmB,EAAuB,CACrD,MACC,cAAc,EAAU,4BAA4B,EAAc,kCACnE,CACD,CACD,EAGM,EAAN,cAAqC,KAAM,CAC1C,KAAgB,oCAChB,KAAgB,yBAEhB,YAAY,EAAmB,CAC9B,MACC,cAAc,EAAU,kEACzB,CACD,CACD,EAoBa,EAAb,KAEE,CACD,OACA,QACA,MAAiB,EACjB,cAEA,YAAY,EAAsB,EAA4B,CAC7D,KAAK,OAAS,EAAU,UAAU,OAClC,IAAM,EAAgB,IAAI,EAAc,EAAQ,aAAa,EAC7D,KAAK,cAAgB,EACrB,IAAM,EAAa,EAAQ,cAAc,iBAAqB,IAAA,IACxD,EAAkB,EAAQ,gBAChC,KAAK,QAAU,cAGL,CAAkC,CAC3C,YAAY,EAAwB,EAA4B,CAC/D,MAAM,EAAY,CACjB,gBACA,aACA,kBACA,UACD,CAAC,CACF,CACD,CACD,CACD"}
+{"version":3,"file":"client.mjs","names":["#kernel","#observability","#writeAudit","#checkPermission","#defaults","CommandKernelClass","#execute"],"sources":["../../../src/components/foundation/client.ts"],"sourcesContent":["import {\n\tCommand as CommandKernelClass,\n\ttype CommandExecution,\n\ttype CommandInput,\n\ttype CommandRegistry,\n\ttype CommandResult,\n} from './modules/command/command'\nimport {\n\tObservability,\n\ttype ObservabilityOptions,\n} from './modules/observability/observability'\nimport { Query } from './modules/query/query'\nimport { executeResultBoundary, projectResult } from './result'\nimport { emitSemanticEvent } from './telemetry'\n\n/** Shape handed to the injected audit writer; classification comes from the operation. */\nexport type AuditEntryInput = {\n\toperation: string\n\tactorId: string\n\taggregate: { type: string; id: string }\n\tmetadata?: Record<string, unknown>\n\tclassification: string\n}\n\nexport type AuditWriter = (\n\tcontext: never,\n\tentry: AuditEntryInput,\n) => Promise<unknown> | unknown\n\ntype MaybePromise<Value> = Value | Promise<Value>\ntype OperationKey<Operations extends CommandRegistry> = Extract<\n\tkeyof Operations,\n\tstring\n>\n\nexport type AuditedOperation = Readonly<{\n\tcommand: Readonly<{ parse: (value: unknown) => unknown }>\n\tresult: Readonly<{ parse: (value: unknown) => unknown }>\n\tclassification: string\n\t/**\n\t * Permission slug required to execute this operation. Checked through the\n\t * Foundation's injected checkPermission BEFORE guards and the handler;\n\t * declaring a permission without injecting a checker fails closed.\n\t */\n\tpermission?: string\n\t/**\n\t * Per-operation precondition, after the permission check and the registry\n\t * default guard, before the handler. Throw to deny — nothing has run yet.\n\t */\n\tguard?: (context: never, command: never) => MaybePromise<void>\n\t/**\n\t * Allowlist of aggregate types this operation's audit may reference. When\n\t * declared, an audit entry whose aggregate.type is not listed throws —\n\t * the audit vocabulary is enforced, not advisory.\n\t */\n\taggregates?: readonly string[]\n\taudit: (\n\t\tresolution: Readonly<{ command: never; result: never }>,\n\t\tcontext: never,\n\t) => MaybePromise<Omit<AuditEntryInput, 'classification'> | null>\n}>\n\n/** Registry-wide defaults applied to every operation of one Command. */\nexport type CommandDefaults = Readonly<{\n\t/** Runs before every operation's own guard. Throw to deny. */\n\tguard?: (context: never) => MaybePromise<void>\n}>\n\n/** Injected permission policy: throw to deny. Host semantics, kit ordering. */\nexport type PermissionChecker = (\n\tcontext: never,\n\tinput: Readonly<{ permission: string; operation: string }>,\n) => MaybePromise<void>\n\nexport type AuditedRegistry = Readonly<Record<string, AuditedOperation>>\n\nexport type FoundationOptions = Readonly<{\n\tobservability: ObservabilityOptions &\n\t\tReadonly<{\n\t\t\t/**\n\t\t\t * In-transaction audit writer used by Command. Operations that\n\t\t\t * return an audit record get it written here automatically.\n\t\t\t */\n\t\t\twriteAudit?: AuditWriter\n\t\t}>\n\t/**\n\t * Permission policy for operations that declare a `permission`. Runs\n\t * before guards and the handler; throw to deny. An operation with a\n\t * permission but no injected checker fails closed.\n\t */\n\tcheckPermission?: PermissionChecker\n}>\n\ntype FoundationComponentApi = Readonly<{\n\tfunctions: Readonly<{ status: unknown }>\n}>\n\n/**\n * Application command protocol bound to a Foundation instance:\n * validate, observe, execute, and audit. `classification` and `audit()`\n * are mandatory per operation — auditing is type-enforced, not opt-in.\n * Obtain it by destructuring the Foundation: `const { Command } = new Foundation(...)`.\n */\nclass BoundCommand<Context, const Operations extends AuditedRegistry> {\n\treadonly #kernel: CommandKernelClass<Context, Operations>\n\treadonly #observability: Observability\n\treadonly #writeAudit: AuditWriter\n\treadonly #checkPermission: PermissionChecker | undefined\n\treadonly #defaults: CommandDefaults\n\n\t/** Declared aggregate types per operation — introspectable for tests. */\n\treadonly aggregates: Readonly<{\n\t\t[Key in OperationKey<Operations>]: Operations[Key]['aggregates']\n\t}>\n\n\tstatic operation<const Definition extends AuditedOperation>(\n\t\tdefinition: Definition,\n\t): Definition {\n\t\treturn definition\n\t}\n\n\tconstructor(\n\t\toperations: Operations,\n\t\tdeps: {\n\t\t\tobservability: Observability\n\t\t\twriteAudit: AuditWriter\n\t\t\tcheckPermission?: PermissionChecker\n\t\t\tdefaults?: CommandDefaults\n\t\t},\n\t) {\n\t\tthis.#observability = deps.observability\n\t\tthis.#writeAudit = deps.writeAudit\n\t\tthis.#checkPermission = deps.checkPermission\n\t\tthis.#defaults = deps.defaults ?? {}\n\t\tthis.aggregates = Object.freeze(\n\t\t\tObject.fromEntries(\n\t\t\t\tObject.entries(operations).map(([operation, definition]) => [\n\t\t\t\t\toperation,\n\t\t\t\t\tdefinition.aggregates,\n\t\t\t\t]),\n\t\t\t),\n\t\t) as this['aggregates']\n\t\tthis.#kernel = new CommandKernelClass<Context, Operations>({\n\t\t\toperations,\n\t\t\texecute: (execution) => this.#execute(execution),\n\t\t})\n\t}\n\n\texec<const Key extends OperationKey<Operations>>(executor: {\n\t\toperation: Key\n\t\thandler: (\n\t\t\tcontext: Context,\n\t\t\tcommand: CommandInput<Operations, Key>,\n\t\t) => MaybePromise<CommandResult<Operations, Key>>\n\t}) {\n\t\treturn this.#kernel.exec(executor)\n\t}\n\n\tasync #execute<Key extends OperationKey<Operations>>(\n\t\texecution: CommandExecution<Context, Operations, Key>,\n\t): Promise<CommandResult<Operations, Key>> {\n\t\treturn this.#observability.observe(\n\t\t\t{\n\t\t\t\toperation: execution.operation,\n\t\t\t\tclassification: execution.definition.classification,\n\t\t\t},\n\t\t\tasync () => {\n\t\t\t\t// Guards run before the handler: permission → default → operation.\n\t\t\t\tconst permission = execution.definition.permission\n\t\t\t\tif (permission !== undefined) {\n\t\t\t\t\tif (!this.#checkPermission) {\n\t\t\t\t\t\tthrow new CommandPermissionError(execution.operation)\n\t\t\t\t\t}\n\t\t\t\t\tawait this.#checkPermission(execution.context as never, {\n\t\t\t\t\t\tpermission,\n\t\t\t\t\t\toperation: execution.operation,\n\t\t\t\t\t})\n\t\t\t\t}\n\t\t\t\tawait this.#defaults.guard?.(execution.context as never)\n\t\t\t\tawait execution.definition.guard?.(\n\t\t\t\t\texecution.context as never,\n\t\t\t\t\texecution.command as never,\n\t\t\t\t)\n\t\t\t\tconst result = await execution.run()\n\t\t\t\tconst audit = await execution.definition.audit(\n\t\t\t\t\t{ command: execution.command, result } as never,\n\t\t\t\t\texecution.context as never,\n\t\t\t\t)\n\t\t\t\tif (audit) {\n\t\t\t\t\tconst allowed = execution.definition.aggregates\n\t\t\t\t\tif (allowed && !allowed.includes(audit.aggregate.type)) {\n\t\t\t\t\t\tthrow new CommandAggregateError(\n\t\t\t\t\t\t\texecution.operation,\n\t\t\t\t\t\t\taudit.aggregate.type,\n\t\t\t\t\t\t)\n\t\t\t\t\t}\n\t\t\t\t\tawait this.#writeAudit(execution.context as never, {\n\t\t\t\t\t\t...audit,\n\t\t\t\t\t\tclassification: execution.definition.classification,\n\t\t\t\t\t})\n\t\t\t\t}\n\t\t\t\treturn result\n\t\t\t},\n\t\t)\n\t}\n}\n\n/** The audit referenced an aggregate type outside the operation's allowlist. */\nclass CommandAggregateError extends Error {\n\treadonly code = 'COMMAND_AGGREGATE_NOT_DECLARED'\n\treadonly name = 'CommandAggregateError'\n\n\tconstructor(operation: string, aggregateType: string) {\n\t\tsuper(\n\t\t\t`Operation \"${operation}\" audited aggregate type \"${aggregateType}\" outside its declared aggregates`,\n\t\t)\n\t}\n}\n\n/** Fails closed: an operation declared a permission but no checker exists. */\nclass CommandPermissionError extends Error {\n\treadonly code = 'COMMAND_PERMISSION_NOT_CONFIGURED'\n\treadonly name = 'CommandPermissionError'\n\n\tconstructor(operation: string) {\n\t\tsuper(\n\t\t\t`Operation \"${operation}\" declares a permission but the Foundation has no checkPermission`,\n\t\t)\n\t}\n}\n\nexport type ApplicationCommand<\n\tContext,\n\tOperations extends AuditedRegistry,\n> = BoundCommand<Context, Operations>\n\ntype CommandConstructor = {\n\tnew <Context, const Operations extends AuditedRegistry>(\n\t\toperations: Operations,\n\t\tdefaults?: CommandDefaults,\n\t): BoundCommand<Context, Operations>\n\toperation: (typeof BoundCommand)['operation']\n}\n\n/**\n * Host facade for a component that owns no application execution capability.\n * Declared once; the sole source of the command protocol, query kernel, and\n * observability: `const { Command, Query, observability } = new Foundation(...)`.\n */\nexport class Foundation<\n\tComponent extends FoundationComponentApi = FoundationComponentApi,\n> {\n\treadonly status: Component['functions']['status']\n\treadonly Command: CommandConstructor\n\treadonly Query = Query\n\treadonly observability: Observability\n\t/** Typed-failure boundary — see result.ts. Facade-bound like the kernels. */\n\treadonly executeResultBoundary = executeResultBoundary\n\treadonly projectResult = projectResult\n\treadonly emitSemanticEvent = emitSemanticEvent\n\n\tconstructor(component: Component, options: FoundationOptions) {\n\t\tthis.status = component.functions.status\n\t\tconst observability = new Observability(options.observability)\n\t\tthis.observability = observability\n\t\tconst writeAudit = options.observability.writeAudit ?? (() => undefined)\n\t\tconst checkPermission = options.checkPermission\n\t\tthis.Command = class <\n\t\t\tContext,\n\t\t\tconst Operations extends AuditedRegistry,\n\t\t> extends BoundCommand<Context, Operations> {\n\t\t\tconstructor(operations: Operations, defaults?: CommandDefaults) {\n\t\t\t\tsuper(operations, {\n\t\t\t\t\tobservability,\n\t\t\t\t\twriteAudit,\n\t\t\t\t\tcheckPermission,\n\t\t\t\t\tdefaults,\n\t\t\t\t})\n\t\t\t}\n\t\t}\n\t}\n}\n\n// Kernel CLASSES are deliberately NOT exported: Command, Query, and\n// Observability exist only as capabilities of a Foundation instance —\n// `const { Command, Query, observability } = new Foundation(...)`. A loose\n// import would construct kernels without the injected observability, audit\n// writer, and permission checker. Types stay exported for signatures.\nexport type {\n\tCommandExecution,\n\tCommandInput,\n\tCommandRegistry,\n\tCommandResult,\n\tParseable,\n} from './modules/command/command'\nexport type {\n\tCommandObservation,\n\tObservabilityOptions,\n} from './modules/observability/observability'\nexport type { QueryExecution } from './modules/query/query'\nexport type {\n\tResult,\n\tResultBoundary,\n\tTransactionMetricsContext,\n} from './result'\n\n// Component definition as default export: `import foundation from \"cvx-kit/components/foundation\"` → app.use(foundation)\nexport { default } from \"./convex.config\"\n"],"mappings":"mVAuGA,IAAM,EAAN,KAAsE,CACrE,GACA,GACA,GACA,GACA,GAGA,WAIA,OAAO,UACN,EACa,CACb,OAAO,CACR,CAEA,YACC,EACA,EAMC,CACD,KAAKC,GAAiB,EAAK,cAC3B,KAAKC,GAAc,EAAK,WACxB,KAAKC,GAAmB,EAAK,gBAC7B,KAAKC,GAAY,EAAK,UAAY,CAAC,EACnC,KAAK,WAAa,OAAO,OACxB,OAAO,YACN,OAAO,QAAQ,CAAU,CAAC,CAAC,KAAK,CAAC,EAAW,KAAgB,CAC3D,EACA,EAAW,UACZ,CAAC,CACF,CACD,EACA,KAAKJ,GAAU,IAAIK,EAAwC,CAC1D,aACA,QAAU,GAAc,KAAKC,GAAS,CAAS,CAChD,CAAC,CACF,CAEA,KAAiD,EAM9C,CACF,OAAO,KAAKN,GAAQ,KAAK,CAAQ,CAClC,CAEA,KAAMM,GACL,EAC0C,CAC1C,OAAO,KAAKL,GAAe,QAC1B,CACC,UAAW,EAAU,UACrB,eAAgB,EAAU,WAAW,cACtC,EACA,SAAY,CAEX,IAAM,EAAa,EAAU,WAAW,WACxC,GAAI,IAAe,IAAA,GAAW,CAC7B,GAAI,CAAC,KAAKE,GACT,MAAM,IAAI,EAAuB,EAAU,SAAS,EAErD,MAAM,KAAKA,GAAiB,EAAU,QAAkB,CACvD,aACA,UAAW,EAAU,SACtB,CAAC,CACF,CACA,MAAM,KAAKC,GAAU,QAAQ,EAAU,OAAgB,EACvD,MAAM,EAAU,WAAW,QAC1B,EAAU,QACV,EAAU,OACX,EACA,IAAM,EAAS,MAAM,EAAU,IAAI,EAC7B,EAAQ,MAAM,EAAU,WAAW,MACxC,CAAE,QAAS,EAAU,QAAS,QAAO,EACrC,EAAU,OACX,EACA,GAAI,EAAO,CACV,IAAM,EAAU,EAAU,WAAW,WACrC,GAAI,GAAW,CAAC,EAAQ,SAAS,EAAM,UAAU,IAAI,EACpD,MAAM,IAAI,EACT,EAAU,UACV,EAAM,UAAU,IACjB,EAED,MAAM,KAAKF,GAAY,EAAU,QAAkB,CAClD,GAAG,EACH,eAAgB,EAAU,WAAW,cACtC,CAAC,CACF,CACA,OAAO,CACR,CACD,CACD,CACD,EAGM,EAAN,cAAoC,KAAM,CACzC,KAAgB,iCAChB,KAAgB,wBAEhB,YAAY,EAAmB,EAAuB,CACrD,MACC,cAAc,EAAU,4BAA4B,EAAc,kCACnE,CACD,CACD,EAGM,EAAN,cAAqC,KAAM,CAC1C,KAAgB,oCAChB,KAAgB,yBAEhB,YAAY,EAAmB,CAC9B,MACC,cAAc,EAAU,kEACzB,CACD,CACD,EAoBa,EAAb,KAEE,CACD,OACA,QACA,MAAiB,EACjB,cAEA,sBAAiC,EACjC,cAAyB,EACzB,kBAA6B,EAE7B,YAAY,EAAsB,EAA4B,CAC7D,KAAK,OAAS,EAAU,UAAU,OAClC,IAAM,EAAgB,IAAI,EAAc,EAAQ,aAAa,EAC7D,KAAK,cAAgB,EACrB,IAAM,EAAa,EAAQ,cAAc,iBAAqB,IAAA,IACxD,EAAkB,EAAQ,gBAChC,KAAK,QAAU,cAGL,CAAkC,CAC3C,YAAY,EAAwB,EAA4B,CAC/D,MAAM,EAAY,CACjB,gBACA,aACA,kBACA,UACD,CAAC,CACF,CACD,CACD,CACD"}

package/docs/commands.md

@@ -184,7 +184,8 @@ failure. Default sink is one JSON line on `console.info`
 ## `executeResultBoundary` — typed failures, but only while it's safe
 
 ```ts
-import { executeResultBoundary } from 'cvx-kit/components/foundation'
+// destructured from the Foundation facade, like everything else
+const { executeResultBoundary, projectResult } = new Foundation(...)
 
 const result = await executeResultBoundary(ctx, () => run(), boundary)
 // Result<Value, Failure> = { ok: true, value } | { ok: false, error }

package/docs/llms.md

@@ -69,7 +69,7 @@ function constructors, a trigger registry, an audited command protocol
 | `cvx-kit/tenancy` | `createTenantRules`, `composeRules`, `requireTenantReference`, `assertTenantOwned`, `TENANT_FIELD` |
 | `cvx-kit/triggers` | `createTriggers`, `timestamps`, `appendOnly`, `noDelete`, `tenantOwnership`, `Triggers` |
 | `cvx-kit/errors` | `KitError`, `defaultErrors`, `ErrorFactory` |
-| `cvx-kit/components/foundation` | `Foundation`, `executeResultBoundary`, `projectResult`, `Observability`; default export = component config for `app.use` |
+| `cvx-kit/components/foundation` | `Foundation` — the ONLY runtime export besides the default component config for `app.use`. Everything (`Command`, `Query`, `observability`, `executeResultBoundary`, `projectResult`, `emitSemanticEvent`) destructures from the instance; nothing is importable loose. |
 | `cvx-kit/components/approvals` | `Approvals` client; default export = component config for `app.use` |
 | `cvx-kit/test` | `registerFoundation(t)`, `registerApprovals(t)` for convex-test |
 

package/package.json

@@ -1,16 +1,10 @@
 {
 	"name": "cvx-kit",
-	"version": "0.0.3",
+	"version": "0.0.5",
 	"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",
 	"sideEffects": false,
-	"files": [
-		"dist",
-		"src",
-		"!src/docs",
-		"docs"
-	],
 	"exports": {
 		"./package.json": "./package.json",
 		".": {
@@ -74,7 +68,7 @@
 		"typecheck": "tsc --noEmit",
 		"test": "vp test run",
 		"docs:sync": "rm -f docs/*.md && cp src/docs/*.md docs/",
-		"prepublishOnly": "bun run typecheck && bun run test && bun run build && bun run docs:sync",
+		"prepublishOnly": "bun run build && bun run typecheck && bun run test && bun run docs:sync",
 		"build:codegen": "convex codegen --component-dir ./src/components/foundation && convex codegen --component-dir ./src/components/approvals && vp pack",
 		"release": "npm version patch && git push --follow-tags",
 		"release:minor": "npm version minor && git push --follow-tags"

package/src/test.ts

@@ -2,16 +2,18 @@
  * Test helpers for consumers, following the official component template:
  * register the kit's components on a convex-test instance so host-app tests
  * run against them in-memory. Requires a vitest-compatible runner
- * (import.meta.glob), which is why this export ships as source.
+ * (import.meta.glob), which is why this file ships as source — but it
+ * registers the COMPILED component modules from dist, so dist is the only
+ * code the package ships.
  */
-import approvalsSchema from './components/approvals/schema'
-import foundationSchema from './components/foundation/schema'
+import approvalsSchema from '../dist/components/approvals/schema.mjs'
+import foundationSchema from '../dist/components/foundation/schema.mjs'
 
 const foundationModules = import.meta.glob(
-	'./components/foundation/**/!(*.test).ts',
+	'../dist/components/foundation/**/*.mjs',
 )
 const approvalsModules = import.meta.glob(
-	'./components/approvals/**/!(*.test).ts',
+	'../dist/components/approvals/**/*.mjs',
 )
 
 type RegistersComponents = {

package/src/auth.ts

@@ -1,473 +0,0 @@
-import {
-	zCustomAction,
-	zCustomMutation,
-	zCustomQuery,
-} from 'convex-helpers/server/zod4'
-import type {
-	ActionBuilder,
-	DocumentByInfo,
-	GenericActionCtx,
-	GenericDataModel,
-	GenericMutationCtx,
-	GenericQueryCtx,
-	GenericTableInfo,
-	IndexNames,
-	IndexRange,
-	IndexRangeBuilder,
-	MutationBuilder,
-	NamedIndex,
-	Query,
-	QueryBuilder,
-	QueryInitializer,
-	UserIdentity,
-} from 'convex/server'
-import type { Triggers } from 'convex-helpers/server/triggers'
-import type { TableNamesInDataModel } from 'convex/server'
-import { defaultErrors, type ErrorFactory } from './errors'
-import {
-	composeRules,
-	createTenantRules,
-	wrapDatabaseReader,
-	wrapDatabaseWriter,
-	type RLSConfig,
-	type Rules,
-} from './tenancy'
-
-/** The default vocabulary; every app can supply its own via the Role generic. */
-export type DefaultRole = 'reader' | 'writer' | 'admin'
-
-export type Actor<Role extends string> = Readonly<{
-	userId: string
-	organizationId: string
-	role: Role
-}>
-
-export type AuthBundle<Role extends string> = Readonly<{
-	identity: UserIdentity
-	user: Readonly<{ id: string }>
-	org: Readonly<{ organizationId: string; role: Role }>
-	role: Role
-	actor: Actor<Role>
-	/** The resolved tenant — security.tenancy.resolve, or the organization id. */
-	tenant: string
-}>
-
-/**
- * Row-level security configuration. Tenant isolation and role-level rules
- * compose (AND) onto the same wrapped database: queries get a wrapped
- * reader, mutations get triggers first, then a wrapped writer.
- */
-export type SecurityConfig<
-	DataModel extends GenericDataModel,
-	Role extends string,
-> = {
-	/**
-	 * Tenant isolation. `tables` is THE registry: every listed table gets
-	 * read/insert/modify gated on row.tenant === ctx.tenant. Pair with
-	 * tenantTable (schema) and tenantOwnership (triggers) on the same list.
-	 */
-	tenancy?: {
-		tables: readonly TableNamesInDataModel<DataModel>[]
-		/** Maps the auth bundle to the tenant; defaults to org.organizationId. */
-		resolve?: (bundle: Omit<AuthBundle<Role>, 'tenant'>) => string
-	}
-	/**
-	 * Role-level (or any policy) rules derived from the authenticated bundle,
-	 * composed AND-wise with tenant isolation. E.g. gate `modify` on a table
-	 * to admin roles.
-	 */
-	rules?: (bundle: AuthBundle<Role>) => Rules<unknown, DataModel>
-	/**
-	 * Policy for tables with no rule. Defaults to 'deny' when tenancy is
-	 * configured (unlisted tables are unreachable — fail closed), 'allow'
-	 * otherwise.
-	 */
-	defaultPolicy?: RLSConfig['defaultPolicy']
-}
-
-type AnyAuthContext<DataModel extends GenericDataModel> =
-	| GenericQueryCtx<DataModel>
-	| GenericMutationCtx<DataModel>
-	| GenericActionCtx<DataModel>
-
-export type AuthFunctionsConfig<
-	DataModel extends GenericDataModel,
-	Role extends string,
-> = {
-	/** The consumer's generated function builders (from ./_generated/server). */
-	query: QueryBuilder<DataModel, 'public'>
-	mutation: MutationBuilder<DataModel, 'public'>
-	action: ActionBuilder<DataModel, 'public'>
-	internalMutation: MutationBuilder<DataModel, 'internal'>
-	internalAction: ActionBuilder<DataModel, 'internal'>
-	/** Resolves the synchronized principal, e.g. (ctx) => authKit.getAuthUser(ctx). */
-	getAuthUser: (
-		ctx: AnyAuthContext<DataModel>,
-	) => Promise<{ id: string } | null>
-	/**
-	 * Maps an identity role slug onto the app's role vocabulary. Returning
-	 * null rejects the caller with FORBIDDEN — unknown roles never pass.
-	 */
-	mapRole: (roleSlug?: string) => Role | null
-	/** Roles allowed through the admin* constructors. */
-	adminRoles: readonly NoInfer<Role>[]
-	/**
-	 * Live membership check for actions (queries/mutations trust the JWT).
-	 * Authentication fails closed with FORBIDDEN when verification errors.
-	 * Omit to let actions trust the JWT like queries do.
-	 */
-	verifyMembership?: (input: {
-		userId: string
-		organizationId: string
-	}) => Promise<{ organizationId: string; roleSlug: string } | null>
-	/** Host error policy; defaults to throwing KitError. */
-	errors?: ErrorFactory
-	/**
-	 * Application trigger registry. When set, every authMutation,
-	 * roleMutation, and systemMutation write runs through triggers.wrapDB —
-	 * evaluations registered on tables fire structurally.
-	 */
-	triggers?: Triggers<DataModel>
-	/** Lower-level alternative to `triggers`: a custom ctx wrapper. */
-	wrapDB?: (
-		ctx: GenericMutationCtx<DataModel>,
-	) => GenericMutationCtx<DataModel>
-	/** Upper bound for include() reads. */
-	maxIncludedQueryRows?: number
-	/**
-	 * Row-level security: tenant isolation (from a table registry) and
-	 * role-level rules, applied structurally inside every auth*, role*, and
-	 * admin* constructor. system* constructors stay unwrapped (trusted).
-	 */
-	security?: SecurityConfig<DataModel, Role>
-}
-
-/** WorkOS-style default: `member` writes; reader/writer/admin pass through. */
-export function defaultRoleMap(roleSlug?: string): DefaultRole | null {
-	const normalized = roleSlug?.trim().toLowerCase()
-	if (normalized === 'member') return 'writer'
-	return normalized === 'reader' ||
-		normalized === 'writer' ||
-		normalized === 'admin'
-		? normalized
-		: null
-}
-
-export type IncludedQuery<Table extends GenericTableInfo> = {
-	when<Value>(
-		value: Value | null | undefined,
-		select: (query: QueryInitializer<Table>, value: Value) => Query<Table>,
-	): IncludedQuery<Table>
-	matching<IndexName extends IndexNames<Table>>(
-		indexName: IndexName,
-		indexRange?: (
-			query: IndexRangeBuilder<
-				DocumentByInfo<Table>,
-				NamedIndex<Table, IndexName>
-			>,
-		) => IndexRange,
-		shouldMatch?: boolean,
-	): IncludedQuery<Table>
-	otherwise(
-		select: (query: QueryInitializer<Table>) => Query<Table>,
-	): Query<Table>
-	resolve(): Query<Table>
-	execute<Result = Awaited<ReturnType<Query<Table>['take']>>>(
-		limit: number,
-		transform?: (
-			data: Awaited<ReturnType<Query<Table>['take']>>,
-		) => Result | Promise<Result>,
-	): Promise<Result>
-}
-
-export type Include = <Table extends GenericTableInfo>(
-	query: QueryInitializer<Table>,
-) => IncludedQuery<Table>
-
-/** Builds an include() that selects the first matching indexed query and bounds the read. */
-export function createInclude(options?: {
-	errors?: ErrorFactory
-	maxRows?: number
-}): Include {
-	const errors = options?.errors ?? defaultErrors
-	const maxRows = options?.maxRows ?? 100
-
-	function attach<Table extends GenericTableInfo>(
-		query: QueryInitializer<Table>,
-		selected?: Query<Table>,
-	): IncludedQuery<Table> {
-		return {
-			when: (value, select) =>
-				selected || value === undefined || value === null
-					? attach(query, selected)
-					: attach(query, select(query, value)),
-			matching: (indexName, indexRange, shouldMatch = true) =>
-				selected || !shouldMatch
-					? attach(query, selected)
-					: attach(query, query.withIndex(indexName, indexRange)),
-			otherwise: (select) => selected ?? select(query),
-			resolve: () => selected ?? query.fullTableScan(),
-			execute: async (limit, transform) => {
-				if (!Number.isSafeInteger(limit) || limit < 1 || limit > maxRows) {
-					return errors.throw({
-						code: 'INVALID_REQUEST_BOUNDARY',
-						message: `A bounded query limit must be from 1 to ${maxRows}`,
-					})
-				}
-				const data = await (selected ?? query.fullTableScan()).take(limit)
-				return transform ? transform(data) : (data as never)
-			},
-		}
-	}
-
-	return (query) => attach(query)
-}
-
-/**
- * Builds the auth-aware function constructors from the host's injected
- * policy: identity resolution, the app's own role vocabulary, live
- * membership verification for actions, trigger wrapping for mutations,
- * and errors. Role-based access is first-class — every constructor family
- * has a role-gated variant (roleQuery/roleMutation/roleAction), and the
- * admin* constructors are just that gate applied to config.adminRoles.
- */
-export function createAuthFunctions<
-	DataModel extends GenericDataModel,
-	const Role extends string = DefaultRole,
->(config: AuthFunctionsConfig<DataModel, Role>) {
-	const errors = config.errors ?? defaultErrors
-	const wrapDB = config.triggers
-		? (ctx: GenericMutationCtx<DataModel>) =>
-				(config.triggers as Triggers<DataModel>).wrapDB(ctx)
-		: (config.wrapDB ?? ((ctx) => ctx))
-	const include = createInclude({
-		errors,
-		maxRows: config.maxIncludedQueryRows,
-	})
-
-	async function authenticatedUser(
-		ctx: AnyAuthContext<DataModel>,
-	): Promise<AuthBundle<Role>> {
-		const identity = await ctx.auth.getUserIdentity()
-		const user = identity ? await config.getAuthUser(ctx) : null
-		if (!identity || !user) return errors.throw({ code: 'UNAUTHENTICATED' })
-		const organization = identity.organization
-		const organizationId =
-			organization &&
-			typeof organization === 'object' &&
-			'organizationId' in organization &&
-			typeof organization.organizationId === 'string'
-				? organization.organizationId
-				: typeof identity.org_id === 'string'
-					? identity.org_id
-					: null
-		if (!organizationId) return errors.throw({ code: 'UNAUTHENTICATED' })
-		const organizationRole =
-			organization &&
-			typeof organization === 'object' &&
-			'role' in organization &&
-			typeof organization.role === 'string'
-				? organization.role
-				: typeof identity.role === 'string'
-					? identity.role
-					: undefined
-		const role = config.mapRole(organizationRole)
-		if (!role) return errors.throw({ code: 'FORBIDDEN' })
-		const base = {
-			identity,
-			user: Object.freeze({ id: user.id }),
-			org: Object.freeze({ organizationId, role }),
-			role,
-			actor: Object.freeze({ userId: user.id, organizationId, role }),
-		}
-		return Object.freeze({
-			...base,
-			tenant: config.security?.tenancy?.resolve?.(base) ?? organizationId,
-		})
-	}
-
-	const securityConfig: RLSConfig | undefined = config.security
-		? {
-				defaultPolicy:
-					config.security.defaultPolicy ??
-					(config.security.tenancy ? 'deny' : 'allow'),
-			}
-		: undefined
-
-	function securityRules(
-		bundle: AuthBundle<Role>,
-	): Rules<unknown, DataModel> | undefined {
-		const security = config.security
-		if (!security) return undefined
-		const sets: Rules<unknown, DataModel>[] = []
-		if (security.tenancy) {
-			sets.push(
-				createTenantRules<DataModel>(bundle.tenant, security.tenancy.tables),
-			)
-		}
-		if (security.rules) sets.push(security.rules(bundle))
-		return sets.length === 1 ? sets[0] : composeRules(...sets)
-	}
-
-	function secureReader(
-		ctx: GenericQueryCtx<DataModel>,
-		bundle: AuthBundle<Role>,
-	): GenericQueryCtx<DataModel> {
-		const rules = securityRules(bundle)
-		if (!rules) return ctx
-		return {
-			...ctx,
-			db: wrapDatabaseReader({}, ctx.db, rules as never, securityConfig),
-		}
-	}
-
-	function secureWriter(
-		ctx: GenericMutationCtx<DataModel>,
-		bundle: AuthBundle<Role>,
-	): GenericMutationCtx<DataModel> {
-		const rules = securityRules(bundle)
-		if (!rules) return ctx
-		// Triggers wrap first (ctx already trigger-wrapped by the caller),
-		// then row-level security wraps the triggered db — order matters.
-		return {
-			...ctx,
-			db: wrapDatabaseWriter({}, ctx.db, rules as never, securityConfig),
-		}
-	}
-
-	async function verifiedMembership(userId: string, organizationId: string) {
-		if (!config.verifyMembership) return null
-		try {
-			const membership = await config.verifyMembership({
-				userId,
-				organizationId,
-			})
-			if (membership && membership.organizationId === organizationId) {
-				return membership
-			}
-		} catch {
-			// Authentication fails closed when membership cannot be verified.
-		}
-		return errors.throw({ code: 'FORBIDDEN' })
-	}
-
-	function requireRole(role: Role, allowed: readonly Role[]) {
-		if (!allowed.includes(role)) return errors.throw({ code: 'FORBIDDEN' })
-	}
-
-	async function queryInput(ctx: GenericQueryCtx<DataModel>) {
-		const bundle = await authenticatedUser(ctx)
-		return {
-			ctx: { ...secureReader(ctx, bundle), include, ...bundle },
-			args: {},
-		}
-	}
-
-	async function mutationInput(ctx: GenericMutationCtx<DataModel>) {
-		const bundle = await authenticatedUser(ctx)
-		return {
-			ctx: { ...secureWriter(wrapDB(ctx), bundle), include, ...bundle },
-			args: {},
-		}
-	}
-
-	async function actionInput(ctx: GenericActionCtx<DataModel>) {
-		const authenticated = await authenticatedUser(ctx)
-		const membership = await verifiedMembership(
-			authenticated.user.id,
-			authenticated.org.organizationId,
-		)
-		if (!membership) return { ctx: { ...ctx, ...authenticated }, args: {} }
-		const role = config.mapRole(membership.roleSlug)
-		if (!role) return errors.throw({ code: 'FORBIDDEN' })
-		const verified = {
-			identity: authenticated.identity,
-			user: authenticated.user,
-			org: Object.freeze({
-				organizationId: membership.organizationId,
-				role,
-			}),
-			role,
-			actor: Object.freeze({
-				userId: authenticated.user.id,
-				organizationId: membership.organizationId,
-				role,
-			}),
-		}
-		return {
-			ctx: {
-				...ctx,
-				...verified,
-				// Tenant re-derives from the live-verified organization.
-				tenant:
-					config.security?.tenancy?.resolve?.(verified) ??
-					membership.organizationId,
-			},
-			args: {},
-		}
-	}
-
-	/** Query constructor allowing only the given roles. */
-	function roleQuery(...allowed: readonly Role[]) {
-		return zCustomQuery(config.query, {
-			args: {},
-			input: async (ctx) => {
-				const authenticated = await queryInput(ctx)
-				requireRole(authenticated.ctx.actor.role, allowed)
-				return authenticated
-			},
-		})
-	}
-
-	/** Mutation constructor allowing only the given roles. */
-	function roleMutation(...allowed: readonly Role[]) {
-		return zCustomMutation(config.mutation, {
-			args: {},
-			input: async (ctx) => {
-				const authenticated = await mutationInput(ctx)
-				requireRole(authenticated.ctx.actor.role, allowed)
-				return authenticated
-			},
-		})
-	}
-
-	/** Action constructor allowing only the given roles (post live verification). */
-	function roleAction(...allowed: readonly Role[]) {
-		return zCustomAction(config.action, {
-			args: {},
-			input: async (ctx) => {
-				const authenticated = await actionInput(ctx)
-				requireRole(authenticated.ctx.actor.role, allowed)
-				return authenticated
-			},
-		})
-	}
-
-	return {
-		include,
-		authenticatedUser,
-		roleQuery,
-		roleMutation,
-		roleAction,
-		authQuery: zCustomQuery(config.query, { args: {}, input: queryInput }),
-		authMutation: zCustomMutation(config.mutation, {
-			args: {},
-			input: mutationInput,
-		}),
-		authAction: zCustomAction(config.action, {
-			args: {},
-			input: actionInput,
-		}),
-		adminQuery: roleQuery(...config.adminRoles),
-		adminMutation: roleMutation(...config.adminRoles),
-		adminAction: roleAction(...config.adminRoles),
-		systemMutation: zCustomMutation(config.internalMutation, {
-			args: {},
-			input: async (ctx) => ({ ctx: { ...wrapDB(ctx), include }, args: {} }),
-		}),
-		systemAction: zCustomAction(config.internalAction, {
-			args: {},
-			input: async (ctx) => ({ ctx, args: {} }),
-		}),
-	}
-}