sourcecode 5.1.0__tar.gz → 5.2.0__tar.gz

{sourcecode-5.1.0 → 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 * * *"
@@ -85,10 +92,15 @@ jobs:
             --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.1.0 → sourcecode-5.2.0}/CHANGELOG.md

@@ -2,6 +2,78 @@
 
 ## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.1.0
+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.1.0-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.1.0 — 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.1.0 → 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.1.0-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.1.0 — 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.1.0 → sourcecode-5.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "5.1.0"
+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.1.0 → sourcecode-5.2.0}/scripts/perf_gate.py

@@ -114,6 +114,11 @@ def _print_config() -> int:
         "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
         ],
@@ -139,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",
@@ -173,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:
@@ -191,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.1.0 → 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.1.0 → 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.1.0"
+__version__ = "5.2.0"

{sourcecode-5.1.0 → sourcecode-5.2.0}/src/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).