Topazdocs
Build & Delivery

Toolchain Status

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

Topaz 5.13.0 is the current product checkpoint. Its current language mode is topaz-5.13.

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.

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.