<p align="center"> <img src="./assets/readme/hero.svg" width="100%" alt="ambrook-mcp-guardrail: deterministic pre-flight ledger validator — an AI agent's proposed financial write is treated as untrusted input and validated before the commit boundary. Real test run: 5/5 tests pass, 0 invalid mutations."> </p>

ambrook-mcp-guardrail

A deterministic pre-flight ledger validator proof-of-concept. An AI agent's proposed financial write is treated as untrusted input and validated against ledger invariants before it reaches a commit boundary.

Inspired by Ambrook's publicly described combination of hybrid AI + rule-based systems, MCP-based tooling, and a multidimensional general ledger (enterprise / project / location / funding dimensions).

This is an independent proof-of-concept inspired by those publicly documented design principles. It is NOT Ambrook's internal implementation.

The invariant

<p align="center"> <img src="./assets/readme/pipeline.svg" width="100%" alt="Pipeline: AI agent → mock MCP write_transaction tool call → deterministic pre-flight validator. VALID → commit; INVALID → structured rejection, no commit. Invariant: invalid transaction → zero ledger mutation."> </p>

INVALID TRANSACTION → ZERO LEDGER MUTATION. The commit branch is the only path that mutates the ledger.

How validation works

ledger-rules.ts is a pure, deterministic validator. All errors are collected; if any invariant fails, the entire write is rejected with structured errors ({ code, message }) — no partial writes.

Rule	What it checks
L1 Double-entry balance	Total debits must equal total credits.
L2 Required structure	Transaction ID, ≥1 debit, ≥1 credit, valid positive amounts, currency.
L3 Multidimensional data	Declared enterprise/project/location/funding dimensions must carry structurally valid identifiers — no silent omission.
L4 No partial validation	One failing invariant rejects the whole write; every rejection returns structured errors.

Proof — the actual run

Five simulated agent tool calls (agent-test-suite.ts), all asserted programmatically. No results are hand-written; everything below is generated from execution into results.json.

#	Tool call	Result	Errors reported	Ledger size
1	agent-tool-call-001 — balanced pair	ACCEPT	—	0 → 1
2	agent-tool-call-002 — balanced + 4 valid dimensions	ACCEPT	—	1 → 2
3	agent-tool-call-003 — unbalanced 1000 / 900	REJECT	UNBALANCED_ENTRY	2 → 2
4	agent-tool-call-004 — missing debit, empty dimension ID	REJECT	MISSING_TX_ID, MISSING_DEBIT, UNBALANCED_ENTRY, INVALID_DIMENSION	2 → 2
5	agent-tool-call-005 — multi-violation	REJECT	INVALID_AMOUNT, UNBALANCED_ENTRY, INVALID_DIMENSION	2 → 2

• 8/8 assertions pass, including: every invalid write changes ledger size by zero, and the final ledger contains only the two valid transactions.
• Deterministic: three consecutive runs produced byte-identical output and an identical results.json.

Run it

npm install
npm run build
npm test

npm test compiles, runs the suite, asserts all invariants, and regenerates results.json — exiting non-zero on any failure.

Structure

ledger-types.ts       domain types (Transaction, ToolCall, ValidationError, …)
ledger-rules.ts       deterministic rules L1–L4
mock-mcp-server.ts    mock MCP boundary: write_transaction + in-memory ledger
agent-test-suite.ts   5 simulated agent writes + 8 assertions → results.json

Limitations

• Mock MCP boundary, in-memory ledger, synthetic transactions — no Ambrook infrastructure was touched.
• No production performance claim, and no claim about how Ambrook actually implements validation.
• Zero runtime dependencies: standard Node.js only, no network, no LLM calls, no API keys.