shards: integrity & lineage-correctness (sign, collapse revisions, no default-fill bias)

[aaronmarkham]

Summary

Tightens how zeitghost uses the spiritwriter shard substrate, in three related ways that make the provenance / integrity story the landing page tells actually true for zeitghost's own output. Came out of an audit of the ingest → analyze → shard write/read path against what spiritwriter.fabric exposes.

1. Opt-in Ed25519 shard signing (#4)

• article_to_internal_shard / article_to_sw_shard take a new signing_seed and call shard.sign() before store.put when one is supplied.
• resolve_signing_seed() reads ZEITGHOST_SIGNING_KEY via spiritwriter.secrets (OS keychain first, then env-var fallback — so the headless us-ny1 builder gets its seed from an env var without a keychain).
• Graceful opt-in: no key configured → unsigned shards + a one-line notice, never a failure. CI/dev/local stay green with zero setup.
• New zeitghost gen-signing-key mints a 32-byte seed, stores it in the keychain (--no-store to just print), and reports the signer thumbprint (the identity MemoryShard.verify() checks) plus the seed for mirroring to prod.
• Signing covers {atoms, scope, origin, …} but not the content-address, so shard_id is unchanged — sign-before-put is safe.

2. Load collapses revision chains to latest-per-entity (#2)

load_articles_from_shards previously rendered every shard in scope. The lineage machinery (parent_shard_id via build_lineage_index) means a re-analyzed article forms a revision chain — so the old loader would surface it as duplicate cards the moment a chain formed. Now it keeps the newest shard per entity (latest-wins by created_at, matching how build_lineage_index picks parents). Latent bug fixed before re-analysis is ever enabled.

3. bias_score is skipped, never default-filled (#5)

analyze_article defaulted a missing score to 0.5 (float(data.get("bias_score", 0.5))) — exactly the silent-mislabel-as-"center" that robustness invariant #1 forbids (the legacy importer already skips NULL scores). Now it returns None and skips. Logic extracted to a testable _parse_bias_score helper; a legitimate 0.0 (full left) still passes through.

Cleanup

Factored the repeated "which article is this shard?" lookup into _entity_of, now shared by known_url_entities, build_lineage_index, and the new load path — so dedup, lineage chaining, and render-time collapse all key off the same identity.

Test plan

• python -m pytest tests/ — 46 passed (existing) + new tests/test_shard_integrity.py
• New tests: signing round-trip + verify(), unsigned-by-default, latest-per-entity collapse, distinct-entity separation, _parse_bias_score (incl. the 0.0 edge), resolve_signing_seed (env / absent / malformed-hex / wrong-length)
• Updated test_shard_metadata_round_trip to assert latest-only load
• python -c "import zeitghost" clean from an empty cwd (invariant Replace coming-soon placeholder with real spiritwriter.ai landing page #2 — no import-time I/O; secrets/crypto imports are all lazy/in-function)
• zeitghost gen-signing-key --no-store smoke-tested

Not in scope (rides with the trace-emitter follow-up)

TraceEmitter wiring (shard_created events, trace_ref population, per-run run_id) and surfacing the signer thumbprint in the card flip-panel. This PR makes the bytes signed and the lineage load-correct; the trace chain + UI come next.

🤖 Generated with Claude Code