fix(retrieval): #882 bound the query context to the model's window and stop citing what it never read

[jasonssdev]

The defect

openkos query built its prompt from the full body of every retrieved document with no size bound and no disclosure. Ollama does not raise on an oversized prompt — it discards the overflow and answers normally — so --save filed every retrieved citation as provenance verbatim, including documents the model had never read. That is a false provenance claim on disk, and no surface (query, lint, status) could reveal it.

#888 chunked the embedding side, but VectorStore.query collapses to one hit per document, so the retrieval unit stayed the whole document and this defect survived it intact.

Measured live, not asserted

Same corpus, same num_ctx: 12288, real qwen3:8b:

arm	prompt	prompt_eval_count
no bound (pre-fix)	208,222 chars	6,146
bounded (post-fix)	8,410 chars	2,449

6146 is the exact truncation constant #866 recorded. At the ratio the bounded arm establishes (3.434 chars/token) the unbounded prompt should evaluate ~60,634 tokens, so 54,488 of them — 89.9% — were discarded in silence. The bounded arm's chars and tokens agree, so the whole prompt is read.

What changed

• New leaf src/openkos/prompt_budget.py owns the bound: planning window, char budget, even-coverage excerpt, and a water-filling split of one window across competing blocks. extraction: the judge died unparseable (no-json) on 3 of 3 chunked Spanish sources, and the runs cost ~8 minutes each #866's _bounded_prompt_source becomes a thin wrapper over the same renderer, so ingest and retrieval cannot drift apart — the two-renderer failure curate renders merged-body contradictions as a self-pair, dropping the diagnosis and the unmerge remedy #883 had just closed elsewhere.
• Citation.excerpted and AnswerResult.excerpted_titles record what was sent, not what was cited: query: the model answers conceptual questions from its own knowledge and still attaches citations #753's attribution filter would otherwise erase the disclosure exactly when the answer cited nothing.
• A block left no room at all is dropped from the prompt and the citation list and reported separately — a bare [concept_id: …] label is still a numbered block the model can cite. The disclosure travels on the no-match return too, or an entirely dropped context reads to the operator as "the bundle has nothing".
• query names the affected documents on stderr, marks partial citations [partial], and discloses both cases in the --save plan before the confirmation gate.

Review

Receipt review-dc71e9c4ba1743da, four lenses, APPROVED with zero corrections consumed. Three earlier candidates were fixed pre-capture:

• a fair_shares invariant violation (CRITICAL) — fair_shares([0, 100], budget=1) returned [1, 0], spending the only available char on an empty body and starving the larger block;
• an order-dependence that contradicted its own docstring — [7, 9, 100] at budget 11 gave [4, 4, 3], the same multiset reversed gave [3, 4, 4]. Fixed in the code rather than weakened in the docs;
• a vacuous test of mine — reworded the notice in an earlier round and left the test grepping for a word it no longer contained, so the assertion passed unconditionally.

Declared, not fixed

The excerpt search is O(n²) in windows: 0.3 ms at 55K chars, 27 ms at 500K, 434 ms at 2M. Left as is — the fit is not strictly monotonic in window count (adjacency changes the join cost), so a binary search could return a smaller excerpt than one that fits. Two lenses raised it; the measurement is in the docstring.

Verification

5747 passed, 1 skipped · coverage 96.79% (gate 90) · ruff check, ruff format --check, mypy . clean over 275 files · 36/36 harness self-tests.

Closes #882