Metadata-Version: 2.5
Name: qig-stack
Version: 0.1.2
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.11
Requires-Dist: packaging>=22
Requires-Dist: qig-bench==0.1.9
Requires-Dist: qig-compute==0.9.10
Requires-Dist: qig-coordizer==0.1.5
Requires-Dist: qig-core==2.15.3
Requires-Dist: qig-geocoding==0.1.2
Requires-Dist: qig-warp==0.6.10
Requires-Dist: qigkernels==0.4.5
Requires-Dist: quner==0.1.3
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
(see `pyproject.toml` and the bundled capability contract) 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 --release-check # release acceptance: live latest, required wiring, all probes resolve
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 packaging  # doctor uses packaging for PEP 440 versions
pytest -q                 # contract schema + doctor unit tests (no network)
```

## Active release set

The dependency pins and bundled contract describe the same tested release set.
Retired qig-consciousness and qig-tokenizer are excluded; qig-coordizer supplies
active coordization. qig-geocoding and quner are included as active libraries and
tools. Installing quner does not enable its daemon or modify system power settings.
The doctor checks package availability and capability wiring; an import check is
not an experimental certification or a performance benchmark.

Release acceptance installs the published pinned wheels into a clean environment,
runs the doctor with live package metadata and probes, and records any hardware-only
checks separately. Frozen experiment environments keep their historical pins.

## Verification boundaries

PyPI timeouts, malformed versions and HTTP 404 responses are unverified states,
not successful latest-version checks. They fail the version gate. Ahead/local
builds also do not equal the latest published version. Offline mode compares the
contract snapshot and reports `latest_verified: false`, even if that comparison
passes. Retry live verification when connectivity is restored.

The current contract sets `entry_point_gates.require_activation: true`: all
required shipped declarations must exist, including when the entire group is
empty. Historical contracts can retain their initial rollout grace explicitly by
omitting that setting; the pure wiring helper preserves that compatibility.

The Phase 2/3 design deliberately kept `--probe` diagnostic and non-gating;
that remains true. For release acceptance use `qig-doctor --release-check --json`.
It requires live PyPI equality, equality to the mutually-tested contract pins,
required declarations, successful import probes
and no moved contract probes, and emits `release_gate_passed` with a nonzero exit
on failure. `--no-network` cannot be combined with release checking. Unknown
additional capability declarations remain warnings if they resolve. This command
imports packages, but does not run physics experiments or enable daemons.

Runtime `qig_stack.__version__` reads installed distribution metadata using
[importlib.metadata](https://docs.python.org/3/library/importlib.metadata.html),
with `0+uninstalled` only when no distribution metadata exists. It is not a
second manually maintained version constant.

`qig-doctor` is the console entry point for `qig_stack.doctor:main`; the equivalent
module command is `python -m qig_stack.doctor`. Package-version coverage includes
every contract package. Capability coverage includes shipped slots with a declared
`provider_pkg`; engine-local (`provider_pkg: null`) and explicitly unshipped slots
are exempt. A package with no contract capability slots is still version-checked;
this is not an assertion that its features were exercised. Integration acceptance
must additionally exercise the actual cooperating package APIs.
