dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/tool_stream.py

@@ -0,0 +1,393 @@
+"""TS — the stall verdict: *is the tool loop producing new bytes, or just spinning?*
+
+docs/145 — the loop-economics axis. `arg_provenance` (docs/143) and the intervention
+ladder (docs/144) are both *prevent-down* on the **Integrity** verifier slice, and both
+**vanish on a strong model** — a model that reads-before-it-writes mints nothing, so the
+detector catches nothing and adds nothing. Their ceiling is the *minting rate*, which → 0
+as the model improves.
+
+This module opens the axis neither doc built. A cheap model on a long horizon **thrashes**:
+it re-issues the same read, polls for an eventual-consistency write to land, or loops
+without progress until it times out at `max_iterations` with the task half-finished. The
+benchmark's own headline is that success **decays monotonically with horizon** (~35 %@4 steps
+→ <20 %@16). A slice of that decay is **not planning** (the off-limits +14–35 pp lever) — it
+is the agent failing to *use* a value it already received. This leaf detects that slice and
+lets a consumer **re-surface the env-authored value the agent already holds**, converting a
+doomed re-read loop into a finished task on the **same budget**. It is the first DOS lever on
+this benchmark that can move success **UP** (add a finishing step) rather than only prevent a
+wrong one — and the first whose value is **independent of minting** (it fires on *any* looping
+model, including a strong one stuck on eventual consistency).
+
+This module is `liveness.classify`'s sibling — a **pure** verdict function, re-aimed off git
+onto the in-process tool-result stream:
+
+    liveness.classify     (ProgressEvidence, policy)  -> LivenessVerdict   (git/journal stream)
+    tool_stream.classify_stream (ToolStream, policy)  -> StreamVerdict     (tool-result stream)
+                          ^ THIS module
+
+`liveness` asks "did the GIT/JOURNAL state advance?"; `tool_stream` asks "did the TOOL-RESULT
+stream advance, or did the env return the same bytes again?" Same temporal-distrust shape,
+different stream — the `journal_delta`-vs-`git_delta` "different input, separate leaf" split
+the kernel already uses (and the `recurring_wedge`-vs-`wedge_reason` precedent).
+
+Why it is byte-clean (the §5a survival argument)
+================================================
+
+The crux: does this survive the **mirror-verifier trap** (docs/141, docs/143 §5a) where the
+obvious "is the agent making PROGRESS?" version does not? Walk the provenance of a `StreamStep`:
+
+  * `tool_name` / `args_digest` — the **agent** authored these (it chose the call).
+  * `result_digest`            — the **gym MCP server** authored these (it produced the result).
+
+The reader's only question is **"is this env-authored `result_digest` byte-identical to one the
+env already returned, N times in a row?"** — *provenance-of-the-identity-of-repeated-output*, a
+pure byte question about **env-authored** bytes. The agent did **not** author the *identity* of
+its own repeated tool results; the gym did. So the signal cannot be forged in the agent's favor.
+The dangerous version — "is the agent making real progress / has it done the right thing yet?" —
+is a **satisfaction predicate** the wrapper would author from agent-visible prose (forgeable);
+this reader **never asks it.** "The same bytes came back N times" is a measured fact about the
+env's outputs, not a judgment of the agent. No answer key, no held-out state, no oracle plan —
+exactly `arg_provenance`'s provenance-of-a-string honesty, re-aimed from "is this id minted?" to
+"did this exact output repeat?".
+
+The honest hole, named (not buried)
+===================================
+
+**Eventual-consistency polling is a legitimate reason to re-read with the same result.** A task
+that correctly waits for an async write to land produces identical reads until it lands — a true
+REPEATING that is *not* a stall. This is why the intervention a consumer attaches to REPEATING
+must be a **WARN that re-surfaces the value, never a cut**: re-presenting bytes the agent already
+holds is harmless if the agent was right to wait (it ignores a value it does not yet need) and
+helpful if it was stuck (it gets the value it kept failing to use). The `ignore_tools` allow-list
+lets a host exempt known pollers from the reader entirely. The verdict itself only REPORTS; the
+turn-preserving discipline lives in the consumer (the docs/99 advisory line, the docs/144 −9 pp
+intervention-cost lesson made structural).
+
+⚓ Pure kernel, I/O on the edge (the dos idiom — mirrors `liveness.classify`,
+`arg_provenance.classify_call`, `churn.decide_coalesce`): `classify_stream(ToolStream, policy)
+-> StreamVerdict` is a frozen tuple of digests in, a frozen verdict out. The CALLER computes the
+`args_digest` / `result_digest` at the boundary (it hashes the normalized args + the result
+bytes the gym returned); the kernel **hashes nothing live**, reads no clock, no disk. That is
+what lets the whole verdict be replay-tested on frozen fixtures with zero benchmark/LLM/MCP
+access — the keystone the audit calls "testable with zero benchmark access."
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# The typed stall verdict — three states, mutually exclusive (the Liveness shape).
+# ---------------------------------------------------------------------------
+class StreamState(str, enum.Enum):
+    """The typed stall verdict over a tool-result stream — three states.
+
+    `str`-valued so it round-trips through a CLI token / JSON / exit-code map without a
+    lookup table (mirrors `liveness.Liveness`, `arg_provenance.ProvenanceStance`).
+
+      ADVANCING — the recent window is producing NEW env-authored bytes: the most recent
+                  `(tool, args, result_digest)` triple is not a long consecutive repeat.
+                  The loop is moving; no intervention. Also the floor when the stream is too
+                  short to judge a repeat (fewer than `repeat_n` steps) — too young to accuse.
+      REPEATING — the SAME `(tool, args, result_digest)` triple has recurred `repeat_n`
+                  consecutive times (but fewer than `stall_n`): the agent is re-issuing a
+                  call the env answers identically — no new information is entering the loop.
+                  The actionable rung — a consumer re-surfaces the repeated env value (WARN).
+      STALLED   — the repeat run has reached `stall_n` consecutive identical triples: the
+                  loop is almost certainly doomed to time out. The hard rung — a host MAY opt
+                  a turn-preserving BLOCK to it (re-surface + reclaim the iteration); the
+                  default still only re-surfaces (a STALLED on a legitimately-polling task is
+                  a read the agent needed).
+    """
+
+    ADVANCING = "ADVANCING"  # the tool stream is producing new env-authored bytes
+    REPEATING = "REPEATING"  # the same (tool, args, result) triple is recurring (no new info)
+    STALLED = "STALLED"      # the repeat run is long enough to be near-certainly doomed
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+# ---------------------------------------------------------------------------
+# The thresholds — policy, not mechanism (the LivenessPolicy seam).
+# ---------------------------------------------------------------------------
+@dataclass(frozen=True)
+class StreamPolicy:
+    """The run-length windows that separate ADVANCING/REPEATING/STALLED — policy, not mechanism.
+
+    The same "mechanism is kernel, thresholds are config" split as `LivenessPolicy`'s
+    `grace_ms`/`spin_ms`. Defaults are GENERIC (no host tuning); a workspace declares its own
+    in `dos.toml [tool_stream]` read back through `SubstrateConfig` (the closed-config-as-data
+    pattern, like `[liveness]` / `[reasons]` / `[intervention]`).
+
+      repeat_n     — the consecutive-identical-triple run-length at which the loop is REPEATING.
+                     Default 3: the first two identical results may be a benign re-check; the
+                     THIRD identical result is where a no-progress loop is established. Mirrors
+                     `churn.DEFAULT_MIN_COALESCE_RUN`'s "the FIRST stands alone, the cycle starts
+                     at the next" reasoning, one rung later (a tool re-read is cheaper to repeat
+                     once than a no-op commit, so the floor is 3 not 2).
+      stall_n      — the run-length at which REPEATING hardens to STALLED (the BLOCK-eligible
+                     rung). Default 5. Must be ≥ repeat_n (validated) — STALLED is strictly more
+                     repetition than REPEATING.
+      ignore_tools — a host's allow-list of known-poller tool names (normalized lower). A step
+                     whose tool is on this list is NEVER counted toward a repeat run — it breaks
+                     the run as if it were new (eventual-consistency pollers a host KNOWS about
+                     are exempted at the source, so the reader never false-fires on them).
+    """
+
+    repeat_n: int = 3
+    stall_n: int = 5
+    ignore_tools: frozenset = frozenset()
+
+    def __post_init__(self) -> None:
+        if self.repeat_n < 1:
+            raise ValueError("repeat_n must be >= 1")
+        if self.stall_n < self.repeat_n:
+            raise ValueError(
+                f"stall_n ({self.stall_n}) must be >= repeat_n ({self.repeat_n}) — "
+                f"STALLED is strictly more repetition than REPEATING"
+            )
+
+
+DEFAULT_POLICY = StreamPolicy()
+
+
+# ---------------------------------------------------------------------------
+# Frozen inputs — the pure datum a caller gathers at the boundary and hands in.
+# ---------------------------------------------------------------------------
+@dataclass(frozen=True)
+class StreamStep:
+    """One step of the tool-result stream, as the pure datum the verdict sees.
+
+    The caller computes the digests at the boundary (it normalizes the args and hashes them;
+    it hashes the result BYTES the gym returned). The kernel never hashes a live value — it
+    compares pre-computed digests, the `liveness` "clock is injected, never read inside"
+    discipline applied to hashing.
+
+      tool_name     — the tool that was called (normalized lower at the boundary is fine; the
+                      verdict casefolds for the `ignore_tools` test). Agent-authored.
+      args_digest   — a stable digest of the call's NORMALIZED arguments (sorted keys, canonical
+                      scalar repr). Agent-authored. Part of the repeat-identity key so two
+                      reads of DIFFERENT rows are not a repeat.
+      result_digest — a stable digest of the RESULT bytes the env returned. ENV-AUTHORED — the
+                      load-bearing field: two steps repeat only if the env returned the SAME
+                      bytes, which the agent cannot forge. `None` marks a step with no result
+                      (a call that errored / returned nothing) — it never matches another step,
+                      so it breaks a run rather than extending it (the fail-safe: no result is
+                      not "the same result").
+    """
+
+    tool_name: str
+    args_digest: str
+    result_digest: Optional[str] = None
+
+    def _key(self, policy: "StreamPolicy") -> "Optional[tuple[str, str, str]]":
+        """The repeat-identity key, or None if this step can never match another.
+
+        None when: the result is absent (no result is not 'the same result'), OR the tool is on
+        the `ignore_tools` allow-list (a known poller is exempt at the source). A None-keyed
+        step breaks any in-progress repeat run — the fail-safe direction (when in doubt, the
+        loop is NOT stalled)."""
+        if self.result_digest is None:
+            return None
+        if self.tool_name.casefold() in {t.casefold() for t in policy.ignore_tools}:
+            return None
+        return (self.tool_name.casefold(), self.args_digest, self.result_digest)
+
+
+@dataclass(frozen=True)
+class ToolStream:
+    """The whole tool-result stream accumulated so far — the `ProgressEvidence` analogue.
+
+    `steps` is a tuple of `StreamStep` in call order. Empty (`()`) or short (< `repeat_n`) reads
+    as ADVANCING — too little has happened to prove a no-progress loop (the load-bearing
+    too-young-to-judge floor, the `liveness` young-and-alive guard's sibling). The stream is
+    kept WHOLE (not pre-reduced) so the verdict measures the run-length ending at the LATEST
+    step — the live "is it stuck right now?" question, not a whole-history histogram.
+    """
+
+    steps: tuple[StreamStep, ...] = ()
+
+
+# ---------------------------------------------------------------------------
+# Frozen verdict — the folded answer, advisory only (the LivenessVerdict shape).
+# ---------------------------------------------------------------------------
+@dataclass(frozen=True)
+class StreamVerdict:
+    """The single verdict `classify_stream` returns — typed state + the legible run detail.
+
+    `state` is the typed `StreamState`. `repeat_run` is the length of the consecutive-identical
+    run ending at the latest step (1 = the latest step is unique; ≥ `repeat_n` = REPEATING).
+    `repeated_step` is the `StreamStep` that is repeating (None when ADVANCING) — the consumer
+    re-surfaces ITS env-authored `result_digest`/value, so the WARN names the exact prior output
+    the agent already holds (never a fabricated one). `reason` is the one-line operator summary.
+    Advisory: never raises, never dispatches — the consumer reads `state` and decides whether to
+    re-surface.
+    """
+
+    state: StreamState
+    repeat_run: int
+    repeated_step: Optional[StreamStep]
+    reason: str
+
+    def to_dict(self) -> dict:
+        rs = self.repeated_step
+        return {
+            "state": self.state.value,
+            "repeat_run": self.repeat_run,
+            "repeated_step": (
+                {
+                    "tool_name": rs.tool_name,
+                    "args_digest": rs.args_digest,
+                    "result_digest": rs.result_digest,
+                }
+                if rs is not None
+                else None
+            ),
+            "reason": self.reason,
+        }
+
+
+# ---------------------------------------------------------------------------
+# The pure verdict — consecutive-identical run-length, lifted from churn.
+# ---------------------------------------------------------------------------
+def _trailing_run(stream: ToolStream, policy: StreamPolicy) -> "tuple[int, Optional[StreamStep]]":
+    """The length of the consecutive-identical-key run ENDING at the latest step, and the step
+    that repeats. PURE — the `churn.decide_coalesce` consecutive-same-cause run-length, lifted
+    off git history onto the tool stream.
+
+    Walks backward from the last step while the repeat-identity key matches. A step whose key is
+    None (no result, or an `ignore_tools` poller) cannot extend or start a run — the fail-safe:
+    an absent/exempt result is never 'the same result', so it can only BREAK a run. Returns
+    (run_length, repeated_step) — run_length 0 with an empty stream, 1 when the latest step does
+    not match the one before it (or its key is None)."""
+    steps = stream.steps
+    if not steps:
+        return 0, None
+    last = steps[-1]
+    last_key = last._key(policy)
+    if last_key is None:
+        # The latest step has no comparable result (absent / exempt poller) — not a repeat.
+        return 1, None
+    run = 1
+    for prev in reversed(steps[:-1]):
+        if prev._key(policy) == last_key:
+            run += 1
+        else:
+            break
+    return run, (last if run >= 2 else None)
+
+
+def classify_stream(
+    stream: ToolStream, policy: StreamPolicy = DEFAULT_POLICY
+) -> StreamVerdict:
+    """Classify the tool-result stream's stall state from the accumulated steps. PURE — no I/O.
+
+    Reads the ladder top to bottom (this function IS the answer to "is the loop stuck?"):
+
+      1. ADVANCING — the trailing identical-run is shorter than `repeat_n` (incl. an empty or
+         too-short stream): the loop is producing new env-authored bytes, or has not repeated
+         long enough to accuse. The benign / no-action verdict (the `liveness` young-and-alive
+         floor's sibling).
+      2. REPEATING — the trailing run has reached `repeat_n` but is shorter than `stall_n`: the
+         same `(tool, args, result)` triple recurred — no new information is entering the loop.
+         The actionable rung; the consumer re-surfaces `repeated_step`'s env value (WARN).
+      3. STALLED   — the trailing run has reached `stall_n`: long enough to be near-certainly
+         doomed. The hard rung (a host MAY opt a turn-preserving BLOCK).
+
+    The ADVANCING/REPEATING boundary is the `repeat_n` run-length; the REPEATING/STALLED boundary
+    is `stall_n`. Both are pure counts over env-authored `result_digest` identity — never a
+    judgment of whether the agent is *succeeding* (that would be the §5a satisfaction predicate
+    this module exists to avoid). The verdict only REPORTS; the turn-preserving re-surface (never
+    a cut) is the consumer's, the docs/99 advisory line.
+    """
+    run, repeated = _trailing_run(stream, policy)
+
+    if run >= policy.stall_n:
+        return StreamVerdict(
+            state=StreamState.STALLED,
+            repeat_run=run,
+            repeated_step=repeated,
+            reason=(
+                f"the same (tool, args, result) triple repeated {run} consecutive times "
+                f"(>= stall {policy.stall_n}) — the loop is near-certainly doomed; the env "
+                f"returned identical bytes each time (no new information)"
+            ),
+        )
+    if run >= policy.repeat_n:
+        return StreamVerdict(
+            state=StreamState.REPEATING,
+            repeat_run=run,
+            repeated_step=repeated,
+            reason=(
+                f"the same (tool, args, result) triple repeated {run} consecutive times "
+                f"(>= repeat {policy.repeat_n}) — no new env-authored bytes are entering the "
+                f"loop; re-surface the value the agent already received"
+            ),
+        )
+    return StreamVerdict(
+        state=StreamState.ADVANCING,
+        repeat_run=run,
+        repeated_step=None,
+        reason=(
+            f"trailing identical-run {run} (< repeat {policy.repeat_n}) — the tool stream is "
+            f"producing new env-authored bytes (or too short to judge a stall)"
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# The declarative on-ramp — read a policy out of dos.toml (mirror reasons/intervention).
+# ---------------------------------------------------------------------------
+def policy_from_table(table: dict) -> StreamPolicy:
+    """Turn a parsed `[tool_stream]` TOML table into a `StreamPolicy`. PURE (no I/O).
+
+    `table` is `{repeat_n?, stall_n?, ignore_tools?}` — the shape
+    `tomllib.load(...)["tool_stream"]` yields. Missing keys fall back to the generic defaults;
+    a malformed value raises (via `StreamPolicy.__post_init__`), so a bad declaration fails
+    loudly at load. `ignore_tools` accepts a list or a single string.
+    """
+    if not table:
+        return DEFAULT_POLICY
+    ig = table.get("ignore_tools", ())
+    if isinstance(ig, str):
+        ig = (ig,)
+    return StreamPolicy(
+        repeat_n=int(table.get("repeat_n", DEFAULT_POLICY.repeat_n)),
+        stall_n=int(table.get("stall_n", DEFAULT_POLICY.stall_n)),
+        ignore_tools=frozenset(str(t) for t in ig),
+    )
+
+
+def load_from_toml(
+    path: "Path | str", *, base: StreamPolicy = DEFAULT_POLICY
+) -> StreamPolicy:
+    """Build a `StreamPolicy` from a `dos.toml`'s `[tool_stream]` table.
+
+    Returns `base` unchanged when the file is absent, has no `[tool_stream]` table, or
+    `tomllib` is unavailable — the declarative path is purely additive, so a missing/empty
+    config degrades to the generic default, never an error. A *present but malformed* table
+    raises (`StreamPolicy.__post_init__`). Reads with `utf-8-sig` to strip a PowerShell-written
+    BOM (the `reasons.load_from_toml` / `intervention.load_from_toml` fix). The OVERRIDE shape
+    (the `[stamp]`/`[liveness]` pattern): a present table replaces the windows wholesale; an
+    absent one inherits `base`.
+    """
+    p = Path(path)
+    if not p.exists():
+        return base
+    try:
+        import tomllib  # py3.11+
+    except ModuleNotFoundError:  # pragma: no cover - py<3.11 fallback
+        try:
+            import tomli as tomllib  # type: ignore
+        except ModuleNotFoundError:
+            return base
+    data = tomllib.loads(p.read_text(encoding="utf-8-sig"))
+    table = data.get("tool_stream")
+    if not isinstance(table, dict) or not table:
+        return base
+    return policy_from_table(table)

dos/tool_stream_eval.py

@@ -0,0 +1,226 @@
+"""The stall-reader evaluation harness — score a `StreamPolicy` by its NET RECOVERY.
+
+docs/145 §9 — the per-axis eval, the `judge_eval` / `overlap_eval` / `intervention_eval`
+discipline re-aimed at the loop-economics axis. Every DOS axis ships an eval that turns its
+thresholds from a hunch into a measured, per-deployment decision (the research-friendliness
+thesis, docs/90 §2). The stall reader's two thresholds (`repeat_n` / `stall_n`) and its
+`ignore_tools` allow-list need exactly that instrument: a backtest that answers **"on this
+deployment's real tool streams, does firing a re-surface on REPEATING recover stuck tasks
+more often than it false-fires on a legitimate poller?"**
+
+The decisive numbers (the dual of `intervention_eval`'s wasted-disruption rate):
+
+  * **recovered_rate** — of the streams that were ACTUALLY stuck (the agent had the value and
+    was looping), the fraction this policy fired REPEATING/STALLED on. Recall-of-action: a
+    too-timid policy (`repeat_n` set huge) scores ~0 — it never fires, never recovers.
+  * **false_resurface_rate** — of the streams that were LEGITIMATELY repeating (eventual-
+    consistency polling, a correct re-check), the fraction this policy ALSO fired on. The
+    dangerous cell — the §3 honest hole made measurable. A re-surface on a legitimate poller is
+    *harmless by design* (re-presenting bytes the agent holds), but a high rate means the
+    threshold is too eager and the host should raise `repeat_n` or grow `ignore_tools`.
+
+The honesty stance (the same as judge_eval / overlap_eval / intervention_eval)
+==============================================================================
+
+The labels are the RESEARCHER's ground truth, never the reader's:
+
+  * `actually_stuck`  — was the agent ACTUALLY looping with a value it already had, and would a
+    re-surface have unstuck it? Known from the replay (a labelled stuck stream), NOT from the
+    `result_digest` repetition the reader keys on. The `overlap_eval.collided` discipline.
+  * `legit_polling`   — was the repetition a LEGITIMATE re-check (eventual-consistency wait, an
+    idempotent retry that later succeeds)? The false-fire denominator.
+  * `recovered_if_fired` — counterfactual ground truth from the EXECUTED replay: under a
+    re-surface WARN, did the agent then finish? (NOT a guessed label — measured, the
+    `intervention_eval.recovered_if_blocked` discipline.)
+
+Everything is **pure**: it consumes already-built `StreamCase`s, runs each through the SAME
+`tool_stream.classify_stream` the consumer's reader takes (so the grid reflects what would
+actually fire — the `overlap_eval` "score under the floor" discipline), and counts in one
+pass. No I/O, no host names — it sits in the kernel layer beside `tool_stream`.
+
+⚠ This is NOT a detector eval of `arg_provenance`, and NOT `intervention_eval`. It measures the
+STALL READER specifically — does firing on a repeat recover more than it wastes — an axis
+orthogonal to both the mint detector (docs/143) and the actuation ladder (docs/144).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+from dos.tool_stream import (
+    StreamPolicy,
+    StreamState,
+    ToolStream,
+    classify_stream,
+)
+
+
+# ---------------------------------------------------------------------------
+# A labelled example — one replayed tool stream + the GROUND-TRUTH outcome.
+# ---------------------------------------------------------------------------
+@dataclass(frozen=True)
+class StreamCase:
+    """One replayed tool stream + the ground-truth labels for what firing on it would do.
+
+    The `state` the policy assigns is NOT stored — it is DERIVED in `score()` via
+    `classify_stream` from the embedded `stream`, so the scored action can never drift from a
+    hand-labelled state (the label-drift trap, the `intervention_eval` discipline). Every other
+    field is a researcher ground-truth label from a replay, NOT a guess.
+
+    Fields:
+      stream             — the real `ToolStream` accumulated for this episode. The policy is
+                           scored against THIS via `classify_stream` (same path as the consumer's
+                           reader), so the grid measures what would actually fire.
+      actually_stuck     — ground truth: was the agent looping with a value it already had (a
+                           re-surface would help)? The recovered_rate numerator's truth.
+      legit_polling      — ground truth: was the repetition a LEGITIMATE re-check (eventual-
+                           consistency wait / idempotent retry that later succeeds)? The
+                           false-resurface denominator. (A stream can be neither — a normal
+                           advancing run — in which case the reader should not fire at all.)
+      recovered_if_fired — counterfactual ground truth: under a re-surface WARN, did the agent
+                           then finish the task? (Measured in replay, not guessed.)
+      label              — optional human handle (carried, never scored).
+    """
+
+    stream: ToolStream
+    actually_stuck: bool
+    legit_polling: bool
+    recovered_if_fired: bool
+    label: str = ""
+
+
+# ---------------------------------------------------------------------------
+# The report — frozen, @property rates with div-guard, to_dict (mirror intervention_eval).
+# ---------------------------------------------------------------------------
+@dataclass(frozen=True)
+class StreamEvalReport:
+    """A `StreamPolicy` scored over labelled cases — the recovery ledger + the false-fire rate.
+
+    The grid splits the ground-truth crosstab (independent of the policy) from the firing ledger
+    (what the policy actually flagged). The named dangerous cell is `fired_on_polling` — a fire
+    on a legitimately-polling stream (harmless by design, but the signal the threshold is too
+    eager).
+    """
+
+    n: int
+    # ground-truth grid (policy-independent):
+    n_stuck: int                  # actually_stuck (the recoverable population)
+    n_polling: int                # legit_polling (the false-fire denominator)
+    # firing ledger (what the policy did):
+    n_fired: int                  # REPEATING or STALLED assigned
+    n_fired_stuck: int            # fired AND actually_stuck (a useful fire)
+    n_fired_polling: int          # fired AND legit_polling (the dangerous cell)
+    n_recovered: int              # fired_stuck whose recovered_if_fired is True (the payoff)
+
+    # --- derived rates (all guard against divide-by-zero) ---
+
+    @property
+    def recovered_rate(self) -> float:
+        """Of all ACTUALLY-stuck streams, the fraction the policy fired on AND that then
+        recovered — the HEADLINE payoff (the loop-economics analogue of the +Npp the audit
+        chases). A timid policy that never fires scores ~0 here."""
+        return (self.n_recovered / self.n_stuck) if self.n_stuck else 0.0
+
+    @property
+    def fire_recall(self) -> float:
+        """Of all ACTUALLY-stuck streams, the fraction the policy fired on (regardless of whether
+        the agent then recovered) — recall-of-action, the counterweight to the false-fire rate."""
+        return (self.n_fired_stuck / self.n_stuck) if self.n_stuck else 0.0
+
+    @property
+    def false_resurface_rate(self) -> float:
+        """Of all LEGITIMATELY-polling streams, the fraction the policy ALSO fired on — THE
+        DANGEROUS-CELL RATE (the `intervention_eval.wasted_disruption_rate` /
+        `overlap_eval.false_admit_rate` analogue). A re-surface here is harmless by design, but a
+        high rate says the threshold is too eager — raise `repeat_n` or grow `ignore_tools`."""
+        return (self.n_fired_polling / self.n_polling) if self.n_polling else 0.0
+
+    @property
+    def fire_precision(self) -> float:
+        """Of all the streams the policy fired on, the fraction that were actually stuck — how
+        much of the firing was well-aimed (vs spent on a poller or an advancing run)."""
+        return (self.n_fired_stuck / self.n_fired) if self.n_fired else 0.0
+
+    @property
+    def net_positive(self) -> bool:
+        """True iff the policy recovers more stuck streams than it false-fires on pollers — the
+        boolean a `dos tool-stream-eval` exit code could ride (the `intervention_eval.net_harmful`
+        analogue, inverted to the friendly direction). Recovery is a real task win; a false
+        re-surface is harmless-but-noise, so net-positive is `recovered > fired_on_polling`."""
+        return self.n_recovered > self.n_fired_polling
+
+    def to_dict(self) -> dict:
+        return {
+            "n": self.n,
+            "grid": {
+                "stuck": self.n_stuck,
+                "polling": self.n_polling,
+            },
+            "firing": {
+                "fired": self.n_fired,
+                "fired_stuck": self.n_fired_stuck,
+                "fired_polling": self.n_fired_polling,
+                "recovered": self.n_recovered,
+            },
+            "rates": {
+                "recovered_rate": round(self.recovered_rate, 4),
+                "fire_recall": round(self.fire_recall, 4),
+                "false_resurface_rate": round(self.false_resurface_rate, 4),
+                "fire_precision": round(self.fire_precision, 4),
+            },
+            "net_positive": self.net_positive,
+        }
+
+
+def score(
+    policy: StreamPolicy,
+    cases: Iterable[StreamCase],
+    *,
+    _classify=classify_stream,
+) -> StreamEvalReport:
+    """Run `policy` over labelled `cases` (via `classify_stream`) and tabulate the ledger.
+
+    The policy is scored through the SAME `classify_stream` path the consumer's reader uses (the
+    `overlap_eval._admits` / `intervention_eval` "score under the floor" discipline), so the grid
+    reflects exactly what would FIRE. A stream FIRES iff its state is REPEATING or STALLED (both
+    actionable — the `ladder.actuates()` data-driven-not-hardcoded discipline, here a simple
+    not-ADVANCING test since the two firing states are the closed set). PURE: reads cases, counts
+    in one pass.
+
+    Invariant (pinned by a test): a stream is counted in `n_fired_stuck` / `n_fired_polling` only
+    if it both fired AND carried the matching ground-truth label, so the firing ledger never
+    exceeds `n_fired`, and `n_recovered <= n_fired_stuck`.
+    """
+    n = 0
+    n_stuck = n_polling = 0
+    n_fired = n_fired_stuck = n_fired_polling = n_recovered = 0
+
+    for case in cases:
+        n += 1
+        verdict = _classify(case.stream, policy)
+        fired = verdict.state is not StreamState.ADVANCING
+
+        if case.actually_stuck:
+            n_stuck += 1
+        if case.legit_polling:
+            n_polling += 1
+
+        if fired:
+            n_fired += 1
+            if case.actually_stuck:
+                n_fired_stuck += 1
+                if case.recovered_if_fired:
+                    n_recovered += 1
+            if case.legit_polling:
+                n_fired_polling += 1
+
+    return StreamEvalReport(
+        n=n,
+        n_stuck=n_stuck,
+        n_polling=n_polling,
+        n_fired=n_fired,
+        n_fired_stuck=n_fired_stuck,
+        n_fired_polling=n_fired_polling,
+        n_recovered=n_recovered,
+    )