@spec add_commit_version(binary(), binary()) ::
  {:ok, binary()} | {:error, reason :: term()}

Adds a commit version to an existing transaction.

@spec add_section(binary(), section_tag(), binary()) ::
  {:ok, binary()} | {:error, reason :: term()}

Adds a new section to the transaction.

Returns error if section already exists. Use for adding COMMIT_VERSION section after commit proxy processing.

@spec commit_version(binary()) :: {:ok, binary() | nil} | {:error, reason :: term()}

Extracts the commit version if present.

Returns nil if no COMMIT_VERSION section exists.

@spec commit_version!(binary()) :: binary() | nil

Extracts the commit version from an encoded transaction, raising on error.

This is the bang version of commit_version/1 that raises an exception instead of returning an error tuple.

Returns the commit version binary or nil if no commit version is present. Raises an exception if the transaction is malformed.

@spec decode(binary()) :: {:ok, transaction_map()} | {:error, reason :: term()}

Decodes a tagged binary transaction back to the transaction map format.

Validates all section CRCs and handles missing sections appropriately.

@spec empty_transaction() :: encoded()

Returns a minimal header-only transaction with no sections for version advancement.

This is more efficient than encoding an empty transaction map as it contains only the transaction header with zero sections, making it the smallest possible valid transaction binary.

@spec encode(transaction_map()) :: binary()

Encodes a transaction map into the tagged binary format.

Automatically selects the most compact opcode variants based on data sizes and omits empty sections for optimal space efficiency.

Options

• :include_commit_version - Include placeholder commit version section
• :include_transaction_id - DEPRECATED: Use :include_commit_version instead

@spec extract_section(binary(), section_tag()) ::
  {:ok, binary()} | {:error, reason :: term()}

Extracts a specific section payload by tag without full transaction decode.

@spec extract_sections(binary(), [atom()]) ::
  {:ok, binary()} | {:error, reason :: term()}

Efficiently extracts specific sections from a transaction into a smaller binary transaction.

This is a convenience wrapper around reassemble_sections/3 for the common case of extracting sections without adding new ones.

Parameters

• encoded_transaction: The source transaction
• sections_to_keep: List of section names to keep (:mutations, :read_conflicts, :write_conflicts, :commit_version)

Examples

# Extract just conflict sections for resolver
{:ok, conflict_binary} = extract_sections(transaction, [:read_conflicts, :write_conflicts])

# Extract mutations for log processing
{:ok, mutations_binary} = extract_sections(transaction, [:mutations])

@spec extract_sections!(binary(), [atom()]) :: binary()

Efficiently extracts specific sections from a transaction into a smaller binary transaction.

Same as extract_sections/2 but raises on error instead of returning {:error, reason}.

Parameters

• encoded_transaction: The source transaction
• sections_to_keep: List of section names to keep (:mutations, :read_conflicts, :write_conflicts, :commit_version)

Examples

# Extract just conflict sections for resolver
conflict_binary = extract_sections!(transaction, [:read_conflicts, :write_conflicts])

# Extract mutations for log processing
mutations_binary = extract_sections!(transaction, [:mutations])

@spec metadata_mutation?(Bedrock.Internal.TransactionBuilder.Tx.mutation()) ::
  boolean()

Checks if a mutation affects metadata keys (keys with \xFF prefix).

Returns true if any key in the mutation starts with \xFF. For :clear_range, returns true if either the start or end key has the prefix.

Examples

iex> Transaction.metadata_mutation?({:set, <<0xFF, "foo">>, "value"})
true

iex> Transaction.metadata_mutation?({:set, "user_key", "value"})
false

iex> Transaction.metadata_mutation?({:clear_range, "start", <<0xFF, "end">>})
true

@spec mutations(binary()) ::
  {:ok, Enumerable.t(Bedrock.Internal.TransactionBuilder.Tx.mutation())}
  | {:error, reason :: term()}

Creates a stream of mutations from the MUTATIONS section.

Enables processing large transactions without loading all mutations into memory.

@spec mutations!(binary()) ::
  Enumerable.t(Bedrock.Internal.TransactionBuilder.Tx.mutation())

Streams mutations from the transaction, raising if the transaction is invalid.

Returns a stream of mutations. Use this when you're confident the transaction is valid or want to fail fast on invalid data.

@spec read_conflicts(binary()) ::
  {:ok, {Bedrock.version() | nil, [{binary(), binary()}]}}
  | {:error, reason :: term()}

Extracts read conflicts and read version from READ_CONFLICTS section.

Returns {nil, []} if no READ_CONFLICTS section exists.

@spec read_write_conflicts(binary()) ::
  {:ok,
   {{Bedrock.version() | nil, [Bedrock.key_range()]}, [Bedrock.key_range()]}}
  | {:error, reason :: term()}

Extracts both read and write conflicts in a single pass for optimal performance.

This is more efficient than calling read_conflicts/1 and write_conflicts/1 separately as it only parses the transaction once.

Returns a tuple with read info and write conflicts.

@spec reassemble_sections(binary(), [atom()], %{required(atom()) => binary()}) ::
  {:ok, binary()} | {:error, reason :: term()}

Efficiently extracts specific sections from a transaction and reassembles them into a new transaction.

This avoids the decode-encode cycle by working directly with binary sections. Much faster than extracting data and calling encode/1 again.

Parameters

• encoded_transaction: The source transaction
• sections_to_keep: List of section names to keep in the new transaction (:mutations, :read_conflicts, :write_conflicts, :commit_version)
• new_sections: Map of additional sections to add (e.g. %{commit_version: version_binary})

Examples

# Extract just mutations and add commit version
{:ok, log_transaction} = reassemble_sections(transaction, [:mutations], %{commit_version: version})

# Extract read conflicts and write conflicts for resolver
{:ok, conflict_data} = reassemble_sections(transaction, [:read_conflicts, :write_conflicts], %{})

@spec shard_index(binary()) ::
  {:ok, [{integer(), integer()}] | nil} | {:error, term()}

Extracts the shard index from the SHARD_INDEX section.

Returns a list of {tag, count} tuples indicating how many contiguous mutations belong to each shard. Returns nil if no SHARD_INDEX section exists.

Example

{:ok, [{0, 5}, {1, 3}]} = Transaction.shard_index(encoded_tx)
# First 5 mutations are shard 0, next 3 are shard 1

@spec shard_index!(binary()) :: [{integer(), integer()}] | nil

Extracts the shard index from an encoded transaction, raising on error.

@spec validate(binary()) :: {:ok, binary()} | {:error, reason :: term()}

Validates the binary format integrity using section CRCs.

Each section validates independently using standard CRC validation by recalculating CRC32 over tag + size + payload and comparing with stored CRC.

@spec write_conflicts(binary()) ::
  {:ok, [{binary(), binary()}]} | {:error, reason :: term()}

Extracts write conflicts from WRITE_CONFLICTS section.

Returns empty list if no WRITE_CONFLICTS section exists.