argand-site-registry/docs/PUBLISHING.md

Dataset publisher runbook

Scheduled acquisition and observation jobs create evidence and candidates. Human reviewers vote on exact bundles. A separate publisher signs and activates an accepted generation.

Prepare trust and state

Keep source caches, captures, writer database, generations, reviewer keys, publisher keys and consumer trust files outside the checkout. A reviewer allowed-signers file contains one principal and public key per line. Add OpenSSH validity options when rotating keys and preserve old keys for retained history.

Create a reviewed policy JSON when the reference policy is not appropriate. The reference policy requires two independent identities, groups and physical keys for every name, edge and equivalence; sticky revocations and publisher separation are mandatory. Record actual group membership in reviewer_groups. Optional risk_thresholds can require a larger quorum for source_conflict or dangerous_drift; blocking those risks remains separately configurable.

Build and inspect a candidate

1. Import only manifests whose source, format, license and typed coverage were checked. Keep the object and acquisition receipt.
2. Build with --reviewer-trust; record the returned receipt pin.
3. Run verify, stats, diff, export-audit and the fixed evaluation corpus.
4. Inspect review-queue, evidence, exact entity/domain reverse lookups and source-separated popularity.
5. Run candidate observations on a bounded schedule and import their manifests. Review drift and revocation-candidates; rebuild after imports.

Queue viewing is read-only. Observation import changes evidence bundles but never route state.

Create authenticated votes

Use prepare-vote for a name or edge, or prepare-equivalence-vote for an exact entity pair. The command writes canonical JSON containing the current evidence and policy digests. Review those exact bytes, then sign them:

ssh-keygen -Y sign -n argand-site-registry-vote \
  -f /secure/reviewer-one vote.json
argand-site-registry verify-vote \
  --generation /data/registry/candidate --pin "$CANDIDATE_PIN" \
  --decision vote.json --signature vote.json.sig \
  --allowed-reviewers /secure/reviewer-allowed-signers \
  --identity reviewer-one
argand-site-registry vote \
  --database /data/registry/import.sqlite \
  --generation /data/registry/candidate --pin "$CANDIDATE_PIN" \
  --decision vote.json --signature vote.json.sig \
  --allowed-reviewers /secure/reviewer-allowed-signers \
  --identity reviewer-one

Repeat with enough independently controlled identities, groups and keys. Use equivalence-vote to append equivalence votes after verify-equivalence-vote. Rebuild and check the compiled decision. Never share one private key under several reviewer names.

An approval expires within 90 days and begins no earlier than writer acceptance. A revocation has no expiry. To restore a revoked subject, every new approval in a complete quorum must list every active revocation ID in supersedes.

Sign and activate

Run all offline gates and the separate network-enabled dependency audit. The publisher identity and physical key must not have supplied any reviewer vote.

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

Record the source-code revision, provider manifest IDs, candidate and reviewed pins, policy and reviewer-trust digests, diff, evaluation report, publisher identity, and activation result in an immutable operator log outside Git. Distribute the complete generation, signature, and independently authenticated publisher trust root. Confirm every consumer received the new revocation state.

For an incident, preserve the suspect evidence, append a signed revocation, rebuild with full history, evaluate, sign and activate. Use revocation-candidates only as review input; it never signs or appends a vote. To protect pinned consumers before the full generation arrives, publish a small cumulative feed under the distinct publisher namespace:

argand-site-registry export-revocations \
  --generation /data/registry/revoked --pin "$REVOKED_PIN" \
  --effective-at 2026-09-13T00:00:00Z --output /data/revocations.json
argand-site-registry sign-revocations \
  --generation /data/registry/revoked --pin "$REVOKED_PIN" \
  --input /data/revocations.json --output /data/revocations.json.sig \
  --key /secure/publisher-key \
  --allowed-reviewers /secure/reviewer-allowed-signers \
  --identity registry-publisher

Signing recomputes the feed from the pinned generation and re-verifies every reviewer vote. Distribute the exact feed, signature, and publisher trust root. When replacing a feed, verify it with the prior feed and signature so a mirror cannot discard a revocation. Refresh feeds before their seven-day deadline. A newer compatible feed can block an older pinned generation, but clearing that block requires installing its exact full generation so the consumer can recompute the authenticated superseding quorum. Follow SECURITY.md for private disclosure and key compromise.