chainlesschain 0.132.0 → 0.145.0

package/src/lib/autonomous-agent.js

@@ -492,3 +492,344 @@ Reply with a JSON object: { "action": "retry|add_step|skip", "newParams": {...},
     return null;
   }
 }
+
+// ===== V2 Surface: Autonomous Agent governance overlay (CLI v0.138.0) =====
+export const AUTOAGENT_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  PAUSED: "paused",
+  ARCHIVED: "archived",
+});
+export const AUTOAGENT_RUN_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const _aaTrans = new Map([
+  [
+    AUTOAGENT_MATURITY_V2.PENDING,
+    new Set([AUTOAGENT_MATURITY_V2.ACTIVE, AUTOAGENT_MATURITY_V2.ARCHIVED]),
+  ],
+  [
+    AUTOAGENT_MATURITY_V2.ACTIVE,
+    new Set([AUTOAGENT_MATURITY_V2.PAUSED, AUTOAGENT_MATURITY_V2.ARCHIVED]),
+  ],
+  [
+    AUTOAGENT_MATURITY_V2.PAUSED,
+    new Set([AUTOAGENT_MATURITY_V2.ACTIVE, AUTOAGENT_MATURITY_V2.ARCHIVED]),
+  ],
+  [AUTOAGENT_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _aaTerminal = new Set([AUTOAGENT_MATURITY_V2.ARCHIVED]);
+const _aaRunTrans = new Map([
+  [
+    AUTOAGENT_RUN_LIFECYCLE_V2.QUEUED,
+    new Set([
+      AUTOAGENT_RUN_LIFECYCLE_V2.RUNNING,
+      AUTOAGENT_RUN_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [
+    AUTOAGENT_RUN_LIFECYCLE_V2.RUNNING,
+    new Set([
+      AUTOAGENT_RUN_LIFECYCLE_V2.COMPLETED,
+      AUTOAGENT_RUN_LIFECYCLE_V2.FAILED,
+      AUTOAGENT_RUN_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [AUTOAGENT_RUN_LIFECYCLE_V2.COMPLETED, new Set()],
+  [AUTOAGENT_RUN_LIFECYCLE_V2.FAILED, new Set()],
+  [AUTOAGENT_RUN_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _aaAgents = new Map();
+const _aaRuns = new Map();
+let _aaMaxActivePerOwner = 5;
+let _aaMaxPendingRunsPerAgent = 10;
+let _aaAgentIdleMs = 7 * 24 * 60 * 60 * 1000;
+let _aaRunStuckMs = 30 * 60 * 1000;
+
+function _aaPos(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 setMaxActiveAutoAgentsPerOwnerV2(n) {
+  _aaMaxActivePerOwner = _aaPos(n, "maxActiveAutoAgentsPerOwner");
+}
+export function getMaxActiveAutoAgentsPerOwnerV2() {
+  return _aaMaxActivePerOwner;
+}
+export function setMaxPendingAutoAgentRunsPerAgentV2(n) {
+  _aaMaxPendingRunsPerAgent = _aaPos(n, "maxPendingAutoAgentRunsPerAgent");
+}
+export function getMaxPendingAutoAgentRunsPerAgentV2() {
+  return _aaMaxPendingRunsPerAgent;
+}
+export function setAutoAgentIdleMsV2(n) {
+  _aaAgentIdleMs = _aaPos(n, "autoAgentIdleMs");
+}
+export function getAutoAgentIdleMsV2() {
+  return _aaAgentIdleMs;
+}
+export function setAutoAgentRunStuckMsV2(n) {
+  _aaRunStuckMs = _aaPos(n, "autoAgentRunStuckMs");
+}
+export function getAutoAgentRunStuckMsV2() {
+  return _aaRunStuckMs;
+}
+
+export function _resetStateAutonomousAgentV2() {
+  _aaAgents.clear();
+  _aaRuns.clear();
+  _aaMaxActivePerOwner = 5;
+  _aaMaxPendingRunsPerAgent = 10;
+  _aaAgentIdleMs = 7 * 24 * 60 * 60 * 1000;
+  _aaRunStuckMs = 30 * 60 * 1000;
+}
+
+export function registerAutoAgentV2({ id, owner, goal, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_aaAgents.has(id)) throw new Error(`auto-agent ${id} already registered`);
+  const now = Date.now();
+  const a = {
+    id,
+    owner,
+    goal: goal || "",
+    status: AUTOAGENT_MATURITY_V2.PENDING,
+    createdAt: now,
+    updatedAt: now,
+    activatedAt: null,
+    archivedAt: null,
+    lastTouchedAt: now,
+    metadata: { ...(metadata || {}) },
+  };
+  _aaAgents.set(id, a);
+  return { ...a, metadata: { ...a.metadata } };
+}
+function _aaCheckA(from, to) {
+  const a = _aaTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid auto-agent transition ${from} → ${to}`);
+}
+function _aaCountActive(owner) {
+  let n = 0;
+  for (const a of _aaAgents.values())
+    if (a.owner === owner && a.status === AUTOAGENT_MATURITY_V2.ACTIVE) n++;
+  return n;
+}
+
+export function activateAutoAgentV2(id) {
+  const a = _aaAgents.get(id);
+  if (!a) throw new Error(`auto-agent ${id} not found`);
+  _aaCheckA(a.status, AUTOAGENT_MATURITY_V2.ACTIVE);
+  const recovery = a.status === AUTOAGENT_MATURITY_V2.PAUSED;
+  if (!recovery) {
+    const c = _aaCountActive(a.owner);
+    if (c >= _aaMaxActivePerOwner)
+      throw new Error(
+        `max active auto-agents per owner (${_aaMaxActivePerOwner}) reached for ${a.owner}`,
+      );
+  }
+  const now = Date.now();
+  a.status = AUTOAGENT_MATURITY_V2.ACTIVE;
+  a.updatedAt = now;
+  a.lastTouchedAt = now;
+  if (!a.activatedAt) a.activatedAt = now;
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function pauseAutoAgentV2(id) {
+  const a = _aaAgents.get(id);
+  if (!a) throw new Error(`auto-agent ${id} not found`);
+  _aaCheckA(a.status, AUTOAGENT_MATURITY_V2.PAUSED);
+  a.status = AUTOAGENT_MATURITY_V2.PAUSED;
+  a.updatedAt = Date.now();
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function archiveAutoAgentV2(id) {
+  const a = _aaAgents.get(id);
+  if (!a) throw new Error(`auto-agent ${id} not found`);
+  _aaCheckA(a.status, AUTOAGENT_MATURITY_V2.ARCHIVED);
+  const now = Date.now();
+  a.status = AUTOAGENT_MATURITY_V2.ARCHIVED;
+  a.updatedAt = now;
+  if (!a.archivedAt) a.archivedAt = now;
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function touchAutoAgentV2(id) {
+  const a = _aaAgents.get(id);
+  if (!a) throw new Error(`auto-agent ${id} not found`);
+  if (_aaTerminal.has(a.status))
+    throw new Error(`cannot touch terminal auto-agent ${id}`);
+  const now = Date.now();
+  a.lastTouchedAt = now;
+  a.updatedAt = now;
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function getAutoAgentV2(id) {
+  const a = _aaAgents.get(id);
+  if (!a) return null;
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function listAutoAgentsV2() {
+  return [..._aaAgents.values()].map((a) => ({
+    ...a,
+    metadata: { ...a.metadata },
+  }));
+}
+
+function _aaCountPendingRuns(aid) {
+  let n = 0;
+  for (const r of _aaRuns.values())
+    if (
+      r.agentId === aid &&
+      (r.status === AUTOAGENT_RUN_LIFECYCLE_V2.QUEUED ||
+        r.status === AUTOAGENT_RUN_LIFECYCLE_V2.RUNNING)
+    )
+      n++;
+  return n;
+}
+
+export function createAutoAgentRunV2({ id, agentId, prompt, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!agentId || typeof agentId !== "string")
+    throw new Error("agentId is required");
+  if (_aaRuns.has(id)) throw new Error(`auto-agent run ${id} already exists`);
+  if (!_aaAgents.has(agentId))
+    throw new Error(`auto-agent ${agentId} not found`);
+  const pending = _aaCountPendingRuns(agentId);
+  if (pending >= _aaMaxPendingRunsPerAgent)
+    throw new Error(
+      `max pending auto-agent runs per agent (${_aaMaxPendingRunsPerAgent}) reached for ${agentId}`,
+    );
+  const now = Date.now();
+  const r = {
+    id,
+    agentId,
+    prompt: prompt || "",
+    status: AUTOAGENT_RUN_LIFECYCLE_V2.QUEUED,
+    createdAt: now,
+    updatedAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: { ...(metadata || {}) },
+  };
+  _aaRuns.set(id, r);
+  return { ...r, metadata: { ...r.metadata } };
+}
+function _aaCheckR(from, to) {
+  const a = _aaRunTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid auto-agent run transition ${from} → ${to}`);
+}
+export function startAutoAgentRunV2(id) {
+  const r = _aaRuns.get(id);
+  if (!r) throw new Error(`auto-agent run ${id} not found`);
+  _aaCheckR(r.status, AUTOAGENT_RUN_LIFECYCLE_V2.RUNNING);
+  const now = Date.now();
+  r.status = AUTOAGENT_RUN_LIFECYCLE_V2.RUNNING;
+  r.updatedAt = now;
+  if (!r.startedAt) r.startedAt = now;
+  return { ...r, metadata: { ...r.metadata } };
+}
+export function completeAutoAgentRunV2(id) {
+  const r = _aaRuns.get(id);
+  if (!r) throw new Error(`auto-agent run ${id} not found`);
+  _aaCheckR(r.status, AUTOAGENT_RUN_LIFECYCLE_V2.COMPLETED);
+  const now = Date.now();
+  r.status = AUTOAGENT_RUN_LIFECYCLE_V2.COMPLETED;
+  r.updatedAt = now;
+  if (!r.settledAt) r.settledAt = now;
+  return { ...r, metadata: { ...r.metadata } };
+}
+export function failAutoAgentRunV2(id, reason) {
+  const r = _aaRuns.get(id);
+  if (!r) throw new Error(`auto-agent run ${id} not found`);
+  _aaCheckR(r.status, AUTOAGENT_RUN_LIFECYCLE_V2.FAILED);
+  const now = Date.now();
+  r.status = AUTOAGENT_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 cancelAutoAgentRunV2(id, reason) {
+  const r = _aaRuns.get(id);
+  if (!r) throw new Error(`auto-agent run ${id} not found`);
+  _aaCheckR(r.status, AUTOAGENT_RUN_LIFECYCLE_V2.CANCELLED);
+  const now = Date.now();
+  r.status = AUTOAGENT_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 getAutoAgentRunV2(id) {
+  const r = _aaRuns.get(id);
+  if (!r) return null;
+  return { ...r, metadata: { ...r.metadata } };
+}
+export function listAutoAgentRunsV2() {
+  return [..._aaRuns.values()].map((r) => ({
+    ...r,
+    metadata: { ...r.metadata },
+  }));
+}
+
+export function autoPauseIdleAutoAgentsV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const a of _aaAgents.values())
+    if (
+      a.status === AUTOAGENT_MATURITY_V2.ACTIVE &&
+      t - a.lastTouchedAt >= _aaAgentIdleMs
+    ) {
+      a.status = AUTOAGENT_MATURITY_V2.PAUSED;
+      a.updatedAt = t;
+      flipped.push(a.id);
+    }
+  return { flipped, count: flipped.length };
+}
+export function autoFailStuckAutoAgentRunsV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const r of _aaRuns.values())
+    if (
+      r.status === AUTOAGENT_RUN_LIFECYCLE_V2.RUNNING &&
+      r.startedAt != null &&
+      t - r.startedAt >= _aaRunStuckMs
+    ) {
+      r.status = AUTOAGENT_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 getAutonomousAgentGovStatsV2() {
+  const agentsByStatus = {};
+  for (const s of Object.values(AUTOAGENT_MATURITY_V2)) agentsByStatus[s] = 0;
+  for (const a of _aaAgents.values()) agentsByStatus[a.status]++;
+  const runsByStatus = {};
+  for (const s of Object.values(AUTOAGENT_RUN_LIFECYCLE_V2))
+    runsByStatus[s] = 0;
+  for (const r of _aaRuns.values()) runsByStatus[r.status]++;
+  return {
+    totalAutoAgentsV2: _aaAgents.size,
+    totalAutoAgentRunsV2: _aaRuns.size,
+    maxActiveAutoAgentsPerOwner: _aaMaxActivePerOwner,
+    maxPendingAutoAgentRunsPerAgent: _aaMaxPendingRunsPerAgent,
+    autoAgentIdleMs: _aaAgentIdleMs,
+    autoAgentRunStuckMs: _aaRunStuckMs,
+    agentsByStatus,
+    runsByStatus,
+  };
+}

package/src/lib/bi-engine.js

@@ -635,3 +635,342 @@ export function _resetV2State() {
   _reportStatusV2.clear();
   _statusHistoryV2.clear();
 }
+
+// ===== V2 Surface: BI Engine governance overlay (CLI v0.135.0) =====
+export const BI_DATASET_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  STALE: "stale",
+  ARCHIVED: "archived",
+});
+export const BI_QUERY_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const _biDsTrans = new Map([
+  [
+    BI_DATASET_MATURITY_V2.PENDING,
+    new Set([BI_DATASET_MATURITY_V2.ACTIVE, BI_DATASET_MATURITY_V2.ARCHIVED]),
+  ],
+  [
+    BI_DATASET_MATURITY_V2.ACTIVE,
+    new Set([BI_DATASET_MATURITY_V2.STALE, BI_DATASET_MATURITY_V2.ARCHIVED]),
+  ],
+  [
+    BI_DATASET_MATURITY_V2.STALE,
+    new Set([BI_DATASET_MATURITY_V2.ACTIVE, BI_DATASET_MATURITY_V2.ARCHIVED]),
+  ],
+  [BI_DATASET_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _biDsTerminal = new Set([BI_DATASET_MATURITY_V2.ARCHIVED]);
+const _biQTrans = new Map([
+  [
+    BI_QUERY_LIFECYCLE_V2.QUEUED,
+    new Set([BI_QUERY_LIFECYCLE_V2.RUNNING, BI_QUERY_LIFECYCLE_V2.CANCELLED]),
+  ],
+  [
+    BI_QUERY_LIFECYCLE_V2.RUNNING,
+    new Set([
+      BI_QUERY_LIFECYCLE_V2.COMPLETED,
+      BI_QUERY_LIFECYCLE_V2.FAILED,
+      BI_QUERY_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [BI_QUERY_LIFECYCLE_V2.COMPLETED, new Set()],
+  [BI_QUERY_LIFECYCLE_V2.FAILED, new Set()],
+  [BI_QUERY_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _biDatasets = new Map();
+const _biQueries = new Map();
+let _biMaxActivePerOwner = 8;
+let _biMaxPendingPerDs = 10;
+let _biDsIdleMs = 7 * 24 * 60 * 60 * 1000;
+let _biQStuckMs = 5 * 60 * 1000;
+
+function _biPos(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 setMaxActiveBiDatasetsPerOwnerV2(n) {
+  _biMaxActivePerOwner = _biPos(n, "maxActiveBiDatasetsPerOwner");
+}
+export function getMaxActiveBiDatasetsPerOwnerV2() {
+  return _biMaxActivePerOwner;
+}
+export function setMaxPendingBiQueriesPerDatasetV2(n) {
+  _biMaxPendingPerDs = _biPos(n, "maxPendingBiQueriesPerDataset");
+}
+export function getMaxPendingBiQueriesPerDatasetV2() {
+  return _biMaxPendingPerDs;
+}
+export function setBiDatasetIdleMsV2(n) {
+  _biDsIdleMs = _biPos(n, "biDatasetIdleMs");
+}
+export function getBiDatasetIdleMsV2() {
+  return _biDsIdleMs;
+}
+export function setBiQueryStuckMsV2(n) {
+  _biQStuckMs = _biPos(n, "biQueryStuckMs");
+}
+export function getBiQueryStuckMsV2() {
+  return _biQStuckMs;
+}
+
+export function _resetStateBiEngineV2() {
+  _biDatasets.clear();
+  _biQueries.clear();
+  _biMaxActivePerOwner = 8;
+  _biMaxPendingPerDs = 10;
+  _biDsIdleMs = 7 * 24 * 60 * 60 * 1000;
+  _biQStuckMs = 5 * 60 * 1000;
+}
+
+export function registerBiDatasetV2({ id, owner, source, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_biDatasets.has(id))
+    throw new Error(`bi dataset ${id} already registered`);
+  const now = Date.now();
+  const d = {
+    id,
+    owner,
+    source: source || "",
+    status: BI_DATASET_MATURITY_V2.PENDING,
+    createdAt: now,
+    updatedAt: now,
+    activatedAt: null,
+    archivedAt: null,
+    lastTouchedAt: now,
+    metadata: { ...(metadata || {}) },
+  };
+  _biDatasets.set(id, d);
+  return { ...d, metadata: { ...d.metadata } };
+}
+function _biCheckD(from, to) {
+  const a = _biDsTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid bi dataset transition ${from} → ${to}`);
+}
+function _biCountActive(owner) {
+  let n = 0;
+  for (const d of _biDatasets.values())
+    if (d.owner === owner && d.status === BI_DATASET_MATURITY_V2.ACTIVE) n++;
+  return n;
+}
+
+export function activateBiDatasetV2(id) {
+  const d = _biDatasets.get(id);
+  if (!d) throw new Error(`bi dataset ${id} not found`);
+  _biCheckD(d.status, BI_DATASET_MATURITY_V2.ACTIVE);
+  const recovery = d.status === BI_DATASET_MATURITY_V2.STALE;
+  if (!recovery) {
+    const a = _biCountActive(d.owner);
+    if (a >= _biMaxActivePerOwner)
+      throw new Error(
+        `max active bi datasets per owner (${_biMaxActivePerOwner}) reached for ${d.owner}`,
+      );
+  }
+  const now = Date.now();
+  d.status = BI_DATASET_MATURITY_V2.ACTIVE;
+  d.updatedAt = now;
+  d.lastTouchedAt = now;
+  if (!d.activatedAt) d.activatedAt = now;
+  return { ...d, metadata: { ...d.metadata } };
+}
+export function staleBiDatasetV2(id) {
+  const d = _biDatasets.get(id);
+  if (!d) throw new Error(`bi dataset ${id} not found`);
+  _biCheckD(d.status, BI_DATASET_MATURITY_V2.STALE);
+  d.status = BI_DATASET_MATURITY_V2.STALE;
+  d.updatedAt = Date.now();
+  return { ...d, metadata: { ...d.metadata } };
+}
+export function archiveBiDatasetV2(id) {
+  const d = _biDatasets.get(id);
+  if (!d) throw new Error(`bi dataset ${id} not found`);
+  _biCheckD(d.status, BI_DATASET_MATURITY_V2.ARCHIVED);
+  const now = Date.now();
+  d.status = BI_DATASET_MATURITY_V2.ARCHIVED;
+  d.updatedAt = now;
+  if (!d.archivedAt) d.archivedAt = now;
+  return { ...d, metadata: { ...d.metadata } };
+}
+export function touchBiDatasetV2(id) {
+  const d = _biDatasets.get(id);
+  if (!d) throw new Error(`bi dataset ${id} not found`);
+  if (_biDsTerminal.has(d.status))
+    throw new Error(`cannot touch terminal bi dataset ${id}`);
+  const now = Date.now();
+  d.lastTouchedAt = now;
+  d.updatedAt = now;
+  return { ...d, metadata: { ...d.metadata } };
+}
+export function getBiDatasetV2(id) {
+  const d = _biDatasets.get(id);
+  if (!d) return null;
+  return { ...d, metadata: { ...d.metadata } };
+}
+export function listBiDatasetsV2() {
+  return [..._biDatasets.values()].map((d) => ({
+    ...d,
+    metadata: { ...d.metadata },
+  }));
+}
+
+function _biCountPending(did) {
+  let n = 0;
+  for (const q of _biQueries.values())
+    if (
+      q.datasetId === did &&
+      (q.status === BI_QUERY_LIFECYCLE_V2.QUEUED ||
+        q.status === BI_QUERY_LIFECYCLE_V2.RUNNING)
+    )
+      n++;
+  return n;
+}
+
+export function createBiQueryV2({ id, datasetId, sql, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!datasetId || typeof datasetId !== "string")
+    throw new Error("datasetId is required");
+  if (_biQueries.has(id)) throw new Error(`bi query ${id} already exists`);
+  if (!_biDatasets.has(datasetId))
+    throw new Error(`bi dataset ${datasetId} not found`);
+  const pending = _biCountPending(datasetId);
+  if (pending >= _biMaxPendingPerDs)
+    throw new Error(
+      `max pending bi queries per dataset (${_biMaxPendingPerDs}) reached for ${datasetId}`,
+    );
+  const now = Date.now();
+  const q = {
+    id,
+    datasetId,
+    sql: sql || "",
+    status: BI_QUERY_LIFECYCLE_V2.QUEUED,
+    createdAt: now,
+    updatedAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: { ...(metadata || {}) },
+  };
+  _biQueries.set(id, q);
+  return { ...q, metadata: { ...q.metadata } };
+}
+function _biCheckQ(from, to) {
+  const a = _biQTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid bi query transition ${from} → ${to}`);
+}
+export function startBiQueryV2(id) {
+  const q = _biQueries.get(id);
+  if (!q) throw new Error(`bi query ${id} not found`);
+  _biCheckQ(q.status, BI_QUERY_LIFECYCLE_V2.RUNNING);
+  const now = Date.now();
+  q.status = BI_QUERY_LIFECYCLE_V2.RUNNING;
+  q.updatedAt = now;
+  if (!q.startedAt) q.startedAt = now;
+  return { ...q, metadata: { ...q.metadata } };
+}
+export function completeBiQueryV2(id) {
+  const q = _biQueries.get(id);
+  if (!q) throw new Error(`bi query ${id} not found`);
+  _biCheckQ(q.status, BI_QUERY_LIFECYCLE_V2.COMPLETED);
+  const now = Date.now();
+  q.status = BI_QUERY_LIFECYCLE_V2.COMPLETED;
+  q.updatedAt = now;
+  if (!q.settledAt) q.settledAt = now;
+  return { ...q, metadata: { ...q.metadata } };
+}
+export function failBiQueryV2(id, reason) {
+  const q = _biQueries.get(id);
+  if (!q) throw new Error(`bi query ${id} not found`);
+  _biCheckQ(q.status, BI_QUERY_LIFECYCLE_V2.FAILED);
+  const now = Date.now();
+  q.status = BI_QUERY_LIFECYCLE_V2.FAILED;
+  q.updatedAt = now;
+  if (!q.settledAt) q.settledAt = now;
+  if (reason) q.metadata.failReason = String(reason);
+  return { ...q, metadata: { ...q.metadata } };
+}
+export function cancelBiQueryV2(id, reason) {
+  const q = _biQueries.get(id);
+  if (!q) throw new Error(`bi query ${id} not found`);
+  _biCheckQ(q.status, BI_QUERY_LIFECYCLE_V2.CANCELLED);
+  const now = Date.now();
+  q.status = BI_QUERY_LIFECYCLE_V2.CANCELLED;
+  q.updatedAt = now;
+  if (!q.settledAt) q.settledAt = now;
+  if (reason) q.metadata.cancelReason = String(reason);
+  return { ...q, metadata: { ...q.metadata } };
+}
+export function getBiQueryV2(id) {
+  const q = _biQueries.get(id);
+  if (!q) return null;
+  return { ...q, metadata: { ...q.metadata } };
+}
+export function listBiQueriesV2() {
+  return [..._biQueries.values()].map((q) => ({
+    ...q,
+    metadata: { ...q.metadata },
+  }));
+}
+
+export function autoStaleIdleBiDatasetsV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const d of _biDatasets.values())
+    if (
+      d.status === BI_DATASET_MATURITY_V2.ACTIVE &&
+      t - d.lastTouchedAt >= _biDsIdleMs
+    ) {
+      d.status = BI_DATASET_MATURITY_V2.STALE;
+      d.updatedAt = t;
+      flipped.push(d.id);
+    }
+  return { flipped, count: flipped.length };
+}
+export function autoFailStuckBiQueriesV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const q of _biQueries.values())
+    if (
+      q.status === BI_QUERY_LIFECYCLE_V2.RUNNING &&
+      q.startedAt != null &&
+      t - q.startedAt >= _biQStuckMs
+    ) {
+      q.status = BI_QUERY_LIFECYCLE_V2.FAILED;
+      q.updatedAt = t;
+      if (!q.settledAt) q.settledAt = t;
+      q.metadata.failReason = "auto-fail-stuck";
+      flipped.push(q.id);
+    }
+  return { flipped, count: flipped.length };
+}
+
+export function getBiEngineStatsV2() {
+  const datasetsByStatus = {};
+  for (const s of Object.values(BI_DATASET_MATURITY_V2))
+    datasetsByStatus[s] = 0;
+  for (const d of _biDatasets.values()) datasetsByStatus[d.status]++;
+  const queriesByStatus = {};
+  for (const s of Object.values(BI_QUERY_LIFECYCLE_V2)) queriesByStatus[s] = 0;
+  for (const q of _biQueries.values()) queriesByStatus[q.status]++;
+  return {
+    totalDatasetsV2: _biDatasets.size,
+    totalQueriesV2: _biQueries.size,
+    maxActiveBiDatasetsPerOwner: _biMaxActivePerOwner,
+    maxPendingBiQueriesPerDataset: _biMaxPendingPerDs,
+    biDatasetIdleMs: _biDsIdleMs,
+    biQueryStuckMs: _biQStuckMs,
+    datasetsByStatus,
+    queriesByStatus,
+  };
+}