cvx-kit 0.1.7 → 0.1.8

package/README.md

@@ -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.
+
+<!-- packed-effect-example -->
 
 ```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),
-    },
+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' }),
   },
-)
-
-// 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) => ({ ... }),
+  writeAudit: (host: Host, entry) => host.appendAudit(entry),
+})
+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 = commands.exec({ operation: 'documents.rename', handler })
+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)
 
@@ -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/components/foundation/client.d.mts

@@ -136,18 +136,25 @@ declare class BoundCommand<Context, const Operations extends AuditedRegistry> {
     checkPermission?: PermissionChecker;
     defaults?: CommandDefaults;
   });
+  /**
+   * @deprecated Declare handlers inside command({...}) using createEffectFoundation
+   * from cvx-kit/effect, then call exec(operation, input, host).
+   */
   exec<const Key extends OperationKey<Operations>>(executor: {
     operation: Key;
     handler: (context: Context & OperationExtension<Operations[Key]>, command: CommandInput<Operations, Key>) => MaybePromise<CommandHandlerResult<Operations, Key>>;
   }): (context: Context, command: SchemaInput<Operations[Key]["command"]>) => Promise<SchemaOutput<Operations[Key]["result"]>>;
 }
+/** @deprecated Use the registry returned by createEffectFoundation(...).Command from cvx-kit/effect. */
 type ApplicationCommand<Context, Operations extends AuditedRegistry> = BoundCommand<Context, Operations>;
 /**
  * The constructor shape a Foundation instance exposes as `Command`.
  * Exported as a TYPE ONLY so factories (e.g. cvx-kit/crud) can accept the
  * destructured facade class as input without importing any runtime kernel.
+ * @deprecated Use createEffectFoundation from cvx-kit/effect and declare handlers inside command({...}).
  */
 type CommandConstructor = {
+  /** @deprecated Use createEffectFoundation(...).Command({ context, operations }) from cvx-kit/effect. */
   new <Context, const Operations extends AuditedRegistry>(operations: Operations & { readonly [Key in keyof Operations]: OperationHostContext<Context>; }, defaults?: CommandDefaults): BoundCommand<Context, Operations>;
   operation: (typeof BoundCommand)['operation'];
   withContext: (typeof BoundCommand)['withContext'];
@@ -160,6 +167,7 @@ type CommandConstructor = {
  */
 declare class Foundation<Component extends FoundationComponentApi = FoundationComponentApi> {
   readonly status: Component['functions']['status'];
+  /** @deprecated Use createEffectFoundation(...).Command from cvx-kit/effect. */
   readonly Command: CommandConstructor;
   readonly Query: typeof Query;
   readonly observability: Observability;

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 type { Value } from 'convex/values'\nimport {\n\tCommand as CommandKernelClass,\n\ttype CommandExecution,\n\ttype CommandHandlerResult,\n\ttype CommandInput,\n\ttype CommandRegistry,\n\ttype CommandResult,\n\ttype CommandSchema,\n\tdecodeCommandSchema,\n\tparseCommandSchema,\n} from './modules/command/command'\nimport { Observability, type ObservabilityOptions } from './modules/observability/observability'\nimport { Query } from './modules/query/query'\nimport {\n\texecuteCommandLifecycle,\n\tpromiseLifecycle,\n\tCommandPermissionError,\n\ttype PromiseExecution,\n} from './modules/command/lifecycle'\nimport { executeResultBoundary, projectResult } from './result'\nimport { emitSemanticEvent } from './telemetry'\nimport {\n\toperationFactory,\n\ttype CommandPreparation,\n\ttype OperationExtension,\n\ttype OperationHostContext,\n} from './operation'\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, Value>\n\tclassification: string\n}\n\nexport type AuditWriter<Result = unknown> = (\n\tcontext: never,\n\tentry: AuditEntryInput,\n) => MaybePromise<Result>\n\ntype MaybePromise<Value> = Value | Promise<Value>\ntype OperationKey<Operations extends CommandRegistry> = Extract<keyof Operations, string>\n\nexport type AuditedOperation = Readonly<{\n\tcommand: CommandSchema\n\tresult: CommandSchema\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\tprepare?: (context: never, command: never) => MaybePromise<CommandPreparation<never>>\n\treplayResult?: CommandSchema\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\t/** Per-operation middleware, inside the registry-wide chain. */\n\tmiddleware?: readonly AnyCommandMiddleware[]\n\taudit: (\n\t\tresolution: Readonly<{ command: never; result: never }>,\n\t\tcontext: never,\n\t) => MaybePromise<Omit<AuditEntryInput, 'classification'> | null>\n}>\n\n/**\n * Composable, next()-based middleware wrapping [guards → handler]. Runs\n * INSIDE the pipeline's invariants: after the permission check, before the\n * result-schema parse, aggregate allowlist, and audit — so middleware can\n * time, trace, enrich context (`next({ context })`), short-circuit, or\n * transform results, but can never skip authorization, return an invalid\n * result, or desynchronize audit from effects.\n */\nexport type CommandMiddleware<\n\tContext = never,\n\tExtension extends object = object,\n\tInput = unknown,\n\tResult = unknown,\n> = (input: {\n\toperation: string\n\tcommand: Input\n\tcontext: Context\n\tnext: (options?: {\n\t\t/** Merged into the context handed to inner middleware, guards, handler. */\n\t\tcontext?: Extension\n\t}) => Promise<Result>\n}) => Promise<Result>\n\n/** Any-context middleware — what registries and operations accept. */\n// Contravariant seam: the supertype every typed CommandMiddleware<C, E>\n// assigns to. Context, command, and next are contravariant storage slots;\n// dispatch restores the selected operation's types before invocation.\nexport type AnyCommandMiddleware<Input = never, Result = unknown, NextResult = never> = (input: {\n\toperation: string\n\tdefinition?: AuditedOperation\n\tcommand: Input\n\tcontext: never\n\tnext: (options?: { context?: object }) => Promise<NextResult>\n}) => Promise<Result>\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\t/** Outermost middleware, in array order, around every operation. */\n\tmiddleware?: readonly AnyCommandMiddleware[]\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\tstatic withContext = operationFactory\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>(definition: Definition): Definition {\n\t\treturn definition\n\t}\n\n\t/**\n\t * Identity helper that types a middleware against its context and the\n\t * context extension it passes downstream via next({ context }).\n\t */\n\tstatic middleware<\n\t\tContext = never,\n\t\tconst Extension extends object = object,\n\t\tInput = unknown,\n\t\tResult = unknown,\n\t>(\n\t\tmiddleware: CommandMiddleware<Context, Extension, Input, Result>,\n\t): CommandMiddleware<Context, Extension, Input, Result> {\n\t\treturn middleware\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\t// SAFETY: this map preserves every operations key and selects its aggregates property.\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 & OperationExtension<Operations[Key]>,\n\t\t\tcommand: CommandInput<Operations, Key>,\n\t\t) => MaybePromise<CommandHandlerResult<Operations, Key>>\n\t}) {\n\t\treturn this.#kernel.exec({\n\t\t\toperation: executor.operation,\n\t\t\thandler: (context, command) =>\n\t\t\t\texecutor.handler(\n\t\t\t\t\t// SAFETY: operationFactory requires enrichment middleware before this handler.\n\t\t\t\t\tcontext as Context & OperationExtension<Operations[Key]>,\n\t\t\t\t\tcommand,\n\t\t\t\t),\n\t\t})\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\tconst definition = execution.definition\n\t\treturn this.#observability.observe(\n\t\t\t{ operation: execution.operation, classification: definition.classification },\n\t\t\t() =>\n\t\t\t\texecuteCommandLifecycle<\n\t\t\t\t\tPromiseExecution,\n\t\t\t\t\tContext,\n\t\t\t\t\tCommandInput<Operations, Key>,\n\t\t\t\t\tCommandHandlerResult<Operations, Key>,\n\t\t\t\t\tCommandResult<Operations, Key>\n\t\t\t\t>(promiseLifecycle, {\n\t\t\t\t\toperation: execution.operation,\n\t\t\t\t\tclassification: definition.classification,\n\t\t\t\t\tcontext: execution.context,\n\t\t\t\t\tcommand: execution.command,\n\t\t\t\t\tpermission:\n\t\t\t\t\t\tdefinition.permission === undefined\n\t\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t\t: async () => {\n\t\t\t\t\t\t\t\t\tif (!this.#checkPermission) throw new CommandPermissionError(execution.operation)\n\t\t\t\t\t\t\t\t\t// SAFETY: injected policy consumes this invocation's original host context.\n\t\t\t\t\t\t\t\t\tawait this.#checkPermission(execution.context as never, {\n\t\t\t\t\t\t\t\t\t\tpermission: definition.permission!,\n\t\t\t\t\t\t\t\t\t\toperation: execution.operation,\n\t\t\t\t\t\t\t\t\t})\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\tprepare: async () => {\n\t\t\t\t\t\t// SAFETY: selected definition and parsed input are paired by the kernel.\n\t\t\t\t\t\tconst preparation = await definition.prepare?.(\n\t\t\t\t\t\t\texecution.context as never,\n\t\t\t\t\t\t\texecution.command as never,\n\t\t\t\t\t\t)\n\t\t\t\t\t\tif (preparation?.kind !== 'execute') return preparation\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tkind: 'execute' as const,\n\t\t\t\t\t\t\tcomplete: preparation.complete\n\t\t\t\t\t\t\t\t? async (result: CommandResult<Operations, Key>) => {\n\t\t\t\t\t\t\t\t\t\t// SAFETY: completion belongs to this operation's validated final result.\n\t\t\t\t\t\t\t\t\t\tawait preparation.complete!(result as never)\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t: undefined,\n\t\t\t\t\t\t}\n\t\t\t\t\t},\n\t\t\t\t\tparseReplay: (value) => {\n\t\t\t\t\t\tif (!definition.replayResult) return execution.parseResult(value)\n\t\t\t\t\t\t// SAFETY: selected replay schema validates this operation's stored output.\n\t\t\t\t\t\treturn parseCommandSchema(definition.replayResult, value) as CommandResult<\n\t\t\t\t\t\t\tOperations,\n\t\t\t\t\t\t\tKey\n\t\t\t\t\t\t>\n\t\t\t\t\t},\n\t\t\t\t\tdecodeReplay: async (value) => {\n\t\t\t\t\t\tif (!definition.replayResult) {\n\t\t\t\t\t\t\treturn execution.decodeResult\n\t\t\t\t\t\t\t\t? execution.decodeResult(value)\n\t\t\t\t\t\t\t\t: execution.parseResult(value)\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst replay = definition.replayResult\n\t\t\t\t\t\t// SAFETY: selected replay decoder owns the final output representation.\n\t\t\t\t\t\treturn (await decodeCommandSchema(replay, value)) as CommandResult<Operations, Key>\n\t\t\t\t\t},\n\t\t\t\t\tmiddleware: [...(this.#defaults.middleware ?? []), ...(definition.middleware ?? [])].map(\n\t\t\t\t\t\t(layer) => async (input) => {\n\t\t\t\t\t\t\t// SAFETY: selected definition owns this heterogeneous middleware's pre-validation output.\n\t\t\t\t\t\t\treturn layer({\n\t\t\t\t\t\t\t\t...input,\n\t\t\t\t\t\t\t\tdefinition,\n\t\t\t\t\t\t\t\t// SAFETY: selected command schema owns this heterogeneous storage value.\n\t\t\t\t\t\t\t\tcommand: input.command as never,\n\t\t\t\t\t\t\t\t// SAFETY: only heterogeneous storage erases the selected middleware context.\n\t\t\t\t\t\t\t\tcontext: input.context as never,\n\t\t\t\t\t\t\t\t// SAFETY: selected operation pairs downstream output with its final schema.\n\t\t\t\t\t\t\t\tnext: input.next as (options?: { context?: object }) => Promise<never>,\n\t\t\t\t\t\t\t}) as Promise<CommandHandlerResult<Operations, Key>>\n\t\t\t\t\t\t},\n\t\t\t\t\t),\n\t\t\t\t\tdefaultGuard: async (context) => {\n\t\t\t\t\t\t// SAFETY: default guards consume the downstream middleware context.\n\t\t\t\t\t\tawait this.#defaults.guard?.(context as never)\n\t\t\t\t\t},\n\t\t\t\t\tguard: async (context) => {\n\t\t\t\t\t\t// SAFETY: selected guard consumes its parsed input and enriched context.\n\t\t\t\t\t\tawait definition.guard?.(context as never, execution.command as never)\n\t\t\t\t\t},\n\t\t\t\t\trun: (context) => execution.runUnparsed(context),\n\t\t\t\t\tparseResult: execution.parseResult,\n\t\t\t\t\tdecodeResult: execution.decodeResult,\n\t\t\t\t\taudit: async (result) => {\n\t\t\t\t\t\t// SAFETY: audit receives this selected parsed command/result and original context.\n\t\t\t\t\t\treturn definition.audit(\n\t\t\t\t\t\t\t{ command: execution.command, result } as never,\n\t\t\t\t\t\t\texecution.context as never,\n\t\t\t\t\t\t)\n\t\t\t\t\t},\n\t\t\t\t\taggregates: definition.aggregates,\n\t\t\t\t\twriteAudit: async (entry) => {\n\t\t\t\t\t\t// SAFETY: host supplied writer for this invocation's original context.\n\t\t\t\t\t\treturn this.#writeAudit(execution.context as never, entry)\n\t\t\t\t\t},\n\t\t\t\t}),\n\t\t)\n\t}\n}\n\nexport type ApplicationCommand<Context, Operations extends AuditedRegistry> = BoundCommand<\n\tContext,\n\tOperations\n>\n\n/**\n * The constructor shape a Foundation instance exposes as `Command`.\n * Exported as a TYPE ONLY so factories (e.g. cvx-kit/crud) can accept the\n * destructured facade class as input without importing any runtime kernel.\n */\nexport type CommandConstructor = {\n\tnew <Context, const Operations extends AuditedRegistry>(\n\t\toperations: Operations & {\n\t\t\treadonly [Key in keyof Operations]: OperationHostContext<Context>\n\t\t},\n\t\tdefaults?: CommandDefaults,\n\t): BoundCommand<Context, Operations>\n\toperation: (typeof BoundCommand)['operation']\n\twithContext: (typeof BoundCommand)['withContext']\n\tmiddleware: (typeof BoundCommand)['middleware']\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<Component extends FoundationComponentApi = FoundationComponentApi> {\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\tclass HostCommand<Context, const Operations extends AuditedRegistry> extends BoundCommand<\n\t\t\tContext,\n\t\t\tOperations\n\t\t> {\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\tthis.Command = HostCommand\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 { CommandPreparation, TypedOperation } from './operation'\nexport type {\n\tCommandArgument,\n\tCommandExecution,\n\tCommandHandlerResult,\n\tCommandInput,\n\tCommandRegistry,\n\tCommandResult,\n\tSchemaOutput,\n\tParseable,\n} from './modules/command/command'\nexport type {\n\tCommandObservation,\n\tObservabilityOptions,\n} from './modules/observability/observability'\nexport type { AnyQueryMiddleware, QueryExecution, QueryMiddleware } from './modules/query/query'\nexport type { Result, ResultBoundary, TransactionMetricsContext } from './result'\n\n// The component definition is deliberately NOT re-exported here: Convex's\n// CLI only discovers a component whose resolved file is convex.config.js,\n// so hosts must mount via the dedicated subpath:\n//   import foundation from 'cvx-kit/components/foundation/convex.config'\n"],"mappings":"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"}
+{"version":3,"file":"client.mjs","names":["#kernel","#observability","#writeAudit","#checkPermission","#defaults","CommandKernelClass","#execute"],"sources":["../../../src/components/foundation/client.ts"],"sourcesContent":["import type { Value } from 'convex/values'\nimport {\n\tCommand as CommandKernelClass,\n\ttype CommandExecution,\n\ttype CommandHandlerResult,\n\ttype CommandInput,\n\ttype CommandRegistry,\n\ttype CommandResult,\n\ttype CommandSchema,\n\tdecodeCommandSchema,\n\tparseCommandSchema,\n} from './modules/command/command'\nimport { Observability, type ObservabilityOptions } from './modules/observability/observability'\nimport { Query } from './modules/query/query'\nimport {\n\texecuteCommandLifecycle,\n\tpromiseLifecycle,\n\tCommandPermissionError,\n\ttype PromiseExecution,\n} from './modules/command/lifecycle'\nimport { executeResultBoundary, projectResult } from './result'\nimport { emitSemanticEvent } from './telemetry'\nimport {\n\toperationFactory,\n\ttype CommandPreparation,\n\ttype OperationExtension,\n\ttype OperationHostContext,\n} from './operation'\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, Value>\n\tclassification: string\n}\n\nexport type AuditWriter<Result = unknown> = (\n\tcontext: never,\n\tentry: AuditEntryInput,\n) => MaybePromise<Result>\n\ntype MaybePromise<Value> = Value | Promise<Value>\ntype OperationKey<Operations extends CommandRegistry> = Extract<keyof Operations, string>\n\nexport type AuditedOperation = Readonly<{\n\tcommand: CommandSchema\n\tresult: CommandSchema\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\tprepare?: (context: never, command: never) => MaybePromise<CommandPreparation<never>>\n\treplayResult?: CommandSchema\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\t/** Per-operation middleware, inside the registry-wide chain. */\n\tmiddleware?: readonly AnyCommandMiddleware[]\n\taudit: (\n\t\tresolution: Readonly<{ command: never; result: never }>,\n\t\tcontext: never,\n\t) => MaybePromise<Omit<AuditEntryInput, 'classification'> | null>\n}>\n\n/**\n * Composable, next()-based middleware wrapping [guards → handler]. Runs\n * INSIDE the pipeline's invariants: after the permission check, before the\n * result-schema parse, aggregate allowlist, and audit — so middleware can\n * time, trace, enrich context (`next({ context })`), short-circuit, or\n * transform results, but can never skip authorization, return an invalid\n * result, or desynchronize audit from effects.\n */\nexport type CommandMiddleware<\n\tContext = never,\n\tExtension extends object = object,\n\tInput = unknown,\n\tResult = unknown,\n> = (input: {\n\toperation: string\n\tcommand: Input\n\tcontext: Context\n\tnext: (options?: {\n\t\t/** Merged into the context handed to inner middleware, guards, handler. */\n\t\tcontext?: Extension\n\t}) => Promise<Result>\n}) => Promise<Result>\n\n/** Any-context middleware — what registries and operations accept. */\n// Contravariant seam: the supertype every typed CommandMiddleware<C, E>\n// assigns to. Context, command, and next are contravariant storage slots;\n// dispatch restores the selected operation's types before invocation.\nexport type AnyCommandMiddleware<Input = never, Result = unknown, NextResult = never> = (input: {\n\toperation: string\n\tdefinition?: AuditedOperation\n\tcommand: Input\n\tcontext: never\n\tnext: (options?: { context?: object }) => Promise<NextResult>\n}) => Promise<Result>\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\t/** Outermost middleware, in array order, around every operation. */\n\tmiddleware?: readonly AnyCommandMiddleware[]\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\tstatic withContext = operationFactory\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>(definition: Definition): Definition {\n\t\treturn definition\n\t}\n\n\t/**\n\t * Identity helper that types a middleware against its context and the\n\t * context extension it passes downstream via next({ context }).\n\t */\n\tstatic middleware<\n\t\tContext = never,\n\t\tconst Extension extends object = object,\n\t\tInput = unknown,\n\t\tResult = unknown,\n\t>(\n\t\tmiddleware: CommandMiddleware<Context, Extension, Input, Result>,\n\t): CommandMiddleware<Context, Extension, Input, Result> {\n\t\treturn middleware\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\t// SAFETY: this map preserves every operations key and selects its aggregates property.\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\t/**\n\t * @deprecated Declare handlers inside command({...}) using createEffectFoundation\n\t * from cvx-kit/effect, then call exec(operation, input, host).\n\t */\n\texec<const Key extends OperationKey<Operations>>(executor: {\n\t\toperation: Key\n\t\thandler: (\n\t\t\tcontext: Context & OperationExtension<Operations[Key]>,\n\t\t\tcommand: CommandInput<Operations, Key>,\n\t\t) => MaybePromise<CommandHandlerResult<Operations, Key>>\n\t}) {\n\t\treturn this.#kernel.exec({\n\t\t\toperation: executor.operation,\n\t\t\thandler: (context, command) =>\n\t\t\t\texecutor.handler(\n\t\t\t\t\t// SAFETY: operationFactory requires enrichment middleware before this handler.\n\t\t\t\t\tcontext as Context & OperationExtension<Operations[Key]>,\n\t\t\t\t\tcommand,\n\t\t\t\t),\n\t\t})\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\tconst definition = execution.definition\n\t\treturn this.#observability.observe(\n\t\t\t{ operation: execution.operation, classification: definition.classification },\n\t\t\t() =>\n\t\t\t\texecuteCommandLifecycle<\n\t\t\t\t\tPromiseExecution,\n\t\t\t\t\tContext,\n\t\t\t\t\tCommandInput<Operations, Key>,\n\t\t\t\t\tCommandHandlerResult<Operations, Key>,\n\t\t\t\t\tCommandResult<Operations, Key>\n\t\t\t\t>(promiseLifecycle, {\n\t\t\t\t\toperation: execution.operation,\n\t\t\t\t\tclassification: definition.classification,\n\t\t\t\t\tcontext: execution.context,\n\t\t\t\t\tcommand: execution.command,\n\t\t\t\t\tpermission:\n\t\t\t\t\t\tdefinition.permission === undefined\n\t\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t\t: async () => {\n\t\t\t\t\t\t\t\t\tif (!this.#checkPermission) throw new CommandPermissionError(execution.operation)\n\t\t\t\t\t\t\t\t\t// SAFETY: injected policy consumes this invocation's original host context.\n\t\t\t\t\t\t\t\t\tawait this.#checkPermission(execution.context as never, {\n\t\t\t\t\t\t\t\t\t\tpermission: definition.permission!,\n\t\t\t\t\t\t\t\t\t\toperation: execution.operation,\n\t\t\t\t\t\t\t\t\t})\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\tprepare: async () => {\n\t\t\t\t\t\t// SAFETY: selected definition and parsed input are paired by the kernel.\n\t\t\t\t\t\tconst preparation = await definition.prepare?.(\n\t\t\t\t\t\t\texecution.context as never,\n\t\t\t\t\t\t\texecution.command as never,\n\t\t\t\t\t\t)\n\t\t\t\t\t\tif (preparation?.kind !== 'execute') return preparation\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tkind: 'execute' as const,\n\t\t\t\t\t\t\tcomplete: preparation.complete\n\t\t\t\t\t\t\t\t? async (result: CommandResult<Operations, Key>) => {\n\t\t\t\t\t\t\t\t\t\t// SAFETY: completion belongs to this operation's validated final result.\n\t\t\t\t\t\t\t\t\t\tawait preparation.complete!(result as never)\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t: undefined,\n\t\t\t\t\t\t}\n\t\t\t\t\t},\n\t\t\t\t\tparseReplay: (value) => {\n\t\t\t\t\t\tif (!definition.replayResult) return execution.parseResult(value)\n\t\t\t\t\t\t// SAFETY: selected replay schema validates this operation's stored output.\n\t\t\t\t\t\treturn parseCommandSchema(definition.replayResult, value) as CommandResult<\n\t\t\t\t\t\t\tOperations,\n\t\t\t\t\t\t\tKey\n\t\t\t\t\t\t>\n\t\t\t\t\t},\n\t\t\t\t\tdecodeReplay: async (value) => {\n\t\t\t\t\t\tif (!definition.replayResult) {\n\t\t\t\t\t\t\treturn execution.decodeResult\n\t\t\t\t\t\t\t\t? execution.decodeResult(value)\n\t\t\t\t\t\t\t\t: execution.parseResult(value)\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst replay = definition.replayResult\n\t\t\t\t\t\t// SAFETY: selected replay decoder owns the final output representation.\n\t\t\t\t\t\treturn (await decodeCommandSchema(replay, value)) as CommandResult<Operations, Key>\n\t\t\t\t\t},\n\t\t\t\t\tmiddleware: [...(this.#defaults.middleware ?? []), ...(definition.middleware ?? [])].map(\n\t\t\t\t\t\t(layer) => async (input) => {\n\t\t\t\t\t\t\t// SAFETY: selected definition owns this heterogeneous middleware's pre-validation output.\n\t\t\t\t\t\t\treturn layer({\n\t\t\t\t\t\t\t\t...input,\n\t\t\t\t\t\t\t\tdefinition,\n\t\t\t\t\t\t\t\t// SAFETY: selected command schema owns this heterogeneous storage value.\n\t\t\t\t\t\t\t\tcommand: input.command as never,\n\t\t\t\t\t\t\t\t// SAFETY: only heterogeneous storage erases the selected middleware context.\n\t\t\t\t\t\t\t\tcontext: input.context as never,\n\t\t\t\t\t\t\t\t// SAFETY: selected operation pairs downstream output with its final schema.\n\t\t\t\t\t\t\t\tnext: input.next as (options?: { context?: object }) => Promise<never>,\n\t\t\t\t\t\t\t}) as Promise<CommandHandlerResult<Operations, Key>>\n\t\t\t\t\t\t},\n\t\t\t\t\t),\n\t\t\t\t\tdefaultGuard: async (context) => {\n\t\t\t\t\t\t// SAFETY: default guards consume the downstream middleware context.\n\t\t\t\t\t\tawait this.#defaults.guard?.(context as never)\n\t\t\t\t\t},\n\t\t\t\t\tguard: async (context) => {\n\t\t\t\t\t\t// SAFETY: selected guard consumes its parsed input and enriched context.\n\t\t\t\t\t\tawait definition.guard?.(context as never, execution.command as never)\n\t\t\t\t\t},\n\t\t\t\t\trun: (context) => execution.runUnparsed(context),\n\t\t\t\t\tparseResult: execution.parseResult,\n\t\t\t\t\tdecodeResult: execution.decodeResult,\n\t\t\t\t\taudit: async (result) => {\n\t\t\t\t\t\t// SAFETY: audit receives this selected parsed command/result and original context.\n\t\t\t\t\t\treturn definition.audit(\n\t\t\t\t\t\t\t{ command: execution.command, result } as never,\n\t\t\t\t\t\t\texecution.context as never,\n\t\t\t\t\t\t)\n\t\t\t\t\t},\n\t\t\t\t\taggregates: definition.aggregates,\n\t\t\t\t\twriteAudit: async (entry) => {\n\t\t\t\t\t\t// SAFETY: host supplied writer for this invocation's original context.\n\t\t\t\t\t\treturn this.#writeAudit(execution.context as never, entry)\n\t\t\t\t\t},\n\t\t\t\t}),\n\t\t)\n\t}\n}\n\n/** @deprecated Use the registry returned by createEffectFoundation(...).Command from cvx-kit/effect. */\nexport type ApplicationCommand<Context, Operations extends AuditedRegistry> = BoundCommand<\n\tContext,\n\tOperations\n>\n\n/**\n * The constructor shape a Foundation instance exposes as `Command`.\n * Exported as a TYPE ONLY so factories (e.g. cvx-kit/crud) can accept the\n * destructured facade class as input without importing any runtime kernel.\n * @deprecated Use createEffectFoundation from cvx-kit/effect and declare handlers inside command({...}).\n */\nexport type CommandConstructor = {\n\t/** @deprecated Use createEffectFoundation(...).Command({ context, operations }) from cvx-kit/effect. */\n\tnew <Context, const Operations extends AuditedRegistry>(\n\t\toperations: Operations & {\n\t\t\treadonly [Key in keyof Operations]: OperationHostContext<Context>\n\t\t},\n\t\tdefaults?: CommandDefaults,\n\t): BoundCommand<Context, Operations>\n\toperation: (typeof BoundCommand)['operation']\n\twithContext: (typeof BoundCommand)['withContext']\n\tmiddleware: (typeof BoundCommand)['middleware']\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<Component extends FoundationComponentApi = FoundationComponentApi> {\n\treadonly status: Component['functions']['status']\n\t/** @deprecated Use createEffectFoundation(...).Command from cvx-kit/effect. */\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\tclass HostCommand<Context, const Operations extends AuditedRegistry> extends BoundCommand<\n\t\t\tContext,\n\t\t\tOperations\n\t\t> {\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\tthis.Command = HostCommand\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 { CommandPreparation, TypedOperation } from './operation'\nexport type {\n\tCommandArgument,\n\tCommandExecution,\n\tCommandHandlerResult,\n\tCommandInput,\n\tCommandRegistry,\n\tCommandResult,\n\tSchemaOutput,\n\tParseable,\n} from './modules/command/command'\nexport type {\n\tCommandObservation,\n\tObservabilityOptions,\n} from './modules/observability/observability'\nexport type { AnyQueryMiddleware, QueryExecution, QueryMiddleware } from './modules/query/query'\nexport type { Result, ResultBoundary, TransactionMetricsContext } from './result'\n\n// The component definition is deliberately NOT re-exported here: Convex's\n// CLI only discovers a component whose resolved file is convex.config.js,\n// so hosts must mount via the dedicated subpath:\n//   import foundation from 'cvx-kit/components/foundation/convex.config'\n"],"mappings":"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"}

package/dist/modules/effect/api-runtime.d.mts

@@ -7,9 +7,18 @@ type EffectApiErrorContract = Pick<ErrorContract<ErrorDefinitions>, 'project'>;
 type EffectApiHandlerValue<Value> = Value | PromiseLike<Value> | Effect.Effect<Value, unknown, unknown>;
 type EffectApiServices = Context.Context<never> | PromiseLike<Context.Context<never>> | Effect.Effect<Context.Context<never>, unknown, Scope.Scope>;
 type ProvidedServices<Provider> = EffectValue<Provider> extends Context.Context<infer Services> ? Services : never;
-type EffectApiOptions<Ctx, Provider extends EffectApiServices> = {
+type EffectApiContext = EffectApiHandlerValue<Record<string, unknown>>;
+type KeysOfUnion<Value> = Value extends object ? keyof Value : never;
+type CheckedContext<Ctx, Added> = Extract<KeysOfUnion<EffectValue<Added>>, keyof Ctx> extends never ? unknown : never;
+type EffectApiOptions<Ctx, Provider extends EffectApiServices, Added = {}> = ([ProvidedServices<Provider>] extends [never] ? {
+  services?: (ctx: Ctx) => Provider;
+} : {
   services: (ctx: Ctx) => Provider;
-} & ({
+}) & ([KeysOfUnion<EffectValue<Added>>] extends [never] ? {
+  context?: (ctx: Ctx) => Added & CheckedContext<Ctx, Added>;
+} : {
+  context: (ctx: Ctx) => Added & CheckedContext<Ctx, Added>;
+}) & ({
   errors: EffectApiErrorContract;
   mapError?: never;
 } | {
@@ -19,10 +28,11 @@ type EffectApiOptions<Ctx, Provider extends EffectApiServices> = {
 type CheckedApiRequirements<Returned, Provider> = [Exclude<CallbackRequirements<NoInfer<Returned>>, ProvidedServices<Provider> | Scope.Scope>] extends [never] ? unknown : never;
 /** Internal erasure is limited to the registration boundary; public adapters check A/E/R. */
 declare function wrapEffectBuilder(builder: Function, options: {
-  services: Function;
+  services?: Function;
+  context?: Function;
   mapError?: EffectApiErrorProjection;
   errors?: EffectApiErrorContract;
 }): Function;
 //#endregion
-export { CheckedApiRequirements, EffectApiErrorContract, EffectApiErrorProjection, EffectApiHandlerValue, EffectApiOptions, EffectApiServices, ProvidedServices, wrapEffectBuilder };
+export { CheckedApiRequirements, CheckedContext, EffectApiContext, EffectApiErrorContract, EffectApiErrorProjection, EffectApiHandlerValue, EffectApiOptions, EffectApiServices, ProvidedServices, wrapEffectBuilder };
 //# sourceMappingURL=api-runtime.d.mts.map

package/dist/modules/effect/api-runtime.mjs

@@ -1,2 +1,2 @@
-import{normalizeEffect as e}from"./normalize.mjs";import{projectErrorCause as t}from"./errors.mjs";import{ConvexError as n}from"convex/values";import{Cause as r,Effect as i,Exit as a}from"effect";function o(o,s){return c=>{let l=typeof c==`function`?c:c.handler,u=async(o,...c)=>{let u=e(()=>s.services(o)).pipe(i.flatMap(t=>e(()=>l(o,...c)).pipe(i.provideContext(t)))),d=await i.runPromiseExit(i.scoped(u));if(a.isSuccess(d))return d.value;if(s.errors)throw new n(t(s.errors,d.cause));let f=d.cause.reasons.length===1?d.cause.reasons[0]:void 0;throw f&&r.isFailReason(f)?s.mapError?s.mapError(f.error):f.error:f&&r.isDieReason(f)?f.defect:Error(`Effect API execution failed`,{cause:d.cause})};return o(typeof c==`function`?u:{...c,handler:u})}}export{o as wrapEffectBuilder};
+import{normalizeEffect as e}from"./normalize.mjs";import{projectErrorCause as t}from"./errors.mjs";import{ConvexError as n}from"convex/values";import{Cause as r,Context as i,Effect as a,Exit as o}from"effect";function s(s,c){return l=>{let u=typeof l==`function`?l:l.handler,d=async(s,...l)=>{let d=e(()=>c.services?c.services(s):i.empty()).pipe(a.flatMap(t=>e(()=>c.context?c.context(s):{}).pipe(a.flatMap(e=>a.sync(()=>{if(typeof e!=`object`||!e)throw Error(`Effect API context must be an object`);let t=Object.getPrototypeOf(e);if(t!==Object.prototype&&t!==null)throw Error(`Effect API context additions must be a plain record`);let n=s;for(let t of Reflect.ownKeys(e))if(t in n)throw Error(`Effect API context cannot replace ${String(t)}`);return c.context?Object.create(Object.getPrototypeOf(n),{...Object.getOwnPropertyDescriptors(n),...Object.getOwnPropertyDescriptors(e)}):s})),a.flatMap(t=>e(()=>u(t,...l))),a.provideContext(t)))),f=await a.runPromiseExit(a.scoped(d));if(o.isSuccess(f))return f.value;if(c.errors)throw new n(t(c.errors,f.cause));let p=f.cause.reasons.length===1?f.cause.reasons[0]:void 0;throw p&&r.isFailReason(p)?c.mapError?c.mapError(p.error):p.error:p&&r.isDieReason(p)?p.defect:Error(`Effect API execution failed`,{cause:f.cause})};return s(typeof l==`function`?d:{...l,handler:d})}}export{s as wrapEffectBuilder};
 //# sourceMappingURL=api-runtime.mjs.map

package/dist/modules/effect/api-runtime.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"api-runtime.mjs","names":[],"sources":["../../../src/modules/effect/api-runtime.ts"],"sourcesContent":["import { Cause, Effect, Exit } from 'effect'\nimport type { Context, Scope } from 'effect'\nimport { ConvexError, type Value } from 'convex/values'\nimport type { ErrorContract, ErrorDefinitions } from '../contracts/errors'\nimport { projectErrorCause } from './errors'\nimport { normalizeEffect } from './normalize'\nimport type { CallbackRequirements, EffectValue } from './operation'\n\n// oxlint-disable-next-line anti-slop/no-unknown-parameters, anti-slop/no-unknown-returns -- Projection receives any expected failure and its result is always thrown, never returned as public data.\nexport type EffectApiErrorProjection = (error: unknown) => unknown\nexport type EffectApiErrorContract = Pick<ErrorContract<ErrorDefinitions>, 'project'>\n\nexport type EffectApiHandlerValue<Value> =\n\t| Value\n\t| PromiseLike<Value>\n\t| Effect.Effect<Value, unknown, unknown>\n\nexport type EffectApiServices =\n\t| Context.Context<never>\n\t| PromiseLike<Context.Context<never>>\n\t| Effect.Effect<Context.Context<never>, unknown, Scope.Scope>\nexport type ProvidedServices<Provider> =\n\tEffectValue<Provider> extends Context.Context<infer Services> ? Services : never\nexport type EffectApiOptions<Ctx, Provider extends EffectApiServices> = {\n\tservices: (ctx: Ctx) => Provider\n} & (\n\t| { errors: EffectApiErrorContract; mapError?: never }\n\t| { errors?: never; mapError?: EffectApiErrorProjection }\n)\nexport type CheckedApiRequirements<Returned, Provider> = [\n\tExclude<CallbackRequirements<NoInfer<Returned>>, ProvidedServices<Provider> | Scope.Scope>,\n] extends [never]\n\t? unknown\n\t: never\n\n/** Internal erasure is limited to the registration boundary; public adapters check A/E/R. */\nexport function wrapEffectBuilder(\n\tbuilder: Function,\n\toptions: {\n\t\tservices: Function\n\t\tmapError?: EffectApiErrorProjection\n\t\terrors?: EffectApiErrorContract\n\t},\n): Function {\n\treturn (definition: Function | { handler: Function }) => {\n\t\t// oxlint-disable-next-line anti-slop/no-runtime-typeof -- Native registration explicitly accepts a callable or an object with a handler.\n\t\tconst original = typeof definition === 'function' ? definition : definition.handler\n\t\t// oxlint-disable-next-line anti-slop/no-unknown-parameters -- Private erased callback receives the context already constructed by the checked native/custom builder.\n\t\tconst handler = async (ctx: unknown, ...args: unknown[]) => {\n\t\t\tconst program = normalizeEffect(() => options.services(ctx)).pipe(\n\t\t\t\tEffect.flatMap((services) =>\n\t\t\t\t\tnormalizeEffect(() => original(ctx, ...args)).pipe(Effect.provideContext(services)),\n\t\t\t\t),\n\t\t\t)\n\t\t\t// SAFETY: checked public signatures prohibit unprovided handler requirements and\n\t\t\t// permit only Scope in providers; services are constructed within this same scope.\n\t\t\tconst exit = await Effect.runPromiseExit(\n\t\t\t\tEffect.scoped(program) as Effect.Effect<unknown, unknown>,\n\t\t\t)\n\t\t\tif (Exit.isSuccess(exit)) return exit.value\n\t\t\tif (options.errors) {\n\t\t\t\t// SAFETY: declared projection copies validated JSON-safe fields; all other Causes have a fixed safe envelope.\n\t\t\t\tthrow new ConvexError(projectErrorCause(options.errors, exit.cause) as Value)\n\t\t\t}\n\t\t\tconst reason = exit.cause.reasons.length === 1 ? exit.cause.reasons[0] : undefined\n\t\t\tif (reason && Cause.isFailReason(reason)) {\n\t\t\t\tthrow options.mapError ? options.mapError(reason.error) : reason.error\n\t\t\t}\n\t\t\tif (reason && Cause.isDieReason(reason)) throw reason.defect\n\t\t\tthrow new Error('Effect API execution failed', { cause: exit.cause })\n\t\t}\n\t\t// oxlint-disable-next-line anti-slop/no-runtime-typeof -- Preserve the original native callable or object registration form.\n\t\treturn builder(typeof definition === 'function' ? handler : { ...definition, handler })\n\t}\n}\n"],"mappings":"oMAoCA,SAAgB,EACf,EACA,EAKW,CACX,MAAQ,IAAiD,CAExD,IAAM,EAAW,OAAO,GAAe,WAAa,EAAa,EAAW,QAEtE,EAAU,MAAO,EAAc,GAAG,IAAoB,CAC3D,IAAM,EAAU,MAAsB,EAAQ,SAAS,CAAG,CAAC,CAAC,CAAC,KAC5D,EAAO,QAAS,GACf,MAAsB,EAAS,EAAK,GAAG,CAAI,CAAC,CAAC,CAAC,KAAK,EAAO,eAAe,CAAQ,CAAC,CACnF,CACD,EAGM,EAAO,MAAM,EAAO,eACzB,EAAO,OAAO,CAAO,CACtB,EACA,GAAI,EAAK,UAAU,CAAI,EAAG,OAAO,EAAK,MACtC,GAAI,EAAQ,OAEX,MAAM,IAAI,EAAY,EAAkB,EAAQ,OAAQ,EAAK,KAAK,CAAU,EAE7E,IAAM,EAAS,EAAK,MAAM,QAAQ,SAAW,EAAI,EAAK,MAAM,QAAQ,GAAK,IAAA,GAKzE,MAJI,GAAU,EAAM,aAAa,CAAM,EAChC,EAAQ,SAAW,EAAQ,SAAS,EAAO,KAAK,EAAI,EAAO,MAE9D,GAAU,EAAM,YAAY,CAAM,EAAS,EAAO,OAC5C,MAAM,8BAA+B,CAAE,MAAO,EAAK,KAAM,CAAC,CACrE,EAEA,OAAO,EAAQ,OAAO,GAAe,WAAa,EAAU,CAAE,GAAG,EAAY,SAAQ,CAAC,CACvF,CACD"}
+{"version":3,"file":"api-runtime.mjs","names":[],"sources":["../../../src/modules/effect/api-runtime.ts"],"sourcesContent":["import { Cause, Context, Effect, Exit } from 'effect'\nimport type { Scope } from 'effect'\nimport { ConvexError, type Value } from 'convex/values'\nimport type { ErrorContract, ErrorDefinitions } from '../contracts/errors'\nimport { projectErrorCause } from './errors'\nimport { normalizeEffect } from './normalize'\nimport type { CallbackRequirements, EffectValue } from './operation'\n\n// oxlint-disable-next-line anti-slop/no-unknown-parameters, anti-slop/no-unknown-returns -- Projection receives any expected failure and its result is always thrown, never returned as public data.\nexport type EffectApiErrorProjection = (error: unknown) => unknown\nexport type EffectApiErrorContract = Pick<ErrorContract<ErrorDefinitions>, 'project'>\n\nexport type EffectApiHandlerValue<Value> =\n\t| Value\n\t| PromiseLike<Value>\n\t| Effect.Effect<Value, unknown, unknown>\n\nexport type EffectApiServices =\n\t| Context.Context<never>\n\t| PromiseLike<Context.Context<never>>\n\t| Effect.Effect<Context.Context<never>, unknown, Scope.Scope>\nexport type ProvidedServices<Provider> =\n\tEffectValue<Provider> extends Context.Context<infer Services> ? Services : never\n// oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- This inference constraint requires record-shaped additions; each adapter preserves its concrete inferred fields and runtime checks the record boundary.\nexport type EffectApiContext = EffectApiHandlerValue<Record<string, unknown>>\ntype KeysOfUnion<Value> = Value extends object ? keyof Value : never\nexport type CheckedContext<Ctx, Added> =\n\tExtract<KeysOfUnion<EffectValue<Added>>, keyof Ctx> extends never ? unknown : never\nexport type EffectApiOptions<Ctx, Provider extends EffectApiServices, Added = {}> = (\n\t[ProvidedServices<Provider>] extends [never]\n\t\t? { services?: (ctx: Ctx) => Provider }\n\t\t: { services: (ctx: Ctx) => Provider }\n) & (\n\t[KeysOfUnion<EffectValue<Added>>] extends [never]\n\t\t? { context?: (ctx: Ctx) => Added & CheckedContext<Ctx, Added> }\n\t\t: { context: (ctx: Ctx) => Added & CheckedContext<Ctx, Added> }\n) & (\n\t| { errors: EffectApiErrorContract; mapError?: never }\n\t| { errors?: never; mapError?: EffectApiErrorProjection }\n)\nexport type CheckedApiRequirements<Returned, Provider> = [\n\tExclude<CallbackRequirements<NoInfer<Returned>>, ProvidedServices<Provider> | Scope.Scope>,\n] extends [never]\n\t? unknown\n\t: never\n\n/** Internal erasure is limited to the registration boundary; public adapters check A/E/R. */\nexport function wrapEffectBuilder(\n\tbuilder: Function,\n\toptions: {\n\t\tservices?: Function\n\t\tcontext?: Function\n\t\tmapError?: EffectApiErrorProjection\n\t\terrors?: EffectApiErrorContract\n\t},\n): Function {\n\treturn (definition: Function | { handler: Function }) => {\n\t\t// oxlint-disable-next-line anti-slop/no-runtime-typeof -- Native registration explicitly accepts a callable or an object with a handler.\n\t\tconst original = typeof definition === 'function' ? definition : definition.handler\n\t\t// oxlint-disable-next-line anti-slop/no-unknown-parameters -- Private erased callback receives the context already constructed by the checked native/custom builder.\n\t\tconst handler = async (ctx: unknown, ...args: unknown[]) => {\n\t\t\tconst program = normalizeEffect(() =>\n\t\t\t\toptions.services ? options.services(ctx) : Context.empty(),\n\t\t\t).pipe(\n\t\t\t\tEffect.flatMap((services) =>\n\t\t\t\t\tnormalizeEffect(() => (options.context ? options.context(ctx) : {})).pipe(\n\t\t\t\t\t\tEffect.flatMap((added) =>\n\t\t\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\t\t\t// oxlint-disable-next-line anti-slop/no-runtime-typeof -- Validate erased context additions before enumerating or merging their fields.\n\t\t\t\t\t\t\t\tif (added === null || typeof added !== 'object')\n\t\t\t\t\t\t\t\t\tthrow Error('Effect API context must be an object')\n\t\t\t\t\t\t\t\tconst additionsPrototype = Object.getPrototypeOf(added)\n\t\t\t\t\t\t\t\tif (additionsPrototype !== Object.prototype && additionsPrototype !== null)\n\t\t\t\t\t\t\t\t\tthrow Error('Effect API context additions must be a plain record')\n\t\t\t\t\t\t\t\t// SAFETY: native and custom builders construct an object context before invoking this private handler.\n\t\t\t\t\t\t\t\tconst originalContext = ctx as object\n\t\t\t\t\t\t\t\tfor (const key of Reflect.ownKeys(added)) {\n\t\t\t\t\t\t\t\t\tif (key in originalContext)\n\t\t\t\t\t\t\t\t\t\tthrow Error(`Effect API context cannot replace ${String(key)}`)\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\treturn options.context\n\t\t\t\t\t\t\t\t\t? Object.create(Object.getPrototypeOf(originalContext), {\n\t\t\t\t\t\t\t\t\t\t\t...Object.getOwnPropertyDescriptors(originalContext),\n\t\t\t\t\t\t\t\t\t\t\t...Object.getOwnPropertyDescriptors(added),\n\t\t\t\t\t\t\t\t\t\t})\n\t\t\t\t\t\t\t\t\t: ctx\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t\t\tEffect.flatMap((context) => normalizeEffect(() => original(context, ...args))),\n\t\t\t\t\t\tEffect.provideContext(services),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t)\n\t\t\t// SAFETY: checked public signatures prohibit unprovided handler requirements and\n\t\t\t// permit only Scope in providers; services are constructed within this same scope.\n\t\t\tconst exit = await Effect.runPromiseExit(\n\t\t\t\tEffect.scoped(program) as Effect.Effect<unknown, unknown>,\n\t\t\t)\n\t\t\tif (Exit.isSuccess(exit)) return exit.value\n\t\t\tif (options.errors) {\n\t\t\t\t// SAFETY: declared projection copies validated JSON-safe fields; all other Causes have a fixed safe envelope.\n\t\t\t\tthrow new ConvexError(projectErrorCause(options.errors, exit.cause) as Value)\n\t\t\t}\n\t\t\tconst reason = exit.cause.reasons.length === 1 ? exit.cause.reasons[0] : undefined\n\t\t\tif (reason && Cause.isFailReason(reason)) {\n\t\t\t\tthrow options.mapError ? options.mapError(reason.error) : reason.error\n\t\t\t}\n\t\t\tif (reason && Cause.isDieReason(reason)) throw reason.defect\n\t\t\tthrow new Error('Effect API execution failed', { cause: exit.cause })\n\t\t}\n\t\t// oxlint-disable-next-line anti-slop/no-runtime-typeof -- Preserve the original native callable or object registration form.\n\t\treturn builder(typeof definition === 'function' ? handler : { ...definition, handler })\n\t}\n}\n"],"mappings":"iNA+CA,SAAgB,EACf,EACA,EAMW,CACX,MAAQ,IAAiD,CAExD,IAAM,EAAW,OAAO,GAAe,WAAa,EAAa,EAAW,QAEtE,EAAU,MAAO,EAAc,GAAG,IAAoB,CAC3D,IAAM,EAAU,MACf,EAAQ,SAAW,EAAQ,SAAS,CAAG,EAAI,EAAQ,MAAM,CAC1D,CAAC,CAAC,KACD,EAAO,QAAS,GACf,MAAuB,EAAQ,QAAU,EAAQ,QAAQ,CAAG,EAAI,CAAC,CAAE,CAAC,CAAC,KACpE,EAAO,QAAS,GACf,EAAO,SAAW,CAEjB,GAAsB,OAAO,GAAU,WAAnC,EACH,MAAM,MAAM,sCAAsC,EACnD,IAAM,EAAqB,OAAO,eAAe,CAAK,EACtD,GAAI,IAAuB,OAAO,WAAa,IAAuB,KACrE,MAAM,MAAM,qDAAqD,EAElE,IAAM,EAAkB,EACxB,IAAK,IAAM,KAAO,QAAQ,QAAQ,CAAK,EACtC,GAAI,KAAO,EACV,MAAM,MAAM,qCAAqC,OAAO,CAAG,GAAG,EAEhE,OAAO,EAAQ,QACZ,OAAO,OAAO,OAAO,eAAe,CAAe,EAAG,CACtD,GAAG,OAAO,0BAA0B,CAAe,EACnD,GAAG,OAAO,0BAA0B,CAAK,CAC1C,CAAC,EACA,CACJ,CAAC,CACF,EACA,EAAO,QAAS,GAAY,MAAsB,EAAS,EAAS,GAAG,CAAI,CAAC,CAAC,EAC7E,EAAO,eAAe,CAAQ,CAC/B,CACD,CACD,EAGM,EAAO,MAAM,EAAO,eACzB,EAAO,OAAO,CAAO,CACtB,EACA,GAAI,EAAK,UAAU,CAAI,EAAG,OAAO,EAAK,MACtC,GAAI,EAAQ,OAEX,MAAM,IAAI,EAAY,EAAkB,EAAQ,OAAQ,EAAK,KAAK,CAAU,EAE7E,IAAM,EAAS,EAAK,MAAM,QAAQ,SAAW,EAAI,EAAK,MAAM,QAAQ,GAAK,IAAA,GAKzE,MAJI,GAAU,EAAM,aAAa,CAAM,EAChC,EAAQ,SAAW,EAAQ,SAAS,EAAO,KAAK,EAAI,EAAO,MAE9D,GAAU,EAAM,YAAY,CAAM,EAAS,EAAO,OAC5C,MAAM,8BAA+B,CAAE,MAAO,EAAK,KAAM,CAAC,CACrE,EAEA,OAAO,EAAQ,OAAO,GAAe,WAAa,EAAU,CAAE,GAAG,EAAY,SAAQ,CAAC,CACvF,CACD"}

package/dist/modules/effect/api-zod.d.mts

@@ -1,5 +1,5 @@
 import { CallbackRequirements, EffectValue } from "./operation.mjs";
-import { EffectApiHandlerValue, EffectApiOptions, EffectApiServices, ProvidedServices } from "./api-runtime.mjs";
+import { EffectApiContext, EffectApiHandlerValue, EffectApiOptions, EffectApiServices, ProvidedServices } from "./api-runtime.mjs";
 import { CustomBuilder } from "convex-helpers/server/zod4";
 import { ArgsArrayToObject, DefaultFunctionArgs, FunctionVisibility } from "convex/server";
 import { ObjectType, PropertyValidators } from "convex/values";
@@ -20,16 +20,16 @@ type ResultInput<Validator extends ResultValidator> = [Validator] extends [zCore
 type ResultOutput<Validator extends ResultValidator, Returned> = [Validator] extends [void] ? EffectValue<Returned> : [Validator] extends [zCore.$ZodType] ? zCore.output<Validator> : [Validator] extends [Fields] ? zCore.output<zCore.$ZodObject<Validator, zCore.$strict>> : never;
 type CheckedRequirements<Returned, Services> = [Exclude<CallbackRequirements<NoInfer<Returned>>, Services | Scope.Scope>] extends [never] ? unknown : never;
 /** Retains the installed Zod custom builder's raw/parsed boundaries and customization options. */
-type EffectZodApiBuilder<Kind extends 'query' | 'mutation' | 'action', CustomArgs extends PropertyValidators, CustomCtx extends Record<string, unknown>, CustomMadeArgs extends Record<string, unknown>, InputCtx, Visibility extends FunctionVisibility, ExtraArgs extends Record<string, unknown>, Services> = {
+type EffectZodApiBuilder<Kind extends 'query' | 'mutation' | 'action', CustomArgs extends PropertyValidators, CustomCtx extends Record<string, unknown>, CustomMadeArgs extends Record<string, unknown>, InputCtx, Visibility extends FunctionVisibility, ExtraArgs extends Record<string, unknown>, Services, Added = {}, Initialized = {}> = {
   <Args extends ArgumentsValidator, Returns extends ResultValidator = void, Returned extends EffectApiHandlerValue<ResultInput<Returns> | (null extends ResultInput<Returns> ? undefined | void : never)> = EffectApiHandlerValue<ResultInput<Returns> | (null extends ResultInput<Returns> ? undefined | void : never)>>(definition: (({
     args?: Args;
     returns?: Returns;
     skipConvexValidation?: boolean;
-    handler: (ctx: Overwrite<InputCtx, CustomCtx>, ...args: HandlerArgs<Args, CustomMadeArgs>) => Returned;
-  } & Omit<ExtraArgs, 'args' | 'returns' | 'handler' | 'skipConvexValidation'>) | ((ctx: Overwrite<InputCtx, CustomCtx>, ...args: HandlerArgs<Args, CustomMadeArgs>) => Returned)) & CheckedRequirements<Returned, Services>): Registration<Kind, Visibility, RawArgs<Args, CustomArgs>, ResultOutput<Returns, Returned>>;
+    handler: (ctx: Overwrite<InputCtx, CustomCtx> & Added, ...args: HandlerArgs<Args, CustomMadeArgs>) => Returned;
+  } & Omit<ExtraArgs, 'args' | 'returns' | 'handler' | 'skipConvexValidation'>) | ((ctx: Overwrite<InputCtx, CustomCtx> & Added, ...args: HandlerArgs<Args, CustomMadeArgs>) => Returned)) & CheckedRequirements<Returned, Services> & CheckedRequirements<Initialized, Services>): Registration<Kind, Visibility, RawArgs<Args, CustomArgs>, ResultOutput<Returns, Returned>>;
 };
 /** Build request services after the original custom builder resolves its trusted context. */
-declare function effectZodApiBuilder<Kind extends 'query' | 'mutation' | 'action', CustomArgs extends PropertyValidators, CustomCtx extends Record<string, unknown>, CustomMadeArgs extends Record<string, unknown>, InputCtx, Visibility extends FunctionVisibility, ExtraArgs extends Record<string, unknown>, Provider extends EffectApiServices>(builder: CustomBuilder<Kind, CustomArgs, CustomCtx, CustomMadeArgs, InputCtx, Visibility, ExtraArgs>, options: EffectApiOptions<Overwrite<InputCtx, CustomCtx>, Provider>): EffectZodApiBuilder<Kind, CustomArgs, CustomCtx, CustomMadeArgs, InputCtx, Visibility, ExtraArgs, ProvidedServices<Provider>>;
+declare function effectZodApiBuilder<Kind extends 'query' | 'mutation' | 'action', CustomArgs extends PropertyValidators, CustomCtx extends Record<string, unknown>, CustomMadeArgs extends Record<string, unknown>, InputCtx, Visibility extends FunctionVisibility, ExtraArgs extends Record<string, unknown>, Provider extends EffectApiServices = import('effect').Context.Context<never>, Added extends EffectApiContext = {}>(builder: CustomBuilder<Kind, CustomArgs, CustomCtx, CustomMadeArgs, InputCtx, Visibility, ExtraArgs>, options: EffectApiOptions<Overwrite<InputCtx, CustomCtx>, Provider, Added>): EffectZodApiBuilder<Kind, CustomArgs, CustomCtx, CustomMadeArgs, InputCtx, Visibility, ExtraArgs, ProvidedServices<Provider>, EffectValue<Added>, Added>;
 //#endregion
 export { EffectZodApiBuilder, effectZodApiBuilder };
 //# sourceMappingURL=api-zod.d.mts.map

package/dist/modules/effect/api-zod.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"api-zod.mjs","names":[],"sources":["../../../src/modules/effect/api-zod.ts"],"sourcesContent":["import type { ArgsArrayToObject, DefaultFunctionArgs, FunctionVisibility } from 'convex/server'\nimport type { ObjectType, PropertyValidators } from 'convex/values'\nimport type { Registration } from 'convex-helpers/server/customFunctions'\nimport type { CustomBuilder } from 'convex-helpers/server/zod4'\nimport type { Scope } from 'effect'\nimport type * as zCore from 'zod/v4/core'\nimport {\n\twrapEffectBuilder,\n\ttype EffectApiOptions,\n\ttype ProvidedServices,\n\ttype EffectApiServices,\n\ttype EffectApiHandlerValue,\n} from './api-runtime'\nimport type { CallbackRequirements, EffectValue } from './operation'\n\ntype Fields = Record<string, zCore.$ZodType>\ntype ArgumentsValidator = Fields | zCore.$ZodObject<Fields> | void\ntype ResultValidator = zCore.$ZodType | Fields | void\ntype Expand<Value> = { [Key in keyof Value]: Value[Key] }\ntype Overwrite<Input, Custom> = Omit<Input, keyof Custom> & Custom\ntype ArgsInput<Validator extends ArgumentsValidator> = [Validator] extends [\n\tzCore.$ZodObject<Fields>,\n]\n\t? [zCore.input<Validator>]\n\t: Validator extends Record<string, never>\n\t\t? [Record<never, never>]\n\t\t: [Validator] extends [Fields]\n\t\t\t? [zCore.input<zCore.$ZodObject<Validator, zCore.$strict>>]\n\t\t\t: [DefaultFunctionArgs]\ntype ArgsOutput<Validator extends ArgumentsValidator> = [Validator] extends [\n\tzCore.$ZodObject<Fields>,\n]\n\t? [zCore.output<Validator>]\n\t: [Validator] extends [Fields]\n\t\t? [zCore.output<zCore.$ZodObject<Validator, zCore.$strict>>]\n\t\t: [DefaultFunctionArgs]\ntype HandlerArgs<Validator extends ArgumentsValidator, Made> =\n\tMade extends Record<string, never>\n\t\t? ArgsOutput<Validator>\n\t\t: [Expand<ArgsOutput<Validator>[0] & Made>]\ntype RawArgs<\n\tValidator extends ArgumentsValidator,\n\tCustom extends PropertyValidators,\n> = ArgsArrayToObject<\n\tCustom extends Record<string, never>\n\t\t? ArgsInput<Validator>\n\t\t: [Expand<ArgsInput<Validator>[0] & ObjectType<Custom>>]\n>\ntype ResultInput<Validator extends ResultValidator> = [Validator] extends [zCore.$ZodType]\n\t? zCore.input<Validator>\n\t: [Validator] extends [Fields]\n\t\t? zCore.input<zCore.$ZodObject<Validator>>\n\t\t: unknown\ntype ResultOutput<Validator extends ResultValidator, Returned> = [Validator] extends [void]\n\t? EffectValue<Returned>\n\t: [Validator] extends [zCore.$ZodType]\n\t\t? zCore.output<Validator>\n\t\t: [Validator] extends [Fields]\n\t\t\t? zCore.output<zCore.$ZodObject<Validator, zCore.$strict>>\n\t\t\t: never\ntype CheckedRequirements<Returned, Services> = [\n\tExclude<CallbackRequirements<NoInfer<Returned>>, Services | Scope.Scope>,\n] extends [never]\n\t? unknown\n\t: never\n\n/** Retains the installed Zod custom builder's raw/parsed boundaries and customization options. */\nexport type EffectZodApiBuilder<\n\tKind extends 'query' | 'mutation' | 'action',\n\tCustomArgs extends PropertyValidators,\n\tCustomCtx extends Record<string, unknown>,\n\tCustomMadeArgs extends Record<string, unknown>,\n\tInputCtx,\n\tVisibility extends FunctionVisibility,\n\tExtraArgs extends Record<string, unknown>,\n\tServices,\n> = {\n\t<\n\t\tArgs extends ArgumentsValidator,\n\t\tReturns extends ResultValidator = void,\n\t\tReturned extends EffectApiHandlerValue<\n\t\t\tResultInput<Returns> | (null extends ResultInput<Returns> ? undefined | void : never)\n\t\t> = EffectApiHandlerValue<\n\t\t\tResultInput<Returns> | (null extends ResultInput<Returns> ? undefined | void : never)\n\t\t>,\n\t>(\n\t\tdefinition: (\n\t\t\t| ({\n\t\t\t\t\targs?: Args\n\t\t\t\t\treturns?: Returns\n\t\t\t\t\tskipConvexValidation?: boolean\n\t\t\t\t\thandler: (\n\t\t\t\t\t\tctx: Overwrite<InputCtx, CustomCtx>,\n\t\t\t\t\t\t...args: HandlerArgs<Args, CustomMadeArgs>\n\t\t\t\t\t) => Returned\n\t\t\t  } & Omit<ExtraArgs, 'args' | 'returns' | 'handler' | 'skipConvexValidation'>)\n\t\t\t| ((\n\t\t\t\t\tctx: Overwrite<InputCtx, CustomCtx>,\n\t\t\t\t\t...args: HandlerArgs<Args, CustomMadeArgs>\n\t\t\t  ) => Returned)\n\t\t) &\n\t\t\tCheckedRequirements<Returned, Services>,\n\t): Registration<Kind, Visibility, RawArgs<Args, CustomArgs>, ResultOutput<Returns, Returned>>\n}\n\n/** Build request services after the original custom builder resolves its trusted context. */\nexport function effectZodApiBuilder<\n\tKind extends 'query' | 'mutation' | 'action',\n\tCustomArgs extends PropertyValidators,\n\tCustomCtx extends Record<string, unknown>,\n\tCustomMadeArgs extends Record<string, unknown>,\n\tInputCtx,\n\tVisibility extends FunctionVisibility,\n\tExtraArgs extends Record<string, unknown>,\n\tProvider extends EffectApiServices,\n>(\n\tbuilder: CustomBuilder<\n\t\tKind,\n\t\tCustomArgs,\n\t\tCustomCtx,\n\t\tCustomMadeArgs,\n\t\tInputCtx,\n\t\tVisibility,\n\t\tExtraArgs\n\t>,\n\toptions: EffectApiOptions<Overwrite<InputCtx, CustomCtx>, Provider>,\n): EffectZodApiBuilder<\n\tKind,\n\tCustomArgs,\n\tCustomCtx,\n\tCustomMadeArgs,\n\tInputCtx,\n\tVisibility,\n\tExtraArgs,\n\tProvidedServices<Provider>\n> {\n\t// SAFETY: Runtime substitution changes only the handler. The original builder retains validation,\n\t// customization, registration kind and visibility; the public call signature above checks Effects.\n\treturn wrapEffectBuilder(builder, options) as EffectZodApiBuilder<\n\t\tKind,\n\t\tCustomArgs,\n\t\tCustomCtx,\n\t\tCustomMadeArgs,\n\t\tInputCtx,\n\t\tVisibility,\n\t\tExtraArgs,\n\t\tProvidedServices<Provider>\n\t>\n}\n"],"mappings":"sDA0GA,SAAgB,EAUf,EASA,EAUC,CAGD,OAAO,EAAkB,EAAS,CAAO,CAU1C"}
+{"version":3,"file":"api-zod.mjs","names":[],"sources":["../../../src/modules/effect/api-zod.ts"],"sourcesContent":["import type { ArgsArrayToObject, DefaultFunctionArgs, FunctionVisibility } from 'convex/server'\nimport type { ObjectType, PropertyValidators } from 'convex/values'\nimport type { Registration } from 'convex-helpers/server/customFunctions'\nimport type { CustomBuilder } from 'convex-helpers/server/zod4'\nimport type { Scope } from 'effect'\nimport type * as zCore from 'zod/v4/core'\nimport {\n\twrapEffectBuilder,\n\ttype EffectApiOptions,\n\ttype ProvidedServices,\n\ttype EffectApiServices,\n\ttype EffectApiHandlerValue,\n\ttype EffectApiContext,\n} from './api-runtime'\nimport type { CallbackRequirements, EffectValue } from './operation'\n\ntype Fields = Record<string, zCore.$ZodType>\ntype ArgumentsValidator = Fields | zCore.$ZodObject<Fields> | void\ntype ResultValidator = zCore.$ZodType | Fields | void\ntype Expand<Value> = { [Key in keyof Value]: Value[Key] }\ntype Overwrite<Input, Custom> = Omit<Input, keyof Custom> & Custom\ntype ArgsInput<Validator extends ArgumentsValidator> = [Validator] extends [\n\tzCore.$ZodObject<Fields>,\n]\n\t? [zCore.input<Validator>]\n\t: Validator extends Record<string, never>\n\t\t? [Record<never, never>]\n\t\t: [Validator] extends [Fields]\n\t\t\t? [zCore.input<zCore.$ZodObject<Validator, zCore.$strict>>]\n\t\t\t: [DefaultFunctionArgs]\ntype ArgsOutput<Validator extends ArgumentsValidator> = [Validator] extends [\n\tzCore.$ZodObject<Fields>,\n]\n\t? [zCore.output<Validator>]\n\t: [Validator] extends [Fields]\n\t\t? [zCore.output<zCore.$ZodObject<Validator, zCore.$strict>>]\n\t\t: [DefaultFunctionArgs]\ntype HandlerArgs<Validator extends ArgumentsValidator, Made> =\n\tMade extends Record<string, never>\n\t\t? ArgsOutput<Validator>\n\t\t: [Expand<ArgsOutput<Validator>[0] & Made>]\ntype RawArgs<\n\tValidator extends ArgumentsValidator,\n\tCustom extends PropertyValidators,\n> = ArgsArrayToObject<\n\tCustom extends Record<string, never>\n\t\t? ArgsInput<Validator>\n\t\t: [Expand<ArgsInput<Validator>[0] & ObjectType<Custom>>]\n>\ntype ResultInput<Validator extends ResultValidator> = [Validator] extends [zCore.$ZodType]\n\t? zCore.input<Validator>\n\t: [Validator] extends [Fields]\n\t\t? zCore.input<zCore.$ZodObject<Validator>>\n\t\t: unknown\ntype ResultOutput<Validator extends ResultValidator, Returned> = [Validator] extends [void]\n\t? EffectValue<Returned>\n\t: [Validator] extends [zCore.$ZodType]\n\t\t? zCore.output<Validator>\n\t\t: [Validator] extends [Fields]\n\t\t\t? zCore.output<zCore.$ZodObject<Validator, zCore.$strict>>\n\t\t\t: never\ntype CheckedRequirements<Returned, Services> = [\n\tExclude<CallbackRequirements<NoInfer<Returned>>, Services | Scope.Scope>,\n] extends [never]\n\t? unknown\n\t: never\n\n/** Retains the installed Zod custom builder's raw/parsed boundaries and customization options. */\nexport type EffectZodApiBuilder<\n\tKind extends 'query' | 'mutation' | 'action',\n\tCustomArgs extends PropertyValidators,\n\tCustomCtx extends Record<string, unknown>,\n\tCustomMadeArgs extends Record<string, unknown>,\n\tInputCtx,\n\tVisibility extends FunctionVisibility,\n\tExtraArgs extends Record<string, unknown>,\n\tServices,\n\tAdded = {},\n\tInitialized = {},\n> = {\n\t<\n\t\tArgs extends ArgumentsValidator,\n\t\tReturns extends ResultValidator = void,\n\t\tReturned extends EffectApiHandlerValue<\n\t\t\tResultInput<Returns> | (null extends ResultInput<Returns> ? undefined | void : never)\n\t\t> = EffectApiHandlerValue<\n\t\t\tResultInput<Returns> | (null extends ResultInput<Returns> ? undefined | void : never)\n\t\t>,\n\t>(\n\t\tdefinition: (\n\t\t\t| ({\n\t\t\t\t\targs?: Args\n\t\t\t\t\treturns?: Returns\n\t\t\t\t\tskipConvexValidation?: boolean\n\t\t\t\t\thandler: (\n\t\t\t\t\t\tctx: Overwrite<InputCtx, CustomCtx> & Added,\n\t\t\t\t\t\t...args: HandlerArgs<Args, CustomMadeArgs>\n\t\t\t\t\t) => Returned\n\t\t\t  } & Omit<ExtraArgs, 'args' | 'returns' | 'handler' | 'skipConvexValidation'>)\n\t\t\t| ((\n\t\t\t\t\tctx: Overwrite<InputCtx, CustomCtx> & Added,\n\t\t\t\t\t...args: HandlerArgs<Args, CustomMadeArgs>\n\t\t\t  ) => Returned)\n\t\t) &\n\t\t\tCheckedRequirements<Returned, Services> &\n\t\t\tCheckedRequirements<Initialized, Services>,\n\t): Registration<Kind, Visibility, RawArgs<Args, CustomArgs>, ResultOutput<Returns, Returned>>\n}\n\n/** Build request services after the original custom builder resolves its trusted context. */\nexport function effectZodApiBuilder<\n\tKind extends 'query' | 'mutation' | 'action',\n\tCustomArgs extends PropertyValidators,\n\tCustomCtx extends Record<string, unknown>,\n\tCustomMadeArgs extends Record<string, unknown>,\n\tInputCtx,\n\tVisibility extends FunctionVisibility,\n\tExtraArgs extends Record<string, unknown>,\n\tProvider extends EffectApiServices = import('effect').Context.Context<never>,\n\tAdded extends EffectApiContext = {},\n>(\n\tbuilder: CustomBuilder<\n\t\tKind,\n\t\tCustomArgs,\n\t\tCustomCtx,\n\t\tCustomMadeArgs,\n\t\tInputCtx,\n\t\tVisibility,\n\t\tExtraArgs\n\t>,\n\toptions: EffectApiOptions<Overwrite<InputCtx, CustomCtx>, Provider, Added>,\n): EffectZodApiBuilder<\n\tKind,\n\tCustomArgs,\n\tCustomCtx,\n\tCustomMadeArgs,\n\tInputCtx,\n\tVisibility,\n\tExtraArgs,\n\tProvidedServices<Provider>,\n\tEffectValue<Added>,\n\tAdded\n> {\n\t// SAFETY: Runtime substitution changes only the handler. The original builder retains validation,\n\t// customization, registration kind and visibility; the public call signature above checks Effects.\n\treturn wrapEffectBuilder(builder, options) as EffectZodApiBuilder<\n\t\tKind,\n\t\tCustomArgs,\n\t\tCustomCtx,\n\t\tCustomMadeArgs,\n\t\tInputCtx,\n\t\tVisibility,\n\t\tExtraArgs,\n\t\tProvidedServices<Provider>,\n\t\tEffectValue<Added>,\n\t\tAdded\n\t>\n}\n"],"mappings":"sDA8GA,SAAgB,EAWf,EASA,EAYC,CAGD,OAAO,EAAkB,EAAS,CAAO,CAY1C"}

package/dist/modules/effect/api.d.mts

@@ -1,21 +1,21 @@
 import { EffectValue } from "./operation.mjs";
-import { CheckedApiRequirements, EffectApiHandlerValue, EffectApiOptions, EffectApiServices } from "./api-runtime.mjs";
+import { CheckedApiRequirements, EffectApiContext, EffectApiHandlerValue, EffectApiOptions, EffectApiServices } from "./api-runtime.mjs";
 import { ActionBuilder, ArgsArrayForOptionalValidator, ArgsArrayToObject, DefaultArgsForOptionalValidator, FunctionVisibility, GenericActionCtx, GenericDataModel, GenericMutationCtx, GenericQueryCtx, MutationBuilder, QueryBuilder, RegisteredAction, RegisteredMutation, RegisteredQuery, ReturnValueForOptionalValidator } from "convex/server";
 import { PropertyValidators, Validator } from "convex/values";
 //#region src/modules/effect/api.d.ts
 type ApiValidator = PropertyValidators | Validator<unknown, 'required', string> | void;
 type ApiOutput<Returns extends ApiValidator> = [Returns] extends [void] ? unknown : ReturnValueForOptionalValidator<Returns>;
-type EffectApiBuilder<Ctx, Visibility extends FunctionVisibility, Kind extends 'query' | 'mutation' | 'action', Provider> = {
+type EffectApiBuilder<Ctx, Visibility extends FunctionVisibility, Kind extends 'query' | 'mutation' | 'action', Provider, Initialized = {}> = {
   <Args extends ApiValidator, Returns extends ApiValidator = void, Returned extends EffectApiHandlerValue<ApiOutput<Returns>> = EffectApiHandlerValue<ApiOutput<Returns>>, OneOrZeroArgs extends ArgsArrayForOptionalValidator<Args> = DefaultArgsForOptionalValidator<Args>>(definition: ({
     args?: Args;
     returns?: Returns;
     handler: (ctx: Ctx, ...args: OneOrZeroArgs) => Returned;
-  } | ((ctx: Ctx, ...args: OneOrZeroArgs) => Returned)) & CheckedApiRequirements<Returned, Provider>): Kind extends 'query' ? RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, Promise<EffectValue<Returned>>> : Kind extends 'mutation' ? RegisteredMutation<Visibility, ArgsArrayToObject<OneOrZeroArgs>, Promise<EffectValue<Returned>>> : RegisteredAction<Visibility, ArgsArrayToObject<OneOrZeroArgs>, Promise<EffectValue<Returned>>>;
+  } | ((ctx: Ctx, ...args: OneOrZeroArgs) => Returned)) & CheckedApiRequirements<Returned, Provider> & CheckedApiRequirements<Initialized, Provider>): Kind extends 'query' ? RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, Promise<EffectValue<Returned>>> : Kind extends 'mutation' ? RegisteredMutation<Visibility, ArgsArrayToObject<OneOrZeroArgs>, Promise<EffectValue<Returned>>> : RegisteredAction<Visibility, ArgsArrayToObject<OneOrZeroArgs>, Promise<EffectValue<Returned>>>;
 };
 /** Provision request services after the supplied builder has constructed its trusted context. */
-declare function effectApiBuilder<DM extends GenericDataModel, V extends FunctionVisibility, Provider extends EffectApiServices>(builder: QueryBuilder<DM, V>, options: EffectApiOptions<GenericQueryCtx<DM>, Provider>): EffectApiBuilder<GenericQueryCtx<DM>, V, 'query', Provider>;
-declare function effectApiBuilder<DM extends GenericDataModel, V extends FunctionVisibility, Provider extends EffectApiServices>(builder: MutationBuilder<DM, V>, options: EffectApiOptions<GenericMutationCtx<DM>, Provider>): EffectApiBuilder<GenericMutationCtx<DM>, V, 'mutation', Provider>;
-declare function effectApiBuilder<DM extends GenericDataModel, V extends FunctionVisibility, Provider extends EffectApiServices>(builder: ActionBuilder<DM, V>, options: EffectApiOptions<GenericActionCtx<DM>, Provider>): EffectApiBuilder<GenericActionCtx<DM>, V, 'action', Provider>;
+declare function effectApiBuilder<DM extends GenericDataModel, V extends FunctionVisibility, Provider extends EffectApiServices = import('effect').Context.Context<never>, Added extends EffectApiContext = {}>(builder: QueryBuilder<DM, V>, options: EffectApiOptions<GenericQueryCtx<DM>, Provider, Added>): EffectApiBuilder<GenericQueryCtx<DM> & EffectValue<Added>, V, 'query', Provider, Added>;
+declare function effectApiBuilder<DM extends GenericDataModel, V extends FunctionVisibility, Provider extends EffectApiServices = import('effect').Context.Context<never>, Added extends EffectApiContext = {}>(builder: MutationBuilder<DM, V>, options: EffectApiOptions<GenericMutationCtx<DM>, Provider, Added>): EffectApiBuilder<GenericMutationCtx<DM> & EffectValue<Added>, V, 'mutation', Provider, Added>;
+declare function effectApiBuilder<DM extends GenericDataModel, V extends FunctionVisibility, Provider extends EffectApiServices = import('effect').Context.Context<never>, Added extends EffectApiContext = {}>(builder: ActionBuilder<DM, V>, options: EffectApiOptions<GenericActionCtx<DM>, Provider, Added>): EffectApiBuilder<GenericActionCtx<DM> & EffectValue<Added>, V, 'action', Provider, Added>;
 //#endregion
 export { EffectApiBuilder, effectApiBuilder };
 //# sourceMappingURL=api.d.mts.map

package/dist/modules/effect/api.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"api.mjs","names":[],"sources":["../../../src/modules/effect/api.ts"],"sourcesContent":["import type {\n\tActionBuilder,\n\tArgsArrayForOptionalValidator,\n\tArgsArrayToObject,\n\tDefaultArgsForOptionalValidator,\n\tFunctionVisibility,\n\tGenericActionCtx,\n\tGenericDataModel,\n\tGenericMutationCtx,\n\tGenericQueryCtx,\n\tMutationBuilder,\n\tQueryBuilder,\n\tRegisteredAction,\n\tRegisteredMutation,\n\tRegisteredQuery,\n\tReturnValueForOptionalValidator,\n} from 'convex/server'\nimport type { PropertyValidators, Validator } from 'convex/values'\nimport type { EffectValue } from './operation'\nimport {\n\twrapEffectBuilder,\n\ttype CheckedApiRequirements,\n\ttype EffectApiOptions,\n\ttype EffectApiErrorProjection,\n\ttype EffectApiErrorContract,\n\ttype EffectApiServices,\n\ttype EffectApiHandlerValue,\n} from './api-runtime'\n\n// Convex's optional-validator grammar, restricted to unknown instead of public any.\ntype ApiValidator = PropertyValidators | Validator<unknown, 'required', string> | void\ntype ApiOutput<Returns extends ApiValidator> = [Returns] extends [void]\n\t? unknown\n\t: ReturnValueForOptionalValidator<Returns>\nexport type EffectApiBuilder<\n\tCtx,\n\tVisibility extends FunctionVisibility,\n\tKind extends 'query' | 'mutation' | 'action',\n\tProvider,\n> = {\n\t<\n\t\tArgs extends ApiValidator,\n\t\tReturns extends ApiValidator = void,\n\t\tReturned extends EffectApiHandlerValue<ApiOutput<Returns>> = EffectApiHandlerValue<\n\t\t\tApiOutput<Returns>\n\t\t>,\n\t\tOneOrZeroArgs extends ArgsArrayForOptionalValidator<Args> =\n\t\t\tDefaultArgsForOptionalValidator<Args>,\n\t>(\n\t\tdefinition: (\n\t\t\t| { args?: Args; returns?: Returns; handler: (ctx: Ctx, ...args: OneOrZeroArgs) => Returned }\n\t\t\t| ((ctx: Ctx, ...args: OneOrZeroArgs) => Returned)\n\t\t) &\n\t\t\tCheckedApiRequirements<Returned, Provider>,\n\t): Kind extends 'query'\n\t\t? RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, Promise<EffectValue<Returned>>>\n\t\t: Kind extends 'mutation'\n\t\t\t? RegisteredMutation<\n\t\t\t\t\tVisibility,\n\t\t\t\t\tArgsArrayToObject<OneOrZeroArgs>,\n\t\t\t\t\tPromise<EffectValue<Returned>>\n\t\t\t\t>\n\t\t\t: RegisteredAction<\n\t\t\t\t\tVisibility,\n\t\t\t\t\tArgsArrayToObject<OneOrZeroArgs>,\n\t\t\t\t\tPromise<EffectValue<Returned>>\n\t\t\t\t>\n}\n\n/** Provision request services after the supplied builder has constructed its trusted context. */\nexport function effectApiBuilder<\n\tDM extends GenericDataModel,\n\tV extends FunctionVisibility,\n\tProvider extends EffectApiServices,\n>(\n\tbuilder: QueryBuilder<DM, V>,\n\toptions: EffectApiOptions<GenericQueryCtx<DM>, Provider>,\n): EffectApiBuilder<GenericQueryCtx<DM>, V, 'query', Provider>\nexport function effectApiBuilder<\n\tDM extends GenericDataModel,\n\tV extends FunctionVisibility,\n\tProvider extends EffectApiServices,\n>(\n\tbuilder: MutationBuilder<DM, V>,\n\toptions: EffectApiOptions<GenericMutationCtx<DM>, Provider>,\n): EffectApiBuilder<GenericMutationCtx<DM>, V, 'mutation', Provider>\nexport function effectApiBuilder<\n\tDM extends GenericDataModel,\n\tV extends FunctionVisibility,\n\tProvider extends EffectApiServices,\n>(\n\tbuilder: ActionBuilder<DM, V>,\n\toptions: EffectApiOptions<GenericActionCtx<DM>, Provider>,\n): EffectApiBuilder<GenericActionCtx<DM>, V, 'action', Provider>\nexport function effectApiBuilder(\n\tbuilder: Function,\n\toptions: {\n\t\tservices: Function\n\t\tmapError?: EffectApiErrorProjection\n\t\terrors?: EffectApiErrorContract\n\t},\n): Function {\n\treturn wrapEffectBuilder(builder, options)\n}\n"],"mappings":"sDA8FA,SAAgB,EACf,EACA,EAKW,CACX,OAAO,EAAkB,EAAS,CAAO,CAC1C"}
+{"version":3,"file":"api.mjs","names":[],"sources":["../../../src/modules/effect/api.ts"],"sourcesContent":["import type {\n\tActionBuilder,\n\tArgsArrayForOptionalValidator,\n\tArgsArrayToObject,\n\tDefaultArgsForOptionalValidator,\n\tFunctionVisibility,\n\tGenericActionCtx,\n\tGenericDataModel,\n\tGenericMutationCtx,\n\tGenericQueryCtx,\n\tMutationBuilder,\n\tQueryBuilder,\n\tRegisteredAction,\n\tRegisteredMutation,\n\tRegisteredQuery,\n\tReturnValueForOptionalValidator,\n} from 'convex/server'\nimport type { PropertyValidators, Validator } from 'convex/values'\nimport type { EffectValue } from './operation'\nimport {\n\twrapEffectBuilder,\n\ttype CheckedApiRequirements,\n\ttype EffectApiOptions,\n\ttype EffectApiErrorProjection,\n\ttype EffectApiErrorContract,\n\ttype EffectApiServices,\n\ttype EffectApiHandlerValue,\n\ttype EffectApiContext,\n} from './api-runtime'\n\n// Convex's optional-validator grammar, restricted to unknown instead of public any.\ntype ApiValidator = PropertyValidators | Validator<unknown, 'required', string> | void\ntype ApiOutput<Returns extends ApiValidator> = [Returns] extends [void]\n\t? unknown\n\t: ReturnValueForOptionalValidator<Returns>\nexport type EffectApiBuilder<\n\tCtx,\n\tVisibility extends FunctionVisibility,\n\tKind extends 'query' | 'mutation' | 'action',\n\tProvider,\n\tInitialized = {},\n> = {\n\t<\n\t\tArgs extends ApiValidator,\n\t\tReturns extends ApiValidator = void,\n\t\tReturned extends EffectApiHandlerValue<ApiOutput<Returns>> = EffectApiHandlerValue<\n\t\t\tApiOutput<Returns>\n\t\t>,\n\t\tOneOrZeroArgs extends ArgsArrayForOptionalValidator<Args> =\n\t\t\tDefaultArgsForOptionalValidator<Args>,\n\t>(\n\t\tdefinition: (\n\t\t\t| { args?: Args; returns?: Returns; handler: (ctx: Ctx, ...args: OneOrZeroArgs) => Returned }\n\t\t\t| ((ctx: Ctx, ...args: OneOrZeroArgs) => Returned)\n\t\t) &\n\t\t\tCheckedApiRequirements<Returned, Provider> &\n\t\t\tCheckedApiRequirements<Initialized, Provider>,\n\t): Kind extends 'query'\n\t\t? RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, Promise<EffectValue<Returned>>>\n\t\t: Kind extends 'mutation'\n\t\t\t? RegisteredMutation<\n\t\t\t\t\tVisibility,\n\t\t\t\t\tArgsArrayToObject<OneOrZeroArgs>,\n\t\t\t\t\tPromise<EffectValue<Returned>>\n\t\t\t\t>\n\t\t\t: RegisteredAction<\n\t\t\t\t\tVisibility,\n\t\t\t\t\tArgsArrayToObject<OneOrZeroArgs>,\n\t\t\t\t\tPromise<EffectValue<Returned>>\n\t\t\t\t>\n}\n\n/** Provision request services after the supplied builder has constructed its trusted context. */\nexport function effectApiBuilder<\n\tDM extends GenericDataModel,\n\tV extends FunctionVisibility,\n\tProvider extends EffectApiServices = import('effect').Context.Context<never>,\n\tAdded extends EffectApiContext = {},\n>(\n\tbuilder: QueryBuilder<DM, V>,\n\toptions: EffectApiOptions<GenericQueryCtx<DM>, Provider, Added>,\n): EffectApiBuilder<GenericQueryCtx<DM> & EffectValue<Added>, V, 'query', Provider, Added>\nexport function effectApiBuilder<\n\tDM extends GenericDataModel,\n\tV extends FunctionVisibility,\n\tProvider extends EffectApiServices = import('effect').Context.Context<never>,\n\tAdded extends EffectApiContext = {},\n>(\n\tbuilder: MutationBuilder<DM, V>,\n\toptions: EffectApiOptions<GenericMutationCtx<DM>, Provider, Added>,\n): EffectApiBuilder<GenericMutationCtx<DM> & EffectValue<Added>, V, 'mutation', Provider, Added>\nexport function effectApiBuilder<\n\tDM extends GenericDataModel,\n\tV extends FunctionVisibility,\n\tProvider extends EffectApiServices = import('effect').Context.Context<never>,\n\tAdded extends EffectApiContext = {},\n>(\n\tbuilder: ActionBuilder<DM, V>,\n\toptions: EffectApiOptions<GenericActionCtx<DM>, Provider, Added>,\n): EffectApiBuilder<GenericActionCtx<DM> & EffectValue<Added>, V, 'action', Provider, Added>\nexport function effectApiBuilder(\n\tbuilder: Function,\n\toptions: {\n\t\tservices?: Function\n\t\tcontext?: Function\n\t\tmapError?: EffectApiErrorProjection\n\t\terrors?: EffectApiErrorContract\n\t},\n): Function {\n\treturn wrapEffectBuilder(builder, options)\n}\n"],"mappings":"sDAoGA,SAAgB,EACf,EACA,EAMW,CACX,OAAO,EAAkB,EAAS,CAAO,CAC1C"}

package/dist/modules/effect/command.d.mts

@@ -1,4 +1,4 @@
-import { ContractSchema } from "../contracts/contract.mjs";
+import { ContractOutput, ContractSchema } from "../contracts/contract.mjs";
 import { OperationPublicResult, SelectedOperation } from "../contracts/exposure.mjs";
 import { Observability } from "../../components/foundation/modules/observability/observability.mjs";
 import { AuditEntryInput } from "../../components/foundation/client.mjs";
@@ -49,8 +49,12 @@ type ErrorOf<Definition, Resolve, Dependencies, Guard> = EffectOperationError<De
 type RequirementsOf<Definition, Resolve, Dependencies, Guard> = EffectOperationRequirements<Definition> | CallbackRequirements<Resolve | Dependencies[keyof Dependencies]> | UnwrappedDefaultRequirements<Definition, Guard>;
 /** Internal registry constructor: the public Foundation binds host policies once. */
 declare function createEffectCommand<Resolve extends Resolver, const Operations extends Registry<DomainOf<Resolve>>, const Dependencies extends EffectCommandDependencies, Guard = never>(configuration: EffectCommandConfiguration<Resolve, Operations, Guard> & Dependencies & HostCompatible<Resolve, Dependencies>): {
+  /** Bind invocation context without resolving it or running an operation. */
+  withContext(context: HostOf<Resolve>): {
+    exec: <Key extends Extract<keyof Operations, string>>(operation: Key, input: EffectOperationArgument<Operations[Key]>) => Effect.Effect<ContractOutput<Operations[Key]["result"]>, ErrorOf<Operations[Key], Resolve, Dependencies, Guard>, RequirementsOf<Operations[Key], Resolve, Dependencies, Guard>>;
+  };
   expose<const Owner extends symbol, const Key extends Extract<keyof Operations, string>>(owner: Owner, operation: Key): SelectedOperation<Owner, Key, Operations[Key]['input'], OperationPublicResult<Operations[Key]>>;
-  exec<Key extends Extract<keyof Operations, string>>(operation: Key, input: EffectOperationArgument<Operations[Key]>, host: HostOf<Resolve>): Effect.Effect<EffectOperationResult<Operations[Key]>, ErrorOf<Operations[Key], Resolve, Dependencies, Guard>, RequirementsOf<Operations[Key], Resolve, Dependencies, Guard>>;
+  exec: <Key extends Extract<keyof Operations, string>>(operation: Key, input: EffectOperationArgument<Operations[Key]>, host: HostOf<Resolve>) => Effect.Effect<EffectOperationResult<Operations[Key]>, ErrorOf<Operations[Key], Resolve, Dependencies, Guard>, RequirementsOf<Operations[Key], Resolve, Dependencies, Guard>>;
 };
 /** Bind trusted application policies without exposing a loose public command kernel. */
 declare function bindEffectCommand<const Dependencies extends EffectCommandDependencies>(dependencies: Dependencies): <Resolve extends Resolver, const Operations extends Registry<DomainOf<Resolve>>, Guard = never>(configuration: EffectCommandConfiguration<Resolve, Operations, Guard> & HostCompatible<Resolve, Dependencies>) => ReturnType<typeof createEffectCommand<Resolve, Operations, Dependencies, Guard>>;

package/dist/modules/effect/command.mjs

@@ -1,2 +1,2 @@
-import{selectOperation as e}from"../contracts/exposure.mjs";import{effectOperationFactory as t}from"./operation.mjs";import{decodeEffectContract as n}from"./schema.mjs";import{CommandPermissionError as r,executeCommandLifecycle as i}from"../../components/foundation/modules/command/lifecycle.mjs";import{normalizeEffect as a,observationFailure as o}from"./normalize.mjs";import{Effect as s,Exit as c}from"effect";const l={succeed:s.succeed,suspend:s.suspend,flatMap:s.flatMap};function u(u){let d=u.operations(t());return{expose(t,n){if(!Object.hasOwn(d,n))throw Error(`The selected command operation is not configured`);return e(t,`mutation`,n,d[n])},exec(e,t,p){return s.suspend(()=>{if(!Object.prototype.hasOwnProperty.call(d,e))throw Error(`The selected command operation is not configured`);let m=d[e];return s.flatMap(n(m.input,t),t=>{let d=t,h=u.observability.start({operation:e,classification:m.classification}),g=u.context;return a(()=>g(p)).pipe(s.flatMap(t=>i(l,{operation:e,classification:m.classification,context:t,command:d,permission:m.permission===void 0?void 0:()=>a(()=>{if(!u.checkPermission)throw new r(e);return u.checkPermission(p,{permission:m.permission,operation:e})}).pipe(s.asVoid),prepare:()=>a(()=>m.prepare?.(t,d)).pipe(s.map(e=>e?.kind===`execute`?{kind:`execute`,complete:e.complete?t=>a(()=>e.complete(t)).pipe(s.asVoid):void 0}:e)),decodeReplay:e=>n(m.replayResult??m.result,e),middleware:m.middleware?[e=>f(()=>m.middleware({...e,input:d}))]:[],defaultGuard:e=>a(()=>u.defaults?.guard?.(e)).pipe(s.asVoid),guard:e=>a(()=>m.guard?.(e,d)).pipe(s.asVoid),run:e=>f(()=>m.handler(d,e)),decodeResult:e=>n(m.result,e),audit:e=>a(()=>m.audit({command:d,result:e},t)),writeAudit:e=>a(()=>u.writeAudit(p,e)),aggregates:m.aggregates})),s.onExit(e=>s.sync(()=>{c.isSuccess(e)?h.completed():h.failed(o(e.cause))})))})})}}}function d(e){return function(t){return u({...t,...e})}}function f(e){return a(e)}export{d as bindEffectCommand,u as createEffectCommand};
+import{selectOperation as e}from"../contracts/exposure.mjs";import{effectOperationFactory as t}from"./operation.mjs";import{decodeEffectContract as n}from"./schema.mjs";import{CommandPermissionError as r,executeCommandLifecycle as i}from"../../components/foundation/modules/command/lifecycle.mjs";import{normalizeEffect as a,observationFailure as o}from"./normalize.mjs";import{Effect as s,Exit as c}from"effect";const l={succeed:s.succeed,suspend:s.suspend,flatMap:s.flatMap};function u(u){let d=u.operations(t()),p=(e,t,p)=>s.suspend(()=>{if(!Object.prototype.hasOwnProperty.call(d,e))throw Error(`The selected command operation is not configured`);let m=d[e];return s.flatMap(n(m.input,t),t=>{let d=t,h=u.observability.start({operation:e,classification:m.classification}),g=u.context;return a(()=>g(p)).pipe(s.flatMap(t=>i(l,{operation:e,classification:m.classification,context:t,command:d,permission:m.permission===void 0?void 0:()=>a(()=>{if(!u.checkPermission)throw new r(e);return u.checkPermission(p,{permission:m.permission,operation:e})}).pipe(s.asVoid),prepare:()=>a(()=>m.prepare?.(t,d)).pipe(s.map(e=>e?.kind===`execute`?{kind:`execute`,complete:e.complete?t=>a(()=>e.complete(t)).pipe(s.asVoid):void 0}:e)),decodeReplay:e=>n(m.replayResult??m.result,e),middleware:m.middleware?[e=>f(()=>m.middleware({...e,input:d}))]:[],defaultGuard:e=>a(()=>u.defaults?.guard?.(e)).pipe(s.asVoid),guard:e=>a(()=>m.guard?.(e,d)).pipe(s.asVoid),run:e=>f(()=>m.handler(d,e)),decodeResult:e=>n(m.result,e),audit:e=>a(()=>m.audit({command:d,result:e},t)),writeAudit:e=>a(()=>u.writeAudit(p,e)),aggregates:m.aggregates})),s.onExit(e=>s.sync(()=>{c.isSuccess(e)?h.completed():h.failed(o(e.cause))})))})});return{withContext(e){return{exec:(t,n)=>p(t,n,e)}},expose(t,n){if(!Object.hasOwn(d,n))throw Error(`The selected command operation is not configured`);return e(t,`mutation`,n,d[n])},exec:p}}function d(e){return function(t){return u({...t,...e})}}function f(e){return a(e)}export{d as bindEffectCommand,u as createEffectCommand};
 //# sourceMappingURL=command.mjs.map