@dvmkit/sdk 0.1.0-rc.5 → 0.1.0-rc.7

package/dist/chunk-TSWKITGR.js

@@ -0,0 +1,772 @@
+import {
+  CONFIG_AUDIT_FILE,
+  CONFIG_BACKUP_FILE,
+  CONFIG_FILE,
+  CONFIG_PINNED_FILE,
+  DvmError,
+  ensureConfigDir
+} from "./chunk-MKI6OVW4.js";
+
+// src/lib/evm-private-key.ts
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { hexToBytes } from "@noble/hashes/utils.js";
+var EVM_PRIVATE_KEY_RE = /^0x[0-9a-fA-F]{64}$/;
+function isValidEvmPrivateKey(value) {
+  return EVM_PRIVATE_KEY_RE.test(value) && secp256k1.utils.isValidSecretKey(hexToBytes(value.slice(2)));
+}
+
+// src/lib/config-mutation.ts
+import {
+  appendFileSync,
+  chmodSync,
+  existsSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+var PROTECTED_CONFIG_FIELDS = ["nwcUri", "defaultIdentity", "tempo", "x402"];
+var ProtectedFieldAuthorization = class {
+  /** Targets this authorization covers. A field also covers its own leaves. */
+  targets;
+  /** Prefer {@link authorizeProtectedRemoval}; this exists for it to call. */
+  constructor(targets) {
+    this.targets = [...targets];
+  }
+  /**
+   * True when `target` is one this authorization names. Naming a field covers
+   * the leaves under it; naming a leaf covers only that leaf, so a command
+   * entitled to clear `tempo.apiKey` still cannot take the whole `tempo` block.
+   */
+  covers(target) {
+    if (this.targets.includes(target)) return true;
+    const field = target.split(".")[0];
+    return target !== field && this.targets.includes(field);
+  }
+};
+function authorizeProtectedRemoval(...targets) {
+  return new ProtectedFieldAuthorization(targets);
+}
+function planConfigReset(config) {
+  const present = Object.keys(config);
+  const resettable = resettableConfigFields();
+  const clearable = new Set(resettable);
+  return {
+    clear: resettable.filter((field) => present.includes(field)),
+    preserved: present.filter((field) => !clearable.has(field))
+  };
+}
+function applyConfigPatch(base, patch) {
+  if (!isPlainObject(patch))
+    throw patchShapeError("A change must be an object with `set` and/or `unset`.");
+  if (patch.set !== void 0 && !isPlainObject(patch.set)) {
+    throw patchShapeError("A change's `set` must be an object of fields to write.");
+  }
+  if (patch.unset !== void 0 && !Array.isArray(patch.unset)) {
+    throw patchShapeError("A change's `unset` must be an array of field names.");
+  }
+  const set = patch.set ?? {};
+  const unset = patch.unset ?? [];
+  for (const [field, value] of Object.entries(set)) {
+    if (value !== void 0) continue;
+    throw new DvmError(
+      "config_patch_invalid",
+      `Config field '${field}' was declared with no value.`,
+      "Give the field a value, or name it in the change's `unset` list to remove it. An undefined value is how a field gets dropped without anyone deciding to drop it."
+    );
+  }
+  for (const field of unset) {
+    if (typeof field !== "string" || field.length === 0) {
+      throw patchShapeError("Every entry in a change's `unset` must be a field name.");
+    }
+    if (!Object.hasOwn(set, field)) continue;
+    throw new DvmError(
+      "config_patch_invalid",
+      `Config field '${field}' is both written and removed by the same change.`,
+      "Declare each field once: in `set` with its new value, or in `unset` to remove it."
+    );
+  }
+  const merged = { ...base, ...set };
+  const removing = new Set(unset);
+  return Object.fromEntries(
+    Object.entries(merged).filter(([field]) => !removing.has(field))
+  );
+}
+function deepFreezeConfig(config) {
+  freezeDeep(config);
+  return config;
+}
+function protectedRemovals(before, after) {
+  const previous = before;
+  const next = after;
+  const removed = [];
+  for (const field of PROTECTED_CONFIG_FIELDS) {
+    const held = previous[field];
+    if (!isPresentValue(held)) continue;
+    const kept = next[field];
+    if (!isPresentValue(kept)) {
+      removed.push(field);
+      continue;
+    }
+    const spec = PROTECTED_FIELDS[field];
+    if (spec.credentialLeaves.length === 0) continue;
+    if (!isPlainObject(held)) continue;
+    if (!isPlainObject(kept)) {
+      removed.push(field);
+      continue;
+    }
+    for (const leaf of spec.credentialLeaves) {
+      if (!isPresentValue(held[leaf]) || isPresentValue(kept[leaf])) continue;
+      removed.push(`${field}.${leaf}`);
+    }
+  }
+  return removed;
+}
+function supersededProtectedSecrets(before, after) {
+  const previous = before;
+  const next = after;
+  const superseded = [];
+  for (const field of PROTECTED_CONFIG_FIELDS) {
+    const spec = PROTECTED_FIELDS[field];
+    if (!spec.secret) continue;
+    const held = previous[field];
+    const kept = next[field];
+    if (spec.credentialLeaves.length === 0) {
+      if (isPresentValue(held) && isPresentValue(kept) && held !== kept) superseded.push(field);
+      continue;
+    }
+    if (!isPlainObject(held) || !isPlainObject(kept)) continue;
+    for (const leaf of spec.credentialLeaves) {
+      const was = held[leaf];
+      const now = kept[leaf];
+      if (!isPresentValue(was) || !isPresentValue(now) || was === now) continue;
+      superseded.push(`${field}.${leaf}`);
+    }
+  }
+  return superseded;
+}
+function changedConfigPaths(before, after) {
+  const found = /* @__PURE__ */ new Set();
+  collectChangedPaths(
+    before,
+    after,
+    CONFIG_PATH_SHAPE,
+    "",
+    found
+  );
+  return [...found].sort();
+}
+function assertValidConfig(config, fields) {
+  if (!isPlainObject(config)) {
+    throw new DvmError(
+      "config_invalid",
+      "The caller configuration is not a JSON object.",
+      `Expected an object at ${CONFIG_FILE}.${rollbackSuffix()}`
+    );
+  }
+  const record = config;
+  const scope = fields ? new Set(fields) : null;
+  for (const [field, kind] of Object.entries(CONFIG_FIELD_TYPES)) {
+    if (scope && !scope.has(field)) continue;
+    const value = record[field];
+    if (value === void 0) continue;
+    if (!matchesKind(value, kind)) throw invalidFieldError(field, kind);
+  }
+  for (const [path, kind] of Object.entries(CONFIG_LEAF_TYPES)) {
+    const [field, leaf] = path.split(".");
+    if (scope && !scope.has(field)) continue;
+    const owner = record[field];
+    if (!isPlainObject(owner)) continue;
+    const value = owner[leaf];
+    if (value === void 0 || !matchesKind(value, kind)) throw invalidFieldError(path, kind);
+  }
+}
+function readRawConfig() {
+  if (!existsSync(CONFIG_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+  } catch {
+    throw new DvmError(
+      "config_corrupt",
+      "Config file is corrupt.",
+      // Not "delete it": those bytes are the only copy on this machine of the
+      // NWC connection string and both private keys, however badly they parse.
+      `Run 'dvm config rollback' to restore a stored copy, or move ${CONFIG_FILE} aside yourself and run 'dvm init'.${rollbackSuffix()}`
+    );
+  }
+}
+function writeConfigFile(config) {
+  writeJsonAtomic(CONFIG_FILE, config);
+}
+var CONFIG_SNAPSHOT_SLOTS = ["backup", "pinned"];
+function configSnapshotPath(slot) {
+  return slot === "pinned" ? CONFIG_PINNED_FILE : CONFIG_BACKUP_FILE;
+}
+function describeConfigBackup(slot = "backup") {
+  const path = configSnapshotPath(slot);
+  try {
+    if (!existsSync(path)) return null;
+    const stat = statSync(path);
+    const posix = process.platform !== "win32";
+    const mode = stat.mode & 511;
+    return {
+      path,
+      slot,
+      bytes: stat.size,
+      modifiedAt: stat.mtime.toISOString(),
+      modeOctal: posix ? toOctal(mode) : null,
+      ownerOnly: !posix || (mode & 63) === 0
+    };
+  } catch {
+    return null;
+  }
+}
+function readConfigBackup(slot = "backup") {
+  const path = configSnapshotPath(slot);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    return isPlainObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function retainConfigBackup(slot = "backup") {
+  if (!existsSync(CONFIG_FILE)) return false;
+  ensureConfigDir();
+  const path = configSnapshotPath(slot);
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, readFileSync(CONFIG_FILE), { mode: 384 });
+  chmodSync(tmp, 384);
+  commitTmp(tmp, path);
+  return true;
+}
+function writeConfigBackup(config, slot = "backup") {
+  writeJsonAtomic(configSnapshotPath(slot), config);
+}
+function removeConfigBackup(slot = "backup") {
+  const path = configSnapshotPath(slot);
+  if (!existsSync(path)) return false;
+  unlinkSync(path);
+  return true;
+}
+function protectedTargetValue(config, target) {
+  const [field, named] = target.split(".");
+  const held = config[field];
+  const leaves = PROTECTED_FIELDS[field].credentialLeaves;
+  const leaf = named ?? (leaves.length > 0 ? leaves[0] : void 0);
+  if (leaf === void 0) return held;
+  return isPlainObject(held) ? held[leaf] : void 0;
+}
+function protectedValuesMatch(target, left, right) {
+  const normalized = comparableProtectedValue(target, left);
+  return normalized !== void 0 && normalized === comparableProtectedValue(target, right);
+}
+function isSecretProtectedTarget(target) {
+  return PROTECTED_FIELDS[target.split(".")[0]].secret;
+}
+function withoutProtectedTargets(config, targets) {
+  const dropping = /* @__PURE__ */ new Set();
+  for (const target of targets) {
+    const field = target.split(".")[0];
+    dropping.add(field);
+    for (const alias of PROTECTED_FIELDS[field].aliases) dropping.add(alias);
+  }
+  return Object.fromEntries(
+    Object.entries(config).filter(([field]) => !dropping.has(field))
+  );
+}
+function appendConfigAudit(record) {
+  try {
+    ensureConfigDir();
+    appendFileSync(CONFIG_AUDIT_FILE, JSON.stringify(record) + "\n", { mode: 384 });
+    chmodSync(CONFIG_AUDIT_FILE, 384);
+  } catch {
+  }
+}
+function protectedRemovalError(targets, reason) {
+  const named = targets.join(", ");
+  const one = targets.length === 1;
+  return new DvmError(
+    "config_protected_field",
+    `The '${reason}' change would remove ${named} from the local configuration.`,
+    `Nothing was written. ${named} ${one ? "is a credential or identity pointer" : "are credentials or identity pointers"} nothing else on this machine records, so only a command that names ${one ? "it" : "them"} explicitly may remove ${one ? "it" : "them"} \u2014 'dvm wallet disconnect', 'dvm wallet tempo-disconnect' and 'dvm wallet x402-disconnect' are those commands.`,
+    { fields: targets }
+  );
+}
+var PROTECTED_FIELDS = {
+  nwcUri: { aliases: [], credentialLeaves: [], secret: true, hexCredential: false },
+  // A pointer at a key, not a key: worth protecting from removal, and never
+  // worth stripping out of a stored copy — that is recovery lost for nothing.
+  defaultIdentity: { aliases: [], credentialLeaves: [], secret: false, hexCredential: false },
+  // `mpp` is the pre-internal-review name; a caller who has not run a mutating command
+  // since the rename still has their private key under it.
+  tempo: { aliases: ["mpp"], credentialLeaves: ["apiKey"], secret: true, hexCredential: true },
+  x402: { aliases: [], credentialLeaves: ["privateKey"], secret: true, hexCredential: true }
+};
+var CONFIG_PATH_SHAPE = {
+  float: { statedBudget: {}, connectedAt: {}, alias: {}, methods: {} },
+  x402: { privateKey: {}, network: {} },
+  tempo: { method: {}, accountId: {}, apiKey: {} },
+  credit: {
+    targetJobs: {},
+    posture: {},
+    tier0Cap: {},
+    tier1Cap: {},
+    pocketTarget: {},
+    fundingRail: {},
+    perDvm: { "*": { targetJobs: {}, posture: {}, fundingRail: {}, dvmId: {}, builderPubkey: {} } },
+    trustOverrides: { "*": {} }
+  },
+  feedback: { posture: {} }
+};
+var CONFIG_FIELD_TYPES = {
+  nwcUri: "string",
+  float: "object",
+  defaultBudget: "string",
+  autoPayThreshold: "string",
+  defaultMaxPayments: "number",
+  cashuMints: "string[]",
+  x402: "object",
+  tempo: "object",
+  defaultRail: "string",
+  defaultIdentity: "string",
+  credit: "object",
+  feedback: "object"
+};
+var CONFIG_LEAF_TYPES = {
+  "float.connectedAt": "string",
+  "x402.privateKey": "string",
+  "tempo.method": "string"
+};
+function collectChangedPaths(before, after, shape, prefix, found) {
+  for (const key of /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])) {
+    const held = before[key];
+    const kept = after[key];
+    if (deepEqual(held, kept)) continue;
+    const known = shape !== void 0 && Object.hasOwn(shape, key);
+    const wildcard = !known && shape !== void 0 && Object.hasOwn(shape, "*");
+    const child = known ? shape[key] : wildcard ? shape["*"] : void 0;
+    const path = prefix ? `${prefix}.${wildcard ? "*" : key}` : key;
+    const descendable = child !== void 0 && Object.keys(child).length > 0 && (held === void 0 || isPlainObject(held)) && (kept === void 0 || isPlainObject(kept));
+    if (descendable) {
+      collectChangedPaths(
+        isPlainObject(held) ? held : {},
+        isPlainObject(kept) ? kept : {},
+        child,
+        path,
+        found
+      );
+    } else {
+      found.add(path);
+    }
+  }
+}
+function resettableConfigFields() {
+  const guarded = new Set(PROTECTED_CONFIG_FIELDS);
+  return Object.keys(CONFIG_FIELD_TYPES).filter((field) => !guarded.has(field));
+}
+function invalidFieldError(path, kind) {
+  return new DvmError(
+    "config_invalid",
+    `Config field '${path}' must be ${describeKind(kind)}.`,
+    `Nothing was written. Correct the field in ${CONFIG_FILE}, or run 'dvm doctor' for the full picture.${rollbackSuffix()}`
+  );
+}
+function describeKind(kind) {
+  switch (kind) {
+    case "string":
+      return "a string";
+    case "number":
+      return "a number";
+    case "object":
+      return "an object";
+    case "string[]":
+      return "an array of strings";
+  }
+}
+function matchesKind(value, kind) {
+  switch (kind) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "object":
+      return isPlainObject(value);
+    case "string[]":
+      return Array.isArray(value) && value.every((item) => typeof item === "string");
+  }
+}
+function rollbackSuffix() {
+  const stored = describeConfigBackup() ?? describeConfigBackup("pinned");
+  return stored === null ? "" : ` A stored copy of the previous configuration is at ${stored.path}.`;
+}
+function writeJsonAtomic(path, value) {
+  ensureConfigDir();
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { mode: 384 });
+  chmodSync(tmp, 384);
+  commitTmp(tmp, path);
+}
+function commitTmp(tmp, path) {
+  try {
+    renameSync(tmp, path);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+    throw err;
+  }
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, index) => deepEqual(item, b[index]));
+  }
+  if (!isPlainObject(a) || !isPlainObject(b)) return false;
+  for (const key of /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)])) {
+    if (!deepEqual(a[key], b[key])) return false;
+  }
+  return true;
+}
+function isPresentValue(value) {
+  if (value === void 0 || value === null) return false;
+  return typeof value !== "string" || value.trim().length > 0;
+}
+function comparableProtectedValue(target, value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return void 0;
+  const field = target.split(".")[0];
+  return PROTECTED_FIELDS[field].hexCredential ? trimmed.toLowerCase() : trimmed;
+}
+function patchShapeError(message) {
+  return new DvmError(
+    "config_patch_invalid",
+    message,
+    "A change declares `set` (fields to write) and `unset` (field names to remove). Anything else cannot be applied, and nothing was written."
+  );
+}
+function freezeDeep(value) {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value)) return;
+  Object.freeze(value);
+  for (const nested of Object.values(value)) freezeDeep(nested);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toOctal(mode) {
+  return "0" + mode.toString(8).padStart(3, "0");
+}
+
+// src/lib/identity.ts
+import lockfile from "proper-lockfile";
+var CREDIT_POSTURES = ["suggest", "auto", "off"];
+function isCreditPosture(value) {
+  return typeof value === "string" && CREDIT_POSTURES.includes(value);
+}
+var FEEDBACK_POSTURES = ["ask", "auto", "off"];
+function isFeedbackPosture(value) {
+  return typeof value === "string" && FEEDBACK_POSTURES.includes(value);
+}
+function migrateCreditConfig(config) {
+  const credit = config.credit;
+  if (!credit) return config;
+  const migrateLayer = (layer) => {
+    const railed = migrateFundingRail(layer);
+    if (!("disabled" in railed)) return railed;
+    const { disabled, ...rest } = railed;
+    const migrated = { ...rest };
+    if (migrated.posture === void 0 && disabled === true) migrated.posture = "off";
+    return migrated;
+  };
+  const perDvm = credit.perDvm;
+  return {
+    ...config,
+    credit: {
+      ...migrateLayer(credit),
+      ...perDvm ? {
+        perDvm: Object.fromEntries(
+          Object.entries(perDvm).map(([endpoint, per]) => [endpoint, migrateLayer(per)])
+        )
+      } : {}
+    }
+  };
+}
+function migrateFundingRail(layer) {
+  const loose = layer;
+  if (loose.fundingRail !== "mpp") return layer;
+  return { ...layer, fundingRail: "tempo" };
+}
+function migrateTempoWalletKey(config) {
+  const loose = config;
+  if (!loose.mpp || loose.tempo) return config;
+  const { mpp, ...rest } = loose;
+  return { ...rest, tempo: mpp };
+}
+function migrateConfig(config) {
+  return migrateCreditConfig(migrateTempoWalletKey(config));
+}
+function loadConfig() {
+  const raw = readRawConfig();
+  return raw === null ? null : migrateConfig(raw);
+}
+async function updateConfig(update) {
+  return withConfigLock(async () => {
+    const raw = readRawConfig();
+    const snapshot = raw === null ? {} : structuredClone(raw);
+    const base = raw === null ? null : migrateConfig(structuredClone(raw));
+    const handed = raw === null ? null : deepFreezeConfig(migrateConfig(structuredClone(raw)));
+    const next = applyConfigPatch(base ?? {}, await runPatch(update, handed));
+    const changed = changedConfigPaths(snapshot, next);
+    if (changed.length === 0) {
+      return {
+        config: base ?? {},
+        previous: base,
+        changed: [],
+        written: false,
+        backup: describeConfigBackup()
+      };
+    }
+    const removals = protectedRemovals(base ?? {}, next);
+    const unauthorized = removals.filter((target) => update.authorize?.covers(target) !== true);
+    if (unauthorized.length > 0) throw protectedRemovalError(unauthorized, update.reason);
+    assertValidConfig(
+      next,
+      changed.map((path) => path.split(".")[0])
+    );
+    const superseded = supersededProtectedSecrets(base ?? {}, next);
+    const stripped = [
+      .../* @__PURE__ */ new Set([...removals, ...superseded, ...update.sanitizeBackup ?? []])
+    ].filter(isSecretProtectedTarget);
+    const sweeping = update.sweepSlots ?? CONFIG_SNAPSHOT_SLOTS;
+    const swept = [];
+    if (raw !== null) {
+      if (stripped.length > 0) {
+        writeConfigBackup(withoutProtectedTargets(raw, stripped));
+        swept.push("backup");
+      } else {
+        retainConfigBackup();
+      }
+    }
+    if (stripped.length > 0 && sweeping.includes("pinned")) {
+      if (sweepPinnedSnapshot(stripped, base ?? {}, update.reason)) swept.push("pinned");
+    }
+    const backup = describeConfigBackup();
+    writeConfigFile(next);
+    appendConfigAudit({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      event: "update",
+      reason: update.reason,
+      fields: changed,
+      ...removals.length > 0 ? { removed: removals } : {},
+      ...superseded.length > 0 ? { superseded } : {},
+      ...swept.length > 0 ? { sweptSlots: swept } : {},
+      backup: backup !== null,
+      pid: process.pid
+    });
+    return { config: next, previous: base, changed, written: true, backup };
+  });
+}
+async function pinConfigSnapshot(reason) {
+  return withConfigLock(() => {
+    if (describeConfigBackup("pinned") !== null) return null;
+    if (!retainConfigBackup("pinned")) return null;
+    const pinned = describeConfigBackup("pinned");
+    appendConfigAudit({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      event: "pinned",
+      reason,
+      fields: [],
+      slot: "pinned",
+      backup: pinned !== null,
+      pid: process.pid
+    });
+    return pinned;
+  });
+}
+async function ensureConfig(seed = {}, reason = "init") {
+  return withConfigLock(() => {
+    const existing = readRawConfig();
+    if (existing !== null) return { config: migrateConfig(existing), created: false };
+    assertValidConfig(seed);
+    writeConfigFile(seed);
+    appendConfigAudit({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      event: "create",
+      reason,
+      fields: changedConfigPaths({}, seed),
+      backup: describeConfigBackup() !== null,
+      pid: process.pid
+    });
+    return { config: seed, created: true };
+  });
+}
+function previewConfigRollback(source = "backup") {
+  const restored = readConfigBackup(source);
+  if (restored === null) return null;
+  let currentOnDisk = null;
+  try {
+    currentOnDisk = readRawConfig();
+  } catch {
+  }
+  return {
+    changed: changedConfigPaths(currentOnDisk ?? {}, restored),
+    removing: protectedRemovals(
+      currentOnDisk === null ? {} : migrateConfig(structuredClone(currentOnDisk)),
+      migrateConfig(structuredClone(restored))
+    )
+  };
+}
+async function rollbackConfig(reason = "config_rollback", source = "backup", authorize) {
+  return withConfigLock(() => {
+    const restored = readConfigBackup(source);
+    if (restored === null) {
+      const stored = describeConfigBackup(source);
+      throw stored === null ? new DvmError(
+        "config_no_rollback",
+        `No ${source === "pinned" ? "pinned snapshot" : "rollback copy"} of the configuration is stored.`,
+        `A rollback copy is written at ${configSnapshotPath(source)} before each change, so there is one to restore only after a change has been made on this machine.`
+      ) : new DvmError(
+        "config_rollback_corrupt",
+        `The stored copy at ${configSnapshotPath(source)} is not readable as a configuration.`,
+        "Nothing was changed. Inspect that file yourself, or remove it and continue with the configuration you have."
+      );
+    }
+    assertValidConfig(restored);
+    let currentOnDisk = null;
+    try {
+      currentOnDisk = readRawConfig();
+    } catch {
+    }
+    const changed = changedConfigPaths(currentOnDisk ?? {}, restored);
+    const removed = protectedRemovals(
+      currentOnDisk === null ? {} : migrateConfig(structuredClone(currentOnDisk)),
+      migrateConfig(structuredClone(restored))
+    );
+    const unauthorized = removed.filter((target) => authorize?.covers(target) !== true);
+    if (unauthorized.length > 0) throw protectedRemovalError(unauthorized, reason);
+    if (!retainConfigBackup()) retireSlot(`${reason}:nothing_to_swap`, "backup");
+    if (source === "pinned") retireSlot(`${reason}:pin_restored`, "pinned");
+    writeConfigFile(restored);
+    appendConfigAudit({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      event: "rollback",
+      reason,
+      fields: changed,
+      ...removed.length > 0 ? { removed } : {},
+      source,
+      backup: describeConfigBackup() !== null,
+      pid: process.pid
+    });
+    return { config: restored, changed, removed };
+  });
+}
+async function retireConfigBackup(reason, slot = "backup") {
+  return withConfigLock(() => retireSlot(reason, slot));
+}
+async function withConfigLock(fn) {
+  ensureConfigDir();
+  let release;
+  try {
+    release = await lockfile.lock(CONFIG_FILE, {
+      lockfilePath: `${CONFIG_FILE}.lock`,
+      realpath: false,
+      stale: 3e4,
+      retries: { retries: 10, factor: 1, minTimeout: 100, maxTimeout: 100 }
+    });
+  } catch {
+    throw new DvmError(
+      "config_locked",
+      "Another dvm process is updating the local configuration.",
+      "Wait a moment and retry."
+    );
+  }
+  try {
+    return await fn();
+  } finally {
+    await release().catch(() => void 0);
+  }
+}
+async function runPatch(update, current) {
+  try {
+    return await update.patch(current);
+  } catch (err) {
+    if (err instanceof TypeError && /read only|not extensible|frozen|cannot delete property|cannot add property/i.test(
+      err.message
+    )) {
+      throw new DvmError(
+        "config_patch_invalid",
+        `The '${update.reason}' change tried to modify the configuration it was handed.`,
+        "Nothing was written. A change declares what it wants through its `set` and `unset` lists; editing the current config in place bypasses the protected-field gate, so the object is frozen."
+      );
+    }
+    throw err;
+  }
+}
+function sweepPinnedSnapshot(targets, departing, reason) {
+  if (describeConfigBackup("pinned") === null) return false;
+  const pinned = readConfigBackup("pinned");
+  if (pinned === null) {
+    return retireSlot(`${reason}:unreadable_pin`, "pinned");
+  }
+  const migrated = migrateConfig(structuredClone(pinned));
+  const matching = targets.filter(
+    (target) => protectedValuesMatch(
+      target,
+      protectedTargetValue(departing, target),
+      protectedTargetValue(migrated, target)
+    )
+  );
+  if (matching.length === 0) return false;
+  const sanitized = withoutProtectedTargets(pinned, matching);
+  const changed = changedConfigPaths(pinned, sanitized);
+  if (changed.length === 0) return false;
+  writeConfigBackup(sanitized, "pinned");
+  appendConfigAudit({
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    event: "backup_sanitized",
+    reason,
+    fields: changed,
+    removed: matching,
+    slot: "pinned",
+    backup: describeConfigBackup() !== null,
+    pid: process.pid
+  });
+  return true;
+}
+function retireSlot(reason, slot) {
+  if (!removeConfigBackup(slot)) return false;
+  appendConfigAudit({
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    event: "backup_retired",
+    reason,
+    fields: [],
+    slot,
+    backup: describeConfigBackup() !== null,
+    pid: process.pid
+  });
+  return true;
+}
+
+export {
+  isValidEvmPrivateKey,
+  authorizeProtectedRemoval,
+  planConfigReset,
+  configSnapshotPath,
+  describeConfigBackup,
+  CREDIT_POSTURES,
+  isCreditPosture,
+  FEEDBACK_POSTURES,
+  isFeedbackPosture,
+  loadConfig,
+  updateConfig,
+  pinConfigSnapshot,
+  ensureConfig,
+  previewConfigRollback,
+  rollbackConfig,
+  retireConfigBackup
+};