feat(provenance): fork-first-class chain model — ADR-0010 (#31; supersedes #32) (#109)

Implements ADR-0010 (now Accepted). The provenance integrity property
is tamper-evidence + no-silent-loss, NOT linearity: legitimate
divergence (partitioned/replicated/offline writers, simulation
branches) must be representable, persisted, detectable and verifiable.

Schema
- NO `UNIQUE(entity_id, previous_hash)` (#32, superseded): it would
  reject a divergent writer's honest history at insert time. The `hash`
  PRIMARY KEY is the correct duplicate guard (domain-tagged preimage).
- Add non-unique `idx_provenance_predecessor` → O(log n) fork detection.
- `verisimdb_provenance_chain_heads(entity_id, head_hash)` multi-head
  tip set; legacy single-head table kept one release with an idempotent
  `INSERT … SELECT` migration (no destructive DROP ships here).

Behaviour
- `append_provenance`: linear fast-path — extends the unique head;
  errors (not silently collapses) if the entity has >1 head.
- `append_provenance_fork(from_hash)`: extends a specific ancestor,
  *adds* a head without removing one → the entity now has ≥2 tips.
- `fork_points()`: every predecessor with >1 child.
- `verify_chain`: per-branch walk (each tip → genesis) so a forked-
  but-honest entity verifies true while tampering any branch still fails.

codegen `overlay.rs` mirrors the schema (harmful `ux_provenance_chain`
removed); its DDL tests inverted to assert the ADR-0010 contract.

Tests: `tests/provenance_fork_test.rs` rewritten to the 4 ADR-0010
cases (the previously failing-by-design test now passes) +
`exact_duplicate_entry_is_rejected`. Full suite green (107 lib + 9 + 4
+ 2, 0 failed). ADR-0010 Proposed → Accepted.

Closes #31. Supersedes #32 (closed not-planned).

Co-authored-by: hyperpolymath <hyperpolymath@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: hyperpolymath

docs/decisions/0010-provenance-forks-are-first-class.adoc

@@ -8,7 +8,11 @@ Date: 2026-05-16
 
 ## Status
 
-Proposed (design + failing test; tracks #31 and #32)
+Accepted (2026-05-17) — implemented in #31 (multi-head tip set,
+fork-aware append, `fork_points`, per-branch `verify_chain`,
+non-destructive migration). #32 (the `UNIQUE INDEX(entity_id,
+previous_hash)`) is superseded by this ADR and closed not-planned:
+the `hash` PRIMARY KEY is the correct duplicate guard.
 
 ## Context
 

src/codegen/overlay.rs

@@ -185,12 +185,19 @@ fn generate_metadata_table(schema: &ParsedSchema) -> String {
 /// append-only, tamper-evident log (see
 /// `docs/theory/provenance-threat-model.adoc`).
 ///
-/// The `chain_head` table is the per-entity head pointer used for the
-/// write-path lock (V-L2-L1). The UNIQUE INDEX on `(entity_id,
-/// previous_hash)` (V-L2-L2) makes chain forks structurally impossible
-/// — defence in depth for if the lock is ever bypassed.
+/// ADR-0010 (provenance forks are first-class): the `hash` PRIMARY KEY
+/// is the duplicate guard (the preimage covers every tamper-relevant
+/// field). We deliberately do **not** emit `UNIQUE(entity_id,
+/// previous_hash)` (#32, superseded) — that rejects a divergent second
+/// writer's legitimate history at insert time. Instead a **non-unique**
+/// `idx_provenance_predecessor` makes fork *detection* O(log n), and the
+/// chain tip is a *set* (`verisimdb_provenance_chain_heads`): one row
+/// for a linear entity, several when it has legitimately forked. The
+/// legacy single-head `verisimdb_provenance_chain_head` is kept one
+/// release for non-destructive migration. Mirrors
+/// `tier1::provenance::SIDECAR_DDL` (kept in sync).
 fn generate_provenance_table() -> String {
-    "-- Provenance: SHA-256 hash-chained audit trail\n\
+    "-- Provenance: SHA-256 hash-chained audit trail (ADR-0010)\n\
      CREATE TABLE IF NOT EXISTS verisimdb_provenance_log (\n\
      \x20   hash          TEXT PRIMARY KEY,\n\
      \x20   previous_hash TEXT NOT NULL,\n\
@@ -203,19 +210,25 @@ fn generate_provenance_table() -> String {
      \x20   transformation  TEXT,          -- description of transformation applied\n\
      \x20   CHECK (operation IN ('insert','update','delete','transform'))\n\
      );\n\
-     -- V-L2-L2: forbid chain forks at the DB level. Genesis records all\n\
-     -- carry previous_hash='' so this also enforces a single genesis per\n\
-     -- entity.\n\
-     CREATE UNIQUE INDEX IF NOT EXISTS ux_provenance_chain\n\
+     -- ADR-0010 #32 (superseded): NO UNIQUE(entity_id, previous_hash) —\n\
+     -- a fork that cannot be written cannot be detected or audited. The\n\
+     -- non-unique index below makes fork detection O(log n) instead.\n\
+     CREATE INDEX IF NOT EXISTS idx_provenance_predecessor\n\
      \x20   ON verisimdb_provenance_log(entity_id, previous_hash);\n\
      CREATE INDEX IF NOT EXISTS idx_provenance_entity ON verisimdb_provenance_log(entity_id);\n\
      CREATE INDEX IF NOT EXISTS idx_provenance_table  ON verisimdb_provenance_log(table_name);\n\
      \n\
-     -- V-L2-L1: per-entity head pointer. The write path takes a row\n\
-     -- lock here (SELECT … FOR UPDATE / BEGIN IMMEDIATE) so concurrent\n\
-     -- appenders on the same entity serialise; cross-entity appends\n\
-     -- remain parallel. Each successful append updates head_hash in\n\
-     -- the same transaction as the INSERT into verisimdb_provenance_log.\n\
+     -- ADR-0010 #31: chain-tip *set*. `append_provenance` keeps a\n\
+     -- BEGIN IMMEDIATE write so racing duplicate appends on one node\n\
+     -- still serialise; a linear append swaps its single tip, a\n\
+     -- deliberate fork adds a tip without removing one.\n\
+     CREATE TABLE IF NOT EXISTS verisimdb_provenance_chain_heads (\n\
+     \x20   entity_id TEXT NOT NULL,\n\
+     \x20   head_hash TEXT NOT NULL,\n\
+     \x20   PRIMARY KEY (entity_id, head_hash)\n\
+     );\n\
+     -- Legacy single-head table: kept one release for non-destructive\n\
+     -- migration (see tier1::provenance::SIDECAR_DDL). No DROP ships here.\n\
      CREATE TABLE IF NOT EXISTS verisimdb_provenance_chain_head (\n\
      \x20   entity_id  TEXT PRIMARY KEY,\n\
      \x20   head_hash  TEXT NOT NULL,\n\
@@ -532,22 +545,47 @@ mod tests {
         assert!(ddl.contains("actor"));
     }
 
-    /// V-L2-L2: forks are forbidden by a UNIQUE INDEX on
-    /// (entity_id, previous_hash).
+    /// ADR-0010 (#32 superseded): forks are first-class. The fork guard
+    /// is the `hash` PRIMARY KEY (duplicate-rejection); there must be
+    /// NO `UNIQUE(entity_id, previous_hash)` (it would discard a
+    /// divergent writer's legitimate history). A *non-unique*
+    /// predecessor index provides O(log n) fork detection instead.
     #[test]
-    fn test_provenance_table_has_unique_chain_index() {
+    fn test_provenance_table_fork_detection_index_is_not_unique() {
         let ddl = generate_provenance_table();
-        assert!(ddl.contains("UNIQUE INDEX"));
-        assert!(ddl.contains("ux_provenance_chain"));
+        assert!(
+            !ddl.contains("ux_provenance_chain"),
+            "the superseded UNIQUE(entity_id, previous_hash) must not be emitted"
+        );
+        assert!(
+            !ddl.contains("CREATE UNIQUE INDEX IF NOT EXISTS ux_provenance"),
+            "no unique provenance-chain index (ADR-0010)"
+        );
+        assert!(
+            ddl.contains("idx_provenance_predecessor"),
+            "non-unique fork-detection index must be present"
+        );
         assert!(ddl.contains("(entity_id, previous_hash)"));
     }
 
-    /// V-L2-L1: chain_head table exists for per-entity write serialisation.
+    /// ADR-0010 #31: the chain tip is a *set* (multi-head); the legacy
+    /// single-head table is retained one release for migration.
     #[test]
-    fn test_provenance_table_has_chain_head() {
+    fn test_provenance_table_has_multihead_and_legacy_head() {
         let ddl = generate_provenance_table();
-        assert!(ddl.contains("verisimdb_provenance_chain_head"));
+        assert!(
+            ddl.contains("verisimdb_provenance_chain_heads"),
+            "multi-head set table must exist"
+        );
+        assert!(
+            ddl.contains("verisimdb_provenance_chain_head ("),
+            "legacy single-head table retained for migration"
+        );
         assert!(ddl.contains("head_hash"));
+        assert!(
+            ddl.contains("PRIMARY KEY (entity_id, head_hash)"),
+            "multi-head table keyed by (entity_id, head_hash)"
+        );
     }
 
     #[test]