replay static method
- required Ledger ledger,
- required CellGraph target,
- int fromSeq = 0,
- ReplayOptions options = ReplayOptions.strict,
Replays the ledger into target, starting at fromSeq.
target must be a graph bound to a fresh ledger store (or no
ledger at all). The engine pushes a ReplayJournal per entry so
the receptor's effectful calls are served from the recording, not
re-executed against the real world.
Parameters:
ledger: The recorded history to replay.target: The graph to replay into.fromSeq: The first ledger sequence to replay.options: Strictness flags; defaults to ReplayOptions.strict.
Returns:
On success, a ReplayResult whose newSnapshot is the target
graph's state at the end of replay. On failure (strict mode),
throws ReplayDivergenceException. In lenient mode, returns a
result with success == false and non-empty divergences.
Non-obvious: the purity gate is the journal, not a pre-check
The engine does not consult CellGraph.purityOf up front. An
effectful cell whose entry records no effects replays "fine" —
but the only way to record no effects with an effectful
component is to have journalled nothing, which the journal's
exhaustion checks then cannot see either. The honest gate is on
the recording side (NullJournal fails loudly, and every
effectful rule writes a verdict); a dedicated purity
pre-validation is a later hardening.
Implementation
static Future<ReplayResult> replay({
required Ledger ledger,
required CellGraph target,
int fromSeq = 0,
ReplayOptions options = ReplayOptions.strict,
}) async {
if (target.ledger != null) {
throw StateError(
'ReplayEngine.replay: target graph "${target.id}" is bound to a '
'ledger. Replaying into a ledgered graph would re-append entries '
'and corrupt the history. Use a graph that is not bound to a '
'ledger (call unbindLedger first), or provide a graph built '
'from the same CellGraphBuilder that produced the original.',
);
}
// Hardening (review fix): never replay a corrupt history.
// One pass recomputes every hash of the chain; a tampered ledger
// fails here with a LedgerIntegrityException instead of producing a
// confusing downstream divergence.
await ledger.verify();
final divergences = <DivergenceReport>[];
int replayed = 0;
int? firstDivergedAt;
final checkBaseline = fromSeq == 0;
// Pulse bodies resolve their parent chains by digest; the engine
// registers each reconstructed pulse as it replays earlier entries.
final parentsByDigest = <String, Pulse<dynamic>>{};
// Timer fires are deferred to after the entry loop (see
// ReplayJournal.deferredFires): the recording's trailing edges
// happened between entries, and firing inside the consuming entry
// moved downstream writes one entry too early.
final deferredFires = <FutureOr<void> Function()>[];
await for (final entry in ledger.entriesSince(fromSeq)) {
if (options.maxEntries != null && replayed >= options.maxEntries!) {
break;
}
// Review fix: a fork ledger's seq 0 is the ForkRecord marker
// (cell `fork:<id>`), not a replayed pulse — replaying it always
// diverged. Make the usage error loud instead: fork replays must
// start at seq 1.
if (entry.seq == 0 && entry.receipt.id.startsWith('fork:')) {
throw StateError(
'ReplayEngine.replay: seq 0 of a fork ledger is the '
'ForkRecord marker, not an entry to replay. Replay a fork '
'with fromSeq: 1.',
);
}
final divergence = await _replayOne(
entry: entry,
target: target,
options: options,
checkBaseline: checkBaseline,
parentsByDigest: parentsByDigest,
deferredFires: deferredFires,
);
replayed++;
if (divergence != null) {
divergences.add(divergence);
firstDivergedAt ??= entry.seq;
if (options.failOnDivergence) {
throw ReplayDivergenceException(
divergence.reason,
seq: entry.seq,
report: divergence,
);
}
}
}
// Run the deferred timer fires — the recording's trailing edges —
// after every entry has replayed and every delta check has passed.
// The fires may write the target cells; their downstream effect is
// exactly what the recorded deltas of the following entries expect.
for (final fire in deferredFires) {
await fire();
}
final success = divergences.isEmpty;
return ReplayResult(
success: success,
entriesReplayed: replayed,
divergedAt: firstDivergedAt,
divergences: List.unmodifiable(divergences),
// Tie the snapshot to the sequence the replay actually reached
// (review fix: the default -1 made the snapshot unbound).
newSnapshot: target.snapshot(lastLedgerSeq: fromSeq + replayed - 1),
);
}