Skip to main content

rusty_agent_runtime/
journal.rs

1//! The effect journal: the Flight Recorder's append-only run evidence, plus
2//! the determinism seams ([`Clock`], [`RngSource`]) that let a recorded run
3//! be re-driven exactly.
4//!
5//! A [`Journal`] is created per run (one `Executor::run` call) and receives
6//! every effect the executor observes: super-step boundaries, node
7//! inputs/outputs, interrupts, resumes, routing decisions, and checkpoint
8//! writes. Nodes, models, and tools record their own calls (model, tool,
9//! remote, WASM) through the same journal when handed a clone — the
10//! [`EventDraft`] builder is the public recording API.
11//!
12//! Two properties make the journal evidence rather than logs:
13//!
14//! - **Causal order.** Every event carries a monotonic `seq` and the id of
15//!   its causal parent, assigned by the journal at record time. The journal
16//!   — not wall time — defines the run's order.
17//! - **Tamper-evident head.** Recording chains a SHA-256 head hash over the
18//!   canonical serialization of each event. Checkpoints stamp the head as a
19//!   [`crate::record::JournalRef`], binding state and evidence together.
20//!
21//! # Determinism seams
22//!
23//! The executor sources every timestamp and every random id through
24//! [`Clock`] and [`RngSource`], configured per run via
25//! `RunConfig::with_clock` / `RunConfig::with_rng`. Defaults
26//! ([`Clock::System`], [`RngSource::System`]) are byte-identical to the
27//! pre-R0.5 behavior. A [`Clock::Logical`] + [`RngSource::Seeded`] pair
28//! makes event timestamps, latencies, event ids, run ids, and checkpoint ids
29//! reproducible — the precondition for exact replay.
30//!
31//! The in-memory journal is the v1 store; [`JournalSnapshot`] is its
32//! serde-complete export form (events plus the artifact payloads they
33//! reference), the unit portable replay fixtures are built from.
34//!
35//! # Artifact persistence seam (R0.7 wave 4)
36//!
37//! Payloads over [`INLINE_PAYLOAD_MAX_BYTES`] have always been
38//! content-addressed ([`ArtifactRef`]) with their bytes embedded in the
39//! snapshot's artifact map — a self-contained fixture contract that
40//! [`Journal::snapshot`] keeps. W4 adds the *other* half of the contract:
41//! an external, content-addressed [`ArtifactStore`] the snapshot can
42//! reference instead ([`JournalSnapshot::artifact_refs`]), so a server
43//! persisting journals stops rewriting the same large payload bytes at
44//! every checkpoint boundary. Writes dedupe by construction (the hash is
45//! the identity); reads verify integrity on every fetch. The seam is
46//! additive: snapshots with embedded bytes — everything written before W4,
47//! and replay fixtures by design — deserialize and load exactly as before.
48
49use std::collections::BTreeMap;
50use std::path::PathBuf;
51use std::sync::{Arc, Mutex, MutexGuard};
52
53use async_trait::async_trait;
54use chrono::{DateTime, Utc};
55use rand::SeedableRng;
56use rand_chacha::ChaCha8Rng;
57use serde::{Deserialize, Serialize};
58use serde_json::Value;
59
60use crate::llm::Usage;
61use crate::record::{
62    canonicalize_value, sha256_hex, ArtifactRef, Effect, EffectReceipt, EventStatus, PayloadRef,
63    RunEvent, RunEventKind, INLINE_PAYLOAD_MAX_BYTES,
64};
65
66/// The `NodeConfig::extra` key under which the executor passes the
67/// node-input journal event id of the current invocation.
68///
69/// Node code that records its own effects (model calls, tool calls) reads
70/// this key to parent them correctly: a model call's causal parent is the
71/// invocation that made it. Reserved by the runtime — applications must not
72/// set it themselves, and it travels in `NodeConfig::extra` over the worker
73/// wire protocol so remote nodes can parent their evidence the same way.
74pub const PARENT_EVENT_KEY: &str = "rusty.parent_event";
75
76/// The run's time source. All executor timestamps — event `recorded_at`,
77/// measured latencies, checkpoint `created_at` — are read through it.
78///
79/// `Clone` is cheap (a shared handle), so the same clock can serve the
80/// executor, every spawned node task, and an attached journal.
81#[derive(Debug, Clone, Default)]
82pub enum Clock {
83    /// Wall-clock UTC (`chrono::Utc::now`). The default; identical to
84    /// pre-R0.5 behavior.
85    #[default]
86    System,
87
88    /// A deterministic logical clock. Starts at `start_ms` (epoch millis)
89    /// and advances by `tick_ms` on **every read**. Two runs with the same
90    /// parameters observe the same timestamp sequence, which is what makes
91    /// recorded evidence reproducible.
92    ///
93    /// The tick-on-read semantics mean timestamps reflect how many clock
94    /// reads happened, not how much wall time passed — that is the point:
95    /// the journal's logical order is defined by `seq`, and timestamps
96    /// become a deterministic attribute rather than a second, unreliable
97    /// clock.
98    Logical(LogicalClock),
99}
100
101impl Clock {
102    /// A logical clock starting at `start_ms` (epoch millis), advancing
103    /// `tick_ms` per read.
104    pub fn logical(start_ms: u64, tick_ms: u64) -> Self {
105        Clock::Logical(LogicalClock {
106            state: Arc::new(Mutex::new(LogicalClockState {
107                now_ms: start_ms,
108                tick_ms,
109            })),
110        })
111    }
112
113    /// The current time. Under [`Clock::Logical`], every call advances the
114    /// clock by its tick.
115    pub fn now(&self) -> DateTime<Utc> {
116        match self {
117            Clock::System => Utc::now(),
118            Clock::Logical(logical) => {
119                let mut state = logical.lock();
120                let millis = state.now_ms;
121                state.now_ms = state.now_ms.saturating_add(state.tick_ms);
122                // Epoch millis are always representable; the logical clock
123                // is the only caller-controlled input and saturates.
124                DateTime::from_timestamp_millis(millis.min(i64::MAX as u64) as i64)
125                    .unwrap_or(DateTime::UNIX_EPOCH)
126            }
127        }
128    }
129
130    /// The current logical clock value in milliseconds (the value stamped
131    /// into [`crate::record::CheckpointHeader::logical_clock`]). Reads
132    /// through the same seam as [`Clock::now`], so logical clocks tick.
133    pub fn now_ms(&self) -> u64 {
134        self.now().timestamp_millis().max(0) as u64
135    }
136}
137
138/// Shared state of a [`Clock::Logical`] handle.
139#[derive(Debug, Clone)]
140pub struct LogicalClock {
141    state: Arc<Mutex<LogicalClockState>>,
142}
143
144#[derive(Debug)]
145struct LogicalClockState {
146    now_ms: u64,
147    tick_ms: u64,
148}
149
150impl LogicalClock {
151    fn lock(&self) -> MutexGuard<'_, LogicalClockState> {
152        // Poison means a recording path panicked mid-read; the clock value
153        // itself is plain data and stays coherent, so recovering is safe.
154        self.state.lock().unwrap_or_else(|e| e.into_inner())
155    }
156}
157
158/// The run's randomness source. Checkpoint ids and run ids are minted
159/// through it — the only entropy the executor consumes.
160#[derive(Debug, Clone, Default)]
161pub enum RngSource {
162    /// Operating-system entropy (`uuid::Uuid::new_v4`). The default;
163    /// identical to pre-R0.5 behavior.
164    #[default]
165    System,
166
167    /// A deterministic ChaCha8 stream seeded from a `u64`. Two runs with the
168    /// same seed mint the same id sequence, so journals and checkpoints of a
169    /// re-driven run reproduce the original's ids.
170    Seeded(SeededRng),
171}
172
173impl RngSource {
174    /// A seeded RNG drawing from one ChaCha8 stream per handle clone.
175    pub fn seeded(seed: u64) -> Self {
176        RngSource::Seeded(SeededRng {
177            rng: Arc::new(Mutex::new(ChaCha8Rng::seed_from_u64(seed))),
178        })
179    }
180
181    /// Mint a UUID (v4 layout in both modes: variant/version bits are set
182    /// explicitly for seeded draws, so downstream consumers cannot
183    /// distinguish the source from the bits).
184    pub fn uuid(&self) -> uuid::Uuid {
185        match self {
186            RngSource::System => uuid::Uuid::new_v4(),
187            RngSource::Seeded(seeded) => {
188                use rand::RngCore as _;
189                let mut bytes = [0u8; 16];
190                let mut rng = seeded.rng.lock().unwrap_or_else(|e| e.into_inner());
191                rng.fill_bytes(&mut bytes);
192                uuid::Builder::from_random_bytes(bytes).into_uuid()
193            }
194        }
195    }
196
197    /// Convenience: [`RngSource::uuid`] as a string.
198    pub fn uuid_string(&self) -> String {
199        self.uuid().to_string()
200    }
201}
202
203/// A shared ChaCha8 stream behind a mutex (interior mutability lets the
204/// executor pass `&self` while node tasks draw ids).
205#[derive(Debug, Clone)]
206pub struct SeededRng {
207    rng: Arc<Mutex<ChaCha8Rng>>,
208}
209
210/// A not-yet-sequenced event: everything about a [`RunEvent`] except the
211/// fields only the journal can assign (`id`, `run_id`, `thread_id`, `seq`,
212/// `recorded_at`). Build via [`EventDraft::new`] plus the builder methods,
213/// then hand to [`Journal::record`].
214#[derive(Debug, Clone)]
215pub struct EventDraft {
216    kind: RunEventKind,
217    effect: Effect,
218    node_id: Option<String>,
219    input: Option<Value>,
220    output: Option<Value>,
221    latency_ms: Option<u64>,
222    tokens: Option<Usage>,
223    cost_usd: Option<f64>,
224    status: EventStatus,
225    parent: Option<String>,
226}
227
228impl EventDraft {
229    /// A draft of kind `kind` produced by an effect of class `effect`.
230    pub fn new(kind: RunEventKind, effect: Effect) -> Self {
231        Self {
232            kind,
233            effect,
234            node_id: None,
235            input: None,
236            output: None,
237            latency_ms: None,
238            tokens: None,
239            cost_usd: None,
240            status: EventStatus::Ok,
241            parent: None,
242        }
243    }
244
245    /// The node this event is about.
246    pub fn node(mut self, node_id: impl Into<String>) -> Self {
247        self.node_id = Some(node_id.into());
248        self
249    }
250
251    /// The input payload. Large values are content-addressed by the journal
252    /// at record time (see [`INLINE_PAYLOAD_MAX_BYTES`]).
253    pub fn input(mut self, value: Value) -> Self {
254        self.input = Some(value);
255        self
256    }
257
258    /// The output payload; same large-value handling as [`EventDraft::input`].
259    pub fn output(mut self, value: Value) -> Self {
260        self.output = Some(value);
261        self
262    }
263
264    /// The measured latency of the recorded operation, in milliseconds.
265    pub fn latency_ms(mut self, latency_ms: u64) -> Self {
266        self.latency_ms = Some(latency_ms);
267        self
268    }
269
270    /// Token usage reported for a model call.
271    pub fn tokens(mut self, usage: Usage) -> Self {
272        self.tokens = Some(usage);
273        self
274    }
275
276    /// Monetary cost of the recorded operation in USD.
277    pub fn cost_usd(mut self, cost: f64) -> Self {
278        self.cost_usd = Some(cost);
279        self
280    }
281
282    /// The outcome status (defaults to [`EventStatus::Ok`]).
283    pub fn status(mut self, status: EventStatus) -> Self {
284        self.status = status;
285        self
286    }
287
288    /// The causal parent: the id of the event that caused this one.
289    pub fn parent(mut self, parent: impl Into<String>) -> Self {
290        self.parent = Some(parent.into());
291        self
292    }
293}
294
295/// The journal's mutable interior, behind one mutex. All fields advance
296/// together on every append, so poisoning cannot leave them inconsistent —
297/// recovery on poison is safe.
298#[derive(Debug)]
299struct JournalInner {
300    events: Vec<RunEvent>,
301    /// Content-addressed payloads too large to inline, keyed by SHA-256 hex.
302    /// `BTreeMap` so snapshot serialization order is canonical.
303    artifacts: BTreeMap<String, Value>,
304    /// Running chained head hash: `H_0 = sha256("")`,
305    /// `H_n = sha256(H_{n-1} || canonical_json(event_n))`.
306    head_hash: String,
307}
308
309/// An append-only, in-memory journal of one run's [`RunEvent`]s.
310///
311/// Cheap to clone: clones share the same journal (one `Arc` layer inside),
312/// which is how node closures record model/tool calls into the same journal
313/// the executor is writing. Thread-safe; `Send + Sync`.
314///
315/// The journal stamps every event with its `run_id`/`thread_id`, the next
316/// sequence number, and a `recorded_at` read from its own [`Clock`] — so
317/// events recorded from inside nodes (whose code cannot see the executor's
318/// clock) are still timestamped through the run's determinism seam.
319#[derive(Debug, Clone)]
320pub struct Journal {
321    run_id: String,
322    thread_id: String,
323    clock: Clock,
324    inner: Arc<Mutex<JournalInner>>,
325}
326
327impl Journal {
328    /// A fresh journal for `run_id` / `thread_id`, timestamping events from
329    /// `clock`.
330    pub fn new(run_id: impl Into<String>, thread_id: impl Into<String>, clock: Clock) -> Self {
331        Self {
332            run_id: run_id.into(),
333            thread_id: thread_id.into(),
334            clock,
335            inner: Arc::new(Mutex::new(JournalInner {
336                events: Vec::new(),
337                artifacts: BTreeMap::new(),
338                head_hash: sha256_hex(b""),
339            })),
340        }
341    }
342
343    /// Rebuild a journal from a [`JournalSnapshot`] (e.g. a replay fixture).
344    ///
345    /// The head hash is recomputed from the events rather than trusted from
346    /// the snapshot, so a corrupted or edited fixture is detected here
347    /// instead of deep inside a replay. Returns `None`-style failure as a
348    /// [`crate::error::RustyError::Serialization`] when an event fails to
349    /// serialize (not realistically possible for well-formed snapshots).
350    pub fn from_snapshot(snapshot: JournalSnapshot, clock: Clock) -> crate::error::Result<Self> {
351        // An externalized snapshot cannot resolve payloads without its
352        // store; refusing here beats a journal that silently answers `None`
353        // for artifact resolutions deep inside a replay.
354        if !snapshot.artifact_refs.is_empty() {
355            return Err(crate::error::RustyError::Serialization(
356                serde_json::Error::io(std::io::Error::new(
357                    std::io::ErrorKind::InvalidData,
358                    "journal snapshot references an external artifact store; \
359                     load it with Journal::from_snapshot_with_store",
360                )),
361            ));
362        }
363        let mut head_hash = sha256_hex(b"");
364        for event in &snapshot.events {
365            head_hash = chained_hash(&head_hash, event)?;
366        }
367        if head_hash != snapshot.head_hash {
368            return Err(crate::error::RustyError::Serialization(
369                serde_json::Error::io(std::io::Error::new(
370                    std::io::ErrorKind::InvalidData,
371                    format!(
372                        "journal snapshot head hash mismatch: events recompute to \
373                         {head_hash}, snapshot claims {}",
374                        snapshot.head_hash
375                    ),
376                )),
377            ));
378        }
379        let run_id = snapshot.run_id.clone();
380        let thread_id = snapshot.thread_id.clone();
381        Ok(Self {
382            run_id,
383            thread_id,
384            clock,
385            inner: Arc::new(Mutex::new(JournalInner {
386                events: snapshot.events,
387                artifacts: snapshot.artifacts,
388                head_hash,
389            })),
390        })
391    }
392
393    /// The run this journal records.
394    pub fn run_id(&self) -> &str {
395        &self.run_id
396    }
397
398    /// The thread the run belongs to.
399    pub fn thread_id(&self) -> &str {
400        &self.thread_id
401    }
402
403    /// The clock events are timestamped from.
404    pub fn clock(&self) -> &Clock {
405        &self.clock
406    }
407
408    fn lock(&self) -> MutexGuard<'_, JournalInner> {
409        self.inner.lock().unwrap_or_else(|e| e.into_inner())
410    }
411
412    /// Append one event and return its id (`{run_id}:{seq}`).
413    ///
414    /// The journal assigns the sequence number and timestamp, promotes
415    /// oversized payloads into the artifact map (replacing them with
416    /// [`PayloadRef::Artifact`] references), and chains the head hash over
417    /// the canonical serialization of the appended event.
418    pub fn record(&self, draft: EventDraft) -> String {
419        let recorded_at = self.clock.now();
420        let mut inner = self.lock();
421        let seq = inner.events.len() as u64;
422        let id = format!("{}:{seq}", self.run_id);
423
424        let input = draft
425            .input
426            .map(|value| store_payload(&mut inner.artifacts, value));
427        let output = draft
428            .output
429            .map(|value| store_payload(&mut inner.artifacts, value));
430
431        let event = RunEvent {
432            id: id.clone(),
433            run_id: self.run_id.clone(),
434            thread_id: self.thread_id.clone(),
435            node_id: draft.node_id,
436            seq,
437            kind: draft.kind,
438            effect: draft.effect,
439            input,
440            output,
441            latency_ms: draft.latency_ms,
442            tokens: draft.tokens,
443            cost_usd: draft.cost_usd,
444            status: draft.status,
445            parent: draft.parent,
446            recorded_at,
447        };
448
449        // Hash chaining over the canonical serialization: payload maps are
450        // key-sorted before hashing (see `canonicalized_for_hash`), so the
451        // hash is stable for identical event content regardless of the
452        // serde_json map backend a build ends up with. Serialization of a
453        // just-constructed event cannot realistically fail; if it somehow
454        // does, the event is still recorded — evidence must not be lost to
455        // a hashing defect — and the head chains over a fixed marker
456        // instead.
457        match serde_json::to_vec(&canonicalized_for_hash(&event)) {
458            Ok(bytes) => {
459                inner.head_hash = sha256_hex(&[inner.head_hash.as_bytes(), &bytes].concat());
460            }
461            Err(e) => {
462                tracing::warn!(error = %e, "failed to serialize event for head hash");
463                inner.head_hash =
464                    sha256_hex(&[inner.head_hash.as_bytes(), b"!unhashable"].concat());
465            }
466        }
467        inner.events.push(event);
468        id
469    }
470
471    /// The recorded events in sequence order.
472    pub fn events(&self) -> Vec<RunEvent> {
473        self.lock().events.clone()
474    }
475
476    /// Number of recorded events.
477    pub fn len(&self) -> usize {
478        self.lock().events.len()
479    }
480
481    /// `true` when nothing has been recorded.
482    pub fn is_empty(&self) -> bool {
483        self.len() == 0
484    }
485
486    /// The current head hash (chained SHA-256 over all recorded events).
487    pub fn head_hash(&self) -> String {
488        self.lock().head_hash.clone()
489    }
490
491    /// The journal head as a [`crate::record::JournalRef`], for stamping
492    /// into checkpoints.
493    pub fn head_ref(&self) -> crate::record::JournalRef {
494        let inner = self.lock();
495        crate::record::JournalRef {
496            events: inner.events.len() as u64,
497            sha256: inner.head_hash.clone(),
498        }
499    }
500
501    /// A serde-complete export of the journal: every event plus the artifact
502    /// payloads they reference. The unit a portable replay fixture is built
503    /// from.
504    ///
505    /// Bytes stay embedded by design: the fixture contract (self-contained,
506    /// loadable anywhere) outranks the size optimization. Persistence paths
507    /// that want the optimization use [`Journal::snapshot_externalized`].
508    pub fn snapshot(&self) -> JournalSnapshot {
509        let inner = self.lock();
510        JournalSnapshot {
511            run_id: self.run_id.clone(),
512            thread_id: self.thread_id.clone(),
513            events: inner.events.clone(),
514            artifacts: inner.artifacts.clone(),
515            artifact_refs: BTreeMap::new(),
516            head_hash: inner.head_hash.clone(),
517        }
518    }
519
520    /// Export the journal with its artifact payloads spilled to an external
521    /// [`ArtifactStore`]: the snapshot records content addresses
522    /// ([`JournalSnapshot::artifact_refs`]) instead of embedding bytes.
523    ///
524    /// This is the persistence-path export (R0.7 wave 4): a server
525    /// rewriting journal snapshots at every checkpoint boundary stores each
526    /// oversized payload once per content, not once per snapshot — re-puts
527    /// dedupe on the content address, so artifact-addressed retry traffic is
528    /// cheap. Load with [`Journal::from_snapshot_with_store`].
529    pub async fn snapshot_externalized(
530        &self,
531        store: &dyn ArtifactStore,
532    ) -> crate::error::Result<JournalSnapshot> {
533        let mut snapshot = self.snapshot();
534        let artifacts = std::mem::take(&mut snapshot.artifacts);
535        for (sha256, value) in artifacts {
536            // The canonical serialization the artifact map was keyed on
537            // (`store_payload`); infallible for a Value in practice.
538            let bytes = serde_json::to_vec(&value).expect("a serde_json::Value always serializes");
539            let reference = store.put(&bytes).await?;
540            debug_assert_eq!(
541                reference.sha256, sha256,
542                "artifact map keys are content addresses by construction"
543            );
544            snapshot.artifact_refs.insert(sha256, reference);
545        }
546        Ok(snapshot)
547    }
548
549    /// Rebuild a journal from an externalized snapshot
550    /// ([`Journal::snapshot_externalized`]): every referenced artifact is
551    /// fetched through `store` — integrity-verified on read by the store's
552    /// contract — and re-embedded, after which the load is the ordinary
553    /// hash-verified [`Journal::from_snapshot`].
554    pub async fn from_snapshot_with_store(
555        mut snapshot: JournalSnapshot,
556        store: &dyn ArtifactStore,
557        clock: Clock,
558    ) -> crate::error::Result<Self> {
559        let refs = std::mem::take(&mut snapshot.artifact_refs);
560        for (sha256, reference) in refs {
561            let bytes = store.get(&reference.sha256).await?;
562            let value: Value = serde_json::from_slice(&bytes).map_err(|e| {
563                crate::error::RustyError::Serialization(serde_json::Error::io(std::io::Error::new(
564                    std::io::ErrorKind::InvalidData,
565                    format!("artifact `{sha256}` is not valid JSON: {e}"),
566                )))
567            })?;
568            snapshot.artifacts.insert(sha256, value);
569        }
570        Self::from_snapshot(snapshot, clock)
571    }
572
573    /// Resolve a [`PayloadRef`] to its value, looking through the artifact
574    /// map. `None` for artifact references whose bytes are absent (a
575    /// truncated snapshot — detectable via [`Journal::from_snapshot`]'s hash
576    /// check).
577    pub fn resolve(&self, payload: &PayloadRef) -> Option<Value> {
578        match payload {
579            PayloadRef::Inline(value) => Some(value.clone()),
580            PayloadRef::Artifact(reference) => {
581                self.lock().artifacts.get(&reference.sha256).cloned()
582            }
583        }
584    }
585
586    /// Journal an effect receipt (R0.6 Durable Work): the effect's own
587    /// confirmation of an `Idempotent` side effect, recorded as a
588    /// [`RunEventKind::EffectReceipt`] event with the receipt as its output
589    /// payload and `parent` as its causal parent — the task lifecycle event
590    /// that completed the effect once task lifecycle journaling lands; until
591    /// then, the run's journal head is the honest parent (the receipt was
592    /// caused by everything the run did before the task settled).
593    ///
594    /// Recording here — one canonical shape, as with model/tool calls — is
595    /// what lets [`JournalSnapshot::find_effect_receipt`] serve the receipt
596    /// during replay instead of re-sending the effect.
597    pub fn record_effect_receipt(&self, receipt: &EffectReceipt, parent: Option<String>) -> String {
598        let mut draft = EventDraft::new(RunEventKind::EffectReceipt, Effect::Idempotent)
599            // Serialization of a just-built receipt cannot realistically
600            // fail; if it somehow does, record the payload the event must
601            // not lose rather than drop the evidence.
602            .output(serde_json::to_value(receipt).unwrap_or_else(
603                |_| serde_json::json!({ "idempotency_key": receipt.idempotency_key }),
604            ));
605        if let Some(parent) = parent {
606            draft = draft.parent(parent);
607        }
608        self.record(draft)
609    }
610
611    /// Bind a memory source to this journal (R0.8 Rusty Learn, wave 1): the
612    /// governed-memory seam. The returned handle journals every read as
613    /// [`RunEventKind::MemoryRead`] ([`Effect::ReadOnly`], with the resolved
614    /// query plus budget as the request and the assembly as the output) and
615    /// every write as [`RunEventKind::MemoryWrite`] ([`Effect::Idempotent`]
616    /// under the derived key), so exact replay serves the journaled assembly
617    /// instead of re-querying the store.
618    ///
619    /// Node closures capture the handle exactly the way they capture a
620    /// [`Journal`] clone for recording model and tool calls; causal
621    /// parentage comes from the invocation's node-input event id
622    /// ([`PARENT_EVENT_KEY`]).
623    pub fn memory(&self, source: crate::memory::MemorySource) -> crate::memory::JournaledMemory {
624        crate::memory::JournaledMemory::new(self, source)
625    }
626}
627
628/// Store `value` inline or — when its serialized size exceeds
629/// [`INLINE_PAYLOAD_MAX_BYTES`] — in the artifact map, returning the
630/// reference to record on the event.
631fn store_payload(artifacts: &mut BTreeMap<String, Value>, value: Value) -> PayloadRef {
632    let Ok(bytes) = serde_json::to_vec(&value) else {
633        // A Value that fails to serialize is a contradiction; keep it inline
634        // rather than drop evidence.
635        return PayloadRef::Inline(value);
636    };
637    if bytes.len() <= INLINE_PAYLOAD_MAX_BYTES {
638        return PayloadRef::Inline(value);
639    }
640    let reference = ArtifactRef {
641        sha256: sha256_hex(&bytes),
642        bytes: bytes.len() as u64,
643    };
644    artifacts.entry(reference.sha256.clone()).or_insert(value);
645    PayloadRef::Artifact(reference)
646}
647
648/// `sha256(prev || canonical_json(event))` — the head-hash chain step,
649/// shared by [`Journal::record`] and [`Journal::from_snapshot`].
650fn chained_hash(prev: &str, event: &RunEvent) -> crate::error::Result<String> {
651    let bytes = serde_json::to_vec(&canonicalized_for_hash(event))?;
652    Ok(sha256_hex(&[prev.as_bytes(), &bytes].concat()))
653}
654
655/// Recompute the chained head over `events` from the genesis hash — the
656/// verification-path half of the chain contract, shared by
657/// [`Journal::from_snapshot`] and the run-receipt verifier
658/// ([`crate::receipt::verify_receipt`]) so a receipt's head and the
659/// journal's head are the same bytes by construction.
660pub(crate) fn recompute_head_hash(events: &[RunEvent]) -> crate::error::Result<String> {
661    let mut head_hash = sha256_hex(b"");
662    for event in events {
663        head_hash = chained_hash(&head_hash, event)?;
664    }
665    Ok(head_hash)
666}
667
668/// The event as the head-hash chain covers it: identical except that every
669/// inline payload value is key-sorted recursively.
670///
671/// The chain's contract is "same content, same hash" — a replay that
672/// reproduces every event exactly must reproduce the head. That held
673/// trivially while serde_json's map was BTreeMap-backed everywhere; the
674/// `preserve_order` feature (pulled in transitively by `cedar-policy-core`
675/// when the server's `capsules` feature is enabled — see
676/// [`canonicalize_value`]) makes `Value` serialization order-sensitive, so
677/// a payload rebuilt in a different key-insertion order would hash
678/// differently while comparing equal. Canonicalizing only the payload
679/// values — struct fields keep their declaration order — preserves every
680/// hash a BTreeMap build ever produced byte-for-byte while making the
681/// chain backend-independent.
682fn canonicalized_for_hash(event: &RunEvent) -> RunEvent {
683    fn canonicalized_payload(payload: &Option<PayloadRef>) -> Option<PayloadRef> {
684        match payload {
685            Some(PayloadRef::Inline(value)) => Some(PayloadRef::Inline(canonicalize_value(value))),
686            other => other.clone(),
687        }
688    }
689    let mut canonical = event.clone();
690    canonical.input = canonicalized_payload(&event.input);
691    canonical.output = canonicalized_payload(&event.output);
692    canonical
693}
694
695/// A content-addressed blob store for journal artifacts (R0.7 wave 4).
696///
697/// The addressing contract predates the store: [`ArtifactRef`] has always
698/// content-addressed oversized payloads by SHA-256 — W4 adds where the
699/// bytes *live* when they leave the journal snapshot. The hash is the
700/// identity, so writes dedupe by construction (re-sent large inputs
701/// reference the same object) and readers can prove they got the bytes they
702/// asked for.
703///
704/// Error mapping: IO failures use the implementation's module convention
705/// ([`RustyError::Serialization`](crate::error::RustyError::Serialization)
706/// here in the journal, `Checkpoint` in the Postgres backend); an
707/// **integrity failure** — bytes that do not re-hash to their address — is
708/// always a `Serialization` error with `InvalidData`, the same shape
709/// [`Journal::from_snapshot`] uses for a tampered snapshot.
710#[async_trait]
711pub trait ArtifactStore: Send + Sync {
712    /// Store `bytes`, returning their content address. Idempotent: storing
713    /// identical bytes twice yields the same address and (at most) one
714    /// stored object.
715    async fn put(&self, bytes: &[u8]) -> crate::error::Result<ArtifactRef>;
716
717    /// Fetch the bytes for a content address. Integrity is verified on
718    /// every read: the returned bytes re-hash to the requested address, or
719    /// this errors — a store that cannot prove its bytes are the addressed
720    /// bytes is corruption, not data.
721    async fn get(&self, sha256: &str) -> crate::error::Result<Vec<u8>>;
722
723    /// Whether the store holds an address (existence only, no integrity
724    /// check — use [`ArtifactStore::get`] when the bytes matter).
725    async fn contains(&self, sha256: &str) -> crate::error::Result<bool>;
726}
727
728/// Map an IO error into the journal module's error convention.
729fn artifact_io_error(context: String, e: std::io::Error) -> crate::error::RustyError {
730    crate::error::RustyError::Serialization(serde_json::Error::io(std::io::Error::new(
731        e.kind(),
732        format!("{context}: {e}"),
733    )))
734}
735
736/// Filesystem [`ArtifactStore`]: one file per artifact at
737/// `{dir}/{sha256}`, written with the same atomic temp-write-then-rename
738/// discipline the JSON-file checkpointer uses — a crash mid-write can never
739/// leave a truncated blob behind (and a truncated blob would be caught by
740/// the read-side integrity check anyway).
741#[derive(Debug, Clone)]
742pub struct FileArtifactStore {
743    dir: PathBuf,
744}
745
746impl FileArtifactStore {
747    /// A store rooted at `dir` (created lazily on first `put`).
748    pub fn new(dir: impl Into<PathBuf>) -> Self {
749        Self { dir: dir.into() }
750    }
751
752    /// The root directory artifacts are stored under.
753    pub fn dir(&self) -> &std::path::Path {
754        &self.dir
755    }
756
757    fn artifact_path(&self, sha256: &str) -> PathBuf {
758        self.dir.join(sha256)
759    }
760}
761
762#[async_trait]
763impl ArtifactStore for FileArtifactStore {
764    async fn put(&self, bytes: &[u8]) -> crate::error::Result<ArtifactRef> {
765        let reference = ArtifactRef {
766            sha256: sha256_hex(bytes),
767            bytes: bytes.len() as u64,
768        };
769        let path = self.artifact_path(&reference.sha256);
770        // Dedupe by construction: an existing file under the address IS
771        // these bytes (or corruption the read side will catch) — re-puts of
772        // the same content are a no-op, which is what makes
773        // artifact-addressed retry traffic cheap.
774        if tokio::fs::try_exists(&path)
775            .await
776            .map_err(|e| artifact_io_error(format!("stat artifact `{}`", path.display()), e))?
777        {
778            return Ok(reference);
779        }
780        tokio::fs::create_dir_all(&self.dir).await.map_err(|e| {
781            artifact_io_error(format!("create artifact dir `{}`", self.dir.display()), e)
782        })?;
783        crate::checkpoint::JsonFileCheckpointer::atomic_write(&path, bytes).await?;
784        Ok(reference)
785    }
786
787    async fn get(&self, sha256: &str) -> crate::error::Result<Vec<u8>> {
788        let path = self.artifact_path(sha256);
789        let bytes = tokio::fs::read(&path)
790            .await
791            .map_err(|e| artifact_io_error(format!("read artifact `{sha256}`"), e))?;
792        let actual = sha256_hex(&bytes);
793        if actual != sha256 {
794            return Err(crate::error::RustyError::Serialization(
795                serde_json::Error::io(std::io::Error::new(
796                    std::io::ErrorKind::InvalidData,
797                    format!(
798                        "artifact integrity failure: `{sha256}` re-hashes to `{actual}`; \
799                         the stored bytes are corrupt"
800                    ),
801                )),
802            ));
803        }
804        Ok(bytes)
805    }
806
807    async fn contains(&self, sha256: &str) -> crate::error::Result<bool> {
808        tokio::fs::try_exists(self.artifact_path(sha256))
809            .await
810            .map_err(|e| artifact_io_error(format!("stat artifact `{sha256}`"), e))
811    }
812}
813
814/// The serde-complete export form of a [`Journal`]: run identity, the full
815/// event sequence, the artifact payloads referenced by events, and the head
816/// hash binding them. Round-trips through JSON unchanged; load with
817/// [`Journal::from_snapshot`] to re-verify the head.
818#[derive(Debug, Clone, Serialize, Deserialize)]
819pub struct JournalSnapshot {
820    /// The recorded run's id.
821    pub run_id: String,
822
823    /// The thread the run belongs to.
824    pub thread_id: String,
825
826    /// Every recorded event, in sequence order.
827    pub events: Vec<RunEvent>,
828
829    /// Content-addressed payloads referenced by events (SHA-256 hex → value).
830    pub artifacts: BTreeMap<String, Value>,
831
832    /// Payloads whose bytes live in an external [`ArtifactStore`] instead
833    /// of embedded in `artifacts` (R0.7 wave 4; see
834    /// [`Journal::snapshot_externalized`]). Additive: absent from the wire
835    /// when empty, so pre-W4 snapshots — and replay fixtures, which embed
836    /// by design — keep their exact shape. Load with
837    /// [`Journal::from_snapshot_with_store`].
838    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
839    pub artifact_refs: BTreeMap<String, ArtifactRef>,
840
841    /// The chained head hash over `events`.
842    pub head_hash: String,
843}
844
845impl JournalSnapshot {
846    /// The effect-receipt replay lookup (R0.6 Durable Work): the journaled
847    /// [`EffectReceipt`] for `idempotency_key`, when one exists.
848    ///
849    /// This is the queue-dispatched analogue of the seq-ordered serving
850    /// cursor exact replay uses for model and tool calls: a task's effect
851    /// lands outside the run's super-step order, so receipts are matched by
852    /// the idempotency key the effect ran under, not by sequence. A
853    /// re-driven run (or a replayed activity) asks "did this key already
854    /// land?" and serves the receipt instead of re-sending the effect.
855    ///
856    /// Malformed receipt payloads (a hand-edited journal) are skipped rather
857    /// than fatal — integrity failures of the snapshot itself are caught by
858    /// [`Journal::from_snapshot`]'s hash check at load time.
859    pub fn find_effect_receipt(&self, idempotency_key: &str) -> Option<EffectReceipt> {
860        self.receipts()
861            .find(|receipt| receipt.idempotency_key == idempotency_key)
862    }
863
864    /// The effect-kernel receipt lookup (R0.7): the journaled
865    /// [`EffectReceipt`] for a deterministic effect id, when one exists.
866    ///
867    /// Where [`JournalSnapshot::find_effect_receipt`] answers "did this key
868    /// already land?", this answers the recovery question the typed kernel
869    /// asks: "did *this exact effect* — this kind, this input, this key, in
870    /// this run scope — already commit?" (see
871    /// [`crate::effects::derive_effect_id`]). Receipts journaled before the
872    /// kernel (no `effect_id` on the wire) simply never match here and keep
873    /// being served by the key lookup — the two lookups coexist, the id
874    /// lookup strictly sharper.
875    pub fn find_effect_receipt_by_effect_id(
876        &self,
877        effect_id: &crate::effects::EffectId,
878    ) -> Option<EffectReceipt> {
879        self.receipts()
880            .find(|receipt| receipt.effect_id.as_deref() == Some(effect_id.as_str()))
881    }
882
883    /// Every well-formed receipt journaled in this snapshot, in sequence
884    /// order. Malformed receipt payloads (a hand-edited journal) are skipped
885    /// rather than fatal — integrity failures of the snapshot itself are
886    /// caught by [`Journal::from_snapshot`]'s hash check at load time.
887    fn receipts(&self) -> impl Iterator<Item = EffectReceipt> + '_ {
888        self.events
889            .iter()
890            .filter(|event| event.kind == RunEventKind::EffectReceipt)
891            .filter_map(|event| {
892                let value = match event.output.as_ref()? {
893                    PayloadRef::Inline(value) => value.clone(),
894                    PayloadRef::Artifact(reference) => {
895                        self.artifacts.get(&reference.sha256)?.clone()
896                    }
897                };
898                serde_json::from_value(value).ok()
899            })
900    }
901}
902
903#[cfg(test)]
904mod tests {
905    use super::*;
906    use serde_json::json;
907
908    fn journal() -> Journal {
909        Journal::new("run-1", "thread-1", Clock::System)
910    }
911
912    #[test]
913    fn record_assigns_sequence_and_deterministic_ids() {
914        let j = journal();
915        let a = j.record(EventDraft::new(RunEventKind::SuperStepStart, Effect::Pure));
916        let b = j.record(
917            EventDraft::new(RunEventKind::NodeInput, Effect::Pure)
918                .node("n")
919                .parent(a.clone()),
920        );
921        assert_eq!(a, "run-1:0");
922        assert_eq!(b, "run-1:1");
923        let events = j.events();
924        assert_eq!(events[1].seq, 1);
925        assert_eq!(events[1].parent.as_deref(), Some("run-1:0"));
926        assert_eq!(events[1].node_id.as_deref(), Some("n"));
927        assert_eq!(j.len(), 2);
928        assert!(!j.is_empty());
929    }
930
931    #[test]
932    fn large_payloads_are_content_addressed_and_resolvable() {
933        let j = journal();
934        let big = json!({"blob": "x".repeat(INLINE_PAYLOAD_MAX_BYTES)});
935        j.record(
936            EventDraft::new(RunEventKind::ModelCall, Effect::NonIdempotent).output(big.clone()),
937        );
938        let event = &j.events()[0];
939        let reference = match event.output.as_ref() {
940            Some(PayloadRef::Artifact(reference)) => reference.clone(),
941            other => panic!("expected artifact reference, got {other:?}"),
942        };
943        assert_eq!(
944            reference.bytes as usize,
945            serde_json::to_vec(&big).unwrap().len()
946        );
947        assert_eq!(j.resolve(event.output.as_ref().unwrap()), Some(big));
948    }
949
950    #[test]
951    fn head_hash_advances_and_binds_content() {
952        let j1 = journal();
953        let j2 = journal();
954        assert_eq!(j1.head_hash(), j2.head_hash());
955        let draft = || EventDraft::new(RunEventKind::SuperStepStart, Effect::Pure);
956        j1.record(draft());
957        assert_ne!(j1.head_hash(), j2.head_hash());
958        j2.record(draft());
959        // Same event content (modulo timestamps — system clock here, so the
960        // hashes may differ; only the advance is asserted).
961        assert_ne!(j1.head_hash(), j2.head_hash());
962    }
963
964    #[test]
965    fn snapshot_roundtrip_reverifies_head() {
966        let j = journal();
967        j.record(
968            EventDraft::new(RunEventKind::SuperStepStart, Effect::Pure).input(json!({"step": 0})),
969        );
970        j.record(
971            EventDraft::new(RunEventKind::NodeInput, Effect::Pure)
972                .node("a")
973                .output(json!({"blob": "y".repeat(INLINE_PAYLOAD_MAX_BYTES)})),
974        );
975        let snapshot = j.snapshot();
976        let wire = serde_json::to_string(&snapshot).unwrap();
977        let parsed: JournalSnapshot = serde_json::from_str(&wire).unwrap();
978        let rebuilt = Journal::from_snapshot(parsed, Clock::System).unwrap();
979        assert_eq!(rebuilt.head_hash(), j.head_hash());
980        assert_eq!(rebuilt.events(), j.events());
981
982        // A tampered snapshot is rejected on load.
983        let mut tampered = j.snapshot();
984        tampered.events[0].status = EventStatus::Error;
985        assert!(Journal::from_snapshot(tampered, Clock::System).is_err());
986    }
987
988    #[test]
989    fn head_hash_is_stable_across_payload_key_order() {
990        // The two payloads are the same logical value parsed from text with
991        // different key orders. Value equality is order-insensitive under
992        // either serde_json map backend, but serialization order is not:
993        // under `preserve_order` (cedar-policy-core's transitive demand)
994        // the parses keep their insertion orders, so chaining hashes over
995        // the raw event would produce different heads for equal content —
996        // the exact failure mode `canonicalized_for_hash` exists to close.
997        let forward: Value =
998            serde_json::from_str(r#"{"alpha": 1, "beta": {"x": 1, "y": 2}, "gamma": [3]}"#)
999                .unwrap();
1000        let reverse: Value =
1001            serde_json::from_str(r#"{"gamma": [3], "beta": {"y": 2, "x": 1}, "alpha": 1}"#)
1002                .unwrap();
1003        assert_eq!(forward, reverse);
1004
1005        let journal_a = Journal::new("run-1", "thread-1", Clock::logical(1_000_000, 5));
1006        let journal_b = Journal::new("run-1", "thread-1", Clock::logical(1_000_000, 5));
1007        journal_a.record(
1008            EventDraft::new(RunEventKind::NodeInput, Effect::Pure)
1009                .node("n")
1010                .input(forward.clone())
1011                .output(reverse.clone()),
1012        );
1013        journal_b.record(
1014            EventDraft::new(RunEventKind::NodeInput, Effect::Pure)
1015                .node("n")
1016                .input(reverse)
1017                .output(forward),
1018        );
1019        assert_eq!(journal_a.events(), journal_b.events());
1020        assert_eq!(journal_a.head_hash(), journal_b.head_hash());
1021
1022        // The from_snapshot path re-chains through `chained_hash`; a
1023        // roundtrip through the wire must reproduce the same head.
1024        let snapshot: JournalSnapshot =
1025            serde_json::from_str(&serde_json::to_string(&journal_a.snapshot()).unwrap()).unwrap();
1026        let rebuilt = Journal::from_snapshot(snapshot, Clock::System).unwrap();
1027        assert_eq!(rebuilt.head_hash(), journal_a.head_hash());
1028    }
1029
1030    #[test]
1031    fn logical_clock_ticks_deterministically() {
1032        let clock = Clock::logical(1_000_000, 5);
1033        let a = clock.now();
1034        let b = clock.now();
1035        assert_eq!(b.timestamp_millis() - a.timestamp_millis(), 5);
1036        assert_eq!(a.timestamp_millis(), 1_000_000);
1037
1038        let same = Clock::logical(1_000_000, 5);
1039        assert_eq!(same.now(), a);
1040        assert_eq!(same.now(), b);
1041    }
1042
1043    #[test]
1044    fn seeded_rng_mints_reproducible_v4_uuids() {
1045        let a = RngSource::seeded(42);
1046        let b = RngSource::seeded(42);
1047        assert_eq!(a.uuid(), b.uuid());
1048        assert_eq!(a.uuid(), b.uuid());
1049        let id = a.uuid();
1050        assert_eq!(id.get_version(), Some(uuid::Version::Random));
1051        // Different seeds diverge.
1052        assert_ne!(RngSource::seeded(1).uuid(), RngSource::seeded(2).uuid());
1053    }
1054
1055    #[test]
1056    fn system_defaults_match_pre_r05_shapes() {
1057        assert!(matches!(Clock::default(), Clock::System));
1058        assert!(matches!(RngSource::default(), RngSource::System));
1059    }
1060
1061    fn receipt(key: &str) -> EffectReceipt {
1062        EffectReceipt {
1063            provider: "stripe".into(),
1064            provider_id: "ch_3PKd".into(),
1065            idempotency_key: key.into(),
1066            task_id: Some("task-9".into()),
1067            effect_id: None,
1068        }
1069    }
1070
1071    #[test]
1072    fn effect_receipt_records_with_parentage_and_is_findable_by_key() {
1073        let j = journal();
1074        let step = j.record(EventDraft::new(RunEventKind::SuperStepStart, Effect::Pure));
1075        let event_id = j.record_effect_receipt(&receipt("run-1:charge:7"), Some(step.clone()));
1076
1077        let events = j.events();
1078        let recorded = events.last().unwrap();
1079        assert_eq!(recorded.id, event_id);
1080        assert_eq!(recorded.kind, RunEventKind::EffectReceipt);
1081        // The receipt is an Idempotent effect's confirmation — declared as
1082        // such so the replay/retry policies classify it like any other event.
1083        assert_eq!(recorded.effect, Effect::Idempotent);
1084        assert_eq!(recorded.parent.as_deref(), Some(step.as_str()));
1085
1086        // The lookup serves the receipt by idempotency key, and only it.
1087        let snapshot = j.snapshot();
1088        assert_eq!(
1089            snapshot.find_effect_receipt("run-1:charge:7"),
1090            Some(receipt("run-1:charge:7"))
1091        );
1092        assert_eq!(snapshot.find_effect_receipt("run-1:charge:8"), None);
1093
1094        // The journaled snapshot survives the integrity-verified reload with
1095        // the receipt still servable (the crash boundary the receipt exists
1096        // to cross).
1097        let rebuilt = Journal::from_snapshot(snapshot, Clock::System).unwrap();
1098        let snapshot = rebuilt.snapshot();
1099        assert_eq!(
1100            snapshot.find_effect_receipt("run-1:charge:7"),
1101            Some(receipt("run-1:charge:7"))
1102        );
1103    }
1104
1105    #[test]
1106    fn effect_receipt_records_without_a_parent() {
1107        let j = journal();
1108        j.record_effect_receipt(&receipt("k"), None);
1109        let event = j.events().pop().unwrap();
1110        assert_eq!(event.parent, None);
1111    }
1112
1113    #[test]
1114    fn effect_receipt_is_findable_by_effect_id() {
1115        use crate::effects::derive_effect_id;
1116
1117        let j = journal();
1118        // The recovery shape: the run re-derives the id of the effect it is
1119        // about to perform; the journal answers with the committed receipt.
1120        let committed = derive_effect_id(
1121            "run-1",
1122            "charge_card",
1123            &sha256_hex(b"input"),
1124            Some("run-1:charge:7"),
1125        );
1126        let mut with_id = receipt("run-1:charge:7");
1127        with_id.effect_id = Some(committed.as_str().to_owned());
1128        j.record_effect_receipt(&with_id, None);
1129        // A pre-kernel receipt (no effect id) coexisting in the same journal.
1130        j.record_effect_receipt(&receipt("run-1:legacy:1"), None);
1131
1132        let snapshot = j.snapshot();
1133        assert_eq!(
1134            snapshot.find_effect_receipt_by_effect_id(&committed),
1135            Some(with_id)
1136        );
1137        // An uncommitted derivation finds nothing, and a legacy receipt
1138        // without an effect id never matches the id lookup.
1139        let other = derive_effect_id(
1140            "run-1",
1141            "charge_card",
1142            &sha256_hex(b"input"),
1143            Some("run-1:charge:8"),
1144        );
1145        assert_eq!(snapshot.find_effect_receipt_by_effect_id(&other), None);
1146        assert!(snapshot
1147            .find_effect_receipt_by_effect_id(&derive_effect_id("run-1", "legacy", "x", None))
1148            .is_none());
1149    }
1150
1151    // ---- Artifact store + persistence seam (R0.7 wave 4) ----
1152
1153    /// Unique temp root under the OS temp dir, removed on drop.
1154    struct TestDir(PathBuf);
1155
1156    impl TestDir {
1157        fn new() -> Self {
1158            Self(std::env::temp_dir().join(format!("rusty-artifact-test-{}", uuid::Uuid::new_v4())))
1159        }
1160    }
1161
1162    impl Drop for TestDir {
1163        fn drop(&mut self) {
1164            let _ = std::fs::remove_dir_all(&self.0);
1165        }
1166    }
1167
1168    fn big_payload() -> Value {
1169        json!({"blob": "x".repeat(INLINE_PAYLOAD_MAX_BYTES)})
1170    }
1171
1172    #[tokio::test]
1173    async fn file_artifact_store_roundtrip_and_dedupe() {
1174        let tmp = TestDir::new();
1175        let store = FileArtifactStore::new(tmp.0.clone());
1176
1177        let bytes = serde_json::to_vec(&big_payload()).unwrap();
1178        let reference = store.put(&bytes).await.unwrap();
1179        assert_eq!(reference.sha256, sha256_hex(&bytes));
1180        assert_eq!(reference.bytes as usize, bytes.len());
1181        assert!(store.contains(&reference.sha256).await.unwrap());
1182        assert!(!store.contains(&sha256_hex(b"never stored")).await.unwrap());
1183
1184        // Dedupe by construction: re-putting the same content is a no-op
1185        // returning the same address, and the file count stays one.
1186        let again = store.put(&bytes).await.unwrap();
1187        assert_eq!(again, reference);
1188        assert_eq!(std::fs::read_dir(&tmp.0).unwrap().count(), 1);
1189
1190        // Read verifies integrity and returns the addressed bytes.
1191        assert_eq!(store.get(&reference.sha256).await.unwrap(), bytes);
1192    }
1193
1194    #[tokio::test]
1195    async fn file_artifact_store_detects_corruption_on_read() {
1196        let tmp = TestDir::new();
1197        let store = FileArtifactStore::new(tmp.0.clone());
1198
1199        let bytes = b"genuine payload".repeat(1024);
1200        let reference = store.put(&bytes).await.unwrap();
1201        // Tamper with the stored bytes: the next read must fail integrity,
1202        // not return corrupt data.
1203        std::fs::write(tmp.0.join(&reference.sha256), b"tampered").unwrap();
1204        let err = store.get(&reference.sha256).await.unwrap_err();
1205        assert!(err.to_string().contains("integrity failure"), "got: {err}");
1206
1207        // A missing artifact is an error, never an empty read.
1208        assert!(store.get(&sha256_hex(b"missing")).await.is_err());
1209    }
1210
1211    #[tokio::test]
1212    async fn externalized_snapshot_spills_and_resolves_artifacts() {
1213        let tmp = TestDir::new();
1214        let store = FileArtifactStore::new(tmp.0.clone());
1215
1216        let j = journal();
1217        let big = big_payload();
1218        j.record(EventDraft::new(RunEventKind::SuperStepStart, Effect::Pure));
1219        j.record(
1220            EventDraft::new(RunEventKind::ModelCall, Effect::NonIdempotent).output(big.clone()),
1221        );
1222
1223        let externalized = j.snapshot_externalized(&store).await.unwrap();
1224        // Bytes left the snapshot: the artifact map is empty, the reference
1225        // ledger points at the store, and the wire shows it.
1226        assert!(externalized.artifacts.is_empty());
1227        assert_eq!(externalized.artifact_refs.len(), 1);
1228        let wire = serde_json::to_string(&externalized).unwrap();
1229        assert!(wire.contains("\"artifact_refs\""));
1230
1231        // The event still references the same content address, and the
1232        // store holds the bytes under it.
1233        let event = &externalized.events[1];
1234        let Some(PayloadRef::Artifact(reference)) = event.output.as_ref() else {
1235            panic!("large payload must be artifact-referenced");
1236        };
1237        assert!(store.contains(&reference.sha256).await.unwrap());
1238
1239        // Loading an externalized snapshot WITHOUT the store is a hard
1240        // error — never a silently unresolvable journal.
1241        let parsed: JournalSnapshot = serde_json::from_str(&wire).unwrap();
1242        assert!(Journal::from_snapshot(parsed, Clock::System).is_err());
1243
1244        // With the store, the load resolves artifacts and re-verifies the
1245        // head hash over events.
1246        let parsed: JournalSnapshot = serde_json::from_str(&wire).unwrap();
1247        let rebuilt = Journal::from_snapshot_with_store(parsed, &store, Clock::System)
1248            .await
1249            .unwrap();
1250        assert_eq!(rebuilt.head_hash(), j.head_hash());
1251        assert_eq!(
1252            rebuilt.resolve(rebuilt.events()[1].output.as_ref().unwrap()),
1253            Some(big)
1254        );
1255
1256        // Re-externalizing the rebuilt journal re-puts nothing new (dedupe).
1257        let re = rebuilt.snapshot_externalized(&store).await.unwrap();
1258        assert_eq!(re.artifact_refs, externalized.artifact_refs);
1259    }
1260
1261    #[test]
1262    fn embedded_byte_snapshots_keep_deserializing() {
1263        // The pre-W4 wire shape: no `artifact_refs` key at all.
1264        let j = journal();
1265        j.record(
1266            EventDraft::new(RunEventKind::SuperStepStart, Effect::Pure).input(json!({"s": 0})),
1267        );
1268        let snapshot = j.snapshot();
1269        let mut wire: serde_json::Map<String, Value> =
1270            serde_json::from_str(&serde_json::to_string(&snapshot).unwrap()).unwrap();
1271        assert!(
1272            wire.remove("artifact_refs").is_none(),
1273            "embedded snapshots must not emit artifact_refs"
1274        );
1275        let text = serde_json::to_string(&Value::Object(wire)).unwrap();
1276        let parsed: JournalSnapshot = serde_json::from_str(&text).unwrap();
1277        assert!(parsed.artifact_refs.is_empty());
1278        // And the snapshot loads through the ordinary integrity-verified path.
1279        let rebuilt = Journal::from_snapshot(parsed, Clock::System).unwrap();
1280        assert_eq!(rebuilt.head_hash(), j.head_hash());
1281    }
1282}