compiler preview

Arguments and rejection

Use topaz compiler preview [entry] --out-dir <dir>. Accept --locked, --self-source, --root <dir>, --terminal ast, --terminal typed or --terminal rust-source, --producer stage1 or --producer stage2, and --language-version <version>.

The default terminal is typed. Without a producer allow only ast or typed and use the linked compiler preview. AST preview requires one entry file. Typed preview allows an entry or package mode.

An explicit producer requires --terminal rust-source. --self-source requires --producer stage2 --terminal rust-source, accepts no entry and conflicts with --locked. It selects the embedded compiler source set rather than a caller package.

Require one output directory outside the selected source root. Reject --compiler, --verbose, compiler budget flags, format selectors, repeated options, equals forms, missing values, unsupported terminals and producers and every unlisted option. Reject --locked for an explicit standalone entry.

Output

Write a human completion line identifying the output directory to standard output after publishing a valid preview. Write producer failures and recovery guidance to standard error. No human banner is written before validation succeeds.

The output is a topaz.compiler.observation-bundle/v1 directory with the requested AST, typed or generated source phase, diagnostic records and explicit producer provenance. Stage 1 and Stage 2 products retain the identities required by their own record schemas.

--format json is rejected because the JSON and JSON Lines members are fixed bundle artifacts. A preview does not offer a separate stdout JSON report.

Exit status

Exit 0 only when a complete preview for the requested route is published.

Exit 1 for invalid arguments, unsupported source or language profile, invalid package state, producer failure, invalid bundle data or unsafe or failed publication.

A producer failure remains a failure. Recovery may recommend a new explicit compiler observe invocation, but this invocation must not execute it or silently downgrade its terminal.

Filesystem effects

Use the same outside source root check and managed bundle publication rules as compiler observe. Stage complete output and replace only an existing valid managed observation bundle.

Read the selected source tree or embedded self source without modifying it. Retain existing output if replacement cannot be installed. Do not emit or run a native program.

Network access

Do not download a producer, compiler or dependency and do not contact a registry. Use only the explicitly admitted installed producer and local input facts.

Reproducibility

Successful runs without host resource failure are repeatable. Canonical preview bytes are stable for the same selected producer identity, source set and logical paths, package facts, language profile, terminal and installed product.

Stage 1 and Stage 2 provenance may differ even when their semantic phases agree. Such a difference is meaningful evidence and remains visible to provenance comparison.

Packages and locks

Entry omission selects package mode except when --self-source selects the embedded compiler source set. Package mode validates the package and uses already materialized dependencies.

--locked verifies the existing matching package lock without updating it. Registry dependencies and Lispex package configuration require this explicit option even when a lock already exists. Without it, only packages with neither requirement may load their local path dependencies using declared content hashes.

Missing or changed dependency content fails without materialization. A locked operation also rejects a missing or stale lock. The embedded compiler source set does not acquire a caller package lock or vendor dependency merely from the current directory.

The invocation topaz compiler preview main.tpz --language-version 5.21 --terminal invalid is expected to exit with 1.