Deterministic Lineage

In sovseal, agent state is not stored as mutable rows. Instead, it is represented as an append-only Directed Acyclic Graph (DAG) of immutable snapshots. Every snapshot contains a cryptographic reference to its parent snapshot, creating a tamper-evident lineage chain.

Snapshot Identity

The identity of a snapshot is represented by its snapshot_id, which binds the current payload to the entire historical lineage:

snapshot_id = sha256(canonicalize(payload) || parent_snapshot_id)

Because the parent_snapshot_id is included in the hash preimage, any modification to a past snapshot propagates forward, breaking the hash of all descendants. This makes the lineage structures structurally tamper-evident.

Concurrent Writes & HEAD Pointer Semantics

When multiple operations or agent threads write to the memory layer concurrently:

1. Local State Locking: The SDK coordinates write access by placing a file-system lock on the local LanceDB index, preventing write collisions.
2. Monotonic Sequences: Writes are executed sequentially. Each write operation fetches the current HEAD snapshot ID, creates a new snapshot pointing to it as the parent, increments the sequence_number monotonically per (agent_id, owner_wallet), and updates HEAD to the new snapshot_id.
3. Queue Serialization: Background replication processes do not block writes. If concurrent operations write to the same logical key, the lineage chain naturally captures them as sequential snapshots.

Rollback vs. Fork Operations

The DAG structure allows agents to navigate time without losing historical data.

   snapshot₀ (genesis)
        │
        ▼
   snapshot₁ ─── store("framework", "vitest")
        │
        ▼
   snapshot₂ ─── store("editor", "neovim") (Old HEAD)
        │
        ├──────────────────────┐
        ▼ (rollback)           ▼ (fork)
   HEAD := snapshot₁       snapshot₃ ─── store("framework", "jest")
                           (new branch pointing to snapshot₁ parent)

Rollback

rollback(snapshot_id) updates the client's local HEAD pointer to refer to snapshot_id.

• Non-Destructive: Rollback is an append-only metadata pointer change. The snapshots generated after snapshot_id are not deleted from the local database or replication server; they simply become unreached from the new HEAD path.
• Byte-Equal Restoration: Because every snapshot contains its parent pointer, rolling back to snapshot_id restores the database state to the exact byte configuration it had at that snapshot.

Fork

fork(snapshot_id) initializes a new state branch using snapshot_id as the parent.

• Multi-Agent Topologies: Multiple agents can fork from the same snapshot to explore alternate reasoning trees or execute parallel tasks.
• Coordination-Free: Because each fork generates snapshots with unique content hashes, agents can write to their respective branches without network coordination or merge conflicts.

SDK Crash Recovery

If the host machine loses power or the agent process crashes mid-operation:

• Index Reconstruction: On startup, the SDK reads the local LanceDB transaction log, starting from the last known checkpoint, and validates the parent-hash chain up to the last written snapshot.
• Outbox Reconciliation: The background replication outbox (stored in the local database) is verified. Any snapshots that were written locally but not yet acknowledged by the remote replication server are automatically re-queued for sync.
• Fail-Safe HEAD: The HEAD pointer is restored to the latest snapshot that successfully passed the local integrity validation check.

Interaction with Write-Behind Replication

The write-behind replication worker respects the lineage DAG:

• Outbox Queueing: When a write occurs, the snapshot is marked as pending_replication in the local outbox.
• Batch Ordering: Batches sent to the server preserve parent pointers. If the replication server receives snapshots out of order (due to network re-routing), it stores them in a temporary holding queue until their parents arrive.
• Idempotency: If the server receives a duplicate snapshot (e.g., when the client retries a successful write after a network timeout), the server drops the duplicate without breaking the lineage.