chipwright 0.2.5__tar.gz → 0.2.7__tar.gz

{chipwright-0.2.5 → chipwright-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chipwright
-Version: 0.2.5
+Version: 0.2.7
 Summary: A verified package manager for Qualcomm NPUs — resolve the artifact that loads on your exact chip, run it, and prove it against a CPU reference.
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/nameissakthi25/chipwright

{chipwright-0.2.5 → chipwright-0.2.7}/chipwright/__init__.py

@@ -8,4 +8,4 @@ from .resolver import Decision, Outcome, Variant, resolve
 from .tags import ArtifactTag
 
 __all__ = ["TargetKey", "probe", "Registry", "Decision", "Outcome", "Variant", "resolve", "ArtifactTag"]
-__version__ = "0.2.5"
+__version__ = "0.2.7"

{chipwright-0.2.5 → chipwright-0.2.7}/chipwright/cli.py

@@ -234,7 +234,8 @@ def cmd_resolve(args):
     if args.model not in reg.models():
         return _unknown_model(args, reg)
     target = _get_target(args)
-    d = resolve(target, reg.variants(args.model), args.quant, args.shape)
+    d = resolve(target, reg.variants(args.model), args.quant, args.shape,
+                want_runtime=getattr(args, "runtime", None), priority=getattr(args, "priority", None))
     if getattr(args, "json", False):
         _emit_json(jsonout.decision_to_dict(args.model, target, d))
     else:
@@ -303,6 +304,42 @@ def cmd_verify(args):
     return _replay(reg, args.model)
 
 
+def _render_run_report(rep, d):
+    """Print a run's verification report (human door) and return its exit code. Shape-safe: the LLM
+    generative gate reports a `tripwire` (token-match), CV/ASR a cosine — the human door must not diverge
+    from the already-shape-safe `--json` projection (Principle IV, and never a KeyError traceback)."""
+    if rep.get("runtime") == "llamacpp-htp":     # runtime path: a silicon record + the host recipe (FR-RT07)
+        rec = rep.get("record") or {}
+        d_ = rec.get("dispatch") or {}
+        q_ = rec.get("quality") or {}
+        print(f"\n{GREEN}✔ cached + hash-verified{RST}  {rep.get('artifact')}")
+        print(f"{YELLOW}runtime = llamacpp-htp{RST}  (on-device execution via the recipe below — not the Genie transport)")
+        if d_:
+            print(f"    on-silicon record ({rec.get('board')}, {rec.get('htp_arch')}, {rec.get('date')}): "
+                  f"Q8_0 dispatched to HTP0 — prefill {d_.get('htp0_prefill_tps')} vs CPU "
+                  f"{d_.get('cpu_prefill_tps')} t/s = {d_.get('prefill_speedup')}×")
+        if q_:
+            print(f"    quality: PPL(WikiText) = {q_.get('ppl_wikitext_q8_0')} (near-lossless)")
+        print(f"    recipe: ADSP_LIBRARY_PATH=<lib> " + " ".join(rep.get("recipe") or []))
+        if rep.get("warn"):
+            print(f"{DIM}    note: {rep['warn']}{RST}")
+        return jsonout.EXIT_USE_WITH_WARN
+    mark = f"{GREEN}✔ VERIFIED{RST}" if rep["pass"] else f"{RED}✗ MISMATCH{RST}"
+    if "tripwire" in rep:                        # LLM generative gate (token-match), not a cosine
+        tw = rep["tripwire"]
+        thr = (tw.get("thresholds") or {}).get("token_match")
+        print(f"\n{mark}  generative gate  token_match = {float(tw.get('token_match', 0.0)):.5f}"
+              + (f"  (threshold {thr})" if thr is not None else ""))
+        if rep.get("behavior"):
+            print(f"    behavioral probe: {rep['behavior']}")
+    else:
+        print(f"\n{mark}  NPU vs CPU-reference  cosine_min = {rep['cosine_min']:.5f}  "
+              f"(threshold {rep['threshold']})")
+        for name, c in rep["per_output"].items():
+            print(f"    {name}: {c:.5f}")
+    return jsonout.exit_code_for(d) if rep["pass"] else jsonout.EXIT_VERIFY_MISMATCH
+
+
 def cmd_run(args):
     reg = Registry(args.registry)
     if args.model not in reg.models():
@@ -312,7 +349,8 @@ def cmd_run(args):
     target = _get_target(args)
     if getattr(args, "json", False):
         return _run_json(args, reg, target)
-    d = resolve(target, reg.variants(args.model), args.quant, args.shape)
+    d = resolve(target, reg.variants(args.model), args.quant, args.shape,
+                want_runtime=getattr(args, "runtime", None), priority=getattr(args, "priority", None))
     _print_decision(args.model, target, d)
     if not d.ok:
         if d.outcome == Outcome.BUILD:
@@ -320,7 +358,9 @@ def cmd_run(args):
         return jsonout.exit_code_for(d)
     # USE / USE_WITH_WARN: execute on the board and verify against a CPU reference.
     v = d.variant
-    if not (v.run and v.run.get("modality")):
+    # the llama.cpp-HTP runtime has its own run path (fetch + silicon record + recipe, FR-RT07) and no
+    # cosine run block — route it through run_variant instead of the no-run-block short-circuit.
+    if not (v.run and v.run.get("modality")) and v.effective_runtime != "llamacpp-htp":
         print(f"{DIM}artifact resolves, but this variant has no run block (modality/meta/cpu_onnx) — "
               f"resolve-only.{RST}")
         if v.url:
@@ -333,12 +373,7 @@ def cmd_run(args):
     except Exception as e:
         print(f"{RED}run failed:{RST} {e}")
         return jsonout.EXIT_UNEXPECTED
-    mark = f"{GREEN}✔ VERIFIED{RST}" if rep["pass"] else f"{RED}✗ MISMATCH{RST}"
-    print(f"\n{mark}  NPU vs CPU-reference  cosine_min = {rep['cosine_min']:.5f}  "
-          f"(threshold {rep['threshold']})")
-    for name, c in rep["per_output"].items():
-        print(f"    {name}: {c:.5f}")
-    return jsonout.exit_code_for(d) if rep["pass"] else jsonout.EXIT_VERIFY_MISMATCH
+    return _render_run_report(rep, d)
 
 
 def _run_json(args, reg, target) -> int:
@@ -348,13 +383,14 @@ def _run_json(args, reg, target) -> int:
     """
     # Everything human — the decision render and the runner's progress lines — to stderr.
     with contextlib.redirect_stdout(sys.stderr):
-        d = resolve(target, reg.variants(args.model), args.quant, args.shape)
+        d = resolve(target, reg.variants(args.model), args.quant, args.shape,
+                want_runtime=getattr(args, "runtime", None), priority=getattr(args, "priority", None))
         _print_decision(args.model, target, d)
         if not d.ok:
             doc, code = jsonout.decision_to_dict(args.model, target, d), jsonout.exit_code_for(d)
         else:
             v = d.variant
-            if not (v.run and v.run.get("modality")):
+            if not (v.run and v.run.get("modality")) and v.effective_runtime != "llamacpp-htp":
                 print(f"artifact resolves, but this variant has no run block — resolve-only.")
                 doc = jsonout.decision_to_dict(args.model, target, d)
                 doc["verified"] = None
@@ -363,7 +399,10 @@ def _run_json(args, reg, target) -> int:
                 from . import run as runner
                 rep = runner.run_variant(v, args.input)   # may raise → caught by the --json wrapper in main
                 doc = jsonout.run_to_dict(args.model, target, d, rep)
-                code = jsonout.exit_code_for(d) if rep.get("pass") else jsonout.EXIT_VERIFY_MISMATCH
+                if rep.get("runtime") == "llamacpp-htp":
+                    code = jsonout.EXIT_USE_WITH_WARN     # usable, with the documented recipe caveat (FR-RT07)
+                else:
+                    code = jsonout.exit_code_for(d) if rep.get("pass") else jsonout.EXIT_VERIFY_MISMATCH
     _emit_json(doc)
     return code
 
@@ -422,7 +461,8 @@ def cmd_build(args):
     if args.model not in reg.models():
         return _unknown_model(args, reg)
     target = _get_target(args)
-    d = resolve(target, reg.variants(args.model), args.quant, args.shape)
+    d = resolve(target, reg.variants(args.model), args.quant, args.shape,
+                want_runtime=getattr(args, "runtime", None), priority=getattr(args, "priority", None))
     _print_decision(args.model, target, d)
     if d.ok:
         print(f"{DIM}already resolves to USE — nothing to build.{RST}")
@@ -486,6 +526,9 @@ def main(argv=None):
     ap.add_argument("--target", help="offline target, e.g. 'htpv68,qnn2.37'")
     ap.add_argument("--quant", help="narrow to a quant, e.g. w8a16")
     ap.add_argument("--shape", help="narrow to a shape profile, e.g. win30s")
+    ap.add_argument("--runtime", help="pick an inference runtime, e.g. llamacpp-htp (default: the genie floor)")
+    ap.add_argument("--priority", choices=["quality", "decode-latency"],
+                    help="when a model spans runtimes, prefer quality (llamacpp-htp) or decode-latency (genie)")
     ap.add_argument("--json", action="store_true",
                     help="emit one JSON document to stdout (resolve/run/list); human text → stderr, "
                          "always plain. Exit codes follow the table below.")

{chipwright-0.2.5 → chipwright-0.2.7}/chipwright/data/index.yaml

@@ -142,6 +142,50 @@ models:
     sdk_compatible: '>=2.34,<2.40'
     ext: qnnctx
     recipe: recipes/qwen2.5-1.5b/1.0.0.yaml
+  # The llama.cpp-HTP runtime variant — a >4-bit integer route (Q8_0) that classic Genie structurally
+  # lacks. Silicon-verified on v73 (spec 004 Track 2). On-device execution is via the documented
+  # llama.cpp-HTP recipe (staged glibc loader + ADSP_LIBRARY_PATH + libggml-htp-v73.so); chipwright-run
+  # CLI integration for this runtime is pending (T-RT11), so `run` here fetches + hash-verifies the GGUF
+  # and surfaces the recipe + this record (FR-RT07), rather than driving the board itself.
+  - arch: v73
+    quant: Q8_0
+    shape: ctx4096
+    runtime: llamacpp-htp
+    sdk_tested: b3278e921
+    sdk_compatible: llama.cpp-HTP (no QAIRT dependency)
+    ext: gguf
+    url: https://huggingface.co/nameissakthi/chipwright-llm/resolve/main/qwen2.5-1.5b-Q8_0.gguf
+    sha256: cedde4175edae2e9467d8b98d70843e57c8fb101afd54ca773bce022e80f7e4e
+    runtime_support:
+      llamacpp-htp:
+        v68: 'unsupported:needs-v73-or-newer-hexagon'
+        v73: supported
+      genie:
+        v68: supported
+        v73: supported
+    verified:
+      'on': QCS9075 (Dragonwing IQ-9075, soc_id 676, Hexagon v73)
+      date: 2026-10-24
+      loads: true
+      runtime: llamacpp-htp
+      vs_reference:
+        backend: llama.cpp-cpu (same Q8_0 GGUF, GGML_HEXAGON_NDEV=0)
+        metric: dispatch+ppl
+        dispatch:
+          device: HTP0
+          htp0_prefill_tps: 592.82
+          cpu_prefill_tps: 217.55
+          prefill_speedup: 2.72
+          note: Q8_0 MUL_MAT dispatched to HTP0 on the compute-DSP (_dom=cdsp), not CPU fallback (SC-RT03)
+        quality:
+          metric: ppl_wikitext
+          chunks: 16
+          ppl_q8_0: 11.6631
+          ppl_stderr: 0.49427
+          ppl_f16_baseline: 11.6388
+          note: near-lossless vs the model's own f16
+        llamacpp_build: b3278e921
+      note: the >4-bit integer route Genie lacks; on-device exec via the llama.cpp-HTP recipe (CLI integration T-RT11)
 - model: qwen2.5-7b-instruct
   source: Qwen/Qwen2.5-7B-Instruct
   license: apache-2.0

{chipwright-0.2.5 → chipwright-0.2.7}/chipwright/jsonout.py

@@ -100,6 +100,13 @@ def run_to_dict(model: str, target, d: Decision, report: dict) -> dict:
     rec["outputs"] = dict(report.get("per_output") or {})
     if "tripwire" in report:           # LLM path: a generative tripwire, not a cosine
         rec["tripwire"] = report["tripwire"]
+    if report.get("runtime") == "llamacpp-htp":   # runtime path: a silicon record + the host recipe
+        rec["runtime"] = report["runtime"]
+        rec["record"] = report.get("record")
+        rec["recipe"] = report.get("recipe")
+        rec["cli_execution"] = report.get("cli_execution")
+        if report.get("warn"):
+            rec.setdefault("warnings", []).append(report["warn"])
     return rec
 
 

{chipwright-0.2.5 → chipwright-0.2.7}/chipwright/recipe.py

@@ -23,6 +23,13 @@ RUNS_ON = ("npu", "host")
 # through to the resolver's refusal verbatim.
 _PRECISION_KINDS = ("supported", "blocked", "unsupported")
 
+# Runtime-support statuses a recipe may declare (spec 004, FR-RT04). The runtime axis is the precision
+# axis a second time — the same {key: "supported" | "<kind>:<reason>"} matrix the resolver already refuses
+# on — only one level deeper, because a runtime's support is *per arch*: `{runtime: {arch: status}}`. A
+# status is the bare word "supported", or "deprecated:<successor>" (runnable, but deprecating upstream —
+# resolve warns), or "unsupported:<reason>" (the board's arch cannot host it — resolve refuses by name).
+_RUNTIME_KINDS = ("supported", "deprecated", "unsupported")
+
 
 @dataclass
 class Source:
@@ -86,6 +93,7 @@ class Recipe:
     host: Host = field(default_factory=Host)
     graphs: List[Graph] = field(default_factory=list)
     precision_support: Dict[str, str] = field(default_factory=dict)  # {precision: status} — LLM, FR-L06
+    runtime_support: Dict[str, Dict[str, str]] = field(default_factory=dict)  # {runtime: {arch: status}} — FR-RT04
 
     @property
     def quant_tag(self) -> str:
@@ -101,6 +109,15 @@ class Recipe:
         """The precisions this recipe declares runnable through the pipeline."""
         return [p for p, s in self.precision_support.items() if s == "supported"]
 
+    def runtime_status(self, runtime: str, arch: str) -> Optional[str]:
+        """The declared status for `runtime` on `arch` ('supported'/'deprecated:<s>'/'unsupported:<r>'), or None."""
+        return self.runtime_support.get(runtime, {}).get(arch)
+
+    def runnable_runtimes(self, arch: str) -> List[str]:
+        """The runtimes this recipe declares runnable on `arch` — 'supported' OR 'deprecated' (not 'unsupported')."""
+        return sorted(rt for rt, am in self.runtime_support.items()
+                      if str(am.get(arch, "")).split(":", 1)[0] in ("supported", "deprecated"))
+
     def adaptation(self, kind: str) -> Optional[Adaptation]:
         """The declared adaptation of a given kind, or None (e.g. recipe.adaptation('erf_to_tanh'))."""
         return next((a for a in self.adaptations if a.kind == kind), None)
@@ -153,6 +170,41 @@ def _parse_precision_support(items: Any) -> Dict[str, str]:
     return out
 
 
+def _parse_runtime_support(items: Any) -> Dict[str, Dict[str, str]]:
+    """Parse + validate `runtime_support:` — a nested map {runtime: {arch: status}}. Raises ValueError if malformed.
+
+    A near-clone of `_parse_precision_support`, one level deeper (runtime -> arch -> status) because a
+    runtime's support is per-arch. A status must be "supported" or "<deprecated|unsupported>:<tail>" with a
+    non-empty tail (the successor for `deprecated`, the reason for `unsupported`) — so a recipe cannot smuggle
+    in a vague "no": a limitation is named or it is not a valid recipe (the same strictness as the tag grammar).
+    """
+    if not items:
+        return {}
+    if not isinstance(items, dict):
+        raise ValueError(f"runtime_support must be a mapping {{runtime: {{arch: status}}}}, got {type(items).__name__}")
+    out: Dict[str, Dict[str, str]] = {}
+    for runtime, archmap in items.items():
+        if not isinstance(archmap, dict):
+            raise ValueError(
+                f"runtime_support[{runtime!r}] must be a mapping {{arch: status}}, got {type(archmap).__name__}")
+        per_arch: Dict[str, str] = {}
+        for arch, status in archmap.items():
+            status = str(status)
+            head = status.split(":", 1)[0]
+            if head not in _RUNTIME_KINDS:
+                raise ValueError(
+                    f"runtime_support[{runtime!r}][{arch!r}] = {status!r}: status must start with one of "
+                    f"{_RUNTIME_KINDS} (e.g. 'supported' or 'unsupported:htp-backend-excludes-v68')")
+            if head != "supported" and (":" not in status or not status.split(":", 1)[1].strip()):
+                raise ValueError(
+                    f"runtime_support[{runtime!r}][{arch!r}] = {status!r}: a {head!r} status must name a "
+                    f"reason/successor after the colon (e.g. 'deprecated:geniex-qairt' or "
+                    f"'unsupported:htp-backend-excludes-v68'); only 'supported' stands alone")
+            per_arch[str(arch)] = status
+        out[str(runtime)] = per_arch
+    return out
+
+
 def from_dict(doc: Dict[str, Any]) -> Recipe:
     """Build a Recipe from an already-parsed YAML mapping. Pure — no I/O. Raises ValueError if malformed."""
     if not isinstance(doc, dict):
@@ -195,7 +247,8 @@ def from_dict(doc: Dict[str, Any]) -> Recipe:
     return Recipe(name=str(doc["name"]), version=str(doc["version"]), route=route,
                   source=source, target=target, adaptations=_parse_adaptations(doc.get("adaptations")),
                   quant=quant, host=host, graphs=graphs,
-                  precision_support=_parse_precision_support(doc.get("precision_support")))
+                  precision_support=_parse_precision_support(doc.get("precision_support")),
+                  runtime_support=_parse_runtime_support(doc.get("runtime_support")))
 
 
 def load(path: str) -> Recipe:

{chipwright-0.2.5 → chipwright-0.2.7}/chipwright/registry.py

@@ -57,6 +57,8 @@ class Registry:
                     url=v.get("url"), sha256=v.get("sha256"),
                     local=v.get("local"), run=v.get("run"),
                     recipe=v.get("recipe"), verified=v.get("verified"),
+                    runtime=v.get("runtime"), runtime_support=v.get("runtime_support"),
+                    precision_support=v.get("precision_support"),
                 ))
             self._models[model] = vs
 

chipwright-0.2.7/chipwright/resolver.py

@@ -0,0 +1,336 @@
+"""Resolver — match registry variants against a board's TargetKey, with an explicit miss path.
+
+The resolution rules, in order:
+
+  1. Exact match on arch, quant, shape; SDK inside the compatible range  -> USE
+  2. Match, but SDK outside the tested point (still in range)            -> USE_WITH_WARN
+  3. No artifact, but a recipe whose target can be built                 -> BUILD (offer, estimate)
+  4. Nothing                                                             -> FAIL, name the axis
+
+Never silently downgrade to a near-miss artifact. The arch axis is hard (a mismatch fails at load);
+the SDK axis is a range, not a point (warn outside the tested point, don't refuse).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import List, Optional
+
+from .env import TargetKey
+
+
+class Outcome(Enum):
+    USE = "use"                   # exact match — run it
+    USE_WITH_WARN = "use_warn"    # in-range but outside the tested SDK point
+    BUILD = "build"               # no artifact, but a recipe can produce one
+    FAIL = "fail"                 # nothing — the named axis is why
+
+
+@dataclass
+class Variant:
+    """One build variant from the registry (the registry's unit is a variant, not a model)."""
+    model: str
+    version: str
+    arch: str
+    quant: str
+    shape: str
+    sdk_tested: str                      # e.g. "2.37.1"
+    sdk_compatible: str                  # e.g. ">=2.34,<2.40"
+    ext: str = "qnnctx"
+    url: Optional[str] = None            # present => a built artifact exists (remote)
+    sha256: Optional[str] = None
+    local: Optional[str] = None          # present => an artifact file on disk (not yet hosted)
+    run: Optional[dict] = None           # how `run` executes it: {modality, meta, cpu_onnx, board_name, input}
+    recipe: Optional[str] = None         # present => can be built when no artifact matches
+    verified: Optional[dict] = None      # the verification record (loads / cosine / task / latency)
+    precision_support: Optional[dict] = None  # LLM: {precision: "supported"|"blocked:<r>"|"unsupported:<r>"}
+    runtime: Optional[str] = None        # the inference runtime this variant binds to (None => classic genie)
+    runtime_support: Optional[dict] = None    # {runtime: {arch: "supported"|"deprecated:<s>"|"unsupported:<r>"}} — FR-RT04
+
+    @property
+    def has_artifact(self) -> bool:
+        return bool(self.url or self.local)
+
+    @property
+    def effective_runtime(self) -> str:
+        """The runtime this variant runs on. Historically every variant silently assumed classic Genie
+        (spec 004), so an unset runtime IS `genie` — the deprecating-but-default floor."""
+        return self.runtime or "genie"
+
+    @property
+    def has_recipe(self) -> bool:
+        return bool(self.recipe)
+
+
+@dataclass
+class Decision:
+    outcome: Outcome
+    variant: Optional[Variant] = None
+    reason: str = ""
+    axis: Optional[str] = None        # on FAIL: which axis could not be satisfied
+    warning: Optional[str] = None     # on USE_WITH_WARN
+
+    @property
+    def ok(self) -> bool:
+        return self.outcome in (Outcome.USE, Outcome.USE_WITH_WARN)
+
+
+# --- precision-support axis (LLM) -------------------------------------------------------------
+# Not every precision survives the qai-hub -> Genie pipeline (spec 002, FR-L06): w4a16 is supported,
+# w8a16 is blocked on a KV-cache-encoding divergence at convert, fp16 is unsupported because Genie's
+# transformer path is integer-only. A recipe declares this per model; `resolve` refuses a non-supported
+# precision and NAMES the reason — the same discipline as FAIL-names-the-axis, applied one axis earlier.
+_SUPPORTED = "supported"
+
+
+def precision_refusal(precision: Optional[str], support: Optional[dict]) -> Optional[str]:
+    """Return the named reason to refuse `precision`, or None if it is supported / not constrained.
+
+    Pure and tiny so it is trivial to test. A precision absent from the matrix is *not* refused here
+    (the matrix only constrains what it declares); the normal variant/quant matching handles the rest.
+    A declared non-"supported" status (e.g. "blocked:kv-cache-encoding") is returned verbatim so the
+    caller can quote the reason by name.
+    """
+    if not precision or not support:
+        return None
+    status = support.get(precision)
+    if status is None or status == _SUPPORTED:
+        return None
+    return str(status)
+
+
+# --- runtime axis (spec 004) ------------------------------------------------------------------
+# The same shape as precision, one axis over. A model+board can be served by different inference runtimes
+# ({genie, geniex-qairt, llamacpp-htp}) with genuinely different arch + precision support (classic Genie is
+# w4a16-only and deprecating; the llama.cpp HTP backend does Q4_0/Q8_0 on v73+ but NOT v68). So `resolve`
+# must (a) refuse a runtime the board's arch cannot host, BY NAME (`axis=runtime`), and (b) among the
+# runtimes the board CAN host, pick the one matching the caller's priority. The support table is per-arch:
+# `{runtime: {arch: status}}`, validated in recipe.py (`_parse_runtime_support`).
+#
+# Priority -> the order runtimes are preferred in, among those runnable on the board's arch. Grounded in the
+# v73 measurement: llamacpp-htp Q8_0 is the quality/prefill win (WikiText PPL 11.66, near-lossless, the
+# >4-bit integer route Genie structurally lacks) but regresses decode (14.4 vs 22.5 tok/s); genie w4a16 is
+# the decode win and the default floor. So quality-first prefers llamacpp-htp, decode-latency-first prefers
+# genie, and the no-priority default is the conservative floor (genie) with a warn to choose explicitly.
+_RUNTIME_PRIORITY = {
+    "quality":        ("llamacpp-htp", "geniex-qairt", "genie"),
+    "decode-latency": ("genie", "geniex-qairt", "llamacpp-htp"),
+}
+_DEFAULT_RUNTIME_ORDER = ("genie", "geniex-qairt", "llamacpp-htp")
+_RUNNABLE = ("supported", "deprecated")   # 'unsupported' is the only hard refusal; 'deprecated' still runs
+
+
+def runtime_refusal(runtime: Optional[str], arch: str, support: Optional[dict]) -> Optional[str]:
+    """Return the named reason to refuse `runtime` on `arch`, or None if it is runnable / not constrained.
+
+    Pure and tiny, mirroring `precision_refusal`. A runtime absent from the matrix (or an arch the matrix
+    doesn't declare for it) is *not* refused here — the matrix only constrains what it declares. Only an
+    explicit `unsupported:<reason>` is a refusal; a `deprecated:<successor>` status still runs (resolve warns).
+    """
+    if not runtime or not support:
+        return None
+    archmap = support.get(runtime)
+    if not isinstance(archmap, dict):
+        return None
+    status = archmap.get(arch)
+    if status is None or str(status).split(":", 1)[0] != "unsupported":
+        return None
+    return str(status)
+
+
+def runnable_runtimes(arch: str, support: Optional[dict]) -> List[str]:
+    """The runtimes the matrix declares runnable on `arch` (status 'supported' or 'deprecated')."""
+    if not support:
+        return []
+    return sorted(rt for rt, am in support.items()
+                  if isinstance(am, dict) and str(am.get(arch, "")).split(":", 1)[0] in _RUNNABLE)
+
+
+def pick_runtime(runtimes: List[str], priority: Optional[str]):
+    """Choose one runtime from `runtimes` (all runnable on the board's arch) by `priority`.
+
+    Returns (chosen, note). `note` records the trade-off (which runtime was chosen over which) so the
+    Decision can carry it — tested-is-a-record, now across runtimes.
+    """
+    order = _RUNTIME_PRIORITY.get(priority)
+    if order:
+        for rt in order:
+            if rt in runtimes:
+                others = [r for r in runtimes if r != rt]
+                return rt, f"priority={priority}: chose runtime {rt} over {others}"
+    # no (or unknown) priority -> the conservative default floor, and say how to choose
+    for rt in _DEFAULT_RUNTIME_ORDER:
+        if rt in runtimes:
+            others = [r for r in runtimes if r != rt]
+            return rt, (f"multiple runtimes available {sorted(runtimes)}; defaulted to {rt} "
+                        f"(pass priority=quality|decode-latency to choose)" + (f"; alternatives {others}" if others else ""))
+    rt = sorted(runtimes)[0]                      # only unrecognised runtimes present
+    return rt, f"multiple runtimes {sorted(runtimes)}; defaulted to {rt}"
+
+
+def _merge_warn(*parts: Optional[str]) -> Optional[str]:
+    """Join the non-empty warning fragments, or None."""
+    return " | ".join(p for p in parts if p) or None
+
+
+# --- tiny semver range check (enough for QAIRT x.y.z) -----------------------------------------
+def _ver(v: str):
+    return tuple(int(x) for x in (v.split("-")[0].split("+")[0].split(".") + ["0", "0"])[:3])
+
+
+def _in_range(point: str, rng: str) -> bool:
+    """point like '2.37.1' against a comma range like '>=2.34,<2.40'."""
+    p = _ver(point)
+    for clause in rng.split(","):
+        clause = clause.strip()
+        for op in (">=", "<=", "==", ">", "<"):
+            if clause.startswith(op):
+                bound = _ver(clause[len(op):])
+                ok = {">=": p >= bound, "<=": p <= bound, "==": p == bound,
+                      ">": p > bound, "<": p < bound}[op]
+                if not ok:
+                    return False
+                break
+    return True
+
+
+def resolve(target: TargetKey, variants: List[Variant],
+            want_quant: Optional[str] = None, want_shape: Optional[str] = None,
+            precision_support: Optional[dict] = None,
+            want_runtime: Optional[str] = None, priority: Optional[str] = None,
+            runtime_support: Optional[dict] = None) -> Decision:
+    """Return the single Decision for this board. Pure function — easy to test without a board."""
+    if not variants:
+        return Decision(Outcome.FAIL, reason="no variants registered for this model", axis="model")
+
+    # The runtime-support matrix may be passed explicitly (e.g. straight from the recipe) or carried on the
+    # variants (the registry populates it). Resolve it once so both the refusal and the selection use it.
+    rsupport = runtime_support
+    if rsupport is None:
+        rsupport = next((v.runtime_support for v in variants if v.runtime_support), None)
+
+    # Axis 0b (runtime refusal): mirror the precision refusal one axis over. If the caller names a runtime
+    # the board's arch cannot host, refuse up front and NAME it — listing the runtimes that ARE runnable on
+    # this arch — before arch/SDK matching, because the runtime is unavailable on this silicon regardless of
+    # which artifact is in hand (FAIL-names-the-axis, FR-RT03 / SC-RT02).
+    if want_runtime:
+        reason = runtime_refusal(want_runtime, target.htp_arch, rsupport)
+        if reason:
+            ok = runnable_runtimes(target.htp_arch, rsupport)
+            return Decision(Outcome.FAIL, axis="runtime",
+                            reason=f"runtime {want_runtime} is not available on {target.htp_arch}: {reason} "
+                                   f"(supported on {target.htp_arch}: {ok})")
+
+    # Axis 0 (LLM precision-support): if the caller asked for a precision the model declares as
+    # blocked/unsupported, refuse up front and name the reason — before arch/SDK matching, because the
+    # precision is unavailable through the pipeline regardless of which board is in hand. The matrix may
+    # be passed explicitly or carried on the variants (the registry populates it per model).
+    if want_quant:
+        support = precision_support
+        if support is None:
+            support = next((v.precision_support for v in variants if v.precision_support), None)
+        reason = precision_refusal(want_quant, support)
+        if reason:
+            return Decision(Outcome.FAIL, axis="precision",
+                            reason=f"precision {want_quant} is not available: {reason}")
+
+    # Axis 1 (hard): Hexagon architecture must match exactly, or the binary fails at load.
+    arch_ok = [v for v in variants if v.arch == target.htp_arch]
+    if not arch_ok:
+        have = sorted({v.arch for v in variants})
+        return Decision(Outcome.FAIL, axis="htp_arch",
+                        reason=f"no variant for arch {target.htp_arch}; registry has {have}")
+
+    # Optional narrowing on quant / shape when the caller asked for a specific one.
+    cand = arch_ok
+    if want_quant:
+        c2 = [v for v in cand if v.quant == want_quant]
+        if not c2:
+            have = sorted({v.quant for v in cand})
+            return Decision(Outcome.FAIL, axis="quant",
+                            reason=f"no {want_quant} for {target.htp_arch}; have {have}")
+        cand = c2
+    if want_shape:
+        c2 = [v for v in cand if v.shape == want_shape]
+        if not c2:
+            have = sorted({v.shape for v in cand})
+            return Decision(Outcome.FAIL, axis="shape",
+                            reason=f"no shape {want_shape} for {target.htp_arch}; have {have}")
+        cand = c2
+
+    # Runtime axis (spec 004): pick WHICH runtime among the candidates runnable on this board's arch.
+    # If the caller named a runtime, narrow to it (its refusal was already handled above). Otherwise, only
+    # when the candidates span more than one runtime do we choose by priority — a single-runtime model
+    # resolves exactly as before, so nothing that pre-dates the runtime axis changes behaviour.
+    runtime_warning = None
+    if want_runtime:
+        c2 = [v for v in cand if v.effective_runtime == want_runtime]
+        if not c2:
+            have = sorted({v.effective_runtime for v in cand})
+            return Decision(Outcome.FAIL, axis="runtime",
+                            reason=f"runtime {want_runtime} has no variant for {target.htp_arch}; have {have}")
+        cand = c2
+    else:
+        runtimes_here = sorted({v.effective_runtime for v in cand})
+        if len(runtimes_here) > 1:
+            chosen, runtime_warning = pick_runtime(runtimes_here, priority)
+            cand = [v for v in cand if v.effective_runtime == chosen]
+    # Warn if the chosen runtime is marked deprecated on this arch (its successor is named in the matrix).
+    if rsupport and cand:
+        dep = rsupport.get(cand[0].effective_runtime, {})
+        dep = dep.get(target.htp_arch, "") if isinstance(dep, dict) else ""
+        if str(dep).split(":", 1)[0] == "deprecated":
+            runtime_warning = _merge_warn(runtime_warning,
+                                          f"runtime {cand[0].effective_runtime} on {target.htp_arch} is {dep}")
+
+    built = [v for v in cand if v.has_artifact]
+
+    # The QAIRT SDK range is a genie/QNN concept — a GGUF on the llama.cpp-HTP runtime has no QAIRT
+    # dependency, its "sdk" is the llama.cpp build, which is not comparable to the board's QAIRT. So skip
+    # the QAIRT axis for it: a matching built artifact on this arch is USE (carry any runtime warning).
+    if built and built[0].effective_runtime == "llamacpp-htp":
+        v = built[0]
+        if runtime_warning:
+            return Decision(Outcome.USE_WITH_WARN, variant=v, warning=runtime_warning,
+                            reason=f"artifact matches arch/quant/shape; runtime llamacpp-htp (llama.cpp {v.sdk_tested})")
+        return Decision(Outcome.USE, variant=v,
+                        reason=f"artifact matches arch/quant/shape; runtime llamacpp-htp (llama.cpp {v.sdk_tested})")
+
+    # Axis: SDK range. If we don't know the board's QAIRT (offline), we can't check the point —
+    # prefer a built artifact and warn that the SDK match is unverified.
+    if built:
+        if target.qairt is None:
+            v = built[0]
+            return Decision(Outcome.USE_WITH_WARN, variant=v,
+                            warning=_merge_warn("board QAIRT unknown (offline) — SDK compatibility unverified",
+                                                runtime_warning),
+                            reason="artifact matches arch/quant/shape")
+        in_range = [v for v in built if _in_range(target.qairt, v.sdk_compatible)]
+        if in_range:
+            exact = [v for v in in_range if _ver(v.sdk_tested) == _ver(target.qairt)]
+            if exact:
+                return Decision(Outcome.USE, variant=exact[0], reason="exact match", warning=runtime_warning)
+            v = in_range[0]
+            return Decision(Outcome.USE_WITH_WARN, variant=v,
+                            warning=_merge_warn(f"board QAIRT {target.qairt} is in range {v.sdk_compatible} "
+                                                f"but the artifact was tested at {v.sdk_tested}", runtime_warning),
+                            reason="in-range, outside tested point")
+        # artifact exists but SDK is out of every range -> fall through to recipe/fail on the SDK axis
+        sdk_axis = True
+    else:
+        sdk_axis = False
+
+    # Axis 3: no usable artifact, but a recipe can build one for this target.
+    buildable = [v for v in cand if v.has_recipe]
+    if buildable:
+        return Decision(Outcome.BUILD, variant=buildable[0], warning=runtime_warning,
+                        reason=("no artifact matches the board SDK; a recipe can build one"
+                                if sdk_axis else "no built artifact, but a recipe exists"))
+
+    # Axis 4: nothing.
+    if sdk_axis:
+        ranges = sorted({v.sdk_compatible for v in built})
+        return Decision(Outcome.FAIL, axis="qairt",
+                        reason=f"board QAIRT {target.qairt} outside every artifact range {ranges}, and no recipe")
+    return Decision(Outcome.FAIL, axis="artifact",
+                    reason="arch matches but no artifact and no recipe for this target")