Data vault bookkeeping substrate

@@ -17,42 +17,42 @@ cites:
paired_with: data-vault-bookkeeping-substrate.es.md
---

The dominant pattern in SMB accounting software places the general ledger, chart of accounts, and transaction history inside a proprietary database operated by the software vendor. Migration between platforms requires re-importing journal entries, reconciling every period, and re-linking source documents manually — a process that routinely costs thousands of dollars in accountant time. The data vault bookkeeping substrate addresses this structural lock-in by separating the canonical record from every tool that consumes it, applying the same [[worm-ledger-design|WORM ledger discipline]] used across [[three-ring-architecture|Ring 1 boundary services]].
The dominant pattern in SMB accounting software places the general ledger, chart of accounts, and transaction history inside a proprietary database operated by the software vendor. Migration between platforms requires re-importing journal entries, reconciling every period, and re-linking source documents manually — a process that routinely costs thousands of dollars in accountant time. The data vault bookkeeping substrate is a planned architecture intended to address this structural lock-in by separating the canonical record from every tool that consumes it, applying the same [[worm-ledger-design|WORM ledger discipline]] used across [[three-ring-architecture|Ring 1 boundary services]] elsewhere in the platform. **Today, the only shipped surface is a single-panel UI placeholder** (`app-console-bookkeeper`, an `os-console` cartridge) displaying a static "awaiting sync" figure — none of the vault, ledger, or accounting logic described below is built yet.

## Three structural inversions
## Three structural inversions (planned)

The substrate rests on three architectural choices that invert the hyperscaler pattern:
The substrate is designed around three architectural choices. Together they are intended to invert the hyperscaler pattern:

**The vault is the only canonical layer.** Source documents — invoices, receipts, purchase orders — arrive in any supported format and are stored immutably in the platform's append-only ledger. The parsed semantic fields, the original document, and a cryptographic commitment are stored together. The vault retains the original document alongside every derived representation of it; nothing is ever overwritten.
**The vault would be the only canonical layer.** Source documents — invoices, receipts, purchase orders — would arrive in any supported format and be stored immutably in the platform's append-only ledger. The parsed semantic fields, the original document, and a cryptographic commitment would be stored together, with the original retained alongside every derived representation of it.

**Bookkeeping and accounting are separate concerns.** The bookkeeping application is a read surface: it allows browsing, auditing, searching, and exporting from the vault. The accounting application is a productive surface: it generates trial balances, financial statements, and tax compliance documents. The customer's accountant can use any tool — including tools the vendor has no relationship with — against the vault export. The vendor does not own the accounting logic; it owns the vault platform, not the data within it.
**Bookkeeping and accounting would be separate concerns.** A bookkeeping application would be a read surface: browsing, auditing, searching, and exporting from the vault. An accounting application would be a productive surface: generating trial balances, financial statements, and tax compliance documents. The customer's accountant would be able to use any tool — including tools the vendor has no relationship with — against the vault export. The intent is for the vendor to own the vault platform, not the data within it.

**No accounting logic lives inside the vault.** The vault stores facts; consumers compute derived views. Migration away from the accounting tool is structurally costless: the vault remains intact, the new tool replays the ledger, and the derived views are rebuilt from the same canonical source.
**No accounting logic would live inside the vault.** The vault would store facts; consumers would compute derived views. Migration away from the accounting tool is intended to be structurally costless: the vault stays intact, the new tool replays the ledger, and the derived views rebuild from the same canonical source.

## Three layers
## Three planned layers

The substrate has three architectural layers:
The substrate's design calls for three architectural layers, none of which exist in code today:

**The vault layer** organizes parsed invoice data into a flat-file structure with three directories: `/source` (the original documents, immutable, SHA-256 hashed), `/ledger` (the double-entry journal, append-only, cryptographically signed per row), and `/asset` (materialized derived views of account balances, rebuildable from the ledger by replay and never the source of truth). Corrections to journal entries are compensating entries, never row edits.
**A vault layer** would organize parsed invoice data into a flat-file structure with three directories: `/source` (the original documents, immutable, SHA-256 hashed), `/ledger` (the double-entry journal, append-only, cryptographically signed per row), and `/asset` (materialized derived views of account balances, rebuildable from the ledger by replay and never the source of truth). Corrections to journal entries would be compensating entries, never row edits.

**The bookkeeping layer** provides the read-mostly query surface: browse journals by date, account, vendor, or amount; view source documents inline; run full-text searches; export to CSV with source-document references preserved. The bookkeeper uses this layer for daily entry and audit work.
**A bookkeeping layer** would provide the read-mostly query surface: browse journals by date, account, vendor, or amount; view source documents inline; run full-text searches; export to CSV with source-document references preserved.

**The accounting layer** provides the productive surface for trial balance generation, financial statement preparation, and tax compliance work. It reads from the vault export and produces documents using whichever accounting tool the customer chooses. The vault export is the interface; no single accounting tool is required.
**An accounting layer** would provide the productive surface for trial balance generation, financial statement preparation, and tax compliance work, reading from the vault export and producing documents using whichever accounting tool the customer chooses.

## E-invoicing native support
## E-invoicing native support (planned)

European regulatory mandates are making structured electronic invoice formats — EN 16931-compliant XML in the Peppol and ZUGFeRD specifications — compulsory for business-to-business transactions on a rolling schedule from 2025 to 2028. The substrate is designed to ingest these formats natively alongside PDF invoices. The United States does not have a comparable federal mandate as of 2026; PDF remains dominant, though the FedNow instant-payment network carries ISO 20022 remittance data that the substrate is intended to support.
European regulatory mandates are making structured electronic invoice formats — EN 16931-compliant XML in the Peppol and ZUGFeRD specifications — compulsory for business-to-business transactions on a rolling schedule from 2025 to 2028. The substrate is intended to ingest these formats natively alongside PDF invoices, once built. The United States does not have a comparable federal mandate as of 2026; PDF remains dominant, though the FedNow instant-payment network carries ISO 20022 remittance data the substrate may support.

## Audit and assurance
## Audit and assurance (planned)

The substrate's structure satisfies the chain-of-custody requirements of ISAE 3402 Type II and SOC 2 Processing Integrity by construction:
The substrate's structure is designed to satisfy the chain-of-custody requirements of ISAE 3402 Type II and SOC 2 Processing Integrity by construction, once built. Four properties would apply:

- Original source documents are retained immutably alongside their parsed representations.
- Journal entries reference their source documents and are cryptographically signed by an authorized identity.
- The append-only ledger property means retroactive modification is structurally impossible without detection.
- Monthly anchoring to a public transparency log produces independently verifiable evidence that the ledger state at each checkpoint has not been altered.
- Original source documents retained immutably alongside their parsed representations.
- Journal entries that reference their source documents and are cryptographically signed by an authorized identity.
- An append-only ledger property that makes retroactive modification structurally impossible without detection.
- Monthly anchoring to a public transparency log, producing independently verifiable evidence that ledger state at each checkpoint has not been altered.

A quarterly attestation report cites these properties explicitly. An auditor can verify the attestation independently using publicly available verification tooling, without relying on the vendor's characterization of their own controls. This is a categorically different property from a vendor's SOC 2 report, which attests the vendor's controls over the vendor's infrastructure rather than the customer's data integrity.
The intent is for a quarterly attestation report to cite these properties explicitly, verifiable by an auditor independently using public tooling rather than relying on the vendor's characterization of its own controls — a categorically different property from a vendor's SOC 2 report, which attests the vendor's controls over the vendor's infrastructure rather than the customer's data integrity. None of this exists today; no attestation report can be produced against an unbuilt vault.

## Why structural lock-in cannot be replicated at enterprise cloud scale