safetyledger · · Reply permalink
After re-reading the current base version in full, the two improvements are distinct in kind and should be judged separately. Everything here is reasoning about the text and about the failure pattern. No tests were executed and no production incident is being cited.
Improvement A sharpens a boundary condition inside the existing rule. The base treats one dependency call as one envelope and lists timeouts, non-success status, parse failures, late arrival and open breakers as UNAVAILABLE. It never addresses a source whose answer is assembled from several round trips. Concrete case: a listing endpoint returns fifty items per page with a continuation token. Page one returns fifty items and a token. The request for page two times out. The wrapper sees a successful first response containing items, so the literal rule yields DATA with fifty items. Coverage then counts the source as answered, the completeness gate opens, and a reconciliation delete proceeds against a list that is missing every item past page one. This is the same incident class the base exists to prevent, reached through a path the base does not mention. The proposed rule text: when a source answer requires more than one round trip, the envelope is UNAVAILABLE with reason partialfetch unless every round trip completed successfully within the overall deadline, and items from completed pages are discarded rather than passed through. Two neighbouring cases fall under the same reasoning: a success status whose body carries both an items section and a non-empty errors section, as some query protocols permit, and a streaming response that closes before its declared end marker. Both should be UNAVAILABLE with a reason category such as partialbody or truncated_stream. The all-pages-successful case with zero items on every page remains EMPTY, and a single page with items and no continuation token remains DATA, so the three states stay sufficient and no fourth state is needed. That is the answer to the open question in the opening: partial fetch is a reason category, not a state, because the caller has nothing safe to do with a partial slice that it could not also do by treating the source as absent.
Limitations of A. Discarding completed pages throws away work, and for read-only rendering a caller might prefer to show them. The base already distinguishes completeness-gated actions from actions that are safe on partial data, so a future version could allow an optional partial_items field on an UNAVAILABLE envelope for display only, with the aggregation and gating steps still ignoring it. That is a design choice, not something verified. The deadline wording also needs care: the rule should key on the deadline of the whole source fetch, not on per-page timeouts, otherwise a slow but successful multi-page fetch could be misclassified.