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

package/dist/lint.js

@@ -1,5 +1,6 @@
 import { createRequire } from "node:module";
 import { SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "./error-resolution.js";
+import { APIFUSE_HANDLE_META_KEY, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
 import { lintPublicSchemaFieldNames } from "./public-schema-field-lint.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY } from "./schema.js";
 const requireModule = createRequire(import.meta.url);
@@ -56,12 +57,7 @@ const AUTH_LIFECYCLE_SEGMENT_WORDS = new Set([
     "auth",
 ]);
 // Ambiguous as a prefix, unambiguous when they are the whole operation id.
-const AUTH_LIFECYCLE_WHOLE_ID_WORDS = new Set([
-    "authorize",
-    "revoke",
-    "unlink",
-    "disconnect",
-]);
+const AUTH_LIFECYCLE_WHOLE_ID_WORDS = new Set(["authorize", "revoke", "unlink", "disconnect"]);
 // A verb stem followed by a direction word across two segments: `sign-out`,
 // `user_sign_up_flow`, and the spelled-out `log-in` / `shop-log-out` forms
 // (their fused equivalents `login`/`logout` live in the segment set above).
@@ -304,15 +300,18 @@ function getObjectShape(schema) {
 }
 function getChildSchemas(schema) {
     const seen = new Map();
+    const origins = new Map();
     const def = getSchemaDef(schema);
-    const add = (key, value) => {
+    const add = (key, value, origin = "structural") => {
         if (!isSchema(value)) {
             return;
         }
-        seen.set(`${key}:${seen.size}`, value);
+        const id = `${key}:${seen.size}`;
+        seen.set(id, value);
+        origins.set(id, origin);
     };
     for (const [key, value] of Object.entries(getObjectShape(schema))) {
-        add(key, value);
+        add(key, value, "shape");
     }
     add("element", schema.element);
     add("innerType", schema.innerType);
@@ -352,6 +351,9 @@ function getChildSchemas(schema) {
         "schema",
         "innerType",
         "type",
+        // zod v4 intersections keep their branches on the definition.
+        "left",
+        "right",
         "valueType",
         "keyType",
         "item",
@@ -375,6 +377,7 @@ function getChildSchemas(schema) {
     return Array.from(seen.entries()).map(([entryKey, child]) => ({
         key: entryKey.split(":")[0] ?? entryKey,
         schema: child,
+        origin: origins.get(entryKey) ?? "structural",
     }));
 }
 function uniqueFields(fields) {
@@ -441,6 +444,78 @@ function isDeclaredSensitiveField(key, schema) {
     return (declaration === true ||
         (declaration === false && PUBLIC_DECLARABLE_FIELD_NAMES.has(normalizeFieldName(key))));
 }
+// Child keys produced by getChildSchemas() that wrap a schema without adding a
+// property path segment (optional/nullable/default/pipe/effects/etc.).
+const SCHEMA_WRAPPER_NODE_KEYS = [
+    "unwrap",
+    "innerType",
+    "sourceType",
+    "schema",
+    "type",
+    "in",
+    "out",
+    "option",
+    "pipe",
+    "payload",
+    "item",
+    "rest",
+    "catchall",
+    "keyType",
+    "valueType",
+    // zod v4 intersection branches: transparent, the enclosing property key applies.
+    "left",
+    "right",
+];
+function isSchemaWrapperNodeKey(key) {
+    return SCHEMA_WRAPPER_NODE_KEYS.includes(key) || key.startsWith("pipe.");
+}
+function getOwnHandleFieldMeta(schema) {
+    const value = Reflect.get(getSchemaMetadata(schema), APIFUSE_HANDLE_META_KEY);
+    return isHandleFieldMeta(value) ? value : undefined;
+}
+/**
+ * Handle meta placed by `kind.field()` lives on the string schema itself; zod
+ * wrappers (`.optional()`, `.nullable()`, `.default()`, pipes) do not inherit
+ * registry metadata, so look through wrapper nodes until a non-wrapper is hit.
+ */
+function getHandleFieldMeta(schema, seen = new Set()) {
+    if (!isSchema(schema) || seen.has(schema))
+        return undefined;
+    seen.add(schema);
+    const own = getOwnHandleFieldMeta(schema);
+    if (own)
+        return own;
+    for (const child of getChildSchemas(schema)) {
+        if (child.origin === "shape" || !isSchemaWrapperNodeKey(child.key))
+            continue;
+        const found = getHandleFieldMeta(child.schema, seen);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * True when `schema` is a handle field (directly or through zod wrappers) whose
+ * description is still the SDK-generated wording and no wrapper adds its own
+ * description.
+ */
+function isSdkOwnedHandleField(schema, seen = new Set()) {
+    if (!isSchema(schema) || seen.has(schema))
+        return false;
+    seen.add(schema);
+    const own = getOwnHandleFieldMeta(schema);
+    if (own)
+        return schema.description === handleFieldDescription(own);
+    if (schema.description)
+        return false;
+    for (const child of getChildSchemas(schema)) {
+        if (child.origin === "shape" || !isSchemaWrapperNodeKey(child.key))
+            continue;
+        if (isSdkOwnedHandleField(child.schema, seen))
+            return true;
+    }
+    return false;
+}
 function collectUnmarkedSensitiveFields(schema, basePath, seen = new Set()) {
     if (!isSchema(schema) || seen.has(schema)) {
         return [];
@@ -457,23 +532,7 @@ function collectUnmarkedSensitiveFields(schema, basePath, seen = new Set()) {
     for (const child of getChildSchemas(schema)) {
         if (Object.hasOwn(getObjectShape(schema), child.key))
             continue;
-        const isWrapperNode = [
-            "unwrap",
-            "innerType",
-            "sourceType",
-            "schema",
-            "type",
-            "in",
-            "out",
-            "option",
-            "pipe",
-            "payload",
-            "item",
-            "rest",
-            "catchall",
-            "keyType",
-            "valueType",
-        ].includes(child.key);
+        const isWrapperNode = SCHEMA_WRAPPER_NODE_KEYS.includes(child.key);
         const childPath = child.key === "element" || child.key.startsWith("element.")
             ? `${basePath}[]`
             : isWrapperNode || child.key.startsWith("pipe.")
@@ -493,6 +552,14 @@ function collectSchemaDescriptionKeyDiagnostics(schema, basePath, seen = new Set
     const diagnostics = [];
     const currentPath = basePath || "schema";
     const hasDescriptionKey = getSchemaDescriptionKey(schema) !== undefined;
+    // Handle fields (`kind.field()`, ADR-0012) carry SDK-owned wording via
+    // .describe() plus x-apifuse-handle meta; they count as described and are
+    // leaves, so neither this node nor its wrapper chain needs a describeKey.
+    // A provider override of that wording (`.describe("…")` on the field or on
+    // a wrapper) is provider prose again and stays subject to the rules below.
+    if (isSdkOwnedHandleField(schema)) {
+        return diagnostics;
+    }
     if (schema.description && !hasDescriptionKey) {
         diagnostics.push({
             rule: "schema-description-raw-prose",
@@ -512,23 +579,7 @@ function collectSchemaDescriptionKeyDiagnostics(schema, basePath, seen = new Set
         });
     }
     for (const child of getChildSchemas(schema)) {
-        const isWrapperNode = [
-            "unwrap",
-            "innerType",
-            "sourceType",
-            "schema",
-            "type",
-            "in",
-            "out",
-            "option",
-            "pipe",
-            "payload",
-            "item",
-            "rest",
-            "catchall",
-            "keyType",
-            "valueType",
-        ].includes(child.key);
+        const isWrapperNode = SCHEMA_WRAPPER_NODE_KEYS.includes(child.key);
         const isStructuralNode = isWrapperNode ||
             child.key.startsWith("pipe.") ||
             child.key === "element" ||
@@ -992,7 +1043,8 @@ function collectLiteralErrorCodeValues(args) {
                             after++;
                         }
                         const nextChar = after < args.length ? (args[after] ?? "") : "";
-                        if (!value.includes("\\") && (nextChar === "," || nextChar === "}" || nextChar === "")) {
+                        if (!value.includes("\\") &&
+                            (nextChar === "," || nextChar === "}" || nextChar === "")) {
                             codes.push(value);
                         }
                         index = end;
@@ -1082,6 +1134,259 @@ function lintUndeclaredThrownErrorCodes(provider) {
     }
     return diagnostics;
 }
+function collectHandleFields(schema, basePath, key = undefined, seen = new Set()) {
+    if (!isSchema(schema))
+        return [];
+    // Record before the cycle guard so one `kind.field()` instance reused under
+    // two property keys is still reported at both positions.
+    const own = getOwnHandleFieldMeta(schema);
+    if (own && key !== undefined) {
+        return [{ path: basePath, key, meta: own }];
+    }
+    // Path-local cycle guard: the same wrapped schema instance may legitimately
+    // appear under several property keys (`Kind.field().optional()` reused), and
+    // each position must be checked. Only true ancestor cycles are cut.
+    if (seen.has(schema))
+        return [];
+    seen.add(schema);
+    try {
+        return collectHandleFieldChildren(schema, basePath, key, seen);
+    }
+    finally {
+        seen.delete(schema);
+    }
+}
+function collectHandleFieldChildren(schema, basePath, key, seen) {
+    const out = [];
+    // zod exposes the same inner schema under several structural edges
+    // (`unwrap`/`innerType`, `element`/`def.element`); traverse each structural
+    // child object once. Shape children are always traversed: the same instance
+    // under two property keys is two fields.
+    const structuralSeen = new Set();
+    for (const child of getChildSchemas(schema)) {
+        if (child.origin !== "shape") {
+            if (structuralSeen.has(child.schema))
+                continue;
+            structuralSeen.add(child.schema);
+        }
+        if (child.origin === "shape") {
+            // Provider-chosen property key: always a real field, even when it is
+            // spelled like a structural edge (`item`, `type`, `schema`, ...).
+            out.push(...collectHandleFields(child.schema, `${basePath}.${child.key}`, child.key, seen));
+        }
+        else if (isSchemaWrapperNodeKey(child.key)) {
+            out.push(...collectHandleFields(child.schema, basePath, key, seen));
+        }
+        else if (child.key === "element" || child.key.startsWith("element.")) {
+            out.push(...collectHandleFields(child.schema, `${basePath}[]`, key, seen));
+        }
+        else if (/^\d+$/.test(child.key)) {
+            out.push(...collectHandleFields(child.schema, `${basePath}[${child.key}]`, key, seen));
+        }
+        else {
+            out.push(...collectHandleFields(child.schema, `${basePath}.${child.key}`, child.key, seen));
+        }
+    }
+    return out;
+}
+/**
+ * Reads `provider.handle` structurally. The declaration type is owned by
+ * define.ts/types.ts; lint only needs the HandleKindDeclaration view, so
+ * malformed entries are skipped rather than reported.
+ */
+function readHandleKindDeclarations(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => {
+        if (typeof entry !== "object" || entry === null)
+            return false;
+        const record = entry;
+        return (typeof record.name === "string" &&
+            (record.type === "cursor" || record.type === "draft") &&
+            typeof record.fieldName === "string" &&
+            (record.issuedBy === undefined || typeof record.issuedBy === "string"));
+    });
+}
+/**
+ * ADR-0012 handle rules: every `x-apifuse-handle` schema field must belong to
+ * a declared kind under its declared property key; every declared kind must be
+ * both issued (some output) and accepted (some input); `issuedBy` must name an
+ * operation whose output carries the field; and `ctx.handle` needs `state`.
+ */
+function lintHandleDeclarations(provider) {
+    const diagnostics = [];
+    const providerLabel = provider.id ? `Provider "${provider.id}"` : "Provider";
+    const kinds = readHandleKindDeclarations(provider.handle);
+    const kindByName = new Map(kinds.map((kind) => [kind.name, kind]));
+    const operations = provider.operations ?? {};
+    if (kinds.length > 0 && !provider.state) {
+        diagnostics.push({
+            rule: "handle-requires-state",
+            level: "warn",
+            field: "handle",
+            message: `${providerLabel} declares handle kinds but not the state capability; ctx.handle stores records through ctx.state, so declare state: true.`,
+        });
+    }
+    const kindsInInputs = new Set();
+    const kindsInOutputs = new Set();
+    const outputKindsByOperation = new Map();
+    for (const [operationKey, operation] of Object.entries(operations)) {
+        const positions = [
+            { side: "input", fields: collectHandleFields(operation.input, "input") },
+            { side: "output", fields: collectHandleFields(operation.output, "output") },
+        ];
+        for (const { side, fields } of positions) {
+            for (const occurrence of fields) {
+                const field = `operations.${operationKey}.${occurrence.path}`;
+                const { kind, fieldName } = occurrence.meta;
+                if (!kindByName.has(kind)) {
+                    diagnostics.push({
+                        rule: "handle-kind-undeclared",
+                        level: "error",
+                        field,
+                        message: `${providerLabel} operation "${operationKey}" ${side} field "${occurrence.path}" is a handle of kind "${kind}", which is not declared in provider.handle. Add the kind to handle: [...] or remove the field.`,
+                    });
+                }
+                if (occurrence.key !== fieldName) {
+                    diagnostics.push({
+                        rule: "handle-field-name",
+                        level: "error",
+                        field,
+                        message: `${providerLabel} operation "${operationKey}" ${side} declares handle kind "${kind}" under property "${occurrence.key}" but the kind's fieldName is "${fieldName}". Use the same key in every schema so the LLM sees one name.`,
+                    });
+                }
+                if (side === "input") {
+                    kindsInInputs.add(kind);
+                }
+                else {
+                    kindsInOutputs.add(kind);
+                    let outputKinds = outputKindsByOperation.get(operationKey);
+                    if (!outputKinds) {
+                        outputKinds = new Set();
+                        outputKindsByOperation.set(operationKey, outputKinds);
+                    }
+                    outputKinds.add(kind);
+                }
+            }
+        }
+    }
+    for (const kind of kinds) {
+        const field = `handle.${kind.name}`;
+        const issued = kindsInOutputs.has(kind.name);
+        const accepted = kindsInInputs.has(kind.name);
+        if (!issued) {
+            diagnostics.push({
+                rule: "handle-field-parity",
+                level: "error",
+                field,
+                message: `${providerLabel} handle kind "${kind.name}" is never issued: no operation output contains its field "${kind.fieldName}". Add ${kind.name}.field() to the issuing operation's output.`,
+            });
+        }
+        if (!accepted) {
+            diagnostics.push({
+                rule: "handle-field-parity",
+                level: "error",
+                field,
+                message: `${providerLabel} handle kind "${kind.name}" is never accepted: no operation input contains its field "${kind.fieldName}". Add ${kind.name}.field() to the consuming operation's input.`,
+            });
+        }
+        if (kind.issuedBy === undefined)
+            continue;
+        if (!Object.hasOwn(operations, kind.issuedBy)) {
+            diagnostics.push({
+                rule: "handle-issued-by",
+                level: "error",
+                field,
+                message: `${providerLabel} handle kind "${kind.name}" declares issuedBy "${kind.issuedBy}", which is not an operation key.`,
+            });
+        }
+        else if (!outputKindsByOperation.get(kind.issuedBy)?.has(kind.name)) {
+            diagnostics.push({
+                rule: "handle-issued-by",
+                level: "error",
+                field,
+                message: `${providerLabel} handle kind "${kind.name}" declares issuedBy "${kind.issuedBy}", but that operation's output has no "${kind.fieldName}" handle field.`,
+            });
+        }
+    }
+    return diagnostics;
+}
+const LEGACY_CHOICE_USAGE_PATTERN = /\bctx\.choice\b|\b(?:createProviderChoiceToken|parseProviderChoiceToken|ProviderChoiceTokenError|createTestProviderChoiceContext)\b/;
+const LEGACY_CHOICE_USAGE_MESSAGE = "Choice tokens were replaced by handles (ADR-0012). See docs/migrations/handle.md.";
+/**
+ * The inline choice-token API was removed outright (no aliases). Any surviving
+ * reference in provider source would fail at runtime, so report it at check time.
+ */
+const LEGACY_CHOICE_IDENTIFIERS = new Set([
+    "createProviderChoiceToken",
+    "parseProviderChoiceToken",
+    "ProviderChoiceTokenError",
+    "createTestProviderChoiceContext",
+]);
+/**
+ * Finds the first legacy choice API reference in executable code. Uses the
+ * TypeScript AST when available so comments, string and template literal text
+ * never count (a migration note such as `// moved from ctx.choice` must not fail
+ * the provider) while code inside `${}` interpolations still does. Falls back
+ * to a raw-source regex when TypeScript is not installed.
+ */
+function findLegacyChoiceUsage(source) {
+    let ts;
+    try {
+        ts = getTypeScript();
+    }
+    catch {
+        return LEGACY_CHOICE_USAGE_PATTERN.exec(source)?.[0];
+    }
+    const file = ts.createSourceFile("provider.ts", source, ts.ScriptTarget.Latest, false, ts.ScriptKind.TSX);
+    let found;
+    const visit = (node) => {
+        if (found)
+            return;
+        if (ts.isIdentifier(node) && LEGACY_CHOICE_IDENTIFIERS.has(node.text)) {
+            found = node.text;
+            return;
+        }
+        if (ts.isPropertyAccessExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            node.expression.text === "ctx" &&
+            node.name.text === "choice") {
+            found = "ctx.choice";
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(file);
+    return found;
+}
+function lintLegacyChoiceUsage(provider) {
+    const sources = [];
+    if (provider.authFlowSource) {
+        sources.push({ field: "auth.flow", source: provider.authFlowSource });
+    }
+    for (const [filePath, source] of Object.entries(provider.providerSourceFiles ?? {})) {
+        sources.push({ field: `sourceFiles.${filePath}`, source });
+    }
+    for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
+        const source = getOperationSource(operation);
+        if (source) {
+            sources.push({ field: `operations.${operationKey}.handler`, source });
+        }
+    }
+    return sources.flatMap(({ field, source }) => {
+        const match = findLegacyChoiceUsage(source);
+        if (!match)
+            return [];
+        return [
+            {
+                rule: "legacy-choice-usage",
+                level: "error",
+                field,
+                message: `Legacy choice API "${match}" is no longer supported. ${LEGACY_CHOICE_USAGE_MESSAGE}`,
+            },
+        ];
+    });
+}
 export function lintOperation(op) {
     const diagnostics = [];
     const hasDescriptionKey = typeof op.descriptionKey === "string" && op.descriptionKey.length > 0;
@@ -1181,6 +1486,8 @@ export function lintProviderWithInformation(provider, options = {}) {
         ...lintSelfHostedBrowserPatterns(provider, options),
         ...lintBrowserVersionLiterals(provider),
         ...lintUndeclaredThrownErrorCodes(provider),
+        ...lintLegacyChoiceUsage(provider),
+        ...lintHandleDeclarations(provider),
     ];
     if (provider.operations) {
         const authMode = provider.auth?.mode;
@@ -1207,9 +1514,7 @@ export function lintProviderWithInformation(provider, options = {}) {
         // Every authenticated mode owns an auth.flow; `oauth2_proxied` was
         // previously exempt, which let auth-lifecycle operations ship on
         // proxied providers unchecked.
-        if (authMode === "credentials" ||
-            authMode === "oauth2" ||
-            authMode === "oauth2_proxied") {
+        if (authMode === "credentials" || authMode === "oauth2" || authMode === "oauth2_proxied") {
             for (const operationKey of Object.keys(provider.operations)) {
                 if (isAuthLifecycleOperationId(operationKey, authMode)) {
                     diagnostics.push({

package/dist/provider.d.ts

@@ -1,7 +1,6 @@
 export { AuthAbortError, credentialsAuthChallenge, createAuthFlowHelpers, defineCredentialsAuth, } from "./auth.js";
 export type { CredentialsAuthChallengeDefinition, CredentialsAuthChallengeRequest, CredentialsAuthCompleteResult, CredentialsAuthCredential, CredentialsAuthField, CredentialsAuthFields, CredentialsAuthFieldType, CredentialsAuthInput, CredentialsAuthLoginResult, DefineCredentialsAuthOptions, DefinedCredentialsAuth, } from "./auth.js";
 export { createFormCeremony } from "./ceremonies/index.js";
-export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, type ProviderChoiceTokenErrorReason, type ProviderChoiceTokenPayload, parseProviderChoiceToken, } from "./choice-token.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
 export type { OperationDefinitionFor, ProviderBuilder, ProviderContextOf, ProviderDeclaration, ProviderDefinitionFor, } from "./define.js";
 export type { JsonPrimitive, JsonValue } from "./contract-json.js";
@@ -11,9 +10,10 @@ export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, i
 export { createProviderEnvironment, createInProcessProviderEngine, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RUNTIME_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedResolverCredentialName, isEngineOwnedRuntimeEnvName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
 export type { ProviderCapabilityKey, ProviderEngine, ProviderEngineAttachmentInput, ProviderEngineBindingCandidates, ProviderEngineCapabilitySurface, ProviderEngineRequest, ProviderEngineResidentSurface, ProviderEngineSession, ProviderEngineTransport, } from "./engine.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
-export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
+export * from "./handle.js";
+export { type CreateHandleContextOptions, type CreateTestHandleContextOptions, createHandleContext, createTestHandleContext, type HandleNormalizationClass, type NormalizedHandle, normalizeHandle, } from "./runtime/handle.js";
 export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, publicField, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, untrustedContent, z, } from "./schema.js";
-export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceConsumeMode, ProviderChoiceConsumeResult, ProviderChoiceContext, ProviderChoiceExplicitParseResult, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeTarget, ProviderRuntimeState, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthChallengeClassification, } from "./types.js";
+export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, ProviderAccessVisibility, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeTarget, ProviderRuntimeState, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthChallengeClassification, } from "./types.js";
 export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export type { NativeGatewayProxy, NativeGatewayProxyResolutionInput, NativeGatewayProxySkipReason, NativeGatewayProxySynthesizer, NativeGatewayProxySynthesisResult, NativeGatewayProxySynthesisInput, NativeNetworkClientOptions, NativeNetworkErrorCode, VendorCredentialLookup, VendorCredentialResolver, } from "./runtime/native-network.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/provider.js

@@ -1,12 +1,12 @@
 export { AuthAbortError, credentialsAuthChallenge, createAuthFlowHelpers, defineCredentialsAuth, } from "./auth.js";
 export { createFormCeremony } from "./ceremonies/index.js";
-export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, parseProviderChoiceToken, } from "./choice-token.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
 export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
 export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
 export { createProviderEnvironment, createInProcessProviderEngine, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RUNTIME_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedResolverCredentialName, isEngineOwnedRuntimeEnvName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
-export { createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
+export * from "./handle.js";
+export { createHandleContext, createTestHandleContext, normalizeHandle, } from "./runtime/handle.js";
 export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, publicField, redactPayload, sensitive, untrustedContent, z, } from "./schema.js";
 export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/runtime/handle-wordlist.d.ts

@@ -0,0 +1,43 @@
+export declare const HANDLE_WORDLIST_SIZE = 1296;
+export declare const HANDLE_WORD_ENTROPY_BITS: number;
+/**
+ * Bound handles live under `state.forConnection(connectionId)`: another
+ * connection cannot address them at all, so no guessing analysis applies. The
+ * only requirement is uniqueness among live handles of one connection
+ * (1,296^2 = 1.68M keys, CAS-if-absent with retries), which two words satisfy.
+ */
+export declare const BOUND_HANDLE_WORD_COUNT = 2;
+/** Public handles are addressable by anyone; ADR 0006 §2 guessing numbers apply. */
+export declare const PUBLIC_HANDLE_WORD_COUNT = 4;
+/** Used when a public kind declares `strength: "high"` or its ttl exceeds one hour. */
+export declare const HIGH_PUBLIC_HANDLE_WORD_COUNT = 5;
+export declare const PUBLIC_HANDLE_ENTROPY_BITS: number;
+export declare const HIGH_PUBLIC_HANDLE_ENTROPY_BITS: number;
+export declare const EFF_SHORT_WORDLIST_2: readonly string[];
+/**
+ * Words the runtime may issue. The handle grammar joins words with `-`, so the
+ * one hyphenated official entry (`yo-yo`) would fuse with the separator and is
+ * never issued. The official list itself stays embedded unchanged.
+ */
+export declare const ISSUABLE_HANDLE_WORDS: readonly string[];
+export declare function handleWordAt(index: number): string;
+export declare function isHandleWord(value: string): boolean;
+/**
+ * Symmetric-deletion index (SymSpell, max distance 1). Two strings at
+ * Levenshtein distance <= 1 always share a form reachable by deleting at most
+ * one character from each side, so a lookup of the query and its one-deletion
+ * variants yields every candidate; a real distance check then removes the false
+ * positives (e.g. transpositions). ~10k entries, O(len) per lookup.
+ */
+/** Shortest and longest words in the list (3 and 10 for the official list). */
+export declare const MIN_HANDLE_WORD_LENGTH: number;
+export declare const MAX_HANDLE_WORD_LENGTH: number;
+/**
+ * Resolves one handle segment to a wordlist entry: the exact word, or the
+ * unique word at edit distance <= `maxDistance`. Returns null when no word or
+ * more than one word qualifies. The official list has pairwise edit distance
+ * >= 3, so at distance 1 every non-null answer is unique; the uniqueness check
+ * is kept as a guard so a wordlist change cannot silently make normalization
+ * map one input onto two different canonical handles.
+ */
+export declare function findHandleWordWithinDistance(segment: string, maxDistance: 1): string | null;