chainlesschain 0.81.0 → 0.143.0

package/src/lib/iteration-budget.js

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

package/src/lib/knowledge-exporter.js

@@ -300,3 +300,384 @@ function markdownToSimpleHtml(md) {
     .replace(/^/, "<p>")
     .replace(/$/, "</p>");
 }
+
+// ─── V2 Governance Layer ────────────────────────────────────────────
+//
+// In-memory governance for export targets + export jobs, independent
+// of the SQLite notes table read by legacy export* helpers. V2 tracks
+// target maturity transitions, per-owner active-target caps, per-target
+// pending-job caps, stamp-once timestamps, and bulk auto-flip routines.
+
+export const TARGET_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  PAUSED: "paused",
+  ARCHIVED: "archived",
+});
+
+export const EXPORT_JOB_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const _TARGET_TRANSITIONS_V2 = new Map([
+  [
+    TARGET_MATURITY_V2.PENDING,
+    new Set([TARGET_MATURITY_V2.ACTIVE, TARGET_MATURITY_V2.ARCHIVED]),
+  ],
+  [
+    TARGET_MATURITY_V2.ACTIVE,
+    new Set([TARGET_MATURITY_V2.PAUSED, TARGET_MATURITY_V2.ARCHIVED]),
+  ],
+  [
+    TARGET_MATURITY_V2.PAUSED,
+    new Set([TARGET_MATURITY_V2.ACTIVE, TARGET_MATURITY_V2.ARCHIVED]),
+  ],
+  [TARGET_MATURITY_V2.ARCHIVED, new Set()],
+]);
+
+const _TARGET_TERMINALS_V2 = new Set([TARGET_MATURITY_V2.ARCHIVED]);
+
+const _JOB_TRANSITIONS_V2 = new Map([
+  [
+    EXPORT_JOB_LIFECYCLE_V2.QUEUED,
+    new Set([
+      EXPORT_JOB_LIFECYCLE_V2.RUNNING,
+      EXPORT_JOB_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [
+    EXPORT_JOB_LIFECYCLE_V2.RUNNING,
+    new Set([
+      EXPORT_JOB_LIFECYCLE_V2.COMPLETED,
+      EXPORT_JOB_LIFECYCLE_V2.FAILED,
+      EXPORT_JOB_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [EXPORT_JOB_LIFECYCLE_V2.COMPLETED, new Set()],
+  [EXPORT_JOB_LIFECYCLE_V2.FAILED, new Set()],
+  [EXPORT_JOB_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _JOB_TERMINALS_V2 = new Set([
+  EXPORT_JOB_LIFECYCLE_V2.COMPLETED,
+  EXPORT_JOB_LIFECYCLE_V2.FAILED,
+  EXPORT_JOB_LIFECYCLE_V2.CANCELLED,
+]);
+
+export const EXPORTER_DEFAULT_MAX_ACTIVE_TARGETS_PER_OWNER = 12;
+export const EXPORTER_DEFAULT_MAX_PENDING_JOBS_PER_TARGET = 3;
+export const EXPORTER_DEFAULT_TARGET_IDLE_MS = 14 * 24 * 60 * 60 * 1000; // 14 days
+export const EXPORTER_DEFAULT_JOB_STUCK_MS = 25 * 60 * 1000; // 25 min
+
+const _stateV2 = {
+  targets: new Map(),
+  jobs: new Map(),
+  maxActiveTargetsPerOwner: EXPORTER_DEFAULT_MAX_ACTIVE_TARGETS_PER_OWNER,
+  maxPendingJobsPerTarget: EXPORTER_DEFAULT_MAX_PENDING_JOBS_PER_TARGET,
+  targetIdleMs: EXPORTER_DEFAULT_TARGET_IDLE_MS,
+  jobStuckMs: EXPORTER_DEFAULT_JOB_STUCK_MS,
+};
+
+function _posIntExporterV2(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 getMaxActiveTargetsPerOwnerV2() {
+  return _stateV2.maxActiveTargetsPerOwner;
+}
+
+export function setMaxActiveTargetsPerOwnerV2(n) {
+  _stateV2.maxActiveTargetsPerOwner = _posIntExporterV2(
+    n,
+    "maxActiveTargetsPerOwner",
+  );
+}
+
+export function getMaxPendingJobsPerTargetV2() {
+  return _stateV2.maxPendingJobsPerTarget;
+}
+
+export function setMaxPendingJobsPerTargetV2(n) {
+  _stateV2.maxPendingJobsPerTarget = _posIntExporterV2(
+    n,
+    "maxPendingJobsPerTarget",
+  );
+}
+
+export function getTargetIdleMsV2() {
+  return _stateV2.targetIdleMs;
+}
+
+export function setTargetIdleMsV2(ms) {
+  _stateV2.targetIdleMs = _posIntExporterV2(ms, "targetIdleMs");
+}
+
+export function getJobStuckMsV2() {
+  return _stateV2.jobStuckMs;
+}
+
+export function setJobStuckMsV2(ms) {
+  _stateV2.jobStuckMs = _posIntExporterV2(ms, "jobStuckMs");
+}
+
+function _copyTargetV2(t) {
+  return { ...t, metadata: { ...t.metadata } };
+}
+
+function _copyJobV2(j) {
+  return { ...j, metadata: { ...j.metadata } };
+}
+
+export function getActiveTargetCountV2(ownerId) {
+  let count = 0;
+  for (const t of _stateV2.targets.values()) {
+    if (t.ownerId === ownerId && t.status === TARGET_MATURITY_V2.ACTIVE)
+      count++;
+  }
+  return count;
+}
+
+export function getPendingJobCountV2(targetId) {
+  let count = 0;
+  for (const j of _stateV2.jobs.values()) {
+    if (
+      j.targetId === targetId &&
+      (j.status === EXPORT_JOB_LIFECYCLE_V2.QUEUED ||
+        j.status === EXPORT_JOB_LIFECYCLE_V2.RUNNING)
+    ) {
+      count++;
+    }
+  }
+  return count;
+}
+
+export function registerTargetV2(
+  id,
+  { ownerId, label, format, metadata } = {},
+) {
+  if (!id) throw new Error("target id is required");
+  if (!ownerId) throw new Error("ownerId is required");
+  if (!label) throw new Error("label is required");
+  if (_stateV2.targets.has(id)) throw new Error(`target ${id} already exists`);
+  const now = Date.now();
+  const target = {
+    id,
+    ownerId,
+    label,
+    format: format || "markdown",
+    status: TARGET_MATURITY_V2.PENDING,
+    createdAt: now,
+    lastSeenAt: now,
+    activatedAt: null,
+    archivedAt: null,
+    metadata: metadata ? { ...metadata } : {},
+  };
+  _stateV2.targets.set(id, target);
+  return _copyTargetV2(target);
+}
+
+export function getTargetV2(id) {
+  const t = _stateV2.targets.get(id);
+  return t ? _copyTargetV2(t) : null;
+}
+
+export function listTargetsV2({ ownerId, status } = {}) {
+  const out = [];
+  for (const t of _stateV2.targets.values()) {
+    if (ownerId && t.ownerId !== ownerId) continue;
+    if (status && t.status !== status) continue;
+    out.push(_copyTargetV2(t));
+  }
+  return out;
+}
+
+export function setTargetStatusV2(id, next) {
+  const t = _stateV2.targets.get(id);
+  if (!t) throw new Error(`target ${id} not found`);
+  const allowed = _TARGET_TRANSITIONS_V2.get(t.status);
+  if (!allowed || !allowed.has(next)) {
+    throw new Error(`invalid target transition: ${t.status} → ${next}`);
+  }
+  if (
+    t.status === TARGET_MATURITY_V2.PENDING &&
+    next === TARGET_MATURITY_V2.ACTIVE
+  ) {
+    const count = getActiveTargetCountV2(t.ownerId);
+    if (count >= _stateV2.maxActiveTargetsPerOwner) {
+      throw new Error(
+        `owner ${t.ownerId} active-target cap reached (${count}/${_stateV2.maxActiveTargetsPerOwner})`,
+      );
+    }
+  }
+  const now = Date.now();
+  t.status = next;
+  t.lastSeenAt = now;
+  if (next === TARGET_MATURITY_V2.ACTIVE && !t.activatedAt) t.activatedAt = now;
+  if (_TARGET_TERMINALS_V2.has(next) && !t.archivedAt) t.archivedAt = now;
+  return _copyTargetV2(t);
+}
+
+export function activateTargetV2(id) {
+  return setTargetStatusV2(id, TARGET_MATURITY_V2.ACTIVE);
+}
+
+export function pauseTargetV2(id) {
+  return setTargetStatusV2(id, TARGET_MATURITY_V2.PAUSED);
+}
+
+export function archiveTargetV2(id) {
+  return setTargetStatusV2(id, TARGET_MATURITY_V2.ARCHIVED);
+}
+
+export function touchTargetV2(id) {
+  const t = _stateV2.targets.get(id);
+  if (!t) throw new Error(`target ${id} not found`);
+  t.lastSeenAt = Date.now();
+  return _copyTargetV2(t);
+}
+
+export function createExportJobV2(id, { targetId, kind, metadata } = {}) {
+  if (!id) throw new Error("job id is required");
+  if (!targetId) throw new Error("targetId is required");
+  if (_stateV2.jobs.has(id)) throw new Error(`job ${id} already exists`);
+  const target = _stateV2.targets.get(targetId);
+  if (!target) throw new Error(`target ${targetId} not found`);
+  const pending = getPendingJobCountV2(targetId);
+  if (pending >= _stateV2.maxPendingJobsPerTarget) {
+    throw new Error(
+      `target ${targetId} pending-job cap reached (${pending}/${_stateV2.maxPendingJobsPerTarget})`,
+    );
+  }
+  const now = Date.now();
+  const job = {
+    id,
+    targetId,
+    kind: kind || "snapshot",
+    status: EXPORT_JOB_LIFECYCLE_V2.QUEUED,
+    createdAt: now,
+    lastSeenAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: metadata ? { ...metadata } : {},
+  };
+  _stateV2.jobs.set(id, job);
+  return _copyJobV2(job);
+}
+
+export function getExportJobV2(id) {
+  const j = _stateV2.jobs.get(id);
+  return j ? _copyJobV2(j) : null;
+}
+
+export function listExportJobsV2({ targetId, status } = {}) {
+  const out = [];
+  for (const j of _stateV2.jobs.values()) {
+    if (targetId && j.targetId !== targetId) continue;
+    if (status && j.status !== status) continue;
+    out.push(_copyJobV2(j));
+  }
+  return out;
+}
+
+export function setExportJobStatusV2(id, next) {
+  const j = _stateV2.jobs.get(id);
+  if (!j) throw new Error(`job ${id} not found`);
+  const allowed = _JOB_TRANSITIONS_V2.get(j.status);
+  if (!allowed || !allowed.has(next)) {
+    throw new Error(`invalid job transition: ${j.status} → ${next}`);
+  }
+  const now = Date.now();
+  j.status = next;
+  j.lastSeenAt = now;
+  if (next === EXPORT_JOB_LIFECYCLE_V2.RUNNING && !j.startedAt)
+    j.startedAt = now;
+  if (_JOB_TERMINALS_V2.has(next) && !j.settledAt) j.settledAt = now;
+  return _copyJobV2(j);
+}
+
+export function startExportJobV2(id) {
+  return setExportJobStatusV2(id, EXPORT_JOB_LIFECYCLE_V2.RUNNING);
+}
+
+export function completeExportJobV2(id) {
+  return setExportJobStatusV2(id, EXPORT_JOB_LIFECYCLE_V2.COMPLETED);
+}
+
+export function failExportJobV2(id) {
+  return setExportJobStatusV2(id, EXPORT_JOB_LIFECYCLE_V2.FAILED);
+}
+
+export function cancelExportJobV2(id) {
+  return setExportJobStatusV2(id, EXPORT_JOB_LIFECYCLE_V2.CANCELLED);
+}
+
+export function autoPauseIdleTargetsV2({ now = Date.now() } = {}) {
+  const flipped = [];
+  for (const t of _stateV2.targets.values()) {
+    if (
+      t.status === TARGET_MATURITY_V2.ACTIVE &&
+      now - t.lastSeenAt > _stateV2.targetIdleMs
+    ) {
+      t.status = TARGET_MATURITY_V2.PAUSED;
+      t.lastSeenAt = now;
+      flipped.push(_copyTargetV2(t));
+    }
+  }
+  return flipped;
+}
+
+export function autoFailStuckExportJobsV2({ now = Date.now() } = {}) {
+  const flipped = [];
+  for (const j of _stateV2.jobs.values()) {
+    if (
+      j.status === EXPORT_JOB_LIFECYCLE_V2.RUNNING &&
+      now - j.lastSeenAt > _stateV2.jobStuckMs
+    ) {
+      j.status = EXPORT_JOB_LIFECYCLE_V2.FAILED;
+      j.lastSeenAt = now;
+      if (!j.settledAt) j.settledAt = now;
+      flipped.push(_copyJobV2(j));
+    }
+  }
+  return flipped;
+}
+
+export function getKnowledgeExporterStatsV2() {
+  const targetsByStatus = {};
+  for (const v of Object.values(TARGET_MATURITY_V2)) targetsByStatus[v] = 0;
+  for (const t of _stateV2.targets.values()) targetsByStatus[t.status]++;
+
+  const jobsByStatus = {};
+  for (const v of Object.values(EXPORT_JOB_LIFECYCLE_V2)) jobsByStatus[v] = 0;
+  for (const j of _stateV2.jobs.values()) jobsByStatus[j.status]++;
+
+  return {
+    totalTargetsV2: _stateV2.targets.size,
+    totalExportJobsV2: _stateV2.jobs.size,
+    maxActiveTargetsPerOwner: _stateV2.maxActiveTargetsPerOwner,
+    maxPendingJobsPerTarget: _stateV2.maxPendingJobsPerTarget,
+    targetIdleMs: _stateV2.targetIdleMs,
+    jobStuckMs: _stateV2.jobStuckMs,
+    targetsByStatus,
+    jobsByStatus,
+  };
+}
+
+export function _resetStateKnowledgeExporterV2() {
+  _stateV2.targets.clear();
+  _stateV2.jobs.clear();
+  _stateV2.maxActiveTargetsPerOwner =
+    EXPORTER_DEFAULT_MAX_ACTIVE_TARGETS_PER_OWNER;
+  _stateV2.maxPendingJobsPerTarget =
+    EXPORTER_DEFAULT_MAX_PENDING_JOBS_PER_TARGET;
+  _stateV2.targetIdleMs = EXPORTER_DEFAULT_TARGET_IDLE_MS;
+  _stateV2.jobStuckMs = EXPORTER_DEFAULT_JOB_STUCK_MS;
+}