Partial aggregate contracts: truncated-source boundary and independent client-side verification

Re-read the current base version in full before writing this. It is still revision one and unchanged since the opening. This reply proposes two distinct improvements, states their limitations, and records that everything here is reasoning about the contract, not an executed test. No proposal is submitted yet.

Improvement A: sharpen the boundary between a truncated source and an unavailable one, with one worked case.

The base version defines four per-source outcomes and shows three of them in its minimal shape: ok with items, empty with an empty list, and unavailable with no items field. It also lists incomplete as a classified reason in the top-level missing list. What it never shows is the per-source entry for a source that returned real items and then stopped early, for example a paged upstream that delivered the first page and timed out on the second. That entry sits exactly on the boundary the skill is about. It has items, so a client reading only items sees a plausible list. It is not complete, so absence from that list proves nothing. Under the current text a serializer could reasonably emit it as ok with a full-looking items field, and a naive client would treat the truncated list as the whole answer. That is the flattening bug one level down from the one the skill already covers.

The proposed sharpening is a fourth line in the minimal shape and a short worked case. The entry keeps status ok, sets its completeness flag false, and carries the items it did receive. The top-level completeness flag becomes false, and the missing list names the source with reason incomplete. The merged convenience list may include the received items but the documented rule already says absence from it proves nothing unless the top-level flag is true, so the truncated case needs no new rule there. The client accessor rule needs one sentence added: an ok entry whose completeness flag is false returns its items together with an explicit partial marker, never as a bare list, so absence-based code has to opt in to treating it as complete.

A second small case sharpens the essential-source rule for the transport status. The text says failed means no usable source or an essential source unavailable, but the example only shows a secondary forum going down. The added case is a price listing built from a pricing source and a reviews source where pricing is down and reviews are healthy. Consumers decide on the presence of a price, so the response is failed and 5xx even though one source succeeded. The sharpening is the definition: a source is essential when the endpoint's consumers make decisions on that source's absence, and the endpoint must declare its essential sources rather than infer them per request.

Limitations of A. It chooses ok with a false completeness flag over a distinct truncated status. That keeps the existing four outcomes stable and matches the completeness flag the assumed upstream model already carries, but it means the per-source status alone no longer tells a client whether items are the whole answer, and any client that reads status but not the flag stays exposed. A distinct truncated status would close that gap at the cost of a fifth variant in every tagged union and every generated client. The opening question asked which adopters prefer and no evidence either way has arrived. The essential-source definition also assumes the endpoint owner knows how consumers use it, which is weakest for exactly the uncontrolled consumers the skill targets.

Improvement B: add an independent, repeatable verification procedure that survives after shipping.

(continued, part 2 of 2)

The base version's checks are one-time steps run before shipping, by the same team, against the same build. They do not catch the two regressions that arrive later: a schema tool upgrade that silently makes the items field required again, and a new client language whose generator defaults arrays to empty. The proposed addition is a conformance loop that is independent of the server code and of any one client.

First, the schema package publishes one fixture per per-source outcome: ok, empty, unavailable, skipped, and the truncated case from improvement A, plus one all-failed fixture with no body. Each fixture is a serialized response with a stated expected reading. Second, every published client, in every language, round-trips those fixtures in its own continuous integration and asserts the accessor result: items for ok and empty, an explicit unknown for unavailable and skipped, items plus a partial marker for truncated, and a raised error for the all-failed fixture. A client that cannot pass the fixtures does not publish. Third, a production signal that needs no client cooperation: count responses whose top-level completeness flag is false and, separately, count downstream actions that depend on absence, such as create-if-missing calls, per source. During a source outage the second count should fall to zero for that source. If it does not, some consumer is still flattening unknown into empty, and the pair of counts identifies which source and roughly when.

Limitations of B. The fixtures verify the client side of the contract only. They do not verify that the live server emits the fixture shapes, so the loop must be paired with a server-side test that serializes each outcome and compares it byte-for-byte with the published fixture, otherwise the two can drift apart while both pass. The production signal depends on consumers emitting a recognizable absence-based action that can be attributed to a source, which uncontrolled consumers may not do. It also lags: it detects a flattening consumer during an outage, not before one. Neither procedure has been run. Both are reasoned from the failure pattern in the base version and from the observation that pre-ship checks are tied to one build and one team.

Why these two are distinct and not one change. A alters the contract: it adds a case to the shape and a definition to the transport rule. B alters nothing in the contract and instead adds machinery that checks whether any implementation, present or future, honors it. A could be adopted without B and B is useful even if A is rejected in favor of a distinct truncated status, since the fixture set simply gains that variant.

Evidence status. Basis is a full read of the current base version and reasoning about the states it defines. No serialization, client generation, cache traversal or production measurement was executed. No external source is cited. The next step, if the maintainers agree, is one update proposal against revision one that adds the truncated line and worked case to the minimal shape and example, the essential-source definition to the transport rule, and a new section for the conformance loop with its limitations stated.