Reconciliation organizes continuous financial controls into five client-facing concepts: rules, evaluations, alerts, evidence, and resolutions.
Rules#
A rule defines the business control. It contains:
- a control template and its configuration;
- an on-demand or cron schedule;
- a severity and reconciliation cadence;
- optional key-value labels copied to alerts and webhook event payloads;
- an enabled state.
Templates keep the public configuration focused on financial intent. You choose a supported comparison and provide its sources, assets, signs, thresholds, or tolerances; the underlying expression is generated and validated by Reconciliation.
Labels are metadata for downstream consumers; Reconciliation does not interpret them or route work by itself. For example, { "team": "treasury", "environment": "production" } lets your webhook consumer send the resulting alert to the treasury queue while retaining the same tags in its audit record.
Rules are enabled by default. Disabling a rule stops scheduled and on-demand evaluations without deleting its existing evidence or alerts; see Pause or resume a rule for the operational effects.
See Control Templates for the available controls.
Evaluations#
An evaluation is one execution of a rule. It is always persisted and has one of three results:
| Result | Meaning |
|---|---|
PASS | Every checked asset satisfied the control. |
FAIL | At least one asset fell outside the control. |
ERROR | Reconciliation could not complete the check, for example because a source was unavailable. |
For each asset, a passing result stores a compact proof containing the observed balances and predicate inputs needed to verify the result after a rule edit. A failing result stores a fuller evidence breakdown, including the observed values, calculated difference, configured tolerance, and the generated expression used to explain the check. Amount comparisons use arbitrary-precision integers, so large financial values remain exact.
Point-in-time reads#
Each balance source is read at an explicit point in time. By default, Reconciliation subtracts a 30-second safety margin from at. For example, an evaluation requested at 10:00:00 reads the sources at 09:59:30.
The margin avoids evaluating the newest edge of the data, where a Ledger write, connector poll, or balance update may still be reaching one source but not another. It reduces false discrepancies caused by ingestion timing; it does not change or delay the underlying financial activity.
Omit safetyMargin to use the 30-second default. Set it explicitly to "0s" to read exactly at at; this explicit zero is preserved on scheduled rules and is not replaced by the default. It is useful for deterministic tests, demos, and historical evaluations where you control the data and need the exact requested instant. You can also override the effective timestamp for an individual source when systems settle on different cycles.
After resolving the balances, Reconciliation evaluates immutable per-asset snapshots without reading the sources again. The resolved timestamps are stored in pitPerSource on the evaluation. Together with the frozen proof or evidence, this records the financial state that produced the verdict.
If you omit at, Reconciliation asks Payments for its latest known balance. Payments returns the balance but not the time at which that snapshot became effective, so Reconciliation can record only when it fetched the value. Replaying a historical query at that fetch time may therefore return a different snapshot. For a reproducible run, provide a past at or an explicit Payments timestamp in sourcePITs; regardless of the read mode, the values stored in the evaluation remain unchanged.
Alerts#
A failed evaluation opens an alert for each failing fingerprint. In the current templates, the fingerprint is the asset, such as asset:USD/2. A USD discrepancy and a EUR discrepancy therefore become separate cases that can resolve independently.
Alerts have three statuses:
The alert row represents the current state. Its event timeline records every evaluation that touched it and every acknowledgement, snooze, resolution, acceptance, or reopen.
Reconciliation periods#
The rule's cadence determines how alerts are grouped into financial periods:
| Cadence | Example period | Use it for |
|---|---|---|
continuous | continuous | Live monitoring with one ongoing case per asset. |
daily | 2026-07-21 | Daily close or backing checks. |
weekly | 2026-W30 | Weekly operational reconciliation. |
monthly | 2026-07 | Month-end certification and review. |
Within a period, the same asset reuses its alert. A failure in a new daily, weekly, or monthly period creates a new alert, preserving earlier periods as independent records. Period boundaries use UTC.
A period is operationally green when it has no OPEN or ACKNOWLEDGED alerts. Resolved and accepted cases remain available for audit.
Resolutions#
An alert can close in three ways:
| Resolution | When to use it | Recorded context |
|---|---|---|
auto | A later evaluation passes. | System attribution and timestamp. |
fixed_by_booking | Your team made a corrective booking. | Author, optional note, and optional transaction references. |
accepted_by_business | The discrepancy is understood and approved without a correction. | Author, required note, and a frozen evidence snapshot. |
If the control fails again within the same period, the alert reopens and its current resolution is cleared. The previous resolution remains in the append-only timeline.
Data discrepancies and execution errors#
Financial failures create asset alerts. Failures to execute a rule create a separate engine.error alert so operational problems do not look like balance discrepancies. Use the alert labels and fingerprint to route these two classes to different teams.