chainlesschain 0.81.0 → 0.143.0

package/src/lib/quantization.js

@@ -360,3 +360,328 @@ export function getQuantizationStats(db) {
 export function _resetState() {
   _jobs.clear();
 }
+
+/* ═════════════════════════════════════════════════════════ *
+ *  Phase 20 V2 — Model Maturity + Job Ticket Lifecycle
+ * ═════════════════════════════════════════════════════════ */
+
+export const MODEL_MATURITY_V2 = Object.freeze({
+  ONBOARDING: "onboarding",
+  ACTIVE: "active",
+  DEPRECATED: "deprecated",
+  RETIRED: "retired",
+});
+
+export const JOB_TICKET_V2 = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELED: "canceled",
+});
+
+const MODEL_TRANSITIONS_V2 = new Map([
+  ["onboarding", new Set(["active", "retired"])],
+  ["active", new Set(["deprecated", "retired"])],
+  ["deprecated", new Set(["active", "retired"])],
+]);
+const MODEL_TERMINALS_V2 = new Set(["retired"]);
+
+const JOB_TRANSITIONS_V2 = new Map([
+  ["queued", new Set(["running", "canceled", "failed"])],
+  ["running", new Set(["completed", "failed", "canceled"])],
+]);
+const JOB_TERMINALS_V2 = new Set(["completed", "failed", "canceled"]);
+
+export const QUANT_DEFAULT_MAX_ACTIVE_MODELS_PER_OWNER = 50;
+export const QUANT_DEFAULT_MAX_RUNNING_JOBS_PER_OWNER = 3;
+export const QUANT_DEFAULT_MODEL_IDLE_MS = 120 * 86400000; // 120d
+export const QUANT_DEFAULT_JOB_STUCK_MS = 6 * 3600000; // 6h
+
+let _maxActiveModelsPerOwnerV2 = QUANT_DEFAULT_MAX_ACTIVE_MODELS_PER_OWNER;
+let _maxRunningJobsPerOwnerV2 = QUANT_DEFAULT_MAX_RUNNING_JOBS_PER_OWNER;
+let _modelIdleMsV2 = QUANT_DEFAULT_MODEL_IDLE_MS;
+let _jobStuckMsV2 = QUANT_DEFAULT_JOB_STUCK_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 getDefaultMaxActiveModelsPerOwnerV2() {
+  return QUANT_DEFAULT_MAX_ACTIVE_MODELS_PER_OWNER;
+}
+export function getMaxActiveModelsPerOwnerV2() {
+  return _maxActiveModelsPerOwnerV2;
+}
+export function setMaxActiveModelsPerOwnerV2(n) {
+  return (_maxActiveModelsPerOwnerV2 = _positiveIntV2(
+    n,
+    "maxActiveModelsPerOwner",
+  ));
+}
+export function getDefaultMaxRunningJobsPerOwnerV2() {
+  return QUANT_DEFAULT_MAX_RUNNING_JOBS_PER_OWNER;
+}
+export function getMaxRunningJobsPerOwnerV2() {
+  return _maxRunningJobsPerOwnerV2;
+}
+export function setMaxRunningJobsPerOwnerV2(n) {
+  return (_maxRunningJobsPerOwnerV2 = _positiveIntV2(
+    n,
+    "maxRunningJobsPerOwner",
+  ));
+}
+export function getDefaultModelIdleMsV2() {
+  return QUANT_DEFAULT_MODEL_IDLE_MS;
+}
+export function getModelIdleMsV2() {
+  return _modelIdleMsV2;
+}
+export function setModelIdleMsV2(ms) {
+  return (_modelIdleMsV2 = _positiveIntV2(ms, "modelIdleMs"));
+}
+export function getDefaultJobStuckMsV2() {
+  return QUANT_DEFAULT_JOB_STUCK_MS;
+}
+export function getJobStuckMsV2() {
+  return _jobStuckMsV2;
+}
+export function setJobStuckMsV2(ms) {
+  return (_jobStuckMsV2 = _positiveIntV2(ms, "jobStuckMs"));
+}
+
+const _modelsV2 = new Map();
+const _jobTicketsV2 = new Map();
+
+export function registerModelV2(
+  _db,
+  { modelId, ownerId, family, initialStatus, metadata } = {},
+) {
+  if (!modelId) throw new Error("modelId is required");
+  if (!ownerId) throw new Error("ownerId is required");
+  if (_modelsV2.has(modelId))
+    throw new Error(`Model ${modelId} already exists`);
+  const status = initialStatus || MODEL_MATURITY_V2.ONBOARDING;
+  if (!Object.values(MODEL_MATURITY_V2).includes(status))
+    throw new Error(`Invalid initial status: ${status}`);
+  if (MODEL_TERMINALS_V2.has(status))
+    throw new Error(`Cannot register in terminal status: ${status}`);
+  if (status === MODEL_MATURITY_V2.ACTIVE) {
+    if (getActiveModelCount(ownerId) >= _maxActiveModelsPerOwnerV2)
+      throw new Error(
+        `Owner ${ownerId} reached active-model cap (${_maxActiveModelsPerOwnerV2})`,
+      );
+  }
+  const now = Date.now();
+  const record = {
+    modelId,
+    ownerId,
+    family: family || "",
+    status,
+    metadata: metadata || {},
+    createdAt: now,
+    updatedAt: now,
+    lastUsedAt: now,
+  };
+  _modelsV2.set(modelId, record);
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getModelV2(modelId) {
+  const r = _modelsV2.get(modelId);
+  return r ? { ...r, metadata: { ...r.metadata } } : null;
+}
+
+export function setModelMaturityV2(_db, modelId, newStatus, patch = {}) {
+  const record = _modelsV2.get(modelId);
+  if (!record) throw new Error(`Unknown model: ${modelId}`);
+  if (!Object.values(MODEL_MATURITY_V2).includes(newStatus))
+    throw new Error(`Invalid status: ${newStatus}`);
+  const allowed = MODEL_TRANSITIONS_V2.get(record.status) || new Set();
+  if (!allowed.has(newStatus))
+    throw new Error(`Invalid transition: ${record.status} -> ${newStatus}`);
+  if (newStatus === MODEL_MATURITY_V2.ACTIVE) {
+    if (getActiveModelCount(record.ownerId) >= _maxActiveModelsPerOwnerV2)
+      throw new Error(
+        `Owner ${record.ownerId} reached active-model cap (${_maxActiveModelsPerOwnerV2})`,
+      );
+  }
+  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 activateModel(db, id, reason) {
+  return setModelMaturityV2(db, id, MODEL_MATURITY_V2.ACTIVE, { reason });
+}
+export function deprecateModel(db, id, reason) {
+  return setModelMaturityV2(db, id, MODEL_MATURITY_V2.DEPRECATED, { reason });
+}
+export function retireModel(db, id, reason) {
+  return setModelMaturityV2(db, id, MODEL_MATURITY_V2.RETIRED, { reason });
+}
+
+export function touchModelUsage(modelId) {
+  const record = _modelsV2.get(modelId);
+  if (!record) throw new Error(`Unknown model: ${modelId}`);
+  record.lastUsedAt = Date.now();
+  record.updatedAt = record.lastUsedAt;
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function enqueueJobTicketV2(
+  _db,
+  { ticketId, ownerId, modelId, quantType, level, metadata } = {},
+) {
+  if (!ticketId) throw new Error("ticketId is required");
+  if (!ownerId) throw new Error("ownerId is required");
+  if (!modelId) throw new Error("modelId is required");
+  if (!quantType) throw new Error("quantType is required");
+  if (_jobTicketsV2.has(ticketId))
+    throw new Error(`Ticket ${ticketId} already exists`);
+  const now = Date.now();
+  const record = {
+    ticketId,
+    ownerId,
+    modelId,
+    quantType,
+    level: level || null,
+    status: JOB_TICKET_V2.QUEUED,
+    metadata: metadata || {},
+    createdAt: now,
+    updatedAt: now,
+  };
+  _jobTicketsV2.set(ticketId, record);
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getJobTicketV2(ticketId) {
+  const r = _jobTicketsV2.get(ticketId);
+  return r ? { ...r, metadata: { ...r.metadata } } : null;
+}
+
+export function setJobTicketStatusV2(_db, ticketId, newStatus, patch = {}) {
+  const record = _jobTicketsV2.get(ticketId);
+  if (!record) throw new Error(`Unknown ticket: ${ticketId}`);
+  if (!Object.values(JOB_TICKET_V2).includes(newStatus))
+    throw new Error(`Invalid status: ${newStatus}`);
+  const allowed = JOB_TRANSITIONS_V2.get(record.status) || new Set();
+  if (!allowed.has(newStatus))
+    throw new Error(`Invalid transition: ${record.status} -> ${newStatus}`);
+  if (newStatus === JOB_TICKET_V2.RUNNING) {
+    if (getRunningJobCount(record.ownerId) >= _maxRunningJobsPerOwnerV2)
+      throw new Error(
+        `Owner ${record.ownerId} reached running-job cap (${_maxRunningJobsPerOwnerV2})`,
+      );
+    record.startedAt = Date.now();
+  }
+  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 startJobTicket(db, id, reason) {
+  return setJobTicketStatusV2(db, id, JOB_TICKET_V2.RUNNING, { reason });
+}
+export function completeJobTicket(db, id, reason) {
+  return setJobTicketStatusV2(db, id, JOB_TICKET_V2.COMPLETED, { reason });
+}
+export function failJobTicket(db, id, reason) {
+  return setJobTicketStatusV2(db, id, JOB_TICKET_V2.FAILED, { reason });
+}
+export function cancelJobTicket(db, id, reason) {
+  return setJobTicketStatusV2(db, id, JOB_TICKET_V2.CANCELED, { reason });
+}
+
+export function getActiveModelCount(ownerId) {
+  let n = 0;
+  for (const r of _modelsV2.values()) {
+    if (r.status !== MODEL_MATURITY_V2.ACTIVE) continue;
+    if (ownerId && r.ownerId !== ownerId) continue;
+    n++;
+  }
+  return n;
+}
+
+export function getRunningJobCount(ownerId) {
+  let n = 0;
+  for (const r of _jobTicketsV2.values()) {
+    if (r.status !== JOB_TICKET_V2.RUNNING) continue;
+    if (ownerId && r.ownerId !== ownerId) continue;
+    n++;
+  }
+  return n;
+}
+
+export function autoRetireIdleModels(_db, nowMs) {
+  const now = nowMs ?? Date.now();
+  const flipped = [];
+  for (const r of _modelsV2.values()) {
+    if (
+      r.status === MODEL_MATURITY_V2.ACTIVE ||
+      r.status === MODEL_MATURITY_V2.DEPRECATED
+    ) {
+      if (now - r.lastUsedAt > _modelIdleMsV2) {
+        r.status = MODEL_MATURITY_V2.RETIRED;
+        r.updatedAt = now;
+        r.lastReason = "idle";
+        flipped.push(r.modelId);
+      }
+    }
+  }
+  return { flipped, count: flipped.length };
+}
+
+export function autoFailStuckJobTickets(_db, nowMs) {
+  const now = nowMs ?? Date.now();
+  const flipped = [];
+  for (const r of _jobTicketsV2.values()) {
+    if (r.status === JOB_TICKET_V2.RUNNING) {
+      const anchor = r.startedAt || r.createdAt;
+      if (now - anchor > _jobStuckMsV2) {
+        r.status = JOB_TICKET_V2.FAILED;
+        r.updatedAt = now;
+        r.lastReason = "stuck_timeout";
+        flipped.push(r.ticketId);
+      }
+    }
+  }
+  return { flipped, count: flipped.length };
+}
+
+export function getQuantizationStatsV2() {
+  const modelsByStatus = {};
+  for (const s of Object.values(MODEL_MATURITY_V2)) modelsByStatus[s] = 0;
+  const ticketsByStatus = {};
+  for (const s of Object.values(JOB_TICKET_V2)) ticketsByStatus[s] = 0;
+  for (const r of _modelsV2.values()) modelsByStatus[r.status]++;
+  for (const r of _jobTicketsV2.values()) ticketsByStatus[r.status]++;
+  return {
+    totalModelsV2: _modelsV2.size,
+    totalTicketsV2: _jobTicketsV2.size,
+    maxActiveModelsPerOwner: _maxActiveModelsPerOwnerV2,
+    maxRunningJobsPerOwner: _maxRunningJobsPerOwnerV2,
+    modelIdleMs: _modelIdleMsV2,
+    jobStuckMs: _jobStuckMsV2,
+    modelsByStatus,
+    ticketsByStatus,
+  };
+}
+
+export function _resetStateV2() {
+  _maxActiveModelsPerOwnerV2 = QUANT_DEFAULT_MAX_ACTIVE_MODELS_PER_OWNER;
+  _maxRunningJobsPerOwnerV2 = QUANT_DEFAULT_MAX_RUNNING_JOBS_PER_OWNER;
+  _modelIdleMsV2 = QUANT_DEFAULT_MODEL_IDLE_MS;
+  _jobStuckMsV2 = QUANT_DEFAULT_JOB_STUCK_MS;
+  _modelsV2.clear();
+  _jobTicketsV2.clear();
+}

package/src/lib/response-cache.js

@@ -154,3 +154,330 @@ export function getCacheStats(db) {
     expired_entries: expired?.cnt || 0,
   };
 }
+
+/* ═══════════════════════════════════════════════════════════════
+ * V2 Surface — Response cache governance layer.
+ * Tracks per-owner cache-profile maturity + per-profile refresh-job
+ * lifecycle independent of SQLite llm_cache table.
+ * ═══════════════════════════════════════════════════════════════ */
+
+export const PROFILE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  SUSPENDED: "suspended",
+  ARCHIVED: "archived",
+});
+
+export const REFRESH_JOB_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const PROFILE_TRANSITIONS_V2 = new Map([
+  ["pending", new Set(["active", "archived"])],
+  ["active", new Set(["suspended", "archived"])],
+  ["suspended", new Set(["active", "archived"])],
+  ["archived", new Set()],
+]);
+const PROFILE_TERMINALS_V2 = new Set(["archived"]);
+
+const REFRESH_TRANSITIONS_V2 = new Map([
+  ["queued", new Set(["running", "cancelled"])],
+  ["running", new Set(["completed", "failed", "cancelled"])],
+  ["completed", new Set()],
+  ["failed", new Set()],
+  ["cancelled", new Set()],
+]);
+const REFRESH_TERMINALS_V2 = new Set(["completed", "failed", "cancelled"]);
+
+export const CACHE_DEFAULT_MAX_ACTIVE_PROFILES_PER_OWNER = 25;
+export const CACHE_DEFAULT_MAX_PENDING_REFRESH_JOBS_PER_PROFILE = 4;
+export const CACHE_DEFAULT_PROFILE_IDLE_MS = 1000 * 60 * 60 * 24 * 7; // 7 days
+export const CACHE_DEFAULT_REFRESH_STUCK_MS = 1000 * 60 * 10; // 10 min
+
+const _profilesV2 = new Map();
+const _refreshJobsV2 = new Map();
+let _maxActiveProfilesPerOwnerV2 = CACHE_DEFAULT_MAX_ACTIVE_PROFILES_PER_OWNER;
+let _maxPendingRefreshJobsPerProfileV2 =
+  CACHE_DEFAULT_MAX_PENDING_REFRESH_JOBS_PER_PROFILE;
+let _profileIdleMsV2 = CACHE_DEFAULT_PROFILE_IDLE_MS;
+let _refreshStuckMsV2 = CACHE_DEFAULT_REFRESH_STUCK_MS;
+
+function _posIntCacheV2(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 getMaxActiveProfilesPerOwnerV2() {
+  return _maxActiveProfilesPerOwnerV2;
+}
+export function setMaxActiveProfilesPerOwnerV2(n) {
+  _maxActiveProfilesPerOwnerV2 = _posIntCacheV2(n, "maxActiveProfilesPerOwner");
+}
+export function getMaxPendingRefreshJobsPerProfileV2() {
+  return _maxPendingRefreshJobsPerProfileV2;
+}
+export function setMaxPendingRefreshJobsPerProfileV2(n) {
+  _maxPendingRefreshJobsPerProfileV2 = _posIntCacheV2(
+    n,
+    "maxPendingRefreshJobsPerProfile",
+  );
+}
+export function getProfileIdleMsV2() {
+  return _profileIdleMsV2;
+}
+export function setProfileIdleMsV2(n) {
+  _profileIdleMsV2 = _posIntCacheV2(n, "profileIdleMs");
+}
+export function getRefreshStuckMsV2() {
+  return _refreshStuckMsV2;
+}
+export function setRefreshStuckMsV2(n) {
+  _refreshStuckMsV2 = _posIntCacheV2(n, "refreshStuckMs");
+}
+
+export function getActiveProfileCountV2(ownerId) {
+  let n = 0;
+  for (const p of _profilesV2.values()) {
+    if (p.ownerId === ownerId && p.status === "active") n += 1;
+  }
+  return n;
+}
+
+export function getPendingRefreshJobCountV2(profileId) {
+  let n = 0;
+  for (const j of _refreshJobsV2.values()) {
+    if (
+      j.profileId === profileId &&
+      (j.status === "queued" || j.status === "running")
+    )
+      n += 1;
+  }
+  return n;
+}
+
+function _copyProfileV2(p) {
+  return { ...p, metadata: { ...p.metadata } };
+}
+function _copyRefreshJobV2(j) {
+  return { ...j, metadata: { ...j.metadata } };
+}
+
+export function registerProfileV2(
+  id,
+  { ownerId, label, metadata = {}, now = Date.now() } = {},
+) {
+  if (!id || typeof id !== "string") throw new Error("id must be a string");
+  if (!ownerId || typeof ownerId !== "string")
+    throw new Error("ownerId must be a string");
+  if (!label || typeof label !== "string")
+    throw new Error("label must be a string");
+  if (_profilesV2.has(id)) throw new Error(`profile ${id} already exists`);
+  const p = {
+    id,
+    ownerId,
+    label,
+    status: "pending",
+    createdAt: now,
+    lastSeenAt: now,
+    activatedAt: null,
+    archivedAt: null,
+    metadata: { ...metadata },
+  };
+  _profilesV2.set(id, p);
+  return _copyProfileV2(p);
+}
+
+export function getProfileV2(id) {
+  const p = _profilesV2.get(id);
+  return p ? _copyProfileV2(p) : null;
+}
+
+export function listProfilesV2({ ownerId, status } = {}) {
+  const out = [];
+  for (const p of _profilesV2.values()) {
+    if (ownerId && p.ownerId !== ownerId) continue;
+    if (status && p.status !== status) continue;
+    out.push(_copyProfileV2(p));
+  }
+  return out;
+}
+
+export function setProfileStatusV2(id, next, { now = Date.now() } = {}) {
+  const p = _profilesV2.get(id);
+  if (!p) throw new Error(`profile ${id} not found`);
+  if (!PROFILE_TRANSITIONS_V2.has(next))
+    throw new Error(`unknown profile status: ${next}`);
+  if (PROFILE_TERMINALS_V2.has(p.status))
+    throw new Error(`profile ${id} is in terminal state ${p.status}`);
+  const allowed = PROFILE_TRANSITIONS_V2.get(p.status);
+  if (!allowed.has(next))
+    throw new Error(`cannot transition profile from ${p.status} to ${next}`);
+  if (next === "active") {
+    if (p.status === "pending") {
+      const count = getActiveProfileCountV2(p.ownerId);
+      if (count >= _maxActiveProfilesPerOwnerV2)
+        throw new Error(
+          `owner ${p.ownerId} already at active-profile cap (${_maxActiveProfilesPerOwnerV2})`,
+        );
+    }
+    if (!p.activatedAt) p.activatedAt = now;
+  }
+  if (next === "archived" && !p.archivedAt) p.archivedAt = now;
+  p.status = next;
+  p.lastSeenAt = now;
+  return _copyProfileV2(p);
+}
+
+export function activateProfileV2(id, opts) {
+  return setProfileStatusV2(id, "active", opts);
+}
+export function suspendProfileV2(id, opts) {
+  return setProfileStatusV2(id, "suspended", opts);
+}
+export function archiveProfileV2(id, opts) {
+  return setProfileStatusV2(id, "archived", opts);
+}
+
+export function touchProfileV2(id, { now = Date.now() } = {}) {
+  const p = _profilesV2.get(id);
+  if (!p) throw new Error(`profile ${id} not found`);
+  p.lastSeenAt = now;
+  return _copyProfileV2(p);
+}
+
+export function createRefreshJobV2(
+  id,
+  { profileId, kind = "warm", metadata = {}, now = Date.now() } = {},
+) {
+  if (!id || typeof id !== "string") throw new Error("id must be a string");
+  if (!profileId || typeof profileId !== "string")
+    throw new Error("profileId must be a string");
+  if (_refreshJobsV2.has(id)) throw new Error(`job ${id} already exists`);
+  const count = getPendingRefreshJobCountV2(profileId);
+  if (count >= _maxPendingRefreshJobsPerProfileV2)
+    throw new Error(
+      `profile ${profileId} already at pending-refresh-job cap (${_maxPendingRefreshJobsPerProfileV2})`,
+    );
+  const j = {
+    id,
+    profileId,
+    kind,
+    status: "queued",
+    createdAt: now,
+    lastSeenAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: { ...metadata },
+  };
+  _refreshJobsV2.set(id, j);
+  return _copyRefreshJobV2(j);
+}
+
+export function getRefreshJobV2(id) {
+  const j = _refreshJobsV2.get(id);
+  return j ? _copyRefreshJobV2(j) : null;
+}
+
+export function listRefreshJobsV2({ profileId, status } = {}) {
+  const out = [];
+  for (const j of _refreshJobsV2.values()) {
+    if (profileId && j.profileId !== profileId) continue;
+    if (status && j.status !== status) continue;
+    out.push(_copyRefreshJobV2(j));
+  }
+  return out;
+}
+
+export function setRefreshJobStatusV2(id, next, { now = Date.now() } = {}) {
+  const j = _refreshJobsV2.get(id);
+  if (!j) throw new Error(`job ${id} not found`);
+  if (!REFRESH_TRANSITIONS_V2.has(next))
+    throw new Error(`unknown job status: ${next}`);
+  if (REFRESH_TERMINALS_V2.has(j.status))
+    throw new Error(`job ${id} is in terminal state ${j.status}`);
+  const allowed = REFRESH_TRANSITIONS_V2.get(j.status);
+  if (!allowed.has(next))
+    throw new Error(`cannot transition job from ${j.status} to ${next}`);
+  if (next === "running" && !j.startedAt) j.startedAt = now;
+  if (REFRESH_TERMINALS_V2.has(next) && !j.settledAt) j.settledAt = now;
+  j.status = next;
+  j.lastSeenAt = now;
+  return _copyRefreshJobV2(j);
+}
+
+export function startRefreshJobV2(id, opts) {
+  return setRefreshJobStatusV2(id, "running", opts);
+}
+export function completeRefreshJobV2(id, opts) {
+  return setRefreshJobStatusV2(id, "completed", opts);
+}
+export function failRefreshJobV2(id, opts) {
+  return setRefreshJobStatusV2(id, "failed", opts);
+}
+export function cancelRefreshJobV2(id, opts) {
+  return setRefreshJobStatusV2(id, "cancelled", opts);
+}
+
+export function autoSuspendIdleProfilesV2({ now = Date.now() } = {}) {
+  const flipped = [];
+  for (const p of _profilesV2.values()) {
+    if (p.status !== "active") continue;
+    if (now - p.lastSeenAt > _profileIdleMsV2) {
+      p.status = "suspended";
+      p.lastSeenAt = now;
+      flipped.push(_copyProfileV2(p));
+    }
+  }
+  return flipped;
+}
+
+export function autoFailStuckRefreshJobsV2({ now = Date.now() } = {}) {
+  const flipped = [];
+  for (const j of _refreshJobsV2.values()) {
+    if (j.status !== "running") continue;
+    if (now - j.lastSeenAt > _refreshStuckMsV2) {
+      j.status = "failed";
+      j.lastSeenAt = now;
+      if (!j.settledAt) j.settledAt = now;
+      flipped.push(_copyRefreshJobV2(j));
+    }
+  }
+  return flipped;
+}
+
+export function getResponseCacheStatsV2() {
+  const profilesByStatus = {};
+  for (const v of Object.values(PROFILE_MATURITY_V2)) profilesByStatus[v] = 0;
+  for (const p of _profilesV2.values()) profilesByStatus[p.status] += 1;
+
+  const jobsByStatus = {};
+  for (const v of Object.values(REFRESH_JOB_LIFECYCLE_V2)) jobsByStatus[v] = 0;
+  for (const j of _refreshJobsV2.values()) jobsByStatus[j.status] += 1;
+
+  return {
+    totalProfilesV2: _profilesV2.size,
+    totalRefreshJobsV2: _refreshJobsV2.size,
+    maxActiveProfilesPerOwner: _maxActiveProfilesPerOwnerV2,
+    maxPendingRefreshJobsPerProfile: _maxPendingRefreshJobsPerProfileV2,
+    profileIdleMs: _profileIdleMsV2,
+    refreshStuckMs: _refreshStuckMsV2,
+    profilesByStatus,
+    jobsByStatus,
+  };
+}
+
+export function _resetStateResponseCacheV2() {
+  _profilesV2.clear();
+  _refreshJobsV2.clear();
+  _maxActiveProfilesPerOwnerV2 = CACHE_DEFAULT_MAX_ACTIVE_PROFILES_PER_OWNER;
+  _maxPendingRefreshJobsPerProfileV2 =
+    CACHE_DEFAULT_MAX_PENDING_REFRESH_JOBS_PER_PROFILE;
+  _profileIdleMsV2 = CACHE_DEFAULT_PROFILE_IDLE_MS;
+  _refreshStuckMsV2 = CACHE_DEFAULT_REFRESH_STUCK_MS;
+}