sourcecode 5.0.1__tar.gz → 5.2.0__tar.gz

{sourcecode-5.0.1 → sourcecode-5.2.0}/.github/workflows/perf-gate.yml

@@ -7,7 +7,14 @@ name: Performance regression gate
 # population are declared in `sourcecode.perf` and documented in
 # `docs/perf/REGRESSION-GATE.md`; nothing here carries a number of its own.
 
+# C3-110: for five releases this ran nightly and on demand, and nothing in the
+# release path asked it anything - so a release could regress and ship, and the
+# nightly would report it to nobody at 03:00. A tag is a release, and a release
+# is gated.
 on:
+  push:
+    tags:
+      - "v*"
   schedule:
     # Nightly, after the day's merges have settled.
     - cron: "0 3 * * *"
@@ -60,7 +67,7 @@ jobs:
           echo "repo_url=$(python3 -c "import json;print(json.load(open('gate-config.json'))['repository_url'])")" >> "$GITHUB_OUTPUT"
           echo "repo=$(python3 -c "import json;print(json.load(open('gate-config.json'))['repository'])")" >> "$GITHUB_OUTPUT"
           echo "fleet_subdir=$(python3 -c "import json;print(json.load(open('gate-config.json'))['fleet_subdir'])")" >> "$GITHUB_OUTPUT"
-          echo "mode=$(python3 -c "import json;print(json.load(open('gate-config.json'))['mode'])")" >> "$GITHUB_OUTPUT"
+          echo "modes=$(python3 -c "import json;print(' '.join(json.load(open('gate-config.json'))['modes']))")" >> "$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"
 
@@ -79,16 +86,21 @@ jobs:
           python3 scripts/perf_harness.py \
             --repos "${{ steps.cfg.outputs.repo }}" \
             --commands ${{ steps.cfg.outputs.commands }} \
-            --modes "${{ steps.cfg.outputs.mode }}" \
+            --modes ${{ steps.cfg.outputs.modes }} \
             --runs "${{ steps.cfg.outputs.runs }}" \
             --fleet-root fleet \
             --out perf-run
 
       - name: Gate
+        # Two comparisons, one verdict. `--baseline` is the previous release and
+        # decides; `--drift-baseline` is the best build ever measured and is
+        # published - a staircase of steps each under the threshold is invisible
+        # to the first and visible to the second (C3-110).
         run: |
           python3 scripts/perf_gate.py \
             --baseline "$BASELINE_DIR" \
             --require-baseline \
+            --drift-baseline "docs/perf/baselines/$(python3 -c "import json;print(json.load(open('gate-config.json'))['drift_baseline'])")" \
             --current perf-run \
             --report perf-run/gate.json \
             --table perf-run/RELEASE-TABLE.md

{sourcecode-5.0.1 → sourcecode-5.2.0}/CHANGELOG.md

@@ -2,6 +2,173 @@
 
 ## [Unreleased]
 
+## [5.2.0] — 2026-08-11
+
+**The queue field evaluation #26 opened, and the row underneath the other rows.**
+The eleventh round retested 5.1.0 on the same subject with the same total purge,
+scored 8,4/10, and printed the series that names the real defect: `validation` on
+one commit of one repository, across eleven releases —
+`35,4 → 14,0 → 36,8 → 35,8 → 41,8 → 17,8 → 39,8 → 13,8 → 34,1 → 39,5 s`. Four
+oscillations of ~2,9×, no net direction, and a green gate throughout.
+
+No analysis changes: what moves is what the product does when there is nothing to
+diff, when two states are one state, when it writes an IR to a file, and when it
+tells you what a command costs.
+
+### Fixed
+
+- **The release is gated, over the population the field measures (C3-110).** The
+  detector has existed since 4.13.0 and had never blocked a release: nothing in
+  the release path asked it anything (`push: tags: v*` does now; the nightly
+  stays, to catch a regression the day it lands rather than the day it ships);
+  its population was six commands against the eighteen the field times (`risk`,
+  `modernize`, `repo-ir` and `data-exposure` are gated now, and every exclusion
+  carries its reason); and it compared against the previous release alone, which
+  passes every step of a staircase — `drift_report()` publishes the distance from
+  the best build this product has measured, without deciding, because some of that
+  distance is work deliberately added and the comparison cannot tell which. Two
+  defects found while measuring the gate itself: **cold cells were not cold**
+  (only the snapshot layer was isolated, so every cold run inherited the previous
+  cell's parse store — the exact regime four in-house A/Bs failed to reproduce a
+  field regression in), and **a failed run was recorded as a fast one**
+  (`--no-cache` is rejected by most subcommands, so `ask risk . --no-cache` exited
+  2 and the harness timed the error envelope at ~0,29 s on any repository).
+- **A figure that advises names the build it was measured on (C3-110/C3-109).**
+  `spring-audit` published *"8,4 s (4.18.0)"* while the same command measured
+  31,0 s on the build in hand, and `risk` carried *"not a foreground run here — a
+  nightly job"* off a 73,3 s anchor from another build while the field ran it in
+  the foreground in 77,2 s. Advising surfaces now say the build **and** that this
+  build has not been re-measured, and *"not a foreground run"* is reserved for
+  figures above 120 s: between the thresholds a command is offered with its cost
+  attached. The anchors are refreshed from evaluation #26.
+- **A tree with nothing to diff is not analysed (C3-102).** `verify-edit` spent
+  119,5 s on the field's repository to produce 807 bytes saying the tree is clean.
+  Every axis diffs the two models and on a clean tree they are one object, so no
+  analysis can change the answer: the clean run takes a model already cached for
+  that tree state and builds nothing when there is none. The verdict publishes
+  what it read, including the claim it does not make — `pass` means the working
+  tree equals HEAD, not that HEAD was audited. **9,94 s → 0,62 s** on a clean
+  worktree of BroadleafCommerce, every layer purged.
+- **One tree state is not analysed at all (C3-107).** 5.1.0 stopped the second
+  build; this stops the first. `delta` **8,08 → 0,35 s** and `contract-diff`
+  **13,69 → 0,33 s** on the same subject, with every delta published as the zero
+  determinism proves and every per-side total as `null` — never 0, because an axis
+  nobody measured is unknown. `contract-diff` also states what `unchanged` means:
+  the difference between the two states, not the health of the contract in either.
+- **The written IR has a ceiling, and the refusal reaches a script (C3-111).** The
+  stdout guard was real and the `-o` path had no limit at all, while the pre-build
+  size band travels through a notice that is silent off-TTY — so the run that
+  writes the file is the one that hears nothing: 101 254 852 B, byte-identical
+  across three releases. An estimate above 50 MB now refuses **before the
+  analysis**, through the error envelope, naming the band, its basis and the four
+  ways out that already existed (`--summary-only`, `--max-nodes/--max-edges`,
+  `--gzip`, `--force`).
+
+### Measured, not fixed
+
+- **C3-103 (two root views of one state).** On a purged BroadleafCommerce
+  worktree: `--compact --git-context --env-map` 14,1 s, `--agent` after it 20,5 s,
+  `--agent` alone 25,3 s. The analysis difference between the two cores is exactly
+  one flag (`graph_modules`), so the increment is augmenting a cached core with one
+  analyzer — with byte-identity against a cold `--agent` run as its acceptance
+  test. A core that is *almost* the cold one is the C3-94 class of defect, so it is
+  not attempted under a deadline.
+
+## [5.1.0] — 2026-08-11
+
+**The operational queue field evaluation #25 left open, and the one row it opened
+that this project can act on.** No analysis changes: `endpoints`, `validation`,
+`posture`, `spring-audit` and `migrate-check` were re-run on spring-petclinic,
+jobrunr and BroadleafCommerce against 5.0.1 from a purged cache, and every
+payload matches byte for byte except the fields that are clocks by definition
+(`generated_at`, `analysis_time_ms`). What moves is what the product does when
+you clear a cache, compare a tree with itself, ask it whether you have edited
+anything, or read what a command costs — and `delta` / `contract-diff` gain one
+declared key, `comparison.identical_states`.
+
+### Fixed
+
+- **A confirmation prompt that cannot be answered is diagnosed, not raised
+  (C3-106).** v1.45.0 guarded the case it knew about — stdin that is not a
+  terminal — and the field found the one it does not cover: a PowerShell 5.1
+  session driven by a harness where `isatty()` answers true and the read hits
+  end-of-input at once, producing a Python traceback under a half-printed prompt.
+  All four prompts (`cache clear`, `cache context-clear`, `mcp init`,
+  `mcp remove` — the last two had no guard at all) now emit the product's own
+  envelope: `INVALID_INPUT`, the command that asked, `reason:
+  unanswerable_prompt`, and the `--yes` flag that removes the question. Exit 2,
+  because nothing was done. A plain "no" is still an answer: exit 1.
+- **The shared parse store can be cleared, and says so (C3-104).** `cache status`
+  publishes three layers and `cache clear` emptied two; the third — the per-file
+  parse store — had no eviction surface at all, so a from-scratch audit meant
+  `rm -rf ~/.sourcecode/parse-cache-v1`, a path the field had to learn from our
+  documentation. `ask cache clear --global` empties it and reports what it
+  removed; the default run names the layer, its size and the flag. Global on
+  purpose: the store is content-addressed across repositories, so "this
+  repository's entries" is not a set it can produce.
+- **One tree state is read once (C3-107).** `delta` and `contract-diff` built both
+  sides and then asked whether they differ. Identity is decided first — the
+  commit on the ref path, `cache.worktree_signature` on the checkout path, and
+  only when both sides produced a signature — so identical refs are materialised
+  once and the head IR is the base one. `comparison.identical_states` is always
+  present, with its basis, so a consumer can tell a degenerate comparison from a
+  real one. Wall time does not move on macOS (9,28 → 9,21 s on BroadleafCommerce):
+  the caches already served the second side, and what this removes is work whose
+  result the product already held.
+- **A clean tree is not checked out a second time (C3-102).** `verify-edit` reads
+  the shared entry instead of materialising HEAD in a throwaway worktree when git
+  reports the tree unmodified, and writes what it builds into both the shared and
+  the HEAD-sha lanes, so the first edit after a clean run is still warm. The
+  measured gain is small (10,32 → 10,03 s cold on BroadleafCommerce): the field's
+  76,6 s is one build of a 3 342-file repository, not a duplicated one. What
+  changes is that the build is no longer written where only `verify-edit` can
+  read it, and a clean-tree run no longer writes `.git/worktrees` in your
+  repository.
+- **The `repo-ir` size band contains the largest repository ever measured
+  (C3-105).** The band was 10,8-27,9 KB/file and the field measured 30,3
+  (101 254 852 B over 3 342 files) — the one number offered for planning excluded
+  the measurement a reader would take. The fifth sample is admitted, and the band
+  now publishes its sample size and its direction: the top under-states, because
+  the sample that set it counted tests among its files and the estimate does not.
+
+### Added
+
+- **A cached core richer than the requested view now serves it (C3-103).** The
+  overlay lookup already reused a *poorer* base and re-attached what it flipped;
+  the reverse was never tried, so asking for less than what was on disk paid for
+  a full analysis. The candidate set is symmetric now, with the dropped blocks
+  removed from the view so a caller never receives something it did not ask for.
+  On jobrunr: `--compact --git-context` then `--compact`, 1,15 s → **0,32 s**,
+  payload equal to a cold run block for block.
+- **Every build carries an in-house measurement of itself (C3-109).** The field
+  anchors are the field's, on their repository and their machine, so this project
+  can never refresh them — which is why B17 reopened one release after it closed:
+  labelling a figure does not re-measure it. `ask cache model` now prints the
+  release gate's own figure beside the field's (`gate:`, `gate_measurement`,
+  `gate_currency()`), with its scale, cache state, host class and build. Beside,
+  never instead — and when the in-house one is behind there is a command to fix
+  it rather than an evaluation to wait for. Generated from the committed baseline
+  by `scripts/sync_gate_anchors.py`; the suite fails if the two disagree.
+- **The gate measures the cold regime (C3-108).** Four consecutive in-house A/Bs
+  have failed to reproduce a field-reported regression, and the gate measured
+  warm only — while every field round since #23 purges every layer first. Cold
+  cells are captured and published (`observed_not_gated`, `decides: false` per
+  cell) and still may not block a release, because a cold median on an ephemeral
+  runner carries a cold page cache as well as a cold parse store.
+
+### Not fixed, and why
+
+- **The 2-2,6x regression across sixteen commands reported between 4.18.0 and
+  5.0.1 (C3-108) is open and unattributed.** Measured here on the field's own
+  method — every layer purged before each run — three builds on BroadleafCommerce
+  land within 2 % (`endpoints` 4,96 / 4,19 / 4,19 s · `spring-audit` 9,87 / 9,76 /
+  9,75 s · `repo-ir` 4,20 / 4,12 / 4,21 s · `validation` 9,39 / 9,26 / 9,33 s for
+  5.0.0 / 4.18.0 / 5.0.1), and the ADR-0006 harness on openmrs-core lands between
+  -0,6 % and +1,8 %, inside the ±5 % noise floor. The 4.18.0→5.0.1 diff is 13
+  files and 702 insertions, two of them on an analysis path and neither adding a
+  pass. A 2x a customer can measure is high whatever its cause, so the row stays
+  open: what it needs is a same-session A/B on the machine that sees it.
+
 ## [5.0.1] — 2026-08-11
 
 **A patch on the release that made the product's own cost figures honest, for the

{sourcecode-5.0.1 → sourcecode-5.2.0}/PKG-INFO

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

{sourcecode-5.0.1 → sourcecode-5.2.0}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.0.1-blue)
+![Version](https://img.shields.io/badge/version-5.2.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`**
@@ -88,7 +88,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.0.1 — and, on a build that has aged,
+ask version                    # ask 5.2.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.0.1 → sourcecode-5.2.0}/pyproject.toml

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

{sourcecode-5.0.1 → sourcecode-5.2.0}/scripts/perf_gate.py

@@ -108,8 +108,17 @@ def _print_config() -> int:
         "fleet_subdir": FLEET.get(perf.RELEASE_GATE_REPO, perf.RELEASE_GATE_REPO),
         "repository_scale": perf.RELEASE_GATE_REPO_SCALE,
         "mode": perf.RELEASE_GATE_MODE,
+        # C3-108: what is measured and what decides are two lists now. The
+        # workflow reads `modes` for the harness; the gate reads the other.
+        "modes": list(perf.RELEASE_GATE_MEASURED_MODES),
+        "deciding_modes": list(perf.RELEASE_GATE_DECIDING_MODES),
         "min_runs": perf.RELEASE_GATE_MIN_RUNS,
         "commands": list(perf.RELEASE_GATE_COMMANDS),
+        # C3-110: what a command needs to be measurable at all, in one place the
+        # workflow reads instead of typing flags of its own.
+        "command_args": {k: list(v) for k, v in sorted(perf.RELEASE_GATE_COMMAND_ARGS.items())},
+        "drift_baseline": perf.RELEASE_GATE_DRIFT_BASELINE,
+        "drift_threshold": perf.RELEASE_GATE_DRIFT_THRESHOLD,
         "exclusions": [
             {"command": c, "reason": r} for c, r in perf.RELEASE_GATE_EXCLUSIONS
         ],
@@ -135,6 +144,9 @@ def main() -> int:
                          "to compare against records every cell as `new` and passes; "
                          "that is a recording, not a gate, and CI must not read it "
                          "as one.")
+    ap.add_argument("--drift-baseline", type=Path,
+                    help="Directory of the best measured build. Compared and "
+                         "published; never fails the run (C3-110).")
     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",
@@ -169,6 +181,16 @@ def main() -> int:
         allow_incomparable=args.allow_incomparable,
         require_min_runs=args.min_runs,
     )
+    drift = None
+    if args.drift_baseline:
+        drift_cells = load_cells(args.drift_baseline)
+        if drift_cells:
+            drift = perf.drift_report(drift_cells, current)
+            report["drift"] = drift
+        else:
+            print(f"no drift-baseline cells in {args.drift_baseline} — the "
+                  f"distance from the best measured build was not computed.",
+                  file=sys.stderr)
     table = perf.release_table(list(current.values()), gate=report)
 
     if args.report:
@@ -187,6 +209,11 @@ def main() -> int:
         print(f"NOT MEASURED (baselined): {cid}", file=sys.stderr)
     for cid in report["under_sampled_cells"]:
         print(f"UNDER-SAMPLED: {cid}", file=sys.stderr)
+    if drift:
+        for entry in drift["cells"]:
+            if entry.get("status") == "drifted":
+                print(f"DRIFT vs {drift['reference']}: {entry['cell']} "
+                      f"x{entry['ratio']}", file=sys.stderr)
 
     return 0 if report["passed"] else 1
 

{sourcecode-5.0.1 → sourcecode-5.2.0}/scripts/perf_harness.py

@@ -118,19 +118,44 @@ def build_argv(command: str, repo_path: Path, cold: bool) -> list[str]:
         argv.append(command)
     argv.append(str(repo_path))
     argv += ["--format", "json"]
-    if cold:
-        argv.append("--no-cache")
+    # C3-110: some commands need an argument to be measurable at all, and the one
+    # authority for which is `perf`, not this script and not a workflow.
+    argv += list(perf.RELEASE_GATE_COMMAND_ARGS.get(command, ()))
+    # C3-110: `--no-cache` used to be appended here for cold cells, and most
+    # subcommands **reject** it — `ask risk <repo> --no-cache` exits 2 with
+    # INVALID_INPUT — so the cold cell for every one of them timed an error
+    # envelope (~0,29 s on any repository, any size). Cold is now what the field
+    # means by cold: both cache trees emptied before the run (see `measure_cell`),
+    # which needs no flag and works for every command in the population.
     return argv
 
 
+class HarnessRunFailed(RuntimeError):
+    """A measured invocation did not succeed, so it is not a measurement (C3-110).
+
+    The gate's whole claim is that a number came from the command doing its work.
+    A run that exits non-zero produced an error envelope in a third of a second on
+    a repository of any size, and recording that as `wall_ms` is not a slow gate —
+    it is a gate reporting green on a command it never ran.
+    """
+
+
 def run_once(argv: list[str], env: dict[str, str], perf_log: Path) -> tuple[float, float, dict | None]:
-    """Run the CLI once. Returns (wall_ms, rss_bytes, phase_ms | None)."""
+    """Run the CLI once. Returns (wall_ms, rss_bytes, phase_ms | None).
+
+    Raises :class:`HarnessRunFailed` on a non-zero exit: see the class docstring.
+    """
     if perf_log.exists():
         perf_log.unlink()
     rss_before = resource.getrusage(resource.RUSAGE_CHILDREN).ru_maxrss
     t0 = time.perf_counter()
-    subprocess.run(argv, env=env, capture_output=True, timeout=1800)
+    proc = subprocess.run(argv, env=env, capture_output=True, timeout=1800)
     wall_ms = (time.perf_counter() - t0) * 1000.0
+    if proc.returncode != 0:
+        detail = (proc.stderr or b"")[:400].decode("utf-8", "replace").strip()
+        raise HarnessRunFailed(
+            f"exit {proc.returncode} from `{' '.join(argv)}`: {detail or 'no stderr'}"
+        )
     rss_after = resource.getrusage(resource.RUSAGE_CHILDREN).ru_maxrss
     # ru_maxrss for RUSAGE_CHILDREN is the peak among reaped children; the delta
     # approximates this run's peak. Approximate by construction — documented.
@@ -156,12 +181,21 @@ def measure_cell(command: str, repo_path: Path, mode: str, runs: int) -> dict:
     phases: list[dict] = []
 
     with tempfile.TemporaryDirectory(prefix="perf-cache-") as cache_dir, \
+         tempfile.TemporaryDirectory(prefix="perf-ctx-") as ctx_dir, \
          tempfile.TemporaryDirectory(prefix="perf-log-") as log_dir:
         perf_log = Path(log_dir) / "phases.jsonl"
         base_env = dict(os.environ)
         base_env[perf.ENV_ENABLE] = "1"
         base_env[perf.ENV_LOG] = str(perf_log)
         base_env["SOURCECODE_CACHE_DIR"] = cache_dir
+        # **C3-110.** `SOURCECODE_CACHE_DIR` isolates the snapshot/view layer and
+        # nothing else: the shared CIR and the content-addressed parse store live
+        # under `SOURCECODE_CONTEXT_CACHE_DIR` (default `~/.sourcecode`), so every
+        # "cold" cell ran with a parse cache the previous cell had filled. The
+        # cold regime C3-108 added to the gate is the regime every field report
+        # since #23 measures — after purging exactly these two trees — and it was
+        # the one regime the harness was not measuring.
+        base_env["SOURCECODE_CONTEXT_CACHE_DIR"] = ctx_dir
 
         # Warm mode: one un-recorded priming run to populate the cache, then the
         # first measured warm run is still discarded (belt and suspenders).
@@ -169,9 +203,10 @@ def measure_cell(command: str, repo_path: Path, mode: str, runs: int) -> dict:
         for i in range(n):
             argv = build_argv(command, repo_path, cold=cold)
             if cold:
-                # Each cold run gets a pristine cache dir.
-                for child in Path(cache_dir).iterdir():
-                    shutil.rmtree(child, ignore_errors=True) if child.is_dir() else child.unlink()
+                # Each cold run gets pristine cache dirs — both of them (C3-110).
+                for base in (cache_dir, ctx_dir):
+                    for child in Path(base).iterdir():
+                        shutil.rmtree(child, ignore_errors=True) if child.is_dir() else child.unlink()
             wall, rss, phase = run_once(argv, base_env, perf_log)
             if mode == "warm" and i == 0:
                 continue  # discard cache-fill run
@@ -234,6 +269,7 @@ def main() -> int:
 
     out_dir.mkdir(parents=True, exist_ok=True)
     failures: list[tuple[str, dict]] = []
+    not_measured: list[str] = []
     for cmd, name, mode in plan:
         subdir = FLEET.get(name, name)
         repo_path = args.fleet_root / subdir
@@ -245,6 +281,15 @@ def main() -> int:
             cell = measure_cell(cmd, repo_path, mode, args.runs)
         except subprocess.TimeoutExpired:
             print(" TIMEOUT", file=sys.stderr)
+            not_measured.append(f"{name}__{cmd or 'ask'}__{mode}: timeout")
+            continue
+        except HarnessRunFailed as exc:
+            # C3-110: a cell that did not run is not written, so the gate reads it
+            # as `missing` — which it already fails on — instead of blessing an
+            # error envelope as a fast command.
+            print(" FAILED", file=sys.stderr)
+            print(f"    {exc}", file=sys.stderr)
+            not_measured.append(f"{name}__{cmd or 'ask'}__{mode}: {exc}")
             continue
         fname = f"{name}__{cmd or 'ask'}__{mode}.json"
         (out_dir / fname).write_text(json.dumps(cell, indent=2) + "\n", encoding="utf-8")
@@ -276,13 +321,20 @@ def main() -> int:
         print(f" p50={w['p50']}ms p95={w['p95']}ms{_gate_text} -> {fname}")
 
     print(f"done. artifacts in {out_dir}")
+    if not_measured:
+        # Written before the gate section: a cell that was not measured is the
+        # failure the gate exists to notice, and it must not be reported as a
+        # green run with a smaller population (C3-110).
+        print("cells not measured:", file=sys.stderr)
+        for line in not_measured:
+            print(f"  {line}", file=sys.stderr)
     if failures:
         print("perf regression gate failed:", file=sys.stderr)
         for fname, gate in failures:
             detail = gate.get("failed_metrics") or gate.get("reasons")
             print(f"  {fname}: {gate.get('status')} {detail}", file=sys.stderr)
         return 1
-    return 0
+    return 1 if not_measured else 0
 
 
 if __name__ == "__main__":

sourcecode-5.2.0/scripts/sync_gate_anchors.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Regenerate `sourcecode.gate_anchors` from the committed gate baseline (C3-109).
+
+The field anchors in `cache_model` are the **field's** measurements, taken on a
+private repository and a Windows machine. This repository can never refresh
+them, which is why B17 reopened one release after it closed: the mechanism that
+labels an anchor with its build works, and nothing can re-measure the number it
+labels.
+
+What this repository *can* measure every release is the gate — `perf-gate.yml`
+runs a declared command population on a 2 985-file repository under a declared
+host class, and commits the cells. This script copies those cells into the
+package, so a build can publish an in-house figure for **itself** beside a field
+anchor that belongs to an older one.
+
+One authority: the baseline JSON. The module is a derived artifact and
+`tests/test_gate_anchor_currency.py` fails when the two disagree, so a refreshed
+baseline that never reached the package is a red suite rather than a silent
+lie — which is the failure mode the whole row is about.
+
+Usage:
+    python3 scripts/sync_gate_anchors.py            # rewrite the module
+    python3 scripts/sync_gate_anchors.py --check    # exit 1 if it is out of date
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+BASELINE_DIR = REPO_ROOT / "docs" / "perf" / "baselines" / "gate-latest"
+MODULE_PATH = REPO_ROOT / "src" / "sourcecode" / "gate_anchors.py"
+
+_HEADER = '''"""gate_anchors.py — what the release gate measured, on the build that ran it.
+
+**Generated by `scripts/sync_gate_anchors.py` from `docs/perf/baselines/gate-latest/`.
+Do not edit by hand.** The baseline is the authority; this module is how a build
+carries it.
+
+C3-109. `cache_model`'s field anchors are the field's own measurements, on their
+repository and their machine — the reason they are trustworthy is the reason they
+cannot be refreshed here, and B17 reopened one release after closing because a
+refreshed anchor expires the moment the next release ships. This is the figure
+this project *can* re-measure every release: the gate's own population on a
+2 985-file repository, under a declared host class, with the build that produced
+it recorded beside it.
+
+It does not replace a field anchor and never overrides one. It is the second
+figure a reader gets — one measured at field scale on another build, one measured
+on this build on a repository we control — and the pair is honest in a way
+neither is alone.
+"""
+from __future__ import annotations
+
+'''
+
+
+def _cells() -> "dict[str, dict]":
+    out: "dict[str, dict]" = {}
+    for path in sorted(BASELINE_DIR.glob("*.json")):
+        cell = json.loads(path.read_text(encoding="utf-8"))
+        command = cell.get("command") or "ask"
+        out[command] = {
+            "seconds": round(float(cell["wall_ms"]["p50"]) / 1000.0, 2),
+            "mode": cell.get("mode", "unknown"),
+            "runs": int(cell.get("runs", 0) or 0),
+        }
+    return out
+
+
+def _meta() -> dict:
+    first = next(iter(sorted(BASELINE_DIR.glob("*.json"))), None)
+    if first is None:
+        return {}
+    cell = json.loads(first.read_text(encoding="utf-8"))
+    return {
+        "version": cell.get("tool_version", ""),
+        "captured_at": cell.get("captured_at", ""),
+        "repository": (cell.get("repo") or {}).get("name", ""),
+        "java_files": int((cell.get("repo") or {}).get("files", 0) or 0),
+        "host_class": (cell.get("env") or {}).get("host_id", "") or "github-ubuntu-latest",
+    }
+
+
+def render() -> str:
+    meta = _meta()
+    cells = _cells()
+    lines = [_HEADER]
+    lines.append("#: The build the gate cells below were captured on.\n")
+    lines.append(f'GATE_MEASURED_VERSION = {meta.get("version", "")!r}\n')
+    lines.append("#: When, so a reader can tell a stale capture from a missing one.\n")
+    lines.append(f'GATE_CAPTURED_AT = {meta.get("captured_at", "")!r}\n')
+    lines.append("#: The repository the gate measures, and its size axis.\n")
+    lines.append(f'GATE_REPOSITORY = {meta.get("repository", "")!r}\n')
+    lines.append(f'GATE_JAVA_FILES = {meta.get("java_files", 0)!r}\n')
+    lines.append(
+        "#: The host class the runs are comparable within. Cross-machine numbers\n"
+        "#: are recorded, never diffed (ADR-0006).\n"
+    )
+    lines.append(f'GATE_HOST_CLASS = {meta.get("host_class", "")!r}\n')
+    lines.append(
+        "\n#: command → measured wall time (p50 seconds), the cache mode it was\n"
+        "#: taken in, and how many runs the median is over.\n"
+    )
+    lines.append("GATE_ANCHORS: \"dict[str, dict]\" = {\n")
+    for command, cell in cells.items():
+        lines.append(
+            f"    {command!r}: {{\"seconds\": {cell['seconds']!r}, "
+            f"\"mode\": {cell['mode']!r}, \"runs\": {cell['runs']!r}}},\n"
+        )
+    lines.append("}\n")
+    return "".join(lines)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--check", action="store_true",
+                    help="Do not write; exit 1 when the module is out of date.")
+    args = ap.parse_args()
+
+    if not BASELINE_DIR.exists():
+        print(f"no baseline directory at {BASELINE_DIR}", file=sys.stderr)
+        return 1
+    rendered = render()
+    current = MODULE_PATH.read_text(encoding="utf-8") if MODULE_PATH.exists() else ""
+    if args.check:
+        if current != rendered:
+            print(
+                "sourcecode/gate_anchors.py is out of date with "
+                "docs/perf/baselines/gate-latest — run scripts/sync_gate_anchors.py",
+                file=sys.stderr,
+            )
+            return 1
+        print("gate anchors are in sync")
+        return 0
+    MODULE_PATH.write_text(rendered, encoding="utf-8")
+    print(f"wrote {MODULE_PATH.relative_to(REPO_ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{sourcecode-5.0.1 → sourcecode-5.2.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__ = "5.0.1"
+__version__ = "5.2.0"