@dvmkit/sdk 0.5.0-rc.1 → 0.7.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-JH3SX3LY.js → chunk-6XF3RVVX.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-P6QON7ER.js";
 import {
   x402NetworkByCaip2
-} from "./chunk-RLTSCKRI.js";
+} from "./chunk-BPYMEMQX.js";
 import {
   diagnosticConsole
 } from "./chunk-ETXDTUJO.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
+};

package/dist/{chunk-RLTSCKRI.js → chunk-BPYMEMQX.js}

@@ -1,6 +1,49 @@
-import {
-  DvmError
-} from "./chunk-LIRAHP7B.js";
+// src/lib/errors.ts
+var DvmError = class extends Error {
+  constructor(code, message, hint, data, display, proseSources) {
+    super(message);
+    this.code = code;
+    this.hint = hint;
+    this.data = data;
+    this.display = display;
+    this.proseSources = proseSources;
+    this.name = "DvmError";
+  }
+  code;
+  hint;
+  data;
+  display;
+  proseSources;
+};
+function providerProseSources(...sources) {
+  const provenance = {};
+  for (const source of sources) {
+    if (!source) continue;
+    for (const field of ["message", "hint", "display"]) {
+      if (typeof source[field] === "string") provenance[field] = "provider";
+    }
+  }
+  return Object.keys(provenance).length > 0 ? provenance : void 0;
+}
+function isAbortError(err) {
+  return err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
+}
+function transportErrorCode(err) {
+  let current = err;
+  const seen = /* @__PURE__ */ new Set();
+  for (let depth = 0; depth < 5 && isErrorLike(current) && !seen.has(current); depth++) {
+    seen.add(current);
+    const code = current.code;
+    if (typeof code === "string" && /^(?:E[A-Z0-9_]{1,63}|UND_ERR_[A-Z0-9_]{1,63})$/.test(code)) {
+      return code;
+    }
+    current = current.cause;
+  }
+  return void 0;
+}
+function isErrorLike(value) {
+  return (typeof value === "object" || typeof value === "function") && value !== null;
+}
 
 // src/lib/x402/networks.ts
 var X402_NETWORKS = [
@@ -99,6 +142,10 @@ var BY_CAIP2 = new Map(X402_NETWORKS.map((n) => [n.caip2, n]));
 var BY_SLUG = new Map(X402_NETWORKS.map((n) => [n.slug, n]));
 
 export {
+  DvmError,
+  providerProseSources,
+  isAbortError,
+  transportErrorCode,
   X402_NETWORKS,
   x402NetworkByCaip2,
   x402NetworkBySlug,

package/dist/chunk-BQJIFRAZ.js

@@ -0,0 +1,36 @@
+// src/sdk/step-cache.ts
+var StepCache = class _StepCache {
+  cache = /* @__PURE__ */ new Map();
+  has(id) {
+    return this.cache.has(id);
+  }
+  get(id) {
+    return this.getRecord(id).value;
+  }
+  getRecord(id) {
+    const record = this.cache.get(id);
+    if (record === void 0) throw new Error(`StepCache: no cached result for step "${id}"`);
+    return record;
+  }
+  set(id, value, costs) {
+    this.cache.set(id, {
+      id,
+      value,
+      ...costs !== void 0 && costs.length > 0 ? { costs: costs.map(({ amount, currency }) => ({ amount, currency })) } : {}
+    });
+  }
+  serialize() {
+    return [...this.cache.values()];
+  }
+  static deserialize(records) {
+    const cache = new _StepCache();
+    for (const { id, value, costs } of records) {
+      cache.set(id, value, costs);
+    }
+    return cache;
+  }
+};
+
+export {
+  StepCache
+};

package/dist/{chunk-IWQHUSMO.js → chunk-CXCQLOOK.js}

@@ -1,7 +1,7 @@
 import {
   x402NetworkByCaip2,
   x402NetworkBySlug
-} from "./chunk-RLTSCKRI.js";
+} from "./chunk-BPYMEMQX.js";
 
 // src/lib/x402/constants.ts
 var X402_DEFAULT_FACILITATOR = "https://x402.org/facilitator";
@@ -204,6 +204,118 @@ function isOptionalRecord(value) {
   return value === void 0 || value === null || isRecord(value);
 }
 
+// src/defaults.ts
+import { homedir } from "os";
+import { join } from "path";
+var CONFIG_DIR = process.env.DVM_CONFIG_DIR ?? join(homedir(), ".dvm");
+var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+var CONFIG_BACKUP_FILE = join(CONFIG_DIR, "config.json.bak");
+var CONFIG_AUDIT_FILE = join(CONFIG_DIR, "config-audit.jsonl");
+var CONFIG_PINNED_FILE = join(CONFIG_DIR, "config.json.pinned");
+var JOBS_FILE = join(CONFIG_DIR, "jobs.json");
+var REQUEST_INTENTS_DIR = join(CONFIG_DIR, "request-intents");
+var FAVORITES_FILE = join(CONFIG_DIR, "favorites.json");
+var MESSAGES_DIR = join(CONFIG_DIR, "messages");
+var RECEIPTS_FILE = join(CONFIG_DIR, "receipts.jsonl");
+var CREDITS_FILE = join(CONFIG_DIR, "credits.json");
+var X402_CHANNELS_FILE = join(CONFIG_DIR, "x402-channels.json");
+var TEMPO_CHANNELS_FILE = join(CONFIG_DIR, "tempo-channels.json");
+var FEEDBACK_NUDGES_FILE = join(CONFIG_DIR, "feedback-nudges.json");
+var RECOVERY_MNEMONIC_FILE = join(CONFIG_DIR, "recovery.mnemonic");
+var WALLET_FILE = join(CONFIG_DIR, "wallet.json");
+var AGENT_MNEMONIC_FILE = join(CONFIG_DIR, "wallet.mnemonic");
+var IDENTITIES_FILE = join(CONFIG_DIR, "identities.json");
+var PAIRINGS_DIR = join(CONFIG_DIR, "pairings");
+var BUDGET_FILE = join(CONFIG_DIR, "budget.json");
+var BTC_RATE_FILE = join(CONFIG_DIR, "btc-rate.json");
+var ADMIN_DIR = join(CONFIG_DIR, "admin");
+var PROXY_STATE_FILE = join(ADMIN_DIR, "proxy.json");
+var BUILDER_CONFIG_DIR = process.env.DVMKIT_CONFIG_DIR ?? join(homedir(), ".dvmkit");
+var BUILDER_FILE = join(BUILDER_CONFIG_DIR, "builder.json");
+var BUILDER_MNEMONIC_FILE = join(BUILDER_CONFIG_DIR, "recovery.mnemonic");
+var BUILDER_KEY_FILE = join(BUILDER_CONFIG_DIR, "builder.key");
+var MELT_PENDING_LOG_FILE = join(BUILDER_CONFIG_DIR, "melt-pending.log");
+var DRAIN_PARK_LOG_FILE = join(BUILDER_CONFIG_DIR, "drain-park.log");
+var DRAIN_HOLD_STATE_FILE = join(BUILDER_CONFIG_DIR, "drain-hold.json");
+var MELT_SUCCESS_FILE = join(BUILDER_CONFIG_DIR, "melt-success.json");
+
+// src/lib/config-dir.ts
+import { chmodSync, mkdirSync, statSync } from "fs";
+var CONFIG_DIR_MODE = 448;
+function ensureConfigDir() {
+  ensureConfigSubdir(CONFIG_DIR);
+}
+function ensureConfigSubdir(path) {
+  mkdirSync(path, { recursive: true, mode: CONFIG_DIR_MODE });
+}
+function repairConfigDirMode() {
+  const base = {
+    path: CONFIG_DIR,
+    exists: false,
+    modeOctal: null,
+    repaired: false,
+    skippedNonPosix: process.platform === "win32"
+  };
+  if (base.skippedNonPosix) return base;
+  let mode;
+  try {
+    mode = statSync(CONFIG_DIR).mode & 511;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const missing = err.code === "ENOENT";
+    return missing ? base : { ...base, error: message };
+  }
+  if ((mode & 63) === 0) {
+    return { ...base, exists: true, modeOctal: toOctal(mode) };
+  }
+  try {
+    chmodSync(CONFIG_DIR, CONFIG_DIR_MODE);
+  } catch (err) {
+    return {
+      ...base,
+      exists: true,
+      modeOctal: toOctal(mode),
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+  return {
+    ...base,
+    exists: true,
+    modeOctal: toOctal(CONFIG_DIR_MODE),
+    previousModeOctal: toOctal(mode),
+    repaired: true
+  };
+}
+function toOctal(mode) {
+  return "0" + mode.toString(8).padStart(3, "0");
+}
+
+// src/lib/payment-rails/rpc.ts
+function resolveRpcOverride(envValue, bundled) {
+  const override = envValue?.trim() ?? "";
+  return override.length > 0 ? { url: override, source: "override" } : { url: bundled, source: "bundled" };
+}
+function resolveRpcHttpTransportOptions(source, envValue) {
+  if (source !== "override" || !envValue?.trim()) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(envValue);
+  } catch {
+    throw new Error("RPC headers must be a JSON object of non-empty string values.");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    throw new Error("RPC headers must be a JSON object of non-empty string values.");
+  const headers = {};
+  for (const [name, value] of Object.entries(parsed)) {
+    if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name) || typeof value !== "string" || value.length === 0 || /[\r\n]/.test(value))
+      throw new Error("RPC headers must be a JSON object of non-empty string values.");
+    headers[name] = value;
+  }
+  if (Object.keys(headers).length === 0)
+    throw new Error("RPC headers must be a JSON object of non-empty string values.");
+  return { fetchOptions: { headers } };
+}
+
 export {
   X402_DEFAULT_FACILITATOR,
   X402_VERSION,
@@ -226,5 +338,34 @@ export {
   encodePaymentRequiredHeader,
   decodePaymentRequiredHeader,
   exactEvmAuthorization,
-  encodeSettleResponseHeader
+  encodeSettleResponseHeader,
+  CONFIG_DIR,
+  CONFIG_FILE,
+  CONFIG_BACKUP_FILE,
+  CONFIG_AUDIT_FILE,
+  CONFIG_PINNED_FILE,
+  JOBS_FILE,
+  REQUEST_INTENTS_DIR,
+  FAVORITES_FILE,
+  MESSAGES_DIR,
+  RECEIPTS_FILE,
+  CREDITS_FILE,
+  X402_CHANNELS_FILE,
+  TEMPO_CHANNELS_FILE,
+  FEEDBACK_NUDGES_FILE,
+  RECOVERY_MNEMONIC_FILE,
+  WALLET_FILE,
+  AGENT_MNEMONIC_FILE,
+  IDENTITIES_FILE,
+  PAIRINGS_DIR,
+  BUDGET_FILE,
+  BTC_RATE_FILE,
+  BUILDER_CONFIG_DIR,
+  BUILDER_FILE,
+  BUILDER_KEY_FILE,
+  ensureConfigDir,
+  ensureConfigSubdir,
+  repairConfigDirMode,
+  resolveRpcOverride,
+  resolveRpcHttpTransportOptions
 };