@zapier/kitcore 0.11.0 → 0.13.0

package/dist/index.d.mts

@@ -8,9 +8,33 @@ declare module "zod" {
     }
 }
 
+/**
+ * The response `meta` sidecar, shared by both output modes: an item method's
+ * `{ data, meta }` envelope and a list method's page carry the same shape, so a
+ * caller reads a framework report the same way regardless of the mode it came
+ * from.
+ *
+ * Every member is optional and framework-owned. A method's `run` returns `data`;
+ * the boundary attaches what belongs here.
+ */
+interface ResponseMeta {
+    /**
+     * What output validation's strip removed from the response, present only when
+     * the head enables the `includeOutputValidationDroppedPaths` core option AND
+     * something was actually dropped. Paths are relative to `data` in both modes
+     * (`a.b` for an item), with array elements collapsed to one `[]` segment and
+     * unioned (`[].b` on a page, `items[].b` for an array inside an item), matching
+     * connectors' format.
+     */
+    outputValidation?: {
+        droppedPaths: 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.
@@ -18,6 +42,10 @@ declare module "zod" {
 interface SdkPage<T = unknown> {
     data: T[];
     nextCursor?: string;
+    /** Additive per-page framework sidecar, the same shape an item method's
+     * envelope carries. Framework-set, not something a handler or `adaptPage`
+     * returns. See {@link ResponseMeta}. */
+    meta?: ResponseMeta;
 }
 /**
  * Return type of every paginated SDK method. The documented surface is:
@@ -480,6 +508,28 @@ declare function withPositional<T extends z.ZodType>(schema: T): T & {
     _def: T["_def"] & PositionalMetadata;
 };
 declare function isPositional(schema: z.ZodType): boolean;
+/**
+ * Marks an optional boolean schema for which omission is distinct from false:
+ * omitting the value means "use the server default" or "preserve the current
+ * value", so an explicit false needs its own affordance. A string supplies
+ * the domain antonym — "disabled" for `enabled` — which each surface renders
+ * in its own vocabulary (a CLI as a flag spelling, a tool description as
+ * prose). `true` requests generic negation when the domain has no antonym.
+ *
+ * Declare it via `.meta({ negatable: "disabled" } satisfies NegatableMetadata)`.
+ * The `satisfies` matters: zod's metadata type permits arbitrary keys, so it
+ * is the only compile-time check against a misspelled key.
+ */
+interface NegatableMetadata {
+    negatable: true | string;
+}
+/**
+ * Read a schema's `negatable` metadata: `true`, the domain antonym, or
+ * undefined when the schema doesn't declare one. Unwraps optional/default
+ * wrappers like `isPositional`, so the `.meta()` call may sit on any layer
+ * of the chain.
+ */
+declare function getNegatable(schema: z.ZodType): NegatableMetadata["negatable"] | undefined;
 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]>;
 
 /**
@@ -504,6 +554,13 @@ interface LeafMetaFields {
     itemType?: string;
     returnType?: string;
     outputSchema?: z.ZodSchema;
+    /** Behavioral opt-out that rides on this config for every `defineMethod`
+     * overload (all merge `LeafMetaFields`), the partner of `outputSchema`: when
+     * true, the materializer skips validating/stripping the output. It is
+     * consumed at build time and stored as a first-class plugin field, NOT folded
+     * into the projected meta (hence absent from `LEAF_META_KEYS`), so it stays
+     * off the registry / CLI / MCP surface, exactly like `skipInputValidation`. */
+    skipOutputValidation?: boolean;
     packages?: string[];
     experimental?: boolean;
     confirm?: "create-secret" | "delete";
@@ -1008,9 +1065,15 @@ interface MethodPlugin<TName extends string = string, TInput = unknown, TOutput
     /** True for a `declareMethod` stand-in: a typed reference with no real
      * implementation. A real plugin under the same id satisfies it. */
     standIn?: boolean;
-    /** True for a `declareOptionalProperty` stand-in over a method id: dependents bind
-     * `undefined` if no real plugin satisfies it. */
+    /** True for a `declareOptionalMethod` stand-in: dependents bind `undefined` if
+     * no real plugin satisfies it, and `PluginSurface` types the binding
+     * `| undefined`. */
     optional?: boolean;
+    /** Present on a `declareDefault` wrapper: this entry is the DEFAULT provider
+     * for its id (preempted by any explicit provider). Its value is the wrapped
+     * plugin, so two defaults for one id dedup (same source) or conflict
+     * (different source). */
+    defaultSource?: AnyLeafPlugin;
     imports: readonly AnyPlugin[];
     /** Binding-name to plugin-id edges, normalized from `imports`;
      * what the `imports` bag is built from. */
@@ -1032,6 +1095,10 @@ interface MethodPlugin<TName extends string = string, TInput = unknown, TOutput
      * For raw methods that own their own validation and must not have their input
      * transformed, e.g. `fetch` passing a `RequestInit` bag through unchanged. */
     skipInputValidation?: boolean;
+    /** When true, the materializer skips validating/stripping `run`'s output
+     * against `meta.outputSchema` (the schema stays for projection). The output
+     * partner of {@link MethodPlugin.skipInputValidation}. */
+    skipOutputValidation?: boolean;
     /** Descriptive metadata for the registry / CLI / MCP / docs (carry-only at
      * runtime). */
     meta?: LeafMeta;
@@ -1146,6 +1213,11 @@ interface PropertyPlugin<TName extends string = string, TValue = unknown> {
      * property satisfies it, dependents bind `undefined` rather than the build
      * failing on a missing dependency. */
     optional?: boolean;
+    /** Present on a `declareDefault` wrapper: this entry is the DEFAULT provider
+     * for its id (preempted by any explicit provider). Its value is the wrapped
+     * plugin, so two defaults for one id dedup (same source) or conflict
+     * (different source). */
+    defaultSource?: AnyLeafPlugin;
     imports: readonly AnyPlugin[];
     /** Binding-name to plugin-id edges, normalized from `imports`;
      * what the `imports` bag is built from. */
@@ -1483,7 +1555,11 @@ type ExportSurface<TChild extends AnyLeafPlugin> = TChild extends MethodPlugin<a
  * bag and `ProvidesOf` is the completeness ledger's phantom ids — both
  * different concepts.
  */
-type PluginSurface<P extends AnyPlugin> = P extends MethodPlugin<infer TName, infer TInput, infer TOutput, infer TPositional> ? {
+type PluginSurface<P extends AnyPlugin> = P extends MethodPlugin<infer TName, infer TInput, infer TOutput, infer TPositional> ? P extends {
+    optional: true;
+} ? {
+    [K in TName]: SurfaceCall<TInput, TOutput, TPositional> | undefined;
+} : {
     [K in TName]: SurfaceCall<TInput, TOutput, TPositional>;
 } : P extends PropertyPlugin<infer TName, infer TValue> ? {
     [K in TName]: TValue;
@@ -2229,6 +2305,7 @@ declare function defineMethod<const TName extends string, TInput, TResponse exte
     run: (bag: MethodRunBag<ImportsOf<TImports>, TInput, TState>) => TResponse | Promise<TResponse>;
 } & LeafMetaFields): MethodPlugin<TName, TInput, Promise<{
     data: TData;
+    meta?: ResponseMeta;
 }>> & 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;
@@ -2450,6 +2527,19 @@ declare function defineFormatter<const TImports extends ImportsInput = readonly
 declare function declareMethod<const TId extends string, TInput = unknown, TOutput = unknown>(config: {
     id: LiteralString<TId>;
 }): MethodPlugin<LastSegment<TId>, TInput, TOutput> & PluginSummary<TId, never>;
+/**
+ * Declare an OPTIONAL stand-in for a method registered elsewhere: the method twin
+ * of `declareOptionalProperty`. Unlike `declareMethod`, an unsatisfied optional
+ * reference is NOT a missing dependency; the binding is typed
+ * `((input) => output) | undefined`, so the consumer must handle the absent case
+ * (`imports.track?.(...)`). Use it to reference a foreign method userland may or
+ * may not import, without claiming its slot.
+ */
+declare function declareOptionalMethod<const TId extends string, TInput = unknown, TOutput = unknown>(config: {
+    id: LiteralString<TId>;
+}): MethodPlugin<LastSegment<TId>, TInput, TOutput> & {
+    optional: true;
+} & PluginSummary<never, never>;
 /**
  * Define a property leaf. Either a static `value` or a computed `get` (eager,
  * dependencies first, like `setup`). `createSdk`, a dependent's `imports`, or
@@ -2507,6 +2597,21 @@ declare function declareProperty<const TId extends string, TValue = unknown>(con
 declare function declareOptionalProperty<const TId extends string, TValue = unknown>(config: {
     id: LiteralString<TId>;
 }): PropertyPlugin<LastSegment<TId>, TValue | undefined> & PluginSummary<never, never>;
+/**
+ * Declare a DEFAULT provider for a dependency you own: import the capability the
+ * given plugin provides, and fall back to that plugin when nothing else provides
+ * its id. Kind-agnostic (the plugin supplies id, type, and kind), so no
+ * method/property split.
+ *
+ * A default materializes a real, single node, so it works out of the box and can
+ * be wrapped or replaced: an explicit provider of the same id silently preempts
+ * it, and two different defaults for one id error only when nothing else provides
+ * it. See the Defaults section in the kitcore README for default vs optional
+ * reference.
+ */
+declare function declareDefault<P extends AnyLeafPlugin>({ plugin, }: {
+    plugin: P;
+}): P;
 /**
  * Define a method-lifecycle hook: a leaf whose `observe` contributes
  * fire-and-forget observers (`onMethodStart` / `onMethodEnd`) the method
@@ -2859,6 +2964,15 @@ interface CoreOptions {
      * reserved for an `on*`-named observer when the unified event bus lands.
      */
     logDeprecation?: (warning: DeprecationWarning) => void;
+    /**
+     * Report what output validation stripped, on the response's
+     * `meta.outputValidation.droppedPaths` (the name mirrors that path). Off by
+     * default: the report is a debugging aid for reconciling a schema against the
+     * wire, and a sidecar every caller has to ignore is worse than one a head
+     * turns on while it audits its schemas. Off also skips the recursive
+     * raw-vs-parsed diff, so the strip costs a parse and nothing more.
+     */
+    includeOutputValidationDroppedPaths?: boolean;
 }
 
 /**
@@ -3449,6 +3563,8 @@ declare function createPaginatedFunction<TUserOptions, TResponse, TItem = ItemTy
     adaptPage?: (response: TResponse) => SdkPage<NoInfer<TItem>>;
     /** Pre-run per-method annotator (see applyAnnotations). */
     annotator?: (input: unknown) => Annotations;
+    /** Applied to each canonical page after the shape guard (output validation). */
+    finalizePage?: (page: SdkPage<TItem>) => SdkPage<TItem>;
     /** Live read of the method's deprecation meta (see signalDeprecation). */
     getDeprecation?: () => FunctionDeprecation | undefined;
 }): (options?: TUserOptions & {
@@ -3749,4 +3865,4 @@ declare class CoreCancelledSignal extends CoreSignal {
  */
 declare function isCoreCancelledSignal(value: unknown): value is CoreCancelledSignal;
 
-export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type Annotations, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type BoundFormatter, type BoundResolver, CONTEXT, CORE_ERROR_SYMBOL, CORE_OPTIONS_ID, CORE_SIGNAL_SYMBOL, type CallContext, type CallOrigin, type CategoryDefinition, type ComposedAnnotator, type ConstantResolver$1 as ConstantResolver, type Controller, type ControllerAction, type ControllerAffordance, type ControllerAnswerFn, type ControllerChoice, type ControllerError, type ControllerIssue, type ControllerListingPage, type ControllerListingPosition, type ControllerMethodDescription, type ControllerMethodSummary, type ControllerPagination, type ControllerParameterDescription, type ControllerPath, type ControllerQuestion, type ControllerResult, type ControllerSdk, type ControllerSelectPage, type ControllerState, type CoreApiError, CoreCancelledSignal, CoreDisposeError, CoreError, CoreErrorCode, type CoreErrorOptions, type CoreOptions, CoreSignal, type CreateSdkOptions, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DisposeFn, type DynamicListResolver, type DynamicMember, type DynamicResolver$1 as DynamicResolver, type DynamicSearchResolver, type FieldsResolver, type FormattedItem, type Formatter, type FunctionDeprecation, type FunctionRegistryEntry, type HookAnnotator, type HookPlugin, type LeafMeta, type LeafSummary, type LegacyMergePlugin, type LegacyPlugin, type ListItemsResult, type ListPromptConfig, type MethodAnnotator, type MethodAttachment, type MethodHooks, type MethodOverridePlugin, type MethodPlugin, type MethodScope, type Resolver as ModelResolver, 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 PluginSurface, 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, canonicalInputSchema, composePlugins, concatLists, concatPaginated, coreOptionsPluginRef, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createValidator, dangerousContextPlugin, declareMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, disposeSdk, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getOutputSchema, getRegistryPlugin, getSchemaDescription, isCoreCancelledSignal, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, resolvePlugin, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };
+export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type Annotations, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type BoundFormatter, type BoundResolver, CONTEXT, CORE_ERROR_SYMBOL, CORE_OPTIONS_ID, CORE_SIGNAL_SYMBOL, type CallContext, type CallOrigin, type CategoryDefinition, type ComposedAnnotator, type ConstantResolver$1 as ConstantResolver, type Controller, type ControllerAction, type ControllerAffordance, type ControllerAnswerFn, type ControllerChoice, type ControllerError, type ControllerIssue, type ControllerListingPage, type ControllerListingPosition, type ControllerMethodDescription, type ControllerMethodSummary, type ControllerPagination, type ControllerParameterDescription, type ControllerPath, type ControllerQuestion, type ControllerResult, type ControllerSdk, type ControllerSelectPage, type ControllerState, type CoreApiError, CoreCancelledSignal, CoreDisposeError, CoreError, CoreErrorCode, type CoreErrorOptions, type CoreOptions, CoreSignal, type CreateSdkOptions, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DisposeFn, type DynamicListResolver, type DynamicMember, type DynamicResolver$1 as DynamicResolver, type DynamicSearchResolver, type FieldsResolver, type FormattedItem, type Formatter, type FunctionDeprecation, type FunctionRegistryEntry, type HookAnnotator, type HookPlugin, type LeafMeta, type LeafSummary, type LegacyMergePlugin, type LegacyPlugin, type ListItemsResult, type ListPromptConfig, type MethodAnnotator, type MethodAttachment, type MethodHooks, type MethodOverridePlugin, type MethodPlugin, type MethodScope, type Resolver as ModelResolver, type NegatableMetadata, 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 PluginSurface, 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 ResponseMeta, type Sdk, type SdkContext, type SdkPage, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, canonicalInputSchema, composePlugins, concatLists, concatPaginated, coreOptionsPluginRef, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createValidator, dangerousContextPlugin, declareDefault, declareMethod, declareOptionalMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, disposeSdk, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getNegatable, getOutputSchema, getRegistryPlugin, getSchemaDescription, isCoreCancelledSignal, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, resolvePlugin, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };

package/dist/index.d.ts

@@ -8,9 +8,33 @@ declare module "zod" {
     }
 }
 
+/**
+ * The response `meta` sidecar, shared by both output modes: an item method's
+ * `{ data, meta }` envelope and a list method's page carry the same shape, so a
+ * caller reads a framework report the same way regardless of the mode it came
+ * from.
+ *
+ * Every member is optional and framework-owned. A method's `run` returns `data`;
+ * the boundary attaches what belongs here.
+ */
+interface ResponseMeta {
+    /**
+     * What output validation's strip removed from the response, present only when
+     * the head enables the `includeOutputValidationDroppedPaths` core option AND
+     * something was actually dropped. Paths are relative to `data` in both modes
+     * (`a.b` for an item), with array elements collapsed to one `[]` segment and
+     * unioned (`[].b` on a page, `items[].b` for an array inside an item), matching
+     * connectors' format.
+     */
+    outputValidation?: {
+        droppedPaths: 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.
@@ -18,6 +42,10 @@ declare module "zod" {
 interface SdkPage<T = unknown> {
     data: T[];
     nextCursor?: string;
+    /** Additive per-page framework sidecar, the same shape an item method's
+     * envelope carries. Framework-set, not something a handler or `adaptPage`
+     * returns. See {@link ResponseMeta}. */
+    meta?: ResponseMeta;
 }
 /**
  * Return type of every paginated SDK method. The documented surface is:
@@ -480,6 +508,28 @@ declare function withPositional<T extends z.ZodType>(schema: T): T & {
     _def: T["_def"] & PositionalMetadata;
 };
 declare function isPositional(schema: z.ZodType): boolean;
+/**
+ * Marks an optional boolean schema for which omission is distinct from false:
+ * omitting the value means "use the server default" or "preserve the current
+ * value", so an explicit false needs its own affordance. A string supplies
+ * the domain antonym — "disabled" for `enabled` — which each surface renders
+ * in its own vocabulary (a CLI as a flag spelling, a tool description as
+ * prose). `true` requests generic negation when the domain has no antonym.
+ *
+ * Declare it via `.meta({ negatable: "disabled" } satisfies NegatableMetadata)`.
+ * The `satisfies` matters: zod's metadata type permits arbitrary keys, so it
+ * is the only compile-time check against a misspelled key.
+ */
+interface NegatableMetadata {
+    negatable: true | string;
+}
+/**
+ * Read a schema's `negatable` metadata: `true`, the domain antonym, or
+ * undefined when the schema doesn't declare one. Unwraps optional/default
+ * wrappers like `isPositional`, so the `.meta()` call may sit on any layer
+ * of the chain.
+ */
+declare function getNegatable(schema: z.ZodType): NegatableMetadata["negatable"] | undefined;
 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]>;
 
 /**
@@ -504,6 +554,13 @@ interface LeafMetaFields {
     itemType?: string;
     returnType?: string;
     outputSchema?: z.ZodSchema;
+    /** Behavioral opt-out that rides on this config for every `defineMethod`
+     * overload (all merge `LeafMetaFields`), the partner of `outputSchema`: when
+     * true, the materializer skips validating/stripping the output. It is
+     * consumed at build time and stored as a first-class plugin field, NOT folded
+     * into the projected meta (hence absent from `LEAF_META_KEYS`), so it stays
+     * off the registry / CLI / MCP surface, exactly like `skipInputValidation`. */
+    skipOutputValidation?: boolean;
     packages?: string[];
     experimental?: boolean;
     confirm?: "create-secret" | "delete";
@@ -1008,9 +1065,15 @@ interface MethodPlugin<TName extends string = string, TInput = unknown, TOutput
     /** True for a `declareMethod` stand-in: a typed reference with no real
      * implementation. A real plugin under the same id satisfies it. */
     standIn?: boolean;
-    /** True for a `declareOptionalProperty` stand-in over a method id: dependents bind
-     * `undefined` if no real plugin satisfies it. */
+    /** True for a `declareOptionalMethod` stand-in: dependents bind `undefined` if
+     * no real plugin satisfies it, and `PluginSurface` types the binding
+     * `| undefined`. */
     optional?: boolean;
+    /** Present on a `declareDefault` wrapper: this entry is the DEFAULT provider
+     * for its id (preempted by any explicit provider). Its value is the wrapped
+     * plugin, so two defaults for one id dedup (same source) or conflict
+     * (different source). */
+    defaultSource?: AnyLeafPlugin;
     imports: readonly AnyPlugin[];
     /** Binding-name to plugin-id edges, normalized from `imports`;
      * what the `imports` bag is built from. */
@@ -1032,6 +1095,10 @@ interface MethodPlugin<TName extends string = string, TInput = unknown, TOutput
      * For raw methods that own their own validation and must not have their input
      * transformed, e.g. `fetch` passing a `RequestInit` bag through unchanged. */
     skipInputValidation?: boolean;
+    /** When true, the materializer skips validating/stripping `run`'s output
+     * against `meta.outputSchema` (the schema stays for projection). The output
+     * partner of {@link MethodPlugin.skipInputValidation}. */
+    skipOutputValidation?: boolean;
     /** Descriptive metadata for the registry / CLI / MCP / docs (carry-only at
      * runtime). */
     meta?: LeafMeta;
@@ -1146,6 +1213,11 @@ interface PropertyPlugin<TName extends string = string, TValue = unknown> {
      * property satisfies it, dependents bind `undefined` rather than the build
      * failing on a missing dependency. */
     optional?: boolean;
+    /** Present on a `declareDefault` wrapper: this entry is the DEFAULT provider
+     * for its id (preempted by any explicit provider). Its value is the wrapped
+     * plugin, so two defaults for one id dedup (same source) or conflict
+     * (different source). */
+    defaultSource?: AnyLeafPlugin;
     imports: readonly AnyPlugin[];
     /** Binding-name to plugin-id edges, normalized from `imports`;
      * what the `imports` bag is built from. */
@@ -1483,7 +1555,11 @@ type ExportSurface<TChild extends AnyLeafPlugin> = TChild extends MethodPlugin<a
  * bag and `ProvidesOf` is the completeness ledger's phantom ids — both
  * different concepts.
  */
-type PluginSurface<P extends AnyPlugin> = P extends MethodPlugin<infer TName, infer TInput, infer TOutput, infer TPositional> ? {
+type PluginSurface<P extends AnyPlugin> = P extends MethodPlugin<infer TName, infer TInput, infer TOutput, infer TPositional> ? P extends {
+    optional: true;
+} ? {
+    [K in TName]: SurfaceCall<TInput, TOutput, TPositional> | undefined;
+} : {
     [K in TName]: SurfaceCall<TInput, TOutput, TPositional>;
 } : P extends PropertyPlugin<infer TName, infer TValue> ? {
     [K in TName]: TValue;
@@ -2229,6 +2305,7 @@ declare function defineMethod<const TName extends string, TInput, TResponse exte
     run: (bag: MethodRunBag<ImportsOf<TImports>, TInput, TState>) => TResponse | Promise<TResponse>;
 } & LeafMetaFields): MethodPlugin<TName, TInput, Promise<{
     data: TData;
+    meta?: ResponseMeta;
 }>> & 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;
@@ -2450,6 +2527,19 @@ declare function defineFormatter<const TImports extends ImportsInput = readonly
 declare function declareMethod<const TId extends string, TInput = unknown, TOutput = unknown>(config: {
     id: LiteralString<TId>;
 }): MethodPlugin<LastSegment<TId>, TInput, TOutput> & PluginSummary<TId, never>;
+/**
+ * Declare an OPTIONAL stand-in for a method registered elsewhere: the method twin
+ * of `declareOptionalProperty`. Unlike `declareMethod`, an unsatisfied optional
+ * reference is NOT a missing dependency; the binding is typed
+ * `((input) => output) | undefined`, so the consumer must handle the absent case
+ * (`imports.track?.(...)`). Use it to reference a foreign method userland may or
+ * may not import, without claiming its slot.
+ */
+declare function declareOptionalMethod<const TId extends string, TInput = unknown, TOutput = unknown>(config: {
+    id: LiteralString<TId>;
+}): MethodPlugin<LastSegment<TId>, TInput, TOutput> & {
+    optional: true;
+} & PluginSummary<never, never>;
 /**
  * Define a property leaf. Either a static `value` or a computed `get` (eager,
  * dependencies first, like `setup`). `createSdk`, a dependent's `imports`, or
@@ -2507,6 +2597,21 @@ declare function declareProperty<const TId extends string, TValue = unknown>(con
 declare function declareOptionalProperty<const TId extends string, TValue = unknown>(config: {
     id: LiteralString<TId>;
 }): PropertyPlugin<LastSegment<TId>, TValue | undefined> & PluginSummary<never, never>;
+/**
+ * Declare a DEFAULT provider for a dependency you own: import the capability the
+ * given plugin provides, and fall back to that plugin when nothing else provides
+ * its id. Kind-agnostic (the plugin supplies id, type, and kind), so no
+ * method/property split.
+ *
+ * A default materializes a real, single node, so it works out of the box and can
+ * be wrapped or replaced: an explicit provider of the same id silently preempts
+ * it, and two different defaults for one id error only when nothing else provides
+ * it. See the Defaults section in the kitcore README for default vs optional
+ * reference.
+ */
+declare function declareDefault<P extends AnyLeafPlugin>({ plugin, }: {
+    plugin: P;
+}): P;
 /**
  * Define a method-lifecycle hook: a leaf whose `observe` contributes
  * fire-and-forget observers (`onMethodStart` / `onMethodEnd`) the method
@@ -2859,6 +2964,15 @@ interface CoreOptions {
      * reserved for an `on*`-named observer when the unified event bus lands.
      */
     logDeprecation?: (warning: DeprecationWarning) => void;
+    /**
+     * Report what output validation stripped, on the response's
+     * `meta.outputValidation.droppedPaths` (the name mirrors that path). Off by
+     * default: the report is a debugging aid for reconciling a schema against the
+     * wire, and a sidecar every caller has to ignore is worse than one a head
+     * turns on while it audits its schemas. Off also skips the recursive
+     * raw-vs-parsed diff, so the strip costs a parse and nothing more.
+     */
+    includeOutputValidationDroppedPaths?: boolean;
 }
 
 /**
@@ -3449,6 +3563,8 @@ declare function createPaginatedFunction<TUserOptions, TResponse, TItem = ItemTy
     adaptPage?: (response: TResponse) => SdkPage<NoInfer<TItem>>;
     /** Pre-run per-method annotator (see applyAnnotations). */
     annotator?: (input: unknown) => Annotations;
+    /** Applied to each canonical page after the shape guard (output validation). */
+    finalizePage?: (page: SdkPage<TItem>) => SdkPage<TItem>;
     /** Live read of the method's deprecation meta (see signalDeprecation). */
     getDeprecation?: () => FunctionDeprecation | undefined;
 }): (options?: TUserOptions & {
@@ -3749,4 +3865,4 @@ declare class CoreCancelledSignal extends CoreSignal {
  */
 declare function isCoreCancelledSignal(value: unknown): value is CoreCancelledSignal;
 
-export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type Annotations, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type BoundFormatter, type BoundResolver, CONTEXT, CORE_ERROR_SYMBOL, CORE_OPTIONS_ID, CORE_SIGNAL_SYMBOL, type CallContext, type CallOrigin, type CategoryDefinition, type ComposedAnnotator, type ConstantResolver$1 as ConstantResolver, type Controller, type ControllerAction, type ControllerAffordance, type ControllerAnswerFn, type ControllerChoice, type ControllerError, type ControllerIssue, type ControllerListingPage, type ControllerListingPosition, type ControllerMethodDescription, type ControllerMethodSummary, type ControllerPagination, type ControllerParameterDescription, type ControllerPath, type ControllerQuestion, type ControllerResult, type ControllerSdk, type ControllerSelectPage, type ControllerState, type CoreApiError, CoreCancelledSignal, CoreDisposeError, CoreError, CoreErrorCode, type CoreErrorOptions, type CoreOptions, CoreSignal, type CreateSdkOptions, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DisposeFn, type DynamicListResolver, type DynamicMember, type DynamicResolver$1 as DynamicResolver, type DynamicSearchResolver, type FieldsResolver, type FormattedItem, type Formatter, type FunctionDeprecation, type FunctionRegistryEntry, type HookAnnotator, type HookPlugin, type LeafMeta, type LeafSummary, type LegacyMergePlugin, type LegacyPlugin, type ListItemsResult, type ListPromptConfig, type MethodAnnotator, type MethodAttachment, type MethodHooks, type MethodOverridePlugin, type MethodPlugin, type MethodScope, type Resolver as ModelResolver, 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 PluginSurface, 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, canonicalInputSchema, composePlugins, concatLists, concatPaginated, coreOptionsPluginRef, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createValidator, dangerousContextPlugin, declareMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, disposeSdk, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getOutputSchema, getRegistryPlugin, getSchemaDescription, isCoreCancelledSignal, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, resolvePlugin, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };
+export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type Annotations, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type BoundFormatter, type BoundResolver, CONTEXT, CORE_ERROR_SYMBOL, CORE_OPTIONS_ID, CORE_SIGNAL_SYMBOL, type CallContext, type CallOrigin, type CategoryDefinition, type ComposedAnnotator, type ConstantResolver$1 as ConstantResolver, type Controller, type ControllerAction, type ControllerAffordance, type ControllerAnswerFn, type ControllerChoice, type ControllerError, type ControllerIssue, type ControllerListingPage, type ControllerListingPosition, type ControllerMethodDescription, type ControllerMethodSummary, type ControllerPagination, type ControllerParameterDescription, type ControllerPath, type ControllerQuestion, type ControllerResult, type ControllerSdk, type ControllerSelectPage, type ControllerState, type CoreApiError, CoreCancelledSignal, CoreDisposeError, CoreError, CoreErrorCode, type CoreErrorOptions, type CoreOptions, CoreSignal, type CreateSdkOptions, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DisposeFn, type DynamicListResolver, type DynamicMember, type DynamicResolver$1 as DynamicResolver, type DynamicSearchResolver, type FieldsResolver, type FormattedItem, type Formatter, type FunctionDeprecation, type FunctionRegistryEntry, type HookAnnotator, type HookPlugin, type LeafMeta, type LeafSummary, type LegacyMergePlugin, type LegacyPlugin, type ListItemsResult, type ListPromptConfig, type MethodAnnotator, type MethodAttachment, type MethodHooks, type MethodOverridePlugin, type MethodPlugin, type MethodScope, type Resolver as ModelResolver, type NegatableMetadata, 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 PluginSurface, 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 ResponseMeta, type Sdk, type SdkContext, type SdkPage, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, canonicalInputSchema, composePlugins, concatLists, concatPaginated, coreOptionsPluginRef, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createValidator, dangerousContextPlugin, declareDefault, declareMethod, declareOptionalMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, disposeSdk, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getNegatable, getOutputSchema, getRegistryPlugin, getSchemaDescription, isCoreCancelledSignal, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, resolvePlugin, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };