runlog

Documentation

Overview

Package runlog is the append-only event log that owns every run's state. One JSONL file per run; sequence numbers are monotone; nothing is ever rewritten. Replaying the log is the only way run state is reconstructed.

Index

• func RunsDir(root string) (string, error)
• type Event
  • func (e Event) Decode(v any) error
• type EventType
• type Log
  • func Create(runsDir, runID string) (*Log, error)
  • func Open(runsDir, runID string) (*Log, error)
  • func (l *Log) Append(t EventType, data any) (Event, error)
  • func (l *Log) Events() []Event

Functions

func RunsDir

func RunsDir(root string) (string, error)

RunsDir returns the runs directory under a root (usually the skill dir or the cwd), creating it if needed.

Types

type Event

type Event struct {
	Seq  int             `json:"seq"`
	Type EventType       `json:"type"`
	At   time.Time       `json:"at"`
	Data json.RawMessage `json:"data,omitempty"`
}

Event is one appended fact. Seq is monotone from 1 within a run.

func (Event) Decode

func (e Event) Decode(v any) error

Decode unmarshals an event's data into v.

type EventType

type EventType string

const (
	RunStarted         EventType = "run.started"
	OperationRequested EventType = "operation.requested"
	OperationCompleted EventType = "operation.completed"
	ResponseRejected   EventType = "response.rejected"
	RequirementPassed  EventType = "requirement.passed"
	RequirementFailed  EventType = "requirement.failed"
	DigestMigrated     EventType = "digest.migrated"
	ReplayDiverged     EventType = "replay.diverged"
	RunCompleted       EventType = "run.completed"
	RunBlocked         EventType = "run.blocked"
	RunRefused         EventType = "run.refused"
)

type Log

type Log struct {
	Path string
	// contains filtered or unexported fields
}

Log is an open run log. Appends go straight to disk with a sync.

func Create

func Create(runsDir, runID string) (*Log, error)

Create starts a new log file for a run. It refuses to overwrite.

func Open

func Open(runsDir, runID string) (*Log, error)

Open loads an existing run log and verifies sequence monotonicity.

func (*Log) Append

func (l *Log) Append(t EventType, data any) (Event, error)

Append writes one event with the next sequence number, fsynced.

func (*Log) Events

func (l *Log) Events() []Event

Events returns the loaded events in order.