run

Arguments and rejection

Accept zero or one entry operand and the listed compiler, lock, verbosity, root, language, and resource options. Without an entry, use the package entry under the selected root.

Arguments after -- belong to the program and retain their order and spelling. They are not parsed as Topaz options. Program arguments require the admitted explicit main signature.

Reject --format json, --exports-json, --profile, and --types before execution. Invalid source, dependency identity, lock content, or entry signature also prevents execution.

Output

Program standard output remains standard output. Runtime diagnostics, command errors, and verbose compiler selection use standard error. The command does not wrap program output in a JSON object or add a check success banner.

--format json is rejected. A program may itself print JSON, which remains program data.

Exit status

Successful top-level execution or an explicit main result of Ok(0) exits 0. An explicit main returns Result<int, string>. Ok(code) uses an integer from 0 through 255 as the process exit code. Err(message) writes the string to standard error and exits 1. An out-of-range code or an invalid result shape fails with exit 1.

Argument, package, compile, runtime, deferred-action, worker, and host-operation failures exit 1. Output and program effects that occurred before a runtime failure remain observable.

A deferred runtime or host error forces exit 1 even when main returned Ok(0). Earlier program output and effects remain observable.

Filesystem effects

Compilation reads project inputs and may use an owned temporary workspace. The tool does not edit source, manifest, lock, or vendor files. After successful checking, the program can perform the filesystem effects admitted by its host. Those runtime effects are not rolled back on failure.

Network access

The compiler and package loader do not use the network or fetch dependencies. The executed program may contact services through the capabilities provided by its host.

Reproducibility

Compilation is repeatable for fixed source, dependencies, options, and toolchain. Program output and exit status also depend on program arguments, standard input, environment, filesystem, time, randomness, and external services. Equal source bytes alone do not imply equal runtime output.

Packages and locks

Resolve the selected package and verify required lock identity before execution. Registry dependencies must already be materialized. No implicit add, lock, or vendor operation occurs.

Registry dependencies or Lispex configuration require explicit --locked, even when a matching lock exists. Without that option, a local-only package can load declared path dependencies by their expected hashes. Locked loading rejects missing or stale state and never repairs it.

Standalone entry mode rejects --locked. Selected-entry test is the exception when an explicit root contains the package manifest and the entry belongs to that package.

The invocation topaz run main.tpz --language-version 5.21 --format json is expected to exit with 1.