sourcecode 4.12.0__tar.gz → 4.14.0__tar.gz

sourcecode-4.14.0/.github/workflows/perf-gate.yml

@@ -0,0 +1,109 @@
+name: Performance regression gate
+
+# F-AP. Field evaluation #16 measured seven commands 2-3.4x slower on a minor
+# release while every payload stayed byte-identical, and named the cause:
+# "no es que haya regresiones - es que no hay nada que las detecte".
+# This is the detector. The threshold, the repository and the gated command
+# population are declared in `sourcecode.perf` and documented in
+# `docs/perf/REGRESSION-GATE.md`; nothing here carries a number of its own.
+
+on:
+  schedule:
+    # Nightly, after the day's merges have settled.
+    - cron: "0 3 * * *"
+  workflow_dispatch:
+    inputs:
+      baseline_ref:
+        description: "Baseline directory under docs/perf/baselines (default: gate-latest)"
+        required: false
+        default: "gate-latest"
+
+concurrency:
+  group: perf-gate
+  cancel-in-progress: false
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    env:
+      # Declares the host class so nightly runs on ephemeral runners are
+      # comparable at all. Recorded in every artifact as `env.host_id_declared`,
+      # so the declaration is visible rather than silent.
+      SOURCECODE_PERF_HOST_ID: github-ubuntu-latest
+      BASELINE_DIR: docs/perf/baselines/${{ github.event.inputs.baseline_ref || 'gate-latest' }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+
+      - name: Prove the gate is armed
+        # A green gate is evidence only when a red one is reachable in the same
+        # job with the same constants. This step fails if a synthetic 3x-slower
+        # cell would have passed.
+        run: python3 scripts/perf_gate.py --self-test
+
+      - name: Read the declared gate configuration
+        id: cfg
+        run: |
+          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 "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
+        run: |
+          mkdir -p fleet
+          git clone --depth 1 "${{ steps.cfg.outputs.repo_url }}" "fleet/${{ steps.cfg.outputs.repo }}"
+
+      - name: Measure
+        env:
+          PERF_FLEET_ROOT: fleet
+        run: |
+          python3 scripts/perf_harness.py \
+            --repos "${{ steps.cfg.outputs.repo }}" \
+            --commands ${{ steps.cfg.outputs.commands }} \
+            --modes "${{ steps.cfg.outputs.mode }}" \
+            --runs "${{ steps.cfg.outputs.runs }}" \
+            --fleet-root fleet \
+            --out perf-run
+
+      - name: Gate
+        run: |
+          python3 scripts/perf_gate.py \
+            --baseline "$BASELINE_DIR" \
+            --current perf-run \
+            --report perf-run/gate.json \
+            --table perf-run/RELEASE-TABLE.md
+
+      - name: Publish the measured table
+        if: always()
+        run: |
+          if [ -f perf-run/RELEASE-TABLE.md ]; then
+            {
+              echo "## Measured wall time per command"
+              echo
+              cat perf-run/RELEASE-TABLE.md
+            } >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - name: Upload artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: perf-gate-${{ github.run_number }}
+          path: |
+            perf-run/**
+            gate-config.json

{sourcecode-4.12.0 → sourcecode-4.14.0}/CHANGELOG.md

@@ -2,6 +2,133 @@
 
 ## [Unreleased]
 
+## [4.14.0] — 2026-08-09
+
+**The Part 1 queue of Amendment N — the four rows field evaluation #17 opened,
+one commit each.** The fourth measurement of the same repository at the same
+commit scored **7,5/10**, the highest of the series, and verified six of the
+previous release's fixes from the outside. Both rows it opened are in the fields
+that describe ASK's *own* reliability, which is where this product can least
+afford to be wrong.
+
+**Fixed in this release:**
+
+- **A truncated answer no longer raises its own confidence (C2-31).** Three
+  complete runs published 395 findings / 98 defects at `confidence_level:
+  medium`; the run the budget cut published 289 / 15 at **`high`**, because the
+  level is derived from the confidence of the high/critical findings *that
+  exist* and the family contributing the medium-confidence ones is the family
+  that did not run. `SpringAuditResult.partial` is now one flag — set by the
+  scopes, by the CLI for a phase that never started, and carried through
+  `merge` — and a partial answer is capped at `low` with `confidence_basis`
+  saying the cut is the reason. `summary` gains `partial`, `counts_are_floor`
+  and `counts_basis`, so the mark lives where the numbers a consumer reads are,
+  not only in `_partial` at the root. The cap is a ceiling and never a floor: a
+  complete run keeps its level and gains no fields.
+- **The rule inventory names rules, and both scopes' (C1-42).** `rules_run`
+  listed four SEC ids in a payload whose findings carried DEAD-001, SEC-008,
+  TX-006, TX-001, SEC-005 and SEC-006, and `rules_not_run` said `[GATE-001]`
+  where the arithmetic proves GATE-004 did not run either. The lists were keyed
+  on the pattern *object's* identity, so a family emitting six rules stood for
+  itself, and `merge` overwrote the TX scope's inventory with the security
+  scope's. `rule_pass.rule_ids_of()` is the one authority, the two lists are
+  unioned across scopes, and `rules_run_count` / `rules_total` sit beside them.
+  Three invariants are asserted over a real audit: every rule that fired is in
+  `rules_run`, the lists never overlap, and a complete `--scope all` run
+  inventories exactly `rule_catalog.ids()`.
+- **The heartbeat is emitted by the work, not only by a thread (C3-80).** Four
+  versions with the same shape: one line at `elapsed=20.1s`, 39 minutes of
+  nothing, then the same stage text seconds before the end. A line-mode
+  heartbeat printed only by a daemon thread depends on that thread being
+  scheduled during exactly the CPU-bound stretch the operator is asking about.
+  `Progress._emit()` is now one seam with one throttle and two callers — the
+  loop on its timer and the analysis in-band — sharing one `_last_emit` stamp,
+  so the line rate is unchanged and a running analysis is always heard from.
+- **The budget cuts inside a rule family (C3-79).** Budget 420 s, elapsed
+  2 376 s: `exhausted()` was asked on a whole-family boundary and one family
+  lasts 39 minutes. `RulePassProgress.tick()` reports counted work and answers
+  *"is the time spent"* in one call, sampling the clock once per 64 units; five
+  families that walk a population take a `FamilyBudget` and stop on a batch
+  boundary. A family cut in flight is in neither list — it is
+  `rules_partially_run` with the count it reached, and the findings it produced
+  are kept, because they were measured. Measured on BroadleafCommerce: a 4,5 s
+  budget stops at 1 408 of 2 766 Java files and ends at 5,1 s.
+
+**Verified in the field, not changed here:** `verify` exiting 2 without contracts
+is C3-75's deliberate half (the waiver `--allow-unverified` and the named
+`unverified_reason` are the fix; a distinct code is a contract change, F-AV), and
+the 4.10.7 performance that never came back is C3-76, which does not reproduce on
+this platform and waits on the Windows runner (F-AW).
+
+Suite 7 787.
+
+## [4.13.0] — 2026-08-08
+
+**The capability queue of Amendment M — the four features field evaluation #16
+asked for, one commit each, after Part 1 closed in 4.12.0.** The evaluation's
+verdict on engineering was *"no es que haya regresiones — es que no hay nada que
+las detecte"*, and its "if you could only do two things" was F-AP and F-AQ, in
+that order. Both ship here, with F-AR and F-AS beside them.
+
+**New in this release:**
+
+- **A release performance gate (F-AP).** `perf.gate_report()` turns a whole run
+  into one verdict against a whole baseline, and three of its four outcomes are
+  not a pass: a cell over the threshold **fails**, a baselined cell this run did
+  not measure **fails** (silence is how "nothing detects a regression" happens),
+  and a cell under the ADR-0006 sample floor **fails**. `scripts/perf_gate.py
+  --self-test` proves the gate is armed by failing a synthetic 3×-slower cell —
+  CI runs it *before* it runs the measurement, because a green gate is evidence
+  only when a red one is reachable on the same constants. Threshold **20 %**,
+  warm mode, one ~3 000-file repository, six repository-wide commands, and the
+  three exclusions published with every verdict. All of it lives in
+  `sourcecode.perf`; `docs/perf/REGRESSION-GATE.md` embeds `--print-config`'s
+  output verbatim and a test asserts they are the same bytes.
+- **The measured times are published, generated (F-AP, second rider).**
+  `perf.release_table()` builds the per-command / per-repository-scale table a
+  release note carries, from the run's own artifacts. An axis that was not
+  measured prints `unknown`, never `0`. And `cache model`'s figures now name the
+  build they were measured on (3.2.2) beside the build you are running, so a
+  table nine releases old cannot read as this build's measurement.
+- **`--jobs N` / `-j` / `ASK_JOBS` (F-AQ)**, default `cpu_count() - 1`. The
+  fourth consecutive evaluation to ask for parallelism was the first to sample
+  it: `threads=1`, `CPU/wall = 0,92…0,95`, 54 minutes, 20 cores. Worker
+  processes now parse files into the *same* content-addressed cache the IR loop
+  is about to read, so the loop is untouched and **byte-identity is structural,
+  not inspected** — no worker output reaches the payload by any route. Measured
+  on 2 766 Java files, both sides parse-cold with their own cache root: 5,36 s →
+  3,46 s (**1,55×**), CPU/wall 2,07, IR hash identical. Every failure mode — no
+  pool, a faulting worker, a frozen build, a disabled cache, a repository under
+  the 200-file floor — degrades to today's sequential parse and returns a receipt
+  naming the reason.
+- **`ASK_PARSE_CACHE_MAX_MB` (F-AR)**, default **512 MB**, least-recently-used,
+  enforced on write and published in `cache status` beside the size it bounds.
+  C3-70 retires the generation that can never be read again — an exact rule, and
+  exact rules only cover what they can foresee. This bounds what they cannot:
+  many repositories, many branches, one machine, and an owner who never runs
+  `ask cache clear`. Reads refresh recency (hourly granularity, so a hit is not a
+  disk write), an entry and its body-fact blob are evicted together, and
+  `ASK_PARSE_CACHE_MAX_MB=0` turns the guard off deliberately and says so.
+- **`--no-write` / `ASK_READONLY=1` (F-AS)** — nothing is created inside the
+  analysed repository, and a command that cannot answer without writing says so
+  instead of writing, in the same error envelope every other refusal uses.
+  Accepted by **every** command (consumed before the parser, the `--detach`
+  precedent), because a mode five commands accept and seventy-nine reject is a
+  mode whose one refusing run is the run that writes. Each refusal is announced
+  once on stderr with its path. Shared caches outside the repository are
+  untouched — an auditor is protecting a checkout, not a home directory.
+- **`ask --help` names every command that writes into the repository**, with the
+  condition beside it ("only with `--snapshot`"), generated from one authority.
+
+**Measured, not fixed, and said so:** the second half of F-AQ — *"one audit per
+run, shared by the compositions"* — was measured before being touched.
+Instrumenting `build_risk` on a real repository counts `run_tx_audit` **1×** and
+`run_security_audit` **1×**: `risk` already hands its findings to every impact
+chain it composes (C3-42-b), so the duplication the field named is between two
+*processes*, not inside one. That needs a persisted audit keyed on the worktree
+signature, and it is not in this release. What ships is the regression test that
+keeps the in-run property true.
+
 ## [4.12.0] — 2026-08-08
 
 **Field evaluation #16 — the third round on the same repository and commit, and the

{sourcecode-4.12.0 → sourcecode-4.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.12.0
+Version: 4.14.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.12.0-blue)
+![Version](https://img.shields.io/badge/version-4.14.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`**
@@ -108,7 +108,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.12.0 — and, on a build that has aged,
+ask version                    # ask 4.14.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.12.0 → sourcecode-4.14.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.12.0-blue)
+![Version](https://img.shields.io/badge/version-4.14.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`**
@@ -70,7 +70,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.12.0 — and, on a build that has aged,
+ask version                    # ask 4.14.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.12.0 → sourcecode-4.14.0}/pyproject.toml

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

sourcecode-4.14.0/scripts/perf_gate.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Release performance gate (F-AP) — compare a run against a baseline, one verdict.
+
+`scripts/perf_harness.py` measures; this decides. It reads two directories of
+`perf-baseline-v1` cells, gates every cell it can match, and exits non-zero when
+any of them regressed beyond the declared threshold, when a baselined cell was not
+measured at all, or when a cell's sample is under the ADR-0006 floor.
+
+The threshold, the repository, the mode and the excluded commands are constants in
+`sourcecode.perf` — this script never carries a number of its own, and
+`docs/perf/REGRESSION-GATE.md` is generated from the same constants.
+
+Usage:
+    # gate a fresh run against the last release's baseline
+    python3 scripts/perf_gate.py \
+        --baseline docs/perf/baselines/4.12.0 \
+        --current  docs/perf/baselines/4.13.0 \
+        --report   gate.json --table RELEASE-TABLE.md
+
+    # prove the gate is armed: a synthetic 3x-slower cell must fail it
+    python3 scripts/perf_gate.py --self-test
+
+    # print the declared configuration (what the doc renders from)
+    python3 scripts/perf_gate.py --print-config
+"""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+from sourcecode import perf  # noqa: E402
+
+
+def load_cells(directory: Path) -> dict[str, dict]:
+    """Every `perf-baseline-v1` cell in *directory*, keyed by `<repo>__<cmd>__<mode>`.
+
+    Gate artifacts (`*.gate.json`) and anything that is not a cell are skipped
+    rather than mis-read: a directory that also holds a report must not turn the
+    report into a measurement.
+    """
+    cells: dict[str, dict] = {}
+    if not directory.is_dir():
+        return cells
+    for path in sorted(directory.glob("*.json")):
+        if path.name.endswith(".gate.json"):
+            continue
+        try:
+            cell = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        if not isinstance(cell, dict) or cell.get("schema_version") != perf.SCHEMA_VERSION:
+            continue
+        cells[perf.cell_id(cell)] = cell
+    return cells
+
+
+def _self_test() -> int:
+    """A deliberately slowed command must fail the gate. Run in CI before the gate.
+
+    This is the exit criterion stated as an executable check: it is not enough for
+    the gate to exist and be green — a green gate is only evidence when a red one
+    is reachable on the same machine, in the same job, with the same constants.
+    """
+    base = perf.build_baseline_cell(
+        tool_version="self-test",
+        command="spring-audit",
+        repo={"name": perf.RELEASE_GATE_REPO, "commit": "self-test", "files": 3000},
+        mode=perf.RELEASE_GATE_MODE,
+        wall_ms_runs=[1000.0] * perf.RELEASE_GATE_MIN_RUNS,
+        rss_bytes_runs=[1.0] * perf.RELEASE_GATE_MIN_RUNS,
+    )
+    slowed = copy.deepcopy(base)
+    slowed["wall_ms"] = {k: v * 3.0 for k, v in base["wall_ms"].items()}
+
+    cid = perf.cell_id(base)
+    red = perf.gate_report({cid: base}, {cid: slowed})
+    green = perf.gate_report({cid: base}, {cid: base})
+    dropped = perf.gate_report({cid: base}, {})
+
+    ok = (not red["passed"]) and green["passed"] and (not dropped["passed"])
+    print(f"self-test: 3x slower -> {'FAIL (correct)' if not red['passed'] else 'PASS (BROKEN)'}")
+    print(f"self-test: unchanged -> {'PASS (correct)' if green['passed'] else 'FAIL (BROKEN)'}")
+    print(f"self-test: cell gone -> {'FAIL (correct)' if not dropped['passed'] else 'PASS (BROKEN)'}")
+    if not ok:
+        print("perf gate self-test FAILED: the gate would not catch a regression.",
+              file=sys.stderr)
+    return 0 if ok else 1
+
+
+def _print_config() -> int:
+    print(json.dumps({
+        "schema_version": perf.GATE_SCHEMA_VERSION,
+        "threshold": perf.RELEASE_GATE_THRESHOLD,
+        "repository": perf.RELEASE_GATE_REPO,
+        "repository_url": perf.RELEASE_GATE_REPO_URL,
+        "repository_scale": perf.RELEASE_GATE_REPO_SCALE,
+        "mode": perf.RELEASE_GATE_MODE,
+        "min_runs": perf.RELEASE_GATE_MIN_RUNS,
+        "commands": list(perf.RELEASE_GATE_COMMANDS),
+        "exclusions": [
+            {"command": c, "reason": r} for c, r in perf.RELEASE_GATE_EXCLUSIONS
+        ],
+    }, indent=2))
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    ap.add_argument("--baseline", type=Path, help="Directory of the release being compared against.")
+    ap.add_argument("--current", type=Path, help="Directory of this run's cells.")
+    ap.add_argument("--threshold", type=float, default=perf.RELEASE_GATE_THRESHOLD,
+                    help=f"Max allowed regression ratio (declared default: "
+                         f"{perf.RELEASE_GATE_THRESHOLD}).")
+    ap.add_argument("--min-runs", type=int, default=perf.RELEASE_GATE_MIN_RUNS)
+    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("--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",
+                    help="Prove the gate is armed; measures nothing.")
+    ap.add_argument("--print-config", action="store_true",
+                    help="Print the declared gate configuration as JSON.")
+    args = ap.parse_args()
+
+    if args.self_test:
+        return _self_test()
+    if args.print_config:
+        return _print_config()
+    if not args.current:
+        ap.error("--current is required (or use --self-test / --print-config)")
+
+    current = load_cells(args.current)
+    if not current:
+        print(f"no perf cells in {args.current} — nothing was measured, "
+              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 {}
+
+    report = perf.gate_report(
+        baseline, current,
+        max_regression=args.threshold,
+        allow_incomparable=args.allow_incomparable,
+        require_min_runs=args.min_runs,
+    )
+    table = perf.release_table(list(current.values()), gate=report)
+
+    if args.report:
+        args.report.parent.mkdir(parents=True, exist_ok=True)
+        args.report.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+    if args.table:
+        args.table.parent.mkdir(parents=True, exist_ok=True)
+        args.table.write_text(table, encoding="utf-8")
+
+    print(table)
+    if not baseline:
+        print("no baseline directory — cells recorded, nothing compared.", file=sys.stderr)
+    for cid in report["regressions"]:
+        print(f"REGRESSION: {cid}", file=sys.stderr)
+    for cid in report["missing_cells"]:
+        print(f"NOT MEASURED (baselined): {cid}", file=sys.stderr)
+    for cid in report["under_sampled_cells"]:
+        print(f"UNDER-SAMPLED: {cid}", file=sys.stderr)
+
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{sourcecode-4.12.0 → sourcecode-4.14.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.12.0"
+__version__ = "4.14.0"

{sourcecode-4.12.0 → sourcecode-4.14.0}/src/sourcecode/architectural_baseline.py

@@ -37,6 +37,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from sourcecode import __version__ as TOOL_VERSION
+from sourcecode import readonly as _readonly
 from sourcecode.architectural_delta import ArchMetrics, diff_metrics, extract_metrics
 from sourcecode.perf import collect_env
 
@@ -412,6 +413,9 @@ def protect_ask_dir(out_dir: Path, *, announce: bool = True) -> None:
         marker = ask_dir / ".gitignore"
         if not marker.exists():
             created = not ask_dir.exists()
+            # F-AS: the guard raises an OSError, which the `except OSError` below
+            # turns into "did not write" — the mode's promise, no new branch.
+            _readonly.guard(ask_dir, what="this tool's own directory")
             ask_dir.mkdir(parents=True, exist_ok=True)
             marker.write_text(_ASK_DIR_GITIGNORE, encoding="utf-8")
             if announce and created:
@@ -442,6 +446,7 @@ def _announce_ask_dir(ask_dir: Path) -> None:
 
 def write_baseline(baseline: dict, out_dir: Path) -> Path:
     """Write `baseline` as deterministic JSON under `out_dir`; return the file path."""
+    _readonly.guard(out_dir, what="baseline history directory")
     out_dir.mkdir(parents=True, exist_ok=True)
     protect_ask_dir(out_dir)
     path = out_dir / _baseline_filename(baseline)

{sourcecode-4.12.0 → sourcecode-4.14.0}/src/sourcecode/cache_model.py

@@ -99,6 +99,15 @@ REFERENCE_REPOSITORY = (
 #: figures are relative to.
 REFERENCE_JAVA_FILES = 2000
 
+#: The build the reference figures were measured on. F-AP's second rider: C3-60
+#: conditioned these figures on the repository in hand; this is the other half —
+#: **keeping them current**, or, when they are not current, saying so. A table
+#: measured nine releases ago and printed without its provenance is a prediction
+#: presented as a measurement, which is the one thing this product does not do.
+#: The nightly gate (`docs/perf/REGRESSION-GATE.md`) is what re-measures them; this
+#: constant is what makes the gap visible until it does.
+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
 #: Windows 11 / PowerShell 5.1 / pipx / Python 3.10: `spring-audit` on a
@@ -164,7 +173,9 @@ LAYERS: tuple[Layer, ...] = (
         location="~/.sourcecode/parse-cache-v1/",
         invalidated_by=(
             "the file's own bytes and the extractor's source — content-addressed, "
-            "so it is never stale and never needs invalidating"
+            "so it is never stale and never needs invalidating. Bounded by "
+            "`ASK_PARSE_CACHE_MAX_MB` (default 512 MB, least-recently-used, "
+            "enforced on write) and reported in `cache status` (F-AR)"
         ),
         warmed="filled for every Java file the warm parses",
     ),
@@ -358,6 +369,34 @@ class Conditioning:
         )
 
 
+def reference_currency() -> dict:
+    """How old the reference figures are, in releases the reader can name (F-AP).
+
+    Returns the build the figures were measured on, the build running now, and
+    whether they are the same. The gap is not converted into a count of releases:
+    versions are not a distance and this module does not invent one. Naming both
+    builds is enough for a reader to see that a figure was measured on a different
+    one — which is the whole defect: *"no predice nada a 3 342 ficheros"* applies
+    to the size axis, and this is the same failure on the time axis.
+    """
+    from sourcecode import __version__
+
+    current = __version__
+    return {
+        "measured_on_version": REFERENCE_MEASURED_VERSION,
+        "running_version": current,
+        "current": REFERENCE_MEASURED_VERSION == current,
+        "statement": (
+            f"Measured on {REFERENCE_MEASURED_VERSION}; you are running {current}. "
+            f"The figures are that build's on that repository — they are not a "
+            f"prediction for this one, and the nightly performance gate "
+            f"(docs/perf/REGRESSION-GATE.md) is what re-measures them."
+            if REFERENCE_MEASURED_VERSION != current
+            else f"Measured on {current}, the build you are running."
+        ),
+    }
+
+
 def as_dict(here: "Optional[Conditioning]" = None) -> dict:
     """The whole model as data — what `ask cache model --json` emits."""
     conditioned: dict = {}
@@ -386,6 +425,9 @@ def as_dict(here: "Optional[Conditioning]" = None) -> dict:
         ],
         "reference_repository": REFERENCE_REPOSITORY,
         "reference_java_files": REFERENCE_JAVA_FILES,
+        # F-AP rider: the figures carry the build they were measured on, so a
+        # 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).
@@ -427,6 +469,15 @@ def render_markdown() -> str:
     out.append("")
     out.append(f"Measured on {REFERENCE_REPOSITORY}, each command in isolation.")
     out.append("")
+    # The build, not the gap: this block is a checked-in document, so naming the
+    # *running* version here would make the doc drift on every release. `cache
+    # model` names both, because there a reader has a running build to compare to.
+    out.append(
+        f"Measured on release {REFERENCE_MEASURED_VERSION}. Figures are that "
+        f"build's on that repository, not a prediction for yours; the nightly "
+        f"performance gate (`docs/perf/REGRESSION-GATE.md`) is what re-measures them."
+    )
+    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:
@@ -504,6 +555,7 @@ def render_text(here: "Optional[Conditioning]" = None) -> str:
     lines.append("")
     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']}")
     width = max(len(c.command) for c in COMMANDS)
     for cmd in COMMANDS:
         repeat = "repeat cached" if cmd.repeat else "recomputes"