l3dg3rr

Note on naming: This project uses multiple names (l3dg3rr, ledgerr-mcp, ledgrrr, ledg3rr) depending on context. See POLYSEME-MAP.md for the mapping.

l3dg3rr is a general-purpose, git-versioned systems modeling and action/decision registry: a strongly typed, ontologically linked graph of scriptable, visual-first workflows, where Rust owns structural invariants, Rhai owns editable classification and workflow rules, and AI/LLM agents drive supervised ETL through MCP tools without taking custody of credentials or approval authority. Local-first bookkeeping — turning financial documents into an accountant-usable, CPA-auditable source of truth — is the first dogfood vertical proving out that substrate, not the project's purpose. Requirements (ReqIF), schema/data modeling (LinkML), and a decision+cost ledger are newer verticals sitting on the same substrate: the ontology graph, the evidence chain, Rhai policy, and KerML/OWL2 metamodel work.

Read the live book: https://promptexecution.github.io/ledgrrr/

Bookkeeping vertical's primary outcome: ingest raw historical statements, classify and reconcile transactions, preserve evidence and mutation history, then export a CPA-reviewable Excel workbook without requiring private data to leave the local machine.

System Thesis

The project is intentionally not just a PDF parser, a rules folder, or a visualization experiment. Those are subsystems of one general process/action control plane, expressed here through its original bookkeeping vertical:

fn source_documents() -> typed_document_graph
fn typed_document_graph() -> extraction_and_normalization
fn extraction_and_normalization() -> transaction_classification
fn transaction_classification() -> validation_and_legal_checks
fn validation_and_legal_checks() -> reconciliation
fn reconciliation() -> workbook_export
fn workbook_export() -> cpa_review
fn cpa_review() -> audit_history

The workbook remains that vertical's human and accounting interface. The graph, sidecar state, Rhai rules, MCP tools, and visualization layers exist to make it reproducible, explainable, and agent-accessible — and the same typed-state machine now also governs non-bookkeeping verticals (requirements, decisions, costs) and agent capability discovery/skill lifecycle, not just financial documents.

Design Lens: TRIZ + MECE

l3dg3rr resolves recurring product contradictions by separating concerns instead of adding one-off glue:

MECE module grouping keeps the logic approachable:

Bookkeeping Flow

1. Ingest: accept statement files named VENDOR--ACCOUNT--YYYY-MM--DOCTYPE.ext, infer document shape, and normalize rows.
2. Identify: generate deterministic Blake3 transaction IDs from account/date/amount/description so re-ingest is idempotent.
3. Classify: run a deterministic Rhai rule waterfall over each transaction and flag low-confidence results.
4. Validate: compound stage confidence, attach typed issues, and separate unrecoverable, recoverable, and advisory dispositions.
5. Reconcile: compare local facts against Xero or other external evidence through supervised capability tools.
6. Export: rebuild the CPA workbook projection with transactions, schedule summaries, flags, and AUDIT.log history.
7. Review: keep human/CPA signoff in Excel while preserving agent-visible evidence paths.

Rhai Rules And Match/Switch Visualization

There are three related but distinct Rhai surfaces:

The match operator discussed in the docs is a switch-like visualization idiom for branch-heavy workflows. Repeated arms with the same expression collapse into one semantic match node:

fn verify_result() -> match_result_disposition
match result.disposition => Disposition::Unrecoverable -> halt_pipeline
match result.disposition => Disposition::Recoverable -> repair_and_retry
match result.disposition => Disposition::Advisory -> record_note
match result.disposition => _ -> operator_review
fn repair_and_retry() -> requeue_validation

Current behavior:

Deep references:

• Live docs: https://promptexecution.github.io/ledgrrr/
• Match Visualization Plan
• Visualization
• Workflow
• Ontology & Type Mesh

Current Capability Snapshot

See Capability Map for the full component table.

Future Ambitions

The roadmap beyond the current stable capability set spans three planned directions. See the linked PRDs for full specification.

PRD-7: Legal Intelligence Layer — Constraint Synergies

PRD-7.md specifies the complete integration of the three verification layers (Kasuari constraint solver, Z3 legal solver, typed pipeline) into a unified, jurisdiction-aware pipeline.

Phase 0 is implemented (constraint + legal signals now flow into MetaCtx and produce typed Issues). Remaining phases:

• Phase 1: FBAR, FEIE, AU s40-5, AU FBT production rule evaluation with TransactionFacts auto-populated from pipeline state
• Phase 2: Symbolic Z3 upgrade — violations produce full Z3 models with satisfying assignments, not just witness strings; constraint consistency xtask checks vendor profiles against legal rule sets
• Phase 3: Excel _audit sheet materialization — every committed transaction row gets constraint_score, legal_result, disposition, and stage_trace_json columns for CPA review

PRD-8: Kani Formal Verification

PRD-8.md specifies a formal verification suite using the Kani bit-precise model checker to prove the type system has no arithmetic gaps between versions.

Key harnesses planned:

• InvoiceConstraintSolver arithmetic correctness (no overflow, correct GST tolerance)
• VendorConstraintSet interval invariants (p05 ≤ p95, non-negative)
• EvidenceGraph structural integrity (no duplicate nodes/edges, NodeId determinism)
• EvidenceChain<S> typestate transition completeness
• Blake3 ID determinism (same inputs → same hash, always)
• CommitGate exhaustiveness (every Reconciled state routes to exactly one gate)

PRD-6-FUTURE: Type Attestation System

PRD-6-FUTURE.md defines a longer-horizon capability: a #[attested("invariant")] proc-macro lint that forces any type claiming a formal property to provide machine-verifiable assertions checked by both Z3 (logical predicates) and Kasuari (numerical bounds), formally proved by Kani, and recorded in an immutable append-only invariant ledger.

Core idea: the Excel workbook gains a _invariants sheet where every type-level claim (e.g., "this invoice GST arithmetic is valid", "this pipeline state has passed legal review") is a persistent, Blake3-chained record linking the runtime verification result to the Kani proof that held at build time. New invariants can be registered by any crate at runtime without modifying ledger-core, making the knowledge system self-extensible.

This closes the gap between structural type safety (what the Rust type system currently enforces) and semantic correctness (what a CPA needs to trust the output).

PRD-11: Desktop Agent, MCPB Bootstrapper, Office Playbook, and Local Simulation Runtime

PRD-11.md defines the Windows and Microsoft 365 product packaging target. Claude Desktop receives a MCPB bundle containing a small ledgrrr-mcp controller (Phase 1 implemented — see MCPB Binary Distinction). The privileged desktop stack will be installed by a native Windows package, which owns ledgrrr-service.exe, ledgrrr-tray.exe, local model/runtime assets, repair/uninstall, and update metadata.

The same ledgrrr playbook model is exposed through Claude, b00t, OneNote/Office, and SharePoint:

• Claude calls explicit MCP tools such as ledgrrr_status, ledgrrr_install_plan, ledgrrr_render_diagram, and ledgrrr_simulate_pipeline.
• b00t discovers ledgrrr through typed datums and stable status, install --dry-run, render, simulate, and export-office JSON contracts.
• OneNote/Office add-ins insert and refresh versioned Mermaid/SVG/PNG/HTML playbook artifacts.
• SharePoint SPFx renders the same published playbook artifacts.
• The local service supports deterministic simulation and local CPU fine-tuned inference without cloud dependency.

<|🥾|> b00t — Capability Surface

l3dg3rr works in concert with the _b00t_ ecosystem: a mesh of typed, lazy-loaded capabilities that govern how agents discover, install, and execute skills, roles, and blessings.

Datum Types

Every capability in the b00t mesh is expressed as a .datum file — a typed document with a structured AST (crates/datum/src/ast.rs), logic gate primitives (crates/datum/src/logic.rs), protocol encoding analysis (crates/datum/src/protocol.rs), and .tomllmd compound document format for summary-level distillation (verbatim / executive / epigram).

Core datum types in the mesh:

Lazy Loading

Skills are lazy-loaded by progressive disclosure: a skill is only ingested into context when a matching capability trigger fires. The capability map (B00T-CAPABILITY-MAP.md) tracks which datums map to which skill names, and the RuleRegistry (crates/ledger-core/src/rule_registry.rs) uses deterministic keyword waterfall + semantic candidate selection to route requests to the right rule set.

Ralph Loop & Autoresearch

Between capability loads and skill iterations, the Ralph loop (crates/b00t-iface/src/ralph.rs) drives an iterative propose → execute → judge → record cycle:

Init → [Propose → Execute → Judge → Record → Maintain]^n → Terminate

This generalizes the karpathy/autoresearch pattern as a typed ProcessSurface with governance-enforced TTL, crash budget, max iterations, and cadence. Each iteration generates an ExperimentVerdict (Pass/Fail) that feeds into the next proposal — the agent keeps iterating until the task objective is met or the budget is exhausted.

The SurfaceHarness (crates/b00t-iface/src/exec/harness.rs) wraps any ProcessSurface with a SurfaceMachine state machine and GovernancePolicy constraints, producing a PromiseChain audit record for every lifecycle transition.

Soul Configuration

The system determines capability preference using an ordered match of agent role tier (sm0l / ch0nky / frontier), skill invariant tags, and context window budget. Selection follows:

1. Agent role tier (Executive → Operator → Specialist → Auditor)
2. Skill invariant tags (#kebab-case tags from crates/ledger-core/src/tags.rs)
3. Context window budget (truncation-aware, preferring smaller datum summary levels)
4. Compounding metadata — .tomllmd merge strategies can combine two+ datums at different summary levels into a higher-order meta-learn datum

Datum Visualization

Datum types have a dedicated visualization layer:

• Gate-level: crates/datum/src/logic.rs defines NAND, NOR, ADD, WAIT, TX, RX, CAP gates with typed port arity and flux capacitor meta-state stability
• Protocol encoding: crates/datum/src/protocol.rs evaluates Z3-style XOR optimality (O = P XOR B) and constraint strength (Required / Strong / Medium / Weak)
• Isometric rendering: crates/b00t-iface/src/viz/mod.rs produces SVG/glTF scene graphs with semantic role-driven icon/color/layout
• Live editor: The mdBook live Rhai editor (synchronized isometric and Mermaid views) renders datum-type graphs with animated SVG reflow

Agent/MCP Interop

The McpProvider trait (crates/ledgerr-mcp/src/provider.rs) and McpProviderRegistry allow b00t's external MCP providers (b00t-mcp, just, ir0ntology) to register their tools alongside the built-in ledgerr_* capability families. The ServiceActor gate system (crates/ledgerr-mcp/src/actor.rs, gate.rs) routes typed messages through channels, forming the concrete dataflow that maps to the flux capacitor gate metaphor.

---

Humble Beginnings

This project started as a local-first bookkeeping pipeline — ingest PDF statements, classify transactions with Rhai rules, export a CPA-auditable Excel workbook (see System Thesis above; that pipeline is still real and still works). The architecture kept revealing a deeper structure: the bookkeeping pipeline was one surface of a more general systems-modeling and action/decision registry, which is why the framing at the top of this README no longer leads with tax/bookkeeping. The same MetaCtx carry-forward confidence model that compounds validation scores also governs which b00t capabilities load into agent context, and the same typed-state machine now governs requirements/decisions/costs, not just financial documents.

---

Documentation Map

The published book is the detailed reference and should be preferred over expanding the README indefinitely:

• https://promptexecution.github.io/ledgrrr/: live GitHub Pages book
• Introduction: product guarantees and primary surfaces
• MCP Surface: published ledgerr_* tool families
• Document Ingestion: source routing and extraction assumptions
• Rule Engine: Rhai classification model
• Workbook & Audit: CPA-facing artifact contract
• Visualization: live editor and visual idioms
• Match Visualization Plan: match/switch branch contract

Build and validate docs locally:

just docgen
just docgen-check
just docserve

Developer Quick Start

Prerequisites:

Common recipes:

# Run the full test suite plus MCP outcome smoke path.
just test

# Build the book into book/book/.
just docgen

# Validate diagrams, links, and live Rhai JS tests.
just docgen-check

# Serve the book locally with live Rhai editing.
just docserve

# Start the stdio MCP server.
just mcp-start

Use Justfile as the executable workflow contract. When a command changes, update the recipe first and reference the recipe name from docs.

MCPB Binary Distinction

This project produces two distinct .mcpb bundles for different use cases:

Use just bundle for the domain server MCPB and just package-desktop-mcpb for the desktop controller. The desktop controller .mcpb directory can be referenced directly in Claude Desktop's MCP config.

Agent And MCP Guide

• AGENTS.md: agent-facing operating rules, product constraints, and persistent session guidance.
• docs/mcp-capability-contract.md: MCP tool matrix, argument contracts, service mappings, and usage flow.
• crates/ledgerr-mcp/src/contract.rs: source of truth for the published MCP surface.

The default MCP catalog should stay collapsed to the top-level ledgerr_* capability families. Add sub-operations through required action parameters instead of expanding the default tool list.

Release and Versioning Policy

l3dg3rr follows an odd/even minor version convention, similar to the Ubuntu LTS model.

Release commands

# Release bump — outcome depends on the next version:
# - even minor => stable release, full test gate including phi4 inference, GitHub release created
# - odd minor => dev/experimental release, fast gate only, no stable GitHub release
just release minor   # or: just release major / just release patch

# Fast test gate only (excludes phi4 GGUF inference, ~seconds)
just test-fast

What the release recipe does

1. Detects the next version's minor parity and selects the appropriate test gate:
   • Even minor (stable) — full cargo test suite including phi4 GGUF inference
   • Odd minor (dev) — fast gate only (--skip phi4_produces_output --skip phi4_mistral_produces_output)
2. Runs ./scripts/e2e_mvp.sh end-to-end smoke path
3. Calls cog bump --<version> — sets version in all Cargo.toml files, creates a conventional-commit bump commit and a semver git tag
4. Pushes branch and tags to origin with git push --follow-tags
5. Even minor — creates a stable GitHub release (gh release create --latest)
6. Odd minor — creates a GitHub pre-release (gh release create --prerelease)

Pushing the tag triggers .github/workflows/docs.yml, which redeploys GitHub Pages regardless of minor parity.

Downloading a release

All release artifacts are attached to the corresponding GitHub Release once .github/workflows/mcpb-publish.yml (MCP server bundles) and .github/workflows/msi-publish.yml (desktop app installer) finish running for that tag:

If a given release page is missing an artifact you expect, check that workflow's run for that tag — matrix legs can fail independently without blocking the others (mcpb-publish.yml's upload job only requires at least one platform to succeed).

To install the desktop app on Windows: download the .msi from the latest stable release and run it. To run the domain MCP server locally instead of downloading a binary, see just mcp-podman-run above or build from source with just bundle.

Docker

docker build -f Containerfile -t l3dg3rr:dev .
docker run --rm -i \
  -v "$PWD/data:/data" \
  l3dg3rr:dev

The container runs ledgerr-mcp-server over stdio. Mount /data for local workbook and document inputs.