sourcecode 5.8.4__tar.gz → 5.8.6__tar.gz

{sourcecode-5.8.4 → sourcecode-5.8.6}/CHANGELOG.md

@@ -2,6 +2,173 @@
 
 ## [Unreleased]
 
+## [5.8.6] — 2026-08-18
+
+*The queue the two 5.8.5 re-audits left, worked in their own order, and the
+theme is again measurement: two of the five rows were closed by **refuting the
+premise the queue carried** — the HTTP-input walk's cost turned out to be a
+parse nobody needed, and the rule pass everyone wanted parallelised is 8 % of
+the clock. The only defect either corpus still held open — WebFlux functional
+routing, eight cycles — is modelled. Four features that had been proposed for
+three rounds without landing shipped behind it.*
+
+### Fixed
+- **A series never measures a commit it has already measured** (C3-129,
+  residual of C3-128). The phase split said 82,9 % `measure:<metric>` and
+  13,8 % materialising the tree, so the command was not slow — it was one
+  analysis paid once per sampled tree, re-paid on every overlapping re-run. A
+  sampled metric is a pure function of the tree at a sha, which makes the key
+  exact rather than heuristic: analyzer fingerprint + metric + commit. Measured
+  on BroadleafCommerce: **26 845 ms → 12 ms** on the same range, samples and
+  transitions byte-identical, and the tree is not materialised at all when
+  every watched metric is a hit. A failed sample is never stored, the hit is
+  published (`sample_cache`, `from_cache`), and `--no-cache` measures
+  everything again.
+- **The HTTP-input walk parses only what it can reach** (C3-127). Two corpora
+  put `reading HTTP-input query sinks` at the top of `risk`; instrumented, none
+  of it was the analysis: 14,0 s of method extraction over 2 766 files feeding
+  a walk that runs in 0,01 s and finds nothing. The walk resolves callees by
+  name, and a file whose text cannot contain that name cannot declare it — an
+  equivalence, not a heuristic. Measured end to end: **risk 13 396 → 5 722 ms
+  (−57 %)**, the phase 10 126 → 526 ms, every row byte-identical.
+- **The measurement protocol ships as code, with a control command**
+  (P1-proc, seventh request). `steady_verdict` (six runs, not four — a
+  transient survived four passes and died on six), `contention_verdict` (a
+  control command interleaved: if the cheap command disperses too, the host is
+  the subject and nothing may be attributed to the build), `host_verdict` (no
+  other `ask` process, since cross-session contention has produced +549 %
+  here), and `scripts/perf_harness.py --steady` to run them. The field's three
+  sessions are replayed as data, so a later change to a threshold that stops
+  classifying them correctly fails in the battery instead of in a round.
+- **Every renamed shape names its producer or says why it cannot** (B21). The
+  producer is derived from the registered command tree and the import graph
+  rather than typed out; five of the six silent shapes now name a command, and
+  the sixth (`canonical-ir-v1`, reached from 28 modules) publishes `substrate`
+  with the count, because naming every command would be less true than naming
+  none.
+
+### Added
+- **WebFlux functional routing is modelled** (R2, eight cycles, the only defect
+  either corpus still held open). Paths are composed along the builder chain —
+  `.path(…)`, `.nest(…)`, the predicate form, and Kotlin's `coRouter { }` /
+  `"/x".nest { }` — so a route declared `/posts/{name}` under a nested prefix is
+  published at the path it is served on. Measured on halo: **0 → 155
+  endpoints**, and through the CIR the cascade closes too — `posture` and
+  `spring-audit` go from 0 to 173 endpoints analysed. A route whose base path is
+  decided where the router is mounted is published with `path_resolution:
+  unresolved` and the reason, never at an invented path.
+- **`ask spring-audit --recipe`** (F-BS): the audit report as an
+  `openrewrite-plan-v1` document — the findings a published recipe repairs, and
+  for every finding no recipe repairs, why its fix is a decision rather than a
+  rewrite. On this rule catalogue that first set is empty today, and the plan
+  says so: a product claiming to fix a `@Transactional` private method or a
+  stored SHA-1 digest would be claiming to make those decisions for you.
+- **`ask regress <before.json> <after.json>`** (F-BU): what moved between two
+  answers, with each delta attributed to a declaration the payloads already
+  carry, and `unattributed` for the ones nothing explains — the operational
+  definition of a silent regression. It refuses comparisons taken under
+  different cache states, which is what four of the field's nine false
+  positives were.
+- **`ask selftest <repo>`** (F-BV): this product's own defect ledger, run
+  against your repository through the entry point you invoke. Seven rows ship;
+  a row whose precondition your repository does not meet answers
+  `not_applicable` with the reason, never `pass` — a green run over nothing is
+  how ASK-09 was closed twice.
+- **`_meta.answer_bounds`** (F-BT): one envelope aggregating the twelve
+  disclosure fields this product publishes, so *"can I act on this answer?"* is
+  one line instead of twelve. It copies no value — provenance and confidence
+  are published as the paths where the payload states them — and lives under
+  `_meta`, so no payload shape a consumer pins moves.
+
+### Changed
+- **Four commands leave the experimental tier on their evidence**: `risk`,
+  `data-exposure`, `audit-report` and `migrate-recipe` become `supported` after
+  ten external rounds on two corpora with a census that never moved. The three
+  that stay now name what is still moving (`cli.EXPERIMENTAL_BASIS`), so
+  membership of that tier is a decision rather than an omission — `posture`
+  spent four releases published as *"do not gate CI on it"* while two field
+  evaluations recommended it first.
+
+## [5.8.5] — 2026-08-18
+
+*Six rows, and the theme is that four of them were closed by **measuring** rather
+than by reasoning — including the one that had been closed twice before on
+reasoning. `ASK-09`'s fifth cycle turned out to be one line of behaviour nobody
+had measured: the hint derived with no Click context returns the field's sentence
+byte for byte, about a command that declares two bounding flags. The `+66 %`
+regression `ASK-17` was holding does not reproduce under controlled conditions
+(+2,3 %), and the mechanism it suspected is worth ~3 %. `timeline`'s 198 s is 83 %
+the analysis it re-runs per tree and 17 % git. And two of the six were found by
+the measurements themselves rather than reported by anyone.*
+
+### Fixed
+- **A ceiling hint that could not read the command's flags now says so** (ASK-09,
+  fifth cycle, second false closure). Measured on the previous tree:
+  `build_hint(None)` — the guard reached with no Click context — returns *"No
+  smaller inline variant is available with the current flags"*, the field's
+  sentence byte for byte, about a command that declares `--compact` and
+  `--limit`. `_declared_and_used(None)` answered `([], set())` and the prefix rule
+  spelled that *absence of a reading* as a *claim about the command*; a
+  `CliRunner` always has a context, which is why nine batteries stayed green
+  through three cycles. Four halves close it: a **second, context-free authority**
+  (the command tree resolved from `sys.argv`, consulted only when the context
+  yields no bounding flag); **observability** — every `OUTPUT_TOO_LARGE` refusal
+  publishes `hint_basis` (`derived_from`, `command`, `declared_flags`,
+  `flags_already_passed`, `context_found`), AST-enforced across all four guards;
+  a **loud failure** when nothing could be resolved, instead of a confident
+  falsehood; and the collateral the row named — the `--force` bypass read the same
+  thread-local and degraded on the identical path. On the field's own subject
+  (`tutorials`, 24 074 `.java`, real 50K ceiling): `estimated_tokens: 241 527`,
+  0,06 % from the reporter's 241 394, hint naming both flags.
+- **The shared parse store names which repository is cold** (ASK-17). It is
+  content-addressed across repositories, so it published one total for every
+  repository the machine had analysed and no attribution — and the field paid
+  457,6 s on a cold `--compact` to discover an eviction. Both halves were already
+  held and thrown away: the walk knows the repository and computes the key. The
+  run records the pairs, `cache status` intersects them with the entry walk it
+  already performs, and coverage is published per repository. The index is merged
+  rather than replaced (a `--changed-only` run must not publish *"12 of 12 cached"*
+  about a cold repository), carries its basis, and is neither an entry nor
+  evictable.
+- **`timeline` publishes where its clock goes** (C3-128). Attribution before
+  tuning, the rule ASK-16 proved: BroadleafCommerce, `--since HEAD~5 --watch
+  posture`, wall 38 921 ms — `measure:posture` 82,9 %, `materialise_tree` 13,8 %,
+  `release_tree` 3,3 %, unaccounted 0,0 %. So five sixths of the cost is the
+  analysis re-run per tree by construction; there is no timeline-specific overhead
+  to remove, and the gain belongs to the metric being sampled.
+- **The declared `schema_version` renames get a date** (B20). `BC-002`: announced
+  5.8.5, takes effect 6.0.0, printed by `ask schema breaking-changes-v1`, carried
+  in `## Upgrading`, and projected into `schemas-v1` as `pending_renames_window` —
+  one fact, two surfaces. The registry's policy is generalised rather than
+  loosened: a declared change is `kind: exit_code` (must move an exit code) or
+  `kind: contract` (must move a published value *and* name when). Correction to
+  the reported cause: **seven** shapes spell their version `1.0`, not two.
+- **Every cache store names the variable that moves it** (E-37, found while
+  measuring ASK-17). Two variables cover three stores whose defaults are siblings
+  under one home, so an operator who empties *the cache* can empty one and be
+  served answers out of the other — which is exactly what happened: 2,4 s against
+  113 s, with an empty parse store. `cache status` now publishes `base_env` per
+  store from one authority and prints it beside each path; `docs/CACHE.md` carries
+  a column instead of a sentence. The assertions are behavioural.
+
+### Measured, not fixed
+- **The `+66 %` cold regression `ASK-17` was holding does not reproduce.**
+  `tutorials` (24 073 `.java`), root `--compact`, both cache bases isolated and
+  emptied between runs, `ASK_PARSE_CACHE_MAX_MB` fixed: 5.7.2 112,0 / 112,6 s
+  against 113,8 / 115,2 s here, **+2,3 %**. With the store pre-filled to 489 MB
+  against the default 512 MB budget — the audit's own condition, isolated as the
+  only variable — **117,0 s, +2,7 %**. So permanent LRU sweeping costs ~3 %, not
+  66 %. What the measurement *does* confirm is the row's own claim: one
+  24 073-file repository leaves 470 MB in a 512 MB budget, so a second repository
+  of any size guarantees a permanently sweeping store. Sizing rule, measured:
+  ~20 KB of store per Java file.
+
+### Found on the way
+- **B21**: six of the thirteen shapes being renamed name no producing command
+  (`emitted_by: []`) beside seven that do, which reads as *"nothing emits this"* —
+  i.e. tells the affected consumer it is unaffected. Each row now carries
+  `emitted_by_basis` naming the gap instead of shipping the empty list as a fact.
+
 ## [5.8.4] — 2026-08-17
 
 *Four rows, and three of them were reported with the wrong cause — which is the
@@ -213,11 +380,43 @@ cap the message names.*
 
 ## Upgrading — incompatible changes
 
-*A change that turns `exit 0` into `exit 1` is a breaking change, and it belongs
-here rather than in a line of a release section. Declared in
-`sourcecode.breaking_changes`, printed by `ask schema breaking-changes-v1`, and
-named in the `--help` of every command it can fire on, so an upgrade can be
-planned instead of discovered by a red pipeline.*
+*A change that breaks a caller belongs here rather than in a line of a release
+section. Two kinds qualify: one that turns `exit 0` into `exit 1`, and one that
+changes a **published value** while every exit code stays 0. Declared in
+`sourcecode.breaking_changes`, printed by `ask schema breaking-changes-v1`, and —
+for the exit-code kind — named in the `--help` of every command it can fire on,
+so an upgrade can be planned instead of discovered by a red pipeline.*
+
+### BC-002 — `schema_version` values are renamed to their canonical names (announced 5.8.5, takes effect 6.0.0)
+
+**Who is affected.** Any consumer that dispatches on the emitted
+`schema_version` string, or validates a payload by matching it. **No exit code
+moves**: a run that answered 0 still answers 0, and what changes is a value
+inside the payload.
+
+Thirteen shapes spell their version in a form that does not follow the naming
+rule (`1.0`, `1.1`, `final-v1`, …). Each already carries the name it becomes —
+`ask schema schemas-v1` publishes them as `pending_renames`, and the list is read
+from the registry rather than copied here. **Seven of them spell it `1.0`
+today** — `core-analysis-v1`, `impact-chain-v1`, `pr-impact-v1`,
+`migration-blast-v1`, `spring-impact-v1`, `event-topology-v1` and
+`test-gap-ranking-v1` — so that identifier does not name a contract on its own;
+the registry publishes that as `ambiguous_identifiers`, and `ask schema 1.0`
+resolves to all seven with the canonical name to pin for each.
+
+**What was missing until now was the date.** The renames were declared without a
+cut-off, so a consumer could read what would change and not when (B20). The
+window: the emitted value is unchanged for the whole of 5.x, and becomes the
+canonical name in **6.0.0**.
+
+**Pin the canonical name today** — `ask schema <canonical>` already resolves, and
+a consumer written against it needs no change in 6.0.0. That is the point of
+announcing a major ahead. **Stop dispatching on `1.0`**: it is ambiguous by
+construction, so match the canonical name or the `subject` the registry publishes
+beside it.
+
+The rename is deliberately **not** made early. Renaming an emitted value before
+its window is exactly the incompatible change this policy exists to prevent.
 
 ### BC-001 — stdout over the output ceiling exits 1 (since 5.7.0)
 

{sourcecode-5.8.4 → sourcecode-5.8.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.8.4
+Version: 5.8.6
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 Project-URL: Homepage, https://github.com/HarounDominique/sourcecode
 Project-URL: Repository, https://github.com/HarounDominique/sourcecode
@@ -49,7 +49,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.8.4-blue)
+![Version](https://img.shields.io/badge/version-5.8.6-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -137,7 +137,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.4 — and, on a build that has aged,
+ask version                    # ask 5.8.6 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -328,7 +328,7 @@ Unresolved is a first-class outcome: a condition the resolver cannot decide is r
 hole with the condition named, never folded into active or inactive. **A posture answer that
 guesses is a confident security falsehood — the worst failure mode this tool has.**
 
-### 5c · Composed Risk *(experimental)*
+### 5c · Composed Risk
 Every command above answers one axis, and a reader composes them by hand. `ask risk` does the
 join over the endpoint and symbol ids these commands already share with each other:
 `severity_effective = defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`. The
@@ -370,7 +370,7 @@ experimental: both are true, and they are two different facts.
 |---|---|---|
 | **core** | contract stable within a major — safe to gate CI on | `endpoints` · `spring-audit` · `migrate-check` · `impact` · `impact-chain` · `pr-impact` · `verify` |
 | **supported** | maintained; fields are added, never removed without a major | every command not named in another row |
-| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `enrich` · `audit-report` · `data-exposure` · `migrate-recipe` · `archetype` · `timeline` |
+| **experimental** | shape may change in a minor — do not gate CI on it | `enrich` · `archetype` · `timeline` |
 | **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
@@ -387,11 +387,11 @@ from it.
 | Command | Tier | Answers | Note |
 |---|---|---|---|
 | `posture` | supported | which beans a profile set wires, and how effective endpoint access differs between two sets | the most differentiated capability here. `--resolve-environments` says which set the repository decides; `--profile-from <file>` reads the artefact that actually decides it (Kubernetes manifest, compose file, deployment plan, `Dockerfile`, dotenv) and answers under that set, with the `file:line` — deciding nothing leaves the verdict untouched |
-| `risk` | experimental | what each defect actually costs, once reach, access, write effect and the shape of the input path are in it | `defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`; every factor names its authority; the `query_construction` factor covers MyBatis `${}` splicing with a three-state verdict (`reaches` / `does_not_reach` / `undecidable`) and publishes the census; `--table --rule SEC-008 --band high --top-n 20` gives audit triage without `jq` |
+| `risk` | supported | what each defect actually costs, once reach, access, write effect and the shape of the input path are in it | `defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`; every factor names its authority; the `query_construction` factor covers MyBatis `${}` splicing with a three-state verdict (`reaches` / `does_not_reach` / `undecidable`) and publishes the census; `--table --rule SEC-008 --band high --top-n 20` gives audit triage without `jq` |
 | `enrich` | experimental | another scanner's SARIF findings, ranked by what this repository does with them | `--sarif <log>`; same composition as `risk`, with `--table --rule <id> --band high --top-n 20` for triage |
-| `audit-report` | experimental | human audit bundle over existing `risk` + `posture` evidence, optionally signed | includes `evidence_manifest` claim provenance; `--format markdown`; `--sign-key <file>` signs canonical JSON with HMAC-SHA256 |
-| `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 |
+| `audit-report` | supported | human audit bundle over existing `risk` + `posture` evidence, optionally signed | includes `evidence_manifest` claim provenance; `--format markdown`; `--sign-key <file>` signs canonical JSON with HMAC-SHA256 |
+| `migrate-recipe` | supported | 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` | supported | 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; `--consumer <repo>` (repeatable) joins the routes against consumers in **other** repositories — TypeScript/JS and Java — and turns the census into a surface-reduction plan: open and called (fix now), open and called by nobody (delete rather than guard), and calls this server serves no route for |
 | `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. Every run inventories its own rules — `rules_run`, `rules_not_run`, `rules_partially_run`, `rules_run_count`/`rules_total` — so "all of them" is a fact, not an assumption |
 | `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 |
@@ -409,6 +409,8 @@ from it.
 | `baseline capture\|diff` · `trend` | supported | versioned architectural metrics over time; `ask trend .` reads the series (a repository path or a baselines directory), `ask baseline diff .` compares the tree against its newest point | trend reporting, not gating. Baselines land in `.ask/baselines` **inside the repository** — the history travels with the code, not with a vendor; an audit that must not write passes `--dir`. `capture --auto` is the unattended form (one baseline per commit, never rewrites one, never fails the build) — automate it: [baseline-ci.yml](docs/baseline-ci.yml) |
 | `retrieve` | parked | typed knowledge queries over the model | |
 | `timeline` | experimental | since when a number moved, and in which commit window | walks the commit series and re-runs the shipped analyses (`posture`, `data-exposure`, `endpoints`, `spring-audit`) on a read-only materialisation of each sampled tree; publishes transitions, not a per-commit dump. A sample that could not be analysed is `null` with a reason, never 0, and a transition under sampling carries the window it could have happened in |
+| `regress` | supported | what moved between two payloads of the same command, and which declaration accounts for it | attributes each delta to a declaration the answers carry (`test_source_excluded`, `symbols_excluded`, `coverage.gaps`, `*_cap`, `waivers`); a delta nothing explains is `unattributed`. Refuses the comparison when `cache_layers`, `base_env` or the analyzer fingerprint differ |
+| `selftest` | supported | this product's own defect ledger, run against your repository | each ledger row's acceptance criterion as an executable assertion, with the subject (repository, size, platform, entry point) beside every verdict; a row whose precondition the repository does not meet is `not_applicable` with the reason, never a pass |
 | `archetype` | experimental | evidence-based architectural archetype | |
 | `rename-class` / `chunk-file` | supported | word-boundary Java rename; split a large file for an agent | |
 | `cache status\|warm\|model\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | supported | housekeeping | `cache model [path]` explains what a warm buys per command; `activate` too |

{sourcecode-5.8.4 → sourcecode-5.8.6}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.8.4-blue)
+![Version](https://img.shields.io/badge/version-5.8.6-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -92,7 +92,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.4 — and, on a build that has aged,
+ask version                    # ask 5.8.6 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -283,7 +283,7 @@ Unresolved is a first-class outcome: a condition the resolver cannot decide is r
 hole with the condition named, never folded into active or inactive. **A posture answer that
 guesses is a confident security falsehood — the worst failure mode this tool has.**
 
-### 5c · Composed Risk *(experimental)*
+### 5c · Composed Risk
 Every command above answers one axis, and a reader composes them by hand. `ask risk` does the
 join over the endpoint and symbol ids these commands already share with each other:
 `severity_effective = defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`. The
@@ -325,7 +325,7 @@ experimental: both are true, and they are two different facts.
 |---|---|---|
 | **core** | contract stable within a major — safe to gate CI on | `endpoints` · `spring-audit` · `migrate-check` · `impact` · `impact-chain` · `pr-impact` · `verify` |
 | **supported** | maintained; fields are added, never removed without a major | every command not named in another row |
-| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `enrich` · `audit-report` · `data-exposure` · `migrate-recipe` · `archetype` · `timeline` |
+| **experimental** | shape may change in a minor — do not gate CI on it | `enrich` · `archetype` · `timeline` |
 | **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
@@ -342,11 +342,11 @@ from it.
 | Command | Tier | Answers | Note |
 |---|---|---|---|
 | `posture` | supported | which beans a profile set wires, and how effective endpoint access differs between two sets | the most differentiated capability here. `--resolve-environments` says which set the repository decides; `--profile-from <file>` reads the artefact that actually decides it (Kubernetes manifest, compose file, deployment plan, `Dockerfile`, dotenv) and answers under that set, with the `file:line` — deciding nothing leaves the verdict untouched |
-| `risk` | experimental | what each defect actually costs, once reach, access, write effect and the shape of the input path are in it | `defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`; every factor names its authority; the `query_construction` factor covers MyBatis `${}` splicing with a three-state verdict (`reaches` / `does_not_reach` / `undecidable`) and publishes the census; `--table --rule SEC-008 --band high --top-n 20` gives audit triage without `jq` |
+| `risk` | supported | what each defect actually costs, once reach, access, write effect and the shape of the input path are in it | `defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`; every factor names its authority; the `query_construction` factor covers MyBatis `${}` splicing with a three-state verdict (`reaches` / `does_not_reach` / `undecidable`) and publishes the census; `--table --rule SEC-008 --band high --top-n 20` gives audit triage without `jq` |
 | `enrich` | experimental | another scanner's SARIF findings, ranked by what this repository does with them | `--sarif <log>`; same composition as `risk`, with `--table --rule <id> --band high --top-n 20` for triage |
-| `audit-report` | experimental | human audit bundle over existing `risk` + `posture` evidence, optionally signed | includes `evidence_manifest` claim provenance; `--format markdown`; `--sign-key <file>` signs canonical JSON with HMAC-SHA256 |
-| `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 |
+| `audit-report` | supported | human audit bundle over existing `risk` + `posture` evidence, optionally signed | includes `evidence_manifest` claim provenance; `--format markdown`; `--sign-key <file>` signs canonical JSON with HMAC-SHA256 |
+| `migrate-recipe` | supported | 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` | supported | 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; `--consumer <repo>` (repeatable) joins the routes against consumers in **other** repositories — TypeScript/JS and Java — and turns the census into a surface-reduction plan: open and called (fix now), open and called by nobody (delete rather than guard), and calls this server serves no route for |
 | `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. Every run inventories its own rules — `rules_run`, `rules_not_run`, `rules_partially_run`, `rules_run_count`/`rules_total` — so "all of them" is a fact, not an assumption |
 | `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 |
@@ -364,6 +364,8 @@ from it.
 | `baseline capture\|diff` · `trend` | supported | versioned architectural metrics over time; `ask trend .` reads the series (a repository path or a baselines directory), `ask baseline diff .` compares the tree against its newest point | trend reporting, not gating. Baselines land in `.ask/baselines` **inside the repository** — the history travels with the code, not with a vendor; an audit that must not write passes `--dir`. `capture --auto` is the unattended form (one baseline per commit, never rewrites one, never fails the build) — automate it: [baseline-ci.yml](docs/baseline-ci.yml) |
 | `retrieve` | parked | typed knowledge queries over the model | |
 | `timeline` | experimental | since when a number moved, and in which commit window | walks the commit series and re-runs the shipped analyses (`posture`, `data-exposure`, `endpoints`, `spring-audit`) on a read-only materialisation of each sampled tree; publishes transitions, not a per-commit dump. A sample that could not be analysed is `null` with a reason, never 0, and a transition under sampling carries the window it could have happened in |
+| `regress` | supported | what moved between two payloads of the same command, and which declaration accounts for it | attributes each delta to a declaration the answers carry (`test_source_excluded`, `symbols_excluded`, `coverage.gaps`, `*_cap`, `waivers`); a delta nothing explains is `unattributed`. Refuses the comparison when `cache_layers`, `base_env` or the analyzer fingerprint differ |
+| `selftest` | supported | this product's own defect ledger, run against your repository | each ledger row's acceptance criterion as an executable assertion, with the subject (repository, size, platform, entry point) beside every verdict; a row whose precondition the repository does not meet is `not_applicable` with the reason, never a pass |
 | `archetype` | experimental | evidence-based architectural archetype | |
 | `rename-class` / `chunk-file` | supported | word-boundary Java rename; split a large file for an agent | |
 | `cache status\|warm\|model\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | supported | housekeeping | `cache model [path]` explains what a warm buys per command; `activate` too |

{sourcecode-5.8.4 → sourcecode-5.8.6}/docs/CACHE.md

@@ -37,13 +37,19 @@ Two things invalidate everything, everywhere:
 
 ## Where it lives
 
-| Path | Holds |
-|---|---|
-| `~/.sourcecode/cache/<repo-id>/` | snapshot cache (`core-*`, `view-*`), the RIS, `prepare-context` task answers |
-| `~/.sourcecode/ctx-*.json.gz` | the shared Canonical IR |
-| `~/.sourcecode/parse-cache-v1/` | the per-file parse cache |
-
-`SOURCECODE_CACHE_DIR` and `SOURCECODE_CONTEXT_CACHE_DIR` move them. Nothing leaves the machine.
+| Path | Holds | Moved by |
+|---|---|---|
+| `~/.sourcecode/cache/<repo-id>/` | snapshot cache (`core-*`, `view-*`), the RIS, `prepare-context` task answers | `SOURCECODE_CACHE_DIR` |
+| `~/.sourcecode/ctx-*.json.gz` | the shared Canonical IR | `SOURCECODE_CONTEXT_CACHE_DIR` |
+| `~/.sourcecode/parse-cache-v1/` | the per-file parse cache | `SOURCECODE_CONTEXT_CACHE_DIR` |
+
+Two variables, three stores, and the column says which moves which — because the paths are
+siblings under one home and the split is not derivable from them. **Redirecting or emptying one
+and not the other leaves the other serving answers**: measured on 2026-08-18 while taking the
+`ASK-17` A/B, a cold run with only `SOURCECODE_CONTEXT_CACHE_DIR` redirected answered from the
+snapshot store in 2,4 s against 113 s, with an empty parse store — a cold measurement that had
+silently become a warm one (E-37). `ask cache status` names the variable beside each store for
+the same reason. Nothing leaves the machine.
 
 The cache is keyed to **the path you analysed**: `cache warm ./service-a` warms `service-a`, not
 the enclosing monorepo, and `cache status` / `cache clear` resolve to that same scope.
@@ -59,6 +65,7 @@ the enclosing monorepo, and `cache status` / `cache clear` resolve to that same
 | `ris` | the Repository Intelligence Snapshot — structural index, endpoint index, summaries | tree state (the snapshot records the tree it describes) | rebuilt on every warm |
 | `cir` | the shared Canonical IR — the Java parse every knowledge command reuses | tree state · analyzer fingerprint · schema version | built |
 | `task` | one `prepare-context` task answer, per task and per option set | tree state · task · --symptom / --all / --include-config / --format | never — a warm does not run any task |
+| `timeline-samples` | one watched metric as measured at one sampled commit, so a series re-run over an overlapping range measures only what is new (C3-129) | the analyzer fingerprint and the commit sha, both in the key. The tree at a sha never changes, so an entry is never stale — the fingerprint is what keeps a corrected analysis from being served from a previous release. `timeline --no-cache` (or `ASK_TIMELINE_NO_SAMPLE_CACHE=1`) measures every sample again | never — a warm analyses the working tree, not history |
 | `parse` | the symbol extraction of one file, keyed by its bytes | the file's own bytes and the extractor's source — content-addressed, so it is never stale and never needs invalidating. Bounded by `ASK_PARSE_CACHE_MAX_MB` (default 512 MB, least-recently-used, swept every 32 MB written rather than on every write, and the last interval before a process exits is never swept — so the store rests up to one interval per writing process above its budget, and the figure to size a disk by is the ceiling `cache status` publishes beside it, not the budget itself (ASK-15)) and reported in `cache status` (F-AR) | filled for every Java file the warm parses |
 
 Measured on BroadleafCommerce (2 000+ Java files, dirty tree), warm machine, 3.2.2, each command in isolation.
@@ -100,7 +107,9 @@ The second anchor is the field one, and it carries its own build for the same re
 | `modernize` | the shared work | 5.2 s → 3.0 s | no | `parse` | Blocked in the session that recorded C3-53 and measured since: a run that did not finish once is not a command that cannot finish. |
 | `chunk-file` | nothing | not timed | no | — | Reads one file; nothing to cache. |
 | `cold-start` | the answer | 0.2 s either way | yes | `ris` | Reads the RIS a warm rebuilds — that is all it does. Without one it answers `no_ris` instead of a snapshot. |
-| `timeline` | nothing | not timed | no | — | Each sample is a fresh materialisation of a different commit, so nothing is shared between samples: two commits are two trees, and a cache keyed on a tree state can only ever serve one of them. The per-sample cost is measured and published in the payload. |
+| `timeline` | nothing | not timed | yes | `timeline-samples` | Two commits are two trees, so nothing is shared *within* a run — but a metric at a commit is a pure function of that tree, and the tree at a sha never changes, so a sample an earlier run of this analyser already measured is read from the store instead of being measured again (C3-129). A warm builds nothing for it: a warm analyses the working tree, not history. `--no-cache` measures every sample again, and the payload publishes the hits. |
+| `selftest` | the shared work | not timed | no | `cir`, `parse` | Runs the ledger's acceptance criteria by invoking other commands against this repository, so it inherits their layers — a warm makes those runs warm. It holds no cache of its own and stores nothing. |
+| `regress` | nothing | not timed | no | — | Diffs two payload files this CLI already wrote; analyses no source, so no cache layer applies. What it reads about caching is the `cache_layers` field inside those payloads — to refuse a comparison taken under different cache states, not to use one. |
 | `trend` | nothing | not timed | no | — | Reads stored baseline artifacts from disk; analyses no source, so no cache layer applies. Same command as `baseline trend`. |
 | `baseline` | the shared work | capture 8.7 s → 3.6 s | no | `parse` | `capture`/`diff`/`trend` over architectural metrics. The field figure is `capture`, the subcommand that analyses; `trend` reads stored artifacts and has its own row. |
 | `retrieve` | the shared work | not timed | no | `cir`, `parse` | Every query builds or reuses the shared CIR a warm builds. |