Generalized compile-time circuit signatures

• Status: proposed
• Revision: 1 (2026-08-09)
• Target contract: 0.1.0-experimental
• Feature flag: experimental.genericCircuits=true
• Owners: language, compiler, tooling, stdlib, product
• Depends on: NM-RFC-0002 exact-version imports, NM-RFC-0013 token frontend, NM-RFC-0014 compile-time constants
• Does not change: stable N/M 0.1 circuit templates, runtime register sizing, statevector ceilings, or NM-RFC-0010 oracle types

1. Summary

N/M 0.1 circuit templates accept one concrete QReg<K> followed by scalar Angle parameters. They are useful for fixed teaching circuits, but cannot express a reusable unitary over two disjoint register views or bind a register width at the call site.

This RFC adds an explicitly negotiated compile-time circuit layer:

circuit entangle<const N: Int>(
  control: QReg<N>,
  target: QReg<N>,
  theta: Angle
) {
  for i in 0..N {
    Ry(target[i], theta);
    CNOT(control[i], target[i]);
  }
}

entangle<2>(q[0..1], q[2..3], PI / 4);

Every const argument, register width, register view, loop and modifier is resolved before executable AST/IR reaches a simulator or target-lowering pass. The feature is type-safety and source-reuse work; it is not a scalability claim.

2. Goals

• Bind one or more const ...: Int parameters at compile time.
• Accept multiple exact-width QReg<E> parameters and scalar Angle parameters in declaration order.
• Permit disjoint views of one physical register while rejecting overlapping views.
• Monomorphize bodies deterministically with source-map and specialization metadata.
• Apply adjoint, at most two-control ctrl, and positive bounded pow through real modifier AST nodes.
• Supply exact-version qft<N> and iqft<N> façades for the measured statevector-ready range.
• Reuse NM-RFC-0010 generic Grover unchanged instead of inventing a second oracle convention.
• Keep unsupported composition fail closed in Core, token frontend, CLI, Worker, Playground, LSP, VS Code, exporters and package readers.

3. Non-goals

• Runtime-sized QReg or runtime generic arguments.
• Dynamic dispatch, closures, reflection, recursive circuits or overload resolution.
• Generic return values, measurement, reset, allocation, sampling, noise, training or runtime control inside a generic circuit.
• Implicit aliasing or overlapping register parameters.
• Arbitrary multi-controlled synthesis in the compiler.
• Raising browser/server statevector ceilings.
• Generic QPE, Simon or Shor readiness.
• Treating a generic signature as hardware or asymptotic-performance evidence.

4. Source grammar

The declaration form is closed:

generic-circuit = "circuit" identifier "<" const-params ">"
                  "(" circuit-params ")" "{" unitary-body "}" ;
const-param     = "const" identifier ":" "Int" ;
circuit-param   = identifier ":" "QReg" "<" const-expression ">"
                | identifier ":" "Angle" ;
generic-call    = identifier "<" const-arguments ">"
                  "(" call-arguments ")" ";" ;

At least one const parameter and one register parameter are required. Names must be unique across const, register and scalar parameters. A declaration without <...> remains the stable concrete N/M 0.1 circuit form and does not require negotiation.

Const expressions use NM-RFC-0014's closed checked integer grammar. This RFC does not add sqrt, floor, exponentiation or runtime variables.

5. Parameter and ownership rules

• Every QReg<E> width must resolve to a positive integer.
• A full register argument must have exactly the declared width.
• An inclusive register slice may satisfy a parameter when its length is exact. Ascending and descending slices preserve their explicit order.
• Every physical qubit (register, index) may appear in at most one register argument of a call. Overlap is NM-CIRCUIT-006.
• Scalar Angle arguments are substituted as parenthesized source expressions and are validated by the ordinary angle parser after monomorphization.
• A register cannot be returned, stored or selected dynamically.

These rules let callers split one allocation safely:

entangle<2>(q[0..1], q[2..3], PI / 4); // valid
entangle<2>(q[0..1], q[1..2], PI / 4); // NM-CIRCUIT-006

6. Body and expansion

The first contract permits only:

• supported unitary gate statements;
• barrier;
• closed repeat E and for i in A..B compile-time blocks;
• calls to named concrete or generic circuits;
• adjoint, ctrl and pow modifiers described in §7.

measure, measure_all, reset, qreg, sample, collect, expect, train, noise/mitigation directives and runtime if/match/until are forbidden. Generic calls are recursively monomorphized to concrete gate lines. Recursion and an expansion depth above eight fail closed.

Loops are exact: a generic circuit never inherits the Playground's historical warning-and-cap behavior. A body that would exceed 32 loop iterations or 4,096 expanded gates is rejected before partial execution.

7. Modifiers

Modifiers use the shared NMQuantumModifier AST:

adjoint qft<4>(q);
ctrl(q[0]) @ block<2>(q[1..2]);
pow(R) @ layer<N>(q, theta);

• adjoint reverses the fully monomorphized unitary and applies the frozen gate inverse table.
• ctrl accepts one or two explicit control qubits. Controls must be disjoint from every target and every expanded gate must have a supported controlled counterpart. Otherwise it fails closed.
• pow requires a positive compile-time integer. Its immediate expansion is limited to 1,024 gates and the complete instantiation to 4,096 gates.
• Global phase under ctrl is relative phase, matching NM-RFC-0010.

No text-only modifier marker is considered authoritative. The compiler records the parsed modifier node and the concrete expansion in the instantiation carrier.

8. Exact-version Fourier façade

The source import is exact:

use package.algorithms.fourier@0.5;

It exports concrete immutable circuits qft1 through qft5 and iqft1 through iqft5. The source spellings qft<N> and iqft<N> are compiler-known façades only while this exact package is imported. The specialization table is:

The range is the current product ceiling, not a property of the generic type. The package freezes ordered H, CP and final SWAP gates. Every iqftN is the checked exact adjoint of qftN. Package source, matrix fixtures, gate/depth budgets and Core/token byte parity are acceptance evidence.

9. Grover boundary

Bounded generic Grover remains the PhaseOracle<N> algorithm from NM-RFC-0010 and imports package.algorithms.grover_primitives@0.2. This RFC neither widens its N=2..5 ready range nor changes oracle verification. Algorithm Pack 0.5 may present QFT, IQFT and Grover together, but their type contracts and feature flags stay separate.

10. Typed carrier

The program metadata is closed and contains:

• declaration names, const parameters, ordered register/scalar parameters and typed modifier/body nodes;
• each instantiation's concrete const arguments, exact register bindings, scalar arguments, expanded gate count and source map;
• exact-version façade selections (package, façade, N, export);
• no raw source text.

The carrier is revalidated before printing, strict sidecar export/import or target lowering. Missing or tampered metadata never triggers guessed source reconstruction.

11. Diagnostics

Diagnostics are reported at the declaration or call site and include an action that does not suggest raising runtime limits.

12. Compatibility and rollout

1. Freeze flag-off parity for every accepted stable circuit fixture.
2. Land the closed AST/carrier and validator without claiming execution.
3. Add Core and independent token frontend monomorphization parity.
4. Add CLI, Worker, Playground, LSP and VS Code explicit negotiation.
5. Publish the exact-version Fourier package and permanent package fixtures.
6. Add QFT/IQFT/Grover parameter scenarios to the main Algorithm Gallery with generated Playground links and honest ready ranges.
7. Close fuzz, maximum-carrier performance, Windows/Linux Node 22, critical browser, accessibility and named language/runtime/product review evidence.

The RFC remains proposed and the capability remains experimental until the full matrix is reviewed. Creating this document is not approval, and a local green test run is not promotion evidence.

13. Acceptance criteria

• Feature flag off preserves stable source behavior byte-for-byte.
• Core and token frontends produce identical concrete statements and carriers.
• Two disjoint views work; one overlapping view fails with NM-CIRCUIT-006.
• All malformed const, width, arity, recursion, loop, modifier and package cases fail with stable diagnostics.
• qft<N> followed by iqft<N> returns every basis state exactly for N=1..5 within numeric tolerance.
• The package reader retains exact source/gate ordering fixtures.
• Strict QASM3 preserves the typed carrier; unsupported exporters fail closed.
• Main Gallery generates compiler-validated scenarios rather than hand-written result claims, supports EN/TR and 360 px, and opens the exact source in Playground with the required flag.
• The product copy states N=1..5, statevector, experimental and no ceiling increase.

14. Revision history

• Revision 1 (2026-08-09): opens the proposed generalized circuit signature contract, freezes exact/disjoint register views, bounded shared modifiers, the exact-version Fourier façade and the separate NM-RFC-0010 Grover boundary. No approval or implementation claim is made.