chainlesschain 0.132.0 → 0.143.0

package/src/lib/browser-automation.js

@@ -214,3 +214,108 @@ export async function takeScreenshot(url, outputPath, options = {}) {
     throw err;
   }
 }
+
+
+// ===== V2 Surface: Browser Automation governance overlay (CLI v0.134.0) =====
+export const BROWSE_TARGET_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", DEGRADED: "degraded", RETIRED: "retired",
+});
+export const BROWSE_ACTION_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", RUNNING: "running", COMPLETED: "completed", FAILED: "failed", CANCELLED: "cancelled",
+});
+
+const _brTargTrans = new Map([
+  [BROWSE_TARGET_MATURITY_V2.PENDING, new Set([BROWSE_TARGET_MATURITY_V2.ACTIVE, BROWSE_TARGET_MATURITY_V2.RETIRED])],
+  [BROWSE_TARGET_MATURITY_V2.ACTIVE, new Set([BROWSE_TARGET_MATURITY_V2.DEGRADED, BROWSE_TARGET_MATURITY_V2.RETIRED])],
+  [BROWSE_TARGET_MATURITY_V2.DEGRADED, new Set([BROWSE_TARGET_MATURITY_V2.ACTIVE, BROWSE_TARGET_MATURITY_V2.RETIRED])],
+  [BROWSE_TARGET_MATURITY_V2.RETIRED, new Set()],
+]);
+const _brTargTerminal = new Set([BROWSE_TARGET_MATURITY_V2.RETIRED]);
+const _brActTrans = new Map([
+  [BROWSE_ACTION_LIFECYCLE_V2.QUEUED, new Set([BROWSE_ACTION_LIFECYCLE_V2.RUNNING, BROWSE_ACTION_LIFECYCLE_V2.CANCELLED])],
+  [BROWSE_ACTION_LIFECYCLE_V2.RUNNING, new Set([BROWSE_ACTION_LIFECYCLE_V2.COMPLETED, BROWSE_ACTION_LIFECYCLE_V2.FAILED, BROWSE_ACTION_LIFECYCLE_V2.CANCELLED])],
+  [BROWSE_ACTION_LIFECYCLE_V2.COMPLETED, new Set()],
+  [BROWSE_ACTION_LIFECYCLE_V2.FAILED, new Set()],
+  [BROWSE_ACTION_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _brTargets = new Map();
+const _brActions = new Map();
+let _brMaxActivePerOwner = 8;
+let _brMaxPendingPerTarget = 20;
+let _brTargetIdleMs = 12 * 60 * 60 * 1000;
+let _brActionStuckMs = 3 * 60 * 1000;
+
+function _brPos(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 setMaxActiveBrowseTargetsPerOwnerV2(n) { _brMaxActivePerOwner = _brPos(n, "maxActiveBrowseTargetsPerOwner"); }
+export function getMaxActiveBrowseTargetsPerOwnerV2() { return _brMaxActivePerOwner; }
+export function setMaxPendingBrowseActionsPerTargetV2(n) { _brMaxPendingPerTarget = _brPos(n, "maxPendingBrowseActionsPerTarget"); }
+export function getMaxPendingBrowseActionsPerTargetV2() { return _brMaxPendingPerTarget; }
+export function setBrowseTargetIdleMsV2(n) { _brTargetIdleMs = _brPos(n, "browseTargetIdleMs"); }
+export function getBrowseTargetIdleMsV2() { return _brTargetIdleMs; }
+export function setBrowseActionStuckMsV2(n) { _brActionStuckMs = _brPos(n, "browseActionStuckMs"); }
+export function getBrowseActionStuckMsV2() { return _brActionStuckMs; }
+
+export function _resetStateBrowserAutomationV2() {
+  _brTargets.clear(); _brActions.clear();
+  _brMaxActivePerOwner = 8; _brMaxPendingPerTarget = 20;
+  _brTargetIdleMs = 12 * 60 * 60 * 1000; _brActionStuckMs = 3 * 60 * 1000;
+}
+
+export function registerBrowseTargetV2({ id, owner, url, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_brTargets.has(id)) throw new Error(`browse target ${id} already registered`);
+  const now = Date.now();
+  const t = { id, owner, url: url || "", status: BROWSE_TARGET_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, retiredAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _brTargets.set(id, t);
+  return { ...t, metadata: { ...t.metadata } };
+}
+function _brCheckT(from, to) { const a = _brTargTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid browse target transition ${from} → ${to}`); }
+function _brCountActive(owner) { let n = 0; for (const t of _brTargets.values()) if (t.owner === owner && t.status === BROWSE_TARGET_MATURITY_V2.ACTIVE) n++; return n; }
+
+export function activateBrowseTargetV2(id) {
+  const t = _brTargets.get(id); if (!t) throw new Error(`browse target ${id} not found`);
+  _brCheckT(t.status, BROWSE_TARGET_MATURITY_V2.ACTIVE);
+  const recovery = t.status === BROWSE_TARGET_MATURITY_V2.DEGRADED;
+  if (!recovery) { const a = _brCountActive(t.owner); if (a >= _brMaxActivePerOwner) throw new Error(`max active browse targets per owner (${_brMaxActivePerOwner}) reached for ${t.owner}`); }
+  const now = Date.now(); t.status = BROWSE_TARGET_MATURITY_V2.ACTIVE; t.updatedAt = now; t.lastTouchedAt = now; if (!t.activatedAt) t.activatedAt = now;
+  return { ...t, metadata: { ...t.metadata } };
+}
+export function degradeBrowseTargetV2(id) { const t = _brTargets.get(id); if (!t) throw new Error(`browse target ${id} not found`); _brCheckT(t.status, BROWSE_TARGET_MATURITY_V2.DEGRADED); t.status = BROWSE_TARGET_MATURITY_V2.DEGRADED; t.updatedAt = Date.now(); return { ...t, metadata: { ...t.metadata } }; }
+export function retireBrowseTargetV2(id) { const t = _brTargets.get(id); if (!t) throw new Error(`browse target ${id} not found`); _brCheckT(t.status, BROWSE_TARGET_MATURITY_V2.RETIRED); const now = Date.now(); t.status = BROWSE_TARGET_MATURITY_V2.RETIRED; t.updatedAt = now; if (!t.retiredAt) t.retiredAt = now; return { ...t, metadata: { ...t.metadata } }; }
+export function touchBrowseTargetV2(id) { const t = _brTargets.get(id); if (!t) throw new Error(`browse target ${id} not found`); if (_brTargTerminal.has(t.status)) throw new Error(`cannot touch terminal browse target ${id}`); const now = Date.now(); t.lastTouchedAt = now; t.updatedAt = now; return { ...t, metadata: { ...t.metadata } }; }
+export function getBrowseTargetV2(id) { const t = _brTargets.get(id); if (!t) return null; return { ...t, metadata: { ...t.metadata } }; }
+export function listBrowseTargetsV2() { return [..._brTargets.values()].map((t) => ({ ...t, metadata: { ...t.metadata } })); }
+
+function _brCountPending(tid) { let n = 0; for (const a of _brActions.values()) if (a.targetId === tid && (a.status === BROWSE_ACTION_LIFECYCLE_V2.QUEUED || a.status === BROWSE_ACTION_LIFECYCLE_V2.RUNNING)) n++; return n; }
+
+export function createBrowseActionV2({ id, targetId, kind, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!targetId || typeof targetId !== "string") throw new Error("targetId is required");
+  if (_brActions.has(id)) throw new Error(`browse action ${id} already exists`);
+  if (!_brTargets.has(targetId)) throw new Error(`browse target ${targetId} not found`);
+  const pending = _brCountPending(targetId);
+  if (pending >= _brMaxPendingPerTarget) throw new Error(`max pending browse actions per target (${_brMaxPendingPerTarget}) reached for ${targetId}`);
+  const now = Date.now();
+  const a = { id, targetId, kind: kind || "fetch", status: BROWSE_ACTION_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _brActions.set(id, a);
+  return { ...a, metadata: { ...a.metadata } };
+}
+function _brCheckA(from, to) { const al = _brActTrans.get(from); if (!al || !al.has(to)) throw new Error(`invalid browse action transition ${from} → ${to}`); }
+export function startBrowseActionV2(id) { const a = _brActions.get(id); if (!a) throw new Error(`browse action ${id} not found`); _brCheckA(a.status, BROWSE_ACTION_LIFECYCLE_V2.RUNNING); const now = Date.now(); a.status = BROWSE_ACTION_LIFECYCLE_V2.RUNNING; a.updatedAt = now; if (!a.startedAt) a.startedAt = now; return { ...a, metadata: { ...a.metadata } }; }
+export function completeBrowseActionV2(id) { const a = _brActions.get(id); if (!a) throw new Error(`browse action ${id} not found`); _brCheckA(a.status, BROWSE_ACTION_LIFECYCLE_V2.COMPLETED); const now = Date.now(); a.status = BROWSE_ACTION_LIFECYCLE_V2.COMPLETED; a.updatedAt = now; if (!a.settledAt) a.settledAt = now; return { ...a, metadata: { ...a.metadata } }; }
+export function failBrowseActionV2(id, reason) { const a = _brActions.get(id); if (!a) throw new Error(`browse action ${id} not found`); _brCheckA(a.status, BROWSE_ACTION_LIFECYCLE_V2.FAILED); const now = Date.now(); a.status = BROWSE_ACTION_LIFECYCLE_V2.FAILED; a.updatedAt = now; if (!a.settledAt) a.settledAt = now; if (reason) a.metadata.failReason = String(reason); return { ...a, metadata: { ...a.metadata } }; }
+export function cancelBrowseActionV2(id, reason) { const a = _brActions.get(id); if (!a) throw new Error(`browse action ${id} not found`); _brCheckA(a.status, BROWSE_ACTION_LIFECYCLE_V2.CANCELLED); const now = Date.now(); a.status = BROWSE_ACTION_LIFECYCLE_V2.CANCELLED; a.updatedAt = now; if (!a.settledAt) a.settledAt = now; if (reason) a.metadata.cancelReason = String(reason); return { ...a, metadata: { ...a.metadata } }; }
+export function getBrowseActionV2(id) { const a = _brActions.get(id); if (!a) return null; return { ...a, metadata: { ...a.metadata } }; }
+export function listBrowseActionsV2() { return [..._brActions.values()].map((a) => ({ ...a, metadata: { ...a.metadata } })); }
+
+export function autoDegradeIdleBrowseTargetsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const tg of _brTargets.values()) if (tg.status === BROWSE_TARGET_MATURITY_V2.ACTIVE && (t - tg.lastTouchedAt) >= _brTargetIdleMs) { tg.status = BROWSE_TARGET_MATURITY_V2.DEGRADED; tg.updatedAt = t; flipped.push(tg.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckBrowseActionsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const a of _brActions.values()) if (a.status === BROWSE_ACTION_LIFECYCLE_V2.RUNNING && a.startedAt != null && (t - a.startedAt) >= _brActionStuckMs) { a.status = BROWSE_ACTION_LIFECYCLE_V2.FAILED; a.updatedAt = t; if (!a.settledAt) a.settledAt = t; a.metadata.failReason = "auto-fail-stuck"; flipped.push(a.id); } return { flipped, count: flipped.length }; }
+
+export function getBrowserAutomationStatsV2() {
+  const targetsByStatus = {}; for (const s of Object.values(BROWSE_TARGET_MATURITY_V2)) targetsByStatus[s] = 0; for (const t of _brTargets.values()) targetsByStatus[t.status]++;
+  const actionsByStatus = {}; for (const s of Object.values(BROWSE_ACTION_LIFECYCLE_V2)) actionsByStatus[s] = 0; for (const a of _brActions.values()) actionsByStatus[a.status]++;
+  return { totalTargetsV2: _brTargets.size, totalActionsV2: _brActions.size, maxActiveBrowseTargetsPerOwner: _brMaxActivePerOwner, maxPendingBrowseActionsPerTarget: _brMaxPendingPerTarget, browseTargetIdleMs: _brTargetIdleMs, browseActionStuckMs: _brActionStuckMs, targetsByStatus, actionsByStatus };
+}

package/src/lib/compliance-framework-reporter.js

@@ -598,3 +598,108 @@ export function generateFrameworkReport(frameworkId, opts = {}) {
 export function _resetState() {
   _customTemplates.clear();
 }
+
+
+// ===== V2 Surface: Compliance Framework Reporter governance overlay (CLI v0.138.0) =====
+export const COMPLIANCE_FW_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", DEPRECATED: "deprecated", ARCHIVED: "archived",
+});
+export const COMPLIANCE_FW_REPORT_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", GENERATING: "generating", COMPLETED: "completed", FAILED: "failed", CANCELLED: "cancelled",
+});
+
+const _cfwTrans = new Map([
+  [COMPLIANCE_FW_MATURITY_V2.PENDING, new Set([COMPLIANCE_FW_MATURITY_V2.ACTIVE, COMPLIANCE_FW_MATURITY_V2.ARCHIVED])],
+  [COMPLIANCE_FW_MATURITY_V2.ACTIVE, new Set([COMPLIANCE_FW_MATURITY_V2.DEPRECATED, COMPLIANCE_FW_MATURITY_V2.ARCHIVED])],
+  [COMPLIANCE_FW_MATURITY_V2.DEPRECATED, new Set([COMPLIANCE_FW_MATURITY_V2.ACTIVE, COMPLIANCE_FW_MATURITY_V2.ARCHIVED])],
+  [COMPLIANCE_FW_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _cfwTerminal = new Set([COMPLIANCE_FW_MATURITY_V2.ARCHIVED]);
+const _cfwRepTrans = new Map([
+  [COMPLIANCE_FW_REPORT_LIFECYCLE_V2.QUEUED, new Set([COMPLIANCE_FW_REPORT_LIFECYCLE_V2.GENERATING, COMPLIANCE_FW_REPORT_LIFECYCLE_V2.CANCELLED])],
+  [COMPLIANCE_FW_REPORT_LIFECYCLE_V2.GENERATING, new Set([COMPLIANCE_FW_REPORT_LIFECYCLE_V2.COMPLETED, COMPLIANCE_FW_REPORT_LIFECYCLE_V2.FAILED, COMPLIANCE_FW_REPORT_LIFECYCLE_V2.CANCELLED])],
+  [COMPLIANCE_FW_REPORT_LIFECYCLE_V2.COMPLETED, new Set()],
+  [COMPLIANCE_FW_REPORT_LIFECYCLE_V2.FAILED, new Set()],
+  [COMPLIANCE_FW_REPORT_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _cfwsV2 = new Map();
+const _cfwReports = new Map();
+let _cfwMaxActivePerOwner = 8;
+let _cfwMaxPendingReportsPerFw = 15;
+let _cfwIdleMs = 90 * 24 * 60 * 60 * 1000;
+let _cfwReportStuckMs = 10 * 60 * 1000;
+
+function _cfwPos(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 setMaxActiveComplianceFwsPerOwnerV2(n) { _cfwMaxActivePerOwner = _cfwPos(n, "maxActiveComplianceFwsPerOwner"); }
+export function getMaxActiveComplianceFwsPerOwnerV2() { return _cfwMaxActivePerOwner; }
+export function setMaxPendingComplianceFwReportsPerFwV2(n) { _cfwMaxPendingReportsPerFw = _cfwPos(n, "maxPendingComplianceFwReportsPerFw"); }
+export function getMaxPendingComplianceFwReportsPerFwV2() { return _cfwMaxPendingReportsPerFw; }
+export function setComplianceFwIdleMsV2(n) { _cfwIdleMs = _cfwPos(n, "complianceFwIdleMs"); }
+export function getComplianceFwIdleMsV2() { return _cfwIdleMs; }
+export function setComplianceFwReportStuckMsV2(n) { _cfwReportStuckMs = _cfwPos(n, "complianceFwReportStuckMs"); }
+export function getComplianceFwReportStuckMsV2() { return _cfwReportStuckMs; }
+
+export function _resetStateComplianceFwReporterV2() {
+  _cfwsV2.clear(); _cfwReports.clear();
+  _cfwMaxActivePerOwner = 8; _cfwMaxPendingReportsPerFw = 15;
+  _cfwIdleMs = 90 * 24 * 60 * 60 * 1000; _cfwReportStuckMs = 10 * 60 * 1000;
+}
+
+export function registerComplianceFwV2({ 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 (_cfwsV2.has(id)) throw new Error(`compliance framework ${id} already registered`);
+  const now = Date.now();
+  const f = { id, owner, name: name || id, status: COMPLIANCE_FW_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, archivedAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _cfwsV2.set(id, f);
+  return { ...f, metadata: { ...f.metadata } };
+}
+function _cfwCheckF(from, to) { const a = _cfwTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid compliance framework transition ${from} → ${to}`); }
+function _cfwCountActive(owner) { let n = 0; for (const f of _cfwsV2.values()) if (f.owner === owner && f.status === COMPLIANCE_FW_MATURITY_V2.ACTIVE) n++; return n; }
+
+export function activateComplianceFwV2(id) {
+  const f = _cfwsV2.get(id); if (!f) throw new Error(`compliance framework ${id} not found`);
+  _cfwCheckF(f.status, COMPLIANCE_FW_MATURITY_V2.ACTIVE);
+  const recovery = f.status === COMPLIANCE_FW_MATURITY_V2.DEPRECATED;
+  if (!recovery) { const c = _cfwCountActive(f.owner); if (c >= _cfwMaxActivePerOwner) throw new Error(`max active compliance frameworks per owner (${_cfwMaxActivePerOwner}) reached for ${f.owner}`); }
+  const now = Date.now(); f.status = COMPLIANCE_FW_MATURITY_V2.ACTIVE; f.updatedAt = now; f.lastTouchedAt = now; if (!f.activatedAt) f.activatedAt = now;
+  return { ...f, metadata: { ...f.metadata } };
+}
+export function deprecateComplianceFwV2(id) { const f = _cfwsV2.get(id); if (!f) throw new Error(`compliance framework ${id} not found`); _cfwCheckF(f.status, COMPLIANCE_FW_MATURITY_V2.DEPRECATED); f.status = COMPLIANCE_FW_MATURITY_V2.DEPRECATED; f.updatedAt = Date.now(); return { ...f, metadata: { ...f.metadata } }; }
+export function archiveComplianceFwV2(id) { const f = _cfwsV2.get(id); if (!f) throw new Error(`compliance framework ${id} not found`); _cfwCheckF(f.status, COMPLIANCE_FW_MATURITY_V2.ARCHIVED); const now = Date.now(); f.status = COMPLIANCE_FW_MATURITY_V2.ARCHIVED; f.updatedAt = now; if (!f.archivedAt) f.archivedAt = now; return { ...f, metadata: { ...f.metadata } }; }
+export function touchComplianceFwV2(id) { const f = _cfwsV2.get(id); if (!f) throw new Error(`compliance framework ${id} not found`); if (_cfwTerminal.has(f.status)) throw new Error(`cannot touch terminal compliance framework ${id}`); const now = Date.now(); f.lastTouchedAt = now; f.updatedAt = now; return { ...f, metadata: { ...f.metadata } }; }
+export function getComplianceFwV2(id) { const f = _cfwsV2.get(id); if (!f) return null; return { ...f, metadata: { ...f.metadata } }; }
+export function listComplianceFwsV2() { return [..._cfwsV2.values()].map((f) => ({ ...f, metadata: { ...f.metadata } })); }
+
+function _cfwCountPendingReports(frameworkId) { let n = 0; for (const r of _cfwReports.values()) if (r.frameworkId === frameworkId && (r.status === COMPLIANCE_FW_REPORT_LIFECYCLE_V2.QUEUED || r.status === COMPLIANCE_FW_REPORT_LIFECYCLE_V2.GENERATING)) n++; return n; }
+
+export function createComplianceFwReportV2({ id, frameworkId, format, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!frameworkId || typeof frameworkId !== "string") throw new Error("frameworkId is required");
+  if (_cfwReports.has(id)) throw new Error(`compliance framework report ${id} already exists`);
+  if (!_cfwsV2.has(frameworkId)) throw new Error(`compliance framework ${frameworkId} not found`);
+  const pending = _cfwCountPendingReports(frameworkId);
+  if (pending >= _cfwMaxPendingReportsPerFw) throw new Error(`max pending compliance framework reports per framework (${_cfwMaxPendingReportsPerFw}) reached for ${frameworkId}`);
+  const now = Date.now();
+  const r = { id, frameworkId, format: format || "markdown", status: COMPLIANCE_FW_REPORT_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _cfwReports.set(id, r);
+  return { ...r, metadata: { ...r.metadata } };
+}
+function _cfwCheckR(from, to) { const a = _cfwRepTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid compliance framework report transition ${from} → ${to}`); }
+export function startComplianceFwReportV2(id) { const r = _cfwReports.get(id); if (!r) throw new Error(`compliance framework report ${id} not found`); _cfwCheckR(r.status, COMPLIANCE_FW_REPORT_LIFECYCLE_V2.GENERATING); const now = Date.now(); r.status = COMPLIANCE_FW_REPORT_LIFECYCLE_V2.GENERATING; r.updatedAt = now; if (!r.startedAt) r.startedAt = now; return { ...r, metadata: { ...r.metadata } }; }
+export function completeComplianceFwReportV2(id) { const r = _cfwReports.get(id); if (!r) throw new Error(`compliance framework report ${id} not found`); _cfwCheckR(r.status, COMPLIANCE_FW_REPORT_LIFECYCLE_V2.COMPLETED); const now = Date.now(); r.status = COMPLIANCE_FW_REPORT_LIFECYCLE_V2.COMPLETED; r.updatedAt = now; if (!r.settledAt) r.settledAt = now; return { ...r, metadata: { ...r.metadata } }; }
+export function failComplianceFwReportV2(id, reason) { const r = _cfwReports.get(id); if (!r) throw new Error(`compliance framework report ${id} not found`); _cfwCheckR(r.status, COMPLIANCE_FW_REPORT_LIFECYCLE_V2.FAILED); const now = Date.now(); r.status = COMPLIANCE_FW_REPORT_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 cancelComplianceFwReportV2(id, reason) { const r = _cfwReports.get(id); if (!r) throw new Error(`compliance framework report ${id} not found`); _cfwCheckR(r.status, COMPLIANCE_FW_REPORT_LIFECYCLE_V2.CANCELLED); const now = Date.now(); r.status = COMPLIANCE_FW_REPORT_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 getComplianceFwReportV2(id) { const r = _cfwReports.get(id); if (!r) return null; return { ...r, metadata: { ...r.metadata } }; }
+export function listComplianceFwReportsV2() { return [..._cfwReports.values()].map((r) => ({ ...r, metadata: { ...r.metadata } })); }
+
+export function autoDeprecateIdleComplianceFwsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const f of _cfwsV2.values()) if (f.status === COMPLIANCE_FW_MATURITY_V2.ACTIVE && (t - f.lastTouchedAt) >= _cfwIdleMs) { f.status = COMPLIANCE_FW_MATURITY_V2.DEPRECATED; f.updatedAt = t; flipped.push(f.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckComplianceFwReportsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const r of _cfwReports.values()) if (r.status === COMPLIANCE_FW_REPORT_LIFECYCLE_V2.GENERATING && r.startedAt != null && (t - r.startedAt) >= _cfwReportStuckMs) { r.status = COMPLIANCE_FW_REPORT_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 getComplianceFwReporterGovStatsV2() {
+  const fwsByStatus = {}; for (const s of Object.values(COMPLIANCE_FW_MATURITY_V2)) fwsByStatus[s] = 0; for (const f of _cfwsV2.values()) fwsByStatus[f.status]++;
+  const reportsByStatus = {}; for (const s of Object.values(COMPLIANCE_FW_REPORT_LIFECYCLE_V2)) reportsByStatus[s] = 0; for (const r of _cfwReports.values()) reportsByStatus[r.status]++;
+  return { totalComplianceFwsV2: _cfwsV2.size, totalComplianceFwReportsV2: _cfwReports.size, maxActiveComplianceFwsPerOwner: _cfwMaxActivePerOwner, maxPendingComplianceFwReportsPerFw: _cfwMaxPendingReportsPerFw, complianceFwIdleMs: _cfwIdleMs, complianceFwReportStuckMs: _cfwReportStuckMs, fwsByStatus, reportsByStatus };
+}

package/src/lib/compression-telemetry.js

@@ -3,3 +3,84 @@ export {
   getCompressionTelemetrySummary,
   resetCompressionTelemetry,
 } from "../harness/compression-telemetry.js";
+
+
+// =====================================================================
+// Compression Telemetry V2 governance overlay
+// =====================================================================
+export const COMPT_PROFILE_MATURITY_V2 = Object.freeze({ PENDING: "pending", ACTIVE: "active", STALE: "stale", ARCHIVED: "archived" });
+export const COMPT_SAMPLE_LIFECYCLE_V2 = Object.freeze({ QUEUED: "queued", RECORDING: "recording", RECORDED: "recorded", FAILED: "failed", CANCELLED: "cancelled" });
+const _comptPTrans = new Map([
+  [COMPT_PROFILE_MATURITY_V2.PENDING, new Set([COMPT_PROFILE_MATURITY_V2.ACTIVE, COMPT_PROFILE_MATURITY_V2.ARCHIVED])],
+  [COMPT_PROFILE_MATURITY_V2.ACTIVE, new Set([COMPT_PROFILE_MATURITY_V2.STALE, COMPT_PROFILE_MATURITY_V2.ARCHIVED])],
+  [COMPT_PROFILE_MATURITY_V2.STALE, new Set([COMPT_PROFILE_MATURITY_V2.ACTIVE, COMPT_PROFILE_MATURITY_V2.ARCHIVED])],
+  [COMPT_PROFILE_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _comptPTerminal = new Set([COMPT_PROFILE_MATURITY_V2.ARCHIVED]);
+const _comptJTrans = new Map([
+  [COMPT_SAMPLE_LIFECYCLE_V2.QUEUED, new Set([COMPT_SAMPLE_LIFECYCLE_V2.RECORDING, COMPT_SAMPLE_LIFECYCLE_V2.CANCELLED])],
+  [COMPT_SAMPLE_LIFECYCLE_V2.RECORDING, new Set([COMPT_SAMPLE_LIFECYCLE_V2.RECORDED, COMPT_SAMPLE_LIFECYCLE_V2.FAILED, COMPT_SAMPLE_LIFECYCLE_V2.CANCELLED])],
+  [COMPT_SAMPLE_LIFECYCLE_V2.RECORDED, new Set()],
+  [COMPT_SAMPLE_LIFECYCLE_V2.FAILED, new Set()],
+  [COMPT_SAMPLE_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+const _comptPsV2 = new Map();
+const _comptJsV2 = new Map();
+let _comptMaxActive = 10, _comptMaxPending = 30, _comptIdleMs = 30 * 24 * 60 * 60 * 1000, _comptStuckMs = 30 * 1000;
+function _comptPos(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 _comptCheckP(from, to) { const a = _comptPTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid compt profile transition ${from} → ${to}`); }
+function _comptCheckJ(from, to) { const a = _comptJTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid compt sample transition ${from} → ${to}`); }
+function _comptCountActive(owner) { let c = 0; for (const p of _comptPsV2.values()) if (p.owner === owner && p.status === COMPT_PROFILE_MATURITY_V2.ACTIVE) c++; return c; }
+function _comptCountPending(profileId) { let c = 0; for (const j of _comptJsV2.values()) if (j.profileId === profileId && (j.status === COMPT_SAMPLE_LIFECYCLE_V2.QUEUED || j.status === COMPT_SAMPLE_LIFECYCLE_V2.RECORDING)) c++; return c; }
+export function setMaxActiveComptProfilesPerOwnerV2(n) { _comptMaxActive = _comptPos(n, "maxActiveComptProfilesPerOwner"); }
+export function getMaxActiveComptProfilesPerOwnerV2() { return _comptMaxActive; }
+export function setMaxPendingComptSamplesPerProfileV2(n) { _comptMaxPending = _comptPos(n, "maxPendingComptSamplesPerProfile"); }
+export function getMaxPendingComptSamplesPerProfileV2() { return _comptMaxPending; }
+export function setComptProfileIdleMsV2(n) { _comptIdleMs = _comptPos(n, "comptProfileIdleMs"); }
+export function getComptProfileIdleMsV2() { return _comptIdleMs; }
+export function setComptSampleStuckMsV2(n) { _comptStuckMs = _comptPos(n, "comptSampleStuckMs"); }
+export function getComptSampleStuckMsV2() { return _comptStuckMs; }
+export function _resetStateCompressionTelemetryV2() { _comptPsV2.clear(); _comptJsV2.clear(); _comptMaxActive = 10; _comptMaxPending = 30; _comptIdleMs = 30 * 24 * 60 * 60 * 1000; _comptStuckMs = 30 * 1000; }
+export function registerComptProfileV2({ id, owner, kind, metadata } = {}) {
+  if (!id || !owner) throw new Error("id and owner required");
+  if (_comptPsV2.has(id)) throw new Error(`compt profile ${id} already exists`);
+  const now = Date.now();
+  const p = { id, owner, kind: kind || "default", status: COMPT_PROFILE_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, lastTouchedAt: now, activatedAt: null, archivedAt: null, metadata: { ...(metadata || {}) } };
+  _comptPsV2.set(id, p); return { ...p, metadata: { ...p.metadata } };
+}
+export function activateComptProfileV2(id) {
+  const p = _comptPsV2.get(id); if (!p) throw new Error(`compt profile ${id} not found`);
+  const isInitial = p.status === COMPT_PROFILE_MATURITY_V2.PENDING;
+  _comptCheckP(p.status, COMPT_PROFILE_MATURITY_V2.ACTIVE);
+  if (isInitial && _comptCountActive(p.owner) >= _comptMaxActive) throw new Error(`max active compt profiles for owner ${p.owner} reached`);
+  const now = Date.now(); p.status = COMPT_PROFILE_MATURITY_V2.ACTIVE; p.updatedAt = now; p.lastTouchedAt = now;
+  if (!p.activatedAt) p.activatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function staleComptProfileV2(id) { const p = _comptPsV2.get(id); if (!p) throw new Error(`compt profile ${id} not found`); _comptCheckP(p.status, COMPT_PROFILE_MATURITY_V2.STALE); p.status = COMPT_PROFILE_MATURITY_V2.STALE; p.updatedAt = Date.now(); return { ...p, metadata: { ...p.metadata } }; }
+export function archiveComptProfileV2(id) { const p = _comptPsV2.get(id); if (!p) throw new Error(`compt profile ${id} not found`); _comptCheckP(p.status, COMPT_PROFILE_MATURITY_V2.ARCHIVED); const now = Date.now(); p.status = COMPT_PROFILE_MATURITY_V2.ARCHIVED; p.updatedAt = now; if (!p.archivedAt) p.archivedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function touchComptProfileV2(id) { const p = _comptPsV2.get(id); if (!p) throw new Error(`compt profile ${id} not found`); if (_comptPTerminal.has(p.status)) throw new Error(`cannot touch terminal compt profile ${id}`); const now = Date.now(); p.lastTouchedAt = now; p.updatedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function getComptProfileV2(id) { const p = _comptPsV2.get(id); if (!p) return null; return { ...p, metadata: { ...p.metadata } }; }
+export function listComptProfilesV2() { return [..._comptPsV2.values()].map((p) => ({ ...p, metadata: { ...p.metadata } })); }
+export function createComptSampleV2({ id, profileId, metric, metadata } = {}) {
+  if (!id || !profileId) throw new Error("id and profileId required");
+  if (_comptJsV2.has(id)) throw new Error(`compt sample ${id} already exists`);
+  if (!_comptPsV2.has(profileId)) throw new Error(`compt profile ${profileId} not found`);
+  if (_comptCountPending(profileId) >= _comptMaxPending) throw new Error(`max pending compt samples for profile ${profileId} reached`);
+  const now = Date.now();
+  const j = { id, profileId, metric: metric || "", status: COMPT_SAMPLE_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _comptJsV2.set(id, j); return { ...j, metadata: { ...j.metadata } };
+}
+export function recordingComptSampleV2(id) { const j = _comptJsV2.get(id); if (!j) throw new Error(`compt sample ${id} not found`); _comptCheckJ(j.status, COMPT_SAMPLE_LIFECYCLE_V2.RECORDING); const now = Date.now(); j.status = COMPT_SAMPLE_LIFECYCLE_V2.RECORDING; j.updatedAt = now; if (!j.startedAt) j.startedAt = now; return { ...j, metadata: { ...j.metadata } }; }
+export function recordComptSampleV2(id) { const j = _comptJsV2.get(id); if (!j) throw new Error(`compt sample ${id} not found`); _comptCheckJ(j.status, COMPT_SAMPLE_LIFECYCLE_V2.RECORDED); const now = Date.now(); j.status = COMPT_SAMPLE_LIFECYCLE_V2.RECORDED; j.updatedAt = now; if (!j.settledAt) j.settledAt = now; return { ...j, metadata: { ...j.metadata } }; }
+export function failComptSampleV2(id, reason) { const j = _comptJsV2.get(id); if (!j) throw new Error(`compt sample ${id} not found`); _comptCheckJ(j.status, COMPT_SAMPLE_LIFECYCLE_V2.FAILED); const now = Date.now(); j.status = COMPT_SAMPLE_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 cancelComptSampleV2(id, reason) { const j = _comptJsV2.get(id); if (!j) throw new Error(`compt sample ${id} not found`); _comptCheckJ(j.status, COMPT_SAMPLE_LIFECYCLE_V2.CANCELLED); const now = Date.now(); j.status = COMPT_SAMPLE_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 getComptSampleV2(id) { const j = _comptJsV2.get(id); if (!j) return null; return { ...j, metadata: { ...j.metadata } }; }
+export function listComptSamplesV2() { return [..._comptJsV2.values()].map((j) => ({ ...j, metadata: { ...j.metadata } })); }
+export function autoStaleIdleComptProfilesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const p of _comptPsV2.values()) if (p.status === COMPT_PROFILE_MATURITY_V2.ACTIVE && (t - p.lastTouchedAt) >= _comptIdleMs) { p.status = COMPT_PROFILE_MATURITY_V2.STALE; p.updatedAt = t; flipped.push(p.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckComptSamplesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const j of _comptJsV2.values()) if (j.status === COMPT_SAMPLE_LIFECYCLE_V2.RECORDING && j.startedAt != null && (t - j.startedAt) >= _comptStuckMs) { j.status = COMPT_SAMPLE_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 getCompressionTelemetryGovStatsV2() {
+  const profilesByStatus = {}; for (const v of Object.values(COMPT_PROFILE_MATURITY_V2)) profilesByStatus[v] = 0; for (const p of _comptPsV2.values()) profilesByStatus[p.status]++;
+  const samplesByStatus = {}; for (const v of Object.values(COMPT_SAMPLE_LIFECYCLE_V2)) samplesByStatus[v] = 0; for (const j of _comptJsV2.values()) samplesByStatus[j.status]++;
+  return { totalComptProfilesV2: _comptPsV2.size, totalComptSamplesV2: _comptJsV2.size, maxActiveComptProfilesPerOwner: _comptMaxActive, maxPendingComptSamplesPerProfile: _comptMaxPending, comptProfileIdleMs: _comptIdleMs, comptSampleStuckMs: _comptStuckMs, profilesByStatus, samplesByStatus };
+}

package/src/lib/content-recommender.js

@@ -203,3 +203,108 @@ export class CLIContentRecommender {
     return matrix;
   }
 }
+
+
+// ===== V2 Surface: Content Recommender governance overlay (CLI v0.139.0) =====
+export const RECOMMENDER_PROFILE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", STALE: "stale", ARCHIVED: "archived",
+});
+export const RECOMMENDATION_JOB_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", RUNNING: "running", COMPLETED: "completed", FAILED: "failed", CANCELLED: "cancelled",
+});
+
+const _crpTrans = new Map([
+  [RECOMMENDER_PROFILE_MATURITY_V2.PENDING, new Set([RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE, RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED])],
+  [RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE, new Set([RECOMMENDER_PROFILE_MATURITY_V2.STALE, RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED])],
+  [RECOMMENDER_PROFILE_MATURITY_V2.STALE, new Set([RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE, RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED])],
+  [RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _crpTerminal = new Set([RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED]);
+const _crjTrans = new Map([
+  [RECOMMENDATION_JOB_LIFECYCLE_V2.QUEUED, new Set([RECOMMENDATION_JOB_LIFECYCLE_V2.RUNNING, RECOMMENDATION_JOB_LIFECYCLE_V2.CANCELLED])],
+  [RECOMMENDATION_JOB_LIFECYCLE_V2.RUNNING, new Set([RECOMMENDATION_JOB_LIFECYCLE_V2.COMPLETED, RECOMMENDATION_JOB_LIFECYCLE_V2.FAILED, RECOMMENDATION_JOB_LIFECYCLE_V2.CANCELLED])],
+  [RECOMMENDATION_JOB_LIFECYCLE_V2.COMPLETED, new Set()],
+  [RECOMMENDATION_JOB_LIFECYCLE_V2.FAILED, new Set()],
+  [RECOMMENDATION_JOB_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _crpsV2 = new Map();
+const _crjsV2 = new Map();
+let _crpMaxActivePerOwner = 8;
+let _crpMaxPendingJobsPerProfile = 10;
+let _crpIdleMs = 7 * 24 * 60 * 60 * 1000;
+let _crjStuckMs = 5 * 60 * 1000;
+
+function _crpPos(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 setMaxActiveRecommenderProfilesPerOwnerV2(n) { _crpMaxActivePerOwner = _crpPos(n, "maxActiveRecommenderProfilesPerOwner"); }
+export function getMaxActiveRecommenderProfilesPerOwnerV2() { return _crpMaxActivePerOwner; }
+export function setMaxPendingRecommendationJobsPerProfileV2(n) { _crpMaxPendingJobsPerProfile = _crpPos(n, "maxPendingRecommendationJobsPerProfile"); }
+export function getMaxPendingRecommendationJobsPerProfileV2() { return _crpMaxPendingJobsPerProfile; }
+export function setRecommenderProfileIdleMsV2(n) { _crpIdleMs = _crpPos(n, "recommenderProfileIdleMs"); }
+export function getRecommenderProfileIdleMsV2() { return _crpIdleMs; }
+export function setRecommendationJobStuckMsV2(n) { _crjStuckMs = _crpPos(n, "recommendationJobStuckMs"); }
+export function getRecommendationJobStuckMsV2() { return _crjStuckMs; }
+
+export function _resetStateContentRecommenderV2() {
+  _crpsV2.clear(); _crjsV2.clear();
+  _crpMaxActivePerOwner = 8; _crpMaxPendingJobsPerProfile = 10;
+  _crpIdleMs = 7 * 24 * 60 * 60 * 1000; _crjStuckMs = 5 * 60 * 1000;
+}
+
+export function registerRecommenderProfileV2({ id, owner, strategy, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_crpsV2.has(id)) throw new Error(`recommender profile ${id} already registered`);
+  const now = Date.now();
+  const p = { id, owner, strategy: strategy || "tfidf", status: RECOMMENDER_PROFILE_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, archivedAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _crpsV2.set(id, p);
+  return { ...p, metadata: { ...p.metadata } };
+}
+function _crpCheckP(from, to) { const a = _crpTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid recommender profile transition ${from} → ${to}`); }
+function _crpCountActive(owner) { let n = 0; for (const p of _crpsV2.values()) if (p.owner === owner && p.status === RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE) n++; return n; }
+
+export function activateRecommenderProfileV2(id) {
+  const p = _crpsV2.get(id); if (!p) throw new Error(`recommender profile ${id} not found`);
+  _crpCheckP(p.status, RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE);
+  const recovery = p.status === RECOMMENDER_PROFILE_MATURITY_V2.STALE;
+  if (!recovery) { const c = _crpCountActive(p.owner); if (c >= _crpMaxActivePerOwner) throw new Error(`max active recommender profiles per owner (${_crpMaxActivePerOwner}) reached for ${p.owner}`); }
+  const now = Date.now(); p.status = RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE; p.updatedAt = now; p.lastTouchedAt = now; if (!p.activatedAt) p.activatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function staleRecommenderProfileV2(id) { const p = _crpsV2.get(id); if (!p) throw new Error(`recommender profile ${id} not found`); _crpCheckP(p.status, RECOMMENDER_PROFILE_MATURITY_V2.STALE); p.status = RECOMMENDER_PROFILE_MATURITY_V2.STALE; p.updatedAt = Date.now(); return { ...p, metadata: { ...p.metadata } }; }
+export function archiveRecommenderProfileV2(id) { const p = _crpsV2.get(id); if (!p) throw new Error(`recommender profile ${id} not found`); _crpCheckP(p.status, RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED); const now = Date.now(); p.status = RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED; p.updatedAt = now; if (!p.archivedAt) p.archivedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function touchRecommenderProfileV2(id) { const p = _crpsV2.get(id); if (!p) throw new Error(`recommender profile ${id} not found`); if (_crpTerminal.has(p.status)) throw new Error(`cannot touch terminal recommender profile ${id}`); const now = Date.now(); p.lastTouchedAt = now; p.updatedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function getRecommenderProfileV2(id) { const p = _crpsV2.get(id); if (!p) return null; return { ...p, metadata: { ...p.metadata } }; }
+export function listRecommenderProfilesV2() { return [..._crpsV2.values()].map((p) => ({ ...p, metadata: { ...p.metadata } })); }
+
+function _crjCountPending(profileId) { let n = 0; for (const j of _crjsV2.values()) if (j.profileId === profileId && (j.status === RECOMMENDATION_JOB_LIFECYCLE_V2.QUEUED || j.status === RECOMMENDATION_JOB_LIFECYCLE_V2.RUNNING)) n++; return n; }
+
+export function createRecommendationJobV2({ id, profileId, query, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!profileId || typeof profileId !== "string") throw new Error("profileId is required");
+  if (_crjsV2.has(id)) throw new Error(`recommendation job ${id} already exists`);
+  if (!_crpsV2.has(profileId)) throw new Error(`recommender profile ${profileId} not found`);
+  const pending = _crjCountPending(profileId);
+  if (pending >= _crpMaxPendingJobsPerProfile) throw new Error(`max pending recommendation jobs per profile (${_crpMaxPendingJobsPerProfile}) reached for ${profileId}`);
+  const now = Date.now();
+  const j = { id, profileId, query: query || "", status: RECOMMENDATION_JOB_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _crjsV2.set(id, j);
+  return { ...j, metadata: { ...j.metadata } };
+}
+function _crjCheckJ(from, to) { const a = _crjTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid recommendation job transition ${from} → ${to}`); }
+export function startRecommendationJobV2(id) { const j = _crjsV2.get(id); if (!j) throw new Error(`recommendation job ${id} not found`); _crjCheckJ(j.status, RECOMMENDATION_JOB_LIFECYCLE_V2.RUNNING); const now = Date.now(); j.status = RECOMMENDATION_JOB_LIFECYCLE_V2.RUNNING; j.updatedAt = now; if (!j.startedAt) j.startedAt = now; return { ...j, metadata: { ...j.metadata } }; }
+export function completeRecommendationJobV2(id) { const j = _crjsV2.get(id); if (!j) throw new Error(`recommendation job ${id} not found`); _crjCheckJ(j.status, RECOMMENDATION_JOB_LIFECYCLE_V2.COMPLETED); const now = Date.now(); j.status = RECOMMENDATION_JOB_LIFECYCLE_V2.COMPLETED; j.updatedAt = now; if (!j.settledAt) j.settledAt = now; return { ...j, metadata: { ...j.metadata } }; }
+export function failRecommendationJobV2(id, reason) { const j = _crjsV2.get(id); if (!j) throw new Error(`recommendation job ${id} not found`); _crjCheckJ(j.status, RECOMMENDATION_JOB_LIFECYCLE_V2.FAILED); const now = Date.now(); j.status = RECOMMENDATION_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 cancelRecommendationJobV2(id, reason) { const j = _crjsV2.get(id); if (!j) throw new Error(`recommendation job ${id} not found`); _crjCheckJ(j.status, RECOMMENDATION_JOB_LIFECYCLE_V2.CANCELLED); const now = Date.now(); j.status = RECOMMENDATION_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 getRecommendationJobV2(id) { const j = _crjsV2.get(id); if (!j) return null; return { ...j, metadata: { ...j.metadata } }; }
+export function listRecommendationJobsV2() { return [..._crjsV2.values()].map((j) => ({ ...j, metadata: { ...j.metadata } })); }
+
+export function autoStaleIdleRecommenderProfilesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const p of _crpsV2.values()) if (p.status === RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE && (t - p.lastTouchedAt) >= _crpIdleMs) { p.status = RECOMMENDER_PROFILE_MATURITY_V2.STALE; p.updatedAt = t; flipped.push(p.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckRecommendationJobsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const j of _crjsV2.values()) if (j.status === RECOMMENDATION_JOB_LIFECYCLE_V2.RUNNING && j.startedAt != null && (t - j.startedAt) >= _crjStuckMs) { j.status = RECOMMENDATION_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 getContentRecommenderGovStatsV2() {
+  const profilesByStatus = {}; for (const s of Object.values(RECOMMENDER_PROFILE_MATURITY_V2)) profilesByStatus[s] = 0; for (const p of _crpsV2.values()) profilesByStatus[p.status]++;
+  const jobsByStatus = {}; for (const s of Object.values(RECOMMENDATION_JOB_LIFECYCLE_V2)) jobsByStatus[s] = 0; for (const j of _crjsV2.values()) jobsByStatus[j.status]++;
+  return { totalRecommenderProfilesV2: _crpsV2.size, totalRecommendationJobsV2: _crjsV2.size, maxActiveRecommenderProfilesPerOwner: _crpMaxActivePerOwner, maxPendingRecommendationJobsPerProfile: _crpMaxPendingJobsPerProfile, recommenderProfileIdleMs: _crpIdleMs, recommendationJobStuckMs: _crjStuckMs, profilesByStatus, jobsByStatus };
+}

package/src/lib/cowork-cron.js

@@ -472,3 +472,84 @@ function _minuteKey(date) {
 function _secondKey(date) {
   return `${_minuteKey(date)}-${date.getSeconds()}`;
 }
+
+
+// =====================================================================
+// Cowork Cron V2 governance overlay
+// =====================================================================
+export const CCRON_PROFILE_MATURITY_V2 = Object.freeze({ PENDING: "pending", ACTIVE: "active", PAUSED: "paused", ARCHIVED: "archived" });
+export const CCRON_TICK_LIFECYCLE_V2 = Object.freeze({ QUEUED: "queued", RUNNING: "running", COMPLETED: "completed", FAILED: "failed", CANCELLED: "cancelled" });
+const _ccronPTrans = new Map([
+  [CCRON_PROFILE_MATURITY_V2.PENDING, new Set([CCRON_PROFILE_MATURITY_V2.ACTIVE, CCRON_PROFILE_MATURITY_V2.ARCHIVED])],
+  [CCRON_PROFILE_MATURITY_V2.ACTIVE, new Set([CCRON_PROFILE_MATURITY_V2.PAUSED, CCRON_PROFILE_MATURITY_V2.ARCHIVED])],
+  [CCRON_PROFILE_MATURITY_V2.PAUSED, new Set([CCRON_PROFILE_MATURITY_V2.ACTIVE, CCRON_PROFILE_MATURITY_V2.ARCHIVED])],
+  [CCRON_PROFILE_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _ccronPTerminal = new Set([CCRON_PROFILE_MATURITY_V2.ARCHIVED]);
+const _ccronTTrans = new Map([
+  [CCRON_TICK_LIFECYCLE_V2.QUEUED, new Set([CCRON_TICK_LIFECYCLE_V2.RUNNING, CCRON_TICK_LIFECYCLE_V2.CANCELLED])],
+  [CCRON_TICK_LIFECYCLE_V2.RUNNING, new Set([CCRON_TICK_LIFECYCLE_V2.COMPLETED, CCRON_TICK_LIFECYCLE_V2.FAILED, CCRON_TICK_LIFECYCLE_V2.CANCELLED])],
+  [CCRON_TICK_LIFECYCLE_V2.COMPLETED, new Set()],
+  [CCRON_TICK_LIFECYCLE_V2.FAILED, new Set()],
+  [CCRON_TICK_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+const _ccronPsV2 = new Map();
+const _ccronTsV2 = new Map();
+let _ccronMaxActive = 6, _ccronMaxPending = 15, _ccronIdleMs = 30 * 24 * 60 * 60 * 1000, _ccronStuckMs = 60 * 1000;
+function _ccronPos(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 _ccronCheckP(from, to) { const a = _ccronPTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid ccron profile transition ${from} → ${to}`); }
+function _ccronCheckT(from, to) { const a = _ccronTTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid ccron tick transition ${from} → ${to}`); }
+function _ccronCountActive(owner) { let c = 0; for (const p of _ccronPsV2.values()) if (p.owner === owner && p.status === CCRON_PROFILE_MATURITY_V2.ACTIVE) c++; return c; }
+function _ccronCountPending(profileId) { let c = 0; for (const t of _ccronTsV2.values()) if (t.profileId === profileId && (t.status === CCRON_TICK_LIFECYCLE_V2.QUEUED || t.status === CCRON_TICK_LIFECYCLE_V2.RUNNING)) c++; return c; }
+export function setMaxActiveCcronProfilesPerOwnerV2(n) { _ccronMaxActive = _ccronPos(n, "maxActiveCcronProfilesPerOwner"); }
+export function getMaxActiveCcronProfilesPerOwnerV2() { return _ccronMaxActive; }
+export function setMaxPendingCcronTicksPerProfileV2(n) { _ccronMaxPending = _ccronPos(n, "maxPendingCcronTicksPerProfile"); }
+export function getMaxPendingCcronTicksPerProfileV2() { return _ccronMaxPending; }
+export function setCcronProfileIdleMsV2(n) { _ccronIdleMs = _ccronPos(n, "ccronProfileIdleMs"); }
+export function getCcronProfileIdleMsV2() { return _ccronIdleMs; }
+export function setCcronTickStuckMsV2(n) { _ccronStuckMs = _ccronPos(n, "ccronTickStuckMs"); }
+export function getCcronTickStuckMsV2() { return _ccronStuckMs; }
+export function _resetStateCoworkCronV2() { _ccronPsV2.clear(); _ccronTsV2.clear(); _ccronMaxActive = 6; _ccronMaxPending = 15; _ccronIdleMs = 30 * 24 * 60 * 60 * 1000; _ccronStuckMs = 60 * 1000; }
+export function registerCcronProfileV2({ id, owner, expr, metadata } = {}) {
+  if (!id || !owner) throw new Error("id and owner required");
+  if (_ccronPsV2.has(id)) throw new Error(`ccron profile ${id} already exists`);
+  const now = Date.now();
+  const p = { id, owner, expr: expr || "0 0 * * *", status: CCRON_PROFILE_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, lastTouchedAt: now, activatedAt: null, archivedAt: null, metadata: { ...(metadata || {}) } };
+  _ccronPsV2.set(id, p); return { ...p, metadata: { ...p.metadata } };
+}
+export function activateCcronProfileV2(id) {
+  const p = _ccronPsV2.get(id); if (!p) throw new Error(`ccron profile ${id} not found`);
+  const isInitial = p.status === CCRON_PROFILE_MATURITY_V2.PENDING;
+  _ccronCheckP(p.status, CCRON_PROFILE_MATURITY_V2.ACTIVE);
+  if (isInitial && _ccronCountActive(p.owner) >= _ccronMaxActive) throw new Error(`max active ccron profiles for owner ${p.owner} reached`);
+  const now = Date.now(); p.status = CCRON_PROFILE_MATURITY_V2.ACTIVE; p.updatedAt = now; p.lastTouchedAt = now;
+  if (!p.activatedAt) p.activatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function pauseCcronProfileV2(id) { const p = _ccronPsV2.get(id); if (!p) throw new Error(`ccron profile ${id} not found`); _ccronCheckP(p.status, CCRON_PROFILE_MATURITY_V2.PAUSED); p.status = CCRON_PROFILE_MATURITY_V2.PAUSED; p.updatedAt = Date.now(); return { ...p, metadata: { ...p.metadata } }; }
+export function archiveCcronProfileV2(id) { const p = _ccronPsV2.get(id); if (!p) throw new Error(`ccron profile ${id} not found`); _ccronCheckP(p.status, CCRON_PROFILE_MATURITY_V2.ARCHIVED); const now = Date.now(); p.status = CCRON_PROFILE_MATURITY_V2.ARCHIVED; p.updatedAt = now; if (!p.archivedAt) p.archivedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function touchCcronProfileV2(id) { const p = _ccronPsV2.get(id); if (!p) throw new Error(`ccron profile ${id} not found`); if (_ccronPTerminal.has(p.status)) throw new Error(`cannot touch terminal ccron profile ${id}`); const now = Date.now(); p.lastTouchedAt = now; p.updatedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function getCcronProfileV2(id) { const p = _ccronPsV2.get(id); if (!p) return null; return { ...p, metadata: { ...p.metadata } }; }
+export function listCcronProfilesV2() { return [..._ccronPsV2.values()].map((p) => ({ ...p, metadata: { ...p.metadata } })); }
+export function createCcronTickV2({ id, profileId, tickAt, metadata } = {}) {
+  if (!id || !profileId) throw new Error("id and profileId required");
+  if (_ccronTsV2.has(id)) throw new Error(`ccron tick ${id} already exists`);
+  if (!_ccronPsV2.has(profileId)) throw new Error(`ccron profile ${profileId} not found`);
+  if (_ccronCountPending(profileId) >= _ccronMaxPending) throw new Error(`max pending ccron ticks for profile ${profileId} reached`);
+  const now = Date.now();
+  const t = { id, profileId, tickAt: tickAt || now, status: CCRON_TICK_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _ccronTsV2.set(id, t); return { ...t, metadata: { ...t.metadata } };
+}
+export function runningCcronTickV2(id) { const t = _ccronTsV2.get(id); if (!t) throw new Error(`ccron tick ${id} not found`); _ccronCheckT(t.status, CCRON_TICK_LIFECYCLE_V2.RUNNING); const now = Date.now(); t.status = CCRON_TICK_LIFECYCLE_V2.RUNNING; t.updatedAt = now; if (!t.startedAt) t.startedAt = now; return { ...t, metadata: { ...t.metadata } }; }
+export function completeCcronTickV2(id) { const t = _ccronTsV2.get(id); if (!t) throw new Error(`ccron tick ${id} not found`); _ccronCheckT(t.status, CCRON_TICK_LIFECYCLE_V2.COMPLETED); const now = Date.now(); t.status = CCRON_TICK_LIFECYCLE_V2.COMPLETED; t.updatedAt = now; if (!t.settledAt) t.settledAt = now; return { ...t, metadata: { ...t.metadata } }; }
+export function failCcronTickV2(id, reason) { const t = _ccronTsV2.get(id); if (!t) throw new Error(`ccron tick ${id} not found`); _ccronCheckT(t.status, CCRON_TICK_LIFECYCLE_V2.FAILED); const now = Date.now(); t.status = CCRON_TICK_LIFECYCLE_V2.FAILED; t.updatedAt = now; if (!t.settledAt) t.settledAt = now; if (reason) t.metadata.failReason = String(reason); return { ...t, metadata: { ...t.metadata } }; }
+export function cancelCcronTickV2(id, reason) { const t = _ccronTsV2.get(id); if (!t) throw new Error(`ccron tick ${id} not found`); _ccronCheckT(t.status, CCRON_TICK_LIFECYCLE_V2.CANCELLED); const now = Date.now(); t.status = CCRON_TICK_LIFECYCLE_V2.CANCELLED; t.updatedAt = now; if (!t.settledAt) t.settledAt = now; if (reason) t.metadata.cancelReason = String(reason); return { ...t, metadata: { ...t.metadata } }; }
+export function getCcronTickV2(id) { const t = _ccronTsV2.get(id); if (!t) return null; return { ...t, metadata: { ...t.metadata } }; }
+export function listCcronTicksV2() { return [..._ccronTsV2.values()].map((t) => ({ ...t, metadata: { ...t.metadata } })); }
+export function autoPauseIdleCcronProfilesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const p of _ccronPsV2.values()) if (p.status === CCRON_PROFILE_MATURITY_V2.ACTIVE && (t - p.lastTouchedAt) >= _ccronIdleMs) { p.status = CCRON_PROFILE_MATURITY_V2.PAUSED; p.updatedAt = t; flipped.push(p.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckCcronTicksV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const x of _ccronTsV2.values()) if (x.status === CCRON_TICK_LIFECYCLE_V2.RUNNING && x.startedAt != null && (t - x.startedAt) >= _ccronStuckMs) { x.status = CCRON_TICK_LIFECYCLE_V2.FAILED; x.updatedAt = t; if (!x.settledAt) x.settledAt = t; x.metadata.failReason = "auto-fail-stuck"; flipped.push(x.id); } return { flipped, count: flipped.length }; }
+export function getCoworkCronGovStatsV2() {
+  const profilesByStatus = {}; for (const v of Object.values(CCRON_PROFILE_MATURITY_V2)) profilesByStatus[v] = 0; for (const p of _ccronPsV2.values()) profilesByStatus[p.status]++;
+  const ticksByStatus = {}; for (const v of Object.values(CCRON_TICK_LIFECYCLE_V2)) ticksByStatus[v] = 0; for (const t of _ccronTsV2.values()) ticksByStatus[t.status]++;
+  return { totalCcronProfilesV2: _ccronPsV2.size, totalCcronTicksV2: _ccronTsV2.size, maxActiveCcronProfilesPerOwner: _ccronMaxActive, maxPendingCcronTicksPerProfile: _ccronMaxPending, ccronProfileIdleMs: _ccronIdleMs, ccronTickStuckMs: _ccronStuckMs, profilesByStatus, ticksByStatus };
+}