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

package/AUTHORING.md

@@ -136,6 +136,8 @@ Hosted runtime settings are engine-owned as well: every `APIFUSE__CDP_POOL__*`
 variable, the Cloudflare OCR/STT tokens and account identifier,
 `APIFUSE__OCR__API_KEY`, and `APIFUSE__CACHE__KEY_PEPPER`. `defineProvider`
 rejects them in `secrets`; the engine reads them from its own environment.
+Provider code must not probe those names either — to learn whether OCR is
+configured, read `ctx.ocr.available` (see the OCR section below).
 
 ### Engine mode
 
@@ -455,6 +457,40 @@ Best-practice rules:
 - Submission checks and health checks must not invoke live STT by default.
   Provide explicit smoke evidence when a provider depends on audio OTP behavior.
 
+### OCR runtime capability: availability is the SDK's verdict
+
+Declare `ocr: { mode: "required" | "optional" }` and call `ctx.ocr` from
+operation handlers or auth-flow handlers. Whether a working backend is wired
+in is decided by the SDK, never by provider code: `ctx.ocr.available` is
+`true` when `createOcrClientFromEnv` found a configured backend and `false`
+for the unsupported/error client that undeclared or misconfigured providers
+receive. Branch on that flag for behavior that depends on OCR being present
+(for example, whether a CAPTCHA field is required from the user), and keep the
+`OCR_UNAVAILABLE` / `UNSUPPORTED_OCR_BACKEND` error fallback for the call
+itself: `available: true` promises a configured backend, not a successful
+upstream call.
+
+```ts
+async start(ctx) {
+  const image = await fetchCaptcha(ctx);
+  return ctx.auth.nextForm({
+    turnId: "credentials",
+    fields: {
+      captchaText: { type: "string", required: !ctx.ocr.available, /* ... */ },
+    },
+    data: { captchaImage: image, ocrConfigured: ctx.ocr.available },
+  });
+}
+```
+
+Do not re-implement the predicate by reading `APIFUSE__OCR__*` or
+`APIFUSE__CLOUDFLARE__ACCOUNT_ID`: those names are engine-owned, the
+runtime-boundary lint reports the read, and a drift between the copy and the
+SDK's own selection logic downgrades every login to the manual path silently.
+
+A custom `OcrContext` override (`serve({ ocr })`, `createFlowContext({ ocr })`,
+or a hand-written test double) must set `available` explicitly as a plain data
+property; the SDK's own clients do, and `bindOcrTelemetry` preserves it.
 
 ### Health journey DX for SMS/payment flows
 
@@ -857,6 +893,77 @@ Note the asymmetry: the gate treats whitespace-only values as missing, but
 `ctx.env.get()` still returns the raw value to handlers — trim at the point of
 use if the upstream is whitespace-sensitive.
 
+### Runtime boundary: no `process.env`, `node:fs`, `child_process`, or raw `fetch()`
+
+Provider runtime code reaches the outside world through the context only:
+`ctx.http` / `ctx.stealth` for HTTP, `ctx.browser` for browser work,
+`ctx.env.get()` / `ctx.credential` for configuration and secrets, `ctx.files` /
+`ctx.cache` / `ctx.state` for data that must outlive a request. Ambient Node
+and Bun globals bypass `allowedHosts`, proxy policy, retries, redaction, the
+secret presence gate, and telemetry. `apifuse check` reports them at **error**
+level — a finding fails `apifuse check` and `apifuse submit-check`, in the
+official and the bounty `standalone` mode alike (the level was `warn` for one
+release as a migration window; the window closed once the fleet's request-path
+hits were fixed or acknowledged — a provider that still carries one sees
+`apifuse check` fail on its next SDK bump and fixes or acknowledges it in that
+same PR):
+
+- `process-env-direct-read` — `process.env.X`, `process.env["X"]`, a bare
+  `process.env` object use, `Bun.env`. The `APIFUSE__RUNTIME__*` bootstrap
+  family (`APIFUSE__RUNTIME__PORT`, `…POD_ID`, `…POD_ENDPOINT`) is exempt
+  everywhere; every other value is declared in `defineProvider` under
+  `secrets: [{ name, required }]` and read with `ctx.env.get(name)`. The names
+  visible to `ctx.env.get` are exactly the declared `secrets[].name` (minus
+  engine-owned names; an `oauth2_proxied` auth flow additionally sees
+  `APIFUSE__AUTH_PROXY__URL`). `env: true` (or `env: {}`) is the capability
+  declaration that turns the `ctx.env` binding on — a type *and* runtime gate,
+  since touching `ctx.env` without it throws `PROVIDER_CAPABILITY_UNDECLARED`
+  — and does not widen the readable names. Test/E2E toggles are not secrets
+  and cannot move to `ctx.env`: replace them with test doubles (inject
+  `ctx.env` / `ctx.http`) or recorded fixtures.
+- `node-runtime-module-import` — value imports of `fs`, `fs/promises`, `net`,
+  `tls`, `dgram`, `http`, `https`, `http2`, `child_process` (with or without
+  `node:`), and `Bun.spawn` / `Bun.spawnSync` / ``Bun.$` ` `` / `Bun.file` /
+  `Bun.write`. Type-only imports (`import type`, or every binding inline `type`) are ignored; `node:path`, `node:crypto`,
+  `node:url` are fine.
+- `direct-fetch-call` — the global `fetch()` (also `globalThis.fetch`).
+  `ctx.stealth.fetch()` never matches, nor does a call to a `fetch` binding
+  declared in an enclosing scope (parameter, variable, import, catch clause).
+  The check is lexical: a wrapper that takes `fetch` as a parameter does not
+  hide a global `fetch()` in another function of the same file.
+
+Scope is runtime source only: tests, recorded fixtures, `.d.ts`, the root
+`dev.ts` / `start.ts` / `deploy.ts` entrypoints, and the `scripts/`, `tools/`,
+`bin/` directories at the provider root are not scanned. Keep fixture
+recorders, smoke scripts, and other operator tooling under `scripts/`, and do
+not import from there in request-path modules. `apifuse check` also leaves out
+any directory that is itself a git checkout (a linked worktree such as
+`.worktree/<branch>/`, a nested clone, an initialised submodule): its files are
+another revision, checked in that checkout, not this provider's runtime source.
+
+Acknowledge a deliberate exception on the finding line or the comment-only
+line above it with `// @apifuse-allow <rule>: <reason>`; the finding then
+appears as an `INFO` audit line instead of an error, and the check passes.
+
+```ts
+// Before: request-path module reads the ambient environment and the disk
+import { mkdir, writeFile } from "node:fs/promises";
+const serviceKey = process.env.EXAMPLE_SERVICE_KEY;
+if (process.env.EXAMPLE_DIAG_TAP_DIR) {
+  await writeFile(`${process.env.EXAMPLE_DIAG_TAP_DIR}/booking.json`, JSON.stringify(response));
+}
+
+// After: the credential is a declared secret read through the context —
+// defineProvider({
+//   env: true, // turns the ctx.env capability on (type + runtime gate)
+//   secrets: [{ name: "APIFUSE__PROVIDER__EXAMPLE__SERVICE_KEY", required: true }], // the readable names
+// })
+// — and the ad-hoc diagnostic tap is deleted: a toggle that is not a secret has
+// no place in ctx.env; observability goes through ctx.trace instead.
+const serviceKey = ctx.env.get("APIFUSE__PROVIDER__EXAMPLE__SERVICE_KEY");
+const response = await ctx.trace.span("booking.confirm", () => confirmBooking(ctx, serviceKey));
+```
+
 ### Credentials forced into query parameters
 
 Prefer an authorization header or request body whenever the upstream supports

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.65
+
+- Release candidate for main commit 4731ac76145caf85a6c340ad0c446371bd24b052.
+
+## 2.2.0-beta.64
+
+- Release candidate for main commit 0505a938340d08db3ea3e2302cab5f6b5dd2b4e5.
+
 ## 2.2.0-beta.63
 
 - Release candidate for main commit a9b85acc5af4c40ec59774b0d1e864e7ed21828e.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vooy Korea, Inc. (주식회사 부이코리아)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/apifuse-check.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { z } from "zod";
@@ -226,6 +226,21 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 	);
 }
 
+/**
+ * A directory under the provider root that is itself a git checkout — a linked
+ * worktree (`.worktree/<branch>/`, whose `.git` is a file pointing at the main
+ * repository), a nested clone (`.git` directory), or an initialised submodule.
+ * Its files are another revision of some repository, not this provider's
+ * runtime source: an older copy of `upstream/` or `scripts/` there would be
+ * linted as if it were request-path code at the root (the tooling-directory
+ * exemption is anchored at the provider root), and its `apifuse check` is run
+ * in that checkout, not here. Git refuses to track a path named `.git`, so the
+ * marker cannot be planted in a committed tree to hide a file from the scan.
+ */
+function isNestedCheckout(directory: string): boolean {
+	return existsSync(join(directory, ".git"));
+}
+
 function collectProviderSourceFiles(providerRoot: string): Record<string, string> {
 	const sources: Record<string, string> = {};
 	// `.agents`/`.apifuse` are deliberately not skipped: managed content there
@@ -236,7 +251,7 @@ function collectProviderSourceFiles(providerRoot: string): Record<string, string
 		for (const entry of readdirSync(directory, { withFileTypes: true })) {
 			const path = resolve(directory, entry.name);
 			if (entry.isDirectory()) {
-				if (!skipDirectories.has(entry.name)) {
+				if (!skipDirectories.has(entry.name) && !isNestedCheckout(path)) {
 					visit(path);
 				}
 				continue;

package/bin/apifuse-submit-check.ts

@@ -25,18 +25,22 @@ import {
 	hasStreamEvidenceMarker,
 	parseStreamEvidenceRecord,
 } from "../src/stream-evidence.js";
+import { getTypeScript } from "../src/typescript-module.js";
 import { type CheckResult, PROMPT_ASSETS_CHECK_MESSAGE, runChecks } from "./apifuse-check.js";
 import { hasSubstantiveDelimitedTextStructure } from "./submit-check-delimited-text.js";
 import { hasSubstantiveXmlStructure } from "./submit-check-xml.js";
 
-const ts: typeof import("typescript") = await loadTypeScript();
+const ts: typeof import("typescript") = loadTypeScript();
 
-async function loadTypeScript(): Promise<typeof import("typescript")> {
+// Shares the lint rules' loader so a workspace whose `typescript` is the 7.x
+// native shell (no compiler API) falls back to `@typescript/typescript6`
+// instead of failing inside the first parse.
+function loadTypeScript(): typeof import("typescript") {
 	try {
-		return await import("typescript");
-	} catch {
+		return getTypeScript();
+	} catch (error) {
 		console.error(
-			"apifuse submit-check requires typescript; install it in the workspace running the CLI (bun add -d typescript)",
+			`apifuse submit-check requires the TypeScript compiler API; install it in the workspace running the CLI (bun add -d typescript). ${error instanceof Error ? error.message : String(error)}`,
 		);
 		process.exit(1);
 	}

package/dist/handle-meta.d.ts

@@ -15,25 +15,60 @@ export type HandleAccess = "bound" | "public";
  * `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. */
+/** The schema side a handle field appears on. */
+export type HandleFieldDirection = "input" | "output";
+/**
+ * Direction-specific property keys for one handle kind, for the operations
+ * whose caller-facing contract names the same handle differently coming in and
+ * going out (the platform canon's `cursor` in, `next_cursor` out). The two keys
+ * are two spellings of ONE handle: the value a caller reads from `output` is
+ * the value it must send back under `input`, unedited.
+ */
+export interface HandleFieldNames {
+    readonly input: string;
+    readonly output: string;
+}
+/**
+ * Value stored under {@link APIFUSE_HANDLE_META_KEY} on a handle field.
+ *
+ * `fieldName` is the INPUT property key — the name a caller sends the handle
+ * back under, and the name every runtime error message quotes. `outputFieldName`
+ * is present only when the output key differs, so a kind with one name emits
+ * exactly the meta it always did.
+ */
 export interface HandleFieldMeta {
     readonly kind: string;
     readonly type: HandleKindType;
     readonly fieldName: string;
+    readonly outputFieldName?: string;
     readonly issuedBy?: HandleIssuedBy;
 }
 /**
  * Structural view of a handle kind as seen by the provider declaration
  * (`handle: [WaitingDraft, PageCursor]`), lint, and the registry. The runtime
  * kinds returned by `defineCursor` / `defineDraft` satisfy this shape.
+ *
+ * `fieldName` / `outputFieldName` follow the {@link HandleFieldMeta} rule:
+ * `fieldName` is the input key, `outputFieldName` is set only when the output
+ * key differs.
  */
 export interface HandleKindDeclaration {
     readonly name: string;
     readonly type: HandleKindType;
     readonly fieldName: string;
+    readonly outputFieldName?: string;
     readonly access: HandleAccess;
     readonly issuedBy?: HandleIssuedBy;
 }
+/**
+ * The property key a handle kind claims on one side of an operation.
+ *
+ * This is the single place that resolves a direction to a key, so lint, the
+ * runtime, and error text cannot disagree about which name belongs where.
+ */
+export declare function handleFieldNameFor(kind: Pick<HandleKindDeclaration, "fieldName" | "outputFieldName">, direction: HandleFieldDirection): string;
+/** True when a kind names the same handle differently on input and output. */
+export declare function handleHasDirectionalFieldNames(kind: Pick<HandleKindDeclaration, "fieldName" | "outputFieldName">): boolean;
 /** 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. */

package/dist/handle-meta.js

@@ -7,6 +7,21 @@
  */
 /** JSON Schema meta key placed on every schema field created by `kind.field()`. */
 export const APIFUSE_HANDLE_META_KEY = "x-apifuse-handle";
+/**
+ * The property key a handle kind claims on one side of an operation.
+ *
+ * This is the single place that resolves a direction to a key, so lint, the
+ * runtime, and error text cannot disagree about which name belongs where.
+ */
+export function handleFieldNameFor(kind, direction) {
+    if (direction === "input")
+        return kind.fieldName;
+    return kind.outputFieldName ?? kind.fieldName;
+}
+/** True when a kind names the same handle differently on input and output. */
+export function handleHasDirectionalFieldNames(kind) {
+    return kind.outputFieldName !== undefined && kind.outputFieldName !== kind.fieldName;
+}
 /** 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. */
@@ -43,6 +58,7 @@ export function isHandleFieldMeta(value) {
     return (typeof record.kind === "string" &&
         (record.type === "cursor" || record.type === "draft") &&
         typeof record.fieldName === "string" &&
+        (record.outputFieldName === undefined || typeof record.outputFieldName === "string") &&
         (record.issuedBy === undefined || isHandleIssuedBy(record.issuedBy)));
 }
 /**

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 HandleIssuedBy, type HandleKindDeclaration, type HandleKindType } from "./handle-meta.js";
+import { type HandleAccess, type HandleFieldDirection, type HandleFieldMeta, type HandleFieldNames, type HandleIssuedBy, type HandleKindDeclaration, type HandleKindType } from "./handle-meta.js";
 import type { ProviderStateDurationString } from "./types.js";
-export type { HandleAccess, HandleFieldMeta, HandleIssuedBy, HandleKindDeclaration, HandleKindType, };
+export type { HandleAccess, HandleFieldDirection, HandleFieldMeta, HandleFieldNames, 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;
@@ -30,6 +30,10 @@ export interface HandleKindBase<TSchema extends ZodType = ZodType> extends Handl
     /**
      * Schema for the handle field, usable in output and input positions. Carries
      * the `x-apifuse-handle` meta and an SDK-owned English description.
+     *
+     * One schema serves both directions even when the kind declares separate
+     * `input` / `output` property keys: the meta carries both names and lint
+     * checks the key against the side the field actually appears on.
      */
     field(): ZodString;
 }
@@ -131,6 +135,7 @@ export declare function isHandleError(value: unknown): value is HandleError;
  */
 export declare function handleRecoverySentence(kind: {
     readonly fieldName: string;
+    readonly outputFieldName?: string;
     readonly issuedBy?: HandleIssuedBy;
 }): string;
 /** Parses a `ProviderStateDurationString` to milliseconds; throws on invalid or non-positive input. */
@@ -138,8 +143,16 @@ export declare function parseHandleDurationMs(value: ProviderStateDurationString
 export interface DefineCursorOptions<TSchema extends ZodType> {
     /** Kind name, `/^[a-z]{2,12}$/`; becomes the handle prefix. */
     readonly name: string;
-    /** Schema property key carrying the handle. Default `${name}_token`. */
-    readonly fieldName?: string;
+    /**
+     * Schema property key carrying the handle. Default `${name}_token`.
+     *
+     * Pass `{ input, output }` when the caller-facing contract names the same
+     * handle differently in each direction — the canon's `{ input: "cursor",
+     * output: "next_cursor" }`. Both keys must be given; the handle's identity
+     * stays the kind, so a value issued under `output` is still only valid when
+     * sent back under `input`.
+     */
+    readonly fieldName?: string | HandleFieldNames;
     readonly schema: TSchema;
     readonly ttl: ProviderStateDurationString;
     /** `"bound"` (default): connection-scoped, 2 words. `"public"`: provider-scoped, 4-5 words. */
@@ -155,7 +168,12 @@ export interface DefineCursorOptions<TSchema extends ZodType> {
 }
 export interface DefineDraftOptions<TSchema extends ZodType, TResultSchema extends ZodType | undefined> {
     readonly name: string;
-    readonly fieldName?: string;
+    /**
+     * Schema property key carrying the handle. Default `${name}_token`. Accepts
+     * `{ input, output }` for a contract that names the handle differently in
+     * each direction; see {@link DefineCursorOptions.fieldName}.
+     */
+    readonly fieldName?: string | HandleFieldNames;
     readonly schema: TSchema;
     /** Optional schema of the commit result (type-level). */
     readonly result?: TResultSchema;

package/dist/handle.js

@@ -9,7 +9,7 @@
  */
 import { z } from "zod";
 import { brandHandleError, hasHandleErrorBrand, ProviderError, } from "./errors.js";
-import { APIFUSE_HANDLE_META_KEY, formatHandleIssuers, handleFieldDescription, HANDLE_KIND_NAME_PATTERN, isHandleIssuedBy, } from "./handle-meta.js";
+import { APIFUSE_HANDLE_META_KEY, formatHandleIssuers, handleFieldDescription, handleHasDirectionalFieldNames, HANDLE_KIND_NAME_PATTERN, isHandleIssuedBy, } from "./handle-meta.js";
 import { BOUND_HANDLE_WORD_COUNT, HIGH_PUBLIC_HANDLE_WORD_COUNT, PUBLIC_HANDLE_WORD_COUNT, } from "./runtime/handle-wordlist.js";
 /** Public kinds whose (max) ttl exceeds this are issued with five words (auto-high). */
 const AUTO_HIGH_TTL_MS = 3_600_000;
@@ -64,6 +64,16 @@ export function isHandleError(value) {
  */
 export function handleRecoverySentence(kind) {
     const issuers = formatHandleIssuers(kind.issuedBy);
+    // When the kind is issued under one key and accepted under another, naming
+    // only one of them tells the LLM to look for a field that is not there. Name
+    // the output key it reads and the input key it writes, in that order.
+    if (handleHasDirectionalFieldNames(kind)) {
+        const issued = kind.outputFieldName;
+        if (issuers) {
+            return `Call ${issuers} again and pass the new \`${issued}\` back as \`${kind.fieldName}\`, exactly as returned.`;
+        }
+        return `Request a new \`${issued}\` and pass it back as \`${kind.fieldName}\`, exactly as returned.`;
+    }
     if (issuers) {
         return `Call ${issuers} again and pass the new \`${kind.fieldName}\` exactly as returned.`;
     }
@@ -111,10 +121,44 @@ function assertKindName(name, define) {
         throw new Error(`${define}: kind name must match ${HANDLE_KIND_NAME_PATTERN} (2-12 lowercase letters, no digits or separators) so it never fuses with the word body; received ${JSON.stringify(name)}.`);
     }
 }
-function assertFieldName(fieldName, define) {
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(fieldName)) {
-        throw new Error(`${define}: fieldName must be a plain identifier usable as a schema property key; received ${JSON.stringify(fieldName)}.`);
+function assertFieldName(fieldName, define, label) {
+    if (typeof fieldName !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(fieldName)) {
+        throw new Error(`${define}: ${label} must be a plain identifier usable as a schema property key; received ${JSON.stringify(fieldName)}.`);
+    }
+}
+/**
+ * Resolves the `fieldName` option to the input key and, when the two differ,
+ * the output key.
+ *
+ * The string form names one key for both directions and is unchanged. The
+ * object form requires BOTH keys: a half-declaration would leave one side
+ * silently defaulting to `${name}_token`, which is the kind of mismatch this
+ * option exists to make explicit. `outputFieldName` is left undefined when the
+ * two keys are equal so a one-name kind emits exactly the meta it always did.
+ */
+function resolveFieldNames(value, define, name) {
+    if (value === undefined)
+        return { fieldName: `${name}_token` };
+    if (typeof value === "string") {
+        assertFieldName(value, define, "fieldName");
+        return { fieldName: value };
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${define}: "${name}" fieldName must be a property key or { input, output }; received ${JSON.stringify(value)}.`);
+    }
+    const record = value;
+    const extra = Object.keys(record).filter((key) => key !== "input" && key !== "output");
+    if (extra.length > 0) {
+        throw new Error(`${define}: "${name}" fieldName accepts only "input" and "output"; received extra ${extra.map((key) => JSON.stringify(key)).join(", ")}.`);
+    }
+    if (record.input === undefined || record.output === undefined) {
+        throw new Error(`${define}: "${name}" fieldName must declare both "input" and "output" when the two directions differ; declaring one would leave the other defaulting to "${name}_token".`);
     }
+    assertFieldName(record.input, define, "fieldName.input");
+    assertFieldName(record.output, define, "fieldName.output");
+    if (record.input === record.output)
+        return { fieldName: record.input };
+    return { fieldName: record.input, outputFieldName: record.output };
 }
 function assertPositiveInteger(value, label, define) {
     if (!Number.isInteger(value) || value <= 0) {
@@ -163,8 +207,7 @@ function createHandleField(meta) {
 export function defineCursor(options) {
     const define = "defineCursor";
     assertKindName(options.name, define);
-    const fieldName = options.fieldName ?? `${options.name}_token`;
-    assertFieldName(fieldName, define);
+    const { fieldName, outputFieldName } = resolveFieldNames(options.fieldName, define, options.name);
     const access = options.access ?? "bound";
     assertAccess(access, define);
     const ttlMs = parseHandleDurationMs(options.ttl, `"${options.name}" ttl`);
@@ -183,12 +226,14 @@ export function defineCursor(options) {
         kind: options.name,
         type: "cursor",
         fieldName,
+        ...(outputFieldName ? { outputFieldName } : {}),
         ...(issuedBy ? { issuedBy } : {}),
     };
     return Object.freeze({
         name: options.name,
         type: "cursor",
         fieldName,
+        outputFieldName,
         access,
         issuedBy,
         schema: options.schema,
@@ -209,8 +254,7 @@ export function defineCursor(options) {
 export function defineDraft(options) {
     const define = "defineDraft";
     assertKindName(options.name, define);
-    const fieldName = options.fieldName ?? `${options.name}_token`;
-    assertFieldName(fieldName, define);
+    const { fieldName, outputFieldName } = resolveFieldNames(options.fieldName, define, options.name);
     if (!options.ttl || typeof options.ttl !== "object") {
         throw new Error(`${define}: draft "${options.name}" ttl must be { idle, max }.`);
     }
@@ -242,12 +286,14 @@ export function defineDraft(options) {
         kind: options.name,
         type: "draft",
         fieldName,
+        ...(outputFieldName ? { outputFieldName } : {}),
         ...(issuedBy ? { issuedBy } : {}),
     };
     return Object.freeze({
         name: options.name,
         type: "draft",
         fieldName,
+        outputFieldName,
         access,
         strength,
         issuedBy,

package/dist/health-scenario.d.ts

@@ -1562,6 +1562,44 @@ export type OperationResult = {
     data: JsonValue;
     request_id: string;
     duration_ms: number;
+    /**
+     * Whether the monitor's operation step was answered from a stale-if-error
+     * cache serve — the runtime's projection of the response envelope's
+     * `meta.stale`.
+     *
+     * An operation that reads its upstream through `ctx.cache.getOrSet(...,
+     * { staleIfErrorMs })` answers an upstream outage with HTTP 200 and a
+     * well-formed, fully schema-valid body for the whole stale window. Every
+     * assertion over `status_code` and `data` therefore passes, and the probe
+     * rolls up `ok` while the upstream is down. This boolean is the only thing
+     * in the step result that separates that from a live read.
+     *
+     * Always present, so a reference to it resolves to `false` rather than
+     * raising `reference_unresolvable`; a response whose `meta` is malformed
+     * fails the step rather than projecting as fresh.
+     *
+     * Providers that serve stale-if-error should guard on it, so an outage the
+     * cache is absorbing stops reading as green:
+     *
+     * ```ts
+     * {
+     *   id: "guard-freshness",
+     *   result: "freshness-guarded",
+     *   kind: "guard",
+     *   condition: {
+     *     kind: "predicate",
+     *     operator: "not_equals",
+     *     actual: { ref: { namespace: "steps", binding: "case", path: ["served_stale_cache"] } },
+     *     expected: true,
+     *   },
+     *   onFail: {
+     *     attribute: [{ operationId, status: "degraded", reasonCode: "expected_absence", reasonKey }],
+     *     stop: "scenario",
+     *   },
+     * }
+     * ```
+     */
+    served_stale_cache: boolean;
     candidate?: {
         attempts: number;
         selected_index: number | null;

package/dist/index.d.ts

@@ -13,14 +13,16 @@ export * from "./engine.js";
 export * from "./observability.js";
 export * from "./user-input.js";
 export * from "./i18n/index.js";
-export { type LintDiagnostic, lintOperation, lintProvider, } from "./lint.js";
+export { type LintDiagnostic, lintOperation, lintProvider, type ProviderLintInformation, type ProviderLintResult, } from "./lint.js";
+export { type LintRuntimeBoundarySourcesOptions, lintRuntimeBoundarySources, RUNTIME_BOUNDARY_RULES, type RuntimeBoundaryRule, } from "./runtime-boundary-lint.js";
+export { TYPESCRIPT_COMPILER_MODULE_SPECIFIERS, type TypeScriptCompilerModuleLike, } from "./typescript-module.js";
 export * from "./recipes/gov-api.js";
 export * from "./recipes/rest-api.js";
 export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export type { BrowserClientOptions } from "./runtime/browser.js";
 export { APIFUSE__CACHE__KEY_PEPPER_ENV, createBypassProviderCache, createProviderCache, type ProviderCacheOptions, } from "./runtime/cache.js";
 export * from "./handle.js";
-export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, handleFieldNameFor, handleHasDirectionalFieldNames, isHandleFieldMeta, } from "./handle-meta.js";
 export { type CreateHandleContextOptions, type CreateTestHandleContextOptions, createHandleContext, createTestHandleContext, type HandleNormalizationClass, type NormalizedHandle, normalizeHandle, } from "./runtime/handle.js";
 export { type CreateCredentialContextOptions, createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";

package/dist/index.js

@@ -12,12 +12,14 @@ export * from "./observability.js";
 export * from "./user-input.js";
 export * from "./i18n/index.js";
 export { lintOperation, lintProvider, } from "./lint.js";
+export { lintRuntimeBoundarySources, RUNTIME_BOUNDARY_RULES, } from "./runtime-boundary-lint.js";
+export { TYPESCRIPT_COMPILER_MODULE_SPECIFIERS, } from "./typescript-module.js";
 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 * from "./handle.js";
-export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, handleFieldNameFor, handleHasDirectionalFieldNames, isHandleFieldMeta, } from "./handle-meta.js";
 export { createHandleContext, createTestHandleContext, normalizeHandle, } from "./runtime/handle.js";
 export { createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";

package/dist/lint.d.ts

@@ -29,11 +29,16 @@ export type ProviderLintMode = "official" | "standalone";
 type ProviderLintOptions = {
     mode?: ProviderLintMode;
 };
+/**
+ * A non-blocking audit line: a finding the author acknowledged with
+ * `// @apifuse-allow <rule>: <reason>`, kept visible in `apifuse check` output.
+ */
 export interface ProviderLintInformation {
     rule: string;
     message: string;
     field?: string;
 }
+/** Diagnostics plus the acknowledged findings that accompany them. */
 export interface ProviderLintResult {
     diagnostics: LintDiagnostic[];
     information: ProviderLintInformation[];