pinakes 0.2.2__py3-none-any.whl

pinakes/__init__.py

@@ -0,0 +1,9 @@
+"""pinakes — a portable, agent-first knowledge base.
+
+One directory is one knowledge base: human-readable sources, human-readable metadata, and a
+disposable machine index. The architecture is specified in docs/DESIGN.md.
+"""
+
+__version__ = "0.2.2"
+
+__all__ = ["__version__"]

pinakes/_toml.py

@@ -0,0 +1,192 @@
+"""A strict reader over parsed TOML.
+
+Every accessor consumes the key it reads; `done()` then fails on whatever is left. That is how
+unknown keys become hard errors: a manifest saying `finall_k = 20` must not be silently ignored,
+because the user would get default behaviour while believing they had configured something.
+
+Errors name the file, the table and the key, in that order — a validation error the user cannot
+locate is barely better than no validation.
+"""
+
+from collections.abc import Sequence
+from decimal import Decimal
+from pathlib import Path
+from typing import Any, cast
+
+from pinakes.errors import ManifestError
+
+ROOT_NAME = "<root>"
+
+
+class Table:
+    """One TOML table, read destructively so leftovers can be reported."""
+
+    def __init__(self, data: dict[str, Any], *, name: str, source: Path) -> None:
+        self._data = dict(data)
+        self._name = name
+        self._source = source
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def _child_name(self, key: str) -> str:
+        """`[retrieval]`, not `[<root>.retrieval]`: the name must match what the user typed."""
+        return key if self._name == ROOT_NAME else f"{self._name}.{key}"
+
+    def _fail(self, message: str, *, remedy: str | None = None) -> ManifestError:
+        return ManifestError(self._source, table=self._name, message=message, remedy=remedy)
+
+    def _take(self, key: str, *, required: bool) -> object | None:
+        """Read and consume a key. Returns `object`, not `Any`, so every caller must narrow it."""
+        if key in self._data:
+            return self._data.pop(key)
+        if required:
+            raise self._fail(f"missing required key `{key}`")
+        return None
+
+    def _string(self, key: str, *, required: bool) -> str | None:
+        value = self._take(key, required=required)
+        if value is None:
+            return None
+        if not isinstance(value, str):
+            raise self._fail(f"`{key}` must be a string, found {type(value).__name__}")
+        if not value.strip():
+            # An explicit empty string is a mistake, never a request for the default: silently
+            # substituting one would hide it until something far downstream failed obscurely.
+            raise self._fail(f"`{key}` must not be empty")
+        return value
+
+    def string(self, key: str) -> str:
+        """A required string. The return type is `str`, so callers need no assertion."""
+        value = self._string(key, required=True)
+        assert value is not None  # `required=True` raised already; this is for the type checker
+        return value
+
+    def optional_string(self, key: str) -> str | None:
+        return self._string(key, required=False)
+
+    def string_or(self, key: str, default: str) -> str:
+        return self._string(key, required=False) or default
+
+    def choice(self, key: str, allowed: Sequence[str], *, default: str | None = None) -> str:
+        value = self.string(key) if default is None else self.string_or(key, default)
+        if value not in allowed:
+            raise self._fail(
+                f"`{key}` must be one of {', '.join(repr(option) for option in allowed)}, "
+                f"found {value!r}"
+            )
+        return value
+
+    def integer(self, key: str, *, default: int | None = None, minimum: int | None = None) -> int:
+        value = self._take(key, required=default is None)
+        if value is None:
+            value = default
+        # bool is an int subclass; `max_tokens = true` must not read as 1.
+        if not isinstance(value, int) or isinstance(value, bool):
+            raise self._fail(f"`{key}` must be an integer, found {type(value).__name__}")
+        if minimum is not None and value < minimum:
+            raise self._fail(f"`{key}` must be >= {minimum}, found {value}")
+        return value
+
+    def number(
+        self, key: str, *, default: float | None = None, minimum: float | None = None
+    ) -> float:
+        value = self._take(key, required=default is None)
+        if value is None:
+            value = default
+        if isinstance(value, bool) or not isinstance(value, int | float):
+            raise self._fail(f"`{key}` must be a number, found {type(value).__name__}")
+        value = float(value)
+        if minimum is not None and value < minimum:
+            raise self._fail(f"`{key}` must be >= {minimum}, found {value}")
+        return value
+
+    def decimal(
+        self, key: str, *, default: Decimal | None = None, minimum: Decimal | None = None
+    ) -> Decimal:
+        """A TOML number read as an exact `Decimal`, for a value that is ever compared or summed
+        as money — where `float`'s binary representation error would make a hard cap not actually
+        hard (I6a).
+
+        TOML has no native decimal type, so `tomllib` hands back a `float` regardless; this goes
+        through `Decimal(str(value))`, never `Decimal(value)` directly. The former recovers the
+        clean literal a user typed (`0.05` -> `Decimal("0.05")`); the latter reproduces the exact
+        binary value that literal only approximates (`0.05` ->
+        `Decimal("0.05000000000000000277555756156289135105907917022705078125")`) — verified
+        directly against every value this project's own `[budget]` defaults use.
+        """
+        value = self._take(key, required=default is None)
+        if value is None:
+            assert default is not None  # `required=True` above already raised otherwise
+            decimal_value = default
+        else:
+            if isinstance(value, bool) or not isinstance(value, int | float):
+                raise self._fail(f"`{key}` must be a number, found {type(value).__name__}")
+            decimal_value = Decimal(str(value))
+        # Checked on both paths, not only the TOML-sourced one — `integer()`/`number()` above
+        # validate their own defaults for free, since they share one type with the parsed value;
+        # `decimal()`'s default is already a `Decimal` rather than a parsed float, so an early
+        # return here would let a below-`minimum` default slip past unminded.
+        if minimum is not None and decimal_value < minimum:
+            raise self._fail(f"`{key}` must be >= {minimum}, found {decimal_value}")
+        return decimal_value
+
+    def strings(self, key: str, *, default: Sequence[str] | None = None) -> tuple[str, ...]:
+        value = self._take(key, required=default is None)
+        if value is None:
+            return tuple(default or ())
+        if not isinstance(value, list):
+            raise self._fail(f"`{key}` must be a list of strings")
+        items: list[str] = []
+        for item in cast(list[object], value):
+            if not isinstance(item, str):
+                raise self._fail(
+                    f"`{key}` must be a list of strings, found a {type(item).__name__}"
+                )
+            items.append(item)
+        return tuple(items)
+
+    def table(self, key: str) -> "Table | None":
+        value = self._take(key, required=False)
+        if value is None:
+            return None
+        if not isinstance(value, dict):
+            raise self._fail(f"`{key}` must be a table")
+        return Table(cast(dict[str, Any], value), name=self._child_name(key), source=self._source)
+
+    def tables(self, key: str) -> list["Table"]:
+        value = self._take(key, required=False)
+        if value is None:
+            return []
+        if not isinstance(value, list):
+            raise self._fail(f"`{key}` must be an array of tables")
+        tables: list[Table] = []
+        for index, item in enumerate(cast(list[object], value)):
+            if not isinstance(item, dict):
+                raise self._fail(f"`{key}` must be an array of tables")
+            tables.append(
+                Table(
+                    cast(dict[str, Any], item),
+                    name=f"{self._child_name(key)}[{index}]",
+                    source=self._source,
+                )
+            )
+        return tables
+
+    def reject(self, key: str, *, because: str) -> None:
+        """Fail loudly on a key that moved, so an old manifest is corrected rather than ignored."""
+        if key in self._data:
+            raise self._fail(f"`{key}` is not valid here: {because}")
+
+    def done(self) -> None:
+        if self._data:
+            unknown = ", ".join(f"`{key}`" for key in sorted(self._data))
+            raise self._fail(
+                f"unknown key(s): {unknown}",
+                remedy=(
+                    "Unknown keys are rejected rather than ignored — a typo would otherwise leave "
+                    "you with default behaviour while believing you had configured something. "
+                    "Check the spelling against docs/DESIGN.md §2.1."
+                ),
+            )

pinakes/budget/__init__.py

@@ -0,0 +1,4 @@
+"""The pure half of the money machinery (I6a, docs/DESIGN.md §5): estimation, per-call and
+per-document reservation, and ledger-window aggregation. No I/O, no `anthropic` import — reading
+`ledger.jsonl` and actually spending are I6b's job. Money is `Decimal` end to end.
+"""

pinakes/budget/estimate.py

@@ -0,0 +1,146 @@
+"""Estimate a PDF document's worst-case cost under a paid extraction backend (I6a, decision 8).
+
+**A request is a K-page slice, never a whole document and never a single page.** Getting the unit
+wrong is the difference between a reservation that bounds a run and one that is wrong by an order
+of magnitude in either direction: a whole-document request makes input quadratic and stops fitting
+the context window past a few hundred pages; a per-page request loses the neighbouring context a
+table or sentence continuing across a page break needs. `K = 5` is a semantic constant, not a
+tuning knob — it is hashed into the paid extractor's own request-shape version (I7b), because the
+context a page is transcribed with is part of what produced its text.
+
+**Worst case per request** = `(K * page_tokens + prompt_tokens) * input_price + max_tokens *
+output_price`, and a document is `ceil(pages / K)` requests. `prompt_tokens` (the instructions plus
+the JSON schema) is a measured module constant, not an afterthought a real "worst case" could
+silently omit. There is deliberately no cache-write multiplier: the shared prefix (system prompt
+plus instructions) is a few hundred tokens against the model's own cache minimum, so it very likely
+cannot be cached at all, and even cached it is roughly 1% of a request dominated by page tokens.
+
+**The whole request must also fit the model's documented context window before the first call** —
+a check that costs nothing to run and, under the shipped constants, never fires (30,300 tokens
+against 1,000,000), but names the exact limit that bounds it rather than letting a real 400 from a
+call already in flight be how the limit is discovered.
+
+Money is `Decimal` end to end and never quantised here — quantisation to the cent happens at
+exactly one point, when a reservation or reconciliation is written to the ledger (I6b).
+"""
+
+import math
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal
+from typing import Final
+
+from pinakes.budget.prices import Prices
+from pinakes.errors import ContextWindowExceededError, StalePricesError
+
+#: Pages per request. A semantic constant (I7b hashes it into the request-shape version) — never
+#: read from configuration, because changing it changes what every cached response actually means.
+K: Final = 5
+
+#: Conservative ceiling until I7b measures the real figure per backend, `measured_on` recorded
+#: beside it. Derived from the vendor's own documented high-resolution page budget (~4,784 visual
+#: tokens per rendered page) plus that page's text, applied to the document's actual page count,
+#: never the API's own maximum page count per request.
+PAGE_TOKEN_CEILING: Final = 6_000
+
+#: The instructions plus the JSON schema a real request sends, measured once as a module constant
+#: — omitting it from the worst-case formula would make "worst case" a claim the formula does not
+#: back.
+PROMPT_TOKENS: Final = 300
+
+#: Output ceiling per request. Caps thinking and response text *together* on `claude-opus-5`, so it
+#: is the correct and only safe per-request output bound. ~4,000 tokens actually produced per
+#: 5-page slice against this leaves 2x headroom, so a truncation retry is rare.
+MAX_TOKENS: Final = 8_000
+
+_TIMESTAMP_FORMAT: Final = "%Y%m%d %H:%M"
+
+#: Documented maximum input tokens, by model name. Not a price, so it does not live in
+#: `prices.toml` — a model absent here cannot be context-window-checked, which `estimate_document`
+#: treats as "nothing to check" rather than a reason to refuse an otherwise-fine estimate.
+MAX_INPUT_TOKENS: Final[dict[str, int]] = {
+    "claude-opus-5": 1_000_000,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Estimate:
+    """A worst-case cost estimate for one document, at the request granularity decision 8 fixes."""
+
+    model: str
+    pages_total: int
+    pages_estimated: int
+    requests: int
+    input_tokens_per_request: int
+    output_tokens_per_request: int
+    input_eur: Decimal
+    output_eur: Decimal
+
+    @property
+    def total_eur(self) -> Decimal:
+        return self.input_eur + self.output_eur
+
+    @property
+    def per_request_eur(self) -> Decimal:
+        """Every request costs the same under this model (same `K`, same prompt, same
+        `max_tokens`) — what `reserve()` checks before each individual call."""
+        return self.total_eur / self.requests
+
+
+def estimate_document(
+    *,
+    pages: int,
+    model: str,
+    prices: Prices,
+    now: str,
+    max_price_age_days: int,
+    pages_estimated: int | None = None,
+) -> Estimate:
+    """Estimate the worst-case cost of extracting `pages` pages of a document with `model`.
+
+    `now` is an explicit `YYYYMMDD HH:MM` string, never read from the wall clock internally —
+    staleness is checked against whatever the caller supplies, which is what keeps this function
+    pure and deterministic under test. `pages_estimated` defaults to the whole document (`pages`);
+    a caller estimating only a remaining slice of a larger document may pass a smaller value, with
+    `pages` still naming the document's true total.
+    """
+    if pages < 1:
+        raise ValueError(f"estimate_document: pages={pages} must be >= 1")
+    estimated = pages if pages_estimated is None else pages_estimated
+    if not 1 <= estimated <= pages:
+        raise ValueError(
+            f"estimate_document: pages_estimated={estimated} must be between 1 and pages={pages}"
+        )
+
+    as_of = datetime.strptime(prices.as_of, _TIMESTAMP_FORMAT)
+    current = datetime.strptime(now, _TIMESTAMP_FORMAT)
+    if (current - as_of).days > max_price_age_days:
+        raise StalePricesError(as_of=prices.as_of, max_age_days=max_price_age_days)
+
+    model_price = prices.for_model(model)
+
+    request_input_tokens = K * PAGE_TOKEN_CEILING + PROMPT_TOKENS
+    max_input = MAX_INPUT_TOKENS.get(model)
+    if max_input is not None and request_input_tokens > max_input:
+        raise ContextWindowExceededError(
+            request_tokens=request_input_tokens, max_input_tokens=max_input, model=model
+        )
+
+    requests = math.ceil(estimated / K)
+    input_tokens_total = requests * request_input_tokens
+    output_tokens_total = requests * MAX_TOKENS
+
+    million = Decimal(1_000_000)
+    input_usd = (Decimal(input_tokens_total) / million) * model_price.input_per_mtok_usd
+    output_usd = (Decimal(output_tokens_total) / million) * model_price.output_per_mtok_usd
+
+    return Estimate(
+        model=model,
+        pages_total=pages,
+        pages_estimated=estimated,
+        requests=requests,
+        input_tokens_per_request=request_input_tokens,
+        output_tokens_per_request=MAX_TOKENS,
+        input_eur=input_usd / prices.usd_per_eur,
+        output_eur=output_usd / prices.usd_per_eur,
+    )

pinakes/budget/prices.py

@@ -0,0 +1,81 @@
+"""`prices.toml` loading — the money-side twin of `extract/floors.py`.
+
+Ships as package data beside `extract/floors.toml`, read through `importlib.resources` for the
+same reason: a file that lives only in the source tree is invisible to an installed wheel, and
+prices are consumed at runtime, not at repo-checkout time.
+
+Every value in the file is a TOML *string*, not a bare number — parsed via `Decimal(the_string)`
+directly, never `Decimal(float(the_string))`. TOML has no native decimal type, so a bare `5.00`
+would come back from `tomllib` as a `float`, and `Decimal(5.00)` reproduces the exact binary value
+that literal only approximates, not the clean decimal a human wrote (verified directly,
+docs/RETROSPECTIVES.md). Because this file is entirely project-controlled — never user-authored,
+unlike `pinakes.toml` — writing prices as strings costs nothing and removes the float
+intermediary altogether, rather than reconstructing it from `str(float(...))` the way
+`manifest.py`'s `Table.decimal()` has to for a user-authored TOML number.
+"""
+
+import tomllib
+from dataclasses import dataclass
+from decimal import Decimal, InvalidOperation
+from importlib import resources
+from typing import Any, cast
+
+from pinakes.errors import PricesMissingError, UnknownModelPriceError
+
+PRICES_RESOURCE = "prices.toml"
+
+
+@dataclass(frozen=True, slots=True)
+class ModelPrice:
+    input_per_mtok_usd: Decimal
+    output_per_mtok_usd: Decimal
+
+
+@dataclass(frozen=True, slots=True)
+class Prices:
+    as_of: str
+    usd_per_eur: Decimal
+    models: dict[str, ModelPrice]
+
+    def for_model(self, model: str) -> ModelPrice:
+        found = self.models.get(model)
+        if found is None:
+            raise UnknownModelPriceError(model, known=tuple(self.models))
+        return found
+
+
+def load_prices() -> Prices:
+    """Read `prices.toml` through `importlib.resources` — never a repo-relative path, or a source
+    checkout would silently pass what an installed wheel cannot (the same lesson `floors.py`
+    already states)."""
+    try:
+        raw = (
+            resources.files("pinakes.budget").joinpath(PRICES_RESOURCE).read_text(encoding="utf-8")
+        )
+    except (FileNotFoundError, OSError) as exc:
+        raise PricesMissingError(reason=str(exc)) from exc
+
+    try:
+        data = tomllib.loads(raw)
+        raw_models = cast(dict[str, Any], data["models"])
+        models = {
+            name: ModelPrice(
+                input_per_mtok_usd=Decimal(str(entry["input_per_mtok_usd"])),
+                output_per_mtok_usd=Decimal(str(entry["output_per_mtok_usd"])),
+            )
+            for name, entry in raw_models.items()
+        }
+        return Prices(
+            as_of=str(data["as_of"]),
+            usd_per_eur=Decimal(str(data["usd_per_eur"])),
+            models=models,
+        )
+    except (
+        tomllib.TOMLDecodeError,  # syntax
+        KeyError,  # a required key absent
+        TypeError,  # a value the wrong shape (e.g. `models` not a table)
+        ValueError,
+        InvalidOperation,  # `Decimal(str(x))` on an unparsable value, e.g. "5,00" or "TBD"
+        AttributeError,  # `models` present but not a table (`raw_models.items()` on a str/int)
+    ) as exc:
+        raise PricesMissingError(reason=f"malformed prices.toml ({exc})") from exc

pinakes/budget/prices.toml

@@ -0,0 +1,17 @@
+# Ships as package data (I6a) — read at runtime through `importlib.resources`, never a
+# repo-relative path, so an installed wheel sees exactly what a source checkout does.
+#
+# Every price is a *string*, not a bare TOML number: this file is entirely project-controlled
+# (never user-authored, unlike pinakes.toml), so there is no reason to let a TOML float sit
+# between the literal below and the `Decimal` this project does all money arithmetic in.
+# `Decimal("5.00")` is exact; `Decimal(5.00)` is not (verified directly, docs/RETROSPECTIVES.md).
+#
+# usd_per_eur carries the same as_of as the model prices below: every EUR figure this project
+# computes depends on it, and a rate with its own, different staleness would make "the prices are
+# fresh" a claim about only half of what an estimate actually uses.
+as_of = "20260728 16:31"
+usd_per_eur = "1.08"
+
+[models.claude-opus-5]
+input_per_mtok_usd = "5.00"
+output_per_mtok_usd = "25.00"

pinakes/budget/reserve.py

@@ -0,0 +1,153 @@
+"""The §5 accountant — pure: given an estimate, the configured caps, and what has already been
+spent, decide whether a call (or a whole document) may proceed (I6a).
+
+**Before every call, all three ceilings are checked** — `per_operation_eur`, `daily_eur`, and
+`monthly_eur` — and if any of `spent.X + reserved` would exceed its cap, the call is never made.
+One operation (one `pnk sync`, one `pnk ask --deep`) bounds a single invocation only; the day and
+month windows are what stop a *sequence* of invocations, which is the failure mode a hook-driven KB
+actually has.
+
+**The whole document is checked before the first call**, not only per call: per-call reservation
+alone bounds each call and nothing else, and a document that will certainly blow through a window
+by call 15 should be refused at call 0, not discovered by watching it fail partway through.
+`reserve_document` is that upfront check — it refuses with all three windows' current headroom,
+the computed estimate, the complete manifest edit that would admit this run, and a line on the
+ongoing exposure that edit creates (a raised cap is permanent; a one-run `--extract=` override for
+a specific paid backend is not).
+
+`confirm_above_eur` is evaluated **once, against the whole-document estimate** — never per call
+(`reserve` itself does not touch it): a per-call reading against a several-cent slice would prompt
+dozens of times for one multi-page document, which is how a confirmation becomes something a user
+learns to hold down `y` through.
+"""
+
+from dataclasses import dataclass
+from decimal import ROUND_CEILING, ROUND_HALF_UP, Decimal
+
+from pinakes.budget.estimate import Estimate
+from pinakes.budget.window import WindowTotals
+
+_CENT = Decimal("0.01")
+
+
+def _display(amount: Decimal) -> str:
+    """Round-half-up to the cent for a human-facing message only — the comparisons above run at
+    full `Decimal` precision throughout; quantisation for *storage* happens once, at ledger-write
+    time (I6b), and this is a separate, display-only rounding that never feeds back into a
+    decision."""
+    return str(amount.quantize(_CENT, rounding=ROUND_HALF_UP))
+
+
+#: (attribute on `Caps`, attribute on `WindowTotals`, display name) — one row per window, checked
+#: in this order everywhere the three are named together.
+_WINDOWS: tuple[tuple[str, str, str], ...] = (
+    ("per_operation_eur", "operation", "per_operation_eur"),
+    ("daily_eur", "day", "daily_eur"),
+    ("monthly_eur", "month", "monthly_eur"),
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Caps:
+    per_operation_eur: Decimal
+    daily_eur: Decimal
+    monthly_eur: Decimal
+
+
+@dataclass(frozen=True, slots=True)
+class Decision:
+    """The outcome of one per-call `reserve()` check."""
+
+    allowed: bool
+    blocked_by: str | None = None
+    """Which window refused it — `"per_operation_eur"`, `"daily_eur"` or `"monthly_eur"` — `None`
+    when `allowed`."""
+    message: str | None = None
+    """A ready-to-print refusal, set only when `allowed` is `False`."""
+
+
+@dataclass(frozen=True, slots=True)
+class DocumentDecision:
+    """The outcome of the whole-document `reserve_document()` precheck."""
+
+    allowed: bool
+    needs_confirmation: bool
+    """`confirm_above_eur` reached — a soft prompt, meaningful only when `allowed`."""
+    message: str | None = None
+    """The complete, multi-line refusal — every window's headroom, the estimate, the manifest
+    edit that would admit this run, and the ongoing-exposure line. Set only when not `allowed`."""
+
+
+def reserve(reserved_eur: Decimal, caps: Caps, spent: WindowTotals) -> Decision:
+    """Check one call's estimated cost against all three windows, in order. The first window it
+    would breach is the one named — the call is refused before any of the others are even
+    checked, since one honest reason is clearer than three, and the caller cannot make the call
+    anyway."""
+    for cap_attr, spent_attr, name in _WINDOWS:
+        cap = getattr(caps, cap_attr)
+        already = getattr(spent, spent_attr)
+        would_be = already + reserved_eur
+        if would_be > cap:
+            message = (
+                f"refused: the {name} cap of €{_display(cap)} would be exceeded "
+                f"(already spent €{_display(already)} this window, this call would add "
+                f"€{_display(reserved_eur)}, total €{_display(would_be)})."
+            )
+            return Decision(allowed=False, blocked_by=name, message=message)
+    return Decision(allowed=True)
+
+
+def reserve_document(
+    estimate: Estimate, caps: Caps, spent: WindowTotals, *, confirm_above_eur: Decimal
+) -> DocumentDecision:
+    """Check a whole document's worst-case estimate against all three windows before the first
+    call. Unlike `reserve`, a refusal here names *every* window at once — walking a user through
+    one manifest edit, then a second, then a third, to discover the actual ceiling is precisely
+    the defect this exists to avoid."""
+    total = estimate.total_eur
+    blocked = [
+        (cap_attr, spent_attr, name, getattr(caps, cap_attr), getattr(spent, spent_attr))
+        for cap_attr, spent_attr, name in _WINDOWS
+        if getattr(spent, spent_attr) + total > getattr(caps, cap_attr)
+    ]
+    if blocked:
+        return DocumentDecision(
+            allowed=False, needs_confirmation=False, message=_refusal_message(estimate, blocked)
+        )
+    return DocumentDecision(allowed=True, needs_confirmation=total > confirm_above_eur)
+
+
+def _refusal_message(
+    estimate: Estimate, blocked: list[tuple[str, str, str, Decimal, Decimal]]
+) -> str:
+    lines = [
+        f"refused: extracting {estimate.pages_estimated} page(s) of {estimate.pages_total} with "
+        f"{estimate.model} is estimated at €{_display(estimate.total_eur)} "
+        f"({estimate.requests} request(s), worst case), which exceeds "
+        f"{len(blocked)} of the three budget windows:",
+    ]
+    edits: list[str] = []
+    for cap_attr, _spent_attr, name, cap, already in blocked:
+        headroom = cap - already
+        # Negative when a cap was lowered below already-recorded spend for this window (the cap
+        # check itself never lets `already` alone exceed a cap that held for the whole window) —
+        # "headroom €-1.00" reads as a typo, not as already being over.
+        headroom_text = (
+            f"headroom €{_display(headroom)}"
+            if headroom >= 0
+            else f"already €{_display(-headroom)} over cap"
+        )
+        minimum_cap = (already + estimate.total_eur).quantize(_CENT, rounding=ROUND_CEILING)
+        lines.append(
+            f"  - {name}: cap €{_display(cap)}, already spent €{_display(already)} this window, "
+            f"{headroom_text} — this run needs €{_display(estimate.total_eur)}."
+        )
+        edits.append(f"{cap_attr} = {minimum_cap}")
+    lines.append("The complete manifest edit that would admit this run:")
+    lines.append("  [budget]")
+    lines.extend(f"  {edit}" for edit in edits)
+    lines.append(
+        "Raising a cap is a permanent, ongoing exposure to every future run at that ceiling — a "
+        "one-run `--extract=<backend>` override changes only this invocation, not the manifest."
+    )
+    return "\n".join(lines)