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

sourcecode/__init__.py

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

sourcecode/architectural_delta.py

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

sourcecode/cache_model.py

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