chainlesschain 0.132.0 → 0.143.0

package/src/lib/inference-network.js

@@ -735,3 +735,108 @@ export function getInferenceStatsV2() {
     avgDurationMs: durCount > 0 ? Math.round(durSum / durCount) : 0,
   };
 }
+
+
+// ===== V2 Surface: Inference Network governance overlay (CLI v0.139.0) =====
+export const INFERENCE_NODE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", DEGRADED: "degraded", DECOMMISSIONED: "decommissioned",
+});
+export const INFERENCE_JOB_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", RUNNING: "running", COMPLETED: "completed", FAILED: "failed", CANCELLED: "cancelled",
+});
+
+const _inTrans = new Map([
+  [INFERENCE_NODE_MATURITY_V2.PENDING, new Set([INFERENCE_NODE_MATURITY_V2.ACTIVE, INFERENCE_NODE_MATURITY_V2.DECOMMISSIONED])],
+  [INFERENCE_NODE_MATURITY_V2.ACTIVE, new Set([INFERENCE_NODE_MATURITY_V2.DEGRADED, INFERENCE_NODE_MATURITY_V2.DECOMMISSIONED])],
+  [INFERENCE_NODE_MATURITY_V2.DEGRADED, new Set([INFERENCE_NODE_MATURITY_V2.ACTIVE, INFERENCE_NODE_MATURITY_V2.DECOMMISSIONED])],
+  [INFERENCE_NODE_MATURITY_V2.DECOMMISSIONED, new Set()],
+]);
+const _inTerminal = new Set([INFERENCE_NODE_MATURITY_V2.DECOMMISSIONED]);
+const _ijTrans = new Map([
+  [INFERENCE_JOB_LIFECYCLE_V2.QUEUED, new Set([INFERENCE_JOB_LIFECYCLE_V2.RUNNING, INFERENCE_JOB_LIFECYCLE_V2.CANCELLED])],
+  [INFERENCE_JOB_LIFECYCLE_V2.RUNNING, new Set([INFERENCE_JOB_LIFECYCLE_V2.COMPLETED, INFERENCE_JOB_LIFECYCLE_V2.FAILED, INFERENCE_JOB_LIFECYCLE_V2.CANCELLED])],
+  [INFERENCE_JOB_LIFECYCLE_V2.COMPLETED, new Set()],
+  [INFERENCE_JOB_LIFECYCLE_V2.FAILED, new Set()],
+  [INFERENCE_JOB_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _innV2 = new Map();
+const _ijsV2 = new Map();
+let _inMaxActivePerOperator = 12;
+let _inMaxPendingJobsPerNode = 25;
+let _inIdleMs = 24 * 60 * 60 * 1000;
+let _ijStuckMs = 10 * 60 * 1000;
+
+function _inPos(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 setMaxActiveInferenceNodesPerOperatorV2(n) { _inMaxActivePerOperator = _inPos(n, "maxActiveInferenceNodesPerOperator"); }
+export function getMaxActiveInferenceNodesPerOperatorV2() { return _inMaxActivePerOperator; }
+export function setMaxPendingInferenceJobsPerNodeV2(n) { _inMaxPendingJobsPerNode = _inPos(n, "maxPendingInferenceJobsPerNode"); }
+export function getMaxPendingInferenceJobsPerNodeV2() { return _inMaxPendingJobsPerNode; }
+export function setInferenceNodeIdleMsV2(n) { _inIdleMs = _inPos(n, "inferenceNodeIdleMs"); }
+export function getInferenceNodeIdleMsV2() { return _inIdleMs; }
+export function setInferenceJobStuckMsV2(n) { _ijStuckMs = _inPos(n, "inferenceJobStuckMs"); }
+export function getInferenceJobStuckMsV2() { return _ijStuckMs; }
+
+export function _resetStateInferenceNetworkV2() {
+  _innV2.clear(); _ijsV2.clear();
+  _inMaxActivePerOperator = 12; _inMaxPendingJobsPerNode = 25;
+  _inIdleMs = 24 * 60 * 60 * 1000; _ijStuckMs = 10 * 60 * 1000;
+}
+
+export function registerInferenceNodeV2({ id, operator, model, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!operator || typeof operator !== "string") throw new Error("operator is required");
+  if (_innV2.has(id)) throw new Error(`inference node ${id} already registered`);
+  const now = Date.now();
+  const n = { id, operator, model: model || "default", status: INFERENCE_NODE_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, decommissionedAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _innV2.set(id, n);
+  return { ...n, metadata: { ...n.metadata } };
+}
+function _inCheckN(from, to) { const a = _inTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid inference node transition ${from} → ${to}`); }
+function _inCountActive(operator) { let n = 0; for (const x of _innV2.values()) if (x.operator === operator && x.status === INFERENCE_NODE_MATURITY_V2.ACTIVE) n++; return n; }
+
+export function activateInferenceNodeV2(id) {
+  const n = _innV2.get(id); if (!n) throw new Error(`inference node ${id} not found`);
+  _inCheckN(n.status, INFERENCE_NODE_MATURITY_V2.ACTIVE);
+  const recovery = n.status === INFERENCE_NODE_MATURITY_V2.DEGRADED;
+  if (!recovery) { const c = _inCountActive(n.operator); if (c >= _inMaxActivePerOperator) throw new Error(`max active inference nodes per operator (${_inMaxActivePerOperator}) reached for ${n.operator}`); }
+  const now = Date.now(); n.status = INFERENCE_NODE_MATURITY_V2.ACTIVE; n.updatedAt = now; n.lastTouchedAt = now; if (!n.activatedAt) n.activatedAt = now;
+  return { ...n, metadata: { ...n.metadata } };
+}
+export function degradeInferenceNodeV2(id) { const n = _innV2.get(id); if (!n) throw new Error(`inference node ${id} not found`); _inCheckN(n.status, INFERENCE_NODE_MATURITY_V2.DEGRADED); n.status = INFERENCE_NODE_MATURITY_V2.DEGRADED; n.updatedAt = Date.now(); return { ...n, metadata: { ...n.metadata } }; }
+export function decommissionInferenceNodeV2(id) { const n = _innV2.get(id); if (!n) throw new Error(`inference node ${id} not found`); _inCheckN(n.status, INFERENCE_NODE_MATURITY_V2.DECOMMISSIONED); const now = Date.now(); n.status = INFERENCE_NODE_MATURITY_V2.DECOMMISSIONED; n.updatedAt = now; if (!n.decommissionedAt) n.decommissionedAt = now; return { ...n, metadata: { ...n.metadata } }; }
+export function touchInferenceNodeV2(id) { const n = _innV2.get(id); if (!n) throw new Error(`inference node ${id} not found`); if (_inTerminal.has(n.status)) throw new Error(`cannot touch terminal inference node ${id}`); const now = Date.now(); n.lastTouchedAt = now; n.updatedAt = now; return { ...n, metadata: { ...n.metadata } }; }
+export function getInferenceNodeV2(id) { const n = _innV2.get(id); if (!n) return null; return { ...n, metadata: { ...n.metadata } }; }
+export function listInferenceNodesV2() { return [..._innV2.values()].map((n) => ({ ...n, metadata: { ...n.metadata } })); }
+
+function _ijCountPending(nodeId) { let n = 0; for (const j of _ijsV2.values()) if (j.nodeId === nodeId && (j.status === INFERENCE_JOB_LIFECYCLE_V2.QUEUED || j.status === INFERENCE_JOB_LIFECYCLE_V2.RUNNING)) n++; return n; }
+
+export function createInferenceJobV2({ id, nodeId, prompt, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!nodeId || typeof nodeId !== "string") throw new Error("nodeId is required");
+  if (_ijsV2.has(id)) throw new Error(`inference job ${id} already exists`);
+  if (!_innV2.has(nodeId)) throw new Error(`inference node ${nodeId} not found`);
+  const pending = _ijCountPending(nodeId);
+  if (pending >= _inMaxPendingJobsPerNode) throw new Error(`max pending inference jobs per node (${_inMaxPendingJobsPerNode}) reached for ${nodeId}`);
+  const now = Date.now();
+  const j = { id, nodeId, prompt: prompt || "", status: INFERENCE_JOB_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _ijsV2.set(id, j);
+  return { ...j, metadata: { ...j.metadata } };
+}
+function _ijCheckJ(from, to) { const a = _ijTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid inference job transition ${from} → ${to}`); }
+export function startInferenceJobV2(id) { const j = _ijsV2.get(id); if (!j) throw new Error(`inference job ${id} not found`); _ijCheckJ(j.status, INFERENCE_JOB_LIFECYCLE_V2.RUNNING); const now = Date.now(); j.status = INFERENCE_JOB_LIFECYCLE_V2.RUNNING; j.updatedAt = now; if (!j.startedAt) j.startedAt = now; return { ...j, metadata: { ...j.metadata } }; }
+export function completeInferenceJobV2(id) { const j = _ijsV2.get(id); if (!j) throw new Error(`inference job ${id} not found`); _ijCheckJ(j.status, INFERENCE_JOB_LIFECYCLE_V2.COMPLETED); const now = Date.now(); j.status = INFERENCE_JOB_LIFECYCLE_V2.COMPLETED; j.updatedAt = now; if (!j.settledAt) j.settledAt = now; return { ...j, metadata: { ...j.metadata } }; }
+export function failInferenceJobV2(id, reason) { const j = _ijsV2.get(id); if (!j) throw new Error(`inference job ${id} not found`); _ijCheckJ(j.status, INFERENCE_JOB_LIFECYCLE_V2.FAILED); const now = Date.now(); j.status = INFERENCE_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 cancelInferenceJobV2(id, reason) { const j = _ijsV2.get(id); if (!j) throw new Error(`inference job ${id} not found`); _ijCheckJ(j.status, INFERENCE_JOB_LIFECYCLE_V2.CANCELLED); const now = Date.now(); j.status = INFERENCE_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 getInferenceJobV2(id) { const j = _ijsV2.get(id); if (!j) return null; return { ...j, metadata: { ...j.metadata } }; }
+export function listInferenceJobsV2() { return [..._ijsV2.values()].map((j) => ({ ...j, metadata: { ...j.metadata } })); }
+
+export function autoDegradeIdleInferenceNodesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const n of _innV2.values()) if (n.status === INFERENCE_NODE_MATURITY_V2.ACTIVE && (t - n.lastTouchedAt) >= _inIdleMs) { n.status = INFERENCE_NODE_MATURITY_V2.DEGRADED; n.updatedAt = t; flipped.push(n.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckInferenceJobsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const j of _ijsV2.values()) if (j.status === INFERENCE_JOB_LIFECYCLE_V2.RUNNING && j.startedAt != null && (t - j.startedAt) >= _ijStuckMs) { j.status = INFERENCE_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 getInferenceNetworkGovStatsV2() {
+  const nodesByStatus = {}; for (const s of Object.values(INFERENCE_NODE_MATURITY_V2)) nodesByStatus[s] = 0; for (const n of _innV2.values()) nodesByStatus[n.status]++;
+  const jobsByStatus = {}; for (const s of Object.values(INFERENCE_JOB_LIFECYCLE_V2)) jobsByStatus[s] = 0; for (const j of _ijsV2.values()) jobsByStatus[j.status]++;
+  return { totalInferenceNodesV2: _innV2.size, totalInferenceJobsV2: _ijsV2.size, maxActiveInferenceNodesPerOperator: _inMaxActivePerOperator, maxPendingInferenceJobsPerNode: _inMaxPendingJobsPerNode, inferenceNodeIdleMs: _inIdleMs, inferenceJobStuckMs: _ijStuckMs, nodesByStatus, jobsByStatus };
+}

package/src/lib/iteration-budget.js

@@ -173,3 +173,108 @@ export class IterationBudget {
 export const DEFAULT_ITERATION_BUDGET = DEFAULT_BUDGET;
 export const BUDGET_WARNING_THRESHOLD = WARNING_THRESHOLD;
 export const BUDGET_WRAPPING_UP_THRESHOLD = WRAPPING_UP_THRESHOLD;
+
+
+// ===== V2 Surface: Iteration Budget governance overlay (CLI v0.140.0) =====
+export const ITER_BUDGET_PROFILE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", PAUSED: "paused", EXHAUSTED: "exhausted",
+});
+export const ITER_RUN_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", RUNNING: "running", COMPLETED: "completed", FAILED: "failed", CANCELLED: "cancelled",
+});
+
+const _ibpTrans = new Map([
+  [ITER_BUDGET_PROFILE_MATURITY_V2.PENDING, new Set([ITER_BUDGET_PROFILE_MATURITY_V2.ACTIVE, ITER_BUDGET_PROFILE_MATURITY_V2.EXHAUSTED])],
+  [ITER_BUDGET_PROFILE_MATURITY_V2.ACTIVE, new Set([ITER_BUDGET_PROFILE_MATURITY_V2.PAUSED, ITER_BUDGET_PROFILE_MATURITY_V2.EXHAUSTED])],
+  [ITER_BUDGET_PROFILE_MATURITY_V2.PAUSED, new Set([ITER_BUDGET_PROFILE_MATURITY_V2.ACTIVE, ITER_BUDGET_PROFILE_MATURITY_V2.EXHAUSTED])],
+  [ITER_BUDGET_PROFILE_MATURITY_V2.EXHAUSTED, new Set()],
+]);
+const _ibpTerminal = new Set([ITER_BUDGET_PROFILE_MATURITY_V2.EXHAUSTED]);
+const _irTrans = new Map([
+  [ITER_RUN_LIFECYCLE_V2.QUEUED, new Set([ITER_RUN_LIFECYCLE_V2.RUNNING, ITER_RUN_LIFECYCLE_V2.CANCELLED])],
+  [ITER_RUN_LIFECYCLE_V2.RUNNING, new Set([ITER_RUN_LIFECYCLE_V2.COMPLETED, ITER_RUN_LIFECYCLE_V2.FAILED, ITER_RUN_LIFECYCLE_V2.CANCELLED])],
+  [ITER_RUN_LIFECYCLE_V2.COMPLETED, new Set()],
+  [ITER_RUN_LIFECYCLE_V2.FAILED, new Set()],
+  [ITER_RUN_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _ibpsV2 = new Map();
+const _irsV2 = new Map();
+let _ibpMaxActivePerOwner = 4;
+let _ibpMaxPendingRunsPerProfile = 8;
+let _ibpIdleMs = 24 * 60 * 60 * 1000;
+let _irStuckMs = 60 * 60 * 1000;
+
+function _ibpPos(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 setMaxActiveIterBudgetProfilesPerOwnerV2(n) { _ibpMaxActivePerOwner = _ibpPos(n, "maxActiveIterBudgetProfilesPerOwner"); }
+export function getMaxActiveIterBudgetProfilesPerOwnerV2() { return _ibpMaxActivePerOwner; }
+export function setMaxPendingIterRunsPerProfileV2(n) { _ibpMaxPendingRunsPerProfile = _ibpPos(n, "maxPendingIterRunsPerProfile"); }
+export function getMaxPendingIterRunsPerProfileV2() { return _ibpMaxPendingRunsPerProfile; }
+export function setIterBudgetProfileIdleMsV2(n) { _ibpIdleMs = _ibpPos(n, "iterBudgetProfileIdleMs"); }
+export function getIterBudgetProfileIdleMsV2() { return _ibpIdleMs; }
+export function setIterRunStuckMsV2(n) { _irStuckMs = _ibpPos(n, "iterRunStuckMs"); }
+export function getIterRunStuckMsV2() { return _irStuckMs; }
+
+export function _resetStateIterationBudgetV2() {
+  _ibpsV2.clear(); _irsV2.clear();
+  _ibpMaxActivePerOwner = 4; _ibpMaxPendingRunsPerProfile = 8;
+  _ibpIdleMs = 24 * 60 * 60 * 1000; _irStuckMs = 60 * 60 * 1000;
+}
+
+export function registerIterBudgetProfileV2({ id, owner, budget, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_ibpsV2.has(id)) throw new Error(`iter budget profile ${id} already registered`);
+  const now = Date.now();
+  const p = { id, owner, budget: budget || 50, status: ITER_BUDGET_PROFILE_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, exhaustedAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _ibpsV2.set(id, p);
+  return { ...p, metadata: { ...p.metadata } };
+}
+function _ibpCheckP(from, to) { const a = _ibpTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid iter budget profile transition ${from} → ${to}`); }
+function _ibpCountActive(owner) { let n = 0; for (const p of _ibpsV2.values()) if (p.owner === owner && p.status === ITER_BUDGET_PROFILE_MATURITY_V2.ACTIVE) n++; return n; }
+
+export function activateIterBudgetProfileV2(id) {
+  const p = _ibpsV2.get(id); if (!p) throw new Error(`iter budget profile ${id} not found`);
+  _ibpCheckP(p.status, ITER_BUDGET_PROFILE_MATURITY_V2.ACTIVE);
+  const recovery = p.status === ITER_BUDGET_PROFILE_MATURITY_V2.PAUSED;
+  if (!recovery) { const c = _ibpCountActive(p.owner); if (c >= _ibpMaxActivePerOwner) throw new Error(`max active iter budget profiles per owner (${_ibpMaxActivePerOwner}) reached for ${p.owner}`); }
+  const now = Date.now(); p.status = ITER_BUDGET_PROFILE_MATURITY_V2.ACTIVE; p.updatedAt = now; p.lastTouchedAt = now; if (!p.activatedAt) p.activatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function pauseIterBudgetProfileV2(id) { const p = _ibpsV2.get(id); if (!p) throw new Error(`iter budget profile ${id} not found`); _ibpCheckP(p.status, ITER_BUDGET_PROFILE_MATURITY_V2.PAUSED); p.status = ITER_BUDGET_PROFILE_MATURITY_V2.PAUSED; p.updatedAt = Date.now(); return { ...p, metadata: { ...p.metadata } }; }
+export function exhaustIterBudgetProfileV2(id) { const p = _ibpsV2.get(id); if (!p) throw new Error(`iter budget profile ${id} not found`); _ibpCheckP(p.status, ITER_BUDGET_PROFILE_MATURITY_V2.EXHAUSTED); const now = Date.now(); p.status = ITER_BUDGET_PROFILE_MATURITY_V2.EXHAUSTED; p.updatedAt = now; if (!p.exhaustedAt) p.exhaustedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function touchIterBudgetProfileV2(id) { const p = _ibpsV2.get(id); if (!p) throw new Error(`iter budget profile ${id} not found`); if (_ibpTerminal.has(p.status)) throw new Error(`cannot touch terminal iter budget profile ${id}`); const now = Date.now(); p.lastTouchedAt = now; p.updatedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function getIterBudgetProfileV2(id) { const p = _ibpsV2.get(id); if (!p) return null; return { ...p, metadata: { ...p.metadata } }; }
+export function listIterBudgetProfilesV2() { return [..._ibpsV2.values()].map((p) => ({ ...p, metadata: { ...p.metadata } })); }
+
+function _irCountPending(profileId) { let n = 0; for (const r of _irsV2.values()) if (r.profileId === profileId && (r.status === ITER_RUN_LIFECYCLE_V2.QUEUED || r.status === ITER_RUN_LIFECYCLE_V2.RUNNING)) n++; return n; }
+
+export function createIterRunV2({ id, profileId, goal, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!profileId || typeof profileId !== "string") throw new Error("profileId is required");
+  if (_irsV2.has(id)) throw new Error(`iter run ${id} already exists`);
+  if (!_ibpsV2.has(profileId)) throw new Error(`iter budget profile ${profileId} not found`);
+  const pending = _irCountPending(profileId);
+  if (pending >= _ibpMaxPendingRunsPerProfile) throw new Error(`max pending iter runs per profile (${_ibpMaxPendingRunsPerProfile}) reached for ${profileId}`);
+  const now = Date.now();
+  const r = { id, profileId, goal: goal || "", status: ITER_RUN_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _irsV2.set(id, r);
+  return { ...r, metadata: { ...r.metadata } };
+}
+function _irCheckR(from, to) { const a = _irTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid iter run transition ${from} → ${to}`); }
+export function startIterRunV2(id) { const r = _irsV2.get(id); if (!r) throw new Error(`iter run ${id} not found`); _irCheckR(r.status, ITER_RUN_LIFECYCLE_V2.RUNNING); const now = Date.now(); r.status = ITER_RUN_LIFECYCLE_V2.RUNNING; r.updatedAt = now; if (!r.startedAt) r.startedAt = now; return { ...r, metadata: { ...r.metadata } }; }
+export function completeIterRunV2(id) { const r = _irsV2.get(id); if (!r) throw new Error(`iter run ${id} not found`); _irCheckR(r.status, ITER_RUN_LIFECYCLE_V2.COMPLETED); const now = Date.now(); r.status = ITER_RUN_LIFECYCLE_V2.COMPLETED; r.updatedAt = now; if (!r.settledAt) r.settledAt = now; return { ...r, metadata: { ...r.metadata } }; }
+export function failIterRunV2(id, reason) { const r = _irsV2.get(id); if (!r) throw new Error(`iter run ${id} not found`); _irCheckR(r.status, ITER_RUN_LIFECYCLE_V2.FAILED); const now = Date.now(); r.status = ITER_RUN_LIFECYCLE_V2.FAILED; r.updatedAt = now; if (!r.settledAt) r.settledAt = now; if (reason) r.metadata.failReason = String(reason); return { ...r, metadata: { ...r.metadata } }; }
+export function cancelIterRunV2(id, reason) { const r = _irsV2.get(id); if (!r) throw new Error(`iter run ${id} not found`); _irCheckR(r.status, ITER_RUN_LIFECYCLE_V2.CANCELLED); const now = Date.now(); r.status = ITER_RUN_LIFECYCLE_V2.CANCELLED; r.updatedAt = now; if (!r.settledAt) r.settledAt = now; if (reason) r.metadata.cancelReason = String(reason); return { ...r, metadata: { ...r.metadata } }; }
+export function getIterRunV2(id) { const r = _irsV2.get(id); if (!r) return null; return { ...r, metadata: { ...r.metadata } }; }
+export function listIterRunsV2() { return [..._irsV2.values()].map((r) => ({ ...r, metadata: { ...r.metadata } })); }
+
+export function autoPauseIdleIterBudgetProfilesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const p of _ibpsV2.values()) if (p.status === ITER_BUDGET_PROFILE_MATURITY_V2.ACTIVE && (t - p.lastTouchedAt) >= _ibpIdleMs) { p.status = ITER_BUDGET_PROFILE_MATURITY_V2.PAUSED; p.updatedAt = t; flipped.push(p.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckIterRunsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const r of _irsV2.values()) if (r.status === ITER_RUN_LIFECYCLE_V2.RUNNING && r.startedAt != null && (t - r.startedAt) >= _irStuckMs) { r.status = ITER_RUN_LIFECYCLE_V2.FAILED; r.updatedAt = t; if (!r.settledAt) r.settledAt = t; r.metadata.failReason = "auto-fail-stuck"; flipped.push(r.id); } return { flipped, count: flipped.length }; }
+
+export function getIterationBudgetGovStatsV2() {
+  const profilesByStatus = {}; for (const s of Object.values(ITER_BUDGET_PROFILE_MATURITY_V2)) profilesByStatus[s] = 0; for (const p of _ibpsV2.values()) profilesByStatus[p.status]++;
+  const runsByStatus = {}; for (const s of Object.values(ITER_RUN_LIFECYCLE_V2)) runsByStatus[s] = 0; for (const r of _irsV2.values()) runsByStatus[r.status]++;
+  return { totalIterBudgetProfilesV2: _ibpsV2.size, totalIterRunsV2: _irsV2.size, maxActiveIterBudgetProfilesPerOwner: _ibpMaxActivePerOwner, maxPendingIterRunsPerProfile: _ibpMaxPendingRunsPerProfile, iterBudgetProfileIdleMs: _ibpIdleMs, iterRunStuckMs: _irStuckMs, profilesByStatus, runsByStatus };
+}

package/src/lib/matrix-bridge.js

@@ -446,3 +446,108 @@ export function _resetState() {
     e2eeEnabled: true,
   };
 }
+
+
+// ===== V2 Surface: Matrix Bridge governance overlay (CLI v0.134.0) =====
+export const MX_ROOM_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", MUTED: "muted", ARCHIVED: "archived",
+});
+export const MX_MESSAGE_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", SENDING: "sending", DELIVERED: "delivered", FAILED: "failed", CANCELLED: "cancelled",
+});
+
+const _mxRoomTrans = new Map([
+  [MX_ROOM_MATURITY_V2.PENDING, new Set([MX_ROOM_MATURITY_V2.ACTIVE, MX_ROOM_MATURITY_V2.ARCHIVED])],
+  [MX_ROOM_MATURITY_V2.ACTIVE, new Set([MX_ROOM_MATURITY_V2.MUTED, MX_ROOM_MATURITY_V2.ARCHIVED])],
+  [MX_ROOM_MATURITY_V2.MUTED, new Set([MX_ROOM_MATURITY_V2.ACTIVE, MX_ROOM_MATURITY_V2.ARCHIVED])],
+  [MX_ROOM_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _mxRoomTerminal = new Set([MX_ROOM_MATURITY_V2.ARCHIVED]);
+const _mxMsgTrans = new Map([
+  [MX_MESSAGE_LIFECYCLE_V2.QUEUED, new Set([MX_MESSAGE_LIFECYCLE_V2.SENDING, MX_MESSAGE_LIFECYCLE_V2.CANCELLED])],
+  [MX_MESSAGE_LIFECYCLE_V2.SENDING, new Set([MX_MESSAGE_LIFECYCLE_V2.DELIVERED, MX_MESSAGE_LIFECYCLE_V2.FAILED, MX_MESSAGE_LIFECYCLE_V2.CANCELLED])],
+  [MX_MESSAGE_LIFECYCLE_V2.DELIVERED, new Set()],
+  [MX_MESSAGE_LIFECYCLE_V2.FAILED, new Set()],
+  [MX_MESSAGE_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _mxRooms = new Map();
+const _mxMsgs = new Map();
+let _mxMaxActivePerOwner = 20;
+let _mxMaxPendingPerRoom = 40;
+let _mxRoomIdleMs = 24 * 60 * 60 * 1000;
+let _mxMsgStuckMs = 3 * 60 * 1000;
+
+function _mxPos(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 setMaxActiveMatrixRoomsPerOwnerV2(n) { _mxMaxActivePerOwner = _mxPos(n, "maxActiveMatrixRoomsPerOwner"); }
+export function getMaxActiveMatrixRoomsPerOwnerV2() { return _mxMaxActivePerOwner; }
+export function setMaxPendingMatrixMessagesPerRoomV2(n) { _mxMaxPendingPerRoom = _mxPos(n, "maxPendingMatrixMessagesPerRoom"); }
+export function getMaxPendingMatrixMessagesPerRoomV2() { return _mxMaxPendingPerRoom; }
+export function setMatrixRoomIdleMsV2(n) { _mxRoomIdleMs = _mxPos(n, "matrixRoomIdleMs"); }
+export function getMatrixRoomIdleMsV2() { return _mxRoomIdleMs; }
+export function setMatrixMessageStuckMsV2(n) { _mxMsgStuckMs = _mxPos(n, "matrixMessageStuckMs"); }
+export function getMatrixMessageStuckMsV2() { return _mxMsgStuckMs; }
+
+export function _resetStateMatrixBridgeV2() {
+  _mxRooms.clear(); _mxMsgs.clear();
+  _mxMaxActivePerOwner = 20; _mxMaxPendingPerRoom = 40;
+  _mxRoomIdleMs = 24 * 60 * 60 * 1000; _mxMsgStuckMs = 3 * 60 * 1000;
+}
+
+export function registerMatrixRoomV2({ id, owner, alias, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_mxRooms.has(id)) throw new Error(`matrix room ${id} already registered`);
+  const now = Date.now();
+  const r = { id, owner, alias: alias || id, status: MX_ROOM_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, archivedAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _mxRooms.set(id, r);
+  return { ...r, metadata: { ...r.metadata } };
+}
+function _mxCheckR(from, to) { const a = _mxRoomTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid matrix room transition ${from} → ${to}`); }
+function _mxCountActive(owner) { let n = 0; for (const r of _mxRooms.values()) if (r.owner === owner && r.status === MX_ROOM_MATURITY_V2.ACTIVE) n++; return n; }
+
+export function activateMatrixRoomV2(id) {
+  const r = _mxRooms.get(id); if (!r) throw new Error(`matrix room ${id} not found`);
+  _mxCheckR(r.status, MX_ROOM_MATURITY_V2.ACTIVE);
+  const recovery = r.status === MX_ROOM_MATURITY_V2.MUTED;
+  if (!recovery) { const a = _mxCountActive(r.owner); if (a >= _mxMaxActivePerOwner) throw new Error(`max active matrix rooms per owner (${_mxMaxActivePerOwner}) reached for ${r.owner}`); }
+  const now = Date.now(); r.status = MX_ROOM_MATURITY_V2.ACTIVE; r.updatedAt = now; r.lastTouchedAt = now; if (!r.activatedAt) r.activatedAt = now;
+  return { ...r, metadata: { ...r.metadata } };
+}
+export function muteMatrixRoomV2(id) { const r = _mxRooms.get(id); if (!r) throw new Error(`matrix room ${id} not found`); _mxCheckR(r.status, MX_ROOM_MATURITY_V2.MUTED); r.status = MX_ROOM_MATURITY_V2.MUTED; r.updatedAt = Date.now(); return { ...r, metadata: { ...r.metadata } }; }
+export function archiveMatrixRoomV2(id) { const r = _mxRooms.get(id); if (!r) throw new Error(`matrix room ${id} not found`); _mxCheckR(r.status, MX_ROOM_MATURITY_V2.ARCHIVED); const now = Date.now(); r.status = MX_ROOM_MATURITY_V2.ARCHIVED; r.updatedAt = now; if (!r.archivedAt) r.archivedAt = now; return { ...r, metadata: { ...r.metadata } }; }
+export function touchMatrixRoomV2(id) { const r = _mxRooms.get(id); if (!r) throw new Error(`matrix room ${id} not found`); if (_mxRoomTerminal.has(r.status)) throw new Error(`cannot touch terminal matrix room ${id}`); const now = Date.now(); r.lastTouchedAt = now; r.updatedAt = now; return { ...r, metadata: { ...r.metadata } }; }
+export function getMatrixRoomV2(id) { const r = _mxRooms.get(id); if (!r) return null; return { ...r, metadata: { ...r.metadata } }; }
+export function listMatrixRoomsV2() { return [..._mxRooms.values()].map((r) => ({ ...r, metadata: { ...r.metadata } })); }
+
+function _mxCountPending(rid) { let n = 0; for (const m of _mxMsgs.values()) if (m.roomId === rid && (m.status === MX_MESSAGE_LIFECYCLE_V2.QUEUED || m.status === MX_MESSAGE_LIFECYCLE_V2.SENDING)) n++; return n; }
+
+export function createMatrixMessageV2({ id, roomId, body, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!roomId || typeof roomId !== "string") throw new Error("roomId is required");
+  if (_mxMsgs.has(id)) throw new Error(`matrix message ${id} already exists`);
+  if (!_mxRooms.has(roomId)) throw new Error(`matrix room ${roomId} not found`);
+  const pending = _mxCountPending(roomId);
+  if (pending >= _mxMaxPendingPerRoom) throw new Error(`max pending matrix messages per room (${_mxMaxPendingPerRoom}) reached for ${roomId}`);
+  const now = Date.now();
+  const m = { id, roomId, body: body || "", status: MX_MESSAGE_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _mxMsgs.set(id, m);
+  return { ...m, metadata: { ...m.metadata } };
+}
+function _mxCheckM(from, to) { const a = _mxMsgTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid matrix message transition ${from} → ${to}`); }
+export function startMatrixMessageV2(id) { const m = _mxMsgs.get(id); if (!m) throw new Error(`matrix message ${id} not found`); _mxCheckM(m.status, MX_MESSAGE_LIFECYCLE_V2.SENDING); const now = Date.now(); m.status = MX_MESSAGE_LIFECYCLE_V2.SENDING; m.updatedAt = now; if (!m.startedAt) m.startedAt = now; return { ...m, metadata: { ...m.metadata } }; }
+export function deliverMatrixMessageV2(id) { const m = _mxMsgs.get(id); if (!m) throw new Error(`matrix message ${id} not found`); _mxCheckM(m.status, MX_MESSAGE_LIFECYCLE_V2.DELIVERED); const now = Date.now(); m.status = MX_MESSAGE_LIFECYCLE_V2.DELIVERED; m.updatedAt = now; if (!m.settledAt) m.settledAt = now; return { ...m, metadata: { ...m.metadata } }; }
+export function failMatrixMessageV2(id, reason) { const m = _mxMsgs.get(id); if (!m) throw new Error(`matrix message ${id} not found`); _mxCheckM(m.status, MX_MESSAGE_LIFECYCLE_V2.FAILED); const now = Date.now(); m.status = MX_MESSAGE_LIFECYCLE_V2.FAILED; m.updatedAt = now; if (!m.settledAt) m.settledAt = now; if (reason) m.metadata.failReason = String(reason); return { ...m, metadata: { ...m.metadata } }; }
+export function cancelMatrixMessageV2(id, reason) { const m = _mxMsgs.get(id); if (!m) throw new Error(`matrix message ${id} not found`); _mxCheckM(m.status, MX_MESSAGE_LIFECYCLE_V2.CANCELLED); const now = Date.now(); m.status = MX_MESSAGE_LIFECYCLE_V2.CANCELLED; m.updatedAt = now; if (!m.settledAt) m.settledAt = now; if (reason) m.metadata.cancelReason = String(reason); return { ...m, metadata: { ...m.metadata } }; }
+export function getMatrixMessageV2(id) { const m = _mxMsgs.get(id); if (!m) return null; return { ...m, metadata: { ...m.metadata } }; }
+export function listMatrixMessagesV2() { return [..._mxMsgs.values()].map((m) => ({ ...m, metadata: { ...m.metadata } })); }
+
+export function autoMuteIdleMatrixRoomsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const r of _mxRooms.values()) if (r.status === MX_ROOM_MATURITY_V2.ACTIVE && (t - r.lastTouchedAt) >= _mxRoomIdleMs) { r.status = MX_ROOM_MATURITY_V2.MUTED; r.updatedAt = t; flipped.push(r.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckMatrixMessagesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const m of _mxMsgs.values()) if (m.status === MX_MESSAGE_LIFECYCLE_V2.SENDING && m.startedAt != null && (t - m.startedAt) >= _mxMsgStuckMs) { m.status = MX_MESSAGE_LIFECYCLE_V2.FAILED; m.updatedAt = t; if (!m.settledAt) m.settledAt = t; m.metadata.failReason = "auto-fail-stuck"; flipped.push(m.id); } return { flipped, count: flipped.length }; }
+
+export function getMatrixBridgeStatsV2() {
+  const roomsByStatus = {}; for (const s of Object.values(MX_ROOM_MATURITY_V2)) roomsByStatus[s] = 0; for (const r of _mxRooms.values()) roomsByStatus[r.status]++;
+  const msgsByStatus = {}; for (const s of Object.values(MX_MESSAGE_LIFECYCLE_V2)) msgsByStatus[s] = 0; for (const m of _mxMsgs.values()) msgsByStatus[m.status]++;
+  return { totalRoomsV2: _mxRooms.size, totalMessagesV2: _mxMsgs.size, maxActiveMatrixRoomsPerOwner: _mxMaxActivePerOwner, maxPendingMatrixMessagesPerRoom: _mxMaxPendingPerRoom, matrixRoomIdleMs: _mxRoomIdleMs, matrixMessageStuckMs: _mxMsgStuckMs, roomsByStatus, msgsByStatus };
+}

package/src/lib/mcp-scaffold.js

@@ -383,3 +383,84 @@ function renderGitignore() {
 !.env.example
 `;
 }
+
+// ===== V2 Surface: MCP Scaffold governance overlay (CLI v0.142.0) =====
+export const MSCAF_PROFILE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", STALE: "stale", ARCHIVED: "archived",
+});
+export const MSCAF_GENERATION_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", GENERATING: "generating", GENERATED: "generated", FAILED: "failed", CANCELLED: "cancelled",
+});
+const _mscafPTrans = new Map([
+  [MSCAF_PROFILE_MATURITY_V2.PENDING, new Set([MSCAF_PROFILE_MATURITY_V2.ACTIVE, MSCAF_PROFILE_MATURITY_V2.ARCHIVED])],
+  [MSCAF_PROFILE_MATURITY_V2.ACTIVE, new Set([MSCAF_PROFILE_MATURITY_V2.STALE, MSCAF_PROFILE_MATURITY_V2.ARCHIVED])],
+  [MSCAF_PROFILE_MATURITY_V2.STALE, new Set([MSCAF_PROFILE_MATURITY_V2.ACTIVE, MSCAF_PROFILE_MATURITY_V2.ARCHIVED])],
+  [MSCAF_PROFILE_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _mscafPTerminal = new Set([MSCAF_PROFILE_MATURITY_V2.ARCHIVED]);
+const _mscafGTrans = new Map([
+  [MSCAF_GENERATION_LIFECYCLE_V2.QUEUED, new Set([MSCAF_GENERATION_LIFECYCLE_V2.GENERATING, MSCAF_GENERATION_LIFECYCLE_V2.CANCELLED])],
+  [MSCAF_GENERATION_LIFECYCLE_V2.GENERATING, new Set([MSCAF_GENERATION_LIFECYCLE_V2.GENERATED, MSCAF_GENERATION_LIFECYCLE_V2.FAILED, MSCAF_GENERATION_LIFECYCLE_V2.CANCELLED])],
+  [MSCAF_GENERATION_LIFECYCLE_V2.GENERATED, new Set()],
+  [MSCAF_GENERATION_LIFECYCLE_V2.FAILED, new Set()],
+  [MSCAF_GENERATION_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+const _mscafPsV2 = new Map();
+const _mscafGsV2 = new Map();
+let _mscafMaxActive = 6, _mscafMaxPending = 15, _mscafIdleMs = 30 * 24 * 60 * 60 * 1000, _mscafStuckMs = 60 * 1000;
+function _mscafPos(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 _mscafCheckP(from, to) { const a = _mscafPTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid mscaf profile transition ${from} → ${to}`); }
+function _mscafCheckG(from, to) { const a = _mscafGTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid mscaf generation transition ${from} → ${to}`); }
+export function setMaxActiveMscafProfilesPerOwnerV2(n) { _mscafMaxActive = _mscafPos(n, "maxActiveMscafProfilesPerOwner"); }
+export function getMaxActiveMscafProfilesPerOwnerV2() { return _mscafMaxActive; }
+export function setMaxPendingMscafGenerationsPerProfileV2(n) { _mscafMaxPending = _mscafPos(n, "maxPendingMscafGenerationsPerProfile"); }
+export function getMaxPendingMscafGenerationsPerProfileV2() { return _mscafMaxPending; }
+export function setMscafProfileIdleMsV2(n) { _mscafIdleMs = _mscafPos(n, "mscafProfileIdleMs"); }
+export function getMscafProfileIdleMsV2() { return _mscafIdleMs; }
+export function setMscafGenerationStuckMsV2(n) { _mscafStuckMs = _mscafPos(n, "mscafGenerationStuckMs"); }
+export function getMscafGenerationStuckMsV2() { return _mscafStuckMs; }
+export function _resetStateMcpScaffoldV2() { _mscafPsV2.clear(); _mscafGsV2.clear(); _mscafMaxActive = 6; _mscafMaxPending = 15; _mscafIdleMs = 30 * 24 * 60 * 60 * 1000; _mscafStuckMs = 60 * 1000; }
+export function registerMscafProfileV2({ id, owner, transport, metadata } = {}) {
+  if (!id) throw new Error("mscaf profile id required"); if (!owner) throw new Error("mscaf profile owner required");
+  if (_mscafPsV2.has(id)) throw new Error(`mscaf profile ${id} already registered`);
+  const now = Date.now();
+  const p = { id, owner, transport: transport || "stdio", status: MSCAF_PROFILE_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, archivedAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _mscafPsV2.set(id, p); return { ...p, metadata: { ...p.metadata } };
+}
+function _mscafCountActive(owner) { let n = 0; for (const p of _mscafPsV2.values()) if (p.owner === owner && p.status === MSCAF_PROFILE_MATURITY_V2.ACTIVE) n++; return n; }
+export function activateMscafProfileV2(id) {
+  const p = _mscafPsV2.get(id); if (!p) throw new Error(`mscaf profile ${id} not found`);
+  _mscafCheckP(p.status, MSCAF_PROFILE_MATURITY_V2.ACTIVE);
+  const recovery = p.status === MSCAF_PROFILE_MATURITY_V2.STALE;
+  if (!recovery && _mscafCountActive(p.owner) >= _mscafMaxActive) throw new Error(`max active mscaf profiles for owner ${p.owner} reached`);
+  const now = Date.now(); p.status = MSCAF_PROFILE_MATURITY_V2.ACTIVE; p.updatedAt = now; p.lastTouchedAt = now; if (!p.activatedAt) p.activatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function staleMscafProfileV2(id) { const p = _mscafPsV2.get(id); if (!p) throw new Error(`mscaf profile ${id} not found`); _mscafCheckP(p.status, MSCAF_PROFILE_MATURITY_V2.STALE); p.status = MSCAF_PROFILE_MATURITY_V2.STALE; p.updatedAt = Date.now(); return { ...p, metadata: { ...p.metadata } }; }
+export function archiveMscafProfileV2(id) { const p = _mscafPsV2.get(id); if (!p) throw new Error(`mscaf profile ${id} not found`); _mscafCheckP(p.status, MSCAF_PROFILE_MATURITY_V2.ARCHIVED); const now = Date.now(); p.status = MSCAF_PROFILE_MATURITY_V2.ARCHIVED; p.updatedAt = now; if (!p.archivedAt) p.archivedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function touchMscafProfileV2(id) { const p = _mscafPsV2.get(id); if (!p) throw new Error(`mscaf profile ${id} not found`); if (_mscafPTerminal.has(p.status)) throw new Error(`cannot touch terminal mscaf profile ${id}`); const now = Date.now(); p.lastTouchedAt = now; p.updatedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function getMscafProfileV2(id) { const p = _mscafPsV2.get(id); if (!p) return null; return { ...p, metadata: { ...p.metadata } }; }
+export function listMscafProfilesV2() { return [..._mscafPsV2.values()].map((p) => ({ ...p, metadata: { ...p.metadata } })); }
+function _mscafCountPending(profileId) { let n = 0; for (const g of _mscafGsV2.values()) if (g.profileId === profileId && (g.status === MSCAF_GENERATION_LIFECYCLE_V2.QUEUED || g.status === MSCAF_GENERATION_LIFECYCLE_V2.GENERATING)) n++; return n; }
+export function createMscafGenerationV2({ id, profileId, target, metadata } = {}) {
+  if (!id) throw new Error("mscaf generation id required"); if (!profileId) throw new Error("mscaf generation profileId required");
+  if (_mscafGsV2.has(id)) throw new Error(`mscaf generation ${id} already exists`);
+  if (!_mscafPsV2.has(profileId)) throw new Error(`mscaf profile ${profileId} not found`);
+  if (_mscafCountPending(profileId) >= _mscafMaxPending) throw new Error(`max pending mscaf generations for profile ${profileId} reached`);
+  const now = Date.now();
+  const g = { id, profileId, target: target || "", status: MSCAF_GENERATION_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _mscafGsV2.set(id, g); return { ...g, metadata: { ...g.metadata } };
+}
+export function generatingMscafGenerationV2(id) { const g = _mscafGsV2.get(id); if (!g) throw new Error(`mscaf generation ${id} not found`); _mscafCheckG(g.status, MSCAF_GENERATION_LIFECYCLE_V2.GENERATING); const now = Date.now(); g.status = MSCAF_GENERATION_LIFECYCLE_V2.GENERATING; g.updatedAt = now; if (!g.startedAt) g.startedAt = now; return { ...g, metadata: { ...g.metadata } }; }
+export function generateMscafGenerationV2(id) { const g = _mscafGsV2.get(id); if (!g) throw new Error(`mscaf generation ${id} not found`); _mscafCheckG(g.status, MSCAF_GENERATION_LIFECYCLE_V2.GENERATED); const now = Date.now(); g.status = MSCAF_GENERATION_LIFECYCLE_V2.GENERATED; g.updatedAt = now; if (!g.settledAt) g.settledAt = now; return { ...g, metadata: { ...g.metadata } }; }
+export function failMscafGenerationV2(id, reason) { const g = _mscafGsV2.get(id); if (!g) throw new Error(`mscaf generation ${id} not found`); _mscafCheckG(g.status, MSCAF_GENERATION_LIFECYCLE_V2.FAILED); const now = Date.now(); g.status = MSCAF_GENERATION_LIFECYCLE_V2.FAILED; g.updatedAt = now; if (!g.settledAt) g.settledAt = now; if (reason) g.metadata.failReason = String(reason); return { ...g, metadata: { ...g.metadata } }; }
+export function cancelMscafGenerationV2(id, reason) { const g = _mscafGsV2.get(id); if (!g) throw new Error(`mscaf generation ${id} not found`); _mscafCheckG(g.status, MSCAF_GENERATION_LIFECYCLE_V2.CANCELLED); const now = Date.now(); g.status = MSCAF_GENERATION_LIFECYCLE_V2.CANCELLED; g.updatedAt = now; if (!g.settledAt) g.settledAt = now; if (reason) g.metadata.cancelReason = String(reason); return { ...g, metadata: { ...g.metadata } }; }
+export function getMscafGenerationV2(id) { const g = _mscafGsV2.get(id); if (!g) return null; return { ...g, metadata: { ...g.metadata } }; }
+export function listMscafGenerationsV2() { return [..._mscafGsV2.values()].map((g) => ({ ...g, metadata: { ...g.metadata } })); }
+export function autoStaleIdleMscafProfilesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const p of _mscafPsV2.values()) if (p.status === MSCAF_PROFILE_MATURITY_V2.ACTIVE && (t - p.lastTouchedAt) >= _mscafIdleMs) { p.status = MSCAF_PROFILE_MATURITY_V2.STALE; p.updatedAt = t; flipped.push(p.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckMscafGenerationsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const g of _mscafGsV2.values()) if (g.status === MSCAF_GENERATION_LIFECYCLE_V2.GENERATING && g.startedAt != null && (t - g.startedAt) >= _mscafStuckMs) { g.status = MSCAF_GENERATION_LIFECYCLE_V2.FAILED; g.updatedAt = t; if (!g.settledAt) g.settledAt = t; g.metadata.failReason = "auto-fail-stuck"; flipped.push(g.id); } return { flipped, count: flipped.length }; }
+export function getMcpScaffoldGovStatsV2() {
+  const profilesByStatus = {}; for (const v of Object.values(MSCAF_PROFILE_MATURITY_V2)) profilesByStatus[v] = 0; for (const p of _mscafPsV2.values()) profilesByStatus[p.status]++;
+  const generationsByStatus = {}; for (const v of Object.values(MSCAF_GENERATION_LIFECYCLE_V2)) generationsByStatus[v] = 0; for (const g of _mscafGsV2.values()) generationsByStatus[g.status]++;
+  return { totalMscafProfilesV2: _mscafPsV2.size, totalMscafGenerationsV2: _mscafGsV2.size, maxActiveMscafProfilesPerOwner: _mscafMaxActive, maxPendingMscafGenerationsPerProfile: _mscafMaxPending, mscafProfileIdleMs: _mscafIdleMs, mscafGenerationStuckMs: _mscafStuckMs, profilesByStatus, generationsByStatus };
+}

package/src/lib/memory-injection.js

@@ -88,3 +88,84 @@ export function buildMemoryInjection(options = {}) {
   });
   return content ? { role: "system", content, count: memories.length } : null;
 }
+
+// ===== V2 Surface: Memory Injection governance overlay (CLI v0.142.0) =====
+export const MINJ_RULE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", PAUSED: "paused", ARCHIVED: "archived",
+});
+export const MINJ_INJECTION_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", INJECTING: "injecting", APPLIED: "applied", FAILED: "failed", CANCELLED: "cancelled",
+});
+const _minjRTrans = new Map([
+  [MINJ_RULE_MATURITY_V2.PENDING, new Set([MINJ_RULE_MATURITY_V2.ACTIVE, MINJ_RULE_MATURITY_V2.ARCHIVED])],
+  [MINJ_RULE_MATURITY_V2.ACTIVE, new Set([MINJ_RULE_MATURITY_V2.PAUSED, MINJ_RULE_MATURITY_V2.ARCHIVED])],
+  [MINJ_RULE_MATURITY_V2.PAUSED, new Set([MINJ_RULE_MATURITY_V2.ACTIVE, MINJ_RULE_MATURITY_V2.ARCHIVED])],
+  [MINJ_RULE_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _minjRTerminal = new Set([MINJ_RULE_MATURITY_V2.ARCHIVED]);
+const _minjITrans = new Map([
+  [MINJ_INJECTION_LIFECYCLE_V2.QUEUED, new Set([MINJ_INJECTION_LIFECYCLE_V2.INJECTING, MINJ_INJECTION_LIFECYCLE_V2.CANCELLED])],
+  [MINJ_INJECTION_LIFECYCLE_V2.INJECTING, new Set([MINJ_INJECTION_LIFECYCLE_V2.APPLIED, MINJ_INJECTION_LIFECYCLE_V2.FAILED, MINJ_INJECTION_LIFECYCLE_V2.CANCELLED])],
+  [MINJ_INJECTION_LIFECYCLE_V2.APPLIED, new Set()],
+  [MINJ_INJECTION_LIFECYCLE_V2.FAILED, new Set()],
+  [MINJ_INJECTION_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+const _minjRsV2 = new Map();
+const _minjIsV2 = new Map();
+let _minjMaxActive = 10, _minjMaxPending = 25, _minjIdleMs = 30 * 24 * 60 * 60 * 1000, _minjStuckMs = 30 * 1000;
+function _minjPos(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 _minjCheckR(from, to) { const a = _minjRTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid minj rule transition ${from} → ${to}`); }
+function _minjCheckI(from, to) { const a = _minjITrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid minj injection transition ${from} → ${to}`); }
+export function setMaxActiveMinjRulesPerOwnerV2(n) { _minjMaxActive = _minjPos(n, "maxActiveMinjRulesPerOwner"); }
+export function getMaxActiveMinjRulesPerOwnerV2() { return _minjMaxActive; }
+export function setMaxPendingMinjInjectionsPerRuleV2(n) { _minjMaxPending = _minjPos(n, "maxPendingMinjInjectionsPerRule"); }
+export function getMaxPendingMinjInjectionsPerRuleV2() { return _minjMaxPending; }
+export function setMinjRuleIdleMsV2(n) { _minjIdleMs = _minjPos(n, "minjRuleIdleMs"); }
+export function getMinjRuleIdleMsV2() { return _minjIdleMs; }
+export function setMinjInjectionStuckMsV2(n) { _minjStuckMs = _minjPos(n, "minjInjectionStuckMs"); }
+export function getMinjInjectionStuckMsV2() { return _minjStuckMs; }
+export function _resetStateMemoryInjectionV2() { _minjRsV2.clear(); _minjIsV2.clear(); _minjMaxActive = 10; _minjMaxPending = 25; _minjIdleMs = 30 * 24 * 60 * 60 * 1000; _minjStuckMs = 30 * 1000; }
+export function registerMinjRuleV2({ id, owner, scope, metadata } = {}) {
+  if (!id) throw new Error("minj rule id required"); if (!owner) throw new Error("minj rule owner required");
+  if (_minjRsV2.has(id)) throw new Error(`minj rule ${id} already registered`);
+  const now = Date.now();
+  const r = { id, owner, scope: scope || "*", status: MINJ_RULE_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, archivedAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _minjRsV2.set(id, r); return { ...r, metadata: { ...r.metadata } };
+}
+function _minjCountActive(owner) { let n = 0; for (const r of _minjRsV2.values()) if (r.owner === owner && r.status === MINJ_RULE_MATURITY_V2.ACTIVE) n++; return n; }
+export function activateMinjRuleV2(id) {
+  const r = _minjRsV2.get(id); if (!r) throw new Error(`minj rule ${id} not found`);
+  _minjCheckR(r.status, MINJ_RULE_MATURITY_V2.ACTIVE);
+  const recovery = r.status === MINJ_RULE_MATURITY_V2.PAUSED;
+  if (!recovery && _minjCountActive(r.owner) >= _minjMaxActive) throw new Error(`max active minj rules for owner ${r.owner} reached`);
+  const now = Date.now(); r.status = MINJ_RULE_MATURITY_V2.ACTIVE; r.updatedAt = now; r.lastTouchedAt = now; if (!r.activatedAt) r.activatedAt = now;
+  return { ...r, metadata: { ...r.metadata } };
+}
+export function pauseMinjRuleV2(id) { const r = _minjRsV2.get(id); if (!r) throw new Error(`minj rule ${id} not found`); _minjCheckR(r.status, MINJ_RULE_MATURITY_V2.PAUSED); r.status = MINJ_RULE_MATURITY_V2.PAUSED; r.updatedAt = Date.now(); return { ...r, metadata: { ...r.metadata } }; }
+export function archiveMinjRuleV2(id) { const r = _minjRsV2.get(id); if (!r) throw new Error(`minj rule ${id} not found`); _minjCheckR(r.status, MINJ_RULE_MATURITY_V2.ARCHIVED); const now = Date.now(); r.status = MINJ_RULE_MATURITY_V2.ARCHIVED; r.updatedAt = now; if (!r.archivedAt) r.archivedAt = now; return { ...r, metadata: { ...r.metadata } }; }
+export function touchMinjRuleV2(id) { const r = _minjRsV2.get(id); if (!r) throw new Error(`minj rule ${id} not found`); if (_minjRTerminal.has(r.status)) throw new Error(`cannot touch terminal minj rule ${id}`); const now = Date.now(); r.lastTouchedAt = now; r.updatedAt = now; return { ...r, metadata: { ...r.metadata } }; }
+export function getMinjRuleV2(id) { const r = _minjRsV2.get(id); if (!r) return null; return { ...r, metadata: { ...r.metadata } }; }
+export function listMinjRulesV2() { return [..._minjRsV2.values()].map((r) => ({ ...r, metadata: { ...r.metadata } })); }
+function _minjCountPending(ruleId) { let n = 0; for (const i of _minjIsV2.values()) if (i.ruleId === ruleId && (i.status === MINJ_INJECTION_LIFECYCLE_V2.QUEUED || i.status === MINJ_INJECTION_LIFECYCLE_V2.INJECTING)) n++; return n; }
+export function createMinjInjectionV2({ id, ruleId, payload, metadata } = {}) {
+  if (!id) throw new Error("minj injection id required"); if (!ruleId) throw new Error("minj injection ruleId required");
+  if (_minjIsV2.has(id)) throw new Error(`minj injection ${id} already exists`);
+  if (!_minjRsV2.has(ruleId)) throw new Error(`minj rule ${ruleId} not found`);
+  if (_minjCountPending(ruleId) >= _minjMaxPending) throw new Error(`max pending minj injections for rule ${ruleId} reached`);
+  const now = Date.now();
+  const i = { id, ruleId, payload: payload || "", status: MINJ_INJECTION_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _minjIsV2.set(id, i); return { ...i, metadata: { ...i.metadata } };
+}
+export function injectingMinjInjectionV2(id) { const i = _minjIsV2.get(id); if (!i) throw new Error(`minj injection ${id} not found`); _minjCheckI(i.status, MINJ_INJECTION_LIFECYCLE_V2.INJECTING); const now = Date.now(); i.status = MINJ_INJECTION_LIFECYCLE_V2.INJECTING; i.updatedAt = now; if (!i.startedAt) i.startedAt = now; return { ...i, metadata: { ...i.metadata } }; }
+export function applyMinjInjectionV2(id) { const i = _minjIsV2.get(id); if (!i) throw new Error(`minj injection ${id} not found`); _minjCheckI(i.status, MINJ_INJECTION_LIFECYCLE_V2.APPLIED); const now = Date.now(); i.status = MINJ_INJECTION_LIFECYCLE_V2.APPLIED; i.updatedAt = now; if (!i.settledAt) i.settledAt = now; return { ...i, metadata: { ...i.metadata } }; }
+export function failMinjInjectionV2(id, reason) { const i = _minjIsV2.get(id); if (!i) throw new Error(`minj injection ${id} not found`); _minjCheckI(i.status, MINJ_INJECTION_LIFECYCLE_V2.FAILED); const now = Date.now(); i.status = MINJ_INJECTION_LIFECYCLE_V2.FAILED; i.updatedAt = now; if (!i.settledAt) i.settledAt = now; if (reason) i.metadata.failReason = String(reason); return { ...i, metadata: { ...i.metadata } }; }
+export function cancelMinjInjectionV2(id, reason) { const i = _minjIsV2.get(id); if (!i) throw new Error(`minj injection ${id} not found`); _minjCheckI(i.status, MINJ_INJECTION_LIFECYCLE_V2.CANCELLED); const now = Date.now(); i.status = MINJ_INJECTION_LIFECYCLE_V2.CANCELLED; i.updatedAt = now; if (!i.settledAt) i.settledAt = now; if (reason) i.metadata.cancelReason = String(reason); return { ...i, metadata: { ...i.metadata } }; }
+export function getMinjInjectionV2(id) { const i = _minjIsV2.get(id); if (!i) return null; return { ...i, metadata: { ...i.metadata } }; }
+export function listMinjInjectionsV2() { return [..._minjIsV2.values()].map((i) => ({ ...i, metadata: { ...i.metadata } })); }
+export function autoPauseIdleMinjRulesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const r of _minjRsV2.values()) if (r.status === MINJ_RULE_MATURITY_V2.ACTIVE && (t - r.lastTouchedAt) >= _minjIdleMs) { r.status = MINJ_RULE_MATURITY_V2.PAUSED; r.updatedAt = t; flipped.push(r.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckMinjInjectionsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const i of _minjIsV2.values()) if (i.status === MINJ_INJECTION_LIFECYCLE_V2.INJECTING && i.startedAt != null && (t - i.startedAt) >= _minjStuckMs) { i.status = MINJ_INJECTION_LIFECYCLE_V2.FAILED; i.updatedAt = t; if (!i.settledAt) i.settledAt = t; i.metadata.failReason = "auto-fail-stuck"; flipped.push(i.id); } return { flipped, count: flipped.length }; }
+export function getMemoryInjectionGovStatsV2() {
+  const rulesByStatus = {}; for (const v of Object.values(MINJ_RULE_MATURITY_V2)) rulesByStatus[v] = 0; for (const r of _minjRsV2.values()) rulesByStatus[r.status]++;
+  const injectionsByStatus = {}; for (const v of Object.values(MINJ_INJECTION_LIFECYCLE_V2)) injectionsByStatus[v] = 0; for (const i of _minjIsV2.values()) injectionsByStatus[i.status]++;
+  return { totalMinjRulesV2: _minjRsV2.size, totalMinjInjectionsV2: _minjIsV2.size, maxActiveMinjRulesPerOwner: _minjMaxActive, maxPendingMinjInjectionsPerRule: _minjMaxPending, minjRuleIdleMs: _minjIdleMs, minjInjectionStuckMs: _minjStuckMs, rulesByStatus, injectionsByStatus };
+}