sourcecode 3.7.0__tar.gz → 4.0.0__tar.gz

{sourcecode-3.7.0 → sourcecode-4.0.0}/CHANGELOG.md

@@ -1,5 +1,457 @@
 # Changelog
 
+## [Unreleased]
+
+## [4.0.0] — 2026-08-02
+
+Major because two published `gate_coverage` fields are removed, not because the
+engine changed shape: `total_controller_handlers` / `gate_bearing` /
+`not_carrying_gate` (C2-14, the announced end of their two-minor window) and
+`possibly_filter_covered` (C1-20, which had no window — it counted the wrong thing).
+`removed_fields` in the same block maps each retired name to its successor.
+
+This release closes fourteen of the sixteen rows opened by the seventh field
+evaluation, in the order that record argued for, and ships `ask risk` — the first
+command that composes the other answers instead of adding one.
+
+### Added
+
+- **`ask risk` — the composition layer** (M10 head; [EXPERIMENTAL]). The seventh
+  evaluation's thesis was *"ASK tiene todos los átomos y no forma moléculas"*: one
+  class was `medium` in `spring-audit`, `medium/5.0` in `impact-chain`,
+  `coverage_unknown → permit_all` in `posture`, and executed a stored procedure that
+  mutates the database. Composed, that is unauthenticated write access under the
+  release build; separately, it was two commands saying "medium" and a reader doing
+  the join by hand.
+  `severity_effective = defect_severity × reachability × auth_verdict × write_effect`,
+  emitted as an ordered list. No new analysis — every factor is read from the
+  authority that already publishes it, and every row carries its four factors with
+  their sources, so a reader can reject one and keep the rest. An axis that could
+  not be measured is `unknown`, multiplies by 1.0, and is named in `blind_axes`:
+  the composition may not invent what nobody measured. This is the item that
+  *"crea producto"* rather than correcting data, and the one nobody replicates by
+  combining three scanners, because none of them shares an endpoint id with the
+  others.
+
+- **Three textbook security rules, because silence has to mean something** (CL-9).
+  The seventh evaluation got one security finding out of 3 342 files, then found
+  three more by hand in three files ASK had pointed it at. `SEC-004` (passwords
+  stored under a fast unsalted digest), `SEC-005` (CSRF disabled under
+  session-bearing authentication) and `SEC-006` (a cookie created without the Secure
+  attribute) ship in the `spring-audit` security surface, from one scan
+  (`sourcecode/security_config_scan.py`) with `file:line`. Each requires a
+  security-configuration context, so SHA-1 over a response body stays an ETag and a
+  stateless API that disables CSRF is not reported — a rule that cannot tell those
+  apart is one teams switch off, after which it protects nothing. These are table
+  stakes rather than differentiation: closing them avoids losing the sale.
+
+- **A third verdict for a gate that authorises against an identity nobody proved**
+  (C1-21). 939 endpoints in the field were reported `protected_custom` for carrying a
+  real gate — whose aspect resolves the caller through a method that returns a
+  database user when the authentication is null. The check runs; what it decides on,
+  for a request carrying no credential, is an identity the application invented, and
+  the vocabulary had no way to say so.
+  - `sourcecode/identity_fallback.py` (extractor) reports a method that reads the
+    platform's identity and, in a branch guarded by that identity being absent,
+    returns one anyway. Throwing, denying and returning null are correct handling and
+    are never reported; nothing branches on a method or class name (VAI).
+  - `security_posture` follows the enforcement path — types carrying published AOP
+    advice vocabulary or implementing a request-chain SPI — over `calls` edges, and
+    emits `protected_custom_degraded` (confidence `RequiresManualReview`) with an
+    `identity_resolution` block naming the method, the absence test and what it
+    returns. A fallback the enforcement path does not reach is not charged to the
+    gate.
+
+- **The remedy travels with the limitation** (C4-8, C3-37). The evaluation's requests
+  #1 and #5 — written by hand with invented syntax — are `posture
+  --resolve-environments` and `verify --init`, both shipped in the build it audited.
+  Four earlier rows say the same thing: discoverability cannot live in a document,
+  because a reader looking at an output does not go and read `--help`. One registry
+  (`sourcecode/remedies.py`), keyed by the question rather than by the flag, is read
+  by `posture.activation`, `posture --diff`, the `security_posture` limitation that is
+  conditional on the profile set, and `verify`'s exit-2 reason. A test refuses any
+  remedy naming a command or option the CLI does not accept, so a renamed flag breaks
+  the build instead of sending a reader to an invocation that no longer exists.
+
+- **A filter that matches a path is not a filter that checks the caller** (C1-20).
+  `gate_coverage` published `possibly_filter_covered: 2635` over patterns `/*`,
+  `/api/*` and `/api/v1/*` — and those three filters were CORS, headers and logging,
+  while the only filter that authenticates covered two prefixes. The wording was
+  technically honest and the number was still *"falso consuelo"*: the corrected split
+  on that repository is 12 covered against 2 623 in the gap. Both halves of the join
+  were already in the same process, so the fix is an intersection **per filter**
+  rather than per pattern-set:
+  - `sourcecode/filter_surface.py` now records each declared filter (`@WebFilter`, and
+    `web.xml` mappings correlated with their `<filter-class>`) with a verdict —
+    `authenticates`, `does_not_authenticate`, `unknown` — decided structurally, never
+    by name (VAI): the filter establishes an identity, or it reads a credential *and*
+    refuses over it. A body that is not in this repository stays `unknown`, because
+    absence of evidence published as evidence of absence is the same defect mirrored.
+  - `gate_coverage` replaces the single count with four that partition the escape set:
+    `filter_covered_authenticating`, `filter_gap_non_authenticating`,
+    `filter_authentication_unknown`, `no_matching_filter_pattern`, plus a `filters`
+    list naming each filter, its patterns and the evidence behind its verdict.
+
+- **Seven presentation rows, none of them an analysis error, two of which led a
+  reader to the inverse conclusion** (C2-15…C2-20, C1-19).
+  - `validation` printed *"0 body endpoints, 1179 gaps"* over a payload carrying
+    `body_endpoints_in_code: 1201` — the declared-constraint count under the
+    code-surface name. Both axes are named in their own units (C2-15).
+  - TX-006's witnesses all carried the callee's line, because that is where the
+    remedy goes, so several rows shared one number and read as duplicates. Each
+    finding now carries its `call_site` from the IR's span index, and the defect row
+    publishes the distinct sites with their count (C2-16).
+  - `limitations` merged across scopes repeated an entry verbatim; deduplicated once
+    in `finalize`, in first-seen order (C2-17).
+  - `spring_profiles.conditional_beans[].source_file` used the platform's native path
+    separator while the rest of the document used `/`; posix everywhere, including the
+    two other extractors that did the same (C2-18).
+  - `estimated_effort_range_days` published `{low: 60.7, high: 60.7}` — not a range,
+    at a precision the model does not have. The band declares `point_estimate` and
+    `precision_days`, and rounds to it (C2-19).
+  - `posture` cut four endpoint lists and its evidence map at 200 and declared
+    nothing, in the command whose declared caps the same evaluation calls a feature.
+    Each cut publishes total/shown/omitted and the registered cap effect; a list that
+    was not cut declares nothing (C2-20).
+  - Three commands published a file count for one repository — 3 337, 3 336, 3 342 —
+    and none said what it counted. Measured rather than equalised: all code-extension
+    files in any language, the non-test denominator of a test ratio, and the `.java`
+    files handed to the migration rules. Each names its population (C1-19).
+
+- **`cache status` counts every store a warm fills** (C3-36). It printed `CAS blobs:
+  0`, `Total size: 0.1 MB` immediately after an 89-second warm of 3 342 files: true of
+  the per-repository core store, and the warm's output mostly lands in the shared
+  Canonical IR and the content-addressed parse cache, which the command never counted.
+  The status now breaks down by store, says what each holds, and labels the parse
+  cache shared across repositories so its size is not read as this repository's.
+
+### Removed
+
+- **BREAKING — `gate_coverage` no longer emits the three deprecated aliases** (C2-14).
+  `total_controller_handlers` counted *endpoints* under a name that says handlers,
+  `gate_bearing` counted *handler methods* while sitting beside an endpoint count, and
+  `not_carrying_gate` duplicated `endpoints_not_carrying_gate`. They were kept for a
+  two-minor window after C1-5 named the units; the seventh field evaluation read the
+  aliases anyway and quoted `total_controller_handlers: 3574` as handlers next to
+  `handler_methods_total: 913`. An alias that still ships is a live claim, and two of
+  these claimed the wrong unit. Read `endpoints_total`,
+  `handler_methods_carrying_gate` and `endpoints_not_carrying_gate`; the block now
+  carries `removed_fields` mapping each retired name to its successor, so a consumer
+  meets the answer rather than a `KeyError`. `possibly_filter_covered` is retired in
+  the same block and for the same reason (C1-20): it counted "a filter runs here" and
+  was read as "a filter checks here".
+
+## [3.8.0] — 2026-08-02
+
+### Added
+
+- **The security surface publishes what it does not answer** (CL-2, CL-7, and the framing half
+  of CL-5). A report that lists what it found and says nothing about what it never looks at
+  invites silence to be read as absence — and the audit that raised this found a credential
+  versioned in three deployment descriptors *by hand*, because nothing here reads outside Java
+  and Spring configuration.
+  - One authority, `sourcecode/non_coverage.py`, read by three surfaces: the `non_coverage`
+    block in the `spring-audit` payload, the command's own `--help`, and the README section —
+    all rendered from the same table, because a curated list beside a generated one is how
+    `endpoints` went missing from every help list.
+  - Four rows for the security surface: no dataflow or taint (NC-001), no secrets outside Java
+    and Spring configuration (NC-002), filter-chain order not reconstructed (NC-003), no CVE
+    matching (NC-004). Each states why it is out of scope rather than unimplemented, and what
+    does answer it. Two more state the migration boundary (NC-005, OpenRewrite takes the
+    recipes this publishes) and the environment boundary (NC-006, answered as far as a
+    repository can by `posture --resolve-environments`).
+  - The evaluator's argument for publishing it is commercial, not ethical: *"un producto que
+    publica sus límites no se compara por amplitud; se compara por profundidad, que es donde
+    gana."*
+
+### Changed
+
+- **Two claims corrected with measured figures.** `--compact` is documented as the smallest
+  answer, **not the cheapest run** — 13.3 s cold on BroadleafCommerce against `spring-audit`
+  3.6 s and `posture` 1.9 s, 0.3 s warm — with the reason to warm before a session stated where
+  the claim is made (CL-3). And the product is positioned as the **diagnosis layer** until an
+  executor ships, in the field's own numbers (7/10 as a report generator, 5.5/10 as a
+  development tool) rather than argued with (CL-5).
+
+- **`ask trend` is a top-level command, and capture is automatable** (P-4). The *series* is the
+  asset — a repository that captured a baseline at each release has a history nobody can
+  reconstruct afterwards, and one that did not never will — so reading it is no longer two words
+  deep, and [`docs/baseline-ci.yml`](docs/baseline-ci.yml) captures one per tag and publishes the
+  trend as a build artifact. `ask baseline trend` is the same command.
+  - The read-only half was a **documentation** gap and is closed where the auditor meets it:
+    `--dir` already existed, and the default now says *why* it is inside the repository (the
+    history travels with the code, not with a vendor) and that an audit which must leave the tree
+    untouched writes elsewhere. README and the user guide say the same.
+  - ⚠Adding the command surfaced the **C4-1 shape a sixth time**: `ask trend` was registered,
+    working and documented, and the CLI answered *"'trend' does not exist"* — because the
+    dispatcher matched against a **hand-written set of subcommand names**. It is derived from the
+    registry now, and the battery asserts every registered command is dispatchable.
+
+- **`ask posture --resolve-environments` — which profile set actually runs, and the worst one
+  that could** (CL-8 / M9.5). `posture --diff` was called the strongest thing this product does
+  and it stopped at the repository boundary: which profile set runs is decided by the
+  deployment, so the answer was conditional and a field evaluator closed the last hops by hand
+  with `grep` (build profile → the property the build filters → a placeholder present in no
+  config file → no `context-param` in any descriptor → therefore nothing decides it).
+  - Those hops are now mechanical. Every artefact that can set `spring.profiles.active` is read
+    — config files, Maven/Gradle properties, `web.xml` context parameters, `Dockerfile` `ENV`
+    and `-D` arguments, Compose and Kubernetes manifests, launch scripts — each publishing what
+    it says with `file:line`. The verdict is `decided_in_repository`, `artefacts_disagree` (two
+    deployments, never a contradiction to resolve by picking one), or **`NOT DECIDED IN THIS
+    REPOSITORY`**.
+  - Every admissible profile set is then resolved over one parse and ranked by what it leaves
+    open, so the payload names the worst case and, where the repository does decide, how far the
+    shipped set is from it: *"one environment variable away from dev"*.
+  - **`open_by_rule` and `access_not_decided` are counted separately.** A readable rule that
+    permits a request unauthenticated is not the same fact as no readable rule matching it, and
+    folding them together would publish the confident security falsehood this command exists to
+    prevent. The reading says which is which.
+  - A value found in the repository is published as a default, never a guarantee:
+    `SPRING_PROFILES_ACTIVE` in the process environment outranks every artefact, and this
+    analysis cannot see the process environment.
+
+- **`ask verify --init` derives the contracts a repository already satisfies** (C3-30). The gate
+  had no way to acquire what it gates on: nobody hand-writes contracts for a 3 300-file
+  monolith, so the honest gate (zero contracts is `unverified`, closed as C3-15) stayed empty —
+  and the gate is the recurring half of the value story, where an audit is bought once.
+  - Three shapes, each written with the measurement behind it: a path prefix whose endpoints all
+    carry the same policy today (`require_endpoint_security`), an audit pattern that fires
+    nowhere (`forbid_finding`), and an injection edge between two annotated populations that
+    does not occur, both populations large enough that the absence is a pattern rather than an
+    accident (`forbidden_edge`).
+  - **Every rule is executed before it is written.** The derived set runs through the same engine
+    `verify` runs, and anything that fails on the tree it came from is dropped and reported —
+    `verify --init` followed by `verify` passes by construction, asserted as a round trip in the
+    battery, together with the proof that the populated gate goes red when the invariant breaks.
+  - Violations that exist today are deliberately not proposed: that is debt for
+    `--capture-baseline`, a different claim from an invariant, and the payload says so per
+    rejected candidate.
+  - `--dry-run` prints without writing; an existing contracts file is never replaced without
+    `--force`.
+
+- **`delta` and `contract-diff` take git refs** (C3-33). Both compared two *checkouts* while
+  `review-pr` in the same CLI already took `--since`, so comparing two commits meant
+  orchestrating worktrees first. In the evaluation that recorded this, that cost coverage rather
+  than convenience: the evaluator ran the full catalogue against a client monolith under a
+  promise to leave the environment byte-identical and **omitted both commands** rather than
+  create worktrees in someone else's repository.
+  - `ask delta --base-ref origin/main --head-ref HEAD [--repo <path>]`, same for
+    `contract-diff`. Two checkouts positionally still work, and the payload publishes a
+    `comparison` block saying which basis it used — with both refs and their resolved commits.
+  - **Reading a ref writes nothing to the repository.** `git archive` streams the tree into a
+    temporary directory that is removed on the way out: no `git worktree add` (which registers
+    administrative state under `.git/worktrees` and leaves it behind if the process dies), no
+    checkout, no stash, no index read. The battery asserts `git status` and `git worktree list`
+    are identical before and after.
+  - A ref this repository does not have is refused by name (`git_ref_not_found`, exit 1) and
+    never substituted with something nearby.
+
+### Fixed
+
+- **`retrieve` stopped publishing scores nothing computed** (C3-19, **`entities[].score` and
+  `explanation.score` are nullable**). `retrieve blast-radius` returned eighty dependents each
+  carrying `"score": 0.0`, beside an explanation whose own score was 92.43 — and the step that
+  orders those entities says in its own docstring that no score is computed. The same default put
+  a zero on every entity of every intent, and an `explanation` block with `winner: null,
+  score: 0.0` on the intents that return what they found rather than choose a winner: the shape
+  the field called *a ranking block that never ran*.
+  - Both fields are `None` when nothing wrote them. The order is real and structural, so the
+    payload states it: `entities_ranked_by` — *"reach from the target (direct before indirect),
+    then identity — a structural order, not a per-entity score"*.
+  - `retrieve` remains `[PARKED]`; this is the honesty fix the tier does not excuse.
+
+- **`archetype` no longer scores an unmeasured HTTP surface as an absent one** (C3-7). The
+  command declares `endpoints` as a missing signal on runs with no root to read — and then
+  scored as if the answer were **0**, which is a measured statement. Inside the scorer that zero
+  did two things at once: it refuted `api-first` and it fired `worker`'s `event_no_http`
+  evidence, so a repository nobody measured came back classified as an event worker with the
+  reason published as if it were a finding (I-3/R9, inside a score).
+  - The count is nullable now. Unmeasured contributes nothing and says so in its own evidence
+    row; `event_no_http` requires the absence of HTTP as a *measured* fact. A measured zero
+    behaves exactly as before, which the battery asserts alongside the unmeasured case.
+  - Measured while closing it, and recorded rather than acted on: `archetype` on
+    BroadleafCommerce takes **9.3 s** (the field reported 22 s) and returns two high-confidence
+    dimensions of four, so the tier stays `[EXPERIMENTAL]` — the cost complaint does not
+    reproduce at that magnitude, and a command with two high-confidence answers is not a
+    candidate for `parked`.
+
+- **The summary stopped costing more than the analyses it summarises** (C3-6, C3-21). Measured on
+  BroadleafCommerce with nothing warm: `--compact` **19.3 s → 13.3 s**, and with the parse cache
+  warm **14.0 s → 7.9 s**; `endpoints` **3.3 s → 1.4 s**. Two duplications inside one process, both
+  removed:
+  - The **core view was built twice on every cold run** — once for the L1 cache write and once for
+    the RIS update — and building it rebuilds the CIR. One repository state has one core view; both
+    writers now read it.
+  - The **endpoint extractor parsed every file itself** while `build_repo_ir` read the
+    content-addressed parse cache for the same bytes. A run that does both paid for the same parse
+    twice, and a warm cache measurably bought `endpoints` nothing — a fact this product published
+    in its own cache model. Same key, same extractor, same capture signature: the entry either side
+    writes is the entry the other reads. The cache-model rows for `endpoints` and the root command
+    are re-measured accordingly.
+  - The inversion is **narrowed, not gone**: `--compact` is still slower than `spring-audit`
+    (3.6 s) or `posture` (1.9 s), because it builds the summary *and* the core view where those
+    build one analysis each.
+  - **C3-21 does not reproduce on 3.7.0**: the cache hit that cost 2 647 ms now costs 1.6 s for
+    `explain` against a 1.6 s cold run, and the snapshot hit for `--compact` is 0.29 s. Recorded as
+    measured, not assumed closed.
+  - The battery pins the two mechanisms rather than wall-clock figures: a second extraction must
+    re-parse nothing, the cached and uncached answers must be identical, and one root run must
+    build the core view once.
+
+- **A comment can no longer take a whole file out of the graph** (E-1). The declaration joiner
+  decided whether a line *starts* a type declaration by scanning raw text, so a comment carrying
+  `class` or `interface` followed by an identifier looked like a declaration head with its brace
+  on a later line — `/** Implements the interface only for the legacy path. */`, or a trailing
+  `// starter class is not an utility class` on an annotation. The join then swallowed the
+  annotation and the real declaration into one entry beginning with `@`, which the parser reads
+  as a pending annotation and never examines: the file contributed **zero symbols** — no type,
+  no endpoint, no transaction boundary — and a file that contributes nothing looks exactly like
+  a file with nothing in it, which is why no field report could ever name this.
+  - Comments are stripped before the keyword scan (block state carried across lines, string
+    literal aware), and the brace that ends a join must also be code, so a commented `{` no
+    longer cuts a real multi-line declaration in half.
+  - Measured A/B over six repositories: **open-banking-gateway recovers 6 types, three of them
+    Spring Boot application classes**; petclinic, eureka, openmrs-core, BroadleafCommerce and
+    keycloak are unchanged, and **no repository loses a symbol**.
+
+- **`generate-tests` ranks by what depends on the file, not by how the file is named**
+  (C3-13, **`untested_sources[]` entries change shape**). Two rules, both name matching, both
+  measured on openmrs-core: admission kept only files whose name ends in one of five suffixes
+  (`Service.java`, `Controller.java`, `Repository.java`, `Mapper.java`, `RestController.java`),
+  reducing **866 production files to 11 candidates**; and coverage was a filename pair, so
+  `PersonServiceImpl` was a gap for want of a `PersonServiceImplTest`. What remained was ordered
+  by how often the substring `"public "` appears in the first 16 KB — while `blast_radius`,
+  transaction boundaries and endpoint exposure were already computed elsewhere in the same
+  product and never consulted.
+  - **Coverage is now a reach fact**: a type is covered when a test source reaches it — named
+    directly, or reached along the call, instantiation and injection edges a blast radius
+    already walks, through the interface the container wires it behind, or as a supertype of
+    something a test exercises. One forward traversal from every test type: 0.01 s on
+    BroadleafCommerce. Reaching is not asserting, so the coverage figure is a floor and the gap
+    list is a ceiling, and `notes` says so.
+  - **Admission is the population**, not a naming convention: openmrs-core 866 production files
+    → **161 untested**, BroadleafCommerce 2 765 → **1 494**, published as `population` beside
+    the list.
+  - **Order is the measured axes** — endpoints reached, transaction boundaries declared, classes
+    that depend on it — reusing `caller_reach`, `spring_impact._collect_endpoints` and
+    `spring_semantic.boundaries_declared_within` rather than deriving them again. The weights
+    that fold the three into `score` are published with `rank_weights_basis: "assumption, not a
+    measurement"`, and the order is reproducible from the axes without accepting them.
+  - `untested_sources[]`/`test_gaps[]` rows drop `rank_score`, `public_method_count` and
+    `has_framework_annotations` — measurements of the replaced basis — and carry
+    `endpoints_reached`, `transaction_boundaries` and `caller_classes` instead. `path`, `score`
+    and `reason` are unchanged. The new `test_gap_ranking` block publishes the basis, the
+    population and the caps.
+  - Cost, measured cold: BroadleafCommerce 11.1 s → **15.3 s**, openmrs-core 5.1 s → 10.2 s. A
+    run whose IR cannot be built keeps the filename algorithm and publishes the
+    `test_reach_graph` signal with what taking it costs the answer (I-8).
+
+- **`generate-tests` publishes its time budget, and a cache no longer defeats it** (C3-1). The
+  30 s cap was reachable only through `SOURCECODE_TESTS_TIMEOUT_MS`, a name in no help text —
+  the one knob that turns an empty answer into an answer was invisible to whoever was holding
+  the empty answer. `--timeout <seconds>` is now a documented flag (the variable still works;
+  the flag wins), and an exhausted budget publishes `analysis_budget` carrying the new
+  `time_budget` cap: *"an empty list here means the walk stopped, NOT that the repository has
+  nothing"*, with the budget, its source, and how to raise it.
+  - Closing it surfaced a sharper defect, measured: **the cache key ignored the budget**, so a
+    run that exhausted 2 s answered the re-run at 30 s from cache — the remedy the payload
+    names did nothing at all. The budget is now part of the cache identity, and an exhausted
+    result is never stored: an unfinished walk is worth re-running.
+  - Measured while closing it: the full scan on openmrs-core (3 300 files, cold cache) takes
+    **3.35 s** and returns 13 untested sources, so the field's empty payload does not reproduce
+    and the default budget is not the constraint it was taken for. The ranking half of C3-13
+    stays open — the command still matches file names while `blast_radius`, transactional
+    writes and endpoint exposure are already computed.
+
+- **`review-pr` no longer counts documentation as a runtime change** (C3-11b). The field
+  reported a diff of 227 `.md` files as `runtime_changes: 228` — while every one of those
+  entries carried `artifact_type: "documentation"` and `change_effect: "documentation file (no
+  runtime impact)"`. The list contradicted its own members. Reproduced on a real git repository
+  (12 `.md` files + one touched controller): **13 → 1**. The classifier was never wrong;
+  membership was "not noise and not a build manifest", which admits everything else, and the
+  admission seam (K2) now asks whether the admitted type can carry runtime behaviour at all.
+  - Nothing is dropped: the twelve are reported under `non_runtime_changes` with the same
+    evidence and effect statement, and the GitHub comment names them by count so it cannot look
+    like it missed part of the diff.
+  - The split is asserted **against the effect statements themselves** — a type whose published
+    statement disclaims impact must be in the non-runtime set — so it cannot drift from the
+    prose it is derived from (C4-1).
+
+- **One profile population, whatever surface is asked** (C1-18, **`spring_profiles` changes on
+  repositories with resource bundles or resource folders**). Reproduced on a fixture first: the
+  same repository in one session answered `["qa","dev"]` in the default view, `["dev","prod",
+  "staging"]` in `posture` and `["dev","prod","qa","staging"]` under `--agent`. Three
+  populations under one name — and every conditional-security finding is keyed on that set, so
+  the default agent surface was answering the profile question with the population that had
+  lost the environments.
+  - Authority `spring_profiles.profile_population`: four named signals — the
+    `application-{profile}` filename, the per-environment overlay directory,
+    `spring.config.activate.on-profile` / `spring.profiles` inside config documents, and
+    `@Profile` on a bean — unioned once, with `by_signal` published so each name's provenance
+    is auditable. The Java stack detector, `posture` and the serializer's profile section all
+    read it, asserted per surface.
+  - Closing it exposed two false positives in the signals it inherited, both fixed
+    structurally rather than by name (VAI): an `application-{x}` file counts only **beside its
+    base config** — alfresco-community-repo's `alfresco/messages/application-model_de.properties`
+    and 19 siblings were reported as twenty environments, now none — and an overlay directory
+    counts only when it **holds a config file** — spring-petclinic's `db/`, `messages/`,
+    `static/` and `templates/` were reported as four environments, now `mysql, postgres`, its
+    real profiles.
+
+- **The token-saving ratio is published, and published as a ceiling** (CL-1). `token_economy`
+  emitted `emitted`, `baseline_raw_read` and `saved` — three numbers a reader divides into a
+  multiple and then quotes. The multiple travelled without the label the block put on the
+  inputs, which is how "up to 55×" ends up in a room. `ratio_upper_bound` is now emitted with
+  a `ratio_basis` that states the counterfactual making it a ceiling — every cited file and
+  build manifest read **in full and once** — the band we measured for the ceiling itself
+  (**3.8×–37.6×** over `--compact` and `--agent` on spring-petclinic, BroadleafCommerce,
+  openmrs-core and keycloak; nothing near 55×), and the field's 10×–20× read of the saving an
+  agent actually realizes.
+- `realized_saving` is `null` with its reason rather than a number: which files an agent would
+  truly have read is not observable from this process, and a `0` there would read as "no
+  saving" (I-3).
+
+- **`spring-audit` counts defects as well as observations** (C2-5). A rule fires per
+  observation; a reader counts repairs. The audit published only the first number and let it
+  stand for the second: on openmrs-core `ConceptServiceImpl#checkIfLocked` carried **six
+  TX-006 findings, one per call site, for one annotated method with one fix**, and the
+  ledger's original witness is a private `@Transactional` method that draws TX-001 *and*
+  TX-006 for the same repair. Measured on the fleet: **openmrs-core 38 findings → 29
+  defects, BroadleafCommerce 19 → 14**.
+  - A defect is `(category, defect_kind, symbol)` — the thing you edit, and what is wrong
+    with it. `defect_kind` is **declared by the rule itself** (TX-001 and TX-006 both
+    declare `proxy_bypass`) and defaults to the rule's own id, so a rule that declares
+    nothing is never merged into another by omission, and there is no rule table maintained
+    beside the rules to drift out of date (C4-1).
+  - Nothing is filtered. `findings[]` keeps every observation and each one now names its
+    `defect_id`; the new `defects[]` rows carry `rule_ids`, `witness_count` and the witness
+    ids, so the grouping is auditable in both directions. `summary` publishes
+    `total_findings`, `total_defects`, `defects_by_severity` and a `counts_note` stating
+    which is which — `by_severity` and `by_category` keep counting observations, because a
+    count that changes basis under an unchanged name is the same defect wearing a new suit.
+  - A defect takes the **strongest** severity and confidence among its witnesses, and its id
+    is keyed on the identity, not the witnesses — acquiring a second witness next run does
+    not rename it, so a baseline keeps matching it.
+
+- **`migrate-check` lists the blockers; hygiene is counted, not listed** (C2-6, **default
+  payload changes**). On openmrs-core the default report carried 310 findings of which **184
+  were `java_8_best_practice` advisory hygiene** — findings that block no version and that
+  every readiness score already excludes. A reader scanning the array met three advisory
+  entries for every two blockers. The emitted list now carries the blockers, ordered
+  most-severe first (**310 → 126 listed, 912 KB → 717 KB**), and `--include-hygiene` restores
+  the entries.
+  - **The floor cuts the list, never a figure.** `summary.by_severity`, `by_rule`,
+    `by_migration_target`, `total_findings`, `hygiene_findings`, `blocking_count` and every
+    dimension score are byte-identical to the unfloored run and still cover the whole
+    population — verified as an equality, not a claim.
+  - It is published as a cap, not applied in silence: `findings_floor` (the `severity_floor`
+    row of `CAP_EFFECTS`, I-8) states what was removed, what stayed exact, and the flag that
+    restores it, so `len(findings)` is never read as the total.
+  - The other half of the ledger row — "headline score reads 0/100 while real blockers are
+    481" — was already closed and re-measured here: hygiene is out of the aggregate, and
+    openmrs's 0 is `min(jakarta 0, hibernate 0)` with `jdk_modernization` (58) excluded by
+    design. The score was honest; the finding list was the noise.
+
 ## [3.7.0] — 2026-08-01
 
 **The exit-code contract and the C3 surface block.** Seven rows closed: the two the field named

{sourcecode-3.7.0 → sourcecode-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.7.0
+Version: 4.0.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
@@ -220,7 +220,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 | `posture` · `archetype` |
+| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `posture` · `archetype` |
 | **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
@@ -237,6 +237,7 @@ 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 |
 | `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 |
@@ -251,7 +252,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 | trend reporting, not gating |
+| `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) |
 | `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 | |
@@ -275,6 +276,34 @@ Honest limits worth knowing before you rely on it:
 - Architecture classification is tuned for Spring MVC layered apps; SPI/plugin models (e.g. Quarkus extensions) may be misclassified. JAX-RS subresource-locator endpoint recall is ~65%.
 - Self-invocation `@Transactional` bypass (same-class call skipping the proxy) is not detected.
 
+### What the security surface does not answer
+
+Published because a product that states its limits is not compared on breadth — it is
+compared on depth. Each row is emitted in the payload too (`non_coverage`), so an agent
+reading JSON sees the same boundary a buyer reads here.
+
+| Not covered | Why | What answers it |
+|---|---|---|
+| **Whether request input reaches a sink — no dataflow or taint analysis.** | This engine resolves structure and wiring without compiling. Taint 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). What this product adds on top is reachability: which of that tool's findings sit behind an endpoint that is reachable unauthenticated. |
+| **Secrets outside Java and Spring configuration — a credential in a deployment descriptor, a Helm value, a CI variable file.** | The file population this analyzer reads is the Java source and the Spring configuration convention. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. | 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. |
+
+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. |
+
+**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,
+and that gap is the honest description, not a defect to argue with. `migrate-check` publishes
+the OpenRewrite recipe each finding carries so the executor that does apply changes has its
+input.
+
+
 ---
 
 ## Pricing
@@ -348,7 +377,8 @@ 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`, 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 |
+| [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 (experimental) |
 | [migrate-check.md](docs/migrate-check.md) | Migration rule catalogue (MIG-001..043) + Hibernate stratification |
 | [MODERNIZATION.md](docs/MODERNIZATION.md) | The modernization product: assess → understand → plan → execute |

{sourcecode-3.7.0 → sourcecode-4.0.0}/README.md

@@ -182,7 +182,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 | `posture` · `archetype` |
+| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `posture` · `archetype` |
 | **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
@@ -199,6 +199,7 @@ 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 |
 | `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 |
@@ -213,7 +214,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 | trend reporting, not gating |
+| `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) |
 | `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 | |
@@ -237,6 +238,34 @@ Honest limits worth knowing before you rely on it:
 - Architecture classification is tuned for Spring MVC layered apps; SPI/plugin models (e.g. Quarkus extensions) may be misclassified. JAX-RS subresource-locator endpoint recall is ~65%.
 - Self-invocation `@Transactional` bypass (same-class call skipping the proxy) is not detected.
 
+### What the security surface does not answer
+
+Published because a product that states its limits is not compared on breadth — it is
+compared on depth. Each row is emitted in the payload too (`non_coverage`), so an agent
+reading JSON sees the same boundary a buyer reads here.
+
+| Not covered | Why | What answers it |
+|---|---|---|
+| **Whether request input reaches a sink — no dataflow or taint analysis.** | This engine resolves structure and wiring without compiling. Taint 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). What this product adds on top is reachability: which of that tool's findings sit behind an endpoint that is reachable unauthenticated. |
+| **Secrets outside Java and Spring configuration — a credential in a deployment descriptor, a Helm value, a CI variable file.** | The file population this analyzer reads is the Java source and the Spring configuration convention. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. | 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. |
+
+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. |
+
+**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,
+and that gap is the honest description, not a defect to argue with. `migrate-check` publishes
+the OpenRewrite recipe each finding carries so the executor that does apply changes has its
+input.
+
+
 ---
 
 ## Pricing
@@ -310,7 +339,8 @@ 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`, 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 |
+| [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 (experimental) |
 | [migrate-check.md](docs/migrate-check.md) | Migration rule catalogue (MIG-001..043) + Hibernate stratification |
 | [MODERNIZATION.md](docs/MODERNIZATION.md) | The modernization product: assess → understand → plan → execute |

{sourcecode-3.7.0 → sourcecode-4.0.0}/pyproject.toml

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

{sourcecode-3.7.0 → sourcecode-4.0.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__ = "3.7.0"
+__version__ = "4.0.0"