Skip to main content

kizz_core/
explain.rs

1// Copyright (c) 2026 Sakura Industries LLC.
2//
3// SPDX-License-Identifier: AGPL-3.0-only
4
5//! Explaining decisions: why a step ran ("Explaining decisions").
6//!
7//! The engine turns the cache check's [`RunReason`](kizz_store::RunReason) into an
8//! [`Explanation`](kizz_store::Explanation) before a step runs:
9//!
10//! * A step key with no record is explained through the step-position records: when the
11//!   task used another key at the same position last time, the reasons compare that key's
12//!   specification with this one. The task program, the arguments, the environment, the
13//!   working directory, `stdin`, the capture mode, the ignore patterns, the `track`
14//!   patterns, the `timestamps` option, and the `machine` names each give their own
15//!   reason; a changed program names its block or each loaded module that changed, from
16//!   the part hashes of the task record. Without an earlier specification, or when only
17//!   the occurrence number differs, the step never ran.
18//! * A step whose record names parts of the machine state, and whose cache check found
19//!   values of them changed, gives a reason of its own that names each changed value, old
20//!   and new, after the changed inputs.
21//! * Each changed input names who last wrote it, from the last-writer records: this
22//!   command on its previous run, another step in this build, a step of an earlier build,
23//!   the program of a task, through `fs.write` or `fs.write_json`, in this build or an
24//!   earlier one, or something outside kizz. A write that kizz recorded before the step's
25//!   recorded state was taken cannot have changed the path since, so then the writer is
26//!   something outside kizz. A task program is named as the writer even when it is the
27//!   program of the step's own task.
28//! * A changed input is self-inflicted when this command last wrote it on its previous
29//!   run and also reads it, or when the step that wrote it in this build runs on every
30//!   build, because it is marked `always`, its task is marked `cache=never`, or it
31//!   re-runs for a self-inflicted reason itself. A path the command read and wrote before
32//!   is not self-inflicted when something outside kizz, another task, or a task program
33//!   changed it since; a change that a task program made is never self-inflicted.
34//! * A step that re-runs for a self-inflicted input that also made it run in its task's
35//!   previous build gets the loud warning for consecutive builds: the step-position
36//!   record carries the self-inflicted inputs of the previous build's run.
37
38use std::{
39    collections::{BTreeMap, BTreeSet},
40    path::PathBuf,
41};
42
43use kizz_store::{
44    AccessBits, BuildId, ChangedInput, ContentHash, Difference, EnvChange, LastWriter,
45    ModuleChange, ModuleChangeKind, ModuleHash, Observation, PathKey, PositionKey, Reason,
46    SelfInflicted, StepKey, StepPosition, StepSpecRecord, StoreError, TaskId, TaskLabel,
47    TaskRecord, Txn, Verdict, Writer, WrittenBy,
48};
49use kizz_trace::AbsolutePath;
50
51use crate::runtime::{ProgramHash, ProgramParts, TaskProgram};
52
53/// The identity of a task whose steps the engine runs: what its step positions,
54/// last writers, and task record are stored under, and how output names it.
55#[derive(Debug, Clone, PartialEq, Eq)]
56pub struct TaskIdentity {
57    /// The task: the absolute path of its `kizz.md` and its index in the file.
58    pub id: TaskId,
59    /// The line of the block's opening fence, counting from 1.
60    pub line: u32,
61    /// The nearest heading above the block, if there is one.
62    pub heading: Option<String>,
63    /// The targets on the block, in the order written.
64    pub targets: Vec<String>,
65    /// The hash of the task program.
66    pub program: ProgramHash,
67    /// The hashes of the program's block and modules.
68    pub parts: ProgramParts,
69    /// The task directory, at which relative patterns are anchored.
70    pub dir: AbsolutePath,
71}
72
73impl TaskIdentity {
74    /// The identity of the task of the loaded program `program`.
75    #[must_use]
76    pub fn of(program: &TaskProgram) -> Self {
77        let task = program.task();
78        Self {
79            id: TaskId {
80                file: task.file.as_path().to_path_buf(),
81                index: task.index,
82            },
83            line: u32::try_from(task.line).unwrap_or(u32::MAX),
84            heading: task.heading.clone(),
85            targets: task.targets.clone(),
86            program: program.hash(),
87            parts: program.parts().clone(),
88            dir: task.dir.clone(),
89        }
90    }
91
92    /// The task as explanations name it.
93    #[must_use]
94    pub fn label(&self) -> TaskLabel {
95        TaskLabel {
96            task: self.id.clone(),
97            line: self.line,
98            heading: self.heading.clone(),
99        }
100    }
101
102    /// The task record of a run in `build` that had `steps` steps and ended as
103    /// `succeeded` says.
104    #[must_use]
105    pub fn task_record(
106        &self,
107        succeeded: bool,
108        build: BuildId,
109        steps: u32,
110    ) -> TaskRecord {
111        TaskRecord {
112            program_hash: *self.program.as_bytes(),
113            succeeded,
114            build,
115            steps,
116            line: self.line,
117            heading: self.heading.clone(),
118            targets: self.targets.clone(),
119            block: ContentHash(self.parts.block),
120            modules: self
121                .parts
122                .modules
123                .iter()
124                .map(|(path, hash)| {
125                    ModuleHash {
126                        path: path.clone(),
127                        hash: ContentHash(*hash),
128                    }
129                })
130                .collect(),
131        }
132    }
133}
134
135/// What a build decided about one step of a task run, for the line `kizz build`
136/// prints for each command it runs and for `--explain`.
137#[derive(Debug, Clone, PartialEq, Eq)]
138pub struct StepDecision {
139    /// The position of the step in the task's run, counting from zero.
140    pub position: u32,
141    /// The command: the argument vector joined with spaces.
142    pub command: String,
143    /// What the build decided.
144    pub verdict: Verdict,
145}
146
147/// The loud warning for a step that re-ran in consecutive builds for the same
148/// self-inflicted reason.
149#[derive(Debug, Clone, PartialEq, Eq)]
150pub struct RepeatedWarning {
151    /// The step's task, or `None` for steps run without a task identity.
152    pub task: Option<TaskLabel>,
153    /// The position of the step in the task's run, counting from zero.
154    pub position: u32,
155    /// The command: the argument vector joined with spaces.
156    pub command: String,
157    /// The self-inflicted inputs that made the step run in both builds, sorted.
158    pub paths: Vec<PathBuf>,
159}
160
161/// The recorded state a cache check compared the file system with: the paths the
162/// step wrote and also read, and when the state was taken.
163#[derive(Debug, Clone, PartialEq, Eq, Default)]
164pub struct Baseline {
165    /// When kizz began recording the states, in nanoseconds since the Unix epoch.
166    pub recorded_at_nanos: u64,
167    /// The recorded paths that the step both wrote and read.
168    pub writes_and_reads: BTreeSet<PathBuf>,
169}
170
171impl Baseline {
172    /// The baseline of the observations `observations`, recorded at
173    /// `recorded_at_nanos`.
174    #[must_use]
175    pub fn new(
176        observations: &[Observation],
177        recorded_at_nanos: u64,
178    ) -> Self {
179        Self {
180            recorded_at_nanos,
181            writes_and_reads: observations
182                .iter()
183                .filter(|observation| {
184                    observation.access.contains(AccessBits::WRITE)
185                        && observation.access.contains(AccessBits::READ)
186                })
187                .map(|observation| observation.path.clone())
188                .collect(),
189        }
190    }
191}
192
193/// What attributing the changed inputs of one step needs.
194#[derive(Debug, Clone, Copy)]
195pub struct InputContext<'a> {
196    /// The step's task, if it has an identity.
197    pub identity: Option<&'a TaskIdentity>,
198    /// The position of the step in the task's run.
199    pub position: u32,
200    /// The step key.
201    pub key: StepKey,
202    /// The current build.
203    pub build: BuildId,
204    /// The recorded state the cache check compared the file system with.
205    pub baseline: Option<&'a Baseline>,
206}
207
208/// The reasons that compare `old`, the specification the task used last time at
209/// the same position, with `new`, in the order of the spec's list.
210///
211/// A changed program names its block and each changed, added, or removed module
212/// when `old_task` is the task record of `old`'s program and `new_parts` holds the
213/// parts of `new`'s program; otherwise it names no part.
214#[must_use]
215pub fn spec_reasons(
216    old: &StepSpecRecord,
217    new: &StepSpecRecord,
218    old_task: Option<&TaskRecord>,
219    new_parts: Option<&ProgramParts>,
220) -> Vec<Reason> {
221    let mut reasons = Vec::new();
222    if old.program_hash != new.program_hash {
223        reasons.push(program_reason(old, old_task, new_parts));
224    }
225    if old.argv != new.argv {
226        reasons.push(Reason::ArgumentsChanged {
227            old: old.argv.clone(),
228            new: new.argv.clone(),
229        });
230    }
231    let changes = env_changes(&old.env, &new.env);
232    if !changes.is_empty() {
233        reasons.push(Reason::EnvironmentChanged { changes });
234    }
235    if old.cwd != new.cwd {
236        reasons.push(Reason::WorkingDirectoryChanged {
237            old: old.cwd.clone(),
238            new: new.cwd.clone(),
239        });
240    }
241    if old.stdin != new.stdin {
242        reasons.push(Reason::StdinChanged {
243            old: old.stdin.clone(),
244            new: new.stdin.clone(),
245        });
246    }
247    if old.capture != new.capture {
248        reasons.push(Reason::CaptureChanged {
249            old: old.capture,
250            new: new.capture,
251        });
252    }
253    if old.ignore != new.ignore {
254        reasons.push(Reason::IgnoreChanged {
255            old: old.ignore.clone(),
256            new: new.ignore.clone(),
257        });
258    }
259    if old.track != new.track {
260        reasons.push(Reason::TrackChanged {
261            old: old.track.clone(),
262            new: new.track.clone(),
263        });
264    }
265    if old.timestamps != new.timestamps {
266        reasons.push(Reason::TimestampsChanged {
267            old: old.timestamps,
268            new: new.timestamps,
269        });
270    }
271    if old.untraced != new.untraced {
272        reasons.push(Reason::TracingChanged {
273            old: old.untraced,
274            new: new.untraced,
275        });
276    }
277    if old.machine != new.machine {
278        reasons.push(Reason::MachineNamesChanged {
279            old: old.machine.clone(),
280            new: new.machine.clone(),
281        });
282    }
283    reasons
284}
285
286/// The reason for a changed task program: which parts changed, when the parts of
287/// both programs are known.
288fn program_reason(
289    old: &StepSpecRecord,
290    old_task: Option<&TaskRecord>,
291    new_parts: Option<&ProgramParts>,
292) -> Reason {
293    let unknown = Reason::ProgramChanged {
294        block: false,
295        modules: Vec::new(),
296    };
297    let (Some(old_task), Some(new_parts)) = (old_task, new_parts) else {
298        return unknown;
299    };
300    if old_task.program_hash != old.program_hash.0 {
301        return unknown;
302    }
303    let old_modules: BTreeMap<&PathBuf, &ContentHash> = old_task
304        .modules
305        .iter()
306        .map(|module| (&module.path, &module.hash))
307        .collect();
308    let new_modules: BTreeMap<&PathBuf, ContentHash> = new_parts
309        .modules
310        .iter()
311        .map(|(path, hash)| (path, ContentHash(*hash)))
312        .collect();
313    let paths: BTreeSet<&PathBuf> = old_modules
314        .keys()
315        .chain(new_modules.keys())
316        .copied()
317        .collect();
318    let modules = paths
319        .into_iter()
320        .filter_map(|path| {
321            let kind = match (old_modules.get(path), new_modules.get(path)) {
322                (Some(old), Some(new)) if *old == new => return None,
323                (Some(_), Some(_)) => ModuleChangeKind::Changed,
324                (None, _) => ModuleChangeKind::Added,
325                (Some(_), None) => ModuleChangeKind::Removed,
326            };
327            Some(ModuleChange {
328                path: path.clone(),
329                kind,
330            })
331        })
332        .collect();
333    Reason::ProgramChanged {
334        block: old_task.block.0 != new_parts.block,
335        modules,
336    }
337}
338
339/// Every variable added, removed, or changed between `old` and `new`, sorted by
340/// name.
341fn env_changes(
342    old: &BTreeMap<String, String>,
343    new: &BTreeMap<String, String>,
344) -> Vec<EnvChange> {
345    let names: BTreeSet<&String> = old.keys().chain(new.keys()).collect();
346    names
347        .into_iter()
348        .filter_map(|name| {
349            let (old, new) = (old.get(name), new.get(name));
350            (old != new).then(|| {
351                EnvChange {
352                    name: name.clone(),
353                    old: old.cloned(),
354                    new: new.cloned(),
355                }
356            })
357        })
358        .collect()
359}
360
361/// Every changed input of `differences`, with who last wrote it and whether the
362/// change is self-inflicted.
363///
364/// # Errors
365///
366/// A [`StoreError`] when a record cannot be read.
367pub fn changed_inputs(
368    txn: &Txn<'_>,
369    context: &InputContext<'_>,
370    differences: &[Difference],
371) -> Result<Vec<ChangedInput>, StoreError> {
372    differences
373        .iter()
374        .map(|difference| {
375            let entry = txn.get::<LastWriter>(&PathKey(difference.path.clone()))?;
376            let writer = attribute(txn, context, entry.as_ref())?;
377            // The change is this command's own doing only when kizz attributes the
378            // write to this command; a path it read and wrote before can still be
379            // changed outside kizz or by another task.
380            let writes_and_reads = writer == Writer::ThisCommand
381                && context
382                    .baseline
383                    .is_some_and(|baseline| baseline.writes_and_reads.contains(&difference.path));
384            let self_inflicted = if writes_and_reads {
385                Some(SelfInflicted::WritesAndReads)
386            } else if let (Writer::ThisBuild { task, position }, Some(entry)) = (&writer, &entry)
387                && writes_every_build(txn, entry, context.build)?
388            {
389                Some(SelfInflicted::WrittenEveryBuild {
390                    task: task.clone(),
391                    position: *position,
392                })
393            } else {
394                None
395            };
396            Ok(ChangedInput {
397                path: difference.path.clone(),
398                change: difference.change.clone(),
399                writer,
400                self_inflicted,
401            })
402        })
403        .collect()
404}
405
406/// Who last wrote a changed input whose last-writer record is `entry`.
407fn attribute(
408    txn: &Txn<'_>,
409    context: &InputContext<'_>,
410    entry: Option<&LastWriter>,
411) -> Result<Writer, StoreError> {
412    let Some(entry) = entry else {
413        return Ok(Writer::Outside);
414    };
415    let baseline_at = context
416        .baseline
417        .map_or(0, |baseline| baseline.recorded_at_nanos);
418    if entry.written_at_nanos <= baseline_at {
419        // The recorded state already includes that write, so whatever changed the
420        // path since did so outside kizz.
421        return Ok(Writer::Outside);
422    }
423    let this_build = entry.build == context.build;
424    let WrittenBy::Step { step, position } = entry.by else {
425        let task = label_of(txn, context.identity, &entry.task)?;
426        return Ok(if this_build {
427            Writer::ProgramThisBuild { task }
428        } else {
429            Writer::ProgramEarlierBuild { task }
430        });
431    };
432    let same_position = context
433        .identity
434        .is_some_and(|identity| identity.id == entry.task && position == context.position);
435    if step == context.key || same_position {
436        return Ok(Writer::ThisCommand);
437    }
438    let task = label_of(txn, context.identity, &entry.task)?;
439    Ok(if this_build {
440        Writer::ThisBuild { task, position }
441    } else {
442        Writer::EarlierBuild { task, position }
443    })
444}
445
446/// The label of the task `task`: from `identity` when it is that task, otherwise
447/// from its task record, and otherwise with an unknown line.
448fn label_of(
449    txn: &Txn<'_>,
450    identity: Option<&TaskIdentity>,
451    task: &TaskId,
452) -> Result<TaskLabel, StoreError> {
453    if let Some(identity) = identity.filter(|identity| identity.id == *task) {
454        return Ok(identity.label());
455    }
456    Ok(match txn.get::<TaskRecord>(task)? {
457        Some(record) => {
458            TaskLabel {
459                task: task.clone(),
460                line: record.line,
461                heading: record.heading,
462            }
463        },
464        None => {
465            TaskLabel {
466                task: task.clone(),
467                line: 0,
468                heading: None,
469            }
470        },
471    })
472}
473
474/// Whether the step that `entry` names, which wrote its path in `build`, runs on
475/// every build: in this build it ran because it is marked `always`, because its task
476/// is marked `cache=never`, or for a self-inflicted reason. A task program is not a
477/// step, so this is never so for one.
478fn writes_every_build(
479    txn: &Txn<'_>,
480    entry: &LastWriter,
481    build: BuildId,
482) -> Result<bool, StoreError> {
483    let WrittenBy::Step { step, position } = entry.by else {
484        return Ok(false);
485    };
486    let position_record = txn.get::<StepPosition>(&PositionKey {
487        task: entry.task.clone(),
488        position,
489    })?;
490    Ok(position_record.is_some_and(|record| {
491        record.build == build
492            && record.step == step
493            && matches!(&record.verdict, Verdict::Ran(explanation) if explanation.runs_every_build())
494    }))
495}
496
497/// The self-inflicted inputs that made the step at a position run in its task's
498/// previous build, sorted, given `previous`, the step-position record before this
499/// build's decision.
500///
501/// Within one build the record keeps what it carried; in a new build it carries
502/// the self-inflicted inputs of the run it records, and nothing when the step was
503/// cached.
504#[must_use]
505pub fn carried_from(
506    previous: Option<&StepPosition>,
507    build: BuildId,
508) -> Vec<PathBuf> {
509    match previous {
510        Some(previous) if previous.build == build => previous.carried.clone(),
511        Some(StepPosition {
512            verdict: Verdict::Ran(explanation),
513            ..
514        }) => explanation.self_inflicted(),
515        Some(_) | None => Vec::new(),
516    }
517}
518
519/// Unit tests for the comparison of specifications and the carried inputs.
520#[cfg(test)]
521#[allow(
522    clippy::disallowed_macros,
523    clippy::disallowed_methods,
524    reason = "test code: the tests assert and lock"
525)]
526mod tests {
527    use kizz_store::{Capture, Change, Explanation};
528
529    use super::*;
530
531    /// A specification.
532    fn spec() -> StepSpecRecord {
533        StepSpecRecord {
534            program_hash: ContentHash([1; 32]),
535            cwd: PathBuf::from("/w"),
536            argv: vec!["cc".to_owned(), "-O2".to_owned()],
537            env: [
538                ("KEEP".to_owned(), "1".to_owned()),
539                ("GONE".to_owned(), "2".to_owned()),
540                ("EDIT".to_owned(), "3".to_owned()),
541            ]
542            .into(),
543            stdin: None,
544            capture: Capture::Split,
545            stream: false,
546            always: false,
547            untraced: false,
548            ignore: Vec::new(),
549            track: Vec::new(),
550            timestamps: false,
551            machine: Vec::new(),
552            expect: None,
553            occurrence: 0,
554        }
555    }
556
557    /// A task record of the program of [`spec`], with module `a` and `b`.
558    fn old_task() -> TaskRecord {
559        TaskRecord {
560            program_hash: [1; 32],
561            succeeded: true,
562            build: BuildId(1),
563            steps: 1,
564            line: 1,
565            heading: None,
566            targets: Vec::new(),
567            block: ContentHash([7; 32]),
568            modules: vec![
569                ModuleHash {
570                    path: PathBuf::from("/w/a.star"),
571                    hash: ContentHash([2; 32]),
572                },
573                ModuleHash {
574                    path: PathBuf::from("/w/b.star"),
575                    hash: ContentHash([3; 32]),
576                },
577            ],
578        }
579    }
580
581    #[test]
582    fn identical_specifications_have_no_reasons() {
583        assert_eq!(
584            spec_reasons(&spec(), &spec(), None, None),
585            Vec::<Reason>::new()
586        );
587        let mut repeated = spec();
588        repeated.occurrence = 1;
589        repeated.stream = true;
590        repeated.always = true;
591        repeated.expect = Some(vec![0]);
592        assert_eq!(
593            spec_reasons(&spec(), &repeated, None, None),
594            Vec::<Reason>::new()
595        );
596    }
597
598    #[test]
599    fn every_changed_value_gives_its_reason_in_order() {
600        let mut new = spec();
601        new.program_hash = ContentHash([9; 32]);
602        new.argv = vec!["cc".to_owned(), "-O0".to_owned()];
603        new.env.remove("GONE");
604        new.env.insert("EDIT".to_owned(), "4".to_owned());
605        new.env.insert("ADDED".to_owned(), "5".to_owned());
606        new.cwd = PathBuf::from("/x");
607        new.stdin = Some("in".to_owned());
608        new.capture = Capture::Merged;
609        new.ignore = vec!["*.o".to_owned()];
610        new.track = vec!["/proc/cpuinfo".to_owned()];
611        new.timestamps = true;
612        new.machine = vec!["kernel".to_owned()];
613        let parts = ProgramParts {
614            block: [7; 32],
615            modules: vec![
616                (PathBuf::from("/w/a.star"), [2; 32]),
617                (PathBuf::from("/w/b.star"), [4; 32]),
618                (PathBuf::from("/w/c.star"), [5; 32]),
619            ],
620        };
621        let reasons = spec_reasons(&spec(), &new, Some(&old_task()), Some(&parts));
622        assert_eq!(reasons, vec![
623            Reason::ProgramChanged {
624                block: false,
625                modules: vec![
626                    ModuleChange {
627                        path: PathBuf::from("/w/b.star"),
628                        kind: ModuleChangeKind::Changed,
629                    },
630                    ModuleChange {
631                        path: PathBuf::from("/w/c.star"),
632                        kind: ModuleChangeKind::Added,
633                    },
634                ],
635            },
636            Reason::ArgumentsChanged {
637                old: spec().argv,
638                new: new.argv.clone(),
639            },
640            Reason::EnvironmentChanged {
641                changes: vec![
642                    EnvChange {
643                        name: "ADDED".to_owned(),
644                        old: None,
645                        new: Some("5".to_owned()),
646                    },
647                    EnvChange {
648                        name: "EDIT".to_owned(),
649                        old: Some("3".to_owned()),
650                        new: Some("4".to_owned()),
651                    },
652                    EnvChange {
653                        name: "GONE".to_owned(),
654                        old: Some("2".to_owned()),
655                        new: None,
656                    },
657                ],
658            },
659            Reason::WorkingDirectoryChanged {
660                old: PathBuf::from("/w"),
661                new: PathBuf::from("/x"),
662            },
663            Reason::StdinChanged {
664                old: None,
665                new: Some("in".to_owned()),
666            },
667            Reason::CaptureChanged {
668                old: Capture::Split,
669                new: Capture::Merged,
670            },
671            Reason::IgnoreChanged {
672                old: Vec::new(),
673                new: vec!["*.o".to_owned()],
674            },
675            Reason::TrackChanged {
676                old: Vec::new(),
677                new: vec!["/proc/cpuinfo".to_owned()],
678            },
679            Reason::TimestampsChanged {
680                old: false,
681                new: true,
682            },
683            Reason::MachineNamesChanged {
684                old: Vec::new(),
685                new: vec!["kernel".to_owned()],
686            },
687        ]);
688    }
689
690    #[test]
691    fn a_changed_program_names_its_parts_only_when_they_are_known() {
692        let mut new = spec();
693        new.program_hash = ContentHash([9; 32]);
694        let parts = ProgramParts {
695            block: [8; 32],
696            modules: vec![(PathBuf::from("/w/a.star"), [2; 32])],
697        };
698        assert_eq!(
699            spec_reasons(&spec(), &new, Some(&old_task()), Some(&parts)),
700            vec![Reason::ProgramChanged {
701                block: true,
702                modules: vec![ModuleChange {
703                    path: PathBuf::from("/w/b.star"),
704                    kind: ModuleChangeKind::Removed,
705                }],
706            }]
707        );
708        let unknown = vec![Reason::ProgramChanged {
709            block: false,
710            modules: Vec::new(),
711        }];
712        assert_eq!(spec_reasons(&spec(), &new, None, Some(&parts)), unknown);
713        let mut other = old_task();
714        other.program_hash = [5; 32];
715        assert_eq!(
716            spec_reasons(&spec(), &new, Some(&other), Some(&parts)),
717            unknown
718        );
719    }
720
721    #[test]
722    fn positions_carry_the_self_inflicted_inputs_of_the_previous_build() {
723        let input = ChangedInput {
724            path: PathBuf::from("/w/cache"),
725            change: Change::Content,
726            writer: Writer::Outside,
727            self_inflicted: Some(SelfInflicted::WritesAndReads),
728        };
729        let ran = StepPosition {
730            step: StepKey([1; 32]),
731            build: BuildId(1),
732            verdict: Verdict::Ran(Explanation {
733                reasons: vec![Reason::InputsChanged {
734                    inputs: vec![input],
735                }],
736                repeated: Vec::new(),
737            }),
738            carried: vec![PathBuf::from("/w/older")],
739        };
740        assert_eq!(carried_from(Some(&ran), BuildId(2)), [PathBuf::from(
741            "/w/cache"
742        )]);
743        assert_eq!(carried_from(Some(&ran), BuildId(1)), [PathBuf::from(
744            "/w/older"
745        )]);
746        let cached = StepPosition {
747            verdict: Verdict::Cached,
748            ..ran
749        };
750        assert_eq!(
751            carried_from(Some(&cached), BuildId(2)),
752            Vec::<PathBuf>::new()
753        );
754        assert_eq!(carried_from(None, BuildId(2)), Vec::<PathBuf>::new());
755    }
756
757    #[test]
758    fn a_baseline_keeps_the_paths_written_and_read() {
759        let observation = |path: &str, access| {
760            Observation {
761                path: PathBuf::from(path),
762                access: AccessBits(access),
763                tracked: false,
764                state: kizz_store::PathState::Absent,
765                attributes: None,
766            }
767        };
768        let baseline = Baseline::new(
769            &[
770                observation("/both", AccessBits::READ | AccessBits::WRITE),
771                observation("/written", AccessBits::WRITE),
772                observation("/read", AccessBits::READ),
773            ],
774            5,
775        );
776        assert_eq!(baseline.recorded_at_nanos, 5);
777        assert_eq!(
778            baseline.writes_and_reads,
779            [PathBuf::from("/both")].into_iter().collect()
780        );
781    }
782}