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

When a sum, count, average, rate or percentage is computed across several sources and one is unavailable or incomplete, do not return a plain number. Carry per-source coverage into the aggregate, report monotone aggregates as bounds, treat signed sums and ratio-style aggregates as unknown or a range, and block threshold, quota and billing decisions that the missing share could flip.

Exact reference: {"kind":"skill_version","skill_id":"skl_Fbo1-v_mQB9nktSbX863vw","version_id":"skv_XeKpHE8GWLnzdYy7X_lR1w"}

Applicability: [{"constraint":"Any operation that returns a total, count, sum, average, rate or ratio computed across two or more independent sources","technology":"distributed systems and API aggregation","version_scheme":"unknown"},{"constraint":"KPI tiles, time-series rollups, period-over-period comparisons and anomaly alerting built from several upstream sources","technology":"metrics, dashboards and rollups","version_scheme":"unknown"},{"constraint":"Threshold, limit or invoicing decisions taken on a number aggregated from several meters or counters, including net totals with credits or refunds","technology":"billing, quota and rate limiting","version_scheme":"unknown"},{"constraint":"Agents that fan out to several tools and report a combined count or total to a user or a later step","technology":"agent tool orchestration","version_scheme":"unknown"}]

# 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.

A fifth shape is the **false lower bound**. A net total that mixes positive and negative contributions, such as usage minus credits, is labelled at least N because it is called a sum. The missing source may hold a credit, so the true value may be below N. The label promises a direction that the arithmetic does not guarantee.

## 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 inputs that are guaranteed non-negative. 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. The guarantee must hold for every source that could be missing, not merely for the sources that happened to respond.
- **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.
- **Signed sums are non-monotone.** A net total, balance, delta, or count that admits negative adjustments is a sum by name but not a monotone aggregate. A missing source could add or subtract, so the computed value is neither a lower nor an upper bound. Treat it exactly like a ratio: unknown, or a range when the magnitude of each missing contribution is bounded by a known limit.
- **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.

The classification test is a single question: for every source that might be missing, is the sign of its contribution guaranteed in advance? If yes for all, the aggregate is monotone and the direction of the bound follows the sign. If no for any, the aggregate is non-monotone regardless of what the operation is called.

## Boundary example: signed contributions

Four regional meters each report net usage for the hour, defined as consumption minus credits and refunds issued in that region. Regions A, B and C respond with a combined net of one thousand two hundred. Region D is unavailable.

If Region D had issued a five hundred credit and no consumption, the true net is seven hundred. If Region D had five hundred of consumption and no credit, the true net is one thousand seven hundred. Both are consistent with the data received. The computed value of one thousand two hundred is therefore not a bound in either direction, and reporting it as at least one thousand two hundred is wrong in the first case.

Correct handling splits the aggregate into its signed parts before classifying. Gross consumption across A, B and C is a monotone sum over non-negative inputs and may be reported as a lower bound. Gross credits across A, B and C are likewise a lower bound on total credits. The net is the difference of two lower bounds and is unknown. If a policy caps credits per region per hour, for example at one thousand, the net can be reported as a range from the computed value minus one thousand up to the computed value plus the largest plausible consumption, or simply as unknown if no such cap exists.

The same reasoning applies to inventory on hand with negative adjustments, account balances built from deposits and withdrawals, and any change-over-period figure. When in doubt, keep positive and negative flows as separate monotone aggregates with their own coverage, and derive the net only when both sides have full coverage.

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

## 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. Apply the sign test from the rule section before choosing a bound form; a sum that can contain negative contributions gets unknown or range, never at least N.
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: lower_bound or upper_bound 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 one source of a net total that includes credits or negative adjustments. The net should be reported unknown or as a range, never as at least N. The gross positive and gross negative parts may each be reported as lower bounds.
- 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.
- Labelling a net total, balance or delta as at least N because the operation is a sum, when a missing source could have contributed a negative amount.
- 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.

## Supporting basis and limitations

The basis is reasoning, not executed tests. No code was written, no test or reproduction was run, and no external sources are cited. The gap was identified during a maintenance review of the base version and discussed in the linked conversation, where the opening message identified the unillustrated non-negative condition and the follow-up message worked through the concrete net usage case and its limitations. The argument follows from arithmetic. If every missing contribution is guaranteed non-negative, adding it can only raise a sum, count or maximum, so the computed value is a lower bound. If any missing contribution may be negative, adding it may raise or lower the total, so the computed value is not a bound in either direction. The worked numbers in the boundary example are chosen to show both outcomes from the same received data: three regions net one thousand two hundred, and a missing fourth region holding either a five hundred credit or five hundred of consumption yields seven hundred or one thousand seven hundred respectively. Splitting a net into gross positive and gross negative parts restores monotonicity for each part because each part is a sum over non-negative inputs; the net remains unknown because it is a difference, which the base version already classifies as non-monotone. The range form for capped credits follows the same logic as the existing range guidance. One limitation was noted in the conversation and is deliberately not addressed in this update: mixed cases where some sources are guaranteed non-negative and others are signed would require a per-source sign field in the minimal shape, which is a schema change that has not been designed. This update keeps the minimal shape unchanged and covers the mixed case only by the conservative rule that the guarantee must hold for every source that could be missing. The new pre-ship check and pitfall are suggested verification steps for adopters, not observed results. A separate verification procedure discussed in the same conversation is intentionally left out of this update.

## Change and rationale

Sharpens the monotone boundary. The rule now states that the non-negative guarantee must hold for every source that could be missing, adds a bullet classifying signed sums such as net totals, balances and deltas as non-monotone, and gives a one-question classification test based on whether the sign of each missing contribution is guaranteed. Adds a fifth failure shape, the false lower bound. Adds a boundary example section with a worked net usage case where a missing region could hold either a credit or consumption, showing the computed value is not a bound and how to split gross positive and gross negative flows into separate monotone aggregates. Adds a matching pre-ship check and pitfall. All other guidance is preserved unchanged.

The base version qualifies the monotone class with the words over non-negative inputs but never illustrates the qualifier, and its only worked example uses purely positive meter readings. A reader who applies the skill to net usage, inventory with adjustments or account balances can therefore label a partial total as at least N when the missing source might have contributed a negative amount, which recreates the silent bias the skill exists to prevent. Making the sign condition explicit, giving a concrete two-outcome example and adding a classification test closes that gap without changing the data shape or any other procedure step.