Skip to content

Configuration ​

This page describes where Veritas reads its configuration, every setting with its default and allowed values, and how the result cache works.

Example ​

.veritas/config.json needs only the settings that differ from the defaults:

json
{
  "$schema": "https://veritas.invalid/schemas/config.json",
  "schemaVersion": "1.0.0",
  "project": { "packageManager": "pnpm", "tsconfig": "tsconfig.json" },
  "analysis": {
    "include": ["src/**/*.ts"],
    "testInclude": ["test/**/*.test.ts"]
  },
  "formal": { "integerDomain": { "min": "-1000000", "max": "1000000" } },
  "pbt": { "numRuns": 500 },
  "policy": {
    "confirmedViolation": "fail",
    "inconclusiveBehavior": "fail",
    "maxNewSurvivors": 0
  },
  "storage": { "retainRuns": 10 }
}
  • analysis.include and analysis.testInclude select the source and test files. veritas init fills them in from what it detects.
  • formal.integerDomain sets the integer range of formal checks. The bounds are decimal strings.
  • policy.inconclusiveBehavior: "fail" makes inconclusive results end with exit code 4, which suits a CI gate.
  • policy.maxNewSurvivors: 0 fails the run when any mutant in scope survives.
  • storage.retainRuns: 10 keeps the ten most recent finished runs; runs still in progress are never removed.

Where configuration lives ​

Veritas reads .veritas/config.json in the project root. veritas init creates it. The file is validated against schemas/config.json; an unknown key or an invalid value fails with CONFIG_INVALID (exit code 2) and lists every invalid field.

You can write the configuration as code instead, in veritas.config.ts, veritas.config.mjs or veritas.config.js in the project root, with the same shape as its default export. Loading it runs project code, so Veritas loads it only with the global --allow-code-config option and otherwise fails with CONFIG_CODE_NOT_ALLOWED. A project may have only one configuration file (CONFIG_AMBIGUOUS otherwise), and a configuration file that is a symbolic link to a location outside the project is refused.

ts
export default {
  project: { packageManager: 'pnpm', tsconfig: 'tsconfig.json' },
  analysis: { include: ['src/**/*.ts'], testInclude: ['test/**/*.test.ts'] },
  policy: { inconclusiveBehavior: 'fail', maxNewSurvivors: 0 },
};

Commit .veritas/config.json and .veritas/approvals.json; the GitHub Action needs the configuration in the repository. Keep .veritas/runs/ and .veritas/cache/ out of version control.

All settings ​

Every setting, with its type, default and allowed values, as validated by schemas/config.json. A setting whose allowed value is marked fixed accepts only that value. unset means the setting has no default value. Unknown keys are rejected.

Top level ​

SettingTypeDefaultAllowed values
$schemastringunset
schemaVersionstring"1.0.0"only "1.0.0" (fixed)

project ​

SettingTypeDefaultAllowed values
project.packageManagerstring"unknown"pnpm, npm, yarn, bun, unknown
project.tsconfigstring or nullnull

sources ​

SettingTypeDefaultAllowed values
sources.localbooleantrue
sources.github.enabledbooleanfalse
sources.github.repostringunsetmatches ^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/(?!\.\.?$)[A-Za-z0-9._-]{1,100}$
sources.web.enabledbooleanfalse
sources.web.allowDomainsarray of string[]items match ^[a-z0-9.-]+$
sources.web.maxPagesinteger30> 0, <= 1000
sources.web.maxDepthinteger1>= 0, <= 5
sources.web.maxCharsinteger200000> 0
sources.web.timeoutMsinteger30000> 0
sources.web.maxDurationMsinteger120000> 0
sources.sendFullTextToLlmbooleanfalse

analysis ​

SettingTypeDefaultAllowed values
analysis.includearray of string (at least 1)["src/**/*.{ts,tsx,js,mjs}"]
analysis.excludearray of string["**/*.generated.*","**/node_modules/**","**/dist/**"]
analysis.testIncludearray of string["**/*.{test,spec}.{ts,tsx,js,mjs}"]
analysis.testFrameworkstring"vitest"only "vitest" (fixed)
analysis.inferSpecsFromCodebooleantrue
analysis.requireApprovalForNormativeClaimsbooleantrueonly true (fixed)

mutation ​

SettingTypeDefaultAllowed values
mutation.backendstring"mizchi"only "mizchi" (fixed)
mutation.modestring"diff"diff, full
mutation.timeoutMsinteger120000> 0

pbt ​

SettingTypeDefaultAllowed values
pbt.numRunsinteger1000> 0, <= 1000000
pbt.seedintegerunset

formal ​

SettingTypeDefaultAllowed values
formal.backendstring"z3"z3, lean
formal.integerDomain.minstring"-10000"matches ^-?\d+$
formal.integerDomain.maxstring"10000"matches ^-?\d+$
formal.maxSolverMsinteger30000> 0
formal.maxArrayLengthinteger3>= 1, <= 8
formal.rejectUnsupportedSemanticsbooleantrueonly true (fixed)

llm ​

SettingTypeDefaultAllowed values
llm.providerstring"none"none, claude, claude-code, openai, codex
llm.modelstringunset
llm.maxTokensPerRuninteger200000>= 0
llm.allowCodexFileReadsbooleanfalse

improvement ​

SettingTypeDefaultAllowed values
improvement.autoApplybooleanfalseonly false (fixed)
improvement.testFilesOnlybooleantrueonly true (fixed)
improvement.maxIterationsinteger3> 0, <= 20
improvement.maxPatchFilesinteger5> 0, <= 50

reports ​

SettingTypeDefaultAllowed values
reports.formatsarray of string["json","markdown","html","sarif"]text, json, markdown, html, sarif

policy ​

SettingTypeDefaultAllowed values
policy.confirmedViolationstring"fail"fail, warn
policy.inconclusiveBehaviorstring"warn"fail, warn, ignore
policy.maxNewSurvivorsintegerunset>= 0
policy.minPropertyCoveragenumberunset>= 0, <= 1

sandbox ​

SettingTypeDefaultAllowed values
sandbox.allowNetworkWithoutIsolationbooleanfalse

storage ​

SettingTypeDefaultAllowed values
storage.retainRunsinteger20> 0
storage.storePromptsbooleanfalseonly false (fixed)

cache ​

SettingTypeDefaultAllowed values
cache.enabledbooleantrue

limits ​

SettingTypeDefaultAllowed values
limits.memoryMbinteger2048>= 256, <= 65536

What the main settings do ​

SettingDefaultEffect
sources.web.enabled, sources.github.enabledfalseCollect evidence from the web or from GitHub. The web source also needs allowDomains; the GitHub source reads sources.github.repo (owner/name). Neither runs with --offline
sources.web.maxPages, maxDepth, maxChars, timeoutMs, maxDurationMs30, 1, 200000, 30000, 120000Limits of the web crawl: pages, link depth, characters kept, time per page, and time for the whole crawl. Pages not fetched in time are reported as skipped
analysis.inferSpecsFromCodetruePropose candidate properties inferred from the code. With false, only documented sources produce properties
mutation.modediffdiff: you are expected to pass --since; without it, all mutants in scope run and the stage messages say so. full: all mutants in scope run, without that message. In both modes, --since limits mutants to changed code
formal.integerDomain-10000 to 10000Integer range of formal checks, within the safe-integer range
formal.maxSolverMs30000Solver time limit per query
formal.maxArrayLength3Longest array (1 to 8) that formal checks cover; longer arrays are not covered
pbt.numRuns, pbt.seed1000, per propertyNumber of property-based test runs, and the seed. Without seed, each property gets a fixed seed derived from its id, so results are reproducible
llm.providernoneLLM used to read free-text statements; see LLM providers. llm.maxTokensPerRun limits the tokens of one run
policy.confirmedViolationfailfail: a confirmed violation ends with exit code 1. warn: it is reported as a warning
policy.inconclusiveBehaviorwarnfail: inconclusive results end with exit code 4. warn and ignore: exit code 0, with the verdict pass_with_warnings and every inconclusive result listed
policy.maxNewSurvivorsunsetExit code 1 when more mutants survive in the run's scope (the changed code with --since). Inconclusive when there are no mutation results
policy.minPropertyCoverageunsetExit code 1 when the share (0 to 1) of accepted properties with a meaningful_with_evidence test is lower. Inconclusive when no property is accepted or the run has no test assessments
sandbox.allowNetworkWithoutIsolationfalseRun project code even without a Node.js 25 or later that can block its network access. Otherwise those results stay inconclusive
storage.retainRuns20Number of finished runs kept in .veritas/runs/, the current run included. Older finished runs are deleted when a run finishes; runs still in progress are kept
cache.enabledtrueReuse results from .veritas/cache/ (see Caching)
limits.memoryMb2048Memory limit (MiB, at least 256) for processes that run project code, the project's tests, mutator and Z3. Lean is not limited. Running out of memory is an error

Inconclusive results are claims that are unknown, timeout, unsupported, semantic_mismatch or error, and stages that are partial, skipped, unsupported, timeout or cancelled.

Settings with a single allowed value ​

These settings state a rule and accept only one value. Any other value is an invalid configuration.

SettingOnly valueRule
analysis.requireApprovalForNormativeClaimstrueA property becomes accepted only through a recorded decision
improvement.testFilesOnlytrueimprove only adds test files and never edits production code
improvement.autoApplyfalseA plan is applied only with --apply, its plan id and its approval token
storage.storePromptsfalsePrompts sent to an LLM are not stored
formal.rejectUnsupportedSemanticstrueCode outside the formal subset is unsupported, never approximated
analysis.testFrameworkvitestVitest is the supported test runner
mutation.backendmizchi@mizchi/mutator runs mutation testing

Caching ​

Veritas keeps three kinds of results in .veritas/cache/ and reuses them when the inputs are identical:

ResultReused when these are identical
Decided Z3 results (sat, unsat)The SMT query, the solver build and the time limit
Successful LLM responsesThe provider, the model and the request
Complete mutation runsThe content of every file git ls-files lists, the mutator, Vitest and Node.js versions, the configuration, --since and the scope

Undecided or failed results are not reused. A reused counterexample is still replayed in JavaScript, and the stage messages say when a result was reused. Without git, mutation results are not cached.

Entries are signed with a key stored outside the project, in ~/.cache/veritas/cache-key (%LOCALAPPDATA%\veritas\cache-key on Windows) or the file named by VERITAS_CACHE_KEY_FILE. Entries signed with a different key, for example ones copied in with a repository or restored on a CI runner without the key, are ignored. A cache directory tracked by git is ignored as a whole.

The project's own tests, which mutation testing runs, can read the key. For code you do not trust, set cache.enabled: false (see Security model).

Released under the Apache-2.0 License.