Write and run quantum circuits using Quantinuum's Guppy language on the Selene emulator. Triggers on Guppy, Selene, Quantinuum, SWAP test, QSP/QSVT, Shor / modular exponentiation, quantum kernel, qubit circuits, parameter sweeps, the selene_run schema, or quantum topological data analysis (QTDA).
SKILL.md

---
name: quantinuum
description: Write and run quantum circuits using Quantinuum's Guppy language on the Selene emulator. Triggers on Guppy, Selene, Quantinuum, SWAP test, QSP/QSVT, Shor / modular exponentiation, quantum kernel, qubit circuits, parameter sweeps, the selene_run schema, or quantum topological data analysis (QTDA).
---

# Quantinuum (Guppy + Selene)

Build real quantum circuits in Python with `@guppy`, compile them, and execute shots on the Selene emulator. Battle-tested in this repo's `quantum/qtda.py` QTDA pipeline and the `quantum/nadarasa_g*.py` Nadarasa frontier.

## Install

```bash
pip install "guppylang>=1.0"     # Python >= 3.12; Selene ships inside guppylang
pip install pytket pytket-quantinuum   # only for the TKET compile lane (offline; no credentials, no HQCs)
```

Guppy v1.0 is a breaking release (`output` replaces `result`, `measure(q).read()`, emulator builder). If you are touching any pre-v1 code or samples, read `references/guppy-v1-migration.md` first.

Some sandboxes vendor Python deps under `.pydeps/` instead of system site-packages. When that convention is in use, install with `pip install --target .pydeps "guppylang>=1.0" numpy scipy` (add `pytket pytket-quantinuum` for the TKET lane) and invoke drivers as `PYTHONPATH=.pydeps PYTHONUNBUFFERED=1 python3 -m quantum.<driver>`. Reinstall it whenever the sandbox is recycled.

## Critical gotchas (read first)

1. **`@guppy`-decorated functions must live in a real `.py` file on disk.** Guppy reads source via `inspect.getsource`, so functions defined in a REPL, `exec()` string, or Jupyter cell will fail. To parameterize kernels at runtime, generate a temp `.py` file and import it via `importlib.util` — see `references/driver-pattern.md`.
2. **`angle(x)` is in HALFTURNS, not radians.** `angle(0.5)` = π/2 (S gate). For an arbitrary radian θ, write `angle(θ / math.pi)`. See `references/guppy-language.md` (§Angles).
3. **Tomographic-equivalence threshold = `4·√(0.5/shots)`, not `3σ·√(p(1−p)/n)`.** The textbook form produces false FAILs near p = 0 or p = 1. See `references/tomographic-equivalence.md` (§Threshold).
4. **No coherent / T1-T2 noise model ships with `selene_sim`.** Only `IdealErrorModel`, `DepolarizingErrorModel`, `SimpleLeakageErrorModel` exist. See `references/selene-runtime.md` (§Noise models).
5. **Long sweeps MUST be resumable via a per-row JSON cache.** A single sandbox timeout otherwise wipes the whole run. Cache each row to `_cache_<name>/<row-tag>.json` before continuing, then wrap the driver in a `while [ $(ls cache | wc -l) -lt N ]; do timeout 580 python -m ...; done` loop. See `references/sweep-runner.md` (§Resumable sweeps).
6. **Ship Selene results as committed JSON, not as a live server function.** The Lovable Cloudflare Worker runtime stubs `child_process` and blocks arbitrary filesystem reads, so `createServerFn` / `createFileRoute` handlers that shell out to Python or read the sweep cache will fail in prod. Run Python in the sandbox, write `src/data/demos/<experiment>.json`, and render a static view. See `references/selene-runtime.md` (§Shipping results to the frontend).
7. **The QPDE / Trotter "evolution-time trick" is in radians; Guppy `angle()` is in halfturns.** If a paper says `t = π/(16 h₁)` so that `e^{-i(π/16)Z} = √T`, write `rz(q, angle(1/16))` — NOT `angle(math.pi/16)`, which is the S gate. Whenever the source formula contains an explicit `π`, divide it out before passing to `angle()`. See `references/qpde.md` and `references/guppy-language.md` (§Angles).
8. **Vendor-realistic H2 noise numbers are published — use them.** `p_2q = 1.29e-3`, `p_r_01 = 0.9e-3`, `p_r_10 = 1.8e-3`, coherent memory `f = 4.3e-2 rad/s`, incoherent `g = 2.8e-3 /s`. Incoherent-memory + gate/readout dominate; dynamical decoupling neutralizes coherent memory. See `references/selene-runtime.md` (§Realistic H2 noise-parameter targets).
9. **Recursive Gate Teleportation (RGT) terminates after `n_b − 2` rounds** for an `n_b`-bit rotation angle. Choose short binary-fraction angles (5 bits is usually enough) to keep pFT logical-rotation cost bounded. See `references/encoded-circuits.md`.
10. **Lovable "internal error" on a Guppy/Selene turn = task rollback, not app crash.** Dev server stays healthy, `git status` clean, no artifacts persist. Trigger is turn-level context pressure (broad reads of `src/routeTree.gen.ts`, `_cache_*/`, `PQP_DIGEST.md`, uploaded PDFs > 1 MB, or ≥3 concurrent sub-agents). Recovery: work in atomic **gates** (one committable artifact per turn), cap sub-agents at 2, start each session with a tiny persistence canary edit. See `references/lovable-orchestration.md`.
11. **`.pydeps/` must be in `.gitignore`.** An unignored multi-hundred-MB vendored dep tree makes the platform's turn-save time out, which surfaces as "An internal error occurred" and rolls the whole turn back. Ignore it, reinstall, then retry. See `references/lovable-orchestration.md`.
12. **QPDE `k` values that put `2φ` at a multiple of π are aliasing controls**, not fit data — exclude them from the gap fit and report separately. See `references/qpde.md`.
13. **Taylor-fit moment estimators are conditioning-limited, not shot-limited.** For `tr(e^{-iHτ})` moment fits, the τ grid and truncation order move σ(T_k) by ~4x while 4x shots only halves it. Tune the design offline against simulated binomial noise first, and report a model-free curve χ² alongside the fitted moments. See `references/laplacian-moments-tda.md`.
14. **Cross-platform corroboration is the strongest validation layer.** A noisy-hardware result is most believable when it is reproduced on a different platform with an independent compiler and noise model. Within one platform, use at least two independent mitigation estimators (e.g. PEC + ZNE, or noise ladder + model-free curve check). See `references/cross-platform-validation.md`.
15. **Only Clifford segments may go through the rule-(N/M/P) canonicaliser.** Split a variational/generated ansatz at its rotation boundaries: canonicalise the `{H, CZ, S}` frames, leave `Ry(θ)`/`Rz(θ)` cores opaque and verify them with the dense matrix oracle. Also: `CNOT · Rz(2θ) · CNOT` is `exp(-iθZ₀Z₁)`, NOT a single-excitation Givens rotation — always check a paper's decomposition against `expm` of the Pauli sum before writing the kernel. See `references/rewriter-composition.md`.
16. **Guppy v1.0 breaks every pre-v1 driver.** `result(...)` → `output(...)`; `measure(q)` returns a `Measurement`, so write `measure(q).read()` (same for each element of `measure_array`); `selene_sim.build(compiled).run_shots(Quest(), ...)` aborts inside the Rust runtime against a v1 package — run through `program.emulator(n_qubits=N).with_shots(S).with_simulator(Quest()).with_error_model(...).with_seed(...).run()` and iterate `shot.entries`. Pass the `@guppy` program object, never `program.compile()`. Error models still come from `selene_sim`. v1 optimises on compile, so rewriter/gate-count benchmarks must pin `program.with_opt_level(OptimizationLevel.Classical)`. Python floor is 3.12. A one-file shim keeping the legacy `build(program).run_shots(...)` shape (see this repo's `quantum/emulate.py`) makes the migration a per-file import swap. See `references/guppy-v1-migration.md`.
17. **TKET (pytket) is the cheapest independent check on a reduction claim.** Compile the same circuit offline with `QuantinuumBackend(device_name="H2-2", api_handler=QuantinuumAPIOffline())` — no credentials, no job, no HQCs — and compare 2q counts against the rewriter's reduced form. Gate every count on a global-phase-free unitary oracle (`||a − (⟨a,b⟩/|⟨a,b⟩|)·b|| ≤ 1e-9`), because an optimiser that changes semantics looks like the best optimiser in the table. TKET **drops idle wires**, so pad with `add_blank_wires` before comparing or sampling or the TVD reads 1.0. Native ops (`PhasedX`, `Rz`, `ZZPhase`, `ZZMax`) map one-to-one onto `guppylang.std.qsystem`, both in halfturns, so a compiled circuit round-trips onto Selene with no angle conversion. Never score approximation families (AQFT band truncation): a correctness-preserving compiler cannot find them. See `references/pytket.md`.




18. **Nexus distribution keys are int tuples indexed by qubit — calibrate before analysing.** `get_empirical_distribution()` (the deprecated `get_distribution()` still works) returns `{(0, 1, 0, …): p}` where `key[q]` is qubit `q` as an **int** (`key[8] == 0`, never `== "0"`), and Qiskit's convention is the exact reverse. Submit a one-gate X-probe job per backend/shape and assert the 1 lands where you expect, before trusting any downstream number. Nexus also refuses to execute an uncompiled ref: `start_compile_job(optimisation_level=…)` → execute the **compiled** ref → `download_result().get_empirical_distribution()`; `jobs.get(id=…)` is keyword-only. See `references/nexus-jobs.md`.
19. **Noisy Nexus emulator jobs have a hard sizing cliff: ≤ ~17 qubits AND/OR ≤ 2048 shots.** A 25q × 8192-shot noisy job ran ~3 h then raised `TimeoutError` with no partial result. Noiseless backends (`H2-1LE`, `H1-1LE`) are far more forgiving. Also: `Helios-1E-lite` needs `HeliosConfig` with an explicit `system_name` and an `emulator_config` — every one of those omissions produces an error that reads like an access problem but is a config mistake. See `references/nexus-jobs.md` (§The Helios lane).
20. **A multi-leg proof is the claim; a single leg is a rumour.** For any headline number, line up a NumPy exact-statevector oracle, a Selene run, a real Nexus job, and an independent simulator (e.g. Aer). Report all legs with shots + seed + job id, and record timeouts/reverts honestly with their cause. Corollary: run the **classical baseline before writing any quantum code** — position-only rotary encoding scoring a perfect 1.000 on every input pair was caught by the baseline, not by the circuit. See `references/cross-platform-validation.md`.
21. **Post-selected fidelity can never exceed the ideal value.** Repetition-encoding each qubit (`|0_L⟩=|00⟩`, `|1_L⟩=|11⟩` via `ry` + `cx`) and post-selecting shots whose physical pairs agree recovers ~+0.03 at 9q and ~+0.06 at 17q (accept 91–95%) on a SWAP-test overlap — detection only, no correction, and recovery grows with depth. If `F_det > F_ideal`, the accept mask or bit order is wrong; fix it before reporting. Compute the `4·√(0.5/shots)` envelope on the **accepted** shot count. See `references/error-detected-inner-products.md`.
22. **The QIR lane needs its own pinned environment and only accepts static kernels.** `guppylang==0.21.16` + `hugr-qir` + `pytket-qir` in a venv separate from the v1 execution env; validate locally with `qircheck` before any upload. Runtime-parameterized angles break emission (bake literals via the temp-module driver pattern) and `discard()` after `measure` aborts (measure-all instead). `qircheck` passing does **not** mean the job will run — QIR execution targets are access-restricted, so document the gap rather than implying it executed. See `references/qir-lane.md`.
23. **pytket halfturns are verifiable in one line.** `Circuit(1).Ry(0.5).get_unitary()` is a π/2 rotation — `Ry`/`Rz`/`ZZPhase` params are half-turns exactly like Guppy's `angle()`, so never multiply by π when porting a formula between the two. See `references/pytket.md`.
24. **Nexus quotas do not cover hardware — `max_cost` is the only real spend guard.** `qnx.quotas.QuotaName` is exactly `compilation | simulation | jupyterhub | database_usage` (CPU-seconds and stored MB); `check_quota("simulation") == True` says nothing about HQC affordability. Guard an H-series run with `max_cost=[…]` on `start_execute_job` (the `QuantinuumConfig.max_cost` field is deprecated), pre-estimate with `qnx.circuits.cost(...)` — which itself runs a billable costing job — and report the real figure from `qnx.jobs.cost(job)`, not a local formula. `Quota.quota` can be the literal string `'No quota set for user'`, so never do arithmetic on it unguarded. See `references/nexus-admin.md`.
25. **`DEPLETED` is a budget outcome, not a circuit bug.** The full lifecycle is `SUBMITTED → QUEUED → RUNNING → COMPLETED | CANCELLED | ERROR | TERMINATED | DEPLETED` (+ `CANCELLING`, `RETRYING`). Report `DEPLETED` and `TIMEOUT` legs with their cause instead of dropping them. `wait_for` defaults to a websocket; pass `HybridStrategy`/`PollingStrategy` for anything that may queue past ~10 min or a dropped socket loses the run. Never resubmit to recover a result — `qnx.jobs.get_all(project=…, properties=…, job_status=[…])` then `jobs.results(job)[0].download_result()`. See `references/nexus-jobs.md`.
26. **Stamp Nexus jobs with typed project properties or the sweep is unrecoverable.** Declare with `qnx.projects.add_property(name, property_type='string'|'int'|'float'|'bool')`, then set them per job (or via `qnx.context.using_properties(...)`); Nexus **propagates a job's properties onto the resources it creates**, so results inherit provenance for free and become queryable. Project names are unique **per user only** — carry `ProjectRef.id` across accounts. Up to 300 programs per job; batch a sweep instead of firing hundreds of jobs. See `references/nexus-jobs.md`.
27. **Role and group semantics decide who can delete your evidence.** Roles are `Reader | Contributor | Maintainer | Administrator`, and where a user holds both a personal and a team role the **most permissive wins** — revoking the personal one changes nothing. Deleting a project deletes it for everyone. A *group* shares a quota (`user_group=` at submission); a *team* shares resources; they are not interchangeable. Hardware queue position is an admin-set priority 1–10, default 5. See `references/nexus-admin.md`.
28. **A lost hardware sweep is re-attached, never re-run — and every job carries a meter.** Recover by job id, by the `execution` block of a shipped dump, or by property query (`--gate`), into an on-disk cache keyed by job id; make resume a command (`python -m quantum.resume`), because an ad-hoc script under pressure becomes a resubmission. Take the decode width from the job's stamped `n_qubits`, not from a driver constant that has moved on. Report a non-`COMPLETED` job with a plain reason and skip it — one `DEPLETED` id must not abandon the other nine — and fail loudly on an unknown id rather than silently executing the row and buying the shots twice. Emit one uniform meter per job (mode `emulator | dry | live | refetch`, device, job id, qubits, shots, seed, estimated + billed HQC, derived delta/ratio) into the dump's `execution` block: `None` must mean "this lane has no such value", so a re-fetch keeps its real `qnx.jobs.cost` even with no estimate, or a resumed sweep reports itself as free. `SweepRunner(resume_from=…)` consumes cached jobs per row and falls through to execution once they run out. See `references/sweep-runner.md` and `references/nexus-jobs.md`.
29. **Run a known-fidelity Bell control beside every batch.** A `|Φ+⟩` pair in the same job costs almost nothing and is the only check that catches a *corrupted batch* rather than a wrong circuit: accept when `anti_correlated / shots <= 4*sqrt(0.5/shots)`, and **fail the whole batch** when it does not — a failed control reported as one bad row among twenty is decoration. Record `bell_anticorrelated` next to the target value in the dump so the check lives in the artefact, not the run log. See `references/evidence-integrity.md`.
30. **Name the trust layer you are actually on.** L1 receipts (job id, shots, seed, committed JSON) → L2 independent arbiters (multi-engine agreement, matched splits, the Bell control) → L3 cryptographic verification on an untrusted server (verified blind computation arXiv:2410.24133, VBPEC arXiv:2607.25704, logical accreditation arXiv:2508.05523). Most work is L1 + part of L2. Never write "cryptographically verified", and never write "ran on the QPU" for an emulator lane whose name shares a prefix with hardware. See `references/evidence-integrity.md`.
31. **Withdraw, don't soften — and run the dequantization gate first.** A result that fails to replicate at larger `n` is withdrawn outright and superseded, with the tool that serves it returning the negative and failing loud on a missing artefact rather than falling back to the flattering older one. Before any advantage claim, run the classical surrogate and report it either way (Born-Ultimatum, arXiv:2511.01845): if a classical method reproduces the distribution within error, the claim dissolves. The 128/512/2048 shot ladder is what separates "shot-noise-limited" from "classically equivalent" — flat metric with paired CIs crossing zero is the latter. See `references/evidence-integrity.md`.
32. **A `code: 14` "you do not have access to this machine" on an *emulator* is a config bug until proven otherwise.** `HeliosConfig()` silently defaults to `system_name="Helios-1"` — the hardware QPU — so a bare config asks for a machine you have no entitlement for and the vendor error names access while the fault is a field you never set. Pass `system_name=<device>`, add `emulator_config=HeliosEmulatorConfig(n_qubits=N)` (both 400 if missing), upload **HUGR** and execute the ref directly because Helios and the `*LE` backends reject pytket circuits and `start_compile_job`, whitelist HUGR runtime ops (`QAlloc`, `QFree`, `Measure`, `MeasureFree`, `Reset`, `helios.*`) in any gate-set preflight, and decode `hugr.qsystem.result.QsysResult` via `result.results[i].entries` — it has no `get_empirical_distribution`. Diff every name field against the device you meant before writing "unreachable" into a results table. See `references/nexus-jobs.md`.

33. **Circuit statistics come from a structural audit, never from recollection.** Compute gate count, CX fraction, depth and per-qubit idle windows from the compiled circuit and serve *that*. The idle windows are the useful part: a long ancilla idle band is the dynamical-decoupling insertion point, and a repeating parity-window cadence must match the encoding you think you compiled — if it does not, the compiler merged or dropped rounds and you will otherwise only see it as a mysteriously worse fidelity. Never let page copy hardcode a gate count the audit would contradict. See `references/agent-native-evidence.md`.
34. **An execution *spec* is not an execution.** A tool may hand an agent the submission contract — builder path (pytket vs HUGR), device, shots, config class, verification discipline — but that response carries no credentials, no job id, no fidelity and no "verified" wording; tokens stay env-only on the runner that holds the session. Generate the spec from the same source the submission path reads, or it is fiction. See `references/agent-native-evidence.md`.
35. **A Nexus account's backend widths are per-backend emulator ceilings, not the published QPU widths.** `H2-Emulator` exposes 26 qubits on an emulator-only account against a 56-qubit H2-1; `Helios-1E-lite` exposes 26 against a 98-qubit Helios-1. Read the width from the device record (or the backends page) and pin the datasheet figure only for the real QPU names. Same table, same trap: the config class is a *family* property — `QuantinuumConfig` for `H1-`/`H2-`, `HeliosConfig` for Helios, `AerConfig` / `QulacsConfig` / `SeleneConfig` for the hosted third-party simulators — and the wrong one fails as `code: 14`, which reads like an entitlement problem. See `references/nexus-jobs.md` (§Backend matrix).
36. **Re-ingest the project brain before any build that touches evidence.** `public/llms-full.txt` is the single source of truth for Lovable and other LLM tools; stale context is the #1 source of wrong generated copy. If the file has changed since the last session, paste the whole thing into the chat or upload it as project knowledge before editing. The skill cards fire on task type; the corpus carries the certified numbers. See `references/lovable-output-hygiene.md`.
37. **Generated copy must pass a certified/forbidden-language table.** Any quantum-advantage or result claim in Lovable output must be traceable to `public/llms-full.txt` or committed `src/data/demos/*.json`; a withdrawn or superseded result must be surfaced as the current state, never softened. End every build with the 8-convention checklist; if a line fails, report it in priority order and do not claim done. See `references/lovable-output-hygiene.md` (§The certified-state / forbidden-language table, §Close with a checklist).
38. **A submitted job is already billed — write the cache row at submit time, not at result time.** The window between "Nexus accepted the job" and "shots came back" is where an environment reset costs real money and leaves a paid result orphaned in the web console. Persist the **`Ref` itself** with `qnx.filesystem.save` plus a `status: "submitted"` cache row carrying the job id, both through an `on_submit(job_id)` hook the moment the id exists — the id string only recovers the job while `jobs.get(id=…)` still resolves it, the saved Ref recovers it from disk, and make the driver's main loop re-attach those rows via `fetch_result` **before** it considers submitting anything. A cell that has a job id is never a cell to submit. See `references/nexus-jobs.md` (§Submit-time persistence) and `references/sweep-runner.md`.
39. **Stamp the sweep coordinates, not just the run metadata.** `device / shots / seed / driver` identify a run; they do not identify *which cell* it measured. A recovered job without `band` and `noise_scale` (or whatever your sweep axes are) in its stamped properties can only be mapped back by submission order or by eyeballing which point of an accuracy curve it looks like — both are guessing, and guessing on a paid artefact is worse than losing it. Declare the axes in the job-property schema alongside the run metadata. See `references/nexus-jobs.md`.
39b. **Namespace the saved `Ref`s per run, and stamp the run id into Nexus too.** A flat ref store keys on the job id alone, so a cell re-submitted after a reset — or two sweeps running at once — overwrites evidence that was already paid for. Mint one sortable run id per process (`<gate>-<driver>-<utc>-<hash>`, overridable by an env var so a resumed process keeps writing into the directory it started), file every `Ref` + sidecar under `_cache_refs/<run_id>/`, and add `run_id` to the declared job-property schema so an orphan found in the cloud names the local directory that owns it. Reads must search the active run, then other runs newest-first, then the legacy flat root — never break the store you already have on disk.

40. **A property query returns COMPILE jobs next to your EXECUTE jobs.** Filtering only by project/property and then reading result fields raises `AttributeError` on the compile rows. Filter `job_type == EXECUTE` first, and read stamped metadata from `job.annotations.properties` — not from a top-level attribute. See `references/nexus-jobs.md`.
41. **The device-authorization path drifts between `qnexus` releases.** `/device/authorize` answers `{"detail":"Not Found"}`; the working path at the time of writing is `/device/device_authorization`. Read the endpoint out of the installed `qnexus.client.auth` instead of a remembered URL, and run the poll loop **in the background** — a foreground poller races the command timeout and dies while the user is still clicking Allow. See `references/nexus-jobs.md` (§Device login).
42. **Environment loss is the expected failure mode of a long cloud sweep, not an exception.** A sandbox reset wipes `.pydeps`, `/tmp`, and `~/.qnx/auth/token.json` while background workers may survive and keep blind-resubmitting against a dead session. Fixed recovery order: **kill the workers → reinstall deps → re-authenticate → purge guard-failure/dry-run rows → re-attach billed jobs → only then submit new cells.** Re-authenticating before killing the workers just lets them spend again. See `references/lovable-orchestration.md` (§Sandbox-reset recovery).
43. **Write Quantinuum code against a crawled docs corpus, not recollection.** All nine sites (Nexus, Guppy, Selene, tket user-guide, tket api-docs, lambeq, Quantum Origin, InQuanto, Systems) are Sphinx and enumerate every page in `searchindex.js` — there is no `sitemap.xml` on any of them. Refresh with `python -m quantum.docs_crawler.{fetch,extract,audit}` (`--site <slug>`), 830 pages / 3 799 snippets in ~6 min. See `references/quantinuum-docs-corpus.md`.

44. **Route every undocumented qnexus call through one pinned compat module.** The audit's drift list — `HeliosConfig`, `auth.login_with_token`, `auth.is_logged_in`, `devices.get_all`, `jobs.HybridStrategy`, `jobs.cost`, `jobs.get`, `users.get_self` — is exactly the cost-guard and resume surface. Undocumented does not mean unsupported, it means unversioned, and an upstream rename otherwise surfaces as a bare `AttributeError` deep inside a submission path *after* the HQCs are spent. Pin the client exactly (`qnexus==0.48.2`), fetch each drift symbol through a named accessor in `quantum/qnexus_compat.py` that raises a `QnexusDriftError` naming the symbol and both versions, call `assert_no_drift()` as a preflight so a moved symbol is fatal *before* submission, treat a version mismatch as a loud warning rather than a hard stop, and give the offline fake in `tests/fake_qnexus.py` a `__version__` matching the pin so the whole surface is exercised with zero submissions. Documented calls (`projects`, `circuits`, `hugr`, `filesystem`, `start_*_job`, `jobs.results`, `jobs.wait_for`) stay on plain `qnx.` — a compat layer that wraps everything stops being maintained.
45. **Use the documented job primitives before hand-rolling them.** `qnx.filesystem.save/load` persists a job `Ref` to disk (a ready-made submit-time durability path), `qnx.context.using_properties(...)` nests so sweep axes can be stamped without threading kwargs through every call, `qnx.jobs.results(..., allow_incomplete=True)` harvests a partially finished batch, and `cancel` / `retry_submission(retry_status=..., remote_retry_strategy=FULL_RESTART)` / `delete` cover the recovery cases we previously improvised. `qnx.devices.supports_shots(config)` is a preflight; `SelenePlusConfig` is the hosted Selene lane for cross-checking a local sweep. See `references/quantinuum-docs-corpus.md`.
46. **Only three Quantinuum docs sites expose `_sources`; the rest need an HTML path.** Nexus, tket and lambeq hand back the markdown/notebook twin at `/_sources/<filename>.txt`; **guppy, selene, inquanto, origin and systems 404 it** and must be scraped from rendered HTML. Take the article container, decompose nav/sidebar/footer, and re-fence each `div.highlight pre` using the parent `highlight-<lang>` class *before* stripping tags — a plain tag-strip keeps the prose and loses every code block, which is the only part worth auditing. Lambeq's 16 `.ipynb` sources still need the notebook flattener.
47. **tket has no single docs root.** `tket/user-guide/` and `tket/api-docs/` are separate Sphinx builds with separate search indexes; `docs.quantinuum.com/tket/searchindex.js` 404s. Register them as two sites or the richest snippet source in the whole corpus (750 blocks from 28 user-guide pages) is silently missing.
48. **Per-library drift is where the next gate hides.** Current audit: guppy clean but we ignore `guppy.load_pytket` and `guppy.nat_var`/`type_var` (generic-width kernels that would collapse our per-n kernel factories); tket documents `Backend.get_operator_expectation_value`, `pytket.utils.expectation_from_counts/shots` and `partition.measurement_reduction` that we reimplement by hand; selene's own examples use `selene_sim.result_handling.parse_shot` + `hugr.qsystem.result` where we hand-roll parsing; `selene_sim.build` is undocumented despite being our entry point. Quantum Origin is CLI/concept prose (5 snippets in 52 pages) — do not expect an importable Python API.

49. **Diff the drift list against the docs automatically, or it rots in both directions.** The list lives twice — prose in the audit, executable truth in `DRIFT_SYMBOLS` — and neither notices when the vendor documents a symbol or a new gate adds an unguarded one. `quantum/docs_crawler/drift_watch.py` derives all three sets (crawled `api_surface.json`, real call sites, `DRIFT_SYMBOLS`) and grades each symbol `stable | newly-documented | undeclared | obsolete`; `--check` exits non-zero, `audit.py` renders the table into both reports, and `tests/test_drift_watch.py` fails the day it goes stale. Two traps make such a diff lie: it must count **compat-mediated** use (once a call is routed through the layer nothing writes `qnx.jobs.cost(` any more, so a direct-call scan grades the whole guarded surface `obsolete` and invites deleting the cost guard — keep a symbol→accessor map for this), and it must **tokenize before scanning** (a plain regex counts `qnexus.auth.login()` inside a docstring and invents an `undeclared` symbol). Stamp the state with the crawl's timestamp: a stale corpus produces confident, stale verdicts.

50. **`max_cost` guards one job; a sweep needs a ledger, and both guards must run before the upload.** Two preflights belong ahead of every paid submission, on the dry-run path as well as the live one — a rehearsal that skips them proves nothing about the spend. First, `qnx.devices.supports_shots(config)`: a distribution-only backend happily accepts a shot-based job and then returns results the shot decoder cannot read, so the refusal has to land before the upload, not after the bill. Second, a per-process **spend ledger**: `max_cost` is enforced server-side per job, so thirty cells at the ceiling cost thirty ceilings; book the estimate the moment Nexus accepts the job (not when the result comes back — that window is exactly where a sandbox reset strands paid work), refuse the next cell when `estimated_total + next > NADARASA_MAX_TOTAL_HQC`, and add `qnx.jobs.cost` billed figures **alongside** the estimates so the dump shows both. `qnx.circuits.cost(...)` gives a truer pre-submission number but is itself billable — keep it opt-in (`NADARASA_COST_PROBE=1`) and let it override the local formula only when it answers. Surface the whole ledger (`budget / jobs / estimated / billed / remaining`) in the dump's `execution` block; `None` must keep meaning "this lane has no such value".

51. **A snapshot audit can describe the API; only a committed baseline can catch it changing.** The expensive failure is a Guppy/Selene/tket/InQuanto symbol moving upstream and surfacing as a crash mid-way through a billed sweep. `quantum/docs_crawler/api_diff.py` snapshots each site's **imports + calls + page set** into `<slug>/api_baseline.json` and grades the next crawl `added | removed | moved | breaking`, where the only difference between `removed` and `breaking` is whether *our* code depends on the symbol; `--check` exits non-zero, `--accept` is a deliberate human sign-off, and the rows render into `AUDIT.md`. Four ways this goes wrong: keying on **calls alone** (the documented call surface is a third of the import surface — Guppy 13 vs 45 — and this repo touches Guppy almost only via `from guppylang.std.quantum import h`, so real removals grade as unused), a **stale `our_files`/`our_globs`** in `sites.py` (a new importer nobody added silently downgrades `breaking` to `removed` — widen the globs in the same commit that adds the import), **treating unknown as broken** (missing baseline, uncrawled site, or an empty `.pydeps` after a sandbox reset must stay silent, never `breaking`), and **over-confident rename inference** (pair a removal with an addition only when the match is unique — same leaf under a new parent, or exactly one out and one in under the same parent; anything ambiguous stays a plain removal). `--introspect` resolves used symbols against the installed packages with `importlib`, catching removals the docs still advertise.

52. **Executing the documented examples is the only check that catches semantic drift — and the harness itself is the main source of fake failures.** `api_diff` proves `selene_sim.build` still exists; it cannot tell you the Selene user guide's `result("x", measure(q))` no longer compiles under Guppy 1.x (it doesn't — every emulation page in that guide fails, the same `measure().read()` migration as Gotcha #16). `quantum/docs_crawler/snippet_run.py` runs each page's blocks **in document order, in one namespace, written to a real `.py` file** — never `exec(code_string)`, because Guppy compiles kernels by reading their source back with `inspect.getsource` and a string-exec harness turns 34 healthy Guppy examples into `OSError: source code not available`; per-block attribution comes from a `_snip_mark(i)` line between blocks, which (unlike wrapping each block in `try:`) leaves the doc code unindented for `getsource`. Three more harness traps, each of which manufactures failures that look like upstream breakage: banning **all** sockets (Selene talks to its own emulator over loopback — block non-local `connect`/`getaddrinfo` only), leaving the **temp page path in the recorded reason** (every run then diffs against its own baseline — normalise it to `<page>`), and reading only stderr's last line (Guppy prints the real diagnostic to *stdout* and ends with the useless "Guppy compilation failed due to 1 previous error"). Grade causes apart: `fail` means a genuine breakage, `NameError`/`ModuleNotFoundError`/memory-cap kills are `blocked`, an absent library is `skipped`, and only `pass -> fail` is a regression. Prefilter anything naming `qnexus`, `start_execute_job`, `QuantinuumBackend` or an API key as `blocked` **before** it can run, and keep a committed test that re-derives that from the corpus — a docs pass must never spend money.

54. **When the batch budget runs out, split the batch — don't throw the run away.** A ledger that only knows how to refuse turns a 19-cell sweep into zero cells the moment the 15th crosses `--budget-hqc`, and the operator's only recovery is to hand-slice the parameter list. Give the ledger a `budget_mode`: `halt` (default, unchanged refusal) and `split`, which submits the largest **prefix** that fits and raises `BudgetPaused` — a stop signal, not a failure. Four rules make this safe. Split on a *prefix*, never a knapsack: the deferred tail must be contiguous and resumable, not a scattered set the operator has to reconstruct by hand. A single job whose estimate alone exceeds the whole budget is a hard `BudgetExceeded` in **both** modes — splitting cannot rescue an indivisible cell. `BudgetPaused` subclasses the backend error, so every driver that writes an `"error"` row on `BackendError` must catch it **first** and re-raise: a paused cell has not run yet, and poisoning its cache row makes the remainder unresumable. And report it — `deferred_jobs`/`deferred_hqc`/`budget_mode` in the summary, the deferred coordinates in the dump, and one console line saying exactly what a re-run with a higher ceiling will pick up.

55. **Reconcile spend per job, not per run — and make the record outlive the process.** A batch total answers "did we stay under `--budget-hqc`?" and nothing else; the question that costs money is *which cell* blew its estimate. Open a reconciliation entry on `SpendLedger` at `record_estimate` (submission time, when the money is committed) and close it at `record_billed` with the real `qnx.jobs.cost` figure, grading the pair with one shared function so the console during the run and the audit report afterwards can never disagree. Four rules. A missing bill is `unbilled`, never `on_budget` and never summed as `0.0` — coercing silence to zero flatters every rollup that touches it, so skip `None` in totals and let the total go `null` instead. Grade against a tolerance (10%) rather than exact equality: the local gate-count estimate is approximate by construction, and a zero-tolerance check cries wolf on every job. Stamp the closed entry into the job's `.meta.json` sidecar (`nexus_refs.stamp_cost`) and add `cost` to `VOLATILE_KEYS` — the bill lands *after* the record was checksummed at submission, so it must not make a healthy sidecar read as tampered-with. And print overages in `budget_line`, not only in JSON: an overage that only exists in a file nobody opens is an overage nobody reviews. The offline exporter (`python -m quantum.cost_report --dumps`) reads sidecars first and falls back to `budget.entries` in committed dumps, so a run whose sandbox was reset still reconciles.

53. **A saved job `Ref` is only evidence if you can prove it is the file you wrote.** `qnx.filesystem.save` gives no checksum and no atomicity, so a sandbox reset mid-write leaves a truncated `.ref.json` that still parses — or does not — and `resume` will happily decode paid shots into whatever coordinates the sidecar claims. Write `schema` (`nexus-ref/1`), `ref_sha256`, `ref_bytes` and a self-excluding `meta_sha256` into the sidecar the instant the ref lands, and have `load_ref`/`saved_job_ids`/`resume` verify by default and **skip** (never guess) a record that fails. Four rules keep this honest: the meta digest must exclude **its own key and every volatile key** (`last_status`, `status_at`) or routine status polling reads as tampering; records written before the schema must grade `legacy` — trusted but unprovable — and be upgradable with an explicit `restamp` that never invents coordinates; a sidecar that is simply **absent** is `unverifiable`, not corrupt, and must not fail the ledger verdict; and `--skip-verify` has to exist as a loud emergency rescue, because refusing to read a slightly damaged store is a worse outcome than reading it under protest when real HQCs are on the other side. Surface the verdict per row in `/nexus/refs` — an integrity layer nobody can see is an integrity layer nobody trusts.

56. **Print the shot-capability matrix before the sweep, and make `unknown` mean missing information.** `devices.supports_shots(config)` answers per *config object*, so a census that probes every backend has to build each one through its family's config class (`QuantinuumConfig` / `HeliosConfig` / `AerConfig` / `QulacsConfig` / `SeleneConfig`) — probe them all through one class and the answers are fiction. Build the matrix in the dry-run branch (`python -m quantum.device_matrix`, `_print_device_matrix`) so the devices a sweep would skip are named *before* submission, with the reason attached: `no` from the probe is `SKIP - distribution-only`, a width below `n_qubits` is `SKIP - too narrow`. The rule that keeps it safe is the third verdict: a device whose config class is absent from the installed client, or whose probe could not run because the session is down, grades **`unknown` and stays usable** (`usable is None`, never `False`) — deleting a working backend from an operator's options because a helper was missing is a worse failure than probing it again. Keep the matrix strictly **advisory**: cache it on the backend, surface it in `describe()` and as a committed no-claim dump, but never let it replace the per-submission `supports_shots` preflight, because a table generated minutes ago is not a promise about the job you are about to pay for. Never raise from the builder — degrade to the pinned table with a `source: "pinned"` note.

57. **Make withdrawal structural, and close a question by counting closures.** "Withdraw, don't soften" (#31) is a policy a tired writer forgets; a resolver cannot forget. Put one manifest in charge of artefact state — `current | superseded | archived`, keyed by claim kind — and make every consumer (MCP tool, route loader, report builder, PDF) read *through* it rather than by filename, so a superseded dump is unreachable by construction and a resolution failure raises instead of falling back to the newest readable file. Two reporting rules travel with it. A negative result is not closed by one experiment: report the **count of independent closures** and name each one (Fourier wall / small-`n` simulation / real-kernel refusal / shot-floor / shot-scaling seal), because a single negative always invites "you didn't try hard enough". And a leg stopped by a platform limit is **`assessed-blocked`, not untried** — record the limit and the error string, or the row reads as a gap in the work and someone re-runs the thing that cannot run. See `references/evidence-integrity.md`.

58. **One versioned receipt envelope per artefact, graded four ways.** Scattering shots in the meter, the commit in a provenance hash and the tolerance in a driver means nothing can audit them as a unit. Attach a named, versioned block (`qas/envelope/0.1`) to every result artefact: `claims` (sentences that could be false, not topics), `engine` **plus a separate `backend_qualifier`** so a device name can never be read as hardware, `shots`, `seed`, `commit`, the computed `envelope` (`4*sqrt(0.5/shots)`, stored so a later reader can re-decide the verdict), and `verdict`. Then grade every artefact with a script, and use four grades, not two: `PASS`, `GAP` (envelope present, a field missing — fill it, don't downgrade the claim), `STRUCTURAL` (no envelope at all — migrate or move it to the no-claim list), `FAIL` (envelope present and *contradicted* — block the build). The `GAP`/`FAIL` split is the whole point, and it is the same rule as the device matrix's `unknown` (#56): missing information is not a lie. The rule that holds even before the tooling exists — never display a number without its engine qualifier and shot count in the same view. See `references/receipt-envelope.md`.

59. **The hosted Selene lane has a depth ceiling, and an agent's choice of observable is the thing no automated check validates.** `SelenePlus` runs 17-qubit *plain* circuits fine but dies on 17q with Toffoli/CSWAP depth with `Unexpected end of stream`, reproducibly across circuit structures — a server-side size limit, not a kernel bug: don't bisect your circuit, record the leg as assessed-blocked and re-certify on `H2-Emulator`. The companion lesson is the verification gap PASQAL demonstrated: an agent proposed a plausible-but-wrong observable and then a wrong *hardware* diagnosis to explain the result, and nothing downstream caught either, because every automated layer (envelope, Bell control, digest, verdict test) checks **consistency**, not correctness — a wrong observable measured perfectly passes them all. The observable is a scientific judgement wearing the clothes of a config field sitting next to `shots`, so the review gate belongs *before* execution, on the credential-free spec (`experiment_spec.json` is the same object #34 calls an execution spec — convergent design), with the observable, its baseline and its falsification criterion legible in one screen for a human who knows the physics. See `references/nexus-jobs.md` (§Sizing) and `references/agent-native-evidence.md` (§The verification gap).

60. **A dependency-gated test proves nothing until you run it with the dependency actually gone.** The quickstart notebooks (`quantum/docs_crawler/notebooks.py`) have exactly one executable cell — an env check — and `pytest.importorskip` around it only ever exercises whatever `.pydeps` happens to hold that session, so the skip path is *assumed*, never observed; the first time the library is genuinely absent is the first time you learn the cell fails instead of skipping. The gate that works runs the real test in a **child pytest** with a `meta_path` finder raising `ModuleNotFoundError` for the target module and its submodules, and asserts on the reported outcomes: zero failures, exactly one skip, and a reason naming both the module and its install command. Four rules keep it honest — block the module in the **child**, never the parent session (a parent-side blocker leaks into every later test in the file); parametrise over the spec's *declared* `env_modules`, and keep a separate test re-deriving that list from the cell source, so a newly added import cannot silently escape the guard; a child that fails to start is a **skip carrying its stdout**, never a silent pass; and pair the whole thing with a **byte-level** regeneration check (`read_bytes()`, not nbformat object equality), because indentation, key order and the trailing newline drift between the committed `.ipynb` and a fresh build long before the parsed objects do. Same reasoning downstream: the `/skills` cards are parsed out of the generated markdown with deliberately defensive parsers, so a shape change empties them *silently* — the manifest test asserting non-empty topics and pitfalls is the only thing that notices. See `references/quickstart-notebooks.md`.

61. **A Nexus submission is a four-step contract, and three of its four failure modes are pre-flight, not physics.** The contract is **upload → compile → execute the *compiled* ref → download**: `qnx.circuits.upload(circuit, name=…)` first, because `programs=` takes a Nexus ref and never a local `pytket.Circuit` — the step most copy-paste examples omit, so an agent starts from a `circuit_ref` it has no way to obtain. `programs=` is the current keyword; `circuits=` is its deprecated spelling and surfaces as a deprecation/schema error rather than a rename hint. The accessors are not interchangeable either: a compile job's `CompilationResultRef` gives `.get_output()` (the compiled ref), an execute job's `ExecutionResultRef` gives `.download_result()` → `.get_counts()` / `.get_empirical_distribution()`, and `ExecutionResultRef has no attribute 'get_output'` means a compile ref and an execute ref got crossed in a resume or re-attach path, not that qnexus is broken. Before the first API call, check four things in order — the interpreter that actually holds `qnexus` (the `.pydeps`/venv binary, never bare system python, else `ModuleNotFoundError: No module named 'qnexus'`), a live session, an **active project** resolved by name from `qnx.projects.get_all()` and set with `qnx.context.set_active_project(...)` (else `NoActiveProjectError` or a bare 403 several calls later), and the right config family. Independently corroborated device capacities: `H1-1LE` 20q, `H2-1LE` 56q, `Helios-1E-lite` 50q+. See `references/nexus-jobs.md` (§The compile → execute → download flow, §Pre-flight).








## Navigation


| Task | Read |
| --- | --- |
| Write a kernel (gates, qubits, measurement, controlled phase) | `references/guppy-language.md` |
| SWAP test, Toffoli, CSWAP, amplitude encoding, controlled phase, coset-state QFT readout, parity windows, feed-forward, inverse-QFT-no-swap, CSWAP-chain shifts, host-side metrics | `references/circuit-patterns.md` |
| Guppy v1 migration: renames, emulator builder, compatibility shim, optimisation levels | `references/guppy-v1-migration.md` |
| Parameterized circuits over many inputs; angle hygiene; sys.path injection; `build(mod.program)` shim | `references/driver-pattern.md` |
| Parameter sweeps as first-class objects (`SweepSpec` + `SweepRunner`); resumable per-row cache; per-job meters; resuming a paid hardware sweep | `references/sweep-runner.md` |
| QSP/QSVT kernel + NumPy phase-finder loop recovering φ from a target polynomial | `references/qsp-qsvt.md` |
| Real controlled `pow_const_mod` for small-N Shor (CSWAP-chain cyclic shifts) | `references/shor-modexp.md` |
| Quantum Phase Difference Estimation (QPDE) + ethylene 2-qubit chemistry benchmark | `references/qpde.md` |
| ADAPT-GQE: generative transformer + RL circuit synthesis for molecular ground states | `references/adapt-gqe.md` |
| Nadarasa v0.4.2 reference stack (G16–G19: QPDE, noise + ZNE, TDA, Floquet validation) | `references/nadarasa-v042-stack.md` |
| [[7,1,3]] Steane color code, RGT gadget, partial-FT gadget-insertion cadence | `references/encoded-circuits.md` |
| Quantum-TDA Laplacian moments `T_k^(d)` + WL-indistinguishable synthetic dataset | `references/laplacian-moments-tda.md` |
| Trust ladder (L1/L2/L3), per-batch Bell control, dequantization gate, withdrawal + supersession rules, forbidden phrasings | `references/evidence-integrity.md` |
| Structural withdrawal (manifest as sole resolver), closure counting, `assessed-blocked` reporting | `references/evidence-integrity.md` (§Structural withdrawal, §Negative-result discipline) |
| Receipt envelope `qas/envelope/0.1` and the PASS / GAP / STRUCTURAL / FAIL artefact grading | `references/receipt-envelope.md` |
| Generated quickstart notebooks: spec shape, `--only`/`--out` CLI, env-check gating, byte-match test, `/skills` cards | `references/quickstart-notebooks.md` |


| Cross-platform validation hierarchies (PEC + ZNE / QESEM, IBM ↔ Quantinuum corroboration) | `references/cross-platform-validation.md` |
| TKET / pytket offline compile lane, native rebase, equivalence oracle, Selene round-trip | `references/pytket.md` |
| Quantinuum hardware roadmap (Helios → Sol → Apollo → Lumos) — what runs where and when | `references/hardware-roadmap.md` |
| Submitting real Nexus jobs: login, projects/properties, compile→execute→distribution, job lifecycle, cost control, backend matrix, sizing, bit-order calibration | `references/nexus-jobs.md` |
| Helios lane: `system_name`, `emulator_config`, HUGR upload, `QsysResult` decoding, the code-14 misdiagnosis | `references/nexus-jobs.md` (§The Helios lane) |
| Nexus accounts: organizations/groups/teams, roles and permissions, the four quotas, priority, usage reports, pre-spend checklist | `references/nexus-admin.md` |
| QIR lane (Guppy → HUGR → QIR), pinned 0.21 venv, `qircheck` constraints, execution gap | `references/qir-lane.md` |
| Error-detected inner products: repetition-encoded SWAP test + parity post-selection accounting | `references/error-detected-inner-products.md` |
| Serving committed evidence to other agents (MCP tools, agent card, x402 gate, mock/real toggle) | `references/agent-native-evidence.md` |
| Structural circuit audit (idle windows → DD points, parity cadence) and credential-free execution specs | `references/agent-native-evidence.md` (§Structural audit, §Execution specs) |
| The verification gap: agent-chosen observables need pre-execution expert review | `references/agent-native-evidence.md` (§The verification gap) |

| Lovable output hygiene: project brain, certified/forbidden language, 8-convention checklist, re-ingest rule | `references/lovable-output-hygiene.md` |
| Skill-authoring hygiene: trigger-led descriptions, one job per skill, always-on rules, closing checklist | `references/lovable-orchestration.md` (§Writing and pruning this skill) |
| Render any Selene experiment via the `selene_run` v1 schema + `<SeleneRunView />` | `references/selene-run-schema.md` |
| Compile and run shots; multi-result decoding; mid-circuit measurement; ancilla reuse; noise models (depolarizing, leakage, realistic H2 targets); shipping results to the frontend | `references/selene-runtime.md` |
| Tomographic equivalence proofs (18-cell 1q, 324-cell 2q) + conjecture-synthesis pipeline | `references/tomographic-equivalence.md` |
| Edge-runtime mini-sim + live SSE shot stream from the Worker | `references/live-sampler.md` |
| Legacy bespoke React wiring (pre-schema demos) | `references/frontend-integration.md` |
| **Which primitive at which stage** — unified cheat sheet mapping Guppy / pytket / Selene / qnexus / Systems / InQuanto primitives onto the model→kernel→compile→verify→execute→recover→analyse→publish spine | `references/stack-cheatsheet.md` |
| Crawled docs corpus for all nine Quantinuum sites, per-library API-drift audits, documented job/ref/property primitives | `references/quantinuum-docs-corpus.md` |
| Generating the Guppy / Selene / tket / lambeq quickstart notebooks from the corpus (selection rules, prose-vs-code filter, pinning a bad pick) | `references/quantinuum-docs-corpus.md` (§Quickstart notebooks) |
| API-surface diff across all nine sites: baselines, `breaking`/`moved` grading, `--accept` sign-off, `--introspect` | `references/quantinuum-docs-corpus.md` (§Catching upstream change) |

| Composing a generated/variational ansatz with the Clifford canonicaliser (safe vs unsafe segments) | `references/rewriter-composition.md` |
| Minimal smoke-test script | `scripts/qtda_template.py` |
| Working around Lovable turn-rollback / "internal error" loops on Guppy/Selene experiments | `references/lovable-orchestration.md` |



## Generative AI circuit synthesis

ADAPT-GQE (arXiv:2607.22468) is a new route to quantum chemistry circuits: train a transformer on ADAPT-VQE references, then use RL to refine the generated circuits past the training-data accuracy. If a future task touches generative circuit synthesis, the practical notes are in `references/adapt-gqe.md`. The key takeaway: the generated circuit is still a Guppy kernel, so the same angle-hygiene, tomographic-verification, and committed-JSON rules apply.




## Running as a team

When the work is split across agent profiles or sub-agents (orchestrator / runner /
analyst / scribe), keep the boundaries hard:

- Long sweeps go to a **runner** that only executes and reports artefact paths. It does
  not interpret, fit, or claim.
- The **per-row JSON cache** is the hand-off artefact between runner and analyst — never
  a chat summary of the numbers. If it isn't in `_cache_<name>/` or `src/data/demos/`,
  it didn't happen.
- No claim crosses a profile boundary without its verification evidence attached: the
  shot count and `4*sqrt(0.5/shots)` verdict for a probability comparison, the 1e-9
  unitary-oracle result for a gate-count reduction, the artefact path for anything else.
- The writer cannot introduce a number that is not already in an artefact.

See the `hermes-agent` skill for the profile mechanics behind this split.

## Quick smoke test

```bash
code--copy knowledge://skill/quantinuum/scripts/qtda_template.py /tmp/qtda_template.py
code--exec python /tmp/qtda_template.py
```

Should print a fidelity in `[0, 1]` for two amplitude-encoded states.

## Reference implementations

- `quantum/qtda.py` — SWAP-test worked example: 8 patients, 28 pairs, Vietoris–Rips filtration, Betti numbers, JSON output consumed by the React routes.
- `quantum/nadarasa_g1.py`, `g2.py`, `g3.py` (+ `*_lib.py`) — coset-state QFT readout, mid-circuit parity windows with ancilla reuse, Birthday-style host-side post-processing.
- `quantum/nadarasa_g4.py` — feed-forward / mid-circuit `if measure(...)` branching.
- `quantum/nadarasa_g8.py`, `g9.py` and `quantum/nadarasa_g1_via_sweep.py` — parameter sweeps via `quantum/sweep.py` (`SweepRunner`). G1-via-sweep is the byte-identical-headline-metrics parity check for the refactor.
- `quantum/nadarasa_g10.py` + `quantum/nadarasa_g10_phasefinder.py` — QSP `qsp_sequence` kernel with hand-chosen φ and the SciPy Powell loop that recovers φ from a target polynomial (Chebyshev `sign(x)`, max |measured − target| < 0.05).
- `quantum/nadarasa_g11.py` + `quantum/nadarasa_g11_real.py` — small-N Shor: compiled `f(x) = x mod 4` shortcut vs. real controlled `pow_const_mod` for `a=2, N=15` implemented as CSWAP-chain cyclic shifts on the orbit of `|1⟩`.
- `quantum/pqp_frontier/tomography.py` + `conjectures.py` — 18-cell 1q tomographic equivalence harness and the driver that PASS-proved 11 conjectured gate identities.
- `quantum/pqp_frontier/noise_resilience.py` + `noise_leakage.py` — `DepolarizingErrorModel` and `SimpleLeakageErrorModel` sweeps showing rewriter-stripped `AQFT_k1` beats full QFT under noise (G1, N ∈ {16, 32, 64}).
- `quantum/pqp_frontier/noise_2q.py` — canonical resumable 2q noise sweep: per-cell cache under `_cache_2q_noise/`, static JSON dumped to `src/data/demos/pqp_frontier_noise_2q.json`, rendered by `src/routes/nadarasa.proofs.noise-2q.tsx` with no server function.
- `quantum/qpde/model.py`, `kernel.py`, `sweep.py`, `validate.py` — full ethylene QPDE benchmark (G16): 20-cell resumable sweep (20/20 PASS), gap fit 0.8099 vs 0.8000 Ha, static JSON at `src/data/demos/qpde_ethylene_selene.json` rendered by `src/routes/nadarasa.g16.tsx`.
- `quantum/qpde/noise.py` + `quantum/qpde/zne.py` — H2-class depolarizing ladder + Richardson quadratic ZNE on the QPDE gap fit (G17): `src/data/demos/qpde_ethylene_noise.json` + `qpde_ethylene_zne.json`, rendered by `src/routes/nadarasa.g17.tsx`.
- `quantum/tda/dataset.py`, `moments.py`, `sweep.py` — Laplacian propagator trace estimator on a WL-indistinguishable C6 vs 2C3 pair (G18): 384-circuit resumable sweep, `src/data/demos/tda_laplacian_moments.json`, rendered by `src/routes/nadarasa.g18.tsx`.
- `src/routes/nadarasa.g19.tsx` + `src/data/nadarasa/quantinuum-2026.ts` — reading note on Leviatan et al. 2026 heavy-hex Floquet QESEM result and cross-platform validation hierarchy.
- `quantum/floquet/model.py`, `kernel.py`, `sweep.py`, `noise.py`, `zne.py` — mixed-field Ising Floquet native port (G20): 384 production cells across chain + heavy-hex-6, ideal-vs-ED max deviation 0.0495, H2 noise ladder + quadratic Richardson ZNE to <2% error, `src/data/demos/floquet_native_zne.json` rendered by `src/routes/nadarasa.g20.tsx`.
- `quantum/adapt/adapt_h2_uccsd.py`, `kernel.py`, `smoke.py` — ADAPT-GQE composition (G21): H2 UCCSD single excitation verified by matrix oracle (1.1e-16), Clifford frames canonicalised by rule (M), 512-shot Selene agreement 0.018; `src/data/demos/adapt_gqe_composed.json` rendered by `src/routes/nadarasa.g21.tsx`.
- `quantum/tket/circuits.py`, `compile.py`, `verify.py`, `selene.py`, `sweep.py` — TKET compile lane (G24): six circuit families in raw vs Nadarasa form, offline `QuantinuumBackend("H2-2")` compilation at levels 0/1/2, unitary-equivalence oracle gating every count, and a Selene round-trip of the compiled natives. TKET level 2 matches the reduced 2q counts on 4 of the 5 scored families; Simon (G23) is the one case where the rewriter stays ahead (3 vs 5 two-qubit gates, a non-local involution a peephole window cannot see). `src/data/demos/tket_compile.json` rendered by `src/routes/nadarasa.g24.tsx`.
- `quantum/emulate.py` — the single execution entry point: Guppy v1 emulator builder behind the legacy `build(program).run_shots(Quest(), ...)` call shape, plus re-exported simulators, error models, and `OptimizationLevel`.
- `quantum/backends.py` + `quantum/backend_selene.py` + `quantum/backend_nexus.py` — the emulator/hardware switch, device-capability preflight, HQC ceiling, and the `job_meter` record every lane emits.
- `quantum/resume.py` — `python -m quantum.resume`: re-attach to Nexus jobs already billed, by id, by a dump's `execution` block, or by property query; caches shots + properties + meter under `quantum/_cache_resume/<job_id>.json` for `SweepRunner(resume_from=…)`. `tests/test_resume.py` + `tests/fake_qnexus.py` cover it offline, each test asserting the fake recorded zero submissions.

- `quantum/pqp_frontier/dump_conjectures.ts` + `dump_conjectures_2q.ts` — TS-side matrix oracle, enumeration, structural rewriter, and matrix-canonical promotion (rule N / rule M) driving `/nadarasa/proofs/conjectures*`.


For new demos, render results through the shared `selene_run` schema (`references/selene-run-schema.md`) instead of building a bespoke React page.

## OpenClaw notes

This skill is loaded on demand: OpenClaw advertises the path plus a `sha256` version marker and the model `read`s this file when the task matches. Keep edits in a managed copy under `~/.openclaw/skills/quantinuum/` so they survive updates. Gotcha 10 ("Lovable internal error = turn rollback") is Lovable-specific and can be ignored elsewhere; the underlying discipline — one committable artefact per gate, resumable caches — still applies to any long sweep.
Quantum Agent Engineering

SKILL.md
