argand-site-registry/docs/PUBLISHING.md

Dataset publisher runbook

This runbook creates a reviewable candidate and a signed activation. Source update, review and release keys are separate authorities. Scheduled jobs may acquire, import and build candidates; they do not approve, sign or activate destinations.

Trust roots and local state

Keep cache, mutable store, immutable generations, reviewer keys, release keys and consumer trust files outside the checkout. An OpenSSH reviewer trust file contains one accepted principal and public key per line:

operator@example.org ssh-ed25519 REVIEWER_PUBLIC_KEY

Distribute the release publisher public key to consumers through an independent authenticated channel. Do not put private keys, production trust files or source datasets in Git or CI. The isolated source CI runner has none of these files.

Candidate acceptance

Run update or the explicit download/import/build commands from the operator guide. For every candidate generation:

1. Verify its externally recorded receipt pin with verify.
2. Run stats and compare source snapshots, selected sources, facts, rejections, reviews, database bytes and upcoming expiry with the prior accepted generation.
3. Run diff against the prior pin. Investigate every source-selection, identity, name, property, edge, popularity, review and equivalence change.
4. Use lookup, entity, lookup-web, popularity and category to inspect exact source evidence and conflicts. Popularity never proves ownership.
5. Replay the maintained evaluation corpus with evaluate; require zero judgment mismatches and compare latency with a documented hardware/process baseline.

Authenticated decisions

Create a bounded review JSON from the exact candidate fingerprint and evidence. Sign its exact bytes and append it through the CLI:

ssh-keygen -Y sign -n argand-site-registry-review \
  -f /secure/reviewer-key review.json
argand-site-registry review --database /data/registry/import.sqlite \
  --generation /data/registry/candidate --pin "$CANDIDATE_PIN" \
  --decision review.json --signature review.json.sig \
  --allowed-reviewers /secure/reviewer-allowed-signers \
  --identity operator@example.org

Identity equivalence decisions use the same signed JSON and reviewer namespace. Rebuild after appending decisions, then repeat the complete diff and evaluation. The release command re-verifies every retained reviewer signature against the current reviewer trust file. Missing, altered or no-longer-trusted proofs stop it.

Sign and activate

argand-site-registry sign --generation /data/registry/reviewed \
  --pin "$REVIEWED_PIN" --key /secure/release-key \
  --allowed-reviewers /secure/reviewer-allowed-signers
argand-site-registry activate --generation /data/registry/reviewed \
  --current /data/registry/current.json \
  --allowed-signers /secure/release-allowed-signers \
  --identity registry-publisher

Record the source commit, candidate and accepted receipt pins, typed diff, evaluation report, reviewer trust-file digest, release signer identity and activation receipt in an immutable operator log. Activation refuses a rollback that drops a distributed revocation. Deliver a new current pointer/pin to every consumer and bound their caches.

For an incident, append a signed revocation, rebuild with full history, inspect, evaluate, sign and activate. Preserve the suspect source bytes, generation and proofs. Follow SECURITY.md for private reporting and key compromise.