# quantum/ — circuit emission primitives

Reversible-circuit emission primitives written in lumbda Scheme: Clifford gates, ripple-carry adder (Cuccaro), modular arithmetic, modular inverse strategies, Karatsuba multiplier, Clifford tableau simulator, circuit scoring. Originally developed at foxhop for secp256k1 attack-surface research; shared upstream under AGPLv3.

## Layers

### Core gates

- `gates.lsp` — Clifford gate library: `CX`, `CCX` (Toffoli), `X`. Counts Toffoli + Clifford totals as side effect for scoring.

### Arithmetic

- `adder.lsp` — Cuccaro ripple-carry reversible n-bit adder. Width-parametric.
- `mod-arith.lsp` — modular add/sub/cmp/neg/mul/square under `*field-prime*`. Default unset; consumer binds (foxhop sets secp256k1 `p`).
- `mod-karatsuba.lsp` — Karatsuba reversible multiplier for ⊕-bit widths. Width-parametric.

### Modular inverse strategies

- `mod-inv-by.lsp` — Bennett by-value-uncompute pattern (host classical `1/x`, then quantum verify-and-zero).
- `mod-inv-by-dialog-gcd.lsp` — Dialog GCD (binary extended Euclidean) reversible mod-inv. General algorithm, not field-specific.
- `mod-inv-by-dialog-gcd-host.lsp` — Host-assisted variant: classical GCD trace replayed as quantum dialog log.

### Simulation + scoring

- `sim.lsp` — Clifford tableau simulator. Verifies emitted circuits against expected truth tables.
- `score.lsp` — circuit metric collector. Tracks Toffoli + qubit + Clifford counts during emission.

## Width discipline

Every primitive width-parametric — no hardcoded `n = 256`. Consumers bind `*field-prime*`, `*width*`, and optional flags (e.g. `*mod-mul-use-karatsuba*`).

## Hard rule — bound every loop, bound every ancilla

- `*max-shots*` caps shot counts in sim (default 64 for dev; raise only by explicit instruction).
- Every `alloc!` call site asserts width-cap at top of caller. Unbounded growth = host hard-freeze on neoblanka (proven 2026-06-11/12).

## Lumbda tier compatibility

These primitives run under any lumbda tier (Python VM, C tree-walker + JIT, C + x86 JIT, pure x86 asm). Cross-tier portal validation: same `.lsp` on Python-tier + C-tier must produce byte-identical result S-expressions. Mismatch halts promotion.

## License

AGPLv3.