cctally 1.113.0 → 1.115.0

package/bin/_lib_perf.py

@@ -149,7 +149,8 @@ def _stack():
 
 
 class Phase:
-    __slots__ = ("name", "elapsed_ms", "count", "meta", "children", "_start", "_stack")
+    __slots__ = ("name", "elapsed_ms", "count", "meta", "children", "_start",
+                 "_stack", "write_bytes", "_write_start")
 
     def __init__(self, name, stack):
         self.name = name
@@ -159,6 +160,8 @@ class Phase:
         self.children = []
         self._start = 0.0
         self._stack = stack
+        self.write_bytes = None
+        self._write_start = None
 
     def set_count(self, n):
         self.count = int(n)
@@ -169,12 +172,17 @@ class Phase:
         self.meta.update(kw)
 
     def __enter__(self):
+        self._write_start = _write_counter_value()
         self._start = time.perf_counter()
         self._stack.append(self)
         return self
 
     def __exit__(self, *exc):
         self.elapsed_ms = (time.perf_counter() - self._start) * 1000.0
+        end = _write_counter_value()
+        if (self._write_start is not None and end is not None
+                and end >= self._write_start):
+            self.write_bytes = end - self._write_start
         # Identity-aware unwind. If a nested phase leaked (its __exit__ was
         # skipped — e.g. an exception escaped a manually CM-bracketed region),
         # drop the leaked frames sitting above us so we never append a phase to
@@ -203,6 +211,8 @@ class Phase:
             d["count"] = self.count
         if self.meta:
             d["meta"] = dict(self.meta)
+        if self.write_bytes is not None:
+            d["write_bytes"] = self.write_bytes
         if self.children:
             d["children"] = [c.to_dict() for c in self.children]
         return d
@@ -227,6 +237,22 @@ class _NullPhase:
 _NULL_PHASE = _NullPhase()
 
 
+def _write_counter_value():
+    """The process write counter for an armed phase (#901 §5.5), or None.
+
+    Deep-phase samples are optional: they ride an armed trace only, and the
+    always-on totals never depend on them. The counter module is used only
+    when the process already loaded it, so this stays stdlib-only."""
+    module = sys.modules.get("_lib_write_io")
+    if module is None:
+        return None
+    try:
+        reading = module.read_counter()
+    except Exception:  # noqa: BLE001 — a diagnostic must not raise
+        return None
+    return reading.value if reading.status == "ok" else None
+
+
 def phase(name):
     # Per-root capture (#583 S1 §2.2). `_ENABLED` is process-global and HTTP
     # handlers open their own roots on their own threads, so a flip landing

package/bin/_lib_pricing.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 
 import dataclasses
 import datetime as dt
+import math
 import re
 import sys
 from typing import Any
@@ -30,6 +31,34 @@ def _eprint(*args: Any) -> None:
 
 TIERED_THRESHOLD = 200_000
 
+# #929: Claude Haiku 5.5 is priced by prompt length. A card that declares
+# `whole_request_prompt_threshold_tokens` selects ONE card per request from its
+# prompt (input + flat cache creation + cache read): over the threshold every
+# class of that request, output included, bills at the `_above_100k_tokens`
+# rates. This is a different mechanism from the per-class MARGINAL
+# `_above_200k_tokens` split older Sonnet cards carry, and a card never mixes
+# the two. A legacy card carries neither the marker nor any 100K field.
+CLAUDE_WHOLE_REQUEST_THRESHOLD_KEY = "whole_request_prompt_threshold_tokens"
+CLAUDE_WHOLE_REQUEST_THRESHOLD = 100_000
+CLAUDE_WHOLE_REQUEST_TIER_FIELDS = (
+    ("input_cost_per_token", "input_cost_per_token_above_100k_tokens"),
+    ("output_cost_per_token", "output_cost_per_token_above_100k_tokens"),
+    ("cache_creation_input_token_cost",
+     "cache_creation_input_token_cost_above_100k_tokens"),
+    ("cache_read_input_token_cost",
+     "cache_read_input_token_cost_above_100k_tokens"),
+)
+CLAUDE_WHOLE_REQUEST_TIER_SUFFIX = "_above_100k_tokens"
+# The marker plus the four recognised tier fields. A card sharing none of them
+# is legacy; the hot path decides that with one `isdisjoint` call. A card that
+# carries some OTHER `_above_100k_tokens` field is malformed: the selector
+# refuses it when the card is otherwise whole-request, and
+# `check_table_shapes` refuses it on any card (`claude_whole_request_
+# declaration_problems`), so it can never silently price at the base card.
+_CLAUDE_WHOLE_REQUEST_KEYS = frozenset(
+    (CLAUDE_WHOLE_REQUEST_THRESHOLD_KEY,
+     *(tier for _, tier in CLAUDE_WHOLE_REQUEST_TIER_FIELDS)))
+
 
 def _chip_for_model(name: str) -> str:
     """Bucket a canonical model id into a small chip palette.
@@ -63,7 +92,12 @@ def _chip_for_model(name: str) -> str:
 # fingerprint a store recorded and refuses a write from an older process. That
 # comparison is day-granular by construction, so two revisions sharing a date
 # compare equal and the older process is authorized to write.
-PRICING_SNAPSHOT_DATE = "2026-09-30"
+#
+# A sync of this date or of either table also changes the dynamic-SQL shape
+# pinned in `bin/_lib_detector_access_registry.py`, so its registry test fails
+# until the affected pins are re-pinned through the reviewed procedure in that
+# module's docstring. Bulk regeneration of the pins alone is not acceptance.
+PRICING_SNAPSHOT_DATE = "2026-10-14"
 PRICING_STALENESS_DAYS = 60  # release pre-flight WARNs past this age
 
 
@@ -517,6 +551,21 @@ CLAUDE_MODEL_PRICING: dict[str, dict[str, Any]] = {
         "cache_creation_input_token_cost": 1.25e-06,
         "cache_read_input_token_cost": 1e-07,
     },
+    "claude-haiku-5-5": {
+        # Source: https://platform.claude.com/docs/en/models/haiku-5-5/overview
+        # Priced by prompt length (#929): over 100,000 prompt tokens the WHOLE
+        # request bills at the _above_100k_tokens card. The 1h write stays
+        # derived (selected input x CACHE_WRITE_1H_MULTIPLIER).
+        "input_cost_per_token": 1e-07,
+        "output_cost_per_token": 5e-07,
+        "cache_creation_input_token_cost": 1.25e-07,
+        "cache_read_input_token_cost": 1e-08,
+        "input_cost_per_token_above_100k_tokens": 5e-07,
+        "output_cost_per_token_above_100k_tokens": 2.5e-06,
+        "cache_creation_input_token_cost_above_100k_tokens": 6.25e-07,
+        "cache_read_input_token_cost_above_100k_tokens": 5e-08,
+        "whole_request_prompt_threshold_tokens": 100_000,
+    },
     "claude-mythos-5": {
         "input_cost_per_token": 1e-05,
         "output_cost_per_token": 5e-05,
@@ -656,7 +705,7 @@ CLAUDE_MODEL_PRICING: dict[str, dict[str, Any]] = {
         "input_cost_per_token": 2e-06,
         "output_cost_per_token": 1e-05,
         "cache_creation_input_token_cost": 2.5e-06,
-        "cache_read_input_token_cost": 2e-07,
+        "cache_read_input_token_cost": 1e-07,
     },
 }
 
@@ -1274,6 +1323,118 @@ def claude_usage_dict(*, cache_1h_tokens, speed, input_tokens=0, output_tokens=0
     return usage
 
 
+def _finite_positive_rate(value) -> bool:
+    return (isinstance(value, (int, float)) and not isinstance(value, bool)
+            and math.isfinite(value) and value > 0)
+
+
+def _is_whole_request_card(card) -> bool:
+    """True when ``card`` declares (or half-declares) a whole-request tier:
+    it carries the marker or one of the four recognised tier fields. This is
+    on every Claude request's pricing path, so it is one set operation; the
+    scan for unrecognised ``_above_100k_tokens`` fields lives in
+    ``claude_whole_request_declaration_problems``."""
+    return not _CLAUDE_WHOLE_REQUEST_KEYS.isdisjoint(card)
+
+
+def _unrecognised_whole_request_fields(card) -> list:
+    return sorted(k for k in card
+                  if k.endswith(CLAUDE_WHOLE_REQUEST_TIER_SUFFIX)
+                  and k not in _CLAUDE_WHOLE_REQUEST_KEYS)
+
+
+def claude_whole_request_declaration_problems(card) -> list:
+    """Every reason ``card``'s whole-request declaration is malformed (#929).
+
+    ``[]`` for a legacy card (neither the marker nor any
+    ``_above_100k_tokens`` field) and for a well-formed declaration. Shared by
+    the selector and ``check_table_shapes`` so the two can never disagree
+    about what is well formed. Any ``_above_100k_tokens`` field other than the
+    four recognised ones is a problem, with or without the marker.
+    """
+    unrecognised = _unrecognised_whole_request_fields(card)
+    if not unrecognised and not _is_whole_request_card(card):
+        return []
+    problems = []
+    key = CLAUDE_WHOLE_REQUEST_THRESHOLD_KEY
+    threshold = card.get(key)
+    if key not in card:
+        problems.append(f"missing {key}")
+    elif (isinstance(threshold, bool) or not isinstance(threshold, int)
+          or threshold != CLAUDE_WHOLE_REQUEST_THRESHOLD):
+        problems.append(
+            f"{key} must be the integer {CLAUDE_WHOLE_REQUEST_THRESHOLD} the "
+            f"_above_100k_tokens fields name (got {threshold!r})")
+    for _, tier in CLAUDE_WHOLE_REQUEST_TIER_FIELDS:
+        if tier not in card:
+            problems.append(f"missing {tier}")
+        elif not _finite_positive_rate(card[tier]):
+            problems.append(
+                f"{tier} not a finite positive number ({card[tier]!r})")
+    mixed = sorted(k for k in card if k.endswith("_above_200k_tokens"))
+    if mixed:
+        problems.append("mixes whole-request and marginal tiers: "
+                        + ", ".join(mixed))
+    if unrecognised:
+        problems.append("unrecognised _above_100k_tokens fields: "
+                        + ", ".join(unrecognised))
+    return problems
+
+
+def _select_claude_request_card(card, *, input_tokens, cache_creation_tokens,
+                                cache_read_tokens, prompt_tokens_for_tier=None):
+    """The card that prices ONE request (#929). Pure: never writes ``card``.
+
+    A legacy card (neither the marker nor any of the four recognised tier
+    fields) is returned unchanged (the same object) without reading a count.
+    A whole-request card must be well formed, which includes carrying no
+    unrecognised ``_above_100k_tokens`` field, or this raises
+    ``ValueError``. Its prompt is ``prompt_tokens_for_tier`` when given (a
+    caller pricing a synthetic subset of a real request), else input + FLAT
+    cache creation + cache read; output and the 1h sub-split never count. At or
+    under the threshold the stored card itself is returned; over it, a NEW dict
+    whose four base slots hold the higher rates and which carries neither the
+    marker nor any tier field.
+    """
+    if not _is_whole_request_card(card):
+        return card
+    problems = claude_whole_request_declaration_problems(card)
+    if problems:
+        raise ValueError("malformed whole-request pricing declaration: "
+                         + "; ".join(problems))
+    if prompt_tokens_for_tier is None:
+        prompt = ((input_tokens or 0) + (cache_creation_tokens or 0)
+                  + (cache_read_tokens or 0))
+    else:
+        prompt = prompt_tokens_for_tier
+    if prompt <= card[CLAUDE_WHOLE_REQUEST_THRESHOLD_KEY]:
+        return card
+    # No marker and no `_above_100k_tokens` field survives into the selected
+    # card (a well-formed card carries no unrecognised one, but the filter
+    # does not rely on that).
+    selected = {k: v for k, v in card.items()
+                if k != CLAUDE_WHOLE_REQUEST_THRESHOLD_KEY
+                and not k.endswith(CLAUDE_WHOLE_REQUEST_TIER_SUFFIX)}
+    for base, tier in CLAUDE_WHOLE_REQUEST_TIER_FIELDS:
+        selected[base] = card[tier]
+    return selected
+
+
+def _whole_request_cache_create_cost(card, flat, h_raw) -> float:
+    """Cache-creation USD on a whole-request card: direct flat arithmetic
+    (#929 spec §5), never the legacy 200K band partition, which is not
+    float-identical to it."""
+    if flat <= 0:
+        return 0.0
+    rate_5m = card.get("cache_creation_input_token_cost", 0.0)
+    h = 0 if h_raw is None else max(0, min(int(h_raw), flat))
+    if h == 0:
+        return flat * rate_5m
+    rate_1h = (card.get("input_cost_per_token", 0.0)
+               * current_pricing_snapshot().cache_write_1h_multiplier)
+    return (flat - h) * rate_5m + h * rate_1h
+
+
 def _cache_create_cost(pricing: dict, flat: int, h_raw, tiered) -> float:
     """USD for one entry's cache-CREATION tokens, priced by TTL (#195).
 
@@ -1320,8 +1481,15 @@ def _calculate_entry_cost(
     usage: dict[str, Any],
     mode: str = "auto",
     cost_usd: float | None = None,
+    *,
+    prompt_tokens_for_tier: int | None = None,
 ) -> float:
-    """Calculate USD cost for a single API call entry."""
+    """Calculate USD cost for a single API call entry.
+
+    ``prompt_tokens_for_tier`` only feeds whole-request card selection (#929):
+    a caller pricing a synthetic subset of a real request passes that
+    request's real prompt total so the subset bills at the request's card.
+    """
     if mode == "display":
         return cost_usd if cost_usd is not None else 0.0
     if mode == "auto" and cost_usd is not None:
@@ -1330,6 +1498,18 @@ def _calculate_entry_cost(
     pricing = _resolve_model_pricing(model)
     if pricing is None:
         return 0.0
+    # #929: a whole-request card selects ONE card for this request. A legacy
+    # card skips selection entirely and runs the pre-#929 expressions below
+    # byte-for-byte (the selector would return it unchanged anyway).
+    whole_request = _is_whole_request_card(pricing)
+    if whole_request:
+        pricing = _select_claude_request_card(
+            pricing,
+            input_tokens=usage.get("input_tokens", 0),
+            cache_creation_tokens=usage.get("cache_creation_input_tokens", 0),
+            cache_read_tokens=usage.get("cache_read_input_tokens", 0),
+            prompt_tokens_for_tier=prompt_tokens_for_tier,
+        )
 
     def _tiered(tokens: int, base_key: str, tiered_key: str) -> float:
         base_rate = pricing.get(base_key, 0.0)
@@ -1361,12 +1541,22 @@ def _calculate_entry_cost(
     # arithmetic or comparison, and the `h_raw` side does its own `int()`
     # inside the clamp (which IS load-bearing there: `min(int(h_raw), flat)`
     # is what pins the 1h portion to whole tokens).
-    cache_create_cost = _cache_create_cost(
-        pricing,
-        usage.get("cache_creation_input_tokens", 0),
-        usage.get("cache_creation_1h_input_tokens"),
-        _tiered,
-    )
+    if not whole_request:
+        cache_create_cost = _cache_create_cost(
+            pricing,
+            usage.get("cache_creation_input_tokens", 0),
+            usage.get("cache_creation_1h_input_tokens"),
+            _tiered,
+        )
+    else:
+        # The selected card has no `_above_200k_tokens` key, so `_tiered`
+        # prices input, output and cache read as tokens x selected rate; cache
+        # creation takes the direct flat form, not the 200K band partition.
+        cache_create_cost = _whole_request_cache_create_cost(
+            pricing,
+            usage.get("cache_creation_input_tokens", 0),
+            usage.get("cache_creation_1h_input_tokens"),
+        )
     cache_read_cost = _tiered(
         usage.get("cache_read_input_tokens", 0),
         "cache_read_input_token_cost",

package/bin/_lib_pricing_check.py

@@ -1,9 +1,12 @@
 """Pure-fn kernel for the pricing-freshness check (spec 2026-05-29).
 
-No I/O, no import of `cctally`/`_lib_pricing` at module scope — every
-dependency (pricing predicates, tables, observed rows, LiteLLM snapshot)
-is passed in by the I/O glue in bin/cctally. Re-exported there like the
-other _lib_* kernels.
+No I/O, and no import of `cctally`/`_lib_pricing` at module scope. The
+tables, observed rows and LiteLLM snapshot are passed in by the I/O glue in
+bin/cctally, which re-exports this module like the other _lib_* kernels.
+The one exception is `check_table_shapes`, which resolves the pure
+`_lib_pricing` kernel per call through `_pricing()` (#929) so the
+whole-request declaration rule has a single definition shared with the
+cost engine's selector.
 """
 from __future__ import annotations
 
@@ -186,6 +189,13 @@ def expired_allowlist_entries(allowlist, as_of_date) -> list:
     ]
 
 
+def _pricing():
+    """The pricing kernel, resolved per call (never bound at module scope —
+    see this module's docstring). Mirrors ``_lib_cost_provenance._pricing``."""
+    import _lib_pricing
+    return _lib_pricing
+
+
 _CLAUDE_REQUIRED = ("input_cost_per_token", "output_cost_per_token",
                     "cache_creation_input_token_cost", "cache_read_input_token_cost")
 _CODEX_REQUIRED = ("input_cost_per_token", "cache_read_input_token_cost",
@@ -211,8 +221,14 @@ def check_table_shapes(claude_tbl, codex_tbl, zero_sentinels) -> list:
         if cost_fields and all(float(v) == 0.0 for v in cost_fields.values()) and not allow_zero:
             problems.append(f"{model}: all cost fields zero but not a documented sentinel")
 
+    # #929: a Claude whole-request (prompt-length) tier is all-or-nothing.
+    # The definition of "well formed" lives beside the selector that refuses a
+    # malformed card, so this check and the cost engine can never disagree.
+    declaration_problems = _pricing().claude_whole_request_declaration_problems
     for model, body in claude_tbl.items():
         _check(model, body, _CLAUDE_REQUIRED, allow_zero=False)
+        for p in declaration_problems(body):
+            problems.append(f"{model}: {p}")
     for model, body in codex_tbl.items():
         _check(model, body, _CODEX_REQUIRED, allow_zero=model in zero_sentinels)
     return problems

package/bin/_lib_quarantine.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""The one parser of tests/quarantine.json, the reviewed flaky-test list (spec 4.3).
+
+Stdlib only. An entry's `id` takes one of two forms:
+
+* a pytest node id, `tests/<file>.py::<node>` (a prefix: pytest's --deselect
+  semantics cover every parametrization of a listed function);
+* a harness case, `harness:<harness-name>::<case>`, where `<harness-name>` is
+  the `NAME` of `bin/cctally-NAME-test` and `<case>` is one scenario of that
+  harness's own case inventory (`bin/cctally-NAME-test --list-cases`).
+
+`bin/cctally-test-all`, `bin/_lib_merge_gate.py` and the quick gate read the
+list through this module; the scheduled CI quarantine leg calls its CLI. An
+absent list quarantines nothing (the public mirror may carry none); a list
+that exists but cannot be read raises QuarantineError, never "nothing listed".
+
+CLI (exit 0, or 2 on an unreadable list or bad usage):
+    python3 bin/_lib_quarantine.py pytest-ids
+    python3 bin/_lib_quarantine.py harness-cases <harness>
+"""
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+import re
+import subprocess
+import sys
+
+LIST_PATH = Path('tests') / 'quarantine.json'
+FIELDS = ('id', 'evidence', 'invariant', 'issue', 'replacement', 'reviewBy')
+PYTEST_ID = re.compile(r'tests/[^:\s]+\.py::\S+')
+HARNESS_ID = re.compile(r'harness:([a-z0-9][a-z0-9-]*)::([A-Za-z0-9][A-Za-z0-9_.-]*)')
+
+
+class QuarantineError(ValueError):
+    """tests/quarantine.json exists but is not a list this parser can apply."""
+
+
+@dataclass(frozen=True)
+class Entry:
+    id: str
+    kind: str                 # 'pytest' or 'harness'
+    harness: str | None       # the harness name for a harness case
+    case: str | None          # the case name for a harness case
+    fields: dict
+
+
+def parse_id(entry_id: str) -> tuple[str, str | None, str | None]:
+    """(kind, harness, case) of one id; QuarantineError for any other form."""
+    if not isinstance(entry_id, str):
+        raise QuarantineError(f'an entry id must be a string, not {entry_id!r}')
+    if PYTEST_ID.fullmatch(entry_id):
+        return 'pytest', None, None
+    match = HARNESS_ID.fullmatch(entry_id)
+    if match:
+        return 'harness', match.group(1), match.group(2)
+    raise QuarantineError(
+        f'{entry_id!r} is neither a pytest node id (tests/<file>.py::<node>) '
+        'nor a harness case (harness:<harness>::<case>)')
+
+
+def parse(doc) -> list[Entry]:
+    if not isinstance(doc, list):
+        raise QuarantineError('expected a JSON list of entries')
+    entries = []
+    for item in doc:
+        if not isinstance(item, dict):
+            raise QuarantineError(f'expected each entry to be an object, not {item!r}')
+        kind, harness, case = parse_id(item.get('id'))
+        entries.append(Entry(item['id'], kind, harness, case, dict(item)))
+    ids = [e.id for e in entries]
+    if len(set(ids)) != len(ids):
+        raise QuarantineError('duplicate entry ids: ' + ', '.join(
+            sorted({i for i in ids if ids.count(i) > 1})))
+    return entries
+
+
+def load_path(path: Path) -> list[Entry]:
+    path = Path(path)
+    if not path.is_file():
+        return []
+    try:
+        doc = json.loads(path.read_text(encoding='utf-8'))
+    except (OSError, ValueError) as exc:
+        raise QuarantineError(f'{path}: {exc}') from None
+    return parse(doc)
+
+
+def load(repo: Path) -> list[Entry]:
+    return load_path(Path(repo) / LIST_PATH)
+
+
+def pytest_ids(entries) -> list[str]:
+    return [e.id for e in entries if e.kind == 'pytest']
+
+
+def harness_cases(entries, harness: str) -> list[str]:
+    return [e.case for e in entries if e.kind == 'harness' and e.harness == harness]
+
+
+def harness_inventory(repo: Path, harness: str, *, timeout: float = 60) -> list[str]:
+    """The case names `bin/cctally-<harness>-test --list-cases` prints.
+
+    QuarantineError when the harness does not exist or has no case inventory:
+    a harness case that cannot be validated against the harness is not
+    quarantinable."""
+    script = Path(repo) / 'bin' / f'cctally-{harness}-test'
+    if not script.is_file():
+        raise QuarantineError(f'harness:{harness}: bin/cctally-{harness}-test does not exist')
+    proc = subprocess.run([str(script), '--list-cases'], cwd=repo, capture_output=True,
+                          text=True, timeout=timeout)
+    if proc.returncode != 0:
+        raise QuarantineError(f'harness:{harness}: --list-cases exited {proc.returncode}: '
+                              + (proc.stderr or proc.stdout).strip()[-400:])
+    return [line.strip() for line in proc.stdout.splitlines() if line.strip()]
+
+
+def validate_harness_cases(repo: Path, entries) -> None:
+    """Each harness case names an existing harness and a case in its inventory."""
+    inventories: dict[str, list[str]] = {}
+    for entry in entries:
+        if entry.kind != 'harness':
+            continue
+        if entry.harness not in inventories:
+            inventories[entry.harness] = harness_inventory(repo, entry.harness)
+        if entry.case not in inventories[entry.harness]:
+            raise QuarantineError(f'{entry.id}: no case {entry.case!r} in the '
+                                  f'{entry.harness} harness inventory')
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    repo = Path(__file__).resolve().parents[1]
+    if len(argv) >= 2 and argv[0] == '--repo':
+        repo, argv = Path(argv[1]), argv[2:]
+    try:
+        if argv == ['pytest-ids']:
+            out = pytest_ids(load(repo))
+        elif len(argv) == 2 and argv[0] == 'harness-cases':
+            out = harness_cases(load(repo), argv[1])
+        else:
+            print('usage: _lib_quarantine.py [--repo DIR] pytest-ids | harness-cases <harness>',
+                  file=sys.stderr)
+            return 2
+    except QuarantineError as exc:
+        print(f'quarantine: {exc}', file=sys.stderr)
+        return 2
+    for item in out:
+        print(item)
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/bin/_lib_quota_calibration.py

@@ -62,6 +62,10 @@ class ApplyRejection(str, enum.Enum):
 
     UNSUPPORTED_COMPOSITION = "unsupported-composition"
     EMPTY_POPULATION = "no-local-history"
+    #: The requested interval, or an entry of the population, lies outside
+    #: the regime's own coefficient era (#978 spec 4.6). Units from another
+    #: era are never divided by this regime's units-per-point.
+    UNVALIDATED_COEFFICIENT_ERA = "unvalidated-coefficient-era"
 
 
 @dataclasses.dataclass(frozen=True)
@@ -88,6 +92,9 @@ class ValidatedRegime:
     class_shares: dict
     family_radius: "float | None"
     class_radius: "float | None"
+    #: The id of the coefficient era the regime was fitted in, always a
+    #: member of `qm.COEFFICIENT_ERAS` (#978).
+    coefficient_era: str
     qualifications: tuple = ()
 
 
@@ -196,6 +203,13 @@ def validate_regime(raw, *, account_key, expected_fingerprint,
     if isinstance(revision, bool) or not isinstance(revision, int) \
             or revision != expected_revision:
         return RegimeRejection.REVISION
+    # #978 spec 4.5: under the current constants a regime names the
+    # coefficient era it was fitted in. Missing or unknown is malformed, never
+    # a guess at an era; a regime from an older build has already been
+    # reported above as a fingerprint mismatch.
+    era = qm.era_by_id(raw.get("coefficientEra"))
+    if era is None:
+        return RegimeRejection.MALFORMED
 
     point = raw.get("unitsPerPoint")
     if not _finite(point) or point <= 0.0:
@@ -256,31 +270,42 @@ def validate_regime(raw, *, account_key, expected_fingerprint,
         class_shares=class_shares,
         family_radius=family_radius,
         class_radius=class_radius,
+        coefficient_era=era.id,
         qualifications=marks,
     )
 
 
-def population_units(entries) -> float:
+def population_units(entries, *, era) -> float:
     """Summed weighted quota units over the general-meter entries.
 
     The same filter `_cctally_quota_model.analyse_account` applies to the
     current week: an entry whose family does not drain the general weekly
     meter contributes nothing, and one whose cache-write split is unknown is
-    skipped rather than priced at zero.
+    skipped rather than priced at zero. Every entry is weighted with `era`,
+    the regime's own coefficient era (#978).
+
+    An entry `era` does not cover raises `CoefficientEraMismatch`, as the
+    kernel's population functions do (#978 spec 4.2, invariant 5): skipping
+    it would divide part of the population by the regime's budget and report
+    the result as the whole.
     """
     total = 0.0
     for entry in entries:
         if qm.family_participation(qm.normalize_family(entry.model)) \
                 != "general":
             continue
-        units = qm.weighted_units(entry)
-        if units is None:
+        weighed = qm.weigh_entry(entry, era)
+        if weighed.cause == qm.ERA_UNAVAILABLE:
+            raise qm.CoefficientEraMismatch(
+                f"entry.at {entry.at.isoformat()} lies outside coefficient "
+                f"era {era.id!r}")
+        if weighed.units is None:
             continue
-        total += units
+        total += weighed.units
     return total
 
 
-def apply_regime(regime: ValidatedRegime, entries
+def apply_regime(regime: ValidatedRegime, entries, *, interval
                  ) -> "AppliedQuota | ApplyRejection":
     """Modelled consumption for `entries` under `regime`.
 
@@ -288,8 +313,28 @@ def apply_regime(regime: ValidatedRegime, entries
     status, because that status describes S1's fit population and this one is
     the consumer's. The arithmetic afterwards reproduces the kernel's, so a
     consumer never re-derives the inversion by hand.
+
+    `interval` is the half-open `[start, end)` the caller models, which a
+    consumer extrapolating over a whole week must pass as that week (#978
+    spec 4.6). Two independent checks run before any aggregation: the
+    interval must lie inside the regime's coefficient era, and so must every
+    entry. The interval check is not implied by the entry check — a week
+    starting before the era whose retained entries all fall after its start
+    is in-era entry by entry, yet modelling the whole week is forbidden.
     """
-    aggregated = qm.aggregate_composition(entries)
+    era = qm.era_by_id(regime.coefficient_era)
+    if era is None:
+        return ApplyRejection.UNVALIDATED_COEFFICIENT_ERA
+    start, end = interval
+    qm.require_aware(start, "interval.start")
+    qm.require_aware(end, "interval.end")
+    era_start, era_end = qm.era_bounds(era)
+    if start < era_start or (era_end is not None and end > era_end):
+        return ApplyRejection.UNVALIDATED_COEFFICIENT_ERA
+    entries = list(entries)
+    if any(not qm.era_contains(era, entry.at) for entry in entries):
+        return ApplyRejection.UNVALIDATED_COEFFICIENT_ERA
+    aggregated = qm.aggregate_composition(entries, era=era)
     if aggregated is None:
         return ApplyRejection.EMPTY_POPULATION
     family_shares, class_shares = aggregated
@@ -298,7 +343,7 @@ def apply_regime(regime: ValidatedRegime, entries
                            regime.class_shares, regime.class_radius):
         return ApplyRejection.UNSUPPORTED_COMPOSITION
 
-    units = population_units(entries)
+    units = population_units(entries, era=era)
     if not _finite(units) or units < 0.0:
         return ApplyRejection.EMPTY_POPULATION
 

package/bin/_lib_quota_copy.py

@@ -70,7 +70,8 @@ _LONG_FORM: dict = {
         "the models in use sit outside the mix the calibration was fitted "
         "over",
     "unvalidated-coefficient-era":
-        "this window predates the token weights the model is validated for",
+        "this window is not inside a single coefficient era the token "
+        "weights are validated for",
     "stale":
         "the stored calibration was fitted under different constants, so it "
         "no longer describes this build",