sourcecode 4.1.0__tar.gz → 4.5.0__tar.gz

{sourcecode-4.1.0 → sourcecode-4.5.0}/CHANGELOG.md

@@ -2,6 +2,415 @@
 
 ## [Unreleased]
 
+## [4.5.0] — 2026-08-03
+
+Minor: the servlet-mounted HTTP surface is admitted as a population of its own
+(CL-12's remaining half), the output envelope is published as an open
+specification (M11's first deliverable), and a specification under `docs/` stops
+being counted as a test source. Nothing published is removed and no exit code
+moves; `--servlets` is opt-in and `endpoints.total` is byte-identical with and
+without it.
+
+### Fixed
+
+- **A specification under `docs/` was classified as a test source.** `spec/` means a
+  test suite in the RSpec/Jasmine sense and the opposite under a documentation root,
+  where a *specification* lives — and the file that exposed it is this release's own
+  `docs/spec/envelope-v1.md`, which landed in the test population of the tool's own
+  metrics the moment it was published. Fixed in the authority (`test_sources`) and in
+  the shared helper (`path_filters`); the segment keeps its meaning everywhere else, and
+  `docs/tests/` is still tests. Found by the suite, not by the field.
+
+### Added
+
+- **`envelope-v1` published as an open specification** (`docs/spec/envelope-v1.md`,
+  roadmap M11). Audit #8 named the output envelope the product's most underrated
+  strategic asset, and the argument is asymmetric: a format that makes `basis`,
+  `limitations`, `unit` and `denominator` mandatory is one an incumbent cannot adopt
+  without confessing what its own output leaves out. The document specifies the four
+  properties an answer must have — provenance, a named unit, a stated basis with
+  `unknown` never spelled `0`, and declared non-coverage — plus the compatibility
+  promise (within `envelope_version: 1`, fields are only ever added). **The field table
+  is generated from the same JSON Schema `ask schema envelope-v1` prints**, and the
+  battery fails when the two disagree: a specification that has drifted from the
+  implementation is worth less than none, because the people asked to adopt it check.
+
+### Added
+
+- **`ask endpoints --servlets` — the admission half of CL-12 / NC-007.** 4.2.0 declared
+  that the endpoint population is Spring handler mappings and that a servlet mapped in
+  `web.xml` or registered as a `ServletRegistrationBean` is reachable HTTP surface in
+  none of those counts; this lists it, as a population of its own with the URL pattern,
+  the servlet class and the declaring file. **It is never merged into
+  `endpoints.total`** — the two count different things, and widening a published figure
+  moves every ratio keyed on it. Measured: openmrs-core **7 patterns against 1 Spring
+  endpoint**, alfresco-community-repo **11**, including `/api/*` served by a WebScript
+  servlet. The flag is what NC-007 now names, through the remedy registry, so a rename
+  breaks the build rather than the reader. Nothing here resolves what guards those
+  patterns and the block says so.
+
+## [4.4.0] — 2026-08-03
+
+Minor: M10.5 closes except for the one item blocked on a population nobody in the
+battery has. Two additions, both additive — a new experimental command
+(`ask migrate-recipe`) and a new opt-in block on `endpoints` (`--client-usage`).
+No published field is removed, no default moves, and neither runs unless asked
+for.
+
+### Added
+
+- **`ask endpoints --client-usage` — which of these routes anything in this repository
+  actually calls** (roadmap M10.5 item 4). On a large surface the cheapest reduction of
+  exposure is deleting API nobody calls, and in a monorepo the caller is checked in
+  beside the callee. The join reads the TypeScript/JavaScript client, extracts the calls
+  whose verb and path are written at the call site, neutralises variable segments on both
+  sides (`${bankId}` and `{bank-id}` are one position with two naming conventions) and
+  reports three counts: routes called here, routes nothing here calls, and **client calls
+  matching no route** — the decisive direction, a request this repository's own front end
+  makes and its server does not serve. Measured on open-banking-gateway: 268 client files,
+  31 calls, **30 of 39 routes called, 9 not, 11 calls matching nothing**.
+  - It is a **floor** and says so (`direction: under_reports`, new row `NC-009`): a route
+    with no call site here is a candidate for deletion, never dead API, because nothing in
+    a repository can observe the consumers it does not contain.
+  - A URL built at run time is published under `unresolved_call_sites` with its file and
+    line, never passed over — it is precisely the call that would make a live route look
+    dead, and a call the extractor could not even *see* would shrink the census silently.
+  - `--client-dir` points at the client when it is not the whole repository. The join runs
+    over the population the filters chose, for the same reason the exposure census does.
+
+- **`ask migrate-recipe` — the migration report in the form the executor takes**
+  (roadmap M10.5 item 5 / M8.5, experimental). `migrate-check` already names the
+  OpenRewrite recipe each finding carries (296 of 309 on openmrs-core) and a reader
+  still had to copy them out of a JSON payload by hand — field evaluation #4's verdict
+  on that gap was *"el informe muere en un cajón; el codemod se convierte en PRs"*. The
+  command emits the declarative composite recipe naming exactly those recipes, the
+  artifact coordinates derived from their packages, and the invocation for the build the
+  repository declares (Maven or Gradle). It writes nothing without `--write`, so an audit
+  of somebody else's repository can run it; `--write` refuses to replace an existing
+  `rewrite.yml` without `--force`. **Nothing here edits source** — that is NC-005's
+  position, not a gap: OpenRewrite is the executor and this is its input.
+  - The recipe list comes from the findings, never from a catalogue of what OpenRewrite
+    can do: a recipe nobody's finding asked for would rewrite code nobody measured.
+  - Every finding with no recipe is published under `manual_remainder`. Measured on
+    BroadleafCommerce: **25 blocking findings in product code and not one automatable**,
+    which is an answer, not an empty result — and the reason an empty recipe list prints
+    *no* runnable command, because `mvn … rewrite:run` over nothing is a green executor
+    run that reads as "the migration is automated".
+  - Advisory hygiene is excluded by default (`--include-hygiene` opts in): on openmrs-core
+    it takes the population from 125 findings to 309 and adds `JavaTimeAPIs`, and a
+    migration diff that also modernises date handling cannot be reviewed as one change.
+  - The coverage block names **both** populations — its own and `migrate-check`'s narrower
+    `blocking_count` (125 against 114 on openmrs-core) — because two populations under one
+    name is the defect this project keeps finding in its own output.
+
+## [4.3.0] — 2026-08-03
+
+Minor, not a patch: two commands are new (`ask enrich`, `ask data-exposure`), the
+composed risk model gains two factors, and `ask verify` writes a file where it
+wrote none — every one of them additive, none of them removing a published field
+or moving an exit code. A pipeline that reads this release the way it read 4.2.0
+gets the same answers, plus blocks it can ignore.
+
+### Added
+
+- **`ask baseline capture --auto` — an architectural history that does not depend on
+  somebody remembering** (roadmap M10.5, head of the milestone). The snapshot has
+  shipped since D5; the *series* is the asset a competitor cannot backfill, and in
+  every repository measured so far its length is zero, because capture is a command a
+  human has to type. `--auto` is the form a pipeline can keep: it captures one baseline
+  per commit, keeps an already-captured commit instead of relabelling it, refuses to
+  file a tree with uncommitted changes under the commit it would be stored as, and
+  **exits 0 whatever happens** — a build never goes red because a snapshot could not be
+  taken. Every outcome names itself (`captured` / `skipped` with the reason and a
+  sentence of effect), so a pipeline log says which happened rather than going quiet.
+  A skip costs no analysis: the decision is taken before the IR is built, so the common
+  case in a per-push job is ~0.2 s against 1.8 s for a capture. New authority
+  `sourcecode/baseline_autocapture.py`; `docs/baseline-ci.yml` now captures per merge
+  as well as per tag.
+- **`ask data-exposure` — which routes can carry the data you labelled, and who
+  reaches them** (roadmap M10.5 item 3, experimental). Nothing here detects sensitive
+  data: a label is a judgement about a domain, a field named `dni` is a national
+  identifier in one repository and a column name in another, and the engine never
+  branches on a name (VAI). It is declared once under `dataLabels` in
+  `sourcecode.config.json`; everything after that is measured over authorities that
+  already exist — the call reach `impact-chain` walks, the endpoint security surface
+  `risk` weighs, the profile resolution `posture` publishes (`--profile`). Two evidence
+  classes, published apart and never added together: `signature` (the handler names the
+  labelled type in its own signature) and `call_reach` (the chain reaches it — a
+  supremum, not a proof, because the mapping in between is not modelled: NC-008).
+  Measured: petclinic labelling `Owner#telephone` → **7 routes by signature**;
+  BroadleafCommerce labelling `Customer` → **6 by call reach and none by signature**,
+  because those controllers return view names. A repository that declared nothing is
+  `answered: false`, never zero exposed routes, and a declared type the graph never
+  resolved is named with the note that this is not evidence it is unexposed.
+- **A request handler declares types too.** `_extract_class_type_refs` enumerated
+  `symbol_kind == "method"`, and a handler is classified `endpoint` at emission (a
+  factory method `bean`), so the class-scope type surface contained **no controller
+  signature anywhere in a repository**: `structural_references_to_type("Owner")` on
+  petclinic returned 3 atoms, none of them a route that takes an `Owner` as its request
+  body, and "which routes accept or return this type" answered nothing while looking
+  like an answer. Now 10 atoms, 7 of them handler signatures. Same shape as the F.4-1
+  body-surface seam, one scope up; `member_kind` still publishes the kind the symbol was
+  classified with.
+- **The history answers from the repository path.** `ask trend .` and
+  `ask baseline trend .` now take either a repository or a directory of baselines, and
+  `ask baseline diff .` defaults to the newest point in that repository's own history
+  instead of requiring `--baseline <file>`. Capture writes to `<repo>/.ask/baselines`,
+  so making the reader name the storage directory was the same friction that kept the
+  series empty. An explicit directory (the `--dir` case) is unchanged, and a repository
+  with no history gets an error that names how to start one. New
+  `architectural_baseline.latest_baseline_path`, ordered exactly as the trend series is
+  ordered so "the last point" and "the base of a default diff" cannot disagree.
+- **`ask verify` carries the history for free.** The gate is the run that already happens
+  on every push and already builds the IR a baseline is extracted from, so where a
+  repository keeps `.ask/baselines` the gate adds the current commit to it and publishes
+  what it did under `architectural_history` — on every run, including the ones that
+  captured nothing, because a series that silently stopped growing is invisible until the
+  day somebody needs it (I-8). Measured on BroadleafCommerce: 3.9 s with the capture
+  against 4.0 s without, i.e. inside the noise; eureka 1.8 s against 0.8 s (its IR is
+  smaller, the extraction is not). The passenger cannot move the gate: the verdict, the
+  exit code and every other field are identical with and without it, and an exception
+  inside it is swallowed. `ASK_BASELINE_AUTOCAPTURE=0/1` overrides in both directions.
+  - ⚠One measured cost stated rather than hidden: a baseline is ~730 KB on a 3 300-file
+    monolith, because it stores the full endpoint surface and fan-in map so a later
+    `baseline diff` is faithful. A point per merge is a megabyte-scale history; a point
+    per release is not. `--dir` sends them outside the repository.
+  - ⚠Found by the battery, not by the field: the first capture writes an untracked file
+    **inside the repository**, so a plain `git status --porcelain` check would have
+    reported a dirty tree from then on and every later run would have skipped — a
+    history of exactly one. The dirtiness question excludes this tool's own footprint
+    (`.ask/`) and nothing else, because everything else is what the baseline measures —
+    and the second half of that came from eureka, where `verify --init` writes
+    `.ask/contracts.yml` and, counted as a modification, would stop the history from
+    ever starting.
+- **`ask enrich --sarif <log>` — somebody else's detection, ranked by what this
+  repository does with it** (roadmap M10, first deliverable). This product does not
+  detect injection, CVEs or secrets and says so in every security payload (NC-001,
+  NC-002); the scanners that do have no bean graph, no profile model and no endpoint
+  id they share with anything, so their output is a list nobody can order. `enrich`
+  reads a SARIF 2.1.0 log from Semgrep, CodeQL or Trivy and runs the **same
+  composition** `ask risk` runs over each finding — same axes, same weights, same
+  `RiskComposer` — with one difference: `defect_severity` is the scanner's own
+  verdict (`security-severity` when the tool published one, `level` otherwise),
+  carried through with the scanner named as its authority. Nothing re-rates,
+  confirms or contradicts a finding. Results sharing (tool, rule, symbol) are one
+  defect with several witnesses; a result the join could not place — a file outside
+  the population this build read, a line with no declaration above it — is published
+  under `unresolved` with the reason, never dropped.
+- **The CVE half of the same command: a dependency finding is joined through the
+  coordinate, not through a line.** A result located on `pom.xml` or
+  `build.gradle` is about a library, so the coordinate is read back out of the
+  manifest the scanner named and the reach is the worst of the types that import
+  it — *of forty vulnerable dependencies, which ones does an unauthenticated route
+  actually reach?* Importers are found from the IR's existing `imports` edges, by
+  the coordinate's group id or by its artifact id as a package segment, and each
+  row publishes which basis found them. A library nothing imports is `unresolved`
+  and never "unreachable": reflection, a service loader and use through another
+  dependency all leave no import edge. Both kinds rank in one list, because a CVE
+  in a reachable library and an injection finding in a handler are the same
+  question to whoever decides what to fix first.
+- **`--profile <set>` on `ask risk` and `ask enrich` — profile context per finding**
+  (M10 exit criterion). The access axis stops answering for *the repository as
+  configured* and answers for *that deployment*: `posture` resolves the conditional
+  bean graph and the request chain under the named set, through a new published
+  seam (`posture.endpoint_access_under`, `posture.access_verdict`), so a composed
+  row and a `posture` run can never disagree about the same profile set. A decision
+  resolves an endpoint the repository-wide surface left at `coverage_unknown`, in
+  either direction — measured on a fixture, one defect scores 11.52/`open` under
+  `dev`, 8.06/`unknown` with no set named, and 5.76/`protected` under `prod`. When
+  both authorities decided, the worse of them wins, per endpoint.
+- **`ask risk` gains a fifth factor: `query_construction`** (roadmap F.4-1). The
+  field asked the question this answers the structural half of — *"con 618 HQL
+  concatenados, ¿alguno concatena entrada de request?"* Following request input to
+  a query is dataflow, is declared out of scope in NC-001, and stays there. What
+  is publishable without it is the adjacency: this defect's own code assembles a
+  query string by concatenation, and the four factors beside it already say whether
+  that code is reachable, unauthenticated and writing. Read from the α
+  argument-shape atoms the IR already carries (`dynamic_argument_surface`) — no new
+  analysis, one pass, joined per defect. `not_observed` means the shape was absent
+  from the body facts; it is never a claim that a query is safely parameterised.
+- **…and a sixth: `input_constraints`** — the other half of the same field question
+  (*"1 201 bodies sin validación"*). Joined by route against `validation`'s gap
+  list: `absent` means one of the endpoints reaching this defect accepts a request
+  body with no declared constraint, taking the worst of the reached routes for the
+  reason the auth axis does. `ask risk` now publishes the `non_coverage` block too,
+  because two axes describing the input path, composed with an open access verdict,
+  read as *injection* unless the payload states that no dataflow was followed.
+
+### Fixed
+
+- **`validation` counted handlers that take no argument as body endpoints.** The
+  body surface was the verb alone (POST/PUT/PATCH) and the declared limitation said
+  the parameter list was not captured. It is now captured (`_handler_params`) and
+  read in the negative direction only: an empty parameter list proves no body can
+  bind. A handler whose parameters are all path or query values still counts, and
+  the limitation says so.
+
+- **The α argument-shape surface was blind to every controller body.**
+  `dynamic_argument_surface` walked `kind="method"` and `kind="constructor"` symbol
+  nodes; a request handler is a `kind="endpoint"` node. The owner population is now
+  the body-fact layer's own (`ContextGraph.body_owners()`).
+
+### Changed
+
+- `severity_effective` in `ask risk` can now be larger for a row whose code
+  concatenates a query. Every factor's neutral value is 1.0, so a new axis only
+  ever moves a row **up**: no band a reader has already acted on is demoted by
+  this release.
+
+## [4.2.0] — 2026-08-03
+
+Minor, not a patch, by this project's own criterion: two published figures move
+and a verdict changes, so a pipeline reading either can change colour.
+`posture --resolve-environments` answers `NOT DECIDED IN THIS REPOSITORY` where
+it answered `artefacts_disagree` on a repository whose build properties nothing
+consumes (C1-22), and `ask risk` publishes defects where it published findings,
+so `total_defects` and `by_band` move (C1-23) — 20 → 15 on BroadleafCommerce.
+`risk` also drops `rule_id` for `rule_ids`: it is in the `experimental` tier,
+whose published promise is exactly that its shape may change in a minor.
+
+Field evaluation #9 (8/10, same 3 337-file monolith as #6–#8) opened nine rows
+and this release closes seven of them. The two left open are open on purpose:
+`C3-39` needs a Windows runner before it needs a fix, and `P-7` is a pricing
+decision. Every complaint was re-measured against HEAD before a row was written
+— five reproduced, one was half false, one was not reproducible here, and one
+was a capability that already shipped.
+
+### Added
+
+- **`ask posture --diff-ref <base>:<head>` and `--since <ref>` — one profile set,
+  two git refs** (roadmap M10.5 item 1). `--diff` holds the tree fixed and moves
+  the profile set; this holds the profile set fixed and moves the tree, which is
+  the question a pull request asks: *does this change what a client can reach
+  without authenticating?* `--since` compares a ref with the working tree,
+  uncommitted edits included. Both refs are read with `git archive`: nothing is
+  written to the repository, no worktree is created and the index is not touched.
+  `docs/posture.md` had declared this as the one requested extension with no
+  feature behind it.
+- **`--fail-on opened|any|never` — the gate half.** Default `never`, so no
+  invocation that worked yesterday changes colour today; `opened` exits 1 when a
+  request a readable rule leaves reachable unauthenticated was not one before.
+  The payload is emitted before the exit code, because a red pipeline with no
+  statement of what opened is a gate nobody keeps. It requires a ref comparison —
+  gating a single run would gate on pre-existing debt, which is `spring-audit --ci`.
+- **`endpoint_request_identity` registered as a fact** (ADR-0008 R11,
+  `sourcecode.canonical_ir:request_identity`). The comparison unit is the request
+  (`METHOD path`), not the endpoint id, which carries the controller FQN and the
+  handler symbol and therefore changes when a handler moves between classes
+  without the URL changing. `contract_diff` re-derived the same identity and now
+  binds to the authority. Path-variable patterns are deliberately **not**
+  normalised: `{id:.*}` and `{id:[^0-9].*}` are different URLs to a caller, and
+  one field repository moved 93 requests with exactly that edit in a single commit.
+
+### Added
+
+- **`ask endpoints --compact` — the census instead of the rows** (C2-22, field
+  evaluation #9). Asked how exposed a repository was, the command answered with
+  1.9 MB of JSON for 3 574 endpoints and no summary mode, and the evaluator
+  aggregated it by hand. Every answer now carries an `exposure` block — counts by
+  method, by security policy, by controller and by first path area — and
+  `--compact` returns it without the rows, declaring what it dropped. Two rules
+  it obeys against itself: the census is measured over the population the filters
+  chose and never over what `--limit` left rendered, and every ranked rollup
+  states its own total when it cuts. Measured on BroadleafCommerce: 95 KB → 11 KB,
+  every count unchanged. (The other half of the complaint is recorded as false:
+  `spring-audit` has shipped `--compact`, `--min-severity` and `--scope` for
+  releases.)
+
+- **NC-007 — the endpoint population is declared** (CL-12, field evaluation #9).
+  `endpoints` projects Spring handler mappings; a servlet declared in `web.xml`
+  or registered as a `ServletRegistrationBean` is reachable over HTTP and is in
+  no part of that model. Six published non-coverage rows are exactly what let a
+  reader treat the list as the whole HTTP surface, and the evaluation lost a
+  monitoring console that way — at a path behind the credential the same run
+  reported as SEC-007. The row is published in the `endpoints` payload and inside
+  `posture.endpoints`, because the reader who counts open requests is reading
+  `posture`. Admission of a servlet surface is deliberately **not** in this
+  change: it is a second population and merging it into `endpoints.total` would
+  move a published count and every ratio keyed on it.
+
+### Fixed
+
+- **A reach figure that did not name its scope** (C2-23, field evaluation #9).
+  `risk` reported `endpoints_reached: 1` for a symbol whose class `impact-chain`
+  said reached 8 — both correct, both documented, in two payloads, so reconciling
+  them cost the reader three unit notes. Each row now carries
+  `endpoints_reached_basis`: what the figure is a reach *of* (a defect sits at the
+  symbol that carries the remedy, so a method-level defect walks from the method)
+  and, where that is narrower than a class, the command that answers the wider
+  question. The relationship is asserted by measurement rather than stated in
+  prose.
+
+- **The remedy registry now follows the status, not only the limitation** (C4-13,
+  field evaluation #9 — the sixth appearance of the C4 shape). The evaluation met
+  `verify`'s `contract_count: 0` → `unverified` → exit 2 under a read-only
+  constraint, concluded the command was unusable and asked for a `--dry-run` that
+  shipped in 3.7.0. The state named one next move and the reader could not take
+  it. `Remedy` gained `also` (the further options an answer needs — a remedy is an
+  invocation, not a flag), the new entry is `ask verify . --init --dry-run`, and
+  the `unverified` reason names both forms. The guard grew with it: every option
+  of an invocation must be accepted by the command it names, and the README check
+  matches a line carrying the command with all of its options, so a front page
+  that lists `--init` and omits `--dry-run` fails the build.
+
+- **The hub-class guard contradicted the payload beside it** (C2-21, field
+  evaluation #9). It printed *"symbol has > 500 direct callers"* while the same
+  run published 215 of them on openmrs-core's `Context`: the guard trips on
+  caller **reference sites** (method-level keys included) and the payload
+  publishes caller **classes**, so the stated reason was checkably false while
+  the decision was right. `caller_reach.bfs_callers` now returns the population it
+  read, and the warning names it with its unit next to the class count it takes
+  from `caller_metrics.caller_classes` — *"792 caller reference sites … exceed the
+  cap of 500 … The 215 direct caller classes this run publishes stay exact"*.
+
+- **`ask risk` ranked findings under the label `spring-audit` deduplicates**
+  (C1-23, field evaluation #9). One SEC-004 appeared three times for three call
+  sites in one class and `by_band` was an observation census under a defect
+  label — measured on BroadleafCommerce, 20 rows over 15 distinct `defect_id`
+  beside `spring-audit`'s own 15 defects / 20 findings. `build_risk` now iterates
+  `defect_identity.group_by_defect`, so one row is one thing to fix and both
+  commands report the same count (asserted against each other, not against a
+  literal). Nothing is dropped: `witness_count` and `witness_sites` carry where
+  each observation was seen, `total_findings` publishes the census under its own
+  name, and `rule_id` becomes **`rule_ids`** because one defect can be witnessed
+  by TX-001 and TX-006 at once and a singular field would have to pick one.
+  `severity` is the strongest across the witnesses, and
+  `factors.defect_severity.basis` says so.
+
+- **A Maven build property was published as a runtime activation** (C1-22, field
+  evaluation #9 — the row it called the most expensive in its report). Two
+  `<properties>` entries setting `spring.profiles.active` made
+  `posture --resolve-environments` answer `artefacts_disagree` — *"different
+  deployments, pick one"* — on a repository where **nothing activates a profile at
+  run time**. The honest verdict, which the command already implements, is
+  `NOT DECIDED IN THIS REPOSITORY`: the default set applies and the permissive
+  profile wins, which is exactly where that audit's most severe finding lived. The
+  command turned a fail-open into a deployment ambiguity, in the scenario it is
+  sold for. A build property is now admitted as an activation only when a resource
+  in the repository consumes it (`@spring.profiles.active@`, or
+  `${spring.profiles.active}` where the build declares its resources filtered).
+  Unconsumed, the value is kept — it is still the profile set a build of it would
+  produce, so the worst case keeps ranking it — and carries the reason it decides
+  nothing, beside a `build_properties_not_consumed` count. The positive control is
+  half the battery: before this, the case where the property genuinely does decide
+  produced the identical verdict, which is how the defect stayed invisible. No
+  movement on the field repositories.
+
+- **A rule that disappeared was reported as protection gained.** Found by the
+  negative control, not in the field: delete a security configuration and every
+  request it decided goes `permit_all` → undecided, which a two-bucket
+  opened/closed split published as *"2 requests no longer reachable
+  unauthenticated"*. Four buckets now: `opened` and `closed` (attributable to the
+  change), `no_longer_decided` (coverage lost) and `now_open_previously_undecided`
+  (our reading moved, not necessarily the system — it never turns a gate red on
+  its own). Requests undecided on either side are counted in
+  `access_not_decided_either_side`, the delta publishes `direction`, and
+  `gate.reading` states the floor (I-8).
+- **`git_checkout` no longer offers a remedy half its callers do not have.** The
+  not-a-repository message told every caller to "pass two checkouts positionally";
+  `posture` takes none. The message states the fact and each command supplies its
+  own hint.
+
 ## [4.1.0] — 2026-08-03
 
 Minor, not a patch, and the criterion is this project's own: a new rule can trip

{sourcecode-4.1.0 → sourcecode-4.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.1.0
+Version: 4.5.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
@@ -156,8 +156,12 @@ ask posture /path/to/repo --resolve-environments
 # writing it, and populate .ask/contracts.yml from the measurement instead of by hand.
 ask verify /path/to/repo --init
 
-# What each defect actually costs once reach, access and write effect are in it:
-# severity × reachability × auth_verdict × write_effect, ordered, every factor traceable.
+# Same derivation under a read-only constraint: prints what it would declare and
+# writes nothing — the form an audit of somebody else's repository can run.
+ask verify /path/to/repo --init --dry-run
+
+# What each defect actually costs once reach, access, write effect and the shape of
+# the input path are in it — ordered, every factor traceable to the command that owns it.
 ask risk /path/to/repo
 ```
 
@@ -230,6 +234,9 @@ What a profile set **actually wires**: which conditional beans register, which d
 `ask posture` · `ask posture --diff dev:prod` · `ask posture --property k=v`
 → [posture.md](docs/posture.md)
 
+**`--diff-ref` makes it a gate instead of a report.** `--diff` moves the profile set; `--diff-ref origin/main:HEAD` (or `--since origin/main`, which compares a ref with the working tree) moves the *tree* under one profile set and answers *did this branch open an endpoint*. `--fail-on opened` exits 1 when it did. Both refs are read with `git archive` — nothing is written to the repository. The comparison is keyed on the request (`METHOD path`), counts requests only one side serves, and never reports a rule that disappeared as protection gained.
+`ask posture . --since origin/main --fail-on opened`
+
 **`--resolve-environments` carries it past the edge of the repository.** Every answer above
 is conditional on a profile set, and which set runs is decided by the deployment. This flag
 reads every artefact in the tree that can set `spring.profiles.active` — Maven/Gradle,
@@ -247,12 +254,16 @@ guesses is a confident security falsehood — the worst failure mode this tool h
 ### 5c · Composed Risk *(experimental)*
 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`. The
-product of the published factors **is** the published score — decomposable to the four
+`severity_effective = defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`. The
+product of the published factors **is** the published score — decomposable to the six
 figures and the authority behind each — and an axis this build cannot measure is `unknown`,
 weighted 1.0 and named in `blind_axes` rather than silently treated as safe. Measured on a
 field case: a defect both `spring-audit` and `impact-chain` called *medium* composes to
 **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 route
+accepting a body with no declared constraint. They are **adjacencies, not dataflow**: no
+value is followed from a request to a sink, which is `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)
 
@@ -278,7 +289,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` · `posture` · `archetype` |
+| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `enrich` · `data-exposure` · `migrate-recipe` · `posture` · `archetype` |
 | **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
@@ -295,7 +306,10 @@ from it.
 | Command | Tier | Answers | Note |
 |---|---|---|---|
 | `posture` | experimental | 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 and write effect are in it | `defect_severity × reachability × auth_verdict × write_effect`; every factor names its authority |
+| `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 |
+| `enrich` | experimental | another scanner's SARIF findings, ranked by what this repository does with them | `--sarif <log>`; the same composition as `risk`, with the scanner as the severity authority |
+| `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) |
 | `endpoints` | core | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators) |
 | `spring-audit` | core | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment` |
 | `migrate-check` | core | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan |
@@ -310,7 +324,7 @@ from it.
 | `review-pr` / `fix-bug` / `prepare-context` | supported | diff review, symptom triage, task-shaped context | |
 | `plan` / `compare` / `delta` / `contract-diff` | supported | what to review for a change; candidates by measured cost; outcome of a change; public-contract break | no verdicts, measured cost only |
 | `validation` | supported | request-body validation coverage and gaps | |
-| `baseline capture\|diff` · `trend` | supported | versioned architectural metrics over time; `ask trend <dir>` reads the series | 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`. Automate it: [baseline-ci.yml](docs/baseline-ci.yml) |
+| `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 | |
 | `archetype` | experimental | evidence-based architectural archetype | |
 | `rename-class` / `chunk-file` | supported | word-boundary Java rename; split a large file for an agent | |
@@ -354,6 +368,31 @@ Two more boundaries worth stating in the same voice:
 | **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. |
 
+
+And one about the endpoint surface itself:
+
+| Not covered | Why | What answers it |
+|---|---|---|
+| **HTTP surface that is not a Spring handler mapping — a servlet declared in `web.xml` or registered as a `ServletRegistrationBean`, a container-level mapping, a static console mounted by a library.** | The endpoint population is projected from the Spring route model: one entry per handler mapping. A servlet is reachable over HTTP and is not in that model, so it is absent from `endpoints`, from the access verdicts derived from it, and from every ratio keyed on the total. Merging a second population into that count would move a published figure and every ratio with it, so the population is declared before it is widened. | Read the deployment descriptors for `<servlet-mapping>` entries and the Spring configuration for `ServletRegistrationBean` beans. Field evaluation #9 found a monitoring console mounted this way, behind a credential `ask spring-audit` did report (SEC-007) at a path nothing here listed. |
+
+And one about labelled data:
+
+| Not covered | Why | What answers it |
+|---|---|---|
+| **Whether a labelled member actually leaves the process on a given route — field-level dataflow through mappers, DTOs, serializers and projections.** | Exposure here is measured at TYPE granularity over the same call reach every other command walks: a route reaches the labelled type, or its signature names it. Whether the mapping in between keeps the labelled member is a dataflow question, and answering it by approximation would put a confident `no` on a route that does leak. So `call_reach` is published as a supremum and says so. | Read the mapping on the routes this answer ranks first — they are the ones worth a human — and label the DTO too if it carries the member, which makes the route `signature` instead of `call_reach`. |
+
+And one about who calls a route:
+
+| Not covered | Why | What answers it |
+|---|---|---|
+| **Whether a route is called from outside this repository — another service, a mobile app, a partner, a cron job, or a client whose URL is assembled at run time.** | The join reads the TypeScript/JavaScript checked in beside the server and only the call shapes whose verb and path are written at the call site. That is a floor on who calls a route and can never be a ceiling: the repository cannot observe consumers it does not contain. So a route with no call site here is published as a candidate for deletion, never as dead API. | Access logs or an API gateway answer who really calls a route. The opposite direction is decisive without them: a client call matching no route is a request this repository's own front end makes and its server does not serve. |
+
+The one row above with a remedy in this build: `ask endpoints /path/to/repo --servlets`
+lists the servlet-mounted HTTP surface as a population of its own — `web.xml` mappings and
+`ServletRegistrationBean` registrations, with the file that declares each — and never merges
+it into `endpoints.total`. Measured: openmrs-core 7 patterns, alfresco-community-repo 11,
+including `/api/*` served by a WebScript servlet.
+
 **Positioning.** Until an executor ships, this is the **diagnosis layer**: it measures what
 must change, what each change reaches, and what a gate should block — and it removes none of
 it. Field evaluation scored it 7/10 as a report generator and 5.5/10 as a development tool,
@@ -446,3 +485,4 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | [PRODUCT_IDENTITY.md](docs/PRODUCT_IDENTITY.md) | `ask` (command) vs `sourcecode` (package/alias) |
 | [privacy.md](docs/privacy.md) | Telemetry and data-handling policy |
 | [DEFECT-LEDGER.md](docs/DEFECT-LEDGER.md) | Every defect found in the field, its class, and which release closed it — published on purpose |
+| [spec/envelope-v1.md](docs/spec/envelope-v1.md) | The output format as an **open specification** — provenance, a named unit, a stated basis, declared non-coverage. Implementable by tools that are not this one; the field table is generated from the schema `ask schema envelope-v1` prints |