sourcecode 4.18.0__tar.gz → 5.0.0__tar.gz

{sourcecode-4.18.0 → sourcecode-5.0.0}/.github/workflows/perf-gate.yml

@@ -59,14 +59,18 @@ jobs:
           python3 scripts/perf_gate.py --print-config | tee gate-config.json
           echo "repo_url=$(python3 -c "import json;print(json.load(open('gate-config.json'))['repository_url'])")" >> "$GITHUB_OUTPUT"
           echo "repo=$(python3 -c "import json;print(json.load(open('gate-config.json'))['repository'])")" >> "$GITHUB_OUTPUT"
+          echo "fleet_subdir=$(python3 -c "import json;print(json.load(open('gate-config.json'))['fleet_subdir'])")" >> "$GITHUB_OUTPUT"
           echo "mode=$(python3 -c "import json;print(json.load(open('gate-config.json'))['mode'])")" >> "$GITHUB_OUTPUT"
           echo "runs=$(python3 -c "import json;print(json.load(open('gate-config.json'))['min_runs'])")" >> "$GITHUB_OUTPUT"
           echo "commands=$(python3 -c "import json;print(' '.join(repr(c) for c in json.load(open('gate-config.json'))['commands']))")" >> "$GITHUB_OUTPUT"
 
       - name: Clone the gate repository
+        # Into the directory the harness resolves the gate repository to, which
+        # `--print-config` publishes. Naming it here instead cost three nightlies
+        # that measured nothing.
         run: |
           mkdir -p fleet
-          git clone --depth 1 "${{ steps.cfg.outputs.repo_url }}" "fleet/${{ steps.cfg.outputs.repo }}"
+          git clone --depth 1 "${{ steps.cfg.outputs.repo_url }}" "fleet/${{ steps.cfg.outputs.fleet_subdir }}"
 
       - name: Measure
         env:
@@ -84,6 +88,7 @@ jobs:
         run: |
           python3 scripts/perf_gate.py \
             --baseline "$BASELINE_DIR" \
+            --require-baseline \
             --current perf-run \
             --report perf-run/gate.json \
             --table perf-run/RELEASE-TABLE.md

{sourcecode-4.18.0 → sourcecode-5.0.0}/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 ## [Unreleased]
 
+## [5.0.0] — 2026-08-11
+
+**The engine got 280× faster in 4.18.0 and every number the product quoted about
+its own cost still described the build before it.** This release changes no
+analysis: it makes what ASK says about itself true again, and makes the way it
+went stale impossible to repeat silently. Field evaluation #22 — eighth
+measurement of the same 3 342-file repository at the same commit — scored the
+build **9,2/10** and named this as the one place the product states something
+false with confidence.
+
+**Why a major.** No API breaks. What changes is an answer thousands of readers
+act on: commands that were published as *"not a foreground run here — `--output
+<file> --detach`, or a nightly job"* are now published as foreground work, and
+the operational advice in `--help`, `cache model`, the budget warning and the
+remedies moves with them. A recommendation that reverses is a contract change
+whatever the surface, so it is versioned like one.
+
+**Fixed in this release:**
+
+- **The cost anchors described a build that no longer exists (C3-97).** `spring-audit`'s
+  field anchor was **2 351 s**, measured on 4.11.0; the same command, on the same
+  repository at the same commit, takes **8,4 s** on 4.18.0 — the two
+  catastrophic-backtracking patterns behind that figure were deleted in C3-95 and
+  C3-96. Four surfaces read the anchors and none could tell they were old:
+  `execution_plan`'s `here:` verdict, the budget warning, the `cache model`
+  header, and the front page. The product therefore recommended a nightly job for
+  an eight-second command, and an operator sizing `ASK_MAX_ANALYSIS_SECONDS` from
+  it would set the budget ~280× too high. Anchors refreshed from evaluation #22
+  (`spring-audit` 2 351 → 8,4 s · `risk` 3 232 → 73,3 s · `posture` 38 → 8,0 s ·
+  `migrate-check` 26,7 → 10,2 s · `endpoints` 5,0 → 3,8 s), first anchors recorded
+  for `impact-chain` 5,5 s, `validation` 17,4 s, `pr-impact` 12,5 s, `impact`
+  7,7 s and `explain` 4,4 s — and `modernize`, carried as *did not finish* since
+  4.10.4, is a measurement again at **9,1 s**.
+- **And they cannot go stale silently again.** Every field figure now carries
+  `field_measured_version`, the build it was taken on. A figure from an earlier
+  release is still published — a measurement at that size beats silence — but it
+  arrives labelled *"measured on 4.10.4, not re-measured on 5.0.0"* wherever it is
+  read, and `ask cache model --json` publishes `field_currency` naming every row
+  in that state. This is the mechanism `REFERENCE_MEASURED_VERSION` already gave
+  the reference figures; the field anchors, which are the ones that decide how a
+  command is offered, had none.
+- **The front page paraphrased the table instead of deriving it (CL-21).** *"Repo-wide/deep
+  compositions can take minutes … use deep jobs nightly"* was written in `cli`
+  beside the model it described, so it aged separately from the anchors it
+  paraphrased. It is generated from `cache_model.cost_sentence()` now: refreshing
+  a measurement refreshes the prose, and a battery asserts the front page contains
+  exactly what the model generates.
+- **The performance gate had no baseline to compare against (C3-98).** F-AP shipped
+  the detector in 4.13.0 and it has run nightly since, self-testing that a
+  synthetic 3× regression would fail — against `docs/perf/baselines/gate-latest`,
+  a directory that was never created. Every run ended in the gate refusing to
+  report green (*"a gate that cannot be red is not evidence"*), which is why eight
+  consecutive field evaluations found no evidence that any benchmark gates a
+  release. The baseline is committed: six cells on BroadleafCommerce, warm, five
+  runs each, captured on the runner at 4.18.0, with provenance and a refresh
+  procedure beside them. First real comparison passed with `regressions: []`, and
+  the observed runner noise floor — ±5 %, widest on the shortest cell — is
+  published next to the 20 % threshold it has to be read against.
+- **The gate's exclusion list quoted a deleted cost (C3-99).** `risk` was excluded
+  because it took *54 minutes* on the gate repository. Since C3-96 it takes
+  **68 s** there. The reason now says so, and names the only thing still keeping
+  it out: no baseline cell exists for it yet.
+- **Stale cost claims elsewhere in the documentation.** README (the proof table's
+  caveat and the problem statement), `USER_GUIDE` (the "Start here" framing and
+  the spinner paragraph), `docs/CACHE.md` (regenerated), `docs/perf/REGRESSION-GATE.md`
+  §3, and the module docstrings of `execution_plan`, `phased_run` and `detach`,
+  where a 408 s / 2 351 s cost was narrated in the present tense.
+
+**Deliberately not in this release:** the `chunk-file -c` remap. The guide says the
+short form moves from `--chunk` to `--copy` "at the next major"; this major
+changes no invocation, and breaking a working command line as a side effect of a
+documentation-truth release would be the wrong trade. It waits for a major that
+changes the command surface on purpose.
+
+**Not changed:** any analysis, any payload, any schema. Every rule, every count and
+every verdict this build produces is byte-identical to 4.18.0's.
+
 ## [4.18.0] — 2026-08-10
 
 **A field battery over the test repositories, run against 4.17.0 and aimed first

{sourcecode-4.18.0 → sourcecode-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.18.0
+Version: 5.0.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.18.0-blue)
+![Version](https://img.shields.io/badge/version-5.0.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`**
@@ -54,7 +54,7 @@ Description-Content-Type: text/markdown
 
 ## The problem
 
-Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. On small and mid-sized repos that cost is seconds; on large Java/Spring monoliths, repo-wide semantic composition can be minutes. Multiply that by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
+Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. On a large Java/Spring monolith that is thousands of files of parsing per turn, repeated for every question asked about the same unchanged tree. Multiply it by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
 
 ASK Engine solves this with a persistent structural cache keyed on file content hashes. After the first scan, later invocations reuse pre-built context whenever their command can consume the warmed layers. The repo doesn't change? The cache doesn't expire.
 
@@ -69,7 +69,7 @@ ASK Engine solves this with a persistent structural cache keyed on file content
 | Keycloak | 7,885 Java files | 10.5s | 0.6s | **~17x** |
 | BroadleafCommerce | 2,985 Java files | 2.7s | 0.3s | **~9x** |
 
-These numbers are cache-layer benchmarks, not a promise for every command. Per-symbol queries and compact context benefit most. Inventory commands scale with file count. Repo-wide/deep compositions such as `risk`, `audit-report` and large `spring-audit` runs can take minutes on multi-thousand-endpoint repositories and belong in a supervised or nightly job unless CI sets an explicit budget.
+These numbers are cache-layer benchmarks, not a promise for every command. Per-symbol queries and compact context benefit most, and inventory commands scale with file count. What a repository-wide analysis costs tracks the build more than the file count: on one 3,342-file monolith, at one commit, `spring-audit` measured 2,351s on 4.11.0 and **8.4s on 4.18.0** with a byte-identical payload — so ASK publishes measured anchors and the release each was taken on, and never projects a duration for your repository. `ask cache model` prints both anchors per command, and `risk` — the one composition still measured in the tens of seconds at that size — is the one to give a budget or a detached run.
 
 With the right command class, ASK Engine becomes **constant infrastructure** inside agent loops — call the fast/context surfaces before edits and reserve deep compositions for the points where their evidence is worth the runtime.
 
@@ -126,7 +126,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.18.0 — and, on a build that has aged,
+ask version                    # ask 5.0.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.18.0 → sourcecode-5.0.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.18.0-blue)
+![Version](https://img.shields.io/badge/version-5.0.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`**
@@ -16,7 +16,7 @@
 
 ## The problem
 
-Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. On small and mid-sized repos that cost is seconds; on large Java/Spring monoliths, repo-wide semantic composition can be minutes. Multiply that by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
+Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. On a large Java/Spring monolith that is thousands of files of parsing per turn, repeated for every question asked about the same unchanged tree. Multiply it by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
 
 ASK Engine solves this with a persistent structural cache keyed on file content hashes. After the first scan, later invocations reuse pre-built context whenever their command can consume the warmed layers. The repo doesn't change? The cache doesn't expire.
 
@@ -31,7 +31,7 @@ ASK Engine solves this with a persistent structural cache keyed on file content
 | Keycloak | 7,885 Java files | 10.5s | 0.6s | **~17x** |
 | BroadleafCommerce | 2,985 Java files | 2.7s | 0.3s | **~9x** |
 
-These numbers are cache-layer benchmarks, not a promise for every command. Per-symbol queries and compact context benefit most. Inventory commands scale with file count. Repo-wide/deep compositions such as `risk`, `audit-report` and large `spring-audit` runs can take minutes on multi-thousand-endpoint repositories and belong in a supervised or nightly job unless CI sets an explicit budget.
+These numbers are cache-layer benchmarks, not a promise for every command. Per-symbol queries and compact context benefit most, and inventory commands scale with file count. What a repository-wide analysis costs tracks the build more than the file count: on one 3,342-file monolith, at one commit, `spring-audit` measured 2,351s on 4.11.0 and **8.4s on 4.18.0** with a byte-identical payload — so ASK publishes measured anchors and the release each was taken on, and never projects a duration for your repository. `ask cache model` prints both anchors per command, and `risk` — the one composition still measured in the tens of seconds at that size — is the one to give a budget or a detached run.
 
 With the right command class, ASK Engine becomes **constant infrastructure** inside agent loops — call the fast/context surfaces before edits and reserve deep compositions for the points where their evidence is worth the runtime.
 
@@ -88,7 +88,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.18.0 — and, on a build that has aged,
+ask version                    # ask 5.0.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.18.0 → sourcecode-5.0.0}/pyproject.toml

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

{sourcecode-4.18.0 → sourcecode-5.0.0}/scripts/perf_gate.py

@@ -33,7 +33,13 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+sys.path.insert(0, str(Path(__file__).resolve().parent))
 from sourcecode import perf  # noqa: E402
+# The directory a repository is checked out under is the harness's fact, not a
+# second one this script or a workflow may restate: CI cloned the gate repo into
+# `fleet/broadleaf` while the harness looked for `fleet/BroadleafCommerce`, so
+# every nightly measured zero cells. `--print-config` now publishes the one name.
+from perf_harness import FLEET  # noqa: E402
 
 
 def load_cells(directory: Path) -> dict[str, dict]:
@@ -98,6 +104,8 @@ def _print_config() -> int:
         "threshold": perf.RELEASE_GATE_THRESHOLD,
         "repository": perf.RELEASE_GATE_REPO,
         "repository_url": perf.RELEASE_GATE_REPO_URL,
+        # Where the harness will look for that checkout, under the fleet root.
+        "fleet_subdir": FLEET.get(perf.RELEASE_GATE_REPO, perf.RELEASE_GATE_REPO),
         "repository_scale": perf.RELEASE_GATE_REPO_SCALE,
         "mode": perf.RELEASE_GATE_MODE,
         "min_runs": perf.RELEASE_GATE_MIN_RUNS,
@@ -122,6 +130,11 @@ def main() -> int:
     ap.add_argument("--allow-incomparable", action="store_true",
                     help="Do not fail cells whose env/host differ. Off by default: "
                          "an incomparable cell is an unmeasured one.")
+    ap.add_argument("--require-baseline", action="store_true",
+                    help="Fail when the baseline holds no cells. A run with nothing "
+                         "to compare against records every cell as `new` and passes; "
+                         "that is a recording, not a gate, and CI must not read it "
+                         "as one.")
     ap.add_argument("--report", type=Path, help="Write the perf-gate-v1 report here.")
     ap.add_argument("--table", type=Path, help="Write the release-notes markdown table here.")
     ap.add_argument("--self-test", action="store_true",
@@ -143,6 +156,12 @@ def main() -> int:
               f"which the gate reads as a failure, not a pass.", file=sys.stderr)
         return 1
     baseline = load_cells(args.baseline) if args.baseline else {}
+    if args.require_baseline and not baseline:
+        where = args.baseline if args.baseline else "<no --baseline given>"
+        print(f"no baseline cells in {where} — every cell would be recorded as "
+              f"`new` and the run would pass without comparing anything. A gate "
+              f"that cannot be red is not evidence.", file=sys.stderr)
+        return 1
 
     report = perf.gate_report(
         baseline, current,

{sourcecode-4.18.0 → sourcecode-5.0.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.18.0"
+__version__ = "5.0.0"

{sourcecode-4.18.0 → sourcecode-5.0.0}/src/sourcecode/cache_model.py

@@ -74,11 +74,11 @@ class CommandCache:
     cold_seconds: "Optional[float]" = None
     warm_seconds: "Optional[float]" = None
     #: The other measured point: this command on the field repository
-    #: (3 342 Java files, Windows 11 / PowerShell 5.1 / pipx, cold), from field
-    #: evaluations #13, #14 and #16. Seconds where a run finished; `field_blocked`
-    #: where it did not — the harness promoted the process and the session died,
-    #: which is a measurement of a different kind and is never written as a
-    #: duration. Rows with neither were not attempted there.
+    #: (3 342 Java files, Windows 11 / PowerShell 5.1 / pipx, warm), from the
+    #: field evaluations. Seconds where a run finished; `field_blocked` where it
+    #: did not — the harness promoted the process and the session died, which is a
+    #: measurement of a different kind and is never written as a duration. Rows
+    #: with neither were not attempted there.
     #:
     #: C3-72: where two evaluations of the same command at this size disagree, the
     #: figure here is the **most recent** one, because it describes the build a
@@ -88,6 +88,17 @@ class CommandCache:
     #: measurement C3-76 exists for.
     field_seconds: "Optional[float]" = None
     field_blocked: bool = False
+    #: **C3-97.** The build the field figure was taken on. An anchor without one is
+    #: a measurement that can outlive its build and keep deciding: 4.18.0 deleted
+    #: two catastrophic-backtracking patterns (C3-95, C3-96) and every figure taken
+    #: before it describes a cost that no longer exists — `spring-audit` at 2 351 s
+    #: where the same command on the same commit of the same repository now takes
+    #: 8,4 s. Anchors older than the running build are still published, because a
+    #: measurement is worth more than silence; what changes is that they are
+    #: **labelled** with the build they belong to, so a reader can see the figure is
+    #: not this one's. `field_anchor_note()` renders that label and
+    #: `execution_plan` appends it to the `here:` line.
+    field_measured_version: "Optional[str]" = None
 
 
 #: Where every `measured` figure comes from.
@@ -109,26 +120,38 @@ 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 #16, on
+#: *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 **2 351 s** — 267× the 8.8 s the same command takes
-#: on the 2 000-file reference, for a repository 1,7× the size. Cost does not
-#: scale with file count in any way this product has measured, so a projected
-#: "~15 s on your repository" would be a confident falsehood of exactly the kind
-#: the ledger exists to prevent. What can be said honestly is the class, the two
-#: measured anchors, and how to run it.
+#: 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.
 #:
-#: C3-72 replaced evaluation #13's 408 s with #16's 2 351 s here: the same command
-#: on the same repository at the same commit, measured three releases later
-#: (2 557 s in 4.10.6, 2 398 s in 4.10.7, 2 351 s in 4.11.0). The older figure was
-#: the one a budget message quoted as "~600s" for three releases while the
-#: measurement stood four times higher.
+#: **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*;
+#: what the series actually shows is that **cost tracks the build**. The identical
+#: command on the identical commit of the identical repository measured 2 557 s
+#: (4.10.6), 2 398 s (4.10.7), 2 351 s (4.11.0), 2 377 s (4.12.0), 1 371 s
+#: (4.16.0) and 8,4 s (4.18.0) — a 280× move produced by deleting two
+#: catastrophic-backtracking patterns (C3-95, C3-96), with every payload
+#: byte-identical throughout. A projection would therefore have to predict our own
+#: next release, which is the confident falsehood the ledger exists to prevent.
+#: What can be said honestly is the class, the two measured anchors, **the build
+#: each was measured on**, and how to run it.
+#:
+#: History of this constant, 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.
 FIELD_ANCHOR = (
-    "field evaluation #16: spring-audit on 3 342 Java files took 2 351 s "
+    "field evaluation #22: spring-audit on 3 342 Java files took 8.4 s "
     "(Windows, pipx, warm cache) against 8.8 s on the 2 000-file reference"
 )
 FIELD_ANCHOR_JAVA_FILES = 3342
-FIELD_ANCHOR_SECONDS = 2351.4
+FIELD_ANCHOR_SECONDS = 8.4
+
+#: The build the field anchors above were taken on. Rows carrying a different
+#: `field_measured_version` are published with that build's name attached rather
+#: than as figures for this one (C3-97).
+FIELD_ANCHOR_MEASURED_VERSION = "4.18.0"
 
 
 #: Every layer keys on `cache.worktree_signature` — the exact tree state (C1-9).
@@ -196,12 +219,12 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "`--env-map`, `--depth N` and `--exclude` change the *analysis*, so they miss the "
                  "warmed core and rescan — this is the 171 s the field measured after a 103 s warm.",
                  "--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=115.0),
+                 "--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=115.0, field_measured_version="4.10.4"),
     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=38.0),
+                 "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"),
     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 "
@@ -209,7 +232,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=3232.2),
+                 analysis_class="deep", field_seconds=73.3, field_measured_version="4.18.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 "
@@ -239,25 +262,31 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "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=5.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=3.8, field_measured_version="4.18.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=2351.4),
+                 "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"),
     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=26.7),
+                 "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"),
     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),
-    CommandCache("impact", ("parse",), "shared", False, "", "4.9 s → 2.8 s", analysis_class="core", cold_seconds=4.9, warm_seconds=2.8),
+                 "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"),
+    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.", analysis_class="core"),
+                 "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"),
     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 "
                  "next run. Its own second run is faster again.",
-                 "14.6 s → 9.6 s → 5.6 s on repeat", analysis_class="repo-wide", cold_seconds=14.6, warm_seconds=9.6, field_blocked=True),
+                 "14.6 s → 9.6 s → 5.6 s on repeat", analysis_class="repo-wide", cold_seconds=14.6, warm_seconds=9.6,
+                 field_blocked=True, field_measured_version="4.10.4"),
     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.",
@@ -286,11 +315,18 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "WITHOUT a warm, a second identical run: 10.2 s → 9.4 s (5 486 files) — "
                  "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),
+                 "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"),
     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, "", "5.1 s → 2.9 s", analysis_class="repo-wide", cold_seconds=5.1, warm_seconds=2.9, field_blocked=True),
-    CommandCache("validation", ("parse",), "shared", False, "", "11.6 s → 6.4 s", analysis_class="repo-wide", cold_seconds=11.6, warm_seconds=6.4),
-    CommandCache("modernize", ("parse",), "shared", False, "", "5.2 s → 3.0 s", analysis_class="repo-wide", cold_seconds=5.2, warm_seconds=3.0, field_blocked=True),
+    CommandCache("repo-ir", ("parse",), "shared", False, "", "5.1 s → 2.9 s", analysis_class="repo-wide", cold_seconds=5.1, warm_seconds=2.9,
+                 field_blocked=True, field_measured_version="4.10.4"),
+    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"),
+    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"),
     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 "
@@ -298,7 +334,7 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "0.2 s either way", analysis_class="core", cold_seconds=0.2, warm_seconds=0.2),
     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.",
-                 "capture 8.7 s → 3.6 s", analysis_class="repo-wide", cold_seconds=8.7, warm_seconds=3.6, field_seconds=11.0),
+                 "capture 8.7 s → 3.6 s", analysis_class="repo-wide", cold_seconds=8.7, warm_seconds=3.6, field_seconds=11.0, field_measured_version="4.10.4"),
     CommandCache("retrieve", ("cir", "parse"), "shared", False,
                  "Every query builds or reuses the shared CIR a warm builds.", analysis_class="core"),
     CommandCache("archetype", ("parse",), "shared", False, "", "9.3 s → 5.6 s", analysis_class="repo-wide", cold_seconds=9.3, warm_seconds=5.6),
@@ -363,12 +399,102 @@ class Conditioning:
         return (
             f"This repository ({self.scope}) is larger than the repository the "
             f"figures below were measured on ({REFERENCE_JAVA_FILES} Java files), "
-            f"and cost has not been observed to scale with file count: "
+            f"and what cost tracks here is the build rather than the file count: "
             f"{FIELD_ANCHOR}. Read each figure as the reference's, not as yours; "
             f"the `here:` lines say how each command can be run on this one."
         )
 
 
+def field_anchor_note(row: "Optional[CommandCache]") -> "Optional[str]":
+    """The build a row's field figure belongs to, when it is not this one (C3-97).
+
+    ``None`` when there is nothing to qualify — no field figure, or one measured on
+    the running build. Otherwise a short parenthetical naming the build, because a
+    figure carrying another release's name is a measurement and a figure carrying
+    none is a claim about this one.
+
+    The figure is never suppressed. A measurement from four releases ago still
+    beats silence for a reader deciding how to run a command; what it must not do
+    is arrive undated, which is how `spring-audit`'s 2 351 s went on recommending
+    a nightly job for a command that had come to take 8,4 s.
+    """
+    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 is None:
+        return "build not recorded"
+    if measured_on == __version__:
+        return None
+    # Short on purpose: this rides along every `here:` line and every row of
+    # `cache model`, and the build is the whole fact. The sentence that explains
+    # what an older build means is `field_currency()['statement']`, printed once.
+    return f"on {measured_on}"
+
+
+def cost_sentence() -> str:
+    """The one paragraph the front page says about cost, derived here (CL-21).
+
+    `--help` and the README used to carry their own hand-written version of it —
+    *"repo-wide/deep compositions can take minutes … use deep jobs nightly"* —
+    which stayed true for as long as the anchors behind it did and then went on
+    being printed for two more releases, recommending a nightly job for commands
+    that had come to finish in seconds. A sentence maintained beside the table it
+    describes is the second copy of a fact, which is the rule this module opens
+    with. It is generated from the anchors instead, so refreshing them refreshes
+    the prose.
+    """
+    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
+    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"ASK_MAX_ANALYSIS_SECONDS/ASK_PROGRESS bound and narrate a run where CI "
+        f"wants an explicit budget."
+    )
+
+
+def _thousands(n: int) -> str:
+    return f"{n:,}".replace(",", " ")
+
+
+def field_currency() -> dict:
+    """The same statement as `reference_currency`, for the field anchors (C3-97).
+
+    Published so a consumer can see which side of the pair is current without
+    parsing prose, and so the gap is visible the day it opens rather than the day
+    an evaluation points at it.
+    """
+    from sourcecode import __version__
+
+    current = __version__
+    stale = sorted(
+        row.command
+        for row in COMMANDS
+        if (row.field_seconds is not None or row.field_blocked)
+        and row.field_measured_version not in (None, current)
+    )
+    return {
+        "anchor": FIELD_ANCHOR,
+        "measured_on_version": FIELD_ANCHOR_MEASURED_VERSION,
+        "running_version": current,
+        "current": FIELD_ANCHOR_MEASURED_VERSION == current,
+        "rows_measured_on_an_earlier_build": stale,
+        "statement": (
+            f"The field anchors were taken on {FIELD_ANCHOR_MEASURED_VERSION}; you "
+            f"are running {current}. Each row states the build its field figure "
+            f"belongs to, and no figure is projected onto this one."
+            if FIELD_ANCHOR_MEASURED_VERSION != current
+            else f"The field anchors were taken on {current}, the build you are running."
+        ),
+    }
+
+
 def reference_currency() -> dict:
     """How old the reference figures are, in releases the reader can name (F-AP).
 
@@ -429,9 +555,10 @@ def as_dict(here: "Optional[Conditioning]" = None) -> dict:
         # table nine releases old cannot read as this build's measurement.
         "reference_currency": reference_currency(),
         # Published beside the reference so no consumer reads the figures as a
-        # law: the same command has been measured 46× slower on a repository 1.7×
-        # the size, on a different platform (C4-19).
+        # law: the same command on the same commit of the same repository has
+        # measured 2 351 s and 8,4 s on two of our own builds (C4-19, C3-97).
         "field_anchor": FIELD_ANCHOR,
+        "field_currency": field_currency(),
         "commands": [
             {
                 "command": cmd.command,
@@ -453,6 +580,20 @@ def as_dict(here: "Optional[Conditioning]" = None) -> dict:
                     if cmd.cold_seconds is None
                     else {"cold": cmd.cold_seconds, "warm": cmd.warm_seconds}
                 ),
+                # C3-97: the field figure and the build it belongs to travel
+                # together, or not at all. A consumer that reads the seconds
+                # without the build is the defect this key exists to prevent.
+                "field_measurement": (
+                    None
+                    if cmd.field_seconds is None and not cmd.field_blocked
+                    else {
+                        "seconds": cmd.field_seconds,
+                        "did_not_finish": cmd.field_blocked,
+                        "java_files": FIELD_ANCHOR_JAVA_FILES,
+                        "measured_on_version": cmd.field_measured_version,
+                        "note": field_anchor_note(cmd),
+                    }
+                ),
             }
             for cmd in COMMANDS
         ],
@@ -478,6 +619,13 @@ def render_markdown() -> str:
         f"performance gate (`docs/perf/REGRESSION-GATE.md`) is what re-measures them."
     )
     out.append("")
+    out.append(
+        f"The second anchor is the field one, and it carries its own build for the "
+        f"same reason (C3-97): {FIELD_ANCHOR}. Where a command was measured on an "
+        f"earlier release than the one you are running, `ask cache model` says so "
+        f"on that row rather than presenting the figure as this build's."
+    )
+    out.append("")
     out.append("| Command | A warm gives it | Measured (nothing cached → after a warm) | Repeat run cached | Layers | Notes |")
     out.append("|---|---|---|---|---|---|")
     for cmd in COMMANDS:
@@ -556,12 +704,26 @@ def render_text(here: "Optional[Conditioning]" = None) -> str:
     lines.append("What a warm gives each command")
     lines.append(f"  Timings: {REFERENCE_REPOSITORY}, each command measured in isolation.")
     lines.append(f"  {reference_currency()['statement']}")
+    lines.append(f"  {field_currency()['statement']}")
     width = max(len(c.command) for c in COMMANDS)
     for cmd in COMMANDS:
         repeat = "repeat cached" if cmd.repeat else "recomputes"
         lines.append(f"  {cmd.command.ljust(width)}  {_WARM_LABEL[cmd.warm]:<16} ({repeat})")
         if cmd.measured:
             lines.append(f"  {' ' * width}    measured: {cmd.measured}")
+        if cmd.field_seconds is not None or cmd.field_blocked:
+            # C3-97: never the seconds without the build they were taken on.
+            note = field_anchor_note(cmd)
+            shown = (
+                "did not finish in an interactive session"
+                if cmd.field_seconds is None
+                else f"{cmd.field_seconds:g} s"
+            )
+            suffix = f" ({note})" if note else ""
+            lines.append(
+                f"  {' ' * width}    field:    {shown} at "
+                f"{_thousands(FIELD_ANCHOR_JAVA_FILES)} Java files{suffix}"
+            )
         if cmd.note:
             lines.append(f"  {' ' * width}    {cmd.note}")
         if here is not None and cmd.command in here.per_command: