feat(swarm): outbound /swarm/lessons feed handler — substrate (#139)

[Dewinator]

Summary

First slice of issue #139 — pure handler module + 32 contract tests for the §10.6 outbound broadcast feed (GET /swarm/lessons?since=…&limit=…). Mirrors the #138 / #154 substrate-vs-wiring split.

• mcp-server/src/swarm/endpoints/lesson-feed.ts — pure response builder. The loader is injected so contract tests run with no DB / HTTP.
• mcp-server/src/__tests__/lesson-feed.test.ts — 32 tests covering input validation, defaulting, clamping, cursor math, and shape-pin regression guards.

Status mapping

• 400 — malformed since (must be ISO8601 with timezone) or malformed limit (must be an integer; clamped silently if outside [1, 200], rejected if non-numeric / decimal / NaN).
• 503 — loader threw; operator-readable detail field in the body.
• 200 — { lessons: Lesson[], next_since: string | null }. next_since = max(signed_at) + 1ms; null on empty page.

Substrate filter contract

Documented on the loader signature: it MUST read FROM swarm_lessons_broadcast_eligible (the §10.6 firebreak view from migration 078) AND apply local_weight >= 0.3 (the §10.4 anti-echo-chamber filter from migration 082). The handler deliberately does NOT re-filter — the substrate IS the contract; the integration test that verifies this lands with the wiring PR.

Privacy invariant

Rows are relayed verbatim — the handler never re-signs. Re-signing would let any node forge producer attestations for lessons it has merely seen (the same trust break the proof handler's relay-guard prevents at §4.6).

Out of scope (issue #139 pieces 2 + 3)

• Active publish at REM B→A promotion (lesson_chain append + producer-side signing). Depends on feat(swarm): wire producer-side lesson_chain hook into record_lesson #136 producer hook.
• Self-broadcast safety CHECK / trigger preventing a self-row from carrying a foreign-looking origin_node_id.
• HTTP wiring into dashboard-server.mjs — follow-up PR (mirror of feat(swarm): GET /swarm/lessons/{id}/proof endpoint — sub-phase 4e (#105) #128 → feat(swarm): wire GET /swarm/lessons/{id}/proof into dashboard-server (#105) #152).

Test plan

• npm test — 678 pass (baseline 646; this PR adds 32 tests)
• tsc --build clean
• Reed merges; integration test ships with the wiring PR

🤖 Generated with Claude Code

[Dewinator]

Peer audit — substrate is solid, two follow-up flags for the wiring PR

Read the handler + tests and ran the contract suite locally on the PR branch (32 pass, 0 fail, tsc --noEmit clean). Probed five edge cases the test file doesn't pin explicitly. Conclusion: this slice is mergeable as-is; the two notes below belong on the wiring PR's checklist, not on this one.

What I verified

• npm test for lesson-feed.test.ts only — 32/32 green on the PR branch.
• npx tsc --noEmit from mcp-server/ — clean.
• The handler is genuinely pure: the loader is the sole I/O surface, all clock reads route through deps.now, and the response is deterministic given the inputs.

Edge cases I probed (all behave as the docstrings claim)

Probe	Result	Verdict
computeNextSince over a page where every row has malformed signed_at	null	At-least-once cursor degrades to "stay put" — receiver re-polls with the same since, no progress, no crash. Matches the empty-page contract.
Two rows with identical signed_at	cursor advances +1ms past both	Documented at-least-once: the tied second row is intentionally not re-served. Receiver-side dedup is its own concern.
resolveLimit(1.0)	{ ok: true, limit: 1 }	Number.isInteger(1.0) === true — float literals that are integer-valued are accepted, as one would hope.
since=2026-04-30T10:20:30+00:00	accepted	Strict +HH:MM form passes the regex.
since=2026-04-30T10:20:30+0000	rejected (400)	Compact ±HHMM form is rejected by the regex (it requires a colon). Conservative, but worth a glance below.
since=2026-04-30T10:20:30.123456Z (microseconds)	accepted, truncated to ms	JS Date only carries ms precision; sub-ms suffix is dropped. Harmless given the cursor is also ms-precision.

Two flags for the wiring PR — not blockers here

1. +0000 rejection is stricter than RFC 3339 §5.6. The regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z\|[+-]\d{2}:\d{2})$ rejects the ±HHMM variant. Date.parse would actually accept it. If a future peer client emits the compact form (Go's time.RFC3339 notably does not, but some Python emitters do), it would 400 here. Decision is fine — strict is safer than permissive — but the wiring PR's HTTP integration test should probably include a +0000 row in the "expected 400" fixture so a later loosening is loud.

2. Substrate filter contract is doc-only on this side. The handler explicitly trusts the loader to (a) read FROM swarm_lessons_broadcast_eligible and (b) apply local_weight >= 0.3. Forgetting either leaks Tier-B lessons or §10.4-dampened ones across the wire — both are silent failures of the privacy/diversity model, no exception, no log line. The doc names this as "the substrate IS the contract; this module verifies shape only," which is the right call for a slice 1 of 3. But the wiring PR should land an integration test that:

   • Inserts one Tier-B lesson + one diversity-dampened Tier-A lesson + one clean Tier-A lesson, all signed_at within the lookback window
   • GETs /swarm/lessons with default params
   • Asserts only the clean Tier-A row appears in the page

The exported MIN_LOCAL_WEIGHT_FOR_BROADCAST = 0.3 constant being importable from this module is the right shape for that test — single source of truth across loader and assertion.

Privacy invariant — verbatim relay

The shape-pin test (top-level keys = ["lessons", "next_since"] only) plus the verbatim-relay test (v1.1 lesson with all optional fields round-trips byte-faithfully through the handler) together cover the §4.6 trust break. JSON.stringify preserves insertion order and the handler never re-shapes a row, so JCS-signed envelopes survive. Confirmed — no rebuild risk.

Net

Substrate is correct, well-tested, and matches the substrate-vs-wiring split that worked for #138 → #154 and #128 → #152. Approving from a peer-review perspective; the two flags above are wiring-PR concerns. No changes requested on this PR.