recorder

Documentation

Overview

Package recorder writes AIR (AI Incident Record) files — portable, tamper-evident audit records for every LLM interaction.

Index

• type Record
  • func Load(path string) (Record, error)
• type Tokens
• type Writer
  • func NewWriter(dir string) (*Writer, error)
  • func (w *Writer) EnableChaining(key string) (int64, error)
  • func (w *Writer) Write(r Record) error

Types

type Record

type Record struct {
	Version          string    `json:"version"`
	RunID            string    `json:"run_id"`
	TraceID          string    `json:"trace_id"`
	Timestamp        time.Time `json:"timestamp"`
	Model            string    `json:"model"`
	Provider         string    `json:"provider"`
	Endpoint         string    `json:"endpoint"`
	RequestVaultRef  string    `json:"request_vault_ref"`
	ResponseVaultRef string    `json:"response_vault_ref"`
	RequestChecksum  string    `json:"request_checksum"`
	ResponseChecksum string    `json:"response_checksum"`
	Tokens           Tokens    `json:"tokens"`
	DurationMS       int64     `json:"duration_ms"`
	Status           string    `json:"status"`
	Error            string    `json:"error,omitempty"`
	// Trajectory linkage (additive, backward compatible). A lone call is a
	// trajectory of one step. See docs/SPEC-trajectory-chain.md.
	TrajectoryID string   `json:"trajectory_id,omitempty"`
	StepID       string   `json:"step_id,omitempty"`
	ParentIDs    []string `json:"parent_ids,omitempty"`
	// Tamper-evidence (present when the writer has chaining enabled).
	// chain_hash = HMAC-SHA256(key, prev_digest || canonical record JSON),
	// the same construction the Python SDK trust layer writes and verifies.
	ChainSeq  int64  `json:"chain_seq,omitempty"`
	ChainHash string `json:"chain_hash,omitempty"`
	// Config attestation: hash of the agent's config bundle (prompts,
	// skills, covenants) active for this call. Covered by chain_hash, so
	// chained records bind each call to the exact configuration that
	// produced it.
	ConfigHash string `json:"config_hash,omitempty"`
}

Record is the AIR file format — one per LLM call.

func Load

func Load(path string) (Record, error)

Load reads an AIR record from a file path.

type Tokens

type Tokens struct {
	Prompt     int `json:"prompt"`
	Completion int `json:"completion"`
	Total      int `json:"total"`
}

Tokens holds token usage from the provider response.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer writes AIR records to a directory. With chaining enabled (see EnableChaining) writes are serialized and each record is linked to the previous one with an HMAC chain hash.

func NewWriter

func NewWriter(dir string) (*Writer, error)

NewWriter creates a writer that saves AIR files to dir.

func (*Writer) EnableChaining

func (w *Writer) EnableChaining(key string) (int64, error)

EnableChaining turns on tamper-evident chaining for this writer. Every record written afterwards gets a chain_seq and a chain_hash computed as

HMAC-SHA256(key, prev_digest || canonical_json(record_without_chain_hash))

which is the exact construction the Python SDK's trust layer writes and its replay/evidence verifiers check. If the runs directory already contains chained records, the chain resumes from the highest chain_seq so a gateway restart does not reset the chain.

It returns the sequence number the chain resumed at (0 for a fresh chain).

func (*Writer) Write

func (w *Writer) Write(r Record) error

Write persists an AIR record as <run_id>.air.json.