"""Consume an OKF consumption **pre-pass payload** — a cut of a knowledge base, declared. The debate normally NAVIGATES its knowledge base (S2c): it is handed a pointer and four tools, and it opens what it chooses. That works — measured 2026-09-06, a live model reached the price form in three steps out of 630 concept documents — and it leaves an **undeclared cut**: nothing in such a run says how many concepts were considered, how many withheld, or by which rule. The OKF consumption contract SS 2.3 calls that a denominator failure dressed as an answer, and this repository holds the same rule under its own names (``skipped_links``, ``unkeyed_verdicts``, ``cost_baseline_anchored`` all exist because a silent drop is a claim nobody can revise). This module consumes the alternative: a payload produced ahead of the run by an external, contract-conformant pre-pass, carrying the delivered excerpts AND the three denominators. **po produces no payload and vendors no producer.** Contract SS 2.4 — "A conformant skill MAY be handed a payload by any transport. The transport is not part of this contract." A subprocess against the producer's checkout would bind this package to a path on one operator's machine and die inside ``git archive HEAD``; a vendored copy would be the second copy of a ranking instrument that ko-(p) forbids. So the payload is an INPUT FILE, in the ``--mandate`` / ``--ledger`` / ``--explore-config`` idiom, and what this module owns is the GATE in front of it. **Two gates live inside the tool this seam withdraws**, and both are re-raised here on the MOUNTED document rather than delegated to the producer's own rules: the verdict-layer refusal (order 20260904T172353Z) and the SS 4.1a dimension scope. Delegating either would make one of this repository's most recently gated invariants depend on a file an external caller supplied. **Validation, NEVER repair** (``okf.write_concept_file``'s rule): a payload that does not hold is refused by name and nothing is recounted, corrected or written. """ from __future__ import annotations import hashlib import json import unicodedata from collections.abc import Mapping from dataclasses import dataclass from pathlib import Path from pydantic import BaseModel, ConfigDict from portfolio_optimiser import okf from portfolio_optimiser.retrieval import PathSecurityError, safe_resolve #: The payload revision this consumer understands, compared with ``==`` and never a prefix #: (SS 8.2 exists so a reader can tell which revision it is holding). A future ``/2`` is refused by #: name rather than consumed as if it were this one — the ``PORTFOLIO_OTEL`` rule: never a silent #: fallback on an unknown declared value. CONTRACT_REVISION = "okf-consumption/1" #: The suffix a ``concept_id`` is missing. The producer's id is the bundle-relative path minus the #: suffix (measured against real output, and against ``okf``'s own ``BundleFile.name``), so the #: join back to a mounted document is this one concatenation. CONCEPT_SUFFIX = ".md" class PrepassRefused(ValueError): """A payload this run will not read from, named. A ``ValueError`` **subclass on purpose**: it must land on ``run.main``'s refusal tuple as ``run refused: ...`` and on the hosted flat's 400 arm, never on the crash channel — the ``okf.BundleIdMismatch`` / ``okf.CostBaselineDerivationError`` precedent. The caller supplied a file that does not hold; that is a refusal, not a failure of this program. """ # --- The payload (contract SS 8, plus po's declared superset) ------------------------------- class _Permissive(BaseModel): """SS 8: "Additional members are permitted and are not read by the checker." Measured against real producer output at revision ``54a0bc2``: excerpts carry ``rank`` and ``bundle_id_inherited`` beyond the members SS 8 fixes. A strict model would refuse conformant payloads, so every model here ignores what it does not name. """ model_config = ConfigDict(extra="ignore") class PrepassKnownPositive(_Permissive): """SS 7.4: the instrument's own proof that it can count.""" case: str expected: int measured: int class PrepassBudget(_Permissive): """SS 7: a limit, the unit it is counted in, the instrument that counted, and the spend.""" unit: str instrument: str limit: int spent: int known_positive: PrepassKnownPositive class PrepassBundle(_Permissive): """SS 3.3: the base's id and the **ref** — a fact about bytes, never a declared version.""" bundle_id: str ref: str class PrepassDenominators(_Permissive): """SS 5.1: the three counts, whose identity SS 5.2 requires to close.""" considered: int withheld: int delivered: int class PrepassSource(_Permissive): """SS 8's declared address for an excerpt: where the underlying source document lives. A fixed, singular member (never a growing family like ``source_*``) — named on purpose. """ resource: str title: str | None = None class PrepassExcerpt(_Permissive): """One delivered unit of bundle content. ``text``, ``text_sha256`` and ``concept_id`` are **po's declared superset of SS 8**, which names no content member at all — a payload can be fully conformant and carry nothing to read, and this seam's entire value is the content. Requiring them refuses that case by name instead of discovering it as an empty prompt. ``title``, ``req_number`` and ``sources`` are named fields because they are SS-8-declared, singular members — every payload has at most one of each. ``source_*`` locators (``source_element_id``, ``source_sha256``, and whatever a future producer adds) are NOT named here: measured (P3, order 20260908T141941Z), the producer's own message calls that a PREFIX RULE rather than a fixed allowlist — a real corpus already carries five such members where another carries two. Naming two of them would need a new field and a new render line for a third; ``extra="allow"`` plus :meth:`source_locators`' prefix scan needs neither. Every field here defaults to ``None`` (or, for ``sources``, absent) because most payloads in this repository predate P2's producer change and carry none of them — a required field would refuse every payload written before today. """ model_config = ConfigDict(extra="allow") bundle_id: str concept_id: str sha256: str adjudication: str trust_tier: str text: str text_sha256: str title: str | None = None req_number: str | None = None sources: tuple[PrepassSource, ...] | None = None def source_locators(self) -> tuple[tuple[str, str], ...]: """Every ``source_*`` scalar the producer attached, sorted by key. Reads ``model_extra`` rather than a named field for each one — the prefix-rule reason this class's docstring gives. ``sources`` itself is excluded: it is a named field (a list, never a scalar) and does not land in ``model_extra`` in the first place, but the guard is explicit rather than relying on that. """ extra = self.model_extra or {} return tuple( sorted( (key, str(value)) for key, value in extra.items() if key.startswith("source_") and key != "sources" ) ) class PrepassWithheld(_Permissive): """SS 5.3: a concept that was considered and not delivered, naming the rule that dropped it.""" concept_id: str rule: str class PrepassPayload(_Permissive): """One contract-SS-8 payload. ``question`` is REQUIRED although SS 8's example does not fix it: a cut computed for a different question, accepted in silence, would leave this run's artefacts unable to say which question produced the denominators they publish — the same undeclared claim the seam exists to remove, one level up. """ contract: str bundle: PrepassBundle budget: PrepassBudget denominators: PrepassDenominators question: str excerpts: tuple[PrepassExcerpt, ...] withheld: tuple[PrepassWithheld, ...] def load_prepass_payload(path: str) -> PrepassPayload: """Read one payload from disk, fail-fast. ``mandate.load_mandate``'s idiom exactly: ``FileNotFoundError`` for a path that is not there, ``ValueError`` (from ``json``) for bytes that are not JSON, ``ValidationError`` for a shape the model refuses. None of them is swallowed — a caller who asked for a declared cut and silently got ``None`` would have been answered by a downgraded order. """ return PrepassPayload.model_validate(json.loads(Path(path).read_text(encoding="utf-8"))) # --- The shape gate ------------------------------------------------------------------------ def check_payload_shape(payload: PrepassPayload) -> None: """Refuse a payload whose own numbers do not hold. Reads no disk. Six refusals. Four are live against today's producer; two are DEFENSIVE and unwitnessed — ``spent > limit`` and a known-positive mismatch are both refused by the producer BEFORE it emits (``okf_consume.py`` raises ``budget_exceeded`` and ``instrument_unvalidated``), so no payload carrying them exists to test against. They stand for the reason ``budget_stop``'s portfolio arm stands: the contract states them as MUSTs about the emitted payload, and a consumer that trusts a producer to have checked has not checked. """ if payload.contract != CONTRACT_REVISION: raise PrepassRefused( f"the payload declares contract {payload.contract!r}, and this consumer reads " f"{CONTRACT_REVISION!r}; refusing rather than reading an unknown revision as if it " "were this one" ) counts = payload.denominators observed = counts.withheld + counts.delivered if counts.considered != observed: # The two numbers as FIELDS, never one sentence (BudgetExceeded's ko-(y) rule): "it does # not close" is not actionable, "9 declared against 5 observed" is. raise PrepassRefused( f"the denominators do not close: considered {counts.considered} declared, " f"{observed} observed as withheld {counts.withheld} + delivered {counts.delivered}; " "a count that does not close is not a denominator (SS 5.2)" ) if len(payload.excerpts) != counts.delivered: raise PrepassRefused( f"the payload carries {len(payload.excerpts)} excerpts but declares " f"delivered {counts.delivered} (SS 8.1)" ) if len(payload.withheld) != counts.withheld: # SS 8.1's SECOND half, and the one this whole seam is about: the withheld list IS the # declaration of what was not delivered. raise PrepassRefused( f"the payload carries {len(payload.withheld)} withheld entries but declares " f"withheld {counts.withheld} (SS 8.1)" ) if payload.budget.spent > payload.budget.limit: raise PrepassRefused( f"the payload spent {payload.budget.spent} against a limit of {payload.budget.limit} " f"{payload.budget.unit}; exceeding the gate means the cut strategy is wrong for this " "bundle, which is a finding requiring a decision (SS 7.3)" ) known = payload.budget.known_positive if known.expected != known.measured: raise PrepassRefused( f"the budget instrument did not reproduce its known positive {known.case!r}: " f"expected {known.expected}, measured {known.measured}; an instrument that has not " "reproduced a known figure has not been shown to count (SS 7.4)" ) # --- Binding the payload to the mounted base ------------------------------------------------ def concept_text(path: Path) -> str: """The concept body as the producer delivers it, re-derived from the mounted file. **Transcribed from the producer, and MEASURED — never guessed.** The rule is: take the text after the frontmatter block, NFC-normalise, and strip trailing whitespace per line (a spreadsheet render is padded to hundreds of trailing spaces per line, so unstripped, most of a budget goes on padding). The frontmatter split uses ``splitlines()``; measured 2026-09-07, a naive ``split("\\n")`` disagrees with the producer, and the disagreement is invisible until a real payload is checked against it — which is what ``test_concept_text_reproduces_the_producers_derivation`` does. """ text = path.read_text(encoding="utf-8") lines = text.splitlines() body = text if lines and lines[0].strip() == "---": for offset, line in enumerate(lines[1:], start=2): if line.strip() == "---": body = "\n".join(lines[offset:]) break return "\n".join(line.rstrip() for line in unicodedata.normalize("NFC", body).split("\n")) def verify_against_bundle( payload: PrepassPayload, *, bundle_dir: str, resolved_id: okf.ResolvedBundleId, dimension: str | None = None, ) -> None: """Refuse a payload that is not this base's cut. Run AFTER :func:`check_payload_shape`. Five checks, each naming what it refused. 1. **Identity** is the base's DECLARED id, never its mount (S7a-3): a base delivered under a directory name of its own is opened rather than refused, so comparing against the mount would refuse exactly the corpora the slack exists for. 2. **The join** goes through ``safe_resolve``, the one fail-closed in-/out-of-bundle test in this repository. A ``concept_id`` is externally supplied, so it is untrusted input by definition — and ``PathSecurityError`` is a ``RuntimeError``, which would leave the CLI as a traceback and the hosted flat as a 500, so it is re-raised here as the refusal it is. 3. **The file digest** catches a stale payload: ``sha256`` is the digest of the WHOLE mounted concept file. ``bundle.ref`` is deliberately NOT recomputed — ``sha256-tree`` is the producer's algorithm, and re-deriving it here would be the vendored copy this module exists without. **Honesty limit, stated:** the delivered documents are verified; the whole tree is not. 4. **The delivered text must be re-derivable from the mounted file.** ``sha256`` digests the file while ``text`` is a DERIVED member, so a payload can carry a correct digest beside arbitrary text — and ``text`` is what enters the debate's task message, the conversation's highest-trust slot. Requiring equality means a payload **cannot deliver bytes the base does not hold**, which reduces the exposure from "external content in the prompt" to "bundle content in the prompt" — what ``read_file`` already does today. 5. **The two withdrawn gates**, re-raised on the mounted DOCUMENT: the verdict layer (whose prior judgements reach a hypothesis only through the gated ExpeL fold) and SS 4.1a's dimension scope. The producer applies its own verdict-layer exclusion, and that is exactly why this is not delegated to it. The ``dimension`` arm is DEFENSIVE from the CLI, which refuses the two flags together; a library caller can still reach it (``budget_stop``'s precedent for an arm that stands without a live caller). """ if payload.bundle.bundle_id != resolved_id.id: raise PrepassRefused( f"the payload declares bundle_id {payload.bundle.bundle_id!r} and this knowledge base " f"declares {resolved_id.id!r} (mounted at {resolved_id.mount!r}); a cut of another " "corpus is not this run's cut" ) for excerpt in payload.excerpts: try: resolved = Path(safe_resolve(bundle_dir, excerpt.concept_id + CONCEPT_SUFFIX)) except PathSecurityError as error: raise PrepassRefused( f"the payload names concept {excerpt.concept_id!r}, which does not resolve inside " f"the knowledge base: {error}" ) from error if not resolved.is_file(): raise PrepassRefused( f"the payload delivers concept {excerpt.concept_id!r}, which this knowledge base " "does not hold" ) if hashlib.sha256(resolved.read_bytes()).hexdigest() != excerpt.sha256: raise PrepassRefused( f"the sha256 the payload declares for {excerpt.concept_id!r} is not the digest of " "the mounted document; the payload was built against different bytes" ) derived = concept_text(resolved) if derived != excerpt.text: raise PrepassRefused( f"the text the payload delivers for {excerpt.concept_id!r} is not the text of the " "mounted document; a payload may only deliver what the knowledge base holds" ) if hashlib.sha256(derived.encode("utf-8")).hexdigest() != excerpt.text_sha256: raise PrepassRefused( f"the text_sha256 the payload declares for {excerpt.concept_id!r} is not the " "digest of the text it delivers" ) if okf.declares_verdict_type(resolved): raise PrepassRefused( f"the payload delivers {excerpt.concept_id!r}, which the knowledge base declares " "as a verdict; prior judgements reach a hypothesis only through the gated " "experience fold, never as read context" ) if dimension is not None and not _in_dimension(resolved, dimension): raise PrepassRefused( f"the payload delivers {excerpt.concept_id!r}, which is outside the dimension " f"{dimension!r} this run is scoped to" ) def _in_dimension(path: Path, dimension: str) -> bool: """The SS 4.1a predicate, applied to a mounted document. ``okf.in_dimension`` takes a ``BundleFile``, so this reads the one frontmatter key it reads and defers to it — never a second copy of the rule (ko-(p)). """ frontmatter = okf.parse_frontmatter(path) return okf.in_dimension( okf.BundleFile( name=path.name, type=frontmatter.get("type", ""), frontmatter=frontmatter, body="", ), dimension, ) # --- The one admission gate, shared by every door that consumes a payload -------------------- def admit_payload( payload: PrepassPayload, *, bundle_dir: str, resolved_id: okf.ResolvedBundleId, dimension: str | None = None, ) -> None: """Everything that must hold before a payload may shape a run. Raises, or returns nothing. ONE copy, because there are now TWO doors onto this file — the debate's ``--prepass-payload`` (the cut REPLACES the pointer and the tools are withdrawn) and the exploration's ``--prepass-seed`` (the cut is the STARTING POINT and the tools stay). The two arms differ in what they do with an admitted payload and in nothing at all about what makes one admissible, and two copies of an admission rule is the ko-(p) drift that would let one door accept what the other refuses. The three steps, in this order and for this reason: the shape gate reads no disk and so is free, the bundle check is the expensive one, and the empty-delivery refusal comes last because a payload that does not hold has not earned an interpretation of its own emptiness. **``delivered == 0`` is refused on BOTH arms**, and on the seeding arm that is a decision rather than an inheritance. Measured, it is reachable only when every concept failed to match lexically (the producer REFUSES the other empty case, where concepts matched and the budget admitted none), so it is evidence of ABSENCE for this question at this ref. On the seeding arm a caller might argue the tools are still there and the run could proceed — but it would then proceed as a PLAIN exploration while the operator had asked for a seeded one, which is the silently downgraded order ``load_mandate`` fail-fasts against. """ check_payload_shape(payload) verify_against_bundle( payload, bundle_dir=bundle_dir, resolved_id=resolved_id, dimension=dimension ) if not payload.excerpts: # Saying it beats two silent alternatives: an empty prompt, or falling through to # ``run_project``'s citation guard, whose message names ``docs_dir`` — ``None`` on this # path. SS 7.3's own posture: the skill stops and says so. raise PrepassRefused( f"the pre-pass delivered 0 of {payload.denominators.considered} concepts for the " f"question {payload.question!r} at ref {payload.bundle.ref}; an empty cut is evidence " "that this knowledge base does not answer that question, not something to run over" ) # --- Rendering the cut for the prompt -------------------------------------------------------- def render_context(payload: PrepassPayload) -> str: """What the debate is handed INSTEAD of ``run._bundle_pointer``'s pointer. Three jobs, and the third is the one the Amendment asked for. 1. **Deliver.** The excerpt text, so the debate can reason at all. 2. **Bound.** The withheld concepts appear as rule -> COUNT and never as ids. Measured on a 629-concept corpus the withheld list alone is 34 451 o200k tokens against a run cap of 100 000 that the task message rides three times — and a rule name is the fact a reader can act on, while a list of ids they cannot open is cost without information. The full list stays in the payload, one artefact away (``list_bundles``' "the whole index is one call away" rule, applied one rung over). 3. **Declare.** The three denominators and the question they were computed for, so the cut is stated rather than left to be inferred from what happens not to be here (SS 2.3). **The closing line is not decoration.** Measured live, a question this corpus cannot answer still returns eight excerpts, and with the navigator tools withdrawn the debate has no way to discover that for itself. So the rendering says plainly that a delivered excerpt is a LEXICAL match and not an answer, and names ``[sourced-not-sufficient]`` from SS 4's marking set as the available verdict. **``adjudication`` and ``trust_tier`` are labelled as the PRODUCER's declaration**, not as ours. B4 established that a trust tier is derived locally from a document's own ``verified`` frontmatter — and this repository's bases carry none, so deriving it here would report ``unverified`` for everything and say nothing. Carrying the producer's value under the producer's name is the honest form; adopting it silently as ours would not be. The excerpt text goes in a delimited DATA block below the instruction (SS 9.3: machine- generated text is data, never instructions). That is MITIGATION and is stated as such — the GATE is ``verify_against_bundle``, which makes the text re-derivable from the mounted base, so a payload cannot deliver bytes the base does not hold. """ return "\n".join( _declaration_lines(payload) + [ "", "Each excerpt below matched the question LEXICALLY. That is not the same as answering " "it: a base that holds no answer still returns its closest matches. If the delivered " "text does not support a claim, say so with [sourced-not-sufficient] rather than " "filling the gap. adjudication and trust_tier are the producer's declarations about " "each document, carried here unchanged.", ] + _data_blocks(payload) ) def render_seed(payload: PrepassPayload) -> str: """What the EXPLORATION is handed IN ADDITION to its prompt, keeping its navigation tools. The other arm of one decision, and the difference is a single fact stated in both directions: :func:`render_context` says "you have no tools to read further, what is below is all of it", which is true there and would be a LIE here. Contract SS 2.2 forbids reading "outside what the payload delivers **or explicitly names as reachable**" — the second clause is what makes this arm conformant, and a rendering that did not say the rest was reachable would leave a model obeying the first clause while holding the tools for the second. **Not a second copy of the rendering rule.** The declaration header, the rule -> COUNT folding and the delimited DATA blocks are the SAME functions the other arm uses; what differs is the one paragraph that tells the reader what it may do next. Two full copies would drift, and a drifted pair would state two different cuts for one run (ko-(p)). ``[unread]`` is used deliberately, and it is one of contract SS 4.1's five required literals: a withheld concept in this arm is not absent and not unavailable, it is simply not yet read — and saying so is what turns the withheld list from a boundary into a next step. """ return "\n".join( _declaration_lines(payload, rest_reachable=True) + [ "", "Each excerpt below matched the question LEXICALLY. That is not the same as answering " "it: a base that holds no answer still returns its closest matches. The withheld " "concepts are [unread], not absent — if the delivered text does not support a claim, " "OPEN THE BASE with your navigation tools rather than filling the gap, and reserve " "[sourced-not-sufficient] for a claim the base itself could not support. Report what " "you actually read. adjudication and trust_tier are the producer's declarations about " "each document, carried here unchanged.", ] + _data_blocks(payload) ) def _declaration_lines(payload: PrepassPayload, *, rest_reachable: bool = False) -> list[str]: """The header both renderings open with: the base, what the cut may be used for, the counts. ONE copy, because these lines ARE the declaration (SS 2.3) and two of them would be two answers to "what was this run's cut". Only the second line differs between the arms, and it differs on exactly the fact ``PrepassDeclaration.rest_reachable`` carries. """ counts = payload.denominators rules = ", ".join(f"{rule} ({count})" for rule, count in withheld_rule_counts(payload)) stance = ( "You are reading a DECLARED CUT of that base as your STARTING POINT, not as a replacement " "for it. The rest of the base stays reachable with your navigation tools, and you are " "expected to use them when the cut does not carry what you need." if rest_reachable else "You are reading a DECLARED CUT of that base, not the base itself, and you have no " "tools to read further. What is below is all of it." ) return [ f"Knowledge base: {payload.bundle.bundle_id} (ref {payload.bundle.ref}).", "", stance, f"The cut was computed for this question: {payload.question}", f"Concepts considered: {counts.considered}. Withheld: {counts.withheld}. " f"Delivered below: {counts.delivered}.", f"Withheld by rule: {rules}." if rules else "Withheld by rule: none.", ] def _excerpt_header(excerpt: PrepassExcerpt) -> str: """The BEGIN line for one excerpt: ``concept_id`` plus whatever the producer named it with. **Known-negative, load-bearing:** a P1-form excerpt (none of the five new fields) renders BYTE-IDENTICAL to before P3 — the loop below appends nothing, and the line is exactly the old ``(adjudication: ..., trust_tier: ...)`` form (``test_a_p1_form_payload_renders_the_header_exactly_as_before``). Carrying a field through must never change what an older payload renders as. ``req_number`` and ``title`` are what a person would cite; the address (``sources[0].resource``) and every ``source_*`` locator are what lets a claim be traced back to the document that produced it — measured (P2 SS 4) to be the exact thing modelled proposals cited a UUID instead of, because the UUID was the only identifier that reached the prompt. """ fields = [f"adjudication: {excerpt.adjudication}", f"trust_tier: {excerpt.trust_tier}"] if excerpt.req_number is not None: fields.append(f"req_number: {excerpt.req_number}") if excerpt.title is not None: fields.append(f"title: {excerpt.title}") if excerpt.sources: fields.append(f"source: {excerpt.sources[0].resource}") for key, value in excerpt.source_locators(): fields.append(f"{key}: {value}") return f"--- BEGIN DATA {excerpt.concept_id} ({', '.join(fields)}) ---" def _data_blocks(payload: PrepassPayload) -> list[str]: """The delimited DATA blocks, one per delivered excerpt (SS 9.3), shared by both arms.""" lines: list[str] = [] for excerpt in payload.excerpts: lines += [ "", _excerpt_header(excerpt), excerpt.text, f"--- END DATA {excerpt.concept_id} ---", ] return lines # --- The declaration ------------------------------------------------------------------------- @dataclass(frozen=True) class PrepassDeclaration: """What a run says about the cut it was given: a RUN-level fact, not a per-candidate one. It reports the payload's OWN denominators verbatim, never a recount off the navigated bundle: the pre-pass may legitimately have considered a different set (it counts the verdict layer, ``Bundle.context_files`` does not), and two numbers for one fact is ko-(p). ``rest_reachable`` says which of the two arms consumed the cut, and it is REQUIRED WITHOUT A DEFAULT for ``ProvenanceStamp.cost_baseline_anchored``'s reason: **both defaults would lie.** ``False`` would let a run that kept its navigation tools publish a declaration claiming the cut was all it could read; ``True`` would let the arm that WITHDREW them claim the base stayed open. It is the contract's own distinction -- SS 2.2 forbids reading "outside what the payload delivers **or explicitly names as reachable**", so a conformant consumer may keep the base reachable, and the difference between the two readings is exactly what a reader of this declaration needs to know. """ bundle_id: str ref: str question: str considered: int withheld: int delivered: int withheld_rules: tuple[tuple[str, int], ...] rest_reachable: bool def withheld_rule_counts(payload: PrepassPayload) -> tuple[tuple[str, int], ...]: """rule -> COUNT, sorted. The ONE folding of the withheld list in this repository. The concept ids are deliberately NOT carried: measured on a 629-concept corpus the withheld list alone is 34 451 o200k tokens, and a rule name is the fact a reader can act on while a list of ids they cannot open is cost without information. The full list stays in the payload, one artefact away. It is a function of its own rather than a step inside ``declaration_of`` because THREE surfaces need it -- the declaration and both renderings -- and a second copy of "how the withheld list folds" would be free to disagree about the run it describes (ko-(p)). """ counts: dict[str, int] = {} for entry in payload.withheld: counts[entry.rule] = counts.get(entry.rule, 0) + 1 return tuple(sorted(counts.items())) def declaration_of(payload: PrepassPayload, *, rest_reachable: bool) -> PrepassDeclaration: """The declaration a verified payload supports, for the arm that consumed it. ``rest_reachable`` is a REQUIRED keyword: see :class:`PrepassDeclaration`. The payload cannot supply it -- a cut does not know what its consumer did with the navigation tools -- so it is the caller's to state, and every caller states it. """ return PrepassDeclaration( bundle_id=payload.bundle.bundle_id, ref=payload.bundle.ref, question=payload.question, considered=payload.denominators.considered, withheld=payload.denominators.withheld, delivered=payload.denominators.delivered, withheld_rules=withheld_rule_counts(payload), rest_reachable=rest_reachable, ) def declaration_payload(declaration: PrepassDeclaration) -> Mapping[str, object]: """The declaration as a plain mapping, so the outbox stays framework-free.""" return { "bundle_id": declaration.bundle_id, "ref": declaration.ref, "question": declaration.question, "considered": declaration.considered, "withheld": declaration.withheld, "delivered": declaration.delivered, "withheld_rules": [ {"rule": rule, "count": count} for rule, count in declaration.withheld_rules ], # Which arm read the cut. An artefact that reported the denominators without saying # whether the consumer could still open the base would leave a reader unable to tell a # bounded run from a seeded one -- the same undeclared claim, one level up. "rest_reachable": declaration.rest_reachable, }