merge: P4b S5, sent tracking (branch S5, ad649be3)

The second of the paused branches. invoice.sent, Ledger::mark_sent (with
its Lean step), books.mark_sent in its own group, the two attention
items, schema 17. Conflicts, resolved as plan 8.0.2 says: the shared
over-the-wire test file crates/ledger-cli/tests/documents.rs (S4.4's
file kept whole, S5's test appended, its create call given the
confirmed: true the S4.4 contract now needs), types.rs (both appends
kept), docs/parity.md (the review's oracle row and S5's new row).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HS8WZziDnyxunC23MUxrLp

crates/ledger-store/src/format.rs

@@ -243,6 +243,7 @@ pub const EVENT_TYPES: &[&str] = &[
     "fx.rate_set",
     "invoice.created",
     "invoice.payment_received",
+    "invoice.sent",
     "instrument.added",
     FORMAT_SET,
     "journal.tail_repaired",

crates/ledger-store/src/meta.rs

@@ -14,7 +14,9 @@
 //! ```
 
 use crate::error::StoreError;
+use crate::journal::JournalLine;
 use chrono::NaiveDate;
+use ledger_core::arap::{SendKind, Sent, SentVia};
 use ledger_core::conventions::{Approval, ConventionKind, NewConvention, NewDecision, NewOpenItem};
 use ledger_core::settings::{Change, Source};
 use ledger_core::{ClassId, ProjectFacts, ProjectKind, ProjectStatus};
@@ -361,6 +363,61 @@ pub fn entry_approved_of(p: &Value, seq: u64) -> Result<(u64, Approval), StoreEr
     ))
 }
 
+/// A list of strings, each checked (`to` on `invoice.sent`).
+fn str_list(p: &Value, event: &str, k: &str) -> Result<Vec<String>, StoreError> {
+    p.get(k)
+        .and_then(Value::as_array)
+        .ok_or_else(|| corrupt(event, k))?
+        .iter()
+        .map(|v| {
+            v.as_str()
+                .map(str::to_string)
+                .ok_or_else(|| corrupt(event, k))
+        })
+        .collect()
+}
+
+/// `invoice.sent {invoice_id, on, by, via, to, kind, reference?, note?}`
+/// (plan P4b S5): a send is a fact of the document's life and moves no
+/// figure.
+pub fn invoice_sent(invoice: u64, s: &Sent) -> Value {
+    let mut o = Map::new();
+    o.insert("invoice_id".into(), json!(invoice));
+    o.insert("on".into(), json!(s.on.to_string()));
+    o.insert("by".into(), json!(s.by));
+    o.insert("via".into(), json!(s.via.key()));
+    o.insert("to".into(), json!(s.to));
+    o.insert("kind".into(), json!(s.kind.key()));
+    put(&mut o, "reference", s.reference.clone());
+    put(&mut o, "note", s.note.clone());
+    Value::Object(o)
+}
+
+/// Read an `invoice.sent`: `(invoice, send)`. A channel or kind this
+/// version doesn't know is newer, never corrupt (rules.md B-27).
+pub fn invoice_sent_of(line: &JournalLine) -> Result<(u64, Sent), StoreError> {
+    const E: &str = "invoice.sent";
+    let p = &line.payload;
+    let via = str_of(p, E, "via")?;
+    let kind = str_of(p, E, "kind")?;
+    Ok((
+        u64_of(p, E, "invoice_id")?,
+        Sent {
+            on: date_of(&str_of(p, E, "on")?, E, "on")?,
+            by: str_of(p, E, "by")?,
+            via: SentVia::parse(&via).ok_or_else(|| {
+                crate::format::newer_content(line, format!("the send channel {via:?}"))
+            })?,
+            to: str_list(p, E, "to")?,
+            kind: SendKind::parse(&kind).ok_or_else(|| {
+                crate::format::newer_content(line, format!("the send kind {kind:?}"))
+            })?,
+            reference: opt_str(p, E, "reference")?,
+            note: opt_str(p, E, "note")?,
+        },
+    ))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

crates/ledger-store/src/schema.rs

@@ -5,7 +5,7 @@
 //! is the current version.
 
 /// Current schema version.
-pub const SCHEMA_VERSION: u32 = 16;
+pub const SCHEMA_VERSION: u32 = 17;
 
 /// Migrations, in order. `MIGRATIONS[i]` migrates from version `i` to `i+1`.
 pub const MIGRATIONS: &[&str] = &[
@@ -417,5 +417,22 @@ ALTER TABLE bills ADD COLUMN received_on TEXT;
 ALTER TABLE bills ADD COLUMN terms TEXT;
 ALTER TABLE bills ADD COLUMN memo TEXT;
 ALTER TABLE bills ADD COLUMN duplicate_reason TEXT;
+"#,
+    r#"
+-- v17: sent tracking (plan P4b S5, `invoice.sent`): one row per recorded
+-- send of an invoice, in the order journaled. A send moves no figure and
+-- no ledger line, so this table is only the projection's copy of the
+-- journal's record (parity with replay). `on` and `by` are quoted: `on`
+-- is an SQL keyword.
+CREATE TABLE IF NOT EXISTS invoice_sends(
+  invoice_id INTEGER NOT NULL,
+  "on" TEXT NOT NULL,
+  "by" TEXT NOT NULL,
+  via TEXT NOT NULL,
+  to_json TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  reference TEXT NULL,
+  note TEXT NULL
+);
 "#,
 ];

crates/ledger-store/src/store.rs

@@ -3756,6 +3756,36 @@ impl Store {
         self.reverse_entry(target, date, &description)
     }
 
+    /// Record that an invoice went out ([`Ledger::mark_sent`], plan P4b
+    /// S5): journaled as `invoice.sent` (feature `documents_v2`: an older
+    /// version refuses the type), then applied to the books. A send moves
+    /// no figure, so it journals one line and no entry.
+    ///
+    /// ```text
+    /// GOAL: a send is journaled once and replays to the same record, in
+    ///       every version that can read the books.
+    /// SOURCE: docs/spec/rules.md B-27, B-38; plan P4b S5, A-4.
+    /// SCENARIOS:
+    ///   1. IF the engine refuses it (unknown or void invoice, a date
+    ///      before the invoice, no recipients, a text the books won't
+    ///      keep): SHOULD refuse, journaling nothing.
+    ///   2. IF the books haven't declared documents_v2: SHOULD need the
+    ///      feature, journaling nothing.
+    /// ```
+    pub fn mark_sent(
+        &mut self,
+        invoice_id: InvoiceId,
+        sent: ledger_core::arap::Sent,
+    ) -> Result<(), StoreError> {
+        self.ensure_feature(crate::format::DOCUMENTS_V2)?;
+        self.rehearse(|l| l.mark_sent(invoice_id, sent.clone()))?;
+        let line =
+            self.append_journal("invoice.sent", crate::meta::invoice_sent(invoice_id, &sent))?;
+        self.ledger.mark_sent(invoice_id, sent)?;
+        apply_line_to_sqlite(&self.conn, &line)?;
+        Ok(())
+    }
+
     // ------------------------------------------------------------------
     // Foreign exchange
     // ------------------------------------------------------------------
@@ -7037,6 +7067,11 @@ fn replay_line(
                 parse_bill_fields(p)?,
             )?;
         }
+        "invoice.sent" => {
+            // A send moves no figure: it only restores the invoice's sends.
+            let (invoice_id, sent) = crate::meta::invoice_sent_of(line)?;
+            ledger.replay_invoice_sent(invoice_id, sent)?;
+        }
         "invoice.payment_received" => {
             // The payment entry was already rebuilt; this only moves the
             // invoice's paid amount and status.
@@ -8019,6 +8054,26 @@ fn apply_line_rows(conn: &Connection, line: &JournalLine) -> Result<(), StoreErr
                 ],
             )?;
         }
+        // A send is a document's own record, not a ledger line (plan P4b
+        // S5): one row each, for the projection to agree with replay.
+        "invoice.sent" => {
+            let to = p
+                .get("to")
+                .ok_or_else(|| StoreError::JournalCorrupt("invoice.sent without to".into()))?;
+            conn.execute(
+                "INSERT INTO invoice_sends(invoice_id, \"on\", \"by\", via, to_json, kind, reference, note) VALUES (?,?,?,?,?,?,?,?)",
+                params![
+                    get_u64(p, "invoice_id")? as i64,
+                    get_str(p, "on")?,
+                    get_str(p, "by")?,
+                    get_str(p, "via")?,
+                    to.to_string(),
+                    get_str(p, "kind")?,
+                    p.get("reference").and_then(|v| v.as_str()),
+                    p.get("note").and_then(|v| v.as_str()),
+                ],
+            )?;
+        }
         // A payment moves no document row: what a document is paid is read
         // from the ledger lines tagged with it (schema v15, rules.md B-38).
         "invoice.payment_received" => {}