# 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:

```text
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:

```bash
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

```bash
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](../SECURITY.md) for private reporting and key compromise.