zephirum 2.1.0__py3-none-any.whl

battery_ci.py

@@ -0,0 +1,95 @@
+# -*- coding: utf-8 -*-
+"""ZQ-GATE CI battery — the trivalent decision battery + receipt verification.
+
+Runs entirely offline (noiseless kernel, no IBM account needed) so any CI can
+use it. Modes via env ZQG_MODE (all | battery | verify-receipts):
+  battery         -> run the trivalent decision battery: constant-1 => 1,
+                     constant-0 => 0, balanced => REFUSED, 1 oracle call each.
+  verify-receipts-> recompute the SHA3-256 seal of every sealed receipt in
+                     experiments/ (Z-QEA, clean canonical rule).
+Exit code 0 = all pass. Any failure exits 1 — nothing passes silently.
+"""
+import os, sys, json, hashlib, glob
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, "..", "src"))
+
+MODE = (os.environ.get("ZQG_MODE") or "all").strip().lower()
+FAILED = []
+
+
+def run_battery():
+    from zyql_quantum_gate import ZYQLQuantumGate
+    cases = [
+        ("constant-1", lambda x: 1, "1"),
+        ("constant-0", lambda x: 0, "0"),
+        ("balanced",   lambda x: x ^ 1, "REFUSED"),
+    ]
+    print("== ZQ-GATE trivalent decision battery (noiseless, canonical) ==")
+    for name, oracle, expected in cases:
+        r = ZYQLQuantumGate(3, oracle).run_quantum()
+        ok = str(r["decision"]) == expected
+        print(f"[{'PASS' if ok else 'FAIL'}] {name}: decision={r['decision']} "
+              f"(expected {expected}) p0={r.get('p0')} calls={r.get('oracle_calls')}")
+        if not ok:
+            FAILED.append(f"battery:{name}")
+
+
+def canon(payload):
+    return json.dumps(payload, sort_keys=True, ensure_ascii=True, default=str)
+
+
+def verify_receipt(path):
+    try:
+        rec = json.load(open(path))
+    except Exception as e:
+        print(f"[FAIL] {os.path.basename(path)}: malformed ({e})")
+        FAILED.append(path)
+        return
+    declared = rec.get("selo_sha3_256")
+    if not declared:
+        print(f"[FAIL] {os.path.basename(path)}: no selo_sha3_256")
+        FAILED.append(path)
+        return
+    if isinstance(rec.get("payload"), dict) and "selo_sha3_256" in rec:
+        # formato aninhado (Rodada G em diante): o selo cobre rec["payload"]
+        payload = rec["payload"]
+    else:
+        payload = {k: v for k, v in rec.items() if k != "selo_sha3_256"}
+    recomputed = hashlib.sha3_256(canon(payload).encode()).hexdigest()
+    ok = declared == recomputed
+    print(f"[{'PASS' if ok else 'FAIL'}] {os.path.basename(path)}: "
+          f"{'SELO ÍNTEGRO' if ok else 'SELO ROMPIDO'}")
+    if not ok:
+        FAILED.append(path)
+
+
+def run_verify():
+    print("== ZQ-GATE receipt verification (Z-QEA, SHA3-256) ==")
+    root = os.path.join(HERE, "..")
+    paths = sorted(glob.glob(os.path.join(root, "experiments", "**", "*.json"), recursive=True))
+    sealed = [p for p in paths if "job_meta" not in os.path.basename(p)]
+    any_sealed = False
+    for p in sealed:
+        try:
+            d = json.load(open(p))
+            if isinstance(d, dict) and d.get("selo_sha3_256"):
+                verify_receipt(p)
+                any_sealed = True
+        except Exception:
+            verify_receipt(p)
+            any_sealed = True
+    if not any_sealed:
+        print("(no sealed receipts found in experiments/ — nothing to verify)")
+
+
+if MODE in ("all", "battery"):
+    run_battery()
+if MODE in ("all", "verify-receipts"):
+    run_verify()
+
+print()
+if FAILED:
+    print("ZQ-GATE: FAIL —", len(FAILED), "failure(s). Nothing passes silently.")
+    sys.exit(1)
+print("ZQ-GATE: ALL PASS — decisions sealed, receipts intact.")

oq3.py

@@ -0,0 +1,84 @@
+"""
+Zephyron → OpenQASM 3 transpiler.
+Zephyron is the circuit language of the Zephyrum ecosystem; OpenQASM 3 is
+the interchange language IBM Quantum (Qiskit Runtime) ingests. This bridge
+is the honest path to real IBM hardware: IBM will never run Zephyron
+natively, but it accepts its compiled output.
+"""
+
+def to_openqasm3(gates, nqubits):
+    """gates: list of strings as produced by QCircuit.gates_applied,
+    e.g. 'H(0)', 'X(1)', 'CNOT(0->1)', 'CZ(0,1)', 'T(1)'."""
+    lines = ["OPENQASM 3.0;", 'include "stdgates.inc";',
+             f"qubit[{nqubits}] q;", f"bit[{nqubits}] c;"]
+    for g in gates:
+        name, rest = g.split("(", 1)
+        args = rest.rstrip(")").replace(" ", "")
+        if name == "CNOT":
+            c, t = args.split("->")
+            lines.append(f"cx q[{c}], q[{t}];")
+        elif name == "CZ":
+            c, t = args.split(",")
+            lines.append(f"cz q[{c}], q[{t}];")
+        elif name == "Z":
+            q = args
+            lines.append(f"z q[{q}];")
+        else:
+            q = args
+            lines.append(f"{name.lower()} q[{q}];")
+    lines.append("c = measure q;")
+    return "\n".join(lines) + "\n"
+
+if __name__ == "__main__":
+    from programs import bell, ghz, grover2
+    for name, prog in (("bell", bell), ("ghz", ghz), ("grover", grover2)):
+        qc, _ = prog(shots=1)
+        oq3 = to_openqasm3(qc.gates_applied, qc.n)
+        print(f"=== {name} ===")
+        print(oq3)
+
+
+# --- OpenQASM 3 -> Zephyron importer (uses the reference parser) ---
+def from_openqasm3(src):
+    """Parse valid OpenQASM 3 (e.g. produced by IBM tools or our own
+    transpiler) into a Zephyron QCircuit. Returns (circuit, gates)."""
+    import math
+    from openqasm3.parser import parse
+    from openqasm3.ast import (QuantumGate, QubitDeclaration,
+                              IndexedIdentifier, IntegerLiteral, UnaryExpression)
+    from zquantum import QCircuit
+
+    nq = 0
+    gates = []
+    for st in parse(src).statements:
+        if isinstance(st, QubitDeclaration):
+            size = st.size
+            if isinstance(size, UnaryExpression):
+                nq = -size.expression.value
+            else:
+                nq = size.value
+        elif isinstance(st, QuantumGate):
+            name = st.name.name
+            qubits = []
+            for q in st.qubits:
+                if isinstance(q, IndexedIdentifier):
+                    idx = q.indices[0][0]
+                    v = idx.value if hasattr(idx, "value") else int(str(idx))
+                    qubits.append(v)
+            angles = [a.value for a in st.arguments]
+            if name in ("cx", "cnot"):
+                gates.append(f"CNOT({qubits[0]}->{qubits[1]})")
+            elif name == "cz":
+                gates.append(f"CZ({qubits[0]},{qubits[1]})")
+            elif name == "swap":
+                gates.append(f"SWAP({qubits[0]},{qubits[1]})")
+            elif name == "ccx":
+                gates.append(f"TOFFOLI({qubits[0]},{qubits[1]}->{qubits[2]})")
+            elif name in ("rx", "ry", "rz"):
+                gates.append(f"{name.upper()}({qubits[0]},{angles[0]})")
+            elif name == "id":
+                continue
+            else:
+                gates.append(f"{name.upper()}({qubits[0]})")
+    qc = QCircuit.from_gates(nq, gates)
+    return qc, gates

quantum_types.py

@@ -0,0 +1,133 @@
+"""
+ZEPHIRUM QUANTUM TYPES (v1.0.0, 12/10/2026) — qbit as a first-class type.
+Prototype pre-parser: the type layer is real (wraps the state-vector kernel),
+the Zephirum interpreter wiring is the next step (declared limitation).
+
+What it enforces:
+  1. qbit declarations, unitary application, entanglement, measurement
+  2. NO-CLONING enforced by the type: assigning/copying a quantum value
+     raises CompileError at the type check, before any execution
+  3. qif: quantum conditional via controlled operation (no collapse)
+"""
+import sys, os, json, time
+try:
+    from zquantum import QCircuit
+except ImportError:  # in-tree, no install
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    from zquantum import QCircuit
+
+class CompileError(Exception):
+    pass
+
+class QType:
+    """First-class quantum value. Lives in one circuit; cannot be copied."""
+    def __init__(self, circ, index, size=1):
+        self.circ, self.index, self.size = circ, index, size
+
+    # no-cloning enforced by the type: any copy attempt fails at compile time
+    def __copy__(self):      raise CompileError("NO_CLONING: quantum value cannot be copied")
+    def __deepcopy__(self, m): raise CompileError("NO_CLONING: quantum value cannot be copied")
+    def clone(self):         raise CompileError("NO_CLONING: quantum value cannot be copied")
+
+
+class QuantumLang:
+    """Mini pre-parser layer: qbit / H / CNOT / qif / measure."""
+
+    def __init__(self, n):
+        self.circ = QCircuit(n)
+        self.n = n
+        self.vars = {}
+        self.classical_copies = []      # legal: measured (collapsed) results
+
+    def qbit(self, name):
+        if name in self.vars: raise CompileError("redeclaration of qbit " + name)
+        idx = len(self.vars)
+        self.vars[name] = QType(self.circ, idx)
+        return self.vars[name]
+
+    def h(self, name):
+        self.circ.h(self.vars[name].index)
+
+    def x(self, name):
+        self.circ.x(self.vars[name].index)
+
+    def cnot(self, a, b):
+        self.circ.cnot(self.vars[a].index, self.vars[b].index)
+
+    def qif(self, cond_name, then_op):
+        """Quantum conditional: controlled operation, NO measurement, NO collapse.
+        then_op is a single-qubit X for the prototype (control decomposition)."""
+        if then_op.upper() not in ("X",):
+            raise CompileError("qif prototype supports controlled-X only")
+        self.circ.cnot(self.vars[cond_name].index,
+                       self._last_free_target(cond_name))
+
+    def _last_free_target(self, not_this):
+        targets = [v for k, v in self.vars.items() if v.index != self.vars[not_this].index]
+        return targets[-1].index
+
+    def measure(self, name, shots=4096, seed=11):
+        """Measurement collapses: the RESULT is classical and copyable."""
+        c = self.circ.measure_all(shots=shots, seed=seed)
+        self.classical_copies.append({name: c})
+        return c
+
+    def assign(self, dst, src):
+        """Type-checked assignment: quantum -> quantum is NO_CLONING (CompileError)."""
+        if src in self.vars:
+            raise CompileError("NO_CLONING: assignment of quantum value '%s' rejected by the type" % src)
+        raise CompileError("unknown assignment %s = %s" % (dst, src))
+
+
+def main():
+    proof = {"module": "quantum_types.py", "version": "1.0.0",
+             "date": time.strftime("%Y-%m-%d %H:%M:%S"), "tests": []}
+
+    # 1. entanglement: Bell state 1/2 + 1/2
+    lang = QuantumLang(2)
+    a, b = lang.qbit("a"), lang.qbit("b")
+    lang.h("a"); lang.cnot("a", "b")
+    c = lang.measure("a", shots=4096, seed=42)
+    p00, p11 = c.get("|00>", 0) / 4096, c.get("|11>", 0) / 4096
+    ent = abs(p00 - 0.5) < 0.02 and abs(p11 - 0.5) < 0.02
+    proof["tests"].append({"name": "entanglement (Bell 1/2+1/2)",
+                           "p00": round(p00, 4), "p11": round(p11, 4), "PASS": ent})
+
+    # 2. no-cloning enforced by the type
+    try:
+        lang2 = QuantumLang(2)
+        lang2.qbit("q"); lang2.qbit("r")
+        lang2.assign("r", "q")           # must raise CompileError
+        nc = False
+    except CompileError as e:
+        nc = "NO_CLONING" in str(e)
+    proof["tests"].append({"name": "no-cloning rejected by type (assign)", "PASS": nc})
+    try:
+        lang3 = QuantumLang(2)
+        q = lang3.qbit("q")
+        q.clone()                         # must raise
+        nc2 = False
+    except CompileError as e:
+        nc2 = "NO_CLONING" in str(e)
+    proof["tests"].append({"name": "no-cloning rejected by type (clone)", "PASS": nc2})
+
+    # 3. qif: controlled operation without collapse
+    lang4 = QuantumLang(2)
+    lang4.qbit("ctrl"); lang4.qbit("tgt")
+    lang4.h("ctrl")            # superposition on control
+    lang4.qif("ctrl", "X")     # controlled-X: entangles, no measurement
+    st = lang4.circ.state
+    amps = [round(abs(x) ** 2, 4) for x in st]
+    qif_ok = abs(amps[0] - 0.5) < 0.01 and abs(amps[3] - 0.5) < 0.01 and amps[1] < 1e-9
+    proof["tests"].append({"name": "qif: controlled-X, no collapse (Bell from superposed ctrl)",
+                           "probabilities": amps, "PASS": qif_ok})
+
+    proof["all_PASS"] = all(t["PASS"] for t in proof["tests"])
+    out = os.path.join(os.path.dirname(__file__), "..", "lab", "prova_quantum_types.json")
+    json.dump(proof, open(out, "w"), indent=1)
+    for t in proof["tests"]:
+        print("%-55s PASS=%s" % (t["name"], t["PASS"]))
+    print("ALL_PASS:", proof["all_PASS"])
+
+if __name__ == "__main__":
+    main()

shot_auditor.py

@@ -0,0 +1,67 @@
+# -*- coding: utf-8 -*-
+"""SHOT AUDITOR — controlador trivalente de continuacao de campanhas quanticas.
+
+Decide CONTINUE / STOP / REFUSED apos cada profundidade de uma campanha,
+com banda declarada (IC 95% do gradiente) e regra de parada selada ANTES
+dos dados. Peeking em runtime => REFUSED (binding via stopping_rule_check).
+"""
+import math
+
+Z95 = 1.959963985  # quantil 95% (declarado, selado junto com a regra)
+
+def gradiente_band(p_obs_counts, shots):
+    """Banda de ruido do gradiente a partir das contagens das DUAS energias.
+
+    p_obs_counts: (counts_mais, counts_menos) — histogramas de E(theta+pi/2)
+    e E(theta-pi/2). E = <Z0> + <Z1Z2> medido dos counts (bitstring q3q2q1q0).
+    Retorna (gradiente, sigma_g, banda_g): banda_g = Z95 * sigma_g.
+    """
+    def energia(counts):
+        tot = sum(counts.values())
+        e = 0.0
+        for bs, c in counts.items():
+            b = bs.replace(" ", "")
+            z0 = 1 - 2 * int(b[-1])           # Z0 (bit menos significativo)
+            z1 = 1 - 2 * int(b[-2])           # Z1
+            z2 = 1 - 2 * int(b[-3])           # Z2
+            e += c * (z0 + z1 * z2)
+        return e / tot
+
+    def var_energia(counts):
+        tot = sum(counts.values())
+        v = 0.0
+        for bs, c in counts.items():
+            b = bs.replace(" ", "")
+            z0 = 1 - 2 * int(b[-1])
+            z1 = 1 - 2 * int(b[-2])
+            z2 = 1 - 2 * int(b[-3])
+            v += c * (z0 + z1 * z2) ** 2
+        m = energia(counts)
+        return (v / tot - m * m) / tot
+
+    e_m, e_n = energia(p_obs_counts[0]), energia(p_obs_counts[1])
+    v_m, v_n = var_energia(p_obs_counts[0]), var_energia(p_obs_counts[1])
+    g = (e_m - e_n) / 2.0
+    sigma_g = math.sqrt(v_m + v_n) / 2.0
+    return g, sigma_g, Z95 * sigma_g
+
+def audit_step(g, banda_g, shots_da_profundidade, selo):
+    """Decisao trivalente da profundidade atual. Regra SELADA antes dos dados:
+    |g| <= banda_g  => STOP (gradiente indistinguivel de zero no IC 95%)
+    |g| >  banda_g  => CONTINUE (sinal acima da banda)
+    Incoerencia com o protocolo selado => REFUSED.
+    """
+    chk = stopping_rule_check(selo, {"shots_observed": shots_da_profundidade,
+                                     "decision_at_shot": shots_da_profundidade})
+    if chk["decision"] == "REFUSED":
+        return {"decisao": "REFUSED", "motivo": chk.get("refusal_reason", "?"),
+                "regra": chk.get("rule", ""), "g": g, "banda": banda_g}
+    if abs(g) <= banda_g:
+        return {"decisao": "STOP", "motivo": "GRADIENTE_DENTRO_DA_BANDA",
+                "regra": "IC 95% do gradiente contem zero: pagar mais shots "
+                         "e estatistica de mais para um sinal que ja e ruido",
+                "g": g, "banda": banda_g}
+    return {"decisao": "CONTINUE", "motivo": "GRADIENTE_ACIMA_DA_BANDA",
+            "g": g, "banda": banda_g}
+
+from zyql_robust import stopping_rule_check  # noqa: E402  (selo/runtime binding)

zephirum-2.1.0.dist-info/METADATA

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: zephirum
+Version: 2.1.0
+Summary: ZEPHIRUM: Lisp-style quantum programming language with the ZYQL trivalent decision core (1/0/REFUSED)
+Author-email: Reginaldo Gonçalves <builderquantunxia@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: lark
+Requires-Dist: qiskit>=2.6
+Provides-Extra: hardware
+Requires-Dist: qiskit-aer>=0.17; extra == "hardware"
+Requires-Dist: qiskit-ibm-runtime>=0.50; extra == "hardware"
+Provides-Extra: interop
+Requires-Dist: cirq>=1.4; extra == "interop"
+Provides-Extra: test
+Requires-Dist: qiskit-qasm3-import>=0.5; extra == "test"
+Dynamic: license-file
+
+<p align="center"><img src="assets/social-preview-1280x640.png" alt="ZYQL: Exact-decision language" width="640"></p>
+
+# ZEPHIRUM
+
+**The quantum programming language with receipts.** ZYQL, its decision core, returns one of three verdicts — `1` (permitted), `0` (forbidden) or `REFUSED` (insufficient confidence) — and seals every decision in a verifiable receipt.
+
+![version](https://img.shields.io/badge/version-2.1.0-6e46b8)
+![license](https://img.shields.io/badge/license-MIT-blue)
+![kernel](https://img.shields.io/badge/kernel-statevector%20%5Bre%2Cim%5D%20float64-cyan)
+![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.23632019-gold)
+[![CI](https://github.com/SerenaSolutions/zephirum-lang/actions/workflows/ci.yml/badge.svg)](https://github.com/SerenaSolutions/zephirum-lang/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/SerenaSolutions/zephirum-lang/actions/workflows/codeql.yml/badge.svg)](https://github.com/SerenaSolutions/zephirum-lang/actions/workflows/codeql.yml)
+![python](https://img.shields.io/badge/python-3.10%20%7C%203.11-blue)
+
+**Contents** — [What it is](#what-it-is) · [Quickstart](#quickstart) · [Evidence](#evidence) · [Architecture](#architecture) · [Tests & reproducibility](#tests--reproducibility) · [Learn](#learn) · [Layout](#layout) · [Scope & honest limits](#honest-scope) · [Citation](#citation)
+
+---
+
+## What it is
+
+ZEPHIRUM is a small quantum programming language. ZYQL is its decision algorithm:
+every computational decision is trivalent — `1` (permitted), `0` (forbidden),
+`REFUSED` (input-dependent or insufficient confidence) — and carries a sealed
+receipt (SHA3-256 integrity seal, hash proves content integrity, not authorship).
+ML-DSA-44 / FIPS 204 signatures are a DECLARED ROADMAP item — to be implemented
+with an accredited module and HSM-held keys, never hand-rolled (see [docs/receipts.md](docs/receipts.md)).
+
+Decisions are produced by Deutsch–Jozsa interference, one oracle call, with a
+declared noise band (±0.15). Nothing executes silently: unknown syntax raises
+an explicit error. Simulation mode is labeled as simulation.
+
+- **Trivalent semantics** — refusal is a first-class verdict, not an exception.
+- **Receipts by construction** — every decision can be sealed (Z-QEA, SHA3-256).
+- **Hardware-verified** — measured on IBM Heron with job IDs published below.
+
+## Quickstart
+
+```bash
+git clone https://github.com/SerenaSolutions/zephirum-lang.git && cd zephirum-lang
+pip install -e .            # or: PYTHONPATH=src
+```
+
+```python
+from zyql_quantum_gate import ZYQLQuantumGate
+
+gate = ZYQLQuantumGate(3, lambda x: x ^ 1)      # balanced oracle
+r = gate.run_quantum(shots=2048)
+print(r["decision"], r.get("refusal_reason", ""))   # REFUSED BALANCED_ORACLE
+```
+
+```bash
+zyql-decide --oracle balanced --shots 512      # CLI runtime, Hoeffding error bound
+python3 src/zyql_lisp.py examples/hello_world.zph   # language front-end + sealed receipt
+```
+
+The baptism of the language — a trivalent greeting, sealed by ZEPHIRUM itself:
+
+```lisp
+;; hello_world.zph — ZEPHIRUM v2 (Lisp)
+(hello "Zephirum")
+(seal "examples/hello_world.receipt.json")
+```
+
+```console
+$ python3 src/zyql_lisp.py examples/hello_world.zph
+Hello, Zephirum! | decisao = 1
+SELO: <sha3-256 do recibo — carimbo temporal, varia por execucao>
+```
+
+The `hello` form prints the greeting and returns the trivalent verdict `1`
+(a greeting is always permitted). The `seal` form writes a Z-QEA receipt
+(SHA3-256) of everything executed — the Hello World carries a sealed receipt,
+as every decision in this house does. Source: [`examples/hello_world.zph`](examples/hello_world.zph).
+
+## Evidence
+
+![S3 fusion channels measured on IBM Heron](assets/proofs/s3-fusion-hardware.png)
+
+*Real-data figure: theoretical braid curves (gold: B_R∘B_S, violet: B_S∘B_R) and the
+points measured on IBM Heron `ibm_fez` — 98.1% vs 95.8%. The braid order is
+distinguishable on silicon. Full detail: [docs/PROOFS.md](docs/PROOFS.md).*
+
+![Non-Abelian anyon braiding — AI art](assets/proofs/non-abelian-braids-art.png)
+
+*Hero art (declared: AI-generated) — braided world-lines of non-Abelian anyons
+converging into three fusion channels, the geometry the experiments probe.*
+
+### Proofs of concept — non-Abelian anyons (S3 qutrit miniature)
+
+| Claim | Mode | Result | Receipt |
+|-------|------|--------|---------|
+| Fusion space is 3-dimensional (qutrit in 2 qubits) | noiseless | exact 1/3+1/3+1/3, forbidden channel vetoed | [sealed receipt](experiments/s3_qutrit_final_receipt.json) |
+| Braiding is non-Abelian (order matters) | noiseless | commutator L1 = 6 exact; B_R∘B_S → ch2, B_S∘B_R → ch1 | same |
+| Noiseless round | noiseless | exact-zero deviation vs theory (canonical rationals) | same |
+| ZYQL trivalent decisions 1 / 0 / REFUSED | **IBM Heron** | **3/3 PASS** (job `dbbugbk24mrc73cif420`) | [battery receipt](experiments/zyql_hardware_battery.json) |
+| Braid order measured on real hardware | **IBM Heron** | **98.1% vs 95.8%** (job `dbbueufi0auc73dtp7og`) | [master receipt](experiments/s3_qutrit_final_receipt.json) |
+| **Shots-to-verdict efficiency** | **IBM Heron** | **256 shots** to a first-step verdict — **96.88% savings vs 8192** | receipt `28f406202e9d125a` (issue #40) |
+
+Receipt seal (SHA3-256): `a44192463ea669564a3da51728c8577e59e5684c67cf2d48f7a95442d548476a` — verify it yourself: `python3 .github/actions/zqea-verify/zqea_verify.py experiments/s3_qutrit_final_receipt.json`
+In language: [`examples/s3_qutrit.zph`](examples/s3_qutrit.zph).
+
+Verified on real hardware (IBM Heron `ibm_fez`, cited as test laboratory with
+verifiable job IDs; no endorsement claimed):
+
+- Constant purpose: measured p(000)=0.9844 (job `db6ded84qg6s73c4jvug`)
+- S3 qutrit miniature: fusion channels (qutrit-in-qubits) + braiding non-commutativity,
+  noiseless with exact-zero deviation and on hardware: ch2=98.1% (RS) vs ch1=95.8% (SR),
+  full ZYQL battery 3/3 PASS on `ibm_fez` (jobs `dbbueufi0auc73dtp7og`, `dbbugbk24mrc73cif420`;
+  Z-QEA receipt sealed, see `experiments/`)
+- Balanced purpose: p(000)=0.0000, orthogonal outcome 93.9%
+- Same-task confrontation vs textbook Qiskit (job `db6dklcvf2bc73d122t0`):
+  Zephyron transpiles to depth 2 / 0 two-qubit gates vs depth 10 / 3 CZ
+
+Benchmark suite: [`benchmarks/`](benchmarks/) (public comparative benchmark, issue #28).
+
+## Architecture
+
+```
+ program (.zph, Lisp)  ──►  front-end parser ──► canonical decision form
+        │                                              │
+        │                                    Deutsch–Jozsa interference
+        │                                    (one oracle call, noise band ±0.15)
+        │                                              │
+        │                                    trivalent verdict: 1 / 0 / REFUSED
+        │                                              │
+        └──────────────►  Z-QEA receipt  ◄─────────────┘
+                     (SHA3-256 seal + machine-readable refusal_reason)
+```
+
+The repository ships the language heart only: kernel (state-vector, `[re,im]`
+float64), OpenQASM 3 transpiler, trivalent gate, quantum types (no-cloning
+enforced) and the receipt chain. See [Honest scope](#honest-scope).
+
+The language:
+
+```
+circuit bell {
+  qubit[2] q;
+  H q[0];
+  CNOT q[0] -> q[1];
+}
+```
+
+## Tests & reproducibility
+
+- **13 test suites** (`tests/`): canonical rational battery, certified decisions,
+  frontiers, KEM, Lisp regression, meta, multiple-testing correction,
+  runtime, shot auditor, Z-QEA verifier, hardware rounds.
+- **CI matrix**: Python 3.10 and 3.11 on every push and pull request, with
+  `PYTHONHASHSEED=0` for reproducible runs; **CodeQL** static analysis;
+  **signed releases with build provenance** (SLSA attestation); a dedicated
+  **ZQ-GATE self-test** workflow.
+- **Statistical discipline**: multiple-comparison correction is part of the test
+  battery — verdicts are not claimed on uncorrected p-values.
+- **Verifiable by construction**: every hardware claim above points to a sealed
+  receipt and a job ID; receipts are re-verifiable with
+  `.github/actions/zqea-verify/zqea_verify.py`.
+- Published testing roadmap (fuzzing the front-end, unitary-equivalence
+  assertions, executed notebooks, coverage gate): tracked in issues.
+
+## Learn
+
+- [docs/LEARN.md](docs/LEARN.md) — progressive tutorial: first decision to sealed hardware receipts
+- [docs/COOKBOOK.md](docs/COOKBOOK.md) — copy-paste recipes, every one executed and recorded
+- [docs/MIGRATION.md](docs/MIGRATION.md) — embedding Zephirum in Python, C and CI pipelines
+- [docs/PROOFS.md](docs/PROOFS.md) — hardware proofs, figures and receipts
+- [docs/MATURITY.md](docs/MATURITY.md) — component-by-component maturity
+
+## Layout
+
+- `src/` — kernel (state-vector), OpenQASM 3 transpiler, trivalent gate,
+  quantum types (no-cloning enforced), neural RAG layer, runtime (`zyql_runtime`)
+- `tests/` — 13 suites (see above)
+- `examples/` — `hello_world.zph`, `bell.zph`, `grover.zph`, `dj_constant.zph`, `s3_qutrit.zph`
+- `benchmarks/` — public comparative benchmark suite
+- `notebooks/` — scientific presentation layer
+- `experiments/` — hardware rounds and sealed receipts (job IDs)
+- `docs/` — language reference, receipt specification, proofs, maturity, dossier
+- `playground/` — browser playground assets · `site/` — docs site · `paper/` — preprint sources
+- `zephirum-vscode/` — VS Code extension for `.zph`
+- `docker/` — reproducible container
+
+## Technical Dossier
+
+A consolidated, receipt-cited dossier of the project — what it is, what has been measured on real quantum hardware, the public m50 commitment, Industry 5.0 applications and the declared honest limits: **[docs/DOSSIER.md](docs/DOSSIER.md)**
+
+
+## Self-verified device decision (new, 2026-10-29)
+
+A decisão trivalente agora roda **na QPU** com a própria QPU certificando a execução:
+
+- **Auto-verificação (espelho C†)** no mesmo job — taxa de zeros medida vira `selfcheck_p0` no recibo; abaixo do limiar ⇒ `REFUSED`.
+- **Evidência sequencial** com regra de parada (alpha-spending) declarada **antes** da execução.
+- **Recibo** com protocolo + contagens por lote + `job_id`, selado SHA3-256.
+
+| Oráculo | Veredito | p0 | selfcheck | Shots | job_id (ibm_fez) |
+|---|---|---|---|---|---|
+| constante | **1** | 0.992 | 0.969 | 128 | `dbhm3ao1h92s73821mm0` |
+| balanceado | **0** | 0.016 | 0.992 | 128 | `dbhm3ik2d77s739d10j0` |
+
+Especificação completa: **[docs/SELFVERIFIED.md](docs/SELFVERIFIED.md)** · recibos em `experiments/selfcheck_ibm_fez_20261029/`.
+
+
+## Refusal witness — abstenção com prova (new, 2026-10-29)
+
+`REFUSED` deixa de ser "não sei" e vira "não sei **porque** a evidência não fecha":
+a TVD entre a distribuição ideal (referência exata) e a medida no dispositivo tem
+intervalo de confiança declarado **antes** da execução.
+
+| Dispositivo | Shots | TVD | Janela | ε | Veredito | job_id |
+|---|---|---|---|---|---|---|
+| ibm_fez | 4096 | 0.0317 | [0.000, 0.104] | 0.10 | **REFUSED** | `dbhn296ne4hc73bd7u1g` |
+| ibm_marrakesh | 8192 | 0.0198 | [0.000, 0.071] | 0.10 | **1 CERTIFICADO** | `dbhn8hs2d77s739d32lg` |
+
+O primeiro voo absteve; com o dobro de evidência, certificou. Especificação:
+**[docs/WITNESS.md](docs/WITNESS.md)** · recibos em `experiments/witness_20261029/`.
+
+
+## Hardware protocols (2026-10-29)
+
+Protocolos pré-declarados, executados no plano Open com recibo selado
+(`docs/PROTOCOLS.md`):
+
+| Protocolo | Medida | Resultado | job_id |
+|---|---|---|---|
+| P-10 fronteira clássica×hardware | TVD vs ideal, n=3..5 | 0.0139 / 0.0188 / 0.0183 | `dbhp6ks2d77s739d692g` |
+| P-08 ZNE vs C† | p0 n=4, com/sem ZNE | 0.0197 → **0.0116** (−41%) | `dbhp6ok2d77s739d6990` |
+
+
+## Apps v1 (2026-10-29)
+
+- **AuditKit (CPA-01)** — certificacao de entropia quantica com recibo: hardware
+  `ibm_marrakesh`, 4096 bits, veredito **1** (job `dbhpaomne4hc73bdbp7g`).
+- **Quantum Regression Seal (QRS-01)** — gate de CI/CD que pega miscompilacao
+  silenciosa por comparacao unitaria; action reutilizavel no repo.
+
+Detalhes: **[docs/APPS.md](docs/APPS.md)**
+
+## Honest scope
+
+This repository contains the language heart only: kernel, types, gate, receipts.
+It does not contain, and will never contain, the Zephirum OS distribution,
+bootloader, installer, or activation keys. Simulations are labeled as
+simulations; without error correction, useful executions are bounded well
+under 20 qubits.
+
+## Runtime de produção (v1.8.0)
+
+```python
+from zyql_runtime import decide, Verdict
+r = decide(lambda x: x & 1, n=3, shots=512)   # -> Verdict.REFUSED
+r.error_bound                                 # limite de erro Hoeffding declarado
+```
+CLI: `zyql-decide --oracle balanced --shots 512`
+
+## ⚠️ Desambiguação / Disambiguation — no PyPI package exists
+
+Instruções circulando na web citam `pip install zephirum-quantum-plugin` e um
+repositório `SerenaSolutions/zephirum`. **Nenhum dos dois existe.** Este
+(`zephirum-lang`) é o único repositório oficial. Nenhum pacote da ZEPHIRUM está
+publicado no PyPI — qualquer instrução citando esse pacote não vem da casa.
+
+## Citation
+
+See `CITATION.cff`. Software deposit: Zenodo concept DOI 10.5281/zenodo.23632019
+(code MIT, companion thesis CC BY-NC-ND 4.0), (c) Serena Solutions.
+
+## License
+
+MIT — see [LICENSE](LICENSE).