chainlesschain 0.81.0 → 0.143.0

package/src/lib/community-governance.js

@@ -647,3 +647,439 @@ export function _resetState() {
   _proposalVotes.clear();
   _seq = 0;
 }
+
+/* ═══════════════════════════════════════════════════════════════
+ * Phase 54 V2 — Proposer Maturity + Vote Delegation Lifecycle
+ * Strictly additive. Legacy surface above is preserved.
+ * ═════════════════════════════════════════════════════════════ */
+
+export const PROPOSER_MATURITY_V2 = Object.freeze({
+  ONBOARDING: "onboarding",
+  ACTIVE: "active",
+  SUSPENDED: "suspended",
+  RETIRED: "retired",
+});
+
+export const DELEGATION_LIFECYCLE_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  REVOKED: "revoked",
+  EXPIRED: "expired",
+});
+
+const PROPOSER_TRANSITIONS_V2 = new Map([
+  ["onboarding", new Set(["active", "retired"])],
+  ["active", new Set(["suspended", "retired"])],
+  ["suspended", new Set(["active", "retired"])],
+]);
+const PROPOSER_TERMINALS_V2 = new Set(["retired"]);
+
+const DELEGATION_TRANSITIONS_V2 = new Map([
+  ["pending", new Set(["active", "revoked", "expired"])],
+  ["active", new Set(["revoked", "expired"])],
+]);
+const DELEGATION_TERMINALS_V2 = new Set(["revoked", "expired"]);
+
+export const GOV_DEFAULT_MAX_ACTIVE_PROPOSERS_PER_REALM = 100;
+export const GOV_DEFAULT_MAX_ACTIVE_DELEGATIONS_PER_DELEGATOR = 5;
+export const GOV_DEFAULT_PROPOSER_IDLE_MS = 180 * 86400000; // 180 days
+export const GOV_DEFAULT_PENDING_DELEGATION_MS = 7 * 86400000; // 7 days
+
+let _maxActiveProposersPerRealmV2 = GOV_DEFAULT_MAX_ACTIVE_PROPOSERS_PER_REALM;
+let _maxActiveDelegationsPerDelegatorV2 =
+  GOV_DEFAULT_MAX_ACTIVE_DELEGATIONS_PER_DELEGATOR;
+let _proposerIdleMsV2 = GOV_DEFAULT_PROPOSER_IDLE_MS;
+let _pendingDelegationMsV2 = GOV_DEFAULT_PENDING_DELEGATION_MS;
+
+const _proposerStatesV2 = new Map(); // proposerId → V2 record
+const _delegationStatesV2 = new Map(); // delegationId → V2 record
+
+function _positiveIntV2(n, label) {
+  const num = Number(n);
+  if (!Number.isFinite(num) || num <= 0) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return Math.floor(num);
+}
+
+function _validProposerStatusV2(s) {
+  return (
+    s === "onboarding" || s === "active" || s === "suspended" || s === "retired"
+  );
+}
+
+function _validDelegationStatusV2(s) {
+  return (
+    s === "pending" || s === "active" || s === "revoked" || s === "expired"
+  );
+}
+
+export function getDefaultMaxActiveProposersPerRealmV2() {
+  return GOV_DEFAULT_MAX_ACTIVE_PROPOSERS_PER_REALM;
+}
+export function getMaxActiveProposersPerRealmV2() {
+  return _maxActiveProposersPerRealmV2;
+}
+export function setMaxActiveProposersPerRealmV2(n) {
+  _maxActiveProposersPerRealmV2 = _positiveIntV2(
+    n,
+    "maxActiveProposersPerRealm",
+  );
+  return _maxActiveProposersPerRealmV2;
+}
+
+export function getDefaultMaxActiveDelegationsPerDelegatorV2() {
+  return GOV_DEFAULT_MAX_ACTIVE_DELEGATIONS_PER_DELEGATOR;
+}
+export function getMaxActiveDelegationsPerDelegatorV2() {
+  return _maxActiveDelegationsPerDelegatorV2;
+}
+export function setMaxActiveDelegationsPerDelegatorV2(n) {
+  _maxActiveDelegationsPerDelegatorV2 = _positiveIntV2(
+    n,
+    "maxActiveDelegationsPerDelegator",
+  );
+  return _maxActiveDelegationsPerDelegatorV2;
+}
+
+export function getDefaultProposerIdleMsV2() {
+  return GOV_DEFAULT_PROPOSER_IDLE_MS;
+}
+export function getProposerIdleMsV2() {
+  return _proposerIdleMsV2;
+}
+export function setProposerIdleMsV2(ms) {
+  _proposerIdleMsV2 = _positiveIntV2(ms, "proposerIdleMs");
+  return _proposerIdleMsV2;
+}
+
+export function getDefaultPendingDelegationMsV2() {
+  return GOV_DEFAULT_PENDING_DELEGATION_MS;
+}
+export function getPendingDelegationMsV2() {
+  return _pendingDelegationMsV2;
+}
+export function setPendingDelegationMsV2(ms) {
+  _pendingDelegationMsV2 = _positiveIntV2(ms, "pendingDelegationMs");
+  return _pendingDelegationMsV2;
+}
+
+/* ── Proposer V2 ────────────────────────────────────────────── */
+
+export function registerProposerV2(db, config = {}) {
+  void db;
+  const proposerId = String(config.proposerId || "").trim();
+  if (!proposerId) throw new Error("proposerId is required");
+  const realm = String(config.realm || "").trim();
+  if (!realm) throw new Error("realm is required");
+  if (_proposerStatesV2.has(proposerId)) {
+    throw new Error(`Proposer already registered in V2: ${proposerId}`);
+  }
+
+  const now = Number(config.now ?? Date.now());
+  const initialStatus = config.initialStatus || "onboarding";
+  if (!_validProposerStatusV2(initialStatus)) {
+    throw new Error(`Invalid initial status: ${initialStatus}`);
+  }
+  if (PROPOSER_TERMINALS_V2.has(initialStatus)) {
+    throw new Error(
+      `Cannot register proposer in terminal status '${initialStatus}'`,
+    );
+  }
+
+  if (initialStatus === "active") {
+    let activeCount = 0;
+    for (const rec of _proposerStatesV2.values()) {
+      if (rec.realm === realm && rec.status === "active") activeCount += 1;
+    }
+    if (activeCount >= _maxActiveProposersPerRealmV2) {
+      throw new Error(
+        `Max active proposers per realm reached (${_maxActiveProposersPerRealmV2})`,
+      );
+    }
+  }
+
+  const record = {
+    proposerId,
+    realm,
+    displayName: config.displayName ? String(config.displayName) : null,
+    status: initialStatus,
+    metadata: config.metadata ? { ...config.metadata } : {},
+    createdAt: now,
+    updatedAt: now,
+    lastActivityAt: now,
+    reason: null,
+  };
+  _proposerStatesV2.set(proposerId, record);
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getProposerV2(proposerId) {
+  const rec = _proposerStatesV2.get(String(proposerId || ""));
+  if (!rec) return null;
+  return { ...rec, metadata: { ...rec.metadata } };
+}
+
+export function setProposerMaturityV2(db, proposerId, newStatus, patch = {}) {
+  void db;
+  const id = String(proposerId || "");
+  const record = _proposerStatesV2.get(id);
+  if (!record) throw new Error(`Proposer not registered in V2: ${id}`);
+  if (!_validProposerStatusV2(newStatus)) {
+    throw new Error(`Invalid proposer status: ${newStatus}`);
+  }
+  if (PROPOSER_TERMINALS_V2.has(record.status)) {
+    throw new Error(
+      `Proposer is in terminal status '${record.status}' and cannot transition`,
+    );
+  }
+  const allowed = PROPOSER_TRANSITIONS_V2.get(record.status);
+  if (!allowed || !allowed.has(newStatus)) {
+    throw new Error(`Invalid transition: ${record.status} → ${newStatus}`);
+  }
+
+  if (newStatus === "active" && record.status !== "active") {
+    let activeCount = 0;
+    for (const rec of _proposerStatesV2.values()) {
+      if (rec.realm === record.realm && rec.status === "active") {
+        activeCount += 1;
+      }
+    }
+    if (activeCount >= _maxActiveProposersPerRealmV2) {
+      throw new Error(
+        `Max active proposers per realm reached (${_maxActiveProposersPerRealmV2})`,
+      );
+    }
+  }
+
+  record.status = newStatus;
+  record.updatedAt = Number(patch.now ?? Date.now());
+  if (patch.reason !== undefined) record.reason = patch.reason;
+  if (patch.metadata && typeof patch.metadata === "object") {
+    record.metadata = { ...record.metadata, ...patch.metadata };
+  }
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function activateProposer(db, proposerId, reason) {
+  return setProposerMaturityV2(db, proposerId, "active", { reason });
+}
+export function suspendProposer(db, proposerId, reason) {
+  return setProposerMaturityV2(db, proposerId, "suspended", { reason });
+}
+export function retireProposer(db, proposerId, reason) {
+  return setProposerMaturityV2(db, proposerId, "retired", { reason });
+}
+
+export function touchProposerActivity(proposerId) {
+  const rec = _proposerStatesV2.get(String(proposerId || ""));
+  if (!rec) throw new Error(`Proposer not registered in V2: ${proposerId}`);
+  rec.lastActivityAt = Date.now();
+  return { ...rec, metadata: { ...rec.metadata } };
+}
+
+/* ── Delegation V2 ──────────────────────────────────────────── */
+
+export function createDelegationV2(db, config = {}) {
+  void db;
+  const delegationId = String(config.delegationId || "").trim();
+  if (!delegationId) throw new Error("delegationId is required");
+  const delegatorId = String(config.delegatorId || "").trim();
+  if (!delegatorId) throw new Error("delegatorId is required");
+  const delegateeId = String(config.delegateeId || "").trim();
+  if (!delegateeId) throw new Error("delegateeId is required");
+  if (delegatorId === delegateeId) {
+    throw new Error("delegatorId and delegateeId must differ");
+  }
+  const scope = String(config.scope || "").trim();
+  if (!scope) throw new Error("scope is required");
+
+  if (_delegationStatesV2.has(delegationId)) {
+    throw new Error(`Delegation already registered in V2: ${delegationId}`);
+  }
+
+  let openCount = 0;
+  for (const rec of _delegationStatesV2.values()) {
+    if (
+      rec.delegatorId === delegatorId &&
+      !DELEGATION_TERMINALS_V2.has(rec.status)
+    ) {
+      openCount += 1;
+    }
+  }
+  if (openCount >= _maxActiveDelegationsPerDelegatorV2) {
+    throw new Error(
+      `Max active delegations per delegator reached (${_maxActiveDelegationsPerDelegatorV2})`,
+    );
+  }
+
+  const now = Number(config.now ?? Date.now());
+  const record = {
+    delegationId,
+    delegatorId,
+    delegateeId,
+    scope,
+    status: "pending",
+    metadata: config.metadata ? { ...config.metadata } : {},
+    createdAt: now,
+    updatedAt: now,
+    activatedAt: null,
+    expiresAt: config.expiresAt ? Number(config.expiresAt) : null,
+    reason: null,
+  };
+  _delegationStatesV2.set(delegationId, record);
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getDelegationV2(delegationId) {
+  const rec = _delegationStatesV2.get(String(delegationId || ""));
+  if (!rec) return null;
+  return { ...rec, metadata: { ...rec.metadata } };
+}
+
+export function setDelegationStatusV2(db, delegationId, newStatus, patch = {}) {
+  void db;
+  const id = String(delegationId || "");
+  const record = _delegationStatesV2.get(id);
+  if (!record) throw new Error(`Delegation not registered in V2: ${id}`);
+  if (!_validDelegationStatusV2(newStatus)) {
+    throw new Error(`Invalid delegation status: ${newStatus}`);
+  }
+  if (DELEGATION_TERMINALS_V2.has(record.status)) {
+    throw new Error(
+      `Delegation is in terminal status '${record.status}' and cannot transition`,
+    );
+  }
+  const allowed = DELEGATION_TRANSITIONS_V2.get(record.status);
+  if (!allowed || !allowed.has(newStatus)) {
+    throw new Error(`Invalid transition: ${record.status} → ${newStatus}`);
+  }
+  const now = Number(patch.now ?? Date.now());
+  record.status = newStatus;
+  record.updatedAt = now;
+  if (newStatus === "active" && record.activatedAt === null) {
+    record.activatedAt = now;
+  }
+  if (patch.reason !== undefined) record.reason = patch.reason;
+  if (patch.metadata && typeof patch.metadata === "object") {
+    record.metadata = { ...record.metadata, ...patch.metadata };
+  }
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function activateDelegation(db, delegationId, reason) {
+  return setDelegationStatusV2(db, delegationId, "active", { reason });
+}
+export function revokeDelegation(db, delegationId, reason) {
+  return setDelegationStatusV2(db, delegationId, "revoked", { reason });
+}
+export function expireDelegation(db, delegationId, reason) {
+  return setDelegationStatusV2(db, delegationId, "expired", { reason });
+}
+
+/* ── Counts ─────────────────────────────────────────────────── */
+
+export function getActiveProposerCount(realm) {
+  let n = 0;
+  for (const rec of _proposerStatesV2.values()) {
+    if (rec.status !== "active") continue;
+    if (realm !== undefined && rec.realm !== String(realm)) continue;
+    n += 1;
+  }
+  return n;
+}
+
+export function getActiveDelegationCount(delegatorId) {
+  let n = 0;
+  for (const rec of _delegationStatesV2.values()) {
+    if (DELEGATION_TERMINALS_V2.has(rec.status)) continue;
+    if (delegatorId !== undefined && rec.delegatorId !== String(delegatorId)) {
+      continue;
+    }
+    n += 1;
+  }
+  return n;
+}
+
+/* ── Auto-flip Bulk Ops ─────────────────────────────────────── */
+
+export function autoRetireIdleProposers(db, nowMs) {
+  void db;
+  const now = Number(nowMs ?? Date.now());
+  const flipped = [];
+  for (const rec of _proposerStatesV2.values()) {
+    if (rec.status !== "active" && rec.status !== "suspended") continue;
+    if (now - rec.lastActivityAt > _proposerIdleMsV2) {
+      rec.status = "retired";
+      rec.updatedAt = now;
+      rec.reason = "idle";
+      flipped.push(rec.proposerId);
+    }
+  }
+  return flipped;
+}
+
+export function autoExpireStalePendingDelegations(db, nowMs) {
+  void db;
+  const now = Number(nowMs ?? Date.now());
+  const flipped = [];
+  for (const rec of _delegationStatesV2.values()) {
+    if (rec.status !== "pending") continue;
+    if (now - rec.createdAt > _pendingDelegationMsV2) {
+      rec.status = "expired";
+      rec.updatedAt = now;
+      rec.reason = "pending_timeout";
+      flipped.push(rec.delegationId);
+    }
+  }
+  return flipped;
+}
+
+/* ── Stats V2 ───────────────────────────────────────────────── */
+
+export function getGovernanceStatsV2() {
+  const proposersByStatus = {
+    onboarding: 0,
+    active: 0,
+    suspended: 0,
+    retired: 0,
+  };
+  const delegationsByStatus = {
+    pending: 0,
+    active: 0,
+    revoked: 0,
+    expired: 0,
+  };
+  for (const rec of _proposerStatesV2.values()) {
+    if (proposersByStatus[rec.status] !== undefined) {
+      proposersByStatus[rec.status] += 1;
+    }
+  }
+  for (const rec of _delegationStatesV2.values()) {
+    if (delegationsByStatus[rec.status] !== undefined) {
+      delegationsByStatus[rec.status] += 1;
+    }
+  }
+  return {
+    totalProposersV2: _proposerStatesV2.size,
+    totalDelegationsV2: _delegationStatesV2.size,
+    maxActiveProposersPerRealm: _maxActiveProposersPerRealmV2,
+    maxActiveDelegationsPerDelegator: _maxActiveDelegationsPerDelegatorV2,
+    proposerIdleMs: _proposerIdleMsV2,
+    pendingDelegationMs: _pendingDelegationMsV2,
+    proposersByStatus,
+    delegationsByStatus,
+  };
+}
+
+/* ── Reset V2 (tests) ───────────────────────────────────────── */
+
+export function _resetStateV2() {
+  _proposerStatesV2.clear();
+  _delegationStatesV2.clear();
+  _maxActiveProposersPerRealmV2 = GOV_DEFAULT_MAX_ACTIVE_PROPOSERS_PER_REALM;
+  _maxActiveDelegationsPerDelegatorV2 =
+    GOV_DEFAULT_MAX_ACTIVE_DELEGATIONS_PER_DELEGATOR;
+  _proposerIdleMsV2 = GOV_DEFAULT_PROPOSER_IDLE_MS;
+  _pendingDelegationMsV2 = GOV_DEFAULT_PENDING_DELEGATION_MS;
+}

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