# `Tay.Storage.Segment`
[🔗](https://github.com/AndriiSydorenko1904/tay/blob/v1.6.1/lib/tay/storage/segment.ex#L1)

Physical v1 segment container. See the Phase 2 segment RFC for the byte contract.

Checksums, framing, and sequence continuity establish physical integrity only.
No result authorizes repair, semantic replay, or an applied checkpoint.

# `footer`

```elixir
@type footer() :: %{
  id: pos_integer(),
  first_sequence: pos_integer(),
  last_sequence: pos_integer(),
  count: pos_integer(),
  store_id: <<_::128>>,
  segment_crc: non_neg_integer()
}
```

# `footer_decode_error`

```elixir
@type footer_decode_error() ::
  :checksum
  | :count_sequence_relation
  | :invalid_argument
  | :invalid_crc
  | :invalid_first_sequence
  | :invalid_last_sequence
  | :invalid_magic
  | :invalid_record_count
  | :invalid_segment_id
  | :invalid_store_id
  | :reserved_bytes
  | :trailing_footer_bytes
  | {:invalid_version, 0}
  | {:unsupported_flags, byte()}
  | {:unsupported_version, byte()}
  | {:mismatch, atom(), term(), term()}
```

# `footer_decode_result`

```elixir
@type footer_decode_result() ::
  {:ok, footer()} | {:incomplete, 64} | {:error, footer_decode_error()}
```

# `footer_encode_error`

```elixir
@type footer_encode_error() ::
  :count_sequence_relation
  | :invalid_argument
  | :invalid_crc
  | :invalid_first_sequence
  | :invalid_last_sequence
  | :invalid_record_count
  | :invalid_segment_id
  | :invalid_store_id
```

# `header_decode_error`

```elixir
@type header_decode_error() ::
  store_decode_error()
  | :invalid_first_sequence
  | :invalid_segment_id
  | {:mismatch, :id | :store_id, term(), <<_::128>> | pos_integer()}
```

# `header_decode_result`

```elixir
@type header_decode_result() ::
  {:ok,
   %Tay.Storage.Segment{
     bytes: term(),
     count: term(),
     crc_state: term(),
     digest: term(),
     first_sequence: term(),
     footer: term(),
     id: term(),
     identity: term(),
     last_sequence: term(),
     state: term(),
     store_id: term()
   }}
  | {:incomplete, 44}
  | {:error, header_decode_error()}
```

# `parse_result`

```elixir
@type parse_result() ::
  {:error, map()}
  | {:ok,
     %Tay.Storage.Segment{
       bytes: term(),
       count: term(),
       crc_state: term(),
       digest: term(),
       first_sequence: term(),
       footer: term(),
       id: term(),
       identity: term(),
       last_sequence: term(),
       state: term(),
       store_id: term()
     }}
  | {:ok,
     %Tay.Storage.Segment{
       bytes: term(),
       count: term(),
       crc_state: term(),
       digest: term(),
       first_sequence: term(),
       footer: term(),
       id: term(),
       identity: term(),
       last_sequence: term(),
       state: term(),
       store_id: term()
     }, term()}
```

# `reduce_result`

```elixir
@type reduce_result(acc) ::
  {:error, map()}
  | {:ok,
     %Tay.Storage.Segment{
       bytes: term(),
       count: term(),
       crc_state: term(),
       digest: term(),
       first_sequence: term(),
       footer: term(),
       id: term(),
       identity: term(),
       last_sequence: term(),
       state: term(),
       store_id: term()
     }, acc}
```

# `store_decode_error`

```elixir
@type store_decode_error() ::
  :checksum
  | :invalid_argument
  | :invalid_magic
  | :invalid_store_id
  | :reserved_bytes
  | :trailing_store_bytes
  | {:invalid_version, 0}
  | {:unsupported_flags, byte()}
  | {:unsupported_version, byte()}
```

# `decode_footer`

```elixir
@spec decode_footer(term(), term()) :: footer_decode_result()
```

# `decode_header`

```elixir
@spec decode_header(term(), term()) :: header_decode_result()
```

# `decode_store`

```elixir
@spec decode_store(term()) ::
  {:ok, <<_::128>>} | {:incomplete, 28} | {:error, store_decode_error()}
```

# `encode_footer`

```elixir
@spec encode_footer(term()) :: {:ok, <<_::512>>} | {:error, footer_encode_error()}
```

# `encode_header`

```elixir
@spec encode_header(any()) ::
  {:error,
   :invalid_argument
   | :invalid_first_sequence
   | :invalid_segment_id
   | :invalid_store_id}
  | {:ok, <<_::32, _::_*8>>}
```

# `encode_store`

```elixir
@spec encode_store(any()) :: {:error, :invalid_store_id} | {:ok, <<_::32, _::_*8>>}
```

# `filename`

```elixir
@spec filename(any()) :: {:error, :invalid_segment_id} | {:ok, <<_::32, _::_*8>>}
```

# `filename_id`

```elixir
@spec filename_id(any()) ::
  {:error, :invalid_segment_id | :invalid_segment_name} | {:ok, integer()}
```

# `max_bytes`

```elixir
@spec max_bytes() :: pos_integer()
```

# `max_count`

```elixir
@spec max_count() :: pos_integer()
```

# `max_id`

```elixir
@spec max_id() :: pos_integer()
```

# `min_rotation_bytes`

```elixir
@spec min_rotation_bytes() :: pos_integer()
```

# `parse`

```elixir
@spec parse(binary(), keyword()) :: parse_result()
```

Validates a complete in-memory segment without retaining its records.

# `reduce`

```elixir
@spec reduce(term(), term(), acc, term(), keyword()) :: reduce_result(acc)
when acc: var
```

Physical reduction; accumulator is returned only on complete success.

# `reduce_while`

Halt-aware physical traversal; errors never return a successful prefix accumulator.

# `scan`

```elixir
@spec scan(term(), term(), keyword()) :: parse_result()
```

Validates a segment through bounded positional reads. No writes occur.

---

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