@dvmkit/dvmctl 0.1.0-rc.2 → 0.2.0-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dvmkit/dvmctl",
-  "version": "0.1.0-rc.2",
+  "version": "0.2.0-rc.2",
   "description": "Builder CLI for creating, testing, and deploying Digital Vending Machines",
   "license": "Apache-2.0",
   "repository": {
@@ -17,9 +17,14 @@
   },
   "files": [
     "dist",
+    "skills",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "README.md"
   ],
+  "exports": {
+    "./skill": "./skills/build-dvm/SKILL.md"
+  },
   "engines": {
     "node": ">=22"
   },
@@ -31,14 +36,14 @@
     "verify": "npm run build && npm run lint && npm run typecheck && npm test"
   },
   "dependencies": {
-    "@dvmkit/sdk": "0.1.0-rc.7"
+    "@dvmkit/sdk": "0.1.4-rc.7"
   },
   "optionalDependencies": {
     "pg": "8.20.0",
     "tsx": "^4"
   },
   "devDependencies": {
-    "@cashu/cashu-ts": "4.2.1",
+    "@cashu/cashu-ts": "4.10.2",
     "@scure/bip39": "2.0.1",
     "commander": "^14",
     "mppx": "0.8.15",

package/skills/build-dvm/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: build-dvm
+description: Build a first DVM with dvmkit. Use when asked to turn an idea into a paid HTTPS capability, scaffold or hand-write a DVM, implement a `configureDVM` handler, run it locally, test it with Cashu FakeWallet funds, or prepare it for deployment. Do not use for changing the dvmkit platform, SDK internals, or a caller wallet unrelated to testing a DVM.
+compatibility: Node.js 22+, npm, the invited `@dvmkit/dvmctl` release, and Docker for the local paid Cashu test. The optional paid test also uses `@dvmkit/dvm-cli@0.2.0` with isolated builder and caller state.
+allowed-tools: Bash Read Write Edit Glob Grep
+---
+
+# Build a DVM
+
+Use this process for a first build. Stop after each approval point; do not deploy, connect a wallet, or spend real funds until the builder explicitly asks.
+
+## 1. Install the CLI and this skill
+
+Use the exact `@dvmkit/dvmctl` version named in the builder's invitation. Never use a floating tag. Install the CLI, then install the complete skill directory so its references remain available.
+
+```bash
+npm install -g @dvmkit/dvmctl@<invited-version>
+npm install --ignore-scripts --prefix "$HOME/.dvmkit" @dvmkit/dvmctl@<invited-version>
+skill_dir="$(dirname "$(NODE_PATH="$HOME/.dvmkit/node_modules" node -p "require.resolve('@dvmkit/dvmctl/skill')")")"
+```
+
+<!-- agent-mirror:verbatim start -->
+For Claude Code, install the complete directory globally:
+
+```bash
+mkdir -p "$HOME/.claude/skills/build-dvm"
+cp -R "$skill_dir"/. "$HOME/.claude/skills/build-dvm/"
+```
+
+For Codex in the current project, install the complete directory locally:
+
+```bash
+mkdir -p .agents/skills/build-dvm
+cp -R "$skill_dir"/. .agents/skills/build-dvm/
+```
+<!-- agent-mirror:verbatim end -->
+
+For another harness, copy the same complete directory to that harness's project-skill location. Confirm `dvmctl --version` reports the invited version before continuing.
+
+Give the builder this canonical prompt after installation:
+
+> Help me build a DVM with dvmkit. Read the installed `build-dvm` skill. Interview me about one capability, its input, output, example, fiat price, and name. Write a short brief and wait for my approval. Then build and test it locally, including the optional Cashu FakeWallet paid-call path with isolated caller state. Do not deploy or use real funds without my approval.
+
+## 2. Shape one capability
+
+Ask only for the decisions that change the first version: input, result, one example, name, and a fiat price. Prefer one capability and one typed object input. Write this brief and get approval before editing:
+
+```text
+Name:
+Capability:
+Input: example JSON and validation rules
+Result: text or named artifact
+Price: $0.01 (or free)
+Paid-test cap: separately approved before test money is spent
+Example: input → result
+```
+
+The approved DVM price and the approved paid-test cap are different decisions. A $0.01 DVM can use a $0.02 per-test cap to allow whole-satoshi rounding, but ask for that cap if it is not already approved. Never raise a cap automatically. Do not choose a payment rail or cloud configuration during this interview. A local Cashu mint is test infrastructure, not the builder's production payment choice.
+
+## 3. Implement and test the free path
+
+Scaffold when it helps; a hand-written Node 22 project with `@dvmkit/sdk` is equally supported.
+
+```bash
+dvmctl create my-dvm
+cd my-dvm
+npm install
+npm test
+dvmctl dev handler.ts
+```
+
+Keep `handler.ts` small: use `configureDVM`, a Zod `input` schema, a USD `price` string when paid, and `ctx.complete()` with a useful summary. Put provider keys in `.env`, never source code. Add a unit test using `createTestContext` before calling external services. Use the `/_dev` URL printed by `dvmctl dev` to show the builder the free result.
+
+Read [the SDK reference](references/sdk-reference.md) for descriptor shapes, job-context methods, streaming, dynamic quotes, auth, persistence, custom routes, and deployment. Read [the Cashu test reference](references/local-cashu-test.md) before a paid test.
+
+## 4. Exercise a paid local call with test money
+
+This is the only first-build paid path. It uses a local Cashu FakeWallet mint, which auto-settles test invoices and has no real value. Before starting, confirm a separate per-test dollar cap; approving the DVM's price alone is not payment approval. Then follow the complete [Local Cashu paid test](references/local-cashu-test.md). It isolates `DVMKIT_CONFIG_DIR`, `DVMCTL_CONFIG_DIR`, and `DVM_CONFIG_DIR`; uses self-hosted `dvmctl serve --dvm` with Postgres; and proves Cashu advertisement, an unpaid 402, the paid result, receipt, and balance decrease.
+
+## 5. Decide before deployment
+
+After the local result and paid test work, show the approved brief, test result, and the exact files changed. Ask whether to prepare deployment. Only then follow the invitation's account and deployment instructions. Production rails, payout configuration, wallet connections, and real funds are separate decisions.
+
+## Reference routing
+
+- [Configure and job context](references/configure-context.md): descriptor shapes, context methods, artifacts, cancellation, and costs.
+- [Pricing and credit](references/pricing-credit.md): fiat pricing, quotes, and prepaid credit.
+- [Patterns and auth](references/patterns-auth.md): multi-turn handlers, signed requests, refunds, receipts, and custom routes.
+- [Testing](references/testing.md): schemas, unit contexts, and live-provider boundaries.
+- [Running and deployment](references/running-deployment.md): dev server, host options, persistence, environment, and deployment.
+- [Operating and feedback](references/operating-feedback.md): deployed-DVM operations, revenue, and caller feedback.
+- [Local Cashu paid test](references/local-cashu-test.md): prerequisites, expected behavior, and failures.
+- [Rail limits](references/payment-rails.md): what can and cannot be tested locally today.

package/skills/build-dvm/references/configure-context.md

@@ -0,0 +1,273 @@
+## Quickstart — scaffold with `dvmctl create`
+
+```bash
+dvmctl create my-dvm           # scaffolds ./my-dvm/
+cd my-dvm
+npm install
+npm test                       # the scaffold ships a passing test
+dvmctl dev handler.ts          # http://localhost:3000, hot reload, /_dev test page
+```
+
+> Zod ships with the SDK — `import { z } from "@dvmkit/sdk"` for typed `input:` schemas, no extra
+> install. Using the SDK's own zod guarantees a builder schema and the SDK validate against one
+> instance. Skip the schema and `ctx.input` is a raw string you parse yourself.
+
+`dvmctl create <name>` writes a standalone npm project:
+
+```
+my-dvm/
+  handler.ts        # your DVM — a configureDVM(...) descriptor (the file you edit)
+  serve.ts          # production entry point — calls serve(handler, {...})
+  handler.test.ts   # vitest unit tests
+  package.json      # depends on @dvmkit/sdk; scripts: test / dev / deploy
+  tsconfig.json
+  Dockerfile        # two-stage Node 22 build (add system deps here)
+  .env.example      # copy to .env for API keys / secrets
+  README.md
+```
+
+The generated `handler.ts` is a one-capability echo stub. Replace its `onJob` body with your
+logic; everything below is how to grow it.
+
+> **Self-hosting instead of deploying to the platform?** Run `dvmctl init <handle> --self-hosted`
+> once to generate a stable `canonical_dvm_id` and persist it to `~/.dvmkit/builder.json` (a
+> platform deploy assigns this ID for you at deploy time). You then `serve(dvm)` on your own
+> infrastructure.
+
+**Imports** (the SDK ships three entry points):
+
+```typescript
+import { configureDVM } from "@dvmkit/sdk"; // descriptor + types
+import { serve, createDVMHost } from "@dvmkit/sdk/server"; // hosting
+import { secp256k1Auth } from "@dvmkit/sdk/server"; // descriptor-level signed-request auth
+import { createTestContext } from "@dvmkit/sdk/testing"; // unit tests
+```
+
+---
+
+## Quick example — single-capability DVM
+
+`handler.ts`:
+
+```typescript
+import { configureDVM, z } from "@dvmkit/sdk";
+
+const inputSchema = z.object({ text: z.string() });
+
+export function createUppercaseDVM() {
+  return configureDVM({
+    name: "uppercase",
+    description: "Convert text to uppercase.",
+    capability: "uppercase",
+    tags: ["text", "uppercase"],
+    input: inputSchema,
+    price: "$0.01",
+
+    async onJob(ctx) {
+      ctx.complete(ctx.input.text.toUpperCase());
+    },
+  });
+}
+
+export default createUppercaseDVM();
+```
+
+`serve.ts`:
+
+```typescript
+import { serve } from "@dvmkit/sdk/server";
+import dvm from "./handler";
+
+await serve(dvm);
+```
+
+`serve(dvm)` reads all wiring (port, `DATABASE_URL`, `DVMKIT_CASHU_MINTS`, Tempo, x402, FX,
+platform reporter) from env. Pass `opts` to override; reach for `createDVMHost` when you need
+custom HTTP routes or to mount several DVMs on one host.
+
+---
+
+## configureDVM() reference
+
+```typescript
+configureDVM({
+  // --- DVM-level (always at top level) ---
+  name: string,
+  description?: string,
+  tag?: string,
+  tags?: string[],
+  idleTimeout?: number,        // seconds before auto-cancel (default: 3600)
+
+  auth?: DVMAuthScheme,        // descriptor-level signed-request auth (secp256k1Auth({...}))
+
+  onBoot?(env): void | Promise<void>,    // run once at server start
+  onShutdown?(): void | Promise<void>,   // run once at server stop
+  routes?(app: Hono): void | Promise<void>, // DVM-scoped non-protocol routes
+
+  paymentMethods?: PaymentMethod[],      // ["cashu" | "x402" | "tempo"]; auto-derived from configured rails
+
+  // --- Pick one of the two shapes below ---
+
+  // Flat single-capability shape (most DVMs):
+  capability?: string,                   // e.g. "synthesise" — names this one capability
+                                         // (auto-slugified from `name` if omitted)
+  input?: ZodSchema,                     // ctx.input is typed
+  state?: object,                        // ctx.state defaults, typed
+  price?: PriceValue,                    // "$0.05" — USD literal, the only form
+  onQuote?: QuoteConfig,                 // dynamic pricing
+  onJob(ctx): void | Promise<void>,      // required
+  onResponse?(ctx, content): void | Promise<void>,
+  onPayment?(ctx, content): void | Promise<void>,
+  onApproval?(ctx, content): void | Promise<void>,
+  onCancel?(ctx, content): void | Promise<void>,
+  onMessage?(ctx, msg): void | Promise<void>,
+
+  // OR multi-capability block (mutually exclusive with flat shape):
+  capabilities?: Record<string, CapabilityConfig>,
+});
+```
+
+`configureDVM` returns a frozen `DVMDescriptor`. The flat shape desugars internally to a
+one-entry `capabilities` map — `dvm.capabilities[<name>].onJob` works in either form (tests rely
+on this).
+
+### Per-capability fields (multi-capability shape)
+
+Each entry in `capabilities` accepts: `description`, `input`, `state`, `price`, `onQuote`,
+`onJob` (required), and the same message hooks (`onResponse`, `onPayment`, `onApproval`,
+`onCancel`, `onMessage`). DVM-level concerns (`name`, `description`, `tags`, `auth`,
+`paymentMethods`, `routes`, lifecycle hooks) stay on the parent and are shared across every
+capability.
+
+---
+
+## SDKJobContext reference
+
+### Identity (readonly)
+
+| Property      | Type                                | Description                                                                                               |
+| ------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `jobId`       | `string`                            | Server-assigned job ID                                                                                    |
+| `tags`        | `string[]`                          | Tags from the DVM descriptor                                                                              |
+| `input`       | `Input`                             | Job input (raw string, or parsed object when `input` schema is set)                                       |
+| `params`      | `Record<string, string>`            | Key-value parameters                                                                                      |
+| `requesterId` | `string`                            | Opaque requester ID (derived from auth or "anonymous")                                                    |
+| `paidMsats`   | `number`                            | Total msats paid so far                                                                                   |
+| `auth`        | `{ pubkey, envelope } \| undefined` | Verified caller identity — present only when the descriptor declares `auth: secp256k1Auth(...)` |
+
+### Messaging
+
+```typescript
+ctx.text(message: string): void
+ctx.artifact(content: ArtifactContent): void
+ctx.sendMessage(type: MessageType, content: object): void
+ctx.progress(percentComplete: number, phase?: string, hint?: string): void
+```
+
+`ArtifactContent`: `{ data: string, mime_type: string, name?: string, encoding?: "base64" }`
+
+### Flow control
+
+```typescript
+ctx.prompt(id: string, text: string, opts?): Promise<ResponseContent>
+ctx.requestPayment(
+  amount: number | { amount: number; currency: "usd" },
+  reason: string,
+  opts?: SDKPaymentRequestOpts,
+): Promise<PaymentContent>
+ctx.working(estimateSeconds?: number, hint?: string): void
+ctx.complete(summary: string): void                 // one-liner; artifacts carry the payload
+ctx.fail(error: string, opts?: { refund?: boolean }): void
+ctx.cost({ amount, currency }): void                 // your serving cost, in major units
+```
+
+`requestPayment` takes msats (`number`) or a fiat envelope (`{ amount, currency: "usd" }`) — the
+SDK converts to sats at send-time. The legacy `"$0.05"` string form was removed. On counter-based
+auto-credit, `requestPayment` resolves synchronously when the upfront pool already
+covers the amount and only suspends when the pool is exhausted. The caller sees whatever currency
+you name; the ledger records the charge in the DVM's own `currency`, converted at the moment the
+charge is made, so the anti-double-charge ceiling on the job's credit stays exact.
+
+Pass `{ refund: true }` to `ctx.fail` to return Cashu proofs to the caller — typical when the
+failure isn't operator fault (a network glitch, an upstream provider error). Don't refund on
+operator-fault failures (misconfiguration, your own upload failing). See [Refund-on-failure
+policy](patterns-auth.md#refund-on-failure-policy).
+
+### Cancellation — `ctx.signal`
+
+```typescript
+ctx.signal: AbortSignal           // aborts on caller cancel, idle timeout, stale sweep, supersession
+```
+
+Cancel is **terminal**: after it, `ctx.complete` / `ctx.fail` / `ctx.working` and the message
+emitters are no-ops that log a warning (a cancelled job can never come back as `completed`, and no
+revenue is booked on it), and `ctx.prompt` / `ctx.requestPayment` reject instead of hanging. This
+holds across machines — a terminal status is sticky in the job store and the runtime re-reads it
+before persisting, so a handler on a machine that never saw the cancel still can't overwrite it.
+
+### Report serving costs
+
+Use `ctx.cost({ amount, currency })` immediately after a paid provider call or other builder-side
+expense. Amounts are major units, repeated calls add, and only the job total is rounded to
+millionths. Every declaration in one job must use the same lowercase ISO currency; a mixed-currency
+job reports no total rather than guessing an exchange rate.
+
+No call means “unknown”; `{ amount: 0, currency: "usd" }` explicitly means free. Cost declarations
+inside `ctx.step()` are cached with the result and replay exactly once when the body is skipped, so
+declare the cost where it is incurred. Paid completions attach it to revenue, while free completions,
+failures, and cancellations use the separate cost-only report and create no revenue row.
+
+`ctx.fetch` already carries the signal — every request through it aborts on cancel, merged with any
+per-request signal you pass. Thread `ctx.signal` into everything else that can be torn down
+(provider SDK `signal` options, spawned processes, your own sleeps): that is where provider spend
+actually stops.
+
+```typescript
+async onJob(ctx) {
+  const audio = await client.tts.generate(text, { signal: ctx.signal });
+
+  for (const chunk of chunks) {
+    if (ctx.signal.aborted) return; // already terminal — don't call ctx.fail()
+    await process(chunk);
+  }
+
+  ctx.complete("Done");
+}
+```
+
+Return early on abort; the runtime has written the terminal status already. `onCancel` still fires if
+you declare one — use it for cleanup (release a lock, delete a staged upload); the signal is raised
+before the hook runs, so a slow cleanup can't hold the abort back.
+
+**`onCancel` is cleanup only — it can't emit.** The job is terminal before the hook runs, so a
+`ctx.text()` / `ctx.artifact()` / `ctx.complete()` inside it is ignored with a
+`ctx.<op>() ignored — job already cancelled` warning. Emit partial results as you go, not on the way
+out.
+
+**Multi-machine DVMs are covered.** On a DVM with `max_machines > 1`, a cancel that lands on a machine
+other than the one running the handler is committed to the store there; the machine running the
+handler subscribes to its own jobs' notifications, so it picks the cancel up within a notification
+round-trip — `ctx.signal` fires, `onCancel` runs on the machine holding the resources, the cancel
+lands in the job's message log, and the handler's late writes are rejected. Same behaviour whichever
+machine the cancel hits.
+
+**Isolate tier.** An isolate-hosted handler runs in its own Machine, so it learns of a cancel by
+polling its job's durable status on the platform (default every 2 s, `DVMKIT_ISOLATE_CANCEL_POLL_MS`).
+The contract above is identical — `ctx.signal` aborts, `ctx.fetch` tears down, emitters no-op, yields
+reject — just one poll tick behind the cancel.
+
+### Platform services
+
+```typescript
+ctx.state: State                  // typed from defaults; auto-persisted on every yield
+ctx.store: KVStore                // cross-job async KV storage
+ctx.fetch: typeof fetch           // instrumented fetch — dvm.fetch spans + auto-aborts on cancel
+ctx.env: Record<string, string>   // environment variables (read at job time, not boot)
+ctx.log: Logger                   // structured logging (.debug, .info, .warn, .error)
+ctx.step<T>(id: string, fn: () => Promise<T>): Promise<T>  // cached on yield
+```
+
+Prefer `ctx.fetch` over the global `fetch` for outbound HTTP: calls show up in traces, and they
+abort when the caller cancels the job.
+
+---

package/skills/build-dvm/references/local-cashu-test.md

@@ -0,0 +1,141 @@
+# Local Cashu paid test
+
+Use this only after the builder has approved both the DVM price and a separate dollar cap for this one test. A $0.01 DVM commonly needs a $0.02 cap because Cashu payments settle in whole satoshis. Do not infer approval or raise the cap after a refusal. This one shell session owns its temporary state, server process, Postgres container, and (unless `CASHU_MINT_URL` is supplied) FakeWallet container. It never stops an externally supplied mint.
+
+The handler must have the approved static USD price and produce a useful completion summary or `ctx.artifact`. Replace the variables with the approved brief. For a named artifact, specify its name and MIME type; for JSON, also specify expected keys from the approved example. Leave the name and MIME values empty only when the completion summary is the whole result. Use `--data` for an object input; a deliberately primitive string input uses `-i` in the final request instead.
+
+```bash
+set -euo pipefail
+
+DVM_HANDLE="my-dvm"
+DVM_CAPABILITY="uppercase"
+DVM_INPUT='{"text":"your approved example"}'
+DVM_PAYMENT_CAP='$0.02' # explicit approval for this test, separate from the $0.01 DVM price
+DVM_ARTIFACT_NAME="" # e.g. result.json; required when the handler emits an artifact
+DVM_ARTIFACT_MIME="" # e.g. application/json
+DVM_ARTIFACT_JSON_KEYS="" # comma-separated required keys, e.g. answer,language
+
+test_root="$(mktemp -d "${TMPDIR:-/tmp}/dvmkit-cashu-paid.XXXXXX")"
+export DVMKIT_CONFIG_DIR="$test_root/builder"
+export DVMCTL_CONFIG_DIR="$test_root/dvmctl"
+export DVM_CONFIG_DIR="$test_root/caller"
+mkdir -p "$DVMKIT_CONFIG_DIR" "$DVMCTL_CONFIG_DIR" "$DVM_CONFIG_DIR"
+
+postgres_name="dvmkit-cashu-postgres-$$"
+postgres_id=""
+mint_id=""
+dvm_pid=""
+cleanup() {
+  status=$?
+  trap - EXIT INT TERM
+  [ -z "$dvm_pid" ] || kill "$dvm_pid" 2>/dev/null || true
+  [ -z "$mint_id" ] || docker rm -f "$mint_id" >/dev/null 2>&1 || true
+  [ -z "$postgres_id" ] || docker rm -f "$postgres_id" >/dev/null 2>&1 || true
+  rm -rf "$test_root"
+  exit "$status"
+}
+trap cleanup EXIT
+trap 'exit 130' INT TERM
+
+docker run --rm -d --name "$postgres_name" -e POSTGRES_PASSWORD=paid-test \
+  -p 127.0.0.1::5432 postgres:17-alpine >/dev/null
+postgres_id="$(docker container inspect --format '{{.Id}}' "$postgres_name")"
+for _ in $(seq 1 30); do docker exec "$postgres_id" pg_isready -U postgres -d postgres >/dev/null 2>&1 && break; sleep 1; done
+docker exec "$postgres_id" pg_isready -U postgres -d postgres >/dev/null
+postgres_port="$(docker port "$postgres_id" 5432/tcp | sed -E 's/.*:([0-9]+)$/\1/')"
+export DATABASE_URL="postgresql://postgres:paid-test@127.0.0.1:${postgres_port}/postgres"
+
+if [ -n "${CASHU_MINT_URL:-}" ]; then
+  cashu_mint_url="$CASHU_MINT_URL"
+else
+  mint_name="dvmkit-cashu-mint-$$"
+  docker run --rm -d --name "$mint_name" -p 127.0.0.1::3338 \
+    -e MINT_LISTEN_HOST=0.0.0.0 -e MINT_LISTEN_PORT=3338 \
+    -e MINT_BACKEND_BOLT11_SAT=FakeWallet \
+    -e MINT_PRIVATE_KEY=test-key-do-not-use-in-production \
+    cashubtc/nutshell:0.19.2 poetry run mint >/dev/null
+  mint_id="$(docker container inspect --format '{{.Id}}' "$mint_name")"
+  cashu_mint_url="http://127.0.0.1:$(docker port "$mint_id" 3338/tcp | sed -E 's/.*:([0-9]+)$/\1/')"
+fi
+for _ in $(seq 1 30); do curl -fsS "$cashu_mint_url/v1/info" >"$test_root/mint-info.json" && break; sleep 1; done
+test -s "$test_root/mint-info.json"
+
+dvmctl lock create
+dvmctl identity create
+dvmctl init "$DVM_HANDLE" --self-hosted
+dvm_port="$(node -e 'require("node:net").createServer().listen(0, "127.0.0.1", function () { console.log(this.address().port); this.close(); })')"
+DVMKIT_CASHU_MINTS="$cashu_mint_url" dvmctl serve handler.ts --dvm "$DVM_HANDLE" --port "$dvm_port" >"$test_root/dvm.log" 2>&1 &
+dvm_pid=$!
+dvm_endpoint="http://127.0.0.1:$dvm_port"
+for _ in $(seq 1 30); do curl -fsS "$dvm_endpoint/v1/info" >"$test_root/info.json" && break; sleep 1; done
+test -s "$test_root/info.json"
+node -e 'const i=require(process.argv[1]); if (!i.payment?.methods?.includes("cashu")) throw new Error("/v1/info does not advertise cashu")' "$test_root/info.json"
+
+node -e 'process.stdout.write(JSON.stringify({capability:process.argv[1],data:JSON.parse(process.argv[2])}))' "$DVM_CAPABILITY" "$DVM_INPUT" >"$test_root/unpaid-request.json"
+unpaid_status="$(curl -sS -o "$test_root/unpaid.json" -w '%{http_code}' -H 'content-type: application/json' --data-binary @"$test_root/unpaid-request.json" "$dvm_endpoint/v1/job")"
+test "$unpaid_status" = 402
+
+npm install -g @dvmkit/dvm-cli@0.2.0
+dvm init
+dvm wallet init
+dvm wallet mint-add "$cashu_mint_url"
+dvm wallet fund '$1' --mint "$cashu_mint_url" --test-skip-lightning
+dvm wallet show >"$test_root/balance-before.json"
+dvm request --endpoint "$dvm_endpoint" --data "$DVM_INPUT" --rail cashu --mint "$cashu_mint_url" \
+  --budget "$DVM_PAYMENT_CAP" --auto-pay-below "$DVM_PAYMENT_CAP" \
+  --max-increment "$DVM_PAYMENT_CAP" --max-payments 1 </dev/null >"$test_root/paid.json"
+dvm wallet show >"$test_root/balance-after.json"
+node -e '
+const before=require(process.argv[1]).total_sats;
+const after=require(process.argv[2]).total_sats;
+const paid=require(process.argv[3]);
+if (!(typeof before === "number" && typeof after === "number" && after < before)) throw new Error("Cashu balance did not decrease");
+if (!paid.jobId || paid.next_action !== null || paid.receipt_verified !== "verified") throw new Error("paid receipt is not verified");
+if (paid.receipt?.outcome !== "completed" || paid.receipt?.paid?.rail !== "cashu" || !(paid.receipt.paid.msats > 0)) throw new Error("receipt does not prove a positive Cashu payment for a completed job");
+if (!(paid.summary || paid.has_artifacts)) throw new Error("paid result has no completion output");
+' "$test_root/balance-before.json" "$test_root/balance-after.json" "$test_root/paid.json"
+if [ -n "$DVM_ARTIFACT_NAME" ]; then
+  node -e 'if (!require(process.argv[1]).has_artifacts) throw new Error("expected artifact is missing")' "$test_root/paid.json"
+  test -n "$DVM_ARTIFACT_NAME" && test -n "$DVM_ARTIFACT_MIME"
+  case "$DVM_ARTIFACT_MIME" in application/json*) test -n "$DVM_ARTIFACT_JSON_KEYS" ;; esac
+  job_id="$(node -p 'require(process.argv[1]).jobId' "$test_root/paid.json")"
+  dvm messages "$job_id" --no-stream >"$test_root/artifacts.json"
+  cat "$test_root/artifacts.json"
+  node -e '
+const m=require(process.argv[1]).messages.filter((m) => m.type === "artifact");
+if (!m.length) throw new Error("artifact content is missing");
+const [name, mime, keys]=process.argv.slice(2);
+Promise.all(m.map(async ({content}) => {
+  let bytes;
+  if (typeof content?.data === "string" && content.data.length > 0) {
+    bytes=Buffer.from(content.data, content.encoding === "base64" ? "base64" : "utf8");
+  } else if (typeof content?.url === "string") {
+    const response=await fetch(content.url);
+    bytes=Buffer.from(await response.arrayBuffer());
+    if (!response.ok || bytes.byteLength === 0) throw new Error("artifact URL did not return content");
+  } else {
+    throw new Error("artifact content is missing");
+  }
+  const name=typeof content.name === "string" ? content.name :
+    content.name?._source === "provider" && typeof content.name.text === "string" ? content.name.text : undefined;
+  return {name, mime_type: content.mime_type, bytes_base64: bytes.toString("base64"), text: bytes.toString("utf8")};
+})).then((artifacts) => {
+  const artifact=artifacts.find((a) => a.name === name && a.mime_type === mime);
+  if (!artifact) throw new Error("expected artifact name or MIME type is missing");
+  if (keys) { const value=JSON.parse(artifact.text); for (const key of keys.split(",")) if (!(key in value)) throw new Error(`artifact JSON is missing ${key}`); }
+  console.log(JSON.stringify({artifact}));
+});' "$test_root/artifacts.json" "$DVM_ARTIFACT_NAME" "$DVM_ARTIFACT_MIME" "$DVM_ARTIFACT_JSON_KEYS" >"$test_root/artifact-content.json"
+  cat "$test_root/artifact-content.json"
+fi
+cat "$test_root/paid.json"
+```
+
+The final JSON is the evidence artifact: it must show a terminal paid job and verified Cashu receipt, while the assertions prove Cashu was advertised, the same unauthenticated request returned 402, and the isolated balance fell. When the approved result is a named artifact, the recipe fetches URL content or decodes inline data, then checks its name, MIME type, and expected JSON keys. Add a stricter assertion for any deeper approved schema before counting the test as passed; the generic recipe cannot infer it. The trap deletes only the state and processes this session created. The FakeWallet key and funds are test-only; do not point this recipe at a production mint.
+
+## Failure routing
+
+- `/v1/info` lacks `cashu`: do not retry with `dvmctl dev`. Confirm the three disposable configuration directories are exported, then rerun `lock create`, `identity create`, `init --self-hosted`, and `serve --dvm` in this session.
+- The unpaid request is not 402: confirm the handler's approved price and capability/input values before spending test money.
+- `fx_rate_unavailable` or `rate_unavailable`: the public BTC/USD rate provider could not answer. Wait for recovery before retrying, keeping the same approved dollar cap. A DVM-side test rate source does not configure the caller’s rate provider.
+- The paid request exceeds the cap: stop and ask for a new explicit dollar cap. Do not increase any flag automatically.
+- The mint cannot be reached: start the owned FakeWallet or correct `CASHU_MINT_URL`; an externally supplied mint remains outside this session's cleanup.