Release and integrity

Three different identities

• dataset_version is only the SHA-256 of the exact canonical hotlines.json bytes. It does not identify generated files or code.
• Each artifact checksum identifies the exact bytes at one path in this release. The deterministic artifact index covers generated /data/, /api/v1/, dataset-change, release-feed, and widget v1 files. It excludes only the artifact index and descriptor themselves to avoid circular identity.
• Build/code versions hash documented finite source sets for the generator, resolver, and widget. They are review aids, not timestamps, signatures, or compatibility guarantees.

The release descriptor's generated_at is null by design. API/data manifests instead retain an ISO build timestamp; SOURCE_DATE_EPOCH is required to reproduce those timestamp-bearing artifacts byte-for-byte. Changed artifact bytes change the index digest and release ID.

The descriptor lists every ordered source path used for each build/code identity. Generator identity covers the static-data generator, metadata report generator, and release-integrity generator; resolver and widget identities each cover their published implementation source.

Verify downloaded bytes

Obtain the descriptor through a channel you trust, download an artifact, then compare its checksum. For example:

curl -fsS https://worldhotlines.org/release/v1/release.json -o release.json
curl -fsS https://worldhotlines.org/api/v1/resolver.js -o resolver.js
shasum -a 256 resolver.js
# Compare with relationships["/api/v1/resolver.js"].sha256 in release.json

These are unsigned checksums. They can detect a byte mismatch after the descriptor is trusted, but cannot authenticate the publisher or prove freshness. No signing keys are managed in this release.

Caching, rollback, and revalidation

The /v1/ URLs are mutable. Respect HTTP cache headers, revalidate the descriptor on a bounded schedule, verify every artifact before promotion, and retain the last reviewed descriptor and artifact set only if your policy permits rollback. A changed release ID with an unchanged dataset version can mean code or generated-artifact changes; review and retest them. A changed dataset version requires data review and refreshed country/record artifacts. On mismatch, stop promotion, keep a safe degraded state, and refetch the descriptor and artifact rather than guessing.