Guide

Provenance & privacy

Every run is a signed timeline of snapshots: the working set at run start, each phase, and run end, plus what changed. You choose how much is revealed, per run.

The provenance timeline

At each boundary K-Veritas hashes the tracked files into a Merkle root and links it to the previous one. The chain is bound into the signature, so the timeline (what changed, and when) cannot be edited after sealing. It shows on the report and in the web verifier.

The timeline is cross-platform. The finer activity map (which files a run read, wrote, and which subprocesses it spawned) is Linux-only for now. macOS and Windows are coming.

Disclosure levels

Set the level at init. It controls what the report reveals, never what is committed (integrity is always bound).

redacted (default)	File names are stable pseudonyms (file#1, file#2), with no names and no content. Proves what changed and when without exposing code or filenames.
names (--show-names)	Real file names, but still no file content bundled.
open (--disclosure open)	Real names plus a checkout bundle of the code contents, so anyone can reconstruct any snapshot.

kveritas init                      # redacted (default)
kveritas init --show-names         # real file names, no content
kveritas init --disclosure open    # names + checkout bundle

What a redacted report never contains

No code, file names, datasets, weights, command line, or salt. The server only ever receives a hash to sign. Leaf hashes use a per-file salt that stays on your machine, so a published hash cannot be guessed back to known content.

Withholding files: .kveritasignore

Put gitignore-style patterns in a .kveritasignore file to keep files out of any bundle, for example a secrets directory or a proprietary module:

# .kveritasignore
secrets/
*.key
proprietary_model.py

A withheld file is still committed as a hash-only leaf and listed as withheld, so it can never be silently dropped. Its content never enters a bundle. Secrets like .env and key files are excluded by default.

Committed

Its hash is in the signed tree.

Disclosed

It appears in the report's withheld list.

Never leaked

Its contents are in no report and no bundle.

Reading the report

On kveritas.org/verify a sealed experiment shows the provenance timeline (disclosure level and withheld panel), attested artifacts, and every run. kveritas verify report.pdf prints the same tree.