Rulvar API reference

---

Rulvar API reference / @rulvar/core / Replayer

Class: Replayer

Defined in: packages/core/src/journal/replayer.ts:204

Per-run journal kernel front end. Everything is per instance: no module state anywhere.

Constructors

Constructor

new Replayer(options): Replayer;

Defined in: packages/core/src/journal/replayer.ts:232

Parameters

Parameter	Type	Description
options	{ disposition?: (op) => OperationDisposition; keyRing?: KeyRing; largeValueWarnBytes?: number; lease?: Lease; leaseOf?: () => Lease | undefined; now?: () => number; onWarn?: (msg) => void; priceUsd?: (servedBy, usage) => number | undefined; priorEntries?: readonly JournalEntry[]; runId: string; store: JournalStore; strict?: boolean; }	-
options.disposition?	(op) => OperationDisposition	-
options.keyRing?	KeyRing	-
options.largeValueWarnBytes?	number	-
options.lease?	Lease	Queue mode: every append carries this lease so a stale holder's writes are rejected by the fencing epoch (M8 entry amendment). Absent means the single-writer precondition is asserted instead of fenced (the embedded default).
options.leaseOf?	() => Lease | undefined	Late-bound lease lookup (P0.2): consulted at EVERY append, winning over the static lease when it returns one. The engine passes its segment-lease holder here, because the engine-acquired genesis lease exists only after the ownership boot, which runs after this constructor.
options.now?	() => number	-
options.onWarn?	(msg) => void	Receives large-value soft warnings (never an error).
options.priceUsd?	(servedBy, usage) => number | undefined	-
options.priorEntries?	readonly JournalEntry[]	The loaded, normalized prior journal (resume).
options.runId	string	-
options.store	JournalStore	-
options.strict?	boolean	Replay-strict: any live-class match throws JournalMissError.

Returns

Replayer

Accessors

fold

Get Signature

get fold(): ResolutionFold;

Defined in: packages/core/src/journal/replayer.ts:392

The DEF-4 fold over this run's journal (prior plus live appends).

Returns

ResolutionFold

---

invalidatedSeqs

Get Signature

get invalidatedSeqs(): ReadonlySet<number>;

Defined in: packages/core/src/journal/replayer.ts:369

Returns

ReadonlySet<number>

Methods

abandonBranch()

abandonBranch(attempt): Promise<ResolutionOutcome>;

Defined in: packages/core/src/journal/replayer.ts:439

Parameters

Parameter	Type
attempt	AbandonAttempt

Returns

Promise<ResolutionOutcome>

---

appendRefEntry()

appendRefEntry(input): Promise<JournalEntry>;

Defined in: packages/core/src/journal/replayer.ts:397

Ref-entry append used by the ResolutionArbiter; O2-checked by shape validation.

Parameters

Parameter	Type
input	{ abandon?: AbandonPayload; kind: "resolution" | "abandon"; ref: number; resolution?: ResolutionPayload; scope: string; spanId: string; }
input.abandon?	AbandonPayload
input.kind	"resolution" | "abandon"
input.ref	number
input.resolution?	ResolutionPayload
input.scope	string
input.spanId	string

Returns

Promise<JournalEntry>

---

appendRunning()

appendRunning(input): Promise<JournalEntry>;

Defined in: packages/core/src/journal/replayer.ts:505

Two-phase dispatch: the running entry (kinds agent, step, child). value is legal on child dispatches only: the child payload { workflow, childScope } lets the abandon fold compute the child's transitive scope coverage (M6-T06). Values never enter identity.

Parameters

Parameter	Type
input	BaseAppend & { memoizeOutcome?: boolean; value?: unknown; }

Returns

Promise<JournalEntry>

---

appendSinglePhase()

appendSinglePhase(input): Promise<JournalEntry>;

Defined in: packages/core/src/journal/replayer.ts:471

Single-phase fact entries: rand, decisions, termination facts.

Parameters

Parameter	Type
input	SinglePhaseAppend

Returns

Promise<JournalEntry>

---

appendSuspended()

appendSuspended(input): Promise<JournalEntry>;

Defined in: packages/core/src/journal/replayer.ts:625

Suspended kinds (external, approval): appended once, closed by ref-entries (M2).

Parameters

Parameter	Type
input	SuspendedAppend

Returns

Promise<JournalEntry>

---

appendTerminal()

appendTerminal(runningSeq, patch): Promise<JournalEntry>;

Defined in: packages/core/src/journal/replayer.ts:535

Two-phase completion: a terminal entry referencing the running entry by ref. Scope, key, ordinal, kind, and hashVersion are inherited from the running entry (running/terminal pairs are always single-version; the pair shares one ordinal because it is one logical operation).

Parameters

Parameter	Type
runningSeq	number
patch	TerminalPatch

Returns

Promise<JournalEntry>

---

flush()

flush(): Promise<void>;

Defined in: packages/core/src/journal/replayer.ts:677

Resolves when every append enqueued so far has persisted, and REJECTS typed when any append was lost (RV3201). Deterministic shims journal fire-and-forget through the serialized queue, whose chain swallows rejections to keep later appends flowing; without this rethrow a failed persist was visible to nobody (the shim dropped its promise, the chain caught the error, and this barrier awaited the already-caught chain), so a run could settle ok over a journal missing a record it believes it wrote. The first failure latches permanently for the segment: every flush from that moment rethrows it, the engine settle path converts a would-be ok into an error terminal, and mid-run flush callers fail fast instead of proceeding over a torn journal.

Returns

Promise<void>

---

invalidate()

invalidate(seq): void;

Defined in: packages/core/src/journal/replayer.ts:365

invalidate/retry: explicit unpinning of a memoized failure; the invalidated entry reruns on this resume. The safety boundary is an open question.

Parameters

Parameter	Type
seq	number

Returns

void

---

ledger()

ledger(): Ledger;

Defined in: packages/core/src/journal/replayer.ts:654

The budget ledger fold: usage sums over terminal entries once, never twice; agentsSpawned counts agent dispatches. Dollars fold on the settled billing basis (RV801): per provider call where the entry's records cover its usage, the per-slice aggregate otherwise, the same basis as the CostReport and the invoice.

Returns

Ledger

---

match()

match(
   scope, 
   identity, 
   mode): MatchResult;

Defined in: packages/core/src/journal/replayer.ts:322

Forward-matches one live call against the prior journal. Fresh runs always miss; the M2-T06 predicate is injected through setDisposition once folds are built.

Parameters

Parameter	Type
scope	string
identity	IdentityInput
mode	ReplayMode

Returns

MatchResult

---

registerAlias()

registerAlias(donorPrefix, targetPrefix): void;

Defined in: packages/core/src/journal/replayer.ts:356

Registers a node.link scope-prefix rewrite (DEF-5): donorPrefix forward-matches into targetPrefix at every nested level. Idempotent; the alias map is rebuilt by fold on resume.

Parameters

Parameter	Type
donorPrefix	string
targetPrefix	string

Returns

void

---

resolveSuspended()

resolveSuspended(target, attempt): Promise<ResolutionOutcome>;

Defined in: packages/core/src/journal/replayer.ts:431

Submits a resolution attempt through the per-target FIFO arbiter. Losing attempts are journaled noops.

Parameters

Parameter	Type
target	number
attempt	ResolutionAttempt

Returns

Promise<ResolutionOutcome>

---

resumeReport()

resumeReport(): ResumeReport;

Defined in: packages/core/src/journal/replayer.ts:373

Returns

ResumeReport

---

seal()

seal(): void;

Defined in: packages/core/src/journal/replayer.ts:762

Seals the journal after the run's durable settle (RV1904): every append funnel rejects typed from here on. The orchestrate exit barrier (RV1903) and the engine settle drain terminate every straggler BEFORE the seal, so a sealed append is a lifecycle bug surfacing loudly instead of the silent post-settle mutation that split the four-role benchmark's cost views. A resume constructs a fresh Replayer and appends normally.

Returns

void

---

setAliasDisposition()

setAliasDisposition(disposition): void;

Defined in: packages/core/src/journal/replayer.ts:347

The disposition for alias-sourced candidates (DEF-5): bypasses the abandon overlay so donor entries regain their pre-abandon terminal status when matched through the alias.

Parameters

Parameter	Type
disposition	(op) => OperationDisposition

Returns

void

---

setDisposition()

setDisposition(disposition): void;

Defined in: packages/core/src/journal/replayer.ts:338

Parameters

Parameter	Type
disposition	(op) => OperationDisposition

Returns

void

---

snapshot()

snapshot(): readonly JournalEntry[];

Defined in: packages/core/src/journal/replayer.ts:659

Read-only view of the appended entries, in per-run total order.

Returns

readonly JournalEntry[]

---

suspensionState()

suspensionState(target): SuspensionState;

Defined in: packages/core/src/journal/replayer.ts:448

Pure fold view, snapshot-pinned.

Parameters

Parameter	Type
target	number

Returns

SuspensionState