Pixir.Compaction (pixir v0.1.0)

Copy Markdown View Source

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.

Summary

Functions

compact(session_id, opts \\ [])

Append a durable history_compaction checkpoint when there is compactable History.

default_tail_events()

Default tail size used for recovery/preflight compactions.

developer_instruction()

Developer instruction for a future model-assisted compaction pass.

dry_run(session_id, opts \\ [])

Plan compaction without appending anything to the Log.

latest_checkpoint_to_seq(history)

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(session_id, events, opts \\ [])

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()

JSON schema for a model-assisted compaction checkpoint.

plan(session_id, opts \\ [])

Build the deterministic compaction plan for a Session.

provider_history(history)

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

render_for_provider(data)

Render compaction data as a Provider input item.

Functions

compact(session_id, opts \\ [])

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

Append a durable history_compaction checkpoint when there is compactable History.

default_tail_events()

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

Default tail size used for recovery/preflight compactions.

developer_instruction()

@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(session_id, opts \\ [])

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

Plan compaction without appending anything to the Log.

latest_checkpoint_to_seq(history)

@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(session_id, events, opts \\ [])

@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()

@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(session_id, opts \\ [])

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

Build the deterministic compaction plan for a Session.

provider_history(history)

@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(data)

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

Render compaction data as a Provider input item.