Topazdocs
Build & Delivery

Toolchain Status

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

Topaz 5.11.0 is the current public product. Its current language mode is topaz-5.11.

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.

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. 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.