Topazdocs
Build & Delivery

Toolchain Status

The current Topaz product identity, available delivery products, and decision-relevant limits.

Topaz 5.14.0 is the current product. Its current language mode is topaz-5.14.

Confirm an installation with:

BASH
topaz version --verbose

The command reports the compiler, language mode, runtime, and Rust backend identity. Include its complete output when reporting an installation problem.

Available product paths

  • The CLI formats, checks, tests, runs, emits, and builds files or packages.
  • Native build creates a platform-specific executable.
  • Python build creates program.py with topaz_py_rt.py and requires Python 3.11 or newer at runtime.
  • Raw Web and Web Worker create WASM packages for an existing JavaScript host.
  • Web Application creates a complete managed static browser product.
  • Bounded HTTP service creates a managed native HTTP/1.1 process with finite listener, request, queue, deadline, log, and shutdown settings.
  • Package commands use manifests, locks, path dependencies, and verified local vendored dependencies.
  • The browser Playground provides bounded check and interpreter execution without installing the native CLI.

Inspect compiler observations

The installed CLI can capture the current checked compiler pipeline through generated Rust source as one canonical managed bundle:

BASH
topaz compiler observe --root my-app --locked --out-dir compiler-observation
topaz compiler validate compiler-observation

Put the output outside my-app; otherwise a later observation can see its own managed directory while collecting package-directory facts. The bundle contains exact source bytes plus source-set, raw and layout token, AST, resolution, structured type, call, closure-capture, source-free lowering, runtime-leaf, generated-Rust, diagnostic, request, response, and provenance records. Treat it with the same confidentiality as the source package.

validate is read-only. It checks canonical encoding, schemas, ordering, cross-references, completeness, sizes, and digests without recompiling or reading the original source tree. Provenance identifies the producer as Rust Stage 0; an observation is not a claim that a compiler stage is already written in Topaz.

The explicit preview route runs the current Topaz-authored lexer, layout implementation, parser, logical import closure, name resolver, and static checker, hosted by Rust Stage 0:

BASH
topaz compiler preview --root my-app --locked --out-dir typed-preview
topaz compiler validate typed-preview

Its bundle ends at the typed phase and records engine: topaz-front-end-preview, producer/result stage 0/0, and Rust Stage 0 as the default engine. The Topaz front end covers the current grammar, canonical AST, logical closure over package, mounted dependency, and standard modules, exact scopes, declarations, references and exports, static types, calls, captures, and structured diagnostics. Source facts, AST and typed nodes, depth, and shell exchange stay bounded. It does not lower, emit, build, or run the target, and it is not a Stage 1 or self-hosted compiler claim. A preview failure stops without retrying target front-end work through Rust; ordinary compiler commands continue to use Rust Stage 0.

The installed product also exposes that generated C1 as an explicit Stage 1 Compiler Preview:

BASH
topaz compiler preview main.tpz --producer stage1 --terminal rust-source --out-dir stage1-observation
topaz compiler validate stage1-observation

C1 consumes the versioned exchange and source-free private IR produced by the Topaz-authored lowering and Rust emitter. It compiles an ordinary package without linking or retrying a Rust target parser, resolver, checker, lowerer, emitter, or interpreter. The managed bundle records producer/result stage 1/1, the compiler source-set identity, generated-source identity, runtime template, and targetCompilerFallback: false. It makes no Stage 2 fixed-point claim.

The comparison boundary keeps semantic observations, diagnostics, generated source, generated-product behavior, and provenance separate. Stage 0 and C1 agree on the declared multi-module and rejected cases. Repeated C1 emission is byte-stable; Stage 0 and Stage 1 Rust are expected to differ and are recorded as separately deterministic producer outputs, not as a failed byte-equality claim. A wrong producer identity or damaged managed C1 product is rejected instead of retrying the target through Stage 0.

The installed package can perform the exact comparison without a repository clone:

BASH
topaz compiler observe main.tpz --terminal rust-source --out-dir rust-observation
topaz compiler preview main.tpz --producer stage1 --terminal rust-source --out-dir stage1-observation
topaz compiler validate rust-observation
topaz compiler validate stage1-observation
topaz compiler compare --layer semantic rust-observation stage1-observation

After the two managed observations are written, validation and comparison no longer read the original target source. If Stage 1 declines or faults, it fails without writing a replacement observation and prints the separate compiler observe recovery command; it never runs that command implicitly. Use ordinary observe, check, or build commands when you explicitly want Rust Stage 0.

Compiler-generated Rust keeps producer and build provenance outside its canonical source bytes. That separation lets later compiler stages compare generated source byte for byte without erasing who produced it; the installed Stage 1 command and Rust Stage 0 default remain unchanged.

A fresh C1 run now emits R1 and the pinned build binds those exact bytes into a separate C2 program image. C1 and C2 have independent manifests and embedded images even when their canonical compiler source is content-identical. This build boundary does not execute C2 or claim a fixed point by itself.

Run the independently embedded C2 image explicitly with:

BASH
topaz compiler preview app/main.tpz \
  --producer stage2 \
  --terminal rust-source \
  --out-dir stage2-observation

Use --self-source without an entry path to compile the compiler source set embedded in the installed product. The command writes a Stage 2 product manifest and never retries C1 or the Rust target front end.

The fixed-point court keeps two claims separate. It compares the decoded C1 and C2 compiler-program semantics plus canonical observations for one normal and one diagnostic input, then compares fresh R1/R2 as raw bytes with no normalization. Both layers are equal. C1/C2 image and invocation provenance is expected to differ, and native executable bytes are not part of this claim. The result proves that the explicit Preview compiler has stabilized at these boundaries; it does not make Stage 2 the default or prove every possible compiler behavior correct.

Bounded failure canaries alter one semantic projection, generated-source identity, C2 provenance, producer, seed, or runtime boundary at a time. Missing source facts and a language mode outside the current Preview boundary also stop before a completed output directory is committed. None of these failures retries C1 or the Rust target front end.

The exact local npm package runs ordinary Stage 2 and the self-source form after the target source and repository paths are absent. The self-source bundle contains stage2-fixed-point.json; its semantic and generated-source statuses are pass, while native binary reproducibility remains not-run. The offline Stage 0 recovery source includes the C1/C2 manifests, fixed-point record, schemas, runtime, and pinned toolchain metadata. Reconstructed Stage 0 remains a separate explicit engine rather than an automatic fallback.

Compare two complete observations by selecting the boundary that answers your question:

BASH
topaz compiler compare --layer semantic observation-a observation-b
topaz compiler compare --layer generated-source observation-a observation-b
topaz compiler compare --layer provenance observation-a observation-b
topaz compiler compare --layer native-binary program-a program-b

The command prints one bounded canonical JSON record and returns a failing exit status when that layer differs. Semantic comparison stops at the first different compiler phase; generated source and provenance remain independent, so a producer identity change does not by itself become a language mismatch.

Recover the Rust Stage 0 seed

A qualifying self-hosting release carries a separate recovery manifest and deterministic source archive alongside the five normal platform binaries. The archive fixes the Rust compiler source, lockfile, vendored dependencies and licenses, runtime templates, protocol schemas, compiler workload, and reconstruction tools. It also records the embedded Topaz-authored compiler files as an independently verified source set. Rebuilding it twice produces identical archive bytes.

The recovery set does not bundle the Rust toolchain. Reconstruction requires the pinned Rust toolchain to be installed already and then builds offline from the archived vendor directory. This is an independent recovery and provenance route, not the normal installer path and not a claim that a compiler stage is already written in Topaz.

Check bootstrap-safe compiler source

The Bootstrap Profile is a machine-readable restriction of the current language for compiler-kernel source. It adds no syntax or dialect. It accepts a locked deterministic package only when its resolved operations avoid ambient host capabilities, extern modules, floating point, concurrency, resources, testing APIs, and other host-dependent leaves:

BASH
topaz check --profile bootstrap --locked --root compiler-kernel

Human diagnostics include a stable bootstrap/* rule. With --format json, stderr contains machine-readable profile diagnostics and stdout contains one summary. A local value is judged by its resolved identity, so merely naming a user function print does not make it a host operation; renaming or aliasing a forbidden host operation does not hide it.

Decision-relevant limits

All targets share parsing, module resolution, and static checking, but host-dependent operations are not universally available. A target that cannot preserve an operation must reject it before writing a product. In particular, generated Python does not support the current fixed-Huffman DEFLATE, fixed zlib, or RS(255,223) helpers; their generation fails explicitly. Consult the backend pages before choosing a target for binary-media work.

The HTTP product is deliberately bounded. It does not add TLS, HTTP/2, WebSocket, outgoing network access, ambient environment authority, shared mutable Topaz state, or a general Web framework.

The Web Application host exposes only declared browser capabilities. Raw Web and Worker products instead require an existing JavaScript host. Playground execution is a source experiment, not deployment evidence.

Concurrent task ordering is unspecified. Programs must not depend on one particular interleaving.

LIT remains a bounded Lispex dogfood and integration surface. It is not a shipped Topaz backend and does not establish whole-language equivalence.

Start with fmt --check, check, and test. Use run for a command application or dev for a Web Application or HTTP service. Build only the target you intend to deliver and copy its complete managed directory.