Theory of Operation

This chapter documents the novel architecture patterns that power l3dg3rr’s AI agent governance system.

Related Chapters

• Graph Data Model - Node and edge definitions
• Force Layout - Force-directed positioning
• Isometric Projection - 3D to 2D mapping
• Pipeline - Type-state workflow
• Validation - Confidence accumulation
• Visualization - Mermaid/HTML export
• Match Visualization Plan - multi-arm branch rendering contract
• Legal Verification - Tax rule verification
• Constraints - Kasuari constraints

The Novel Theory of Tool Pattern

Concept

Traditional tool use in LLM agents treats tools as stateless functions that transform inputs to outputs. The Novel Theory of Tool (NTTP) pattern instead treats tools as stateful instruction executors with:

// Rhai patterns auto-parse to Mermaid
fn ingest() -> validate
fn validate() -> classify
fn classify() -> reconcile
fn reconcile() -> commit

flowchart TD
    ingest["ingest"]
    validate["validate"]
    classify["classify"]
    reconcile["reconcile"]
    commit["commit"]
    ingest --> validate
    validate --> classify
    classify --> reconcile
    reconcile --> commit

Conditional flow:

if confidence > 0.8 -> commit
if confidence > 0.5 -> reconcile  
if confidence <= 0.5 -> review
if review == approved -> classify

flowchart TD
    confidence_gt_0_8{"confidence > 0.8"}
    commit["commit"]
    confidence_gt_0_5{"confidence > 0.5"}
    reconcile["reconcile"]
    confidence____0_5{"confidence <= 0.5"}
    review["review"]
    review____approved{"review == approved"}
    classify["classify"]
    confidence_gt_0_8 -->|"true"|commit
    confidence_gt_0_8 -->|"false"|confidence_gt_0_5
    confidence_gt_0_5 -->|"true"|reconcile
    confidence____0_5 -->|"true"|review
    review____approved -->|"true"|classify

1. Composable instruction streams - Tools accept not just data, but instructions that modify their behavior
2. Idempotent re-execution - Tools can be safely re-run with the same inputs, producing deterministic outputs
3. Content-addressed identity - All outputs are identified by cryptographic hashes of their inputs
4. Audit-native design - Every tool execution produces traceable evidence

Executable Pattern Example

#![allow(unused)]
fn main() {
use ledger_core::{graph::*, layout::*, render::*};

// Create a pipeline graph
let nodes = create_pipeline_nodes();
let edges = create_pipeline_edges();

// Initialize force layout
let mut layout = ForceLayout::for_pipeline();

// Run simulation
for _ in 0..50 {
    layout.tick();
}

// Render to screen coordinates
let renderer = GraphRenderer::new(800, 600);
for (idx, _) in nodes.iter().enumerate() {
    if let Some(pos) = layout.position(idx) {
        let screen = renderer.screen_position(pos.x, pos.y, pos.z);
        println!("Node {} -> ({:.1}, {:.1})", idx, screen.x, screen.y);
    }
}
}

Comparison

System Architecture Diagram

fn human_accountant() -> tray_icon
fn human_accountant() -> window_ui
fn tray_icon() -> slint_graph_view
fn window_ui() -> slint_graph_view
fn toast_notifier() -> slint_graph_view
fn credential_manager() -> slint_graph_view
fn slint_graph_view() -> pipeline_hsm
fn pipeline_hsm() -> validation
fn pipeline_hsm() -> legal_solver
fn pipeline_hsm() -> constraints
fn pipeline_hsm() -> ledgerr_documents
fn pipeline_hsm() -> ledgerr_review
fn pipeline_hsm() -> ledgerr_reconciliation

flowchart TD
    human_accountant["human_accountant"]
    tray_icon["tray_icon"]
    window_ui["window_ui"]
    slint_graph_view["slint_graph_view"]
    toast_notifier["toast_notifier"]
    credential_manager["credential_manager"]
    pipeline_hsm["pipeline_hsm"]
    validation["validation"]
    legal_solver["legal_solver"]
    constraints["constraints"]
    ledgerr_documents["ledgerr_documents"]
    ledgerr_review["ledgerr_review"]
    ledgerr_reconciliation["ledgerr_reconciliation"]
    human_accountant --> tray_icon
    human_accountant --> window_ui
    tray_icon --> slint_graph_view
    window_ui --> slint_graph_view
    toast_notifier --> slint_graph_view
    credential_manager --> slint_graph_view
    slint_graph_view --> pipeline_hsm
    pipeline_hsm --> validation
    pipeline_hsm --> legal_solver
    pipeline_hsm --> constraints
    pipeline_hsm --> ledgerr_documents
    pipeline_hsm --> ledgerr_review
    pipeline_hsm --> ledgerr_reconciliation

Pipeline Flow Diagram

fn ingested() -> validating
fn validating() -> classifying
fn classifying() -> reconciling
fn reconciling() -> committed
if low_confidence == true -> needs_review
if approved == true -> classifying

flowchart TD
    ingested["ingested"]
    validating["validating"]
    classifying["classifying"]
    reconciling["reconciling"]
    committed["committed"]
    low_confidence____true{"low_confidence == true"}
    needs_review["needs_review"]
    approved____true{"approved == true"}
    ingested --> validating
    validating --> classifying
    classifying --> reconciling
    reconciling --> committed
    low_confidence____true -->|"true"|needs_review
    approved____true -->|"true"|classifying

LLM Verification Pattern

fn proposer_llm() -> decision_store
fn decision_store() -> reviewer_llm
if reviewer_agreed == true -> accepted_result
if reviewer_agreed == false -> human_review
fn human_review() -> accepted_result

flowchart TD
    proposer_llm["proposer_llm"]
    decision_store["decision_store"]
    reviewer_llm["reviewer_llm"]
    human_review["human_review"]
    accepted_result["accepted_result"]
    reviewer_agreed____true{"reviewer_agreed == true"}
    reviewer_agreed____false{"reviewer_agreed == false"}
    proposer_llm --> decision_store
    decision_store --> reviewer_llm
    human_review --> accepted_result
    reviewer_agreed____true -->|"true"|accepted_result
    reviewer_agreed____false -->|"true"|human_review

Executable LLM Pipeline Integration

Proposer/Reviewer Pattern

The verification system uses a two-model approach for classification quality:

#![allow(unused)]
fn main() {
use ledger_core::verify::Verifier;
use ledger_core::validation::{Disposition, MetaCtx};

// Initialize verifier with two models
let verifier = Verifier::new(proposer_model.clone(), reviewer_model.clone());

// Propose classification
let proposal = verifier.propose(&transaction, "OfficeSupplies");

// Reviewer evaluates
let review = verifier.review(&proposal);

// Combine into result with confidence
let confidence = if review.agreed {
    proposal.confidence * 0.95  // High agreement boost
} else {
    proposal.confidence * 0.5   // Disagreement penalty
};
}

Multi-Stage Classification Flow (Executable)

#![allow(unused)]
fn main() {
use ledger_core::{graph::*, layout::*, pipeline::*, validation::*};

// Complete pipeline execution
fn run_pipeline(document_path: &str) -> Result<PipelineState<Committed>, Issue> {
    // Stage 1: Ingest
    let data = std::fs::read(document_path)?;
    let tx_id = blake3::hash(&data).to_hex();
    let state = PipelineState::new(Ingested { tx_id, data });
    
    // Stage 2: Validate (Kasuari constraints + Z3 legal)
    let ctx = MetaCtx::default();
    let validated = state.validate(&ctx)?;
    
    // Stage 3: Classify (LLM → Reviewer → Human if needed)
    let classified = validated.classify("OfficeSupplies".to_string())?;
    
    // Stage 4: Reconcile (Xero)
    let reconciled = classified.reconcile(Some(xero_id))?;
    
    // Stage 5: Commit (Audit log + schedule)
    Ok(reconciled.commit()?)
}
}

Isometric Visualization (Executable)

3D Force Layout to 2D Screen

fn node_a_3d() -> isometric_projection
fn node_b_3d() -> isometric_projection
fn node_c_3d() -> isometric_projection
fn isometric_projection() -> screen_coordinates

flowchart TD
    node_a_3d["node_a_3d"]
    isometric_projection["isometric_projection"]
    node_b_3d["node_b_3d"]
    node_c_3d["node_c_3d"]
    screen_coordinates["screen_coordinates"]
    node_a_3d --> isometric_projection
    node_b_3d --> isometric_projection
    node_c_3d --> isometric_projection
    isometric_projection --> screen_coordinates

State Visualization Mapping

#![allow(unused)]
fn main() {
use ledger_core::{graph::*, layout::*, render::*};

// Full visualization pipeline
fn visualize_pipeline() -> String {
    // 1. Create graph data
    let nodes = create_pipeline_nodes();
    
    // 2. Run force-directed layout
    let mut layout = ForceLayout::for_pipeline();
    for _ in 0..100 { layout.tick(); }
    
    // 3. Render to screen coordinates
    let renderer = GraphRenderer::new(800, 600);
    let mut positions = Vec::new();
    for (idx, node) in nodes.iter().enumerate() {
        if let Some(pos) = layout.position(idx) {
            let screen = renderer.screen_position(pos.x, pos.y, pos.z);
            positions.push((node.label.clone(), screen));
        }
    }
    
    // 4. Generate Mermaid diagram
    let mut mermaid = String::from("stateDiagram-v2\n");
    for (label, _) in &positions {
        mermaid.push_str(&format!("    {}: {}\n", label, label));
    }
    mermaid
}
}

State Visualization Mapping

Integration Test Recipes

CI/CD Test Matrix

# .github/workflows/ci.yml
test-recipes:
  - name: e2e-mvp
    command: ./scripts/e2e_mvp.sh
    validates: full ingest → classify → audit → schedule

  - name: visualization-render
    command: cargo test --package ledgerr-host visualization_e2e
    validates: isometric graph rendering

  - name: mdbook-build
    command: just docgen-check
    validates: documentation generation plus live Rhai editor assets

  - name: mcp-surface-contract
    command: cargo run -p xtask-mcpb -- generate-mcp-artifacts
    validates: MCP tool contract matches code

Executable Documentation Tests

#![allow(unused)]
fn main() {
// Tests that verify documentation examples work
#[cfg(test)]
mod doc_tests {
    use ledger_core::{graph::*, layout::*, render::*, visualize::*};
    
    #[test]
    fn test_force_layout_tick() {
        let mut layout = ForceLayout::for_pipeline();
        let initial = layout.position(0);
        
        layout.tick();
        
        // Position should change after tick
        assert_ne!(initial, layout.position(0));
    }
    
    #[test]
    fn test_isometric_projection() {
        let renderer = GraphRenderer::new(800, 600);
        
        // Center position should map near origin
        let center = renderer.screen_position(0.0, 0.0, 0.0);
        assert!((center.x - 400.0).abs() < 1.0);
        assert!((center.y - 300.0).abs() < 1.0);
    }
    
    #[test]
    fn test_pipeline_state_transitions() {
        let state = PipelineState::new(Ingested { 
            tx_id: "test123".to_string(),
            data: vec![1, 2, 3] 
        });
        
        let ctx = MetaCtx::default();
        let validated = state.validate(&ctx).unwrap();
        
        assert!(matches!(validated, PipelineState::Validating(_)));
    }
}
}

Multi-Jurisdiction Tax Rules

Jurisdiction Activation

#![allow(unused)]
fn main() {
use ledger_core::legal::{us_schedule_c, LegalSolver, TransactionFacts, Z3Result};

let solver = LegalSolver::new();
let rule = us_schedule_c::rule_ordinary_necessary();
let mut facts = TransactionFacts::new();
facts.is_business_activity = Some(true);
facts.is_ordinary = Some(true);
facts.is_necessary = Some(false);

let result = solver.verify(&rule, &facts);

match result {
    Z3Result::Satisfied => println!("rule satisfied"),
    Z3Result::Violated { witness } => println!("blocked: {witness}"),
    Z3Result::Unknown => println!("more facts required"),
}
}

The visualization plan for this kind of multi-arm branch is documented in Match Visualization Plan. Branch-heavy examples should include a fan-out sample that keeps arm order stable across Mermaid and isometric views.

Content-Hash Identity Model

Idempotent Ingest (Executable)

#![allow(unused)]
fn main() {
use blake3::hash;

// Generate deterministic transaction ID
fn compute_tx_id(account: &str, date: &str, amount: f64, desc: &str) -> String {
    let input = format!("{}|{}|{}|{}", account, date, amount, desc);
    hash(input.as_bytes()).to_hex().to_string()
}

// Example: Same inputs produce same ID (idempotent)
let id1 = compute_tx_id("WF-BH-CHK", "2024-01-15", 150.00, "Office Depot");
let id2 = compute_tx_id("WF-BH-CHK", "2024-01-15", 150.00, "Office Depot");
assert_eq!(id1, id2); // Idempotent!
}

Content-Hash Flow

fn account_date_amount_desc() -> blake3_hasher
fn blake3_hasher() -> hex_64_chars
fn hex_64_chars() -> tx_id_stored

flowchart TD
    account_date_amount_desc["account_date_amount_desc"]
    blake3_hasher["blake3_hasher"]
    hex_64_chars["hex_64_chars"]
    tx_id_stored["tx_id_stored"]
    account_date_amount_desc --> blake3_hasher
    blake3_hasher --> hex_64_chars
    hex_64_chars --> tx_id_stored

Workflow DSL Compilation (Executable)

TOML → Triple Compilation

#![allow(unused)]
fn main() {
use ledger_core::workflow::{WorkflowToml, compile_mermaid, compile_rhai, compile_rust_enum};

// Parse TOML workflow definition
let toml_str = r#"
[[state]]
id = "Ingested"
[[state]]
id = "Validating"
[[transition]]
from = "Ingested"
to = "Validating"
"#;

let workflow: WorkflowToml = toml::from_str(toml_str).unwrap();

// Compile to three outputs
let mermaid = compile_mermaid(&workflow);
let rhai = compile_rhai(&workflow);
let rust_enum = compile_rust_enum(&workflow);

println!("Mermaid:\n{}", mermaid);
println!("\nRhai:\n{}", rhai);
println!("\nRust:\n{}", rust_enum);
}

Verb Pattern (Executable)

Reversible Operations

#![allow(unused)]
fn main() {
use ledger_core::pipeline::*;

// Ingest with idempotency
let result1 = service.ingest_statement_rows(rows.clone())?;
assert_eq!(result1.inserted_count, 1);

let result2 = service.ingest_statement_rows(rows)?;  // Same rows
assert_eq!(result2.inserted_count, 0);  // Idempotent - no dup!

// Classification with confidence
let updated = service.classify_transaction(ClassifyTransactionRequest {
    tx_id,
    category: "OfficeSupplies".to_string(),
    confidence: "0.93".to_string(),
    actor: "agent".to_string(),
})?;
assert_eq!(updated.category, "OfficeSupplies");
}