sourcecode 4.16.0__py3-none-any.whl → 4.18.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.18.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:
@@ -8222,14 +8285,20 @@ def spring_audit_cmd(
     )
     _stopped_early: Optional[str] = None
 
+    from sourcecode import context_cache as _ctxcache
+
     phase = f"auditing {len(file_list)} Java files"
     with _expensive_analysis_scope("spring-audit", target, phase):
         _prog = Progress()
         _prog.start(phase)
         try:
-            cir = ContextGraph.build(
-                file_list, target, progress=_work_sink(_prog)
-            ).cir
+            # The parse is ~89 % of this command's wall clock (measured: 8,54 s of
+            # 9,53 s on a 1 303-file repository) and it is the same parse the other
+            # knowledge commands share, so it is fetched rather than rebuilt — which
+            # is what makes a warm worth anything here (cold == warm before C3-94).
+            cir = _ctxcache.shared_cir(
+                target, file_list, progress=_work_sink(_prog)
+            )
             # 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
@@ -8395,8 +8464,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 +8495,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 +9048,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 +9342,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")
@@ -9854,7 +9972,7 @@ def _migration_blast_radius(
         from sourcecode.spring_model import SpringSemanticModel
 
         try:
-            cir, _ = _ctxcache.get_or_build_cir(_resolve_repo_root(target), target, file_list)
+            cir = _ctxcache.shared_cir(target, file_list)
         except Exception:
             cir = ContextGraph.build(file_list, target).cir
         model = SpringSemanticModel.build(cir)
@@ -10408,10 +10526,7 @@ def impact_chain_cmd(
     # a fresh build, exactly as explain does, so impact-chain never breaks.
     from sourcecode import context_cache as _ctxcache
     try:
-        cir, _ = _ctxcache.get_or_build_cir(
-            _resolve_repo_root(target), target, file_list,
-            progress=_work_sink(_prog),
-        )
+        cir = _ctxcache.shared_cir(target, file_list, progress=_work_sink(_prog))
     except Exception:
         cir = ContextGraph.build(file_list, target, progress=_work_sink(_prog)).cir
     _model = SpringSemanticModel.build(cir)
@@ -10737,11 +10852,13 @@ def explain_cmd(
         )
         raise typer.Exit(code=1)
 
-    # AI Context Cache — operates at the *knowledge* level: it caches the
-    # reusable Canonical IR (the expensive Java parse), keyed only by knowledge
-    # state, not by command. explain then derives its answer cheaply from that
-    # shared CIR. The same cached CIR is reused for free by any other command.
-    # Provider-agnostic and best-effort: any fault degrades to a fresh build.
+    # AI Context Cache — operates at the *knowledge* level: it caches the reusable
+    # Canonical IR (the expensive Java parse), keyed by knowledge state and by the
+    # analysed set, not by command. explain then derives its answer cheaply from
+    # that shared CIR, and any other command over the same files reuses it for
+    # free. Provider-agnostic and best-effort: any fault degrades to a fresh build.
+    # This call site keeps the lower-level entry point because it reports the
+    # lookup (`_cc_look`); `shared_cir` is the same door without the receipt.
     _prog = Progress()
     _prog.start(f"explaining {class_name} ({len(file_list)} files)")
     _cc_look = None
@@ -11782,7 +11899,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 +11922,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 +11935,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 +12000,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/context_cache.py

@@ -651,6 +651,33 @@ class KnowledgeLookup:
         return f"Context cache: MISS  (build {self.build_ms:.0f}ms)"
 
 
+def analysed_set_signature(root: Path, file_list: list[str]) -> str:
+    """Fingerprint of *what was analysed*: the scope root and the exact file set.
+
+    The shared CIR is keyed on knowledge state, and until C3-94 "knowledge state"
+    was read as the worktree alone — which is only half of it. A run bounded to a
+    subdirectory parses a *subset* of the same worktree, and the resulting CIR is
+    a different artifact answering a different question. Keyed on the worktree
+    alone, both artifacts collided on one entry: measured on a 861-file repository,
+    ``explain WebUtil <repo>/web`` stored a 42-file / 382-symbol CIR under the
+    repo-wide key, and the next repo-wide command read it and answered about 3 % of
+    the repository — silently, because the reader passes its own ``file_paths`` to
+    ``ir_dict_to_canonical`` and the reconstructed CIR then reports 861 files
+    beside 382 symbols.
+
+    So the analysed set is stated, not hoped for. The scope path and the file list
+    are both in it: two roots can yield the same file count, and a caller that
+    filters its list (tests in or out) is asking about a different population than
+    one that does not.
+    """
+    payload = "".join([
+        str(root.resolve()),
+        str(len(file_list)),
+        hashlib.sha256("\n".join(sorted(file_list)).encode("utf-8")).hexdigest(),
+    ])
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]
+
+
 def get_or_build_cir(
     repo_root: Path,
     root: Path,
@@ -662,11 +689,19 @@ def get_or_build_cir(
     """Return ``(CanonicalRepositoryIR, KnowledgeLookup)``, caching the CIR.
 
     This is the knowledge-level entry point. It caches the **reusable** raw IR
-    (the expensive Java parse) keyed only by knowledge state — not by command —
-    so every command that needs a CIR shares one cache entry. On a hit the full
-    CIR is rebuilt cheaply from the cached raw IR via ``ir_dict_to_canonical``,
-    skipping the parse entirely. Best-effort: any cache fault falls back to a
-    fresh build.
+    (the expensive Java parse) keyed by knowledge state and by the analysed set —
+    not by command — so every command that parses the same files shares one cache
+    entry. On a hit the full CIR is rebuilt cheaply from the cached raw IR via
+    ``ir_dict_to_canonical``, skipping the parse entirely. Best-effort: any cache
+    fault falls back to a fresh build.
+
+    A **repo-wide** run (``root`` is ``repo_root``) owns the scope-free entry —
+    the one :func:`peek_cir` reads without knowing any file list, which is why
+    that key must stay free of one. Every **bounded** run keys on its own analysed
+    set instead, so it can neither read nor overwrite the repo-wide answer. Either
+    way the entry carries the analysed signature it was built from and a reader
+    whose set does not match rebuilds: the key prevents the collision, the check
+    makes the prevention verifiable rather than assumed (C3-94).
 
     `progress` is the (done, total, stage) sink the caller's heartbeat reads
     (C3-56). It reaches only the *building* paths, which is the honest place for
@@ -684,14 +719,23 @@ def get_or_build_cir(
         cir = build_canonical_ir(file_list, root, since=since, progress=progress)
         return cir, KnowledgeLookup(hit=False, enabled=False)
 
-    key = cache.knowledge_key(SCOPE_JAVA_CIR, options={"since": since} if since else None)
+    analysed = analysed_set_signature(root, file_list)
+    options: dict[str, Any] = {"since": since} if since else None
+    if root.resolve() != repo_root.resolve():
+        # A bounded run: its own entry, never the repo-wide one.
+        options = dict(options or {})
+        options["analysed"] = analysed
+    key = cache.knowledge_key(SCOPE_JAVA_CIR, options=options)
 
     t0 = time.perf_counter()
     cached = cache.get(key)
     lookup_ms = (time.perf_counter() - t0) * 1000
     if cached is not None:
         raw = cached.payload.get("raw_ir")
-        if isinstance(raw, dict):
+        stored = (cached.metadata or {}).get("analysed_set")
+        # An entry written before C3-94 carries no signature; it cannot be shown to
+        # describe this analysed set, so it is not served as if it did.
+        if isinstance(raw, dict) and stored == analysed:
             try:
                 cir = ir_dict_to_canonical(raw, file_paths=file_list)
                 if not validate_canonical_ir(cir):
@@ -708,6 +752,8 @@ def get_or_build_cir(
                 "scope": SCOPE_JAVA_CIR,
                 "cir_hash": cir.cir_hash,
                 "schema_version": cir.schema_version,
+                "analysed_set": analysed,
+                "analysed_root": str(root.resolve()),
                 "file_count": len(cir.files),
                 "symbol_count": len(cir.symbols),
             },
@@ -725,6 +771,41 @@ def get_or_build_cir(
     return cir, KnowledgeLookup(hit=False, enabled=True, build_ms=build_ms)
 
 
+def repo_root_of(root: Path) -> Path:
+    """The enclosing git root, or *root* itself outside a repository."""
+    candidate = root.resolve()
+    while True:
+        if (candidate / ".git").exists():
+            return candidate
+        if candidate.parent == candidate:
+            return root.resolve()
+        candidate = candidate.parent
+
+
+def shared_cir(
+    root: Path,
+    file_list: list[str],
+    *,
+    since: Optional[str] = None,
+    progress: "Optional[Callable[[int, int, str], None]]" = None,
+) -> Any:
+    """The Java CIR for *root*, from the shared knowledge cache.
+
+    The one door for a command that needs the repository parse and does not care
+    where it comes from: it resolves the enclosing repository itself, so a caller
+    holds no opinion about cache scope — the reason each call-site that built its
+    own CIR was one more place for the scope rule to be got wrong (C3-94).
+
+    Best-effort by construction: `get_or_build_cir` degrades to a fresh build on
+    any cache fault, so the answer never depends on the cache being there.
+    """
+    cir, _lookup = get_or_build_cir(
+        repo_root_of(root), Path(root).resolve(), file_list,
+        since=since, progress=progress,
+    )
+    return cir
+
+
 def peek_cir(
     repo_root: Path,
     *,
@@ -755,6 +836,12 @@ def peek_cir(
     raw = cached.payload.get("raw_ir")
     if not isinstance(raw, dict):
         return None
+    # The caller is promised the *repo-wide* CIR, so the entry has to say it is one.
+    # C3-94 makes the key unreachable to bounded runs; this re-reads the fact from
+    # the entry rather than inferring it from the key, and treats an entry written
+    # before that guarantee (no recorded root) as a miss.
+    if (cached.metadata or {}).get("analysed_root") != str(repo_root.resolve()):
+        return None
     try:
         cir = ir_dict_to_canonical(raw, file_paths=None)
         # validate_canonical_ir returns a LIST of problems — empty means valid.

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)