#Staging and Code Generation
Staging lets ordinary Rig code compute values, construct types, and generate expressions during compilation. The distinction is in types: Int describes a runtime integer, while Int_1 describes an integer used one stage earlier.
#Values at Different Stages
Stage 0 is the running program. Higher stages execute during compilation, from higher to lower:
Stage 1 computes base. const turns that value into checked code for an Int at Stage 0; inline inserts it into answer. The resulting exported function returns 42 without reading a Stage 1 binding at runtime.
This example is a library Component, not a WASI command: build it to export answer, or use it from another source file. Getting Started shows a complete command with output.
A stage suffix describes when values exist, not an optimization hint. A Stage 0 function cannot directly read an Int_1. Cross-stage persistence is explicit, even when the compiler could recognize a constant.
Function types follow the same rule: (Fn_1 Int_1 Int_1) describes a Stage 1 function from integer to integer. Every parameter and result belongs to that function's stage.
#Types as Values
Int is itself a value of type Type_1: a Stage 1 description of Stage 0 integers. Type constructors therefore fit naturally into staged functions:
Pair is an ordinary function. Evaluating (Pair Int) produces a Record type before its value is checked. Generic type construction does not require a separate type-parameter syntax.
Types retain their structural or nominal identity when passed this way; they are not converted to source text. A type describing Stage 1 values, such as Int_1, is a Stage 2 value of type Type_2.
#Syntax and Checked Code
Syntax_1 is a bound expression fragment constructed at Stage 1. Its body has lexical meaning but has not yet been checked against a payload type. (Code_1 Int) is completed code for a Stage 0 Int expression.
check makes that guarantee explicit:
Checking compiles the fragment before returning Code. It may execute that fragment's compile-time work, but it does not run the residual Stage 0 addition. Failed checking reports a compiler diagnostic; it does not produce a runtime error value or an unchecked substitute for Code.
When the expected Code type is already known, code is the concise form:
code obtains its payload type from that expectation. It does not infer one or try multiple types to resolve an overload. Use check or an annotated intermediate value when the context is not unique.
uncheck turns Code back into Syntax while preserving its resolved meaning and completed staged work. Rechecking does not repeat work already eliminated from that Code.
#Captures and Generated Functions
A quotation uses names from its definition site, not whatever names happen to be available where it is checked or inserted. This supports generators whose type inputs are ordinary captured values:
splice evaluates (make_id Int) at Stage 1, checks the resulting Syntax against the declared (Fn Int Int) type, and inserts the completed function. It uses the captured type to establish the generated parameter type. Calling identity runs the finished Stage 0 function.
Use splice when the surrounding context supplies the expected type. The explicit equivalent here is (inline (check (Fn Int Int) (make_id Int))). Use inline directly when you already have checked Code.
Construction-stage local values are snapshots; captured references retain their ordinary aliasing. Static references preserve links to their defining owners. Unlike an ordinary Fn closure, a Syntax value may have a dynamically sized capture environment. This is explicit quotation storage, not a way to enlarge Fn's inline capture budget.
A quotation cannot capture a surrounding runtime local before that local exists. Bind runtime inputs as parameters of the generated function. To embed an available compile-time data value, use inline with const; merely naming the higher-stage value inside runtime code does not persist it.
const supports reifiable data, including scalars and composites of supported values. It is not a universal serializer: live reference identities, function closures, and Syntax environments cannot be persisted this way. Syntax itself is a bound value, not a portable text representation.
#Execution Order
Higher stages run first. A runtime conditional cannot suppress Stage 1 work merely because its runtime branch will not be taken. Within the stage that is executing, ordinary control flow, source order, and initialization rules still apply.
Before a Syntax_N is constructed, work above Stage N in its body has already completed. Work at N waits for checking, and lower-stage work remains residual. A later check cannot reopen a completed higher stage.
Repeated checks repeat remaining fragment-owned compile-time work. They do not rerun completed external initializers or annotations, and inline does not rebind names at its insertion site. Compile-time effects are real effects: failed compilation cannot undo file writes or other external actions.
Module-level initializers remain non-suspending at every stage. Ordinary staged computation outside those initializers can use supported asynchronous host interfaces. Compile-time authority is controlled independently from runtime authority, and access to time, randomness, or external data can make compilation results vary.
#Inspecting Reduction
Use the CLI to inspect what remains at a selected stage:
rig reduce main.rig --stage 0
The output is an inspection view, not a recompilable residual-source artifact. Running reduction again repeats compile-time effects. Use it to understand stage flow rather than as a serialization format for generated programs.