sourcecode 4.18.0__py3-none-any.whl → 5.0.1__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__ = "4.18.0"
+__version__ = "5.0.1"

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
@@ -87,7 +87,39 @@ class CommandCache:
     #: releases (spring-audit, 408 s in #13 against 2 351 s in #16) is itself the
     #: measurement C3-76 exists for.
     field_seconds: "Optional[float]" = None
+    #: **C3-100.** `field_blocked` is a *measurement outcome*, not a property of the
+    #: command: it says "this run did not finish on that build, at that size", and
+    #: like every other measurement here it belongs to the build named in
+    #: `field_measured_version` and expires with it. It was read as a property for
+    #: three releases — `repo-ir` and `verify-edit` carried a 4.10.4 outcome while
+    #: eval #23 ran them in 9,8 s and 76,6 s — which is worse than a stale number,
+    #: because a stale number is a measurement and *"the field could not run this"*
+    #: is an incapacity the product does not have. A blocked row without a build is
+    #: rejected by the battery for the same reason a figure without one is.
     field_blocked: bool = False
+    #: The cache state the field figure was taken in. Eval #22 measured a warm
+    #: machine; eval #23 purged every cache first (`cache clear --all`,
+    #: `context-clear`, `rm -rf parse-cache-v1`) and then ran the whole catalogue
+    #: in one round, so its first figures are cold and its later ones are neither —
+    #: the shared layers filled as the round went on. Published because *72,3 s
+    #: cold* and *72,3 s warm* are two different facts about the same command, and
+    #: the row that says which is the only thing standing between the two:
+    #:   ``warm``  — the caches were warmed before the run
+    #:   ``cold``  — every cache was purged before the run
+    #:   ``mixed`` — inside a round that began purged: earlier commands had already
+    #:               filled some of the shared layers this one reads
+    field_cache_state: str = "warm"
+    #: **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 +141,37 @@ 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.
-FIELD_ANCHOR = (
-    "field evaluation #16: spring-audit on 3 342 Java files took 2 351 s "
-    "(Windows, pipx, warm cache) against 8.8 s on the 2 000-file reference"
-)
+#: **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 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.
+#:
+#: ⚠ `FIELD_ANCHOR`, `FIELD_ANCHOR_SECONDS` and `FIELD_ANCHOR_MEASURED_VERSION`
+#: are **derived from the `spring-audit` row**, below `COMMANDS`. They used to be
+#: written out here as well, which made the anchor two facts kept in step by hand:
+#: C3-97 refreshed both, and C3-100 is what it costs when the next refresh reaches
+#: only one of the copies. One authority per fact — the table — and the headline
+#: reads itself off it.
+#:
+#: The size of the field repository every `field_seconds` below was taken on.
 FIELD_ANCHOR_JAVA_FILES = 3342
-FIELD_ANCHOR_SECONDS = 2351.4
 
 
 #: Every layer keys on `cache.worktree_signature` — the exact tree state (C1-9).
@@ -194,14 +237,17 @@ COMMANDS: tuple[CommandCache, ...] = (
     CommandCache("ask (root)", ("snapshot", "ris", "parse"), "answer", True,
                  "`--compact` is what a warm stores by default; `--agent` needs `cache warm --agent`. "
                  "`--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.",
+                 "warmed core and rescan — the 171 s the field measured after a 103 s warm on 4.10.4. "
+                 "Eval #23 timed the same invocation at 72,3 s from a purged cache, and then paid "
+                 "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=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=72.3, field_cache_state="cold", field_measured_version="5.0.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=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 +255,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 +285,33 @@ 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),
+                 "next run. Its own second run is faster again. At field size that loop is not short "
+                 "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"),
     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,19 +340,33 @@ 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,
+                 "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"),
+    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 "
                  "`no_ris` instead of a snapshot.",
                  "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),
+    CommandCache("baseline", ("parse",), "shared", False,
+                 "`capture`/`diff`/`trend` over architectural metrics. The field figure is `capture`, "
+                 "the subcommand that analyses; `trend` reads stored artifacts and has its own row.",
+                 "capture 8.7 s → 3.6 s", analysis_class="repo-wide", cold_seconds=8.7, warm_seconds=3.6,
+                 field_seconds=2.2, field_cache_state="mixed", field_measured_version="5.0.0"),
     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),
@@ -319,6 +387,73 @@ _WARM_LABEL = {
     "none": "nothing",
 }
 
+#: The cache states a field figure may declare. A row outside this set is a
+#: measurement whose conditions nobody can read (C3-100).
+FIELD_CACHE_STATES = ("warm", "cold", "mixed")
+
+
+def _thousands(n: int) -> str:
+    return f"{n:,}".replace(",", " ")
+
+
+def _row(command: str) -> "CommandCache":
+    for entry in COMMANDS:
+        if entry.command == command:
+            return entry
+    raise KeyError(command)
+
+
+#: 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.
+_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"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 "
+    f"{_thousands(REFERENCE_JAVA_FILES)}-file reference"
+)
+
+
+def _version_key(version: "Optional[str]") -> tuple:
+    """A comparable key for a release name, for ordering measurements only.
+
+    Not a distance — `reference_currency` refuses to invent one and this does not
+    either. It answers exactly one question: is this row's build older than the
+    newest build anything in the table was measured on (C3-100)? Anything
+    unparseable sorts oldest, which is the safe direction: it gets labelled.
+    """
+    if not version:
+        return ()
+    parts: list[int] = []
+    for chunk in version.split("."):
+        digits = "".join(c for c in chunk if c.isdigit())
+        if not digits:
+            break
+        parts.append(int(digits))
+    return tuple(parts)
+
+
+def newest_field_measurement_version() -> "Optional[str]":
+    """The most recent build any field figure in the table was taken on.
+
+    The reference point for *"this row is older than the table it sits in"* — the
+    state C3-100 lived in for three releases, where a refresh reached five rows
+    and left four behind on a build four releases older, with nothing anywhere
+    saying so.
+    """
+    versions = [
+        row.field_measured_version
+        for row in COMMANDS
+        if (row.field_seconds is not None or row.field_blocked)
+        and row.field_measured_version
+    ]
+    return max(versions, key=_version_key) if versions else None
+
 
 def layer(layer_id: str) -> Layer:
     for entry in LAYERS:
@@ -363,12 +498,124 @@ 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 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__
+    measured = [
+        row for row in COMMANDS
+        if row.field_seconds is not None or row.field_blocked
+    ]
+    stale = sorted(
+        row.command
+        for row in measured
+        if row.field_measured_version not in (None, current)
+    )
+    # C3-100: the other staleness, and the one that hid for three releases — not
+    # "older than the build you are running" (every row is, the day after a
+    # release) but "older than the newest measurement in this same table", which
+    # is a refresh that reached some rows and not others. Named here so the gap is
+    # readable without diffing the rows by hand.
+    newest = newest_field_measurement_version()
+    behind = sorted(
+        row.command
+        for row in measured
+        if _version_key(row.field_measured_version) < _version_key(newest)
+    )
+    lagging = (
+        f" {len(behind)} of the {len(measured)} field figures were taken before "
+        f"the newest one in this table ({newest}): "
+        f"{', '.join(behind)}."
+        if behind
+        else ""
+    )
+    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,
+        "newest_field_measurement_version": newest,
+        "rows_behind_the_newest_field_measurement": behind,
+        "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."
+            )
+            + lagging
+        ),
+    }
+
+
 def reference_currency() -> dict:
     """How old the reference figures are, in releases the reader can name (F-AP).
 
@@ -429,9 +676,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 +701,21 @@ 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,
+                        "cache_state": cmd.field_cache_state,
+                        "measured_on_version": cmd.field_measured_version,
+                        "note": field_anchor_note(cmd),
+                    }
+                ),
             }
             for cmd in COMMANDS
         ],
@@ -478,6 +741,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 +826,28 @@ 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.
+            # C3-100: nor without the cache state they were taken in.
+            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"
+            )
+            qualifiers = [f"{cmd.field_cache_state} cache"] + ([note] if note else [])
+            suffix = f" ({', '.join(qualifiers)})"
+            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:

sourcecode/cli.py

@@ -467,6 +467,25 @@ def _help_scope() -> "Optional[Any]":
         return None
 
 
+def _cost_sentence() -> str:
+    """What the front page says about cost, from the module that measured it.
+
+    CL-21: this paragraph used to be written here, went stale with the anchors it
+    paraphrased, and kept telling operators to schedule a nightly job for commands
+    that finish in seconds. It is `cache_model`'s sentence now, so it cannot drift
+    from the table `ask cache model` prints.
+    """
+    try:
+        from sourcecode.cache_model import cost_sentence
+
+        return cost_sentence()
+    except Exception:
+        return (
+            "Cost tracks the command class and the build: `ask cache model` prints "
+            "what each command measured, and on which build."
+        )
+
+
 def _build_help_text(scope: "Optional[Any]" = None) -> str:
     """Build --help text dynamically based on current license state."""
     try:
@@ -485,10 +504,7 @@ def _build_help_text(scope: "Optional[Any]" = None) -> str:
 Deterministic Java/Spring semantics and reusable structural context for AI coding agents.
 
 Cache warms on first scan; later calls reuse pre-built context instead of rescanning.
-Performance depends on command class and repo size: per-symbol queries are the fast path,
-inventory commands scale with files, and repo-wide/deep compositions can take
-minutes on multi-thousand-endpoint repositories. Use deep jobs nightly or with
-ASK_MAX_ANALYSIS_SECONDS/ASK_PROGRESS when CI needs an explicit budget.
+{_cost_sentence()}
 
 {_start_here_block(scope)}
 

sourcecode/detach.py

@@ -1,8 +1,12 @@
 """detach.py — run a repository-wide analysis so it outlives the shell that started it.
 
-C3-53, three reproductions on the field repository: `spring-audit` runs 408 s of
-analysis, the agent harness promotes the foreground process to background at
-~600 s, and the session dies. **Backgrounding it did not help, and neither did
+C3-53, three reproductions on the field repository: `spring-audit` ran 408 s of
+analysis **on the build measured then** (4.7.0-class; the same command on the same
+repository measures 8,4 s on 4.18.0 — C3-97), the agent harness promoted the
+foreground process to background at ~600 s, and the session died. The cost that
+provoked this module has since collapsed; what the module answers — *a run that
+must outlive the shell that started it* — has not, because a nightly composition
+or a `risk` on a large tree still crosses that boundary. **Backgrounding it did not help, and neither did
 `Start-Process -NoNewWindow -PassThru`** — all six detached processes died at
 the same second the session did.