Veritas

Artifacts and Schemas

This page ties the repo layout to the framework contract.

If you want command syntax, use CLI Reference. If you want sample payloads, use Example Fixtures.

Repo Areas

Repo-Local Generated Artifacts

These are the paths the framework writes into a target repo.

Starter kit from init

Evidence and eval capture

Suggested wiring from apply

The CLI intentionally refuses to write these artifacts outside their reviewable directories unless the path class itself is allowed.

Canonical vs Derived

Canonical records:

Derived read-model artifacts may exist on top of those records. Current example:

Derived artifacts are useful summaries, but they should not become second sources of truth.

Recent governance additions follow that split:

Reference Artifact Types

Adapter

Defined by schemas/veritas-adapter.schema.json.

An adapter owns:

Reference files:

Important distinction:

Graph

Defined by schemas/veritas-graph.schema.json.

The graph contract covers:

Supported node kinds currently include:

Policy pack

Defined by schemas/veritas-policy-pack.schema.json.

A policy pack provides:

Reference file:

Evidence record

Defined by schemas/veritas-evidence.schema.json.

An evidence artifact records:

The framework currently distinguishes three evidence source kinds:

Adapter Proof-Lane Migration

Current adapters use explicit proof-lane objects:

{
  "evidence": {
    "proofLanes": [
      {
        "id": "required-proof",
        "command": "npm run verify",
        "method": "validation",
        "summary": "Runs the repository verification suite."
      }
    ],
    "requiredProofLaneIds": ["required-proof"],
    "defaultProofLaneIds": ["required-proof"],
    "surfaceProofRoutes": [
      {
        "nodeIds": ["verification.tests"],
        "proofLaneIds": ["required-proof"]
      }
    ]
  }
}

Legacy requiredProofLanes, defaultProofLanes, and surfaceProofLanes command arrays are intentionally rejected by runtime validation. Migrate by assigning each command a stable proofLanes[].id, moving the command into proofLanes[].command, and replacing route command arrays with proofLaneIds.

Adapters can also declare family-level proof inventories:

{
  "evidence": {
    "proofFamilyManifests": [
      ".veritas/proof-families/repo-guardrails.families.json"
    ]
  }
}

Those manifests are repo-local inventories. Veritas reports their portable summary as proof_family_results and verification_budget in the evidence artifact.

The portable manifest contract is documented in veritas-proof-family-manifest.schema.json. Runtime validation adds usefulness rules that JSON Schema alone cannot express:

Proof-family results include freshness fields:

veritas budget is the shortest way to inspect the generated verification_budget without opening the full report artifact.

Surface TrustInput block

Every new evidence artifact also includes a surface.input block. That block is the portable Surface TrustInput projection of the Veritas run, not a generated Surface TrustReport.

Veritas owns the repo-specific producer fields. Surface owns generated report fields such as id, generatedAt, summary, faultLines, and proofRequirementsByClaimId. Those report-only fields must not appear under surface.input.

Evidence field Surface mapping Classification
run_id, timestamp, source_ref, source_kind, source_scope Surface input source, claim/evidence/event timestamps, integrity refs, and evidence metadata Surface-mapped
resolved_phase, resolved_workstream, matched_artifacts, affected_lanes, files, unresolved_files Claim and evidence metadata that explains why Veritas selected the surface Surface-mapped
affected_nodes Claim, Evidence, and VerificationEvent records on veritas.affected-surface Surface-mapped
selected_proof_commands, selected_proof_lanes, proof_resolution_source Claim, Evidence, VerificationPolicy, and VerificationEvent records on veritas.proof-lanes Surface-mapped
uncovered_path_result, baseline_ci_fast_passed Proof-lane claim status, verification events, and metadata for proof confidence Surface-mapped
proof_family_results Claim, Evidence, VerificationEvent, and metadata records on veritas.proof-families Surface-mapped
verification_budget A budget claim/evidence pair plus metadata used by Surface report generation Surface-mapped
policy_pack, policy_results Policy-result claims, evidence, events, and policy-violation fault-line hints Surface-mapped
recommendations, false_positive_review, promotion_candidate, override_or_bypass, owner, promotion_allowed Surface metadata and confidence context Surface-mapped
framework, adapter, framework_version Veritas-local producer/runtime metadata Veritas-local
surface Embedded Surface TrustInput projection consumed by Surface adapters and tests Surface-mapped

The schema enforces this boundary with x_surface_mapping metadata on top-level evidence properties. Allowed classifications are mapped, veritas-local, transitional, and deprecated. Fields marked mapped must also declare x_surface_targets, such as claim, evidence, policy, event, metadata, or report-input.

Team profile

Defined by schemas/veritas-team-profile.schema.json.

A team profile controls:

Eval draft and eval record

Defined by:

The draft captures prefilled context without inventing missing judgment. The record captures the completed operator judgment.

Marker benchmark scenario, transcript, and comparison

Defined by:

These benchmark artifacts support deterministic scoring for “did the right context surface at the right time” comparisons:

Marker benchmark suite and suite report

Defined by:

These artifacts support broader benchmark proof:

How The Pieces Fit

The framework flow in this repo is:

  1. init writes a starter adapter, policy pack, team profile, and local README.
  2. report resolves files through the adapter and writes an evidence artifact.
  3. eval draft turns that evidence into a repo-local draft artifact.
  4. eval record turns the evidence or draft into a completed live-eval record.
  5. shadow run orchestrates the report plus eval path and can also run proof first.

The starter guidance surface also includes .veritas/GOVERNANCE.md, which is a committed governance artifact rather than a disposable generated output.

Current Safety Rails

The shipped code currently enforces these boundaries:

Current Reference Files In This Repo

Use these when you want concrete, current examples instead of abstract schema descriptions: