sourcecode 5.8.5__tar.gz → 5.8.6__tar.gz

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

@@ -2,6 +2,93 @@
 
 ## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.8.5
+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.5-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.5 — 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.5 → 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.5-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.5 — 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.5 → sourcecode-5.8.6}/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,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. |