Stax Digital Garden

QTM-1002 - Beancount Syntax Integration via Tree-sitter In-Memory ASTs

2 min read

Living Document Notice
Published 2026-09-17. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.

Beancount Syntax Integration via Tree-sitter In-Memory ASTs

Beancount Syntax Integration via Tree-sitter In-Memory ASTs: Dual-trace Phosphor P1 high-persistence green and P4 paper white vector CRT macro showing Tree-sitter AST syntax graphs, Beancount grammar node branching, and real-time validation matrices

Parsing financial ledgers through brittle regular expressions invites catastrophic reconciliation errors. Missing a single minus sign or misinterpreting currency decimal points corrupts balance sheets. Quartermaster uses a dedicated Tree-sitter grammar for Beancount and Ledger syntax, building in-memory Concrete Syntax Trees in microseconds.

Structured Financial AST Parsing

Tree-sitter parses postings, accounts, and monetary amounts into a typed syntax tree:

use tree_sitter::{Parser, Node};
 
pub fn parse_transaction_node(source: &str, node: Node) -> Option<Transaction> {
    if node.kind() != "transaction" {
        return None;
    }
    let date_node = node.child_by_field_name("date")?;
    let payee_node = node.child_by_field_name("payee");
    let narration_node = node.child_by_field_name("narration")?;
    
    // Parse individual balanced postings
    Some(Transaction {
        date: date_node.utf8_text(source.as_bytes()).ok()?.to_string(),
        narration: narration_node.utf8_text(source.as_bytes()).ok()?.to_string(),
        postings: Vec::new(),
    })
}

The concrete syntax tree preserves exact character offsets, allowing surgical updates to transaction tags without touching adjacent narrative text.

High-Performance Balance Verification

Because Tree-sitter compiles to native machine code, validating a 50,000-line historical ledger executes in under 12 milliseconds on local hardware. The parser catches syntax errors immediately inside terminal editors as numbers are typed.

  • Directus Target: quartermaster
  • Garden Source Reference: MOC - Personal Finance, Ledgers & Tax Manifests, MOC - Bosun PKM Tools
  • Garden Source Reference: [QTM-1002 - Beancount Syntax Integration via Tree-sitter In-Memory ASTs](QTM-1002 - Beancount Syntax Integration via Tree-sitter In-Memory ASTs)

Graph View