QPGF

QPGF is a deterministic verification termination oracle for FTQC quantum modules:

exit 0  <=>  <id>.sealed.json exists  <=>  the generation loop terminates

QPGF is not an "agentic quantum factory." The defensible core is narrower and stronger: if a module cannot be verified, it is not sealed; only sealed modules may enter registry composition. The AI runtime may generate and repair candidate modules, but the termination condition is deterministic code.

Status

• Research artifact, not a production security boundary.
• MIT licensed.
• Core oracle bundle is self-contained over Python, NumPy, Qualtran, Cirq, and PyZX.
• Current verification target: 157 green checks across 11 suites.
• Signatures are tamper-evident deterministic hashes, not private-key cryptographic signatures.
• Release integrity is signed with Sigstore keyless CI (no private key) and checked by verify_bundle.
• QPGF is the verification core of a broader AI-native quantum foundry vision (QuantaFoundry); this repository is the standalone, defensible oracle. See DEPLOYMENT-TRUST.md for the release trust model.

What Is New

QPGF does not claim that exact tensor verification, stabilizer-tableau reasoning, or ZX equivalence checking are new. Those techniques already exist in systems such as VOQC/SQIR/Qbricks and MQT QCEC.

The novelty is the system integration:

• deterministic phase-preserving verification is used as the binary stop condition for AI repair loops;
• a *.sealed.json artifact is the only accepted proof of completion;
• registry rules enforce that only sealed modules can be composed;
• FTQC resource accounting, especially T-count and magic-state cost, is bound into the seal;
• larger applications can be built by composing sealed leaves and then sealing the composition.

In short:

AI generates.
ContractGate verifies.
Registry admits only sealed modules.
Composition re-verifies before sealing again.

Architecture

GenCore              ->  ContractGate                  ->  ResourceCore
AI/runtime generation    deterministic verification        FTQC cost accounting
PG/PPR specs             C1-C4 contracts                   Qualtran QECGatesCost
candidate code           sealed artifact                   resource in seal

Boundary invariant:

• AI may generate, decompose, orchestrate, and repair.
• Deterministic code performs contract verification and resource accounting.
• The oracle does not implement the loop. Runtime-native loops call the oracle until exit 0.

Seal Tiers

Tier	Scope	Method	Meaning
Tier 0 EXACT	Small dense modules/apps	dense unitary plus golden comparison	canonical exact seal
Tier 1 STRUCTURAL	Large app trees with sealed children	Merkle-style hash over child seals and wiring	correct-by-construction composition
Tier 2 CLIFFORD	Large Clifford circuits	stabilizer tableau canonicalization	exact dense-free Clifford seal
Tier 3 CLIFFORD+T	Larger universal circuits with reference circuit	ZX-calculus equivalence via PyZX	sound if equivalence is proved; conservative refusal otherwise

Probabilistic measurement checks are advisory only. They are not seals.

Contracts

The oracle enforces:

• C1 FullCharacterization: the candidate has a complete unitary or valid isometry of the declared shape.
• C2 PhasePreserved: the candidate is unitary/isometric, so complex amplitudes and phases are preserved.
• C3 AncillaClean / C3-iso: supported ancilla forms must be clean or faithful.
• C4 ComposableContract: the candidate matches an independent golden reference up to global phase, or a composition is re-verified.
• C-app: a decomposed application must match its declared application-level intent.

Canonical convention: Qualtran-native raw big-endian tensor_contract() output. The first register is the MSB.

Quickstart

Install the runtime dependencies:

pip install numpy qualtran cirq pyzx

Run a single seal:

python .agents/skills/qpgf-oracle/scripts/spec_guard.py \
       .agents/skills/qpgf-oracle/examples/qft2.pg

python .agents/skills/qpgf-oracle/scripts/verify_seal.py \
       .agents/skills/qpgf-oracle/examples/qft2.pg --out ./_seal

Success means:

exit 0
_seal/qft2.sealed.json exists

Determinism check:

python .agents/skills/qpgf-oracle/scripts/verify_seal.py \
       .agents/skills/qpgf-oracle/examples/qft2.pg --out ./_seal_a
python .agents/skills/qpgf-oracle/scripts/verify_seal.py \
       .agents/skills/qpgf-oracle/examples/qft2.pg --out ./_seal_b
diff ./_seal_a/qft2.sealed.json ./_seal_b/qft2.sealed.json

Full Verification

python qcore/test_qcore.py
python .agents/skills/qpgf-oracle/scripts/test_contracts.py
python .agents/skills/qpgf-oracle/scripts/test_verify_seal.py
python .agents/skills/qpgf-oracle/scripts/test_spec_guard.py
python .agents/skills/qpgf-oracle/scripts/test_golden_guard.py
python .agents/skills/qpgf-oracle/scripts/test_registry.py
python .agents/skills/qpgf-oracle/scripts/test_app_assemble.py
python .agents/skills/qpgf-oracle/scripts/test_bundle_manifest.py
python .agents/skills/qpgf-oracle/scripts/test_clifford_seal.py
python .agents/skills/qpgf-oracle/scripts/test_zx_seal.py
python .agents/skills/qpgf-oracle/scripts/test_verify_bundle.py

Expected state: 152 green checks.

Prior Art Positioning

Prior system	What it provides	How QPGF differs
VOQC / SQIR / Qbricks	formal quantum semantics and proof-oriented verification	QPGF reuses the verification idea as an automated seal gate for AI loops
MQT QCEC / ZX-based checking	circuit equivalence checking	QPGF can use equivalence engines as sealing backends plus registry/resource integration
Qualtran / resource estimators	FTQC-oriented cost analysis	QPGF binds resource accounting into the verification artifact
agentic quantum search or RL loops	generation/search signal	QPGF supplies a deterministic binary termination oracle

Useful references include VOQC/SQIR/Qbricks, MQT QCEC, design-by-contract work for quantum software, Qualtran, and ZX-calculus tooling.

Trust Model

The seal is deterministic and tamper-evident:

• u_hash fingerprints the verified unitary/isometry.
• sig is a deterministic hash over canonical seal fields.
• code fingerprints can bind the seal to the oracle bundle that produced it.
• BUNDLE.sha256 tracks bundle integrity.

This is not enough to trust an arbitrary release by itself. A verifier should first validate the bundle manifest and release signature, then re-run the oracle locally. See DEPLOYMENT-TRUST.md.

Repository Map

README.md
LICENSE
docs/
  QPGF-Technical-Spec.md
  CONVENTION.md
qcore/
  qcore.py
  test_qcore.py
  qcore-spec.md
.agents/skills/qpgf-oracle/
  SKILL.md
  scripts/
  references/
  examples/
  DEPENDENCIES.lock
  BUNDLE.sha256
.pgf/
  DESIGN-*.md
  ANALYSIS-*.md
  multiruntime/
  crossgen/

Limits

• Dense exact tensor verification is small-N by nature.
• Tier 1 structural seals trust the decomposition plan as the intent.
• ZX-based Tier 3 checking is conservative: if equivalence is not proved, the module is not sealed.
• A golden reference must be correct and independent; the oracle checks agreement with it, not its philosophical intent.
• Release trust requires a signed bundle or an equivalent out-of-band trust anchor.

License

MIT. See LICENSE.