chainlesschain 0.81.0 → 0.143.0

package/src/lib/memory-manager.js

@@ -209,3 +209,333 @@ export function updateMemoryFile(memoryDir, content) {
   fs.writeFileSync(filePath, content, "utf8");
   return { path: filePath };
 }
+
+/* ═══════════════════════════════════════════════════════════════
+ * V2 Surface — Memory governance layer.
+ * Tracks per-category entry maturity + consolidation job lifecycle
+ * independent of legacy SQLite memory_entries table.
+ * ═══════════════════════════════════════════════════════════════ */
+
+export const ENTRY_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  PARKED: "parked",
+  ARCHIVED: "archived",
+});
+
+export const CONSOLIDATION_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  SUCCEEDED: "succeeded",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const ENTRY_TRANSITIONS_V2 = new Map([
+  ["pending", new Set(["active", "archived"])],
+  ["active", new Set(["parked", "archived"])],
+  ["parked", new Set(["active", "archived"])],
+  ["archived", new Set()],
+]);
+const ENTRY_TERMINALS_V2 = new Set(["archived"]);
+
+const JOB_TRANSITIONS_V2 = new Map([
+  ["queued", new Set(["running", "cancelled"])],
+  ["running", new Set(["succeeded", "failed", "cancelled"])],
+  ["succeeded", new Set()],
+  ["failed", new Set()],
+  ["cancelled", new Set()],
+]);
+const JOB_TERMINALS_V2 = new Set(["succeeded", "failed", "cancelled"]);
+
+export const MEMORY_DEFAULT_MAX_ACTIVE_ENTRIES_PER_CATEGORY = 200;
+export const MEMORY_DEFAULT_MAX_RUNNING_JOBS_PER_SOURCE = 2;
+export const MEMORY_DEFAULT_ENTRY_IDLE_MS = 1000 * 60 * 60 * 24 * 90; // 90 days
+export const MEMORY_DEFAULT_JOB_STUCK_MS = 1000 * 60 * 10; // 10 minutes
+
+const _entriesV2 = new Map();
+const _jobsV2 = new Map();
+let _maxActiveEntriesPerCategoryV2 =
+  MEMORY_DEFAULT_MAX_ACTIVE_ENTRIES_PER_CATEGORY;
+let _maxRunningJobsPerSourceV2 = MEMORY_DEFAULT_MAX_RUNNING_JOBS_PER_SOURCE;
+let _entryIdleMsV2 = MEMORY_DEFAULT_ENTRY_IDLE_MS;
+let _jobStuckMsV2 = MEMORY_DEFAULT_JOB_STUCK_MS;
+
+function _posIntMemoryV2(n, label) {
+  const v = Math.floor(Number(n));
+  if (!Number.isFinite(v) || v <= 0)
+    throw new Error(`${label} must be a positive integer`);
+  return v;
+}
+
+export function getMaxActiveEntriesPerCategoryV2() {
+  return _maxActiveEntriesPerCategoryV2;
+}
+export function setMaxActiveEntriesPerCategoryV2(n) {
+  _maxActiveEntriesPerCategoryV2 = _posIntMemoryV2(
+    n,
+    "maxActiveEntriesPerCategory",
+  );
+}
+export function getMaxRunningJobsPerSourceV2() {
+  return _maxRunningJobsPerSourceV2;
+}
+export function setMaxRunningJobsPerSourceV2(n) {
+  _maxRunningJobsPerSourceV2 = _posIntMemoryV2(n, "maxRunningJobsPerSource");
+}
+export function getEntryIdleMsV2() {
+  return _entryIdleMsV2;
+}
+export function setEntryIdleMsV2(n) {
+  _entryIdleMsV2 = _posIntMemoryV2(n, "entryIdleMs");
+}
+export function getJobStuckMsV2() {
+  return _jobStuckMsV2;
+}
+export function setJobStuckMsV2(n) {
+  _jobStuckMsV2 = _posIntMemoryV2(n, "jobStuckMs");
+}
+
+export function getActiveEntryCountV2(category) {
+  let n = 0;
+  for (const e of _entriesV2.values()) {
+    if (e.category === category && e.status === "active") n += 1;
+  }
+  return n;
+}
+
+export function getRunningJobCountV2(source) {
+  let n = 0;
+  for (const j of _jobsV2.values()) {
+    if (j.source === source && j.status === "running") n += 1;
+  }
+  return n;
+}
+
+function _copyEntryV2(e) {
+  return { ...e, metadata: { ...e.metadata } };
+}
+function _copyJobV2(j) {
+  return { ...j, metadata: { ...j.metadata } };
+}
+
+export function registerEntryV2(
+  id,
+  { category, summary, metadata = {}, now = Date.now() } = {},
+) {
+  if (!id || typeof id !== "string") throw new Error("id must be a string");
+  if (!category || typeof category !== "string")
+    throw new Error("category must be a string");
+  if (!summary || typeof summary !== "string")
+    throw new Error("summary must be a string");
+  if (_entriesV2.has(id)) throw new Error(`entry ${id} already exists`);
+  const e = {
+    id,
+    category,
+    summary,
+    status: "pending",
+    createdAt: now,
+    lastSeenAt: now,
+    activatedAt: null,
+    archivedAt: null,
+    metadata: { ...metadata },
+  };
+  _entriesV2.set(id, e);
+  return _copyEntryV2(e);
+}
+
+export function getEntryV2(id) {
+  const e = _entriesV2.get(id);
+  return e ? _copyEntryV2(e) : null;
+}
+
+export function listEntriesV2({ category, status } = {}) {
+  const out = [];
+  for (const e of _entriesV2.values()) {
+    if (category && e.category !== category) continue;
+    if (status && e.status !== status) continue;
+    out.push(_copyEntryV2(e));
+  }
+  return out;
+}
+
+export function setEntryStatusV2(id, next, { now = Date.now() } = {}) {
+  const e = _entriesV2.get(id);
+  if (!e) throw new Error(`entry ${id} not found`);
+  if (!ENTRY_TRANSITIONS_V2.has(next))
+    throw new Error(`unknown entry status: ${next}`);
+  if (ENTRY_TERMINALS_V2.has(e.status))
+    throw new Error(`entry ${id} is in terminal state ${e.status}`);
+  const allowed = ENTRY_TRANSITIONS_V2.get(e.status);
+  if (!allowed.has(next))
+    throw new Error(`cannot transition entry from ${e.status} to ${next}`);
+  if (next === "active") {
+    if (e.status === "pending") {
+      const count = getActiveEntryCountV2(e.category);
+      if (count >= _maxActiveEntriesPerCategoryV2)
+        throw new Error(
+          `category ${e.category} already at active-entry cap (${_maxActiveEntriesPerCategoryV2})`,
+        );
+    }
+    if (!e.activatedAt) e.activatedAt = now;
+  }
+  if (next === "archived" && !e.archivedAt) e.archivedAt = now;
+  e.status = next;
+  e.lastSeenAt = now;
+  return _copyEntryV2(e);
+}
+
+export function activateEntryV2(id, opts) {
+  return setEntryStatusV2(id, "active", opts);
+}
+export function parkEntryV2(id, opts) {
+  return setEntryStatusV2(id, "parked", opts);
+}
+export function archiveEntryV2(id, opts) {
+  return setEntryStatusV2(id, "archived", opts);
+}
+
+export function touchEntryV2(id, { now = Date.now() } = {}) {
+  const e = _entriesV2.get(id);
+  if (!e) throw new Error(`entry ${id} not found`);
+  e.lastSeenAt = now;
+  return _copyEntryV2(e);
+}
+
+export function createConsolidationJobV2(
+  id,
+  { source, scope, metadata = {}, now = Date.now() } = {},
+) {
+  if (!id || typeof id !== "string") throw new Error("id must be a string");
+  if (!source || typeof source !== "string")
+    throw new Error("source must be a string");
+  if (!scope || typeof scope !== "string")
+    throw new Error("scope must be a string");
+  if (_jobsV2.has(id)) throw new Error(`job ${id} already exists`);
+  const j = {
+    id,
+    source,
+    scope,
+    status: "queued",
+    createdAt: now,
+    lastSeenAt: now,
+    startedAt: null,
+    finishedAt: null,
+    metadata: { ...metadata },
+  };
+  _jobsV2.set(id, j);
+  return _copyJobV2(j);
+}
+
+export function getConsolidationJobV2(id) {
+  const j = _jobsV2.get(id);
+  return j ? _copyJobV2(j) : null;
+}
+
+export function listConsolidationJobsV2({ source, status } = {}) {
+  const out = [];
+  for (const j of _jobsV2.values()) {
+    if (source && j.source !== source) continue;
+    if (status && j.status !== status) continue;
+    out.push(_copyJobV2(j));
+  }
+  return out;
+}
+
+export function setJobStatusV2(id, next, { now = Date.now() } = {}) {
+  const j = _jobsV2.get(id);
+  if (!j) throw new Error(`job ${id} not found`);
+  if (!JOB_TRANSITIONS_V2.has(next))
+    throw new Error(`unknown job status: ${next}`);
+  if (JOB_TERMINALS_V2.has(j.status))
+    throw new Error(`job ${id} is in terminal state ${j.status}`);
+  const allowed = JOB_TRANSITIONS_V2.get(j.status);
+  if (!allowed.has(next))
+    throw new Error(`cannot transition job from ${j.status} to ${next}`);
+  if (next === "running") {
+    if (j.status === "queued") {
+      const count = getRunningJobCountV2(j.source);
+      if (count >= _maxRunningJobsPerSourceV2)
+        throw new Error(
+          `source ${j.source} already at running-job cap (${_maxRunningJobsPerSourceV2})`,
+        );
+    }
+    if (!j.startedAt) j.startedAt = now;
+  }
+  if (JOB_TERMINALS_V2.has(next) && !j.finishedAt) j.finishedAt = now;
+  j.status = next;
+  j.lastSeenAt = now;
+  return _copyJobV2(j);
+}
+
+export function startConsolidationJobV2(id, opts) {
+  return setJobStatusV2(id, "running", opts);
+}
+export function succeedConsolidationJobV2(id, opts) {
+  return setJobStatusV2(id, "succeeded", opts);
+}
+export function failConsolidationJobV2(id, opts) {
+  return setJobStatusV2(id, "failed", opts);
+}
+export function cancelConsolidationJobV2(id, opts) {
+  return setJobStatusV2(id, "cancelled", opts);
+}
+
+export function autoParkIdleEntriesV2({ now = Date.now() } = {}) {
+  const flipped = [];
+  for (const e of _entriesV2.values()) {
+    if (e.status !== "active") continue;
+    if (now - e.lastSeenAt > _entryIdleMsV2) {
+      e.status = "parked";
+      e.lastSeenAt = now;
+      flipped.push(_copyEntryV2(e));
+    }
+  }
+  return flipped;
+}
+
+export function autoFailStuckJobsV2({ now = Date.now() } = {}) {
+  const flipped = [];
+  for (const j of _jobsV2.values()) {
+    if (j.status !== "running") continue;
+    if (now - j.lastSeenAt > _jobStuckMsV2) {
+      j.status = "failed";
+      j.lastSeenAt = now;
+      if (!j.finishedAt) j.finishedAt = now;
+      flipped.push(_copyJobV2(j));
+    }
+  }
+  return flipped;
+}
+
+export function getMemoryManagerStatsV2() {
+  const entriesByStatus = {};
+  for (const v of Object.values(ENTRY_MATURITY_V2)) entriesByStatus[v] = 0;
+  for (const e of _entriesV2.values()) entriesByStatus[e.status] += 1;
+
+  const jobsByStatus = {};
+  for (const v of Object.values(CONSOLIDATION_LIFECYCLE_V2))
+    jobsByStatus[v] = 0;
+  for (const j of _jobsV2.values()) jobsByStatus[j.status] += 1;
+
+  return {
+    totalEntriesV2: _entriesV2.size,
+    totalJobsV2: _jobsV2.size,
+    maxActiveEntriesPerCategory: _maxActiveEntriesPerCategoryV2,
+    maxRunningJobsPerSource: _maxRunningJobsPerSourceV2,
+    entryIdleMs: _entryIdleMsV2,
+    jobStuckMs: _jobStuckMsV2,
+    entriesByStatus,
+    jobsByStatus,
+  };
+}
+
+export function _resetStateMemoryManagerV2() {
+  _entriesV2.clear();
+  _jobsV2.clear();
+  _maxActiveEntriesPerCategoryV2 =
+    MEMORY_DEFAULT_MAX_ACTIVE_ENTRIES_PER_CATEGORY;
+  _maxRunningJobsPerSourceV2 = MEMORY_DEFAULT_MAX_RUNNING_JOBS_PER_SOURCE;
+  _entryIdleMsV2 = MEMORY_DEFAULT_ENTRY_IDLE_MS;
+  _jobStuckMsV2 = MEMORY_DEFAULT_JOB_STUCK_MS;
+}

package/src/lib/multimodal.js

@@ -723,3 +723,349 @@ export function getMultimodalStats(db) {
 export function _resetState() {
   _contextCache.clear();
 }
+
+/* ═════════════════════════════════════════════════════════ *
+ *  Phase 27 V2 — Session Maturity + Artifact Lifecycle
+ * ═════════════════════════════════════════════════════════ */
+
+export const SESSION_MATURITY_V2 = Object.freeze({
+  ONBOARDING: "onboarding",
+  ACTIVE: "active",
+  PAUSED: "paused",
+  COMPLETED: "completed",
+  ARCHIVED: "archived",
+});
+
+export const ARTIFACT_LIFECYCLE_V2 = Object.freeze({
+  PENDING: "pending",
+  READY: "ready",
+  PURGED: "purged",
+});
+
+const SESSION_TRANSITIONS_V2 = new Map([
+  ["onboarding", new Set(["active", "archived"])],
+  ["active", new Set(["paused", "completed", "archived"])],
+  ["paused", new Set(["active", "completed", "archived"])],
+  ["completed", new Set(["archived"])],
+]);
+const SESSION_TERMINALS_V2 = new Set(["archived"]);
+
+const ARTIFACT_TRANSITIONS_V2 = new Map([
+  ["pending", new Set(["ready", "purged"])],
+  ["ready", new Set(["purged"])],
+]);
+const ARTIFACT_TERMINALS_V2 = new Set(["purged"]);
+
+export const MM_DEFAULT_MAX_ACTIVE_SESSIONS_PER_OWNER = 50;
+export const MM_DEFAULT_MAX_ARTIFACTS_PER_SESSION = 200;
+export const MM_DEFAULT_SESSION_IDLE_MS = 30 * 86400000;
+export const MM_DEFAULT_ARTIFACT_STALE_MS = 14 * 86400000;
+
+let _maxActiveSessionsPerOwnerV2 = MM_DEFAULT_MAX_ACTIVE_SESSIONS_PER_OWNER;
+let _maxArtifactsPerSessionV2 = MM_DEFAULT_MAX_ARTIFACTS_PER_SESSION;
+let _sessionIdleMsV2 = MM_DEFAULT_SESSION_IDLE_MS;
+let _artifactStaleMsV2 = MM_DEFAULT_ARTIFACT_STALE_MS;
+
+function _positiveIntV2(n, label) {
+  const v = Math.floor(Number(n));
+  if (!Number.isFinite(v) || v <= 0)
+    throw new Error(`${label} must be a positive integer`);
+  return v;
+}
+
+export function getDefaultMaxActiveSessionsPerOwnerV2() {
+  return MM_DEFAULT_MAX_ACTIVE_SESSIONS_PER_OWNER;
+}
+export function getMaxActiveSessionsPerOwnerV2() {
+  return _maxActiveSessionsPerOwnerV2;
+}
+export function setMaxActiveSessionsPerOwnerV2(n) {
+  return (_maxActiveSessionsPerOwnerV2 = _positiveIntV2(
+    n,
+    "maxActiveSessionsPerOwner",
+  ));
+}
+export function getDefaultMaxArtifactsPerSessionV2() {
+  return MM_DEFAULT_MAX_ARTIFACTS_PER_SESSION;
+}
+export function getMaxArtifactsPerSessionV2() {
+  return _maxArtifactsPerSessionV2;
+}
+export function setMaxArtifactsPerSessionV2(n) {
+  return (_maxArtifactsPerSessionV2 = _positiveIntV2(
+    n,
+    "maxArtifactsPerSession",
+  ));
+}
+export function getDefaultSessionIdleMsV2() {
+  return MM_DEFAULT_SESSION_IDLE_MS;
+}
+export function getSessionIdleMsV2() {
+  return _sessionIdleMsV2;
+}
+export function setSessionIdleMsV2(ms) {
+  return (_sessionIdleMsV2 = _positiveIntV2(ms, "sessionIdleMs"));
+}
+export function getDefaultArtifactStaleMsV2() {
+  return MM_DEFAULT_ARTIFACT_STALE_MS;
+}
+export function getArtifactStaleMsV2() {
+  return _artifactStaleMsV2;
+}
+export function setArtifactStaleMsV2(ms) {
+  return (_artifactStaleMsV2 = _positiveIntV2(ms, "artifactStaleMs"));
+}
+
+const _sessionsV2 = new Map();
+const _artifactsV2 = new Map();
+
+export function registerSessionV2(
+  _db,
+  { sessionId, ownerId, title, initialStatus, metadata } = {},
+) {
+  if (!sessionId) throw new Error("sessionId is required");
+  if (!ownerId) throw new Error("ownerId is required");
+  if (_sessionsV2.has(sessionId))
+    throw new Error(`Session ${sessionId} already exists`);
+  const status = initialStatus || SESSION_MATURITY_V2.ONBOARDING;
+  if (!Object.values(SESSION_MATURITY_V2).includes(status))
+    throw new Error(`Invalid initial status: ${status}`);
+  if (SESSION_TERMINALS_V2.has(status))
+    throw new Error(`Cannot register in terminal status: ${status}`);
+  if (status === SESSION_MATURITY_V2.ACTIVE) {
+    if (getActiveSessionCount(ownerId) >= _maxActiveSessionsPerOwnerV2)
+      throw new Error(
+        `Owner ${ownerId} reached active-session cap (${_maxActiveSessionsPerOwnerV2})`,
+      );
+  }
+  const now = Date.now();
+  const record = {
+    sessionId,
+    ownerId,
+    title: title || "",
+    status,
+    metadata: metadata || {},
+    createdAt: now,
+    updatedAt: now,
+    lastActivityAt: now,
+  };
+  _sessionsV2.set(sessionId, record);
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getSessionV2(sessionId) {
+  const r = _sessionsV2.get(sessionId);
+  return r ? { ...r, metadata: { ...r.metadata } } : null;
+}
+
+export function setSessionMaturityV2(_db, sessionId, newStatus, patch = {}) {
+  const record = _sessionsV2.get(sessionId);
+  if (!record) throw new Error(`Unknown session: ${sessionId}`);
+  if (!Object.values(SESSION_MATURITY_V2).includes(newStatus))
+    throw new Error(`Invalid status: ${newStatus}`);
+  const allowed = SESSION_TRANSITIONS_V2.get(record.status) || new Set();
+  if (!allowed.has(newStatus))
+    throw new Error(`Invalid transition: ${record.status} -> ${newStatus}`);
+  if (newStatus === SESSION_MATURITY_V2.ACTIVE) {
+    if (getActiveSessionCount(record.ownerId) >= _maxActiveSessionsPerOwnerV2)
+      throw new Error(
+        `Owner ${record.ownerId} reached active-session cap (${_maxActiveSessionsPerOwnerV2})`,
+      );
+  }
+  record.status = newStatus;
+  record.updatedAt = Date.now();
+  if (patch.reason !== undefined) record.lastReason = patch.reason;
+  if (patch.metadata)
+    record.metadata = { ...record.metadata, ...patch.metadata };
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function activateSession(db, sessionId, reason) {
+  return setSessionMaturityV2(db, sessionId, SESSION_MATURITY_V2.ACTIVE, {
+    reason,
+  });
+}
+export function pauseSession(db, sessionId, reason) {
+  return setSessionMaturityV2(db, sessionId, SESSION_MATURITY_V2.PAUSED, {
+    reason,
+  });
+}
+export function completeSessionV2(db, sessionId, reason) {
+  return setSessionMaturityV2(db, sessionId, SESSION_MATURITY_V2.COMPLETED, {
+    reason,
+  });
+}
+export function archiveSession(db, sessionId, reason) {
+  return setSessionMaturityV2(db, sessionId, SESSION_MATURITY_V2.ARCHIVED, {
+    reason,
+  });
+}
+
+export function touchSessionActivity(sessionId) {
+  const record = _sessionsV2.get(sessionId);
+  if (!record) throw new Error(`Unknown session: ${sessionId}`);
+  record.lastActivityAt = Date.now();
+  record.updatedAt = record.lastActivityAt;
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function registerArtifactV2(
+  _db,
+  { artifactId, sessionId, modality, size, initialStatus, metadata } = {},
+) {
+  if (!artifactId) throw new Error("artifactId is required");
+  if (!sessionId) throw new Error("sessionId is required");
+  if (!modality) throw new Error("modality is required");
+  if (!MODALITIES.includes(modality))
+    throw new Error(`Invalid modality: ${modality}`);
+  if (_artifactsV2.has(artifactId))
+    throw new Error(`Artifact ${artifactId} already exists`);
+  const status = initialStatus || ARTIFACT_LIFECYCLE_V2.PENDING;
+  if (!Object.values(ARTIFACT_LIFECYCLE_V2).includes(status))
+    throw new Error(`Invalid initial status: ${status}`);
+  if (ARTIFACT_TERMINALS_V2.has(status))
+    throw new Error(`Cannot register in terminal status: ${status}`);
+  if (getArtifactCount(sessionId) >= _maxArtifactsPerSessionV2)
+    throw new Error(
+      `Session ${sessionId} reached artifact cap (${_maxArtifactsPerSessionV2})`,
+    );
+  const now = Date.now();
+  const record = {
+    artifactId,
+    sessionId,
+    modality,
+    size: size || 0,
+    status,
+    metadata: metadata || {},
+    createdAt: now,
+    updatedAt: now,
+    lastAccessAt: now,
+  };
+  _artifactsV2.set(artifactId, record);
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getArtifactV2(artifactId) {
+  const r = _artifactsV2.get(artifactId);
+  return r ? { ...r, metadata: { ...r.metadata } } : null;
+}
+
+export function setArtifactStatusV2(_db, artifactId, newStatus, patch = {}) {
+  const record = _artifactsV2.get(artifactId);
+  if (!record) throw new Error(`Unknown artifact: ${artifactId}`);
+  if (!Object.values(ARTIFACT_LIFECYCLE_V2).includes(newStatus))
+    throw new Error(`Invalid status: ${newStatus}`);
+  const allowed = ARTIFACT_TRANSITIONS_V2.get(record.status) || new Set();
+  if (!allowed.has(newStatus))
+    throw new Error(`Invalid transition: ${record.status} -> ${newStatus}`);
+  record.status = newStatus;
+  record.updatedAt = Date.now();
+  if (patch.reason !== undefined) record.lastReason = patch.reason;
+  if (patch.metadata)
+    record.metadata = { ...record.metadata, ...patch.metadata };
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function markArtifactReady(db, artifactId, reason) {
+  return setArtifactStatusV2(db, artifactId, ARTIFACT_LIFECYCLE_V2.READY, {
+    reason,
+  });
+}
+export function purgeArtifact(db, artifactId, reason) {
+  return setArtifactStatusV2(db, artifactId, ARTIFACT_LIFECYCLE_V2.PURGED, {
+    reason,
+  });
+}
+
+export function touchArtifactAccess(artifactId) {
+  const record = _artifactsV2.get(artifactId);
+  if (!record) throw new Error(`Unknown artifact: ${artifactId}`);
+  record.lastAccessAt = Date.now();
+  record.updatedAt = record.lastAccessAt;
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getActiveSessionCount(ownerId) {
+  let n = 0;
+  for (const r of _sessionsV2.values()) {
+    if (r.status !== SESSION_MATURITY_V2.ACTIVE) continue;
+    if (ownerId && r.ownerId !== ownerId) continue;
+    n++;
+  }
+  return n;
+}
+
+export function getArtifactCount(sessionId) {
+  let n = 0;
+  for (const r of _artifactsV2.values()) {
+    if (ARTIFACT_TERMINALS_V2.has(r.status)) continue;
+    if (sessionId && r.sessionId !== sessionId) continue;
+    n++;
+  }
+  return n;
+}
+
+export function autoArchiveIdleSessions(_db, nowMs) {
+  const now = nowMs ?? Date.now();
+  const flipped = [];
+  for (const r of _sessionsV2.values()) {
+    if (
+      r.status === SESSION_MATURITY_V2.ACTIVE ||
+      r.status === SESSION_MATURITY_V2.PAUSED ||
+      r.status === SESSION_MATURITY_V2.COMPLETED
+    ) {
+      if (now - r.lastActivityAt > _sessionIdleMsV2) {
+        r.status = SESSION_MATURITY_V2.ARCHIVED;
+        r.updatedAt = now;
+        r.lastReason = "idle";
+        flipped.push(r.sessionId);
+      }
+    }
+  }
+  return { flipped, count: flipped.length };
+}
+
+export function autoPurgeStaleArtifacts(_db, nowMs) {
+  const now = nowMs ?? Date.now();
+  const flipped = [];
+  for (const r of _artifactsV2.values()) {
+    if (r.status === ARTIFACT_LIFECYCLE_V2.READY) {
+      if (now - r.lastAccessAt > _artifactStaleMsV2) {
+        r.status = ARTIFACT_LIFECYCLE_V2.PURGED;
+        r.updatedAt = now;
+        r.lastReason = "stale";
+        flipped.push(r.artifactId);
+      }
+    }
+  }
+  return { flipped, count: flipped.length };
+}
+
+export function getMultimodalStatsV2() {
+  const sessionsByStatus = {};
+  for (const s of Object.values(SESSION_MATURITY_V2)) sessionsByStatus[s] = 0;
+  const artifactsByStatus = {};
+  for (const s of Object.values(ARTIFACT_LIFECYCLE_V2))
+    artifactsByStatus[s] = 0;
+  for (const r of _sessionsV2.values()) sessionsByStatus[r.status]++;
+  for (const r of _artifactsV2.values()) artifactsByStatus[r.status]++;
+  return {
+    totalSessionsV2: _sessionsV2.size,
+    totalArtifactsV2: _artifactsV2.size,
+    maxActiveSessionsPerOwner: _maxActiveSessionsPerOwnerV2,
+    maxArtifactsPerSession: _maxArtifactsPerSessionV2,
+    sessionIdleMs: _sessionIdleMsV2,
+    artifactStaleMs: _artifactStaleMsV2,
+    sessionsByStatus,
+    artifactsByStatus,
+  };
+}
+
+export function _resetStateV2() {
+  _maxActiveSessionsPerOwnerV2 = MM_DEFAULT_MAX_ACTIVE_SESSIONS_PER_OWNER;
+  _maxArtifactsPerSessionV2 = MM_DEFAULT_MAX_ARTIFACTS_PER_SESSION;
+  _sessionIdleMsV2 = MM_DEFAULT_SESSION_IDLE_MS;
+  _artifactStaleMsV2 = MM_DEFAULT_ARTIFACT_STALE_MS;
+  _sessionsV2.clear();
+  _artifactsV2.clear();
+}