@dvmkit/sdk 0.4.0-rc.1 → 0.6.0-rc.1

package/README.md

@@ -96,6 +96,12 @@ For Bitcoin credit monitoring, `GET /admin/credit/bitcoin-liability` reports exa
 
 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
+
+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.
+
 ## Repository development
 
 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.
@@ -182,3 +188,97 @@ None of this claims exclusive rights in the phrase "digital vending machine" or
 ## License
 
 Apache-2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
+
+## Job content retention and case holds
+
+`configureDVM` defaults `jobRetentionDays` to 730. Set a shorter or longer whole-day
+window explicitly, or `0` to disable automatic age expiry. Only completed, failed,
+and cancelled jobs are eligible. The terminal `lastActivityAt` is frozen: reads,
+receipt delivery, late messages, and re-saving an outcome do not renew it. The
+sweep removes input, params, summary, messages, state, caches, and bearer proofs;
+it preserves durable status, signed receipts, payment amounts, and recovery linkage.
+
+Authenticated job submit, request-result, status and JSON message responses expose
+`content_expires_at` (epoch milliseconds or `null`) and `content_available` (boolean).
+A null deadline means the job is active, expiry is disabled, or an active hold
+suppresses it. A past deadline can still have available content until the sweep
+runs. Missing fields on an older service or unsupported custom store mean unknown.
+SSE messages retain their existing event format; read job status for expiry.
+
+With durable service-admin configuration, use signed `Authorization: P2PK`
+requests on the service-local routes:
+
+| Method | Path | JSON body |
+| --- | --- | --- |
+| GET | `/admin/jobs/:jobId/content-holds` | none |
+| POST | `/admin/jobs/:jobId/content-holds` | `purpose`, `reason`, `review_due_at` |
+| POST | `/admin/jobs/:jobId/content-holds/:holdId/renew` | `reason`, `review_due_at` |
+| POST | `/admin/jobs/:jobId/content-holds/:holdId/clear` | `reason` |
+
+Purpose is `support` or `dispute`; reason is 1–1000 characters and review dates
+are future epoch millisecond integers. Unknown body fields are rejected. Hold IDs,
+actor public keys, and creation/clear times are server-derived. Authentication uses
+the existing method/path/service-bound admin challenge, current and grace-period
+keys, and atomic durable nonce consumption. A hold request does not grant access
+to job content. Authentication failure returns 401 with a reason; an unsupported
+store returns `content_holds_unavailable` (503), missing jobs return 404, and a
+redacted job or inactive hold returns 409. Holds cannot restore redacted content.
+
+Responses include `job_id`, caller content metadata, `baseline_content_expires_at`,
+`holds`, and append-only `events`. Each hold contains `id`, `job_id`, `purpose`,
+`reason`, original `actor`, `created_at`, `review_due_at`, `cleared_at`, and computed
+`review_overdue`. Each event contains `id`, `hold_id`, `job_id`, `action`, `actor`,
+`reason`, `at`, `review_due_at`. Renew and clear preserve the original actor and
+creation date; their authenticated actors are in history. Any active hold suppresses
+the effective deadline. Overdue review flags work; it does not release the hold.
+The baseline remains visible for review. Clearing the last hold restores the
+baseline and can make content immediately eligible for the next sweep.
+
+`PostgresJobStore.init()` adds `job_content_holds` and `job_content_hold_events`
+with job-scoped indexes; existing jobs need no expiry column or backfill. Placement
+and sweep lock the same job row and check redaction/terminal activity/active holds
+inside the transaction. Admin operations refuse jobs bound to another service;
+legacy unbound rows belong to the local service database. A committed hold wins any later competing sweep; if
+redaction wins first, placement fails. `MemoryJobStore` supplies the same contract
+for development. Custom stores must implement `ContentHoldStore` and atomic
+redaction fencing to support holds and truthful metadata.
+
+Before explicitly destroying a service database, use your existing database
+connection/proxy and the packaged `recipes/postgres/financial-export-v1.sql`:
+
+```sh
+psql "$DATABASE_URL" -X -q -t -A -v ON_ERROR_STOP=1 \
+  -f node_modules/@dvmkit/sdk/recipes/postgres/financial-export-v1.sql \
+  > financial-evidence.json
+```
+
+The versioned JSON export takes a consistent read-only snapshot and includes signed
+receipt tuples, ledger balances/amounts/currencies, job/payment links, and recovery
+outcomes. Funding lots preserve every deposit's original sats and credit basis,
+including depleted lots. Draws retain both the original allocation and settled
+amount. Refunds retain fulfilment costs and funding-lot linkage. Optional channel
+projections preserve amounts and settlement links while excluding authorization
+signatures and vouchers; Tempo bigint amounts are decimal strings.
+Unsigned JSON blocks use typed financial projections: unsupported fields and
+objects or arrays in scalar positions are excluded. Optional ledger tables absent from a service become empty arrays. It
+excludes raw input/output, bearer tokens/proofs, payout descriptors, and operational
+credentials. Signed receipts may retain their signed terminal reason and result
+hash; supported version-1 job, funding, and drain receipts are returned unchanged.
+Unsupported receipt versions, kinds, fields, or nested extensions fail the entire
+export before any JSON is emitted. Update the recipe for that schema before
+destruction; a failed export is not retained financial evidence. Verify receipt
+signatures and check the file before destruction, then keep it securely with this recipe
+and the service's public receipt-key attestation. The builder owns this export;
+the platform retains its separate financial history. An export does not settle
+caller balances or refunds: resolve liabilities through their existing lifecycle.
+Case holds affect age expiry, not explicit erasure or contract/lifecycle destruction.
+The active-service window does not extend any contractual maximum for copies after
+explicit destruction, including a 90-day post-destruction limit where applicable.
+
+The wire fields and routes are additive within protocol version 1. Existing explicit
+retention settings retain their value. The new default also applies to existing
+unredacted terminal rows; previously removed content stays unavailable. Upgrade
+all replicas before relying on holds: older SDKs do not recognize the hold fence.
+Do not downgrade or mix old replicas with active holds unless automatic sweeping
+is disabled on those replicas. The SQL export format is versioned independently
+of the package and is not a raw database backup or a content archive.

package/dist/{chunk-TXX4GOUB.js → chunk-7ZUKL4IV.js}

@@ -11,7 +11,7 @@ import {
 } from "./chunk-IWQHUSMO.js";
 import {
   usdcToMsats
-} from "./chunk-3MHE725Z.js";
+} from "./chunk-PAIM66YA.js";
 import {
   callerLoggers
 } from "./chunk-66HGCPBU.js";

package/dist/chunk-AFV77S4C.js

@@ -0,0 +1,258 @@
+import {
+  StepCache
+} from "./chunk-BQJIFRAZ.js";
+
+// src/sdk/server/job.ts
+function toJobRecord(job) {
+  return {
+    id: job.id,
+    tags: job.tags,
+    capability: job.capability,
+    input: job.input,
+    params: job.params,
+    requesterId: job.requesterId,
+    requesterTokenHash: job.requesterTokenHash,
+    requesterToken: job.requesterToken,
+    requestFingerprint: job.requestFingerprint,
+    requesterPubkey: job.requesterPubkey,
+    requestId: job.requestId,
+    authRequestPath: job.authRequestPath,
+    status: job.status,
+    summary: job.summary,
+    timingKnown: job.timingKnown,
+    endedBy: job.endedBy,
+    terminalAtMs: job.terminalAtMs,
+    callerWaitMs: job.callerWaitMs,
+    awaitingInputAtMs: job.awaitingInputAtMs,
+    messages: job.messages,
+    seq: job.seq,
+    paidMsats: job.paidMsats,
+    paymentMint: job.paymentMint,
+    paymentRail: job.paymentRail,
+    paymentTxHash: job.paymentTxHash,
+    paymentTransactionHash: job.paymentTransactionHash,
+    nativeAmount: job.nativeAmount,
+    nativeAsset: job.nativeAsset,
+    cashuFlow: job.cashuFlow,
+    costAmountMicro: job.costAmountMicro,
+    costCurrency: job.costCurrency,
+    costRevision: job.costRevision,
+    creditId: job.creditId,
+    drawId: job.drawId,
+    fundingReceipt: job.fundingReceipt,
+    fundingCredit: job.fundingCredit,
+    receivedProofs: job.receivedProofs,
+    pendingPaymentMsats: job.pendingPaymentMsats,
+    pendingMppChallengeIds: job.pendingMppChallengeIds,
+    pendingX402Nonce: job.pendingX402Nonce,
+    pendingX402AmountUsdcMicro: job.pendingX402AmountUsdcMicro,
+    pendingPaymentFiatMicro: job.pendingPaymentFiatMicro,
+    pendingPaymentFiatCurrency: job.pendingPaymentFiatCurrency,
+    askedTopUpMicro: job.askedTopUpMicro,
+    askedTopUpCurrency: job.askedTopUpCurrency,
+    topUpCapUnenforcedReason: job.topUpCapUnenforcedReason,
+    requiredMsats: job.requiredMsats,
+    receipt: job.receipt,
+    stepCache: job.stepCache.serialize(),
+    state: job.state,
+    createdAt: job.createdAt,
+    lastActivityAt: job.lastActivityAt
+  };
+}
+function fromJobRecord(record) {
+  return {
+    id: record.id,
+    tags: record.tags,
+    capability: record.capability,
+    input: record.input,
+    params: record.params,
+    requesterId: record.requesterId,
+    requesterTokenHash: record.requesterTokenHash,
+    status: record.status,
+    summary: record.summary,
+    timingKnown: record.timingKnown,
+    endedBy: record.endedBy,
+    terminalAtMs: record.terminalAtMs,
+    callerWaitMs: record.callerWaitMs,
+    awaitingInputAtMs: record.awaitingInputAtMs,
+    messages: [...record.messages],
+    seq: record.seq,
+    paidMsats: record.paidMsats,
+    paymentMint: record.paymentMint,
+    paymentRail: record.paymentRail,
+    paymentTxHash: record.paymentTxHash,
+    paymentTransactionHash: record.paymentTransactionHash,
+    nativeAmount: record.nativeAmount,
+    nativeAsset: record.nativeAsset,
+    cashuFlow: record.cashuFlow,
+    costAmountMicro: record.costAmountMicro,
+    costCurrency: record.costCurrency,
+    costRevision: record.costRevision,
+    creditId: record.creditId,
+    drawId: record.drawId,
+    fundingReceipt: record.fundingReceipt,
+    fundingCredit: record.fundingCredit,
+    receivedProofs: [...record.receivedProofs],
+    pendingPaymentMsats: record.pendingPaymentMsats,
+    pendingMppChallengeIds: record.pendingMppChallengeIds ? [...record.pendingMppChallengeIds] : void 0,
+    requesterToken: record.requesterToken,
+    requestFingerprint: record.requestFingerprint,
+    requesterPubkey: record.requesterPubkey,
+    requestId: record.requestId,
+    authRequestPath: record.authRequestPath,
+    pendingX402Nonce: record.pendingX402Nonce,
+    pendingX402AmountUsdcMicro: record.pendingX402AmountUsdcMicro,
+    pendingPaymentFiatMicro: record.pendingPaymentFiatMicro,
+    pendingPaymentFiatCurrency: record.pendingPaymentFiatCurrency,
+    askedTopUpMicro: record.askedTopUpMicro,
+    askedTopUpCurrency: record.askedTopUpCurrency,
+    topUpCapUnenforcedReason: record.topUpCapUnenforcedReason,
+    requiredMsats: record.requiredMsats,
+    receipt: record.receipt,
+    listeners: /* @__PURE__ */ new Set(),
+    abort: new AbortController(),
+    messageAppender: void 0,
+    messageAppenderTail: void 0,
+    stepCache: StepCache.deserialize(record.stepCache),
+    state: record.state,
+    pendingPrompts: /* @__PURE__ */ new Map(),
+    pendingPayment: null,
+    replayHighSeq: null,
+    replayProviderSkip: 0,
+    replayPaymentIndex: 0,
+    createdAt: record.createdAt,
+    lastActivityAt: record.lastActivityAt
+  };
+}
+function abortJob(job, reason) {
+  job.abort.abort(new JobCancelledError(reason));
+}
+var JobCancelledError = class extends Error {
+  constructor(message = "Job cancelled") {
+    super(message);
+    this.name = "JobCancelledError";
+  }
+};
+function providerMessage(job, type, content) {
+  if (job.replayProviderSkip > 0) {
+    job.replayProviderSkip--;
+    return;
+  }
+  const msg = localMessage(job, "provider", type, content);
+  if (type === "payment-request") {
+    const paymentRequest = content;
+    const pendingPaymentDelta = typeof paymentRequest.amount_msats === "number" ? paymentRequest.amount_msats : void 0;
+    const pendingMppChallengeIds = paymentRequest.tempo?.challenges?.map((challenge) => challenge.id).filter((id) => typeof id === "string");
+    job.messageAppender?.(msg, {
+      awaitingInput: job.status === "awaiting-input",
+      pendingPaymentDelta,
+      pendingMppChallengeIds,
+      pendingX402Nonce: typeof paymentRequest.x402?.nonce === "string" ? paymentRequest.x402.nonce : void 0,
+      pendingX402AmountUsdcMicro: typeof paymentRequest.x402?.required_usdc_micro === "string" ? paymentRequest.x402.required_usdc_micro : void 0,
+      // read off the job rather than the content — the fiat envelope
+      // is ledger state, not part of the wire shape, and `requestPayment` has
+      // already pinned it on the job by the time this fires (same ordering the
+      // `pendingPaymentMsats` comment above describes).
+      pendingPaymentFiatMicro: job.pendingPaymentFiatMicro,
+      pendingPaymentFiatCurrency: job.pendingPaymentFiatCurrency
+    });
+    return;
+  }
+  job.messageAppender?.(msg, type === "prompt" ? { awaitingInput: job.status === "awaiting-input" } : void 0);
+}
+function localMessage(job, from, type, content) {
+  job.seq++;
+  const msg = {
+    seq: job.seq,
+    from,
+    timestamp: Math.floor(Date.now() / 1e3),
+    type,
+    content
+  };
+  job.messages.push(msg);
+  for (const listener of job.listeners) {
+    listener(msg);
+  }
+  return msg;
+}
+function isTerminal(status) {
+  return status === "completed" || status === "failed" || status === "cancelled";
+}
+function isYieldMessage(msg) {
+  return msg.type === "prompt" || msg.type === "payment-request" || msg.type === "working" || msg.type === "complete" || msg.type === "cancel";
+}
+
+// src/sdk/server/content-retention.ts
+import { randomUUID } from "crypto";
+var ContentHoldError = class extends Error {
+  constructor(code) {
+    super(code);
+    this.code = code;
+  }
+  code;
+};
+function isContentHoldStore(store) {
+  return "getContentSnapshot" in store && "mutateContentHold" in store;
+}
+function contentMetadata(job, retentionDays, holds = []) {
+  const baseline = baselineContentExpiry(job, retentionDays);
+  return {
+    content_expires_at: holds.some((hold) => hold.cleared_at === null) ? null : baseline,
+    content_available: job.redactedAt === void 0
+  };
+}
+function baselineContentExpiry(job, retentionDays) {
+  return retentionDays > 0 && isTerminal(job.status) ? job.lastActivityAt + retentionDays * 864e5 : null;
+}
+function applyContentHoldMutation(job, history, mutation) {
+  if (job.redactedAt !== void 0) throw new ContentHoldError("content_unavailable");
+  const result = structuredClone(history);
+  let hold;
+  if (mutation.action === "placed") {
+    hold = {
+      id: randomUUID(),
+      job_id: job.id,
+      purpose: mutation.purpose,
+      reason: mutation.reason,
+      actor: mutation.actor,
+      created_at: mutation.at,
+      review_due_at: mutation.review_due_at,
+      cleared_at: null
+    };
+    result.holds.push(hold);
+  } else {
+    const existing = result.holds.find((item) => item.id === mutation.hold_id && item.cleared_at === null);
+    if (!existing) throw new ContentHoldError("hold_not_active");
+    hold = existing;
+    if (mutation.action === "cleared") hold.cleared_at = mutation.at;
+    else hold.review_due_at = mutation.review_due_at;
+    hold.reason = mutation.reason;
+  }
+  result.events.push({
+    id: randomUUID(),
+    hold_id: hold.id,
+    job_id: job.id,
+    action: mutation.action,
+    actor: mutation.actor,
+    reason: mutation.reason,
+    at: mutation.at,
+    review_due_at: hold.review_due_at
+  });
+  return result;
+}
+
+export {
+  toJobRecord,
+  fromJobRecord,
+  abortJob,
+  JobCancelledError,
+  providerMessage,
+  localMessage,
+  isTerminal,
+  isYieldMessage,
+  ContentHoldError,
+  isContentHoldStore,
+  contentMetadata,
+  baselineContentExpiry,
+  applyContentHoldMutation
+};