@zapier/kitcore 0.14.0 → 0.16.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;
@@ -1195,10 +1263,10 @@ type DataOf<TResponse> = TResponse extends {
 } ? TData : 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.
+ * constant; `get({ imports, state })` computes the value from imports and
+ * `setup` state, re-running live on each read. An optional `setup` runs once
+ * eagerly at createSdk (dependencies first, like a method's `setup`) to build
+ * that state. An imported/surfaced property yields the value, not a callable.
  */
 interface PropertyPlugin<TName extends string = string, TValue = unknown> {
     pluginType: "property";
@@ -1238,6 +1306,7 @@ interface PropertyPlugin<TName extends string = string, TValue = unknown> {
     get?: (bag: {
         imports: Record<string, unknown>;
         state: unknown;
+        callContext?: CallContext;
     }) => TValue;
     /** Descriptive metadata for the registry / CLI / MCP / docs (carry-only). */
     meta?: LeafMeta;
@@ -1480,7 +1549,10 @@ interface PropertyEntry {
     pluginType: "property";
     name: string;
     value?: any;
-    getValue?: () => any;
+    /** Re-derives the value per read. Receives the live per-call `CallContext`
+     * when installed on a method's `imports` bag with a threaded context, and
+     * nothing on a surface / build-time read. */
+    getValue?: (callContext?: CallContext) => any;
     /** Carried from the descriptor for the registry / CLI / MCP / docs. */
     meta?: LeafMeta;
     /** Carried from the descriptor: templated registry members for this
@@ -1748,8 +1820,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 +1926,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;
@@ -2541,9 +2631,11 @@ declare function declareOptionalMethod<const TId extends string, TInput = unknow
     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
- * an aggregate's re-export binds it under its bare `name` and yields the value.
+ * Define a property leaf. Either a static `value` or a computed `get`, which
+ * re-runs live on each read; an optional `setup` runs once at `createSdk`
+ * (dependencies first, like a method's `setup`) to build the state `get` reads.
+ * `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;
@@ -2565,6 +2657,13 @@ declare function defineProperty<const TName extends string, TValue, const TImpor
     get: (bag: {
         imports: ImportsOf<TImports>;
         state: TState;
+        /** The live per-call context when the property is read from a method's
+         * `imports` bag — every method call has one, at any depth. Undefined only
+         * where no call is in flight: the property bound onto the SDK object
+         * itself, and reads from a `setup`-time imports bag. A context-aware
+         * property reads its `callId` off this; because its value is then specific
+         * to the reading call, callers must not cache it across calls. */
+        callContext?: CallContext;
     }) => TValue;
     /** Templated registry members for this property's dynamic sub-surface (e.g.
      * a proxy): each a bodyless declaration keyed by `path` instead of `name`. */
@@ -2928,6 +3027,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 +3073,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 +3646,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 +3688,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 +3931,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 +4368,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;
@@ -1195,10 +1263,10 @@ type DataOf<TResponse> = TResponse extends {
 } ? TData : 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.
+ * constant; `get({ imports, state })` computes the value from imports and
+ * `setup` state, re-running live on each read. An optional `setup` runs once
+ * eagerly at createSdk (dependencies first, like a method's `setup`) to build
+ * that state. An imported/surfaced property yields the value, not a callable.
  */
 interface PropertyPlugin<TName extends string = string, TValue = unknown> {
     pluginType: "property";
@@ -1238,6 +1306,7 @@ interface PropertyPlugin<TName extends string = string, TValue = unknown> {
     get?: (bag: {
         imports: Record<string, unknown>;
         state: unknown;
+        callContext?: CallContext;
     }) => TValue;
     /** Descriptive metadata for the registry / CLI / MCP / docs (carry-only). */
     meta?: LeafMeta;
@@ -1480,7 +1549,10 @@ interface PropertyEntry {
     pluginType: "property";
     name: string;
     value?: any;
-    getValue?: () => any;
+    /** Re-derives the value per read. Receives the live per-call `CallContext`
+     * when installed on a method's `imports` bag with a threaded context, and
+     * nothing on a surface / build-time read. */
+    getValue?: (callContext?: CallContext) => any;
     /** Carried from the descriptor for the registry / CLI / MCP / docs. */
     meta?: LeafMeta;
     /** Carried from the descriptor: templated registry members for this
@@ -1748,8 +1820,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 +1926,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;
@@ -2541,9 +2631,11 @@ declare function declareOptionalMethod<const TId extends string, TInput = unknow
     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
- * an aggregate's re-export binds it under its bare `name` and yields the value.
+ * Define a property leaf. Either a static `value` or a computed `get`, which
+ * re-runs live on each read; an optional `setup` runs once at `createSdk`
+ * (dependencies first, like a method's `setup`) to build the state `get` reads.
+ * `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;
@@ -2565,6 +2657,13 @@ declare function defineProperty<const TName extends string, TValue, const TImpor
     get: (bag: {
         imports: ImportsOf<TImports>;
         state: TState;
+        /** The live per-call context when the property is read from a method's
+         * `imports` bag — every method call has one, at any depth. Undefined only
+         * where no call is in flight: the property bound onto the SDK object
+         * itself, and reads from a `setup`-time imports bag. A context-aware
+         * property reads its `callId` off this; because its value is then specific
+         * to the reading call, callers must not cache it across calls. */
+        callContext?: CallContext;
     }) => TValue;
     /** Templated registry members for this property's dynamic sub-surface (e.g.
      * a proxy): each a bodyless declaration keyed by `path` instead of `name`. */
@@ -2928,6 +3027,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 +3073,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 +3646,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 +3688,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 +3931,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 +4368,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 };