@zapier/kitcore 0.0.0 → 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,2907 @@
+import { z } from 'zod';
+
+declare module "zod" {
+    interface GlobalMeta {
+        internal?: boolean;
+        deprecated?: boolean;
+        valueHint?: string;
+    }
+}
+
+/**
+ * Pagination shapes used by the plugin framework.
+ */
+/**
+ * Single page of a paginated SDK list result. Returned from the page-level
+ * promise and yielded from the page-level async iterable.
+ */
+interface SdkPage<T = unknown> {
+    data: T[];
+    nextCursor?: string;
+}
+/**
+ * Return type of every paginated SDK method. The same value is both:
+ *
+ *   - a Promise that resolves to the first page (`SdkPage<TItem>`), and
+ *   - an AsyncIterable that yields each page in turn,
+ *
+ * with an `.items()` method that returns an AsyncIterable over individual
+ * items across all pages. Named so paginated plugin signatures serialize
+ * as `PaginatedSdkResult<AppItem>` in `.d.ts` rather than expanding the
+ * full triple-intersection at every callsite.
+ *
+ * The faces share one underlying cursor, so a result is consumed once:
+ *
+ *   - `await` / `.then()` read the buffered first page without starting the
+ *     stream, so awaiting is a repeatable peek and you can still iterate the
+ *     result afterward.
+ *   - The page-iterable and `.items()` are two views over one page stream, so
+ *     consuming either drains the other: the second view yields nothing (it
+ *     does not replay page 1). To read a result more than once, call the
+ *     method again for a fresh result.
+ */
+interface PaginatedSdkResult<TItem> extends Promise<SdkPage<TItem>>, AsyncIterable<SdkPage<TItem>> {
+    items(): AsyncIterable<TItem>;
+}
+type PaginatedSdkFunction<TOptions, TItem> = (options: TOptions) => PaginatedSdkResult<TItem>;
+
+interface FormattedItem {
+    title: string;
+    /**
+     * Secondary identifying context shown dimmed after the title (ids, keys,
+     * slugs, ...). A dumb visual string a renderer shows verbatim, never
+     * structured data it has to interpret; the same role as a prompt choice's
+     * `hint`. An array is joined with ", ". Structured fields live on the
+     * response / `outputSchema`, not here, so the renderer stays dumb.
+     */
+    hint?: string | string[];
+    /** @deprecated Use `hint` (the renderer no longer interprets ids). */
+    id?: string;
+    /** @deprecated Use `hint`. */
+    key?: string;
+    /** @deprecated Use `hint`. */
+    keys?: string[];
+    description?: string;
+    /** If provided, the renderer shows this raw (verbatim) instead of `details`. */
+    raw?: unknown;
+    details: Array<{
+        label?: string;
+        text: string;
+        style: "normal" | "dim" | "accent" | "warning" | "success";
+    }>;
+}
+interface OutputFormatter<TSdk, TItem = unknown, TParams = Record<string, unknown>, TContext = unknown> {
+    fetch?: (sdk: TSdk, params: TParams, item: TItem, context: TContext | undefined) => Promise<TContext>;
+    format: (item: TItem, context?: TContext) => FormattedItem;
+}
+declare function getOutputSchema(inputSchema: z.ZodType): z.ZodType | undefined;
+declare function withOutputSchema<T extends z.ZodType>(inputSchema: T, outputSchema: z.ZodType): T & {
+    _def: T["_def"] & {
+        outputSchema: z.ZodType;
+    };
+};
+/** A selectable option in a prompt. `label` is the display text; `value` is
+ * what the resolver returns when picked. */
+interface PromptConfigChoice {
+    label: string;
+    value: unknown;
+    /**
+     * Optional secondary info shown after the label. The CLI wraps it in
+     * dimmed parens; an array is joined with ", ". Use for keys, ids, or
+     * other context that's useful but shouldn't compete visually with
+     * the primary label.
+     */
+    hint?: string | string[];
+}
+/**
+ * The pre-rename choice shape, kept so existing resolvers keep compiling while
+ * they migrate to {@link PromptConfigChoice}.
+ * @deprecated Use {@link PromptConfigChoice} with `label` instead of `name`.
+ */
+interface DeprecatedPromptConfigChoice {
+    /** @deprecated Use `label` instead. */
+    name: string;
+    value: unknown;
+    hint?: string | string[];
+}
+interface PromptConfig {
+    type: "list" | "checkbox" | "confirm";
+    /**
+     * The answer key. The framework supplies it from the resolver's attachment
+     * (the param the resolver resolves), so authors should omit it; a provided
+     * value is overwritten.
+     * @deprecated Omit; the framework supplies the param key.
+     */
+    name?: string;
+    message: string;
+    choices?: Array<PromptConfigChoice | DeprecatedPromptConfigChoice>;
+    default?: unknown;
+    /** Informational, non-selectable lines shown with the prompt (e.g. "enable X
+     * to see more"). A host renders them dimmed, after the choices. The framework
+     * stays agnostic about their content; the resolver composes the text. */
+    notes?: string[];
+    filter?: (value: unknown) => unknown;
+    /**
+     * Return `true` for valid; a string for a custom invalid message; or
+     * `false` for invalid with a generic fallback message ("X: invalid
+     * value."). Prefer returning a string so users see something specific.
+     */
+    validate?: (value: unknown) => boolean | string;
+}
+/** A PromptConfig narrowed to single-select list mode. */
+type ListPromptConfig = PromptConfig & {
+    type: "list";
+};
+/**
+ * The prompt config the NEW-model resolvers (`defineResolver`) return. It omits
+ * three fields the resolution controller does not honor, so authors can't
+ * supply a silent no-op:
+ *  - `name`   — the framework supplies the answer key (always was overwritten).
+ *  - `default`— no resolver uses it; the controller has no preselect concept.
+ *  - `filter` — no resolver uses it; transform values in `listItems` instead.
+ * (The legacy `SchemaParameterResolver` still honors `default`/`filter`, so the
+ * full `PromptConfig` stays for that path.)
+ */
+type ResolverPromptConfig = Omit<PromptConfig, "name" | "default" | "filter">;
+interface Resolver$1 {
+    type: string;
+    depends?: readonly string[] | string[];
+}
+interface StaticResolver$1 extends Resolver$1 {
+    type: "static";
+    inputType?: "text" | "password" | "email";
+    placeholder?: string;
+}
+/**
+ * A resolver that always resolves to a fixed value, never prompts. Use to
+ * pin an implicit parameter that downstream resolvers or SDK calls require
+ * but the user shouldn't have to provide. Triggers, for example, are always
+ * `actionType: "read"` from the SDK's perspective; createTriggerInbox
+ * declares `actionType: { type: "constant", value: "read" }` so the
+ * standard `actionKeyResolver` and `inputsResolver` (which depend on
+ * `actionType`) work without any pinned variants.
+ *
+ * Constants attached to keys that aren't in the schema are seeded into
+ * `resolvedParams` upfront, so dependent resolvers find them in context
+ * without the key appearing in the user-facing surface (TS option type,
+ * CLI flags, generated docs).
+ */
+interface ConstantResolver$1 extends Resolver$1 {
+    type: "constant";
+    value: unknown;
+}
+/**
+ * Fields shared by both variants of {@link DynamicResolver}.
+ */
+interface DynamicResolverBase<TSdk, TItem, TParams> extends Resolver$1 {
+    type: "dynamic";
+    prompt: (items: TItem[], params: TParams) => PromptConfig;
+    /** Capabilities that expand results. The parameter resolver shows a hint for any that aren't enabled. */
+    requireCapabilities?: string[];
+    /**
+     * Optional hook called before fetch/prompt. If it returns a non-null object,
+     * resolvedValue is used directly and fetch/prompt are skipped entirely. Return
+     * null to fall through to the normal resolution flow. Implementations should
+     * catch their own errors and return null on failure rather than throwing, so
+     * that a transient API error does not block the CLI entirely.
+     */
+    tryResolveWithoutPrompt?: (sdk: TSdk, params: TParams) => Promise<{
+        resolvedValue: unknown;
+    } | null>;
+}
+/**
+ * The classic dynamic-resolver variant: `fetch` returns a list of items
+ * that the CLI renders as a search-filterable dropdown. The user picks one.
+ */
+interface DynamicListResolver<TSdk, TItem, TParams> extends DynamicResolverBase<TSdk, TItem, TParams> {
+    /** Explicitly absent on the list variant; set `inputType: "search"` to opt into the search variant. */
+    inputType?: never;
+    /** Only meaningful for the search variant; set to `never` here so TS catches misuse. */
+    placeholder?: never;
+    fetch: (sdk: TSdk, resolvedParams: TParams) => PromiseLike<TItem[] | {
+        data: TItem[];
+        nextCursor?: string;
+    } | AsyncIterable<{
+        data: TItem[];
+        nextCursor?: string;
+    }>>;
+}
+/**
+ * The search-input variant: the CLI prompts the user for free-form text
+ * first, then calls `fetch` with `{ ...resolvedParams, search }`.
+ *
+ * `fetch` can short-circuit by returning a primitive (`string | number`),
+ * which the CLI treats as an exact match — no dropdown is rendered. Any
+ * other return (array, page, async iterable) is rendered as the normal
+ * search-filterable dropdown.
+ *
+ * The `search` key is injected by the CLI at call time; it isn't part of
+ * `TParams` because callers that invoke `fetch` directly (outside the CLI)
+ * are responsible for passing it themselves. Search-mode resolvers should
+ * type `TParams` as `{ search?: string; ...otherDeps }` to make this
+ * explicit.
+ */
+interface DynamicSearchResolver<TSdk, TItem, TParams> extends Omit<DynamicResolverBase<TSdk, TItem, TParams>, "prompt"> {
+    inputType: "search";
+    /**
+     * Hint text appended to the search prompt's message. NOT used as
+     * inquirer's `default` value, because inquirer prefills `default` as
+     * editable text that the user has to delete before typing.
+     */
+    placeholder?: string;
+    /**
+     * Search-mode always renders a single-select @inquirer/search dropdown,
+     * so `prompt` must return a list-typed PromptConfig. Checkbox/confirm
+     * configs would be silently ignored at runtime; the type narrows so
+     * misuse fails at compile time.
+     *
+     * Note: a primitive return from `fetch` (string | number) is treated
+     * as an exact match and short-circuits without running this prompt or
+     * the resolver's validate/filter. Canonicalize inside `fetch` if the
+     * exact-match path needs normalization.
+     */
+    prompt: (items: TItem[], params: TParams) => ListPromptConfig;
+    fetch: (sdk: TSdk, resolvedParams: TParams) => PromiseLike<string | number | TItem[] | {
+        data: TItem[];
+        nextCursor?: string;
+    } | AsyncIterable<{
+        data: TItem[];
+        nextCursor?: string;
+    }>>;
+}
+/**
+ * A dynamic resolver: either a classic list (`inputType` absent) or a
+ * search-input variant (`inputType: "search"`). The discriminator is the
+ * `inputType` field; TS narrows to the right variant when you check it.
+ */
+type DynamicResolver$1<TSdk, TItem = unknown, TParams = Record<string, unknown>> = DynamicListResolver<TSdk, TItem, TParams> | DynamicSearchResolver<TSdk, TItem, TParams>;
+interface ResolverFieldItem {
+    type: string;
+    key: string;
+    title?: string;
+    is_required?: boolean;
+    value_type?: string;
+    choices?: Array<{
+        label: string;
+        value: string;
+    }>;
+    fields?: ResolverFieldItem[];
+    resolver?: ResolverMetadata<any, any, any>;
+}
+interface FieldsResolver<TSdk, TParams = Record<string, unknown>, TResult = Record<string, unknown>> extends Resolver$1 {
+    type: "fields";
+    fetch: (sdk: TSdk, resolvedParams: TParams) => Promise<ResolverFieldItem[]>;
+    transform?: (value: Record<string, unknown>) => TResult;
+}
+interface ArrayResolver$1<TSdk, TParams = Record<string, unknown>> extends Resolver$1 {
+    type: "array";
+    fetch: (sdk: TSdk, resolvedParams: TParams) => Promise<ResolverMetadata<TSdk, unknown, TParams>>;
+    minItems?: number;
+    maxItems?: number;
+}
+type ResolverMetadata<TSdk, TItem = unknown, TParams = Record<string, unknown>> = StaticResolver$1 | ConstantResolver$1 | DynamicResolver$1<TSdk, TItem, TParams> | FieldsResolver<TSdk, TParams> | ArrayResolver$1<TSdk, TParams>;
+/**
+ * Extract the SDK shape a resolver requires by inferring it from the resolver's
+ * `fetch` callback. Static and Constant resolvers have no fetch and produce
+ * `unknown`, meaning they impose no requirement on the plugin's SDK.
+ */
+type RequiredSdkOf<R> = R extends {
+    fetch: (sdk: infer S, ...args: any[]) => any;
+} ? S : unknown;
+/**
+ * Per-entry resolver-slot validator. For each key, if the plugin's `TSdk`
+ * satisfies the resolver's required SDK, the entry passes through unchanged;
+ * otherwise the slot widens to `ResolverMetadata<TSdk, any, any>`, so TS
+ * surfaces the mismatch at the specific offending key rather than at the
+ * whole `resolvers` object.
+ *
+ * Pair with `NoInfer<TSdk>` at the call site to prevent TS from inferring
+ * `TSdk` from a resolver entry (which would silently accommodate the
+ * mismatch). With `NoInfer`, the only inference site for `TSdk` is the
+ * `sdk` argument, and each resolver is then checked against it.
+ */
+type ValidResolvers<TSdk, R> = {
+    [K in keyof R]: TSdk extends RequiredSdkOf<R[K]> ? R[K] : ResolverMetadata<TSdk, any, any>;
+};
+interface ResolverConfig<TSdk, TItem = unknown, TParams = Record<string, unknown>> {
+    resolver: ResolverMetadata<TSdk, TItem, TParams>;
+}
+declare function withResolver<T extends z.ZodType, TSdk, TItem = unknown, TParams = Record<string, unknown>>(schema: T, config: ResolverConfig<TSdk, TItem, TParams>): T;
+declare function getSchemaDescription(schema: z.ZodSchema): string | undefined;
+declare function getFieldDescriptions(schema: z.ZodObject<z.ZodRawShape>): Record<string, string>;
+interface PositionalMetadata {
+    positionalMeta: {
+        positional: true;
+    };
+}
+declare function withPositional<T extends z.ZodType>(schema: T): T & {
+    _def: T["_def"] & PositionalMetadata;
+};
+declare function isPositional(schema: z.ZodType): boolean;
+declare function openEnum<const T extends readonly [string, ...string[]]>(values: T, description: string): z.ZodUnion<readonly [z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: { [k_1 in T[number]]: k_1; }[k]; } : never>, z.ZodString]>;
+
+/**
+ * Method-call lifecycle hooks. Plugins contribute `onMethodStart` and/or
+ * `onMethodEnd` on their context; `buildHooks` composes contributions across
+ * plugins so multiple observers can coexist. Composition is right-additive
+ * (newer plugins fire after earlier ones); only opt-in methods built through
+ * `createPluginMethod` / `createPaginatedPluginMethod` trigger the hooks.
+ */
+interface OnMethodStartContext {
+    methodName: string;
+    args: unknown[];
+    isPaginated: boolean;
+    /**
+     * Depth of this method invocation in the SDK call tree. 0 = outermost
+     * (user-initiated) call; 1+ = called from inside another SDK method.
+     * Observers can use this to ignore nested calls if they only want
+     * top-level events.
+     */
+    depth: number;
+}
+type OnMethodStart = (ctx: OnMethodStartContext) => void;
+interface OnMethodEndContext {
+    methodName: string;
+    args: unknown[];
+    isPaginated: boolean;
+    depth: number;
+    durationMs: number;
+    error?: Error;
+}
+type OnMethodEnd = (ctx: OnMethodEndContext) => void;
+interface MethodHooks {
+    onMethodStart?: OnMethodStart;
+    onMethodEnd?: OnMethodEnd;
+}
+
+/**
+ * Descriptive metadata a leaf carries for the registry / CLI / MCP / docs:
+ * description, categories, type, formatter, resolvers, etc.
+ * Reuses the shipped `PluginMeta` minus `inputSchema`, which is a first-class
+ * descriptor field (it also drives `input` typing and runtime validation).
+ */
+type LeafMeta = Omit<PluginMeta, "inputSchema">;
+/**
+ * The descriptive registry fields a `defineMethod` / `defineProperty` author
+ * sets directly on the config (hoisted, not nested under a `meta` wrapper).
+ * The impl folds whichever are present back into the stored `LeafMeta`. This is
+ * the strict, explicit subset of `PluginMeta` (no `[key: string]: any` escape
+ * hatch, no `inputSchema` / `formatter` / `resolvers` — those are first-class
+ * config fields of their own).
+ */
+interface LeafMetaFields {
+    description?: string;
+    categories?: (string | CategoryDefinition)[];
+    type?: "list" | "item" | "create" | "update" | "delete" | "function";
+    itemType?: string;
+    returnType?: string;
+    outputSchema?: z.ZodSchema;
+    inputParameters?: Array<{
+        name: string;
+        schema: z.ZodSchema;
+    }>;
+    packages?: string[];
+    experimental?: boolean;
+    confirm?: "create-secret" | "delete";
+    deprecation?: FunctionDeprecation;
+    aliases?: Record<string, string>;
+    supportsJsonOutput?: boolean;
+}
+type AnyMethodPlugin = MethodPlugin<string, any, any, readonly string[]>;
+type AnyPropertyPlugin = PropertyPlugin<string, any>;
+/** A leaf plugin: a method (callable) or a property (value). */
+type AnyLeafPlugin = AnyMethodPlugin | AnyPropertyPlugin;
+/**
+ * How a module declares its imports: an array. Each element binds under its own
+ * name (a leaf under its name, a module under each of its export names); a
+ * `selectExports(...)` element contributes its chosen bindings. To rename or
+ * subset, wrap an element in `selectExports`; there is no alias-map form.
+ */
+type ImportsInput = readonly AnyPlugin[];
+/** A resolved import edge: the local binding name and the plugin id it reads
+ * from `context.plugins` (id, not identity, so a swap stays transparent). */
+interface ImportBinding {
+    binding: string;
+    id: string;
+}
+/**
+ * Collapse a union to an intersection. Turns the per-dependency
+ * `{ name: signature }` union into one `imports` object type.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/**
+ * A method's callable signature. A method with no declared input infers
+ * `TInput = unknown`; make its input optional so it is callable with no
+ * argument. An input whose properties are all optional (e.g. a `list` method
+ * whose only input is the framework's `cursor` / `pageSize` / `maxItems`) is
+ * also callable with no argument. A real required input keeps the arg required.
+ */
+type MethodCall<TInput, TOutput> = [unknown] extends [TInput] ? (input?: TInput) => TOutput : {} extends TInput ? (input?: TInput) => TOutput : (input: TInput) => TOutput;
+/**
+ * Project the canonical input through an ordered list of key names into a
+ * positional argument tuple, preserving trailing-optionality: a key that is
+ * optional in `TInput` becomes an optional argument (so `fetch(url)` is legal
+ * when `init` is optional). A name that is not a key of `TInput` is an error.
+ */
+type PositionalArgs<TInput, TNames extends readonly PropertyKey[]> = TNames extends readonly [
+    infer Head extends keyof TInput,
+    ...infer Tail extends readonly (keyof TInput)[]
+] ? {} extends Pick<TInput, Head> ? [arg?: TInput[Head], ...PositionalArgs<TInput, Tail>] : [arg: TInput[Head], ...PositionalArgs<TInput, Tail>] : [];
+/**
+ * The public call signature of a method on the surface and in `imports`. With
+ * no positional projection it is the canonical single-object `MethodCall`; with
+ * one it is the positional signature derived from the input. Middleware does
+ * NOT use this (its bag carries one canonical `input`); see `MiddlewareMap`.
+ */
+type SurfaceCall<TInput, TOutput, TPositional extends readonly string[]> = TPositional extends readonly [] ? MethodCall<TInput, TOutput> : (...args: PositionalArgs<TInput, TPositional>) => TOutput;
+/**
+ * The bindings one array-form dependency contributes to `imports`: a leaf under
+ * its own name (method callable or property value), an aggregate under each of
+ * its export names.
+ */
+type BindingsOf<TDep> = TDep extends MethodPlugin<infer TName, infer TInput, infer TOutput, infer TPositional> ? {
+    [P in TName]: SurfaceCall<TInput, TOutput, TPositional>;
+} : TDep extends PropertyPlugin<infer TName, infer TValue> ? {
+    [P in TName]: TValue;
+} : TDep extends AggregatePlugin<string, infer TExports> ? {
+    [K in keyof TExports]: ExportSurface<TExports[K]>;
+} : never;
+/**
+ * The `imports` a body receives. Each element contributes its bindings
+ * (`BindingsOf`); empty imports yield an empty object.
+ */
+type ImportsOf<TImports extends ImportsInput> = TImports extends readonly [] ? Record<never, never> : UnionToIntersection<{
+    [K in keyof TImports]: BindingsOf<TImports[K]>;
+}[number]>;
+/**
+ * The bag a method body receives. `imports` is the dependency-narrowed reach;
+ * `state` is the plugin's private constructor result (undefined when none);
+ * `input` is the canonical call argument.
+ */
+interface MethodRunBag<TImports, TInput, TState = unknown> {
+    imports: TImports;
+    state: TState;
+    input: TInput;
+}
+/** Shared plumbing for the method attachments: each declares its own
+ * dependencies. Resolvers and formatters are otherwise separate concepts. */
+interface MethodAttachment {
+    imports: readonly AnyPlugin[];
+    /** Binding-name to plugin-id edges, normalized from `imports`; what the
+     * narrowed bag captured at materialization is built from. */
+    importBindings: readonly ImportBinding[];
+}
+/**
+ * A resolver's kind, the discriminant of the {@link Resolver} union. Scalars
+ * (`dynamic` / `static` / `constant`) resolve one value; `info` resolves none
+ * (display-only); `object` / `array` compose nested resolvers. Names borrow
+ * JSON Schema's structural vocabulary (`object`/`array`/`properties`/`items`),
+ * but a resolver carries behavior (fetch/prompt), not validation.
+ */
+type ResolverType = "dynamic" | "static" | "constant" | "info" | "object" | "array";
+/**
+ * A reference from a field (or array `items`) to a reusable resolver in the
+ * nearest `definitions` block. `input` are merged into the referenced
+ * resolver's `input` (e.g. the field key a shared choices-fetcher needs).
+ * Used when a fetch-built field needs an import-bearing resolver, which can't
+ * be inlined at fetch time (its imports bind at materialization).
+ */
+interface ResolverRef {
+    ref: string;
+    input?: Record<string, unknown>;
+}
+/**
+ * One member of an object resolver's `properties` (literal or fetch-built): the
+ * resolver for the value plus its per-occurrence meta. `required` / `valueType`
+ * live here, not on the resolver, because the same resolver can be required in
+ * one object and optional in another, and a fetch-built field (no schema) has
+ * nowhere else to carry them.
+ */
+interface Field {
+    resolver: Resolver | ResolverRef;
+    label?: string;
+    required?: boolean;
+    valueType?: string;
+}
+/** Shared gates for resolvers that resolve a value: the attachment plumbing
+ * plus the param-dataflow prerequisite. (`info` skips these.) */
+interface ResolverBase extends MethodAttachment {
+    /** Sibling parameters that must resolve before this resolver runs (it reads
+     * their values from `input`). The param-dataflow prerequisite, distinct from
+     * `imports`' SDK-capability graph. */
+    requireParameters?: readonly string[];
+}
+/** List candidate items and prompt the user to pick one. */
+interface DynamicResolver extends ResolverBase {
+    type: "dynamic";
+    inputType?: "text" | "password" | "email" | "search";
+    placeholder?: string;
+    /** Compute side-context once, before `listItems`, with the narrowed `imports`
+     * bag (no items yet — it runs pre-fetch so it can shape the fetch). The result
+     * flows into `listItems` and `prompt` as `context`. Use it to resolve, in one
+     * place, anything both the fetch and the render need (e.g. a capability gate:
+     * compute `includeShared` here, gate the fetch in `listItems`, surface a
+     * `notes` hint in `prompt`). May run more than once across re-asks, so keep it
+     * cheap/idempotent. */
+    getContext?: (bag: {
+        imports: Record<string, unknown>;
+        input: Record<string, unknown>;
+    }) => PromiseLike<unknown>;
+    /** Produce the candidate list. Behaves like an SDK list method: returns a
+     * paginated result (await for the first page + `nextCursor`, or iterate pages),
+     * never a bare array. `cursor` is the stateless re-entry hook for "load more":
+     * an in-process host iterates the result; a distributed host awaits one page,
+     * carries `nextCursor`, and calls again with `cursor`. */
+    listItems?: (bag: {
+        imports: Record<string, unknown>;
+        input: Record<string, unknown>;
+        /** The value `getContext` returned, if any. */
+        context?: unknown;
+        /** Free-text term injected by the CLI for search-mode resolvers. A separate
+         * key, not part of `input`, so it never collides with a method parameter
+         * also named `search`. */
+        search?: string;
+        cursor?: string;
+    }) => ListItemsResult<unknown>;
+    prompt?: (bag: {
+        items: unknown[];
+        input: Record<string, unknown>;
+        /** The value `getContext` returned, if any. */
+        context?: unknown;
+    }) => ResolverPromptConfig;
+    /** Resolve with no user input at all (e.g. a configured default), skipping the
+     * prompt. Runs before prompting; used always in non-interactive mode and as a
+     * "can we skip asking?" check otherwise. Returns null to fall through to a prompt. */
+    tryResolveWithoutPrompt?: (bag: {
+        imports: Record<string, unknown>;
+        input: Record<string, unknown>;
+    }) => Promise<{
+        resolvedValue: unknown;
+    } | null>;
+    /** Search-mode exact match: the user typed `search`; if it already names a
+     * valid value (e.g. validated via the API), return it to skip the picker.
+     * Distinct from `tryResolveWithoutPrompt` (no input) — this is interactive,
+     * mid-prompt, with the typed term. Returns null to fall through to `listItems`. */
+    tryResolveFromSearch?: (bag: {
+        imports: Record<string, unknown>;
+        input: Record<string, unknown>;
+        search?: string;
+    }) => Promise<{
+        resolvedValue: unknown;
+    } | null>;
+}
+/** Free-text input, no candidate list. */
+interface StaticResolver extends ResolverBase {
+    type: "static";
+    inputType?: "text" | "password" | "email" | "search";
+    placeholder?: string;
+}
+/** A fixed value, no prompt. */
+interface ConstantResolver extends ResolverBase {
+    type: "constant";
+    value: unknown;
+}
+/** Display-only text; resolves no value (its key is skipped in the result). */
+interface InfoResolver extends MethodAttachment {
+    type: "info";
+    text: string;
+}
+/** A keyed object. `properties` are known up front; `getProperties` builds them
+ * when the key set is dynamic (re-invoked as `input` grow, for depends-on
+ * fields). Returns the property map raw (no envelope: nothing to paginate).
+ * `definitions` holds reusable resolvers reached by `{ ref }` from built fields
+ * that need an import. */
+interface ObjectResolver extends ResolverBase {
+    type: "object";
+    properties?: Record<string, Field>;
+    getProperties?: (bag: {
+        imports: Record<string, unknown>;
+        input: Record<string, unknown>;
+    }) => PromiseLike<Record<string, Field>>;
+    definitions?: Record<string, Resolver>;
+}
+/** A homogeneous list: each element resolves through `items`. */
+interface ArrayResolver extends ResolverBase {
+    type: "array";
+    items: Resolver | ResolverRef;
+    minItems?: number;
+    maxItems?: number;
+    /** Coarse value type of each element, so a free-text item answer coerces
+     * (e.g. `"5"` → `5` for `z.array(z.number())`) the way object fields do via
+     * `Field.valueType`. `items` is a bare resolver with no `valueType` slot of
+     * its own, so the element type rides here. */
+    itemValueType?: string;
+    definitions?: Record<string, Resolver>;
+}
+/**
+ * An input resolver descriptor (produced by `defineResolver`, attached to a
+ * method parameter). A discriminated union on `type`; composites (`object` /
+ * `array`) recurse. Callbacks take a narrowed `imports` bag; the materializer
+ * captures it and produces a {@link BoundResolver}. Stored loosely (the precise
+ * `imports` / item / param types live on the `defineResolver` config), like
+ * `MethodPlugin.run`.
+ */
+type Resolver = DynamicResolver | StaticResolver | ConstantResolver | InfoResolver | ObjectResolver | ArrayResolver;
+/**
+ * An output formatter descriptor (produced by `defineFormatter`, attached to a
+ * method's output). `getContext` reaches the narrowed `imports` bag; the
+ * materializer captures it and produces a {@link BoundFormatter}. Stored
+ * loosely, like {@link Resolver}. Both callbacks receive the method's `input`
+ * (the formatter runs post-execution, so the input is complete, unlike a
+ * resolver's partial `input`).
+ */
+interface Formatter extends MethodAttachment {
+    getContext?: (bag: {
+        imports: Record<string, unknown>;
+        items: unknown[];
+        input: Record<string, unknown>;
+        context?: unknown;
+    }) => Promise<unknown>;
+    format: (bag: {
+        item: unknown;
+        input: Record<string, unknown>;
+        context?: unknown;
+    }) => FormattedItem;
+}
+/** What a dynamic resolver's `listItems` yields: an SDK list-method result
+ * (`await` for the first page + `nextCursor`, or iterate pages in-process), or a
+ * plain page / promise of one. No bare array and no scalar: it behaves like any
+ * other list method, and exact-match short-circuits live on `tryResolveFromSearch`. */
+type ListItemsResult<TItem> = PaginatedSdkResult<TItem> | SdkPage<TItem> | Promise<SdkPage<TItem>>;
+/** A bound object resolver's literal property: its resolver is already bound
+ * (or a `{ ref }` the CLI resolves against `definitions` at runtime). */
+interface BoundField {
+    resolver: BoundResolver | ResolverRef;
+    label?: string;
+    required?: boolean;
+    valueType?: string;
+}
+/**
+ * The runtime resolver `defineResolver` binds to: its imports are already
+ * captured, so the CLI calls these with input (and `search`) only, no sdk.
+ * `prompt` stays pure (no SDK reach).
+ *
+ * Carries every kind's fields on one loose interface, discriminated by `type`.
+ * The CLI rewrite (the consumer) narrows this into per-kind shapes; until then
+ * a single shape keeps the binder simple. `listItems` produces the candidate
+ * list for `dynamic`; `getProperties` builds the (unbound) property map for
+ * `object`. `properties` / `definitions` are bound; `items` is bound (or a ref).
+ */
+interface BoundResolver {
+    type: ResolverType;
+    /** Sibling parameters that must resolve before this resolver runs (it reads
+     * their values from `input`). The param-dataflow prerequisite, distinct from
+     * `imports`' SDK-capability graph. */
+    requireParameters?: readonly string[];
+    inputType?: "text" | "password" | "email" | "search";
+    placeholder?: string;
+    value?: unknown;
+    text?: string;
+    properties?: Record<string, BoundField>;
+    definitions?: Record<string, BoundResolver>;
+    items?: BoundResolver | ResolverRef;
+    minItems?: number;
+    maxItems?: number;
+    /** For an array: the element's coarse value type, used to coerce a free-text
+     * item answer before validation (see {@link ArrayResolver.itemValueType}). */
+    itemValueType?: string;
+    getContext?: (bag: {
+        input: Record<string, unknown>;
+    }) => PromiseLike<unknown>;
+    listItems?: (bag: {
+        input: Record<string, unknown>;
+        context?: unknown;
+        search?: string;
+        cursor?: string;
+    }) => ListItemsResult<unknown>;
+    getProperties?: (bag: {
+        input: Record<string, unknown>;
+    }) => PromiseLike<Record<string, Field>>;
+    prompt?: (bag: {
+        items: unknown[];
+        input: Record<string, unknown>;
+        context?: unknown;
+    }) => ResolverPromptConfig;
+    tryResolveWithoutPrompt?: (bag: {
+        input: Record<string, unknown>;
+    }) => Promise<{
+        resolvedValue: unknown;
+    } | null>;
+    tryResolveFromSearch?: (bag: {
+        input: Record<string, unknown>;
+        search?: string;
+    }) => Promise<{
+        resolvedValue: unknown;
+    } | null>;
+}
+/**
+ * The runtime formatter `defineFormatter` binds to: `getContext` runs once per
+ * rendered batch (imports captured, no sdk) to build shared context; `format`
+ * is pure and synchronous, turning one item + context into a `FormattedItem`.
+ */
+interface BoundFormatter<TItem = unknown, TInput = Record<string, unknown>, TContext = unknown> {
+    getContext?: (bag: {
+        items: TItem[];
+        input: TInput;
+        context?: TContext;
+    }) => Promise<TContext>;
+    format: (bag: {
+        item: TItem;
+        input: TInput;
+        context?: TContext;
+    }) => FormattedItem;
+}
+/**
+ * A leaf plugin that is a single function: it IS the method. `pluginType` is
+ * the node-kind discriminant; `name` is its identity and default
+ * binding name. `imports` are the other plugins it depends on. The stored
+ * `run` is loosely typed for `imports` (the precise type lives on the
+ * `defineMethod` authoring surface, like the shipped definePlugin).
+ */
+interface MethodPlugin<TName extends string = string, TInput = unknown, TOutput = unknown, TPositional extends readonly string[] = readonly []> {
+    pluginType: "method";
+    name: TName;
+    namespace?: string;
+    /** `namespace/name`, or bare `name`. The `context.plugins` key. */
+    id: string;
+    /** True for a `declareMethod` stand-in: a typed reference with no real
+     * implementation. A real plugin under the same id satisfies it. */
+    standIn?: boolean;
+    imports: readonly AnyPlugin[];
+    /** Binding-name to plugin-id edges, normalized from `imports`;
+     * what the `imports` bag is built from. */
+    importBindings: readonly ImportBinding[];
+    /** Optional per-materialization constructor: runs once at createSdk
+     * (dependencies first), may side-effect, and returns the method's private
+     * state (delivered to `run` as `bag.state`). */
+    setup?: (bag: {
+        imports: Record<string, unknown>;
+    }) => unknown;
+    /** Validates `input` before `run` and drives the authoring `input` type. */
+    inputSchema?: z.ZodType;
+    /** Descriptive metadata for the registry / CLI / MCP / docs (carry-only at
+     * runtime). */
+    meta?: LeafMeta;
+    /** Per-parameter input resolvers (method attachments). Reached for
+     * materialization and bound into the entry at createSdk; a reachability-only
+     * edge whose imports never enter this method's `importBindings`. */
+    resolvers?: Record<string, Resolver>;
+    /** Output formatter (method attachment). Bound into the entry at createSdk. */
+    formatter?: Formatter;
+    run: (bag: MethodRunBag<any, TInput, any>) => TOutput;
+    /** How `run`'s result is shaped into the public surface (see Output in the
+     * design doc). Omitted is "raw". Stored loosely; the precise per-mode typing
+     * lives on the `defineMethod` overloads. */
+    output?: OutputConfig;
+    /** Positional projection (see Output): ordered keys of the canonical input
+     * that the public surface and imports take as positional arguments. The
+     * framework packs them back into `{ input }` before validation, middleware,
+     * and `run`, so internals stay canonical. The runtime reads this loose field;
+     * the precise names ride the `TPositional` type param for surface typing. */
+    positional?: readonly string[];
+    /**
+     * Phantom: carries the positional names as a tuple type so `BindingsOf` /
+     * `ExportSurface` can render the positional signature. Never present at
+     * runtime; the loose `positional` field above is the runtime carrier.
+     * @internal
+     */
+    readonly [POSITIONAL_NAMES]?: TPositional;
+}
+/** Phantom-only key (see `MethodPlugin`); never set at runtime. */
+declare const POSITIONAL_NAMES: unique symbol;
+/** A method's output mode: raw passthrough, a `{ data }` item envelope, or a
+ * paginated list. */
+type OutputMode = "raw" | "item" | "list";
+/** The authoring value for `output`: a bare mode string, or the object form
+ * (which carries list options). */
+type OutputConfig = OutputMode | {
+    type: "raw";
+} | {
+    type: "item";
+} | {
+    type: "list";
+    adaptPage?: (response: any) => SdkPage<any>;
+    defaultPageSize?: number;
+};
+/** Normalized output config: always the object form with a resolved `type`. */
+interface NormalizedOutput {
+    type: OutputMode;
+    adaptPage?: (response: any) => SdkPage<any>;
+    defaultPageSize?: number;
+}
+/** Framework-injected page controls a list method's `run` receives. */
+type PageFetchInput = {
+    cursor?: string;
+    pageSize?: number;
+};
+/** Page controls a list method's public caller may pass. */
+type PaginatedCallInput = PageFetchInput & {
+    maxItems?: number;
+};
+/**
+ * A response whose only own keys are `data` / `nextCursor`. Gates the
+ * list-standard overload: a raw envelope with extra keys is not a `StrictPage`
+ * and falls through to the adapted overload, where `adaptPage` is required.
+ */
+type StrictPage$1<TResponse> = SdkPage<unknown> & {
+    [K in Exclude<keyof TResponse, keyof SdkPage<unknown>>]?: never;
+};
+/** Item type sourced from a page-ish response. */
+type ItemOf$1<TResponse> = TResponse extends SdkPage<infer TItem> ? TItem : TResponse extends {
+    data: readonly (infer TItem)[];
+} ? TItem : never;
+/**
+ * A leaf plugin that is a single value (not a function). `value` is a static
+ * constant; `get({ imports })` computes the value from imports. Like a
+ * method's `setup`, `get` runs eagerly at createSdk (dependencies first), so a
+ * module-level value is built on import. An imported/surfaced property yields
+ * the value, not a callable.
+ */
+interface PropertyPlugin<TName extends string = string, TValue = unknown> {
+    pluginType: "property";
+    name: TName;
+    namespace?: string;
+    /** `namespace/name`, or bare `name`. The `context.plugins` key. */
+    id: string;
+    /** True for a `declareProperty` stand-in: a typed reference with no value. A
+     * real property under the same id satisfies it. */
+    standIn?: boolean;
+    imports: readonly AnyPlugin[];
+    /** Binding-name to plugin-id edges, normalized from `imports`;
+     * what the `imports` bag is built from. */
+    importBindings: readonly ImportBinding[];
+    /** Optional once-eager constructor (the property twin of a method's `setup`):
+     * runs once at createSdk (dependencies first), may side-effect, and returns the
+     * private state delivered to `get` as `bag.state`. */
+    setup?: (bag: {
+        imports: Record<string, unknown>;
+    }) => unknown;
+    value?: TValue;
+    /** A live getter: computes the value from imports and `setup` state on each
+     * read (not once). The stored shape is loose; the precise typing lives on the
+     * `defineProperty` overloads. */
+    get?: (bag: {
+        imports: Record<string, unknown>;
+        state: unknown;
+    }) => TValue;
+    /** Descriptive metadata for the registry / CLI / MCP / docs (carry-only). */
+    meta?: LeafMeta;
+    /** A built-in whose value is the live `SdkContext`, injected at
+     * materialization. Reserved for kitcore's own plugins;
+     * authors use `value` / `get`. */
+    privileged?: boolean;
+}
+/**
+ * A middleware function wrapping one of the aggregate's imported methods.
+ * `next` invokes the next layer (an inner wrap, ultimately the core method);
+ * `imports` is the middleware plugin's own dependency reach; `input` is the
+ * canonical call argument. It must preserve the target's contract; the
+ * `MiddlewareMap` typing on `definePlugin` enforces that statically.
+ */
+type MiddlewareFn = (bag: {
+    imports: any;
+    next: (input: any) => any;
+    input: any;
+}) => any;
+/**
+ * The authoring type for an aggregate's `middleware`: a map
+ * whose keys are the method bindings among `imports` (you can only wrap a
+ * method you import) and whose values are contract-preserving wraps. `next` and
+ * `input` take the target's input and the wrap must return the target's output,
+ * so a wrap that changes the public signature, or that targets a non-imported /
+ * non-method binding, does not compile.
+ */
+type MiddlewareMap<TImports> = {
+    [K in keyof TImports as TImports[K] extends (input: any) => any ? K : never]?: TImports[K] extends (input: infer TInput) => infer TOutput ? (bag: {
+        imports: TImports;
+        next: (input: TInput) => TOutput;
+        input: TInput;
+    }) => TOutput : never;
+};
+/** The export record one array element contributes: a leaf under its own name,
+ * a module under each of its export bindings. */
+type ElementExports<E> = E extends MethodPlugin<infer N, any, any, any> ? {
+    [K in N]: E;
+} : E extends PropertyPlugin<infer N, any> ? {
+    [K in N]: E;
+} : E extends AggregatePlugin<string, infer TE> ? TE : never;
+/**
+ * The canonical export record an aggregate stores: each array element's
+ * bindings merged, so every downstream consumer sees a `Record<binding, leaf>`.
+ */
+type ArrayExports<T extends readonly (AnyLeafPlugin | AnyAggregatePlugin)[]> = T extends readonly [] ? Record<never, never> : UnionToIntersection<{
+    [I in keyof T]: ElementExports<T[I]>;
+}[number]>;
+interface AggregatePlugin<TName extends string = string, TExports extends Record<string, AnyLeafPlugin> = Record<string, AnyLeafPlugin>> {
+    pluginType: "aggregate";
+    name: TName;
+    namespace?: string;
+    /** `namespace/name`, or bare `name`. The `context.plugins` key. */
+    id: string;
+    /** True for a `declarePlugin` stand-in: a typed reference to a whole module
+     * with no implementation. A real aggregate under the same id satisfies it. */
+    standIn?: boolean;
+    imports: readonly AnyPlugin[];
+    /** Binding-name to plugin-id edges, normalized from `imports`; what a
+     * middleware wrap's `imports` is built from, and how a middleware target
+     * binding resolves to a method id. */
+    importBindings: readonly ImportBinding[];
+    exports: TExports;
+    middleware?: Record<string, MiddlewareFn>;
+}
+type AnyAggregatePlugin = AggregatePlugin<string, Record<string, any>>;
+/**
+ * A legacy bridge plugin: wraps an old function plugin
+ * (`(sdk) => provides`) so it materializes inside the new graph. At
+ * materialization it runs `run` against a live compat view, merges the
+ * returned context contributions into the shared `SdkContext`, and synthesizes
+ * a `context.plugins` entry per root key. `TSurface` is the surfaced shape (the
+ * provides minus `context`). This is the single shape `createPluginStack()
+ * .toPlugin()` emits; there is no separate interim definition format.
+ */
+interface LegacyPlugin<TSurface = Record<string, unknown>> {
+    pluginType: "legacy";
+    name: string;
+    namespace?: string;
+    /** `namespace/name`, or bare `name`. The `context.plugins` key. */
+    id: string;
+    imports: readonly AnyPlugin[];
+    importBindings: readonly ImportBinding[];
+    run: (sdk: any) => PluginProvides;
+    /** Type-only carrier for the surfaced shape; never set at runtime. */
+    readonly __surface?: TSurface;
+}
+type AnyLegacyPlugin = LegacyPlugin<any>;
+type AnyPlugin = AnyLeafPlugin | AnyAggregatePlugin | AnyLegacyPlugin;
+/**
+ * A transitional root that merges a legacy function-plugin stack with the
+ * module-model plugins migrated off it (see Migration order). At `createSdk` it
+ * lifts and runs the legacy stack (like `fromFunctionPlugin`), materializes the
+ * module-model `plugin`, and surfaces the union: the legacy stack's methods plus
+ * the module plugin's exports. The migrated plugins live in one `plugin`
+ * aggregate, so each migration only edits that aggregate's exports, not the
+ * heads. Deleted once every plugin is module-model.
+ */
+interface LegacyMergePlugin<TProvides extends PluginProvides = PluginProvides, TPlugin extends AnyPlugin = AnyPlugin> {
+    pluginType: "legacy-merge";
+    name: string;
+    namespace?: string;
+    id: string;
+    /** The lifted legacy stack (one node). */
+    legacy: LegacyPlugin<TProvides & {
+        getRegistry: (options?: {
+            package?: string;
+        }) => RegistryResult;
+    }>;
+    /** The module-model plugins migrated off the legacy stack. */
+    plugin: TPlugin;
+}
+/** One middleware layer on a method's chain: the wrap and its owning aggregate
+ * (whose `imports` the wrap receives, built live at call time). */
+interface MiddlewareWrap {
+    run: MiddlewareFn;
+    owner: AnyAggregatePlugin;
+}
+/** A materialized method: a stable callable `value` that folds `chain` around
+ * the core at call time. The chain is ordered dependents-outermost; it is
+ * mutable so post-seal `addPlugin` middleware can append. */
+interface MethodEntry {
+    pluginType: "method";
+    name: string;
+    value: (input: any) => any;
+    chain: MiddlewareWrap[];
+    /** Carried from the descriptor for the registry / CLI / MCP / docs. */
+    inputSchema?: z.ZodType;
+    meta?: LeafMeta;
+    /** Resolved output mode; the registry derives presentation from it. */
+    output?: NormalizedOutput;
+    /** Positional input projection (see Output): ordered canonical-input keys the
+     * public callable / imports take as positional args. */
+    positional?: readonly string[];
+    /** Bound input resolvers (their imports captured at materialization), keyed by
+     * param name. The CLI calls these with input only, no sdk. */
+    resolvers?: Record<string, BoundResolver>;
+    /** Bound output formatter (imports captured at materialization). */
+    formatter?: BoundFormatter;
+}
+/** A materialized property: a static `value`, or a live `getValue` thunk that
+ * re-derives the value per read (consumers install it as a getter on the surface
+ * and on `imports`). Exactly one of `value` / `getValue` is set. */
+interface PropertyEntry {
+    pluginType: "property";
+    name: string;
+    value?: any;
+    getValue?: () => any;
+    /** Carried from the descriptor for the registry / CLI / MCP / docs. */
+    meta?: LeafMeta;
+}
+/** A materialized aggregate: its resolved export bindings to child values
+ * (a method's callable or a property's value). */
+interface AggregateEntry {
+    pluginType: "aggregate";
+    name: string;
+    exports: Record<string, any>;
+}
+/** An entry in `context.plugins`. The `value`
+ * of a method entry is its callable; of a property entry, its value. */
+type PluginEntry = MethodEntry | PropertyEntry | AggregateEntry;
+/**
+ * The materialization substrate: every reachable plugin keyed by
+ * id, plus the legacy-compat surface used during migration. The
+ * compat fields let adapted function plugins read/write `context` exactly as
+ * they do on the shipped stack: `meta` is the per-method registry source, `hooks`
+ * the composed lifecycle hooks, and the index signature covers arbitrary legacy
+ * fields a function plugin contributes (`api`, `options`, `manifest` helpers,
+ * ...). A pure module-model SDK leaves `meta`/`hooks` empty and uses entry-level
+ * metadata instead.
+ */
+interface SdkContext {
+    plugins: Record<string, PluginEntry>;
+    meta: Record<string, PluginMeta>;
+    hooks: MethodHooks;
+    /** The SDK surface: each callable/value binding name mapped to the leaf plugin
+     * id it resolves to. This is what the consumer actually calls (the root's
+     * re-exports plus `addPlugin` additions), so the registry reports entries by
+     * binding (with meta from the leaf) rather than dumping `plugins` by id. An
+     * aliased re-export (`{ hi: greet }`) appears here as `hi -> "greet"`. */
+    surface: Record<string, string>;
+    [key: string]: any;
+}
+/** The surfaced shape of one re-exported child: a method's callable or a
+ * property's value. */
+type ExportSurface<TChild extends AnyLeafPlugin> = TChild extends MethodPlugin<any, infer TInput, infer TOutput, infer TPositional> ? SurfaceCall<TInput, TOutput, TPositional> : TChild extends PropertyPlugin<any, infer TValue> ? TValue : never;
+/**
+ * The framework-owned access an SDK carries beyond its string surface: the
+ * legacy `context` string key (back-compat, narrows away later). The off-surface
+ * `[CONTEXT]` symbol is attached at runtime (reach it via `getContext`) but kept
+ * out of this type so it never leaks into a consumer's emitted declarations.
+ */
+type SdkInternals = {
+    context: SdkContext;
+};
+/**
+ * The materialized SDK for a leaf root: the root's callable (method) or value
+ * (property) under its name, plus framework access.
+ */
+type Sdk$1<TName extends string, TInput, TOutput, TPositional extends readonly string[] = readonly []> = {
+    [K in TName]: SurfaceCall<TInput, TOutput, TPositional>;
+} & SdkInternals;
+/** The materialized SDK for a property root: the value under its name. */
+type PropertySdk<TName extends string, TValue> = {
+    [K in TName]: TValue;
+} & SdkInternals;
+/**
+ * The materialized SDK for an aggregate root: each export binding becomes a
+ * surface entry, typed from the re-exported child (callable for a method,
+ * value for a property).
+ */
+type AggregateSdk<TExports extends Record<string, AnyLeafPlugin>> = {
+    [K in keyof TExports]: ExportSurface<TExports[K]>;
+} & SdkInternals;
+/**
+ * The surface a plugin adds to an SDK when passed to `addPlugin`: a method
+ * under its name, a property's value, an aggregate's export bindings, or a
+ * legacy function plugin's root provides (minus `context`).
+ */
+type AddedSurface<P> = P extends MethodPlugin<infer TName, infer TInput, infer TOutput, infer TPositional> ? {
+    [K in TName]: SurfaceCall<TInput, TOutput, TPositional>;
+} : P extends PropertyPlugin<infer TName, infer TValue> ? {
+    [K in TName]: TValue;
+} : P extends AggregatePlugin<string, infer TExports> ? {
+    [K in keyof TExports]: ExportSurface<TExports[K]>;
+} : P extends (sdk: any) => infer TProvides ? TProvides extends PluginProvides ? Omit<TProvides, "context"> : Record<never, never> : Record<never, never>;
+/** `T` when it is a specific string literal, else `never`. Used on a stand-in's
+ * `name` so the id is always captured as a literal: a widened `string` (or the
+ * stale `declareMethod<TInput, TOutput>(...)` call shape, where the contract
+ * lands in the name slot) is rejected at the call rather than silently
+ * weakening the requirements ledger. */
+type LiteralString<T extends string> = string extends T ? never : T;
+declare const REQUIRES: unique symbol;
+declare const PROVIDES: unique symbol;
+/** Phantom carriers for the requirements ledger; never present at runtime. */
+interface PluginSummary<TRequires extends string = never, TProvides extends string = never> {
+    /** Declaration ids the plugin's subgraph still needs. @internal */
+    readonly [REQUIRES]?: TRequires;
+    /** Ids the plugin and its subgraph provide. @internal */
+    readonly [PROVIDES]?: TProvides;
+}
+/** The declaration ids a plugin still needs (reads the phantom carrier). */
+type RequiresOf<P> = P extends {
+    readonly [REQUIRES]?: infer R;
+} ? Extract<R, string> : never;
+/** The ids a plugin and its subgraph provide (reads the phantom carrier). */
+type ProvidesOf$1<P> = P extends {
+    readonly [PROVIDES]?: infer R;
+} ? Extract<R, string> : never;
+/** Union the requires / provides across an inline imports or exports tuple. */
+type RequiresIn<T extends readonly unknown[]> = RequiresOf<T[number]>;
+type ProvidesIn<T extends readonly unknown[]> = ProvidesOf$1<T[number]>;
+/**
+ * Reject an `imports` / `exports` value whose type widened to a non-tuple
+ * `Plugin[]`: a literal tuple has a literal `length`, a widened array has
+ * `length: number`. Identity in the good (tuple) case, so `T & StaticList<T>`
+ * infers `T` unchanged; an error brand in the bad case, which the passed array
+ * is not assignable to.
+ */
+type StaticList<T extends readonly unknown[]> = number extends T["length"] ? {
+    readonly __kitcoreError: "must be a fixed inline list of plugins, not a widened Plugin[]; declare them inline so the dependency graph stays statically known";
+} : T;
+/** A leaf provides its own name plus whatever its imports provide. */
+type LeafProvides<TName extends string, TImports extends readonly unknown[]> = TName | ProvidesIn<TImports>;
+/** A leaf requires its imports' requirements, minus what it provides. */
+type LeafRequires<TName extends string, TImports extends readonly unknown[]> = Exclude<RequiresIn<TImports>, LeafProvides<TName, TImports>>;
+/** An aggregate provides its own name plus its imports' and exports' provides. */
+type AggregateProvides<TName extends string, TImports extends readonly unknown[], TExports extends readonly unknown[]> = TName | ProvidesIn<TImports> | ProvidesIn<TExports>;
+/** An aggregate requires its imports' and exports' requirements, minus provides. */
+type AggregateRequires<TName extends string, TImports extends readonly unknown[], TExports extends readonly unknown[]> = Exclude<RequiresIn<TImports> | RequiresIn<TExports>, AggregateProvides<TName, TImports, TExports>>;
+/** A plugin's id as a type: `namespace/name`, or bare `name` when the namespace
+ * is empty. The ledger keys on this (matching runtime id resolution), not the
+ * bare name, so same-named plugins in different namespaces stay distinct. */
+type IdOf<TNamespace extends string, TName extends string> = TNamespace extends "" ? TName : `${TNamespace}/${TName}`;
+/** The binding name of an id: its last `/`-separated segment. The inverse view
+ * of `IdOf`, used by `declare*` to derive the bare binding from a full id. */
+type LastSegment<TId extends string> = TId extends `${string}/${infer Rest}` ? LastSegment<Rest> : TId;
+/** The `PluginSummary` a leaf carries, keyed on its full id. */
+type LeafSummary<TNamespace extends string, TName extends string, TImports extends readonly unknown[]> = PluginSummary<LeafRequires<IdOf<TNamespace, TName>, TImports>, LeafProvides<IdOf<TNamespace, TName>, TImports>>;
+/** The `PluginSummary` an aggregate carries, keyed on its full id. */
+type AggregateSummary<TNamespace extends string, TName extends string, TImports extends readonly unknown[], TExports extends readonly unknown[]> = PluginSummary<AggregateRequires<IdOf<TNamespace, TName>, TImports, TExports>, AggregateProvides<IdOf<TNamespace, TName>, TImports, TExports>>;
+/** Surfaced by `createSdk` when reachable declarations have no provider. */
+interface MissingDependencies<TIds extends string> {
+    readonly __kitcoreError: "Missing concrete provider(s) for required declaration id(s)";
+    readonly missing: TIds;
+}
+/**
+ * `unknown` when every reachable declaration is provided, otherwise a
+ * `MissingDependencies` brand. `createSdk` takes `root: P & CompletenessOf<P>`,
+ * so a complete root infers `P` unchanged (intersect `unknown`) while an
+ * incomplete one fails to assign (the argument lacks `missing`).
+ */
+type CompletenessOf<P> = [
+    Exclude<RequiresOf<P>, ProvidesOf$1<P>>
+] extends [never] ? unknown : MissingDependencies<Exclude<RequiresOf<P>, ProvidesOf$1<P>>>;
+/** Recover the materialized SDK type for a checked root (the summary that
+ * rides on the `define*` return is transparent to these). */
+type MethodSdkOf<P> = P extends MethodPlugin<infer TName, infer TInput, infer TOutput, infer TPos> ? Sdk$1<TName, TInput, TOutput, TPos> : never;
+type PropertySdkOf<P> = P extends PropertyPlugin<infer TName, infer TValue> ? PropertySdk<TName, TValue> : never;
+type AggregateSdkOf<P> = P extends AggregatePlugin<string, infer TExports> ? AggregateSdk<TExports> : never;
+
+/**
+ * Declaration for a registry category (a bucket grouping related functions).
+ * Plugins reference categories in their `meta.categories` field, as either a
+ * bare key (auto-derive title and plural) or this object (override either).
+ *
+ * Examples (with auto-derive rules):
+ * - `{ key: "app" }`               → title "App", plural "Apps"
+ * - `{ key: "client-credentials" }` → title "Client Credentials", plural "Client Credentials"
+ * - `{ key: "utility" }`           → title "Utility", plural "Utilities"
+ * - `{ key: "http", title: "HTTP Request" }` → plural "HTTP Requests"
+ */
+interface CategoryDefinition {
+    key: string;
+    /** Display title for the category. Auto-derived from `key` if omitted. */
+    title?: string;
+    /** Plural form of `title`. Auto-derived from the resolved title if omitted. */
+    titlePlural?: string;
+}
+interface FunctionRegistryEntry<TSdk = any> {
+    name: string;
+    /**
+     * Human-readable description of the function. Surfaced wherever the
+     * registry is consumed (command help, tool/RPC descriptions, generated
+     * documentation). Prefer providing this directly rather than relying
+     * solely on inputSchema.describe().
+     */
+    description?: string;
+    type?: "list" | "item" | "create" | "update" | "delete" | "function";
+    itemType?: string;
+    returnType?: string;
+    inputSchema?: z.ZodSchema;
+    inputParameters?: Array<{
+        name: string;
+        schema: z.ZodSchema;
+    }>;
+    outputSchema?: z.ZodSchema;
+    /**
+     * Ordered input keys the public surface projects onto positional arguments
+     * (the method's `positional` declaration). Absent when the method takes only
+     * the canonical single bag. Lifted off the materialized method entry by the
+     * surface builder, like `boundResolvers` — a runtime projection, not
+     * descriptive meta.
+     */
+    positional?: readonly string[];
+    categories: string[];
+    resolvers?: Record<string, ResolverMetadata<TSdk, any, any>>;
+    /**
+     * Per-parameter bound resolvers from the new model (imports already captured,
+     * called with `input` only, no sdk). Parallel to the legacy `resolvers` field
+     * and `formatter`: the surface builder lifts these off the materialized method
+     * entry. Additive bridge — populated for migrated `defineMethod` plugins; the
+     * legacy `resolvers` field above stays the source for unmigrated ones.
+     */
+    boundResolvers?: Record<string, BoundResolver>;
+    packages?: string[];
+    /**
+     * True if the plugin is registered only in the experimental SDK
+     * factory. See `PluginMeta.experimental`.
+     */
+    experimental?: boolean;
+    /** Confirmation prompt type - prompts user before executing */
+    confirm?: "create-secret" | "delete";
+    /**
+     * Optional deprecation metadata for commands.
+     */
+    deprecation?: FunctionDeprecation;
+    /**
+     * Short aliases for parameter names (e.g., { request: "X", header: "H" }).
+     * Consumers that render the function as a flag-style command surface use
+     * these as short forms.
+     */
+    aliases?: Record<string, string>;
+    /**
+     * Output formatter, normalized to the bound runtime shape (its imports/sdk
+     * already captured), so consumers call `getContext`/`format` with no sdk.
+     * The surface builder produces this from the method entry — `entry.formatter`
+     * for a migrated plugin, or the legacy `meta.formatter` adapted — so vintage
+     * is invisible here.
+     */
+    formatter?: BoundFormatter;
+    /** Defaults to true. Set to false to suppress --json (e.g. login/logout/init). */
+    supportsJsonOutput: boolean;
+}
+interface FunctionDeprecation {
+    /** User-facing deprecation message for why/how to migrate */
+    message: string;
+}
+interface RegistryResult<TSdk = any> {
+    functions: FunctionRegistryEntry<TSdk>[];
+    categories: {
+        key: string;
+        title: string;
+        titlePlural: string;
+        functions: string[];
+    }[];
+}
+
+/**
+ * ------------------------------
+ * Plugin Type System
+ * ------------------------------
+ *
+ * Plugins receive the sdk as a positional parameter. sdk.context holds shared
+ * internal state (api client, event emission, meta, options, etc.). SDK methods
+ * live at the root, context nests under .context.
+ *
+ * A plugin is (sdk) => partialSdk. `createPluginStack()` accumulates plugins
+ * and materializes a built `Sdk` via `.toSdk()`; `addPlugin(sdk, plugin)`
+ * extends an already-built SDK in place with one more plugin.
+ */
+
+interface PluginProvides extends Record<string, any> {
+    context?: {
+        meta?: Record<string, PluginMeta<any>>;
+        hooks?: MethodHooks;
+        [key: string]: any;
+    };
+}
+interface PluginMeta<TSdk = unknown> {
+    /**
+     * Human-readable description of the plugin function. Used by the CLI (help text),
+     * MCP (tool description), and README generators. When omitted, falls back to
+     * the inputSchema's `.describe()` value or a generic placeholder.
+     */
+    description?: string;
+    /**
+     * Buckets this function belongs to in `getRegistry()` output. Each entry is
+     * either a bare key (`"app"`) for auto-derived titles or a {@link CategoryDefinition}
+     * object to override the title or plural. Only one plugin needs to supply
+     * the object form per category key; object refs win over string refs, so
+     * other plugins in the same bucket can stay on bare strings.
+     */
+    categories?: (string | CategoryDefinition)[];
+    type?: "list" | "item" | "create" | "update" | "delete" | "function";
+    itemType?: string;
+    returnType?: string;
+    inputSchema?: z.ZodSchema;
+    outputSchema?: z.ZodSchema;
+    /**
+     * Item formatter that the registry hands to the CLI/MCP renderer. The
+     * `sdk` param on `fetch` is typed to the plugin's own declared SDK
+     * surface (`TRequires & TProvides`); reaching into another plugin's
+     * method requires adding it to `TRequires` explicitly.
+     */
+    formatter?: OutputFormatter<TSdk, any, any, any>;
+    /**
+     * Per-parameter resolver metadata. Same `TSdk` surfaces in each
+     * resolver's `fetch`/`tryResolveWithoutPrompt` callbacks.
+     */
+    resolvers?: Record<string, ResolverMetadata<TSdk, any, any>>;
+    /** Confirmation prompt type - prompts user before executing */
+    confirm?: "create-secret" | "delete";
+    /**
+     * Marks this plugin as experimental — wrappers can keep it out of
+     * their stable build (typically by gating it behind an
+     * `experimental` subpath import) and the registry can badge it in
+     * generated docs / CLI help. No runtime capability check.
+     */
+    experimental?: boolean;
+    [key: string]: any;
+}
+/**
+ * Plugin interface — 2 type params:
+ *
+ *   TSdk = what this plugin needs (the SDK shape including context)
+ *   TProvides = what this plugin returns (a partial SDK shape)
+ *
+ * The sdk param always includes context.meta, even if TSdk doesn't declare it.
+ */
+interface Plugin<TSdk = {}, TProvides extends PluginProvides = PluginProvides> {
+    (sdk: TSdk & {
+        context: {
+            meta: Record<string, PluginMeta<any>>;
+            hooks: MethodHooks;
+        };
+    }): TProvides;
+}
+/**
+ * A built SDK. Carries the plugins' contributions plus the
+ * `getRegistry` accessor over `context.meta`. No `addPlugin` method
+ * on the shape: extension after build goes through the top-level
+ * `addPlugin(sdk, plugin)` function, which mutates the sdk in place
+ * and narrows the caller's binding via TypeScript's assertion
+ * functions.
+ */
+type Sdk<T = {
+    context: {
+        meta: Record<string, PluginMeta<any>>;
+        hooks: MethodHooks;
+    };
+}> = T & {
+    getRegistry(options?: {
+        package?: string;
+    }): RegistryResult<T>;
+};
+
+/**
+ * ------------------------------
+ * Plugin authoring helpers
+ * ------------------------------
+ *
+ * - `createPluginMethod` / `createPaginatedPluginMethod`: per-method
+ *   primitives that sit inside a `definePlugin` callback and build the
+ *
+ *     { [name]: wrappedFn, context: { meta: { [name]: meta } } }
+ *
+ *   fragment a plugin returns for a single method, wiring up
+ *   `createFunction` / `createPaginatedFunction`, the method-call hooks,
+ *   and the doubled `name` (function key + meta key) in one place.
+ *
+ * Two method helpers (rather than one with a `paginated: true` discriminant)
+ * because the handler signature changes shape across pagination, and
+ * discriminated unions on optional booleans produce noisy TS errors.
+ */
+
+/**
+ * Method-level meta fields. Mirrors `PluginMeta` minus `inputSchema`, which is
+ * passed at the top level alongside the handler and merged into the meta by
+ * the helpers themselves.
+ */
+type MethodMeta<TSdk> = Omit<PluginMeta<TSdk>, "inputSchema">;
+/**
+ * The plugin's own method signature, synthesized from the method config.
+ * Mixed into the resolver-side SDK so a resolver may freely reference the
+ * host plugin's own method (e.g. `appKeyResolver` calling `sdk.getApp`)
+ * without forcing the plugin to declare a circular dependency on itself.
+ *
+ * Uses `any` for options and return: we only need to assert the method
+ * exists on `sdk`, not pin its full signature. Using `TInput`/`TResult`
+ * here would create a circular inference (TSdk depends on TInput/TResult
+ * via the resolvers slot, TInput/TResult are inferred from the handler
+ * which depends on TSdk), and TS resolves the cycle by widening to
+ * `unknown`. With `any`, the resolver check still verifies the method's
+ * presence on the SDK; signature precision for self is the plugin
+ * author's responsibility.
+ *
+ * Not mixed into the handler's `sdk`: handlers run against the SDK that
+ * existed when the plugin was added to the stack (closure-captured), so
+ * self-method access there would be a lie at runtime.
+ */
+type SelfMethod<TName extends string> = {
+    [K in TName]: (options?: any) => any;
+};
+interface PluginMethodConfig<TSdk, TInput, TResult, TName extends string, TResolvers> extends Omit<MethodMeta<TSdk>, "resolvers"> {
+    name: TName;
+    /**
+     * Schema for runtime input validation; drives the handler's `options`
+     * type. For plugins that accept deprecated parameter aliases this is a
+     * `z.union([CanonicalSchema, DeprecatedSchema])` — the registry
+     * unwraps unions and exposes only the first variant (canonical) to
+     * documentation and downstream consumer surfaces.
+     */
+    inputSchema?: z.ZodSchema<TInput>;
+    handler: (args: {
+        sdk: TSdk;
+        options: TInput;
+    }) => Promise<TResult>;
+    /**
+     * Per-parameter resolvers. Each entry's `TSdk` requirement is checked
+     * against the plugin's own `TSdk` (plus the plugin's own method via
+     * {@link SelfMethod}) using {@link ValidResolvers}; mismatches surface
+     * at the offending key. `NoInfer` pins `TSdk` to the `sdk` argument so
+     * resolver entries don't widen the inferred `TSdk`.
+     */
+    resolvers?: ValidResolvers<NoInfer<TSdk & SelfMethod<TName>>, TResolvers> & TResolvers;
+}
+type PluginMethodReturn<TName extends string, TInput, TResult> = {
+    [K in TName]: (options?: TInput) => Promise<TResult>;
+} & {
+    context: {
+        meta: {
+            [K in TName]: PluginMeta;
+        };
+    };
+};
+/**
+ * Build the method fragment for a non-paginated SDK method. Used inside a
+ * `definePlugin(...)` callback:
+ *
+ *   export const getProfilePlugin = definePlugin(
+ *     (sdk: ApiPluginProvides & EventEmissionProvides) =>
+ *       createPluginMethod(sdk, {
+ *         name: "getProfile",
+ *         categories: ["account"],
+ *         inputSchema: GetProfileSchema,
+ *         handler: async ({ sdk }) => { ... },
+ *       }),
+ *   );
+ */
+declare function createPluginMethod<const TName extends string, TSdk extends {
+    context: unknown;
+}, TInput, TResult, const TResolvers extends Record<string, ResolverMetadata<any, any, any>> = {}>(sdk: TSdk, config: PluginMethodConfig<TSdk, TInput, TResult, TName, TResolvers>): PluginMethodReturn<TName, TInput, TResult>;
+interface PaginatedPluginMethodConfigBase<TSdk, TInput, TName extends string, TResolvers> extends Omit<MethodMeta<TSdk>, "resolvers"> {
+    name: TName;
+    /** Same semantics as `createPluginMethod`'s `inputSchema`. */
+    inputSchema?: z.ZodSchema<TInput>;
+    /**
+     * Optional default page size when the caller doesn't pass one. Mirrors
+     * `createPaginatedFunction`'s `defaultPageSize` arg.
+     */
+    defaultPageSize?: number;
+    /** See {@link PluginMethodConfig.resolvers}. */
+    resolvers?: ValidResolvers<NoInfer<TSdk & SelfMethod<TName>>, TResolvers> & TResolvers;
+}
+/**
+ * A page whose *only* own keys are `data` / `nextCursor`. Used to constrain
+ * the Standard overload: a raw envelope with extra keys (a JSON:API
+ * `links`/`meta`, a top-level `next`, etc.) is NOT a `StrictPage`, so it falls
+ * through to the Adapted overload and `adaptPage` becomes required. Each excess
+ * key is mapped to `?: never`, which a real value (e.g. `links: {...}`) can't
+ * satisfy — that's what a plain `SdkPage` assignability check (which allows
+ * excess keys structurally) misses.
+ */
+type StrictPage<TResponse> = SdkPage<unknown> & {
+    [K in Exclude<keyof TResponse, keyof SdkPage<unknown>>]?: never;
+};
+/**
+ * Config for a paginated method whose handler already returns a clean page
+ * (`{ data, nextCursor? }` and nothing else — see `StrictPage`, enforced on
+ * the overload). No `adaptPage` needed; `TItem` is sourced from the handler's
+ * `data`. Interface extension keeps this a single flattened object type (not
+ * an intersection), preserving clean inference of the `resolvers` /
+ * `TResolvers` slot.
+ */
+interface PaginatedPluginMethodConfigStandard<TSdk, TInput, TResponse, TName extends string, TResolvers> extends PaginatedPluginMethodConfigBase<TSdk, TInput, TName, TResolvers> {
+    handler: (args: {
+        sdk: TSdk;
+        options: TInput & {
+            cursor?: string;
+            pageSize?: number;
+        };
+    }) => Promise<TResponse>;
+    /** No adapter: the handler already returns a page. */
+    adaptPage?: undefined;
+}
+/**
+ * Config for a paginated method whose handler returns a raw upstream shape
+ * (`TResponse`, e.g. a JSON:API `links.next` envelope). `adaptPage` is required
+ * to translate it into a page. `TItem` is sourced from `TResponse` (`ItemOf`),
+ * not the adapter — the adapter is item-agnostic (relocates the cursor; items
+ * are finalized in the handler's `data`), hence `NoInfer`, so a generic adapter
+ * (e.g. `<T>(r) => SdkPage<T>`) doesn't collapse `TItem` to `unknown`.
+ */
+interface PaginatedPluginMethodConfigAdapted<TSdk, TInput, TResponse, TItem, TName extends string, TResolvers> extends PaginatedPluginMethodConfigBase<TSdk, TInput, TName, TResolvers> {
+    handler: (args: {
+        sdk: TSdk;
+        options: TInput & {
+            cursor?: string;
+            pageSize?: number;
+        };
+    }) => Promise<TResponse>;
+    adaptPage: (response: TResponse) => SdkPage<NoInfer<TItem>>;
+}
+type ItemOf<TResponse> = TResponse extends SdkPage<infer TItem> ? TItem : TResponse extends {
+    data: readonly (infer TItem)[];
+} ? TItem : never;
+type PaginatedPluginMethodReturn<TName extends string, TInput, TItem> = {
+    [K in TName]: (options?: TInput & {
+        cursor?: string;
+        pageSize?: number;
+        maxItems?: number;
+    }) => PaginatedSdkResult<TItem>;
+} & {
+    context: {
+        meta: {
+            [K in TName]: PluginMeta;
+        };
+    };
+};
+/**
+ * Paginated variant of `createPluginMethod`. Two overloads enforce the
+ * response contract at compile time:
+ *
+ *  - **Standard** — the handler returns a strict `SdkPage<TItem>`
+ *    (`{ data, nextCursor? }` and nothing else); no `adaptPage`.
+ *  - **Adapted** — the handler returns a raw upstream shape and `adaptPage` is
+ *    *required* to translate it.
+ *
+ * A handler that returns neither a page-like shape nor pairs a raw shape with
+ * `adaptPage` matches no overload and is a compile error.
+ *
+ *   createPaginatedPluginMethod(sdk, {
+ *     name: "listThings",
+ *     inputSchema: ListThingsSchema,
+ *     adaptPage: (res) => ({ data: res.items, nextCursor: res.next }),
+ *     handler: ({ sdk, options }) => sdk.context.api.get("/things", { ... }),
+ *   });
+ */
+declare function createPaginatedPluginMethod<const TName extends string, TSdk extends {
+    context: unknown;
+}, TInput, TResponse extends StrictPage<TResponse>, TItem = ItemOf<TResponse>, const TResolvers extends Record<string, ResolverMetadata<any, any, any>> = {}>(sdk: TSdk, config: PaginatedPluginMethodConfigStandard<TSdk, TInput, TResponse, TName, TResolvers>): PaginatedPluginMethodReturn<TName, TInput, TItem>;
+declare function createPaginatedPluginMethod<const TName extends string, TSdk extends {
+    context: unknown;
+}, TInput, TResponse, TItem = ItemOf<TResponse>, const TResolvers extends Record<string, ResolverMetadata<any, any, any>> = {}>(sdk: TSdk, config: PaginatedPluginMethodConfigAdapted<TSdk, TInput, TResponse, TItem, TName, TResolvers>): PaginatedPluginMethodReturn<TName, TInput, TItem>;
+/**
+ * Maps a tuple of plugins to a tuple of their TSdk requirement types.
+ *
+ *   SdkRequirementsOf<[Plugin<{ api }, _>, Plugin<{ options }, _>]>
+ *     = [{ api }, { options }]
+ */
+type SdkRequirementsOf<T extends readonly Plugin<any, any>[]> = {
+    [K in keyof T]: T[K] extends Plugin<infer Sdk, any> ? Sdk : never;
+};
+/**
+ * Maps a tuple of plugins to a tuple of their TProvides output types.
+ *
+ *   ProvidesOf<[Plugin<_, { hello }>, Plugin<_, { goodbye }>]>
+ *     = [{ hello }, { goodbye }]
+ */
+type ProvidesOf<T extends readonly Plugin<any, any>[]> = {
+    [K in keyof T]: T[K] extends Plugin<any, infer Provides> ? Provides : never;
+};
+/**
+ * Intersects every member of a tuple into a single combined type. The
+ * result is an object that has every property of every member at once.
+ *
+ *   IntersectAll<[{ api }, { options }]> = { api } & { options }
+ *   IntersectAll<[]>                     = {}
+ *
+ * Walks recursively: head & IntersectAll<tail>, base case is the empty
+ * tuple. Why intersection (`&`) and not union (`|`): the composed plugin
+ * must require ALL of the sub-plugins' needs at once — an SDK that has
+ * both `api` AND `options` — not "either api or options."
+ */
+type IntersectAll<T extends readonly unknown[]> = T extends readonly [
+    infer Head,
+    ...infer Tail
+] ? Head & IntersectAll<Tail> : {};
+/**
+ * The TSdk a composed plugin requires: every sub-plugin's TSdk requirement,
+ * all at once. Composing a plugin that needs `{ api }` with one that needs
+ * `{ options }` yields a composed plugin that needs `{ api } & { options }`.
+ */
+type ComposeSdk<T extends readonly Plugin<any, any>[]> = IntersectAll<SdkRequirementsOf<T>>;
+/**
+ * What a composed plugin provides: every sub-plugin's TProvides combined.
+ * Composing a plugin that provides `{ hello }` with one that provides
+ * `{ goodbye }` yields `{ hello } & { goodbye }`.
+ */
+type ComposeProvides<T extends readonly Plugin<any, any>[]> = IntersectAll<ProvidesOf<T>>;
+/**
+ * @deprecated Use {@link createPluginStack} instead. It carries the same
+ * collision-detection and hook-composition behavior and supports
+ * per-step `{ override: true }` for intentional duplicates. Migration
+ * (note the stack emits a definition, not a bare function):
+ *
+ *   composePlugins(a, b, c)
+ *   //  →
+ *   createPluginStack().use(a).use(b).use(c).toPlugin({ name: "bundle" })
+ *
+ * Bundles N plugins into a single plugin so a consumer can call
+ * `.use(combined)` once on a stack. Bag mode: sub-plugins must not
+ * depend on each other; TSdk on sub-plugins is the intersection of
+ * every sub-plugin's requirements (so the type system never exposes
+ * one sub-plugin's contributions to another).
+ */
+declare function composePlugins<const Ts extends readonly Plugin<any, any>[]>(...plugins: Ts): Plugin<ComposeSdk<Ts>, ComposeProvides<Ts>>;
+/**
+ * A typed builder that accumulates plugins into an immutable linked list.
+ * Each `.use` returns a new stack instance (cons-style); the original
+ * stack stays usable for branching. Call `toPlugin()` to collapse the
+ * accumulated chain into a single `Plugin<TRequires, TProvides>`.
+ *
+ * Type params: `TRequires` is the external surface declared on
+ * `createPluginStack<TRequires>()` (what the outer sdk will provide);
+ * `TProvides` accumulates every registration's provides.
+ */
+interface PluginStack<TRequires, TProvides extends PluginProvides> {
+    /**
+     * Register a bare plugin function. Its required surface is constrained
+     * to `TRequires & TProvides` (the external requirements plus everything
+     * provided by earlier `.use` calls), so registration order is enforced
+     * per step: a plugin that reads a dependency at construction can only be
+     * registered after a plugin that provides it. This stack collapses to a
+     * single function plugin and runs its entries in registration order, so
+     * the type-level order matches the runtime order.
+     *
+     * `{ override: true }` lets a registration replace an earlier root/meta
+     * key it would otherwise collide with.
+     */
+    use<TNewProvides extends PluginProvides>(plugin: Plugin<TRequires & TProvides, TNewProvides>, options?: {
+        override?: boolean;
+    }): PluginStack<TRequires, TProvides & TNewProvides>;
+    /**
+     * Collapse the accumulated registrations into a single bare function
+     * plugin. Its TSdk is `TRequires` (the declared external surface);
+     * in-stack inter-plugin dependencies are resolved when its setup runs.
+     * A head lifts it into the module model with `fromFunctionPlugin`.
+     */
+    toPlugin(): Plugin<TRequires, TProvides>;
+    /**
+     * Build the stack into a sealed, ready-to-use SDK. Eagerly applies the
+     * resolved order: each plugin runs once during `toSdk`, contributions
+     * merge into a single accumulator, and the result is wrapped as an
+     * `Sdk<TRequires & TProvides>`. The returned SDK has `context` and
+     * `getRegistry`, but no plugin-registration method.
+     * To extend a built SDK, use the top-level {@link addPlugin}.
+     */
+    toSdk(): Sdk<TRequires & TProvides>;
+}
+/**
+ * Create an empty plugin stack. Pass a type parameter to declare external
+ * SDK requirements that every plugin in the stack can rely on:
+ *
+ *   const tablesPlugin = createPluginStack<FetchPluginProvides>()
+ *     .use(apiPlugin)
+ *     .use(listTablesPlugin)
+ *     .use(getTablePlugin)
+ *     .toPlugin({ name: "tables" });
+ *
+ *   const sdk = createPluginStack()
+ *     .use(fetchPlugin)   // provides FetchPluginProvides
+ *     .use(tablesPlugin)  // PluginDefinition<FetchPluginProvides, ...>
+ *     .toSdk();
+ *
+ * The stack itself is immutable: calling `.use` returns a new stack
+ * without mutating the original, so you can branch off a base stack for
+ * different consumers. Until the stack materializes, no plugin functions
+ * run.
+ */
+declare function createPluginStack<TRequires = object>(): PluginStack<TRequires, {
+    context: {
+        meta: Record<string, PluginMeta>;
+        hooks: MethodHooks;
+    };
+}>;
+
+/**
+ * Define a method leaf. The plugin IS the function; `createSdk` (or a
+ * dependent's `imports`) binds it under its bare `name`. `imports` is typed
+ * from the declared `imports` array. `namespace` sets the plugin's id
+ * (`namespace/name`).
+ *
+ * The `output` mode shapes `run`'s result into the public surface and drives
+ * the overload that types the call: raw (default, passthrough), `item`
+ * (`run` returns `T`, surfaced as `Promise<{ data: T }>`), or `list` (`run`
+ * returns one `SdkPage`, surfaced as `PaginatedSdkResult`). See Output.
+ */
+declare function defineMethod<const TName extends string, TInput, TOutput, const TPositional extends readonly (keyof TInput & string)[] = readonly [], const TImports extends ImportsInput = readonly [], const TNamespace extends string = "", TState = undefined>(config: {
+    name: TName;
+    namespace?: TNamespace;
+    imports?: TImports & StaticList<TImports>;
+    /** Validates `input` and drives its type: when given, `input` is the schema's
+     * output and no `run` annotation is needed. */
+    inputSchema?: z.ZodType<TInput>;
+    resolvers?: Record<string, Resolver>;
+    formatter?: Formatter;
+    output?: "raw" | {
+        type: "raw";
+    };
+    positional?: TPositional;
+    setup?: (bag: {
+        imports: ImportsOf<TImports>;
+    }) => TState;
+    run: (bag: MethodRunBag<ImportsOf<TImports>, TInput, TState>) => TOutput;
+} & LeafMetaFields): MethodPlugin<TName, TInput, TOutput, TPositional> & LeafSummary<TNamespace, TName, TImports>;
+declare function defineMethod<const TName extends string, TInput, TData, const TImports extends ImportsInput = readonly [], const TNamespace extends string = "", TState = undefined>(config: {
+    name: TName;
+    namespace?: TNamespace;
+    imports?: TImports & StaticList<TImports>;
+    inputSchema?: z.ZodType<TInput>;
+    resolvers?: Record<string, Resolver>;
+    formatter?: Formatter;
+    output: "item" | {
+        type: "item";
+    };
+    setup?: (bag: {
+        imports: ImportsOf<TImports>;
+    }) => TState;
+    run: (bag: MethodRunBag<ImportsOf<TImports>, TInput, TState>) => TData;
+} & LeafMetaFields): MethodPlugin<TName, TInput, Promise<{
+    data: Awaited<TData>;
+}>> & LeafSummary<TNamespace, TName, TImports>;
+declare function defineMethod<const TName extends string, TInput, TResponse extends StrictPage$1<TResponse>, TItem = ItemOf$1<TResponse>, const TImports extends ImportsInput = readonly [], const TNamespace extends string = "", TState = undefined>(config: {
+    name: TName;
+    namespace?: TNamespace;
+    imports?: TImports & StaticList<TImports>;
+    inputSchema?: z.ZodType<TInput>;
+    resolvers?: Record<string, Resolver>;
+    formatter?: Formatter;
+    output: "list" | {
+        type: "list";
+        adaptPage?: undefined;
+        defaultPageSize?: number;
+    };
+    setup?: (bag: {
+        imports: ImportsOf<TImports>;
+    }) => TState;
+    run: (bag: MethodRunBag<ImportsOf<TImports>, TInput & PageFetchInput, TState>) => TResponse | Promise<TResponse>;
+} & LeafMetaFields): MethodPlugin<TName, TInput & PaginatedCallInput, PaginatedSdkResult<TItem>> & LeafSummary<TNamespace, TName, TImports>;
+declare function defineMethod<const TName extends string, TInput, TResponse, TItem, const TImports extends ImportsInput = readonly [], const TNamespace extends string = "", TState = undefined>(config: {
+    name: TName;
+    namespace?: TNamespace;
+    imports?: TImports & StaticList<TImports>;
+    inputSchema?: z.ZodType<TInput>;
+    resolvers?: Record<string, Resolver>;
+    formatter?: Formatter;
+    output: {
+        type: "list";
+        adaptPage: (response: TResponse) => SdkPage<TItem>;
+        defaultPageSize?: number;
+    };
+    setup?: (bag: {
+        imports: ImportsOf<TImports>;
+    }) => TState;
+    run: (bag: MethodRunBag<ImportsOf<TImports>, TInput & PageFetchInput, TState>) => TResponse | Promise<TResponse>;
+} & LeafMetaFields): MethodPlugin<TName, TInput & PaginatedCallInput, PaginatedSdkResult<TItem>> & LeafSummary<TNamespace, TName, TImports>;
+/**
+ * Define an input resolver: a method attachment for one of its parameters. Like
+ * `defineMethod` it declares its own `imports`, and its callbacks receive a
+ * narrowed `imports` bag, NOT the whole SDK. The graph reaches its imports
+ * (materialize + dedup) but they never enter the host method's run-bag, so a
+ * resolver may even import its own host method. At createSdk the imports are
+ * captured, so the CLI later calls `listItems(input)` / `tryResolveWithoutPrompt
+ * (input)` with no sdk argument.
+ *
+ * The `type` selects the kind (a {@link Resolver} union member); the config
+ * narrows to it. `requireParameters` names sibling parameters that must resolve
+ * first (it reads their values from `input`), independent of `imports` (the
+ * SDK-capability graph). `object` / `array` resolvers compose nested resolvers;
+ * an import-bearing resolver reached from a built field lives in `definitions`
+ * (reached by `{ ref }`), since it can't be inlined when the field set is built
+ * dynamically.
+ */
+declare function defineResolver<const TImports extends ImportsInput = readonly [], TItem = unknown, TInput = Record<string, unknown>, TContext = unknown>(config: {
+    type?: "dynamic";
+    imports?: TImports & StaticList<TImports>;
+    requireParameters?: readonly string[];
+    inputType?: "text" | "password" | "email" | "search";
+    placeholder?: string;
+    /** Compute side-context once, before `listItems` (pre-fetch, no items yet),
+     * with the narrowed `imports`. Its result flows into `listItems` and `prompt`
+     * as `context`, so one place resolves what both the fetch and the render need
+     * (e.g. a capability gate). May re-run across re-asks; keep it cheap. */
+    getContext?: (bag: {
+        imports: ImportsOf<TImports>;
+        input: TInput;
+    }) => PromiseLike<TContext>;
+    /** Produce the candidate list. Behaves like an SDK list method (returns a page
+     * / paginated result, never a bare array). `cursor` is the stateless "load
+     * more" re-entry hook. */
+    listItems?: (bag: {
+        imports: ImportsOf<TImports>;
+        input: TInput;
+        /** The value `getContext` returned, if any. */
+        context?: TContext;
+        /** Free-text term the CLI injects for search-mode resolvers; a separate key
+         * from `input`, so it never collides with a parameter named `search`. */
+        search?: string;
+        cursor?: string;
+    }) => ListItemsResult<TItem>;
+    prompt?: (bag: {
+        items: TItem[];
+        input: TInput;
+        /** The value `getContext` returned, if any. */
+        context?: TContext;
+    }) => ResolverPromptConfig;
+    /** Resolve with no user input (e.g. a configured default), skipping the prompt. */
+    tryResolveWithoutPrompt?: (bag: {
+        imports: ImportsOf<TImports>;
+        input: TInput;
+    }) => Promise<{
+        resolvedValue: unknown;
+    } | null>;
+    /** Search-mode exact match: the typed `search` already names a valid value, so
+     * return it and skip the picker. Returns null to fall through to `listItems`. */
+    tryResolveFromSearch?: (bag: {
+        imports: ImportsOf<TImports>;
+        input: TInput;
+        search?: string;
+    }) => Promise<{
+        resolvedValue: unknown;
+    } | null>;
+}): DynamicResolver;
+declare function defineResolver(config: {
+    type: "static";
+    requireParameters?: readonly string[];
+    inputType?: "text" | "password" | "email" | "search";
+    placeholder?: string;
+}): StaticResolver;
+declare function defineResolver(config: {
+    type: "constant";
+    value: unknown;
+    requireParameters?: readonly string[];
+}): ConstantResolver;
+declare function defineResolver(config: {
+    type: "info";
+    text: string;
+}): InfoResolver;
+declare function defineResolver<const TImports extends ImportsInput = readonly [], TInput = Record<string, unknown>>(config: {
+    type: "object";
+    imports?: TImports & StaticList<TImports>;
+    requireParameters?: readonly string[];
+    properties?: Record<string, Field>;
+    /** Build the property map when the key set is dynamic (re-invoked as `input`
+     * grow). Returns the map raw, no envelope. */
+    getProperties?: (bag: {
+        imports: ImportsOf<TImports>;
+        input: TInput;
+    }) => PromiseLike<Record<string, Field>>;
+    definitions?: Record<string, Resolver>;
+}): ObjectResolver;
+declare function defineResolver(config: {
+    type: "array";
+    requireParameters?: readonly string[];
+    items: Resolver | ResolverRef;
+    minItems?: number;
+    maxItems?: number;
+    /** Coarse value type of each element, so a free-text item answer coerces
+     * (e.g. `"5"` → `5`) like object fields do via `Field.valueType`. */
+    itemValueType?: string;
+    definitions?: Record<string, Resolver>;
+}): ArrayResolver;
+/**
+ * Define an output formatter: a method attachment for its output. `getContext`
+ * runs once per rendered page with the narrowed `imports` bag (no sdk); it
+ * receives the items on the page and the context accumulated from prior pages,
+ * and returns the (possibly extended) context — so page-independent context
+ * (e.g. field labels) is fetched once, while per-item context grows as pages
+ * arrive. `format` is pure and synchronous, turning one item + context into a
+ * `FormattedItem`. Anything needing SDK data belongs in `getContext`, not
+ * `format`. Both callbacks get the method's `input` (complete, since the
+ * formatter runs after the method).
+ */
+declare function defineFormatter<const TImports extends ImportsInput = readonly [], TItem = unknown, TInput = Record<string, unknown>, TContext = unknown>(config: {
+    imports?: TImports & StaticList<TImports>;
+    getContext?: (bag: {
+        imports: ImportsOf<TImports>;
+        items: TItem[];
+        input: TInput;
+        context?: TContext;
+    }) => Promise<TContext>;
+    format: (bag: {
+        item: TItem;
+        input: TInput;
+        context?: TContext;
+    }) => FormattedItem;
+}): Formatter;
+/**
+ * Declare a stand-in for a method registered elsewhere (a configured factory
+ * plugin, or just a different module). You reference it by `id` (`namespace/name`,
+ * or a bare name); the binding is the id's last segment, and resolution by id
+ * binds the real implementation at materialization (constraints 3-4). Its `run`
+ * throws, since a stand-in must never be the implementation.
+ */
+declare function declareMethod<const TId extends string, TInput = unknown, TOutput = unknown>(config: {
+    id: LiteralString<TId>;
+}): MethodPlugin<LastSegment<TId>, TInput, TOutput> & PluginSummary<TId, never>;
+/**
+ * Define a property leaf. Either a static `value` or a computed `get` (eager,
+ * dependencies first, like `setup`). `createSdk`, a dependent's `imports`, or
+ * an aggregate's re-export binds it under its bare `name` and yields the value.
+ */
+declare function defineProperty<const TName extends string, TValue, const TNamespace extends string = "">(config: {
+    name: TName;
+    namespace?: TNamespace;
+    value: TValue;
+} & LeafMetaFields): PropertyPlugin<TName, TValue> & PluginSummary<never, IdOf<TNamespace, TName>>;
+declare function defineProperty<const TName extends string, TValue, const TImports extends ImportsInput = readonly [], const TNamespace extends string = "", TState = undefined>(config: {
+    name: TName;
+    namespace?: TNamespace;
+    imports?: TImports & StaticList<TImports>;
+    setup?: (bag: {
+        imports: ImportsOf<TImports>;
+    }) => TState;
+    get: (bag: {
+        imports: ImportsOf<TImports>;
+        state: TState;
+    }) => TValue;
+} & LeafMetaFields): PropertyPlugin<TName, TValue> & LeafSummary<TNamespace, TName, TImports>;
+/**
+ * Declare a stand-in for a property registered elsewhere (a configured factory
+ * plugin, e.g. the api client built from options). Carries only a name and a
+ * provides type; dependents reference it for typing, and resolution by id binds
+ * the real property at materialization (constraints 3-4, the property twin of
+ * `declareMethod`). A stand-in left with no real implementation is a missing
+ * dependency (a runtime error from `createSdk`).
+ */
+declare function declareProperty<const TId extends string, TValue = unknown>(config: {
+    id: LiteralString<TId>;
+}): PropertyPlugin<LastSegment<TId>, TValue> & PluginSummary<TId, never>;
+/**
+ * Declare a stand-in for a whole aggregate (module) registered elsewhere: the
+ * aggregate twin of `declareMethod` / `declareProperty`. `exports` is an array
+ * of leaf stand-ins describing the module's surface, so dependents that import
+ * it get typed bindings; resolution by id binds the real aggregate at
+ * materialization, and a stand-in left with no implementation is a missing
+ * dependency. Use it to depend on a module abstractly and provide the concrete
+ * one at the composition root (the tree-shakeable / swappable shape).
+ */
+declare function declarePlugin<const TId extends string, const TExports extends readonly AnyLeafPlugin[] = readonly []>(config: {
+    id: LiteralString<TId>;
+    exports?: TExports & StaticList<TExports>;
+}): AggregatePlugin<LastSegment<TId>, ArrayExports<TExports>> & PluginSummary<TId, never>;
+/**
+ * Define a plugin. Two forms, one function:
+ *
+ * - **Object form** — a module that re-exports child plugins and may wrap
+ *   imported methods with `middleware`. `exports` mirrors `imports`: an
+ *   array where a leaf binds under its own name (`[greet]` binds "greet"), a
+ *   module spreads its bindings, and `selectExports(dep, { hi: "greet" })`
+ *   subsets/renames. It is optional, so a pure-middleware module can omit it.
+ *   Re-exporting implies a dependency on the child. A middleware key names the
+ *   target's binding, a direct dependency.
+ * - **Function form** — the legacy function-plugin identity wrapper: it returns
+ *   the function unchanged but constrains its return to `PluginProvides` and
+ *   preserves the narrow inferred shape, so callers derive `*PluginProvides`
+ *   via `ReturnType<typeof plugin>`. This is how the existing ~90 plugins are
+ *   written; they run on the module model through the legacy bridge.
+ */
+declare function definePlugin<TSdk, TProvides extends PluginProvides>(fn: (sdk: TSdk & {
+    context: {
+        meta: Record<string, PluginMeta>;
+    };
+}) => TProvides): (sdk: TSdk & {
+    context: {
+        meta: Record<string, PluginMeta>;
+    };
+}) => TProvides;
+declare function definePlugin<const TName extends string, const TImports extends ImportsInput = readonly [], const TNamespace extends string = "", const TExports extends readonly (AnyLeafPlugin | AnyAggregatePlugin)[] = readonly []>(config: {
+    name: TName;
+    namespace?: TNamespace;
+    imports?: TImports & StaticList<TImports>;
+    exports?: TExports & StaticList<TExports>;
+    middleware?: MiddlewareMap<ImportsOf<TImports>>;
+}): AggregatePlugin<TName, ArrayExports<TExports>> & AggregateSummary<TNamespace, TName, TImports, TExports>;
+
+/**
+ * A `selectExports` spec: a bare export name to keep (`"getApp"`), or a rename
+ * map whose key is the resulting binding and value the source export name
+ * (`{ getUser: "getProfile" }` is `export { getProfile as getUser }`).
+ */
+type SelectSpec<TExports> = (keyof TExports & string) | {
+    [newName: string]: keyof TExports & string;
+};
+/** The export record one spec contributes: a kept name maps to its own leaf; a
+ * rename map keys each new name to the leaf at the source name. */
+type ResolveSpec<TExports extends Record<string, AnyLeafPlugin>, S> = S extends string | number ? S extends keyof TExports ? {
+    [K in S]: TExports[S];
+} : never : {
+    [K in keyof S]: S[K] extends keyof TExports ? TExports[S[K]] : never;
+};
+/** Ensure the computed export record satisfies the `AggregatePlugin` constraint
+ * (an empty/degenerate selection collapses to a bare exports record). */
+type AsExports<T> = T extends Record<string, AnyLeafPlugin> ? T : Record<string, AnyLeafPlugin>;
+/**
+ * Select (and optionally rename) a subset of a module's exports, the ES
+ * `{ a, b, c as d }` clause. Works the same in `imports` (import) and
+ * `exports` (re-export): each spec is a bare name to keep or a `{ new: "old" }`
+ * rename map. An unknown source name throws. Returns a re-export descriptor (a
+ * synthetic aggregate over the chosen bindings) that drops straight into either
+ * array; the selected bindings keep the source module's identity.
+ */
+declare function selectExports<TExports extends Record<string, AnyLeafPlugin>, const TSpecs extends readonly SelectSpec<TExports>[]>(source: AggregatePlugin<string, TExports>, ...specs: TSpecs): AggregatePlugin<string, AsExports<UnionToIntersection<{
+    [I in keyof TSpecs]: ResolveSpec<TExports, TSpecs[I]>;
+}[number]>>>;
+
+/**
+ * Lift a legacy function plugin into the module model. The
+ * returned plugin runs `fn` at materialization and surfaces its root methods;
+ * `createPluginStack().toPlugin()` is built on this, and `addPlugin` uses it for
+ * external function plugins. `fn`'s `context` contributions merge into the live
+ * `SdkContext`; its other root keys become the surface.
+ */
+declare function fromFunctionPlugin<TProvides extends PluginProvides>(fn: (sdk: any) => TProvides, config: {
+    name: string;
+    namespace?: string;
+}): LegacyPlugin<TProvides & {
+    getRegistry: (options?: {
+        package?: string;
+    }) => RegistryResult;
+}>;
+/**
+ * Build a {@link LegacyMergePlugin}: pass the collapsed legacy stack
+ * (`stack.toPlugin()`) as `legacy` and the migrated module-model plugins as
+ * `plugin`. `createSdk(defineLegacyMerge({...}))` surfaces both.
+ */
+declare function defineLegacyMerge<TProvides extends PluginProvides, const TPlugin extends AnyPlugin>(args: {
+    name: string;
+    namespace?: string;
+    legacy: (sdk: any) => TProvides;
+    plugin: TPlugin;
+}): LegacyMergePlugin<TProvides, TPlugin>;
+
+/**
+ * Escape hatch. A built-in privileged plugin whose value is the live
+ * `SdkContext`: the raw plugin graph plus the legacy compat fields. Importing it
+ * (`imports.context`) lets a body reach internals the model otherwise keeps
+ * private.
+ *
+ * Prefer not to depend on this. The `SdkContext` shape is an implementation
+ * detail and may change without notice; import the specific plugins you need,
+ * and use `getRegistryPlugin` for surface introspection. It exists mainly so a
+ * not-yet-migrated plugin can read legacy `context.*` fields during migration.
+ * Its value is injected at materialization, not authored.
+ */
+declare const dangerousContextPlugin: PropertyPlugin<"context", SdkContext>;
+/**
+ * A built-in that reports the live SDK surface as the canonical
+ * {@link RegistryResult}. It is just a method depending on `dangerousContextPlugin` (no
+ * new privilege): re-export it to put `getRegistry()` on the SDK surface. Reads
+ * `context.surface` at call time, so it reflects any post-seal `addPlugin`
+ * additions, and produces the same registry shape the heads (CLI / MCP / docs)
+ * consume.
+ */
+declare const getRegistryPlugin: MethodPlugin<"getRegistry", {
+    package?: string | undefined;
+} | undefined, RegistryResult<any>, readonly []> & LeafSummary<"kitcore", "getRegistry", readonly [PropertyPlugin<"context", SdkContext>]>;
+
+/**
+ * The external escape-hatch key for an SDK's context. A Symbol,
+ * not a string, so it stays off the string surface (which is exactly the root's
+ * exports) and is collision-free and clearly internal. It is attached at
+ * runtime but kept OUT of the public SDK type (a `unique symbol` in an exported
+ * type can't be named in a consumer's emitted `.d.ts`); reach it through the
+ * typed `getContext(sdk)` accessor.
+ */
+declare const CONTEXT: unique symbol;
+/** The off-surface escape hatch to an SDK's `SdkContext`. */
+declare function getContext(sdk: unknown): SdkContext;
+/**
+ * Materialize one plugin into an SDK whose surface is that plugin's exports.
+ * A method root surfaces its callable under its bare name; a property root its
+ * value; an aggregate root its export bindings.
+ */
+declare function createSdk<P extends AnyMethodPlugin>(root: P & CompletenessOf<P>): MethodSdkOf<P>;
+declare function createSdk<P extends AnyPropertyPlugin>(root: P & CompletenessOf<P>): PropertySdkOf<P>;
+declare function createSdk<P extends AnyAggregatePlugin>(root: P & CompletenessOf<P>): AggregateSdkOf<P>;
+declare function createSdk<TSurface>(root: LegacyPlugin<TSurface>): TSurface & SdkInternals;
+declare function createSdk<TProvides extends PluginProvides, TPlugin extends AnyPlugin>(root: LegacyMergePlugin<TProvides, TPlugin>): TProvides & {
+    getRegistry: (options?: {
+        package?: string;
+    }) => RegistryResult;
+} & AddedSurface<TPlugin> & SdkInternals;
+/**
+ * Extend an already-built SDK in place with one more plugin (the post-seal
+ * extension path). Dispatches on shape: a module-model plugin (`defineMethod` /
+ * `defineProperty` / `definePlugin`) is materialized incrementally into the live
+ * graph; a legacy function plugin runs through the legacy merge. Either way the
+ * caller's `sdk` binding is narrowed to include the addition.
+ */
+declare function addPlugin<TSdk extends object, P>(sdk: TSdk, plugin: P, options?: {
+    override?: boolean;
+}): asserts sdk is TSdk & AddedSurface<P>;
+
+/**
+ * Public types for the resolution engine: the serializable protocol a host
+ * drives (`start` / `step`), the in-process `resolve` sugar's answerer, and the
+ * reflection shapes (`listMethods` / `getMethod` / `listChoices`). The engine
+ * turns a method's partial input into a complete, validated input by resolving
+ * each parameter, interacting with the host only when it must. See the kitcore
+ * README's "Resolving inputs: controllers" section for worked host examples.
+ */
+/** A candidate value the host renders; the host composes its own display label
+ * from `label`/`hint`. `value` is what flows back in a `choose` action. */
+interface ControllerChoice {
+    label: string;
+    value: string;
+    hint?: string;
+}
+/**
+ * A move the host can make in response to a question, self-described so an agent
+ * can follow it without the type definitions (HATEOAS-lite). `description` says
+ * what it does; `supply` names the single payload field to include when sending
+ * the action (absent = no payload). Enriching an affordance with a full field
+ * schema later is additive and never changes the {@link ControllerAction} it
+ * produces.
+ */
+interface ControllerAffordance {
+    action: ControllerAction["type"];
+    description: string;
+    supply?: "value" | "term";
+}
+/** A question the host renders. Discriminated on `type`; the available moves are
+ * the self-describing `actions` list (single source of truth, no flags). */
+type ControllerQuestion = {
+    type: "select";
+    message: string;
+    /** What this field is, for an agent that lacks the schema. */
+    description?: string;
+    choices: ControllerChoice[];
+    actions: ControllerAffordance[];
+    /** A multi-select (the resolver's `prompt` returned `type: "checkbox"`);
+     * the `choose` action then carries an array. */
+    multiple?: boolean;
+    /** Informational, non-selectable lines (`PromptConfig.notes`), e.g. a
+     * capability hint. A host renders them dimmed, after the choices. */
+    notes?: string[];
+} | {
+    type: "input";
+    message: string;
+    description?: string;
+    inputType: "text" | "password" | "email";
+    placeholder?: string;
+    actions: ControllerAffordance[];
+} | {
+    type: "collection";
+    message: string;
+    description?: string;
+    count: number;
+    min: number;
+    /** Absent when the array is unbounded (no `maxItems`); a finite cap
+     * otherwise. Omitted rather than `Infinity` so the question stays JSON. */
+    max?: number;
+    actions: ControllerAffordance[];
+};
+/** The host's response to a question. The wire shape is frozen: a fuller
+ * HATEOAS affordance schema would still produce exactly these. */
+type ControllerAction = {
+    type: "choose";
+    value: string | string[];
+} | {
+    type: "search";
+    term: string;
+} | {
+    type: "more";
+} | {
+    type: "custom";
+    value: string;
+} | {
+    type: "skip";
+} | {
+    type: "add";
+} | {
+    type: "done";
+} | {
+    type: "cancel";
+} | {
+    type: "retry";
+};
+/** What `start` / `step` return alongside the next state. `ask` carries a
+ * question to answer; `done` the fully resolved input; `invalid` the validation
+ * issues; `failed` a thrown lookup error plus a question offering retry/cancel. */
+type ControllerResult = {
+    status: "ask";
+    question: ControllerQuestion;
+    /** The prior answer's validation failure (`PromptConfig.validate`), when
+     * this is a re-ask. About the last transition, not the question itself. */
+    error?: string;
+} | {
+    status: "done";
+    value: Record<string, unknown>;
+} | {
+    status: "invalid";
+    issues: ControllerIssue[];
+} | {
+    status: "failed";
+    error: ControllerError;
+    question: ControllerQuestion;
+} | {
+    status: "cancelled";
+};
+/** A thrown lookup failure, normalized to plain data at the wall. The engine
+ * catches an arbitrary throwable; a raw `Error` loses its message under
+ * `JSON.stringify` (and a circular/custom value can break transport), so a
+ * `failed` result carries this DTO instead, which a remote host can render. */
+interface ControllerError {
+    name: string;
+    message: string;
+    code?: string;
+}
+/** A single validation problem, keyed to the offending parameter when known. */
+interface ControllerIssue {
+    parameter?: string;
+    message: string;
+}
+/**
+ * The serializable, caller-held progress of a resolution. The host carries it
+ * forward and passes it back into the next `step`; it round-trips across a
+ * client/server boundary unchanged (no closures, no live iterators). It carries
+ * the method id, so `step` needs nothing else.
+ */
+interface ControllerState {
+    method: string;
+    /** The growing input, as a nested tree of *real values only* — objects build
+     * in place (`resolved.inputs.channel`), so a leaf value lives at its {@link ControllerPath}. */
+    resolved: Record<string, unknown>;
+    /** Dotted path-keys the engine is done with: a resolved leaf (value in
+     * `resolved`), a skipped leaf (no value), or a finished array. Objects derive
+     * doneness from their children. The "touched" analog from form libraries. */
+    settled: string[];
+    /** The path of the parameter (or nested field) currently being asked. */
+    current?: ControllerPath;
+    /** Listing progress for the current dynamic leaf (serializable: items +
+     * cursor, never a live iterator). */
+    listing?: ControllerListing;
+    /** Whether the host will prompt. Interactive (the default) always asks;
+     * non-interactive runs `tryResolveWithoutPrompt` to auto-fill what it can
+     * (e.g. configured defaults) before asking for the rest. */
+    interactive: boolean;
+}
+/** A location in the input tree: top-level `["app"]`, a nested object field
+ * `["inputs", "channel"]`, or (later) an array item `["records", 0, "id"]`. */
+type ControllerPath = (string | number)[];
+/** Accumulated candidate items for the current dynamic parameter, plus the
+ * serializable cursor for "load more" and the active search term. */
+interface ControllerListing {
+    items: unknown[];
+    cursor?: string;
+    search?: string;
+    /** True when the source reported no further pages. */
+    exhausted: boolean;
+}
+/**
+ * The one pluggable seam for the in-process `resolve` sugar. It receives the
+ * same `{ state, result }` pair `start`/`step` return (so an answer callback
+ * sees exactly what a host driving the protocol directly would) and produces
+ * the next action. `result` is a question-bearing result — `ask` (the question
+ * plus any prior-answer `error`) or `failed` (a lookup threw; the question
+ * offers `retry`/`cancel`, `error` is the thrown value). `state` is read-only
+ * context (e.g. an agent can inspect `state.resolved`); mutating it is
+ * unsupported. Modality-agnostic — inquirer/DOM, an LLM agent, an auto-select
+ * policy, or a test script all satisfy it. The `start`/`step` protocol needs no
+ * answer callback.
+ */
+type ControllerAnswerFn = (turn: {
+    state: ControllerState;
+    result: Extract<ControllerResult, {
+        status: "ask" | "failed";
+    }>;
+}) => Promise<ControllerAction>;
+/** Per-parameter metadata for reflection (agents / MCP / docs / previews). The
+ * static, no-I/O view, complementing the in-the-moment `question`. */
+interface ControllerParameterDescription {
+    required: boolean;
+    /** True when values come from a fetch (`listItems`) rather than a static set. */
+    dynamic: boolean;
+    /** True when the resolver accepts a free-text search term. */
+    searchable?: boolean;
+    /** The field's serialized type (`z.toJSONSchema` of its input schema). Absent
+     * for a dynamically-shaped field (`getProperties`) with no static schema, or
+     * when the schema can't be represented as JSON Schema. zod never crosses the
+     * wall; this is its plain-data projection. */
+    schema?: Record<string, unknown>;
+    /** Statically known labeled values, when the parameter is a fixed enum. Richer
+     * than `schema.enum` (carries label/hint), so kept alongside `schema`. */
+    choices?: ControllerChoice[];
+    /** Sibling parameters this one depends on (`requireParameters`). A form host
+     * reads this to know which fields are independent (render together) and which
+     * to re-fetch when a dependency changes. */
+    requireParameters?: readonly string[];
+}
+/** A method's lightweight index entry: enough to render a menu or tool list
+ * without the full per-parameter detail. The list face of {@link Controller}. */
+interface ControllerMethodSummary {
+    name: string;
+    description?: string;
+    categories?: string[];
+}
+/** A method's full static contract, serialized: its parameters as a named bag
+ * (mirroring the canonical single-object input), the positional projection if
+ * the surface declares one, and the output type. All plain JSON — the
+ * serializable projection of the registry entry, never its live zod. */
+interface ControllerMethodDescription {
+    name: string;
+    description?: string;
+    categories?: string[];
+    /** Keyed by parameter name (the input bag's shape), not an ordered array:
+     * named-first, since MCP/web/agent hosts fill named slots. Order, when it
+     * matters, lives in `positional`. */
+    parameters: Record<string, ControllerParameterDescription>;
+    /** Ordered input keys the public surface takes as positional args, when the
+     * method declares a positional projection. Absent for a pure single-bag call. */
+    positional?: readonly string[];
+    /** The output type (`z.toJSONSchema` of the output schema), when known. */
+    output?: Record<string, unknown>;
+}
+/**
+ * Drives parameter resolution over a built SDK, reading its registry for the
+ * method's input schema and bound resolvers. Created from an SDK with
+ * `createController(sdk)`; transport-agnostic, so a remote implementation
+ * (browser → server) satisfies the same interface.
+ */
+interface Controller {
+    /** In-process sugar: loop `start`/`step` against an answer callback, return
+     * the resolved input (ready to pass to the SDK method). Throws on cancel. */
+    resolve(opts: {
+        method: string;
+        input?: Record<string, unknown>;
+        answer: ControllerAnswerFn;
+        /** Defaults to true. Pass false for an agent/headless answer callback that
+         * wants configured defaults auto-filled (`tryResolveWithoutPrompt`) rather
+         * than prompted. */
+        interactive?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /** Start resolving: seed from `input`, auto-resolve what needs no interaction,
+     * return the first result (an `ask`, or `done`). */
+    start(opts: {
+        method: string;
+        input?: Record<string, unknown>;
+        /** Defaults to true (always prompt). Pass false for headless/agent hosts to
+         * auto-fill via `tryResolveWithoutPrompt` before asking. */
+        interactive?: boolean;
+    }): Promise<{
+        state: ControllerState;
+        result: ControllerResult;
+    }>;
+    /** Advance with the user's action; return the next state and result. */
+    step(opts: {
+        state: ControllerState;
+        action: ControllerAction;
+    }): Promise<{
+        state: ControllerState;
+        result: ControllerResult;
+    }>;
+    /** Reflection (list): the lightweight index of every method (no I/O). The
+     * `nextCursor` slot mirrors `listChoices` and leaves room for paging a future
+     * dynamic/large method set; unpaged today. */
+    listMethods(): {
+        data: ControllerMethodSummary[];
+        nextCursor?: string;
+    };
+    /** Reflection (item): one method's full static contract, serialized (no I/O).
+     * Named `getMethod` to mirror the SDK's `getApp`/`listApps` resource pair;
+     * returns the method's *description*, not the callable. */
+    getMethod(opts: {
+        method: string;
+    }): {
+        data: ControllerMethodDescription;
+    };
+    /** Reflection: enumerate legal values for one dynamic parameter. */
+    listChoices(opts: {
+        method: string;
+        parameter: string;
+        input?: Record<string, unknown>;
+        search?: string;
+        cursor?: string;
+    }): Promise<{
+        data: ControllerChoice[];
+        nextCursor?: string;
+    }>;
+}
+
+/** The slice of a built SDK the driver needs: its registry accessor. */
+interface ControllerSdk {
+    getRegistry: (options?: {
+        package?: string;
+    }) => RegistryResult;
+}
+/**
+ * Build a {@link Controller} over a built SDK. Reads `sdk.getRegistry()`
+ * at call time (so post-build `addPlugin` additions are visible) to find each
+ * method's canonical input schema and bound resolvers, then drives the engine.
+ * The SDK surface itself is untouched; this is a sibling layer.
+ */
+declare function createController(sdk: ControllerSdk): Controller;
+
+/**
+ * Generic utility functions for creating SDK-method wrappers.
+ *
+ * Both `createFunction` and `createPaginatedFunction` accept the SDK
+ * as a parameter and read framework state (`hooks`, `core.adaptError`)
+ * live from `sdk.context.*` at method-invocation time. Plugins registered
+ * after a method is built still observe and configure it; ordering of
+ * plugin registration doesn't change runtime semantics. (Pagination's
+ * `adaptPage` is passed in per method, not read from context.)
+ */
+
+/**
+ * Minimal SDK shape the function wrappers accept. The wrappers only
+ * touch `context.hooks` and `context.core.*`, but we keep `context`
+ * typed as `unknown` so any kitcore-built SDK (whose context type
+ * widens unpredictably as plugins layer on) flows through without
+ * upstream type narrowing. Each read inside is asserted at the use
+ * site against the small slice we actually need.
+ */
+type FunctionSdk = {
+    context: unknown;
+};
+/**
+ * Wrap a core async function with input validation, error normalization,
+ * and method-call lifecycle hooks. Hooks and `adaptError` are read live
+ * from `sdk.context.*` at every invocation, so a plugin registered
+ * after this method is built still observes and configures it.
+ *
+ * @param coreFn - the underlying async function to wrap
+ * @param options.sdk - the SDK (or sub-SDK view) providing `context.hooks`
+ *                      and `context.core`
+ * @param options.schema - optional Zod schema for input validation
+ */
+declare function createFunction<TOptions, TResult, TSchemaOptions extends TOptions = TOptions>(coreFn: (options: TOptions) => Promise<TResult>, options: {
+    sdk: FunctionSdk;
+    schema?: z.ZodSchema<TSchemaOptions>;
+    name?: string;
+}): (callOptions?: TOptions) => Promise<TResult>;
+/**
+ * Higher-order function that creates a paginated function that wraps
+ * results in `SdkPage<TItem>`.
+ *
+ * @param coreFn - Function that returns T directly or throws errors
+ * @returns A function that normalizes errors and wraps results in `SdkPage`
+ */
+/**
+ * Extract the item type from a page handler's return shape. The handler
+ * may return a flat `{ data: TItem[] }` (or single `data: TItem`), a bare
+ * array, or anything else; in all cases the wrapper normalizes to
+ * `SdkPage<TItem>` and this resolves the right `TItem`.
+ */
+type ItemType<TResult> = TResult extends {
+    data: infer TData;
+} ? TData extends readonly (infer TItem)[] ? TItem : TData : TResult extends readonly (infer TItem)[] ? TItem : TResult;
+declare function createPaginatedFunction<TUserOptions, TResponse, TItem = ItemType<TResponse>>(coreFn: (options: TUserOptions & {
+    cursor?: string;
+    pageSize?: number;
+}) => Promise<TResponse>, options: {
+    sdk: FunctionSdk;
+    schema?: z.ZodSchema<TUserOptions>;
+    name?: string;
+    defaultPageSize?: number;
+    /**
+     * Translate the handler's raw `TResponse` into `SdkPage<TItem>`. `TItem`
+     * is wrapped in `NoInfer`: it is sourced from `TResponse` (via the
+     * `ItemType` default), not from this adapter, which is item-agnostic (it
+     * relocates the cursor; items are finalized in the handler's `data`).
+     * Without `NoInfer`, a generic adapter (e.g. `<T>(r) => SdkPage<T>`)
+     * would collapse `TItem` to `unknown`.
+     */
+    adaptPage?: (response: TResponse) => SdkPage<NoInfer<TItem>>;
+}): (options?: TUserOptions & {
+    cursor?: string;
+    pageSize?: number;
+    maxItems?: number;
+}) => PaginatedSdkResult<TItem>;
+
+/**
+ * Core error machinery.
+ *
+ * kitcore constructs errors at two internal throw sites: input
+ * validation (`utils/validation.ts`) and non-Error normalization
+ * (`utils/function-utils.ts`'s `normalizeError`). Heads supply a
+ * `adaptError` factory via `createCorePlugin` to map kitcore's abstract
+ * `CoreErrorCode` values onto their own branded error classes; if
+ * no factory is supplied, kitcore falls back to constructing a plain
+ * `CoreError`. Either way, every kitcore-thrown error is brand-stamped
+ * with `CORE_ERROR_SYMBOL` and `coreCode` (non-enumerable),
+ * so consumers can recognize core errors via `isCoreError`
+ * without knowing the head's class identity.
+ */
+/**
+ * Cross-package brand for kitcore-constructed errors. `Symbol.for(key)`
+ * reads from the engine-global registry, so the same value resolves
+ * across realms and across multiple copies of kitcore (e.g. when one
+ * package bundles kitcore and another installs it standalone). Use
+ * `isCoreError` for cross-package checks.
+ */
+declare const CORE_ERROR_SYMBOL: unique symbol;
+/**
+ * Abstract codes for the errors kitcore can produce. Heads receive these
+ * via `AdaptErrorOptions.code` and map them onto their own named
+ * error classes (e.g. `VALIDATION_ERROR` → the head's branded
+ * `<Prefix>ValidationError`).
+ */
+declare const CoreErrorCode: {
+    readonly Validation: "VALIDATION_ERROR";
+    readonly Unknown: "UNKNOWN_ERROR";
+};
+type CoreErrorCode = (typeof CoreErrorCode)[keyof typeof CoreErrorCode];
+/**
+ * Standard error envelope. kitcore doesn't generate these
+ * itself; heads set `errors?: CoreApiError[]` on their error constructor
+ * options when surfacing structured upstream failures.
+ */
+interface CoreApiError {
+    status: number;
+    code: string;
+    title: string;
+    detail: string;
+    source?: unknown;
+    meta?: unknown;
+}
+/**
+ * Base options for the default `CoreError` fallback. Heads' own error
+ * classes typically accept a richer options bag.
+ */
+interface CoreErrorOptions {
+    statusCode?: number;
+    errors?: CoreApiError[];
+    cause?: unknown;
+    response?: unknown;
+}
+/**
+ * What `adaptError` factories receive. `code` is the abstract error
+ * code; `details` carries type-specific extras (validation issues for
+ * `VALIDATION_ERROR`, etc.).
+ */
+interface AdaptErrorOptions {
+    code: CoreErrorCode;
+    message: string;
+    cause?: unknown;
+    details?: unknown;
+}
+type AdaptError = (options: AdaptErrorOptions) => Error;
+/**
+ * Default error class kitcore constructs when no `adaptError` is
+ * supplied. Heads typically provide their own branded classes via
+ * `adaptError` and never see this. Exported so the rare head-less
+ * caller (tests, scratch scripts) can recognize the fallback.
+ */
+declare class CoreError extends Error {
+    readonly name: string;
+    statusCode?: number;
+    errors?: CoreApiError[];
+    cause?: unknown;
+    response?: unknown;
+    constructor(message: string, options?: CoreErrorOptions);
+}
+/**
+ * Construct a core error, optionally via a head-supplied factory.
+ * Stamps the core brand and the abstract `coreCode` on the
+ * returned instance (non-enumerable, so they don't pollute JSON
+ * serialization). The `instanceof <HeadErrorClass>` check on the
+ * result works as expected; `isCoreError` is the cross-package
+ * recognizer that survives bundled/standalone splits.
+ */
+declare function createCoreError(options: AdaptErrorOptions, adaptError?: AdaptError): Error;
+/**
+ * Cross-package-safe check that `value` was produced by kitcore's
+ * error construction path (i.e. through `createCoreError`). Use
+ * this in code that needs to distinguish "kitcore threw this" from
+ * "a handler threw an unrelated `Error` subclass" — `instanceof` checks
+ * on specific head classes also work, but `isCoreError` is the
+ * neutral recognizer.
+ */
+declare function isCoreError(value: unknown): boolean;
+/**
+ * Abstract `CoreErrorCode` for an error produced via
+ * `createCoreError`. Returns `undefined` for non-kitcore values.
+ */
+declare function getCoreErrorCode(value: unknown): CoreErrorCode | undefined;
+/**
+ * `cause` field accessor that doesn't trip the type system. Same as
+ * `(value as { cause?: unknown }).cause` for kitcore-produced errors;
+ * returns `undefined` for non-kitcore values.
+ */
+declare function getCoreErrorCause(value: unknown): unknown;
+
+/**
+ * ------------------------------
+ * Core configuration plugin
+ * ------------------------------
+ *
+ * `createCorePlugin` is how a head supplies kitcore-level behavior knobs
+ * (`adaptError` for branded errors, future entries similarly). The plugin
+ * writes to `context.core`; kitcore reads from that path at every method
+ * invocation. Consumers configure through this factory's typed `CoreOptions`,
+ * never by touching the context path.
+ *
+ *   createPluginStack()
+ *     .use(createCorePlugin({ adaptError: myAdaptError }))
+ *     .use(listAppsPlugin);
+ *
+ * Installing this plugin is optional. Kitcore reads `context.core.*`
+ * with optional chaining, so an SDK without `createCorePlugin`
+ * installed just falls back to kitcore's built-in behavior.
+ *
+ * Note: pagination shaping is NOT configured here. Each paginated method
+ * declares its own `adaptPage` on `createPaginatedPluginMethod`, so the
+ * adapter travels with the plugin (and stays type-checked) rather than
+ * relying on an ambient SDK-wide default.
+ */
+
+/**
+ * Head-supplied configuration for kitcore-managed behavior. All fields are
+ * optional; absent fields fall back to kitcore's built-in behavior.
+ */
+interface CoreOptions {
+    /**
+     * Construct the head's branded error class for kitcore-thrown errors
+     * (validation failures, non-Error normalization). Receives the
+     * abstract `CoreErrorCode`, message, optional cause, and
+     * type-specific details; returns the head's `Error` subclass. The
+     * returned instance is automatically brand-stamped via
+     * `createCoreError` so `isCoreError(err)` still recognizes
+     * it across package boundaries. If absent, kitcore throws a plain
+     * `CoreError`.
+     */
+    adaptError?: AdaptError;
+}
+/**
+ * Register kitcore-level configuration. Writes the options to
+ * `context.core` internally; consumers never reference the path.
+ *
+ * Reads of `context.core.adaptError` are
+ * live: kitcore's method wrappers consult them at every invocation,
+ * not at registration time. A `createCorePlugin` registered after a
+ * method plugin still applies to that method's subsequent calls.
+ */
+declare function createCorePlugin(options: CoreOptions): Plugin<object, {
+    context: {
+        core: CoreOptions;
+    };
+}>;
+
+/**
+ * Per-invocation scope for SDK method calls. Each top-level SDK method call
+ * runs in its own AsyncLocalStorage scope (via `runInMethodScope`), isolating
+ * its depth counter and any plugin-specific state from concurrent calls.
+ *
+ * The toolkit reserves the `depth` field; anything else on the scope is
+ * opaque key/value storage that plugins can use (e.g. eventEmission stores
+ * its `MethodMetadata` under its own key).
+ */
+/**
+ * The per-call scope object held in ALS. Toolkit owns `depth`; everything
+ * else is open for plugin-specific use.
+ */
+interface MethodScope {
+    depth: number;
+    [key: string]: unknown;
+}
+/**
+ * Read the current scope object, or `undefined` if no scope is active or
+ * AsyncLocalStorage isn't available. Plugins use this to read/write their
+ * own scoped state under their own key.
+ */
+declare function getCurrentScope(): MethodScope | undefined;
+/**
+ * Current depth of the SDK method-call stack. 0 = outermost call,
+ * 1+ = invoked from inside another SDK method. Returns 0 when no scope
+ * is active (e.g. raw callers outside the framework).
+ */
+declare function getCurrentDepth(): number;
+/**
+ * True when the current call is nested inside another SDK method.
+ * Preserves the legacy "no store = nested" fallback used by browser
+ * builds to suppress hook firing when async_hooks isn't available.
+ */
+declare function isNestedMethodCall(): boolean;
+/**
+ * Run `fn` inside a new method scope. Nested invocations see an incremented
+ * `depth`. When no scope store is available (e.g. browsers without
+ * async_hooks), `fn` is called directly with no scope tracking.
+ */
+declare function runInMethodScope<T>(fn: () => T): T;
+declare const runWithTelemetryContext: typeof runInMethodScope;
+declare const isTelemetryNested: typeof isNestedMethodCall;
+
+/**
+ * A typed wrapper around a single `AsyncLocalStorage` instance. Centralizes the
+ * `node:async_hooks` plumbing (bundler-safe static import, browser fallback) so
+ * consumers don't each hand-roll it and drift apart.
+ *
+ * The wrapper holds no merge or depth policy: `run` simply activates `store`
+ * for the duration of `fn`, and `get` returns whatever is active. Consumers
+ * layer their own semantics (e.g. depth counting, parent merging) on top.
+ */
+interface AsyncContext<T> {
+    /** Run `fn` with `store` active. Returns whatever `fn` returns; `fn`'s errors propagate. */
+    run<R>(store: T, fn: () => R): R;
+    /** The active store, or `undefined` if no scope is active or ALS is unavailable. */
+    get(): T | undefined;
+    /**
+     * `false` only where `node:async_hooks` could not be loaded (e.g. browsers),
+     * leaving the context inert. Lets callers distinguish "ALS unavailable" from
+     * the also-`undefined` "ALS available but no active scope".
+     */
+    readonly available: boolean;
+}
+/** Create an isolated {@link AsyncContext} backed by one `AsyncLocalStorage`. */
+declare function createAsyncContext<T>(): AsyncContext<T>;
+
+/**
+ * Deferred form: bind a schema (and `adaptError`) once, get a reusable
+ * validator. Its input is `unknown` so it can validate values wider than the
+ * schema's own type (e.g. paginated options that carry cursor / pageSize
+ * alongside the schema-typed fields).
+ */
+declare function createValidator<TSchema extends z.ZodSchema>(schema: TSchema, { adaptError }?: {
+    adaptError?: AdaptError;
+}): (input: unknown) => z.infer<TSchema>;
+/**
+ * Eager form: validate `options` now and return the parsed value. The
+ * `TSchemaOptions extends TOptions` generics let the call site check that the
+ * value being validated matches the schema's type, which `createValidator`
+ * (input `unknown`) can't.
+ */
+declare const validateOptions: <TOptions, TSchemaOptions extends TOptions>(schema: z.ZodSchema<TSchemaOptions>, options: TOptions, { adaptError }?: {
+    adaptError?: AdaptError;
+}) => TSchemaOptions;
+
+/**
+ * Translates a paginated handler's raw response into a normalized
+ * `SdkPage<TItem>`. Supplied per method as the `adaptPage` on
+ * `createPaginatedPluginMethod` (and forwarded to `createPaginatedFunction`).
+ */
+type AdaptPage<TResponse = unknown, TItem = unknown> = (response: TResponse) => SdkPage<TItem>;
+type TPageOptions<TOptions> = TOptions extends undefined ? {
+    cursor?: string;
+    maxItems?: number;
+    pageSize?: number;
+} : TOptions & {
+    cursor?: string;
+    maxItems?: number;
+    pageSize?: number;
+};
+declare function decodeIncomingCursor(incoming?: string): {
+    offset: number;
+    cursor: string | undefined;
+};
+declare function createPrefixedCursor(prefix: string, cursor: string | undefined): string;
+declare function splitPrefixedCursor(cursor: string | undefined, prefixes?: string[]): [string | undefined, string | undefined];
+/**
+ * Utility for paginating through API endpoints that return cursor-based pages.
+ * Accepts and yields SDK-encoded cursor envelopes. Any incoming cursor is decoded
+ * before being passed to the page function; all outgoing cursors are encoded.
+ *
+ * @param pageFunction - Function that fetches a single page with {data, nextCursor} structure
+ * @param pageOptions - Options to pass to the page function (cursor will be managed automatically)
+ * @returns Async iterator that yields pages with encoded cursors
+ */
+declare function paginateMaxItems<TOptions, TPage extends {
+    data: any[];
+    nextCursor?: string;
+}>(pageFunction: (options: TOptions & {
+    cursor?: string;
+    maxItems?: number;
+    pageSize?: number;
+}) => Promise<TPage>, pageOptions?: TPageOptions<TOptions>): AsyncIterableIterator<TPage>;
+declare function paginateBuffered<TOptions, TPage extends {
+    data: any[];
+    nextCursor?: string;
+}>(pageFunction: (options: TOptions & {
+    cursor?: string;
+    maxItems?: number;
+    pageSize?: number;
+}) => Promise<TPage>, pageOptions?: TPageOptions<TOptions>): AsyncIterableIterator<TPage>;
+declare const paginate: typeof paginateBuffered;
+interface PaginatedResult<TItem> {
+    data: TItem[];
+    nextCursor?: string;
+}
+type PaginatedSource<TItem> = () => PromiseLike<PaginatedResult<TItem>> & AsyncIterable<PaginatedResult<TItem>>;
+/**
+ * Concatenate multiple paginated SDK results into a single paginated stream.
+ * Each source is a function returning a dual Promise+AsyncIterable (as SDK
+ * paginated methods return). Sources are drained in order.
+ *
+ * The optional `dedupe` key extractor filters items from source N against
+ * all items seen in sources 0 through N-1.
+ *
+ * Uses paginateBuffered internally to normalize page sizes across source
+ * boundaries — e.g. if the first source only has 2 items, they'll be
+ * buffered with items from the next source into a full page.
+ *
+ * Returns the same dual Promise+AsyncIterable shape that resolvers expect.
+ */
+declare function concatPaginated<TItem>({ sources, dedupe, pageSize, }: {
+    sources: PaginatedSource<TItem>[];
+    dedupe?: (item: TItem) => string;
+    pageSize?: number;
+}): PromiseLike<PaginatedResult<TItem>> & AsyncIterable<PaginatedResult<TItem>>;
+/**
+ * Strip the PromiseLike from an async iterable, returning a plain
+ * AsyncIterable. This prevents async functions from unwrapping the
+ * iterable (since async only unwraps PromiseLike, not AsyncIterable).
+ */
+declare function toIterable<T>(source: AsyncIterable<T>): AsyncIterable<T>;
+
+/**
+ * Generic string utilities used by the plugin framework.
+ */
+/**
+ * Converts a string to title case, handling various input formats:
+ * - camelCase: "firstName" → "First Name"
+ * - snake_case: "first_name" → "First Name"
+ * - kebab-case: "first-name" → "First Name"
+ * - mixed formats: "first_name-value" → "First Name Value"
+ */
+declare function toTitleCase(input: string): string;
+/**
+ * Converts a string to snake_case, handling various input formats:
+ * - camelCase: "firstName" → "first_name"
+ * - kebab-case: "first-name" → "first_name"
+ * - title case: "First Name" → "first_name"
+ * - mixed formats: "first-Name Value" → "first_name_value"
+ * - starts with number: "123abc" → "_123abc"
+ */
+declare function toSnakeCase(input: string): string;
+
+interface DeprecationLogger {
+    logDeprecation(message: string): void;
+    resetDeprecationWarnings(): void;
+}
+/**
+ * Create a package-tagged deprecation logger. Each logger tracks its own
+ * once-per-process message Set, so package heads can keep independent warning
+ * channels while sharing the implementation.
+ */
+declare function createDeprecationLogger(tag: string): DeprecationLogger;
+
+/**
+ * Core signal machinery.
+ *
+ * Signals are intentional control-flow throws — not failures. They're the
+ * sibling of {@link CoreError}: where an error means "something went wrong," a
+ * signal means "stop and do this on purpose." The first (and currently only)
+ * one is {@link CoreCancelledSignal}, thrown by `Controller.resolve` when the
+ * host cancels resolution (its answer callback returned `{ type: "cancel" }`).
+ *
+ * Like errors, every signal is brand-stamped with {@link CORE_SIGNAL_SYMBOL} so
+ * a consumer can recognize one via {@link isCoreSignal} without sharing class
+ * identity — important across the bundled-vs-standalone kitcore boundary.
+ */
+/**
+ * Cross-package brand for kitcore signals. `Symbol.for(key)` reads the
+ * engine-global registry, so the same value resolves across realms and across
+ * multiple copies of kitcore. Use {@link isCoreSignal} for cross-package checks.
+ */
+declare const CORE_SIGNAL_SYMBOL: unique symbol;
+/**
+ * Base class for kitcore signals. A signal is intentional control flow, not an
+ * error, so it does NOT extend any error hierarchy that failure-handling code
+ * sweeps up via `instanceof CoreError`. Subclasses declare a stable `name` and
+ * `code`. (Mirrors the head convention, e.g. zapier-sdk's `ZapierSignal`.)
+ */
+declare abstract class CoreSignal extends Error {
+    abstract readonly name: string;
+    abstract readonly code: string;
+    constructor(message?: string);
+}
+/**
+ * Cross-package-safe check that `value` is a kitcore signal (an intentional
+ * control-flow throw), as opposed to a real error. Survives the
+ * bundled/standalone kitcore split, where `instanceof CoreSignal` may not.
+ */
+declare function isCoreSignal(value: unknown): boolean;
+/**
+ * Thrown by `Controller.resolve` when the host cancels resolution (the answer
+ * callback returned `{ type: "cancel" }`). The lower-level `start`/`step`
+ * protocol instead returns a `{ status: "cancelled" }` result, so a host
+ * driving it directly never sees this throw; `resolve` raises it because its
+ * contract is "the resolved input, or nothing."
+ */
+declare class CoreCancelledSignal extends CoreSignal {
+    readonly name = "CoreCancelledSignal";
+    readonly code: "CANCELLED";
+    constructor(message?: string);
+}
+
+export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type BoundFormatter, type BoundResolver, CONTEXT, CORE_ERROR_SYMBOL, CORE_SIGNAL_SYMBOL, type CategoryDefinition, type ConstantResolver$1 as ConstantResolver, type Controller, type ControllerAction, type ControllerAffordance, type ControllerAnswerFn, type ControllerChoice, type ControllerError, type ControllerIssue, type ControllerListing, type ControllerMethodDescription, type ControllerMethodSummary, type ControllerParameterDescription, type ControllerPath, type ControllerQuestion, type ControllerResult, type ControllerSdk, type ControllerState, type CoreApiError, CoreCancelledSignal, CoreError, CoreErrorCode, type CoreErrorOptions, type CoreOptions, CoreSignal, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DynamicListResolver, type DynamicResolver$1 as DynamicResolver, type DynamicSearchResolver, type FieldsResolver, type FormattedItem, type Formatter, type FunctionDeprecation, type FunctionRegistryEntry, type LeafMeta, type LegacyMergePlugin, type LegacyPlugin, type ListItemsResult, type ListPromptConfig, type MethodAttachment, type MethodHooks, type MethodPlugin, type MethodScope, type OnMethodEnd, type OnMethodEndContext, type OnMethodStart, type OnMethodStartContext, type OutputFormatter, type PaginatedSdkFunction, type PaginatedSdkResult, type Plugin, type PluginMeta, type PluginProvides, type PluginStack, type PluginSummary, type PositionalMetadata, type PromptConfig, type PromptConfigChoice, type PropertyPlugin, type RegistryResult, type RequiredSdkOf, type Resolver$1 as Resolver, type ResolverConfig, type ResolverFieldItem, type ResolverMetadata, type ResolverPromptConfig, type ResolverType, type Sdk, type SdkContext, type SdkPage, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, composePlugins, concatPaginated, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createValidator, dangerousContextPlugin, declareMethod, declarePlugin, declareProperty, decodeIncomingCursor, defineFormatter, defineLegacyMerge, defineMethod, definePlugin, defineProperty, defineResolver, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getOutputSchema, getRegistryPlugin, getSchemaDescription, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, openEnum, paginate, paginateBuffered, paginateMaxItems, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };