Skip to content

Reports and artifacts ​

This page describes the report formats, the sections of a report, the files of a run directory under .veritas/runs/<run-id>/, the metadata the files carry, and how secrets are removed. The CLI, the Node API, the MCP server and the GitHub Action write the same files. For how to interpret a report, see Reading results.

Report formats ​

bash
veritas report                          # text summary of the latest run
veritas report --format html > report.html
veritas report --format sarif --run <run-id> > veritas.sarif
veritas report --json                   # same as --format json
Format--formatFile in the run directoryUse
Texttextnone (printed only)Terminal summary; the default of veritas report
JSONjsonreport.jsonEverything the other formats show, for tools
Markdownmarkdownreport.mdPull request comments and documents
HTMLhtmlreport.htmlA single self-contained page for reading in a browser
SARIFsarifreport.sarifSARIF 2.1.0 for code scanning tools, with locations

The files are written by commands that include the report stage (veritas run with any profile, and veritas prove), in the formats listed in reports.formats (default: json, markdown, html, sarif; text is never written to a file). veritas report renders any format on demand, from the latest run or from --run <run-id>, and redacts what it prints.

Report sections ​

The JSON, Markdown and HTML reports have the same ten sections:

SectionContent
1. Run metadata/environment/scopeRun id, command, profile, options, stages with their status and messages, verdict and reasons, and the envelope metadata
2. Collected evidence with provenanceSources (location, kind, trust) and the normative statements quoted from them
3. Property ledgerEvery property with its review status, origin, sources and formal model
4. Specification vs implementation mismatchesFindings where the code and a property disagree, with counterexamples
5. Tests x properties matrixWhich test relates to which property
6. Mutation outcomesMutants by status, and the tests that cover and kill them
7. Formal claimsEach claim with its kind, status, engine, assurance, bounds, assumptions and counterexample
8. Test assessmentsThe evidence vector and outcome of each test
9. Improvement proposalsImprovement plans made from the run, with their apply attempts
10. LimitationsWhat the run could not check, and why

A section whose stage did not run is empty. An artifact that exists but cannot be read is an error, not an empty section, so a damaged file cannot hide its findings.

report.json carries schemaVersion and meta (the envelope metadata below) at the top level, followed by run, sources, statements, properties, conflicts, tests, edges, assessments, mutants, claims, findings, improvements and artifactBase.

Run directory ​

A run of veritas run --profile deep produces this layout; other commands write the subset their stages produce.

text
.veritas/runs/run-20261120T100639627Z-000-a465b9/
├── run.json              command, options, scope, stages, verdict, policy reasons
├── code-index.json       exported functions, signatures, branches (index stage)
├── evidence.json         sources and quoted statements (discover stage)
├── properties.json       properties, conflicts, statement mapping, formalization (spec stage)
├── test-map.json         tests, assertions, test-property edges (map stage)
├── mutation.json         mutants and their status (mutate stage)
├── mutation/             mutator's own report and the Vitest configuration it ran with
├── pbt.json              property-based test results with seeds (pbt stage)
├── pbt/                  one file per property-based test (PBT-<id>.json)
├── claims.json           formal claims (prove stage)
├── proofs/               solver inputs and outputs, JavaScript replays
├── assessments.json      test assessments (assess stage)
├── findings.json         findings
├── report.json  report.md  report.html  report.sarif
├── artifact-index.json   SHA-256 and metadata of every file without an envelope
└── trace.jsonl           every log event of the run, debug level included

The mutation/ directory is absent when mutation results were reused from the cache.

FileContent
run.jsonId, command, arguments, profile, scope, options, start and end time, each stage with its status, messages, artifacts and usage, the exit code, the verdict and the policy reasons
code-index.jsonThe code index of the project's sources
evidence.jsonCollected sources with their provenance and trust, statements, and skipped sources
properties.jsonproperties, conflicts, mapping (what became of each statement), formalization and staleApprovals
test-map.jsonThe test inventory and the edges between tests, symbols and properties
mutation.jsonMutation counts and mutants, each with the tests that cover it (coveredBy) and kill it (killedBy)
pbt.jsonEach property-based test with status, seed, run count, counterexample, shrink path and replay command
claims.jsonFormal claims: kind, status, engine and version, assurance, assumptions, scope, semantic gaps, solver input and output files, the counterexample and its JavaScript reproduction
proofs/For Z3: <claim-id>.smt2 (the query), <claim-id>.out (the solver output) and <claim-id>.replay.json (the replay in JavaScript), plus range and bound checks for some claims. For Lean: proofs/lean/<claim-id>/, a Lake project
assessments.jsonOne assessment per test: the evidence vector, the outcome and the unknowns
findings.jsonFindings with kind, title, severity, certainty, locations, and the properties and sources behind them
artifact-index.jsonFiles that cannot carry an envelope, with path, kind, SHA-256, size and creation time
trace.jsonlOne JSON object per log event (time, level, message, and fields such as event and stage), at most 4 MB; a final line says how many events were dropped

Veritas keeps the most recent storage.retainRuns finished runs (default 20) and deletes older ones when a run finishes. Runs still in progress are not deleted.

Other files under .veritas/:

PathContent
.veritas/config.jsonConfiguration (see Configuration)
.veritas/approvals.jsonAppend-only decisions on properties: who, when, what and why
.veritas/improvements/<plan-id>/plan.json, and for each apply approval-<n>.json and attempt-<n>.json
.veritas/generated-tests/Files written by veritas test generate
.veritas/cache/Signed, content-addressed cache of decisive solver results, LLM responses and mutation runs

Envelope metadata ​

The JSON files Veritas writes for a run (all except report.json and mutator's own files) are envelopes { "meta": { ... }, "data": ... }:

json
{
  "meta": {
    "schemaVersion": "1.0.0",
    "runId": "run-20261120T100618836Z-000-1951f4",
    "toolVersion": "0.1.2",
    "gitCommit": "8a0dfe77e920c63934c08149b2f0a7aa67aecaa0",
    "configHash": "26b755aea2820bc824e016aaa6c9c6a663f172075da0d22a449ae19ea1af9255",
    "sourceHash": "64bf135f24766bd2b631d31b80625951a3629b2c23f7d0b0deacc76437082b6b",
    "createdAt": "2026-11-20T10:06:20.072Z"
  },
  "data": []
}
FieldMeaning
schemaVersionVersion of the artifact schemas
runIdThe run that wrote the artifact
createdAtWhen the artifact was written (ISO 8601, UTC)
toolVersionVeritas version
gitCommitHEAD of the analysed repository, or null without git
configHashHash of the validated configuration
sourceHashHash of the indexed source files

Files that cannot hold an envelope (solver input and output, Lean sources, rendered reports, mutator's own report files) are listed in artifact-index.json with their SHA-256, and the index carries the metadata. The rendered reports show it too. readArtifact in the Node API validates a file against its schema and rejects it if it does not match.

JSON Schemas ​

The JSON Schemas of the configuration and of the records in the artifacts are in schemas/ in the repository:

SchemaDescribes
config.json.veritas/config.json
artifact-meta.jsonThe envelope metadata
run.json, stage-result.jsonA run and its stage results
capability.jsonA capability reported by veritas doctor
evidence-source.jsonA collected source
property.json, property-ir.jsonA property and its formal model (Property IR)
test-case.json, test-property-edge.jsonA test and its relations to properties
mutant.jsonA mutant
formal-claim.jsonA formal claim
test-assessment.jsonA test assessment
finding.jsonA finding
approval-ledger.json.veritas/approvals.json
improvement-plan.json, patch-attempt.jsonAn improvement plan and an apply attempt

The design is explained in ADR 0002.

Redaction ​

Secrets are removed before anything is written to an artifact, a report, a log or the trace, and again when veritas report prints, an MCP tool returns, or the GitHub Action writes its outputs and step summary. Redaction replaces with [REDACTED]:

  • common token formats: Anthropic and OpenAI keys (sk-ant-..., sk-...), GitHub tokens (ghp_..., github_pat_... and the other gh*_ prefixes), AWS access key ids, Slack tokens and PEM private keys;
  • assignments such as token=..., password: ... and api_key=..., credentials in URLs (https://user:pass@host) and Authorization header values;
  • the values of environment variables whose names contain TOKEN, SECRET, PASSWORD, API_KEY, PRIVATE_KEY or CREDENTIAL (values of at least 8 characters);
  • the arguments of secret command-line flags such as --token or --api-key in recorded commands.

Logs and traces never include environment values or file contents. Prompts sent to an LLM are not stored (storage.storePrompts accepts only false).

Released under the Apache-2.0 License.