sourcecode 4.15.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.15.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:
@@ -8230,6 +8293,14 @@ def spring_audit_cmd(
             cir = ContextGraph.build(
                 file_list, target, progress=_work_sink(_prog)
             ).cir
+            # C3-85: the stretch between the last `linking` tick and the first rule
+            # tick reports nothing, and what stays on the line is `n/n` — a counter
+            # that finished, reading as a stage still running. Measured on keycloak
+            # (5 486 files, warm): **8,2 s of a 24 s run, 34 %**, all of it here.
+            # It has no population to count — it is one walk that builds the model
+            # every rule then reads — so it is named, which is what C3-56 does for
+            # a stage whose denominator would have to be invented.
+            _prog.update(f"building the semantic model over {len(file_list)} Java files")
             _model = SpringSemanticModel.build(cir)
             _run.checkpoint("ir")
             # The IR is built; the rule passes are the work now, and they are not
@@ -8353,37 +8424,15 @@ def spring_audit_cmd(
 
             data = combined.to_compact_dict() if compact else combined.to_dict()
             if _stopped_early:
-                data["_partial"] = _run.status(_stopped_early)
-                if _rules_partial:
-                    # C3-79: neither run nor not-run. How far it got is what a
-                    # reader needs to decide whether to re-run with more time, and
-                    # the findings it produced before the cut are in the payload.
-                    data["_partial"]["rules_partially_run"] = _rules_partial
-                    data["_partial"]["how_to_read"] += (
-                        " One rule family was stopped part-way through its own "
-                        "population: "
-                        + "; ".join(
-                            f"{'/'.join(entry['rule_ids'])} after "
-                            f"{entry['units_done']} of {entry['units_total']} "
-                            f"{entry['unit']}"
-                            for entry in _rules_partial
-                        )
-                        + ". What it found before the cut is reported and is a floor."
-                    )
-                if _rules_cut:
-                    # C3-71: a phase stopped *inside* is neither completed nor
-                    # pending, and calling it either would misreport the run. The
-                    # families it did not reach are named instead.
-                    data["_partial"]["rules_not_run"] = _rules_cut
-                    # A phase that was stopped inside is in neither list, and
-                    # putting it in `phases_pending` alone would claim none of it
-                    # ran when most of it did.
-                    data["_partial"]["phases_stopped_inside"] = _phases_cut
-                    data["_partial"]["how_to_read"] += (
-                        " The rule pass was stopped between families: "
-                        f"{', '.join(_rules_cut)} did not run, so every count here "
-                        "is a floor over the families that did."
-                    )
+                # C3-87: the block is composed by `PhasedRun.status`, which is the
+                # authority `risk` is now bound to as well — one vocabulary for
+                # "the budget cut this run", not one per command.
+                data["_partial"] = _run.status(
+                    _stopped_early,
+                    rules_partially_run=_rules_partial,
+                    rules_not_run=_rules_cut,
+                    phases_stopped_inside=_phases_cut,
+                )
 
             # Non-fatal RIS side-effect — persist summary only (not full findings).
             try:
@@ -8409,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=(
@@ -8425,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)
 
@@ -8949,10 +9015,18 @@ def risk_cmd(
                 profiles=_profile_set(profile),
                 # C3-73: 54 minutes with one line on stderr in the field. The
                 # factory hands the composer an observer per counted stage.
+                #
+                # C3-87: and the observer carries the deadline. This factory built
+                # its observers with no `stop_when` for four releases, so `risk`
+                # declared `budget_seconds` on the run above and then never asked
+                # whether it was spent — the budget was honoured only between the
+                # two phases. `PhasedRun.exhausted` stays the one authority; what
+                # is new is that the second consumer asks it.
                 progress=lambda stage, unit="rule families": _rule_pass_progress(
-                    _prog, stage, unit
+                    _prog, stage, unit, stop_when=_run.exhausted
                 ),
                 checkpoint=_run.checkpoint,
+                partial_status=lambda **cut: _run.status(_WHY_BUDGET, **cut),
             )
         finally:
             _prog.stop()
@@ -8968,7 +9042,10 @@ 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 "")
         ),
     )
     # The complete answer is on disk; the checkpoint that stood in for it is not
@@ -9259,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")
@@ -11785,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,
@@ -11800,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,
@@ -11813,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
@@ -11874,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")