@trazum/core 1.53.4 → 1.55.0

package/dist/rollup.js

@@ -0,0 +1,844 @@
+/**
+ * Several records, one roll-up, and every contributor's gaps still visible.
+ *
+ * Everything else in this repository assumes one operator with files on disk.
+ * `--by-source` and `owners` divide a bill somebody already collected;
+ * `fleetRollup` compares services whose logs one machine could open. None of
+ * them answers the question a team actually has: **four people measured four
+ * things, and nobody wants to email logs around.**
+ *
+ * So this module merges *documents*, not logs. Each contributor runs
+ * `trazum profile --json` wherever their traffic already is, and hands over a
+ * profile document — which carries no prompt text, no completion text, no
+ * session keys and no credentials, and never has. The roll-up is a format and
+ * a merge rather than a service: the transport is somebody else's problem,
+ * deliberately, because a tool whose argument is that it reads your bill
+ * without uploading it cannot also be the place everybody's bill is uploaded.
+ *
+ * **The merge is the easy half.** The half worth building carefully is what
+ * *cannot* be merged, and this module refuses in four different ways:
+ *
+ * - **Findings that need the records.** Percentile shapes, conversation
+ *   growth, repeated turns, truncation retries — every one of them is computed
+ *   from individual calls, and a summary of a summary cannot reproduce them.
+ *   They are named, with the contributors that had them, rather than dropped.
+ * - **A day's dearest label.** Each contributor states its own; the merged
+ *   answer needs per-label-per-day figures no document carries. Where two
+ *   contributors share a day the answer is `null` with the reason attached,
+ *   not the louder contributor's.
+ * - **Overlap between contributors.** Two people exporting the same traffic
+ *   double the bill, and nothing here can see it: the roll-up never sees a raw
+ *   line, so the duplicate detection a single profile does is structurally out
+ *   of reach. Every roll-up of more than one contributor says so.
+ * - **Each contributor's own blind spots.** Unreadable lines, unpriced calls,
+ *   a log with no clock. Summing them into one figure would say "3% of this
+ *   roll-up is unpriced" when the truth is "one of your four machines is 90%
+ *   unpriced and the other three are clean" — the same averaging-away this arc
+ *   exists to refuse. They stay per contributor.
+ *
+ * No I/O: the caller hands over text it read, so this stays browser-safe and
+ * the CLI keeps its monopoly on the filesystem.
+ */
+import { conform } from './conform.js';
+/**
+ * Every numeric field of a breakdown, and how two of them combine.
+ *
+ * Listed rather than inferred, because both mistakes here are silent. A field
+ * left out of both lists would vanish from every merged breakdown — a finding
+ * present in each contribution and absent from the roll-up. And
+ * `maxCallInputTokens` summed would report a fleet whose largest call is the
+ * sum of four machines' largest calls, which is a number no call ever had, in
+ * the direction that makes a context window look tight.
+ *
+ * `rollup.test.js` derives the field names from `usage.ts` and fails the build
+ * when one is in neither list, so the next field added upstream cannot be
+ * quietly dropped here.
+ */
+const BREAKDOWN_SUM = [
+    'calls',
+    'inputTokens',
+    'cacheReadTokens',
+    'cacheWriteTokens',
+    'cacheWrite5mTokens',
+    'cacheWrite1hTokens',
+    'outputTokens',
+    'assumedWriteTtlCalls',
+    'inputUsd',
+    'cacheReadUsd',
+    'cacheWriteUsd',
+    'outputUsd',
+    'totalUsd',
+    'cachedTokensAtInputRateUsd',
+    'cacheWriteUsdIfAssumed1h',
+    'truncatedCalls',
+    'truncatedOutputUsd',
+    'stopReasonCalls',
+];
+/** Fields whose combination is a maximum, because a sum would invent a call. */
+const BREAKDOWN_MAX = ['maxCallInputTokens'];
+/** Every counter of a coverage tally. All of them sum. */
+const COVERAGE_FIELDS = [
+    'label',
+    'session',
+    'outcome',
+    'ts',
+    'stopReason',
+    'cacheTtl',
+    'cacheWrites',
+    'parsed',
+];
+const emptyBreakdown = () => {
+    const out = {};
+    for (const field of BREAKDOWN_SUM)
+        out[field] = 0;
+    for (const field of BREAKDOWN_MAX)
+        out[field] = 0;
+    return out;
+};
+const emptyCoverage = () => {
+    const out = {};
+    for (const field of COVERAGE_FIELDS)
+        out[field] = 0;
+    return out;
+};
+const numberAt = (source, field) => {
+    const value = source[field];
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+};
+const asString = (value) => typeof value === 'string' && value !== '' ? value : null;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Adds one contribution's breakdown into an accumulator.
+ *
+ * Returns the numeric fields it did not recognise, so a document from a newer
+ * Trazum is reported rather than half-merged. Guessing that an unknown number
+ * is additive is how a ratio becomes four times itself.
+ */
+function addBreakdown(into, from) {
+    if (!isRecord(from))
+        return [];
+    const target = into;
+    for (const field of BREAKDOWN_SUM)
+        target[field] = (target[field] ?? 0) + numberAt(from, field);
+    for (const field of BREAKDOWN_MAX) {
+        target[field] = Math.max(target[field] ?? 0, numberAt(from, field));
+    }
+    const known = new Set([...BREAKDOWN_SUM, ...BREAKDOWN_MAX]);
+    return Object.keys(from).filter((key) => !known.has(key) && typeof from[key] === 'number');
+}
+/**
+ * Merges keyed breakdowns — labels, models, or the pair — into one map.
+ *
+ * The identity travels in the value rather than being parsed back out of the
+ * key: a label may contain any character, including whatever separator a key
+ * would join on, and a pair key split on a separator the label also uses
+ * silently merges two different workloads.
+ */
+function mergeKeyed(into, rows, identityOf) {
+    if (!Array.isArray(rows))
+        return;
+    for (const row of rows) {
+        if (!isRecord(row))
+            continue;
+        const identity = identityOf(row);
+        if (identity === null)
+            continue;
+        const key = JSON.stringify([identity.label, identity.model]);
+        const slice = into.get(key) ?? { ...identity, breakdown: emptyBreakdown() };
+        addBreakdown(slice.breakdown, row.breakdown);
+        into.set(key, slice);
+    }
+}
+/** Largest bill first, the order somebody would act in. */
+const byMoney = (rows, usd) => [...rows].sort((a, b) => usd(b) - usd(a));
+const DAY_MS = 86_400_000;
+/** UTC `YYYY-MM-DD` for an instant — the bucketing every day figure here uses. */
+const dayOf = (ms) => new Date(ms).toISOString().slice(0, 10);
+/** Midnight UTC of the day an instant falls in. */
+const midnightOf = (ms) => Date.parse(`${dayOf(ms)}T00:00:00.000Z`);
+/**
+ * The longest claim this module will walk day by day: ten years.
+ *
+ * A bound rather than trust, because these documents come from elsewhere. A
+ * contribution claiming `untilMs: 1e15` is a malformed document, not a team
+ * with a long memory, and enumerating it would be thirty million iterations
+ * inside a merge somebody ran on four files. The claim is kept and reported;
+ * only the enumeration is refused, with a caveat saying so — a refusal never
+ * arrives bare.
+ */
+const MAX_CLAIM_DAYS = 3660;
+/**
+ * The stretches of a claimed window on which nothing was recorded.
+ *
+ * Returns `null` when the claim cannot be walked: unbounded on either end, out
+ * of order, or longer than the bound above. The window is half-open, so the
+ * last claimed day is the one containing `untilMs - 1` — an `until` of
+ * midnight claims up to the previous day and not that day, which is how the
+ * profile's own filter reads it.
+ */
+function silenceIn(claim, daysWithTraffic) {
+    const { sinceMs, untilMs } = claim;
+    if (sinceMs === null || untilMs === null)
+        return null;
+    if (!Number.isFinite(sinceMs) || !Number.isFinite(untilMs))
+        return null;
+    if (untilMs <= sinceMs)
+        return null;
+    const first = midnightOf(sinceMs);
+    const last = midnightOf(untilMs - 1);
+    const span = Math.round((last - first) / DAY_MS) + 1;
+    if (span > MAX_CLAIM_DAYS)
+        return null;
+    const runs = [];
+    let open = null;
+    let days = 0;
+    for (let at = first; at <= last; at += DAY_MS) {
+        const day = dayOf(at);
+        if (daysWithTraffic.has(day)) {
+            if (open !== null)
+                runs.push(open);
+            open = null;
+            continue;
+        }
+        days += 1;
+        if (open === null)
+            open = { from: day, to: day, days: 1 };
+        else {
+            open.to = day;
+            open.days += 1;
+        }
+    }
+    if (open !== null)
+        runs.push(open);
+    return { runs, days };
+}
+/** The findings a document carries per call, which no summary can reconstruct. */
+const PER_RECORD_FINDINGS = [
+    {
+        field: 'conversations',
+        finding: 'conversation growth',
+        because: 'it is measured over the turns of one session, and a document carries the growth rather than the turns',
+    },
+    {
+        field: 'inputShapes',
+        finding: 'input shape — the median and p95 call',
+        because: 'a percentile of two contributors is not a percentile of their percentiles, and the calls behind them are in neither document',
+    },
+    {
+        field: 'outputShapes',
+        finding: 'output concentration',
+        because: 'it asks what share of the calls holds what share of the output spend, and both shares need the individual calls',
+    },
+    {
+        field: 'repeatedTurns',
+        finding: 'repeated turns — the shape of a retry loop',
+        because: 'it compares consecutive calls in one session seconds apart, and consecutive calls are what a summary has already collapsed',
+    },
+    {
+        field: 'truncationRetries',
+        finding: 'truncation followed by a retry',
+        because: 'it pairs a truncated answer with the call that followed it, and a document carries neither call',
+    },
+];
+/**
+ * Merges profile documents into one roll-up.
+ *
+ * Every input is checked against the `profile` contract before a figure of it
+ * is used. A document that does not conform is **rejected with its reason and
+ * not merged** — a roll-up that quietly skipped a malformed contribution would
+ * report a total missing one machine's entire bill, and the reader would have
+ * no way to tell that from that machine having spent nothing.
+ */
+export function rollUp(inputs) {
+    const contributors = [];
+    const rejected = [];
+    const cannotSay = new Set();
+    const total = emptyBreakdown();
+    const unpriced = emptyBreakdown();
+    const unpricedModels = new Set();
+    const labels = new Map();
+    const models = new Map();
+    const pairs = new Map();
+    const coverage = emptyCoverage();
+    const outcomeValues = new Map();
+    const outcome = { recorded: 0, parsed: 0, unrecordedUsd: 0 };
+    const duplicateLines = { count: 0, usd: 0 };
+    const unknownFields = new Set();
+    const days = new Map();
+    const findingsPresentIn = new Map();
+    /** Findings a nested roll-up already refused to merge, carried through. */
+    const nestedFindings = new Map();
+    /** Identical-document groups a nested roll-up already found. */
+    const nestedIdentical = [];
+    /** The text of each accepted contribution, for the identical-document check. */
+    const seenText = new Map();
+    let identicalUsd = 0;
+    let claimFrom = null;
+    let claimTo = null;
+    let claimants = 0;
+    let spanFrom = null;
+    let spanTo = null;
+    let spanCalls = 0;
+    for (const input of inputs) {
+        /**
+         * A profile, or a roll-up somebody else already made.
+         *
+         * Detected rather than forced, because a roll-up is a contribution too:
+         * three teams roll up their own machines, and the organisation rolls up
+         * the three. Every summable part of a roll-up carries the same field names
+         * as a profile — that is what makes the nesting arithmetic free — and the
+         * parts that are *not* summable are exactly the ones this loop has to
+         * carry through by hand rather than lose a layer at a time.
+         */
+        const checked = conform(input.text);
+        const nested = checked.contract === 'roll-up';
+        if (!checked.conforms || (checked.contract !== 'profile' && !nested)) {
+            const first = checked.problems[0];
+            rejected.push({
+                name: input.name,
+                via: null,
+                because: first === undefined
+                    ? (checked.because ?? 'it is neither a profile nor a roll-up')
+                    : `${first.at}: ${first.detail}`,
+            });
+            cannotSay.add('contribution-rejected');
+            continue;
+        }
+        // `conform` parsed it once already and reported nothing, so this cannot
+        // throw — but a parse whose failure mode is a crash is a parse worth
+        // guarding, and the reject path above is already the right answer.
+        let parsed;
+        try {
+            parsed = JSON.parse(input.text.trim());
+        }
+        catch {
+            rejected.push({ name: input.name, via: null, because: 'it is not valid JSON' });
+            cannotSay.add('contribution-rejected');
+            continue;
+        }
+        if (!isRecord(parsed)) {
+            rejected.push({ name: input.name, via: null, because: 'a document must be a JSON object' });
+            cannotSay.add('contribution-rejected');
+            continue;
+        }
+        const doc = parsed;
+        const text = input.text.trim();
+        const sameAs = seenText.get(text);
+        if (sameAs === undefined) {
+            seenText.set(text, [input.name]);
+        }
+        else {
+            sameAs.push(input.name);
+            cannotSay.add('identical-contributions');
+            identicalUsd += isRecord(doc.total) ? numberAt(doc.total, 'totalUsd') : 0;
+        }
+        for (const field of addBreakdown(total, doc.total))
+            unknownFields.add(field);
+        addBreakdown(unpriced, doc.unpriced);
+        if (Array.isArray(doc.unpricedModels)) {
+            for (const model of doc.unpricedModels) {
+                const name = asString(model);
+                if (name !== null)
+                    unpricedModels.add(name);
+            }
+        }
+        mergeKeyed(labels, doc.byLabel, (row) => {
+            const label = asString(row.label);
+            return label === null ? null : { label, model: null };
+        });
+        mergeKeyed(models, doc.byModel, (row) => {
+            const model = asString(row.model);
+            return model === null ? null : { label: null, model };
+        });
+        mergeKeyed(pairs, doc.byLabelAndModel, (row) => {
+            const label = asString(row.label);
+            const model = asString(row.model);
+            return label === null || model === null ? null : { label, model };
+        });
+        if (isRecord(doc.fieldCoverage)) {
+            const target = coverage;
+            for (const field of COVERAGE_FIELDS) {
+                target[field] = (target[field] ?? 0) + numberAt(doc.fieldCoverage, field);
+            }
+        }
+        if (isRecord(doc.outcomeTally)) {
+            const tally = doc.outcomeTally;
+            outcome.recorded += numberAt(tally, 'recorded');
+            outcome.parsed += numberAt(tally, 'parsed');
+            outcome.unrecordedUsd += numberAt(tally, 'unrecordedUsd');
+            if (Array.isArray(tally.byValue)) {
+                for (const row of tally.byValue) {
+                    if (!isRecord(row))
+                        continue;
+                    const value = asString(row.value);
+                    if (value === null)
+                        continue;
+                    const current = outcomeValues.get(value) ?? { calls: 0, usd: 0 };
+                    current.calls += numberAt(row, 'calls');
+                    current.usd += numberAt(row, 'usd');
+                    outcomeValues.set(value, current);
+                }
+            }
+        }
+        if (isRecord(doc.duplicateLines)) {
+            duplicateLines.count += numberAt(doc.duplicateLines, 'count');
+            duplicateLines.usd += numberAt(doc.duplicateLines, 'usd');
+        }
+        if (Array.isArray(doc.spendByDay)) {
+            for (const row of doc.spendByDay) {
+                if (!isRecord(row))
+                    continue;
+                const day = asString(row.day);
+                if (day === null)
+                    continue;
+                const bucket = days.get(day) ?? {
+                    usd: 0,
+                    calls: 0,
+                    contributors: 0,
+                    models: new Map(),
+                    from: new Set(),
+                    topLabel: null,
+                    topLabelUsd: null,
+                };
+                bucket.usd += numberAt(row, 'usd');
+                bucket.calls += numberAt(row, 'calls');
+                bucket.from.add(input.name);
+                // How many *machines* saw this day, not how many documents mentioned
+                // it: a nested roll-up already knows its own count, and counting it as
+                // one would report twelve machines as three.
+                bucket.contributors += Math.max(1, numberAt(row, 'contributors') || 1);
+                if (bucket.from.size === 1) {
+                    bucket.topLabel = asString(row.topLabel);
+                    bucket.topLabelUsd = bucket.topLabel === null ? null : numberAt(row, 'topLabelUsd');
+                }
+                else {
+                    // A second contributor on this day puts the merged answer out of
+                    // reach, and the first contributor's answer stops being the
+                    // roll-up's answer.
+                    bucket.topLabel = null;
+                    bucket.topLabelUsd = null;
+                    cannotSay.add('day-top-label-unknown');
+                }
+                if (Array.isArray(row.byModel)) {
+                    for (const entry of row.byModel) {
+                        if (!isRecord(entry))
+                            continue;
+                        const name = asString(entry.model);
+                        if (name === null)
+                            continue;
+                        const current = bucket.models.get(name) ?? { usd: 0, calls: 0 };
+                        current.usd += numberAt(entry, 'usd');
+                        current.calls += numberAt(entry, 'calls');
+                        bucket.models.set(name, current);
+                    }
+                }
+                days.set(day, bucket);
+            }
+        }
+        for (const entry of PER_RECORD_FINDINGS) {
+            const value = doc[entry.field];
+            if (Array.isArray(value) && value.length > 0) {
+                const list = findingsPresentIn.get(entry.field) ?? [];
+                list.push(input.name);
+                findingsPresentIn.set(entry.field, list);
+            }
+        }
+        /**
+         * A roll-up somebody else already made: carry through what does not sum.
+         *
+         * Everything above this point merged already, because a roll-up names its
+         * summable parts exactly the way a profile does. What is left is the half
+         * that would quietly disappear a layer at a time — and each of these is a
+         * refusal that must survive nesting or the format is worse than no format:
+         *
+         * - **Contributors are flattened, not collapsed.** Twelve machines stay
+         *   twelve machines with twelve sets of gaps.
+         * - **Rejections travel, with the roll-up they came through.** Otherwise a
+         *   machine whose document did not conform could be made to disappear by
+         *   adding a layer.
+         * - **Caveats travel.** An inner roll-up that could not see overlap does
+         *   not become an outer roll-up that could.
+         * - **Findings that did not roll up inside do not roll up outside.**
+         */
+        if (nested) {
+            if (Array.isArray(doc.contributors)) {
+                for (const row of doc.contributors) {
+                    if (!isRecord(row))
+                        continue;
+                    const name = asString(row.name);
+                    if (name === null)
+                        continue;
+                    const innerSpan = isRecord(row.span)
+                        ? {
+                            fromMs: numberAt(row.span, 'fromMs'),
+                            toMs: numberAt(row.span, 'toMs'),
+                            calls: numberAt(row.span, 'calls'),
+                        }
+                        : null;
+                    contributors.push({
+                        name,
+                        // The roll-up it arrived through — never overwritten when it is
+                        // already set, so a third layer says which roll-up handed it over
+                        // rather than claiming the machine came straight from there.
+                        via: asString(row.via) ?? input.name,
+                        totalUsd: numberAt(row, 'totalUsd'),
+                        calls: numberAt(row, 'calls'),
+                        span: innerSpan,
+                        spanDays: typeof row.spanDays === 'number' ? row.spanDays : null,
+                        claimed: isRecord(row.claimed)
+                            ? {
+                                sinceMs: typeof row.claimed.sinceMs === 'number' ? row.claimed.sinceMs : null,
+                                untilMs: typeof row.claimed.untilMs === 'number' ? row.claimed.untilMs : null,
+                            }
+                            : null,
+                        silence: isRecord(row.silence)
+                            ? {
+                                runs: Array.isArray(row.silence.runs) ? row.silence.runs : [],
+                                days: numberAt(row.silence, 'days'),
+                            }
+                            : null,
+                        undatedExcluded: typeof row.undatedExcluded === 'number' ? row.undatedExcluded : null,
+                        gaps: Array.isArray(row.gaps) ? row.gaps : [],
+                    });
+                }
+            }
+            if (Array.isArray(doc.rejected)) {
+                for (const row of doc.rejected) {
+                    if (!isRecord(row))
+                        continue;
+                    const name = asString(row.name);
+                    if (name === null)
+                        continue;
+                    rejected.push({
+                        name,
+                        via: asString(row.via) ?? input.name,
+                        because: asString(row.because) ?? 'no reason travelled with it',
+                    });
+                    cannotSay.add('contribution-rejected');
+                }
+            }
+            if (Array.isArray(doc.cannotSay)) {
+                for (const code of doc.cannotSay) {
+                    const caveat = asString(code);
+                    if (caveat !== null)
+                        cannotSay.add(caveat);
+                }
+            }
+            if (Array.isArray(doc.notMerged)) {
+                for (const row of doc.notMerged) {
+                    if (!isRecord(row))
+                        continue;
+                    const finding = asString(row.finding);
+                    if (finding === null)
+                        continue;
+                    const list = nestedFindings.get(finding) ?? {
+                        because: asString(row.because) ?? '',
+                        presentIn: [],
+                    };
+                    if (Array.isArray(row.presentIn)) {
+                        for (const who of row.presentIn) {
+                            const named = asString(who);
+                            if (named !== null && !list.presentIn.includes(named))
+                                list.presentIn.push(named);
+                        }
+                    }
+                    nestedFindings.set(finding, list);
+                }
+            }
+            if (isRecord(doc.identicalContributions)) {
+                identicalUsd += numberAt(doc.identicalContributions, 'usd');
+                if (Array.isArray(doc.identicalContributions.groups)) {
+                    for (const group of doc.identicalContributions.groups) {
+                        if (Array.isArray(group)) {
+                            nestedIdentical.push(group.map((name) => String(name)));
+                        }
+                    }
+                }
+            }
+            if (isRecord(doc.claimedSpan)) {
+                const from = numberAt(doc.claimedSpan, 'fromMs');
+                const to = numberAt(doc.claimedSpan, 'toMs');
+                if (from > 0 && to > from) {
+                    claimFrom = claimFrom === null ? from : Math.min(claimFrom, from);
+                    claimTo = claimTo === null ? to : Math.max(claimTo, to);
+                    claimants += Math.max(1, numberAt(doc.claimedSpan, 'contributors') || 1);
+                }
+            }
+            if (isRecord(doc.span)) {
+                const from = numberAt(doc.span, 'fromMs');
+                const to = numberAt(doc.span, 'toMs');
+                spanFrom = spanFrom === null ? from : Math.min(spanFrom, from);
+                spanTo = spanTo === null ? to : Math.max(spanTo, to);
+                spanCalls += numberAt(doc.span, 'calls');
+            }
+            continue;
+        }
+        // --- this contributor, as it will be listed ---------------------------
+        const totals = isRecord(doc.total) ? doc.total : {};
+        const ownUnpriced = isRecord(doc.unpriced) ? doc.unpriced : {};
+        const ownCoverage = isRecord(doc.fieldCoverage) ? doc.fieldCoverage : {};
+        const span = isRecord(doc.span)
+            ? {
+                fromMs: numberAt(doc.span, 'fromMs'),
+                toMs: numberAt(doc.span, 'toMs'),
+                calls: numberAt(doc.span, 'calls'),
+            }
+            : null;
+        if (span !== null) {
+            spanFrom = spanFrom === null ? span.fromMs : Math.min(spanFrom, span.fromMs);
+            spanTo = spanTo === null ? span.toMs : Math.max(spanTo, span.toMs);
+            spanCalls += span.calls;
+        }
+        const gaps = [];
+        const skipped = Array.isArray(doc.skippedLines) ? doc.skippedLines.length : 0;
+        if (skipped > 0) {
+            gaps.push({
+                kind: 'unreadable-lines',
+                // The positions are deliberately absent: a line number is an offset
+                // into a file only this contributor has, and a merged list of them
+                // points at nothing.
+                detail: `${skipped} line${skipped === 1 ? '' : 's'} of this contributor's log could not be read`,
+                usd: null,
+                calls: null,
+            });
+        }
+        const unpricedCalls = numberAt(ownUnpriced, 'calls');
+        if (unpricedCalls > 0) {
+            gaps.push({
+                kind: 'unpriced-calls',
+                detail: `${unpricedCalls} call${unpricedCalls === 1 ? '' : 's'} ran on a model the catalogue does not price`,
+                usd: null,
+                calls: unpricedCalls,
+            });
+        }
+        const parsedRecords = numberAt(ownCoverage, 'parsed');
+        const dated = numberAt(ownCoverage, 'ts');
+        if (span === null) {
+            gaps.push({
+                kind: 'no-clock',
+                detail: 'no record carried a timestamp, so none of this contributor is in any day',
+                usd: null,
+                calls: null,
+            });
+            cannotSay.add('contributor-without-clock');
+        }
+        else if (parsedRecords > 0 && dated < parsedRecords) {
+            gaps.push({
+                kind: 'partial-clock',
+                detail: `${parsedRecords - dated} of ${parsedRecords} records carried no timestamp`,
+                usd: null,
+                calls: parsedRecords - dated,
+            });
+        }
+        if (parsedRecords > 0 && numberAt(ownCoverage, 'session') === 0) {
+            gaps.push({
+                kind: 'no-sessions',
+                detail: 'no record carried a session, so this contributor brings no conversation findings',
+                usd: null,
+                calls: null,
+            });
+        }
+        if (parsedRecords > 0 && numberAt(ownCoverage, 'label') === 0) {
+            gaps.push({
+                kind: 'no-labels',
+                detail: 'no record carried a label, so this contributor is unlabelled in every per-workload figure',
+                usd: null,
+                calls: null,
+            });
+        }
+        if (isRecord(doc.duplicateLines)) {
+            const count = numberAt(doc.duplicateLines, 'count');
+            if (count > 0) {
+                gaps.push({
+                    kind: 'duplicate-lines',
+                    detail: `${count} line${count === 1 ? '' : 's'} of this contributor's log repeated an earlier line exactly`,
+                    usd: numberAt(doc.duplicateLines, 'usd'),
+                    calls: count,
+                });
+            }
+        }
+        /**
+         * The window this contributor asked for, if it asked for one.
+         *
+         * `timeWindow` is present in a profile document only when the profile was
+         * run with `--since` or `--until`, so its absence is the ordinary case and
+         * is an answer rather than a defect: nobody claimed a period, and the span
+         * is all that is known.
+         */
+        const window = isRecord(doc.timeWindow) ? doc.timeWindow : null;
+        const claimed = window === null
+            ? null
+            : {
+                sinceMs: typeof window.sinceMs === 'number' ? window.sinceMs : null,
+                untilMs: typeof window.untilMs === 'number' ? window.untilMs : null,
+            };
+        if (claimed === null) {
+            cannotSay.add('no-claimed-period');
+        }
+        else if (claimed.sinceMs === null || claimed.untilMs === null) {
+            cannotSay.add('claim-not-bounded');
+        }
+        /** The days this contributor itself put spend on — its own bucketing. */
+        const ownDays = new Set();
+        if (Array.isArray(doc.spendByDay)) {
+            for (const row of doc.spendByDay) {
+                if (!isRecord(row))
+                    continue;
+                const day = asString(row.day);
+                if (day !== null)
+                    ownDays.add(day);
+            }
+        }
+        const silence = claimed === null ? null : silenceIn(claimed, ownDays);
+        if (claimed !== null &&
+            claimed.sinceMs !== null &&
+            claimed.untilMs !== null &&
+            silence === null) {
+            // Bounded, in order, and still not walked: it was longer than the bound.
+            cannotSay.add('claim-too-long-to-enumerate');
+        }
+        if (silence !== null && silence.days > 0) {
+            cannotSay.add('silence-inside-a-claim');
+            gaps.push({
+                kind: 'silent-days',
+                detail: `${silence.days} day${silence.days === 1 ? '' : 's'} inside the window this contributor asked for recorded nothing`,
+                usd: null,
+                calls: null,
+            });
+        }
+        if (claimed?.sinceMs != null && claimed.untilMs != null) {
+            claimFrom = claimFrom === null ? claimed.sinceMs : Math.min(claimFrom, claimed.sinceMs);
+            claimTo = claimTo === null ? claimed.untilMs : Math.max(claimTo, claimed.untilMs);
+            claimants += 1;
+        }
+        contributors.push({
+            name: input.name,
+            via: null,
+            totalUsd: numberAt(totals, 'totalUsd'),
+            calls: numberAt(totals, 'calls'),
+            span,
+            spanDays: span === null ? null : (span.toMs - span.fromMs) / 86_400_000,
+            claimed,
+            silence,
+            undatedExcluded: window === null ? null : numberAt(window, 'undatedExcluded'),
+            gaps,
+        });
+    }
+    if (contributors.length > 1)
+        cannotSay.add('overlap-invisible');
+    if (unknownFields.size > 0)
+        cannotSay.add('unknown-fields-dropped');
+    /**
+     * Mismatched spans, on the rule `fleetRollup` already uses: more than a day
+     * apart in length, or one contributor with a clock beside one without. A
+     * share of a sum stays valid either way; reading it as a comparison of
+     * *rates* is the mistake this names.
+     */
+    const spanLengths = contributors.map((contributor) => contributor.spanDays);
+    const known = spanLengths.filter((days_) => days_ !== null);
+    if ((spanLengths.some((length) => length === null) && known.length > 0) ||
+        (known.length > 1 && Math.max(...known) - Math.min(...known) > 1)) {
+        cannotSay.add('mismatched-spans');
+    }
+    /**
+     * Contributor names that turn up more than once.
+     *
+     * Handing over both a roll-up and one of the machines inside it counts that
+     * machine's money twice — and unlike the identical-document check, this one
+     * can see it: the two documents differ, but the name does not. Named and
+     * never subtracted, because two teams genuinely running `api.json` is
+     * possible and removing money to decide between them is the repair this tool
+     * does not make.
+     */
+    const timesSeen = new Map();
+    for (const contributor of contributors) {
+        timesSeen.set(contributor.name, (timesSeen.get(contributor.name) ?? 0) + 1);
+    }
+    const repeatedContributors = [...timesSeen.entries()]
+        .filter(([, times]) => times > 1)
+        .map(([name]) => name)
+        .sort();
+    if (repeatedContributors.length > 0)
+        cannotSay.add('contributor-named-twice');
+    const notMerged = PER_RECORD_FINDINGS.filter((entry) => findingsPresentIn.has(entry.field)).map((entry) => ({
+        finding: entry.finding,
+        because: entry.because,
+        presentIn: findingsPresentIn.get(entry.field) ?? [],
+    }));
+    if (cannotSay.has('day-top-label-unknown')) {
+        const shared = [...days.values()].filter((bucket) => bucket.from.size > 1);
+        notMerged.push({
+            finding: "a day's dearest label",
+            because: 'each contributor knows its own, and the merged answer needs the per-label-per-day spend that no document carries',
+            presentIn: [...new Set(shared.flatMap((bucket) => [...bucket.from]))].sort(),
+        });
+    }
+    // Findings an inner roll-up already refused to merge do not become mergeable
+    // by being handed on. Merged by their own text so the same finding from two
+    // roll-ups is one entry naming both sets of contributors.
+    for (const [finding, entry] of nestedFindings) {
+        const existing = notMerged.find((row) => row.finding === finding);
+        if (existing === undefined) {
+            notMerged.push({ finding, because: entry.because, presentIn: [...entry.presentIn].sort() });
+            continue;
+        }
+        for (const who of entry.presentIn) {
+            if (!existing.presentIn.includes(who))
+                existing.presentIn.push(who);
+        }
+        existing.presentIn.sort();
+    }
+    if (unknownFields.size > 0) {
+        notMerged.push({
+            finding: `numeric fields this version cannot combine: ${[...unknownFields].sort().join(', ')}`,
+            because: 'a field added after this roll-up was written may be a sum, a maximum or a ratio, and combining it the wrong way is worse than leaving it out',
+            presentIn: [],
+        });
+    }
+    return {
+        schemaVersion: 1,
+        contributors,
+        rejected,
+        identicalContributions: {
+            groups: [...[...seenText.values()].filter((names) => names.length > 1), ...nestedIdentical],
+            usd: identicalUsd,
+        },
+        total,
+        unpriced,
+        unpricedModels: [...unpricedModels].sort(),
+        byLabel: byMoney([...labels.values()].map((slice) => ({ label: slice.label ?? '', breakdown: slice.breakdown })), (row) => row.breakdown.totalUsd),
+        byModel: byMoney([...models.values()].map((slice) => ({ model: slice.model ?? '', breakdown: slice.breakdown })), (row) => row.breakdown.totalUsd),
+        byLabelAndModel: byMoney([...pairs.values()].map((slice) => ({
+            label: slice.label ?? '',
+            model: slice.model ?? '',
+            breakdown: slice.breakdown,
+        })), (row) => row.breakdown.totalUsd),
+        spendByDay: [...days.entries()]
+            .sort((a, b) => (a[0] < b[0] ? -1 : 1))
+            .map(([day, bucket]) => ({
+            day,
+            usd: bucket.usd,
+            calls: bucket.calls,
+            contributors: bucket.contributors,
+            byModel: byMoney([...bucket.models.entries()].map(([model, figures]) => ({ model, ...figures })), (row) => row.usd),
+            topLabel: bucket.topLabel,
+            topLabelUsd: bucket.topLabelUsd,
+        })),
+        span: spanFrom === null || spanTo === null ? null : { fromMs: spanFrom, toMs: spanTo, calls: spanCalls },
+        claimedSpan: claimFrom === null || claimTo === null
+            ? null
+            : { fromMs: claimFrom, toMs: claimTo, contributors: claimants },
+        fieldCoverage: coverage,
+        outcomeTally: {
+            byValue: byMoney([...outcomeValues.entries()].map(([value, figures]) => ({ value, ...figures })), (row) => row.usd),
+            recorded: outcome.recorded,
+            parsed: outcome.parsed,
+            unrecordedUsd: outcome.unrecordedUsd,
+        },
+        duplicateLines,
+        repeatedContributors,
+        notMerged,
+        cannotSay: [...cannotSay].sort(),
+    };
+}
+//# sourceMappingURL=rollup.js.map