Report bounds and coverage for numeric aggregates over partial fan-out results

When to use

Use this when an operation combines numbers from two or more independent sources and returns a total, count, sum, maximum, average, median, percentage, rate or ratio. Typical cases are dashboards and KPI tiles, usage and billing rollups, quota and rate-limit checks, inventory and capacity totals, health and error-rate scores, cost reports, and agents that summarize counts across several tools.

This skill assumes the caller already models each source outcome as ok, empty, unavailable or skipped, with a separate completeness flag, and keeps partial results instead of failing the whole operation. It covers the narrower question of what number may be emitted from a partial set of sources and which decisions that number may support.

The failure pattern

A list built from a partial fan-out at least looks short. A number built from a partial fan-out looks like a number. Nothing about the value 1250 says that a fourth of the inputs never arrived. Three shapes are common:

1. Silent under-count. A sum over three of four regions is returned as the total. A dashboard shows a dip, an alert fires for a traffic drop, or a quota check passes because usage appears lower than it is.
2. Biased ratio. An error rate whose numerator source failed but whose denominator source succeeded, or the reverse. The result is not a bound in either direction. It is simply wrong, and there is no way to tell from the value.
3. Zero default. The unavailable source is folded in as zero. A per-source breakdown shows a zero bar, a week-over-week comparison shows a one hundred percent decline, and a rule such as no usage this period fires.

A fourth shape appears on recovery. When the missing source returns, the number jumps back up, and an anomaly detector that was quiet during the outage fires on the recovery instead.

Rule

A numeric aggregate is a value plus a coverage record, never a bare number. Coverage states which sources contributed and, where known, what share of the expected scope they represent. Classify each aggregate by how a missing input can move the true value:

• Monotone aggregates such as sum, count and maximum over non-negative inputs. A missing input can only make the true value larger. Report the computed value as a lower bound with the missing sources named. A minimum over sources is the mirror case and is an upper bound.
• Non-monotone aggregates such as average, median, percentage, rate, ratio, difference and anything with a denominator. A missing input can move the true value in either direction. Report unknown, or a range if per-source bounds are known. Never present a point value as the answer.
• Existence tests derived from numbers such as count equals zero or usage is under the limit. Treat these like absence decisions. They require full coverage and confirmed completeness.

How to apply

1. Compute per source first. Keep each source number next to its status. Never fold an unavailable or skipped source in as zero. Represent its contribution as unknown, which is a distinct value from zero and from empty.
2. Attach coverage. Record contributing sources over expected sources. Where weights are known, for example last period share or a known population size per source, add an estimated share of scope. Say explicitly when weights are unknown rather than assuming equal weight.
3. Pick the report form by aggregate class. Use at least N for a lower bound, at most N for an upper bound, a range when both are known, exact only with full coverage, and unknown otherwise. Carry the form as a field, not just in display text.
4. Build ratios from one source set. Numerator and denominator must come from exactly the same set of sources. If the sets differ, reduce both to the intersection and report the coverage of that intersection. Never divide a numerator from three sources by a denominator from four.
5. Compare only on matching coverage. For a change over time, compare the contributing sources today with the same sources in the earlier period and label the comparison as restricted. If that is not possible, mark the comparison unavailable rather than showing a decline.
6. Ask whether the missing share could flip a decision. For a threshold test on a monotone aggregate, over threshold is safe to decide once the lower bound exceeds the threshold. Under threshold is not safe to decide unless coverage is full. For each decision, state which side is the safe failure. Do not finalize an invoice on a partial total. Do not release capacity on a partial count. For rate limiting, choose deliberately between failing open and failing closed and record that choice with the decision.
7. Alert on coverage separately from value. Emit a coverage metric and alert when it falls below a floor. Suppress or tag value-based anomaly alerts while coverage is below the floor, and for one evaluation window after coverage recovers, so the recovery jump is not reported as an anomaly.
8. Show partial numbers as partial. Render a visible marker and a coverage statement next to the value. In breakdown charts, draw an unavailable source as a distinct unknown mark, not as a zero bar. In agent or chat output, say at least and name the missing source.
9. Store coverage with rollups. When persisting hourly or daily totals, store the coverage record beside the value. A partial historical point must remain distinguishable from a genuinely quiet period. Never overwrite a fully covered rollup with a partial one.
10. Backfill on recovery. When a source returns, recompute the affected windows, replace partial rollups, and record that a backfill occurred so later comparisons over that period are consistent.

Minimal shape (language-neutral)

aggregate = { kind: sum, value: 1250, form: lowerbound or upperbound or range or exact or unknown, coverage: { contributing: 3, expected: 4, scope_share: 0.7 or unknown, complete: false }, missing: [ { name: "region-d", status: unavailable, reason: "timeout" } ] }

Only an aggregate with form exact and full coverage may support a decision that a count is zero or that a value is under a limit.

Reasoned example

Usage-based billing reads four regional meters every hour. Region D times out during one hourly rollup.

Without this rule, the customer usage for that hour is under-reported by the Region D share, the invoice is wrong, a quota check passes because usage looks lower, and when Region D recovers the next hour shows a jump that trips a sudden-usage rule.

With this rule, the hour is stored as a lower bound with coverage three of four. The invoicing job refuses to finalize any hour whose coverage is incomplete and waits for a backfill. The quota check reports that it cannot confirm usage is under the limit and applies the policy chosen for that case. The coverage alert fires once. The anomaly detector ignores the recovery jump because coverage changed in the same window.

This example is reasoning about the procedure. It is not the result of an executed test.

Checks before shipping

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

• Fail one source. The sum should be reported as a lower bound with the missing source named, the average should be reported unknown or as a range, and no breakdown should show a zero for that source.
• Fail the numerator source of a ratio but not the denominator source. The ratio should be reported unknown, not as a low value.
• Run a threshold test with partial coverage. Over threshold should still be decided when the lower bound exceeds it. Under threshold should be blocked.
• Persist a partial rollup, then recover the source. The partial rollup should carry coverage, the backfill should replace it, and a full rollup should never be overwritten by a partial one.
• Drop coverage below the floor. The coverage alert should fire, value anomaly alerts should be suppressed or tagged, and no alert should fire on the recovery jump.
• Compute a period-over-period change with a partial current period. The comparison should be restricted to matching sources or marked unavailable.

Pitfalls

• Default-to-zero in reducers, fold operations or database coalesce expressions.
• Averages formed by dividing a partial sum by the full expected count.
• Health scores or percent-complete figures that count unavailable sources as either failing or passing.
• Treating a count of zero from partial data as proof that nothing exists.
• Rollups stored without coverage, so a partial hour is indistinguishable from a quiet hour forever.
• Anomaly detectors that treat the recovery as the anomaly.
• Displaying a coverage note in a tooltip only, where downstream consumers and exports never see it.