Invocation, options and results
링크topaz lock
topaz lock
입력
topaz lock accepts no positional operands. - selects the package root and defaults to the current directory.
The root must contain a valid topaz.. The package language selects lock interpretation, so - is rejected. -, -, output-format options, extra operands, missing values, repeated options, and attached values are rejected.
옵션과 충돌
| 옵션 | 기본값 | 계약 | 충돌 |
|---|---|---|---|
--root <dir> | . | The explicit source root or package root for this invocation. | 없음 |
출력 채널
stdout
stderr
종료 상태
0
Every required identity was established and the new lock was installed.
1
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.
효과
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. 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.
Lock generation uses local files and installed components without network access. Missing registry content is not downloaded.
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.
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/ 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.
Operation
링크Prepare dependency identities in the manifest before locking. Local dependency content must agree with the manifest.
Option conditions
링크lock uses topaz.toml [package].language; drop --language-version
Behavior contract
링크Command behavior
Arguments and rejection
topaz lock accepts no positional operands. - selects the package root and defaults to the current directory.
The root must contain a valid topaz.. The package language selects lock interpretation, so - is rejected. -, -, 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. to standard error.
Failures write a human diagnostic to standard error. - 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_. 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. 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/ 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.
이유
A lock binds known package inputs to exact identities. It must not silently select newer versions or bless a changed local dependency hash, because that would change the input being locked.
The linked public CLI recipe checks the exact displayed argument rejection before the requested operation. It does not execute the successful operation or verify its effects.
Successful lock generation writes package identity files and can prepare Lispex artifacts, so it is outside the execution allowlist. The linked safe recipe rejects the extra source operand and language selector.
Example contract
링크Example contract
The invocation topaz lock main. is expected to exit with 1.
The command has no positional source operand. The adapter-supplied fixture operand is deliberately rejected before its operation; this is an arity example, not a successful lock session.
이유
A lock records dependencies for the package selected by -. Rejecting a source operand prevents a file argument from appearing to choose a different dependency graph.
Example
링크Argument-rejection example
링크function identity<T>(value: T) -> T {value}
기대 결과
기대 결과
Textual rejection details remain Pending in the reference model. The independent Tools example gate expects exit 1.
The command has no positional source operand. The adapter-supplied fixture operand is deliberately rejected before its operation; this is an arity example, not a successful lock session.
Verification scope
링크Observed with Topaz 5.21.3 on 2026-11-06T08:36:29.642Z. This invocation passed; exit 1. 3 assertions were evaluated against the independent expected result. Execution record. This result covers the displayed invocation.