pub struct Journal { /* private fields */ }Expand description
An append-only, in-memory journal of one run’s RunEvents.
Cheap to clone: clones share the same journal (one Arc layer inside),
which is how node closures record model/tool calls into the same journal
the executor is writing. Thread-safe; Send + Sync.
The journal stamps every event with its run_id/thread_id, the next
sequence number, and a recorded_at read from its own Clock — so
events recorded from inside nodes (whose code cannot see the executor’s
clock) are still timestamped through the run’s determinism seam.
Implementations§
Source§impl Journal
impl Journal
Sourcepub fn new(
run_id: impl Into<String>,
thread_id: impl Into<String>,
clock: Clock,
) -> Self
pub fn new( run_id: impl Into<String>, thread_id: impl Into<String>, clock: Clock, ) -> Self
A fresh journal for run_id / thread_id, timestamping events from
clock.
Sourcepub fn from_snapshot(snapshot: JournalSnapshot, clock: Clock) -> Result<Self>
pub fn from_snapshot(snapshot: JournalSnapshot, clock: Clock) -> Result<Self>
Rebuild a journal from a JournalSnapshot (e.g. a replay fixture).
The head hash is recomputed from the events rather than trusted from
the snapshot, so a corrupted or edited fixture is detected here
instead of deep inside a replay. Returns None-style failure as a
crate::error::RustyError::Serialization when an event fails to
serialize (not realistically possible for well-formed snapshots).
Sourcepub fn record(&self, draft: EventDraft) -> String
pub fn record(&self, draft: EventDraft) -> String
Append one event and return its id ({run_id}:{seq}).
The journal assigns the sequence number and timestamp, promotes
oversized payloads into the artifact map (replacing them with
PayloadRef::Artifact references), and chains the head hash over
the canonical serialization of the appended event.
Sourcepub fn head_hash(&self) -> String
pub fn head_hash(&self) -> String
The current head hash (chained SHA-256 over all recorded events).
Sourcepub fn head_ref(&self) -> JournalRef
pub fn head_ref(&self) -> JournalRef
The journal head as a crate::record::JournalRef, for stamping
into checkpoints.
Sourcepub fn snapshot(&self) -> JournalSnapshot
pub fn snapshot(&self) -> JournalSnapshot
A serde-complete export of the journal: every event plus the artifact payloads they reference. The unit a portable replay fixture is built from.
Bytes stay embedded by design: the fixture contract (self-contained,
loadable anywhere) outranks the size optimization. Persistence paths
that want the optimization use Journal::snapshot_externalized.
Sourcepub async fn snapshot_externalized(
&self,
store: &dyn ArtifactStore,
) -> Result<JournalSnapshot>
pub async fn snapshot_externalized( &self, store: &dyn ArtifactStore, ) -> Result<JournalSnapshot>
Export the journal with its artifact payloads spilled to an external
ArtifactStore: the snapshot records content addresses
(JournalSnapshot::artifact_refs) instead of embedding bytes.
This is the persistence-path export (R0.7 wave 4): a server
rewriting journal snapshots at every checkpoint boundary stores each
oversized payload once per content, not once per snapshot — re-puts
dedupe on the content address, so artifact-addressed retry traffic is
cheap. Load with Journal::from_snapshot_with_store.
Sourcepub async fn from_snapshot_with_store(
snapshot: JournalSnapshot,
store: &dyn ArtifactStore,
clock: Clock,
) -> Result<Self>
pub async fn from_snapshot_with_store( snapshot: JournalSnapshot, store: &dyn ArtifactStore, clock: Clock, ) -> Result<Self>
Rebuild a journal from an externalized snapshot
(Journal::snapshot_externalized): every referenced artifact is
fetched through store — integrity-verified on read by the store’s
contract — and re-embedded, after which the load is the ordinary
hash-verified Journal::from_snapshot.
Sourcepub fn resolve(&self, payload: &PayloadRef) -> Option<Value>
pub fn resolve(&self, payload: &PayloadRef) -> Option<Value>
Resolve a PayloadRef to its value, looking through the artifact
map. None for artifact references whose bytes are absent (a
truncated snapshot — detectable via Journal::from_snapshot’s hash
check).
Sourcepub fn record_effect_receipt(
&self,
receipt: &EffectReceipt,
parent: Option<String>,
) -> String
pub fn record_effect_receipt( &self, receipt: &EffectReceipt, parent: Option<String>, ) -> String
Journal an effect receipt (R0.6 Durable Work): the effect’s own
confirmation of an Idempotent side effect, recorded as a
RunEventKind::EffectReceipt event with the receipt as its output
payload and parent as its causal parent — the task lifecycle event
that completed the effect once task lifecycle journaling lands; until
then, the run’s journal head is the honest parent (the receipt was
caused by everything the run did before the task settled).
Recording here — one canonical shape, as with model/tool calls — is
what lets JournalSnapshot::find_effect_receipt serve the receipt
during replay instead of re-sending the effect.
Sourcepub fn memory(&self, source: MemorySource) -> JournaledMemory
pub fn memory(&self, source: MemorySource) -> JournaledMemory
Bind a memory source to this journal (R0.8 Rusty Learn, wave 1): the
governed-memory seam. The returned handle journals every read as
RunEventKind::MemoryRead (Effect::ReadOnly, with the resolved
query plus budget as the request and the assembly as the output) and
every write as RunEventKind::MemoryWrite (Effect::Idempotent
under the derived key), so exact replay serves the journaled assembly
instead of re-querying the store.
Node closures capture the handle exactly the way they capture a
Journal clone for recording model and tool calls; causal
parentage comes from the invocation’s node-input event id
(PARENT_EVENT_KEY).