cvx-kit 0.1.8 → 0.1.10

package/dist/modules/contracts/workflow.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.mjs","names":[],"sources":["../../../src/modules/contracts/workflow.ts"],"sourcesContent":["import type { FunctionReference, FunctionVisibility, FunctionType } from 'convex/server'\nimport type { WorkflowCtx } from '@convex-dev/workflow'\nimport {\n\tdecodeContract,\n\ttype ContractInput,\n\ttype ContractOutput,\n\ttype NeutralSchema,\n} from './contract'\nimport {\n\tcanonicalConvexBytes,\n\tcaptureIdempotencyInvocation,\n\ttype CanonicalConvexBounds,\n\ttype IdempotencyInvocation,\n\ttype IdempotencyPreparation,\n} from './idempotency'\n\nexport class WorkflowBindingError extends Error {\n\treadonly _tag = 'WorkflowBindingError'\n\tconstructor(message: string) {\n\t\tsuper(message)\n\t\tthis.name = 'WorkflowBindingError'\n\t}\n}\nexport interface WorkflowExecution<Args = unknown> {\n\treadonly version: 1\n\treadonly operation: string\n\treadonly operationVersion: string\n\treadonly contractVersion: string\n\treadonly bindingVersion: string\n\t/** Host-issued business-run identity. Recovery preserves it. */\n\treadonly run: string\n\t/** Opaque host capability; never caller-supplied principal or tenant authority. */\n\treadonly capability: string\n\t/** Logical occurrence, distinct for each repeated loop step. */\n\treadonly occurrence: string\n\treadonly args: Args\n}\nexport type WorkflowStepArguments<Args> = { execution: WorkflowExecution<Args> }\nconst fields = [\n\t'version',\n\t'operation',\n\t'operationVersion',\n\t'contractVersion',\n\t'bindingVersion',\n\t'run',\n\t'capability',\n\t'occurrence',\n\t'args',\n] as const\nconst descriptorBounds = {\n\tmaxDepth: 64,\n\tmaxNodes: 100000,\n\tmaxBytes: 1000000,\n\tmaxArrayLength: 100000,\n\tmaxObjectFields: 100000,\n}\n/** Strict plain, versioned transport. Validity does not confer authority; the host resolves capability anew. */\n/* oxlint-disable anti-slop/no-unknown-parameters, anti-slop/no-runtime-typeof -- This decoder validates an untrusted execution descriptor before it enters the native workflow boundary. */\nexport function workflowExecution<Args>(value: WorkflowExecution<Args>): WorkflowExecution<Args>\nexport function workflowExecution(value: unknown): WorkflowExecution\nexport function workflowExecution(value: unknown): WorkflowExecution {\n\tif (\n\t\t!value ||\n\t\ttypeof value !== 'object' ||\n\t\tObject.getPrototypeOf(value) !== Object.prototype ||\n\t\tReflect.ownKeys(value).length !== fields.length ||\n\t\tfields.some((field) => !Object.hasOwn(value, field))\n\t)\n\t\tthrow new WorkflowBindingError('Execution requires exact plain descriptor fields')\n\t// SAFETY: the exact field set is checked above; values and accessors are checked before use below.\n\tconst descriptor = value as WorkflowExecution\n\tfor (const field of fields)\n\t\tif (!('value' in Object.getOwnPropertyDescriptor(value, field)!))\n\t\t\tthrow new WorkflowBindingError('Execution cannot contain accessors')\n\tif (\n\t\tdescriptor.version !== 1 ||\n\t\tfields\n\t\t\t.filter((field) => field !== 'version' && field !== 'args')\n\t\t\t.some((field) => typeof descriptor[field] !== 'string' || descriptor[field].length === 0)\n\t)\n\t\tthrow new WorkflowBindingError('Invalid execution descriptor version or identity')\n\ttry {\n\t\tcanonicalConvexBytes(descriptor.args, descriptorBounds)\n\t} catch {\n\t\tthrow new WorkflowBindingError('Execution args require plain Convex data')\n\t}\n\treturn descriptor\n}\n/* oxlint-enable anti-slop/no-unknown-parameters, anti-slop/no-runtime-typeof */\nexport interface WorkflowBinding<\n\tKind extends FunctionType,\n\tArgs extends NeutralSchema,\n\tResult extends NeutralSchema,\n> {\n\treadonly kind: Kind\n\treadonly operation: string\n\treadonly operationVersion: string\n\treadonly contractVersion: string\n\treadonly bindingVersion: string\n\treadonly args: Args\n\treadonly result: Result\n\treadonly reference: FunctionReference<\n\t\tNoInfer<Kind>,\n\t\tFunctionVisibility,\n\t\tWorkflowStepArguments<NoInfer<ContractInput<Args>>>,\n\t\tNoInfer<ContractInput<Result>>\n\t>\n\t/** Host explicitly lists deployed descriptor versions whose semantics remain compatible. */\n\treadonly compatibleVersions?: readonly {\n\t\toperationVersion: string\n\t\tcontractVersion: string\n\t\tbindingVersion: string\n\t}[]\n}\n/** Both phantom reference args and results must match the explicit wire contracts. */\nexport function workflowBinding<\n\tKind extends FunctionType,\n\tconst Args extends NeutralSchema,\n\tconst Result extends NeutralSchema,\n>(binding: WorkflowBinding<Kind, Args, Result>): WorkflowBinding<Kind, Args, Result> {\n\tconst compatibleVersions = binding.compatibleVersions?.map((version) =>\n\t\tObject.freeze({ ...version }),\n\t)\n\tconst snapshot = { ...binding }\n\tif (compatibleVersions !== undefined)\n\t\tsnapshot.compatibleVersions = Object.freeze(compatibleVersions)\n\treturn Object.freeze(snapshot)\n}\nexport type WorkflowStepOptions = {\n\tname?: string\n\tretry?: NonNullable<Parameters<WorkflowCtx['withOptions']>[0]['retry']>\n} & (\n\t| { inline?: false; runAt?: number; runAfter?: number }\n\t| { inline: true; runAt?: never; runAfter?: never }\n)\n/** A structural seam allows invocation-scoped native WorkflowCtx without creating another durability runtime. */\nexport interface WorkflowStepRunner {\n\t/* oxlint-disable anti-slop/no-unknown-returns -- Native runner results stay opaque here; runWorkflowStep correlates them with the binding's raw result contract without replay decoding. */\n\trunQuery?: (\n\t\treference: FunctionReference<'query', FunctionVisibility>,\n\t\targs: WorkflowStepArguments<unknown>,\n\t\toptions?: WorkflowStepOptions,\n\t) => Promise<unknown>\n\trunMutation?: (\n\t\treference: FunctionReference<'mutation', FunctionVisibility>,\n\t\targs: WorkflowStepArguments<unknown>,\n\t\toptions?: WorkflowStepOptions,\n\t) => Promise<unknown>\n\trunAction?: (\n\t\treference: FunctionReference<'action', FunctionVisibility>,\n\t\targs: WorkflowStepArguments<unknown>,\n\t\toptions?: WorkflowStepOptions,\n\t) => Promise<unknown>\n\t/* oxlint-enable anti-slop/no-unknown-returns */\n}\nexport async function runWorkflowStep<\n\tKind extends FunctionType,\n\tArgs extends NeutralSchema,\n\tResult extends NeutralSchema,\n>(\n\tstep: WorkflowCtx | WorkflowStepRunner,\n\tbinding: WorkflowBinding<Kind, Args, Result>,\n\tinput: WorkflowExecution<ContractInput<Args>>,\n\toptions: WorkflowStepOptions = {},\n): Promise<ContractInput<Result>> {\n\t// SAFETY: each binding has nonempty, checked generated args. Native ArgsAndOptions' empty-args overload is never selected.\n\tconst runner = step as WorkflowStepRunner\n\tconst execution = workflowExecution(input)\n\tconst versions = [binding, ...(binding.compatibleVersions ?? [])]\n\tif (\n\t\texecution.operation !== binding.operation ||\n\t\t!versions.some(\n\t\t\t(version) =>\n\t\t\t\tversion.operationVersion === execution.operationVersion &&\n\t\t\t\tversion.contractVersion === execution.contractVersion &&\n\t\t\t\tversion.bindingVersion === execution.bindingVersion,\n\t\t)\n\t)\n\t\tthrow new WorkflowBindingError('Incompatible workflow operation version')\n\tconst nativeOptions = {\n\t\t...options,\n\t\tname: options.name ?? `${execution.operation}:${execution.occurrence}`,\n\t}\n\tlet output: unknown\n\tswitch (binding.kind) {\n\t\tcase 'query':\n\t\t\tif (!runner.runQuery) throw new WorkflowBindingError('Native query runner missing')\n\t\t\t// SAFETY: the checked binding kind selects this exact native reference kind.\n\t\t\toutput = await runner.runQuery(\n\t\t\t\tbinding.reference as FunctionReference<'query', FunctionVisibility>,\n\t\t\t\t{ execution },\n\t\t\t\tnativeOptions,\n\t\t\t)\n\t\t\tbreak\n\t\tcase 'mutation':\n\t\t\tif (!runner.runMutation) throw new WorkflowBindingError('Native mutation runner missing')\n\t\t\t// SAFETY: the checked binding kind selects this exact native reference kind.\n\t\t\toutput = await runner.runMutation(\n\t\t\t\tbinding.reference as FunctionReference<'mutation', FunctionVisibility>,\n\t\t\t\t{ execution },\n\t\t\t\tnativeOptions,\n\t\t\t)\n\t\t\tbreak\n\t\tcase 'action':\n\t\t\tif (!runner.runAction) throw new WorkflowBindingError('Native action runner missing')\n\t\t\tif (options.inline) throw new WorkflowBindingError('Actions cannot execute inline')\n\t\t\t// SAFETY: the checked binding kind selects this exact native reference kind.\n\t\t\toutput = await runner.runAction(\n\t\t\t\tbinding.reference as FunctionReference<'action', FunctionVisibility>,\n\t\t\t\t{ execution },\n\t\t\t\t{ ...nativeOptions, retry: options.retry ?? false },\n\t\t\t)\n\t\t\tbreak\n\t}\n\t// Native validators own wire validation. Replaying workflow code must not rerun transforms.\n\t// SAFETY: the binding correlates the generated reference's result with this raw wire contract.\n\treturn output as ContractInput<Result>\n}\nexport async function workflowDecode<S extends NeutralSchema>(\n\tschema: S,\n\t// oxlint-disable-next-line anti-slop/no-unknown-parameters -- The schema parses retained or native transport values at this boundary.\n\tvalue: unknown,\n): Promise<ContractOutput<S>> {\n\tconst decoded = await decodeContract(schema, value)\n\tif (decoded.issues) throw new WorkflowBindingError('Workflow contract validation failed')\n\treturn decoded.value\n}\ntype Ordinary<A> = A | PromiseLike<A>\n/** This helper belongs inside a registered native function, never in the replaying workflow handler. */\nexport function workflowAttempt<Args, Authority, Result>(configuration: {\n\tauthorize: (execution: WorkflowExecution<Args>) => Ordinary<Authority>\n\texecute: (execution: WorkflowExecution<Args>, authority: Authority) => Ordinary<Result>\n}) {\n\treturn async (input: WorkflowExecution<Args>): Promise<Result> => {\n\t\tconst execution = workflowExecution(input)\n\t\tconst authority = await configuration.authorize(execution)\n\t\treturn configuration.execute(execution, authority)\n\t}\n}\nexport type WorkflowOutcome<Result = unknown, Failure = unknown> =\n\t| { readonly version: 1; readonly kind: 'succeeded'; readonly value: Result }\n\t| { readonly version: 1; readonly kind: 'failed'; readonly error: Failure }\ndeclare const protectedMutation: unique symbol\nexport interface ReceiptProtectedWorkflowMutation<Args, Result> {\n\treadonly [protectedMutation]: { args: Args; result: Result }\n\treadonly handler: (execution: WorkflowExecution<Args>) => Promise<Result>\n}\nexport interface WorkflowReceiptAdapter<S extends NeutralSchema> {\n\treadonly replayResult: S\n\treadonly prepare: (\n\t\tinvocation: IdempotencyInvocation,\n\t) => Promise<IdempotencyPreparation<ContractOutput<S>>>\n}\n/** Host registers this handler as the inner native mutation. All callbacks share its transaction. */\nexport function receiptWorkflowMutation<\n\tArgs,\n\tAuthority,\n\tconst Replay extends NeutralSchema,\n>(configuration: {\n\tauthorize: (execution: WorkflowExecution<Args>) => Ordinary<Authority>\n\treceipt: (authority: Authority) => WorkflowReceiptAdapter<Replay>\n\tinvocation: (execution: WorkflowExecution<Args>, authority: Authority) => IdempotencyInvocation\n\texecute: (\n\t\texecution: WorkflowExecution<Args>,\n\t\tauthority: Authority,\n\t) => Ordinary<ContractOutput<Replay>>\n}): ReceiptProtectedWorkflowMutation<Args, ContractOutput<Replay>> {\n\tconst handler = workflowAttempt({\n\t\tauthorize: configuration.authorize,\n\t\texecute: async (execution: WorkflowExecution<Args>, authority: Authority) => {\n\t\t\tconst adapter = configuration.receipt(authority)\n\t\t\tconst preparation = await adapter.prepare(configuration.invocation(execution, authority))\n\t\t\tif (preparation.kind === 'replay')\n\t\t\t\treturn workflowDecode(adapter.replayResult, preparation.result)\n\t\t\tconst value = await configuration.execute(execution, authority)\n\t\t\tawait preparation.complete(value)\n\t\t\treturn value\n\t\t},\n\t})\n\t// SAFETY: the private type evidence can only be issued by this receipt-protected helper.\n\treturn { handler } as ReceiptProtectedWorkflowMutation<Args, ContractOutput<Replay>>\n}\nexport function workflowReceiptInvocation(\n\texecution: WorkflowExecution,\n\toptions: { scope: string; fingerprintPolicy: string; bounds: CanonicalConvexBounds },\n): IdempotencyInvocation {\n\tconst descriptor = workflowExecution(execution)\n\treturn captureIdempotencyInvocation({\n\t\tbinding: { kind: 'mutation', atomicity: 'same-mutation' },\n\t\tidentity: {\n\t\t\toperation: descriptor.operation,\n\t\t\tscope: options.scope,\n\t\t\tkey: JSON.stringify([descriptor.run, descriptor.occurrence]),\n\t\t},\n\t\tversions: {\n\t\t\toperation: descriptor.operationVersion,\n\t\t\tcontract: descriptor.contractVersion,\n\t\t\tbinding: descriptor.bindingVersion,\n\t\t\tfingerprintPolicy: options.fingerprintPolicy,\n\t\t},\n\t\trawInput: descriptor.args,\n\t\tcanonical: { bounds: options.bounds },\n\t})\n}\ntype TerminalMode<Args> =\n\t| {\n\t\t\tkind: 'mutation'\n\t\t\t/** Assertion supplied only after host native rollback/journaling acceptance. */ atomicJournalProof: 'host-verified'\n\t  }\n\t| { kind: 'action'; protectedMutation: ReceiptProtectedWorkflowMutation<Args, unknown> }\n/** The native inner mutation rejection must cross its transaction boundary before terminal mapping. */\nexport function terminalWorkflowAttempt<\n\tArgs,\n\tAuthority,\n\tconst Result extends NeutralSchema,\n\tconst Failure extends NeutralSchema,\n>(\n\tconfiguration: TerminalMode<Args> & {\n\t\tauthorize: (execution: WorkflowExecution<Args>) => Ordinary<Authority>\n\t\tinvokeMutation: (\n\t\t\texecution: WorkflowExecution<Args>,\n\t\t\tauthority: Authority,\n\t\t) => Promise<ContractInput<Result>>\n\t\t// oxlint-disable-next-line anti-slop/no-unknown-parameters -- Native thrown values are classified by the host before validating the terminal failure contract.\n\t\tterminal: (error: unknown) => Ordinary<ContractInput<Failure> | undefined>\n\t\tresult: Result\n\t\tfailure: Failure\n\t},\n) {\n\treturn workflowAttempt({\n\t\tauthorize: configuration.authorize,\n\t\texecute: async (\n\t\t\texecution: WorkflowExecution<Args>,\n\t\t\tauthority: Authority,\n\t\t): Promise<WorkflowOutcome<ContractInput<Result>, ContractOutput<Failure>>> => {\n\t\t\tlet value: ContractInput<Result>\n\t\t\ttry {\n\t\t\t\tvalue = await configuration.invokeMutation(execution, authority)\n\t\t\t} catch (error) {\n\t\t\t\tconst terminal = await configuration.terminal(error)\n\t\t\t\tif (terminal === undefined) throw error\n\t\t\t\tconst safeFailure = await workflowDecode(configuration.failure, terminal)\n\t\t\t\tcanonicalConvexBytes(safeFailure, descriptorBounds)\n\t\t\t\treturn { version: 1, kind: 'failed', error: safeFailure }\n\t\t\t}\n\t\t\tawait workflowDecode(configuration.result, value)\n\t\t\tcanonicalConvexBytes(value, descriptorBounds)\n\t\t\treturn { version: 1, kind: 'succeeded', value }\n\t\t},\n\t})\n}\nexport type WorkflowNativeStatus = 'running' | 'succeeded' | 'failed' | 'canceled'\nexport interface WorkflowHostState<Result = unknown, Failure = unknown> {\n\treadonly generation: number\n\treadonly status: WorkflowNativeStatus\n\treadonly nativeStatus: WorkflowNativeStatus\n\treadonly outcome?: WorkflowOutcome<Result, Failure>\n}\nexport interface WorkflowHostUpdate<Result = unknown, Failure = unknown> {\n\treadonly generation: number\n\treadonly nativeStatus: WorkflowNativeStatus\n\treadonly outcome?: WorkflowOutcome<Result, Failure>\n}\nexport type WorkflowTransition<Result = unknown, Failure = unknown> = {\n\treadonly kind: 'applied' | 'ignored'\n\treadonly state: WorkflowHostState<Result, Failure>\n}\n/** Call within a host transaction or compare-and-set. A late operation failure refines host success; cancellation and terminal native status stay fenced. */\nexport function workflowTransition<Result, Failure>(\n\tcurrent: WorkflowHostState<Result, Failure>,\n\tupdate: WorkflowHostUpdate<Result, Failure>,\n): WorkflowTransition<Result, Failure> {\n\tgeneration(current.generation)\n\tgeneration(update.generation)\n\tif (current.generation !== update.generation) return { kind: 'ignored', state: current }\n\tconst nativeStatus =\n\t\tcurrent.nativeStatus !== 'running' ? current.nativeStatus : update.nativeStatus\n\tconst outcome = current.outcome ?? update.outcome\n\tconst status =\n\t\t(current.status === 'running' || current.status === 'succeeded') &&\n\t\tnativeStatus === 'succeeded' &&\n\t\toutcome?.kind === 'failed'\n\t\t\t? 'failed'\n\t\t\t: current.status !== 'running'\n\t\t\t\t? current.status\n\t\t\t\t: nativeStatus\n\tconst state = { generation: current.generation, status, nativeStatus }\n\treturn { kind: 'applied', state: outcome === undefined ? state : { ...state, outcome } }\n}\nexport function workflowCancel<Result, Failure>(\n\tcurrent: WorkflowHostState<Result, Failure>,\n\texpectedGeneration: number,\n): WorkflowTransition<Result, Failure> {\n\tgeneration(expectedGeneration)\n\tif (current.generation !== expectedGeneration) return { kind: 'ignored', state: current }\n\treturn {\n\t\tkind: 'applied',\n\t\tstate: { ...current, status: current.status === 'running' ? 'canceled' : current.status },\n\t}\n}\n/** Host calls after an authorized native restart. Receipt identity remains run plus occurrence. */\nexport function workflowRestart<Result, Failure>(\n\tcurrent: WorkflowHostState<Result, Failure>,\n): WorkflowHostState<Result, Failure> {\n\tgeneration(current.generation)\n\tgeneration(current.generation + 1)\n\tconst state = {\n\t\tgeneration: current.generation + 1,\n\t\tstatus: 'running' as const,\n\t\tnativeStatus: 'running' as const,\n\t}\n\treturn current.outcome?.kind === 'succeeded' ? { ...state, outcome: current.outcome } : state\n}\n/** Host closures capture the trusted run, secured storage and manager. `write` must enforce expected generation atomically. */\nexport function workflowStatusBindings<Result, Failure>(configuration: {\n\tauthorize: () => Ordinary<void>\n\tread: () => Ordinary<WorkflowHostState<Result, Failure>>\n\twrite: (expectedGeneration: number, state: WorkflowHostState<Result, Failure>) => Ordinary<void>\n\tnativeStatus: () => Ordinary<WorkflowNativeStatus>\n\treceiptOutcome: () => Ordinary<WorkflowOutcome<Result, Failure> | undefined>\n\t/** Host calls the manager in the same transaction as its guarded state write. */\n\tcancelNative: () => Ordinary<void>\n\trestartNative: () => Ordinary<void>\n}) {\n\tasync function apply(\n\t\texpectedGeneration: number,\n\t\tnativeStatus: WorkflowNativeStatus,\n\t\toutcome?: WorkflowOutcome<Result, Failure>,\n\t) {\n\t\tconst update = { generation: expectedGeneration, nativeStatus }\n\t\tconst transition = workflowTransition(\n\t\t\tawait configuration.read(),\n\t\t\toutcome === undefined ? update : { ...update, outcome },\n\t\t)\n\t\tif (transition.kind === 'applied')\n\t\t\tawait configuration.write(expectedGeneration, transition.state)\n\t\treturn transition\n\t}\n\treturn {\n\t\tasync callback(\n\t\t\texpectedGeneration: number,\n\t\t\tnativeStatus: WorkflowNativeStatus,\n\t\t\toutcome?: WorkflowOutcome<Result, Failure>,\n\t\t) {\n\t\t\tawait configuration.authorize()\n\t\t\treturn apply(expectedGeneration, nativeStatus, outcome)\n\t\t},\n\t\tasync reconcile(expectedGeneration: number) {\n\t\t\tawait configuration.authorize()\n\t\t\treturn apply(\n\t\t\t\texpectedGeneration,\n\t\t\t\tawait configuration.nativeStatus(),\n\t\t\t\tawait configuration.receiptOutcome(),\n\t\t\t)\n\t\t},\n\t\tasync cancel(expectedGeneration: number) {\n\t\t\tawait configuration.authorize()\n\t\t\tconst current = await configuration.read()\n\t\t\tconst transition = workflowCancel(current, expectedGeneration)\n\t\t\tif (transition.kind === 'applied' && current.status === 'running') {\n\t\t\t\tawait configuration.cancelNative()\n\t\t\t\tawait configuration.write(expectedGeneration, transition.state)\n\t\t\t}\n\t\t\treturn transition\n\t\t},\n\t\tasync restart(expectedGeneration: number) {\n\t\t\tawait configuration.authorize()\n\t\t\tconst current = await configuration.read()\n\t\t\tif (current.generation !== expectedGeneration)\n\t\t\t\treturn { kind: 'ignored' as const, state: current }\n\t\t\tconst state = workflowRestart(current)\n\t\t\tawait configuration.restartNative()\n\t\t\tawait configuration.write(expectedGeneration, state)\n\t\t\treturn { kind: 'applied' as const, state }\n\t\t},\n\t}\n}\nfunction generation(value: number): void {\n\tif (!Number.isSafeInteger(value) || value < 0)\n\t\tthrow new WorkflowBindingError('Invalid host execution generation')\n}\n"],"mappings":"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"}
+{"version":3,"file":"workflow.mjs","names":["WorkflowBindingError","message","fields","descriptorBounds","workflowExecution","value","field","descriptor","canonicalConvexBytes","workflowBinding","compatibleVersions","binding","version","snapshot","runWorkflowStep","runner","step","execution","input","versions","nativeOptions","options","output","workflowDecode","decoded","decodeContract","schema","workflowAttempt","authority","configuration","receiptWorkflowMutation","adapter","preparation","workflowReceiptInvocation","captureIdempotencyInvocation","terminalWorkflowAttempt","error","terminal","safeFailure","workflowTransition","generation","current","update","nativeStatus","outcome","status","state","workflowCancel","expectedGeneration","workflowRestart","workflowStatusBindings","apply","transition"],"sources":["../../../src/modules/contracts/workflow.ts"],"sourcesContent":["import type { FunctionReference, FunctionVisibility, FunctionType } from 'convex/server'\nimport type { WorkflowCtx } from '@convex-dev/workflow'\nimport {\n\tdecodeContract,\n\ttype ContractInput,\n\ttype ContractOutput,\n\ttype NeutralSchema,\n} from './contract'\nimport {\n\tcanonicalConvexBytes,\n\tcaptureIdempotencyInvocation,\n\ttype CanonicalConvexBounds,\n\ttype IdempotencyInvocation,\n\ttype IdempotencyPreparation,\n} from './idempotency'\n\nexport class WorkflowBindingError extends Error {\n\treadonly _tag = 'WorkflowBindingError'\n\tconstructor(message: string) {\n\t\tsuper(message)\n\t\tthis.name = 'WorkflowBindingError'\n\t}\n}\nexport interface WorkflowExecution<Args = unknown> {\n\treadonly version: 1\n\treadonly operation: string\n\treadonly operationVersion: string\n\treadonly contractVersion: string\n\treadonly bindingVersion: string\n\t/** Host-issued business-run identity. Recovery preserves it. */\n\treadonly run: string\n\t/** Opaque host capability; never caller-supplied principal or tenant authority. */\n\treadonly capability: string\n\t/** Logical occurrence, distinct for each repeated loop step. */\n\treadonly occurrence: string\n\treadonly args: Args\n}\nexport type WorkflowStepArguments<Args> = { execution: WorkflowExecution<Args> }\nconst fields = [\n\t'version',\n\t'operation',\n\t'operationVersion',\n\t'contractVersion',\n\t'bindingVersion',\n\t'run',\n\t'capability',\n\t'occurrence',\n\t'args',\n] as const\nconst descriptorBounds = {\n\tmaxDepth: 64,\n\tmaxNodes: 100000,\n\tmaxBytes: 1000000,\n\tmaxArrayLength: 100000,\n\tmaxObjectFields: 100000,\n}\n/** Strict plain, versioned transport. Validity does not confer authority; the host resolves capability anew. */\n/* oxlint-disable anti-slop/no-unknown-parameters, anti-slop/no-runtime-typeof -- This decoder validates an untrusted execution descriptor before it enters the native workflow boundary. */\nexport function workflowExecution<Args>(value: WorkflowExecution<Args>): WorkflowExecution<Args>\nexport function workflowExecution(value: unknown): WorkflowExecution\nexport function workflowExecution(value: unknown): WorkflowExecution {\n\tif (\n\t\t!value ||\n\t\ttypeof value !== 'object' ||\n\t\tObject.getPrototypeOf(value) !== Object.prototype ||\n\t\tReflect.ownKeys(value).length !== fields.length ||\n\t\tfields.some((field) => !Object.hasOwn(value, field))\n\t)\n\t\tthrow new WorkflowBindingError('Execution requires exact plain descriptor fields')\n\t// SAFETY: the exact field set is checked above; values and accessors are checked before use below.\n\tconst descriptor = value as WorkflowExecution\n\tfor (const field of fields)\n\t\tif (!('value' in Object.getOwnPropertyDescriptor(value, field)!))\n\t\t\tthrow new WorkflowBindingError('Execution cannot contain accessors')\n\tif (\n\t\tdescriptor.version !== 1 ||\n\t\tfields\n\t\t\t.filter((field) => field !== 'version' && field !== 'args')\n\t\t\t.some((field) => typeof descriptor[field] !== 'string' || descriptor[field].length === 0)\n\t)\n\t\tthrow new WorkflowBindingError('Invalid execution descriptor version or identity')\n\ttry {\n\t\tcanonicalConvexBytes(descriptor.args, descriptorBounds)\n\t} catch {\n\t\tthrow new WorkflowBindingError('Execution args require plain Convex data')\n\t}\n\treturn descriptor\n}\n/* oxlint-enable anti-slop/no-unknown-parameters, anti-slop/no-runtime-typeof */\nexport interface WorkflowBinding<\n\tKind extends FunctionType,\n\tArgs extends NeutralSchema,\n\tResult extends NeutralSchema,\n> {\n\treadonly kind: Kind\n\treadonly operation: string\n\treadonly operationVersion: string\n\treadonly contractVersion: string\n\treadonly bindingVersion: string\n\treadonly args: Args\n\treadonly result: Result\n\treadonly reference: FunctionReference<\n\t\tNoInfer<Kind>,\n\t\tFunctionVisibility,\n\t\tWorkflowStepArguments<NoInfer<ContractInput<Args>>>,\n\t\tNoInfer<ContractInput<Result>>\n\t>\n\t/** Host explicitly lists deployed descriptor versions whose semantics remain compatible. */\n\treadonly compatibleVersions?: readonly {\n\t\toperationVersion: string\n\t\tcontractVersion: string\n\t\tbindingVersion: string\n\t}[]\n}\n/** Both phantom reference args and results must match the explicit wire contracts. */\nexport function workflowBinding<\n\tKind extends FunctionType,\n\tconst Args extends NeutralSchema,\n\tconst Result extends NeutralSchema,\n>(binding: WorkflowBinding<Kind, Args, Result>): WorkflowBinding<Kind, Args, Result> {\n\tconst compatibleVersions = binding.compatibleVersions?.map((version) =>\n\t\tObject.freeze({ ...version }),\n\t)\n\tconst snapshot = { ...binding }\n\tif (compatibleVersions !== undefined)\n\t\tsnapshot.compatibleVersions = Object.freeze(compatibleVersions)\n\treturn Object.freeze(snapshot)\n}\nexport type WorkflowStepOptions = {\n\tname?: string\n\tretry?: NonNullable<Parameters<WorkflowCtx['withOptions']>[0]['retry']>\n} & (\n\t| { inline?: false; runAt?: number; runAfter?: number }\n\t| { inline: true; runAt?: never; runAfter?: never }\n)\n/** A structural seam allows invocation-scoped native WorkflowCtx without creating another durability runtime. */\nexport interface WorkflowStepRunner {\n\t/* oxlint-disable anti-slop/no-unknown-returns -- Native runner results stay opaque here; runWorkflowStep correlates them with the binding's raw result contract without replay decoding. */\n\trunQuery?: (\n\t\treference: FunctionReference<'query', FunctionVisibility>,\n\t\targs: WorkflowStepArguments<unknown>,\n\t\toptions?: WorkflowStepOptions,\n\t) => Promise<unknown>\n\trunMutation?: (\n\t\treference: FunctionReference<'mutation', FunctionVisibility>,\n\t\targs: WorkflowStepArguments<unknown>,\n\t\toptions?: WorkflowStepOptions,\n\t) => Promise<unknown>\n\trunAction?: (\n\t\treference: FunctionReference<'action', FunctionVisibility>,\n\t\targs: WorkflowStepArguments<unknown>,\n\t\toptions?: WorkflowStepOptions,\n\t) => Promise<unknown>\n\t/* oxlint-enable anti-slop/no-unknown-returns */\n}\nexport async function runWorkflowStep<\n\tKind extends FunctionType,\n\tArgs extends NeutralSchema,\n\tResult extends NeutralSchema,\n>(\n\tstep: WorkflowCtx | WorkflowStepRunner,\n\tbinding: WorkflowBinding<Kind, Args, Result>,\n\tinput: WorkflowExecution<ContractInput<Args>>,\n\toptions: WorkflowStepOptions = {},\n): Promise<ContractInput<Result>> {\n\t// SAFETY: each binding has nonempty, checked generated args. Native ArgsAndOptions' empty-args overload is never selected.\n\tconst runner = step as WorkflowStepRunner\n\tconst execution = workflowExecution(input)\n\tconst versions = [binding, ...(binding.compatibleVersions ?? [])]\n\tif (\n\t\texecution.operation !== binding.operation ||\n\t\t!versions.some(\n\t\t\t(version) =>\n\t\t\t\tversion.operationVersion === execution.operationVersion &&\n\t\t\t\tversion.contractVersion === execution.contractVersion &&\n\t\t\t\tversion.bindingVersion === execution.bindingVersion,\n\t\t)\n\t)\n\t\tthrow new WorkflowBindingError('Incompatible workflow operation version')\n\tconst nativeOptions = {\n\t\t...options,\n\t\tname: options.name ?? `${execution.operation}:${execution.occurrence}`,\n\t}\n\tlet output: unknown\n\tswitch (binding.kind) {\n\t\tcase 'query':\n\t\t\tif (!runner.runQuery) throw new WorkflowBindingError('Native query runner missing')\n\t\t\t// SAFETY: the checked binding kind selects this exact native reference kind.\n\t\t\toutput = await runner.runQuery(\n\t\t\t\tbinding.reference as FunctionReference<'query', FunctionVisibility>,\n\t\t\t\t{ execution },\n\t\t\t\tnativeOptions,\n\t\t\t)\n\t\t\tbreak\n\t\tcase 'mutation':\n\t\t\tif (!runner.runMutation) throw new WorkflowBindingError('Native mutation runner missing')\n\t\t\t// SAFETY: the checked binding kind selects this exact native reference kind.\n\t\t\toutput = await runner.runMutation(\n\t\t\t\tbinding.reference as FunctionReference<'mutation', FunctionVisibility>,\n\t\t\t\t{ execution },\n\t\t\t\tnativeOptions,\n\t\t\t)\n\t\t\tbreak\n\t\tcase 'action':\n\t\t\tif (!runner.runAction) throw new WorkflowBindingError('Native action runner missing')\n\t\t\tif (options.inline) throw new WorkflowBindingError('Actions cannot execute inline')\n\t\t\t// SAFETY: the checked binding kind selects this exact native reference kind.\n\t\t\toutput = await runner.runAction(\n\t\t\t\tbinding.reference as FunctionReference<'action', FunctionVisibility>,\n\t\t\t\t{ execution },\n\t\t\t\t{ ...nativeOptions, retry: options.retry ?? false },\n\t\t\t)\n\t\t\tbreak\n\t}\n\t// Native validators own wire validation. Replaying workflow code must not rerun transforms.\n\t// SAFETY: the binding correlates the generated reference's result with this raw wire contract.\n\treturn output as ContractInput<Result>\n}\nexport async function workflowDecode<S extends NeutralSchema>(\n\tschema: S,\n\t// oxlint-disable-next-line anti-slop/no-unknown-parameters -- The schema parses retained or native transport values at this boundary.\n\tvalue: unknown,\n): Promise<ContractOutput<S>> {\n\tconst decoded = await decodeContract(schema, value)\n\tif (decoded.issues) throw new WorkflowBindingError('Workflow contract validation failed')\n\treturn decoded.value\n}\ntype Ordinary<A> = A | PromiseLike<A>\n/** This helper belongs inside a registered native function, never in the replaying workflow handler. */\nexport function workflowAttempt<Args, Authority, Result>(configuration: {\n\tauthorize: (execution: WorkflowExecution<Args>) => Ordinary<Authority>\n\texecute: (execution: WorkflowExecution<Args>, authority: Authority) => Ordinary<Result>\n}) {\n\treturn async (input: WorkflowExecution<Args>): Promise<Result> => {\n\t\tconst execution = workflowExecution(input)\n\t\tconst authority = await configuration.authorize(execution)\n\t\treturn configuration.execute(execution, authority)\n\t}\n}\nexport type WorkflowOutcome<Result = unknown, Failure = unknown> =\n\t| { readonly version: 1; readonly kind: 'succeeded'; readonly value: Result }\n\t| { readonly version: 1; readonly kind: 'failed'; readonly error: Failure }\ndeclare const protectedMutation: unique symbol\nexport interface ReceiptProtectedWorkflowMutation<Args, Result> {\n\treadonly [protectedMutation]: { args: Args; result: Result }\n\treadonly handler: (execution: WorkflowExecution<Args>) => Promise<Result>\n}\nexport interface WorkflowReceiptAdapter<S extends NeutralSchema> {\n\treadonly replayResult: S\n\treadonly prepare: (\n\t\tinvocation: IdempotencyInvocation,\n\t) => Promise<IdempotencyPreparation<ContractOutput<S>>>\n}\n/** Host registers this handler as the inner native mutation. All callbacks share its transaction. */\nexport function receiptWorkflowMutation<\n\tArgs,\n\tAuthority,\n\tconst Replay extends NeutralSchema,\n>(configuration: {\n\tauthorize: (execution: WorkflowExecution<Args>) => Ordinary<Authority>\n\treceipt: (authority: Authority) => WorkflowReceiptAdapter<Replay>\n\tinvocation: (execution: WorkflowExecution<Args>, authority: Authority) => IdempotencyInvocation\n\texecute: (\n\t\texecution: WorkflowExecution<Args>,\n\t\tauthority: Authority,\n\t) => Ordinary<ContractOutput<Replay>>\n}): ReceiptProtectedWorkflowMutation<Args, ContractOutput<Replay>> {\n\tconst handler = workflowAttempt({\n\t\tauthorize: configuration.authorize,\n\t\texecute: async (execution: WorkflowExecution<Args>, authority: Authority) => {\n\t\t\tconst adapter = configuration.receipt(authority)\n\t\t\tconst preparation = await adapter.prepare(configuration.invocation(execution, authority))\n\t\t\tif (preparation.kind === 'replay')\n\t\t\t\treturn workflowDecode(adapter.replayResult, preparation.result)\n\t\t\tconst value = await configuration.execute(execution, authority)\n\t\t\tawait preparation.complete(value)\n\t\t\treturn value\n\t\t},\n\t})\n\t// SAFETY: the private type evidence can only be issued by this receipt-protected helper.\n\treturn { handler } as ReceiptProtectedWorkflowMutation<Args, ContractOutput<Replay>>\n}\nexport function workflowReceiptInvocation(\n\texecution: WorkflowExecution,\n\toptions: { scope: string; fingerprintPolicy: string; bounds: CanonicalConvexBounds },\n): IdempotencyInvocation {\n\tconst descriptor = workflowExecution(execution)\n\treturn captureIdempotencyInvocation({\n\t\tbinding: { kind: 'mutation', atomicity: 'same-mutation' },\n\t\tidentity: {\n\t\t\toperation: descriptor.operation,\n\t\t\tscope: options.scope,\n\t\t\tkey: JSON.stringify([descriptor.run, descriptor.occurrence]),\n\t\t},\n\t\tversions: {\n\t\t\toperation: descriptor.operationVersion,\n\t\t\tcontract: descriptor.contractVersion,\n\t\t\tbinding: descriptor.bindingVersion,\n\t\t\tfingerprintPolicy: options.fingerprintPolicy,\n\t\t},\n\t\trawInput: descriptor.args,\n\t\tcanonical: { bounds: options.bounds },\n\t})\n}\ntype TerminalMode<Args> =\n\t| {\n\t\t\tkind: 'mutation'\n\t\t\t/** Assertion supplied only after host native rollback/journaling acceptance. */ atomicJournalProof: 'host-verified'\n\t  }\n\t| { kind: 'action'; protectedMutation: ReceiptProtectedWorkflowMutation<Args, unknown> }\n/** The native inner mutation rejection must cross its transaction boundary before terminal mapping. */\nexport function terminalWorkflowAttempt<\n\tArgs,\n\tAuthority,\n\tconst Result extends NeutralSchema,\n\tconst Failure extends NeutralSchema,\n>(\n\tconfiguration: TerminalMode<Args> & {\n\t\tauthorize: (execution: WorkflowExecution<Args>) => Ordinary<Authority>\n\t\tinvokeMutation: (\n\t\t\texecution: WorkflowExecution<Args>,\n\t\t\tauthority: Authority,\n\t\t) => Promise<ContractInput<Result>>\n\t\t// oxlint-disable-next-line anti-slop/no-unknown-parameters -- Native thrown values are classified by the host before validating the terminal failure contract.\n\t\tterminal: (error: unknown) => Ordinary<ContractInput<Failure> | undefined>\n\t\tresult: Result\n\t\tfailure: Failure\n\t},\n) {\n\treturn workflowAttempt({\n\t\tauthorize: configuration.authorize,\n\t\texecute: async (\n\t\t\texecution: WorkflowExecution<Args>,\n\t\t\tauthority: Authority,\n\t\t): Promise<WorkflowOutcome<ContractInput<Result>, ContractOutput<Failure>>> => {\n\t\t\tlet value: ContractInput<Result>\n\t\t\ttry {\n\t\t\t\tvalue = await configuration.invokeMutation(execution, authority)\n\t\t\t} catch (error) {\n\t\t\t\tconst terminal = await configuration.terminal(error)\n\t\t\t\tif (terminal === undefined) throw error\n\t\t\t\tconst safeFailure = await workflowDecode(configuration.failure, terminal)\n\t\t\t\tcanonicalConvexBytes(safeFailure, descriptorBounds)\n\t\t\t\treturn { version: 1, kind: 'failed', error: safeFailure }\n\t\t\t}\n\t\t\tawait workflowDecode(configuration.result, value)\n\t\t\tcanonicalConvexBytes(value, descriptorBounds)\n\t\t\treturn { version: 1, kind: 'succeeded', value }\n\t\t},\n\t})\n}\nexport type WorkflowNativeStatus = 'running' | 'succeeded' | 'failed' | 'canceled'\nexport interface WorkflowHostState<Result = unknown, Failure = unknown> {\n\treadonly generation: number\n\treadonly status: WorkflowNativeStatus\n\treadonly nativeStatus: WorkflowNativeStatus\n\treadonly outcome?: WorkflowOutcome<Result, Failure>\n}\nexport interface WorkflowHostUpdate<Result = unknown, Failure = unknown> {\n\treadonly generation: number\n\treadonly nativeStatus: WorkflowNativeStatus\n\treadonly outcome?: WorkflowOutcome<Result, Failure>\n}\nexport type WorkflowTransition<Result = unknown, Failure = unknown> = {\n\treadonly kind: 'applied' | 'ignored'\n\treadonly state: WorkflowHostState<Result, Failure>\n}\n/** Call within a host transaction or compare-and-set. A late operation failure refines host success; cancellation and terminal native status stay fenced. */\nexport function workflowTransition<Result, Failure>(\n\tcurrent: WorkflowHostState<Result, Failure>,\n\tupdate: WorkflowHostUpdate<Result, Failure>,\n): WorkflowTransition<Result, Failure> {\n\tgeneration(current.generation)\n\tgeneration(update.generation)\n\tif (current.generation !== update.generation) return { kind: 'ignored', state: current }\n\tconst nativeStatus =\n\t\tcurrent.nativeStatus !== 'running' ? current.nativeStatus : update.nativeStatus\n\tconst outcome = current.outcome ?? update.outcome\n\tconst status =\n\t\t(current.status === 'running' || current.status === 'succeeded') &&\n\t\tnativeStatus === 'succeeded' &&\n\t\toutcome?.kind === 'failed'\n\t\t\t? 'failed'\n\t\t\t: current.status !== 'running'\n\t\t\t\t? current.status\n\t\t\t\t: nativeStatus\n\tconst state = { generation: current.generation, status, nativeStatus }\n\treturn { kind: 'applied', state: outcome === undefined ? state : { ...state, outcome } }\n}\nexport function workflowCancel<Result, Failure>(\n\tcurrent: WorkflowHostState<Result, Failure>,\n\texpectedGeneration: number,\n): WorkflowTransition<Result, Failure> {\n\tgeneration(expectedGeneration)\n\tif (current.generation !== expectedGeneration) return { kind: 'ignored', state: current }\n\treturn {\n\t\tkind: 'applied',\n\t\tstate: { ...current, status: current.status === 'running' ? 'canceled' : current.status },\n\t}\n}\n/** Host calls after an authorized native restart. Receipt identity remains run plus occurrence. */\nexport function workflowRestart<Result, Failure>(\n\tcurrent: WorkflowHostState<Result, Failure>,\n): WorkflowHostState<Result, Failure> {\n\tgeneration(current.generation)\n\tgeneration(current.generation + 1)\n\tconst state = {\n\t\tgeneration: current.generation + 1,\n\t\tstatus: 'running' as const,\n\t\tnativeStatus: 'running' as const,\n\t}\n\treturn current.outcome?.kind === 'succeeded' ? { ...state, outcome: current.outcome } : state\n}\n/** Host closures capture the trusted run, secured storage and manager. `write` must enforce expected generation atomically. */\nexport function workflowStatusBindings<Result, Failure>(configuration: {\n\tauthorize: () => Ordinary<void>\n\tread: () => Ordinary<WorkflowHostState<Result, Failure>>\n\twrite: (expectedGeneration: number, state: WorkflowHostState<Result, Failure>) => Ordinary<void>\n\tnativeStatus: () => Ordinary<WorkflowNativeStatus>\n\treceiptOutcome: () => Ordinary<WorkflowOutcome<Result, Failure> | undefined>\n\t/** Host calls the manager in the same transaction as its guarded state write. */\n\tcancelNative: () => Ordinary<void>\n\trestartNative: () => Ordinary<void>\n}) {\n\tasync function apply(\n\t\texpectedGeneration: number,\n\t\tnativeStatus: WorkflowNativeStatus,\n\t\toutcome?: WorkflowOutcome<Result, Failure>,\n\t) {\n\t\tconst update = { generation: expectedGeneration, nativeStatus }\n\t\tconst transition = workflowTransition(\n\t\t\tawait configuration.read(),\n\t\t\toutcome === undefined ? update : { ...update, outcome },\n\t\t)\n\t\tif (transition.kind === 'applied')\n\t\t\tawait configuration.write(expectedGeneration, transition.state)\n\t\treturn transition\n\t}\n\treturn {\n\t\tasync callback(\n\t\t\texpectedGeneration: number,\n\t\t\tnativeStatus: WorkflowNativeStatus,\n\t\t\toutcome?: WorkflowOutcome<Result, Failure>,\n\t\t) {\n\t\t\tawait configuration.authorize()\n\t\t\treturn apply(expectedGeneration, nativeStatus, outcome)\n\t\t},\n\t\tasync reconcile(expectedGeneration: number) {\n\t\t\tawait configuration.authorize()\n\t\t\treturn apply(\n\t\t\t\texpectedGeneration,\n\t\t\t\tawait configuration.nativeStatus(),\n\t\t\t\tawait configuration.receiptOutcome(),\n\t\t\t)\n\t\t},\n\t\tasync cancel(expectedGeneration: number) {\n\t\t\tawait configuration.authorize()\n\t\t\tconst current = await configuration.read()\n\t\t\tconst transition = workflowCancel(current, expectedGeneration)\n\t\t\tif (transition.kind === 'applied' && current.status === 'running') {\n\t\t\t\tawait configuration.cancelNative()\n\t\t\t\tawait configuration.write(expectedGeneration, transition.state)\n\t\t\t}\n\t\t\treturn transition\n\t\t},\n\t\tasync restart(expectedGeneration: number) {\n\t\t\tawait configuration.authorize()\n\t\t\tconst current = await configuration.read()\n\t\t\tif (current.generation !== expectedGeneration)\n\t\t\t\treturn { kind: 'ignored' as const, state: current }\n\t\t\tconst state = workflowRestart(current)\n\t\t\tawait configuration.restartNative()\n\t\t\tawait configuration.write(expectedGeneration, state)\n\t\t\treturn { kind: 'applied' as const, state }\n\t\t},\n\t}\n}\nfunction generation(value: number): void {\n\tif (!Number.isSafeInteger(value) || value < 0)\n\t\tthrow new WorkflowBindingError('Invalid host execution generation')\n}\n"],"mappings":"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"}

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

@@ -2,15 +2,15 @@ import { ErrorContract, ErrorDefinitions } from "../contracts/errors.mjs";
 import { CallbackRequirements, EffectValue } from "./operation.mjs";
 import { Context, Effect, Scope } from "effect";
 //#region src/modules/effect/api-runtime.d.ts
-type EffectApiErrorProjection = (error: unknown) => unknown;
-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 EffectApiContext = EffectApiHandlerValue<Record<string, unknown>>;
+export type EffectApiErrorProjection = (error: unknown) => unknown;
+export type EffectApiErrorContract = Pick<ErrorContract<ErrorDefinitions>, 'project'>;
+export type EffectApiHandlerValue<Value> = Value | PromiseLike<Value> | Effect.Effect<Value, unknown, unknown>;
+export type EffectApiServices = Context.Context<never> | PromiseLike<Context.Context<never>> | Effect.Effect<Context.Context<never>, unknown, Scope.Scope>;
+export type ProvidedServices<Provider> = EffectValue<Provider> extends Context.Context<infer Services> ? Services : never;
+export 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] ? {
+export type CheckedContext<Ctx, Added> = Extract<KeysOfUnion<EffectValue<Added>>, keyof Ctx> extends never ? unknown : never;
+export type EffectApiOptions<Ctx, Provider extends EffectApiServices, Added = {}> = ([ProvidedServices<Provider>] extends [never] ? {
   services?: (ctx: Ctx) => Provider;
 } : {
   services: (ctx: Ctx) => Provider;
@@ -25,14 +25,13 @@ type EffectApiOptions<Ctx, Provider extends EffectApiServices, Added = {}> = ([P
   errors?: never;
   mapError?: EffectApiErrorProjection;
 });
-type CheckedApiRequirements<Returned, Provider> = [Exclude<CallbackRequirements<NoInfer<Returned>>, ProvidedServices<Provider> | Scope.Scope>] extends [never] ? unknown : never;
+export 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: {
+export declare function wrapEffectBuilder(builder: Function, options: {
   services?: Function;
   context?: Function;
   mapError?: EffectApiErrorProjection;
   errors?: EffectApiErrorContract;
 }): Function;
 //#endregion
-export { CheckedApiRequirements, CheckedContext, EffectApiContext, EffectApiErrorContract, EffectApiErrorProjection, EffectApiHandlerValue, EffectApiOptions, EffectApiServices, ProvidedServices, wrapEffectBuilder };
 //# sourceMappingURL=api-runtime.d.mts.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, 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"}
+{"version":3,"file":"api-runtime.mjs","names":["wrapEffectBuilder","original","definition","handler","args","program","normalizeEffect","options","ctx","Context","Effect","added","additionsPrototype","originalContext","key","context","services","exit","Exit","ConvexError","projectErrorCause","reason","Cause","builder"],"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,SAAgBA,EACf,EACA,EAMW,CACX,MAAQ,IAAiD,CAExD,IAAMC,EAAW,OAAOC,GAAe,WAAaA,EAAaA,EAAW,QAEtEC,EAAU,MAAO,EAAc,GAAGC,IAAoB,CAC3D,IAAMC,EAAUC,MACfC,EAAQ,SAAWA,EAAQ,SAASC,CAAG,EAAIC,EAAQ,MAAM,CAC1D,CAAC,CAAC,KACDC,EAAO,QAAS,GACfJ,MAAuBC,EAAQ,QAAUA,EAAQ,QAAQC,CAAG,EAAI,CAAC,CAAE,CAAC,CAAC,KACpEE,EAAO,QAAS,GACfA,EAAO,SAAW,CAEjB,GAAsB,OAAOC,GAAU,WAAnCA,EACH,MAAM,MAAM,sCAAsC,EACnD,IAAMC,EAAqB,OAAO,eAAeD,CAAK,EACtD,GAAIC,IAAuB,OAAO,WAAaA,IAAuB,KACrE,MAAM,MAAM,qDAAqD,EAElE,IAAMC,EAAkBL,EACxB,IAAK,IAAMM,KAAO,QAAQ,QAAQH,CAAK,EACtC,GAAIG,KAAOD,EACV,MAAM,MAAM,qCAAqC,OAAOC,CAAG,GAAG,EAEhE,OAAOP,EAAQ,QACZ,OAAO,OAAO,OAAO,eAAeM,CAAe,EAAG,CACtD,GAAG,OAAO,0BAA0BA,CAAe,EACnD,GAAG,OAAO,0BAA0BF,CAAK,CAC1C,CAAC,EACAH,CACJ,CAAC,CACF,EACAE,EAAO,QAAS,GAAYJ,MAAsBL,EAASc,EAAS,GAAGX,CAAI,CAAC,CAAC,EAC7EM,EAAO,eAAeM,CAAQ,CAC/B,CACD,CACD,EAGMC,EAAO,MAAMP,EAAO,eACzBA,EAAO,OAAOL,CAAO,CACtB,EACA,GAAIa,EAAK,UAAUD,CAAI,EAAG,OAAOA,EAAK,MACtC,GAAIV,EAAQ,OAEX,MAAM,IAAIY,EAAYC,EAAkBb,EAAQ,OAAQU,EAAK,KAAK,CAAU,EAE7E,IAAMI,EAASJ,EAAK,MAAM,QAAQ,SAAW,EAAIA,EAAK,MAAM,QAAQ,GAAK,IAAA,GAKzE,MAJII,GAAUC,EAAM,aAAaD,CAAM,EAChCd,EAAQ,SAAWA,EAAQ,SAASc,EAAO,KAAK,EAAIA,EAAO,MAE9DA,GAAUC,EAAM,YAAYD,CAAM,EAASA,EAAO,OAC5C,MAAM,8BAA+B,CAAE,MAAOJ,EAAK,KAAM,CAAC,CACrE,EAEA,OAAOM,EAAQ,OAAOrB,GAAe,WAAaC,EAAU,CAAE,GAAGD,EAAY,SAAQ,CAAC,CACvF,CACD"}

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

@@ -20,7 +20,7 @@ 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, Added = {}, Initialized = {}> = {
+export type EffectZodApiBuilder<Kind extends 'query' | 'mutation' | 'action', CustomArgs extends PropertyValidators, CustomCtx extends object, 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;
@@ -29,7 +29,6 @@ type EffectZodApiBuilder<Kind extends 'query' | 'mutation' | 'action', CustomArg
   } & 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 = 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>;
+export declare function effectZodApiBuilder<Kind extends 'query' | 'mutation' | 'action', CustomArgs extends PropertyValidators, CustomCtx extends object, 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\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"}
+{"version":3,"file":"api-zod.mjs","names":["effectZodApiBuilder","wrapEffectBuilder","builder","options"],"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\t// Native Convex context interfaces do not declare a string index signature.\n\tCustomCtx extends object,\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 object,\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":"sDA+GA,SAAgBA,EAWf,EASA,EAYC,CAGD,OAAOC,EAAkBC,EAASC,CAAO,CAY1C"}

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

@@ -5,7 +5,7 @@ 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, Initialized = {}> = {
+export 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;
@@ -13,9 +13,8 @@ type EffectApiBuilder<Ctx, Visibility extends FunctionVisibility, Kind extends '
   } | ((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 = 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>;
+export 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>;
+export 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>;
+export 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\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"}
+{"version":3,"file":"api.mjs","names":["effectApiBuilder","wrapEffectBuilder","builder","options"],"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,SAAgBA,EACf,EACA,EAMW,CACX,OAAOC,EAAkBC,EAASC,CAAO,CAC1C"}

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

@@ -24,7 +24,7 @@ type Operation = {
   replayResult?: ContractSchema;
 };
 type Registry<Context> = Readonly<Record<string, Pick<Operation, 'input' | 'result' | 'classification' | 'handler' | 'audit'> & CheckedEffectOperation<Context>>>;
-type EffectCommandDependencies = {
+export type EffectCommandDependencies = {
   observability: Observability;
   checkPermission?: (host: never, input: {
     permission: string;
@@ -38,7 +38,7 @@ type HostCompatible<Resolve extends Resolver, Dependencies extends EffectCommand
   context: never;
 };
 type Factory<Resolve extends Resolver, Guard> = ReturnType<typeof effectOperationFactory<DomainOf<Resolve>, Record<never, never>, NoInfer<CallbackError<Guard>>, NoInfer<CallbackRequirements<Guard>>>>;
-type EffectCommandConfiguration<Resolve extends Resolver, Operations extends Registry<DomainOf<Resolve>>, Guard> = {
+export type EffectCommandConfiguration<Resolve extends Resolver, Operations extends Registry<DomainOf<Resolve>>, Guard> = {
   context: Resolve;
   operations: (define: Factory<Resolve, Guard>) => Operations & NoInfer<ValidatedEffectOperations<Operations>>;
   defaults?: {
@@ -48,7 +48,7 @@ type EffectCommandConfiguration<Resolve extends Resolver, Operations extends Reg
 type ErrorOf<Definition, Resolve, Dependencies, Guard> = EffectOperationError<Definition> | CallbackError<Resolve | Dependencies[keyof Dependencies]> | UnwrappedDefaultError<Definition, Guard>;
 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>): {
+export 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>>;
@@ -57,7 +57,6 @@ declare function createEffectCommand<Resolve extends Resolver, const Operations
   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>>;
+export 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>>;
 //#endregion
-export { EffectCommandConfiguration, EffectCommandDependencies, bindEffectCommand, createEffectCommand };
 //# sourceMappingURL=command.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"command.mjs","names":[],"sources":["../../../src/modules/effect/command.ts"],"sourcesContent":["import { Effect, Exit } from 'effect'\nimport type { AuditEntryInput } from '../../components/foundation/client'\nimport type { ContractSchema } from '../contracts/contract'\nimport {\n\tselectOperation,\n\ttype SelectedOperation,\n\ttype OperationPublicResult,\n} from '../contracts/exposure'\nimport { decodeEffectContract } from './schema'\n// oxlint-disable-next-line cvx/component-boundaries -- SAFETY: Internal optional adapter shares the Effect-free Foundation lifecycle and types without entering the Convex component deployment graph.\nimport {\n\tCommandPermissionError,\n\texecuteCommandLifecycle,\n\ttype ExecutionKind,\n\ttype LifecycleAlgebra,\n\ttype LifecyclePreparation,\n} from '../../components/foundation/modules/command/lifecycle'\n// oxlint-disable-next-line cvx/component-boundaries -- SAFETY: Internal optional adapter shares the Effect-free Foundation lifecycle and types without entering the Convex component deployment graph.\nimport type { Observability } from '../../components/foundation/modules/observability/observability'\nimport { normalizeEffect, observationFailure } from './normalize'\nimport {\n\teffectOperationFactory,\n\ttype CallbackError,\n\ttype CallbackRequirements,\n\ttype EffectValue,\n\ttype EffectOperationArgument,\n\ttype EffectOperationInput,\n\ttype EffectOperationHandlerResult,\n\ttype EffectPreparation,\n\ttype EffectOperationResult,\n\ttype EffectOperationError,\n\ttype EffectOperationRequirements,\n\ttype CheckedEffectOperation,\n\ttype UnwrappedDefaultError,\n\ttype UnwrappedDefaultRequirements,\n\ttype ValidatedEffectOperations,\n} from './operation'\n\ntype Supported<Value> = Value | PromiseLike<Value> | Effect.Effect<Value, unknown, unknown>\n// Heterogeneous storage constraints preserve concrete callbacks in inferred definitions.\n// oxlint-disable-next-line anti-slop/no-unknown-returns -- Internal callback storage; selected definitions retain concrete return contracts.\ntype Callback = (...arguments_: never[]) => Supported<unknown>\n// oxlint-disable-next-line anti-slop/no-unknown-returns -- Resolver constraint captures its concrete return in Resolve; it never exposes this storage type at exec.\ntype Resolver = (host: never) => Supported<unknown>\ntype HostOf<Resolve extends Resolver> = Parameters<Resolve>[0]\ntype DomainOf<Resolve extends Resolver> = EffectValue<ReturnType<Resolve>>\ntype Operation = {\n\tinput: ContractSchema\n\tresult: ContractSchema\n\tclassification: string\n\thandler: Callback\n\taudit: Callback\n\tguard?: Callback\n\tprepare?: Callback\n\tmiddleware?: Callback\n\tpermission?: string\n\taggregates?: readonly string[]\n\treplayResult?: ContractSchema\n}\ntype Registry<Context> = Readonly<\n\tRecord<\n\t\tstring,\n\t\tPick<Operation, 'input' | 'result' | 'classification' | 'handler' | 'audit'> &\n\t\t\tCheckedEffectOperation<Context>\n\t>\n>\nexport type EffectCommandDependencies = {\n\tobservability: Observability\n\tcheckPermission?: (\n\t\thost: never,\n\t\tinput: { permission: string; operation: string },\n\t) => Supported<void>\n\t// oxlint-disable-next-line anti-slop/no-unknown-returns -- Audit writer storage; its concrete return/error/services remain in Dependencies.\n\twriteAudit: (host: never, entry: AuditEntryInput) => Supported<unknown>\n}\ntype HostParameter<Policy> = [Exclude<Policy, undefined>] extends [never]\n\t? unknown\n\t: // oxlint-disable-next-line anti-slop/no-unknown-returns -- Conditional parameter-extraction predicate, not an executable callback contract.\n\t\tExclude<Policy, undefined> extends (...arguments_: infer Arguments) => Supported<unknown>\n\t\t? Arguments extends []\n\t\t\t? unknown\n\t\t\t: Arguments[0]\n\t\t: unknown\ntype PolicyHost<Dependencies extends EffectCommandDependencies> = HostParameter<\n\tDependencies['writeAudit']\n> &\n\tHostParameter<Dependencies['checkPermission']>\ntype HostCompatible<Resolve extends Resolver, Dependencies extends EffectCommandDependencies> = [\n\tHostOf<Resolve>,\n] extends [PolicyHost<Dependencies>]\n\t? unknown\n\t: { context: never }\ntype Factory<Resolve extends Resolver, Guard> = ReturnType<\n\ttypeof effectOperationFactory<\n\t\tDomainOf<Resolve>,\n\t\tRecord<never, never>,\n\t\tNoInfer<CallbackError<Guard>>,\n\t\tNoInfer<CallbackRequirements<Guard>>\n\t>\n>\nexport type EffectCommandConfiguration<\n\tResolve extends Resolver,\n\tOperations extends Registry<DomainOf<Resolve>>,\n\tGuard,\n> = {\n\tcontext: Resolve\n\toperations: (\n\t\tdefine: Factory<Resolve, Guard>,\n\t) => Operations & NoInfer<ValidatedEffectOperations<Operations>>\n\tdefaults?: { guard?: (context: DomainOf<Resolve>) => Guard }\n}\ntype ErrorOf<Definition, Resolve, Dependencies, Guard> =\n\t| EffectOperationError<Definition>\n\t| CallbackError<Resolve | Dependencies[keyof Dependencies]>\n\t| UnwrappedDefaultError<Definition, Guard>\ntype RequirementsOf<Definition, Resolve, Dependencies, Guard> =\n\t| EffectOperationRequirements<Definition>\n\t| CallbackRequirements<Resolve | Dependencies[keyof Dependencies]>\n\t| UnwrappedDefaultRequirements<Definition, Guard>\ninterface EffectExecution extends ExecutionKind {\n\treadonly type: Effect.Effect<this['value'], unknown, unknown>\n}\nconst effectLifecycle: LifecycleAlgebra<EffectExecution> = {\n\tsucceed: Effect.succeed,\n\tsuspend: Effect.suspend,\n\tflatMap: Effect.flatMap,\n}\ntype RuntimeOperation<Context, Input, Raw, Result> = {\n\tinput: ContractSchema\n\tresult: ContractSchema\n\tclassification: string\n\tpermission?: string\n\taggregates?: readonly string[]\n\treplayResult?: ContractSchema\n\thandler: (input: Input, context: Context) => Supported<Raw>\n\tguard?: (context: Context, input: Input) => Supported<void>\n\tprepare?: (\n\t\tcontext: Context,\n\t\tinput: Input,\n\t) => Supported<EffectPreparation<Result, unknown, unknown>>\n\taudit: (\n\t\tresolution: { command: Input; result: Result },\n\t\tcontext: Context,\n\t) => Supported<Omit<AuditEntryInput, 'classification'> | null>\n\tmiddleware?: (input: {\n\t\toperation: string\n\t\tcommand: Input\n\t\tinput: Input\n\t\tcontext: Context\n\t\tnext: (options?: { context?: object }) => Effect.Effect<Raw, unknown, unknown>\n\t}) => Supported<Raw>\n}\n\n/** Internal registry constructor: the public Foundation binds host policies once. */\nexport function createEffectCommand<\n\tResolve extends Resolver,\n\tconst Operations extends Registry<DomainOf<Resolve>>,\n\tconst Dependencies extends EffectCommandDependencies,\n\tGuard = never,\n>(\n\tconfiguration: EffectCommandConfiguration<Resolve, Operations, Guard> &\n\t\tDependencies &\n\t\tHostCompatible<Resolve, Dependencies>,\n) {\n\tconst operations: Operations =\n\t\tconfiguration.operations(\n\t\t\teffectOperationFactory<\n\t\t\t\tDomainOf<Resolve>,\n\t\t\t\tRecord<never, never>,\n\t\t\t\tCallbackError<Guard>,\n\t\t\t\tCallbackRequirements<Guard>\n\t\t\t>(),\n\t\t)\n\tconst exec = <Key extends Extract<keyof Operations, string>>(\n\t\toperation: Key,\n\t\tinput: EffectOperationArgument<Operations[Key]>,\n\t\thost: HostOf<Resolve>,\n\t): Effect.Effect<\n\t\tEffectOperationResult<Operations[Key]>,\n\t\tErrorOf<Operations[Key], Resolve, Dependencies, Guard>,\n\t\tRequirementsOf<Operations[Key], Resolve, Dependencies, Guard>\n\t> => {\n\t\tconst execution = Effect.suspend(() => {\n\t\t\tif (!Object.prototype.hasOwnProperty.call(operations, operation))\n\t\t\t\tthrow Error('The selected command operation is not configured')\n\t\t\t// SAFETY: this helper checked selected callbacks against their parsed schemas and domain context.\n\t\t\tconst definition = operations[operation] as Operations[Key] &\n\t\t\t\tRuntimeOperation<\n\t\t\t\t\tDomainOf<Resolve>,\n\t\t\t\t\tEffectOperationInput<Operations[Key]>,\n\t\t\t\t\tEffectOperationHandlerResult<Operations[Key]>,\n\t\t\t\t\tEffectOperationResult<Operations[Key]>\n\t\t\t\t>\n\t\t\t// SAFETY: selected command input was parsed by its own paired schema.\n\t\t\treturn Effect.flatMap(decodeEffectContract(definition.input, input), (decoded) => {\n\t\t\t\t// SAFETY: the selected operation's decoder owns this concrete domain input.\n\t\t\t\tconst command = decoded as EffectOperationInput<Operations[Key]>\n\t\t\t\tconst observation = configuration.observability.start({\n\t\t\t\t\toperation,\n\t\t\t\t\tclassification: definition.classification,\n\t\t\t\t})\n\t\t\t\t// SAFETY: resolver identity owns its concrete invocation return and host parameter.\n\t\t\t\tconst resolve = configuration.context as (host: HostOf<Resolve>) => ReturnType<Resolve>\n\t\t\t\treturn normalizeEffect(() => resolve(host)).pipe(\n\t\t\t\t\tEffect.flatMap((context) => {\n\t\t\t\t\t\tconst lifecycle = executeCommandLifecycle<\n\t\t\t\t\t\t\tEffectExecution,\n\t\t\t\t\t\t\tDomainOf<Resolve>,\n\t\t\t\t\t\t\tEffectOperationInput<Operations[Key]>,\n\t\t\t\t\t\t\tEffectOperationHandlerResult<Operations[Key]>,\n\t\t\t\t\t\t\tEffectOperationResult<Operations[Key]>\n\t\t\t\t\t\t>(effectLifecycle, {\n\t\t\t\t\t\t\toperation,\n\t\t\t\t\t\t\tclassification: definition.classification,\n\t\t\t\t\t\t\tcontext,\n\t\t\t\t\t\t\tcommand,\n\t\t\t\t\t\t\tpermission:\n\t\t\t\t\t\t\t\tdefinition.permission === undefined\n\t\t\t\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t\t\t\t: () =>\n\t\t\t\t\t\t\t\t\t\t\tnormalizeEffect(() => {\n\t\t\t\t\t\t\t\t\t\t\t\tif (!configuration.checkPermission)\n\t\t\t\t\t\t\t\t\t\t\t\t\tthrow new CommandPermissionError(operation)\n\t\t\t\t\t\t\t\t\t\t\t\t// SAFETY: HostCompatible proves this invocation satisfies the configured policy host.\n\t\t\t\t\t\t\t\t\t\t\t\treturn configuration.checkPermission(host as never, {\n\t\t\t\t\t\t\t\t\t\t\t\t\tpermission: definition.permission!,\n\t\t\t\t\t\t\t\t\t\t\t\t\toperation,\n\t\t\t\t\t\t\t\t\t\t\t\t})\n\t\t\t\t\t\t\t\t\t\t\t}).pipe(Effect.asVoid),\n\t\t\t\t\t\t\tprepare: () =>\n\t\t\t\t\t\t\t\tnormalizeEffect(() => definition.prepare?.(context, command)).pipe(\n\t\t\t\t\t\t\t\t\tEffect.map((preparation) => {\n\t\t\t\t\t\t\t\t\t\tif (preparation?.kind !== 'execute') return preparation\n\t\t\t\t\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\t\t\t\t\tkind: 'execute',\n\t\t\t\t\t\t\t\t\t\t\tcomplete: preparation.complete\n\t\t\t\t\t\t\t\t\t\t\t\t? (result) =>\n\t\t\t\t\t\t\t\t\t\t\t\t\t\tnormalizeEffect(() => preparation.complete!(result)).pipe(\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\tEffect.asVoid,\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t\t\t\t\t\t: undefined,\n\t\t\t\t\t\t\t\t\t\t} satisfies LifecyclePreparation<\n\t\t\t\t\t\t\t\t\t\t\tEffectExecution,\n\t\t\t\t\t\t\t\t\t\t\tEffectOperationResult<Operations[Key]>\n\t\t\t\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t// SAFETY: the selected final replay contract owns this result; operation types retain its E/R.\n\t\t\t\t\t\t\tdecodeReplay: (value) =>\n\t\t\t\t\t\t\t\tdecodeEffectContract(\n\t\t\t\t\t\t\t\t\tdefinition.replayResult ?? definition.result,\n\t\t\t\t\t\t\t\t\tvalue,\n\t\t\t\t\t\t\t\t) as Effect.Effect<EffectOperationResult<Operations[Key]>, unknown, unknown>,\n\t\t\t\t\t\t\tmiddleware: definition.middleware\n\t\t\t\t\t\t\t\t? [\n\t\t\t\t\t\t\t\t\t\t(input_) =>\n\t\t\t\t\t\t\t\t\t\t\tnormalizeCommandResult(() =>\n\t\t\t\t\t\t\t\t\t\t\t\tdefinition.middleware!({ ...input_, input: command }),\n\t\t\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t\t]\n\t\t\t\t\t\t\t\t: [],\n\t\t\t\t\t\t\tdefaultGuard: (enriched) =>\n\t\t\t\t\t\t\t\tnormalizeEffect(() => configuration.defaults?.guard?.(enriched)).pipe(\n\t\t\t\t\t\t\t\t\tEffect.asVoid,\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\tguard: (enriched) =>\n\t\t\t\t\t\t\t\tnormalizeEffect(() => definition.guard?.(enriched, command)).pipe(Effect.asVoid),\n\t\t\t\t\t\t\trun: (enriched) =>\n\t\t\t\t\t\t\t\tnormalizeCommandResult(() => definition.handler(command, enriched)),\n\t\t\t\t\t\t\t// SAFETY: the selected contract owns the decoded result; the public operation retains decoder E/R.\n\t\t\t\t\t\t\tdecodeResult: (value) =>\n\t\t\t\t\t\t\t\tdecodeEffectContract(definition.result, value) as Effect.Effect<\n\t\t\t\t\t\t\t\t\tEffectOperationResult<Operations[Key]>,\n\t\t\t\t\t\t\t\t\tunknown,\n\t\t\t\t\t\t\t\t\tunknown\n\t\t\t\t\t\t\t\t>,\n\t\t\t\t\t\t\taudit: (result) =>\n\t\t\t\t\t\t\t\tnormalizeEffect(() => definition.audit({ command, result }, context)),\n\t\t\t\t\t\t\twriteAudit: (entry) =>\n\t\t\t\t\t\t\t\tnormalizeEffect(() => {\n\t\t\t\t\t\t\t\t\t// SAFETY: HostCompatible proves this invocation satisfies the configured writer host.\n\t\t\t\t\t\t\t\t\treturn configuration.writeAudit(host as never, entry)\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\taggregates: definition.aggregates,\n\t\t\t\t\t\t})\n\t\t\t\t\t\treturn lifecycle\n\t\t\t\t\t}),\n\t\t\t\t\tEffect.onExit((exit) =>\n\t\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\t\tif (Exit.isSuccess(exit)) observation.completed()\n\t\t\t\t\t\t\telse observation.failed(observationFailure(exit.cause))\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t)\n\t\t\t})\n\t\t})\n\t\t// SAFETY: dispatch selects exactly this operation; callbacks preserve the concrete definition/policy E/R.\n\t\treturn execution as Effect.Effect<\n\t\t\tEffectOperationResult<Operations[Key]>,\n\t\t\tErrorOf<Operations[Key], Resolve, Dependencies, Guard>,\n\t\t\tRequirementsOf<Operations[Key], Resolve, Dependencies, Guard>\n\t\t>\n\t}\n\treturn {\n\t\t/** Bind invocation context without resolving it or running an operation. */\n\t\twithContext(context: HostOf<Resolve>) {\n\t\t\treturn {\n\t\t\t\texec: <Key extends Extract<keyof Operations, string>>(\n\t\t\t\t\toperation: Key,\n\t\t\t\t\tinput: EffectOperationArgument<Operations[Key]>,\n\t\t\t\t) => exec(operation, input, context),\n\t\t\t}\n\t\t},\n\t\texpose<const Owner extends symbol, const Key extends Extract<keyof Operations, string>>(\n\t\t\towner: Owner,\n\t\t\toperation: Key,\n\t\t): SelectedOperation<\n\t\t\tOwner,\n\t\t\tKey,\n\t\t\tOperations[Key]['input'],\n\t\t\tOperationPublicResult<Operations[Key]>\n\t\t> {\n\t\t\tif (!Object.hasOwn(operations, operation))\n\t\t\t\tthrow Error('The selected command operation is not configured')\n\t\t\treturn selectOperation(owner, 'mutation', operation, operations[operation])\n\t\t},\n\t\texec,\n\t}\n}\n\n/** Bind trusted application policies without exposing a loose public command kernel. */\nexport function bindEffectCommand<const Dependencies extends EffectCommandDependencies>(\n\tdependencies: Dependencies,\n) {\n\treturn function command<\n\t\tResolve extends Resolver,\n\t\tconst Operations extends Registry<DomainOf<Resolve>>,\n\t\tGuard = never,\n\t>(\n\t\tconfiguration: EffectCommandConfiguration<Resolve, Operations, Guard> &\n\t\t\tHostCompatible<Resolve, Dependencies>,\n\t): ReturnType<typeof createEffectCommand<Resolve, Operations, Dependencies, Guard>> {\n\t\treturn createEffectCommand<Resolve, Operations, Dependencies, Guard>({\n\t\t\t...configuration,\n\t\t\t...dependencies,\n\t\t})\n\t}\n}\n\nfunction normalizeCommandResult<Value>(\n\tinvoke: () => Supported<Value>,\n): Effect.Effect<Value, unknown, unknown> {\n\t// SAFETY: selected definition helper checks the callback's normalized success against the schema input.\n\treturn normalizeEffect(invoke) as Effect.Effect<Value, unknown, unknown>\n}\n"],"mappings":"6ZA0HA,MAAM,EAAqD,CAC1D,QAAS,EAAO,QAChB,QAAS,EAAO,QAChB,QAAS,EAAO,OACjB,EA4BA,SAAgB,EAMf,EAGC,CACD,IAAM,EACL,EAAc,WACb,EAKE,CACH,EACK,GACL,EACA,EACA,IAMkB,EAAO,YAAc,CACtC,GAAI,CAAC,OAAO,UAAU,eAAe,KAAK,EAAY,CAAS,EAC9D,MAAM,MAAM,kDAAkD,EAE/D,IAAM,EAAa,EAAW,GAQ9B,OAAO,EAAO,QAAQ,EAAqB,EAAW,MAAO,CAAK,EAAI,GAAY,CAEjF,IAAM,EAAU,EACV,EAAc,EAAc,cAAc,MAAM,CACrD,YACA,eAAgB,EAAW,cAC5B,CAAC,EAEK,EAAU,EAAc,QAC9B,OAAO,MAAsB,EAAQ,CAAI,CAAC,CAAC,CAAC,KAC3C,EAAO,QAAS,GACG,EAMhB,EAAiB,CAClB,YACA,eAAgB,EAAW,eAC3B,UACA,UACA,WACC,EAAW,aAAe,IAAA,GACvB,IAAA,OAEA,MAAsB,CACrB,GAAI,CAAC,EAAc,gBAClB,MAAM,IAAI,EAAuB,CAAS,EAE3C,OAAO,EAAc,gBAAgB,EAAe,CACnD,WAAY,EAAW,WACvB,WACD,CAAC,CACF,CAAC,CAAC,CAAC,KAAK,EAAO,MAAM,EACzB,YACC,MAAsB,EAAW,UAAU,EAAS,CAAO,CAAC,CAAC,CAAC,KAC7D,EAAO,IAAK,GACP,GAAa,OAAS,UACnB,CACN,KAAM,UACN,SAAU,EAAY,SAClB,GACD,MAAsB,EAAY,SAAU,CAAM,CAAC,CAAC,CAAC,KACpD,EAAO,MACR,EACA,IAAA,EACJ,EAT4C,CAa5C,CACF,EAED,aAAe,GACd,EACC,EAAW,cAAgB,EAAW,OACtC,CACD,EACD,WAAY,EAAW,WACpB,CACC,GACA,MACC,EAAW,WAAY,CAAE,GAAG,EAAQ,MAAO,CAAQ,CAAC,CACrD,CACF,EACC,CAAC,EACJ,aAAe,GACd,MAAsB,EAAc,UAAU,QAAQ,CAAQ,CAAC,CAAC,CAAC,KAChE,EAAO,MACR,EACD,MAAQ,GACP,MAAsB,EAAW,QAAQ,EAAU,CAAO,CAAC,CAAC,CAAC,KAAK,EAAO,MAAM,EAChF,IAAM,GACL,MAA6B,EAAW,QAAQ,EAAS,CAAQ,CAAC,EAEnE,aAAe,GACd,EAAqB,EAAW,OAAQ,CAAK,EAK9C,MAAQ,GACP,MAAsB,EAAW,MAAM,CAAE,UAAS,QAAO,EAAG,CAAO,CAAC,EACrE,WAAa,GACZ,MAEQ,EAAc,WAAW,EAAe,CAAK,CACpD,EACF,WAAY,EAAW,UACxB,CACe,CACf,EACD,EAAO,OAAQ,GACd,EAAO,SAAW,CACb,EAAK,UAAU,CAAI,EAAG,EAAY,UAAU,EAC3C,EAAY,OAAO,EAAmB,EAAK,KAAK,CAAC,CACvD,CAAC,CACF,CACD,CACD,CAAC,CACF,CAEe,EAMhB,MAAO,CAEN,YAAY,EAA0B,CACrC,MAAO,CACN,MACC,EACA,IACI,EAAK,EAAW,EAAO,CAAO,CACpC,CACD,EACA,OACC,EACA,EAMC,CACD,GAAI,CAAC,OAAO,OAAO,EAAY,CAAS,EACvC,MAAM,MAAM,kDAAkD,EAC/D,OAAO,EAAgB,EAAO,WAAY,EAAW,EAAW,EAAU,CAC3E,EACA,MACD,CACD,CAGA,SAAgB,EACf,EACC,CACD,OAAO,SAKN,EAEmF,CACnF,OAAO,EAA8D,CACpE,GAAG,EACH,GAAG,CACJ,CAAC,CACF,CACD,CAEA,SAAS,EACR,EACyC,CAEzC,OAAO,EAAgB,CAAM,CAC9B"}
+{"version":3,"file":"command.mjs","names":["effectLifecycle","Effect","createEffectCommand","operations","configuration","effectOperationFactory","exec","operation","definition","decodeEffectContract","input","command","decoded","observation","resolve","normalizeEffect","host","executeCommandLifecycle","CommandPermissionError","context","preparation","result","value","normalizeCommandResult","input_","enriched","entry","Exit","exit","observationFailure","selectOperation","owner","bindEffectCommand","dependencies","invoke"],"sources":["../../../src/modules/effect/command.ts"],"sourcesContent":["import { Effect, Exit } from 'effect'\nimport type { AuditEntryInput } from '../../components/foundation/client'\nimport type { ContractSchema } from '../contracts/contract'\nimport {\n\tselectOperation,\n\ttype SelectedOperation,\n\ttype OperationPublicResult,\n} from '../contracts/exposure'\nimport { decodeEffectContract } from './schema'\n// oxlint-disable-next-line cvx/component-boundaries -- SAFETY: Internal optional adapter shares the Effect-free Foundation lifecycle and types without entering the Convex component deployment graph.\nimport {\n\tCommandPermissionError,\n\texecuteCommandLifecycle,\n\ttype ExecutionKind,\n\ttype LifecycleAlgebra,\n\ttype LifecyclePreparation,\n} from '../../components/foundation/modules/command/lifecycle'\n// oxlint-disable-next-line cvx/component-boundaries -- SAFETY: Internal optional adapter shares the Effect-free Foundation lifecycle and types without entering the Convex component deployment graph.\nimport type { Observability } from '../../components/foundation/modules/observability/observability'\nimport { normalizeEffect, observationFailure } from './normalize'\nimport {\n\teffectOperationFactory,\n\ttype CallbackError,\n\ttype CallbackRequirements,\n\ttype EffectValue,\n\ttype EffectOperationArgument,\n\ttype EffectOperationInput,\n\ttype EffectOperationHandlerResult,\n\ttype EffectPreparation,\n\ttype EffectOperationResult,\n\ttype EffectOperationError,\n\ttype EffectOperationRequirements,\n\ttype CheckedEffectOperation,\n\ttype UnwrappedDefaultError,\n\ttype UnwrappedDefaultRequirements,\n\ttype ValidatedEffectOperations,\n} from './operation'\n\ntype Supported<Value> = Value | PromiseLike<Value> | Effect.Effect<Value, unknown, unknown>\n// Heterogeneous storage constraints preserve concrete callbacks in inferred definitions.\n// oxlint-disable-next-line anti-slop/no-unknown-returns -- Internal callback storage; selected definitions retain concrete return contracts.\ntype Callback = (...arguments_: never[]) => Supported<unknown>\n// oxlint-disable-next-line anti-slop/no-unknown-returns -- Resolver constraint captures its concrete return in Resolve; it never exposes this storage type at exec.\ntype Resolver = (host: never) => Supported<unknown>\ntype HostOf<Resolve extends Resolver> = Parameters<Resolve>[0]\ntype DomainOf<Resolve extends Resolver> = EffectValue<ReturnType<Resolve>>\ntype Operation = {\n\tinput: ContractSchema\n\tresult: ContractSchema\n\tclassification: string\n\thandler: Callback\n\taudit: Callback\n\tguard?: Callback\n\tprepare?: Callback\n\tmiddleware?: Callback\n\tpermission?: string\n\taggregates?: readonly string[]\n\treplayResult?: ContractSchema\n}\ntype Registry<Context> = Readonly<\n\tRecord<\n\t\tstring,\n\t\tPick<Operation, 'input' | 'result' | 'classification' | 'handler' | 'audit'> &\n\t\t\tCheckedEffectOperation<Context>\n\t>\n>\nexport type EffectCommandDependencies = {\n\tobservability: Observability\n\tcheckPermission?: (\n\t\thost: never,\n\t\tinput: { permission: string; operation: string },\n\t) => Supported<void>\n\t// oxlint-disable-next-line anti-slop/no-unknown-returns -- Audit writer storage; its concrete return/error/services remain in Dependencies.\n\twriteAudit: (host: never, entry: AuditEntryInput) => Supported<unknown>\n}\ntype HostParameter<Policy> = [Exclude<Policy, undefined>] extends [never]\n\t? unknown\n\t: // oxlint-disable-next-line anti-slop/no-unknown-returns -- Conditional parameter-extraction predicate, not an executable callback contract.\n\t\tExclude<Policy, undefined> extends (...arguments_: infer Arguments) => Supported<unknown>\n\t\t? Arguments extends []\n\t\t\t? unknown\n\t\t\t: Arguments[0]\n\t\t: unknown\ntype PolicyHost<Dependencies extends EffectCommandDependencies> = HostParameter<\n\tDependencies['writeAudit']\n> &\n\tHostParameter<Dependencies['checkPermission']>\ntype HostCompatible<Resolve extends Resolver, Dependencies extends EffectCommandDependencies> = [\n\tHostOf<Resolve>,\n] extends [PolicyHost<Dependencies>]\n\t? unknown\n\t: { context: never }\ntype Factory<Resolve extends Resolver, Guard> = ReturnType<\n\ttypeof effectOperationFactory<\n\t\tDomainOf<Resolve>,\n\t\tRecord<never, never>,\n\t\tNoInfer<CallbackError<Guard>>,\n\t\tNoInfer<CallbackRequirements<Guard>>\n\t>\n>\nexport type EffectCommandConfiguration<\n\tResolve extends Resolver,\n\tOperations extends Registry<DomainOf<Resolve>>,\n\tGuard,\n> = {\n\tcontext: Resolve\n\toperations: (\n\t\tdefine: Factory<Resolve, Guard>,\n\t) => Operations & NoInfer<ValidatedEffectOperations<Operations>>\n\tdefaults?: { guard?: (context: DomainOf<Resolve>) => Guard }\n}\ntype ErrorOf<Definition, Resolve, Dependencies, Guard> =\n\t| EffectOperationError<Definition>\n\t| CallbackError<Resolve | Dependencies[keyof Dependencies]>\n\t| UnwrappedDefaultError<Definition, Guard>\ntype RequirementsOf<Definition, Resolve, Dependencies, Guard> =\n\t| EffectOperationRequirements<Definition>\n\t| CallbackRequirements<Resolve | Dependencies[keyof Dependencies]>\n\t| UnwrappedDefaultRequirements<Definition, Guard>\ninterface EffectExecution extends ExecutionKind {\n\treadonly type: Effect.Effect<this['value'], unknown, unknown>\n}\nconst effectLifecycle: LifecycleAlgebra<EffectExecution> = {\n\tsucceed: Effect.succeed,\n\tsuspend: Effect.suspend,\n\tflatMap: Effect.flatMap,\n}\ntype RuntimeOperation<Context, Input, Raw, Result> = {\n\tinput: ContractSchema\n\tresult: ContractSchema\n\tclassification: string\n\tpermission?: string\n\taggregates?: readonly string[]\n\treplayResult?: ContractSchema\n\thandler: (input: Input, context: Context) => Supported<Raw>\n\tguard?: (context: Context, input: Input) => Supported<void>\n\tprepare?: (\n\t\tcontext: Context,\n\t\tinput: Input,\n\t) => Supported<EffectPreparation<Result, unknown, unknown>>\n\taudit: (\n\t\tresolution: { command: Input; result: Result },\n\t\tcontext: Context,\n\t) => Supported<Omit<AuditEntryInput, 'classification'> | null>\n\tmiddleware?: (input: {\n\t\toperation: string\n\t\tcommand: Input\n\t\tinput: Input\n\t\tcontext: Context\n\t\tnext: (options?: { context?: object }) => Effect.Effect<Raw, unknown, unknown>\n\t}) => Supported<Raw>\n}\n\n/** Internal registry constructor: the public Foundation binds host policies once. */\nexport function createEffectCommand<\n\tResolve extends Resolver,\n\tconst Operations extends Registry<DomainOf<Resolve>>,\n\tconst Dependencies extends EffectCommandDependencies,\n\tGuard = never,\n>(\n\tconfiguration: EffectCommandConfiguration<Resolve, Operations, Guard> &\n\t\tDependencies &\n\t\tHostCompatible<Resolve, Dependencies>,\n) {\n\tconst operations: Operations =\n\t\tconfiguration.operations(\n\t\t\teffectOperationFactory<\n\t\t\t\tDomainOf<Resolve>,\n\t\t\t\tRecord<never, never>,\n\t\t\t\tCallbackError<Guard>,\n\t\t\t\tCallbackRequirements<Guard>\n\t\t\t>(),\n\t\t)\n\tconst exec = <Key extends Extract<keyof Operations, string>>(\n\t\toperation: Key,\n\t\tinput: EffectOperationArgument<Operations[Key]>,\n\t\thost: HostOf<Resolve>,\n\t): Effect.Effect<\n\t\tEffectOperationResult<Operations[Key]>,\n\t\tErrorOf<Operations[Key], Resolve, Dependencies, Guard>,\n\t\tRequirementsOf<Operations[Key], Resolve, Dependencies, Guard>\n\t> => {\n\t\tconst execution = Effect.suspend(() => {\n\t\t\tif (!Object.prototype.hasOwnProperty.call(operations, operation))\n\t\t\t\tthrow Error('The selected command operation is not configured')\n\t\t\t// SAFETY: this helper checked selected callbacks against their parsed schemas and domain context.\n\t\t\tconst definition = operations[operation] as Operations[Key] &\n\t\t\t\tRuntimeOperation<\n\t\t\t\t\tDomainOf<Resolve>,\n\t\t\t\t\tEffectOperationInput<Operations[Key]>,\n\t\t\t\t\tEffectOperationHandlerResult<Operations[Key]>,\n\t\t\t\t\tEffectOperationResult<Operations[Key]>\n\t\t\t\t>\n\t\t\t// SAFETY: selected command input was parsed by its own paired schema.\n\t\t\treturn Effect.flatMap(decodeEffectContract(definition.input, input), (decoded) => {\n\t\t\t\t// SAFETY: the selected operation's decoder owns this concrete domain input.\n\t\t\t\tconst command = decoded as EffectOperationInput<Operations[Key]>\n\t\t\t\tconst observation = configuration.observability.start({\n\t\t\t\t\toperation,\n\t\t\t\t\tclassification: definition.classification,\n\t\t\t\t})\n\t\t\t\t// SAFETY: resolver identity owns its concrete invocation return and host parameter.\n\t\t\t\tconst resolve = configuration.context as (host: HostOf<Resolve>) => ReturnType<Resolve>\n\t\t\t\treturn normalizeEffect(() => resolve(host)).pipe(\n\t\t\t\t\tEffect.flatMap((context) => {\n\t\t\t\t\t\tconst lifecycle = executeCommandLifecycle<\n\t\t\t\t\t\t\tEffectExecution,\n\t\t\t\t\t\t\tDomainOf<Resolve>,\n\t\t\t\t\t\t\tEffectOperationInput<Operations[Key]>,\n\t\t\t\t\t\t\tEffectOperationHandlerResult<Operations[Key]>,\n\t\t\t\t\t\t\tEffectOperationResult<Operations[Key]>\n\t\t\t\t\t\t>(effectLifecycle, {\n\t\t\t\t\t\t\toperation,\n\t\t\t\t\t\t\tclassification: definition.classification,\n\t\t\t\t\t\t\tcontext,\n\t\t\t\t\t\t\tcommand,\n\t\t\t\t\t\t\tpermission:\n\t\t\t\t\t\t\t\tdefinition.permission === undefined\n\t\t\t\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t\t\t\t: () =>\n\t\t\t\t\t\t\t\t\t\t\tnormalizeEffect(() => {\n\t\t\t\t\t\t\t\t\t\t\t\tif (!configuration.checkPermission)\n\t\t\t\t\t\t\t\t\t\t\t\t\tthrow new CommandPermissionError(operation)\n\t\t\t\t\t\t\t\t\t\t\t\t// SAFETY: HostCompatible proves this invocation satisfies the configured policy host.\n\t\t\t\t\t\t\t\t\t\t\t\treturn configuration.checkPermission(host as never, {\n\t\t\t\t\t\t\t\t\t\t\t\t\tpermission: definition.permission!,\n\t\t\t\t\t\t\t\t\t\t\t\t\toperation,\n\t\t\t\t\t\t\t\t\t\t\t\t})\n\t\t\t\t\t\t\t\t\t\t\t}).pipe(Effect.asVoid),\n\t\t\t\t\t\t\tprepare: () =>\n\t\t\t\t\t\t\t\tnormalizeEffect(() => definition.prepare?.(context, command)).pipe(\n\t\t\t\t\t\t\t\t\tEffect.map((preparation) => {\n\t\t\t\t\t\t\t\t\t\tif (preparation?.kind !== 'execute') return preparation\n\t\t\t\t\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\t\t\t\t\tkind: 'execute',\n\t\t\t\t\t\t\t\t\t\t\tcomplete: preparation.complete\n\t\t\t\t\t\t\t\t\t\t\t\t? (result) =>\n\t\t\t\t\t\t\t\t\t\t\t\t\t\tnormalizeEffect(() => preparation.complete!(result)).pipe(\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\tEffect.asVoid,\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t\t\t\t\t\t: undefined,\n\t\t\t\t\t\t\t\t\t\t} satisfies LifecyclePreparation<\n\t\t\t\t\t\t\t\t\t\t\tEffectExecution,\n\t\t\t\t\t\t\t\t\t\t\tEffectOperationResult<Operations[Key]>\n\t\t\t\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t// SAFETY: the selected final replay contract owns this result; operation types retain its E/R.\n\t\t\t\t\t\t\tdecodeReplay: (value) =>\n\t\t\t\t\t\t\t\tdecodeEffectContract(\n\t\t\t\t\t\t\t\t\tdefinition.replayResult ?? definition.result,\n\t\t\t\t\t\t\t\t\tvalue,\n\t\t\t\t\t\t\t\t) as Effect.Effect<EffectOperationResult<Operations[Key]>, unknown, unknown>,\n\t\t\t\t\t\t\tmiddleware: definition.middleware\n\t\t\t\t\t\t\t\t? [\n\t\t\t\t\t\t\t\t\t\t(input_) =>\n\t\t\t\t\t\t\t\t\t\t\tnormalizeCommandResult(() =>\n\t\t\t\t\t\t\t\t\t\t\t\tdefinition.middleware!({ ...input_, input: command }),\n\t\t\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t\t]\n\t\t\t\t\t\t\t\t: [],\n\t\t\t\t\t\t\tdefaultGuard: (enriched) =>\n\t\t\t\t\t\t\t\tnormalizeEffect(() => configuration.defaults?.guard?.(enriched)).pipe(\n\t\t\t\t\t\t\t\t\tEffect.asVoid,\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\tguard: (enriched) =>\n\t\t\t\t\t\t\t\tnormalizeEffect(() => definition.guard?.(enriched, command)).pipe(Effect.asVoid),\n\t\t\t\t\t\t\trun: (enriched) =>\n\t\t\t\t\t\t\t\tnormalizeCommandResult(() => definition.handler(command, enriched)),\n\t\t\t\t\t\t\t// SAFETY: the selected contract owns the decoded result; the public operation retains decoder E/R.\n\t\t\t\t\t\t\tdecodeResult: (value) =>\n\t\t\t\t\t\t\t\tdecodeEffectContract(definition.result, value) as Effect.Effect<\n\t\t\t\t\t\t\t\t\tEffectOperationResult<Operations[Key]>,\n\t\t\t\t\t\t\t\t\tunknown,\n\t\t\t\t\t\t\t\t\tunknown\n\t\t\t\t\t\t\t\t>,\n\t\t\t\t\t\t\taudit: (result) =>\n\t\t\t\t\t\t\t\tnormalizeEffect(() => definition.audit({ command, result }, context)),\n\t\t\t\t\t\t\twriteAudit: (entry) =>\n\t\t\t\t\t\t\t\tnormalizeEffect(() => {\n\t\t\t\t\t\t\t\t\t// SAFETY: HostCompatible proves this invocation satisfies the configured writer host.\n\t\t\t\t\t\t\t\t\treturn configuration.writeAudit(host as never, entry)\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\taggregates: definition.aggregates,\n\t\t\t\t\t\t})\n\t\t\t\t\t\treturn lifecycle\n\t\t\t\t\t}),\n\t\t\t\t\tEffect.onExit((exit) =>\n\t\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\t\tif (Exit.isSuccess(exit)) observation.completed()\n\t\t\t\t\t\t\telse observation.failed(observationFailure(exit.cause))\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t)\n\t\t\t})\n\t\t})\n\t\t// SAFETY: dispatch selects exactly this operation; callbacks preserve the concrete definition/policy E/R.\n\t\treturn execution as Effect.Effect<\n\t\t\tEffectOperationResult<Operations[Key]>,\n\t\t\tErrorOf<Operations[Key], Resolve, Dependencies, Guard>,\n\t\t\tRequirementsOf<Operations[Key], Resolve, Dependencies, Guard>\n\t\t>\n\t}\n\treturn {\n\t\t/** Bind invocation context without resolving it or running an operation. */\n\t\twithContext(context: HostOf<Resolve>) {\n\t\t\treturn {\n\t\t\t\texec: <Key extends Extract<keyof Operations, string>>(\n\t\t\t\t\toperation: Key,\n\t\t\t\t\tinput: EffectOperationArgument<Operations[Key]>,\n\t\t\t\t) => exec(operation, input, context),\n\t\t\t}\n\t\t},\n\t\texpose<const Owner extends symbol, const Key extends Extract<keyof Operations, string>>(\n\t\t\towner: Owner,\n\t\t\toperation: Key,\n\t\t): SelectedOperation<\n\t\t\tOwner,\n\t\t\tKey,\n\t\t\tOperations[Key]['input'],\n\t\t\tOperationPublicResult<Operations[Key]>\n\t\t> {\n\t\t\tif (!Object.hasOwn(operations, operation))\n\t\t\t\tthrow Error('The selected command operation is not configured')\n\t\t\treturn selectOperation(owner, 'mutation', operation, operations[operation])\n\t\t},\n\t\texec,\n\t}\n}\n\n/** Bind trusted application policies without exposing a loose public command kernel. */\nexport function bindEffectCommand<const Dependencies extends EffectCommandDependencies>(\n\tdependencies: Dependencies,\n) {\n\treturn function command<\n\t\tResolve extends Resolver,\n\t\tconst Operations extends Registry<DomainOf<Resolve>>,\n\t\tGuard = never,\n\t>(\n\t\tconfiguration: EffectCommandConfiguration<Resolve, Operations, Guard> &\n\t\t\tHostCompatible<Resolve, Dependencies>,\n\t): ReturnType<typeof createEffectCommand<Resolve, Operations, Dependencies, Guard>> {\n\t\treturn createEffectCommand<Resolve, Operations, Dependencies, Guard>({\n\t\t\t...configuration,\n\t\t\t...dependencies,\n\t\t})\n\t}\n}\n\nfunction normalizeCommandResult<Value>(\n\tinvoke: () => Supported<Value>,\n): Effect.Effect<Value, unknown, unknown> {\n\t// SAFETY: selected definition helper checks the callback's normalized success against the schema input.\n\treturn normalizeEffect(invoke) as Effect.Effect<Value, unknown, unknown>\n}\n"],"mappings":"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"}

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

@@ -8,7 +8,7 @@ import { GenericId } from "convex/values";
 import { Effect } from "effect";
 //#region src/modules/effect/crud.d.ts
 /** Table masks and branded IDs come from the same kit-owned table boundary. */
-type EffectCrudTable = {
+export type EffectCrudTable = {
   tableName: string;
   commandInput: z.ZodObject<Record<string, z.ZodType>>;
   storage: z.ZodObject<Record<string, z.ZodType>>;
@@ -45,16 +45,16 @@ type StorageOverrides<Table extends EffectCrudTable> = (StorageCompatible<Input<
   };
 });
 type Supported<Value> = Value | PromiseLike<Value> | Effect.Effect<Value, unknown, unknown>;
-type EffectCrudPage<Row> = PaginationResult<Row>;
-type EffectCrudPagination = { [Key in keyof PaginationOptions]: PaginationOptions[Key]; } & {
+export type EffectCrudPage<Row> = PaginationResult<Row>;
+export type EffectCrudPagination = { [Key in keyof PaginationOptions]: PaginationOptions[Key]; } & {
   id?: number;
 };
 /** Trusted repositories receive domain context, never authority from caller arguments. */
-type EffectCrudRepository<Context, Table extends EffectCrudTable, Insert, Patch> = {
+export type EffectCrudRepository<Context, Table extends EffectCrudTable, Insert, Patch> = {
   insert: (context: Context, values: Storage<Table>) => Insert;
   patch: (context: Context, id: Id<Table>, values: Partial<Storage<Table>>) => Patch;
 };
-type EffectCrudContext<Table extends EffectCrudTable> = {
+export type EffectCrudContext<Table extends EffectCrudTable> = {
   db: {
     insert: (table: Table['tableName'], values: Storage<Table>) => Promise<Id<Table>>;
     patch: (id: Id<Table>, values: Partial<Storage<Table>>) => Promise<void>;
@@ -75,7 +75,7 @@ type CrudExecutor<Host, Operations extends Readonly<Record<string, {
 }>>, Callbacks, Guard> = {
   exec<Key extends Extract<keyof Operations, string>>(operation: Key, input: EffectOperationArgument<Operations[Key]>, host: Host): Effect.Effect<EffectOperationResult<Operations[Key]>, EffectOperationError<Operations[Key]> | CallbackError<Callbacks> | UnwrappedDefaultError<Operations[Key], Guard>, EffectOperationRequirements<Operations[Key]> | CallbackRequirements<Callbacks> | UnwrappedDefaultRequirements<Operations[Key], Guard>>;
 };
-type EffectCrudConfig<Options extends EffectFoundationOptions, Host, ContextReturned, Table extends EffectCrudTable, Actor, Enrich, Insert, Patch, Get, List, Project, Policy, CreateGuard, UpdateGuard, ArchiveGuard, GetGuard, ListGuard, CreateOverride, UpdateOverride, ArchiveOverride, CheckId = never> = {
+export type EffectCrudConfig<Options extends EffectFoundationOptions, Host, ContextReturned, Table extends EffectCrudTable, Actor, Enrich, Insert, Patch, Get, List, Project, Policy, CreateGuard, UpdateGuard, ArchiveGuard, GetGuard, ListGuard, CreateOverride, UpdateOverride, ArchiveOverride, CheckId = never> = {
   foundation: EffectFoundation<Options>;
   table: Table;
   context: (host: Host) => ContextReturned;
@@ -122,7 +122,7 @@ type EffectCrudConfig<Options extends EffectFoundationOptions, Host, ContextRetu
   checkId: (context: EffectValue<ContextReturned>, id: string) => CheckId;
 }) & StorageOverrides<Table>;
 /** Generate operations through the Foundation's bound helpers; no runner or policy lives here. */
-declare function createEffectCrud<const Options extends EffectFoundationOptions, Host extends PolicyHost<Options>, ContextReturned, const Table extends EffectCrudTable, Actor extends Supported<string>, Enrich extends Supported<Partial<Storage<Table>>> = never, Insert extends Supported<Id<Table>> = never, Patch extends Supported<void> = never, Get extends Supported<Storage<Table> | null> = never, List extends Supported<EffectCrudPage<Storage<Table>>> = never, Project extends Supported<z.input<Table['publicDto']>> = never, Policy extends Supported<void> = never, CreateGuard extends Supported<void> = never, UpdateGuard extends Supported<void> = never, ArchiveGuard extends Supported<void> = never, GetGuard extends Supported<void> = never, ListGuard extends Supported<void> = never, CreateOverride extends Supported<{
+export declare function createEffectCrud<const Options extends EffectFoundationOptions, Host extends PolicyHost<Options>, ContextReturned, const Table extends EffectCrudTable, Actor extends Supported<string>, Enrich extends Supported<Partial<Storage<Table>>> = never, Insert extends Supported<Id<Table>> = never, Patch extends Supported<void> = never, Get extends Supported<Storage<Table> | null> = never, List extends Supported<EffectCrudPage<Storage<Table>>> = never, Project extends Supported<z.input<Table['publicDto']>> = never, Policy extends Supported<void> = never, CreateGuard extends Supported<void> = never, UpdateGuard extends Supported<void> = never, ArchiveGuard extends Supported<void> = never, GetGuard extends Supported<void> = never, ListGuard extends Supported<void> = never, CreateOverride extends Supported<{
   id: Id<Table>;
 }> = never, UpdateOverride extends Supported<{
   ok: true;
@@ -781,5 +781,4 @@ type RequiredOverride<Configuration, Key extends string> = Configuration extends
 } ? true : false;
 type Chosen<Override, Default, Required extends boolean> = Required extends true ? Override : [Override] extends [never] ? Default : Override | Default;
 //#endregion
-export { EffectCrudConfig, EffectCrudContext, EffectCrudPage, EffectCrudPagination, EffectCrudRepository, EffectCrudTable, createEffectCrud };
 //# sourceMappingURL=crud.d.mts.map