Skip to content

V-L2-L1: per-entity serialisation prevents chain forks (write-path lock) #31

Closed

Description

@hyperpolymath

Context

The provenance chain has no concurrency story. Two writers that
race against the same entity each:

  1. Read the current latest hash for that entity
  2. Call ProvenanceEntry::chain(...) with that hash as previous_hash
  3. Insert their new entry

Both succeed. The chain forks. Nothing in the codebase enforces
single-writer semantics.

What to do

Decide and implement per-entity serialisation. Concretely:

  1. Add a chain_head lookup keyed by entity_id (SQLite table with
    entity_id PRIMARY KEY, head_hash TEXT NOT NULL) updated atomically
    alongside each provenance insert.
  2. The provenance-write code path must, within a single SQL
    transaction:
    • SELECT chain_head WHERE entity_id = ? FOR UPDATE
      (or BEGIN IMMEDIATE on SQLite)
    • Build the new ProvenanceEntry with that head as previous_hash
    • INSERT the new entry
    • UPDATE chain_head SET head_hash = new.hash WHERE entity_id = ?
    • COMMIT
  3. Concurrent transactions on the same entity_id are serialised by
    the DB lock; concurrent transactions on different entity_ids
    proceed in parallel.

For now this lands as a write-path library function in
src/tier1/provenance.rs (or intercept/ once it's real) — not a
daemon. The integration test exercises it directly via the library.

Acceptance

  • chain_head table generated by codegen alongside provenance_log
  • Library function append_provenance(conn, entity_id, op, actor, …)
    that performs the transactional sequence above
  • Property test (proptest or quickcheck): spawn N threads each
    appending K entries against M entities; chain integrity holds
    for every entity (no forks, no skipped previous_hash)
  • Documents the trade-off: serial writes per entity, parallel
    across entities (cites V-L1-B1 threat model section on
    "Sidecar-write adversary")

Activity

  1. hyperpolymath commented on May 16, 2026

    @hyperpolymath
    OwnerAuthor

    Fork-impossibility: design + failing test (draft PR #104)

    Investigating #31 alongside #32 surfaced a defect: as specified,
    the two together make a forked provenance history impossible to
    represent
    , not merely impossible to create adversarially.

    append_provenance already uses BEGIN IMMEDIATE, and
    verisimdb_provenance_chain_head keys on entity_id as PRIMARY KEY —
    a single scalar head per entity. There is no way to record that an
    entity has two valid tips. Legitimate divergence is real: partitioned
    / replicated honest writers and simulation branches (ADR-0006) all
    fork the chain. The integrity property we want is tamper-evidence +
    no silent loss, not linearity.

    Plan (full design: docs/decisions/0010-provenance-forks-are-first-class.adoc)

    • V-L2-L1: per-entity serialisation prevents chain forks (write-path lock) #31 rework: verisimdb_provenance_chain_head (entity_id PK) →
      verisimdb_provenance_chain_heads (PRIMARY KEY(entity_id, head_hash)) — a set of tips. append_provenance keeps
      BEGIN IMMEDIATE (still serialises racing duplicate appends from
      one node) but on linear append removes the parent tip and adds the
      new one; a new append_provenance_fork(conn, entity, from_hash, …)
      adds a head without removing one. verify_chain becomes
      per-branch (walk each head → genesis), so a fork is not conflated
      with tampering.
    • Detection: new fork_points(conn, entity) over a non-unique
      idx_provenance_predecessor(entity_id, previous_hash).
    • Data migration: idempotent CREATE TABLE IF NOT EXISTS +
      INSERT…SELECT copy of the head table guarded by a sqlite_master
      check; old table retained for one release (no destructive step
      ships). verisimdb_provenance_log is unchanged — existing rows
      stay valid.

    A failing-by-design test (tests/provenance_fork_test.rs) writes
    genesis + branch A + a second legitimate child of genesis and asserts
    both branches and two heads persist. It is verified red today:
    the log keeps both child rows but the single-head table collapses
    branch B (head_count 1, expected 2) — exactly this issue's defect,
    in executable form.

    Draft PR (design + failing test, not for merge): #104

  2. added 2 commits that reference this issue on May 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew capability or improvement to existing behaviour

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions