> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Matcher concepts
> Learn Matcher's five core concepts — contexts, sources, field maps, match rules, and matches — that shape every reconciliation you build.
The five core concepts in Matcher: **contexts**, **sources**, **field maps**, **rules**, and **matches**. Understand these and you'll understand how the entire system works.
## Context
***
A **context** defines what you reconcile. It is the configuration container for sources and rules. Matcher creates a new context in `DRAFT`, and its inline sources and rules are optional.
A context answers: *what am I matching against what?*
You can start with an empty draft. To activate it, configure at least one `LEFT` source and one `RIGHT` source, map every source (or declare valid `camt053` options, which self-map), and add a match rule. If fee normalization is enabled, add a fee rule too.
### Context types
| Type | Description | Example |
| ------- | --------------------------- | -------------------------------------- |
| **1:1** | One-to-one reconciliation | Bank statement vs ERP records |
| **1:N** | One-to-many reconciliation | One payment covering multiple invoices |
| **N:M** | Many-to-many reconciliation | Netting or aggregation scenarios |
### Example
A context named **"Chase Bank vs ERP System"** would:
* Define Chase Bank as one reconciliation source
* Define your ERP system as another source
* Specify the rules used to reconcile transactions between them
## Source
***
A **source** is where transactions come from. A draft context can start without sources; an activatable context needs at least one source on each matching side.
### Source types
* **LEDGER**: Ledger source category
* **BANK**: Bank source category
* **GATEWAY**: Payment-gateway source category
* **CUSTOM**: Custom source category
* **FETCHER**: A Fetcher source category
### Source setup
Each source requires:
* **Name**: Label it (e.g., "Chase Checking")
* **Type**: Category (`LEDGER`, `BANK`, `GATEWAY`, `CUSTOM`, or `FETCHER`)
* **Side**: Which matching side it feeds (`LEFT` or `RIGHT`)
**Config** is optional. If you omit it, Matcher stores an empty config and uses parser defaults for absent policy keys.
Field maps translate each source's fields into Matcher's standard schema.
## Field map
***
A **field map** translates external field names into Matcher's standard schema. Every system calls things differently—field maps normalize that.
### Standard fields
| Field | Required | Type | Description |
| -------------- | -------- | -------- | ----------------------------------------- |
| `external_id` | Yes | String | Source-system transaction identifier |
| `amount` | Yes | Decimal | Transaction amount (positive or negative) |
| `currency` | Yes | String | ISO 4217 currency code |
| `date` | Yes | DateTime | Transaction date |
| `description` | No | String | External reference or description |
| `fee_amount` | No | Decimal | Optional fee amount column |
| `fee_currency` | No | String | Optional fee currency column |
The canonical vocabulary is closed — a field map that declares any other key is rejected.
When a source config declares `camt053` options, Matcher uses its built-in ISO 20022 mapping and ignores a field map; activation treats that source as mapped.
### Example mapping
A bank statement exposing `TXN_ID`, `VALUE`, `CCY`, and `POST_DATE` would be mapped as:
```json theme={null}
{
"external_id": "TXN_ID",
"amount": "VALUE",
"currency": "CCY",
"date": "POST_DATE"
}
```
## Match rule
***
A **match rule** tells Matcher how to compare transactions. Rules run in ascending priority; a transaction claimed by an earlier rule is unavailable to later rules, which still evaluate the remaining transactions.
### Rule types
* **EXACT**: Compares configured fields exactly. Amount, currency, date (by day), and reference are enabled by default.
* **TOLERANCE**: Matches amounts inside the configured absolute and/or percentage tolerance. Omitted amount tolerances and `dateWindowDays` default to `0`, so no drift or date window is allowed until you configure one.
* **DATE\_LAG**: Matches within a configured day-difference band. `minDays` and `maxDays` both default to `0` (same day), not ±3. Like FUZZY, DATE\_LAG matches never auto-confirm — they always go to manual review.
* **FUZZY**: Grades normalized transaction references. It uses `Reference`, populated from the transaction's `ExternalID`; a field-map `description` is not a FUZZY input. FUZZY only proposes—it never auto-confirms, so a human reviews every fuzzy link.
### Priority order
Lower numbers run first. A rule claims its matching transactions; later rules continue with the remaining transactions.
| Priority | Rule | Description |
| -------- | ------------------ | -------------------------------------- |
| 1 | Exact match | Amount, date, and reference must match |
| 2 | Same-day tolerance | Same date, amount within 0.5% |
| 3 | Week tolerance | Within 7 days, amount within 1% |
These priorities and values are illustrative rules, not engine defaults. Configure the values for your reconciliation policy.
### Rule parameters
| Rule type | Parameters |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| EXACT | `matchAmount`, `matchCurrency`, `matchDate`, `matchReference`: which fields must match exactly |
| TOLERANCE | Top-level non-negative `percentTolerance` and/or `absTolerance` values (numbers or decimal strings); optionally set `dateWindowDays` (`0` by default; maximum `3650`). Do not wrap these values in a `tolerance` object. |
| DATE\_LAG | `minDays`, `maxDays`: allowed day-difference band. Both default to `0`, must be from `0` to `3650`, and `maxDays` must be at least `minDays`; `inclusive` defaults to `true` and controls the upper bound. |
| FUZZY | `minSimilarity`: normalized-reference threshold from `0` to `1` (defaults to `0.80`), plus optional amount, currency, and date axes. |
## Match
***
A **match** is when transactions from different sources are reconciled together. It's the end goal.
### Match status
| Status | Description |
| ----------- | -------------------------------------------------------------------------------- |
| `PROPOSED` | Matcher found it, waiting for confirmation |
| `CONFIRMED` | Auto-approved or manually approved |
| `REJECTED` | Manually rejected |
| `REVOKED` | A previously confirmed match was unmatched, returning its transactions to review |
### Match patterns
#### 1:1 match
One transaction from each source is reconciled.
```
Bank: $100.00 on Jan 15 → ERP: $100.00 on Jan 15
```
#### 1:N match
One transaction is reconciled against multiple transactions.
```
Bank: $300.00 → ERP: $100.00 + $100.00 + $100.00
```
#### N:1 match
Multiple transactions are reconciled against a single transaction.
```
Bank: $50.00 + $50.00 + $50.00 → ERP: $150.00
```
#### N:M match
Multiple transactions on each side are reconciled together. N:M evaluation only executes `EXACT` and `TOLERANCE` rules; it considers up to four transactions per side in a group and caps each identity bucket at 40 candidates.
```
Bank: $100.00 + $200.00 → ERP: $150.00 + $150.00
```
### Match items
Each match group contains **match items**, which record transaction participation and allocation.
This enables partial reconciliation in split and aggregation scenarios.
## Exception
***
An **exception** records a transaction that needs review, including unmatched transactions and matched transactions with residual conditions such as FX-rate variance.
### Exception status
| Status | Description |
| -------------------- | ------------------------------------------------ |
| `OPEN` | Waiting for assignment |
| `ASSIGNED` | Someone's investigating |
| `PENDING_RESOLUTION` | A resolution is in progress, awaiting completion |
| `RESOLVED` | Handled |
### Severity
Matcher auto-classifies exceptions so you know what to prioritize.
| Severity | Default criteria |
| ------------ | --------------------------------------------------------------------------------------- |
| **Critical** | Absolute base amount ≥ 100,000, age ≥ 120 hours, or a configured regulatory source type |
| **High** | Absolute base amount ≥ 10,000 or age ≥ 72 hours |
| **Medium** | Absolute base amount ≥ 1,000 or age ≥ 24 hours |
| **Low** | All other cases |
The classifier evaluates the criteria from top to bottom. When an exception meets the criteria of more than one severity, the highest matching severity applies.
### Resolution workflows
* **Resolve**: Record a resolution label and optional reason to close an exception.
* **Force match**: Resolve an exception by forcing a match with an override reason after manual review.
* **Adjust entry**: Resolve an exception by creating an adjustment entry with a reason, notes, positive amount, currency, and effective time.
## Confidence score
***
A **confidence score** indicates the reliability of an automated match on a 0–100 scale.
Higher scores represent stronger alignment between transactions.
### Score calculation
| Component | Weight | Description |
| -------------- | ------ | ----------------------------------------------------------- |
| Amount match | 40% | Degree of amount alignment |
| Currency match | 30% | Currency consistency |
| Date tolerance | 20% | Proximity of transaction dates |
| Reference | 10% | Normalized reference alignment (graded 0–1 for FUZZY rules) |
### Confidence tiers
| Tier | Score range | System behavior |
| ----------------- | ----------- | -------------------------------------------------------------------------------------------------- |
| **Auto-approved** | ≥ 90 | Confirmed automatically (EXACT and TOLERANCE rules only — FUZZY and DATE\_LAG always go to review) |
| **Needs review** | 60–89 | Flagged for manual review |
| **No match** | \< 60 | Does not create a match proposal |
Confidence weights and tier thresholds are fixed by the engine and are not configurable.
## Audit log
***
An **audit log** is an immutable, append-only record created by an instrumented workflow.
It provides traceability for the actions Matcher records.
### Logged events
Only workflows instrumented to emit an audit event create entries. When audit publishing is configured, verified producers include:
* Context, source, field-map, and rule mutations
* Exception workflows, including force match and adjust entry
### Audit entry contents
| Field | Description |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| `createdAt` | Record creation timestamp (UTC), which can differ from the audited action time |
| `actorId` | Actor identifier, when supplied |
| `action` | Action performed |
| `entityType` | Affected entity type |
| `entityId` | Identifier of the affected entity |
| `changes` | Structured JSON event data; emitted events include `occurred_at` and any supplied changes |
| `tenantSeq` | Per-tenant sequence number |
| `prevHash` / `recordHash` | Hash chain linking each entry to the previous one, making tampering detectable |
Audit logs are append-only. Entries cannot be modified or removed.
## Next steps
***
See how these concepts are implemented across bounded contexts.
Apply these concepts in a guided, hands-on flow.