Adopt journal, ledger, and trail as internal terminology

Author: istathar

AGENTS.md

@@ -290,7 +290,7 @@ where the fields are
 - `()` the value of the step or state, if any, in this case Unitus.
 
 Results are written to the @./.store/ directory, and serve both as the
-permanent record of a step having been completed and also as a trace allowing
+permanent record of a step having been completed and also as a journal allowing
 the procedure to be resumed if interrupted. The line format is serialized by
 @src/runner/state.rs, which is authoritative.
 

src/engraving/checks/ledger.rs

@@ -310,7 +310,7 @@ fn an_orphaned_scope_does_not_adopt_what_opens_after_it() {
 fn a_resumed_scope_keeps_the_serial_it_was_entered_at() {
     // A scope opened after an orphan is found again on the next walk, so
     // resuming does not write a second `Begin` for it. It did, and each resume
-    // then mis-parented the next, ratcheting a duplicate spine onto the trail
+    // then mis-parented the next, ratcheting a duplicate spine onto the journal
     // one pair of records at a time.
     let ledger = fold(vec![
         record(1, "/task:", State::Begin(Vec::new())),

src/engraving/checks/navigation.rs

@@ -1,4 +1,4 @@
-use crate::engraving::{InvokeTarget, Motion, Position, Record, RunId, Serial, State, Trail};
+use crate::engraving::{InvokeTarget, Journal, Motion, Position, Record, RunId, Serial, State};
 
 fn record(serial: u32, path: &str, state: State) -> Record {
     Record {
@@ -10,7 +10,7 @@ fn record(serial: u32, path: &str, state: State) -> Record {
     }
 }
 
-// A step invoking a procedure, which the trail writes at a path beside the
+// A step invoking a procedure, which the journal writes at a path beside the
 // step rather than beneath it.
 fn calling() -> Vec<Record> {
     vec![
@@ -40,42 +40,42 @@ fn calling() -> Vec<Record> {
 #[test]
 fn a_callee_is_enclosed_by_its_call_site() {
     let records = calling();
-    let trail = Trail::new(&records);
+    let journal = Journal::new(&records);
 
     assert_eq!(
-        trail.step(Position::At(4), Motion::Left),
+        journal.step(Position::At(4), Motion::Left),
         Some(Position::At(2))
     );
     assert_eq!(
-        trail.step(Position::At(3), Motion::Right),
+        journal.step(Position::At(3), Motion::Right),
         Some(Position::At(4))
     );
-    assert_eq!(trail.step(Position::At(4), Motion::PageUp), None);
-    assert_eq!(trail.step(Position::At(4), Motion::PageDown), None);
+    assert_eq!(journal.step(Position::At(4), Motion::PageUp), None);
+    assert_eq!(journal.step(Position::At(4), Motion::PageDown), None);
 }
 
 /// Down off the last record reaches the prompt the run is waiting at, and a
 /// run that walked to its end has no prompt to reach.
 #[test]
 fn down_off_the_end_leaves_review() {
     let records = calling();
-    let trail = Trail::new(&records);
+    let journal = Journal::new(&records);
     assert_eq!(
-        trail.step(Position::At(7), Motion::Down),
+        journal.step(Position::At(7), Motion::Down),
         Some(Position::Live)
     );
     assert_eq!(
-        trail.step(Position::Live, Motion::Up),
+        journal.step(Position::Live, Motion::Up),
         Some(Position::At(7))
     );
-    assert_eq!(trail.step(Position::Live, Motion::Down), None);
+    assert_eq!(journal.step(Position::Live, Motion::Down), None);
 
     let mut ended = calling();
     ended.push(record(0, "/", State::Finish));
-    let trail = Trail::new(&ended);
-    assert_eq!(trail.last(), Some(Position::At(7)));
-    assert_eq!(trail.step(Position::At(7), Motion::Down), None);
-    assert_eq!(trail.step(Position::At(0), Motion::Up), None);
+    let journal = Journal::new(&ended);
+    assert_eq!(journal.last(), Some(Position::At(7)));
+    assert_eq!(journal.step(Position::At(7), Motion::Down), None);
+    assert_eq!(journal.step(Position::At(0), Motion::Up), None);
 }
 
 /// `Stop` and `Resume` bracket a session, not the walk. Review opens on the
@@ -88,24 +88,24 @@ fn a_session_boundary_is_not_a_position() {
     records.insert(6, record(0, "/", State::Stop));
     records.push(record(0, "/", State::Stop));
     records.push(record(0, "/", State::Resume));
-    let trail = Trail::new(&records);
+    let journal = Journal::new(&records);
 
-    assert_eq!(trail.last(), Some(Position::At(9)));
+    assert_eq!(journal.last(), Some(Position::At(9)));
     assert_eq!(
-        trail.step(Position::Live, Motion::Up),
+        journal.step(Position::Live, Motion::Up),
         Some(Position::At(9))
     );
     // 5 and 8 are the records either side of the interruption.
     assert_eq!(
-        trail.step(Position::At(8), Motion::Up),
+        journal.step(Position::At(8), Motion::Up),
         Some(Position::At(5))
     );
     assert_eq!(
-        trail.step(Position::At(5), Motion::Down),
+        journal.step(Position::At(5), Motion::Down),
         Some(Position::At(8))
     );
     assert_eq!(
-        trail.step(Position::At(9), Motion::Down),
+        journal.step(Position::At(9), Motion::Down),
         Some(Position::Live)
     );
 }
@@ -139,19 +139,19 @@ fn redispatched() -> Vec<Record> {
 #[test]
 fn a_redispatched_call_is_one_place_to_stand() {
     // Two sessions reaching the same call wrote the dispatch line twice, and
-    // pressing Up walked both showing the same thing each time. The trail keeps
+    // pressing Up walked both showing the same thing each time. The journal keeps
     // them; the cursor stops on the last. A second call in the same step writes
     // a different line at the same address, and stands on its own.
     let records = redispatched();
-    let trail = Trail::new(&records);
+    let journal = Journal::new(&records);
 
-    let at = trail
+    let at = journal
         .last()
         .expect("a position to open on");
     assert_eq!(at, Position::At(6));
-    assert_eq!(trail.step(at, Motion::Up), Some(Position::At(5)));
+    assert_eq!(journal.step(at, Motion::Up), Some(Position::At(5)));
     assert_eq!(
-        trail.step(Position::At(5), Motion::Up),
+        journal.step(Position::At(5), Motion::Up),
         Some(Position::At(1))
     );
 }
@@ -172,11 +172,11 @@ fn two_invocations_of_one_procedure_both_stand() {
         record(5, "/task:/check:", State::Done(None)),
         record(4, "/task:/2", State::Done(None)),
     ];
-    let trail = Trail::new(&records);
+    let journal = Journal::new(&records);
 
     let mut at = Position::At(8);
     for expected in [7, 6, 5, 4, 3, 2, 1, 0] {
-        at = trail
+        at = journal
             .step(at, Motion::Up)
             .expect("every record stands as its own position");
         assert_eq!(at, Position::At(expected));
@@ -198,15 +198,15 @@ fn an_amended_answer_is_the_only_one_review_reaches() {
         record(3, "/task:/1", State::Begin(Vec::new())),
         record(3, "/task:/1", State::Done(None)),
     ];
-    let trail = Trail::new(&records);
+    let journal = Journal::new(&records);
 
-    let at = trail
+    let at = journal
         .last()
         .expect("a position to open on");
     assert_eq!(at, Position::At(5));
-    assert_eq!(trail.step(at, Motion::Up), Some(Position::At(4)));
+    assert_eq!(journal.step(at, Motion::Up), Some(Position::At(4)));
     assert_eq!(
-        trail.step(Position::At(4), Motion::Up),
+        journal.step(Position::At(4), Motion::Up),
         Some(Position::At(0))
     );
 }
@@ -228,14 +228,14 @@ fn a_revoked_scope_takes_what_it_held_with_it() {
         record(5, "/task:/check:/1", State::Done(None)),
         record(4, "/task:/check:", State::Done(None)),
     ];
-    let trail = Trail::new(&records);
+    let journal = Journal::new(&records);
 
     let mut at = Position::At(9);
     for expected in [8, 7, 6, 0] {
-        at = trail
+        at = journal
             .step(at, Motion::Up)
             .expect("the standing execution walks back to the root");
         assert_eq!(at, Position::At(expected));
     }
-    assert_eq!(trail.step(at, Motion::Up), None);
+    assert_eq!(journal.step(at, Motion::Up), None);
 }

src/engraving/checks/record.rs

@@ -179,7 +179,7 @@ fn create_and_open_round_trips_libraries() {
     assert_eq!(libraries, selected);
 }
 
-// One record line, for building a trail a test then writes to disk.
+// One record line, for building a journal a test then writes to disk.
 fn line(serial: u32, path: &str, state: State) -> String {
     format_record(&Record {
         recorded: format!("2026-05-14T12:00:{:02}Z", serial),

src/engraving/ledger.rs

@@ -48,7 +48,7 @@ impl Ledger {
         }
     }
 
-    /// Whether the trail already states this and still truly: the recorded
+    /// Whether the journal already states this and still truly: the recorded
     /// line stands, so there is nothing here to record.
     pub fn carries(&self, record: &Record) -> bool {
         match &record.state {

src/engraving/mod.rs

@@ -20,7 +20,7 @@ pub enum StoreError {
 }
 
 pub use ledger::{Entry, Ledger};
-pub use navigation::{Motion, Position, Trail};
+pub use navigation::{Journal, Motion, Position};
 pub use record::{
     InvokeTarget, Record, RecordError, RunId, Serial, State, Supplied, display_path, parse_records,
 };

src/engraving/navigation.rs

@@ -1,4 +1,4 @@
-//! Moving over the records of a trail: where the review cursor can rest and
+//! Moving over the records of a journal: where the review cursor can rest and
 //! what each keystroke reaches. Every record is a position; the tree the
 //! motions climb is the one the walk took, a callee enclosed by the step that
 //! invoked it rather than by the path it was written at.
@@ -56,15 +56,15 @@ struct Scope {
     outcome: Option<usize>,
 }
 
-/// The live tree of a trail, and the motions over it.
-pub struct Trail<'i> {
+/// The live tree of a journal, and the motions over it.
+pub struct Journal<'i> {
     records: &'i [Record],
     scopes: HashMap<Serial, Scope>,
     /// The scope each record was written against.
     within: Vec<Serial>,
     /// Scopes in the order they opened, which is the order peers stand in.
     opened: Vec<Serial>,
-    /// The records the cursor stops on, in trail order. `Stop`, `Resume` and
+    /// The records the cursor stops on, in journal order. `Stop`, `Resume` and
     /// `Finish` bracket a session rather than state anything the walk did, so
     /// they are not positions; `Start` is, being the root's own entry.
     order: Vec<usize>,
@@ -73,11 +73,11 @@ pub struct Trail<'i> {
     finished: bool,
 }
 
-impl<'i> Trail<'i> {
-    /// Fold a trail into the tree it built. The enclosing scope of each is
+impl<'i> Journal<'i> {
+    /// Fold a journal into the tree it built. The enclosing scope of each is
     /// whichever was innermost open when its `Begin` landed, so a procedure is
     /// enclosed by the step that invoked it.
-    pub fn new(records: &'i [Record]) -> Trail<'i> {
+    pub fn new(records: &'i [Record]) -> Journal<'i> {
         let mut scopes: HashMap<Serial, Scope> = HashMap::new();
         let mut within = Vec::with_capacity(records.len());
         let mut opened = Vec::new();
@@ -226,7 +226,7 @@ impl<'i> Trail<'i> {
             order.push(i);
         }
 
-        Trail {
+        Journal {
             records,
             scopes,
             within,

src/engraving/record.rs

@@ -487,7 +487,7 @@ fn parse_optional_value(rest: Option<&str>) -> Result<Option<value::Value>, Reco
 }
 
 // Single-line PFFTT text form for a runtime `value::Value`, so a completed
-// step's result survives in the trail and rehydrates on resume.
+// step's result survives in the journal and rehydrates on resume.
 //
 //   Unitus            -> ()
 //   Literali(s)       -> "<escaped>"

src/engraving/store.rs

@@ -94,7 +94,7 @@ impl Store {
         Ok((run_id, run_dir))
     }
 
-    /// Read an existing run's trail back into memory, every record in the
+    /// Read an existing run's journal back into memory, every record in the
     /// order it was written.
     pub fn read(&self, run_id: RunId) -> Result<Vec<Record>, StoreError> {
         let run_dir = self

src/main.rs

@@ -380,7 +380,7 @@ fn main() {
                         .default_value("interactive")
                         .action(ArgAction::Set)
                         .conflicts_with_all(["interactive", "automatic", "quiet"])
-                        .help("How to walk the procedure: interactively, prompting the user at each step; automatically, taking each step's computed value and running to completion or first failure; or quietly, also running automatically but suppressing all progress trace output, so that only the output of external commands is printed to the terminal."),
+                        .help("How to walk the procedure: interactively, prompting the user at each step; automatically, taking each step's computed value and running to completion or first failure; or quietly, also running automatically but suppressing all progress trail output, so that only the output of external commands is printed to the terminal."),
                 )
                 .arg(
                     Arg::new("interactive")
@@ -409,7 +409,7 @@ fn main() {
                         .value_parser(["pfftt", "native"])
                         .default_value("pfftt")
                         .action(ArgAction::Set)
-                        .help("Whether to write the recorded trace to disk in PFFTT format, as is the default, or to instead print a diagnostic trace of the steps as the are completed (for debugging)."),
+                        .help("Whether to write the recorded journal to disk in PFFTT format, as is the default, or to instead print a diagnostic trail of the steps as they are completed (for debugging)."),
                 )
                 .arg(
                     Arg::new("raw-control-chars")
@@ -436,8 +436,8 @@ fn main() {
         )
         .subcommand(
             Command::new("log")
-                .about("Print the trace recorded for a procedure run.")
-                .long_about("Print the trace recorded when a Technique procedure was run. \
+                .about("Print the journal recorded for a procedure run.")
+                .long_about("Print the journal recorded when a Technique procedure was run. \
                     Each line is one recorded event: entering a step, executing a command, \
                     and the result the step settled on. Times are relative to the start of \
                     the run, which is given in the heading.")
@@ -452,7 +452,7 @@ fn main() {
                         .value_parser(["console", "json", "pfftt", "native"])
                         .default_value("console")
                         .action(ArgAction::Set)
-                        .help("Change the output format. The default is to print a human-readable version of the trace to the terminal. \
+                        .help("Change the output format. The default is to print a human-readable version of the journal to the terminal. \
                             Other formats include a JSON array, with one object per record line; \
                             the raw Procedure interchange Format For Transferring Techniques record lines as they are stored on disk; \
                             or, (for debugging) the internal data structures the records were parsed back into)."),