chainlesschain 0.81.0 → 0.132.0

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();
+}

package/src/lib/nl-programming.js

@@ -593,3 +593,346 @@ export function _resetState() {
   _translations.clear();
   _conventions.clear();
 }
+
+/* ═════════════════════════════════════════════════════════ *
+ *  Phase 28 V2 — Spec Maturity + Dialogue Lifecycle
+ * ═════════════════════════════════════════════════════════ */
+
+export const SPEC_MATURITY_V2 = Object.freeze({
+  DRAFT: "draft",
+  REFINING: "refining",
+  APPROVED: "approved",
+  IMPLEMENTED: "implemented",
+  ARCHIVED: "archived",
+});
+
+export const DIALOGUE_TURN_V2 = Object.freeze({
+  PENDING: "pending",
+  ANSWERED: "answered",
+  DISMISSED: "dismissed",
+  ESCALATED: "escalated",
+});
+
+const SPEC_TRANSITIONS_V2 = new Map([
+  ["draft", new Set(["refining", "approved", "archived"])],
+  ["refining", new Set(["draft", "approved", "archived"])],
+  ["approved", new Set(["refining", "implemented", "archived"])],
+  ["implemented", new Set(["archived"])],
+]);
+const SPEC_TERMINALS_V2 = new Set(["archived"]);
+
+const DIALOGUE_TRANSITIONS_V2 = new Map([
+  ["pending", new Set(["answered", "dismissed", "escalated"])],
+  ["escalated", new Set(["answered", "dismissed"])],
+]);
+const DIALOGUE_TERMINALS_V2 = new Set(["answered", "dismissed"]);
+
+export const NLPROG_DEFAULT_MAX_ACTIVE_SPECS_PER_AUTHOR = 30;
+export const NLPROG_DEFAULT_MAX_PENDING_TURNS_PER_SPEC = 20;
+export const NLPROG_DEFAULT_SPEC_IDLE_MS = 45 * 86400000; // 45d
+export const NLPROG_DEFAULT_TURN_PENDING_MS = 7 * 86400000; // 7d
+
+let _maxActiveSpecsPerAuthorV2 = NLPROG_DEFAULT_MAX_ACTIVE_SPECS_PER_AUTHOR;
+let _maxPendingTurnsPerSpecV2 = NLPROG_DEFAULT_MAX_PENDING_TURNS_PER_SPEC;
+let _specIdleMsV2 = NLPROG_DEFAULT_SPEC_IDLE_MS;
+let _turnPendingMsV2 = NLPROG_DEFAULT_TURN_PENDING_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 getDefaultMaxActiveSpecsPerAuthorV2() {
+  return NLPROG_DEFAULT_MAX_ACTIVE_SPECS_PER_AUTHOR;
+}
+export function getMaxActiveSpecsPerAuthorV2() {
+  return _maxActiveSpecsPerAuthorV2;
+}
+export function setMaxActiveSpecsPerAuthorV2(n) {
+  return (_maxActiveSpecsPerAuthorV2 = _positiveIntV2(
+    n,
+    "maxActiveSpecsPerAuthor",
+  ));
+}
+export function getDefaultMaxPendingTurnsPerSpecV2() {
+  return NLPROG_DEFAULT_MAX_PENDING_TURNS_PER_SPEC;
+}
+export function getMaxPendingTurnsPerSpecV2() {
+  return _maxPendingTurnsPerSpecV2;
+}
+export function setMaxPendingTurnsPerSpecV2(n) {
+  return (_maxPendingTurnsPerSpecV2 = _positiveIntV2(
+    n,
+    "maxPendingTurnsPerSpec",
+  ));
+}
+export function getDefaultSpecIdleMsV2() {
+  return NLPROG_DEFAULT_SPEC_IDLE_MS;
+}
+export function getSpecIdleMsV2() {
+  return _specIdleMsV2;
+}
+export function setSpecIdleMsV2(ms) {
+  return (_specIdleMsV2 = _positiveIntV2(ms, "specIdleMs"));
+}
+export function getDefaultTurnPendingMsV2() {
+  return NLPROG_DEFAULT_TURN_PENDING_MS;
+}
+export function getTurnPendingMsV2() {
+  return _turnPendingMsV2;
+}
+export function setTurnPendingMsV2(ms) {
+  return (_turnPendingMsV2 = _positiveIntV2(ms, "turnPendingMs"));
+}
+
+const _specsV2 = new Map();
+const _turnsV2 = new Map();
+
+function _isActiveSpec(s) {
+  return (
+    s === SPEC_MATURITY_V2.DRAFT ||
+    s === SPEC_MATURITY_V2.REFINING ||
+    s === SPEC_MATURITY_V2.APPROVED
+  );
+}
+
+export function registerSpecV2(
+  _db,
+  { specId, authorId, title, initialStatus, metadata } = {},
+) {
+  if (!specId) throw new Error("specId is required");
+  if (!authorId) throw new Error("authorId is required");
+  if (_specsV2.has(specId)) throw new Error(`Spec ${specId} already exists`);
+  const status = initialStatus || SPEC_MATURITY_V2.DRAFT;
+  if (!Object.values(SPEC_MATURITY_V2).includes(status))
+    throw new Error(`Invalid initial status: ${status}`);
+  if (SPEC_TERMINALS_V2.has(status))
+    throw new Error(`Cannot register in terminal status: ${status}`);
+  if (_isActiveSpec(status)) {
+    if (getActiveSpecCount(authorId) >= _maxActiveSpecsPerAuthorV2)
+      throw new Error(
+        `Author ${authorId} reached active-spec cap (${_maxActiveSpecsPerAuthorV2})`,
+      );
+  }
+  const now = _now();
+  const record = {
+    specId,
+    authorId,
+    title: title || "",
+    status,
+    metadata: metadata || {},
+    createdAt: now,
+    updatedAt: now,
+    lastActivityAt: now,
+  };
+  _specsV2.set(specId, record);
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getSpecV2(specId) {
+  const r = _specsV2.get(specId);
+  return r ? { ...r, metadata: { ...r.metadata } } : null;
+}
+
+export function setSpecMaturityV2(_db, specId, newStatus, patch = {}) {
+  const record = _specsV2.get(specId);
+  if (!record) throw new Error(`Unknown spec: ${specId}`);
+  if (!Object.values(SPEC_MATURITY_V2).includes(newStatus))
+    throw new Error(`Invalid status: ${newStatus}`);
+  const allowed = SPEC_TRANSITIONS_V2.get(record.status) || new Set();
+  if (!allowed.has(newStatus))
+    throw new Error(`Invalid transition: ${record.status} -> ${newStatus}`);
+  if (_isActiveSpec(newStatus) && !_isActiveSpec(record.status)) {
+    if (getActiveSpecCount(record.authorId) >= _maxActiveSpecsPerAuthorV2)
+      throw new Error(
+        `Author ${record.authorId} reached active-spec cap (${_maxActiveSpecsPerAuthorV2})`,
+      );
+  }
+  record.status = newStatus;
+  record.updatedAt = _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 refineSpec(db, id, reason) {
+  return setSpecMaturityV2(db, id, SPEC_MATURITY_V2.REFINING, { reason });
+}
+export function approveSpec(db, id, reason) {
+  return setSpecMaturityV2(db, id, SPEC_MATURITY_V2.APPROVED, { reason });
+}
+export function implementSpec(db, id, reason) {
+  return setSpecMaturityV2(db, id, SPEC_MATURITY_V2.IMPLEMENTED, { reason });
+}
+export function archiveSpec(db, id, reason) {
+  return setSpecMaturityV2(db, id, SPEC_MATURITY_V2.ARCHIVED, { reason });
+}
+
+export function touchSpecActivity(specId) {
+  const record = _specsV2.get(specId);
+  if (!record) throw new Error(`Unknown spec: ${specId}`);
+  record.lastActivityAt = _now();
+  record.updatedAt = record.lastActivityAt;
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function registerDialogueTurnV2(
+  _db,
+  { turnId, specId, role, question, initialStatus, metadata } = {},
+) {
+  if (!turnId) throw new Error("turnId is required");
+  if (!specId) throw new Error("specId is required");
+  if (!_specsV2.has(specId)) throw new Error(`Unknown spec: ${specId}`);
+  if (_turnsV2.has(turnId)) throw new Error(`Turn ${turnId} already exists`);
+  const status = initialStatus || DIALOGUE_TURN_V2.PENDING;
+  if (!Object.values(DIALOGUE_TURN_V2).includes(status))
+    throw new Error(`Invalid initial status: ${status}`);
+  if (DIALOGUE_TERMINALS_V2.has(status))
+    throw new Error(`Cannot register in terminal status: ${status}`);
+  if (status === DIALOGUE_TURN_V2.PENDING) {
+    if (getPendingTurnCount(specId) >= _maxPendingTurnsPerSpecV2)
+      throw new Error(
+        `Spec ${specId} reached pending-turn cap (${_maxPendingTurnsPerSpecV2})`,
+      );
+  }
+  const now = _now();
+  const record = {
+    turnId,
+    specId,
+    role: role || "user",
+    question: question || "",
+    status,
+    metadata: metadata || {},
+    createdAt: now,
+    updatedAt: now,
+  };
+  _turnsV2.set(turnId, record);
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getDialogueTurnV2(turnId) {
+  const r = _turnsV2.get(turnId);
+  return r ? { ...r, metadata: { ...r.metadata } } : null;
+}
+
+export function setDialogueTurnStatusV2(_db, turnId, newStatus, patch = {}) {
+  const record = _turnsV2.get(turnId);
+  if (!record) throw new Error(`Unknown turn: ${turnId}`);
+  if (!Object.values(DIALOGUE_TURN_V2).includes(newStatus))
+    throw new Error(`Invalid status: ${newStatus}`);
+  const allowed = DIALOGUE_TRANSITIONS_V2.get(record.status) || new Set();
+  if (!allowed.has(newStatus))
+    throw new Error(`Invalid transition: ${record.status} -> ${newStatus}`);
+  record.status = newStatus;
+  record.updatedAt = _now();
+  if (patch.answer !== undefined) record.answer = patch.answer;
+  if (patch.reason !== undefined) record.lastReason = patch.reason;
+  if (patch.metadata)
+    record.metadata = { ...record.metadata, ...patch.metadata };
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function answerTurn(db, id, answer, reason) {
+  return setDialogueTurnStatusV2(db, id, DIALOGUE_TURN_V2.ANSWERED, {
+    answer,
+    reason,
+  });
+}
+export function dismissTurn(db, id, reason) {
+  return setDialogueTurnStatusV2(db, id, DIALOGUE_TURN_V2.DISMISSED, {
+    reason,
+  });
+}
+export function escalateTurn(db, id, reason) {
+  return setDialogueTurnStatusV2(db, id, DIALOGUE_TURN_V2.ESCALATED, {
+    reason,
+  });
+}
+
+export function getActiveSpecCount(authorId) {
+  let n = 0;
+  for (const r of _specsV2.values()) {
+    if (!_isActiveSpec(r.status)) continue;
+    if (authorId && r.authorId !== authorId) continue;
+    n++;
+  }
+  return n;
+}
+
+export function getPendingTurnCount(specId) {
+  let n = 0;
+  for (const r of _turnsV2.values()) {
+    if (r.status !== DIALOGUE_TURN_V2.PENDING) continue;
+    if (specId && r.specId !== specId) continue;
+    n++;
+  }
+  return n;
+}
+
+export function autoArchiveIdleSpecs(_db, nowMs) {
+  const now = nowMs ?? _now();
+  const flipped = [];
+  for (const r of _specsV2.values()) {
+    if (
+      r.status === SPEC_MATURITY_V2.DRAFT ||
+      r.status === SPEC_MATURITY_V2.REFINING ||
+      r.status === SPEC_MATURITY_V2.APPROVED ||
+      r.status === SPEC_MATURITY_V2.IMPLEMENTED
+    ) {
+      if (now - r.lastActivityAt > _specIdleMsV2) {
+        r.status = SPEC_MATURITY_V2.ARCHIVED;
+        r.updatedAt = now;
+        r.lastReason = "idle";
+        flipped.push(r.specId);
+      }
+    }
+  }
+  return { flipped, count: flipped.length };
+}
+
+export function autoDismissStalePendingTurns(_db, nowMs) {
+  const now = nowMs ?? _now();
+  const flipped = [];
+  for (const r of _turnsV2.values()) {
+    if (r.status === DIALOGUE_TURN_V2.PENDING) {
+      if (now - r.createdAt > _turnPendingMsV2) {
+        r.status = DIALOGUE_TURN_V2.DISMISSED;
+        r.updatedAt = now;
+        r.lastReason = "pending_timeout";
+        flipped.push(r.turnId);
+      }
+    }
+  }
+  return { flipped, count: flipped.length };
+}
+
+export function getNlProgrammingStatsV2() {
+  const specsByStatus = {};
+  for (const s of Object.values(SPEC_MATURITY_V2)) specsByStatus[s] = 0;
+  const turnsByStatus = {};
+  for (const s of Object.values(DIALOGUE_TURN_V2)) turnsByStatus[s] = 0;
+  for (const r of _specsV2.values()) specsByStatus[r.status]++;
+  for (const r of _turnsV2.values()) turnsByStatus[r.status]++;
+  return {
+    totalSpecsV2: _specsV2.size,
+    totalTurnsV2: _turnsV2.size,
+    maxActiveSpecsPerAuthor: _maxActiveSpecsPerAuthorV2,
+    maxPendingTurnsPerSpec: _maxPendingTurnsPerSpecV2,
+    specIdleMs: _specIdleMsV2,
+    turnPendingMs: _turnPendingMsV2,
+    specsByStatus,
+    turnsByStatus,
+  };
+}
+
+export function _resetStateV2() {
+  _maxActiveSpecsPerAuthorV2 = NLPROG_DEFAULT_MAX_ACTIVE_SPECS_PER_AUTHOR;
+  _maxPendingTurnsPerSpecV2 = NLPROG_DEFAULT_MAX_PENDING_TURNS_PER_SPEC;
+  _specIdleMsV2 = NLPROG_DEFAULT_SPEC_IDLE_MS;
+  _turnPendingMsV2 = NLPROG_DEFAULT_TURN_PENDING_MS;
+  _specsV2.clear();
+  _turnsV2.clear();
+}