Pixir.Log (pixir v0.1.0)

Copy Markdown View Source

The per-Session Log (ADR 0003 / 0004): an append-only NDJSON file at .pixir/sessions/<id>.ndjson, the single source of truth for a Session.

Only canonical Events are written — one Pixir.Event per line, serialized 1:1. fold/2 replays the file into History: the ordered list of canonical Events (by seq, with file append order as the backstop, per ADR 0004).

Append is the deliberate exception to the temp+rename rule (the file only ever grows and a single Session process serializes writes). Ephemeral Events are never logged.

Summary

Types

history()

Functions

append(event, opts \\ [])

Append a canonical Event to the Session's Log. Ephemeral Events are rejected with a structured error (ADR 0005) — logging one is a programming error.

create_session(session_id, events, opts \\ [])

Create a new Session Log from canonical Events in one atomic write (temp + rename).

exists?(session_id, opts \\ [])

Whether a Log file exists for this Session yet.

fold(session_id, opts \\ [])

Fold the Log into History — the ordered list of canonical Events. A missing Log is an empty History. Returns {:ok, history} or a structured error if a line is unparseable.

path(session_id, opts \\ [])

Absolute path to a Session's Log. Accepts :workspace (default: cwd).

Types

history()

@type history() :: [Pixir.Event.t()]

Functions

append(event, opts \\ [])

@spec append(
  Pixir.Event.t(),
  keyword()
) :: {:ok, Pixir.Event.t()} | {:error, map()}

Append a canonical Event to the Session's Log. Ephemeral Events are rejected with a structured error (ADR 0005) — logging one is a programming error.

Returns {:ok, event} on success.

create_session(session_id, events, opts \\ [])

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

Create a new Session Log from canonical Events in one atomic write (temp + rename).

Unlike append/2, this refuses when the Log already exists and writes the full file at once. Used for fork child Log creation where partial NDJSON must not remain on failure.

exists?(session_id, opts \\ [])

@spec exists?(
  String.t(),
  keyword()
) :: boolean()

Whether a Log file exists for this Session yet.

fold(session_id, opts \\ [])

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

Fold the Log into History — the ordered list of canonical Events. A missing Log is an empty History. Returns {:ok, history} or a structured error if a line is unparseable.

path(session_id, opts \\ [])

@spec path(
  String.t(),
  keyword()
) :: String.t()

Absolute path to a Session's Log. Accepts :workspace (default: cwd).