compiler observe

Arguments and rejection

Use topaz compiler observe [entry] --out-dir <dir>. Accept --compiler rust or --compiler self, --locked, --verbose, --root <dir>, --terminal typed or --terminal rust-source, --language-version <version>, --compiler-memory-mib <MiB> and --compiler-time-ms <ms>.

The default terminal is rust-source and the current profile compiler default is self. Memory and time values are positive decimal integers using the shared option and environment precedence. Require one output directory and at most one entry operand.

Reject --terminal ast, an unknown terminal, bootstrap producer or self source options, repeated options, missing values, equals forms and every unlisted option. Reject --locked when an explicit standalone entry is supplied.

Without an entry load the package selected by --root or the current directory. With an entry use its directory as the default source root. Require the resolved output path to be outside that source root.

Output

On success write a human completion line identifying the output directory to standard output. Diagnostics and verbose compiler selection information use standard error. There is no selectable JSON report and --format json is rejected.

The output directory contains topaz-observation.json using topaz.compiler.observation-bundle/v1, request and response records, source and diagnostic records, phase records through the requested terminal and producer provenance. Every member has the schema and digest required by the bundle manifest.

A typed terminal contains no invented later phase result. A Rust source terminal records generated source rather than a native executable. An observation result may describe compiler diagnostics and must retain their outcome faithfully.

Exit status

Exit 0 only after publishing a complete valid observation of the selected compiler route. A recorded compiler rejection can be a valid observation and must be identified in its response record.

Exit 1 for invalid arguments or source selection, an unsupported explicit compiler route, missing or invalid package state, compiler or resource failure that prevents an observation, invalid bundle construction, unsafe output destination or publication failure.

No failure may trigger an implicit preview producer or substitute compiler.

Filesystem effects

Read the selected source tree and already materialized package dependencies without editing them. Create output parents as needed only after validating that the destination is outside the source root.

Stage and validate the entire bundle in a sibling directory. An existing output directory may be replaced only when it is already a valid managed observation bundle. Reject unmanaged directories, special files and symlinked bundle members.

Publish the complete bundle and retain the previous managed bundle if installation of its replacement fails. Remove only staging and backup paths owned by the operation. A crash may leave a private recovery directory and must not turn arbitrary sibling files into cleanup targets.

Network access

Perform no registry access, dependency fetch or compiler download. Observation ends at compiler data or generated source and does not invoke a native build or run the user program.

Reproducibility

Successful runs without host resource failure are repeatable. The same source bytes and logical paths, package graph, dependency bytes, language profile, compiler identity, product release, terminal and budgets produce the same canonical observation content.

Comparing different compilers or producers requires the declared comparison layer. Provenance identifies the producer and is not erased to make distinct compiler routes look identical. Human output paths and resource failures require the same environment for byte equality.

Packages and locks

Package mode uses the manifest entry and table dependency declarations. --locked requires a valid matching topaz.lock before compilation. Registry dependencies and Lispex package configuration require this explicit option even when a lock already exists.

Without --locked, a package with neither registry dependencies nor Lispex configuration loads local path dependencies using their declared content hashes. Missing or changed dependency content fails without a fetch. A locked operation also rejects a missing or stale lock without repairing it.

Observation does not create or rewrite a package lock or vendor tree. Standalone entry mode rejects --locked.

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