tan-cli 0.7.0__py3-none-any.whl

tan/commands/model_device_cmd.py

@@ -0,0 +1,351 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`tan model run --device` / `ab --device` (tan-cli#1287, on-device tier).
+
+The target runs a benchmark app (alp-sdk's `examples/aen/aen-inference-energy`
+speaks the console protocol `tan.core.model_device` parses) and prints
+per-window timing and, when the board has the monitor IC, power samples. This
+module turns that console text into the same `result` envelope the host tier
+fills, with `tier: device`; deployment and capture belong to tan's own flash and
+monitor paths, so they enter through ONE seam, `LIVE_FLOW`:
+
+* `--capture FILE` ingests a console capture taken by whoever ran the board
+  (the bench's `ram-run.sh`, `tan monitor`, a `ram_console_buf` dump). It needs
+  no hardware, no extra and no onnxruntime -- parsing is stdlib.
+* Without `--capture`, `--device` calls `LIVE_FLOW(...)`, which RAM-runs the
+  already-built `diagnostics.link: itcm` project through `tan flash --ram`'s own
+  Flow C and returns the RAM console (`tan.commands.model_device_live`); the row
+  then carries `source: live`. `capture_via` composes any deploy/read pair with
+  the same coded failures.
+
+powerMj is always `null` on this tier (energy is reported in `energy`, with its
+scope label, from usable active+idle sample pairs only). peakSramKib is
+ENERGY-CFG `sram_peak_bytes` / 1024 and `model` falls back to ENERGY-CFG `model`
+when no model file is named (tan-cli#1404); both are `null` if the app omits them.
+Refusals are plain `Issue(...)` returns so the registry gate sees the codes.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from tan.commands.build_output import ProjectContext, resolve_project_context
+from tan.commands.model_device_live import LiveOptions, LiveRefusal, LiveRun, live_console, preflight
+from tan.commands.model_host_cmd import (
+    ab_empty_data,
+    resolve_model_path,
+    run_empty_data,
+)
+from tan.core.model_device import (
+    NOISE_SIGMA,
+    DeviceCaptureError,
+    parse_console,
+    run_result_from_capture,
+)
+from tan.envelope import Issue, Project, SdkInfo
+from tan.exit_codes import ExitCode
+from tan.model.measure import compare
+
+Result = tuple[Project, SdkInfo | None, dict, list[Issue], ExitCode]
+
+#: Largest console capture read from disk (a 64 KiB RAM console is the app's own
+#: ceiling; this only stops a wrong file being slurped).
+MAX_CAPTURE_BYTES = 8 * 1024 * 1024
+
+#: Longest `consoleText` carried in a live row, in CHARACTERS (not bytes). A larger
+#: console is trimmed (`consoleTruncated: true`); the saved
+#: `model-console-*.txt` always holds all of it. Over the cap the TAIL is kept --
+#: `LATENCY-RESULT` is printed last.
+MAX_CONSOLE_TEXT_CHARS = 64 * 1024
+
+#: `(context, model_label, options) -> console text | Issue`: RAM-run the project
+#: through Flow C and return its console (`model_device_live.live_console`). A seam
+#: so a test can substitute a deploy that needs no probe.
+LIVE_FLOW: Callable[[ProjectContext, str | None, LiveOptions], LiveRun | LiveRefusal] = live_console
+
+
+def capture_via(
+    deploy: Callable[[], Issue | None], read_console: Callable[[], str | Issue]
+) -> str | Issue:
+    """Run `deploy()` (an `Issue` means it failed) then `read_console()`;
+    the first failure is returned verbatim, so flash/monitor refusals keep their
+    own codes."""
+    failed = deploy()
+    if failed is not None:
+        return failed
+    return read_console()
+
+
+def _read_capture(context: ProjectContext, raw: str, role: str) -> str | Issue:
+    """The capture file's text. Only a regular file is read -- never a FIFO,
+    device or /proc entry -- and at most `MAX_CAPTURE_BYTES + 1` bytes of it, so
+    a file that grows or lies about its size cannot be slurped."""
+    path = Path(raw)
+    if not path.is_absolute():
+        path = Path(context.workspace_root) / path
+    try:
+        fd = os.open(path, os.O_RDONLY | getattr(os, "O_NONBLOCK", 0))
+        with os.fdopen(fd, "rb") as handle:
+            if not stat.S_ISREG(os.fstat(handle.fileno()).st_mode):
+                return Issue("model.device-capture-invalid", "error", f"{role} {path} is not a regular file.")
+            data = handle.read(MAX_CAPTURE_BYTES + 1)
+    except OSError as err:
+        return Issue("model.device-capture-missing", "error", f"Cannot read {role} {path}: {err}")
+    if len(data) > MAX_CAPTURE_BYTES:
+        return Issue("model.device-capture-invalid", "error", f"{role} {path} is larger than {MAX_CAPTURE_BYTES} bytes.")
+    return data.decode("utf-8", errors="replace")
+
+
+def _console_for(
+    context: ProjectContext, capture: str | None, label: str | None, role: str, live: LiveOptions
+) -> LiveRun | LiveRefusal:
+    if capture:
+        text = _read_capture(context, capture, role)
+        return LiveRefusal([text]) if isinstance(text, Issue) else LiveRun(text, [], None)
+    return LIVE_FLOW(context, label, live)
+
+
+def _row(
+    label: str | None, text: str, run: LiveRun | None = None, project_path: str | None = None
+) -> tuple[dict, Any] | Issue:
+    """The `result` row for one console capture, or the `model.device-capture-invalid` refusal."""
+    try:
+        result, energy, diag = run_result_from_capture(parse_console(text))
+    except (DeviceCaptureError, KeyError, ValueError, TypeError, ArithmeticError, AttributeError,
+            RecursionError) as err:
+        return Issue(
+            "model.device-capture-invalid", "error",
+            f"Unusable device capture: {err}; if the app had not finished, raise --wait.",
+        )
+    size = None
+    if label:
+        try:
+            size = os.stat(label).st_size
+        except OSError:
+            size = None
+    live = run is not None and run.flash is not None
+    extra = {"source": "capture"}
+    if live:
+        extra = {
+            "source": "live", "project": project_path, "flash": run.flash,
+            "consoleText": text[-MAX_CONSOLE_TEXT_CHARS:],
+            "consoleTruncated": len(text) > MAX_CONSOLE_TEXT_CHARS,
+        }
+    return {
+        **extra,
+        "model": label or diag.get("model"),
+        "backend": result.backend,
+        "tier": "device",
+        # The app's own LATENCY-RESULT ms_per_inference when printed (scope
+        # "device-latency-result"), else the median over active windows of
+        # (window span / inferences completed); the latter always stays in
+        # diagnostics.windowLatencyMs.
+        "latencyMs": result.latency_ms,
+        "latencyScope": diag["latencyScope"],
+        "outputArgmax": None,
+        "peakSramKib": result.peak_sram_kib,
+        # Always null on the device tier: energy is reported in `energy`, with
+        # its own scope label, never as a bare number.
+        "powerMj": None,
+        # Inferences timed across the active windows (NOT a repeat count).
+        "runs": result.runs,
+        "sizeBytes": size,
+        "energy": None if energy is None else {
+            "valueMjPerInference": energy.value_mj_per_inference,
+            "spreadMj": energy.spread_mj,
+            "rails": list(energy.rails),
+            "nInferences": energy.n_inferences,
+            "windowMs": energy.window_ms,
+            "sampleCount": energy.sample_count,
+            "source": energy.source,
+            "scope": energy.scope,
+        },
+        "diagnostics": diag,
+    }, result
+
+
+def _degraded(row: dict, label: str) -> list[Issue]:
+    diag = row["diagnostics"]
+    unresolved = diag.get("unresolvedEnergy")
+    issues = [] if unresolved is None else [_unresolved_issue(unresolved, label)]
+    # The device's own unresolvable-delta line is the unresolved issue's evidence; not repeated here.
+    warn = [w for w in diag["warnLines"] if unresolved is None or w != unresolved["deviceLine"]]
+    notes = [*diag["werrLines"], *warn, *diag["skippedPairs"]]
+    if diag.get("energyNote"):
+        notes.append(diag["energyNote"])
+    if not diag["npuDispatched"]:
+        notes.append("the app reported npu_dispatched=false (NPU did not run the model)")
+    if notes:
+        issues.append(
+            Issue("model.device-capture-degraded", "warning", f"{label}: " + "; ".join(notes[:5]))
+        )
+    return issues
+
+
+def _unresolved_issue(unresolved: dict, label: str) -> Issue:
+    """tan-cli#1387: the energy delta is below the rail's noise, so `energy` is null."""
+    spread = unresolved["spreadMj"]
+    spread_text = "no spread (one pair)" if spread is None else f"spread {spread:.6g} mJ"
+    why = (
+        f"the device reported `{unresolved['deviceLine']}`"
+        if unresolved["verdict"] == "device"
+        else f"the mean is not {NOISE_SIGMA:g} standard errors above zero over "
+        f"{unresolved['pairs']} pair(s)"
+    )
+    return Issue(
+        "model.device-energy-unresolved", "warning",
+        f"{label}: energy on rail `{unresolved['rail']}` is not resolvable -- mean "
+        f"{unresolved['valueMjPerInference']:.6g} mJ/inference, {spread_text}; {why}. "
+        "`energy` is null (the raw values are in diagnostics.unresolvedEnergy); "
+        "latency is unaffected. The inference load may be below this rail's noise, "
+        "or the rail may be the wrong one.",
+    )
+
+
+def _device_label(context: ProjectContext, source: str | None) -> str | None | Issue:
+    """The model label: the file given (it must exist), or `None`."""
+    if not source:
+        return None
+    resolved = resolve_model_path(context, source, "run")
+    return resolved if isinstance(resolved, Issue) else resolved.as_posix()
+
+
+def run_device_run(
+    *, context: ProjectContext, source: str | None, capture: str | None, live: LiveOptions | None = None
+) -> Result:
+    project, sdk = context.project(), context.sdk
+    data = run_empty_data()
+
+    def refuse(issue: Issue) -> Result:
+        return project, sdk, data, [issue], ExitCode.VALIDATION_FAILURE
+
+    label = _device_label(context, source)
+    if isinstance(label, Issue):
+        return refuse(label)
+    live = live or LiveOptions()
+    run = _console_for(context, capture, label, "the run", live)
+    if isinstance(run, LiveRefusal):
+        if run.flash is not None:
+            data["flash"] = run.flash
+        return project, sdk, data, run.issues, run.exit_code
+    built = _row(label, run.text, run, context.workspace_root)
+    if isinstance(built, Issue):
+        if run.flash is not None:
+            data["flash"] = run.flash  # the board WAS loaded and reset
+        return project, sdk, data, [*run.issues, built], ExitCode.VALIDATION_FAILURE
+    row, _ = built
+    data["model"] = row["model"]
+    data["result"] = row
+    return project, sdk, data, [*run.issues, *_degraded(row, "device run")], ExitCode.SUCCESS
+
+
+def _note_loaded(data: dict, flashes: dict, role: str, flash: dict | None) -> None:
+    """Refused `ab`: report every side that had already RAM-loaded and reset the board."""
+    if flash is not None:
+        flashes[role.lower()] = flash
+    if flashes:
+        data["flash"] = dict(flashes)
+
+
+def _preflight_both(contexts: list[ProjectContext], live: LiveOptions) -> Issue | None:
+    """tan-cli#1522: both projects' preflight (board.yaml, manifest, ITCM slice)
+    up front -- B's refusal must not come after A already reset the board."""
+    for ctx in contexts:
+        refused = preflight(ctx, live)
+        if refused is not None:
+            return refused
+    return None
+
+
+def _scope_mismatch(a_row: dict, b_row: dict) -> list[Issue]:
+    """tan-cli#1522: latencies measured differently (a window span is an upper
+    bound) make `faster`/`latencyRatio` not like-for-like."""
+    if a_row["latencyScope"] == b_row["latencyScope"]:
+        return []
+    return [Issue(
+        "model.device-ab-scope-mismatch", "warning",
+        f"A's latency is {a_row['latencyScope']} but B's is {b_row['latencyScope']}: "
+        "the two are not like-for-like (a window span includes the energy polling and is an "
+        "upper bound), so `faster` and `latencyRatio` are not a reliable comparison; "
+        "print LATENCY-RESULT on both sides.",
+    )]
+
+
+def _second_context(context: ProjectContext, capture: str | None,
+                    against_capture: str | None, live: LiveOptions) -> ProjectContext | Issue:
+    """B's project context, or the refusal for a mixed/underspecified A-vs-B."""
+    if bool(capture) != bool(against_capture):
+        return Issue(
+            "model.device-ab-mixed-sources", "error",
+            "`ab --device` takes both sides live (--against-project, --confirm) or both from "
+            "captures (--capture and --against-capture), not one of each; nothing was run.",
+        )
+    context_b = context
+    if not against_capture and live.against_project:
+        context_b = resolve_project_context(live.against_project, None, live.sdk_root)
+    if not against_capture and context_b is context:
+        return Issue(
+            "model.device-live-needs-two-projects", "error",
+            "`ab --device` without --against-capture runs each project in turn: pass the second "
+            "project with --against-project (nothing was run).",
+        )
+    return context_b
+
+
+def run_device_ab(
+    *,
+    context: ProjectContext,
+    source: str | None,
+    against: str | None,
+    capture: str | None,
+    against_capture: str | None,
+    live: LiveOptions | None = None,
+) -> Result:
+    project, sdk = context.project(), context.sdk
+    data = ab_empty_data()
+    rows: list[tuple[dict, Any]] = []
+    issues: list[Issue] = []
+    flashes: dict[str, dict] = {}
+    live = live or LiveOptions()
+    context_b = _second_context(context, capture, against_capture, live)
+    if isinstance(context_b, Issue):
+        return project, sdk, data, [context_b], ExitCode.VALIDATION_FAILURE
+    sides = (("A", source, capture, context), ("B", against, against_capture, context_b))
+    # Both labels first: a missing model file must refuse before A loads the board.
+    labels = [_device_label(ctx, raw) for _, raw, _, ctx in sides]
+    for label in labels:
+        if isinstance(label, Issue):
+            return project, sdk, data, [label], ExitCode.VALIDATION_FAILURE
+    if not capture:
+        refused = _preflight_both([ctx for _r, _raw, _c, ctx in sides], live)
+        if refused is not None:
+            return project, sdk, data, [refused], ExitCode.VALIDATION_FAILURE
+    for (role, _raw, cap, ctx), label in zip(sides, labels):
+        run = _console_for(ctx, cap, label, f"model {role}", live)
+        if isinstance(run, LiveRefusal):
+            _note_loaded(data, flashes, role, run.flash)
+            return project, sdk, data, [*issues, *run.issues], run.exit_code
+        built = _row(label, run.text, run, ctx.workspace_root)
+        if isinstance(built, Issue):
+            _note_loaded(data, flashes, role, run.flash)
+            return project, sdk, data, [*issues, *run.issues, built], ExitCode.VALIDATION_FAILURE
+        rows.append(built)
+        if run.flash is not None:
+            flashes[role.lower()] = run.flash
+        issues.extend(run.issues)
+        issues.extend(_degraded(built[0], f"device run {role}"))
+    (a_row, a_res), (b_row, b_res) = rows
+    cmp = compare(a_res, b_res)
+    data["a"], data["b"] = a_row, b_row
+    issues.extend(_scope_mismatch(a_row, b_row))
+    data["comparison"] = {
+        "faster": cmp.faster,
+        "latencyRatio": cmp.latency_ratio,
+        "aLatencyMs": cmp.a_latency_ms,
+        "bLatencyMs": cmp.b_latency_ms,
+        "sizeDeltaBytes": None,
+    }
+    return project, sdk, data, issues, ExitCode.SUCCESS

tan/commands/model_device_live.py

@@ -0,0 +1,234 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The live tier of `tan model run --device` / `ab --device` (tan-cli#1287).
+
+`live_console` RAM-runs an already-built `diagnostics.link: itcm` project through
+AEN Flow C -- the same `flash_cmd._run(ram=True, ram_console=True)` that
+`tan flash --ram --ram-console` calls, in-process, never a subprocess of tan --
+and returns the `ram_console_buf` text for `model_device_cmd` to hand to the
+capture parser. The benchmark app (alp-sdk `examples/aen/aen-inference-latency`
+or `aen-inference-energy`) must have the model baked in: tan does not build,
+convert or embed it here.
+
+`--ram` is the only write path used, so MRAM is never touched. Every flash
+refusal is passed through with its own `flash.*` code; the refusals this module
+adds are plain `Issue(...)` returns so the registry gate sees the codes.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from tan.commands import flash_cmd
+from tan.commands.build_output import ProjectContext
+from tan.core.jlink_probe import is_valid_usb_path
+from tan.core.link_refusal import RAM_RUN_ONLY_METHOD
+from tan.core.flash_plan import ManifestError, confirm_gate_note, parse_system_manifest
+from tan.envelope import Issue
+from tan.exit_codes import ExitCode
+
+DEFAULT_CORE = "m55_he"
+DEFAULT_WAIT_S = 1.5
+
+
+@dataclass(frozen=True)
+class LiveOptions:
+    """The flags a live device run forwards to Flow C."""
+
+    core: str = DEFAULT_CORE
+    wait: float = DEFAULT_WAIT_S
+    confirm: bool = False
+    probe_serial: str | None = None
+    probe_usb_path: str | None = None
+    jlink: str | None = None
+    sdk_root: str | None = None
+    against_project: str | None = None
+    #: The user's own `--board-yaml`, forwarded to Flow C; `None` when left at the default.
+    board_yaml: str | None = None
+
+    def any_set(self) -> bool:
+        return self != LiveOptions(sdk_root=self.sdk_root, board_yaml=self.board_yaml)
+
+
+@dataclass(frozen=True)
+class LiveRun:
+    """A successful RAM-run: the console, EVERY `flash.*` issue Flow C raised
+    (warnings such as `flash.probe-unverified` included -- they qualify the
+    measurement), and the `flash` provenance block for the result row."""
+
+    text: str
+    issues: list[Issue]
+    flash: dict | None = None
+    #: Where the raw console was saved (`<build>/flash-logs/model-console-<ts>.txt`), if it was.
+    console_path: str | None = None
+
+
+@dataclass(frozen=True)
+class LiveRefusal:
+    """A refusal: the issues to report (Flow C's own, verbatim and in order) and
+    the exit code -- Flow C's `ExitCode` is kept, a model-side refusal is a
+    validation failure."""
+
+    issues: list[Issue]
+    exit_code: ExitCode = ExitCode.VALIDATION_FAILURE
+    #: The `flash` provenance block when the image WAS RAM-loaded and reset before
+    #: the refusal (tan-cli#1417); `None` when nothing reached the board.
+    flash: dict | None = None
+
+
+def _refuse(issue: Issue, *before: Issue) -> LiveRefusal:
+    return LiveRefusal([*before, issue])
+
+
+def preflight(context: ProjectContext, live: LiveOptions) -> Issue | None:
+    """The project must be built for RAM-run: board.yaml, a manifest, and a
+    `ram_run_only` (ITCM-linked) slice for the chosen core."""
+    if not Path(context.board_yaml).is_file():
+        return Issue(
+            "model.device-no-project", "error",
+            f"No project at {context.workspace_root} (board.yaml not found at {context.board_yaml}); "
+            "`--device` without --capture needs a built diagnostics.link: itcm project (--project).",
+        )
+    if live.probe_usb_path is not None and not is_valid_usb_path(live.probe_usb_path):
+        return Issue(
+            "model.device-probe-invalid", "error",
+            f"{live.probe_usb_path!r} is not a USB port path like 3-4.2 (<bus>-<port>[.<port>...]).",
+        )
+    manifest_path = Path(context.workspace_root) / "build" / "system-manifest.yaml"
+    try:
+        manifest = parse_system_manifest(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, ManifestError) as err:
+        return Issue(
+            "model.device-no-manifest", "error",
+            f"No usable system-manifest.yaml at {manifest_path} ({err}); run `tan build --project "
+            f"{context.workspace_root}` for the benchmark app first.",
+        )
+    if not any(s.core_id == live.core and s.flash_method == RAM_RUN_ONLY_METHOD for s in manifest.slices):
+        return Issue(
+            "model.device-no-itcm-slice", "error",
+            f"The manifest has no RAM-run-only slice for core {live.core}: the benchmark app must be "
+            "built with board.yaml `diagnostics.link: itcm` (an ITCM-linked image, the only kind "
+            "`tan flash --ram` runs).",
+        )
+    return None
+
+
+def _provenance(entry: dict, live: LiveOptions, console_path: str | None = None) -> dict:
+    jlink = entry.get("jlink") or {}
+    block = {
+        "core": live.core,
+        "wait": live.wait,
+        "transcriptPath": jlink.get("transcriptPath"),
+        "attachedCore": jlink.get("attachedCore"),
+    }
+    if jlink.get("dpidr"):
+        block["dpidr"] = jlink["dpidr"]
+    if console_path:
+        block["consolePath"] = console_path
+    return block
+
+
+def _save_console(
+    context: ProjectContext, text: object, build_root: object = None
+) -> tuple[str | None, list[Issue]]:
+    """Write the raw RAM console next to the Flow C transcript
+    (`<build>/flash-logs/model-console-<UTC ts>.txt`, never overwritten) so
+    `latencyMs` can be checked against the app's own `LATENCY-RESULT`. A write
+    failure is a warning: the measurement is still valid. `build_root` is the one
+    Flow C itself used (so the file sits beside its transcript, nested layouts
+    included); a blank console is not saved."""
+    if not isinstance(text, str) or not text.strip():
+        return None, []
+    root = Path(build_root) if isinstance(build_root, str) and build_root else Path(context.workspace_root) / "build"
+    logs = root / "flash-logs"
+    base = time.strftime("model-console-%Y%m%dT%H%M%SZ", time.gmtime())
+    try:
+        logs.mkdir(parents=True, exist_ok=True)
+        n = 0
+        while True:
+            path = logs / (f"{base}.txt" if n == 0 else f"{base}-{n}.txt")
+            try:
+                with open(path, "x", encoding="utf-8", newline="\n") as handle:
+                    handle.write(text)
+                return str(path), []
+            except FileExistsError:
+                n += 1
+    except OSError as err:
+        return None, [Issue(
+            "model.device-console-unsaved", "warning",
+            f"The raw RAM console could not be saved under {logs}: {err}",
+        )]
+
+
+def live_console(context: ProjectContext, label: str | None, live: LiveOptions) -> LiveRun | LiveRefusal:
+    """RAM-run the project and return its console plus Flow C's issues, or the refusal."""
+    refused = preflight(context, live)
+    if refused is not None:
+        return _refuse(refused)
+    code, data, issues, _lines, _sdk = flash_cmd._run(
+        app_path=context.workspace_root,
+        build_root_arg=None,
+        sdk_root_arg=live.sdk_root,
+        board_yaml=live.board_yaml,
+        core=live.core,
+        helper=None,
+        dry_run=False,
+        skip_missing_tools=False,
+        capture=True,
+        cwd=context.workspace_root,
+        confirm_flag=live.confirm,
+        probe_serial=live.probe_serial,
+        probe_usb_path=live.probe_usb_path,
+        jlink_path=live.jlink,
+        ram=True,
+        ram_console=True,
+        ram_wait=live.wait,
+    )
+    entries = data.get("entries") or []
+    entry = entries[0] if entries else {}
+    flash_issues = list(issues)
+    if entry.get("status") == "planned":
+        # First, so a consumer reading issues[0] sees the actionable refusal; Flow C's
+        # own `flash.nothing-flashed` / `flash.confirm-required` follow it.
+        return LiveRefusal([Issue(
+            "model.device-confirm-required", "error",
+            "A live device run RAM-loads the image and resets the whole device (including the Secure "
+            "Enclave); nothing was run: "
+            f"{confirm_gate_note('--confirm was not given', 'run on the device')}.",
+        ), *flash_issues])
+    failed = int(code) != 0 or entry.get("status") == "failed"
+    if failed:
+        if not any(i.severity == "error" for i in flash_issues):
+            flash_issues.append(Issue(
+                "model.device-flash-failed", "error",
+                f"The Flow C RAM-run failed: {entry.get('message') or 'no detail reported'}",
+            ))
+        # tan-cli#1486: the registry documents `model.device-flash-failed` as
+        # VALIDATION_FAILURE; a Flow C error issue passed through keeps Flow C's own code.
+        synthesised = not any(i.severity == "error" for i in issues)
+        if synthesised:
+            exit_code = ExitCode.VALIDATION_FAILURE
+        else:
+            exit_code = ExitCode(int(code)) if int(code) else ExitCode.RUNTIME_FAILURE
+        # tan-cli#1497: a failure AFTER the image was loaded and the device reset
+        # (Flow C's `ram.loaded`) still happened to the board: keep the provenance.
+        loaded = bool((entry.get("ram") or {}).get("loaded"))
+        return LiveRefusal(flash_issues, exit_code,
+                           flash=_provenance(entry, live) if loaded else None)
+    console = entry.get("ramConsole") or {}
+    text = console.get("text")
+    console_path, save_issues = _save_console(context, text, data.get("buildRoot"))
+    flash = _provenance(entry, live, console_path)
+    if not isinstance(text, str) or not text.strip():
+        which = console.get("selected")
+        why = (
+            "the build selected the UART console, which a RAM-run cannot read"
+            if which == "uart" else f"nothing was printed in the {live.wait:g}s wait"
+        )
+        return LiveRefusal([*flash_issues, Issue(
+            "model.device-console-empty", "error",
+            f"The RAM console is empty ({why}); raise --wait or check the benchmark app.",
+        )], flash=flash)
+    return LiveRun(text, [*flash_issues, *save_issues], flash, console_path)