qtdf 0.3.0__tar.gz

qtdf-0.3.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

qtdf-0.3.0/NOTICE

@@ -0,0 +1,11 @@
+qtdf — Quantum Test Data Format and known-good-qubit test stack
+Copyright 2026 Zubin Birnbach
+
+Licensed under the Apache License, Version 2.0.
+
+Measured-data provenance: records with data_source "measured" produced by
+ingest_ibm_snapshots.py derive from static calibration snapshots of IBM
+Quantum devices bundled with the qiskit-ibm-runtime package (Apache-2.0,
+(c) IBM). This repository ships the ingester, not the ingested data; run the
+ingester to regenerate the fleet locally. IBM device names appear factually
+as data provenance and imply no affiliation or endorsement.

qtdf-0.3.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: qtdf
+Version: 0.3.0
+Summary: Quantum Test Data Format and the known-good-qubit test stack: schema, hashed store, cross-fridge test executive, virtual fridge, CLI. Zero dependencies.
+Author-email: Zubin Birnbach <zubin.birnbach@yale.edu>
+License: Apache-2.0
+Keywords: quantum,qubit,test-data,known-good-die,yield,STDF,cryogenic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# QTDF — Quantum Test Data Format
+
+An open, versioned record for qubit/device test data — the STDF analog for
+quantum. This repo is the v0.1 reference: the spec, a zero-dependency Python
+library, and the first real record (a full-wave RF launch qualification).
+
+QTDF is the wedge in the "known-good-qubit" stack: free to adopt, works with any
+fridge, and feeds the yield-learning / dispositioning layer above it. The cassette
+makes the data better (automatic socket→device genealogy, a qualified RF
+environment) but is never required — a hand-wired setup emits valid QTDF too.
+
+## Layout
+
+```
+qtdf/
+  SCHEMA.md                 # the human-readable v0.2 spec (start here)
+  verify.sh                 # THE entry point: tests + store + demo, PASS/FAIL
+  AGENTS.md                 # guidance for AI agents (don't explore store/)
+  qtdf/                     # everything importable lives under qtdf.*
+    core.py                 # schema version, canonical hashing, io, migration
+    validate.py             # structural + semantic validator, quantity profiles
+    touchstone.py           # minimal .s2p ingest + S-parameter helpers
+    store.py                # append-only record store with index + query
+    cli.py / demo.py        # the qtdf CLI and packaged end-to-end demo
+    vfridge/                # virtual fridge: wafer truth model + cooldown measurement
+      wafer.py              # correlated variation, TLS bath, labeled defects
+      measure.py            # cooldown fluctuation, meas noise, QTDF emission
+    executive/              # the cross-fridge test executive
+      plan.py               # declarative JSON plans, content-hashed
+      adapters.py           # CarrierProvider (cassette/manual), FridgeProfile
+      backends.py           # vfridge + replay backends, capture I/O
+      run.py                # execute/replay with deterministic record identity
+    disposition/            # specs + policies, priced exactly   [commercial layer]
+      policy.py             # Spec (a view over records), 5 screening policies
+      engine.py             # multi-round evaluation vs truth, economics
+    analytics/              # the yield-learning layer            [commercial layer]
+      wafermap.py           # spatial yield from device.wafer coords
+      spc.py                # x-bar control charts, drift detection
+      gauge.py              # gauge R&R across fridges (%GRR, culprit)
+      mcm.py                # P(module ok | dies): margins MC + collision rule
+  plans/                    # versioned test plans (JSON)
+  captures/                 # replayable run captures (generated)
+  seed_from_eng_rf_002.py   # ingest the real ENG-RF-002 s2p -> record #1
+  ingest_ibm_snapshots.py   # real IBM calibration snapshots -> store (needs venv)
+  calibrate_emulator.py     # fit vfridge distributions to the measured fleet
+  fleet_report.py           # fleet-level yield analytics over the store
+  phase2_demo.py            # closed loop: emulated lot -> exact escape/overkill
+  records/                  # record #1 standalone copy
+  store/                    # measured fleet store: 3,649 records (generated)
+  truth/                    # truth sidecars — NEVER inside a store
+  tests/                    # 7 suites; each runs standalone
+```
+
+## Install
+
+```bash
+pip install .                     # zero dependencies, Python 3.10+ (pkg 0.3.0, schema 0.2.0)
+qtdf demo                         # the whole pipeline on a virtual lot, ~2 s
+qtdf validate my_record.json      # validate any QTDF record
+qtdf show my_record.json          # summary + hash verification
+qtdf query store --verdict pass --count
+qtdf verify store                 # re-hash every record
+qtdf diff a.json b.json           # semantic diff
+```
+
+## Quickstart (repo checkout)
+
+```bash
+# core is stdlib only, Python 3.10+
+python tests/test_qtdf.py                 # v0.1 invariants -> 7/7
+python tests/test_store_v02.py            # v0.2 store/profiles -> 7/7
+python seed_from_eng_rf_002.py            # record #1 from the openEMS result
+
+# the real-data fleet (one-time venv for the ingester only)
+python3 -m venv .venv && .venv/bin/pip install qiskit-ibm-runtime
+.venv/bin/python ingest_ibm_snapshots.py  # 3,648 real qubit records, 68 chips
+python fleet_report.py                    # yield, T1/T2 stats, bin pareto
+
+# the closed loop (no venv needed)
+python calibrate_emulator.py              # fit emulator to the measured fleet
+python tests/test_vfridge.py              # emulator invariants -> 9/9
+python phase2_demo.py                     # exact escape/overkill vs truth
+
+# the executive (no venv needed)
+python tests/test_executive.py            # plans, carriers, replay -> 7/7
+python phase3_demo.py                     # cassette load -> capture -> replay
+
+# the disposition engine
+python tests/test_disposition.py          # specs, policies, exact eval -> 8/8
+python phase4_demo.py                     # 5 policies priced on one lot
+
+# yield analytics + MCM scorer
+python tests/test_analytics.py            # maps, SPC, R&R, scorer -> 7/7
+python phase5_demo.py                     # wafer map, drift, R&R, assembly
+```
+
+```python
+import qtdf
+st = qtdf.Store("store")
+st.count(record_type="qubit_coherence_screen", verdict="pass")
+```
+
+## Status
+
+Phase 1 ✓ — QTDF v0.2, coherence vocabulary grounded on real measured IBM
+calibration data (3,528 qubits, 67 chips), append-only store, quantity
+profiles, wafer/run genealogy. v0.1 records load unchanged (tested).
+
+Phase 2 ✓ — vfridge: virtual wafer with spatially-correlated variation, TLS
+bath, labeled defects, calibrated against the measured fleet; cooldown
+measurement with TLS-telegraph fluctuation + fit/shot noise; truth kept in a
+sidecar the pipeline cannot see. The closed loop computes EXACT escape and
+overkill for any screen policy. Byte-identical across processes
+(golden-pinned); measurement noise is keyed per (cooldown, die, qubit) so
+values are independent of batch composition — fair cross-policy comparison.
+
+Phase 3 ✓ — qtdf-exec: declarative content-hashed JSON plans (hash stamped
+into run.plan_hash), CarrierProvider adapters (cassette with per-die socket
+assignment + capacity enforcement; manual as the degenerate case), swappable
+measurement backends, and record/replay with deterministic identity
+(record_id = uuid5(run_id, device_id)): a replayed capture reproduces the
+live run byte-for-byte — verified down to file bytes in tests. Any captured
+run, virtual today or a real fridge later, is a CI fixture.
+
+Phase 4 ✓ — the disposition engine. Specs are frozen objects and disposition
+is a VIEW: the engine re-bins stored measurement values under any spec
+without remeasuring. Five screening policies (single-pass, best-of-N,
+confirm-Nx, guard-band, gray-zone retest) evaluated multi-round through the
+executive and priced exactly against truth. Demo lot at illustrative MCM
+economics: confirm-2x wins ($105k) — retesting passers is cheap when the
+pass population is small; best-of-2 is worst ($379k, adverse selection
+quantified). Known gap (deliberate): Spec expresses per-qubit limits only;
+die-level pairwise rules (freq_collision) belong to the Phase 5 MCM scorer.
+
+Phase 5 ✓ — the yield-learning layer. Wafer maps from device.wafer coords
+(dispositioned as a view, any spec). SPC x-bar charts: an injected 15% T1
+process drift at lot 4 is flagged at exactly lots 4-6. Gauge R&R across
+three virtual fridges with within-cooldown repeats (the emulator gained a
+`repeat` axis: fit noise redraws, TLS telegraph stays fixed — across-cooldown
+"repeats" would confound gauge noise with device telegraph) correctly
+isolates the secretly-noisy fridge; fridge-to-fridge AV physically includes
+per-cooldown telegraph. The MCM scorer answers the money question:
+P(module meets spec | measured dies) = margin Monte Carlo x deterministic
+interface-collision filter, with derating (screen at 140 us what must hold
+110 us at operation). Demo: scorer-assembled modules predicted 0.94 ->
+realized 2/2; random grouping predicted ~0 -> realized 0/2.
+
+Phase 6 ✓ — packaging. `pip install` with zero dependencies; `qtdf` CLI
+(validate / show / query / verify / diff / demo / version); `qtdf demo` runs
+the entire pipeline — virtual lot -> executive screen -> wafer map -> policies
+priced vs truth -> MCM assembly — self-contained (embedded plan) in ~2 s on a
+clean machine. Verified: fresh venv, install, run from an unrelated cwd. The
+demo's finale is the thesis in one line: from a 100-die lot with 7 true
+MCM-grade dies, the best 3-die chain scores P(meets spec) = 0.10 — known-good-
+die infrastructure is the difference between that and shipping modules.
+
+Release pass (pkg 0.3.0, July 2026) ✓ — everything folded under the
+`qtdf.*` namespace (imports changed, schema/records did not: schema stays
+0.2.0 and v0.1/v0.2 records load unchanged); user paths scrubbed from all
+shipped artifacts (record #1 re-finalized, store index rebuilt); Apache-2.0
+LICENSE + NOTICE (with IBM data provenance); `verify.sh` single-command
+verification; `AGENTS.md` so AI agents run instead of "architecting"; git +
+CI (Linux/macOS × Python 3.10–3.14). Independent reproduction: confirmed
+July 2026 on a non-macOS OS and non-3.14 Python (details to be recorded).
+
+Deferred: JSON Schema export for other languages (first non-Python partner).
+
+## License
+
+Apache-2.0 (see LICENSE, NOTICE) on this repository: the QTDF schema,
+validator, store, executive, virtual fridge, and CLI — open because a test
+-data standard is only useful if everyone can adopt it. The dispositioning
+engine and yield analytics (`qtdf/disposition/`, `qtdf/analytics/`) are the
+commercial layer and are not part of the public distribution; this working
+repository contains them for development.

qtdf-0.3.0/README.md

@@ -0,0 +1,175 @@
+# QTDF — Quantum Test Data Format
+
+An open, versioned record for qubit/device test data — the STDF analog for
+quantum. This repo is the v0.1 reference: the spec, a zero-dependency Python
+library, and the first real record (a full-wave RF launch qualification).
+
+QTDF is the wedge in the "known-good-qubit" stack: free to adopt, works with any
+fridge, and feeds the yield-learning / dispositioning layer above it. The cassette
+makes the data better (automatic socket→device genealogy, a qualified RF
+environment) but is never required — a hand-wired setup emits valid QTDF too.
+
+## Layout
+
+```
+qtdf/
+  SCHEMA.md                 # the human-readable v0.2 spec (start here)
+  verify.sh                 # THE entry point: tests + store + demo, PASS/FAIL
+  AGENTS.md                 # guidance for AI agents (don't explore store/)
+  qtdf/                     # everything importable lives under qtdf.*
+    core.py                 # schema version, canonical hashing, io, migration
+    validate.py             # structural + semantic validator, quantity profiles
+    touchstone.py           # minimal .s2p ingest + S-parameter helpers
+    store.py                # append-only record store with index + query
+    cli.py / demo.py        # the qtdf CLI and packaged end-to-end demo
+    vfridge/                # virtual fridge: wafer truth model + cooldown measurement
+      wafer.py              # correlated variation, TLS bath, labeled defects
+      measure.py            # cooldown fluctuation, meas noise, QTDF emission
+    executive/              # the cross-fridge test executive
+      plan.py               # declarative JSON plans, content-hashed
+      adapters.py           # CarrierProvider (cassette/manual), FridgeProfile
+      backends.py           # vfridge + replay backends, capture I/O
+      run.py                # execute/replay with deterministic record identity
+    disposition/            # specs + policies, priced exactly   [commercial layer]
+      policy.py             # Spec (a view over records), 5 screening policies
+      engine.py             # multi-round evaluation vs truth, economics
+    analytics/              # the yield-learning layer            [commercial layer]
+      wafermap.py           # spatial yield from device.wafer coords
+      spc.py                # x-bar control charts, drift detection
+      gauge.py              # gauge R&R across fridges (%GRR, culprit)
+      mcm.py                # P(module ok | dies): margins MC + collision rule
+  plans/                    # versioned test plans (JSON)
+  captures/                 # replayable run captures (generated)
+  seed_from_eng_rf_002.py   # ingest the real ENG-RF-002 s2p -> record #1
+  ingest_ibm_snapshots.py   # real IBM calibration snapshots -> store (needs venv)
+  calibrate_emulator.py     # fit vfridge distributions to the measured fleet
+  fleet_report.py           # fleet-level yield analytics over the store
+  phase2_demo.py            # closed loop: emulated lot -> exact escape/overkill
+  records/                  # record #1 standalone copy
+  store/                    # measured fleet store: 3,649 records (generated)
+  truth/                    # truth sidecars — NEVER inside a store
+  tests/                    # 7 suites; each runs standalone
+```
+
+## Install
+
+```bash
+pip install .                     # zero dependencies, Python 3.10+ (pkg 0.3.0, schema 0.2.0)
+qtdf demo                         # the whole pipeline on a virtual lot, ~2 s
+qtdf validate my_record.json      # validate any QTDF record
+qtdf show my_record.json          # summary + hash verification
+qtdf query store --verdict pass --count
+qtdf verify store                 # re-hash every record
+qtdf diff a.json b.json           # semantic diff
+```
+
+## Quickstart (repo checkout)
+
+```bash
+# core is stdlib only, Python 3.10+
+python tests/test_qtdf.py                 # v0.1 invariants -> 7/7
+python tests/test_store_v02.py            # v0.2 store/profiles -> 7/7
+python seed_from_eng_rf_002.py            # record #1 from the openEMS result
+
+# the real-data fleet (one-time venv for the ingester only)
+python3 -m venv .venv && .venv/bin/pip install qiskit-ibm-runtime
+.venv/bin/python ingest_ibm_snapshots.py  # 3,648 real qubit records, 68 chips
+python fleet_report.py                    # yield, T1/T2 stats, bin pareto
+
+# the closed loop (no venv needed)
+python calibrate_emulator.py              # fit emulator to the measured fleet
+python tests/test_vfridge.py              # emulator invariants -> 9/9
+python phase2_demo.py                     # exact escape/overkill vs truth
+
+# the executive (no venv needed)
+python tests/test_executive.py            # plans, carriers, replay -> 7/7
+python phase3_demo.py                     # cassette load -> capture -> replay
+
+# the disposition engine
+python tests/test_disposition.py          # specs, policies, exact eval -> 8/8
+python phase4_demo.py                     # 5 policies priced on one lot
+
+# yield analytics + MCM scorer
+python tests/test_analytics.py            # maps, SPC, R&R, scorer -> 7/7
+python phase5_demo.py                     # wafer map, drift, R&R, assembly
+```
+
+```python
+import qtdf
+st = qtdf.Store("store")
+st.count(record_type="qubit_coherence_screen", verdict="pass")
+```
+
+## Status
+
+Phase 1 ✓ — QTDF v0.2, coherence vocabulary grounded on real measured IBM
+calibration data (3,528 qubits, 67 chips), append-only store, quantity
+profiles, wafer/run genealogy. v0.1 records load unchanged (tested).
+
+Phase 2 ✓ — vfridge: virtual wafer with spatially-correlated variation, TLS
+bath, labeled defects, calibrated against the measured fleet; cooldown
+measurement with TLS-telegraph fluctuation + fit/shot noise; truth kept in a
+sidecar the pipeline cannot see. The closed loop computes EXACT escape and
+overkill for any screen policy. Byte-identical across processes
+(golden-pinned); measurement noise is keyed per (cooldown, die, qubit) so
+values are independent of batch composition — fair cross-policy comparison.
+
+Phase 3 ✓ — qtdf-exec: declarative content-hashed JSON plans (hash stamped
+into run.plan_hash), CarrierProvider adapters (cassette with per-die socket
+assignment + capacity enforcement; manual as the degenerate case), swappable
+measurement backends, and record/replay with deterministic identity
+(record_id = uuid5(run_id, device_id)): a replayed capture reproduces the
+live run byte-for-byte — verified down to file bytes in tests. Any captured
+run, virtual today or a real fridge later, is a CI fixture.
+
+Phase 4 ✓ — the disposition engine. Specs are frozen objects and disposition
+is a VIEW: the engine re-bins stored measurement values under any spec
+without remeasuring. Five screening policies (single-pass, best-of-N,
+confirm-Nx, guard-band, gray-zone retest) evaluated multi-round through the
+executive and priced exactly against truth. Demo lot at illustrative MCM
+economics: confirm-2x wins ($105k) — retesting passers is cheap when the
+pass population is small; best-of-2 is worst ($379k, adverse selection
+quantified). Known gap (deliberate): Spec expresses per-qubit limits only;
+die-level pairwise rules (freq_collision) belong to the Phase 5 MCM scorer.
+
+Phase 5 ✓ — the yield-learning layer. Wafer maps from device.wafer coords
+(dispositioned as a view, any spec). SPC x-bar charts: an injected 15% T1
+process drift at lot 4 is flagged at exactly lots 4-6. Gauge R&R across
+three virtual fridges with within-cooldown repeats (the emulator gained a
+`repeat` axis: fit noise redraws, TLS telegraph stays fixed — across-cooldown
+"repeats" would confound gauge noise with device telegraph) correctly
+isolates the secretly-noisy fridge; fridge-to-fridge AV physically includes
+per-cooldown telegraph. The MCM scorer answers the money question:
+P(module meets spec | measured dies) = margin Monte Carlo x deterministic
+interface-collision filter, with derating (screen at 140 us what must hold
+110 us at operation). Demo: scorer-assembled modules predicted 0.94 ->
+realized 2/2; random grouping predicted ~0 -> realized 0/2.
+
+Phase 6 ✓ — packaging. `pip install` with zero dependencies; `qtdf` CLI
+(validate / show / query / verify / diff / demo / version); `qtdf demo` runs
+the entire pipeline — virtual lot -> executive screen -> wafer map -> policies
+priced vs truth -> MCM assembly — self-contained (embedded plan) in ~2 s on a
+clean machine. Verified: fresh venv, install, run from an unrelated cwd. The
+demo's finale is the thesis in one line: from a 100-die lot with 7 true
+MCM-grade dies, the best 3-die chain scores P(meets spec) = 0.10 — known-good-
+die infrastructure is the difference between that and shipping modules.
+
+Release pass (pkg 0.3.0, July 2026) ✓ — everything folded under the
+`qtdf.*` namespace (imports changed, schema/records did not: schema stays
+0.2.0 and v0.1/v0.2 records load unchanged); user paths scrubbed from all
+shipped artifacts (record #1 re-finalized, store index rebuilt); Apache-2.0
+LICENSE + NOTICE (with IBM data provenance); `verify.sh` single-command
+verification; `AGENTS.md` so AI agents run instead of "architecting"; git +
+CI (Linux/macOS × Python 3.10–3.14). Independent reproduction: confirmed
+July 2026 on a non-macOS OS and non-3.14 Python (details to be recorded).
+
+Deferred: JSON Schema export for other languages (first non-Python partner).
+
+## License
+
+Apache-2.0 (see LICENSE, NOTICE) on this repository: the QTDF schema,
+validator, store, executive, virtual fridge, and CLI — open because a test
+-data standard is only useful if everyone can adopt it. The dispositioning
+engine and yield analytics (`qtdf/disposition/`, `qtdf/analytics/`) are the
+commercial layer and are not part of the public distribution; this working
+repository contains them for development.

qtdf-0.3.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qtdf"
+version = "0.3.0"
+description = "Quantum Test Data Format and the known-good-qubit test stack: schema, hashed store, cross-fridge test executive, virtual fridge, CLI. Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Zubin Birnbach", email = "zubin.birnbach@yale.edu" }]
+keywords = ["quantum", "qubit", "test-data", "known-good-die", "yield", "STDF", "cryogenic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+# Zero runtime dependencies — the whole stack is stdlib-only by design.
+# (The IBM snapshot ingester needs qiskit-ibm-runtime; deliberately NOT a dep.)
+dependencies = []
+
+[project.scripts]
+qtdf = "qtdf.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["qtdf*"]
+
+# Package version (0.3.0) is decoupled from the QTDF SCHEMA version (0.2.0,
+# qtdf.QTDF_VERSION): the 0.2->0.3 package bump is the qtdf.* namespace
+# consolidation — imports changed, records did not.

qtdf-0.3.0/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",
+]