chipwright 0.2.3__tar.gz → 0.2.4__tar.gz

{chipwright-0.2.3 → chipwright-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chipwright
-Version: 0.2.3
+Version: 0.2.4
 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
@@ -161,6 +161,48 @@ That `0.95600` is not a claim in a README. It is the number Chipwright measured
 - `--target <arch[,sdk]>` — resolve **offline** against a hand-named target instead of a probed board, e.g. `--target htpv68` or `--target htpv68,qnn2.37`. The arch is required; the SDK is optional — omit it and the SDK axis is reported unverified rather than guessed. It is a global flag, so it goes before the subcommand (`chipwright --target htpv68 resolve …`).
 - `CW_REGISTRY` — point the client at an alternate index (a local path or a URL) instead of the public index bundled in the wheel. Use it to resolve/run against a dev or private registry; the author's development overlay is `registry/index.dev.yaml`.
 
+### Machine interface — `--json` and exit codes
+
+Chipwright is meant to be a CI/CD gate, so every outcome is machine-readable. `--json` is a **global flag** (it goes before the subcommand, like `--target`), and it makes `resolve` / `run` / `list` emit **exactly one JSON document to stdout and nothing else** — no colour, no human prose. Any human or progress text goes to **stderr**, so a pipeline can parse stdout cleanly:
+
+```bash
+$ chipwright --target htpv68 --json resolve mobilenet-v2 | jq -e '.outcome'
+"USE_WITH_WARN"
+```
+
+```json
+{
+  "model": "mobilenet-v2", "target": "htpv68", "outcome": "USE_WITH_WARN",
+  "variant": "mobilenet-v2-1.0.0", "arch": "v68", "quant": "w8a16", "shape": "img224",
+  "warnings": ["board QAIRT unknown (offline) — SDK compatibility unverified"],
+  "reason": "artifact matches arch/quant/shape"
+}
+```
+
+`run` adds the verification record, so a deploy can gate on `.verified` without scraping text:
+
+```bash
+$ chipwright --json run mobilenet-v2 | jq '{verified, cosine_min, threshold}'
+{ "verified": true, "cosine_min": 0.95600, "threshold": 0.95 }
+```
+
+The **outcome is data, not a glyph** — on a `FAIL`, the failing `axis` (`htp_arch`, `qairt`, `quant`, …) is a first-class field, not a free-text reason to regex. `list` emits an array of per-variant records. Colour in the human (non-`--json`) output is gated on `stdout.isatty()` and honours `NO_COLOR` (disable) and `FORCE_COLOR=1` (enable); `--json` is always plain.
+
+Each outcome maps to its own **stable, documented exit code** (also in `chipwright --help`), so a gate can branch on the code alone — "build it" vs "never runs here" vs "FAILED the gate" are distinct:
+
+| code | meaning | when |
+| ---: | --- | --- |
+| `0`  | **USE** | exact match — run it |
+| `11` | **USE_WITH_WARN** | a match, but the board's SDK is off the tested point (still in range) |
+| `10` | **BUILD** | no artifact, but a recipe can build one |
+| `20` | **FAIL** | nothing fits — the message names the axis |
+| `30` | **VERIFY_MISMATCH** | ran, but the NPU-vs-CPU cosine fell below threshold |
+| `40` | **NOT_RUNNABLE** | resolved, but cannot execute here (no run block / no board) |
+| `2`  | usage / unknown model | a usage error |
+| `1`  | unexpected error | an internal error (in `--json` mode, still emitted as `{"error":…,"exit_code":1}`) |
+
+The codes are a **versioned contract** (`chipwright.jsonout.__api__`): a code never changes meaning without a MAJOR bump, and new outcomes take new codes. (This replaces the earlier 0/1 collapse, where BUILD, FAIL and a failed verification all exited `1` — the one deliberate behaviour change in this release.)
+
 ---
 
 ## The three verbs

{chipwright-0.2.3 → chipwright-0.2.4}/README.md

@@ -125,6 +125,48 @@ That `0.95600` is not a claim in a README. It is the number Chipwright measured
 - `--target <arch[,sdk]>` — resolve **offline** against a hand-named target instead of a probed board, e.g. `--target htpv68` or `--target htpv68,qnn2.37`. The arch is required; the SDK is optional — omit it and the SDK axis is reported unverified rather than guessed. It is a global flag, so it goes before the subcommand (`chipwright --target htpv68 resolve …`).
 - `CW_REGISTRY` — point the client at an alternate index (a local path or a URL) instead of the public index bundled in the wheel. Use it to resolve/run against a dev or private registry; the author's development overlay is `registry/index.dev.yaml`.
 
+### Machine interface — `--json` and exit codes
+
+Chipwright is meant to be a CI/CD gate, so every outcome is machine-readable. `--json` is a **global flag** (it goes before the subcommand, like `--target`), and it makes `resolve` / `run` / `list` emit **exactly one JSON document to stdout and nothing else** — no colour, no human prose. Any human or progress text goes to **stderr**, so a pipeline can parse stdout cleanly:
+
+```bash
+$ chipwright --target htpv68 --json resolve mobilenet-v2 | jq -e '.outcome'
+"USE_WITH_WARN"
+```
+
+```json
+{
+  "model": "mobilenet-v2", "target": "htpv68", "outcome": "USE_WITH_WARN",
+  "variant": "mobilenet-v2-1.0.0", "arch": "v68", "quant": "w8a16", "shape": "img224",
+  "warnings": ["board QAIRT unknown (offline) — SDK compatibility unverified"],
+  "reason": "artifact matches arch/quant/shape"
+}
+```
+
+`run` adds the verification record, so a deploy can gate on `.verified` without scraping text:
+
+```bash
+$ chipwright --json run mobilenet-v2 | jq '{verified, cosine_min, threshold}'
+{ "verified": true, "cosine_min": 0.95600, "threshold": 0.95 }
+```
+
+The **outcome is data, not a glyph** — on a `FAIL`, the failing `axis` (`htp_arch`, `qairt`, `quant`, …) is a first-class field, not a free-text reason to regex. `list` emits an array of per-variant records. Colour in the human (non-`--json`) output is gated on `stdout.isatty()` and honours `NO_COLOR` (disable) and `FORCE_COLOR=1` (enable); `--json` is always plain.
+
+Each outcome maps to its own **stable, documented exit code** (also in `chipwright --help`), so a gate can branch on the code alone — "build it" vs "never runs here" vs "FAILED the gate" are distinct:
+
+| code | meaning | when |
+| ---: | --- | --- |
+| `0`  | **USE** | exact match — run it |
+| `11` | **USE_WITH_WARN** | a match, but the board's SDK is off the tested point (still in range) |
+| `10` | **BUILD** | no artifact, but a recipe can build one |
+| `20` | **FAIL** | nothing fits — the message names the axis |
+| `30` | **VERIFY_MISMATCH** | ran, but the NPU-vs-CPU cosine fell below threshold |
+| `40` | **NOT_RUNNABLE** | resolved, but cannot execute here (no run block / no board) |
+| `2`  | usage / unknown model | a usage error |
+| `1`  | unexpected error | an internal error (in `--json` mode, still emitted as `{"error":…,"exit_code":1}`) |
+
+The codes are a **versioned contract** (`chipwright.jsonout.__api__`): a code never changes meaning without a MAJOR bump, and new outcomes take new codes. (This replaces the earlier 0/1 collapse, where BUILD, FAIL and a failed verification all exited `1` — the one deliberate behaviour change in this release.)
+
 ---
 
 ## The three verbs

{chipwright-0.2.3 → chipwright-0.2.4}/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.3"
+__version__ = "0.2.4"

{chipwright-0.2.3 → chipwright-0.2.4}/chipwright/cache.py

@@ -109,3 +109,34 @@ def fetch_named(url: str, sha256: str, name: str, sidecars=None) -> str:
         _require_sha(s_sha, "reference sidecar")
         _ensure(s_url, s_sha, os.path.join(d, _safe_name(s_name)))
     return main
+
+
+def _looks_url(s) -> bool:
+    return isinstance(s, str) and s.startswith(("http://", "https://"))
+
+
+def locate_ref(r: dict, key: str, override=None):
+    """Locate a run-block reference (cpu_onnx / input / meta): a local path, or a HOSTED url fetched into
+    the cache so a stranger's `run` works, not only the author's.
+
+    A url value is sha-verified via a companion `<key>_sha256` (refusing by name if absent — never an
+    unverified reference) and fetched with its original filename so an ONNX's external-data sidecar
+    resolves; declare sidecars under `<key>_sidecars: [{url, sha256, name}]`.
+
+    Lives here (device-free) rather than in `run.py` so both the live gate (`run.run_variant`) and the
+    offline replay (`replay.rederive`) share one reference locator without either importing the board
+    transport. `run._locate_ref` is an alias of this.
+    """
+    val = override if override is not None else r.get(key)
+    if val is None:
+        return None
+    if _looks_url(val):
+        sha = r.get(f"{key}_sha256")
+        if not sha:
+            raise RuntimeError(
+                f"run block {key} is a url but carries no {key}_sha256 — refusing to fetch an unverified "
+                f"reference (a reference the gate can't trust is worse than none).")
+        sidecars = [(s["url"], s["sha256"], s["name"]) for s in (r.get(f"{key}_sidecars") or [])]
+        name = val.rsplit("/", 1)[-1]
+        return fetch_named(val, sha, name, sidecars)
+    return os.path.expanduser(val)

{chipwright-0.2.3 → chipwright-0.2.4}/chipwright/cli.py

@@ -11,18 +11,70 @@ plainly rather than guessing.
 from __future__ import annotations
 
 import argparse
+import contextlib
 import importlib.util
+import json
 import os
 import re
 import sys
 
-from . import cache
+from . import cache, jsonout
 from .env import TargetKey, probe
 from .registry import Registry
 from .resolver import Outcome, resolve
 
+# ANSI palette. These are module globals so the whole file can keep printing with them; `_set_palette`
+# blanks them when colour is off (not a TTY / NO_COLOR / --json). The literals below are the coloured
+# default; the actual values for a given invocation are chosen in `main()`.
 GREEN, YELLOW, RED, DIM, RST = "\033[32m", "\033[33m", "\033[31m", "\033[2m", "\033[0m"
 
+
+def _color_enabled(json_mode: bool) -> bool:
+    """Should colour be emitted? (spec 006 FR-J05)
+
+    `--json` is always plain. Otherwise honour `NO_COLOR` (set → off, any value, per the no-color.org
+    convention), then `FORCE_COLOR=1` (on), else gate on whether stdout is a real TTY.
+    """
+    if json_mode:
+        return False
+    if os.environ.get("NO_COLOR") is not None:
+        return False
+    if os.environ.get("FORCE_COLOR") == "1":
+        return True
+    try:
+        return sys.stdout.isatty()
+    except Exception:
+        return False
+
+
+def _set_palette(enabled: bool):
+    """Point the module colour globals at either the ANSI codes or empty strings."""
+    global GREEN, YELLOW, RED, DIM, RST
+    if enabled:
+        GREEN, YELLOW, RED, DIM, RST = "\033[32m", "\033[33m", "\033[31m", "\033[2m", "\033[0m"
+    else:
+        GREEN = YELLOW = RED = DIM = RST = ""
+
+
+def _emit_json(obj):
+    """Write exactly one JSON document to the real stdout, and nothing else (FR-J01).
+
+    `default=str` keeps a verification record portable: YAML parses `date: 2026-10-08` into a
+    `datetime.date`, which `json` can't serialize — stringify such leaves rather than crash.
+    """
+    sys.stdout.write(json.dumps(obj, default=str))
+    sys.stdout.write("\n")
+
+
+def _unknown_model(args, reg) -> int:
+    """Report an unknown model consistently in both modes; exit code 2 (usage/unknown-model)."""
+    if getattr(args, "json", False):
+        _emit_json({"error": f"unknown model '{args.model}'. known: {', '.join(reg.models())}",
+                    "exit_code": jsonout.EXIT_USAGE})
+    else:
+        print(f"{RED}unknown model{RST} '{args.model}'. known: {', '.join(reg.models())}")
+    return jsonout.EXIT_USAGE
+
 # A bare Hexagon arch (what `list` and FAIL messages print, e.g. "v68") looks like a target but is
 # missing the mandatory `htp` prefix. Used to turn a malformed --target into a helpful suggestion.
 _ARCH_LIKE = re.compile(r"^v\d+$", re.IGNORECASE)
@@ -134,6 +186,19 @@ def cmd_doctor(args):
     return rc
 
 
+def _rederivable_note(v):
+    """A small, non-breaking annotation (spec 005 FR-RR04): is this record's headline number
+    independently re-derivable offline (NPU output pinned), or does it predate reproducible-record?
+    Returns a colored line, or None when the variant carries no verification record at all.
+    """
+    from . import replay
+    if not isinstance(v.verified, dict) or not isinstance(v.verified.get("vs_reference"), dict):
+        return None
+    if replay.is_rederivable(v):
+        return f"{GREEN}↺ independently re-derivable{RST} — chipwright run {v.model} --replay"
+    return f"{DIM}not independently re-derivable yet (record predates reproducible-record){RST}"
+
+
 def _print_decision(model, target, d):
     print(f"model   : {model}")
     print(f"target  : {target}")
@@ -143,6 +208,9 @@ def _print_decision(model, target, d):
               f"qnn{v.sdk_tested}  ({d.reason})")
         if v.verified:
             print(f"  {DIM}verified: {v.verified}{RST}")
+            note = _rederivable_note(v)
+            if note:
+                print(f"  {note}")
     elif d.outcome == Outcome.USE_WITH_WARN:
         v = d.variant
         print(f"{YELLOW}▲ USE (warn){RST}  {v.model}-{v.version}  htp{v.arch}/{v.quant}/{v.shape}")
@@ -153,6 +221,9 @@ def _print_decision(model, target, d):
         print(f"  {DIM}{d.reason}{RST}")
         if v.verified:
             print(f"  {DIM}prior verification on record: {v.verified}{RST}")
+            note = _rederivable_note(v)
+            if note:
+                print(f"  {note}")
     else:
         print(f"{RED}✗ FAIL{RST}  axis={d.axis}: {d.reason}")
     return d
@@ -161,26 +232,92 @@ def _print_decision(model, target, d):
 def cmd_resolve(args):
     reg = Registry(args.registry)
     if args.model not in reg.models():
-        print(f"{RED}unknown model{RST} '{args.model}'. known: {', '.join(reg.models())}")
-        return 2
+        return _unknown_model(args, reg)
     target = _get_target(args)
     d = resolve(target, reg.variants(args.model), args.quant, args.shape)
-    _print_decision(args.model, target, d)
-    return 0 if d.ok else 1
+    if getattr(args, "json", False):
+        _emit_json(jsonout.decision_to_dict(args.model, target, d))
+    else:
+        _print_decision(args.model, target, d)
+    return jsonout.exit_code_for(d)
 
 
-def cmd_run(args):
+def _replay(reg, model):
+    """Offline replay of a recorded on-device verification (spec 005 US2 / FR-RR03).
+
+    Picks a variant whose record pins the NPU output, re-derives the cosine from the pinned operands with
+    the shared gate, and prints the result LABELLED as a replay of the recorded result (board + date) —
+    never as a fresh on-silicon verification (Principle I). Exits 0 on a reproduced pass, non-zero on a
+    fail / a recomputed≠recorded mismatch / a missing pin.
+    """
+    from . import replay as rp
+    variants = reg.variants(model)
+    cand = [v for v in variants if rp.is_rederivable(v)]
+    if not cand:
+        print(f"{RED}✗ cannot replay{RST} {model}: no pinned on-device output to replay; this record "
+              f"predates reproducible-record or was not captured.")
+        # a record exists but was never captured for replay — point at the live gate as the way to verify.
+        if any(v.verified for v in variants):
+            print(f"  {DIM}the recorded number is still shown by `chipwright list` / `resolve`; to get a "
+                  f"fresh VERIFIED line, run it on a board (chipwright run {model}).{RST}")
+        return 2
+
+    v = cand[0]
+    try:
+        res = rp.rederive(v)
+    except Exception as e:
+        print(f"{RED}✗ replay failed:{RST} {e}")
+        return 1
+
+    rec = v.verified or {}
+    board = rec.get("on", "?")
+    date = rec.get("date", "?")
+    cmin = res["cosine_min"]
+    tag = f"{DIM}↺ REPLAY{RST} (recorded on {board}, {date})"
+
+    if not res["matches"]:
+        # recomputed ≠ recorded → refuse, never silently pass (FR-RR04 / Principle II).
+        print(f"{tag}  recomputed cosine_min={cmin:.5f} {RED}≠{RST} recorded {res['recorded']} "
+              f"(±{rp.TOLERANCE})  {RED}✗ REFUSING — record not reproducible{RST}")
+        return 1
+    if res["pass"]:
+        print(f"{tag}  cosine_min={cmin:.5f}  {GREEN}VERIFIED{RST}")
+        for name, c in res["outputs"].items():
+            print(f"    {name}: {c:.5f}")
+        return 0
+    # reproduced faithfully, but the recorded number is itself below threshold → a recorded FAIL.
+    print(f"{tag}  cosine_min={cmin:.5f}  {RED}FAILED{RST} (threshold {res['threshold']})")
+    return 1
+
+
+def cmd_verify(args):
+    """`chipwright verify <model> --offline` — the replay under its own verb (spec 005 US2)."""
     reg = Registry(args.registry)
     if args.model not in reg.models():
         print(f"{RED}unknown model{RST} '{args.model}'. known: {', '.join(reg.models())}")
         return 2
+    if not getattr(args, "offline", False):
+        print(f"{YELLOW}verify currently supports only offline replay{RST} — pass --offline "
+              f"(a live on-device verify is `chipwright run {args.model}`).")
+        return 2
+    return _replay(reg, args.model)
+
+
+def cmd_run(args):
+    reg = Registry(args.registry)
+    if args.model not in reg.models():
+        return _unknown_model(args, reg)
+    if getattr(args, "replay", False):
+        return _replay(reg, args.model)
     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)
     _print_decision(args.model, target, d)
     if not d.ok:
         if d.outcome == Outcome.BUILD:
             print(f"{DIM}milestone 1 is resolve-only — building is out of scope; stopping.{RST}")
-        return 1
+        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")):
@@ -189,19 +326,46 @@ def cmd_run(args):
         if v.url:
             print(f"fetching → cache ({cache.CACHE_DIR}) …")
             print(f"{GREEN}✔ cached + hash-verified{RST}  {cache.fetch(v.url, v.sha256)}")
-        return 0
+        return jsonout.EXIT_NOT_RUNNABLE
     from . import run as runner
     try:
-        rep = runner.run_variant(v, args.input)
+        rep = runner.run_variant(v, args.input, emit_record=getattr(args, "emit_record", False))
     except Exception as e:
         print(f"{RED}run failed:{RST} {e}")
-        return 1
+        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 0 if rep["pass"] else 1
+    return jsonout.exit_code_for(d) if rep["pass"] else jsonout.EXIT_VERIFY_MISMATCH
+
+
+def _run_json(args, reg, target) -> int:
+    """`run` in `--json` mode: all human/progress text (including the device runner's own prints) goes to
+    stderr, then exactly one JSON document goes to stdout. The resolve/run/verify logic is untouched —
+    this only redirects the human stream and projects the result (Principle IV).
+    """
+    # 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)
+        _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")):
+                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
+                code = jsonout.EXIT_NOT_RUNNABLE
+            else:
+                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
+    _emit_json(doc)
+    return code
 
 
 def cmd_list(args):
@@ -216,10 +380,15 @@ def cmd_list(args):
     if target is None and args.target:
         target = _manual_target(args.target)
 
+    if getattr(args, "json", False):
+        _emit_json(jsonout.list_to_dict(reg, target))
+        return 0
+
     head = f"{target}" if target else "no target — pass --target or configure a board to resolve"
     print(f"{DIM}catalogue · {len(reg.models())} models · {head}{RST}")
     badge = {Outcome.USE: f"{GREEN}USE{RST}", Outcome.USE_WITH_WARN: f"{YELLOW}USE*{RST}",
              Outcome.BUILD: f"{YELLOW}BUILD{RST}", Outcome.FAIL: f"{RED}FAIL{RST}"}
+    from . import replay as rp
     for m in reg.models():
         vs = reg.variants(m)
         archs = ",".join(sorted({v.arch for v in vs}))
@@ -230,13 +399,19 @@ def cmd_list(args):
             out = badge.get(d.outcome, "")
             if d.outcome == Outcome.FAIL and d.axis:
                 out += f"{DIM}({d.axis}){RST}"
-        rec = next((v.verified for v in vs if v.verified), None)
+        rec_v = next((v for v in vs if v.verified), None)
+        rec = rec_v.verified if rec_v else None
         vr = ""
         if rec and isinstance(rec.get("vs_reference"), dict):
             val = rec["vs_reference"].get("value")
             met = rec["vs_reference"].get("metric", "")
             if val is not None:
                 vr = f"{DIM}{met}={val}{RST}"
+            # annotate re-derivability (spec 005 FR-RR04) — a small, non-breaking tag.
+            if rp.is_rederivable(rec_v):
+                vr += f" {GREEN}↺replay{RST}"
+            else:
+                vr += f" {DIM}(not independently re-derivable yet){RST}"
         print(f"  {m:20s} {archs:9s} {quants:9s} {out:16s} {vr}")
     return 0
 
@@ -245,16 +420,15 @@ def cmd_build(args):
     import os
     reg = Registry(args.registry)
     if args.model not in reg.models():
-        print(f"{RED}unknown model{RST} '{args.model}'. known: {', '.join(reg.models())}")
-        return 2
+        return _unknown_model(args, reg)
     target = _get_target(args)
     d = resolve(target, reg.variants(args.model), args.quant, args.shape)
     _print_decision(args.model, target, d)
     if d.ok:
         print(f"{DIM}already resolves to USE — nothing to build.{RST}")
-        return 0
+        return jsonout.exit_code_for(d)
     if d.outcome != Outcome.BUILD:
-        return 1
+        return jsonout.exit_code_for(d)
     v = d.variant
     from . import config, build as builder, errors, recipe as recipe_mod
 
@@ -290,22 +464,59 @@ def cmd_build(args):
     return 1
 
 
+# The outcome→exit-code contract, shown in `--help` so a pipeline author can read it without the README
+# (spec 006 FR-J04). Kept in lockstep with chipwright.jsonout (the single source of the numbers).
+_EXIT_CODE_HELP = f"""exit codes (stable contract, chipwright.jsonout.__api__={jsonout.__api__}):
+  {jsonout.EXIT_USE:<3} USE               exact match — run it
+  {jsonout.EXIT_USE_WITH_WARN:<3} USE_WITH_WARN     in range, outside the tested SDK point
+  {jsonout.EXIT_BUILD:<3} BUILD             no artifact, but a recipe can build one
+  {jsonout.EXIT_FAIL:<3} FAIL              nothing fits — the message names the axis
+  {jsonout.EXIT_VERIFY_MISMATCH:<3} VERIFY_MISMATCH   ran, but the NPU vs CPU cosine fell below threshold
+  {jsonout.EXIT_NOT_RUNNABLE:<3} NOT_RUNNABLE      resolved, but cannot execute here (no run block / no board)
+  {jsonout.EXIT_USAGE:<3} usage             usage error / unknown model
+  {jsonout.EXIT_UNEXPECTED:<3} unexpected        an unexpected internal error
+"""
+
+
 def main(argv=None):
-    ap = argparse.ArgumentParser(prog="chipwright", description="Chipwright — package manager for Qualcomm NPUs")
+    ap = argparse.ArgumentParser(prog="chipwright", description="Chipwright — package manager for Qualcomm NPUs",
+                                 epilog=_EXIT_CODE_HELP, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("--registry", default=None, help="index path/URL (default: bundled registry)")
     ap.add_argument("--host"); ap.add_argument("--user"); ap.add_argument("--pw"); ap.add_argument("--port")
     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("--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.")
     sub = ap.add_subparsers(dest="cmd", required=True)
     sub.add_parser("doctor", help="probe the board")
     sub.add_parser("list", help="browse the catalogue (with resolve outcome for your board)")
     rp = sub.add_parser("resolve", help="resolve a model against the board"); rp.add_argument("model")
     rnp = sub.add_parser("run", help="resolve, fetch, run on the board, verify vs CPU"); rnp.add_argument("model"); rnp.add_argument("--input")
+    rnp.add_argument("--replay", action="store_true",
+                     help="no board: replay the recorded on-device verification from its pinned tensors")
+    rnp.add_argument("--emit-record", action="store_true",
+                     help="capture the on-device NPU output tensor(s) + print a ready-to-host record fragment (spec 005 FR-RR05)")
+    vp = sub.add_parser("verify", help="offline replay of a recorded verification (no board)")
+    vp.add_argument("model"); vp.add_argument("--offline", action="store_true",
+                                              help="re-derive the recorded result from pinned tensors")
     bp = sub.add_parser("build", help="resolve; when it misses, build from a recipe"); bp.add_argument("model")
     args = ap.parse_args(argv)
-    return {"doctor": cmd_doctor, "list": cmd_list, "resolve": cmd_resolve,
-            "run": cmd_run, "build": cmd_build}[args.cmd](args)
+    _set_palette(_color_enabled(args.json))
+    handler = {"doctor": cmd_doctor, "list": cmd_list, "resolve": cmd_resolve,
+               "run": cmd_run, "verify": cmd_verify, "build": cmd_build}[args.cmd]
+    # In --json mode, an unexpected internal error must still leave exactly one JSON document on stdout
+    # (never a half-line a parser chokes on) and exit 1 (FR-J01, edge case).
+    if args.json and args.cmd in ("resolve", "run", "list"):
+        try:
+            return handler(args)
+        except SystemExit:
+            raise                       # clean usage refusals (exit 2) keep stdout empty — fine for a parser
+        except Exception as e:
+            _emit_json({"error": str(e), "exit_code": jsonout.EXIT_UNEXPECTED})
+            return jsonout.EXIT_UNEXPECTED
+    return handler(args)
 
 
 if __name__ == "__main__":

{chipwright-0.2.3 → chipwright-0.2.4}/chipwright/data/index.yaml

@@ -198,6 +198,12 @@ models:
         metric: cosine_min
         value: 0.956
         note: real image (ImageNet 'Samoyed'); random-noise input gives 0.776 and the gate correctly FAILs it
+        npu_output:
+          - name: class_logits
+            url: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/mobilenet-v2/npu_class_logits.npy
+            sha256: 7064b5bd22d053fdce8d7f602cdafecc30b01944b3a422da9143e0627bafc3a8
+            dtype: float32
+            shape: [1, 1000]
       latency_ms:
         note: single 224x224 image; DLC compiled to context on-board
 - model: quicksrnet-small