tan-cli 0.7.0__py3-none-any.whl

tan/core/mram_link.py

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pure logic for Flow D's link-address guard (tan-cli#1371).
+
+An image destined for the app's MRAM slot must be LOADed at or above that slot. An
+ITCM-linked image (`p_paddr` 0x0) written there is the mistake this catches, and the
+manifest's `flash_method: ram_run_only` only stops it when the manifest is current --
+a hand-edited manifest, a build whose manifest write failed, or a direct backend call
+bypass it. It is the mirror of `flash.ram-image-not-ram-linked` (`tan.core.ram_run`).
+
+Only the program headers are read, with no IO: the symbol table (and its limits) is
+irrelevant to a load address and must neither skip nor refuse the check. `p_paddr` is
+the LOAD address; `p_vaddr` is where the image runs, and an image loaded into MRAM may
+legitimately run from ITCM.
+
+**Lower bound only.** An image is refused when it is loaded BELOW its slot, never for
+being above it. An image linked above its own slot -- say an M55-HP image at 0x802B0000
+written to the M55-HE slot 0x80010000 -- is NOT caught: that needs per-core slot windows
+this guard does not have. Equality with the slot is not required either, because an image
+header may offset the first segment."""
+from __future__ import annotations
+
+import struct
+
+#: Registered issue code (`contract/issue-codes.json`).
+CODE_NOT_MRAM_LINKED = "flash.mram-image-not-mram-linked"
+
+_ELF_HEADER_SIZE = 52
+_PHDR_SIZE = 32
+_PT_LOAD = 1
+
+
+class UnreadableElf(Exception):
+    """The program headers cannot be read; the message is the reason."""
+
+
+def lowest_load_paddr(data: bytes) -> int:
+    """The lowest `p_paddr` among LOAD segments with a nonzero `p_filesz` (never "the
+    first LOAD": a zero-FileSiz `.bss` in DTCM is often listed first). Raises
+    [`UnreadableElf`] for a 64-bit or big-endian file, a truncated header, a program
+    header table past the end of the file, or no such segment."""
+    if len(data) < _ELF_HEADER_SIZE:
+        raise UnreadableElf(f"truncated: {len(data)} B is shorter than an ELF32 header")
+    if data[4] != 1:
+        raise UnreadableElf("it is not an ELF32 file (only ELF32 images are supported)")
+    if data[5] != 1:
+        raise UnreadableElf("it is not little-endian (only little-endian images are supported)")
+    phoff = struct.unpack_from("<I", data, 28)[0]
+    phentsize, phnum = struct.unpack_from("<HH", data, 42)
+    if phnum and phentsize < _PHDR_SIZE:
+        raise UnreadableElf(f"its program header entry size is {phentsize} B (an Elf32_Phdr is 32)")
+    if phoff + phnum * phentsize > len(data):
+        raise UnreadableElf(
+            f"its {phnum} program headers at offset {phoff} run past the end of the file "
+            f"({len(data)} B)"
+        )
+    loadable = []
+    for i in range(phnum):
+        p_type, _off, _vaddr, p_paddr, p_filesz, _memsz = struct.unpack_from(
+            "<IIIIII", data, phoff + i * phentsize
+        )
+        if p_type == _PT_LOAD and p_filesz:
+            loadable.append(p_paddr)
+    if not loadable:
+        raise UnreadableElf("it has no LOAD segment with file content")
+    return min(loadable)
+
+
+def mram_link_refusal(data: bytes, floor: int, floor_name: str) -> str | None:
+    """A refusal message when the ELF in `data` is not loaded at or above `floor`, else
+    `None`. `floor` is the entry's `slot0_load_address`;
+    `floor_name` names it for the message. An ELF whose program headers cannot be
+    read is REFUSED, never waved through: the guard exists for the image nothing else
+    caught. Equality is not required -- an image header may offset the first segment."""
+    try:
+        lowest = lowest_load_paddr(data)
+    except UnreadableElf as err:
+        return (
+            f"the artefact's ELF could not be parsed ({err}), so its load address cannot be "
+            "verified against the MRAM slot -- refusing to write an unchecked image."
+        )
+    if lowest >= floor:
+        return None
+    return (
+        f"the image's lowest LOAD segment (p_paddr) is at 0x{lowest:X}, below {floor_name} "
+        f"0x{floor:X}: it is not linked for that MRAM slot (an ITCM/RAM-linked build). "
+        "Rebuild it MRAM-linked, or RAM-run it with `tan flash --ram` (Flow C)."
+    )

tan/core/new_som_ospi.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`ospi_memories:`/`hyperram:` `on_module:` scaffold lines for `tan new-som`
+(tan-cli#1220).
+
+Split into its own module rather than grown inside `new_som_cmd.py`: that
+file already sits at its `tests/gates/module_size_budget.d/` ceiling
+(`MODULE_CAP`), and PR #1222 set the precedent for this exact situation --
+`model_cmd.py` at its own ceiling got a new `tan/core/model_list.py` for the
+actual engine, keeping the command file's own growth to dispatch/glue. This
+module is the `_render_preset` sibling: pure string rendering, no IO, no
+click/typer.
+
+Scoped to Alif Ensemble parts only. The caller (`_render_preset`) already
+splits every `soc_ref` into `vendor_slug, family_slug, part_slug` for its own
+`metadata/socs/...` path -- `is_alif_ensemble` reads that SAME triple rather
+than adding a second vendor/family discrimination mechanism (tan-cli#1220's
+own instruction: reuse how `new_som_cmd.py` already tells vendors/families
+apart, don't invent a new one). The scope itself is not arbitrary: the
+schema's own `on_module.ospi_memories` description reads "(AEN family)"
+(`metadata/schemas/som-preset-v2.schema.json`), and every shipped
+`E1M-AEN*.yaml` preset that populates these fields (301/401/501/601/701/801)
+uses the identical CS0=NOR/CS1=HyperRAM split on one shared octal OSPI0
+controller.
+
+Every value below is either that shared Ensemble-silicon convention
+(`chip_select`, `interface`) or an explicit placeholder -- never an invented
+MPN or capacity (ADR-0017, invariant I-26). Two of the schema's fields have
+no `"TBD"` string escape hatch the way `chip`/`capacity_mbit` do:
+`chip_select` is a bare `"type": "integer"` (no `oneOf` alternative), and
+`role`/`interface` must match a lowercase-slug pattern (`^[a-z][a-z0-9_]*$`,
+which an uppercase `TBD` fails). The convention value fills `chip_select`/
+`interface`; the schema-legal lowercase literal `tbd` fills `role`, matching
+`inference.auto_order`'s own `[tbd]` placeholder convention next door in
+`_render_preset`.
+
+`chip_select`'s only bound in `metadata/schemas/som-preset-v2.schema.json` is
+`"minimum": 0` -- there is no schema maximum, and no `scripts/check_*.py`
+gate in the pinned alp-sdk checkout mentions `chip_select` at all (measured:
+`grep -rn chip_select scripts/` finds nothing). "Bounded to 0 or 1" is a
+description of the real OSPI0 controller's two physical chip-selects, not an
+enforced ceiling; nothing stops a preset from declaring `chip_select: 2` and
+still passing every automated check in this checkout.
+
+`assembled:` (optional on both `$defs`, and also has no `"TBD"` variant) is
+left out of the rendered block entirely -- the schema's own default when
+omitted is `true` (populated), which this scaffold has no basis to assert OR
+deny for a module whose BOM does not exist yet. Matches how `_render_preset`
+already treats every other schema-optional block it cannot safely guess
+(`capabilities:`, `pad_routes:`, `helper_firmware:`): a comment, not a
+guessed value.
+"""
+from __future__ import annotations
+
+#: The one (vendor, family) pair `ospi_memories:`/`hyperram:` are scoped to
+#: -- see the module docstring for why.
+_ALIF_ENSEMBLE = ("alif", "ensemble")
+
+
+def is_alif_ensemble(vendor_slug: str, family_slug: str) -> bool:
+    """True when a `soc_ref`'s parsed `vendor_slug`/`family_slug` name an
+    Alif Ensemble part -- the one scope `render_ospi_memories_and_hyperram`
+    is meant to be called under."""
+    return (vendor_slug, family_slug) == _ALIF_ENSEMBLE
+
+
+def render_ospi_memories_and_hyperram() -> list[str]:
+    """The `ospi_memories:`/`hyperram:` `on_module:` sub-block, as 2-space-
+    indented lines ready to append inside `_render_preset`'s `on_module:`
+    section (append after `eeprom:`, before the `i2c_devices:` comment
+    block -- the same relative order every shipped `E1M-AEN*.yaml` preset
+    that carries both keys uses). See the module docstring for what each
+    field's placeholder is and why.
+    """
+    lines: list[str] = []
+    a = lines.append
+    a("  # OSPI0 dual-chip-select external memory (Ensemble-family")
+    a("  # convention): NOR flash on CS0, HyperRAM on CS1, sharing one")
+    a("  # shared octal bus.  Delete the whole ospi_memories:/hyperram:")
+    a("  # pair if this module populates neither; add an ospi1: row")
+    a("  # alongside ospi0: for a second, independent OSPI controller.")
+    a("  ospi_memories:")
+    a("    ospi0:")
+    a("      chip:           TBD   # storage-part MPN (datasheet/BOM), or TBD")
+    a("      capacity_mbit:  TBD   # Mbit, from the storage-part datasheet")
+    a("      chip_select:    0     # OSPI0 CS0 (Ensemble-family convention)")
+    a("      role:           tbd   # what it's for, e.g. app_storage")
+    a("  # HyperRAM sharing the OSPI0 octal bus with the flash above,")
+    a("  # separated only by chip-select -- delete if not populated.")
+    a("  hyperram:")
+    a("    chip:           TBD     # HyperRAM MPN (datasheet/BOM), or TBD")
+    a("    capacity_mbit:  TBD     # Mbit, from the HyperRAM datasheet")
+    a("    interface:      ospi0   # controller instance (Ensemble convention)")
+    a("    chip_select:    1       # OSPI0 CS1 (Ensemble-family convention)")
+    return lines

tan/core/os_class.py

@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The Cortex-A/Cortex-M -> OS convention (issue #95), free of `tan.planner`'s
+binding requirement.
+
+`tan.planner.topology` owns the AUTHORITATIVE version of this rule --
+`_default_os_from_core_type` there is what `validate._enforce_os_matches_core_class`
+gates a real build on, and it re-exports the same names this module defines so
+every existing planner caller/test is unaffected by this file's existence
+(`tan.planner.topology._default_os_from_core_type` and `.CLASS_RUNTIMES` are
+now this module's `default_os_from_core_type`/`CLASS_RUNTIMES`, imported not
+redefined).
+
+**Why this lives OUTSIDE `tan.planner` (tan-cli#870).** `tan.planner` is a
+process-global-bound package: importing ANY of its submodules requires
+`tan.planner_root.bind_sdk_root(<checkout>)` to have already run, because
+`tan/planner/__init__.py` -> `tan/planner/paths.py` reads `sdk_root()` at
+IMPORT time and the binding is refuse-to-rebind for the rest of the process
+(`tan/planner_root.py`'s own docstring). That is the right contract for `tan
+build`'s single big planning pass per process. It is the WRONG contract for
+`tan presets`, which is exercised by dozens of small, independent unit tests
+in the SAME pytest process, each against its own disposable synthetic SDK
+root: the first such test to reach a `tan.planner` import permanently binds
+the whole worker process to ITS throwaway root, and every later test in that
+worker that needs a DIFFERENT (often the real, `ALP_SDK_ROOT`-derived) root
+then fails outright -- measured while building tan-cli#870: routing
+`presets_cmd`'s SoC-type/`allowed_os` lookups through `tan.planner.topology`
+turned a clean local bound suite run (5 failed, 0 errors, the 5 pre-existing
+terminal-width/breadth-layer artefacts) into 292 `PlannerRootError` cascades
+across `tests/parity/test_planner_emit_parity.py`, in a completely unrelated
+file, purely from `tests/commands/test_presets_command.py`'s own throwaway
+fixtures winning the race to bind first in their xdist worker.
+
+So the RULE (this file) lives somewhere binding-free, and both consumers
+import it: `tan.planner.topology` for the planner's own enforcement (still
+combined there with `_core_os_choices`'s bound-tree schema fallback, which a
+real build-time metadata root may legitimately need), and
+`tan.commands.presets_cmd` for the wizard's `allowedOs` (combined there with a
+plain, no-fallback read of the GIVEN checkout's own `board.schema.json` --
+`presets` never has a "different bound tree" to fall back to; it is reading
+exactly one checkout throughout). Neither consumer re-derives the convention;
+both call this module.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+#: The two class-determined OS runtimes (issue #95): Cortex-A -> Yocto
+#: (Linux), Cortex-M -> Zephyr (RTOS). These follow the core class and are NOT
+#: user-selectable (see `default_os_from_core_type`); `baremetal` (no-OS) and
+#: `off` (disabled) are the only values a board.yaml may set explicitly.
+CLASS_RUNTIMES = ("yocto", "zephyr")
+
+
+def default_os_from_core_type(core_type: str) -> str:
+    """Infer default OS from a SoC's `cores[].type`.
+
+    Convention (codified across the SoM presets pre-2026-05-18):
+        cortex-a*  ->  yocto
+        cortex-m*  ->  zephyr
+        anything else ->  off
+
+    Used as the fallback when a SoM preset's `topology.<core>.os` is
+    omitted (the field is optional in som-preset-v2.schema.json -- M-class
+    cores default to Zephyr, A-class to Yocto).
+
+    *core_type* is typed `str` but this is the SHARED entry point both
+    binding-free callers (`presets_cmd.allowed_os_lookup`) and the planner
+    (`topology._default_os_from_core_type`) reach with a value read off a
+    SoC JSON that a schema-invalid `--sdk-root`/`--metadata-root` tree makes
+    no promise about (tan-cli#957) -- `isinstance` here, not `str`-only trust
+    in the annotation, is the backstop for every caller, present or future,
+    that forwards a `cores[].type` value without its OWN guard. A non-string
+    normalises to the same `""` unresolved sentinel a genuinely absent
+    `type` already produces, rather than raising `AttributeError` on
+    `.lower()`.
+    """
+    t = core_type.lower() if isinstance(core_type, str) else ""
+    if t.startswith("cortex-a"):
+        return "yocto"
+    if t.startswith("cortex-m"):
+        return "zephyr"
+    return "off"
+
+
+def cross_class_os(core_type: str) -> set[str]:
+    """The class runtime a core may NOT be set to -- the OS of the *other*
+    class. A Cortex-A can't run Zephyr; a Cortex-M can't run Yocto."""
+    return set(CLASS_RUNTIMES) - {default_os_from_core_type(core_type)}
+
+
+def allowed_os_for_core(core_type: str, choices: Iterable[str]) -> list[str]:
+    """The `os:` values valid for a core: *choices* (the checkout's own `os:`
+    enum) minus the cross-class OS -- e.g. Cortex-A -> `[yocto, baremetal,
+    off]`, Cortex-M -> `[zephyr, baremetal, off]`.
+
+    `core_type == ""` is the shared UNRESOLVED sentinel both callers of this
+    function use when a core's `type` could not be determined (no matching
+    SoC JSON on disk, no entry for this core id in it, a synthetic/partial
+    checkout, ...) -- `tan.planner.topology.core_os_topology`'s
+    `soc_types.get(core_id, "")` and `tan.commands.presets_cmd.read_soms`'s
+    `core_types.get(c.id, "")` both feed it here unchanged. Degrades to `[]`
+    rather than the plausible-but-wrong cross-class subtraction `cross_class_os("")`
+    would otherwise produce (tan-cli#914): `default_os_from_core_type("")`
+    falls through to `"off"`, so an UNRESOLVED type and a genuinely
+    off-class core type were indistinguishable at this call, and the
+    unresolved case silently offered Bare-metal for what may be a Cortex-M
+    core -- the exact defect #870 exists to close, reproduced by the very
+    field meant to prevent it. An unresolved type gets an unresolved (empty)
+    answer instead, for both the wizard's `presets_cmd.allowed_os_lookup` and
+    the build-time `topology._allowed_os_for_core` -- the one call this
+    module exists to share, so the two can never drift back apart on this.
+
+    A non-string *core_type* is ALSO treated as unresolved (tan-cli#957),
+    not just falsy ones: `default_os_from_core_type`'s own `isinstance`
+    guard already stops a truthy non-string (`7`, a populated list, `True`,
+    ...) from raising here, but without this function's OWN `isinstance`
+    check that value would still reach `cross_class_os` truthy, fall through
+    `default_os_from_core_type`'s `"off"` default the same way `""` does,
+    and hand back the identical `["baremetal", "off"]` plausible-but-wrong
+    guess this docstring already rejects for the empty-string case --
+    the crash-vs-leak choice tan-cli#957 found in `core_type_lookup` shows
+    up here too, one level in, if this guard is skipped: a caller's own
+    `isinstance` at its read site is not something this shared function may
+    assume every present or future caller remembered to add.
+    """
+    if not isinstance(core_type, str) or not core_type:
+        return []
+    cross = cross_class_os(core_type)
+    return [o for o in choices if o not in cross]
+
+
+def infer_runtime_for_core_id(core_id: str) -> str:
+    """Best-effort runtime for a core id with no OS given: an `a` followed by
+    a digit at a WORD start (`a55_cluster`, `cluster_a32`, `A55`) runs
+    `yocto`; everything else defaults to `zephyr`.
+
+    Word starts are the string start and any position after `_`/`-`, so
+    `data55` is NOT Cortex-A. Mirrors
+    `tan_core::wizard::infer_runtime_for_core_id`, and KEEP IN SYNC with
+    alp-sdk-vscode's ConfiguratorView `coreSiliconClass` (same word-start
+    test; the one intentional difference is the fallback, since a CLI must
+    pick a concrete runtime where the IDE can offer "unknown").
+
+    A last resort: a topology that declares `board:`/`machine:` never reaches
+    it. Lives here rather than beside either caller because it had TWO
+    definitions -- `tan/core/scaffold.py` and `tan/commands/presets_cmd.py` --
+    and `tan/core/bootstrap.py` reached OUTWARD past the core one to import
+    the command's copy (tan-cli#408). One owner, in the leaf module that
+    already answers "what OS class is this core", is what the duplicated
+    docstrings each said they wanted.
+    """
+    lowered = core_id.lower()
+    word_start = True
+    for i, ch in enumerate(lowered):
+        if word_start and ch == "a" and i + 1 < len(lowered) and lowered[i + 1].isdigit():
+            return "yocto"
+        word_start = ch in "_-"
+    return "zephyr"

tan/core/patch_paths.py

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Repo-relative paths a unified diff / `git format-patch` file touches.
+
+Pure text in, paths out (tan-cli#1384). Used to fingerprint the working-tree
+files alp-sdk's `zephyr/patches/` write, so the set must include every path a
+patch can change on disk, not only the ones with a `+++ b/` line:
+
+* `diff --git a/<old> b/<new>` names BOTH sides, which is the only place a pure
+  rename, a mode-only change or a binary patch is visible (none of them carry
+  `---`/`+++` lines);
+* `--- a/<path>` names a file the patch deletes (`+++ /dev/null`);
+* `+++ b/<path>` names a file it writes (`--- /dev/null` when it creates it).
+
+`---`/`+++` count only as headers, never as hunk content: after a
+`diff --git` line and before the first `@@`, or (for a plain `diff -u` with no
+`diff --git` line) as a `---`, `+++`, `@@` triple.
+"""
+from __future__ import annotations
+
+import re
+
+_TOKEN = re.compile(r'"(?:[^"\\]|\\.)*"|\S+')
+
+
+def _unquote(raw: str) -> str:
+    """Undo git's C-style quoting (`"a/caf\\303\\251"`); plain paths pass through."""
+    raw = raw.strip()
+    if len(raw) >= 2 and raw[0] == raw[-1] == '"':
+        try:
+            return (
+                raw[1:-1].encode("utf-8").decode("unicode_escape")
+                .encode("latin-1").decode("utf-8", "replace")
+            )
+        except (UnicodeError, ValueError):
+            return raw[1:-1]
+    return raw
+
+
+def _side(raw: str, prefix: str) -> str | None:
+    """The path on one side of a header, or `None` (`/dev/null`, no prefix)."""
+    path = _unquote(raw.split("\t", 1)[0]).strip()
+    if path == "/dev/null" or not path.startswith(prefix):
+        return None
+    return path[len(prefix):] or None
+
+
+def _git_header(rest: str) -> list[str]:
+    """Both paths of `diff --git a/<old> b/<new>` (the text after `diff --git `)."""
+    if '"' in rest:
+        tokens = _TOKEN.findall(rest)
+        if len(tokens) == 2:
+            return [p for p in (_side(tokens[0], "a/"), _side(tokens[1], "b/")) if p]
+    half = (len(rest) - 1) // 2
+    if len(rest) % 2 == 1 and rest[:half].startswith("a/") and rest[half] == " " \
+            and rest[half + 1:] == "b/" + rest[:half][2:]:
+        return [rest[:half][2:]]  # unrenamed: both sides are the same path
+    old, sep, new = rest.partition(" b/")
+    return [p for p in (_side(old, "a/"), new if sep else None) if p]
+
+
+def patch_paths(text: str) -> set[str]:
+    """Every repo-relative path `text` (one patch file) touches."""
+    lines = text.splitlines()
+    paths: set[str] = set()
+    in_header = False
+    for i, ln in enumerate(lines):
+        if ln.startswith("diff --git "):
+            in_header = True
+            paths.update(_git_header(ln[len("diff --git "):]))
+        elif ln.startswith("@@"):
+            in_header = False
+        elif ln.startswith(("--- ", "+++ ")):
+            plain_triple = (
+                ln.startswith("--- ")
+                and i + 2 < len(lines)
+                and lines[i + 1].startswith("+++ ")
+                and lines[i + 2].startswith("@@")
+            )
+            if in_header or plain_triple:
+                side = _side(ln[4:], "a/" if ln[0] == "-" else "b/")
+                if side:
+                    paths.add(side)
+                if plain_triple:
+                    plus = _side(lines[i + 1][4:], "b/")
+                    if plus:
+                        paths.add(plus)
+    return paths

tan/core/pending.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The one definition of alp-sdk's `TBD` pending-placeholder sentinel (#276).
+
+alp-sdk writes the literal string `TBD` into a manifest/preset field it has
+not filled in yet -- `flash_args: TBD`, `silicon_variant: TBD`, an unfilled
+`e1m_pad` -- a deliberate "don't invent a value" convention, not an error.
+Every reader of that convention has to agree on what "unfilled" means, so the
+rule lives here ONCE rather than being re-typed at each read site.
+
+This module is deliberately the neutral one: it has no flash-planning
+machinery (`tan.core.flash_plan`) and no image-bundle machinery
+(`tan.core.image_bundle`) behind it, so a consumer that is neither -- `tan.core.size`,
+and `pinmux` once it is ported -- can test for the sentinel without pulling
+either domain in. `flash_plan` still owns the flash-specific decisions built
+on top (`flash_args_has_tbd`'s mapping/sequence recursion, the skip-vs-fail
+split between `flash_args` and an artefact path); only the base comparison
+moved here.
+
+Trimmed before comparing -- a YAML `device: "  TBD  "` is the same unfilled
+field -- but deliberately NOT case-folded and NOT a substring test:
+`TBD-1234-XYZ` is a plausible part number and `flash_args.build_dir:
+/opt/TBDtool/x` a plausible path, and refusing either would block a
+legitimate value. `tbd` lowercase is not the sentinel alp-sdk emits; widening
+to it means widening the SDK's convention first, in one place, not here.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+#: alp-sdk's unfilled-field sentinel.
+PENDING_PLACEHOLDER = "TBD"
+
+
+def is_pending_placeholder(value: Any) -> bool:
+    """Whether a manifest/preset SCALAR is the SDK's unfilled-field sentinel.
+
+    `None` and every non-string value are never pending; a string is pending
+    only when it is exactly `PENDING_PLACEHOLDER` after trimming surrounding
+    whitespace."""
+    return isinstance(value, str) and value.strip() == PENDING_PLACEHOLDER

tan/core/plain_zephyr_plan.py

@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: Apache-2.0
+"""A single-slice build plan for a `board.yaml`-less Zephyr example (tan-cli#1359).
+
+alp-sdk's bench-style examples (`examples/aen/aen-inference-latency`, ...) are
+plain Zephyr apps built per board target and ship no `board.yaml`, so the
+planner has nothing to read. `tan build --project <dir> --board <target>`
+synthesises the plan the planner WOULD have emitted for one Zephyr slice and
+feeds it through the ordinary `tan build` pipeline -- the same token
+substitution, host-Python resolver (#1326), toolchain / west-workspace
+resolution, dispatch, pristine policy and envelope as a planned build. Nothing
+here spawns or resolves anything; it only shapes data.
+
+The slice mirrors a planner Zephyr slice: `west build -b <board> <app> --`
+run with cwd `build/<core>-zephyr` (so west's own `build/` lands under it and
+`--pristine`'s wipe guards still apply -- an explicit `-d` would disable them).
+"""
+from __future__ import annotations
+
+import json
+import re
+
+from tan.core.plan_tokens import TOKEN_PYTHON, TOKEN_SDK_ROOT
+
+#: A Zephyr board target: `<board>[@rev][/<soc>[/<cpucluster>[/<variant>]]]`.
+_BOARD_TARGET = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_.@-]*(/[A-Za-z0-9_.-]+){0,3}")
+#: `-DNAME=value` / `-DNAME:TYPE=value` / `-DNAME`.
+_DEFINE = re.compile(r"-D[A-Za-z_][A-Za-z0-9_]*(:[A-Za-z]+)?(=.*)?", re.DOTALL)
+
+
+def board_target_problem(board: str) -> str | None:
+    if not _BOARD_TARGET.fullmatch(board):
+        return (
+            f"`--board {board}` is not a Zephyr board target "
+            "(e.g. `alp_e1m_aen803_m55_he/ae822fa0e5597ls0/rtss_he`)"
+        )
+    return None
+
+
+def normalise_defines(defines: list[str]) -> tuple[list[str], str | None]:
+    """`-D` values as CMake args: `FOO=1` and `-DFOO=1` both become `-DFOO=1`."""
+    out: list[str] = []
+    for raw in defines:
+        item = raw if raw.startswith("-D") else f"-D{raw}"
+        if "${" in item:
+            # Plan token substitution would expand (or choke on) it.
+            return [], f"`-D {raw}` contains `${{`, which tan reserves for build-plan tokens"
+        if not _DEFINE.fullmatch(item):
+            return [], f"`-D {raw}` is not a CMake definition (`NAME=VALUE`)"
+        out.append(item)
+    return out, None
+
+
+def core_id_for(board: str) -> str:
+    """The slice's id: the board target's core part, else its board name."""
+    parts = board.split("/")
+    name = parts[2] if len(parts) >= 3 else parts[0]
+    return re.sub(r"[^A-Za-z0-9_]+", "_", name).strip("_").lower() or "app"
+
+
+#: `generatedBy` of a synthesised plan: how the post-build manifest write
+#: recognises the plain route (tan-cli#1370).
+PLAIN_GENERATED_BY = "tan build --board"
+
+
+def plain_route_target(plan) -> tuple[str, str] | None:
+    """`(board target, core id)` of a plan [`plain_zephyr_plan`] synthesised."""
+    if plan.generated_by != PLAIN_GENERATED_BY or len(plan.slices) != 1:
+        return None
+    (sl,) = plan.slices
+    args = sl.command.args if sl.command else []
+    if "-b" not in args or args.index("-b") + 1 >= len(args):
+        return None
+    return args[args.index("-b") + 1], sl.core_id
+
+
+def plain_zephyr_plan(
+    app_dir: str, board: str, defines: list[str], core_id: str | None = None
+) -> str:
+    """The build-plan JSON text for one Zephyr slice building `app_dir`.
+
+    `core_id` is the planner core id the board target maps to (`m55_he` for
+    `.../rtss_he`); without it the slice is named for the board qualifier."""
+    core = core_id or core_id_for(board)
+    slice_dir = f"build/{core}-zephyr"
+    out = f"{slice_dir}/build"
+    plan = {
+        "schemaVersion": 1,
+        "planPathMode": "tokened",
+        "generatedBy": PLAIN_GENERATED_BY,
+        "boardYaml": "",
+        "sku": "",
+        "buildRoot": "build",
+        "executionPolicy": {"unknownBackend": "fail", "missingTool": "skip", "nullCommand": "skip"},
+        "slices": [
+            {
+                "coreId": core,
+                "backend": "zephyr",
+                "buildDir": slice_dir,
+                "appDir": app_dir,
+                "configArtefacts": [],
+                # `toolchain` / `debug` below are required plan fields; no consumer
+                # of this synthesised plan reads their values.
+                "toolchain": {
+                    "targetTriple": "arm-zephyr-eabi",
+                    "compiler": "arm-zephyr-eabi-gcc",
+                    "sysroot": None,
+                    "id": "arm-zephyr-eabi",
+                },
+                "artifacts": {
+                    "elf": f"{out}/zephyr/zephyr.elf",
+                    "map": f"{out}/zephyr/zephyr.map",
+                    "bin": f"{out}/zephyr/zephyr.bin",
+                    "sizeReport": f"{out}/zephyr/zephyr.stat",
+                    "symbols": f"{out}/zephyr/zephyr.symbols",
+                    "compileCommands": f"{out}/compile_commands.json",
+                    "outputDir": None,
+                },
+                "debug": {"console": "uart", "probe": None},
+                "command": {
+                    "tool": "west",
+                    "args": [
+                        "build", "-b", board, app_dir, "--",
+                        f"-DPython3_EXECUTABLE={TOKEN_PYTHON}", *defines,
+                    ],
+                    "cwd": slice_dir,
+                },
+                "postCommands": [],
+                "env": {"ALP_SDK_ROOT": TOKEN_SDK_ROOT},
+                "envAppendPath": {
+                    "EXTRA_ZEPHYR_MODULES": [TOKEN_SDK_ROOT],
+                    "PYTHONPATH": [f"{TOKEN_SDK_ROOT}/scripts"],
+                },
+            }
+        ],
+        "sharedArtefacts": [],
+        "warnings": [],
+    }
+    return json.dumps(plan, indent=2)