tan-cli 0.7.0__py3-none-any.whl

tan/commands/workspace_patch_check.py

@@ -0,0 +1,296 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Is alp-sdk's `zephyr/patches.yml` applied in the resolved west workspace?
+(tan-cli#1376)
+
+A customer hit `alp_camera_open FAILED: ALP_ERR_NOSUPPORT` because the
+workspace lacked patch 0001 (Alif clock `set_rate`) while `tan build` said
+`ok: true`. `tan bootstrap` applies the patches (`bootstrap_patches.py`); this
+module only ASKS, for `tan doctor` and `tan build`, and never writes to the
+workspace.
+
+The SDK's own `scripts/verify_west_patches.py` is the source of truth and is
+run unchanged; this module reads its exit code (0 applied / 1 not applied /
+2 uninspectable / 3 module not checked out) and its failure report. It never
+raises: an absent verifier (older SDK), a missing interpreter, a timeout or an
+unreadable report all become `unchecked`, because a check that cannot run must
+not fail an offline doctor or a build.
+
+Caching (`tan build` only): a positive verdict (applied, or applied with some
+modules not checked out) is stored in `<project>/build/` keyed by (every
+workspace module's HEAD, `patches.yml` bytes, and a working-tree fingerprint:
+`(path, mtime_ns, size)` of every file the patches write, looked up under every
+module checkout). The fingerprint matters because `west patch clean`,
+`git checkout -- .` and `git stash` revert patches WITHOUT moving HEAD; they
+rewrite the patched files, so mtime/size change and the cache misses. Only
+positive verdicts are cached: a cached "missing" would go stale the moment the
+user ran `tan bootstrap`.
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import tempfile
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+
+from tan.core.atomic_write import atomic_write_text
+from tan.core.host_python import probe_host_python
+from tan.core.patch_paths import patch_paths
+from tan.core.subprocess_env import spawn_env
+from tan.core.venv import venv_python, west_program
+from tan.core.west_patches import (
+    UnappliedPatch,
+    cache_key,
+    classify_verify,
+    parse_unapplied,
+    parse_unapplied_patches,
+)
+
+APPLIED = "applied"
+MISSING = "missing"
+UNCHECKED = "unchecked"
+
+CACHE_FILE = ".tan-workspace-patches.json"
+_VERIFIER = Path("scripts") / "verify_west_patches.py"
+_PATCHES_YML = Path("zephyr") / "patches.yml"
+_TIMEOUT_S = 120
+_PYTHON_FLOOR = (3, 10)
+
+
+@dataclass(frozen=True)
+class PatchCheck:
+    state: str  # APPLIED | MISSING | UNCHECKED
+    patches: list[UnappliedPatch] = field(default_factory=list)
+    modules: list[str] = field(default_factory=list)
+    #: Why `unchecked`, or the applied count line; empty for `missing`.
+    note: str = ""
+    cached: bool = False
+    #: Why `tan build` re-verifies on every build: the cache key could not be
+    #: built in full, so nothing is cached. Empty when caching was in play.
+    cache_note: str = ""
+
+
+def _run(argv: list[str], cwd: str, timeout: int = _TIMEOUT_S) -> tuple[int | None, str, str]:
+    try:
+        out = subprocess.run(
+            argv, cwd=cwd, capture_output=True, text=True, encoding="utf-8",
+            errors="replace", stdin=subprocess.DEVNULL, timeout=timeout,
+            env=spawn_env(), check=False,
+        )
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return None, "", ""
+    return out.returncode, out.stdout, out.stderr
+
+
+def _head(module_dir: Path) -> str:
+    """A cheap, spawn-free identity of a checkout's HEAD. Not a verdict: it
+    only has to CHANGE when the checkout moves."""
+    try:
+        git = module_dir / ".git"
+        gitdir = git
+        if git.is_file():
+            text = git.read_text(encoding="utf-8").strip()
+            if text.startswith("gitdir:"):
+                gitdir = (module_dir / text[len("gitdir:"):].strip()).resolve()
+        head_file = gitdir / "HEAD"
+        head = head_file.read_text(encoding="utf-8").strip()
+        if head.startswith("ref:"):
+            ref = head[4:].strip()
+            loose = gitdir / ref
+            if loose.is_file():
+                return loose.read_text(encoding="utf-8").strip()
+            packed = gitdir / "packed-refs"
+            if packed.is_file():
+                for line in packed.read_text(encoding="utf-8").splitlines():
+                    if line.endswith(" " + ref):
+                        return line.split(" ", 1)[0]
+            return f"{ref}@{head_file.stat().st_mtime_ns}"
+        return head
+    except (OSError, UnicodeDecodeError):
+        return "unreadable"
+
+
+def _workspace_heads(west: str, workspace: Path) -> dict[str, str] | None:
+    code, out, _ = _run([west, "list", "-f", "{abspath}"], str(workspace))
+    if code != 0:
+        return None
+    return {p: _head(Path(p)) for p in (ln.strip() for ln in out.splitlines()) if p}
+
+
+_PATCH_ENTRY = re.compile(r"^\s*-?\s*path:\s*['\"]?([^'\"#\s]+)", re.MULTILINE)
+
+
+def _patched_files(sdk: Path) -> list[str] | None:
+    """Repo-relative paths every `patches.yml` patch touches, or `None`.
+
+    Every path a patch touches counts, deletions, renames and binary patches
+    included (`tan.core.patch_paths`), so a revert that restores a deleted
+    file moves the fingerprint.
+
+    `None` when the list cannot be trusted to be complete: `patches.yml` or
+    any named patch is unreadable, or no path was found at all. A partial
+    list would silently weaken the cache key towards HEAD-only, reopening the
+    revert hole for the dropped files, so the caller skips caching instead.
+    """
+    rels: set[str] = set()
+    try:
+        entries = _PATCH_ENTRY.findall((sdk / _PATCHES_YML).read_text(encoding="utf-8"))
+        for entry in entries:
+            text = (sdk / "zephyr" / "patches" / entry).read_text(encoding="utf-8", errors="replace")
+            rels.update(patch_paths(text))
+    except (OSError, ValueError):
+        return None
+    return sorted(rels) or None
+
+
+def _tree_fingerprint(module_dirs: list[str], rels: list[str]) -> dict[str, str]:
+    """`{path: "mtime_ns:size"}` for each patched file present under any module."""
+    out: dict[str, str] = {}
+    for d in module_dirs:
+        for rel in rels:
+            f = Path(d) / rel
+            try:
+                st = f.stat()
+            except OSError:
+                continue
+            out[str(f)] = f"{st.st_mtime_ns}:{st.st_size}"
+    return out
+
+
+def _cache_key(west: str, workspace: Path, sdk: Path, why: list[str]) -> str | None:
+    """The cache key, or `None` after appending the reason to `why` when it
+    cannot be built in full (nothing is then cached)."""
+    heads = _workspace_heads(west, workspace)
+    if heads is None:
+        why.append("the west workspace modules could not be listed")
+        return None
+    try:
+        rels = _patched_files(sdk)
+        if rels is None:
+            why.append("zephyr/patches.yml or a patch it names could not be read in full")
+            return None
+        tree = _tree_fingerprint(list(heads), rels)
+        return cache_key((sdk / _PATCHES_YML).read_bytes(), {**heads, **tree})
+    except OSError:
+        why.append("zephyr/patches.yml could not be read")
+        return None
+
+
+def _interpreter(workspace: Path, sdk_root: str) -> str | None:
+    # The workspace venv carries west + pyyaml (Zephyr's requirements), which
+    # the verifier imports; the resolved host Python is the fallback.
+    py = venv_python(str(workspace), sdk_root)
+    if py is not None:
+        return py
+    host = probe_host_python(_PYTHON_FLOOR, need_west=True)
+    return host.interpreter if host is not None else None
+
+
+def _read_cache(path: Path, key: str) -> str | None:
+    """The cached state (`APPLIED` or `UNCHECKED`) for `key`, else `None`."""
+    try:
+        doc = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if isinstance(doc, dict) and doc.get("key") == key and doc.get("state") in (APPLIED, UNCHECKED):
+        return doc["state"]
+    return None
+
+
+def _cache_hit(cache_dir: Path, key: str | None) -> PatchCheck | None:
+    cached = _read_cache(cache_dir / CACHE_FILE, key) if key is not None else None
+    if cached == APPLIED:
+        return PatchCheck(APPLIED, note="verified applied (cached)", cached=True)
+    if cached == UNCHECKED:
+        return PatchCheck(UNCHECKED, note=_PARTIAL_NOTE, cached=True)
+    return None
+
+
+def _write_cache(path: Path, key: str, state: str) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(str(path), json.dumps({"key": key, "state": state}))
+    except Exception:  # noqa: BLE001 -- the cache is an optimisation
+        pass
+
+
+_PARTIAL_NOTE = (
+    "some zephyr/patches.yml modules are not checked out in this workspace; "
+    "their patches could not be checked"
+)
+
+
+def check_workspace_patches(
+    workspace: Path,
+    sdk_root: str | None,
+    *,
+    cache_dir: Path | None = None,
+    timeout: int = _TIMEOUT_S,
+) -> PatchCheck:
+    """Verify `<sdk_root>/zephyr/patches.yml` against `workspace`. Read-only,
+    and never raises: anything unexpected is `unchecked`."""
+    why: list[str] = []
+    try:
+        result = _check(workspace, sdk_root, cache_dir, timeout, why)
+        if why and result.state != MISSING:
+            result = replace(result, cache_note=why[0])
+        return result
+    except Exception:  # noqa: BLE001 -- an advisory check must never break its caller
+        return PatchCheck(UNCHECKED, note="the patch check failed unexpectedly")
+
+
+def _check(
+    workspace: Path, sdk_root: str | None, cache_dir: Path | None, timeout: int,
+    why: list[str],
+) -> PatchCheck:
+    if sdk_root is None:
+        return PatchCheck(UNCHECKED, note="no alp-sdk checkout resolved")
+    sdk = Path(sdk_root)
+    verifier, patches_yml = sdk / _VERIFIER, sdk / _PATCHES_YML
+    if not verifier.is_file() or not patches_yml.is_file():
+        return PatchCheck(
+            UNCHECKED,
+            note="this alp-sdk checkout carries no patch verifier "
+            "(scripts/verify_west_patches.py), so patches cannot be checked",
+        )
+    west = west_program(str(workspace), sdk_root)
+    key = None
+    if cache_dir is not None:
+        key = _cache_key(west, workspace, sdk, why)
+        hit = _cache_hit(cache_dir, key)
+        if hit is not None:
+            return hit
+
+    python = _interpreter(workspace, sdk_root)
+    if python is None:
+        return PatchCheck(UNCHECKED, note="no Python able to run the patch verifier was found")
+    argv = [
+        python, str(verifier), "--repo", str(sdk),
+        "--topdir", str(workspace), "--west", west,
+    ]
+    with tempfile.TemporaryDirectory(prefix="tan-patches-") as scratch:
+        code, _out, err = _run(argv, scratch, timeout)
+        verdict = classify_verify(code)
+        if verdict == "applied":
+            if key is not None and cache_dir is not None:
+                _write_cache(cache_dir / CACHE_FILE, key, APPLIED)
+            return PatchCheck(APPLIED, note="verified applied")
+        if verdict == "unchecked":
+            # Everything inspectable is patched: as good as applied until a
+            # head or patched file moves, so it is cached too.
+            if key is not None and cache_dir is not None:
+                _write_cache(cache_dir / CACHE_FILE, key, UNCHECKED)
+            return PatchCheck(UNCHECKED, note=_PARTIAL_NOTE)
+        if verdict != "unapplied" or "Traceback" in err:
+            return PatchCheck(
+                UNCHECKED,
+                note="the patch verifier could not inspect this workspace "
+                "(run scripts/verify_west_patches.py directly to see why)",
+            )
+        # Exit 1 is the verifier's "not applied"; if it printed no parsable
+        # line, the patches are unnamed but still missing.
+        patches = parse_unapplied_patches(err)
+        lcode, listing, _ = _run([*argv, "--list-unapplied"], scratch, timeout)
+        modules = parse_unapplied(listing) if lcode == 0 else []
+    return PatchCheck(MISSING, patches=patches, modules=modules)

tan/core/__init__.py

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

tan/core/alp_conf_pregen.py

@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: Apache-2.0
+"""What to tell a `tan init --from-example` user whose copied example reads a
+pre-generated `generated/alp.conf` (alp-sdk#866).
+
+alp-sdk#866 deleted the example `CMakeLists.txt` bridge that wrote the
+per-core `alp.conf` at configure time. An example's twister scenarios and
+bare `west build` lines now pass `EXTRA_CONF_FILE=generated/alp.conf`, and
+its prose points at alp-sdk's `scripts/gen_example_alp_conf.py` to write it.
+That script only walks alp-sdk's own `examples/`: run against a project
+`tan init --from-example` copied out, it exits 0 having written nothing.
+`tan build` needs none of it (the plan writes and passes its own `alp.conf`),
+but a bare `west build`/twister run in the copied project names a missing
+overlay, which Zephyr refuses.
+
+`--from-example` copies the example verbatim -- the prose is the SDK's, at
+the bound SDK's revision, and tan does not rewrite it. What tan CAN do
+honestly is say, once, which command writes the file in this project:
+`tan generate --target zephyr-conf --core <id> --output <dir>/generated/alp.conf`
+writes exactly the bytes the build plan's `configArtefacts` carry for that
+core. Pure: takes the planned files, returns the message or `None`.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import re
+from collections.abc import Iterable
+from typing import Protocol
+
+#: The reference the message is about. `(?<![\w])` rejects Zephyr's
+#: per-image `<image>_EXTRA_CONF_FILE=` spelling.
+_READS_GENERATED = re.compile(r"(?<![\w])EXTRA_CONF_FILE=generated/alp\.conf(?![\w./])")
+
+#: Core OSes that have no Zephyr `alp.conf` at all.
+_NON_ZEPHYR_OS = frozenset({"off", "yocto", "baremetal", "linux"})
+
+_CORE_PLACEHOLDER = "<core-id>"
+
+
+class _File(Protocol):
+    relative_path: str
+    content: str
+
+
+def _dir_of(path: str) -> str:
+    return posixpath.dirname(path)
+
+
+def _app_dirs(cores: object, paths: set[str]) -> dict[str, list[str]]:
+    """`{project-relative west app dir: [core ids]}` for every Zephyr-capable
+    core. Mirrors the planner's `_zephyr_app_dir` rule: the `app:` directory
+    itself when it carries a `CMakeLists.txt`, else its parent."""
+    out: dict[str, list[str]] = {}
+    if not isinstance(cores, dict):
+        return out
+    for core_id, cfg in cores.items():
+        if not isinstance(core_id, str) or not isinstance(cfg, dict):
+            continue
+        if str(cfg.get("os", "")).lower() in _NON_ZEPHYR_OS:
+            continue
+        app = cfg.get("app")
+        if not isinstance(app, str) or not app.strip():
+            continue
+        app_dir = posixpath.normpath(app.strip())
+        app_dir = "" if app_dir == "." else app_dir
+        if posixpath.join(app_dir, "CMakeLists.txt") not in paths:
+            app_dir = _dir_of(app_dir)
+        out.setdefault(app_dir, []).append(core_id)
+    return out
+
+
+def pregeneration_message(
+    files: Iterable[_File], board_cores: object, sdk_display: str, subject: str
+) -> str | None:
+    """The one-paragraph instruction, or `None` when no copied file reads
+    `generated/alp.conf`. *board_cores* is the copied board.yaml's parsed
+    `cores:` mapping (anything else degrades to the `<core-id>` placeholder).
+    """
+    files = list(files)
+    readers = sorted(f.relative_path for f in files if _READS_GENERATED.search(f.content))
+    if not readers:
+        return None
+    by_dir = _app_dirs(board_cores, {f.relative_path for f in files})
+    commands = []
+    for directory in sorted({_dir_of(r) for r in readers}):
+        candidates = by_dir.get(directory, [])
+        core = candidates[0] if len(candidates) == 1 else _CORE_PLACEHOLDER
+        output = posixpath.join(directory, "generated/alp.conf")
+        commands.append(
+            f"tan generate --target zephyr-conf --core {core} "
+            f"--sdk-root {sdk_display} --output {output}"
+        )
+    return (
+        f"{subject} reads generated/alp.conf ({', '.join(readers)}): `tan build` "
+        "writes its own and does not need it, but a bare `west build` or twister "
+        "run in this project does. Write it with: "
+        + "; ".join(f"`{c}`" for c in commands)
+        + ". The example's own pointer, alp-sdk's scripts/gen_example_alp_conf.py, "
+        "only writes inside alp-sdk's examples/ (alp-sdk#866)."
+    )

tan/core/artifact_provenance.py

@@ -0,0 +1,240 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`metadata/bootstrap.json`'s `artifactProvenance` block, normalised --
+pure, no IO (same contract as `tan.core.bootstrap`, which imports this).
+
+alp-sdk v0.16.0 (alplabai/alp-sdk#1574) added a top-level `artifactProvenance`
+map to the manifest tan already reads for `missingPrerequisites[].command`:
+
+    "artifactProvenance": {
+      "cmake": {"tier": "A", "source": "https://cmake.org/",
+                "sizeBytes": null, "licence": "BSD-3-Clause"},
+      ...
+    }
+
+Its keys are the `prerequisites.{posix,macos,windows}` tool vocabulary (plus
+`7zip`) -- the SAME names `missingPrerequisites[].tool` already carries -- so
+carrying the block onto those entries is a join on an identity that already
+exists, not a new one (tan-cli#1066).
+
+**`source` on the wire becomes `sourceUrl`.** alp-sdk spells the upstream
+project page `source`; the envelope deliberately does not. The consumer that
+asked for this (alp-sdk-vscode#467's dependency-consent screen) already
+defines a `source` column as *what will actually run* -- the install command,
+verbatim -- and the artifact a user actually installs is a brew bottle or an
+apt package, not the tarball behind that page. One name for two meanings would
+misinform the security reader the screen exists for, so tan-cli#1066 renames
+it at the seam it crosses. `licence` keeps alp-sdk's own (British) spelling,
+because that one is the same fact under the same name.
+
+**Absence is `null`, never an omitted key and never a default.** `xz` and
+`7zip` genuinely declare no licence upstream and every entry's `sizeBytes` is
+`null` today; an SDK predating the block (v0.16.0-rc1 and earlier) reports
+`null` for all four. "Not reported" is a true answer and an invented one is
+not -- and a key set that is stable regardless of the SDK in front of it is
+what lets `contract/doctor-data-keys.json` declare one shape rather than
+"these four keys, sometimes".
+
+**Malformed input DEGRADES, it does not refuse.** This is the one place this
+module deliberately does NOT reuse the curated-error register the sibling
+readers use (`planner.template._require_mapping_doc` / `_require_field`, PR
+tan-cli#1073/#1082, which raise a named `TemplateError`). Those guard a
+document whose content the command cannot proceed without. This one is
+advisory display metadata hanging off `tan doctor` -- whose whole job is to
+report on a broken environment, and which already treats a missing or
+malformed `bootstrap.json` as a warning with a documented fallback rather than
+a refusal (`doctor_cmd._load_manifest`'s own docstring: "a doctor that cannot
+start because the thing it diagnoses is broken is the failure mode it exists
+to prevent"). Refusing here would let one upstream typo in a field nobody
+builds with take out the diagnosis of every OTHER thing wrong with the host.
+So every malformed shape -- a non-mapping block, a non-mapping entry, a
+missing or wrongly-typed field -- collapses to the SAME `null` an absent SDK
+key yields, per FIELD rather than per block: a `cmake` entry whose `sizeBytes`
+is the string `"12"` still reports its real `tier`/`licence`/`sourceUrl`.
+
+**Degrading is not the same as saying nothing** (tan-cli#1066 review).
+Silently, a corrupt block and an SDK predating the block produce byte-identical
+envelopes -- so an alp-sdk generator regression would render "not reported" on
+every consent screen with `tan doctor` saying nothing at all, which is the
+failure mode `doctor` exists to prevent. `problems_in` (below) is what makes it
+sayable: `doctor_cmd` raises its EXISTING `bootstrapManifest` warn and
+`doctor.bootstrap-manifest` issue for a block that is present and unreadable,
+and stays silent for one that is merely absent. Nothing about the entries or
+the exit code changes -- the four keys are still there, still `null`.
+
+Its report is DERIVED from these parsers, never a second opinion about types: a
+field is called unreadable exactly when the manifest declared a value (not
+`null`, not absent) and the real reader still answered `None`. Tightening
+`_count` -- the negative-size refusal, say -- starts being reported with no
+change to `problems_in` at all; loosening it stops being reported. A test pins
+that coupling rather than trusting this paragraph.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+#: The manifest's own key for the block, and for the one field renamed on the
+#: wire. Named rather than inlined so the rename has exactly one spelling.
+BLOCK_KEY = "artifactProvenance"
+SDK_SOURCE_KEY = "source"
+
+
+@dataclass(frozen=True)
+class ArtifactProvenance:
+    """One tool's provenance, already normalised to the wire's own shape.
+
+    Every field defaults to `None` so `ArtifactProvenance()` IS the "not
+    reported" value -- there is no second spelling of absence to keep in sync,
+    and a caller with no table at hand (`UNKNOWN` below) produces exactly what
+    a caller holding a table with no entry for its tool does.
+    """
+
+    tier: str | None = None
+    licence: str | None = None
+    source_url: str | None = None
+    size_bytes: int | None = None
+
+    def as_dict(self) -> dict[str, str | int | None]:
+        """The four keys as `missingPrerequisites[]` carries them. Always all
+        four, always in this order -- see the module docstring on absence."""
+        return {
+            "tier": self.tier,
+            "licence": self.licence,
+            "sourceUrl": self.source_url,
+            "sizeBytes": self.size_bytes,
+        }
+
+
+#: The "nothing reported" provenance: an SDK predating `artifactProvenance`, a
+#: tool with no entry in it (`west`, `zephyrSdk`, `setools`, `jlink` and
+#: `python3-venv` all have none today), or an entry too malformed to read.
+UNKNOWN = ArtifactProvenance()
+
+
+def _text(value: Any) -> str | None:
+    """A string field, or `None` for anything else -- including a number, a
+    `null` alp-sdk wrote deliberately (`xz`/`7zip`'s `licence`), and a nested
+    object. No `str()` coercion: rendering `{'a': 1}` as a licence in a consent
+    screen would be an invented fact, which is the one thing this must not do."""
+    return value if isinstance(value, str) else None
+
+
+def _count(value: Any) -> int | None:
+    """A byte count, or `None`. `bool` is excluded explicitly for the reason
+    the sibling readers exclude it (`parse_bootstrap_manifest`, `_load_manifest`):
+    `True == 1` in Python, so `"sizeBytes": true` would otherwise report a size
+    of one byte. A float is rejected rather than truncated -- alp-sdk emits
+    `null` or an integer, and a truncation here would be tan inventing a
+    precision the manifest never claimed.
+
+    A NEGATIVE int is refused for the same reason as the float: `-4096` is not
+    a download size, and rendering "-4 KB" on a consent screen is the same
+    class of nonsense as rendering a truncated float. `0` is kept -- an empty
+    artefact is silly but arithmetically meaningful, and `null` already exists
+    for "not reported", so coercing `0` would erase a distinction the manifest
+    can actually draw."""
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        return None
+    return value
+
+
+def entry_from_doc(doc: Any) -> ArtifactProvenance:
+    """One `artifactProvenance[<tool>]` value, normalised. Anything that is not
+    a mapping (a bare string, a list, `null`) yields `UNKNOWN` rather than
+    raising -- see the module docstring."""
+    if not isinstance(doc, dict):
+        return UNKNOWN
+    return ArtifactProvenance(
+        tier=_text(doc.get("tier")),
+        licence=_text(doc.get("licence")),
+        source_url=_text(doc.get(SDK_SOURCE_KEY)),
+        size_bytes=_count(doc.get("sizeBytes")),
+    )
+
+
+def parse_table(raw: Any) -> dict[str, ArtifactProvenance]:
+    """The whole `artifactProvenance` block, normalised to `tool ->
+    ArtifactProvenance`.
+
+    `{}` for an absent block, a block that is not a mapping, or one whose every
+    entry is unreadable -- all four of which are the same fact downstream
+    ("nothing to report"), and none of which is an error here. A non-string key
+    is dropped: `missingPrerequisites[].tool` is a string, so a key that could
+    never match one carries no information and keeping it would only widen this
+    return type for a lookup that cannot hit.
+    """
+    if not isinstance(raw, dict):
+        return {}
+    return {
+        tool: entry_from_doc(doc) for tool, doc in raw.items() if isinstance(tool, str)
+    }
+
+
+def _entry_problems(tool: str, entry: Any) -> list[str]:
+    """One tool's row: everything the manifest DECLARED there that the real
+    readers could not read, named `<tool>.<manifest key>`.
+
+    Derived from `entry_from_doc`'s own answer rather than a second copy of the
+    type rules, so it cannot drift from what the parse actually accepts (see
+    the module docstring's "Malformed input" section)."""
+    if not isinstance(entry, dict):
+        kind = "null" if entry is None else type(entry).__name__
+        return [f"`{tool}` is {kind}, not an object"]
+    parsed = entry_from_doc(entry)
+    return [
+        f"`{tool}.{key}` is not readable ({entry[key]!r})"
+        for key, read in (
+            ("tier", parsed.tier),
+            ("licence", parsed.licence),
+            (SDK_SOURCE_KEY, parsed.source_url),
+            ("sizeBytes", parsed.size_bytes),
+        )
+        # DECLARED and unreadable. An absent key and an explicit `null` are
+        # both "not reported", the normal shape (`xz`/`7zip` licence, every
+        # `sizeBytes` today), and neither is a problem.
+        if entry.get(key) is not None and read is None
+    ]
+
+
+def problems_in(doc: dict[str, Any]) -> str | None:
+    """What in `doc`'s `artifactProvenance` block tan could not read, as ONE
+    human-readable line, or `None` when there is nothing to say.
+
+    Takes the whole parsed manifest, not the block, because the distinction it
+    draws is about the KEY: an absent `artifactProvenance` is every SDK before
+    v0.16.0 and stays silent, while a key that IS present and unreadable --
+    `"artifactProvenance": null` included, which no alp-sdk has ever emitted --
+    is a producer defect worth naming. It reports; it never refuses and never
+    changes what the entries carry. See the module docstring for why silence
+    was not an option and which channel this feeds.
+    """
+    if BLOCK_KEY not in doc:
+        return None
+    raw = doc[BLOCK_KEY]
+    if not isinstance(raw, dict):
+        kind = "null" if raw is None else type(raw).__name__
+        return f"`{BLOCK_KEY}` is {kind}, not an object"
+
+    problems: list[str] = []
+    for tool, entry in raw.items():
+        if not isinstance(tool, str):
+            problems.append(f"`{BLOCK_KEY}` has a non-string key ({tool!r})")
+            continue
+        problems.extend(_entry_problems(tool, entry))
+    if not problems:
+        return None
+    # Bounded: a wholly corrupt block would otherwise put dozens of clauses
+    # into one `doctor` line. The count stays exact, so nothing is hidden.
+    head = "; ".join(problems[:3])
+    if len(problems) > 3:
+        head += f"; and {len(problems) - 3} more"
+    return head
+
+
+def for_tool(table: dict[str, ArtifactProvenance] | None, tool: str) -> ArtifactProvenance:
+    """`table`'s entry for `tool`, or `UNKNOWN`. Takes `None` for a caller that
+    has no table at all (every pre-tan-cli#1066 call site, and every unit test
+    of the refusal builders), so "no table" and "no entry" cannot diverge."""
+    if not table:
+        return UNKNOWN
+    return table.get(tool, UNKNOWN)