tan-cli 0.7.0__py3-none-any.whl

tan/core/atomic_write.py

@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: Apache-2.0
+"""A durable atomic-write helper (`atomic_write_text`, plus the byte-exact
+`atomic_write_bytes`) for a file more than one process or SDK checkout can
+share -- fsync'd before the rename, not just atomic-in-naming.
+
+tan-cli#516: `bootstrap_cmd.reconcile_west_manifest_path` wrote its temp
+sibling with `Path.write_text` and a bare `os.replace`, with no `os.fsync` on
+the temp before the rename and no directory `fsync` after it. `os.replace`'s
+atomicity guarantee covers the RENAME only -- it says nothing about whether
+the renamed-to content has actually reached stable storage. A crash between
+the rename landing and the temp's data blocks flushing can leave `.west/
+config` existing under its real name with truncated or missing content, on
+any filesystem that does not happen to order the two together: ext4's
+`auto_da_alloc` heuristic covers the common Linux case; XFS, btrfs, APFS,
+NTFS via `MoveFileExW`, and network filesystems generally do not.
+
+This is the SAME durability + symlink-safety + mode-preservation shape
+`debug_config_cmd._atomic_write_launch_json` carried (tan-cli#489, review
+findings 4+5) for the identical reason -- that function's own opening comment
+already called its shape "matching `bootstrap_cmd.reconcile_west_manifest_
+path`'s own pattern", so the two were always meant to agree; #516 is that
+agreement breaking (the fsync fix landed on one call site, not the other, and
+outlived it). Extracted here rather than re-copied inline a second time, so a
+future edit to the durability sequence itself cannot re-diverge between call
+sites the way it just did -- tan-cli#510 was exactly this failure mode: two
+independent copies of a resolver that drifted apart. `debug_config_cmd.py`'s
+own copy is gone as of the #516 review round -- `_write` now calls this
+function directly, rather than keeping a second, hand-synchronised
+implementation beside it -- so the docstring's promise and the code agree.
+
+**Mode preservation mirrors `_atomic_write_launch_json` exactly**, because
+this helper now serves BOTH call sites and one of them (`.vscode/
+launch.json`) genuinely needs it: a `664`-mode file a shared checkout
+convention set deliberately must not come back at `mkstemp`'s hardcoded
+`0600` merely because it was rewritten. `.west/config` -- this helper's other
+caller -- has no such convention to preserve, but reading a mode that already
+exists and reapplying it after the swap is a no-op cost for that caller, not
+a hazard, so one shape serves both rather than growing a caller-specific
+branch.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import tempfile
+
+
+def atomic_write_text(path: str, content: str, *, encoding: str = "utf-8") -> None:
+    """Write `content` to `path` atomically and durably. Raises on any
+    failure; the caller decides how to report it.
+
+    * **Symlink-safe.** `os.path.realpath` resolves the real target FIRST,
+      both for where the temp sibling is created (the same directory, and so
+      the same filesystem -- `os.replace` requires that for its atomicity
+      guarantee and fails outright with `EXDEV` without it) and for what
+      `os.replace` itself targets: writing the temp beside the UNresolved
+      `path` and replacing that would put a regular file where a symlink was,
+      destroying the link, while the real file silently stops being updated.
+    * **Durable, not just atomic-in-naming.** `os.fsync` on the temp file's
+      own descriptor, before the rename, gets the CONTENT onto stable
+      storage; a POSIX directory `fsync` after the rename covers the RENAME
+      ENTRY surviving a crash too (Windows has no directory handle to fsync,
+      and `ReplaceFile`/`MoveFileExW` already journal the rename itself).
+    * **Mode-preserving.** The existing file's permission bits (`stat.S_IMODE`,
+      read BEFORE the write) are re-applied to the real path AFTER a
+      successful `os.replace` -- never to the temp file itself, since
+      `os.replace` swaps the directory entry, not the inode's own mode bits,
+      and `mkstemp`'s hardcoded `0600` would otherwise silently narrow
+      whatever the file used to be. A first-ever write (no existing file to
+      read a mode from) gets `0666 & ~umask` instead of keeping `mkstemp`'s
+      `0600` forever, so it starts out at the ordinary default a plain
+      `open(path, "w")` would have produced.
+    * **Cleans up its own temp on failure** -- the caller never needs a
+      matching `unlink` in its own `except` block. This covers more than
+      `OSError`: an unencodable `content` under `encoding` raises
+      `UnicodeEncodeError` (a `ValueError`) from `handle.write`, and an
+      unknown `encoding=` raises `LookupError` from `os.fdopen` itself --
+      both happen strictly between `mkstemp` creating the temp and the
+      rename, so both must unlink it too, or it leaks into the caller's
+      directory un-unlinked.
+    """
+    # `content.encode(encoding)` raises `UnicodeEncodeError` (a `ValueError`)
+    # on unencodable content, or `LookupError` on an unknown `encoding=` --
+    # both used to surface later, from inside `os.fdopen`/`handle.write`,
+    # strictly between `mkstemp` creating the temp and the rename, which is
+    # why the old single-function version needed its own cleanup `except`
+    # for them. Encoding FIRST means either error now raises before any temp
+    # file exists at all, so there is nothing here left to clean up.
+    encoded = content.encode(encoding)
+    _atomic_write_bytes(path, encoded)
+
+
+def atomic_write_bytes(path: str, data: bytes) -> None:
+    """`atomic_write_text`'s byte-exact sibling -- same symlink-safety,
+    durability and mode-preservation, with no text encode/decode round trip
+    in between.
+
+    **The one caller that needs this over `atomic_write_text`
+    (`bootstrap_cmd._undo_relocation`'s registry rollback, review #904 third
+    round, nit) is restoring a BYTE snapshot taken before this run's own
+    write** (`_read_global_sdk_registry_bytes`), not producing fresh
+    content -- and that snapshot is not guaranteed UTF-8: this registry
+    tolerates a hand-edited or pre-this-fix file (`parse_registry`'s own
+    "never raises on malformed content" contract), so decoding it to `str`
+    and back through `atomic_write_text` could raise on exactly the
+    corrupted-but-was-there-before content a rollback exists to put back
+    unchanged. Restoring the literal bytes, atomically, is the only shape
+    that can't fail on its own input.
+    """
+    _atomic_write_bytes(path, data)
+
+
+def _atomic_write_bytes(path: str, data: bytes) -> None:
+    resolved = os.path.realpath(path)
+    directory = os.path.dirname(resolved)
+    existing_mode: int | None = None
+    try:
+        existing_mode = stat.S_IMODE(os.stat(resolved).st_mode)
+    except OSError:
+        pass
+    fd, tmp_path = tempfile.mkstemp(dir=directory, suffix=".tan-tmp")
+    try:
+        try:
+            handle = os.fdopen(fd, "wb")
+        except OSError:
+            # `fdopen` failing before a file object takes ownership of `fd`
+            # would otherwise leak the raw descriptor `mkstemp` opened.
+            # Best-effort: close if `fd` is still ours to close, ignore if
+            # not.
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+            raise
+        with handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_path, resolved)
+    except OSError:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+    if existing_mode is not None:
+        try:
+            os.chmod(resolved, existing_mode)
+        except OSError:
+            pass
+    else:
+        try:
+            # No race-free way to READ the process umask -- the standard
+            # idiom sets a harmless value and reads back the PREVIOUS one,
+            # then restores it immediately. `os.umask` is PROCESS-global, so
+            # this brief set-then-restore is safe only under tan's own
+            # single-threaded use of this helper; a second thread doing
+            # anything umask-sensitive inside this same window would observe
+            # -- or set -- the wrong value.
+            current_umask = os.umask(0o022)
+            os.umask(current_umask)
+            os.chmod(resolved, 0o666 & ~current_umask)
+        except OSError:
+            pass
+    if os.name != "nt":
+        try:
+            dir_fd = os.open(directory, os.O_RDONLY)
+            try:
+                os.fsync(dir_fd)
+            finally:
+                os.close(dir_fd)
+        except OSError:
+            # Best-effort insurance for the RENAME entry surviving a crash, on
+            # top of the file's own fsync above (which already protects the
+            # content): some filesystems/mounts (overlayfs, certain FUSE/NFS
+            # setups) refuse a bare directory fsync outright.
+            pass

tan/core/board_context.py

@@ -0,0 +1,351 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Where a project's `board.yaml` is, and the one fact `tan scaffold` reports
+out of it.
+
+Two halves of the same question, and both had a copy-per-command problem:
+
+* [`resolve_board_path`] is `validate_cmd._resolve_board_path`, MOVED here
+  rather than re-typed. `tan scaffold` needed exactly what `tan validate`
+  already does (tan-cli#1031), and this repo already carries SIX project/board
+  resolvers. A SEVENTH, written for `scaffold`, is precisely the drift
+  `tan.core.shapes`' own docstring is about; and it would be the same drift
+  alp-sdk-vscode#601/#633 had just finished deleting a second copy of THIS
+  generator to escape (the README's `## Wiring` section went missing on the
+  extension's side because a second copy existed at all). So the function
+  moved to a binding-free home both commands import.
+
+  **The criterion, stated so the next reader can CHECK the membership instead
+  of re-deriving it** -- this count has now been revised three times in a
+  docstring whose whole thesis is drift, which is its own argument for naming
+  the rule rather than the number. A member is a NAMED, REUSABLE function
+  under `python/tan/**` that turns the `--project`/`--board-yaml` pair into
+  the `board.yaml` path a command works from. Per-command inline joins do not
+  count; neither does anything under `tan/planner/**`, which resolves a board
+  DOCUMENT out of metadata rather than a path out of two flags. The six, with
+  the commands each serves:
+
+    tan/core/board_context.py:resolve_board_path      validate, scaffold
+    presets_cmd.py:resolve_project_paths              presets, pinmux, kconfig,
+                                                      diff, clean, bootstrap
+    build_output.py:resolve_project_context           size, image, model, west,
+                                                      debug-config
+    inspect_cmd.py:resolve_debug_project_context      inspect, trace,
+                                                      support-bundle
+    flash_cmd.py:_resolve_project                     flash
+    generate_cmd.py:_resolve_board_path               generate
+
+  FIVE of the six feed `tan.envelope.Project.resolved`, the reporting seam.
+  `generate_cmd._resolve_board_path` is the one that does not, deliberately:
+  `generate` reports the AS-GIVEN strings, built inline, because existence-
+  checking them against the real cwd is wrong the moment `--project` differs
+  from it (its own call site says so, citing tan-cli#236), and this resolver
+  answers only the path it READS. It is on the list anyway because it answers
+  the same question. A criterion of "uses `Project.resolved`" would have got
+  this exactly backwards on both ends: it would have EXCLUDED `generate_cmd`,
+  the one resolver that answers the question without the seam, while
+  ADMITTING a dozen things that are not resolvers at all -- measured at this
+  commit, there are 20 `Project.resolved(` call sites across 16 modules
+  (excluding the definition at `tan/envelope.py:222`), mostly command
+  callbacks doing an inline join. Hence the criterion above keys on what a
+  function DOES, not on which helper it happens to call.
+
+  Two earlier revisions of this paragraph were wrong in two different
+  directions -- one listed `generate_cmd`, the loosest match, while omitting
+  `inspect_cmd`, which does use the seam; the next inverted the reason above.
+  Three wrong revisions of one claim in a docstring whose subject is drift is
+  itself the argument for tan-cli#1091: prose does not hold a boundary, a
+  gate does.
+
+  The count did NOT go down: six before this change and six after, because
+  the sixth is validate's, relocated. Each is pinned to a different oracle's
+  reported shape, so they are distinct answers rather than duplicates, and
+  unifying them is not this change's job. What this change bought is that
+  `scaffold` did not make it seven.
+
+  **"One definition" here is now a gate, not prose (tan-cli#1091).**
+  `tests/gates/test_shared_helpers_have_one_definition.py` used to hard-assert
+  that every helper it owns lives in `tan/core/shapes.py`, reading its
+  ownership list out of that one file, so `resolve_board_path` could not join
+  it without generalising the gate from "shapes owns these" to a
+  `{name -> home module}` map. tan-cli#1091 did exactly that: the map is
+  `_SHARED_HELPERS` now, `resolve_board_path` is seeded in it pointed at this
+  module, and the per-helper assertion compares each entry against its OWN
+  declared home rather than a hard-coded `tan/core/shapes.py` literal. Its
+  sibling `tests/gates/test_shared_test_helpers_have_one_definition.py`
+  (tan-cli#1083) was already that shape and is what tan-cli#1091 copied.
+  NOT tan-cli#1081, which an earlier revision of this paragraph pointed at:
+  #1081's durable half already landed as #1083; the remainder of #1081's
+  scope (an outstanding `bound_sdk*` binder audit, tracked by PR #1102)
+  touches none of `TAN_ROOT`, `_SHARED_HELPERS`, or the per-entry home
+  assertion. A seventh private `_resolve_board_path` -- or a private
+  redefinition of this module's own --
+  now REDS `test_a_shared_helper_is_defined_exactly_once[resolve_board_path]`,
+  naming both files; this paragraph recorded the gap while it existed rather
+  than claiming it was already closed.
+
+* [`read_board_context`] is the content of the generated module's
+  `// Board context: ...` line. Its wire spelling -- `<sku> / <os>`, with
+  [`UNSET`] for a half the document does not declare -- is the retired
+  alp-sdk-vscode generator's, kept verbatim so a module scaffolded from the
+  extension and one scaffolded by `tan` carry the same bytes.
+
+**One spelling per envelope: the separator follows the ROOT** (tan-cli#1031,
+found by CI on `windows-latest`; this box is Linux and cannot reproduce it).
+[`resolve_board_path`] used to join the leaf with a hardcoded `/`, which is
+right only while the root is posix-spelled. Given `--project C:\\w\\proj`
+it answered the MIXED `C:\\w\\proj/board.yaml` while `project.root` stayed
+`C:\\w\\proj` -- one envelope carrying two spellings of one directory, and
+`C:\\w\\proj/board.yaml` is a spelling nothing contracts for and nobody
+asked for. `tan validate` had emitted it since long before `scaffold` existed;
+`scaffold`'s tests are simply the first to pass an absolute `--project`.
+
+The invariant every OTHER reporter of this pair already satisfies is
+`project.boardYaml == project.root + <sep> + <leaf>` -- asserted verbatim as
+`f"{root}/board.yaml"` by `test_build_command.py:1182`,
+`test_presets_command.py:702` and `test_inspect_command.py:163`. Those three
+read `/` because THEIR root is posix-normalised upstream
+(`build_output.to_posix`, `presets_cmd._posix`, `inspect_cmd._abs_posix`), NOT
+because the leaf is posix by contract. So the fix is to derive the separator
+from the root, not to posix the leaf.
+
+`root` itself is deliberately NOT normalised here: `validate` and `scaffold`
+report the string the caller TYPED (`generate` does the same), and re-spelling
+it would be a behaviour change to a shipped command that no defect asks for.
+A root with no separator at all (`"."`, `"proj"`, `"C:"`) keeps `/` on every
+platform, so `"./board.yaml"` -- what every committed conformance golden
+captures -- stays byte-identical across hosts. A root the caller spelled with
+BOTH separators is left alone, `/` winning, so the answer is never more mixed
+than the input.
+
+`"C:"` is the one separator-less root where declining `ntpath.join` is not
+merely a spelling difference but a DIFFERENT DIRECTORY, so it is called out
+rather than left implicit (measured): this rule answers `C:/board.yaml`, the
+root OF drive C:, while `ntpath.join("C:", "board.yaml")` answers
+`C:board.yaml`, the drive-RELATIVE path naming the cwd ON C:. The input is
+pathological -- `--project C:` is a drive letter, not a project -- and both
+answers are defensible for it, but the divergence is real and a reader
+checking this rule against the platform's own join deserves to meet it here
+instead of discovering it. `tests/core/test_board_context.py` pins both
+spellings.
+
+The choice reads the root STRING, never `os.sep`, so the Windows branch is
+fully exercised by a Linux run: `tests/core/test_board_context.py` drives it
+against `ntpath.join`/`posixpath.join` as oracles. The Windows behaviour here
+is therefore reasoned and unit-tested, not executed on Windows. Only
+`os.path.isabs` stays host-aware, which is correct -- whether `C:\\x\\y` is
+absolute genuinely IS a host question.
+
+**What a reported path does and does not promise.** `tan.envelope.Project.
+resolved` is the seam that turns a resolved path into `project.boardYaml`, and
+it gates on `os.path.exists`, which is true for a DIRECTORY -- so a directory
+named `board.yaml` reports a non-null path despite that method's own "only when
+a file is really there". Pre-existing, and shared with `tan validate` and `tan
+flash` (all three report through the same seam), so it is recorded here rather
+than fixed asymmetrically in one command. It costs this module nothing:
+[`read_board_context`] answers `unavailable` for that input either way, because
+reading a directory raises and lands on the file-failure arm
+(`test_a_directory_where_the_file_should_be_is_unavailable`).
+
+**`board.yaml` ONLY, no SDK -- deliberately.** `tan scaffold` resolves no
+alp-sdk checkout (its own module docstring says so, and one of tan-cli#1031's
+four reported invocations passes no `--sdk-root` at all), and this module does
+not change that. The consequence is stated rather than hidden: a v2
+`board.yaml` that omits `os:` genuinely does not carry one -- alp-sdk's
+`board.schema.json` says of `cores.<id>.os` that "The OS runtime is DERIVED
+from the core's silicon class and is not selectable... Omit `os:` to take that
+runtime", so the value then lives in the SoM preset, behind a checkout. That
+half renders [`UNSET`]; it is not guessed from the core id. Resolving it would
+mean walking `board.yaml -> som.sku -> metadata/e1m_modules/<sku>.yaml ->
+silicon -> metadata/socs/**.json -> cores[].type ->
+tan.core.os_class.default_os_from_core_type`, which would make a COMMENT's
+bytes depend on which checkout happened to be discovered on the machine that
+ran the scaffold. That is a bigger contract than a comment is worth; if it is
+wanted it is a separate, argued change.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+#: What a resolved `board.yaml` renders for a field it does not declare. The
+#: retired alp-sdk-vscode generator's own `?? "<unset>"` spelling
+#: (`packages/alp-core/src/wizard/service.ts`, deleted in alp-sdk-vscode#601).
+UNSET = "<unset>"
+
+#: A `cores.<id>.os` value that PARKS a core rather than naming a runtime, so
+#: it can never be the project's OS. Not a nicety: of the 100 example
+#: `board.yaml` files in alp-sdk v0.16.0 (tag `v0.16.0`, `eb96112ba` -- an
+#: earlier count of 99 here was measured off a stale `dev` working tree, not
+#: the tag it cited), 53 declare `os:` at all and 51 of those declare ONLY
+#: this -- reading the first declared value blindly would report `off` as the
+#: board context for most real projects. Zero of the 100 carry a top-level
+#: `os:`.
+#:
+#: The two that name a real runtime are the whole population this module can
+#: answer without an SDK, so they are named rather than counted:
+#: `examples/connectivity/modbus-server/board.yaml` (one core, `os: zephyr`)
+#: and `examples/power-timing/power-managed-sensor/board.yaml` (`os: "off"`
+#: on the parked HP core AND `os: zephyr` on the HE core -- the mixed shape
+#: this constant exists for, and the one `test_a_parked_core_is_not_a_runtime`
+#: pins). Every other example board renders the [`UNSET`] half.
+OS_OFF = "off"
+
+#: `cores.<id>.os` values that are declared but carry no runtime name. `""`
+#: is not schema-valid (the enum is `zephyr|yocto|baremetal|off`); it is
+#: rejected here anyway rather than being echoed into a C comment, since this
+#: input is a hand-edited customer file and nothing upstream of here has
+#: validated it.
+_NOT_A_RUNTIME = ("", OS_OFF)
+
+
+def resolve_board_path(project: str | None, board_yaml: str | None) -> tuple[str, str]:
+    """Return `(project_root, board_yaml_path)`, both as the CLI reports them.
+
+    Mirrors `resolve_offline_board_path`: the root defaults to the literal `"."`
+    and the board path stays RELATIVE, which the conformance fixtures pin
+    (`project.root == "."`, `boardYamlPath == "./board.yaml"`).
+
+    **`board_yaml` -- the `--board-yaml` flag -- WINS over the project-relative
+    default whenever it is given**: absolute, verbatim; relative, joined onto
+    the root. That is what its help text has always claimed ("Explicit
+    board.yaml path (overrides project resolution)") and what tan-cli#1031
+    found `tan scaffold` was not honouring, because `scaffold` never called a
+    resolver at all.
+
+    Existence is NOT checked here, and must not be: `validate`'s refusal
+    message names the path it could not open, so nulling it at the resolver
+    would strip the path out of the very message that names it.
+    `tan.envelope.Project.resolved` is the seam that checks -- its own
+    docstring documents that split.
+
+    The separator follows the ROOT's own spelling -- see "One spelling per
+    envelope" in the module docstring for why, and for what the alternatives
+    cost.
+    """
+    root = project if project else "."
+    if board_yaml and os.path.isabs(board_yaml):
+        return root, board_yaml
+    leaf = board_yaml or "board.yaml"
+    # Joined as STRINGS, not via pathlib: `Path(".") / "board.yaml"` normalises
+    # to `board.yaml`, but Rust's `Path::new(".").join("board.yaml")` keeps the
+    # `./`, and the conformance fixtures pin `"./board.yaml"`.
+    if root.endswith(("/", "\\")):
+        sep = ""
+    elif "\\" in root and "/" not in root:
+        sep = "\\"
+    else:
+        sep = "/"
+    return root, f"{root}{sep}{leaf}"
+
+
+def _board_mapping(board_yaml_path: str | None) -> dict[str, Any] | None:
+    """`board.yaml` parsed to a mapping, or `None` for EVERY way that can
+    fail -- no path at all, a missing file, a directory, an unreadable one, a
+    non-UTF-8 byte, malformed YAML, an empty document, a document that parses
+    to something other than a mapping, or PyYAML not installed.
+
+    **Never raises**, and that is the contract, not an implementation detail:
+    `tan scaffold`'s job is to write a module, and it must still write one
+    when the `board.yaml` beside it is broken. `unavailable` is what the
+    generated line is FOR.
+
+    The broad `except` is deliberate rather than lazy. `UnicodeDecodeError` is
+    a `ValueError`, NOT an `OSError`, so an `except OSError` alone could never
+    catch it -- one undecodable byte in a customer's own board.yaml escaped
+    `tan model` as a traceback for exactly that reason (tan-cli#396). Nothing
+    upstream of here has validated this file.
+
+    PyYAML is a DECLARED BASE dependency (`python/pyproject.toml`'s
+    `dependencies = [... "pyyaml>=6" ...]`, which
+    `tests/gates/test_declared_dependencies.py` enforces) -- an earlier version
+    of this note claimed "tan ships no YAML dependency of its own", which is
+    simply false. The `except ImportError` is still right, for the reason
+    `tan.core.system_manifest._import_yaml` gives for its own copy: a frozen
+    `tan` built from a stale venv. It answers "nothing resolved" rather than a
+    coded envelope only because this is a comment line, not a manifest read.
+    """
+    if not board_yaml_path:
+        return None
+    try:
+        import yaml  # noqa: PLC0415  (optional at runtime, by design)
+    except ImportError:
+        return None
+    # `Path(...)` is built OUTSIDE the `try` on purpose. The backstop below is
+    # for a BROKEN FILE; a `board_yaml_path` that is not path-like at all is a
+    # caller bug, and swallowing its `TypeError` here would report "no board
+    # context" for a defect in `tan`'s own code. It is also what makes the
+    # `if not board_yaml_path` guard above load-bearing rather than decorative:
+    # measured, with the try widened to cover this line, deleting that guard
+    # left `test_no_path_at_all_is_unavailable` GREEN, because `Path(None)`'s
+    # `TypeError` landed on the file-failure arm and answered `None` by
+    # accident (tan-cli#1031's own mutation run, mutant G3).
+    path = Path(board_yaml_path)
+    try:
+        document = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001 -- the customer's hand-edited file, not ours
+        return None
+    return document if isinstance(document, dict) else None
+
+
+def _declared_os(board: dict[str, Any]) -> str | None:
+    """The OS this `board.yaml` DECLARES, or `None` when it declares none.
+
+    Two shapes, because `board.yaml` has had two. A v1 document carries a
+    top-level `os:` -- the field the retired alp-sdk-vscode generator read
+    (`boardModel.os`) and the one that produced the
+    `// Board context: E1M-AEN801 / zephyr` line tan-cli#1031 asks for. A v2
+    document has no top-level `os` at all (alp-sdk's `board.schema.json`
+    declares no such property, and the extension's own `normalizeBoardModel`
+    deleted it on the way out: "v2: top-level os: has no meaning"); v2's home
+    for the field is `cores.<id>.os`, which the second arm reads.
+
+    Cores that DISAGREE collapse to `None` rather than picking one. A
+    heterogeneous project (`a55_cluster: yocto` + `m33_sm: zephyr`) has no
+    single OS, and a module scaffold is never told which core it is for
+    (`plan_module_files` receives the template definition and the name,
+    nothing else) -- so there is nothing to choose with.
+
+    `None` is also the honest answer for the common v2 project that declares
+    no `os:` anywhere; see the module docstring for why that is not resolved
+    from the SDK here.
+    """
+    top = board.get("os")
+    if isinstance(top, str) and top not in _NOT_A_RUNTIME:
+        return top
+    cores = board.get("cores")
+    if not isinstance(cores, dict):
+        return None
+    declared = {
+        entry["os"]
+        for entry in cores.values()
+        if isinstance(entry, dict)
+        and isinstance(entry.get("os"), str)
+        and entry["os"] not in _NOT_A_RUNTIME
+    }
+    return declared.pop() if len(declared) == 1 else None
+
+
+def read_board_context(board_yaml_path: str | None) -> str | None:
+    """`"<som.sku> / <os>"` for the generated `// Board context:` line, or
+    `None` when there is no board context to report -- the caller then keeps
+    the `unavailable` placeholder that line has always carried, now meaning
+    "genuinely none" rather than "never looked" (tan-cli#1031).
+
+    **`som.sku` is the gate, not a field that may go [`UNSET`].** It is the one
+    value alp-sdk's `board.schema.json` requires at the top level (`required:
+    [som, cores]`, and `som.required: [sku]`), so a document without a usable
+    one is not a board -- reporting `<unset> / <unset>` for it would dress a
+    broken file up as a resolved board, and `project.boardYaml` would still
+    name the file for anyone who wants to look. Every other half may be
+    `<unset>`; see [`_declared_os`].
+    """
+    board = _board_mapping(board_yaml_path)
+    if board is None:
+        return None
+    som = board.get("som")
+    sku = som.get("sku") if isinstance(som, dict) else None
+    if not isinstance(sku, str) or not sku:
+        return None
+    return f"{sku} / {_declared_os(board) or UNSET}"

tan/core/board_diagnostic.py

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Diagnostic data type + Rust-style renderer for the in-process board validator.
+
+PORTED from alp-sdk `scripts/alp_cli/diagnostic.py` (pinned by
+`tests/gates/test_planner_relocation_freshness.py::HAND_PORT_HASHES`).
+
+One deliberate departure: the SDK file takes its colour from `colorama`
+(`Fore.RED`, `Style.RESET_ALL`, ...), an undeclared optional dependency that
+`colorama.init()` additionally wraps `sys.stderr` with, stripping every escape
+when stderr is not a tty. tan declares neither, so the same three SGR
+sequences are spelled out here. The in-process engine always renders with
+`color=False` (`board_validator_run`): the bytes the SDK script's stderr carries
+under a pipe, which is the only way tan ever ran it.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+Severity = Literal["error", "warning", "note"]
+
+# colorama's Fore.RED / Fore.YELLOW / Fore.CYAN / Style.RESET_ALL.
+_RED = "\x1b[31m"
+_YELLOW = "\x1b[33m"
+_CYAN = "\x1b[36m"
+_RESET = "\x1b[0m"
+
+
+@dataclass(slots=True)
+class Diagnostic:
+    severity: Severity
+    path: Path
+    line: int
+    col: int
+    span: int
+    code: str
+    message: str
+    hint: str | None = None
+    doc_url: str | None = None
+
+
+def _doc_url(code: str) -> str:
+    base = os.environ.get("ALP_DIAG_BASE_URL", "docs/diagnostics")
+    return f"{base}/{code}.md"
+
+
+def _use_color(color: bool | None) -> bool:
+    if color is False:
+        return False
+    if color is True:
+        return True
+    if os.environ.get("NO_COLOR"):
+        return False
+    return sys.stdout.isatty()
+
+
+def render(diag: Diagnostic, source_text: str, color: bool | None = None) -> str:
+    """Render a diagnostic as a multi-line Rust-style block."""
+    use_color = _use_color(color)
+
+    def paint(s: str, hue: str) -> str:
+        return f"{hue}{s}{_RESET}" if use_color else s
+
+    sev_hue = {"error": _RED, "warning": _YELLOW, "note": _CYAN}[diag.severity]
+    header = f"{paint(f'{diag.severity}[{diag.code}]', sev_hue)}: {diag.message}"
+    arrow = f"  --> {diag.path}:{diag.line}:{diag.col}"
+
+    lines = source_text.splitlines()
+    if 1 <= diag.line <= len(lines):
+        src_line = lines[diag.line - 1]
+    else:
+        src_line = ""
+
+    gutter_w = max(2, len(str(diag.line)))
+    blank_gutter = " " * gutter_w
+    src_block = (
+        f"{blank_gutter} |\n"
+        f"{str(diag.line).rjust(gutter_w)} | {src_line}\n"
+        f"{blank_gutter} | {' ' * (diag.col - 1)}{paint('^' * max(1, diag.span), sev_hue)}"
+    )
+
+    tail: list[str] = []
+    if diag.hint:
+        tail.append(f"{blank_gutter} = hint: {diag.hint}")
+    tail.append(f"{blank_gutter} = see: {diag.doc_url or _doc_url(diag.code)}")
+
+    return "\n".join([header, arrow, src_block, *tail, ""])
+
+
+class DiagnosticCollector:
+    """Collect diagnostics across multiple validation passes."""
+
+    def __init__(self) -> None:
+        self._items: list[Diagnostic] = []
+
+    def add(self, diag: Diagnostic) -> None:
+        self._items.append(diag)
+
+    def __iter__(self) -> Iterator[Diagnostic]:
+        return iter(self._items)
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def has_errors(self) -> bool:
+        return any(d.severity == "error" for d in self._items)