Callback Wrapping in Fault-Tolerant Quantum Compilation

• Callback Wrapping is a mechanism in quantum compilers that adapts measurement stacks to ensure callbacks receive the logical bits they expect for fault-tolerant execution.
• It employs compiler pass wrappers that decode expanded physical measurements and recompile dynamically generated kernels, maintaining semantic correctness.
• By isolating classical control as opaque callbacks, it enables automated, compositional compilation across multiple ISA and error correction transformations without manual rewriting.

Searching arXiv for the cited paper to ground the response. Callback wrapping is the central mechanism in qstack, a compiler framework for fault-tolerant quantum programs in which classical logic is exposed to the compiler only through opaque callbacks. In this setting, every quantum kernel ends with a measurement whose outcome is passed to a classical callback routine, and compilation may transform a kernel by changing its instruction set or by inserting quantum-error-correction layers. Because such transformations alter the structure of instructions and measurements, callback wrapping adapts each original callback so that it still receives exactly the logical bit or bits it was written to handle, while ensuring that any kernel returned dynamically by the callback is itself sent through the same compilation pipeline. This mechanism is presented as the basis for compositional compilation across ISA translation and quantum error correction, including concatenation of error-correcting codes, without manual callback rewriting (Paz et al., 15 May 2026).

1. Role in fault-tolerant quantum compilation

Compiling a quantum program for fault-tolerant execution requires transformation across multiple abstraction layers, from high-level logical operations to error-corrected encodings and then to hardware-native instructions (Paz et al., 15 May 2026). A principal difficulty is that quantum error correction converts a purely quantum program into a hybrid quantum-classical program: syndrome measurements produce classical information, and that information drives quantum corrections at runtime. qstack addresses this by retaining a purely quantum intermediate representation and treating all classical logic as external, opaque callbacks.

Within this model, callback wrapping serves two functions. First, it adapts the callback interface after compilation has changed the measurement structure. Second, it preserves the invariant that dynamically generated kernels are compiled by the same sequence of passes as the original program. The motivating failure mode is explicit: if a callback was written to pop one bit from the measurement stack, then after QEC injection it may encounter three physical bits instead of one logical bit; if left unmodified, it would pop only one bit, misinterpret the data, and break program semantics. Callback wrapping restores the stack invariants automatically, so that every callback still pops exactly the number of logical bits it expects (Paz et al., 15 May 2026).

The mechanism is therefore not merely a convenience layer around classical control. It is the means by which qstack reconciles semantic preservation with transformations that expand a logical gate into many physical gates and measurements, or replace a single logical measurement by multiple physical measurements.

2. Intermediate representation and callback semantics

The qstack intermediate representation is described as a minimal grammar in which a program is a kernel, a kernel consists of qubit allocation, instructions, and an optional callback, and instructions are either gates or nested kernels (Paz et al., 15 May 2026). The callback identifier denotes an opaque classical function. No classical expressions or control-flow constructs appear in the IR itself.

The callback interface is given by the type

$$f_{\mathrm{cb}} : \mathrm{bit}^* \to (\mathrm{kernel\ option} \times \mathrm{bit}^*).$$

The callback consumes the current measurement stack and returns an updated stack together with either None, indicating termination of the kernel, or Some kernel, indicating a subsequent kernel to invoke (Paz et al., 15 May 2026).

Three aspects of the typing discipline are fundamental. A gate applied to $k$ qubits produces no new classical bits. A kernel always produces exactly one classical bit through its final measurement before invoking its callback. A callback must handle exactly the number of logical bits intended by the source program. The measurement stack is therefore the sole interface between quantum execution and classical control at the IR boundary.

This design is central to callback wrapping. Since the compiler never reasons about classical control flow internally, adaptation occurs by replacing callback identifiers with wrapped callback identifiers in the callback set associated with the transformed program. The IR remains quantum-only, while the host language carries all classical decoding, decision logic, and dynamic kernel generation.

3. Mechanics of wrapping within a compiler pass

In qstack, a compiler pass is a transformation

$$\mathrm{compile} : (\mathrm{Program}, \mathrm{CallbackSet}) \to (\mathrm{Program}', \mathrm{CallbackSet}').$$

The transformed program is rewritten into a new or unchanged gate set, and the transformed callback set contains wrapped versions of the original callbacks (Paz et al., 15 May 2026).

The wrapping procedure is defined operationally. For each callback $cb$, the compiler constructs a wrapped callback $w_{cb}$ that first applies a pass-specific decode function to the measurement stack, then invokes the original callback on the restored logical stack, and finally compiles any kernel returned by that callback using the same compiler’s compile_kernel routine (Paz et al., 15 May 2026). The pass-level workflow is correspondingly simple: rewrite qubit-operation nodes, recursively rewrite nested kernels, wrap each callback, and return the new kernel together with the wrapped callback set.

The order of operations is significant. Decoding occurs before control is passed back to the original callback, because the callback was written against the logical program interface rather than the physicalized measurement layout introduced by later passes. Recompilation of any returned kernel occurs after the original callback executes, because the callback may dynamically generate a kernel in the source-level representation. Callback wrapping thus ensures that the dynamic control path is not an escape hatch from compilation: any new kernel is fed back through the same pass sequence as the top-level program (Paz et al., 15 May 2026).

In this sense, wrapping is the compiler-side realization of two invariants stated explicitly in the source material: the callback always sees the logical bits it expects, and dynamically generated kernels always traverse the full compilation pipeline.

4. Compositionality and correctness preservation

The key theorem associated with callback wrapping is stated as a compositionality result. Given two compiler passes $C_1$ and $C_2$, with corresponding decode₁, decode₂, compile_kernel₁, and compile_kernel₂, applying $C_1$ and then $C_2$ yields a wrapper chain

$w_2 \circ w_1 \circ cb_{\mathrm{orig}},$

such that runtime decoding occurs in the order decode₂ then decode₁ before the original callback is invoked, while any returned kernel is compiled by compile₁ and then compile₂ (Paz et al., 15 May 2026).

The runtime behavior is described explicitly. After a physical measurement, the outer wrapper decodes the bits introduced by the outer pass; the inner wrapper then decodes the bits introduced by the inner pass; only after these decodings does the original callback execute. If the callback returns a kernel $k$0, that kernel is recompiled inside-out through the same passes before execution. Because each decode routine pops exactly the bits inserted by its own pass, and because wrapper composition is outside-in while recompilation is inside-out, the measurement stack seen by the original callback is identical to that of the source program (Paz et al., 15 May 2026).

This formulation gives callback wrapping its semantic role. It is not just a mechanism for bit remapping; it is the structure that makes compilation compositional across passes that alter both quantum operations and the associated classical interface. The result is presented as correctness preservation under layering of ISA translation and QEC passes, including concatenated codes.

5. Representative examples

The tutorial material provides three concrete examples (Paz et al., 15 May 2026). In the first, a repeat-until-success source kernel allocates two qubits, applies $k$1 and $k$2, and performs measurements whose callbacks either terminate or request a retry by returning a new kernel. The callback repeat_zero pops one bit from the measurement stack and, if that bit is $k$3, returns bell_kernel(); otherwise it returns None. This illustrates the baseline model in which callback logic consumes a logical measurement directly.

In the second example, the same source program is compiled through a bit-flip repetition-3 pass. Each logical qubit becomes three physical qubits, and each logical measurement becomes three physical measurements. The pass defines decode_rep3, which pops three physical bits and pushes back their majority value. The wrapped callbacks w_done and w_repeat_zero first execute decode_rep3, then call the original callbacks, and in the case of w_repeat_zero also compile any returned bell_kernel through the repetition-3 compiler (Paz et al., 15 May 2026). The stated measurement-stack trace shows that when w_done fires, it pops three bits and restores one logical bit, so the original done callback sees exactly the single bit it expects.

In the third example, a Steane-code pass is stacked on top of the repetition-3 bit-flip pass. The composition $k$7 produces a 21-qubit physical encoding per logical qubit, since each logical qubit is encoded in $k$4 physical qubits. The wrapper chain is w_steane → w_rep3 → cb_orig. At runtime, decode_steane runs after each block of seven physical measurements, decode_rep3 then runs on the resulting structure, and only then is the original callback invoked. Any kernel returned by the original callback is first compiled through repetition-3 and then through Steane, restoring the full 21-qubit encoding (Paz et al., 15 May 2026).

These examples illustrate the two recurring effects of callback wrapping: restoration of the logical measurement interface and recursive recompilation of dynamically generated kernels.

6. Advantages, constraints, and comparison with circuit-level approaches

The benefits and limitations of callback wrapping are stated directly in the source material (Paz et al., 15 May 2026). The primary benefit is a uniform IR: a quantum-only abstract syntax tree combined with opaque callbacks, without intermixed classical AST nodes. This supports automatic adaptation, because classical callbacks do not need to be rewritten or inlined at each compilation stage. It also enables free composition for passes that preserve the ISA, with explicit examples including bit-flip plus phase-flip yielding the Shor code, and Steane plus repetition-3 yielding a concatenated code. A further stated benefit is expressive classical logic: callbacks may be arbitrary host-language routines, including an MWPM decoder or a lookup table.

The constraints are equally explicit. The measurement stack must obey a LIFO discipline, and each QEC pass must push its physical bits as a contiguous block on top of the stack. There is runtime overhead from the additional function call and stack manipulation introduced by each wrapper, although the text states that this overhead is negligible compared to quantum gate execution. There are also classical-side constraints: if one wishes to verify or bound callback runtime, those analyses must be added on the host-language side rather than inside the IR (Paz et al., 15 May 2026).

The comparison provided with prior approaches is framed in terms of Qiskit and OpenQASM 3. There, one typically inlines decoders as circuit-level classical primitives and manually remaps registers at each stage, which requires writing a custom pass that recurses into all control-flow constructs. qstack instead moves decoder logic into opaque callbacks, thereby offering arbitrary external code and shifting classical optimization to the classical compiler (Paz et al., 15 May 2026). The contrast is methodological: circuit-level integration of classical logic versus a quantum-only IR with an opaque callback boundary.

7. Position within qstack’s end-to-end pipeline

Callback wrapping is presented as one component of qstack’s broader goal of end-to-end compilation from a high-level gate set through Clifford gates to trapped-ion native operations, with support for bit-flip and phase-flip repetition codes, the Steane code, and the Shor code obtained by composing two repetition passes (Paz et al., 15 May 2026). Within that broader compiler architecture, callback wrapping is the mechanism that makes these transformations composable at the interface between quantum execution and classical feedback.

The key insights summarized in the source are tightly aligned with this role. Callback wrapping abstracts away remapping of measurement bits and recompilation of dynamically generated kernels. It relies on a strictly quantum IR with opaque callbacks, so the compiler does not reason about classical control flow. Each compiler pass contributes two ingredients: handlers to rewrite gates or kernels, and a decode function that restores logical measurement bits. Wrapper layering is compositional by construction, since pass $k$5 wraps the callbacks already transformed by pass $k$6 (Paz et al., 15 May 2026).

A plausible implication is that qstack’s notion of compositional compilation depends as much on disciplined management of the classical boundary as on quantum gate rewriting. In the formulation given, callback wrapping is the device that turns hybrid quantum-classical feedback from a source of ad hoc pass-specific engineering into a systematic compilation interface.