@apifuse/provider-sdk 2.2.0-beta.61 → 2.2.0-beta.63

package/dist/cli/migrate-provider-shape.d.ts

@@ -24,7 +24,11 @@ export type ProviderShapeKind =
 "single-phase-default-export"
 /** `const p = defineProvider({ ..., operations }); export default p;` */
  | "single-phase-variable-export"
-/** `const p = defineProvider({ ..., operations }); export default { ...p, deployment };` */
+/**
+ * `const p = defineProvider({ ..., operations }); export default { ...p, extra };`
+ * — extras stay on the spread export; a `deployment` extra is a legacy
+ * surface that `apifuse migrate-deployment` hoists into the declaration.
+ */
  | "single-phase-variable-spread-export"
 /** Already `const b = defineProvider(...); export default b({ operations })` */
  | "two-phase";

package/dist/cli/migrate-provider-shape.js

@@ -218,7 +218,7 @@ function defaultExportCallsBuilder(exportAssignment, declarationCall) {
  * resolves to a builder-call result. Covers the three migrated layouts —
  * `export default buildProvider({...})`, an intermediate
  * `const provider = buildProvider({...}); export default provider;`, and the
- * spread export `export default { ...provider, deployment }` over such a
+ * spread export `export default { ...provider, ...extras }` over such a
  * binding. Without the latter two, re-running the transform on its own
  * spread-shape output reports "ambiguous" instead of "unchanged", which
  * breaks idempotency for repeated fan-out runs.
@@ -376,7 +376,9 @@ function rewriteDefaultExport(source, exportAssignment, shape, builderName, oper
         ];
     }
     // Spread export: re-introduce the provider binding so the extra properties
-    // (currently `deployment`) still spread over a built provider.
+    // (e.g. `healthAccountSeedInputs`, or a legacy `deployment` that
+    // `apifuse migrate-deployment` later hoists) still spread over a built
+    // provider.
     const providerName = shape.variableName ?? "provider";
     const extras = shape.spreadExportExtras ?? "";
     const rebuilt = extras.length > 0

package/dist/cli/resolver-runtime.d.ts

@@ -0,0 +1,21 @@
+import { ResolverTelemetryCollector } from "../runtime/resolver-telemetry.js";
+import type { ProviderCache, ProviderDefinition, ResolverContext } from "../types.js";
+export interface CliResolverRuntime {
+    readonly resolver: ResolverContext;
+    /** Per-context sink; `toLogPayload()` is the `resolver` sibling of the server request log. */
+    readonly resolverTelemetry: ResolverTelemetryCollector;
+    /**
+     * Extend the collector's redaction with values learned after construction (request-scoped
+     * `sensitiveParams` the recorder captures); the collector redacts at record time, before it
+     * truncates, so values must be registered before the vendor call that may echo them.
+     */
+    readonly registerSensitiveValues: (values: readonly string[]) => void;
+}
+/**
+ * Resolver chain for the CLI helper contexts (`apifuse record`, the `apifuse dev` helper), built
+ * like a server request scope: engine-owned solver keys, the CDP pool URL, and the resolver
+ * timeout come from the process environment, the runtime options come from the shared builder,
+ * and every vendor invocation lands in a collector redacted with the provider's static sensitive
+ * inventory. A CLI context has no server-owned identity scope and no proxy telemetry.
+ */
+export declare function createCliResolverRuntime(provider: ProviderDefinition, cache: ProviderCache): CliResolverRuntime;

package/dist/cli/resolver-runtime.js

@@ -0,0 +1,31 @@
+import { compileProcessDiagnosticSensitiveValues, createDiagnosticRedactor, } from "../runtime/diagnostic-redactor.js";
+import { createResolverClientFromEnv, createUnsupportedResolverClient, } from "../runtime/resolver.js";
+import { createResolverRuntimeOptions, resolveNativeProxyPolicy, } from "../runtime/resolver-runtime-options.js";
+import { ResolverTelemetryCollector } from "../runtime/resolver-telemetry.js";
+import { collectStaticDiagnosticSensitiveValues } from "../server/sensitive-values.js";
+import { getStealthProfile } from "../stealth/profiles.js";
+/**
+ * Resolver chain for the CLI helper contexts (`apifuse record`, the `apifuse dev` helper), built
+ * like a server request scope: engine-owned solver keys, the CDP pool URL, and the resolver
+ * timeout come from the process environment, the runtime options come from the shared builder,
+ * and every vendor invocation lands in a collector redacted with the provider's static sensitive
+ * inventory. A CLI context has no server-owned identity scope and no proxy telemetry.
+ */
+export function createCliResolverRuntime(provider, cache) {
+    const sensitiveValues = createDiagnosticRedactor([], compileProcessDiagnosticSensitiveValues(collectStaticDiagnosticSensitiveValues(provider)));
+    const resolverTelemetry = new ResolverTelemetryCollector({ redact: sensitiveValues.redact });
+    const registerSensitiveValues = (values) => sensitiveValues.add(values);
+    if (!provider.resolver) {
+        return {
+            resolver: createUnsupportedResolverClient("Provider does not declare resolver capability"),
+            resolverTelemetry,
+            registerSensitiveValues,
+        };
+    }
+    const stealthProfile = provider.stealth ? getStealthProfile(provider.stealth) : undefined;
+    return {
+        resolver: createResolverClientFromEnv(provider.resolver, process.env, createResolverRuntimeOptions(provider, cache, undefined, resolveNativeProxyPolicy(provider), { upstream: { proxy: provider.proxy } }, stealthProfile, resolverTelemetry)),
+        resolverTelemetry,
+        registerSensitiveValues,
+    };
+}

package/dist/define.d.ts

@@ -54,6 +54,9 @@ export interface ProviderDeclaration {
      * provider definition. The SDK types this field but does not deep-validate
      * it — the APIFuse registry builder owns deployment validation and
      * resolves omitted fields against the runtime deployment profiles.
+     *
+     * This is the only authored deployment surface (no standalone
+     * `deploy.ts`); declare only the fields that differ from the profile.
      */
     deployment?: ProviderDeploymentOverrides;
     /** Declares the HTTP capability binding. A bare object states use without configuration. */

package/dist/define.js

@@ -636,6 +636,11 @@ function validateProviderImplementationShape(config) {
 }
 function validateProviderProxy(config) {
     for (const secret of config.secrets ?? []) {
+        if (secret.issuer !== undefined &&
+            secret.issuer !== "apifuse" &&
+            secret.issuer !== "contributor") {
+            throw new ValidationError(`Provider "${config.id}" secret "${secret.name}" has invalid issuer "${String(secret.issuer)}"`, { fix: `Set issuer to "apifuse" or "contributor", or omit it.` });
+        }
         const engineName = engineOwnedResolverCredentialTarget(secret.name);
         if (engineName !== undefined) {
             throw new ValidationError(`Provider "${config.id}" cannot declare engine-owned resolver credential "${secret.name}"`, {

package/dist/dev.d.ts

@@ -1,10 +1,12 @@
-import type { ProviderEngine } from "./engine.js";
+import type { ProviderEngine, ProviderEngineMode } from "./engine.js";
 import type { ProviderDefinition } from "./types.js";
 export interface DevServerOptions {
     port?: number;
     sessionDbPath?: string;
     /** Override the default in-process engine attachment. */
     engine?: ProviderEngine;
+    /** Explicit engine mode; `APIFUSE__ENGINE__MODE` outranks it when both are set. */
+    engineMode?: ProviderEngineMode;
 }
 export declare function createDevServer(provider: ProviderDefinition, options?: DevServerOptions): {
     start: () => void;

package/dist/dev.js

@@ -5,7 +5,12 @@ export function createDevServer(provider, options) {
         start: () => {
             // Local development has no Redis by default; handles (ADR-0012) need a
             // state backend, so fall back to memory state when none is configured.
-            void serve(provider, { port, engine: options?.engine, allowMemoryStateFallback: true });
+            void serve(provider, {
+                port,
+                engine: options?.engine,
+                engineMode: options?.engineMode,
+                allowMemoryStateFallback: true,
+            });
             console.log(`[apifuse dev] ${provider.id}@${provider.version} running at http://localhost:${port}`);
             console.log(`[apifuse dev] Operations: ${Object.keys(provider.operations).join(", ")}`);
             console.log(`[apifuse dev] Health: http://localhost:${port}/health`);

package/dist/engine.d.ts

@@ -2,6 +2,25 @@ import type { HandleContext } from "./handle.js";
 import type { AuthContext, BrowserClient, CredentialContext, EnvContext, HttpClient, NativeContext, OcrContext, ProviderCache, ProviderContext, ProviderDefinition, ProviderFilesContext, ProviderRequestContext, ProviderRuntimeState, ResolverContext, StealthClient, SttContext, TraceContext } from "./types.js";
 /** Versioned envelope protocol used by out-of-process engine transports. */
 export declare const PROVIDER_ENGINE_PROTOCOL_VERSION: "provider-engine.v1";
+/**
+ * Environment variable that selects how a provider process attaches its capability
+ * bindings. Engine-owned by prefix (`APIFUSE__ENGINE__*`): never declarable as a
+ * provider secret and never projected into `ctx.env`.
+ *
+ * Values are trimmed and case-folded; absent or blank means "unset". An
+ * unrecognized value is reported on the `provider_engine_mode` boot event and
+ * ignored — a deployment-authored typo must never turn into CrashLoopBackOff.
+ */
+export declare const PROVIDER_ENGINE_MODE_ENV = "APIFUSE__ENGINE__MODE";
+/**
+ * How a provider process attaches its capability bindings: `"in-process"` today,
+ * `"remote"` for the authenticated engine (ADR-0011).
+ *
+ * The union is intentionally open so further lanes (for example a provider hosted
+ * inside the engine) can be named without a breaking change. Unknown values are
+ * rejected at runtime, not by the type.
+ */
+export type ProviderEngineMode = "in-process" | "remote" | (string & {});
 /** Credential names owned by the engine and forbidden in provider declarations. */
 export declare const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES: readonly ["APIFUSE__PROXY__SMARTPROXY_APP_KEY", "APIFUSE__PROXY__NODEMAVEN_USERNAME", "APIFUSE__PROXY__NODEMAVEN_PASSWORD"];
 export declare function isEngineOwnedProxyCredentialName(name: string): boolean;
@@ -89,7 +108,22 @@ export interface ProviderEngineAttachmentInput {
 }
 /** Attachment boundary shared by in-process development and remote RPC bridges. */
 export interface ProviderEngine {
+    /**
+     * Which attachment this engine performs. Lets the server report a truthful
+     * mode at boot and compare an explicit engine object against a requested
+     * `engineMode`; omit for opaque host engines (reported as `custom`).
+     */
+    readonly kind?: ProviderEngineMode;
     attach<TDeclaration extends object = Record<string, unknown>>(input: ProviderEngineAttachmentInput): ProviderContext<TDeclaration>;
 }
-/** Local engine attachment; deployed bridges implement the same interface with RPC clients. */
+/**
+ * Local engine attachment; deployed bridges implement the same interface with RPC clients.
+ *
+ * ADR-0011 makes the authenticated remote engine the only attachment, so this one
+ * is scheduled for removal — but not deprecated yet: the remote client ships in a
+ * later release, and deprecating the only working constructor before its
+ * replacement exists would flag every current caller with no fix available. Until
+ * then it stays the default, and the server reports each in-process boot as
+ * `provider_engine_mode` with `deprecated: true`.
+ */
 export declare function createInProcessProviderEngine(): ProviderEngine;

package/dist/engine.js

@@ -4,6 +4,16 @@ import { APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__AP
 import { OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_HEADERS, OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME, } from "./runtime/otlp.js";
 /** Versioned envelope protocol used by out-of-process engine transports. */
 export const PROVIDER_ENGINE_PROTOCOL_VERSION = "provider-engine.v1";
+/**
+ * Environment variable that selects how a provider process attaches its capability
+ * bindings. Engine-owned by prefix (`APIFUSE__ENGINE__*`): never declarable as a
+ * provider secret and never projected into `ctx.env`.
+ *
+ * Values are trimmed and case-folded; absent or blank means "unset". An
+ * unrecognized value is reported on the `provider_engine_mode` boot event and
+ * ignored — a deployment-authored typo must never turn into CrashLoopBackOff.
+ */
+export const PROVIDER_ENGINE_MODE_ENV = "APIFUSE__ENGINE__MODE";
 /** Credential names owned by the engine and forbidden in provider declarations. */
 export const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES = [
     "APIFUSE__PROXY__SMARTPROXY_APP_KEY",
@@ -184,7 +194,16 @@ function attachInProcess(input) {
         },
     });
 }
-/** Local engine attachment; deployed bridges implement the same interface with RPC clients. */
+/**
+ * Local engine attachment; deployed bridges implement the same interface with RPC clients.
+ *
+ * ADR-0011 makes the authenticated remote engine the only attachment, so this one
+ * is scheduled for removal — but not deprecated yet: the remote client ships in a
+ * later release, and deprecating the only working constructor before its
+ * replacement exists would flag every current caller with no fix available. Until
+ * then it stays the default, and the server reports each in-process boot as
+ * `provider_engine_mode` with `deprecated: true`.
+ */
 export function createInProcessProviderEngine() {
-    return { attach: attachInProcess };
+    return { kind: "in-process", attach: attachInProcess };
 }

package/dist/error-resolution.d.ts

@@ -2,3 +2,4 @@ import type { ProviderErrorStatus } from "./types.js";
 export declare const SDK_OWNED_PROVIDER_ERROR_CODES: Set<string>;
 export declare const SDK_RUNTIME_OWNED_ERROR_CODES: Set<string>;
 export declare const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, ProviderErrorStatus>;
+export declare const SDK_CANONICAL_ERROR_CODE_RETRYABILITY: ReadonlyMap<string, boolean>;

package/dist/error-resolution.js

@@ -18,6 +18,14 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
     "refresh_not_supported",
     "RUNTIME_UNSUPPORTED",
     "PROVIDER_STATE_UNSUPPORTED",
+    // Engine attachment (ADR-0011). Registered here so an engine failure is served
+    // as a known SDK code instead of raising a false
+    // `unregistered_provider_error_code` signal on a 500.
+    "PROVIDER_ENGINE_AUTHENTICATION_FAILED",
+    "PROVIDER_ENGINE_PROTOCOL_VERSION_MISMATCH",
+    "PROVIDER_ENGINE_UNAVAILABLE",
+    "PROVIDER_ENGINE_MODE_UNSUPPORTED",
+    "PROVIDER_EGRESS_DENIED",
     "HANDLE_INVALID",
     "HANDLE_NOT_FOUND",
     "HANDLE_EXPIRED",
@@ -57,6 +65,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
     "http_redirect_missing_location",
     "http_redirect_loop",
     "transport_invalid_url",
+    "http_header_factory_failed",
     "EGRESS_LEASE_INVALID",
     "EGRESS_LEASE_BINDING_INVALID",
     "EGRESS_LEASE_KEY_MISSING",
@@ -84,6 +93,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
     "STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
     "STATEFUL_FORWARDING_REQUEST_FAILED",
     "STATEFUL_FORWARDING_CONTEXT_MISSING",
+    "STATEFUL_FORWARDING_CONTEXT_INVALID",
     "STATEFUL_FORWARDING_BAD_RESPONSE",
     "STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
     "STATEFUL_FILE_FORWARDING_UNSUPPORTED",
@@ -144,9 +154,53 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES = new Map([
     ["HANDLE_BUSY", 409],
     ["UPSTREAM_ERROR", 502],
     ["BLOCKED", 502],
+    // Fleet-consensus provider codes. These are thrown by provider code, not
+    // by the SDK, so they are registered here (status mapping) and not in
+    // SDK_RUNTIME_OWNED_ERROR_CODES: an operation-declared status still wins,
+    // exactly as it does for UPSTREAM_ERROR and BLOCKED above. Registering
+    // them stops the fleet from re-declaring the same three rows on every
+    // operation, and stops an undeclared throw from being served as 500.
+    //
+    // A platform-managed upstream service key the upstream refuses. With
+    // `auth.mode: "platform-managed"` the caller holds no credential, so 401
+    // ("re-authenticate") tells the caller to do something it cannot do, and
+    // 502 ("upstream is sick") promises a recovery that will never come. It is
+    // a deployment/config defect — the same class as MISSING_SECRET above,
+    // which is already an explicit 400 for that reason.
+    ["UPSTREAM_AUTH_ERROR", 400],
+    // The upstream changed its response shape and the provider cannot
+    // normalize it. 502 because the fault is upstream of us, non-retryable
+    // because a retry returns the same broken payload.
+    ["UPSTREAM_SCHEMA_ERROR", 502],
+    // Caller-side bad input rejected by the provider. The minority spellings
+    // (INVALID_INPUT / VALIDATION_ERROR / BAD_REQUEST) are deliberately not
+    // registered: they migrate to this spelling on the contract track, and
+    // registering them here would freeze the divergence.
+    ["INVALID_REQUEST", 400],
     ["OCR_UNAVAILABLE", 503],
     ["UNSUPPORTED_OCR_BACKEND", 503],
     ["STT_UNAVAILABLE", 503],
     ["UNSUPPORTED_STT_BACKEND", 503],
     ["STATEFUL_FORWARDING_REPLAY_CACHE_FULL", 503],
+    // The engine is reachable-in-principle but not now: retryable, so the
+    // caller may retry once the engine recovers. Authentication, protocol
+    // mismatch, an unsupported mode and denied egress stay unmapped (500) and
+    // non-retryable: they are deployment or provider faults that no caller
+    // retry can clear, and a retryable 5xx there would turn one bad rollout
+    // into gateway-driven load.
+    ["PROVIDER_ENGINE_UNAVAILABLE", 503],
+]);
+// Canonical retryability for the fleet-consensus codes registered above.
+//
+// Runtime retryability still resolves as `instance option ?? declared ??
+// false`, so this map changes no served response: an undeclared throw already
+// defaults to false, which is what every entry here says. It exists so the
+// authoring lint can tell a provider that its declared `retryable` contradicts
+// the registered meaning of the code, instead of the fleet quietly shipping two
+// answers for the same code. Only codes whose retryability was fixed as part of
+// registration belong here — do not backfill opinions the SDK never made.
+export const SDK_CANONICAL_ERROR_CODE_RETRYABILITY = new Map([
+    ["UPSTREAM_AUTH_ERROR", false],
+    ["UPSTREAM_SCHEMA_ERROR", false],
+    ["INVALID_REQUEST", false],
 ]);

package/dist/errors.d.ts

@@ -1,5 +1,6 @@
+import type { ProviderErrorMessageParams } from "./i18n/error-messages.js";
 import type { ProviderErrorCategory } from "./observability.js";
-import type { HttpRedirectFailureReason } from "./types.js";
+import type { HttpRedirectFailureReason, ProviderLocaleKeyInput } from "./types.js";
 export type ProviderErrorOptions = {
     fix?: string;
     code?: string;
@@ -9,6 +10,25 @@ export type ProviderErrorOptions = {
     retryable?: boolean;
     /** Provider-authored, bounded metadata safe for operational logs and error headers. */
     observability?: ProviderErrorObservability;
+    /**
+     * Locale catalog key for the client-facing `message`, e.g.
+     * `"errors.upstreamSchema.message"`. Resolved at serve time against the
+     * provider's `locales/{en,ko,ja}.json` with the caller's `Accept-Language`,
+     * falling back to `en` and then to the positional `message`.
+     *
+     * The positional `message` stays English: it is what `error.message`, cause
+     * frames, logs and OTLP attributes carry. Only the response envelope is
+     * localized.
+     */
+    messageKey?: ProviderLocaleKeyInput;
+    /** Locale catalog key for the client-facing `fix`. Same resolution as {@link ProviderErrorOptions.messageKey}. */
+    fixKey?: ProviderLocaleKeyInput;
+    /**
+     * Values substituted into `{name}` placeholders of the resolved text.
+     * Strings and finite numbers only; string values are scrubbed and length
+     * capped before substitution because upstream text routinely lands here.
+     */
+    params?: ProviderErrorMessageParams;
 };
 /**
  * Provider-authored error diagnostics whose runtime values are validated before emission.
@@ -33,6 +53,24 @@ export declare class ProviderError extends Error {
 export declare class SDKError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);
 }
+/** Raised when the remote provider engine speaks an incompatible protocol version. */
+export declare class ProviderEngineProtocolVersionError extends SDKError {
+    readonly receivedVersion: unknown;
+    readonly expectedVersion: string;
+    constructor(receivedVersion: unknown, expectedVersion: string);
+}
+/** Raised when the remote provider engine rejects a workspace API key. */
+export declare class ProviderEngineAuthenticationError extends SDKError {
+    constructor(message?: string, options?: ProviderErrorOptions);
+}
+/** Raised when the remote engine cannot be reached. There is no local fallback. */
+export declare class ProviderEngineUnavailableError extends SDKError {
+    constructor(message?: string, cause?: Error);
+}
+/** Raised when the engine refuses egress outside the workspace's pinned allowlist. */
+export declare class ProviderEgressDeniedError extends ProviderError {
+    constructor(message: string, details?: unknown);
+}
 /** Raised when persisted stealth cookies use a store version this SDK cannot read. */
 export declare class StealthCookieStoreVersionError extends SDKError {
     readonly version: unknown;

package/dist/errors.js

@@ -59,6 +59,56 @@ export class SDKError extends ProviderError {
         this.name = "SDKError";
     }
 }
+/** Raised when the remote provider engine speaks an incompatible protocol version. */
+export class ProviderEngineProtocolVersionError extends SDKError {
+    receivedVersion;
+    expectedVersion;
+    constructor(receivedVersion, expectedVersion) {
+        super(`Provider engine protocol version mismatch: expected ${expectedVersion}, received ${String(receivedVersion)}`, {
+            code: "PROVIDER_ENGINE_PROTOCOL_VERSION_MISMATCH",
+            details: { receivedVersion, expectedVersion },
+            fix: "Update @apifuse/provider-sdk or use a compatible APIFuse provider engine.",
+        });
+        this.receivedVersion = receivedVersion;
+        this.expectedVersion = expectedVersion;
+        this.name = "ProviderEngineProtocolVersionError";
+    }
+}
+/** Raised when the remote provider engine rejects a workspace API key. */
+export class ProviderEngineAuthenticationError extends SDKError {
+    constructor(message = "Provider engine authentication failed", options) {
+        super(message, {
+            code: "PROVIDER_ENGINE_AUTHENTICATION_FAILED",
+            fix: "Set APIFUSE__ENGINE__API_KEY to the workspace API key from your APIFuse bounty dashboard.",
+            ...options,
+        });
+        this.name = "ProviderEngineAuthenticationError";
+    }
+}
+/** Raised when the remote engine cannot be reached. There is no local fallback. */
+export class ProviderEngineUnavailableError extends SDKError {
+    constructor(message = "The remote APIFuse provider engine is unavailable", cause) {
+        super(message, {
+            code: "PROVIDER_ENGINE_UNAVAILABLE",
+            retryable: true,
+            fix: "Check network access and the provider engine endpoint, then retry.",
+            ...(cause ? { cause } : {}),
+        });
+        this.name = "ProviderEngineUnavailableError";
+    }
+}
+/** Raised when the engine refuses egress outside the workspace's pinned allowlist. */
+export class ProviderEgressDeniedError extends ProviderError {
+    constructor(message, details) {
+        super(message, {
+            code: "PROVIDER_EGRESS_DENIED",
+            retryable: false,
+            details,
+            fix: "Use a host in the provider's pinned allowedHosts declaration, or request a trusted pin update.",
+        });
+        this.name = "ProviderEgressDeniedError";
+    }
+}
 /** Raised when persisted stealth cookies use a store version this SDK cannot read. */
 export class StealthCookieStoreVersionError extends SDKError {
     version;

package/dist/handle-meta.d.ts

@@ -9,12 +9,18 @@
 export declare const APIFUSE_HANDLE_META_KEY: "x-apifuse-handle";
 export type HandleKindType = "cursor" | "draft";
 export type HandleAccess = "bound" | "public";
+/**
+ * Operation key(s) that issue a handle. A single string is the common case; a
+ * list names every operation whose output carries the field (for example
+ * `search-address` and `reverse-geocode` both issuing `location_token`).
+ */
+export type HandleIssuedBy = string | readonly string[];
 /** Value stored under {@link APIFUSE_HANDLE_META_KEY} on a handle field. */
 export interface HandleFieldMeta {
     readonly kind: string;
     readonly type: HandleKindType;
     readonly fieldName: string;
-    readonly issuedBy?: string;
+    readonly issuedBy?: HandleIssuedBy;
 }
 /**
  * Structural view of a handle kind as seen by the provider declaration
@@ -26,10 +32,20 @@ export interface HandleKindDeclaration {
     readonly type: HandleKindType;
     readonly fieldName: string;
     readonly access: HandleAccess;
-    readonly issuedBy?: string;
+    readonly issuedBy?: HandleIssuedBy;
 }
 /** Kind names are lowercase letters only so they never fuse with the word body. */
 export declare const HANDLE_KIND_NAME_PATTERN: RegExp;
+/** True for a single operation key or a non-empty list of operation keys. */
+export declare function isHandleIssuedBy(value: unknown): value is HandleIssuedBy;
+/** Normalizes `issuedBy` to a list of operation keys (empty when undefined). */
+export declare function handleIssuerList(issuedBy: HandleIssuedBy | undefined): readonly string[];
+/**
+ * Renders the issuing operation(s) as inline code for error and description
+ * text: `` `a` ``, `` `a` or `b` ``, `` `a`, `b`, or `c` ``. Undefined when no
+ * issuer is declared.
+ */
+export declare function formatHandleIssuers(issuedBy: HandleIssuedBy | undefined): string | undefined;
 export declare function isHandleFieldMeta(value: unknown): value is HandleFieldMeta;
 /**
  * The SDK-owned description `kind.field()` emits. Lint exempts a handle field

package/dist/handle-meta.js

@@ -9,6 +9,33 @@
 export const APIFUSE_HANDLE_META_KEY = "x-apifuse-handle";
 /** Kind names are lowercase letters only so they never fuse with the word body. */
 export const HANDLE_KIND_NAME_PATTERN = /^[a-z]{2,12}$/;
+/** True for a single operation key or a non-empty list of operation keys. */
+export function isHandleIssuedBy(value) {
+    if (typeof value === "string")
+        return true;
+    return (Array.isArray(value) && value.length > 0 && value.every((entry) => typeof entry === "string"));
+}
+/** Normalizes `issuedBy` to a list of operation keys (empty when undefined). */
+export function handleIssuerList(issuedBy) {
+    if (issuedBy === undefined)
+        return [];
+    return typeof issuedBy === "string" ? [issuedBy] : issuedBy;
+}
+/**
+ * Renders the issuing operation(s) as inline code for error and description
+ * text: `` `a` ``, `` `a` or `b` ``, `` `a`, `b`, or `c` ``. Undefined when no
+ * issuer is declared.
+ */
+export function formatHandleIssuers(issuedBy) {
+    const issuers = handleIssuerList(issuedBy).map((operation) => `\`${operation}\``);
+    if (issuers.length === 0)
+        return undefined;
+    if (issuers.length === 1)
+        return issuers[0];
+    if (issuers.length === 2)
+        return `${issuers[0]} or ${issuers[1]}`;
+    return `${issuers.slice(0, -1).join(", ")}, or ${issuers[issuers.length - 1]}`;
+}
 export function isHandleFieldMeta(value) {
     if (typeof value !== "object" || value === null)
         return false;
@@ -16,7 +43,7 @@ export function isHandleFieldMeta(value) {
     return (typeof record.kind === "string" &&
         (record.type === "cursor" || record.type === "draft") &&
         typeof record.fieldName === "string" &&
-        (record.issuedBy === undefined || typeof record.issuedBy === "string"));
+        (record.issuedBy === undefined || isHandleIssuedBy(record.issuedBy)));
 }
 /**
  * The SDK-owned description `kind.field()` emits. Lint exempts a handle field
@@ -24,6 +51,7 @@ export function isHandleFieldMeta(value) {
  * provider override re-enters the localization rules.
  */
 export function handleFieldDescription(meta) {
-    const origin = meta.issuedBy ? ` issued by \`${meta.issuedBy}\`` : "";
+    const issuers = formatHandleIssuers(meta.issuedBy);
+    const origin = issuers ? ` issued by ${issuers}` : "";
     return `Opaque handle${origin}. Copy it exactly as returned; do not edit or shorten it.`;
 }

package/dist/handle.d.ts

@@ -9,9 +9,9 @@
  */
 import { type ZodString, type ZodType, z } from "zod";
 import { ProviderError, type ProviderErrorOptions } from "./errors.js";
-import { type HandleAccess, type HandleFieldMeta, type HandleKindDeclaration, type HandleKindType } from "./handle-meta.js";
+import { type HandleAccess, type HandleFieldMeta, type HandleIssuedBy, type HandleKindDeclaration, type HandleKindType } from "./handle-meta.js";
 import type { ProviderStateDurationString } from "./types.js";
-export type { HandleAccess, HandleFieldMeta, HandleKindDeclaration, HandleKindType };
+export type { HandleAccess, HandleFieldMeta, HandleIssuedBy, HandleKindDeclaration, HandleKindType, };
 export type HandleStrength = "standard" | "high";
 /** Words issued per handle: 2 for bound kinds, 4 for public, 5 for high-strength public. */
 export type HandleWordCount = 2 | 4 | 5;
@@ -41,7 +41,10 @@ export interface CursorKind<TSchema extends ZodType = ZodType> extends HandleKin
 }
 export interface DraftKind<TSchema extends ZodType = ZodType, TResultSchema extends ZodType | undefined = ZodType | undefined> extends HandleKindBase<TSchema> {
     readonly type: "draft";
-    readonly access: "bound";
+    /** `"bound"` (default): connection-scoped, 2 words. `"public"`: provider-scoped, 4-5 words. */
+    readonly access: HandleAccess;
+    /** Public only; `"high"` forces 5 words. Always `"standard"` for bound drafts. */
+    readonly strength: HandleStrength;
     readonly ttl: {
         readonly idle: ProviderStateDurationString;
         readonly max: ProviderStateDurationString;
@@ -52,7 +55,6 @@ export interface DraftKind<TSchema extends ZodType = ZodType, TResultSchema exte
     readonly resultTtlMs: number;
     /** Optional schema describing the commit result; type-level only at runtime. */
     readonly result: TResultSchema | undefined;
-    readonly wordCount: 2;
 }
 export type HandleKind = CursorKind<any> | DraftKind<any, any>;
 /** Stored record data type (schema output); what `read`, `update`, and `commit` callbacks receive. */
@@ -79,6 +81,12 @@ export interface HandleCommitResult<K extends HandleKind> {
 export interface HandleContext {
     /** Validates `data` with `kind.schema`, stores it, and returns the canonical handle. */
     create<K extends HandleKind>(kind: K, data: InputOf<K>): Promise<string>;
+    /**
+     * Same as `create` but returns the full record (`handle`, `status`, `data`,
+     * `createdAt`, `expiresAt`) so a provider can expose `expires_at` without
+     * recomputing ttl math. `create` is the string-returning shortcut.
+     */
+    createRecord<K extends HandleKind>(kind: K, data: InputOf<K>): Promise<HandleRecord<K>>;
     /** Tolerantly parses `handle`, loads the record; drafts get their idle TTL touched. */
     read<K extends HandleKind>(kind: K, handle: string): Promise<HandleRecord<K>>;
     /** CAS update of an active draft (3 retries) with sliding TTL. */
@@ -123,7 +131,7 @@ export declare function isHandleError(value: unknown): value is HandleError;
  */
 export declare function handleRecoverySentence(kind: {
     readonly fieldName: string;
-    readonly issuedBy?: string;
+    readonly issuedBy?: HandleIssuedBy;
 }): string;
 /** Parses a `ProviderStateDurationString` to milliseconds; throws on invalid or non-positive input. */
 export declare function parseHandleDurationMs(value: ProviderStateDurationString, label: string): number;
@@ -142,8 +150,8 @@ export interface DefineCursorOptions<TSchema extends ZodType> {
     readonly maxValueBytes?: number;
     /** Public only; `"high"` forces 5 words. Auto-high when ttl > 1h. */
     readonly strength?: HandleStrength;
-    /** Operation key that issues this handle; used in error text and lint. */
-    readonly issuedBy?: string;
+    /** Operation key(s) that issue this handle; used in error text and lint. */
+    readonly issuedBy?: HandleIssuedBy;
 }
 export interface DefineDraftOptions<TSchema extends ZodType, TResultSchema extends ZodType | undefined> {
     readonly name: string;
@@ -157,15 +165,28 @@ export interface DefineDraftOptions<TSchema extends ZodType, TResultSchema exten
     };
     /** How long a committed record stays for replay. Default "24h". */
     readonly resultTtl?: ProviderStateDurationString;
-    /** Default 200 per connection. */
+    /**
+     * `"bound"` (default): connection-scoped, 2 words. `"public"`: provider-scoped
+     * draft for connectionless providers (`auth: none`), 4-5 words, `maxEntries`
+     * required; every lookup failure collapses to `HANDLE_INVALID`.
+     */
+    readonly access?: HandleAccess;
+    /** Required when public. Bound default 200 per connection. */
     readonly maxEntries?: number;
     /** Default 64,000. */
     readonly maxValueBytes?: number;
-    readonly issuedBy?: string;
+    /** Public only; `"high"` forces 5 words. Auto-high when ttl.max > 1h. */
+    readonly strength?: HandleStrength;
+    /** Operation key(s) that issue this handle; used in error text and lint. */
+    readonly issuedBy?: HandleIssuedBy;
 }
 /** Defines an immutable cursor kind (pagination, offered option lists). */
 export declare function defineCursor<TSchema extends ZodType>(options: DefineCursorOptions<TSchema>): CursorKind<TSchema>;
-/** Defines a mutable, always-bound draft kind (multi-turn forms with one-shot commit). */
+/**
+ * Defines a mutable draft kind (multi-turn forms with one-shot commit). Bound
+ * by default; `access: "public"` opts a connectionless provider into a
+ * provider-scoped draft under the public guessing analysis (ADR-0012 D3).
+ */
 export declare function defineDraft<TSchema extends ZodType, TResultSchema extends ZodType | undefined = undefined>(options: DefineDraftOptions<TSchema, TResultSchema>): DraftKind<TSchema, TResultSchema>;
 export declare function isDraftKind(kind: HandleKind): kind is DraftKind<any, any>;
 export declare function isCursorKind(kind: HandleKind): kind is CursorKind<any>;
@@ -174,8 +195,8 @@ export interface PickOptions<T> {
     readonly field: string;
     /** Item property compared against `value`. Default = `field`. */
     readonly by?: keyof T & string;
-    /** Operation that listed the items; used in the error message when known. */
-    readonly issuedBy?: string;
+    /** Operation(s) that listed the items; used in the error message when known. */
+    readonly issuedBy?: HandleIssuedBy;
 }
 /**
  * Chooses one offered item by a plain value the LLM copied from the offer.