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

package/AUTHORING.md

@@ -136,6 +136,75 @@ 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
+
+Provider processes attach their capability bindings through an engine. Today the
+default is the in-process engine; ADR-0011 replaces it with the authenticated
+remote engine in a phased migration, and `serve` logs every boot as
+`provider_engine_mode` (`deprecated: true` for in-process). You do not need to
+change anything now.
+
+A deployment names the mode with the engine-owned `APIFUSE__ENGINE__MODE`
+variable (`in-process` or `remote`; trimmed and case-folded, blank means unset);
+hosts may pass `engineMode` to `serve`/`createServerApp`/`startDevServer`
+instead. The manifest wins when the two disagree, so provider code cannot
+silently downgrade what the deployment asked for; the disagreement is reported in
+the boot event's `warnings`. An unrecognized value is warned about and ignored —
+it never crashes the process. `APIFUSE__ENGINE__MODE` cannot be declared in
+`secrets` (`APIFUSE__ENGINE__*` is engine-owned).
+
+`remote` has no client in this release: the server attaches an engine that fails
+every request with `PROVIDER_ENGINE_MODE_UNSUPPORTED` and reports `503` on
+`/readyz`. It never falls back to in-process. `apifuse dev` and `apifuse record`
+refuse to start instead.
+
+`GET /health` is liveness only and stays engine-blind; `GET /readyz` reports the
+resolved engine attachment and is what readiness/startup probes should use — but
+only for a provider already pinned to an SDK release that serves the route.
+Earlier pins answer `404`, and a failing readiness/startup probe is not
+self-healing, so manifests move to `/readyz` after the pin wave, never before.
+
+### Deployment intent
+
+Deployment intent (runtime profile, resources, HPA, Redis, extra TCP ports) has
+exactly one authored home: the optional `deployment` key inside
+`defineProvider({...})`. The SDK passes it through verbatim; the APIFuse
+registry resolves omitted fields from the runtime profile and rejects anything
+it cannot resolve.
+
+- Declare only what differs from the profile. Profile defaults:
+  `runtime: "shared"`, `language: "typescript"`, `replicas: 1`,
+  `hpa: { enabled: true, minReplicas: 1, maxReplicas: 1, targetCPUUtilizationPercentage: 70 }`,
+  resources `25m/128Mi` (shared) or `200m/256Mi` (browser), `buildContext: "."`.
+  Most providers therefore declare no `deployment` key at all.
+- The deployment `runtime` axis (`shared | dedicated | browser`) is distinct
+  from the execution `runtime` (`standard | shared | browser`) declared next to
+  it.
+- Do not author a standalone `deploy.ts`, a `deployment` extra on a spread
+  default export (`export default { ...provider, deployment }`), or a
+  re-exported config module. A repository that still carries `deploy.ts`
+  migrates with `apifuse migrate-deployment .`: it hoists the file's non-default
+  values into the declaration, proves the result resolves identically, and
+  deletes the file. The `/deploy.ts` CODEOWNERS entry stays until the platform
+  stops honoring a re-added legacy file (`--drop-codeowners-lock` then). A
+  refusal names the manual step.
+- `apifuse check` warns during the migration window
+  (`deployment/legacy-deploy-file`, `deployment/spread-export`,
+  `deployment/redundant-default`); the rules become errors once no repository
+  carries the legacy file.
+
+```ts
+const buildProvider = defineProvider({
+  id: "example",
+  version: "1.0.0",
+  runtime: "standard",
+  deployment: { cache: { redis: { enabled: true } } },
+  // ...
+});
+```
 
 ### Factored operations
 
@@ -388,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
 
@@ -536,18 +639,20 @@ operation:
 
 ```ts
 errorCodes: [{
-  code: "UPSTREAM_SCHEMA_ERROR",
-  status: 502,
-  retryable: true,
-  description: "The upstream response no longer matches its schema.",
+  code: "ITEM_SOLD_OUT",
+  status: 409,
+  retryable: false,
+  description: "The upstream sold the item before checkout completed.",
 }],
 handler: async () => {
-  throw new ProviderError("Upstream schema changed", {
-    code: "UPSTREAM_SCHEMA_ERROR",
-  });
+  throw new ProviderError("Item sold out", { code: "ITEM_SOLD_OUT" });
 },
 ```
 
+Declare only codes the SDK does not already register. `UPSTREAM_SCHEMA_ERROR`,
+`UPSTREAM_AUTH_ERROR`, and `INVALID_REQUEST` are registered below, so throwing
+them needs no declaration at all.
+
 `defineProvider` accepts only statuses the server can emit: 400, 401, 404, 429,
 500, 502, 503, and 504. Invalid declared statuses fail provider definition,
 not a live request. Status selection uses this order:
@@ -567,10 +672,10 @@ The registered mappings are:
 | Error code or fallback | HTTP status |
 | --- | ---: |
 | `AUTH_REQUIRED`, `reauth_required` | 401 |
-| `MISSING_SECRET` | 400 |
+| `MISSING_SECRET`, `UPSTREAM_AUTH_ERROR`, `INVALID_REQUEST` | 400 |
 | `NOT_FOUND`, `not_found`, `NO_DATA` | 404 |
 | `RATE_LIMITED`, `UPSTREAM_RATE_LIMIT`, `LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR` | 429 |
-| `UPSTREAM_ERROR`, `BLOCKED` | 502 |
+| `UPSTREAM_ERROR`, `BLOCKED`, `UPSTREAM_SCHEMA_ERROR` | 502 |
 | `STT_UNAVAILABLE`, `UNSUPPORTED_STT_BACKEND`, `STATEFUL_FORWARDING_REPLAY_CACHE_FULL` | 503 |
 | Unregistered input `ValidationError` code | 400 |
 | Other unregistered `ProviderError` code | 500 |
@@ -587,6 +692,154 @@ Throw the domain `ProviderError` directly. Subclassing or wrapping it as a
 domain code's `status` instead. Genuine `TransportError` values remain
 SDK-owned and keep their 502/504 mapping.
 
+#### Three fleet-consensus codes are registered
+
+`UPSTREAM_AUTH_ERROR` (400), `UPSTREAM_SCHEMA_ERROR` (502), and
+`INVALID_REQUEST` (400) are registered mappings. All three are non-retryable.
+
+- `UPSTREAM_AUTH_ERROR` is 400, not 401 or 502, because it means the upstream
+  refused a *platform-managed* service key. The caller holds no credential, so
+  401 ("re-authenticate") asks for something the caller cannot do, and 502
+  ("the upstream is sick") promises a recovery that will never arrive. It is a
+  deployment/config defect, exactly like `MISSING_SECRET`.
+- `UPSTREAM_SCHEMA_ERROR` is non-retryable: a retry returns the same payload
+  the provider already could not normalize.
+- `INVALID_REQUEST` is the spelling for caller-side bad input. `INVALID_INPUT`,
+  `VALIDATION_ERROR`, and `BAD_REQUEST` are not registered.
+
+Like `UPSTREAM_ERROR` and `BLOCKED`, these are thrown by provider code rather
+than by the SDK, so they are registered mappings and not SDK-owned codes: an
+existing operation declaration still wins at runtime (step 2 above). Registering
+them therefore never rewrites a status you already declared. What it does do is
+let you delete the declaration — and when your declaration disagrees with the
+registered mapping, `apifuse check` reports it rather than leaving the fleet
+answering one code two ways:
+
+- `error-code-status-conflicts-sdk` — declared `status` differs from the
+  registered status.
+- `error-code-retryable-conflicts-sdk` — declared `retryable` differs from the
+  registered retryability.
+
+Both are warnings. Drop the conflicting field so the SDK supplies the value, or,
+if your operation genuinely means something else, throw a distinct code that
+says so.
+
+### Localized error messages (`messageKey` / `fixKey`)
+
+The positional `ProviderError` message stays **English**. It is what
+`error.message`, cause frames, the `provider_request_failed` log, OTLP
+attributes and tests see. Only two fields of the response body are localized:
+`error.message` and `error.fix`. Nothing else — not `code`, not `details`, not
+`errorCodes[].description`, not the `X-ApiFuse-Error-Observability` header.
+
+Attach locale keys instead of parsing `Accept-Language` yourself:
+
+```ts
+// locales/en.json
+{ "errors": { "upstreamSchema": {
+    "message": "{provider} returned an unexpected response.",
+    "fix": "Retry in a few minutes."
+} } }
+```
+
+```ts
+throw new ProviderError("The culture data service returned an unexpected response.", {
+  code: "UPSTREAM_SCHEMA_ERROR",
+  messageKey: "errors.upstreamSchema.message",
+  fixKey: "errors.upstreamSchema.fix",
+  params: { provider: "Culture Data" },
+});
+```
+
+Keys can also live on the declaration, which localizes **every** site that
+throws that code without touching the throw sites:
+
+```ts
+errorCodes: [{
+  code: "UPSTREAM_SCHEMA_ERROR",
+  description: "The upstream response no longer matches its schema.",
+  messageKey: "errors.upstreamSchema.message",
+  fixKey: "errors.upstreamSchema.fix",
+}],
+```
+
+`status` and `retryable` are omitted because `UPSTREAM_SCHEMA_ERROR` is a
+registered code: the SDK already supplies 502 and non-retryable, and declaring
+a different value trips `error-code-status-conflicts-sdk` /
+`error-code-retryable-conflicts-sdk`. A declaration that carries only keys is
+still worth writing — it localizes every site that throws the code.
+
+Resolution order per field, evaluated at serve time:
+
+1. the throw site's `messageKey` / `fixKey`;
+2. the matching `errorCodes[]` entry's `messageKey` / `fixKey`;
+3. the derived `errors.<code>.message` / `errors.<code>.fix` (the code is used
+   verbatim as a catalog segment, so `errors.UPSTREAM_SCHEMA_ERROR.message`
+   works with no declaration at all);
+4. the English literal passed to the constructor.
+
+Each candidate is resolved in the caller's locale first and then in `en`, so a
+more specific key always beats a more specific locale. A missing key, a
+malformed key, a non-string catalog value or an absent catalog is a miss, never
+a throw: the caller always gets text. Steps 2 and 3 do not apply to SDK-owned
+failures (transport, Zod, stateful deadline, SDK runtime codes) — a provider
+catalog must not be able to relabel `Request timed out`.
+
+**Key grammar.** A locale key is dot-separated segments. Every segment is
+camelCase (`upstreamSchema`, `whenToUse`) or an array index (`0`), and the
+first segment is always a camelCase namespace. The one exception is the segment
+directly under `errors`, which may also be the error code spelled the way it is
+thrown — `errors.UPSTREAM_SCHEMA_ERROR.message`, `errors.BLOCKED.fix`,
+`errors.reauth_required.message`. Both spellings work, so
+`errors.upstreamSchema.message` and `errors.UPSTREAM_SCHEMA_ERROR.message` are
+equally legal keys; write the code form when you want the key to match the
+derived path in step 3. Nothing else loosens: a space, a dot inside a segment,
+an empty segment, a mixed-case or hyphenated code, and a leading digit are all
+still malformed.
+
+Locale negotiation reads `Accept-Language` from the request envelope's
+`headers` map first (the gateway stamps the flow's locale there) and then from
+the HTTP header, honours quality values, matches on the primary subtag, and
+supports `en`, `ko`, `ja` with `en` as the default. A request with no
+`Accept-Language` therefore keeps serving the `en` catalog value, so existing
+contract fixtures do not churn.
+
+**Interpolation.** `{name}` placeholders, `{{` and `}}` for literal braces.
+`params` accepts strings and finite numbers only. A placeholder with no usable
+param is left verbatim so the authoring gap is visible rather than silently
+deleting text.
+
+**Params are untrusted.** Upstream error text routinely ends up in `params`, so
+every string value is scrubbed before substitution: secrets and e-mail
+addresses redacted, control/bidi/newline characters encoded or collapsed,
+`<`, `>` and backticks removed, HTML-entity ampersands (`&lt;`) neutralized
+while ordinary ampersands survive, and the value capped at 200 characters.
+Substituted text is never rescanned, so a value containing `{other}` cannot
+trigger a second interpolation round. Prefer `details` when you need to relay
+an upstream body verbatim; `params` is for short, bounded values.
+
+**Catalog loading.** Catalogs are read once when the server is built (from the
+provider directory's `locales/{en,ko,ja}.json`, loading only the locales that
+exist). Pass `serve(provider, { localeCatalogs })` to bundle them instead. A
+catalog that exists but cannot be parsed logs one
+`provider_locale_catalogs_unavailable` warn at boot and every field falls back
+to its English literal.
+
+**Lint.** `apifuse check` reports:
+
+- `error-locale-key-missing` / `error-locale-key-malformed` (**error**) — a
+  literal `messageKey`/`fixKey`, on a throw site or on an `errorCodes[]` entry,
+  that `locales/en.json` does not resolve to non-empty text, or that is not a
+  legal locale dot path (see **Key grammar** above).
+- `thrown-error-message-not-localized` (**warn**) — a throw site whose declared
+  code has no key anywhere and no `errors.<code>.message` in `en`, so it is
+  served untranslated. Warning during the migration; promoted to error per
+  provider as each wave lands.
+
+`ko`/`ja` coverage needs no new rule: `en` is the baseline, so the existing
+catalog parity and placeholder checks already fail an `errors.*` key that is
+missing or untranslated in `ko`/`ja`.
+
 ### Declared secrets are SDK-enforced
 
 Environment/secret presence validation is single-sourced in the SDK. Declare
@@ -640,6 +893,69 @@ 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 (**warn** in
+this release; the level is raised once the fleet is clean):
+
+- `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.
+
+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 a warning.
+
+```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
@@ -678,6 +994,48 @@ redacted. If a login flow must consume a rotated credential from `Location`,
 inspect it inside `stopWhen`; that callback receives the real hop while callback
 failures are sanitized before propagation.
 
+### Request-bound proof headers
+
+When an upstream requires a single-use, request-bound header (DPoP proofs,
+HTTP message signatures, HMAC nonces), pass `headers` as a factory instead of a
+record. `ctx.http` calls it once per issued attempt with the resolved URL and
+method, so a managed retry sends a fresh proof rather than replaying the first
+one, and the request keeps proxy failover and the transient retry taxonomy:
+
+```ts
+const response = await ctx.http.get(requestUrl, {
+	headers: async ({ url, method }) => {
+		// RFC 9449 §4.2: `htu` is the target URI without query and fragment.
+		const htu = new URL(url);
+		htu.search = "";
+		htu.hash = "";
+		return {
+			...commonHeaders,
+			dpop: await createDpopProof(htu.toString(), method),
+		};
+	},
+});
+```
+
+`url` is the exact URL the attempt is issued against, including `params` and
+`sensitiveParams`. Bind to it instead of a URL you rebuild, but strip the query
+and fragment for fields that are defined without them (DPoP `htu`), and never
+log it or copy it verbatim into a signed field a verifier logs.
+
+Keep the factory fast and local. It runs after proxy resolution, so an already
+allocated egress endpoint and its lease are held while it is awaited; a remote
+signing round trip there can outlive the lease TTL. Mint locally, and set
+`timeout` on the call so a hung signer cannot hold the endpoint indefinitely.
+
+The factory is not invoked for redirect hops (they reuse the attempt's
+headers), for skipped duplicate proxy offsets, or for an attempt whose proxy
+allocation failed — those build no request, so `attempt` counts only the
+requests that are actually issued. A factory that throws fails the request with
+the non-retryable `TransportError` code `http_header_factory_failed`, which is
+classified as a provider-side fault (`provider_error`), not an upstream
+failure. `ctx.stealth` has its own `headers` option and does not accept a
+factory.
+
 ### Public local debugging checklist
 
 - Operation smoke requests use the provider server envelope:

package/CHANGELOG.md

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

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/README.md

@@ -78,6 +78,7 @@ The operation request body is the same envelope used by the APIFuse gateway:
 | `headers` | no | Extra caller headers to expose through `ctx.request.headers`. |
 | `connectionId` | no | Connection identity only; it does not include credentials. The gateway sends it for `optional` connection mode, and only when the caller supplied a connection that passed authorization. Exposed as `ctx.request.connectionId`. |
 | `connection` | no | Credential-bearing connection data. The gateway sends it for `required` connection mode; omit it for no-auth/public (`none` mode) operations. For local debugging, pass an object with `id`, `mode`, `secrets`, `metadata`, and `externalRef`. Do not pass `null`. |
+| `tenantId` | no | Gateway-asserted principal scope: the organization id for customer subjects, the service-account id for platform service accounts. Sent for every connection mode, including `none`; absent on direct calls and self-test. Exposed as `ctx.request.tenantId` (`undefined` when absent or empty). Caller headers never populate it. |
 
 The gateway sends only `connection` for `required` mode, only `connectionId`
 for `optional` mode (and nothing when the caller passed no connection), and

package/bin/apifuse-check.ts

@@ -15,6 +15,7 @@ import {
 	DECLARATION_INVALID_CODE,
 	validateFailClosedDeclaration,
 } from "../src/declaration-validation.js";
+import { redundantDeploymentDefaults } from "../src/cli/deployment-intent.js";
 import { isProviderError } from "../src/errors.js";
 import type { ProviderDefinition } from "../src/index.js";
 import { lintProviderWithInformation, type ProviderLintMode } from "../src/lint.js";
@@ -140,6 +141,7 @@ export async function runChecks(
 	}
 	const provider = assertProviderDefinition(providerModule?.default);
 	const providerSourceFiles = collectProviderSourceFiles(providerRoot);
+	const localeCatalogEn = readEnglishLocaleCatalog(providerRoot);
 
 	return [
 		checkIndex(indexPath, provider),
@@ -147,8 +149,9 @@ export async function runChecks(
 		checkOperations(provider),
 		checkFixtures(provider),
 		checkSchemas(provider),
-		checkAuthoringLint(provider, providerSourceFiles, options.lintMode),
+		checkAuthoringLint(provider, providerSourceFiles, localeCatalogEn, options.lintMode),
 		checkProviderMetadata(provider),
+		await checkDeploymentIntent(providerRoot, provider),
 		checkDockerfile(dockerfilePath),
 		checkPackageJson(packageJsonPath),
 		checkProviderJson(providerJsonPath, packageJsonPath),
@@ -367,9 +370,30 @@ function checkSchemas(provider: ProviderDefinition | undefined): CheckResult {
 	};
 }
 
+/**
+ * Reads `locales/en.json` so the error-localization lint rules can resolve
+ * declared `messageKey`/`fixKey` values. An absent or unreadable catalog is
+ * reported as an empty catalog rather than as "no catalog": a provider that
+ * references locale keys without shipping `en.json` must still fail the
+ * missing-key rule instead of silently skipping it.
+ */
+function readEnglishLocaleCatalog(providerRoot: string): Record<string, unknown> {
+	const catalogPath = resolve(providerRoot, "locales", "en.json");
+	if (!existsSync(catalogPath)) return {};
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(catalogPath, "utf8"));
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+			? (parsed as Record<string, unknown>)
+			: {};
+	} catch {
+		return {};
+	}
+}
+
 function checkAuthoringLint(
 	provider: ProviderDefinition | undefined,
 	providerSourceFiles: Record<string, string>,
+	localeCatalogEn: Record<string, unknown>,
 	lintMode: ProviderLintMode = "official",
 ): CheckResult {
 	if (!provider) {
@@ -380,7 +404,7 @@ function checkAuthoringLint(
 	}
 
 	const { diagnostics, information } = lintProviderWithInformation(
-		{ ...provider, providerSourceFiles },
+		{ ...provider, providerSourceFiles, localeCatalogEn },
 		{ mode: lintMode },
 	);
 	const errors = diagnostics.filter((diagnostic) => diagnostic.level === "error");
@@ -448,6 +472,64 @@ function checkProviderMetadata(provider: ProviderDefinition | undefined): CheckR
 	};
 }
 
+export const DEPLOYMENT_INTENT_CHECK_MESSAGE =
+	"Deployment intent lives only in defineProvider({ deployment }) without restating profile defaults";
+export const LEGACY_DEPLOY_FILE_RULE = "deployment/legacy-deploy-file";
+export const REDUNDANT_DEPLOYMENT_DEFAULT_RULE = "deployment/redundant-default";
+export const SPREAD_EXPORT_DEPLOYMENT_RULE = "deployment/spread-export";
+
+/**
+ * Deployment intent has one authored home: the `deployment` key on
+ * `defineProvider()`, carrying only the fields that differ from the runtime
+ * profile. A standalone `deploy.ts` is a legacy surface and a field that
+ * restates a profile default is noise the platform derives anyway. Both are
+ * reported as warnings while the fleet migrates (`apifuse
+ * migrate-deployment`); they become errors once no repository carries the
+ * legacy file.
+ */
+async function checkDeploymentIntent(
+	providerRoot: string,
+	provider: ProviderDefinition | undefined,
+): Promise<CheckResult> {
+	const details: string[] = [];
+	if (existsSync(resolve(providerRoot, "deploy.ts"))) {
+		details.push(
+			`WARN ${LEGACY_DEPLOY_FILE_RULE}: deploy.ts is a legacy deployment surface; run \`apifuse migrate-deployment .\` to move its non-default values into defineProvider({ deployment }) and delete the file.`,
+		);
+	}
+	// A `deployment` extra on `export default { ...provider, deployment }` is
+	// indistinguishable from a declaration key once the module is loaded, so
+	// inspect the source. The inspector needs the TypeScript compiler (a
+	// devDependency of provider repositories); without it this rule is skipped.
+	const indexPath = resolve(providerRoot, "index.ts");
+	if (existsSync(indexPath)) {
+		try {
+			const { findSpreadExportDeploymentProperty } = await import(
+				"../src/cli/migrate-deployment-intent.js"
+			);
+			const spread = findSpreadExportDeploymentProperty(readFileSync(indexPath, "utf8"), indexPath);
+			if (spread !== undefined) {
+				details.push(
+					`WARN ${SPREAD_EXPORT_DEPLOYMENT_RULE}: index.ts:${spread.line} attaches \`deployment\` to a spread default export; the only authored surface is the \`deployment\` key inside defineProvider({...}). Run \`apifuse migrate-deployment .\` to hoist it.`,
+				);
+			}
+		} catch {
+			// TypeScript unavailable: the source-shape rule cannot run here.
+		}
+	}
+	if (provider?.deployment !== undefined) {
+		for (const redundant of redundantDeploymentDefaults(provider.deployment)) {
+			details.push(`WARN ${REDUNDANT_DEPLOYMENT_DEFAULT_RULE}: ${redundant.message}`);
+		}
+	}
+	return {
+		message: DEPLOYMENT_INTENT_CHECK_MESSAGE,
+		// Warning-only during the fleet migration window.
+		passed: true,
+		details,
+	};
+}
+
 function checkDockerfile(dockerfilePath: string): CheckResult {
 	return {
 		message: "Dockerfile exists",