chainlesschain 0.66.0 → 0.132.0

package/src/lib/cross-chain.js

@@ -666,4 +666,349 @@ export function _resetState() {
   _swaps.clear();
   _messages.clear();
   _chainConfigs.clear();
+  _maxActiveBridgesPerAddress = DEFAULT_MAX_ACTIVE_BRIDGES_PER_ADDRESS;
+}
+
+/* ══════════════════════════════════════════════════════════
+ * Phase 89 — Cross-Chain V2 surface (strictly additive)
+ *
+ * Adds canonical enums, per-address bridge concurrency cap,
+ * chain config CRUD, patch-merged state-machine setters,
+ * auto-expire swaps, and all-enum-key stats V2.
+ * ══════════════════════════════════════════════════════════ */
+
+/* ── V2 Frozen Enums ────────────────────────────────────── */
+
+export const BRIDGE_STATUS_V2 = Object.freeze({
+  PENDING: "pending",
+  LOCKED: "locked",
+  MINTED: "minted",
+  COMPLETED: "completed",
+  REFUNDED: "refunded",
+  FAILED: "failed",
+});
+
+export const SWAP_STATUS_V2 = Object.freeze({
+  INITIATED: "initiated",
+  HASH_LOCKED: "hash_locked",
+  CLAIMED: "claimed",
+  REFUNDED: "refunded",
+  EXPIRED: "expired",
+});
+
+export const MESSAGE_STATUS_V2 = Object.freeze({
+  PENDING: "pending",
+  SENT: "sent",
+  DELIVERED: "delivered",
+  FAILED: "failed",
+});
+
+export const CHAIN_ID_V2 = Object.freeze({
+  ETHEREUM: "ethereum",
+  POLYGON: "polygon",
+  BSC: "bsc",
+  ARBITRUM: "arbitrum",
+  SOLANA: "solana",
+});
+
+const DEFAULT_MAX_ACTIVE_BRIDGES_PER_ADDRESS = 3;
+export const CROSSCHAIN_DEFAULT_MAX_ACTIVE_BRIDGES_PER_ADDRESS =
+  DEFAULT_MAX_ACTIVE_BRIDGES_PER_ADDRESS;
+
+let _maxActiveBridgesPerAddress = DEFAULT_MAX_ACTIVE_BRIDGES_PER_ADDRESS;
+
+/* ── State Machine Definitions ──────────────────────────── */
+
+const BRIDGE_TRANSITIONS_V2 = new Map([
+  ["pending", new Set(["locked", "failed"])],
+  ["locked", new Set(["minted", "refunded", "failed"])],
+  ["minted", new Set(["completed", "failed"])],
+]);
+const BRIDGE_TERMINALS_V2 = new Set(["completed", "refunded", "failed"]);
+
+const SWAP_TRANSITIONS_V2 = new Map([
+  ["initiated", new Set(["hash_locked", "claimed", "refunded", "expired"])],
+  ["hash_locked", new Set(["claimed", "refunded", "expired"])],
+]);
+const SWAP_TERMINALS_V2 = new Set(["claimed", "refunded", "expired"]);
+
+const MESSAGE_TRANSITIONS_V2 = new Map([
+  ["pending", new Set(["sent", "failed"])],
+  ["sent", new Set(["delivered", "failed"])],
+  ["failed", new Set(["pending"])],
+]);
+const MESSAGE_TERMINALS_V2 = new Set(["delivered"]);
+
+/* ── Concurrency Cap ───────────────────────────────────── */
+
+export function setMaxActiveBridgesPerAddress(n) {
+  if (typeof n !== "number" || Number.isNaN(n) || n < 1) {
+    throw new Error("Max active bridges must be a positive integer");
+  }
+  _maxActiveBridgesPerAddress = Math.floor(n);
+}
+
+export function getMaxActiveBridgesPerAddress() {
+  return _maxActiveBridgesPerAddress;
+}
+
+export function getActiveBridgeCount(address) {
+  let count = 0;
+  for (const b of _bridges.values()) {
+    if (BRIDGE_TERMINALS_V2.has(b.status)) continue;
+    if (address == null || b.sender_address === address) count += 1;
+  }
+  return count;
+}
+
+/* ── Chain Config V2 ───────────────────────────────────── */
+
+export function configureChainV2({
+  chainId,
+  rpcUrl,
+  contractAddress,
+  enabled = true,
+}) {
+  if (!_validateChain(chainId)) {
+    throw new Error(`Unsupported chain: ${chainId}`);
+  }
+  const cfg = {
+    chainId,
+    rpcUrl: rpcUrl || null,
+    contractAddress: contractAddress || null,
+    enabled: enabled !== false,
+    updatedAt: _now(),
+  };
+  _chainConfigs.set(chainId, cfg);
+  return { ...cfg };
+}
+
+export function getChainConfigV2(chainId) {
+  const cfg = _chainConfigs.get(chainId);
+  return cfg ? { ...cfg } : null;
+}
+
+export function listChainsV2() {
+  return Object.values(SUPPORTED_CHAINS).map((chain) => {
+    const cfg = _chainConfigs.get(chain.id);
+    return {
+      ...chain,
+      enabled: cfg ? cfg.enabled : false,
+      rpcUrl: cfg ? cfg.rpcUrl : null,
+      contractAddress: cfg ? cfg.contractAddress : null,
+    };
+  });
+}
+
+/* ── Bridge V2 (throws + cap enforcement) ──────────────── */
+
+export function bridgeAssetV2(
+  db,
+  { fromChain, toChain, asset, amount, senderAddress, recipientAddress },
+) {
+  if (!_validateChain(fromChain)) {
+    throw new Error(`Unsupported source chain: ${fromChain}`);
+  }
+  if (!_validateChain(toChain)) {
+    throw new Error(`Unsupported destination chain: ${toChain}`);
+  }
+  if (fromChain === toChain) {
+    throw new Error("Source and destination chains must differ");
+  }
+  if (!amount || amount <= 0) {
+    throw new Error("Amount must be positive");
+  }
+  if (amount > DEFAULT_CONFIG.maxBridgeAmount) {
+    throw new Error(
+      `Amount ${amount} exceeds max ${DEFAULT_CONFIG.maxBridgeAmount}`,
+    );
+  }
+  if (senderAddress) {
+    const active = getActiveBridgeCount(senderAddress);
+    if (active >= _maxActiveBridgesPerAddress) {
+      throw new Error(
+        `Max active bridges per address reached (${active}/${_maxActiveBridgesPerAddress})`,
+      );
+    }
+  }
+
+  const result = bridgeAsset(db, {
+    fromChain,
+    toChain,
+    asset,
+    amount,
+    senderAddress,
+    recipientAddress,
+  });
+  return result;
+}
+
+/* ── Generic patch-merged state setters ────────────────── */
+
+export function setBridgeStatusV2(db, bridgeId, newStatus, patch = {}) {
+  const b = _bridges.get(bridgeId);
+  if (!b) throw new Error(`Bridge not found: ${bridgeId}`);
+
+  const allowed = BRIDGE_TRANSITIONS_V2.get(b.status);
+  if (!allowed || !allowed.has(newStatus)) {
+    throw new Error(`Invalid bridge transition: ${b.status} → ${newStatus}`);
+  }
+  if (!Object.values(BRIDGE_STATUS_V2).includes(newStatus)) {
+    throw new Error(`Unknown bridge status: ${newStatus}`);
+  }
+
+  b.status = newStatus;
+  if (patch.lockTxHash !== undefined) b.lock_tx_hash = patch.lockTxHash;
+  if (patch.mintTxHash !== undefined) b.mint_tx_hash = patch.mintTxHash;
+  if (patch.errorMessage !== undefined) b.error_message = patch.errorMessage;
+  if (BRIDGE_TERMINALS_V2.has(newStatus) && !b.completed_at) {
+    b.completed_at = _now();
+  }
+
+  db.prepare(
+    `UPDATE cc_bridges SET status = ?, lock_tx_hash = ?, mint_tx_hash = ?,
+     completed_at = ?, error_message = ? WHERE id = ?`,
+  ).run(
+    b.status,
+    b.lock_tx_hash,
+    b.mint_tx_hash,
+    b.completed_at,
+    b.error_message,
+    bridgeId,
+  );
+
+  return { ...b };
+}
+
+export function setSwapStatusV2(db, swapId, newStatus, patch = {}) {
+  const s = _swaps.get(swapId);
+  if (!s) throw new Error(`Swap not found: ${swapId}`);
+
+  const allowed = SWAP_TRANSITIONS_V2.get(s.status);
+  if (!allowed || !allowed.has(newStatus)) {
+    throw new Error(`Invalid swap transition: ${s.status} → ${newStatus}`);
+  }
+  if (!Object.values(SWAP_STATUS_V2).includes(newStatus)) {
+    throw new Error(`Unknown swap status: ${newStatus}`);
+  }
+
+  s.status = newStatus;
+  if (patch.claimTxHash !== undefined) s.claim_tx_hash = patch.claimTxHash;
+  if (patch.refundTxHash !== undefined) s.refund_tx_hash = patch.refundTxHash;
+
+  db.prepare(
+    `UPDATE cc_swaps SET status = ?, claim_tx_hash = ?, refund_tx_hash = ?
+     WHERE id = ?`,
+  ).run(s.status, s.claim_tx_hash, s.refund_tx_hash, swapId);
+
+  const out = { ...s };
+  delete out.secret;
+  return out;
+}
+
+export function setMessageStatusV2(db, messageId, newStatus, patch = {}) {
+  const m = _messages.get(messageId);
+  if (!m) throw new Error(`Message not found: ${messageId}`);
+
+  const allowed = MESSAGE_TRANSITIONS_V2.get(m.status);
+  if (!allowed || !allowed.has(newStatus)) {
+    throw new Error(`Invalid message transition: ${m.status} → ${newStatus}`);
+  }
+  if (!Object.values(MESSAGE_STATUS_V2).includes(newStatus)) {
+    throw new Error(`Unknown message status: ${newStatus}`);
+  }
+
+  m.status = newStatus;
+  if (patch.sourceTxHash !== undefined) m.source_tx_hash = patch.sourceTxHash;
+  if (patch.destinationTxHash !== undefined)
+    m.destination_tx_hash = patch.destinationTxHash;
+  if (newStatus === "delivered" && !m.delivered_at) m.delivered_at = _now();
+  if (newStatus === "pending") m.retries += 1;
+
+  db.prepare(
+    `UPDATE cc_messages SET status = ?, source_tx_hash = ?, destination_tx_hash = ?,
+     delivered_at = ?, retries = ? WHERE id = ?`,
+  ).run(
+    m.status,
+    m.source_tx_hash,
+    m.destination_tx_hash,
+    m.delivered_at,
+    m.retries,
+    messageId,
+  );
+
+  return { ...m };
+}
+
+/* ── Auto-expire swaps ─────────────────────────────────── */
+
+export function autoExpireSwapsV2(db) {
+  const now = _now();
+  const expired = [];
+  for (const s of _swaps.values()) {
+    if (s.status !== "initiated" && s.status !== "hash_locked") continue;
+    if (s.expires_at > now) continue;
+
+    s.status = "expired";
+    db.prepare("UPDATE cc_swaps SET status = ? WHERE id = ?").run(
+      "expired",
+      s.id,
+    );
+    const out = { ...s };
+    delete out.secret;
+    expired.push(out);
+  }
+  return expired;
+}
+
+/* ── Stats V2 ──────────────────────────────────────────── */
+
+export function getCrossChainStatsV2() {
+  const bridgesByStatus = {};
+  for (const v of Object.values(BRIDGE_STATUS_V2)) bridgesByStatus[v] = 0;
+  const swapsByStatus = {};
+  for (const v of Object.values(SWAP_STATUS_V2)) swapsByStatus[v] = 0;
+  const messagesByStatus = {};
+  for (const v of Object.values(MESSAGE_STATUS_V2)) messagesByStatus[v] = 0;
+  const chainUsage = {};
+  for (const v of Object.values(CHAIN_ID_V2)) chainUsage[v] = 0;
+
+  let totalBridgeVolume = 0;
+  let totalFees = 0;
+  let activeBridges = 0;
+  for (const b of _bridges.values()) {
+    bridgesByStatus[b.status] = (bridgesByStatus[b.status] || 0) + 1;
+    chainUsage[b.from_chain] = (chainUsage[b.from_chain] || 0) + 1;
+    chainUsage[b.to_chain] = (chainUsage[b.to_chain] || 0) + 1;
+    totalBridgeVolume += b.amount;
+    totalFees += b.fee_amount;
+    if (!BRIDGE_TERMINALS_V2.has(b.status)) activeBridges += 1;
+  }
+
+  for (const s of _swaps.values()) {
+    swapsByStatus[s.status] = (swapsByStatus[s.status] || 0) + 1;
+    chainUsage[s.from_chain] = (chainUsage[s.from_chain] || 0) + 1;
+    chainUsage[s.to_chain] = (chainUsage[s.to_chain] || 0) + 1;
+  }
+
+  for (const m of _messages.values()) {
+    messagesByStatus[m.status] = (messagesByStatus[m.status] || 0) + 1;
+    chainUsage[m.from_chain] = (chainUsage[m.from_chain] || 0) + 1;
+    chainUsage[m.to_chain] = (chainUsage[m.to_chain] || 0) + 1;
+  }
+
+  return {
+    totalBridges: _bridges.size,
+    totalSwaps: _swaps.size,
+    totalMessages: _messages.size,
+    activeBridges,
+    maxActiveBridgesPerAddress: _maxActiveBridgesPerAddress,
+    bridgesByStatus,
+    swapsByStatus,
+    messagesByStatus,
+    chainUsage,
+    totalBridgeVolume,
+    totalFees: Math.round(totalFees * 1000) / 1000,
+    configuredChains: _chainConfigs.size,
+  };
 }

package/src/lib/crypto-manager.js

@@ -244,3 +244,353 @@ export function getEncryptedFileInfo(filePath) {
     modified: stats.mtime.toISOString(),
   };
 }
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * V2 in-memory governance layer (independent of file/buffer crypto helpers)
+ * ───────────────────────────────────────────────────────────────────────── */
+
+export const KEY_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  ROTATED: "rotated",
+  RETIRED: "retired",
+});
+
+export const CRYPTO_JOB_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const KEY_TERMINAL_V2 = new Set([KEY_MATURITY_V2.RETIRED]);
+const JOB_TERMINAL_V2 = new Set([
+  CRYPTO_JOB_LIFECYCLE_V2.COMPLETED,
+  CRYPTO_JOB_LIFECYCLE_V2.FAILED,
+  CRYPTO_JOB_LIFECYCLE_V2.CANCELLED,
+]);
+
+const KEY_TRANSITIONS_V2 = new Map([
+  [
+    KEY_MATURITY_V2.PENDING,
+    new Set([KEY_MATURITY_V2.ACTIVE, KEY_MATURITY_V2.RETIRED]),
+  ],
+  [
+    KEY_MATURITY_V2.ACTIVE,
+    new Set([KEY_MATURITY_V2.ROTATED, KEY_MATURITY_V2.RETIRED]),
+  ],
+  [
+    KEY_MATURITY_V2.ROTATED,
+    new Set([KEY_MATURITY_V2.ACTIVE, KEY_MATURITY_V2.RETIRED]),
+  ],
+]);
+
+const JOB_TRANSITIONS_V2 = new Map([
+  [
+    CRYPTO_JOB_LIFECYCLE_V2.QUEUED,
+    new Set([
+      CRYPTO_JOB_LIFECYCLE_V2.RUNNING,
+      CRYPTO_JOB_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [
+    CRYPTO_JOB_LIFECYCLE_V2.RUNNING,
+    new Set([
+      CRYPTO_JOB_LIFECYCLE_V2.COMPLETED,
+      CRYPTO_JOB_LIFECYCLE_V2.FAILED,
+      CRYPTO_JOB_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+]);
+
+export const CRYPTO_DEFAULT_MAX_ACTIVE_KEYS_PER_OWNER = 12;
+export const CRYPTO_DEFAULT_MAX_PENDING_JOBS_PER_KEY = 16;
+export const CRYPTO_DEFAULT_KEY_IDLE_MS = 14 * 24 * 60 * 60 * 1000;
+export const CRYPTO_DEFAULT_JOB_STUCK_MS = 5 * 60 * 1000;
+
+let _maxActiveKeysPerOwnerV2 = CRYPTO_DEFAULT_MAX_ACTIVE_KEYS_PER_OWNER;
+let _maxPendingJobsPerKeyV2 = CRYPTO_DEFAULT_MAX_PENDING_JOBS_PER_KEY;
+let _keyIdleMsV2 = CRYPTO_DEFAULT_KEY_IDLE_MS;
+let _jobStuckMsV2 = CRYPTO_DEFAULT_JOB_STUCK_MS;
+
+const _keysV2 = new Map();
+const _jobsV2 = new Map();
+
+function _posIntCryptoV2(n, label) {
+  if (typeof n !== "number" || !Number.isFinite(n) || n <= 0) {
+    throw new Error(`${label} must be a positive number`);
+  }
+  return Math.floor(n);
+}
+
+export function getMaxActiveKeysPerOwnerV2() {
+  return _maxActiveKeysPerOwnerV2;
+}
+export function setMaxActiveKeysPerOwnerV2(n) {
+  _maxActiveKeysPerOwnerV2 = _posIntCryptoV2(n, "maxActiveKeysPerOwner");
+  return _maxActiveKeysPerOwnerV2;
+}
+export function getMaxPendingJobsPerKeyV2() {
+  return _maxPendingJobsPerKeyV2;
+}
+export function setMaxPendingJobsPerKeyV2(n) {
+  _maxPendingJobsPerKeyV2 = _posIntCryptoV2(n, "maxPendingJobsPerKey");
+  return _maxPendingJobsPerKeyV2;
+}
+export function getKeyIdleMsV2() {
+  return _keyIdleMsV2;
+}
+export function setKeyIdleMsV2(ms) {
+  _keyIdleMsV2 = _posIntCryptoV2(ms, "keyIdleMs");
+  return _keyIdleMsV2;
+}
+export function getJobStuckMsV2() {
+  return _jobStuckMsV2;
+}
+export function setJobStuckMsV2(ms) {
+  _jobStuckMsV2 = _posIntCryptoV2(ms, "jobStuckMs");
+  return _jobStuckMsV2;
+}
+
+export function getActiveKeyCountV2(ownerId) {
+  let n = 0;
+  for (const k of _keysV2.values()) {
+    if (k.status !== KEY_MATURITY_V2.ACTIVE) continue;
+    if (ownerId && k.ownerId !== ownerId) continue;
+    n++;
+  }
+  return n;
+}
+
+export function getPendingJobCountV2(keyId) {
+  let n = 0;
+  for (const j of _jobsV2.values()) {
+    if (
+      j.status !== CRYPTO_JOB_LIFECYCLE_V2.QUEUED &&
+      j.status !== CRYPTO_JOB_LIFECYCLE_V2.RUNNING
+    )
+      continue;
+    if (keyId && j.keyId !== keyId) continue;
+    n++;
+  }
+  return n;
+}
+
+function _cloneKeyCryptoV2(k) {
+  return { ...k, metadata: { ...k.metadata } };
+}
+function _cloneJobCryptoV2(j) {
+  return { ...j, metadata: { ...j.metadata } };
+}
+
+export function registerKeyV2(
+  id,
+  { ownerId, algorithm, purpose, metadata } = {},
+) {
+  if (!id || typeof id !== "string") throw new Error("key id required");
+  if (!ownerId || typeof ownerId !== "string")
+    throw new Error("ownerId required");
+  if (!algorithm || typeof algorithm !== "string")
+    throw new Error("algorithm required");
+  if (_keysV2.has(id)) throw new Error(`key ${id} already exists`);
+  const now = Date.now();
+  const key = {
+    id,
+    ownerId,
+    algorithm,
+    purpose: purpose || "encryption",
+    status: KEY_MATURITY_V2.PENDING,
+    createdAt: now,
+    activatedAt: null,
+    retiredAt: null,
+    lastSeenAt: now,
+    metadata: metadata ? { ...metadata } : {},
+  };
+  _keysV2.set(id, key);
+  return _cloneKeyCryptoV2(key);
+}
+
+export function getKeyV2(id) {
+  const k = _keysV2.get(id);
+  return k ? _cloneKeyCryptoV2(k) : null;
+}
+
+export function listKeysV2({ ownerId, status, algorithm } = {}) {
+  const out = [];
+  for (const k of _keysV2.values()) {
+    if (ownerId && k.ownerId !== ownerId) continue;
+    if (status && k.status !== status) continue;
+    if (algorithm && k.algorithm !== algorithm) continue;
+    out.push(_cloneKeyCryptoV2(k));
+  }
+  return out;
+}
+
+export function setKeyStatusV2(id, next) {
+  const k = _keysV2.get(id);
+  if (!k) throw new Error(`unknown key ${id}`);
+  if (KEY_TERMINAL_V2.has(k.status)) {
+    throw new Error(`key ${id} is terminal (${k.status})`);
+  }
+  const allowed = KEY_TRANSITIONS_V2.get(k.status);
+  if (!allowed || !allowed.has(next)) {
+    throw new Error(`invalid key transition ${k.status} -> ${next}`);
+  }
+  if (next === KEY_MATURITY_V2.ACTIVE && k.status === KEY_MATURITY_V2.PENDING) {
+    const owned = getActiveKeyCountV2(k.ownerId);
+    if (owned >= _maxActiveKeysPerOwnerV2) {
+      throw new Error(
+        `owner ${k.ownerId} active key cap reached (${_maxActiveKeysPerOwnerV2})`,
+      );
+    }
+  }
+  const now = Date.now();
+  k.status = next;
+  if (next === KEY_MATURITY_V2.ACTIVE && !k.activatedAt) k.activatedAt = now;
+  if (next === KEY_MATURITY_V2.RETIRED && !k.retiredAt) k.retiredAt = now;
+  k.lastSeenAt = now;
+  return _cloneKeyCryptoV2(k);
+}
+
+export function activateKeyV2(id) {
+  return setKeyStatusV2(id, KEY_MATURITY_V2.ACTIVE);
+}
+export function rotateKeyV2(id) {
+  return setKeyStatusV2(id, KEY_MATURITY_V2.ROTATED);
+}
+export function retireKeyV2(id) {
+  return setKeyStatusV2(id, KEY_MATURITY_V2.RETIRED);
+}
+
+export function touchKeyV2(id) {
+  const k = _keysV2.get(id);
+  if (!k) throw new Error(`unknown key ${id}`);
+  k.lastSeenAt = Date.now();
+  return _cloneKeyCryptoV2(k);
+}
+
+export function createJobV2(id, { keyId, kind, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("job id required");
+  if (!keyId || typeof keyId !== "string") throw new Error("keyId required");
+  if (_jobsV2.has(id)) throw new Error(`job ${id} already exists`);
+  if (!_keysV2.has(keyId)) throw new Error(`unknown key ${keyId}`);
+  const pending = getPendingJobCountV2(keyId);
+  if (pending >= _maxPendingJobsPerKeyV2) {
+    throw new Error(
+      `key ${keyId} pending job cap reached (${_maxPendingJobsPerKeyV2})`,
+    );
+  }
+  const now = Date.now();
+  const job = {
+    id,
+    keyId,
+    kind: kind || "encrypt",
+    status: CRYPTO_JOB_LIFECYCLE_V2.QUEUED,
+    createdAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: metadata ? { ...metadata } : {},
+  };
+  _jobsV2.set(id, job);
+  return _cloneJobCryptoV2(job);
+}
+
+export function getJobV2(id) {
+  const j = _jobsV2.get(id);
+  return j ? _cloneJobCryptoV2(j) : null;
+}
+
+export function listJobsV2({ keyId, status, kind } = {}) {
+  const out = [];
+  for (const j of _jobsV2.values()) {
+    if (keyId && j.keyId !== keyId) continue;
+    if (status && j.status !== status) continue;
+    if (kind && j.kind !== kind) continue;
+    out.push(_cloneJobCryptoV2(j));
+  }
+  return out;
+}
+
+export function setJobStatusV2(id, next) {
+  const j = _jobsV2.get(id);
+  if (!j) throw new Error(`unknown job ${id}`);
+  if (JOB_TERMINAL_V2.has(j.status)) {
+    throw new Error(`job ${id} is terminal (${j.status})`);
+  }
+  const allowed = JOB_TRANSITIONS_V2.get(j.status);
+  if (!allowed || !allowed.has(next)) {
+    throw new Error(`invalid job transition ${j.status} -> ${next}`);
+  }
+  const now = Date.now();
+  j.status = next;
+  if (next === CRYPTO_JOB_LIFECYCLE_V2.RUNNING && !j.startedAt)
+    j.startedAt = now;
+  if (JOB_TERMINAL_V2.has(next) && !j.settledAt) j.settledAt = now;
+  return _cloneJobCryptoV2(j);
+}
+
+export function startJobV2(id) {
+  return setJobStatusV2(id, CRYPTO_JOB_LIFECYCLE_V2.RUNNING);
+}
+export function completeJobV2(id) {
+  return setJobStatusV2(id, CRYPTO_JOB_LIFECYCLE_V2.COMPLETED);
+}
+export function failJobV2(id) {
+  return setJobStatusV2(id, CRYPTO_JOB_LIFECYCLE_V2.FAILED);
+}
+export function cancelJobV2(id) {
+  return setJobStatusV2(id, CRYPTO_JOB_LIFECYCLE_V2.CANCELLED);
+}
+
+export function autoRotateIdleKeysV2({ now = Date.now() } = {}) {
+  const out = [];
+  for (const k of _keysV2.values()) {
+    if (k.status !== KEY_MATURITY_V2.ACTIVE) continue;
+    if (now - k.lastSeenAt < _keyIdleMsV2) continue;
+    k.status = KEY_MATURITY_V2.ROTATED;
+    k.lastSeenAt = now;
+    out.push(_cloneKeyCryptoV2(k));
+  }
+  return out;
+}
+
+export function autoFailStuckJobsV2({ now = Date.now() } = {}) {
+  const out = [];
+  for (const j of _jobsV2.values()) {
+    if (j.status !== CRYPTO_JOB_LIFECYCLE_V2.RUNNING) continue;
+    if (!j.startedAt || now - j.startedAt < _jobStuckMsV2) continue;
+    j.status = CRYPTO_JOB_LIFECYCLE_V2.FAILED;
+    j.settledAt = now;
+    out.push(_cloneJobCryptoV2(j));
+  }
+  return out;
+}
+
+export function getCryptoManagerStatsV2() {
+  const keysByStatus = {};
+  for (const s of Object.values(KEY_MATURITY_V2)) keysByStatus[s] = 0;
+  for (const k of _keysV2.values()) keysByStatus[k.status]++;
+  const jobsByStatus = {};
+  for (const s of Object.values(CRYPTO_JOB_LIFECYCLE_V2)) jobsByStatus[s] = 0;
+  for (const j of _jobsV2.values()) jobsByStatus[j.status]++;
+  return {
+    totalKeysV2: _keysV2.size,
+    totalJobsV2: _jobsV2.size,
+    maxActiveKeysPerOwner: _maxActiveKeysPerOwnerV2,
+    maxPendingJobsPerKey: _maxPendingJobsPerKeyV2,
+    keyIdleMs: _keyIdleMsV2,
+    jobStuckMs: _jobStuckMsV2,
+    keysByStatus,
+    jobsByStatus,
+  };
+}
+
+export function _resetStateCryptoManagerV2() {
+  _keysV2.clear();
+  _jobsV2.clear();
+  _maxActiveKeysPerOwnerV2 = CRYPTO_DEFAULT_MAX_ACTIVE_KEYS_PER_OWNER;
+  _maxPendingJobsPerKeyV2 = CRYPTO_DEFAULT_MAX_PENDING_JOBS_PER_KEY;
+  _keyIdleMsV2 = CRYPTO_DEFAULT_KEY_IDLE_MS;
+  _jobStuckMsV2 = CRYPTO_DEFAULT_JOB_STUCK_MS;
+}