tumwater 0.4.1 → 0.4.3

package/dist/src/report/report-render.js

@@ -1,12 +1,12 @@
 import { addTo, rankCountEntries, sortByValueDesc } from "../collections.js";
+import { foldBaseRoles } from "./report-fold.js";
 import { compactTokens, usd } from "../text/format.js";
 import { durationLabel } from "../cli/cli-args.js";
-import { boundedWindowLine, monthDay, reportWindow, sinceWindowLine } from "../text/datetime.js";
+import { monthDay, reportWindow } from "../text/datetime.js";
 import { eventsRotationLabel } from "../events/events.js";
 import { SPARSE_WINDOW_NOTE } from "../events/event-window.js";
 import { shortSpanPhrase } from "../text/phrases.js";
 import { markdownTable } from "../text/markdown.js";
-import { baseRoleOf } from "../roles/runner-ids.js";
 import { backendDisplayName } from "../agent/backend-traits.js";
 /** Bar width for one day: up to 20 blocks scaled to the window's max tokensOut —
  * round(20·v/max), min 1 when v > 0. */
@@ -19,7 +19,7 @@ function barWidth(v, max) {
  * collections.ts's rank rule, so the report cannot drift from the other counters that rank the
  * same way.
  * Callers filter/format the ranked pairs. */
-function rankedRoleMap(totals) {
+export function rankedRoleMap(totals) {
     return rankCountEntries(Object.entries(totals));
 }
 /** Window totals per role: fold the per-day role maps (any `Record<string, number>` day field,
@@ -35,7 +35,7 @@ function rankedRoleTotals(series, pick) {
 }
 /** One "**Label:** role — n · role — n" Markdown line from already-ranked pairs; an empty
  * pair list (an all-zero window) renders "-". fmt formats each role's number. */
-function rankedRoleLine(label, pairs, fmt) {
+export function rankedRoleLine(label, pairs, fmt) {
     return `**${label}:** ${pairs.length === 0 ? "-" : pairs.map(([r, n]) => `${r} — ${fmt(n)}`).join(" · ")}`;
 }
 /** The "**Prompt tokens by role:**" line — each role's prompt-token total and, when its
@@ -43,7 +43,7 @@ function rankedRoleLine(label, pairs, fmt) {
  * — with zero-total roles omitted (the same zero-means-absent rule the sibling lines apply)
  * and "-" when no role sent a prompt. `prompt` arrives already ranked (prompt desc then
  * name asc). The one home of the share format, so the day and `--since` lines cannot drift. */
-function promptTokensLine(prompt, cache) {
+export function promptTokensLine(prompt, cache) {
     const cacheByRole = new Map(cache);
     const cells = prompt
         .filter(([, n]) => n > 0)
@@ -58,9 +58,21 @@ function promptTokensLine(prompt, cache) {
  * unfiltered lines. fmt formats each role's number (default String for count lines; pass
  * usd/compactTokens for spend/token lines). All the "X by role" lines share this filter-rule
  * home so the zero-means-render-dash guard cannot drift between the --since and day renders. */
-function pushRankedRoleLine(lines, label, pairs, fmt = String) {
+export function pushRankedRoleLine(lines, label, pairs, fmt = String) {
     lines.push(rankedRoleLine(label, pairs.filter(([, n]) => n > 0), fmt));
 }
+/** Push a "**Label:** …" ranked-role line only when some role carries a positive value — the
+ * zero-means-absent idiom: a window or day with no evidence prints no line at all, unlike
+ * pushRankedRoleLine's always-printed "-", because "no model ran" is an absence, not a zero
+ * (the same reason pushProviderCostLines and pushDayCameoLine stay silent when empty). fmt
+ * formats each role's number (default String for count lines). Shared by the since and day
+ * renders so the filter-and-if-present guard cannot drift between them — a field that flipped
+ * one render to always-print would show an absent "-" line in one report but not the other. */
+export function pushPresentRankedLine(lines, label, pairs, fmt = String) {
+    const present = pairs.filter(([, n]) => n > 0);
+    if (present.length > 0)
+        lines.push(rankedRoleLine(label, present, fmt));
+}
 /** The per-day cameo line of the team day report — "MMM D <cell>" cells for each day that
  * carries a value, joined under a bold title, or undefined when no day has one (zero means
  * absent). The one home of that cameo rendering, shared by the per-day medians, the red-check
@@ -90,7 +102,7 @@ function pushDayCameoLine(lines, series, title, pick, fmt = shortSpanPhrase) {
  * renders. Zero-means-absent: a provider with no spend prints no line, and both lanes format
  * with usd so the day and --since windows cannot drift (the --since path ranks via rankedRoleMap,
  * the day path via rankedRoleTotals). */
-function pushProviderCostLines(lines, rankCost, rankNotional) {
+export function pushProviderCostLines(lines, rankCost, rankNotional) {
     const providers = rankCost().filter(([, c]) => c > 0);
     if (providers.length > 0)
         lines.push(rankedRoleLine("Cost by provider", providers, usd));
@@ -159,7 +171,7 @@ const ROLE_SCOPE_NOTE = "role scope: merge runs and backlog tallies (features do
  * nonzero (zero means absent, so an API-only or merge-free window renders as before), and the
  * role-scope note when the report is scoped. One home so the day report and the --since window
  * cannot drift on the order, the omission predicates, or the scope note. */
-function pushReportSummary(lines, t, tail = "", scoped = false) {
+export function pushReportSummary(lines, t, tail = "", scoped = false) {
     lines.push(totalsLine(t, tail));
     if (t.mergeRuns > 0)
         lines.push(mergeShareLine(t));
@@ -168,160 +180,13 @@ function pushReportSummary(lines, t, tail = "", scoped = false) {
     if (scoped)
         lines.push(ROLE_SCOPE_NOTE);
 }
-/** Render a trailing-window totals report as Markdown — the aggregate sibling of the
- * `logs --since` raw stream ("how much" here, "what exactly" there). Pure function of
- * SinceReport: no I/O, no clock reads (the window line's local time is rendered from the
- * collector's captured cutoff, so the printed window matches the aggregated one). */
-export function renderSinceReportMarkdown(data) {
-    const lines = [];
-    lines.push("# tumwater usage report");
-    lines.push("");
-    lines.push(data.untilMs !== undefined && data.toIso !== undefined
-        ? boundedWindowLine(durationLabel(data.sinceMs), durationLabel(data.untilMs), data.fromIso, data.toIso)
-        : sinceWindowLine(durationLabel(data.sinceMs), data.fromIso));
-    if (data.role !== undefined)
-        lines.push(`role: ${data.role}`);
-    lines.push("");
-    const t = data.totals;
-    // Same totals voice as the day report, minus the features/bugs and filing cells: those tallies
-    // come from day-granular backlog-file dates that cannot subdivide a sub-day window, so the
-    // final line below states the omission instead of showing a day-rounded number.
-    pushReportSummary(lines, t, "", data.role !== undefined);
-    lines.push("");
-    lines.push(rankedRoleLine("Runs by role", rankedRoleMap(data.runsByRole), String));
-    // Same breakdown for token spend: ranked by tokens desc then name asc, zero-token roles
-    // omitted — an all-zero window renders "-" like the other lines. Output tokens are the
-    // resource the budget charges, so this is the line an operator reads to find which role's
-    // prompt loop burned the window's tokens.
-    pushRankedRoleLine(lines, "Tokens by role", rankedRoleMap(data.tokensByRole), compactTokens);
-    // The prompt side of the same breakdown, straight after the output-token line: how many
-    // prompt tokens each role sent and the share of them its backend served from cache — the
-    // input side of the bill an operator cannot see from Tokens by role. Zero-prompt roles are
-    // omitted, and an all-zero window renders "-" like the sibling lines.
-    lines.push(promptTokensLine(rankedRoleMap(data.promptTokensByRole ?? {}), rankedRoleMap(data.cacheReadTokensByRole ?? {})));
-    // Same breakdown for spend: ranked by spend desc then name asc, zero-spend roles omitted —
-    // an all-zero window renders "-" like the runs line.
-    pushRankedRoleLine(lines, "Cost by role", rankedRoleMap(data.costByRole), usd);
-    // The same breakdown per PROVIDER (plans: per-provider spend), gated to the team report
-    // like its day sibling. SinceReport.costByProvider is always present (empty when none), so
-    // the zero-means-absent gate prints no line for a window with no provider spend.
-    if (data.role === undefined) {
-        pushProviderCostLines(lines, () => rankedRoleMap(data.costByProvider), () => rankedRoleMap(data.notionalByProvider));
-        // The same breakdown per MODEL (each run_start's agent-qualified selector — the model a
-        // team mixing providers, per-role overrides and fallbacks actually ran on), gated to the
-        // team report like the provider lines: a model is not a role, so a role-scoped window
-        // omits it. SinceReport.runsByModel is always present, so a window with no modelled
-        // start prints no line (keeping a model-less day's output unchanged), exactly as the
-        // provider lines stay absent when no provider spent.
-        const modelPairs = rankedRoleMap(data.runsByModel).filter(([, n]) => n > 0);
-        if (modelPairs.length > 0)
-            lines.push(rankedRoleLine("Runs by model", modelPairs, String));
-    }
-    // Main's red wall-clock over the window (main's own, not any role's — a role-scoped
-    // collector carries 0, so this never prints for a scoped window). Zero-absent: no line for
-    // a window main was never red.
-    if (data.mainRedMs > 0)
-        lines.push(`**Main red:** ${durationLabel(data.mainRedMs)}`);
-    // The same "what kept main red" detail named by failing test — which tests main's own red
-    // checks named over the window. Team-only like main's red time, so a role-scoped window
-    // omits it; zero-absent: no line when the window's red checks named no test.
-    if (data.role === undefined) {
-        const mainRedByTest = rankedRoleMap(data.mainRedByTest ?? {}).filter(([, n]) => n > 0);
-        if (mainRedByTest.length > 0)
-            lines.push(rankedRoleLine("Main red by test", mainRedByTest, String));
-        // The same "what kept main red" detail named by merge — the landed merges the watch's
-        // own main_culprit events blamed, mirroring the failing-test line right above. Team-only
-        // like main's red time and zero-absent: no line when the window blamed no merge.
-        const mainRedByCulprit = rankedRoleMap(data.mainRedByCulprit ?? {}).filter(([, n]) => n > 0);
-        if (mainRedByCulprit.length > 0)
-            lines.push(rankedRoleLine("Main red by merge", mainRedByCulprit, String));
-    }
-    // The same breakdown for review friction: rejections per role from review_rejected events;
-    // a window with none renders "-" like the other lines. The post-merge line is the
-    // afterMerge: true subset — rejections that reached an already-merged commit.
-    pushRankedRoleLine(lines, "Rejections by role", rankedRoleMap(data.rejectionsByRole));
-    pushRankedRoleLine(lines, "Post-merge rejections by role", rankedRoleMap(data.postMergeRejectionsByRole));
-    pushRankedRoleLine(lines, "Revisions by role", rankedRoleMap(data.revisionsByRole));
-    pushRankedRoleLine(lines, "Refusals by role", rankedRoleMap(data.refusalsByRole));
-    // The same breakdown for outright failures: error-class run_ends per role under the
-    // digest's OUTCOME_CLASS — the runs that burned agent time and merged nothing without
-    // going through review, which rejections/revisions would miss entirely. A window with
-    // none renders "-" like the other lines.
-    pushRankedRoleLine(lines, "Failed runs by role", rankedRoleMap(data.failedRunsByRole));
-    pushRankedRoleLine(lines, "Fallbacks by role", rankedRoleMap(data.fallbacksByRole));
-    pushRankedRoleLine(lines, "Image reroutes by role", rankedRoleMap(data.imageReroutesByRole));
-    // Deferred maintenance runs per reason code, the --since twin of the day render's line:
-    // how many due maintenance runs stood down and why (backlog / no-work / plans-full).
-    // Gated to the team report — a reason is not a role, so a role-scoped window omits it.
-    // Zero-means-absent: a window with no deferral prints no line.
-    if (data.role === undefined) {
-        const deferred = rankedRoleMap(data.deferredByReason ?? {}).filter(([, n]) => n > 0);
-        if (deferred.length > 0)
-            lines.push(rankedRoleLine("Deferred runs by reason", deferred, String));
-    }
-    // The merged-commits split by base role, matching the day render's unfiltered line: the
-    // window's totals.commits carries the count; this line says which role's commits it was.
-    lines.push(rankedRoleLine("Commits by role", rankedRoleMap(data.commitsByRole), String));
-    // The merged-outcomes split by base role, mirroring the day render's line: which roles'
-    // changes reach main and which bounce off the gate (merge_failed). Gated to the team
-    // report — a role-scoped window omits merge (ROLE_SCOPE_NOTE), so the per-role
-    // attribution would contradict it. Zero-means-absent: the failures line prints only when
-    // some role has one; a merge-free window renders `-` like the other lines.
-    if (data.role === undefined) {
-        lines.push(rankedRoleLine("Merged by role", rankedRoleMap(data.mergedByRole), String));
-        const mergeFailures = rankedRoleMap(data.mergeFailedByRole).filter(([, n]) => n > 0);
-        if (mergeFailures.length > 0)
-            lines.push(rankedRoleLine("Merge failures by role", mergeFailures, String));
-        // WHY the window's merges failed, from each merge_failed's result code — the day
-        // report's reason twin of the role line above, so an operator can tell a review
-        // rejection (fix the change) from a conflict/block (rebase) from a shutdown abort
-        // (capacity). Ranked the same way (count desc then code asc), reason-free only.
-        const mergeFailureReasons = rankedRoleMap(data.mergeFailedByReason ?? {}).filter(([, n]) => n > 0);
-        if (mergeFailureReasons.length > 0)
-            lines.push(rankedRoleLine("Merge failures by reason", mergeFailureReasons, String));
-    }
-    // Spend per merged commit, the --since twin of the day render's `Cost per commit:` line:
-    // costByRole is keyed by role id (instances not folded, so `feature-2` joins `feature`),
-    // commitsByRole is already base-role keyed. Prints for a spend-free window as `-` and for a
-    // role-scoped window from its scoped maps, matching the day render.
-    lines.push(costPerCommitLine("Cost per commit", costPerCommitPairsFrom(foldBaseRoles(data.costByRole), data.commitsByRole)));
-    // Subscription spend is notional: its own line, only when the window has any — the same
-    // conditional/filtered `usd` form the day render's "Estimated by role" uses.
-    if (data.notionalByRole !== undefined) {
-        pushRankedRoleLine(lines, "Estimated by role", rankedRoleMap(data.notionalByRole), usd);
-        // The day render's `Estimated per commit:` twin, after `Estimated by role`, from the same
-        // notionalByRole source folded to base roles and the base-keyed commitsByRole.
-        lines.push(costPerCommitLine("Estimated per commit", costPerCommitPairsFrom(foldBaseRoles(data.notionalByRole), data.commitsByRole)));
-    }
-    lines.push("");
-    // Exactly one final line, chosen by the collector's coverage proof: either a hedged note
-    // that stays true whenever it prints (the oldest retained event lies inside the window —
-    // whether from rotation or a log born inside the window), or the one-time statement of the
-    // backlog-tally omission. A flat "rotated out" claim would be false for a log that never
-    // had the older events, so the wording names only what is provably the case. A role-scoped
-    // report already states the omission in ROLE_SCOPE_NOTE, so it does not repeat the --days
-    // pointer, which would imply a scoped day report shows the tallies it too omits.
-    if (!data.coversFullWindow)
-        lines.push(SPARSE_WINDOW_NOTE);
-    else if (data.role === undefined)
-        lines.push("backlog tallies (features done / bugs fixed / plans added / bugs filed) need the day report (--days)");
-    return lines.join("\n");
-}
-/** Fold every key of a per-role-id map through its base role, so `feature-2` joins `feature`.
- * The same fold the day caller does per day, applied to an already-aggregated window map. */
-function foldBaseRoles(map) {
-    const folded = {};
-    for (const [id, c] of Object.entries(map))
-        addTo(folded, baseRoleOf(id), c);
-    return folded;
-}
 /** Rank one cost map against a base-keyed commits map into cost-per-commit output: the shared
  * core of the day and --since cost-per-commit lines. `cost` is expected base-role keyed (the
  * day caller folds per day, the --since caller via `foldBaseRoles`); commits are base-role
  * keyed. `merged` is [role, cost per commit, commits] for roles with both, ranked by cost per
  * commit desc then name asc; `idle` is roles that spent and merged nothing, ranked by spend.
  * A role with commits but no spend appears in neither list. */
-function costPerCommitPairsFrom(cost, commits) {
+export function costPerCommitPairsFrom(cost, commits) {
     const mergeDone = [];
     const idleCost = [];
     for (const [role, c] of Object.entries(cost)) {
@@ -336,24 +201,26 @@ function costPerCommitPairsFrom(cost, commits) {
     sortByValueDesc(mergeDone);
     return { mergeDone, idle: rankCountEntries(idleCost) };
 }
-/** The day caller of the cost-per-commit core: fold each day's role-id-keyed spend map through
- * its base role (so `feature-2` joins `feature`) and aggregate the base-keyed commitsByRole,
- * then hand both to `costPerCommitPairsFrom`. `pick` selects the per-role-id spend map; merge
- * spend (the reviewer's) and notional subscription spend stay out by default, matching
- * `**Cost by role:**`. */
+/** The day caller of the cost-per-commit core: aggregate each day's role-id-keyed spend map
+ * under its raw role id, then fold the whole map through its base role (so `feature-2` joins
+ * `feature`) once via the shared foldBaseRoles — addition is associative and the fold is
+ * deterministic, so this is the same total the --since caller's single fold reaches — and
+ * aggregate the base-keyed commitsByRole, then hand both to `costPerCommitPairsFrom`. `pick`
+ * selects the per-role-id spend map; merge spend (the reviewer's) and notional subscription
+ * spend stay out by default, matching `**Cost by role:**`. */
 function costPerCommitPairs(series, pick = (d) => d.costByRole) {
     const cost = {};
     const commits = {};
     for (const d of series) {
         for (const [id, c] of Object.entries(pick(d)))
-            addTo(cost, baseRoleOf(id), c);
+            addTo(cost, id, c);
         for (const [role, n] of Object.entries(d.commitsByRole ?? {}))
             addTo(commits, role, n);
     }
-    return costPerCommitPairsFrom(cost, commits);
+    return costPerCommitPairsFrom(foldBaseRoles(cost), commits);
 }
 /** One `**<label>:** …` line from costPerCommitPairs output; `-` when there is nothing. */
-function costPerCommitLine(label, pairs) {
+export function costPerCommitLine(label, pairs) {
     const parts = [
         ...pairs.mergeDone.map(([r, per, n]) => `${r} — ${usd(per)} (${n})`),
         ...pairs.idle.map(([r, c]) => `${r} — ${usd(c)}, no commits`),
@@ -424,9 +291,7 @@ function pushReportProviderLines(lines, data) {
         // omits it (ROLE_SCOPE_NOTE covers the omission), and a window with no modelled start
         // prints no line (keeping a model-less day's output unchanged), exactly as the provider
         // lines stay absent when no provider spent. Ranked and formatted like Cost by role.
-        const modelPairs = rankedRoleTotals(data.series, (d) => d.runsByModel ?? {}).filter(([, n]) => n > 0);
-        if (modelPairs.length > 0)
-            lines.push(rankedRoleLine("Runs by model", modelPairs, String));
+        pushPresentRankedLine(lines, "Runs by model", rankedRoleTotals(data.series, (d) => d.runsByModel ?? {}));
     }
 }
 /** The per-role review-friction and outright-failure lines. */
@@ -443,7 +308,6 @@ function pushReportFrictionLines(lines, data) {
     // through review, which rejections/revisions would miss entirely. Zero-means-absent, so a
     // failure-free window renders no line and an all-zero window renders "-" like the others.
     pushRankedRoleLine(lines, "Failed runs by role", rankedRoleTotals(data.series, (d) => d.failedRunsByRole ?? {}));
-    pushRankedRoleLine(lines, "Fallbacks by role", rankedRoleTotals(data.series, (d) => d.fallbacksByRole ?? {}));
     pushRankedRoleLine(lines, "Image reroutes by role", rankedRoleTotals(data.series, (d) => d.imageReroutesByRole ?? {}));
 }
 /** The team-only deferred-runs-by-reason line. */
@@ -454,9 +318,7 @@ function pushReportDeferralLines(lines, data) {
     // reason is not a role (ROLE_SCOPE_NOTE covers the omission). Zero-means-absent: a window
     // with no deferral prints no line, so a deferral-free day's output is unchanged.
     if (data.role === undefined) {
-        const deferred = rankedRoleTotals(data.series, (d) => d.deferredByReason ?? {}).filter(([, n]) => n > 0);
-        if (deferred.length > 0)
-            lines.push(rankedRoleLine("Deferred runs by reason", deferred, String));
+        pushPresentRankedLine(lines, "Deferred runs by reason", rankedRoleTotals(data.series, (d) => d.deferredByReason ?? {}));
     }
 }
 /** The Commits-by-role line plus the team-only merge/main-red/cameo block. */
@@ -474,14 +336,10 @@ function pushReportMergeLines(lines, data) {
     if (data.role === undefined) {
         const mergeDone = rankedRoleTotals(data.series, (d) => d.mergedByRole ?? {});
         lines.push(rankedRoleLine("Merged by role", mergeDone, String));
-        const mergeFailures = rankedRoleTotals(data.series, (d) => d.mergeFailedByRole ?? {}).filter(([, n]) => n > 0);
-        if (mergeFailures.length > 0)
-            lines.push(rankedRoleLine("Merge failures by role", mergeFailures, String));
+        pushPresentRankedLine(lines, "Merge failures by role", rankedRoleTotals(data.series, (d) => d.mergeFailedByRole ?? {}));
         // The --since reason twin, folded across the series the same way; a reason-free window
         // prints no line, so its output is byte-for-byte unchanged.
-        const mergeFailureReasons = rankedRoleTotals(data.series, (d) => d.mergeFailedByReason ?? {}).filter(([, n]) => n > 0);
-        if (mergeFailureReasons.length > 0)
-            lines.push(rankedRoleLine("Merge failures by reason", mergeFailureReasons, String));
+        pushPresentRankedLine(lines, "Merge failures by reason", rankedRoleTotals(data.series, (d) => d.mergeFailedByReason ?? {}));
         // Per-day median passing check time, so a suite slowing over days shows; days without a
         // check are left out, and no line prints when no day has one (zero means absent).
         pushDayCameoLine(lines, data.series, "Merge check median", (d) => d.checkMedianMs);
@@ -495,15 +353,11 @@ function pushReportMergeLines(lines, data) {
         // The day twin of the --since window's totals line: the same tests ranked across the
         // series' per-day main-red maps (Main red by test). Zero-absent: no line when no day
         // named a failing test.
-        const mainRedByTest = rankedRoleTotals(data.series, (d) => d.mainRedByTest ?? {}).filter(([, n]) => n > 0);
-        if (mainRedByTest.length > 0)
-            lines.push(rankedRoleLine("Main red by test", mainRedByTest, String));
+        pushPresentRankedLine(lines, "Main red by test", rankedRoleTotals(data.series, (d) => d.mainRedByTest ?? {}));
         // The day twin of the --since window's merges line: the same culprits ranked across the
         // series' per-day main-red maps (Main red by merge). Zero-absent: no line when no day
         // blamed a merge.
-        const mainRedByCulprit = rankedRoleTotals(data.series, (d) => d.mainRedByCulprit ?? {}).filter(([, n]) => n > 0);
-        if (mainRedByCulprit.length > 0)
-            lines.push(rankedRoleLine("Main red by merge", mainRedByCulprit, String));
+        pushPresentRankedLine(lines, "Main red by merge", rankedRoleTotals(data.series, (d) => d.mainRedByCulprit ?? {}));
         pushDayCameoLine(lines, data.series, "Merge wait median", (d) => d.mergeWaitMedianMs);
         // How long the merge slot itself held each change it landed, beside the merge-wait median:
         // the queue backlog (merge wait minus slot time) apart from the slot's own review/check/

package/dist/src/report/report-since-data.js

@@ -0,0 +1,219 @@
+/** The trailing-window half of the usage report's collection: read the harness's event log
+ * over the `sinceMs` window and distill it into a `SinceReport` — run/token/commit/cost
+ * totals plus features-done/cost maps and main-red tallies. Split out of
+ * src/report/report-data.ts (which keeps the per-day `ReportData` series collector) so each
+ * window collector owns its own helpers and its own shape: the day collector's zero-filled
+ * series and backlog-file reads have no place in a window totals view, and the two change
+ * for different reasons. The event-log folding both collectors share lives in
+ * src/report/report-usage-fold.ts (foldUsageEvent) and src/report/report-fold.ts (the windowed
+ * cache and scope helpers), the shapes they produce in src/report/report-types.ts, and the
+ * Markdown rendering in src/report/report-since-render.ts (which imports the shared formatting
+ * voice from src/report/report-render.ts). */
+import { assertReportSinceMs, eventWindowCovers, readWindowEvents, sinceWindowTiming } from "../events/event-window.js";
+import { dayKey } from "../text/datetime.js";
+import { addTo } from "../collections.js";
+import { nonemptyObj, roleSum, scopeBases, scopedByRole, zeroCommitCounts, zeroMergeCounts, } from "./report-fold.js";
+import { foldUsageEvent } from "./report-usage-fold.js";
+import { mainRedCulpritsByDay, mainRedFailingTestsByDay, mainRedMinutesByDay } from "./report-main-red.js";
+/** Aggregate team usage over the trailing `sinceMs` window ending now (or `untilMs` ago, which
+ * drops events at or after that end; `coversFullWindow` still judges the far edge
+ * only), from the event log only (run_end/merged — see SinceReport for why the backlog files
+ * are not read). Kept a
+ * separate function rather than a `collectReport` variant flag: the day collector's
+ * zero-filled series and backlog-file reads have no place in a window totals view. */
+export function collectReportSince(root, sinceMs, role, untilMs) {
+    assertReportSinceMs(sinceMs);
+    const { now, cutoff, end, slice } = sinceWindowTiming(sinceMs, untilMs);
+    const { raw, acc } = foldSinceWindow(root, cutoff, now, end, untilMs);
+    // The empty-window branch of the shared proof matters here: with no retained events nothing
+    // can have rotated away, and printing a rotation note over a fresh install would claim a
+    // history that never existed. When neither proof holds, the oldest retained event lies inside
+    // the window and the render notes the possible truncation.
+    const coversFullWindow = eventWindowCovers(raw, cutoff);
+    // Role scope: every map and total below derives from the fold's per-role maps for the named
+    // base roles alone — merge usage (the merge slot's, not the role's) and the team-only
+    // fields stay out, so a scoped --since report sums exactly the same events the scoped day
+    // report would. The scope is the base roles, so instances (`feature-2`) aggregate into their
+    // group as the cap does.
+    const bases = scopeBases(role);
+    return {
+        ...slice,
+        ...(bases === undefined ? {} : { role: bases.join(",") }),
+        totals: sinceScopedTotals(acc, bases),
+        ...sinceRoleMaps(acc, bases),
+        // Main's red time is main's own (G1's rule), not any role's, so a role-scoped window
+        // carries 0 — the type's always-present default for the team-only field.
+        mainRedMs: bases === undefined
+            ? [...mainRedMinutesByDay(raw.events, cutoff, end).values()].reduce((a, b) => a + b, 0)
+            : 0,
+        ...nonemptyObj("mainRedByTest", sinceMainRedByTest(raw, cutoff, end, bases)),
+        ...nonemptyObj("mainRedByCulprit", sinceMainRedByCulprit(raw, cutoff, end, bases)),
+        coversFullWindow,
+    };
+}
+/** The window's event read and fold, one function so the read happens exactly once per window
+ * and every downstream builder — the coverage proof and the main-red by-test/by-culprit maps
+ * — consumes the same `raw`. `raw` is the one day-keyed log read the whole report is built on
+ * (its `events` feed both the `acc` fold below and the red maps), so its retention-backed
+ * coverage and its event set cannot disagree across the builders. */
+function foldSinceWindow(root, cutoff, now, end, untilMs) {
+    // The window key is the cutoff's local calendar day, from the shared dayKey helper
+    // eventDayKey buckets events with, so the read's day keys cannot disagree with the ts
+    // filter below; the day-keyed read may include earlier hours of that day, which the ts
+    // filter removes (over-read is at most one day's events). Future-dated events are dropped
+    // here too, matching collectReport (its day map only holds the window's days).
+    const fromKey = dayKey(cutoff);
+    const raw = readWindowEvents(root, fromKey);
+    const acc = {
+        runs: 0,
+        runsByRole: {},
+        rejectionsByRole: {},
+        postMergeRejectionsByRole: {},
+        revisionsByRole: {},
+        refusalsByRole: {},
+        checkDurationsMs: [],
+        checkFailures: 0,
+        mergeWaitsMs: [],
+        mergeDurationsMs: [],
+        runDurationsMs: [],
+        providerWaitsMs: [],
+        slotWaitsMs: [],
+        checkWaitsMs: [],
+        reviewDurationsMs: [],
+        failedRunsByRole: {},
+        imageReroutesByRole: {},
+        tokensByRole: {},
+        promptTokensByRole: {},
+        cacheReadTokensByRole: {},
+        costByRole: {},
+        tokensOut: 0,
+        ...zeroCommitCounts(),
+        costUsd: 0,
+        notionalCostUsd: 0,
+        notionalByRole: {},
+        ...zeroMergeCounts(),
+        mergedByRole: {},
+        mergeFailedByRole: {},
+        mergeFailedByReason: {},
+        costByProvider: {},
+        notionalByProvider: {},
+        notionalByBackend: {},
+        runsByModel: {},
+        deferredByReason: {},
+    };
+    for (const ev of raw.events) {
+        if (typeof ev.ts !== "number" || ev.ts < cutoff || ev.ts > now || (untilMs !== undefined && ev.ts >= end))
+            continue;
+        foldUsageEvent(acc, ev);
+    }
+    return { raw, acc };
+}
+/** The window's `totals` group under both scope rules, named so the team-vs-role branch reads
+ * as one function instead of a ternary buried in the return: the team figure sums the merge-slot
+ * fields in (the merge slot's dash tokens/cost are the same team spend the budget charges), while
+ * the role branch sums just the base roles through `roleSum` and zeroes the merge counts — a
+ * role's merge usage is the merge slot's, not the role's. */
+function sinceScopedTotals(acc, bases) {
+    return bases === undefined
+        ? {
+            tokensOut: acc.tokensOut + (acc.mergeTokens ?? 0),
+            runs: acc.runs ?? 0,
+            commits: acc.commits,
+            costUsd: acc.costUsd + (acc.mergeCostUsd ?? 0),
+            ...(acc.notionalCostUsd > 0 ? { notionalCostUsd: acc.notionalCostUsd } : {}),
+            ...nonemptyObj("notionalByBackend", acc.notionalByBackend),
+            mergeRuns: acc.mergeRuns ?? 0,
+            mergeTokens: acc.mergeTokens ?? 0,
+            mergeCostUsd: acc.mergeCostUsd ?? 0,
+            ...((acc.mergeFailed ?? 0) > 0 ? { mergeFailed: acc.mergeFailed } : {}),
+        }
+        : (() => {
+            // The role's own notional spend, from its run_end events; the merge slot's
+            // notional is team-wide and stays out like its cost.
+            const notional = roleSum(acc.notionalByRole, bases);
+            return {
+                tokensOut: roleSum(acc.tokensByRole, bases),
+                runs: roleSum(acc.runsByRole, bases),
+                commits: roleSum(acc.commitsByRole, bases),
+                costUsd: roleSum(acc.costByRole, bases),
+                ...(notional > 0 ? { notionalCostUsd: notional } : {}),
+                ...zeroMergeCounts(),
+            };
+        })();
+}
+/** Flatten a per-day main-red record map (day → label → count) into one flat label→count map,
+ * the shared body of sinceMainRedByTest and sinceMainRedByCulprit. Main's red state is main's
+ * own, not any role's, so a role-scoped window carries none — the empty map `nonemptyObj` then
+ * omits from the JSON, keeping a red-free --since byte-identical to today. */
+function flattenMainRedByDay(perDay, bases) {
+    if (bases !== undefined)
+        return {};
+    const flat = {};
+    for (const record of perDay.values()) {
+        for (const [label, n] of Object.entries(record))
+            addTo(flat, label, n);
+    }
+    return flat;
+}
+/** Main's red failing tests over the window, flattened across the per-day records of the same
+ * red `main_check` events the red time uses (G1's rule) into one map. Main's failing tests are
+ * main's own, not any role's, so a role-scoped window carries none (see flattenMainRedByDay). */
+function sinceMainRedByTest(raw, cutoff, end, bases) {
+    return flattenMainRedByDay(mainRedFailingTestsByDay(raw.events, cutoff, end), bases);
+}
+/** Main's red culprits over the window, flattened across the per-day records of the same red
+ * `main_culprit` events the live `mainred` alert's `red.culprit` reads (the historical twin)
+ * into one map. Main's own blame, not any role's, so a role-scoped window carries none (see
+ * flattenMainRedByDay). */
+function sinceMainRedByCulprit(raw, cutoff, end, bases) {
+    return flattenMainRedByDay(mainRedCulpritsByDay(raw.events, cutoff, end), bases);
+}
+/** The `SinceReport` return's role-scoped map group — every field a reader names when asking
+ * "which fields are team-only?": each `scopedByRole` call applies the base-role scope (the
+ * rule `collectReportSince`'s `bases` comment spells), so a role-scoped window shows exactly
+ * the maps the scoped day report would, and the team-only fields (providers, backends, models,
+ * deferred reasons) carry full maps for the team or empty maps for a scoped role. */
+function sinceRoleMaps(acc, bases) {
+    // The --since render/JSON's Notional by role line is conditional on the window's own
+    // notional spend, scoped to base when a role is given — the same conditional the day
+    // collector applies to ReportDay.notionalByRole (line ~573), so a role-scoped window
+    // whose role spent no notional carries no notionalByRole instead of an empty map.
+    const notionalByRole = scopedByRole(acc.notionalByRole, bases);
+    // Deferred runs are bucketed by a reason code (not a role), so a role-scoped window
+    // carries no entries — the same team-only rule runsByModel follows. Only set when the
+    // window actually deferred (zero means absent), so a deferral-free --since JSON omits it.
+    const deferred = scopedByRole(acc.deferredByReason, bases);
+    return {
+        runsByRole: scopedByRole(acc.runsByRole, bases),
+        costByRole: scopedByRole(acc.costByRole, bases),
+        rejectionsByRole: scopedByRole(acc.rejectionsByRole, bases),
+        postMergeRejectionsByRole: scopedByRole(acc.postMergeRejectionsByRole, bases),
+        revisionsByRole: scopedByRole(acc.revisionsByRole, bases),
+        refusalsByRole: scopedByRole(acc.refusalsByRole, bases),
+        failedRunsByRole: scopedByRole(acc.failedRunsByRole, bases),
+        imageReroutesByRole: scopedByRole(acc.imageReroutesByRole, bases),
+        tokensByRole: scopedByRole(acc.tokensByRole, bases),
+        ...nonemptyObj("promptTokensByRole", scopedByRole(acc.promptTokensByRole, bases)),
+        ...nonemptyObj("cacheReadTokensByRole", scopedByRole(acc.cacheReadTokensByRole, bases)),
+        commitsByRole: scopedByRole(acc.commitsByRole, bases),
+        mergedByRole: scopedByRole(acc.mergedByRole, bases),
+        mergeFailedByRole: scopedByRole(acc.mergeFailedByRole, bases),
+        // A result code is not a role, so a role-scoped window carries an empty map (a code
+        // never baseRoleOf to the role) — the render gates the reason line to the team report.
+        mergeFailedByReason: scopedByRole(acc.mergeFailedByReason, bases),
+        ...nonemptyObj("notionalByRole", notionalByRole),
+        // Provider spend is a team attribution (a provider is not a role), so a role-scoped
+        // window carries empty maps — providers never baseRoleOf to the role — and the render
+        // gates the provider lines to the team report anyway. Always present, empty when none.
+        costByProvider: scopedByRole(acc.costByProvider, bases),
+        notionalByProvider: scopedByRole(acc.notionalByProvider, bases),
+        // Backend spend is a team attribution (a backend is not a role), so a role-scoped window
+        // omits it — the same absent-when-empty rule the day collector applies.
+        ...nonemptyObj("notionalByBackend", scopedByRole(acc.notionalByBackend, bases)),
+        // Model attribution is team-only (a model is not a role, so no model folds to the
+        // scoped role), the same full-map-for-team / empty-for-scoped rule costByProvider
+        // follows. Always present so the render can gate on the window's own events.
+        runsByModel: scopedByRole(acc.runsByModel, bases),
+        ...nonemptyObj("deferredByReason", deferred),
+    };
+}