# vgrid recon

Config-driven reconciliation engine that matches records across 2 or 3 data sources (processor, ledger, bank). Reads a `.recon.toml` config defining roles, column mappings, transforms, and pair strategies; loads CSVs; aggregates by match key + currency; matches per configured pair; classifies into buckets; and emits JSON.

## recon run

Run a reconciliation from a TOML config file.

```bash
vgrid recon run <config.recon.toml> [options]
```

| Option | Description |
|--------|-------------|
| `--json` | Output JSON to stdout (in addition to human summary on stderr) |
| `--output <path>` | Write JSON output to file |

### Examples

```bash
# Run with human summary to stderr
vgrid recon run stripe-qbo.recon.toml

# JSON to stdout
vgrid recon run stripe-qbo.recon.toml --json

# Save JSON to file
vgrid recon run stripe-qbo.recon.toml --output result.json

# Both: save to file + print to stdout
vgrid recon run stripe-qbo.recon.toml --json --output result.json
```

### Human summary

Always printed to stderr:

```
2-way recon: 4 groups — 2 matched, 0 amount mismatches, 0 timing mismatches, 2 unmatched
```

---

## recon validate

Check a config file for correctness without running the reconciliation.

```bash
vgrid recon validate <config.recon.toml>
```

### Examples

```bash
vgrid recon validate stripe-qbo.recon.toml
# valid: 2-way recon 'Stripe ↔ QBO' with 2 role(s), 1 pair(s)
```

---

## Config format

Configs use `.recon.toml` extension. CSV file paths are resolved relative to the config file's directory.

### Minimal 2-way example

```toml
name = "Stripe ↔ QBO Payout Recon"
way = 2

[roles.processor]
kind = "processor"
file = "stripe.csv"

[roles.processor.columns]
record_id  = "source_id"
match_key  = "group_id"
amount     = "amount_minor"
date       = "effective_date"
currency   = "currency"
kind       = "type"

[roles.processor.filter]
column = "type"
values = ["payout"]

[roles.processor.transform]
multiply = -1
when_column = "type"
when_values = ["payout"]

[roles.ledger]
kind = "ledger"
file = "qbo.csv"

[roles.ledger.columns]
record_id  = "source_id"
match_key  = "source_id"
amount     = "amount_minor"
date       = "effective_date"
currency   = "currency"
kind       = "type"

[roles.ledger.filter]
column = "type"
values = ["deposit"]

[pairs.processor_ledger]
left = "processor"
right = "ledger"
strategy = "fuzzy_amount_date"

[tolerance]
amount_cents = 0
date_window_days = 2
```

### 3-way example

```toml
name = "Stripe ↔ QBO ↔ Mercury"
way = 3

# ... processor and ledger roles same as above ...

[roles.bank]
kind = "bank"
file = "mercury.csv"

[roles.bank.columns]
record_id  = "source_id"
match_key  = "source_id"
amount     = "amount_minor"
date       = "effective_date"
currency   = "currency"
kind       = "type"

[roles.bank.filter]
column = "type"
values = ["deposit"]

[pairs.processor_ledger]
left = "processor"
right = "ledger"
strategy = "fuzzy_amount_date"

[pairs.processor_bank]
left = "processor"
right = "bank"
strategy = "fuzzy_amount_date"

[tolerance]
amount_cents = 0
date_window_days = 2
```

### Config reference

| Field | Required | Description |
|-------|----------|-------------|
| `name` | yes | Human-readable name for the recon |
| `way` | yes | `2` (one pair) or `3` (two pairs) |
| `roles.<name>` | yes | At least 2 roles required |
| `roles.<name>.kind` | yes | `processor`, `ledger`, or `bank` |
| `roles.<name>.file` | yes | Path to CSV file (relative to config) |
| `roles.<name>.columns` | yes | Column mapping (see below) |
| `roles.<name>.filter` | no | Row filter: keep only rows where `column` is in `values` |
| `roles.<name>.transform` | no | Amount transform: `multiply` with optional `when_column`/`when_values` |
| `pairs.<name>.left` | yes | Role name for left side |
| `pairs.<name>.right` | yes | Role name for right side |
| `pairs.<name>.strategy` | no | `exact_key` (default) or `fuzzy_amount_date` |
| `tolerance.amount_cents` | no | Max allowed amount difference in cents (default: `0`) |
| `tolerance.date_window_days` | no | Max allowed date offset in days (default: `0`) |

### Column mapping

Every role must map these 6 columns to CSV header names:

| Column | Purpose |
|--------|---------|
| `record_id` | Unique row identifier (e.g. `source_id`) |
| `match_key` | Aggregation/matching key (e.g. `payout_id`, `deposit_id`) |
| `amount` | Integer cents column (e.g. `amount_minor`) |
| `date` | Date column, `YYYY-MM-DD` format (e.g. `effective_date`) |
| `currency` | Currency code (e.g. `USD`). Part of the aggregation key — never matches across currencies |
| `kind` | Row type (e.g. `payout`, `deposit`). Used by filters |

### Matching strategies

**`exact_key`** (default): Matches aggregates by `(match_key, currency)`. Both sides must use the same key space (e.g. payout ID).

**`fuzzy_amount_date`**: Matches aggregates by amount and date within tolerance. Same currency required. Greedy best-match: smallest `|amount_delta| + |date_offset|` wins. Use when left and right have different key spaces.

### Filters

Keep only rows where the named column's value is in the list:

```toml
[roles.processor.filter]
column = "type"
values = ["payout"]
```

### Transforms

Modify amounts conditionally. Currently supports `multiply`:

```toml
[roles.processor.transform]
multiply = -1              # Negate the amount
when_column = "type"       # Only when this column...
when_values = ["payout"]   # ...has one of these values
```

If `when_column`/`when_values` are omitted, the transform applies to all rows.

---

## Aggregation

Records are grouped by `(match_key, currency)` per role. Within each group:

- Amounts are summed (integer cents, `i64`)
- The earliest date is used as the group date
- All `record_id` values are preserved

This means multiple charges/fees/refunds with the same payout ID roll up into one aggregate before matching.

---

## Bucket classification

### 2-way buckets

| Bucket | Meaning |
|--------|---------|
| `matched_two_way` | Matched within tolerance |
| `amount_mismatch` | Matched by key but amount delta exceeds `amount_cents` |
| `timing_mismatch` | Matched by key but date offset exceeds `date_window_days` |
| `processor_ledger_only` | Left-side aggregate with no match on right |
| `ledger_only` | Right-side aggregate with no match on left |

### 3-way buckets

3-way recon runs two pairs (e.g. processor↔ledger, processor↔bank) and merges results:

| Bucket | Meaning |
|--------|---------|
| `matched_three_way` | Matched in both pairs |
| `processor_ledger_only` | Matched processor↔ledger but no bank match |
| `processor_bank_only` | Matched processor↔bank but no ledger match |
| `ledger_only` | Ledger aggregate with no match |
| `bank_only` | Bank aggregate with no match |
| `amount_mismatch` | Key matched but amount out of tolerance (either pair) |
| `timing_mismatch` | Key matched but date out of window (either pair) |

---

## JSON output

```json
{
  "meta": {
    "config_name": "Demo: Missing Deposits",
    "way": 2,
    "engine_version": "0.9.0",
    "run_at": "2026-02-17T17:53:20+00:00"
  },
  "summary": {
    "total_groups": 4,
    "matched": 2,
    "amount_mismatches": 0,
    "timing_mismatches": 0,
    "left_only": 2,
    "right_only": 0,
    "bucket_counts": {
      "matched_two_way": 2,
      "processor_ledger_only": 2
    }
  },
  "groups": [
    {
      "bucket": "matched_two_way",
      "match_key": "po_501",
      "currency": "USD",
      "aggregates": {
        "processor": {
          "role": "processor",
          "match_key": "po_501",
          "currency": "USD",
          "date": "2026-01-12",
          "total_cents": 24275,
          "record_count": 1,
          "record_ids": ["po_501"]
        },
        "ledger": {
          "role": "ledger",
          "match_key": "dep_501",
          "currency": "USD",
          "date": "2026-01-13",
          "total_cents": 24275,
          "record_count": 1,
          "record_ids": ["dep_501"]
        }
      },
      "deltas": {
        "delta_cents": 0,
        "date_offset_days": -1
      }
    },
    {
      "bucket": "processor_ledger_only",
      "match_key": "po_503",
      "currency": "USD",
      "aggregates": {
        "processor": {
          "role": "processor",
          "match_key": "po_503",
          "currency": "USD",
          "date": "2026-01-15",
          "total_cents": 48550,
          "record_count": 1,
          "record_ids": ["po_503"]
        }
      },
      "deltas": {}
    }
  ]
}
```

---

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | All groups matched within tolerance |
| 1 | Mismatches found (amount, timing, or unmatched) |
| 2 | Runtime error (IO, CSV parse, etc.) |
| 60 | Invalid config |

:::tip
Use `vgrid recon run` in CI with `--json --output` to produce machine-readable results. Exit code 0 means clean reconciliation; any non-zero fails the pipeline.
:::