# `SuperPi.Durable.Storage`
[🔗](https://github.com/oleksandr/super-pi-beam/blob/v0.1.0/lib/super_pi/durable/storage.ex#L1)

Transactional durable storage engine (`SuperPi.Durable.Storage`) implementing:
- Monotonic sequence numbers (`Seq`)
- Conversation creation (with reserved `ROOT_CONVERSATION_ID = 1`) and atomic built-in documents
- Conversation forking at any visible entry with `asOf` rewind of `pi.agent` and fresh `pi.provider` UUIDv7
- Entry appending with `head` markers and `ContextEdit` operations

# `append_entry!`

Appends an immutable entry to `conversation_id`.
Supports `head_entry_id: :self` (used by `pi.reset`) or an explicit integer `EntryId` (used by `pi.compaction`).

# `commit`

Executes a durable commit, first draining any pending deferred updates (`REQ-DUR-05`)
and allocating a monotonic `seq` number.

# `configure_agent!`

Updates the conversation's `pi.agent` rewindable document (`Conversation.configure()`).

# `create_conversation!`

Atomically creates a conversation and initializes its 5 built-in documents:
`pi.agent`, `pi.provider` (UUIDv7), `pi.live`, `pi.inbox`, and `pi.usage`.

# `current_seq`

# `ensure_root_conversation!`

Opens or lazily creates the root conversation (`id = 1`) with its 5 built-in documents (`spec.md` §2.5).

# `fork_conversation!`

Atomically forks `parent_conversation_id` at `at_entry_id` (`spec.md` §2.5, §3.7):
- Copies `pi.agent` `asOf` the target entry's commit `seq`
- Mints a fresh `pi.provider` UUIDv7 (forks never copy parent's provider UUID)
- Initializes fresh `pi.live`, `pi.inbox`, and `pi.usage` documents

# `latest_conversation`

The most recently created top-level conversation (no owning task), or `nil`.
Used by `--continue`.

# `next_seq!`

Allocates and returns the next monotonic sequence number (`Seq`).

One atomic upsert, valid on SQLite and PostgreSQL. The row lock held until
commit serializes concurrent allocators.

# `root_conversation_id`

# `row_locks?`

True when the backend supports `SELECT ... FOR UPDATE`.

# `tx_opts`

Options for `Repo.transaction/2`. SQLite takes the write lock up front
(`BEGIN IMMEDIATE`) so a read-then-write transaction cannot lose a race.

---

*Consult [api-reference.md](api-reference.md) for complete listing*