chainlesschain 0.132.0 → 0.145.0

package/src/lib/dlp-engine.js

@@ -691,3 +691,346 @@ export function getHighestUnresolvedSeverity() {
 }
 
 export { _v2PolicyMeta, _v2IncidentMeta, _builtinPolicyTemplates };
+
+// ===== V2 Surface: DLP Engine governance overlay (CLI v0.135.0) =====
+export const DLP_POLICY_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  SUSPENDED: "suspended",
+  RETIRED: "retired",
+});
+export const DLP_SCAN_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  SCANNING: "scanning",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const _dlpPolTrans = new Map([
+  [
+    DLP_POLICY_MATURITY_V2.PENDING,
+    new Set([DLP_POLICY_MATURITY_V2.ACTIVE, DLP_POLICY_MATURITY_V2.RETIRED]),
+  ],
+  [
+    DLP_POLICY_MATURITY_V2.ACTIVE,
+    new Set([DLP_POLICY_MATURITY_V2.SUSPENDED, DLP_POLICY_MATURITY_V2.RETIRED]),
+  ],
+  [
+    DLP_POLICY_MATURITY_V2.SUSPENDED,
+    new Set([DLP_POLICY_MATURITY_V2.ACTIVE, DLP_POLICY_MATURITY_V2.RETIRED]),
+  ],
+  [DLP_POLICY_MATURITY_V2.RETIRED, new Set()],
+]);
+const _dlpPolTerminal = new Set([DLP_POLICY_MATURITY_V2.RETIRED]);
+const _dlpScanTrans = new Map([
+  [
+    DLP_SCAN_LIFECYCLE_V2.QUEUED,
+    new Set([DLP_SCAN_LIFECYCLE_V2.SCANNING, DLP_SCAN_LIFECYCLE_V2.CANCELLED]),
+  ],
+  [
+    DLP_SCAN_LIFECYCLE_V2.SCANNING,
+    new Set([
+      DLP_SCAN_LIFECYCLE_V2.COMPLETED,
+      DLP_SCAN_LIFECYCLE_V2.FAILED,
+      DLP_SCAN_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [DLP_SCAN_LIFECYCLE_V2.COMPLETED, new Set()],
+  [DLP_SCAN_LIFECYCLE_V2.FAILED, new Set()],
+  [DLP_SCAN_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _dlpPols = new Map();
+const _dlpScans = new Map();
+let _dlpMaxActivePerOwner = 16;
+let _dlpMaxPendingPerPol = 20;
+let _dlpPolIdleMs = 12 * 60 * 60 * 1000;
+let _dlpScanStuckMs = 5 * 60 * 1000;
+
+function _dlpPos(n, lbl) {
+  const v = Math.floor(Number(n));
+  if (!Number.isFinite(v) || v <= 0)
+    throw new Error(`${lbl} must be positive integer`);
+  return v;
+}
+
+export function setMaxActiveDlpPoliciesPerOwnerV2(n) {
+  _dlpMaxActivePerOwner = _dlpPos(n, "maxActiveDlpPoliciesPerOwner");
+}
+export function getMaxActiveDlpPoliciesPerOwnerV2() {
+  return _dlpMaxActivePerOwner;
+}
+export function setMaxPendingDlpScansPerPolicyV2(n) {
+  _dlpMaxPendingPerPol = _dlpPos(n, "maxPendingDlpScansPerPolicy");
+}
+export function getMaxPendingDlpScansPerPolicyV2() {
+  return _dlpMaxPendingPerPol;
+}
+export function setDlpPolicyIdleMsV2(n) {
+  _dlpPolIdleMs = _dlpPos(n, "dlpPolicyIdleMs");
+}
+export function getDlpPolicyIdleMsV2() {
+  return _dlpPolIdleMs;
+}
+export function setDlpScanStuckMsV2(n) {
+  _dlpScanStuckMs = _dlpPos(n, "dlpScanStuckMs");
+}
+export function getDlpScanStuckMsV2() {
+  return _dlpScanStuckMs;
+}
+
+export function _resetStateDlpEngineV2() {
+  _dlpPols.clear();
+  _dlpScans.clear();
+  _dlpMaxActivePerOwner = 16;
+  _dlpMaxPendingPerPol = 20;
+  _dlpPolIdleMs = 12 * 60 * 60 * 1000;
+  _dlpScanStuckMs = 5 * 60 * 1000;
+}
+
+export function registerDlpPolicyV2({
+  id,
+  owner,
+  classification,
+  metadata,
+} = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_dlpPols.has(id)) throw new Error(`dlp policy ${id} already registered`);
+  const now = Date.now();
+  const p = {
+    id,
+    owner,
+    classification: classification || "internal",
+    status: DLP_POLICY_MATURITY_V2.PENDING,
+    createdAt: now,
+    updatedAt: now,
+    activatedAt: null,
+    retiredAt: null,
+    lastTouchedAt: now,
+    metadata: { ...(metadata || {}) },
+  };
+  _dlpPols.set(id, p);
+  return { ...p, metadata: { ...p.metadata } };
+}
+function _dlpCheckP(from, to) {
+  const a = _dlpPolTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid dlp policy transition ${from} → ${to}`);
+}
+function _dlpCountActive(owner) {
+  let n = 0;
+  for (const p of _dlpPols.values())
+    if (p.owner === owner && p.status === DLP_POLICY_MATURITY_V2.ACTIVE) n++;
+  return n;
+}
+
+export function activateDlpPolicyV2(id) {
+  const p = _dlpPols.get(id);
+  if (!p) throw new Error(`dlp policy ${id} not found`);
+  _dlpCheckP(p.status, DLP_POLICY_MATURITY_V2.ACTIVE);
+  const recovery = p.status === DLP_POLICY_MATURITY_V2.SUSPENDED;
+  if (!recovery) {
+    const a = _dlpCountActive(p.owner);
+    if (a >= _dlpMaxActivePerOwner)
+      throw new Error(
+        `max active dlp policies per owner (${_dlpMaxActivePerOwner}) reached for ${p.owner}`,
+      );
+  }
+  const now = Date.now();
+  p.status = DLP_POLICY_MATURITY_V2.ACTIVE;
+  p.updatedAt = now;
+  p.lastTouchedAt = now;
+  if (!p.activatedAt) p.activatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function suspendDlpPolicyV2(id) {
+  const p = _dlpPols.get(id);
+  if (!p) throw new Error(`dlp policy ${id} not found`);
+  _dlpCheckP(p.status, DLP_POLICY_MATURITY_V2.SUSPENDED);
+  p.status = DLP_POLICY_MATURITY_V2.SUSPENDED;
+  p.updatedAt = Date.now();
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function retireDlpPolicyV2(id) {
+  const p = _dlpPols.get(id);
+  if (!p) throw new Error(`dlp policy ${id} not found`);
+  _dlpCheckP(p.status, DLP_POLICY_MATURITY_V2.RETIRED);
+  const now = Date.now();
+  p.status = DLP_POLICY_MATURITY_V2.RETIRED;
+  p.updatedAt = now;
+  if (!p.retiredAt) p.retiredAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function touchDlpPolicyV2(id) {
+  const p = _dlpPols.get(id);
+  if (!p) throw new Error(`dlp policy ${id} not found`);
+  if (_dlpPolTerminal.has(p.status))
+    throw new Error(`cannot touch terminal dlp policy ${id}`);
+  const now = Date.now();
+  p.lastTouchedAt = now;
+  p.updatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function getDlpPolicyV2(id) {
+  const p = _dlpPols.get(id);
+  if (!p) return null;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function listDlpPoliciesV2() {
+  return [..._dlpPols.values()].map((p) => ({
+    ...p,
+    metadata: { ...p.metadata },
+  }));
+}
+
+function _dlpCountPending(pid) {
+  let n = 0;
+  for (const s of _dlpScans.values())
+    if (
+      s.policyId === pid &&
+      (s.status === DLP_SCAN_LIFECYCLE_V2.QUEUED ||
+        s.status === DLP_SCAN_LIFECYCLE_V2.SCANNING)
+    )
+      n++;
+  return n;
+}
+
+export function createDlpScanV2({ id, policyId, target, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!policyId || typeof policyId !== "string")
+    throw new Error("policyId is required");
+  if (_dlpScans.has(id)) throw new Error(`dlp scan ${id} already exists`);
+  if (!_dlpPols.has(policyId))
+    throw new Error(`dlp policy ${policyId} not found`);
+  const pending = _dlpCountPending(policyId);
+  if (pending >= _dlpMaxPendingPerPol)
+    throw new Error(
+      `max pending dlp scans per policy (${_dlpMaxPendingPerPol}) reached for ${policyId}`,
+    );
+  const now = Date.now();
+  const s = {
+    id,
+    policyId,
+    target: target || "",
+    status: DLP_SCAN_LIFECYCLE_V2.QUEUED,
+    createdAt: now,
+    updatedAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: { ...(metadata || {}) },
+  };
+  _dlpScans.set(id, s);
+  return { ...s, metadata: { ...s.metadata } };
+}
+function _dlpCheckS(from, to) {
+  const a = _dlpScanTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid dlp scan transition ${from} → ${to}`);
+}
+export function startDlpScanV2(id) {
+  const s = _dlpScans.get(id);
+  if (!s) throw new Error(`dlp scan ${id} not found`);
+  _dlpCheckS(s.status, DLP_SCAN_LIFECYCLE_V2.SCANNING);
+  const now = Date.now();
+  s.status = DLP_SCAN_LIFECYCLE_V2.SCANNING;
+  s.updatedAt = now;
+  if (!s.startedAt) s.startedAt = now;
+  return { ...s, metadata: { ...s.metadata } };
+}
+export function completeDlpScanV2(id) {
+  const s = _dlpScans.get(id);
+  if (!s) throw new Error(`dlp scan ${id} not found`);
+  _dlpCheckS(s.status, DLP_SCAN_LIFECYCLE_V2.COMPLETED);
+  const now = Date.now();
+  s.status = DLP_SCAN_LIFECYCLE_V2.COMPLETED;
+  s.updatedAt = now;
+  if (!s.settledAt) s.settledAt = now;
+  return { ...s, metadata: { ...s.metadata } };
+}
+export function failDlpScanV2(id, reason) {
+  const s = _dlpScans.get(id);
+  if (!s) throw new Error(`dlp scan ${id} not found`);
+  _dlpCheckS(s.status, DLP_SCAN_LIFECYCLE_V2.FAILED);
+  const now = Date.now();
+  s.status = DLP_SCAN_LIFECYCLE_V2.FAILED;
+  s.updatedAt = now;
+  if (!s.settledAt) s.settledAt = now;
+  if (reason) s.metadata.failReason = String(reason);
+  return { ...s, metadata: { ...s.metadata } };
+}
+export function cancelDlpScanV2(id, reason) {
+  const s = _dlpScans.get(id);
+  if (!s) throw new Error(`dlp scan ${id} not found`);
+  _dlpCheckS(s.status, DLP_SCAN_LIFECYCLE_V2.CANCELLED);
+  const now = Date.now();
+  s.status = DLP_SCAN_LIFECYCLE_V2.CANCELLED;
+  s.updatedAt = now;
+  if (!s.settledAt) s.settledAt = now;
+  if (reason) s.metadata.cancelReason = String(reason);
+  return { ...s, metadata: { ...s.metadata } };
+}
+export function getDlpScanV2(id) {
+  const s = _dlpScans.get(id);
+  if (!s) return null;
+  return { ...s, metadata: { ...s.metadata } };
+}
+export function listDlpScansV2() {
+  return [..._dlpScans.values()].map((s) => ({
+    ...s,
+    metadata: { ...s.metadata },
+  }));
+}
+
+export function autoSuspendIdleDlpPoliciesV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const p of _dlpPols.values())
+    if (
+      p.status === DLP_POLICY_MATURITY_V2.ACTIVE &&
+      t - p.lastTouchedAt >= _dlpPolIdleMs
+    ) {
+      p.status = DLP_POLICY_MATURITY_V2.SUSPENDED;
+      p.updatedAt = t;
+      flipped.push(p.id);
+    }
+  return { flipped, count: flipped.length };
+}
+export function autoFailStuckDlpScansV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const s of _dlpScans.values())
+    if (
+      s.status === DLP_SCAN_LIFECYCLE_V2.SCANNING &&
+      s.startedAt != null &&
+      t - s.startedAt >= _dlpScanStuckMs
+    ) {
+      s.status = DLP_SCAN_LIFECYCLE_V2.FAILED;
+      s.updatedAt = t;
+      if (!s.settledAt) s.settledAt = t;
+      s.metadata.failReason = "auto-fail-stuck";
+      flipped.push(s.id);
+    }
+  return { flipped, count: flipped.length };
+}
+
+export function getDlpEngineStatsV2() {
+  const policiesByStatus = {};
+  for (const s of Object.values(DLP_POLICY_MATURITY_V2))
+    policiesByStatus[s] = 0;
+  for (const p of _dlpPols.values()) policiesByStatus[p.status]++;
+  const scansByStatus = {};
+  for (const s of Object.values(DLP_SCAN_LIFECYCLE_V2)) scansByStatus[s] = 0;
+  for (const sc of _dlpScans.values()) scansByStatus[sc.status]++;
+  return {
+    totalPoliciesV2: _dlpPols.size,
+    totalScansV2: _dlpScans.size,
+    maxActiveDlpPoliciesPerOwner: _dlpMaxActivePerOwner,
+    maxPendingDlpScansPerPolicy: _dlpMaxPendingPerPol,
+    dlpPolicyIdleMs: _dlpPolIdleMs,
+    dlpScanStuckMs: _dlpScanStuckMs,
+    policiesByStatus,
+    scansByStatus,
+  };
+}

package/src/lib/evolution-system.js

@@ -959,3 +959,339 @@ export function _resetV2State() {
   _v2Config.predictionHorizonMs = 86400000;
   _v2Config.growthLogRetentionDays = 365;
 }
+
+// ===== V2 Surface: Evolution System governance overlay (CLI v0.137.0) =====
+export const EVO_GOAL_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  PAUSED: "paused",
+  ARCHIVED: "archived",
+});
+export const EVO_CYCLE_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const _evoGoalTrans = new Map([
+  [
+    EVO_GOAL_MATURITY_V2.PENDING,
+    new Set([EVO_GOAL_MATURITY_V2.ACTIVE, EVO_GOAL_MATURITY_V2.ARCHIVED]),
+  ],
+  [
+    EVO_GOAL_MATURITY_V2.ACTIVE,
+    new Set([EVO_GOAL_MATURITY_V2.PAUSED, EVO_GOAL_MATURITY_V2.ARCHIVED]),
+  ],
+  [
+    EVO_GOAL_MATURITY_V2.PAUSED,
+    new Set([EVO_GOAL_MATURITY_V2.ACTIVE, EVO_GOAL_MATURITY_V2.ARCHIVED]),
+  ],
+  [EVO_GOAL_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _evoGoalTerminal = new Set([EVO_GOAL_MATURITY_V2.ARCHIVED]);
+const _evoCycleTrans = new Map([
+  [
+    EVO_CYCLE_LIFECYCLE_V2.QUEUED,
+    new Set([EVO_CYCLE_LIFECYCLE_V2.RUNNING, EVO_CYCLE_LIFECYCLE_V2.CANCELLED]),
+  ],
+  [
+    EVO_CYCLE_LIFECYCLE_V2.RUNNING,
+    new Set([
+      EVO_CYCLE_LIFECYCLE_V2.COMPLETED,
+      EVO_CYCLE_LIFECYCLE_V2.FAILED,
+      EVO_CYCLE_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [EVO_CYCLE_LIFECYCLE_V2.COMPLETED, new Set()],
+  [EVO_CYCLE_LIFECYCLE_V2.FAILED, new Set()],
+  [EVO_CYCLE_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _evoGoals = new Map();
+const _evoCycles = new Map();
+let _evoMaxActivePerOwner = 6;
+let _evoMaxPendingPerGoal = 12;
+let _evoGoalIdleMs = 14 * 24 * 60 * 60 * 1000;
+let _evoCycleStuckMs = 10 * 60 * 1000;
+
+function _evoPos(n, lbl) {
+  const v = Math.floor(Number(n));
+  if (!Number.isFinite(v) || v <= 0)
+    throw new Error(`${lbl} must be positive integer`);
+  return v;
+}
+
+export function setMaxActiveEvoGoalsPerOwnerV2(n) {
+  _evoMaxActivePerOwner = _evoPos(n, "maxActiveEvoGoalsPerOwner");
+}
+export function getMaxActiveEvoGoalsPerOwnerV2() {
+  return _evoMaxActivePerOwner;
+}
+export function setMaxPendingEvoCyclesPerGoalV2(n) {
+  _evoMaxPendingPerGoal = _evoPos(n, "maxPendingEvoCyclesPerGoal");
+}
+export function getMaxPendingEvoCyclesPerGoalV2() {
+  return _evoMaxPendingPerGoal;
+}
+export function setEvoGoalIdleMsV2(n) {
+  _evoGoalIdleMs = _evoPos(n, "evoGoalIdleMs");
+}
+export function getEvoGoalIdleMsV2() {
+  return _evoGoalIdleMs;
+}
+export function setEvoCycleStuckMsV2(n) {
+  _evoCycleStuckMs = _evoPos(n, "evoCycleStuckMs");
+}
+export function getEvoCycleStuckMsV2() {
+  return _evoCycleStuckMs;
+}
+
+export function _resetStateEvolutionSystemV2() {
+  _evoGoals.clear();
+  _evoCycles.clear();
+  _evoMaxActivePerOwner = 6;
+  _evoMaxPendingPerGoal = 12;
+  _evoGoalIdleMs = 14 * 24 * 60 * 60 * 1000;
+  _evoCycleStuckMs = 10 * 60 * 1000;
+}
+
+export function registerEvoGoalV2({ id, owner, objective, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_evoGoals.has(id)) throw new Error(`evo goal ${id} already registered`);
+  const now = Date.now();
+  const g = {
+    id,
+    owner,
+    objective: objective || "",
+    status: EVO_GOAL_MATURITY_V2.PENDING,
+    createdAt: now,
+    updatedAt: now,
+    activatedAt: null,
+    archivedAt: null,
+    lastTouchedAt: now,
+    metadata: { ...(metadata || {}) },
+  };
+  _evoGoals.set(id, g);
+  return { ...g, metadata: { ...g.metadata } };
+}
+function _evoCheckG(from, to) {
+  const a = _evoGoalTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid evo goal transition ${from} → ${to}`);
+}
+function _evoCountActive(owner) {
+  let n = 0;
+  for (const g of _evoGoals.values())
+    if (g.owner === owner && g.status === EVO_GOAL_MATURITY_V2.ACTIVE) n++;
+  return n;
+}
+
+export function activateEvoGoalV2(id) {
+  const g = _evoGoals.get(id);
+  if (!g) throw new Error(`evo goal ${id} not found`);
+  _evoCheckG(g.status, EVO_GOAL_MATURITY_V2.ACTIVE);
+  const recovery = g.status === EVO_GOAL_MATURITY_V2.PAUSED;
+  if (!recovery) {
+    const a = _evoCountActive(g.owner);
+    if (a >= _evoMaxActivePerOwner)
+      throw new Error(
+        `max active evo goals per owner (${_evoMaxActivePerOwner}) reached for ${g.owner}`,
+      );
+  }
+  const now = Date.now();
+  g.status = EVO_GOAL_MATURITY_V2.ACTIVE;
+  g.updatedAt = now;
+  g.lastTouchedAt = now;
+  if (!g.activatedAt) g.activatedAt = now;
+  return { ...g, metadata: { ...g.metadata } };
+}
+export function pauseEvoGoalV2(id) {
+  const g = _evoGoals.get(id);
+  if (!g) throw new Error(`evo goal ${id} not found`);
+  _evoCheckG(g.status, EVO_GOAL_MATURITY_V2.PAUSED);
+  g.status = EVO_GOAL_MATURITY_V2.PAUSED;
+  g.updatedAt = Date.now();
+  return { ...g, metadata: { ...g.metadata } };
+}
+export function archiveEvoGoalV2(id) {
+  const g = _evoGoals.get(id);
+  if (!g) throw new Error(`evo goal ${id} not found`);
+  _evoCheckG(g.status, EVO_GOAL_MATURITY_V2.ARCHIVED);
+  const now = Date.now();
+  g.status = EVO_GOAL_MATURITY_V2.ARCHIVED;
+  g.updatedAt = now;
+  if (!g.archivedAt) g.archivedAt = now;
+  return { ...g, metadata: { ...g.metadata } };
+}
+export function touchEvoGoalV2(id) {
+  const g = _evoGoals.get(id);
+  if (!g) throw new Error(`evo goal ${id} not found`);
+  if (_evoGoalTerminal.has(g.status))
+    throw new Error(`cannot touch terminal evo goal ${id}`);
+  const now = Date.now();
+  g.lastTouchedAt = now;
+  g.updatedAt = now;
+  return { ...g, metadata: { ...g.metadata } };
+}
+export function getEvoGoalV2(id) {
+  const g = _evoGoals.get(id);
+  if (!g) return null;
+  return { ...g, metadata: { ...g.metadata } };
+}
+export function listEvoGoalsV2() {
+  return [..._evoGoals.values()].map((g) => ({
+    ...g,
+    metadata: { ...g.metadata },
+  }));
+}
+
+function _evoCountPending(gid) {
+  let n = 0;
+  for (const c of _evoCycles.values())
+    if (
+      c.goalId === gid &&
+      (c.status === EVO_CYCLE_LIFECYCLE_V2.QUEUED ||
+        c.status === EVO_CYCLE_LIFECYCLE_V2.RUNNING)
+    )
+      n++;
+  return n;
+}
+
+export function createEvoCycleV2({ id, goalId, generation, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!goalId || typeof goalId !== "string")
+    throw new Error("goalId is required");
+  if (_evoCycles.has(id)) throw new Error(`evo cycle ${id} already exists`);
+  if (!_evoGoals.has(goalId)) throw new Error(`evo goal ${goalId} not found`);
+  const pending = _evoCountPending(goalId);
+  if (pending >= _evoMaxPendingPerGoal)
+    throw new Error(
+      `max pending evo cycles per goal (${_evoMaxPendingPerGoal}) reached for ${goalId}`,
+    );
+  const now = Date.now();
+  const c = {
+    id,
+    goalId,
+    generation: generation ?? 0,
+    status: EVO_CYCLE_LIFECYCLE_V2.QUEUED,
+    createdAt: now,
+    updatedAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: { ...(metadata || {}) },
+  };
+  _evoCycles.set(id, c);
+  return { ...c, metadata: { ...c.metadata } };
+}
+function _evoCheckC(from, to) {
+  const a = _evoCycleTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid evo cycle transition ${from} → ${to}`);
+}
+export function startEvoCycleV2(id) {
+  const c = _evoCycles.get(id);
+  if (!c) throw new Error(`evo cycle ${id} not found`);
+  _evoCheckC(c.status, EVO_CYCLE_LIFECYCLE_V2.RUNNING);
+  const now = Date.now();
+  c.status = EVO_CYCLE_LIFECYCLE_V2.RUNNING;
+  c.updatedAt = now;
+  if (!c.startedAt) c.startedAt = now;
+  return { ...c, metadata: { ...c.metadata } };
+}
+export function completeEvoCycleV2(id) {
+  const c = _evoCycles.get(id);
+  if (!c) throw new Error(`evo cycle ${id} not found`);
+  _evoCheckC(c.status, EVO_CYCLE_LIFECYCLE_V2.COMPLETED);
+  const now = Date.now();
+  c.status = EVO_CYCLE_LIFECYCLE_V2.COMPLETED;
+  c.updatedAt = now;
+  if (!c.settledAt) c.settledAt = now;
+  return { ...c, metadata: { ...c.metadata } };
+}
+export function failEvoCycleV2(id, reason) {
+  const c = _evoCycles.get(id);
+  if (!c) throw new Error(`evo cycle ${id} not found`);
+  _evoCheckC(c.status, EVO_CYCLE_LIFECYCLE_V2.FAILED);
+  const now = Date.now();
+  c.status = EVO_CYCLE_LIFECYCLE_V2.FAILED;
+  c.updatedAt = now;
+  if (!c.settledAt) c.settledAt = now;
+  if (reason) c.metadata.failReason = String(reason);
+  return { ...c, metadata: { ...c.metadata } };
+}
+export function cancelEvoCycleV2(id, reason) {
+  const c = _evoCycles.get(id);
+  if (!c) throw new Error(`evo cycle ${id} not found`);
+  _evoCheckC(c.status, EVO_CYCLE_LIFECYCLE_V2.CANCELLED);
+  const now = Date.now();
+  c.status = EVO_CYCLE_LIFECYCLE_V2.CANCELLED;
+  c.updatedAt = now;
+  if (!c.settledAt) c.settledAt = now;
+  if (reason) c.metadata.cancelReason = String(reason);
+  return { ...c, metadata: { ...c.metadata } };
+}
+export function getEvoCycleV2(id) {
+  const c = _evoCycles.get(id);
+  if (!c) return null;
+  return { ...c, metadata: { ...c.metadata } };
+}
+export function listEvoCyclesV2() {
+  return [..._evoCycles.values()].map((c) => ({
+    ...c,
+    metadata: { ...c.metadata },
+  }));
+}
+
+export function autoPauseIdleEvoGoalsV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const g of _evoGoals.values())
+    if (
+      g.status === EVO_GOAL_MATURITY_V2.ACTIVE &&
+      t - g.lastTouchedAt >= _evoGoalIdleMs
+    ) {
+      g.status = EVO_GOAL_MATURITY_V2.PAUSED;
+      g.updatedAt = t;
+      flipped.push(g.id);
+    }
+  return { flipped, count: flipped.length };
+}
+export function autoFailStuckEvoCyclesV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const c of _evoCycles.values())
+    if (
+      c.status === EVO_CYCLE_LIFECYCLE_V2.RUNNING &&
+      c.startedAt != null &&
+      t - c.startedAt >= _evoCycleStuckMs
+    ) {
+      c.status = EVO_CYCLE_LIFECYCLE_V2.FAILED;
+      c.updatedAt = t;
+      if (!c.settledAt) c.settledAt = t;
+      c.metadata.failReason = "auto-fail-stuck";
+      flipped.push(c.id);
+    }
+  return { flipped, count: flipped.length };
+}
+
+export function getEvolutionSystemGovStatsV2() {
+  const goalsByStatus = {};
+  for (const s of Object.values(EVO_GOAL_MATURITY_V2)) goalsByStatus[s] = 0;
+  for (const g of _evoGoals.values()) goalsByStatus[g.status]++;
+  const cyclesByStatus = {};
+  for (const s of Object.values(EVO_CYCLE_LIFECYCLE_V2)) cyclesByStatus[s] = 0;
+  for (const c of _evoCycles.values()) cyclesByStatus[c.status]++;
+  return {
+    totalGoalsV2: _evoGoals.size,
+    totalCyclesV2: _evoCycles.size,
+    maxActiveEvoGoalsPerOwner: _evoMaxActivePerOwner,
+    maxPendingEvoCyclesPerGoal: _evoMaxPendingPerGoal,
+    evoGoalIdleMs: _evoGoalIdleMs,
+    evoCycleStuckMs: _evoCycleStuckMs,
+    goalsByStatus,
+    cyclesByStatus,
+  };
+}