sourcecode 3.5.0__py3-none-any.whl → 3.6.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__ = "3.5.0"
+__version__ = "3.6.0"

sourcecode/cli.py

@@ -857,7 +857,13 @@ def _emit_command_output(
     if output_path is not None:
         _safe_write_file(output_path, content)
         if success_msg:
-            typer.echo(success_msg, err=True)
+            # C3-26/C3-18: the payload went to the file, so stdout is free and
+            # this confirmation is the run's whole answer — `cache warm` and
+            # `cache clear` were corrected for exactly this in 3.5.0 and these
+            # three (`repo-ir`, `modernize`, `export`) were missed because the
+            # stderr battery listed its commands by hand. Measured before the
+            # fix on spring-petclinic: stdout 0 bytes, stderr 155.
+            typer.echo(success_msg)
     else:
         try:
             sys.stdout.buffer.write(content.encode("utf-8"))
@@ -874,30 +880,112 @@ def _emit_command_output(
         except AttributeError:
             sys.stdout.write(content + "\n")
         if copy and _copy_to_clipboard(content):
-            typer.echo("✓ copied to clipboard", err=True)
+            # The payload is on stdout here, so this cannot join it; it is a
+            # notice and takes the terminal gate rather than dirtying a capture.
+            _notice("✓ copied to clipboard")
 
 
 # H-06: Intercept Click-level UsageError (unknown options, bad args) and emit JSON.
 # Click's default show() writes "Error: No such option: --foo" as plain text.
 # Automation consumers need JSON on stderr regardless of how the error originated.
+def _root_level_flags() -> set[str]:
+    """Every option declared on the root command, discovered from the CLI.
+
+    Read at error time so a flag added to the root callback is covered without
+    anyone remembering to list it here — the C4-1 lesson about curated lists
+    living beside generated ones. Never raises: a failure here must not turn a
+    usage error into a traceback.
+    """
+    try:
+        import typer.main as _tm
+
+        group = _tm.get_command(app)
+        return {opt for param in group.params for opt in param.opts}
+    except Exception:
+        return set()
+
+
 try:
     import click.exceptions as _click_exc
 
+    def _misplaced_global_flag_hint(exc: Any) -> "tuple[Optional[str], Optional[str]]":
+        """(flag, hint) when a rejected option is really a root-level one.
+
+        C3-4: `ask spring-audit --full` answered "No such option: --full" about
+        a flag the tool does have — it is declared on the root command, not on
+        the subcommand, and nothing said so. Refusing is right; refusing
+        without naming where the flag lives is what cost the user the run.
+
+        The flag is looked up on the root command, so every global flag typed
+        after every subcommand is covered and no flag name is written here.
+        """
+        flag = str(
+            (getattr(exc, "option_name", None) or getattr(exc, "param_hint", None)) or ""
+        ).strip("'\"")
+        if not flag or flag not in _root_level_flags():
+            return (flag or None), None
+        cmd_path = getattr(getattr(exc, "ctx", None), "command_path", "") or ""
+        parts = cmd_path.split()
+        sub = parts[-1] if len(parts) > 1 else ""
+        hint = (
+            f"`{flag}` is a global flag: it goes before the command, "
+            f"as `ask {flag} <path>`" + (f", not after `{sub}`." if sub else ".")
+        )
+        return flag, hint
+
     def _json_click_usage_error_show(self: Any, file: Any = None) -> None:  # type: ignore[override]
         import json as _je
-        _flag = str((getattr(self, "option_name", None) or getattr(self, "param_hint", None)) or "").strip("'\"")
+        _flag, _hint = _misplaced_global_flag_hint(self)
         _context: dict[str, object] = {}
         if _flag:
             _context["flag"] = _flag
+        if _hint:
+            _context["scope"] = "root"
         payload = build_error_envelope(
             INVALID_INPUT_CODE,
             self.format_message(),
+            hint=_hint,
             **_context,
         )
         sys.stderr.write(_je.dumps(payload, ensure_ascii=False) + "\n")
         sys.stderr.flush()
 
     _click_exc.UsageError.show = _json_click_usage_error_show  # type: ignore[method-assign]
+
+    # ...and again where Typer actually goes. With `rich_markup_mode` set — it
+    # is, for the help panels — typer.core routes every ClickException to
+    # `rich_utils.rich_format_error` and *never* calls `.show()`, so the patch
+    # above was dead for this app and no usage error has been emitting the JSON
+    # envelope: `ask <cmd> --badflag` answered with a rich text box on stderr.
+    # That is the same broken contract C3-23 closed for `archetype`, reached by
+    # a different route. Patched here rather than by dropping rich mode, which
+    # would cost the C4-1/C4-2 help panels.
+    try:
+        import typer.rich_utils as _typer_rich
+
+        _rich_format_error_original = _typer_rich.rich_format_error
+
+        def _json_rich_format_error(exc: Any) -> None:
+            """JSON for a pipeline, the usage box for a person.
+
+            Audience, not preference — the same reasoning as `_notice`. A
+            consumer parses stderr and needs the envelope; a human at a
+            terminal needs the `Usage:` line and the pointer to `--help`, and
+            would get neither from JSON. Nothing is lost either way.
+            """
+            if sys.stderr.isatty():
+                _rich_format_error_original(exc)
+                # The person who mistyped the flag is exactly who needs C3-4's
+                # hint, so it follows the box rather than living only in JSON.
+                _, _hint = _misplaced_global_flag_hint(exc)
+                if _hint:
+                    typer.echo(_hint, err=True)
+            else:
+                _json_click_usage_error_show(exc)
+
+        _typer_rich.rich_format_error = _json_rich_format_error  # type: ignore[assignment]
+    except Exception:
+        pass  # rich unavailable — .show() above already covers the plain path
 except Exception:
     pass  # click unavailable — plain-text fallback
 
@@ -1081,6 +1169,64 @@ _FREE_TIER_NODE_CAP: int = 50  # graph/semantic node cap — applies only to lar
 _JAVA_MIN_SCAN_DEPTH: int = 12  # Maven src/main/java/<pkg>/<module>/File depth floor
 _LARGE_REPO_ADVISORY_FILES: int = 3000  # cold-scan advisory threshold (files); honest expectation-setting, not a speed claim
 
+#: What one Java file costs in serialized `repo-ir` output, measured across four
+#: repositories (C3-18): spring-petclinic 30 files/318 KB (10.8 KB/file),
+#: jobrunr 581/9.5 MB (16.8), openmrs-core 866/21 MB (25.2), eureka 299/8.0 MB
+#: (27.3). Kept as a band, never collapsed to a midpoint: the 2.6x spread is
+#: real — it tracks how densely the code cross-references — and a point estimate
+#: would assert a precision the sample does not support (the C1-12 rule).
+_IR_BYTES_PER_FILE_LOW: int = 10_800
+_IR_BYTES_PER_FILE_HIGH: int = 27_900
+_IR_SIZE_WARN_MB: int = 10  # advise above this; below it the write is not worth a sentence
+
+#: What `--no-cache` means on a subcommand (C3-5). The old text — "this command
+#: always reads fresh source (no snapshot cache)" — was false: `cache model`, the
+#: authority, records these commands reading the `ris`, `cir` and `parse` layers.
+#: They do skip the *snapshot* layer, which is the only thing the sentence got
+#: right, and it read as a promise about all caching.
+#:
+#: The flag is a genuine no-op here, and for a reason worth stating rather than
+#: asserting: since C1-9 every layer keys on the exact tree state and the
+#: analyzer fingerprint, and the parse layer is content-addressed, so none of
+#: them can serve an answer for code that has changed. There is no staleness for
+#: the flag to bypass. It is accepted so a script can pass it uniformly, and it
+#: is real on the root command, where the snapshot layer does store a rendered
+#: answer.
+_NO_CACHE_SUBCOMMAND_HELP = (
+    "Accepted for compatibility; a no-op here. This command's layers key on the "
+    "tree state, so none can serve a stale answer. Real on `ask --no-cache` "
+    "(root), which caches a rendered answer. See `ask cache model`."
+)
+
+
+def _ir_size_advisory_message(file_count: int) -> "Optional[str]":
+    """Return the `repo-ir` output-size advisory, or ``None`` below the threshold.
+
+    C3-18: the cost is stated *before* it is paid. The old advisory ran after
+    the IR was built and serialized — the whole bill already settled and the
+    file already on disk — so it could tell a user what they had just spent,
+    never what they were about to.
+
+    The figure is a band, not a point. Sampled across four repositories the IR
+    costs 10.8-27.9 KB per Java file, and that 2.6x spread is a real property of
+    the input (how densely the code cross-references), not sampling noise.
+    Publishing its midpoint as one number would assert a precision the sample
+    does not support — the same defect C1-12 records for migration effort — so
+    the band is published with the word "estimate" on it.
+
+    Pure and TTY-agnostic: the caller owns the terminal gate, so this never
+    reaches stdout or a pipeline (C3-26).
+    """
+    est_low_mb = file_count * _IR_BYTES_PER_FILE_LOW / (1024 * 1024)
+    est_high_mb = file_count * _IR_BYTES_PER_FILE_HIGH / (1024 * 1024)
+    if est_high_mb <= _IR_SIZE_WARN_MB:
+        return None
+    return (
+        f"[repo-ir] {file_count} files — estimated output "
+        f"{est_low_mb:.0f}-{est_high_mb:.0f}MB (estimate, not a measurement). "
+        "To spend less: --summary-only, --max-nodes N --max-edges N, or --gzip."
+    )
+
 
 def _cold_scan_advisory_message(
     file_tree: dict,
@@ -4091,6 +4237,19 @@ def repo_ir_cmd(
             )
             raise typer.Exit(code=1)
 
+    # C3-18: state the cost before paying it, not after. The old advisory fired
+    # once the IR was built AND serialized — the whole bill already paid, and the
+    # file already on disk. The estimate is a RANGE because a point would be a
+    # measurement we do not have: sampled across four repositories the IR costs
+    # 10.8-27.9 KB per Java file (petclinic 30 files/318 KB, jobrunr 581/9.5 MB,
+    # openmrs-core 866/21 MB, eureka 299/8.0 MB), a 2.6x spread that depends on
+    # how densely the code cross-references. Reporting the midpoint of that as a
+    # single figure is the C1-12 defect.
+    if output_path and not gzip_output:
+        _notice_msg = _ir_size_advisory_message(len(file_list))
+        if _notice_msg:
+            _notice(_notice_msg)
+
     _ir_phase = f"extracting IR ({len(file_list)} files)"
     if since:
         _ir_phase += f" since {since}"
@@ -4113,38 +4272,32 @@ def repo_ir_cmd(
             output_path = output_path.with_suffix(output_path.suffix + ".gz")
         raw_bytes = output.encode("utf-8")
         size_bytes = len(raw_bytes)
-        _SIZE_WARN_BYTES = 10 * 1024 * 1024  # 10MB
-        if size_bytes > _SIZE_WARN_BYTES and not gzip_output:
-            typer.echo(
-                f"[repo-ir] Output is {size_bytes // (1024 * 1024)}MB — "
-                "consider --summary-only, --max-nodes N --max-edges N, or --gzip to compress.",
-                err=True,
-            )
         if gzip_output:
             import gzip as _gzip
             with _gzip.open(output_path, "wb") as _gz:
                 _gz.write(raw_bytes)
             compressed_kb = output_path.stat().st_size // 1024
             size_kb = size_bytes // 1024
+            # C3-26: when the payload went to a file, this confirmation IS the
+            # answer of the run — the same case as `cache warm`. On stderr,
+            # `ask repo-ir -o ir.json > log.txt` captured nothing and PowerShell
+            # 5.1 raised NativeCommandError over a run that succeeded.
             typer.echo(
-                f"IR written to {output_path} ({compressed_kb}KB gzip, {size_kb}KB uncompressed)",
-                err=True,
+                f"IR written to {output_path} ({compressed_kb}KB gzip, {size_kb}KB uncompressed)"
             )
         else:
             output_path.write_bytes(raw_bytes)
             size_kb = size_bytes // 1024
             if summary_only:
                 typer.echo(
-                    f"IR written to {output_path} ({size_kb}KB, graph omitted by --summary-only)",
-                    err=True,
+                    f"IR written to {output_path} ({size_kb}KB, graph omitted by --summary-only)"
                 )
             else:
                 n_nodes = len((ir.get("graph") or {}).get("nodes") or [])
                 n_edges = len((ir.get("graph") or {}).get("edges") or [])
                 typer.echo(
                     f"IR written to {output_path} "
-                    f"({size_kb}KB, {n_nodes} nodes, {n_edges} edges)",
-                    err=True,
+                    f"({size_kb}KB, {n_nodes} nodes, {n_edges} edges)"
                 )
     else:
         if gzip_output:
@@ -4239,7 +4392,7 @@ def impact_cmd(
     ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
-        help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
+        help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
 ) -> None:
     """Blast-radius analysis: who calls this class and what breaks if it changes?
@@ -4333,8 +4486,16 @@ def impact_cmd(
     finally:
         _prog.finish()
 
-    result = compute_blast_radius(ir, target, max_depth=depth)
-    result = _trim(result, BUDGET_IMPACT, label="impact")
+    # `--output <file>` asks for the whole answer, and its own note promised it.
+    # Both halves of that promise were broken: the caller lists were capped at
+    # construction, so the file held the same 30 of 134, and the output budget
+    # trimmed the file too — while `--agent` and `--compact` beside it already
+    # skipped the budget when writing to a file (C2-2).
+    _to_file = output_path is not None
+    result = compute_blast_radius(
+        ir, target, max_depth=depth, list_limit=0 if _to_file else None
+    )
+    result = _trim(result, BUDGET_IMPACT, label="impact", skip=_to_file)
     if _misread and result.get("resolution") == "not_found":
         result["analysis_warnings"] = [*(result.get("analysis_warnings") or []), _misread]
 
@@ -4422,7 +4583,7 @@ def endpoints_cmd(
     ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
-        help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
+        help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
     by_controller: bool = typer.Option(
         False, "--by-controller",
@@ -5047,7 +5208,7 @@ def validation_cmd(
     ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
-        help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
+        help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
 ) -> None:
     """Map request-body validation per endpoint (constraints + custom validators).
@@ -5910,7 +6071,7 @@ def spring_audit_cmd(
     ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
-        help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
+        help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
 ) -> None:
     """Spring semantic audit: TX anomalies (TX-001..006) + security surface (SEC-001..003).
@@ -6182,12 +6343,13 @@ def verify_cmd(
 
     \b
     Contracts live in `.ask/contracts.yml` (see `ask verify-edit --help` for the
-    rule kinds). No contracts declared → nothing to verify, exit 0.
+    rule kinds). No contracts declared → nothing was verified, exit 2.
 
     \b
     Exit codes (with --ci, the default): 0 = pass, 1 = violations blocked,
-    2 = unverified (contracts unreadable or the repository could not be
-    analysed — never a silent pass). Same codes as `verify-edit`.
+    2 = unverified (no contracts declared, contracts unreadable, or the
+    repository could not be analysed — never a silent pass). Same codes as
+    `verify-edit`.
 
     \b
     Examples:
@@ -6451,6 +6613,24 @@ def migrate_check_cmd(
         help="Minimum severity to include: critical, high, medium, or low (default).",
         show_default=True,
     ),
+    target_jdk: Optional[int] = typer.Option(
+        None,
+        "--target-jdk",
+        help=(
+            "The JDK you are actually moving to (e.g. 11, 17, 21). Rules for a "
+            "later JDK are not your blockers and are not reported. Without it, "
+            "every JDK axis is reported at once."
+        ),
+    ),
+    keep_boot: bool = typer.Option(
+        False,
+        "--keep-boot",
+        help=(
+            "You are staying on Spring Boot 2.x. Drops the Boot 3 axes — the "
+            "jakarta namespace, Spring Security 6 and the Hibernate 5→6 rewrite "
+            "— which are not blockers for a move you are not making."
+        ),
+    ),
     compact: bool = typer.Option(
         False,
         "--compact",
@@ -6463,7 +6643,7 @@ def migrate_check_cmd(
     ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
-        help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
+        help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
     snapshot: bool = typer.Option(
         False, "--snapshot",
@@ -6594,7 +6774,13 @@ def migrate_check_cmd(
     _prog = Progress()
     _prog.start(f"checking migration ({len(file_list)} files)")
     try:
-        report = run_migrate_check(file_list, target, min_severity=min_severity)
+        report = run_migrate_check(
+            file_list,
+            target,
+            min_severity=min_severity,
+            target_jdk=target_jdk,
+            keep_boot=keep_boot,
+        )
     finally:
         _prog.finish()
     if _file_limitations:
@@ -6669,6 +6855,26 @@ _IMPACT_CAPPED_LISTS = (
 )
 
 
+def _flag_was_given(name: str) -> bool:
+    """True when the user typed this option, rather than inheriting its default.
+
+    A default is not a request: `--output` means "give me the whole answer", and
+    that reading must not override a cap the user explicitly asked for on the same
+    line. Click records where each value came from, which is the only way to tell
+    `--limit 100` apart from the 100 nobody typed.
+    """
+    try:
+        import click
+
+        ctx = click.get_current_context(silent=True)
+        if ctx is None:
+            return False
+        source = ctx.get_parameter_source(name)
+    except Exception:
+        return False
+    return source is not None and getattr(source, "name", "") == "COMMANDLINE"
+
+
 def _cap_impact_lists(data: dict, limit: int) -> dict:
     """Cap impact-chain leaf arrays, keeping every total exact.
 
@@ -6745,7 +6951,7 @@ def impact_chain_cmd(
     ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
-        help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
+        help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
     limit: int = typer.Option(
         100, "--limit",
@@ -6874,6 +7080,11 @@ def impact_chain_cmd(
     result = run_impact_chain(cir, symbol, depth=depth, root=target, model=_model)
 
     data = result.to_dict()
+    # Same rule as `impact`: a file is a request for the whole answer (C2-2). An
+    # explicit `--limit` still wins — the user asking for a cap on a file has said
+    # so, and a default is not a request.
+    if output_path is not None and not _flag_was_given("limit"):
+        limit = 0
     data = _cap_impact_lists(data, limit)
     if _misread and result.resolution == "not_found":
         data["analysis_warnings"] = [*(data.get("analysis_warnings") or []), _misread]
@@ -7821,7 +8032,9 @@ def modernize_cmd(
 
     if output_path:
         _safe_write_file(output_path, output)
-        typer.echo(f"Modernization analysis written to {output_path}", err=True)
+        # C3-26: the payload is in the file; this line is the answer (see
+        # _emit_command_output, which this branch predates).
+        typer.echo(f"Modernization analysis written to {output_path}")
     else:
         try:
             sys.stdout.buffer.write(output.encode("utf-8"))
@@ -8775,16 +8988,17 @@ def cold_start_cmd(
     _meta_cs["token_economy"] = _tok_econ(_out, _out_with_meta, target)
     _out = _json.dumps(_out_with_meta, indent=2, ensure_ascii=False)
     if not compact and _size > 400_000:
-        sys.stderr.write(
+        # Informational: the answer is still on stdout, so this is a notice and
+        # takes the terminal gate (C3-26).
+        _notice(
             f"WARNING: Output is ~{_tokens // 1000}K tokens. This exceeds the context window of "
             "most LLMs (GPT-4o: 128K, Claude Sonnet: 200K). "
-            "Use --compact for a ~10K token subset, or --output FILE to save.\n"
+            "Use --compact for a ~10K token subset, or --output FILE to save."
         )
-        sys.stderr.flush()
     if output_path:
         _safe_write_file(output_path, _out)
-        sys.stderr.write(f"Saved {len(_out.encode('utf-8'))} bytes to {output_path}\n")
-        sys.stderr.flush()
+        # C3-26: payload in the file, so this line is the answer — stdout.
+        typer.echo(f"Saved {len(_out.encode('utf-8'))} bytes to {output_path}")
     else:
         typer.echo(_out)
 

sourcecode/compare.py

@@ -39,24 +39,76 @@ COMPARE_SCHEMA: str = "candidate-comparison-v1"
 _UNRESOLVED: frozenset[str] = frozenset({"not_found", "ambiguous_path"})
 
 
+def _measured_count(blast: dict, stat_key: str, list_key: str) -> tuple[int, bool]:
+    """(magnitude, is_floor) for one cost field.
+
+    C2-1: three fields of the ranking vector were `len()` of a *display* list.
+    Those lists are a rendering choice (`list_limit`), so the ranking key — the
+    entire product of this command — was computed over however many rows the
+    renderer had decided to show. The count taken before any cap lives in
+    `stats`, which is what the `why` trail was already corrected to read (C1-16).
+
+    A `stats` value of `None` is the C1-13 case: the walk was capped and never
+    looked, so the true magnitude is unknown. The ranking still has to be a
+    total order, so the list length is used as a **floor** and the field is
+    reported as one — never silently rendered as a confident 0, which would rank
+    a hub as the cheapest candidate on the axis the cap blinded.
+    """
+    stat = (blast.get("stats") or {}).get(stat_key)
+    if isinstance(stat, int):
+        return stat, False
+    return len(blast.get(list_key) or []), True
+
+
 def _cost_vector(plan: dict, blast: dict) -> dict[str, int]:
     """Aggregate the measured cost vector for one candidate from D3 + blast primitives.
 
     Every field is a non-negative count of a real architectural consequence. No
     weighting, no score — the magnitudes are reported as-is; ordering happens in
     `_rank_key` over these same magnitudes."""
+    modules, modules_floor = _measured_count(
+        blast, "modules_affected_count", "cross_module_impact"
+    )
+    secured, secured_floor = _measured_count(
+        blast, "security_surface_count", "security_surface_affected"
+    )
+    txn, txn_floor = _measured_count(
+        blast, "transactional_boundaries_count", "transactional_boundaries_touched"
+    )
     return {
         # Production reverse-dependency closure size (same set D3 lists as components).
         "blast_radius": int(plan.get("affected_components", {}).get("count", 0)),
         "affected_endpoints": int(plan.get("affected_endpoints", {}).get("count", 0)),
         "tests_at_risk": int(plan.get("covering_tests", {}).get("count", 0)),
         "rollback_files": int(plan.get("rollback_surface", {}).get("file_count", 0)),
-        "modules_spanned": len(blast.get("cross_module_impact") or []),
-        "secured_endpoints": len(blast.get("security_surface_affected") or []),
-        "transactional_boundaries": len(blast.get("transactional_boundaries_touched") or []),
+        "modules_spanned": modules,
+        "secured_endpoints": secured,
+        "transactional_boundaries": txn,
     }
 
 
+def _floor_fields(blast: dict) -> list[str]:
+    """Cost fields whose magnitude is a floor, not a measurement (C1-13).
+
+    Kept beside `cost` rather than inside it: `cost` is a map of name to
+    magnitude, and putting a list in it would make the same key hold two types
+    depending on the run — the C2-10 defect this codebase just closed.
+    """
+    return sorted(
+        name
+        for name, (_, is_floor) in (
+            ("modules_spanned", _measured_count(
+                blast, "modules_affected_count", "cross_module_impact")),
+            ("secured_endpoints", _measured_count(
+                blast, "security_surface_count", "security_surface_affected")),
+            ("transactional_boundaries", _measured_count(
+                blast, "transactional_boundaries_count",
+                "transactional_boundaries_touched")),
+        )
+        if is_floor
+    )
+
+
 def _rank_key(cand: dict) -> tuple:
     """Deterministic total order: resolved-first, then descending measured cost.
 
@@ -131,13 +183,26 @@ def build_comparison(
             # Unresolved targets carry a zeroed cost so the table stays rectangular;
             # they are ranked last and their evidence says why they didn't resolve.
             cost = {k: 0 for k in cost}
-        candidates.append({
+        candidate = {
             "target": target,
             "resolution": resolution,
             "resolved": resolved,
             "cost": cost,
             "why": _evidence_trail(cost, blast, resolved, plan),
-        })
+        }
+        # C1-13/C2-1: when the walk was capped, some magnitudes are floors. The
+        # ranking still needs a total order, so a floor is used — but a reader
+        # comparing candidates has to know which side of the comparison is a
+        # lower bound, or the ordering reads as measured when it is partly not.
+        _floors = _floor_fields(blast) if resolved else []
+        if _floors:
+            candidate["cost_floor_fields"] = _floors
+            candidate["cost_floor_note"] = (
+                "The walk was capped before these magnitudes were complete, so "
+                "they are lower bounds and this candidate may rank lower than "
+                "its true cost. Every other field is measured."
+            )
+        candidates.append(candidate)
 
     candidates.sort(key=_rank_key)
     for i, cand in enumerate(candidates, start=1):