Rendered from docs/interfaces/headwater-conformance.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

headwater conformance

Synopsis

headwater conformance [--level <name>] [--now <date>] [--json] [--root <path>]

The verb evaluates the repository against the conformance rules in its selected package. It takes no operand.

Description

headwater conformance reads the package rule set and evaluates the four readings this engine holds: pin.current, lock.current, corpus.classified and projections.current.

pin.current is the reading that holds the installed bytes to the pin. It compares the version the installed package declares to the version the consumer pinned. It then compares the digest the consumer pinned to the digest in the record the publisher wrote. It then recomputes the digest of every file under the package directory and compares each one to that record. It names the same three divergences vendor names, and it writes nothing. headwater taxonomy resolve performs only the first of those comparisons and reads no digest.

The report identifies the package, version, digest and date. It lists every rule, each level and the highest level reached by met rules. A level is cumulative, so it includes the rules of earlier levels.

Beside the digest, the report states whether this run compared that digest to the release record of the installed package. Where a rule of the set reads the pin, the report names that rule. Where no rule reads it, the report states what the installed package declares about itself. That statement carries no verdict. No level and no exit status reads it, and a set that declares pin.current is the only set in which a rule decides the pin.

A waiver covers a gap only for a requested level and only until its inclusive expiry date. It never changes the reported level, because the reported level reads met rules alone. A rule with no engine reading, an orphan waiver or malformed conformance data ends the run rather than being skipped.

Without --level, the verb measures and exits successfully even when gaps exist. With --level, it exits successfully only when every rule under that rung is met or covered by a live waiver. Text goes to standard output. JSON carries the same report and adds a gate member only when a level was requested.

Preconditions

The repository must carry a readable .headwater/taxonomy.lock and consumer declaration. The lock supplies the package identity and the corpus configuration.

The selected package must exist under .headwater/packages/, declare a conformance file and carry a conformance format this engine reads.

The projections must read from the resolved taxonomy. The host must provide a date, or --now must provide one in YYYY-MM-DD form.

Options

Option	What it does
--level <name>	Ask whether the named cumulative rung passes. A live waiver can cover a gap under this rung.
--now <date>	Evaluate expiry and dated readings against this date.
--json	Write the machine-readable conformance report.
--root <path>	Select the repository to evaluate.
--no-color	Force plain text on both streams: bold and dim weight plus glyphs, no escape sequence. The default already senses whether each stream is a terminal, and renders color only there.
--no-banner	Suppress the masthead: the line naming this binary and its version, that the root help screen alone prints. It is accepted here and does nothing, since only the root screen prints one.

--format is not an option of this verb. --wide is refused because the verb prints a report rather than help. Global --help, --version and --no-banner are answered before the verb runs.

Exit status

0 means that evaluation completed. Without --level, this includes gaps, expired waivers and undecided attestations.

1 means that the command line, taxonomy, package, conformance file, waiver set or date was refused, or that the requested level did not pass. An ordinary report is printed before a failed requested gate is reported on standard error.

A level that did not pass still wrote its whole document, and a refusal wrote none. Take conformance --json --level L1 over a corpus that does not reach L1. It exits 1 with the whole document on standard output, because the gate is a member of that document. A refusal writes nothing there, and its account is one English sentence on standard error. So the property is that a refusal writes no document, and not that a non-zero exit writes none, which is what HW-DR-0043 rules.

Installed bytes that differ from the release record end the run, whatever level was requested. The rule set this verb reads lives inside the package, so a package whose bytes moved carries a rule set the run cannot trust. The refusal names each member that moved, and --level does not decide it.

A rung the package does not declare is a refusal, and the two formats print it in a different order. The text report is written before the gate is asked, so an undeclared rung is refused under the gaps it is about. The document cannot take that order, so --json writes nothing at all on that run.

1, and never 101, when standard output or standard error cannot be written, and one sentence on standard error names a failed standard output.

Environment

No environment variable reaches this verb. The package, taxonomy, repository and date come from the tree and command line.

Files

Path	How this verb treats it
.headwater/taxonomy.lock	Read for the resolved taxonomy and lock digest. A lock that is not a regular file is refused before the verb opens it, at each read.
.headwater/taxonomy.yml	Read through the consumer loader.
.headwater/packages/ and the selected package directory	Read for the package manifest, release record and conformance rules. A release record, a member or a conformance file that is not a regular file is refused before the verb opens it. A named pipe is one example.
The corpus	Read for classification and projection checks.
.headwater/imports/	Read where .headwater/taxonomy.yml declares an import, for the anchors that an imported snapshot supplies. An imports entry that does not read stops the verb with exit 1, and so does an at path outside the repository root.
the path each harvests.<name>.at names	Read where .headwater/taxonomy.yml declares a pinned corpus export, for the anchors that export supplies. A harvests entry that does not read stops the verb with exit 1, and so does an at path outside the repository root. A pin with no digest binds no anchor. An absent file binds no anchor, and neither does a file that fails the pinned digest or is not an export.

The verb writes no file.

See also

headwater taxonomy vendor installs the package whose conformance rules this verb reads.

Spec 7 defines conformance as wired adoption rather than a copied taxonomy.

headwater check reports findings over the corpus. Its --strict option is a separate check gate.