sourcecode 5.2.0__tar.gz → 5.3.0__tar.gz

{sourcecode-5.2.0 → sourcecode-5.3.0}/CHANGELOG.md

@@ -2,6 +2,113 @@
 
 ## [Unreleased]
 
+## [5.3.0] — 2026-08-11
+
+**The capability queue, built on the stable point.** 5.2.0 was the highest-scored
+build of twelve rounds and left three defect rows open, none of which blocks a
+capability — so the queue that had been accumulating across four field
+evaluations was built instead. Five features, one commit each, and **not one of
+them is a new analysis**: each joins two things this product already measures.
+The three defect rows stay open on purpose (C3-112, C3-113, C3-103) and are named
+in the roadmap rather than quietly deferred.
+
+Every one of the five keeps the rule the series is built on — an answer that
+cannot be decided says so. `--profile-from` on an artefact that decides nothing
+leaves the previous verdict byte-for-byte; a waiver that expired does not apply
+and is published as expired; a timeline sample that could not be analysed is
+`null` with a reason; the spliced-SQL verdict has a third state; the
+surface-reduction plan calls its delete list *candidates* and publishes what
+bounds it.
+
+### Added
+- **`endpoints --consumer <repo>` — the surface-reduction plan (F-BH).** One
+  repository is analysed; the system is four, and the consumers live in
+  repositories nobody analyses together — so the census answers *what is exposed*
+  and every plan started with "protect 2 635 routes". Name the consumers
+  (repeatable) and `consumer_join` (`consumer-join-v1`) crosses each route's
+  access verdict, read from `posture`, with whether anybody calls it:
+  **`fix_now`** (open and consumed), **`delete_candidates`** (open and consumed by
+  nobody — remove the surface instead of guarding it), **`broken_integrations`**
+  (a consumer calls a route this server does not serve, the one direction needing
+  no coverage assumption). Java consumers are read too — `RestTemplate`/exchange
+  calls and declarative client interfaces — under the same admission rule as the
+  TypeScript side: the verb and path must be written at the call site, and a type
+  that does not declare itself an HTTP client is never read as one. The plan is
+  bounded and says so: per-consumer file counts and unresolved call sites are
+  published, `direction: under_reports` stands, `delete_candidates` carries the
+  sentence to read before acting, and a match through a neutralised path variable
+  is reported as `normalised` rather than exact. It also adjudicates
+  duplicate-looking routes (`/v1/agrupadorGfh` beside `/v1/agrupador-gfh`) by who
+  calls them: live aliases, or one live route plus debris.
+- **Bounded HTTP-input → spliced-SQL taint, three-state (F-BF).** SEC-008 reports
+  every MyBatis `${}`; which of them request input actually reaches was the
+  question nobody could answer — *"la diferencia entre 16 sitios que revisar y 2
+  sitios que arreglar hoy"* — and `risk`'s `query_construction` axis answered
+  `not_observed` (×1,0) on **all 98 rows** of the field's repository, because its
+  propagation ends at Java query-builder calls while that repository's SQL lives
+  in mapper XML. `sql_taint` (`sql-taint-v1`) joins the two ends the product
+  already resolves: the annotated `@RequestParam`/`@PathVariable`/`@RequestBody`
+  seeds `risk` walks from, and the `${}` population SEC-008 indexes, keyed by
+  namespace and statement id. Verdict lattice **`reaches`** (with the trace) /
+  **`does_not_reach`** (stated only where the call sites were found) /
+  **`undecidable`** (no resolvable call site, no statement id, an undeclared
+  namespace) — only the first moves the axis, to a new
+  `http_input_reaches_sql_interpolation` value weighted the same as the
+  concatenation case, because the distinction is the evidence and not the
+  severity. `risk` publishes the three-state census beside the rows. This is not
+  interprocedural taint and does not claim to be: NC-001 stands for everything
+  outside the pair.
+- **`ask timeline` — since when, and in which commit window (F-BJ).**
+  `data-exposure` answers *"2 453 routes reach labelled data and nothing decides
+  access to them"*; nobody could answer *since when*, which is the question that
+  turns a finding into an owner, a date and a work item — and the first question
+  asked after a breach. `ask timeline . --since v1.0 --watch
+  posture,data-exposure` walks the commit series, runs the analyses that already
+  ship on a read-only materialisation of each sampled tree (the repository is
+  never written to), and publishes **transitions** rather than a per-commit
+  dump. Four watchable metrics (`posture`, `data-exposure`, `endpoints`,
+  `spring-audit`), each declaring the command it projects, so every point is
+  re-derivable by running that command at that commit. Only buildable now
+  because the analyses cost seconds and eleven rounds of byte-identical payloads
+  mean a difference between two samples is a difference in the code. Honest by
+  construction: a sample that could not be analysed is `null` with a reason and
+  never 0; a transition names the commit it was **observed** at and publishes
+  the window it could have happened in rather than attributing it to a commit it
+  was not measured at (raise `--max-commits` to close the window to one commit);
+  the first sample is a baseline, never a transition; and the per-sample cost is
+  measured and published, because a hundred-commit series is a nightly job.
+- **`.ask/waivers.yml` — adjudication that survives the next run (F-BI).** The
+  `verify` baseline records accepted *debt*; a waiver makes the other claim —
+  *this row was never a defect here* — which is the only thing that lets a team
+  gate on a family with any false-positive rate at all (field evaluation #24: 9
+  of 9 `high` findings false on a greenfield module, and *"do not gate CI on
+  this"*). Keyed on the stable `finding_id`/`defect_id`, `reason` required,
+  optional `by` and `expires`. `spring-audit` publishes what left — `waived[]`
+  with the reason and the declaring file, `summary.waived_findings`, and a
+  `waivers` block listing what was declared, applied, **expired** and matched
+  nothing — and `verify`, `verify-edit`, `risk` and `pr-impact` honour the same
+  file, so an adjudicated row stops holding the gate red. A rule family cannot
+  be waived (a silenced family is indistinguishable from one that found
+  nothing), and a malformed file stops the command instead of reading as
+  "nothing waived". A repository that declares no waivers gets a byte-identical
+  payload.
+- **`posture --profile-from <deployment artefact>` (F-BG) — the last hop of the
+  flagship.** `posture` resolved the conditional bean graph completely and then
+  stopped where the answer is actually decided: *"SPRING_PROFILES_ACTIVE in the
+  process environment outranks every artefact below it, and this analysis cannot
+  see the process environment"* — three field evaluations named this as their
+  first choice. Name the artefact that decides it (Kubernetes manifest, compose
+  file, WebLogic deployment plan, `Dockerfile`, dotenv, launch script;
+  repeatable) and the whole command answers under that profile set, publishing a
+  `profile_from` block (`profile-from-v1`) with the artefacts read, the
+  `file:line` that decided it and the caveat that the process environment
+  outranks the file too. Undecidable-first, so the flag is safe to point
+  anywhere: a placeholder, an entry with no value, a file that never mentions the
+  setting, or two artefacts that disagree all decide **nothing**, and the
+  repository's own verdict survives byte-for-byte. `--env-file` now shares this
+  reader, so a dotenv is one shape among six instead of the only one the product
+  could be handed.
+
 ## [5.2.0] — 2026-08-11
 
 **The queue field evaluation #26 opened, and the row underneath the other rows.**

{sourcecode-5.2.0 → sourcecode-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.2.0
+Version: 5.3.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.2.0-blue)
+![Version](https://img.shields.io/badge/version-5.3.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -126,7 +126,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.2.0 — and, on a build that has aged,
+ask version                    # ask 5.3.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -195,6 +195,29 @@ ask verify /path/to/repo --init --dry-run
 ask risk /path/to/repo
 ```
 
+**And the three that answer questions this repository does not contain the answer to.**
+The profile set is decided by a deployment artefact, the consumers are other repositories,
+and *since when* is a fact about history — each one is a join of things already measured,
+and each one leaves the previous answer untouched when it cannot decide:
+
+```bash
+# The artefact that decides the profile set — Kubernetes manifest, compose file, WebLogic
+# deployment plan, Dockerfile, dotenv, launch script. Every answer is then given under the
+# set it names, with the file:line that decided it. An artefact that decides nothing (a
+# placeholder, two artefacts that disagree) leaves the repository's own verdict as it was.
+ask posture /path/to/repo --profile-from k8s/deployment-prod.yaml
+
+# Of the routes a readable rule leaves open: which ones a consumer actually calls (work),
+# and which ones nobody calls (surface to delete instead of guard). Reads TypeScript/JS and
+# Java consumers, only where the verb and the path are written at the call site.
+ask endpoints /path/to/repo --consumer ../web-client --consumer ../partner-api
+
+# Since when. Walks the commit series, runs the analyses that already ship on a read-only
+# materialisation of each sampled tree, and publishes where a number MOVED — with the commit
+# it was observed at and the window it could have happened in.
+ask timeline /path/to/repo --since v1.0 --watch posture,data-exposure
+```
+
 Then the everyday loop:
 
 ```bash
@@ -249,7 +272,7 @@ Blast radius from a class or interface — reverse dependencies, through Spring
 
 ### 3 · Architecture Intelligence
 The system map: module graph, dependency views, REST surface, per-class summaries, and a symbol-level IR for downstream tooling.
-`ask export` · `ask repo-ir` · `ask endpoints` · `ask explain`
+`ask export` · `ask repo-ir` · `ask endpoints` · `ask explain` · `ask timeline` (*experimental* — the same views over the commit series: when a number moved, and in which window)
 → [reference](docs/USER_GUIDE.md#core-commands)
 
 ### 4 · Migration & Modernization
@@ -280,6 +303,16 @@ parse and publishes the worst. A field audit closed those five hops by hand with
 the flag existed.
 `ask posture . --resolve-environments`
 
+**`--profile-from` closes the loop.** `--resolve-environments` reads what the *repository*
+says; the artefact that actually decides the profile set usually lives outside it. Name it —
+Kubernetes manifest, compose file, WebLogic deployment plan, `Dockerfile`, dotenv, launch
+script — and every answer is given under the set it sets, with the `file:line` that decided
+it. Undecidable-first, so pointing it at the wrong file costs nothing: a placeholder, an entry
+with no value, or two artefacts that disagree decide **nothing** and leave the repository's
+own verdict byte-for-byte as it was. The process environment still outranks the file, and the
+payload says so.
+`ask posture . --profile-from k8s/deployment-prod.yaml`
+
 Unresolved is a first-class outcome: a condition the resolver cannot decide is reported as a
 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.**
@@ -295,8 +328,12 @@ field case: a defect both `spring-audit` and `impact-chain` called *medium* comp
 **high (8.06)** once *reachable unauthenticated* and *writes to the database* are in it.
 The last two factors describe the input path: a query assembled by concatenation, a bounded
 HTTP-input-to-query-sink path when ASK can prove one, and a route accepting a body with no
-declared constraint. General taint remains `NC-001` and is published in the payload's own
-`non_coverage` block.
+declared constraint. **The sink family a MyBatis codebase actually uses is covered too**: an
+annotated HTTP input reaching a statement that splices it into the SQL with `${...}` is a
+three-state verdict — `reaches` (with the trace), `does_not_reach` (stated only where the call
+sites were found) or `undecidable` — and only the first moves the factor. The census is
+published beside the rows, so the multiplier is auditable rather than asserted. General taint
+remains `NC-001` and is published in the payload's own `non_coverage` block.
 `ask risk .` · `ask risk . --min-band high` · `ask risk . --limit 10`
 → [reference](docs/USER_GUIDE.md)
 
@@ -322,7 +359,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` |
+| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `enrich` · `audit-report` · `data-exposure` · `migrate-recipe` · `archetype` · `timeline` |
 | **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
@@ -338,18 +375,18 @@ 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 |
-| `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; `--table --rule SEC-008 --band high --top-n 20` gives audit triage without `jq` |
+| `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` |
 | `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 |
-| `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 |
+| `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 |
 | `impact` / `impact-chain` | core | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
 | `pr-impact` | core | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
-| `verify` | core | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2 |
+| `verify` | core | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2. `.ask/waivers.yml` adjudicates a finding as *not a defect here* (stable id + required reason, optional expiry) so a reviewed row stops holding the gate red — a baseline records accepted debt, a waiver says it was never a defect |
 | `verify-edit` | supported | did the working-tree edits change runtime behaviour | semantic diff gate for the edit loop |
 | `--compact` / `--agent` | — | bounded structural context for an agent | flags of the root command, not commands: not tiered |
 | `onboard` / `explain` / `cold-start` | supported | orientation in an unfamiliar repo; per-class summary; bootstrap snapshot | |
@@ -360,6 +397,7 @@ from it.
 | `validation` | supported | request-body validation coverage and gaps | |
 | `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 |
 | `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 |
@@ -404,7 +442,7 @@ reading JSON sees the same boundary a buyer reads here.
 
 | Not covered | Why | What answers it |
 |---|---|---|
-| **General request-input-to-sink taint analysis.** | `ask risk` includes a bounded slice for annotated HTTP parameters, positional calls in repository Java sources and known query sinks. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the bounded slice, whether an annotated HTTP input reaches a known concatenated query sink. |
+| **General request-input-to-sink taint analysis.** | `ask risk` includes two bounded slices for annotated HTTP parameters and positional calls in repository Java sources: known query sinks, and MyBatis statements that splice a value into their SQL. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the two bounded slices, whether an annotated HTTP input reaches a known concatenated query sink or a spliced SQL statement — the latter with a three-state verdict that says `undecidable` rather than clearing a route it could not follow. |
 | **Secrets outside Java, Spring configuration and the deployment descriptors — a Helm value, a CI variable file, a shell script.** | The file population this analyzer reads is the Java source, the Spring configuration convention and the descriptors it already parses to resolve an environment. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. Narrowed by CL-10: a credential stored in `web.xml` or a Spring XML context IS reported (SEC-007), because those files were already being read. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
 | **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
 | **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |
@@ -414,7 +452,7 @@ Two more boundaries worth stating in the same voice:
 | Not covered | Why | What answers it |
 |---|---|---|
 | **Applying a migration — nothing here edits source.** | This is the diagnosis layer: it measures what must change and what each change would reach. Rewriting code is an execution problem with an established executor, and duplicating it would mean maintaining a second, worse one. | OpenRewrite. `migrate-check` publishes the recipe each finding carries (`recipes[]`), which is the input that executor takes. |
-| **What the process environment sets at start-up — the profile set, properties and secrets a container is given.** | Nothing in a repository can observe the environment of a process that has not started. A value read from a file here is the default the repository ships, never a guarantee of what runs. | `ask posture --resolve-environments` reads every artefact in the repository that names the profile set, says when none of them decides it, and ranks the admissible sets by what each leaves open. |
+| **What the process environment sets at start-up — the profile set, properties and secrets a container is given.** | Nothing in a repository can observe the environment of a process that has not started. A value read from a file here is the default the repository ships, never a guarantee of what runs. | `ask posture --resolve-environments` reads every artefact in the repository that names the profile set, says when none of them decides it, and ranks the admissible sets by what each leaves open. `--profile-from <file>` goes one step further and reads the deployment artefact itself, which is where that decision is actually written — still a file, so the process environment still outranks it, and the payload says so. |
 
 
 And one about the endpoint surface itself:
@@ -560,7 +598,7 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | Doc | What it covers |
 |-----|----------------|
 | [USER_GUIDE.md](docs/USER_GUIDE.md) | Full command reference, flags, output schema, workflows |
-| [contracts.md](docs/contracts.md) | Declare invariants in `.ask/contracts.yml` (or derive them with `ask verify --init`), enforce them in the edit loop and in CI |
+| [contracts.md](docs/contracts.md) | Declare invariants in `.ask/contracts.yml` (or derive them with `ask verify --init`), enforce them in the edit loop and in CI — and adjudicate a finding as *not a defect here* in `.ask/waivers.yml` |
 | [baseline-ci.yml](docs/baseline-ci.yml) | Capture an architectural baseline per release, so the series exists when you want to read it |
 | [posture.md](docs/posture.md) | What a profile set actually wires — down to which endpoints its filter chain permits — and what could not be decided |
 | [migrate-check.md](docs/migrate-check.md) | Migration rule catalogue (MIG-001..043) + Hibernate stratification |

{sourcecode-5.2.0 → sourcecode-5.3.0}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.2.0-blue)
+![Version](https://img.shields.io/badge/version-5.3.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -88,7 +88,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.2.0 — and, on a build that has aged,
+ask version                    # ask 5.3.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -157,6 +157,29 @@ ask verify /path/to/repo --init --dry-run
 ask risk /path/to/repo
 ```
 
+**And the three that answer questions this repository does not contain the answer to.**
+The profile set is decided by a deployment artefact, the consumers are other repositories,
+and *since when* is a fact about history — each one is a join of things already measured,
+and each one leaves the previous answer untouched when it cannot decide:
+
+```bash
+# The artefact that decides the profile set — Kubernetes manifest, compose file, WebLogic
+# deployment plan, Dockerfile, dotenv, launch script. Every answer is then given under the
+# set it names, with the file:line that decided it. An artefact that decides nothing (a
+# placeholder, two artefacts that disagree) leaves the repository's own verdict as it was.
+ask posture /path/to/repo --profile-from k8s/deployment-prod.yaml
+
+# Of the routes a readable rule leaves open: which ones a consumer actually calls (work),
+# and which ones nobody calls (surface to delete instead of guard). Reads TypeScript/JS and
+# Java consumers, only where the verb and the path are written at the call site.
+ask endpoints /path/to/repo --consumer ../web-client --consumer ../partner-api
+
+# Since when. Walks the commit series, runs the analyses that already ship on a read-only
+# materialisation of each sampled tree, and publishes where a number MOVED — with the commit
+# it was observed at and the window it could have happened in.
+ask timeline /path/to/repo --since v1.0 --watch posture,data-exposure
+```
+
 Then the everyday loop:
 
 ```bash
@@ -211,7 +234,7 @@ Blast radius from a class or interface — reverse dependencies, through Spring
 
 ### 3 · Architecture Intelligence
 The system map: module graph, dependency views, REST surface, per-class summaries, and a symbol-level IR for downstream tooling.
-`ask export` · `ask repo-ir` · `ask endpoints` · `ask explain`
+`ask export` · `ask repo-ir` · `ask endpoints` · `ask explain` · `ask timeline` (*experimental* — the same views over the commit series: when a number moved, and in which window)
 → [reference](docs/USER_GUIDE.md#core-commands)
 
 ### 4 · Migration & Modernization
@@ -242,6 +265,16 @@ parse and publishes the worst. A field audit closed those five hops by hand with
 the flag existed.
 `ask posture . --resolve-environments`
 
+**`--profile-from` closes the loop.** `--resolve-environments` reads what the *repository*
+says; the artefact that actually decides the profile set usually lives outside it. Name it —
+Kubernetes manifest, compose file, WebLogic deployment plan, `Dockerfile`, dotenv, launch
+script — and every answer is given under the set it sets, with the `file:line` that decided
+it. Undecidable-first, so pointing it at the wrong file costs nothing: a placeholder, an entry
+with no value, or two artefacts that disagree decide **nothing** and leave the repository's
+own verdict byte-for-byte as it was. The process environment still outranks the file, and the
+payload says so.
+`ask posture . --profile-from k8s/deployment-prod.yaml`
+
 Unresolved is a first-class outcome: a condition the resolver cannot decide is reported as a
 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.**
@@ -257,8 +290,12 @@ field case: a defect both `spring-audit` and `impact-chain` called *medium* comp
 **high (8.06)** once *reachable unauthenticated* and *writes to the database* are in it.
 The last two factors describe the input path: a query assembled by concatenation, a bounded
 HTTP-input-to-query-sink path when ASK can prove one, and a route accepting a body with no
-declared constraint. General taint remains `NC-001` and is published in the payload's own
-`non_coverage` block.
+declared constraint. **The sink family a MyBatis codebase actually uses is covered too**: an
+annotated HTTP input reaching a statement that splices it into the SQL with `${...}` is a
+three-state verdict — `reaches` (with the trace), `does_not_reach` (stated only where the call
+sites were found) or `undecidable` — and only the first moves the factor. The census is
+published beside the rows, so the multiplier is auditable rather than asserted. General taint
+remains `NC-001` and is published in the payload's own `non_coverage` block.
 `ask risk .` · `ask risk . --min-band high` · `ask risk . --limit 10`
 → [reference](docs/USER_GUIDE.md)
 
@@ -284,7 +321,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` |
+| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `enrich` · `audit-report` · `data-exposure` · `migrate-recipe` · `archetype` · `timeline` |
 | **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
@@ -300,18 +337,18 @@ 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 |
-| `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; `--table --rule SEC-008 --band high --top-n 20` gives audit triage without `jq` |
+| `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` |
 | `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 |
-| `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 |
+| `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 |
 | `impact` / `impact-chain` | core | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
 | `pr-impact` | core | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
-| `verify` | core | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2 |
+| `verify` | core | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2. `.ask/waivers.yml` adjudicates a finding as *not a defect here* (stable id + required reason, optional expiry) so a reviewed row stops holding the gate red — a baseline records accepted debt, a waiver says it was never a defect |
 | `verify-edit` | supported | did the working-tree edits change runtime behaviour | semantic diff gate for the edit loop |
 | `--compact` / `--agent` | — | bounded structural context for an agent | flags of the root command, not commands: not tiered |
 | `onboard` / `explain` / `cold-start` | supported | orientation in an unfamiliar repo; per-class summary; bootstrap snapshot | |
@@ -322,6 +359,7 @@ from it.
 | `validation` | supported | request-body validation coverage and gaps | |
 | `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 |
 | `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 |
@@ -366,7 +404,7 @@ reading JSON sees the same boundary a buyer reads here.
 
 | Not covered | Why | What answers it |
 |---|---|---|
-| **General request-input-to-sink taint analysis.** | `ask risk` includes a bounded slice for annotated HTTP parameters, positional calls in repository Java sources and known query sinks. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the bounded slice, whether an annotated HTTP input reaches a known concatenated query sink. |
+| **General request-input-to-sink taint analysis.** | `ask risk` includes two bounded slices for annotated HTTP parameters and positional calls in repository Java sources: known query sinks, and MyBatis statements that splice a value into their SQL. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the two bounded slices, whether an annotated HTTP input reaches a known concatenated query sink or a spliced SQL statement — the latter with a three-state verdict that says `undecidable` rather than clearing a route it could not follow. |
 | **Secrets outside Java, Spring configuration and the deployment descriptors — a Helm value, a CI variable file, a shell script.** | The file population this analyzer reads is the Java source, the Spring configuration convention and the descriptors it already parses to resolve an environment. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. Narrowed by CL-10: a credential stored in `web.xml` or a Spring XML context IS reported (SEC-007), because those files were already being read. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
 | **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
 | **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |
@@ -376,7 +414,7 @@ Two more boundaries worth stating in the same voice:
 | Not covered | Why | What answers it |
 |---|---|---|
 | **Applying a migration — nothing here edits source.** | This is the diagnosis layer: it measures what must change and what each change would reach. Rewriting code is an execution problem with an established executor, and duplicating it would mean maintaining a second, worse one. | OpenRewrite. `migrate-check` publishes the recipe each finding carries (`recipes[]`), which is the input that executor takes. |
-| **What the process environment sets at start-up — the profile set, properties and secrets a container is given.** | Nothing in a repository can observe the environment of a process that has not started. A value read from a file here is the default the repository ships, never a guarantee of what runs. | `ask posture --resolve-environments` reads every artefact in the repository that names the profile set, says when none of them decides it, and ranks the admissible sets by what each leaves open. |
+| **What the process environment sets at start-up — the profile set, properties and secrets a container is given.** | Nothing in a repository can observe the environment of a process that has not started. A value read from a file here is the default the repository ships, never a guarantee of what runs. | `ask posture --resolve-environments` reads every artefact in the repository that names the profile set, says when none of them decides it, and ranks the admissible sets by what each leaves open. `--profile-from <file>` goes one step further and reads the deployment artefact itself, which is where that decision is actually written — still a file, so the process environment still outranks it, and the payload says so. |
 
 
 And one about the endpoint surface itself:
@@ -522,7 +560,7 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | Doc | What it covers |
 |-----|----------------|
 | [USER_GUIDE.md](docs/USER_GUIDE.md) | Full command reference, flags, output schema, workflows |
-| [contracts.md](docs/contracts.md) | Declare invariants in `.ask/contracts.yml` (or derive them with `ask verify --init`), enforce them in the edit loop and in CI |
+| [contracts.md](docs/contracts.md) | Declare invariants in `.ask/contracts.yml` (or derive them with `ask verify --init`), enforce them in the edit loop and in CI — and adjudicate a finding as *not a defect here* in `.ask/waivers.yml` |
 | [baseline-ci.yml](docs/baseline-ci.yml) | Capture an architectural baseline per release, so the series exists when you want to read it |
 | [posture.md](docs/posture.md) | What a profile set actually wires — down to which endpoints its filter chain permits — and what could not be decided |
 | [migrate-check.md](docs/migrate-check.md) | Migration rule catalogue (MIG-001..043) + Hibernate stratification |

{sourcecode-5.2.0 → sourcecode-5.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "5.2.0"
+version = "5.3.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-5.2.0 → sourcecode-5.3.0}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "5.2.0"
+__version__ = "5.3.0"

{sourcecode-5.2.0 → sourcecode-5.3.0}/src/sourcecode/cache_model.py

@@ -368,6 +368,7 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "`no_ris` instead of a snapshot.",
                  "0.2 s either way", analysis_class="core", cold_seconds=0.2, warm_seconds=0.2,
                  field_seconds=0.4, field_cache_state="mixed", field_measured_version="5.1.0"),
+    CommandCache("timeline", (), "none", False, "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.", analysis_class="ir"),
     CommandCache("trend", (), "none", False, "Reads stored baseline artifacts from disk; analyses no source, so no cache layer applies. Same command as `baseline trend`.", analysis_class="none"),
     CommandCache("baseline", ("parse",), "shared", False,
                  "`capture`/`diff`/`trend` over architectural metrics. The field figure is `capture`, "