@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.50

package/CHANGELOG.md

@@ -1,5 +1,191 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.50
+
+- Release candidate for main commit 341c2f0e55a4159cac423fec0bf4f84625191731.
+
+## 2.2.0-beta.49
+
+- Release candidate for main commit 694b145f65c2c81e298c2516dde221ce19cb52da.
+
+## 2.2.0-beta.48
+
+- Release candidate for main commit ba6636fa8dd53a35af3091ae6efd797f5ef3d836.
+
+## 2.2.0-beta.47
+
+- Release candidate for main commit 0ff0c6c90153af3aab75978eb73040c9adaa2609.
+
+## 2.2.0-beta.46
+
+- Release candidate for main commit 0340fbc51b4ad71689bb1ec61b9b818dedda4587.
+
+## 2.2.0-beta.45
+
+- Release candidate for main commit 5d337d9fc1c77cd814ec7a4e1aa44ba0f8b2a5a9.
+
+## 2.2.0-beta.44
+
+- Release candidate for main commit a3091c0b4931c5ae48fe01b9776e4dc213db2716.
+
+## 2.2.0-beta.43
+
+- Release candidate for main commit 5b8b6048514fb500ead400495bd5e1ed8695ed6d.
+
+## 2.2.0-beta.42
+
+- Release candidate for main commit efbdbb409c9400e6211b061705b634e659f298bd.
+
+## 2.2.0-beta.41
+
+- Release candidate for main commit e1bde60e6a9e0424074a357afd9e8af56549080d.
+
+## 2.2.0-beta.40
+
+- Release candidate for main commit 7e2f05a954c23593a77e89e463a9bcbc2cdc7695.
+
+## 2.2.0-beta.39
+
+- Release candidate for main commit ecbe349c44e15c873b7c58b42e14610db029eb5f.
+
+## 2.2.0-beta.38
+
+- Release candidate for main commit 448775077dbc9ab907209f1feee4e6e4e5ef4283.
+
+## 2.2.0-beta.37
+
+- Release candidate for main commit aa14b268dffe1196f25c2b6b314598fe0896edec.
+
+## 2.2.0-beta.36
+
+- Release candidate for main commit c6858f8b87d78b3b755adeb28982e875434be406.
+
+## 2.2.0-beta.35
+
+- Release candidate for main commit 027fa0087b883a6281bc6d8bdaaf6d0be382000f.
+
+## 2.2.0-beta.34
+
+- Release candidate for main commit 383a97e7d0ce995d098d5f95c9ffdcbeed13de31.
+
+## 2.2.0-beta.33
+
+- Release candidate for main commit e7d854ec3e859702b22e2b37eaa2ae6bd4545c80.
+
+## 2.2.0-beta.32
+
+- Release candidate for main commit 82f1c0c1de916a40c8c74b1d6470a493b134c0ed.
+
+## 2.2.0-beta.31
+
+- Release candidate for main commit 94006be0852918867d254dc23d0fa8420a07be9c.
+
+## 2.2.0-beta.30
+
+- Release candidate for main commit ccf3d56bfcbe9683c6e7ad45dde8e6703467f9e7.
+
+## 2.2.0-beta.29
+
+- Release candidate for main commit b7243459ab12403e11d7b5b93292f09b734b0a96.
+
+## 2.2.0-beta.28
+
+- Release candidate for main commit 2936f1891d4e2326502f0585081f8a58060d6dd7.
+
+## 2.2.0-beta.27
+
+- Release candidate for main commit 579d9e7fd22d8414b151be2b71a43a0990456911.
+
+## 2.2.0-beta.26
+
+- Release candidate for main commit 924fe13d1101e7840d799a562a7a70174355185d.
+
+## 2.2.0-beta.25
+
+- Release candidate for main commit e6df658b95c0728b671fd221919ec2f85f82b0b7.
+
+## 2.2.0-beta.24
+
+- Release candidate for main commit 0f21a2959dcbb9b96fe426259259d0870cfc537f.
+
+## 2.2.0-beta.23
+
+- Release candidate for main commit 36b3bedc9c14913c4152c4631cc87de71062f21f.
+
+## 2.2.0-beta.22
+
+- Release candidate for main commit b8bf920b5ca053d1bf43018167fd4eedff01700d.
+
+## Unreleased
+
+- Server-stored provider choices now issue word-format tokens unconditionally. The runtime issuance setting and legacy issuance path were removed.
+- **Breaking:** Legacy encrypted server-handle choice tokens are no longer parsed. They are rejected with the uniform choice-not-found error; server-stored choices are now word-only. Encrypted inline choice tokens remain supported.
+- Added the `thrown-error-code-undeclared` authoring lint (warning level): `apifuse check` now statically flags literal `ProviderError`/`ValidationError` codes that are neither SDK-registered nor declared in any operation's `docs.errorCodes`, surfacing the runtime `unregistered_provider_error_code` signal at check time. The canonical SDK code→status mapping moved to `SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES` in `error-resolution.ts`, shared by the runtime status resolver and the lint.
+
+## 2.2.0-beta.21
+
+- Release candidate for main commit 00f61024fb18db39711dc5076c4621508baa49f5.
+
+## 2.2.0-beta.20
+
+- Release candidate for main commit 8043d2ef0047e431aace750d8abca2e1149ec1d6.
+
+## 2.2.0-beta.19
+
+- Release candidate for main commit fd93ae68d0472fae68d908312249163373ec5d22.
+
+## 2.2.0-beta.18
+
+- Release candidate for main commit cebaf4b994918d2641c0fe6681fbffd3a3284c5d.
+
+## 2.2.0-beta.17
+
+- Release candidate for main commit 5a0f9127a5861992d5c144b07ad379a085756544.
+
+## 2.2.0-beta.16
+
+- Release candidate for main commit c5deb2bc31a4a4a236d27a2ce3d214b533ed358f.
+
+## 2.2.0-beta.15
+
+- Release candidate for main commit b5ebd25e48f6502e4ddb775d4e0a25f5c8276712.
+
+## 2.2.0-beta.14
+
+- Release candidate for main commit 3491acd253ca17b517985e8a618f1c2904a664a9.
+
+## 2.2.0-beta.13
+
+- Release candidate for main commit 75e840d0614aea3b99a1e5cef4f93f8cdccf0507.
+
+## 2.2.0-beta.12
+
+- Release candidate for main commit c66789c4745c72fc94ad3c10b3e0d7e5ed83fd25.
+
+## 2.2.0-beta.11
+
+- Release candidate for main commit f6f739bd5265afe714bbace9900edc2695fcf826.
+
+## 2.2.0-beta.10
+
+- Release candidate for main commit c41bd919739e0293ae8fa4d72a8a32f034cef4b8.
+
+## 2.2.0-beta.9
+
+- Release candidate for main commit 5c78c8b (bundles #67 nodemaven required-secret + #68 transport vendor-advance).
+
+## 2.2.0-beta.8
+
+- Release candidate for main commit 9e8a3f028ee78b9cab29d4aa3f5494ac9cffa65f.
+
+## 2.2.0-beta.7
+
+- Release candidate for main commit 2ce4ea4bd36ce333eba8b3b474bf6e82b5e9216c.
+
+## 2.2.0-beta.6
+
+- Release candidate for main commit 17f4e41d44efe7c148ef875b950be4f2c7df1294.
+
 ## 2.2.0-beta.5
 
 - Release candidate for main commit 82fa14e99a9af7edd44e3196aa3f4e87b4699edf.
@@ -50,8 +236,22 @@
 
 ## Unreleased
 
+- Upstream the platform monorepo's beta.16 dist patch: OAuth2-proxied auth ceremony (`createOAuth2ProxiedStart`, `OAUTH2_PROXIED_PKCE_VERIFIER_KEY`, `APIFUSE__AUTH_PROXY__URL` origin key, proxied redirect/callback turns) and the provider runtime state upgrades it depends on (in-memory compareAndSet with quota-aware write policy, Redis CAS/set Lua scripts with entry quotas and legacy index migration). The monorepo drops `patchedDependencies` once it pins this release.
+- **honest-provider-error-contract (phase 2):** `UPSTREAM_REJECTED` is a registered code family serving HTTP 409 with `retryable: false` — deterministic upstream business refusals are no longer 502s. Operation-declared `docs.errorCodes` may now use 409/410/422. Public error envelopes carry a `source` field (`client` | `upstream_rule` | `upstream_failure` | `apifuse`) derived from the observability category. Taxonomy version bumps to `2026-08-07` with the `upstream_rejected`, `dependency_unavailable`, `unsupported_transport`, and `client_cancelled` categories (409/410/422 map to `upstream_rejected`), matching the platform monorepo SoT. The `unregistered_provider_error_code` signal now carries a `signalFix` pointing at `docs.errorCodes` declaration.
+- **Breaking for custom native gateway adapters:** `NativeGatewayProxySynthesisInput` now includes an injected `credentials` resolver and selected `protocol`; synthesizers may return promises and structured skip reasons, and `resolveNativeGatewayProxy` is async. Default callers retain env-backed behavior. Native transport now supports both HTTP CONNECT and SOCKS5, defaults per vendor with an explicit runtime override, registers smartproxy allocation ahead of nodemaven when declared in that order, and reports every exhausted vendor reason without exposing proxy credentials.
+- Honor operation `docs.errorCodes` at runtime: declared provider-owned statuses and retryability now drive the HTTP envelope, observability header, and structured log; invalid statuses fail `defineProvider`, declared codes no longer emit the unregistered-code signal, and `TransportError` status-preservation workarounds are obsolete.
+- Add an opt-in same-origin redirect hop policy to `ctx.http`, with bounded manual following and typed failures before a refused target is requested.
+- Enforce provider-declared native TCP/TLS egress before proxy or socket setup, with revocable and expiring dynamic grants plus typed authorization failures; providers without a native egress declaration retain legacy behavior.
+- **Breaking:** Provider error `details` is now passed through verbatim; SDK observability fields (`category`, `taxonomyVersion`, `upstreamStatus`, and derived `retryable`) are no longer merged into the public body. Emitted error envelopes now require top-level `retryable`, while inbound stateful forwarding tolerates an older owner response that omits it and defaults it to `false`. The removed observability metadata is available in the new `X-ApiFuse-Error-Observability` response header.
+- Unregistered `ProviderError` codes now default to HTTP 500 instead of 400 and emit an `unregistered_provider_error_code` structured-log signal; registered mappings remain unchanged and take precedence over the HTTP 400 fallback for unregistered input `ValidationError` codes.
+- Add an opt-in native connection idle read timeout with a typed error, independently from TCP/SOCKS/TLS establishment deadlines.
+- Add opt-in `maxBodyBytes` enforcement to stealth fetches and redirect hops, aborting oversized decoded response streams with `response_too_large`.
+- Resolve relative date tokens in fixture requests before input-schema validation, add KST capture-date `fixtures.recordedAt` metadata, and support explicit KST/UTC calendars in the shared health-input resolver.
+- Add opt-in `runStandardTests(provider, { upstreamStub })` real-handler E2E coverage with strict offline transport stubs, output-schema validation, and per-operation warnings when handler E2E is not enabled.
+- Export native-network and request-file TypeScript contracts from the package root and `./provider`, including typed native provider declarations and optional runtime capabilities on provider/auth contexts.
 - Add `arrayBuffer()` and `bytes()` to `HttpResponse` so `ctx.http` consumers can read binary-safe upstream bodies; internal response handling is now byte-first.
 - Preserve identity-only operation `connectionId` values in `ProviderContext` without requiring credential material.
+- Accept and validate `proxy.session.drainLeadSeconds` in `defineProvider`, so providers can actually declare the native sticky-expiry drain lead time the type surface already exposed; a non-positive value, or one that meets or exceeds the sticky lifetime, is rejected at define time.
 
 ## 2.1.0-beta.15
 
@@ -107,7 +307,7 @@
 
 ## 2.1.0-beta.3
 
-- Replace the legacy TypeScript request transport with `ctx.stealth`, backed by `impit` browser-grade TLS/HTTP2 impersonation without Python runtime dependencies.
+- Replace the legacy TypeScript request transport with `ctx.stealth`, backed by browser-grade TLS/HTTP2 impersonation without Python runtime dependencies.
 - Add the public `apifuse submit-check` / `apifuse bounty-check` CLI for score-based pre-submission provider quality checks.
 - Ship `SUBMISSION.md` in the npm package so bounty contributors can follow the checklist without access to the private monorepo.
 - Include submit-check in generated provider validation scripts and packed-artifact smoke coverage.

package/README.md

@@ -119,7 +119,11 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   local-only values through `connection.secrets`. Read them in handlers with
   `ctx.credential.get("key")` or `ctx.credential.getAccessToken()`.
 - **Provider env secrets**: declare `secrets[]`, set values in your shell or
-  `.env`, and read only those names through `ctx.env.get("NAME")`.
+  `.env`, and read only those names through `ctx.env.get("NAME")`. The SDK
+  enforces presence of `required: true` declarations before handlers and auth
+  flows run, failing the invocation with a structured `MISSING_SECRET` error
+  (HTTP 400, category `credential_unavailable`) — do not re-check presence in
+  handlers.
 - **Credentials auth flows**: prefer `defineCredentialsAuth()` over hand-written
   `auth.flow`. Declare the form fields and credential keys once, then put the
   upstream login/session creation in `login(ctx, input)`. Return
@@ -133,15 +137,59 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   `context` object.
 - **Stealth-sensitive providers**: use `ctx.http` for normal JSON/REST calls and
   `ctx.stealth.fetch()` when you need browser-like session or cookie control.
-  `ctx.stealth.fetch()` uses the impit-backed browser stealth transport and
-  accepts request controls for `params`, `proxy`, `timeout`, `profile`,
-  `redirect`, `throwOnHttpError`, and `stealth.insecureSkipVerify`. For login
+  `ctx.stealth.fetch()` uses the `wreq-js`-backed browser stealth transport and
+  accepts request controls for `params`, `sensitiveParams`, `proxy`, `timeout`,
+  `maxBodyBytes`, `redirect`, `throwOnHttpError`, and
+  `stealth.insecureSkipVerify`. For login
   flows that must inspect intermediate `Location`/`Set-Cookie` headers, create
   a session with `ctx.stealth.createSession()` and use `session.redirects.run()`;
   inspect accumulated cookies through `session.cookies`. Select an SDK stealth
-  `profile` such as `chrome-146`; do not tune JA3, HTTP/2 SETTINGS, or
-  pseudo-header order in provider code. Chrome/Firefox-style profiles are
-  supported; use `ctx.browser` when Safari-specific behavior is required.
+  identity with structured `stealth: { browser, os }` options; omitted `os`
+  explicitly defaults to `macos`. Do not pin a browser version
+  or tune JA3, HTTP/2 SETTINGS, or
+  pseudo-header order in provider code. Chrome, Firefox, and Safari profiles
+  are supported; use `ctx.browser` when the provider needs browser execution.
+- **Query-parameter credentials**: when an upstream requires a credential in
+  its URL query, pass it through `sensitiveParams`, not `params` and never a
+  hand-built URL. It is sent as a normal query parameter while the SDK redacts
+  its value from transport errors, traces, and recorded fixtures:
+
+  ```ts
+  const response = await ctx.http.get("/openapi/service", {
+    params: { page: 1 },
+    sensitiveParams: { serviceKey: ctx.env.get("APIFUSE__PROVIDER__EXAMPLE__API_KEY")! },
+  });
+  ```
+
+  Use this only when the upstream offers no header or body credential channel.
+  Declared query-key positions and exact scalar diagnostics are always redacted.
+  Free-text values of four or more characters are redacted as substrings; shorter
+  values require token boundaries so low-entropy values do not corrupt unrelated
+  words or timestamps. Consequently, a sub-four-character secret embedded in a
+  larger alphanumeric token can remain in free text; prefer higher-entropy or
+  non-query credentials when possible. `sensitiveParams: {}` is equivalent to
+  omitting the option. Redirect results structurally redact declared keys and
+  common response-only credential keys from hop URLs; use
+  `redirects.run({ stopWhen })` to inspect a real intermediate `Location` during
+  the run when a login flow needs a rotated value.
+- **Proxy URLs for non-stealth consumers**: use `resolveProxy()` when a
+  provider-owned client outside `ctx.stealth` needs the provider's proxy, such
+  as a CAPTCHA solver that must use matching egress. Pass the provider proxy
+  policy used by the provider and consume the returned `url`; the SDK owns
+  vendor selection, allocation, failover, and URL formats. Never call proxy
+  allocator APIs or hardcode proxy vendor hostnames in provider code.
+
+  ```ts
+  import { resolveProxy } from "@apifuse/provider-sdk"
+
+  const resolvedProxy = await resolveProxy({
+    proxyPolicy,
+    affinityKey: connectionId,
+  })
+
+  if (!resolvedProxy.url) throw new Error("This login requires proxy egress")
+  const captchaTask = { proxy: resolvedProxy.url }
+  ```
 - **Browser providers**: for TypeScript Providers use `runtime: "browser"` plus
   `browser.engine: "playwright-stealth"`; `nodriver` is a Python-runtime path.
   Install local browser assets with `bunx playwright install chromium` when
@@ -150,12 +198,29 @@ the bad request path; provider/runtime failures include `code`, `message`, and
 
 ## Authoring ergonomics
 
-`defineProvider()` infers each operation handler input from the operation `input` schema. For larger providers, factor operations with `defineOperation()` and compose them later:
+`defineProvider()` establishes the capability declaration before its returned
+builder contextually types operations. For larger providers, export the derived
+context once and use it with `defineOperation()` in separate files:
 
 ```ts
-import { defineOperation, defineProvider, z } from "@apifuse/provider-sdk/provider"
+import {
+  defineOperation,
+  defineProvider,
+  type ProviderContextOf,
+  z,
+} from "@apifuse/provider-sdk/provider"
+
+const buildProvider = defineProvider({
+  id: "factored-provider",
+  version: "1.0.0",
+  runtime: "standard",
+  meta: { displayName: "Factored", category: "demo" },
+})
 
-const search = defineOperation({
+export type ProviderContext = ProviderContextOf<typeof buildProvider>
+
+const search = defineOperation<ProviderContext>()({
+  riskClass: "read",
   input: z.object({ q: z.string().describe("Search query") }),
   output: z.object({ count: z.number().describe("Result count") }),
   async handler(ctx, input) {
@@ -166,11 +231,7 @@ const search = defineOperation({
   },
 })
 
-export default defineProvider({
-  id: "factored-provider",
-  version: "1.0.0",
-  runtime: "standard",
-  meta: { displayName: "Factored", category: "demo" },
+export default buildProvider({
   operations: { search },
 })
 ```
@@ -207,17 +268,17 @@ healthCheck: {
 }
 ```
 
-### Operation annotations
+### Flat operation metadata
 
-Operations declare non-functional metadata via `annotations`:
+Operations declare access, safety, and execution metadata directly on the
+operation. `riskClass` is required and is the safety source of truth:
 
 | Field | Type | Notes |
 |---|---|---|
-| `readOnly` | `boolean` | Operation has no side effects (safe to test in production). |
-| `destructive` | `boolean` | Operation modifies/deletes state. |
-| `idempotent` | `boolean` | Safe to retry without duplicate side effects. |
-| `openWorld` | `boolean` | Callable without authentication. |
-| `rateLimit` | `{ calls, window }` | Per-operation rate hint. `window` is `"minute"\|"hour"\|"day"`. |
+| `riskClass` | `"read" \| "write" \| "destructive" \| "external-send"` | Required safety classification. |
+| `approval` | `"never" \| "risk-based" \| "always"` | Optional override; omit when it matches the risk-class default. |
+| `connectionMode` | `"none" \| "optional" \| "required"` | Access requirement. Required by lint for credential-bearing providers. |
+| `connectionExternalRefParam` | `string` | Public argument used to resolve a Connection. |
 | `timeoutMs` | `number` | Per-operation upstream timeout (1–60000 ms). Omit to inherit the gateway global default. |
 
 `defineProvider()` validates `timeoutMs` is an integer in `[1, 60000]` and throws `ValidationError` otherwise. The gateway applies the value via `context.WithTimeout` on every proxied call and clamps defensively to the same bound.

package/SUBMISSION.md

@@ -28,7 +28,7 @@ The score is a triage aid, not a payout guarantee. Maintainers still review corr
 | Category | Points | Examples |
 |---|---:|---|
 | Definition & metadata | 15 | `defineProvider`, package, Dockerfile, SDK structural checks |
-| Operations & schemas | 15 | strong descriptions, annotations, input/output schemas |
+| Operations & schemas | 15 | locale-keyed descriptions, explicit risk classes, input/output schemas |
 | Fixtures & tests | 15 | bidirectional fixtures that parse against schemas |
 | Health coverage | 15 | real `healthCheck` or specific `healthCheckUnsupported.reason` |
 | Runtime/local smoke | 10 | `/health` and at least one `POST /v1/{operation}` note |
@@ -50,7 +50,7 @@ Fix all blockers before submitting:
 - High-confidence secret or token material in source, README, package metadata, or fixtures.
 - SDK-native source blockers: prefixed Provider ids, `vendor/` SDK shims or imports, raw `.describe()` prose instead of `describeKey`, raw global `fetch()` calls, and excessive `as Type` assertions.
 
-Warnings do not fail the command, but they should be addressed when practical. For example, the generated starter `ping` operation warns because it is not a real upstream-backed bounty Operation. SDK-native warnings also flag moderate `as Type` assertion counts and credentialed Providers that never reference `ctx.credential`.
+Warnings do not fail the command, but they should be addressed when practical. For example, the generated starter `ping` operation warns because it is not a real upstream-backed bounty Operation. SDK-native warnings also flag moderate `as Type` assertion counts, credentialed Providers that never reference `ctx.credential`, and provider-local re-validation of declared env secrets (`sdk-owned-secret-presence`, 0 points): the SDK already rejects invocations with a structured `MISSING_SECRET` error when a declared `required: true` secret is unset, so `requireServiceKey`-style presence guards are deprecated dead weight — delete the guard and read the value directly with `ctx.env.get()`, or acknowledge a deliberate exception with `// @apifuse-allow sdk-owned-secret-presence: <reason>`.
 
 ## Measured local smoke
 

package/bin/apifuse-check.ts

@@ -6,8 +6,18 @@ import { pathToFileURL } from "node:url";
 
 import { z } from "zod";
 
+import {
+	formatPromptAssetIssues,
+	PROMPT_ASSET_SYNC_REMEDIATION,
+	verifyPromptAssets,
+} from "../src/cli/prompt-assets.js";
+import {
+	DECLARATION_INVALID_CODE,
+	validateFailClosedDeclaration,
+} from "../src/declaration-validation.js";
+import { isProviderError } from "../src/errors.js";
 import type { ProviderDefinition } from "../src/index.js";
-import { lintProvider, type ProviderLintMode } from "../src/lint.js";
+import { lintProviderWithInformation, type ProviderLintMode } from "../src/lint.js";
 import { safeParseSchemaSync } from "../src/schema.js";
 
 const HELP_TEXT = `Usage: apifuse check [path]
@@ -61,7 +71,7 @@ function normalizeArgs(argv: string[]): string[] {
 	return argv[0] === "check" ? argv.slice(1) : argv;
 }
 
-function resolveProviderRoot(inputPath: string): string {
+export function resolveProviderRoot(inputPath: string): string {
 	const resolvedInput = resolveFromParents(inputPath);
 
 	if (!existsSync(resolvedInput)) {
@@ -113,15 +123,27 @@ export async function runChecks(
 	const indexPath = resolve(providerRoot, "index.ts");
 	const dockerfilePath = resolve(providerRoot, "Dockerfile");
 	const packageJsonPath = resolve(providerRoot, "package.json");
-
-	const providerModule = existsSync(indexPath)
-		? await import(pathToFileURL(indexPath).href)
-		: undefined;
+	const providerJsonPath = resolve(providerRoot, "provider.json");
+
+	let providerModule: Record<string, unknown> | undefined;
+	let providerImportError: unknown;
+	if (existsSync(indexPath)) {
+		try {
+			providerModule = (await import(pathToFileURL(indexPath).href)) as Record<string, unknown>;
+		} catch (error) {
+			if (isProviderError(error) && error.code === DECLARATION_INVALID_CODE) {
+				providerImportError = error;
+			} else {
+				throw error;
+			}
+		}
+	}
 	const provider = assertProviderDefinition(providerModule?.default);
 	const providerSourceFiles = collectProviderSourceFiles(providerRoot);
 
 	return [
 		checkIndex(indexPath, provider),
+		checkDeclaration(provider, providerImportError),
 		checkOperations(provider),
 		checkFixtures(provider),
 		checkSchemas(provider),
@@ -129,9 +151,70 @@ export async function runChecks(
 		checkProviderMetadata(provider),
 		checkDockerfile(dockerfilePath),
 		checkPackageJson(packageJsonPath),
+		checkProviderJson(providerJsonPath, packageJsonPath),
+		checkPromptAssets(providerRoot),
 	];
 }
 
+const DECLARATION_CHECK_MESSAGE = "Provider declaration passes fail-closed validation";
+
+function checkDeclaration(
+	provider: ProviderDefinition | undefined,
+	importError: unknown,
+): CheckResult {
+	if (importError !== undefined) {
+		return {
+			message: DECLARATION_CHECK_MESSAGE,
+			passed: false,
+			details: formatDeclarationError(importError),
+		};
+	}
+	if (!provider) return { message: DECLARATION_CHECK_MESSAGE, passed: false };
+	try {
+		validateFailClosedDeclaration(provider);
+		return { message: DECLARATION_CHECK_MESSAGE, passed: true };
+	} catch (error) {
+		return {
+			message: DECLARATION_CHECK_MESSAGE,
+			passed: false,
+			details: formatDeclarationError(error),
+		};
+	}
+}
+
+function formatDeclarationError(error: unknown): string[] {
+	if (isProviderError(error) && error.code === DECLARATION_INVALID_CODE) {
+		const details = error.details;
+		if (isRecord(details) && Array.isArray(details.violations)) {
+			return details.violations.map((violation) => {
+				if (!isRecord(violation)) return String(violation);
+				const ruleId = typeof violation.ruleId === "string" ? violation.ruleId : "unknown-rule";
+				const path = typeof violation.path === "string" ? violation.path : "unknown-path";
+				const message = typeof violation.message === "string" ? `: ${violation.message}` : "";
+				const fix = typeof violation.fix === "string" ? ` Fix: ${violation.fix}` : "";
+				return `${path} [${ruleId}]${message}${fix}`;
+			});
+		}
+	}
+	return [error instanceof Error ? error.message : String(error)];
+}
+
+export const PROMPT_ASSETS_CHECK_MESSAGE =
+	"Agent prompt assets match the installed SDK version";
+
+function checkPromptAssets(providerRoot: string): CheckResult {
+	const verification = verifyPromptAssets(providerRoot);
+	if (verification.ok) {
+		return { message: PROMPT_ASSETS_CHECK_MESSAGE, passed: true };
+	}
+
+	return {
+		message: PROMPT_ASSETS_CHECK_MESSAGE,
+		passed: false,
+		details: [...formatPromptAssetIssues(verification), PROMPT_ASSET_SYNC_REMEDIATION],
+	};
+}
+
 function isScannableProviderSourceFile(relativePath: string): boolean {
 	return (
 		/\.(?:ts|tsx|js|jsx|mjs|cjs|sh|bash)$/.test(relativePath) ||
@@ -142,6 +225,9 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 
 function collectProviderSourceFiles(providerRoot: string): Record<string, string> {
 	const sources: Record<string, string> = {};
+	// `.agents`/`.apifuse` are deliberately not skipped: managed content there
+	// is markdown/JSON (never matched by isScannableProviderSourceFile), and a
+	// planted `.ts`/`.sh` under those directories must stay in scanner scope.
 	const skipDirectories = new Set([".git", "node_modules", "dist", "build", ".next"]);
 	const visit = (directory: string) => {
 		for (const entry of readdirSync(directory, { withFileTypes: true })) {
@@ -293,12 +379,21 @@ function checkAuthoringLint(
 		};
 	}
 
-	const diagnostics = lintProvider({ ...provider, providerSourceFiles }, { mode: lintMode });
+	const { diagnostics, information } = lintProviderWithInformation(
+		{ ...provider, providerSourceFiles },
+		{ mode: lintMode },
+	);
 	const errors = diagnostics.filter((diagnostic) => diagnostic.level === "error");
-	const details = diagnostics.map((diagnostic) => {
-		const field = diagnostic.field ? `${diagnostic.field}: ` : "";
-		return `${diagnostic.level.toUpperCase()} ${diagnostic.rule} ${field}${diagnostic.message}`;
+	const details = information.map((entry) => {
+		const field = entry.field ? `${entry.field}: ` : "";
+		return `INFO ${entry.rule} ${field}${entry.message}`;
 	});
+	details.push(
+		...diagnostics.map((diagnostic) => {
+			const field = diagnostic.field ? `${diagnostic.field}: ` : "";
+			return `${diagnostic.level.toUpperCase()} ${diagnostic.rule} ${field}${diagnostic.message}`;
+		}),
+	);
 
 	return {
 		message: "Provider authoring lint has no error-level diagnostics",
@@ -394,6 +489,65 @@ function checkPackageJson(packageJsonPath: string): CheckResult {
 	}
 }
 
+export const PROVIDER_JSON_CHECK_MESSAGE = "provider.json exists with a valid declaration";
+
+const providerDeclarationSchema = z
+	.object({
+		schemaVersion: z.literal(1),
+		providerId: z.string(),
+		owner: z.string(),
+		lifecycle: z.enum(["draft", "ready", "live", "retired"]),
+	})
+	.strict();
+
+function checkProviderJson(providerJsonPath: string, packageJsonPath: string): CheckResult {
+	if (!existsSync(providerJsonPath)) {
+		return {
+			message: PROVIDER_JSON_CHECK_MESSAGE,
+			passed: false,
+			details: ["Missing provider.json at the provider root"],
+		};
+	}
+
+	try {
+		const declaration = providerDeclarationSchema.parse(
+			JSON.parse(readFileSync(providerJsonPath, "utf-8")) as unknown,
+		);
+		const expectedProviderId = readProviderIdFromPackageName(packageJsonPath);
+		if (expectedProviderId !== undefined && declaration.providerId !== expectedProviderId) {
+			return {
+				message: PROVIDER_JSON_CHECK_MESSAGE,
+				passed: false,
+				details: [
+					`provider.json providerId "${declaration.providerId}" does not match package.json name (expected "${expectedProviderId}")`,
+				],
+			};
+		}
+
+		return {
+			message: PROVIDER_JSON_CHECK_MESSAGE,
+			passed: true,
+			details: [`providerId: ${declaration.providerId}`, `lifecycle: ${declaration.lifecycle}`],
+		};
+	} catch (error) {
+		return {
+			message: PROVIDER_JSON_CHECK_MESSAGE,
+			passed: false,
+			details: [error instanceof Error ? error.message : String(error)],
+		};
+	}
+}
+
+function readProviderIdFromPackageName(packageJsonPath: string): string | undefined {
+	try {
+		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as unknown;
+		if (!isRecord(packageJson) || typeof packageJson.name !== "string") return undefined;
+		return /^(?:apifuse-provider-|@apifuse\/provider-)(.+)$/.exec(packageJson.name)?.[1];
+	} catch {
+		return undefined;
+	}
+}
+
 function assertProviderDefinition(value: unknown): ProviderDefinition | undefined {
 	return isProviderDefinition(value) ? value : undefined;
 }
@@ -406,7 +560,7 @@ function isProviderDefinition(value: unknown): value is ProviderDefinition {
 	return (
 		typeof value.id === "string" &&
 		typeof value.version === "string" &&
-		(value.runtime === "standard" || value.runtime === "browser") &&
+		(value.runtime === "standard" || value.runtime === "shared" || value.runtime === "browser") &&
 		typeof value.meta.displayName === "string" &&
 		typeof value.meta.category === "string"
 	);