sourcecode 4.10.6__tar.gz → 4.10.7__tar.gz

{sourcecode-4.10.6 → sourcecode-4.10.7}/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 ## [Unreleased]
 
+## [4.10.7] — 2026-08-07
+
+**Tier D, and with it the M13 bug queue.** Five ledger rows close (C4-17 · C4-18 ·
+C4-19 · C4-20 · C4-21), one commit each, all of them discoverability: none was
+publishing a false claim, and together they are the ergonomics score two field
+evaluations put at 5/10. What remains of the queue is a *measurement*, not a fix —
+the C3-53 re-run on Windows under an agent harness, which is written the same way
+in the ledger and in the 4.10.6 entry below.
+
+⚠ **Three behaviour changes to read before upgrading a pipeline:**
+
+- **`ask cache status --json` renames `cores` to `cached_cores`.** It always
+  counted cached core entries; `cores` is what a captured baseline calls the
+  machine's CPU count (C4-18).
+- **`--output/-o` is now accepted after every command that publishes `--copy`**,
+  including eleven that refused it. On those the answer goes to the file and
+  stdout carries one `Written to <path>` line (C4-17).
+- **`--detach` accepts every repository-wide and deep command**, not the six that
+  happened to be listed in a hand-kept table. `posture`, `modernize`, `repo-ir`
+  and `verify-edit` — four of the commands the field could not run in a session —
+  could not be detached before this release (C4-19).
+
+### Fixed
+
+- **`ask --help` orders its front page by what will run on the repository being
+  read** (C4-19). *Start here* was, on the field repository, exactly the set of
+  commands that could not run there — four of five unrunnable in one evaluation,
+  three of five killing the session in the next. The help now measures the scope
+  (a capped tree walk plus two stat calls, paid only when help is what was asked
+  for) and groups the entries into **Runs now**, **Warm the cache first** and
+  **Too big for this session — `--output <file> --detach`**. What it deliberately
+  does not do is project a duration: `spring-audit` is 8.8 s on the 2 000-file
+  reference and was measured at 408 s on 3 342 files, so a scaled estimate would
+  be a confident falsehood; the class and the measured anchors are published
+  instead, and a command measured fast at field size (`endpoints`, 4.2 s) stays
+  on the fast list whatever its class. `--detach` accepts every repository-wide
+  and deep command now, not the six that happened to be in a hand-kept table:
+  `posture`, `modernize`, `repo-ir` and `verify-edit` were on the field's blocked
+  list and could not be detached.
+- **A remedy is checked against the repository it is printed on** (C4-20).
+  `plan` pointed an unresolved symbol at `ask repo-ir`, and `onboard` named
+  `ask posture --profile <set>` as the authority — both correct, and neither
+  finished in an interactive session on the repository whose answer named them.
+  Every remedy block (`posture`, `data-exposure`, `verify`, the security-surface
+  limitation, the unresolved-target message) now carries `how_to_run_here` when
+  there is something to say: run it detached, or warm the cache first. Nothing is
+  added where the command runs in the foreground, and nothing is guessed where
+  the scope is unknown.
+- **`--output/-o` works after every command that produces an answer** (C4-17).
+  It was a per-command decision, and the decisions disagreed: `endpoints`,
+  `validation` and `data-exposure` accepted it after the command, `baseline
+  capture` refused it — while its own siblings `baseline diff` and `baseline
+  trend` accepted it — and the refusal's hint blamed the placement rather than
+  the gap. The rule is now one line with its population taken from the CLI
+  registry: **a command that publishes `--copy` publishes `--output`**. Eleven
+  commands gained it (`version`, `baseline capture`, `cache status/warm/model/
+  freshness/context-stats`, `auth status`, `mcp status`, `mcp list-tools`,
+  `telemetry status`); on those the answer goes to the file and stdout carries
+  only `Written to <path>`. The hint for a genuinely global flag typed after a
+  subcommand was corrected with it: it said *"it goes before the command"*, which
+  is a placement that does nothing, since the root analysis is skipped as soon as
+  a subcommand is invoked.
+- **`ask config` lists the repository's own declaration** (C4-21). `data-exposure`
+  answers `answered: false` until `sourcecode.config.json` declares which types
+  and fields are sensitive — the right refusal, since a label is a judgement
+  about a domain and is never inferred — but nothing afterwards said whether the
+  file had been picked up, so the last step of the cold start was a guess.
+  `ask config [path]` now resolves that file and reports its path, the labels
+  read from it, the custom security annotations, and any declaration that could
+  not be used; when it is absent, the path it looked at and the answer that
+  absence produces. The `data-exposure` refusal points at it (`declare.confirm`).
+- **`cache status` no longer calls a cache count `Cores:`** (C4-18). The line
+  counted `core-*.json.gz` entries under the field name a captured baseline uses
+  for the machine's CPU count (`env: {cores: 20}` on the same machine, same
+  scope, minutes apart), and it sat beside `Views: 0 / CAS blobs: 0`, so
+  `Cores: 0` read as *the cache is empty* rather than *no core entries yet*. The
+  text line is `Cached cores: N entries` and the JSON key is `cached_cores`.
+  **Behaviour change for consumers of `ask cache status --json`: the `cores` key
+  is gone, replaced by `cached_cores`** — one fact, one name.
+
 ## [4.10.6] — 2026-08-07
 
 The M13 sanitation queue, tiers A through C plus the claims tier: **eighteen ledger

{sourcecode-4.10.6 → sourcecode-4.10.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.10.6
+Version: 4.10.7
 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.10.6-blue)
+![Version](https://img.shields.io/badge/version-4.10.7-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`**
@@ -106,7 +106,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.10.6 — and, on a build that has aged,
+ask version                    # ask 4.10.7 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -467,6 +467,9 @@ Full breakdown: [docs/PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md).
 
 ```bash
 ask config              # version, config file path, telemetry status
+ask config /repo        # + the repository's own sourcecode.config.json:
+                        #   data labels, custom security annotations,
+                        #   and any declaration that could not be used
 ask telemetry enable    # anonymous telemetry is OFF by default (opt-in)
 ```
 

{sourcecode-4.10.6 → sourcecode-4.10.7}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.10.6-blue)
+![Version](https://img.shields.io/badge/version-4.10.7-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`**
@@ -68,7 +68,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.10.6 — and, on a build that has aged,
+ask version                    # ask 4.10.7 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -429,6 +429,9 @@ Full breakdown: [docs/PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md).
 
 ```bash
 ask config              # version, config file path, telemetry status
+ask config /repo        # + the repository's own sourcecode.config.json:
+                        #   data labels, custom security annotations,
+                        #   and any declaration that could not be used
 ask telemetry enable    # anonymous telemetry is OFF by default (opt-in)
 ```
 

{sourcecode-4.10.6 → sourcecode-4.10.7}/pyproject.toml

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

{sourcecode-4.10.6 → sourcecode-4.10.7}/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.10.6"
+__version__ = "4.10.7"

{sourcecode-4.10.6 → sourcecode-4.10.7}/src/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-4.10.6 → sourcecode-4.10.7}/src/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,78 +171,78 @@ 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 "
@@ -204,7 +250,7 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "diff-dependent and never cached.",
                  "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)"),
+                 "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: "
@@ -212,33 +258,33 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "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"),
+                 "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 = {
@@ -274,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,
@@ -282,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-4.10.6 → sourcecode-4.10.7}/src/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-4.10.6 → sourcecode-4.10.7}/src/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).