feat(prd-7): materialize AUDIT.log sheet — AuditRow, 9 columns, MetaFlag Display (#57) (#92)

* fix(ledger-core): remove conflicting From impl in ingest.rs

From<&TransactionInput> for DocumentFields conflicted with Rust's blanket
TryFrom via Into. Keep only TryFrom (the fallible parse-aware version).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(prd-7): materialize AUDIT.log sheet — AuditRow, 9 columns, MetaFlag Display

Closes #57. Makes the PRD-7 verification layer CPA-visible: every committed
transaction now emits a row in AUDIT.log with the full verification provenance.

- validation.rs: add Display for MetaFlag (all 5 variants)
- workbook.rs: AuditRow struct + constructor (blake3 entry_id, worst-case
  disposition, legal_violation scan, serde_json stage trace, comma-joined flags)
- workbook.rs: setup_audit_sheet() with 9 headers; stage_trace_json column
  pinned to width 8 to avoid overwhelming the CPA view
- workbook.rs: wire setup_audit_sheet into initialize_workbook + copy_all_sheets
- workbook.rs: WorkbookWriter::append_audit_row()
- 3 new tests: legal_violation result, Approved gate, stage_trace_json round-trip

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet (coordinator) <coordinator@promptexecution.com.au>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

crates/ledger-core/src/validation.rs

@@ -2,6 +2,7 @@
 //! These types provide a carry-forward validation context that accumulates
 //! confidence and issues through each pipeline stage.
 
+use std::fmt;
 use serde::{Deserialize, Serialize};
 
 /// Disposition classifies how an issue should be handled by the pipeline.
@@ -107,6 +108,17 @@ pub enum MetaFlag {
     LowUpstreamConf { score: f32, stage: String },
     ConstraintWeak { constraint: String },
 }
+impl fmt::Display for MetaFlag {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            MetaFlag::NewVendor { vendor } => write!(f, "new_vendor:{vendor}"),
+            MetaFlag::AnomalyDetected { code, impact } => write!(f, "anomaly:{code}:{impact:.2}"),
+            MetaFlag::RepairApplied { rule_id } => write!(f, "repair:{rule_id}"),
+            MetaFlag::LowUpstreamConf { score, stage } => write!(f, "low_conf:{stage}:{score:.2}"),
+            MetaFlag::ConstraintWeak { constraint } => write!(f, "constraint_weak:{constraint}"),
+        }
+    }
+}
 
 /// Score from a single pipeline stage.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]

crates/ledger-core/src/workbook.rs

@@ -5,6 +5,7 @@ use calamine::{Reader, open_workbook, Xlsx, Data};
 use serde::{Deserialize, Serialize};
 
 use crate::classify::{TaxCategory, Flag};
+use crate::validation::{CommitGate, Disposition, Issue, MetaCtx};
 use strum::VariantArray;
 
 pub const REQUIRED_SHEETS: &[&str] = &[
@@ -30,6 +31,8 @@ pub fn initialize_workbook(path: &Path) -> Result<(), rust_xlsxwriter::XlsxError
 
         if *sheet_name == TRANSACTIONS_SHEET {
             setup_transactions_sheet(worksheet)?;
+        } else if *sheet_name == "AUDIT.log" {
+            setup_audit_sheet(worksheet)?;
         }
     }
     workbook.save(path)
@@ -60,6 +63,21 @@ fn setup_transactions_sheet(worksheet: &mut Worksheet) -> Result<(), rust_xlsxwr
     Ok(())
 }
 
+fn setup_audit_sheet(worksheet: &mut Worksheet) -> Result<(), rust_xlsxwriter::XlsxError> {
+    worksheet.write_string(0, 0, "entry_id")?;
+    worksheet.write_string(0, 1, "constraint_score")?;
+    worksheet.write_string(0, 2, "legal_result")?;
+    worksheet.write_string(0, 3, "disposition")?;
+    worksheet.write_string(0, 4, "accumulated_confidence")?;
+    worksheet.write_string(0, 5, "stage_trace_json")?;
+    worksheet.write_string(0, 6, "flags")?;
+    worksheet.write_string(0, 7, "invoice_arithmetic_ok")?;
+    worksheet.write_string(0, 8, "commit_gate")?;
+    // Keep stage_trace_json narrow so it doesn't overwhelm the CPA view
+    worksheet.set_column_width(5, 8)?;
+    Ok(())
+}
+
 pub struct WorkbookWriter {
     path: PathBuf,
 }
@@ -127,6 +145,8 @@ impl WorkbookWriter {
             let worksheet = new_workbook.add_worksheet().set_name(*sheet_name)?;
             if *sheet_name == TRANSACTIONS_SHEET {
                 setup_transactions_sheet(worksheet)?;
+            } else if *sheet_name == "AUDIT.log" {
+                setup_audit_sheet(worksheet)?;
             }
             if let Ok(range) = workbook.worksheet_range(*sheet_name) {
                 Self::copy_sheet_data(worksheet, &range)?;
@@ -215,6 +235,32 @@ impl WorkbookWriter {
         Ok(())
     }
 
+    pub fn append_audit_row(
+        &self,
+        row: &AuditRow,
+    ) -> Result<(), Box<dyn std::error::Error>> {
+        let row_idx = self.get_row_count("AUDIT.log")?;
+
+        let mut new_workbook = Workbook::new();
+        self.copy_all_sheets(&mut new_workbook)?;
+
+        let worksheet = Self::find_worksheet_by_name(&mut new_workbook, "AUDIT.log")
+            .ok_or("AUDIT.log sheet not found")?;
+
+        worksheet.write_string(row_idx, 0, &row.entry_id)?;
+        worksheet.write_number(row_idx, 1, row.constraint_score as f64)?;
+        worksheet.write_string(row_idx, 2, &row.legal_result)?;
+        worksheet.write_string(row_idx, 3, &row.disposition)?;
+        worksheet.write_number(row_idx, 4, row.accumulated_confidence as f64)?;
+        worksheet.write_string(row_idx, 5, &row.stage_trace_json)?;
+        worksheet.write_string(row_idx, 6, &row.flags)?;
+        worksheet.write_boolean(row_idx, 7, row.invoice_arithmetic_ok)?;
+        worksheet.write_string(row_idx, 8, &row.commit_gate)?;
+
+        new_workbook.save(&self.path)?;
+        Ok(())
+    }
+
     pub fn append_mutation(
         &self,
         timestamp: &str,
@@ -265,6 +311,83 @@ impl WorkbookWriter {
     }
 }
 
+/// One audit row per committed transaction for the AUDIT.log sheet.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AuditRow {
+    pub entry_id: String,
+    pub constraint_score: f32,
+    pub legal_result: String,
+    pub disposition: String,
+    pub accumulated_confidence: f32,
+    pub stage_trace_json: String,
+    pub flags: String,
+    pub invoice_arithmetic_ok: bool,
+    pub commit_gate: String,
+}
+
+impl AuditRow {
+    pub fn new(
+        document_id: &str,
+        source_ref: &str,
+        constraint_score: f32,
+        issues: &[Issue],
+        meta: &MetaCtx,
+        invoice_arithmetic_ok: bool,
+        gate: &CommitGate,
+    ) -> Self {
+        let entry_id = {
+            let input = format!("{document_id}|{source_ref}");
+            blake3::hash(input.as_bytes()).to_hex().to_string()
+        };
+
+        let legal_result = issues
+            .iter()
+            .find(|i| i.code == "legal_violation")
+            .map(|i| i.code.clone())
+            .unwrap_or_else(|| "ok".to_string());
+
+        let disposition = issues
+            .iter()
+            .map(|i| i.disposition)
+            .max_by_key(|d| match d {
+                Disposition::Unrecoverable => 2,
+                Disposition::Recoverable => 1,
+                Disposition::Advisory => 0,
+            })
+            .map(|d| format!("{d:?}").to_ascii_lowercase())
+            .unwrap_or_else(|| "ok".to_string());
+
+        let stage_trace_json = serde_json::to_string(&meta.stage_trace)
+            .unwrap_or_else(|_| "[]".to_string());
+
+        let flags = meta
+            .flags
+            .iter()
+            .map(|f| f.to_string())
+            .collect::<Vec<_>>()
+            .join(",");
+
+        let commit_gate = match gate {
+            CommitGate::Approved { .. } => "Approved",
+            CommitGate::PendingOperator { .. } => "PendingOperator",
+            CommitGate::Blocked { .. } => "Blocked",
+        }
+        .to_string();
+
+        Self {
+            entry_id,
+            constraint_score,
+            legal_result,
+            disposition,
+            accumulated_confidence: meta.accumulated_confidence,
+            stage_trace_json,
+            flags,
+            invoice_arithmetic_ok,
+            commit_gate,
+        }
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct TxProjectionRow {
     pub tx_id: String,
@@ -629,4 +752,46 @@ mod tests {
             _ => panic!("Unexpected cell type"),
         }
     }
+    #[test]
+    fn test_audit_row_legal_violation_result() {
+        use crate::validation::{CommitGate, Disposition, Issue, IssueSource, MetaCtx};
+        let issues = vec![Issue {
+            code: "legal_violation".to_string(),
+            message: "foreign SaaS should have BASEXCLUDED tax code".to_string(),
+            field: None,
+            disposition: Disposition::Unrecoverable,
+            source: IssueSource::TypeCheck,
+        }];
+        let meta = MetaCtx::default();
+        let gate = CommitGate::Blocked { issues: issues.clone() };
+        let row = AuditRow::new("doc1", "WF--BH--2026-01", 0.0, &issues, &meta, true, &gate);
+        assert_eq!(row.legal_result, "legal_violation");
+        assert_eq!(row.commit_gate, "Blocked");
+        assert_eq!(row.disposition, "unrecoverable");
+    }
+
+    #[test]
+    fn test_audit_row_approved_gate() {
+        use crate::validation::{CommitGate, MetaCtx};
+        let gate = CommitGate::Approved { confidence: 0.95 };
+        let meta = MetaCtx::default();
+        let row = AuditRow::new("doc2", "WF--BH--2026-01", 0.95, &[], &meta, true, &gate);
+        assert_eq!(row.commit_gate, "Approved");
+        assert_eq!(row.legal_result, "ok");
+        assert_eq!(row.disposition, "ok");
+    }
+
+    #[test]
+    fn test_audit_row_stage_trace_json_is_valid() {
+        use crate::validation::{CommitGate, MetaCtx};
+        let mut meta = MetaCtx::default();
+        meta = meta.advance("validate", 0.9, &[]);
+        meta = meta.advance("verify_legal", 1.0, &[]);
+        let gate = CommitGate::Approved { confidence: 0.9 };
+        let row = AuditRow::new("doc3", "src", 1.0, &[], &meta, false, &gate);
+        let parsed: serde_json::Value = serde_json::from_str(&row.stage_trace_json)
+            .expect("stage_trace_json must be valid JSON");
+        assert!(parsed.is_array());
+        assert_eq!(parsed.as_array().unwrap().len(), 2);
+    }
 }