chainlesschain 0.66.0 → 0.132.0

package/src/lib/sync-manager.js

@@ -345,3 +345,329 @@ export function clearSyncData(db) {
   db.prepare("DELETE FROM sync_log").run();
   return true;
 }
+
+/* ═══════════════════════════════════════════════════════════════
+ * V2 Surface — Sync Manager governance layer.
+ * Tracks tracked-resource maturity + sync-run lifecycle independent
+ * of legacy registerResource/pushResources/pullResources flows above.
+ * ═══════════════════════════════════════════════════════════════ */
+
+export const RESOURCE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  PAUSED: "paused",
+  ARCHIVED: "archived",
+});
+
+export const SYNC_RUN_V2 = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  SUCCEEDED: "succeeded",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const RESOURCE_TRANSITIONS_V2 = new Map([
+  ["pending", new Set(["active", "archived"])],
+  ["active", new Set(["paused", "archived"])],
+  ["paused", new Set(["active", "archived"])],
+  ["archived", new Set()],
+]);
+const RESOURCE_TERMINALS_V2 = new Set(["archived"]);
+
+const RUN_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 RUN_TERMINALS_V2 = new Set(["succeeded", "failed", "cancelled"]);
+
+export const SYNC_DEFAULT_MAX_ACTIVE_RESOURCES_PER_OWNER = 200;
+export const SYNC_DEFAULT_MAX_RUNNING_RUNS_PER_RESOURCE = 1;
+export const SYNC_DEFAULT_RESOURCE_IDLE_MS = 1000 * 60 * 60 * 24 * 30; // 30 days
+export const SYNC_DEFAULT_RUN_STUCK_MS = 1000 * 60 * 15; // 15 min
+
+const _resourcesV2 = new Map();
+const _runsV2 = new Map();
+let _maxActiveResourcesPerOwnerV2 = SYNC_DEFAULT_MAX_ACTIVE_RESOURCES_PER_OWNER;
+let _maxRunningRunsPerResourceV2 = SYNC_DEFAULT_MAX_RUNNING_RUNS_PER_RESOURCE;
+let _resourceIdleMsV2 = SYNC_DEFAULT_RESOURCE_IDLE_MS;
+let _runStuckMsV2 = SYNC_DEFAULT_RUN_STUCK_MS;
+
+function _posIntSyncV2(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 getMaxActiveResourcesPerOwnerV2() {
+  return _maxActiveResourcesPerOwnerV2;
+}
+export function setMaxActiveResourcesPerOwnerV2(n) {
+  _maxActiveResourcesPerOwnerV2 = _posIntSyncV2(
+    n,
+    "maxActiveResourcesPerOwner",
+  );
+}
+export function getMaxRunningRunsPerResourceV2() {
+  return _maxRunningRunsPerResourceV2;
+}
+export function setMaxRunningRunsPerResourceV2(n) {
+  _maxRunningRunsPerResourceV2 = _posIntSyncV2(n, "maxRunningRunsPerResource");
+}
+export function getResourceIdleMsV2() {
+  return _resourceIdleMsV2;
+}
+export function setResourceIdleMsV2(n) {
+  _resourceIdleMsV2 = _posIntSyncV2(n, "resourceIdleMs");
+}
+export function getRunStuckMsV2() {
+  return _runStuckMsV2;
+}
+export function setRunStuckMsV2(n) {
+  _runStuckMsV2 = _posIntSyncV2(n, "runStuckMs");
+}
+
+export function getActiveResourceCountV2(owner) {
+  let n = 0;
+  for (const r of _resourcesV2.values()) {
+    if (r.owner === owner && r.status === "active") n += 1;
+  }
+  return n;
+}
+
+export function getRunningRunCountV2(resourceId) {
+  let n = 0;
+  for (const j of _runsV2.values()) {
+    if (j.resourceId === resourceId && j.status === "running") n += 1;
+  }
+  return n;
+}
+
+function _copyResV2(r) {
+  return { ...r, metadata: { ...r.metadata } };
+}
+function _copyRunV2(j) {
+  return { ...j, metadata: { ...j.metadata } };
+}
+
+export function registerResourceV2(
+  id,
+  { owner, kind, metadata = {}, now = Date.now() } = {},
+) {
+  if (!id || typeof id !== "string") throw new Error("id must be a string");
+  if (!owner || typeof owner !== "string")
+    throw new Error("owner must be a string");
+  if (!kind || typeof kind !== "string")
+    throw new Error("kind must be a string");
+  if (_resourcesV2.has(id)) throw new Error(`resource ${id} already exists`);
+  const r = {
+    id,
+    owner,
+    kind,
+    status: "pending",
+    createdAt: now,
+    lastSeenAt: now,
+    activatedAt: null,
+    archivedAt: null,
+    metadata: { ...metadata },
+  };
+  _resourcesV2.set(id, r);
+  return _copyResV2(r);
+}
+
+export function getResourceV2(id) {
+  const r = _resourcesV2.get(id);
+  return r ? _copyResV2(r) : null;
+}
+
+export function listResourcesV2({ owner, kind, status } = {}) {
+  const out = [];
+  for (const r of _resourcesV2.values()) {
+    if (owner && r.owner !== owner) continue;
+    if (kind && r.kind !== kind) continue;
+    if (status && r.status !== status) continue;
+    out.push(_copyResV2(r));
+  }
+  return out;
+}
+
+export function setResourceStatusV2(id, next, { now = Date.now() } = {}) {
+  const r = _resourcesV2.get(id);
+  if (!r) throw new Error(`resource ${id} not found`);
+  if (!RESOURCE_TRANSITIONS_V2.has(next))
+    throw new Error(`unknown resource status: ${next}`);
+  if (RESOURCE_TERMINALS_V2.has(r.status))
+    throw new Error(`resource ${id} is in terminal state ${r.status}`);
+  const allowed = RESOURCE_TRANSITIONS_V2.get(r.status);
+  if (!allowed.has(next))
+    throw new Error(`cannot transition resource from ${r.status} to ${next}`);
+  if (next === "active") {
+    if (r.status === "pending") {
+      const count = getActiveResourceCountV2(r.owner);
+      if (count >= _maxActiveResourcesPerOwnerV2)
+        throw new Error(
+          `owner ${r.owner} already at active-resource cap (${_maxActiveResourcesPerOwnerV2})`,
+        );
+    }
+    if (!r.activatedAt) r.activatedAt = now;
+  }
+  if (next === "archived" && !r.archivedAt) r.archivedAt = now;
+  r.status = next;
+  r.lastSeenAt = now;
+  return _copyResV2(r);
+}
+
+export function activateResourceV2(id, opts) {
+  return setResourceStatusV2(id, "active", opts);
+}
+export function pauseResourceV2(id, opts) {
+  return setResourceStatusV2(id, "paused", opts);
+}
+export function archiveResourceV2(id, opts) {
+  return setResourceStatusV2(id, "archived", opts);
+}
+
+export function touchResourceV2(id, { now = Date.now() } = {}) {
+  const r = _resourcesV2.get(id);
+  if (!r) throw new Error(`resource ${id} not found`);
+  r.lastSeenAt = now;
+  return _copyResV2(r);
+}
+
+export function createSyncRunV2(
+  id,
+  { resourceId, kind = "push", metadata = {}, now = Date.now() } = {},
+) {
+  if (!id || typeof id !== "string") throw new Error("id must be a string");
+  if (!resourceId || typeof resourceId !== "string")
+    throw new Error("resourceId must be a string");
+  if (_runsV2.has(id)) throw new Error(`syncRun ${id} already exists`);
+  const j = {
+    id,
+    resourceId,
+    kind,
+    status: "queued",
+    createdAt: now,
+    lastSeenAt: now,
+    startedAt: null,
+    finishedAt: null,
+    metadata: { ...metadata },
+  };
+  _runsV2.set(id, j);
+  return _copyRunV2(j);
+}
+
+export function getSyncRunV2(id) {
+  const j = _runsV2.get(id);
+  return j ? _copyRunV2(j) : null;
+}
+
+export function listSyncRunsV2({ resourceId, status } = {}) {
+  const out = [];
+  for (const j of _runsV2.values()) {
+    if (resourceId && j.resourceId !== resourceId) continue;
+    if (status && j.status !== status) continue;
+    out.push(_copyRunV2(j));
+  }
+  return out;
+}
+
+export function setSyncRunStatusV2(id, next, { now = Date.now() } = {}) {
+  const j = _runsV2.get(id);
+  if (!j) throw new Error(`syncRun ${id} not found`);
+  if (!RUN_TRANSITIONS_V2.has(next))
+    throw new Error(`unknown syncRun status: ${next}`);
+  if (RUN_TERMINALS_V2.has(j.status))
+    throw new Error(`syncRun ${id} is in terminal state ${j.status}`);
+  const allowed = RUN_TRANSITIONS_V2.get(j.status);
+  if (!allowed.has(next))
+    throw new Error(`cannot transition syncRun from ${j.status} to ${next}`);
+  if (next === "running" && j.status === "queued") {
+    const count = getRunningRunCountV2(j.resourceId);
+    if (count >= _maxRunningRunsPerResourceV2)
+      throw new Error(
+        `resource ${j.resourceId} already at running-run cap (${_maxRunningRunsPerResourceV2})`,
+      );
+    if (!j.startedAt) j.startedAt = now;
+  }
+  if (RUN_TERMINALS_V2.has(next) && !j.finishedAt) j.finishedAt = now;
+  j.status = next;
+  j.lastSeenAt = now;
+  return _copyRunV2(j);
+}
+
+export function startSyncRunV2(id, opts) {
+  return setSyncRunStatusV2(id, "running", opts);
+}
+export function succeedSyncRunV2(id, opts) {
+  return setSyncRunStatusV2(id, "succeeded", opts);
+}
+export function failSyncRunV2(id, opts) {
+  return setSyncRunStatusV2(id, "failed", opts);
+}
+export function cancelSyncRunV2(id, opts) {
+  return setSyncRunStatusV2(id, "cancelled", opts);
+}
+
+export function autoArchiveIdleResourcesV2({ now = Date.now() } = {}) {
+  const flipped = [];
+  for (const r of _resourcesV2.values()) {
+    if (r.status === "archived" || r.status === "pending") continue;
+    if (now - r.lastSeenAt > _resourceIdleMsV2) {
+      r.status = "archived";
+      r.lastSeenAt = now;
+      if (!r.archivedAt) r.archivedAt = now;
+      flipped.push(_copyResV2(r));
+    }
+  }
+  return flipped;
+}
+
+export function autoFailStuckSyncRunsV2({ now = Date.now() } = {}) {
+  const flipped = [];
+  for (const j of _runsV2.values()) {
+    if (j.status !== "running") continue;
+    const ref = j.startedAt ?? j.lastSeenAt;
+    if (now - ref > _runStuckMsV2) {
+      j.status = "failed";
+      j.lastSeenAt = now;
+      if (!j.finishedAt) j.finishedAt = now;
+      flipped.push(_copyRunV2(j));
+    }
+  }
+  return flipped;
+}
+
+export function getSyncManagerStatsV2() {
+  const resourcesByStatus = {};
+  for (const v of Object.values(RESOURCE_MATURITY_V2)) resourcesByStatus[v] = 0;
+  for (const r of _resourcesV2.values()) resourcesByStatus[r.status] += 1;
+
+  const runsByStatus = {};
+  for (const v of Object.values(SYNC_RUN_V2)) runsByStatus[v] = 0;
+  for (const j of _runsV2.values()) runsByStatus[j.status] += 1;
+
+  return {
+    totalResourcesV2: _resourcesV2.size,
+    totalSyncRunsV2: _runsV2.size,
+    maxActiveResourcesPerOwner: _maxActiveResourcesPerOwnerV2,
+    maxRunningRunsPerResource: _maxRunningRunsPerResourceV2,
+    resourceIdleMs: _resourceIdleMsV2,
+    runStuckMs: _runStuckMsV2,
+    resourcesByStatus,
+    runsByStatus,
+  };
+}
+
+export function _resetStateSyncManagerV2() {
+  _resourcesV2.clear();
+  _runsV2.clear();
+  _maxActiveResourcesPerOwnerV2 = SYNC_DEFAULT_MAX_ACTIVE_RESOURCES_PER_OWNER;
+  _maxRunningRunsPerResourceV2 = SYNC_DEFAULT_MAX_RUNNING_RUNS_PER_RESOURCE;
+  _resourceIdleMsV2 = SYNC_DEFAULT_RESOURCE_IDLE_MS;
+  _runStuckMsV2 = SYNC_DEFAULT_RUN_STUCK_MS;
+}

package/src/lib/tech-learning-engine.js

@@ -649,3 +649,372 @@ export function _resetState() {
   _practices.clear();
   _seq = 0;
 }
+
+/* ═══════════════════════════════════════════════════════════════
+ * V2 Surface — Tech Learning Engine V2 (additive)
+ * State machines + caps + auto-flip for tech profiles / learning runs
+ * ═══════════════════════════════════════════════════════════════ */
+
+export const PROFILE_MATURITY_V2 = Object.freeze({
+  DRAFT: "draft",
+  ACTIVE: "active",
+  STALE: "stale",
+  ARCHIVED: "archived",
+});
+
+export const LEARNING_RUN_V2 = Object.freeze({
+  QUEUED: "queued",
+  STUDYING: "studying",
+  COMPLETED: "completed",
+  ABANDONED: "abandoned",
+  FAILED: "failed",
+});
+
+const _PROFILE_TRANS_V2 = new Map([
+  [
+    PROFILE_MATURITY_V2.DRAFT,
+    new Set([PROFILE_MATURITY_V2.ACTIVE, PROFILE_MATURITY_V2.ARCHIVED]),
+  ],
+  [
+    PROFILE_MATURITY_V2.ACTIVE,
+    new Set([PROFILE_MATURITY_V2.STALE, PROFILE_MATURITY_V2.ARCHIVED]),
+  ],
+  [
+    PROFILE_MATURITY_V2.STALE,
+    new Set([PROFILE_MATURITY_V2.ACTIVE, PROFILE_MATURITY_V2.ARCHIVED]),
+  ],
+  [PROFILE_MATURITY_V2.ARCHIVED, new Set()],
+]);
+
+const _RUN_TRANS_V2 = new Map([
+  [
+    LEARNING_RUN_V2.QUEUED,
+    new Set([
+      LEARNING_RUN_V2.STUDYING,
+      LEARNING_RUN_V2.ABANDONED,
+      LEARNING_RUN_V2.FAILED,
+    ]),
+  ],
+  [
+    LEARNING_RUN_V2.STUDYING,
+    new Set([
+      LEARNING_RUN_V2.COMPLETED,
+      LEARNING_RUN_V2.FAILED,
+      LEARNING_RUN_V2.ABANDONED,
+    ]),
+  ],
+  [LEARNING_RUN_V2.COMPLETED, new Set()],
+  [LEARNING_RUN_V2.ABANDONED, new Set()],
+  [LEARNING_RUN_V2.FAILED, new Set()],
+]);
+
+const _PROFILE_TERMINAL_V2 = new Set([PROFILE_MATURITY_V2.ARCHIVED]);
+const _RUN_TERMINAL_V2 = new Set([
+  LEARNING_RUN_V2.COMPLETED,
+  LEARNING_RUN_V2.ABANDONED,
+  LEARNING_RUN_V2.FAILED,
+]);
+
+export const TLE_DEFAULT_MAX_ACTIVE_PROFILES_PER_OWNER = 10;
+export const TLE_DEFAULT_MAX_STUDYING_RUNS_PER_LEARNER = 5;
+export const TLE_DEFAULT_PROFILE_STALE_MS = 60 * 24 * 60 * 60 * 1000;
+export const TLE_DEFAULT_RUN_STUCK_MS = 7 * 24 * 60 * 60 * 1000;
+
+let _tleMaxActiveProfiles = TLE_DEFAULT_MAX_ACTIVE_PROFILES_PER_OWNER;
+let _tleMaxStudyingRuns = TLE_DEFAULT_MAX_STUDYING_RUNS_PER_LEARNER;
+let _tleProfileStaleMs = TLE_DEFAULT_PROFILE_STALE_MS;
+let _tleRunStuckMs = TLE_DEFAULT_RUN_STUCK_MS;
+
+const _profilesV2 = new Map();
+const _runsV2 = new Map();
+
+function _posIntV2(n, label) {
+  const v = Number.isInteger(n) ? n : Math.floor(n);
+  if (!Number.isFinite(v) || v <= 0)
+    throw new Error(`${label} must be a positive integer`);
+  return v;
+}
+
+export function getMaxActiveProfilesPerOwnerV2() {
+  return _tleMaxActiveProfiles;
+}
+export function setMaxActiveProfilesPerOwnerV2(n) {
+  _tleMaxActiveProfiles = _posIntV2(n, "maxActiveProfilesPerOwner");
+  return _tleMaxActiveProfiles;
+}
+export function getMaxStudyingRunsPerLearnerV2() {
+  return _tleMaxStudyingRuns;
+}
+export function setMaxStudyingRunsPerLearnerV2(n) {
+  _tleMaxStudyingRuns = _posIntV2(n, "maxStudyingRunsPerLearner");
+  return _tleMaxStudyingRuns;
+}
+export function getProfileStaleMsV2() {
+  return _tleProfileStaleMs;
+}
+export function setProfileStaleMsV2(n) {
+  _tleProfileStaleMs = _posIntV2(n, "profileStaleMs");
+  return _tleProfileStaleMs;
+}
+export function getRunStuckMsV2() {
+  return _tleRunStuckMs;
+}
+export function setRunStuckMsV2(n) {
+  _tleRunStuckMs = _posIntV2(n, "runStuckMs");
+  return _tleRunStuckMs;
+}
+
+export function getActiveProfileCountV2(owner) {
+  if (!owner) throw new Error("owner is required");
+  let c = 0;
+  for (const p of _profilesV2.values()) {
+    if (p.owner !== owner) continue;
+    if (p.status === PROFILE_MATURITY_V2.ARCHIVED) continue;
+    if (p.status === PROFILE_MATURITY_V2.DRAFT) continue;
+    c++;
+  }
+  return c;
+}
+
+export function getStudyingRunCountV2(learner) {
+  if (!learner) throw new Error("learner is required");
+  let c = 0;
+  for (const r of _runsV2.values()) {
+    if (r.learner !== learner) continue;
+    if (r.status !== LEARNING_RUN_V2.STUDYING) continue;
+    c++;
+  }
+  return c;
+}
+
+export function createProfileV2({ id, owner, stackName, metadata }) {
+  if (!id) throw new Error("id is required");
+  if (!owner) throw new Error("owner is required");
+  if (!stackName) throw new Error("stackName is required");
+  if (_profilesV2.has(id)) throw new Error(`profile ${id} already exists`);
+  const now = Date.now();
+  const profile = {
+    id,
+    owner,
+    stackName: String(stackName),
+    status: PROFILE_MATURITY_V2.DRAFT,
+    createdAt: now,
+    updatedAt: now,
+    activatedAt: null,
+    lastTouchedAt: now,
+    metadata: metadata ? { ...metadata } : {},
+  };
+  _profilesV2.set(id, profile);
+  return { ...profile, metadata: { ...profile.metadata } };
+}
+
+export function getProfileV2(id) {
+  const p = _profilesV2.get(id);
+  if (!p) return null;
+  return { ...p, metadata: { ...p.metadata } };
+}
+
+export function listProfilesV2({ owner, status } = {}) {
+  const out = [];
+  for (const p of _profilesV2.values()) {
+    if (owner && p.owner !== owner) continue;
+    if (status && p.status !== status) continue;
+    out.push({ ...p, metadata: { ...p.metadata } });
+  }
+  return out;
+}
+
+export function setProfileMaturityV2(
+  id,
+  nextStatus,
+  { reason, metadata } = {},
+) {
+  const p = _profilesV2.get(id);
+  if (!p) throw new Error(`profile ${id} not found`);
+  if (!_PROFILE_TRANS_V2.has(p.status))
+    throw new Error(`unknown status ${p.status}`);
+  const allowed = _PROFILE_TRANS_V2.get(p.status);
+  if (!allowed.has(nextStatus)) {
+    throw new Error(
+      `cannot transition profile ${id} from ${p.status} to ${nextStatus}`,
+    );
+  }
+  if (nextStatus === PROFILE_MATURITY_V2.ACTIVE && p.owner) {
+    const count = getActiveProfileCountV2(p.owner);
+    const wasActive =
+      p.status === PROFILE_MATURITY_V2.ACTIVE ||
+      p.status === PROFILE_MATURITY_V2.STALE;
+    if (!wasActive && count >= _tleMaxActiveProfiles) {
+      throw new Error(
+        `owner ${p.owner} exceeds max active profile cap ${_tleMaxActiveProfiles}`,
+      );
+    }
+  }
+  const now = Date.now();
+  p.status = nextStatus;
+  p.updatedAt = now;
+  p.lastTouchedAt = now;
+  if (nextStatus === PROFILE_MATURITY_V2.ACTIVE && !p.activatedAt)
+    p.activatedAt = now;
+  if (reason) p.reason = reason;
+  if (metadata) p.metadata = { ...p.metadata, ...metadata };
+  return { ...p, metadata: { ...p.metadata } };
+}
+
+export function activateProfileV2(id, opts) {
+  return setProfileMaturityV2(id, PROFILE_MATURITY_V2.ACTIVE, opts);
+}
+export function markProfileStaleV2(id, opts) {
+  return setProfileMaturityV2(id, PROFILE_MATURITY_V2.STALE, opts);
+}
+export function archiveProfileV2(id, opts) {
+  return setProfileMaturityV2(id, PROFILE_MATURITY_V2.ARCHIVED, opts);
+}
+
+export function touchProfileV2(id) {
+  const p = _profilesV2.get(id);
+  if (!p) throw new Error(`profile ${id} not found`);
+  if (_PROFILE_TERMINAL_V2.has(p.status))
+    throw new Error(`profile ${id} is terminal`);
+  p.lastTouchedAt = Date.now();
+  return { ...p, metadata: { ...p.metadata } };
+}
+
+export function enqueueRunV2({ id, learner, topic, metadata }) {
+  if (!id) throw new Error("id is required");
+  if (!learner) throw new Error("learner is required");
+  if (!topic) throw new Error("topic is required");
+  if (_runsV2.has(id)) throw new Error(`run ${id} already exists`);
+  const now = Date.now();
+  const run = {
+    id,
+    learner,
+    topic: String(topic),
+    status: LEARNING_RUN_V2.QUEUED,
+    createdAt: now,
+    updatedAt: now,
+    startedAt: null,
+    endedAt: null,
+    metadata: metadata ? { ...metadata } : {},
+  };
+  _runsV2.set(id, run);
+  return { ...run, metadata: { ...run.metadata } };
+}
+
+export function getRunV2(id) {
+  const r = _runsV2.get(id);
+  if (!r) return null;
+  return { ...r, metadata: { ...r.metadata } };
+}
+
+export function listRunsV2({ learner, status } = {}) {
+  const out = [];
+  for (const r of _runsV2.values()) {
+    if (learner && r.learner !== learner) continue;
+    if (status && r.status !== status) continue;
+    out.push({ ...r, metadata: { ...r.metadata } });
+  }
+  return out;
+}
+
+export function setRunStatusV2(id, nextStatus, { reason, metadata } = {}) {
+  const r = _runsV2.get(id);
+  if (!r) throw new Error(`run ${id} not found`);
+  if (!_RUN_TRANS_V2.has(r.status))
+    throw new Error(`unknown status ${r.status}`);
+  const allowed = _RUN_TRANS_V2.get(r.status);
+  if (!allowed.has(nextStatus)) {
+    throw new Error(
+      `cannot transition run ${id} from ${r.status} to ${nextStatus}`,
+    );
+  }
+  if (nextStatus === LEARNING_RUN_V2.STUDYING) {
+    const count = getStudyingRunCountV2(r.learner);
+    if (count >= _tleMaxStudyingRuns) {
+      throw new Error(
+        `learner ${r.learner} exceeds max studying run cap ${_tleMaxStudyingRuns}`,
+      );
+    }
+  }
+  const now = Date.now();
+  r.status = nextStatus;
+  r.updatedAt = now;
+  if (nextStatus === LEARNING_RUN_V2.STUDYING && !r.startedAt)
+    r.startedAt = now;
+  if (_RUN_TERMINAL_V2.has(nextStatus)) r.endedAt = now;
+  if (reason) r.reason = reason;
+  if (metadata) r.metadata = { ...r.metadata, ...metadata };
+  return { ...r, metadata: { ...r.metadata } };
+}
+
+export function startRunV2(id, opts) {
+  return setRunStatusV2(id, LEARNING_RUN_V2.STUDYING, opts);
+}
+export function completeRunV2(id, opts) {
+  return setRunStatusV2(id, LEARNING_RUN_V2.COMPLETED, opts);
+}
+export function abandonRunV2(id, opts) {
+  return setRunStatusV2(id, LEARNING_RUN_V2.ABANDONED, opts);
+}
+export function failRunV2(id, opts) {
+  return setRunStatusV2(id, LEARNING_RUN_V2.FAILED, opts);
+}
+
+export function autoMarkStaleProfilesV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const out = [];
+  for (const p of _profilesV2.values()) {
+    if (p.status !== PROFILE_MATURITY_V2.ACTIVE) continue;
+    if (t - p.lastTouchedAt > _tleProfileStaleMs) {
+      p.status = PROFILE_MATURITY_V2.STALE;
+      p.updatedAt = t;
+      out.push(p.id);
+    }
+  }
+  return out;
+}
+
+export function autoFailStuckRunsV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const out = [];
+  for (const r of _runsV2.values()) {
+    if (r.status !== LEARNING_RUN_V2.STUDYING) continue;
+    if (r.startedAt == null) continue;
+    if (t - r.startedAt > _tleRunStuckMs) {
+      r.status = LEARNING_RUN_V2.FAILED;
+      r.endedAt = t;
+      r.updatedAt = t;
+      r.reason = r.reason || "auto-fail: stuck studying";
+      out.push(r.id);
+    }
+  }
+  return out;
+}
+
+export function getTechLearningStatsV2() {
+  const profilesByStatus = {};
+  for (const v of Object.values(PROFILE_MATURITY_V2)) profilesByStatus[v] = 0;
+  for (const p of _profilesV2.values()) profilesByStatus[p.status]++;
+  const runsByStatus = {};
+  for (const v of Object.values(LEARNING_RUN_V2)) runsByStatus[v] = 0;
+  for (const r of _runsV2.values()) runsByStatus[r.status]++;
+  return {
+    totalProfilesV2: _profilesV2.size,
+    totalRunsV2: _runsV2.size,
+    maxActiveProfilesPerOwner: _tleMaxActiveProfiles,
+    maxStudyingRunsPerLearner: _tleMaxStudyingRuns,
+    profileStaleMs: _tleProfileStaleMs,
+    runStuckMs: _tleRunStuckMs,
+    profilesByStatus,
+    runsByStatus,
+  };
+}
+
+export function _resetStateV2() {
+  _profilesV2.clear();
+  _runsV2.clear();
+  _tleMaxActiveProfiles = TLE_DEFAULT_MAX_ACTIVE_PROFILES_PER_OWNER;
+  _tleMaxStudyingRuns = TLE_DEFAULT_MAX_STUDYING_RUNS_PER_LEARNER;
+  _tleProfileStaleMs = TLE_DEFAULT_PROFILE_STALE_MS;
+  _tleRunStuckMs = TLE_DEFAULT_RUN_STUCK_MS;
+}