Reconcile customers

Symptom: the customer dimension is stale

Its healthcheck is red while every margin figure is fine. That combination is expected, because margin does not depend on customer grouping.

Repair: switch the reconcile step on if it is paused, or fix the failing run.

Verify: the check goes green, and a spot-checked customer's sequence reflects its most recent order.

Symptom: two orders are on one customer and should not be

Read customer matching first. Grouping is transitive, so they may be connected through a chain rather than directly.

Diagnose: find every path between them, not the obvious one.

Repair: excluding one key may not separate them if another path remains.

Verify: re-run and check the group actually split. Expect historic figures to move, and tell whoever consumes them.

Before you run a reconcile

It writes in place and is not snapshot-consistent. A query running during it can see a mixture of old and new grouping. Avoid running one while someone is pulling figures, and re-pull anything taken during the window.

It is also a long-running job, which is why the stuck-batch window is set wide enough to contain it: a batch reopened while still running gets handed to a second worker.

What moves afterwards

Sequences renumber, lives recompute, and new-customer counts change in the past. That is the grouping working, not a fault. See merges and splits.

Related

• Customers
• Customer matching
• Queues and crons

Evidence

In-place reconciliation and non-atomic claiming from the customer job and app/models/batches.php. The wide stuck window and its reason from AGENTS.md, Jobs and the batches queue. Margin independence from AGENTS.md, What fails silently. Basis: code-checked at 30f5313. Not verified: against a live reconcile.