Aethera/render_3D/third_party/datoviz/spec/release/ARTIFACT_EVIDENCE.md

Release Artifact And Evidence State

Campaign identity and the shared cloud/physical execution model are defined in VALIDATION_CAMPAIGNS.md.

Release automation writes state under:

build/release/<version>/

The directory is build output. It may be deleted and regenerated, but each published RC or final release should copy the important report, checksums, and evidence summary into release notes or the GitHub release.

Candidate State

The canonical local state file is:

build/release/<version>/release-state.json

Required top-level fields:

Field	Meaning
schema	State schema identifier. Current value: datoviz.release-state.v1.
version	Release version without leading v, for example 0.4.0rc1.
tag	Expected tag, for example v0.4.0rc1.
created_at_utc	UTC timestamp for the state write.
commit	Git commit used to create the candidate.
branch	Current branch name when known.
identity	Version values read from package metadata, citation metadata, and C headers.
commands	Command records with argv, return code, duration, log paths, and diagnostics.
artifacts	Source bundle, wheel, report, docs, and checksum metadata.
evidence	Machine evidence records discovered or ingested for this candidate.
gates	Approval gates and their current status.

Command logs should live under:

build/release/<version>/logs/

Command records may include diagnostics and diagnostic_counts. Error diagnostics from Datoviz logs, Vulkan validation output, sanitizer output, crashes, or Python tracebacks are blocking for machine validation even when the command exits with status 0. Warning diagnostics are recorded under machine evidence warnings for maintainer review.

Artifacts generated by the candidate command should live under:

build/release/<version>/artifacts/

Artifact Records

Every artifact record should include:

Field	Meaning
kind	source-bundle, wheel, checksum, notes, docs, or another explicit kind.
path	Local path when available.
name	Artifact filename or external asset name.
bytes	File size in bytes.
sha256	SHA-256 digest.
sha512	SHA-512 digest for source bundles and registry artifacts.
validated	Whether this exact artifact was covered by evidence.

Artifacts are immutable once validation starts. If an artifact checksum changes, validation must be rerun or explicitly discarded.

Machine Evidence

Machine validation should create:

build/release/<version>/evidence/<machine-id>/
  evidence.json
  environment.json
  failures.md
  logs/
  captures/

environment.json should include OS, kernel, CPU architecture, GPU/driver details when available, Python version, compiler, Vulkan loader/runtime details, and Datoviz artifact identity.

evidence.json should include:

Field	Meaning
machine_id	Stable local name chosen by the maintainer.
profile	Validation profile such as quick, rc, full, or manual.
started_at_utc	Start timestamp.
finished_at_utc	Finish timestamp.
artifact_checksums	Checksums of installed wheels/source bundles.
results	Command and check results.
captures	Captured image paths, dimensions, hashes, and visual comparison status.
skips	Explicit skipped checks and reasons.
failures	Blocking or non-blocking failures.

The current thin-slice validator writes this structure through:

just release-validation-pack <version> --wheel <wheel>
just release-machine-validate <version> --wheel <wheel> --profile quick
just release-machine-validate <version> --wheel <wheel> --profile rc
just release-machine-validate <version> --wheel <wheel> --profile full

The validation pack contains validate-quick.sh, validate-rc.sh, validate-full.sh, and validate.ps1 wrappers so physical machines do not need a full repository checkout.

Returned evidence is ingested with:

just release-ingest-evidence <version> path/to/evidence-dir-or-tar

The report matrix is checked with:

just release-report <version> --strict-matrix

The publication safety summary and local checksum files are generated with:

just release-gates <version> --write-artifacts --strict-matrix

This writes build/release/<version>/release-report.md, SHA256SUMS, and SHA512SUMS.

Report Status Values

Use these status values in reports:

Status	Meaning
pass	Required check passed.
fail	Required check failed.
missing	Required evidence is absent.
skip	Check was intentionally skipped for a recorded reason.
known-issue	Failure accepted as a release note known issue.
manual	Requires maintainer inspection or approval.
not-applicable	Platform or artifact does not apply.

Reports should treat fail and missing as blockers unless a maintainer explicitly reclassifies them as known-issue or not-applicable for that release.