sourcecode 5.0.0__py3-none-any.whl → 5.1.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.0.0"
+__version__ = "5.1.0"

sourcecode/cache_model.py

@@ -87,7 +87,28 @@ 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
@@ -137,21 +158,20 @@ REFERENCE_MEASURED_VERSION = "3.2.2"
 #: 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:
+#: 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 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`, `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 = 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).
@@ -217,9 +237,12 @@ 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, field_measured_version="4.10.4"),
+                 "--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 "
@@ -284,9 +307,11 @@ COMMANDS: tuple[CommandCache, ...] = (
     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.",
+                 "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_blocked=True, field_measured_version="4.10.4"),
+                 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.",
@@ -318,8 +343,12 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "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, field_measured_version="4.10.4"),
+    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,
@@ -333,8 +362,11 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "`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, field_measured_version="4.10.4"),
+    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),
@@ -355,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:
@@ -459,10 +558,6 @@ def cost_sentence() -> str:
     )
 
 
-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).
 
@@ -473,11 +568,32 @@ def field_currency() -> dict:
     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 COMMANDS
-        if (row.field_seconds is not None or row.field_blocked)
-        and row.field_measured_version not in (None, current)
+        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,
@@ -485,12 +601,114 @@ def field_currency() -> dict:
         "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 gate_anchor(command: str) -> "Optional[dict]":
+    """What the release gate measured for *command*, or ``None`` (C3-109).
+
+    The third figure in this module, and the only one this repository can refresh
+    by itself. `REFERENCE_*` is a 3.2.2 measurement on a 2 000-file tree;
+    `field_seconds` is the field's, at 3 342 files, on their machine and their
+    build. Both age, and neither can be re-measured from here — which is exactly
+    how B17 reopened one release after it was closed: the labelling worked and
+    the number still expired.
+
+    The gate measures a 2 985-file repository under a declared host class every
+    release and commits its cells, so this figure carries the build that produced
+    it and can be brought current by running the gate. It never overrides a field
+    anchor — a measurement at field scale outranks one at gate scale — it is
+    published *beside* it, so an anchor from an older build is no longer the only
+    number a reader has.
+    """
+    try:
+        from sourcecode.gate_anchors import (
+            GATE_ANCHORS,
+            GATE_HOST_CLASS,
+            GATE_JAVA_FILES,
+            GATE_MEASURED_VERSION,
+            GATE_REPOSITORY,
+        )
+    except Exception:
+        return None
+    cell = GATE_ANCHORS.get(command)
+    if not cell:
+        return None
+    return {
+        "seconds": cell["seconds"],
+        "cache_state": cell["mode"],
+        "runs": cell["runs"],
+        "measured_on_version": GATE_MEASURED_VERSION,
+        "repository": GATE_REPOSITORY,
+        "java_files": GATE_JAVA_FILES,
+        "host_class": GATE_HOST_CLASS,
+    }
+
+
+def gate_currency() -> dict:
+    """Whether the in-house gate figures describe the build in hand (C3-109).
+
+    Same shape and same purpose as `field_currency`, for the anchor set that can
+    actually be refreshed. When this says `current: false`, the remedy is a
+    command rather than a hope: re-run the gate on the tag and commit the cells.
+    """
+    from sourcecode import __version__
+
+    current = __version__
+    try:
+        from sourcecode.gate_anchors import (
+            GATE_ANCHORS,
+            GATE_CAPTURED_AT,
+            GATE_HOST_CLASS,
+            GATE_JAVA_FILES,
+            GATE_MEASURED_VERSION,
+            GATE_REPOSITORY,
+        )
+    except Exception:
+        return {
+            "available": False,
+            "running_version": current,
+            "statement": (
+                "This build carries no gate measurement of its own. The gate "
+                "publishes one per release (docs/perf/REGRESSION-GATE.md); until "
+                "it runs, the field anchors are the only measured figures here."
+            ),
+        }
+    return {
+        "available": True,
+        "measured_on_version": GATE_MEASURED_VERSION,
+        "running_version": current,
+        "current": GATE_MEASURED_VERSION == current,
+        "captured_at": GATE_CAPTURED_AT,
+        "repository": GATE_REPOSITORY,
+        "java_files": GATE_JAVA_FILES,
+        "host_class": GATE_HOST_CLASS,
+        "commands": sorted(GATE_ANCHORS),
         "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."
+            f"The release gate measured {len(GATE_ANCHORS)} commands on "
+            f"{GATE_REPOSITORY} ({GATE_JAVA_FILES} Java files, {GATE_HOST_CLASS}) "
+            + (
+                f"on {current}, the build you are running."
+                if GATE_MEASURED_VERSION == current
+                else (
+                    f"on {GATE_MEASURED_VERSION}; you are running {current}, which "
+                    f"the gate has not measured. Re-run it on this build "
+                    f"(docs/perf/REGRESSION-GATE.md) — unlike the field anchors, "
+                    f"this is a figure this project can refresh."
+                )
+            )
         ),
     }
 
@@ -559,6 +777,11 @@ def as_dict(here: "Optional[Conditioning]" = None) -> dict:
         # 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(),
+        # C3-109: and the figure this project can refresh by itself. A field
+        # anchor belongs to the build the field ran; this one belongs to the
+        # build the gate ran, which is a release away at worst instead of
+        # unreachable. Published beside, never instead.
+        "gate_currency": gate_currency(),
         "commands": [
             {
                 "command": cmd.command,
@@ -590,10 +813,17 @@ def as_dict(here: "Optional[Conditioning]" = None) -> dict:
                         "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),
                     }
                 ),
+                # C3-109: the in-house measurement of this command, on the build
+                # the gate last ran. Absent for commands the gate does not cover —
+                # its population is declared in `sourcecode.perf`, with the
+                # exclusions and their reasons, and an axis nobody measured is
+                # never a number here.
+                "gate_measurement": gate_anchor(cmd.command),
             }
             for cmd in COMMANDS
         ],
@@ -705,6 +935,7 @@ def render_text(here: "Optional[Conditioning]" = None) -> str:
     lines.append(f"  Timings: {REFERENCE_REPOSITORY}, each command measured in isolation.")
     lines.append(f"  {reference_currency()['statement']}")
     lines.append(f"  {field_currency()['statement']}")
+    lines.append(f"  {gate_currency()['statement']}")
     width = max(len(c.command) for c in COMMANDS)
     for cmd in COMMANDS:
         repeat = "repeat cached" if cmd.repeat else "recomputes"
@@ -713,17 +944,30 @@ def render_text(here: "Optional[Conditioning]" = None) -> str:
             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"
             )
-            suffix = f" ({note})" if note else ""
+            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}"
             )
+        _gate = gate_anchor(cmd.command)
+        if _gate:
+            # C3-109: the in-house figure, beside the field's rather than instead
+            # of it — one is at field scale on another build, one is on a build
+            # this project can bring current.
+            lines.append(
+                f"  {' ' * width}    gate:     {_gate['seconds']:g} s at "
+                f"{_thousands(_gate['java_files'])} Java files "
+                f"({_gate['cache_state']} cache, on {_gate['measured_on_version']}, "
+                f"{_gate['host_class']})"
+            )
         if cmd.note:
             lines.append(f"  {' ' * width}    {cmd.note}")
         if here is not None and cmd.command in here.per_command: