<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

```bash
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.