Reference

replay

Walk the Field's append-only event log — reconstruct chains, history, and past state.

replay()

Returns an ordered slice of the Field's event log. Added in v0.3 as part of full Level 1 conformance.

Where read() gives you current state and attune() / reckon() give you scored, filtered state, replay() gives you history — every write, retract, and supersede, in the order they happened, each carrying the intent that motivated it.

Signature

field.replay(query?: ReplayQuery): Promise<FieldEvent[]>

type ReplayQuery = {
  entry_id?: string
  topic?: string
  agent?: string
  sinceSeq?: number
  untilSeq?: number
  followChain?: boolean
}

type FieldEvent = {
  type: 'RECORD' | 'STATUS_CHANGE'
  seq: number
  lamport: number       // causal ordering value (epoch)
  agent?: string
  intent?: string        // present on RECORD and STATUS_CHANGE events
  entry_id: string
  // ...additional event-specific fields
}

Parameters

All fields are optional and combine with AND semantics, except entry_id + followChain:

Parameter	Description
`entry_id`	Narrows results to events affecting one entry. Enables chain following.
`topic`	Filters to `RECORD` events on a given `entry.topic`. Excludes `STATUS_CHANGE` events.
`agent`	Restricts to events originating from a particular agent.
`sinceSeq`	Only events with `seq` strictly greater than this value.
`untilSeq`	Only events with `seq` less than or equal to this value.
`followChain`	Defaults to `true` when `entry_id` is set — walks the full supersession chain. Set `false` to see only that entry's own events.

Behavior

Returns events in chronological order (seq ascending).
Every write, retract, and supersede call appends at least one event; supersede appends two (a STATUS_CHANGE on the predecessor, a RECORD for the new entry) — both are guaranteed atomic by every storage adapter.
Calling replay() with no arguments returns the entire log — use sinceSeq / untilSeq to page through large logs.

Example — reconstruct a correction chain

const chain = await field.replay({ entry_id: originalId })

for (const event of chain) {
  console.log(event.type, event.agent, '—', event.intent)
}
// RECORD    researcher    — market size from three analyst reports
// STATUS_CHANGE fact-checker — revised projection after reviewing Q4 earnings directly
// RECORD    fact-checker  — revised projection after reviewing Q4 earnings directly

This is the whole point of replay(): not just what changed, but why, at every step — "a story, not a dump."

Example — reconstruct state at a point in time

Combine replay() with the exported buildProjection helper to derive historical Field state:

import { buildProjection } from '@akashikprotocol/core'

const eventsUpToThen = await field.replay({ untilSeq: someSeq })
const stateAtThatPoint = buildProjection(eventsUpToThen)

Errors

Code	When
`INVALID_QUERY`	`query` is provided but is not a plain object, or `sinceSeq` / `untilSeq` is invalid

Storage Adapters — the durable backends replay() reads from
Managing Entries — retract and supersede, the operations that populate the log

Errors

AkashikError — the single error type raised by the SDK.

Storage Adapters

Memory, File, and Postgres adapters — make a Field durable.