chainlesschain 0.132.0 → 0.145.0

package/src/lib/activitypub-bridge.js

@@ -621,3 +621,346 @@ export function _resetState() {
 }
 
 export const _constants = { PUBLIC_AUDIENCE, CONTEXT, DEFAULT_ORIGIN };
+
+// ===== V2 Surface: ActivityPub Bridge governance overlay (CLI v0.135.0) =====
+export const AP_ACTOR_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  SUSPENDED: "suspended",
+  DEACTIVATED: "deactivated",
+});
+export const AP_ACTIVITY_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  DELIVERING: "delivering",
+  DELIVERED: "delivered",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const _apActorTrans = new Map([
+  [
+    AP_ACTOR_MATURITY_V2.PENDING,
+    new Set([AP_ACTOR_MATURITY_V2.ACTIVE, AP_ACTOR_MATURITY_V2.DEACTIVATED]),
+  ],
+  [
+    AP_ACTOR_MATURITY_V2.ACTIVE,
+    new Set([AP_ACTOR_MATURITY_V2.SUSPENDED, AP_ACTOR_MATURITY_V2.DEACTIVATED]),
+  ],
+  [
+    AP_ACTOR_MATURITY_V2.SUSPENDED,
+    new Set([AP_ACTOR_MATURITY_V2.ACTIVE, AP_ACTOR_MATURITY_V2.DEACTIVATED]),
+  ],
+  [AP_ACTOR_MATURITY_V2.DEACTIVATED, new Set()],
+]);
+const _apActorTerminal = new Set([AP_ACTOR_MATURITY_V2.DEACTIVATED]);
+const _apActTrans = new Map([
+  [
+    AP_ACTIVITY_LIFECYCLE_V2.QUEUED,
+    new Set([
+      AP_ACTIVITY_LIFECYCLE_V2.DELIVERING,
+      AP_ACTIVITY_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [
+    AP_ACTIVITY_LIFECYCLE_V2.DELIVERING,
+    new Set([
+      AP_ACTIVITY_LIFECYCLE_V2.DELIVERED,
+      AP_ACTIVITY_LIFECYCLE_V2.FAILED,
+      AP_ACTIVITY_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [AP_ACTIVITY_LIFECYCLE_V2.DELIVERED, new Set()],
+  [AP_ACTIVITY_LIFECYCLE_V2.FAILED, new Set()],
+  [AP_ACTIVITY_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _apActors = new Map();
+const _apActs = new Map();
+let _apMaxActivePerOwner = 15;
+let _apMaxPendingPerActor = 25;
+let _apActorIdleMs = 24 * 60 * 60 * 1000;
+let _apActStuckMs = 3 * 60 * 1000;
+
+function _apPos(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 setMaxActiveApActorsPerOwnerV2(n) {
+  _apMaxActivePerOwner = _apPos(n, "maxActiveApActorsPerOwner");
+}
+export function getMaxActiveApActorsPerOwnerV2() {
+  return _apMaxActivePerOwner;
+}
+export function setMaxPendingApActivitiesPerActorV2(n) {
+  _apMaxPendingPerActor = _apPos(n, "maxPendingApActivitiesPerActor");
+}
+export function getMaxPendingApActivitiesPerActorV2() {
+  return _apMaxPendingPerActor;
+}
+export function setApActorIdleMsV2(n) {
+  _apActorIdleMs = _apPos(n, "apActorIdleMs");
+}
+export function getApActorIdleMsV2() {
+  return _apActorIdleMs;
+}
+export function setApActivityStuckMsV2(n) {
+  _apActStuckMs = _apPos(n, "apActivityStuckMs");
+}
+export function getApActivityStuckMsV2() {
+  return _apActStuckMs;
+}
+
+export function _resetStateActivityPubBridgeV2() {
+  _apActors.clear();
+  _apActs.clear();
+  _apMaxActivePerOwner = 15;
+  _apMaxPendingPerActor = 25;
+  _apActorIdleMs = 24 * 60 * 60 * 1000;
+  _apActStuckMs = 3 * 60 * 1000;
+}
+
+export function registerApActorV2({ id, owner, handle, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!owner || typeof owner !== "string") throw new Error("owner is required");
+  if (_apActors.has(id))
+    throw new Error(`activitypub actor ${id} already registered`);
+  const now = Date.now();
+  const a = {
+    id,
+    owner,
+    handle: handle || id,
+    status: AP_ACTOR_MATURITY_V2.PENDING,
+    createdAt: now,
+    updatedAt: now,
+    activatedAt: null,
+    deactivatedAt: null,
+    lastTouchedAt: now,
+    metadata: { ...(metadata || {}) },
+  };
+  _apActors.set(id, a);
+  return { ...a, metadata: { ...a.metadata } };
+}
+function _apCheckA(from, to) {
+  const al = _apActorTrans.get(from);
+  if (!al || !al.has(to))
+    throw new Error(`invalid activitypub actor transition ${from} → ${to}`);
+}
+function _apCountActive(owner) {
+  let n = 0;
+  for (const a of _apActors.values())
+    if (a.owner === owner && a.status === AP_ACTOR_MATURITY_V2.ACTIVE) n++;
+  return n;
+}
+
+export function activateApActorV2(id) {
+  const a = _apActors.get(id);
+  if (!a) throw new Error(`activitypub actor ${id} not found`);
+  _apCheckA(a.status, AP_ACTOR_MATURITY_V2.ACTIVE);
+  const recovery = a.status === AP_ACTOR_MATURITY_V2.SUSPENDED;
+  if (!recovery) {
+    const c = _apCountActive(a.owner);
+    if (c >= _apMaxActivePerOwner)
+      throw new Error(
+        `max active activitypub actors per owner (${_apMaxActivePerOwner}) reached for ${a.owner}`,
+      );
+  }
+  const now = Date.now();
+  a.status = AP_ACTOR_MATURITY_V2.ACTIVE;
+  a.updatedAt = now;
+  a.lastTouchedAt = now;
+  if (!a.activatedAt) a.activatedAt = now;
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function suspendApActorV2(id) {
+  const a = _apActors.get(id);
+  if (!a) throw new Error(`activitypub actor ${id} not found`);
+  _apCheckA(a.status, AP_ACTOR_MATURITY_V2.SUSPENDED);
+  a.status = AP_ACTOR_MATURITY_V2.SUSPENDED;
+  a.updatedAt = Date.now();
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function deactivateApActorV2(id) {
+  const a = _apActors.get(id);
+  if (!a) throw new Error(`activitypub actor ${id} not found`);
+  _apCheckA(a.status, AP_ACTOR_MATURITY_V2.DEACTIVATED);
+  const now = Date.now();
+  a.status = AP_ACTOR_MATURITY_V2.DEACTIVATED;
+  a.updatedAt = now;
+  if (!a.deactivatedAt) a.deactivatedAt = now;
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function touchApActorV2(id) {
+  const a = _apActors.get(id);
+  if (!a) throw new Error(`activitypub actor ${id} not found`);
+  if (_apActorTerminal.has(a.status))
+    throw new Error(`cannot touch terminal activitypub actor ${id}`);
+  const now = Date.now();
+  a.lastTouchedAt = now;
+  a.updatedAt = now;
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function getApActorV2(id) {
+  const a = _apActors.get(id);
+  if (!a) return null;
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function listApActorsV2() {
+  return [..._apActors.values()].map((a) => ({
+    ...a,
+    metadata: { ...a.metadata },
+  }));
+}
+
+function _apCountPending(aid) {
+  let n = 0;
+  for (const ac of _apActs.values())
+    if (
+      ac.actorId === aid &&
+      (ac.status === AP_ACTIVITY_LIFECYCLE_V2.QUEUED ||
+        ac.status === AP_ACTIVITY_LIFECYCLE_V2.DELIVERING)
+    )
+      n++;
+  return n;
+}
+
+export function createApActivityV2({ id, actorId, kind, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!actorId || typeof actorId !== "string")
+    throw new Error("actorId is required");
+  if (_apActs.has(id))
+    throw new Error(`activitypub activity ${id} already exists`);
+  if (!_apActors.has(actorId))
+    throw new Error(`activitypub actor ${actorId} not found`);
+  const pending = _apCountPending(actorId);
+  if (pending >= _apMaxPendingPerActor)
+    throw new Error(
+      `max pending activitypub activities per actor (${_apMaxPendingPerActor}) reached for ${actorId}`,
+    );
+  const now = Date.now();
+  const ac = {
+    id,
+    actorId,
+    kind: kind || "Note",
+    status: AP_ACTIVITY_LIFECYCLE_V2.QUEUED,
+    createdAt: now,
+    updatedAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: { ...(metadata || {}) },
+  };
+  _apActs.set(id, ac);
+  return { ...ac, metadata: { ...ac.metadata } };
+}
+function _apCheckAct(from, to) {
+  const al = _apActTrans.get(from);
+  if (!al || !al.has(to))
+    throw new Error(`invalid activitypub activity transition ${from} → ${to}`);
+}
+export function startApActivityV2(id) {
+  const ac = _apActs.get(id);
+  if (!ac) throw new Error(`activitypub activity ${id} not found`);
+  _apCheckAct(ac.status, AP_ACTIVITY_LIFECYCLE_V2.DELIVERING);
+  const now = Date.now();
+  ac.status = AP_ACTIVITY_LIFECYCLE_V2.DELIVERING;
+  ac.updatedAt = now;
+  if (!ac.startedAt) ac.startedAt = now;
+  return { ...ac, metadata: { ...ac.metadata } };
+}
+export function deliverApActivityV2(id) {
+  const ac = _apActs.get(id);
+  if (!ac) throw new Error(`activitypub activity ${id} not found`);
+  _apCheckAct(ac.status, AP_ACTIVITY_LIFECYCLE_V2.DELIVERED);
+  const now = Date.now();
+  ac.status = AP_ACTIVITY_LIFECYCLE_V2.DELIVERED;
+  ac.updatedAt = now;
+  if (!ac.settledAt) ac.settledAt = now;
+  return { ...ac, metadata: { ...ac.metadata } };
+}
+export function failApActivityV2(id, reason) {
+  const ac = _apActs.get(id);
+  if (!ac) throw new Error(`activitypub activity ${id} not found`);
+  _apCheckAct(ac.status, AP_ACTIVITY_LIFECYCLE_V2.FAILED);
+  const now = Date.now();
+  ac.status = AP_ACTIVITY_LIFECYCLE_V2.FAILED;
+  ac.updatedAt = now;
+  if (!ac.settledAt) ac.settledAt = now;
+  if (reason) ac.metadata.failReason = String(reason);
+  return { ...ac, metadata: { ...ac.metadata } };
+}
+export function cancelApActivityV2(id, reason) {
+  const ac = _apActs.get(id);
+  if (!ac) throw new Error(`activitypub activity ${id} not found`);
+  _apCheckAct(ac.status, AP_ACTIVITY_LIFECYCLE_V2.CANCELLED);
+  const now = Date.now();
+  ac.status = AP_ACTIVITY_LIFECYCLE_V2.CANCELLED;
+  ac.updatedAt = now;
+  if (!ac.settledAt) ac.settledAt = now;
+  if (reason) ac.metadata.cancelReason = String(reason);
+  return { ...ac, metadata: { ...ac.metadata } };
+}
+export function getApActivityV2(id) {
+  const ac = _apActs.get(id);
+  if (!ac) return null;
+  return { ...ac, metadata: { ...ac.metadata } };
+}
+export function listApActivitiesV2() {
+  return [..._apActs.values()].map((ac) => ({
+    ...ac,
+    metadata: { ...ac.metadata },
+  }));
+}
+
+export function autoSuspendIdleApActorsV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const a of _apActors.values())
+    if (
+      a.status === AP_ACTOR_MATURITY_V2.ACTIVE &&
+      t - a.lastTouchedAt >= _apActorIdleMs
+    ) {
+      a.status = AP_ACTOR_MATURITY_V2.SUSPENDED;
+      a.updatedAt = t;
+      flipped.push(a.id);
+    }
+  return { flipped, count: flipped.length };
+}
+export function autoFailStuckApActivitiesV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const ac of _apActs.values())
+    if (
+      ac.status === AP_ACTIVITY_LIFECYCLE_V2.DELIVERING &&
+      ac.startedAt != null &&
+      t - ac.startedAt >= _apActStuckMs
+    ) {
+      ac.status = AP_ACTIVITY_LIFECYCLE_V2.FAILED;
+      ac.updatedAt = t;
+      if (!ac.settledAt) ac.settledAt = t;
+      ac.metadata.failReason = "auto-fail-stuck";
+      flipped.push(ac.id);
+    }
+  return { flipped, count: flipped.length };
+}
+
+export function getActivityPubBridgeStatsV2() {
+  const actorsByStatus = {};
+  for (const s of Object.values(AP_ACTOR_MATURITY_V2)) actorsByStatus[s] = 0;
+  for (const a of _apActors.values()) actorsByStatus[a.status]++;
+  const activitiesByStatus = {};
+  for (const s of Object.values(AP_ACTIVITY_LIFECYCLE_V2))
+    activitiesByStatus[s] = 0;
+  for (const ac of _apActs.values()) activitiesByStatus[ac.status]++;
+  return {
+    totalActorsV2: _apActors.size,
+    totalActivitiesV2: _apActs.size,
+    maxActiveApActorsPerOwner: _apMaxActivePerOwner,
+    maxPendingApActivitiesPerActor: _apMaxPendingPerActor,
+    apActorIdleMs: _apActorIdleMs,
+    apActivityStuckMs: _apActStuckMs,
+    actorsByStatus,
+    activitiesByStatus,
+  };
+}

package/src/lib/agent-economy.js

@@ -846,3 +846,361 @@ export function _resetV2State() {
   _v2TaskContributions.clear();
   _v2Distributions.length = 0;
 }
+
+// ===== V2 Surface: Agent Economy governance overlay (CLI v0.137.0) =====
+export const ECONOMY_ACCOUNT_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  FROZEN: "frozen",
+  CLOSED: "closed",
+});
+export const ECONOMY_TX_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  PROCESSING: "processing",
+  SETTLED: "settled",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const _econAcctTrans = new Map([
+  [
+    ECONOMY_ACCOUNT_MATURITY_V2.PENDING,
+    new Set([
+      ECONOMY_ACCOUNT_MATURITY_V2.ACTIVE,
+      ECONOMY_ACCOUNT_MATURITY_V2.CLOSED,
+    ]),
+  ],
+  [
+    ECONOMY_ACCOUNT_MATURITY_V2.ACTIVE,
+    new Set([
+      ECONOMY_ACCOUNT_MATURITY_V2.FROZEN,
+      ECONOMY_ACCOUNT_MATURITY_V2.CLOSED,
+    ]),
+  ],
+  [
+    ECONOMY_ACCOUNT_MATURITY_V2.FROZEN,
+    new Set([
+      ECONOMY_ACCOUNT_MATURITY_V2.ACTIVE,
+      ECONOMY_ACCOUNT_MATURITY_V2.CLOSED,
+    ]),
+  ],
+  [ECONOMY_ACCOUNT_MATURITY_V2.CLOSED, new Set()],
+]);
+const _econAcctTerminal = new Set([ECONOMY_ACCOUNT_MATURITY_V2.CLOSED]);
+const _econTxTrans = new Map([
+  [
+    ECONOMY_TX_LIFECYCLE_V2.QUEUED,
+    new Set([
+      ECONOMY_TX_LIFECYCLE_V2.PROCESSING,
+      ECONOMY_TX_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [
+    ECONOMY_TX_LIFECYCLE_V2.PROCESSING,
+    new Set([
+      ECONOMY_TX_LIFECYCLE_V2.SETTLED,
+      ECONOMY_TX_LIFECYCLE_V2.FAILED,
+      ECONOMY_TX_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+  [ECONOMY_TX_LIFECYCLE_V2.SETTLED, new Set()],
+  [ECONOMY_TX_LIFECYCLE_V2.FAILED, new Set()],
+  [ECONOMY_TX_LIFECYCLE_V2.CANCELLED, new Set()],
+]);
+
+const _econAccts = new Map();
+const _econTxs = new Map();
+let _econMaxActivePerHolder = 20;
+let _econMaxPendingPerAcct = 30;
+let _econAcctIdleMs = 7 * 24 * 60 * 60 * 1000;
+let _econTxStuckMs = 5 * 60 * 1000;
+
+function _econPos(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 setMaxActiveEconomyAccountsPerHolderV2(n) {
+  _econMaxActivePerHolder = _econPos(n, "maxActiveEconomyAccountsPerHolder");
+}
+export function getMaxActiveEconomyAccountsPerHolderV2() {
+  return _econMaxActivePerHolder;
+}
+export function setMaxPendingEconomyTxsPerAccountV2(n) {
+  _econMaxPendingPerAcct = _econPos(n, "maxPendingEconomyTxsPerAccount");
+}
+export function getMaxPendingEconomyTxsPerAccountV2() {
+  return _econMaxPendingPerAcct;
+}
+export function setEconomyAccountIdleMsV2(n) {
+  _econAcctIdleMs = _econPos(n, "economyAccountIdleMs");
+}
+export function getEconomyAccountIdleMsV2() {
+  return _econAcctIdleMs;
+}
+export function setEconomyTxStuckMsV2(n) {
+  _econTxStuckMs = _econPos(n, "economyTxStuckMs");
+}
+export function getEconomyTxStuckMsV2() {
+  return _econTxStuckMs;
+}
+
+export function _resetStateAgentEconomyV2() {
+  _econAccts.clear();
+  _econTxs.clear();
+  _econMaxActivePerHolder = 20;
+  _econMaxPendingPerAcct = 30;
+  _econAcctIdleMs = 7 * 24 * 60 * 60 * 1000;
+  _econTxStuckMs = 5 * 60 * 1000;
+}
+
+export function registerEconomyAccountV2({
+  id,
+  holder,
+  currency,
+  metadata,
+} = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!holder || typeof holder !== "string")
+    throw new Error("holder is required");
+  if (_econAccts.has(id))
+    throw new Error(`economy account ${id} already registered`);
+  const now = Date.now();
+  const a = {
+    id,
+    holder,
+    currency: currency || "CLC",
+    status: ECONOMY_ACCOUNT_MATURITY_V2.PENDING,
+    createdAt: now,
+    updatedAt: now,
+    activatedAt: null,
+    closedAt: null,
+    lastTouchedAt: now,
+    metadata: { ...(metadata || {}) },
+  };
+  _econAccts.set(id, a);
+  return { ...a, metadata: { ...a.metadata } };
+}
+function _econCheckA(from, to) {
+  const a = _econAcctTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid economy account transition ${from} → ${to}`);
+}
+function _econCountActive(holder) {
+  let n = 0;
+  for (const a of _econAccts.values())
+    if (a.holder === holder && a.status === ECONOMY_ACCOUNT_MATURITY_V2.ACTIVE)
+      n++;
+  return n;
+}
+
+export function activateEconomyAccountV2(id) {
+  const a = _econAccts.get(id);
+  if (!a) throw new Error(`economy account ${id} not found`);
+  _econCheckA(a.status, ECONOMY_ACCOUNT_MATURITY_V2.ACTIVE);
+  const recovery = a.status === ECONOMY_ACCOUNT_MATURITY_V2.FROZEN;
+  if (!recovery) {
+    const c = _econCountActive(a.holder);
+    if (c >= _econMaxActivePerHolder)
+      throw new Error(
+        `max active economy accounts per holder (${_econMaxActivePerHolder}) reached for ${a.holder}`,
+      );
+  }
+  const now = Date.now();
+  a.status = ECONOMY_ACCOUNT_MATURITY_V2.ACTIVE;
+  a.updatedAt = now;
+  a.lastTouchedAt = now;
+  if (!a.activatedAt) a.activatedAt = now;
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function freezeEconomyAccountV2(id) {
+  const a = _econAccts.get(id);
+  if (!a) throw new Error(`economy account ${id} not found`);
+  _econCheckA(a.status, ECONOMY_ACCOUNT_MATURITY_V2.FROZEN);
+  a.status = ECONOMY_ACCOUNT_MATURITY_V2.FROZEN;
+  a.updatedAt = Date.now();
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function closeEconomyAccountV2(id) {
+  const a = _econAccts.get(id);
+  if (!a) throw new Error(`economy account ${id} not found`);
+  _econCheckA(a.status, ECONOMY_ACCOUNT_MATURITY_V2.CLOSED);
+  const now = Date.now();
+  a.status = ECONOMY_ACCOUNT_MATURITY_V2.CLOSED;
+  a.updatedAt = now;
+  if (!a.closedAt) a.closedAt = now;
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function touchEconomyAccountV2(id) {
+  const a = _econAccts.get(id);
+  if (!a) throw new Error(`economy account ${id} not found`);
+  if (_econAcctTerminal.has(a.status))
+    throw new Error(`cannot touch terminal economy account ${id}`);
+  const now = Date.now();
+  a.lastTouchedAt = now;
+  a.updatedAt = now;
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function getEconomyAccountV2(id) {
+  const a = _econAccts.get(id);
+  if (!a) return null;
+  return { ...a, metadata: { ...a.metadata } };
+}
+export function listEconomyAccountsV2() {
+  return [..._econAccts.values()].map((a) => ({
+    ...a,
+    metadata: { ...a.metadata },
+  }));
+}
+
+function _econCountPending(aid) {
+  let n = 0;
+  for (const t of _econTxs.values())
+    if (
+      t.accountId === aid &&
+      (t.status === ECONOMY_TX_LIFECYCLE_V2.QUEUED ||
+        t.status === ECONOMY_TX_LIFECYCLE_V2.PROCESSING)
+    )
+      n++;
+  return n;
+}
+
+export function createEconomyTxV2({ id, accountId, amount, metadata } = {}) {
+  if (!id || typeof id !== "string") throw new Error("id is required");
+  if (!accountId || typeof accountId !== "string")
+    throw new Error("accountId is required");
+  if (_econTxs.has(id)) throw new Error(`economy tx ${id} already exists`);
+  if (!_econAccts.has(accountId))
+    throw new Error(`economy account ${accountId} not found`);
+  const pending = _econCountPending(accountId);
+  if (pending >= _econMaxPendingPerAcct)
+    throw new Error(
+      `max pending economy txs per account (${_econMaxPendingPerAcct}) reached for ${accountId}`,
+    );
+  const now = Date.now();
+  const t = {
+    id,
+    accountId,
+    amount: amount || "0",
+    status: ECONOMY_TX_LIFECYCLE_V2.QUEUED,
+    createdAt: now,
+    updatedAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: { ...(metadata || {}) },
+  };
+  _econTxs.set(id, t);
+  return { ...t, metadata: { ...t.metadata } };
+}
+function _econCheckT(from, to) {
+  const a = _econTxTrans.get(from);
+  if (!a || !a.has(to))
+    throw new Error(`invalid economy tx transition ${from} → ${to}`);
+}
+export function startEconomyTxV2(id) {
+  const t = _econTxs.get(id);
+  if (!t) throw new Error(`economy tx ${id} not found`);
+  _econCheckT(t.status, ECONOMY_TX_LIFECYCLE_V2.PROCESSING);
+  const now = Date.now();
+  t.status = ECONOMY_TX_LIFECYCLE_V2.PROCESSING;
+  t.updatedAt = now;
+  if (!t.startedAt) t.startedAt = now;
+  return { ...t, metadata: { ...t.metadata } };
+}
+export function settleEconomyTxV2(id) {
+  const t = _econTxs.get(id);
+  if (!t) throw new Error(`economy tx ${id} not found`);
+  _econCheckT(t.status, ECONOMY_TX_LIFECYCLE_V2.SETTLED);
+  const now = Date.now();
+  t.status = ECONOMY_TX_LIFECYCLE_V2.SETTLED;
+  t.updatedAt = now;
+  if (!t.settledAt) t.settledAt = now;
+  return { ...t, metadata: { ...t.metadata } };
+}
+export function failEconomyTxV2(id, reason) {
+  const t = _econTxs.get(id);
+  if (!t) throw new Error(`economy tx ${id} not found`);
+  _econCheckT(t.status, ECONOMY_TX_LIFECYCLE_V2.FAILED);
+  const now = Date.now();
+  t.status = ECONOMY_TX_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 cancelEconomyTxV2(id, reason) {
+  const t = _econTxs.get(id);
+  if (!t) throw new Error(`economy tx ${id} not found`);
+  _econCheckT(t.status, ECONOMY_TX_LIFECYCLE_V2.CANCELLED);
+  const now = Date.now();
+  t.status = ECONOMY_TX_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 getEconomyTxV2(id) {
+  const t = _econTxs.get(id);
+  if (!t) return null;
+  return { ...t, metadata: { ...t.metadata } };
+}
+export function listEconomyTxsV2() {
+  return [..._econTxs.values()].map((t) => ({
+    ...t,
+    metadata: { ...t.metadata },
+  }));
+}
+
+export function autoFreezeIdleEconomyAccountsV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const a of _econAccts.values())
+    if (
+      a.status === ECONOMY_ACCOUNT_MATURITY_V2.ACTIVE &&
+      t - a.lastTouchedAt >= _econAcctIdleMs
+    ) {
+      a.status = ECONOMY_ACCOUNT_MATURITY_V2.FROZEN;
+      a.updatedAt = t;
+      flipped.push(a.id);
+    }
+  return { flipped, count: flipped.length };
+}
+export function autoFailStuckEconomyTxsV2({ now } = {}) {
+  const t = now ?? Date.now();
+  const flipped = [];
+  for (const tx of _econTxs.values())
+    if (
+      tx.status === ECONOMY_TX_LIFECYCLE_V2.PROCESSING &&
+      tx.startedAt != null &&
+      t - tx.startedAt >= _econTxStuckMs
+    ) {
+      tx.status = ECONOMY_TX_LIFECYCLE_V2.FAILED;
+      tx.updatedAt = t;
+      if (!tx.settledAt) tx.settledAt = t;
+      tx.metadata.failReason = "auto-fail-stuck";
+      flipped.push(tx.id);
+    }
+  return { flipped, count: flipped.length };
+}
+
+export function getAgentEconomyGovStatsV2() {
+  const accountsByStatus = {};
+  for (const s of Object.values(ECONOMY_ACCOUNT_MATURITY_V2))
+    accountsByStatus[s] = 0;
+  for (const a of _econAccts.values()) accountsByStatus[a.status]++;
+  const txsByStatus = {};
+  for (const s of Object.values(ECONOMY_TX_LIFECYCLE_V2)) txsByStatus[s] = 0;
+  for (const t of _econTxs.values()) txsByStatus[t.status]++;
+  return {
+    totalAccountsV2: _econAccts.size,
+    totalTxsV2: _econTxs.size,
+    maxActiveEconomyAccountsPerHolder: _econMaxActivePerHolder,
+    maxPendingEconomyTxsPerAccount: _econMaxPendingPerAcct,
+    economyAccountIdleMs: _econAcctIdleMs,
+    economyTxStuckMs: _econTxStuckMs,
+    accountsByStatus,
+    txsByStatus,
+  };
+}