feat(X402-41): ADR-004 — v0.3.2 scope + JSON API stability + facilitator-aware verdict semantics

[fardinvahdat]

Summary

X402-41 — first ticket in the v0.3.2 cycle. Pure docs. Locks 3 architectural pillars in DECISIONS.md before D.x implementation begins:

1. Verdict taxonomy extension — new top-level upstream_stuck composite for stalled-indexer cases (Max precedent). Rolls up to exit code 3 to preserve the CI integration contract.
2. JSON API stability commitment — snapshot tests + src/bazaar/json-api.md + versioning rule (additive minor, renames major) + ### JSON API CHANGELOG discipline. @TomSmart_ai's mapper integration depends on shape stability.
3. Facilitator-aware verdict semantics — non-CDP services produce not_applicable_non_cdp states in D.2/D.3 → composite looks_correct (WAI), NOT upstream_issue. Pillar 3 derives from @Cryptor+@ferj correction (2026-05-21) establishing Bazaar indexing is CDP-only by design.

X402-37's historical reservation of "ADR-004" (stretch SLA-breach, never started) is superseded; renumber to next available ADR when/if X402-37 goes active.

Scope

• DECISIONS.md only: append ADR-004 (106 lines) after ADR-003, before the closing ---
• Pure docs; no code changes; no test changes; no dep changes

Strict audit gate — abbreviated (user-in-review-loop mode per ADR-003)

• Stage 1 pre-work: branched off origin/main HEAD; .gitignore WIP on branch but NOT staged (hard rule docs(X402-8): SPEC.md v0.1 — implements the wedge from ADR-001 #7 preserved)
• Stage 2 implementation: ADR-004 covers all 3 pillars + X402-37 collision note + 8-ticket layout reference
• Stage 3 correctness: ✅ typecheck clean; ✅ lint+prettier clean; ✅ 429 tests pass + 4 skipped (v0.3.1 baseline); ✅ build clean; ✅ check:publish-surface 96 files / 352 KB / 0 devDep imports (under 400 KB cap)
• Stage 4 edge cases: JSON API snapshot path no collision (will be created in X402-44); ADR sequence clean 001→004; final --- separator preserved; memory [[bazaar-indexing-spec]] + [[listing-readiness-framing]] both exist + updated today with CDP-only correction; all 8 Jira IDs + 3 PR IDs + 2 upstream issue IDs verified; em-dashes match ADR-003 style; only DECISIONS.md staged (.gitignore WIP not staged)
• Stage 5 gap check: vs X402-41 AC — all 5 AC items satisfied; the 3rd pillar (facilitator-aware) was added during Batch 4 review and is folded in as a co-equal pillar; 8 risks + 5 rejected alternatives documented
• Stage 6 ship: this PR; awaiting maintainer merge per [[user-merges-prs-themselves]] discipline

Test plan

• Markdown renders correctly on GitHub (links resolve, formatting clean)
• All cited Jira ticket numbers (X402-37, X402-41, X402-43, X402-44, X402-46, X402-48) link to real tickets
• PR + upstream issue citations (fix(parse): v2 challenge bodies with canonical v2 field names (#65) #66, fix: timeout bazaar-check HTTP probes #67, fix(bazaar): validate extensions.bazaar.{name,description} in manifest (#65 finding 2) #70, #1875, #2207) all real
• Notion v0.3.2 plan referenced via memory; ADR self-contained for offline reading
• No mainnet RPC URLs introduced (hard rule feat(X402-3): dogfood x402 server + client on Base Sepolia #2)
• One thing per PR — pure DECISIONS.md ADR-004 append (hard rule docs(X402-8): SPEC.md v0.1 — implements the wedge from ADR-001 #7)

What unblocks on merge

Per the dependency graph (10 Blocks links wired):

• X402-42 (D.4 --endpoint) — parallel-safe start
• X402-43 (D.5 variant-aware extensions.bazaar) — parallel-safe start
• X402-44 (JSON API stability) — parallel-safe start

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
x402trace-dogfood	Ready	Preview, Comment	May 22, 2026 8:17pm