A deferred error fails the whole command Adopted November 8, 2026 · 6.0.0 · In progress
Problem The main execution can finish before deferred work reports a runtime or host error. Callers that look only at completion status still need to see that failure.
Decision A deferred runtime or host error fails the execution and prevents a test- ok report.
Alternatives considered Report the main execution’s success as the final result. A later failure would be hidden by the successful result.Why Tools that inspect command completion can detect deferred failures.
Changed rules Test completion and failure reporting →
Test assertions evaluate once and compare golden files exactly Adopted November 7, 2026 · 6.0.0 · Being verified
Problem Assertion arguments can have side effects, and a final newline can matter in a golden file. Tests need defined behavior both after a failed assertion and when the file differs.
Decision Evaluate arguments once, from left to right. Use ordinary comparisons and extract the outer constructor. An assertion fault TPZ4007 stops the current test at runtime. Compare the existing UTF-8 golden file exactly, without creating or updating it. Examples
Equality returns unit and execution continues run · runtime · Verification · not-run
assert-eq.tpz Equality returns unit and execution continues Open in Playground → import std.io import std.test let result: () = test. assertEq ([ 1 , 2 ], [ 1 , 2 ]) io. writeLine ( "{result}" ) Expected output Exit code 0
()
Expected result Expected result Execution completes. Exit code 0.
No stderr.
Expected stdout This exact example has not been executed.
Match exact line endings and an empty golden file run · running · Verification · not-run
main.tpz Match exact line endings and an empty golden file import std.test import std.io test. assertGolden ( "expected.txt" , "alpha\r\nβ\n" ) test. assertGolden ( "empty.txt" , "" ) io. writeLine ( "golden text matched" ) Expected output Exit code 0
golden text matched
expected.txt Match exact line endings and an empty golden file empty.txt Match exact line endings and an empty golden file Expected result Expected result Execution completes. Exit code 0.
No stderr.
Expected stdout This exact example has not been executed.
Fail when the final newline is missing from actual text run · running · Verification · not-run
main.tpz Fail when the final newline is missing from actual text import std.test import std.io io. writeLine ( "before" ) test. assertGolden ( "expected.txt" , "line" ) io. writeLine ( "after" ) Expected output Nonzero exit
before
expected.txt Fail when the final newline is missing from actual text Expected result Expected result Rejection during run. Nonzero exit.
Expected stdout This exact example has not been executed.
Fail instead of creating a missing golden file run · running · Verification · not-run
main.tpz Fail instead of creating a missing golden file Open in Playground → import std.test import std.io io. writeLine ( "before" ) test. assertGolden ( "missing.txt" , "new text" ) io. writeLine ( "after" ) Expected output Nonzero exit
before
Expected result Expected result Rejection during run. Nonzero exit.
Expected stdout This exact example has not been executed.
Fail assertOk with the rendered error run · running · Verification · not-run
main.tpz Fail assertOk with the rendered error Open in Playground → import std.test import std.io let value: Result < int , string > = Err( "bad" ) io. writeLine ( "before" ) test. assertOk (value) io. writeLine ( "after" ) Expected output Nonzero exit
before
Expected result Expected result Rejection during run. Nonzero exit.
Expected stdout This exact example has not been executed.
Why A failed assertion stops the test, and the same checked-in golden file can be compared again.
Changed rules Equality assertions →Compare existing golden text without updating it →Assert a Result constructor and return its payload →Assert presence or absence →
Storage cleanup preserves workspaces that may still be in use Adopted November 8, 2026 · 6.0.0 · In progress
Problem An old workspace can still belong to a running job. Its ownership or liveness can also change between inspection and deletion.
Decision Preserve workspaces with a live or uncertain owner regardless of age. Status and cleanup use the same classification. Recheck ownership and liveness immediately before deletion. Alternatives considered Delete by age alone. An old workspace can still be in use.Why Cleanup leaves files in place while an owner is active or its status is uncertain.
Changed rules Command behavior →Command behavior →
Command options with no effect are removed Adopted November 7, 2026 · 6.0.0 · In progress
Problem A script using - - types can look as though it requests extra work. An option that does nothing obscures what the command actually runs.
Decision Remove options that have no effect, including - - types.
Examples
reject · command-validation · Verification · not-run
main.tpz Reject the unused types option Expected output Exit code 1
No stdout. Expected result Expected result Rejection during command. Exit code 1.
No stdout.
This exact example has not been executed.
check · command-validation · Verification · not-run
Expected result Expected result Checking accepts the program. Exit code 0.
No stderr.
No stdout.
This exact example has not been executed.
Alternatives considered Continue accepting no-op flags. Readers could mistake the flag for a behavior change.Why An option in a command line corresponds to real work or a real choice.
Changed rules Type checking without a mode flag →
Topaz version prints the product version Adopted November 7, 2026 · 6.0.0 · In progress
Problem Printing the version and requesting verbose output could each have several spellings. Documentation and scripts might use different names for the same operation.
Decision Run topaz version to print the version. Use - - verbose for verbose output. Remove aliases for both operations. Examples
reject · command-validation · Verification · not-run
main.tpz Reject the version flag alias Expected output Exit code 1
No stdout. Expected result Expected result Rejection during command. Exit code 1.
No stdout.
This exact example has not been executed.
reject · command-validation · Verification · not-run
main.tpz Reject the short version alias Expected output Exit code 1
No stdout. Expected result Expected result Rejection during command. Exit code 1.
No stdout.
This exact example has not been executed.
reject · command-validation · Verification · not-run
main.tpz Reject the short detail alias Expected output Exit code 1
No stdout. Expected result Expected result Rejection during command. Exit code 1.
No stdout.
This exact example has not been executed.
check · command-validation · Verification · not-run
main.tpz Request the detailed release report Expected output Exit code 0
Expected result Expected result Checking accepts the program. Exit code 0.
No stderr.
This exact example has not been executed.
Alternatives considered Keep the aliases. Readers would still need to recognize multiple names for equivalent operations.Why Use the spelling from help directly in scripts.
Changed rules Named metadata commands and long options →
An option value is a separate argument Adopted November 7, 2026 · 6.0.0 · In progress
Problem Joining an option with its value or passing two arguments gives the same command two forms. Code that constructs an argument array can use one convention.
Decision Pass the value as the next argument. The - - flag=value form is unavailable.
Examples
reject · command-validation · Verification · not-run
main.tpz Reject an equals format value Expected output Exit code 1
No stdout. Expected result Expected result Rejection during command. Exit code 1.
No stdout.
This exact example has not been executed.
check · command-validation · Verification · not-run
Expected result Expected result Checking accepts the program. Exit code 0.
No stderr.
No stdout.
This exact example has not been executed.
Alternatives considered Accept joined and separate values. The same option value would have two spellings.Why The argument list marks the boundary between the option and its value.
Changed rules Separate option values →
A command option occurs at most once Adopted November 7, 2026 · 6.0.0 · In progress
Problem A script that combines arguments can pass the same option twice. Accepting both occurrences makes it harder to tell which value took effect.
Decision Reject a repeated option even when its values are identical.
Examples
reject · command-validation · Verification · not-run
main.tpz Reject a repeated language selector Expected output Exit code 1
No stdout. Expected result Expected result Rejection during command. Exit code 1.
No stdout.
This exact example has not been executed.
reject · command-validation · Verification · not-run
main.tpz Reject conflicting formats in one order Expected output Exit code 1
No stdout. Expected result Expected result Rejection during command. Exit code 1.
No stdout.
This exact example has not been executed.
reject · command-validation · Verification · not-run
main.tpz Reject conflicting formats in the other order Expected output Exit code 1
No stdout. Expected result Expected result Rejection during command. Exit code 1.
No stdout.
This exact example has not been executed.
check · command-validation · Verification · not-run
Expected result Expected result Checking accepts the program. Exit code 0.
No stderr.
No stdout.
This exact example has not been executed.
Alternatives considered Use the last value. Changing the order in which arguments are assembled could silently change behavior.Why The duplicate is visible at the command that contains it.
Changed rules One occurrence of each option →
Adopted November 7, 2026 · 6.0.0 · In progress
Problem A script can read output from several commands. Command-specific flags would give the same output choice several spellings.
Decision Use - - format json on commands with JSON output. Remove - - json.
Examples
check · command-validation · Verification · not-run
Expected result Expected result Checking accepts the program. Exit code 0.
No stderr.
No stdout.
This exact example has not been executed.
Alternatives considered Keep separate flags for each command. Users would have to remember different ways to request the same format.Why Scripts can select the output format consistently across commands.
Changed rules One JSON format selector →
JSON diagnostics keep stable codes and primary locations Adopted November 7, 2026 · 6.0.0 · Being verified
Problem Tools read a diagnostic's code and location to navigate to the offending expression. The message can improve without changing what the tool highlights.
Decision The - - format json contract covers structured identity, required fields and their types, coordinate units, severity and the cause pointed to by the primary location. Message and label wording can change. Redefining an identity or a promised location requires a contract version and migration guidance. Retired identities are never reused. Alternatives considered Leave location meaning outside the stable contract. A tool could start highlighting another cause with no clear regression signal.Make message wording and the order of secondary notes stable too. The contract should catch wrong causes and locations without blocking wording improvements.Why Tools can consume fields while documentation can improve diagnostic wording.
Changed rules One JSON format selector →
Topaz help opens command help Adopted November 7, 2026 · 6.0.0 · In progress
Problem A script can accidentally omit the command name. If that prints help successfully, it is hard to tell whether the intended work ran.
Decision Request help with topaz help. Running without a command is a usage error.
Examples
reject · command-validation · Verification · not-run
main.tpz Reject an invocation without a command Expected output Exit code 1
No stdout. Expected result Expected result Rejection during command. Exit code 1.
No stdout.
This exact example has not been executed.
Alternatives considered Show help when the command is omitted. A missing command would look like an intentional help request.Keep both a bare invocation and topaz help as help. Help would have two entry points, and a missing command would pass as success.Why Help requests are distinct from missing arguments.
Changed rules Name the help command →
Vendor brings dependency sources into the project Adopted November 7, 2026 · 6.0.0 · In progress
Problem Two command names could fetch dependency sources in the same way. Users had to determine whether the commands behaved differently.
Decision Use vendor and remove fetch, which performed the same operation.
Alternatives considered Keep both commands. One operation would still need two names and help entries.Why Scripts use one recognizable command for bringing in dependency sources.
Changed rules One registry materialization command →
Dependency declarations use tables Adopted November 7, 2026 · 6.0.0 · In progress
Problem A dependency written as a string might need a format conversion before adding a field. Tool-generated files can avoid that difference as well.
Decision Write dependency declarations as tables. init and add also generate tables.
Alternatives considered Support both version strings and tables. The same dependency could have two structures.Why Dependency attributes use a consistent structure across manifests.
Changed rules Dependency declarations use tables →