sourcecode 5.1.0__py3-none-any.whl → 5.2.0__py3-none-any.whl

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__ = "5.1.0"
+__version__ = "5.2.0"

sourcecode/architectural_delta.py

@@ -235,6 +235,63 @@ def diff_metrics(base: ArchMetrics, head: ArchMetrics) -> dict:
     }
 
 
+#: The one sentence both identical-state payloads are derived from (C3-107).
+#: It is an argument, not an assumption, and it rests on a property this product
+#: publishes and asserts every release: the analysis is a pure function of the
+#: tree state, byte-identical across eleven field rounds and two major jumps.
+IDENTICAL_STATE_BASIS = (
+    "The two states are one tree, and the analysis is a deterministic function of "
+    "the tree state, so every delta is zero without reading the tree. What is "
+    "*not* claimed is anything about the tree itself: the per-side totals were "
+    "not measured and are `null`, never 0 — pass two different states, or run "
+    "`ask <repo>` on one of them, to measure the repository rather than the diff."
+)
+
+
+def identical_state_delta() -> dict:
+    """The `architectural-delta-v1` payload for two states that are one state.
+
+    C3-107 closed the second build; the eleventh round measured what was left —
+    `delta` 24,6 s and `contract-diff` 59,9 s to conclude that a tree does not
+    differ from itself, from a purged cache. Building one side to diff it against
+    itself is a measurement of the *repository*, and this command's answer is the
+    *difference*: with one tree state the difference is empty by construction.
+
+    So the deltas are published as the zeroes they provably are, and every figure
+    that would require an analysis is `null` with the reason attached — the rule
+    this product applies everywhere else (an axis that was not measured is
+    `unknown`, never `0`).
+    """
+    empty_counts = {"base": None, "head": None, "delta": 0}
+    return {
+        "schema": ARCH_DELTA_SCHEMA,
+        "base_cir_hash": None,
+        "head_cir_hash": None,
+        "totals": {
+            "files": dict(empty_counts),
+            "symbols": dict(empty_counts),
+            "endpoints": dict(empty_counts),
+            "dependency_edges": dict(empty_counts),
+            "import_cycles": dict(empty_counts),
+        },
+        "endpoint_surface": {
+            "added_count": 0, "removed_count": 0, "added": [], "removed": [],
+        },
+        "fan_in_shifts": {"changed_count": 0, "shifts": []},
+        "import_cycle_shifts": {
+            "added_count": 0, "removed_count": 0, "added": [], "removed": [],
+        },
+        "blast_radius_shifts": {
+            "scope": "fan_in_shift_symbols", "changed_count": 0, "shifts": [],
+        },
+        "analysis": {"performed": False, "basis": IDENTICAL_STATE_BASIS},
+        "provenance": (
+            "architectural_delta (D1), identical states: no repository was read. "
+            + IDENTICAL_STATE_BASIS
+        ),
+    }
+
+
 def _transitive_reach(fqn: str, reverse_graph: dict, node_cap: int) -> int:
     """Size of the transitive reverse-dependency set of `fqn` (its blast radius).
 

sourcecode/cache_model.py

@@ -141,10 +141,11 @@ REFERENCE_JAVA_FILES = 2000
 REFERENCE_MEASURED_VERSION = "3.2.2"
 
 #: The other end of the measured range, and the reason this module publishes a
-#: *class* rather than a projected duration (C4-19). Field evaluation #22, on
-#: Windows 11 / PowerShell 5.1 / pipx / Python 3.10: `spring-audit` on a
-#: 3 342-file repository ran **8,4 s** — the same command takes 8.8 s on the
-#: 2 000-file reference, for a repository 1,7× the size.
+#: *class* rather than a projected duration (C4-19). Field evaluation #26, on
+#: Windows 11 / PowerShell 5.1 / pipx / Python 3.10, every cache purged first:
+#: `spring-audit` on a 3 342-file repository ran **31,0 s** — the same command
+#: takes 8.8 s on the 2 000-file reference, for a repository 1,7× the size, and it
+#: ran 8,4 s on the same subject two releases earlier.
 #:
 #: **The refusal to project stands, and this evaluation strengthened it** (C3-97).
 #: For eight releases the pair of anchors said *cost does not track file count*;
@@ -159,9 +160,11 @@ REFERENCE_MEASURED_VERSION = "3.2.2"
 #: each was measured on**, and how to run it.
 #:
 #: History of the anchor, kept because it is the measurement C3-76 exists for:
-#: 408 s (#13) → 2 351 s (#16, C3-72) → 8,4 s (#22, C3-97). The middle figure was
-#: quoted as an operational anchor for four releases after the build that produced
-#: it, and told operators to detach commands that finish in seconds.
+#: 408 s (#13) → 2 351 s (#16, C3-72) → 8,4 s (#22, C3-97) → 31,0 s (#26, C3-110).
+#: The middle figure was quoted as an operational anchor for four releases after
+#: the build that produced it, and told operators to detach commands that finish in
+#: seconds; the last one moved 3,7× in two releases with byte-identical payloads,
+#: which is the movement the release gate exists to catch and did not.
 #:
 #: ⚠ `FIELD_ANCHOR`, `FIELD_ANCHOR_SECONDS` and `FIELD_ANCHOR_MEASURED_VERSION`
 #: are **derived from the `spring-audit` row**, below `COMMANDS`. They used to be
@@ -242,12 +245,12 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "71,7 s again for `--agent` on the state it had just analysed (C3-103).",
                  "--compact 13.3 s cold → 0.3 s warm (cold re-measured on 3.7.0: was 19.3 s, C3-6); "
                  "--agent --full --env-map --depth 20 34.7 s → 33.9 s (no gain)", analysis_class="repo-wide", cold_seconds=13.3, warm_seconds=0.3,
-                 field_seconds=72.3, field_cache_state="cold", field_measured_version="5.0.0"),
+                 field_seconds=166.7, field_cache_state="cold", field_measured_version="5.1.0"),
     CommandCache("posture", ("cir", "parse"), "shared", False,
                  "Resolves the conditional bean graph on every run, over the shared CIR a warm "
                  "builds — the parse it used to repeat for itself. `--diff` compares two profile "
                  "sets over that one IR, so the second side costs the resolution only.",
-                 "10.1 s → 1.6 s", analysis_class="repo-wide", cold_seconds=10.1, warm_seconds=1.6, field_seconds=8.0, field_measured_version="4.18.0"),
+                 "10.1 s → 1.6 s", analysis_class="repo-wide", cold_seconds=10.1, warm_seconds=1.6, field_seconds=8.3, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("risk", ("cir", "parse"), "shared", False,
                  "Composes what the audit, impact-chain and the posture already answer, so it "
                  "pays each of their costs once over the shared CIR a warm builds — one parse "
@@ -255,7 +258,7 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "within the run.",
                  "not measured on the battery yet — the composition is bounded by the "
                  "`spring-audit` + `impact-chain` costs listed here, not by new analysis",
-                 analysis_class="deep", field_seconds=73.3, field_measured_version="4.18.0"),
+                 analysis_class="deep", field_seconds=77.2, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("enrich", ("cir", "parse"), "shared", False,
                  "Runs the same composition as `risk` over the repository, then joins a SARIF "
                  "log to it. Reading the log is negligible; everything a warm helps with is the "
@@ -280,30 +283,31 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "builds. Cost scales with the number of declared types, not with the "
                  "size of the label.",
                  "not measured on the battery yet — one `impact-chain` traversal per "
-                 "declared seed type over a CIR the warm already paid for", analysis_class="repo-wide"),
+                 "declared seed type over a CIR the warm already paid for", analysis_class="repo-wide",
+                 field_seconds=28.9, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("endpoints", ("ris", "parse"), "shared", False,
                  "Recomputes the endpoint surface on every run, over a parse a warm has already "
                  "paid for. Until 3.7.0 the extractor parsed every file itself instead of reading "
                  "the shared parse cache, and a warm measurably bought it nothing (C3-6).",
-                 "3.3 s → 1.4 s (re-measured on 3.7.0; was 2.8 s → 2.9 s)", analysis_class="repo-wide", cold_seconds=3.3, warm_seconds=1.4, field_seconds=3.8, field_measured_version="4.18.0"),
+                 "3.3 s → 1.4 s (re-measured on 3.7.0; was 2.8 s → 2.9 s)", analysis_class="repo-wide", cold_seconds=3.3, warm_seconds=1.4, field_seconds=5.6, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("spring-audit", ("ris", "parse"), "shared", False,
                  "Recomputes every run, but over a parse a warm has already paid for.",
-                 "8.8 s → 3.7 s", analysis_class="repo-wide", cold_seconds=8.8, warm_seconds=3.7, field_seconds=8.4, field_measured_version="4.18.0"),
+                 "8.8 s → 3.7 s", analysis_class="repo-wide", cold_seconds=8.8, warm_seconds=3.7, field_seconds=31.0, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("migrate-check", ("cir",), "none", False,
                  "Computes its own inventory and shares nothing a warm builds. Only `--blast-radius` "
                  "reuses the shared CIR.",
-                 "4.8 s → 4.8 s", analysis_class="repo-wide", cold_seconds=4.8, warm_seconds=4.8, field_seconds=10.2, field_measured_version="4.18.0"),
+                 "4.8 s → 4.8 s", analysis_class="repo-wide", cold_seconds=4.8, warm_seconds=4.8, field_seconds=11.3, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("impact-chain", ("cir", "parse"), "shared", False,
                  "The CIR is the expensive half — this is where a warm pays most.",
                  "9.9 s → 1.7 s", analysis_class="core", cold_seconds=9.9, warm_seconds=1.7,
-                 field_seconds=5.5, field_measured_version="4.18.0"),
+                 field_seconds=16.1, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("impact", ("parse",), "shared", False, "", "4.9 s → 2.8 s", analysis_class="core", cold_seconds=4.9, warm_seconds=2.8,
                  field_seconds=7.7, field_measured_version="4.18.0"),
     CommandCache("pr-impact", ("parse",), "shared", False,
                  "Diff-dependent: the answer itself is never stored. What it costs follows the "
                  "diff, not the repository: 12,5 s on an ordinary one and 11,8 s on a diff of "
                  "security configuration, measured at field scale.", analysis_class="core",
-                 field_seconds=12.5, field_measured_version="4.18.0"),
+                 field_seconds=25.7, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("verify", (), "none", False, "Runs the contracts against a fresh reading.", analysis_class="core"),
     CommandCache("verify-edit", ("parse",), "shared", True,
                  "Built for the edit loop: the parse cache is what keeps an unchanged file out of the "
@@ -311,15 +315,17 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "yet: eval #23 measured 76,6 s on a tree with no edits, because the HEAD side is "
                  "still built in a throwaway worktree instead of reusing the shared CIR (C3-102).",
                  "14.6 s → 9.6 s → 5.6 s on repeat", analysis_class="repo-wide", cold_seconds=14.6, warm_seconds=9.6,
-                 field_seconds=76.6, field_cache_state="mixed", field_measured_version="5.0.0"),
+                 field_seconds=119.5, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("review-pr", ("cir",), "none", False,
                  "Diff-dependent, and it reuses the CIR only if one exists. On a small diff, loading "
                  "the warmed CIR costs more than the work it saves.",
                  "1.1 s → 2.3 s (slower)", analysis_class="core", cold_seconds=1.1, warm_seconds=2.3),
     CommandCache("plan", ("parse",), "shared", False, "", "9.3 s → 3.8 s", analysis_class="core", cold_seconds=9.3, warm_seconds=3.8),
     CommandCache("compare", ("parse",), "shared", False, "", analysis_class="core"),
-    CommandCache("delta", (), "none", False, "Analyses two states — two checkouts, or two refs materialised into temporary trees; neither is the tree the cache describes.", analysis_class="repo-wide"),
-    CommandCache("contract-diff", (), "none", False, "Analyses two states (checkouts or refs); neither is the tree the cache describes.", analysis_class="repo-wide"),
+    CommandCache("delta", (), "none", False, "Analyses two states — two checkouts, or two refs materialised into temporary trees; neither is the tree the cache describes.", analysis_class="repo-wide",
+                 field_seconds=24.6, field_cache_state="mixed", field_measured_version="5.1.0"),
+    CommandCache("contract-diff", (), "none", False, "Analyses two states (checkouts or refs); neither is the tree the cache describes.", analysis_class="repo-wide",
+                 field_seconds=59.9, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("fix-bug", ("task",), "none", True,
                  "Shorthand for `prepare-context fix-bug`; caches its own answer, which a warm never runs.", analysis_class="core"),
     CommandCache("rename-class", (), "none", False, "", analysis_class="core"),
@@ -341,26 +347,27 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "no answer hit", analysis_class="repo-wide", cold_seconds=6.5, warm_seconds=0.3),
     CommandCache("explain", ("cir",), "shared", False, "Serves from the shared CIR a warm builds.",
                  "9.8 s → 1.6 s", analysis_class="core", cold_seconds=9.8, warm_seconds=1.6,
-                 field_seconds=4.4, field_measured_version="4.18.0"),
+                 field_seconds=6.3, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("export", ("parse",), "shared", False, "", "8.8 s → 3.7 s", analysis_class="repo-wide", cold_seconds=8.8, warm_seconds=3.7),
     CommandCache("repo-ir", ("parse",), "shared", False,
                  "Carried as *did not finish* from 4.10.4 until eval #23 ran it at field size in "
                  "9,8 s — a run that did not finish once is not a command that cannot finish "
                  "(C3-100, and the same correction `modernize` needed).",
                  "5.1 s → 2.9 s", analysis_class="repo-wide", cold_seconds=5.1, warm_seconds=2.9,
-                 field_seconds=9.8, field_cache_state="mixed", field_measured_version="5.0.0"),
+                 field_seconds=19.2, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("validation", ("parse",), "shared", False, "", "11.6 s → 6.4 s", analysis_class="repo-wide", cold_seconds=11.6, warm_seconds=6.4,
-                 field_seconds=17.4, field_measured_version="4.18.0"),
+                 field_seconds=39.5, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("modernize", ("parse",), "shared", False,
                  "Blocked in the session that recorded C3-53 and measured since: a run that did "
                  "not finish once is not a command that cannot finish.",
                  "5.2 s → 3.0 s", analysis_class="repo-wide", cold_seconds=5.2, warm_seconds=3.0,
-                 field_seconds=9.1, field_measured_version="4.18.0"),
+                 field_seconds=17.1, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("chunk-file", (), "none", False, "Reads one file; nothing to cache.", analysis_class="core"),
     CommandCache("cold-start", ("ris",), "answer", True,
                  "Reads the RIS a warm rebuilds — that is all it does. Without one it answers "
                  "`no_ris` instead of a snapshot.",
-                 "0.2 s either way", analysis_class="core", cold_seconds=0.2, warm_seconds=0.2),
+                 "0.2 s either way", analysis_class="core", cold_seconds=0.2, warm_seconds=0.2,
+                 field_seconds=0.4, field_cache_state="mixed", field_measured_version="5.1.0"),
     CommandCache("trend", (), "none", False, "Reads stored baseline artifacts from disk; analyses no source, so no cache layer applies. Same command as `baseline trend`.", analysis_class="none"),
     CommandCache("baseline", ("parse",), "shared", False,
                  "`capture`/`diff`/`trend` over architectural metrics. The field figure is `capture`, "
@@ -405,13 +412,15 @@ def _row(command: str) -> "CommandCache":
 
 #: The headline anchor, read off the table rather than written twice (C3-100).
 #: `spring-audit` is the command the whole series measured — 408 s (#13), 2 351 s
-#: (#16), 8,4 s (#22) — so it is the row the front page quotes, and quoting it
-#: means reading it, not copying it.
+#: (#16), 8,4 s (#22), 31,0 s (#26) — so it is the row the front page quotes, and
+#: quoting it means reading it, not copying it. The figure moving *up* between two
+#: rounds with byte-identical payloads is the reason C3-110 exists: nothing in this
+#: repository measured the direction, and the anchor is the only place it shows.
 _FIELD_ANCHOR_ROW = _row("spring-audit")
 FIELD_ANCHOR_SECONDS = _FIELD_ANCHOR_ROW.field_seconds
 FIELD_ANCHOR_MEASURED_VERSION = _FIELD_ANCHOR_ROW.field_measured_version
 FIELD_ANCHOR = (
-    f"field evaluation #22: spring-audit on {_thousands(FIELD_ANCHOR_JAVA_FILES)} "
+    f"field evaluation #26: spring-audit on {_thousands(FIELD_ANCHOR_JAVA_FILES)} "
     f"Java files took {FIELD_ANCHOR_SECONDS:g} s (Windows, pipx, "
     f"{_FIELD_ANCHOR_ROW.field_cache_state} cache) against "
     f"{_FIELD_ANCHOR_ROW.cold_seconds:g} s on the "
@@ -532,6 +541,37 @@ def field_anchor_note(row: "Optional[CommandCache]") -> "Optional[str]":
     return f"on {measured_on}"
 
 
+def field_anchor_currency_clause(row: "Optional[CommandCache]") -> "Optional[str]":
+    """The same fact as :func:`field_anchor_note`, said where it is *acted on* (C3-110).
+
+    C3-109 made every field figure carry its build, and the eleventh round confirms
+    the label is read and believed — and then reports the gap it does not close:
+    `spring-audit` publishes *"8,4 s … (4.18.0)"* while the same command measures
+    31,0 s on the build the reader is running. `(on 4.18.0)` is the right label for
+    a **row in a table**, where the reader is comparing figures; it is not enough
+    on a line that tells somebody how to run something, because there the figure is
+    being used as advice about the build in hand.
+
+    So the same fact gets a longer form for the surfaces that advise: the build,
+    and the admission that nothing has re-measured it here. That admission is the
+    registry this product applies everywhere else (`counts_are_floor`,
+    `unchanged_for`, `confidence_basis`) and the one place it had not applied to
+    itself.
+
+    ``None`` when the figure was taken on the running build — there is nothing to
+    admit — or when there is no figure at all.
+    """
+    if row is None or (row.field_seconds is None and not row.field_blocked):
+        return None
+    from sourcecode import __version__
+
+    measured_on = row.field_measured_version
+    if measured_on == __version__:
+        return None
+    where = f"measured on {measured_on}" if measured_on else "build not recorded"
+    return f"{where}; this build has not been re-measured at that scale"
+
+
 def cost_sentence() -> str:
     """The one paragraph the front page says about cost, derived here (CL-21).
 
@@ -544,15 +584,38 @@ def cost_sentence() -> str:
     with. It is generated from the anchors instead, so refreshing them refreshes
     the prose.
     """
+    from sourcecode import __version__
+
     audit = next((r for r in COMMANDS if r.command == "spring-audit"), None)
     seconds = FIELD_ANCHOR_SECONDS if audit is None or audit.field_seconds is None else audit.field_seconds
+    # C3-110: the figure is history the moment it is published, and this sentence
+    # is the surface a reader budgets against. The field measured 31,0 s where this
+    # line said 8,4 s, and the line was not wrong — it named 4.18.0 — it just left
+    # the reader to notice that 4.18.0 is not the build they are running. Said
+    # outright, and paired with the one figure this project *can* refresh: the gate
+    # measurement of the build in hand, when there is one.
+    stale = (
+        ""
+        if FIELD_ANCHOR_MEASURED_VERSION == __version__
+        else f", and {__version__} has not been re-measured at that scale"
+    )
+    gate = ""
+    _gate_cell = gate_anchor("spring-audit")
+    _gate_state = gate_currency()
+    if _gate_cell and _gate_state.get("current"):
+        gate = (
+            f" On this build the release gate measured the same command at "
+            f"{_gate_cell['seconds']:g} s on a "
+            f"{_thousands(int(_gate_cell['java_files']))}-file repository "
+            f"({_gate_cell['cache_state']} cache, {_gate_cell['host_class']})."
+        )
     return (
         f"Cost tracks the command class and the build, not the file count: "
         f"per-symbol queries are the fast path, inventory commands scale with "
         f"files, and a repository-wide audit measured {seconds:g} s on a "
         f"{_thousands(FIELD_ANCHOR_JAVA_FILES)}-file repository "
-        f"({FIELD_ANCHOR_MEASURED_VERSION}). `ask cache model` prints the figure "
-        f"and the build behind it for every command; "
+        f"({FIELD_ANCHOR_MEASURED_VERSION}{stale}).{gate} `ask cache model` prints "
+        f"the figure and the build behind it for every command; "
         f"ASK_MAX_ANALYSIS_SECONDS/ASK_PROGRESS bound and narrate a run where CI "
         f"wants an explicit budget."
     )

sourcecode/cli.py

@@ -403,7 +403,7 @@ def _start_here_block(scope: "Optional[Any]" = None) -> str:
     not would be worse than the one this replaces.
     """
     from sourcecode.execution_plan import (
-        BUCKET_ORDER, BUCKET_TITLE, DETACH, RUNS_NOW, UNKNOWN, plan,
+        BUCKET_ORDER, BUCKET_TITLE, BUDGETED, DETACH, RUNS_NOW, UNKNOWN, plan,
     )
 
     if scope is None or not scope.measured:
@@ -430,7 +430,7 @@ def _start_here_block(scope: "Optional[Any]" = None) -> str:
                 "    [dim]…each of these answers into a file and survives the shell:"
                 " add --output <file> --detach[/dim]"
             )
-    if not (grouped.get(RUNS_NOW) or grouped.get(UNKNOWN)):
+    if not (grouped.get(RUNS_NOW) or grouped.get(BUDGETED) or grouped.get(UNKNOWN)):
         lines.append(
             "  [dim]Nothing here runs in seconds on a repository this size. "
             "`ask cache warm .` first, or start with `ask endpoints . -o endpoints.json`.[/dim]"
@@ -2559,6 +2559,20 @@ _IR_BYTES_PER_FILE_HIGH: int = 30_300
 _IR_BYTES_PER_FILE_SAMPLES: int = 5
 _IR_SIZE_WARN_MB: int = 10  # advise above this; below it the write is not worth a sentence
 
+#: **C3-111.** The ceiling on the `-o` path, which had none. `--output FILE skips
+#: the payload budget entirely` is right about a *budget* — a file has no context
+#: window — and it was read as *no limit of any kind*: the field's run wrote
+#: **101 254 852 B**, byte-identical across three releases, with no line anywhere,
+#: because the pre-build band travels through `_notice`, which is silent off-TTY
+#: by contract (C3-26) and every `-o` run is a scripted one.
+#:
+#: 50 MB is where a projection or compression stops being optional: nothing in
+#: this catalogue reads a file that size in one piece, and `--gzip` cuts it by
+#: ~70-80 %. The guard fires *before* the build, so refusing costs the reader a
+#: third of a second rather than the whole analysis, and `--force` keeps the door
+#: open for somebody who means it.
+_IR_FILE_CEILING_MB: int = 50
+
 #: What `--no-cache` means on a subcommand (C3-5). The old text — "this command
 #: always reads fresh source (no snapshot cache)" — was false: `cache model`, the
 #: authority, records these commands reading the `ris`, `cir` and `parse` layers.
@@ -2579,6 +2593,21 @@ _NO_CACHE_SUBCOMMAND_HELP = (
 )
 
 
+def _ir_size_estimate_mb(file_count: int) -> "tuple[float, float, float]":
+    """The `repo-ir` size band for *file_count*, as ``(low, high, midpoint)`` MB.
+
+    One authority for the estimate (C3-111): the advisory printed it and the
+    guard needed it, and two derivations of one band drift the way the band and
+    the field's measurement drifted in C3-105. The midpoint is what the ceiling
+    is compared against — the low end would have let the field's 101 MB through
+    (34 MB estimated) and the high end refuses repositories whose real output is
+    half of it.
+    """
+    low = file_count * _IR_BYTES_PER_FILE_LOW / (1024 * 1024)
+    high = file_count * _IR_BYTES_PER_FILE_HIGH / (1024 * 1024)
+    return low, high, (low + high) / 2
+
+
 def _ir_size_advisory_message(file_count: int) -> "Optional[str]":
     """Return the `repo-ir` output-size advisory, or ``None`` below the threshold.
 
@@ -2604,8 +2633,7 @@ def _ir_size_advisory_message(file_count: int) -> "Optional[str]":
     Pure and TTY-agnostic: the caller owns the terminal gate, so this never
     reaches stdout or a pipeline (C3-26).
     """
-    est_low_mb = file_count * _IR_BYTES_PER_FILE_LOW / (1024 * 1024)
-    est_high_mb = file_count * _IR_BYTES_PER_FILE_HIGH / (1024 * 1024)
+    est_low_mb, est_high_mb, _ = _ir_size_estimate_mb(file_count)
     if est_high_mb <= _IR_SIZE_WARN_MB:
         return None
     return (
@@ -5809,6 +5837,39 @@ def repo_ir_cmd(
         if _notice_msg:
             _notice(_notice_msg)
 
+        # C3-111: and the notice above is the half that does not reach a script.
+        # `-o` is a scripted run by construction, `_notice` is silent off-TTY by
+        # contract (C3-26), and the write had no ceiling of any kind — which is
+        # how 101 254 852 B arrived three releases running with no line anywhere.
+        # An error envelope reaches every consumer, and this one is raised before
+        # the analysis rather than after the file is on disk.
+        _est_low, _est_high, _est_mid = _ir_size_estimate_mb(len(file_list))
+        _bounded = summary_only or max_nodes is not None or max_edges is not None
+        if _est_mid > _IR_FILE_CEILING_MB and not force and not _bounded:
+            _emit_error_json(
+                "OUTPUT_TOO_LARGE",
+                f"Estimated output is {_est_low:.0f}-{_est_high:.0f}MB for "
+                f"{len(file_list)} files, above the {_IR_FILE_CEILING_MB}MB "
+                f"ceiling for a written IR.",
+                hint=(
+                    "Choose the size deliberately: --summary-only (~5K tokens), "
+                    "--max-nodes N --max-edges N, --gzip (70-80% smaller), or "
+                    "--force to write it in full."
+                ),
+                expected=(
+                    f"An estimate under {_IR_FILE_CEILING_MB}MB, or one of "
+                    f"--summary-only / --max-nodes / --max-edges / --gzip / --force"
+                ),
+                estimate_mb={"low": round(_est_low, 1), "high": round(_est_high, 1)},
+                estimate_basis=(
+                    f"{_IR_BYTES_PER_FILE_LOW}-{_IR_BYTES_PER_FILE_HIGH} bytes per "
+                    f"Java file, sampled across {_IR_BYTES_PER_FILE_SAMPLES} "
+                    f"repositories; the top of the band under-states, since its "
+                    f"sample counted tests among its files and this run does not"
+                ),
+            )
+            raise typer.Exit(1)
+
     _ir_phase = f"extracting IR ({len(file_list)} files)"
     if since:
         _ir_phase += f" since {since}"
@@ -7103,12 +7164,13 @@ def _two_states(
                 f"--base-ref and --head-ref resolve to the same commit ({base_sha})",
             )
             if _identical:
-                # C3-107, the first half: two refs that name one commit are one
-                # tree, so it is read out once. The second `git archive` copied
-                # the same bytes to a second directory for a build that is going
-                # to be reused rather than repeated.
-                with materialize_ref(target, base_ref) as tree:
-                    yield tree, tree, block
+                # C3-107: two refs that name one commit are one tree. The first
+                # half of the row stopped the second `git archive`; the second
+                # half stops the first one too, because a caller that reads
+                # `identical_states` analyses neither side — there is no
+                # difference to measure, and materialising a tree nobody opens is
+                # the whole cost on a large repository.
+                yield root, root, block
                 return
             with materialize_ref(target, base_ref) as base_tree, \
                     materialize_ref(target, head_ref) as head_tree:
@@ -7233,7 +7295,10 @@ def delta_cmd(
     _enforce_format("delta", format)
 
     from sourcecode.context_graph import ContextGraph
-    from sourcecode.architectural_delta import architectural_delta
+    from sourcecode.architectural_delta import (
+        architectural_delta,
+        identical_state_delta as _identical_state_delta,
+    )
 
     _prog = Progress()
     with _two_states(
@@ -7242,15 +7307,18 @@ def delta_cmd(
         # C3-107: `_two_states` has already decided this, from the commit on the
         # ref path and from the tree signature on the checkout path.
         _same = bool(_comparison.get("identical_states"))
-        _prog.start("building base IR")
-        _base_cir = ContextGraph.build_from_root(_base_root).cir
         if _same:
-            _head_cir = _base_cir
+            # C3-107, second half: one tree state has no difference to measure, so
+            # nothing is read. Eval #26 measured 24,6 s here to conclude that a
+            # tree does not differ from itself.
+            data = _identical_state_delta()
         else:
+            _prog.start("building base IR")
+            _base_cir = ContextGraph.build_from_root(_base_root).cir
             _prog.update("building head IR")
             _head_cir = ContextGraph.build_from_root(_head_root).cir
-        _prog.update("diffing snapshots")
-        data = architectural_delta(_base_cir, _head_cir)
+            _prog.update("diffing snapshots")
+            data = architectural_delta(_base_cir, _head_cir)
     data["comparison"] = _comparison
     _prog.finish()
 
@@ -7328,7 +7396,10 @@ def contract_diff_cmd(
     _enforce_format("contract-diff", format)
 
     from sourcecode.context_graph import ContextGraph
-    from sourcecode.contract_diff import contract_diff as _contract_diff
+    from sourcecode.contract_diff import (
+        contract_diff as _contract_diff,
+        identical_state_contract_diff as _identical_state_contract_diff,
+    )
     from sourcecode.constraint_diff import constraint_findings as _constraint_findings
     from sourcecode.validation_surface import build_validation_surface
 
@@ -7339,24 +7410,26 @@ def contract_diff_cmd(
         # C3-107: `_two_states` has already decided this, from the commit on the
         # ref path and from the tree signature on the checkout path.
         _same = bool(_comparison.get("identical_states"))
-        _prog.start("building base IR")
-        _base_cir = ContextGraph.build_from_root(_base_root).cir
         if _same:
-            _head_cir = _base_cir
+            # C3-107, second half. This is the command the round measured at
+            # **59,9 s** on one tree — two CIRs and two validation surfaces, all
+            # four of them projections of the same bytes.
+            data = _identical_state_contract_diff()
         else:
+            _prog.start("building base IR")
+            _base_cir = ContextGraph.build_from_root(_base_root).cir
             _prog.update("building head IR")
             _head_cir = ContextGraph.build_from_root(_head_root).cir
-        # D2-b: proven request-constraint loosenings fill the non_breaking bucket. The
-        # validation surface needs the repo roots (it discovers specs/DTOs), not just the
-        # CIR — build it per side and diff the constraint contracts.
-        _prog.update("projecting validation constraints")
-        _base_surface = build_validation_surface(_base_root)
-        _cfindings = _constraint_findings(
-            _base_surface,
-            _base_surface if _same else build_validation_surface(_head_root),
-        )
-        _prog.update("diffing contracts")
-        data = _contract_diff(_base_cir, _head_cir, constraint_findings=_cfindings)
+            # D2-b: proven request-constraint loosenings fill the non_breaking bucket. The
+            # validation surface needs the repo roots (it discovers specs/DTOs), not just the
+            # CIR — build it per side and diff the constraint contracts.
+            _prog.update("projecting validation constraints")
+            _cfindings = _constraint_findings(
+                build_validation_surface(_base_root),
+                build_validation_surface(_head_root),
+            )
+            _prog.update("diffing contracts")
+            data = _contract_diff(_base_cir, _head_cir, constraint_findings=_cfindings)
     data["comparison"] = _comparison
     _prog.finish()
 
@@ -13810,7 +13883,7 @@ def _cache_model_conditioning(path: Path) -> Any:
     try:
         from sourcecode import cache_model as _cmodel
         from sourcecode.execution_plan import (
-            DETACH, RUNS_NOW, UNKNOWN, WARM_FIRST, scope_for, verdict,
+            BUDGETED, DETACH, RUNS_NOW, UNKNOWN, WARM_FIRST, scope_for, verdict,
         )
 
         scope = scope_for(path)
@@ -13820,6 +13893,11 @@ def _cache_model_conditioning(path: Path) -> Any:
         phrasing = {
             RUNS_NOW: "runs in the foreground here",
             WARM_FIRST: "run `ask cache warm .` first; it pays once for every command after it",
+            # C3-110: a minute of foreground work is a budget line, not a refusal.
+            # This line said *"not a foreground run here — a nightly job"* about a
+            # command the field had just run in the foreground, off a figure taken
+            # on another build.
+            BUDGETED: "a foreground run to budget for here — keep the answer with `--output <file>`",
             DETACH: "not a foreground run here — `--output <file> --detach`, or a nightly job",
             UNKNOWN: "not measured at this size",
         }

sourcecode/contract_diff.py

@@ -206,6 +206,33 @@ def diff_contract(
     }
 
 
+def identical_state_contract_diff() -> dict:
+    """The `contract-diff-v1` payload for two states that are one state (C3-107).
+
+    Same argument as `architectural_delta.identical_state_delta`, and the same
+    care about what it does not say: `unchanged` here is a statement about the
+    *difference* between the two states, which is empty because there is only one
+    state. It is not a statement that the contract is sound, and the payload says
+    so rather than leaving a reader to infer it from a green word.
+    """
+    from sourcecode.architectural_delta import IDENTICAL_STATE_BASIS
+
+    return {
+        "schema": CONTRACT_DIFF_SCHEMA,
+        "contract_status": "unchanged",
+        "summary": {"breaking": 0, "additive": 0, "non_breaking": 0},
+        "breaking": [],
+        "additive": [],
+        "non_breaking": [],
+        "analysis": {"performed": False, "basis": IDENTICAL_STATE_BASIS},
+        "provenance": (
+            "contract_diff (D2), identical states: no repository was read, and "
+            "`unchanged` describes the difference between the two states, not the "
+            "health of the contract in either. " + IDENTICAL_STATE_BASIS
+        ),
+    }
+
+
 def contract_diff(
     base_cir: "CanonicalRepositoryIR",
     head_cir: "CanonicalRepositoryIR",

sourcecode/execution_plan.py

@@ -38,12 +38,14 @@ from sourcecode.cache_model import (
     FIELD_ANCHOR_JAVA_FILES,
     REFERENCE_JAVA_FILES,
     REFERENCE_REPOSITORY,
+    field_anchor_currency_clause,
     field_anchor_note,
 )
 
 #: How a command can be run on the scope in hand.
 RUNS_NOW = "runs_now"          # foreground, seconds — the fast path
 WARM_FIRST = "warm_first"      # foreground, after `cache warm`, which pays once
+BUDGETED = "budgeted"          # foreground, but long enough to plan for (C3-110)
 DETACH = "detach"              # `--output` + `--detach`, or a nightly job
 UNKNOWN = "unknown"            # not measured on this axis; never guessed
 
@@ -257,6 +259,17 @@ class Verdict:
 #: session (C3-53). Commands measured under it at field size are still offered.
 FOREGROUND_SECONDS = 30.0
 
+#: **C3-110.** Above this, and only above it, the product says *"not a foreground
+#: run"*. Between the two thresholds a command is offered with its measured cost
+#: attached, because those two sentences are different claims and the product was
+#: making the stronger one on the weaker evidence: `risk` carried *"not a
+#: foreground run here — `--output <file> --detach`, or a nightly job"* off a
+#: 73,3 s anchor taken on another build, and the field — who had just run it in
+#: 77,2 s in the foreground — read that as the product refusing work it does
+#: nightly. Their number, and they are the ones holding the stopwatch: *"umbral
+#: para `not a foreground run`: no emitirlo por debajo de ~120 s"*.
+DETACH_SECONDS = 120.0
+
 
 def _reference(row) -> Optional[str]:
     if row is None:
@@ -360,8 +373,13 @@ def verdict(command: str, scope: Scope) -> Verdict:
             # row this matters most on — 72,3 s from a purged cache against 0,3 s
             # warm on the reference — and the honest thing to publish is the
             # measurement's conditions, not a warm figure nobody took at this size.
+            # C3-110: on the surfaces that *advise*, the build the figure belongs
+            # to is not a parenthetical — it is the reason the advice may be wrong
+            # here, so it is said in full.
+            currency = field_anchor_currency_clause(row)
             qualifiers = ", ".join(
-                [f"{row.field_cache_state} cache"] + ([note] if note else [])
+                [f"{row.field_cache_state} cache"]
+                + ([currency] if currency else ([note] if note else []))
             )
             dated = f" ({qualifiers})"
             if row.field_seconds <= FOREGROUND_SECONDS:
@@ -370,6 +388,19 @@ def verdict(command: str, scope: Scope) -> Verdict:
                     f"measured at {row.field_seconds:g} s on a repository this size{dated}",
                     cls, reference,
                 )
+            if row.field_seconds <= DETACH_SECONDS:
+                # C3-110: a minute is a cost, not a prohibition. The figure decides
+                # as it always did; what changes is that it stops being read as a
+                # refusal on the strength of a measurement from another build.
+                return Verdict(
+                    command, BUDGETED,
+                    (
+                        f"measured at {row.field_seconds:g} s on a repository this "
+                        f"size{dated} — a foreground run to budget for, or "
+                        f"`--output <file>` to keep the answer"
+                    ),
+                    cls, reference,
+                )
             return Verdict(
                 command, DETACH,
                 (
@@ -454,6 +485,10 @@ def advice(invocation: str, root: "Optional[Path]") -> str:
     found = verdict(invocation, scope)
     if found.how == DETACH:
         return f"Not a foreground run on this repository ({scope.describe()}): {found.why}."
+    if found.how == BUDGETED:
+        # C3-110: stated as a cost, never as a refusal — the distinction the
+        # threshold above exists to keep.
+        return f"A run to budget for on this repository ({scope.describe()}): {found.why}."
     if found.how == WARM_FIRST:
         return (
             f"The cache for this repository is cold ({scope.describe()}); "
@@ -464,11 +499,15 @@ def advice(invocation: str, root: "Optional[Path]") -> str:
 
 #: The order the front page lists the buckets in: what the reader can do now
 #: first, what costs one warm next, what needs a plan last.
-BUCKET_ORDER = (RUNS_NOW, WARM_FIRST, DETACH, UNKNOWN)
+BUCKET_ORDER = (RUNS_NOW, WARM_FIRST, BUDGETED, DETACH, UNKNOWN)
 
 BUCKET_TITLE = {
     RUNS_NOW: "Runs now",
     WARM_FIRST: "Warm the cache first — `ask cache warm .` pays once",
+    BUDGETED: (
+        f"Foreground, with a budget — measured between {FOREGROUND_SECONDS:g} s "
+        f"and {DETACH_SECONDS:g} s at this size"
+    ),
     DETACH: "Too big for this session — `--output <file> --detach`, or nightly",
     UNKNOWN: "Cost not measured on this repository",
 }

sourcecode/perf.py

@@ -452,24 +452,121 @@ RELEASE_GATE_MIN_RUNS = 5
 #: The gated population: repository-wide commands that take only a path, so the
 #: gate never depends on a symbol that exists in one revision and not the next.
 #: `""` is the root analysis (`ask <repo>`).
+#:
+#: **C3-110.** Six commands for five releases, against the eighteen the field
+#: measures every round — so `validation` could oscillate 2,9× four times, `risk`
+#: could cross two orders of magnitude, and the gate could stay green throughout
+#: because neither was in it. Every path-only command the field times is here now;
+#: what is left out is left out for a reason, and the reason is published below.
 RELEASE_GATE_COMMANDS: tuple[str, ...] = (
     "", "endpoints", "spring-audit", "migrate-check", "validation", "posture",
+    "risk", "modernize", "repo-ir", "data-exposure",
 )
 
+#: Extra arguments a gated command needs to be measured at all — one authority,
+#: read by the harness and published by `--print-config`, because a flag typed
+#: into a workflow is a second copy of a decision.
+#:
+#: `repo-ir` writes its whole IR by default, which C3-111 now refuses above 50 MB
+#: on the gate repository. `--summary-only` measures the half that is analysis
+#: (build the IR) without the half that is serialisation of ~80 MB, and it is the
+#: form the harness already uses to count symbols.
+RELEASE_GATE_COMMAND_ARGS: dict[str, tuple[str, ...]] = {
+    "repo-ir": ("--summary-only",),
+}
+
 #: What the gate does **not** cover, and why — published rather than omitted, so
 #: "the gate is green" is never read as "every command was measured".
 RELEASE_GATE_EXCLUSIONS: tuple[tuple[str, str], ...] = (
-    ("risk", "68 s on the gate repository since C3-96 deleted the catastrophic "
-             "backtracking that made it 54 minutes (F-AQ) — no longer excluded for "
-             "cost, only until a baseline cell exists for it; the first capture "
-             "that includes it makes it gated (C3-99)"),
     ("impact-chain", "takes a symbol, not a repository — its cost is the audit "
                      "`risk` and `spring-audit` already gate"),
+    ("explain", "takes a symbol, same reason"),
     ("verify-edit", "measures an edit loop, which needs a working-tree mutation "
-                    "the gate would have to fabricate"),
+                    "the gate would have to fabricate. Its clean-tree path builds "
+                    "no model at all since C3-102, so the figure a gate could take "
+                    "here would not be the figure a user pays"),
+    ("delta / contract-diff", "take two tree states; on one state they read "
+                              "nothing at all (C3-107), and on two they measure "
+                              "the same build the gated commands already cover"),
+    ("pr-impact / review-pr", "diff-dependent — their cost follows a diff the "
+                              "gate would have to invent, and an invented diff "
+                              "measures the invention"),
 )
 
 
+#: **C3-110.** The second comparison, and the one that would have caught the
+#: series the field prints. A release compared only against the release before it
+#: passes every step of a staircase: `validation` went 13,8 → 34,1 → 39,5 s in
+#: three releases and no single step is 20 %. The reference build is the best
+#: measurement this product has taken, kept as its own baseline directory, and a
+#: release states its distance from it.
+#:
+#: Drift is **measured and published, never deciding** — the same separation
+#: C3-108 drew for cold cells, and for a stronger reason: some of the distance
+#: from the best build is deliberate (work that was added), and a gate that
+#: cannot tell deliberate from accidental must not hold the release. What it must
+#: do is make the number impossible to not know.
+RELEASE_GATE_DRIFT_BASELINE = "reference-best"
+#: The distance at which drift is reported as `drifted` rather than `within`.
+#: Same 20 % as the release threshold: one number for "this is a lot", so a reader
+#: never has to hold two.
+RELEASE_GATE_DRIFT_THRESHOLD = RELEASE_GATE_THRESHOLD
+
+
+def drift_report(
+    reference_cells: Mapping[str, Mapping[str, object]],
+    current_cells: Mapping[str, Mapping[str, object]],
+    *,
+    threshold: float = RELEASE_GATE_DRIFT_THRESHOLD,
+) -> dict[str, object]:
+    """How far this run is from the best build ever measured, cell by cell.
+
+    Never a verdict: every entry is a ratio and a label, `passed` is not part of
+    the shape, and the caller cannot accidentally gate on it. The one thing this
+    fails at is silence.
+    """
+    cells: list[dict[str, object]] = []
+    drifted: list[str] = []
+    for cid in sorted(set(reference_cells) & set(current_cells)):
+        base = reference_cells[cid]
+        head = current_cells[cid]
+        b_wall = base.get("wall_ms") if isinstance(base.get("wall_ms"), Mapping) else {}
+        h_wall = head.get("wall_ms") if isinstance(head.get("wall_ms"), Mapping) else {}
+        b50, h50 = b_wall.get("p50"), h_wall.get("p50")
+        if not isinstance(b50, (int, float)) or not isinstance(h50, (int, float)) or b50 <= 0:
+            cells.append({"cell": cid, "status": "unmeasured"})
+            continue
+        ratio = float(h50) / float(b50)
+        status = "drifted" if (ratio - 1.0) > threshold else "within"
+        if status == "drifted":
+            drifted.append(cid)
+        cells.append({
+            "cell": cid,
+            "status": status,
+            "reference_p50_ms": round(float(b50), 3),
+            "current_p50_ms": round(float(h50), 3),
+            "ratio": round(ratio, 3),
+        })
+    unmeasured = sorted(set(reference_cells) - set(current_cells))
+    return {
+        "schema_version": GATE_SCHEMA_VERSION,
+        "comparison": "drift_against_reference_best",
+        "reference": RELEASE_GATE_DRIFT_BASELINE,
+        "threshold": threshold,
+        "cells": cells,
+        "drifted": drifted,
+        "not_measured_here": unmeasured,
+        "basis": (
+            "Distance from the best measurement this product has taken, not from "
+            "the previous release. A staircase of steps under the release "
+            "threshold is invisible to a release-to-release gate and visible "
+            "here. Measured and published; never a verdict, because some of the "
+            "distance is work that was deliberately added and this comparison "
+            "cannot tell which."
+        ),
+    }
+
+
 def cell_id(cell: Mapping[str, object]) -> str:
     """The identity two runs are matched on: ``<repo>__<command>__<mode>``.
 

sourcecode/verify_edit.py

@@ -56,6 +56,15 @@ class HeadVsWorking:
     #: True when the working CIR *is* the HEAD CIR because git reported an
     #: unmodified tree, so it was never built a second time (C3-32).
     working_cir_reused: bool = False
+    #: **C3-102.** False when no model was built at all, which is the only
+    #: honest answer to *"what did you analyse?"* on a tree git reports as
+    #: unmodified: nothing, because there is nothing to diff. `cir_head` and
+    #: `cir_working` are then the cached model if one already existed for this
+    #: exact tree state — free — and ``None`` otherwise. Every axis diffs the two
+    #: CIRs, so an empty change set has one answer that no analysis can alter;
+    #: paying 119,5 s to reach it is what put this command outside the loop it
+    #: was built for.
+    model_built: bool = True
 
 
 # Git env vars that REDIRECT git at where it operates. When verify-edit runs INSIDE a
@@ -218,34 +227,33 @@ def _build_head_cir_via_worktree(root: Path) -> Any:
 
 
 def _clean_tree_cir(root: Path) -> tuple[Any, bool]:
-    """The CIR of a tree git reports identical to HEAD — from the shared entry.
-
-    C3-102. C3-32 closed the second half of this: on a clean tree the *working*
-    CIR is the HEAD CIR, so it is not built twice. What was left is the first
-    half — the HEAD side still checked out a throwaway detached worktree and
-    parsed it, which on the field's repository is 76,6 s to answer *"you have
-    not edited anything"*, and 176,6 s in the round after.
-
-    When git says the tree does not differ from HEAD, the HEAD tree **is** the
-    worktree: copying it to a temp directory copies bytes that are already on
-    disk, and the shared repository-wide CIR for exactly this state is what
-    every other command on this repository has already built or will build.
-    `context_cache` keys that entry on `worktree_signature`, which on a clean
-    tree *is* the HEAD sha — the two lanes were separate for a reason that only
-    holds while the tree is dirty.
+    """The cached CIR for a tree git reports identical to HEAD, or ``(None, False)``.
+
+    **C3-102, second half.** The first half stopped the throwaway worktree: on a
+    clean tree the HEAD tree *is* the working tree, so it was read through the
+    shared entry instead of being copied and re-parsed. What that left is the
+    build itself — 119,5 s on the field's repository, from a purged cache, to
+    produce 807 bytes saying *"you have not edited anything"* — and the eleventh
+    round is the third to report it.
+
+    The build is not needed. `verdict()` short-circuits an empty change set
+    because every axis is a diff of the two CIRs and here they are the same
+    object: no analysis can change the answer, only the time it takes to give it.
+    So a clean run takes the model if one is already cached for exactly this tree
+    state (free, and it keeps `--compact`-style consumers whole) and builds
+    nothing when there is not.
 
     The shortcut is reached only through `git_answered` (C3-32's guard): a failed
     `git diff` also returns an empty change set, and mistaking that for a clean
     tree would turn an unknown into a confident *"nothing changed"*.
     """
     from sourcecode import context_cache as _ctx
-    from sourcecode.repository_ir import find_java_files
 
-    repo_root = _ctx.repo_root_of(root)
-    cached = _ctx.peek_cir(repo_root)
-    if cached is not None:
-        return cached, True
-    return _ctx.shared_cir(root, find_java_files(root)), False
+    try:
+        cached = _ctx.peek_cir(_ctx.repo_root_of(root))
+    except Exception:
+        return None, False
+    return (cached, True) if cached is not None else (None, False)
 
 
 def _head_cir(root: Path, head_sha: str) -> tuple[Any, bool]:
@@ -347,11 +355,14 @@ def head_vs_working(path: Path) -> HeadVsWorking:
     # before the build rather than after it. A clean tree needs no worktree
     # checkout: the tree on disk is HEAD, and its CIR is the shared one.
     t1 = time.perf_counter()
+    model_built = True
     if reused:
+        # C3-102: nothing to diff, so nothing is built. A model already cached for
+        # this exact tree state is taken because it costs a lookup; its absence is
+        # not a reason to spend a repository-wide parse on an answer that cannot
+        # depend on it.
         cir_head, hit = _clean_tree_cir(root)
-        if not hit:
-            # Keep the edit lane warm: the next run is the one with an edit in it.
-            _store_head_cir(root, head_sha, cir_head)
+        model_built = False
     else:
         cir_head, hit = _head_cir(root, head_sha)
     timings["head_cir_ms"] = (time.perf_counter() - t1) * 1000.0
@@ -369,6 +380,7 @@ def head_vs_working(path: Path) -> HeadVsWorking:
         timings_ms=timings,
         changed_build_files=changed_build,
         working_cir_reused=reused,
+        model_built=model_built,
     )
 
 
@@ -424,6 +436,11 @@ class VerifyVerdict:
     reasons: tuple[str, ...]
     exit_code: int
     head_sha: str
+    #: **C3-102.** What was read to produce this verdict. Always present, because
+    #: its absence would be the answer: a `pass` that analysed nothing and a `pass`
+    #: that diffed two models are the same verdict on different evidence, and a
+    #: consumer gating on this is owed the difference.
+    analysis: dict = field(default_factory=lambda: {"model_built": True})
 
     def to_dict(self) -> dict:
         return {
@@ -436,6 +453,7 @@ class VerifyVerdict:
             "blast_radius": self.blast_radius,
             "reasons": list(self.reasons),
             "exit_code": self.exit_code,
+            "analysis": dict(self.analysis),
         }
 
 
@@ -775,6 +793,25 @@ def verdict(hvw: HeadVsWorking, root: Path) -> VerifyVerdict:
             reasons=(),
             exit_code=0,
             head_sha=hvw.head_sha,
+            analysis={
+                "model_built": hvw.model_built,
+                "basis": (
+                    "git reports no file differing from HEAD, so the working tree "
+                    "is HEAD and every axis diffs a state against itself"
+                ),
+                "what_was_read": (
+                    "the git change set, and a model already cached for this tree "
+                    "state" if hvw.cir_head is not None else "the git change set"
+                ),
+                # The claim this verdict does NOT make, said outright: nothing was
+                # analysed, so nothing is asserted about the code beyond identity
+                # with HEAD.
+                "scope_note": (
+                    "`pass` here means the working tree does not differ from HEAD, "
+                    "not that HEAD was audited — that is `ask spring-audit` / "
+                    "`ask verify`."
+                ),
+            },
         )
 
     axes: dict[str, AxisResult] = {
@@ -815,6 +852,15 @@ def verdict(hvw: HeadVsWorking, root: Path) -> VerifyVerdict:
         reasons=tuple(reasons),
         exit_code=code,
         head_sha=hvw.head_sha,
+        analysis={
+            "model_built": True,
+            "basis": (
+                f"{len(hvw.changed_files)} changed .java file(s) and "
+                f"{len(hvw.changed_build_files)} changed build file(s): HEAD and "
+                f"the working tree were both modelled and diffed"
+            ),
+            "head_model_cache_hit": hvw.head_cache_hit,
+        },
     )
 
 

{sourcecode-5.1.0.dist-info → sourcecode-5.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.1.0
+Version: 5.2.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-5.1.0-blue)
+![Version](https://img.shields.io/badge/version-5.2.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 5.1.0 — and, on a build that has aged,
+ask version                    # ask 5.2.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.1.0.dist-info → sourcecode-5.2.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
-sourcecode/__init__.py,sha256=AQosRL48ISdUoMCE4htHdgvYGVNDHGx2oIMtrSEFoew,308
+sourcecode/__init__.py,sha256=ceBAMIauSu1eUdUEkTRgsDTDWiSm1LutxpbiBjjoS-Y,308
 sourcecode/adaptive_scanner.py,sha256=yJBKjNpkY6bpueYJ2YnRezen3sYZDecEt7WaaNWdqug,9466
 sourcecode/archetype.py,sha256=CZvRLpkHot_D8D3JFQVorr-EHDJyh0BbS7RnSTqBigM,40499
 sourcecode/architectural_baseline.py,sha256=4GiMVBLJVHvRKSWQGf2ZVurI1-R0qk5pmaevgvGSgVA,26325
-sourcecode/architectural_delta.py,sha256=E6MkyjWl-1ZgR4KSKnI785gUAfc8nq-lK-jd_rupQBU,12496
+sourcecode/architectural_delta.py,sha256=JhZVmA0gYUryt4x4ieVuxPbcvoBygHgADZaYJ_o4gdk,15142
 sourcecode/architecture_analyzer.py,sha256=GFc4ek-s1IHWM7pl-0L32WahZ93AmDgrAMcOuBKA5Dk,61463
 sourcecode/architecture_summary.py,sha256=BVVRHd952cjRhjHnR6CPrvKgaa-tdM16l-pBi1yDCPs,32395
 sourcecode/ast_extractor.py,sha256=aXJjZ7XjAdxa99hWNm4SyzPqx4gNWiTbUYjNWGNl-Vc,51213
 sourcecode/audit_report.py,sha256=CLvvlQH2oA6Qj4UADUWhNwSsp1OcyzwXXey5DN_IiWI,8660
 sourcecode/baseline_autocapture.py,sha256=tmMLexQSeaQRRbqxAd7walvGQqnF0mdpxQmkL40rlhI,15623
 sourcecode/cache.py,sha256=CK_J8NqyaTNZ57KQT-R4puqI8yYlzG5WL7uLFRbzods,41727
-sourcecode/cache_model.py,sha256=w-pmiVRxzNO6BOqYwEQ6fPNXEPDhz0hSmJruX2byNAY,52868
+sourcecode/cache_model.py,sha256=EqsVZ9U2f5Yd1A1RuBp9CBWyMh-mHpFDBOA3aSCmU74,56721
 sourcecode/call_surface.py,sha256=fiqYfHooxN1fX9oQoysq1LS3LoZcobhyUNjAGEZKpwk,4148
 sourcecode/caller_metrics.py,sha256=--sFGDnIog_YGu9xZHMcB91F5xZakfaAKvy15xU54hg,7904
 sourcecode/caller_reach.py,sha256=RRF49tv4-QswraJ2vsZ89VAMOj7BmYXlAdXr-tLP_CA,9483
@@ -18,7 +18,7 @@ sourcecode/chain_rules.py,sha256=Bi6UHfgd-GxWswmnHRcPz5jdbAuqka3Zkz_P-MTvqhw,127
 sourcecode/change_plan.py,sha256=aX1mp2XnlDN-8R2BcTiu8HlkDwQ_4fN1ZLckj0VMXHM,9945
 sourcecode/cir_graphs.py,sha256=9G0HHj1kw2325IDyzo2OpX73BNswEckecf4MZUXB4JM,12078
 sourcecode/classifier.py,sha256=JBzPwSSrDG-tUHAbcKB678HRbjLpD-ohzbzzO62mgpo,20114
-sourcecode/cli.py,sha256=KEYjMKuDdlsrmhfAa3c4MKKPVGywZtPYNNWQriQGrnc,617524
+sourcecode/cli.py,sha256=_dDEE_2pyD4d0VD6WR2KDVKeCVFH6pHToUMEhdd_T4I,622141
 sourcecode/client_calls.py,sha256=daRTgbXNUOfkzGXJpVb6A737R_Thhka8vw1_YgxCaLg,13548
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/compare.py,sha256=2GdDy0qkDSgmkkpgvoCHitoLj3mt30EeFgJ8PGEXJng,14712
@@ -29,7 +29,7 @@ sourcecode/context_cache.py,sha256=xfS0GpWG8MpHwqgw61tp3IR7jZ2IdG1j-v_HoIiSx7o,3
 sourcecode/context_graph.py,sha256=a6v2lgl2DxDnPAWE59K3yg6L5YFDak0LIUff3pi9p0c,47327
 sourcecode/context_scorer.py,sha256=QpChSpsmaAYz91rXA4Ue5xzQmNz_ZboZN09YOHScq1U,14679
 sourcecode/context_summarizer.py,sha256=cI2TZMvEhl0BEma12VtPaX6z03ZVBAetVzuK5GaCOvg,6852
-sourcecode/contract_diff.py,sha256=ivgHL1qRKFhriwQ52KWj4oJselqd5icSJW7Z2Ke04po,9429
+sourcecode/contract_diff.py,sha256=skND-oDmLyMDW5Qdvz-yDh7VyisikBCm5fvmLP7Q1xE,10618
 sourcecode/contract_init.py,sha256=bXRCqWM9tvrDLeT8j7ea6IWf87jB4VJxnlSzGBsRRXo,19582
 sourcecode/contract_model.py,sha256=nRxJKPMs1VHwFTa8AVXhGmaLjti3Lr2sjHDpWgv1bfE,3917
 sourcecode/contract_pipeline.py,sha256=4XE-xhab7ysdExXyUOBl2hAH4MABo7moKnT9V4XcEwQ,30243
@@ -52,7 +52,7 @@ sourcecode/envelope.py,sha256=fpF_8znvPqGXKZb0UPYcCYjm27yO7Pr-WsdXNE-tEoY,8911
 sourcecode/environment_resolution.py,sha256=bfhkM0RGSyLwzFvfi-YhHjU1cy2ufA_WIkXBVeHs9y8,22130
 sourcecode/error_schema.py,sha256=uwosfNaSujtYm11_732Hu92z5ITV040fQDaIyefSvR4,1683
 sourcecode/evidence_provider.py,sha256=GSSL44JEaouO5AHks2sB3d1YvC9xIKIld1yBYxZpXxo,4277
-sourcecode/execution_plan.py,sha256=c_pYnk-JFY7QNuk_Wc1F0z6tBJswUeu_j5i3QQtakGg,20390
+sourcecode/execution_plan.py,sha256=sV2VrR60XxdzM58SwI577kucLBqCVNQFbDGmA-x9Mvo,22655
 sourcecode/explain.py,sha256=yqxvKiLF0XMMg11PdgqMFrsim5SXuEKM1U2cLvCLspM,29935
 sourcecode/file_chunker.py,sha256=3vkM3mDQ5eE_yTPvUgjyjpGFBIjkW6_mrBmIbrylnA8,16444
 sourcecode/file_classifier.py,sha256=pJCeN9KqWpAwKMCgGP4KDsBjuWMeo4zlbj5fv3hk9dA,15587
@@ -83,7 +83,7 @@ sourcecode/parse_cache.py,sha256=TpIoSeNUba4Aoaz5o5SmgAc0Tz02OKq1Du4Hw7HyJfg,225
 sourcecode/partial_contract.py,sha256=x_N_0bF3mpNNjXd7JFB1zr6LSIroo2zN5GCz14GXvXQ,3510
 sourcecode/path_admission.py,sha256=OGNSoluhVh8YYOBZBnACUrkmH4Tp_yxjGLifkcsxQpo,5838
 sourcecode/path_filters.py,sha256=LmTYq735orssKTIuxTX1mE1FHAXF7dVEJEse35xE1RA,12371
-sourcecode/perf.py,sha256=l5YW_BBKMRZb88yjzI9FnXpr21pgmQ7LPt1MZBYhf3k,29345
+sourcecode/perf.py,sha256=Zipl5Wveolrl5xsDzHtlX7q0WYGQLfKlGX1m6__AkWA,34232
 sourcecode/phased_run.py,sha256=cFd0Lxfc8XL-XkCVCCzcjd9bZbtgkJkGZAHfmJ6dBJ4,16542
 sourcecode/pipe_contract.py,sha256=PML0Er5d8uDyec4OrdUXuyqHbGPUYndjeaKUjkFz2u4,8369
 sourcecode/posture.py,sha256=7d3zM4ExrSXVKrWNTlXQ0fUQNqDdl1LOuKwRVaXdRss,76574
@@ -143,7 +143,7 @@ sourcecode/tree_utils.py,sha256=8GAkIfQAsvtEudIeW1l4ooH_oRtrWR8cpJQJsEa_Pfw,2093
 sourcecode/type_usage_surface.py,sha256=51IrKRQoIoRnlsiDjHnqpJBn2rc6E59aRhgS0HTzAF0,4428
 sourcecode/validation_inference.py,sha256=-oWJqE6PqkqcZbCFDJeWCQHgI9Dbuv5ggJWD3LE_2IU,20817
 sourcecode/validation_surface.py,sha256=jYL-hkDjaaRKkAt7ZUcbxm3Dydl8o6KVRhTkuPXKPVc,31460
-sourcecode/verify_edit.py,sha256=djBCZcDMEM71UFhls_J4oImYBu7CUeQOHPKzWrT9c9U,40288
+sourcecode/verify_edit.py,sha256=SUaJeH5Icc54mutQx3-gh7i8U6d50cb_oxYc9SDUnHs,42757
 sourcecode/verify_repo.py,sha256=aHlNIUfoVVUxTXTNtSFryP4dOFBOvCfdyC31fFRXU6s,15346
 sourcecode/verify_rules.py,sha256=YxG5JkDXBVpwbU1_tIKVtU8_eaF3zjpsq05tjpN4Z7Y,19401
 sourcecode/version_check.py,sha256=CHp6ZxTIfo8kyHPCBgJA1uFC0xQCoXMuuOfrW8QTL8o,4942
@@ -207,8 +207,8 @@ sourcecode/telemetry/consent.py,sha256=pQdl-QeLl6Gcibn0eWHSKZrm-HYSsjpVqOnjrgFp8
 sourcecode/telemetry/events.py,sha256=4_yeO58U-Cwc1Qb27VB0_EjhmroY0k91n3_VGxeALB8,2776
 sourcecode/telemetry/filters.py,sha256=RzxauTz8HliO4BllQnXEXc7zTeqdCZi5MgqGEDuW7OQ,6570
 sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
-sourcecode-5.1.0.dist-info/METADATA,sha256=-w-kPbI2gq9YUOyXPsS8f-zgKHUVJBsbC_u-iXcgAZ0,42410
-sourcecode-5.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-5.1.0.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
-sourcecode-5.1.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-5.1.0.dist-info/RECORD,,
+sourcecode-5.2.0.dist-info/METADATA,sha256=5c5Xukk2etIZwtrijfL2_Hya7h1a08S-MyOD0s7EX8U,42410
+sourcecode-5.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-5.2.0.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
+sourcecode-5.2.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-5.2.0.dist-info/RECORD,,