Topazdocs
Build & Delivery

Toolchain Status

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

Topaz 5.20.1 is the current product. The current language mode is topaz-5.20.

The source of 5.20.1 is public at github.com/studiohaze/topaz. Official releases are published on topaz.ooo and npm.

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

Topaz uses Rust Stage 0 as the default for every compiler-bearing command. The installed Stage 2 self compiler remains available when explicitly selected with --compiler self on its admitted current-mode 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

An omitted selection means that when --compiler is absent, Topaz runs Rust Stage 0 by default. Explicit self specifies --compiler self to invoke the installed Stage 2 self compiler on its admitted current-mode routes. Execution proceeds under the chosen compiler, with no automatic retry or silent fallback. The explicit self selection covers parse, dump-ast, check, current profiles, export reports, run, test, bench, locked packages, compiler observe, checked Rust and Python emit, native and Web-family builds, Web/service dev, formatting, LSP, and package documentation. One LSP process retains one compiler choice; restart the editor session after changing 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 occur 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 calculated fresh for each request and are never reused as prepared compiler state. This preparation remains within 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

In the installed product, package checks, tests, builds, and source-free runs use the Rust Stage 0 default. Explicit self remains separately selectable by passing --compiler self on admitted current-mode routes. Rebuilding a managed output with Rust and self replaces compiler provenance atomically.

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. Broader 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. An explicit self selection can then build and run a new source-free native product.

The exact npm installation carries both compiler choices in one executable and does not require 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 manages a 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 admitted command routes.

Self-hosted 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.
  • The HTTP service creates a managed native HTTP/1.1 process with fixed 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 Lispex request with declared resource limits using the 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 check and interpreter execution without installing the native CLI.

Run the 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. Evaluator and profile selectors, sidecar downloads, callbacks, imports, and fallback are absent. The report records Topaz execution and admission; the application artifact API produces portable Lispex-format cores. See Lispex Evaluator and LIT for the complete distinction.

Topaz exposes the locked std.lispex complete-current-profile API through the interpreter and all five native release targets. Follow Run Lispex Rules for the manifest, lock, build, artifact, and replay workflow. generated-python, raw-web, worker-web, managed-web, http-service, no-capability, and mcp-empty-component-set routes reject before artifact output or execution. Fallback is absent.

Inspect compiler observations

Capture an installed compiler observation

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 the observation bundle

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.

Understand the comparison boundary

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 diagnostic cases. For the declared comparison product, the linked and interpreted Stage 1 paths produce identical generated Rust, while Stage 0 and Stage 1 generated Rust differ. The compiled Stage 1 product prints exactly 42. A wrong producer identity or damaged managed Stage 1 product is rejected instead of retrying the target through Stage 0.

Compare without a repository clone

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.

Choose a comparison boundary

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 canonical JSON record within the documented size limit 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.

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 declines a program before writing an artifact when it uses the fixed-Huffman DEFLATE, fixed zlib, or RS(255,223) helpers, the toFloat and toIntRadix conversions, the Regex methods find and findAll, or any Date, BigInt, or Decimal member. The decline reports TPZ6PY0001 with the source position, and the Python Backend page lists the exact members. Consult the backend pages before choosing a target for binary media, calendar dates, or arbitrary-precision numbers.

The HTTP product implements managed HTTP/1.1 with fixed listener, request, queue, deadline, log, and shutdown controls. TLS, HTTP/2, WebSocket, outgoing network access, ambient environment authority, shared mutable Topaz state, and a general Web framework are outside this product.

The Web Application host uses declared browser capabilities. Raw Web and Worker products require an existing JavaScript host. Playground runs source in the browser; validate deployment with the generated product outside the source workspace.

Concurrent task ordering is unspecified. Join tasks before ordered output.

The installed evaluator handles topaz lispex embed, while Topaz target selection is separate and --target lispex rejects before artifact output. LIT is the Lispex test and integration surface from one source lineage and remains separate from the installed evaluator and output backends.

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.