koala73 / koala73/worldmonitor
feat(mcp): surface theater-posture source attribution to agent consumers (get_military_surge)
- Dominant language
- TypeScript
- Stars
- 86.6k
- Forks
- 13.1k
- Avg merge
- 8h 4m
- Merged PRs (30d)
- 825
Description
## Summary
PR #6092 (issue #5945 residual) made theater-posture publication attribute its actual source (`opensky` / `adsb.lol` / `wingbits` / `vessel-only`) on the operator surfaces: authenticated relay `/metrics` (`theaterPosture.lastRun` + `sourceCountsSinceBoot`), `seed-meta:theater-posture` (`sourceVersion` + `producer`), and the relay log line.
The **canonical payload** written to `theater-posture:sebuf:v1` is still `{ theaters }` with no source field. `server/worldmonitor/military/v1/get-theater-posture.ts` returns it verbatim, and the MCP tool `get_military_surge` consumes it via `readCachesWithFreshness`, whose freshness envelope carries only `cached_at`/`stale`/`unavailable_inputs` — `sourceVersion` from seed-meta is discarded for every tool.
Net effect: an on-call human reading `/metrics` can discount a single-flight Wingbits-fallback posture reading; an agent calling `get_military_surge` gets the identical posture assessment with zero signal that it came from degraded single-flight fallback rather than a comprehensive OpenSky read. The #5945 misattribution risk is closed for humans but remains open one hop downstream on the only surface an LLM reasons over.
## Proposed scope
- Add `sourceVersion` (and optionally `flightCount`) alongside `theaters` in the theater-posture canonical payload (additive; both writers).
- Forward it through `get-theater-posture.ts` and surface it in `get_military_surge`'s output schema so agent consumers can flag or discount degraded-source readings.
- Respect the API-contract gates (sebuf schema, MCP parity tests, stats/docs registries) — this is why it was split out of #6092 rather than folded in.
## Acceptance
- [ ] Canonical theater-posture payload carries source attribution from both writers (relay loop + seed-military-flights).
- [ ] `get_military_surge` (and `get-theater-posture`) expose it in their response schema.
- [ ] A test proves a Wingbits-fallback cycle is distinguishable from an OpenSky cycle through the MCP tool response.
Related: #5945, PR #6092. Found by the agent-native lens during #6092's multi-agent review.
https://claude.ai/code/session_01ENW1FZgjbDCbVKBkcaLr79
Contributor guide
Research direction
Start with server/worldmonitor/military/v1/get-theater-posture.ts and trace the theater-posture:sebuf:v1 payload through both writers into get_military_surge. Read the sebuf schema, MCP parity tests, and stats/docs registries before changing the response shape. Done means both writers preserve source attribution and a test distinguishes Wingbits fallback from OpenSky through the MCP response.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, backend-api-design, testing
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100