Fold a nested aggregator's partial result into one parent source outcome without flattening

When to use

Use this when the thing you call is itself an aggregator: a backend-for-frontend calling a service that fans out to several stores, a portal page calling a section service, a parent agent reading a sub-agent's summary, a pipeline stage consuming the merged output of an earlier stage, or a federated search calling a regional search that federates again.

This skill assumes each layer already models its own sources as ok, empty, unavailable or skipped with a separate completeness flag, and keeps partial results. It covers the narrower question that model leaves open: the child returns a structured result that says complete, partial or failed, and the parent has to turn that whole result into exactly one outcome for the child as a source. Done carelessly, the parent reintroduces the flattening the child avoided.

The failure pattern

1. Transport success read as ok and complete. The child answers with a success status and a body whose overall field says partial. The parent's client only checks the transport status, so the child becomes ok and complete. Everything the child could not see is now, at the parent, confirmed absent.
2. Failed child read as empty. The child reports overall failed with zero items, again over a success transport status. The parent sees an empty item list and reports empty. An outage two layers down becomes a confirmed absence one layer up.
3. Missing-source list dropped. The child names the sub-sources it could not reach. The parent keeps only a boolean or a count, so the consumer at the top cannot tell which data is missing or whether the missing part matters to it.
4. Required sub-source hidden inside a partial. The child treats an authorization or conflict check as optional and reports partial. The parent needed that check to be complete. Because the parent only sees the overall value, it proceeds.
5. Degrade counted twice. The parent derives its own overall status from the child's overall value and from the child's sub-source list, so the same missing sub-source lowers the parent's result twice, or once at each of three layers. Every response becomes partial and the flag stops meaning anything.
6. Stale label lost. The child served one sub-source from stale cache with an age. The parent copies the items and forgets the stale flag and age. The top layer presents fallback data as current.
7. Skipped required sub-source behind a complete overall. The child treats one store as optional and skips it to stay inside a time or cost budget. Nothing the child intended to read failed, so it reports overall complete with its completeness flag true and lists the store as skipped. The parent reads overall complete, finds items, and maps the child to ok and complete. If the skipped store is on the parent's required list, the parent has accepted a result missing something it needed, and no missing path is recorded because the child never considered the store missing. This is the one case where the child's overall value is honest and still wrong for the parent.

Rule

The parent classifies the child from the child's body, not from the transport status alone. It produces one outcome for the child using three inputs: the child's overall status, the child's completeness, and the parent's own requirement on the child's sub-sources. The mapping is:

• Child overall complete, one or more items: status ok, complete true.
• Child overall complete, zero items: status empty, complete true.
• Child overall partial, one or more items: status ok, complete false.
• Child overall partial, zero items: status empty, complete false. Do not report unavailable, because some sub-sources did answer. Do not report empty and complete, because some did not.
• Child overall failed: status unavailable, complete false, regardless of transport status.
• Transport failure, timeout, malformed body, or a body without a recognizable overall field: status unavailable, complete false. The child's sub-sources are all unknown.
• Any child sub-source that the parent lists as required is unavailable, incomplete, skipped, or stale beyond the parent's tolerance: status unavailable for the whole child, complete false, reason naming that sub-source and its state. This overrides the overall value, including a complete overall. A required sub-source reported as skipped is treated exactly like one reported unavailable, because from the parent's point of view the data is equally absent.
• Any child sub-source, required or not, reported as skipped: the parent's completeness for the child is false, even when the child's own completeness flag is true. The child's flag describes what the child intended to read; the parent's flag describes what was actually covered. Add the skipped sub-source to the missing list as a path with a reason of skipped.

Completeness at the parent is the child's completeness and never higher, and it is further lowered by any skipped entry in the child's sub-source list. The stale flag is true if any contributing sub-source was stale, and the reported age is the largest age among them. The effective as-of time used for any absence decision is the oldest observed time among the sub-sources that contributed.

The parent's overall status is then derived only from the parent's own per-source outcomes, where the child is one source. The child's internal partial has already been folded into that one outcome and is not counted again.

How to apply

1. Make the child's contract explicit. The child's result must expose an overall value of complete, partial or failed, a completeness flag, the item list, and a per-sub-source list with name, status, completeness, stale flag, age and reason. The sub-source list must include skipped entries, not only failed ones; a child that drops skipped entries from the list makes the parent's required check impossible. A summary sentence or a bare item list is not enough for a parent to classify safely.
2. Classify from the body. In the parent's adapter for the child, read the overall field first, then scan the sub-source list before trusting a complete overall. Treat a success transport status with a failed body as unavailable. Treat a success transport status with an unparseable body as unavailable. Never let a default of an empty collection fill a missing items field.
3. Declare requirements per layer. The parent keeps a short list of the child's sub-sources it requires, by name. If the child cannot prove those complete, the parent marks the child unavailable. The child cannot know what the parent needs, so this decision belongs to the parent. Pass the required names down with the request so the child does not skip them for budget reasons; this is the only defense against a child that omits skipped entries from its list.
4. Carry provenance as paths. The parent's outcome keeps a missing list whose entries are path names such as child name, then a separator, then sub-source name. Concatenate the child's missing list under the child's name rather than replacing it with a count, and include skipped entries with a reason of skipped. Bound the depth, for example three levels, and beyond that keep the count plus the top-level names.
5. Propagate the labels, not just the items. Copy the stale flag, the largest age, and the oldest observed time into the parent's outcome for the child. A consumer that gates absence decisions on stale false and completeness true must be able to see these at every depth.
6. Pass a remaining time budget down. Give the child a deadline that fits inside the parent's per-source timeout. A child that answers after the parent's deadline is unavailable at the parent even if its late answer was complete. Without this, the child's own per-source timeouts add up to more than the parent will wait, and the parent times out a child that was about to return a good partial answer.
7. Speak in the top layer's terms. When the top layer tells a user or an agent that a result is partial, name the missing paths in words the consumer understands, for example that the notes part of the activity section is unavailable, rather than listing internal service names or only saying partial.

Minimal shape (language-neutral)

child result = { overall: complete or partial or failed, complete: true or false, items: [...], sources: [ { name, status: ok or empty or unavailable or skipped, complete, stale, ageseconds, observedat, reason } ] }

parent outcome for the child = { name: "activity", status: ok or empty or unavailable or skipped, complete: child.complete and no sub-source is skipped and no required sub-source is missing, stale: any contributing sub-source stale, ageseconds: largest sub-source age, observedat: oldest sub-source observed time, missing: [ "activity/notes", "activity/transfers" ], items: child.items, reason }

Reasoned example

A portfolio page is assembled by a parent service from three sources: holdings, activity and alerts. The activity source is a child service that itself fans out to an orders store, a transfers store, a notes store and an ownership check. The notes store is down for ten minutes.

The child returns a success transport status with overall partial, orders and transfers items present, and notes listed as unavailable with a timeout reason.

A parent that classifies by transport status marks activity ok and complete. The page contains an onboarding banner shown whenever a user has no notes, and a nightly job that deletes empty note drafts for users with no notes. Both read the page model, both see no notes and completeness true, and both act. The banner appears for every user for ten minutes and the nightly job, if it runs in that window, deletes drafts.

A parent that follows this skill marks activity ok, complete false, missing activity slash notes, with the timeout reason. Its overall status is partial. The banner logic requires completeness true for the notes path and does not show. The nightly job requires completeness true and stale false and skips those users. The page shows orders and transfers and says that notes are temporarily unavailable.

Second case in the same setup: the child's sub-source list shows its ownership check as unavailable, and the parent lists that check as required for the activity section. The child still says partial. The parent marks activity unavailable and the whole section fails closed, while holdings and alerts still render.

Third case, the boundary this revision sharpens: all stores are healthy, but the child is running close to its deadline and treats the ownership check as optional, so it skips that check to return on time. Orders, transfers and notes are all present. The child reports overall complete, completeness true, and lists the ownership check with status skipped and a reason of budget. A parent that reads only the overall value maps activity to ok and complete, and the page renders activity for a user whose ownership was never confirmed. A parent that follows the rule scans the sub-source list, finds a required entry in the skipped state, and marks activity unavailable with a reason naming the ownership check as skipped. Holdings and alerts still render. If instead the parent had not required the ownership check, activity would be ok with completeness false and a missing path of activity slash ownership with reason skipped, so any consumer gating on completeness true would still hold back.

These cases are reasoning about the procedure. They are not the result of an executed test.

Checks before shipping

These are suggested verification steps for adopters, not observed results.

• Return a child body with overall partial over a success transport status. The parent outcome should be ok or empty with completeness false, and the missing list should contain the path-named sub-source.
• Return a child body with overall failed and zero items over a success transport status. The parent outcome should be unavailable, not empty.
• Return a child body with overall partial where the missing sub-source is on the parent's required list. The parent outcome should be unavailable with a reason naming that sub-source.
• Return a child body with overall complete and completeness true whose sub-source list contains a skipped entry that is on the parent's required list. The parent outcome should be unavailable with a reason naming that sub-source as skipped. Repeat with the same entry not on the required list; the parent outcome should be ok with completeness false and a missing path for it.
• Return a child body where one sub-source was served stale with an age. The parent outcome should carry stale true and that age.
• Nest three layers with one missing leaf. The top-level result should be partial exactly once and its missing list should contain one three-segment path.
• Delay the child past the parent's deadline while the child would have returned complete. The parent should report the child unavailable and the other parent sources should still appear.

Pitfalls

• A client wrapper that raises on transport errors but returns any success body untouched, so partial and failed bodies pass through as data.
• Trusting a complete overall value without scanning the sub-source list. A child that skipped an optional store reports complete in good faith, and only the parent knows whether that store was optional for it.
• Summaries between agents that say what was found but not what could not be checked or was skipped. A sub-agent's summary needs the same missing list a service response would carry.
• Deciding required sub-sources inside the child. The child does not know which consumer needs what.
• Recomputing the parent's overall status from the child's sub-source list as well as from the child's outcome, which degrades the same failure twice.
• Keeping only the newest observed time for the child, which makes an absence decision look fresher than its oldest contributing sub-source.
• Carrying the missing list only in logs. The top layer's consumer needs it in the response.