@apifuse/provider-sdk 2.1.0-beta.2 → 2.1.0-beta.21

package/src/cli/templates/provider/.gitignore.tpl

@@ -0,0 +1,22 @@
+node_modules/
+
+# Environment and local secrets
+.env
+.env.*
+!.env.example
+
+# Build, coverage, cache, and local runtime artifacts
+coverage/
+dist/
+.cache/
+.turbo/
+.bun/
+*.tsbuildinfo
+
+# Bounty submission output
+submission-report.md
+
+# OS/editor junk
+.DS_Store
+Thumbs.db
+*.swp

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,6 +8,68 @@ Generated with `apifuse create`.
 bun run dev
 bun run check
 bun run test
+bun run submit-check -- --smoke
+bunx apifuse perf . --operation <operation-id> --runs 3
+```
+
+
+## Module layout
+
+The generated provider uses the recommended split layout:
+
+```text
+index.ts              # composition root: defineProvider() and wiring only
+meta.ts               # provider metadata
+operations/           # APIFuse operation contracts and handlers
+schemas/              # public input/output schemas near operations
+upstream/             # upstream ceremony: clients, auth, request builders
+mappers/              # upstream-to-APIFuse normalization helpers
+domain/               # shared provider-specific business ceremony
+```
+
+Small providers may stay in one file, but larger providers are easier to
+review when `index.ts` remains a short composition root.
+
+## Pre-submission report
+
+Before posting bounty evidence, run:
+
+```bash
+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. `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
+
+### Parameters
+
+Starter `ping` accepts `{ "value": string }`. Replace this section with each
+real operation's input schema, required fields, formats, limits, and examples
+before submitting bounty evidence.
+
+### Response
+
+Starter `ping` returns `{ "ok": boolean, "message": string }`. Replace this
+section with the normalized response fields, units, enum values, pagination,
+and upstream caveats for each real operation.
+
+### Example
+
+```json
+{
+	"requestId": "req_local_ping",
+	"input": { "value": "hello" },
+	"headers": {}
+}
 ```
 
 ## Provider server contract
@@ -51,18 +113,18 @@ Structured errors return an `error` object with `code`, `message`,
   `connection.secrets`, and read them with `ctx.credential`.
 - Auth flow: call `/auth/start`, then `/auth/continue` with the same `flowId`;
   carry returned `contextPatch` values into the next request's `context`.
-- TLS/browser runtime: if Bun blocks native dependency lifecycle scripts, run
-  `bun pm untrusted` and trust SDK dependencies such as `koffi` before debugging
-  `ctx.tls`; for TypeScript browser Providers use
-  `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only),
-  then install local Chromium with `bunx playwright install chromium` or set
-  `CDP_POOL_URL`.
+- Stealth/browser runtime: keep access-sensitive operations on `ctx.stealth.fetch()` with an
+  SDK stealth `profile`; the TypeScript stealth runtime uses `impit` internally.
+  `ctx.stealth` supports Chrome/Firefox-style profiles. For TypeScript browser
+  Providers or Safari-specific behavior use `browser.engine: "playwright-stealth"`
+  (`nodriver` is Python-runtime only), then install local Chromium with
+  `bunx playwright install chromium` or set `APIFUSE__CDP_POOL__URL`.
 
 ## Next steps
 
 1. Replace the sample `ping` operation with real upstream logic.
 2. Once the real operation declares `upstream.baseUrl` and uses `ctx.http` or
-   `ctx.tls`, record a fixture with:
+   `ctx.stealth`, record a fixture with:
    `bun run record -- --operation <operation> --params '<json-input>'`.
 3. Replace the starter `healthCheckUnsupported` with a real `healthCheck` for read-only upstream operations when safe.
 4. Extend tests and operation metadata until the provider is bounty-ready.
@@ -81,3 +143,21 @@ Every operation must declare exactly one of:
 
 The generated `ping` operation uses `healthCheckUnsupported` only because it is
 a local scaffold check, not a real upstream API probe.
+
+`healthCheck.cases[].assertions` receives `{ data, status, durationMs, meta }`.
+`data` is the parsed operation output. Use this shape in real operations:
+
+```ts
+healthCheck: {
+  interval: "5m",
+  cases: [{
+    name: "lookup baseline",
+    input: { q: "btc" },
+    assertions: ({ data, status, durationMs }) => {
+      if (status !== 200 || data.results.length === 0 || durationMs > 3000) {
+        return { status: "degraded", label: "lookup baseline changed" };
+      }
+    },
+  }],
+}
+```

package/src/cli/templates/provider/dev.ts.tpl

@@ -2,4 +2,4 @@ import { startDevServer } from "@apifuse/provider-sdk";
 
 import provider from "./index";
 
-startDevServer(provider, { port: Number(process.env.PORT) || 3900 });
+startDevServer(provider, { port: Number(process.env.APIFUSE__RUNTIME__PORT) || 3900 });

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

@@ -0,0 +1,3 @@
+# Domain
+
+Put provider-specific business ceremony here when it is shared across operations and too complex to live inside one operation module.

package/src/cli/templates/provider/index.ts.tpl

@@ -1,23 +1,7 @@
-import { defineProvider, z } from "@apifuse/provider-sdk";
+import { defineProvider } from "@apifuse/provider-sdk/provider";
 
-const InputSchema = z
-  .object({
-    value: z
-      .string()
-      .describe("Sample input value used to verify the generated provider scaffold is wired correctly."),
-  })
-  .describe("Input payload for the generated ping operation.");
-
-const OutputSchema = z
-  .object({
-    ok: z
-      .boolean()
-      .describe("Whether the generated provider handled the sample request successfully."),
-    message: z
-      .string()
-      .describe("Human-readable confirmation that the generated provider round-tripped the sample payload."),
-  })
-  .describe("Output payload returned by the generated ping operation.");
+import { providerMeta } from "./meta";
+import { operations } from "./operations";
 
 export default defineProvider({
   id: "{{PROVIDER_ID}}",
@@ -26,32 +10,6 @@ export default defineProvider({
   allowedHosts: ["api.example.com"],
   reviewed: "community",
   {{SECRETS_BLOCK}}{{CREDENTIAL_BLOCK}}auth: {{AUTH_BLOCK}},
-  meta: {
-    displayName: "{{DISPLAY_NAME}}",
-    description: "{{DISPLAY_NAME}} provider starter for ApiFuse community contributions.",
-    category: "{{CATEGORY}}",
-    tags: ["{{PROVIDER_ID}}", "starter", "community"],
-  },
-  operations: {
-    ping: {
-      description:
-        "Confirms the generated provider wiring is operational by echoing a small sample payload through the ApiFuse runtime contract. Use when validating local development, baseline checks, or first-pass bounty scaffolds. Do NOT use for production data retrieval or upstream-specific workflows because this starter operation exists only to prove the generated project compiles, serves, and round-trips input/output correctly. Returns a success flag plus a message containing the supplied value.",
-      input: InputSchema,
-      output: OutputSchema,
-      handler: async (_ctx, input) => {
-        return {
-          ok: true,
-          message: "{{DISPLAY_NAME}} received: " + input.value,
-        };
-      },
-      fixtures: {
-        request: { value: "hello" },
-        response: { ok: true, message: "{{DISPLAY_NAME}} received: hello" },
-      },
-      healthCheckUnsupported: {
-        reason:
-          "Generated local-only scaffold operation. Replace this with a real healthCheck for upstream-backed bounty operations when safe; keep healthCheckUnsupported only for destructive, paid, credential-sensitive, or otherwise unprobeable operations with a specific rationale.",
-      },
-    },
-  },
+  meta: providerMeta,
+  operations: operations,
 });

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

@@ -0,0 +1,3 @@
+# Mappers
+
+Put normalization helpers here when upstream responses need to become public APIFuse operation outputs.

package/src/cli/templates/provider/meta.ts.tpl

@@ -0,0 +1,7 @@
+export const providerMeta = {
+  displayName: "{{PROVIDER_ID}}",
+  displayNameKey: "meta.displayName",
+  descriptionKey: "meta.description",
+  category: "{{CATEGORY}}",
+  tags: ["{{PROVIDER_ID}}", "starter", "community"],
+} as const;

package/src/cli/templates/provider/operations/index.ts.tpl

@@ -0,0 +1,5 @@
+import { pingOperation } from "./ping";
+
+export const operations = {
+  ping: pingOperation,
+};

package/src/cli/templates/provider/operations/ping.ts.tpl

@@ -0,0 +1,24 @@
+import { defineOperation } from "@apifuse/provider-sdk/provider";
+
+import { pingInputSchema, pingOutputSchema } from "../schemas/ping";
+
+export const pingOperation = defineOperation({
+  descriptionKey: "operations.ping.description",
+  input: pingInputSchema,
+  output: pingOutputSchema,
+  handler: async ({{HANDLER_CTX}}, input) => {
+    {{BROWSER_HANDLER_BLOCK}}
+    return {
+      ok: true,
+      message: "{{DISPLAY_NAME}} received: " + input.value{{BROWSER_RESPONSE_FIELDS}},
+    };
+  },
+  fixtures: {
+    request: { value: "hello" },
+    response: { ok: true, message: "{{DISPLAY_NAME}} received: hello" },
+  },
+  healthCheckUnsupported: {
+    reason:
+      "Generated local-only scaffold operation. Replace this with a real healthCheck for upstream-backed bounty operations when safe; keep healthCheckUnsupported only for destructive, paid, credential-sensitive, or otherwise unprobeable operations with a specific rationale.",
+  },
+});

package/src/cli/templates/provider/schemas/ping.ts.tpl

@@ -0,0 +1,24 @@
+import { describeKey, z } from "@apifuse/provider-sdk/provider";
+
+export const pingInputSchema = describeKey(
+  z.object({
+    value: describeKey(z.string(), "schemaDescriptions.input.value"),
+  }),
+  "schemaDescriptions.input.root",
+);
+
+export const pingOutputSchema = describeKey(
+  z.object({
+    ok: describeKey(z.boolean(), "schemaDescriptions.output.ok"),
+    message: describeKey(z.string(), "schemaDescriptions.output.message"),
+    pageTitle: describeKey(
+      z.string().optional(),
+      "schemaDescriptions.output.pageTitle",
+    ),
+    frameCount: describeKey(
+      z.number().int().nonnegative().optional(),
+      "schemaDescriptions.output.frameCount",
+    ),
+  }),
+  "schemaDescriptions.output.root",
+);

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

package/src/cli/templates/provider/skills/normalization-standards/SKILL.md.tpl

@@ -0,0 +1,57 @@
+---
+name: normalization-standards
+description: Public output contract rules — field naming, timestamps, enums, units, nullability. Load before writing or editing any output schema or mapper.
+---
+
+# Normalization standards
+
+Public output is the product. Apply these to every schema + mapper pair.
+
+## Field naming
+- `snake_case`, English, semantic. `emergency_phone`, not `dutyTel3`.
+- Never expose vendor key vocabularies (`hv1`..`hv12`, `MKioskTy*`, `duty*`)
+  as public field names OR as dynamic record keys. A
+  `z.record(z.string(), ...)` keyed by vendor codes is still a vendor leak —
+  map codes to a stable public vocabulary (enum keys or an array of
+  `{ code, label, status }` objects with normalized status).
+
+## Timestamps and dates
+- Public: ISO 8601 (`2026-07-07T22:28:55+09:00`, dates `2026-07-07`,
+  clock times `HH:MM`). Include the upstream's timezone offset; Korean public
+  APIs are KST (+09:00) — verify, then encode it.
+- Vendor formats (`YYYYMMDDHHmmss`, `HHmm`, unpadded `900`) are parsed inside
+  the mapper. Unparseable → `null`, plus a test for that row shape.
+- Never emit a raw vendor timestamp string in public output, including
+  fixtures.
+
+## Enums
+- Vendor status values (codes, `Y`/`N`, Korean labels like `불가능`,
+  `정보미제공`) → declared `z.enum`. Unknown value → explicit `unknown` member
+  or fail closed; never pass raw text through.
+- Map from the OFFICIAL code table, not from guessing what live samples mean.
+  Add a regression test per enum member.
+
+## Numbers and units
+- Field name states the unit: `distance_meters`, `radius_meters`,
+  `price_krw`. Mapper proves the conversion (upstream km → `* 1000`).
+- Verify the upstream unit from spec or live-data sanity check (a "distance"
+  of `1.2` from a nearby search is km, not meters). Sibling endpoints of the
+  same vendor may differ — verify each one.
+- Value-domain constraints (`nonnegative`, `min`, `max`) must reflect the
+  upstream's REAL domain observed in live data, not what seems sensible.
+  A wrong `nonnegative()` turns real negative values into `null`/errors
+  silently.
+
+## Nullability
+- `null` means "upstream did not provide it" — never "parsing failed" and
+  never a placeholder for invented data.
+- Required-for-identity fields (ids, names) missing → throw
+  `UPSTREAM_SCHEMA_ERROR`; do not emit partial rows.
+
+## Checklist before submitting a schema/mapper change
+- [ ] No vendor key visible in any public field name or record key
+- [ ] All timestamps ISO 8601 with timezone; parsing tested for real vendor
+      shapes (padded/unpadded, string/number)
+- [ ] All status-like strings are declared enums with official-table mapping
+- [ ] Every numeric field's unit is in its name and conversion is tested
+- [ ] Constraints checked against live data, not intuition

package/src/cli/templates/provider/skills/pagination-and-counts/SKILL.md.tpl

@@ -0,0 +1,52 @@
+---
+name: pagination-and-counts
+description: total_count semantics, client-side filtering, and paging honesty. Load before implementing any list/search operation.
+---
+
+# Pagination and counts
+
+A caller uses `total_count`, `page`, and `limit` to plan iteration. If those
+numbers don't describe what the caller can actually page through, the
+operation is lying.
+
+## The client-side filtering trap
+If the upstream has no server-side filter for one of your inputs (e.g. no
+radius param) and you filter rows after fetching:
+
+- Upstream `totalCount` counts UNFILTERED rows. Returning it as your
+  `total_count` while returning filtered rows means: caller sees
+  `total_count: 541`, gets 1 row on page 1, and pages 2..28 return rows that
+  are outside the filter or empty. This is a contract failure, not a nuance.
+
+Acceptable resolutions, in preference order:
+1. **Don't accept the input.** If the upstream can't filter by it and you
+   can't enumerate all pages, drop the input from the schema and document the
+   upstream's real semantics (e.g. "results are distance-sorted; no radius
+   cutoff").
+2. **Expose upstream semantics honestly.** Distance-sorted paging with a
+   documented "no radius filter" contract and no fake `radius` input.
+3. **Filter AND fix the metadata.** If you must filter client-side, do not
+   return the upstream total. Return only what you can prove (`returned_count`
+   plus a `has_more` you can actually compute) and document that totals are
+   unavailable.
+
+Never combine: accepted filter input + client-side filter + upstream total.
+
+## Count integrity
+- Parse failure of `totalCount` → `UPSTREAM_SCHEMA_ERROR`, not `0`.
+  A fail-open zero disguises upstream drift as an empty dataset.
+- If `total_count > 0` but the page's row array normalizes to empty on
+  page 1, throw — that combination means broken extraction, not empty data.
+
+## Page/limit echo
+- Echo the EFFECTIVE values: if you clamp `limit` to the upstream max, return
+  the clamped value, not the requested one.
+- `page`/`limit` semantics must match the upstream's paging model
+  (1-indexed vs 0-indexed) — verify with two live pages, checking the
+  returned rows actually differ.
+
+## Checklist
+- [ ] No input is filtered client-side while `total_count` comes from upstream
+- [ ] totalCount parse failure fails closed
+- [ ] Effective (clamped) limit echoed
+- [ ] Two-page live check proves paging advances

package/src/cli/templates/provider/skills/upstream-contract-verification/SKILL.md.tpl

@@ -0,0 +1,45 @@
+---
+name: upstream-contract-verification
+description: How to establish evidence for upstream request params and response fields before coding. Load before wiring any new endpoint or mapping new fields.
+---
+
+# Upstream contract verification
+
+Most provider P0s come from guessed upstream contracts. Every param name and
+response field needs evidence BEFORE it ships.
+
+## Request parameters
+1. Start from the official spec document (data.go.kr 활용가이드, vendor API
+   docs). Copy exact names — casing and underscores matter
+   (`WGS84_LAT` ≠ `WGS84LAT`; the wrong one is often silently ignored).
+2. Confirm with ONE live call per endpoint. A param being ignored does not
+   produce an error — it produces plausible-looking wrong results, so compare:
+   - filtered vs unfiltered `totalCount` (identical → param ignored)
+   - a dense-area query returning 0 rows (→ param name/format wrong)
+3. Do NOT copy param names from a sibling endpoint or sibling API of the same
+   vendor without re-verifying. Same vendor ≠ same contract; endpoints drift.
+4. If a param only works together with another param (district requires
+   province), encode that dependency in the input schema with a clear error.
+   Test it: dependent-param-alone must be rejected, not silently national.
+
+## Response fields
+- Map exactly the field names present in your recorded live fixtures.
+- No speculative fallback chains (`row.distance ?? row.dist ?? row.Distance`).
+  If two shapes genuinely exist, you need a recorded fixture proving EACH
+  branch plus a row-level test per branch; otherwise map one name only.
+- Field presence varies by endpoint within the same vendor. Detail endpoints
+  often return more/differently-named fields than list endpoints — record
+  fixtures per endpoint, not per vendor.
+
+## When results look wrong
+- Same response body across different request payloads → the upstream is
+  ignoring your variation; stop tuning fields and re-check param names/auth.
+- Empty result for a query that must have data (city-center radius search,
+  major-district listing) → treat as a request bug. Never record it as a
+  fixture and never ship it.
+
+## Deliverables per endpoint
+- [ ] Spec reference (URL or doc name + section) noted in the PR/commit
+- [ ] One recorded live fixture proving request params take effect
+- [ ] Negative evidence checked: filtered count differs from unfiltered
+- [ ] Param dependencies enforced in the input schema with tests