chainlesschain 0.81.0 → 0.132.0

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;
+}

package/src/lib/dbevo.js

@@ -667,3 +667,341 @@ export function _resetState() {
   _suggestions.clear();
   _slowQueryThresholdMs = 100;
 }
+
+/* ═════════════════════════════════════════════════════════ *
+ *  Phase 80 V2 — Schema Baseline + Migration-Run Lifecycle
+ * ═════════════════════════════════════════════════════════ */
+
+export const SCHEMA_BASELINE_V2 = Object.freeze({
+  DRAFT: "draft",
+  VALIDATED: "validated",
+  ACTIVE: "active",
+  DEPRECATED: "deprecated",
+  RETIRED: "retired",
+});
+
+export const MIGRATION_RUN_V2 = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  APPLIED: "applied",
+  FAILED: "failed",
+  ROLLED_BACK: "rolled_back",
+});
+
+const BASELINE_TRANSITIONS_V2 = new Map([
+  ["draft", new Set(["validated", "retired"])],
+  ["validated", new Set(["active", "retired"])],
+  ["active", new Set(["deprecated", "retired"])],
+  ["deprecated", new Set(["active", "retired"])],
+]);
+const BASELINE_TERMINALS_V2 = new Set(["retired"]);
+
+const RUN_TRANSITIONS_V2 = new Map([
+  ["queued", new Set(["running", "failed"])],
+  ["running", new Set(["applied", "failed", "rolled_back"])],
+  ["applied", new Set(["rolled_back"])],
+]);
+const RUN_TERMINALS_V2 = new Set(["failed", "rolled_back"]);
+
+export const DBEVO_DEFAULT_MAX_ACTIVE_BASELINES_PER_DB = 1;
+export const DBEVO_DEFAULT_MAX_RUNNING_MIGRATIONS_PER_DB = 1;
+export const DBEVO_DEFAULT_BASELINE_IDLE_MS = 180 * 86400000; // 180 days
+export const DBEVO_DEFAULT_MIGRATION_STUCK_MS = 30 * 60000; // 30 minutes
+
+let _maxActiveBaselinesPerDbV2 = DBEVO_DEFAULT_MAX_ACTIVE_BASELINES_PER_DB;
+let _maxRunningMigrationsPerDbV2 = DBEVO_DEFAULT_MAX_RUNNING_MIGRATIONS_PER_DB;
+let _baselineIdleMsV2 = DBEVO_DEFAULT_BASELINE_IDLE_MS;
+let _migrationStuckMsV2 = DBEVO_DEFAULT_MIGRATION_STUCK_MS;
+
+function _positiveIntV2(n, label) {
+  const v = Math.floor(Number(n));
+  if (!Number.isFinite(v) || v <= 0)
+    throw new Error(`${label} must be a positive integer`);
+  return v;
+}
+
+export function getDefaultMaxActiveBaselinesPerDbV2() {
+  return DBEVO_DEFAULT_MAX_ACTIVE_BASELINES_PER_DB;
+}
+export function getMaxActiveBaselinesPerDbV2() {
+  return _maxActiveBaselinesPerDbV2;
+}
+export function setMaxActiveBaselinesPerDbV2(n) {
+  return (_maxActiveBaselinesPerDbV2 = _positiveIntV2(
+    n,
+    "maxActiveBaselinesPerDb",
+  ));
+}
+export function getDefaultMaxRunningMigrationsPerDbV2() {
+  return DBEVO_DEFAULT_MAX_RUNNING_MIGRATIONS_PER_DB;
+}
+export function getMaxRunningMigrationsPerDbV2() {
+  return _maxRunningMigrationsPerDbV2;
+}
+export function setMaxRunningMigrationsPerDbV2(n) {
+  return (_maxRunningMigrationsPerDbV2 = _positiveIntV2(
+    n,
+    "maxRunningMigrationsPerDb",
+  ));
+}
+export function getDefaultBaselineIdleMsV2() {
+  return DBEVO_DEFAULT_BASELINE_IDLE_MS;
+}
+export function getBaselineIdleMsV2() {
+  return _baselineIdleMsV2;
+}
+export function setBaselineIdleMsV2(ms) {
+  return (_baselineIdleMsV2 = _positiveIntV2(ms, "baselineIdleMs"));
+}
+export function getDefaultMigrationStuckMsV2() {
+  return DBEVO_DEFAULT_MIGRATION_STUCK_MS;
+}
+export function getMigrationStuckMsV2() {
+  return _migrationStuckMsV2;
+}
+export function setMigrationStuckMsV2(ms) {
+  return (_migrationStuckMsV2 = _positiveIntV2(ms, "migrationStuckMs"));
+}
+
+const _baselinesV2 = new Map();
+const _runsV2 = new Map();
+
+export function registerBaselineV2(
+  _db,
+  { baselineId, databaseId, version, initialStatus, metadata } = {},
+) {
+  if (!baselineId) throw new Error("baselineId is required");
+  if (!databaseId) throw new Error("databaseId is required");
+  if (!version) throw new Error("version is required");
+  if (_baselinesV2.has(baselineId))
+    throw new Error(`Baseline ${baselineId} already exists`);
+  const status = initialStatus || SCHEMA_BASELINE_V2.DRAFT;
+  if (!Object.values(SCHEMA_BASELINE_V2).includes(status))
+    throw new Error(`Invalid initial status: ${status}`);
+  if (BASELINE_TERMINALS_V2.has(status))
+    throw new Error(`Cannot register in terminal status: ${status}`);
+  if (status === SCHEMA_BASELINE_V2.ACTIVE) {
+    if (getActiveBaselineCount(databaseId) >= _maxActiveBaselinesPerDbV2)
+      throw new Error(
+        `Database ${databaseId} reached active-baseline cap (${_maxActiveBaselinesPerDbV2})`,
+      );
+  }
+  const now = Date.now();
+  const record = {
+    baselineId,
+    databaseId,
+    version,
+    status,
+    metadata: metadata || {},
+    createdAt: now,
+    updatedAt: now,
+    lastTouchedAt: now,
+  };
+  _baselinesV2.set(baselineId, record);
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getBaselineV2(baselineId) {
+  const r = _baselinesV2.get(baselineId);
+  return r ? { ...r, metadata: { ...r.metadata } } : null;
+}
+
+export function setBaselineStatusV2(_db, baselineId, newStatus, patch = {}) {
+  const record = _baselinesV2.get(baselineId);
+  if (!record) throw new Error(`Unknown baseline: ${baselineId}`);
+  if (!Object.values(SCHEMA_BASELINE_V2).includes(newStatus))
+    throw new Error(`Invalid status: ${newStatus}`);
+  const allowed = BASELINE_TRANSITIONS_V2.get(record.status) || new Set();
+  if (!allowed.has(newStatus))
+    throw new Error(`Invalid transition: ${record.status} -> ${newStatus}`);
+  if (newStatus === SCHEMA_BASELINE_V2.ACTIVE) {
+    if (getActiveBaselineCount(record.databaseId) >= _maxActiveBaselinesPerDbV2)
+      throw new Error(
+        `Database ${record.databaseId} reached active-baseline cap (${_maxActiveBaselinesPerDbV2})`,
+      );
+  }
+  record.status = newStatus;
+  record.updatedAt = Date.now();
+  if (patch.reason !== undefined) record.lastReason = patch.reason;
+  if (patch.metadata)
+    record.metadata = { ...record.metadata, ...patch.metadata };
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function validateBaseline(db, id, reason) {
+  return setBaselineStatusV2(db, id, SCHEMA_BASELINE_V2.VALIDATED, { reason });
+}
+export function activateBaseline(db, id, reason) {
+  return setBaselineStatusV2(db, id, SCHEMA_BASELINE_V2.ACTIVE, { reason });
+}
+export function deprecateBaseline(db, id, reason) {
+  return setBaselineStatusV2(db, id, SCHEMA_BASELINE_V2.DEPRECATED, { reason });
+}
+export function retireBaseline(db, id, reason) {
+  return setBaselineStatusV2(db, id, SCHEMA_BASELINE_V2.RETIRED, { reason });
+}
+
+export function touchBaselineActivity(baselineId) {
+  const record = _baselinesV2.get(baselineId);
+  if (!record) throw new Error(`Unknown baseline: ${baselineId}`);
+  record.lastTouchedAt = Date.now();
+  record.updatedAt = record.lastTouchedAt;
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function enqueueMigrationRunV2(
+  _db,
+  { runId, databaseId, migrationId, direction, metadata } = {},
+) {
+  if (!runId) throw new Error("runId is required");
+  if (!databaseId) throw new Error("databaseId is required");
+  if (!migrationId) throw new Error("migrationId is required");
+  if (!direction) throw new Error("direction is required");
+  if (!Object.values(MIGRATION_DIRECTION).includes(direction))
+    throw new Error(`Invalid direction: ${direction}`);
+  if (_runsV2.has(runId)) throw new Error(`Run ${runId} already exists`);
+  const now = Date.now();
+  const record = {
+    runId,
+    databaseId,
+    migrationId,
+    direction,
+    status: MIGRATION_RUN_V2.QUEUED,
+    metadata: metadata || {},
+    createdAt: now,
+    updatedAt: now,
+  };
+  _runsV2.set(runId, record);
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getMigrationRunV2(runId) {
+  const r = _runsV2.get(runId);
+  return r ? { ...r, metadata: { ...r.metadata } } : null;
+}
+
+export function setMigrationRunStatusV2(_db, runId, newStatus, patch = {}) {
+  const record = _runsV2.get(runId);
+  if (!record) throw new Error(`Unknown run: ${runId}`);
+  if (!Object.values(MIGRATION_RUN_V2).includes(newStatus))
+    throw new Error(`Invalid status: ${newStatus}`);
+  const allowed = RUN_TRANSITIONS_V2.get(record.status) || new Set();
+  if (!allowed.has(newStatus))
+    throw new Error(`Invalid transition: ${record.status} -> ${newStatus}`);
+  if (newStatus === MIGRATION_RUN_V2.RUNNING) {
+    if (
+      getRunningMigrationCount(record.databaseId) >=
+      _maxRunningMigrationsPerDbV2
+    )
+      throw new Error(
+        `Database ${record.databaseId} reached running-migration cap (${_maxRunningMigrationsPerDbV2})`,
+      );
+    if (!record.startedAt) record.startedAt = Date.now();
+  }
+  record.status = newStatus;
+  record.updatedAt = Date.now();
+  if (patch.reason !== undefined) record.lastReason = patch.reason;
+  if (patch.metadata)
+    record.metadata = { ...record.metadata, ...patch.metadata };
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function startMigrationRun(db, id, reason) {
+  return setMigrationRunStatusV2(db, id, MIGRATION_RUN_V2.RUNNING, { reason });
+}
+export function applyMigrationRun(db, id, reason) {
+  return setMigrationRunStatusV2(db, id, MIGRATION_RUN_V2.APPLIED, { reason });
+}
+export function failMigrationRun(db, id, reason) {
+  return setMigrationRunStatusV2(db, id, MIGRATION_RUN_V2.FAILED, { reason });
+}
+export function rollbackMigrationRun(db, id, reason) {
+  return setMigrationRunStatusV2(db, id, MIGRATION_RUN_V2.ROLLED_BACK, {
+    reason,
+  });
+}
+
+export function getActiveBaselineCount(databaseId) {
+  let n = 0;
+  for (const r of _baselinesV2.values()) {
+    if (r.status !== SCHEMA_BASELINE_V2.ACTIVE) continue;
+    if (databaseId && r.databaseId !== databaseId) continue;
+    n++;
+  }
+  return n;
+}
+
+export function getRunningMigrationCount(databaseId) {
+  let n = 0;
+  for (const r of _runsV2.values()) {
+    if (r.status !== MIGRATION_RUN_V2.RUNNING) continue;
+    if (databaseId && r.databaseId !== databaseId) continue;
+    n++;
+  }
+  return n;
+}
+
+export function autoRetireIdleBaselines(_db, nowMs) {
+  const now = nowMs ?? Date.now();
+  const flipped = [];
+  for (const r of _baselinesV2.values()) {
+    if (
+      r.status === SCHEMA_BASELINE_V2.DEPRECATED ||
+      r.status === SCHEMA_BASELINE_V2.DRAFT ||
+      r.status === SCHEMA_BASELINE_V2.VALIDATED
+    ) {
+      if (now - r.lastTouchedAt > _baselineIdleMsV2) {
+        r.status = SCHEMA_BASELINE_V2.RETIRED;
+        r.updatedAt = now;
+        r.lastReason = "idle_timeout";
+        flipped.push(r.baselineId);
+      }
+    }
+  }
+  return { flipped, count: flipped.length };
+}
+
+export function autoFailStuckMigrationRuns(_db, nowMs) {
+  const now = nowMs ?? Date.now();
+  const flipped = [];
+  for (const r of _runsV2.values()) {
+    if (r.status === MIGRATION_RUN_V2.RUNNING) {
+      const anchor = r.startedAt || r.createdAt;
+      if (now - anchor > _migrationStuckMsV2) {
+        r.status = MIGRATION_RUN_V2.FAILED;
+        r.updatedAt = now;
+        r.lastReason = "migration_timeout";
+        flipped.push(r.runId);
+      }
+    }
+  }
+  return { flipped, count: flipped.length };
+}
+
+export function getDbEvoStatsV2() {
+  const baselinesByStatus = {};
+  for (const s of Object.values(SCHEMA_BASELINE_V2)) baselinesByStatus[s] = 0;
+  const runsByStatus = {};
+  for (const s of Object.values(MIGRATION_RUN_V2)) runsByStatus[s] = 0;
+  for (const r of _baselinesV2.values()) baselinesByStatus[r.status]++;
+  for (const r of _runsV2.values()) runsByStatus[r.status]++;
+  return {
+    totalBaselinesV2: _baselinesV2.size,
+    totalRunsV2: _runsV2.size,
+    maxActiveBaselinesPerDb: _maxActiveBaselinesPerDbV2,
+    maxRunningMigrationsPerDb: _maxRunningMigrationsPerDbV2,
+    baselineIdleMs: _baselineIdleMsV2,
+    migrationStuckMs: _migrationStuckMsV2,
+    baselinesByStatus,
+    runsByStatus,
+  };
+}
+
+export function _resetStateV2() {
+  _maxActiveBaselinesPerDbV2 = DBEVO_DEFAULT_MAX_ACTIVE_BASELINES_PER_DB;
+  _maxRunningMigrationsPerDbV2 = DBEVO_DEFAULT_MAX_RUNNING_MIGRATIONS_PER_DB;
+  _baselineIdleMsV2 = DBEVO_DEFAULT_BASELINE_IDLE_MS;
+  _migrationStuckMsV2 = DBEVO_DEFAULT_MIGRATION_STUCK_MS;
+  _baselinesV2.clear();
+  _runsV2.clear();
+}