lock

Arguments and rejection

topaz lock accepts no positional operands. --root <dir> selects the package root and defaults to the current directory.

The root must contain a valid topaz.toml. The package language selects lock interpretation, so --language-version is rejected. --from, --locked, output-format options, extra operands, missing values, repeated options, and attached values are rejected.

Output

Successful locking leaves standard output empty and writes a completion line naming topaz.lock to standard error.

Failures write a human diagnostic to standard error. --format json is rejected because lock generation has no JSON report.

The lock is UTF-8 TOML with a root [[package]] entry containing name, version, source, and manifest_hash. The root source is root. Subsequent package entries are ordered by dependency name.

A local dependency entry contains its declared name, path, and verified hash. A registry entry contains name, exact version, source registry, and hash. The standard library is bound by the language mode and is not emitted as an ordinary external package entry.

Declared extern entries record their module and artifact identities, ABI identity, sandbox settings, and replay input identity. Lispex entries additionally bind the selected profile, application, target disposition, component, rule inputs, quotas, handle catalogue, and prepared artifacts.

Exit status

Exit code 0 means every required identity was established and the new lock was installed.

Exit code 1 covers invalid arguments, invalid or unreadable manifests, dependency identity or hash mismatches, unavailable hash inputs, invalid extern or Lispex inputs, preparation failures, and failed lock writes.

Filesystem effects

The command reads the manifest and the declared local inputs. A local dependency hash is recomputed and must equal the manifest hash.

The command stages the complete lock and replaces topaz.lock through the strict package file boundary. Symlinks, nonregular lock paths, and stale staging paths are rejected. Failures before replacement retain the prior lock.

For a package with Lispex rules, locking also prepares the declared rule artifacts and handle catalogue in package-owned paths before publishing the lock that identifies them. It does not rewrite the manifest or dependency source trees.

Network access

Lock generation uses local files and installed components without network access. Missing registry content is not downloaded.

Reproducibility

Identical manifest bytes, admitted package content, extern inputs, and Lispex component identities produce identical lock bytes. The manifest hash includes whitespace, so changing manifest formatting changes that identity.

Lock ordering is independent of filesystem enumeration. The lock contains no timestamp, random identifier, or temporary workspace path. Repeating the operation with unchanged inputs preserves the lock bytes.

Packages and locks

A registry dependency with an explicit manifest hash can be locked without a vendor copy. When its hash is absent, the matching package under vendor/<name>/<version> supplies the content hash.

Recording a declared registry hash does not establish that its bytes are installed. Locked compilation separately verifies matching vendored content.

A local dependency always requires a manifest hash. Locking rejects changed local content and never replaces the expected hash with the observed hash.

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