xytara 3.1.16 → 3.2.0

package/lib/provider_registry.js

@@ -1,852 +0,0 @@
-"use strict";
-
-// Open execution-provider network (dynamic, state-backed) — the keystone that turns the
-// single-tenant env-pinned execution targets (external_execution_runtime.js) into a
-// two-sided network any provider can plug into: providers self-register their endpoint +
-// the capabilities they serve + their revenue-share; the runtime routes matching paid calls
-// to ACTIVE providers; settlement splits the money (provider cut vs platform take) and
-// records a per-provider ledger.
-//
-// Safe-by-default: a newly registered provider lands "pending" and is NOT routable until an
-// operator activates it, and a re-registration that changes the endpoint reverts an active
-// provider to pending (so a leaked registration bearer cannot silently redirect live paid
-// traffic). With an empty registry every function here is inert — zero behavior change.
-
-const crypto = require("crypto");
-const { clampTargetTimeoutMs, checkEndpointUrlShape } = require("./external_execution_policy");
-
-function normStr(value, fallback = "") {
-  const s = typeof value === "string" ? value.trim() : "";
-  return s || fallback;
-}
-function ensureObject(value) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-function normStrArray(value) {
-  return Array.isArray(value) ? [...new Set(value.map((v) => normStr(v)).filter(Boolean))] : [];
-}
-function nowIso() {
-  return new Date().toISOString();
-}
-function emptyRollup() {
-  return { routed_calls: 0, settled_calls: 0, gross_minor: 0, provider_share_minor: 0, platform_take_minor: 0, paid_out_minor: 0 };
-}
-
-function emptyHealth() {
-  return { status: "healthy", consecutive_failures: 0, last_success_at_iso: null, last_failure_at_iso: null, unhealthy_until_iso: null };
-}
-
-function emptyReputation() {
-  return { success_count: 0, failure_count: 0 };
-}
-
-// Smoothed reputation score in (0,1] for ROUTING order. Uses an optimistic prior (+2 pseudo-
-// successes): a no-history provider scores 1.0 (OPTIMISTIC cold-start — it still gets a fair
-// first shot), and a single early transient failure scores ~0.67 (recoverable), NEVER 0.0 — so
-// a provider is not permanently doomed/starved by one bad call. Bad providers still sink over time.
-// Optional recency decay for the ROUTING score only (never money, never health exclusion). A
-// factor in (0,1) fades older observations on each update so recent performance dominates — a
-// provider that regressed sinks, one that recovered rises. Default 1.0 = NO decay, i.e. exactly
-// the lifetime-count behavior. Routing-only: raw lifetime counts stay intact for display.
-function reputationDecayFactor() {
-  const n = Number(process.env.XYTARA_PROVIDER_REPUTATION_DECAY);
-  return Number.isFinite(n) && n > 0 && n < 1 ? n : 1;
-}
-
-function reputationScore(rec) {
-  const rep = (rec && rec.reputation) || emptyReputation();
-  // Prefer the recency-weighted pseudo-counts when present; fall back to raw lifetime counts for a
-  // no-history or pre-decay provider. With the default factor 1.0 the two are identical. Same
-  // optimistic +2 prior either way (a new provider still scores 1.0 and gets a fair first shot).
-  const success = Number.isFinite(Number(rep.decayed_success)) ? Number(rep.decayed_success) : (Number(rep.success_count) || 0);
-  const failure = Number.isFinite(Number(rep.decayed_failure)) ? Number(rep.decayed_failure) : (Number(rep.failure_count) || 0);
-  return (success + 2) / (success + failure + 2);
-}
-
-function reputationView(rec) {
-  const rep = { ...emptyReputation(), ...((rec && rec.reputation) || {}) };
-  const success = Number(rep.success_count) || 0;
-  const failure = Number(rep.failure_count) || 0;
-  const total = success + failure;
-  return {
-    success_count: success,
-    failure_count: failure,
-    total_calls: total,
-    // RAW observed success rate for display; the smoothed reputationScore above is routing-only.
-    success_rate: total === 0 ? null : Number((success / total).toFixed(4))
-  };
-}
-
-function unhealthyThreshold() {
-  const n = Number(process.env.XYTARA_PROVIDER_UNHEALTHY_THRESHOLD);
-  return Number.isInteger(n) && n >= 1 ? n : 3;
-}
-function unhealthyCooldownMs() {
-  const n = Number(process.env.XYTARA_PROVIDER_UNHEALTHY_COOLDOWN_MS);
-  // Clamp to <= 24h so Date.now()+cooldown can never overflow a valid Date (which would throw
-  // in .toISOString() and silently drop the unhealthy transition, leaving a bad provider live).
-  return Number.isFinite(n) && n >= 0 ? Math.min(n, 86400000) : 60000;
-}
-function failoverMax() {
-  const n = Number(process.env.XYTARA_PROVIDER_FAILOVER_MAX);
-  return Number.isInteger(n) && n >= 1 ? n : 3;
-}
-
-// A provider is routable w.r.t. health when it is healthy, OR it was marked unhealthy but the
-// cooldown has elapsed (half-open: give it one more chance). Healthy is preferred over
-// half-open at selection time. Returns null for routable, or "unhealthy_cooldown" when skipped.
-function healthRoutingState(health, nowMs) {
-  const h = health || emptyHealth();
-  if (h.status !== "unhealthy") return { routable: true, half_open: false };
-  const until = h.unhealthy_until_iso ? Date.parse(h.unhealthy_until_iso) : 0;
-  // null -> 0 -> elapsed; a garbage/unparseable timestamp -> NaN -> treat as elapsed (recover,
-  // never strand a provider permanently excluded). Only a valid FUTURE timestamp excludes it.
-  if (!Number.isFinite(until) || nowMs >= until) return { routable: true, half_open: true };
-  return { routable: false, half_open: false };
-}
-
-const PAYOUT_STATUSES = new Set(["pending", "settled", "cancelled"]);
-
-const PROVIDER_STATUSES = new Set(["pending", "active", "suspended"]);
-
-function timingSafeStrEqual(a, b) {
-  const x = Buffer.from(String(a || ""), "utf8");
-  const y = Buffer.from(String(b || ""), "utf8");
-  if (x.length !== y.length || x.length === 0) return false;
-  try { return crypto.timingSafeEqual(x, y); } catch (_) { return false; }
-}
-
-function maxRevenueShareBps() {
-  const raw = Number(process.env.XYTARA_PROVIDER_MAX_REVENUE_SHARE_BPS);
-  return Number.isInteger(raw) && raw >= 0 && raw <= 10000 ? raw : 10000;
-}
-
-// Fields whose change on an ACTIVE provider must force re-approval (back to pending): the
-// endpoint it is called at, the capabilities it serves (which calls route to it), its
-// revenue split, and the token used to call it. Metadata (label/pricing/timeout) is exempt.
-function routingMaterialChanged(existing, next) {
-  // JSON-encode the sorted, deduped members (not a delimiter-join) so a member containing
-  // the separator cannot collide two different sets onto the same string.
-  const sameSet = (a, b) => {
-    const norm = (arr) => JSON.stringify([...new Set((arr || []).map(String))].sort());
-    return norm(a) === norm(b);
-  };
-  return existing.endpoint_url !== next.endpoint_url
-    || !sameSet(existing.task_refs, next.task_refs)
-    || !sameSet(existing.tool_names, next.tool_names)
-    || !sameSet(existing.integration_ids, next.integration_ids)
-    || existing.revenue_share_bps !== next.revenue_share_bps
-    || (existing.auth_token || null) !== (next.auth_token || null);
-}
-
-function ensureProviderCollections(state) {
-  if (!state || typeof state !== "object") return;
-  if (!(state.providerRegistry instanceof Map)) state.providerRegistry = new Map();
-  if (!Array.isArray(state.providerSettlementLedger)) state.providerSettlementLedger = [];
-  if (!Array.isArray(state.providerPayouts)) state.providerPayouts = [];
-}
-
-function rollupField(rec, field) {
-  return rec && rec.rollup && Number.isFinite(Number(rec.rollup[field])) ? Number(rec.rollup[field]) : 0;
-}
-
-// Ledger rows and payouts belong to a REGISTRATION of a provider_id, not to the id itself: a
-// removed id that someone else re-registers must never see, inherit, or be credited by the
-// previous owner's rows. Legacy rows/records without an epoch match each other (null === null).
-function sameRegistrationEpoch(row, rec) {
-  return ((row && row.registration_epoch) || null) === ((rec && rec.registration_epoch) || null);
-}
-
-// A payout mid-dispatch to the signer must not be cancellable: the signer may already have sent
-// the funds, and freeing the reservation would let a second payout re-send them. The guard
-// expires (process died during dispatch) so an operator can still reconcile a stuck record.
-const IN_FLIGHT_CANCEL_GUARD_MS = 5 * 60 * 1000;
-function payoutInFlight(payout) {
-  if (!payout || payout.dispatch_state !== "in_flight") return false;
-  const started = Date.parse(payout.dispatch_started_at_iso || "");
-  return !Number.isFinite(started) || Date.now() - started < IN_FLIGHT_CANCEL_GUARD_MS;
-}
-
-// What a provider is owed, accounting for already-settled payouts AND outstanding pending ones
-// so two concurrent pending payouts can never over-draw the accrued share.
-//   accrued   = cumulative provider_share credited by settlements
-//   paid_out  = cumulative confirmed (settled) payouts
-//   pending   = sum of not-yet-confirmed payouts
-//   available = accrued - paid_out - pending   (the max a NEW payout may claim)
-//   owed      = accrued - paid_out             (total still outstanding, incl. pending)
-function computeProviderPayoutState(state, providerId) {
-  ensureProviderCollections(state);
-  const rec = state.providerRegistry.get(normStr(providerId));
-  if (!rec) return null;
-  const accrued = rollupField(rec, "provider_share_minor");
-  const paidOut = rollupField(rec, "paid_out_minor");
-  const pending = state.providerPayouts
-    .filter((p) => p.provider_id === rec.provider_id && sameRegistrationEpoch(p, rec) && p.status === "pending")
-    .reduce((sum, p) => sum + (Number(p.amount_minor) || 0), 0);
-  return {
-    provider_id: rec.provider_id,
-    payout_address: rec.payout_address || null,
-    payout_network: rec.payout_network || null,
-    payout_asset: rec.payout_asset || null,
-    currency: "USD_CENTS",
-    accrued_minor: accrued,
-    paid_out_minor: paidOut,
-    pending_minor: pending,
-    available_minor: Math.max(0, accrued - paidOut - pending),
-    owed_minor: Math.max(0, accrued - paidOut)
-  };
-}
-
-// Never leaks auth_token — callers that need to CALL the provider read the stored record
-// directly (resolveRegisteredTarget); everything buyer/operator-facing uses this view.
-function buildProviderPublicView(rec) {
-  if (!rec) return null;
-  return {
-    provider_id: rec.provider_id,
-    label: rec.label,
-    endpoint_url: rec.endpoint_url,
-    task_refs: rec.task_refs,
-    tool_names: rec.tool_names,
-    integration_ids: rec.integration_ids,
-    revenue_share_bps: rec.revenue_share_bps,
-    pricing: rec.pricing,
-    status: rec.status,
-    timeout_ms: rec.timeout_ms,
-    auth_bound: Boolean(rec.auth_token),
-    payout_bound: Boolean(rec.payout_address),
-    payout_network: rec.payout_network || null,
-    payout_asset: rec.payout_asset || null,
-    registered_at_iso: rec.registered_at_iso,
-    activated_at_iso: rec.activated_at_iso,
-    updated_at_iso: rec.updated_at_iso,
-    rollup: { ...emptyRollup(), ...(rec.rollup || {}) },
-    health: { ...emptyHealth(), ...(rec.health || {}) },
-    reputation: reputationView(rec)
-  };
-}
-
-// POST register (or idempotent update keyed on provider_id).
-function registerProvider(state, input) {
-  ensureProviderCollections(state);
-  const b = ensureObject(input);
-  const endpointUrl = normStr(b.endpoint_url);
-  if (!endpointUrl || !/^https?:\/\//i.test(endpointUrl)) {
-    return { ok: false, reason: "endpoint_url_required" };
-  }
-  // Endpoint policy (strict on hosted deploys): https only, no loopback/private/link-local/metadata
-  // hosts, no embedded credentials — the runtime POSTs to this URL, so it must not be usable as a
-  // proxy into the runtime's own network. Re-checked (with DNS) at dispatch time.
-  const endpointPolicy = checkEndpointUrlShape(endpointUrl);
-  if (!endpointPolicy.ok) {
-    return { ok: false, reason: endpointPolicy.reason, detail: endpointPolicy.detail || null, endpoint_policy: endpointPolicy.policy };
-  }
-  const taskRefs = normStrArray(b.task_refs);
-  const toolNames = normStrArray(b.tool_names);
-  const integrationIds = normStrArray(b.integration_ids);
-  if (taskRefs.length + toolNames.length + integrationIds.length < 1) {
-    return { ok: false, reason: "capability_selector_required" };
-  }
-  const shareBps = Number(b.revenue_share_bps);
-  if (!Number.isInteger(shareBps) || shareBps < 0 || shareBps > 10000) {
-    return { ok: false, reason: "revenue_share_bps_invalid" };
-  }
-  if (shareBps > maxRevenueShareBps()) {
-    return { ok: false, reason: "revenue_share_bps_exceeds_max", max_revenue_share_bps: maxRevenueShareBps() };
-  }
-  const providerId = normStr(b.provider_id) || `provider_${crypto.randomBytes(6).toString("hex")}`;
-  const existing = state.providerRegistry.get(providerId) || null;
-
-  // Per-provider ownership: a new provider_id mints an owner_secret (returned ONCE); any
-  // re-registration of an existing provider_id MUST present that secret. This stops one
-  // holder of the shared registration bearer from mutating, re-pointing, or DoS-ing another
-  // provider's record.
-  if (existing && !timingSafeStrEqual(normStr(b.owner_secret), existing.owner_secret)) {
-    return { ok: false, reason: "provider_owner_mismatch" };
-  }
-  const ownerSecret = existing ? existing.owner_secret : `prvown_${crypto.randomBytes(24).toString("hex")}`;
-  const authToken = normStr(b.auth_token) || (existing && existing.auth_token) || null;
-
-  // Payout destination (where this provider's revenue-share is paid). Owner-protected like
-  // the rest of the record; NOT routing-material (changing it does not affect execution, so
-  // it does not revert an active provider to pending). An eip155 address is shape-checked.
-  const payoutNetwork = normStr(b.payout_network) || (existing && existing.payout_network) || "eip155:8453";
-  const payoutAsset = normStr(b.payout_asset) || (existing && existing.payout_asset) || "USDC";
-  const payoutAddress = normStr(b.payout_address) || (existing && existing.payout_address) || null;
-  if (payoutAddress && /^eip155/i.test(payoutNetwork) && !/^0x[0-9a-fA-F]{40}$/.test(payoutAddress)) {
-    return { ok: false, reason: "payout_address_invalid" };
-  }
-
-  const nextRouting = {
-    endpoint_url: endpointUrl,
-    task_refs: taskRefs,
-    tool_names: toolNames,
-    integration_ids: integrationIds,
-    revenue_share_bps: shareBps,
-    auth_token: authToken
-  };
-  // New -> pending. Re-registration that changes ANY routing-material field (endpoint, served
-  // capabilities, revenue split, or call token) reverts an ACTIVE provider to pending, so an
-  // expanded or altered capability can never receive paid traffic without operator re-approval.
-  let status = existing ? existing.status : "pending";
-  if (existing && existing.status === "active" && routingMaterialChanged(existing, nextRouting)) {
-    status = "pending";
-  }
-
-  const record = {
-    provider_id: providerId,
-    label: normStr(b.label, providerId),
-    endpoint_url: endpointUrl,
-    task_refs: taskRefs,
-    tool_names: toolNames,
-    integration_ids: integrationIds,
-    revenue_share_bps: shareBps,
-    pricing: ensureObject(b.pricing),
-    payout_address: payoutAddress,
-    payout_network: payoutNetwork,
-    payout_asset: payoutAsset,
-    auth_token: authToken,
-    owner_secret: ownerSecret,
-    // Minted once per registration; every ledger row / payout is stamped with it (see
-    // sameRegistrationEpoch). A re-registration of an existing record keeps its epoch.
-    registration_epoch: existing ? (existing.registration_epoch || null) : `reg_${crypto.randomBytes(6).toString("hex")}`,
-    // Capped (30s): a longer call could not settle inside the x402 authorization window.
-    timeout_ms: clampTargetTimeoutMs(b.timeout_ms),
-    status,
-    registered_by: normStr(b.registered_by) || (existing && existing.registered_by) || null,
-    registered_at_iso: existing ? existing.registered_at_iso : nowIso(),
-    activated_at_iso: status === "active" ? (existing && existing.activated_at_iso) || null : (existing && existing.activated_at_iso) || null,
-    updated_at_iso: nowIso(),
-    rollup: existing ? existing.rollup : emptyRollup(),
-    health: existing ? (existing.health || emptyHealth()) : emptyHealth(),
-    reputation: existing ? (existing.reputation || emptyReputation()) : emptyReputation()
-  };
-  state.providerRegistry.set(providerId, record);
-  const result = { ok: true, provider_id: providerId, status, provider: buildProviderPublicView(record) };
-  if (!existing) result.owner_secret = ownerSecret; // returned exactly once, at first registration
-  return result;
-}
-
-// Operator activate / suspend / re-pend.
-function setProviderStatus(state, providerId, status) {
-  ensureProviderCollections(state);
-  const nextStatus = normStr(status);
-  if (!PROVIDER_STATUSES.has(nextStatus)) return { ok: false, reason: "invalid_status" };
-  const rec = state.providerRegistry.get(normStr(providerId));
-  if (!rec) return { ok: false, reason: "provider_not_found" };
-  const next = {
-    ...rec,
-    status: nextStatus,
-    activated_at_iso: nextStatus === "active" ? rec.activated_at_iso || nowIso() : rec.activated_at_iso,
-    updated_at_iso: nowIso()
-  };
-  state.providerRegistry.set(rec.provider_id, next);
-  return { ok: true, provider: buildProviderPublicView(next) };
-}
-
-function getProvider(state, providerId) {
-  ensureProviderCollections(state);
-  return state.providerRegistry.get(normStr(providerId)) || null;
-}
-
-// Operator removes a provider from the registry (e.g. to purge suspended/spam records and free
-// the pending pool). Refuses when the provider still has an unpaid owed balance unless `force`,
-// so a provider with earnings can't be silently dropped.
-function removeProvider(state, providerId, options = {}) {
-  ensureProviderCollections(state);
-  const id = normStr(providerId);
-  const rec = state.providerRegistry.get(id);
-  if (!rec) return { ok: false, reason: "provider_not_found" };
-  const owed = Math.max(0, rollupField(rec, "provider_share_minor") - rollupField(rec, "paid_out_minor"));
-  if (owed > 0 && !(options && options.force)) {
-    return { ok: false, reason: "provider_has_unpaid_balance", owed_minor: owed };
-  }
-  // Cancel this registration's pending payouts so they can never be confirmed against (or reserve
-  // balance of) a later registration of the same id. A payout mid-dispatch may already have been
-  // sent, so it is left pending for manual reconciliation. Ledger rows are retained as the
-  // operator's audit trail; they are epoch-scoped so a new registration never sees them.
-  const cancelledPendingPayouts = [];
-  const inFlightPayouts = [];
-  for (const payout of state.providerPayouts) {
-    if (payout.provider_id !== id || payout.status !== "pending" || !sameRegistrationEpoch(payout, rec)) continue;
-    if (payoutInFlight(payout)) {
-      inFlightPayouts.push(payout.payout_id);
-      continue;
-    }
-    payout.status = "cancelled";
-    payout.cancelled_at_iso = nowIso();
-    payout.note = [payout.note, "provider_removed"].filter(Boolean).join("; ");
-    cancelledPendingPayouts.push(payout.payout_id);
-  }
-  state.providerRegistry.delete(id);
-  return {
-    ok: true,
-    removed: id,
-    forced: Boolean(options && options.force),
-    owed_minor_at_removal: owed,
-    cancelled_pending_payouts: cancelledPendingPayouts,
-    in_flight_payouts_left_pending: inFlightPayouts
-  };
-}
-
-function listProviders(state, filters = {}) {
-  ensureProviderCollections(state);
-  let items = Array.from(state.providerRegistry.values());
-  const status = normStr(filters && filters.status);
-  if (status) items = items.filter((p) => p.status === status);
-  return items;
-}
-
-// Resolve an ACTIVE registered provider for a call. Mirrors the env-target selectors
-// (task_ref / tool_name / integration_id) but a provider matches if the call hits ANY of
-// the capabilities it declared it serves. Returns a target shaped for executeExternalTarget.
-function providerMatchesCall(p, taskRefs, toolName, integrationIds) {
-  if (p.status !== "active") return false;
-  if (p.task_refs.length && p.task_refs.some((r) => taskRefs.includes(r))) return true;
-  if (p.tool_names.length && toolName && p.tool_names.includes(toolName)) return true;
-  if (p.integration_ids.length && p.integration_ids.some((id) => integrationIds.has(id))) return true;
-  return false;
-}
-
-// Hosted providers can be cold (a free-tier host takes 20–50 s to wake). On a hosted deploy a
-// registered provider gets at least this long per attempt, inside the shared execution budget, so
-// a waking provider isn't cut off at its 10 s default and reported as a buyer-input failure.
-function providerMinTimeoutMs() {
-  const raw = process.env.XYTARA_PROVIDER_MIN_TIMEOUT_MS;
-  const fallback = process.env.RENDER ? 25000 : 0;
-  const n = raw === undefined || raw === "" ? fallback : Number(raw);
-  return Number.isFinite(n) && n > 0 ? Math.min(30000, Math.round(n)) : 0;
-}
-
-function targetFromProvider(p) {
-  return {
-    target_id: p.provider_id,
-    endpoint_url: p.endpoint_url,
-    task_ref: null,
-    tool_name: null,
-    integration_id: null,
-    provider: p.provider_id,
-    auth_token: p.auth_token,
-    timeout_ms: Math.max(Number(p.timeout_ms) || 0, providerMinTimeoutMs()),
-    enabled: true,
-    registered_provider_id: p.provider_id
-  };
-}
-
-// All ACTIVE + health-routable providers matching the call, ordered healthy-first then
-// half-open (recovered past their cooldown), capped at the failover max — so a caller can try
-// them in sequence and fail over when one is down. Currently-unhealthy (in-cooldown) providers
-// are excluded.
-function extractCallSelectors(payload, quote) {
-  const body = ensureObject(payload && payload.body);
-  const taskRefs = Array.isArray(payload && payload.tasks) && payload.tasks.length > 0
-    ? payload.tasks.map((t) => normStr(t && t.task_ref)).filter(Boolean)
-    : [normStr(payload && payload.task_ref)].filter(Boolean);
-  const toolName = normStr(body.tool_name) || null;
-  const integrationIds = new Set(
-    []
-      .concat(normStr(payload && payload.integration_id) ? [normStr(payload && payload.integration_id)] : [])
-      .concat(Array.isArray(payload && payload.integration_ids) ? payload.integration_ids.map((v) => normStr(v)).filter(Boolean) : [])
-      .concat(Array.isArray(quote && quote.integration_ids) ? quote.integration_ids.map((v) => normStr(v)).filter(Boolean) : [])
-  );
-  return { taskRefs, toolName, integrationIds };
-}
-
-// Whether ANY active provider matches the call, regardless of health. Lets the caller tell
-// "no provider serves this capability" (fall through to local handling) apart from "providers
-// serve it but are all currently unhealthy" (fail — don't charge for undelivered work).
-function hasActiveMatchingProvider(state, payload, quote) {
-  ensureProviderCollections(state);
-  if (state.providerRegistry.size < 1) return false;
-  const { taskRefs, toolName, integrationIds } = extractCallSelectors(payload, quote);
-  for (const p of state.providerRegistry.values()) {
-    if (providerMatchesCall(p, taskRefs, toolName, integrationIds)) return true;
-  }
-  return false;
-}
-
-function resolveRegisteredTargets(state, payload, quote) {
-  ensureProviderCollections(state);
-  if (state.providerRegistry.size < 1) return [];
-  const { taskRefs, toolName, integrationIds } = extractCallSelectors(payload, quote);
-  const nowMs = Date.now();
-  const healthy = [];
-  const halfOpen = [];
-  for (const p of state.providerRegistry.values()) {
-    if (!providerMatchesCall(p, taskRefs, toolName, integrationIds)) continue;
-    const hs = healthRoutingState(p.health, nowMs);
-    if (!hs.routable) continue;
-    (hs.half_open ? halfOpen : healthy).push(p);
-  }
-  // Within the healthy tier, prefer higher lifetime reputation (stable sort keeps registration
-  // order for ties; a no-history provider scores 1.0 optimistically so it still gets routed and
-  // can build a record). Half-open (recovering) providers always come after healthy ones.
-  healthy.sort((a, b) => reputationScore(b) - reputationScore(a));
-  return healthy.concat(halfOpen).map(targetFromProvider).slice(0, failoverMax());
-}
-
-function resolveRegisteredTarget(state, payload, quote) {
-  const targets = resolveRegisteredTargets(state, payload, quote);
-  return targets.length > 0 ? targets[0] : null;
-}
-
-// Update a provider's health after a routed call. Success resets to healthy; failure increments
-// consecutive_failures and, on crossing the threshold, marks it unhealthy with a cooldown
-// (excluded from routing until the cooldown elapses, then half-open for one retry).
-function recordProviderHealth(state, providerId, result = {}) {
-  ensureProviderCollections(state);
-  const rec = state.providerRegistry.get(normStr(providerId));
-  if (!rec) return { ok: false, reason: "provider_not_found" };
-  const h = rec.health || emptyHealth();
-  const stamp = nowIso();
-  let next;
-  if (result && result.ok) {
-    next = { status: "healthy", consecutive_failures: 0, last_success_at_iso: stamp, last_failure_at_iso: h.last_failure_at_iso || null, unhealthy_until_iso: null };
-  } else {
-    const failures = (Number(h.consecutive_failures) || 0) + 1;
-    const nowUnhealthy = failures >= unhealthyThreshold();
-    next = {
-      status: nowUnhealthy ? "unhealthy" : h.status,
-      consecutive_failures: failures,
-      last_success_at_iso: h.last_success_at_iso || null,
-      last_failure_at_iso: stamp,
-      unhealthy_until_iso: nowUnhealthy ? new Date(Date.now() + unhealthyCooldownMs()).toISOString() : (h.unhealthy_until_iso || null)
-    };
-  }
-  const rep = rec.reputation || emptyReputation();
-  const ok = Boolean(result && result.ok);
-  // Raw lifetime counts (for display / success_rate) — unchanged integer-increment semantics.
-  const rawSuccess = (Number(rep.success_count) || 0) + (ok ? 1 : 0);
-  const rawFailure = (Number(rep.failure_count) || 0) + (ok ? 0 : 1);
-  // Recency-weighted pseudo-counts (routing order). Seeded from the raw counts the first time, then
-  // decayed each update. With the default factor 1.0 these stay equal to the raw counts exactly.
-  const decay = reputationDecayFactor();
-  const baseSuccess = Number.isFinite(Number(rep.decayed_success)) ? Number(rep.decayed_success) : (Number(rep.success_count) || 0);
-  const baseFailure = Number.isFinite(Number(rep.decayed_failure)) ? Number(rep.decayed_failure) : (Number(rep.failure_count) || 0);
-  const nextRep = {
-    success_count: rawSuccess,
-    failure_count: rawFailure,
-    decayed_success: baseSuccess * decay + (ok ? 1 : 0),
-    decayed_failure: baseFailure * decay + (ok ? 0 : 1)
-  };
-  state.providerRegistry.set(rec.provider_id, { ...rec, health: next, reputation: nextRep, updated_at_iso: stamp });
-  return { ok: true, health: next, reputation: nextRep };
-}
-
-// Count a routed dispatch (whether or not it later settles).
-function recordProviderRouting(state, providerId) {
-  ensureProviderCollections(state);
-  const rec = state.providerRegistry.get(normStr(providerId));
-  if (!rec) return { ok: false, reason: "provider_not_found" };
-  const roll = rec.rollup || emptyRollup();
-  state.providerRegistry.set(rec.provider_id, {
-    ...rec,
-    rollup: { ...roll, routed_calls: (roll.routed_calls || 0) + 1 },
-    updated_at_iso: nowIso()
-  });
-  return { ok: true };
-}
-
-// Split a settled amount for a provider and record a ledger entry. provider_share is floored
-// (platform keeps the rounding remainder); amounts are integer minor units.
-function recordProviderSettlement(state, input) {
-  ensureProviderCollections(state);
-  const b = ensureObject(input);
-  const rec = state.providerRegistry.get(normStr(b.provider_id));
-  if (!rec) return { ok: false, reason: "provider_not_found" };
-  const gross = Math.max(0, Math.round(Number(b.amount_minor) || 0));
-  const providerShare = Math.floor((gross * rec.revenue_share_bps) / 10000);
-  const platformTake = gross - providerShare;
-  const optionalMinor = (value) => (value !== undefined && value !== null && Number.isFinite(Number(value)) ? Math.round(Number(value)) : null);
-  const entry = {
-    settlement_entry_id: `provset_${crypto.randomBytes(6).toString("hex")}`,
-    provider_id: rec.provider_id,
-    registration_epoch: rec.registration_epoch || null,
-    transaction_id: normStr(b.transaction_id) || null,
-    settlement_ref: normStr(b.settlement_ref) || null,
-    task_ref: normStr(b.task_ref) || null,
-    currency: normStr(b.currency) || null,
-    // What the accrual was based on (the caller reconciles quote vs. what actually settled).
-    settlement_basis: normStr(b.settlement_basis) || "quote",
-    quoted_minor: optionalMinor(b.quoted_minor),
-    settled_minor: optionalMinor(b.settled_minor),
-    reconciled: b.reconciled === undefined ? true : Boolean(b.reconciled),
-    gross_minor: gross,
-    revenue_share_bps: rec.revenue_share_bps,
-    provider_share_minor: providerShare,
-    platform_take_minor: platformTake,
-    recorded_at_iso: nowIso()
-  };
-  state.providerSettlementLedger.push(entry);
-  const roll = rec.rollup || emptyRollup();
-  state.providerRegistry.set(rec.provider_id, {
-    ...rec,
-    rollup: {
-      ...roll,
-      settled_calls: (roll.settled_calls || 0) + 1,
-      gross_minor: (roll.gross_minor || 0) + gross,
-      provider_share_minor: (roll.provider_share_minor || 0) + providerShare,
-      platform_take_minor: (roll.platform_take_minor || 0) + platformTake
-    },
-    updated_at_iso: nowIso()
-  });
-  return { ok: true, settlement: entry };
-}
-
-// Optional `registration_epoch` filter (pass null to select legacy un-stamped rows) scopes the
-// rows to ONE registration of the id; without it the operator sees the full audit trail.
-function hasEpochFilter(filters) {
-  return Boolean(filters) && Object.prototype.hasOwnProperty.call(filters, "registration_epoch");
-}
-
-function listProviderSettlements(state, filters = {}) {
-  ensureProviderCollections(state);
-  let items = state.providerSettlementLedger.slice();
-  const providerId = normStr(filters && filters.provider_id);
-  if (providerId) items = items.filter((e) => e.provider_id === providerId);
-  if (hasEpochFilter(filters)) items = items.filter((e) => sameRegistrationEpoch(e, { registration_epoch: filters.registration_epoch }));
-  return items;
-}
-
-// Create a payout CLAIM for a provider (operator action). Amount defaults to the full
-// available balance and can NEVER exceed available (accrued - paid - pending), so concurrent
-// pending payouts cannot over-draw. The runtime does NOT move funds here — it records the
-// intent; the operator executes the on-chain transfer and confirms it with the tx hash.
-function createProviderPayout(state, providerId, input = {}) {
-  ensureProviderCollections(state);
-  const rec = state.providerRegistry.get(normStr(providerId));
-  if (!rec) return { ok: false, reason: "provider_not_found" };
-  if (!rec.payout_address) return { ok: false, reason: "payout_address_not_set" };
-  const payoutState = computeProviderPayoutState(state, rec.provider_id);
-  const available = payoutState.available_minor;
-  if (available <= 0) return { ok: false, reason: "nothing_payable", available_minor: available };
-  const b = ensureObject(input);
-  const requested = b.amount_minor !== undefined && b.amount_minor !== null ? Math.round(Number(b.amount_minor)) : available;
-  if (!Number.isFinite(requested) || requested <= 0) return { ok: false, reason: "amount_invalid" };
-  if (requested > available) return { ok: false, reason: "amount_exceeds_available", available_minor: available };
-  const payout = {
-    payout_id: `provpay_${crypto.randomBytes(6).toString("hex")}`,
-    provider_id: rec.provider_id,
-    registration_epoch: rec.registration_epoch || null,
-    dispatch_state: null,
-    dispatch_started_at_iso: null,
-    payout_address: rec.payout_address,
-    payout_network: rec.payout_network || null,
-    payout_asset: rec.payout_asset || null,
-    amount_minor: requested,
-    currency: "USD_CENTS",
-    status: "pending",
-    tx_ref: null,
-    created_at_iso: nowIso(),
-    settled_at_iso: null,
-    cancelled_at_iso: null,
-    note: normStr(b.note) || null
-  };
-  state.providerPayouts.push(payout);
-  return { ok: true, payout, payout_state: computeProviderPayoutState(state, rec.provider_id) };
-}
-
-function getProviderPayout(state, payoutId) {
-  ensureProviderCollections(state);
-  return state.providerPayouts.find((p) => p.payout_id === normStr(payoutId)) || null;
-}
-
-// Confirm a payout the operator executed on-chain. Idempotent: re-confirming a settled payout
-// returns it without double-crediting paid_out. Only a pending payout credits paid_out_minor.
-function confirmProviderPayout(state, payoutId, input = {}) {
-  ensureProviderCollections(state);
-  const payout = getProviderPayout(state, payoutId);
-  if (!payout) return { ok: false, reason: "payout_not_found" };
-  if (payout.status === "settled") return { ok: true, payout, idempotent: true };
-  if (payout.status !== "pending") return { ok: false, reason: "payout_not_pending", status: payout.status };
-  const txRef = normStr(ensureObject(input).tx_ref);
-  if (!txRef) return { ok: false, reason: "tx_ref_required" };
-  // A tx_ref may back only ONE settled payout. Otherwise two payouts credit paid_out for a
-  // single on-chain transfer, silently under-paying the provider and burning reserved balance.
-  if (state.providerPayouts.some((p) => p.status === "settled" && p.tx_ref === txRef && p.payout_id !== payout.payout_id)) {
-    return { ok: false, reason: "duplicate_tx_ref" };
-  }
-  payout.status = "settled";
-  payout.tx_ref = txRef;
-  payout.settled_at_iso = nowIso();
-  payout.dispatch_state = null;
-  const rec = state.providerRegistry.get(payout.provider_id);
-  // Credit paid_out ONLY on the registration the payout belongs to — a payout from a previous
-  // (removed) registration of the same id is recorded but never credits the current record.
-  const rollupCredited = Boolean(rec && sameRegistrationEpoch(payout, rec));
-  if (rollupCredited) {
-    const roll = rec.rollup || emptyRollup();
-    state.providerRegistry.set(rec.provider_id, {
-      ...rec,
-      rollup: { ...roll, paid_out_minor: (Number(roll.paid_out_minor) || 0) + payout.amount_minor },
-      updated_at_iso: nowIso()
-    });
-  }
-  return { ok: true, payout, rollup_credited: rollupCredited, payout_state: rec ? computeProviderPayoutState(state, payout.provider_id) : null };
-}
-
-// Cancel a pending payout — frees its reserved amount back into available. Never a settled one.
-function cancelProviderPayout(state, payoutId) {
-  ensureProviderCollections(state);
-  const payout = getProviderPayout(state, payoutId);
-  if (!payout) return { ok: false, reason: "payout_not_found" };
-  if (payout.status === "cancelled") return { ok: true, payout, idempotent: true };
-  if (payout.status !== "pending") return { ok: false, reason: "payout_not_pending", status: payout.status };
-  if (payoutInFlight(payout)) {
-    return {
-      ok: false,
-      reason: "payout_in_flight",
-      status: payout.status,
-      dispatch_started_at_iso: payout.dispatch_started_at_iso || null,
-      remediation: "this payout is being sent by the signer right now; wait for the dispatch result (it confirms or stays pending for reconciliation) instead of cancelling"
-    };
-  }
-  payout.status = "cancelled";
-  payout.cancelled_at_iso = nowIso();
-  return {
-    ok: true,
-    payout,
-    warning: "cancel only a payout NOT yet sent on-chain — the amount returns to available and can be paid again"
-  };
-}
-
-// Dispatch bookkeeping for the external-signer flow: "in_flight" while the signer call is
-// outstanding (blocks cancel, see payoutInFlight), null once the signer has answered.
-function markProviderPayoutDispatch(state, payoutId, dispatchState) {
-  ensureProviderCollections(state);
-  const payout = getProviderPayout(state, payoutId);
-  if (!payout) return { ok: false, reason: "payout_not_found" };
-  if (dispatchState === "in_flight") {
-    payout.dispatch_state = "in_flight";
-    payout.dispatch_started_at_iso = nowIso();
-  } else {
-    payout.dispatch_state = null;
-  }
-  return { ok: true, payout };
-}
-
-// Last-resort safety net: a payout that was cancelled while (or after) the signer actually sent
-// the funds is put back to PENDING with the reported tx and flagged, so the reservation is held
-// again and the operator reconciles (confirm with the tx) instead of the ledger re-paying it.
-function reinstateCancelledPayoutForReconciliation(state, payoutId, txRef) {
-  ensureProviderCollections(state);
-  const payout = getProviderPayout(state, payoutId);
-  if (!payout) return { ok: false, reason: "payout_not_found" };
-  if (payout.status !== "cancelled") return { ok: false, reason: "payout_not_cancelled", status: payout.status };
-  payout.status = "pending";
-  payout.cancelled_at_iso = null;
-  payout.dispatch_state = null;
-  payout.tx_ref = normStr(txRef) || payout.tx_ref || null;
-  payout.reconcile_required = true;
-  payout.note = [payout.note, "reinstated_after_cancel_during_dispatch"].filter(Boolean).join("; ");
-  return { ok: true, payout };
-}
-
-function listProviderPayouts(state, filters = {}) {
-  ensureProviderCollections(state);
-  let items = state.providerPayouts.slice();
-  const providerId = normStr(filters && filters.provider_id);
-  const status = normStr(filters && filters.status);
-  if (providerId) items = items.filter((p) => p.provider_id === providerId);
-  if (status) items = items.filter((p) => p.status === status);
-  if (hasEpochFilter(filters)) items = items.filter((p) => sameRegistrationEpoch(p, { registration_epoch: filters.registration_epoch }));
-  return items;
-}
-
-// Authenticate a provider acting on its OWN record using the owner_secret minted at
-// registration (constant-time compare). Returns the record on match, or a reason code. This is
-// the provider-SIDE auth (self-service), distinct from the operator bearer: it lets a
-// self-registered provider read its own earnings without granting any operator capability.
-function authenticateProviderOwner(state, providerId, ownerSecret) {
-  ensureProviderCollections(state);
-  const rec = state.providerRegistry.get(normStr(providerId));
-  if (!rec) return { ok: false, reason: "provider_not_found" };
-  if (!timingSafeStrEqual(normStr(ownerSecret), rec.owner_secret)) {
-    return { ok: false, reason: "provider_owner_mismatch" };
-  }
-  return { ok: true, provider: rec };
-}
-
-// Read-only self-service earnings view for a provider: its public profile, computed payout state
-// (accrued / paid / pending / available / owed), its settlement ledger rows, and its payout
-// history. Composes existing read helpers only — never mutates state, and never leaks auth_token
-// or owner_secret (public view + the provider's own ledger rows). Caller must authenticate first.
-function buildProviderEarningsView(state, providerId) {
-  ensureProviderCollections(state);
-  const rec = state.providerRegistry.get(normStr(providerId));
-  if (!rec) return null;
-  // Scoped to THIS registration's epoch: a re-registered id never reads a previous owner's rows.
-  const epoch = rec.registration_epoch || null;
-  return {
-    provider: buildProviderPublicView(rec),
-    payout_state: computeProviderPayoutState(state, rec.provider_id),
-    settlements: listProviderSettlements(state, { provider_id: rec.provider_id, registration_epoch: epoch }),
-    payouts: listProviderPayouts(state, { provider_id: rec.provider_id, registration_epoch: epoch })
-  };
-}
-
-function summarizeProviderNetwork(state) {
-  ensureProviderCollections(state);
-  const providers = Array.from(state.providerRegistry.values());
-  const byStatus = { pending: 0, active: 0, suspended: 0 };
-  const totals = { gross_minor: 0, provider_share_minor: 0, platform_take_minor: 0, paid_out_minor: 0, owed_minor: 0, routed_calls: 0, settled_calls: 0 };
-  for (const p of providers) {
-    byStatus[p.status] = (byStatus[p.status] || 0) + 1;
-    const share = rollupField(p, "provider_share_minor");
-    const paid = rollupField(p, "paid_out_minor");
-    totals.gross_minor += rollupField(p, "gross_minor");
-    totals.provider_share_minor += share;
-    totals.platform_take_minor += rollupField(p, "platform_take_minor");
-    totals.paid_out_minor += paid;
-    totals.owed_minor += Math.max(0, share - paid);
-    totals.routed_calls += rollupField(p, "routed_calls");
-    totals.settled_calls += rollupField(p, "settled_calls");
-  }
-  const nowMs = Date.now();
-  const health = { routable: 0, unhealthy: 0 };
-  for (const p of providers) {
-    if (p.status !== "active") continue;
-    if (healthRoutingState(p.health, nowMs).routable) health.routable += 1; else health.unhealthy += 1;
-  }
-  const pendingPayouts = state.providerPayouts.filter((p) => p.status === "pending");
-  return {
-    ok: true,
-    provider_count: providers.length,
-    by_status: byStatus,
-    health,
-    totals,
-    settlement_ledger_entries: state.providerSettlementLedger.length,
-    payouts: {
-      total: state.providerPayouts.length,
-      pending: pendingPayouts.length,
-      pending_minor: pendingPayouts.reduce((sum, p) => sum + (Number(p.amount_minor) || 0), 0)
-    }
-  };
-}
-
-module.exports = {
-  ensureProviderCollections,
-  registerProvider,
-  setProviderStatus,
-  getProvider,
-  removeProvider,
-  listProviders,
-  buildProviderPublicView,
-  authenticateProviderOwner,
-  buildProviderEarningsView,
-  resolveRegisteredTarget,
-  resolveRegisteredTargets,
-  hasActiveMatchingProvider,
-  recordProviderHealth,
-  recordProviderRouting,
-  recordProviderSettlement,
-  listProviderSettlements,
-  summarizeProviderNetwork,
-  computeProviderPayoutState,
-  createProviderPayout,
-  getProviderPayout,
-  confirmProviderPayout,
-  cancelProviderPayout,
-  markProviderPayoutDispatch,
-  reinstateCancelledPayoutForReconciliation,
-  listProviderPayouts
-};