chainlesschain 0.81.0 → 0.143.0

package/src/lib/social-graph-analytics.js

@@ -705,3 +705,84 @@ export function analyticsStats(snapshot, opts = {}) {
     generatedAt: new Date().toISOString(),
   };
 }
+
+
+// =====================================================================
+// Social Graph Analytics V2 governance overlay
+// =====================================================================
+export const SGAN_PROFILE_MATURITY_V2 = Object.freeze({ PENDING: "pending", ACTIVE: "active", STALE: "stale", ARCHIVED: "archived" });
+export const SGAN_RUN_LIFECYCLE_V2 = Object.freeze({ QUEUED: "queued", RUNNING: "running", COMPLETED: "completed", FAILED: "failed", CANCELLED: "cancelled" });
+const _sganPTrans = new Map([
+  [SGAN_PROFILE_MATURITY_V2.PENDING, new Set([SGAN_PROFILE_MATURITY_V2.ACTIVE, SGAN_PROFILE_MATURITY_V2.ARCHIVED])],
+  [SGAN_PROFILE_MATURITY_V2.ACTIVE, new Set([SGAN_PROFILE_MATURITY_V2.STALE, SGAN_PROFILE_MATURITY_V2.ARCHIVED])],
+  [SGAN_PROFILE_MATURITY_V2.STALE, new Set([SGAN_PROFILE_MATURITY_V2.ACTIVE, SGAN_PROFILE_MATURITY_V2.ARCHIVED])],
+  [SGAN_PROFILE_MATURITY_V2.ARCHIVED, new Set()],
+]);
+const _sganPTerminal = new Set([SGAN_PROFILE_MATURITY_V2.ARCHIVED]);
+const _sganJTrans = new Map([
+  [SGAN_RUN_LIFECYCLE_V2.QUEUED, new Set([SGAN_RUN_LIFECYCLE_V2.RUNNING, SGAN_RUN_LIFECYCLE_V2.CANCELLED])],
+  [SGAN_RUN_LIFECYCLE_V2.RUNNING, new Set([SGAN_RUN_LIFECYCLE_V2.COMPLETED, SGAN_RUN_LIFECYCLE_V2.FAILED, SGAN_RUN_LIFECYCLE_V2.CANCELLED])],
+  [SGAN_RUN_LIFECYCLE_V2.COMPLETED, new Set()],
+  [SGAN_RUN_LIFECYCLE_V2.FAILED, new Set()],
+  [SGAN_RUN_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+const _sganPsV2 = new Map();
+const _sganJsV2 = new Map();
+let _sganMaxActive = 6, _sganMaxPending = 12, _sganIdleMs = 30 * 24 * 60 * 60 * 1000, _sganStuckMs = 60 * 1000;
+function _sganPos(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 _sganCheckP(from, to) { const a = _sganPTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid sgan profile transition ${from} → ${to}`); }
+function _sganCheckJ(from, to) { const a = _sganJTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid sgan run transition ${from} → ${to}`); }
+function _sganCountActive(owner) { let c = 0; for (const p of _sganPsV2.values()) if (p.owner === owner && p.status === SGAN_PROFILE_MATURITY_V2.ACTIVE) c++; return c; }
+function _sganCountPending(profileId) { let c = 0; for (const j of _sganJsV2.values()) if (j.profileId === profileId && (j.status === SGAN_RUN_LIFECYCLE_V2.QUEUED || j.status === SGAN_RUN_LIFECYCLE_V2.RUNNING)) c++; return c; }
+export function setMaxActiveSganProfilesPerOwnerV2(n) { _sganMaxActive = _sganPos(n, "maxActiveSganProfilesPerOwner"); }
+export function getMaxActiveSganProfilesPerOwnerV2() { return _sganMaxActive; }
+export function setMaxPendingSganRunsPerProfileV2(n) { _sganMaxPending = _sganPos(n, "maxPendingSganRunsPerProfile"); }
+export function getMaxPendingSganRunsPerProfileV2() { return _sganMaxPending; }
+export function setSganProfileIdleMsV2(n) { _sganIdleMs = _sganPos(n, "sganProfileIdleMs"); }
+export function getSganProfileIdleMsV2() { return _sganIdleMs; }
+export function setSganRunStuckMsV2(n) { _sganStuckMs = _sganPos(n, "sganRunStuckMs"); }
+export function getSganRunStuckMsV2() { return _sganStuckMs; }
+export function _resetStateSocialGraphAnalyticsV2() { _sganPsV2.clear(); _sganJsV2.clear(); _sganMaxActive = 6; _sganMaxPending = 12; _sganIdleMs = 30 * 24 * 60 * 60 * 1000; _sganStuckMs = 60 * 1000; }
+export function registerSganProfileV2({ id, owner, algorithm, metadata } = {}) {
+  if (!id || !owner) throw new Error("id and owner required");
+  if (_sganPsV2.has(id)) throw new Error(`sgan profile ${id} already exists`);
+  const now = Date.now();
+  const p = { id, owner, algorithm: algorithm || "centrality", status: SGAN_PROFILE_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, lastTouchedAt: now, activatedAt: null, archivedAt: null, metadata: { ...(metadata || {}) } };
+  _sganPsV2.set(id, p); return { ...p, metadata: { ...p.metadata } };
+}
+export function activateSganProfileV2(id) {
+  const p = _sganPsV2.get(id); if (!p) throw new Error(`sgan profile ${id} not found`);
+  const isInitial = p.status === SGAN_PROFILE_MATURITY_V2.PENDING;
+  _sganCheckP(p.status, SGAN_PROFILE_MATURITY_V2.ACTIVE);
+  if (isInitial && _sganCountActive(p.owner) >= _sganMaxActive) throw new Error(`max active sgan profiles for owner ${p.owner} reached`);
+  const now = Date.now(); p.status = SGAN_PROFILE_MATURITY_V2.ACTIVE; p.updatedAt = now; p.lastTouchedAt = now;
+  if (!p.activatedAt) p.activatedAt = now;
+  return { ...p, metadata: { ...p.metadata } };
+}
+export function staleSganProfileV2(id) { const p = _sganPsV2.get(id); if (!p) throw new Error(`sgan profile ${id} not found`); _sganCheckP(p.status, SGAN_PROFILE_MATURITY_V2.STALE); p.status = SGAN_PROFILE_MATURITY_V2.STALE; p.updatedAt = Date.now(); return { ...p, metadata: { ...p.metadata } }; }
+export function archiveSganProfileV2(id) { const p = _sganPsV2.get(id); if (!p) throw new Error(`sgan profile ${id} not found`); _sganCheckP(p.status, SGAN_PROFILE_MATURITY_V2.ARCHIVED); const now = Date.now(); p.status = SGAN_PROFILE_MATURITY_V2.ARCHIVED; p.updatedAt = now; if (!p.archivedAt) p.archivedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function touchSganProfileV2(id) { const p = _sganPsV2.get(id); if (!p) throw new Error(`sgan profile ${id} not found`); if (_sganPTerminal.has(p.status)) throw new Error(`cannot touch terminal sgan profile ${id}`); const now = Date.now(); p.lastTouchedAt = now; p.updatedAt = now; return { ...p, metadata: { ...p.metadata } }; }
+export function getSganProfileV2(id) { const p = _sganPsV2.get(id); if (!p) return null; return { ...p, metadata: { ...p.metadata } }; }
+export function listSganProfilesV2() { return [..._sganPsV2.values()].map((p) => ({ ...p, metadata: { ...p.metadata } })); }
+export function createSganRunV2({ id, profileId, snapshotId, metadata } = {}) {
+  if (!id || !profileId) throw new Error("id and profileId required");
+  if (_sganJsV2.has(id)) throw new Error(`sgan run ${id} already exists`);
+  if (!_sganPsV2.has(profileId)) throw new Error(`sgan profile ${profileId} not found`);
+  if (_sganCountPending(profileId) >= _sganMaxPending) throw new Error(`max pending sgan runs for profile ${profileId} reached`);
+  const now = Date.now();
+  const j = { id, profileId, snapshotId: snapshotId || "", status: SGAN_RUN_LIFECYCLE_V2.QUEUED, createdAt: now, updatedAt: now, startedAt: null, settledAt: null, metadata: { ...(metadata || {}) } };
+  _sganJsV2.set(id, j); return { ...j, metadata: { ...j.metadata } };
+}
+export function runningSganRunV2(id) { const j = _sganJsV2.get(id); if (!j) throw new Error(`sgan run ${id} not found`); _sganCheckJ(j.status, SGAN_RUN_LIFECYCLE_V2.RUNNING); const now = Date.now(); j.status = SGAN_RUN_LIFECYCLE_V2.RUNNING; j.updatedAt = now; if (!j.startedAt) j.startedAt = now; return { ...j, metadata: { ...j.metadata } }; }
+export function completeSganRunV2(id) { const j = _sganJsV2.get(id); if (!j) throw new Error(`sgan run ${id} not found`); _sganCheckJ(j.status, SGAN_RUN_LIFECYCLE_V2.COMPLETED); const now = Date.now(); j.status = SGAN_RUN_LIFECYCLE_V2.COMPLETED; j.updatedAt = now; if (!j.settledAt) j.settledAt = now; return { ...j, metadata: { ...j.metadata } }; }
+export function failSganRunV2(id, reason) { const j = _sganJsV2.get(id); if (!j) throw new Error(`sgan run ${id} not found`); _sganCheckJ(j.status, SGAN_RUN_LIFECYCLE_V2.FAILED); const now = Date.now(); j.status = SGAN_RUN_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 cancelSganRunV2(id, reason) { const j = _sganJsV2.get(id); if (!j) throw new Error(`sgan run ${id} not found`); _sganCheckJ(j.status, SGAN_RUN_LIFECYCLE_V2.CANCELLED); const now = Date.now(); j.status = SGAN_RUN_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 getSganRunV2(id) { const j = _sganJsV2.get(id); if (!j) return null; return { ...j, metadata: { ...j.metadata } }; }
+export function listSganRunsV2() { return [..._sganJsV2.values()].map((j) => ({ ...j, metadata: { ...j.metadata } })); }
+export function autoStaleIdleSganProfilesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const p of _sganPsV2.values()) if (p.status === SGAN_PROFILE_MATURITY_V2.ACTIVE && (t - p.lastTouchedAt) >= _sganIdleMs) { p.status = SGAN_PROFILE_MATURITY_V2.STALE; p.updatedAt = t; flipped.push(p.id); } return { flipped, count: flipped.length }; }
+export function autoFailStuckSganRunsV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const j of _sganJsV2.values()) if (j.status === SGAN_RUN_LIFECYCLE_V2.RUNNING && j.startedAt != null && (t - j.startedAt) >= _sganStuckMs) { j.status = SGAN_RUN_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 getSocialGraphAnalyticsGovStatsV2() {
+  const profilesByStatus = {}; for (const v of Object.values(SGAN_PROFILE_MATURITY_V2)) profilesByStatus[v] = 0; for (const p of _sganPsV2.values()) profilesByStatus[p.status]++;
+  const runsByStatus = {}; for (const v of Object.values(SGAN_RUN_LIFECYCLE_V2)) runsByStatus[v] = 0; for (const j of _sganJsV2.values()) runsByStatus[j.status]++;
+  return { totalSganProfilesV2: _sganPsV2.size, totalSganRunsV2: _sganJsV2.size, maxActiveSganProfilesPerOwner: _sganMaxActive, maxPendingSganRunsPerProfile: _sganMaxPending, sganProfileIdleMs: _sganIdleMs, sganRunStuckMs: _sganStuckMs, profilesByStatus, runsByStatus };
+}

package/src/lib/social-graph.js

@@ -406,3 +406,84 @@ export function _resetState() {
   _nodes.clear();
   _bus.removeAllListeners();
 }
+
+// ===== V2 Surface: Social Graph governance overlay (CLI v0.141.0) =====
+export const SG_NODE_MATURITY_V2 = Object.freeze({
+  PENDING: "pending", ACTIVE: "active", INACTIVE: "inactive", REMOVED: "removed",
+});
+export const SG_EDGE_LIFECYCLE_V2 = Object.freeze({
+  PROPOSED: "proposed", ESTABLISHED: "established", SEVERED: "severed", EXPIRED: "expired", CANCELLED: "cancelled",
+});
+const _sgNTrans = new Map([
+  [SG_NODE_MATURITY_V2.PENDING, new Set([SG_NODE_MATURITY_V2.ACTIVE, SG_NODE_MATURITY_V2.REMOVED])],
+  [SG_NODE_MATURITY_V2.ACTIVE, new Set([SG_NODE_MATURITY_V2.INACTIVE, SG_NODE_MATURITY_V2.REMOVED])],
+  [SG_NODE_MATURITY_V2.INACTIVE, new Set([SG_NODE_MATURITY_V2.ACTIVE, SG_NODE_MATURITY_V2.REMOVED])],
+  [SG_NODE_MATURITY_V2.REMOVED, new Set()],
+]);
+const _sgNTerminal = new Set([SG_NODE_MATURITY_V2.REMOVED]);
+const _sgETrans = new Map([
+  [SG_EDGE_LIFECYCLE_V2.PROPOSED, new Set([SG_EDGE_LIFECYCLE_V2.ESTABLISHED, SG_EDGE_LIFECYCLE_V2.CANCELLED])],
+  [SG_EDGE_LIFECYCLE_V2.ESTABLISHED, new Set([SG_EDGE_LIFECYCLE_V2.SEVERED, SG_EDGE_LIFECYCLE_V2.EXPIRED])],
+  [SG_EDGE_LIFECYCLE_V2.SEVERED, new Set()],
+  [SG_EDGE_LIFECYCLE_V2.EXPIRED, new Set()],
+  [SG_EDGE_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+const _sgNsV2 = new Map();
+const _sgEsV2 = new Map();
+let _sgMaxActivePerOwner = 50, _sgMaxPendingEdgesPerNode = 100, _sgIdleMs = 60 * 24 * 60 * 60 * 1000, _sgStuckMs = 14 * 24 * 60 * 60 * 1000;
+function _sgPos(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 _sgCheckN(from, to) { const a = _sgNTrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid sg node transition ${from} → ${to}`); }
+function _sgCheckE(from, to) { const a = _sgETrans.get(from); if (!a || !a.has(to)) throw new Error(`invalid sg edge transition ${from} → ${to}`); }
+export function setMaxActiveSgNodesPerOwnerV2(n) { _sgMaxActivePerOwner = _sgPos(n, "maxActiveSgNodesPerOwner"); }
+export function getMaxActiveSgNodesPerOwnerV2() { return _sgMaxActivePerOwner; }
+export function setMaxPendingSgEdgesPerNodeV2(n) { _sgMaxPendingEdgesPerNode = _sgPos(n, "maxPendingSgEdgesPerNode"); }
+export function getMaxPendingSgEdgesPerNodeV2() { return _sgMaxPendingEdgesPerNode; }
+export function setSgNodeIdleMsV2(n) { _sgIdleMs = _sgPos(n, "sgNodeIdleMs"); }
+export function getSgNodeIdleMsV2() { return _sgIdleMs; }
+export function setSgEdgeStuckMsV2(n) { _sgStuckMs = _sgPos(n, "sgEdgeStuckMs"); }
+export function getSgEdgeStuckMsV2() { return _sgStuckMs; }
+export function _resetStateSocialGraphV2() { _sgNsV2.clear(); _sgEsV2.clear(); _sgMaxActivePerOwner = 50; _sgMaxPendingEdgesPerNode = 100; _sgIdleMs = 60 * 24 * 60 * 60 * 1000; _sgStuckMs = 14 * 24 * 60 * 60 * 1000; }
+export function registerSgNodeV2({ id, owner, handle, metadata } = {}) {
+  if (!id) throw new Error("sg node id required"); if (!owner) throw new Error("sg node owner required");
+  if (_sgNsV2.has(id)) throw new Error(`sg node ${id} already registered`);
+  const now = Date.now();
+  const n = { id, owner, handle: handle || id, status: SG_NODE_MATURITY_V2.PENDING, createdAt: now, updatedAt: now, activatedAt: null, removedAt: null, lastTouchedAt: now, metadata: { ...(metadata || {}) } };
+  _sgNsV2.set(id, n); return { ...n, metadata: { ...n.metadata } };
+}
+function _sgCountActive(owner) { let n = 0; for (const v of _sgNsV2.values()) if (v.owner === owner && v.status === SG_NODE_MATURITY_V2.ACTIVE) n++; return n; }
+export function activateSgNodeV2(id) {
+  const n = _sgNsV2.get(id); if (!n) throw new Error(`sg node ${id} not found`);
+  _sgCheckN(n.status, SG_NODE_MATURITY_V2.ACTIVE);
+  const recovery = n.status === SG_NODE_MATURITY_V2.INACTIVE;
+  if (!recovery && _sgCountActive(n.owner) >= _sgMaxActivePerOwner) throw new Error(`max active sg nodes for owner ${n.owner} reached`);
+  const now = Date.now(); n.status = SG_NODE_MATURITY_V2.ACTIVE; n.updatedAt = now; n.lastTouchedAt = now; if (!n.activatedAt) n.activatedAt = now;
+  return { ...n, metadata: { ...n.metadata } };
+}
+export function deactivateSgNodeV2(id) { const n = _sgNsV2.get(id); if (!n) throw new Error(`sg node ${id} not found`); _sgCheckN(n.status, SG_NODE_MATURITY_V2.INACTIVE); n.status = SG_NODE_MATURITY_V2.INACTIVE; n.updatedAt = Date.now(); return { ...n, metadata: { ...n.metadata } }; }
+export function removeSgNodeV2(id) { const n = _sgNsV2.get(id); if (!n) throw new Error(`sg node ${id} not found`); _sgCheckN(n.status, SG_NODE_MATURITY_V2.REMOVED); const now = Date.now(); n.status = SG_NODE_MATURITY_V2.REMOVED; n.updatedAt = now; if (!n.removedAt) n.removedAt = now; return { ...n, metadata: { ...n.metadata } }; }
+export function touchSgNodeV2(id) { const n = _sgNsV2.get(id); if (!n) throw new Error(`sg node ${id} not found`); if (_sgNTerminal.has(n.status)) throw new Error(`cannot touch terminal sg node ${id}`); const now = Date.now(); n.lastTouchedAt = now; n.updatedAt = now; return { ...n, metadata: { ...n.metadata } }; }
+export function getSgNodeV2(id) { const n = _sgNsV2.get(id); if (!n) return null; return { ...n, metadata: { ...n.metadata } }; }
+export function listSgNodesV2() { return [..._sgNsV2.values()].map((n) => ({ ...n, metadata: { ...n.metadata } })); }
+function _sgCountPending(nodeId) { let n = 0; for (const e of _sgEsV2.values()) if (e.nodeId === nodeId && e.status === SG_EDGE_LIFECYCLE_V2.PROPOSED) n++; return n; }
+export function createSgEdgeV2({ id, nodeId, targetId, metadata } = {}) {
+  if (!id) throw new Error("sg edge id required"); if (!nodeId) throw new Error("sg edge nodeId required");
+  if (_sgEsV2.has(id)) throw new Error(`sg edge ${id} already exists`);
+  if (!_sgNsV2.has(nodeId)) throw new Error(`sg node ${nodeId} not found`);
+  if (_sgCountPending(nodeId) >= _sgMaxPendingEdgesPerNode) throw new Error(`max pending sg edges for node ${nodeId} reached`);
+  const now = Date.now();
+  const e = { id, nodeId, targetId: targetId || "", status: SG_EDGE_LIFECYCLE_V2.PROPOSED, createdAt: now, updatedAt: now, startedAt: now, settledAt: null, metadata: { ...(metadata || {}) } };
+  _sgEsV2.set(id, e); return { ...e, metadata: { ...e.metadata } };
+}
+export function establishSgEdgeV2(id) { const e = _sgEsV2.get(id); if (!e) throw new Error(`sg edge ${id} not found`); _sgCheckE(e.status, SG_EDGE_LIFECYCLE_V2.ESTABLISHED); const now = Date.now(); e.status = SG_EDGE_LIFECYCLE_V2.ESTABLISHED; e.updatedAt = now; if (!e.settledAt) e.settledAt = now; return { ...e, metadata: { ...e.metadata } }; }
+export function severSgEdgeV2(id, reason) { const e = _sgEsV2.get(id); if (!e) throw new Error(`sg edge ${id} not found`); _sgCheckE(e.status, SG_EDGE_LIFECYCLE_V2.SEVERED); const now = Date.now(); e.status = SG_EDGE_LIFECYCLE_V2.SEVERED; e.updatedAt = now; if (reason) e.metadata.severReason = String(reason); return { ...e, metadata: { ...e.metadata } }; }
+export function expireSgEdgeV2(id) { const e = _sgEsV2.get(id); if (!e) throw new Error(`sg edge ${id} not found`); _sgCheckE(e.status, SG_EDGE_LIFECYCLE_V2.EXPIRED); const now = Date.now(); e.status = SG_EDGE_LIFECYCLE_V2.EXPIRED; e.updatedAt = now; return { ...e, metadata: { ...e.metadata } }; }
+export function cancelSgEdgeV2(id, reason) { const e = _sgEsV2.get(id); if (!e) throw new Error(`sg edge ${id} not found`); _sgCheckE(e.status, SG_EDGE_LIFECYCLE_V2.CANCELLED); const now = Date.now(); e.status = SG_EDGE_LIFECYCLE_V2.CANCELLED; e.updatedAt = now; if (!e.settledAt) e.settledAt = now; if (reason) e.metadata.cancelReason = String(reason); return { ...e, metadata: { ...e.metadata } }; }
+export function getSgEdgeV2(id) { const e = _sgEsV2.get(id); if (!e) return null; return { ...e, metadata: { ...e.metadata } }; }
+export function listSgEdgesV2() { return [..._sgEsV2.values()].map((e) => ({ ...e, metadata: { ...e.metadata } })); }
+export function autoDeactivateIdleSgNodesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const n of _sgNsV2.values()) if (n.status === SG_NODE_MATURITY_V2.ACTIVE && (t - n.lastTouchedAt) >= _sgIdleMs) { n.status = SG_NODE_MATURITY_V2.INACTIVE; n.updatedAt = t; flipped.push(n.id); } return { flipped, count: flipped.length }; }
+export function autoExpireStaleSgEdgesV2({ now } = {}) { const t = now ?? Date.now(); const flipped = []; for (const e of _sgEsV2.values()) if (e.status === SG_EDGE_LIFECYCLE_V2.PROPOSED && (t - e.startedAt) >= _sgStuckMs) { e.status = SG_EDGE_LIFECYCLE_V2.CANCELLED; e.updatedAt = t; if (!e.settledAt) e.settledAt = t; e.metadata.cancelReason = "auto-cancel-stale"; flipped.push(e.id); } return { flipped, count: flipped.length }; }
+export function getSocialGraphGovStatsV2() {
+  const nodesByStatus = {}; for (const v of Object.values(SG_NODE_MATURITY_V2)) nodesByStatus[v] = 0; for (const n of _sgNsV2.values()) nodesByStatus[n.status]++;
+  const edgesByStatus = {}; for (const v of Object.values(SG_EDGE_LIFECYCLE_V2)) edgesByStatus[v] = 0; for (const e of _sgEsV2.values()) edgesByStatus[e.status]++;
+  return { totalSgNodesV2: _sgNsV2.size, totalSgEdgesV2: _sgEsV2.size, maxActiveSgNodesPerOwner: _sgMaxActivePerOwner, maxPendingSgEdgesPerNode: _sgMaxPendingEdgesPerNode, sgNodeIdleMs: _sgIdleMs, sgEdgeStuckMs: _sgStuckMs, nodesByStatus, edgesByStatus };
+}

package/src/lib/social-manager.js

@@ -281,3 +281,329 @@ export function _resetState() {
   _posts.clear();
   _messages.clear();
 }
+
+/* ═══════════════════════════════════════════════════════════════
+ * V2 Surface — Social governance layer.
+ * Tracks relationship maturity + thread lifecycle independent of
+ * legacy contacts/friends/posts/messages stores above.
+ * ═══════════════════════════════════════════════════════════════ */
+
+export const RELATIONSHIP_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  CONNECTED: "connected",
+  MUTED: "muted",
+  BLOCKED: "blocked",
+});
+
+export const THREAD_LIFECYCLE_V2 = Object.freeze({
+  OPEN: "open",
+  ENGAGED: "engaged",
+  RESOLVED: "resolved",
+  ABANDONED: "abandoned",
+  REPORTED: "reported",
+});
+
+const REL_TRANSITIONS_V2 = new Map([
+  ["pending", new Set(["connected", "blocked"])],
+  ["connected", new Set(["muted", "blocked"])],
+  ["muted", new Set(["connected", "blocked"])],
+  ["blocked", new Set()],
+]);
+const REL_TERMINALS_V2 = new Set(["blocked"]);
+
+const THREAD_TRANSITIONS_V2 = new Map([
+  ["open", new Set(["engaged", "abandoned", "reported"])],
+  ["engaged", new Set(["resolved", "abandoned", "reported"])],
+  ["resolved", new Set()],
+  ["abandoned", new Set()],
+  ["reported", new Set()],
+]);
+const THREAD_TERMINALS_V2 = new Set(["resolved", "abandoned", "reported"]);
+
+export const SOCIAL_DEFAULT_MAX_CONNECTED_PER_USER = 500;
+export const SOCIAL_DEFAULT_MAX_OPEN_THREADS_PER_USER = 50;
+export const SOCIAL_DEFAULT_RELATIONSHIP_IDLE_MS = 1000 * 60 * 60 * 24 * 180; // 180 days
+export const SOCIAL_DEFAULT_THREAD_STUCK_MS = 1000 * 60 * 60 * 24 * 7; // 7 days
+
+const _relationshipsV2 = new Map();
+const _threadsV2 = new Map();
+let _maxConnectedPerUserV2 = SOCIAL_DEFAULT_MAX_CONNECTED_PER_USER;
+let _maxOpenThreadsPerUserV2 = SOCIAL_DEFAULT_MAX_OPEN_THREADS_PER_USER;
+let _relationshipIdleMsV2 = SOCIAL_DEFAULT_RELATIONSHIP_IDLE_MS;
+let _threadStuckMsV2 = SOCIAL_DEFAULT_THREAD_STUCK_MS;
+
+function _posIntSocialV2(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 getMaxConnectedPerUserV2() {
+  return _maxConnectedPerUserV2;
+}
+export function setMaxConnectedPerUserV2(n) {
+  _maxConnectedPerUserV2 = _posIntSocialV2(n, "maxConnectedPerUser");
+}
+export function getMaxOpenThreadsPerUserV2() {
+  return _maxOpenThreadsPerUserV2;
+}
+export function setMaxOpenThreadsPerUserV2(n) {
+  _maxOpenThreadsPerUserV2 = _posIntSocialV2(n, "maxOpenThreadsPerUser");
+}
+export function getRelationshipIdleMsV2() {
+  return _relationshipIdleMsV2;
+}
+export function setRelationshipIdleMsV2(n) {
+  _relationshipIdleMsV2 = _posIntSocialV2(n, "relationshipIdleMs");
+}
+export function getThreadStuckMsV2() {
+  return _threadStuckMsV2;
+}
+export function setThreadStuckMsV2(n) {
+  _threadStuckMsV2 = _posIntSocialV2(n, "threadStuckMs");
+}
+
+export function getConnectedCountV2(userId) {
+  let n = 0;
+  for (const r of _relationshipsV2.values()) {
+    if (r.userId === userId && r.status === "connected") n += 1;
+  }
+  return n;
+}
+
+export function getOpenThreadCountV2(userId) {
+  let n = 0;
+  for (const t of _threadsV2.values()) {
+    if (t.userId === userId && (t.status === "open" || t.status === "engaged"))
+      n += 1;
+  }
+  return n;
+}
+
+function _copyRelV2(r) {
+  return { ...r, metadata: { ...r.metadata } };
+}
+function _copyThreadV2(t) {
+  return { ...t, metadata: { ...t.metadata } };
+}
+
+export function registerRelationshipV2(
+  id,
+  { userId, peerId, metadata = {}, now = Date.now() } = {},
+) {
+  if (!id || typeof id !== "string") throw new Error("id must be a string");
+  if (!userId || typeof userId !== "string")
+    throw new Error("userId must be a string");
+  if (!peerId || typeof peerId !== "string")
+    throw new Error("peerId must be a string");
+  if (_relationshipsV2.has(id))
+    throw new Error(`relationship ${id} already exists`);
+  const r = {
+    id,
+    userId,
+    peerId,
+    status: "pending",
+    createdAt: now,
+    lastSeenAt: now,
+    connectedAt: null,
+    blockedAt: null,
+    metadata: { ...metadata },
+  };
+  _relationshipsV2.set(id, r);
+  return _copyRelV2(r);
+}
+
+export function getRelationshipV2(id) {
+  const r = _relationshipsV2.get(id);
+  return r ? _copyRelV2(r) : null;
+}
+
+export function listRelationshipsV2({ userId, status } = {}) {
+  const out = [];
+  for (const r of _relationshipsV2.values()) {
+    if (userId && r.userId !== userId) continue;
+    if (status && r.status !== status) continue;
+    out.push(_copyRelV2(r));
+  }
+  return out;
+}
+
+export function setRelationshipStatusV2(id, next, { now = Date.now() } = {}) {
+  const r = _relationshipsV2.get(id);
+  if (!r) throw new Error(`relationship ${id} not found`);
+  if (!REL_TRANSITIONS_V2.has(next))
+    throw new Error(`unknown relationship status: ${next}`);
+  if (REL_TERMINALS_V2.has(r.status))
+    throw new Error(`relationship ${id} is in terminal state ${r.status}`);
+  const allowed = REL_TRANSITIONS_V2.get(r.status);
+  if (!allowed.has(next))
+    throw new Error(
+      `cannot transition relationship from ${r.status} to ${next}`,
+    );
+  if (next === "connected") {
+    if (r.status === "pending") {
+      const count = getConnectedCountV2(r.userId);
+      if (count >= _maxConnectedPerUserV2)
+        throw new Error(
+          `user ${r.userId} already at connected cap (${_maxConnectedPerUserV2})`,
+        );
+    }
+    if (!r.connectedAt) r.connectedAt = now;
+  }
+  if (next === "blocked" && !r.blockedAt) r.blockedAt = now;
+  r.status = next;
+  r.lastSeenAt = now;
+  return _copyRelV2(r);
+}
+
+export function connectRelationshipV2(id, opts) {
+  return setRelationshipStatusV2(id, "connected", opts);
+}
+export function muteRelationshipV2(id, opts) {
+  return setRelationshipStatusV2(id, "muted", opts);
+}
+export function blockRelationshipV2(id, opts) {
+  return setRelationshipStatusV2(id, "blocked", opts);
+}
+
+export function touchRelationshipV2(id, { now = Date.now() } = {}) {
+  const r = _relationshipsV2.get(id);
+  if (!r) throw new Error(`relationship ${id} not found`);
+  r.lastSeenAt = now;
+  return _copyRelV2(r);
+}
+
+export function createThreadV2(
+  id,
+  { userId, topic, metadata = {}, now = Date.now() } = {},
+) {
+  if (!id || typeof id !== "string") throw new Error("id must be a string");
+  if (!userId || typeof userId !== "string")
+    throw new Error("userId must be a string");
+  if (!topic || typeof topic !== "string")
+    throw new Error("topic must be a string");
+  if (_threadsV2.has(id)) throw new Error(`thread ${id} already exists`);
+  const count = getOpenThreadCountV2(userId);
+  if (count >= _maxOpenThreadsPerUserV2)
+    throw new Error(
+      `user ${userId} already at open-thread cap (${_maxOpenThreadsPerUserV2})`,
+    );
+  const t = {
+    id,
+    userId,
+    topic,
+    status: "open",
+    createdAt: now,
+    lastSeenAt: now,
+    engagedAt: null,
+    settledAt: null,
+    metadata: { ...metadata },
+  };
+  _threadsV2.set(id, t);
+  return _copyThreadV2(t);
+}
+
+export function getThreadV2(id) {
+  const t = _threadsV2.get(id);
+  return t ? _copyThreadV2(t) : null;
+}
+
+export function listThreadsV2({ userId, status } = {}) {
+  const out = [];
+  for (const t of _threadsV2.values()) {
+    if (userId && t.userId !== userId) continue;
+    if (status && t.status !== status) continue;
+    out.push(_copyThreadV2(t));
+  }
+  return out;
+}
+
+export function setThreadStatusV2(id, next, { now = Date.now() } = {}) {
+  const t = _threadsV2.get(id);
+  if (!t) throw new Error(`thread ${id} not found`);
+  if (!THREAD_TRANSITIONS_V2.has(next))
+    throw new Error(`unknown thread status: ${next}`);
+  if (THREAD_TERMINALS_V2.has(t.status))
+    throw new Error(`thread ${id} is in terminal state ${t.status}`);
+  const allowed = THREAD_TRANSITIONS_V2.get(t.status);
+  if (!allowed.has(next))
+    throw new Error(`cannot transition thread from ${t.status} to ${next}`);
+  if (next === "engaged" && !t.engagedAt) t.engagedAt = now;
+  if (THREAD_TERMINALS_V2.has(next) && !t.settledAt) t.settledAt = now;
+  t.status = next;
+  t.lastSeenAt = now;
+  return _copyThreadV2(t);
+}
+
+export function engageThreadV2(id, opts) {
+  return setThreadStatusV2(id, "engaged", opts);
+}
+export function resolveThreadV2(id, opts) {
+  return setThreadStatusV2(id, "resolved", opts);
+}
+export function abandonThreadV2(id, opts) {
+  return setThreadStatusV2(id, "abandoned", opts);
+}
+export function reportThreadV2(id, opts) {
+  return setThreadStatusV2(id, "reported", opts);
+}
+
+export function autoMuteIdleRelationshipsV2({ now = Date.now() } = {}) {
+  const flipped = [];
+  for (const r of _relationshipsV2.values()) {
+    if (r.status !== "connected") continue;
+    if (now - r.lastSeenAt > _relationshipIdleMsV2) {
+      r.status = "muted";
+      r.lastSeenAt = now;
+      flipped.push(_copyRelV2(r));
+    }
+  }
+  return flipped;
+}
+
+export function autoAbandonStuckThreadsV2({ now = Date.now() } = {}) {
+  const flipped = [];
+  for (const t of _threadsV2.values()) {
+    if (t.status !== "open" && t.status !== "engaged") continue;
+    if (now - t.lastSeenAt > _threadStuckMsV2) {
+      t.status = "abandoned";
+      t.lastSeenAt = now;
+      if (!t.settledAt) t.settledAt = now;
+      flipped.push(_copyThreadV2(t));
+    }
+  }
+  return flipped;
+}
+
+export function getSocialManagerStatsV2() {
+  const relationshipsByStatus = {};
+  for (const v of Object.values(RELATIONSHIP_MATURITY_V2))
+    relationshipsByStatus[v] = 0;
+  for (const r of _relationshipsV2.values())
+    relationshipsByStatus[r.status] += 1;
+
+  const threadsByStatus = {};
+  for (const v of Object.values(THREAD_LIFECYCLE_V2)) threadsByStatus[v] = 0;
+  for (const t of _threadsV2.values()) threadsByStatus[t.status] += 1;
+
+  return {
+    totalRelationshipsV2: _relationshipsV2.size,
+    totalThreadsV2: _threadsV2.size,
+    maxConnectedPerUser: _maxConnectedPerUserV2,
+    maxOpenThreadsPerUser: _maxOpenThreadsPerUserV2,
+    relationshipIdleMs: _relationshipIdleMsV2,
+    threadStuckMs: _threadStuckMsV2,
+    relationshipsByStatus,
+    threadsByStatus,
+  };
+}
+
+export function _resetStateSocialManagerV2() {
+  _relationshipsV2.clear();
+  _threadsV2.clear();
+  _maxConnectedPerUserV2 = SOCIAL_DEFAULT_MAX_CONNECTED_PER_USER;
+  _maxOpenThreadsPerUserV2 = SOCIAL_DEFAULT_MAX_OPEN_THREADS_PER_USER;
+  _relationshipIdleMsV2 = SOCIAL_DEFAULT_RELATIONSHIP_IDLE_MS;
+  _threadStuckMsV2 = SOCIAL_DEFAULT_THREAD_STUCK_MS;
+}