sourcecode 4.10.6__tar.gz → 4.11.0__tar.gz

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

@@ -2,6 +2,204 @@
 
 ## [Unreleased]
 
+## [4.11.0] — 2026-08-07
+
+**The queue behind Tier D: five ledger rows, and three batteries that were red in
+the release before this one.** C3-59 · C3-56 (second half) · C3-52 · C3-60 (second
+half) · CL-15 close here, one commit each. Two of them were bigger than the row
+said, and both in the same direction — a flag that parses and does not check, a
+message that promises output nobody writes:
+
+- **`--format` was published by eleven commands that validated nothing**, so
+  `ask risk . --format bogus` answered with JSON as if the value had counted
+  (C3-59);
+- **`--detach` told the operator "progress and errors go to `log`"** and the log
+  held one line, because a detached worker has no terminal and the heartbeat
+  switched itself off exactly where it is the only way to tell work from a hang
+  (C3-52).
+
+⚠ **Behaviour changes to read before upgrading a pipeline:**
+
+- **An unsupported `--format` now exits 2** with the values that are valid, on
+  the eleven commands that used to accept anything and answer JSON. A script
+  passing a value that was never supported fails where it used to appear to work.
+- **`--format/-f` is accepted after 34 more commands**, including the 29
+  `retrieve` intents, `modernize`, `schema`, `onboard` and `fix-bug`.
+- **`ask config <path>` refuses a path that does not exist** (exit 1, the standard
+  envelope) instead of reporting "nothing is declared" about it.
+- **A detached run writes heartbeat lines into its own log** unless `--progress`
+  or `ASK_PROGRESS` says otherwise. Nothing changes for a foreground, piped or CI
+  run that does not ask.
+
+Three tests were **already red in 4.10.7** — each a battery that derives its
+population from the CLI, so C4-17's and C4-20's own changes tripped them — and
+they are fixed here. One of the three was not a test defect: it found `ask config`
+answering about a repository that does not exist.
+
+### Changed
+
+- **The `spring-audit` security section says what it is before it says what it
+  found** (CL-15). A field evaluation found the repository's critical SQL
+  injection by hand and ASK did not report it — correctly and by declaration
+  (NC-001: no dataflow) — but the section is announced as a *security surface*,
+  which invites reading it as a defect finder. The surface now states, from one
+  table rendered into both `--help` and the payload, that it reads the security
+  **configuration and exposure** (declared chain rules, open endpoints, disabled
+  controls, bypassable gates, each with file and line), that it is **not** a
+  vulnerability scanner, and where it is strongest: given a defect somebody else
+  found, `ask impact` and `ask risk` quantify what it reaches. The rule-family
+  label follows (`security surface` → `security configuration and exposure`). No
+  rule and no finding changed — this was always a naming defect.
+
+### Fixed
+
+- **`ask config <path>` refuses a repository nobody could read** instead of
+  reporting on it (C4-21 follow-up). The command gained a repository argument in
+  4.10.7 without the admission gate every other path-taking command uses, so
+  `ask config /nonexistent` answered *"Declaration: none at
+  /nonexistent/sourcecode.config.json"* with exit 0 — and *"nothing is declared
+  here"* is indistinguishable from *"nobody could look"*, which is the reading
+  ADR-0008 exists to prevent.
+
+- **`ask cache model` states which repository its figures were measured on, and
+  what that means for yours** (C3-60, second half). It published `verify-edit` as
+  *14,6 s → 9,6 s → 5,6 s* and called it *"built for the edit loop"* while the
+  same command had not answered at 495 s on the field repository — both
+  measurements, one printed. The command now measures the scope it is run in
+  (same authority as `--help` and the remedies), says whether the published
+  figures transfer to it, and gives each command a `here:` line saying how it can
+  be run on *this* repository. No figure changed and nothing is projected: an
+  unmeasurable scope gets the reference figures unqualified, as before.
+
+- **`--progress off | stderr | file:<path>` on every command that can make you
+  wait** (C3-52). The heartbeat existed and the watcher model everybody uses
+  could not see it: a supervisor reading the standard streams got nothing for
+  703 seconds unless it knew to set `ASK_PROGRESS=1` or to poll the run record —
+  knowledge that appeared in no `--help` and in no payload. The choice is now
+  published on the command being typed (62 commands, population from the
+  registry), `ASK_PROGRESS` still sets the same thing in the environment, and an
+  unrecognised value is refused with exit 2 rather than silently falling back to
+  the default. Nothing changes for a piped or CI run that does not ask.
+- **A detached run's log carries the progress its own envelope promises**
+  (C3-52). `--detach` printed *"Progress and errors go to `log`"* and the log
+  held one line, because a detached worker has no terminal and the heartbeat
+  disabled itself exactly where it is the only way to tell work from a hang. A
+  detached run now enables the heartbeat into its own log unless `--progress` or
+  `ASK_PROGRESS` says otherwise; no shell reads those bytes, so the PowerShell
+  `$?` problem (C3-66) cannot be reached from a detached run.
+
+- **The progress heartbeat carries a denominator and an ETA** (C3-56, second
+  half). `phase=auditing 3342 Java files elapsed=6.8m` said the run was alive and
+  nothing about whether it was worth waiting for; the field's only way to tell
+  work from a hang was reading the worker's CPU time. The line now reads
+  `phase=auditing 2766 Java files stage=parsing 1458/2766 files elapsed=2.0s
+  eta=1.8s eta_covers=parsing`, with the counts coming from the loops that read
+  the files rather than from the spinner. The ETA **names what it covers**
+  (nothing here knows the cost of the stages after the counted one), is withheld
+  until it can be measured, and is dropped when the phase changes rather than
+  freezing at `2766/2766`. A run with no heartbeat enabled is not asked to count.
+
+- **`-f` means `--format` on every command that publishes it, and every command
+  that answers with a payload document publishes it** (C3-59). `-f json` was
+  accepted by `endpoints` and `spring-audit` and refused by `modernize`, whose
+  error called `-f` a global flag *"as `ask -f <path>`"* — so the message taught
+  the collision it was meant to remove. The population is now the C4-17 rule one
+  level along (a payload command publishes `--format/-f`; a command that answers
+  in lines is exempt on the record in `cli.COMMANDS_WITHOUT_FORMAT`), and 34
+  commands gained the flag: `modernize`, `archetype`, `cold-start`, `schema`,
+  `onboard`, `fix-bug` and the 29 `retrieve` intents. One conversion in the emit
+  seam serves all of them, on the *stamped* document, so a YAML answer carries
+  the same `_meta` as the JSON one.
+- **An unsupported `--format` is refused instead of silently ignored** (C3-59).
+  Eleven commands published the flag and validated nothing — `ask risk .
+  --format bogus` answered with JSON as if the value had counted. Validation
+  moved into the shared option factory, keyed off the command being run, so a
+  command cannot publish the flag and skip the check;
+  `sourcecode.format_contract.FORMAT_REGISTRY` is the one authority for what
+  each command accepts, and an invalid value exits 2 with the values that are
+  valid. `rename-class` keeps `-f` for `--from` (on the record in
+  `COMMANDS_WITHOUT_FORMAT_SHORTHAND`); its long `--format` is unchanged.
+
+## [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.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.10.6
+Version: 4.11.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-4.10.6-blue)
+![Version](https://img.shields.io/badge/version-4.11.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`**
@@ -73,8 +73,10 @@ These numbers are cache-layer benchmarks, not a promise for every command. Per-s
 
 With the right command class, ASK Engine becomes **constant infrastructure** inside agent loops — call the fast/context surfaces before edits and reserve deep compositions for the points where their evidence is worth the runtime.
 
-**Large-repo controls.** Set `ASK_PROGRESS=1` to get line heartbeats in non-TTY
-supervised runs. Long repo-wide/deep runs also write durable records under
+**Large-repo controls.** Pass `--progress stderr` (or `--progress file:run.log`)
+for line heartbeats in a non-TTY supervised run — with the file being read so
+far and an ETA for the stage being measured. `ASK_PROGRESS` sets the same thing
+in the environment. Long repo-wide/deep runs also write durable records under
 `~/.sourcecode/runs/<repo-hash>/` by default, not inside the audited repository;
 set `ASK_RUNS_IN_REPO=1` only when repo-local `.ask/runs` records are intentional.
 Set `ASK_MAX_ANALYSIS_SECONDS=<seconds>` to fail before starting a repo-wide/deep
@@ -106,7 +108,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.11.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -322,7 +324,7 @@ from it.
 | `migrate-recipe` | experimental | the migration report as the OpenRewrite recipe that applies it | only recipes a finding named; the manual remainder published beside them; writes nothing without `--write`, and never a runnable command for an empty recipe list |
 | `data-exposure` | experimental | which routes can carry the data you labelled, and who reaches them | labels declared in `sourcecode.config.json` — never inferred from a name; `signature` and `call_reach` evidence published apart, field-level flow out of scope (NC-008). With nothing declared, `ask data-exposure /path/to/repo` answers `answered: false` and hands back the file, the key and an example to declare — it never reports zero exposed routes |
 | `endpoints` | core | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators). `--compact` answers the exposure census without the rows; `--servlets` lists the servlet-mounted surface as its own population; `--client-usage` says which routes the TS/JS client in this repository actually calls |
-| `spring-audit` | core | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review |
+| `spring-audit` | core | transactional anomalies + security configuration/exposure + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review |
 | `migrate-check` | core | Boot 2→3 readiness + Java LTS/licensing inventory: located blockers, per-dimension score, effort, detected Java 8/11/17/21/25 evidence and explicit licensing-review signals | `--target-jdk 25` sets the target LTS route; `--blast-radius` orders the re-test plan; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
 | `impact` / `impact-chain` | core | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
 | `pr-impact` | core | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
@@ -359,7 +361,21 @@ Honest limits worth knowing before you rely on it:
 - Architecture classification is tuned for Spring MVC layered apps; SPI/plugin models (e.g. Quarkus extensions) may be misclassified. JAX-RS subresource-locator endpoint recall is ~65%.
 - Self-invocation `@Transactional` bypass (same-class call skipping the proxy) is not detected.
 
-### What the security surface does not answer
+### What the security section is, and what it does not answer
+
+**What it reads:** the security *configuration and exposure* of a repository — which
+rules the request chain declares, which endpoints they leave open, which controls are
+present but disabled, and which custom gates can be bypassed, each with the file and
+line that says so.
+
+**What it is not:** a vulnerability scanner. No value flows through a program here, so
+an injection, a deserialization sink or a logic flaw inside a method body is not looked
+for, and its absence from the report is not evidence (NC-001, below).
+
+**Where it is strongest:** given a defect somebody else found — a scanner finding, a
+line from a review — `ask impact <symbol>` and `ask risk` quantify what it reaches: the
+endpoints, the transactional boundaries and the modules downstream of it, with the
+confidence of each hop. That is the question a taint scanner does not answer.
 
 Published because a product that states its limits is not compared on breadth — it is
 compared on depth. Each row is emitted in the payload too (`non_coverage`), so an agent
@@ -467,6 +483,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.11.0}/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.11.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`**
@@ -35,8 +35,10 @@ These numbers are cache-layer benchmarks, not a promise for every command. Per-s
 
 With the right command class, ASK Engine becomes **constant infrastructure** inside agent loops — call the fast/context surfaces before edits and reserve deep compositions for the points where their evidence is worth the runtime.
 
-**Large-repo controls.** Set `ASK_PROGRESS=1` to get line heartbeats in non-TTY
-supervised runs. Long repo-wide/deep runs also write durable records under
+**Large-repo controls.** Pass `--progress stderr` (or `--progress file:run.log`)
+for line heartbeats in a non-TTY supervised run — with the file being read so
+far and an ETA for the stage being measured. `ASK_PROGRESS` sets the same thing
+in the environment. Long repo-wide/deep runs also write durable records under
 `~/.sourcecode/runs/<repo-hash>/` by default, not inside the audited repository;
 set `ASK_RUNS_IN_REPO=1` only when repo-local `.ask/runs` records are intentional.
 Set `ASK_MAX_ANALYSIS_SECONDS=<seconds>` to fail before starting a repo-wide/deep
@@ -68,7 +70,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.11.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -284,7 +286,7 @@ from it.
 | `migrate-recipe` | experimental | the migration report as the OpenRewrite recipe that applies it | only recipes a finding named; the manual remainder published beside them; writes nothing without `--write`, and never a runnable command for an empty recipe list |
 | `data-exposure` | experimental | which routes can carry the data you labelled, and who reaches them | labels declared in `sourcecode.config.json` — never inferred from a name; `signature` and `call_reach` evidence published apart, field-level flow out of scope (NC-008). With nothing declared, `ask data-exposure /path/to/repo` answers `answered: false` and hands back the file, the key and an example to declare — it never reports zero exposed routes |
 | `endpoints` | core | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators). `--compact` answers the exposure census without the rows; `--servlets` lists the servlet-mounted surface as its own population; `--client-usage` says which routes the TS/JS client in this repository actually calls |
-| `spring-audit` | core | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review |
+| `spring-audit` | core | transactional anomalies + security configuration/exposure + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review |
 | `migrate-check` | core | Boot 2→3 readiness + Java LTS/licensing inventory: located blockers, per-dimension score, effort, detected Java 8/11/17/21/25 evidence and explicit licensing-review signals | `--target-jdk 25` sets the target LTS route; `--blast-radius` orders the re-test plan; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
 | `impact` / `impact-chain` | core | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
 | `pr-impact` | core | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
@@ -321,7 +323,21 @@ Honest limits worth knowing before you rely on it:
 - Architecture classification is tuned for Spring MVC layered apps; SPI/plugin models (e.g. Quarkus extensions) may be misclassified. JAX-RS subresource-locator endpoint recall is ~65%.
 - Self-invocation `@Transactional` bypass (same-class call skipping the proxy) is not detected.
 
-### What the security surface does not answer
+### What the security section is, and what it does not answer
+
+**What it reads:** the security *configuration and exposure* of a repository — which
+rules the request chain declares, which endpoints they leave open, which controls are
+present but disabled, and which custom gates can be bypassed, each with the file and
+line that says so.
+
+**What it is not:** a vulnerability scanner. No value flows through a program here, so
+an injection, a deserialization sink or a logic flaw inside a method body is not looked
+for, and its absence from the report is not evidence (NC-001, below).
+
+**Where it is strongest:** given a defect somebody else found — a scanner finding, a
+line from a review — `ask impact <symbol>` and `ask risk` quantify what it reaches: the
+endpoints, the transactional boundaries and the modules downstream of it, with the
+confidence of each hop. That is the question a taint scanner does not answer.
 
 Published because a product that states its limits is not compared on breadth — it is
 compared on depth. Each row is emitted in the payload too (`non_coverage`), so an agent
@@ -429,6 +445,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.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "4.10.6"
+version = "4.11.0"
 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.11.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__ = "4.10.6"
+__version__ = "4.11.0"

{sourcecode-4.10.6 → sourcecode-4.11.0}/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),