tan-cli 0.7.0__py3-none-any.whl

tan/core/model_zoo.py

@@ -0,0 +1,353 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The model-zoo engine behind `tan model zoo` / `tan model add` (tan-cli#1286,
+ADR-0028).
+
+alp-sdk owns the DATA (`metadata/model_zoo/<id>.yaml`, shape
+`metadata/schemas/model-zoo-v1.schema.json`, validated by that repo's own
+`scripts/validate_metadata.py`); tan owns the ENGINE that reads it, so this
+module consumes the manifests and invents no zoo format of its own. It
+re-checks only what a consumer must not take on trust (shape of the fields it
+reads, the `source` oneOf, path confinement of a bundled starter, https-only
+and sha256-pinned downloads) and tolerates fields it does not know, so an
+SDK that adds optional fields does not break an older tan.
+
+No zoo directory means an SDK that predates the data: `load_zoo` raises
+`ZooUnavailable`, which the command turns into a refusal naming
+`MIN_SDK_COMMIT`.
+
+`validated_soms` is a hardware claim and an EMPTY list means "nothing
+confirmed", never "works everywhere": `filter_by_sku` matches no entry whose
+list is empty.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import tempfile
+import time
+from collections.abc import Callable, Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+#: The alp-sdk commit that first carried `metadata/model_zoo/` (alp-sdk#2542).
+#: No released tag contains it yet; named in the `zoo-unavailable` refusal.
+MIN_SDK_COMMIT = "7018515f9"
+
+#: Model source suffixes `models[].source` accepts (board.schema.json).
+MODEL_SUFFIXES = (".tflite", ".onnx", ".pte")
+
+#: Hard ceiling on a downloaded model, so a hostile or broken URL cannot fill
+#: the disk.
+MAX_DOWNLOAD_BYTES = 256 * 1024 * 1024
+
+#: Total wall-clock budget for one download.
+MAX_DOWNLOAD_SECONDS = 300.0
+
+_ID_RE = re.compile(r"[a-z][a-z0-9-]*")
+_BUNDLED_RE = re.compile(r"starters/[A-Za-z0-9._-]+")
+_SHA256_RE = re.compile(r"[a-f0-9]{64}")
+_URL_RE = re.compile(r"https://[^\s/?#@]+/\S+")
+_SKU_RE = re.compile(r"E1M-(AEN[3-8][0-9]{2}|V2N[0-9]{3}|V2M[0-9]{3})")
+
+
+class ZooUnavailable(Exception):
+    """The bound SDK has no `metadata/model_zoo/` directory."""
+
+
+class ZooFetchError(Exception):
+    """A model could not be fetched or did not match its pinned hash."""
+
+    def __init__(self, message: str, *, mismatch: bool = False) -> None:
+        super().__init__(message)
+        self.mismatch = mismatch
+
+
+@dataclass(frozen=True)
+class ZooEntry:
+    id: str
+    kind: str
+    task: str
+    description: str
+    license: str
+    source: dict[str, str]
+    validated_soms: tuple[str, ...]
+    compile: dict[str, Any] | None
+    example_app: str | None
+
+    @property
+    def suffix(self) -> str:
+        """`.tflite`/`.onnx`/`.pte` -- from the bundled file name or the URL path."""
+        raw = self.source.get("bundled") or self.source["url"].split("?", 1)[0]
+        return Path(raw).suffix.lower()
+
+
+def entry_as_dict(entry: ZooEntry) -> dict[str, Any]:
+    """The `data.entries[]` row `--format json` carries for one entry."""
+    return {
+        "id": entry.id,
+        "kind": entry.kind,
+        "task": entry.task,
+        "description": entry.description,
+        "license": entry.license,
+        "source": dict(entry.source),
+        "validatedSoms": list(entry.validated_soms),
+        "compile": sorted(entry.compile) if entry.compile else [],
+        "exampleApp": entry.example_app,
+    }
+
+
+def _check_compile(comp: Any) -> None:
+    """`compile` must be `{backend: {key: str | int | [str|int, ...]}}` -- the
+    only shape `models[].compile` takes. Checked shallowly (no recursion), so a
+    self-referencing YAML alias is rejected here as a plain type error."""
+    if comp is None:
+        return
+    if not isinstance(comp, dict):
+        raise ValueError("`compile` must be a mapping")
+
+    def scalar(v: Any) -> bool:
+        return isinstance(v, (str, int)) and not isinstance(v, bool)
+
+    for backend, opts in comp.items():
+        if not isinstance(backend, str) or not isinstance(opts, dict) or not opts:
+            raise ValueError("`compile` must map backend ids to non-empty mappings")
+        for key, value in opts.items():
+            ok = scalar(value) or (isinstance(value, list) and value and all(scalar(v) for v in value))
+            if not isinstance(key, str) or not ok:
+                raise ValueError(f"`compile.{backend}.{key}` must be a string, integer or list of them")
+
+
+def _parse_entry(doc: Any, stem: str) -> ZooEntry:
+    """A `ZooEntry`, or `ValueError` naming the first thing wrong."""
+    if not isinstance(doc, dict):
+        raise ValueError("not a YAML mapping")
+    if doc.get("schema_version") != 1 or isinstance(doc.get("schema_version"), bool):
+        raise ValueError(f"unsupported schema_version {doc.get('schema_version')!r} (this tan reads 1)")
+    entry_id = doc.get("id")
+    if not isinstance(entry_id, str) or not _ID_RE.fullmatch(entry_id):
+        raise ValueError("`id` is missing or not lowercase kebab-case")
+    if entry_id != stem:
+        raise ValueError(f"`id` {entry_id!r} does not match the file name")
+    kind = doc.get("kind")
+    if kind not in ("model", "fixture"):
+        raise ValueError("`kind` must be `model` or `fixture`")
+    for key in ("task", "description", "license"):
+        if not isinstance(doc.get(key), str) or not doc[key]:
+            raise ValueError(f"`{key}` is missing")
+    src = doc.get("source")
+    if not isinstance(src, dict):
+        raise ValueError("`source` is missing")
+    if set(src) == {"bundled"}:
+        bundled = src["bundled"]
+        if not isinstance(bundled, str) or not _BUNDLED_RE.fullmatch(bundled) or ".." in bundled.split("/"):
+            raise ValueError("`source.bundled` must be `starters/<file>`")
+        source = {"bundled": bundled}
+    elif set(src) == {"url", "sha256"}:
+        url, digest = src["url"], src["sha256"]
+        if not isinstance(url, str) or not _URL_RE.fullmatch(url):
+            raise ValueError("`source.url` must be an https:// URL without credentials")
+        if not isinstance(digest, str) or not _SHA256_RE.fullmatch(digest):
+            raise ValueError("`source.sha256` must be 64 lowercase hex characters")
+        source = {"url": url, "sha256": digest}
+    else:
+        raise ValueError("`source` must be exactly {bundled} or {url, sha256}")
+    soms = doc.get("validated_soms")
+    if not isinstance(soms, list) or not all(isinstance(s, str) and _SKU_RE.fullmatch(s) for s in soms):
+        raise ValueError("`validated_soms` must be a list of SKUs")
+    comp = doc.get("compile")
+    _check_compile(comp)
+    example_app = doc.get("example_app")
+    if example_app is not None and not isinstance(example_app, str):
+        raise ValueError("`example_app` must be a string")
+    entry = ZooEntry(
+        entry_id, kind, doc["task"], doc["description"], doc["license"], source,
+        tuple(soms), comp or None, example_app,
+    )
+    if entry.suffix not in MODEL_SUFFIXES:
+        raise ValueError(f"source file type {entry.suffix or '(none)'!r} is not one of {', '.join(MODEL_SUFFIXES)}")
+    return entry
+
+
+def load_zoo(zoo_dir: Path) -> tuple[list[ZooEntry], list[tuple[str, str]]]:
+    """`(entries sorted by id, [(file name, problem), ...])` for every
+    `*.yaml` under `zoo_dir`. A bad file is reported and skipped, never fatal
+    to the rest. Raises `ZooUnavailable` when `zoo_dir` does not exist."""
+    import yaml  # noqa: PLC0415 (declared dependency)
+
+    if not zoo_dir.is_dir():
+        raise ZooUnavailable(str(zoo_dir))
+    entries: list[ZooEntry] = []
+    problems: list[tuple[str, str]] = []
+    for path in sorted(zoo_dir.glob("*.yaml")):
+        try:
+            entries.append(_parse_entry(yaml.safe_load(path.read_text(encoding="utf-8")), path.stem))
+        except (OSError, UnicodeDecodeError, yaml.YAMLError, ValueError, RecursionError) as err:
+            problems.append((path.name, str(err)))
+    entries.sort(key=lambda e: e.id)
+    return entries, problems
+
+
+def filter_by_sku(entries: list[ZooEntry], sku: str) -> list[ZooEntry]:
+    """Entries bench-validated on exactly `sku`; an empty `validated_soms`
+    matches nothing (module doc)."""
+    return [e for e in entries if sku in e.validated_soms]
+
+
+#: Largest read from the socket at a time (never an unbounded `read()`).
+READ_CHUNK_BYTES = 64 * 1024
+
+#: Redirects followed before giving up.
+MAX_REDIRECTS = 5
+
+
+def iter_url(
+    url: str,
+    *,
+    max_seconds: float = MAX_DOWNLOAD_SECONDS,
+    _schemes: tuple[str, ...] = ("https://",),
+) -> Iterator[bytes]:
+    """Chunks (<= 64 KiB) of a GET with tan's TLS trust context.
+
+    Hardened against a hostile server: only identity encoding is accepted (a
+    gzip/deflate body is refused, and `Accept-Encoding: identity` is sent, so
+    nothing expands transparently); a `Content-Length` over `MAX_DOWNLOAD_BYTES`
+    is refused before reading; `read1` returns after one receive, so the total
+    wall-clock deadline is checked between every chunk (a slow drip cannot
+    hide inside one long read); redirects are capped at `MAX_REDIRECTS` and may
+    only stay on https. The body is never trusted to match its
+    `Content-Length`: `fetch_source` still counts every byte against the cap.
+    `urllib` is imported here so a bare `tan` start-up does not load it."""
+    import urllib.error  # noqa: PLC0415
+    import urllib.request  # noqa: PLC0415
+
+    from tan.net import default_ssl_context  # noqa: PLC0415
+
+    deadline = time.monotonic() + max_seconds
+
+    class LimitedRedirect(urllib.request.HTTPRedirectHandler):
+        max_redirections = MAX_REDIRECTS
+
+        def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+            if not newurl.lower().startswith(_schemes):
+                raise urllib.error.URLError(f"refusing a redirect to a non-https URL: {newurl}")
+            if time.monotonic() > deadline:
+                raise urllib.error.URLError(f"not complete within {max_seconds:g} s")
+            return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+    try:
+        opener = urllib.request.build_opener(
+            urllib.request.HTTPSHandler(context=default_ssl_context()), LimitedRedirect
+        )
+        req = urllib.request.Request(
+            url, headers={"User-Agent": "tan-model-zoo", "Accept-Encoding": "identity"}
+        )
+        with opener.open(req, timeout=max(0.1, min(30.0, max_seconds))) as resp:
+            encoding = (resp.headers.get("Content-Encoding") or "identity").strip().lower()
+            if encoding != "identity":
+                raise ZooFetchError(f"{url}: refusing Content-Encoding {encoding!r}")
+            declared = resp.headers.get("Content-Length")
+            if declared and declared.strip().isdigit() and int(declared) > MAX_DOWNLOAD_BYTES:
+                raise ZooFetchError(f"{url}: Content-Length {declared} exceeds {MAX_DOWNLOAD_BYTES} bytes")
+            while True:
+                if time.monotonic() > deadline:
+                    raise ZooFetchError(f"{url}: not complete within {max_seconds:g} s")
+                chunk = resp.read1(READ_CHUNK_BYTES)
+                if not chunk:
+                    return
+                yield chunk
+    except ZooFetchError:
+        raise
+    except (OSError, ValueError) as err:  # URLError is an OSError
+        raise ZooFetchError(f"{url}: {err}") from err
+
+
+@dataclass(frozen=True)
+class StagedModel:
+    """A verified model sitting in a temp file the caller must publish or unlink."""
+
+    path: Path
+    sha256: str
+    size: int
+
+
+def bundled_chunks(zoo_dir: Path, bundled: str) -> Iterator[bytes]:
+    starters = (zoo_dir / "starters").resolve()
+    path = (zoo_dir / bundled).resolve()
+    if path.parent != starters or not path.is_file():
+        raise ZooFetchError(f"bundled starter {bundled} is missing or outside {starters}")
+    try:
+        with path.open("rb") as handle:
+            while chunk := handle.read(1 << 20):
+                yield chunk
+    except OSError as err:
+        raise ZooFetchError(f"{path}: {err}") from err
+
+
+def closing_iter(chunks: Iterable[bytes]) -> Iterator[bytes]:
+    """Iterate `chunks`, closing it (generator `.close()`, which releases the
+    HTTP connection) when the consumer stops early -- a tripped cap or deadline."""
+    it = iter(chunks)
+    try:
+        yield from it
+    finally:
+        close = getattr(it, "close", None)
+        if close is not None:
+            close()
+
+
+def fetch_source(
+    entry: ZooEntry,
+    zoo_dir: Path,
+    *,
+    tmp_dir: Path,
+    reader: Callable[[str], Iterable[bytes]] = iter_url,
+    max_seconds: float = MAX_DOWNLOAD_SECONDS,
+) -> StagedModel:
+    """Stream the model for `entry` into a temp file in `tmp_dir` (the
+    destination directory, so publishing is a same-filesystem link), hashing as
+    it goes -- never buffering the model in memory. A download is capped in
+    size and total wall-clock time and must hash to the manifest's `sha256`;
+    a bundled starter is read from inside `zoo_dir/starters` (confined). The
+    temp file is removed on any failure. Raises `ZooFetchError`; a hash
+    mismatch sets `.mismatch`."""
+    bundled = entry.source.get("bundled")
+    chunks = closing_iter(bundled_chunks(zoo_dir, bundled) if bundled else reader(entry.source["url"]))
+    label = bundled or entry.source["url"]
+    digest = hashlib.sha256()
+    size = 0
+    deadline = time.monotonic() + max_seconds
+    fd, tmp_name = tempfile.mkstemp(dir=tmp_dir, prefix=".tan-zoo-", suffix=".part")
+    try:
+        # `mkstemp` makes a 0600 file; the published model should carry the
+        # mode an ordinary new file would (0666 & ~umask).
+        mask = os.umask(0)
+        os.umask(mask)
+        os.chmod(tmp_name, 0o666 & ~mask)
+        with os.fdopen(fd, "wb") as out:
+            for chunk in chunks:
+                if size + len(chunk) > MAX_DOWNLOAD_BYTES:
+                    raise ZooFetchError(f"{label}: larger than {MAX_DOWNLOAD_BYTES} bytes")
+                size += len(chunk)
+                if time.monotonic() > deadline:
+                    raise ZooFetchError(f"{label}: not complete within {max_seconds:g} s")
+                digest.update(chunk)
+                out.write(chunk)
+        chunks.close()
+        got = digest.hexdigest()
+        if not bundled and got != entry.source["sha256"]:
+            raise ZooFetchError(
+                f"{label}: sha256 {got} does not match the manifest's {entry.source['sha256']}",
+                mismatch=True,
+            )
+    except OSError as err:
+        chunks.close()
+        Path(tmp_name).unlink(missing_ok=True)
+        raise ZooFetchError(f"{label}: {err}") from err
+    except BaseException:
+        chunks.close()
+        Path(tmp_name).unlink(missing_ok=True)
+        raise
+    return StagedModel(Path(tmp_name), got, size)

tan/core/module_template.py

@@ -0,0 +1,340 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Module-scaffold template registry, name normalization, and file-content
+generators for `tan scaffold` -- adds one driver/service/stage/check module
+INTO an existing project. Distinct from `tan.core.scaffold`, which is the
+whole-*project* `tan init` engine (a different template id space: six
+project templates there vs. the four module templates here, and neither
+registry's ids overlap the other's).
+
+Port of `crates/tan-core/src/wizard/{models,service/registry,service/plan,
+service/module_scaffold}.rs`'s module-scaffold slice only -- the project-
+wizard half of those same files is `tan.core.scaffold`'s job.
+
+Diffing planned files against disk, writing them, and rendering the ASCII
+tree preview are deliberately NOT re-implemented here: `tan.core.scaffold`'s
+`PlannedFile` / `collect_file_changes` / `write_files` / `scaffold_tree_preview`
+already do exactly that -- module-scaffold's planned files are the SAME
+`PlannedFile` shape a whole-project plan uses, and `write_files` already
+carries the tan-cli#325 containment fix (`tan.core.fs_confine.resolve_confined`).
+A second copy of any of the four here would be exactly the drift
+`tan.core.fs_confine`'s own module docstring warns a THIRD hand-rolled
+resolver into being.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from tan.core.scaffold import PlannedFile
+
+#: Module template ids, in registry order (`ModuleTemplateId::as_str`,
+#: `wizard/models.rs`). Wire contract: `data.templateId` echoes one of these
+#: verbatim.
+MODULE_TEMPLATE_IDS = (
+    "sensor-driver",
+    "connectivity-service",
+    "inference-stage",
+    "diagnostics-check",
+)
+
+#: The template a non-interactive `tan scaffold` with no `--template` gets --
+#: `resolve_template`'s non-interactive arm in `crates/tan-cli/src/commands/
+#: scaffold.rs` hardcodes `ModuleTemplateId::SensorDriver`, the registry's
+#: first entry. Unlike `tan.core.scaffold.DEFAULT_TEMPLATE_ID` (`tan init`'s
+#: own default), this one has no reason to diverge from "first in the list":
+#: there is no `CMakeLists.txt`-shaped trap here, every module template emits
+#: the same three-file shape.
+DEFAULT_MODULE_TEMPLATE_ID = "sensor-driver"
+
+
+@dataclass(frozen=True)
+class ModuleTemplateDefinition:
+    """One module-template registry entry. `explanation` lines may contain a
+    literal `{nm}` placeholder, substituted with the normalized module name
+    when a module's `README.md` is rendered (see `_readme`, below)."""
+
+    id: str
+    label: str
+    description: str
+    function_prefix: str
+    explanation: tuple[str, ...]
+
+
+#: `MODULE_TEMPLATE_DEFINITIONS` (`wizard/service/registry.rs`), ported
+#: verbatim -- same four ids, same order, same prose.
+_REGISTRY: tuple[ModuleTemplateDefinition, ...] = (
+    ModuleTemplateDefinition(
+        id="sensor-driver",
+        label="Sensor driver module",
+        description="Adds a source/header pair for sensor acquisition logic.",
+        function_prefix="alp_sensor",
+        explanation=(
+            "Use {nm}_run to place sensor polling and conversion logic.",
+            "Keep hardware-specific register access isolated from upper-level app flow.",
+        ),
+    ),
+    ModuleTemplateDefinition(
+        id="connectivity-service",
+        label="Connectivity service module",
+        description="Adds module skeleton for network/session orchestration.",
+        function_prefix="alp_conn",
+        explanation=(
+            "Use {nm}_init for stack/session initialization.",
+            "Keep retry/backoff and transport health checks localized in this module.",
+        ),
+    ),
+    ModuleTemplateDefinition(
+        id="inference-stage",
+        label="Inference stage module",
+        description="Adds module skeleton for model pre/post processing path.",
+        function_prefix="alp_infer",
+        explanation=(
+            "Use {nm}_run to host pre-process, infer, and post-process calls.",
+            "Keep model IO shaping and feature extraction close to this module boundary.",
+        ),
+    ),
+    ModuleTemplateDefinition(
+        id="diagnostics-check",
+        label="Diagnostics check module",
+        description="Adds bring-up and runtime health-check module scaffold.",
+        function_prefix="alp_diag",
+        explanation=(
+            "Use {nm}_run for periodic health checks and error probes.",
+            "Keep board bring-up assertions and diagnostics output in this module.",
+        ),
+    ),
+)
+
+_BY_ID = {d.id: d for d in _REGISTRY}
+
+
+def list_module_templates() -> list[ModuleTemplateDefinition]:
+    """All registered module-scaffold templates, in registry order."""
+    return list(_REGISTRY)
+
+
+def normalize_module_name(name: str) -> str:
+    """Lowercase `name` and collapse every run of non-`[a-z0-9]` characters
+    (after lowering) into a single `_` separator, with none leading or
+    trailing. Raises `ValueError` -- its message is `scaffold.invalid-name`'s
+    wire text verbatim -- when nothing survives.
+
+    `wizard::service::plan::normalize_module_name`, ported: Rust lowercases
+    with the full Unicode mapping, then keeps only `is_ascii_lowercase() ||
+    is_ascii_digit()` chars, treating everything else (accented letters
+    included, even after they lower) as a separator run. Python's `.lower()`
+    is equally Unicode-aware, so the same two-step -- lower, then filter to
+    ASCII alnum -- reproduces it byte-for-byte (measured against the oracle:
+    `"Héllo--World123"` -> `"h_llo_world123"`, the accented `é` collapsing
+    into the same run as the double dash beside it).
+    """
+    lowered = name.strip().lower()
+    out: list[str] = []
+    in_sep = False
+    for ch in lowered:
+        if ("a" <= ch <= "z") or ("0" <= ch <= "9"):
+            if in_sep and out:
+                out.append("_")
+            out.append(ch)
+            in_sep = False
+        else:
+            in_sep = True
+    result = "".join(out)
+    if not result:
+        raise ValueError("Module name is empty after normalization.")
+    return result
+
+
+def _header(prefix: str, nm: str) -> str:
+    """`gen_module_header`, ported. `nm` is always already-normalized ASCII
+    lowercase/digits/underscore, so a plain `.upper()` reproduces Rust's
+    `nm.to_uppercase()` exactly -- no non-ASCII input ever reaches here."""
+    upper = nm.upper()
+    return (
+        "// SPDX-License-Identifier: Apache-2.0\n"
+        "\n"
+        f"#ifndef ALP_MODULES_{upper}_H\n"
+        f"#define ALP_MODULES_{upper}_H\n"
+        "\n"
+        f"int {prefix}_{nm}_init(void);\n"
+        f"int {prefix}_{nm}_run(void);\n"
+        "\n"
+        f"#endif /* ALP_MODULES_{upper}_H */\n"
+    )
+
+
+def _source(prefix: str, nm: str, board_context: str | None) -> str:
+    """`gen_module_c`, ported, with tan-cli#1031's RESOLVED board line.
+
+    *board_context* is `"<som.sku> / <os>"` as
+    `tan.core.board_context.read_board_context` reads it out of the project's
+    own `board.yaml`, or `None` when no board resolved. `None` renders the
+    `unavailable` placeholder this line has carried since the Rust oracle --
+    unchanged bytes, but it now means "there is genuinely no board.yaml here"
+    instead of "this command never looked", which is the whole of tan-cli#1031:
+    every project got `unavailable`, including one that passed
+    `--board-yaml <p>/board.yaml` explicitly.
+
+    Not read from disk here: this module plans FILE CONTENT and has no IO, the
+    same split `plan_module_files` keeps for diffing and writing (see the
+    module docstring). The command resolves, this renders.
+    """
+    hint = board_context if board_context else "unavailable"
+    return (
+        "// SPDX-License-Identifier: Apache-2.0\n"
+        "\n"
+        f'#include "modules/{nm}.h"\n'
+        "\n"
+        f"// Board context: {hint}\n"
+        "\n"
+        f"int {prefix}_{nm}_init(void) {{\n"
+        "  // TODO: initialize module dependencies.\n"
+        "  return 0;\n"
+        "}\n"
+        "\n"
+        f"int {prefix}_{nm}_run(void) {{\n"
+        "  // TODO: implement module main behavior.\n"
+        "  return 0;\n"
+        "}\n"
+    )
+
+
+def _wiring(nm: str) -> str:
+    """The `## Wiring` section (tan-cli#494 defect 5).
+
+    `tan scaffold` wrote a module NO SHIPPED TEMPLATE CAN BUILD and said
+    nothing about it. Measured off the frozen oracle trees in
+    `tests/fixtures/oracle_captures/scaffold_trees.json`, which are the six
+    project templates' real bytes: not one of the six names `modules` in any
+    `CMakeLists.txt`, so `src/modules/<nm>/<nm>.c` is compiled by nothing, and
+    only `minimal-app` sets an include directory at all, so
+    `#include "modules/<nm>.h"` does not resolve under the other five. The
+    command reported `ok:true`, three files written, no issue and no next
+    step, and the module was silently dead.
+
+    Inherited from the frozen oracle
+    (`crates/tan-core/src/wizard/service/module_scaffold.rs`), so this is a
+    pre-existing PRODUCT gap rather than a port regression -- and the oracle
+    is a fixed point for behaviour that is right, not for a scaffold that
+    cannot build. Nothing frozen pins these particular bytes:
+    `PARITY-COVERAGE.txt` records `scaffold` as covered for its REFUSAL
+    envelope only ("STILL UNCOVERED: an actual write"), `contract/envelopes/`
+    carries no scaffold success case, and `scaffold_trees.json` freezes `tan
+    init`'s PROJECT trees -- it contains no `src/modules/` path at all. The
+    only pin is `tests/core/test_module_template.py`'s hand-written
+    expectation, updated with this change.
+
+    **Two shapes, because the six templates have two.** `tan scaffold` adds a
+    module to an EXISTING project and is never told which template made it
+    (`plan_module_files` receives the definition and the name, nothing else),
+    so the section cannot pick one -- and naming only the majority shape would
+    hand `minimal-app` users a target that does not exist in their tree. Five
+    templates (`zephyr-app`, `iot-starter`, `sensor-starter`,
+    `edge-ai-starter`, `board-diagnostics`) use Zephyr's `app` target in the
+    top-level `CMakeLists.txt`; `minimal-app` builds `alp_app` from an
+    `ALP_APP_SOURCES` list in `src/CMakeLists.txt` and already sets
+    `target_include_directories(alp_app PRIVATE ../include)`, so it needs the
+    source entry only -- relative to `src/`, since that is where its
+    `add_executable` lives.
+
+    The exact lines are spelled out rather than described, because they are
+    the whole content of the fix: an approximate instruction here is worth no
+    more than the silence it replaces.
+    """
+    return (
+        "## Wiring\n"
+        "\n"
+        "`tan scaffold` writes this module but does NOT edit your build files.\n"
+        "\n"
+        "Most templates (`zephyr-app`, `iot-starter`, `sensor-starter`,\n"
+        "`edge-ai-starter`, `board-diagnostics`) build Zephyr's `app` target -- add\n"
+        "both lines to the top-level `CMakeLists.txt`, after its `target_sources`:\n"
+        "\n"
+        "```cmake\n"
+        f"target_sources(app PRIVATE src/modules/{nm}/{nm}.c)\n"
+        "target_include_directories(app PRIVATE include)\n"
+        "```\n"
+        "\n"
+        "`minimal-app` builds `alp_app` and already sets its include directory, so\n"
+        "it needs the source only -- add this to `ALP_APP_SOURCES` in\n"
+        "`src/CMakeLists.txt` (paths there are relative to `src/`):\n"
+        "\n"
+        "```cmake\n"
+        f"  modules/{nm}/{nm}.c\n"
+        "```\n"
+        "\n"
+        "Without the source entry the module is never compiled; without an include\n"
+        f'directory `#include "modules/{nm}.h"` does not resolve.\n'
+    )
+
+
+def _readme(definition: ModuleTemplateDefinition, nm: str) -> str:
+    """`gen_module_readme`, ported, plus the `## Wiring` section (see
+    [`_wiring`] for why the oracle's own output is not the fixed point here)."""
+    lines = "".join(f"- {line.replace('{nm}', nm)}\n" for line in definition.explanation)
+    return (
+        "# Alp Module Scaffold\n"
+        "\n"
+        f"Template: {definition.id}\n"
+        f"Module: {nm}\n"
+        "\n"
+        "## Notes\n"
+        "\n"
+        f"{lines}"
+        "\n"
+        f"{_wiring(nm)}"
+        "\n"
+        "Generated by Alp: Scaffold module.\n"
+    )
+
+
+def plan_module_files(
+    definition: ModuleTemplateDefinition, nm: str, board_context: str | None = None
+) -> list[PlannedFile]:
+    """The three files a module template lays down: a header, its source, and
+    a README. `gen_module_files`, ported -- same relative paths, same order
+    (the order the oracle's own `data.fileChanges[]` lists them in, and what
+    `contract`-style byte-for-byte JSON comparison depends on).
+
+    *board_context*: see [`_source`]. Defaults to `None` (the `unavailable`
+    line) so a caller with no project in hand -- every existing one but
+    `scaffold_cmd` -- is unchanged."""
+    return [
+        PlannedFile(f"include/modules/{nm}.h", _header(definition.function_prefix, nm)),
+        PlannedFile(
+            f"src/modules/{nm}/{nm}.c",
+            _source(definition.function_prefix, nm, board_context),
+        ),
+        PlannedFile(f"src/modules/{nm}/README.md", _readme(definition, nm)),
+    ]
+
+
+@dataclass(frozen=True)
+class ModuleScaffoldPlan:
+    """`ModuleScaffoldPlan`, ported: the resolved template plus the module's
+    normalized name and its planned files."""
+
+    template_id: str
+    normalized_name: str
+    files: list[PlannedFile]
+
+
+def create_module_scaffold_plan(
+    template_id: str, module_name: str, board_context: str | None = None
+) -> ModuleScaffoldPlan:
+    """Normalize `module_name`, then plan its three-file set against
+    `template_id`. Raises `ValueError` when the name normalizes to empty
+    (`normalize_module_name`); a `template_id` outside `MODULE_TEMPLATE_IDS`
+    is a caller bug, not a user error -- `scaffold_cmd` validates it against
+    the registry BEFORE calling this, so `KeyError` here would mean that
+    validation was skipped. `create_module_scaffold_plan`, ported.
+
+    *board_context* is threaded straight through to [`plan_module_files`] and
+    is the only input here that is not derivable from the two required
+    arguments -- it is a fact about the PROJECT, which this registry has no
+    way to reach and (per its own module docstring) no business reading.
+    """
+    normalized = normalize_module_name(module_name)
+    definition = _BY_ID[template_id]
+    files = plan_module_files(definition, normalized, board_context)
+    return ModuleScaffoldPlan(template_id=template_id, normalized_name=normalized, files=files)