compiler compare

Arguments and rejection

Use topaz compiler compare <left> <right> with exactly two operands. The only option is --layer semantic, --layer generated-source, --layer provenance or --layer native-binary. The default is semantic.

For the first three layers both operands are observation bundle directories and each must validate before comparison. For native-binary the operands are existing regular files whose bytes are read without execution.

Reject an unknown layer, repeated option, missing value, equals form, missing or extra operand and every unlisted option. In particular no compiler, language, root, output or format selector is accepted.

Output

Write one canonical JSON comparison receipt using topaz.compiler.comparison/v1 to standard output. This is the fixed comparison artifact and there is no human renderer or --format selector. Both --format human and --format json are rejected.

The receipt contains schema, string layer, boolean equal, nullable string firstFailingPhase, nonnegative integer mismatchCount, array mismatches and boolean truncated.

Each mismatch identifies phase, path, kind and nullable stableId, together with nullable left and right byte lengths and SHA-256 digests. Report at most 32 mismatch rows at the first failing phase and set truncated when further mismatches at that phase were omitted.

Semantic comparison examines source set, tokens, AST, resolved data, typed data, lowered data, diagnostics and recorded outcome in that order. Generated source comparison examines generated source records and source bytes. Provenance comparison examines producer provenance. Native comparison compares the complete supplied file bytes.

Disagreement produces a valid receipt. A failure to read or validate the inputs writes a human explanation to standard error and does not fabricate a comparison receipt.

Exit status

Exit 0 when the requested layer is equal. Exit 1 when the valid comparison receipt reports a difference.

Exit 1 also covers invalid arguments, unreadable inputs, invalid observation bundles or failure to produce the receipt. Callers distinguish a valid disagreement by its complete stdout receipt.

Filesystem effects

Read both inputs without changing them. Do not rebuild sources, run either native input, write a result file, rewrite an observation manifest or follow bundle member symlinks.

The left and right operand order determines the labels in the receipt. Do not silently swap operands to normalize a disagreement.

Network access

Perform no network access. Missing observations, dependencies or native inputs are errors rather than download requests.

Reproducibility

The same ordered input bytes, selected layer and comparison schema produce identical canonical receipt bytes. Mismatch ordering follows phase order and member path order.

Equality is scoped to the requested layer. Semantic equality does not claim identical generated source, provenance or native binaries.

Packages and locks

Compare package facts already recorded in an observation. Do not resolve the caller package, consult a live registry, rewrite its lock or materialize its dependencies.

Native comparison accepts existing product files and does not infer a package build request from their paths.

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