Command reference

• validate
• run
• verdicts
• verify-record
• perf
• stress
• aql-probe
• stress-compare
• perf-assets
• conformance-assets
• emit-schemas

Every flag below is the one the binary declares. veredictum <command> --help prints the same list from the build you have installed, and that output is the authority if the two ever disagree.

Three commands make the conformance record (validate, run, verdicts), two measure (perf, stress), verify-record checks a sealed bundle, and the rest render or explore.

validate

Validate one artifact tree through every machine gate.

veredictum validate --root <ROOT> [--specs <SPECS>] [--write-report]

Every machine check over the catalogue: identifier uniqueness, citation resolution, binding completeness, coverage of the enumerated wire surface, and claim completeness against the committed party statements. It prints one line per finding and a summary line, and exits 1 if the finding count is not zero.

--write-report is off by default on purpose. A check verb that rewrites a file on every run is a trap for read-only invocations, so the pipelines that publish the coverage report ask for it explicitly. The report lands at <ROOT>/coverage-report.md, beside the artifact families it measures.

run

Execute the catalogue against a live SUT and emit results.json plus the run report.

veredictum run --root <ROOT> --ixit <IXIT> --out <OUT> \
    [--sut-name <NAME>] [--sut-version <VERSION>] \
    [--filter <SUBSTRING>] [--statement <STATEMENT>] \
    [--sign-key <KEY>]

Drives every applicable case and records the exchange. Exits 1 if any case failed or errored.

verdicts

Compute the verdicts from a statement and a results record against an artifact tree, and write the rendered submission documents.

veredictum verdicts --statement <STATEMENT> --results <RESULTS> \
    --root <ROOT> --out <OUT> [--sign-key <KEY>]

The pure step. It reaches no network and reads nothing but its inputs, which is what makes a published verdict re-derivable by anyone who has the same four files.

verify-record

Verify a sealed bundle: recompute every digest its record manifest names, and check the detached signature over that manifest.

veredictum verify-record --record <DIR> --key <KEY>

Prints the signer fingerprint, the signing time, and one line per file with its digest verdict. Zero findings is the only passing result: a digest mismatch, a file the manifest names but the bundle does not carry, or a signature no component of the supplied key verifies, each exits 1 naming what failed.

The bundle is ordinary files, so the check does not depend on this tool. gpg --verify record-manifest.json.asc record-manifest.json establishes the same signature, and sha256sum re-derives the same digests.

A verified bundle is one link in the chain and not the whole of it. A valid signature proves integrity and origin since signing, and says nothing about the conditions the run executed under. The published instrument, the verification pack and the citation-carrying record are the rest, which is why that sentence prints on every verification.

perf

Execute the performance schedule’s open-loop measured run against a live SUT and merge the measurement records into an existing results.json.

veredictum perf --root <ROOT> --ixit <IXIT> --results <RESULTS> --class <CLASS> \
    [--seed-workers <N>] [--hours <H>]

Conformance by measurement. Latency is measured from the planned arrival instant under open-loop offered load, so a stall shows up as latency instead of disappearing into a slowed-down request rate. A longer --hours window is a stricter demonstration and persists like any measured run; nothing shorter than the case exists.

The environment block is mandatory rather than optional because a latency number is a claim about a deployment, and a claim with no deployment described cannot be checked or reproduced.

stress

Run the step-load stress instrument: geometric load steps up to the maximum sustainable throughput.

veredictum stress --root <ROOT> --ixit <IXIT> --out <OUT> \
    [--corpus-class <CLASS>] [--seed-workers <N>] \
    [--step-secs <S>] [--bisections <N>] [--max-rate <R>]

Exploration only, and class-free by design: no class floor enters the stress report or its chart. A stress.json is never a conformance record, and quoting one as if it were is a misuse of the tool.

aql-probe

Run the AQL optimization probe against a live, freshly seeded SUT.

veredictum aql-probe --root <ROOT> --ixit <IXIT> --out <OUT> \
    [--corpus-class <CLASS>] [--seed-workers <N>] [--requests <N>]

Fires the measurement machinery’s AQL vocabulary, records wire percentiles per probe, and attributes the database-side cost through pg_stat_statements. This is evidence for someone optimizing a server, and it is never a conformance record.

stress-compare

Render the cross-SUT stress overlay from two committed stress reports.

veredictum stress-compare --left <LEFT> --left-label <LABEL> \
    --right <RIGHT> --right-label <LABEL> --out <OUT>

Deterministic, and both directions on equal footing: the two curves are drawn by the same code from the same kind of file, so neither side gets a rendering advantage.

perf-assets

Render the published performance SVG assets from a committed results.json.

veredictum perf-assets --root <ROOT> --results <RESULTS> --out <OUT> \
    [--summary <PATH>] [--stress <STRESS>]

conformance-assets

Render the capability heat grid and the per-chapter outcome bars from committed party artifacts.

veredictum conformance-assets --root <ROOT> --results <RESULTS> \
    --verdicts <VERDICTS> --out <OUT> [--suffix <SUFFIX>]

Both renderers are deterministic over files already committed, so a build job can regenerate them and diff the result. A hand-drawn number in a published chart is a build failure rather than a review comment.

emit-schemas

Write the published JSON-Schema set.

veredictum emit-schemas --out <OUT>

Byte-deterministic. The schemas in the repository’s schemas/ directory are this command’s output, drift-tested against it, which is how the published format and the code that reads it stay one thing. Author against these if you are writing your own catalogue or your own harness.