# `Pixir.Compaction`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/compaction.ex#L1)

Durable History compaction.

Pixir keeps the full Log as source of truth, but the Provider does not need every
old Event on every Turn. Compaction records a canonical `history_compaction` Event
that summarizes an older prefix and leaves a recent tail uncompressed. Provider
replay then sends the latest checkpoint plus the tail, so context stays bounded
while resume/fork/debug still read the original Log.

# `compact`

```elixir
@spec compact(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, map()}
```

Append a durable `history_compaction` checkpoint when there is compactable History.

# `default_tail_events`

```elixir
@spec default_tail_events() :: {:ok, pos_integer()}
```

Default tail size used for recovery/preflight compactions.

# `developer_instruction`

```elixir
@spec developer_instruction() :: String.t()
```

Developer instruction for a future model-assisted compaction pass.

Keep this short and contract-like. Detailed shape belongs in `output_schema/0`, and
actual Session facts belong in the per-call input payload.

# `dry_run`

```elixir
@spec dry_run(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, map()}
```

Plan compaction without appending anything to the Log.

# `latest_checkpoint_to_seq`

```elixir
@spec latest_checkpoint_to_seq([Pixir.Event.t()]) :: non_neg_integer() | nil
```

The `to_seq` of the latest compaction checkpoint in `history`, or `nil` when the
Session has never been compacted. Keys context-pressure warning hysteresis
(ADR 0020): a new checkpoint re-arms the warning gate.

# `model_contract`

```elixir
@spec model_contract(String.t(), [Pixir.Event.t()], keyword()) ::
  {:ok, map()} | {:error, map()}
```

Build the instruction, schema, and delimited user payload for model-assisted compaction.
This does not call the network and does not mutate the Log.

# `output_schema`

```elixir
@spec output_schema() :: map()
```

JSON schema for a model-assisted compaction checkpoint.

This intentionally lives in code instead of prompt prose so the Provider path can
enforce the shape with structured outputs when model-assisted compaction is enabled.

# `plan`

```elixir
@spec plan(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, map()}
```

Build the deterministic compaction plan for a Session.

# `provider_history`

```elixir
@spec provider_history([Pixir.Event.t()]) :: [Pixir.Event.t()]
```

Return the Provider-visible History: latest compaction checkpoint plus uncompressed
events after its range. Sessions without compaction pass through unchanged.

# `render_for_provider`

```elixir
@spec render_for_provider(map()) :: String.t()
```

Render compaction data as a Provider input item.

---

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