chainlesschain 0.81.0 → 0.143.0

package/src/lib/siem-exporter.js

@@ -468,3 +468,108 @@ export function listTargetsByStatus(status) {
 }
 
 export { _severityCEF, _allowedTargetTransitions };
+
+
+// ===== V2 Surface: SIEM Exporter governance overlay (CLI v0.138.0) =====
+export const SIEM_TARGET_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", DEGRADED: "degraded", RETIRED: "retired",
+});
+export const SIEM_EXPORT_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", SENDING: "sending", DELIVERED: "delivered", FAILED: "failed", CANCELLED: "cancelled",
+});
+
+const _siemTargetTrans = new Map([
+  [SIEM_TARGET_MATURITY_V2.PENDING, new Set([SIEM_TARGET_MATURITY_V2.ACTIVE, SIEM_TARGET_MATURITY_V2.RETIRED])],
+  [SIEM_TARGET_MATURITY_V2.ACTIVE, new Set([SIEM_TARGET_MATURITY_V2.DEGRADED, SIEM_TARGET_MATURITY_V2.RETIRED])],
+  [SIEM_TARGET_MATURITY_V2.DEGRADED, new Set([SIEM_TARGET_MATURITY_V2.ACTIVE, SIEM_TARGET_MATURITY_V2.RETIRED])],
+  [SIEM_TARGET_MATURITY_V2.RETIRED, new Set()],
+]);
+const _siemTargetTerminal = new Set([SIEM_TARGET_MATURITY_V2.RETIRED]);
+const _siemExportTrans = new Map([
+  [SIEM_EXPORT_LIFECYCLE_V2.QUEUED, new Set([SIEM_EXPORT_LIFECYCLE_V2.SENDING, SIEM_EXPORT_LIFECYCLE_V2.CANCELLED])],
+  [SIEM_EXPORT_LIFECYCLE_V2.SENDING, new Set([SIEM_EXPORT_LIFECYCLE_V2.DELIVERED, SIEM_EXPORT_LIFECYCLE_V2.FAILED, SIEM_EXPORT_LIFECYCLE_V2.CANCELLED])],
+  [SIEM_EXPORT_LIFECYCLE_V2.DELIVERED, new Set()],
+  [SIEM_EXPORT_LIFECYCLE_V2.FAILED, new Set()],
+  [SIEM_EXPORT_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _siemTargets = new Map();
+const _siemExportJobs = new Map();
+let _siemMaxActivePerOperator = 8;
+let _siemMaxPendingExportsPerTarget = 50;
+let _siemTargetIdleMs = 24 * 60 * 60 * 1000;
+let _siemExportStuckMs = 5 * 60 * 1000;
+
+function _siemPos(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 setMaxActiveSiemTargetsPerOperatorV2(n) { _siemMaxActivePerOperator = _siemPos(n, "maxActiveSiemTargetsPerOperator"); }
+export function getMaxActiveSiemTargetsPerOperatorV2() { return _siemMaxActivePerOperator; }
+export function setMaxPendingSiemExportsPerTargetV2(n) { _siemMaxPendingExportsPerTarget = _siemPos(n, "maxPendingSiemExportsPerTarget"); }
+export function getMaxPendingSiemExportsPerTargetV2() { return _siemMaxPendingExportsPerTarget; }
+export function setSiemTargetIdleMsV2(n) { _siemTargetIdleMs = _siemPos(n, "siemTargetIdleMs"); }
+export function getSiemTargetIdleMsV2() { return _siemTargetIdleMs; }
+export function setSiemExportStuckMsV2(n) { _siemExportStuckMs = _siemPos(n, "siemExportStuckMs"); }
+export function getSiemExportStuckMsV2() { return _siemExportStuckMs; }
+
+export function _resetStateSiemExporterV2() {
+  _siemTargets.clear(); _siemExportJobs.clear();
+  _siemMaxActivePerOperator = 8; _siemMaxPendingExportsPerTarget = 50;
+  _siemTargetIdleMs = 24 * 60 * 60 * 1000; _siemExportStuckMs = 5 * 60 * 1000;
+}
+
+export function registerSiemTargetV2({ id, operator, kind, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!operator || typeof operator !== "string") throw new Error("operator is required");
+  if (_siemTargets.has(id)) throw new Error(`siem target ${id} already registered`);
+  const now = Date.now();
+  const t = { id, operator, kind: kind || "splunk_hec", status: SIEM_TARGET_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, retiredAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _siemTargets.set(id, t);
+  return { ...t, metadata: { ...t.metadata } };
+}
+function _siemCheckT(from, to) { const a = _siemTargetTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid siem target transition ${from} → ${to}`); }
+function _siemCountActive(operator) { let n = 0; for (const t of _siemTargets.values()) if (t.operator === operator && t.status === SIEM_TARGET_MATURITY_V2.ACTIVE) n++; return n; }
+
+export function activateSiemTargetV2(id) {
+  const t = _siemTargets.get(id); if (!t) throw new Error(`siem target ${id} not found`);
+  _siemCheckT(t.status, SIEM_TARGET_MATURITY_V2.ACTIVE);
+  const recovery = t.status === SIEM_TARGET_MATURITY_V2.DEGRADED;
+  if (!recovery) { const c = _siemCountActive(t.operator); if (c >= _siemMaxActivePerOperator) throw new Error(`max active siem targets per operator (${_siemMaxActivePerOperator}) reached for ${t.operator}`); }
+  const now = Date.now(); t.status = SIEM_TARGET_MATURITY_V2.ACTIVE; t.updatedAt = now; t.lastTouchedAt = now; if (!t.activatedAt) t.activatedAt = now;
+  return { ...t, metadata: { ...t.metadata } };
+}
+export function degradeSiemTargetV2(id) { const t = _siemTargets.get(id); if (!t) throw new Error(`siem target ${id} not found`); _siemCheckT(t.status, SIEM_TARGET_MATURITY_V2.DEGRADED); t.status = SIEM_TARGET_MATURITY_V2.DEGRADED; t.updatedAt = Date.now(); return { ...t, metadata: { ...t.metadata } }; }
+export function retireSiemTargetV2(id) { const t = _siemTargets.get(id); if (!t) throw new Error(`siem target ${id} not found`); _siemCheckT(t.status, SIEM_TARGET_MATURITY_V2.RETIRED); const now = Date.now(); t.status = SIEM_TARGET_MATURITY_V2.RETIRED; t.updatedAt = now; if (!t.retiredAt) t.retiredAt = now; return { ...t, metadata: { ...t.metadata } }; }
+export function touchSiemTargetV2(id) { const t = _siemTargets.get(id); if (!t) throw new Error(`siem target ${id} not found`); if (_siemTargetTerminal.has(t.status)) throw new Error(`cannot touch terminal siem target ${id}`); const now = Date.now(); t.lastTouchedAt = now; t.updatedAt = now; return { ...t, metadata: { ...t.metadata } }; }
+export function getSiemTargetV2(id) { const t = _siemTargets.get(id); if (!t) return null; return { ...t, metadata: { ...t.metadata } }; }
+export function listSiemTargetsV2() { return [..._siemTargets.values()].map((t) => ({ ...t, metadata: { ...t.metadata } })); }
+
+function _siemCountPendingExports(tid) { let n = 0; for (const e of _siemExportJobs.values()) if (e.targetId === tid && (e.status === SIEM_EXPORT_LIFECYCLE_V2.QUEUED || e.status === SIEM_EXPORT_LIFECYCLE_V2.SENDING)) n++; return n; }
+
+export function createSiemExportV2({ id, targetId, format, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!targetId || typeof targetId !== "string") throw new Error("targetId is required");
+  if (_siemExportJobs.has(id)) throw new Error(`siem export ${id} already exists`);
+  if (!_siemTargets.has(targetId)) throw new Error(`siem target ${targetId} not found`);
+  const pending = _siemCountPendingExports(targetId);
+  if (pending >= _siemMaxPendingExportsPerTarget) throw new Error(`max pending siem exports per target (${_siemMaxPendingExportsPerTarget}) reached for ${targetId}`);
+  const now = Date.now();
+  const e = { id, targetId, format: format || "json", status: SIEM_EXPORT_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _siemExportJobs.set(id, e);
+  return { ...e, metadata: { ...e.metadata } };
+}
+function _siemCheckE(from, to) { const a = _siemExportTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid siem export transition ${from} → ${to}`); }
+export function startSiemExportV2(id) { const e = _siemExportJobs.get(id); if (!e) throw new Error(`siem export ${id} not found`); _siemCheckE(e.status, SIEM_EXPORT_LIFECYCLE_V2.SENDING); const now = Date.now(); e.status = SIEM_EXPORT_LIFECYCLE_V2.SENDING; e.updatedAt = now; if (!e.startedAt) e.startedAt = now; return { ...e, metadata: { ...e.metadata } }; }
+export function deliverSiemExportV2(id) { const e = _siemExportJobs.get(id); if (!e) throw new Error(`siem export ${id} not found`); _siemCheckE(e.status, SIEM_EXPORT_LIFECYCLE_V2.DELIVERED); const now = Date.now(); e.status = SIEM_EXPORT_LIFECYCLE_V2.DELIVERED; e.updatedAt = now; if (!e.settledAt) e.settledAt = now; return { ...e, metadata: { ...e.metadata } }; }
+export function failSiemExportV2(id, reason) { const e = _siemExportJobs.get(id); if (!e) throw new Error(`siem export ${id} not found`); _siemCheckE(e.status, SIEM_EXPORT_LIFECYCLE_V2.FAILED); const now = Date.now(); e.status = SIEM_EXPORT_LIFECYCLE_V2.FAILED; e.updatedAt = now; if (!e.settledAt) e.settledAt = now; if (reason) e.metadata.failReason = String(reason); return { ...e, metadata: { ...e.metadata } }; }
+export function cancelSiemExportV2(id, reason) { const e = _siemExportJobs.get(id); if (!e) throw new Error(`siem export ${id} not found`); _siemCheckE(e.status, SIEM_EXPORT_LIFECYCLE_V2.CANCELLED); const now = Date.now(); e.status = SIEM_EXPORT_LIFECYCLE_V2.CANCELLED; e.updatedAt = now; if (!e.settledAt) e.settledAt = now; if (reason) e.metadata.cancelReason = String(reason); return { ...e, metadata: { ...e.metadata } }; }
+export function getSiemExportV2(id) { const e = _siemExportJobs.get(id); if (!e) return null; return { ...e, metadata: { ...e.metadata } }; }
+export function listSiemExportsV2() { return [..._siemExportJobs.values()].map((e) => ({ ...e, metadata: { ...e.metadata } })); }
+
+export function autoDegradeIdleSiemTargetsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const tgt of _siemTargets.values()) if (tgt.status === SIEM_TARGET_MATURITY_V2.ACTIVE && (t - tgt.lastTouchedAt) >= _siemTargetIdleMs) { tgt.status = SIEM_TARGET_MATURITY_V2.DEGRADED; tgt.updatedAt = t; flipped.push(tgt.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckSiemExportsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const e of _siemExportJobs.values()) if (e.status === SIEM_EXPORT_LIFECYCLE_V2.SENDING && e.startedAt != null && (t - e.startedAt) >= _siemExportStuckMs) { e.status = SIEM_EXPORT_LIFECYCLE_V2.FAILED; e.updatedAt = t; if (!e.settledAt) e.settledAt = t; e.metadata.failReason = "auto-fail-stuck"; flipped.push(e.id); } return { flipped, count: flipped.length }; }
+
+export function getSiemExporterGovStatsV2() {
+  const targetsByStatus = {}; for (const s of Object.values(SIEM_TARGET_MATURITY_V2)) targetsByStatus[s] = 0; for (const t of _siemTargets.values()) targetsByStatus[t.status]++;
+  const exportsByStatus = {}; for (const s of Object.values(SIEM_EXPORT_LIFECYCLE_V2)) exportsByStatus[s] = 0; for (const e of _siemExportJobs.values()) exportsByStatus[e.status]++;
+  return { totalSiemTargetsV2: _siemTargets.size, totalSiemExportsV2: _siemExportJobs.size, maxActiveSiemTargetsPerOperator: _siemMaxActivePerOperator, maxPendingSiemExportsPerTarget: _siemMaxPendingExportsPerTarget, siemTargetIdleMs: _siemTargetIdleMs, siemExportStuckMs: _siemExportStuckMs, targetsByStatus, exportsByStatus };
+}

package/src/lib/skill-loader.js

@@ -356,3 +356,380 @@ export class CLISkillLoader {
     this._cache = null;
   }
 }
+
+// ─── V2 Governance Layer ────────────────────────────────────────────
+//
+// In-memory governance for skill registrations + execution tickets,
+// independent of the file-based 4-layer CLISkillLoader (which scans
+// bundled/marketplace/managed/workspace dirs). V2 tracks maturity
+// transitions, per-owner active-skill caps, per-skill pending-execution
+// caps, stamp-once timestamps, and bulk auto-flip routines.
+
+export const SKILL_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  DEPRECATED: "deprecated",
+  ARCHIVED: "archived",
+});
+
+export const EXECUTION_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  SUCCEEDED: "succeeded",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const _SKILL_TRANSITIONS_V2 = new Map([
+  [
+    SKILL_MATURITY_V2.PENDING,
+    new Set([SKILL_MATURITY_V2.ACTIVE, SKILL_MATURITY_V2.ARCHIVED]),
+  ],
+  [
+    SKILL_MATURITY_V2.ACTIVE,
+    new Set([SKILL_MATURITY_V2.DEPRECATED, SKILL_MATURITY_V2.ARCHIVED]),
+  ],
+  [
+    SKILL_MATURITY_V2.DEPRECATED,
+    new Set([SKILL_MATURITY_V2.ACTIVE, SKILL_MATURITY_V2.ARCHIVED]),
+  ],
+  [SKILL_MATURITY_V2.ARCHIVED, new Set()],
+]);
+
+const _SKILL_TERMINALS_V2 = new Set([SKILL_MATURITY_V2.ARCHIVED]);
+
+const _EXEC_TRANSITIONS_V2 = new Map([
+  [
+    EXECUTION_LIFECYCLE_V2.QUEUED,
+    new Set([EXECUTION_LIFECYCLE_V2.RUNNING, EXECUTION_LIFECYCLE_V2.CANCELLED]),
+  ],
+  [
+    EXECUTION_LIFECYCLE_V2.RUNNING,
+    new Set([
+      EXECUTION_LIFECYCLE_V2.SUCCEEDED,
+      EXECUTION_LIFECYCLE_V2.FAILED,
+      EXECUTION_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [EXECUTION_LIFECYCLE_V2.SUCCEEDED, new Set()],
+  [EXECUTION_LIFECYCLE_V2.FAILED, new Set()],
+  [EXECUTION_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _EXEC_TERMINALS_V2 = new Set([
+  EXECUTION_LIFECYCLE_V2.SUCCEEDED,
+  EXECUTION_LIFECYCLE_V2.FAILED,
+  EXECUTION_LIFECYCLE_V2.CANCELLED,
+]);
+
+export const SKILL_DEFAULT_MAX_ACTIVE_PER_OWNER = 30;
+export const SKILL_DEFAULT_MAX_PENDING_EXECUTIONS_PER_SKILL = 5;
+export const SKILL_DEFAULT_SKILL_IDLE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+export const SKILL_DEFAULT_EXEC_STUCK_MS = 15 * 60 * 1000; // 15 min
+
+const _stateV2 = {
+  skills: new Map(),
+  executions: new Map(),
+  maxActiveSkillsPerOwner: SKILL_DEFAULT_MAX_ACTIVE_PER_OWNER,
+  maxPendingExecutionsPerSkill: SKILL_DEFAULT_MAX_PENDING_EXECUTIONS_PER_SKILL,
+  skillIdleMs: SKILL_DEFAULT_SKILL_IDLE_MS,
+  execStuckMs: SKILL_DEFAULT_EXEC_STUCK_MS,
+};
+
+function _posIntSkillV2(n, label) {
+  const v = Math.floor(Number(n));
+  if (!Number.isFinite(v) || v <= 0) {
+    throw new Error(`${label} must be a positive integer, got ${n}`);
+  }
+  return v;
+}
+
+export function getMaxActiveSkillsPerOwnerV2() {
+  return _stateV2.maxActiveSkillsPerOwner;
+}
+
+export function setMaxActiveSkillsPerOwnerV2(n) {
+  _stateV2.maxActiveSkillsPerOwner = _posIntSkillV2(
+    n,
+    "maxActiveSkillsPerOwner",
+  );
+}
+
+export function getMaxPendingExecutionsPerSkillV2() {
+  return _stateV2.maxPendingExecutionsPerSkill;
+}
+
+export function setMaxPendingExecutionsPerSkillV2(n) {
+  _stateV2.maxPendingExecutionsPerSkill = _posIntSkillV2(
+    n,
+    "maxPendingExecutionsPerSkill",
+  );
+}
+
+export function getSkillIdleMsV2() {
+  return _stateV2.skillIdleMs;
+}
+
+export function setSkillIdleMsV2(ms) {
+  _stateV2.skillIdleMs = _posIntSkillV2(ms, "skillIdleMs");
+}
+
+export function getExecStuckMsV2() {
+  return _stateV2.execStuckMs;
+}
+
+export function setExecStuckMsV2(ms) {
+  _stateV2.execStuckMs = _posIntSkillV2(ms, "execStuckMs");
+}
+
+function _copySkillV2(s) {
+  return { ...s, metadata: { ...s.metadata } };
+}
+
+function _copyExecV2(e) {
+  return { ...e, metadata: { ...e.metadata } };
+}
+
+export function getActiveSkillCountV2(ownerId) {
+  let count = 0;
+  for (const s of _stateV2.skills.values()) {
+    if (s.ownerId === ownerId && s.status === SKILL_MATURITY_V2.ACTIVE) count++;
+  }
+  return count;
+}
+
+export function getPendingExecutionCountV2(skillId) {
+  let count = 0;
+  for (const e of _stateV2.executions.values()) {
+    if (
+      e.skillId === skillId &&
+      (e.status === EXECUTION_LIFECYCLE_V2.QUEUED ||
+        e.status === EXECUTION_LIFECYCLE_V2.RUNNING)
+    ) {
+      count++;
+    }
+  }
+  return count;
+}
+
+export function registerSkillV2(id, { ownerId, name, layer, metadata } = {}) {
+  if (!id) throw new Error("skill id is required");
+  if (!ownerId) throw new Error("ownerId is required");
+  if (!name) throw new Error("name is required");
+  if (_stateV2.skills.has(id)) throw new Error(`skill ${id} already exists`);
+  const now = Date.now();
+  const skill = {
+    id,
+    ownerId,
+    name,
+    layer: layer || "workspace",
+    status: SKILL_MATURITY_V2.PENDING,
+    createdAt: now,
+    lastSeenAt: now,
+    activatedAt: null,
+    archivedAt: null,
+    metadata: metadata ? { ...metadata } : {},
+  };
+  _stateV2.skills.set(id, skill);
+  return _copySkillV2(skill);
+}
+
+export function getSkillV2(id) {
+  const s = _stateV2.skills.get(id);
+  return s ? _copySkillV2(s) : null;
+}
+
+export function listSkillsV2({ ownerId, status, layer } = {}) {
+  const out = [];
+  for (const s of _stateV2.skills.values()) {
+    if (ownerId && s.ownerId !== ownerId) continue;
+    if (status && s.status !== status) continue;
+    if (layer && s.layer !== layer) continue;
+    out.push(_copySkillV2(s));
+  }
+  return out;
+}
+
+export function setSkillStatusV2(id, next) {
+  const s = _stateV2.skills.get(id);
+  if (!s) throw new Error(`skill ${id} not found`);
+  const allowed = _SKILL_TRANSITIONS_V2.get(s.status);
+  if (!allowed || !allowed.has(next)) {
+    throw new Error(`invalid skill transition: ${s.status} → ${next}`);
+  }
+  if (
+    s.status === SKILL_MATURITY_V2.PENDING &&
+    next === SKILL_MATURITY_V2.ACTIVE
+  ) {
+    const count = getActiveSkillCountV2(s.ownerId);
+    if (count >= _stateV2.maxActiveSkillsPerOwner) {
+      throw new Error(
+        `owner ${s.ownerId} active-skill cap reached (${count}/${_stateV2.maxActiveSkillsPerOwner})`,
+      );
+    }
+  }
+  const now = Date.now();
+  s.status = next;
+  s.lastSeenAt = now;
+  if (next === SKILL_MATURITY_V2.ACTIVE && !s.activatedAt) s.activatedAt = now;
+  if (_SKILL_TERMINALS_V2.has(next) && !s.archivedAt) s.archivedAt = now;
+  return _copySkillV2(s);
+}
+
+export function activateSkillV2(id) {
+  return setSkillStatusV2(id, SKILL_MATURITY_V2.ACTIVE);
+}
+
+export function deprecateSkillV2(id) {
+  return setSkillStatusV2(id, SKILL_MATURITY_V2.DEPRECATED);
+}
+
+export function archiveSkillV2(id) {
+  return setSkillStatusV2(id, SKILL_MATURITY_V2.ARCHIVED);
+}
+
+export function touchSkillV2(id) {
+  const s = _stateV2.skills.get(id);
+  if (!s) throw new Error(`skill ${id} not found`);
+  s.lastSeenAt = Date.now();
+  return _copySkillV2(s);
+}
+
+export function createExecutionV2(id, { skillId, kind, metadata } = {}) {
+  if (!id) throw new Error("execution id is required");
+  if (!skillId) throw new Error("skillId is required");
+  if (_stateV2.executions.has(id))
+    throw new Error(`execution ${id} already exists`);
+  const skill = _stateV2.skills.get(skillId);
+  if (!skill) throw new Error(`skill ${skillId} not found`);
+  const pending = getPendingExecutionCountV2(skillId);
+  if (pending >= _stateV2.maxPendingExecutionsPerSkill) {
+    throw new Error(
+      `skill ${skillId} pending-execution cap reached (${pending}/${_stateV2.maxPendingExecutionsPerSkill})`,
+    );
+  }
+  const now = Date.now();
+  const exec = {
+    id,
+    skillId,
+    kind: kind || "invoke",
+    status: EXECUTION_LIFECYCLE_V2.QUEUED,
+    createdAt: now,
+    lastSeenAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: metadata ? { ...metadata } : {},
+  };
+  _stateV2.executions.set(id, exec);
+  return _copyExecV2(exec);
+}
+
+export function getExecutionV2(id) {
+  const e = _stateV2.executions.get(id);
+  return e ? _copyExecV2(e) : null;
+}
+
+export function listExecutionsV2({ skillId, status } = {}) {
+  const out = [];
+  for (const e of _stateV2.executions.values()) {
+    if (skillId && e.skillId !== skillId) continue;
+    if (status && e.status !== status) continue;
+    out.push(_copyExecV2(e));
+  }
+  return out;
+}
+
+export function setExecutionStatusV2(id, next) {
+  const e = _stateV2.executions.get(id);
+  if (!e) throw new Error(`execution ${id} not found`);
+  const allowed = _EXEC_TRANSITIONS_V2.get(e.status);
+  if (!allowed || !allowed.has(next)) {
+    throw new Error(`invalid execution transition: ${e.status} → ${next}`);
+  }
+  const now = Date.now();
+  e.status = next;
+  e.lastSeenAt = now;
+  if (next === EXECUTION_LIFECYCLE_V2.RUNNING && !e.startedAt)
+    e.startedAt = now;
+  if (_EXEC_TERMINALS_V2.has(next) && !e.settledAt) e.settledAt = now;
+  return _copyExecV2(e);
+}
+
+export function startExecutionV2(id) {
+  return setExecutionStatusV2(id, EXECUTION_LIFECYCLE_V2.RUNNING);
+}
+
+export function succeedExecutionV2(id) {
+  return setExecutionStatusV2(id, EXECUTION_LIFECYCLE_V2.SUCCEEDED);
+}
+
+export function failExecutionV2(id) {
+  return setExecutionStatusV2(id, EXECUTION_LIFECYCLE_V2.FAILED);
+}
+
+export function cancelExecutionV2(id) {
+  return setExecutionStatusV2(id, EXECUTION_LIFECYCLE_V2.CANCELLED);
+}
+
+export function autoDeprecateIdleSkillsV2({ now = Date.now() } = {}) {
+  const flipped = [];
+  for (const s of _stateV2.skills.values()) {
+    if (
+      s.status === SKILL_MATURITY_V2.ACTIVE &&
+      now - s.lastSeenAt > _stateV2.skillIdleMs
+    ) {
+      s.status = SKILL_MATURITY_V2.DEPRECATED;
+      s.lastSeenAt = now;
+      flipped.push(_copySkillV2(s));
+    }
+  }
+  return flipped;
+}
+
+export function autoFailStuckExecutionsV2({ now = Date.now() } = {}) {
+  const flipped = [];
+  for (const e of _stateV2.executions.values()) {
+    if (
+      e.status === EXECUTION_LIFECYCLE_V2.RUNNING &&
+      now - e.lastSeenAt > _stateV2.execStuckMs
+    ) {
+      e.status = EXECUTION_LIFECYCLE_V2.FAILED;
+      e.lastSeenAt = now;
+      if (!e.settledAt) e.settledAt = now;
+      flipped.push(_copyExecV2(e));
+    }
+  }
+  return flipped;
+}
+
+export function getSkillLoaderStatsV2() {
+  const skillsByStatus = {};
+  for (const v of Object.values(SKILL_MATURITY_V2)) skillsByStatus[v] = 0;
+  for (const s of _stateV2.skills.values()) skillsByStatus[s.status]++;
+
+  const executionsByStatus = {};
+  for (const v of Object.values(EXECUTION_LIFECYCLE_V2))
+    executionsByStatus[v] = 0;
+  for (const e of _stateV2.executions.values()) executionsByStatus[e.status]++;
+
+  return {
+    totalSkillsV2: _stateV2.skills.size,
+    totalExecutionsV2: _stateV2.executions.size,
+    maxActiveSkillsPerOwner: _stateV2.maxActiveSkillsPerOwner,
+    maxPendingExecutionsPerSkill: _stateV2.maxPendingExecutionsPerSkill,
+    skillIdleMs: _stateV2.skillIdleMs,
+    execStuckMs: _stateV2.execStuckMs,
+    skillsByStatus,
+    executionsByStatus,
+  };
+}
+
+export function _resetStateSkillLoaderV2() {
+  _stateV2.skills.clear();
+  _stateV2.executions.clear();
+  _stateV2.maxActiveSkillsPerOwner = SKILL_DEFAULT_MAX_ACTIVE_PER_OWNER;
+  _stateV2.maxPendingExecutionsPerSkill =
+    SKILL_DEFAULT_MAX_PENDING_EXECUTIONS_PER_SKILL;
+  _stateV2.skillIdleMs = SKILL_DEFAULT_SKILL_IDLE_MS;
+  _stateV2.execStuckMs = SKILL_DEFAULT_EXEC_STUCK_MS;
+}

package/src/lib/slot-filler.js

@@ -596,3 +596,84 @@ Keep values concise (single words or short strings).`;
     return Object.keys(REQUIRED_SLOTS);
   }
 }
+
+// ===== V2 Surface: Slot Filler governance overlay (CLI v0.142.0) =====
+export const SLOTF_PROFILE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", STALE: "stale", ARCHIVED: "archived",
+});
+export const SLOTF_FILL_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", FILLING: "filling", FILLED: "filled", FAILED: "failed", CANCELLED: "cancelled",
+});
+const _slotfPTrans = new Map([
+  [SLOTF_PROFILE_MATURITY_V2.PENDING, new Set([SLOTF_PROFILE_MATURITY_V2.ACTIVE, SLOTF_PROFILE_MATURITY_V2.ARCHIVED])],
+  [SLOTF_PROFILE_MATURITY_V2.ACTIVE, new Set([SLOTF_PROFILE_MATURITY_V2.STALE, SLOTF_PROFILE_MATURITY_V2.ARCHIVED])],
+  [SLOTF_PROFILE_MATURITY_V2.STALE, new Set([SLOTF_PROFILE_MATURITY_V2.ACTIVE, SLOTF_PROFILE_MATURITY_V2.ARCHIVED])],
+  [SLOTF_PROFILE_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _slotfPTerminal = new Set([SLOTF_PROFILE_MATURITY_V2.ARCHIVED]);
+const _slotfFTrans = new Map([
+  [SLOTF_FILL_LIFECYCLE_V2.QUEUED, new Set([SLOTF_FILL_LIFECYCLE_V2.FILLING, SLOTF_FILL_LIFECYCLE_V2.CANCELLED])],
+  [SLOTF_FILL_LIFECYCLE_V2.FILLING, new Set([SLOTF_FILL_LIFECYCLE_V2.FILLED, SLOTF_FILL_LIFECYCLE_V2.FAILED, SLOTF_FILL_LIFECYCLE_V2.CANCELLED])],
+  [SLOTF_FILL_LIFECYCLE_V2.FILLED, new Set()],
+  [SLOTF_FILL_LIFECYCLE_V2.FAILED, new Set()],
+  [SLOTF_FILL_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+const _slotfPsV2 = new Map();
+const _slotfFsV2 = new Map();
+let _slotfMaxActive = 10, _slotfMaxPending = 20, _slotfIdleMs = 30 * 24 * 60 * 60 * 1000, _slotfStuckMs = 30 * 1000;
+function _slotfPos(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 _slotfCheckP(from, to) { const a = _slotfPTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid slotf profile transition ${from} → ${to}`); }
+function _slotfCheckF(from, to) { const a = _slotfFTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid slotf fill transition ${from} → ${to}`); }
+export function setMaxActiveSlotfTemplatesPerOwnerV2(n) { _slotfMaxActive = _slotfPos(n, "maxActiveSlotfTemplatesPerOwner"); }
+export function getMaxActiveSlotfTemplatesPerOwnerV2() { return _slotfMaxActive; }
+export function setMaxPendingSlotfFillsPerTemplateV2(n) { _slotfMaxPending = _slotfPos(n, "maxPendingSlotfFillsPerTemplate"); }
+export function getMaxPendingSlotfFillsPerTemplateV2() { return _slotfMaxPending; }
+export function setSlotfTemplateIdleMsV2(n) { _slotfIdleMs = _slotfPos(n, "slotfTemplateIdleMs"); }
+export function getSlotfTemplateIdleMsV2() { return _slotfIdleMs; }
+export function setSlotfFillStuckMsV2(n) { _slotfStuckMs = _slotfPos(n, "slotfFillStuckMs"); }
+export function getSlotfFillStuckMsV2() { return _slotfStuckMs; }
+export function _resetStateSlotFillerV2() { _slotfPsV2.clear(); _slotfFsV2.clear(); _slotfMaxActive = 10; _slotfMaxPending = 20; _slotfIdleMs = 30 * 24 * 60 * 60 * 1000; _slotfStuckMs = 30 * 1000; }
+export function registerSlotfTemplateV2({ id, owner, schema, metadata } = {}) {
+  if (!id) throw new Error("slotf template id required"); if (!owner) throw new Error("slotf template owner required");
+  if (_slotfPsV2.has(id)) throw new Error(`slotf template ${id} already registered`);
+  const now = Date.now();
+  const p = { id, owner, schema: schema || "{}", status: SLOTF_PROFILE_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, archivedAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _slotfPsV2.set(id, p); return { ...p, metadata: { ...p.metadata } };
+}
+function _slotfCountActive(owner) { let n = 0; for (const p of _slotfPsV2.values()) if (p.owner === owner && p.status === SLOTF_PROFILE_MATURITY_V2.ACTIVE) n++; return n; }
+export function activateSlotfTemplateV2(id) {
+  const p = _slotfPsV2.get(id); if (!p) throw new Error(`slotf template ${id} not found`);
+  _slotfCheckP(p.status, SLOTF_PROFILE_MATURITY_V2.ACTIVE);
+  const recovery = p.status === SLOTF_PROFILE_MATURITY_V2.STALE;
+  if (!recovery && _slotfCountActive(p.owner) >= _slotfMaxActive) throw new Error(`max active slotf templates for owner ${p.owner} reached`);
+  const now = Date.now(); p.status = SLOTF_PROFILE_MATURITY_V2.ACTIVE; p.updatedAt = now; p.lastTouchedAt = now; if (!p.activatedAt) p.activatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function staleSlotfTemplateV2(id) { const p = _slotfPsV2.get(id); if (!p) throw new Error(`slotf template ${id} not found`); _slotfCheckP(p.status, SLOTF_PROFILE_MATURITY_V2.STALE); p.status = SLOTF_PROFILE_MATURITY_V2.STALE; p.updatedAt = Date.now(); return { ...p, metadata: { ...p.metadata } }; }
+export function archiveSlotfTemplateV2(id) { const p = _slotfPsV2.get(id); if (!p) throw new Error(`slotf template ${id} not found`); _slotfCheckP(p.status, SLOTF_PROFILE_MATURITY_V2.ARCHIVED); const now = Date.now(); p.status = SLOTF_PROFILE_MATURITY_V2.ARCHIVED; p.updatedAt = now; if (!p.archivedAt) p.archivedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function touchSlotfTemplateV2(id) { const p = _slotfPsV2.get(id); if (!p) throw new Error(`slotf template ${id} not found`); if (_slotfPTerminal.has(p.status)) throw new Error(`cannot touch terminal slotf template ${id}`); const now = Date.now(); p.lastTouchedAt = now; p.updatedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function getSlotfTemplateV2(id) { const p = _slotfPsV2.get(id); if (!p) return null; return { ...p, metadata: { ...p.metadata } }; }
+export function listSlotfTemplatesV2() { return [..._slotfPsV2.values()].map((p) => ({ ...p, metadata: { ...p.metadata } })); }
+function _slotfCountPending(templateId) { let n = 0; for (const f of _slotfFsV2.values()) if (f.templateId === templateId && (f.status === SLOTF_FILL_LIFECYCLE_V2.QUEUED || f.status === SLOTF_FILL_LIFECYCLE_V2.FILLING)) n++; return n; }
+export function createSlotfFillV2({ id, templateId, input, metadata } = {}) {
+  if (!id) throw new Error("slotf fill id required"); if (!templateId) throw new Error("slotf fill templateId required");
+  if (_slotfFsV2.has(id)) throw new Error(`slotf fill ${id} already exists`);
+  if (!_slotfPsV2.has(templateId)) throw new Error(`slotf template ${templateId} not found`);
+  if (_slotfCountPending(templateId) >= _slotfMaxPending) throw new Error(`max pending slotf fills for template ${templateId} reached`);
+  const now = Date.now();
+  const f = { id, templateId, input: input || "", status: SLOTF_FILL_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _slotfFsV2.set(id, f); return { ...f, metadata: { ...f.metadata } };
+}
+export function fillingSlotfFillV2(id) { const f = _slotfFsV2.get(id); if (!f) throw new Error(`slotf fill ${id} not found`); _slotfCheckF(f.status, SLOTF_FILL_LIFECYCLE_V2.FILLING); const now = Date.now(); f.status = SLOTF_FILL_LIFECYCLE_V2.FILLING; f.updatedAt = now; if (!f.startedAt) f.startedAt = now; return { ...f, metadata: { ...f.metadata } }; }
+export function fillSlotfFillV2(id) { const f = _slotfFsV2.get(id); if (!f) throw new Error(`slotf fill ${id} not found`); _slotfCheckF(f.status, SLOTF_FILL_LIFECYCLE_V2.FILLED); const now = Date.now(); f.status = SLOTF_FILL_LIFECYCLE_V2.FILLED; f.updatedAt = now; if (!f.settledAt) f.settledAt = now; return { ...f, metadata: { ...f.metadata } }; }
+export function failSlotfFillV2(id, reason) { const f = _slotfFsV2.get(id); if (!f) throw new Error(`slotf fill ${id} not found`); _slotfCheckF(f.status, SLOTF_FILL_LIFECYCLE_V2.FAILED); const now = Date.now(); f.status = SLOTF_FILL_LIFECYCLE_V2.FAILED; f.updatedAt = now; if (!f.settledAt) f.settledAt = now; if (reason) f.metadata.failReason = String(reason); return { ...f, metadata: { ...f.metadata } }; }
+export function cancelSlotfFillV2(id, reason) { const f = _slotfFsV2.get(id); if (!f) throw new Error(`slotf fill ${id} not found`); _slotfCheckF(f.status, SLOTF_FILL_LIFECYCLE_V2.CANCELLED); const now = Date.now(); f.status = SLOTF_FILL_LIFECYCLE_V2.CANCELLED; f.updatedAt = now; if (!f.settledAt) f.settledAt = now; if (reason) f.metadata.cancelReason = String(reason); return { ...f, metadata: { ...f.metadata } }; }
+export function getSlotfFillV2(id) { const f = _slotfFsV2.get(id); if (!f) return null; return { ...f, metadata: { ...f.metadata } }; }
+export function listSlotfFillsV2() { return [..._slotfFsV2.values()].map((f) => ({ ...f, metadata: { ...f.metadata } })); }
+export function autoStaleIdleSlotfTemplatesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const p of _slotfPsV2.values()) if (p.status === SLOTF_PROFILE_MATURITY_V2.ACTIVE && (t - p.lastTouchedAt) >= _slotfIdleMs) { p.status = SLOTF_PROFILE_MATURITY_V2.STALE; p.updatedAt = t; flipped.push(p.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckSlotfFillsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const f of _slotfFsV2.values()) if (f.status === SLOTF_FILL_LIFECYCLE_V2.FILLING && f.startedAt != null && (t - f.startedAt) >= _slotfStuckMs) { f.status = SLOTF_FILL_LIFECYCLE_V2.FAILED; f.updatedAt = t; if (!f.settledAt) f.settledAt = t; f.metadata.failReason = "auto-fail-stuck"; flipped.push(f.id); } return { flipped, count: flipped.length }; }
+export function getSlotFillerGovStatsV2() {
+  const templatesByStatus = {}; for (const v of Object.values(SLOTF_PROFILE_MATURITY_V2)) templatesByStatus[v] = 0; for (const p of _slotfPsV2.values()) templatesByStatus[p.status]++;
+  const fillsByStatus = {}; for (const v of Object.values(SLOTF_FILL_LIFECYCLE_V2)) fillsByStatus[v] = 0; for (const f of _slotfFsV2.values()) fillsByStatus[f.status]++;
+  return { totalSlotfTemplatesV2: _slotfPsV2.size, totalSlotfFillsV2: _slotfFsV2.size, maxActiveSlotfTemplatesPerOwner: _slotfMaxActive, maxPendingSlotfFillsPerTemplate: _slotfMaxPending, slotfTemplateIdleMs: _slotfIdleMs, slotfFillStuckMs: _slotfStuckMs, templatesByStatus, fillsByStatus };
+}