sourcecode 4.10.6__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.6"
+__version__ = "4.10.7"

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,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/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).