tan-cli 0.7.0__py3-none-any.whl

tan/core/flow_d_report.py

@@ -0,0 +1,381 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pure facts about a Flow D write, for the envelope (tan-cli#1321, #1318).
+
+Two halves, both IO-free:
+
+**What a J-Link transcript says (tan-cli#1321).** `verifybin` compares the file
+against J-Link's flash CACHE, not the chip, so "verified" overstated what was
+proven (alp-sdk#2233: on this bench only a fresh-session read after a cold cycle
+proves a write). The envelope reports `verification: "cache-verified"`, the SW-DP
+ID the transcript actually carried, and every reset-failure marker in it
+(tan-cli#522: `Failed to halt CPU` was already caught; `Reset: Failed` and
+`CPU may have not been reset` are the same condition worded by other J-Link
+builds).
+
+**What a write would do (tan-cli#1318).** Every write as `{address, size,
+sectorSpan}` with 16 KiB sectors -- the AEN MRAM loader rewrites whole sectors
+and fills the remainder with 0xFF, so a write's footprint is wider than its
+size, and the operator needs it before arming.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+from collections.abc import Sequence
+from typing import Any
+
+from tan.core.dp_id import _dp_id_value
+from tan.core.flash_plan import FlashPlanError, commander_path, validate_commander_path
+
+#: The MRAM loader's erase/rewrite granule on the AEN parts (tan-cli#1318).
+SECTOR_BYTES = 16 * 1024
+
+#: What `verifybin` proves, in the one spelling the envelope and message use.
+VERIFICATION_CACHE = "cache-verified"
+VERIFICATION_READBACK = "readback-verified"
+#: Stated once, beside the field, so a consumer is not left reading
+#: "verified" as "the chip holds these bytes".
+VERIFICATION_NOTE = (
+    "verifybin compares the image against J-Link's flash cache, not the chip; a "
+    "fresh-session read after a cold power cycle is what proves a write "
+    "(alp-sdk#2233). --readback adds a fresh-session read-back + sha256 compare."
+)
+
+#: What a matching read-back proves: a FRESH J-Link session read the same bytes. Still
+#: not a cold-cycle proof (alp-sdk#2233).
+VERIFICATION_READBACK_NOTE = (
+    "a fresh J-Link session read the written regions back and their sha256 matches the "
+    "source files; this is stronger than the flash cache but is not a cold-power-cycle "
+    "proof (alp-sdk#2233)."
+)
+
+#: J-Link Commander phrasing that means the PIN reset (`RSetType 2` / `r` / `g`)
+#: did not land. Substring-matched against the captured transcript; the exit
+#: code cannot tell these runs apart (JLinkExe still exits 0).
+RESET_FAILURE_MARKERS = (
+    "Failed to halt CPU",
+    "CPU is not halted",
+    "Reset: Failed",
+    "CPU may have not been reset",
+)
+
+
+def reset_failures(transcript: str) -> tuple[str, ...]:
+    """Every reset-failure marker present in `transcript`, in marker order."""
+    return tuple(m for m in RESET_FAILURE_MARKERS if m in transcript)
+
+
+#: Core-debug DHCSR (0xE000EDF0) bits (tan-cli#1453). S_RESET_ST and S_RETIRE_ST are
+#: sticky but CLEAR ON READ, and J-Link reads DHCSR itself (a failed halt, the probe's
+#: own `connect`) before tan does -- so only S_RESET_ST (a reset happened since the last
+#: read, with no lockup) counts as proof that THIS reset booted. S_SLEEP / S_RETIRE_ST
+#: alone are also what the OLD image idling looks like, so they prove only that a core is
+#: running, never that the reset took.
+DHCSR_ADDRESS = "0xE000EDF0"
+DHCSR_S_HALT = 1 << 17
+DHCSR_S_SLEEP = 1 << 18
+DHCSR_S_LOCKUP = 1 << 19
+DHCSR_S_RETIRE_ST = 1 << 24
+DHCSR_S_RESET_ST = 1 << 25
+_DHCSR_RAN = DHCSR_S_SLEEP | DHCSR_S_RETIRE_ST | DHCSR_S_RESET_ST
+
+#: Probe-transcript phrasing that means the probe session itself reset or tried to halt
+#: the core, which makes its DHCSR read evidence of that session, not of the flash's reset.
+PROBE_TROUBLE_MARKERS = ("Reset:",)
+
+#: DWT_PCSR, the program-counter sample register: a NON-halting witness of where a RUNNING
+#: core is executing (tan-cli#1453 review). DHCSR's S_RESET_ST is cleared by J-Link's own
+#: reads and will usually be gone, so this is the second witness. It needs the DWT unit
+#: present (Cortex-M55 has it) and readable while the core runs; a halted or sleeping core
+#: returns 0xFFFFFFFF, which is no sample at all.
+DWT_PCSR_ADDRESS = "0xE000101C"
+PCSR_NO_SAMPLE = 0xFFFFFFFF
+#: 0x00000000 is not a sample either (a gated or unpowered DWT reads as zero).
+PCSR_NO_SAMPLES = (PCSR_NO_SAMPLE, 0x00000000)
+PCSR_SAMPLES = 3
+
+
+def nohalt_probe_script(jlink_script: str, extra_reads: Sequence[str] = ()) -> str:
+    """A fresh, read-only, NON-halting session: the write's preamble up to and including
+    `connect`, one `mem32` of DHCSR, the PCSR samples, then `extra_reads` (the read-only uptime
+    reads of tan-cli#1539), `exit` (tan-cli#1453). Raises `ValueError` without a `connect` line."""
+    out: list[str] = []
+    for line in jlink_script.splitlines():
+        out.append(line)
+        if line.strip().lower() == "connect":
+            break
+    else:
+        raise ValueError("the write script has no `connect` line to build a probe from")
+    out.append(f"mem32 {DHCSR_ADDRESS} 1")
+    for _ in range(PCSR_SAMPLES):
+        out += [f"mem32 {DWT_PCSR_ADDRESS} 1", "Sleep 5"]
+    out += extra_reads
+    out.append("exit")
+    return "\n".join(out) + "\n"
+
+
+def dhcsr_in(transcript: str) -> int | None:
+    """The DHCSR word a `mem32 0xE000EDF0 1` printed (`E000EDF0 = 03050001`), or `None`."""
+    match = re.search(r"E000EDF0\s*=\s*([0-9A-Fa-f]{8})", transcript)
+    return int(match.group(1), 16) if match else None
+
+
+def dhcsr_confirms_reset(value: int | None) -> bool:
+    """True only when `value` shows a reset since the last read (S_RESET_ST) on a core
+    that is neither halted nor locked up."""
+    return (
+        value is not None and bool(value & DHCSR_S_RESET_ST)
+        and not value & (DHCSR_S_HALT | DHCSR_S_LOCKUP)
+    )
+
+
+def dhcsr_core_running(value: int | None) -> bool:
+    """True when `value` shows a running core (retired an instruction, slept, or reset)
+    that is not halted or locked up. This does NOT say the reset took."""
+    return (
+        value is not None and bool(value & _DHCSR_RAN)
+        and not value & (DHCSR_S_HALT | DHCSR_S_LOCKUP)
+    )
+
+
+def pcsr_samples(transcript: str) -> list[int]:
+    """Every PC sample a `mem32 0xE000101C 1` printed, in order (0xFFFFFFFF included)."""
+    return [int(m, 16) for m in re.findall(r"E000101C\s*=\s*([0-9A-Fa-f]{8})", transcript)]
+
+
+def pcsr_in_ranges(samples: Sequence[int], ranges: Sequence[tuple[int, int]]) -> bool:
+    """True when at least one real sample exists and EVERY real sample lies inside
+    `ranges` (`[start, end)` of the image tan just flashed). 0xFFFFFFFF is no evidence; a
+    sample outside the ranges (old image, loader, ROM) vetoes. The old image is not known to
+    tan, so an old image linked into the same range is not excluded (tan-cli#1537): a True here
+    is "the core runs code from this range", never "the new image runs" or "a reset happened"."""
+    real = [x for x in samples if x not in PCSR_NO_SAMPLES]
+    return bool(real) and bool(ranges) and all(
+        any(lo <= x < hi for lo, hi in ranges) for x in real
+    )
+
+
+def probe_trouble(transcript: str) -> tuple[str, ...]:
+    """Reset/halt markers in a boot-probe transcript (it must have done neither)."""
+    return tuple(m for m in (*PROBE_TROUBLE_MARKERS, *RESET_FAILURE_MARKERS) if m in transcript)
+
+
+def dpidr_in(transcript: str) -> str | None:
+    """The SW-DP ID the transcript reports (`Found SW-DP with ID 0x...` /
+    `DPIDR: 0x...`), verbatim, or `None` when it names none."""
+    return _dp_id_value(transcript)
+
+
+def transcript_tail(transcript: str, lines: int = 40) -> list[str]:
+    """The last `lines` non-empty lines of `transcript`."""
+    kept = [line.rstrip() for line in transcript.splitlines() if line.strip()]
+    return kept[-lines:]
+
+
+def sector_span(address: int, size: int, sector: int = SECTOR_BYTES) -> dict[str, Any]:
+    """The sectors a write of `size` bytes at `address` touches: the first
+    sector's base address, the last sector's END (exclusive), the count and the
+    byte footprint (count * sector). A zero-size write touches nothing."""
+    if size <= 0:
+        return {"first": hex_addr(address - address % sector), "end": hex_addr(address - address % sector),
+                "count": 0, "bytes": 0, "sectorBytes": sector}
+    first = address - address % sector
+    last = (address + size - 1) - (address + size - 1) % sector
+    count = (last - first) // sector + 1
+    return {
+        "first": hex_addr(first),
+        "end": hex_addr(last + sector),
+        "count": count,
+        "bytes": count * sector,
+        "sectorBytes": sector,
+    }
+
+
+def hex_addr(value: int) -> str:
+    return f"0x{value:08X}"
+
+
+def planned_write(name: str, address: str, size: int | None, path: str | None) -> dict[str, Any]:
+    """One planned write as the envelope reports it. `size` is `None` when the
+    file is not readable yet (the dry-run of a hand-written manifest)."""
+    entry: dict[str, Any] = {"name": name, "address": address, "path": path, "size": size}
+    if size is not None:
+        entry["sectorSpan"] = sector_span(int(address, 16), size)
+    return entry
+
+
+def sha256_of(path: str) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def reset_tail(jlink_script: str) -> list[str]:
+    """The write script's reset/run tail -- from its first `RSetType` line up to (not
+    including) the final `exit` -- so a read-back ends the same way the write did and
+    the app is not left halted. `["g"]` when the script has no `RSetType`."""
+    lines = [line for line in jlink_script.splitlines() if line.strip()]
+    for i, line in enumerate(lines):
+        if line.strip().lower().startswith("rsettype"):
+            end = len(lines) - 1 if lines[-1].strip().lower() == "exit" else len(lines)
+            return lines[i:end]
+    return ["g"]
+
+
+#: What an in-session read-back proves (tan-cli#1458): the chip's bytes were read back after a
+#: halt, in the write's own session, before the reset -- NOT a fresh session, so J-Link's
+#: flash cache may sit between the read and the cells.
+VERIFICATION_INSESSION = "insession-readback"
+VERIFICATION_INSESSION_NOTE = (
+    "the written regions were read back with savebin in the SAME J-Link session as the write, "
+    "after a halt and before the PIN reset (a separate session would let the app run in "
+    "between); their sha256 matches the source files. J-Link may serve that read from its flash "
+    "cache, so this is NOT a fresh-session or cold-power-cycle proof (alp-sdk#2233); "
+    "`readback-verified` is reserved for a fresh-session match."
+)
+VERIFICATION_INSESSION_NORESET_NOTE = (
+    "the written regions were read back with savebin in the SAME J-Link session as the write, "
+    "after a halt; no reset command was sent (--no-reset); their sha256 matches the source "
+    "files. J-Link may serve that read from its flash cache, so this is NOT a fresh-session or "
+    "cold-power-cycle proof (alp-sdk#2233); `readback-verified` is reserved for a fresh-session "
+    "match."
+)
+
+#: J-Link Commander phrasing for "no debug access to the target right now" -- a gated
+#: debug domain (the app is in STOP/WFI) as much as a bad cable (tan-cli#1450).
+UNREACHABLE_MARKERS = (
+    "Could not read memory",
+    "Cannot read memory",
+    "Cannot connect to target",
+    "Could not connect to target",
+    "Connecting to target failed",
+)
+
+
+def target_unreachable(transcript: str) -> bool:
+    """Whether `transcript` says the target could not be reached for a memory read."""
+    return any(m in transcript for m in UNREACHABLE_MARKERS)
+
+
+def drop_reset_tail(jlink_script: str) -> str:
+    """The write script WITHOUT its reset/run tail (`RSetType` .. final `exit`): connect,
+    loadbin, verifybin, `exit`. For `--no-reset` (tan-cli#1445): no reset command is sent. J-Link's
+    `exit` may still resume the core (bench, tan-cli#1458), which is why the envelope says so."""
+    lines = [line for line in jlink_script.splitlines() if line.strip()]
+    for i, line in enumerate(lines):
+        if line.strip().lower().startswith("rsettype"):
+            return "\n".join([*lines[:i], "exit"]) + "\n"
+    return jlink_script
+
+
+def combined_script(
+    jlink_script: str, regions: Sequence[tuple[str, int, str]], tail: bool = True
+) -> str:
+    """The write session WITH the read-back inside it (tan-cli#1458, bench): everything up to
+    the first `RSetType` (connect, loadbin, verifybin), then `h`, one `savebin` per region,
+    the write's own reset/run tail, `exit`. There is NO `exit` between the write and the read:
+    J-Link's `exit` resumes the core even after `h`, so a separate read-back session let the
+    app run on stale state before it connected. `regions` is `(address_hex, size, dest)`.
+    `tail=False` (`--no-reset`) ends after the read with `exit` and no reset/run commands; the
+    script then needs no `RSetType`. Otherwise raises `ValueError` without a `RSetType` tail to
+    keep (nothing to run after the read)."""
+    lines = [line for line in jlink_script.splitlines() if line.strip()]
+    for i, line in enumerate(lines):
+        if line.strip().lower().startswith("rsettype"):
+            break
+    else:
+        if tail:
+            raise ValueError("the write script has no reset tail to run after the read-back")
+        i = len(lines) - 1 if lines and lines[-1].strip().lower() == "exit" else len(lines)
+    tail_lines = reset_tail(jlink_script) if tail else []
+    out = [*lines[:i], "h"]
+    for address, size, dest in regions:
+        validate_commander_path(dest, "the read-back destination path")
+        out.append(f"savebin {commander_path(dest)} {address} 0x{size:X}")
+    return "\n".join([*out, *tail_lines, "exit"]) + "\n"
+
+
+def readback_script(
+    jlink_script: str,
+    regions: Sequence[tuple[str, int, str]],
+) -> str:
+    """The Commander script of a FRESH read-back session: the same preamble the
+    write used (everything up to and including `connect`, so the same probe,
+    interface, speed and part-number device), then one `savebin <file>, <addr>,
+    <size>` per region and `exit`. `regions` is `(address_hex, size, dest_path)`.
+    The session ends at `exit` WITHOUT the write's reset/run tail (a raw sector write must
+    not reset or run anything, tan-cli#1446; Flow D reads inside its write session instead,
+    see [`combined_script`]).
+    Raises `ValueError` if `jlink_script` has no `connect` line."""
+    out: list[str] = []
+    for line in jlink_script.splitlines():
+        out.append(line)
+        if line.strip().lower() == "connect":
+            break
+    else:
+        raise ValueError("the write script has no `connect` line to build a read-back from")
+    for address, size, dest in regions:
+        validate_commander_path(dest, "the read-back destination path")
+        out.append(f"savebin {commander_path(dest)} {address} 0x{size:X}")
+    out.append("exit")
+    return "\n".join(out) + "\n"
+
+
+# ── sector overlap (tan-cli#1343 review) ────────────────────────────────────
+
+CODE_SECTOR_OVERLAP = "flash.write-sector-overlap"
+
+
+class SectorOverlapError(FlashPlanError):
+    """Two writes (or a write and a resident entry that will not be rewritten)
+    share a 16 KiB sector. `code` is the registered issue code."""
+
+    code = CODE_SECTOR_OVERLAP
+
+
+def _interval(address: int, size: int | None) -> tuple[int, int]:
+    """`[first, end)` of the sectors touched by `size` bytes at `address`; an
+    unknown size counts as one sector (the least it can touch)."""
+    first = address - address % SECTOR_BYTES
+    last = address + max((size or 1), 1) - 1
+    return first, last - last % SECTOR_BYTES + SECTOR_BYTES
+
+
+def find_overlaps(
+    writes: Sequence[dict[str, Any]],
+    resident: Sequence[tuple[str, int | None, int | None]] = (),
+) -> list[str]:
+    """Human descriptions of every sector overlap among `writes`
+    (`{name, address, size}` dicts) and between a write and a `resident`
+    `(name, address, size)` region (entries with no address are skipped: tan
+    cannot place what it was not told). The loader rewrites WHOLE sectors, so a
+    write whose tail reaches the next write's first sector would erase the
+    neighbour's head."""
+    spans = [
+        (w["name"], *_interval(int(w["address"], 16), w.get("size")))
+        for w in writes
+        if w.get("address")
+    ]
+    out: list[str] = []
+    for i, (a_name, a_lo, a_hi) in enumerate(spans):
+        for b_name, b_lo, b_hi in spans[i + 1 :]:
+            if a_lo < b_hi and b_lo < a_hi:
+                lo, hi = max(a_lo, b_lo), min(a_hi, b_hi)
+                out.append(
+                    f"the {a_name} write and the {b_name} write share the 16 KiB sector(s) "
+                    f"{hex_addr(lo)}-{hex_addr(hi)}"
+                )
+    for r_name, r_addr, r_size in resident:
+        if r_addr is None:
+            continue
+        r_lo, r_hi = _interval(r_addr, r_size)
+        for w_name, w_lo, w_hi in spans:
+            if w_lo < r_hi and r_lo < w_hi:
+                out.append(
+                    f"the {w_name} write's sectors {hex_addr(w_lo)}-{hex_addr(w_hi)} cover the "
+                    f"resident entry {r_name} at {hex_addr(r_addr)}, and no write here replaces it "
+                    "(a write starting at exactly that address does)"
+                )
+    return out

tan/core/flow_d_uptime.py

@@ -0,0 +1,164 @@
+# SPDX-License-Identifier: Apache-2.0
+"""tan-cli#1539: a boot witness for Flow D -- the kernel uptime, bounded by the wall clock.
+
+After a write whose halt failed, DHCSR `S_RESET_ST` is usually gone and PC samples cannot tell the
+new image from the replaced one (tan-cli#1537). A free-running tick counter can, provided it is
+compared with the time tan itself measured: the probe's last read must show an uptime no larger
+than the monotonic time elapsed since the write session ended (plus a slack for the reset tail
+inside that session). SysTick stops while the core is halted for the write, so an image that was
+already running when the write began resumes with its uptime frozen at the halt; the bound admits it
+only if that frozen uptime was at most the slack, i.e. it booted under ~1 s before the write halted
+it, which the preceding probe/preflight sessions already rule out in practice.
+This proves a RECENT BOOT, not that the SE PIN reset took (reported as `reset: "booted"`).
+
+The counter is Zephyr's kernel tick count (`curr_tick`, a `static uint64_t` in `kernel/timeout.c`;
+present in an AEN alp-console ELF at a DTCM address). Its address is resolved from the ELF being
+flashed, never hardcoded, and only an address inside a RAM LOAD segment of the slice core's own
+DTCM / SRAM0 is ever read (never HP ITCM 0x50000000, never anything outside the image). The tick
+rate comes from the same ELF's absolute `CONFIG_SYS_CLOCK_TICKS_PER_SEC` symbol, else the build's
+`.config` beside it. Anything missing, ambiguous or out of range yields no probe, and the caller
+keeps the honest `unconfirmed`. Pure: no IO except `load_uptime_probe` reading two local files."""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from typing import Sequence
+
+from tan.core.ram_run import ElfImage, RamRunError, parse_elf
+
+UPTIME_SYMBOL = "curr_tick"
+TICKS_PER_SEC_SYMBOL = "CONFIG_SYS_CLOCK_TICKS_PER_SEC"
+#: Reads per session, and the pause between them (ms). The tick only advances when the timeout
+#: ISR announces, so the window must span more than one idle wake-up of a typical sleeper.
+UPTIME_READS = 4
+UPTIME_SLEEP_MS = 600
+#: Slack (s) added to the elapsed time: the reset tail runs inside the write session, so the
+#: image boots slightly BEFORE the session's end timestamp. Measured on e1m-aen-evk-02
+#: (alp-console, 2026-10-11): uptime - elapsed = -0.04..-0.05 s, so 1 s is all headroom.
+UPTIME_SLACK_SECONDS = 1.0
+#: The only address windows ever read: the slice core's DTCM (local alias, 1 MiB window) and the
+#: E8's 4 MiB SRAM0. HP ITCM (0x50000000) and every other aperture are out.
+_READABLE = ((0x20000000, 0x20100000), (0x02000000, 0x02400000))
+
+
+@dataclass(frozen=True)
+class UptimeProbe:
+    address: int
+    size: int  # 4 or 8 bytes
+    ticks_per_sec: int
+    symbol: str = UPTIME_SYMBOL
+
+    @property
+    def words(self) -> int:
+        return self.size // 4
+
+
+def plan_uptime_probe(elf: ElfImage, config_ticks_per_sec: int | None = None) -> UptimeProbe | None:
+    """The probe for `elf`, or `None` when the symbol is missing, ambiguous, oddly sized, outside
+    the readable RAM windows or outside a RAM LOAD segment, or the tick rate is unknown."""
+    if UPTIME_SYMBOL in elf.ambiguous or UPTIME_SYMBOL not in elf.symbols:
+        return None
+    address, size = elf.symbols[UPTIME_SYMBOL]
+    if size not in (4, 8) or address % 4:
+        return None
+    end = address + size
+    if not any(lo <= address and end <= hi for lo, hi in _READABLE):
+        return None
+    if not any(s.vaddr <= address and end <= s.vaddr + s.memsz for s in elf.segments):
+        return None
+    rate = config_ticks_per_sec
+    if TICKS_PER_SEC_SYMBOL in elf.symbols and TICKS_PER_SEC_SYMBOL not in elf.ambiguous:
+        rate = elf.symbols[TICKS_PER_SEC_SYMBOL][0]
+    if not rate or rate <= 0:
+        return None
+    return UptimeProbe(address, size, rate)
+
+
+def config_ticks_per_sec(config_text: str) -> int | None:
+    match = re.search(r"^CONFIG_SYS_CLOCK_TICKS_PER_SEC=(\d+)\s*$", config_text, re.MULTILINE)
+    return int(match.group(1)) if match else None
+
+
+def load_elf(elf_path: str) -> ElfImage | None:
+    """The parsed ELF at `elf_path`, or `None` when it cannot be read or parsed."""
+    try:
+        with open(elf_path, "rb") as fh:
+            return parse_elf(fh.read())
+    except (OSError, RamRunError):
+        return None
+
+
+def load_uptime_probe(elf: ElfImage | None, elf_path: str) -> UptimeProbe | None:
+    """`plan_uptime_probe` for the parsed `elf` (read from `elf_path`, whose directory may hold
+    the build's `.config`); `None` when there is no ELF."""
+    if elf is None:
+        return None
+    rate = None
+    try:
+        with open(os.path.join(os.path.dirname(elf_path), ".config"), encoding="utf-8") as fh:
+            rate = config_ticks_per_sec(fh.read())
+    except OSError:
+        pass
+    return plan_uptime_probe(elf, rate)
+
+
+def uptime_script_lines(probe: UptimeProbe) -> list[str]:
+    """Read-only Commander lines: `UPTIME_READS` non-halting `mem32` reads of the counter."""
+    out: list[str] = []
+    for i in range(UPTIME_READS):
+        out.append(f"mem32 0x{probe.address:08X} {probe.words}")
+        if i + 1 < UPTIME_READS:
+            out.append(f"Sleep {UPTIME_SLEEP_MS}")
+    return out
+
+
+def uptime_ticks(transcript: str, probe: UptimeProbe) -> list[int]:
+    """Every counter value the probe's `mem32` lines printed, in order (little-endian words)."""
+    pattern = rf"(?<![0-9A-Fa-f]){probe.address:08X}\s*=\s*((?:[0-9A-Fa-f]{{8}}\s*){{{probe.words}}})"
+    values: list[int] = []
+    for match in re.finditer(pattern, transcript, re.IGNORECASE):
+        words = [int(w, 16) for w in match.group(1).split()]
+        values.append(sum(w << (32 * i) for i, w in enumerate(words)))
+    return values
+
+
+def uptime_confirms_boot(
+    ticks: Sequence[int], ticks_per_sec: int, elapsed_s: float,
+    slack_s: float = UPTIME_SLACK_SECONDS,
+) -> bool:
+    """True only for a counter that moved (never going backwards, last > first) and whose last
+    value is no more uptime than `elapsed_s` (monotonic seconds since the write session ended)
+    plus `slack_s`. A constant counter is a halted or gated core; a larger uptime is an image
+    that was running before the write; an all-ones word is an unreadable bus, not a count. The
+    64-bit counter is read as two 32-bit words, so a read can tear across a carry: it shows as a
+    huge jump or a step backwards and is rejected by the same rules."""
+    if len(ticks) < 2 or any(t in (0xFFFFFFFF, 0xFFFFFFFFFFFFFFFF) for t in ticks):
+        return False
+    if any(b < a for a, b in zip(ticks, ticks[1:])) or ticks[-1] <= ticks[0]:
+        return False
+    return ticks[-1] / ticks_per_sec <= elapsed_s + slack_s
+
+
+def uptime_evidence(
+    transcript: str, probe: UptimeProbe, elapsed_s: float
+) -> tuple[dict, dict | None]:
+    """`(bootProbe.uptime evidence, jlink-block update)`; the update is `None` unless the
+    counter confirms a boot."""
+    ticks = uptime_ticks(transcript, probe)
+    evidence = {
+        "symbol": probe.symbol, "address": f"0x{probe.address:08X}",
+        "ticks": [f"0x{t:X}" for t in ticks], "ticksPerSec": probe.ticks_per_sec,
+        "elapsedSinceWriteSeconds": round(elapsed_s, 2),
+    }
+    if not uptime_confirms_boot(ticks, probe.ticks_per_sec, elapsed_s):
+        return evidence, None
+    return evidence, {
+        "coreRunning": True, "reset": "booted", "resetConfirmedBy": "uptime",
+        "witness": f"{probe.symbol} 0x{ticks[0]:X} -> 0x{ticks[-1]:X}, up "
+        f"{ticks[-1] / probe.ticks_per_sec:.1f} s, {elapsed_s:.1f} s after the write",
+        "resetNote": "the halt after the reset failed, but the kernel tick counter "
+        f"({probe.symbol}, read without halting at the flashed ELF's own address) is rising and "
+        "shows no more uptime than the time elapsed since the write ended: the image booted "
+        "after the write. That proves a recent boot, not that the SE PIN reset took.",
+    }

tan/core/fs_confine.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The one containment guard every ACTIVE project writer trusts.
+
+`tan init` (`tan.core.scaffold.write_files`) and `tan generate`
+(`tan.commands.generate_cmd`, its default -- non-`--output` -- targets) both
+join a caller-controlled relative path onto a project root and write there.
+Neither used to check the RESOLVED target after following symlinks, so a
+pre-existing directory symlink under the project (`<project>/src` ->
+somewhere else) or a symlinked existing leaf silently redirected the write
+outside the project while the envelope still reported the logical in-project
+path as written (tan-cli#325).
+
+`confine_to_build_root` (`tan.commands.build.materialise`) is the same
+question for a DIFFERENT root (a build root, reused by `tan clean`) with its
+own coded error (`build.path-escape`) and its own message shape; this module
+is `resolve_confined` for the other two writers, not a third hand-rolled copy
+of the same predicate (tan-cli#322 is exactly this drift: bootstrap and doctor
+each grew their own resolver).
+
+`Path.is_relative_to()` on TWO resolved paths, not a string prefix test:
+resolving both sides is what makes a symlinked PROJECT ROOT itself still work
+(`is_relative_to` only needs the root to be a prefix of the target's own
+resolved components, so a project opened through a symlink still confines
+correctly -- the escape this guards against is a write LANDING outside the
+root, not the root being reached through one), and `is_relative_to` is
+correct on Windows where a naive `str(target).startswith(str(root))` is not:
+path comparison there folds case (`C:\\Foo` vs `c:\\foo`) and a bare
+`startswith` would also wrongly accept a sibling directory whose name happens
+to share the root's as a prefix (`C:\\proj` vs `C:\\project2`).
+
+That case-folding is a `PureWindowsPath` property, NOT a filesystem one, and
+those two came apart on macOS (tan-cli#587). `PurePosixPath.is_relative_to`
+compares case-SENSITIVELY, and `Path.resolve()` does not canonicalise case on
+a POSIX flavour to hide the difference -- `posixpath.realpath` walks the path
+with `os.lstat`/`os.readlink` only and never asks the filesystem for a
+component's true on-disk name, so `<tmp>/PROJECT` stays `<tmp>/PROJECT` even
+where it names the very directory created as `<tmp>/Project`. On APFS (the
+macOS default, case-INSENSITIVE and case-preserving) that made the guard
+refuse a target genuinely inside the root. The failure direction was
+over-restriction, never a bypass, but a `PathEscapeError` naming a path the
+user can plainly see inside their project is a refusal that cannot be
+trusted, and this module exists to be trusted.
+
+The fallback below is INODE IDENTITY (`os.path.samestat`), not case folding.
+Folding would be wrong on a case-sensitive volume, where `<tmp>/Project` and
+`<tmp>/PROJECT` are two different directories and accepting the second as
+inside the first is exactly the escape this guards against; asking the
+filesystem whether the two names reach the same directory is right on both
+kinds of volume, and needs no guess about which kind is underfoot.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+class PathEscapeError(Exception):
+    """`target` resolved outside `root` after symlink resolution. Carries both
+    resolved paths so a caller can phrase its own coded issue message rather
+    than parsing this one."""
+
+    def __init__(self, root: Path, target: Path) -> None:
+        super().__init__(f"'{target}' resolves outside '{root}'")
+        self.root = root
+        self.target = target
+
+
+def _reaches_the_same_root(resolved_root: Path, resolved_target: Path) -> bool:
+    """True when `resolved_target`'s first `len(resolved_root.parts)` components
+    name the SAME directory as `resolved_root`, spelled differently.
+
+    Only the prefix at the root's own depth is compared, and only by
+    `os.stat` identity: if that prefix IS the root directory, everything after
+    it lands inside the root by construction -- `resolved_target` has already
+    had every symlink followed by `Path.resolve()`, so the remaining
+    components are literal, not another indirection waiting to redirect the
+    write.
+
+    A shorter target than the root cannot be inside it, and an `OSError` (the
+    prefix does not exist, or is unreadable) answers the question `False`:
+    this runs only after `is_relative_to` already said no, so `False` simply
+    keeps the pre-existing refusal.
+
+    Not restricted to case: a bind mount or any other alias that makes two
+    spellings reach one directory answers `True` here, which is the same
+    answer for the same reason -- the write lands inside the root either way,
+    and "the write LANDS outside the root" is the escape being guarded.
+    """
+    root_parts = resolved_root.parts
+    target_parts = resolved_target.parts
+    if len(target_parts) < len(root_parts):
+        return False
+    prefix = Path(*target_parts[: len(root_parts)])
+    try:
+        return os.path.samestat(os.stat(prefix), os.stat(resolved_root))
+    except OSError:
+        return False
+
+
+def resolve_confined(root: Path, target: Path) -> Path:
+    """Resolve `target` and require it stays inside the resolved `root`.
+
+    Returns the resolved target. Raises `PathEscapeError` when it does not --
+    including when a symlinked (or junctioned) PARENT directory of `target`
+    points outside `root`, and when `target` itself is a symlink to a file
+    outside `root`; `Path.resolve()` follows both. `target` need not exist:
+    `resolve(strict=False)` (the default) resolves every symlink it finds and
+    appends any remaining, not-yet-created components literally, so a `new`
+    file under a symlinked parent is caught exactly like an existing one.
+
+    Callers should also catch `OSError`/`ValueError` around this call: a path
+    shape the host rejects outright (a Windows device-namespace path, one
+    embedding a NUL) raises there, not here, and is a refusal either way.
+
+    The returned path keeps the CALLER's spelling of the components it was
+    given (`<tmp>/PROJECT/board.yaml`, not `<tmp>/Project/board.yaml`) on the
+    identity path: on a case-insensitive volume both spellings open the same
+    file, and re-spelling a caller's path from the on-disk casing would need
+    a `readdir` per component that `Path.resolve()` never performs. Compare
+    two returned paths with `os.path.samefile`, not `==`, if a test needs to
+    tie one back to a differently-spelled root (tan-cli#587).
+    """
+    resolved_root = root.resolve()
+    resolved_target = target.resolve()
+    if not resolved_target.is_relative_to(resolved_root) and not _reaches_the_same_root(
+        resolved_root, resolved_target
+    ):
+        raise PathEscapeError(resolved_root, resolved_target)
+    return resolved_target