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

package/dist/typescript-module.js

@@ -0,0 +1,72 @@
+import { createRequire } from "node:module";
+const requireModule = createRequire(import.meta.url);
+/**
+ * Package specifiers that may carry the compiler API, in resolution order.
+ *
+ * `typescript@7` (the Go-native toolchain) resolves but its JavaScript entry
+ * exports only `version`/`getExePath` — no `createSourceFile`, so the lint
+ * rules cannot parse with it. The compiler API of that generation is published
+ * as `@typescript/typescript6`, which is what a `typescript@7` dependency tree
+ * (for example the APIFuse monorepo root) installs alongside the shell.
+ */
+export const TYPESCRIPT_COMPILER_MODULE_SPECIFIERS = [
+    "typescript",
+    "@typescript/typescript6",
+];
+/**
+ * True when `candidate` is a loaded module that exposes the parser the lint
+ * rules need. Internal (narrows to the `typescript` module type, which is not
+ * part of the package surface); `lintRuntimeBoundarySources` applies it to the
+ * caller-supplied option.
+ */
+export function isTypeScriptCompilerModule(candidate) {
+    return (typeof candidate === "object" &&
+        candidate !== null &&
+        typeof candidate.createSourceFile === "function" &&
+        typeof candidate.ScriptTarget === "object");
+}
+function describeCandidate(candidate) {
+    if (typeof candidate === "object" && candidate !== null) {
+        const version = candidate.version;
+        if (typeof version === "string")
+            return `resolved ${version} without a compiler API`;
+    }
+    return "resolved without a compiler API";
+}
+/**
+ * Resolve the compiler API through `load`, trying each specifier in order and
+ * accepting the first module that exposes `createSourceFile`. Exposed for the
+ * tests; production code uses `getTypeScript()`.
+ */
+export function loadTypeScriptModule(load, specifiers = TYPESCRIPT_COMPILER_MODULE_SPECIFIERS) {
+    const attempts = [];
+    for (const specifier of specifiers) {
+        let candidate;
+        try {
+            candidate = load(specifier);
+        }
+        catch {
+            attempts.push(`${specifier}: not resolvable`);
+            continue;
+        }
+        if (isTypeScriptCompilerModule(candidate))
+            return candidate;
+        attempts.push(`${specifier}: ${describeCandidate(candidate)}`);
+    }
+    throw new Error(`The provider source lint needs the TypeScript compiler API (createSourceFile) and none of the resolvable packages provide it — ${attempts.join("; ")}. Install typescript 6.x as a devDependency, or @typescript/typescript6 next to a typescript 7 toolchain, in the dependency tree that installs @apifuse/provider-sdk.`);
+}
+/**
+ * Lazily loaded TypeScript compiler API shared by the source-level lint rules.
+ *
+ * `typeof import(...)` keeps the type without emitting a static import: the
+ * typescript package is a devDependency of the SDK and only the CLI and the
+ * lint rules need it at runtime, which the typescript-import-boundary test
+ * enforces for production sources. Resolution starts at the installed SDK, so
+ * the caller's dependency tree must provide one of
+ * `TYPESCRIPT_COMPILER_MODULE_SPECIFIERS`.
+ */
+let typeScriptModule;
+export function getTypeScript() {
+    typeScriptModule ??= loadTypeScriptModule(requireModule);
+    return typeScriptModule;
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.63",
+	"version": "2.2.0-beta.64",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/handle-meta.ts

@@ -19,11 +19,34 @@ export type HandleAccess = "bound" | "public";
  */
 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;
 }
 
@@ -31,15 +54,41 @@ export interface HandleFieldMeta {
  * 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 function handleFieldNameFor(
+	kind: Pick<HandleKindDeclaration, "fieldName" | "outputFieldName">,
+	direction: HandleFieldDirection,
+): string {
+	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: Pick<HandleKindDeclaration, "fieldName" | "outputFieldName">,
+): boolean {
+	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}$/;
 
@@ -77,6 +126,7 @@ export function isHandleFieldMeta(value: unknown): value is HandleFieldMeta {
 		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/src/handle.ts

@@ -18,9 +18,12 @@ import {
 	APIFUSE_HANDLE_META_KEY,
 	formatHandleIssuers,
 	handleFieldDescription,
+	handleHasDirectionalFieldNames,
 	HANDLE_KIND_NAME_PATTERN,
 	type HandleAccess,
+	type HandleFieldDirection,
 	type HandleFieldMeta,
+	type HandleFieldNames,
 	type HandleIssuedBy,
 	type HandleKindDeclaration,
 	type HandleKindType,
@@ -36,7 +39,9 @@ import type { ProviderStateDurationString } from "./types.js";
 
 export type {
 	HandleAccess,
+	HandleFieldDirection,
 	HandleFieldMeta,
+	HandleFieldNames,
 	HandleIssuedBy,
 	HandleKindDeclaration,
 	HandleKindType,
@@ -69,6 +74,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;
 }
@@ -259,9 +268,20 @@ export function isHandleError(value: unknown): value is HandleError {
  */
 export function handleRecoverySentence(kind: {
 	readonly fieldName: string;
+	readonly outputFieldName?: string;
 	readonly issuedBy?: HandleIssuedBy;
 }): string {
 	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 as string;
+		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.`;
 	}
@@ -317,8 +337,16 @@ export function parseHandleDurationMs(value: ProviderStateDurationString, label:
 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. */
@@ -338,7 +366,12 @@ export interface DefineDraftOptions<
 	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;
@@ -372,12 +405,59 @@ function assertKindName(name: unknown, define: string): asserts name is string {
 	}
 }
 
-function assertFieldName(fieldName: string, define: string): void {
-	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(fieldName)) {
+function assertFieldName(
+	fieldName: unknown,
+	define: string,
+	label: string,
+): asserts fieldName is string {
+	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: string | HandleFieldNames | undefined,
+	define: string,
+	name: string,
+): { fieldName: string; outputFieldName?: string } {
+	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 as unknown as Record<string, unknown>;
+	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}: fieldName must be a plain identifier usable as a schema property key; received ${JSON.stringify(fieldName)}.`,
+			`${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: number, label: string, define: string): void {
@@ -442,8 +522,7 @@ export function defineCursor<TSchema extends ZodType>(
 ): CursorKind<TSchema> {
 	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: unknown = options.access ?? "bound";
 	assertAccess(access, define);
 	const ttlMs = parseHandleDurationMs(options.ttl, `"${options.name}" ttl`);
@@ -464,12 +543,14 @@ export function defineCursor<TSchema extends ZodType>(
 		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,
@@ -494,8 +575,7 @@ export function defineDraft<
 >(options: DefineDraftOptions<TSchema, TResultSchema>): DraftKind<TSchema, TResultSchema> {
 	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 }.`);
 	}
@@ -533,12 +613,14 @@ export function defineDraft<
 		kind: options.name,
 		type: "draft",
 		fieldName,
+		...(outputFieldName ? { outputFieldName } : {}),
 		...(issuedBy ? { issuedBy } : {}),
 	};
 	return Object.freeze({
 		name: options.name,
 		type: "draft",
 		fieldName,
+		outputFieldName,
 		access,
 		strength,
 		issuedBy,

package/src/health-scenario.ts

@@ -545,6 +545,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 };
 };
 export type ExtractResult<T extends JsonValue = JsonValue> = {

package/src/index.ts

@@ -127,7 +127,19 @@ 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";
@@ -143,6 +155,8 @@ export {
 	APIFUSE_HANDLE_META_KEY,
 	HANDLE_KIND_NAME_PATTERN,
 	handleFieldDescription,
+	handleFieldNameFor,
+	handleHasDirectionalFieldNames,
 	isHandleFieldMeta,
 } from "./handle-meta.js";
 export {