@apifuse/provider-sdk 2.1.0-beta.1 → 2.1.0-beta.10

package/AUTHORING.md

@@ -1,7 +1,7 @@
 ## Generator and runtime alignment
 
 - Canonical scaffolding command: `apifuse create`
-- Monorepo contributors should use `apifuse create <name> --preset monorepo`
+- External bounty workspaces are one-provider repositories initialized with the standalone create flow. `--preset monorepo` is an internal APIFuse maintainer path only and must reject outside the private monorepo detected by `packages/provider-sdk/package.json`.
 - Standalone bounty contributors should use `bunx @apifuse/provider-sdk@beta create <name> --yes` until this release is promoted to `latest`
 - Provider server contract is:
   - dev default `3900`
@@ -47,12 +47,36 @@ description:
 - `description` — 150+ chars English (error-level rule)
 - Every Zod field in input AND output has `.describe()` including nested objects + array items (error-level rule)
 - `fixtures.request` + `fixtures.response` both present (error-level rule)
-- Exactly one of `healthCheck` or `healthCheckUnsupported` per operation. Prefer `healthCheck` for safe read-only upstream probes; use `healthCheckUnsupported` only with a specific reason for destructive, paid, credential-sensitive, flaky, or otherwise unsafe probes.
+- Exactly one of `healthCheck`, `healthCheckUnsupported`, or `healthJourneys[].coversOperations` coverage per operation. Prefer `healthCheck` for safe read-only upstream probes; use `healthCheckUnsupported` only with a specific reason for destructive, paid, credential-sensitive, flaky, or otherwise unsafe probes. Use a provider-level health journey when a destructive or credential-sensitive flow can be proven safely only as a multi-step boundary test, such as stopping at a payment WebView URL.
 
 ### Factored operations
 
 Use `defineOperation()` when an operation is large enough to live beside helper functions or in a separate module. It preserves the same type inference as inline `defineProvider()` operations and can be placed directly in the provider `operations` map. `defineProvider()` accepts Zod and Standard Schema v1-compatible schemas. If config validation fails, the SDK names the field to fix, for example `runtime`, `auth.mode`, `operations.<id>.handler`, or `operations.<id>.fixtures.response`.
 
+### Health assertion context
+
+`healthCheck.cases[].assertions` receives a `HealthCheckAssertionContext` with
+`data`, `status`, `durationMs`, and optional `meta`. `data` is typed from the
+operation output schema, so assertions should inspect normalized output instead
+of reaching into transport internals.
+
+<!-- @magic-start:sample -->
+```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" };
+      }
+    },
+  }],
+}
+```
+<!-- @magic-end:sample -->
+
 ### Strongly recommended (warn-level rules)
 
 - `description` includes "use" AND "when" phrasing
@@ -65,6 +89,158 @@ Use `defineOperation()` when an operation is large enough to live beside helper
 - `tags`: operation-level semantic tags for retrieval (e.g., `["weather", "korea", "realtime"]`)
 - `relatedOperations`: `{ alternatives?: string[] }` — links to fallback/sibling operations
 
+### STT runtime capability for audio OTP and short transcription
+
+Providers that need speech-to-text should use the SDK runtime capability instead
+of constructing a vendor client inside provider code. Declare STT at the provider
+level, then call `ctx.stt` from operation handlers or auth-flow handlers.
+
+<!-- @magic-start:sample -->
+```ts
+export default defineProvider({
+  id: "example-provider",
+  // ...metadata, auth, operations, allowedHosts
+  stt: { mode: "required" },
+  operations: {
+    verifyAudioOtp: {
+      input: z.object({
+        audioBase64: z.string().describe("Base64-encoded short OTP audio"),
+        mediaType: z.string().optional().describe("Audio MIME type"),
+      }),
+      output: z.object({ code: z.string().describe("Verification code") }),
+      async handler(ctx, input) {
+        const transcript = await ctx.stt.transcribe({
+          audio: {
+            kind: "base64",
+            data: input.audioBase64,
+            mediaType: input.mediaType,
+          },
+          language: "ko-KR",
+          mode: "otp",
+          verificationCode: { codeLengths: [4, 6] },
+        });
+
+        const code =
+          transcript.verificationCode?.code ??
+          ctx.stt.extractVerificationCode(transcript.text, {
+            locale: "ko-KR",
+            codeLengths: [4, 6],
+          }).code;
+
+        return { code };
+      },
+      healthCheckUnsupported: {
+        reason: "Audio OTP transcription is cost-bearing and requires explicit smoke evidence.",
+      },
+    },
+  },
+});
+```
+<!-- @magic-end:sample -->
+
+Best-practice rules:
+
+- `stt: { mode: "required" }` is the production path for providers that depend
+  on STT; APIFuse provider manifests project STT credentials, model config, and
+  Cloudflare egress only for required STT. Use `mode: "optional"` only when STT
+  is a host/test override or truly best-effort capability that can remain
+  unavailable in production.
+- Do not assume OTPs are always four digits. Configure accepted lengths, for
+  example `[4, 6]`, and keep the returned code as a string to preserve leading
+  zeros.
+- Prompts are hints, not correctness guarantees. General transcription sends no
+  prompt by default. OTP mode may send a default digit-preserving hint. Use a
+  custom `initialPrompt` only with `promptPolicy: "custom-hint"`, and do not log
+  prompts, transcripts, raw audio, or OTP values.
+- STT v1 accepts JSON-safe base64 audio only. Do not fetch arbitrary audio URLs
+  from provider code; URL input needs separate SSRF/private-network policy.
+- Local and production wiring use the same env-backed runtime path. For the
+  Cloudflare Workers AI backend, set `APIFUSE__STT__BACKEND=cloudflare-workers-ai`,
+  `APIFUSE__STT__MODEL=@cf/openai/whisper-large-v3-turbo`,
+  `APIFUSE__CLOUDFLARE__ACCOUNT_ID`, and `APIFUSE__STT__CLOUDFLARE_API_TOKEN` in `.env.local` or the
+  provider workload environment. Do not deploy a Cloudflare Worker proxy for the
+  MVP; the SDK runtime calls Workers AI REST directly.
+- Submission checks and health checks must not invoke live STT by default.
+  Provide explicit smoke evidence when a provider depends on audio OTP behavior.
+
+
+### Health journey DX for SMS/payment flows
+
+Use `defineSmsOtpMatcher()` plus `defineHealthJourney()` when a real health signal requires an OTP ceremony and a safe handoff boundary. Keep matcher fields standards-backed: ISO 3166-1 alpha-2 `country`, BCP 47 `locale`, E.164 `phoneNumber` when present, ISO 8601 durations, and `nationalServiceCode` origins for local service senders. Do not add custom allowlist fields such as `senderAllowlist`; model the sender as an origin instead.
+
+<!-- @magic-start:sample -->
+```ts
+import {
+	defineHealthJourney,
+	defineProvider,
+	defineSmsOtpMatcher,
+	every,
+} from "@apifuse/provider-sdk";
+
+const phoneOtp = defineSmsOtpMatcher({
+	id: "phone-otp",
+	country: "KR",
+	locale: "ko-KR",
+	origins: [
+		{
+			kind: "nationalServiceCode",
+			country: "KR",
+			value: "16615270",
+			display: "1661-5270",
+		},
+	],
+	code: { pattern: /인증번호는\s*\[([0-9]{4})\]/, capture: 1 },
+	maxAge: "PT5M",
+	waitTimeout: "PT2M30S",
+	clockSkew: "PT10S",
+});
+
+const paymentWebviewJourney = defineHealthJourney({
+	id: "sms-payment-webview",
+	schedule: every("8h", { jitter: "PT20M" }),
+	timeout: "PT5M",
+	cooldown: "PT8H",
+	requiredSecrets: [
+		"APIFUSE__HEALTH_MONITOR__PROVIDER_PHONE",
+		"APIFUSE__HEALTH_MONITOR__PROVIDER_PASSWORD",
+		"APIFUSE__HEALTH_MONITOR__PROVIDER_CANARY_ORDER_JSON",
+	],
+	coversOperations: ["verify-phone", "confirm-phone", "place-order"],
+	smsMatchers: [phoneOtp],
+	steps: [
+		{ id: "send-phone-otp", kind: "operation", operationId: "verify-phone" },
+		{ id: "wait-phone-otp", kind: "smsOtp", usesSmsMatcher: "phone-otp" },
+		{ id: "confirm-phone-otp", kind: "operation", operationId: "confirm-phone" },
+		{
+			id: "create-payment-webview",
+			kind: "operation",
+			operationId: "place-order",
+			safeBoundary: "paymentWebviewUrl",
+		},
+	],
+});
+
+export default defineProvider({
+	id: "example-provider",
+	// ...metadata, auth, operations, allowedHosts
+	healthJourneys: [paymentWebviewJourney],
+});
+```
+<!-- @magic-end:sample -->
+
+The journey runner supplies `ctx.gateway`, `ctx.sms.waitForOtp()`, `ctx.journal.sideEffect()`, `ctx.state`, and `ctx.event.operation()` to the optional journey `run` function. Provider authors should keep `run` small: call the covered operations in step order, stop at the declared safe boundary, and let the generated health metadata carry schedule, timeout, required secret, and SMS matcher information to the health monitor.
+
+For authenticated journeys, open a fresh connection inside `run` with `ctx.gateway.connect({ input: { ... } })`, execute covered operations with the returned `connectionId`, and disconnect in a `finally` block. Do not require or store long-lived `HEALTH_MONITOR_*_CONNECTION_ID` secrets; those stale connection IDs can hide broken login ceremonies.
+
+Use the runtime capabilities narrowly:
+
+- `ctx.gateway.execute()` is the default path for operation health evidence; the runner records operation success/failure automatically.
+- `ctx.journal.sideEffect()` wraps non-replayable provider mutations such as create/cancel/send operations.
+- `ctx.state.namespace(name, policy)` stores bounded lifecycle memory and recovery cursors with TTL/quota/value-size policy. It is not a replacement for the side-effect journal.
+- `ctx.event.operation()` records only synthetic operation outcomes proven by the journey, such as recovery/manual-review checks that are not direct gateway calls. The runtime rejects events for operations outside `coversOperations`.
+
+Do not import `apps/health-monitor`, generated health artifacts, database repositories, schedulers, or recorders from provider code. If a journey needs provider-specific helper code, place it under the provider package (for example `providers/<id>/health-journeys/*`) and keep the SDK boundary generic.
+
 ### External bounty submission evidence
 
 External contributors are expected to submit standalone Provider source plus:
@@ -74,11 +250,41 @@ External contributors are expected to submit standalone Provider source plus:
 - Health coverage table for every Operation.
 - `bun run check` output.
 - `bun run test` output.
+- `bun run submit-check` score/verdict and generated `submission-report.md`.
 - Fixture evidence and known upstream constraints.
 
 Maintainers own monorepo import under `providers/<id>/`, registry generation,
 deployment projection checks, and release workflows.
 
+### Public local debugging checklist
+
+- Operation smoke requests use the provider server envelope:
+  `{"requestId":"req_local_<operation>","input":{...},"headers":{}}`.
+  Omit `connection` for public/no-auth operations; do not send `connection: null`.
+- Credential-backed smoke requests pass local-only credential material in
+  `connection.secrets`. Keep real values in shell env or `.env`, never in source
+  or fixtures.
+- Auth-flow debugging starts with `/auth/start`, continues with
+  `/auth/continue`, and carries returned `contextPatch` values into the next
+  request's `context`.
+- Stealth/browser providers may require local runtime setup outside Provider code:
+  keep access-sensitive operations on `ctx.stealth.fetch()` with an SDK stealth
+  `profile`; the TypeScript runtime uses `impit` behind that interface, so do
+  not add per-operation JA3, HTTP/2 SETTINGS, or pseudo-header tuning. `ctx.stealth`
+  supports Chrome/Firefox-style profiles; use `browser.engine:
+  "playwright-stealth"` for Safari-specific or real browser Providers
+  (`nodriver` is Python-runtime only); install local browser assets with
+  `bunx playwright install chromium`, or set
+  `APIFUSE__CDP_POOL__URL` for remote browser debugging.
+
+### Running the pre-submission report
+
+```bash
+bun run submit-check
+```
+
+The report scores review readiness across definition metadata, operation/schema quality, fixtures/tests, health coverage, local smoke evidence, auth safety, secret hygiene, and submission docs. It is not a payout guarantee; any blocker must be fixed before review. For the complete public-only submission checklist, see `SUBMISSION.md` in the SDK package.
+
 ### Running the lint locally
 
 ```bash

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.1.0-beta.9
+
+- Preserve raw stealth response bytes through the public SDK response wrapper.
+- Add `arrayBuffer()` and `bytes()` to `StealthResponse` so consumers can inspect binary-safe upstream bodies.
+
+## 2.1.0-beta.8
+
+- Fix release automation for compiled `dist` package exports by building before package self-tests.
+- Provide `GH_TOKEN` to the GitHub release creation step.
+
+## 2.1.0-beta.7
+
+- Publish compiled `dist` exports for npm consumers so Next.js/Vercel builds do not parse TypeScript from `node_modules`.
+- Keep public CLI/template source files in the package while routing library exports through generated JavaScript and declarations.
+
+## 2.1.0-beta.6
+
+- Public repository clean-import release for `APIFuseHQ/provider-sdk`.
+- Preserves the monorepo SDK exports required by ApiFuse provider registry cutover, including `./contract` and provider i18n helpers.
+
+
+## 2.1.0-beta.5
+
+- Republish the bounty workspace DX hardening that accepts generated readonly metadata and factored `defineOperation()` maps during standalone TypeScript checks.
+- Ensure new bounty workspaces can install the public SDK version that matches their generated scaffold and pass `bun run check` immediately after bootstrap.
+
+## 2.1.0-beta.4
+
+- Align `apifuse create` with the bounty program topology: external contributors use the standalone one-provider-repository scaffold even when their assigned repo contains workspace-like files.
+- Stop auto-detecting `providers/` directories as public monorepo scaffolds. `--preset monorepo` is now reserved for the private APIFuse monorepo where `packages/provider-sdk` is actually present.
+- Remove public CLI/docs examples that present monorepo placement as a contributor workflow.
+
+## 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.
+- 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.
+- Warn, instead of hard-block, generated OAuth starters that have not yet declared persisted credential keys.
+
+## 2.1.0-beta.2
+
+- Harden public bounty contributor DX with server-contract accurate README and generated Provider smoke examples.
+- Add packed-artifact regression checks so stale `connection: null` or missing `requestId` examples cannot ship again.
+- Extend clean-room packed SDK smoke coverage to boot the generated dev server and call `/health` plus `POST /v1/ping`.
+- Document credential, auth-flow, stealth, browser, and Bun trusted-dependency troubleshooting for SDK-only local development.
+
 ## 2.1.0-beta.1
 
 - Fix public `apifuse create` runtime packaging by publishing `@clack/prompts` as a production dependency.

package/README.md

@@ -1,6 +1,6 @@
 # @apifuse/provider-sdk
 
-ApiFuse Provider SDK — build provider declarations and runtimes with one public SDK surface and one canonical CLI.
+APIFuse Provider SDK — build provider declarations and runtimes with one public SDK surface and one canonical CLI.
 
 ## Install
 
@@ -29,13 +29,11 @@ The canonical `create` flow:
 3. runs baseline validation,
 4. prints the exact next local-dev command.
 
-### Monorepo preset
+### Repository shape
 
-Inside the ApiFuse repository:
+The Provider SDK is a public bounty-contributor tool first. External bounty workspaces are one-provider repositories initialized from the standalone create flow. The generated provider must be installable without private APIFuse monorepo access.
 
-```bash
-apifuse create my-provider --preset monorepo
-```
+Do not use internal monorepo placement for bounty workspaces. Accepted provider work is imported into the private APIFuse monorepo later by maintainers or trusted automation.
 
 ## Provider server contract
 
@@ -58,6 +56,7 @@ Removed legacy runtime paths are not supported:
 cd my-provider
 bun run check
 bun run test
+bun run submit-check
 bun run dev
 ```
 
@@ -67,9 +66,76 @@ Smoke the generated local server:
 curl -s http://localhost:3900/health
 curl -s -X POST http://localhost:3900/v1/ping \
   -H 'Content-Type: application/json' \
-  -d '{"input":{"value":"hello"},"headers":{},"connection":null}'
+  -d '{"requestId":"req_local_ping","input":{"value":"hello"},"headers":{}}'
+```
+
+The operation request body is the same envelope used by the APIFuse gateway:
+
+| Field | Required | Notes |
+|---|---:|---|
+| `requestId` | yes | Any unique string is fine for local debugging; it is echoed in structured errors. |
+| `input` | yes | The operation input after schema validation. |
+| `headers` | no | Extra caller headers to expose through `ctx.request.headers`. |
+| `connection` | no | Omit for no-auth/public operations. For credential debugging, pass an object with `id`, `mode`, `secrets`, `metadata`, and `externalRef`. Do not pass `null`. |
+
+Credential-bearing local smoke example:
+
+```bash
+curl -s -X POST http://localhost:3900/v1/me \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "requestId":"req_local_me",
+    "input":{},
+    "connection":{
+      "id":"af_con_local_debug",
+      "mode":"credentials",
+      "secrets":{"apiKey":"dev-only-secret"},
+      "scopes":[],
+      "metadata":{},
+      "externalRef":"local-debug"
+    }
+  }'
+```
+
+Auth-flow endpoints use the same `requestId` convention:
+
+```bash
+curl -s -X POST http://localhost:3900/auth/start \
+  -H 'Content-Type: application/json' \
+  -d '{"requestId":"req_auth_start","flowId":"flow_local_1","providerId":"my-provider","context":{}}'
 ```
 
+If a local smoke returns `{"error":...}`, inspect the JSON error body and the
+`apifuse dev` server log. Validation failures include a `details` array with
+the bad request path; provider/runtime failures include `code`, `message`, and
+`requestId`.
+
+### Local debugging checklist
+
+- **`invalid_request` on `/v1/{operation}`**: confirm the request body includes
+  `requestId` and `input`. Omit `connection` for public/no-auth operations;
+  never send `connection: null`.
+- **Credential-backed operations**: declare `credential.keys`, then pass matching
+  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")`.
+- **Auth flows**: call `/auth/start`, then `/auth/continue` with the same
+  `flowId`; preserve any returned `contextPatch` in the next local request's
+  `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`, `throwOnHttpError`, and
+  `stealth.insecureSkipVerify`. 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.
+- **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
+  using the Playwright runtime, or set `APIFUSE__CDP_POOL__URL`
+  when debugging against a remote browser pool.
+
 ## Authoring ergonomics
 
 `defineProvider()` infers each operation handler input from the operation `input` schema. For larger providers, factor operations with `defineOperation()` and compose them later:
@@ -83,6 +149,9 @@ const search = defineOperation({
   async handler(ctx, input) {
     return { count: input.q.length }
   },
+  healthCheckUnsupported: {
+    reason: "Example operation only; replace with a real upstream probe.",
+  },
 })
 
 export default defineProvider({
@@ -108,6 +177,24 @@ 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 operation output parsed by the declared output schema:
+
+```ts
+healthCheck: {
+  interval: "5m",
+  cases: [{
+    name: "search responds",
+    input: { q: "weather" },
+    assertions: ({ data, status, durationMs }) => {
+      if (status !== 200 || data.count < 1 || durationMs > 3000) {
+        return { status: "degraded", label: "unexpected search baseline" }
+      }
+    },
+  }],
+}
+```
+
 ### Operation annotations
 
 Operations declare non-functional metadata via `annotations`:
@@ -129,11 +216,28 @@ Operations declare non-functional metadata via `annotations`:
 apifuse create <name>
 apifuse dev [path]
 apifuse check [path]
-apifuse record [path] --operation <operation> --params '{"value":"hello"}'
+apifuse record providers/korea-air-quality --operation realtime --params '{"stationName":"종로구"}'
 apifuse test [path]
-apifuse perf <path> --operation <operation>
+apifuse submit-check [path] --tier bronze --markdown submission-report.md
+apifuse bounty-check [path]
+apifuse perf providers/korea-air-quality --operation realtime --params '{"stationName":"종로구"}'
 ```
 
+`apifuse record` is for real upstream-backed operations that declare
+`upstream.baseUrl` and call the upstream through `ctx.http` or `ctx.stealth`. The
+generated local-only `ping` operation intentionally has no upstream and should
+be replaced before recording fixtures.
+
+## Bounty submission readiness
+
+Standalone providers include a pre-submission script:
+
+```bash
+bun run submit-check
+```
+
+This runs the public review-readiness evaluator and writes `submission-report.md`. The report contains provider metadata, a 100-point readiness score, hard blockers, warnings, checklist evidence, and remediation. Blockers override the score; fix them before posting bounty evidence. The command is offline-safe by default and does not execute arbitrary upstream calls. Add local smoke notes to your assigned workspace PR after testing `/health` and `POST /v1/{operation}`. See [`SUBMISSION.md`](./SUBMISSION.md) for the full public-only bounty submission checklist shipped in the npm package.
+
 ## Scope boundary
 
 Generator v1 scaffolds **TypeScript providers only** for this redesign. Python generation remains future work.
@@ -144,6 +248,6 @@ Generator v1 scaffolds **TypeScript providers only** for this redesign. Python g
 Provider cataloging, deployment enrollment, docs indexing, and runtime discovery are internal platform-registry responsibilities and are not part of the public `@apifuse/provider-sdk` contract.
 
 External bounty contributors should submit standalone Provider source plus
-`bun run check` / `bun run test` evidence. ApiFuse maintainers own monorepo
+`bun run check` / `bun run test` evidence. APIFuse maintainers own monorepo
 import, registry generation, deployment projection checks, and release
 publishing.

package/SUBMISSION.md

@@ -0,0 +1,87 @@
+# Provider bounty submission guide
+
+This guide is for public bounty contributors who only have access to the published `@apifuse/provider-sdk` package. You do **not** need the private APIFuse monorepo to build or pre-check a Provider.
+
+## SDK-only workspace workflow
+
+```bash
+bunx @apifuse/provider-sdk@beta create my-provider --yes
+cd my-provider
+bun run check
+bun run test
+bun run submit-check
+bun run dev
+```
+
+`bun run submit-check` runs `apifuse submit-check . --markdown submission-report.md` in generated Providers.
+
+## What submit-check scores
+
+`apifuse submit-check` produces a 100-point review-readiness score and a verdict:
+
+- `ready` — no blockers or warnings and score is at least 90.
+- `reviewable_with_warnings` — no blockers, but reviewers should inspect the warnings.
+- `blocked` — at least one hard blocker must be fixed before review.
+
+The score is a triage aid, not a payout guarantee. Maintainers still review correctness, upstream behavior, policy fit, and bounty scope.
+
+| Category | Points | Examples |
+|---|---:|---|
+| Definition & metadata | 15 | `defineProvider`, package, Dockerfile, SDK structural checks |
+| Operations & schemas | 15 | strong descriptions, annotations, 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 |
+| Auth/credential safety | 10 | auth mode and credential declarations are consistent |
+| Security hygiene | 10 | no high-confidence secrets in shareable files |
+| Docs/submission evidence | 10 | README Parameters, Response, Example, submit-check guidance |
+
+## Hard blockers
+
+Fix all blockers before submitting:
+
+- `bun run check` failures.
+- Provider cannot be imported from `index.ts`.
+- Missing handler/input/output for any Operation.
+- Missing fixture request or response.
+- Fixture data does not parse against schemas.
+- Missing `healthCheck` or `healthCheckUnsupported` on any Operation.
+- Credential-backed auth mode without declared credential keys.
+- 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`.
+
+## Safe local smoke evidence
+
+`submit-check` does not call arbitrary live upstream APIs by default. After replacing starter logic, run the Provider locally and record a short evidence note:
+
+```bash
+bun run dev
+curl -s http://localhost:3900/health
+curl -s -X POST http://localhost:3900/v1/<operation> \
+  -H 'Content-Type: application/json' \
+  -d '{"requestId":"req_local_smoke","input":{...},"headers":{}}'
+
+bun run submit-check -- --smoke-note "GET /health and POST /v1/<operation> passed locally with redacted input."
+```
+
+Never paste real credentials, personal data, account numbers, access tokens, cookies, or unredacted upstream responses into workspace PR comments, chat, or reports.
+
+## Submission evidence checklist
+
+Include the following when you submit a Provider for review:
+
+- Provider SDK version, for example `bun pm ls @apifuse/provider-sdk` or package.json dependency.
+- Provider id, version, runtime, and auth mode.
+- Operation list with input/output summaries.
+- Health coverage table: one row per Operation with `healthCheck` or `healthCheckUnsupported` and rationale.
+- `bun run check` output.
+- `bun run test` output.
+- `submission-report.md` generated by `bun run submit-check`.
+- Local smoke evidence for `/health` and at least one `POST /v1/{operation}` call.
+- Known upstream constraints: rate limits, paid/destructive calls, auth limits, flaky endpoints, or unsupported probes.
+
+## Maintainer-owned follow-up
+
+After workspace evidence is submitted, APIFuse maintainers import accepted standalone Provider work into the private monorepo and run internal registry, generated artifact, deployment projection, and CI checks. External contributors are not expected to run those private checks.