docs: state the grounding bound as the per-server one it is #923

Merged

coilysiren merged 1 commit from issue-858-grounding-bound-per-server into main

2026-08-17 19:11:48 +00:00

coilyco-ops commented

2026-08-17 19:03:30 +00:00

Member

Takes the issue's first option: doc follows code.

Verified before writing

readGrounding is called at mcp.go:194, inside the per-server loop, and budget := maxGroundingBytes sits inside readGrounding itself. maxGroundingDocuments is checked in the same loop. Both reset per connected server. The issue's reading is correct.

Why doc follows code

The issue says option 1 is sufficient "if the per-server shape is what was intended". It is: the bound exists so one large catalogue cannot crowd out the turn, and per server is exactly what stops one server flooding. A turn-wide budget would be a different property.

Code follows doc is not taken. Threading one budget through the server loop changes runtime behaviour and needs the per-server fairness question answered first, since a first-listed server could consume the whole budget and starve the rest. Nothing is near either bound today, so that decision does not have to be made under pressure, and this change does not foreclose it.

What a reader now sees

The scope is stated in the three places someone might start from: docs/sirens-echo-mcp.md with the roster-wide worst case beside it, readGrounding's doc comment, and the line that initialises the budget.

No test

The fix is a corrected sentence. A test asserting the doc's wording would restate configuration, which AGENTS.md rules out, and a behavioural test would need a two-server MCP fixture to assert behaviour nobody is changing.

The page was at its 8,000-char cap, so three restatements elsewhere on it were compressed to make room.

closes #858

Takes the issue's first option: doc follows code. ## Verified before writing `readGrounding` is called at `mcp.go:194`, inside the per-server loop, and `budget := maxGroundingBytes` sits inside `readGrounding` itself. `maxGroundingDocuments` is checked in the same loop. Both reset per connected server. The issue's reading is correct. ## Why doc follows code The issue says option 1 is sufficient **"if the per-server shape is what was intended"**. It is: the bound exists so one large catalogue cannot crowd out the turn, and per server is exactly what stops one server flooding. A turn-wide budget would be a different property. Code follows doc is not taken. Threading one budget through the server loop changes runtime behaviour and needs the per-server fairness question answered first, since a first-listed server could consume the whole budget and starve the rest. Nothing is near either bound today, so that decision does not have to be made under pressure, and this change does not foreclose it. ## What a reader now sees The scope is stated in the three places someone might start from: `docs/sirens-echo-mcp.md` with the roster-wide worst case beside it, `readGrounding`'s doc comment, and the line that initialises the budget. ## No test The fix is a corrected sentence. A test asserting the doc's wording would restate configuration, which `AGENTS.md` rules out, and a behavioural test would need a two-server MCP fixture to assert behaviour nobody is changing. The page was at its 8,000-char cap, so three restatements elsewhere on it were compressed to make room. closes #858

coilyco-ops added 1 commit

2026-08-17 19:03:30 +00:00

docs: state the grounding bound as the per-server one it is

ci / image-build (pull_request) Successful in 31s

Details

ci / test (pull_request) Successful in 58s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

0bba46c41a

The bound was written as a turn budget and enforced per server. readGrounding
is called inside the per-server loop and initialises budget := maxGroundingBytes
itself, so it resets for every connected server rather than accumulating. On
Echo's eleven-server roster the real ceiling is 88 documents and 90KB against a
documented 8.

Doc follows code, which the issue names as sufficient if the per-server shape
was intended. It was: the bound exists so one large catalogue cannot crowd out
the turn, and per server is what stops one server flooding.

Code follows doc is not taken. Threading one budget through the server loop
changes runtime behaviour and needs the per-server fairness question answered
first, since a first-listed server could consume the whole turn budget and
starve the rest. Nothing is near either bound today, so that decision does not
have to be made under pressure.

The scope is now stated in three places a reader might start from: the page,
readGrounding's doc comment, and the line that initialises the budget.

closes #858

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-17 19:03:30 +00:00

coilyco-ops referenced this pull request

2026-08-17 19:03:46 +00:00

The grounding bound is documented per turn and enforced per server, so the real ceiling is 11x the stated one #858