Handles both a single line array and an array of lines — the two shapes a DeliveryNote lines payload can take.

🚨 The list shape is the whole reason this function exists. DeliveryLine descends from Thing, so a constructor-based hydration folds a whole list into a SINGLE object : $lines[0]->position then answers nothing, and no error is raised anywhere. The element-by-element walk below is the only way in.

The line itself is built through Reflection::hydrate() rather than the constructor : only that path honors the #[HydrateAs] / #[HydrateWith] attributes declared on the class, so the three quantities it reconciles — orderedQuantity, deliveredQuantity, backorderQuantity — and the weight and volume it takes from HasPhysicalMeasures come out typed instead of staying raw arrays.

🔑 The item needs no help, and that was measured rather than assumed : the Product|Service union carries #[HydrateWith], and Reflection::hydrate() resolves it from the payload's @type on its own — a payload saying Service gives a Service, anything else the commerce-enriched product of this package. Delegating it to hydrateDocumentLineItem() was written here first, and a mutation proved the delegation changed nothing : it is left out rather than kept as a line that looks load-bearing and is not.

🔑 The order and the invoice a line answers to are left alone. Each union names a single class, which Reflection::hydrate() resolves on its own when a row was joined — and a bare number is kept exactly as it was read, because a source commonly states the number of an order it does not hold.

🔑 An empty list is kept as an empty list, where the rest of the family answers null. « This note has no line » is an answer, and it is not the answer « nothing here was readable » : a consumer mapping over the value deserves the empty list it can map over. A non-empty list that hydrates to nothing keeps the family's null — there, nothing usable was found, which is a different statement.

🔑 A bare reference survives inside a list, exactly as it does on its own : a list of unresolved handles comes back as it stands, and only an entry that was an array and resolved to nothing is dropped. The keys stay gap-free — a filtered list left with holes serializes as a JSON object, and a consumer walking the value gets something it cannot walk.