Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(x402): surface the settle mechanism on healthz, where the runbook says to read it

nirholas019277358cad
diff --git a/api/_lib/ops/x402-settle-health.js b/api/_lib/ops/x402-settle-health.js
index 44489810e..7fc3aeda9 100644
--- a/api/_lib/ops/x402-settle-health.js
+++ b/api/_lib/ops/x402-settle-health.js
@@ -497,7 +497,13 @@ export async function gatherX402SettleHealth() {
topFaults: v.faultClasses.slice(0, 5),
// The collapse-vs-rejection split. `cause` is what an operator should
// read first; noSolanaAccept is the volume the rate cannot show.
+ // `mechanism` is what to read SECOND, and it is not cosmetic: one
+ // `cause: sponsor_floor` covers a withdrawn accept (the facilitator
+ // never saw these calls) and a floor refusal (it saw and rejected
+ // every one), which send an operator to opposite evidence. The triage
+ // runbook's mechanism table keys off exactly this field.
...(v.cause ? { cause: v.cause } : {}),
+ ...(v.mechanism ? { mechanism: v.mechanism } : {}),
noSolanaAccept: v.noSolanaAccept ?? 0,
floorSignals: v.floorSignals ?? 0,
// Deliberate spend-pacing, not failure. Read it next to `rate`: the two
diff --git a/tests/api/x402-settle-health.test.js b/tests/api/x402-settle-health.test.js
index 1da7511d1..c2651b916 100644
--- a/tests/api/x402-settle-health.test.js
+++ b/tests/api/x402-settle-health.test.js
@@ -1,4 +1,5 @@
import { describe, it, expect } from 'vitest';
+import { readFile } from 'node:fs/promises';
import {
isRailFault,
classifySettleBuckets,
@@ -583,3 +584,20 @@ describe('classifySettleBuckets: a floor refusal is not a withdrawn accept', ()
expect(rail.mechanism).toBe('rail');
});
});
+
+describe('readSettleHealth surfaces the mechanism the runbook tells operators to read', () => {
+ // The field is computed in the classifier and consumed by
+ // docs/ops/production-log-triage.md as `metrics.mechanism`. It reached the
+ // healthz payload only because it is listed in the metrics builder, and a
+ // documented field that is silently absent is worse than no field: it sends
+ // the reader looking for something that is not there. Pin the wiring.
+ it('lists mechanism in the metrics the health check builds', async () => {
+ const src = await readFile(
+ new URL('../../api/_lib/ops/x402-settle-health.js', import.meta.url),
+ 'utf8',
+ );
+ const metricsBlock = src.slice(src.indexOf('metrics: {'), src.indexOf('metrics: {') + 1400);
+ expect(metricsBlock).toMatch(/mechanism: v\.mechanism/);
+ expect(metricsBlock).toMatch(/cause: v\.cause/);
+ });
+});