@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.2

package/src/ceremonies/index.ts

@@ -1,7 +1,8 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 
-import Ajv from "ajv";
+import Ajv2020 from "ajv/dist/2020.js";
 
+import { AUTH_TURN_SCHEMA, type KnownAuthTurnKind } from "../auth-turn";
 import {
 	FlowExpiredError,
 	ProviderSecretError,
@@ -15,53 +16,18 @@ import type {
 	FlowContext,
 } from "../types";
 
-type TurnKind =
-	| "abort"
-	| "challenge"
-	| "complete"
-	| "form"
-	| "message"
-	| "multi_choice"
-	| "poll"
-	| "redirect"
-	| "retry";
+type TurnKind = KnownAuthTurnKind;
 
 type CeremonyHandler = AuthFlowInputHandler;
 
 type JsonObject = Record<string, unknown>;
 
-const ajv = new Ajv({ allErrors: true, strict: true, strictSchema: true });
-
-const authTurnSchema = {
-	type: "object",
-	additionalProperties: false,
-	required: ["kind", "turnId"],
-	properties: {
-		kind: { type: "string", minLength: 1 },
-		turnId: { type: "string", minLength: 1 },
-		expiresAt: { type: "string", minLength: 1 },
-		data: {
-			type: "object",
-			additionalProperties: true,
-		},
-		expectedInput: {
-			type: "object",
-			additionalProperties: true,
-		},
-		hint: { type: "string" },
-		hintKey: { type: "string" },
-		timing: {
-			type: "object",
-			additionalProperties: false,
-			properties: {
-				suggestedPollIntervalMs: { type: "number", minimum: 1 },
-				maxWaitMs: { type: "number", minimum: 1 },
-			},
-		},
-	},
-} as const;
-
-const validateAuthTurn = ajv.compile(authTurnSchema);
+const ajv = new Ajv2020({ allErrors: true, strict: true, strictSchema: true });
+
+// Runtime ceremony-output validation derives from the exported versioned
+// contract: it compiles the exact AUTH_TURN_SCHEMA document shipped at
+// dist/auth-turn/auth-turn.v1.schema.json, so the two cannot drift.
+const validateAuthTurn = ajv.compile(AUTH_TURN_SCHEMA);
 
 const OAUTH2_STATE_KEY = "__oauth2_state";
 const OAUTH2_PKCE_VERIFIER_KEY = "__oauth2_pkce_verifier";

package/src/cli/create.ts

@@ -4,15 +4,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import {
-	cancel,
-	intro,
-	isCancel,
-	note,
-	outro,
-	select,
-	text,
-} from "@clack/prompts";
+import { cancel, intro, isCancel, note, outro, select, text } from "@clack/prompts";
 import { z } from "zod";
 
 import packageJson from "../../package.json";
@@ -28,12 +20,7 @@ export const CATEGORY_OPTIONS = [
 	"communication",
 	"other",
 ] as const;
-export const AUTH_MODE_OPTIONS = [
-	"none",
-	"platform-managed",
-	"credentials",
-	"oauth2",
-] as const;
+export const AUTH_MODE_OPTIONS = ["none", "platform-managed", "credentials", "oauth2"] as const;
 export const RUNTIME_OPTIONS = ["standard", "browser"] as const;
 export const PRESET_OPTIONS = ["standalone", "monorepo"] as const;
 
@@ -95,9 +82,7 @@ export type ProviderCreatePlan = {
 	workspaceRoot?: string;
 };
 
-const TEMPLATE_DIR = fileURLToPath(
-	new URL("./templates/provider/", import.meta.url),
-);
+const TEMPLATE_DIR = fileURLToPath(new URL("./templates/provider/", import.meta.url));
 const HELP_TEXT = `Usage: apifuse create <provider-name> [options]
 Examples:
   apifuse create my-provider
@@ -126,9 +111,7 @@ export async function main() {
 	}
 
 	const parsed = parseArgs(normalizedArgs);
-	const config = parsed.configPath
-		? await loadConfig(parsed.configPath)
-		: undefined;
+	const config = parsed.configPath ? await loadConfig(parsed.configPath) : undefined;
 	const resolved = await resolveCreateOptions(parsed, config, process.cwd());
 	const plan = await buildProviderCreatePlan(resolved, process.cwd());
 
@@ -195,18 +178,10 @@ function parseArgs(argv: string[]): ParsedArgs {
 				parsed.displayName = ensureValue(flag, consumeValue());
 				break;
 			case "--category":
-				parsed.category = parseEnum(
-					"category",
-					consumeValue(),
-					CATEGORY_OPTIONS,
-				);
+				parsed.category = parseEnum("category", consumeValue(), CATEGORY_OPTIONS);
 				break;
 			case "--auth-mode":
-				parsed.authMode = parseEnum(
-					"auth mode",
-					consumeValue(),
-					AUTH_MODE_OPTIONS,
-				);
+				parsed.authMode = parseEnum("auth mode", consumeValue(), AUTH_MODE_OPTIONS);
 				break;
 			case "--runtime":
 				parsed.runtime = parseEnum("runtime", consumeValue(), RUNTIME_OPTIONS);
@@ -253,9 +228,7 @@ function parseEnum<T extends readonly string[]>(
 	const resolvedValue = ensureValue(`--${label}`, value);
 	const matchedValue = options.find((option) => option === resolvedValue);
 	if (!matchedValue) {
-		throw new Error(
-			`Invalid ${label}: ${resolvedValue}. Expected one of: ${options.join(", ")}`,
-		);
+		throw new Error(`Invalid ${label}: ${resolvedValue}. Expected one of: ${options.join(", ")}`);
 	}
 	return matchedValue;
 }
@@ -282,9 +255,7 @@ async function resolveCreateOptions(
 		authMode: parsed.authMode ?? config?.authMode,
 		runtime: parsed.runtime ?? config?.runtime,
 		sdkSpecifier:
-			parsed.sdkSpecifier ??
-			config?.sdkSpecifier ??
-			process.env.APIFUSE__SDK__SPECIFIER,
+			parsed.sdkSpecifier ?? config?.sdkSpecifier ?? process.env.APIFUSE__SDK__SPECIFIER,
 		dryRun: parsed.dryRun,
 		json: parsed.json,
 		yes: parsed.yes,
@@ -298,9 +269,7 @@ async function resolveCreateOptions(
 
 	if (partial.yes) {
 		if (!partial.name) {
-			throw new Error(
-				"--yes requires a provider name (positional or via config).",
-			);
+			throw new Error("--yes requires a provider name (positional or via config).");
 		}
 
 		return {
@@ -410,9 +379,7 @@ export async function buildProviderCreatePlan(
 	cwd: string,
 ): Promise<ProviderCreatePlan> {
 	const resolvedWorkspaceRoot =
-		options.preset === "monorepo"
-			? findApifuseInternalWorkspaceRoot(cwd)
-			: undefined;
+		options.preset === "monorepo" ? findApifuseInternalWorkspaceRoot(cwd) : undefined;
 	if (options.preset === "monorepo" && !resolvedWorkspaceRoot) {
 		throw new Error(
 			"Monorepo preset is internal to the APIFuse repository. External bounty workspaces are one-provider repositories; use the standalone default create flow.",
@@ -424,9 +391,7 @@ export async function buildProviderCreatePlan(
 	if (options.outputDir) {
 		providerRoot = resolve(cwd, options.outputDir);
 		installCwd =
-			options.preset === "monorepo" && resolvedWorkspaceRoot
-				? resolvedWorkspaceRoot
-				: providerRoot;
+			options.preset === "monorepo" && resolvedWorkspaceRoot ? resolvedWorkspaceRoot : providerRoot;
 	} else if (options.preset === "monorepo" && resolvedWorkspaceRoot) {
 		providerRoot = resolve(resolvedWorkspaceRoot, "providers", options.name);
 		installCwd = resolvedWorkspaceRoot;
@@ -439,10 +404,7 @@ export async function buildProviderCreatePlan(
 		throw new Error(`Target directory already exists: ${providerRoot}`);
 	}
 
-	if (
-		options.sdkSpecifier?.startsWith("workspace:") &&
-		!resolvedWorkspaceRoot
-	) {
+	if (options.sdkSpecifier?.startsWith("workspace:") && !resolvedWorkspaceRoot) {
 		throw new Error(
 			"workspace:* is only valid inside the APIFuse monorepo because public Provider SDK scaffolds must install from npm or an explicit tarball/file specifier.",
 		);
@@ -576,6 +538,38 @@ export async function buildProviderCreatePlan(
 				PROVIDER_ID: options.name,
 			}),
 		},
+		{
+			path: resolve(providerRoot, "AGENTS.md"),
+			content: await renderTemplate("AGENTS.md.tpl", {}),
+		},
+		{
+			path: resolve(providerRoot, "CLAUDE.md"),
+			content: await renderTemplate("CLAUDE.md.tpl", {}),
+		},
+		{
+			path: resolve(providerRoot, "skills", "normalization-standards", "SKILL.md"),
+			content: await renderTemplate("skills/normalization-standards/SKILL.md.tpl", {}),
+		},
+		{
+			path: resolve(providerRoot, "skills", "upstream-contract-verification", "SKILL.md"),
+			content: await renderTemplate("skills/upstream-contract-verification/SKILL.md.tpl", {}),
+		},
+		{
+			path: resolve(providerRoot, "skills", "fixtures-and-recording", "SKILL.md"),
+			content: await renderTemplate("skills/fixtures-and-recording/SKILL.md.tpl", {}),
+		},
+		{
+			path: resolve(providerRoot, "skills", "pagination-and-counts", "SKILL.md"),
+			content: await renderTemplate("skills/pagination-and-counts/SKILL.md.tpl", {}),
+		},
+		{
+			path: resolve(providerRoot, "skills", "health-checks-and-fail-closed", "SKILL.md"),
+			content: await renderTemplate("skills/health-checks-and-fail-closed/SKILL.md.tpl", {}),
+		},
+		{
+			path: resolve(providerRoot, "skills", "upstream-notes", "README.md"),
+			content: await renderTemplate("skills/upstream-notes/README.md.tpl", {}),
+		},
 	];
 
 	return {
@@ -592,17 +586,14 @@ export async function buildProviderCreatePlan(
 		validationCommands: [
 			"bun run check",
 			"bun run type-check",
-			"bun run submit-check",
+			"bun run submit-check -- --smoke",
 			"bun run test",
 		],
 		workspaceRoot: resolvedWorkspaceRoot,
 	};
 }
 
-async function renderTemplate(
-	fileName: string,
-	values: Record<string, string>,
-): Promise<string> {
+async function renderTemplate(fileName: string, values: Record<string, string>): Promise<string> {
 	const templatePath = resolve(TEMPLATE_DIR, fileName);
 	const template = await readFile(templatePath, "utf8");
 	return template.replace(/\{\{([A-Z_]+)\}\}/g, (_match, key: string) => {
@@ -610,10 +601,7 @@ async function renderTemplate(
 	});
 }
 
-function renderPackageJson(input: {
-	packageName: string;
-	sdkSpecifier: string;
-}): string {
+function renderPackageJson(input: { packageName: string; sdkSpecifier: string }): string {
 	return `${JSON.stringify(
 		{
 			name: input.packageName,
@@ -625,11 +613,9 @@ function renderPackageJson(input: {
 				dev: "apifuse dev .",
 				check: "apifuse check . && bun run type-check",
 				"type-check": "tsc --noEmit",
-				"submit-check":
-					"apifuse submit-check . --markdown submission-report.md",
+				"submit-check": "apifuse submit-check . --markdown submission-report.md",
 				test: "apifuse test .",
 				record: "apifuse record .",
-				"perf:sample": "apifuse perf . --operation ping --runs 3",
 				start: "bun start.ts",
 			},
 			dependencies: {
@@ -666,10 +652,7 @@ function renderTsconfig(): string {
 	)}\n`;
 }
 
-function renderStarterLocaleCatalog(
-	displayName: string,
-	locale: "en" | "ko",
-): string {
+function renderStarterLocaleCatalog(displayName: string, locale: "en" | "ko"): string {
 	const catalog = {
 		meta: {
 			displayName,
@@ -734,8 +717,8 @@ function renderAuthBlock(authMode: CreateAuthMode): string {
 			return `{
     mode: "credentials",
     flow: {
-      start: async () => ({
-        kind: "input",
+      start: async (_ctx) => ({
+        kind: "form",
         turnId: crypto.randomUUID(),
         expectedInput: {
           schema: {
@@ -778,7 +761,7 @@ function renderAuthBlock(authMode: CreateAuthMode): string {
 			return `{
     mode: "oauth2",
     flow: {
-      start: async () => ({
+      start: async (_ctx) => ({
         kind: "redirect",
         turnId: crypto.randomUUID(),
         data: {
@@ -871,9 +854,7 @@ function isApifuseInternalWorkspaceRoot(workspaceRoot: string): boolean {
 		return false;
 	}
 	try {
-		const packageJson = JSON.parse(
-			readFileSync(providerSdkPackageJsonPath, "utf8"),
-		);
+		const packageJson = JSON.parse(readFileSync(providerSdkPackageJsonPath, "utf8"));
 		return (
 			typeof packageJson === "object" &&
 			packageJson !== null &&
@@ -892,27 +873,17 @@ async function writePlan(plan: ProviderCreatePlan): Promise<void> {
 	}
 }
 
-async function installDependencies(
-	plan: ProviderCreatePlan,
-	jsonMode: boolean,
-): Promise<void> {
+async function installDependencies(plan: ProviderCreatePlan, jsonMode: boolean): Promise<void> {
 	await runCommand(plan.installCommand, plan.installCwd, jsonMode);
 }
 
-async function runBaselineValidation(
-	plan: ProviderCreatePlan,
-	jsonMode: boolean,
-): Promise<void> {
+async function runBaselineValidation(plan: ProviderCreatePlan, jsonMode: boolean): Promise<void> {
 	for (const command of plan.validationCommands) {
 		await runCommand(command, plan.providerRoot, jsonMode);
 	}
 }
 
-async function runCommand(
-	command: string,
-	cwd: string,
-	jsonMode: boolean,
-): Promise<void> {
+async function runCommand(command: string, cwd: string, jsonMode: boolean): Promise<void> {
 	const [binary, ...args] = command.split(" ");
 	if (!binary) {
 		throw new Error(`Cannot run empty command in ${cwd}`);
@@ -944,9 +915,7 @@ async function runCommand(
 			rejectPromise(
 				new Error(
 					`Command failed (${command}) in ${cwd}${
-						stdout || stderr
-							? `\n${[stdout, stderr].filter(Boolean).join("\n")}`
-							: ""
+						stdout || stderr ? `\n${[stdout, stderr].filter(Boolean).join("\n")}` : ""
 					}`,
 				),
 			);
@@ -954,11 +923,7 @@ async function runCommand(
 	});
 }
 
-function printResult(
-	plan: ProviderCreatePlan,
-	jsonMode: boolean,
-	dryRun: boolean,
-) {
+function printResult(plan: ProviderCreatePlan, jsonMode: boolean, dryRun: boolean) {
 	const payload = {
 		success: true,
 		dryRun,
@@ -975,9 +940,7 @@ function printResult(
 		},
 		validationCommands: plan.validationCommands,
 		nextDevCommand: plan.nextDevCommand,
-		files: plan.files.map(
-			(file) => relative(plan.providerRoot, file.path) || file.path,
-		),
+		files: plan.files.map((file) => relative(plan.providerRoot, file.path) || file.path),
 	};
 
 	if (jsonMode) {
@@ -993,7 +956,7 @@ function printResult(
 	}
 	console.log(`Next local dev: ${plan.nextDevCommand}`);
 	console.log(
-		"Submission evidence: run `bun run submit-check`, save the generated report, and note `/health` plus `POST /v1/{operation}` smoke results.",
+		"Submission evidence: run `bun run submit-check -- --smoke` to archive measured `/health` and `POST /v1/{operation}` results.",
 	);
 	if (plan.files.some((file) => file.content.includes('runtime: "browser"'))) {
 		console.log(

package/src/cli/templates/provider/AGENTS.md.tpl

@@ -0,0 +1,87 @@
+# APIFuse Provider Workspace — Agent Guide
+
+You are building an APIFuse provider. APIFuse turns messy upstream APIs into
+normalized, typed, evidence-backed public APIs. A provider that merely proxies
+the upstream is a failed provider, even if every check passes.
+
+This file is the core contract. Detailed procedures live in `skills/` — load
+the matching skill BEFORE working on that area (index at the bottom).
+
+## Non-negotiable principles
+
+### 1. Normalize, don't proxy
+Public output is an APIFuse contract, not the upstream's shape.
+- Field names: `snake_case`, semantic, English. Never leak vendor keys
+  (`dutyTel1`, `hvec`, `MKioskTy7`) into public output.
+- Timestamps: ISO 8601 in public output. Vendor formats (`20260707222855`)
+  are parsed inside mappers only. If a value cannot be parsed, omit/null it —
+  never pass the raw vendor string through.
+- Enums: normalize vendor status text/codes (`Y` / `불가능` / `정보미제공`) into a
+  declared enum. Mixed raw-text passthrough is a contract failure.
+- Units: every numeric field name states its unit (`distance_meters`), and the
+  mapper proves the conversion. Never relabel an upstream number without
+  verifying its unit against docs or live data.
+
+### 2. Fail closed, never fabricate
+- Never invent output values to satisfy a schema. Missing upstream data → null
+  field or structured error, never a plausible dummy.
+- Parse failures are errors, not defaults. Returning `0`, `[]`, or `null`
+  when the upstream shape changed hides breakage from every downstream gate.
+- If a non-empty upstream collection normalizes to zero rows, throw
+  `UPSTREAM_SCHEMA_ERROR` — silent empty success is the worst failure mode.
+- Model the upstream's real value domain. Check live data before adding
+  constraints like `nonnegative()` — some upstreams legitimately return
+  negative counts (e.g. overcapacity) and a wrong constraint silently
+  nulls real data.
+
+### 3. Preserve every input or fail loudly
+- Every accepted input must be representable in the upstream request. If it
+  isn't, reject at the schema or throw — never silently drop it.
+- Upstream parameter dependencies (param B ignored without param A) must be
+  enforced in YOUR schema. The upstream ignoring input silently is not an
+  excuse for your provider to do the same.
+
+### 4. Evidence over assumption
+- Upstream parameter names and response fields must be verified against the
+  official spec AND at least one live call. Do not guess casing or
+  underscores; do not copy from a sibling API without re-verifying.
+- No speculative field probing (`row.distance ?? row.dist ?? row.Distance`).
+  Map exactly the fields you have evidence for. One verified name per field.
+- Fixtures are recorded live evidence (`bun run record`), never hand-written.
+  Placeholder-looking values (`02-1234-5678`, "테헤란로 123") mean the fixture
+  is fabricated and the submission is not reviewable.
+- An empty result set from a dense query (0 hospitals within 5km of a city
+  center) is a request bug, not a valid fixture. Investigate before recording.
+
+### 5. Honest pagination and counts
+- If you filter rows client-side, the upstream `totalCount` is no longer your
+  `total_count`. Either expose upstream semantics honestly (documented) or
+  don't expose a total at all. A count the caller cannot page against is a lie.
+
+### 6. Health checks must detect real regressions
+- `Array.isArray(data.items)` alone can never fail. Every list operation's
+  health check must also flag the zero-rows case for a query that is known to
+  return data (dense-area query), so a broken upstream contract degrades
+  visibly instead of passing forever.
+
+## Verification loop (before every submit)
+
+```bash
+bun run check        # apifuse check + type-check
+bun run test         # your tests — cover mappers, error paths, edge rows
+bun run submit-check # structural score; a high score does NOT prove quality
+```
+
+`submit-check` is a structural gate. Every principle above can be violated
+while scoring 95/100 — reviewers and CI audit for exactly these classes.
+
+## Skill index — load before working on:
+
+| Area | Load |
+| --- | --- |
+| Output schemas, mappers, field naming, timestamps, enums | `skills/normalization-standards/SKILL.md` |
+| Upstream request params, new endpoint wiring, field mapping | `skills/upstream-contract-verification/SKILL.md` |
+| Recording fixtures, writing tests against fixtures | `skills/fixtures-and-recording/SKILL.md` |
+| List operations, paging, totals, client-side filtering | `skills/pagination-and-counts/SKILL.md` |
+| healthCheck blocks, error classification, fail-closed guards | `skills/health-checks-and-fail-closed/SKILL.md` |
+| Upstream-specific known pitfalls for THIS bounty | `skills/upstream-notes/` (read every file) |

package/src/cli/templates/provider/CLAUDE.md.tpl

@@ -0,0 +1 @@
+@AGENTS.md

package/src/cli/templates/provider/README.md.tpl

@@ -8,7 +8,8 @@ Generated with `apifuse create`.
 bun run dev
 bun run check
 bun run test
-bun run submit-check
+bun run submit-check -- --smoke
+bunx apifuse perf . --operation <operation-id> --runs 3
 ```
 
 
@@ -34,15 +35,17 @@ review when `index.ts` remains a short composition root.
 Before posting bounty evidence, run:
 
 ```bash
-bun run submit-check
+bun run submit-check -- --smoke
 ```
 
 This writes `submission-report.md` with a review-readiness score, blockers,
 warnings, health coverage notes, fixture/schema evidence, and remediation. A
 score is not a payout guarantee; blockers must be fixed before maintainer
 review. The generated `ping` starter intentionally warns until you replace it
-with real upstream-backed Operations. The full public-only checklist is shipped
-in `node_modules/@apifuse/provider-sdk/SUBMISSION.md`.
+with real upstream-backed Operations. `APIFUSE__PROVIDER__*` env vars enable
+live upstream calls; without them, structured provider errors can still verify
+runtime routing. The full public-only checklist is shipped in
+`node_modules/@apifuse/provider-sdk/SUBMISSION.md`.
 
 
 ## Operation guide

package/src/cli/templates/provider/skills/fixtures-and-recording/SKILL.md.tpl

@@ -0,0 +1,58 @@
+---
+name: fixtures-and-recording
+description: Recording live fixtures and writing trustworthy tests from them. Load before touching __fixtures__/ or writing operation tests.
+---
+
+# Fixtures and recording
+
+Fixtures are evidence, not examples. Reviewers treat fixtures as proof your
+provider ran against the real upstream.
+
+## Recording
+- Always record from the live upstream: `bun run record -- --operation <op>
+  --params '<json>'` with the real service key configured.
+- Record queries that RETURN DATA. Choose dense/known-good inputs (major city
+  district, a real entity id from a prior list call).
+- Re-record after any request-param or mapper change; stale fixtures make
+  every downstream test meaningless.
+
+## Forbidden fixture states
+- **Hand-written fixtures.** Values like `02-1234-5678`, "테헤란로 123",
+  round-number coordinates, or sequential ids are fabrication tells. If it
+  wasn't returned by the upstream, it cannot be in `__fixtures__/`.
+- **Empty-result fixtures for dense queries.** `items: [], total_count: 0`
+  for "hospitals within 5km of Gangnam" is not a fixture — it is an
+  unfixed request bug (wrong param name/format). Investigate first.
+- **Fixtures that contradict each other.** If one operation's fixture proves
+  `total_count: 541` while returning 1 filtered row, your count semantics are
+  broken (see pagination skill), not your fixture.
+
+## Fixture shape
+`apifuse record` (`bun run record`) writes the captured RAW UPSTREAM payload
+to `__fixtures__/raw.json` (secrets sanitized). With `--append` it
+accumulates an array of raw payloads. The recorder does NOT write your
+normalized output — raw.json is upstream evidence only.
+
+Derive normalized expectations in TESTS, not in the fixture file: load the
+recorded raw payload, run your mapper over it, and assert the exact expected
+normalized rows inline in the test. If you keep expected-output snapshots,
+generate them from the mapper and review them row by row — never hand-author
+values that the upstream did not return.
+
+## Tests to derive from fixtures
+- Mapper: `map(recordedUpstreamRow)` equals the expected normalized row
+  (toEqual, not toMatchObject, for full rows — partial matching hides
+  dropped fields).
+- Edge rows: single-item object vs array (`items.item` unwrapping), missing
+  optional fields, unpadded/numeric time values, vendor error headers.
+- Error paths: upstream error `resultCode`, HTTP failure, missing secret,
+  NO_DATA — each asserts the structured `ProviderError` code.
+- Handler-level: run the operation handler against a mock ctx that returns
+  the fixture upstream body; assert the full normalized envelope.
+
+## Checklist
+- [ ] Every fixture recorded live; no placeholder-looking values
+- [ ] No empty-result fixture for a query that must have data
+- [ ] normalized expectations derived from mapper(recorded raw), not
+      hand-authored
+- [ ] Error and edge-shape rows covered, not just the happy row

package/src/cli/templates/provider/skills/health-checks-and-fail-closed/SKILL.md.tpl

@@ -0,0 +1,65 @@
+---
+name: health-checks-and-fail-closed
+description: Writing health checks that can actually fail, and fail-closed guards at envelope and row level. Load before writing healthCheck blocks or error handling.
+---
+
+# Health checks and fail-closed guards
+
+## Health checks that can actually fail
+`Array.isArray(data.items)` alone can never fail. Every list operation's
+health check must be able to detect the zero-rows regression.
+
+Assertion contract (per SDK `HealthCheckCase`): THROW to fail the case
+(recorded as `down`); return `{ status: "degraded", label }` to flag without
+failing; return nothing for `ok`. There is no `"down"` return value.
+
+```ts
+assertions: ({ status, data }) => {
+  if (status !== 200) {
+    throw new Error(`<op> request failed with status ${status}`);
+  }
+  if (!Array.isArray(data.items)) {
+    throw new Error("<op> missing items array");
+  }
+  // Dense query MUST return rows; zero rows = upstream contract drift
+  if (data.items.length === 0) {
+    return { status: "degraded", label: "<op> dense query returned 0 rows" };
+  }
+}
+```
+
+- Choose health-check inputs that are guaranteed-dense (major city district,
+  a stable well-known entity id). Verify the id still exists when picking it.
+- Also assert one semantic field on the first row (e.g. `items[0].name` is a
+  non-empty string) so a mapper regression that empties fields degrades too.
+
+## Fail-closed: envelope level
+- Upstream error headers/codes → structured `ProviderError` with a stable
+  `code` (`UPSTREAM_AUTH_ERROR`, `UPSTREAM_ERROR`, `NO_DATA`, ...).
+- Non-JSON body, unexpected content type → `UPSTREAM_SCHEMA_ERROR`.
+- HTTP non-2xx → classified error; never a fake empty success envelope.
+  Fixture-based tests cannot catch swallowed errors — write an explicit test:
+  mock a non-ok response and assert the handler REJECTS.
+
+## Fail-closed: row level
+Envelope guards are not enough. The silent killer is: response is valid,
+array is non-empty, but every row normalizes to nothing.
+- If a non-empty upstream collection produces zero normalized rows, throw
+  `UPSTREAM_SCHEMA_ERROR` instead of returning `items: []`.
+- Identity fields (id, name) missing on a row → throw, don't skip the row
+  silently.
+- Regression-test both layers separately: a bad envelope AND a good envelope
+  with unmappable rows.
+
+## Error message hygiene
+`ProviderError.message` reaches the tenant verbatim. Never interpolate
+upstream free text that may contain personal data (names, phone numbers,
+addresses); allowlist known code tokens and keep raw bodies in server-side
+details/logs only.
+
+## Checklist
+- [ ] Every list op health check flags 0 rows on a dense query
+- [ ] One semantic field asserted on a real row
+- [ ] Swallowed-error test exists (non-ok mock → handler rejects)
+- [ ] Non-empty upstream → zero normalized rows throws
+- [ ] No upstream free text in customer-facing error messages