Building OmniRecon: governed AI for reconciliation

OmniRecon is a reconciliation system for organisations whose systems disagree about the same event. One system says a customer used a service; another says what they were billed. The useful question is not only whether the numbers differ, but what should happen next and who is allowed to make it happen.

This is an account of the implemented core, the reasoning behind it, and the work deliberately still ahead. It is not a claim of production deployment or measured customer outcomes. The repository uses synthetic data and fixture-backed connectors.

The problem

Operational systems rarely agree perfectly. Usage metering, billing, rate cards, orders, fulfilment, and settlement systems all describe parts of the same reality from different viewpoints. Small disagreements accumulate into two different risks:

• Financial impact: delivered value that was not billed.
• Exposure impact: a customer billed for value that was not delivered.

Those risks are asymmetric. A queue ordered only by dollar value can treat a possible overcharge as less urgent than a larger missed charge. OmniRecon keeps both measures visible so a reviewer can make the right decision for the case.

The design question is therefore: how can software resolve the clear cases quickly without giving an AI system unchecked authority over the ambiguous ones?

The core idea

The system makes deterministic software the engine and AI the exception handler. Rules and tolerances settle the straightforward correspondences. Only the residue becomes a case for investigation and review.

For a non-technical reader, the key point is simple: the system does not ask a model to decide whether it may charge, credit, or alter a record. A model can help investigate and propose. A separate policy and, when needed, a person decide whether anything happens.

source facts
  -> immutable facts with provenance
  -> entity resolution and deterministic matching
  -> settled within tolerance | reconciliation case
  -> investigation and proposed action
  -> independent policy: auto | approval required | denied
  -> constrained executor
  -> later ingestion verifies the outcome

Start with boundaries, not a prompt

The project began with constraints rather than an agent prompt. The core is domain-neutral: it understands facts, correspondences, cases, evidence, policy, and actions. A domain pack supplies the specific fields, matching rules, tolerances, policy defaults, and synthetic fixtures.

The first pack is SaaS revenue reconciliation. Usage metering, billing, and a rate card are compared by account, period, and usage type. A deliberately thin order-fulfilment pack tests whether the core boundary survives a different problem rather than merely claiming it is generic.

This arrangement makes a useful distinction. Domain knowledge belongs in an explicit, inspectable pack. The system that decides what is safe to do remains separate from both the pack and any model.

Preserve evidence before drawing conclusions

Each imported assertion is an immutable, provenance-stamped fact. If a source record changes, a new version is recorded and the prior version remains available for audit. The matcher uses the current version, while a case can pin the exact facts and configuration it used as evidence.

That solves a practical investigation problem: a reviewer should be able to answer "what did the system know at that time?" without reconstructing it from mutable source records.

The reviewer UI is consequently designed as an evidence-first ledger rather than a generic AI control room. The main surface is the case queue and case detail view. It shows the reconciliation ledger, pinned evidence, action payload, revision, audit events, and linked cases before any generated explanation.

Put ordinary arithmetic ahead of AI

The matching engine normalises records into a canonical correspondence, applies pack-defined tolerance, and settles cases that are safely within it. It opens or reuses one active case when a mismatch remains.

Routine arithmetic, identity checks, and tolerance handling are therefore deterministic, testable, and cheap. The current agent workflow performs triage. The broader investigation, adjudication, and execution workflow remains a design direction, not a claim of completed autonomous operation.

The architectural split is deliberate:

Most of the system is deterministic. That is the point.

Treat model output as untrusted input

Source records can contain text written by an external party. That text can be wrong, misleading, or adversarial. Prompting a model to ignore it is not a sufficient defence.

OmniRecon separates trusted instructions, validated domain declarations, and untrusted source data. Facts such as amounts, dates, quantities, and identifiers stay in the deterministic matcher wherever possible. Text that must reach a model is fenced and labelled as data, constrained by field-specific limits, and handled through scoped tools.

A proposed action is not an authorised action. Every proposal is evaluated through a pure policy function outside the agent framework and outside the connectors. The outcome is one of three states:

1. Automatic for narrowly bounded actions.
2. Human approval required for corrective documents, amendments, and fuzzy merges.
3. Denied for actions that must never run autonomously.

The policy is fail-closed. Known low-risk actions can proceed, corrective proposals require approval, and unknown actions are denied. Reviewer approval is bound to the displayed action revision and payload hash, avoiding approval of a quietly changed request.

Design closure as verification, not optimism

An executed correction is not automatically considered resolved. It remains awaiting verification until a later ingestion pass finds the expected correction and reconciles the original correspondence. If that correction is absent or ineffective, the system records the failure and opens a linked follow-up case.

This prevents a common automation failure mode: treating "we attempted a write" as proof that the business state is now correct.

The design therefore makes every correction another claim to reconcile rather than an assumption that disappears after a button is pressed.

Make generated interfaces auditable

Domain packs can produce a compact, read-only UI artifact. The default artifact is deterministic and generated offline. An optional model-assisted mode generates JSON UI constrained to an allowlisted component catalog.

The artifact records model selection, prompt version, and SHA-256 input and output hashes. The application falls back to the deterministic template if no generated artifact is available. This allows useful generation without accepting arbitrary model-generated code into the product surface.

Decisions and trade-offs

What exists today

The current repository includes immutable fact storage and a current-version projection; deterministic SaaS revenue matching and settlement handling; active-case creation, state transitions, event records, action revisions, and fixture-backed correction verification.

It also includes a compiled policy foundation, reviewer API, authenticated review UI, and operational screens for automation, assurance, integrations, and cost. The system has a triage workflow, synthetic fixtures, a local demo flow, and an in-repository test suite.

The reviewer UI includes a browser-local onboarding and recruiter walkthrough. It simulates source and destination setup, MCP URLs, authentication values, notifications, and a sample workflow. It creates no account, connects no system, and sends no email. The distinction is explicit so a demo never implies that a production integration occurred.

What is deliberately not claimed

• No production customer data or live customer connector is used here.
• No real external billing write-back is claimed.
• No benchmark accuracy, safety rate, cost saving, or latency result is published until a reproducible evaluation exists.
• Multi-tenant isolation enforcement, real connector admission, and the full multi-stage agent workflow remain future work.

The intended evaluation is explicit: deterministic settlement, agent residue, policy outcomes, false auto-execution, injection resistance, accuracy by difficulty band, cost per case, and traceable workflow behaviour. Until those runs exist, value claims remain potential rather than observed.

Where it goes next

The next meaningful step is not making the agent more autonomous everywhere. It is earning autonomy narrowly. Repeated, well-evidenced reviewer decisions can be proposed as deterministic configuration changes, evaluated against labelled fixtures and historical cases, and approved by a person before promotion.

That path keeps the original principle intact: the more a pattern becomes known, the less it should need a model.