chainlesschain 0.81.0 → 0.143.0

package/src/lib/decentral-infra.js

@@ -443,3 +443,343 @@ export function _resetState() {
   _versions.clear();
   _routes.clear();
 }
+
+/* ═════════════════════════════════════════════════════════ *
+ *  Phase 74-75 V2 — Provider Maturity + Deal Lifecycle
+ * ═════════════════════════════════════════════════════════ */
+
+export const PROVIDER_MATURITY_V2 = Object.freeze({
+  ONBOARDING: "onboarding",
+  ACTIVE: "active",
+  DEGRADED: "degraded",
+  OFFLINE: "offline",
+  RETIRED: "retired",
+});
+
+export const DEAL_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  ACTIVE: "active",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELED: "canceled",
+});
+
+const PROVIDER_TRANSITIONS_V2 = new Map([
+  ["onboarding", new Set(["active", "retired"])],
+  ["active", new Set(["degraded", "offline", "retired"])],
+  ["degraded", new Set(["active", "offline", "retired"])],
+  ["offline", new Set(["active", "retired"])],
+]);
+const PROVIDER_TERMINALS_V2 = new Set(["retired"]);
+
+const DEAL_TRANSITIONS_V2 = new Map([
+  ["queued", new Set(["active", "canceled", "failed"])],
+  ["active", new Set(["completed", "failed", "canceled"])],
+]);
+const DEAL_TERMINALS_V2 = new Set(["completed", "failed", "canceled"]);
+
+export const DI_DEFAULT_MAX_ACTIVE_PROVIDERS_PER_OPERATOR = 20;
+export const DI_DEFAULT_MAX_ACTIVE_DEALS_PER_PROVIDER = 10;
+export const DI_DEFAULT_PROVIDER_IDLE_MS = 7 * 86400000; // 7 days
+export const DI_DEFAULT_DEAL_STUCK_MS = 24 * 3600000; // 24 hours
+
+let _maxActiveProvidersPerOperatorV2 =
+  DI_DEFAULT_MAX_ACTIVE_PROVIDERS_PER_OPERATOR;
+let _maxActiveDealsPerProviderV2 = DI_DEFAULT_MAX_ACTIVE_DEALS_PER_PROVIDER;
+let _providerIdleMsV2 = DI_DEFAULT_PROVIDER_IDLE_MS;
+let _dealStuckMsV2 = DI_DEFAULT_DEAL_STUCK_MS;
+
+function _positiveIntV2(n, label) {
+  const v = Math.floor(Number(n));
+  if (!Number.isFinite(v) || v <= 0)
+    throw new Error(`${label} must be a positive integer`);
+  return v;
+}
+
+export function getDefaultMaxActiveProvidersPerOperatorV2() {
+  return DI_DEFAULT_MAX_ACTIVE_PROVIDERS_PER_OPERATOR;
+}
+export function getMaxActiveProvidersPerOperatorV2() {
+  return _maxActiveProvidersPerOperatorV2;
+}
+export function setMaxActiveProvidersPerOperatorV2(n) {
+  return (_maxActiveProvidersPerOperatorV2 = _positiveIntV2(
+    n,
+    "maxActiveProvidersPerOperator",
+  ));
+}
+export function getDefaultMaxActiveDealsPerProviderV2() {
+  return DI_DEFAULT_MAX_ACTIVE_DEALS_PER_PROVIDER;
+}
+export function getMaxActiveDealsPerProviderV2() {
+  return _maxActiveDealsPerProviderV2;
+}
+export function setMaxActiveDealsPerProviderV2(n) {
+  return (_maxActiveDealsPerProviderV2 = _positiveIntV2(
+    n,
+    "maxActiveDealsPerProvider",
+  ));
+}
+export function getDefaultProviderIdleMsV2() {
+  return DI_DEFAULT_PROVIDER_IDLE_MS;
+}
+export function getProviderIdleMsV2() {
+  return _providerIdleMsV2;
+}
+export function setProviderIdleMsV2(ms) {
+  return (_providerIdleMsV2 = _positiveIntV2(ms, "providerIdleMs"));
+}
+export function getDefaultDealStuckMsV2() {
+  return DI_DEFAULT_DEAL_STUCK_MS;
+}
+export function getDealStuckMsV2() {
+  return _dealStuckMsV2;
+}
+export function setDealStuckMsV2(ms) {
+  return (_dealStuckMsV2 = _positiveIntV2(ms, "dealStuckMs"));
+}
+
+const _providersV2 = new Map();
+const _dealsV2 = new Map();
+
+export function registerProviderV2(
+  _db,
+  { providerId, operatorId, kind, initialStatus, metadata } = {},
+) {
+  if (!providerId) throw new Error("providerId is required");
+  if (!operatorId) throw new Error("operatorId is required");
+  if (!kind) throw new Error("kind is required");
+  if (_providersV2.has(providerId))
+    throw new Error(`Provider ${providerId} already exists`);
+  const status = initialStatus || PROVIDER_MATURITY_V2.ONBOARDING;
+  if (!Object.values(PROVIDER_MATURITY_V2).includes(status))
+    throw new Error(`Invalid initial status: ${status}`);
+  if (PROVIDER_TERMINALS_V2.has(status))
+    throw new Error(`Cannot register in terminal status: ${status}`);
+  if (status === PROVIDER_MATURITY_V2.ACTIVE) {
+    if (getActiveProviderCount(operatorId) >= _maxActiveProvidersPerOperatorV2)
+      throw new Error(
+        `Operator ${operatorId} reached active-provider cap (${_maxActiveProvidersPerOperatorV2})`,
+      );
+  }
+  const now = Date.now();
+  const record = {
+    providerId,
+    operatorId,
+    kind,
+    status,
+    metadata: metadata || {},
+    createdAt: now,
+    updatedAt: now,
+    lastHeartbeatAt: now,
+  };
+  _providersV2.set(providerId, record);
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getProviderV2(providerId) {
+  const r = _providersV2.get(providerId);
+  return r ? { ...r, metadata: { ...r.metadata } } : null;
+}
+
+export function setProviderMaturityV2(_db, providerId, newStatus, patch = {}) {
+  const record = _providersV2.get(providerId);
+  if (!record) throw new Error(`Unknown provider: ${providerId}`);
+  if (!Object.values(PROVIDER_MATURITY_V2).includes(newStatus))
+    throw new Error(`Invalid status: ${newStatus}`);
+  const allowed = PROVIDER_TRANSITIONS_V2.get(record.status) || new Set();
+  if (!allowed.has(newStatus))
+    throw new Error(`Invalid transition: ${record.status} -> ${newStatus}`);
+  if (newStatus === PROVIDER_MATURITY_V2.ACTIVE) {
+    if (
+      getActiveProviderCount(record.operatorId) >=
+      _maxActiveProvidersPerOperatorV2
+    )
+      throw new Error(
+        `Operator ${record.operatorId} reached active-provider cap (${_maxActiveProvidersPerOperatorV2})`,
+      );
+  }
+  record.status = newStatus;
+  record.updatedAt = Date.now();
+  if (patch.reason !== undefined) record.lastReason = patch.reason;
+  if (patch.metadata)
+    record.metadata = { ...record.metadata, ...patch.metadata };
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function activateProvider(db, id, reason) {
+  return setProviderMaturityV2(db, id, PROVIDER_MATURITY_V2.ACTIVE, { reason });
+}
+export function degradeProvider(db, id, reason) {
+  return setProviderMaturityV2(db, id, PROVIDER_MATURITY_V2.DEGRADED, {
+    reason,
+  });
+}
+export function offlineProvider(db, id, reason) {
+  return setProviderMaturityV2(db, id, PROVIDER_MATURITY_V2.OFFLINE, {
+    reason,
+  });
+}
+export function retireProvider(db, id, reason) {
+  return setProviderMaturityV2(db, id, PROVIDER_MATURITY_V2.RETIRED, {
+    reason,
+  });
+}
+
+export function touchProviderHeartbeat(providerId) {
+  const record = _providersV2.get(providerId);
+  if (!record) throw new Error(`Unknown provider: ${providerId}`);
+  record.lastHeartbeatAt = Date.now();
+  record.updatedAt = record.lastHeartbeatAt;
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function enqueueDealV2(
+  _db,
+  { dealId, providerId, ownerId, metadata } = {},
+) {
+  if (!dealId) throw new Error("dealId is required");
+  if (!providerId) throw new Error("providerId is required");
+  if (!ownerId) throw new Error("ownerId is required");
+  if (!_providersV2.has(providerId))
+    throw new Error(`Unknown provider: ${providerId}`);
+  if (_dealsV2.has(dealId)) throw new Error(`Deal ${dealId} already exists`);
+  const now = Date.now();
+  const record = {
+    dealId,
+    providerId,
+    ownerId,
+    status: DEAL_LIFECYCLE_V2.QUEUED,
+    metadata: metadata || {},
+    createdAt: now,
+    updatedAt: now,
+  };
+  _dealsV2.set(dealId, record);
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function getDealV2(dealId) {
+  const r = _dealsV2.get(dealId);
+  return r ? { ...r, metadata: { ...r.metadata } } : null;
+}
+
+export function setDealStatusV2(_db, dealId, newStatus, patch = {}) {
+  const record = _dealsV2.get(dealId);
+  if (!record) throw new Error(`Unknown deal: ${dealId}`);
+  if (!Object.values(DEAL_LIFECYCLE_V2).includes(newStatus))
+    throw new Error(`Invalid status: ${newStatus}`);
+  const allowed = DEAL_TRANSITIONS_V2.get(record.status) || new Set();
+  if (!allowed.has(newStatus))
+    throw new Error(`Invalid transition: ${record.status} -> ${newStatus}`);
+  if (newStatus === DEAL_LIFECYCLE_V2.ACTIVE) {
+    if (getActiveDealCount(record.providerId) >= _maxActiveDealsPerProviderV2)
+      throw new Error(
+        `Provider ${record.providerId} reached active-deal cap (${_maxActiveDealsPerProviderV2})`,
+      );
+    if (!record.activatedAt) record.activatedAt = Date.now();
+  }
+  record.status = newStatus;
+  record.updatedAt = Date.now();
+  if (patch.reason !== undefined) record.lastReason = patch.reason;
+  if (patch.metadata)
+    record.metadata = { ...record.metadata, ...patch.metadata };
+  return { ...record, metadata: { ...record.metadata } };
+}
+
+export function activateDeal(db, id, reason) {
+  return setDealStatusV2(db, id, DEAL_LIFECYCLE_V2.ACTIVE, { reason });
+}
+export function completeDeal(db, id, reason) {
+  return setDealStatusV2(db, id, DEAL_LIFECYCLE_V2.COMPLETED, { reason });
+}
+export function failDeal(db, id, reason) {
+  return setDealStatusV2(db, id, DEAL_LIFECYCLE_V2.FAILED, { reason });
+}
+export function cancelDeal(db, id, reason) {
+  return setDealStatusV2(db, id, DEAL_LIFECYCLE_V2.CANCELED, { reason });
+}
+
+export function getActiveProviderCount(operatorId) {
+  let n = 0;
+  for (const r of _providersV2.values()) {
+    if (r.status !== PROVIDER_MATURITY_V2.ACTIVE) continue;
+    if (operatorId && r.operatorId !== operatorId) continue;
+    n++;
+  }
+  return n;
+}
+
+export function getActiveDealCount(providerId) {
+  let n = 0;
+  for (const r of _dealsV2.values()) {
+    if (r.status !== DEAL_LIFECYCLE_V2.ACTIVE) continue;
+    if (providerId && r.providerId !== providerId) continue;
+    n++;
+  }
+  return n;
+}
+
+export function autoOfflineStaleProviders(_db, nowMs) {
+  const now = nowMs ?? Date.now();
+  const flipped = [];
+  for (const r of _providersV2.values()) {
+    if (
+      r.status === PROVIDER_MATURITY_V2.ACTIVE ||
+      r.status === PROVIDER_MATURITY_V2.DEGRADED
+    ) {
+      if (now - r.lastHeartbeatAt > _providerIdleMsV2) {
+        r.status = PROVIDER_MATURITY_V2.OFFLINE;
+        r.updatedAt = now;
+        r.lastReason = "heartbeat_timeout";
+        flipped.push(r.providerId);
+      }
+    }
+  }
+  return { flipped, count: flipped.length };
+}
+
+export function autoFailStuckActiveDeals(_db, nowMs) {
+  const now = nowMs ?? Date.now();
+  const flipped = [];
+  for (const r of _dealsV2.values()) {
+    if (r.status === DEAL_LIFECYCLE_V2.ACTIVE) {
+      const anchor = r.activatedAt || r.createdAt;
+      if (now - anchor > _dealStuckMsV2) {
+        r.status = DEAL_LIFECYCLE_V2.FAILED;
+        r.updatedAt = now;
+        r.lastReason = "deal_timeout";
+        flipped.push(r.dealId);
+      }
+    }
+  }
+  return { flipped, count: flipped.length };
+}
+
+export function getDecentralInfraStatsV2() {
+  const providersByStatus = {};
+  for (const s of Object.values(PROVIDER_MATURITY_V2)) providersByStatus[s] = 0;
+  const dealsByStatus = {};
+  for (const s of Object.values(DEAL_LIFECYCLE_V2)) dealsByStatus[s] = 0;
+  for (const r of _providersV2.values()) providersByStatus[r.status]++;
+  for (const r of _dealsV2.values()) dealsByStatus[r.status]++;
+  return {
+    totalProvidersV2: _providersV2.size,
+    totalDealsV2: _dealsV2.size,
+    maxActiveProvidersPerOperator: _maxActiveProvidersPerOperatorV2,
+    maxActiveDealsPerProvider: _maxActiveDealsPerProviderV2,
+    providerIdleMs: _providerIdleMsV2,
+    dealStuckMs: _dealStuckMsV2,
+    providersByStatus,
+    dealsByStatus,
+  };
+}
+
+export function _resetStateV2() {
+  _maxActiveProvidersPerOperatorV2 =
+    DI_DEFAULT_MAX_ACTIVE_PROVIDERS_PER_OPERATOR;
+  _maxActiveDealsPerProviderV2 = DI_DEFAULT_MAX_ACTIVE_DEALS_PER_PROVIDER;
+  _providerIdleMsV2 = DI_DEFAULT_PROVIDER_IDLE_MS;
+  _dealStuckMsV2 = DI_DEFAULT_DEAL_STUCK_MS;
+  _providersV2.clear();
+  _dealsV2.clear();
+}

package/src/lib/did-manager.js

@@ -268,3 +268,370 @@ export function resolveDID(db, did) {
   if (!identity) return null;
   return JSON.parse(identity.did_document || "{}");
 }
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * V2 in-memory governance layer (independent of SQLite did_identities)
+ * ───────────────────────────────────────────────────────────────────────── */
+
+export const IDENTITY_MATURITY_V2 = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  SUSPENDED: "suspended",
+  REVOKED: "revoked",
+});
+
+export const ISSUANCE_LIFECYCLE_V2 = Object.freeze({
+  QUEUED: "queued",
+  ISSUING: "issuing",
+  ISSUED: "issued",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+const IDENTITY_TERMINAL_V2 = new Set([IDENTITY_MATURITY_V2.REVOKED]);
+const ISSUANCE_TERMINAL_V2 = new Set([
+  ISSUANCE_LIFECYCLE_V2.ISSUED,
+  ISSUANCE_LIFECYCLE_V2.FAILED,
+  ISSUANCE_LIFECYCLE_V2.CANCELLED,
+]);
+
+const IDENTITY_TRANSITIONS_V2 = new Map([
+  [
+    IDENTITY_MATURITY_V2.PENDING,
+    new Set([IDENTITY_MATURITY_V2.ACTIVE, IDENTITY_MATURITY_V2.REVOKED]),
+  ],
+  [
+    IDENTITY_MATURITY_V2.ACTIVE,
+    new Set([IDENTITY_MATURITY_V2.SUSPENDED, IDENTITY_MATURITY_V2.REVOKED]),
+  ],
+  [
+    IDENTITY_MATURITY_V2.SUSPENDED,
+    new Set([IDENTITY_MATURITY_V2.ACTIVE, IDENTITY_MATURITY_V2.REVOKED]),
+  ],
+]);
+
+const ISSUANCE_TRANSITIONS_V2 = new Map([
+  [
+    ISSUANCE_LIFECYCLE_V2.QUEUED,
+    new Set([ISSUANCE_LIFECYCLE_V2.ISSUING, ISSUANCE_LIFECYCLE_V2.CANCELLED]),
+  ],
+  [
+    ISSUANCE_LIFECYCLE_V2.ISSUING,
+    new Set([
+      ISSUANCE_LIFECYCLE_V2.ISSUED,
+      ISSUANCE_LIFECYCLE_V2.FAILED,
+      ISSUANCE_LIFECYCLE_V2.CANCELLED,
+    ]),
+  ],
+]);
+
+export const DID_DEFAULT_MAX_ACTIVE_IDENTITIES_PER_OWNER = 8;
+export const DID_DEFAULT_MAX_PENDING_ISSUANCES_PER_IDENTITY = 12;
+export const DID_DEFAULT_IDENTITY_IDLE_MS = 90 * 24 * 60 * 60 * 1000;
+export const DID_DEFAULT_ISSUANCE_STUCK_MS = 5 * 60 * 1000;
+
+let _maxActiveIdentitiesPerOwnerV2 =
+  DID_DEFAULT_MAX_ACTIVE_IDENTITIES_PER_OWNER;
+let _maxPendingIssuancesPerIdentityV2 =
+  DID_DEFAULT_MAX_PENDING_ISSUANCES_PER_IDENTITY;
+let _identityIdleMsV2 = DID_DEFAULT_IDENTITY_IDLE_MS;
+let _issuanceStuckMsV2 = DID_DEFAULT_ISSUANCE_STUCK_MS;
+
+const _identitiesV2 = new Map();
+const _issuancesV2 = new Map();
+
+function _posIntDidV2(n, label) {
+  if (typeof n !== "number" || !Number.isFinite(n) || n <= 0) {
+    throw new Error(`${label} must be a positive number`);
+  }
+  return Math.floor(n);
+}
+
+export function getMaxActiveIdentitiesPerOwnerV2() {
+  return _maxActiveIdentitiesPerOwnerV2;
+}
+export function setMaxActiveIdentitiesPerOwnerV2(n) {
+  _maxActiveIdentitiesPerOwnerV2 = _posIntDidV2(
+    n,
+    "maxActiveIdentitiesPerOwner",
+  );
+  return _maxActiveIdentitiesPerOwnerV2;
+}
+export function getMaxPendingIssuancesPerIdentityV2() {
+  return _maxPendingIssuancesPerIdentityV2;
+}
+export function setMaxPendingIssuancesPerIdentityV2(n) {
+  _maxPendingIssuancesPerIdentityV2 = _posIntDidV2(
+    n,
+    "maxPendingIssuancesPerIdentity",
+  );
+  return _maxPendingIssuancesPerIdentityV2;
+}
+export function getIdentityIdleMsV2() {
+  return _identityIdleMsV2;
+}
+export function setIdentityIdleMsV2(ms) {
+  _identityIdleMsV2 = _posIntDidV2(ms, "identityIdleMs");
+  return _identityIdleMsV2;
+}
+export function getIssuanceStuckMsV2() {
+  return _issuanceStuckMsV2;
+}
+export function setIssuanceStuckMsV2(ms) {
+  _issuanceStuckMsV2 = _posIntDidV2(ms, "issuanceStuckMs");
+  return _issuanceStuckMsV2;
+}
+
+export function getActiveIdentityCountV2(ownerId) {
+  let n = 0;
+  for (const i of _identitiesV2.values()) {
+    if (i.status !== IDENTITY_MATURITY_V2.ACTIVE) continue;
+    if (ownerId && i.ownerId !== ownerId) continue;
+    n++;
+  }
+  return n;
+}
+
+export function getPendingIssuanceCountV2(identityId) {
+  let n = 0;
+  for (const j of _issuancesV2.values()) {
+    if (
+      j.status !== ISSUANCE_LIFECYCLE_V2.QUEUED &&
+      j.status !== ISSUANCE_LIFECYCLE_V2.ISSUING
+    )
+      continue;
+    if (identityId && j.identityId !== identityId) continue;
+    n++;
+  }
+  return n;
+}
+
+function _cloneIdentityV2(i) {
+  return { ...i, metadata: { ...i.metadata } };
+}
+function _cloneIssuanceV2(j) {
+  return { ...j, metadata: { ...j.metadata } };
+}
+
+export function registerIdentityV2(
+  id,
+  { ownerId, didMethod, displayName, metadata } = {},
+) {
+  if (!id || typeof id !== "string") throw new Error("identity id required");
+  if (!ownerId || typeof ownerId !== "string")
+    throw new Error("ownerId required");
+  if (!didMethod || typeof didMethod !== "string")
+    throw new Error("didMethod required");
+  if (_identitiesV2.has(id)) throw new Error(`identity ${id} already exists`);
+  const now = Date.now();
+  const identity = {
+    id,
+    ownerId,
+    didMethod,
+    displayName: displayName || id,
+    status: IDENTITY_MATURITY_V2.PENDING,
+    createdAt: now,
+    activatedAt: null,
+    revokedAt: null,
+    lastSeenAt: now,
+    metadata: metadata ? { ...metadata } : {},
+  };
+  _identitiesV2.set(id, identity);
+  return _cloneIdentityV2(identity);
+}
+
+export function getIdentityV2(id) {
+  const i = _identitiesV2.get(id);
+  return i ? _cloneIdentityV2(i) : null;
+}
+
+export function listIdentitiesV2({ ownerId, status, didMethod } = {}) {
+  const out = [];
+  for (const i of _identitiesV2.values()) {
+    if (ownerId && i.ownerId !== ownerId) continue;
+    if (status && i.status !== status) continue;
+    if (didMethod && i.didMethod !== didMethod) continue;
+    out.push(_cloneIdentityV2(i));
+  }
+  return out;
+}
+
+export function setIdentityStatusV2(id, next) {
+  const i = _identitiesV2.get(id);
+  if (!i) throw new Error(`unknown identity ${id}`);
+  if (IDENTITY_TERMINAL_V2.has(i.status)) {
+    throw new Error(`identity ${id} is terminal (${i.status})`);
+  }
+  const allowed = IDENTITY_TRANSITIONS_V2.get(i.status);
+  if (!allowed || !allowed.has(next)) {
+    throw new Error(`invalid identity transition ${i.status} -> ${next}`);
+  }
+  if (
+    next === IDENTITY_MATURITY_V2.ACTIVE &&
+    i.status === IDENTITY_MATURITY_V2.PENDING
+  ) {
+    const owned = getActiveIdentityCountV2(i.ownerId);
+    if (owned >= _maxActiveIdentitiesPerOwnerV2) {
+      throw new Error(
+        `owner ${i.ownerId} active identity cap reached (${_maxActiveIdentitiesPerOwnerV2})`,
+      );
+    }
+  }
+  const now = Date.now();
+  i.status = next;
+  if (next === IDENTITY_MATURITY_V2.ACTIVE && !i.activatedAt)
+    i.activatedAt = now;
+  if (next === IDENTITY_MATURITY_V2.REVOKED && !i.revokedAt) i.revokedAt = now;
+  i.lastSeenAt = now;
+  return _cloneIdentityV2(i);
+}
+
+export function activateIdentityV2(id) {
+  return setIdentityStatusV2(id, IDENTITY_MATURITY_V2.ACTIVE);
+}
+export function suspendIdentityV2(id) {
+  return setIdentityStatusV2(id, IDENTITY_MATURITY_V2.SUSPENDED);
+}
+export function revokeIdentityV2(id) {
+  return setIdentityStatusV2(id, IDENTITY_MATURITY_V2.REVOKED);
+}
+
+export function touchIdentityV2(id) {
+  const i = _identitiesV2.get(id);
+  if (!i) throw new Error(`unknown identity ${id}`);
+  i.lastSeenAt = Date.now();
+  return _cloneIdentityV2(i);
+}
+
+export function createIssuanceV2(
+  id,
+  { identityId, credentialType, metadata } = {},
+) {
+  if (!id || typeof id !== "string") throw new Error("issuance id required");
+  if (!identityId || typeof identityId !== "string")
+    throw new Error("identityId required");
+  if (!credentialType || typeof credentialType !== "string")
+    throw new Error("credentialType required");
+  if (_issuancesV2.has(id)) throw new Error(`issuance ${id} already exists`);
+  if (!_identitiesV2.has(identityId))
+    throw new Error(`unknown identity ${identityId}`);
+  const pending = getPendingIssuanceCountV2(identityId);
+  if (pending >= _maxPendingIssuancesPerIdentityV2) {
+    throw new Error(
+      `identity ${identityId} pending issuance cap reached (${_maxPendingIssuancesPerIdentityV2})`,
+    );
+  }
+  const now = Date.now();
+  const job = {
+    id,
+    identityId,
+    credentialType,
+    status: ISSUANCE_LIFECYCLE_V2.QUEUED,
+    createdAt: now,
+    startedAt: null,
+    settledAt: null,
+    metadata: metadata ? { ...metadata } : {},
+  };
+  _issuancesV2.set(id, job);
+  return _cloneIssuanceV2(job);
+}
+
+export function getIssuanceV2(id) {
+  const j = _issuancesV2.get(id);
+  return j ? _cloneIssuanceV2(j) : null;
+}
+
+export function listIssuancesV2({ identityId, status } = {}) {
+  const out = [];
+  for (const j of _issuancesV2.values()) {
+    if (identityId && j.identityId !== identityId) continue;
+    if (status && j.status !== status) continue;
+    out.push(_cloneIssuanceV2(j));
+  }
+  return out;
+}
+
+export function setIssuanceStatusV2(id, next) {
+  const j = _issuancesV2.get(id);
+  if (!j) throw new Error(`unknown issuance ${id}`);
+  if (ISSUANCE_TERMINAL_V2.has(j.status)) {
+    throw new Error(`issuance ${id} is terminal (${j.status})`);
+  }
+  const allowed = ISSUANCE_TRANSITIONS_V2.get(j.status);
+  if (!allowed || !allowed.has(next)) {
+    throw new Error(`invalid issuance transition ${j.status} -> ${next}`);
+  }
+  const now = Date.now();
+  j.status = next;
+  if (next === ISSUANCE_LIFECYCLE_V2.ISSUING && !j.startedAt) j.startedAt = now;
+  if (ISSUANCE_TERMINAL_V2.has(next) && !j.settledAt) j.settledAt = now;
+  return _cloneIssuanceV2(j);
+}
+
+export function startIssuanceV2(id) {
+  return setIssuanceStatusV2(id, ISSUANCE_LIFECYCLE_V2.ISSUING);
+}
+export function completeIssuanceV2(id) {
+  return setIssuanceStatusV2(id, ISSUANCE_LIFECYCLE_V2.ISSUED);
+}
+export function failIssuanceV2(id) {
+  return setIssuanceStatusV2(id, ISSUANCE_LIFECYCLE_V2.FAILED);
+}
+export function cancelIssuanceV2(id) {
+  return setIssuanceStatusV2(id, ISSUANCE_LIFECYCLE_V2.CANCELLED);
+}
+
+export function autoSuspendIdleIdentitiesV2({ now = Date.now() } = {}) {
+  const out = [];
+  for (const i of _identitiesV2.values()) {
+    if (i.status !== IDENTITY_MATURITY_V2.ACTIVE) continue;
+    if (now - i.lastSeenAt < _identityIdleMsV2) continue;
+    i.status = IDENTITY_MATURITY_V2.SUSPENDED;
+    i.lastSeenAt = now;
+    out.push(_cloneIdentityV2(i));
+  }
+  return out;
+}
+
+export function autoFailStuckIssuancesV2({ now = Date.now() } = {}) {
+  const out = [];
+  for (const j of _issuancesV2.values()) {
+    if (j.status !== ISSUANCE_LIFECYCLE_V2.ISSUING) continue;
+    if (!j.startedAt || now - j.startedAt < _issuanceStuckMsV2) continue;
+    j.status = ISSUANCE_LIFECYCLE_V2.FAILED;
+    j.settledAt = now;
+    out.push(_cloneIssuanceV2(j));
+  }
+  return out;
+}
+
+export function getDidManagerStatsV2() {
+  const identitiesByStatus = {};
+  for (const s of Object.values(IDENTITY_MATURITY_V2))
+    identitiesByStatus[s] = 0;
+  for (const i of _identitiesV2.values()) identitiesByStatus[i.status]++;
+  const issuancesByStatus = {};
+  for (const s of Object.values(ISSUANCE_LIFECYCLE_V2))
+    issuancesByStatus[s] = 0;
+  for (const j of _issuancesV2.values()) issuancesByStatus[j.status]++;
+  return {
+    totalIdentitiesV2: _identitiesV2.size,
+    totalIssuancesV2: _issuancesV2.size,
+    maxActiveIdentitiesPerOwner: _maxActiveIdentitiesPerOwnerV2,
+    maxPendingIssuancesPerIdentity: _maxPendingIssuancesPerIdentityV2,
+    identityIdleMs: _identityIdleMsV2,
+    issuanceStuckMs: _issuanceStuckMsV2,
+    identitiesByStatus,
+    issuancesByStatus,
+  };
+}
+
+export function _resetStateDidManagerV2() {
+  _identitiesV2.clear();
+  _issuancesV2.clear();
+  _maxActiveIdentitiesPerOwnerV2 = DID_DEFAULT_MAX_ACTIVE_IDENTITIES_PER_OWNER;
+  _maxPendingIssuancesPerIdentityV2 =
+    DID_DEFAULT_MAX_PENDING_ISSUANCES_PER_IDENTITY;
+  _identityIdleMsV2 = DID_DEFAULT_IDENTITY_IDLE_MS;
+  _issuanceStuckMsV2 = DID_DEFAULT_ISSUANCE_STUCK_MS;
+}