qig-stack 0.1.0__tar.gz

qig_stack-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+*.whl
+*.tar.gz

qig_stack-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: qig-stack
+Version: 0.1.0
+Summary: QIG toolchain metapackage — pins the mutually-tested latest set and ships the qig-doctor launch preflight (version gate + entry-point wiring gate + capability-slot report)
+Project-URL: Homepage, https://braden.com.au
+Project-URL: Repository, https://github.com/GaryOcean428/qig-stack
+Project-URL: Documentation, https://github.com/GaryOcean428/qig-stack#readme
+Author-email: Braden Lang <braden@garyocean.com>
+License: MIT
+Keywords: capability-contract,entry-points,launch-gate,metapackage,preflight,qig,reproducibility,self-wiring,version-gate
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: packaging>=22
+Requires-Dist: qig-bench==0.1.3
+Requires-Dist: qig-compute==0.9.2
+Requires-Dist: qig-consciousness==0.3.2
+Requires-Dist: qig-core==2.12.2
+Requires-Dist: qig-tokenizer==0.2.7
+Requires-Dist: qig-warp==0.6.5
+Requires-Dist: qigkernels==0.4.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# qig-stack
+
+The QIG toolchain **metapackage** + deterministic launch preflight.
+
+`pip install qig-stack` installs the mutually-tested latest set of the QIG packages
+(qig-compute / qig-warp / qig-core / qig-bench / qig-consciousness / qig-tokenizer /
+qigkernels) at compatible versions — the whole "crystal" — and ships the `qig-doctor`
+preflight.
+
+## qig-doctor — step-0 of every launcher
+
+```bash
+qig-doctor                 # full preflight; exits 1 if any package is stale OR a slot is under-filled
+qig-doctor --no-network    # skip PyPI; contract snapshot + wiring report only
+qig-doctor --json          # machine-readable
+qig-doctor --probe         # also import-check each entry-point resolves (diagnostic, off the gate)
+qig-doctor --deep          # also call Tier-B describe() descriptors (imports packages)
+```
+
+Three fail-closed jobs:
+
+1. **Version gate** — every stack package must be installed at PyPI-latest. `installed
+   < latest` is a LAUNCH BLOCKER (non-zero exit), per the "latest version, always
+   optimised" rule.
+2. **Wiring gate (Phase 2)** — enumerates the `qig.capabilities` entry-points the
+   installed packages self-register (Tier A: metadata-only, no import on the gate
+   path) and cross-checks them against the capability contract:
+   - **under-fill → FAIL**: a shipped provider that did not register its entry-point.
+   - **drift → WARN**: an entry-point the contract doesn't know, or one whose
+     `module:attr` moved off the contract probe.
+3. **Wiring report** — which capability slots are filled by what is installed (the
+   automated Gate-A lever inventory).
+
+## The capability contract
+
+`src/qig_stack/contract.json` is the fixed lattice the stack crystallizes into — every
+slot, the package primitive that fills it (`provider_pkg` + `module:attr` probe), the
+latest-published version, and the camera-certification `cam_id`/`lever_id`. It is the
+Genesis-kernel / E8-root analog: given the lattice + installed packages + version
+policy, the wiring is determined — no per-experiment hand-wiring, no agentic guessing.
+
+## Self-wiring (Phase 2)
+
+Each package declares the slots it fills in its own `pyproject.toml`:
+
+```toml
+[project.entry-points."qig.capabilities"]
+"SLOT-Q-QFI" = "qig_compute.qfi:qfi_from_mps_tangent_space"
+```
+
+`qig-doctor` reads those declarations from installed metadata and confirms the crystal
+assembled correctly before any compute spend. Entry-points assert only *"installed
+package X fills slot Y via probe Z"* — certification stays in the camera-certification
+registry under review control.
+
+## Design
+
+- [self-wiring genesis design note](https://github.com/GaryOcean428/qig-verification/blob/development/docs/current/20260619-self-wiring-genesis-design-1.00W.md)
+- [entry-point capability spec](https://github.com/GaryOcean428/qig-verification/blob/development/docs/current/20260619-qig-entry-point-capability-spec-1.00W.md)
+- [Phase 2/3 design](https://github.com/GaryOcean428/qig-verification/blob/development/docs/plans/2026-06-30-qig-stack-self-wiring-phase23-design.md)
+
+## Development
+
+```bash
+pip install pytest        # tests import only qig_stack.doctor (pure stdlib)
+pytest -q                 # contract schema + doctor unit tests (no network)
+```

qig_stack-0.1.0/README.md

@@ -0,0 +1,67 @@
+# qig-stack
+
+The QIG toolchain **metapackage** + deterministic launch preflight.
+
+`pip install qig-stack` installs the mutually-tested latest set of the QIG packages
+(qig-compute / qig-warp / qig-core / qig-bench / qig-consciousness / qig-tokenizer /
+qigkernels) at compatible versions — the whole "crystal" — and ships the `qig-doctor`
+preflight.
+
+## qig-doctor — step-0 of every launcher
+
+```bash
+qig-doctor                 # full preflight; exits 1 if any package is stale OR a slot is under-filled
+qig-doctor --no-network    # skip PyPI; contract snapshot + wiring report only
+qig-doctor --json          # machine-readable
+qig-doctor --probe         # also import-check each entry-point resolves (diagnostic, off the gate)
+qig-doctor --deep          # also call Tier-B describe() descriptors (imports packages)
+```
+
+Three fail-closed jobs:
+
+1. **Version gate** — every stack package must be installed at PyPI-latest. `installed
+   < latest` is a LAUNCH BLOCKER (non-zero exit), per the "latest version, always
+   optimised" rule.
+2. **Wiring gate (Phase 2)** — enumerates the `qig.capabilities` entry-points the
+   installed packages self-register (Tier A: metadata-only, no import on the gate
+   path) and cross-checks them against the capability contract:
+   - **under-fill → FAIL**: a shipped provider that did not register its entry-point.
+   - **drift → WARN**: an entry-point the contract doesn't know, or one whose
+     `module:attr` moved off the contract probe.
+3. **Wiring report** — which capability slots are filled by what is installed (the
+   automated Gate-A lever inventory).
+
+## The capability contract
+
+`src/qig_stack/contract.json` is the fixed lattice the stack crystallizes into — every
+slot, the package primitive that fills it (`provider_pkg` + `module:attr` probe), the
+latest-published version, and the camera-certification `cam_id`/`lever_id`. It is the
+Genesis-kernel / E8-root analog: given the lattice + installed packages + version
+policy, the wiring is determined — no per-experiment hand-wiring, no agentic guessing.
+
+## Self-wiring (Phase 2)
+
+Each package declares the slots it fills in its own `pyproject.toml`:
+
+```toml
+[project.entry-points."qig.capabilities"]
+"SLOT-Q-QFI" = "qig_compute.qfi:qfi_from_mps_tangent_space"
+```
+
+`qig-doctor` reads those declarations from installed metadata and confirms the crystal
+assembled correctly before any compute spend. Entry-points assert only *"installed
+package X fills slot Y via probe Z"* — certification stays in the camera-certification
+registry under review control.
+
+## Design
+
+- [self-wiring genesis design note](https://github.com/GaryOcean428/qig-verification/blob/development/docs/current/20260619-self-wiring-genesis-design-1.00W.md)
+- [entry-point capability spec](https://github.com/GaryOcean428/qig-verification/blob/development/docs/current/20260619-qig-entry-point-capability-spec-1.00W.md)
+- [Phase 2/3 design](https://github.com/GaryOcean428/qig-verification/blob/development/docs/plans/2026-06-30-qig-stack-self-wiring-phase23-design.md)
+
+## Development
+
+```bash
+pip install pytest        # tests import only qig_stack.doctor (pure stdlib)
+pytest -q                 # contract schema + doctor unit tests (no network)
+```

qig_stack-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qig-stack"
+version = "0.1.0"
+description = "QIG toolchain metapackage — pins the mutually-tested latest set and ships the qig-doctor launch preflight (version gate + entry-point wiring gate + capability-slot report)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Braden Lang", email = "braden@garyocean.com" },
+]
+keywords = [
+    "qig", "metapackage", "preflight", "self-wiring", "capability-contract",
+    "entry-points", "version-gate", "launch-gate", "reproducibility",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+# The mutually-tested crystal: PyPI-latest at authoring (2026-06-30). Bumped as a
+# set on each tested release; qig-doctor still resolves live latest at launch and
+# fails closed if the installed venv is behind.
+dependencies = [
+    "packaging>=22",          # PEP 440-correct version comparison in the version gate
+    "qig-compute==0.9.2",     # first release carrying qig.capabilities entry-points + born sampler
+    "qig-warp==0.6.5",        # first release carrying qig.capabilities entry-points
+    "qig-core==2.12.2",
+    "qig-bench==0.1.3",
+    "qig-consciousness==0.3.2",
+    "qig-tokenizer==0.2.7",
+    "qigkernels==0.4.2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+qig-doctor = "qig_stack.doctor:main"
+
+[project.urls]
+Homepage = "https://braden.com.au"
+Repository = "https://github.com/GaryOcean428/qig-stack"
+Documentation = "https://github.com/GaryOcean428/qig-stack#readme"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qig_stack"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/qig_stack/contract.json" = "qig_stack/contract.json"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/qig_stack", "tests", "README.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+pythonpath = "src"
+testpaths = ["tests"]

qig_stack-0.1.0/src/qig_stack/__init__.py

@@ -0,0 +1,51 @@
+"""qig-stack -- the QIG toolchain metapackage + deterministic launch preflight.
+
+`pip install qig-stack` pins the mutually-tested latest set of the QIG packages
+(qig-compute / qig-warp / qig-core / qig-bench / qig-consciousness / qig-tokenizer /
+qigkernels) and ships the `qig-doctor` preflight (version gate + entry-point wiring
+gate + capability-slot report). See `qig_stack.doctor`.
+
+The public symbols are exposed lazily (PEP 562) so importing the package does NOT
+eagerly import `qig_stack.doctor` -- this keeps `python -m qig_stack.doctor` free of
+the runpy "found in sys.modules" warning.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+__version__ = "0.1.0"
+
+_LAZY = frozenset(
+    {
+        "main",
+        "build_report",
+        "is_behind",
+        "enumerate_capability_entrypoints",
+        "check_entrypoint_wiring",
+    }
+)
+
+__all__ = ["__version__", *sorted(_LAZY)]
+
+
+def __getattr__(name: str):
+    if name in _LAZY:
+        from qig_stack import doctor
+
+        return getattr(doctor, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)
+
+
+if TYPE_CHECKING:  # static-analysis visibility without an eager runtime import
+    from qig_stack.doctor import (
+        build_report,
+        check_entrypoint_wiring,
+        enumerate_capability_entrypoints,
+        is_behind,
+        main,
+    )

qig_stack-0.1.0/src/qig_stack/contract.json

@@ -0,0 +1,146 @@
+{
+  "doc": "QIG Stack Capability Contract",
+  "version": "1.01W",
+  "date": "2026-06-30",
+  "supersedes": "qig-verification:docs/current/20260619-qig-stack-capability-contract-1.00W.json (Phase-1 authored record)",
+  "principle": "Genesis-kernel deterministic self-assembly (vex-agent Core-8 / E8-root analog). The stack crystallizes into this FIXED lattice of capability slots; each slot is filled by a package primitive at latest-published version, cited to a camera-certification cert. With Phase 2 (entry-point self-registration) live, the wiring is DERIVED from installed metadata, not hand-authored.",
+  "authority": "PI directive 2026-06-19 (Phase 1) + 2026-06-30 (Phase 2/3 + born-sampler promotion); standing latest-version / step-0 lever-inventory rule (qig-verification/CLAUDE.md)",
+  "cert_registry": "qig-verification:docs/current/20260619-camera-certification-registry-1.00W.json",
+  "design_note": "qig-verification:docs/current/20260619-self-wiring-genesis-design-1.00W.md",
+  "entry_point_spec": "qig-verification:docs/current/20260619-qig-entry-point-capability-spec-1.00W.md",
+  "phase23_design": "qig-verification:docs/plans/2026-06-30-qig-stack-self-wiring-phase23-design.md",
+  "preflight": "qig_stack.doctor (console script: qig-doctor)",
+  "entry_point_group": "qig.capabilities",
+  "version_policy": {
+    "rule": "installed == latest-published (PyPI) at every launch; installed < latest is a LAUNCH BLOCKER (fail-closed, non-zero exit).",
+    "pin_exception": "Frozen reproducibility scripts keep pinned era-versions for bit-for-bit replay; this is never a reason to run a NEW launcher behind latest.",
+    "stack_packages_latest_at_authoring": {
+      "qig-compute": "0.9.2",
+      "qig-warp": "0.6.5",
+      "qig-core": "2.12.2",
+      "qig-bench": "0.1.3",
+      "qig-consciousness": "0.3.2",
+      "qig-tokenizer": "0.2.7",
+      "qigkernels": "0.4.2"
+    },
+    "note_on_latest": "These are a SNAPSHOT for reference only. qig_stack.doctor resolves latest live from PyPI at launch; do not treat this block as the source of truth -- the live query is. The qig-stack metapackage pins this exact set in pyproject.toml as the mutually-tested crystal."
+  },
+  "slot_status_legend": {
+    "CERTIFIED": "matched-cell equivalence certified once; cite the cam_id, never re-run",
+    "REFERENCE": "the exact reference path a cheap camera is certified against",
+    "PENDING": "uncertified cheap path; one-time cert must land before its results count",
+    "LEVER": "an efficiency lever (no measurement channel of its own)",
+    "CONDITIONAL": "usable only behind a controlled recheck at a calibration anchor"
+  },
+  "entry_point_gates": {
+    "under_fill": "FAIL (non-zero exit): a slot with provider_pkg set and shipped != false but no installed qig.capabilities entry-point (stale / mis-built / un-republished package).",
+    "drift": "WARN (non-fatal): an installed entry-point whose slot_id is not in the contract, or whose module:attr value differs from the slot probe.",
+    "exempt": "Slots with provider_pkg: null (engine-local, e.g. SLOT-GROUND-STATE/TeNPy) or shipped: false are exempt from under_fill."
+  },
+  "slots": [
+    {
+      "slot_id": "SLOT-GROUND-STATE",
+      "role": "prepare the lattice ground state psi that both channels read",
+      "channel": "state",
+      "provided_by": "qig-verification (engine) + TeNPy DMRG-complex",
+      "provider_pkg": null,
+      "primitive": "DMRG/MPS ground-state preparation vs ED",
+      "probe": "tenpy",
+      "cam_id": "CAM-STATE-DMRG-VS-ED",
+      "cert_status": "CERTIFIED",
+      "feasible_at": "L>=6 via MPS/DMRG"
+    },
+    {
+      "slot_id": "SLOT-Q-QFI",
+      "role": "quantum Fisher information (Q channel) -- exact, tensor-contractible",
+      "channel": "Q",
+      "provided_by": "qig-compute",
+      "provider_pkg": "qig-compute",
+      "primitive": "qfi.qfi_from_mps_tangent_space(psi_mps, L)",
+      "probe": "qig_compute.qfi:qfi_from_mps_tangent_space",
+      "cam_id": "CAM-QFI-MPS-TANGENT",
+      "cert_status": "CERTIFIED",
+      "feasible_at": "all L (O(chi^3) contraction, no sampling, zero error bar)",
+      "alternatives": ["CAM-QFI-DENSE-STREAMING", "CAM-QFI-BITFLIP", "CAM-QFI-SPARSE-NN", "CAM-QFI-SITE-PRUNE", "CAM-QFI-SITELOCAL"]
+    },
+    {
+      "slot_id": "SLOT-C-SUSCEPTIBILITY-REF",
+      "role": "classical / phase-blind Bhattacharyya fidelity-susceptibility (C channel) EXACT reference",
+      "channel": "C",
+      "provided_by": "qig-compute",
+      "provider_pkg": "qig-compute",
+      "primitive": "qfi.classical_fidelity_susceptibility(p_plus, p_minus, eps)",
+      "probe": "qig_compute.qfi:classical_fidelity_susceptibility",
+      "cam_id": "CAM-C-DENSE-REF",
+      "cert_status": "REFERENCE",
+      "feasible_at": "L<=5 ONLY (dense Born p over 2^N states; L=6 -> ~1.1 TB, infeasible)"
+    },
+    {
+      "slot_id": "SLOT-C-BORN-SAMPLER",
+      "role": "MPS Born-sampler -- the L=6-feasible C path (CERTIFIED via EXP-122 2026-06-19; PROMOTED to qig-compute 2026-06-30)",
+      "channel": "C",
+      "provided_by": "qig-compute (promoted from EXP-122 launcher born_C_score, byte-identical numerics)",
+      "provider_pkg": "qig-compute",
+      "primitive": "sampling.born_classical_fisher_score(psi_base, psi_p, psi_m, eps, M, seed): x ~ p(x) from MPS perfect (Ferris-Vidal) sampling, O(N chi^2)/sample; C = E_{x~p_base}[((log p+ - log p-)/2eps)^2] (PHASE-FREE classical-Fisher SCORE, estimator (c)). The Bhattacharyya form (estimator (a)) FAILS the 1/eps^2 variance test -- (c) is the certified estimator.",
+      "probe": "qig_compute.sampling:born_classical_fisher_score",
+      "cam_id": "CAM-C-BORN-MPS",
+      "cert_status": "CERTIFIED",
+      "shipped": true,
+      "promoted": "2026-06-30 from qig-verification/scripts/exp122_dmrg_complex.py:born_C_score (byte-identical). The frozen launcher keeps its inline copy for bit-for-bit reproducibility of the L=5 cert.",
+      "feasible_at": "L=6 (CERTIFIED at L=5: EXP-122 L=5 cert results/exp122/20260619_exp122_L5_born_cert.json @566b245 -- M=150k Delta=0.000373 bias PASS, sigma_D=0.00332 < D_sep/3=0.00473 variance PASS)."
+    },
+    {
+      "slot_id": "SLOT-SCREENING",
+      "role": "site pruning / screening lever (Yukawa shell cutoff)",
+      "channel": "lever",
+      "provided_by": "qig-warp",
+      "provider_pkg": "qig-warp",
+      "primitive": "prune_sites / screening_cutoff",
+      "probe": "qig_warp.screening:prune_sites",
+      "cam_id": "CAM-QFI-SITE-PRUNE",
+      "cert_status": "CERTIFIED"
+    },
+    {
+      "slot_id": "SLOT-EARLY-STOP",
+      "role": "convergence early-stop across the chi sub-ladder (8/16/24/32)",
+      "channel": "lever",
+      "provided_by": "qig-warp",
+      "provider_pkg": "qig-warp",
+      "primitive": "convergence.check_ci_stabilized / find_early_stop_point",
+      "probe": "qig_warp.convergence:check_ci_stabilized",
+      "lever_id": "LEV-CONVERGENCE-EARLYSTOP",
+      "cert_status": "LEVER"
+    },
+    {
+      "slot_id": "SLOT-RUNTIME-PRICING",
+      "role": "spend preflight before heavy launches",
+      "channel": "lever",
+      "provided_by": "qig-warp + chi-ladder pace-check",
+      "provider_pkg": "qig-warp",
+      "primitive": "bridge.predict_runtime (J-scaling) / chi-ladder pace-check",
+      "probe": "qig_warp.bridge:predict_runtime",
+      "lever_id": "LEV-CHI-PACE-CHECK",
+      "cert_status": "LEVER",
+      "caveat": "predict_runtime is J-scaling and is WRONG for L/chi-BOUND jobs at fixed J (EXP-122). For those, use the chi-ladder pace-check (LEV-CHI-PACE-CHECK)."
+    },
+    {
+      "slot_id": "SLOT-BLAS-PIN",
+      "role": "deterministic BLAS threading (API, not raw env-vars)",
+      "channel": "lever",
+      "provided_by": "qig-compute",
+      "provider_pkg": "qig-compute",
+      "primitive": "pin_blas_threads / single_thread_blas",
+      "probe": "qig_compute.blas:pin_blas_threads",
+      "lever_id": "LEV-BLAS-PIN",
+      "cert_status": "LEVER"
+    }
+  ],
+  "how_to_use": "Step-0 of every launcher: run `qig-doctor` (from the qig-stack package; qig-verification/scripts/qig_doctor.py is a back-compat shim). It (1) fails closed if any stack package is behind PyPI-latest, (2) fails closed on under-filled slots (a shipped provider that did not self-register its entry-point), and (3) enumerates which slots are filled by what is installed -- the automated Gate-A lever inventory. An experiment then cites the cam_id/lever_id for each slot it uses and never re-runs a matched-cell gate.",
+  "roadmap": {
+    "phase_1": "DONE -- fixed lattice (this contract) + qig_doctor.py fail-closed version preflight (qig-verification).",
+    "phase_2": "DONE 2026-06-30 -- each package self-registers its slots via [project.entry-points.'qig.capabilities'] (qig-compute, qig-warp); qig_stack.doctor derives wiring from entry-points (Tier-A metadata-only) with under-fill (FAIL) + drift (WARN) gates.",
+    "phase_3": "DONE 2026-06-30 -- qig-stack metapackage pins the mutually-tested latest set, houses the doctor + this contract, ships the qig-doctor console script; CI runs contract schema + doctor unit tests (no network).",
+    "born_sampler_promotion": "DONE 2026-06-30 -- SLOT-C-BORN-SAMPLER shipped:false -> true; born_C_score promoted to qig_compute.sampling.born_classical_fisher_score (byte-identical), gains an entry-point. CAM-C-BORN-MPS stays CERTIFIED.",
+    "activation": "entry-points go live in the installed crystal on each package's next PyPI release; cut qig-compute / qig-warp / qig-stack releases to activate (PI greenlight)."
+  }
+}

qig_stack-0.1.0/src/qig_stack/doctor.py

@@ -0,0 +1,530 @@
+#!/usr/bin/env python3
+"""qig_stack.doctor -- deterministic launch preflight (Genesis-kernel self-assembly check).
+
+Step-0 of every launcher. Three jobs, all fail-closed:
+
+  1. VERSION GATE -- every stack package must be installed at PyPI-latest.
+     installed < latest is a LAUNCH BLOCKER (non-zero exit), per
+     qig-verification/CLAUDE.md "Packages: latest version, always optimised".
+
+  2. WIRING GATE (Phase 2) -- enumerate the `qig.capabilities` entry-points the
+     installed packages self-register (Tier A: metadata-only, NO import on the
+     fail-closed path) and cross-check them against the capability contract:
+       - UNDER-FILL -> FAIL (non-zero exit): a slot whose provider package is
+         shipped but did not register its entry-point (stale / mis-built package).
+       - DRIFT -> WARN: an installed entry-point the contract does not know, or
+         one whose module:attr moved off the contract probe.
+     ACTIVATION GRACE: if NO `qig.capabilities` entry-point is installed at all,
+     the feature is not yet activated in this venv (the providers have not
+     republished with entry-points) -- the gate reports PENDING and PASSES rather
+     than false-blocking every launch. Once any provider registers, the gate is
+     strict: a missing expected slot is then a real UNDER-FILL.
+
+  3. WIRING REPORT -- which contract slots are filled by what is installed (the
+     automated Gate-A lever inventory).
+
+The contract (bundled as `qig_stack/contract.json`) is the fixed lattice the
+stack crystallizes into; this preflight checks the crystal formed correctly
+before any compute spend.
+
+Usage:
+    qig-doctor                      # full preflight, exits 1 if stale OR under-filled
+    qig-doctor --no-network         # skip PyPI (contract snapshot + wiring only)
+    qig-doctor --json               # machine-readable report
+    qig-doctor --probe              # also import-check each entry-point resolves (off the gate)
+    qig-doctor --deep               # also call Tier-B describe() descriptors (imports packages)
+    qig-doctor --contract PATH      # override the bundled contract (testing)
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import importlib.metadata as importlib_metadata
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+try:  # PEP 440-correct version comparison; `packaging` is a declared dependency.
+    from packaging.version import InvalidVersion, Version
+
+    _HAVE_PACKAGING = True
+except ImportError:  # pragma: no cover - defensive; packaging is in [project.dependencies]
+    _HAVE_PACKAGING = False
+
+CAPABILITY_GROUP = "qig.capabilities"
+PYPI_TIMEOUT_S = 10
+
+
+def _contract_path(override: str | Path | None = None) -> Path:
+    """Locate the capability contract: explicit override > env var > bundled copy."""
+    if override:
+        return Path(override)
+    env = os.environ.get("QIG_STACK_CONTRACT")
+    if env:
+        return Path(env)
+    return Path(__file__).resolve().parent / "contract.json"
+
+
+def latest_pypi_version(package: str, timeout: float = PYPI_TIMEOUT_S) -> str | None:
+    """Return the latest published version on PyPI, or None if unreachable.
+
+    Raises _PyPIAbsent on a definitive HTTP 404 (package/version genuinely not on
+    PyPI -- yanked or renamed), so the caller can distinguish that from a transient
+    network blip (which returns None -> fail-open).
+    """
+    url = f"https://pypi.org/pypi/{package}/json"
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as resp:
+            payload = json.load(resp)
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            raise _PyPIAbsent(package) from exc
+        return None
+    except (urllib.error.URLError, TimeoutError, ValueError):
+        return None
+    info = payload.get("info", {})
+    version = info.get("version")
+    return version if isinstance(version, str) else None
+
+
+class _PyPIAbsent(Exception):
+    """Definitive 'no such package/version on PyPI' (HTTP 404)."""
+
+
+def installed_version(package: str) -> str | None:
+    try:
+        return importlib_metadata.version(package)
+    except importlib_metadata.PackageNotFoundError:
+        return None
+
+
+def _parse_version(text: str) -> tuple[int, ...]:
+    """Zero-padding-agnostic release tuple (fallback only; drops local/pre/dev tails)."""
+    release = text.split("+", 1)[0]
+    parts: list[int] = []
+    for chunk in release.split("."):
+        digits = "".join(ch for ch in chunk if ch.isdigit())
+        if digits == chunk and digits:  # pure numeric release component
+            parts.append(int(digits))
+        else:  # a pre/post/dev tail (e.g. '1rc2', 'dev0') ends the release tuple
+            break
+    return tuple(parts)
+
+
+def is_behind(installed: str, latest: str) -> bool:
+    """True iff `installed` is an older version than `latest` (PEP 440-correct)."""
+    if _HAVE_PACKAGING:
+        try:
+            return Version(installed) < Version(latest)
+        except InvalidVersion:  # pragma: no cover - non-PEP440 string
+            pass
+    a, b = _parse_version(installed), _parse_version(latest)
+    n = max(len(a), len(b))
+    a += (0,) * (n - len(a))
+    b += (0,) * (n - len(b))
+    return a < b
+
+
+# ───────────────────────── Phase-2: entry-point self-registration ─────────────────────────
+def enumerate_capability_entrypoints() -> dict[str, str]:
+    """Tier A (CANONICAL): name -> "module:attr" for the qig.capabilities group.
+
+    Metadata-only -- enumerates DECLARATIONS without importing any package, so it
+    can never run package code and cannot inject non-determinism into a launch.
+    Requires the Python 3.10+ selectable entry_points(group=) API (requires-python>=3.10).
+    """
+    return {ep.name: ep.value for ep in importlib_metadata.entry_points(group=CAPABILITY_GROUP)}
+
+
+@dataclass
+class WiringIssue:
+    slot_id: str
+    kind: str  # UNDER_FILL | DRIFT_UNKNOWN | DRIFT_MOVED
+    detail: str
+
+
+def check_entrypoint_wiring(
+    slots: list[dict], declared: dict[str, str]
+) -> tuple[list[WiringIssue], list[WiringIssue]]:
+    """Cross-check declared qig.capabilities entry-points against the contract lattice.
+
+    Returns (underfill, drift). Pure function -- `declared` is injected so this is
+    unit-testable without a live environment.
+      - UNDER_FILL (FAIL): a slot with provider_pkg set and shipped != false but no
+        declared entry-point -- ONLY when the feature is activated (declared is
+        non-empty). An empty `declared` means the feature is not yet live in this
+        venv (providers not republished) -> no under-fill (see build_report's
+        wiring_activation = PENDING).
+      - DRIFT (WARN): a declared entry-point whose slot_id is not in the contract
+        (DRIFT_UNKNOWN), or whose value differs from the slot probe (DRIFT_MOVED).
+    """
+    underfill: list[WiringIssue] = []
+    drift: list[WiringIssue] = []
+    by_id = {s["slot_id"]: s for s in slots}
+    group_active = bool(declared)
+
+    if group_active:
+        for slot in slots:
+            provider = slot.get("provider_pkg")
+            shipped = slot.get("shipped", True)
+            expected = provider is not None and shipped is not False
+            if expected and slot["slot_id"] not in declared:
+                underfill.append(
+                    WiringIssue(
+                        slot["slot_id"],
+                        "UNDER_FILL",
+                        f"{provider} ships this slot but registered no '{CAPABILITY_GROUP}' "
+                        f"entry-point (probe {slot.get('probe')!r}); stale or mis-built package.",
+                    )
+                )
+
+    for name, value in declared.items():
+        slot = by_id.get(name)
+        if slot is None:
+            drift.append(
+                WiringIssue(name, "DRIFT_UNKNOWN", f"entry-point '{name}={value}' is not a contract slot_id")
+            )
+        elif slot.get("probe") and value != slot["probe"]:
+            drift.append(
+                WiringIssue(
+                    name,
+                    "DRIFT_MOVED",
+                    f"entry-point value {value!r} != contract probe {slot['probe']!r}",
+                )
+            )
+
+    return underfill, drift
+
+
+def _expected_slot_ids(slots: list[dict]) -> list[str]:
+    return [
+        s["slot_id"]
+        for s in slots
+        if s.get("provider_pkg") is not None and s.get("shipped", True) is not False
+    ]
+
+
+@dataclass
+class PackageCheck:
+    package: str
+    installed: str | None
+    latest: str | None
+    status: str  # OK | STALE | MISSING | LATEST_UNKNOWN | PYPI_ABSENT
+
+
+@dataclass
+class SlotCheck:
+    slot_id: str
+    cite: str
+    cert_status: str
+    provided_by: str
+    filled: str  # FILLED | MISSING | UNSHIPPED | PKG_ABSENT
+    entrypoint: str  # DECLARED | ABSENT | DRIFT | EXEMPT | UNSHIPPED | PENDING
+
+
+@dataclass
+class Report:
+    contract: str
+    packages: list[PackageCheck] = field(default_factory=list)
+    slots: list[SlotCheck] = field(default_factory=list)
+    entrypoint_underfill: list[WiringIssue] = field(default_factory=list)
+    entrypoint_drift: list[WiringIssue] = field(default_factory=list)
+    wiring_activation: str = "N/A"  # ACTIVE | PENDING | N/A
+    version_gate_passed: bool = True
+    wiring_gate_passed: bool = True
+
+
+def check_packages(latest_versions: dict[str, str], use_network: bool) -> list[PackageCheck]:
+    checks: list[PackageCheck] = []
+    for package in sorted(latest_versions):
+        installed = installed_version(package)
+        if use_network:
+            try:
+                latest = latest_pypi_version(package)
+            except _PyPIAbsent:
+                checks.append(PackageCheck(package, installed, None, "PYPI_ABSENT"))
+                continue
+        else:
+            latest = latest_versions[package]
+        if installed is None:
+            status = "MISSING"
+        elif latest is None:
+            status = "LATEST_UNKNOWN"
+        elif is_behind(installed, latest):
+            status = "STALE"
+        else:
+            status = "OK"
+        checks.append(PackageCheck(package, installed, latest, status))
+    return checks
+
+
+def _module_importable(probe: str | None) -> bool:
+    if not probe:
+        return False
+    top = probe.partition(":")[0].split(".")[0]
+    try:
+        importlib.import_module(top)
+        return True
+    except ImportError:
+        return False
+
+
+def _probe_filled(probe: str | None) -> bool:
+    """A slot is filled if its probe imports. `module:attr` also checks the attr."""
+    if not probe:
+        return False
+    module_name, _, attr = probe.partition(":")
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError:
+        return False
+    if attr:
+        return hasattr(module, attr)
+    return True
+
+
+def check_slots(slots: list[dict], declared: dict[str, str]) -> list[SlotCheck]:
+    checks: list[SlotCheck] = []
+    group_active = bool(declared)
+    for slot in slots:
+        cite = slot.get("cam_id") or slot.get("lever_id") or "(uncited)"
+        provided_by = slot.get("provided_by", "")
+        probe = slot.get("probe")
+        provider = slot.get("provider_pkg")
+        shipped = slot.get("shipped", True)
+
+        # UNSHIPPED is a PACKAGE/wiring status, orthogonal to cert_status.
+        if shipped is False or (slot.get("cert_status") == "PENDING" and probe is None):
+            filled = "UNSHIPPED"
+        elif _probe_filled(probe):
+            filled = "FILLED"
+        elif _module_importable(probe):
+            filled = "MISSING"  # package present, symbol gone
+        else:
+            filled = "PKG_ABSENT"
+
+        # entry-point dimension (Phase 2)
+        if provider is None:
+            entrypoint = "EXEMPT"
+        elif shipped is False:
+            entrypoint = "UNSHIPPED"
+        elif slot["slot_id"] in declared:
+            entrypoint = "DRIFT" if (probe and declared[slot["slot_id"]] != probe) else "DECLARED"
+        elif group_active:
+            entrypoint = "ABSENT"
+        else:
+            entrypoint = "PENDING"  # feature not yet activated in this venv
+
+        checks.append(
+            SlotCheck(
+                slot_id=slot["slot_id"],
+                cite=cite,
+                cert_status=slot.get("cert_status", ""),
+                provided_by=provided_by,
+                filled=filled,
+                entrypoint=entrypoint,
+            )
+        )
+    return checks
+
+
+class ContractError(Exception):
+    """The capability contract is missing, unreadable, or malformed."""
+
+
+def _load_contract(contract_path: Path) -> dict:
+    try:
+        data = json.loads(Path(contract_path).read_text())
+    except FileNotFoundError as exc:
+        raise ContractError(f"contract not found at {contract_path}") from exc
+    except json.JSONDecodeError as exc:
+        raise ContractError(f"contract at {contract_path} is not valid JSON: {exc}") from exc
+    if "slots" not in data or "version_policy" not in data:
+        raise ContractError(
+            f"contract at {contract_path} missing required keys ('slots', 'version_policy')"
+        )
+    try:
+        data["version_policy"]["stack_packages_latest_at_authoring"]
+    except (KeyError, TypeError) as exc:
+        raise ContractError(
+            f"contract at {contract_path} missing version_policy.stack_packages_latest_at_authoring"
+        ) from exc
+    return data
+
+
+def build_report(
+    contract_path: Path,
+    use_network: bool,
+    declared: dict[str, str] | None = None,
+) -> Report:
+    contract = _load_contract(Path(contract_path))
+    latest_versions = contract["version_policy"]["stack_packages_latest_at_authoring"]
+    slots = contract["slots"]
+    if declared is None:
+        declared = enumerate_capability_entrypoints()
+
+    report = Report(contract=str(contract_path))
+    report.packages = check_packages(latest_versions, use_network)
+    report.slots = check_slots(slots, declared)
+    report.entrypoint_underfill, report.entrypoint_drift = check_entrypoint_wiring(slots, declared)
+
+    if not _expected_slot_ids(slots):
+        report.wiring_activation = "N/A"
+    elif declared:
+        report.wiring_activation = "ACTIVE"
+    else:
+        report.wiring_activation = "PENDING"
+
+    report.version_gate_passed = all(
+        pkg.status in ("OK", "LATEST_UNKNOWN", "PYPI_ABSENT") for pkg in report.packages
+    )
+    report.wiring_gate_passed = not report.entrypoint_underfill
+    return report
+
+
+def probe_entrypoints(declared: dict[str, str]) -> dict[str, bool]:
+    """Optional `--probe`: import-check that each entry-point module:attr resolves.
+
+    This IMPORTS packages, so it is OFF the fail-closed gate -- a diagnostic only.
+    """
+    return {name: _probe_filled(value) for name, value in declared.items()}
+
+
+def deep_descriptors() -> list[dict]:
+    """Optional Tier-B `--deep`: call any `_descriptor` describe() entry-points.
+
+    IMPORTS + EXECUTES package code; FORBIDDEN on the fail-closed gate, behind --deep only.
+    """
+    out: list[dict] = []
+    for ep in importlib_metadata.entry_points(group=CAPABILITY_GROUP):
+        if ep.name != "_descriptor":
+            continue
+        try:
+            result = ep.load()()
+            if isinstance(result, list):
+                out.extend(result)
+        except Exception as exc:  # noqa: BLE001 - diagnostic, never gates
+            out.append({"error": f"{ep.value}: {exc}"})
+    return out
+
+
+_GLYPH = {
+    "OK": "ok ",
+    "STALE": "STALE",
+    "MISSING": "MISSING",
+    "LATEST_UNKNOWN": "lat?",
+    "PYPI_ABSENT": "404!",
+    "FILLED": "filled",
+    "UNSHIPPED": "UNSHIPPED",
+    "PKG_ABSENT": "pkg-absent",
+    "DECLARED": "ep-ok",
+    "ABSENT": "ep-ABSENT",
+    "DRIFT": "ep-DRIFT",
+    "EXEMPT": "exempt",
+    "PENDING": "ep-pending",
+}
+
+
+def print_report(report: Report, use_network: bool) -> None:
+    print(f"qig-doctor -- preflight against {report.contract}")
+    print(f"  version source: {'PyPI (live)' if use_network else 'contract snapshot'}\n")
+    print("  VERSION GATE (installed must equal latest-published):")
+    for pkg in report.packages:
+        print(
+            f"    [{_GLYPH[pkg.status]:>6}] {pkg.package:<18}"
+            f" installed={pkg.installed or '-':<28} latest={pkg.latest or '-'}"
+        )
+    print(f"\n  WIRING REPORT (slots -> installed / entry-point) [activation: {report.wiring_activation}]:")
+    for slot in report.slots:
+        print(
+            f"    [{_GLYPH[slot.filled]:>10}|{_GLYPH.get(slot.entrypoint, slot.entrypoint):>10}]"
+            f" {slot.slot_id:<26} {slot.cite:<22} ({slot.cert_status}) via {slot.provided_by}"
+        )
+
+    if report.entrypoint_drift:
+        print("\n  WIRING DRIFT (WARN -- contract bump may be needed):")
+        for issue in report.entrypoint_drift:
+            print(f"    [{issue.kind}] {issue.slot_id}: {issue.detail}")
+
+    absent = [p.package for p in report.packages if p.status == "PYPI_ABSENT"]
+    if absent:
+        print(f"\n  NOTE: PyPI returned 404 for: {', '.join(absent)} (yanked/renamed? -- could not verify latest)")
+
+    stale = [p.package for p in report.packages if p.status in ("STALE", "MISSING")]
+    print()
+    if report.version_gate_passed:
+        print("  VERSION GATE: PASS")
+    else:
+        print(f"  VERSION GATE: FAIL -- stale/missing: {', '.join(stale)}")
+        print("  -> LAUNCH BLOCKED. Update to latest published before launching:")
+        print(f"     uv pip install -U {' '.join(stale)}")
+
+    if report.wiring_activation == "PENDING":
+        print("  WIRING GATE: PENDING ACTIVATION -- no qig.capabilities entry-points installed")
+        print("     (providers not yet republished with entry-points; not a blocker).")
+    elif report.wiring_gate_passed:
+        print("  WIRING GATE: PASS")
+    else:
+        under = ", ".join(i.slot_id for i in report.entrypoint_underfill)
+        print(f"  WIRING GATE: FAIL -- under-filled slots: {under}")
+        print("  -> LAUNCH BLOCKED. A shipped provider did not self-register its")
+        print("     qig.capabilities entry-point (stale / mis-built package).")
+        for issue in report.entrypoint_underfill:
+            print(f"     - {issue.slot_id}: {issue.detail}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="qig launch preflight (version gate + entry-point wiring gate + report)"
+    )
+    parser.add_argument(
+        "--no-network", action="store_true", help="skip PyPI; use contract snapshot"
+    )
+    parser.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    parser.add_argument(
+        "--probe", action="store_true", help="import-check each entry-point resolves (off the gate)"
+    )
+    parser.add_argument(
+        "--deep", action="store_true", help="call Tier-B describe() descriptors (imports packages)"
+    )
+    parser.add_argument("--contract", default=None, help="override the bundled contract path")
+    args = parser.parse_args(argv)
+
+    use_network = not args.no_network
+    try:
+        report = build_report(_contract_path(args.contract), use_network)
+    except ContractError as exc:
+        sys.stderr.write(f"qig-doctor: {exc}\n  -> LAUNCH BLOCKED (preflight fail-closed).\n")
+        return 1
+
+    extras: dict[str, object] = {}
+    if args.probe:
+        extras["entrypoint_probe"] = probe_entrypoints(enumerate_capability_entrypoints())
+    if args.deep:
+        extras["descriptors"] = deep_descriptors()
+
+    if args.json:
+        payload = asdict(report)
+        payload.update(extras)
+        print(json.dumps(payload, indent=2))
+    else:
+        print_report(report, use_network)
+        if "entrypoint_probe" in extras:
+            print("\n  ENTRY-POINT PROBE (import resolve-check):")
+            for name, ok in extras["entrypoint_probe"].items():  # type: ignore[union-attr]
+                print(f"    [{'ok ' if ok else 'FAIL':>4}] {name}")
+        if "descriptors" in extras:
+            print("\n  TIER-B DESCRIPTORS (--deep):")
+            for d in extras["descriptors"]:  # type: ignore[union-attr]
+                print(f"    {d}")
+
+    return 0 if (report.version_gate_passed and report.wiring_gate_passed) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

qig_stack-0.1.0/tests/test_contract.py

@@ -0,0 +1,63 @@
+"""Schema tests for the bundled QIG Stack Capability Contract (no network)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+CONTRACT = Path(__file__).resolve().parent.parent / "src" / "qig_stack" / "contract.json"
+
+
+def _load() -> dict:
+    return json.loads(CONTRACT.read_text())
+
+
+def test_contract_present():
+    assert CONTRACT.exists(), "bundled contract.json missing from src/qig_stack/"
+
+
+def test_contract_top_level_schema():
+    data = _load()
+    for key in ("doc", "version", "version_policy", "slots", "entry_point_group"):
+        assert key in data, f"contract missing top-level key: {key}"
+    assert data["entry_point_group"] == "qig.capabilities"
+    latest = data["version_policy"]["stack_packages_latest_at_authoring"]
+    for pkg in ("qig-compute", "qig-warp", "qig-core", "qig-bench"):
+        assert pkg in latest, f"version snapshot missing {pkg}"
+
+
+def test_slots_well_formed():
+    data = _load()
+    seen: set[str] = set()
+    for slot in data["slots"]:
+        sid = slot["slot_id"]
+        assert sid not in seen, f"duplicate slot_id {sid}"
+        seen.add(sid)
+        assert "cert_status" in slot
+        assert slot.get("cam_id") or slot.get("lever_id"), f"{sid} cites no cam/lever id"
+        # provider_pkg is mandatory (may be null for engine-local slots)
+        assert "provider_pkg" in slot, f"{sid} missing provider_pkg"
+
+
+def test_provider_slots_have_full_module_attr_probe():
+    """Every PyPI-provided, shipped slot must carry a module:attr probe == its entry-point."""
+    data = _load()
+    for slot in data["slots"]:
+        if slot.get("provider_pkg") and slot.get("shipped", True) is not False:
+            probe = slot.get("probe", "")
+            assert ":" in probe, f"{slot['slot_id']} probe {probe!r} is not module:attr"
+
+
+def test_born_sampler_promoted():
+    data = _load()
+    born = next(s for s in data["slots"] if s["slot_id"] == "SLOT-C-BORN-SAMPLER")
+    assert born["shipped"] is True, "born sampler should be shipped after promotion"
+    assert born["provider_pkg"] == "qig-compute"
+    assert born["probe"] == "qig_compute.sampling:born_classical_fisher_score"
+    assert born["cert_status"] == "CERTIFIED"
+
+
+def test_ground_state_is_engine_local():
+    data = _load()
+    gs = next(s for s in data["slots"] if s["slot_id"] == "SLOT-GROUND-STATE")
+    assert gs["provider_pkg"] is None, "ground-state slot is engine-local (no PyPI entry-point)"

qig_stack-0.1.0/tests/test_doctor.py

@@ -0,0 +1,166 @@
+"""Unit tests for qig_stack.doctor -- version compare, slot fill, entry-point cross-check.
+
+Network-free: the entry-point wiring is exercised by INJECTING a `declared` dict, so
+these tests do not depend on what is installed in the environment.
+"""
+
+from __future__ import annotations
+
+import json
+
+from qig_stack import doctor
+
+
+def _contract_slots() -> list[dict]:
+    return json.loads(doctor._contract_path().read_text())["slots"]
+
+
+def _all_expected_declared() -> dict[str, str]:
+    """The fully-wired crystal: every shipped, PyPI-provided slot declared at its probe."""
+    return {
+        s["slot_id"]: s["probe"]
+        for s in _contract_slots()
+        if s.get("provider_pkg") and s.get("shipped", True) is not False
+    }
+
+
+# ───────────────────────── version gate (PEP 440-correct) ─────────────────────────
+def test_version_comparison_logic():
+    assert doctor.is_behind("0.6.2", "0.9.1") is True
+    assert doctor.is_behind("0.9.1", "0.9.1") is False
+    assert doctor.is_behind("0.9.2", "0.9.1") is False
+    assert doctor.is_behind("0.2.0", "0.2.7") is True
+    assert doctor.is_behind("2.9.0", "2.12.2") is True  # multi-digit minor
+
+
+def test_version_comparison_prerelease_and_local():
+    # a dev/rc build is BEHIND its final release (the false-PASS the review caught)
+    assert doctor.is_behind("0.9.1.dev3", "0.9.1") is True
+    assert doctor.is_behind("0.9.1rc1", "0.9.1") is True
+    assert doctor.is_behind("0.9.2.dev8+g083281", "0.9.1") is False  # dev of a newer release
+    # a post-release is AHEAD of its base release
+    assert doctor.is_behind("1.0.0.post1", "1.0.0") is False
+    # trailing-zero normalisation must not false-FAIL
+    assert doctor.is_behind("1.0", "1.0.0") is False
+    assert doctor.is_behind("2.12", "2.12.0") is False
+
+
+# ───────────────────────── entry-point wiring gate (activation grace) ─────────────────────────
+def test_wiring_clean_when_fully_declared():
+    slots = _contract_slots()
+    underfill, drift = doctor.check_entrypoint_wiring(slots, _all_expected_declared())
+    assert underfill == []
+    assert drift == []
+
+
+def test_wiring_pending_when_nothing_declared():
+    """Empty group = feature not yet activated -> NO under-fill (grace, not a false-FAIL)."""
+    slots = _contract_slots()
+    underfill, drift = doctor.check_entrypoint_wiring(slots, {})
+    assert underfill == []
+    assert drift == []
+
+
+def test_wiring_underfill_on_partial_activation():
+    """Once ANY provider registers, a missing expected slot is a real UNDER_FILL."""
+    slots = _contract_slots()
+    declared = _all_expected_declared()
+    missing = declared.pop("SLOT-Q-QFI")  # qig-compute registered the rest but not this
+    assert missing
+    underfill, _ = doctor.check_entrypoint_wiring(slots, declared)
+    assert {i.slot_id for i in underfill} == {"SLOT-Q-QFI"}
+    assert all(i.kind == "UNDER_FILL" for i in underfill)
+
+
+def test_wiring_exempts_engine_local_on_partial_activation():
+    slots = _contract_slots()
+    declared = _all_expected_declared()
+    declared.pop("SLOT-BLAS-PIN")  # force partial activation
+    underfill, _ = doctor.check_entrypoint_wiring(slots, declared)
+    ids = {i.slot_id for i in underfill}
+    assert "SLOT-GROUND-STATE" not in ids  # provider_pkg=null is never under-fill
+
+
+def test_wiring_drift_unknown_slot():
+    slots = _contract_slots()
+    declared = _all_expected_declared()
+    declared["SLOT-MADE-UP"] = "qig_compute.nowhere:ghost"
+    _, drift = doctor.check_entrypoint_wiring(slots, declared)
+    assert any(i.kind == "DRIFT_UNKNOWN" and i.slot_id == "SLOT-MADE-UP" for i in drift)
+
+
+def test_wiring_drift_moved_value():
+    slots = _contract_slots()
+    declared = _all_expected_declared()
+    declared["SLOT-Q-QFI"] = "qig_compute.somewhere_else:qfi_from_mps_tangent_space"
+    _, drift = doctor.check_entrypoint_wiring(slots, declared)
+    assert any(i.kind == "DRIFT_MOVED" and i.slot_id == "SLOT-Q-QFI" for i in drift)
+
+
+# ───────────────────────── report assembly (offline) ─────────────────────────
+def test_build_report_offline_fully_wired():
+    report = doctor.build_report(
+        doctor._contract_path(), use_network=False, declared=_all_expected_declared()
+    )
+    assert report.packages, "no package checks produced"
+    assert report.slots, "no slot checks produced"
+    assert report.wiring_activation == "ACTIVE"
+    assert report.wiring_gate_passed is True
+    born = next(s for s in report.slots if s.slot_id == "SLOT-C-BORN-SAMPLER")
+    assert born.entrypoint == "DECLARED"
+    gs = next(s for s in report.slots if s.slot_id == "SLOT-GROUND-STATE")
+    assert gs.entrypoint == "EXEMPT"
+
+
+def test_build_report_pending_passes_wiring():
+    """Un-activated venv (no entry-points) -> PENDING, gate PASSES (no false block)."""
+    report = doctor.build_report(doctor._contract_path(), use_network=False, declared={})
+    assert report.wiring_activation == "PENDING"
+    assert report.wiring_gate_passed is True
+    assert report.entrypoint_underfill == []
+    born = next(s for s in report.slots if s.slot_id == "SLOT-C-BORN-SAMPLER")
+    assert born.entrypoint == "PENDING"
+
+
+def test_build_report_partial_activation_fails_wiring():
+    declared = _all_expected_declared()
+    declared.pop("SLOT-SCREENING")
+    report = doctor.build_report(doctor._contract_path(), use_network=False, declared=declared)
+    assert report.wiring_activation == "ACTIVE"
+    assert report.wiring_gate_passed is False
+    assert {i.slot_id for i in report.entrypoint_underfill} == {"SLOT-SCREENING"}
+
+
+# ───────────────────────── malformed contract (fail-closed, no traceback) ─────────────────────────
+def test_malformed_contract_raises_contract_error(tmp_path):
+    bad = tmp_path / "broken.json"
+    bad.write_text("{ not valid json ")
+    import pytest
+
+    with pytest.raises(doctor.ContractError):
+        doctor.build_report(bad, use_network=False, declared={})
+
+
+def test_missing_keys_contract_raises_contract_error(tmp_path):
+    bad = tmp_path / "incomplete.json"
+    bad.write_text(json.dumps({"doc": "x", "slots": []}))  # no version_policy
+    import pytest
+
+    with pytest.raises(doctor.ContractError):
+        doctor.build_report(bad, use_network=False, declared={})
+
+
+def test_main_offline_runs(capsys):
+    rc = doctor.main(["--no-network", "--contract", str(doctor._contract_path())])
+    out = capsys.readouterr().out
+    assert "VERSION GATE" in out and "WIRING" in out
+    assert rc in (0, 1)
+
+
+def test_main_malformed_contract_returns_1(tmp_path, capsys):
+    bad = tmp_path / "broken.json"
+    bad.write_text("nonsense")
+    rc = doctor.main(["--no-network", "--contract", str(bad)])
+    err = capsys.readouterr().err
+    assert rc == 1
+    assert "LAUNCH BLOCKED" in err