@dvmkit/sdk 0.7.0-rc.1 → 0.7.0-rc.10

package/README.md

@@ -92,12 +92,16 @@ Builders can pass `onPaidJobCompleted` to observe settled customer charges after
 - A `credit` block opts into reusable prepaid balances and their reclaim obligations. Reusable channels return undrawn collateral through their channel lifecycle; one-payment stablecoin funding is disabled unless `allowOneShotStablecoin: true` because it creates manual refunds. Run and monitor the documented reclaim/payout worker.
 - Honour `ctx.signal`, use `ctx.fetch` for abortable provider calls, and declare provider cost with `ctx.cost` only after the durable step that incurred it.
 
+Reusable x402 channels default to a 24-hour payer withdrawal grace (86400 seconds) on every network. For Base Sepolia (`eip155:84532`) acceptance tests, set `x402.batchSettlement.withdrawDelay: 900` or `DVMKIT_X402_WITHDRAW_DELAY_SECONDS=900` with `DVMKIT_X402_BATCH_SETTLEMENT=true`. Explicit delays must be integer seconds and at least 900 on Base Sepolia; Base mainnet retains the 86400 minimum even in development mode and still requires self-relay. The grace is bound into each channel's immutable configuration: changing the server setting affects new channels, not existing deposits. A shorter testnet run exercises early-withdrawal refusal and post-deadline recovery; retain a separate 24-hour run to cover next-day recovery.
+
 For Bitcoin credit monitoring, `GET /admin/credit/bitcoin-liability` reports exact in-kind obligations in satoshis. Uncovered and basisless credits need live-rate pricing on reclaim, so their whole balances appear in `uncovered_by_currency` and `unbacked_by_currency` as `{ currency, micro, credits }` entries. Sum the credit counts if useful, but display or price each currency separately. Older consumers must replace the former `uncovered_micro` and `unbacked_micro` scalar reads; the [portable response fixture](./protocol-fixtures/bitcoin-liability.json) shows the full shape.
 
 The public [SDK guide](https://dvmkit.com/docs/sdk) covers signed requests, custom routes, rail configuration, credit reclaim, persistence, and deployment in depth. The [protocol guide](https://dvmkit.com/docs/protocol) specifies the HTTP contract.
 
 ## Diagnostic retention
 
+[Payment diagnostics](./docs/DIAGNOSTICS.md) documents the closed failure categories, stages, and top-up causes retained by safe logging sinks.
+
 The SDK advertises 730 days of retention for sanitized diagnostics in every existing span dataset: `platform`, `cashu`, `lightning`, `stripe`, `x402`, `tempo`, `isolate`, `audit`, and `cron`. Dataset names, producer permissions, and query semantics remain unchanged; only operator services may write to `audit`.
 
 This metadata describes the retention schedule. The SDK does not automatically delete diagnostics or override platform destruction or case controls. The platform must enforce the schedule and those controls.
@@ -106,7 +110,7 @@ This metadata describes the retention schedule. The SDK does not automatically d
 
 Use the Node.js release in `.nvmrc` (Node 22). Install with `npm ci`, then run the same gate CI runs with `npm run verify`. The gate checks repository metadata in the checkout, copies only tracked and unignored source into an isolated directory, installs its locked dependencies, and runs lint, build, typecheck (including the release scripts under `checkJs`), unit and database tests, API, package, consumer, packed-artifact safety, and release checks there. The clean source tree owns the complete build and test pass, so verification never depends on the checkout's `node_modules` or pre-existing `dist` and does not repeat the full suite; after every check passes, its verified `dist` replaces the checkout's build output for release packaging.
 
-`DATABASE_URL` is optional locally. Without it the database suite is skipped rather than passed, and `verify` says so in its summary, because a skipped suite verified nothing and must not be reported as green. Point `DATABASE_URL` at a scratch Postgres to run it, and pass `npm run verify -- --require-database` to make a missing one a failure, which is what CI does.
+`DATABASE_URL` is optional locally. Without it the database suite is skipped rather than passed, and `verify` says so in its summary, because a skipped suite verified nothing and must not be reported as green. Point `DATABASE_URL` at a scratch Postgres to run it, and pass `npm run verify -- --require-database` to make a missing one a failure, which is what CI does. That mode also requires the local test mint started by `node scripts/start-cashu-mint.mjs`.
 
 The public surface is exactly `@dvmkit/sdk`, `@dvmkit/sdk/server`, and `@dvmkit/sdk/testing`.
 
@@ -146,6 +150,10 @@ The same values are accepted as `--endpoint <url>` and `--job-token <hex>`. Thes
 
 If an upgrade broke something for you, an [API compatibility report](https://github.com/dvmkit/sdk/issues/new/choose) is the most useful thing you can send us. It tells us which parts of the published surface people actually build on, which no test of ours can.
 
+## Job identity field
+
+Every 200 or 202 response to `POST /v1/job`, `POST /v1/request-resume/:id` and `POST /v1/request-result/:id` carries a `DVM-Job-Identity-V1` response-head field whose value is the body's `job_id`, byte for byte, so a router or caller can learn which job a response names without reading a body of any size. No other status carries it. The value grammar is `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`; a server whose job ID falls outside it sends no field. A reader takes the value from `Headers.get`, trims nothing and never folds case: a repeated field (joined with `", "`), an empty value or any other character is invalid, and a trailer of the same name is never identity. The portable contract and its classification vectors are in `protocol-fixtures/job-identity-v1.json`. Hosting control's status reports `jobIdentityHeader: "v1"` when the deployment emits the field.
+
 ## Per-job costs
 
 A handler can declare what a job cost **you**, the builder, to serve — a vendor API call, a GPU minute, a per-request licence fee — and the SDK reports it to the platform alongside what the caller paid, so your dashboard can state a margin instead of guessing at one.
@@ -167,7 +175,36 @@ Three things worth knowing:
 - **Declare the cost where you incur it, including inside `ctx.step`.** The step cache carries those declarations with the result and applies them once when a replay skips the body.
 - **Every terminal job reports its declared cost.** A paid completion carries the cost on its revenue report. A free completion, failure, or cancellation sends a separate cost-only report and does not create revenue.
 
-The cost is yours, never the caller's: it is recorded separately from what the caller paid and is never netted against it. Both report shapes use the same durable outbox. Cost-only reports are keyed on the job id and revisioned, so retries and cross-machine updates converge on the latest cumulative value. With the Postgres job store, boot-time and periodic reconciliation enqueue any terminal cost revision that a process exited before reporting.
+The cost is yours, never the caller's: it is recorded separately from what the caller paid and is never netted against it. Both report shapes use the same durable outbox. Cost-only reports are keyed on the job id and revisioned, so retries and cross-machine updates converge on the latest cumulative value. With the Postgres job store, boot-time and periodic reconciliation enqueue any terminal cost revision that a process exited before reporting. Other job stores get no reconciliation: their cost-only report is durable only once the outbox insert commits, so an exit between the terminal save and that insert loses it.
+
+## Rate cards
+
+A priced capability can tell callers what it charges per unit, so an agent can explain the price before it asks for a quote. Declare `rates` next to `price` or `onQuote`, in the flat shape or on an entry in `capabilities`:
+
+```ts
+capabilities: {
+  synthesise: {
+    onQuote: { schema, handler: quoteBySize },
+    rates: [
+      { label: "balanced", amount: "0.00015", currency: "USD", per: "character" },
+      { label: "expressive", amount: "0.00030", currency: "USD", per: "character" },
+    ],
+    onJob,
+  },
+},
+```
+
+`/v1/info` publishes the list as `capabilities.<name>.pricing.rates`, exactly as you wrote it: same order, same strings. A capability without `rates` publishes nothing extra. For a quoted capability the rates describe how your quote is computed; the SDK does not compute or check quotes against them, so keep the two in step yourself.
+
+The server refuses to start, naming the capability and the entry, when a rate card breaks one of these limits:
+
+- 1 to 5 entries, on a capability with `price` or `onQuote`. A free capability cannot declare rates.
+- `amount` is decimal dollars as a string, above zero and at most 12 characters: `"0.00015"`, not `0.00015` or `"$0.00015"`.
+- `currency` is `"USD"`.
+- `per` names the unit (`"character"`, `"episode"`, `"GB per day stored"`) and `label`, which is optional, names a tier. Each is 1 to 24 characters with no leading or trailing spaces.
+- No other keys.
+
+The [portable fixture](./protocol-fixtures/capability-rates.json) carries the same limits and the accepted and refused examples, for clients that parse the field.
 
 ## Contributing
 

package/dist/{chunk-S3OY533W.js → chunk-2NUFE2PG.js}

@@ -1,9 +1,34 @@
 import {
   X402_DEFAULT_FACILITATOR
-} from "./chunk-CXCQLOOK.js";
+} from "./chunk-62FI3NJF.js";
 import {
   callerLoggers
 } from "./chunk-66HGCPBU.js";
+import {
+  diagnosticConsole
+} from "./chunk-ZCNPIILZ.js";
+
+// src/observability/payment-diagnostics.ts
+import { AsyncLocalStorage } from "async_hooks";
+var scopes = new AsyncLocalStorage();
+function withPaymentDiagnostics(fn) {
+  return scopes.run({}, fn);
+}
+async function withPaymentStage(stage, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    const scope = scopes.getStore();
+    if (scope && (!scope.failure || !Object.is(scope.failure.error, error))) {
+      scope.failure = { error, stage };
+    }
+    throw error;
+  }
+}
+function paymentFailureStage(error) {
+  const failure = scopes.getStore()?.failure;
+  return failure && Object.is(failure.error, error) ? failure.stage : "unknown";
+}
 
 // src/lib/x402/facilitator.ts
 import { createPrivateKey, randomBytes } from "crypto";
@@ -82,7 +107,7 @@ async function verifyWithFacilitator(payload, requirements, config = {}, createA
   return callerLoggers.x402.span(
     "x402.verify_with_facilitator",
     { facilitator_url: url },
-    async () => {
+    () => withPaymentStage("verifier", async () => {
       const authHeaders = (await createAuthHeaders?.())?.verify ?? {};
       const res = await fetch(url, {
         method: "POST",
@@ -96,14 +121,17 @@ async function verifyWithFacilitator(payload, requirements, config = {}, createA
       if (!res.ok) {
         const rejection = await readFacilitatorRejection(res);
         if (rejection?.isValid === false && typeof rejection.invalidReason === "string" && rejection.invalidReason.length > 0) {
+          logRejected("verifier");
           return rejection;
         }
+        logRejected("verifier");
         return { isValid: false, invalidReason: `facilitator_status_${res.status}` };
       }
       const data = await res.json();
+      if (!data.isValid) logRejected("verifier");
       callerLoggers.x402.info("x402.verify_with_facilitator.result", { is_valid: data.isValid });
       return data;
-    }
+    })
   );
 }
 async function settleWithFacilitator(payload, requirements, config = {}, createAuthHeaders = createX402FacilitatorAuthHeaders(config)) {
@@ -112,7 +140,7 @@ async function settleWithFacilitator(payload, requirements, config = {}, createA
   return callerLoggers.x402.span(
     "x402.settle_with_facilitator",
     { facilitator_url: url },
-    async () => {
+    () => withPaymentStage("broadcast", async () => {
       const authHeaders = (await createAuthHeaders?.())?.settle ?? {};
       const res = await fetch(url, {
         method: "POST",
@@ -126,17 +154,20 @@ async function settleWithFacilitator(payload, requirements, config = {}, createA
       if (!res.ok) {
         const rejection = await readFacilitatorRejection(res);
         if (rejection?.success === false && typeof rejection.errorReason === "string" && rejection.errorReason.length > 0) {
+          logRejected("broadcast");
           return rejection;
         }
+        logRejected("broadcast");
         return { success: false, errorReason: `facilitator_status_${res.status}` };
       }
       const data = await res.json();
+      if (!data.success) logRejected("broadcast");
       callerLoggers.x402.info("x402.settle_with_facilitator.result", {
         success: data.success,
         tx_hash: data.transaction
       });
       return data;
-    }
+    })
   );
 }
 async function readFacilitatorRejection(res) {
@@ -151,8 +182,19 @@ async function readFacilitatorRejection(res) {
 function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+function logRejected(stage) {
+  diagnosticConsole.warn({
+    event: "x402_credential_rejected",
+    rail: "x402",
+    failure_category: stage === "verifier" ? "verification_failed" : "settlement_failed",
+    failure_stage: stage
+  });
+}
 
 export {
+  withPaymentDiagnostics,
+  withPaymentStage,
+  paymentFailureStage,
   createX402FacilitatorAuthHeaders,
   createX402FacilitatorClient,
   verifyWithFacilitator,

package/dist/{chunk-RA2WIX7G.js → chunk-3E4C6W7W.js}

@@ -2,19 +2,20 @@ import {
   createX402FacilitatorAuthHeaders,
   settleWithFacilitator,
   verifyWithFacilitator
-} from "./chunk-S3OY533W.js";
-import {
-  usdcToMsats
-} from "./chunk-NFMOPYBA.js";
+} from "./chunk-2NUFE2PG.js";
 import {
   buildPaymentRequirements,
   decodePayment,
   encodeSettleResponseHeader,
-  exactEvmAuthorization
-} from "./chunk-CXCQLOOK.js";
+  exactEvmAuthorization,
+  usdcToMsats
+} from "./chunk-62FI3NJF.js";
 import {
   callerLoggers
 } from "./chunk-66HGCPBU.js";
+import {
+  diagnosticConsole
+} from "./chunk-ZCNPIILZ.js";
 
 // src/lib/x402/verify.ts
 async function verifyX402Payment(paymentHeader, config, requiredUsdcMicro, resource, btcUsdRate, exactVersions = { v1: true, v2: true }) {
@@ -30,9 +31,11 @@ async function verifyX402Payment(paymentHeader, config, requiredUsdcMicro, resou
       try {
         payload = decodePayment(paymentHeader);
       } catch {
+        logRejected("malformed_credential", "verifier");
         return { verified: false, amountMsats: 0, invalidReason: "decode_failed" };
       }
       if (payload.x402Version === 1 && !exactVersions.v1 || payload.x402Version === 2 && !exactVersions.v2) {
+        logRejected("unsupported_version", "verifier");
         return { verified: false, amountMsats: 0, invalidReason: "unsupported_version" };
       }
       const requirementOpts = { x402Config: config, requiredUsdcMicro, resource };
@@ -81,6 +84,14 @@ async function verifyX402Payment(paymentHeader, config, requiredUsdcMicro, resou
     }
   );
 }
+function logRejected(category, stage) {
+  diagnosticConsole.warn({
+    event: "x402_credential_rejected",
+    rail: "x402",
+    failure_category: category,
+    failure_stage: stage
+  });
+}
 
 export {
   verifyX402Payment