Skip to main content

qualia_core_db/governance/
instrument_trace.rs

1//! Instrument trace ledger — a local, customer-readable audit trail (R12).
2//!
3//! This module distinguishes forbidden provider bylines (CLAUDE.md §16) from
4//! customer-readable audit traces required for observability, accounting, and
5//! delegation compliance. The ledger is local-only (no unsolicited graph publication).
6
7/// A single instrument trace entry (Kind B — customer-readable).
8#[derive(Debug, Clone, PartialEq, Eq)]
9pub struct TraceEntry {
10    /// What instrument instance performed the act (e.g., "devin-session-3").
11    pub instrument_id: String,
12    /// What act was performed (e.g., "eval_cell", "commit_graph", "invoke_capability").
13    pub act: String,
14    /// Which files or resources were touched.
15    pub targets: Vec<String>,
16    /// The Instant the act started (Unix nanos, or 0 if unavailable).
17    pub started_at: u64,
18    /// The Instant the act completed (Unix nanos, or 0 if unavailable).
19    pub completed_at: u64,
20    /// The capability lease under which the act was performed.
21    pub lease_id: Option<String>,
22    /// The cost in tokens/cycles (if measured).
23    pub cost: Option<u64>,
24    /// Whether the act succeeded.
25    pub success: bool,
26    /// Optional diagnostic message (on failure).
27    pub diagnostic: Option<String>,
28}
29
30/// The instrument trace ledger — a local, append-only record of
31/// instrument acts. This is NOT a provider byline (those are
32/// forbidden per CLAUDE.md §16). This is a customer-readable audit
33/// trail that the principal can inspect.
34#[derive(Debug, Clone)]
35pub struct InstrumentTraceLedger {
36    entries: Vec<TraceEntry>,
37    /// Maximum entries before the oldest are evicted.
38    max_entries: usize,
39}
40
41impl Default for InstrumentTraceLedger {
42    /// Equivalent to [`InstrumentTraceLedger::new`] (capacity
43    /// `DEFAULT_MAX_ENTRIES`).
44    fn default() -> Self {
45        Self::new()
46    }
47}
48
49impl InstrumentTraceLedger {
50    /// Default maximum entries (10,000).
51    pub const DEFAULT_MAX_ENTRIES: usize = 10_000;
52
53    /// Create with a default max of 10,000 entries.
54    pub fn new() -> Self {
55        Self {
56            entries: Vec::new(),
57            max_entries: Self::DEFAULT_MAX_ENTRIES,
58        }
59    }
60
61    /// Create with a custom max capacity.
62    pub fn with_capacity(max: usize) -> Self {
63        Self {
64            entries: Vec::with_capacity(max.min(Self::DEFAULT_MAX_ENTRIES)),
65            max_entries: max,
66        }
67    }
68
69    /// Record an instrument act, evicting the oldest entries if over capacity.
70    pub fn record(&mut self, entry: TraceEntry) {
71        if self.max_entries == 0 {
72            return;
73        }
74        if self.entries.len() >= self.max_entries {
75            let overflow = self.entries.len() - self.max_entries + 1;
76            self.entries.drain(0..overflow);
77        }
78        self.entries.push(entry);
79    }
80
81    /// Read all entries in the ledger.
82    pub fn entries(&self) -> &[TraceEntry] {
83        &self.entries
84    }
85
86    /// Filter entries by instrument ID.
87    pub fn entries_for_instrument(&self, id: &str) -> Vec<&TraceEntry> {
88        self.entries
89            .iter()
90            .filter(|e| e.instrument_id == id)
91            .collect()
92    }
93
94    /// Filter entries by act type.
95    pub fn entries_for_act(&self, act: &str) -> Vec<&TraceEntry> {
96        self.entries.iter().filter(|e| e.act == act).collect()
97    }
98
99    /// Sum of all recorded entry costs.
100    pub fn total_cost(&self) -> u64 {
101        self.entries.iter().map(|e| e.cost.unwrap_or(0)).sum()
102    }
103
104    /// Fraction of entries with success = true (0.0 if empty).
105    pub fn success_rate(&self) -> f64 {
106        if self.entries.is_empty() {
107            return 0.0;
108        }
109        let successes = self.entries.iter().filter(|e| e.success).count();
110        successes as f64 / self.entries.len() as f64
111    }
112
113    /// Clear all entries from the ledger.
114    pub fn clear(&mut self) {
115        self.entries.clear();
116    }
117}
118
119/// Check that a text or commit message does not contain forbidden provider bylines (T58).
120/// Enforces CLAUDE.md §16 mechanically.
121pub fn check_no_bylines(text: &str) -> Result<(), String> {
122    for (line_num, line) in text.lines().enumerate() {
123        let trimmed = line.trim();
124        let lower = trimmed.to_ascii_lowercase();
125
126        if lower.starts_with("generated with")
127            || lower.starts_with("🤖 generated with")
128            || trimmed.starts_with("🤖 Generated with")
129            || lower.starts_with("co-authored-by:")
130            || lower.contains("co-authored-by:")
131        {
132            return Err(format!(
133                "forbidden provider byline on line {}: '{}' (violates CLAUDE.md §16)",
134                line_num + 1,
135                trimmed
136            ));
137        }
138    }
139    Ok(())
140}
141
142#[cfg(test)]
143mod tests {
144    use super::*;
145
146    fn sample_entry(
147        instrument_id: &str,
148        act: &str,
149        cost: Option<u64>,
150        success: bool,
151    ) -> TraceEntry {
152        TraceEntry {
153            instrument_id: instrument_id.to_string(),
154            act: act.to_string(),
155            targets: vec!["file1.rs".into(), "file2.rs".into()],
156            started_at: 1_000_000,
157            completed_at: 2_000_000,
158            lease_id: Some("lease-123".into()),
159            cost,
160            success,
161            diagnostic: if success { None } else { Some("failed".into()) },
162        }
163    }
164
165    #[test]
166    fn record_and_read_entry() {
167        let mut ledger = InstrumentTraceLedger::new();
168        assert!(ledger.entries().is_empty());
169
170        let entry = sample_entry("inst-1", "eval_cell", Some(150), true);
171        ledger.record(entry.clone());
172
173        assert_eq!(ledger.entries().len(), 1);
174        assert_eq!(ledger.entries()[0], entry);
175    }
176
177    #[test]
178    fn eviction_on_overflow() {
179        let mut ledger = InstrumentTraceLedger::with_capacity(3);
180        ledger.record(sample_entry("inst-1", "act-1", Some(10), true));
181        ledger.record(sample_entry("inst-1", "act-2", Some(20), true));
182        ledger.record(sample_entry("inst-1", "act-3", Some(30), true));
183        assert_eq!(ledger.entries().len(), 3);
184        assert_eq!(ledger.entries()[0].act, "act-1");
185
186        // 4th entry evicts oldest (act-1)
187        ledger.record(sample_entry("inst-1", "act-4", Some(40), true));
188        assert_eq!(ledger.entries().len(), 3);
189        assert_eq!(ledger.entries()[0].act, "act-2");
190        assert_eq!(ledger.entries()[2].act, "act-4");
191    }
192
193    #[test]
194    fn filter_by_instrument() {
195        let mut ledger = InstrumentTraceLedger::new();
196        ledger.record(sample_entry("inst-A", "act-1", None, true));
197        ledger.record(sample_entry("inst-B", "act-2", None, true));
198        ledger.record(sample_entry("inst-A", "act-3", None, false));
199
200        let for_a = ledger.entries_for_instrument("inst-A");
201        assert_eq!(for_a.len(), 2);
202        assert_eq!(for_a[0].act, "act-1");
203        assert_eq!(for_a[1].act, "act-3");
204
205        let for_b = ledger.entries_for_instrument("inst-B");
206        assert_eq!(for_b.len(), 1);
207        assert_eq!(for_b[0].act, "act-2");
208
209        let for_c = ledger.entries_for_instrument("inst-C");
210        assert!(for_c.is_empty());
211    }
212
213    #[test]
214    fn filter_by_act() {
215        let mut ledger = InstrumentTraceLedger::new();
216        ledger.record(sample_entry("inst-A", "commit_graph", None, true));
217        ledger.record(sample_entry("inst-B", "eval_cell", None, true));
218        ledger.record(sample_entry("inst-C", "commit_graph", None, true));
219
220        let commits = ledger.entries_for_act("commit_graph");
221        assert_eq!(commits.len(), 2);
222        assert_eq!(commits[0].instrument_id, "inst-A");
223        assert_eq!(commits[1].instrument_id, "inst-C");
224
225        let evals = ledger.entries_for_act("eval_cell");
226        assert_eq!(evals.len(), 1);
227    }
228
229    #[test]
230    fn total_cost() {
231        let mut ledger = InstrumentTraceLedger::new();
232        assert_eq!(ledger.total_cost(), 0);
233
234        ledger.record(sample_entry("inst-1", "act-1", Some(100), true));
235        ledger.record(sample_entry("inst-2", "act-2", None, true));
236        ledger.record(sample_entry("inst-3", "act-3", Some(250), false));
237
238        assert_eq!(ledger.total_cost(), 350);
239    }
240
241    #[test]
242    fn success_rate() {
243        let mut ledger = InstrumentTraceLedger::new();
244        assert_eq!(ledger.success_rate(), 0.0);
245
246        ledger.record(sample_entry("inst-1", "act-1", None, true));
247        ledger.record(sample_entry("inst-2", "act-2", None, false));
248        ledger.record(sample_entry("inst-3", "act-3", None, true));
249        ledger.record(sample_entry("inst-4", "act-4", None, true));
250
251        assert!((ledger.success_rate() - 0.75).abs() < 1e-6);
252    }
253
254    #[test]
255    fn clear_ledger() {
256        let mut ledger = InstrumentTraceLedger::new();
257        ledger.record(sample_entry("inst-1", "act-1", Some(10), true));
258        assert_eq!(ledger.entries().len(), 1);
259
260        ledger.clear();
261        assert_eq!(ledger.entries().len(), 0);
262        assert_eq!(ledger.total_cost(), 0);
263    }
264
265    #[test]
266    fn clean_text_passes() {
267        let msg = "feat(poet-host): add new invoke function\n\nImplements feature X and tests.";
268        assert!(check_no_bylines(msg).is_ok());
269    }
270
271    #[test]
272    fn generated_with_fails() {
273        let msg = "feat: update parser\n\nGenerated with Devin";
274        assert!(check_no_bylines(msg).is_err());
275    }
276
277    #[test]
278    fn co_authored_by_fails() {
279        let msg = "feat: add capability\n\nCo-Authored-By: Devin <devin@cognition.ai>";
280        assert!(check_no_bylines(msg).is_err());
281    }
282
283    #[test]
284    fn bot_attribution_fails() {
285        let msg = "fix: bug\n\nCo-Authored-By: devin-ai-integration[bot] <12345+bot@users.noreply.github.com>";
286        assert!(check_no_bylines(msg).is_err());
287    }
288
289    #[test]
290    fn emoji_generated_fails() {
291        let msg = "chore: cleanup\n\n🤖 Generated with Claude Code";
292        assert!(check_no_bylines(msg).is_err());
293    }
294}