"""Load-bearing gate for what a declared cut LOOKS LIKE in the prompt (order 20260907T080223Z). Two things are gated here, and they pull in opposite directions: - The rendering must carry enough that the debate can reason and DECLARE — the delivered text, the three denominators, and the rules that dropped everything else. - It must stay bounded. Measured on a 629-concept corpus, the whole payload is 41 097 o200k tokens and its withheld list alone is 34 451; the debate's task message rides in three calls, so a rendering that carried the payload verbatim would cost ~123 000 against a run cap of 100 000 that has already fired live. The ceiling therefore lives HERE and not in `prepass.py` — `_CATALOGUE_EXCERPT_CHARS`' own rule: a bound imported from the implementation moves with it, and widening it is exactly the regression this file exists to catch. """ from __future__ import annotations import hashlib import json import shutil from pathlib import Path from typing import Any from portfolio_optimiser import prepass FIXTURE = Path(__file__).parent / "fixtures" / "prepass" / "bygg-energi-mikro-fixture.payload.json" SHIPPED_BASE = Path(__file__).parent.parent / "shared" / "examples" / "bygg-energi-mikro" #: What the rendering may add ON TOP of the delivered text, in CHARACTERS. #: #: **The OVERHEAD is bounded, not the total, and that is the whole point.** The delivered text is #: already bounded by the producer's own budget gate (SS 7.3, re-checked by `check_payload_shape`), #: so an absolute ceiling would either refuse a legitimately large cut or be so loose it caught #: nothing. What po must guarantee is the shape of the cost: O(delivered text) + O(1), never #: O(corpus) — which is exactly what regresses if the 621-entry withheld list creeps back in. #: #: Characters, not tokens, for MAJOR-3's reason: `tiktoken` is not a dependency of this package, #: and a gate that skips when an optional package is missing is a gate that can be silently #: absent. Measured 2026-09-07 with a validated instrument, the byte/token ratio is not one #: number — 2,50 for a withheld list, 2,90 for ordinary Norwegian concept prose, 17,90 for a #: padded spreadsheet render — so converting a token budget into this bound would import an #: arithmetic that does not hold across the corpus. #: #: The bound lives HERE and never in `prepass.py`: `_CATALOGUE_EXCERPT_CHARS`' rule, because a #: bound imported from the implementation moves with it, and widening it is the regression. _CEILING_OVERHEAD_CHARS = 2_000 _DELIVERED_SENTINEL = "SENTINEL-LEVERT-UTDRAG" _WITHHELD_SENTINEL = "SENTINEL-TILBAKEHOLDT-KONSEPT" def _raw() -> dict[str, Any]: return json.loads(FIXTURE.read_text(encoding="utf-8")) def _marked_base(tmp_path: Path) -> tuple[str, prepass.PrepassPayload]: """A base where a DELIVERED concept and a WITHHELD one each carry their own sentinel. Two sentinels, not one: with a single marker the "the withheld text never reaches the prompt" assertion could be satisfied by a rendering that carries nothing at all, and the "the delivered text does reach it" assertion by one that carries everything. """ root = tmp_path / "marked" shutil.copytree(SHIPPED_BASE, root) index = root / "index.md" lines = index.read_text(encoding="utf-8").split("\n") lines.insert(1, "bundle_id: bygg-energi-mikro-fixture") index.write_text("\n".join(lines), encoding="utf-8") raw = _raw() delivered = raw["excerpts"][0] withheld_id = raw["withheld"][0]["concept_id"] for concept_id, sentinel in ( (delivered["concept_id"], _DELIVERED_SENTINEL), (withheld_id, _WITHHELD_SENTINEL), ): path = root / (concept_id + ".md") path.write_text(path.read_text(encoding="utf-8") + f"\n\n{sentinel}\n", encoding="utf-8") delivered["sha256"] = hashlib.sha256( (root / (delivered["concept_id"] + ".md")).read_bytes() ).hexdigest() delivered["text"] = prepass.concept_text(root / (delivered["concept_id"] + ".md")) delivered["text_sha256"] = hashlib.sha256(delivered["text"].encode("utf-8")).hexdigest() return str(root), prepass.PrepassPayload.model_validate(raw) # --- what the rendering carries ------------------------------------------------------------- def test_the_rendering_carries_the_delivered_text(tmp_path: Path) -> None: _, payload = _marked_base(tmp_path) assert _DELIVERED_SENTINEL in prepass.render_context(payload) def test_the_rendering_carries_nothing_from_a_withheld_concept(tmp_path: Path) -> None: """The half that matters. A withheld concept was withheld deliberately (SS 2.2).""" _, payload = _marked_base(tmp_path) assert _WITHHELD_SENTINEL not in prepass.render_context(payload) def test_the_withheld_sentinel_really_is_in_the_base(tmp_path: Path) -> None: """The causality control for the arm above: without it, that assertion is satisfied by a sentinel that was never written anywhere.""" bundle_dir, payload = _marked_base(tmp_path) withheld_id = payload.withheld[0].concept_id body = (Path(bundle_dir) / (withheld_id + ".md")).read_text(encoding="utf-8") assert _WITHHELD_SENTINEL in body def test_the_rendering_names_the_withheld_rules_and_never_the_withheld_ids() -> None: """Rule -> COUNT. A rule name is a fact a reader can act on; a list of ids they cannot open is cost without information, and on a real corpus it is 34 451 tokens of it.""" payload = prepass.load_prepass_payload(str(FIXTURE)) rendering = prepass.render_context(payload) # The HEADER — everything po itself authors, before the first delivered document. A whole- # rendering substring assert would be red for the wrong reason the moment a delivered concept # happens to CITE a withheld one, which in a cross-linked base is ordinary (measured: it does). header = rendering.split("--- BEGIN DATA")[0] assert "verdict_layer_excluded" in header for entry in payload.withheld: assert entry.concept_id not in header def test_the_rendering_carries_the_three_denominators_and_the_question() -> None: payload = prepass.load_prepass_payload(str(FIXTURE)) rendering = prepass.render_context(payload) for number in ( payload.denominators.considered, payload.denominators.withheld, payload.denominators.delivered, ): assert str(number) in rendering assert payload.question in rendering assert payload.bundle.bundle_id in rendering def test_the_rendering_says_a_delivered_excerpt_is_not_an_answer() -> None: """Measured live on a 629-concept corpus: a question the base cannot answer still returns eight excerpts. A rendering that presented them as "what the base says about this" would be handing the debate a confident guess wearing a denominator.""" rendering = prepass.render_context(prepass.load_prepass_payload(str(FIXTURE))) assert "[sourced-not-sufficient]" in rendering # --- the bound ------------------------------------------------------------------------------ def _overhead(payload: prepass.PrepassPayload) -> int: """What the rendering costs beyond the delivered text itself.""" return len(prepass.render_context(payload)) - sum(len(e.text) for e in payload.excerpts) def test_the_rendering_adds_only_a_bounded_overhead_to_the_delivered_text() -> None: payload = prepass.load_prepass_payload(str(FIXTURE)) assert _overhead(payload) <= _CEILING_OVERHEAD_CHARS, _overhead(payload) def test_the_overhead_stays_bounded_when_the_corpus_is_large() -> None: """The arm that makes the bound mean something. The checked-in fixture withholds ONE concept, so a rendering that dumped every withheld id would pass the arm above on it. This one synthesises the corpus-scale case — 620 withheld concepts, K2's own order of magnitude — and requires the overhead to be UNCHANGED in order of magnitude, which only a rule -> count rendering can do. """ raw = _raw() raw["withheld"] = [ { "concept_id": f"del-ii/{n:03d}/et-ganske-langt-konseptnavn-som-i-et-ekte-korpus", "rule": "no_lexical_match", } for n in range(620) ] + raw["withheld"] raw["denominators"]["withheld"] = len(raw["withheld"]) raw["denominators"]["considered"] = len(raw["withheld"]) + raw["denominators"]["delivered"] payload = prepass.PrepassPayload.model_validate(raw) prepass.check_payload_shape(payload) assert _overhead(payload) <= _CEILING_OVERHEAD_CHARS, _overhead(payload) def test_the_withheld_list_alone_is_far_over_the_overhead_ceiling() -> None: """The flat control: without it, the arm above could be green because the synthetic list is somehow cheap rather than because the rendering summarises it.""" withheld = [ { "concept_id": f"del-ii/{n:03d}/et-ganske-langt-konseptnavn-som-i-et-ekte-korpus", "rule": "no_lexical_match", } for n in range(620) ] assert len(json.dumps(withheld, ensure_ascii=False)) > 5 * _CEILING_OVERHEAD_CHARS # --- the declaration ------------------------------------------------------------------------- def test_the_declaration_reports_the_payloads_own_denominators() -> None: """Never a recount off the navigated bundle: the pre-pass counts the verdict layer and `Bundle.context_files` does not, so two numbers for one fact would be kø-(p).""" payload = prepass.load_prepass_payload(str(FIXTURE)) declaration = prepass.declaration_of(payload, rest_reachable=False) assert declaration.considered == payload.denominators.considered == 5 assert declaration.withheld == payload.denominators.withheld == 1 assert declaration.delivered == payload.denominators.delivered == 4 assert declaration.ref == payload.bundle.ref assert declaration.question == payload.question def test_the_declaration_counts_the_withheld_rules_without_naming_the_concepts() -> None: payload = prepass.load_prepass_payload(str(FIXTURE)) declaration = prepass.declaration_of(payload, rest_reachable=False) assert declaration.withheld_rules == (("verdict_layer_excluded", 1),) assert sum(count for _, count in declaration.withheld_rules) == declaration.withheld def test_the_declaration_payload_is_a_plain_mapping() -> None: """The outbox stays framework-free (`explore.trace_payload`'s rule).""" declaration = prepass.declaration_of( prepass.load_prepass_payload(str(FIXTURE)), rest_reachable=False ) body = prepass.declaration_payload(declaration) assert json.loads(json.dumps(body))["withheld_rules"] == [ {"rule": "verdict_layer_excluded", "count": 1} ]