qtdf 0.3.0__py3-none-any.whl

qtdf/__init__.py

@@ -0,0 +1,34 @@
+"""QTDF — Quantum Test Data Format (v0.1 reference implementation)."""
+from .core import (
+    QTDF_VERSION,
+    content_hash,
+    finalize,
+    migrate,
+    new_record_id,
+    read_record,
+    utc_now,
+    verify_hash,
+    write_record,
+)
+from .store import Store
+from .validate import errors_only, is_valid, validate
+
+# package (distribution) version — distinct from QTDF_VERSION, the schema
+# version stamped into records. 0.3.0 = the qtdf.* namespace consolidation.
+__version__ = "0.3.0"
+
+__all__ = [
+    "QTDF_VERSION",
+    "content_hash",
+    "finalize",
+    "migrate",
+    "new_record_id",
+    "read_record",
+    "utc_now",
+    "verify_hash",
+    "write_record",
+    "validate",
+    "errors_only",
+    "is_valid",
+    "Store",
+]

qtdf/cli.py

@@ -0,0 +1,217 @@
+"""qtdf — the command line for QTDF stores and records.
+
+    qtdf validate FILE...        validate record files (exit 1 on hard errors)
+    qtdf show FILE               human-readable record summary + hash check
+    qtdf query STORE [filters]   list/count records in a store
+    qtdf verify STORE            re-hash every record in a store
+    qtdf diff A B                semantic diff of two records
+    qtdf demo                    the end-to-end pipeline on a virtual lot
+    qtdf version                 library + schema version
+
+Stdlib only, like everything in qtdf-core.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def _load(path: str) -> dict:
+    with open(path, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+# ------------------------------------------------------------------ #
+def cmd_validate(args) -> int:
+    import qtdf
+    worst = 0
+    for path in args.files:
+        problems = qtdf.validate(_load(path))
+        errors = [p for p in problems if not p.startswith("warning: ")]
+        warnings = [p for p in problems if p.startswith("warning: ")]
+        status = "OK" if not errors else "INVALID"
+        print(f"{status:8s} {path}"
+              + (f"  ({len(warnings)} warning{'s' * (len(warnings) != 1)})"
+                 if warnings else ""))
+        for p in errors + (warnings if args.verbose else []):
+            print(f"         - {p}")
+        worst = max(worst, 1 if errors else 0)
+    return worst
+
+
+def cmd_show(args) -> int:
+    import qtdf
+    rec = _load(args.file)
+    dev, disp, run = rec.get("device", {}), rec.get("disposition", {}), rec.get("run") or {}
+    w = dev.get("wafer") or {}
+    print(f"record   : {rec.get('record_id')}  (qtdf {rec.get('qtdf_version')})")
+    print(f"type     : {rec.get('record_type')}  [{rec.get('data_source')}]")
+    print(f"device   : {dev.get('device_id')}"
+          + (f"  (lot {w.get('lot_id')} wafer {w.get('wafer_id')}"
+             f" die {w.get('die_x')},{w.get('die_y')})" if w else ""))
+    c = rec.get("carrier", {})
+    print(f"carrier  : {c.get('provider')}"
+          + (f" {c.get('carrier_part')}" if c.get("carrier_part") else "")
+          + (f" socket {c.get('socket')}" if c.get("socket") else ""))
+    f = rec.get("fixture", {})
+    print(f"fixture  : {f.get('fridge_id')}"
+          + (f" @ {f.get('temperature_K')} K" if f.get("temperature_K") is not None else ""))
+    if run:
+        ph = run.get("plan_hash") or ""
+        print(f"run      : {run.get('run_id')}  {run.get('cooldown_id') or ''}"
+              + (f"  plan {ph[:18]}…" if ph else ""))
+    print(f"verdict  : {disp.get('verdict')} (bin {disp.get('bin')})"
+          + (f" — {disp['reason']}" if disp.get("reason") else ""))
+    print("measurements:")
+    for m in rec.get("measurements", []):
+        lim = m.get("limit")
+        lim_s = f"{lim['op']} {lim['value']}" if lim else ""
+        ok = {True: "PASS", False: "FAIL", None: "    "}[m.get("pass")]
+        val = m.get("value")
+        if isinstance(val, float):
+            val_s = f"{val:12.5g}"
+        elif isinstance(val, (list, dict)):        # array values (e.g. band lobes)
+            s = json.dumps(val)
+            val_s = s if len(s) <= 28 else s[:25] + "..."
+        else:
+            val_s = f"{val!s:>12}"
+        print(f"  {m.get('quantity', ''):16s} {val_s} {m.get('unit', ''):4s}"
+              f" {lim_s:12s} {ok}")
+    print(f"hash     : {'verified OK' if qtdf.verify_hash(rec) else 'MISMATCH'}")
+    return 0
+
+
+def cmd_query(args) -> int:
+    from qtdf.store import Store
+    filters = {}
+    for key in ("record_type", "data_source", "verdict", "run_id"):
+        v = getattr(args, key)
+        if v is not None:
+            filters[key] = v
+    rows = Store(args.store).query(device_prefix=args.device_prefix, **filters)
+    if args.count:
+        print(sum(1 for _ in rows))
+        return 0
+    n = 0
+    for row in rows:
+        print(f"{row['verdict'] or '-':5s} {row['record_type'] or '-':26s} "
+              f"{row['device_id'] or '-'}")
+        n += 1
+        if args.limit and n >= args.limit:
+            print(f"... (--limit {args.limit} reached)")
+            break
+    return 0
+
+
+def cmd_verify(args) -> int:
+    from qtdf.store import Store
+    st = Store(args.store)
+    bad = st.verify_all()
+    n = sum(1 for _ in st.index())
+    if bad:
+        print(f"{len(bad)}/{n} records FAILED hash verification:")
+        for rid in bad[:20]:
+            print(f"  {rid}")
+        return 1
+    print(f"{n} records, all hashes verified")
+    return 0
+
+
+def cmd_diff(args) -> int:
+    a, b = _load(args.a), _load(args.b)
+    if a.get("device", {}).get("device_id") != b.get("device", {}).get("device_id"):
+        print(f"device   : {a['device']['device_id']}  vs  {b['device']['device_id']}")
+    ma = {m["quantity"]: m for m in a.get("measurements", [])}
+    mb = {m["quantity"]: m for m in b.get("measurements", [])}
+    changed = False
+    for q in sorted(set(ma) | set(mb)):
+        va, vb = (ma.get(q) or {}).get("value"), (mb.get(q) or {}).get("value")
+        if va == vb:
+            continue
+        changed = True
+        delta = ""
+        if isinstance(va, (int, float)) and isinstance(vb, (int, float)) and va:
+            delta = f"  ({100.0 * (vb - va) / abs(va):+.1f}%)"
+        print(f"{q:16s}: {va} -> {vb}{delta}")
+    da, db = a.get("disposition", {}), b.get("disposition", {})
+    if (da.get("verdict"), da.get("bin")) != (db.get("verdict"), db.get("bin")):
+        changed = True
+        print(f"verdict         : {da.get('verdict')}(bin {da.get('bin')})"
+              f" -> {db.get('verdict')}(bin {db.get('bin')})")
+    pa = (a.get("run") or {}).get("plan_hash")
+    pb = (b.get("run") or {}).get("plan_hash")
+    if pa != pb:
+        changed = True
+        print(f"plan_hash       : {'differs' if pa and pb else 'added/removed'}"
+              f" ({(pa or '-')[:18]}… -> {(pb or '-')[:18]}…)")
+    if not changed:
+        print("no semantic differences (values, verdict, plan)")
+    return 0
+
+
+def cmd_demo(args) -> int:
+    from qtdf.demo import run
+    return run(seed=args.seed, rows=args.rows, cols=args.cols,
+               store_dir=args.store)
+
+
+def cmd_version(_args) -> int:
+    import qtdf
+    print(f"qtdf {qtdf.__version__} (schema {qtdf.QTDF_VERSION})")
+    return 0
+
+
+# ------------------------------------------------------------------ #
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="qtdf", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("validate", help="validate record files")
+    p.add_argument("files", nargs="+")
+    p.add_argument("-v", "--verbose", action="store_true",
+                   help="also print warnings")
+    p.set_defaults(fn=cmd_validate)
+
+    p = sub.add_parser("show", help="summarize one record")
+    p.add_argument("file")
+    p.set_defaults(fn=cmd_show)
+
+    p = sub.add_parser("query", help="filter a store's index")
+    p.add_argument("store")
+    p.add_argument("--record-type", dest="record_type")
+    p.add_argument("--data-source", dest="data_source")
+    p.add_argument("--verdict")
+    p.add_argument("--run-id", dest="run_id")
+    p.add_argument("--device-prefix", dest="device_prefix")
+    p.add_argument("--count", action="store_true")
+    p.add_argument("--limit", type=int, default=40)
+    p.set_defaults(fn=cmd_query)
+
+    p = sub.add_parser("verify", help="re-hash every record in a store")
+    p.add_argument("store")
+    p.set_defaults(fn=cmd_verify)
+
+    p = sub.add_parser("diff", help="semantic diff of two records")
+    p.add_argument("a")
+    p.add_argument("b")
+    p.set_defaults(fn=cmd_diff)
+
+    p = sub.add_parser("demo", help="end-to-end pipeline on a virtual lot")
+    p.add_argument("--seed", type=int, default=42)
+    p.add_argument("--rows", type=int, default=10)
+    p.add_argument("--cols", type=int, default=10)
+    p.add_argument("--store", default=None,
+                   help="keep the demo store here (default: temp dir)")
+    p.set_defaults(fn=cmd_demo)
+
+    p = sub.add_parser("version", help="print schema/library version")
+    p.set_defaults(fn=cmd_version)
+
+    args = ap.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

qtdf/core.py

@@ -0,0 +1,151 @@
+"""QTDF core — Quantum Test Data Format, reference implementation (v0.1).
+
+Zero external dependencies (Python stdlib only). A QTDF record is a plain dict
+that round-trips to JSON. This module supplies:
+  - the version + controlled vocabularies,
+  - canonical serialization + content hashing (tamper-evident provenance),
+  - read/write helpers,
+  - a forward-migration hook.
+
+Validation lives in ``qtdf.validate``; touchstone ingest in ``qtdf.touchstone``.
+"""
+from __future__ import annotations
+
+import copy
+import datetime as _dt
+import hashlib
+import json
+import uuid
+from typing import Any
+
+# Schema semver. Bump MINOR for additive/compatible changes, MAJOR for breaking.
+# v0.2.0 (additive over 0.1): optional `device.wafer` genealogy (lot/wafer/die x,y),
+# optional top-level `run` grouping (cooldown/session), per-record_type required-
+# quantity profiles in the validator, and the qubit_coherence_screen vocabulary.
+# v0.1 records remain valid v0.2 records — hashes and validity are unchanged.
+QTDF_VERSION = "0.2.0"
+
+# --- Controlled vocabularies (recommended, not closed; validator warns on novel) ---
+
+# What kind of test the record captures. Open vocab, but these are the seeds.
+RECORD_TYPES = frozenset({
+    "rf_launch_qualification",   # S-parameter qualification of an RF transition/fixture
+    "qubit_coherence_screen",    # T1 / T2* / T2echo
+    "readout_fidelity",
+    "gate_benchmarking",         # RB / XEB
+    "spectroscopy",              # f_01, anharmonicity, TLS
+    "continuity",                # DC / wiring integrity
+})
+
+# Whether the numbers are physically measured or predicted. CRITICAL to keep
+# straight — a test-data standard must never let a sim be mistaken for a DUT.
+DATA_SOURCES = frozenset({"measured", "simulation", "emulated"})
+
+# How the device under test reached the fridge. This is the cassette tier.
+CARRIER_PROVIDERS = frozenset({
+    "cassette",   # CPN cassette: socket->device_id is automatic, RF env qualified
+    "manual",     # bare wirebond / hand-wired: metadata entered by operator
+    "custom",     # third-party carrier via an adapter
+})
+
+# Dispositioning verdicts (the disposition standard). Overall verdict may be
+# derived from measurement passes OR set by engineering override (with reason).
+VERDICTS = frozenset({"pass", "fail", "hold", "scrap", "rework"})
+
+# Comparison operators for a measurement limit.
+LIMIT_OPS = frozenset({"<=", ">=", "<", ">", "==", "in_range"})
+
+
+# --------------------------------------------------------------------------- #
+# Identity + timestamps
+# --------------------------------------------------------------------------- #
+def new_record_id() -> str:
+    """Return a fresh urn:uuid record identifier."""
+    return f"urn:uuid:{uuid.uuid4()}"
+
+
+def utc_now() -> str:
+    """ISO-8601 UTC timestamp, second precision, 'Z' suffix."""
+    return _dt.datetime.now(_dt.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+# --------------------------------------------------------------------------- #
+# Canonicalization + content hashing
+# --------------------------------------------------------------------------- #
+def canonical_json(obj: Any) -> str:
+    """Deterministic JSON: sorted keys, no insignificant whitespace.
+
+    Two records with the same content hash to the same string regardless of key
+    insertion order, so ``content_hash`` is a stable identity for the payload.
+    """
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def content_hash(record: dict) -> str:
+    """sha256 over the record with ``provenance.content_hash`` excluded.
+
+    The hash cannot cover itself, so we strip it before hashing. Returns a
+    'sha256:...' prefixed hex digest.
+    """
+    stripped = copy.deepcopy(record)
+    prov = stripped.get("provenance")
+    if isinstance(prov, dict):
+        prov.pop("content_hash", None)
+    digest = hashlib.sha256(canonical_json(stripped).encode("utf-8")).hexdigest()
+    return f"sha256:{digest}"
+
+
+def finalize(record: dict) -> dict:
+    """Stamp ``provenance.content_hash`` in place and return the record.
+
+    Call once, immediately before persisting. A record is immutable after
+    finalize; corrections are new records that set ``supersedes``.
+    """
+    record.setdefault("provenance", {})
+    record["provenance"]["content_hash"] = content_hash(record)
+    return record
+
+
+def verify_hash(record: dict) -> bool:
+    """True iff the stored content hash matches a fresh recomputation."""
+    stored = record.get("provenance", {}).get("content_hash")
+    return bool(stored) and stored == content_hash(record)
+
+
+# --------------------------------------------------------------------------- #
+# I/O
+# --------------------------------------------------------------------------- #
+def write_record(record: dict, path: str) -> None:
+    """Write a record as pretty JSON (finalize first if not already hashed)."""
+    if not record.get("provenance", {}).get("content_hash"):
+        finalize(record)
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(record, fh, indent=1, ensure_ascii=False)
+        fh.write("\n")
+
+
+def read_record(path: str) -> dict:
+    """Read a record from JSON and migrate it to the current QTDF_VERSION."""
+    with open(path, encoding="utf-8") as fh:
+        return migrate(json.load(fh))
+
+
+# --------------------------------------------------------------------------- #
+# Migration
+# --------------------------------------------------------------------------- #
+def migrate(record: dict) -> dict:
+    """Forward-migrate an older-minor record to QTDF_VERSION.
+
+    v0.1 is the floor, so this is currently a version-gate: it refuses a record
+    whose MAJOR differs from ours. As the schema evolves, add step functions
+    here (0.1 -> 0.2 -> ...) so historical records keep loading — backward
+    compatibility is a product feature, labs keep data for years.
+    """
+    ver = str(record.get("qtdf_version", "0.0.0"))
+    major = ver.split(".")[0]
+    if major != QTDF_VERSION.split(".")[0]:
+        raise ValueError(
+            f"record qtdf_version {ver} is a different MAJOR than {QTDF_VERSION}; "
+            "no migration path is defined"
+        )
+    return record

qtdf/demo.py

@@ -0,0 +1,171 @@
+"""The packaged end-to-end demo: `qtdf demo`.
+
+Self-contained — the plan is embedded and the emulator uses its built-in
+(fleet-calibrated) defaults, so this runs identically on a clean install with
+zero repo files: virtual lot -> executive screen -> wafer map -> policy
+pricing vs truth -> MCM assembly -> store integrity.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+
+DEMO_PLAN = {
+    "plan_id": "demo-coherence-screen",
+    "plan_version": "1.0.0",
+    "record_type": "qubit_coherence_screen",
+    "quantities": [
+        {"quantity": "T1", "symbol": "T1", "unit": "us",
+         "limit": {"op": ">=", "value": 150.0}},
+        {"quantity": "T2", "symbol": "T2", "unit": "us"},
+        {"quantity": "f_01", "symbol": "f01", "unit": "GHz"},
+        {"quantity": "readout_error", "symbol": "eps_ro", "unit": "1",
+         "limit": {"op": "<=", "value": 0.02}},
+    ],
+    "disposition": {
+        "spec_id": "MCM-GRADE-v0",
+        "response_quantity": "T1",
+        "pass_bin": 1,
+        "default_fail_bin": 9,
+        "bin_map": [
+            {"bin": 2, "when_failed": ["T1"]},
+            {"bin": 3, "when_failed": ["readout_error"]},
+            {"bin": 4, "when_failed": ["T1", "readout_error"]},
+            {"bin": 5, "nonfunctional": True},
+        ],
+    },
+}
+
+
+def run(seed: int = 42, rows: int = 10, cols: int = 10,
+        store_dir: str | None = None, echo=print) -> int:
+    from qtdf.executive import (
+        CassetteCarrier, FridgeProfile, VFridgeBackend, execute, plan_hash,
+        read_capture, replay, slots_from_wafer,
+    )
+    from qtdf.store import Store
+    from qtdf.vfridge import EmuConfig, generate_wafer
+
+    # the dispositioning/analytics layer ships separately (commercial); the
+    # demo runs end-to-end either way, swapping the finale
+    try:
+        from qtdf.analytics import ModuleSpec, ascii_map, die_map_from_store, \
+            radial_yield, score_module, select_modules
+        from qtdf.disposition import (
+            ConfirmPass, GrayZoneRetest, SinglePass, Spec, compare,
+            measured_die_values,
+        )
+        commercial = True
+    except ImportError:
+        commercial = False
+
+    tmp = None
+    if store_dir is None:
+        tmp = tempfile.mkdtemp(prefix="qtdf-demo-")
+        store_dir = tmp
+    try:
+        store = Store(store_dir)
+        cfg = EmuConfig.from_calibration(seed=seed, lot_id="LOT-DEMO",
+                                         rows=rows, cols=cols, qubits_per_die=4)
+        wafer = generate_wafer(cfg, 1)
+        limits = {q["quantity"]: q["limit"]
+                  for q in DEMO_PLAN["quantities"] if q.get("limit")}
+        spec_id = DEMO_PLAN["disposition"]["spec_id"]
+        echo(f"qtdf end-to-end demo — lot {cfg.lot_id}: {rows}x{cols} dies x 4 qubits"
+             f" (seed {seed})")
+        echo(f"plan {DEMO_PLAN['plan_id']} {plan_hash(DEMO_PLAN)[:18]}…  "
+             f"spec {spec_id}: T1>={limits['T1']['value']}us, "
+             f"ro<={limits['readout_error']['value']}\n")
+
+        # 1 — screen the wafer through the executive (cassette carrier)
+        carrier = CassetteCarrier(capacity=10 ** 6)
+        slots = carrier.load(slots_from_wafer(wafer))
+        run_id = "demo:screen:r1"
+        cap_path = os.path.join(store_dir, "demo_capture.json")
+        summary = execute(DEMO_PLAN, slots, carrier.meta(),
+                          VFridgeBackend(wafer, cfg),
+                          FridgeProfile("VF-1", 0.012), store, run_id=run_id,
+                          capture_path=None if commercial else cap_path)
+        echo(f"== screen: {summary['records']} qubit records, "
+             f"verdicts {summary['verdicts']} ==\n")
+
+        if not commercial:
+            # open-build finale: prove the record/replay property live
+            rep = Store(os.path.join(store_dir, "replay"))
+            s2 = replay(read_capture(cap_path), rep)
+            live = {r["record_id"]: r["content_hash"] for r in store.index()}
+            back = {r["record_id"]: r["content_hash"] for r in rep.index()}
+            echo("== record/replay: captured run replayed into a fresh store ==")
+            echo(f"  byte-identical reproduction: {live == back}"
+                 f"  ({s2['records']} records)")
+            echo("  (any captured run — virtual or a real fridge session — is a"
+                 " CI fixture)\n")
+            echo("(wafer maps, policy pricing, and MCM assembly-risk scoring live"
+                 " in the\n commercial layer; this open build carries the standard"
+                 " + executive)\n")
+            n = sum(1 for _ in store.index())
+            bad = store.verify_all()
+            echo(f"store: {n} records, "
+                 f"{'all hashes verified' if not bad else f'{len(bad)} HASH FAILURES'}")
+            return 0 if not bad and live == back else 1
+
+        spec = Spec.from_plan(DEMO_PLAN)
+
+        # 2 — wafer map (a VIEW: values re-dispositioned under the spec)
+        dm = die_map_from_store(store, run_id, spec)
+        echo(f"== wafer map ('.' = known-good-die under {spec.spec_id}) ==")
+        echo(ascii_map(dm, rows, cols))
+        rz = radial_yield(dm, rows, cols)
+        (cy, cn), (ey, en) = rz["center"], rz["edge"]
+        echo(f"radial: center {100 * cy:.0f}% ({cn} dies) vs edge {100 * ey:.0f}%"
+             f" ({en} dies)\n")
+
+        # 3 — screening policies priced exactly against truth
+        echo("== screening policies priced vs truth "
+             "(escape $50k, overkill $2k, test $200) ==")
+        rows_ = compare([SinglePass(), ConfirmPass(2), GrayZoneRetest(0.15)],
+                        [wafer], cfg, DEMO_PLAN, store, spec)
+        for m in rows_:
+            echo(f"  {m['policy']:14s} ship {m['shipped']:3d}  esc {m['escapes']:2d}"
+                 f"  ovk {m['overkill']:2d}  cost {m['cost_die_cooldowns']:3d}"
+                 f"  -> ${m['usd_total']:>9,.0f}")
+        echo(f"  winner: {rows_[0]['policy']}  "
+             f"(true good dies: {rows_[0]['true_good']}/{rows_[0]['dies']})\n")
+
+        # 4 — MCM assembly. The strict-KGD bin is tiny AND same-index qubits
+        # share one frequency plan across dies, so chains built only from that
+        # bin usually collide at the >=25 MHz interface rule (this is why real
+        # module builders stagger die frequency plans). So: assemble from all
+        # functional dies and let the scorer price each chain's risk.
+        vals = measured_die_values(store, run_id)
+        kgd = [d for d, qv in vals.items() if spec.die_pass(qv)]
+        functional = [
+            {"die_id": d, "qubits": qv} for d, qv in sorted(vals.items())
+            if all(v is not None for qv2 in qv for v in qv2.values())
+        ]
+        mspec = ModuleSpec(dies_per_module=3)
+        modules = select_modules(functional, mspec, mc=400, seed=seed)
+        echo(f"== MCM assembly ({mspec.dies_per_module}-die chains, "
+             f">= {mspec.min_sep_MHz:.0f} MHz interface separation) ==")
+        echo(f"  strict-KGD bin: {len(kgd)} dies (identical frequency plans -> "
+             f"chains collide); assembling from {len(functional)} functional dies:")
+        scored = sorted(
+            ((score_module(m, mspec, mc=800, seed=seed), m) for m in modules),
+            key=lambda x: -x[0])
+        for i, (p, mod) in enumerate(scored[:3]):
+            echo(f"  best module {i + 1}: P(meets spec) = {p:.2f}  "
+                 f"[{', '.join(d['die_id'].rsplit(':', 1)[-1] for d in mod)}]")
+        if len(scored) > 3:
+            echo(f"  ... {len(scored) - 3} more assembled; "
+                 f"worst P = {scored[-1][0]:.2f} — pick with eyes open")
+
+        # 5 — integrity
+        n = sum(1 for _ in store.index())
+        bad = store.verify_all()
+        echo(f"\nstore: {n} records, "
+             f"{'all hashes verified' if not bad else f'{len(bad)} HASH FAILURES'}")
+        return 0 if not bad else 1
+    finally:
+        if tmp:
+            shutil.rmtree(tmp, ignore_errors=True)

qtdf/executive/__init__.py

@@ -0,0 +1,24 @@
+"""qtdf-exec — the cross-fridge test executive (stdlib only).
+
+Plans (declarative, hashed) x adapters (carrier/backend/fridge) -> QTDF records
+with deterministic identity; captures make any run a replayable CI fixture.
+"""
+from .adapters import CassetteCarrier, DeviceSlot, FridgeProfile, ManualCarrier
+from .backends import (
+    ReplayBackend,
+    VFridgeBackend,
+    read_capture,
+    slots_from_capture,
+    slots_from_wafer,
+    write_capture,
+)
+from .plan import disposition, load_plan, plan_hash, validate_plan
+from .run import execute, record_id_for, replay
+
+__all__ = [
+    "DeviceSlot", "FridgeProfile", "CassetteCarrier", "ManualCarrier",
+    "VFridgeBackend", "ReplayBackend",
+    "slots_from_wafer", "slots_from_capture", "read_capture", "write_capture",
+    "load_plan", "plan_hash", "validate_plan", "disposition",
+    "execute", "replay", "record_id_for",
+]