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

package/dist/index.js

@@ -1,7 +1,6 @@
 // @apifuse/provider-sdk
 export * from "./auth.js";
 export * from "./ceremonies/index.js";
-export * from "./choice-token.js";
 export { defineConfig, loadApiFuseConfig, resolveProxy } from "./config/loader.js";
 export { canonicalJson, digestProviderContract, extractProviderContract, PROVIDER_CONTRACT_SCHEMA_VERSION, } from "./contract.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, } from "./define.js";
@@ -17,7 +16,8 @@ export * from "./recipes/gov-api.js";
 export * from "./recipes/rest-api.js";
 export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export { APIFUSE__CACHE__KEY_PEPPER_ENV, createBypassProviderCache, createProviderCache, } from "./runtime/cache.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 { createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
@@ -36,7 +36,7 @@ export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, }
 export { APIFUSE__OCR__API_KEY_ENV, APIFUSE__OCR__BACKEND_ENV, APIFUSE__OCR__BASE_URL_ENV, APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__OCR__MODEL_ENV, CLOUDFLARE_ACCOUNT_ID_ENV, CLOUDFLARE_WORKERS_AI_OCR_BACKEND, createCloudflareWorkersAiOcrClient, createOcrClientFromEnv, createOpenAiCompatibleOcrClient, createUnsupportedOcrClient, DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL, extractCaptchaCandidates, OPENAI_COMPATIBLE_OCR_BACKEND, } from "./runtime/ocr.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { createTraceContext, } from "./runtime/trace.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, redactPayload, sensitive, untrustedContent, z, } from "./schema.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 { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, serve, } from "./server/serve.js";
 export { DEFAULT_STEALTH_BROWSER, DEFAULT_STEALTH_OS, getStealthProfile, listStealthProfiles, } from "./stealth/profiles.js";
 export * from "./stream.js";
@@ -45,3 +45,4 @@ export * from "./utils/date.js";
 export * from "./utils/parse.js";
 export * from "./utils/text.js";
 export * from "./utils/transform.js";
+export { NativeTelemetryCollector, } from "./runtime/native-telemetry.js";

package/dist/lint.d.ts

@@ -80,6 +80,9 @@ export declare function lintProvider(provider: {
         contract?: ProviderContractMetaLike;
     };
     reviewed?: string;
+    /** Declared handle kinds (ADR-0012); read structurally, see readHandleKindDeclarations. */
+    handle?: unknown;
+    state?: unknown;
 }, options?: ProviderLintOptions): LintDiagnostic[];
 /** Internal detailed result used by the CLI to render suppression audits. */
 export declare function lintProviderWithInformation(provider: Parameters<typeof lintProvider>[0], options?: ProviderLintOptions): ProviderLintResult;

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,22 +377,34 @@ 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) {
     return Array.from(new Set(fields));
 }
-function isSensitiveSchema(schema) {
-    if (!schema || typeof schema !== "object" || !("meta" in schema)) {
-        return false;
+function readSensitivityDeclaration(schema, seen = new Set()) {
+    // Declarations sit on the leaf; same-path wrappers such as .optional(),
+    // .nullable(), .pipe() or z.lazy() carry no metadata of their own, so look
+    // through them.
+    if (!isSchema(schema) || seen.has(schema))
+        return undefined;
+    seen.add(schema);
+    const value = Reflect.get(getSchemaMetadata(schema), APIFUSE_SENSITIVE_META_KEY);
+    if (typeof value === "boolean")
+        return value;
+    const def = getSchemaDef(schema);
+    const children = def.type === "pipe"
+        ? [def.in, def.out]
+        : def.type === "lazy" && typeof def.getter === "function"
+            ? [def.getter()]
+            : [def.innerType];
+    for (const child of children) {
+        const declaration = readSensitivityDeclaration(child, seen);
+        if (declaration !== undefined)
+            return declaration;
     }
-    const meta = schema.meta;
-    if (typeof meta !== "function")
-        return false;
-    const metadata = meta.call(schema);
-    return (!!metadata &&
-        typeof metadata === "object" &&
-        Reflect.get(metadata, APIFUSE_SENSITIVE_META_KEY) === true);
+    return undefined;
 }
 function getSchemaMetadata(schema) {
     return schema.meta?.() ?? {};
@@ -416,9 +430,91 @@ const SENSITIVE_FIELD_NAMES = new Set([
     "phonenumber",
     "paymenturl",
 ]);
+// Only phone-shaped keys can hold reviewed public data (facility phones); the
+// rest are credentials, which a public declaration must not launder.
+const PUBLIC_DECLARABLE_FIELD_NAMES = new Set(["phone", "phonenumber"]);
+function normalizeFieldName(name) {
+    return name.toLowerCase().replace(/[-_\s]/g, "");
+}
 function isSensitiveFieldName(name) {
-    const normalized = name.toLowerCase().replace(/[-_\s]/g, "");
-    return SENSITIVE_FIELD_NAMES.has(normalized);
+    return SENSITIVE_FIELD_NAMES.has(normalizeFieldName(name));
+}
+function isDeclaredSensitiveField(key, schema) {
+    const declaration = readSensitivityDeclaration(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)) {
@@ -428,7 +524,7 @@ function collectUnmarkedSensitiveFields(schema, basePath, seen = new Set()) {
     const out = [];
     for (const [key, child] of Object.entries(getObjectShape(schema))) {
         const childPath = basePath ? `${basePath}.${key}` : key;
-        if (isSensitiveFieldName(key) && !isSensitiveSchema(child)) {
+        if (isSensitiveFieldName(key) && !isDeclaredSensitiveField(key, child)) {
             out.push(childPath);
         }
         out.push(...collectUnmarkedSensitiveFields(child, childPath, seen));
@@ -436,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.")
@@ -472,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",
@@ -491,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" ||
@@ -971,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;
@@ -1061,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;
@@ -1086,7 +1412,7 @@ export function lintOperation(op) {
             rule: "sensitive-field-unmarked",
             level: "warn",
             field,
-            message: `Schema field "${field}" looks sensitive; mark it with fields.*(), field(..., { sensitive: true }), or sensitive(...).`,
+            message: `Schema field "${field}" looks sensitive; mark it with fields.*() or sensitive(...); publicField(...) is accepted only for reviewed public phone-shaped fields.`,
         });
     }
     for (const field of uniqueFields(collectUnmarkedSensitiveFields(op.output, "output"))) {
@@ -1094,7 +1420,7 @@ export function lintOperation(op) {
             rule: "sensitive-field-unmarked",
             level: "warn",
             field,
-            message: `Schema field "${field}" looks sensitive; mark it with fields.*(), field(..., { sensitive: true }), or sensitive(...).`,
+            message: `Schema field "${field}" looks sensitive; mark it with fields.*() or sensitive(...); publicField(...) is accepted only for reviewed public phone-shaped fields.`,
         });
     }
     return diagnostics;
@@ -1160,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;
@@ -1186,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 { 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, 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 * 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, 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";