kenshou-cli-0.1.0.0: help/evidence.md
# Verification evidence
`kenshou record RUN-DIR --data-base-uri gs://BUCKET/PREFIX --purpose release --project PROJECT` publishes a finished run's files and adds one record to the OKF verification bundle. The record names the run, cohort, outcome, and SHA-256-pinned object links. It contains no measurements; those remain in the linked run files.
`kenshou record --comparison FILE --data-base-uri gs://BUCKET/PREFIX --purpose release --project PROJECT` records a `kenshou.comparison/v1` document. Every baseline and candidate run named by the comparison must already have a run record in the bundle. The comparison record links the source document by digest and references those run concepts. Supply either `RUN-DIR` or `--comparison FILE`.
The default bundle is `docs/verification`. `--bundle DIR` selects another bundle. A real GCS upload requires `--project PROJECT`, and the command checks that the active gcloud project matches it. `--verify-only` checks that all objects already exist; `--deep-verify` downloads them and checks their bytes. Failed or inconclusive runs link logs automatically; `--link-logs` also links logs for a passing run.
`--config PATH` reads ordered YAML configuration. The supported keys are `evidence.bundle-root`, `gcp.project`, `evidence.data-base-uri`, `evidence.default-subject`, and `evidence.bundle-uri`; the corresponding environment variables are `KENSHOU_EVIDENCE_BUNDLE`, `KENSHOU_GCP_PROJECT`, `KENSHOU_EVIDENCE_DATA_BASE_URI`, `KENSHOU_EVIDENCE_SUBJECT`, and `KENSHOU_EVIDENCE_BUNDLE_URI`. Named flags take precedence over the environment and files. `kenshou evidence check` uses the same bundle default and configuration sources. Unknown keys are rejected.
A dirty harness requires `--allow-dirty` and is recorded with `purpose: investigation` regardless of the requested purpose. Use `--subject MORI-URI` with `--subject-kind project|package` when the default layer project is too broad. Repeat `--produced MORI-URI` for reports caused by this run.
For a local rehearsal, copy the verification bundle outside the repository and pass `--bundle COPY --store-root DIR`. The record still contains `gs://` URIs, while the bytes are stored under the scratch directory. The command refuses `--store-root` with a bundle inside this repository.
`--json` prints one `kenshou.record-result/v1` document and sends errors to standard error. A repeat with the same record content succeeds and reports `already recorded`; different content at the same record path is a conflict.
`kenshou evidence check` checks record paths, IDs, digest and revision shapes, textual fields, event-only keys, timestamps, required data links, comparison arm references and verdicts, and changes to committed records. `--base REF` limits the Git history span. `--network --project PROJECT` checks object size and SHA-256 metadata, and `--deep` downloads bytes to verify each digest. The command exits 0 when clean, 1 for findings, and 4 when it cannot check. `--json` prints one `kenshou.evidence-check/v1` document.
`kenshou history --scenario LAYER/COMPONENT/KIND/NAME --json` reads matching records in time order and emits `kenshou.evidence-history/v1`. Use `--cohort-component PACKAGE[=VERSION|REVISION]`, repeatable `--outcome`, `--since YYYY-MM-DD`, or `--confirmed-only` to narrow the series. Each entry includes linked attestations, a derived trust tier, and the latest earlier confirmed baseline with the same scenario and compatibility key. The history view does not modify the bundle.
`kenshou attest RECORD-OR-ID --project PROJECT` fetches the recorded run or comparison data and writes an immutable attestation with six named checks. For a comparison, it verifies both recorded arms and replays the paired algorithm from their samples under the stored policy. `--offline` skips revision resolution that needs network access; `--linked-only` checks only directly linked objects. It reports `refuted` when fetched data contradicts the record and `incomplete` when a check cannot establish the claim. A scenario oracle must be registered before `verdict-recomputed` can pass for an ordinary run, so generic runs currently remain incomplete. Exit codes are 0 for confirmed, 1 for refuted, 3 for incomplete, 2 for invalid input, and 4 for an operational failure. `--json` emits one `kenshou.attest-result/v1` result document.
A person may annotate an incomplete or refuted attestation with `--accept-anomaly --authority human:ID --reason TEXT` from an interactive terminal. The computed verdict does not change. The command rejects this action in CI or without a terminal.