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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
fix(fact-check): keep the verdict honest and the feed and avatars in step
nirholas771761928b2d
diff --git a/agents/fact-checker/src/llm-verdict.js b/agents/fact-checker/src/llm-verdict.jsindex 9e1f4bf48..5311bac65 100644--- a/agents/fact-checker/src/llm-verdict.js+++ b/agents/fact-checker/src/llm-verdict.js@@ -14,6 +14,76 @@ const TIMEOUT_MS = 30_000;// strictly worse than degrading immediately.const MIN_VIABLE_MS = 3_000;+// The stance vocabulary the verdict layer reads. `partial` exists because the+// verdict taxonomy has four classes and this list had three: a claim that is+// TRUE ONLY IN PART had nowhere to land, so every source judging one got+// collapsed onto "supports" or "contradicts" and the `mixed` verdict became+// unreachable from evidence that agrees with itself. See computeVerdict() in+// api/x402/fact-check.js.+export const STANCES = Object.freeze(['supports', 'contradicts', 'partial', 'neutral']);++/**+ * Pull the first well-formed JSON array out of an LLM response.+ *+ * The naive `text.match(/\[[\s\S]*?\]/)` this replaces was NON-greedy, so it+ * stopped at the first `]` in the response. Any bracket ahead of the real+ * payload truncated the match into garbage: a reasoning model's `<think>` block,+ * a markdown fence, a citation marker like `[1]`, or simply a nested array+ * inside the payload. When that happened both stages fell back silently, which+ * is how a live check on "A tomato is a vegetable." came back with five real+ * Wikipedia sources (Nix v. Hedden among them), 1476 spent LLM tokens, and+ * every stance "neutral".+ *+ * This scans for a BALANCED array instead, string-literal aware so a `]` inside+ * an excerpt cannot close it early, and retries at each later `[` so a leading+ * `[1]` citation is skipped rather than fatal.+ *+ * @param {string} text+ * @returns {unknown[] | null} the parsed array, or null when there is none.+ */+export function extractJsonArray(text) {+ if (typeof text !== 'string' || !text) return null;+ // Reasoning models emit their scratchpad first; it is prose, not payload.+ // Drop closed blocks, and drop an unterminated tail (a truncated turn).+ const body = text+ .replace(/<think>[\s\S]*?<\/think>/gi, ' ')+ .replace(/<think>[\s\S]*$/i, ' ')+ .replace(/```(?:json)?/gi, ' ');++ for (let start = body.indexOf('['); start !== -1; start = body.indexOf('[', start + 1)) {+ let depth = 0;+ let inString = false;+ let escaped = false;+ for (let i = start; i < body.length; i++) {+ const ch = body[i];+ if (escaped) {+ escaped = false;+ continue;+ }+ if (inString) {+ if (ch === '\\') escaped = true;+ else if (ch === '"') inString = false;+ continue;+ }+ if (ch === '"') inString = true;+ else if (ch === '[' || ch === '{') depth++;+ else if (ch === ']' || ch === '}') {+ depth--;+ if (depth === 0) {+ try {+ const parsed = JSON.parse(body.slice(start, i + 1));+ if (Array.isArray(parsed)) return parsed;+ } catch {+ // Not valid JSON from this `[`; try the next one.+ }+ break;+ }+ }+ }+ }+ return null;+}+/*** One LLM turn, bounded by whatever wall-clock budget the caller still has.*@@ -79,27 +149,32 @@ Example output: ["query one", "query two", "query three"]`;return { queries: [claim], tokens: 0, degraded: `query generation unavailable: ${failure}` };}- let queries;- try {- // Extract JSON array from the response, tolerating minor surrounding text.- const match = text.match(/\[[\s\S]*?\]/);- if (!match) throw new Error('no array found');- queries = JSON.parse(match[0]);- if (!Array.isArray(queries) || queries.length === 0) throw new Error('empty array');- queries = queries.slice(0, 3).map((q) => String(q).trim()).filter(Boolean);- if (queries.length === 0) throw new Error('all queries empty after trim');- } catch (parseErr) {- // Fallback: split on newlines and use first 3 non-empty lines.+ const parsed = extractJsonArray(text);+ let queries = Array.isArray(parsed)+ ? parsed.slice(0, 3).map((q) => String(q).trim()).filter(Boolean)+ : [];++ if (queries.length === 0) {+ // Fallback: read the response as a plain list, one query per line. Lines+ // are length-bounded and required to hold at least two words, because a+ // reasoning model's prose is not a search query — accepting it is how a+ // three-angle sweep silently collapsed into one bad one.queries = text.split('\n').map((l) => l.replace(/^["'\d.\-\s]+/, '').replace(/["',]+$/, '').trim())- .filter(Boolean)+ .filter((l) => l.length > 0 && l.length <= 120 && /\s/.test(l) && !l.endsWith(':')).slice(0, 3);+ }- if (queries.length === 0) {- // Last resort: use the claim itself as a query.- queries = [claim];- }+ if (queries.length === 0) {+ // Last resort: the claim itself is a legitimate search query, so the check+ // still runs on real evidence — but on one angle instead of three, which+ // the caller has to be told about.+ return {+ queries: [claim],+ tokens: inputTokens + outputTokens,+ degraded: 'query generation unreadable: provider returned no parseable query list',+ };}return { queries, tokens: inputTokens + outputTokens };@@ -135,13 +210,15 @@ ${numbered}For each result (1 through ${results.length}), output:- excerpt: a 200-character or shorter direct quote or paraphrase from the content that is most relevant to the claim-- stance: one of "supports", "contradicts", or "neutral"+- stance: one of "supports", "contradicts", "partial", or "neutral"Stance rubric — commit to a stance whenever the content addresses the claim's central assertion:- "supports": the content affirms the claim's central assertion, including via paraphrase or equivalent figures (e.g. claim says 330 m, source says "about 330 metres" or "1,083 ft").- "contradicts": the content states something INCOMPATIBLE with the claim. A different number, a different record-holder, a different date, or an explicit negation is a contradiction, NOT neutral. If the claim says "the tallest is X" and the source names Y as tallest, that contradicts.+- "partial": the content engages the claim's central assertion and shows the claim is true in one respect while wrong, overstated, or only conditionally true in another. Right about the fact but wrong about its scale, cause, exclusivity or universality; true only under conditions the content states; or a claim the content both affirms and corrects. If the claim conjoins several assertions and the same content affirms one while refuting another, that is "partial", not a choice between them.- "neutral": ONLY when the content genuinely does not address the claim's central assertion (same broad topic but silent on the specific fact). Do not use neutral as a low-effort default; check the numbers and named entities first.-- If the claim conjoins several assertions and the content affirms one while refuting another, choose the stance for the assertion the content speaks to most directly (supports if it affirms that part, contradicts if it refutes it).++Choosing between them: affirmed with no meaningful correction is "supports"; refuted with no part left standing is "contradicts". "partial" is not for hedged prose, thin coverage, or your own uncertainty. It requires the content itself to establish that the claim is both right and wrong in identifiable respects.Output ONLY a valid JSON array with ${results.length} objects, in order, each with fields "excerpt" (string) and "stance" (string).No markdown, no explanation, just the JSON array.@@ -166,7 +243,7 @@ Example (for 2 results): [{"excerpt":"The tower stands at 330m","stance":"suppor// Normalize and pad/trim to match results length.analyses = analyses.slice(0, results.length).map((a) => ({excerpt: String(a?.excerpt || '').slice(0, 200),- stance: ['supports', 'contradicts', 'neutral'].includes(a?.stance)+ stance: ['supports', 'contradicts', 'partial', 'neutral'].includes(a?.stance)? a.stance: 'neutral',}));diff --git a/api/_lib/avatars.js b/api/_lib/avatars.jsindex 823534928..8b8707208 100644--- a/api/_lib/avatars.js+++ b/api/_lib/avatars.js@@ -7,6 +7,55 @@ import { publicUrl, thumbnailUrl, presignGet, deleteObject } from './r2.js';import { defaultStorageMode } from './storage-mode.js';import { isUuid } from './validate.js';+/**+ * Build the row-selection half of listAvatars.+ *+ * With `includePublic` the caller sees their own avatars AND the public+ * catalog, which used to be one `(owner_id = $1 or visibility = 'public')`+ * predicate. That OR is unindexable: Postgres fell back to a parallel seq scan+ * plus a full sort of every row it kept, so the query cost grew with the+ * catalog instead of with the page. Measured on the live table at 58k avatars,+ * a 50-row page read 7,605 heap pages and took 48.7 ms, and it got slower every+ * day the seed cron ran.+ *+ * Each half is perfectly indexed on its own (`avatars_owner_idx`, and the+ * partial `avatars_public_idx` on (visibility, created_at desc)), so the+ * listing is a UNION ALL of two already-ordered, already-limited branches that+ * Postgres merges with a Merge Append. Same rows, same order, and the public+ * branch excludes the caller's own rows with `is distinct from` so a+ * self-owned public avatar appears exactly once while a NULL owner_id (which a+ * plain `<>` would silently drop) still shows. Same page on the same table:+ * 0.17 ms and 2 page reads.+ *+ * Only ids and the sort key pass through the union; the wide column list and+ * the agent-identity lateral are applied to the resulting page, so neither+ * branch carries the join.+ *+ * @param {{ includePublic: boolean, visibility?: string, cursor?: string,+ * limit: number, params: unknown[] }} opts `params` starts as+ * [userId] and is appended to in place.+ * @returns {string} a subquery yielding (id, created_at), unordered across the+ * union (the caller applies the final order + limit).+ */+function ownerVisibleRowsSql({ includePublic, visibility, cursor, limit, params }) {+ const shared = ['deleted_at is null'];+ if (visibility) {+ params.push(visibility);+ shared.push(`visibility = $${params.length}`);+ }+ if (cursor) {+ params.push(new Date(cursor));+ shared.push(`created_at < $${params.length}`);+ }+ params.push(limit);+ const lim = `$${params.length}`;+ const where = shared.join(' and ');+ const own = `(select id, created_at from avatars where owner_id = $1 and ${where} order by created_at desc limit ${lim})`;+ if (!includePublic) return own;+ const pub = `(select id, created_at from avatars where visibility = 'public' and owner_id is distinct from $1 and ${where} order by created_at desc limit ${lim})`;+ return `${own} union all ${pub}`;+}+export async function listAvatars({userId,limit = 50,@@ -16,17 +65,13 @@ export async function listAvatars({}) {limit = Math.min(Math.max(limit, 1), 200);const params = [userId];- const conds = ['a.deleted_at is null'];- conds.push(includePublic ? `(a.owner_id = $1 or a.visibility = 'public')` : `a.owner_id = $1`);- if (visibility) {- params.push(visibility);- conds.push(`a.visibility = $${params.length}`);- }- if (cursor) {- params.push(new Date(cursor));- conds.push(`a.created_at < $${params.length}`);- }- params.push(limit + 1);+ const rowsSql = ownerVisibleRowsSql({+ includePublic,+ visibility,+ cursor,+ limit: limit + 1,+ params,+ });// usdz_key / halfbody_key are intentionally NOT selected here yet — the// 20260515 migration adds them but is rolled out separately. The decorate()// helper falls back to null if the columns are missing from the row, so@@ -42,7 +87,8 @@ export async function listAvatars({ai.solana_address as agent_solana_address,ai.solana_vanity_prefix as agent_solana_vanity_prefix,ai.solana_vanity_suffix as agent_solana_vanity_suffix- from avatars a+ from (${rowsSql}) v+ join avatars a on a.id = v.idleft join lateral (select id, wallet_address,meta->>'solana_address' as solana_address,@@ -52,8 +98,7 @@ export async function listAvatars({where avatar_id = a.id and user_id = $1 and deleted_at is nullorder by created_at asc limit 1) ai on true- where ${conds.join(' and ')}- order by a.created_at desc limit $${params.length}`,+ order by v.created_at desc limit $${params.length}`,params,);const hasMore = rows.length > limit;diff --git a/api/_lib/feed.js b/api/_lib/feed.jsindex 010dd3d23..0924bd151 100644--- a/api/_lib/feed.js+++ b/api/_lib/feed.js@@ -104,6 +104,9 @@ export const USER_EVENT_TYPES = new Set(['asset_payment_mismatch','skill_payment_mismatch','referral_earned',+ // Materialize: one type for the whole print lifecycle, carrying the status+ // and, once the box ships, its certificate link.+ 'print_update',]);function redis() { return getRedis(); }diff --git a/api/ops/payment-outcomes.js b/api/ops/payment-outcomes.jsindex 91dccd7cb..e2fbe140f 100644--- a/api/ops/payment-outcomes.js+++ b/api/ops/payment-outcomes.js@@ -14,6 +14,13 @@// sponsor : fee-wallet SOL vs its floor plus measured burn (fee_lamports// over a stated window) and the runway in days that implies,// including the threshold the scheduled monitor alerts on.+// stranded_custody : custodial wallets whose secret no longer decrypts, with+// the SOL behind them split platform vs customer. Capital the+// treasury cannot reclaim and customers cannot withdraw is a+// payment-outcome fact, and it was previously visible only to+// whoever ran a CLI audit by hand. Snapshot-cached for six+// hours (custody loss is a rotation event, not a live metric),+// so polling this board never turns into fleet-wide RPC load.//// The panels are read independently and a failed one does not blank the others.// `ok` says whether all three rendered (never whether payments are healthy, which@@ -30,6 +37,7 @@ import { sql } from '../_lib/db.js';import { authorizeOps } from '../_lib/ops-auth.js';import { gatherX402SettleHealth } from '../_lib/ops/x402-settle-health.js';import { checkRingWallets } from '../_lib/x402/wallet-balance-monitor.js';+import { strandedCustodyPanel } from '../_lib/custodial-key-health.js';export const maxDuration = 30;@@ -201,12 +209,13 @@ export default wrap(async (req, res) => {const auth = await authorizeOps(req);if (!auth.ok) return error(res, 401, 'unauthorized', 'ops secret or admin session required');- // The three boards are independent reads; one failing must not blank the- // others (an RPC outage is exactly when the settle panels matter most).- const [inbound, ringSettle, sponsor] = await Promise.allSettled([+ // The panels are independent reads; one failing must not blank the others+ // (an RPC outage is exactly when the settle panels matter most).+ const [inbound, ringSettle, sponsor, stranded] = await Promise.allSettled([inboundBoard(),gatherX402SettleHealth(),sponsorBoard(),+ strandedCustodyPanel(),]);const unwrap = (r) => (r.status === 'fulfilled' ? r.value : { error: r.reason?.message || 'unavailable' });@@ -214,11 +223,12 @@ export default wrap(async (req, res) => {inbound: unwrap(inbound),ring_settle: unwrap(ringSettle),sponsor: unwrap(sponsor),+ stranded_custody: unwrap(stranded),};// `ok` reports whether the BOARD rendered, not whether payments are healthy// (that verdict is per panel). It used to be the literal `true`, so a read- // where all three panels threw still answered 200 ok:true with three error- // objects in the body: a monitoring surface that reports success while it is+ // where every panel threw still answered 200 ok:true with a body full of+ // error objects: a monitoring surface that reports success while it is// blind. A failed panel now names itself in `degraded` and the response is// 207 Multi-Status, the same convention /api/ops/health uses.const degraded = Object.keys(panels).filter((k) => panels[k]?.error);diff --git a/api/x402/fact-check.js b/api/x402/fact-check.jsindex b3f262afd..144b111f6 100644--- a/api/x402/fact-check.js+++ b/api/x402/fact-check.js@@ -121,21 +121,34 @@ function cacheKey(claim, strictness, imageUrl) {// ── Verdict logic ─────────────────────────────────────────────────────────────// Verdict = direction of the stance-BEARING evidence, gated by how much of the-// evidence engaged the claim at all. The previous version divided by TOTAL+// evidence engaged the claim at all. The pre-2026-08 version divided by TOTAL// weight (neutral sources included), so three tangential results could drown// two clear confirmations below the 0.65 bar, and an all-neutral result set-// still returned "mixed" — which is how the 2026-07-08 benchmark collapsed to+// still returned "mixed", which is how the 2026-07-08 benchmark collapsed to// 20% (every class predicted "mixed"). Rules now:-// • <2 sources, zero weight, or zero stance-bearing weight → insufficient:+// • <2 sources, zero weight, or zero stance-bearing weight -> insufficient:// evidence that never engages the claim is absence of evidence, not// disagreement.// • A single stance-bearing source lost in otherwise-silent evidence-// (coverage <30%) is also insufficient — one loosely-matched page must not+// (coverage <30%) is also insufficient: one loosely-matched page must not// decide a verdict on its own.-// • Direction is judged over stance-bearing weight only: ≥70% one way →-// supported/contradicted; a real split → mixed.+// • Direction is judged over stance-bearing weight only: >=70% one way ->+// supported/contradicted; anything else -> mixed.+// • `partial` weight is stance-bearing but takes neither side. A source that+// reports the claim as true in one respect and wrong in another is not a+// confirmation, so it dilutes dominance and pushes the result toward mixed.+// This is the SECOND route to a mixed verdict and the one that matters:+// before the stance existed, `mixed` was reachable only when sources+// disagreed with EACH OTHER, which well-sourced evidence about a well-known+// half-truth ("a tomato is a vegetable", "Napoleon was short") never does.+// Every source reads the same nuance and the old vocabulary forced each of+// them to project it onto one side, so the 2026-08-10 benchmark scored the+// whole mixed class 0/10 with 7 of them landing on `contradicted`.// • Confidence blends dominance with coverage, so a unanimous verdict from-// thin engagement scores lower than one from broad engagement.+// thin engagement scores lower than one from broad engagement. For `mixed`+// the dominance term is how strongly the evidence establishes mixedness+// itself (partial weight, plus opposed stances counted as the joint+// evidence of a split that they are), never how lopsided the split was.function computeVerdict(sources) {if (sources.length < 2) {return { verdict: 'insufficient', confidence: 0.2 };@@ -143,6 +156,7 @@ function computeVerdict(sources) {let weightedSupport = 0;let weightedContra = 0;+ let weightedPartial = 0;let totalWeight = 0;let stanceBearing = 0;@@ -154,10 +168,13 @@ function computeVerdict(sources) {} else if (s.stance === 'contradicts') {weightedContra += s.weight;stanceBearing++;+ } else if (s.stance === 'partial') {+ weightedPartial += s.weight;+ stanceBearing++;}}- const stanceWeight = weightedSupport + weightedContra;+ const stanceWeight = weightedSupport + weightedContra + weightedPartial;if (totalWeight === 0 || stanceWeight === 0) {return { verdict: 'insufficient', confidence: 0.3 };}@@ -169,6 +186,7 @@ function computeVerdict(sources) {const supportRatio = weightedSupport / stanceWeight;const contraRatio = weightedContra / stanceWeight;+ const partialRatio = weightedPartial / stanceWeight;const confidence = (dominance) =>Math.round(Math.min(0.98, dominance * (0.6 + 0.4 * Math.min(1, coverage * 2))) * 100) / 100;@@ -178,7 +196,12 @@ function computeVerdict(sources) {if (contraRatio >= 0.7) {return { verdict: 'contradicted', confidence: confidence(contraRatio) };}- return { verdict: 'mixed', confidence: confidence(Math.max(supportRatio, contraRatio)) };+ // Neither side owns the evidence. How strongly is that established? Weight+ // that says "partly true" states it outright; a pair of opposed stances states+ // it jointly, so the smaller side counts twice (its mirror on the other side+ // is the other half of the same fact about the evidence).+ const mixedness = Math.min(1, partialRatio + 2 * Math.min(supportRatio, contraRatio));+ return { verdict: 'mixed', confidence: confidence(mixedness) };}// ── Core fact-check pipeline ───────────────────────────────────────────────────@@ -516,7 +539,7 @@ const OUTPUT_SCHEMA = {url: { type: 'string' },title: { type: 'string' },excerpt: { type: 'string' },- stance: { type: 'string', enum: ['supports', 'contradicts', 'neutral'] },+ stance: { type: 'string', enum: ['supports', 'contradicts', 'partial', 'neutral'] },weight: { type: 'number' },retrievedAt: { type: 'string', format: 'date-time' },},@@ -538,7 +561,7 @@ const OUTPUT_SCHEMA = {url: { type: 'string' },description: { type: ['string', 'null'] },visibleText: { type: ['string', 'null'] },- stance: { type: 'string', enum: ['supports', 'contradicts', 'neutral'] },+ stance: { type: 'string', enum: ['supports', 'contradicts', 'partial', 'neutral'] },reason: { type: ['string', 'null'] },provider: { type: 'string' },},@@ -669,4 +692,8 @@ export default wrap(async function handler(req, res) {}});-export { parseFactCheckBody as _parseFactCheckBody, checkClaim as _checkClaim };+export {+ parseFactCheckBody as _parseFactCheckBody,+ checkClaim as _checkClaim,+ computeVerdict as _computeVerdict,+};diff --git a/docs/agent-identities.md b/docs/agent-identities.mdindex 2f63d34e3..9f1f050de 100644--- a/docs/agent-identities.md+++ b/docs/agent-identities.md@@ -4,7 +4,7 @@ Every AI agent deserves a face. The Agent Identity Studio takes an agent's namePage: [/agent-identities](https://three.ws/agent-identities) (the showcase) · Endpoint: `https://three.ws/api/okx/3d/identity-studio`-> The buyer-facing contract for this service (price, the payment challenge and replay flow, the payment guarantees, the rails it settles on) lives in [OKX.AI Marketplace Services](./okx-marketplace.md#agent-identity-studio-150-per-identity). This document is the other half: what the pipeline actually does between the brief and the deliverables, what the showcase page renders, and the shape of the job API. Read the marketplace doc first if you are buying; read this one if you are building on it or changing it.+> The buyer-facing contract for this service (price, the payment challenge and replay flow, the payment guarantees, the rails it settles on) lives in [OKX.AI Marketplace Services](./okx-marketplace.md#back-burner). This document is the other half: what the pipeline actually does between the brief and the deliverables, what the showcase page renders, and the shape of the job API. Read the marketplace doc first if you are buying; read this one if you are building on it or changing it.## Why it existsdiff --git a/docs/nvidia-visibility-map.md b/docs/nvidia-visibility-map.mdindex 5b41e2c10..48b7f0a93 100644--- a/docs/nvidia-visibility-map.md+++ b/docs/nvidia-visibility-map.md@@ -183,6 +183,16 @@ Write it against [api/_lib/a2f-nvidia.js](../api/_lib/a2f-nvidia.js) andbehind it, and follow the house rule the existing two follow: real numbers,real latencies, no marketing voice.+**It is written: [nvidia-forum-browser-digital-human.md](./nvidia-forum-browser-digital-human.md)** (drafted+2026-09-02). It covers the NVCF bidirectional stream, the 44.1 kHz to 16 kHz+resampling contract and why playback must use the original audio, the derived+blendshape path that lets a VRM or Oculus-viseme rig lip-sync from an ARKit-52+track, the double-stacking and 30-to-60 fps interpolation bugs that only appear+on real uploads, and the function-id rotation that took the lane down once.+Latencies in it were measured against the live endpoint the day it was written,+not estimated. It is owner-gated under the external-channel rule: paste and post+when approved.+## Benefits we are entitled to and have never requestedStraight from NVIDIA's [Inception program page](https://www.nvidia.com/en-us/startups/).diff --git a/docs/ops/agent-index.md b/docs/ops/agent-index.mdindex b136689c2..7316f2bb8 100644--- a/docs/ops/agent-index.md+++ b/docs/ops/agent-index.md@@ -9,8 +9,11 @@ it, and both are crons:| EVM (secondary) | `/api/cron/erc8004-crawl` | 15 min | `erc8004_crawl_cursor` | `erc8004CrawlChain` in `api/cron/[name].js` |The Solana cron does two things in one tick: the attestation crawl first, then-`solanaEventSweep()`, which is the half that fills `agent_event_cursor`. Its-batch is `SOLANA_SWEEP_BATCH` and its wall-clock budget is `SOL_EVENT_BUDGET_MS`.+`sweepAgentEvents()`, which is the half that fills `agent_event_cursor`. Its+batch, its worker pool and its wall-clock budget are `SOLANA_SWEEP_BATCH`,+`SOLANA_SWEEP_CONCURRENCY` and `SOLANA_SWEEP_BUDGET_MS`, all three exported from+`api/_lib/solana-agent-events.js` beside the crawl they bound, because the+freshness sensor derives the index's cycle time from those same constants.The freshness sensor is `api/_lib/ops/index-lag.js`. It reports on`/api/healthz` and `/status` as `agent_index`, and reads only the cursor tables:@@ -30,7 +33,10 @@ same bug on both chains, and it is silent by construction:retention, so a cursor written by one lane is regularly unreadable by the next.- EVM resumes at `last_block + 1`. A provider that has pruned that height answers`History has been pruned for this block`, and no smaller window fixes it,- because the data is gone rather than the request being too wide.+ because the data is gone rather than the request being too wide. A keyless node+ that serves recent blocks and answers older ones with+ `Archive requests require a personal token` has drawn the same wall behind a+ paywall, so `isPrunedHistoryRejection()` treats both as retention.In both cases the cursor is only written on the success path, so the next tickpresents the same dead value and gets the same error, forever. Nothing pages:@@ -42,6 +48,26 @@ Both legs now recover on their own:and `isPrunedHistoryRejection()` skips the EVM cursor forward to the head. Bothare safe to replay, because every row lands through `on conflict do nothing`.+Two things had to change before the EVM half could actually fire. `erc8004RpcCall`+now reads the JSON-RPC body **before** the HTTP status, because the providers that+gate archive ranges answer with a real error message under a 403 and throwing on+the status alone reduced it to `HTTP 403 from <host>`, which no predicate can+classify. And it now surfaces a retention diagnosis from **any** lane rather than+whichever error the LAST lane happened to return: on 2026-09-02 one chain's first+lane said plainly that the blocks were pruned while its final lane answered a+generic `limit exceeded`, the crawl saw only the second, and the chain sat stale+for eight days.++Skipping the wall closes the backlog, which is exactly why the skipped span is+banked on the cursor rather than only reported in the cron response: the moment+the cursor reaches the head the chain reports zero blocks behind and reads as+healthy. `erc8004_crawl_cursor.history_gap_blocks` accumulates every block the+crawl gave up on, `history_gap_to` names where the newest skip resumed, and+`history_gap_at` when. The sensor reports the total (`evm.historyGapChains`,+`evm.historyGapBlocks`) and deliberately never scores it: the gap is history that+is already lost, and scoring it would pin the subsystem red over something no+tick can fix. Only an archive provider for that chain can backfill it.+## Diagnose in three reads```sh@@ -73,10 +99,10 @@ gcloud logging read 'resource.type="cloud_run_revision" resource.labels.service_| `solana rpc provider error -16401 @ <host>` | The lane gates this method behind a paid tier. | Per-method capability routing in `api/_lib/solana/connection.js`. Add the method to that lane's blocked set. || `fetch failed (…) @ <host>` | Transport fault on one lane. | Transient. Persistent means the lane is dead: drop it. || `agent_ref is not a Solana account key` | A directory row whose ref is not an account. | Never crawlable. It is recorded once rather than retried every tick. |-| EVM `has been pruned` | The provider dropped the blocks the cursor points at. | Self-healing: the crawl resumes at the head and reports the skipped span as `prunedSkip`. That span is a permanent gap; only an archive node can backfill it. |+| EVM `has been pruned` / `Archive requests require a personal token` | The provider will not serve the blocks the cursor points at, whether it dropped them or paywalled them. | Self-healing: the crawl resumes at the head, reports the skipped span as `prunedSkip`, and banks it in `history_gap_blocks`. That span is a permanent gap; only an archive node can backfill it. || EVM `block range` / `response size` / `query returned more than` | The window was too wide. | Self-healing: `backoffChunkSize()` halves it in place and the width is persisted in `chunk_size`. || EVM `limit exceeded` | A plan or compute limit, **not** a range ceiling. | Shrinking does not help. Deliberately excluded from `isRangeRejection`. |-| EVM `HTTP 403 from <host>` | The last-resort keyless lane refused us. | Not recoverable in code. The chain needs a lane that answers from a datacenter IP; see the `rpcUrls` note in `api/_lib/erc8004-chains.js`. |+| EVM `HTTP 403 from <host>` | A lane refused us with no readable JSON-RPC body. | The body is read first now, so a bare status here means the lane returned nothing to classify. The chain needs a lane that answers from a datacenter IP; see the `rpcUrls` note in `api/_lib/erc8004-chains.js`. |## Recovery: drain a wedged backlog now@@ -101,6 +127,7 @@ that is months behind changes nothing they can see.| Solana cursors carrying an error | `SOLANA_ERROR_RATE_DEGRADED` | `SOLANA_ERROR_RATE_DOWN` || EVM worst cursor age | `EVM_LAG_DEGRADED_MIN` | `EVM_LAG_DOWN_MIN` || EVM worst backlog | `EVM_BLOCKS_BEHIND_DEGRADED` | `EVM_BLOCKS_BEHIND_DOWN` |+| EVM permanent history gap | reported only | reported only |Read the numbers from `index-lag.js`; they are exported so nothing has to quotethem. Two rules shape the verdict:@@ -120,10 +147,35 @@ rather than against a live database.## Sweep cycleA queue drained oldest-first sits at half its cycle time, so the median lag is-`sweepCycleMin(agents) / 2`. `sweepCycleMin()` derives the cycle from-`SOLANA_SWEEP_BATCH` and `SOLANA_SWEEP_PERIOD_MIN`, which means a directory that-outgrows its batch shows up as a number on the status surface instead of as an-unexplained median. Raising the batch costs one `getSignaturesForAddress` per-agent per tick; the real ceiling is `SOL_EVENT_BUDGET_MS`, not the constant, and-the sweep reports `truncated: true` when it runs out of budget mid-batch. Check+`sweepCycleMin(agents) / 2`, and the OLDEST agent waits a whole cycle. Both+numbers matter: a cycle longer than `SOLANA_LAG_DEGRADED_MIN` means part of the+directory is always stale by the sensor's own definition, even when the median+looks fine. `sweepCycleMin()` derives the cycle from `SOLANA_SWEEP_BATCH` and+`SOLANA_SWEEP_PERIOD_MIN`, so a directory that outgrows its batch shows up as a+number on the status surface instead of as an unexplained median.++The batch, not the budget, was the cap. Measured against the live lane router on+2026-09-02, one agent costs about 370 ms end to end, so a 120-second budget+drains roughly 320 agents serially and far more through the worker pool, while+the sweep was taking 120 per tick and leaving three quarters of its tick idle.+The 1,604-agent directory therefore cycled in 140 minutes against a 90-minute+threshold. Re-sizing it is a two-constant decision:++```+sweepCycleMin = ceil(agents / SOLANA_SWEEP_BATCH) * SOLANA_SWEEP_PERIOD_MIN+```++Keep that at or under `SOLANA_LAG_DEGRADED_MIN` with headroom for the directory+to grow, and keep `SOLANA_SWEEP_BATCH * 0.37s / SOLANA_SWEEP_CONCURRENCY` well+inside `SOLANA_SWEEP_BUDGET_MS`. `tests/agent-index.test.js` asserts both the+cycle and the concurrency ceiling, so an over-large batch fails the suite rather+than quietly truncating in production.++Concurrency is deliberately small. Every agent is one `getSignaturesForAddress`+plus its transaction reads, so the sweep spends nearly all its wall clock waiting+on the RPC and a small pool converts that into throughput; a wide fan-out earns+429s from the shared lanes faster than it earns signatures, and those show up+immediately in the sensor's error rate. The sweep reports `truncated: true` when+the budget runs out mid-batch, which is the signal that the batch has finally+outgrown the budget and the sensor's cycle number has become optimistic. Checkthat flag before raising the batch again.diff --git a/scripts/check-browser-graph.mjs b/scripts/check-browser-graph.mjsindex e9017d8c0..ec45a0351 100644--- a/scripts/check-browser-graph.mjs+++ b/scripts/check-browser-graph.mjs@@ -215,7 +215,9 @@ function configEntries() {const block = /\n\t*input: \{\n([\s\S]*?)\n\t*\},\n/.exec(config);if (!block) return [];const out = [];- for (const m of block[1].matchAll(/resolve\(__dirname, '([^']+)'\)/g)) {+ // Whitespace-tolerant: a formatter wrapping one long entry across lines must+ // not quietly drop that page's module graph from the walk.+ for (const m of block[1].matchAll(/resolve\(\s*__dirname,\s*'([^']+)'\s*,?\s*\)/g)) {const abs = resolve(ROOT, m[1]);if (existsSync(abs)) out.push([abs, `vite.config.js input: ${m[1]}`]);}diff --git a/scripts/migrate-plaintext-secrets.mjs b/scripts/migrate-plaintext-secrets.mjsindex f63db8f10..3653cb886 100755--- a/scripts/migrate-plaintext-secrets.mjs+++ b/scripts/migrate-plaintext-secrets.mjs@@ -162,6 +162,12 @@ export function classify(name) {if (publicSegment) return { secret: false, reason: `public identifier (${publicSegment})` };const secretSegment = segments.find((s) => SECRET_SEGMENTS.has(s));if (secretSegment) return { secret: true, reason: `credential-bearing name (${secretSegment})` };+ // A provider URL routinely carries its key in the query string (Helius, Alchemy,+ // QuickNode all do). The name cannot say whether this one does, so it is+ // surfaced for a human call instead of being silently filed as public config.+ if (/_(URL|URI|ENDPOINT|DSN)$/.test(name)) {+ return { secret: false, review: true, reason: 'URL: may embed a key in its query string' };+ }return { secret: false, reason: 'no credential marker in the name' };}@@ -224,6 +230,7 @@ function partition(env) {const alreadySecret = [];const credentials = [];const config = [];+ const review = [];for (const entry of env) {const name = entry.name;if (ONLY.length && !ONLY.includes(name)) continue;@@ -234,7 +241,7 @@ function partition(env) {const value = entry.value ?? '';const verdict = classify(name);if (!verdict.secret) {- config.push({ name, reason: verdict.reason });+ (verdict.review ? review : config).push({ name, reason: verdict.reason });continue;}if (!value) {@@ -243,7 +250,7 @@ function partition(env) {}credentials.push({ name, value, reason: verdict.reason, secretName: NAME_MAP.get(name) || defaultSecretName(name) });}- return { alreadySecret, credentials, config };+ return { alreadySecret, credentials, config, review };}async function secretExists(name) {@@ -357,7 +364,7 @@ async function main() {if (!before.serviceAccount) {fail(`${SERVICE} has no explicit runtime service account; refusing to guess who to grant access to`);}- const { alreadySecret, credentials, config } = partition(before.env);+ const { alreadySecret, credentials, config, review } = partition(before.env);console.log(`\nService: ${SERVICE} (${REGION}, ${PROJECT})`);console.log(`Runtime service account: ${before.serviceAccount}`);@@ -370,6 +377,11 @@ async function main() {console.log(`\nPlaintext, left as config (${config.length}):`);for (const e of config) console.log(` ${e.name} (${e.reason})`);+ if (review.length) {+ console.log(`\nPlaintext, needs a human call (${review.length}):`);+ for (const e of review) console.log(` ${e.name} (${e.reason}; --include ${e.name} to migrate it)`);+ }+console.log(`\nPlaintext credentials to migrate (${credentials.length}):`);for (const e of credentials) console.log(` ${e.name} -> ${e.secretName} (${e.reason})`);diff --git a/scripts/verify-routes.mjs b/scripts/verify-routes.mjsindex a5b5e0905..8c67a3ae3 100644--- a/scripts/verify-routes.mjs+++ b/scripts/verify-routes.mjs@@ -73,7 +73,11 @@ function walk(dir, base = dir, exts = null) {// Which pages/*.html actually reach dist: rollup inputs + dashboard-next glob + ibm copy.const viteSrc = readFileSync(resolve(ROOT, 'vite.config.js'), 'utf8');const viteInputs = new Set();-for (const m of viteSrc.matchAll(/resolve\(__dirname,\s*['"]([^'"]+\.html)['"]\)/g)) viteInputs.add(m[1]);+// Whitespace-tolerant on purpose: a formatter wrapping one long entry across+// lines used to drop it from this set, which reads downstream as a real 404 for+// a page the build actually emits (/events/build-3d-agents-live, 2026-09-02).+for (const m of viteSrc.matchAll(/resolve\(\s*__dirname,\s*['"]([^'"]+\.html)['"]\s*,?\s*\)/g))+ viteInputs.add(m[1]);const served = new Set(); // dist-relative file paths that will exist on diskfor (const f of walk(resolve(ROOT, 'pages'), resolve(ROOT, 'pages'), ['.html'])) {diff --git a/tests/audit-links-surfaces.test.js b/tests/audit-links-surfaces.test.jsindex dc5adcebb..99bc98fa4 100644--- a/tests/audit-links-surfaces.test.js+++ b/tests/audit-links-surfaces.test.js@@ -65,3 +65,50 @@ describe('link audit coverage', () => {expect(pkg.scripts.gate).toContain('audit:links');});});++// The audit's own classification rules. Each one below was a false positive the+// audit reported against correct code, and a false positive in a gate is not+// harmless: it trains everyone to read a red audit as noise, which is how a real+// dead link ships behind three fake ones. These pin the rules narrowly, so+// widening one into a blanket ignore fails here.+describe('link audit classification', () => {+ function source() {+ return readFileSync(SCRIPT, 'utf8');+ }++ it('exempts only build outputs that something actually writes', () => {+ const m = source().match(/const GENERATED_TARGETS = new Set\(\[([^\]]*)\]\)/);+ expect(m, 'audit-links.mjs must declare GENERATED_TARGETS').not.toBeNull();+ const targets = (m[1].match(/'([^']+)'/g) || []).map((t) => t.slice(1, -1));+ expect(targets).toContain('/build-info.json');+ // The exemption is a claim that the build emits the file. Hold it to the+ // script that makes the claim true, so a target cannot linger here after+ // whatever produced it is gone.+ const writer = readFileSync(join(ROOT, 'scripts', 'write-build-info.mjs'), 'utf8');+ expect(writer).toContain('build-info.json');+ });++ it('masks comments in the fetch scanner, like the two scanners beside it', () => {+ // A module header warning against a call pattern quotes that pattern. The+ // fetch scanner was the only extractor that never consulted the mask, so+ // src/api.js was reported as fetching the path its own comment says not to.+ const body = source().match(/fetchRe\.lastIndex = 0;[\s\S]*?\n\t\}/);+ expect(body, 'audit-links.mjs must scan fetch() calls').not.toBeNull();+ expect(body[0]).toContain('inComment(m.index)');+ });++ it('treats an empty object-literal href as absence, and a DOM assignment as a stub', () => {+ const m = source().match(/const jsNavRe = (\/.*\/[gimsuy]*);/);+ expect(m, 'audit-links.mjs must declare jsNavRe').not.toBeNull();+ const prefixOf = (code) => {+ const re = new RegExp(m[1].slice(1, m[1].lastIndexOf('/')), 'gi');+ return re.exec(code)?.[1] ?? null;+ };+ // The exemption keys off the prefix the regex captures, anchored at the+ // end, which is the whole reason it cannot swallow a DOM assignment.+ expect(source()).toMatch(/target === '' && \/href\\s\*:\$\/i\.test\(m\[1\]\)/);+ expect(prefixOf("{ href: '' }")).toMatch(/href\s*:$/);+ expect(prefixOf("el.href = ''")).not.toMatch(/href\s*:$/);+ expect(prefixOf("location.assign('')")).not.toMatch(/href\s*:$/);+ });+});diff --git a/tests/openapi-aggregator.test.js b/tests/openapi-aggregator.test.jsindex 3988d2888..1515b7633 100644--- a/tests/openapi-aggregator.test.js+++ b/tests/openapi-aggregator.test.js@@ -7,6 +7,7 @@import { describe, it, expect, beforeAll } from 'vitest';import openapiHandler from '../api/openapi-json.js';import { providerCatalog } from '../api/v1/_providers.js';+import { PAID_SERVICES } from '../api/_lib/service-catalog/services/index.js';function mockRes() {return {@@ -208,3 +209,112 @@ describe('GET /openapi.json — aggregator coverage', () => {expect(doc.info.license?.url || doc.info.license?.identifier).toBeTruthy();});});++describe('GET /openapi.json: paid service-catalog coverage', () => {+ let doc;++ beforeAll(async () => {+ const res = mockRes();+ await openapiHandler(mockReq(), res);+ doc = JSON.parse(res._body);+ });++ // The drift this closes: /openapi.json is what x402scan reads when it+ // registers an origin, and what AgentCash's validator reads to find payable+ // operations. Its /api/x402/* operations were hand-authored, so 24 of the+ // catalog's 75 live paid services had an entry and the rest were invisible+ // to both directories while answering a perfectly valid 402 in production.+ // Projecting them from the catalog fixed it; this keeps it fixed.+ it('covers every live paid service in the catalog', () => {+ const cdp = Boolean(process.env.CDP_API_KEY_ID && process.env.CDP_API_KEY_SECRET);+ let covered = 0;+ for (const service of PAID_SERVICES) {+ if (service.free || service.status !== 'live') continue;+ // Unpayable without CDP credentials, so deliberately unadvertised.+ if (service.acceptsBuilder === 'permit2-only' && !cdp) {+ expect(doc.paths[service.path]).toBeUndefined();+ continue;+ }+ const pathItem = doc.paths[service.path];+ expect(pathItem, `missing OpenAPI path for ${service.path}`).toBeTruthy();++ const operation = pathItem[service.method.toLowerCase()];+ expect(+ operation,+ `missing ${service.method} operation for ${service.path}`,+ ).toBeTruthy();+ expect(operation.responses?.['402'], `${service.path} documents no 402`).toBeTruthy();+ // Both halves are required together: AgentCash's+ // StructuredPaymentInfoSchema silently drops a price with no sibling+ // protocols and reports the operation as unpriced.+ expect(operation['x-payment-info']?.price, `${service.path} price`).toBeTruthy();+ expect(operation['x-payment-info']?.protocols, `${service.path} protocols`).toBeTruthy();+ covered += 1;+ }+ // Sanity: the catalog is not empty, which would make this vacuous.+ expect(covered).toBeGreaterThan(50);+ });++ it('prices every projected operation from the catalog, never a hand-copied number', () => {+ // Only fixed-price entries are compared to the catalog. Six hand-authored+ // operations quote a difficulty- or size-tiered price instead+ // (`mode: 'dynamic'` with min/max, e.g. vanity at $0.01 for one character+ // and $0.25 for three); the live 402 quotes the exact figure per request,+ // and the catalog's single priceAtomics is the floor, not the price. The+ // projection never overwrites a hand-authored operation, so those keep+ // their range and are asserted as a range.+ for (const service of PAID_SERVICES) {+ if (service.free || service.status !== 'live') continue;+ const operation = doc.paths[service.path]?.[service.method.toLowerCase()];+ if (!operation) continue;+ const price = operation['x-payment-info']?.price;+ expect(price, `${service.path} declares no price`).toBeTruthy();+ if (price.mode === 'dynamic') {+ expect(Number(price.min), `${service.path} dynamic min`).toBeGreaterThan(0);+ expect(Number(price.max), `${service.path} dynamic max`).toBeGreaterThanOrEqual(+ Number(price.min),+ );+ continue;+ }+ expect(+ Number(price.amount),+ `${service.path} price drift (declared ${price.amount})`,+ ).toBeCloseTo(Number(service.priceAtomics) / 1e6, 6);+ }+ });++ it('keeps every hand-authored operation exactly as written', () => {+ // The projection is spread before the hand-authored paths, so a route+ // with a richer hand-written entry keeps it. agent-reputation is one:+ // its typed uuid query parameter would be a plain string if the+ // projection had won.+ const handAuthored = doc.paths['/api/x402/agent-reputation']?.get;+ expect(handAuthored.operationId).toBe('x402_agent_reputation');+ const agentId = handAuthored.parameters.find((p) => p.name === 'agent_id');+ expect(agentId.schema.format).toBe('uuid');+ });++ it('projects GET inputs as query parameters and POST inputs as a request body', () => {+ const getOp = doc.paths['/api/x402/market-coin']?.get;+ expect(Array.isArray(getOp.parameters)).toBe(true);+ expect(getOp.parameters.some((p) => p.name === 'id')).toBe(true);+ expect(getOp.requestBody).toBeUndefined();++ const postOp = doc.paths['/api/x402/pipeline-rig']?.post;+ expect(postOp.requestBody?.content?.['application/json']?.schema?.properties?.glb_url).toBeTruthy();+ expect(postOp.requestBody.required).toBe(true);+ expect(postOp.parameters).toBeUndefined();+ });++ it('carries the JSON Schema required list onto the query parameters', () => {+ // token-intel's inputSchema requires `mint`; a projection that dropped the+ // required list would document every parameter as optional and agents+ // would call it without one.+ const parameters = doc.paths['/api/x402/token-intel'].get.parameters;+ expect(parameters.find((p) => p.name === 'mint').required).toBe(true);+ // market-coin requires nothing (id or contract, either one), so its+ // parameters must not be forced.+ const optional = doc.paths['/api/x402/market-coin'].get.parameters;+ expect(optional.every((p) => p.required === false)).toBe(true);+ });+});