sourcecode 3.4.0__tar.gz → 3.5.0__tar.gz

{sourcecode-3.4.0 → sourcecode-3.5.0}/CHANGELOG.md

@@ -1,6 +1,266 @@
 # Changelog
 
-## [Unreleased]
+## [3.5.0] — 2026-07-31
+
+**M7.7 "Robustness floor" — the axis field evaluation #5 scored 4/10.** Ten pieces, and the
+pattern in eight of them is the same: the reported symptom was real, and the measured cause was
+not the one anyone had assumed. Input admission had four behaviours for one fact, not one broken
+command. `posture`'s cost was not the Java parse but a quadratic scan of two branches that could
+not fire — and that dead code was also a false zero on the security axis. The blast radius
+disagreed with itself because there were two traversals of the reverse graph, not because reach
+is hard. Two reported symptoms did not reproduce at all and are recorded as measured rather than
+fixed blind.
+
+**Minor, not patch**, on two counts: `impact` now publishes endpoints, transaction boundaries and
+a security surface where it published `0`, so its risk score moves and a pipeline gating on it can
+change colour; and `estimated_effort_days` is nullable where a range applies.
+
+### Changed
+
+- **`retrieve` moves from `experimental` to `parked`** (C3-24) — kept working, no longer
+  developed, and saying so: `[PARKED]` in its own help, in the README table and in the user
+  guide, all rendered from `cli.COMMAND_TIERS`. The battery now also asserts that a parked
+  command declares itself, the twin of the assertion that already existed for experimental.
+  **Two of the three reported symptoms did not reproduce**, and are recorded that way rather
+  than repeated: `transaction-propagation` returns one entity because the battery repository
+  has exactly one non-default boundary (`REQUIRES_NEW: 1` of 161) — `observations.total` is the
+  tx-index population standing beside the answer, not a truncated total, and a `--limit` exists
+  (default unbounded) that records `entities_truncated` when it bites; `security-surface`
+  returns 0 where `spring-audit --scope security` also returns 0. What does reproduce is an
+  `explanation` block shaped for a ranking that never ran. The surface is not non-functional —
+  it is undifferentiated, re-stating behind 15+ intents what the core commands answer better.
+
+### Measured
+
+- **`review-pr`'s path argument is not decorative — the reported scope defect does not
+  reproduce** (C3-27, scope half). Field evaluation #5 reported that given a submodule path the
+  command reports the *enclosing* repository as `repo_root` and reviews 227 files from other
+  modules. Re-measured on six shapes: a module subdirectory, that same subdirectory as the
+  working directory, a nested path given relative to the root, an embedded repository, a **real
+  git submodule** (where `.git` is a gitlink *file*, so an `exists()` test is true for it and the
+  walk up has to stop there), and a submodule asked for a ref only its parent has. Every run is
+  bounded to the path it was given: on BroadleafCommerce the scoped runs return exactly
+  `git diff --name-only <ref> -- <scope>` — 5 of 17 files at `core/`, 855 at
+  `core/broadleaf-framework/`, 1 222 at `core/` over a 3 332-file range — `_meta.scope` names the
+  tree answered about, no sibling-module path appears anywhere in the payload, and the
+  missing-ref case is refused (`git_ref_not_found`, exit 1) instead of borrowed from the parent.
+  Recorded as not reproducing rather than fixed blind, and the six shapes are now asserted in
+  `tests/test_git_scope_namespace.py` so the symptom cannot return silently. The probable closer
+  is the Bug A scope-namespace seam, which landed between the evaluated build and this
+  measurement.
+
+### Fixed
+
+- **`impact` reported `endpoints_affected_count: 0` for a symbol `impact-chain` reached 21
+  endpoints from** (C1-16, endpoint half — the caller half closed in 3.5.0). A false zero on the
+  blast-radius axis, which is the number a user takes a risk decision with. The cause was
+  measured, not guessed: there were **two traversals** of the reverse graph, and they disagreed
+  twice.
+  - `impact` looked up the exact reverse-graph key. The callers of a class are stored under its
+    **method** keys (`Foo#doWork`), never under `Foo`, so the walk terminated at every
+    class-level node — which is exactly what a DI `injects` edge normalises to. 125 indirect
+    callers instead of 1 442.
+  - It admitted `implements`/`extends` as caller edges (an implementor does not call an
+    interface by implementing it, CH-006) under a comment claiming its edge set was *"consistent
+    with `spring_impact._SKIP_EDGE_TYPES`"*, which skips both. And it held no interface index, so
+    it never crossed the DI boundary at all: on `Money` it reached 200 classes and **zero
+    controllers**, against 441 and 18.
+  - New authority `sourcecode/caller_reach.py`, registered as fact `blast_radius_reach`, with
+    `impact`, `impact-chain` and `migrate-check --blast-radius` all bound to it. On
+    BroadleafCommerce's `Money`, `impact` now reports **20 of the 21 endpoints** (0 before),
+    **53 transactional boundaries** (0), **20 persistence paths** (2) and **15 security-gated
+    endpoints** (0) — while `stats.direct_caller_count` stays **134**, so the caller axis closed
+    in 3.5.0 does not move. Parity verified command-to-command on spring-petclinic
+    (`OwnerRepository`: 13 = 13 endpoints, exact) and open-banking-gateway (two symbols, exact):
+    the reconciliation adds no false positives. Cost unchanged (5.0 s vs 4.9 s on that repo).
+  - Also fixed here: the explanation prose read *"433 direct callers"* beside a payload
+    publishing 134 caller classes and 433 reference sites, each named for its unit. Prose is
+    what a reader quotes, so it now names its unit too.
+  - **Residual, stated because it is measured:** one endpoint of the 21
+    (`BroadleafOauthRegisterController#processRegister`) is still reached by `impact-chain` and
+    not by `impact`, because the two commands read *different graphs* — `impact` builds the repo
+    IR, `impact-chain` the CIR, and the CIR carries a method key for that handler the repo IR
+    does not. That is a graph-population gap, not a traversal one. Seed expansion is asymmetric
+    for the same reason (`impact-chain` expands a seed to its subtypes, `impact` only to the
+    interfaces it implements).
+
+- **`posture` costs a sixth of what it did, and a warm is finally worth something to it**
+  (C3-25) — 24.5 s → **10.1 s** cold and 19.3 s → **1.6 s** after `cache warm`, measured on
+  BroadleafCommerce in isolation. Field evaluation #5 measured 195 s, ×18 the session median,
+  on the one command the product differentiates on, and the cache model honestly documented
+  that a warm bought it almost nothing. Both had the same cause, and it was not the Java parse
+  everyone blamed:
+  - **The security predicate re-walked every node in the repository for every class** —
+    6 075 × ~29 000 ≈ 176 M dictionary reads on the battery repository, larger than the parse
+    itself — looking for `node["return_type"]` and `node["supertypes"]`. **The IR publishes
+    neither key on a node.** Inheritance and return types are `extends`, `implements` and
+    `returns` *edges*, so both branches were structurally dead in every release: a repository
+    that wires its chain with a `@Bean SecurityFilterChain` or a filter subclass and no
+    `@EnableWebSecurity` was reported as configuring no security at all — a **false zero on the
+    axis this command exists for**. The predicate now reads the edges, once per IR. On
+    BroadleafCommerce it recovers 6 request-chain configurations, verified 6/6 against source
+    with no false positive, one of which is `@ConditionalOnProperty` and now correctly qualifies
+    the endpoint claim as unresolved instead of silently strengthening it.
+  - **`posture` built its own CIR on every run** — the same parse `cache warm`, `explain` and
+    `impact-chain` already share. It now goes through the shared knowledge cache, poison-safe by
+    the `peek_cir` rule: the knowledge key is repo-wide and carries no scope, so a run bounded to
+    a subdirectory neither reads nor writes it and keeps its own unshared build.
+  - **`--diff` parsed the repository once per side.** The IR does not depend on which profiles
+    are asked about — only the resolution over it does — so the second side now costs the
+    resolution alone: 2.3 s warm for a two-set comparison, the shape a per-PR gate runs.
+
+- **A degraded run now states the effect of the degradation** — invariant **I-8**, accepted and
+  enforced (C3-27, and the class field evaluation #5 named). `review-pr` published
+  `analysis_limiter: {"missing_signals": ["dependency_graph", "import_graph"]}`: what was
+  absent, and nothing about what its absence changed. A reader could not tell whether the answer
+  was a floor, a ceiling or unaffected — the same defect shape as `statically_unreferenced: 0`,
+  one level up.
+  - Every signal a command can report as missing now carries **what it feeds**, **what the
+    answer does without it**, and a **`direction`**: `under_reports` (read the answer as a
+    floor — absence of a finding is not evidence of none), `over_reports` (a ceiling), or
+    `undetermined`. Mixed directions collapse to `undetermined`: an answer that is a floor in
+    one place and a ceiling in another is neither. The block ends with one sentence on how to
+    read the result, and the GitHub comment prints it beside the `OMITTED` badge — a reviewer
+    reads the comment, not the JSON.
+  - One authority (`sourcecode/degradation.py`) serves every emitter, and the battery discovers
+    signal names **from the source by AST**, so a signal added without an effect statement fails
+    the suite. That scan found a second emitter the field never reached: **`archetype`** declares
+    `repo_ir_subsystem_masses` and `semantic_ir_spi_fanin` missing on *every* run — signals wired
+    into no release — and its missing `endpoints` signal enters the score as `0.0` rather than as
+    unknown, so an HTTP-facing repository is scored as if it exposed no HTTP surface. Both now
+    say so in the payload; correcting the score itself is separate work.
+  - **The second family is now covered too: what the product cuts on purpose.** A missing signal
+    is something the run did not have; a **cap** is something it had and chose not to publish.
+    Those said only *that* they capped — `"_truncation_summary": {"total_omitted_items": 1442}`,
+    `"bfs_truncation_reason": "hub_class_depth_cap"`, `"is_stale": true` — and a count of omitted
+    items is not an effect. `CAP_EFFECTS` gives each one the same three fields plus a fourth,
+    `exact`, which is what separates a cap from a missing signal: what survived the cut.
+    - **The output budget** publishes the least intuitive effect of all: *nothing moved*. Every
+      figure is computed before serialisation, so the counts stay exact and only the lists became
+      samples — and deriving a count from a truncated list is exactly how the field arrived at
+      four contradictory fan-in figures. The block now says so, and the battery asserts a trimmed
+      payload keeps its count.
+    - **Display caps** (`impact-chain --limit`, `impact`'s 30-class sample, `retrieve --limit`)
+      state that the total beside the list was computed over the whole population, so list and
+      total disagreeing is construction, not contradiction.
+    - **The hub-class depth cap** names every figure it turns into a floor — indirect callers and
+      the endpoints, transaction boundaries, security surface and risk score derived from them —
+      and every figure it leaves exact. A zero under a cap means the capped walk found none.
+    - **A stale snapshot** is `undetermined`, not a floor: it describes a different tree, so a
+      symbol added since is missing *and* a symbol deleted since is still listed.
+    - **An unavailable section** (`migrate-check --blast-radius` when the IR cannot be built)
+      says the failure is bounded to that block and the findings beside it are untouched.
+    - Same enforcement as the signal family: the battery discovers cap names from the source by
+      AST, so a cap applied without an effect statement fails the suite.
+
+- **A run that succeeded now writes nothing to stderr** (C3-26). PowerShell 5.1 — a declared
+  target platform — turns any stderr write from a native command into a `NativeCommandError`,
+  so an informational line makes a successful run look like a failed one and forces the caller
+  to swallow errors it should be reporting. Measured non-TTY before fixing: `migrate-check`
+  wrote a size advisory, `validation` a note about an empty result, `explain` a cache hit/miss
+  line; everything else was already clean. Those three now go through one seam (`cli._notice`)
+  that speaks only when stderr is a terminal. No `--quiet` flag: a flag has to be remembered by
+  every caller, on the platform where forgetting it is fatal.
+  - **`cache warm` and `cache clear` print their status on stdout**, where `cache status` in the
+    same group already printed it. Their status *is* their answer — on stderr, `ask cache warm >
+    log.txt` captured nothing at all.
+  - Errors keep stderr, where they pair with a non-zero exit; `tests/test_stderr_purity_matrix.py`
+    asserts both halves across 13 commands through a real subprocess, because a CliRunner blurs
+    the two streams — which is how three of these survived the stdout-purity battery that
+    already existed.
+
+- **Every example the CLI prints now parses against the CLI that prints it** (C3-16). The root
+  help led its gating panel with `pr-impact . --since main`; `pr-impact` has no `--since`. It
+  was reported by three field evaluations and survived all three, because the check was a
+  person re-reading a hand-written block — and the header panels print invocations *without*
+  the `ask ` prefix, so even grepping for `ask ` missed it. The example is now
+  `pr-impact . --files -` (the stdin form, verified against a real `git diff --name-only`), and
+  `tests/test_help_examples.py` extracts all 156 invocations from every help screen — root
+  panels, command docstrings, group and subcommand help — and parses each one against the
+  command it names. The battery states its own scope: the command and its options exist and
+  take the arity given; values are not validated and nothing is executed.
+
+- **One class, four fan-in figures — two of them wrong about their own unit** (C1-16, field
+  evaluation #5). On `org.broadleafcommerce.common.money.Money` the product published 1 868,
+  673, 418 and 151 under names that all read as fan-in, and the note written to pre-empt that
+  confusion promised an ordering (`modernize.in_degree` *"always the largest"*, the other two
+  within *"a small margin"*) that measurement falsified by 2,8× and 177 %. This is the number
+  a risk decision is taken with: *"¿el blast radius son 484 o 611 clases?"*
+  - **`impact.stats.direct_caller_count` counted caller *symbols*** — 418, of which 346 were
+    method-level, so a class was counted once per method touching the target. It now counts
+    **distinct classes** (134) with the reference sites beside it as
+    **`direct_caller_symbol_count`** (418). The risk score still weighs reference sites; it was
+    the published unit that was false. `direct_callers` is a class list (`direct_caller_symbols`
+    keeps the sites), so the array and its count are finally the same unit.
+  - **`explain.incoming_callers` deduplicated by simple name**, collapsing 186 distinct classes
+    into 151 and dropping 35 real dependents. Identity is the FQN; a colliding simple name is
+    rendered qualified. New **`incoming_callers_count`** is measured before the `--limit` cap,
+    so a consumer never has to take `len()` of a truncated array.
+  - **`impact-chain.metadata.callers_total` was the size of the whole chain**, not fan-in, and
+    was absent from the note. It stays (removing a published key is breaking) and now says so,
+    beside **`chain_classes_total`** (441) and **`direct_caller_count`** (134) — which equals
+    `impact`'s figure by construction. `explain` is a declared superset: it admits import-only
+    references, a blast radius does not.
+  - **The note is generated from a registry** (`caller_metrics.FAN_IN_FIGURES`), each figure
+    carrying its unit and the references it admits, and the battery asserts every figure appears
+    with its unit. No ordering between units is promised any more — the three falsified phrases
+    are banned by test. Registered as fact `caller_fan_in` (ADR-0008 R11-R14).
+  - `compare`'s evidence trail read `len()` of the 30-item display array and told every hub
+    class in the repository it had "30 direct callers". It reads `stats` now.
+  - Still open and stated rather than guessed: `impact` reports `endpoints_affected_count: 0`
+    where `impact-chain` returns 21 endpoints for the same class. Measured today, the two
+    traversals reach different populations (259 vs 441 classes at full depth), so that half is
+    engine reach, not presentation.
+
+- **A command must not answer a question about a repository it could not read** (C3-22, C3-23,
+  the robustness finding of field evaluation #5 — *"un gate que puede pasar sin analizar nada
+  es peor que no tener gate, porque genera confianza injustificada"*). The same nonexistent
+  path produced four different behaviours: six commands refused it correctly, `verify`
+  answered `{"verdict": "pass", "exit_code": 0}`, `posture` answered an all-zeros payload with
+  exit 0, `archetype` raised a `FileNotFoundError` traceback through the JSON-always contract,
+  and `cold-start` reported `no_ris`. In `ask verify $DIR --fail-on new`, one typo in the
+  variable was a permanently green pipeline.
+  - **One admission authority** (`sourcecode.path_admission`): "can this path be analysed?" is
+    one fact, so **25 path-taking commands** now derive it in one place instead of twenty
+    inline copies plus four omissions. The refusal carries a machine-readable **`reason`** —
+    `missing`, `not_a_directory`, or `unreadable`.
+  - **`unreadable` is new and was not in the field report.** A directory that exists but cannot
+    be listed produced the same `archetype` traceback; it is now refused before the scan starts.
+  - **`verify` and `verify-edit` refuse with exit 2, not 1.** Their published contract reserves
+    2 for *unverified* — the run that could not look — as distinct from 1, the run that looked
+    and found violations. A gate that never analysed anything reports neither `pass` nor a
+    violation count.
+  - **`impact-chain` and `impact` name the repository they actually read.** A path in the
+    symbol slot made them report `not_found` about the current working directory. A file path
+    is still a legitimate symbol; a symbol that *is* a directory, or that carries a path
+    separator and does not exist, now says which repository was analysed and how the arguments
+    are ordered.
+  - The battery discovers path-taking commands from the CLI itself: a new command that skips
+    the gate fails the suite.
+
+- **An effort figure is a point only when nothing under it is a range** (C1-12, the third
+  reconciliation gate of field evaluation #4). `migrate-check` folded the Hibernate 5→6 slice
+  into the headline as the **midpoint** of a range the same report labels `confidence: low`,
+  and that the Hibernate effort model itself calls a non-deduplicated *upper bound*. Measured
+  on the battery: BroadleafCommerce billed **157.7 d, 153.7 of them (97%) from 76.5–230.8**;
+  openmrs-core 76.4 d with 62.2 (81%) from 28.9–95.6. The arithmetic was right and the claim
+  was still false — a 3× span presented as one number.
+  - New top-level **`estimated_effort_range_days`** `{low, high, confidence, basis}`. The band
+    is the worst confidence of the contributing slices; findings effort is a per-file
+    measurement and enters as a point.
+  - **`estimated_effort_days` is `null`** when a range slice is in the total (never `0` — that
+    reads as "no work"), and stays a number on every repo where no range applies. The text
+    report prints the span: `Estimated effort: 80.6–234.9d (low confidence — not a point
+    estimate)`.
+  - `effort_breakdown.hibernate_rewrite_effort_days` is `null`: the midpoint is not a
+    measurement of anything, so it is no longer published. The range sits beside it in
+    `hibernate_rewrite_range`, with `hibernate_rewrite_effort_basis` and `unestimated_slices`.
+  - **An inferred version buys no number.** When the 5→6 axis applies only because a Spring
+    Boot 2 BOM manages Hibernate 5.x — no version declared in the build — the rewrite *scope*
+    is a hypothesis: the slice contributes neither a point nor a range, and the gap is named.
+    The readiness dimension stays applicable; not estimating is not pretending it is absent.
+  - Readiness snapshots/trends carry `estimated_effort_low_days` / `estimated_effort_high_days`
+    so the series does not go blind exactly where the effort is largest.
 
 ## [3.4.0] — 2026-07-29
 

{sourcecode-3.4.0 → sourcecode-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.4.0
+Version: 3.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
@@ -220,8 +220,8 @@ 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` · `retrieve` |
-| **parked** | kept working, no longer developed | none today |
+| **experimental** | shape may change in a minor — do not gate CI on it | `posture` · `archetype` |
+| **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
 (`cli.COMMAND_TIERS`) — the battery fails if a command is in no tier, or if this file drifts
@@ -252,7 +252,7 @@ from it.
 | `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 |
-| `retrieve` | experimental | typed knowledge queries over the model | |
+| `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 | |
 | `cache status\|warm\|model\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | supported | housekeeping | `activate` too |

{sourcecode-3.4.0 → sourcecode-3.5.0}/README.md

@@ -182,8 +182,8 @@ 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` · `retrieve` |
-| **parked** | kept working, no longer developed | none today |
+| **experimental** | shape may change in a minor — do not gate CI on it | `posture` · `archetype` |
+| **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
 (`cli.COMMAND_TIERS`) — the battery fails if a command is in no tier, or if this file drifts
@@ -214,7 +214,7 @@ from it.
 | `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 |
-| `retrieve` | experimental | typed knowledge queries over the model | |
+| `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 | |
 | `cache status\|warm\|model\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | supported | housekeeping | `activate` too |

{sourcecode-3.4.0 → sourcecode-3.5.0}/pyproject.toml

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

{sourcecode-3.4.0 → sourcecode-3.5.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.4.0"
+__version__ = "3.5.0"

{sourcecode-3.4.0 → sourcecode-3.5.0}/src/sourcecode/archetype.py

@@ -30,6 +30,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Optional
 
+from sourcecode.degradation import analysis_limiter as _analysis_limiter
 from sourcecode.graph_evidence import GraphEvidence, GraphEvidenceProvider, GraphEvidenceResult
 from sourcecode.schema import SourceMap
 from sourcecode.tree_utils import flatten_file_tree
@@ -157,6 +158,9 @@ class ArchetypeAnalysis:
             },
             "signals_used": self.signals_used,
             "signals_missing": self.signals_missing,
+            # I-8: the names alone say nothing about what the classification lost.
+            # Same authority the review-pr limiter uses, so both read alike.
+            "analysis_limiter": _analysis_limiter(self.signals_missing),
             "generated_from": self.generated_from,
             "graph_metrics": {k: round(v, 4) for k, v in self.graph_metrics.items()},
         }

{sourcecode-3.4.0 → sourcecode-3.5.0}/src/sourcecode/cache_model.py

@@ -125,10 +125,11 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "`--env-map`, `--depth N` and `--exclude` change the *analysis*, so they miss the "
                  "warmed core and rescan — this is the 171 s the field measured after a 103 s warm.",
                  "--compact 17.7 s → 0.3 s; --agent --full --env-map --depth 20 34.7 s → 33.9 s (no gain)"),
-    CommandCache("posture", ("parse",), "shared", False,
-                 "Resolves the conditional bean graph on every run; a warm saves it the Java parse, "
-                 "which is the smaller half of its work.",
-                 "24.5 s → 19.3 s"),
+    CommandCache("posture", ("cir", "parse"), "shared", False,
+                 "Resolves the conditional bean graph on every run, over the shared CIR a warm "
+                 "builds — the parse it used to repeat for itself. `--diff` compares two profile "
+                 "sets over that one IR, so the second side costs the resolution only.",
+                 "10.1 s → 1.6 s"),
     CommandCache("endpoints", ("ris", "parse"), "none", False,
                  "Recomputes the endpoint surface on every run and refreshes the RIS endpoint index. "
                  "Measured: a warm buys it nothing.",

sourcecode-3.5.0/src/sourcecode/caller_metrics.py

@@ -0,0 +1,168 @@
+"""The authority for "how many things reference this class" (ADR-0008, R11-R14).
+
+Several commands publish such a number. They are not the same number, and the
+gap is not a rounding margin: measured on `org.broadleafcommerce.common.money.Money`
+(BroadleafCommerce, one version, one machine) the product published **four**
+figures — 1 868, 673, 418 and 151 — under names that all read as fan-in. Field
+evaluation #5 asked the only question that matters about that: *"¿el blast radius
+son 484 o 611 clases?"*
+
+The previous version of this module promised a relationship in prose:
+`modernize.in_degree >= explain.incoming_callers ~= impact.stats.direct_caller_count`,
+with `in_degree` *"always the largest of the three"* and the other two differing
+*"by a small margin"*. Measurement falsified both halves — `impact-chain` was not
+in the relationship at all and was 2,8× the figure declared always-largest, and
+the *"small margin"* was 177 %. A published relationship is a contract, so this
+module no longer publishes prose: it publishes a **registry of figures**, each
+with its unit and its edge population, and the note is *generated* from it. What
+the battery can assert is what the registry says, which is why it cannot drift
+again.
+
+Two of the four figures were also wrong about their own unit, and that is the
+defect underneath the divergence:
+
+- `impact.stats.direct_caller_count` counted caller **symbols** — 418, of which
+  346 were method-level — while its own note called them distinct classes. The
+  same class was counted once per method that touches the target. As classes:
+  **134**.
+- `explain.incoming_callers` deduplicated by **simple name**, collapsing 186
+  distinct classes into 151 and silently dropping 35 of them (the identity rule
+  that made `by_controller` keys FQNs applies here too).
+
+With both fixed, the residual difference is a *declared* one: `impact` excludes
+`imports` edges from a blast radius (an import is not a runtime dependency,
+FP-001) and `explain` includes them, so `explain` counts a superset. That is a
+fact about populations, stated per figure, not a promise about magnitudes.
+"""
+from __future__ import annotations
+
+from typing import Iterable
+
+from sourcecode.fqn_utils import normalize_owner_fqn
+
+#: Unit tags. Two figures are comparable only if both agree.
+UNIT_CLASSES = "distinct_classes"
+UNIT_SYMBOLS = "caller_symbols"
+UNIT_EDGES = "graph_edges"
+
+#: Population tags — *which* references were admitted, not how they were counted.
+POP_REFERENCES_WITH_IMPORTS = "references_including_imports"
+POP_REFERENCES_NO_IMPORTS = "references_excluding_imports"
+POP_ALL_EDGES = "all_incoming_edges"
+POP_TRANSITIVE_CHAIN = "transitive_chain"
+
+
+def caller_classes(symbols: Iterable[str], *, exclude: Iterable[str] = ()) -> set[str]:
+    """The distinct classes behind a set of caller symbols — the fan-in unit.
+
+    A caller list mixes granularities: `pkg.Utils`, `pkg.Utils#getMoney`,
+    `pkg.Utils.field`. Counting it raw answers "how many references" and calls
+    it "how many classes". This is the one place that normalisation happens.
+    """
+    excluded = {normalize_owner_fqn(e) for e in exclude}
+    out: set[str] = set()
+    for sym in symbols:
+        if not sym:
+            continue
+        owner = normalize_owner_fqn(sym)
+        if owner and owner not in excluded:
+            out.add(owner)
+    return out
+
+
+def caller_class_count(symbols: Iterable[str], *, exclude: Iterable[str] = ()) -> int:
+    """``len(caller_classes(...))`` — the number a fan-in figure may publish."""
+    return len(caller_classes(symbols, exclude=exclude))
+
+
+#: Every published fan-in figure, with what it counts. A figure that is not here
+#: is not allowed to be emitted (asserted by `tests/test_fan_in_authority.py`).
+FAN_IN_FIGURES: tuple[dict[str, str], ...] = (
+    {
+        "key": "explain.incoming_callers_count",
+        "unit": UNIT_CLASSES,
+        "population": POP_REFERENCES_WITH_IMPORTS,
+        "means": "distinct classes that reference this class, imports included",
+    },
+    {
+        "key": "impact.stats.direct_caller_count",
+        "unit": UNIT_CLASSES,
+        "population": POP_REFERENCES_NO_IMPORTS,
+        "means": "distinct classes that call or depend on this class; import-only "
+                 "references are excluded from a blast radius",
+    },
+    {
+        "key": "impact.stats.direct_caller_symbol_count",
+        "unit": UNIT_SYMBOLS,
+        "population": POP_REFERENCES_NO_IMPORTS,
+        "means": "the same population counted as reference sites (methods and "
+                 "fields), which is what the risk score weighs",
+    },
+    {
+        "key": "impact-chain.metadata.chain_classes_total",
+        "unit": UNIT_CLASSES,
+        "population": POP_TRANSITIVE_CHAIN,
+        "means": "every class in the call chain, direct AND transitive — a reach "
+                 "figure, not fan-in; unbounded above by any direct-caller count",
+    },
+    {
+        "key": "impact-chain.metadata.direct_caller_count",
+        "unit": UNIT_CLASSES,
+        "population": POP_REFERENCES_NO_IMPORTS,
+        "means": "distinct classes calling the target at depth 1",
+    },
+    {
+        "key": "modernize.in_degree",
+        "unit": UNIT_EDGES,
+        "population": POP_ALL_EDGES,
+        "means": "incoming graph edges at symbol level, not deduplicated to "
+                 "classes — a ranking weight, never a count of classes",
+    },
+)
+
+
+def _render_reconciliation() -> str:
+    lines = [
+        "Fan-in figures differ across commands because they count different "
+        "things. Each figure below states its unit and the references it admits; "
+        "two figures are comparable only when both match. No ordering between "
+        "units is promised — an earlier version of this note promised one and "
+        "measurement falsified it."
+    ]
+    for fig in FAN_IN_FIGURES:
+        lines.append(f"{fig['key']} [{fig['unit']}] = {fig['means']}.")
+    lines.append(
+        "Any list of callers in the payload may be truncated for output size and "
+        "is a display sample: read the *_count fields, never len() of the array."
+    )
+    return " ".join(lines)
+
+
+CALLER_METRIC_RECONCILIATION: str = _render_reconciliation()
+
+#: Kept for the payload key that was `callers_total` before it was named for what
+#: it counts. Consumers reading the old key get the same number and this note.
+CALLERS_TOTAL_DEPRECATION: str = (
+    "metadata.callers_total is the size of the whole call chain (direct + "
+    "transitive), not a fan-in count; it is superseded by "
+    "metadata.chain_classes_total and metadata.direct_caller_count."
+)
+
+
+# Cycle / tangle metrics come from TWO different graphs. Both are correct; they
+# answer different questions, and without saying so the pair reads as one command
+# contradicting another (external audit 2026-07-25: modernize reported 15 cyclic
+# tangles while retrieve subsystem-coupling reported import_cycles: 0).
+CYCLE_METRIC_RECONCILIATION: str = (
+    "Cycle metrics differ across commands BY DESIGN. modernize.cross_module_tangles "
+    "is computed over the SYMBOL dependency graph, aggregated to subsystem packages: "
+    "coupling_type=cyclic means two subsystems reference each other (a 2-cycle "
+    "between package groups). The module-graph metrics (import_cycles, cyclic_density, "
+    "scc_mass — used by archetype and the subsystem-coupling retrieval intent) are "
+    "computed over the MODULE/DIRECTORY graph, are bounded for cost (node/edge caps), "
+    "and count strongly-connected components among modules. A repo can therefore "
+    "show mutual package-level coupling (tangles > 0) with no module-level SCC "
+    "(import_cycles = 0): the coupling exists between package groups inside the same "
+    "module. Neither number invalidates the other — read tangles for decomposition "
+    "risk and import_cycles for module-graph topology."
+)