[docs] hero_indexer docs/specs.md advertises methods missing from dispatcher #21

New issue

Open

opened 2026-05-01 04:09:28 +00:00 by mik-tf · 0 comments

mik-tf commented

2026-05-01 04:09:28 +00:00

Owner

Summary

hero_indexer/docs/specs.md advertises methods that are not present in the actual JSON-RPC dispatcher. Either the spec is aspirational (then mark planned/unimplemented) or the handlers are missing (then implement). Pick one source of truth before agent / docs grounding diverges from code.

Source

docs/specs.md advertises:
- doc.update
- index.merge
- aggregations
- search.explain
crates/hero_indexer_server/src/server/handlers.rs:42-66 — does not dispatch any of these.

Why this matters

docs_hero Phase 1 grounds the AI Assistant on capability pages. If the page references doc.update because specs.md claims it, the agent will hallucinate that method to users. Same risk for any third party reading the spec to integrate.

Proposed fix

Pick one:

Option A (mark aspirational) — add a "Status: planned / not yet implemented" badge to each method that isn't in the dispatcher. Cleanest if the methods are roadmap.
Option B (implement) — add the missing methods to the dispatcher. Larger surface; only worth it if there's a real use case.

Severity

Low (docs accuracy + agent hallucination risk).

Cross-refs

Sister sovereignty issue on the same repo (hero_indexer discards X-Hero-Context, this session)

Spotted during docs_hero Phase 1 source-grounded read (session 52). Reconciliation memo: memory/investigation_roadmap_reconciliation.md.

## Summary `hero_indexer/docs/specs.md` advertises methods that are not present in the actual JSON-RPC dispatcher. Either the spec is aspirational (then mark planned/unimplemented) or the handlers are missing (then implement). Pick one source of truth before agent / docs grounding diverges from code. ## Source - [`docs/specs.md`](https://forge.ourworld.tf/lhumina_code/hero_indexer/src/branch/development/docs/specs.md) advertises: - `doc.update` - `index.merge` - aggregations - `search.explain` - [`crates/hero_indexer_server/src/server/handlers.rs:42-66`](https://forge.ourworld.tf/lhumina_code/hero_indexer/src/branch/development/crates/hero_indexer_server/src/server/handlers.rs) — does not dispatch any of these. ## Why this matters docs_hero Phase 1 grounds the AI Assistant on capability pages. If the page references `doc.update` because `specs.md` claims it, the agent will hallucinate that method to users. Same risk for any third party reading the spec to integrate. ## Proposed fix Pick one: - **Option A (mark aspirational)** — add a "Status: planned / not yet implemented" badge to each method that isn't in the dispatcher. Cleanest if the methods are roadmap. - **Option B (implement)** — add the missing methods to the dispatcher. Larger surface; only worth it if there's a real use case. ## Severity Low (docs accuracy + agent hallucination risk). ## Cross-refs - Sister sovereignty issue on the same repo (`hero_indexer` discards `X-Hero-Context`, this session) Spotted during docs_hero Phase 1 source-grounded read (session 52). Reconciliation memo: `memory/investigation_roadmap_reconciliation.md`.