@zapier/kitcore 0.14.0 → 0.15.0

package/dist/index.d.mts

@@ -222,6 +222,72 @@ interface MethodHooks {
     annotator?: ComposedAnnotator;
 }
 
+/**
+ * API stability tiers.
+ *
+ * A plugin declares exactly one level via `PluginMeta.stability`; tier
+ * membership (which subpath aggregate exports the plugin) is structural,
+ * so nothing here compares levels ordinally. The array is the single
+ * source of truth: it derives the {@link StabilityLevel} type, gives the
+ * ladder tests their adjacent-tier iteration order, and gives docs a
+ * render order.
+ */
+declare const STABILITY_LEVELS: readonly ["stable", "beta", "experimental"];
+type StabilityLevel = (typeof STABILITY_LEVELS)[number];
+/**
+ * Title-case display names for each level, for section-level badges in
+ * generated docs (e.g. `Code Workflows (Beta)`). Inline description
+ * labels go through {@link applyStabilityLabel} instead.
+ */
+declare const STABILITY_TITLES: {
+    readonly stable: "Stable";
+    readonly beta: "Beta";
+    readonly experimental: "Experimental";
+};
+/**
+ * Normalize authored meta to a concrete level: absent means `"stable"`,
+ * and the deprecated `experimental: true` boolean means `"experimental"`.
+ * The registry projection runs every entry through this, so
+ * `FunctionRegistryEntry.stability` is always concrete and consumers
+ * never branch on `undefined`.
+ *
+ * The declared value can cross a JSON boundary from a hand-written
+ * plugin, so at runtime it may be any string. An unrecognized level
+ * clamps to `"experimental"` — the author declared the method not
+ * stable, and clamping keeps the raw string out of notices and labels.
+ * It doesn't throw because this also runs in the `getStability` live
+ * read on the call path, where a throw would break the observed call.
+ */
+declare function normalizeStability(meta: {
+    stability?: StabilityLevel;
+    experimental?: boolean;
+}): StabilityLevel;
+/**
+ * The shared label renderer: every consumer that renders a registry
+ * entry's description (CLI help, MCP tool descriptions) labels it
+ * through this function, so a new consumer cannot silently drop the
+ * label. `stability` stays structured data on the registry entry — the
+ * label is applied at render time, never baked into the stored
+ * description (docs badge at the section level, so baking it in would
+ * double-badge).
+ *
+ * The label follows the plugin's declared level, not the subpath that
+ * surfaced it: a beta method surfaced through an experimental-tier
+ * consumer still reads "(beta)".
+ */
+declare function applyStabilityLabel({ description, stability, placement, }: {
+    description: string;
+    /** Absent means stable (the value may arrive from outside the
+     * normalized registry projection, e.g. hand-built JSON). */
+    stability: StabilityLevel | undefined;
+    /**
+     * `"suffix"` renders `<description> (beta)` (CLI help);
+     * `"prefix"` renders `[Beta] <description>` (MCP tool descriptions,
+     * where the front of the string is what an LLM reads first).
+     */
+    placement?: "suffix" | "prefix";
+}): string;
+
 /**
  * Plugins with a required-parameter rename declare two schemas: a canonical one
  * (new names only, carrying `.meta({ aliases })`) and a `z.union([canonical,
@@ -562,6 +628,8 @@ interface LeafMetaFields {
      * off the registry / CLI / MCP surface, exactly like `skipInputValidation`. */
     skipOutputValidation?: boolean;
     packages?: string[];
+    stability?: StabilityLevel;
+    /** @deprecated Use `stability: "experimental"` instead. */
     experimental?: boolean;
     confirm?: "create-secret" | "delete";
     deprecation?: FunctionDeprecation;
@@ -1748,8 +1816,17 @@ interface FunctionRegistryEntry {
     resolvers?: Record<string, BoundResolver>;
     packages?: string[];
     /**
-     * True if the plugin is registered only in the experimental SDK
-     * factory. See `PluginMeta.experimental`.
+     * API stability tier of the plugin, normalized from `PluginMeta.stability`
+     * (absent means `"stable"`; the legacy `experimental: true` boolean means
+     * `"experimental"`). Always concrete here, so consumers never branch on
+     * `undefined`.
+     */
+    stability: StabilityLevel;
+    /**
+     * @deprecated Read `stability` instead. Derived as
+     * `stability === "experimental"` — literal by name, so beta reads
+     * `false`; the not-stable warning duty lives in `stability` and the
+     * runtime stability notice.
      */
     experimental?: boolean;
     /** Confirmation prompt type - prompts user before executing */
@@ -1845,10 +1922,19 @@ interface PluginMeta<TSdk = unknown> {
     /** 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.
+     * API stability tier this plugin belongs to. Absent means `"stable"`;
+     * the registry projection normalizes it, so registry consumers always
+     * read a concrete {@link StabilityLevel}. Wrappers keep non-stable
+     * plugins out of their stable build (by gating them behind a `beta` /
+     * `experimental` subpath import) and consumers badge the level in
+     * generated docs, CLI help, and MCP tool descriptions. No runtime
+     * capability check.
+     */
+    stability?: StabilityLevel;
+    /**
+     * @deprecated Use `stability: "experimental"` instead. Kept as an
+     * input for external authors; `true` normalizes to
+     * `stability: "experimental"` in the registry projection.
      */
     experimental?: boolean;
     [key: string]: any;
@@ -2928,6 +3014,16 @@ interface DeprecationWarning {
  * once-per-process per message.
  */
 declare function defaultLogDeprecation({ methodName, deprecation, }: DeprecationWarning): void;
+/**
+ * What the boundary reports when a non-stable (beta / experimental) method
+ * is called: the method plus its declared level. `DeprecationWarning`'s
+ * sibling — same self-describing shape, same handler-not-observer contract.
+ */
+interface StabilityNotice {
+    type: "stability";
+    methodName: string;
+    stability: StabilityLevel;
+}
 /**
  * The well-known id for framework options: heads inject a `CoreOptions` bag
  * under it via `createSdk`'s `configuration` (or register a property plugin),
@@ -2964,6 +3060,16 @@ interface CoreOptions {
      * reserved for an `on*`-named observer when the unified event bus lands.
      */
     logDeprecation?: (warning: DeprecationWarning) => void;
+    /**
+     * `logDeprecation`'s sibling for API stability: the framework signals
+     * every surface call of a method declaring a non-stable `stability`
+     * level (beta / experimental), and this gate decides what happens.
+     * Exactly one: absent falls back to {@link defaultLogStabilityNotice}
+     * (once-per-process per message), supplied replaces it. Runs isolated,
+     * so a throwing handler never breaks the observed call. Internal
+     * delegation never signals, matching the deprecation contract.
+     */
+    logStabilityNotice?: (notice: StabilityNotice) => void;
     /**
      * Report what output validation stripped, on the response's
      * `meta.outputValidation.droppedPaths` (the name mirrors that path). Off by
@@ -3527,6 +3633,8 @@ declare function createFunction<TOptions, TResult, TSchemaOptions extends TOptio
     annotator?: (input: unknown) => Annotations;
     /** Live read of the method's deprecation meta (see signalDeprecation). */
     getDeprecation?: () => FunctionDeprecation | undefined;
+    /** Live read of the method's stability level (see signalStability). */
+    getStability?: () => StabilityLevel | undefined;
 }): (callOptions?: TOptions) => Promise<TResult>;
 /**
  * Higher-order function that creates a paginated function that wraps
@@ -3567,6 +3675,8 @@ declare function createPaginatedFunction<TUserOptions, TResponse, TItem = ItemTy
     finalizePage?: (page: SdkPage<TItem>) => SdkPage<TItem>;
     /** Live read of the method's deprecation meta (see signalDeprecation). */
     getDeprecation?: () => FunctionDeprecation | undefined;
+    /** Live read of the method's stability level (see signalStability). */
+    getStability?: () => StabilityLevel | undefined;
 }): (options?: TUserOptions & {
     cursor?: string;
     pageSize?: number;
@@ -3808,6 +3918,16 @@ interface DeprecationLogger {
  * channels while sharing the implementation.
  */
 declare function createDeprecationLogger(tag: string): DeprecationLogger;
+interface StabilityNoticeLogger {
+    logStabilityNotice(message: string): void;
+    resetStabilityNotices(): void;
+}
+/**
+ * Create a package-tagged stability-notice logger: the deprecation logger's
+ * sibling for non-stable (beta / experimental) API warnings, with the same
+ * once-per-process dedupe policy and its own independent message Set.
+ */
+declare function createStabilityNoticeLogger(tag: string): StabilityNoticeLogger;
 
 /**
  * Core signal machinery.
@@ -4235,4 +4355,4 @@ declare const normalizeConnectionPlugin: MethodPlugin<"normalizeConnection", Nor
  */
 declare const resolveConnectionPlugin: MethodPlugin<"resolveConnection", ResolveConnectionInput, string | undefined, readonly []> & LeafSummary<"kitcore", "resolveConnection", readonly []>;
 
-export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type Annotations, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type AttemptHttpRequestInput, type AuthorizeHttpRequestInput, 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 DefaultConnectionSchemeInput, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DispatchHttpRequestInput, 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 HttpAttemptContext, type HttpFetchInit, type HttpOperationContext, type HttpOperationStart, type HttpPipelineState, type HttpRequest, type HttpRequestInput, type HttpResponse, type InitializeHttpRequestInput, 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 NormalizeConnectionInput, type NormalizedConnection, 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 PrepareHttpRequestInput, type PromptConfig, type PromptConfigChoice, type PropertyPlugin, RETRY_HTTP_REQUEST_OPTIONS_ID, type ReceiveHttpResponseInput, type RegistryResult, type RequiredSdkOf, type ResolveConnectionInput, type Resolver$1 as Resolver, type ResolverConfig, type ResolverFieldItem, type ResolverMetadata, type ResolverPromptConfig, type ResolverType, type ResponseMeta, type RetryHttpRequestOptions, type Sdk, type SdkContext, type SdkPage, type SendHttpRequest, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, attemptHttpRequestPlugin, authorizeHttpRequestPlugin, 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, defaultConnectionSchemePlugin, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, dispatchHttpRequestPlugin, disposeSdk, fetchPlugin, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getNegatable, getOutputSchema, getRegistryPlugin, getSchemaDescription, initializeHttpRequestPlugin, isCoreCancelledSignal, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, normalizeConnectionPlugin, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, prepareHttpRequestPlugin, receiveHttpResponsePlugin, redactHeaders, redactHttpRequest, resolveConnectionPlugin, resolvePlugin, retryHttpRequestOptionsPluginRef, retryHttpRequestPlugin, runInMethodScope, runWithTelemetryContext, selectExports, sendHttpRequestPlugin, 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 AttemptHttpRequestInput, type AuthorizeHttpRequestInput, 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 DefaultConnectionSchemeInput, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DispatchHttpRequestInput, 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 HttpAttemptContext, type HttpFetchInit, type HttpOperationContext, type HttpOperationStart, type HttpPipelineState, type HttpRequest, type HttpRequestInput, type HttpResponse, type InitializeHttpRequestInput, 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 NormalizeConnectionInput, type NormalizedConnection, 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 PrepareHttpRequestInput, type PromptConfig, type PromptConfigChoice, type PropertyPlugin, RETRY_HTTP_REQUEST_OPTIONS_ID, type ReceiveHttpResponseInput, type RegistryResult, type RequiredSdkOf, type ResolveConnectionInput, type Resolver$1 as Resolver, type ResolverConfig, type ResolverFieldItem, type ResolverMetadata, type ResolverPromptConfig, type ResolverType, type ResponseMeta, type RetryHttpRequestOptions, STABILITY_LEVELS, STABILITY_TITLES, type Sdk, type SdkContext, type SdkPage, type SendHttpRequest, type StabilityLevel, type StabilityNotice, type StabilityNoticeLogger, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, applyStabilityLabel, attemptHttpRequestPlugin, authorizeHttpRequestPlugin, canonicalInputSchema, composePlugins, concatLists, concatPaginated, coreOptionsPluginRef, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createStabilityNoticeLogger, createValidator, dangerousContextPlugin, declareDefault, declareMethod, declareOptionalMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultConnectionSchemePlugin, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, dispatchHttpRequestPlugin, disposeSdk, fetchPlugin, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getNegatable, getOutputSchema, getRegistryPlugin, getSchemaDescription, initializeHttpRequestPlugin, isCoreCancelledSignal, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, normalizeConnectionPlugin, normalizeStability, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, prepareHttpRequestPlugin, receiveHttpResponsePlugin, redactHeaders, redactHttpRequest, resolveConnectionPlugin, resolvePlugin, retryHttpRequestOptionsPluginRef, retryHttpRequestPlugin, runInMethodScope, runWithTelemetryContext, selectExports, sendHttpRequestPlugin, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };

package/dist/index.d.ts

@@ -222,6 +222,72 @@ interface MethodHooks {
     annotator?: ComposedAnnotator;
 }
 
+/**
+ * API stability tiers.
+ *
+ * A plugin declares exactly one level via `PluginMeta.stability`; tier
+ * membership (which subpath aggregate exports the plugin) is structural,
+ * so nothing here compares levels ordinally. The array is the single
+ * source of truth: it derives the {@link StabilityLevel} type, gives the
+ * ladder tests their adjacent-tier iteration order, and gives docs a
+ * render order.
+ */
+declare const STABILITY_LEVELS: readonly ["stable", "beta", "experimental"];
+type StabilityLevel = (typeof STABILITY_LEVELS)[number];
+/**
+ * Title-case display names for each level, for section-level badges in
+ * generated docs (e.g. `Code Workflows (Beta)`). Inline description
+ * labels go through {@link applyStabilityLabel} instead.
+ */
+declare const STABILITY_TITLES: {
+    readonly stable: "Stable";
+    readonly beta: "Beta";
+    readonly experimental: "Experimental";
+};
+/**
+ * Normalize authored meta to a concrete level: absent means `"stable"`,
+ * and the deprecated `experimental: true` boolean means `"experimental"`.
+ * The registry projection runs every entry through this, so
+ * `FunctionRegistryEntry.stability` is always concrete and consumers
+ * never branch on `undefined`.
+ *
+ * The declared value can cross a JSON boundary from a hand-written
+ * plugin, so at runtime it may be any string. An unrecognized level
+ * clamps to `"experimental"` — the author declared the method not
+ * stable, and clamping keeps the raw string out of notices and labels.
+ * It doesn't throw because this also runs in the `getStability` live
+ * read on the call path, where a throw would break the observed call.
+ */
+declare function normalizeStability(meta: {
+    stability?: StabilityLevel;
+    experimental?: boolean;
+}): StabilityLevel;
+/**
+ * The shared label renderer: every consumer that renders a registry
+ * entry's description (CLI help, MCP tool descriptions) labels it
+ * through this function, so a new consumer cannot silently drop the
+ * label. `stability` stays structured data on the registry entry — the
+ * label is applied at render time, never baked into the stored
+ * description (docs badge at the section level, so baking it in would
+ * double-badge).
+ *
+ * The label follows the plugin's declared level, not the subpath that
+ * surfaced it: a beta method surfaced through an experimental-tier
+ * consumer still reads "(beta)".
+ */
+declare function applyStabilityLabel({ description, stability, placement, }: {
+    description: string;
+    /** Absent means stable (the value may arrive from outside the
+     * normalized registry projection, e.g. hand-built JSON). */
+    stability: StabilityLevel | undefined;
+    /**
+     * `"suffix"` renders `<description> (beta)` (CLI help);
+     * `"prefix"` renders `[Beta] <description>` (MCP tool descriptions,
+     * where the front of the string is what an LLM reads first).
+     */
+    placement?: "suffix" | "prefix";
+}): string;
+
 /**
  * Plugins with a required-parameter rename declare two schemas: a canonical one
  * (new names only, carrying `.meta({ aliases })`) and a `z.union([canonical,
@@ -562,6 +628,8 @@ interface LeafMetaFields {
      * off the registry / CLI / MCP surface, exactly like `skipInputValidation`. */
     skipOutputValidation?: boolean;
     packages?: string[];
+    stability?: StabilityLevel;
+    /** @deprecated Use `stability: "experimental"` instead. */
     experimental?: boolean;
     confirm?: "create-secret" | "delete";
     deprecation?: FunctionDeprecation;
@@ -1748,8 +1816,17 @@ interface FunctionRegistryEntry {
     resolvers?: Record<string, BoundResolver>;
     packages?: string[];
     /**
-     * True if the plugin is registered only in the experimental SDK
-     * factory. See `PluginMeta.experimental`.
+     * API stability tier of the plugin, normalized from `PluginMeta.stability`
+     * (absent means `"stable"`; the legacy `experimental: true` boolean means
+     * `"experimental"`). Always concrete here, so consumers never branch on
+     * `undefined`.
+     */
+    stability: StabilityLevel;
+    /**
+     * @deprecated Read `stability` instead. Derived as
+     * `stability === "experimental"` — literal by name, so beta reads
+     * `false`; the not-stable warning duty lives in `stability` and the
+     * runtime stability notice.
      */
     experimental?: boolean;
     /** Confirmation prompt type - prompts user before executing */
@@ -1845,10 +1922,19 @@ interface PluginMeta<TSdk = unknown> {
     /** 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.
+     * API stability tier this plugin belongs to. Absent means `"stable"`;
+     * the registry projection normalizes it, so registry consumers always
+     * read a concrete {@link StabilityLevel}. Wrappers keep non-stable
+     * plugins out of their stable build (by gating them behind a `beta` /
+     * `experimental` subpath import) and consumers badge the level in
+     * generated docs, CLI help, and MCP tool descriptions. No runtime
+     * capability check.
+     */
+    stability?: StabilityLevel;
+    /**
+     * @deprecated Use `stability: "experimental"` instead. Kept as an
+     * input for external authors; `true` normalizes to
+     * `stability: "experimental"` in the registry projection.
      */
     experimental?: boolean;
     [key: string]: any;
@@ -2928,6 +3014,16 @@ interface DeprecationWarning {
  * once-per-process per message.
  */
 declare function defaultLogDeprecation({ methodName, deprecation, }: DeprecationWarning): void;
+/**
+ * What the boundary reports when a non-stable (beta / experimental) method
+ * is called: the method plus its declared level. `DeprecationWarning`'s
+ * sibling — same self-describing shape, same handler-not-observer contract.
+ */
+interface StabilityNotice {
+    type: "stability";
+    methodName: string;
+    stability: StabilityLevel;
+}
 /**
  * The well-known id for framework options: heads inject a `CoreOptions` bag
  * under it via `createSdk`'s `configuration` (or register a property plugin),
@@ -2964,6 +3060,16 @@ interface CoreOptions {
      * reserved for an `on*`-named observer when the unified event bus lands.
      */
     logDeprecation?: (warning: DeprecationWarning) => void;
+    /**
+     * `logDeprecation`'s sibling for API stability: the framework signals
+     * every surface call of a method declaring a non-stable `stability`
+     * level (beta / experimental), and this gate decides what happens.
+     * Exactly one: absent falls back to {@link defaultLogStabilityNotice}
+     * (once-per-process per message), supplied replaces it. Runs isolated,
+     * so a throwing handler never breaks the observed call. Internal
+     * delegation never signals, matching the deprecation contract.
+     */
+    logStabilityNotice?: (notice: StabilityNotice) => void;
     /**
      * Report what output validation stripped, on the response's
      * `meta.outputValidation.droppedPaths` (the name mirrors that path). Off by
@@ -3527,6 +3633,8 @@ declare function createFunction<TOptions, TResult, TSchemaOptions extends TOptio
     annotator?: (input: unknown) => Annotations;
     /** Live read of the method's deprecation meta (see signalDeprecation). */
     getDeprecation?: () => FunctionDeprecation | undefined;
+    /** Live read of the method's stability level (see signalStability). */
+    getStability?: () => StabilityLevel | undefined;
 }): (callOptions?: TOptions) => Promise<TResult>;
 /**
  * Higher-order function that creates a paginated function that wraps
@@ -3567,6 +3675,8 @@ declare function createPaginatedFunction<TUserOptions, TResponse, TItem = ItemTy
     finalizePage?: (page: SdkPage<TItem>) => SdkPage<TItem>;
     /** Live read of the method's deprecation meta (see signalDeprecation). */
     getDeprecation?: () => FunctionDeprecation | undefined;
+    /** Live read of the method's stability level (see signalStability). */
+    getStability?: () => StabilityLevel | undefined;
 }): (options?: TUserOptions & {
     cursor?: string;
     pageSize?: number;
@@ -3808,6 +3918,16 @@ interface DeprecationLogger {
  * channels while sharing the implementation.
  */
 declare function createDeprecationLogger(tag: string): DeprecationLogger;
+interface StabilityNoticeLogger {
+    logStabilityNotice(message: string): void;
+    resetStabilityNotices(): void;
+}
+/**
+ * Create a package-tagged stability-notice logger: the deprecation logger's
+ * sibling for non-stable (beta / experimental) API warnings, with the same
+ * once-per-process dedupe policy and its own independent message Set.
+ */
+declare function createStabilityNoticeLogger(tag: string): StabilityNoticeLogger;
 
 /**
  * Core signal machinery.
@@ -4235,4 +4355,4 @@ declare const normalizeConnectionPlugin: MethodPlugin<"normalizeConnection", Nor
  */
 declare const resolveConnectionPlugin: MethodPlugin<"resolveConnection", ResolveConnectionInput, string | undefined, readonly []> & LeafSummary<"kitcore", "resolveConnection", readonly []>;
 
-export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type Annotations, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type AttemptHttpRequestInput, type AuthorizeHttpRequestInput, 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 DefaultConnectionSchemeInput, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DispatchHttpRequestInput, 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 HttpAttemptContext, type HttpFetchInit, type HttpOperationContext, type HttpOperationStart, type HttpPipelineState, type HttpRequest, type HttpRequestInput, type HttpResponse, type InitializeHttpRequestInput, 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 NormalizeConnectionInput, type NormalizedConnection, 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 PrepareHttpRequestInput, type PromptConfig, type PromptConfigChoice, type PropertyPlugin, RETRY_HTTP_REQUEST_OPTIONS_ID, type ReceiveHttpResponseInput, type RegistryResult, type RequiredSdkOf, type ResolveConnectionInput, type Resolver$1 as Resolver, type ResolverConfig, type ResolverFieldItem, type ResolverMetadata, type ResolverPromptConfig, type ResolverType, type ResponseMeta, type RetryHttpRequestOptions, type Sdk, type SdkContext, type SdkPage, type SendHttpRequest, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, attemptHttpRequestPlugin, authorizeHttpRequestPlugin, 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, defaultConnectionSchemePlugin, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, dispatchHttpRequestPlugin, disposeSdk, fetchPlugin, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getNegatable, getOutputSchema, getRegistryPlugin, getSchemaDescription, initializeHttpRequestPlugin, isCoreCancelledSignal, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, normalizeConnectionPlugin, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, prepareHttpRequestPlugin, receiveHttpResponsePlugin, redactHeaders, redactHttpRequest, resolveConnectionPlugin, resolvePlugin, retryHttpRequestOptionsPluginRef, retryHttpRequestPlugin, runInMethodScope, runWithTelemetryContext, selectExports, sendHttpRequestPlugin, 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 AttemptHttpRequestInput, type AuthorizeHttpRequestInput, 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 DefaultConnectionSchemeInput, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DispatchHttpRequestInput, 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 HttpAttemptContext, type HttpFetchInit, type HttpOperationContext, type HttpOperationStart, type HttpPipelineState, type HttpRequest, type HttpRequestInput, type HttpResponse, type InitializeHttpRequestInput, 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 NormalizeConnectionInput, type NormalizedConnection, 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 PrepareHttpRequestInput, type PromptConfig, type PromptConfigChoice, type PropertyPlugin, RETRY_HTTP_REQUEST_OPTIONS_ID, type ReceiveHttpResponseInput, type RegistryResult, type RequiredSdkOf, type ResolveConnectionInput, type Resolver$1 as Resolver, type ResolverConfig, type ResolverFieldItem, type ResolverMetadata, type ResolverPromptConfig, type ResolverType, type ResponseMeta, type RetryHttpRequestOptions, STABILITY_LEVELS, STABILITY_TITLES, type Sdk, type SdkContext, type SdkPage, type SendHttpRequest, type StabilityLevel, type StabilityNotice, type StabilityNoticeLogger, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, applyStabilityLabel, attemptHttpRequestPlugin, authorizeHttpRequestPlugin, canonicalInputSchema, composePlugins, concatLists, concatPaginated, coreOptionsPluginRef, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createStabilityNoticeLogger, createValidator, dangerousContextPlugin, declareDefault, declareMethod, declareOptionalMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultConnectionSchemePlugin, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, dispatchHttpRequestPlugin, disposeSdk, fetchPlugin, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getNegatable, getOutputSchema, getRegistryPlugin, getSchemaDescription, initializeHttpRequestPlugin, isCoreCancelledSignal, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, normalizeConnectionPlugin, normalizeStability, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, prepareHttpRequestPlugin, receiveHttpResponsePlugin, redactHeaders, redactHttpRequest, resolveConnectionPlugin, resolvePlugin, retryHttpRequestOptionsPluginRef, retryHttpRequestPlugin, runInMethodScope, runWithTelemetryContext, selectExports, sendHttpRequestPlugin, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };

package/dist/index.mjs

@@ -89,6 +89,28 @@ function openEnum(values, description) {
   return z.union([z.enum(values), z.string()]).describe(description);
 }
 
+// src/utils/stability.ts
+var STABILITY_LEVELS = ["stable", "beta", "experimental"];
+var STABILITY_TITLES = {
+  stable: "Stable",
+  beta: "Beta",
+  experimental: "Experimental"
+};
+function normalizeStability(meta) {
+  if (meta.stability !== void 0) {
+    return STABILITY_LEVELS.includes(meta.stability) ? meta.stability : "experimental";
+  }
+  return meta.experimental ? "experimental" : "stable";
+}
+function applyStabilityLabel({
+  description,
+  stability,
+  placement = "suffix"
+}) {
+  if (stability === void 0 || stability === "stable") return description;
+  return placement === "prefix" ? `[${STABILITY_TITLES[stability]}] ${description}` : `${description} (${stability})`;
+}
+
 // src/registry.ts
 function resolveCategoryDefinition(ref) {
   const def = typeof ref === "string" ? { key: ref } : ref;
@@ -133,6 +155,7 @@ function buildRegistry({
     return typeof rootProperty === "object" && rootProperty !== null;
   }).map((key) => {
     const m = meta[key];
+    const stability = normalizeStability(m);
     return {
       name: key,
       description: m.description,
@@ -148,7 +171,11 @@ function buildRegistry({
       ),
       resolvers: resolvers?.[key],
       formatter: formatters?.[key],
-      experimental: m.experimental,
+      stability,
+      // Deprecated derived read, literal by name: only the experimental
+      // tier reads true. Beta reads false — the "not stable" warning duty
+      // lives in `stability` and the runtime notice, not this boolean.
+      experimental: stability === "experimental",
       packages: m.packages,
       confirm: m.confirm ?? (m.type === "delete" ? "delete" : void 0),
       deprecation: m.deprecation,
@@ -237,6 +264,20 @@ function createDeprecationLogger(tag) {
   };
 }
 var { logDeprecation, resetDeprecationWarnings } = createDeprecationLogger("core");
+function createStabilityNoticeLogger(tag) {
+  const loggedNotices = /* @__PURE__ */ new Set();
+  return {
+    logStabilityNotice(message) {
+      if (loggedNotices.has(message)) return;
+      loggedNotices.add(message);
+      console.warn(`[${tag}] ${message}`);
+    },
+    resetStabilityNotices() {
+      loggedNotices.clear();
+    }
+  };
+}
+var { logStabilityNotice, resetStabilityNotices } = createStabilityNoticeLogger("core");
 
 // src/types/errors.ts
 var CORE_ERROR_SYMBOL = Symbol.for("kitcore.error");
@@ -721,6 +762,19 @@ function defaultLogDeprecation({
 }) {
   logDeprecation(`${methodName}() is deprecated. ${deprecation.message}`);
 }
+var STABILITY_NOTICE_DETAILS = {
+  beta: "Its API shape is settled, but it is not yet covered by stable-tier guarantees.",
+  experimental: "It may change shape or disappear without notice."
+};
+function defaultLogStabilityNotice({
+  methodName,
+  stability
+}) {
+  if (stability === "stable") return;
+  logStabilityNotice(
+    `${methodName}() is a ${stability} API. ${STABILITY_NOTICE_DETAILS[stability]}`
+  );
+}
 var CORE_OPTIONS_ID = "kitcore/coreOptions";
 
 // src/utils/function-utils.ts
@@ -769,6 +823,18 @@ function signalDeprecation(context, methodName, getDeprecation) {
   const handler = resolveCoreOptions(context)?.logDeprecation ?? defaultLogDeprecation;
   runIsolatedObserver(() => handler(warning));
 }
+function signalStability(context, methodName, getStability) {
+  if (isInsideObserver()) return;
+  const stability = getStability?.();
+  if (!stability || stability === "stable") return;
+  const notice = {
+    type: "stability",
+    methodName,
+    stability
+  };
+  const handler = resolveCoreOptions(context)?.logStabilityNotice ?? defaultLogStabilityNotice;
+  runIsolatedObserver(() => handler(notice));
+}
 function normalizeError(error, adaptError) {
   if (error instanceof Error) return error;
   const message = typeof error === "object" && error !== null && "message" in error && typeof error.message === "string" ? error.message : String(error);
@@ -782,7 +848,7 @@ function normalizeError(error, adaptError) {
   );
 }
 function createFunction(coreFn, options) {
-  const { sdk, schema, name, annotator, getDeprecation } = options;
+  const { sdk, schema, name, annotator, getDeprecation, getStability } = options;
   const functionName = name || coreFn.name;
   const namedFunctions = {
     [functionName]: async function(callOptions) {
@@ -790,6 +856,7 @@ function createFunction(coreFn, options) {
       const context = resolveCallContext(internal);
       if (!isCallContext(internal) && internal !== INTERNAL_CALL) {
         signalDeprecation(sdk.context, functionName, getDeprecation);
+        signalStability(sdk.context, functionName, getStability);
       }
       return runInMethodScope(async () => {
         const startTime = Date.now();
@@ -856,12 +923,21 @@ function createFunction(coreFn, options) {
   return namedFunctions[functionName];
 }
 function createRawFunction(coreFn, options) {
-  const { sdk, name, schema, positional, annotator, getDeprecation } = options;
+  const {
+    sdk,
+    name,
+    schema,
+    positional,
+    annotator,
+    getDeprecation,
+    getStability
+  } = options;
   return function(rawInput) {
     const internal = arguments[1];
     const context = resolveCallContext(internal);
     if (!isCallContext(internal) && internal !== INTERNAL_CALL) {
       signalDeprecation(sdk.context, name, getDeprecation);
+      signalStability(sdk.context, name, getStability);
     }
     return runInMethodScope(() => {
       const startTime = Date.now();
@@ -967,7 +1043,8 @@ function createPaginatedFunction(coreFn, options) {
     adaptPage,
     annotator,
     finalizePage,
-    getDeprecation
+    getDeprecation,
+    getStability
   } = options;
   const pageFunction = createPageFunction(coreFn, {
     sdk,
@@ -981,6 +1058,7 @@ function createPaginatedFunction(coreFn, options) {
       const context = resolveCallContext(internal);
       if (!isCallContext(internal) && internal !== INTERNAL_CALL) {
         signalDeprecation(sdk.context, functionName, getDeprecation);
+        signalStability(sdk.context, functionName, getStability);
       }
       return runInMethodScope(() => {
         const startTime = Date.now();
@@ -1425,6 +1503,7 @@ var LEAF_META_KEYS = [
   "returnType",
   "outputSchema",
   "packages",
+  "stability",
   "experimental",
   "confirm",
   "deprecation",
@@ -2692,7 +2771,8 @@ function buildMethodEntries(descriptors, context, states) {
           // (item mode's sibling); dropped paths surface as `[].x` in the page's
           // `meta`, unioned across items.
           finalizePage: (page) => applyListOutputPolicy(page, outputPolicy()),
-          getDeprecation: () => entry.meta?.deprecation
+          getDeprecation: () => entry.meta?.deprecation,
+          getStability: () => entry.meta ? normalizeStability(entry.meta) : void 0
         }
       );
     } else if (out.type === "item") {
@@ -2704,7 +2784,8 @@ function buildMethodEntries(descriptors, context, states) {
           schema: descriptor.inputSchema,
           name: descriptor.name,
           annotator: boundAnnotator,
-          getDeprecation: () => entry.meta?.deprecation
+          getDeprecation: () => entry.meta?.deprecation,
+          getStability: () => entry.meta ? normalizeStability(entry.meta) : void 0
         }
       );
     } else {
@@ -2718,8 +2799,10 @@ function buildMethodEntries(descriptors, context, states) {
           annotator: boundAnnotator,
           // The boundary reads the deprecation LIVE off the entry, so a
           // deprecation merged after build (defineMethodOverride, addPlugin)
-          // fires too.
-          getDeprecation: () => entry.meta?.deprecation
+          // fires too. Same for the stability level, normalized from the
+          // entry meta (declared level or legacy `experimental` boolean).
+          getDeprecation: () => entry.meta?.deprecation,
+          getStability: () => entry.meta ? normalizeStability(entry.meta) : void 0
         }
       );
     }
@@ -4779,7 +4862,10 @@ export {
   CoreErrorCode,
   CoreSignal,
   RETRY_HTTP_REQUEST_OPTIONS_ID,
+  STABILITY_LEVELS,
+  STABILITY_TITLES,
   addPlugin,
+  applyStabilityLabel,
   attemptHttpRequestPlugin,
   authorizeHttpRequestPlugin,
   canonicalInputSchema,
@@ -4799,6 +4885,7 @@ export {
   createPluginStack,
   createPrefixedCursor,
   createSdk,
+  createStabilityNoticeLogger,
   createValidator,
   dangerousContextPlugin,
   declareDefault,
@@ -4840,6 +4927,7 @@ export {
   isPositional,
   isTelemetryNested,
   normalizeConnectionPlugin,
+  normalizeStability,
   omitExports,
   openEnum,
   paginate,