@spec apply_one_transaction!(mvcc :: t(), Bedrock.DataPlane.Transaction.encoded()) ::
  :ok

Apply a single transaction to the given table, atomically. Returns :ok if the transaction was applied successfully.

@spec apply_transactions!(
  mvcc :: t(),
  transactions :: [Bedrock.DataPlane.Transaction.encoded()]
) :: Bedrock.version()

@spec apply_transactions!(t(), [Bedrock.DataPlane.Transaction.encoded()]) :: :ok

Apply a series of transactions to the given table and return the id of the last transaction applied. Transaction IDs must be ever-increasing. Though each transaction is applied atomically, it's possible that reads will be interleaved between them.

If any of the transactions fails to apply, an exception will be raised.

@spec fetch(mvcc :: t(), Bedrock.key(), Bedrock.version()) ::
  {:ok, Bedrock.value()} | {:error, :not_found}

@spec fetch(t(), Bedrock.key(), Bedrock.version()) :: Bedrock.value() | :not_found

Lookup the value for the given key/version. The exact version, or the next- oldest will be returned. Values for the key newer than the given version will not be considered. If no suitable keys are found, then {:error, :not_found} will be returned.

This is useful for providing a consistent view of the data at a given point in the transaction timeline.

@spec insert_read(
  mvcc :: t(),
  Bedrock.key(),
  Bedrock.version(),
  Bedrock.value() | nil
) :: :ok

@spec insert_read(t(), Bedrock.key(), Bedrock.version(), Bedrock.value() | nil) :: :ok

Store a key/value pair in the table, at the given version. If the key already exists, then nothing will happen. This value will be returned by subsequent calls to lookup/3, but will never be returned as part of a snapshot. This is useful for caching values that are (possibly expensive) to retrieve from permanent storage.

No error checking is performed on the version.

@spec newest_version(mvcc :: t()) :: Bedrock.version() | nil

Get the last transaction version performed on the table. If no transaction has been performed then nil is returned.

@spec oldest_version(mvcc :: t()) :: Bedrock.version() | nil

Get the oldest possible transaction that can be read by the system. All transactions prior to this will have been coalesced.

@spec purge_keys_older_than_version(mvcc :: t(), Bedrock.version()) ::
  {:ok, n_purged :: pos_integer()}

@spec purge_keys_older_than_version(t(), Bedrock.version()) :: :ok

Purge all keys/versions (and values) that are older than the given version.

@spec transaction_at_version(
  mvcc :: t(),
  version :: :latest | Bedrock.version()
) :: Bedrock.DataPlane.Transaction.encoded() | nil

@spec transaction_at_version(t(), :latest | Bedrock.version()) ::
  Bedrock.DataPlane.Transaction.encoded() | nil

Build a new transaction that encompasses only the latest writes for each key in the table, using the latest version as the cutoff. Since the latest transaction version is updated atomically alongside the transaction values, it's guaranteed that the generated transaction will include all writes that have been applied up until that point, and none that have been applied after.

Returns a transaction tuple. If no transactions have been performed then nil is returned.