@dvmkit/dvmctl 0.1.0-rc.2 → 0.2.1-rc.1

package/skills/build-dvm/references/pricing-credit.md

@@ -0,0 +1,155 @@
+## Tags
+
+Tags are freeform strings describing what a DVM does, advertised in `/v1/info` and used by
+clients to discover providers:
+
+```typescript
+tag: "text"; // single tag
+tags: ["web", "extraction"]; // multiple tags
+```
+
+---
+
+## Pricing
+
+Static prices are USD literals (`PriceValue`) — the only static price form:
+
+```typescript
+price: "$0.05"; // USD → converted at current BTC rate
+```
+
+A raw-msats price throws at `configureDVM`. So does anything below `"$0.0001"` or finer than four
+decimals — that's the precision every caller-facing surface advertises at, so a finer price would
+advertise one number and charge another. Free capabilities omit `price`. Need finer granularity?
+Price dynamically with `onQuote`; dynamic upfronts carry full micro-unit precision.
+
+Dynamic pricing with `onQuote` — fiat-first. The handler returns an `upfront` envelope
+(`{ amount, currency: "usd" }`) plus a `shape`:
+
+```typescript
+onQuote: {
+  schema: z.object({ duration: z.number() }),
+  async handler(ctx) {
+    return {
+      upfront: { amount: ctx.data.duration * 0.001, currency: "usd" },
+      description: `${ctx.data.duration}s of synthesis`,
+      shape: "fixed",
+    };
+  },
+},
+```
+
+(`ctx.data` here is the quote-time parsed input, distinct from a job's `ctx.input`.)
+
+Two-phase metered pricing — `shape: "rate"` returns an `upfront` floor plus a `rate` (per-unit)
+so the SDK advertises a max-units cap; the handler calls `ctx.requestPayment(...)` again mid-job
+once actual usage is known (this is scribe's pattern):
+
+```typescript
+onQuote: {
+  schema: transcribeSchema,
+  async handler(ctx) {
+    return {
+      upfront: { amount: 0.02, currency: "usd" },        // spam-gate floor
+      description: "Up to 15 minutes; metered per-minute after",
+      shape: "rate",
+      rate: {
+        per_unit: { amount: 0.02, currency: "usd" },
+        unit: "minute",
+        max_units: 15,
+      },
+    };
+  },
+},
+```
+
+All first-party DVMs quote in `currency: "usd"`; the SDK converts to sats at the 402 handshake.
+
+To price in something else, declare it once at the DVM level — `currency: "eur"` on `configureDVM`
+(ISO 4217 lowercase; the bundled fx fetcher carries usd/eur/gbp/jpy). That one field is what the
+credit ledger, the funding menu, and `POST /v1/credit` all denominate in, so the two ways it could
+drift are both refused rather than converted: an `onQuote` returning a different currency answers
+`quote_currency_mismatch` (500), and a static `price` on a non-USD DVM throws at `configureDVM`
+(`"$0.05"` is a USD literal — a non-USD DVM prices with `onQuote`). `credit.min`/`max` stay USD
+literals whatever you price in; the menu converts them.
+
+---
+
+## Prepaid credit
+
+Every payment settles through a per-DVM **credit ledger**: the rail funds a balance, the job draws from it.
+Per-call payment is the N=1 case of that (fund the paid amount, draw it, same transaction) and happens
+whether or not you opt in. Declaring a `credit` block is the opt-in for callers to _hold_ a balance across
+jobs — the ledger, `POST /v1/credit`, the funding menu on quotes and 402s, per-draw idempotency and the
+quote balance echo are then wired for you:
+
+```typescript
+configureDVM({
+  name: "assessor",
+  capability: "assess",
+  price: "$0.01",
+  auth: secp256k1Auth(), // required — a balance belongs to a verified pubkey
+  credit: {
+    min: "$0.10", // smallest top-up accepted (default "$0.10")
+    max: "$5.00", // ceiling on a caller's *residual balance* (default "$5.00")
+    ttl: 30 * 24 * 60 * 60, // seconds; default 30 days
+    allowOneShotStablecoin: false, // default; stablecoin credit uses reusable channels
+  },
+  onJob(ctx) {
+    /* unchanged */
+  },
+});
+```
+
+`max` bounds what a caller may sit on, not what they may pay: a job priced above `max` still clears, because
+that request funds and draws in one step. Needs a Postgres-backed host — balances must survive a restart and
+be visible fleet-wide.
+
+- **`credit_id` / `draw_id` / `fund` are reserved at the top level of `data`.** A caller draws by putting
+  them in the same signed object your input schema validates. The SDK removes them before your schema sees
+  them and before the auth gate's schema check, so declare nothing for them, and **do** use `.strict()` if
+  you want it — unknown-key rejection still catches a caller's typo'd field with a 400 naming it.
+  The signature covers those keys either way, so tampering with one is still a 401. Don't name a field of
+  your own after one of them.
+- **Never hand-roll credit state.** The SDK ships the primitive (`credits` + `credit_draws`, `SELECT … FOR
+UPDATE` debits). `ctx.store` is **prohibited** for balances: last-write-wins KV on a multi-machine fleet
+  loses money under concurrency.
+- **Stablecoin credit is reusable-only unless you deliberately opt in.** Tempo `session` and x402
+  `batch-settlement` fund prepaid balances by default; Tempo `charge` and x402 `exact` still pay per call.
+  Set `allowOneShotStablecoin: true` only when you accept that every unused one-payment balance becomes a
+  manual refund obligation. Missing, malformed and older config fails closed.
+- **No debit on job failure**, with nothing to wire. A draw is a pending hold — settled on `completed`,
+  released on `failed` / `cancelled`, including `ctx.fail`, caller cancels and the stale-job reaper.
+- **Quote handlers see the caller.** `ctx.callerPubkey` is the verified pubkey (undefined without auth);
+  `ctx.credit` is a read-only snapshot `{ creditId, currency, balanceMicro, availableMicro, expiryMs,
+expired }` in micro-units — price against it, don't try to spend it (spending happens on the job path,
+  under the ledger's lock).
+- **Menu missing when you expected one?** The refusal ladder is ordered, and **only its last two rungs say
+  anything**. Isolate runtime (never offers credit), no `credit` block, and no descriptor auth all return
+  silently — check those three first, in that order, because no log will point you at them. A non-durable
+  ledger outside devMode warns `credit_menu_suppressed_non_durable`; bounds not expressible in the quote
+  currency warn `credit_menu_bounds_unavailable` (note the different prefix — don't grep for one pattern).
+  Both fire once per process (`warnOnce`), so a restart is what re-arms them. A rung never fails the quote —
+  the sale survives without credit.
+- **Reclaim is a builder obligation on the rails you hold the money on — and only those.** Who fulfils a
+  drain is decided by the rail, and treating one shape as another is how a self-settling refund lands on
+  your worklist or a real debt goes unpaid. **Ecash is the whole of your automatic obligation**:
+  `dvmctl melt-pending` parks notes P2PK-locked to the caller's refund key and holds your payout melt back
+  while refund liability is outstanding. A **Lightning-funded** credit reclaims that same way — direct
+  Lightning payout is not a reclaim method, so a `method: "lightning"` drain is refused
+  `drain_method_unsupported` and your deployment never needs a send-capable Lightning credential.
+  **Channel-backed x402 and Tempo drains settle themselves** on the caller's signed refund
+  voucher — no builder spending key, nothing to record; `drains-owed` never lists one and `drain-settle`
+  refuses it (`channel_bound_drain`), because a hand-recorded payout takes the row out of the reconciliation
+  that would have paid it. **One-payment x402 and Tempo drains are the only shape a person settles**: they
+  queue behind `drain_manual_settlement_required`, and `dvmctl credit drains-owed <handle>` then
+  `dvmctl credit drain-settle <handle> <credit-id> <drain-id> --tx <hash>` is the path. That one is manual
+  by design — automating it would put a chain spending key with your whole stablecoin balance behind it on
+  the `melt-pending` host. On the rails you hold, an
+  unfulfilled drain is a signed IOU the caller can prove. One-payment stablecoin credit exists only when
+  `allowOneShotStablecoin` explicitly enabled it; do not take that opt-in without an operating refund path.
+
+For wire shapes and supported options, consult the installed SDK declarations and the local `dvmctl`
+help for the version you installed.
+
+---

package/skills/build-dvm/references/running-deployment.md

@@ -0,0 +1,231 @@
+## Running
+
+### dvmctl dev (development)
+
+```bash
+dvmctl dev handler.ts              # http://localhost:3000, hot reload, /_dev test page
+dvmctl dev handler.ts --port 4000  # custom port
+```
+
+Port resolution: `--port` > `.env PORT` > `process.env.PORT` > `3000`.
+
+Handler resolution: default export > `dvm` named export > first `DVMDescriptor` export.
+
+The dev server auto-credits payments — upfront and mid-job alike — **only while no mints are
+configured**, so a priced handler runs with no wallet in sight. A mint alone starts Cashu accumulator
+mode but does not supply its lock pubkey, durable DVM ID, or Postgres store, so it does not advertise
+Cashu. Use the complete [Local Cashu paid test](local-cashu-test.md) for the self-hosted `dvmctl serve
+--dvm` path. `dvmctl dev` itself serves a test page at `/_dev` for
+interactive testing, whose auto-approve button satisfies a mid-job ask with a proofless `dev_auto`
+flag no non-dev server admits. Drive it from another terminal with the `dvm` CLI:
+
+```bash
+dvm request --endpoint http://localhost:3000 -i "input" --human
+```
+
+`--endpoint` and `-d <identifier>` are mutually exclusive — pass one or the other, not both.
+Against a raw endpoint the capability auto-resolves from `/v1/info`, so a single-cap DVM needs
+nothing more. A multi-cap DVM has no capability to auto-resolve and errors `ambiguous_capability`
+with the available tags listed — pin one via the slash form (`-d <identifier>/<tag>`), where
+`<identifier>` is an owner-qualified `<handle>--<slug>` or a saved favorite.
+
+### serve(dvm) — production one-liner
+
+```typescript
+import { serve } from "@dvmkit/sdk/server";
+import dvm from "./handler";
+
+await serve(dvm);
+// or with overrides:
+await serve(dvm, { port: 8080, mints: ["https://mint.example.com"] });
+```
+
+`serve(dvm, opts?)` is a thin wrapper over `createDVMHost(opts).mount(dvm).serve()` and returns
+`{ url, close }`. All wiring (port, `DATABASE_URL`, `DVMKIT_CASHU_MINTS`, Tempo/x402 rails, FX,
+platform reporter) is resolved from env by default — `opts` only overrides.
+
+### createDVMHost(opts) — advanced
+
+Use directly when you need to register `host.app` routes, mount several DVMs, or graceful-shutdown
+alongside DVM-owned resources:
+
+```typescript
+import { createDVMHost } from "@dvmkit/sdk/server";
+import { createCastDVM, buildCastRuntime } from "./handler";
+
+const { runtime } = await buildCastRuntime(process.env);
+
+const host = createDVMHost({
+  fx: runtime.fxFetcher,
+  // database / mints / port etc default from env
+});
+
+host.mount(createCastDVM(runtime));
+
+const { url } = await host.serve();
+console.log(`cast running at ${url}`);
+```
+
+---
+
+## createDVMHost / serve options
+
+`DVMHostOpts` (passed to either function):
+
+| Option             | Type                     | Default                       | Description                                                 |
+| ------------------ | ------------------------ | ----------------------------- | ----------------------------------------------------------- |
+| `port`             | `number`                 | `PORT` env or `8080`          | HTTP listen port                                            |
+| `database`         | `string`                 | `DATABASE_URL` env            | Postgres URL — auto-creates job + KV stores (`pg` peer dep) |
+| `jobStore`         | `JobStore`               | derived from `database`       | Explicit job store; precedence over `database`              |
+| `store`            | `KVStore`                | in-memory                     | KV store for `ctx.store`                                    |
+| `env`              | `Record<string, string>` | `process.env`                 | Injected as `ctx.env`                                       |
+| `mints`            | `string[]`               | `DVMKIT_CASHU_MINTS` env      | Cashu mints accepted                                        |
+| `mpp`              | `MppxServer`             | from `DVMKIT_TEMPO_*` env       | Tempo rail handle (mppx server)                             |
+| `x402`             | `X402Config`             | from `DVMKIT_X402_*` env      | x402 stablecoin rail config                                 |
+| `paymentMethods`   | `PaymentMethod[]`        | derived from configured rails | Restrict accepted rails                                     |
+| `fx`               | `FxFetcher`              | env-derived                   | FX rate fetcher (override for tests or alt sources)         |
+| `builder`          | `BuilderIdentity`        | env-derived                   | `{ id?, name?, url? }` for `/v1/info`                       |
+| `healthHandler`    | `(c) => Response`        | default `/health`             | Custom `/health` handler                                    |
+| `platformReporter` | `PlatformReporterOpts`   | `DVMKIT_PLATFORM_*` env       | `{ token?, url? }` for revenue reporting                    |
+| `devMode`          | `boolean`                | `false`                       | Skips DB requirement; auto-credits only when mint-less      |
+
+`DVMHost` returned by `createDVMHost`:
+
+| Property / method             | Description                                                     |
+| ----------------------------- | --------------------------------------------------------------- |
+| `host.app`                    | Underlying Hono app — register host-level routes here           |
+| `host.pool`                   | Postgres pool, set after `host.serve()` resolves                |
+| `host.mount(dvm, { prefix })` | Mount a DVM; optional prefix nests its routes under `/<prefix>` |
+| `host.serve({ port })`        | Start listening; returns `{ url, close }`                       |
+| `host.shutdown()`             | Graceful shutdown                                               |
+
+---
+
+## Persistence
+
+Pass `database` (or set `DATABASE_URL`) to persist jobs, state, step caches, and KV data to
+Postgres:
+
+```typescript
+await serve(dvm, { database: process.env.DATABASE_URL });
+```
+
+From the handler author's perspective:
+
+- `ctx.state` is typed from your `state: { ... }` defaults and is **auto-persisted transactionally
+  on every yield** (prompt, requestPayment) and at terminal states (complete, fail). After a
+  process restart, the SDK reloads state from Postgres and resumes.
+- `ctx.step("id", fn)` results are persisted alongside state. On replay, cached steps return their
+  stored value without re-executing, and replay the step's `ctx.cost()` declarations exactly once.
+- `ctx.requestPayment(amount, reason, opts?)` resolves on **counter-based auto-credit**: if the
+  upfront payment already covers `amount - alreadyCreditedToThisHandler`, the call returns
+  synchronously without round-tripping to the client. Only when the upfront pool is exhausted does
+  the handler suspend waiting for a new payment.
+
+Auto-creates `PostgresJobStore` + `PostgresKVStore`; tables are created on first run. `jobStore`
+and `store` opts take precedence over `database` for advanced use. `pg` is an optional peer dep —
+the scaffold already lists it.
+
+---
+
+## Deployment
+
+The scaffold ships a Dockerfile and wires `npm run deploy` → `dvmctl deploy`. The cloud path:
+
+```bash
+dvmctl validate          # fast local check: slug, package.json, vmConfig — JSON out, no Docker
+dvmctl deploy            # build container, push, deploy to the dvmkit platform
+dvmctl deploy --dry-run  # full validation incl. a real `docker build` (slow, cold) — no provisioning
+```
+
+Use `dvmctl validate` for fast iteration; it's instant and emits `{"status":"ok", ...}`.
+`dvmctl deploy --dry-run` adds a real container build on top, so it's slower and needs Docker.
+
+On dvmkit Cloud, the active org owns each deployed DVM. Its treasury holds payout configuration — Tempo recipient, Base/x402 address, Cashu mints, and lock pubkey — rather than the DVM descriptor or builder profile. The lock pubkey propagates from org to DVM to SDK; see the three-level lock pubkey model.
+
+Provide the deployed DVM's API keys and payment credentials through its host's runtime environment
+facility; keep them out of source control. That is separate from the platform org treasury's payout
+configuration. System dependencies (ffmpeg, python, …) go in the scaffolded `Dockerfile`'s runtime
+stage. VM resources go in `package.json`'s `dvmkit` field (`{ "dvmkit": { "memory_mb": 1024 } }`).
+
+### Environment variables
+
+The SDK reads only `DVMKIT_*`-prefixed variables. Old unprefixed names (`MINTS`,
+`MPP_TEMPO_RECIPIENT`, `X402_PAY_TO`, etc.) and the legacy `DVMKIT_FIRST_PARTY` /
+`DVMKIT_ACCESS_TOKENS` / `DVMKIT_SKIP_PAYMENT` are gone — don't use them.
+
+**Standard (unprefixed):**
+
+| Var            | Description                                      |
+| -------------- | ------------------------------------------------ |
+| `PORT`         | HTTP port (default: 8080)                        |
+| `DATABASE_URL` | Postgres connection string (enables persistence) |
+
+**Cashu rail:**
+
+| Var                        | Description                                                                                                                                                                                                                                  |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DVMKIT_CASHU_MINTS`       | Comma-separated Cashu mint URLs                                                                                                                                                                                                              |
+| `DVMKIT_CASHU_LOCK_PUBKEY` | P2PK lock pubkey for the accumulator                                                                                                                                                                                                         |
+| `DVMKIT_DVM_ID`            | DVM identifier (replay key + scheduler lock)                                                                                                                                                                                                 |
+| `DVMKIT_CANONICAL_DVM_ID`  | Override `DVMKIT_DVM_ID` for cross-instance canonical ID                                                                                                                                                                                     |
+| `DVMKIT_ALLOW_TEST_MINTS`  | `true` to allow a test mint (`localhost:3338`, `testnut.cashu.space`) on a platform-hosted boot (`DVMKIT_PLATFORM_URL` set). Otherwise such a boot refuses to start — a test mint settles no real money. Local dev never trips it. |
+
+**Tempo rail:**
+
+| Var                          | Description                                     |
+| ---------------------------- | ----------------------------------------------- |
+| `DVMKIT_TEMPO_RECIPIENT` | 0x-prefixed 40-char hex Tempo recipient address |
+| `DVMKIT_TEMPO_SECRET_KEY`      | HMAC key for Tempo challenges                   |
+| `DVMKIT_TEMPO_METHODS`         | Comma-separated allowlist of Tempo methods      |
+
+**x402 rail:**
+
+| Var                       | Description                              |
+| ------------------------- | ---------------------------------------- |
+| `DVMKIT_X402_PAY_TO`      | EVM address receiving stablecoin         |
+| `DVMKIT_X402_NETWORK`     | Validated CAIP-2 id or known slug (default `eip155:8453`) |
+| `DVMKIT_X402_ASSET`       | Asset symbol                             |
+| `DVMKIT_X402_FACILITATOR` | Facilitator URL; use `https://api.cdp.coinbase.com/platform/v2/x402` for CDP |
+| `DVMKIT_X402_FACILITATOR_KEY_ID` | CDP API key ID; requires the secret below |
+| `DVMKIT_X402_FACILITATOR_KEY_SECRET` | CDP SEC1 ES256 PEM (`BEGIN EC PRIVATE KEY`) or base64 Ed25519 secret; provide it through the deployment environment |
+| `DVMKIT_X402_DUAL_SERVE`  | `"false"` disables dual-serve            |
+| `DVMKIT_X402_DESCRIPTION` | Prose description                        |
+| `DVMKIT_X402_BATCH_SETTLEMENT` | `true` enables reusable channels: Base Sepolia uses hosted facilitator support; Base mainnet also requires the self-relay key below and keeps batch credit funding independent from hosted exact health |
+| `DVMKIT_X402_RECEIVER_AUTHORIZER_KEY` | Receiver-authorizer private key when the facilitator supplies none; mainnet self-relay requires this separate signing-only key |
+| `DVMKIT_X402_SELF_RELAY_KEY` | Dedicated funded EOA key for one DVM's Base-mainnet relay; never reuse it as the authorizer or across DVMs |
+| `DVMKIT_X402_SELF_RELAY_MIN_BALANCE_WEI` | Optional positive Base ETH paging floor; defaults to 0.001 ETH |
+| `DVMKIT_X402_RPC_URL` | Required explicit Base RPC for self-relay transaction submission and settlement evidence |
+| `DVMKIT_X402_WITHDRAW_DELAY_SECONDS` | Channel withdrawal grace; minimum/default 86400 |
+
+**Lightning receive (credit funding only —:**
+
+| Var                                      | Description                                                                                                                                                                                          |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DVMKIT_NWC_RECEIVE_URI`                 | **Receive-only** NWC connection the DVM issues credit-funding bolt11s over. Adds `lightning` to the credit funding menu; never to `payment_methods` — there is no per-call Lightning rail. |
+| `DVMKIT_NWC_RECEIVE_INVOICE_TTL_SECONDS` | Invoice lifetime (default `900`, floor `600`)                                                                                                                                                        |
+| `DVMKIT_LIGHTNING_FUNDING_MIN_SATS`      | The deployment's receive floor in sats (default `2000`,. Advertised on the menu as `lightning_min_micro` (×1.15 fx margin); a sub-floor fund is refused `below_rail_minimum` before any invoice exists — a bolt11 under the channel's `htlc_minimum_msat` can never route. |
+
+The connection must permit `get_info`, `get_balance`, `make_invoice`, `lookup_invoice` and **not** `pay_invoice` — the SDK probes it at boot and refuses to start on a spend-capable connection, or on a wallet that won't state what its connection permits. A DVM machine never holds a spending credential; the drain sender is a deliberately separate, budget-capped connection.
+
+Crediting is **pull-based**. The caller sends `op: "fund"` with `fund: { amount_micro, fund_id, method: "lightning" }` and no `commitment` (there is no artifact to hash — the invoice is minted for the credit and amount in their signed body, which is the binding), gets a 402 carrying the bolt11, and their _next_ request — a re-poll, a `balance` read, or a job submit naming the credit — asks the wallet and credits the ledger in one transaction. No background watcher, so a suspend-to-zero fleet works unchanged. A re-poll always returns the same bolt11; a second invoice per `fund_id` would be two payable invoices against one creditable funding. If the wallet is unreachable, `lightning` drops off the menu and the other rails carry the sale.
+
+**Platform / ops:**
+
+| Var                     | Description                                                                                      |
+| ----------------------- | ------------------------------------------------------------------------------------------------ |
+| `DVMKIT_FAIL_FAST`      | `"1"` or `"true"` → escalate warning-level SDK boot checks to fatal (strict mode)                |
+| `DVMKIT_FX_SOURCE`      | FX rate source override                                                                          |
+| `DVMKIT_PLATFORM_TOKEN` | Bearer token for platform revenue reporter                                                       |
+| `DVMKIT_PLATFORM_URL`   | Platform internal URL — setting it marks the boot platform-hosted                                |
+| `DVMKIT_RECEIPT_KEY`    | Receipt-signing secret. Provisioned by `dvmctl deploy` — see [Signed receipts](patterns-auth.md#signed-receipts) |
+
+Setting `DVMKIT_PLATFORM_URL` makes `DVMKIT_PLATFORM_TOKEN`, `DVMKIT_DVM_ID`, and `DATABASE_URL`
+mandatory: partial revenue-reporter wiring is fatal at boot whether or not `DVMKIT_FAIL_FAST` is set
+. `devMode` boots — `dvmctl dev`, `dvm serve`, the e2e/smoke harnesses — are exempt, so a
+`DVMKIT_PLATFORM_URL` exported in your shell won't stop a dev server booting.
+
+`DVMKIT_FAIL_FAST` is the general strict-mode flag for the SDK's other boot checks (e.g.
+`secp256k1Auth`'s in-memory replay store outside `devMode`); set it in production.
+
+---

package/skills/build-dvm/references/sdk-reference.md

@@ -0,0 +1,47 @@
+# SDK reference
+
+Use this after the first-build brief is approved. Keep the first version flat and single-capability unless the product requires distinct inputs, prices, or handlers.
+
+```ts
+import { configureDVM, z } from "@dvmkit/sdk";
+
+export default configureDVM({
+  name: "Uppercase",
+  description: "Convert text to uppercase.",
+  capability: "uppercase",
+  tags: ["text"],
+  input: z.object({ text: z.string().min(1) }),
+  price: "$0.01",
+  async onJob(ctx) {
+    ctx.complete(ctx.input.text.toUpperCase());
+  },
+});
+```
+
+Import `serve` or `createDVMHost` from `@dvmkit/sdk/server`, and `createTestContext` from `@dvmkit/sdk/testing`. `serve(dvm)` is sufficient for a normal DVM. Use `createDVMHost` only for custom HTTP routes, mounting several DVMs, or explicit lifecycle control.
+
+## Descriptor choices
+
+- `input: z.object(...)` validates requests before `onJob` and types `ctx.input`. Omit it only for deliberately raw-string input.
+- `price: "$0.01"` is a static USD price. Omit it for free work. Use `onQuote` for dynamic pricing; never calculate a static price in sats.
+- `capabilities: { ... }` replaces the flat capability fields for a multi-capability DVM. Keep name, tags, auth, routes, and lifecycle hooks at the parent level.
+- `state` provides typed per-job defaults. Use a persistent store only when jobs must survive process restarts.
+- `paymentMethods` is normally derived from configured server rails. Do not advertise a rail that the server cannot settle.
+
+## Job handler rules
+
+`ctx.text()` sends progress, `ctx.artifact()` sends named data, `ctx.working()` yields with an estimate, `ctx.prompt()` waits for a caller response, and `ctx.complete()` finishes. Call `ctx.cost({ amount, currency })` immediately after a paid provider call. Check `ctx.signal.aborted` around long work and pass the signal to fetches where supported. A cancellation is terminal; never attempt to complete it afterward.
+
+Use `ctx.fail(message, { refund: true })` for a provider or network failure that should return a Cashu payment. Configuration errors and invalid user input should fail without a refund.
+
+## Tests and secrets
+
+Write deterministic unit tests with `createTestContext`; assert messages, completion, failure, and artifacts. Mock an upstream boundary in unit tests and keep live-provider tests separate. Load credentials from environment variables. Never place a key, mnemonic, private key, or test wallet state in a repository.
+
+## Advanced routing
+
+Use descriptor `auth: secp256k1Auth(...)` only when the product needs authenticated callers. The verified identity is `ctx.auth`; do not accept an identity asserted in input. Use `routes(app)` for non-protocol endpoints and keep `/v1/*` protocol endpoints under SDK control. See the installed package's TypeScript declarations for exact option types; they match the installed SDK version.
+
+## Deploy preparation
+
+Before deployment, run the generated tests and validate the descriptor. A production deployment needs its own account, identity, database, environment secrets, and payment configuration. Do not reuse a local FakeWallet mint or its test key in production.

package/skills/build-dvm/references/testing.md

@@ -0,0 +1,181 @@
+## Input validation
+
+Pass an `input:` Zod schema and `ctx.input` is parsed and typed. Zod ships with the SDK —
+`import { z } from "@dvmkit/sdk"`, no extra install. Skip the schema and `ctx.input` stays a raw
+string you parse yourself.
+
+```typescript
+import { configureDVM, z } from "@dvmkit/sdk";
+
+export default configureDVM({
+  name: "Image Gen",
+  capability: "generate",
+  tags: ["image-generation"],
+  input: z.object({
+    prompt: z.string(),
+    width: z.number().default(1024),
+    height: z.number().default(1024),
+  }),
+
+  async onJob(ctx) {
+    // ctx.input is typed: { prompt: string; width: number; height: number }
+    ctx.text(`Generating: ${ctx.input.prompt}`);
+  },
+});
+```
+
+**Document fields with `.describe()`, not JSDoc.** `/v1/info` renders each field via
+`toJSONSchema(input, { io: "input" })`, which carries **only** Zod `.describe()` metadata — a
+`/** … */` JSDoc comment on a schema field is silently dropped and never reaches the cold-calling
+agent. Put field docs on `.describe("…")`; reserve JSDoc for internal notes. When a cross-field
+rule lives in a `.refine()` (e.g. "exactly one of `audio_url` / `audio_upload_handle`"), name it in
+the fields' `.describe()` and also ship an `example` so the CLI renders a runnable `--data` payload
+instead of a schema skeleton. The `dvmkit/no-jsdoc-on-zod-schema` ESLint rule (scoped to
+the DVM source tree) flags JSDoc on Zod-object properties.
+
+```typescript
+// ❌ dropped from /v1/info          ✅ reaches the wire
+z.object({                           z.object({
+  /** Omit to auto-detect. */          language: z.string().describe("Omit to auto-detect.").optional(),
+  language: z.string().optional(),   });
+});
+```
+
+---
+
+## Testing
+
+### createTestContext()
+
+```typescript
+import { createTestContext } from "@dvmkit/sdk/testing";
+
+const ctx = createTestContext({
+  input: "test input", // string or parsed type
+  tags: ["web"],
+  params: { key: "value" },
+  env: { API_KEY: "test" }, // ctx.env
+  state: { step: 0 }, // ctx.state (typed, structured-cloned)
+  paidMsats: 10000,
+  responses: {
+    // pre-programmed prompt answers
+    q1: { text: "answer", prompt_id: "q1" },
+  },
+  payment: { cashu_token: "..." }, // pre-programmed requestPayment answer
+  jobId: "test-job-1",
+  requesterId: "test-requester",
+});
+```
+
+`createTestContext` bypasses `JobStore` entirely: `step()` runs `fn()` directly with no caching,
+state is a structured clone of `opts.state`, and there is no Postgres dependency. `ctx.auth` is
+always `undefined` in tests (there's no `auth` option) — exercise signed-request auth through
+`createSignedRequestVerifier` round-trips instead.
+
+### Inspection properties
+
+| Property          | Type                  | Description                               |
+| ----------------- | --------------------- | ----------------------------------------- |
+| `messages`        | `RecordedMessage[]`   | All outbound messages `[{type, content}]` |
+| `completed`       | `boolean`             | Whether `complete()` was called           |
+| `failed`          | `boolean`             | Whether `fail()` was called               |
+| `refundRequested` | `boolean`             | Whether `fail()` was called with refund   |
+| `summary`         | `string \| undefined` | The string passed to `complete()`         |
+| `failError`       | `string \| undefined` | The string passed to `fail()`             |
+
+`ctx.cancel(reason?)` aborts `ctx.signal` exactly as a real cancel would and puts the context into the
+same post-terminal shape as the runtime: every emitter (`text` / `artifact` / `sendMessage` /
+`working` / `progress` / `complete` / `fail`) is a no-op, and `prompt` / `requestPayment` reject with
+`JobCancelledError`. Use it to assert your handler stops work:
+
+```typescript
+const ctx = createTestContext({ input: "long job" });
+const running = dvm.capabilities.transcribe.onJob(ctx);
+ctx.cancel("caller changed their mind");
+await running;
+expect(ctx.completed).toBe(false);
+```
+
+### Calling the handler
+
+The descriptor exposes `dvm.capabilities[<name>].onJob` in both shapes (flat single-capability or
+multi-capability):
+
+```typescript
+import { describe, expect, it } from "vitest";
+
+import { createTestContext } from "@dvmkit/sdk/testing";
+
+import { createTranslatorDVM } from "./handler";
+
+describe("Translator", () => {
+  const dvm = createTranslatorDVM();
+
+  it("translates with language prompt", async () => {
+    const ctx = createTestContext({
+      input: "Hello",
+      tags: ["translation"],
+      state: { detectedLanguage: "", targetLanguage: "" },
+      responses: { "target-lang": { text: "Spanish", prompt_id: "target-lang" } },
+    });
+
+    await dvm.capabilities.translate.onJob(ctx);
+
+    expect(ctx.completed).toBe(true);
+    expect(ctx.summary).toContain("Spanish");
+    expect(ctx.messages).toContainEqual(expect.objectContaining({ type: "artifact" }));
+  });
+});
+```
+
+### Live provider contracts
+
+**Invariant: a capability that charges _and_ whose handler calls a paid third-party API must ship a
+live provider-contract test.** Both halves of the conjunction are required, and the rule is
+deliberately narrow. A free capability, or one that only talks to your database, your own endpoints,
+or a local FakeWallet mint, falls outside it. Give those paths appropriate integration checks in
+your project.
+
+Why: `createTestContext` and a stubbed `globalThis.fetch` pin your request shape against your own
+expectation. They do not prove the provider accepts it. A provider can reject a request after the
+job has taken payment. No debit lands either way — the draw releases (see
+[Refund-on-failure policy](patterns-auth.md#refund-on-failure-policy)) — but reaching that released
+value needs a verified caller. Add `auth` when the product needs callers to use released credit again;
+a rail-level reversal is a separate payment-design choice.
+
+The pattern has three parts:
+
+1. **Name the file `<provider>.live.test.ts`.** Configure your project's default test command to
+   exclude `**/*.live.test.ts`, so ordinary checks never spend vendor money.
+2. **Gate the suite on `describe.skipIf(!process.env.<PROVIDER_KEY>)`.** This is what makes the test
+   **merge inert**: a keyless checkout and a keyless CI run both skip cleanly rather than reddening.
+   The rule does **not** mean CI needs your API key.
+3. **Add an opt-in `test:providers:live` script** that includes only `**/*.live.test.ts`. Nothing
+   else runs it.
+
+```typescript
+const API_KEY = process.env.ELEVENLABS_API_KEY;
+
+describe.skipIf(!API_KEY)("ElevenLabs live provider contract (real EL spend)", () => {
+  it("accepts the expressive multi-chunk shape we emit", async () => {
+    // Real call. Assert the provider ACCEPTS what we send…
+    expect(call.status).toBe(200);
+    expect(call.body.model_id).toBe(ELEVENLABS_V3_MODEL_ID);
+    // …and returns what we actually parse.
+    expectMp3(audio);
+  });
+});
+```
+
+**Assert the provider accepts every request shape the handler actually emits, and returns something
+the parser actually parses.** A live 2xx alone is not the contract — if the handler branches (model
+× chunking, streaming vs. batch, each option a caller can select), each branch is a distinct wire
+shape and needs a cell. This is a _contract_ test, not a quality test: "the provider accepts what we
+send", never "the output is good".
+
+It spends **real vendor money** (never caller funds, never production). Keep request and response
+evidence small: record URL, body shape, and status; never print headers or keys. A provider 429/5xx
+may retry once, then skip with a clear reason rather than reporting a false product regression.
+Shipping this test with the capability keeps a new paid boundary from depending only on mocks.
+
+---