sourcecode 4.10.5__py3-none-any.whl → 4.10.7__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__ = "4.10.5"
+__version__ = "4.10.7"

sourcecode/architectural_baseline.py

@@ -136,6 +136,19 @@ def _fan_in_from_stored(value: Any) -> dict[str, int]:
     return {}
 
 
+def _comparability_env() -> dict:
+    """The environment fields a delta actually depends on (C3-68).
+
+    A baseline is comparable to another when the platform and the tool agree;
+    the CPU model, the core count and a hash of the hostname change none of
+    that. `--record-env` restores the full set for someone benchmarking runs
+    against each other on one machine.
+    """
+    import sys as _sys
+
+    return {"os": _sys.platform, "tool_version": TOOL_VERSION, "recorded": "comparability_only"}
+
+
 def build_baseline(
     cir: "CanonicalRepositoryIR",
     *,
@@ -145,6 +158,7 @@ def build_baseline(
     captured_at: str | None = None,
     env: dict | None = None,
     tool_version: str | None = None,
+    record_env: bool = False,
 ) -> dict:
     """Freeze a CIR's measured architectural metrics into a baseline artifact.
 
@@ -168,6 +182,21 @@ def build_baseline(
             "files": m.file_count,
             "symbols": m.symbol_count,
             "endpoints": m.endpoint_count,
+            # C1-37: this artefact's declared purpose is to be a replayable
+            # fingerprint, and it disagreed with itself — `totals.endpoints`
+            # 3 574 against `len(endpoint_surface)` 3 538 on the field
+            # repository. Neither figure was wrong: `endpoints` counts handler
+            # mappings and `endpoint_surface` is the set of distinct
+            # (METHOD, path) contract pairs, so 36 routes are declared by more
+            # than one handler. Two facts, two names, and the invariant the
+            # battery can actually hold.
+            "endpoint_contract_pairs": len(m.endpoints),
+            "endpoints_unit": (
+                "handler mappings declared in the repository; "
+                "`endpoint_contract_pairs` counts the distinct (METHOD, path) "
+                "pairs those mappings expose, which is what `endpoint_surface` "
+                "lists and what a diff compares"
+            ),
             "dependency_edges": m.dependency_edge_count,
             "import_cycles": len(m.cycles),
         },
@@ -175,7 +204,16 @@ def build_baseline(
         "endpoint_surface": endpoints,
         "fan_in": _fan_in_to_list(m.fan_in),
         "import_cycles": cycles,
-        "env": env if env is not None else collect_env(),
+        # C3-68: this artefact is written inside the work tree, so what it
+        # records is what a `git add -A` publishes. `hostname_hash`, `cpu` and
+        # `cores` describe the developer's machine and affect nothing a delta
+        # compares — from a tool whose own `ask config` says telemetry is off.
+        # The default is now the two fields that DO decide comparability; the
+        # rest is opt-in per capture.
+        "env": (
+            env if env is not None
+            else (collect_env() if record_env else _comparability_env())
+        ),
         "provenance": (
             "architectural_baseline (D5): a measured structural fingerprint of one "
             "CIR, persisted per ref. Metric content is a pure function of the repo "
@@ -319,9 +357,50 @@ def _baseline_filename(baseline: dict) -> str:
     return f"{safe}.json"
 
 
+#: What `.ask/` gets the moment it is created, and why.
+#:
+#: C3-68: `baseline capture` writes into the work tree and nothing protected it.
+#: The field verified `grep -nE "^\.ask|sourcecode" .gitignore` → no matches, so
+#: a `git add -A` commits the artefact — which carries a machine fingerprint and
+#: a 14 587-entry structural inventory of the code. A self-confined
+#: `.ask/.gitignore` is the honest form: it never touches the user's own
+#: `.gitignore`, and it stops applying the moment they delete the directory.
+_ASK_DIR_GITIGNORE = (
+    "# Written by `ask` the first time it created this directory.\n"
+    "# These are local analysis artefacts: a structural inventory of your code\n"
+    "# and, if you asked for it, the machine that measured it. Nothing here\n"
+    "# belongs in a commit. Delete this file to version them deliberately.\n"
+    "*\n"
+)
+
+
+def protect_ask_dir(out_dir: Path) -> None:
+    """Give a freshly created `.ask/` its own `.gitignore` (C3-68).
+
+    Best-effort and never overwriting: a user who edited it decided something,
+    and a tool that re-imposes its default on every run is worse than one that
+    never wrote it.
+    """
+    try:
+        ask_dir = Path(out_dir)
+        while ask_dir.name and ask_dir.name != ".ask":
+            if ask_dir.parent == ask_dir:
+                return
+            ask_dir = ask_dir.parent
+        if ask_dir.name != ".ask":
+            return
+        marker = ask_dir / ".gitignore"
+        if not marker.exists():
+            ask_dir.mkdir(parents=True, exist_ok=True)
+            marker.write_text(_ASK_DIR_GITIGNORE, encoding="utf-8")
+    except OSError:
+        return
+
+
 def write_baseline(baseline: dict, out_dir: Path) -> Path:
     """Write `baseline` as deterministic JSON under `out_dir`; return the file path."""
     out_dir.mkdir(parents=True, exist_ok=True)
+    protect_ask_dir(out_dir)
     path = out_dir / _baseline_filename(baseline)
     path.write_text(
         json.dumps(baseline, sort_keys=True, indent=2) + "\n", encoding="utf-8"

sourcecode/cache.py

@@ -336,10 +336,15 @@ def cache_dir(repo_root: Path) -> Path:
 def status(repo_root: Path) -> dict[str, Any]:
     """Return a stats dict describing the current cache state for *repo_root*.
 
-    Keys: ``cache_dir``, ``cores``, ``views``, ``cas_blobs``,
+    Keys: ``cache_dir``, ``cached_cores``, ``views``, ``cas_blobs``,
     ``total_size_bytes``, ``total_size_mb``, ``ris_exists``, ``ris_git_head``,
     ``ris_last_updated_at``, ``ris_is_stale``, ``current_git_head``.
 
+    ``cached_cores`` counts ``core-*.json.gz`` entries in this cache. It was
+    named ``cores`` until 4.10.7, which is the field name a captured baseline
+    uses for the machine's CPU count (``env.cores``) — two different facts under
+    one name, on the same machine, minutes apart (C4-18).
+
     Note: ``snapshots`` is a legacy v1 field — always 0 in v2 (kept for
     backward compatibility; v2 writes ``core-*`` and ``view-*`` files only).
     """
@@ -377,7 +382,7 @@ def status(repo_root: Path) -> dict[str, Any]:
     if not cache_d.exists():
         return {
             "cache_dir": str(cache_d),
-            "cores": 0, "snapshots": 0, "views": 0, "cas_blobs": 0,
+            "cached_cores": 0, "snapshots": 0, "views": 0, "cas_blobs": 0,
             "total_size_bytes": 0, "total_size_mb": 0.0,
             "current_git_head": current_head,
             "stores": _store_breakdown(repo_root, 0),
@@ -391,7 +396,7 @@ def status(repo_root: Path) -> dict[str, Any]:
     total_bytes = sum(f.stat().st_size for f in all_files if f.exists())
     return {
         "cache_dir": str(cache_d),
-        "cores": len(cores),
+        "cached_cores": len(cores),
         "snapshots": len(snapshots),
         "views": len(views),
         "cas_blobs": len(cas_blobs),

sourcecode/cache_model.py

@@ -27,6 +27,7 @@ warm buys `endpoints` and `migrate-check` **nothing**, and on a small diff it ma
 from __future__ import annotations
 
 from dataclasses import dataclass
+from typing import Optional
 
 
 @dataclass(frozen=True)
@@ -54,6 +55,32 @@ class CommandCache:
     #: then the command — because measuring them in sequence lets one command warm the
     #: next and reports a benefit the user will not get.
     measured: str = ""
+    #: What the command has to touch to answer, in the vocabulary the budget
+    #: floors already use (C4-19). This is the axis that decides how a command can
+    #: be *run* — in the foreground, after a warm, or detached — as opposed to how
+    #: much a warm saves it, which is `warm` above:
+    #:   ``core``      — a symbol, one file, a diff, or stored metadata
+    #:   ``repo-wide`` — one pass over the repository
+    #:   ``deep``      — a composition of several repo-wide passes
+    #:   ``none``      — not an analysis of a repository at all
+    #: It lives here because this is where the measurements live; `cli`'s budget
+    #: floors and `detach.detachable_commands()` read it rather than keeping a
+    #: second table, which is how `posture`, `modernize` and `repo-ir` — three of
+    #: the commands the field could not run — ended up undetachable.
+    analysis_class: str = "repo-wide"
+    #: The same figures `measured` describes, in machine form: seconds on the
+    #: reference repository, cold and after `cache warm`. ``None`` where the row
+    #: was never timed — an axis that could not be measured is never a number.
+    cold_seconds: "Optional[float]" = None
+    warm_seconds: "Optional[float]" = None
+    #: The other measured point: this command on the field repository
+    #: (3 342 Java files, Windows 11 / PowerShell 5.1 / pipx, cold), from field
+    #: evaluations #13 and #14. Seconds where a run finished; `field_blocked`
+    #: where it did not — the harness promoted the process and the session died,
+    #: which is a measurement of a different kind and is never written as a
+    #: duration. Rows with neither were not attempted there.
+    field_seconds: "Optional[float]" = None
+    field_blocked: bool = False
 
 
 #: Where every `measured` figure comes from.
@@ -61,6 +88,25 @@ REFERENCE_REPOSITORY = (
     "BroadleafCommerce (2 000+ Java files, dirty tree), warm machine, 3.2.2"
 )
 
+#: The size of that repository, so a reader on a different one knows what the
+#: figures are relative to.
+REFERENCE_JAVA_FILES = 2000
+
+#: The other end of the measured range, and the reason this module publishes a
+#: *class* rather than a projected duration (C4-19). Field evaluation #13, on
+#: Windows 11 / PowerShell 5.1 / pipx / Python 3.10: `spring-audit` on a
+#: 3 342-file repository ran **408 s** — 46× the 8.8 s the same command takes on
+#: the 2 000-file reference. Cost does not scale with file count in any way this
+#: product has measured, so a projected "~15 s on your repository" would be a
+#: confident falsehood of exactly the kind the ledger exists to prevent. What can
+#: be said honestly is the class, the two measured anchors, and how to run it.
+FIELD_ANCHOR = (
+    "field evaluation #13: spring-audit on 3 342 Java files took 408 s "
+    "(Windows, pipx, cold) against 8.8 s on the 2 000-file reference"
+)
+FIELD_ANCHOR_JAVA_FILES = 3342
+FIELD_ANCHOR_SECONDS = 408.0
+
 
 #: Every layer keys on `cache.worktree_signature` — the exact tree state (C1-9).
 #: One sentence covers all of them: **any change to the analysed files invalidates,
@@ -125,113 +171,120 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "`--env-map`, `--depth N` and `--exclude` change the *analysis*, so they miss the "
                  "warmed core and rescan — this is the 171 s the field measured after a 103 s warm.",
                  "--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)"),
+                 "--agent --full --env-map --depth 20 34.7 s → 33.9 s (no gain)", analysis_class="repo-wide", cold_seconds=13.3, warm_seconds=0.3, field_seconds=115.0),
     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"),
+                 "10.1 s → 1.6 s", analysis_class="repo-wide", cold_seconds=10.1, warm_seconds=1.6, field_blocked=True),
     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 "
                  "for the whole composition, and the reachability query is cached per symbol "
                  "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"),
+                 "`spring-audit` + `impact-chain` costs listed here, not by new analysis", analysis_class="deep"),
     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 "
                  "repository side, so what it buys is what it buys `risk`.",
                  "not measured on the battery yet — bounded by the `risk` composition, plus "
-                 "reading one JSON file"),
+                 "reading one JSON file", analysis_class="deep"),
     CommandCache("audit-report", ("cir", "parse"), "shared", False,
                  "Packages `risk` and `posture` evidence. A warm helps the repository side; "
                  "`--from-risk risk.json` skips risk recomputation entirely and only builds "
                  "the posture/report projection.",
                  "not measured on the battery yet — bounded by `risk` + `posture`, or by "
-                 "`posture` when `--from-risk` is supplied"),
+                 "`posture` when `--from-risk` is supplied", analysis_class="deep"),
     CommandCache("migrate-recipe", ("parse",), "shared", False,
                  "Runs the same scan as `migrate-check` and projects its findings into an "
                  "OpenRewrite recipe, so it buys exactly what a warm buys `migrate-check`: "
                  "the parse, not the rule pass.",
                  "not measured on the battery yet — bounded by `migrate-check` on the same "
-                 "repository (openmrs-core ~2 s)"),
+                 "repository (openmrs-core ~2 s)", analysis_class="repo-wide"),
     CommandCache("data-exposure", ("cir", "parse"), "shared", False,
                  "Walks the same call reach as `impact-chain` once per declared type and "
                  "reads the endpoint security surface, both over the shared CIR a warm "
                  "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"),
+                 "declared seed type over a CIR the warm already paid for", analysis_class="repo-wide"),
     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)"),
+                 "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=4.2),
     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"),
+                 "8.8 s → 3.7 s", analysis_class="repo-wide", cold_seconds=8.8, warm_seconds=3.7, field_seconds=408.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"),
+                 "4.8 s → 4.8 s", analysis_class="repo-wide", cold_seconds=4.8, warm_seconds=4.8, field_blocked=True),
     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"),
-    CommandCache("impact", ("parse",), "shared", False, "", "4.9 s → 2.8 s"),
+                 "9.9 s → 1.7 s", analysis_class="core", cold_seconds=9.9, warm_seconds=1.7),
+    CommandCache("impact", ("parse",), "shared", False, "", "4.9 s → 2.8 s", analysis_class="core", cold_seconds=4.9, warm_seconds=2.8),
     CommandCache("pr-impact", ("parse",), "shared", False,
-                 "Diff-dependent: the answer itself is never stored."),
-    CommandCache("verify", (), "none", False, "Runs the contracts against a fresh reading."),
+                 "Diff-dependent: the answer itself is never stored.", analysis_class="core"),
+    CommandCache("verify", (), "none", False, "Runs the contracts against a fresh reading.", analysis_class="core"),
     CommandCache("verify-edit", ("parse",), "shared", True,
                  "Built for the edit loop: the parse cache is what keeps an unchanged file out of the "
                  "next run. Its own second run is faster again.",
-                 "14.6 s → 9.6 s → 5.6 s on repeat"),
+                 "14.6 s → 9.6 s → 5.6 s on repeat", analysis_class="repo-wide", cold_seconds=14.6, warm_seconds=9.6, field_blocked=True),
     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)"),
-    CommandCache("plan", ("parse",), "shared", False, "", "9.3 s → 3.8 s"),
-    CommandCache("compare", ("parse",), "shared", False, ""),
-    CommandCache("delta", (), "none", False, "Analyses two states — two checkouts, or two refs materialised into temporary trees; neither is the tree the cache describes."),
-    CommandCache("contract-diff", (), "none", False, "Analyses two states (checkouts or refs); neither is the tree the cache describes."),
+                 "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("fix-bug", ("task",), "none", True,
-                 "Shorthand for `prepare-context fix-bug`; caches its own answer, which a warm never runs."),
-    CommandCache("rename-class", (), "none", False, ""),
+                 "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"),
     CommandCache("prepare-context", ("task", "ris", "cir", "parse"), "answer", True,
                  "Per task: `onboard` and `explain` are served from the RIS a warm rebuilds; "
                  "`refactor`, `fix-bug` and `generate-tests` cache their own answer, but a warm does "
                  "not run them, so their first call pays full price; `delta` and `review-pr` are "
                  "diff-dependent and never cached.",
-                 "onboard 6.5 s → 0.3 s · refactor 7.7 s → 7.7 s (0.3 s on repeat) · "
-                 "generate-tests 12.4 s → 11.0 s (0.3 s on repeat)"),
-    CommandCache("onboard", ("task", "ris"), "answer", True, "Shorthand for `prepare-context onboard`.",
-                 "6.5 s → 0.3 s"),
+                 "onboard 6.5 s → 0.3 s with a warm — but a second run with NO warm recomputes "
+                 "(10.2 s → 9.4 s at 5 486 files; C1-40) · refactor 7.7 s → 7.7 s (0.3 s on "
+                 "repeat) · generate-tests 12.4 s → 11.0 s (0.3 s on repeat)", analysis_class="repo-wide", cold_seconds=6.5, warm_seconds=0.3),
+    CommandCache("onboard", ("task", "ris"), "answer", False,
+                 "Shorthand for `prepare-context onboard`. A warm stores its answer; the command "
+                 "does NOT store its own, so a second run without a warm pays full price. C1-40: "
+                 "the field read `repeat cached` here, ran it twice with no warm, and measured "
+                 "56 s then 23,5 s — this row said it would be a hit.",
+                 "with a warm: 6.5 s → 0.3 s (2 000 files) · 10.2 s → 0.7 s (5 486 files). "
+                 "WITHOUT a warm, a second identical run: 10.2 s → 9.4 s (5 486 files) — "
+                 "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"),
-    CommandCache("export", ("parse",), "shared", False, "", "8.8 s → 3.7 s"),
-    CommandCache("repo-ir", ("parse",), "shared", False, "", "5.1 s → 2.9 s"),
-    CommandCache("validation", ("parse",), "shared", False, "", "11.6 s → 6.4 s"),
-    CommandCache("modernize", ("parse",), "shared", False, "", "5.2 s → 3.0 s"),
-    CommandCache("chunk-file", (), "none", False, "Reads one file; nothing to cache."),
+                 "9.8 s → 1.6 s", analysis_class="core", cold_seconds=9.8, warm_seconds=1.6),
+    CommandCache("export", ("parse",), "shared", False, "", "8.8 s → 3.7 s", analysis_class="repo-wide", cold_seconds=8.8, warm_seconds=3.7),
+    CommandCache("repo-ir", ("parse",), "shared", False, "", "5.1 s → 2.9 s", analysis_class="repo-wide", cold_seconds=5.1, warm_seconds=2.9, field_blocked=True),
+    CommandCache("validation", ("parse",), "shared", False, "", "11.6 s → 6.4 s", analysis_class="repo-wide", cold_seconds=11.6, warm_seconds=6.4),
+    CommandCache("modernize", ("parse",), "shared", False, "", "5.2 s → 3.0 s", analysis_class="repo-wide", cold_seconds=5.2, warm_seconds=3.0, field_blocked=True),
+    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"),
-    CommandCache("trend", (), "none", False, "Reads stored baseline artifacts from disk; analyses no source, so no cache layer applies. Same command as `baseline trend`."),
+                 "0.2 s either way", analysis_class="core", cold_seconds=0.2, warm_seconds=0.2),
+    CommandCache("trend", (), "none", False, "Reads stored baseline artifacts from disk; analyses no source, so no cache layer applies. Same command as `baseline trend`.", analysis_class="none"),
     CommandCache("baseline", ("parse",), "shared", False, "`capture`/`diff`/`trend` over architectural metrics.",
-                 "capture 8.7 s → 3.6 s"),
+                 "capture 8.7 s → 3.6 s", analysis_class="repo-wide", cold_seconds=8.7, warm_seconds=3.6, field_seconds=11.0),
     CommandCache("retrieve", ("cir", "parse"), "shared", False,
-                 "Every query builds or reuses the shared CIR a warm builds."),
-    CommandCache("archetype", ("parse",), "shared", False, "", "9.3 s → 5.6 s"),
-    CommandCache("activate", (), "none", False, "Not an analysis."),
-    CommandCache("auth", (), "none", False, "Not an analysis."),
-    CommandCache("cache", (), "none", False, "Operates on the caches themselves."),
-    CommandCache("config", (), "none", False, "Not an analysis."),
+                 "Every query builds or reuses the shared CIR a warm builds.", analysis_class="core"),
+    CommandCache("archetype", ("parse",), "shared", False, "", "9.3 s → 5.6 s", analysis_class="repo-wide", cold_seconds=9.3, warm_seconds=5.6),
+    CommandCache("activate", (), "none", False, "Not an analysis.", analysis_class="none"),
+    CommandCache("auth", (), "none", False, "Not an analysis.", analysis_class="none"),
+    CommandCache("cache", (), "none", False, "Operates on the caches themselves.", analysis_class="none"),
+    CommandCache("config", (), "none", False, "Not an analysis.", analysis_class="none"),
     CommandCache("mcp", ("snapshot", "ris", "cir", "parse"), "shared", True,
-                 "Serves the same commands over MCP, with the same layers."),
-    CommandCache("schema", (), "none", False, "Prints registries; reads no repository."),
-    CommandCache("telemetry", (), "none", False, "Not an analysis."),
-    CommandCache("version", (), "none", False, "Not an analysis."),
+                 "Serves the same commands over MCP, with the same layers.", analysis_class="none"),
+    CommandCache("schema", (), "none", False, "Prints registries; reads no repository.", analysis_class="none"),
+    CommandCache("telemetry", (), "none", False, "Not an analysis.", analysis_class="none"),
+    CommandCache("version", (), "none", False, "Not an analysis.", analysis_class="none"),
 )
 
 _WARM_LABEL = {
@@ -267,6 +320,11 @@ def as_dict() -> dict:
             for lyr in LAYERS
         ],
         "reference_repository": REFERENCE_REPOSITORY,
+        "reference_java_files": REFERENCE_JAVA_FILES,
+        # 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).
+        "field_anchor": FIELD_ANCHOR,
         "commands": [
             {
                 "command": cmd.command,
@@ -275,6 +333,12 @@ def as_dict() -> dict:
                 "repeat_run_is_cached": cmd.repeat,
                 "note": cmd.note,
                 "measured": cmd.measured or None,
+                "analysis_class": cmd.analysis_class,
+                "reference_seconds": (
+                    None
+                    if cmd.cold_seconds is None
+                    else {"cold": cmd.cold_seconds, "warm": cmd.warm_seconds}
+                ),
             }
             for cmd in COMMANDS
         ],

sourcecode/canonical_ir.py

@@ -636,6 +636,7 @@ def project_blast_radius(
     target: str,
     *,
     max_depth: int = 4,
+    root=None,
 ) -> dict:
     """Project blast radius from CIR.
 
@@ -645,7 +646,7 @@ def project_blast_radius(
     All endpoints in the result come from cir.endpoints (via route_surface).
     No independent endpoint reconstruction.
     """
-    return _compute_blast_radius(cir._raw_ir, target, max_depth=max_depth)
+    return _compute_blast_radius(cir._raw_ir, target, max_depth=max_depth, root=root)
 
 
 # ---------------------------------------------------------------------------

sourcecode/change_plan.py

@@ -81,10 +81,15 @@ def _node_meta(cir: "CanonicalRepositoryIR") -> dict[str, dict]:
 
 
 def build_change_plan(
-    cir: "CanonicalRepositoryIR", target: str, *, max_depth: int = 4
+    cir: "CanonicalRepositoryIR", target: str, *, max_depth: int = 4, root=None
 ) -> dict:
-    """Build the deterministic change plan for `target` over `cir`."""
-    blast = project_blast_radius(cir, target, max_depth=max_depth)
+    """Build the deterministic change plan for `target` over `cir`.
+
+    `root` is optional and is used for one thing: the advice attached to an
+    unresolved target names a command, and whether that command can be run on
+    this repository is a property of the repository (C4-20).
+    """
+    blast = project_blast_radius(cir, target, max_depth=max_depth, root=root)
     resolution = blast.get("resolution", "not_found")
 
     # Unresolvable target → return a plan-shaped resolution notice (never crash).
@@ -93,17 +98,31 @@ def build_change_plan(
     from sourcecode.target_admission import is_unresolved
 
     if is_unresolved(resolution) or not blast.get("matched_fqns"):
+        # C1-39: this is a well-formed `change-plan-v1`, not an error envelope,
+        # so an agent reads its fields — and every cost used to be `0`. Nothing
+        # was measured, and `0` is the answer to a different question. The
+        # product already gets this right elsewhere (`data-exposure` answers
+        # `answered: false` rather than measuring nothing and publishing a
+        # confident zero); this is the same rule, one level up.
+        _not_measured = {
+            "answered": False,
+            "reason": f"target {target!r} did not resolve — nothing was measured",
+        }
         return {
             "schema": CHANGE_PLAN_SCHEMA,
             "target": target,
             "resolution": resolution,
             "message": blast.get("message", f"Target {target!r} not found."),
             "candidates": blast.get("candidates", []),
-            "affected_components": {"count": 0, "components": []},
-            "covering_tests": {"count": 0, "tests": []},
-            "affected_endpoints": {"count": 0, "endpoints": []},
-            "rollback_surface": {"file_count": 0, "files": []},
+            "affected_components": {"count": None, "components": [], **_not_measured},
+            "covering_tests": {"count": None, "tests": [], **_not_measured},
+            "affected_endpoints": {"count": None, "endpoints": [], **_not_measured},
+            "rollback_surface": {"file_count": None, "files": [], **_not_measured},
             "review_checklist": [],
+            "how_to_read": (
+                "Every cost here is `null`, not `0`: the target did not resolve, so "
+                "nothing was measured. A zero would say the change is free."
+            ),
         }
 
     seeds = list(blast["matched_fqns"])
@@ -148,10 +167,21 @@ def build_change_plan(
         checklist.append(
             f"Re-verify the contract of {len(ep_strings)} endpoint(s) in the blast radius."
         )
+    # C1-39, second half: on a repository with no test source root at all — the
+    # field one had 0 test files for 3 337 non-test Java sources — "0 covering
+    # tests" reads as *the change is safe* when it means *there are no tests*.
+    _has_test_root = any(
+        is_test_path(str(m.get("file") or "")) for m in meta.values()
+    )
     if tests:
         checklist.append(
             f"Run {len(tests)} covering test symbol(s) that reach the change."
         )
+    elif not _has_test_root:
+        checklist.append(
+            "Covering tests were not measured: this repository has no test source "
+            "root, so `covering_tests.count` is null rather than 0."
+        )
     else:
         checklist.append(
             "No covering tests reach the change — no existing test exercises this blast radius."
@@ -178,10 +208,20 @@ def build_change_plan(
             "count": len(prod),
             "components": prod[:_LIST_CAP],
         },
-        "covering_tests": {
-            "count": len(tests),
-            "tests": tests[:_LIST_CAP],
-        },
+        "covering_tests": (
+            {
+                "count": len(tests),
+                "tests": tests[:_LIST_CAP],
+                "answered": True,
+            }
+            if _has_test_root else
+            {
+                "count": None,
+                "tests": [],
+                "answered": False,
+                "reason": "no test source root in this repository — nothing to measure",
+            }
+        ),
         "affected_endpoints": {
             "count": len(ep_strings),
             "endpoints": ep_strings[:_LIST_CAP],