sourcecode 4.16.0__py3-none-any.whl → 4.17.0__py3-none-any.whl

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__ = "4.16.0"
+__version__ = "4.17.0"

sourcecode/audit_report.py

@@ -12,9 +12,10 @@ import hmac
 import json
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Callable, Optional
 
 from sourcecode import __version__
+from sourcecode.partial_contract import floor_counts, read_count
 
 AUDIT_REPORT_SCHEMA = "audit-report-v1"
 
@@ -40,14 +41,30 @@ def build_audit_report(
     sign_key: Optional[bytes] = None,
     risk_limit: int = 10,
     risk_payload: Optional[dict[str, Any]] = None,
+    progress: "Optional[Callable[..., Any]]" = None,
+    checkpoint: "Optional[Callable[[str, dict], None]]" = None,
+    partial_status: "Optional[Callable[..., dict]]" = None,
 ) -> dict[str, Any]:
-    """Build the buyer-readable audit bundle from existing command payloads."""
+    """Build the buyer-readable audit bundle from existing command payloads.
+
+    C3-89. This command composes the whole of `risk`, and for four releases it did
+    so with none of the three arguments above — no observer carrying the deadline,
+    no checkpoint, no `partial_status` — while `cli` built no `PhasedRun` for it
+    either. The operator's budget therefore did not exist here at all: the field
+    measured **2 265 s under `ASK_MAX_ANALYSIS_SECONDS=300`** (7,55×), CPU-bound in
+    one worker, with no `partial` and no answer. C3-87 bound the second consumer of
+    that fact and moved the composition of the `_partial` keys into
+    `PhasedRun.status` so the third would get it by construction; this is the third.
+    """
     from sourcecode.posture import build_posture
 
     root = Path(root).resolve()
     if risk_payload is None:
         from sourcecode.risk import build_risk
-        risk = build_risk(root, limit=risk_limit, min_band="low", profiles=profiles)
+        risk = build_risk(
+            root, limit=risk_limit, min_band="low", profiles=profiles,
+            progress=progress, checkpoint=checkpoint, partial_status=partial_status,
+        )
         risk_source = "computed"
     else:
         risk = risk_payload
@@ -65,8 +82,10 @@ def build_audit_report(
         "summary": {
             "risk_model": risk.get("model"),
             "risk_source": risk_source,
-            "total_defects": risk.get("total_defects"),
-            "total_findings": risk.get("total_findings"),
+            # F-AV: read under either spelling, and republished under the one
+            # the bundle's own `summary.partial` already qualifies.
+            "total_defects": read_count(risk, "total_defects"),
+            "total_findings": read_count(risk, "total_findings"),
             "risk_bands": risk.get("by_band", {}),
             "top_risks_shown": len(top_risks),
             "endpoint_access": access.get("summary", {}),
@@ -85,6 +104,28 @@ def build_audit_report(
             "non_coverage": (risk.get("non_coverage") or {}).get("items", []),
         },
     }
+    # C3-89. A bundle whose evidence was cut says so **before** it is signed, and
+    # says it where a reader of the summary sees it — a signature over a truncated
+    # payload that does not declare the truncation is the worst artifact this
+    # product can produce. The keys come from `risk` itself, whichever way it
+    # arrived: a `--from-risk` file that was cut carries its own `_partial`, and
+    # packaging it silently would launder a floor into a verdict (C2-31's rule).
+    if risk.get("partial"):
+        unsigned["summary"]["partial"] = True
+        floor_counts(unsigned["summary"], True)  # F-AV, on the bundle too
+        unsigned["summary"]["counts_are_floor"] = True
+        unsigned["summary"]["counts_basis"] = (
+            "The risk evidence in this bundle was stopped by the analysis budget. "
+            "`total_defects` and `risk_bands` count what the families that ran "
+            "measured, and are a floor over the repository."
+        )
+        _risk_partial = risk.get("_partial")
+        if isinstance(_risk_partial, dict):
+            unsigned["_partial"] = dict(_risk_partial)
+            unsigned["_partial"]["command"] = "audit-report"
+            unsigned["_partial"]["cut_in"] = "risk"
+            if risk_source == "from-risk":
+                unsigned["_partial"]["cut_in"] = "the `--from-risk` payload"
     from sourcecode.provenance import build_evidence_manifest
     unsigned["evidence_manifest"] = build_evidence_manifest(
         unsigned,
@@ -117,7 +158,8 @@ def render_markdown(report: dict[str, Any]) -> str:
         f"- Repository: `{repo}`",
         f"- ASK version: `{(report.get('tool') or {}).get('version', '')}`",
         f"- Profile set: `{profile}`",
-        f"- Total defects: `{summary.get('total_defects')}`",
+        f"- Total defects: `{read_count(summary, 'total_defects')}`"
+        + ("  **(floor — this run was cut short)**" if summary.get("partial") else ""),
         f"- Risk bands: `{summary.get('risk_bands')}`",
         f"- Endpoint access: `{summary.get('endpoint_access')}`",
         "",

sourcecode/cli.py

@@ -24,6 +24,8 @@ from sourcecode.output_encoding import json_ensure_ascii as _json_ensure_ascii
 from sourcecode.output_encoding import set_ascii_fallback
 from sourcecode.phased_run import WHY_BUDGET as _WHY_BUDGET
 from sourcecode.phased_run import PhasedRun
+from sourcecode.partial_contract import PARTIAL_EXIT_CODE as _PARTIAL_EXIT
+from sourcecode.partial_contract import read_count as _read_count
 from sourcecode import perf
 from sourcecode.caller_metrics import (
     CALLER_METRIC_RECONCILIATION,
@@ -238,6 +240,16 @@ def _writes_help_block() -> str:
         lines.append(f"  {name.ljust(width)}  {what}")
     lines.append("")
     lines.append("  --no-write (ASK_READONLY=1) refuses all of it and says so on stderr.")
+    # F-AX: the other half of an audit that may not write — where the repository's
+    # own declaration is allowed to live.
+    lines.append(
+        "  --config <path> (ASK_CONFIG) reads the repository's declaration from "
+        "outside it,"
+    )
+    lines.append(
+        "                  so labels and custom security annotations can be "
+        "declared without writing."
+    )
     return "\n".join(lines)
 
 
@@ -746,7 +758,7 @@ def _preprocess_args(args: list[str]) -> list[str]:
 
 def _preprocess_argv() -> None:
     """Apply _preprocess_args to sys.argv in-place (used by main_entry)."""
-    modified = _preprocess_args(_apply_no_write(sys.argv[1:]))
+    modified = _preprocess_args(_apply_external_config(_apply_no_write(sys.argv[1:])))
     sys.argv = sys.argv[:1] + modified
 
 
@@ -2045,6 +2057,57 @@ NO_WRITE_OPTION_HELP = (
 NO_WRITE_FLAG = "--no-write"
 
 
+#: The one help string for `--config` (F-AX).
+CONFIG_OPTION_HELP = (
+    "Read this repository's declaration (data labels, custom security "
+    "annotations) from <path> instead of <repo>/sourcecode.config.json — so an "
+    "auditor can declare without writing into somebody else's tree. Env: "
+    "ASK_CONFIG."
+)
+
+#: Handled before the parser, for `--no-write`'s reason: a declaration honoured
+#: by some commands and not others is worse than none, because the reader cannot
+#: tell which answer used it.
+CONFIG_FLAG = "--config"
+
+
+def _apply_external_config(argv: "list[str]") -> "list[str]":
+    """Consume `--config <path>`, putting the declaration in force. Never raises.
+
+    F-AX. Under `ASK_READONLY=1` the only way to declare anything used to be a
+    file inside the analysed tree, which left `data-exposure`, the `Verified`
+    upgrade for a custom gate, and everything downstream of them unreachable by
+    construction for the exact user this mode exists for — the auditor of
+    somebody else's repository.
+    """
+    if CONFIG_FLAG not in argv:
+        return argv
+    out: "list[str]" = []
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if token != CONFIG_FLAG:
+            out.append(token)
+            index += 1
+            continue
+        value = argv[index + 1] if index + 1 < len(argv) else ""
+        if not value or value.startswith("-"):
+            print(
+                f"error: {CONFIG_FLAG} needs a path to a declaration file.\n"
+                f"       use: ask {CONFIG_FLAG} ./declarations.json <command> …",
+                file=sys.stderr,
+            )
+            raise SystemExit(2)
+        try:
+            from sourcecode import declarations
+
+            declarations.set_config_path(value)
+        except Exception:
+            pass
+        index += 2
+    return out
+
+
 def _apply_no_write(argv: "list[str]") -> "list[str]":
     """Consume `--no-write` from *argv*, putting the mode in force. Never raises."""
     if NO_WRITE_FLAG not in argv:
@@ -8395,8 +8458,23 @@ def spring_audit_cmd(
     else:
         output = _serialize_dict(data, format)
 
-    _total = combined.summary.get("total_findings", 0)
+    # F-AV: our own readers ask for the count under either spelling — the break
+    # is meant for a consumer that never asked whether the run finished.
+    _total = _read_count(combined.summary, "total_findings") or 0
     _partial_msg = " — PARTIAL, budget exhausted" if _stopped_early else ""
+    # CL-19: the payload carries `stack_fit`, and the person who most needs it is
+    # the one who will read the counts and stop. Said once, on stderr, so piped
+    # output stays byte-identical.
+    if not combined.spring_detected:
+        _notice(
+            "[ask] stack fit: no Spring detected in this scope. The access, "
+            "transaction and "
+            "Boot-readiness axes model Spring semantics and are NOT measuring "
+            "this repository — read their answers as `unknown`, never as `none`. "
+            "The structural axes (call graph, endpoint census, coupling, JDK "
+            "inventory) answer here as they do anywhere. See `stack_fit` in the "
+            "payload."
+        )
     _emit_command_output(
         output, output_path, copy,
         success_msg=(
@@ -8411,8 +8489,10 @@ def spring_audit_cmd(
 
     if ci and _stopped_early:
         # A gate on incomplete evidence must not read as a pass — the same rule
-        # `pr-impact` holds for UNKNOWN.
-        raise typer.Exit(code=1)
+        # `pr-impact` holds for UNKNOWN. F-AV: and it must not read as a *failure*
+        # either, because "the gate found something" and "the gate did not finish"
+        # call for different pipeline decisions. 75 is neither 0, 1 nor 2.
+        raise typer.Exit(code=_PARTIAL_EXIT)
     if ci and combined.findings:
         raise typer.Exit(code=1)
 
@@ -8962,7 +9042,7 @@ def risk_cmd(
         copy,
         success_msg=(
             f"risk written to {output_path} ({data['shown']} of "
-            f"{data['total_defects']} defects composed)"
+            f"{_read_count(data, 'total_defects')} defects composed)"
             # C3-87: the terminal says it too. A reader who never opens the payload
             # must not take a truncated ranking for the repository's risk.
             + (" — PARTIAL, budget exhausted" if data.get("partial") else "")
@@ -9256,26 +9336,58 @@ def audit_report_cmd(
             )
             raise typer.Exit(code=1)
 
-    _prog = Progress()
-    _prog.start("packaging audit evidence")
-    try:
-        data = build_audit_report(
-            path, profiles=_profile_set(profile), sign_key=key_bytes,
-            risk_payload=risk_payload,
-        )
-    finally:
-        _prog.stop()
+    # C3-89: this command composes the whole of `risk`, and it did so with no
+    # deadline of any kind — no `PhasedRun`, no `stop_when` on the observers, no
+    # checkpoint. The field measured 2 265 s under a 300 s budget, CPU-bound in one
+    # worker, killed by hand with nothing to show. `risk` was bound in 4.16.0
+    # (C3-87) and the composition of the `_partial` keys moved into
+    # `PhasedRun.status` precisely so the next consumer would inherit it; this is
+    # that consumer. The phases are `risk`'s own (it is the analysis being run)
+    # plus this command's packaging step.
+    _phase = "packaging audit evidence"
+    _budget = _analysis_budget("audit-report")
+    _run = PhasedRun(
+        command="audit-report",
+        root=path,
+        phases=["audit", "compose", "bundle"],
+        output_path=output_path,
+        budget_seconds=_budget.get("configured_max_seconds"),
+        budget_source=_budget.get("configured_source"),
+        writer=_safe_write_file,
+    )
+    with _expensive_analysis_scope("audit-report", path, _phase):
+        _prog = Progress()
+        _prog.start(_phase)
+        try:
+            data = build_audit_report(
+                path, profiles=_profile_set(profile), sign_key=key_bytes,
+                risk_payload=risk_payload,
+                progress=lambda stage, unit="rule families": _rule_pass_progress(
+                    _prog, stage, unit, stop_when=_run.exhausted
+                ),
+                checkpoint=_run.checkpoint,
+                partial_status=lambda **cut: _run.status(_WHY_BUDGET, **cut),
+            )
+        finally:
+            _prog.stop()
     output = render_markdown(data) if fmt == "markdown" else _serialize_dict(data, fmt)
+    _summary = data.get("summary") if isinstance(data.get("summary"), dict) else {}
     _emit_command_output(
         output,
         output_path,
         copy,
-        success_msg=f"audit report written to {output_path}",
+        success_msg=f"audit report written to {output_path}"
+        # The terminal says it too, for the same reason `risk` does: a signed
+        # bundle that was cut must not be read as the repository's audit.
+        + (" — PARTIAL, budget exhausted" if _summary.get("partial") else ""),
         # A signed artifact cannot be mutated after signing. The report carries
         # tool/version metadata itself, and `signature.payload_sha256` is over
         # the exact JSON payload the user receives.
         stamp_envelope=False,
     )
+    # The complete bundle is written; the checkpoint that stood in for it must not
+    # outlive it (C3-77's invariant, as `risk` applies it).
+    _run.discard_checkpoint()
 
 
 @app.command("migrate-recipe")
@@ -11782,7 +11894,15 @@ def schema_cmd(
     # through the command that already answers "what shape does this release
     # produce?" rather than a command of its own.
     names = available_schemas()
-    if name == "facts-v1":
+    # C4-22: one authority for *what this argument accepts*. The registry names
+    # itself (`registry_version`), so the listing, the dispatch below and the
+    # rejection all read the same value — the field's audit was told
+    # `available: ["envelope-v1"]` by a rejection that knew only half of what the
+    # very next line accepts, and concluded that was the whole published surface.
+    registries = [str(load_registry().get("registry_version") or "")]
+    registries = [r for r in registries if r]
+    accepted = list(names) + registries
+    if name in registries:
         _emit_command_output(
             json.dumps(load_registry(), indent=2, ensure_ascii=False),
             output_path,
@@ -11797,7 +11917,7 @@ def schema_cmd(
             # answers have a single authority. Both are contracts this release
             # carries, listed apart because they are not the same kind of thing.
             json.dumps(
-                {"schemas": names, "registries": ["facts-v1"]},
+                {"schemas": names, "registries": registries},
                 indent=2, ensure_ascii=False,
             ),
             output_path,
@@ -11810,10 +11930,14 @@ def schema_cmd(
     except FileNotFoundError:
         _emit_error_json(
             INVALID_INPUT_CODE,
-            f"No published schema named '{name}'.",
-            available=names,
-            hint="Run `ask schema` to list published schemas.",
-            expected="A published schema name.",
+            f"'{name}' is not a published schema or registry.",
+            available=accepted,
+            hint=(
+                "Run `ask schema` to list them: "
+                + ", ".join(accepted)
+                + "."
+            ),
+            expected="One of: " + " | ".join(accepted),
         )
         raise typer.Exit(code=1)
     # A schema document describes the envelope; stamping one into it would put
@@ -11871,8 +11995,17 @@ def config_cmd(
     _answer.say(f"Telemetry: {'enabled' if is_enabled() else 'disabled'} (off by default; opt-in)")
     _answer.say("")
 
-    _declaration_path = _repo / CONFIG_FILENAME
+    # F-AX: the declaration may sit outside the analysed tree, and *which* file
+    # answered is the first thing this command exists to say.
+    from sourcecode.declarations import config_path as _config_path, is_external
+
+    _declaration_path = _config_path(_repo) or (_repo / CONFIG_FILENAME)
     _answer.say(f"Repository: {_repo}")
+    if is_external():
+        _answer.say(
+            "Declared with --config / ASK_CONFIG — read from outside the "
+            "repository, which is unchanged by this run."
+        )
     if not _declaration_path.is_file():
         _answer.say(f"Declaration: none at {_declaration_path}")
         _answer.say(

sourcecode/data_exposure.py

@@ -40,6 +40,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, Optional
 
 from sourcecode.data_labels import DataLabel, LabelDeclaration, load_labels
+from sourcecode.declarations import source_note as _declaration_source
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
     from sourcecode.canonical_ir import CanonicalRepositoryIR
@@ -139,7 +140,10 @@ def build_data_exposure(
 
     payload: dict = {
         "schema_version": SCHEMA_VERSION,
-        "declaration": decl.to_dict(),
+        # F-AX: which file answered. A declaration read from outside the analysed
+        # tree is the auditor's case, and a payload that does not say so leaves
+        # the reader unable to reproduce the answer.
+        "declaration": {**decl.to_dict(), "source": _declaration_source()},
         "profiles": sorted(profiles) if profiles else None,
     }
 

sourcecode/data_labels.py

@@ -39,7 +39,9 @@ from pathlib import Path
 from typing import Optional
 
 #: The same file the custom security annotations are declared in.
-CONFIG_FILENAME = "sourcecode.config.json"
+#: F-AX: the name lives in `declarations`, which also decides *where* it is
+#: looked for. Re-exported so existing importers keep working.
+from sourcecode.declarations import CONFIG_FILENAME  # noqa: E402,F401
 
 #: The key under which labels are declared.
 CONFIG_KEY = "dataLabels"
@@ -108,9 +110,14 @@ def load_labels(root: Optional[Path]) -> LabelDeclaration:
     Never raises. An absent file is not a problem — it is a repository that has
     declared nothing, and the caller says so in the words of the question.
     """
-    if root is None:
+    # F-AX: the path is resolved by one authority, so `--config <external>` is
+    # honoured identically here and in `security_config` — a declaration that
+    # applied to one loader and not the other would be worse than none.
+    from sourcecode.declarations import config_path
+
+    cfg_path = config_path(root)
+    if cfg_path is None:
         return LabelDeclaration()
-    cfg_path = Path(root) / CONFIG_FILENAME
     try:
         if not cfg_path.is_file():
             return LabelDeclaration(config_file=None)

sourcecode/declarations.py

@@ -0,0 +1,81 @@
+"""declarations.py — where this repository's declaration lives. One authority.
+
+`sourcecode.config.json` is what a repository declares **about itself**: the data
+labels `data-exposure` refuses to invent, and the custom security annotations
+`spring-audit` and `posture` will not guess. Two loaders read it, and until this
+module each of them resolved the path itself, from its own copy of the filename.
+
+**F-AX.** The path also has to be allowed to sit *outside* the analysed tree. The
+use case is not hypothetical — it is the one field evaluation #20 executed: an
+auditor running over somebody else's repository under `ASK_READONLY=1`, who found
+four commands unreachable **by construction**, because the only way to declare
+anything was to write a file into a tree they had been told not to touch:
+
+    "bajo restricción read-only, cuatro comandos son inalcanzables por
+     construcción. Falta un modo --config-from <ruta externa>."
+
+So the resolution order is: an explicit `--config <path>` (or `ASK_CONFIG`),
+then `<root>/sourcecode.config.json`. The override is a whole-process decision
+like `--no-write` — a declaration that applied to some commands and not others
+would be worse than none, because the reader could not tell which answer used it.
+
+Nothing here reads or parses the file. It answers one question: *which path*.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+#: The name a repository's own declaration has when it lives in the repository.
+CONFIG_FILENAME = "sourcecode.config.json"
+
+#: The environment channel, equal in force to the flag (the `ASK_READONLY`
+#: precedent): a CI job declares once, in the environment, for every command.
+ENV_CONFIG = "ASK_CONFIG"
+
+_OVERRIDE: "Optional[Path]" = None
+
+
+def set_config_path(path: "Optional[Path | str]") -> None:
+    """Point every loader at *path* for the rest of this process. Never raises."""
+    global _OVERRIDE
+    _OVERRIDE = Path(str(path)).expanduser() if path else None
+
+
+def override() -> "Optional[Path]":
+    """The declared external path, from the flag or the environment, or None."""
+    if _OVERRIDE is not None:
+        return _OVERRIDE
+    raw = os.environ.get(ENV_CONFIG, "").strip()
+    return Path(raw).expanduser() if raw else None
+
+
+def config_path(root: "Optional[Path]") -> "Optional[Path]":
+    """Where this run's declaration is, whether or not it exists.
+
+    Returns None only when there is no candidate at all — no override and no
+    root — so a caller can distinguish *"nothing was declared"* from *"the file
+    it would have been in is absent"*, which is the distinction `ask config`
+    prints and `data-exposure` refuses on.
+    """
+    external = override()
+    if external is not None:
+        return external
+    if root is None:
+        return None
+    return Path(root) / CONFIG_FILENAME
+
+
+def is_external() -> bool:
+    """True when the declaration in force comes from outside the analysed tree."""
+    return override() is not None
+
+
+def source_note() -> str:
+    """One clause naming where the declaration came from, for a payload or a line."""
+    external = override()
+    if external is None:
+        return f"<repo>/{CONFIG_FILENAME}"
+    return f"{external} (declared with --config / {ENV_CONFIG})"

sourcecode/mcp/orchestrator.py

@@ -794,7 +794,9 @@ def run_migrate_flow_impl(repo_path: str, min_severity: str = "low") -> dict[str
                 headline[key] = report[key]
         _summary = report.get("summary", {})
         if isinstance(_summary, dict):
-            headline["total_findings"] = _summary.get("total_findings")
+            from sourcecode.partial_contract import read_count as _read_count
+
+            headline["total_findings"] = _read_count(_summary, "total_findings")
             headline["affected_files"] = _summary.get("affected_files")
             headline["by_severity"] = _summary.get("by_severity")
             headline["by_target"] = _summary.get("by_target") or _summary.get("by_rule")

sourcecode/non_coverage.py

@@ -349,6 +349,92 @@ def block(surface: str) -> dict:
     return published
 
 
+STACK_FIT_SCHEMA = "stack-fit-v1"
+
+#: The axes of this product that model **Spring** semantics, and what each one
+#: reports on a repository where no Spring is detected (CL-19). Every entry is a
+#: fact the payload already contains; what did not exist was a place that adds
+#: them up.
+_SPRING_SHAPED_AXES: "tuple[tuple[str, str], ...]" = (
+    (
+        "endpoint access policy",
+        "every handler is reported `none_detected`, because the policy this axis "
+        "reads is a declared annotation and this repository does not declare one",
+    ),
+    (
+        "effective access (posture)",
+        "every request is `access_not_decided`: the chain this axis resolves is a "
+        "Spring Security configuration",
+    ),
+    (
+        "annotation-based security findings (SEC-001)",
+        "not emitted at all — the rule states that it only applies to an "
+        "`annotation_based` security model",
+    ),
+    (
+        "declarative transaction boundaries (TX-001..006)",
+        "no boundary is found, because the boundary this axis reads is declared "
+        "with an annotation",
+    ),
+    (
+        "Spring Boot 2 -> 3 readiness",
+        "reported `applicable: false` with its reason",
+    ),
+)
+
+#: What keeps working, and is what such a repository is actually measured on.
+_STACK_INDEPENDENT_AXES: "tuple[str, ...]" = (
+    "the call graph and blast radius (`impact-chain`, `impact`, `pr-impact`)",
+    "the HTTP surface census (`endpoints`) and its request-body validation gaps",
+    "coupling, hotspots and dead-code candidates (`modernize`)",
+    "the JDK and Jakarta inventories (`migrate-check`)",
+    "contract derivation from the measured surface (`verify --init`)",
+)
+
+
+def stack_fit(spring_detected: bool) -> dict:
+    """Whether this product's Spring-shaped axes model the repository. (CL-19)
+
+    Every axis publishes its own limits, its own units and its own confidence,
+    and the run states `spring_detected` inside each payload — and **no surface
+    adds them up**. On a repository where that flag is `false`, the field
+    received six axes returning the shape of an answer (614 endpoints
+    `none_detected`, 3 152/3 152 `access_not_decided`, `security_model: unknown`,
+    TX at zero) and no sentence anywhere saying *this axis does not model your
+    stack*. The auditor had to derive it — *"tuve que deducirlo de
+    `spring_detected: false` enterrado en el JSON"* — and the verdict that
+    followed is the cost: *"una herramienta de inventario estructural muy buena
+    vendida como auditor de seguridad"*.
+
+    Returns `{}` when Spring **is** detected: a repository this product models
+    gains no field, and its payload stays byte-identical.
+    """
+    if spring_detected:
+        return {}
+    return {
+        "schema_version": STACK_FIT_SCHEMA,
+        "spring_detected": False,
+        "statement": (
+            "No Spring was detected in this scope. The axes listed under "
+            "`axes_not_measuring` model Spring semantics, so on this repository "
+            "they report an absence of MODEL, never an absence of control: read "
+            "every one of their answers as `unknown`, not as `none`. The axes "
+            "under `axes_measuring` are structural and answer here exactly as "
+            "they do anywhere else."
+        ),
+        "axes_not_measuring": [
+            {"axis": axis, "what_it_reports_here": effect}
+            for axis, effect in _SPRING_SHAPED_AXES
+        ],
+        "axes_measuring": list(_STACK_INDEPENDENT_AXES),
+        "how_to_read": (
+            "This block is a statement about the FIT between this product and "
+            "this repository. It is not a finding, and it does not lower the "
+            "confidence of anything under `axes_measuring`."
+        ),
+    }
+
+
 def reference(surface: str, *, published_at: str) -> dict:
     """A pointer to a block published elsewhere in the same document (C2-28).