Back to buildsBUILD RECORD

Operations Ledger / Business control tooling / 2026

Recording a purchase and its retry result together.

Exact invoice calculations feed one SQLite transaction for the purchase, stock records, audit event and saved response.

Confidential work. Names and identifying business details have been changed.

ROLE
Software engineering
STATE OF THE BUILD
In progress
RECORD UPDATED

THE WORK

The project.

I'm building Operations Ledger to turn a checked invoice allocation into a purchase that can be retried without recording it twice. Integer arithmetic validates the totals before SQLite commits the business records, audit event and replay result together. Its Operations Snapshot Dashboard reads versioned exports over MCP, while writes, corrections and external reconciliation remain in the ledger.

IMPLEMENTATION

Design choices.

  1. Money uses integer minor units instead of binary floating point. Explicit allocation rules reconstruct the invoice total, so a rounding or allocation mismatch is a reason to stop before recording a purchase.
  2. The request key and invoice identity answer different questions. One recognises an exact retry; the other detects an existing purchase even when the caller supplies a new key. Both checks are needed to prevent a new request from duplicating the same invoice.
  3. The saved response commits with the rows it describes. There isn't a later receipt write that can be lost after the purchase succeeds, or an earlier success receipt that can survive a rolled-back purchase.
  4. Corrections and external confirmations have separate records. This keeps local history visible and stops a successful database transaction from being mistaken for confirmation that another accounting system was updated.

HOW IT FITS TOGETHER

Architecture.

  • The MCP service parses serialized input with Zod, resolves the referenced document and converts money and quantities to bigint values. The purchase calculator reconstructs discounts, invoice components and allocations before storage creates any rows. A nonzero variance stops the write.
  • The mutation wrapper starts BEGIN IMMEDIATE and looks up the idempotency key. It compares both the operation name and canonical request digest: an exact retry returns the original result, while changed content is rejected.
  • A new purchase must also pass an invoice-identity check. The store then writes its header, allocated lines and stock receipts, followed by the linked audit event and retry result inside the same transaction. An exception rolls the transaction back.
  • Operations Snapshot Dashboard is a separate view within this project. It reads versioned ledger exports over MCP and also connects to Research Workflow Engine. It has no ownership of the ledger database and adds no write actions; corrections and external readback records remain with the ledger.
Explore the architecture map9 components · 11 connections

Local ledger authority and external readback

Calculations and records belong to the core; external writes remain a separate approved browser workflow.

Direct callAsync taskResponse / returnBlocked / denied
Orchestration
Local core
External evidence and systems

Scroll or drag the background to move. Use the zoom buttons to resize.Arrow keys move between components. Enter selects.

Choose a component to explore

Select a numbered component on the map or use the component menu. Its details and connections will appear here.

No component selected.

All connections (11)
  1. 03 · Source documents → 02 · Codex coordinatorobserved evidence · Response / return
  2. 01 · Owner → 02 · Codex coordinatorscope and authority · Direct call
  3. 02 · Codex coordinator → 04 · MCP contractstyped record · Direct call
  4. 04 · MCP contracts → 05 · Calculation modulesvalidated inputs · Direct call
  5. 05 · Calculation modules → 06 · SQLite ledgeraccepted operation · Direct call
  6. 06 · SQLite ledger → 02 · Codex coordinatorlocal result and next state · Response / return
  7. 02 · Codex coordinator → 07 · Approved browser actionapproved handoff · Async task
  8. 07 · Approved browser action → 08 · Operational/accounting systemsexternal action · Direct call
  9. 08 · Operational/accounting systems → 07 · Approved browser actionread back actual state · Response / return
  10. 07 · Approved browser action → 09 · Readback receiptvia validated core request · Direct call
  11. 06 · SQLite ledger → 08 · Operational/accounting systemsno direct network write · Blocked / denied

MADE WITH

TypeScript · Node.js · SQLite · MCP · Zod

CHECKS & RESULTS

What was checked.

A source review shows what the code does. It is not a fresh test of the running app.

  1. Code and development records reviewedReviewed

    The code, tests and available development records were checked. Reported test results keep their original scope. No fresh app or live deployment check was run for this write-up.

    Scope of this check
    Code review, not a fresh run of the app

NEXT

Still to work through.

The transaction gives the local purchase and its receipt one outcome. Work in another system still needs its own readback and reconciliation, and unsupported corrections remain under review. This account is based on current source, including uncommitted work, without a new test run or inspection of live ledger data.

FROM THE SAME WORK

Technical note

Committing a purchase with the result its retry will receive