# Balance Proof — exact wire and outcome freeze

Date: 2026-10-25. Root ratified the control schema direction and aggregate precedence before implementation. This file supplies the exact owner-selected fields under BALANCE-PROOF-DEFINITION-CONTRACT.md. All objects reject missing and unknown fields; no caller input is coerced. The existing Exact Reference Match core remains unchanged and is pinned locally for common selection regression.

## Public API and common source semantics

Python `balance_proof(query, internal_groups, external_groups, context)`; TypeScript `balanceProof` with the same four arguments.

Query exact keys: `schema_version, ledger_id, entity_id, reconciliation_account_id, period_start, period_end, knowledge_cutoff, reference_policy, currency, basis`.

Version is `d30-balance-proof-v1`. The first eight common fields follow the frozen reconciliation contract, with the developer-pinned expected schema version above. Currency is USD or EUR. Basis is exactly `booked-cash-asset-utc-v1`. Any other balance basis routes `UNSUPPORTED_BALANCE_BASIS`; no available/value-date control is silently relabeled. Same 1–366-day UTC [start,end) booking window, K at or after end midnight, positive 30-digit movement strings, canonical complete observer logs, whole-group receipts, external revision chains and reversal signs.

Context exact keys: `internal_head, external_head, internal_controls, external_controls, reconciling_items`. Source heads are the unchanged shared head schema. No synthetic opposing trusted head may be invented to obtain a complete side.

Both source histories are independently validated after common strict query/head validation. Structural/conflicting invalid input rejects globally before any arithmetic. A complete side can retain its evidence and numeric bridge diagnostics when the opposite side is incomplete; this is explicitly a partial diagnostic, never a clean proof or partial matching proposal.

The original all-or-none `select_reconciliation_rows` / `selectReconciliationRows` public helper stays unchanged in a pinned local module. Its complete outputs are regression-tested against all 105 shared independent cases. The proof extension may call its validated per-side selector after strict common query/head checks; other topic copies are untouched.

## Independent control bundles

Each side controls object has exactly `opening, closing`. Each role bundle has exactly `head, versions`.

Control head exact keys:

`schema_version, control_id, source_id, side, ledger_id, entity_id, reconciliation_account_id, role, currency, basis, boundary_at, head_revision, observed_at, receipt_ref`.

- Version `d30-balance-control-head-v1`.
- Identifiers use shared ASCII grammar. source_id, side and scope equal the corresponding movement head; control observations remain independently supplied.
- role is opening or closing and matches its position. Opening and closing control IDs differ within a source. IDs are namespaced by source; they need not be globally distinct across different sources.
- Currency and basis equal the query.
- boundary_at is exact query start midnight for opening and exact exclusive-end midnight for closing.
- head_revision is a canonical nonnegative decimal string with numeric value 0..512.
- observed_at is genuine strict Gregorian UTC milliseconds. It must be at or after boundary_at and cover K. K beyond this independent observation is indeterminate `KNOWLEDGE_BEYOND_CONTROL`.
- receipt_ref identifies trusted independent extraction/coverage evidence; its presence is not authentication.

Control version exact keys:

`schema_version, control_id, revision, supersedes_revision, available_at, source_version_ref, action, amount_minor`.

- Version `d30-balance-control-v1`. control_id equals its head.
- revision canonical positive decimal string 1..512; predecessor null at 1, otherwise exact prior version.
- available_at genuine UTC milliseconds, at or after the role boundary and no later than head.observed_at. Receipts are nondecreasing along the chain.
- action upsert or withdraw. Upsert amount is canonical signed integer string, zero allowed, at most 120 magnitude digits: `0` or an optional minus followed by nonzero leading digit. No plus, -0, leading zero, Number, exponent, bool or decimal. Negative bank-asset balances are valid.
- Withdraw amount is null. First version must be upsert. Withdraw requires a currently active upsert; later upsert reinstatement continues the chain. Consecutive withdrawals reject.
- source_version_ref strict identifier preserves original control-document/extract provenance.

Both internal and external control evidence can be revised. This changes the observed control history, not accepted immutable financial movements. Complete chains through independent head_revision are validated before K selection. At most 512 supplied versions per role. Exact duplicates reject `DUPLICATE_CONTROL_VERSION`; changed payload with the same control/version identity rejects `CONTROL_VERSION_CONFLICT`, with changed conflict winning globally over identical copies. Arrays may be arbitrarily delivered and are canonicalized by declared numeric revision after checks.

Missing revision positions or short coverage relative to head yield indeterminate `INCOMPLETE_CONTROL_HISTORY`. An impossible predecessor/action/clock/schema/scope is rejected. A version beyond declared head rejects `CONTROL_HEAD_MISMATCH`. A zero head and no versions is valid evidence of no control and yields `CONTROL_MISSING`.

Include versions with receipt ≤ K and choose the latest. No visible version yields `CONTROL_NOT_AVAILABLE`. A latest visible withdrawal yields `CONTROL_WITHDRAWN` and does not revive an older amount. Future version IDs/content never appear in selected controls. Trusted head metadata may declare the validated revision count without leaking future version payloads.

## Investigated reconciling-item register

Context reconciling_items is a list of at most 512 objects with exact keys:

`item_id, side, row_ref, reason, available_at`.

- item_id strict identifier, unique within this request.
- side internal or external; row_ref has the exact shared five fields `source_id,row_id,revision,sequence,source_version_ref`.
- reason is 1..240 Unicode scalars, no lone surrogates/C0/DEL/C1, with at least one non-whitespace scalar. Whitespace classification is the explicitly pinned Python strip set; retain original valid reason bytes.
- available_at genuine UTC milliseconds; it must cover the selected row's receipt and be ≤ K.
- Authority/investigation validity is a trusted host precondition; no matching score or JSON receipt proves authority.
- Derive signed amount only from the complete current selected in-window chosen-currency movement. No free amount, journal or residual field is accepted.
- Unknown, stale, withdrawn or out-of-window row reference: indeterminate `STALE_RECONCILING_EVIDENCE`. Wrong chosen currency: indeterminate `RECONCILING_CURRENCY_MISMATCH`. Future item: indeterminate `RECONCILING_ITEM_NOT_AVAILABLE`. A receipt earlier than its row's available_at rejects `ITEM_CLOCK_ORDER_VIOLATION`.
- Same row referenced by two items rejects `RECONCILING_ROW_REUSED`. Exact duplicate item IDs reject `DUPLICATE_RECONCILING_ITEM`; changed same-ID payload rejects `RECONCILING_ITEM_CONFLICT` before exact duplicates.

Every registered item is unresolved in this tutorial. It explains a difference without clearing it or granting posting permission. Prior durable acceptance/reuse control is a downstream host obligation.

## Output schema

Top-level exact keys:

`status, code, source_evidence, control_evidence, bridges, comparison, reconciling_items`.

Status is pass, fail, indeterminate or rejected. A structurally rejected input returns its typed code, null for source_evidence/control_evidence/bridges/comparison and [] for reconciling_items. No numeric proof is computed before all structural validation completes.

source_evidence exact internal/external objects, each:

`status, code, coverage, selected`.

A complete side has status ok/code SOURCE_SELECTED. coverage is the unchanged shared per-side coverage object. selected exact `active, withdrawn, out_of_window_count`; active and withdrawn retain unchanged shared row objects. An incomplete side has indeterminate/typed code and null coverage/selected. Complete source diagnostics on the other side remain explicitly separate.

control_evidence exact internal/external, each exact opening/closing selection objects:

`status, code, coverage, selected`.

Complete validated history coverage exact `control_id,source_id,receipt_ref,observed_at,head_revision,validated_through_revision,visible_through_revision`. Upsert selected is a full copied control-version object, status ok/code CONTROL_SELECTED. Missing/unavailable/withdrawn is indeterminate with the typed code above; withdrawn retains its latest visible version as diagnostic. Incomplete history/observation has null coverage/selected. Never leak future control-version payloads.

bridges exact internal/external, each exact:

`status, code, currency, opening_control_ref, closing_control_ref, opening_minor, inflow_minor, outflow_minor, net_movement_minor, expected_closing_minor, reported_closing_minor, residual_minor, excluded_currency_count, trace`.

Control reference exact `source_id,control_id,revision,source_version_ref`. A bridge is numeric only when its own source and both role controls are complete and selected upserts. Then:

- inflow_minor and outflow_minor are unsigned exact sums in chosen currency.
- net_movement_minor = inflow − outflow.
- expected_closing_minor = opening + net movement.
- residual_minor = reported closing − expected closing.
- status pass/code BRIDGE_PASS iff residual zero; otherwise fail/BRIDGE_RESIDUAL.
- excluded_currency_count canonical string counts active selected rows in other supported currency, never their amounts.
- trace is in selected-version observer-sequence order, explicitly an audit order rather than an intraday balance history. Each entry exact `row_ref,group_id,available_at,booking_date,direction,is_reversal,amount_minor,signed_amount_minor,running_balance_minor`.

An indeterminate bridge has code SIDE_EVIDENCE_INDETERMINATE, known query currency, null control references/numeric/count fields and empty trace. Individually selected control evidence remains available separately. Derived totals may exceed input magnitude limits; use arbitrary-precision integers and canonical string output, without a zero floor.

comparison exact:

`status, code, opening_difference_minor, closing_difference_minor, internal_item_signed_minor, external_item_signed_minor, adjusted_internal_closing_minor, adjusted_closing_residual_minor, unresolved_item_count`.

Raw differences are internal minus external, computed when the corresponding two selected controls are available, independently of whether a bridge is known. Missing values are null, never zero. If every item can be validated and both closing controls are available:

adjusted_internal_closing = internal_closing + external_item_signed − internal_item_signed.

Adjusted residual = adjusted_internal_closing − external_closing. An unknown/stale item makes both item sums and adjusted values null; no partial item sum is presented. With no items, both item sums are zero once source selection is sufficient to validate the empty register; closing controls alone do not establish source completeness.

Item diagnostic exact `item_id,side,row_ref,reason,available_at,status,code,signed_amount_minor`. A valid unresolved item has ok/RECONCILING_ITEM_RETAINED and derived signed amount. Indeterminate items retain typed code and null amount.

Comparison status/code: nonzero known raw opening difference => fail/OPENING_BALANCES_DIFFER; otherwise nonzero known adjusted closing residual => fail/CLOSING_BALANCES_DIFFER; otherwise missing required evidence => indeterminate/COMPARISON_INDETERMINATE; otherwise nonempty register => indeterminate/RECONCILING_ITEMS_REMAIN; otherwise pass/CONTROLS_AGREE.

## Aggregate precedence

1. Any structural/schema/scope/conflict defect => rejected, no arithmetic.
2. Any independently known side bridge residual ≠ 0 => fail/SIDE_BRIDGE_FAILED.
3. Known raw opening difference ≠ 0 => fail/OPENING_BALANCES_DIFFER.
4. Known adjusted closing residual ≠ 0 => fail/CLOSING_BALANCES_DIFFER.
5. Any remaining missing source/control/item evidence => indeterminate/EVIDENCE_INDETERMINATE.
6. Any valid unresolved reconciling item => indeterminate/RECONCILING_ITEMS_REMAIN.
7. Otherwise both bridges and comparisons pass => pass/BALANCE_PROOF_PASS.

This retains known numeric failure even when the opposite side is indeterminate. A nonzero current-period item never conceals an opening discrepancy. Clean pass means arithmetic consistency under the supplied independently trusted scope/controls; not economic truth, final settlement, source authentication or detection of all omitted real-world transactions.

## Independent canonical arithmetic

At corrected K = 22 October 09:00: internal net 4300, external net 5000; independent openings 10000 each and independent closings 14300/15000. Both bridges pass. No item gives raw and adjusted closing difference −700: overall fail. Internal-only I-MISSING outflow 700 gives internal item signed −700, adjusted internal closing 14300−(−700)=15000, adjusted residual 0, but unresolved item => indeterminate.

Before correction K, external net is 4400 and its earlier closing control is 14400. Latest visible external closing is selected at the same K; no future 15000 control leaks. Internal close remains 14300, raw difference −100. Do not carry a newly revised movement with a stale control as if both were current at one receipt.

Other independent fixtures must cover clean/equal-net distinct histories, each wrong control, missing future history, duplicate/conflicting versions, complete future control chains, absent/withdrawn controls, period/basis/currency/scope mismatches, exact receipt equality, true reversal, negative asset balances, 120-digit controls, stale/reused items, source-gap versus known opposite bridge failure, and immutable output/permutation invariance.