The current manual describes the Topaz language that users should write today. Its examples use the same grammar accepted by the checker, and the command-line tools report unsupported forms as errors instead of guessing.
Language definition
The language reference defines syntax, types, evaluation order, errors, modules, and the standard library. The covers metadata on each page helps maintainers keep that material synchronized, but readers do not need private design documents to understand the language.
Checking a program
Use topaz check for static validation and topaz run to execute a program directly. When you need a deployable artifact, build the Rust, Python, or web target documented for that environment.
Compatibility across outputs
Supported output targets are tested against direct execution for the language features they accept. A target that cannot preserve a feature must reject it clearly. The Toolchain Status page lists the currently available targets and their practical limits.
Lispex integration evidence
The repository also uses a Lispex interpreter written in Topaz as a demanding cross-target program. This is integration evidence, not an additional Topaz product or language release.
Construction checks
| Implementation boundary | Execution and replay evidence | Rejected checker mutations |
|---|---|---|
| Lexical, numeric, and tail machine; 100,000-step self, mutual, and apply recursion with maximum continuation depths 3, 3, and 4 | 66 cases, 396 executions, 198 replay checks, 66 three-host agreements | 17 classes |
| Unified control transfer | 26 cases, 156 executions, 78 replay checks, 26 three-host agreements | 23 classes |
| Versioned primitive floor and common guest-call dispatcher | 40 cases, 240 executions, 120 replay checks, 40 three-host agreements, 200 profile comparisons | 32 classes |
| Independent raw-byte UTF-8 reader and normalizer with a bounded explicit stack | 64 cases, 384 executions, 192 replay checks, 64 three-host agreements, 192 projection validations, 320 profile comparisons | 66 classes: 46 result and 20 projection |
| Source-only backend route with no kernel producer or host apply/eval/control fallback | 144 cases, 864 executions, 432 replay checks, 144 three-host agreements, 720 profile comparisons | 49 classes |
These are staged construction surfaces; their case counts are not added together into a larger language-conformance denominator.
| Measured surface | Exact inventory | Recorded result |
|---|---|---|
| Full three-host LIT construction | 144 cases across the interpreter, generated Rust, and generated Python | 864 fresh executions, 432 replay checks, 144 complete three-host byte agreements, and zero host fallback |
| LIT four-host integration record | One canonical source across the interpreter, generated Rust, generated Python, and Web | Internal evidence records its bounded four-host check surface |
| Primitive capability boundary | 205 rows | 84 supported, including 31 deterministic delegations and 53 machine implementations; 121 fail loudly; six of 18 guest-calling rows are supported |
| Lispex v1.5 joint observation | Rust, LIL, and one installed LIT route across 144 cases | 432 executions; 59 all-family agreements; 253 pair agreements and 179 pair divergences; pairs Rust/LIL 61/83, Rust/LIT 65/79, and LIL/LIT 127/17 |
The four Topaz routes are host variants of one canonical LIT source, not independent implementations, and this documentation makes no source-independence claim for LIT. The joint observation is bounded to its declared cases and preserves measured divergences; it does not establish whole-language semantic equivalence. The integration record remains internal evidence and is not a public Topaz backend.
Version boundaries
The manual follows the latest language policy. The version number appears where installation, packages, generated artifacts, or migration depend on it. Long-form guides remain available in Classic.
Common checks
topaz check main.tpz
topaz run main.tpz
topaz build main.tpz --out-dir build