Raxol.Harness.Fixture (Raxol v2.6.1)

View Source

Loader + decode shim for versioned JSONL harness fixtures.

A fixture is the recorded bus stream (both tiers — ephemeral item_delta traffic included), not the durable journal (docs/proposals/in-flight/harness-ui-testing/06-projection.md §1.1). Line 1 is a header record; every subsequent line is one serialized %Envelope{} per harness-spec-protocol.md §2/§3.

decode/1 is the stand-in for the real agent-lane codec (which does not exist in code yet — harness-spec-protocol.md §6 describes the eventual single validation seam; Raxol.Agent.Contract from PR #542 is the shipped v0 slice). It is loud-reject: a structurally invalid line produces a typed Raxol.Harness.Fixture.DecodeError, never a best-effort partial parse. load/1 upcasts every envelope on read via Raxol.Harness.Fixture.Upcast.

Summary

Types

decoded()

Functions

decode(line)

Decode one raw JSONL line into a Header or an Envelope.

load(path)

Load a fixture file: decode every line, upcast each envelope's body to the current schema, and assemble a Session. The header must be line 1 and unique; any envelope line failing decode/1 halts the load loud (the offset in the resulting error is the 1-based line number).

Types

decoded()

@type decoded() ::
  Raxol.Harness.Fixture.Header.t() | Raxol.Harness.Fixture.Envelope.t()

Functions

decode(line)

@spec decode(String.t()) ::
  {:ok, decoded()} | {:error, Raxol.Harness.Fixture.DecodeError.t()}

Decode one raw JSONL line into a Header or an Envelope.

Validates shape strictly: the top-level Event.type is checked against the known family-scoped vocabulary (an unknown top-level type is a version mismatch — a loud error per protocol §6). Vocabulary within a known event (e.g. an unrecognized item_type inside a payload) is deliberately NOT validated here — that is a projection-level, graceful- opaque-render concern (06-projection §4.6, N-FWD), out of scope for the decode seam.

load(path)

@spec load(Path.t()) ::
  {:ok, Raxol.Harness.Fixture.Session.t()}
  | {:error, Raxol.Harness.Fixture.DecodeError.t()}

Load a fixture file: decode every line, upcast each envelope's body to the current schema, and assemble a Session. The header must be line 1 and unique; any envelope line failing decode/1 halts the load loud (the offset in the resulting error is the 1-based line number).

Offset integrity: interior blank lines are a :blank_line error (they would desync offset from the physical line number); a trailing final newline is tolerated.