@dvmkit/sdk 0.3.4-rc.10 → 0.5.0-rc.1

package/dist/{chunk-C2AGARLM.js → chunk-B2IROPQF.js}

@@ -1,47 +1,14 @@
 import {
-  IMPLICIT_CREDIT_TTL_MS
-} from "./chunk-A4CM2BD3.js";
+  IMPLICIT_CREDIT_TTL_MS,
+  isDrainReceipt
+} from "./chunk-PAIM66YA.js";
 import {
   CREDITS_FILE,
-  DvmError,
   ensureConfigDir
-} from "./chunk-MKI6OVW4.js";
-
-// src/lib/output.ts
-import { writeSync } from "fs";
-var _traceId = null;
-function setOutputTraceId(id) {
-  _traceId = id;
-}
-function getOutputTraceId() {
-  return _traceId;
-}
-function json(data) {
-  const out = _traceId !== null && typeof data === "object" && data !== null && !Array.isArray(data) && !("trace_id" in data) ? { trace_id: _traceId, ...data } : data;
-  writeAllSync(1, JSON.stringify(out) + "\n");
-}
-function info(msg) {
-  writeAllSync(2, msg + "\n");
-}
-function raw(msg) {
-  writeAllSync(1, msg + "\n");
-}
-function progress(event) {
-  writeAllSync(2, JSON.stringify(event) + "\n");
-}
-function writeAllSync(fd, text) {
-  const buf = Buffer.from(text, "utf8");
-  let offset = 0;
-  while (offset < buf.length) {
-    try {
-      offset += writeSync(fd, buf, offset, buf.length - offset);
-    } catch (err) {
-      const code = err.code;
-      if (code === "EAGAIN" || code === "EINTR") continue;
-      throw err;
-    }
-  }
-}
+} from "./chunk-CZULM42S.js";
+import {
+  DvmError
+} from "./chunk-LIRAHP7B.js";
 
 // src/lib/payment-rails/types.ts
 var RAIL_FLAGS = ["cashu", "tempo", "x402"];
@@ -55,9 +22,9 @@ function withinAdvertisedTolerance(advertisedMicro, localMicro) {
 
 // src/lib/transport/types.ts
 var SUPPORTED_PROTOCOL_VERSION = 1;
-function parseCreditTerms(raw2) {
-  if (!raw2 || typeof raw2 !== "object" || Array.isArray(raw2)) return void 0;
-  const credit = raw2;
+function parseCreditTerms(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const credit = raw;
   if (typeof credit.min_micro !== "number" || typeof credit.max_micro !== "number" || typeof credit.ttl_ms !== "number" || typeof credit.currency !== "string" || !Array.isArray(credit.funding) || !credit.funding.every((method) => typeof method === "string") || credit.lightning_min_micro !== void 0 && typeof credit.lightning_min_micro !== "number")
     return void 0;
   const tempo = credit.tempo === void 0 ? void 0 : parseCreditTempoTerms(credit.tempo);
@@ -77,10 +44,10 @@ function parseCreditTerms(raw2) {
     }
   };
 }
-function parseCreditMenu(raw2) {
-  const terms = parseCreditTerms(raw2);
+function parseCreditMenu(raw) {
+  const terms = parseCreditTerms(raw);
   if (!terms) return void 0;
-  const credit = raw2;
+  const credit = raw;
   return {
     ...terms,
     ...typeof credit.credit_id === "string" && { credit_id: credit.credit_id },
@@ -91,9 +58,9 @@ function parseCreditMenu(raw2) {
     ...typeof credit.expiry_ms === "number" && { expiry_ms: credit.expiry_ms }
   };
 }
-function parseCreditTempoTerms(raw2) {
-  if (!raw2 || typeof raw2 !== "object" || Array.isArray(raw2)) return void 0;
-  const block = raw2;
+function parseCreditTempoTerms(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const block = raw;
   if (!Array.isArray(block.methods) || !block.methods.every(isCreditTempoMethod)) return void 0;
   if (block.withheld !== void 0 && (!Array.isArray(block.withheld) || !block.withheld.every(isCreditTempoWithheldMethod)))
     return void 0;
@@ -111,15 +78,15 @@ function parseCreditTempoTerms(raw2) {
     }
   };
 }
-function isCreditTempoMethod(raw2) {
-  return !!raw2 && typeof raw2 === "object" && typeof raw2.method === "string" && (raw2.intent === "charge" || raw2.intent === "session");
+function isCreditTempoMethod(raw) {
+  return !!raw && typeof raw === "object" && typeof raw.method === "string" && (raw.intent === "charge" || raw.intent === "session");
 }
-function isCreditTempoWithheldMethod(raw2) {
-  return isCreditTempoMethod(raw2) && typeof raw2.reason === "string";
+function isCreditTempoWithheldMethod(raw) {
+  return isCreditTempoMethod(raw) && typeof raw.reason === "string";
 }
-function parseCreditX402Terms(raw2) {
-  if (!raw2 || typeof raw2 !== "object" || Array.isArray(raw2)) return void 0;
-  const schemes = raw2.schemes;
+function parseCreditX402Terms(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const schemes = raw.schemes;
   if (!Array.isArray(schemes) || !schemes.every(
     (entry) => !!entry && typeof entry === "object" && typeof entry.scheme === "string" && typeof entry.network === "string"
   ))
@@ -133,9 +100,348 @@ function parseCreditX402Terms(raw2) {
 }
 
 // src/lib/credit-store.ts
-import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "fs";
+import { existsSync, readFileSync as readFileSync2, renameSync, unlinkSync, writeFileSync } from "fs";
 import { dirname } from "path";
 import lockfile from "proper-lockfile";
+
+// src/lib/credit-history.ts
+import { createHash } from "crypto";
+import {
+  closeSync,
+  fsyncSync,
+  openSync,
+  readFileSync,
+  writeSync,
+  ftruncateSync
+} from "fs";
+function historyPath() {
+  return `${CREDITS_FILE.slice(0, -5)}-history.jsonl`;
+}
+function hash(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function fail(detail) {
+  throw new DvmError(
+    "credit_history_unavailable",
+    `Completed credit history could not be preserved: ${detail}`,
+    "Keep the credit store and history file intact, fix the file access or damage, and retry. Working evidence was not evicted."
+  );
+}
+var receiptKeys = /* @__PURE__ */ new Set([
+  "v",
+  "kind",
+  "credit_id",
+  "drain_id",
+  "event",
+  "method",
+  "amount_micro",
+  "balance_after_micro",
+  "ledger_seq",
+  "issued_at",
+  "caller_pubkey",
+  "dvm_id",
+  "dvm",
+  "receipt_pubkey",
+  "signature"
+]);
+var attestationKeys = /* @__PURE__ */ new Set([
+  "dvm_id",
+  "slug",
+  "capabilities_hash",
+  "builder_pubkey",
+  "receipt_pubkey",
+  "deployed_at"
+]);
+function safeReceipts(bundle) {
+  const receipts = [];
+  for (const receipt of bundle.receipts) {
+    if (!isDrainReceipt(receipt))
+      fail("a completed bundle contains an unrecognized receipt");
+    if (Object.keys(receipt).some((key) => !receiptKeys.has(key)))
+      fail("a receipt contains unsupported fields");
+    if (Object.values(receipt).some(
+      (value) => typeof value !== "string" && typeof value !== "number" || typeof value === "number" && (!Number.isSafeInteger(value) || value < 0)
+    ))
+      fail("a receipt contains unsupported values");
+    receipts.push(receipt);
+  }
+  return receipts;
+}
+function safeAnchor(anchor) {
+  if (!anchor) return void 0;
+  if (typeof anchor.pubkey !== "string" || typeof anchor.signature !== "string" || !anchor.attestation || Object.keys(anchor.attestation).some((key) => !attestationKeys.has(key)) || Object.values(anchor.attestation).some(
+    (value) => typeof value !== "string" && typeof value !== "number"
+  ))
+    fail("an advertisement contains unsupported fields");
+  return {
+    pubkey: anchor.pubkey,
+    signature: anchor.signature,
+    attestation: anchor.attestation
+  };
+}
+function hasAttestedIdentity(record) {
+  return Boolean(record.dvmId && record.attestedBuilderPubkey);
+}
+function compatibleLocations(left, right) {
+  if (hasAttestedIdentity(left) && hasAttestedIdentity(right))
+    return left.dvmId === right.dvmId && left.attestedBuilderPubkey === right.attestedBuilderPubkey;
+  return [left.endpoint, ...left.endpointAliases].some(
+    (origin) => [right.endpoint, ...right.endpointAliases].includes(origin)
+  );
+}
+function base(record, identity, occurredAt) {
+  return {
+    v: 1,
+    id: hash(
+      JSON.stringify([
+        record.callerPubkey,
+        hasAttestedIdentity(record) ? record.dvmId : record.endpoint,
+        hasAttestedIdentity(record) ? record.attestedBuilderPubkey : null,
+        record.creditId,
+        identity
+      ])
+    ),
+    endpoint: record.endpoint,
+    endpointAliases: record.endpointAliases ?? [],
+    dvmId: record.dvmId ?? null,
+    attestedBuilderPubkey: record.attestedBuilderPubkey ?? null,
+    callerPubkey: record.callerPubkey,
+    creditId: record.creditId,
+    occurredAt,
+    rail: null,
+    currency: null,
+    amountMicro: null,
+    feeMicro: null
+  };
+}
+function completedRefund(record, bundle) {
+  const receipts = safeReceipts(bundle);
+  const anchor = safeAnchor(bundle.anchor);
+  const receipt = receipts.find(
+    (r) => r.drain_id === bundle.drainId && r.credit_id === bundle.creditId
+  );
+  const metadata = bundle.settlement;
+  if (metadata && (metadata.rail !== null && typeof metadata.rail !== "string" || metadata.currency !== null && typeof metadata.currency !== "string" || [metadata.amountMicro, metadata.feeMicro].some(
+    (value) => value !== null && (!Number.isSafeInteger(value) || value < 0)
+  )))
+    fail("invalid settlement metadata");
+  return {
+    ...base(
+      { ...record, creditId: bundle.creditId },
+      `refund:${bundle.drainId}`,
+      bundle.settledAt
+    ),
+    kind: "completed_refund",
+    outcome: "refunded",
+    drainId: bundle.drainId,
+    settledAt: bundle.settledAt,
+    collectedAt: bundle.collectedAt === 0 ? null : bundle.collectedAt,
+    rail: metadata?.rail ?? receipt?.method ?? null,
+    currency: metadata?.currency ?? null,
+    amountMicro: metadata?.amountMicro ?? receipt?.amount_micro ?? null,
+    feeMicro: metadata?.feeMicro ?? null,
+    receipts,
+    ...anchor ? { anchor } : {},
+    provenance: {
+      settlement: "local_observation",
+      receipts: "unverified_observations",
+      advertisement: anchor ? "present" : "absent"
+    }
+  };
+}
+function completedLoss(record) {
+  return {
+    ...base(record, "loss", record.updatedAt),
+    kind: "expired_credit_loss",
+    outcome: "lost",
+    rail: record.creditId.startsWith("imp:") ? record.creditId.split(":")[1] || null : null,
+    currency: record.currency,
+    amountMicro: record.remainingMicro,
+    reason: record.lossReason ?? "expired",
+    releasedAt: record.releasedAt,
+    expiryMs: record.expiryMs,
+    releasedByJobId: record.releasedByJobId
+  };
+}
+function validateHistoryRecord(row) {
+  if (!row || row.v !== 1 || typeof row.id !== "string" || !Number.isSafeInteger(row.occurredAt) || typeof row.endpoint !== "string" || typeof row.callerPubkey !== "string" || typeof row.creditId !== "string" || !Array.isArray(row.endpointAliases) || row.endpointAliases.some((value) => typeof value !== "string") || [row.dvmId, row.attestedBuilderPubkey, row.currency, row.rail].some(
+    (value) => value !== null && typeof value !== "string"
+  ) || [row.amountMicro, row.feeMicro].some(
+    (value) => value !== null && (!Number.isSafeInteger(value) || value < 0)
+  ))
+    fail("invalid complete journal entry");
+  if (row.kind === "completed_refund") {
+    if (row.outcome !== "refunded" || typeof row.drainId !== "string" || !Number.isSafeInteger(row.settledAt) || row.collectedAt !== null && !Number.isSafeInteger(row.collectedAt) || !Array.isArray(row.receipts) || row.provenance?.settlement !== "local_observation" || row.provenance.receipts !== "unverified_observations" || !["present", "absent"].includes(row.provenance.advertisement))
+      fail("invalid refund entry");
+    safeReceipts({
+      drainId: row.drainId,
+      creditId: row.creditId,
+      receipts: row.receipts,
+      collectedAt: row.collectedAt ?? 0
+    });
+    safeAnchor(row.anchor);
+  } else if (row.kind === "expired_credit_loss") {
+    if (row.outcome !== "lost" || !["expired", "not_found"].includes(row.reason) || !Number.isSafeInteger(row.releasedAt) || !Number.isSafeInteger(row.expiryMs) || typeof row.releasedByJobId !== "string")
+      fail("invalid loss entry");
+  } else fail("invalid complete journal entry");
+}
+function journal() {
+  let bytes;
+  try {
+    bytes = readFileSync(historyPath());
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return { bytes: Buffer.alloc(0), complete: 0, rows: [] };
+    fail(error instanceof Error ? error.message : String(error));
+  }
+  const complete = bytes.lastIndexOf(10) + 1;
+  const rows = bytes.subarray(0, complete).toString("utf8").split("\n").filter(Boolean).map((line) => {
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      fail("damaged complete journal line");
+    }
+    validateHistoryRecord(row);
+    return row;
+  });
+  return { bytes, complete, rows };
+}
+function archiveCompletedCreditRecords(records) {
+  if (!records.length) return;
+  try {
+    const current = journal();
+    const latest = new Map(
+      current.rows.map((record) => [record.id, JSON.stringify(record)])
+    );
+    const observed = new Map(current.rows.map((record) => [record.id, record]));
+    const additions = [];
+    for (const incoming of records) {
+      const prior = [...observed.values()].reverse().find(
+        (row) => row.kind === incoming.kind && row.callerPubkey === incoming.callerPubkey && row.creditId === incoming.creditId && (row.kind !== "completed_refund" || incoming.kind === "completed_refund" && row.drainId === incoming.drainId) && compatibleLocations(row, incoming)
+      );
+      const newerPrior = prior && (incoming.kind === "completed_refund" && prior.kind === "completed_refund" ? (prior.collectedAt ?? 0) > (incoming.collectedAt ?? 0) : prior.occurredAt > incoming.occurredAt);
+      const facts = newerPrior ? prior : incoming;
+      const identity = prior && hasAttestedIdentity(prior) ? prior : hasAttestedIdentity(incoming) ? incoming : newerPrior || !incoming.dvmId && !incoming.attestedBuilderPubkey ? prior ?? incoming : incoming;
+      const record = prior ? {
+        ...facts,
+        id: prior.id,
+        dvmId: identity.dvmId,
+        attestedBuilderPubkey: identity.attestedBuilderPubkey,
+        endpointAliases: [
+          .../* @__PURE__ */ new Set([
+            prior.endpoint,
+            ...prior.endpointAliases,
+            incoming.endpoint,
+            ...incoming.endpointAliases
+          ])
+        ].filter((origin) => origin !== facts.endpoint)
+      } : incoming;
+      validateHistoryRecord(record);
+      const encoded = JSON.stringify(record);
+      if (latest.get(record.id) === encoded) continue;
+      additions.push(encoded + "\n");
+      latest.set(record.id, encoded);
+      observed.set(record.id, record);
+    }
+    const fd = openSync(historyPath(), "a", 384);
+    try {
+      if (current.complete !== current.bytes.length)
+        ftruncateSync(fd, current.complete);
+      const bytes = Buffer.from(additions.join(""));
+      let written = 0;
+      while (written < bytes.length) {
+        const count = writeSync(fd, bytes, written, bytes.length - written);
+        if (!count) fail("zero-length append");
+        written += count;
+      }
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    {
+      const directory = openSync(
+        historyPath().slice(0, historyPath().lastIndexOf("/")),
+        "r"
+      );
+      try {
+        fsyncSync(directory);
+      } finally {
+        closeSync(directory);
+      }
+    }
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}
+function readCreditHistoryPage(query) {
+  const limit = query.limit ?? 50;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+    throw new DvmError(
+      "invalid_credit_history_query",
+      "History page limit must be an integer from 1 through 100."
+    );
+  const order = query.order ?? "asc";
+  if (order !== "asc" && order !== "desc")
+    throw new DvmError(
+      "invalid_credit_history_query",
+      "History order must be asc or desc."
+    );
+  const direction = order === "asc" ? 1 : -1;
+  const filter = JSON.stringify([
+    order,
+    query.endpoint ? new URL(query.endpoint).origin : null,
+    query.dvmId ?? null,
+    query.callerPubkey ?? null
+  ]);
+  const current = journal();
+  let end = current.complete;
+  let after;
+  if (query.cursor) {
+    try {
+      const cursor = JSON.parse(
+        Buffer.from(query.cursor, "base64url").toString("utf8")
+      );
+      if (cursor.v !== 1 || !Number.isSafeInteger(cursor.end) || cursor.end < 0 || cursor.end > current.complete || cursor.end > 0 && current.bytes[cursor.end - 1] !== 10 || cursor.filter !== filter || cursor.prefix !== hash(current.bytes.subarray(0, cursor.end).toString("utf8")) || !Array.isArray(cursor.after) || !Number.isFinite(cursor.after[0]) || typeof cursor.after[1] !== "string")
+        throw new Error("cursor mismatch");
+      end = cursor.end;
+      after = cursor.after;
+    } catch {
+      throw new DvmError(
+        "invalid_credit_history_cursor",
+        "History cursor is invalid, stale, or belongs to different filters."
+      );
+    }
+  }
+  const rows = current.bytes.subarray(0, end).toString("utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+  const endpoint = query.endpoint ? new URL(query.endpoint).origin : void 0;
+  const ordered = [...new Map(rows.map((row) => [row.id, row])).values()].filter(
+    (row) => (!endpoint || row.endpoint === endpoint || row.endpointAliases.includes(endpoint)) && (!query.dvmId || row.dvmId === query.dvmId) && (!query.callerPubkey || row.callerPubkey === query.callerPubkey)
+  ).sort(
+    (a, b) => direction * (a.occurredAt - b.occurredAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  );
+  const remaining = ordered.filter(
+    (row) => !after || direction * (row.occurredAt - after[0]) > 0 || row.occurredAt === after[0] && (direction === 1 ? row.id > after[1] : row.id < after[1])
+  );
+  const records = remaining.slice(0, limit);
+  const last = records.at(-1);
+  return {
+    records,
+    ...remaining.length > limit && last ? {
+      nextCursor: Buffer.from(
+        JSON.stringify({
+          v: 1,
+          end,
+          prefix: hash(current.bytes.subarray(0, end).toString("utf8")),
+          filter,
+          after: [last.occurredAt, last.id]
+        })
+      ).toString("base64url")
+    } : {}
+  };
+}
+
+// src/lib/credit-store.ts
 function withCreditLock(fn, opts = {}) {
   if (lockDepth > 0) {
     lockDepth += 1;
@@ -258,6 +564,12 @@ function clearCreditSelection(endpoint, callerPubkey, creditId, identity) {
     return structuredClone(record);
   });
 }
+function readCompletedCreditHistory(query = {}) {
+  return withCreditLock(() => {
+    loadStore(true);
+    return readCreditHistoryPage(query);
+  });
+}
 function listCredits() {
   return withCreditLock(() => [...loadStore().credits].sort((a, b) => b.updatedAt - a.updatedAt));
 }
@@ -308,7 +620,13 @@ function markImplicitCreditLost(args) {
       where: (candidate) => candidate.callerPubkey === args.callerPubkey && candidate.creditId === args.creditId
     });
     if (!record) return void 0;
-    attachDvmLocation(record, key, args.identity);
+    const locationChanged = attachDvmLocation(record, key, args.identity);
+    if (record.status === "lost" && !archiveOrKeep(
+      () => archiveCompletedCreditRecords([completedLoss(record)])
+    )) {
+      if (locationChanged) saveStore(store);
+      return record;
+    }
     record.status = "lost";
     record.lossReason = args.reason;
     record.updatedAt = args.now ?? Date.now();
@@ -577,7 +895,13 @@ function applyImplicitReceiptCredit(args) {
       saveStore(store);
       return store.implicitCredits.includes(record) ? { credit: record } : {};
     }
-    attachDvmLocation(record, key, args.identity);
+    const locationChanged = attachDvmLocation(record, key, args.identity);
+    if (record.status === "lost" && !archiveOrKeep(
+      () => archiveCompletedCreditRecords([completedLoss(record)])
+    )) {
+      if (locationChanged) saveStore(store);
+      return { credit: record };
+    }
     let mismatch;
     const sequential = args.credit.ledger_seq === record.ledgerSeq + 1;
     if (sequential && args.outcome === "completed" && record.status === "active") {
@@ -754,6 +1078,9 @@ function forgetCredit(endpoint, callerPubkey, identity) {
       where: (c) => c.callerPubkey === callerPubkey
     });
     if (!record) return;
+    archiveCompletedCreditRecords(
+      (record.drainEvidence ?? []).filter((bundle) => bundle.settledAt !== void 0).map((bundle) => completedRefund(record, bundle))
+    );
     saveStore({ ...store, credits: store.credits.filter((c) => c !== record) });
   });
 }
@@ -796,6 +1123,11 @@ function recordDrainReceipts(args) {
   mutateCredit(mutationAt(endpoint, callerPubkey, identity), (record) => {
     const evidence = record.drainEvidence ??= [];
     let bundle = evidence.find((e) => e.drainId === drainId);
+    if (bundle?.settledAt !== void 0 && !archiveOrKeep(
+      () => archiveCompletedCreditRecords([completedRefund(record, bundle)])
+    )) {
+      return "skip";
+    }
     if (!bundle) {
       bundle = { drainId, creditId, receipts: [], collectedAt: now };
       evidence.push(bundle);
@@ -803,9 +1135,15 @@ function recordDrainReceipts(args) {
     bundle.creditId = creditId;
     bundle.receipts = receipts;
     bundle.collectedAt = now;
+    bundle.settlement ??= {
+      rail: null,
+      currency: record.creditId === creditId ? record.currency : null,
+      amountMicro: null,
+      feeMicro: null
+    };
     if (read.anchor) bundle.anchor = read.anchor;
     else if (read.reachable) delete bundle.anchor;
-    record.drainEvidence = capDrainEvidence(evidence, endpoint);
+    record.drainEvidence = evidence;
     return void 0;
   });
 }
@@ -816,7 +1154,8 @@ function settleDrainEvidence(args) {
     const bundle = evidence.find((e) => e.drainId === drainId);
     if (!bundle || bundle.settledAt !== void 0) return "skip";
     bundle.settledAt = now;
-    record.drainEvidence = capDrainEvidence(evidence, endpoint);
+    if (args.settlement) bundle.settlement = args.settlement;
+    record.drainEvidence = evidence;
     return void 0;
   });
 }
@@ -882,19 +1221,19 @@ function adoptCreditId(record, creditId) {
 var MAX_SETTLED_DRAIN_EVIDENCE = 8;
 var MAX_LOST_IMPLICIT_CREDITS = 8;
 var MAX_DATE_MS = 864e13;
-function loadStore() {
+function loadStore(requireArchive = false) {
   if (!existsSync(CREDITS_FILE)) {
     return { credits: [], implicitCredits: [], pendingFundings: [], fundingMenuSnapshots: [] };
   }
-  let raw2;
+  let raw;
   try {
-    raw2 = readFileSync(CREDITS_FILE, "utf-8");
+    raw = readFileSync2(CREDITS_FILE, "utf-8");
   } catch (cause) {
     throw unreadableStore(cause);
   }
   let data;
   try {
-    const parsed = JSON.parse(raw2);
+    const parsed = JSON.parse(raw);
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
       throw new Error("the file parsed as JSON but is not a credit-store object");
     }
@@ -915,7 +1254,8 @@ function loadStore() {
     Array.isArray(data.pendingFundings) ? data.pendingFundings.filter((funding) => isObjectRecord(funding)).map(normalizeRailKey) : []
   );
   const implicit = dedupeImplicitCredits(
-    Array.isArray(data.implicitCredits) ? data.implicitCredits.filter(isStoredImplicitCredit) : []
+    Array.isArray(data.implicitCredits) ? data.implicitCredits.filter(isStoredImplicitCredit) : [],
+    requireArchive
   );
   const store = {
     credits: merged.credits,
@@ -923,14 +1263,16 @@ function loadStore() {
     pendingFundings: fundings.fundings,
     fundingMenuSnapshots: snapshots.snapshots
   };
+  if (requireArchive) archiveStore(store);
   if (merged.changed || snapshots.changed || fundings.changed || implicit.changed) saveStore(store);
+  else if (!requireArchive) archiveOrKeep(() => archiveStore(store));
   return store;
 }
 function isStoredImplicitCredit(value) {
   if (!isObjectRecord(value)) return false;
   return typeof value.endpoint === "string" && typeof value.callerPubkey === "string" && typeof value.creditId === "string" && value.creditId.startsWith("imp:") && typeof value.currency === "string" && typeof value.remainingMicro === "number" && Number.isFinite(value.remainingMicro) && typeof value.ledgerSeq === "number" && Number.isInteger(value.ledgerSeq) && typeof value.expiryMs === "number" && Number.isFinite(value.expiryMs) && (value.status === "active" || value.status === "lost") && typeof value.releasedByJobId === "string" && typeof value.releasedAt === "number" && Number.isFinite(value.releasedAt) && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt);
 }
-function dedupeImplicitCredits(credits) {
+function dedupeImplicitCredits(credits, requireArchive = false) {
   const merged = [];
   let changed = false;
   for (const candidate of credits) {
@@ -945,6 +1287,9 @@ function dedupeImplicitCredits(credits) {
       merged.push(candidate);
       continue;
     }
+    if (!archiveOrKeep(() => archiveCompletedCreditRecords(
+      [existing, candidate].filter((record) => record.status === "lost").map(completedLoss)
+    ), requireArchive)) return { credits, changed: false };
     changed = true;
     for (const origin of dvmLocationOrigins(candidate)) {
       attachDvmLocation(existing, origin, identity);
@@ -966,7 +1311,7 @@ function dedupeImplicitCredits(credits) {
       existing.releasedByJobId = candidate.releasedByJobId;
     }
   }
-  const capped = capLostImplicitCredits(merged);
+  const capped = capLostImplicitCredits(merged, requireArchive);
   return { credits: capped.credits, changed: changed || capped.changed };
 }
 function ageImplicitCredits(credits, now) {
@@ -981,7 +1326,14 @@ function ageImplicitCredits(credits, now) {
   }
   return changed;
 }
-function capLostImplicitCredits(credits) {
+function capLostImplicitCredits(credits, requireArchive = false) {
+  const archived = archiveOrKeep(
+    () => archiveCompletedCreditRecords(
+      credits.filter((credit) => credit.status === "lost").map(completedLoss)
+    ),
+    requireArchive
+  );
+  if (!archived) return { credits, changed: false };
   const lostByOwner = /* @__PURE__ */ new Map();
   for (const credit of credits) {
     if (credit.status !== "lost") continue;
@@ -1284,19 +1636,39 @@ function isEvidenceish(value) {
 function isDrainish(value) {
   return typeof value === "object" && value !== null && typeof value.drainId === "string";
 }
-function capDrainEvidence(evidence, endpoint) {
-  const settled = evidence.filter((e) => e.settledAt !== void 0).sort((a, b) => (a.settledAt ?? 0) - (b.settledAt ?? 0));
-  if (settled.length <= MAX_SETTLED_DRAIN_EVIDENCE) return evidence;
-  const dropped = new Set(settled.slice(0, settled.length - MAX_SETTLED_DRAIN_EVIDENCE));
-  for (const e of dropped) {
-    info(
-      `Dropping the oldest completed reclaim's receipts (drain ${e.drainId}${e.creditId ? ` on credit ${e.creditId}` : ""}) \u2014 ${String(MAX_SETTLED_DRAIN_EVIDENCE)} is the most this DVM's record archives. Export the ones still held before they age out too: 'dvm credit receipts ${endpoint} --export'.`
-    );
+function archiveOrKeep(action, requireArchive = false) {
+  try {
+    action();
+    return true;
+  } catch (error) {
+    if (requireArchive || !(error instanceof DvmError) || error.code !== "credit_history_unavailable") {
+      throw error;
+    }
+    return false;
   }
+}
+function archiveStore(store) {
+  archiveCompletedCreditRecords([
+    ...store.credits.flatMap(
+      (credit) => (credit.drainEvidence ?? []).filter((bundle) => bundle.settledAt !== void 0).map((bundle) => completedRefund(credit, bundle))
+    ),
+    ...store.implicitCredits.filter((credit) => credit.status === "lost").map(completedLoss)
+  ]);
+}
+function capDrainEvidence(evidence) {
+  const settled = evidence.filter((e) => e.settledAt !== void 0).sort((a, b) => a.settledAt - b.settledAt);
+  const dropped = new Set(
+    settled.slice(0, Math.max(0, settled.length - MAX_SETTLED_DRAIN_EVIDENCE))
+  );
   return evidence.filter((e) => !dropped.has(e));
 }
 function saveStore(store) {
   ensureConfigDir();
+  if (archiveOrKeep(() => archiveStore(store))) {
+    for (const credit of store.credits) {
+      if (credit.drainEvidence) credit.drainEvidence = capDrainEvidence(credit.drainEvidence);
+    }
+  }
   const tmp = `${CREDITS_FILE}.${String(process.pid)}.tmp`;
   writeFileSync(tmp, JSON.stringify(store, null, 2) + "\n", { mode: 384 });
   try {
@@ -1428,12 +1800,6 @@ function sleepSync(ms) {
 }
 
 export {
-  setOutputTraceId,
-  getOutputTraceId,
-  json,
-  info,
-  raw,
-  progress,
   RAIL_FLAGS,
   maxAdvertisedMicro,
   withinAdvertisedTolerance,
@@ -1447,6 +1813,7 @@ export {
   pendingDrainById,
   loadCredit,
   clearCreditSelection,
+  readCompletedCreditHistory,
   listCredits,
   listImplicitCredits,
   loadImplicitCredits,