chainlesschain 0.132.0 → 0.143.0

package/src/lib/evomap-manager.js

@@ -225,3 +225,108 @@ export class EvoMapManager {
     };
   }
 }
+
+
+// ===== V2 Surface: EvoMap Manager governance overlay (CLI v0.135.0) =====
+export const EVOMAP_MAP_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", STALE: "stale", ARCHIVED: "archived",
+});
+export const EVOMAP_EVOLUTION_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", RUNNING: "running", COMPLETED: "completed", FAILED: "failed", CANCELLED: "cancelled",
+});
+
+const _emMapTrans = new Map([
+  [EVOMAP_MAP_MATURITY_V2.PENDING, new Set([EVOMAP_MAP_MATURITY_V2.ACTIVE, EVOMAP_MAP_MATURITY_V2.ARCHIVED])],
+  [EVOMAP_MAP_MATURITY_V2.ACTIVE, new Set([EVOMAP_MAP_MATURITY_V2.STALE, EVOMAP_MAP_MATURITY_V2.ARCHIVED])],
+  [EVOMAP_MAP_MATURITY_V2.STALE, new Set([EVOMAP_MAP_MATURITY_V2.ACTIVE, EVOMAP_MAP_MATURITY_V2.ARCHIVED])],
+  [EVOMAP_MAP_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _emMapTerminal = new Set([EVOMAP_MAP_MATURITY_V2.ARCHIVED]);
+const _emEvoTrans = new Map([
+  [EVOMAP_EVOLUTION_LIFECYCLE_V2.QUEUED, new Set([EVOMAP_EVOLUTION_LIFECYCLE_V2.RUNNING, EVOMAP_EVOLUTION_LIFECYCLE_V2.CANCELLED])],
+  [EVOMAP_EVOLUTION_LIFECYCLE_V2.RUNNING, new Set([EVOMAP_EVOLUTION_LIFECYCLE_V2.COMPLETED, EVOMAP_EVOLUTION_LIFECYCLE_V2.FAILED, EVOMAP_EVOLUTION_LIFECYCLE_V2.CANCELLED])],
+  [EVOMAP_EVOLUTION_LIFECYCLE_V2.COMPLETED, new Set()],
+  [EVOMAP_EVOLUTION_LIFECYCLE_V2.FAILED, new Set()],
+  [EVOMAP_EVOLUTION_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _emMaps = new Map();
+const _emEvos = new Map();
+let _emMaxActivePerOwner = 10;
+let _emMaxPendingPerMap = 15;
+let _emMapIdleMs = 7 * 24 * 60 * 60 * 1000;
+let _emEvoStuckMs = 5 * 60 * 1000;
+
+function _emPos(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 setMaxActiveEvoMapsPerOwnerV2(n) { _emMaxActivePerOwner = _emPos(n, "maxActiveEvoMapsPerOwner"); }
+export function getMaxActiveEvoMapsPerOwnerV2() { return _emMaxActivePerOwner; }
+export function setMaxPendingEvoEvolutionsPerMapV2(n) { _emMaxPendingPerMap = _emPos(n, "maxPendingEvoEvolutionsPerMap"); }
+export function getMaxPendingEvoEvolutionsPerMapV2() { return _emMaxPendingPerMap; }
+export function setEvoMapIdleMsV2(n) { _emMapIdleMs = _emPos(n, "evoMapIdleMs"); }
+export function getEvoMapIdleMsV2() { return _emMapIdleMs; }
+export function setEvoEvolutionStuckMsV2(n) { _emEvoStuckMs = _emPos(n, "evoEvolutionStuckMs"); }
+export function getEvoEvolutionStuckMsV2() { return _emEvoStuckMs; }
+
+export function _resetStateEvoMapManagerV2() {
+  _emMaps.clear(); _emEvos.clear();
+  _emMaxActivePerOwner = 10; _emMaxPendingPerMap = 15;
+  _emMapIdleMs = 7 * 24 * 60 * 60 * 1000; _emEvoStuckMs = 5 * 60 * 1000;
+}
+
+export function registerEvoMapV2({ id, owner, name, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_emMaps.has(id)) throw new Error(`evomap ${id} already registered`);
+  const now = Date.now();
+  const m = { id, owner, name: name || id, status: EVOMAP_MAP_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, archivedAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _emMaps.set(id, m);
+  return { ...m, metadata: { ...m.metadata } };
+}
+function _emCheckM(from, to) { const a = _emMapTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid evomap transition ${from} → ${to}`); }
+function _emCountActive(owner) { let n = 0; for (const m of _emMaps.values()) if (m.owner === owner && m.status === EVOMAP_MAP_MATURITY_V2.ACTIVE) n++; return n; }
+
+export function activateEvoMapV2(id) {
+  const m = _emMaps.get(id); if (!m) throw new Error(`evomap ${id} not found`);
+  _emCheckM(m.status, EVOMAP_MAP_MATURITY_V2.ACTIVE);
+  const recovery = m.status === EVOMAP_MAP_MATURITY_V2.STALE;
+  if (!recovery) { const a = _emCountActive(m.owner); if (a >= _emMaxActivePerOwner) throw new Error(`max active evomaps per owner (${_emMaxActivePerOwner}) reached for ${m.owner}`); }
+  const now = Date.now(); m.status = EVOMAP_MAP_MATURITY_V2.ACTIVE; m.updatedAt = now; m.lastTouchedAt = now; if (!m.activatedAt) m.activatedAt = now;
+  return { ...m, metadata: { ...m.metadata } };
+}
+export function staleEvoMapV2(id) { const m = _emMaps.get(id); if (!m) throw new Error(`evomap ${id} not found`); _emCheckM(m.status, EVOMAP_MAP_MATURITY_V2.STALE); m.status = EVOMAP_MAP_MATURITY_V2.STALE; m.updatedAt = Date.now(); return { ...m, metadata: { ...m.metadata } }; }
+export function archiveEvoMapV2(id) { const m = _emMaps.get(id); if (!m) throw new Error(`evomap ${id} not found`); _emCheckM(m.status, EVOMAP_MAP_MATURITY_V2.ARCHIVED); const now = Date.now(); m.status = EVOMAP_MAP_MATURITY_V2.ARCHIVED; m.updatedAt = now; if (!m.archivedAt) m.archivedAt = now; return { ...m, metadata: { ...m.metadata } }; }
+export function touchEvoMapV2(id) { const m = _emMaps.get(id); if (!m) throw new Error(`evomap ${id} not found`); if (_emMapTerminal.has(m.status)) throw new Error(`cannot touch terminal evomap ${id}`); const now = Date.now(); m.lastTouchedAt = now; m.updatedAt = now; return { ...m, metadata: { ...m.metadata } }; }
+export function getEvoMapV2(id) { const m = _emMaps.get(id); if (!m) return null; return { ...m, metadata: { ...m.metadata } }; }
+export function listEvoMapsV2() { return [..._emMaps.values()].map((m) => ({ ...m, metadata: { ...m.metadata } })); }
+
+function _emCountPending(mid) { let n = 0; for (const e of _emEvos.values()) if (e.mapId === mid && (e.status === EVOMAP_EVOLUTION_LIFECYCLE_V2.QUEUED || e.status === EVOMAP_EVOLUTION_LIFECYCLE_V2.RUNNING)) n++; return n; }
+
+export function createEvoEvolutionV2({ id, mapId, strategy, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!mapId || typeof mapId !== "string") throw new Error("mapId is required");
+  if (_emEvos.has(id)) throw new Error(`evo evolution ${id} already exists`);
+  if (!_emMaps.has(mapId)) throw new Error(`evomap ${mapId} not found`);
+  const pending = _emCountPending(mapId);
+  if (pending >= _emMaxPendingPerMap) throw new Error(`max pending evo evolutions per map (${_emMaxPendingPerMap}) reached for ${mapId}`);
+  const now = Date.now();
+  const e = { id, mapId, strategy: strategy || "default", status: EVOMAP_EVOLUTION_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _emEvos.set(id, e);
+  return { ...e, metadata: { ...e.metadata } };
+}
+function _emCheckE(from, to) { const a = _emEvoTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid evo evolution transition ${from} → ${to}`); }
+export function startEvoEvolutionV2(id) { const e = _emEvos.get(id); if (!e) throw new Error(`evo evolution ${id} not found`); _emCheckE(e.status, EVOMAP_EVOLUTION_LIFECYCLE_V2.RUNNING); const now = Date.now(); e.status = EVOMAP_EVOLUTION_LIFECYCLE_V2.RUNNING; e.updatedAt = now; if (!e.startedAt) e.startedAt = now; return { ...e, metadata: { ...e.metadata } }; }
+export function completeEvoEvolutionV2(id) { const e = _emEvos.get(id); if (!e) throw new Error(`evo evolution ${id} not found`); _emCheckE(e.status, EVOMAP_EVOLUTION_LIFECYCLE_V2.COMPLETED); const now = Date.now(); e.status = EVOMAP_EVOLUTION_LIFECYCLE_V2.COMPLETED; e.updatedAt = now; if (!e.settledAt) e.settledAt = now; return { ...e, metadata: { ...e.metadata } }; }
+export function failEvoEvolutionV2(id, reason) { const e = _emEvos.get(id); if (!e) throw new Error(`evo evolution ${id} not found`); _emCheckE(e.status, EVOMAP_EVOLUTION_LIFECYCLE_V2.FAILED); const now = Date.now(); e.status = EVOMAP_EVOLUTION_LIFECYCLE_V2.FAILED; e.updatedAt = now; if (!e.settledAt) e.settledAt = now; if (reason) e.metadata.failReason = String(reason); return { ...e, metadata: { ...e.metadata } }; }
+export function cancelEvoEvolutionV2(id, reason) { const e = _emEvos.get(id); if (!e) throw new Error(`evo evolution ${id} not found`); _emCheckE(e.status, EVOMAP_EVOLUTION_LIFECYCLE_V2.CANCELLED); const now = Date.now(); e.status = EVOMAP_EVOLUTION_LIFECYCLE_V2.CANCELLED; e.updatedAt = now; if (!e.settledAt) e.settledAt = now; if (reason) e.metadata.cancelReason = String(reason); return { ...e, metadata: { ...e.metadata } }; }
+export function getEvoEvolutionV2(id) { const e = _emEvos.get(id); if (!e) return null; return { ...e, metadata: { ...e.metadata } }; }
+export function listEvoEvolutionsV2() { return [..._emEvos.values()].map((e) => ({ ...e, metadata: { ...e.metadata } })); }
+
+export function autoStaleIdleEvoMapsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const m of _emMaps.values()) if (m.status === EVOMAP_MAP_MATURITY_V2.ACTIVE && (t - m.lastTouchedAt) >= _emMapIdleMs) { m.status = EVOMAP_MAP_MATURITY_V2.STALE; m.updatedAt = t; flipped.push(m.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckEvoEvolutionsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const e of _emEvos.values()) if (e.status === EVOMAP_EVOLUTION_LIFECYCLE_V2.RUNNING && e.startedAt != null && (t - e.startedAt) >= _emEvoStuckMs) { e.status = EVOMAP_EVOLUTION_LIFECYCLE_V2.FAILED; e.updatedAt = t; if (!e.settledAt) e.settledAt = t; e.metadata.failReason = "auto-fail-stuck"; flipped.push(e.id); } return { flipped, count: flipped.length }; }
+
+export function getEvoMapManagerStatsV2() {
+  const mapsByStatus = {}; for (const s of Object.values(EVOMAP_MAP_MATURITY_V2)) mapsByStatus[s] = 0; for (const m of _emMaps.values()) mapsByStatus[m.status]++;
+  const evosByStatus = {}; for (const s of Object.values(EVOMAP_EVOLUTION_LIFECYCLE_V2)) evosByStatus[s] = 0; for (const e of _emEvos.values()) evosByStatus[e.status]++;
+  return { totalMapsV2: _emMaps.size, totalEvolutionsV2: _emEvos.size, maxActiveEvoMapsPerOwner: _emMaxActivePerOwner, maxPendingEvoEvolutionsPerMap: _emMaxPendingPerMap, evoMapIdleMs: _emMapIdleMs, evoEvolutionStuckMs: _emEvoStuckMs, mapsByStatus, evosByStatus };
+}

package/src/lib/execution-backend.js

@@ -237,3 +237,108 @@ export function createBackend(config = {}) {
       return new LocalBackend(config.options || {});
   }
 }
+
+
+// ===== V2 Surface: Execution Backend governance overlay (CLI v0.133.0) =====
+export const EXECBE_BACKEND_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", DEGRADED: "degraded", RETIRED: "retired",
+});
+export const EXECBE_JOB_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", RUNNING: "running", SUCCEEDED: "succeeded", FAILED: "failed", CANCELLED: "cancelled",
+});
+
+const _ebBackendTrans = new Map([
+  [EXECBE_BACKEND_MATURITY_V2.PENDING, new Set([EXECBE_BACKEND_MATURITY_V2.ACTIVE, EXECBE_BACKEND_MATURITY_V2.RETIRED])],
+  [EXECBE_BACKEND_MATURITY_V2.ACTIVE, new Set([EXECBE_BACKEND_MATURITY_V2.DEGRADED, EXECBE_BACKEND_MATURITY_V2.RETIRED])],
+  [EXECBE_BACKEND_MATURITY_V2.DEGRADED, new Set([EXECBE_BACKEND_MATURITY_V2.ACTIVE, EXECBE_BACKEND_MATURITY_V2.RETIRED])],
+  [EXECBE_BACKEND_MATURITY_V2.RETIRED, new Set()],
+]);
+const _ebBackendTerminal = new Set([EXECBE_BACKEND_MATURITY_V2.RETIRED]);
+const _ebJobTrans = new Map([
+  [EXECBE_JOB_LIFECYCLE_V2.QUEUED, new Set([EXECBE_JOB_LIFECYCLE_V2.RUNNING, EXECBE_JOB_LIFECYCLE_V2.CANCELLED])],
+  [EXECBE_JOB_LIFECYCLE_V2.RUNNING, new Set([EXECBE_JOB_LIFECYCLE_V2.SUCCEEDED, EXECBE_JOB_LIFECYCLE_V2.FAILED, EXECBE_JOB_LIFECYCLE_V2.CANCELLED])],
+  [EXECBE_JOB_LIFECYCLE_V2.SUCCEEDED, new Set()],
+  [EXECBE_JOB_LIFECYCLE_V2.FAILED, new Set()],
+  [EXECBE_JOB_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _ebBackends = new Map();
+const _ebJobs = new Map();
+let _ebMaxActivePerOwner = 6;
+let _ebMaxPendingPerBackend = 20;
+let _ebBackendIdleMs = 12 * 60 * 60 * 1000;
+let _ebJobStuckMs = 10 * 60 * 1000;
+
+function _ebPos(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 setMaxActiveBackendsPerOwnerV2(n) { _ebMaxActivePerOwner = _ebPos(n, "maxActiveBackendsPerOwner"); }
+export function getMaxActiveBackendsPerOwnerV2() { return _ebMaxActivePerOwner; }
+export function setMaxPendingJobsPerBackendV2(n) { _ebMaxPendingPerBackend = _ebPos(n, "maxPendingJobsPerBackend"); }
+export function getMaxPendingJobsPerBackendV2() { return _ebMaxPendingPerBackend; }
+export function setBackendIdleMsV2(n) { _ebBackendIdleMs = _ebPos(n, "backendIdleMs"); }
+export function getBackendIdleMsV2() { return _ebBackendIdleMs; }
+export function setExecJobStuckMsV2(n) { _ebJobStuckMs = _ebPos(n, "execJobStuckMs"); }
+export function getExecJobStuckMsV2() { return _ebJobStuckMs; }
+
+export function _resetStateExecutionBackendV2() {
+  _ebBackends.clear(); _ebJobs.clear();
+  _ebMaxActivePerOwner = 6; _ebMaxPendingPerBackend = 20;
+  _ebBackendIdleMs = 12 * 60 * 60 * 1000; _ebJobStuckMs = 10 * 60 * 1000;
+}
+
+export function registerBackendV2({ id, owner, kind, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_ebBackends.has(id)) throw new Error(`backend ${id} already registered`);
+  const now = Date.now();
+  const b = { id, owner, kind: kind || "local", status: EXECBE_BACKEND_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, retiredAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _ebBackends.set(id, b);
+  return { ...b, metadata: { ...b.metadata } };
+}
+function _ebCheckB(from, to) { const allowed = _ebBackendTrans.get(from); if (!allowed || !allowed.has(to)) throw new Error(`invalid backend transition ${from} → ${to}`); }
+function _ebCountActive(owner) { let n = 0; for (const b of _ebBackends.values()) if (b.owner === owner && b.status === EXECBE_BACKEND_MATURITY_V2.ACTIVE) n++; return n; }
+
+export function activateBackendV2(id) {
+  const b = _ebBackends.get(id); if (!b) throw new Error(`backend ${id} not found`);
+  _ebCheckB(b.status, EXECBE_BACKEND_MATURITY_V2.ACTIVE);
+  const recovery = b.status === EXECBE_BACKEND_MATURITY_V2.DEGRADED;
+  if (!recovery) { const a = _ebCountActive(b.owner); if (a >= _ebMaxActivePerOwner) throw new Error(`max active backends per owner (${_ebMaxActivePerOwner}) reached for ${b.owner}`); }
+  const now = Date.now(); b.status = EXECBE_BACKEND_MATURITY_V2.ACTIVE; b.updatedAt = now; b.lastTouchedAt = now; if (!b.activatedAt) b.activatedAt = now;
+  return { ...b, metadata: { ...b.metadata } };
+}
+export function degradeBackendV2(id) { const b = _ebBackends.get(id); if (!b) throw new Error(`backend ${id} not found`); _ebCheckB(b.status, EXECBE_BACKEND_MATURITY_V2.DEGRADED); b.status = EXECBE_BACKEND_MATURITY_V2.DEGRADED; b.updatedAt = Date.now(); return { ...b, metadata: { ...b.metadata } }; }
+export function retireBackendV2(id) { const b = _ebBackends.get(id); if (!b) throw new Error(`backend ${id} not found`); _ebCheckB(b.status, EXECBE_BACKEND_MATURITY_V2.RETIRED); const now = Date.now(); b.status = EXECBE_BACKEND_MATURITY_V2.RETIRED; b.updatedAt = now; if (!b.retiredAt) b.retiredAt = now; return { ...b, metadata: { ...b.metadata } }; }
+export function touchBackendV2(id) { const b = _ebBackends.get(id); if (!b) throw new Error(`backend ${id} not found`); if (_ebBackendTerminal.has(b.status)) throw new Error(`cannot touch terminal backend ${id}`); const now = Date.now(); b.lastTouchedAt = now; b.updatedAt = now; return { ...b, metadata: { ...b.metadata } }; }
+export function getBackendV2(id) { const b = _ebBackends.get(id); if (!b) return null; return { ...b, metadata: { ...b.metadata } }; }
+export function listBackendsV2() { return [..._ebBackends.values()].map((b) => ({ ...b, metadata: { ...b.metadata } })); }
+
+function _ebCountPending(bid) { let n = 0; for (const j of _ebJobs.values()) if (j.backendId === bid && (j.status === EXECBE_JOB_LIFECYCLE_V2.QUEUED || j.status === EXECBE_JOB_LIFECYCLE_V2.RUNNING)) n++; return n; }
+
+export function createExecJobV2({ id, backendId, command, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!backendId || typeof backendId !== "string") throw new Error("backendId is required");
+  if (_ebJobs.has(id)) throw new Error(`exec job ${id} already exists`);
+  if (!_ebBackends.has(backendId)) throw new Error(`backend ${backendId} not found`);
+  const pending = _ebCountPending(backendId);
+  if (pending >= _ebMaxPendingPerBackend) throw new Error(`max pending jobs per backend (${_ebMaxPendingPerBackend}) reached for ${backendId}`);
+  const now = Date.now();
+  const j = { id, backendId, command: command || "", status: EXECBE_JOB_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _ebJobs.set(id, j);
+  return { ...j, metadata: { ...j.metadata } };
+}
+function _ebCheckJ(from, to) { const allowed = _ebJobTrans.get(from); if (!allowed || !allowed.has(to)) throw new Error(`invalid exec job transition ${from} → ${to}`); }
+export function startExecJobV2(id) { const j = _ebJobs.get(id); if (!j) throw new Error(`exec job ${id} not found`); _ebCheckJ(j.status, EXECBE_JOB_LIFECYCLE_V2.RUNNING); const now = Date.now(); j.status = EXECBE_JOB_LIFECYCLE_V2.RUNNING; j.updatedAt = now; if (!j.startedAt) j.startedAt = now; return { ...j, metadata: { ...j.metadata } }; }
+export function succeedExecJobV2(id) { const j = _ebJobs.get(id); if (!j) throw new Error(`exec job ${id} not found`); _ebCheckJ(j.status, EXECBE_JOB_LIFECYCLE_V2.SUCCEEDED); const now = Date.now(); j.status = EXECBE_JOB_LIFECYCLE_V2.SUCCEEDED; j.updatedAt = now; if (!j.settledAt) j.settledAt = now; return { ...j, metadata: { ...j.metadata } }; }
+export function failExecJobV2(id, reason) { const j = _ebJobs.get(id); if (!j) throw new Error(`exec job ${id} not found`); _ebCheckJ(j.status, EXECBE_JOB_LIFECYCLE_V2.FAILED); const now = Date.now(); j.status = EXECBE_JOB_LIFECYCLE_V2.FAILED; j.updatedAt = now; if (!j.settledAt) j.settledAt = now; if (reason) j.metadata.failReason = String(reason); return { ...j, metadata: { ...j.metadata } }; }
+export function cancelExecJobV2(id, reason) { const j = _ebJobs.get(id); if (!j) throw new Error(`exec job ${id} not found`); _ebCheckJ(j.status, EXECBE_JOB_LIFECYCLE_V2.CANCELLED); const now = Date.now(); j.status = EXECBE_JOB_LIFECYCLE_V2.CANCELLED; j.updatedAt = now; if (!j.settledAt) j.settledAt = now; if (reason) j.metadata.cancelReason = String(reason); return { ...j, metadata: { ...j.metadata } }; }
+export function getExecJobV2(id) { const j = _ebJobs.get(id); if (!j) return null; return { ...j, metadata: { ...j.metadata } }; }
+export function listExecJobsV2() { return [..._ebJobs.values()].map((j) => ({ ...j, metadata: { ...j.metadata } })); }
+
+export function autoDegradeIdleBackendsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const b of _ebBackends.values()) if (b.status === EXECBE_BACKEND_MATURITY_V2.ACTIVE && (t - b.lastTouchedAt) >= _ebBackendIdleMs) { b.status = EXECBE_BACKEND_MATURITY_V2.DEGRADED; b.updatedAt = t; flipped.push(b.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckExecJobsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const j of _ebJobs.values()) if (j.status === EXECBE_JOB_LIFECYCLE_V2.RUNNING && j.startedAt != null && (t - j.startedAt) >= _ebJobStuckMs) { j.status = EXECBE_JOB_LIFECYCLE_V2.FAILED; j.updatedAt = t; if (!j.settledAt) j.settledAt = t; j.metadata.failReason = "auto-fail-stuck"; flipped.push(j.id); } return { flipped, count: flipped.length }; }
+
+export function getExecutionBackendStatsV2() {
+  const backendsByStatus = {}; for (const s of Object.values(EXECBE_BACKEND_MATURITY_V2)) backendsByStatus[s] = 0; for (const b of _ebBackends.values()) backendsByStatus[b.status]++;
+  const jobsByStatus = {}; for (const s of Object.values(EXECBE_JOB_LIFECYCLE_V2)) jobsByStatus[s] = 0; for (const j of _ebJobs.values()) jobsByStatus[j.status]++;
+  return { totalBackendsV2: _ebBackends.size, totalJobsV2: _ebJobs.size, maxActiveBackendsPerOwner: _ebMaxActivePerOwner, maxPendingJobsPerBackend: _ebMaxPendingPerBackend, backendIdleMs: _ebBackendIdleMs, execJobStuckMs: _ebJobStuckMs, backendsByStatus, jobsByStatus };
+}

package/src/lib/feature-flags.js

@@ -5,3 +5,88 @@ export {
   setFeature,
   getFlagInfo,
 } from "../harness/feature-flags.js";
+
+
+// =====================================================================
+// Feature Flags V2 governance overlay (in-memory, atop legacy flags)
+// =====================================================================
+export const FFLAG_PROFILE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", PAUSED: "paused", ARCHIVED: "archived",
+});
+export const FFLAG_EVAL_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", EVALUATING: "evaluating", EVALUATED: "evaluated", FAILED: "failed", CANCELLED: "cancelled",
+});
+const _fflagPTrans = new Map([
+  [FFLAG_PROFILE_MATURITY_V2.PENDING, new Set([FFLAG_PROFILE_MATURITY_V2.ACTIVE, FFLAG_PROFILE_MATURITY_V2.ARCHIVED])],
+  [FFLAG_PROFILE_MATURITY_V2.ACTIVE, new Set([FFLAG_PROFILE_MATURITY_V2.PAUSED, FFLAG_PROFILE_MATURITY_V2.ARCHIVED])],
+  [FFLAG_PROFILE_MATURITY_V2.PAUSED, new Set([FFLAG_PROFILE_MATURITY_V2.ACTIVE, FFLAG_PROFILE_MATURITY_V2.ARCHIVED])],
+  [FFLAG_PROFILE_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _fflagPTerminal = new Set([FFLAG_PROFILE_MATURITY_V2.ARCHIVED]);
+const _fflagETrans = new Map([
+  [FFLAG_EVAL_LIFECYCLE_V2.QUEUED, new Set([FFLAG_EVAL_LIFECYCLE_V2.EVALUATING, FFLAG_EVAL_LIFECYCLE_V2.CANCELLED])],
+  [FFLAG_EVAL_LIFECYCLE_V2.EVALUATING, new Set([FFLAG_EVAL_LIFECYCLE_V2.EVALUATED, FFLAG_EVAL_LIFECYCLE_V2.FAILED, FFLAG_EVAL_LIFECYCLE_V2.CANCELLED])],
+  [FFLAG_EVAL_LIFECYCLE_V2.EVALUATED, new Set()],
+  [FFLAG_EVAL_LIFECYCLE_V2.FAILED, new Set()],
+  [FFLAG_EVAL_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+const _fflagPsV2 = new Map();
+const _fflagEsV2 = new Map();
+let _fflagMaxActive = 15, _fflagMaxPending = 30, _fflagIdleMs = 30 * 24 * 60 * 60 * 1000, _fflagStuckMs = 30 * 1000;
+function _fflagPos(n, label) { const v = Math.floor(Number(n)); if (!Number.isFinite(v) || v <= 0) throw new Error(`${label} must be positive integer`); return v; }
+function _fflagCheckP(from, to) { const a = _fflagPTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid fflag profile transition ${from} → ${to}`); }
+function _fflagCheckE(from, to) { const a = _fflagETrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid fflag eval transition ${from} → ${to}`); }
+function _fflagCountActive(owner) { let c = 0; for (const p of _fflagPsV2.values()) if (p.owner === owner && p.status === FFLAG_PROFILE_MATURITY_V2.ACTIVE) c++; return c; }
+function _fflagCountPending(profileId) { let c = 0; for (const e of _fflagEsV2.values()) if (e.profileId === profileId && (e.status === FFLAG_EVAL_LIFECYCLE_V2.QUEUED || e.status === FFLAG_EVAL_LIFECYCLE_V2.EVALUATING)) c++; return c; }
+export function setMaxActiveFflagProfilesPerOwnerV2(n) { _fflagMaxActive = _fflagPos(n, "maxActiveFflagProfilesPerOwner"); }
+export function getMaxActiveFflagProfilesPerOwnerV2() { return _fflagMaxActive; }
+export function setMaxPendingFflagEvalsPerProfileV2(n) { _fflagMaxPending = _fflagPos(n, "maxPendingFflagEvalsPerProfile"); }
+export function getMaxPendingFflagEvalsPerProfileV2() { return _fflagMaxPending; }
+export function setFflagProfileIdleMsV2(n) { _fflagIdleMs = _fflagPos(n, "fflagProfileIdleMs"); }
+export function getFflagProfileIdleMsV2() { return _fflagIdleMs; }
+export function setFflagEvalStuckMsV2(n) { _fflagStuckMs = _fflagPos(n, "fflagEvalStuckMs"); }
+export function getFflagEvalStuckMsV2() { return _fflagStuckMs; }
+export function _resetStateFeatureFlagsV2() { _fflagPsV2.clear(); _fflagEsV2.clear(); _fflagMaxActive = 15; _fflagMaxPending = 30; _fflagIdleMs = 30 * 24 * 60 * 60 * 1000; _fflagStuckMs = 30 * 1000; }
+export function registerFflagProfileV2({ id, owner, scope, metadata } = {}) {
+  if (!id || !owner) throw new Error("id and owner required");
+  if (_fflagPsV2.has(id)) throw new Error(`fflag profile ${id} already exists`);
+  const now = Date.now();
+  const p = { id, owner, scope: scope || "*", status: FFLAG_PROFILE_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, lastTouchedAt: now, activatedAt: null, archivedAt: null, metadata: { ...(metadata || {}) } };
+  _fflagPsV2.set(id, p); return { ...p, metadata: { ...p.metadata } };
+}
+export function activateFflagProfileV2(id) {
+  const p = _fflagPsV2.get(id); if (!p) throw new Error(`fflag profile ${id} not found`);
+  const isInitial = p.status === FFLAG_PROFILE_MATURITY_V2.PENDING;
+  _fflagCheckP(p.status, FFLAG_PROFILE_MATURITY_V2.ACTIVE);
+  if (isInitial && _fflagCountActive(p.owner) >= _fflagMaxActive) throw new Error(`max active fflag profiles for owner ${p.owner} reached`);
+  const now = Date.now(); p.status = FFLAG_PROFILE_MATURITY_V2.ACTIVE; p.updatedAt = now; p.lastTouchedAt = now;
+  if (!p.activatedAt) p.activatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function pauseFflagProfileV2(id) { const p = _fflagPsV2.get(id); if (!p) throw new Error(`fflag profile ${id} not found`); _fflagCheckP(p.status, FFLAG_PROFILE_MATURITY_V2.PAUSED); p.status = FFLAG_PROFILE_MATURITY_V2.PAUSED; p.updatedAt = Date.now(); return { ...p, metadata: { ...p.metadata } }; }
+export function archiveFflagProfileV2(id) { const p = _fflagPsV2.get(id); if (!p) throw new Error(`fflag profile ${id} not found`); _fflagCheckP(p.status, FFLAG_PROFILE_MATURITY_V2.ARCHIVED); const now = Date.now(); p.status = FFLAG_PROFILE_MATURITY_V2.ARCHIVED; p.updatedAt = now; if (!p.archivedAt) p.archivedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function touchFflagProfileV2(id) { const p = _fflagPsV2.get(id); if (!p) throw new Error(`fflag profile ${id} not found`); if (_fflagPTerminal.has(p.status)) throw new Error(`cannot touch terminal fflag profile ${id}`); const now = Date.now(); p.lastTouchedAt = now; p.updatedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function getFflagProfileV2(id) { const p = _fflagPsV2.get(id); if (!p) return null; return { ...p, metadata: { ...p.metadata } }; }
+export function listFflagProfilesV2() { return [..._fflagPsV2.values()].map((p) => ({ ...p, metadata: { ...p.metadata } })); }
+export function createFflagEvalV2({ id, profileId, key, metadata } = {}) {
+  if (!id || !profileId) throw new Error("id and profileId required");
+  if (_fflagEsV2.has(id)) throw new Error(`fflag eval ${id} already exists`);
+  if (!_fflagPsV2.has(profileId)) throw new Error(`fflag profile ${profileId} not found`);
+  if (_fflagCountPending(profileId) >= _fflagMaxPending) throw new Error(`max pending fflag evals for profile ${profileId} reached`);
+  const now = Date.now();
+  const e = { id, profileId, key: key || "", status: FFLAG_EVAL_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _fflagEsV2.set(id, e); return { ...e, metadata: { ...e.metadata } };
+}
+export function evaluatingFflagEvalV2(id) { const e = _fflagEsV2.get(id); if (!e) throw new Error(`fflag eval ${id} not found`); _fflagCheckE(e.status, FFLAG_EVAL_LIFECYCLE_V2.EVALUATING); const now = Date.now(); e.status = FFLAG_EVAL_LIFECYCLE_V2.EVALUATING; e.updatedAt = now; if (!e.startedAt) e.startedAt = now; return { ...e, metadata: { ...e.metadata } }; }
+export function evaluateFflagEvalV2(id) { const e = _fflagEsV2.get(id); if (!e) throw new Error(`fflag eval ${id} not found`); _fflagCheckE(e.status, FFLAG_EVAL_LIFECYCLE_V2.EVALUATED); const now = Date.now(); e.status = FFLAG_EVAL_LIFECYCLE_V2.EVALUATED; e.updatedAt = now; if (!e.settledAt) e.settledAt = now; return { ...e, metadata: { ...e.metadata } }; }
+export function failFflagEvalV2(id, reason) { const e = _fflagEsV2.get(id); if (!e) throw new Error(`fflag eval ${id} not found`); _fflagCheckE(e.status, FFLAG_EVAL_LIFECYCLE_V2.FAILED); const now = Date.now(); e.status = FFLAG_EVAL_LIFECYCLE_V2.FAILED; e.updatedAt = now; if (!e.settledAt) e.settledAt = now; if (reason) e.metadata.failReason = String(reason); return { ...e, metadata: { ...e.metadata } }; }
+export function cancelFflagEvalV2(id, reason) { const e = _fflagEsV2.get(id); if (!e) throw new Error(`fflag eval ${id} not found`); _fflagCheckE(e.status, FFLAG_EVAL_LIFECYCLE_V2.CANCELLED); const now = Date.now(); e.status = FFLAG_EVAL_LIFECYCLE_V2.CANCELLED; e.updatedAt = now; if (!e.settledAt) e.settledAt = now; if (reason) e.metadata.cancelReason = String(reason); return { ...e, metadata: { ...e.metadata } }; }
+export function getFflagEvalV2(id) { const e = _fflagEsV2.get(id); if (!e) return null; return { ...e, metadata: { ...e.metadata } }; }
+export function listFflagEvalsV2() { return [..._fflagEsV2.values()].map((e) => ({ ...e, metadata: { ...e.metadata } })); }
+export function autoPauseIdleFflagProfilesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const p of _fflagPsV2.values()) if (p.status === FFLAG_PROFILE_MATURITY_V2.ACTIVE && (t - p.lastTouchedAt) >= _fflagIdleMs) { p.status = FFLAG_PROFILE_MATURITY_V2.PAUSED; p.updatedAt = t; flipped.push(p.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckFflagEvalsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const e of _fflagEsV2.values()) if (e.status === FFLAG_EVAL_LIFECYCLE_V2.EVALUATING && e.startedAt != null && (t - e.startedAt) >= _fflagStuckMs) { e.status = FFLAG_EVAL_LIFECYCLE_V2.FAILED; e.updatedAt = t; if (!e.settledAt) e.settledAt = t; e.metadata.failReason = "auto-fail-stuck"; flipped.push(e.id); } return { flipped, count: flipped.length }; }
+export function getFeatureFlagsGovStatsV2() {
+  const profilesByStatus = {}; for (const v of Object.values(FFLAG_PROFILE_MATURITY_V2)) profilesByStatus[v] = 0; for (const p of _fflagPsV2.values()) profilesByStatus[p.status]++;
+  const evalsByStatus = {}; for (const v of Object.values(FFLAG_EVAL_LIFECYCLE_V2)) evalsByStatus[v] = 0; for (const e of _fflagEsV2.values()) evalsByStatus[e.status]++;
+  return { totalFflagProfilesV2: _fflagPsV2.size, totalFflagEvalsV2: _fflagEsV2.size, maxActiveFflagProfilesPerOwner: _fflagMaxActive, maxPendingFflagEvalsPerProfile: _fflagMaxPending, fflagProfileIdleMs: _fflagIdleMs, fflagEvalStuckMs: _fflagStuckMs, profilesByStatus, evalsByStatus };
+}

package/src/lib/git-integration.js

@@ -218,3 +218,108 @@ echo "ChainlessChain: pre-commit hook running"
 
   return { installed: true, hook: "pre-commit", path: hookPath };
 }
+
+
+// ===== V2 Surface: Git Integration governance overlay (CLI v0.139.0) =====
+export const GIT_REPO_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", ARCHIVED: "archived", DECOMMISSIONED: "decommissioned",
+});
+export const GIT_COMMIT_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", COMMITTING: "committing", COMMITTED: "committed", FAILED: "failed", CANCELLED: "cancelled",
+});
+
+const _grTrans = new Map([
+  [GIT_REPO_MATURITY_V2.PENDING, new Set([GIT_REPO_MATURITY_V2.ACTIVE, GIT_REPO_MATURITY_V2.DECOMMISSIONED])],
+  [GIT_REPO_MATURITY_V2.ACTIVE, new Set([GIT_REPO_MATURITY_V2.ARCHIVED, GIT_REPO_MATURITY_V2.DECOMMISSIONED])],
+  [GIT_REPO_MATURITY_V2.ARCHIVED, new Set([GIT_REPO_MATURITY_V2.ACTIVE, GIT_REPO_MATURITY_V2.DECOMMISSIONED])],
+  [GIT_REPO_MATURITY_V2.DECOMMISSIONED, new Set()],
+]);
+const _grTerminal = new Set([GIT_REPO_MATURITY_V2.DECOMMISSIONED]);
+const _gcTrans = new Map([
+  [GIT_COMMIT_LIFECYCLE_V2.QUEUED, new Set([GIT_COMMIT_LIFECYCLE_V2.COMMITTING, GIT_COMMIT_LIFECYCLE_V2.CANCELLED])],
+  [GIT_COMMIT_LIFECYCLE_V2.COMMITTING, new Set([GIT_COMMIT_LIFECYCLE_V2.COMMITTED, GIT_COMMIT_LIFECYCLE_V2.FAILED, GIT_COMMIT_LIFECYCLE_V2.CANCELLED])],
+  [GIT_COMMIT_LIFECYCLE_V2.COMMITTED, new Set()],
+  [GIT_COMMIT_LIFECYCLE_V2.FAILED, new Set()],
+  [GIT_COMMIT_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _grsV2 = new Map();
+const _gcsV2 = new Map();
+let _grMaxActivePerOwner = 10;
+let _grMaxPendingCommitsPerRepo = 20;
+let _grIdleMs = 30 * 24 * 60 * 60 * 1000;
+let _gcStuckMs = 5 * 60 * 1000;
+
+function _grPos(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 setMaxActiveGitReposPerOwnerV2(n) { _grMaxActivePerOwner = _grPos(n, "maxActiveGitReposPerOwner"); }
+export function getMaxActiveGitReposPerOwnerV2() { return _grMaxActivePerOwner; }
+export function setMaxPendingGitCommitsPerRepoV2(n) { _grMaxPendingCommitsPerRepo = _grPos(n, "maxPendingGitCommitsPerRepo"); }
+export function getMaxPendingGitCommitsPerRepoV2() { return _grMaxPendingCommitsPerRepo; }
+export function setGitRepoIdleMsV2(n) { _grIdleMs = _grPos(n, "gitRepoIdleMs"); }
+export function getGitRepoIdleMsV2() { return _grIdleMs; }
+export function setGitCommitStuckMsV2(n) { _gcStuckMs = _grPos(n, "gitCommitStuckMs"); }
+export function getGitCommitStuckMsV2() { return _gcStuckMs; }
+
+export function _resetStateGitIntegrationV2() {
+  _grsV2.clear(); _gcsV2.clear();
+  _grMaxActivePerOwner = 10; _grMaxPendingCommitsPerRepo = 20;
+  _grIdleMs = 30 * 24 * 60 * 60 * 1000; _gcStuckMs = 5 * 60 * 1000;
+}
+
+export function registerGitRepoV2({ id, owner, branch, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_grsV2.has(id)) throw new Error(`git repo ${id} already registered`);
+  const now = Date.now();
+  const r = { id, owner, branch: branch || "main", status: GIT_REPO_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, decommissionedAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _grsV2.set(id, r);
+  return { ...r, metadata: { ...r.metadata } };
+}
+function _grCheckR(from, to) { const a = _grTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid git repo transition ${from} → ${to}`); }
+function _grCountActive(owner) { let n = 0; for (const r of _grsV2.values()) if (r.owner === owner && r.status === GIT_REPO_MATURITY_V2.ACTIVE) n++; return n; }
+
+export function activateGitRepoV2(id) {
+  const r = _grsV2.get(id); if (!r) throw new Error(`git repo ${id} not found`);
+  _grCheckR(r.status, GIT_REPO_MATURITY_V2.ACTIVE);
+  const recovery = r.status === GIT_REPO_MATURITY_V2.ARCHIVED;
+  if (!recovery) { const c = _grCountActive(r.owner); if (c >= _grMaxActivePerOwner) throw new Error(`max active git repos per owner (${_grMaxActivePerOwner}) reached for ${r.owner}`); }
+  const now = Date.now(); r.status = GIT_REPO_MATURITY_V2.ACTIVE; r.updatedAt = now; r.lastTouchedAt = now; if (!r.activatedAt) r.activatedAt = now;
+  return { ...r, metadata: { ...r.metadata } };
+}
+export function archiveGitRepoV2(id) { const r = _grsV2.get(id); if (!r) throw new Error(`git repo ${id} not found`); _grCheckR(r.status, GIT_REPO_MATURITY_V2.ARCHIVED); r.status = GIT_REPO_MATURITY_V2.ARCHIVED; r.updatedAt = Date.now(); return { ...r, metadata: { ...r.metadata } }; }
+export function decommissionGitRepoV2(id) { const r = _grsV2.get(id); if (!r) throw new Error(`git repo ${id} not found`); _grCheckR(r.status, GIT_REPO_MATURITY_V2.DECOMMISSIONED); const now = Date.now(); r.status = GIT_REPO_MATURITY_V2.DECOMMISSIONED; r.updatedAt = now; if (!r.decommissionedAt) r.decommissionedAt = now; return { ...r, metadata: { ...r.metadata } }; }
+export function touchGitRepoV2(id) { const r = _grsV2.get(id); if (!r) throw new Error(`git repo ${id} not found`); if (_grTerminal.has(r.status)) throw new Error(`cannot touch terminal git repo ${id}`); const now = Date.now(); r.lastTouchedAt = now; r.updatedAt = now; return { ...r, metadata: { ...r.metadata } }; }
+export function getGitRepoV2(id) { const r = _grsV2.get(id); if (!r) return null; return { ...r, metadata: { ...r.metadata } }; }
+export function listGitReposV2() { return [..._grsV2.values()].map((r) => ({ ...r, metadata: { ...r.metadata } })); }
+
+function _gcCountPending(repoId) { let n = 0; for (const c of _gcsV2.values()) if (c.repoId === repoId && (c.status === GIT_COMMIT_LIFECYCLE_V2.QUEUED || c.status === GIT_COMMIT_LIFECYCLE_V2.COMMITTING)) n++; return n; }
+
+export function createGitCommitV2({ id, repoId, message, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!repoId || typeof repoId !== "string") throw new Error("repoId is required");
+  if (_gcsV2.has(id)) throw new Error(`git commit ${id} already exists`);
+  if (!_grsV2.has(repoId)) throw new Error(`git repo ${repoId} not found`);
+  const pending = _gcCountPending(repoId);
+  if (pending >= _grMaxPendingCommitsPerRepo) throw new Error(`max pending git commits per repo (${_grMaxPendingCommitsPerRepo}) reached for ${repoId}`);
+  const now = Date.now();
+  const c = { id, repoId, message: message || "", status: GIT_COMMIT_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _gcsV2.set(id, c);
+  return { ...c, metadata: { ...c.metadata } };
+}
+function _gcCheckC(from, to) { const a = _gcTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid git commit transition ${from} → ${to}`); }
+export function startGitCommitV2(id) { const c = _gcsV2.get(id); if (!c) throw new Error(`git commit ${id} not found`); _gcCheckC(c.status, GIT_COMMIT_LIFECYCLE_V2.COMMITTING); const now = Date.now(); c.status = GIT_COMMIT_LIFECYCLE_V2.COMMITTING; c.updatedAt = now; if (!c.startedAt) c.startedAt = now; return { ...c, metadata: { ...c.metadata } }; }
+export function commitGitCommitV2(id) { const c = _gcsV2.get(id); if (!c) throw new Error(`git commit ${id} not found`); _gcCheckC(c.status, GIT_COMMIT_LIFECYCLE_V2.COMMITTED); const now = Date.now(); c.status = GIT_COMMIT_LIFECYCLE_V2.COMMITTED; c.updatedAt = now; if (!c.settledAt) c.settledAt = now; return { ...c, metadata: { ...c.metadata } }; }
+export function failGitCommitV2(id, reason) { const c = _gcsV2.get(id); if (!c) throw new Error(`git commit ${id} not found`); _gcCheckC(c.status, GIT_COMMIT_LIFECYCLE_V2.FAILED); const now = Date.now(); c.status = GIT_COMMIT_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 cancelGitCommitV2(id, reason) { const c = _gcsV2.get(id); if (!c) throw new Error(`git commit ${id} not found`); _gcCheckC(c.status, GIT_COMMIT_LIFECYCLE_V2.CANCELLED); const now = Date.now(); c.status = GIT_COMMIT_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 getGitCommitV2(id) { const c = _gcsV2.get(id); if (!c) return null; return { ...c, metadata: { ...c.metadata } }; }
+export function listGitCommitsV2() { return [..._gcsV2.values()].map((c) => ({ ...c, metadata: { ...c.metadata } })); }
+
+export function autoArchiveIdleGitReposV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const r of _grsV2.values()) if (r.status === GIT_REPO_MATURITY_V2.ACTIVE && (t - r.lastTouchedAt) >= _grIdleMs) { r.status = GIT_REPO_MATURITY_V2.ARCHIVED; r.updatedAt = t; flipped.push(r.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckGitCommitsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const c of _gcsV2.values()) if (c.status === GIT_COMMIT_LIFECYCLE_V2.COMMITTING && c.startedAt != null && (t - c.startedAt) >= _gcStuckMs) { c.status = GIT_COMMIT_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 getGitIntegrationGovStatsV2() {
+  const reposByStatus = {}; for (const s of Object.values(GIT_REPO_MATURITY_V2)) reposByStatus[s] = 0; for (const r of _grsV2.values()) reposByStatus[r.status]++;
+  const commitsByStatus = {}; for (const s of Object.values(GIT_COMMIT_LIFECYCLE_V2)) commitsByStatus[s] = 0; for (const c of _gcsV2.values()) commitsByStatus[c.status]++;
+  return { totalGitReposV2: _grsV2.size, totalGitCommitsV2: _gcsV2.size, maxActiveGitReposPerOwner: _grMaxActivePerOwner, maxPendingGitCommitsPerRepo: _grMaxPendingCommitsPerRepo, gitRepoIdleMs: _grIdleMs, gitCommitStuckMs: _gcStuckMs, reposByStatus, commitsByStatus };
+}

package/src/lib/hierarchical-memory.js

@@ -1068,3 +1068,108 @@ export function _resetV2State() {
     _consolidationTimer = null;
   }
 }
+
+
+// ===== V2 Surface: Hierarchical Memory governance overlay (CLI v0.137.0) =====
+export const HMEM_TIER_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", DORMANT: "dormant", RETIRED: "retired",
+});
+export const HMEM_PROMOTION_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", PROMOTING: "promoting", PROMOTED: "promoted", FAILED: "failed", CANCELLED: "cancelled",
+});
+
+const _hmemTierTrans = new Map([
+  [HMEM_TIER_MATURITY_V2.PENDING, new Set([HMEM_TIER_MATURITY_V2.ACTIVE, HMEM_TIER_MATURITY_V2.RETIRED])],
+  [HMEM_TIER_MATURITY_V2.ACTIVE, new Set([HMEM_TIER_MATURITY_V2.DORMANT, HMEM_TIER_MATURITY_V2.RETIRED])],
+  [HMEM_TIER_MATURITY_V2.DORMANT, new Set([HMEM_TIER_MATURITY_V2.ACTIVE, HMEM_TIER_MATURITY_V2.RETIRED])],
+  [HMEM_TIER_MATURITY_V2.RETIRED, new Set()],
+]);
+const _hmemTierTerminal = new Set([HMEM_TIER_MATURITY_V2.RETIRED]);
+const _hmemPromoTrans = new Map([
+  [HMEM_PROMOTION_LIFECYCLE_V2.QUEUED, new Set([HMEM_PROMOTION_LIFECYCLE_V2.PROMOTING, HMEM_PROMOTION_LIFECYCLE_V2.CANCELLED])],
+  [HMEM_PROMOTION_LIFECYCLE_V2.PROMOTING, new Set([HMEM_PROMOTION_LIFECYCLE_V2.PROMOTED, HMEM_PROMOTION_LIFECYCLE_V2.FAILED, HMEM_PROMOTION_LIFECYCLE_V2.CANCELLED])],
+  [HMEM_PROMOTION_LIFECYCLE_V2.PROMOTED, new Set()],
+  [HMEM_PROMOTION_LIFECYCLE_V2.FAILED, new Set()],
+  [HMEM_PROMOTION_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _hmemTiers = new Map();
+const _hmemPromos = new Map();
+let _hmemMaxActivePerOwner = 12;
+let _hmemMaxPendingPerTier = 30;
+let _hmemTierIdleMs = 30 * 24 * 60 * 60 * 1000;
+let _hmemPromoStuckMs = 5 * 60 * 1000;
+
+function _hmemPos(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 setMaxActiveHmemTiersPerOwnerV2(n) { _hmemMaxActivePerOwner = _hmemPos(n, "maxActiveHmemTiersPerOwner"); }
+export function getMaxActiveHmemTiersPerOwnerV2() { return _hmemMaxActivePerOwner; }
+export function setMaxPendingHmemPromotionsPerTierV2(n) { _hmemMaxPendingPerTier = _hmemPos(n, "maxPendingHmemPromotionsPerTier"); }
+export function getMaxPendingHmemPromotionsPerTierV2() { return _hmemMaxPendingPerTier; }
+export function setHmemTierIdleMsV2(n) { _hmemTierIdleMs = _hmemPos(n, "hmemTierIdleMs"); }
+export function getHmemTierIdleMsV2() { return _hmemTierIdleMs; }
+export function setHmemPromotionStuckMsV2(n) { _hmemPromoStuckMs = _hmemPos(n, "hmemPromotionStuckMs"); }
+export function getHmemPromotionStuckMsV2() { return _hmemPromoStuckMs; }
+
+export function _resetStateHierarchicalMemoryV2() {
+  _hmemTiers.clear(); _hmemPromos.clear();
+  _hmemMaxActivePerOwner = 12; _hmemMaxPendingPerTier = 30;
+  _hmemTierIdleMs = 30 * 24 * 60 * 60 * 1000; _hmemPromoStuckMs = 5 * 60 * 1000;
+}
+
+export function registerHmemTierV2({ id, owner, level, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_hmemTiers.has(id)) throw new Error(`hmem tier ${id} already registered`);
+  const now = Date.now();
+  const t = { id, owner, level: level || "short-term", status: HMEM_TIER_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, retiredAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _hmemTiers.set(id, t);
+  return { ...t, metadata: { ...t.metadata } };
+}
+function _hmemCheckT(from, to) { const a = _hmemTierTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid hmem tier transition ${from} → ${to}`); }
+function _hmemCountActive(owner) { let n = 0; for (const t of _hmemTiers.values()) if (t.owner === owner && t.status === HMEM_TIER_MATURITY_V2.ACTIVE) n++; return n; }
+
+export function activateHmemTierV2(id) {
+  const t = _hmemTiers.get(id); if (!t) throw new Error(`hmem tier ${id} not found`);
+  _hmemCheckT(t.status, HMEM_TIER_MATURITY_V2.ACTIVE);
+  const recovery = t.status === HMEM_TIER_MATURITY_V2.DORMANT;
+  if (!recovery) { const c = _hmemCountActive(t.owner); if (c >= _hmemMaxActivePerOwner) throw new Error(`max active hmem tiers per owner (${_hmemMaxActivePerOwner}) reached for ${t.owner}`); }
+  const now = Date.now(); t.status = HMEM_TIER_MATURITY_V2.ACTIVE; t.updatedAt = now; t.lastTouchedAt = now; if (!t.activatedAt) t.activatedAt = now;
+  return { ...t, metadata: { ...t.metadata } };
+}
+export function dormantHmemTierV2(id) { const t = _hmemTiers.get(id); if (!t) throw new Error(`hmem tier ${id} not found`); _hmemCheckT(t.status, HMEM_TIER_MATURITY_V2.DORMANT); t.status = HMEM_TIER_MATURITY_V2.DORMANT; t.updatedAt = Date.now(); return { ...t, metadata: { ...t.metadata } }; }
+export function retireHmemTierV2(id) { const t = _hmemTiers.get(id); if (!t) throw new Error(`hmem tier ${id} not found`); _hmemCheckT(t.status, HMEM_TIER_MATURITY_V2.RETIRED); const now = Date.now(); t.status = HMEM_TIER_MATURITY_V2.RETIRED; t.updatedAt = now; if (!t.retiredAt) t.retiredAt = now; return { ...t, metadata: { ...t.metadata } }; }
+export function touchHmemTierV2(id) { const t = _hmemTiers.get(id); if (!t) throw new Error(`hmem tier ${id} not found`); if (_hmemTierTerminal.has(t.status)) throw new Error(`cannot touch terminal hmem tier ${id}`); const now = Date.now(); t.lastTouchedAt = now; t.updatedAt = now; return { ...t, metadata: { ...t.metadata } }; }
+export function getHmemTierV2(id) { const t = _hmemTiers.get(id); if (!t) return null; return { ...t, metadata: { ...t.metadata } }; }
+export function listHmemTiersV2() { return [..._hmemTiers.values()].map((t) => ({ ...t, metadata: { ...t.metadata } })); }
+
+function _hmemCountPending(tid) { let n = 0; for (const p of _hmemPromos.values()) if (p.tierId === tid && (p.status === HMEM_PROMOTION_LIFECYCLE_V2.QUEUED || p.status === HMEM_PROMOTION_LIFECYCLE_V2.PROMOTING)) n++; return n; }
+
+export function createHmemPromotionV2({ id, tierId, itemKey, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!tierId || typeof tierId !== "string") throw new Error("tierId is required");
+  if (_hmemPromos.has(id)) throw new Error(`hmem promotion ${id} already exists`);
+  if (!_hmemTiers.has(tierId)) throw new Error(`hmem tier ${tierId} not found`);
+  const pending = _hmemCountPending(tierId);
+  if (pending >= _hmemMaxPendingPerTier) throw new Error(`max pending hmem promotions per tier (${_hmemMaxPendingPerTier}) reached for ${tierId}`);
+  const now = Date.now();
+  const p = { id, tierId, itemKey: itemKey || "", status: HMEM_PROMOTION_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _hmemPromos.set(id, p);
+  return { ...p, metadata: { ...p.metadata } };
+}
+function _hmemCheckP(from, to) { const a = _hmemPromoTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid hmem promotion transition ${from} → ${to}`); }
+export function startHmemPromotionV2(id) { const p = _hmemPromos.get(id); if (!p) throw new Error(`hmem promotion ${id} not found`); _hmemCheckP(p.status, HMEM_PROMOTION_LIFECYCLE_V2.PROMOTING); const now = Date.now(); p.status = HMEM_PROMOTION_LIFECYCLE_V2.PROMOTING; p.updatedAt = now; if (!p.startedAt) p.startedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function completeHmemPromotionV2(id) { const p = _hmemPromos.get(id); if (!p) throw new Error(`hmem promotion ${id} not found`); _hmemCheckP(p.status, HMEM_PROMOTION_LIFECYCLE_V2.PROMOTED); const now = Date.now(); p.status = HMEM_PROMOTION_LIFECYCLE_V2.PROMOTED; p.updatedAt = now; if (!p.settledAt) p.settledAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function failHmemPromotionV2(id, reason) { const p = _hmemPromos.get(id); if (!p) throw new Error(`hmem promotion ${id} not found`); _hmemCheckP(p.status, HMEM_PROMOTION_LIFECYCLE_V2.FAILED); const now = Date.now(); p.status = HMEM_PROMOTION_LIFECYCLE_V2.FAILED; p.updatedAt = now; if (!p.settledAt) p.settledAt = now; if (reason) p.metadata.failReason = String(reason); return { ...p, metadata: { ...p.metadata } }; }
+export function cancelHmemPromotionV2(id, reason) { const p = _hmemPromos.get(id); if (!p) throw new Error(`hmem promotion ${id} not found`); _hmemCheckP(p.status, HMEM_PROMOTION_LIFECYCLE_V2.CANCELLED); const now = Date.now(); p.status = HMEM_PROMOTION_LIFECYCLE_V2.CANCELLED; p.updatedAt = now; if (!p.settledAt) p.settledAt = now; if (reason) p.metadata.cancelReason = String(reason); return { ...p, metadata: { ...p.metadata } }; }
+export function getHmemPromotionV2(id) { const p = _hmemPromos.get(id); if (!p) return null; return { ...p, metadata: { ...p.metadata } }; }
+export function listHmemPromotionsV2() { return [..._hmemPromos.values()].map((p) => ({ ...p, metadata: { ...p.metadata } })); }
+
+export function autoDormantIdleHmemTiersV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const tier of _hmemTiers.values()) if (tier.status === HMEM_TIER_MATURITY_V2.ACTIVE && (t - tier.lastTouchedAt) >= _hmemTierIdleMs) { tier.status = HMEM_TIER_MATURITY_V2.DORMANT; tier.updatedAt = t; flipped.push(tier.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckHmemPromotionsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const p of _hmemPromos.values()) if (p.status === HMEM_PROMOTION_LIFECYCLE_V2.PROMOTING && p.startedAt != null && (t - p.startedAt) >= _hmemPromoStuckMs) { p.status = HMEM_PROMOTION_LIFECYCLE_V2.FAILED; p.updatedAt = t; if (!p.settledAt) p.settledAt = t; p.metadata.failReason = "auto-fail-stuck"; flipped.push(p.id); } return { flipped, count: flipped.length }; }
+
+export function getHierarchicalMemoryGovStatsV2() {
+  const tiersByStatus = {}; for (const s of Object.values(HMEM_TIER_MATURITY_V2)) tiersByStatus[s] = 0; for (const t of _hmemTiers.values()) tiersByStatus[t.status]++;
+  const promotionsByStatus = {}; for (const s of Object.values(HMEM_PROMOTION_LIFECYCLE_V2)) promotionsByStatus[s] = 0; for (const p of _hmemPromos.values()) promotionsByStatus[p.status]++;
+  return { totalTiersV2: _hmemTiers.size, totalPromotionsV2: _hmemPromos.size, maxActiveHmemTiersPerOwner: _hmemMaxActivePerOwner, maxPendingHmemPromotionsPerTier: _hmemMaxPendingPerTier, hmemTierIdleMs: _hmemTierIdleMs, hmemPromotionStuckMs: _hmemPromoStuckMs, tiersByStatus, promotionsByStatus };
+}