feat(swarm): GET /swarm/lessons/{id}/proof endpoint — sub-phase 4e (#105)

[Dewinator]

Summary

Lands the §4.6 Merkle-inclusion-proof endpoint and the receiver-side rules 17 + 18 validator. Sits on top of the producer-side substrate (migration 077, sub-phase 4e substrate) and the 4c evidence-merkle module — receivers can now verify a Lesson's evidence_root commitment without ever seeing raw episode content.

• mcp-server/src/swarm/endpoints/lesson-proof.ts — buildLessonProofResponse async handler with the full 200/404/410/503/400 status mapping per §4.6, dependency-injected so tests exercise the full path without Supabase or the on-disk node key. Relay guard fires before loadLeaves — even if leaves are locally cached, a non-origin node never signs an envelope.
• mcp-server/src/services/evidence-merkle.ts — two new exports (computeRootFromHashedLeaves, buildInclusionProofFromHashedLeaves) that reuse the producer's algorithm verbatim instead of duplicating the Merkle math. Avoids the divergence surface that would let producer-vs-endpoint drift silently break every receiver's rule 18 check.
• mcp-server/src/services/wire-validator.ts — new validateLessonProof covering rules 17 + 18 plus presence/type, spec_version major (rule 1), envelope signature against the producer's Ed25519 key (rule 5), signed_at future bound (rule 7), and an evidence_count shape pin so a 0/0 envelope cannot slip past rule 17. Separate entry point from validateWireRecord because a proof is the answer to a §4.6 challenge, not a wire record that gets ingested.

Privacy invariant (Designprinzip 2)

Substrate stores only hashed leaves, so the response naturally contains no raw experience IDs. The contract test scans the response body for any UUID-shaped substring other than lesson_id AND for any of the (UUID-shaped) raw experience IDs the fixture used to build the tree — both are forbidden by Designprinzip 2.

Out of scope for 4e

• Reputation decay arithmetic on rule 17/18 failure → 4f territory
• Top-level HTTP router wiring → no router exists in this repo yet (node-advertisement.ts has the same handler shape; both will be wired together once the router lands)
• Per-leaf proof caching keyed on useful_count increments → perf TODO; spec says MAY
• Cross-reference proof.evidence_root vs the stored lesson row's evidence_root → lives in the receiver's ingest path

Test plan

• npm run build — TypeScript clean
• npm test — 568/569 tests pass; the single failure is the pre-existing migration-074 test that depends on PR feat(swarm): prev_lesson_hash chain table — sub-phase 4d (#104) #119 landing first (074_lesson_chain.sql is not on main yet, unrelated to this PR)
• lesson-proof-endpoint.test.ts — 1-/2-/5-/7-leaf round-trip against a real node:http server with full envelope verification; 404 (not held); 410 (published-then-forgotten); 404 (relay guard); 503 (no self-identity, missing substrate, malformed leaf); 400 (non-UUID id); privacy contract scan
• wire-validator.test.ts — 10 new tests for validateLessonProof covering rules 1, 2, 3, 5, 7, 16, 17, 18-tampered-path, 18-wrong-root + happy path

Closes part of #105.

🤖 Generated with Claude Code

[Dewinator]

Cross-PR collision flag — autonomous tick 2026-04-30 (post-#131).

This PR and #119 both modify mcp-server/src/__tests__/wire-validator.test.ts and mcp-server/src/services/wire-validator.ts. Re-ran the merges in scratch worktrees against current main:

Pair	wire-validator.ts	wire-validator.test.ts
#119 → #128	auto-merge clean	CONFLICT at line 638 (textual only)
#128 → #119	auto-merge clean	CONFLICT at line 638 (textual only)

The .ts file auto-merges because the two PRs touch disjoint regions of the file: #119 inserts the rule-19 block inside validateWireRecord (before the final return { ok: true }), while this PR appends validateLessonProof after the function close. No semantic overlap.

The .test.ts conflict is a pure mechanical "two appends to the same anchor" — both PRs add a fresh block after the existing line 638 (v1.1 Lesson with prev_lesson_hash = null test). Neither block depends on the other's tests. Resolution = keep both blocks in either order.

Recommendation: land #119 first (it's been waiting longer and was already rebased after #123). Then rebase this PR; the resolution is mechanical:

1. git rebase main after feat(swarm): prev_lesson_hash chain table — sub-phase 4d (#104) #119 lands
2. On the wire-validator.test.ts conflict, the imports at the top auto-merge (feat(swarm): prev_lesson_hash chain table — sub-phase 4d (#104) #119 doesn't touch them, this PR adds validateLessonProof + evidence-merkle helpers). Only the trailing-append region needs a one-line resolution: keep this PR's validateLessonProof block, then either before or after feat(swarm): prev_lesson_hash chain table — sub-phase 4d (#104) #119's rule-19 block — both orderings produce identical test runs.
3. No wire-validator.ts work needed (auto-merges).
4. Migration order is naturally clean — feat(swarm): prev_lesson_hash chain table — sub-phase 4d (#104) #119 owns 074, no migration here.

Verified via git merge-tree --write-tree: every other pairwise combination of the five open PRs (#119, #128, #129, #130, #131) merges cleanly, so this is the only collision left in the open queue.