Skip to content

Architecture ​

Veritas answers, for each test, which specification it is derived from, what it observes, which faults it detects, what has been formally checked under which model and bounds, and what remains unknown. The evidence for each answer is written to machine-readable files. This page shows how a run flows through the packages of Veritas and where it stores its data. For what the results mean, see Semantics.

Pipeline ​

text
CLI / Node API / Agent Skill / MCP / GitHub Action
                       |
               Orchestrator (engine)
                       |
    +------------------+-------------------+
Evidence collectors  Code intelligence  Test inventory
    +---------- Specification engine ------+
                        |
                 Property registry
       +----------------+------------------+
 Mutation adapter  Property-based tests  Formal adapter
   (mutator)          (fast-check)        (Z3 / Lean)
       +----------------+------------------+
                 Assessment engine
                        |
               Improvement planner
                        |
        Artifact store / reporters / CI policy

Packages ​

PackageResponsibility
coreDomain schemas, Property IR, artifact store, cache, IDs, policy, exit codes, process runner, path safety, redaction, project detection, init/doctor
cliveritas and veritas-mcp executables, published as @under18dev/veritas; parses arguments and calls package APIs
engineOrchestrator and Node API: runs stages, persists run artifacts, reports, explain, spec helpers; shared by the CLI, MCP server and GitHub Action
spec-discoveryEvidence collectors (local, GitHub, web), provenance graph, normative statement extraction
code-intelligenceTypeScript analysis: exports, signatures, branches, boundaries, side effects
property-engineProperty registry, review state machine, conflicts, approvals
test-inventoryVitest test discovery, assertion analysis, test-symbol-property graph
mutation-adapterRuns the mutation backend and normalizes results
property-testingfast-check generators, seeds, shrinking, replay
formal-coreTypeScript subset to Property IR, claims, semantic validation
solver-z3, solver-leanSolver backends
assessmentEvidence vectors and test outcomes
improvementPlans, approved patches in isolated workspaces, rollback
llm, llm-providers/*Provider-neutral LLM interface and one adapter per provider: llm-providers/claude (Anthropic API), claude-code (Claude Code CLI), openai (OpenAI API), codex (Codex CLI)
reportsText, JSON, Markdown, HTML, SARIF
mcpMCP server
github-actionCI integration

What each part supports is listed in the support matrix.

How the pieces fit ​

  • The CLI, the Node API, the MCP server and the GitHub Action call the same package functions. A command and its API function or MCP tool run the same stages and write the same files; for example, veritas analyze, analyze() and the analyze_tests tool.
  • Each stage reports its own result. A stage that throws ends as error, stages that depend on a failed stage are skipped, and no stage reports success for another one.

Storage ​

PathContent
.veritas/config.json (or veritas.config.{ts,mjs,js} with --allow-code-config)Configuration
.veritas/approvals.jsonHuman decisions on properties: who, when, what, why
.veritas/runs/<run-id>/Per-run artifacts: evidence, properties, test map, mutants, solver input/output, patches, reports
.veritas/cache/Content-addressed cache of decisive solver results, LLM responses and mutation runs; ignored if tracked by git
.veritas/improvements/<plan-id>/Improvement plans, approvals and apply attempts
.veritas/generated-tests/Property-based test files written by veritas test generate

Each JSON artifact is an envelope with schemaVersion, runId, createdAt, toolVersion, gitCommit, configHash and sourceHash (ADR 0002). Files that cannot hold an envelope (solver input and output, Lean sources, rendered reports, the mutator's own report files) are listed in artifact-index.json with their SHA-256, and that index carries the metadata; the rendered reports also show it. JSON Schemas are in schemas/. See Reports and artifacts for every file of a run.

Exit codes ​

CodeMeaning
0Success
1Confirmed policy failure
2Invalid configuration or user error
3Tool or infrastructure error (including commands not available in this build)
4Inconclusive under the configured policy

With --json, stdout carries only JSON; logs go to stderr. See the CLI reference for verdicts.

Released under the Apache-2.0 License.