sourcecode 5.8.5__tar.gz → 5.8.7__tar.gz

{sourcecode-5.8.5 → sourcecode-5.8.7}/CHANGELOG.md

@@ -2,6 +2,177 @@
 
 ## [Unreleased]
 
+## [5.8.7] — 2026-08-18
+
+*An ASK polish pass, and then the recommended-feature queue emptied. The theme
+of the fixes is again the one the field keeps teaching: **three of the seven
+closed by finding the premise wrong**. E-9's caveat was not dropped between two
+commands — on that shape nothing ever produced it. E-14's row said "either the
+limit is not enforced or it is enforced and unreported"; it was neither, two
+authorities disagreed about the same number. And `C3-84`'s confident falsehood
+turned out to be **our own qualifier**, added a release earlier to close a
+silence, refuted by our own measurement.*
+
+### Fixed
+- **A partially resolved route path is unresolved, and its id stays readable**
+  (E-9). `@Path("/{accountId:" + UUID_PATTERN + "}")` contains string literals,
+  so every reader concluded the path was known and published the first literal —
+  `/{accountId:` — as the route, silently. A partial resolution is not a
+  resolution. The caveat is now a field of `CanonicalEndpoint`, so `endpoints`,
+  `impact-chain` and `impact` publish it from one authority; and `make_id`
+  percent-escapes the separator, so an endpoint id has four fields for every
+  route rather than five.
+- **The re-export hop budget is enforced, and running out of it is declared**
+  (E-14). Two authorities disagreed: the test said a three-level chain must not
+  resolve, the walk said "depth=2 total" and resolved it. The walk wins — two
+  hops land on the module where the symbol is declared. What was missing is the
+  other side, plus two defects found while adjudicating: a chain still going
+  when the budget ran out was published as if it had ended, and a chain that
+  simply ends inside a package reported a limit it never reached.
+- **`impact-chain`'s sentence names the unit its number is in** (C1-16, witness
+  a). It printed the entry count under the words "22 direct callers" while the
+  field beside it said 14. `impact` had closed this half already.
+- **`--jobs` states the measured cost split, not the estimate** (C3-84). The
+  4.15.0 wording called the rule pass *"where a repository-wide audit spends
+  most of its time"*. Instrumented: the CIR build is 88 % of the clock and every
+  rule together 8 %. All three surfaces carry the measurement now, and the
+  correction reverses what the flag implies — it covers the phase with the cost.
+- **A run cannot exit 0 without producing the file it promised** (C3-122). One
+  field report: 444 s, exit 0, no output, no file. Fixed as the shape rather
+  than the occurrence — the promise is noted from the argument vector, so all 65
+  commands that publish `--output` are covered including one that returns before
+  its emit seam, and a file write is never silent.
+- **SEC-001 reports an absence it measured, not a verdict it did not** (C1-43).
+  It told the reader *"any caller can reach this endpoint without
+  authentication"* from the absence of the two chain shapes it knows how to look
+  for, at `confidence: high`. It now states what was looked for and not found,
+  publishes the premise as evidence, and binds the coverage answer to the
+  authority that owns it.
+- **DEAD-001 keeps `high`, and the reason is on the record** (C3-101 c). The
+  severity was never the defect; the precision was, and it shipped.
+
+### Added
+- **`spring-audit --since <ref> --fail-on-new`** (F-BL) — the gate a repository
+  with existing debt can actually turn on. Joins two audits on the content-stable
+  `defect_id` and fails only on what the change introduced. Both sides are asked
+  the same question and the payload says which; a renamed symbol reads as one
+  resolved plus one new and says so; a comparison that could not be made exits
+  non-zero, never 0.
+- **`ask explain-endpoint '<VERB> <path>'`** (F-BN) — show your work for one
+  route: match, declaration, handler, chain, profiles, verdict, each naming the
+  authority that produced it and the file it can be checked against. A step that
+  could not be derived is `undetermined` **with the reason** — none of the six is
+  ever absent in silence.
+- **`spring-audit --remediation-diff`** (F-BK) — the findings as patches `git
+  apply` takes, for the defects whose repair is the lexical inverse of the
+  defect. Not `--recipe` with a different encoding: a recipe is run, a diff is
+  decided, and every patch carries what applying it decides.
+- **`spring-audit --clusters`** (F-BM) — 386 rows as the handful of things
+  somebody has to do, keyed on `(defect_kind, repair_shape, locus)` with the axis
+  declared. The effort figure is an assumption with its arithmetic exposed; an
+  owner comes from CODEOWNERS or is absent.
+- **A deprecation channel for published payload keys** (F-BQ, BC-003). A key on
+  its way out is published beside its replacement with the release that removes
+  it. `auth status` moves onto it, so it ships with a real population.
+- **The base URL a client centralises is resolved from its own declaration**
+  (F-BO). 115 of 135 client calls were unresolved for one reason: the head is a
+  constant written a few lines up. A name bound twice — `environment.ts` and
+  `environment.prod.ts` — is still not resolved.
+- **A declaration split across lines is still a declaration** (F-BP). A wrapped
+  generic return type published the member with *no annotations at all*, so the
+  route left the census and its guard left with it. `endpoints` on
+  BroadleafCommerce and spring-boot-admin is byte-identical: recall on the broken
+  shapes and nothing else.
+- **A cost fixture for the composition family** (F-BR, second half) — counted,
+  not timed, so it means the same thing on any machine.
+
+## [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
@@ -300,6 +471,27 @@ changes a **published value** while every exit code stays 0. Declared in
 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-003 — deprecated payload keys are removed (announced 5.8.7, takes effect 6.0.0)
+
+**Who is affected.** Any consumer reading a key that `field_deprecations` lists.
+**No exit code moves**: the key stops being emitted, and a consumer that reads it
+gets nothing rather than a wrong value.
+
+A published key that has been replaced is emitted **beside** its replacement for
+the whole window, listed in the payload's own `deprecated_fields`, and described
+in `field_deprecations` with the release that removes it — `alias_of` where the
+key was renamed and is copied from its replacement, `replaced_by` where the
+value is derived differently and the command still produces it. In 6.0.0 those
+keys stop being emitted, and nothing is removed that was not declared here
+first. C3-124 is the reason the channel exists rather than the schedule: an
+experimental tier is permission to change shape, not permission to change it in
+silence.
+
+The population is read from `sourcecode.field_deprecations` rather than copied
+here. Today it is the four `pro*` keys on `ask auth status`, which that payload
+publishes side by side with the entitlement block that replaced them — so the
+migration is checkable against one run.
+
 ### 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

{sourcecode-5.8.5 → sourcecode-5.8.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.8.5
+Version: 5.8.7
 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.5-blue)
+![Version](https://img.shields.io/badge/version-5.8.7-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
@@ -91,9 +91,11 @@ in the environment, and the heartbeat is emitted by the analysis itself, not onl
 by a timer thread, so a CPU-bound stretch is never silent. `--jobs N` / `-j`
 (env `ASK_JOBS`) sets the worker processes that parse files — default CPU count
 − 1; parallelism only warms the content-addressed parse cache, so the answer is
-byte-identical at any value. It does **not** parallelise the rule pass, which is
-where a repository-wide audit spends most of its time, and a warm cache leaves it
-nothing to parse — so raising it there buys nothing. Long repo-wide/deep runs also write durable records
+byte-identical at any value. It does **not** parallelise the rule pass —
+measured with `metadata.timings` on a 2 766-file repository, the CIR build is
+88 % of a repository-wide audit's clock and every rule together 8 %, so the flag
+covers the phase that holds the cost; a warm cache leaves it nothing to parse, so
+raising it there buys nothing. 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. Use `ask audit-report --from-risk risk.json` to package an existing
@@ -137,7 +139,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.5 — and, on a build that has aged,
+ask version                    # ask 5.8.7 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -328,7 +330,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 +372,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 +389,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 +411,9 @@ 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 |
+| `explain-endpoint` | supported | the derivation behind one route's verdict | six steps — match, declaration, handler, chain, profiles, verdict — each naming the authority that produced it and the file it can be checked against; a step that could not be derived is `undetermined` with the reason, never absent |
+| `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.5 → sourcecode-5.8.7}/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.5-blue)
+![Version](https://img.shields.io/badge/version-5.8.7-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
@@ -46,9 +46,11 @@ in the environment, and the heartbeat is emitted by the analysis itself, not onl
 by a timer thread, so a CPU-bound stretch is never silent. `--jobs N` / `-j`
 (env `ASK_JOBS`) sets the worker processes that parse files — default CPU count
 − 1; parallelism only warms the content-addressed parse cache, so the answer is
-byte-identical at any value. It does **not** parallelise the rule pass, which is
-where a repository-wide audit spends most of its time, and a warm cache leaves it
-nothing to parse — so raising it there buys nothing. Long repo-wide/deep runs also write durable records
+byte-identical at any value. It does **not** parallelise the rule pass —
+measured with `metadata.timings` on a 2 766-file repository, the CIR build is
+88 % of a repository-wide audit's clock and every rule together 8 %, so the flag
+covers the phase that holds the cost; a warm cache leaves it nothing to parse, so
+raising it there buys nothing. 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. Use `ask audit-report --from-risk risk.json` to package an existing
@@ -92,7 +94,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.5 — and, on a build that has aged,
+ask version                    # ask 5.8.7 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -283,7 +285,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 +327,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 +344,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 +366,9 @@ 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 |
+| `explain-endpoint` | supported | the derivation behind one route's verdict | six steps — match, declaration, handler, chain, profiles, verdict — each naming the authority that produced it and the file it can be checked against; a step that could not be derived is `undetermined` with the reason, never absent |
+| `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.5 → sourcecode-5.8.7}/docs/CACHE.md

@@ -65,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.
@@ -106,7 +107,10 @@ 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. |
+| `explain-endpoint` | the shared work | not measured on the battery yet — bounded by `endpoints` on the same repository | yes | `cir`, `parse` | Builds the repository IR to answer about ONE route, so the warm it shares with `endpoints` and `posture` is the whole difference between a question you ask once and a question you ask twenty times. |
+| `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. |