ADR-0068: The Reconciliation gaps read says why the list is empty

Status: Accepted Date: 2026-09-20

Decisions

D-144 The gaps read carries whether the document holds any Restriction and whether any span has been selected from it, so an empty list says which of its three causes it has

The read answers with more than { sdsId, gaps[] }. It reports the two facts that tell the three causes apart, and the reconcile page states the case the curator is actually in. The page composes no claim the payload does not carry.

Context

An empty gaps array has three causes and the payload cannot tell them apart:

1. every (Restriction, selected span) pair has been judged;
2. the document holds no Restriction at all;
3. nothing has been selected from the document yet.

Ticket 38 defined a gap pairwise and made the gate agree with the query, so the list itself is correct in all three cases. What was never decided is what a page may say when it is empty.

The reconcile page asserted the first cause until 2026-09-20. A curator who had selected nothing was told that every pair had been judged, by a named curator — a sentence about human judgement (D-49) that no human had made, on the surface that exists to collect exactly that judgement. It now names all three causes and asserts none, which is honest and is worse to read: a curator finishing a document and a curator who has not started are shown the same paragraph.

Both states are wrong in the same way. The page was deciding something out of a payload that does not determine it — first by guessing, then by refusing to guess. The fix is not a better sentence; it is a payload that determines the answer. This is the curator-side form of the rule the snapshot seam already states: the server decides every per-field value and the client derives nothing from it (D-124).

Widening the read is what makes the strong sentence true rather than merely confident.

Decision

The Reconciliation gaps read reports whether the document holds any Restriction and whether any span has been selected from it, alongside the gaps themselves. The reconcile page states the case those facts determine, and states nothing they do not.

Rejected options

• Keeping the three-possibility sentence — rejected. It is honest and it is free, and it leaves the curator to work out which case they are in from knowledge the server already has. A safety write surface should not make its curator infer what it could state.
• Having the page infer the case from other reads it already makes — rejected because that is a claim composed on the client out of two payloads, which is the defect this ADR exists to remove, not a cheaper way to fix it. Two reads can also disagree, and the moment they do the page asserts something no single server answer ever said.
• Asserting the judged case as before, and accepting the false sentence as rare — rejected because it is not rare: it is what every curator sees on every document before their first selection, which is the first thing any of them will ever see.

This ruling may not be re-decided

If a change contradicts this ADR: stop and raise it. Do not implement over it.

Specifically: do not return the page to asserting one cause, do not compose the case on the client from two reads, and do not word an empty list as a statement about judgement unless the payload says judgement is what happened.

Consequences

What becomes true. A curator opening a document they have not started reads that they have not started. A curator who has judged every pair reads that, and it is true when they read it. The reconcile page states only what one server answer determined.

What this costs — stated, not discovered. One more query on a read that already runs per document, and a payload shape both repositories have to agree on. The seam is gated the way the others are, so the cost is a fixture to keep committed as well as a query to run.

What is closed off. A page-composed answer to which case an empty list is, and any wording of the empty state that outruns the payload.

Coverage

Upstream	Landed in	Evidence	Note
D-44	D-144	the gaps this read reports are the unresolved pairs the reconciliation rule requires to be judged, which is what makes the empty case worth naming precisely	ADR-0022; ticket 38 made the query and the gate agree on the pairwise definition
D-49	D-144	the false sentence asserted a named curator's judgement where none existed, which is the claim D-49 makes load-bearing	ADR-0022
D-124	D-144	the server decides every per-field value and the client derives nothing from it; this is that rule applied to the curator-side read	ADR-0053; the same cross-repository seam instrument gates the widened payload
D-110	D-144	the read is loopback-only curation surface, so widening it reaches no device and no Handler	ADR-0048