chainlesschain 0.81.0 → 0.143.0

package/src/lib/content-recommendation.js

@@ -598,3 +598,472 @@ export function _resetState() {
   _userRecs.clear();
   _seq = 0;
 }
+
+/* ═══════════════════════════════════════════════════════════════
+ * Phase 48 V2 — Profile Maturity + Feed Channel Lifecycle
+ * Strictly additive. Legacy surface above is preserved.
+ * ═════════════════════════════════════════════════════════════ */
+
+export const PROFILE_MATURITY_V2 = Object.freeze({
+  ONBOARDING: "onboarding",
+  ACTIVE: "active",
+  DORMANT: "dormant",
+  RETIRED: "retired",
+});
+
+export const FEED_LIFECYCLE_V2 = Object.freeze({
+  DRAFT: "draft",
+  ACTIVE: "active",
+  PAUSED: "paused",
+  ARCHIVED: "archived",
+});
+
+const PROFILE_TRANSITIONS_V2 = new Map([
+  ["onboarding", new Set(["active", "retired"])],
+  ["active", new Set(["dormant", "retired"])],
+  ["dormant", new Set(["active", "retired"])],
+]);
+const PROFILE_TERMINALS_V2 = new Set(["retired"]);
+
+const FEED_TRANSITIONS_V2 = new Map([
+  ["draft", new Set(["active", "archived"])],
+  ["active", new Set(["paused", "archived"])],
+  ["paused", new Set(["active", "archived"])],
+]);
+const FEED_TERMINALS_V2 = new Set(["archived"]);
+
+export const REC_DEFAULT_MAX_ACTIVE_PROFILES_PER_SEGMENT = 10000;
+export const REC_DEFAULT_MAX_ACTIVE_FEEDS_PER_CURATOR = 20;
+export const REC_DEFAULT_PROFILE_IDLE_MS = 90 * 86400000; // 90 days
+export const REC_DEFAULT_FEED_STALE_MS = 30 * 86400000; // 30 days
+
+let _maxActiveProfilesPerSegmentV2 =
+  REC_DEFAULT_MAX_ACTIVE_PROFILES_PER_SEGMENT;
+let _maxActiveFeedsPerCuratorV2 = REC_DEFAULT_MAX_ACTIVE_FEEDS_PER_CURATOR;
+let _profileIdleMsV2 = REC_DEFAULT_PROFILE_IDLE_MS;
+let _feedStaleMsV2 = REC_DEFAULT_FEED_STALE_MS;
+
+const _profileStatesV2 = new Map(); // profileId → V2 record
+const _feedStatesV2 = new Map(); // feedId → V2 record
+
+function _positiveIntV2(n, label) {
+  const num = Number(n);
+  if (!Number.isFinite(num) || num <= 0) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return Math.floor(num);
+}
+
+function _validProfileStatusV2(s) {
+  return (
+    s === "onboarding" || s === "active" || s === "dormant" || s === "retired"
+  );
+}
+
+function _validFeedStatusV2(s) {
+  return s === "draft" || s === "active" || s === "paused" || s === "archived";
+}
+
+export function getDefaultMaxActiveProfilesPerSegmentV2() {
+  return REC_DEFAULT_MAX_ACTIVE_PROFILES_PER_SEGMENT;
+}
+export function getMaxActiveProfilesPerSegmentV2() {
+  return _maxActiveProfilesPerSegmentV2;
+}
+export function setMaxActiveProfilesPerSegmentV2(n) {
+  _maxActiveProfilesPerSegmentV2 = _positiveIntV2(
+    n,
+    "maxActiveProfilesPerSegment",
+  );
+  return _maxActiveProfilesPerSegmentV2;
+}
+
+export function getDefaultMaxActiveFeedsPerCuratorV2() {
+  return REC_DEFAULT_MAX_ACTIVE_FEEDS_PER_CURATOR;
+}
+export function getMaxActiveFeedsPerCuratorV2() {
+  return _maxActiveFeedsPerCuratorV2;
+}
+export function setMaxActiveFeedsPerCuratorV2(n) {
+  _maxActiveFeedsPerCuratorV2 = _positiveIntV2(n, "maxActiveFeedsPerCurator");
+  return _maxActiveFeedsPerCuratorV2;
+}
+
+export function getDefaultProfileIdleMsV2() {
+  return REC_DEFAULT_PROFILE_IDLE_MS;
+}
+export function getProfileIdleMsV2() {
+  return _profileIdleMsV2;
+}
+export function setProfileIdleMsV2(ms) {
+  _profileIdleMsV2 = _positiveIntV2(ms, "profileIdleMs");
+  return _profileIdleMsV2;
+}
+
+export function getDefaultFeedStaleMsV2() {
+  return REC_DEFAULT_FEED_STALE_MS;
+}
+export function getFeedStaleMsV2() {
+  return _feedStaleMsV2;
+}
+export function setFeedStaleMsV2(ms) {
+  _feedStaleMsV2 = _positiveIntV2(ms, "feedStaleMs");
+  return _feedStaleMsV2;
+}
+
+/* ── Profile V2 ─────────────────────────────────────────────── */
+
+export function registerProfileV2(db, config = {}) {
+  void db;
+  const profileId = String(config.profileId || "").trim();
+  if (!profileId) throw new Error("profileId is required");
+  const segment = String(config.segment || "").trim();
+  if (!segment) throw new Error("segment is required");
+  if (_profileStatesV2.has(profileId)) {
+    throw new Error(`Profile already registered in V2: ${profileId}`);
+  }
+
+  const now = Number(config.now ?? Date.now());
+  const initialStatus = config.initialStatus || "onboarding";
+  if (!_validProfileStatusV2(initialStatus)) {
+    throw new Error(`Invalid initial status: ${initialStatus}`);
+  }
+  if (PROFILE_TERMINALS_V2.has(initialStatus)) {
+    throw new Error(
+      `Cannot register profile in terminal status '${initialStatus}'`,
+    );
+  }
+
+  if (initialStatus === "active") {
+    let activeCount = 0;
+    for (const rec of _profileStatesV2.values()) {
+      if (rec.segment === segment && rec.status === "active") {
+        activeCount += 1;
+      }
+    }
+    if (activeCount >= _maxActiveProfilesPerSegmentV2) {
+      throw new Error(
+        `Max active profiles per segment reached (${_maxActiveProfilesPerSegmentV2})`,
+      );
+    }
+  }
+
+  const record = {
+    profileId,
+    segment,
+    ownerId: config.ownerId ? String(config.ownerId) : null,
+    status: initialStatus,
+    metadata: config.metadata ? { ...config.metadata } : {},
+    createdAt: now,
+    updatedAt: now,
+    lastActivityAt: now,
+    reason: null,
+  };
+  _profileStatesV2.set(profileId, record);
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getProfileV2(profileId) {
+  const rec = _profileStatesV2.get(String(profileId || ""));
+  if (!rec) return null;
+  return { ...rec, metadata: { ...rec.metadata } };
+}
+
+export function setProfileMaturityV2(db, profileId, newStatus, patch = {}) {
+  void db;
+  const id = String(profileId || "");
+  const record = _profileStatesV2.get(id);
+  if (!record) throw new Error(`Profile not registered in V2: ${id}`);
+  if (!_validProfileStatusV2(newStatus)) {
+    throw new Error(`Invalid profile status: ${newStatus}`);
+  }
+  if (PROFILE_TERMINALS_V2.has(record.status)) {
+    throw new Error(
+      `Profile is in terminal status '${record.status}' and cannot transition`,
+    );
+  }
+  const allowed = PROFILE_TRANSITIONS_V2.get(record.status);
+  if (!allowed || !allowed.has(newStatus)) {
+    throw new Error(`Invalid transition: ${record.status} → ${newStatus}`);
+  }
+
+  if (newStatus === "active" && record.status !== "active") {
+    let activeCount = 0;
+    for (const rec of _profileStatesV2.values()) {
+      if (rec.segment === record.segment && rec.status === "active") {
+        activeCount += 1;
+      }
+    }
+    if (activeCount >= _maxActiveProfilesPerSegmentV2) {
+      throw new Error(
+        `Max active profiles per segment reached (${_maxActiveProfilesPerSegmentV2})`,
+      );
+    }
+  }
+
+  record.status = newStatus;
+  record.updatedAt = Number(patch.now ?? Date.now());
+  if (patch.reason !== undefined) record.reason = patch.reason;
+  if (patch.metadata && typeof patch.metadata === "object") {
+    record.metadata = { ...record.metadata, ...patch.metadata };
+  }
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function activateProfile(db, profileId, reason) {
+  return setProfileMaturityV2(db, profileId, "active", { reason });
+}
+export function dormantProfile(db, profileId, reason) {
+  return setProfileMaturityV2(db, profileId, "dormant", { reason });
+}
+export function retireProfile(db, profileId, reason) {
+  return setProfileMaturityV2(db, profileId, "retired", { reason });
+}
+
+export function touchProfileActivity(profileId) {
+  const rec = _profileStatesV2.get(String(profileId || ""));
+  if (!rec) throw new Error(`Profile not registered in V2: ${profileId}`);
+  rec.lastActivityAt = Date.now();
+  return { ...rec, metadata: { ...rec.metadata } };
+}
+
+/* ── Feed V2 ────────────────────────────────────────────────── */
+
+export function registerFeedV2(db, config = {}) {
+  void db;
+  const feedId = String(config.feedId || "").trim();
+  if (!feedId) throw new Error("feedId is required");
+  const curatorId = String(config.curatorId || "").trim();
+  if (!curatorId) throw new Error("curatorId is required");
+  const name = String(config.name || "").trim();
+  if (!name) throw new Error("name is required");
+  if (_feedStatesV2.has(feedId)) {
+    throw new Error(`Feed already registered in V2: ${feedId}`);
+  }
+
+  const now = Number(config.now ?? Date.now());
+  const initialStatus = config.initialStatus || "draft";
+  if (!_validFeedStatusV2(initialStatus)) {
+    throw new Error(`Invalid initial status: ${initialStatus}`);
+  }
+  if (FEED_TERMINALS_V2.has(initialStatus)) {
+    throw new Error(
+      `Cannot register feed in terminal status '${initialStatus}'`,
+    );
+  }
+
+  if (initialStatus === "active") {
+    let activeCount = 0;
+    for (const rec of _feedStatesV2.values()) {
+      if (rec.curatorId === curatorId && rec.status === "active") {
+        activeCount += 1;
+      }
+    }
+    if (activeCount >= _maxActiveFeedsPerCuratorV2) {
+      throw new Error(
+        `Max active feeds per curator reached (${_maxActiveFeedsPerCuratorV2})`,
+      );
+    }
+  }
+
+  const record = {
+    feedId,
+    curatorId,
+    name,
+    topics: Array.isArray(config.topics) ? [...config.topics] : [],
+    status: initialStatus,
+    metadata: config.metadata ? { ...config.metadata } : {},
+    createdAt: now,
+    updatedAt: now,
+    lastPublishedAt: now,
+    reason: null,
+  };
+  _feedStatesV2.set(feedId, record);
+  return {
+    ...record,
+    topics: [...record.topics],
+    metadata: { ...record.metadata },
+  };
+}
+
+export function getFeedV2(feedId) {
+  const rec = _feedStatesV2.get(String(feedId || ""));
+  if (!rec) return null;
+  return {
+    ...rec,
+    topics: [...rec.topics],
+    metadata: { ...rec.metadata },
+  };
+}
+
+export function setFeedStatusV2(db, feedId, newStatus, patch = {}) {
+  void db;
+  const id = String(feedId || "");
+  const record = _feedStatesV2.get(id);
+  if (!record) throw new Error(`Feed not registered in V2: ${id}`);
+  if (!_validFeedStatusV2(newStatus)) {
+    throw new Error(`Invalid feed status: ${newStatus}`);
+  }
+  if (FEED_TERMINALS_V2.has(record.status)) {
+    throw new Error(
+      `Feed is in terminal status '${record.status}' and cannot transition`,
+    );
+  }
+  const allowed = FEED_TRANSITIONS_V2.get(record.status);
+  if (!allowed || !allowed.has(newStatus)) {
+    throw new Error(`Invalid transition: ${record.status} → ${newStatus}`);
+  }
+
+  if (newStatus === "active" && record.status !== "active") {
+    let activeCount = 0;
+    for (const rec of _feedStatesV2.values()) {
+      if (rec.curatorId === record.curatorId && rec.status === "active") {
+        activeCount += 1;
+      }
+    }
+    if (activeCount >= _maxActiveFeedsPerCuratorV2) {
+      throw new Error(
+        `Max active feeds per curator reached (${_maxActiveFeedsPerCuratorV2})`,
+      );
+    }
+  }
+
+  record.status = newStatus;
+  record.updatedAt = Number(patch.now ?? Date.now());
+  if (patch.reason !== undefined) record.reason = patch.reason;
+  if (patch.metadata && typeof patch.metadata === "object") {
+    record.metadata = { ...record.metadata, ...patch.metadata };
+  }
+  return {
+    ...record,
+    topics: [...record.topics],
+    metadata: { ...record.metadata },
+  };
+}
+
+export function activateFeed(db, feedId, reason) {
+  return setFeedStatusV2(db, feedId, "active", { reason });
+}
+export function pauseFeed(db, feedId, reason) {
+  return setFeedStatusV2(db, feedId, "paused", { reason });
+}
+export function archiveFeed(db, feedId, reason) {
+  return setFeedStatusV2(db, feedId, "archived", { reason });
+}
+
+export function touchFeedPublish(feedId) {
+  const rec = _feedStatesV2.get(String(feedId || ""));
+  if (!rec) throw new Error(`Feed not registered in V2: ${feedId}`);
+  rec.lastPublishedAt = Date.now();
+  return {
+    ...rec,
+    topics: [...rec.topics],
+    metadata: { ...rec.metadata },
+  };
+}
+
+/* ── Counts ─────────────────────────────────────────────────── */
+
+export function getActiveProfileCount(segment) {
+  let n = 0;
+  for (const rec of _profileStatesV2.values()) {
+    if (rec.status !== "active") continue;
+    if (segment !== undefined && rec.segment !== String(segment)) continue;
+    n += 1;
+  }
+  return n;
+}
+
+export function getActiveFeedCount(curatorId) {
+  let n = 0;
+  for (const rec of _feedStatesV2.values()) {
+    if (rec.status !== "active") continue;
+    if (curatorId !== undefined && rec.curatorId !== String(curatorId)) {
+      continue;
+    }
+    n += 1;
+  }
+  return n;
+}
+
+/* ── Auto-flip Bulk Ops ─────────────────────────────────────── */
+
+export function autoDormantIdleProfiles(db, nowMs) {
+  void db;
+  const now = Number(nowMs ?? Date.now());
+  const flipped = [];
+  for (const rec of _profileStatesV2.values()) {
+    if (rec.status !== "active") continue;
+    if (now - rec.lastActivityAt > _profileIdleMsV2) {
+      rec.status = "dormant";
+      rec.updatedAt = now;
+      rec.reason = "idle";
+      flipped.push(rec.profileId);
+    }
+  }
+  return flipped;
+}
+
+export function autoArchiveStaleFeeds(db, nowMs) {
+  void db;
+  const now = Number(nowMs ?? Date.now());
+  const flipped = [];
+  for (const rec of _feedStatesV2.values()) {
+    if (rec.status !== "active" && rec.status !== "paused") continue;
+    if (now - rec.lastPublishedAt > _feedStaleMsV2) {
+      rec.status = "archived";
+      rec.updatedAt = now;
+      rec.reason = "stale";
+      flipped.push(rec.feedId);
+    }
+  }
+  return flipped;
+}
+
+/* ── Stats V2 ───────────────────────────────────────────────── */
+
+export function getRecommendationStatsV2() {
+  const profilesByStatus = {
+    onboarding: 0,
+    active: 0,
+    dormant: 0,
+    retired: 0,
+  };
+  const feedsByStatus = {
+    draft: 0,
+    active: 0,
+    paused: 0,
+    archived: 0,
+  };
+  for (const rec of _profileStatesV2.values()) {
+    if (profilesByStatus[rec.status] !== undefined) {
+      profilesByStatus[rec.status] += 1;
+    }
+  }
+  for (const rec of _feedStatesV2.values()) {
+    if (feedsByStatus[rec.status] !== undefined) {
+      feedsByStatus[rec.status] += 1;
+    }
+  }
+  return {
+    totalProfilesV2: _profileStatesV2.size,
+    totalFeedsV2: _feedStatesV2.size,
+    maxActiveProfilesPerSegment: _maxActiveProfilesPerSegmentV2,
+    maxActiveFeedsPerCurator: _maxActiveFeedsPerCuratorV2,
+    profileIdleMs: _profileIdleMsV2,
+    feedStaleMs: _feedStaleMsV2,
+    profilesByStatus,
+    feedsByStatus,
+  };
+}
+
+/* ── Reset V2 (tests) ───────────────────────────────────────── */
+
+export function _resetStateV2() {
+  _profileStatesV2.clear();
+  _feedStatesV2.clear();
+  _maxActiveProfilesPerSegmentV2 = REC_DEFAULT_MAX_ACTIVE_PROFILES_PER_SEGMENT;
+  _maxActiveFeedsPerCuratorV2 = REC_DEFAULT_MAX_ACTIVE_FEEDS_PER_CURATOR;
+  _profileIdleMsV2 = REC_DEFAULT_PROFILE_IDLE_MS;
+  _feedStaleMsV2 = REC_DEFAULT_FEED_STALE_MS;
+}

package/src/lib/content-recommender.js

@@ -203,3 +203,108 @@ export class CLIContentRecommender {
     return matrix;
   }
 }
+
+
+// ===== V2 Surface: Content Recommender governance overlay (CLI v0.139.0) =====
+export const RECOMMENDER_PROFILE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", STALE: "stale", ARCHIVED: "archived",
+});
+export const RECOMMENDATION_JOB_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued", RUNNING: "running", COMPLETED: "completed", FAILED: "failed", CANCELLED: "cancelled",
+});
+
+const _crpTrans = new Map([
+  [RECOMMENDER_PROFILE_MATURITY_V2.PENDING, new Set([RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE, RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED])],
+  [RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE, new Set([RECOMMENDER_PROFILE_MATURITY_V2.STALE, RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED])],
+  [RECOMMENDER_PROFILE_MATURITY_V2.STALE, new Set([RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE, RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED])],
+  [RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _crpTerminal = new Set([RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED]);
+const _crjTrans = new Map([
+  [RECOMMENDATION_JOB_LIFECYCLE_V2.QUEUED, new Set([RECOMMENDATION_JOB_LIFECYCLE_V2.RUNNING, RECOMMENDATION_JOB_LIFECYCLE_V2.CANCELLED])],
+  [RECOMMENDATION_JOB_LIFECYCLE_V2.RUNNING, new Set([RECOMMENDATION_JOB_LIFECYCLE_V2.COMPLETED, RECOMMENDATION_JOB_LIFECYCLE_V2.FAILED, RECOMMENDATION_JOB_LIFECYCLE_V2.CANCELLED])],
+  [RECOMMENDATION_JOB_LIFECYCLE_V2.COMPLETED, new Set()],
+  [RECOMMENDATION_JOB_LIFECYCLE_V2.FAILED, new Set()],
+  [RECOMMENDATION_JOB_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _crpsV2 = new Map();
+const _crjsV2 = new Map();
+let _crpMaxActivePerOwner = 8;
+let _crpMaxPendingJobsPerProfile = 10;
+let _crpIdleMs = 7 * 24 * 60 * 60 * 1000;
+let _crjStuckMs = 5 * 60 * 1000;
+
+function _crpPos(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 setMaxActiveRecommenderProfilesPerOwnerV2(n) { _crpMaxActivePerOwner = _crpPos(n, "maxActiveRecommenderProfilesPerOwner"); }
+export function getMaxActiveRecommenderProfilesPerOwnerV2() { return _crpMaxActivePerOwner; }
+export function setMaxPendingRecommendationJobsPerProfileV2(n) { _crpMaxPendingJobsPerProfile = _crpPos(n, "maxPendingRecommendationJobsPerProfile"); }
+export function getMaxPendingRecommendationJobsPerProfileV2() { return _crpMaxPendingJobsPerProfile; }
+export function setRecommenderProfileIdleMsV2(n) { _crpIdleMs = _crpPos(n, "recommenderProfileIdleMs"); }
+export function getRecommenderProfileIdleMsV2() { return _crpIdleMs; }
+export function setRecommendationJobStuckMsV2(n) { _crjStuckMs = _crpPos(n, "recommendationJobStuckMs"); }
+export function getRecommendationJobStuckMsV2() { return _crjStuckMs; }
+
+export function _resetStateContentRecommenderV2() {
+  _crpsV2.clear(); _crjsV2.clear();
+  _crpMaxActivePerOwner = 8; _crpMaxPendingJobsPerProfile = 10;
+  _crpIdleMs = 7 * 24 * 60 * 60 * 1000; _crjStuckMs = 5 * 60 * 1000;
+}
+
+export function registerRecommenderProfileV2({ id, owner, strategy, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_crpsV2.has(id)) throw new Error(`recommender profile ${id} already registered`);
+  const now = Date.now();
+  const p = { id, owner, strategy: strategy || "tfidf", status: RECOMMENDER_PROFILE_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, archivedAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _crpsV2.set(id, p);
+  return { ...p, metadata: { ...p.metadata } };
+}
+function _crpCheckP(from, to) { const a = _crpTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid recommender profile transition ${from} → ${to}`); }
+function _crpCountActive(owner) { let n = 0; for (const p of _crpsV2.values()) if (p.owner === owner && p.status === RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE) n++; return n; }
+
+export function activateRecommenderProfileV2(id) {
+  const p = _crpsV2.get(id); if (!p) throw new Error(`recommender profile ${id} not found`);
+  _crpCheckP(p.status, RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE);
+  const recovery = p.status === RECOMMENDER_PROFILE_MATURITY_V2.STALE;
+  if (!recovery) { const c = _crpCountActive(p.owner); if (c >= _crpMaxActivePerOwner) throw new Error(`max active recommender profiles per owner (${_crpMaxActivePerOwner}) reached for ${p.owner}`); }
+  const now = Date.now(); p.status = RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE; p.updatedAt = now; p.lastTouchedAt = now; if (!p.activatedAt) p.activatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function staleRecommenderProfileV2(id) { const p = _crpsV2.get(id); if (!p) throw new Error(`recommender profile ${id} not found`); _crpCheckP(p.status, RECOMMENDER_PROFILE_MATURITY_V2.STALE); p.status = RECOMMENDER_PROFILE_MATURITY_V2.STALE; p.updatedAt = Date.now(); return { ...p, metadata: { ...p.metadata } }; }
+export function archiveRecommenderProfileV2(id) { const p = _crpsV2.get(id); if (!p) throw new Error(`recommender profile ${id} not found`); _crpCheckP(p.status, RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED); const now = Date.now(); p.status = RECOMMENDER_PROFILE_MATURITY_V2.ARCHIVED; p.updatedAt = now; if (!p.archivedAt) p.archivedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function touchRecommenderProfileV2(id) { const p = _crpsV2.get(id); if (!p) throw new Error(`recommender profile ${id} not found`); if (_crpTerminal.has(p.status)) throw new Error(`cannot touch terminal recommender profile ${id}`); const now = Date.now(); p.lastTouchedAt = now; p.updatedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function getRecommenderProfileV2(id) { const p = _crpsV2.get(id); if (!p) return null; return { ...p, metadata: { ...p.metadata } }; }
+export function listRecommenderProfilesV2() { return [..._crpsV2.values()].map((p) => ({ ...p, metadata: { ...p.metadata } })); }
+
+function _crjCountPending(profileId) { let n = 0; for (const j of _crjsV2.values()) if (j.profileId === profileId && (j.status === RECOMMENDATION_JOB_LIFECYCLE_V2.QUEUED || j.status === RECOMMENDATION_JOB_LIFECYCLE_V2.RUNNING)) n++; return n; }
+
+export function createRecommendationJobV2({ id, profileId, query, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!profileId || typeof profileId !== "string") throw new Error("profileId is required");
+  if (_crjsV2.has(id)) throw new Error(`recommendation job ${id} already exists`);
+  if (!_crpsV2.has(profileId)) throw new Error(`recommender profile ${profileId} not found`);
+  const pending = _crjCountPending(profileId);
+  if (pending >= _crpMaxPendingJobsPerProfile) throw new Error(`max pending recommendation jobs per profile (${_crpMaxPendingJobsPerProfile}) reached for ${profileId}`);
+  const now = Date.now();
+  const j = { id, profileId, query: query || "", status: RECOMMENDATION_JOB_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _crjsV2.set(id, j);
+  return { ...j, metadata: { ...j.metadata } };
+}
+function _crjCheckJ(from, to) { const a = _crjTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid recommendation job transition ${from} → ${to}`); }
+export function startRecommendationJobV2(id) { const j = _crjsV2.get(id); if (!j) throw new Error(`recommendation job ${id} not found`); _crjCheckJ(j.status, RECOMMENDATION_JOB_LIFECYCLE_V2.RUNNING); const now = Date.now(); j.status = RECOMMENDATION_JOB_LIFECYCLE_V2.RUNNING; j.updatedAt = now; if (!j.startedAt) j.startedAt = now; return { ...j, metadata: { ...j.metadata } }; }
+export function completeRecommendationJobV2(id) { const j = _crjsV2.get(id); if (!j) throw new Error(`recommendation job ${id} not found`); _crjCheckJ(j.status, RECOMMENDATION_JOB_LIFECYCLE_V2.COMPLETED); const now = Date.now(); j.status = RECOMMENDATION_JOB_LIFECYCLE_V2.COMPLETED; j.updatedAt = now; if (!j.settledAt) j.settledAt = now; return { ...j, metadata: { ...j.metadata } }; }
+export function failRecommendationJobV2(id, reason) { const j = _crjsV2.get(id); if (!j) throw new Error(`recommendation job ${id} not found`); _crjCheckJ(j.status, RECOMMENDATION_JOB_LIFECYCLE_V2.FAILED); const now = Date.now(); j.status = RECOMMENDATION_JOB_LIFECYCLE_V2.FAILED; j.updatedAt = now; if (!j.settledAt) j.settledAt = now; if (reason) j.metadata.failReason = String(reason); return { ...j, metadata: { ...j.metadata } }; }
+export function cancelRecommendationJobV2(id, reason) { const j = _crjsV2.get(id); if (!j) throw new Error(`recommendation job ${id} not found`); _crjCheckJ(j.status, RECOMMENDATION_JOB_LIFECYCLE_V2.CANCELLED); const now = Date.now(); j.status = RECOMMENDATION_JOB_LIFECYCLE_V2.CANCELLED; j.updatedAt = now; if (!j.settledAt) j.settledAt = now; if (reason) j.metadata.cancelReason = String(reason); return { ...j, metadata: { ...j.metadata } }; }
+export function getRecommendationJobV2(id) { const j = _crjsV2.get(id); if (!j) return null; return { ...j, metadata: { ...j.metadata } }; }
+export function listRecommendationJobsV2() { return [..._crjsV2.values()].map((j) => ({ ...j, metadata: { ...j.metadata } })); }
+
+export function autoStaleIdleRecommenderProfilesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const p of _crpsV2.values()) if (p.status === RECOMMENDER_PROFILE_MATURITY_V2.ACTIVE && (t - p.lastTouchedAt) >= _crpIdleMs) { p.status = RECOMMENDER_PROFILE_MATURITY_V2.STALE; p.updatedAt = t; flipped.push(p.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckRecommendationJobsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const j of _crjsV2.values()) if (j.status === RECOMMENDATION_JOB_LIFECYCLE_V2.RUNNING && j.startedAt != null && (t - j.startedAt) >= _crjStuckMs) { j.status = RECOMMENDATION_JOB_LIFECYCLE_V2.FAILED; j.updatedAt = t; if (!j.settledAt) j.settledAt = t; j.metadata.failReason = "auto-fail-stuck"; flipped.push(j.id); } return { flipped, count: flipped.length }; }
+
+export function getContentRecommenderGovStatsV2() {
+  const profilesByStatus = {}; for (const s of Object.values(RECOMMENDER_PROFILE_MATURITY_V2)) profilesByStatus[s] = 0; for (const p of _crpsV2.values()) profilesByStatus[p.status]++;
+  const jobsByStatus = {}; for (const s of Object.values(RECOMMENDATION_JOB_LIFECYCLE_V2)) jobsByStatus[s] = 0; for (const j of _crjsV2.values()) jobsByStatus[j.status]++;
+  return { totalRecommenderProfilesV2: _crpsV2.size, totalRecommendationJobsV2: _crjsV2.size, maxActiveRecommenderProfilesPerOwner: _crpMaxActivePerOwner, maxPendingRecommendationJobsPerProfile: _crpMaxPendingJobsPerProfile, recommenderProfileIdleMs: _crpIdleMs, recommendationJobStuckMs: _crjStuckMs, profilesByStatus, jobsByStatus };
+}

package/src/lib/cowork-cron.js

@@ -472,3 +472,84 @@ function _minuteKey(date) {
 function _secondKey(date) {
   return `${_minuteKey(date)}-${date.getSeconds()}`;
 }
+
+
+// =====================================================================
+// Cowork Cron V2 governance overlay
+// =====================================================================
+export const CCRON_PROFILE_MATURITY_V2 = Object.freeze({ PENDING: "pending", ACTIVE: "active", PAUSED: "paused", ARCHIVED: "archived" });
+export const CCRON_TICK_LIFECYCLE_V2 = Object.freeze({ QUEUED: "queued", RUNNING: "running", COMPLETED: "completed", FAILED: "failed", CANCELLED: "cancelled" });
+const _ccronPTrans = new Map([
+  [CCRON_PROFILE_MATURITY_V2.PENDING, new Set([CCRON_PROFILE_MATURITY_V2.ACTIVE, CCRON_PROFILE_MATURITY_V2.ARCHIVED])],
+  [CCRON_PROFILE_MATURITY_V2.ACTIVE, new Set([CCRON_PROFILE_MATURITY_V2.PAUSED, CCRON_PROFILE_MATURITY_V2.ARCHIVED])],
+  [CCRON_PROFILE_MATURITY_V2.PAUSED, new Set([CCRON_PROFILE_MATURITY_V2.ACTIVE, CCRON_PROFILE_MATURITY_V2.ARCHIVED])],
+  [CCRON_PROFILE_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _ccronPTerminal = new Set([CCRON_PROFILE_MATURITY_V2.ARCHIVED]);
+const _ccronTTrans = new Map([
+  [CCRON_TICK_LIFECYCLE_V2.QUEUED, new Set([CCRON_TICK_LIFECYCLE_V2.RUNNING, CCRON_TICK_LIFECYCLE_V2.CANCELLED])],
+  [CCRON_TICK_LIFECYCLE_V2.RUNNING, new Set([CCRON_TICK_LIFECYCLE_V2.COMPLETED, CCRON_TICK_LIFECYCLE_V2.FAILED, CCRON_TICK_LIFECYCLE_V2.CANCELLED])],
+  [CCRON_TICK_LIFECYCLE_V2.COMPLETED, new Set()],
+  [CCRON_TICK_LIFECYCLE_V2.FAILED, new Set()],
+  [CCRON_TICK_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+const _ccronPsV2 = new Map();
+const _ccronTsV2 = new Map();
+let _ccronMaxActive = 6, _ccronMaxPending = 15, _ccronIdleMs = 30 * 24 * 60 * 60 * 1000, _ccronStuckMs = 60 * 1000;
+function _ccronPos(n, label) { const v = Math.floor(Number(n)); if (!Number.isFinite(v) || v <= 0) throw new Error(`${label} must be positive integer`); return v; }
+function _ccronCheckP(from, to) { const a = _ccronPTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid ccron profile transition ${from} → ${to}`); }
+function _ccronCheckT(from, to) { const a = _ccronTTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid ccron tick transition ${from} → ${to}`); }
+function _ccronCountActive(owner) { let c = 0; for (const p of _ccronPsV2.values()) if (p.owner === owner && p.status === CCRON_PROFILE_MATURITY_V2.ACTIVE) c++; return c; }
+function _ccronCountPending(profileId) { let c = 0; for (const t of _ccronTsV2.values()) if (t.profileId === profileId && (t.status === CCRON_TICK_LIFECYCLE_V2.QUEUED || t.status === CCRON_TICK_LIFECYCLE_V2.RUNNING)) c++; return c; }
+export function setMaxActiveCcronProfilesPerOwnerV2(n) { _ccronMaxActive = _ccronPos(n, "maxActiveCcronProfilesPerOwner"); }
+export function getMaxActiveCcronProfilesPerOwnerV2() { return _ccronMaxActive; }
+export function setMaxPendingCcronTicksPerProfileV2(n) { _ccronMaxPending = _ccronPos(n, "maxPendingCcronTicksPerProfile"); }
+export function getMaxPendingCcronTicksPerProfileV2() { return _ccronMaxPending; }
+export function setCcronProfileIdleMsV2(n) { _ccronIdleMs = _ccronPos(n, "ccronProfileIdleMs"); }
+export function getCcronProfileIdleMsV2() { return _ccronIdleMs; }
+export function setCcronTickStuckMsV2(n) { _ccronStuckMs = _ccronPos(n, "ccronTickStuckMs"); }
+export function getCcronTickStuckMsV2() { return _ccronStuckMs; }
+export function _resetStateCoworkCronV2() { _ccronPsV2.clear(); _ccronTsV2.clear(); _ccronMaxActive = 6; _ccronMaxPending = 15; _ccronIdleMs = 30 * 24 * 60 * 60 * 1000; _ccronStuckMs = 60 * 1000; }
+export function registerCcronProfileV2({ id, owner, expr, metadata } = {}) {
+  if (!id || !owner) throw new Error("id and owner required");
+  if (_ccronPsV2.has(id)) throw new Error(`ccron profile ${id} already exists`);
+  const now = Date.now();
+  const p = { id, owner, expr: expr || "0 0 * * *", status: CCRON_PROFILE_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, lastTouchedAt: now, activatedAt: null, archivedAt: null, metadata: { ...(metadata || {}) } };
+  _ccronPsV2.set(id, p); return { ...p, metadata: { ...p.metadata } };
+}
+export function activateCcronProfileV2(id) {
+  const p = _ccronPsV2.get(id); if (!p) throw new Error(`ccron profile ${id} not found`);
+  const isInitial = p.status === CCRON_PROFILE_MATURITY_V2.PENDING;
+  _ccronCheckP(p.status, CCRON_PROFILE_MATURITY_V2.ACTIVE);
+  if (isInitial && _ccronCountActive(p.owner) >= _ccronMaxActive) throw new Error(`max active ccron profiles for owner ${p.owner} reached`);
+  const now = Date.now(); p.status = CCRON_PROFILE_MATURITY_V2.ACTIVE; p.updatedAt = now; p.lastTouchedAt = now;
+  if (!p.activatedAt) p.activatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function pauseCcronProfileV2(id) { const p = _ccronPsV2.get(id); if (!p) throw new Error(`ccron profile ${id} not found`); _ccronCheckP(p.status, CCRON_PROFILE_MATURITY_V2.PAUSED); p.status = CCRON_PROFILE_MATURITY_V2.PAUSED; p.updatedAt = Date.now(); return { ...p, metadata: { ...p.metadata } }; }
+export function archiveCcronProfileV2(id) { const p = _ccronPsV2.get(id); if (!p) throw new Error(`ccron profile ${id} not found`); _ccronCheckP(p.status, CCRON_PROFILE_MATURITY_V2.ARCHIVED); const now = Date.now(); p.status = CCRON_PROFILE_MATURITY_V2.ARCHIVED; p.updatedAt = now; if (!p.archivedAt) p.archivedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function touchCcronProfileV2(id) { const p = _ccronPsV2.get(id); if (!p) throw new Error(`ccron profile ${id} not found`); if (_ccronPTerminal.has(p.status)) throw new Error(`cannot touch terminal ccron profile ${id}`); const now = Date.now(); p.lastTouchedAt = now; p.updatedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function getCcronProfileV2(id) { const p = _ccronPsV2.get(id); if (!p) return null; return { ...p, metadata: { ...p.metadata } }; }
+export function listCcronProfilesV2() { return [..._ccronPsV2.values()].map((p) => ({ ...p, metadata: { ...p.metadata } })); }
+export function createCcronTickV2({ id, profileId, tickAt, metadata } = {}) {
+  if (!id || !profileId) throw new Error("id and profileId required");
+  if (_ccronTsV2.has(id)) throw new Error(`ccron tick ${id} already exists`);
+  if (!_ccronPsV2.has(profileId)) throw new Error(`ccron profile ${profileId} not found`);
+  if (_ccronCountPending(profileId) >= _ccronMaxPending) throw new Error(`max pending ccron ticks for profile ${profileId} reached`);
+  const now = Date.now();
+  const t = { id, profileId, tickAt: tickAt || now, status: CCRON_TICK_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _ccronTsV2.set(id, t); return { ...t, metadata: { ...t.metadata } };
+}
+export function runningCcronTickV2(id) { const t = _ccronTsV2.get(id); if (!t) throw new Error(`ccron tick ${id} not found`); _ccronCheckT(t.status, CCRON_TICK_LIFECYCLE_V2.RUNNING); const now = Date.now(); t.status = CCRON_TICK_LIFECYCLE_V2.RUNNING; t.updatedAt = now; if (!t.startedAt) t.startedAt = now; return { ...t, metadata: { ...t.metadata } }; }
+export function completeCcronTickV2(id) { const t = _ccronTsV2.get(id); if (!t) throw new Error(`ccron tick ${id} not found`); _ccronCheckT(t.status, CCRON_TICK_LIFECYCLE_V2.COMPLETED); const now = Date.now(); t.status = CCRON_TICK_LIFECYCLE_V2.COMPLETED; t.updatedAt = now; if (!t.settledAt) t.settledAt = now; return { ...t, metadata: { ...t.metadata } }; }
+export function failCcronTickV2(id, reason) { const t = _ccronTsV2.get(id); if (!t) throw new Error(`ccron tick ${id} not found`); _ccronCheckT(t.status, CCRON_TICK_LIFECYCLE_V2.FAILED); const now = Date.now(); t.status = CCRON_TICK_LIFECYCLE_V2.FAILED; t.updatedAt = now; if (!t.settledAt) t.settledAt = now; if (reason) t.metadata.failReason = String(reason); return { ...t, metadata: { ...t.metadata } }; }
+export function cancelCcronTickV2(id, reason) { const t = _ccronTsV2.get(id); if (!t) throw new Error(`ccron tick ${id} not found`); _ccronCheckT(t.status, CCRON_TICK_LIFECYCLE_V2.CANCELLED); const now = Date.now(); t.status = CCRON_TICK_LIFECYCLE_V2.CANCELLED; t.updatedAt = now; if (!t.settledAt) t.settledAt = now; if (reason) t.metadata.cancelReason = String(reason); return { ...t, metadata: { ...t.metadata } }; }
+export function getCcronTickV2(id) { const t = _ccronTsV2.get(id); if (!t) return null; return { ...t, metadata: { ...t.metadata } }; }
+export function listCcronTicksV2() { return [..._ccronTsV2.values()].map((t) => ({ ...t, metadata: { ...t.metadata } })); }
+export function autoPauseIdleCcronProfilesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const p of _ccronPsV2.values()) if (p.status === CCRON_PROFILE_MATURITY_V2.ACTIVE && (t - p.lastTouchedAt) >= _ccronIdleMs) { p.status = CCRON_PROFILE_MATURITY_V2.PAUSED; p.updatedAt = t; flipped.push(p.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckCcronTicksV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const x of _ccronTsV2.values()) if (x.status === CCRON_TICK_LIFECYCLE_V2.RUNNING && x.startedAt != null && (t - x.startedAt) >= _ccronStuckMs) { x.status = CCRON_TICK_LIFECYCLE_V2.FAILED; x.updatedAt = t; if (!x.settledAt) x.settledAt = t; x.metadata.failReason = "auto-fail-stuck"; flipped.push(x.id); } return { flipped, count: flipped.length }; }
+export function getCoworkCronGovStatsV2() {
+  const profilesByStatus = {}; for (const v of Object.values(CCRON_PROFILE_MATURITY_V2)) profilesByStatus[v] = 0; for (const p of _ccronPsV2.values()) profilesByStatus[p.status]++;
+  const ticksByStatus = {}; for (const v of Object.values(CCRON_TICK_LIFECYCLE_V2)) ticksByStatus[v] = 0; for (const t of _ccronTsV2.values()) ticksByStatus[t.status]++;
+  return { totalCcronProfilesV2: _ccronPsV2.size, totalCcronTicksV2: _ccronTsV2.size, maxActiveCcronProfilesPerOwner: _ccronMaxActive, maxPendingCcronTicksPerProfile: _ccronMaxPending, ccronProfileIdleMs: _ccronIdleMs, ccronTickStuckMs: _ccronStuckMs, profilesByStatus, ticksByStatus };
+}