Output and schemas

Formats

Format	Memory characteristic	Use for
`json`	Buffers the full result before writing.	Smaller files, integrations that want one complete document.
`json-stream`	Encodes events as they’re processed. May be invalid JSON if the process is interrupted.	Lower memory pressure while still wanting JSON-like structure.
`ndjson`	One tagged event per line. O(1) for result writing, crash-safe for already-written lines.	Large files, streaming pipelines, scheduled jobs.
`csv`	Fixed-schema, flat.	Spreadsheet inspection, downstream tabular processing.
`table`	Buffers rows for display.	Interactive human inspection only.

--audit is supported for json, json-stream, and ndjson, not csv or table. --deterministic only affects buffered json output. For rights multi-counterpart runs, json, json-stream, and ndjson include a per-counterpart breakdown; csv and table include only the aggregate result.

The NDJSON envelope

Every NDJSON line carries the same envelope shape:

{"schema": "reconify.engine.result.v1", "type": "match", "data": {}}

Field	Description
`schema`	Always `reconify.engine.result.v1` for reconcile output.
`type`	The event name. See the list below.
`data`	The event payload.

Event names are stable and are not renamed: run_info, index_selection, match, amount_diff, timing_diff, unmatched_left, unmatched_right, duplicate, grouped_match, grouped_amount_diff, grouped_timing_diff, many_to_many_match, many_to_many_amount_diff, many_to_many_timing_diff, ambiguous_group, source_summary, summary.

The result document

json and json-stream output share this top-level shape:

{
  "schema": "reconify.engine.result.v1",
  "pair": "left_source_vs_right_source",
  "left_source": "left_source",
  "right_source": "right_source",
  "summary": {
    "currency": "NGN",
    "total_left": 842,
    "total_right": 851,
    "matched": 810,
    "unmatched_left": 12,
    "unmatched_right": 18,
    "amount_diff_count": 6,
    "timing_diff_count": 4,
    "duplicate_count": 2,
    "match_rate_pct": 96.2,
    "reconciled_rate_pct": 97.6,
    "matched_amount_left": 184230000,
    "matched_amount_right": 184230000,
    "unmatched_amount_left": 1500000,
    "unmatched_amount_right": 2200000,
    "amount_diff_total": 340000,
    "total_discrepancy": 4040000
  },
  "matched": [],
  "unmatched_left": [],
  "unmatched_right": [],
  "amount_diff": [],
  "timing_diff": [],
  "duplicates": [],
  "grouped_matched": [],
  "grouped_amount_diff": [],
  "grouped_timing_diff": [],
  "many_to_many_matched": [],
  "many_to_many_amount_diff": [],
  "many_to_many_timing_diff": [],
  "ambiguous_groups": [],
  "warnings": []
}

184230000 is 1,842,300.00: every monetary field is minor units.

Field	Description
`schema`	Always `reconify.engine.result.v1`.
`run_info`	Present only under `--audit` or `--auto`. See `run_info` below.
`index_selection`	Present when the run recorded which index backend was chosen and why.
`pair`, `left_source`, `right_source`	The pair and source names from the config.
`summary`	Aggregate counts and totals. See The summary object.
`matched`	One-to-one matches: same reference, amount within tolerance, date within window.
`unmatched_left` / `unmatched_right`	Rows present on one side with no counterpart on the other.
`amount_diff`	Same reference, date fine, amounts disagree beyond tolerance.
`timing_diff`	Same reference, amounts agree, dates outside the window.
`duplicates`	Rows in the same source sharing a group key, annotated for visibility. Every row still participates in matching; a duplicate group can include a row that matched normally.
`grouped_matched`, `grouped_amount_diff`, `grouped_timing_diff`	Populated only by an `one_to_many` pass.
`many_to_many_matched`, `many_to_many_amount_diff`, `many_to_many_timing_diff`	Populated only by a `many_to_many` pass.
`ambiguous_groups`	Groups where grouping was undetermined; excluded from matching and requiring manual resolution.
`warnings`	Non-fatal observations, such as empty-currency rows mixed with a non-empty base currency.
`by_source`	Populated only for `rights` multi-counterpart runs. See Per-counterpart summaries.

The summary object

{
  "currency": "NGN",
  "total_left": 842,
  "total_right": 851,
  "matched": 810,
  "unmatched_left": 12,
  "unmatched_right": 18,
  "amount_diff_count": 6,
  "timing_diff_count": 4,
  "duplicate_count": 2,
  "match_rate_pct": 96.2,
  "reconciled_rate_pct": 97.6,
  "matched_amount_left": 184230000,
  "matched_amount_right": 184230000,
  "unmatched_amount_left": 1500000,
  "unmatched_amount_right": 2200000,
  "amount_diff_total": 340000,
  "total_discrepancy": 4040000
}

result_mode and run_id are omitted from this object entirely unless they apply: result_mode only appears when a run sets it explicitly (per pair, or with --result-mode), and run_id only when telemetry is active. Similarly, grouped_matched, grouped_amount_diff, grouped_timing_diff, many_to_many_matched, many_to_many_amount_diff, many_to_many_timing_diff, ambiguous_group_count, ambiguous_amount_left, and ambiguous_amount_right only appear when the pair configures the matching passes that produce them.

Field	Description
`result_mode`	Present only when set. The emission mode applied: `all`, `exceptions_only`, or `summary_only`.
`currency`	The base currency for monetary totals. Empty when no transaction carried a currency.
`run_id`	Present only when telemetry is active. The telemetry run identifier.
`total_left`, `total_right`	Row counts parsed from each source.
`matched`, `unmatched_left`, `unmatched_right`, `amount_diff_count`, `timing_diff_count`, `duplicate_count`	Outcome counts. `duplicate_count` counts transactions across all duplicate groups, not the number of groups.
`match_rate_pct`	Percentage of exact one-to-one reference matches only, of `max(total_left, total_right)`.
`reconciled_rate_pct`	Percentage including amount diffs, timing diffs, and grouped outcomes: every case where the two sides were reconciled to each other, just not perfectly. Also of `max(total_left, total_right)`. A `one_to_many` pass inflates `total_right`, so a fully reconciled grouped dataset can legitimately report a sub-100% `reconciled_rate_pct`.
`grouped_matched`, `grouped_amount_diff`, `grouped_timing_diff`	Present only with a `one_to_many` pass configured. Counts from that pass.
`many_to_many_matched`, `many_to_many_amount_diff`, `many_to_many_timing_diff`	Present only with a `many_to_many` pass configured. Counts from that pass.
`ambiguous_group_count`	Present only when relevant. Groups excluded from matching because grouping was undetermined.
`matched_amount_left`, `matched_amount_right`	Minor-unit totals of matched rows on each side.
`unmatched_amount_left`, `unmatched_amount_right`	Minor-unit totals of unmatched rows on each side.
`amount_diff_total`	Minor-unit sum of amount differences.
`ambiguous_amount_left`, `ambiguous_amount_right`	Present only when relevant. Minor-unit totals from ambiguous groups.
`total_discrepancy`	`unmatched_amount_left + unmatched_amount_right + amount_diff_total + ambiguous_amount_left + ambiguous_amount_right` (the last two are `0` when absent). Zero with the expected `matched` count means a clean run; non-zero is exactly the money still unexplained.

All monetary fields are minor units, and are always computed from the full reconciliation, even when result_mode suppresses item events.

`run_info`

Present when --audit is set, or when reconcile --auto is used:

{
  "run_id": "01HZXQ",
  "timestamp": "2026-01-15T09:32:00Z",
  "tool_version": "0.4.0",
  "left_file": {
    "path": "path/to/left-file.csv",
    "sha256": "e3b0c4...",
    "size_bytes": 184320,
    "mod_time": "2026-01-14T22:00:00Z"
  },
  "right_file": {
    "path": "path/to/right-file.csv",
    "sha256": "9f86d0...",
    "size_bytes": 92160,
    "mod_time": "2026-01-14T21:45:00Z"
  },
  "pair_config": {
    "date_window": "1d",
    "amount_tolerance_minor": 0,
    "name_mode": "none"
  },
  "inferred_config": null,
  "inference_confidence": null
}

Field	Description
`run_id`, `timestamp`, `tool_version`	Run identifier, RFC3339 timestamp, and the binary version that produced the result.
`left_file`, `right_file`	`path`, `sha256`, `size_bytes`, `mod_time` for each input file.
`pair_config`	Snapshot of the applied `date_window`, `amount_tolerance_minor`, and `name_mode`.
`inferred_config`	Populated only for `--auto` runs: the exact YAML config used, so the run is reproducible non-auto.
`inference_confidence`	Populated only for `--auto` runs: each selected mapping’s column, confidence, and confidence lead.

Per-counterpart summaries

json and json-stream include a per-counterpart by_source object alongside the aggregate summary for rights runs:

{
  "pair": "ledger_vs_settlements",
  "summary": {
    "total_left": 1200,
    "matched": 1180,
    "reconciled_rate_pct": 98.33
  },
  "by_source": {
    "right_source": {
      "total_left": 1200,
      "total_right": 900,
      "matched": 890,
      "unmatched_left": 310,
      "unmatched_right": 10,
      "reconciled_rate_pct": 74.17
    },
    "paypal_settlements": {
      "total_left": 310,
      "total_right": 298,
      "matched": 290,
      "unmatched_left": 20,
      "unmatched_right": 8,
      "reconciled_rate_pct": 93.55
    }
  }
}

ndjson emits the same breakdown as one source_summary line per counterpart, followed by the aggregate summary line:

{"type":"source_summary","data":{"source":"right_source","summary":{"total_left":1200,"total_right":900,"matched":890,"reconciled_rate_pct":74.17}}}
{"type":"summary","data":{"total_left":1200,"matched":1180,"reconciled_rate_pct":98.33}}

csv and table omit the per-counterpart breakdown and include only the aggregate result.

`result_mode`

Value	Emits
`all`	Every event, including clean matches. Default.
`exceptions_only`	Unmatched rows, amount/timing diffs, duplicates, ambiguous groups, and grouped/N:M exception events. Clean matches are suppressed.
`summary_only`	Only the final summary. All item events are suppressed.

Set result_mode per pair in reconify.yaml, or override at runtime with --result-mode; the flag wins. Filtering happens at the writer boundary: classification counts, monetary totals, and currency are always computed from the full reconciliation. Suppressing events never changes the numbers.

Schema identifiers

Identifier	Emitted by
`reconify.engine.result.v1`	`reconcile` (JSON/json-stream top level, and every NDJSON envelope)
`reconify.engine.diagnostic.v1`	Any command, on error, when `--error-format json` or `--agent`
`reconify.engine.capabilities.v1`	`capabilities`
`reconify.engine.profile.v1`	`inspect`
`reconify.engine.config-proposal.v1`	`config infer`
`reconify.engine.explanation.v1`	`explain`

reconify schema <name> prints the published Draft 2020-12 document for each identifier (for example, reconify schema result). Versioning rule: new fields under a vN identifier are additive and safe for a consumer to ignore; a breaking change creates a new v2 identifier rather than reusing v1 for an incompatible shape.

Diagnostics

When --error-format json or --agent is set, a failed command emits this envelope to stderr:

{
  "error": "amount column not found",
  "code": "config_error",
  "ok": false,
  "schema": "reconify.engine.diagnostic.v1",
  "diagnostic": {
    "code": "AMOUNT_COLUMN_NOT_FOUND",
    "category": "config",
    "message": "amount column \"Amount\" not found in path/to/left-file.csv",
    "details": { "column": "Amount", "source": "left_source" },
    "suggestions": ["Run `reconify inspect path/to/left-file.csv` to see the actual column names."]
  }
}

The legacy error and code fields remain present and unchanged in meaning, for callers that only understand the original contract. diagnostic.code can be more granular. suggestions exists specifically so an agent has a next action instead of a dead end.

Exit codes

Code	Meaning
`0`	Success.
`1`	Unexpected or internal error.
`2`	Config or validation error.
`3`	Reconcile completed with unmatched rows (`--fail-if-unmatched` only).
`4`	Reconcile completed with exception events (`--fail-if-exceptions`; takes precedence over `3`).

3 and 4 are not failures: the run completed and found unmatched rows or exceptions. They only fire when you’ve opted in with --fail-if-unmatched or --fail-if-exceptions.

Start here

Concepts

Guides

Reference

Help

Formats

The NDJSON envelope

The result document

The summary object

`run_info`

Per-counterpart summaries

`result_mode`

Schema identifiers

Diagnostics

Exit codes

​Formats

​The NDJSON envelope

​The result document

​The summary object

​run_info

​Per-counterpart summaries

​result_mode

​Schema identifiers

​Diagnostics

​Exit codes

Formats

The NDJSON envelope

The result document

The summary object

`run_info`

Per-counterpart summaries

`result_mode`

Schema identifiers

Diagnostics

Exit codes