boundary-trace

Structured event system for deterministic boundary behavior.

boundary-trace is built around structured boundary events. A boundary event records a meaningful state transition in a deterministic boundary system, such as a verification failure, a repair being generated, or a retry being scheduled.

This event stream is the canonical representation of boundary behavior. Console views, JSON logs, and future TUI tools should all consume the same event stream.

Event Model

Every event uses a shared envelope:

• system source of event (for example, llm-contract)
• runId logical boundary execution ID
• ts timestamp in ISO format
• type canonical state transition name
• attempt optional attempt number
• data typed payload for the transition

Boundary Events

The core union models boundary lifecycle transitions:

• run.started
• attempt.started
• output.raw_observed
• output.cleaned
• verification.passed
• verification.failed
• repair.generated
• retry.scheduled
• run.succeeded
• run.failed

Memory Trace

Use createMemoryTrace() to collect events in order for tests, debugging, and comparison.

It returns:

• events collected event array
• sink sink-compatible emitter
• reset() utility for reuse

Fanout Sinks

Use createFanoutSink([...sinks]) to broadcast one event stream to multiple sinks.

This supports attaching memory capture, renderers, and downstream tooling without changing event producers.

Quick start

npm install
npm run example

Boundary Inspector UI

The repository includes a renderer for fast run comprehension:

• left panel: attempt timeline
• center panel: selected event inspector
• right panel: failure + repair details
• raw/structured event toggle
• replay mode
• copy reproduction payload

Run the inspector locally:

npm run inspector:dev