tan-cli 0.7.0__py3-none-any.whl

tan/commands/bootstrap_patches.py

@@ -0,0 +1,164 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`tan bootstrap`'s `zephyr/patches.yml` phase (tan-cli#1296).
+
+alp-sdk carries patches against Zephyr and its modules in `zephyr/patches.yml`
+(e.g. `ipm_arm_mhuv2.c`'s `poll_out`, hal_alif's `se_service_boot_cpu`).
+`scripts/bootstrap.sh` applies them and documents them as required to build;
+`tan bootstrap` did not, and a tan-made workspace failed to compile the
+`peripheral-io/hello-world` example for E1M-AEN801 (m55_hp slice) with
+`'struct ipm_driver_api' has no member named 'poll_out'`. This mirrors that
+script's algorithm -- the SDK's own `scripts/verify_west_patches.py` is the
+oracle for "is it applied"; tan only drives it (it must not re-implement the
+SDK's patch knowledge).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from tan.core.west_patches import classify_verify, output_tail, parse_unapplied
+
+if TYPE_CHECKING:  # bootstrap_cmd imports THIS module, so no runtime import back
+    from tan.commands.bootstrap_cmd import Log, Runner, VenvBin, Workspace
+
+#: Issue-code suffixes (`bootstrap.<suffix>`); `FAILED` is a `WORKSPACE_BLOCKING`
+#: member: a tree that lacks the patches cannot build what needs them.
+FAILED = "west-patches-failed"
+UNCHECKED = "west-patches-unchecked"
+
+_VERIFIER = Path("scripts") / "verify_west_patches.py"
+_PATCHES_YML = Path("zephyr") / "patches.yml"
+
+_OPT_OUT = (
+    " Pass `--no-patches` to skip this step (zephyr/patches.yml is then NOT applied, "
+    "and builds that need those patches will not compile)."
+)
+
+
+def _detail(*chunks: str) -> str:
+    tail = output_tail("\n".join(chunk for chunk in chunks if chunk))
+    return f"\n{tail}" if tail else ""
+
+
+def _fail(log: Log, message: str, *output: str) -> None:
+    log.warn(FAILED, f"{message}{_OPT_OUT}{_detail(*output)}")
+
+
+def _report(
+    ws: Workspace, log: Log, verdict: str, out: str, err: str, *, after_apply: bool
+) -> bool:
+    """Act on a verifier verdict. True when the phase is finished; False only
+    for the one verdict that means "go apply" (`unapplied`, before applying)."""
+    if verdict == "applied":
+        when = "verified applied" if after_apply else "already applied"
+        log.line(f"zephyr/patches.yml {when} in {ws.workspace_dir}")
+    elif verdict == "unchecked":
+        # Everything inspectable is patched; a module the file names just is not
+        # in this workspace. Normal for a narrow one, so a warning.
+        log.warn(
+            UNCHECKED,
+            "some zephyr/patches.yml modules are not in this workspace, so their patches "
+            f"could not be checked.{_detail(out, err)}",
+        )
+    elif verdict == "unrunnable":
+        # Exit 2 / never launched: the patch state is UNKNOWN, so do not claim
+        # "not applied".
+        _fail(
+            log,
+            "could not run or inspect the zephyr/patches.yml verifier "
+            "(scripts/verify_west_patches.py) -- the patch state is unknown.",
+            out, err,
+        )
+    elif after_apply:
+        _fail(
+            log,
+            f"zephyr/patches.yml is still not applied in {ws.workspace_dir} after "
+            "`west patch apply`.",
+            out, err,
+        )
+    else:
+        return False
+    return True
+
+
+def _apply_missing(
+    ws: Workspace, venv: VenvBin, log: Log, runner: Runner, modules: list[str]
+) -> bool:
+    """`west patch apply` per module. False (after recording the error) on the
+    first failure."""
+    # Late import: `bootstrap_cmd` imports this module, so a top-level import
+    # of its `_west_argv` would be circular.
+    from tan.commands.bootstrap_cmd import _west_argv
+
+    for module in modules:
+        # PER MODULE, never a bare `west patch apply`: it is not idempotent, so
+        # on a partially patched workspace (zephyr patched, mcuboot fresh) it
+        # re-applies the patched module's patches and dies on the first.
+        # `--dst-module` is a flag of `west patch` ITSELF, so it precedes
+        # `apply`; the other order is a usage error.
+        log.line(f"Applying zephyr/patches.yml for module '{module}'")
+        failure = runner.run(
+            _west_argv(venv, ["patch", "--dst-module", module, "apply"]), cwd=ws.workspace_dir
+        )
+        if failure is not None:
+            # `clean` is the zephyr `west patch` default pair `git checkout .`
+            # + `git clean -d -f -x` run in the module: it is the way out of a
+            # half-applied patch, and it discards uncommitted work there.
+            _fail(
+                log,
+                f"`west patch --dst-module {module} apply` failed, so the module may be "
+                f"half-patched. To recover, run `west patch --dst-module {module} clean` "
+                f"from {ws.workspace_dir} (it runs `git checkout .` and `git clean -d -f "
+                f"-x` in that module, discarding uncommitted changes there), then re-run "
+                f"`tan bootstrap`.",
+                failure,
+            )
+            return False
+    return True
+
+
+def patches_phase(
+    ws: Workspace, venv: VenvBin, log: Log, runner: Runner, sdk_root: str
+) -> None:
+    """Verify, then apply only what is missing, then verify again.
+
+    Non-fatal like `pip_phase`/`toolchain_phase`: a failure is a recorded
+    `bootstrap.west-patches-failed` (which blocks `complete.` unless
+    `--allow-partial`), never an abort, so it cannot skip the toolchain phase.
+    """
+    sdk = Path(sdk_root)
+    verifier = sdk / _VERIFIER
+    if not verifier.is_file() or not (sdk / _PATCHES_YML).is_file():
+        # An older SDK tag simply has no patch set to apply -- not an error.
+        log.line("Skipping zephyr/patches.yml: this alp-sdk checkout carries no patch verifier")
+        return
+
+    # Run from the SDK root, like bootstrap.sh, so the verifier resolves its
+    # own `patches.yml` the way it was written to.
+    verify = [
+        str(venv.python), str(verifier),
+        "--topdir", str(ws.workspace_dir), "--west", str(venv.west),
+    ]
+    code, out, err = runner.run_status(verify, cwd=sdk)
+    if runner.dry_run:
+        log.line("Would verify zephyr/patches.yml and apply any missing patches (--dry-run)")
+        return
+    if _report(ws, log, classify_verify(code), out, err, after_apply=False):
+        return
+
+    code, listing, list_err = runner.run_status([*verify, "--list-unapplied"], cwd=sdk)
+    modules = parse_unapplied(listing) if code == 0 else []
+    if not modules:
+        _fail(
+            log,
+            "zephyr/patches.yml is not applied but the verifier named no module to patch "
+            "-- run scripts/verify_west_patches.py directly to see why.",
+            out, err, list_err,
+        )
+        return
+
+    if _apply_missing(ws, venv, log, runner, modules):
+        # `west patch apply` exits 0 on three do-nothing paths, so its status is
+        # not evidence; the verifier is.
+        code, out, err = runner.run_status(verify, cwd=sdk)
+        _report(ws, log, classify_verify(code), out, err, after_apply=True)

tan/commands/bootstrap_toolchain_fetch.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: Apache-2.0
+"""IO half of tan-cli#1496's toolchain-archive check: download the pinned
+`arm-zephyr-eabi` archive ourselves, hash it against alp-sdk's pin while it
+streams, and extract it into the layout the SDK's own `setup.sh` produces
+(`<sdk>/gnu/arm-zephyr-eabi`). West verifies only the minimal bundle and its
+`setup.sh` downloads this archive unchecked, so west is told
+`--no-gnu-toolchains` and this module does the job (see `tan.core.toolchain_pin`)."""
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import subprocess
+import tarfile
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from tan.core.proxy import select_https_proxy
+from tan.core.subprocess_env import spawn_env
+from tan.core.toolchain_provision import (
+    TMP_SUFFIX_PREFIX,
+    TOOLCHAIN_COMPONENT,
+    ToolchainArtifact,
+)
+
+#: The artifact row whose archive west's `setup.sh` would have fetched.
+TOOLCHAIN_ARTIFACT_COMPONENT = f"{TOOLCHAIN_COMPONENT}-toolchain"
+SEVEN_ZIP_EXTRACTORS = ("7z", "7za", "7zr", "7zz", "7zzs")
+_CHUNK = 1 << 20
+
+
+@dataclass(frozen=True)
+class FetchOutcome:
+    #: "ok" | "mismatch" (hash differs from the pin) | "unverified" (could not download)
+    #: | "install" (downloaded and matched, but could not be extracted/placed).
+    kind: str
+    message: str = ""
+
+
+def toolchain_artifact(artifacts: tuple[ToolchainArtifact, ...]) -> ToolchainArtifact | None:
+    found = [a for a in artifacts if a.component == TOOLCHAIN_ARTIFACT_COMPONENT]
+    return found[0] if len(found) == 1 else None
+
+
+def _download(url: str, dest: Path, art: ToolchainArtifact) -> FetchOutcome:
+    from tan.commands.sdk_cmd import (  # noqa: PLC0415
+        NETWORK_TIMEOUT_SECONDS,
+        _releases_opener,
+        _unroutable_proxy_refusal,
+    )
+
+    proxy = select_https_proxy(url)
+    refusal = _unroutable_proxy_refusal(proxy, url)
+    if refusal is not None:
+        return FetchOutcome("unverified", refusal)
+    import urllib.request  # noqa: PLC0415
+
+    request = urllib.request.Request(url, headers={"User-Agent": "tan-cli/0"})  # noqa: S310
+    digest = hashlib.sha256()
+    total = 0
+    try:
+        with _releases_opener(proxy).open(request, timeout=NETWORK_TIMEOUT_SECONDS) as resp:
+            with open(dest, "wb") as out:
+                while True:
+                    chunk = resp.read(_CHUNK)
+                    if not chunk:
+                        break
+                    total += len(chunk)
+                    if total > art.size_bytes:
+                        return FetchOutcome(
+                            "mismatch",
+                            f"{url} is larger than the {art.size_bytes} bytes alp-sdk pins "
+                            f"for {art.filename}",
+                        )
+                    digest.update(chunk)
+                    out.write(chunk)
+    except Exception as err:  # noqa: BLE001 -- every transport failure is a message
+        return FetchOutcome("unverified", f"{type(err).__name__}: {err}")
+    if total < art.size_bytes:
+        return FetchOutcome(
+            "unverified",
+            f"incomplete download: {total} of the pinned {art.size_bytes} bytes of "
+            f"{art.filename} arrived before the stream ended",
+        )
+    got = digest.hexdigest()
+    if got != art.sha256.strip().lower():
+        return FetchOutcome(
+            "mismatch",
+            f"{art.filename} downloaded from {url} has sha256 {got}, but alp-sdk pins "
+            f"{art.sha256} (a proxy rewriting the download gives the same symptom)",
+        )
+    return FetchOutcome("ok")
+
+
+def _find_seven_zip() -> str | None:
+    """Absolute path of the first 7-Zip on PATH that is not inside the current
+    directory. The bare name is never spawned: on Windows CreateProcess searches the
+    parent's cwd first, so a planted `7z.exe` in the project would run (cf. #1483)."""
+    from tan.core.tool_lookup import resolve_tool  # noqa: PLC0415
+
+    cwd = Path(os.getcwd()).resolve()
+    for name in SEVEN_ZIP_EXTRACTORS:
+        found = resolve_tool(name, os.environ).resolved
+        if found is None or not Path(found).is_absolute():
+            continue
+        real = Path(found).resolve()
+        if real == cwd or cwd in real.parents:
+            continue
+        return str(real)
+    return None
+
+
+def _extract(archive: Path, dest: Path) -> str | None:
+    """Error text, or None. `.tar.xz` via tarfile's `data` filter (no absolute paths,
+    no escapes, no device nodes); `.7z` via a 7-Zip binary (Windows' archive format)."""
+    dest.mkdir(parents=True, exist_ok=True)
+    try:
+        if archive.name.endswith(".7z"):
+            program = _find_seven_zip()
+            if program is None:
+                return "no usable 7-Zip on PATH to extract the .7z toolchain archive"
+            proc = subprocess.run(  # noqa: S603
+                [program, "x", "-y", f"-o{dest}", "--", str(archive)],
+                capture_output=True, text=True, check=False, env=spawn_env(),
+            )
+            return None if proc.returncode == 0 else f"{program} exited {proc.returncode}"
+        with tarfile.open(archive, "r:*") as tar:
+            tar.extractall(dest, filter="data")
+    except (OSError, tarfile.TarError, subprocess.SubprocessError) as err:
+        return f"{type(err).__name__}: {err}"
+    return None
+
+
+def install_pinned_toolchain(
+    base_url: str, art: ToolchainArtifact, tmp_dir: Path, scratch_parent: Path, leaf: str
+) -> FetchOutcome:
+    """Download + hash + extract `art` into `<tmp_dir>/gnu/` (the layout `setup.sh`
+    gives). The scratch dir is a swept `<leaf>.tmp-*` sibling, deleted on every path."""
+    url = base_url.rstrip("/") + "/" + art.filename
+    with tempfile.TemporaryDirectory(
+        dir=scratch_parent, prefix=f"{leaf}{TMP_SUFFIX_PREFIX}dl-"
+    ) as scratch:
+        archive = Path(scratch) / art.filename
+        got = _download(url, archive, art)
+        if got.kind != "ok":
+            return got
+        err = _extract(archive, tmp_dir / "gnu")
+        if err is not None:
+            return FetchOutcome("install", f"extracting {art.filename} failed: {err}")
+    if not (tmp_dir / "gnu" / TOOLCHAIN_COMPONENT).is_dir():
+        return FetchOutcome(
+            "install", f"{art.filename} did not extract a gnu/{TOOLCHAIN_COMPONENT} directory"
+        )
+    return FetchOutcome("ok")

tan/commands/bootstrap_toolchain_pin.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: Apache-2.0
+"""IO half of tan-cli#1496: fetch the release `sha256.sum` through the same
+proxy decision + OS-trust-store TLS context `tan sdk list --online` uses, then
+hand the text to `tan.core.toolchain_pin`. Only this small file is downloaded."""
+from __future__ import annotations
+
+from tan.core.proxy import select_https_proxy
+
+#: Cap on the sum file. The real one is ~100 KiB; anything bigger is not it.
+MAX_SUM_BYTES = 4 * 1024 * 1024
+
+
+def fetch_sum_text(url: str) -> tuple[str | None, str | None]:
+    """`(text, None)` or `(None, why)`. Never raises: every transport failure is a
+    message, so the caller always refuses visibly instead of passing silently."""
+    from tan.commands.sdk_cmd import (  # noqa: PLC0415
+        NETWORK_TIMEOUT_SECONDS,
+        _releases_opener,
+        _unroutable_proxy_refusal,
+    )
+
+    proxy = select_https_proxy(url)
+    refusal = _unroutable_proxy_refusal(proxy, url)
+    if refusal is not None:
+        return None, refusal
+    import urllib.request  # noqa: PLC0415
+
+    request = urllib.request.Request(url, headers={"User-Agent": "tan-cli/0"})  # noqa: S310
+    try:
+        with _releases_opener(proxy).open(request, timeout=NETWORK_TIMEOUT_SECONDS) as resp:
+            raw = resp.read(MAX_SUM_BYTES + 1)
+    except Exception as err:  # noqa: BLE001 -- see docstring
+        return None, f"{type(err).__name__}: {err}"
+    if len(raw) > MAX_SUM_BYTES:
+        return None, f"response exceeds {MAX_SUM_BYTES} bytes"
+    return raw.decode("utf-8", errors="replace"), None

tan/commands/build/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0

tan/commands/build/configure_inputs.py

@@ -0,0 +1,277 @@
+# SPDX-License-Identifier: Apache-2.0
+"""tan-cli#655: the file-existence side of Zephyr's own devicetree-overlay /
+Kconfig-fragment auto-discovery, tracked across `tan build` invocations so
+`execute.py` can tell when the discoverable SET changed (a new `app.overlay`
+appeared, an existing one was removed, a new `boards/<board>.conf` showed up)
+-- the one case Zephyr's own `CMAKE_CONFIGURE_DEPENDS` machinery does not
+self-heal, because `configuration_files.cmake` caches its auto-discovery
+result the first time it runs and only re-discovers `if(NOT DEFINED ...)`.
+See `execute._maybe_reset_stale_configure_cache` for the fix this supports
+and the measurement behind it.
+
+Existence-only, not content: an EDIT to an ALREADY-discovered file is already
+handled by Zephyr's own `CMAKE_CONFIGURE_DEPENDS` (the tracked file's mtime
+bump alone triggers a reconfigure) -- this module exists only for the set-
+membership change that mechanism cannot see."""
+from __future__ import annotations
+
+import os
+from pathlib import Path, PurePath
+
+from tan.core.shapes import is_file, matches_glob_suffix
+
+__all__ = [
+    "configure_inputs_stamp_path",
+    "discover_configure_inputs",
+    "read_configure_inputs_stamp",
+    "relative_key",
+    "resolve_zephyr_discovery_dir",
+    "write_configure_inputs_stamp",
+]
+
+#: Lives inside west's own nested build dir (mirrors `manifest.py`'s
+#: `_SDK_STAMP_FILE`/`sdk_stamp_path`), so a pristine wipe of that dir retires
+#: this stamp atomically along with the CMake cache it describes -- it can
+#: never outlive or misdescribe a build dir that no longer exists.
+_CONFIGURE_INPUTS_STAMP_FILE = ".tan-configure-inputs"
+
+
+def resolve_zephyr_discovery_dir(app_dir: str, build_root: Path) -> Path:
+    """Anchor a slice's plan-supplied `appDir` on `build_root`, then apply
+    Zephyr's own `app: ./src`-vs-self-contained convention, so a caller
+    working from the CONFIGURED app dir (`appDir` -- see
+    `tan.commands.build_cmd`'s "Note `appDir` is NOT the substituted value"
+    docstring) lands on the directory Zephyr actually auto-discovers
+    overlays/Kconfig fragments from -- the same one `west build` is pointed
+    at (tan-cli#798).
+
+    Anchoring mirrors both existing `appDir` probes,
+    `build_cmd._missing_app_dirs` and `build_cmd._substituted_app_dirs`: a
+    relative `appDir` resolves against `build_root`, never the `tan`
+    process's own CWD, so the result does not depend on where `tan` was
+    invoked from. The fallback mirrors `tan.planner.orchestrator`'s
+    `_zephyr_app_dir` (hash-audited, tan-cli#655's relocation gate -- not
+    importable here without reproducing its `_resolve_app_path` machinery
+    for a value, `appDir`, that is already resolved): when `app_dir` itself
+    carries no `CMakeLists.txt` but its parent does, Zephyr auto-discovers
+    from the parent instead (the shipped `app: ./src` sources-only
+    convention -- 96 of 105 alp-sdk example core entries use it). Neither
+    directory existing is reported as-is; the caller's own existence checks
+    (`discover_configure_inputs` returns the empty set for a missing dir)
+    already handle that case correctly without this function raising.
+
+    Unlike `build_cmd._substituted_app_dirs`, this does NOT carry an
+    `app_dir_path.is_dir()` precondition before falling back to the parent --
+    a nonexistent `app_dir` whose parent happens to carry a `CMakeLists.txt`
+    globs the parent here. Deliberately left unguarded: this function's only
+    caller runs on slices that already survived `_missing_app_dirs`
+    (`build.app-dir-missing` already failed a nonexistent `appDir` before
+    `execute_slices` dispatches it), so the divergence is unreachable in
+    practice, not merely tolerated."""
+    app_dir_path = Path(app_dir)
+    if not app_dir_path.is_absolute():
+        app_dir_path = build_root / app_dir_path
+    if (app_dir_path / "CMakeLists.txt").is_file():
+        return app_dir_path
+    if (app_dir_path.parent / "CMakeLists.txt").is_file():
+        return app_dir_path.parent
+    return app_dir_path
+
+
+#: The two auto-discovery families `cmake/modules/configuration_files.cmake`
+#: resolves `if(NOT DEFINED ...)`: Kconfig fragments (`CONF_FILE`, `NAMES
+#: "prj.conf"` at the app root plus `boards/`/`socs/` qualifiers) and
+#: devicetree overlays (`DTC_OVERLAY_FILE`, `NAMES "app.overlay"` plus the
+#: same `boards/`/`socs/` qualifiers). Not an attempt to reproduce Zephyr's
+#: exact per-qualifier candidate-name algorithm (board revision, `SUFFIX`,
+#: sysbuild image scoping -- all of which drift across Zephyr versions);
+#: tracking every `*.conf`/`*.overlay` at these locations is a superset that
+#: stays correct even when it over-tracks a file Zephyr itself would not have
+#: picked for THIS exact board target -- an extra reset is harmless, a missed
+#: one is the bug this module exists to close.
+_CANDIDATE_SUFFIXES = (".conf", ".overlay")
+
+#: The two qualifier subtrees, walked to ANY depth below themselves -- the
+#: `boards/**/*.conf` half of what this module used to express as six
+#: `Path.glob` patterns. `**` matched zero or more directories, so a file
+#: directly in `boards/` counted too; the walk below reproduces that by
+#: starting at the subtree root itself, not at its children.
+_CANDIDATE_SUBTREES = ("boards", "socs")
+
+# WHY `os.scandir` AND NOT `Path.glob` (tan-cli#1132, following tan-cli#1127's
+# identical swap in `new_som_cmd._known_board_names`).
+#
+# This module used to iterate `app_dir.glob(pattern)` OUTSIDE the `try` that
+# was supposed to guard it:
+#
+#     try:
+#         matches = app_dir.glob(pattern)   # lazy: builds a generator
+#     except OSError:
+#         continue
+#     for path in matches:                  # the filesystem work happens HERE
+#
+# `Path.glob` is lazy, so the guarded statement could not fail and the
+# `except OSError` was dead on every interpreter -- it wrapped the
+# construction of a generator. Forcing iteration inside the `try` would have
+# fixed the escape but not the contract, because `Path.glob` does not raise
+# uniformly. Measured on this tree, non-root, for the two denied shapes
+# (`app_dir` itself `chmod 000`, and `app_dir`'s PARENT `chmod 000`):
+#
+#   primitive                      self-denied            ancestor-denied
+#   Path.is_dir()                  True   / True  / True  RAISE / RAISE / False
+#   list(Path.glob("*.conf"))      []     / []    / []    RAISE / []    / []
+#   os.listdir() / os.scandir()    RAISE  / RAISE / RAISE RAISE / RAISE / RAISE
+#                                  (3.12.3 / 3.13.15 / 3.14.7)
+#
+# So `Path.glob` never raises at all for a self-denied directory, and raises
+# for a denied ancestor only on 3.12.3 -- an `except OSError` around it is
+# dead code on 3.13.15 and 3.14.7. `os.scandir` raises `PermissionError` for
+# both shapes on all three, which is what makes the single `except OSError`
+# in `discover_configure_inputs` load-bearing everywhere rather than on one
+# interpreter by accident. The `if not app_dir.is_dir()` pre-flight is gone
+# for the same reason (tan-cli#1127, and PR #1110/#1121 before it): it
+# raised `PermissionError` on 3.12.3/3.13.15 for a denied ancestor and
+# answered `False` on 3.14.7, so it could not be the thing that decides this
+# function's contract. The real exception classifies it now.
+
+
+def relative_key(path: PurePath, base: PurePath) -> str:
+    """@path relative to @base, spelled with forward slashes -- THE stamp
+    file's key, and the one expression `_candidate_files` uses to build one.
+
+    A separate function so the Windows spelling can be DRIVEN rather than
+    restated (tan-cli#1132 review): `os.scandir` hands back a
+    backslash-separated `entry.path` on Windows, so the key must be proven to
+    normalise. Taking `PurePath` (not `Path`) is what makes that provable on
+    ANY host without touching a filesystem, which is the point -- CI does run
+    this suite on `windows-latest` (`parity.yml`'s `python-tests-shard`, whose
+    matrix `os:` carries all three platforms; tan-cli#1153 corrects the "no
+    Windows host" claim that stood here), but only after a push, whereas a
+    pure-string oracle answers while the code is being written. A test passes
+    real `PureWindowsPath` values through THIS function, so a future edit here
+    (say, to `os.path.relpath`, which would leave backslashes in) reds the
+    oracle instead of sailing past a restatement of the old expression. The
+    keys are compared across runs, so a changed spelling would report every
+    tracked file as new on the first build after an upgrade."""
+    return path.relative_to(base).as_posix()
+
+
+def _candidate_files(directory: Path, base: Path, *, recurse: bool) -> set[str]:
+    """Relative-POSIX paths (to @base) of the regular files directly in
+    @directory -- and, when @recurse, at any depth below it -- whose name
+    matches `_CANDIDATE_SUFFIXES`.
+
+    Raises `OSError` (`PermissionError`, `FileNotFoundError`,
+    `NotADirectoryError`, ...) for any directory it cannot list; the single
+    caller classifies. See the block comment above for why that is
+    `os.scandir` and not `Path.glob`.
+
+    Three `Path.glob` behaviours this deliberately reproduces rather than
+    quietly improving on:
+
+    * A symlinked directory is NOT descended into -- `**` does not follow
+      symlinks on any supported interpreter (3.13's own
+      `recurse_symlinks=False` default), which is what
+      `entry.is_dir(follow_symlinks=False)` preserves.
+    * A name matching a candidate suffix that is a DIRECTORY is not a match,
+      the old code's `path.is_file()` filter.
+    * A per-entry stat failure SKIPS that entry rather than failing the
+      walk. That is why the file test is `shapes.is_file` and not
+      `entry.is_file()`: measured on 3.12.3, 3.13.15 and 3.14.7 alike, a
+      self-referential `loop.conf -> loop.conf` symlink makes
+      `os.DirEntry.is_file()` raise `OSError(ELOOP)` where `Path.is_file()`
+      -- what the `glob` version called -- returns `False` and keeps the
+      rest of the set. Only the DIRECTORY LISTING is allowed to fail the
+      walk, and `os.scandir` above is the call that does it.
+
+    Symlinks are otherwise followed for the file test, so a symlink TO a
+    fragment still counts, exactly as it did through `glob` + `is_file()`."""
+    found: set[str] = set()
+    pending = [directory]
+    while pending:
+        with os.scandir(pending.pop()) as entries:
+            for entry in entries:
+                if recurse and entry.is_dir(follow_symlinks=False):
+                    pending.append(Path(entry.path))
+                elif matches_glob_suffix(entry.name, *_CANDIDATE_SUFFIXES) and is_file(entry.path):
+                    found.add(relative_key(Path(entry.path), base))
+    return found
+
+
+def discover_configure_inputs(app_dir: Path) -> frozenset[str]:
+    """The set of configure-time Kconfig-fragment/devicetree-overlay paths
+    (relative POSIX, to `app_dir`) currently present under `app_dir` at one
+    of Zephyr's own auto-discovery locations. Returns the empty set for a
+    missing or unreadable `app_dir`, and for an unreadable `boards/`/`socs/`
+    subtree under it -- "nothing discoverable" is the same honest answer a
+    real Zephyr configure would reach, not an error this best-effort tracker
+    should raise.
+
+    An ABSENT `boards/`/`socs/` is the ordinary case, not a failure: it
+    contributes nothing and the app-root fragments still come back. That is
+    the inner handler's whole job, and it is why the outer one cannot simply
+    swallow every `OSError` from the whole walk."""
+    found: set[str] = set()
+    try:
+        found |= _candidate_files(app_dir, app_dir, recurse=False)
+        for subtree in _CANDIDATE_SUBTREES:
+            try:
+                found |= _candidate_files(app_dir / subtree, app_dir, recurse=True)
+            except (FileNotFoundError, NotADirectoryError):
+                continue
+    except OSError:
+        return frozenset()
+    return frozenset(found)
+
+
+def configure_inputs_stamp_path(slice_cwd: Path) -> Path:
+    """Path of the tan-owned configure-inputs stamp for one slice."""
+    return slice_cwd / "build" / _CONFIGURE_INPUTS_STAMP_FILE
+
+
+def read_configure_inputs_stamp(slice_cwd: Path) -> frozenset[str] | None:
+    """The configure-input file set recorded at the last stamp write, or
+    `None` for "never stamped", "unreadable", or "unreadable as UTF-8" --
+    all three read as "no signal", which the caller treats conservatively
+    (as a change, forcing one reset) rather than trusting a cache it cannot
+    actually verify. An empty stamped file (no candidate files at all) reads
+    back as the real empty set, `frozenset()`, not `None`."""
+    try:
+        text = configure_inputs_stamp_path(slice_cwd).read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+    return frozenset(line for line in text.splitlines() if line)
+
+
+def write_configure_inputs_stamp(slice_cwd: Path, inputs: frozenset[str]) -> None:
+    """Write the stamp BEFORE the tool is spawned (see the caller): a
+    mid-configure failure still stamped correctly, since the discoverable
+    set on disk really was what `inputs` records regardless of whether the
+    build finishes. One relative path per line, sorted for a stable diff.
+    Raises `OSError` on failure -- the caller treats the write as
+    best-effort (a write failure just means the next run may treat this dir
+    as unstamped: fails toward a spurious extra reset, never toward trusting
+    a stale cache)."""
+    path = configure_inputs_stamp_path(slice_cwd)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(sorted(inputs)) + ("\n" if inputs else ""), encoding="utf-8")
+
+
+def _user_defines_stamp_path(slice_cwd: Path) -> Path:
+    return slice_cwd / "build" / ".tan-user-defines"
+
+
+def read_user_defines_stamp(slice_cwd: Path) -> list[str] | None:
+    """The user `-D` key names of the last configure, or `None` if unstamped."""
+    try:
+        text = _user_defines_stamp_path(slice_cwd).read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+    return [line for line in text.splitlines() if line]
+
+
+def write_user_defines_stamp(slice_cwd: Path, keys: list[str]) -> None:
+    """Best-effort for the caller (raises `OSError`), like the inputs stamp."""
+    path = _user_defines_stamp_path(slice_cwd)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(sorted(keys)) + ("\n" if keys else ""), encoding="utf-8")