tan-cli 0.7.0__py3-none-any.whl

tan/core/ram_watch.py

@@ -0,0 +1,231 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`tan flash --ram --watch` -- read-only memory sampling while a RAM-run image runs
+(tan-cli#1436). Pure logic, no IO:
+
+* [`parse_watch`]: one `--watch <addr>[:<words>][@<period-ms>]` spec -> [`WatchSpec`],
+  refusing an unaligned address, a zero or excessive word count, a period outside the
+  supported range, and any address the probe cannot safely read.
+* [`schedule`]: the specs + the `--wait` window -> the sample times, merged in order.
+* [`watch_lines`]: the J-Link Commander lines appended after `go` -- `mem32` reads
+  separated by `Sleep <ms>`. `mem32` only: no write command is ever produced.
+* [`parse_samples`]: the load transcript -> the envelope's `data.watch[]`.
+
+**Time basis.** J-Link Commander prints no timestamps, so a sample's `elapsedMs` is its
+SCHEDULED offset after `go` (the `Sleep` sum), not a measurement; every `mem32` adds SWD
+latency on top, so the real offset is later and drifts upward over a long window.
+
+**Unsafe addresses.** The denylist is keyed by the attached core. For the M55 HE (the
+only core a RAM-run attaches to) the HP TCM windows `[0x50000000, 0x58000000)` (ITCM and
+DTCM globals) are refused: reading them from an HE attach is the bench's known-bad read,
+it leaves the core unhaltable until a PIN reset (bench round 8, see `tan.core.ram_run`).
+
+**Side effects.** `mem32` is read-only on memory, but a register read (a FIFO, a
+clear-on-read status, a clock-gated block) may have side effects; tan cannot tell them
+apart, so watch RAM or plain data registers.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from tan.core.ram_run import HE_ALIAS, _ITCM_GLOBAL
+
+CODE_INVALID = "flash.ram-watch-invalid"
+CODE_UNSAFE = "flash.ram-watch-unsafe-address"
+CODE_INCOMPLETE = "flash.ram-watch-incomplete"
+
+DEFAULT_WORDS = 1
+MAX_WORDS = 64
+DEFAULT_PERIOD_MS = 100
+MIN_PERIOD_MS = 10
+MAX_PERIOD_MS = 60_000
+MAX_WATCHES = 8
+#: Upper bound on the `mem32` reads in one session, so a long `--wait` with a short
+#: period cannot build a script of unbounded size.
+MAX_SAMPLES = 2000
+#: Per attached core, the spans its attach must never read. HE: the HP TCM windows
+#: [HP ITCM global, HE ITCM global) -- ITCM and DTCM.
+DENIED_SPANS = {"M55_HE": ((_ITCM_GLOBAL["M55_HP"], HE_ALIAS),)}
+#: Wall-clock budget per `mem32` (SWD read + J-Link command overhead), generous.
+PER_READ_BUDGET_S = 2.0
+TIMEOUT_MARGIN_S = 60.0
+
+
+def session_timeout_s(specs: "Sequence[WatchSpec]", duration_ms: int) -> float:
+    """The load session's spawn timeout: the window, plus a budget per scheduled read,
+    plus a margin."""
+    return duration_ms / 1000 + len(schedule(specs, duration_ms)) * PER_READ_BUDGET_S + TIMEOUT_MARGIN_S
+
+_SPEC = re.compile(
+    r"^(?P<addr>0[xX][0-9A-Fa-f]{1,8}|[0-9]{1,10})(?::(?P<words>[0-9]+))?(?:@(?P<period>[0-9]+))?$"
+)
+
+
+class WatchError(Exception):
+    """A `--watch` refusal. `code` is the registered issue code."""
+
+    def __init__(self, message: str, code: str = CODE_INVALID):
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass(frozen=True)
+class WatchSpec:
+    address: int
+    words: int
+    period_ms: int
+    text: str
+
+
+def parse_watch(text: str, core: str = "M55_HE") -> WatchSpec:
+    match = _SPEC.match(text.strip()) if isinstance(text, str) else None
+    if match is None:
+        raise WatchError(
+            f"--watch {text!r} is not <addr>[:<words>][@<period-ms>] (addr is 0x-hex or decimal)"
+        )
+    raw = match["addr"]
+    address = int(raw, 16) if raw[:2].lower() == "0x" else int(raw)
+    words = int(match["words"]) if match["words"] is not None else DEFAULT_WORDS
+    period = int(match["period"]) if match["period"] is not None else DEFAULT_PERIOD_MS
+    if address > 0xFFFFFFFF:
+        raise WatchError(f"--watch {text!r}: address 0x{address:X} is beyond 32 bits")
+    if address % 4:
+        raise WatchError(f"--watch {text!r}: address 0x{address:08X} is not 4-byte aligned (mem32)")
+    if not 1 <= words <= MAX_WORDS:
+        raise WatchError(f"--watch {text!r}: {words} words is outside 1..{MAX_WORDS}")
+    if not MIN_PERIOD_MS <= period <= MAX_PERIOD_MS:
+        raise WatchError(
+            f"--watch {text!r}: period {period} ms is outside {MIN_PERIOD_MS}..{MAX_PERIOD_MS}"
+        )
+    last = address + 4 * words - 1
+    if last > 0xFFFFFFFF:
+        raise WatchError(f"--watch {text!r}: the read runs past the end of the address space")
+    for lo, hi in DENIED_SPANS.get(core, ()):
+        if address < hi and last >= lo:
+            raise WatchError(
+                f"--watch {text!r}: 0x{address:08X}..0x{last:08X} overlaps the HP TCM "
+                f"windows 0x{lo:08X}..0x{hi - 1:08X}; reading it from the HE attach "
+                "leaves the core unhaltable until a PIN reset",
+                CODE_UNSAFE,
+            )
+    return WatchSpec(address, words, period, text.strip())
+
+
+def parse_watches(texts: Sequence[str], core: str = "M55_HE") -> list[WatchSpec]:
+    if len(texts) > MAX_WATCHES:
+        raise WatchError(f"{len(texts)} --watch options; at most {MAX_WATCHES}")
+    return [parse_watch(t, core) for t in texts]
+
+
+def schedule(specs: Sequence[WatchSpec], duration_ms: int) -> list[tuple[int, int]]:
+    """`(offset_ms, spec_index)` for every sample in `[0, duration_ms]`, time-ordered
+    (ties in spec order). Refuses more than [`MAX_SAMPLES`]."""
+    out = [
+        (t, i)
+        for i, s in enumerate(specs)
+        for t in range(0, max(duration_ms, 0) + 1, s.period_ms)
+    ]
+    if len(out) > MAX_SAMPLES:
+        raise WatchError(
+            f"{len(out)} samples over {duration_ms} ms exceeds {MAX_SAMPLES}; "
+            "raise the period or shorten --wait"
+        )
+    return sorted(out)
+
+
+def watch_lines(specs: Sequence[WatchSpec], duration_ms: int) -> list[str]:
+    """Commander lines for after `go`: `mem32` reads with `Sleep` between, padded so the
+    session lasts the whole `--wait` window. Addresses and counts are ints rendered `0x%X`."""
+    lines: list[str] = []
+    now = 0
+    for offset, i in schedule(specs, duration_ms):
+        if offset > now:
+            lines.append(f"Sleep {offset - now}")
+            now = offset
+        lines.append(f"mem32 0x{specs[i].address:X}, 0x{specs[i].words:X}")
+    if duration_ms > now:
+        lines.append(f"Sleep {duration_ms - now}")
+    return lines
+
+
+_MEM32_LINE = re.compile(r"^([0-9A-Fa-f]{8}) = ((?:[0-9A-Fa-f]{8}(?:\s+|$))+)$")
+
+
+_ECHO = re.compile(r"^J-Link>\s*mem32\s+0[xX]([0-9A-Fa-f]+)\s*,\s*0[xX]([0-9A-Fa-f]+)\s*$")
+
+
+def _blocks(transcript: str) -> list[tuple[int, list[tuple[int, list[int]]]]] | None:
+    """Each echoed `J-Link>mem32 0xADDR, 0xN` with the dump lines that follow it (up to the
+    next `J-Link>` echo). `None` when the transcript echoes no `mem32` at all."""
+    blocks: list[tuple[int, list[tuple[int, list[int]]]]] = []
+    for raw in transcript.splitlines():
+        line = raw.strip()
+        echo = _ECHO.match(line)
+        if echo:
+            blocks.append((int(echo[1], 16), []))
+        elif line.startswith("J-Link>"):
+            blocks.append((-1, []))  # another command: closes the open block
+        else:
+            m = _MEM32_LINE.match(line)
+            if m and blocks:
+                blocks[-1][1].append((int(m[1], 16), [int(w, 16) for w in m[2].split()]))
+    reads = [b for b in blocks if b[0] >= 0]
+    return reads if reads else None
+
+
+def _collect(address: int, words: int, dumps: list[tuple[int, list[int]]]) -> list[int] | None:
+    values: list[int] = []
+    for base, got in dumps:
+        if base != address + 4 * len(values):
+            break
+        values.extend(got)
+    return values if len(values) == words else None
+
+
+def parse_samples(transcript: str, specs: Sequence[WatchSpec], duration_ms: int) -> list[dict]:
+    """The envelope's `data.watch[]`: one entry per scheduled sample, in order, each
+    `{address, words, index, elapsedMs, values}`; `values` is `None` when its dump is
+    missing. Strict: only `ADDR = WWWWWWWW ...` lines count. When J-Link echoes the
+    commands, each echoed `mem32` is paired with the dumps that follow IT, so a missing
+    dump is `None` at its own index and shifts nothing; a transcript with no echo falls
+    back to matching dump lines in order against each sample's expected address."""
+    sched = schedule(specs, duration_ms)
+    blocks = _blocks(transcript)
+    flat = []
+    for raw in transcript.splitlines():
+        m = _MEM32_LINE.match(raw.strip())
+        if m:
+            flat.append((int(m[1], 16), [int(w, 16) for w in m[2].split()]))
+    out: list[dict] = []
+    cursor = 0
+    counts: dict[int, int] = {}
+    for n, (offset, i) in enumerate(sched):
+        spec = specs[i]
+        if blocks is not None:
+            got = None
+            if n < len(blocks) and blocks[n][0] == spec.address:
+                got = _collect(spec.address, spec.words, blocks[n][1])
+        else:
+            got = None
+            pos, values = cursor, []
+            while len(values) < spec.words and pos < len(flat):
+                base, words = flat[pos]
+                if base != spec.address + 4 * len(values):
+                    break
+                values.extend(words)
+                pos += 1
+            if len(values) == spec.words:
+                got, cursor = values, pos
+        idx = counts.get(i, 0)
+        counts[i] = idx + 1
+        out.append(
+            {
+                "address": f"0x{spec.address:08X}",
+                "words": spec.words,
+                "index": idx,
+                "elapsedMs": offset,
+                "values": [f"0x{v:08X}" for v in got] if got is not None else None,
+            }
+        )
+    return out

tan/core/raw_write.py

@@ -0,0 +1,160 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pure facts for `tan flash --raw <file>@<addr>` (tan-cli#1446): a byte-exact,
+sector-granular MRAM write for bench backup/restore.
+
+Flow D writes a built image plus a signed ATOC. A bench that backed MRAM up with
+`savebin` needs the saved sectors put back EXACTLY, and nothing else: no signing, no
+address derivation, no reset. Everything here is IO-free; the J-Link session lives in
+`tan.commands.flash_raw`.
+
+**tan never invents an address.** Each `--raw` names its own address on the command
+line; nothing is read from an `app-package-map.txt`, a manifest or a file name. That is
+the whole ATOC/STOC rule: the Secure Enclave table lives in the last MRAM sectors, and a
+write there is only ever one the user asked for by address.
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from tan.core.flash_plan import commander_path, validate_commander_path
+from tan.core.flow_d_report import SECTOR_BYTES, hex_addr, sector_span
+
+CODE_INVALID = "flash.raw-invalid"
+CODE_RESERVATION = "flash.raw-reservation-required"
+CODE_FAILED = "flash.raw-failed"
+
+
+class RawError(ValueError):
+    """A `--raw` input tan refuses before any spawn. `code` is the registered issue code."""
+
+    code = CODE_INVALID
+
+
+@dataclass(frozen=True)
+class RawSpec:
+    path: str
+    address: int
+    size: int = 0
+
+
+def parse_raw(spec: str) -> RawSpec:
+    """`<file>@<addr>` -> `RawSpec`. The LAST `@` splits, so a path may contain one; the
+    address must be an explicit hex literal (`0x80010000`)."""
+    path, sep, addr = spec.rpartition("@")
+    if not sep or not path or not addr:
+        raise RawError(f"--raw {spec!r} is not <file>@<address> (e.g. he_slot0.bin@0x80010000)")
+    if not addr.lower().startswith("0x"):
+        raise RawError(f"--raw {spec!r}: the address must be an explicit hex literal like 0x80010000")
+    try:
+        value = int(addr, 16)
+    except ValueError:
+        raise RawError(f"--raw {spec!r}: {addr!r} is not a hex address") from None
+    validate_commander_path(path, "the --raw file path")
+    return RawSpec(path=path, address=value)
+
+
+def validate_ranges(
+    specs: Sequence[RawSpec], mram_bytes: int, base: int
+) -> None:
+    """Refuse every unaligned, empty, out-of-MRAM or overlapping range. The loader rewrites
+    whole 16 KiB sectors and fills a short tail with 0xFF, so a blob whose address or size
+    is not sector-aligned would NOT be a byte-exact restore of what it names."""
+    if not specs:
+        raise RawError("--raw needs at least one <file>@<address>")
+    end_of_mram = base + mram_bytes
+    problems: list[str] = []
+    for s in specs:
+        where = f"{s.path}@{hex_addr(s.address)} ({s.size} B)"
+        if s.size <= 0:
+            problems.append(f"{where}: the file is empty")
+            continue
+        if s.address % SECTOR_BYTES:
+            problems.append(f"{where}: the address is not {SECTOR_BYTES // 1024} KiB sector-aligned")
+        if s.size % SECTOR_BYTES:
+            problems.append(
+                f"{where}: the size is not a whole number of {SECTOR_BYTES // 1024} KiB sectors -- "
+                "the loader would fill the rest of the last sector with 0xFF, so this is not "
+                "a byte-exact write; pad the saved blob to the sector boundary yourself"
+            )
+        if s.address < base or s.address + s.size > end_of_mram:
+            problems.append(
+                f"{where}: outside MRAM [{hex_addr(base)}, {hex_addr(end_of_mram)})"
+            )
+    ordered = sorted(specs, key=lambda s: s.address)
+    for a, b in zip(ordered, ordered[1:]):
+        if a.address + a.size > b.address:
+            problems.append(
+                f"{a.path}@{hex_addr(a.address)} and {b.path}@{hex_addr(b.address)} overlap"
+            )
+    if problems:
+        raise RawError("; ".join(problems))
+
+
+def raw_script(preamble: str, specs: Sequence[RawSpec]) -> str:
+    """The write session: `preamble` (everything up to and including `connect`), a
+    `loadbin` then `verifybin` per blob, `exit`. NO reset and NO `go`: the write must not
+    boot, halt-resume or reset anything."""
+    lines = [preamble.rstrip("\n")]
+    for s in specs:
+        lines.append(f"loadbin {commander_path(s.path)} {hex_addr(s.address)}")
+    for s in specs:
+        lines.append(f"verifybin {commander_path(s.path)} {hex_addr(s.address)}")
+    lines.append("exit")
+    return "\n".join(lines) + "\n"
+
+
+def planned(specs: Sequence[RawSpec], sha256s: Sequence[str]) -> list[dict]:
+    """Each blob as the envelope reports it: path, address, size, sha256, sector span."""
+    return [
+        {
+            "path": s.path, "address": hex_addr(s.address), "size": s.size, "sha256": digest,
+            "sectorSpan": sector_span(s.address, s.size),
+        }
+        for s, digest in zip(specs, sha256s)
+    ]
+
+
+def lease_holder(show_text: str) -> str | None:
+    """The `acquired:` holder (`host/user`) in `labgrid-client -p <place> show` output,
+    strictly: exactly one distinct, non-empty value across the `  acquired:` lines, else
+    `None` (ambiguity is never a holder)."""
+    holders = {
+        line.split(":", 1)[1].strip()
+        for line in show_text.splitlines()
+        if line.startswith("  acquired:")
+    }
+    return holders.pop() if len(holders) == 1 and next(iter(holders), "x") else None
+
+
+def lease_swd_path(show_text: str) -> str | None:
+    """The USB path of the `swd` resource in `labgrid-client -p <place> show` output (the
+    `'path': '3-4.2'` entry of the `Acquired|Matching resource 'swd'` block), or `None`.
+    The `matches:` list at the top names the same resource without a path, so only the
+    resource block counts."""
+    import re
+
+    inside = False
+    for line in show_text.splitlines():
+        if re.match(r"^(Acquired|Matching) resource 'swd'", line):
+            inside = True
+            continue
+        if inside:
+            if line and not line[0].isspace():
+                return None
+            found = re.search(r"'path': '([^']+)'", line)
+            if found:
+                return found.group(1)
+    return None
+
+
+def lease_changed(show_text: str) -> str | None:
+    """The place's `changed:` timestamp in `labgrid-client show` output (labgrid 26.0 updates it
+    on every acquire/release), strictly: exactly one distinct, non-empty value, else `None`.
+    The lease file records it at acquire time so a lease cannot outlive its acquisition."""
+    values = {
+        line.split(":", 1)[1].strip()
+        for line in show_text.splitlines()
+        if line.startswith("  changed:")
+    }
+    return next(iter(values)) if len(values) == 1 and next(iter(values)) else None

tan/core/reset_plan.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: Apache-2.0
+"""tan-cli#1452: the pure half of `tan reset` -- the one-pulse nRESET script.
+
+`tan reset` is ONE clean pin pulse through J-Link Commander: `r0` (drive nRESET
+low), a `sleep` of the pulse width, `r1` (release), `q`. It deliberately has none of
+the machinery `tan flash`'s pin reset carries: no `connect`, no halt, no `RSetType`, no
+connect-under-reset, no `g`, no retry. Each of those either wakes a target out
+of STOP, loses the VBAT/BKRAM evidence of a non-waking STOP, or both.
+`FORBIDDEN_VERBS` is what the tests hold the generated script to.
+"""
+from __future__ import annotations
+
+import re
+
+DEFAULT_PULSE_MS = 100
+MIN_PULSE_MS = 1
+MAX_PULSE_MS = 10000
+#: Commander has to open the probe, never attach to the target: a `connect`
+#: against an Alif target in STOP fails (debug domain gated) or disturbs the
+#: evidence this verb exists to preserve. Bench-proven script: r0 / sleep 100 / r1 / q.
+_SAFE_TOKEN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+#: Commander verbs a reset script must never contain.
+FORBIDDEN_VERBS = (
+    "connect", "h", "halt", "g", "go", "rsettype", "resettype", "reset", "r", "rx", "w1", "w2", "w4",
+    "loadbin", "loadfile", "erase", "unlock", "setpc", "step", "s",
+)
+
+
+class ResetArgError(ValueError):
+    """A bad `--pulse-ms`."""
+
+
+def check_pulse_ms(pulse_ms: int) -> int:
+    if isinstance(pulse_ms, bool) or not isinstance(pulse_ms, int):
+        raise ResetArgError(f"--pulse-ms {pulse_ms!r} is not an integer")
+    if not MIN_PULSE_MS <= pulse_ms <= MAX_PULSE_MS:
+        raise ResetArgError(
+            f"--pulse-ms {pulse_ms} is outside {MIN_PULSE_MS}..{MAX_PULSE_MS} milliseconds"
+        )
+    return pulse_ms
+
+
+def pulse_script(serial: str | None, pulse_ms: int) -> str:
+    """`SelectEmuBySN <serial>` (only when a probe is selected), then
+    `r0`, `sleep <ms>`, `r1`, `q`. No `connect`."""
+    check_pulse_ms(pulse_ms)
+    if serial is not None and not _SAFE_TOKEN.match(serial):
+        raise ResetArgError(f"the J-Link serial {serial!r} is not a plain token")
+    pre = [f"SelectEmuBySN {serial}"] if serial else []
+    return "\n".join([*pre, "r0", f"sleep {pulse_ms}", "r1", "q"]) + "\n"
+
+
+def script_verbs(script: str) -> list[str]:
+    """The first token of every non-empty line, lower-cased."""
+    return [ln.split()[0].lower() for ln in script.splitlines() if ln.split()]

tan/core/run.py

@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pure post-build decision logic for `tan run` -- port of
+`crates/tan-core/src/run.rs`. No IO: the subprocess spawn and the filesystem
+probe live in `tan.commands.run_cmd`.
+
+`tan run` is a THIN ORCHESTRATOR over `tan build`'s engine and (on a hardware
+target, with `--flash`) `tan flash`'s engine -- it never re-derives either.
+The only thing this module owns is the decision of WHICH of those two to
+reach, from signals the build step that just ran produced: whether the build
+succeeded, whether it could establish a host (`native_sim`) vs. hardware
+target, whether `--flash` was requested, and whether the post-build
+`system-manifest.yaml` write is confirmed to have succeeded. Flashing real
+silicon is the dangerous path, so it is never the default action -- a
+hardware target flashes only on an explicit `--flash`.
+
+**`native_sim_target`/`manifest_written` must come from the SAME build run
+`tan run` just performed, in memory -- never from re-reading
+`system-manifest.yaml` off disk afterward.** The Rust oracle's own module doc
+records why (three attempts, the last two of which re-read a stale on-disk
+manifest and let a `--flash` slip through against the WRONG target). `tan build` writes the post-build `system-manifest.yaml` and
+`execute.last_manifest_write()` supplies the real signal, so
+`tan.commands.run_cmd` passes the genuine `native_sim_target` / `manifest_written`
+pair and the FLASH and EXECUTE_NATIVE arms are reachable. `native_sim_target=None`
+still means "could not be established", never "not native_sim".
+"""
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+#: The Zephyr board target of a `native_sim` slice -- the robust
+#: discriminator for the host build (an actual `board` value from the
+#: manifest, not a build-dir-name guess). Verbatim from `tan_core::run`.
+NATIVE_SIM_BOARD = "native_sim"
+
+#: The literal binary Zephyr's `native_sim` target produces -- a fixed name on
+#: every host OS. It sits beside `zephyr.elf` in the build's `zephyr/` output
+#: dir.
+#:
+#: Module-private (the oracle's equivalent is `pub(crate)`, run.rs:166-169 --
+#: the #83 fix): [`native_sim_exe_beside`] is the ONLY sanctioned way to spell
+#: the swap. A third caller importing this constant to hand-roll
+#: `parent().join(NATIVE_SIM_EXE)` again would silently reopen the door #83
+#: closed -- see that function's docstring.
+_NATIVE_SIM_EXE = "zephyr.exe"
+
+
+class RunAction(StrEnum):
+    """What `tan run` does after its build step -- the pure decision,
+    decoupled from the subprocess/filesystem work so it is unit-testable
+    without a real build."""
+
+    #: The build failed -- short-circuit: never run or flash, report the build.
+    BUILD_FAILED = "build_failed"
+    #: A host target -- execute the produced `native_sim` binary.
+    EXECUTE_NATIVE = "execute_native"
+    #: A hardware target with an explicit `--flash`, and THIS run's manifest
+    #: write is confirmed to have succeeded -- flash the built image.
+    FLASH = "flash"
+    #: A hardware target WITHOUT `--flash` -- build succeeded, but programming
+    #: the board needs explicit consent: report + stop, leave hardware
+    #: untouched.
+    BUILD_ONLY = "build_only"
+    #: `--flash` was requested, but this run's OWN build outcome does not
+    #: confirm it is safe to flash: either the target could not be
+    #: established at all (`native_sim_target is None`), or it is hardware
+    #: but THIS run's manifest file write failed (`manifest_written` is
+    #: `False`). Refuse rather than flash from a build that can't vouch for
+    #: itself. Board untouched, same as `BUILD_ONLY`, but reported as an
+    #: error: the caller explicitly asked to flash and that request could not
+    #: be honored safely.
+    MANIFEST_STALE = "manifest_stale"
+
+
+def decide_run_action(
+    build_ok: bool,
+    native_sim_target: bool | None,
+    flash_requested: bool,
+    manifest_written: bool,
+) -> RunAction:
+    """Decide what `tan run` does once the build step finished -- entirely
+    from signals THIS build produced, never from a post-hoc disk read (see
+    the module doc for why that used to be the actual defect).
+
+    - `native_sim_target` is `True`/`False` when this run's build established
+      a target (from the SDK's freshly-emitted system-manifest projection,
+      independent of whether the on-disk file write then succeeded), or
+      `None` when it could not (the emit itself failed/didn't parse) -- an
+      unconfirmed target, not "not native_sim".
+    - `manifest_written` is whether THIS run's `system-manifest.yaml` file
+      write actually succeeded -- the "write definitely succeeded" signal
+      that gates `--flash` for a confirmed hardware target (a failed write
+      means `flash` would next read a stale/wrong file).
+
+    Rules (verbatim from `tan_core::run::decide_run_action`):
+    - build failed                                     -> BUILD_FAILED
+    - host target (`True`)                             -> EXECUTE_NATIVE
+      (never FLASH: native_sim is not flashable, regardless of `--flash`/
+      `manifest_written`)
+    - hardware (`False`) + `--flash` + write ok         -> FLASH
+    - hardware (`False`) + `--flash`, write failed      -> MANIFEST_STALE
+    - hardware (`False`), no `--flash`                  -> BUILD_ONLY
+    - unknown (`None`) + `--flash`                      -> MANIFEST_STALE (refuse)
+    - unknown (`None`), no `--flash`                    -> BUILD_ONLY
+    """
+    if not build_ok:
+        return RunAction.BUILD_FAILED
+    if native_sim_target is True:
+        # A host target is never flashable -- settled by THIS run's own build
+        # outcome, so a failed/absent manifest FILE write can't flip a host
+        # build into FLASH.
+        return RunAction.EXECUTE_NATIVE
+    if native_sim_target is False:
+        if not flash_requested:
+            return RunAction.BUILD_ONLY
+        return RunAction.FLASH if manifest_written else RunAction.MANIFEST_STALE
+    # native_sim_target is None: this run's build could not confirm host vs.
+    # hardware at all. Flashing blind is never acceptable; a bare run still
+    # gets to report + stop like any other hardware-shaped build.
+    return RunAction.MANIFEST_STALE if flash_requested else RunAction.BUILD_ONLY
+
+
+def is_native_sim_board(board: Any) -> bool:
+    """True for the bare `native_sim` board AND Zephyr's qualified board form
+    (`native_sim/native/64`, SoC/variant-qualified). Exact-matching only the
+    bare name let a qualified board name defeat the host-vs-hardware
+    discriminator on a perfectly fresh manifest. `"native_simulated_foo"`
+    deliberately does NOT match -- the required `/` after the prefix anchors
+    it to Zephyr's actual board-qualifier syntax instead of an arbitrary
+    substring."""
+    return isinstance(board, str) and (
+        board == NATIVE_SIM_BOARD or board.startswith(f"{NATIVE_SIM_BOARD}/")
+    )
+
+
+def native_sim_slice(manifest: Any) -> dict[str, Any] | None:
+    """The `native_sim` slice in a post-build manifest, if any -- identified
+    by its Zephyr board target ([`is_native_sim_board`]). `manifest` is a
+    `tan.core.system_manifest.SystemManifest`; its `slices` are raw dicts
+    (the manifest reader's own lossless-round-trip convention). Pure: no IO.
+    """
+    return next(
+        (s for s in manifest.slices if is_native_sim_board(s.get("board"))), None
+    )
+
+
+def native_sim_exe_beside(elf: str) -> str:
+    """Swap a native_sim slice's `output_artefact` for the runnable
+    [`_NATIVE_SIM_EXE`] that sits beside it. A manifest NEVER records the
+    `.exe`: `output_artefact` always names `zephyr.elf`, for every zephyr
+    slice including native_sim, so every consumer that wants the host
+    runnable has to make this swap -- and must all make the SAME one. This is
+    THE one spelling of the rule: `tan.commands.debug_config_cmd` calls this
+    function rather than carrying its own copy (the #83 fix this module's
+    `_NATIVE_SIM_EXE` docstring records).
+
+    Splits on the separator the path itself uses rather than normalising via
+    a path library, which on Windows would rejoin with `\\` and turn a
+    `/`-authored manifest path into a mixed `a/b\\zephyr.exe`."""
+    cut = max(elf.rfind("/"), elf.rfind("\\"))
+    return _NATIVE_SIM_EXE if cut < 0 else elf[: cut + 1] + _NATIVE_SIM_EXE