sourcecode 4.15.0__tar.gz → 4.16.0__tar.gz

{sourcecode-4.15.0 → sourcecode-4.16.0}/CHANGELOG.md

@@ -2,6 +2,110 @@
 
 ## [Unreleased]
 
+## [4.16.0] — 2026-08-10
+
+**The Part 1 queue of field evaluation #19 — three rows, one commit each — and
+the round where reading the field's *numbers* against our source found more than
+reading its *conclusions* did.** The sixth measurement of the same repository at
+the same commit scored **8,2/10**, the highest of the series: *"4.15.0 es la
+mejor versión medida."* It verified both of the previous release's rows from the
+outside (C3-81's `stage_stopped_in`, C3-83's budget provenance), determinism held
+a **sixth** consecutive build across five version jumps, and five commands got
+much faster (`validation` −57 %, `posture --diff` −54 %).
+
+Two of the three complaints it left open turned out not to be what was filed.
+
+**Fixed in this release:**
+
+- **`risk` declares a budget and never asks whether it is spent (C3-87).** The
+  field filed `risk` at 2 842 s under a 420 s budget as a +41 % performance
+  regression. It is a consumer left unbound. C3-71 and C3-79 made the deadline
+  reach inside the rule pass and bound exactly one: `spring-audit` passes
+  `stop_when=_run.exhausted` at both of its call sites, while `risk` built the
+  same `PhasedRun`, with the same `budget_seconds` and the same `budget_source`,
+  and then constructed its observers with **no `stop_when` at all** — so
+  `should_stop()` answered `False` for the life of the run and the budget could
+  only be observed on the boundary between two phases. Their own two numbers
+  prove it on one machine under one budget: `spring-audit` **1,94×** over, `risk`
+  **6,8×** over. Reproduced here on keycloak (5 486 files) with a 5 s budget —
+  `spring-audit` stops at 9,9 s with `_partial` published; `risk` was still
+  running at **10 minutes, 120×**, and had to be killed. Both rule passes and the
+  composition join now ask, each on the unit it iterates. A cut run publishes the
+  floor marks **where the numbers are** (`partial`, `counts_are_floor`,
+  `counts_basis` — C2-31's rule applied to the second consumer), names the join's
+  own cut (`composition_stopped_after`), and says PARTIAL on the terminal. A
+  complete run gains no field. The three rule-pass keys of `_partial` move into
+  `PhasedRun.status`: for four releases there was one caller, so "the caller" and
+  "the authority" were the same object by accident, and a second consumer would
+  otherwise have duplicated thirty lines of composition or invented a second
+  vocabulary for one fact. **The battery asserts an absence**, because the defect
+  was one — a missing argument at a call site is invisible in the payload of the
+  command that omits it, so it reads `cli.py` and fails on any
+  `_rule_pass_progress(...)` built without `stop_when`. A third consumer cannot
+  be added unbound.
+
+- **A stage of an audit either counts its population or names itself (C3-85).**
+  Six rounds of field reports read the 14,5-minute silence as a dead emitter,
+  proposing that the timer be re-armed. Measured through the real seam, the
+  emitter is alive and correct: a per-unit tick loop produced **5 evenly spaced
+  lines over 5,4 s at a 1 s interval**. What is silent is the work no counter
+  covers — instrumented on keycloak, **8,2 s of a 24 s warm run, 34 %**, between
+  the last `linking` tick and the first rule tick, with `linking 5486/5486`
+  frozen on screen throughout; 2,7 s more inside `GATE-001`; 24,7 s on a cold run
+  after `parsing 50/5486`. Named, not counted: the IR build's tail (`assembling
+  the IR`, `recovering spec-declared routes`, `scanning XML security
+  configuration`), the semantic-model build, the whole-tree walk *inside* the
+  configuration family (through `FamilyBudget.stage`, so the line says which
+  family it belongs to), the rule pass's dedup-and-order tail, and each of the
+  five repository-wide walks `risk` makes before it composes. A single walk has
+  no population, and inventing a denominator for it is the fabrication C3-56
+  refused. The assertion is the invariant rather than the symptom: a build may
+  not end on a completed counter, because everything after it runs under a line
+  that reads as still running.
+
+- **A count that has stopped moving says so, and stops estimating (C3-86).** The
+  field's line — `3340/3342 java files eta=0.5s` — was written **fourteen
+  minutes** after the counter last advanced, and both of its halves are claims
+  the run cannot support: it asserts the stage is 99,9 % done *now*, and the ETA
+  divides the remaining units by a rate measured over a window in which nothing
+  happened, so the longer the stall lasted the more imminent the finish looked. A
+  line whose counted state has not advanced for a whole interval now publishes
+  `unchanged_for=<duration>` and withholds the estimate — the rule
+  `_eta_seconds` already applies to a stage too young to extrapolate from. The
+  count itself is still printed: it is true, and it is what a reader wants; what
+  is withheld is the assertion that it is current. The staleness clock is
+  deliberately not the stage clock — a long, healthy, advancing stage must not be
+  marked frozen, and both directions are asserted. An uncounted stage is never
+  called stale: it never claimed a denominator.
+
+**Measured and not reproduced:** the report's third proposed fix — *"corregir la
+documentación del flag `--jobs`"* — is already shipped. `JOBS_OPTION_HELP` in
+this build reads *"It does NOT parallelise the rule pass, which is where a
+repository-wide audit spends most of its time, and on a warm cache there is
+nothing left to parse, so raising it buys nothing there."* The report quotes a
+truncated earlier string. Recorded on CL-18 so it is not re-opened, which is the
+CL-17 precedent.
+
+**Deliberately not in this release**, and each for a stated reason: **F-AT**
+(parallel rule evaluation — the field's single priority, *"lo único que separa
+este producto de un 9"*: a capability, and it does not start before this queue
+finishes), **F-AV** (a distinct exit code for a partial answer, or renaming
+`total_defects` to `total_defects_floor` when `partial` is true — a published
+contract change, never a side effect of a correction), **F-AU** (reusing the
+cached audit in the compositions), and **C3-76/F-AW** (the cross-version `risk`
+variance: macOS measures both sides flat for the second consecutive A/B, and a
+regression that reproduces on one platform cannot be bisected from the platform
+where it does not).
+
+**What C3-87 does not close, stated plainly: the wall time.** After the fix,
+`risk` on BroadleafCommerce (2 985 files) still runs past ten minutes under a 3 s
+budget, because the cost is not in the passes that now ask. That is **C3-88**,
+and it is open with a measurement rather than a hypothesis — the stage-by-stage
+profile was started and cancelled before it attributed the time, so the row says
+so instead of guessing.
+
+Suite **7 833** (7 813 before), 20 new assertions, zero failures.
+
 ## [4.15.0] — 2026-08-10
 
 **The Part 1 queue of Amendment O — the four rows field evaluation #18 opened,

{sourcecode-4.15.0 → sourcecode-4.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.15.0
+Version: 4.16.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.15.0-blue)
+![Version](https://img.shields.io/badge/version-4.16.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -126,7 +126,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.15.0 — and, on a build that has aged,
+ask version                    # ask 4.16.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.15.0 → sourcecode-4.16.0}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.15.0-blue)
+![Version](https://img.shields.io/badge/version-4.16.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -88,7 +88,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.15.0 — and, on a build that has aged,
+ask version                    # ask 4.16.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.15.0 → sourcecode-4.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "4.15.0"
+version = "4.16.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-4.15.0 → sourcecode-4.16.0}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "4.15.0"
+__version__ = "4.16.0"

{sourcecode-4.15.0 → sourcecode-4.16.0}/src/sourcecode/cli.py

@@ -8230,6 +8230,14 @@ def spring_audit_cmd(
             cir = ContextGraph.build(
                 file_list, target, progress=_work_sink(_prog)
             ).cir
+            # C3-85: the stretch between the last `linking` tick and the first rule
+            # tick reports nothing, and what stays on the line is `n/n` — a counter
+            # that finished, reading as a stage still running. Measured on keycloak
+            # (5 486 files, warm): **8,2 s of a 24 s run, 34 %**, all of it here.
+            # It has no population to count — it is one walk that builds the model
+            # every rule then reads — so it is named, which is what C3-56 does for
+            # a stage whose denominator would have to be invented.
+            _prog.update(f"building the semantic model over {len(file_list)} Java files")
             _model = SpringSemanticModel.build(cir)
             _run.checkpoint("ir")
             # The IR is built; the rule passes are the work now, and they are not
@@ -8353,37 +8361,15 @@ def spring_audit_cmd(
 
             data = combined.to_compact_dict() if compact else combined.to_dict()
             if _stopped_early:
-                data["_partial"] = _run.status(_stopped_early)
-                if _rules_partial:
-                    # C3-79: neither run nor not-run. How far it got is what a
-                    # reader needs to decide whether to re-run with more time, and
-                    # the findings it produced before the cut are in the payload.
-                    data["_partial"]["rules_partially_run"] = _rules_partial
-                    data["_partial"]["how_to_read"] += (
-                        " One rule family was stopped part-way through its own "
-                        "population: "
-                        + "; ".join(
-                            f"{'/'.join(entry['rule_ids'])} after "
-                            f"{entry['units_done']} of {entry['units_total']} "
-                            f"{entry['unit']}"
-                            for entry in _rules_partial
-                        )
-                        + ". What it found before the cut is reported and is a floor."
-                    )
-                if _rules_cut:
-                    # C3-71: a phase stopped *inside* is neither completed nor
-                    # pending, and calling it either would misreport the run. The
-                    # families it did not reach are named instead.
-                    data["_partial"]["rules_not_run"] = _rules_cut
-                    # A phase that was stopped inside is in neither list, and
-                    # putting it in `phases_pending` alone would claim none of it
-                    # ran when most of it did.
-                    data["_partial"]["phases_stopped_inside"] = _phases_cut
-                    data["_partial"]["how_to_read"] += (
-                        " The rule pass was stopped between families: "
-                        f"{', '.join(_rules_cut)} did not run, so every count here "
-                        "is a floor over the families that did."
-                    )
+                # C3-87: the block is composed by `PhasedRun.status`, which is the
+                # authority `risk` is now bound to as well — one vocabulary for
+                # "the budget cut this run", not one per command.
+                data["_partial"] = _run.status(
+                    _stopped_early,
+                    rules_partially_run=_rules_partial,
+                    rules_not_run=_rules_cut,
+                    phases_stopped_inside=_phases_cut,
+                )
 
             # Non-fatal RIS side-effect — persist summary only (not full findings).
             try:
@@ -8949,10 +8935,18 @@ def risk_cmd(
                 profiles=_profile_set(profile),
                 # C3-73: 54 minutes with one line on stderr in the field. The
                 # factory hands the composer an observer per counted stage.
+                #
+                # C3-87: and the observer carries the deadline. This factory built
+                # its observers with no `stop_when` for four releases, so `risk`
+                # declared `budget_seconds` on the run above and then never asked
+                # whether it was spent — the budget was honoured only between the
+                # two phases. `PhasedRun.exhausted` stays the one authority; what
+                # is new is that the second consumer asks it.
                 progress=lambda stage, unit="rule families": _rule_pass_progress(
-                    _prog, stage, unit
+                    _prog, stage, unit, stop_when=_run.exhausted
                 ),
                 checkpoint=_run.checkpoint,
+                partial_status=lambda **cut: _run.status(_WHY_BUDGET, **cut),
             )
         finally:
             _prog.stop()
@@ -8969,6 +8963,9 @@ def risk_cmd(
         success_msg=(
             f"risk written to {output_path} ({data['shown']} of "
             f"{data['total_defects']} defects composed)"
+            # C3-87: the terminal says it too. A reader who never opens the payload
+            # must not take a truncated ranking for the repository's risk.
+            + (" — PARTIAL, budget exhausted" if data.get("partial") else "")
         ),
     )
     # The complete answer is on disk; the checkpoint that stood in for it is not

{sourcecode-4.15.0 → sourcecode-4.16.0}/src/sourcecode/phased_run.py

@@ -131,8 +131,29 @@ class PhasedRun:
         done = set(self.completed)
         return [p for p in self.phases if p not in done]
 
-    def status(self, why: str) -> dict:
-        """The block an incomplete answer carries, and nothing else does."""
+    def status(
+        self,
+        why: str,
+        *,
+        rules_partially_run: "Optional[list[dict]]" = None,
+        rules_not_run: "Optional[list[str]]" = None,
+        phases_stopped_inside: "Optional[list[str]]" = None,
+    ) -> dict:
+        """The block an incomplete answer carries, and nothing else does.
+
+        **C3-87.** The three rule-pass keys used to be assembled by the caller, and
+        for four releases there was exactly one caller, so "the caller" and "the
+        authority" were the same object by accident. When `risk` was bound to the
+        same budget it became clear what that costs: a second consumer either
+        duplicates thirty lines of `how_to_read` composition or publishes a
+        different vocabulary for the same fact. They live here now, so a command
+        that stops inside its rule pass describes it the one way — and a *third*
+        consumer gets it by construction.
+
+        Each key is present only when there is something to say. A run stopped
+        between phases, with no family cut, produces exactly the block it produced
+        before this seam existed.
+        """
         out: dict[str, Any] = {
             "schema_version": SCHEMA_VERSION,
             "partial": True,
@@ -147,6 +168,38 @@ class PhasedRun:
             out["budget_seconds"] = float(self.budget_seconds)
             if self.budget_source:
                 out["budget_source"] = self.budget_source
+        if rules_partially_run:
+            # C3-79: neither run nor not-run. How far it got is what a reader needs
+            # in order to decide whether to re-run with more time, and the findings
+            # it produced before the cut are in the payload.
+            out["rules_partially_run"] = list(rules_partially_run)
+            out["how_to_read"] += (
+                " One rule family was stopped part-way through its own "
+                "population: "
+                + "; ".join(
+                    f"{'/'.join(entry['rule_ids'])} after "
+                    f"{entry['units_done']} of {entry['units_total']} "
+                    f"{entry['unit']}"
+                    for entry in rules_partially_run
+                )
+                + ". What it found before the cut is reported and is a floor."
+            )
+        if phases_stopped_inside:
+            # C3-71: a phase stopped *inside* is neither completed nor pending, and
+            # putting it in `phases_pending` alone would claim none of it ran when
+            # most of it did. Independent of the rule keys: a phase can be cut in a
+            # walk that evaluates no rules at all, which is how `risk` loses its
+            # composition join (C3-87).
+            out["phases_stopped_inside"] = list(phases_stopped_inside)
+        if rules_not_run:
+            # The families it did not reach are named, so the answer states a gap
+            # rather than an absence of findings.
+            out["rules_not_run"] = list(rules_not_run)
+            out["how_to_read"] += (
+                " The rule pass was stopped between families: "
+                f"{', '.join(rules_not_run)} did not run, so every count here "
+                "is a floor over the families that did."
+            )
         return out
 
     # -- checkpoints -------------------------------------------------------

{sourcecode-4.15.0 → sourcecode-4.16.0}/src/sourcecode/progress.py

@@ -178,6 +178,10 @@ class Progress:
         self._unit = "files"
         self._stage = ""
         self._stage_t0 = time.monotonic()
+        #: When the counted state last *advanced* (C3-86). Distinct from
+        #: `_stage_t0`, which is when the stage began: a stage can begin, count to
+        #: 3 340 of 3 342, and then stand still while an uncounted walk runs.
+        self._count_t0 = time.monotonic()
         #: When a heartbeat line was last written, by either emitter (C3-80). One
         #: stamp is what keeps the loop and the in-band beat from double-printing.
         self._last_emit = 0.0
@@ -227,6 +231,7 @@ class Progress:
             self._total = 0
             self._stage = ""
             self._estimate = True
+            self._count_t0 = time.monotonic()
         # C3-80: a new phase is the most informative thing this line can say, and
         # the phase that follows it may be the long one.
         self._beat()
@@ -262,6 +267,11 @@ class Progress:
         rule `_eta_seconds` already applies to a stage that has barely started.
         """
         with self._lock:
+            # C3-86: read before anything is mutated — the clock the *staleness* of
+            # a line is measured against only restarts when the state it reports
+            # actually changed.
+            if (done, total, stage) != (self._done, self._total, self._stage):
+                self._count_t0 = time.monotonic()
             if stage != self._stage or done < self._done:
                 self._stage = stage
                 self._stage_t0 = time.monotonic()
@@ -407,6 +417,19 @@ class Progress:
                 self._done, self._total, self._unit, self._stage
             )
             eta = self._eta_seconds(done, total)
+            # C3-86: how long this count has stood still. The field read
+            # `3340/3342 java files eta=0.5s` **fourteen minutes** after the
+            # counter last advanced, and both halves of that line are claims the
+            # run cannot support: it asserts the stage is 99,9 % done *now*, and
+            # the rate behind the ETA is computed over a window in which nothing
+            # happened — so the longer the stall lasts, the more imminent the
+            # finish looks. A count that has not moved for a whole interval says
+            # so and withholds the estimate, which is the rule `_eta_seconds`
+            # already applies to a stage too young to extrapolate from.
+            stalled = time.monotonic() - self._count_t0
+        stale = total > 0 and stalled >= self._interval
+        if stale:
+            eta = None
         counted = f"{done}/{total} {unit}" if total > 0 else ""
         if self._line_mode:
             line = f"[ask] progress phase={phase}"
@@ -415,6 +438,8 @@ class Progress:
             if counted:
                 line += f" {counted}"
             line += f" elapsed={_duration(elapsed)}"
+            if stale:
+                line += f" unchanged_for={_duration(stalled)}"
             if eta is not None:
                 # Named, not implied: the estimate covers the counted stage.
                 # Nothing here knows the cost of the stages after it, and a
@@ -426,6 +451,8 @@ class Progress:
             if counted:
                 shown += f" {counted}"
             tail = f"{elapsed:.1f}s"
+            if stale:
+                tail += f", unchanged for {_duration(stalled)}"
             if eta is not None:
                 tail += f", eta {_duration(eta)}"
             line = f"\r\033[K{frame} {shown} ({tail})"

{sourcecode-4.15.0 → sourcecode-4.16.0}/src/sourcecode/repository_ir.py

@@ -5538,6 +5538,14 @@ def build_repo_ir(
             )
         )
 
+    # C3-85: from here to the end of the build there is no per-file loop, so the
+    # heartbeat kept `linking n/n` on screen — a counter that finished, reading as
+    # a stage still running. Measured on keycloak (5 486 files, warm), the stretch
+    # between the last `linking` tick and the first rule tick was **8,2 s of a 24 s
+    # run**. These stages have no population to count; they are named, which is
+    # what C3-56 does rather than invent a denominator.
+    if progress is not None:
+        progress(0, 0, "assembling the IR")
     spring_summary = _build_spring_summary(all_symbols)
 
     # Deduplicate relations
@@ -5570,6 +5578,8 @@ def build_repo_ir(
     # when `since` is set). Done here, where `root` is available; placed before the
     # XML-security retag so spec routes lacking security get the same treatment.
     if route_diffs_arg is None:
+        if progress is not None:
+            progress(0, 0, "recovering spec-declared routes")
         _routed_fqns_ir = {
             r.get("effective_class")
             for r in (ir.get("route_surface") or [])
@@ -5597,6 +5607,8 @@ def build_repo_ir(
         r'|xmlns:security="http://www\.springframework\.org/schema/security")',
         re.IGNORECASE,
     )
+    if progress is not None:
+        progress(0, 0, "scanning XML security configuration")
     _xml_sec_detected = False
     for _xml_glob in (
         "*security*.xml", "*Security*.xml",

{sourcecode-4.15.0 → sourcecode-4.16.0}/src/sourcecode/risk.py

@@ -788,6 +788,14 @@ class RiskComposer:
         # caller owns — `(stage, unit) -> RulePassProgress | None` — so this module
         # never learns what a spinner is and a run nobody watches pays nothing.
         self._progress = progress
+        # C3-87: the observers are kept, not discarded. Each one holds what the
+        # operator's budget cut out of the pass it watched, and until this command
+        # was bound to the budget there was nothing to keep: `stop_when` was never
+        # passed, so `should_stop()` answered False for the life of the run and the
+        # deadline could only ever be observed on the boundary between two phases.
+        # The field measured what that costs on one machine under one 420 s
+        # budget — `spring-audit` 1,94× over, `risk` 6,8× over.
+        self._rule_watchers: "list[Any]" = []
         if findings is None:
             findings = list(run_tx_audit(
                 self.cir, root=self.root, model=self.model,
@@ -801,7 +809,21 @@ class RiskComposer:
             )
         self.findings = findings
 
+        # C3-85: everything from here to the composition is repository-wide work
+        # with no population of its own, and it reported nothing — so the line held
+        # the last rule family's count while it ran. Each walk is named as it
+        # starts, which is what the operator needs in order to tell a slow stage
+        # from a hung one, and which is also how the next round gets to say *which*
+        # of these walks the wall time is in.
+        _setup = self._rule_progress("composing risk factors", "walks")
+
+        def _named(label: str) -> None:
+            if _setup is not None:
+                _setup.step(label)
+
+        _named("inferring the security posture")
         posture = infer_security_posture(self.cir, root=self.root)
+        _named("resolving the endpoint security surface")
         self.surface = endpoint_security_surface(self.cir, root=self.root, posture=posture)
         access = (
             posture.to_dict().get("endpoints", []) if hasattr(posture, "to_dict") else []
@@ -815,8 +837,11 @@ class RiskComposer:
         # F.4-1. One pass over the α argument-shape atoms and one over the validation
         # surface: both are repository-wide facts, read once and joined by symbol and
         # by route, never re-derived per row.
+        _named("reading concatenated-query owners")
         self.concat_owners = _concatenated_query_owners(self.cir)
+        _named("reading HTTP-input query sinks")
         self.http_input_query_sinks = _http_input_query_sinks(self.root, self.cir)
+        _named("indexing the validation surface")
         self.constraint_index = _constraint_index(
             self.root, self.cir, extract_java_endpoints(self.root)
         )
@@ -843,6 +868,7 @@ class RiskComposer:
 
         # One pass answers both: the access axis (C1-26) and how much of the
         # request surface each chain configuration file decides (C1-25).
+        _named("resolving the conditional bean graph")
         self.profile_access, self.chain_reach = access_resolution(
             self.root,
             self.profiles if self.profiles is not None else set(),
@@ -887,13 +913,58 @@ class RiskComposer:
         return symbol, "method" if "#" in symbol else "class"
 
     def _rule_progress(self, stage: str, unit: str = "rule families") -> "Any":
-        """The observer for one counted stage, or None when nobody is watching."""
+        """The observer for one counted stage, or None when nobody is watching.
+
+        C3-87: "nobody is watching" now includes the budget. The factory returns an
+        observer whenever a heartbeat *or* a deadline exists, so a CI run with no
+        TTY — precisely where a budget matters — gets the same stop the terminal
+        does. The observer is registered here because this is the one place that
+        makes them, so `budget_gap()` cannot miss a pass.
+        """
         if self._progress is None:
             return None
         try:
-            return self._progress(stage, unit)
+            watcher = self._progress(stage, unit)
         except Exception:
             return None
+        if watcher is not None:
+            self._rule_watchers.append((stage, watcher))
+        return watcher
+
+    def budget_gap(self) -> dict:
+        """What the operator's budget cut out of the rule passes, or `{}`.
+
+        The two audits report through observers this class made, and each records
+        its own cut in the vocabulary `spring-audit` already publishes: families
+        that never started (`rules_not_run`) and a family stopped part-way through
+        one of its stages (`rules_partially_run`, with `stage_stopped_in`). Read
+        back here so the composition can publish the gap rather than a total that
+        silently shrank.
+
+        Only the *rule* passes are read. The composition observer counts defects,
+        not rule families, and folding its ids into a rule inventory would be the
+        two-populations-under-one-name defect this ledger already carries twice.
+        """
+        not_run: "list[str]" = []
+        partially_run: "list[dict]" = []
+        stages: "list[str]" = []
+        for stage, watcher in self._rule_watchers:
+            if not stage.endswith("rules"):
+                continue
+            _cut = list(getattr(watcher, "not_run", []) or [])
+            _partial = list(getattr(watcher, "partially_run", []) or [])
+            if not _cut and not _partial:
+                continue
+            not_run.extend(_cut)
+            partially_run.extend(_partial)
+            stages.append(stage)
+        if not not_run and not partially_run:
+            return {}
+        return {
+            "rules_not_run": not_run,
+            "rules_partially_run": partially_run,
+            "stages_stopped_inside": stages,
+        }
 
     def compose(
         self,
@@ -1157,6 +1228,7 @@ def _assemble_payload(
     limit: int,
     min_band: str,
     profiles: "Optional[set[str]]",
+    budget_cut: "Optional[dict]" = None,
 ) -> dict:
     """The `risk` answer document for `rows`. One construction, two callers.
 
@@ -1199,6 +1271,21 @@ def _assemble_payload(
         # that sentence, and it belongs where the composition is, not one command away.
         "non_coverage": non_coverage.block("security_surface"),
     }
+    # C3-87 (and C2-31's rule, applied to the second consumer): the counts above
+    # are arithmetic over what was composed, and on a cut run that is a truncated
+    # population. The mark goes where the numbers are — a reader who never opens
+    # `_partial` must not read `total_defects` as a census. A complete run gains
+    # no fields and stays byte-identical.
+    if budget_cut:
+        payload["partial"] = True
+        payload["counts_are_floor"] = True
+        payload["counts_basis"] = (
+            "This run was cut short by the analysis budget, so every count above "
+            "is a FLOOR over what did run — the absence of a risk composed from a "
+            "rule family that never ran is not evidence there is none, and a "
+            "composition stopped part-way leaves defects unranked rather than "
+            "unfound. `_partial` names what was not measured."
+        )
     if len(kept) > limit:
         from sourcecode.degradation import cap_effect
 
@@ -1238,6 +1325,7 @@ def build_risk(
     profiles: "Optional[set[str]]" = None,
     progress: "Optional[Callable[..., Any]]" = None,
     checkpoint: "Optional[Callable[[str, dict], None]]" = None,
+    partial_status: "Optional[Callable[..., dict]]" = None,
 ) -> dict:
     """Compose this build's own audit with reach, access, write effect and shape.
 
@@ -1267,11 +1355,47 @@ def build_risk(
     # C3-73: the join is the other half of this command's wall time, and it has a
     # denominator of its own — one row per defect. Counted with the same seam as
     # the rule passes, so there is one place that knows how to report counted work.
+    # C3-87: what the budget cut out of the two rule passes, read back from the
+    # observers this composition made. Empty on a run that was not cut, which is
+    # every run without `ASK_MAX_ANALYSIS_SECONDS` set.
+    _cut: dict = dict(composer.budget_gap())
+
     def _assemble(_rows: "list[Any]") -> dict:
-        return _assemble_payload(
+        payload = _assemble_payload(
             _rows, findings=findings, composer=composer, root=root,
             limit=limit, min_band=min_band, profiles=profiles,
+            budget_cut=_cut or None,
         )
+        if _cut and partial_status is not None:
+            # A phase stopped *inside* is neither completed nor pending: `audit`
+            # when a rule family was cut, `compose` when the join was.
+            _inside = [
+                name
+                for name, hit in (
+                    ("audit", bool(_cut.get("rules_not_run"))),
+                    ("compose", _cut.get("defects_composed") is not None),
+                )
+                if hit
+            ]
+            payload["_partial"] = partial_status(
+                rules_partially_run=_cut.get("rules_partially_run") or None,
+                rules_not_run=_cut.get("rules_not_run") or None,
+                phases_stopped_inside=_inside or None,
+            )
+            if _cut.get("defects_composed") is not None:
+                # The join is this command's own population, and a run cut inside
+                # it did rank some defects and not others. Neither `phases_completed`
+                # nor `phases_pending` can say that, so it is said here.
+                payload["_partial"]["composition_stopped_after"] = {
+                    "defects_composed": _cut["defects_composed"],
+                    "defects_total": _cut["defects_total"],
+                    "basis": (
+                        "The audit ran; the join that ranks its defects was cut. "
+                        "The defects not composed were measured and are counted in "
+                        "total_defects — they carry no band and are not in `risks`."
+                    ),
+                }
+        return payload
 
     if checkpoint is not None:
         # The audit and the posture are paid for; the join has not started. A
@@ -1286,6 +1410,15 @@ def build_risk(
     rows = []
     for _index, defect in enumerate(_defects, start=1):
         if _rows_progress is not None:
+            # C3-87: the join is the other half of this command's wall time, so the
+            # deadline is asked here too — on a whole composed row, which is this
+            # loop's unit, and sampled by the same seam the rule passes use.
+            if _rows_progress.tick(
+                _index - 1, len(_defects), label="composing defects", unit="defects"
+            ):
+                _cut["defects_composed"] = _index - 1
+                _cut["defects_total"] = len(_defects)
+                break
             _rows_progress.rule(_index, len(_defects), str(defect["defect_id"]))
         rows.append(composer.compose(
             defect_id=str(defect["defect_id"]),