better-call 0.0.0-experimental.7f728d4b

package/dist/fn.d.cts

@@ -0,0 +1,286 @@
+import { FnError } from "./error.cjs";
+import { LiteralString, Prettify } from "./types.cjs";
+import { InferArgs, InferInput, OutputSchemaOf, vTypes } from "./schema.cjs";
+import { VarDefination } from "./var.cjs";
+import { ApplyOns, Module, ModuleFns, OnEntry, TargetMatches, VarGetContext, VarSetContext, WithDerived } from "./module.cjs";
+import { ResolvedVars, ScopeOf, VarName, VarScope } from "./scope.cjs";
+//#region src/fn.d.ts
+type ParentContext = Record<string, any>;
+/** The call shape: a TUPLE input spreads - one parameter per position,
+ * the parent context last. Everything else takes (input?, parent?). */
+type CallArgs<A, I> = I extends readonly unknown[] ? A extends readonly unknown[] ? [...A] | [...A, ParentContext] : never : [A] extends [void] ? [input?: undefined, parent?: ParentContext] : [input: A, parent?: ParentContext];
+/** The union of a fn's DECLARED errors, as thrown values. */
+type FnErrorsOf<Er> = { [T in keyof Er & string]: FnError<T, InferInput<Er[T]>>; }[keyof Er & string];
+/** The declared-error union of a fn - for typing catch sites. */
+type FnErrors<F> = F extends FnDefination<any, any, any, any, any, infer Er> ? FnErrorsOf<Er> : never;
+type TryResult<R, Er> = R extends Promise<infer V> ? Promise<{
+  ok: true;
+  value: V;
+} | {
+  ok: false;
+  error: FnErrorsOf<Er>;
+}> : {
+  ok: true;
+  value: R;
+} | {
+  ok: false;
+  error: FnErrorsOf<Er>;
+};
+/** No declared errors - the default error channel. */
+type NoErrors = Record<never, never>;
+/** The `use` half of `.with`: fn overrides by name, recursing into
+ * GROUPS so a nested binding can be overridden too. A var alias takes a
+ * SEED for the var it points at. */
+type WithFns<U> = { [K in keyof U]?: U[K] extends FnDefination<any, any, any, any, any, any> ? BoundFn<U[K]> : U[K] extends VarDefination<any, infer T, any, any> ? T : WithFns<U[K]>; };
+/** The context `.with` accepts: any var of the fn's WHOLE chain scope
+ * (the builder's `use` included, not just the fn's own), plus any `use`
+ * fn as an override - and nothing else. Kept as PLAIN mapped types: with
+ * `RV`/`U` unknown both halves collapse to `{}`, which keeps every
+ * `extends FnDefination<any, ...>` structural check passing. */
+type WithContext<RV, U> = { [K in keyof RV]?: RV[K]; } & WithFns<U>;
+/** What `.with` returns: the same callable, context baked in. */
+interface BoundCall<A, R, I, Er> {
+  (...args: CallArgs<A, I>): R;
+  try(...args: CallArgs<A, I>): TryResult<R, Er>;
+}
+interface FnDefination<A, R, K extends string = string, I = unknown, P extends readonly string[] = readonly string[], Er = NoErrors, RV = unknown, U = unknown, O = unknown> {
+  (...args: CallArgs<A, I>): R;
+  /**
+   * Call with DECLARED errors caught as a value: `{ ok: true, value }`
+   * or `{ ok: false, error }`, narrowed by `error.tag`. Only tagged,
+   * expected errors become results - defects and contract violations
+   * still throw, exactly as they should.
+   */
+  try(...args: CallArgs<A, I>): TryResult<R, Er>;
+  /**
+   * Call with a HAND-BUILT context. Keys naming a var SEED that var in a
+   * fresh scope; keys naming a `use` fn OVERRIDE that binding for the
+   * whole subtree below. Both are typed from the fn's chain - what the
+   * BUILDER mounted counts, so `signOut.with({ user })` type-checks even
+   * though `signOut` itself never says `use: [user]`. A parent passed to
+   * the bound call is FORKED: its vars are copied in, never written back.
+   */
+  with(context: WithContext<RV, U>): BoundCall<A, R, I, Er>;
+  /** Brand, so a plugin module can be scanned for its fns. */
+  readonly $fn: true;
+  /** The name interceptors target - literal, so `ApplyOn` can match it. */
+  readonly key: K;
+  /** The declared contract, retained AS WRITTEN for runtime
+   * introspection (tool cards, docs renderers): the raw input/output
+   * schemas, error tag map, and required vars. Optional so structural
+   * `extends FnDefination` checks keep passing for hand-built fns. */
+  readonly $schema?: {
+    input?: unknown;
+    output?: unknown;
+    errors?: Record<string, unknown>;
+    requires?: readonly string[];
+    /** Declared idempotence - same args, same result, safe to repeat. */
+    idempotent?: boolean;
+  };
+  /** Vars this fn promises to set when ITS OWN body runs - the literal
+   * list, readable by graph tooling at both type and runtime level. */
+  readonly provides: P;
+  /** Phantom: the raw declared input, so extensions of the vars it
+   * references can widen used-fn call sites. Never set at runtime. */
+  readonly $input?: I;
+  /** Phantom: the raw declared output, the counterpart of `$input` - the
+   * schema as written, for type-level introspection. Never set at runtime. */
+  readonly $output?: O;
+  /** Phantom: declared error tags -> payload schemas. */
+  readonly $errors?: Er;
+}
+type ArgsOf<I> = I extends readonly unknown[] ? { -readonly [K in keyof I]: InferArgs<I[K]>; } : unknown extends I ? void : InferArgs<I>;
+type OptionType<I, O, P, Q, PL, RO extends boolean = boolean, Er = any> = {
+  /**
+   * The fn's DECLARED failures: tag -> payload schema. The THIRD
+   * contract door - input validates on entry, output on exit, errors at
+   * `throw c.error(tag, data)`. Once declared, any UNTAGGED throw
+   * escaping the body is a defect and comes out as `UnexpectedError` -
+   * callers can tell a domain refusal from a bug without string
+   * matching.
+   */
+  errors?: Er;
+  /**
+   * A readonly fn cannot write vars - not in its handler, not in
+   * anything it calls, not from interceptors mounted on it. Enforced at
+   * the type level (vars readonly on `c`, declared writers uncallable)
+   * and at runtime (the whole subtree's store locks).
+   */
+  readonly?: RO;
+  /**
+   * Declared idempotence: calling with the same args always produces the
+   * same result and repeating the call is harmless - a read, a lookup, a
+   * pure computation. Part of the retained contract (`$schema`), so
+   * hosts may DEDUPE calls: the script engine serves repeated
+   * same-args calls to an idempotent fn from one dispatch per session.
+   * Note this is a different promise than `readonly` (writes no vars) -
+   * an fn can be readonly and still hit a non-idempotent API.
+   */
+  idempotent?: boolean;
+  input?: I;
+  /**
+   * The fn's return contract. A bare schema is BOTH the signature and
+   * the exit check; the wrapper `{ def?, validation? }` splits them -
+   * `{ def }` documents the return (tool cards, handler typing) without
+   * runtime validation, `validation` is the schema the exit check runs
+   * (defaults to none in the wrapper form).
+   */
+  output?: O;
+  /** Vars this fn guarantees to set. Checked on exit. */
+  provides?: P;
+  /** Vars that must already be set. Checked on entry, before the body. */
+  requires?: Q;
+  /**
+   * Module namespaces to pull in. Their vars come into scope, their fns
+   * land directly on `c` already bound to this context (a plain-record
+   * member nests as a NAMESPACE: `c.cookies.setCookie`), and their `on`
+   * entries stay active for everything below.
+   */
+  use?: PL;
+};
+/** A used fn, with the parent context already applied. A tuple-input fn
+ * keeps its positional signature. */
+type BoundFn<F> = F extends FnDefination<infer A, infer R, string, infer I, any, any> ? I extends readonly unknown[] ? A extends readonly unknown[] ? (...args: [...A]) => R : never : [A] extends [void] ? () => R : (input: A) => R : never;
+/** Keys of a usable map whose member is a VAR alias. */
+type UseVarKeys<U> = { [K in keyof U]: U[K] extends VarDefination<any, any, any, any> ? K : never; }[keyof U];
+/** A var alias' surface: the var's VALUE, read and written in place. */
+type UseVarValue<V> = V extends VarDefination<any, infer T, any, any> ? T : never;
+type UseApi<U> = Prettify<{ [K in Exclude<keyof U, UseVarKeys<U>>]: U[K] extends FnDefination<any, any, any, any, any, any> ? BoundFn<U[K]> : UseApi<U[K]>; } & { [K in UseVarKeys<U>]: UseVarValue<U[K]>; }>;
+/** Used fns inside a readonly fn: declared writers become uncallable,
+ * with the reason on hover instead of a generic type error; var aliases
+ * become readonly properties. */
+type ReadUseApi<U> = Prettify<{ [K in Exclude<keyof U, UseVarKeys<U>>]: U[K] extends FnDefination<any, any, any, any, infer P, any> ? P extends readonly [] ? BoundFn<U[K]> : `writes "${P[number] & string}" - not callable from a readonly fn` : ReadUseApi<U[K]>; } & { readonly [K in UseVarKeys<U>]: UseVarValue<U[K]>; }>;
+type Context<I, RV, Required, U = unknown, FnApi = Fn, RO extends boolean = false, Errs = NoErrors> = {
+  input: InferInput<I>;
+  /**
+   * Mint a DECLARED error - tag-checked, payload validated at creation:
+   * `throw c.error("invalid_credentials", { attempts: 3 })`. Only tags
+   * from this fn's `errors` exist; the payload validates like input.
+   */
+  error: <T extends keyof Errs & string>(tag: T, ...data: Record<never, never> extends InferArgs<Errs[T]> ? [data?: InferArgs<Errs[T]>] : [data: InferArgs<Errs[T]>]) => FnError<T, InferInput<Errs[T]>>;
+  /** Define fns from inside: this fn's scope and key carry over, so
+   * anything built here is typed exactly like a chained builder. */
+  fn: FnApi;
+  /** The schema constructors (string, number, object, ...). */
+  types: typeof vTypes;
+} & /** Every var in scope, directly on `c`: read `c.session`, write by
+ * plain assignment (`c.session = {...}`). Every var is a readonly
+ * property on a readonly fn. */ VarScope<RV, Required, RO> &
+/** Fns from `use`, directly on `c` and already threaded with this
+ * context: `c.createUser({...})`. */
+(RO extends true ? ReadUseApi<U> : UseApi<U>);
+type InferReturn<O> = unknown extends O ? unknown : InferInput<OutputSchemaOf<O>>;
+interface Fn<Base = unknown, BaseFns = unknown, BasePL extends readonly Module[] = [], Prefix extends string = ""> {
+  /**
+   * The builder FN is a schema too: `create: v.fn` (never called) declares
+   * "any function" - typed `(...args: any[]) => any`, runtime checks only
+   * `typeof value === "function"`.
+   */
+  readonly $fnSchema: {
+    input?: unknown;
+    output?: unknown;
+  };
+  /**
+   * "A fn with THIS signature", as a schema: `create: v.fn.type({ input,
+   * output })` types the field as that fn and validates what a signature
+   * CAN be validated for - the value is a function, and a plain closure
+   * gets the declared input checked at its door on every call.
+   *
+   * This exists apart from a handler-less `v.fn({ input, output })` for
+   * INLINE use: `v.fn`'s handler overloads return a callable, which makes
+   * TypeScript defer any inline `v.fn(...)` call inside another generic
+   * call's arguments (higher-order inference) - the enclosing `v.object`/
+   * `v.var` then loses its shape inference entirely. `v.fn.type` returns a
+   * plain carrier, so it composes inline anywhere.
+   */
+  readonly type: <I = unknown, O = unknown>(signature?: {
+    input?: I;
+    output?: O;
+  }) => {
+    readonly $fnSchema: {
+      input?: I;
+      output?: O;
+    };
+  };
+  <R>(fn: (ctx: Context<unknown, ScopeOf<[], Base, BasePL>, never, BaseFns, Fn<Base, BaseFns, BasePL, Prefix>>) => R): FnDefination<void, R, Prefix extends "" ? string : Prefix, unknown, readonly string[], NoErrors, ScopeOf<[], Base, BasePL>, BaseFns>;
+  <K extends LiteralString, R>(key: K, fn: (ctx: Context<unknown, ScopeOf<[], Base, BasePL>, never, BaseFns, Fn<Base, BaseFns, BasePL, `${Prefix}${K}`>>) => R): FnDefination<void, R, `${Prefix}${K}`, unknown, readonly string[], NoErrors, ScopeOf<[], Base, BasePL>, BaseFns>;
+  <const I, O, R extends InferReturn<O> | Promise<InferReturn<O>>, const PL extends readonly Module[] = [], const P extends readonly VarName<ScopeOf<PL, Base>>[] = readonly [], const Q extends readonly VarName<ScopeOf<PL, Base>>[] = readonly [], RO extends boolean = false, Er extends Record<string, unknown> = NoErrors>(options: OptionType<I, O, P, Q, PL, RO, Er>, fn: (ctx: Context<I, ScopeOf<PL, Base, readonly [...BasePL, ...PL]>, WithDerived<PL, BasePL, Q[number]>, ApplyOns<ModuleFns<PL>, PL> & BaseFns, Fn<Base & ResolvedVars<PL>, ApplyOns<ModuleFns<PL>, PL> & BaseFns, readonly [...BasePL, ...PL], Prefix>, RO, Er>) => R): FnDefination<ArgsOf<I>, R, Prefix extends "" ? string : Prefix, I, P, Er, ScopeOf<PL, Base, readonly [...BasePL, ...PL]>, ApplyOns<ModuleFns<PL>, PL> & BaseFns, O>;
+  <K extends LiteralString, const I, O, R extends InferReturn<O> | Promise<InferReturn<O>>, const PL extends readonly Module[] = [], const P extends readonly VarName<ScopeOf<PL, Base>>[] = readonly [], const Q extends readonly VarName<ScopeOf<PL, Base>>[] = readonly [], RO extends boolean = false, Er extends Record<string, unknown> = NoErrors>(key: K, options: OptionType<I, O, P, Q, PL, RO, Er>, fn: (ctx: Context<I, ScopeOf<PL, Base, readonly [...BasePL, ...PL]>, WithDerived<PL, BasePL, Q[number]>, ApplyOns<ModuleFns<PL>, PL> & BaseFns, Fn<Base & ResolvedVars<PL>, ApplyOns<ModuleFns<PL>, PL> & BaseFns, readonly [...BasePL, ...PL], `${Prefix}${K}`>, RO, Er>) => R): FnDefination<ArgsOf<I>, R, `${Prefix}${K}`, I, P, Er, ScopeOf<PL, Base, readonly [...BasePL, ...PL]>, ApplyOns<ModuleFns<PL>, PL> & BaseFns, O>;
+  <K extends LiteralString>(key: K): Instance<Base, BaseFns, BasePL, `${Prefix}${K}`>;
+  <I, O, const PL extends readonly Module[] = [], const P extends readonly VarName<ScopeOf<PL, Base>>[] = readonly [], const Q extends readonly VarName<ScopeOf<PL, Base>>[] = readonly []>(options: OptionType<I, O, P, Q, PL>): Instance<Base & ResolvedVars<PL>, BaseFns & ApplyOns<ModuleFns<PL>, PL>, readonly [...BasePL, ...PL], Prefix, I, O>;
+  <K extends LiteralString, I, O, const PL extends readonly Module[] = [], const P extends readonly VarName<ScopeOf<PL, Base>>[] = readonly [], const Q extends readonly VarName<ScopeOf<PL, Base>>[] = readonly []>(key: K, options: OptionType<I, O, P, Q, PL>): Instance<Base & ResolvedVars<PL>, BaseFns & ApplyOns<ModuleFns<PL>, PL>, readonly [...BasePL, ...PL], `${Prefix}${K}`, I, O>;
+}
+/** Every target worth suggesting on a builder's `on`: the mounted fns'
+ * keys (prefix-stripped, so they are valid RELATIVE targets), the scope's
+ * var-write events by name, and the two wildcards. Arbitrary strings stay
+ * legal - these only feed completion. */
+type OnTargetSuggest<Base, BaseFns, Prefix extends string> = FnTargetSuggest<BaseFns, Prefix> | `var.set.${keyof ScopeOf<[], Base> & string}` | "var.set.*" | `var.get.${keyof ScopeOf<[], Base> & string}` | "var.get.*" | "*";
+type FnTargetSuggest<Fns, Prefix extends string> = { [K in keyof Fns]: Fns[K] extends FnDefination<any, any, infer FK, any, any, any> ? FK extends `${Prefix}${infer Rest}` ? Rest : never : never; }[keyof Fns];
+type VarNameOfT<T extends string> = T extends `var.${"set" | "get"}.${infer N}` ? N extends `${string}*${string}` ? string : N : string;
+/** The scope's value for a var-event target - `unknown` when inexact. */
+type VarValueOfT<T extends string, Base> = VarNameOfT<T> extends keyof ScopeOf<[], Base> ? ScopeOf<[], Base>[VarNameOfT<T>] : unknown;
+/** The fns among `Fns` whose key the (already prefixed) target hits. */
+type MatchedFn<Fns, T extends string> = { [K in keyof Fns]: Fns[K] extends FnDefination<any, any, infer FK, any, any, any> ? TargetMatches<T, FK & string> extends true ? Fns[K] : never : never; }[keyof Fns];
+/** The intercepted input: the matched fn's (a union under wildcards),
+ * or an open record when the target names nothing the builder knows. */
+type MatchedInput<F> = [F] extends [never] ? Record<string, any> : F extends FnDefination<any, any, any, infer I, any, any> ? InferInput<I> : never;
+/** What `next()` resolves to: the matched fn's own result. */
+type MatchedResult<F> = [F] extends [never] ? any : F extends FnDefination<any, infer R, any, any, any, any> ? Awaited<R> : never;
+/** What a builder-scoped `on` handler sees: vars and `use` fns directly
+ * on `c` from the builder, `input` from the TARGET fn when known. */
+type OnContext<Base, BaseFns, F, Ext = unknown> = {
+  input: MatchedInput<F> & (unknown extends Ext ? unknown : InferInput<Ext>);
+  types: typeof vTypes;
+  fn: unknown;
+} & VarScope<ScopeOf<[], Base>, never> & UseApi<BaseFns>;
+/** `v.on`, scoped: string targets get the builder's key prefix; the
+ * handler's `c` and `next()` are typed against the matched target fn. */
+interface InstanceOn<Base, BaseFns, Prefix extends string> {
+  /** A fn REFERENCE targets its own key - never prefixed, fully typed
+   * from the fn itself plus the builder's scope. */
+  <F extends FnDefination<any, any, string, any, any, any>>(target: F, handler: (c: OnContext<Base, BaseFns, F>, next: () => Promise<MatchedResult<F>>) => any): OnEntry<F["key"]>;
+  /** Var-write events: never prefixed (vars are global), and `value`
+   * is typed from the builder's scope when the target is exact. */
+  <T extends `var.set.${keyof ScopeOf<[], Base> & string}` | "var.set.*" | `var.set.${string}`>(target: T, handler: (c: VarSetContext<VarNameOfT<T>> & {
+    value: VarValueOfT<T, Base>;
+  }, next: () => void) => void): OnEntry<T>;
+  /** Var-read events: `next()` yields the stored value and the handler's
+   * return becomes the read result - typed from the scope when exact. */
+  <T extends `var.get.${keyof ScopeOf<[], Base> & string}` | "var.get.*" | `var.get.${string}`>(target: T, handler: (c: VarGetContext<VarNameOfT<T>>, next: () => VarValueOfT<T, Base>) => VarValueOfT<T, Base>): OnEntry<T>;
+  (target: RegExp, handler: (c: OnContext<Base, BaseFns, never>, next: () => Promise<any>) => any): OnEntry<string>;
+  <N extends OnTargetSuggest<Base, BaseFns, Prefix> | LiteralString>(target: N, handler: (c: OnContext<Base, BaseFns, MatchedFn<BaseFns, `${Prefix}${N}`>>, next: () => Promise<MatchedResult<MatchedFn<BaseFns, `${Prefix}${N}`>>>) => any): OnEntry<`${Prefix}${N}`>;
+  <const Ext>(target: RegExp, extend: {
+    input: Ext;
+  }, handler: (c: OnContext<Base, BaseFns, never, Ext>, next: () => Promise<any>) => any): OnEntry<string, Ext>;
+  <N extends OnTargetSuggest<Base, BaseFns, Prefix> | LiteralString, const Ext>(target: N, extend: {
+    input: Ext;
+  }, handler: (c: OnContext<Base, BaseFns, MatchedFn<BaseFns, `${Prefix}${N}`>, Ext>, next: () => Promise<MatchedResult<MatchedFn<BaseFns, `${Prefix}${N}`>>>) => any): OnEntry<`${Prefix}${N}`, Ext>;
+}
+type Instance<Base, BaseFns, PL extends readonly Module[] = [], Prefix extends string = "", I = unknown, O = unknown> = {
+  /** Same as `v.fn`, with this builder's key prefix and options baked in. */
+  fn: Fn<Base, BaseFns, PL, Prefix>;
+  /**
+   * A handler-less builder doubles as an input SCHEMA: used as `input`
+   * (or an input field) it declares "a FN from `input` to `output`" -
+   * the value crossing is the fn itself. Carries the declared schemas
+   * for inference here and validation at runtime (see `isFnSchema`).
+   */
+  readonly $fnSchema: {
+    input?: I;
+    output?: O;
+  };
+  /** Same as `v.on`, with the prefix on string targets and the handler
+   * typed against the matched target fn. */
+  on: InstanceOn<Base, BaseFns, Prefix>;
+  /**
+   * The context a handler on this builder receives - a TYPE carrier for
+   * `typeof f.ctx` (helper signatures, plugin contracts). Every handler
+   * context on this builder is assignable to it: `input` and `fn` are
+   * loosened since they vary per fn. A real context only exists per
+   * invocation, so this is `undefined` at runtime.
+   */
+  readonly ctx: Context<unknown, ScopeOf<[], Base, PL>, never, BaseFns, unknown>;
+};
+//#endregion
+export { ArgsOf, BoundCall, Context, Fn, FnDefination, FnErrors, FnErrorsOf, InferReturn, Instance, InstanceOn, OptionType, ParentContext, UseApi, WithContext };
+//# sourceMappingURL=fn.d.cts.map

package/dist/fn.d.mts

@@ -0,0 +1,286 @@
+import { FnError } from "./error.mjs";
+import { LiteralString, Prettify } from "./types.mjs";
+import { InferArgs, InferInput, OutputSchemaOf, vTypes } from "./schema.mjs";
+import { VarDefination } from "./var.mjs";
+import { ApplyOns, Module, ModuleFns, OnEntry, TargetMatches, VarGetContext, VarSetContext, WithDerived } from "./module.mjs";
+import { ResolvedVars, ScopeOf, VarName, VarScope } from "./scope.mjs";
+//#region src/fn.d.ts
+type ParentContext = Record<string, any>;
+/** The call shape: a TUPLE input spreads - one parameter per position,
+ * the parent context last. Everything else takes (input?, parent?). */
+type CallArgs<A, I> = I extends readonly unknown[] ? A extends readonly unknown[] ? [...A] | [...A, ParentContext] : never : [A] extends [void] ? [input?: undefined, parent?: ParentContext] : [input: A, parent?: ParentContext];
+/** The union of a fn's DECLARED errors, as thrown values. */
+type FnErrorsOf<Er> = { [T in keyof Er & string]: FnError<T, InferInput<Er[T]>>; }[keyof Er & string];
+/** The declared-error union of a fn - for typing catch sites. */
+type FnErrors<F> = F extends FnDefination<any, any, any, any, any, infer Er> ? FnErrorsOf<Er> : never;
+type TryResult<R, Er> = R extends Promise<infer V> ? Promise<{
+  ok: true;
+  value: V;
+} | {
+  ok: false;
+  error: FnErrorsOf<Er>;
+}> : {
+  ok: true;
+  value: R;
+} | {
+  ok: false;
+  error: FnErrorsOf<Er>;
+};
+/** No declared errors - the default error channel. */
+type NoErrors = Record<never, never>;
+/** The `use` half of `.with`: fn overrides by name, recursing into
+ * GROUPS so a nested binding can be overridden too. A var alias takes a
+ * SEED for the var it points at. */
+type WithFns<U> = { [K in keyof U]?: U[K] extends FnDefination<any, any, any, any, any, any> ? BoundFn<U[K]> : U[K] extends VarDefination<any, infer T, any, any> ? T : WithFns<U[K]>; };
+/** The context `.with` accepts: any var of the fn's WHOLE chain scope
+ * (the builder's `use` included, not just the fn's own), plus any `use`
+ * fn as an override - and nothing else. Kept as PLAIN mapped types: with
+ * `RV`/`U` unknown both halves collapse to `{}`, which keeps every
+ * `extends FnDefination<any, ...>` structural check passing. */
+type WithContext<RV, U> = { [K in keyof RV]?: RV[K]; } & WithFns<U>;
+/** What `.with` returns: the same callable, context baked in. */
+interface BoundCall<A, R, I, Er> {
+  (...args: CallArgs<A, I>): R;
+  try(...args: CallArgs<A, I>): TryResult<R, Er>;
+}
+interface FnDefination<A, R, K extends string = string, I = unknown, P extends readonly string[] = readonly string[], Er = NoErrors, RV = unknown, U = unknown, O = unknown> {
+  (...args: CallArgs<A, I>): R;
+  /**
+   * Call with DECLARED errors caught as a value: `{ ok: true, value }`
+   * or `{ ok: false, error }`, narrowed by `error.tag`. Only tagged,
+   * expected errors become results - defects and contract violations
+   * still throw, exactly as they should.
+   */
+  try(...args: CallArgs<A, I>): TryResult<R, Er>;
+  /**
+   * Call with a HAND-BUILT context. Keys naming a var SEED that var in a
+   * fresh scope; keys naming a `use` fn OVERRIDE that binding for the
+   * whole subtree below. Both are typed from the fn's chain - what the
+   * BUILDER mounted counts, so `signOut.with({ user })` type-checks even
+   * though `signOut` itself never says `use: [user]`. A parent passed to
+   * the bound call is FORKED: its vars are copied in, never written back.
+   */
+  with(context: WithContext<RV, U>): BoundCall<A, R, I, Er>;
+  /** Brand, so a plugin module can be scanned for its fns. */
+  readonly $fn: true;
+  /** The name interceptors target - literal, so `ApplyOn` can match it. */
+  readonly key: K;
+  /** The declared contract, retained AS WRITTEN for runtime
+   * introspection (tool cards, docs renderers): the raw input/output
+   * schemas, error tag map, and required vars. Optional so structural
+   * `extends FnDefination` checks keep passing for hand-built fns. */
+  readonly $schema?: {
+    input?: unknown;
+    output?: unknown;
+    errors?: Record<string, unknown>;
+    requires?: readonly string[];
+    /** Declared idempotence - same args, same result, safe to repeat. */
+    idempotent?: boolean;
+  };
+  /** Vars this fn promises to set when ITS OWN body runs - the literal
+   * list, readable by graph tooling at both type and runtime level. */
+  readonly provides: P;
+  /** Phantom: the raw declared input, so extensions of the vars it
+   * references can widen used-fn call sites. Never set at runtime. */
+  readonly $input?: I;
+  /** Phantom: the raw declared output, the counterpart of `$input` - the
+   * schema as written, for type-level introspection. Never set at runtime. */
+  readonly $output?: O;
+  /** Phantom: declared error tags -> payload schemas. */
+  readonly $errors?: Er;
+}
+type ArgsOf<I> = I extends readonly unknown[] ? { -readonly [K in keyof I]: InferArgs<I[K]>; } : unknown extends I ? void : InferArgs<I>;
+type OptionType<I, O, P, Q, PL, RO extends boolean = boolean, Er = any> = {
+  /**
+   * The fn's DECLARED failures: tag -> payload schema. The THIRD
+   * contract door - input validates on entry, output on exit, errors at
+   * `throw c.error(tag, data)`. Once declared, any UNTAGGED throw
+   * escaping the body is a defect and comes out as `UnexpectedError` -
+   * callers can tell a domain refusal from a bug without string
+   * matching.
+   */
+  errors?: Er;
+  /**
+   * A readonly fn cannot write vars - not in its handler, not in
+   * anything it calls, not from interceptors mounted on it. Enforced at
+   * the type level (vars readonly on `c`, declared writers uncallable)
+   * and at runtime (the whole subtree's store locks).
+   */
+  readonly?: RO;
+  /**
+   * Declared idempotence: calling with the same args always produces the
+   * same result and repeating the call is harmless - a read, a lookup, a
+   * pure computation. Part of the retained contract (`$schema`), so
+   * hosts may DEDUPE calls: the script engine serves repeated
+   * same-args calls to an idempotent fn from one dispatch per session.
+   * Note this is a different promise than `readonly` (writes no vars) -
+   * an fn can be readonly and still hit a non-idempotent API.
+   */
+  idempotent?: boolean;
+  input?: I;
+  /**
+   * The fn's return contract. A bare schema is BOTH the signature and
+   * the exit check; the wrapper `{ def?, validation? }` splits them -
+   * `{ def }` documents the return (tool cards, handler typing) without
+   * runtime validation, `validation` is the schema the exit check runs
+   * (defaults to none in the wrapper form).
+   */
+  output?: O;
+  /** Vars this fn guarantees to set. Checked on exit. */
+  provides?: P;
+  /** Vars that must already be set. Checked on entry, before the body. */
+  requires?: Q;
+  /**
+   * Module namespaces to pull in. Their vars come into scope, their fns
+   * land directly on `c` already bound to this context (a plain-record
+   * member nests as a NAMESPACE: `c.cookies.setCookie`), and their `on`
+   * entries stay active for everything below.
+   */
+  use?: PL;
+};
+/** A used fn, with the parent context already applied. A tuple-input fn
+ * keeps its positional signature. */
+type BoundFn<F> = F extends FnDefination<infer A, infer R, string, infer I, any, any> ? I extends readonly unknown[] ? A extends readonly unknown[] ? (...args: [...A]) => R : never : [A] extends [void] ? () => R : (input: A) => R : never;
+/** Keys of a usable map whose member is a VAR alias. */
+type UseVarKeys<U> = { [K in keyof U]: U[K] extends VarDefination<any, any, any, any> ? K : never; }[keyof U];
+/** A var alias' surface: the var's VALUE, read and written in place. */
+type UseVarValue<V> = V extends VarDefination<any, infer T, any, any> ? T : never;
+type UseApi<U> = Prettify<{ [K in Exclude<keyof U, UseVarKeys<U>>]: U[K] extends FnDefination<any, any, any, any, any, any> ? BoundFn<U[K]> : UseApi<U[K]>; } & { [K in UseVarKeys<U>]: UseVarValue<U[K]>; }>;
+/** Used fns inside a readonly fn: declared writers become uncallable,
+ * with the reason on hover instead of a generic type error; var aliases
+ * become readonly properties. */
+type ReadUseApi<U> = Prettify<{ [K in Exclude<keyof U, UseVarKeys<U>>]: U[K] extends FnDefination<any, any, any, any, infer P, any> ? P extends readonly [] ? BoundFn<U[K]> : `writes "${P[number] & string}" - not callable from a readonly fn` : ReadUseApi<U[K]>; } & { readonly [K in UseVarKeys<U>]: UseVarValue<U[K]>; }>;
+type Context<I, RV, Required, U = unknown, FnApi = Fn, RO extends boolean = false, Errs = NoErrors> = {
+  input: InferInput<I>;
+  /**
+   * Mint a DECLARED error - tag-checked, payload validated at creation:
+   * `throw c.error("invalid_credentials", { attempts: 3 })`. Only tags
+   * from this fn's `errors` exist; the payload validates like input.
+   */
+  error: <T extends keyof Errs & string>(tag: T, ...data: Record<never, never> extends InferArgs<Errs[T]> ? [data?: InferArgs<Errs[T]>] : [data: InferArgs<Errs[T]>]) => FnError<T, InferInput<Errs[T]>>;
+  /** Define fns from inside: this fn's scope and key carry over, so
+   * anything built here is typed exactly like a chained builder. */
+  fn: FnApi;
+  /** The schema constructors (string, number, object, ...). */
+  types: typeof vTypes;
+} & /** Every var in scope, directly on `c`: read `c.session`, write by
+ * plain assignment (`c.session = {...}`). Every var is a readonly
+ * property on a readonly fn. */ VarScope<RV, Required, RO> &
+/** Fns from `use`, directly on `c` and already threaded with this
+ * context: `c.createUser({...})`. */
+(RO extends true ? ReadUseApi<U> : UseApi<U>);
+type InferReturn<O> = unknown extends O ? unknown : InferInput<OutputSchemaOf<O>>;
+interface Fn<Base = unknown, BaseFns = unknown, BasePL extends readonly Module[] = [], Prefix extends string = ""> {
+  /**
+   * The builder FN is a schema too: `create: v.fn` (never called) declares
+   * "any function" - typed `(...args: any[]) => any`, runtime checks only
+   * `typeof value === "function"`.
+   */
+  readonly $fnSchema: {
+    input?: unknown;
+    output?: unknown;
+  };
+  /**
+   * "A fn with THIS signature", as a schema: `create: v.fn.type({ input,
+   * output })` types the field as that fn and validates what a signature
+   * CAN be validated for - the value is a function, and a plain closure
+   * gets the declared input checked at its door on every call.
+   *
+   * This exists apart from a handler-less `v.fn({ input, output })` for
+   * INLINE use: `v.fn`'s handler overloads return a callable, which makes
+   * TypeScript defer any inline `v.fn(...)` call inside another generic
+   * call's arguments (higher-order inference) - the enclosing `v.object`/
+   * `v.var` then loses its shape inference entirely. `v.fn.type` returns a
+   * plain carrier, so it composes inline anywhere.
+   */
+  readonly type: <I = unknown, O = unknown>(signature?: {
+    input?: I;
+    output?: O;
+  }) => {
+    readonly $fnSchema: {
+      input?: I;
+      output?: O;
+    };
+  };
+  <R>(fn: (ctx: Context<unknown, ScopeOf<[], Base, BasePL>, never, BaseFns, Fn<Base, BaseFns, BasePL, Prefix>>) => R): FnDefination<void, R, Prefix extends "" ? string : Prefix, unknown, readonly string[], NoErrors, ScopeOf<[], Base, BasePL>, BaseFns>;
+  <K extends LiteralString, R>(key: K, fn: (ctx: Context<unknown, ScopeOf<[], Base, BasePL>, never, BaseFns, Fn<Base, BaseFns, BasePL, `${Prefix}${K}`>>) => R): FnDefination<void, R, `${Prefix}${K}`, unknown, readonly string[], NoErrors, ScopeOf<[], Base, BasePL>, BaseFns>;
+  <const I, O, R extends InferReturn<O> | Promise<InferReturn<O>>, const PL extends readonly Module[] = [], const P extends readonly VarName<ScopeOf<PL, Base>>[] = readonly [], const Q extends readonly VarName<ScopeOf<PL, Base>>[] = readonly [], RO extends boolean = false, Er extends Record<string, unknown> = NoErrors>(options: OptionType<I, O, P, Q, PL, RO, Er>, fn: (ctx: Context<I, ScopeOf<PL, Base, readonly [...BasePL, ...PL]>, WithDerived<PL, BasePL, Q[number]>, ApplyOns<ModuleFns<PL>, PL> & BaseFns, Fn<Base & ResolvedVars<PL>, ApplyOns<ModuleFns<PL>, PL> & BaseFns, readonly [...BasePL, ...PL], Prefix>, RO, Er>) => R): FnDefination<ArgsOf<I>, R, Prefix extends "" ? string : Prefix, I, P, Er, ScopeOf<PL, Base, readonly [...BasePL, ...PL]>, ApplyOns<ModuleFns<PL>, PL> & BaseFns, O>;
+  <K extends LiteralString, const I, O, R extends InferReturn<O> | Promise<InferReturn<O>>, const PL extends readonly Module[] = [], const P extends readonly VarName<ScopeOf<PL, Base>>[] = readonly [], const Q extends readonly VarName<ScopeOf<PL, Base>>[] = readonly [], RO extends boolean = false, Er extends Record<string, unknown> = NoErrors>(key: K, options: OptionType<I, O, P, Q, PL, RO, Er>, fn: (ctx: Context<I, ScopeOf<PL, Base, readonly [...BasePL, ...PL]>, WithDerived<PL, BasePL, Q[number]>, ApplyOns<ModuleFns<PL>, PL> & BaseFns, Fn<Base & ResolvedVars<PL>, ApplyOns<ModuleFns<PL>, PL> & BaseFns, readonly [...BasePL, ...PL], `${Prefix}${K}`>, RO, Er>) => R): FnDefination<ArgsOf<I>, R, `${Prefix}${K}`, I, P, Er, ScopeOf<PL, Base, readonly [...BasePL, ...PL]>, ApplyOns<ModuleFns<PL>, PL> & BaseFns, O>;
+  <K extends LiteralString>(key: K): Instance<Base, BaseFns, BasePL, `${Prefix}${K}`>;
+  <I, O, const PL extends readonly Module[] = [], const P extends readonly VarName<ScopeOf<PL, Base>>[] = readonly [], const Q extends readonly VarName<ScopeOf<PL, Base>>[] = readonly []>(options: OptionType<I, O, P, Q, PL>): Instance<Base & ResolvedVars<PL>, BaseFns & ApplyOns<ModuleFns<PL>, PL>, readonly [...BasePL, ...PL], Prefix, I, O>;
+  <K extends LiteralString, I, O, const PL extends readonly Module[] = [], const P extends readonly VarName<ScopeOf<PL, Base>>[] = readonly [], const Q extends readonly VarName<ScopeOf<PL, Base>>[] = readonly []>(key: K, options: OptionType<I, O, P, Q, PL>): Instance<Base & ResolvedVars<PL>, BaseFns & ApplyOns<ModuleFns<PL>, PL>, readonly [...BasePL, ...PL], `${Prefix}${K}`, I, O>;
+}
+/** Every target worth suggesting on a builder's `on`: the mounted fns'
+ * keys (prefix-stripped, so they are valid RELATIVE targets), the scope's
+ * var-write events by name, and the two wildcards. Arbitrary strings stay
+ * legal - these only feed completion. */
+type OnTargetSuggest<Base, BaseFns, Prefix extends string> = FnTargetSuggest<BaseFns, Prefix> | `var.set.${keyof ScopeOf<[], Base> & string}` | "var.set.*" | `var.get.${keyof ScopeOf<[], Base> & string}` | "var.get.*" | "*";
+type FnTargetSuggest<Fns, Prefix extends string> = { [K in keyof Fns]: Fns[K] extends FnDefination<any, any, infer FK, any, any, any> ? FK extends `${Prefix}${infer Rest}` ? Rest : never : never; }[keyof Fns];
+type VarNameOfT<T extends string> = T extends `var.${"set" | "get"}.${infer N}` ? N extends `${string}*${string}` ? string : N : string;
+/** The scope's value for a var-event target - `unknown` when inexact. */
+type VarValueOfT<T extends string, Base> = VarNameOfT<T> extends keyof ScopeOf<[], Base> ? ScopeOf<[], Base>[VarNameOfT<T>] : unknown;
+/** The fns among `Fns` whose key the (already prefixed) target hits. */
+type MatchedFn<Fns, T extends string> = { [K in keyof Fns]: Fns[K] extends FnDefination<any, any, infer FK, any, any, any> ? TargetMatches<T, FK & string> extends true ? Fns[K] : never : never; }[keyof Fns];
+/** The intercepted input: the matched fn's (a union under wildcards),
+ * or an open record when the target names nothing the builder knows. */
+type MatchedInput<F> = [F] extends [never] ? Record<string, any> : F extends FnDefination<any, any, any, infer I, any, any> ? InferInput<I> : never;
+/** What `next()` resolves to: the matched fn's own result. */
+type MatchedResult<F> = [F] extends [never] ? any : F extends FnDefination<any, infer R, any, any, any, any> ? Awaited<R> : never;
+/** What a builder-scoped `on` handler sees: vars and `use` fns directly
+ * on `c` from the builder, `input` from the TARGET fn when known. */
+type OnContext<Base, BaseFns, F, Ext = unknown> = {
+  input: MatchedInput<F> & (unknown extends Ext ? unknown : InferInput<Ext>);
+  types: typeof vTypes;
+  fn: unknown;
+} & VarScope<ScopeOf<[], Base>, never> & UseApi<BaseFns>;
+/** `v.on`, scoped: string targets get the builder's key prefix; the
+ * handler's `c` and `next()` are typed against the matched target fn. */
+interface InstanceOn<Base, BaseFns, Prefix extends string> {
+  /** A fn REFERENCE targets its own key - never prefixed, fully typed
+   * from the fn itself plus the builder's scope. */
+  <F extends FnDefination<any, any, string, any, any, any>>(target: F, handler: (c: OnContext<Base, BaseFns, F>, next: () => Promise<MatchedResult<F>>) => any): OnEntry<F["key"]>;
+  /** Var-write events: never prefixed (vars are global), and `value`
+   * is typed from the builder's scope when the target is exact. */
+  <T extends `var.set.${keyof ScopeOf<[], Base> & string}` | "var.set.*" | `var.set.${string}`>(target: T, handler: (c: VarSetContext<VarNameOfT<T>> & {
+    value: VarValueOfT<T, Base>;
+  }, next: () => void) => void): OnEntry<T>;
+  /** Var-read events: `next()` yields the stored value and the handler's
+   * return becomes the read result - typed from the scope when exact. */
+  <T extends `var.get.${keyof ScopeOf<[], Base> & string}` | "var.get.*" | `var.get.${string}`>(target: T, handler: (c: VarGetContext<VarNameOfT<T>>, next: () => VarValueOfT<T, Base>) => VarValueOfT<T, Base>): OnEntry<T>;
+  (target: RegExp, handler: (c: OnContext<Base, BaseFns, never>, next: () => Promise<any>) => any): OnEntry<string>;
+  <N extends OnTargetSuggest<Base, BaseFns, Prefix> | LiteralString>(target: N, handler: (c: OnContext<Base, BaseFns, MatchedFn<BaseFns, `${Prefix}${N}`>>, next: () => Promise<MatchedResult<MatchedFn<BaseFns, `${Prefix}${N}`>>>) => any): OnEntry<`${Prefix}${N}`>;
+  <const Ext>(target: RegExp, extend: {
+    input: Ext;
+  }, handler: (c: OnContext<Base, BaseFns, never, Ext>, next: () => Promise<any>) => any): OnEntry<string, Ext>;
+  <N extends OnTargetSuggest<Base, BaseFns, Prefix> | LiteralString, const Ext>(target: N, extend: {
+    input: Ext;
+  }, handler: (c: OnContext<Base, BaseFns, MatchedFn<BaseFns, `${Prefix}${N}`>, Ext>, next: () => Promise<MatchedResult<MatchedFn<BaseFns, `${Prefix}${N}`>>>) => any): OnEntry<`${Prefix}${N}`, Ext>;
+}
+type Instance<Base, BaseFns, PL extends readonly Module[] = [], Prefix extends string = "", I = unknown, O = unknown> = {
+  /** Same as `v.fn`, with this builder's key prefix and options baked in. */
+  fn: Fn<Base, BaseFns, PL, Prefix>;
+  /**
+   * A handler-less builder doubles as an input SCHEMA: used as `input`
+   * (or an input field) it declares "a FN from `input` to `output`" -
+   * the value crossing is the fn itself. Carries the declared schemas
+   * for inference here and validation at runtime (see `isFnSchema`).
+   */
+  readonly $fnSchema: {
+    input?: I;
+    output?: O;
+  };
+  /** Same as `v.on`, with the prefix on string targets and the handler
+   * typed against the matched target fn. */
+  on: InstanceOn<Base, BaseFns, Prefix>;
+  /**
+   * The context a handler on this builder receives - a TYPE carrier for
+   * `typeof f.ctx` (helper signatures, plugin contracts). Every handler
+   * context on this builder is assignable to it: `input` and `fn` are
+   * loosened since they vary per fn. A real context only exists per
+   * invocation, so this is `undefined` at runtime.
+   */
+  readonly ctx: Context<unknown, ScopeOf<[], Base, PL>, never, BaseFns, unknown>;
+};
+//#endregion
+export { ArgsOf, BoundCall, Context, Fn, FnDefination, FnErrors, FnErrorsOf, InferReturn, Instance, InstanceOn, OptionType, ParentContext, UseApi, WithContext };
+//# sourceMappingURL=fn.d.mts.map