AGENTS.md — .attestations/ (signed probe attestation chain)

Working agreement for AI agents touching the Ed25519-signed attestation chain.

What this is

.attestations/ contains the signed daily probe attestation chain — every datapulse-my release carries a chain_head.json that cryptographically proves which datasets were probed at the time of release. Each release's chain head = the SHA-256 of (previous chain head || dataset_links_sha256 || dataset_count || date). Each chain head is signed with the project's Ed25519 keypair.

Why this matters: M8ven grades this positively (secret flow analysis, signed probe attestation chain checks). The release pipeline (.github/workflows/release-please.yml) asserts the chain head is stamped on each release; a broken chain breaks release attestation.

Public verification: anyone with the public key (in .well-known/datapulse-probe-keys.json) can verify a release's attestation. The keypair is split: private key in DATAPULSE_ATTESTATION_PRIVATE_KEY_FILE (a GitHub Actions secret), public key in the repo.

Hard rules

1. chain_head.json is generated, never hand-edited. Manual edits will not match the cryptographic history; the release pipeline will detect the inconsistency and reject the release.
2. The only writer to .attestations/ is scripts/gen_attestations.py. Don't write new scripts that touch this directory; extend gen_attestations.py if new outputs are needed.
3. Re-running gen_attestations.py with different inputs produces a different chain head. That's expected and correct. The chain advances on every daily run; the previous chain head is the input to the next.
4. The Ed25519 keypair is generated by scripts/init_keys.py. Don't re-roll keys without operator approval. Key rotation breaks all historical attestation verification — the public key in .well-known/ would need to be updated in lockstep, AND any external verifiers would need to migrate.
5. All chain outputs are deterministic given (private_key, date, previous_chain_head, dataset_set). If two runs of the same input produce different chain heads, the keypair was rolled mid-run — surface this to the operator immediately.

File map

.attestations/
├── AGENTS.md                 # this file
├── chain_head.json           # current head: { date, previous_chain_head, dataset_count, dataset_links_sha256, signature }
└── latest/                   # daily digest envelopes (one per day, immutable)
    ├── 2026-08-15.json       # { date, attestations: [...], chain_head }
    ├── 2026-08-16.json
    └── ...

Chain structure (canonical)

{
  "schema": "datapulse/v1/daily-chain-head-envelope",
  "payload": {
    "schema": "datapulse/v1/daily-chain-head",
    "date": "2026-08-15",
    "previous_chain_head": "0000...0000",   // "0" * 64 for the genesis
    "dataset_count": 389,
    "dataset_links_sha256": "e3852d..."      // hash of sorted manifest links
  },
  "signature": "<base64 Ed25519 over canonical(payload)>"
}

Canonical form: json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")). Any change to this canonical form breaks signature verification across all historical attestations.

Regeneration contract

scripts/gen_attestations.py is invoked daily by the datapulse-attest-daily systemd timer via ~/dotfiles/scripts/datapulse-attest-daily.sh (after datapulse-health.service). It:

1. Reads health/latest.json (current probe results)
2. Reads the current chain_head.json (previous_chain_head input)
3. Reads the Ed25519 private key from DATAPULSE_ATTESTATION_PRIVATE_KEY_FILE
4. Computes the new chain head
5. Signs it
6. Writes .attestations/latest/<date>.json (immutable daily digest)
7. Updates .attestations/chain_head.json (mutable head pointer)

Never: re-run for the same date (overwrites the daily digest, breaks the audit trail). The --quick-test flag skips signing and uses a known-private test key — never run --quick-test against production chain_head.json.

Public verification

External verifiers can verify a release's attestation with:

# Pseudocode for an external verifier
public_key_pem = requests.get("https://data-pulse.my/.well-known/datapulse-probe-keys.json").json()["active"]
envelope = json.loads(open(".attestations/latest/<release-date>.json").read())
verify(
    public_key_pem,
    canonical(envelope["payload"]),       # canonical form, NOT pretty-printed
    base64.b64decode(envelope["signature"])
)

The canonical(payload) form is the same as gen_attestations.py uses. External verifiers depend on this exact form being stable. Any change to canonical-JSON serialisation breaks compatibility.

What is NOT in .attestations/

• The public key registry — that's .well-known/datapulse-probe-keys.json at the public endpoint, generated by init_keys.py and committed to the repo root
• Historical chain heads — they're captured in the daily digests (latest/<date>.json) as previous_chain_head; the current chain_head.json only holds the latest
• The signing key itself — DATAPULSE_ATTESTATION_PRIVATE_KEY_FILE (GitHub Actions secret), never in the repo

Out of scope

• Switching the signature algorithm (Ed25519 → ECDSA, RSA, etc.) — would break every external verifier. Operator decision only.
• Adding per-dataset attestation granularity — the current chain is one digest per day across all datasets. Per-dataset attestation is a separate feature.
• Tampering with the chain head to "fix" a release — that's the trust claim this entire repo depends on. Surface any apparent chain-head inconsistency to the operator; do not patch.

Pre-flight checklist (for dispatch briefs)

When writing a codex brief that touches .attestations/ or gen_attestations.py:

• What's the cryptographic change? brief must describe the algorithm/serialisation/canonical-form change
• What's the backwards-compat plan? every external verifier depends on the current shape
• Does the brief involve the signing key? brief must name the env var path and forbid print(private_key_bytes) / print(signature_bytes) etc.
• Does the change affect canonical JSON form? STOP and surface to operator first; this breaks external verifiers
• What does the release pipeline assertion need to know? brief must mention assert_and_publish_attestation_anchor in .github/workflows/release-please.yml
• Workdir: absolute path to this repo