cvx-kit 0.1.7 → 0.1.10

package/CHANGELOG.md

@@ -12,6 +12,21 @@ are this file's matching section.
 
 ## [Unreleased]
 
+## [0.1.10] - 2026-10-09
+
+### Fixed
+
+- Preserve native Convex context types in auth, role, admin, and system function
+  constructors so secured handlers bind directly to Effect registries (#22).
+- Install Standard Schema types explicitly so native contract input and output
+  inference works in clean installations.
+
+### Changed
+
+- Update package dependencies and migrate the development toolchain to Vite+ 1.1.
+- Require Convex 1.46 or newer and convex-helpers 0.1.127 or newer (below 0.2.0),
+  matching workflow 0.4.10.
+
 ## [0.1.7] - 2026-10-07
 
 ### Added

package/README.md

@@ -13,7 +13,7 @@ bun add cvx-kit
 # or: npm install cvx-kit
 ```
 
-Supported versions: Convex `^1.45.0`, Zod `^4.5.4`, Bun `1.3+`, and Node.js
+Supported versions: Convex `^1.46.0`, Zod `^4.5.4`, Bun `1.3+`, and Node.js
 `24+` with npm `11+`. The library runtime is ESM-only.
 
 ## Toolchain
@@ -35,7 +35,7 @@ authored in [`src/docs/`](./src/docs/):
 - [`conventions.md`](./src/docs/conventions.md) — the doctrine: folder structure, file anatomy, naming grammar, import rules
 - [`zod-table.md`](./src/docs/zod-table.md) — one zod shape per entity, masked into every boundary
 - [`auth.md`](./src/docs/auth.md) — auth-aware function constructors from injected policy
-- [`commands.md`](./src/docs/commands.md) — Foundation, the audited command protocol, observability
+- [`commands.md`](./src/docs/commands.md) — Effect command declarations, lifecycle, and migration
 - [`effect.md`](./src/docs/effect.md) — opt-in Effect v4 registries, injected services, and shared API builders
 - [`domain-operations.md`](./src/docs/domain-operations.md) — server domain/API examples, contracts, errors, receipts, workflow steps, and selected tools
 - [`triggers.md`](./src/docs/triggers.md) — trigger registry, timestamps/append-only/no-delete
@@ -128,57 +128,67 @@ registry structurally; `include()` bounds every read (default 100 rows).
 `resolveOrganization` derives org and role from your own tables, enabling
 identity providers whose tokens carry no org claims.
 
-### `cvx-kit/components/foundation`
+### `cvx-kit/effect` — commands and queries
 
-Declared once; everything destructures from it. `Command` comes out of the
-Foundation already bound to observability and the audit writer — there is no
-separate command import.
+Use the Effect API for new commands. Install Effect `>=4.0.1 <5`, bind host
+policies once with `createEffectFoundation`, and declare each handler inside
+`command({...})` beside its schemas and audit policy.
 
-```ts
-// convex/convex.config.ts
-import foundation from 'cvx-kit/components/foundation/convex.config'
-app.use(foundation)
-
-// convex/foundation.ts — declared once, the single kernel source
-import { Foundation } from 'cvx-kit/components/foundation'
-export const { Command, Query, observability } = new Foundation(
-  components.foundation,
-  {
-    observability: {
-      enabled: () => env.OBS === 'true',
-      classifyError,
-      writeAudit: (ctx, entry) => writeAuditEntry(ctx, entry),
-    },
-  },
-)
+<!-- packed-effect-example -->
 
-// convex/domain/<owner>/commands.ts
-import { Command } from '../foundation'
-
-const commands = new Command({
-  'documents.rename': Command.operation({
-    command: renameInput,
-    result: renameResult,
-    classification: 'business',
-    audit: ({ command }, ctx) => ({ ... }),
-  }),
+```ts
+import { createEffectFoundation } from 'cvx-kit/effect'
+import type { AuditEntryInput } from 'cvx-kit/components/foundation'
+import { z } from 'zod'
+
+type Host = {
+	actorId: string
+	rename: (id: string, title: string) => Promise<void>
+	appendAudit: (entry: AuditEntryInput) => Promise<void>
+}
+const { Command } = createEffectFoundation({
+	observability: {
+		enabled: false,
+		classifyError: () => ({ outcome: 'failed', errorCode: 'RENAME_FAILED' }),
+	},
+	writeAudit: (host: Host, entry) => host.appendAudit(entry),
 })
-export const executeRename = commands.exec({ operation: 'documents.rename', handler })
+const renameInput = z.object({ id: z.string(), title: z.string() }).strict()
+export const commands = Command({
+	context: (host: Host) => host,
+	operations: ({ command }) => ({
+		'documents.rename': command({
+			input: renameInput,
+			result: z.object({ ok: z.literal(true) }).strict(),
+			classification: 'business',
+			handler: async (input, context) => {
+				await context.rename(input.id, input.title)
+				return { ok: true as const }
+			},
+			audit: ({ command }, context) => ({
+				operation: 'documents.rename',
+				actorId: context.actorId,
+				aggregate: { type: 'document', id: command.id },
+			}),
+		}),
+	}),
+})
+export const executeRename = (input: z.input<typeof renameInput>, host: Host) =>
+	commands.exec('documents.rename', input, host)
 ```
 
-Every command is validated (input and output zod-parsed), observed, and
-audited in-transaction. `classification` and `audit()` are mandatory per
-operation: auditing is type-enforced, not opt-in. The foundation component
-itself owns zero tables and ships `executeResultBoundary` (typed failures
-only while the transaction has no effects; otherwise rethrow so Convex
-rolls back).
+`exec` returns a lazy Effect even for ordinary async handlers. Shared
+`effectApiBuilder` / `effectZodApiBuilder` constructors provide invocation-local
+services and execute it; domain code can compose `Effect.gen` and `Effect.fn`
+without starting another runner. Commands validate inputs and results, enforce
+permissions and guards, and write audit entries in the mutation transaction.
+See [commands](./src/docs/commands.md), [complete Effect wiring](./src/docs/effect.md),
+and [authenticated builders](./src/docs/auth.md).
 
-For cohesive command/query entries that include their handlers, use
-[`cvx-kit/effect`](./src/docs/effect.md). Install Effect `>=4.0.1 <5` separately;
-ordinary handlers, `Effect.gen`, and `Effect.fn` compose through the same
-registry. Shared API builders provide invocation-local services and execute
-the Effect. Existing Foundation declarations and Promise executors remain
-supported, so domains can migrate independently.
+The old `Foundation.Command` Promise facade is **deprecated** and retained for
+existing consumers. Its separate executor handler options are covered only in
+the [compatibility reference](./src/docs/commands-legacy.md). The Foundation
+component and its transaction result helpers remain available.
 
 ### `cvx-kit/components/approvals` (component)
 
@@ -237,7 +247,7 @@ module cycles. Run Oxlint on the whole backend, including `convex.config.ts`;
 changed-file-only lint cannot guarantee a project scan. No application-owned
 architecture test framework is required. The plugin also exports `checkArchitecture()`
 for tools that need project diagnostics directly, named `rules`, and `RuleName`. Verified with
-Oxlint 1.79.0 and Vite+ 0.3.0. See [rule coverage and limitations](./src/docs/oxlint.md)
+Oxlint 1.87.0 and Vite+ 1.1.0. See [rule coverage and limitations](./src/docs/oxlint.md)
 and the [migration from the initial 0.1.4 plugin](./src/docs/upgrading.md).
 
 Repository checks and the enforced library rules are documented in
@@ -297,3 +307,9 @@ One-time setup (already-published package required first):
 ## Roadmap
 
 See [ROADMAP.md](./ROADMAP.md) — milestones from 0.1.0 through 1.0.0.
+
+Optional request context can be added through the existing Effect API adapter's
+`context` callback. Bind selected registries with `commands.withContext(value)`
+and consume `ctx.commands.exec(name, input)` through the application's existing
+function helper names. Keep dependencies local to each feature; explicit execution
+and input-only command handlers remain supported. See [optional context injection](./src/docs/command-context.md).

package/dist/agent-tools.d.mts

@@ -7,7 +7,7 @@ import { z } from "zod";
  * adaptable to ai-sdk tool(). The kit imports neither framework — checked
  * against registry snapshots on 2026-08-14; re-verify at install time.
  */
-type AgentToolRecord<Result = unknown, Context = never, Input = never> = {
+export type AgentToolRecord<Result = unknown, Context = never, Input = never> = {
   name: string;
   description: string;
   args: z.ZodType;
@@ -22,7 +22,7 @@ type ToolTable = {
   };
 };
 type ToolHandler<Result> = (ctx: never, input: never) => Promise<Result>;
-type AgentToolHandlers<Result = unknown> = {
+export type AgentToolHandlers<Result = unknown> = {
   /** Mutations: route through command executors — agents get audited commands. */
   create?: ToolHandler<Result>;
   update?: ToolHandler<Result>;
@@ -48,15 +48,15 @@ declare const listArgs: z.ZodObject<{
  * are emitted. Wire mutation handlers to createCrudCommands executors (or
  * your own) so every agent action is an audited command.
  */
-declare function createAgentTools<Table extends ToolTable, Handlers extends AgentToolHandlers>(table: Table, handlers: Handlers, options?: {
+export declare function createAgentTools<Table extends ToolTable, Handlers extends AgentToolHandlers>(table: Table, handlers: Handlers, options?: {
   descriptions?: Partial<Record<keyof AgentToolHandlers, string>>;
 }): AgentTools<Table, Handlers>;
-type AgentTools<Table extends ToolTable, Handlers extends AgentToolHandlers> = Partial<{ [Verb in keyof Handlers & keyof AgentToolHandlers as `${Table['tableName']}_${Verb}`]: {
+export type AgentTools<Table extends ToolTable, Handlers extends AgentToolHandlers> = Partial<{ [Verb in keyof Handlers & keyof AgentToolHandlers as `${Table['tableName']}_${Verb}`]: {
   name: string;
   description: string;
   args: Verb extends 'create' ? Table['tools']['insert'] : Verb extends 'update' ? Table['tools']['update'] : Verb extends 'list' ? typeof listArgs : Table['tools']['id'];
   handler: NonNullable<Handlers[Verb]>;
 }; }>;
 //#endregion
-export { AgentToolHandlers, AgentToolRecord, AgentTools, type OperationExecutor, type OperationPublicResult, type OperationTool, type OperationToolConverter, type OperationToolDefinition, type OperationToolJsonSchema, type OperationToolOutcome, type SelectedOperation, bindOperationExecutor, createAgentTools, createOperationTools, operationToolDialect, selectOperation };
+export { type OperationExecutor, type OperationPublicResult, type OperationTool, type OperationToolConverter, type OperationToolDefinition, type OperationToolJsonSchema, type OperationToolOutcome, type SelectedOperation, bindOperationExecutor, createOperationTools, operationToolDialect, selectOperation };
 //# sourceMappingURL=agent-tools.d.mts.map

package/dist/agent-tools.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"agent-tools.mjs","names":[],"sources":["../src/agent-tools.ts"],"sourcesContent":["import { convexToZod } from 'convex-helpers/server/zod4'\nimport { paginationOptsValidator } from 'convex/server'\nimport { z } from 'zod'\n\n/**\n * A framework-agnostic tool record: directly spreadable into\n * @convex-dev/agent's createTool ({ description, args, handler }) and\n * adaptable to ai-sdk tool(). The kit imports neither framework — checked\n * against registry snapshots on 2026-08-14; re-verify at install time.\n */\nexport type AgentToolRecord<Result = unknown, Context = never, Input = never> = {\n\tname: string\n\tdescription: string\n\targs: z.ZodType\n\thandler: (ctx: Context, input: Input) => Promise<Result>\n}\n\ntype ToolTable = {\n\ttableName: string\n\ttools: {\n\t\tinsert: z.ZodType\n\t\tupdate: z.ZodType\n\t\tid: z.ZodType\n\t}\n}\n\ntype ToolHandler<Result> = (ctx: never, input: never) => Promise<Result>\n\nexport type AgentToolHandlers<Result = unknown> = {\n\t/** Mutations: route through command executors — agents get audited commands. */\n\tcreate?: ToolHandler<Result>\n\tupdate?: ToolHandler<Result>\n\tarchive?: ToolHandler<Result>\n\t/** Reads: caller-supplied query handlers (reads do not route through commands). */\n\tget?: ToolHandler<Result>\n\tlist?: ToolHandler<Result>\n}\n\nconst listArgs = z.object({ paginationOpts: convexToZod(paginationOptsValidator) }).strict()\n\n/**\n * Emits agent tool definitions from the existing table tool masks: args are\n * the masks (jsonSafeZid keeps ids primitive in generated JSON schemas),\n * names are `<tableName>_<verb>`, and only the kinds you supply handlers for\n * are emitted. Wire mutation handlers to createCrudCommands executors (or\n * your own) so every agent action is an audited command.\n */\nexport function createAgentTools<Table extends ToolTable, Handlers extends AgentToolHandlers>(\n\ttable: Table,\n\thandlers: Handlers,\n\toptions?: { descriptions?: Partial<Record<keyof AgentToolHandlers, string>> },\n) {\n\tconst name = table.tableName\n\tconst masks: Record<keyof AgentToolHandlers, z.ZodType> = {\n\t\tcreate: table.tools.insert,\n\t\tupdate: table.tools.update,\n\t\tarchive: table.tools.id,\n\t\tget: table.tools.id,\n\t\tlist: listArgs,\n\t}\n\tconst defaults: Record<keyof AgentToolHandlers, string> = {\n\t\tcreate: `Create a ${name} record`,\n\t\tupdate: `Update fields of an existing ${name} record`,\n\t\tarchive: `Archive (soft-delete) a ${name} record`,\n\t\tget: `Fetch one ${name} record by id`,\n\t\tlist: `List ${name} records, paginated`,\n\t}\n\tconst tools: Record<string, AgentToolRecord> = {}\n\tfor (const verb of ['create', 'update', 'archive', 'get', 'list'] as const) {\n\t\tconst handler = handlers[verb]\n\t\tif (!handler) continue\n\t\ttools[`${name}_${verb}`] = {\n\t\t\tname: `${name}_${verb}`,\n\t\t\tdescription: options?.descriptions?.[verb] ?? defaults[verb],\n\t\t\targs: masks[verb],\n\t\t\thandler,\n\t\t}\n\t}\n\t// SAFETY: each emitted key combines this table name with a supplied verb; its handler and schema come from those same inputs.\n\treturn tools as AgentTools<Table, Handlers>\n}\n\nexport type AgentTools<Table extends ToolTable, Handlers extends AgentToolHandlers> = Partial<{\n\t[Verb in keyof Handlers & keyof AgentToolHandlers as `${Table['tableName']}_${Verb}`]: {\n\t\tname: string\n\t\tdescription: string\n\t\targs: Verb extends 'create'\n\t\t\t? Table['tools']['insert']\n\t\t\t: Verb extends 'update'\n\t\t\t\t? Table['tools']['update']\n\t\t\t\t: Verb extends 'list'\n\t\t\t\t\t? typeof listArgs\n\t\t\t\t\t: Table['tools']['id']\n\t\thandler: NonNullable<Handlers[Verb]>\n\t}\n}>\nexport {\n\tselectOperation,\n\tbindOperationExecutor,\n\tcreateOperationTools,\n\toperationToolDialect,\n\ttype SelectedOperation,\n\ttype OperationExecutor,\n\ttype OperationPublicResult,\n\ttype OperationToolJsonSchema,\n\ttype OperationToolConverter,\n\ttype OperationToolDefinition,\n\ttype OperationToolOutcome,\n\ttype OperationTool,\n} from './modules/contracts/exposure'\n"],"mappings":"2RAsCA,MAAM,EAAW,EAAE,OAAO,CAAE,eAAgB,EAAY,CAAuB,CAAE,CAAC,CAAC,CAAC,OAAO,EAS3F,SAAgB,EACf,EACA,EACA,EACC,CACD,IAAM,EAAO,EAAM,UACb,EAAoD,CACzD,OAAQ,EAAM,MAAM,OACpB,OAAQ,EAAM,MAAM,OACpB,QAAS,EAAM,MAAM,GACrB,IAAK,EAAM,MAAM,GACjB,KAAM,CACP,EACM,EAAoD,CACzD,OAAQ,YAAY,EAAK,SACzB,OAAQ,gCAAgC,EAAK,SAC7C,QAAS,2BAA2B,EAAK,SACzC,IAAK,aAAa,EAAK,eACvB,KAAM,QAAQ,EAAK,oBACpB,EACM,EAAyC,CAAC,EAChD,IAAK,IAAM,IAAQ,CAAC,SAAU,SAAU,UAAW,MAAO,MAAM,EAAY,CAC3E,IAAM,EAAU,EAAS,GACpB,IACL,EAAM,GAAG,EAAK,GAAG,KAAU,CAC1B,KAAM,GAAG,EAAK,GAAG,IACjB,YAAa,GAAS,eAAe,IAAS,EAAS,GACvD,KAAM,EAAM,GACZ,SACD,EACD,CAEA,OAAO,CACR"}
+{"version":3,"file":"agent-tools.mjs","names":["listArgs","z","convexToZod","paginationOptsValidator","createAgentTools","name","table","masks","defaults","tools","verb","handler","handlers","options","bindOperationExecutor","createOperationTools","operationToolDialect","selectOperation"],"sources":["../src/agent-tools.ts"],"sourcesContent":["import { convexToZod } from 'convex-helpers/server/zod4'\nimport { paginationOptsValidator } from 'convex/server'\nimport { z } from 'zod'\n\n/**\n * A framework-agnostic tool record: directly spreadable into\n * @convex-dev/agent's createTool ({ description, args, handler }) and\n * adaptable to ai-sdk tool(). The kit imports neither framework — checked\n * against registry snapshots on 2026-08-14; re-verify at install time.\n */\nexport type AgentToolRecord<Result = unknown, Context = never, Input = never> = {\n\tname: string\n\tdescription: string\n\targs: z.ZodType\n\thandler: (ctx: Context, input: Input) => Promise<Result>\n}\n\ntype ToolTable = {\n\ttableName: string\n\ttools: {\n\t\tinsert: z.ZodType\n\t\tupdate: z.ZodType\n\t\tid: z.ZodType\n\t}\n}\n\ntype ToolHandler<Result> = (ctx: never, input: never) => Promise<Result>\n\nexport type AgentToolHandlers<Result = unknown> = {\n\t/** Mutations: route through command executors — agents get audited commands. */\n\tcreate?: ToolHandler<Result>\n\tupdate?: ToolHandler<Result>\n\tarchive?: ToolHandler<Result>\n\t/** Reads: caller-supplied query handlers (reads do not route through commands). */\n\tget?: ToolHandler<Result>\n\tlist?: ToolHandler<Result>\n}\n\nconst listArgs = z.object({ paginationOpts: convexToZod(paginationOptsValidator) }).strict()\n\n/**\n * Emits agent tool definitions from the existing table tool masks: args are\n * the masks (jsonSafeZid keeps ids primitive in generated JSON schemas),\n * names are `<tableName>_<verb>`, and only the kinds you supply handlers for\n * are emitted. Wire mutation handlers to createCrudCommands executors (or\n * your own) so every agent action is an audited command.\n */\nexport function createAgentTools<Table extends ToolTable, Handlers extends AgentToolHandlers>(\n\ttable: Table,\n\thandlers: Handlers,\n\toptions?: { descriptions?: Partial<Record<keyof AgentToolHandlers, string>> },\n) {\n\tconst name = table.tableName\n\tconst masks: Record<keyof AgentToolHandlers, z.ZodType> = {\n\t\tcreate: table.tools.insert,\n\t\tupdate: table.tools.update,\n\t\tarchive: table.tools.id,\n\t\tget: table.tools.id,\n\t\tlist: listArgs,\n\t}\n\tconst defaults: Record<keyof AgentToolHandlers, string> = {\n\t\tcreate: `Create a ${name} record`,\n\t\tupdate: `Update fields of an existing ${name} record`,\n\t\tarchive: `Archive (soft-delete) a ${name} record`,\n\t\tget: `Fetch one ${name} record by id`,\n\t\tlist: `List ${name} records, paginated`,\n\t}\n\tconst tools: Record<string, AgentToolRecord> = {}\n\tfor (const verb of ['create', 'update', 'archive', 'get', 'list'] as const) {\n\t\tconst handler = handlers[verb]\n\t\tif (!handler) continue\n\t\ttools[`${name}_${verb}`] = {\n\t\t\tname: `${name}_${verb}`,\n\t\t\tdescription: options?.descriptions?.[verb] ?? defaults[verb],\n\t\t\targs: masks[verb],\n\t\t\thandler,\n\t\t}\n\t}\n\t// SAFETY: each emitted key combines this table name with a supplied verb; its handler and schema come from those same inputs.\n\treturn tools as AgentTools<Table, Handlers>\n}\n\nexport type AgentTools<Table extends ToolTable, Handlers extends AgentToolHandlers> = Partial<{\n\t[Verb in keyof Handlers & keyof AgentToolHandlers as `${Table['tableName']}_${Verb}`]: {\n\t\tname: string\n\t\tdescription: string\n\t\targs: Verb extends 'create'\n\t\t\t? Table['tools']['insert']\n\t\t\t: Verb extends 'update'\n\t\t\t\t? Table['tools']['update']\n\t\t\t\t: Verb extends 'list'\n\t\t\t\t\t? typeof listArgs\n\t\t\t\t\t: Table['tools']['id']\n\t\thandler: NonNullable<Handlers[Verb]>\n\t}\n}>\nexport {\n\tselectOperation,\n\tbindOperationExecutor,\n\tcreateOperationTools,\n\toperationToolDialect,\n\ttype SelectedOperation,\n\ttype OperationExecutor,\n\ttype OperationPublicResult,\n\ttype OperationToolJsonSchema,\n\ttype OperationToolConverter,\n\ttype OperationToolDefinition,\n\ttype OperationToolOutcome,\n\ttype OperationTool,\n} from './modules/contracts/exposure'\n"],"mappings":"2RAsCA,MAAMA,EAAWC,EAAE,OAAO,CAAE,eAAgBC,EAAYC,CAAuB,CAAE,CAAC,CAAC,CAAC,OAAO,EAS3F,SAAgBC,EACf,EACA,EACA,EACC,CACD,IAAMC,EAAOC,EAAM,UACbC,EAAoD,CACzD,OAAQD,EAAM,MAAM,OACpB,OAAQA,EAAM,MAAM,OACpB,QAASA,EAAM,MAAM,GACrB,IAAKA,EAAM,MAAM,GACjB,KAAMN,CACP,EACMQ,EAAoD,CACzD,OAAQ,YAAYH,EAAK,SACzB,OAAQ,gCAAgCA,EAAK,SAC7C,QAAS,2BAA2BA,EAAK,SACzC,IAAK,aAAaA,EAAK,eACvB,KAAM,QAAQA,EAAK,oBACpB,EACMI,EAAyC,CAAC,EAChD,IAAK,IAAMC,IAAQ,CAAC,SAAU,SAAU,UAAW,MAAO,MAAM,EAAY,CAC3E,IAAMC,EAAUC,EAASF,GACpBC,IACL,EAAM,GAAGN,EAAK,GAAGK,KAAU,CAC1B,KAAM,GAAGL,EAAK,GAAGK,IACjB,YAAaG,GAAS,eAAeH,IAASF,EAASE,GACvD,KAAMH,EAAMG,GACZ,SACD,EACD,CAEA,OAAOD,CACR"}

package/dist/auth.d.mts

@@ -1,16 +1,17 @@
 import { ErrorFactory } from "./errors.mjs";
 import { RLSConfig, Rules } from "./tenancy.mjs";
+import { CustomBuilder } from "convex-helpers/server/zod4";
 import { ActionBuilder, DocumentByInfo, GenericActionCtx, GenericDataModel, GenericMutationCtx, GenericQueryCtx, GenericTableInfo, IndexNames, IndexRange, IndexRangeBuilder, MutationBuilder, NamedIndex, PaginationOptions, PaginationResult, Query, QueryBuilder, QueryInitializer, TableNamesInDataModel, UserIdentity } from "convex/server";
 import { Triggers } from "convex-helpers/server/triggers";
 //#region src/auth.d.ts
 /** The default vocabulary; every app can supply its own via the Role generic. */
-type DefaultRole = 'reader' | 'writer' | 'admin';
-type Actor<Role extends string> = Readonly<{
+export type DefaultRole = 'reader' | 'writer' | 'admin';
+export type Actor<Role extends string> = Readonly<{
   userId: string;
   organizationId: string;
   role: Role;
 }>;
-type AuthBundle<Role extends string> = Readonly<{
+export type AuthBundle<Role extends string> = Readonly<{
   identity: UserIdentity;
   user: Readonly<{
     id: string;
@@ -29,7 +30,7 @@ type AuthBundle<Role extends string> = Readonly<{
  * compose (AND) onto the same wrapped database: queries get a wrapped
  * reader, mutations get triggers first, then a wrapped writer.
  */
-type SecurityConfig<DataModel extends GenericDataModel, Role extends string> = {
+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
@@ -54,7 +55,7 @@ type SecurityConfig<DataModel extends GenericDataModel, Role extends string> = {
   defaultPolicy?: RLSConfig['defaultPolicy'];
 };
 type AnyAuthContext<DataModel extends GenericDataModel> = GenericQueryCtx<DataModel> | GenericMutationCtx<DataModel> | GenericActionCtx<DataModel>;
-type AuthFunctionsConfig<DataModel extends GenericDataModel, Role extends string> = {
+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'>;
@@ -121,8 +122,8 @@ type AuthFunctionsConfig<DataModel extends GenericDataModel, Role extends string
   security?: SecurityConfig<DataModel, Role>;
 };
 /** WorkOS-style default: `member` writes; reader/writer/admin pass through. */
-declare function defaultRoleMap(roleSlug?: string): DefaultRole | null;
-type IncludedQuery<Table extends GenericTableInfo> = {
+export declare function defaultRoleMap(roleSlug?: string): DefaultRole | 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>;
@@ -139,9 +140,37 @@ type IncludedQuery<Table extends GenericTableInfo> = {
   paginate(opts: PaginationOptions): Promise<PaginationResult<DocumentByInfo<Table>>>;
   paginate<Item>(opts: PaginationOptions, transform: (page: DocumentByInfo<Table>[]) => Item[] | Promise<Item[]>): Promise<PaginationResult<Item>>;
 };
-type Include = <Table extends GenericTableInfo>(query: QueryInitializer<Table>) => IncludedQuery<Table>;
+export type Include = <Table extends GenericTableInfo>(query: QueryInitializer<Table>) => IncludedQuery<Table>;
+/**
+ * Keep native contexts symbolic in published declarations. Inferred spreads
+ * copy build-time Convex methods and override the consumer's native context.
+ */
+export type AuthFunctions<DataModel extends GenericDataModel, Role extends string = DefaultRole> = {
+  include: Include;
+  authenticatedUser: (ctx: AnyAuthContext<DataModel>) => Promise<AuthBundle<Role>>;
+  authQuery: CustomBuilder<'query', {}, GenericQueryCtx<DataModel> & AuthBundle<Role> & {
+    include: Include;
+  }, {}, GenericQueryCtx<DataModel>, 'public', object>;
+  authMutation: CustomBuilder<'mutation', {}, GenericMutationCtx<DataModel> & AuthBundle<Role> & {
+    include: Include;
+  }, {}, GenericMutationCtx<DataModel>, 'public', object>;
+  authAction: CustomBuilder<'action', {}, GenericActionCtx<DataModel> & AuthBundle<Role>, {}, GenericActionCtx<DataModel>, 'public', object>;
+  roleQuery: (...allowed: readonly Role[]) => AuthFunctions<DataModel, Role>['authQuery'];
+  roleMutation: (...allowed: readonly Role[]) => AuthFunctions<DataModel, Role>['authMutation'];
+  roleAction: (...allowed: readonly Role[]) => AuthFunctions<DataModel, Role>['authAction'];
+  adminQuery: AuthFunctions<DataModel, Role>['authQuery'];
+  adminMutation: AuthFunctions<DataModel, Role>['authMutation'];
+  adminAction: AuthFunctions<DataModel, Role>['authAction'];
+  systemQuery: CustomBuilder<'query', {}, GenericQueryCtx<DataModel> & {
+    include: Include;
+  }, {}, GenericQueryCtx<DataModel>, 'internal', object>;
+  systemMutation: CustomBuilder<'mutation', {}, GenericMutationCtx<DataModel> & {
+    include: Include;
+  }, {}, GenericMutationCtx<DataModel>, 'internal', object>;
+  systemAction: CustomBuilder<'action', {}, GenericActionCtx<DataModel>, {}, GenericActionCtx<DataModel>, 'internal', object>;
+};
 /** Builds an include() that selects the first matching indexed query and bounds the read. */
-declare function createInclude(options?: {
+export declare function createInclude(options?: {
   errors?: ErrorFactory;
   maxRows?: number;
 }): Include;
@@ -153,285 +182,6 @@ declare function createInclude(options?: {
  * has a role-gated variant (roleQuery/roleMutation/roleAction), and the
  * admin* constructors are just that gate applied to config.adminRoles.
  */
-declare function createAuthFunctions<DataModel extends GenericDataModel, const Role extends string = DefaultRole>(config: AuthFunctionsConfig<DataModel, Role>): {
-  include: Include;
-  authenticatedUser: (ctx: AnyAuthContext<DataModel>) => Promise<AuthBundle<Role>>;
-  roleQuery: (...allowed: readonly Role[]) => import("convex-helpers/server/zod4").CustomBuilder<"query", {}, {
-    db: import("convex/server").GenericDatabaseReader<DataModel>;
-    auth: import("convex/server").Auth;
-    storage: import("convex/server").StorageReader;
-    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, {
-      transactionLimits?: import("convex/server").TransactionLimits;
-    }>) => Promise<import("convex/server").FunctionReturnType<Query>>;
-    meta: import("convex/server").QueryMeta;
-    identity: UserIdentity;
-    user: Readonly<{
-      id: string;
-    }>;
-    org: Readonly<{
-      organizationId: string;
-      role: Role;
-    }>;
-    role: Role;
-    actor: Readonly<{
-      userId: string;
-      organizationId: string;
-      role: Role;
-    }>;
-    tenant: string;
-    include: Include;
-  }, {}, GenericQueryCtx<DataModel>, "public", object>;
-  roleMutation: (...allowed: readonly Role[]) => import("convex-helpers/server/zod4").CustomBuilder<"mutation", {}, {
-    db: import("convex/server").GenericDatabaseWriter<DataModel>;
-    auth: import("convex/server").Auth;
-    storage: import("convex/server").StorageWriter;
-    scheduler: import("convex/server").Scheduler;
-    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, import("convex/server").AdvancedRunQueryOptions>) => Promise<import("convex/server").FunctionReturnType<Query>>;
-    runMutation: <Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").ArgsAndOptions<Mutation, {
-      transactionLimits?: import("convex/server").TransactionLimits;
-    }>) => Promise<import("convex/server").FunctionReturnType<Mutation>>;
-    meta: import("convex/server").MutationMeta;
-    identity: UserIdentity;
-    user: Readonly<{
-      id: string;
-    }>;
-    org: Readonly<{
-      organizationId: string;
-      role: Role;
-    }>;
-    role: Role;
-    actor: Readonly<{
-      userId: string;
-      organizationId: string;
-      role: Role;
-    }>;
-    tenant: string;
-    include: Include;
-  }, {}, GenericMutationCtx<DataModel>, "public", object>;
-  roleAction: (...allowed: readonly Role[]) => import("convex-helpers/server/zod4").CustomBuilder<"action", {}, {
-    runQuery<Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").OptionalRestArgs<Query>): Promise<import("convex/server").FunctionReturnType<Query>>;
-    runMutation<Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").OptionalRestArgs<Mutation>): Promise<import("convex/server").FunctionReturnType<Mutation>>;
-    runAction<Action extends import("convex/server").FunctionReference<"action", "public" | "internal">>(action: Action, ...args: import("convex/server").OptionalRestArgs<Action>): Promise<import("convex/server").FunctionReturnType<Action>>;
-    scheduler: import("convex/server").Scheduler;
-    auth: import("convex/server").Auth;
-    storage: import("convex/server").StorageActionWriter;
-    vectorSearch<TableName extends TableNamesInDataModel<DataModel>, IndexName extends import("convex/server").VectorIndexNames<import("convex/server").NamedTableInfo<DataModel, TableName>>>(tableName: TableName, indexName: IndexName, query: {
-      vector: number[];
-      limit?: number;
-      filter?: ((q: import("convex/server").VectorFilterBuilder<DocumentByInfo<import("convex/server").NamedTableInfo<DataModel, TableName>>, import("convex/server").NamedVectorIndex<import("convex/server").NamedTableInfo<DataModel, TableName>, IndexName>>) => import("convex/server").FilterExpression<boolean>) | undefined;
-    }): Promise<{
-      _id: import("convex/values").GenericId<TableName>;
-      _score: number;
-    }[]>;
-    meta: import("convex/server").ActionMeta;
-    identity: UserIdentity;
-    user: Readonly<{
-      id: string;
-    }>;
-    org: Readonly<{
-      organizationId: string;
-      role: Role;
-    }>;
-    role: Role;
-    actor: Readonly<{
-      userId: string;
-      organizationId: string;
-      role: Role;
-    }>;
-    tenant: string;
-  }, {}, GenericActionCtx<DataModel>, "public", object>;
-  authQuery: import("convex-helpers/server/zod4").CustomBuilder<"query", {}, {
-    db: import("convex/server").GenericDatabaseReader<DataModel>;
-    auth: import("convex/server").Auth;
-    storage: import("convex/server").StorageReader;
-    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, {
-      transactionLimits?: import("convex/server").TransactionLimits;
-    }>) => Promise<import("convex/server").FunctionReturnType<Query>>;
-    meta: import("convex/server").QueryMeta;
-    identity: UserIdentity;
-    user: Readonly<{
-      id: string;
-    }>;
-    org: Readonly<{
-      organizationId: string;
-      role: Role;
-    }>;
-    role: Role;
-    actor: Readonly<{
-      userId: string;
-      organizationId: string;
-      role: Role;
-    }>;
-    tenant: string;
-    include: Include;
-  }, {}, GenericQueryCtx<DataModel>, "public", object>;
-  authMutation: import("convex-helpers/server/zod4").CustomBuilder<"mutation", {}, {
-    db: import("convex/server").GenericDatabaseWriter<DataModel>;
-    auth: import("convex/server").Auth;
-    storage: import("convex/server").StorageWriter;
-    scheduler: import("convex/server").Scheduler;
-    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, import("convex/server").AdvancedRunQueryOptions>) => Promise<import("convex/server").FunctionReturnType<Query>>;
-    runMutation: <Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").ArgsAndOptions<Mutation, {
-      transactionLimits?: import("convex/server").TransactionLimits;
-    }>) => Promise<import("convex/server").FunctionReturnType<Mutation>>;
-    meta: import("convex/server").MutationMeta;
-    identity: UserIdentity;
-    user: Readonly<{
-      id: string;
-    }>;
-    org: Readonly<{
-      organizationId: string;
-      role: Role;
-    }>;
-    role: Role;
-    actor: Readonly<{
-      userId: string;
-      organizationId: string;
-      role: Role;
-    }>;
-    tenant: string;
-    include: Include;
-  }, {}, GenericMutationCtx<DataModel>, "public", object>;
-  authAction: import("convex-helpers/server/zod4").CustomBuilder<"action", {}, {
-    runQuery<Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").OptionalRestArgs<Query>): Promise<import("convex/server").FunctionReturnType<Query>>;
-    runMutation<Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").OptionalRestArgs<Mutation>): Promise<import("convex/server").FunctionReturnType<Mutation>>;
-    runAction<Action extends import("convex/server").FunctionReference<"action", "public" | "internal">>(action: Action, ...args: import("convex/server").OptionalRestArgs<Action>): Promise<import("convex/server").FunctionReturnType<Action>>;
-    scheduler: import("convex/server").Scheduler;
-    auth: import("convex/server").Auth;
-    storage: import("convex/server").StorageActionWriter;
-    vectorSearch<TableName extends TableNamesInDataModel<DataModel>, IndexName extends import("convex/server").VectorIndexNames<import("convex/server").NamedTableInfo<DataModel, TableName>>>(tableName: TableName, indexName: IndexName, query: {
-      vector: number[];
-      limit?: number;
-      filter?: ((q: import("convex/server").VectorFilterBuilder<DocumentByInfo<import("convex/server").NamedTableInfo<DataModel, TableName>>, import("convex/server").NamedVectorIndex<import("convex/server").NamedTableInfo<DataModel, TableName>, IndexName>>) => import("convex/server").FilterExpression<boolean>) | undefined;
-    }): Promise<{
-      _id: import("convex/values").GenericId<TableName>;
-      _score: number;
-    }[]>;
-    meta: import("convex/server").ActionMeta;
-    identity: UserIdentity;
-    user: Readonly<{
-      id: string;
-    }>;
-    org: Readonly<{
-      organizationId: string;
-      role: Role;
-    }>;
-    role: Role;
-    actor: Readonly<{
-      userId: string;
-      organizationId: string;
-      role: Role;
-    }>;
-    tenant: string;
-  }, {}, GenericActionCtx<DataModel>, "public", object>;
-  adminQuery: import("convex-helpers/server/zod4").CustomBuilder<"query", {}, {
-    db: import("convex/server").GenericDatabaseReader<DataModel>;
-    auth: import("convex/server").Auth;
-    storage: import("convex/server").StorageReader;
-    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, {
-      transactionLimits?: import("convex/server").TransactionLimits;
-    }>) => Promise<import("convex/server").FunctionReturnType<Query>>;
-    meta: import("convex/server").QueryMeta;
-    identity: UserIdentity;
-    user: Readonly<{
-      id: string;
-    }>;
-    org: Readonly<{
-      organizationId: string;
-      role: Role;
-    }>;
-    role: Role;
-    actor: Readonly<{
-      userId: string;
-      organizationId: string;
-      role: Role;
-    }>;
-    tenant: string;
-    include: Include;
-  }, {}, GenericQueryCtx<DataModel>, "public", object>;
-  adminMutation: import("convex-helpers/server/zod4").CustomBuilder<"mutation", {}, {
-    db: import("convex/server").GenericDatabaseWriter<DataModel>;
-    auth: import("convex/server").Auth;
-    storage: import("convex/server").StorageWriter;
-    scheduler: import("convex/server").Scheduler;
-    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, import("convex/server").AdvancedRunQueryOptions>) => Promise<import("convex/server").FunctionReturnType<Query>>;
-    runMutation: <Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").ArgsAndOptions<Mutation, {
-      transactionLimits?: import("convex/server").TransactionLimits;
-    }>) => Promise<import("convex/server").FunctionReturnType<Mutation>>;
-    meta: import("convex/server").MutationMeta;
-    identity: UserIdentity;
-    user: Readonly<{
-      id: string;
-    }>;
-    org: Readonly<{
-      organizationId: string;
-      role: Role;
-    }>;
-    role: Role;
-    actor: Readonly<{
-      userId: string;
-      organizationId: string;
-      role: Role;
-    }>;
-    tenant: string;
-    include: Include;
-  }, {}, GenericMutationCtx<DataModel>, "public", object>;
-  adminAction: import("convex-helpers/server/zod4").CustomBuilder<"action", {}, {
-    runQuery<Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").OptionalRestArgs<Query>): Promise<import("convex/server").FunctionReturnType<Query>>;
-    runMutation<Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").OptionalRestArgs<Mutation>): Promise<import("convex/server").FunctionReturnType<Mutation>>;
-    runAction<Action extends import("convex/server").FunctionReference<"action", "public" | "internal">>(action: Action, ...args: import("convex/server").OptionalRestArgs<Action>): Promise<import("convex/server").FunctionReturnType<Action>>;
-    scheduler: import("convex/server").Scheduler;
-    auth: import("convex/server").Auth;
-    storage: import("convex/server").StorageActionWriter;
-    vectorSearch<TableName extends TableNamesInDataModel<DataModel>, IndexName extends import("convex/server").VectorIndexNames<import("convex/server").NamedTableInfo<DataModel, TableName>>>(tableName: TableName, indexName: IndexName, query: {
-      vector: number[];
-      limit?: number;
-      filter?: ((q: import("convex/server").VectorFilterBuilder<DocumentByInfo<import("convex/server").NamedTableInfo<DataModel, TableName>>, import("convex/server").NamedVectorIndex<import("convex/server").NamedTableInfo<DataModel, TableName>, IndexName>>) => import("convex/server").FilterExpression<boolean>) | undefined;
-    }): Promise<{
-      _id: import("convex/values").GenericId<TableName>;
-      _score: number;
-    }[]>;
-    meta: import("convex/server").ActionMeta;
-    identity: UserIdentity;
-    user: Readonly<{
-      id: string;
-    }>;
-    org: Readonly<{
-      organizationId: string;
-      role: Role;
-    }>;
-    role: Role;
-    actor: Readonly<{
-      userId: string;
-      organizationId: string;
-      role: Role;
-    }>;
-    tenant: string;
-  }, {}, GenericActionCtx<DataModel>, "public", object>;
-  systemQuery: import("convex-helpers/server/zod4").CustomBuilder<"query", {}, {
-    db: import("convex/server").GenericDatabaseReader<DataModel>;
-    auth: import("convex/server").Auth;
-    storage: import("convex/server").StorageReader;
-    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, {
-      transactionLimits?: import("convex/server").TransactionLimits;
-    }>) => Promise<import("convex/server").FunctionReturnType<Query>>;
-    meta: import("convex/server").QueryMeta;
-    include: Include;
-  }, {}, GenericQueryCtx<DataModel>, "internal", object>;
-  systemMutation: import("convex-helpers/server/zod4").CustomBuilder<"mutation", {}, {
-    db: import("convex/server").GenericDatabaseWriter<DataModel>;
-    auth: import("convex/server").Auth;
-    storage: import("convex/server").StorageWriter;
-    scheduler: import("convex/server").Scheduler;
-    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, import("convex/server").AdvancedRunQueryOptions>) => Promise<import("convex/server").FunctionReturnType<Query>>;
-    runMutation: <Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").ArgsAndOptions<Mutation, {
-      transactionLimits?: import("convex/server").TransactionLimits;
-    }>) => Promise<import("convex/server").FunctionReturnType<Mutation>>;
-    meta: import("convex/server").MutationMeta;
-    include: Include;
-  }, {}, GenericMutationCtx<DataModel>, "internal", object>;
-  systemAction: import("convex-helpers/server/zod4").CustomBuilder<"action", {}, GenericActionCtx<DataModel>, {}, GenericActionCtx<DataModel>, "internal", object>;
-};
+export declare function createAuthFunctions<DataModel extends GenericDataModel, const Role extends string = DefaultRole>(config: AuthFunctionsConfig<DataModel, Role>): AuthFunctions<DataModel, Role>;
 //#endregion
-export { Actor, AuthBundle, AuthFunctionsConfig, DefaultRole, Include, IncludedQuery, SecurityConfig, createAuthFunctions, createInclude, defaultRoleMap };
 //# sourceMappingURL=auth.d.mts.map