VaultEq Core — MVP v1.1

LLMs orchestrate. VaultEq computes.

A deterministic, auditable double-entry accounting engine built for AI agent orchestration. This is the foundational 10% of FinanceX — the part you ship before writing another line of design doc.

What's inside

Design decisions

• Amounts are integer minor units (BIGINT, cents) — never floats, never unconstrained decimals in storage.
• Audit events are hash-chained (prev_event_hash → SHA-256 of previous event). This proves deletion resistance, not just modification resistance.
• Idempotency is real, not cosmetic:
  • Same key + same payload → returns cached PostResponse (safe retry)
  • Same key + different payload → DUPLICATE_IDEMPOTENCY_KEY conflict
  • Check is atomic under BEGIN IMMEDIATE with explicit transaction control (isolation_level=None)
  • Belt-and-suspenders: IntegrityError from the UNIQUE constraint is caught and resolved into proper retry or conflict
• Error taxonomy is explicit and complete:

Run it

python demo.py        # functional demo
python race_test.py   # concurrent idempotency verification

No dependencies. Uses Python stdlib + SQLite.

Why the race test proves what it proves

race_test.py uses separate sqlite3 connections per thread (not a shared connection, which would serialize through Python's GIL and mask real cross-connection races) and a threading.Barrier to force both threads into post() at the same instant rather than hoping for a scheduling accident. It asserts the invariant that matters: exactly one journal entry in the database, both threads returning the same journal ID, and zero raw IntegrityError exceptions leaking to the caller. This is a legitimate concurrency test, not a token one.

What works now

• Organization & Chart of Accounts management
• Double-entry journal posting with strict balance validation
• Real idempotency — safe retries return cached responses, conflicts are explicit
• Atomic idempotency under SQLite reserved lock with explicit transaction control
• Race-safety verified — concurrent threads with same key produce exactly one journal entry
• Immutable, hash-chained audit trail
• Trial balance query
• Audit chain integrity verification
• Complete error taxonomy with structured JSON responses

What's intentionally deferred

• Multi-currency FX rates (MVP enforces base-currency only)
• Period close / lock
• Journal reversals
• HTTP API layer (FastAPI wrapper)
• Concurrent post safety at scale (SQLite serializes; prod needs row-level locking in Postgres)
• Postgres migration (swap connection string, schema is compatible)

The one thing to remember

This is infrastructure, not a fintech. Your first customer is a developer building an AI agent that needs to post a journal without hallucinating the math.

Ship this. Get feedback. Then build PaymentsX.