Why must a subgraph's _entities resolver return its results in the input order?

## The contract, and why it has to be positional The reserved field is declared roughly like this: ```graphql type Query { _entities(representations: [_Any!]!): [_Entity]! } ``` Note the two nullability positions. The **list** is non-null: a subgraph must always return a list. The **elements** are nullable: any individual slot may be null. Now ask how the router pairs a returned object with the representation that asked for it. It cannot read a key out of the result, because the outbound query only selected the fields the plan needs: ```graphql query($representations: [_Any!]!) { _entities(representations: $representations) { ... on Trial { enrollmentTarget primaryOutcome } } } ``` There is no `nctId` in that selection, and there is no requirement that there ever be one. The response is a bare list of objects. The only correspondence available is *index n of the result answers index n of the input*, and that is exactly what the federation specification requires: the returned list must have the same length as `representations` and be in the same order. ## How the alignment gets broken Almost always through the data store, because the natural implementation reads like this: ```pseudocode resolve Query._entities(representations): ids = representations.map(r -> r["nctId"]) return trialStore.findAllByNctId(ids) # WRONG ``` Two independent things go wrong with that line. **Order.** `SELECT ... WHERE nct_id IN (...)` returns rows in whatever order the planner chose — index order, insertion order, whatever the join produced — not the order of the `IN` list. A cache or a search index has even less obligation. **Length.** Rows that do not exist do not come back. A batch of 23 representations where the trial at index 14 was withdrawn from the registry returns 22 rows. Every entity from index 14 onward now answers the wrong representation, and index 22 has no answer at all — some servers then pad, others return a short list the router rejects. The symptom is the ugly kind: no exception, no error entry, HTTP 200, a well-formed response, and `NCT-05128` showing another trial's enrolment target. It survives code review, it survives a unit test written against a two-element batch where both rows exist, and it appears in production only when the batch contains a miss — which is to say, at the worst possible moment. ## The shape that is correct by construction Drive the output from the *input list*, never from the store's result: ```pseudocode resolve Query._entities(representations): ids = representations.filter(r -> r["__typename"] == "Trial") .map(r -> r["nctId"]) byId = trialStore.findAllByNctId(ids).indexBy(t -> t.nctId) return representations.map(r -> r["__typename"] == "Trial" ? byId[r["nctId"]] : null) ``` This is the same discipline a batching loader demands of its batch function — the list you return is a rewrite of the list you were given, not a repackaging of what came back from storage. Two further habits keep it honest: never deduplicate the output (the router may legitimately send the same key twice, and it expects an answer at both indexes), and never sort for tidiness. ## What a null slot means, and what an exception means A null at index n says: *this subgraph cannot resolve that reference*. It is the specified way to report an unresolvable representation — the trial was withdrawn, the id is from a stale cache, the reference was never valid. The router places null where that object sat in the response, and what the client sees from there is the ordinary null-propagation story of the composed schema. Throwing is different and much blunter. If the resolver raises for the whole field, the field error hits `[_Entity]!`, which is non-null, so the whole `_entities` result becomes null and the entire batch of 23 is lost rather than one slot. That is why 'one bad representation kills the fetch' is a real production failure mode: a subgraph that lets a malformed key throw out of the loop turns a single dud reference into a wholesale hole in the response. ## Testing it The test that catches this costs three lines: send a batch of at least three representations where the middle one does not exist, and assert both the length and the identity of each slot. Asserting length alone passes a padded-but-reordered list; asserting identity requires selecting a key field in the test document so you can see which entity landed where. A property test over shuffled batches is cheap here and catches the store-order variant that only shows up under a different query plan.