chainlesschain 0.132.0 → 0.145.0

package/src/lib/perf-tuning.js

@@ -735,3 +735,367 @@ export function getPerformanceReport(db) {
 export function _resetState() {
   /* CLI is stateless; helper exists for parity with other libs */
 }
+
+// ===== V2 Surface: Perf Tuning governance overlay (CLI v0.140.0) =====
+export const PERF_TUNING_PROFILE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  STALE: "stale",
+  DECOMMISSIONED: "decommissioned",
+});
+export const PERF_BENCH_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const _ptpTrans = new Map([
+  [
+    PERF_TUNING_PROFILE_MATURITY_V2.PENDING,
+    new Set([
+      PERF_TUNING_PROFILE_MATURITY_V2.ACTIVE,
+      PERF_TUNING_PROFILE_MATURITY_V2.DECOMMISSIONED,
+    ]),
+  ],
+  [
+    PERF_TUNING_PROFILE_MATURITY_V2.ACTIVE,
+    new Set([
+      PERF_TUNING_PROFILE_MATURITY_V2.STALE,
+      PERF_TUNING_PROFILE_MATURITY_V2.DECOMMISSIONED,
+    ]),
+  ],
+  [
+    PERF_TUNING_PROFILE_MATURITY_V2.STALE,
+    new Set([
+      PERF_TUNING_PROFILE_MATURITY_V2.ACTIVE,
+      PERF_TUNING_PROFILE_MATURITY_V2.DECOMMISSIONED,
+    ]),
+  ],
+  [PERF_TUNING_PROFILE_MATURITY_V2.DECOMMISSIONED, new Set()],
+]);
+const _ptpTerminal = new Set([PERF_TUNING_PROFILE_MATURITY_V2.DECOMMISSIONED]);
+const _pbTrans = new Map([
+  [
+    PERF_BENCH_LIFECYCLE_V2.QUEUED,
+    new Set([
+      PERF_BENCH_LIFECYCLE_V2.RUNNING,
+      PERF_BENCH_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [
+    PERF_BENCH_LIFECYCLE_V2.RUNNING,
+    new Set([
+      PERF_BENCH_LIFECYCLE_V2.COMPLETED,
+      PERF_BENCH_LIFECYCLE_V2.FAILED,
+      PERF_BENCH_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [PERF_BENCH_LIFECYCLE_V2.COMPLETED, new Set()],
+  [PERF_BENCH_LIFECYCLE_V2.FAILED, new Set()],
+  [PERF_BENCH_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _ptpsV2 = new Map();
+const _pbsV2 = new Map();
+let _ptpMaxActivePerOwner = 6;
+let _ptpMaxPendingBenchesPerProfile = 10;
+let _ptpIdleMs = 7 * 24 * 60 * 60 * 1000;
+let _pbStuckMs = 30 * 60 * 1000;
+
+function _ptpPos(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 setMaxActivePerfTuningProfilesPerOwnerV2(n) {
+  _ptpMaxActivePerOwner = _ptpPos(n, "maxActivePerfTuningProfilesPerOwner");
+}
+export function getMaxActivePerfTuningProfilesPerOwnerV2() {
+  return _ptpMaxActivePerOwner;
+}
+export function setMaxPendingPerfBenchesPerProfileV2(n) {
+  _ptpMaxPendingBenchesPerProfile = _ptpPos(
+    n,
+    "maxPendingPerfBenchesPerProfile",
+  );
+}
+export function getMaxPendingPerfBenchesPerProfileV2() {
+  return _ptpMaxPendingBenchesPerProfile;
+}
+export function setPerfTuningProfileIdleMsV2(n) {
+  _ptpIdleMs = _ptpPos(n, "perfTuningProfileIdleMs");
+}
+export function getPerfTuningProfileIdleMsV2() {
+  return _ptpIdleMs;
+}
+export function setPerfBenchStuckMsV2(n) {
+  _pbStuckMs = _ptpPos(n, "perfBenchStuckMs");
+}
+export function getPerfBenchStuckMsV2() {
+  return _pbStuckMs;
+}
+
+export function _resetStatePerfTuningV2() {
+  _ptpsV2.clear();
+  _pbsV2.clear();
+  _ptpMaxActivePerOwner = 6;
+  _ptpMaxPendingBenchesPerProfile = 10;
+  _ptpIdleMs = 7 * 24 * 60 * 60 * 1000;
+  _pbStuckMs = 30 * 60 * 1000;
+}
+
+export function registerPerfTuningProfileV2({
+  id,
+  owner,
+  target,
+  metadata,
+} = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_ptpsV2.has(id))
+    throw new Error(`perf tuning profile ${id} already registered`);
+  const now = Date.now();
+  const p = {
+    id,
+    owner,
+    target: target || "default",
+    status: PERF_TUNING_PROFILE_MATURITY_V2.PENDING,
+    createdAt: now,
+    updatedAt: now,
+    activatedAt: null,
+    decommissionedAt: null,
+    lastTouchedAt: now,
+    metadata: { ...(metadata || {}) },
+  };
+  _ptpsV2.set(id, p);
+  return { ...p, metadata: { ...p.metadata } };
+}
+function _ptpCheckP(from, to) {
+  const a = _ptpTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid perf tuning profile transition ${from} → ${to}`);
+}
+function _ptpCountActive(owner) {
+  let n = 0;
+  for (const p of _ptpsV2.values())
+    if (
+      p.owner === owner &&
+      p.status === PERF_TUNING_PROFILE_MATURITY_V2.ACTIVE
+    )
+      n++;
+  return n;
+}
+
+export function activatePerfTuningProfileV2(id) {
+  const p = _ptpsV2.get(id);
+  if (!p) throw new Error(`perf tuning profile ${id} not found`);
+  _ptpCheckP(p.status, PERF_TUNING_PROFILE_MATURITY_V2.ACTIVE);
+  const recovery = p.status === PERF_TUNING_PROFILE_MATURITY_V2.STALE;
+  if (!recovery) {
+    const c = _ptpCountActive(p.owner);
+    if (c >= _ptpMaxActivePerOwner)
+      throw new Error(
+        `max active perf tuning profiles per owner (${_ptpMaxActivePerOwner}) reached for ${p.owner}`,
+      );
+  }
+  const now = Date.now();
+  p.status = PERF_TUNING_PROFILE_MATURITY_V2.ACTIVE;
+  p.updatedAt = now;
+  p.lastTouchedAt = now;
+  if (!p.activatedAt) p.activatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function stalePerfTuningProfileV2(id) {
+  const p = _ptpsV2.get(id);
+  if (!p) throw new Error(`perf tuning profile ${id} not found`);
+  _ptpCheckP(p.status, PERF_TUNING_PROFILE_MATURITY_V2.STALE);
+  p.status = PERF_TUNING_PROFILE_MATURITY_V2.STALE;
+  p.updatedAt = Date.now();
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function decommissionPerfTuningProfileV2(id) {
+  const p = _ptpsV2.get(id);
+  if (!p) throw new Error(`perf tuning profile ${id} not found`);
+  _ptpCheckP(p.status, PERF_TUNING_PROFILE_MATURITY_V2.DECOMMISSIONED);
+  const now = Date.now();
+  p.status = PERF_TUNING_PROFILE_MATURITY_V2.DECOMMISSIONED;
+  p.updatedAt = now;
+  if (!p.decommissionedAt) p.decommissionedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function touchPerfTuningProfileV2(id) {
+  const p = _ptpsV2.get(id);
+  if (!p) throw new Error(`perf tuning profile ${id} not found`);
+  if (_ptpTerminal.has(p.status))
+    throw new Error(`cannot touch terminal perf tuning profile ${id}`);
+  const now = Date.now();
+  p.lastTouchedAt = now;
+  p.updatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function getPerfTuningProfileV2(id) {
+  const p = _ptpsV2.get(id);
+  if (!p) return null;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function listPerfTuningProfilesV2() {
+  return [..._ptpsV2.values()].map((p) => ({
+    ...p,
+    metadata: { ...p.metadata },
+  }));
+}
+
+function _pbCountPending(profileId) {
+  let n = 0;
+  for (const b of _pbsV2.values())
+    if (
+      b.profileId === profileId &&
+      (b.status === PERF_BENCH_LIFECYCLE_V2.QUEUED ||
+        b.status === PERF_BENCH_LIFECYCLE_V2.RUNNING)
+    )
+      n++;
+  return n;
+}
+
+export function createPerfBenchV2({ id, profileId, scenario, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!profileId || typeof profileId !== "string")
+    throw new Error("profileId is required");
+  if (_pbsV2.has(id)) throw new Error(`perf bench ${id} already exists`);
+  if (!_ptpsV2.has(profileId))
+    throw new Error(`perf tuning profile ${profileId} not found`);
+  const pending = _pbCountPending(profileId);
+  if (pending >= _ptpMaxPendingBenchesPerProfile)
+    throw new Error(
+      `max pending perf benches per profile (${_ptpMaxPendingBenchesPerProfile}) reached for ${profileId}`,
+    );
+  const now = Date.now();
+  const b = {
+    id,
+    profileId,
+    scenario: scenario || "",
+    status: PERF_BENCH_LIFECYCLE_V2.QUEUED,
+    createdAt: now,
+    updatedAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: { ...(metadata || {}) },
+  };
+  _pbsV2.set(id, b);
+  return { ...b, metadata: { ...b.metadata } };
+}
+function _pbCheckB(from, to) {
+  const a = _pbTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid perf bench transition ${from} → ${to}`);
+}
+export function startPerfBenchV2(id) {
+  const b = _pbsV2.get(id);
+  if (!b) throw new Error(`perf bench ${id} not found`);
+  _pbCheckB(b.status, PERF_BENCH_LIFECYCLE_V2.RUNNING);
+  const now = Date.now();
+  b.status = PERF_BENCH_LIFECYCLE_V2.RUNNING;
+  b.updatedAt = now;
+  if (!b.startedAt) b.startedAt = now;
+  return { ...b, metadata: { ...b.metadata } };
+}
+export function completePerfBenchV2(id) {
+  const b = _pbsV2.get(id);
+  if (!b) throw new Error(`perf bench ${id} not found`);
+  _pbCheckB(b.status, PERF_BENCH_LIFECYCLE_V2.COMPLETED);
+  const now = Date.now();
+  b.status = PERF_BENCH_LIFECYCLE_V2.COMPLETED;
+  b.updatedAt = now;
+  if (!b.settledAt) b.settledAt = now;
+  return { ...b, metadata: { ...b.metadata } };
+}
+export function failPerfBenchV2(id, reason) {
+  const b = _pbsV2.get(id);
+  if (!b) throw new Error(`perf bench ${id} not found`);
+  _pbCheckB(b.status, PERF_BENCH_LIFECYCLE_V2.FAILED);
+  const now = Date.now();
+  b.status = PERF_BENCH_LIFECYCLE_V2.FAILED;
+  b.updatedAt = now;
+  if (!b.settledAt) b.settledAt = now;
+  if (reason) b.metadata.failReason = String(reason);
+  return { ...b, metadata: { ...b.metadata } };
+}
+export function cancelPerfBenchV2(id, reason) {
+  const b = _pbsV2.get(id);
+  if (!b) throw new Error(`perf bench ${id} not found`);
+  _pbCheckB(b.status, PERF_BENCH_LIFECYCLE_V2.CANCELLED);
+  const now = Date.now();
+  b.status = PERF_BENCH_LIFECYCLE_V2.CANCELLED;
+  b.updatedAt = now;
+  if (!b.settledAt) b.settledAt = now;
+  if (reason) b.metadata.cancelReason = String(reason);
+  return { ...b, metadata: { ...b.metadata } };
+}
+export function getPerfBenchV2(id) {
+  const b = _pbsV2.get(id);
+  if (!b) return null;
+  return { ...b, metadata: { ...b.metadata } };
+}
+export function listPerfBenchesV2() {
+  return [..._pbsV2.values()].map((b) => ({
+    ...b,
+    metadata: { ...b.metadata },
+  }));
+}
+
+export function autoStaleIdlePerfTuningProfilesV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const p of _ptpsV2.values())
+    if (
+      p.status === PERF_TUNING_PROFILE_MATURITY_V2.ACTIVE &&
+      t - p.lastTouchedAt >= _ptpIdleMs
+    ) {
+      p.status = PERF_TUNING_PROFILE_MATURITY_V2.STALE;
+      p.updatedAt = t;
+      flipped.push(p.id);
+    }
+  return { flipped, count: flipped.length };
+}
+export function autoFailStuckPerfBenchesV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const b of _pbsV2.values())
+    if (
+      b.status === PERF_BENCH_LIFECYCLE_V2.RUNNING &&
+      b.startedAt != null &&
+      t - b.startedAt >= _pbStuckMs
+    ) {
+      b.status = PERF_BENCH_LIFECYCLE_V2.FAILED;
+      b.updatedAt = t;
+      if (!b.settledAt) b.settledAt = t;
+      b.metadata.failReason = "auto-fail-stuck";
+      flipped.push(b.id);
+    }
+  return { flipped, count: flipped.length };
+}
+
+export function getPerfTuningGovStatsV2() {
+  const profilesByStatus = {};
+  for (const s of Object.values(PERF_TUNING_PROFILE_MATURITY_V2))
+    profilesByStatus[s] = 0;
+  for (const p of _ptpsV2.values()) profilesByStatus[p.status]++;
+  const benchesByStatus = {};
+  for (const s of Object.values(PERF_BENCH_LIFECYCLE_V2))
+    benchesByStatus[s] = 0;
+  for (const b of _pbsV2.values()) benchesByStatus[b.status]++;
+  return {
+    totalPerfTuningProfilesV2: _ptpsV2.size,
+    totalPerfBenchesV2: _pbsV2.size,
+    maxActivePerfTuningProfilesPerOwner: _ptpMaxActivePerOwner,
+    maxPendingPerfBenchesPerProfile: _ptpMaxPendingBenchesPerProfile,
+    perfTuningProfileIdleMs: _ptpIdleMs,
+    perfBenchStuckMs: _pbStuckMs,
+    profilesByStatus,
+    benchesByStatus,
+  };
+}

package/src/lib/permission-engine.js

@@ -372,3 +372,322 @@ export function listUserRoles(db) {
 
   return [...userMap.entries()].map(([userDid, roles]) => ({ userDid, roles }));
 }
+
+// ===== V2 Surface: Permission Engine governance overlay (CLI v0.141.0) =====
+export const PERM_RULE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  DISABLED: "disabled",
+  RETIRED: "retired",
+});
+export const PERM_CHECK_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  EVALUATING: "evaluating",
+  ALLOWED: "allowed",
+  DENIED: "denied",
+  CANCELLED: "cancelled",
+});
+const _permRTrans = new Map([
+  [
+    PERM_RULE_MATURITY_V2.PENDING,
+    new Set([PERM_RULE_MATURITY_V2.ACTIVE, PERM_RULE_MATURITY_V2.RETIRED]),
+  ],
+  [
+    PERM_RULE_MATURITY_V2.ACTIVE,
+    new Set([PERM_RULE_MATURITY_V2.DISABLED, PERM_RULE_MATURITY_V2.RETIRED]),
+  ],
+  [
+    PERM_RULE_MATURITY_V2.DISABLED,
+    new Set([PERM_RULE_MATURITY_V2.ACTIVE, PERM_RULE_MATURITY_V2.RETIRED]),
+  ],
+  [PERM_RULE_MATURITY_V2.RETIRED, new Set()],
+]);
+const _permRTerminal = new Set([PERM_RULE_MATURITY_V2.RETIRED]);
+const _permCTrans = new Map([
+  [
+    PERM_CHECK_LIFECYCLE_V2.QUEUED,
+    new Set([
+      PERM_CHECK_LIFECYCLE_V2.EVALUATING,
+      PERM_CHECK_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [
+    PERM_CHECK_LIFECYCLE_V2.EVALUATING,
+    new Set([
+      PERM_CHECK_LIFECYCLE_V2.ALLOWED,
+      PERM_CHECK_LIFECYCLE_V2.DENIED,
+      PERM_CHECK_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [PERM_CHECK_LIFECYCLE_V2.ALLOWED, new Set()],
+  [PERM_CHECK_LIFECYCLE_V2.DENIED, new Set()],
+  [PERM_CHECK_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+const _permRsV2 = new Map();
+const _permCsV2 = new Map();
+let _permMaxActivePerOwner = 10,
+  _permMaxPendingChecksPerRule = 30,
+  _permIdleMs = 30 * 24 * 60 * 60 * 1000,
+  _permStuckMs = 60 * 1000;
+function _permPos(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 _permCheckR(from, to) {
+  const a = _permRTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid perm rule transition ${from} → ${to}`);
+}
+function _permCheckC(from, to) {
+  const a = _permCTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid perm check transition ${from} → ${to}`);
+}
+export function setMaxActivePermRulesPerOwnerV2(n) {
+  _permMaxActivePerOwner = _permPos(n, "maxActivePermRulesPerOwner");
+}
+export function getMaxActivePermRulesPerOwnerV2() {
+  return _permMaxActivePerOwner;
+}
+export function setMaxPendingPermChecksPerRuleV2(n) {
+  _permMaxPendingChecksPerRule = _permPos(n, "maxPendingPermChecksPerRule");
+}
+export function getMaxPendingPermChecksPerRuleV2() {
+  return _permMaxPendingChecksPerRule;
+}
+export function setPermRuleIdleMsV2(n) {
+  _permIdleMs = _permPos(n, "permRuleIdleMs");
+}
+export function getPermRuleIdleMsV2() {
+  return _permIdleMs;
+}
+export function setPermCheckStuckMsV2(n) {
+  _permStuckMs = _permPos(n, "permCheckStuckMs");
+}
+export function getPermCheckStuckMsV2() {
+  return _permStuckMs;
+}
+export function _resetStatePermissionEngineV2() {
+  _permRsV2.clear();
+  _permCsV2.clear();
+  _permMaxActivePerOwner = 10;
+  _permMaxPendingChecksPerRule = 30;
+  _permIdleMs = 30 * 24 * 60 * 60 * 1000;
+  _permStuckMs = 60 * 1000;
+}
+export function registerPermRuleV2({ id, owner, scope, metadata } = {}) {
+  if (!id) throw new Error("perm rule id required");
+  if (!owner) throw new Error("perm rule owner required");
+  if (_permRsV2.has(id)) throw new Error(`perm rule ${id} already registered`);
+  const now = Date.now();
+  const r = {
+    id,
+    owner,
+    scope: scope || "*",
+    status: PERM_RULE_MATURITY_V2.PENDING,
+    createdAt: now,
+    updatedAt: now,
+    activatedAt: null,
+    retiredAt: null,
+    lastTouchedAt: now,
+    metadata: { ...(metadata || {}) },
+  };
+  _permRsV2.set(id, r);
+  return { ...r, metadata: { ...r.metadata } };
+}
+function _permCountActive(owner) {
+  let n = 0;
+  for (const r of _permRsV2.values())
+    if (r.owner === owner && r.status === PERM_RULE_MATURITY_V2.ACTIVE) n++;
+  return n;
+}
+export function activatePermRuleV2(id) {
+  const r = _permRsV2.get(id);
+  if (!r) throw new Error(`perm rule ${id} not found`);
+  _permCheckR(r.status, PERM_RULE_MATURITY_V2.ACTIVE);
+  const recovery = r.status === PERM_RULE_MATURITY_V2.DISABLED;
+  if (!recovery && _permCountActive(r.owner) >= _permMaxActivePerOwner)
+    throw new Error(`max active perm rules for owner ${r.owner} reached`);
+  const now = Date.now();
+  r.status = PERM_RULE_MATURITY_V2.ACTIVE;
+  r.updatedAt = now;
+  r.lastTouchedAt = now;
+  if (!r.activatedAt) r.activatedAt = now;
+  return { ...r, metadata: { ...r.metadata } };
+}
+export function disablePermRuleV2(id) {
+  const r = _permRsV2.get(id);
+  if (!r) throw new Error(`perm rule ${id} not found`);
+  _permCheckR(r.status, PERM_RULE_MATURITY_V2.DISABLED);
+  r.status = PERM_RULE_MATURITY_V2.DISABLED;
+  r.updatedAt = Date.now();
+  return { ...r, metadata: { ...r.metadata } };
+}
+export function retirePermRuleV2(id) {
+  const r = _permRsV2.get(id);
+  if (!r) throw new Error(`perm rule ${id} not found`);
+  _permCheckR(r.status, PERM_RULE_MATURITY_V2.RETIRED);
+  const now = Date.now();
+  r.status = PERM_RULE_MATURITY_V2.RETIRED;
+  r.updatedAt = now;
+  if (!r.retiredAt) r.retiredAt = now;
+  return { ...r, metadata: { ...r.metadata } };
+}
+export function touchPermRuleV2(id) {
+  const r = _permRsV2.get(id);
+  if (!r) throw new Error(`perm rule ${id} not found`);
+  if (_permRTerminal.has(r.status))
+    throw new Error(`cannot touch terminal perm rule ${id}`);
+  const now = Date.now();
+  r.lastTouchedAt = now;
+  r.updatedAt = now;
+  return { ...r, metadata: { ...r.metadata } };
+}
+export function getPermRuleV2(id) {
+  const r = _permRsV2.get(id);
+  if (!r) return null;
+  return { ...r, metadata: { ...r.metadata } };
+}
+export function listPermRulesV2() {
+  return [..._permRsV2.values()].map((r) => ({
+    ...r,
+    metadata: { ...r.metadata },
+  }));
+}
+function _permCountPending(ruleId) {
+  let n = 0;
+  for (const c of _permCsV2.values())
+    if (
+      c.ruleId === ruleId &&
+      (c.status === PERM_CHECK_LIFECYCLE_V2.QUEUED ||
+        c.status === PERM_CHECK_LIFECYCLE_V2.EVALUATING)
+    )
+      n++;
+  return n;
+}
+export function createPermCheckV2({ id, ruleId, subject, metadata } = {}) {
+  if (!id) throw new Error("perm check id required");
+  if (!ruleId) throw new Error("perm check ruleId required");
+  if (_permCsV2.has(id)) throw new Error(`perm check ${id} already exists`);
+  if (!_permRsV2.has(ruleId)) throw new Error(`perm rule ${ruleId} not found`);
+  if (_permCountPending(ruleId) >= _permMaxPendingChecksPerRule)
+    throw new Error(`max pending perm checks for rule ${ruleId} reached`);
+  const now = Date.now();
+  const c = {
+    id,
+    ruleId,
+    subject: subject || "",
+    status: PERM_CHECK_LIFECYCLE_V2.QUEUED,
+    createdAt: now,
+    updatedAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: { ...(metadata || {}) },
+  };
+  _permCsV2.set(id, c);
+  return { ...c, metadata: { ...c.metadata } };
+}
+export function evaluatePermCheckV2(id) {
+  const c = _permCsV2.get(id);
+  if (!c) throw new Error(`perm check ${id} not found`);
+  _permCheckC(c.status, PERM_CHECK_LIFECYCLE_V2.EVALUATING);
+  const now = Date.now();
+  c.status = PERM_CHECK_LIFECYCLE_V2.EVALUATING;
+  c.updatedAt = now;
+  if (!c.startedAt) c.startedAt = now;
+  return { ...c, metadata: { ...c.metadata } };
+}
+export function allowPermCheckV2(id) {
+  const c = _permCsV2.get(id);
+  if (!c) throw new Error(`perm check ${id} not found`);
+  _permCheckC(c.status, PERM_CHECK_LIFECYCLE_V2.ALLOWED);
+  const now = Date.now();
+  c.status = PERM_CHECK_LIFECYCLE_V2.ALLOWED;
+  c.updatedAt = now;
+  if (!c.settledAt) c.settledAt = now;
+  return { ...c, metadata: { ...c.metadata } };
+}
+export function denyPermCheckV2(id, reason) {
+  const c = _permCsV2.get(id);
+  if (!c) throw new Error(`perm check ${id} not found`);
+  _permCheckC(c.status, PERM_CHECK_LIFECYCLE_V2.DENIED);
+  const now = Date.now();
+  c.status = PERM_CHECK_LIFECYCLE_V2.DENIED;
+  c.updatedAt = now;
+  if (!c.settledAt) c.settledAt = now;
+  if (reason) c.metadata.denyReason = String(reason);
+  return { ...c, metadata: { ...c.metadata } };
+}
+export function cancelPermCheckV2(id, reason) {
+  const c = _permCsV2.get(id);
+  if (!c) throw new Error(`perm check ${id} not found`);
+  _permCheckC(c.status, PERM_CHECK_LIFECYCLE_V2.CANCELLED);
+  const now = Date.now();
+  c.status = PERM_CHECK_LIFECYCLE_V2.CANCELLED;
+  c.updatedAt = now;
+  if (!c.settledAt) c.settledAt = now;
+  if (reason) c.metadata.cancelReason = String(reason);
+  return { ...c, metadata: { ...c.metadata } };
+}
+export function getPermCheckV2(id) {
+  const c = _permCsV2.get(id);
+  if (!c) return null;
+  return { ...c, metadata: { ...c.metadata } };
+}
+export function listPermChecksV2() {
+  return [..._permCsV2.values()].map((c) => ({
+    ...c,
+    metadata: { ...c.metadata },
+  }));
+}
+export function autoDisableIdlePermRulesV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const r of _permRsV2.values())
+    if (
+      r.status === PERM_RULE_MATURITY_V2.ACTIVE &&
+      t - r.lastTouchedAt >= _permIdleMs
+    ) {
+      r.status = PERM_RULE_MATURITY_V2.DISABLED;
+      r.updatedAt = t;
+      flipped.push(r.id);
+    }
+  return { flipped, count: flipped.length };
+}
+export function autoDenyStuckPermChecksV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const c of _permCsV2.values())
+    if (
+      c.status === PERM_CHECK_LIFECYCLE_V2.EVALUATING &&
+      c.startedAt != null &&
+      t - c.startedAt >= _permStuckMs
+    ) {
+      c.status = PERM_CHECK_LIFECYCLE_V2.DENIED;
+      c.updatedAt = t;
+      if (!c.settledAt) c.settledAt = t;
+      c.metadata.denyReason = "auto-deny-stuck";
+      flipped.push(c.id);
+    }
+  return { flipped, count: flipped.length };
+}
+export function getPermissionEngineGovStatsV2() {
+  const rulesByStatus = {};
+  for (const v of Object.values(PERM_RULE_MATURITY_V2)) rulesByStatus[v] = 0;
+  for (const r of _permRsV2.values()) rulesByStatus[r.status]++;
+  const checksByStatus = {};
+  for (const v of Object.values(PERM_CHECK_LIFECYCLE_V2)) checksByStatus[v] = 0;
+  for (const c of _permCsV2.values()) checksByStatus[c.status]++;
+  return {
+    totalPermRulesV2: _permRsV2.size,
+    totalPermChecksV2: _permCsV2.size,
+    maxActivePermRulesPerOwner: _permMaxActivePerOwner,
+    maxPendingPermChecksPerRule: _permMaxPendingChecksPerRule,
+    permRuleIdleMs: _permIdleMs,
+    permCheckStuckMs: _permStuckMs,
+    rulesByStatus,
+    checksByStatus,
+  };
+}