Topazdocs
Build & Delivery

Toolchain Status

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

This page describes Topaz v5.17. Before treating it as current, compare /version.json with version 5.17.

Topaz 5.17.0 is the current product. Its current language mode is topaz-5.17.

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.

Choose the compiler

The installed Stage 2 compiler is the default for supported current-mode routes. Rust Stage 0 remains available explicitly for comparison, recovery, older language modes, and declared compatibility routes:

BASH
topaz check app/main.tpz
topaz check app/main.tpz --compiler self
topaz test --root app --locked --compiler self
topaz emit app/main.tpz --compiler self
topaz emit app/main.tpz --target python --compiler self --out-dir python-source
topaz build app/main.tpz --compiler self --out-dir app-product
topaz build app/main.tpz --target web --compiler self --out-dir web-product
topaz dev --root web-app --locked --compiler self
topaz fmt app/main.tpz --compiler self
topaz lsp --compiler self
topaz doc --root app --locked --compiler self --out-dir api-docs
topaz compiler observe app/main.tpz --compiler self --out-dir observation
topaz check app/main.tpz --compiler rust
topaz compiler status --json

Omitting --compiler selects self on supported current-mode routes. That route uses the installed self-hosted compiler image and never retries through Rust when it fails. parse, dump-ast, check, every current profile, export reports, run, test, bench, locked packages, compiler observe, checked boxed Rust emit, native build, Python source and deployment products, raw Web, worker, Web application, HTTP service, admitted Web/service dev, formatting, LSP, and package documentation routes use that selection. The self formatter and documentation route consume the selected syntax and semantic product, then share the deterministic printer and presentation schema with the Rust route. The self LSP builds and caches that validated product for the open document set and answers every declared method without invoking a Rust compiler phase. One LSP process keeps one compiler choice; restart the editor session after changing it. Self target adapters consume the same validated facts; their artifacts record topaz-stage2 provenance and never invoke the Rust target front end. Older language modes, unchecked compilation, native specialization, and the listed Rust-only commands resolve an omitted selector to Rust compatibility before compiler work. An unsupported explicit self selection stops before source or output work and prints the explicit Rust recovery command without running it.

Add --verbose to a compiler-bearing command to print whether the resolved selection was explicit, the current default, or compatibility.

Compiler intent is preserved until the effective language mode is known. For a package command, the CLI reads and validates only the root topaz.toml before choosing the compiler; dependency resolution, lock verification, source loading, caches, and output work remain later. A package that selects an older language mode uses Rust when the selector is omitted or explicitly rust, while explicit self fails before that later work. This ordering keeps current-mode default selection and declared Rust compatibility as separate, observable decisions.

The installed process validates and decodes the exact immutable self-hosted compiler image once, then shares that prepared program across self compiler and LSP worker threads. Its cache key includes the image, source set, schema, runtime template, and toolchain identities. A mismatch stops self work. Target source, diagnostics, generated source, and managed outputs are still computed for each request and are never reused as prepared compiler state. This preparation remains within the documented cold-start, LSP, and memory limits.

compiler status --json is the machine-readable source of truth for the installed producer, program-image and source-set identities, supported routes, declines, each route's omitted choice, default, compatibility and recovery choices, and no-fallback policy. Managed artifacts also record whether the selection was explicit, the current default, or compatibility.

Installed recovery boundary

The npm-installed product uses the same default for package checks, selected tests, managed Python packaging, and source-free execution. Rebuilding one managed output with Rust and self replaces compiler provenance atomically rather than reusing a foreign result.

The same installed default completes the two-module learning application through check, its selected test, native release packaging, source removal, and execution. The field ledger closes only resolved product problems; wider compiler and integration campaigns remain release-candidate checks.

The installed Stage 1 and Stage 2 paths can each produce a fresh validated observation from new source, after which the default self path builds and runs a new source-free native product. Rust Stage 0 recovery remains a separate, pinned reconstruction path rather than the installed default.

The exact npm installation carries both compiler choices in one executable and does not need a repository checkout. Products built with either choice run after their Topaz source is removed. If the installed self-hosted compiler image is missing or damaged, a self request fails without retrying or reusing a Rust result; rerun the original command with --compiler rust only when you explicitly choose recovery. Rust remains usable independently, and the published Stage 0 recovery kit is a separate offline reconstruction path rather than an automatic fallback.

The installed self compiler now owns one versioned complete current-mode compilation product: ordered modules, tokens and AST, resolution and exports, typed profile diagnostics, lowering and runtime requirements, generated Rust, and exact invocation/result provenance. The host adapter validates and decodes those facts; it does not recreate a missing compiler decision. Shared package and runtime hosts consume the same validated product for the admitted command routes.

Self Rust emit retains the fixed-point IR table and adds only the ordinary application host facade. A target-only shared runtime executes that table; it contains no compiler image and cannot run a Rust parser, resolver, checker, lowerer, or emitter. Native artifact manifests record the selected compiler, producer, compiler and target source sets, compilation product, generated-source digest, and targetCompilerFallback: false.

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.
  • topaz lispex embed run evaluates one bounded Lispex request with the exact evaluator built into the installed binary. topaz lispex embed info --json reports its component, profile, contract, runtime, and no-fallback identity.
  • The browser Playground provides bounded check and interpreter execution without installing the native CLI.

Run the bounded Lispex evaluator

The product takes four named regular files or paths. The output directory must not exist:

BASH
topaz lispex embed run \
  --source rule.lspx \
  --input value.lpxvalue \
  --limits limits.json \
  --output lispex-result

A complete evaluation writes result.lpxvalue and report.json. Deterministic semantic failure or limit exhaustion writes only report.json. Request refusal, contract failure, or engine failure leaves no output directory. Provisional result and transcript bytes never cross the boundary.

The evaluator, profile, runtime policy, and admission are fixed by the installed product. There is no evaluator or profile selector, sidecar download, callback, import, or fallback. The report is a Topaz product record, not a portable Lispex provider receipt. See Lispex Evaluator and LIT for the complete distinction.

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. That fact describes this observation path; it does not identify the implementation language of other compiler stages.

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 its bootstrap host. 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 follow the installed route-aware default.

The installed product also exposes 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

The Stage 1 Preview 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. Rust Stage 0 and the Stage 1 Preview agree on the declared multi-module and rejected cases. Repeated Stage 1 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 Stage 1 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 --compiler rust on an ordinary check or build command 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 remains an explicit producer Preview and is separate from the ordinary route default.

A fresh Stage 1 run generates compiler source, and the pinned build turns those exact bytes into a separate installed Stage 2 compiler image. The two generations keep independent manifests and embedded images even when their canonical compiler source is content-identical. This build boundary does not execute Stage 2 or claim a fixed point by itself.

Run the independently embedded Stage 2 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 another compiler producer or the Rust target front end.

The fixed-point check keeps two claims separate. It compares the decoded compiler-program semantics and canonical observations from two successive self-hosted generations for one normal and one diagnostic input. It then compares their newly generated compiler source as raw bytes with no normalization. Both layers are equal. 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. The installed support contract separately governs the ordinary Stage 2 default; neither result proves every possible compiler behavior correct.

Bounded failure canaries alter one semantic projection, generated-source identity, Stage 2 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 another compiler producer 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 compiler-generation 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 it does not make the Rust recovery chain self-hosted.

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.

The installed bounded evaluator is not a Lispex backend or --target lispex, and it does not establish whole-language equivalence. LIT remains a separate same-lineage dogfood and integration surface.

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.