@zaip-ai/cli 1.0.7 → 1.0.8

package/templates/.agents/dashboard/modules/cost-monitor/src/server/build-cost-summary-projection.ts

@@ -0,0 +1,775 @@
+import type {
+  OperationsProjection,
+  RunProjection,
+  UsageMetricProjection,
+  UsageProjection,
+} from "@zaip-ai/dashboard-operations/contracts";
+import {
+  canonicalAllTimeDurationMs,
+  isAfterLegacyEffortCutoff,
+  LEGACY_EFFORT_DAILY_MS,
+  LEGACY_EFFORT_SNAPSHOT,
+  saoPauloPeriodKey,
+} from "@zaip-ai/dashboard-operations/contracts";
+import {
+  normalizeTokenBackedDailyDuration,
+  hybridDailyDuration as sharedHybridDailyDuration,
+  rootExecutionDurationByDay as sharedRootExecutionDurationByDay,
+} from "@zaip-ai/dashboard-operations/server";
+import type { CostGroupRow, CostMonitorProjection } from "../contracts.js";
+import { estimatedDurationMs, TOKEN_DURATION_ESTIMATE_BASIS } from "../duration-estimate.js";
+import { buildCostMonitorProjection, usageForRuns } from "./build-cost-monitor-projection.js";
+
+/** Fast Cost Monitor first fold backed only by the durable lifecycle summary. */
+export function buildCostSummaryProjection(
+  summary: CostSummarySource,
+  operations: OperationsProjection,
+  currency: "BRL" | "USD",
+  fxRate: number | null,
+): CostMonitorProjection {
+  const effectiveSummaryRuns = (summary.run_metrics ?? []).map(effectiveSummaryRun);
+  const compactRuns = effectiveSummaryRuns
+    .filter((run) => {
+      const day = saoPauloPeriodKey(run.finished_at ?? run.started_at, "day");
+      return day !== null && inRange(day, operations.filters.from, operations.filters.to);
+    })
+    .map(summaryRunProjection);
+  const available =
+    operations.schema_version === 2
+      ? buildCostMonitorProjection(
+          {
+            ...operations,
+            tasks: operations.tasks ?? [],
+            runs: compactRuns,
+          } as OperationsProjection,
+          undefined,
+        )
+      : null;
+  // A Model/Provider table shows only concrete source dimensions. Summary
+  // cards retain all financial facts; unknown attribution is never reassigned.
+  const concreteDimensionRows = (rows: readonly CostGroupRow[]) =>
+    rows.filter((row) => {
+      const key = row.key.trim().toLowerCase();
+      return key.length > 0 && !["mixed", "unknown", "unavailable"].includes(key);
+    });
+  const hasRunMetrics = summary.run_metrics !== undefined;
+  const hasCanonicalSqliteFacts =
+    summary.cost_monitor_daily_duration !== undefined || summary.canonical_daily_duration_ms !== undefined;
+  // The SQLite path is fully sourced from canonical Run facts. Legacy daily
+  // buckets remain available only to the old manifest path.
+  const dailyPeriods = new Map<string, PeriodSummary>(
+    Object.entries(finishDayCostPeriods(summary)),
+  );
+  // A factual source interval can cross a Sao Paulo midnight. Preserve the
+  // elapsed-session day even where no separate financial source event exists.
+  for (const key of Object.keys(summary.cost_monitor_daily_duration ?? {}))
+    if (!dailyPeriods.has(key)) dailyPeriods.set(key, emptyPeriodSummary());
+  if (!hasRunMetrics && !hasCanonicalSqliteFacts) {
+    for (const day of Object.keys(LEGACY_EFFORT_DAILY_MS))
+      if (!dailyPeriods.has(day)) dailyPeriods.set(day, emptyPeriodSummary());
+  }
+  // Prefer the compact Run projection whenever it is available: it already
+  // assigns the shared effective duration to every tokenized Run. Falling
+  // back to root-only summary timing would turn a tokenized day into 0 s.
+  const periodEntries = [...dailyPeriods].filter(([key]) =>
+    inRange(key, operations.filters.from, operations.filters.to),
+  );
+  const factualDurationByDay = durationByRootExecutionDay(effectiveSummaryRuns);
+  const factualCostDurationByDay = summary.cost_monitor_daily_duration;
+  const durationForDay = (key: string, period: PeriodSummary): DurationSource => {
+    if (factualCostDurationByDay !== undefined) {
+      const value = factualCostDurationByDay[key];
+      return value === undefined
+        ? emptyDuration()
+        : {
+            value: {
+              known_sum: value.known_sum,
+              unknown: value.eligible_runs - value.known_runs,
+              complete: value.eligible_runs === value.known_runs,
+              coverage_ratio:
+                value.eligible_runs === 0 ? 1 : value.known_runs / value.eligible_runs,
+            },
+            population: runPopulation(value.eligible_runs, value.known_runs),
+          };
+    }
+    if (summary.canonical_daily_duration_ms !== undefined) {
+      const value = summary.canonical_daily_duration_ms[key];
+      return value === undefined
+        ? emptyDuration()
+        : {
+            value: { known_sum: value, unknown: 0, complete: true, coverage_ratio: 1 },
+            population: runPopulation(period.runs, period.runs),
+          };
+    }
+    if (hasRunMetrics) return factualDurationByDay.get(key) ?? emptyDuration();
+    return dailyDurationSource(key, period);
+  };
+  const durationBudget = periodEntries.reduce(
+    (total, [key, period]) => total + durationForDay(key, period).value.known_sum,
+    0,
+  );
+  const normalizedDurationBudget =
+    !hasRunMetrics && !hasCanonicalSqliteFacts && operations.filters.from === null && operations.filters.to === null
+      ? canonicalAllTimeDurationMs(durationBudget)
+      : durationBudget;
+  const factualDailyRows = new Map(
+    (summary.daily_rows ?? []).map((row) => [row.key, row] as const),
+  );
+  const projectedDaily = periodEntries.map(([key, period]) =>
+    periodRow(key, period, fxRate, durationForDay(key, period), factualDailyRows.get(key)),
+  );
+  // Canonical SQLite duration is already deduplicated and assigned to the
+  // correct São Paulo calendar day. Rebalancing it by token population would
+  // preserve only the all-time total while corrupting each daily row.
+  const daily = hasCanonicalSqliteFacts
+    ? projectedDaily
+    : normalizeTokenBackedGroupBudget(
+        projectedDaily.map(ensureTokenBackedGroupDuration),
+        normalizedDurationBudget,
+      );
+  const runCount = daily.reduce((total, row) => total + row.run_count, 0);
+  const eventCount = daily.reduce((total, row) => total + row.event_count, 0);
+  // A completely unavailable population must not become a factual zero merely
+  // because the daily structural accumulator starts at zero.
+  const tokenTotal = !hasCanonicalSqliteFacts && compactRuns.every((run) => run.usage.total.tokens.total === null)
+    ? null
+    : sumNullable(daily.map((row) => row.total_tokens));
+  const brlTotal = !hasCanonicalSqliteFacts && compactRuns.every((run) => run.usage.total.cost.brl === null)
+    ? null
+    : sumNullable(daily.map((row) => row.estimated_brl));
+  const usdTotal = sumNullable(daily.map((row) => row.estimated_usd));
+  const observedDurationAverage = averageObservedPostCutoffRootDuration(summary.run_metrics ?? []);
+  const taskCount =
+    operations.summary.overview_metrics?.task_count ?? operations.summary.task_count;
+  // Period summaries expose the number of unavailable Runs. Compute coverage
+  // against exactly the Run population used by the cards, rather than event
+  // coverage (which is absent from the fast summary path).
+  const coverage = {
+    events: runCount,
+    tokens: daily.reduce((total, row) => total + row.coverage.tokens, 0),
+    usd: daily.reduce((total, row) => total + row.coverage.usd, 0),
+    brl: daily.reduce((total, row) => total + row.coverage.brl, 0),
+  };
+  return {
+    schema_version: 2,
+    layout_version: operations.layout_version,
+    readonly: true,
+    source: ".agents/records",
+    aggregate_only: true,
+    data_source: hasRunMetrics || hasCanonicalSqliteFacts ? "run_records" : "lifecycle_manifest_summary",
+    legacy_effort_baseline:
+      !hasRunMetrics && !hasCanonicalSqliteFacts && operations.filters.from === null && operations.filters.to === null
+        ? { cutoff: LEGACY_EFFORT_SNAPSHOT.cutoff, duration_ms: LEGACY_EFFORT_SNAPSHOT.durationMs }
+        : null,
+    currency,
+    pricing: { catalog_updated_at: null, fx_rate: fxRate, conversion_applied: fxRate !== null },
+    filters: operations.filters,
+    overview: {
+      task_count: taskCount,
+      run_count: runCount,
+      event_count: eventCount,
+      total_tokens: tokenTotal,
+      estimated_usd: usdTotal,
+      estimated_brl: brlTotal,
+      recorded_usd: null,
+      recorded_brl: null,
+      average_run_cost_usd: runCount === 0 || usdTotal === null ? null : usdTotal / runCount,
+      average_run_cost_brl: runCount === 0 || brlTotal === null ? null : brlTotal / runCount,
+      // Legacy effort has no individual Run cardinality, so it is not a
+      // legitimate contributor to an average per Run.
+      average_run_duration_ms: observedDurationAverage,
+      known_tokens_per_cycle: runCount === 0 || tokenTotal === null ? null : tokenTotal / runCount,
+      top_10_token_share: null,
+      coverage,
+    },
+    filters_available: {
+      providers: available?.filters_available.providers ?? [],
+      agents: available?.filters_available.agents ?? [],
+      models: available?.filters_available.models ?? [],
+      statuses: available?.filters_available.statuses ?? [],
+      priorities: available?.filters_available.priorities ?? [],
+      risks: available?.filters_available.risks ?? [],
+      phases: available?.filters_available.phases ?? [],
+      origins: available?.filters_available.origins ?? [],
+      work_types: available?.filters_available.work_types ?? [],
+    },
+    configured_agents: available?.configured_agents ?? [],
+    // Compact Run facts preserve total tokens and cost even though component
+    // telemetry is intentionally absent. Reuse their phase-aware aggregate
+    // instead of the quick Operations placeholder, which has no Run rows.
+    usage: summary.aggregate_usage ?? available?.usage ?? usageForRuns(compactRuns),
+    origins: emptyOrigins(),
+    prds: available?.prds ?? operations.prds,
+    specs: available?.specs ?? operations.specs,
+    // Keep summary first-paint bounded. Dimensional aggregates above were
+    // computed from compact facts, but Run transport stays page-only.
+    runs: [],
+    groups: {
+      // These two dimensions can contain one row per conversation or Task.
+      // They are rendered through the compact, paginated SQLite views after
+      // their tabs open, so carrying them in the first-fold summary only
+      // delays the Cost Monitor without contributing to its initial view.
+      conversations: [],
+      tasks: [],
+      providers: concreteDimensionRows(available?.groups.providers ?? []),
+      agents: available?.groups.agents ?? [],
+      // Model residuals preserve financial reconciliation in SQLite as
+      // unavailable, but are not a factual model category for the chart.
+      models: concreteDimensionRows(summary.model_groups ?? available?.groups.models ?? []),
+      daily,
+      monthly: mergePeriodRows(daily, 7),
+      annual: mergePeriodRows(daily, 4),
+    },
+  };
+}
+
+function dailyDurationSource(key: string, period: PeriodSummary): DurationSource {
+  return sharedHybridDailyDuration(key, period) as DurationSource;
+}
+
+function emptyPeriodSummary(): PeriodSummary {
+  const empty: KnownValue = { known_sum: 0, unknown: 0, complete: true, coverage_ratio: 1 };
+  return {
+    prds: 0,
+    specs: 0,
+    tasks: 0,
+    validations: 0,
+    evidences: 0,
+    runs: 0,
+    usage: { total_tokens: empty, cost: { ...empty, currency: "BRL" } },
+  };
+}
+
+export interface CostSummarySource {
+  periods: { daily: Record<string, PeriodSummary> };
+  /**
+   * SQLite's selected financial facts, retained for compact summaries where
+   * no Run transport is present. Values are factual and currency-specific.
+   */
+  daily_rows?: Array<{
+    key: string;
+    total_cost_usd: number | null;
+    total_cost_brl: number | null;
+  }>;
+  /** Distinct Tasks represented by the filtered aggregate population. */
+  task_count?: number;
+  aggregate_usage?: UsageProjection;
+  /** Segment-backed model aggregates for the SQLite first fold. */
+  model_groups?: CostGroupRow[];
+  /** @deprecated Root-execution duration; retained for non-SQLite callers. */
+  canonical_daily_duration_ms?: Record<string, number>;
+  /** Factual source duration paired with the financial invocation population. */
+  cost_monitor_daily_duration?: Record<
+    string,
+    { known_sum: number; eligible_runs: number; known_runs: number }
+  >;
+  run_metrics?: Array<{
+    id: string;
+    started_at: string;
+    finished_at: string | null;
+    task_id: string | null;
+    execution_id?: string | null;
+    conversation_id?: string | null;
+    agent?: string | null;
+    agent_name?: string | null;
+    provider?: string | null;
+    model?: string | null;
+    spec_id?: string | null;
+    prd_id?: string | null;
+    change_id?: string | null;
+    run_kind?: "run" | "subrun" | null;
+    phase: string | null;
+    parent_run_id: string | null;
+    status: string | null;
+    duration_ms: number | null;
+    /** Raw factual invocation duration, never a token estimate. */
+    source_duration_ms?: number | null;
+    duration_provenance?: "observed" | "estimated" | "unavailable";
+    estimation_basis?: string | null;
+    duration_started_at?: string | null;
+    total_tokens: number | null;
+    input_tokens?: number | null;
+    cached_input_tokens?: number | null;
+    output_tokens?: number | null;
+    reasoning_tokens?: number | null;
+    cost: number | null;
+    currency: string | null;
+    events: number | null;
+  }>;
+}
+
+/** Adapter from the durable compact Run fact to the Cost projection contract. */
+function summaryRunProjection(
+  run: NonNullable<CostSummarySource["run_metrics"]>[number],
+): RunProjection {
+  const empty = {
+    events: 0,
+    duration_ms: null,
+    tokens: { input: null, cached_input: null, output: null, reasoning: null, total: null },
+    cost: { usd: null, brl: null },
+    coverage: { events: 0, tokens: 0, usd: 0, brl: 0 },
+  };
+  const usage = {
+    ...empty,
+    events: run.events ?? 0,
+    duration_ms: run.source_duration_ms ?? null,
+    tokens: {
+      ...empty.tokens,
+      input: run.input_tokens ?? null,
+      cached_input: run.cached_input_tokens ?? null,
+      output: run.output_tokens ?? null,
+      reasoning: run.reasoning_tokens ?? null,
+      total: run.total_tokens,
+    },
+    cost: { usd: null, brl: run.currency === "BRL" ? run.cost : null },
+    coverage: {
+      events: run.events ?? 0,
+      tokens: run.total_tokens === null ? 0 : 1,
+      usd: 0,
+      brl: run.cost === null ? 0 : 1,
+    },
+  };
+  const phase = run.phase === "conversation" || run.phase === "planning" ? run.phase : "execution";
+  return {
+    id: run.id,
+    artifact_path: `.agents/records/runs/${run.id}`,
+    status:
+      run.status === "failed" || run.status === "cancelled" || run.status === "running"
+        ? run.status
+        : "completed",
+    phase,
+    entrypoint: run.task_id === null ? "conversation" : "task",
+    work_type: "new",
+    run_role: run.run_kind === "subrun" ? "subagent" : "orchestrator",
+    run_kind: run.run_kind ?? "run",
+    run_purpose: "execution",
+    requires_finalizer: false,
+    parent_run_id: run.parent_run_id,
+    client: "unknown",
+    agent: run.agent ?? "unknown",
+    agent_name: run.agent_name ?? run.agent ?? "unknown",
+    provider: run.provider ?? "unavailable",
+    model: run.model ?? "unknown",
+    reasoning_effort: null,
+    effective_model: run.model ?? null,
+    effective_reasoning_effort: null,
+    effective_config_mixed: false,
+    call_count: null,
+    terminal_call_count: null,
+    failed_call_count: 0,
+    cancelled_call_count: 0,
+    conversation_id: run.conversation_id ?? run.id,
+    execution_id: run.execution_id ?? null,
+    task_id: run.task_id,
+    spec_id: run.spec_id ?? null,
+    prd_id: run.prd_id ?? null,
+    change_id: run.change_id ?? null,
+    started_at: run.started_at,
+    finished_at: run.finished_at,
+    duration_ms: run.duration_ms,
+    source_duration_ms: run.source_duration_ms ?? null,
+    ...(run.duration_provenance === undefined
+      ? {}
+      : { duration_provenance: run.duration_provenance }),
+    ...(run.estimation_basis === undefined ? {} : { estimation_basis: run.estimation_basis }),
+    usage: {
+      conversation: phase === "conversation" ? usage : empty,
+      planning: phase === "planning" ? usage : empty,
+      execution: phase === "execution" ? usage : empty,
+      total: usage,
+      new_work: usage,
+      rework: empty,
+    },
+  };
+}
+
+function effectiveSummaryRun(
+  run: NonNullable<CostSummarySource["run_metrics"]>[number],
+): NonNullable<CostSummarySource["run_metrics"]>[number] {
+  if (run.duration_ms !== null)
+    return {
+      ...run,
+      duration_provenance: run.duration_provenance ?? "unavailable",
+      estimation_basis: run.duration_provenance === "estimated" ? run.estimation_basis ?? null : null,
+    };
+  const duration_ms = estimatedDurationMs(run.total_tokens);
+  return duration_ms === null
+    ? { ...run, duration_provenance: "unavailable", estimation_basis: null }
+    : {
+        ...run,
+        duration_ms,
+        duration_provenance: "estimated",
+        estimation_basis: TOKEN_DURATION_ESTIMATE_BASIS,
+      };
+}
+
+function ensureTokenBackedGroupDuration(row: CostGroupRow): CostGroupRow {
+  if ((row.total_tokens ?? 0) <= 0 || (row.duration_ms ?? 0) > 0) return row;
+  const duration_ms = estimatedDurationMs(row.total_tokens);
+  if (duration_ms === null || duration_ms <= 0) return row;
+  const coverageCounts = row.coverage_counts;
+  return {
+    ...row,
+    duration_ms,
+    duration: { known_sum: duration_ms, unknown: 0, complete: true, coverage_ratio: 1 },
+    ...(coverageCounts === undefined
+      ? {}
+      : {
+          coverage_counts: {
+            ...coverageCounts,
+            ...(coverageCounts.metrics === undefined
+              ? {}
+              : {
+                  metrics: {
+                    ...coverageCounts.metrics,
+                    duration: {
+                      eligible_runs: row.run_count,
+                      known_runs: row.run_count,
+                      unknown_runs: 0,
+                    },
+                  },
+                }),
+          },
+        }),
+  };
+}
+
+function normalizeTokenBackedGroupBudget(
+  rows: readonly CostGroupRow[],
+  budget: number,
+): CostGroupRow[] {
+  return normalizeTokenBackedDailyDuration(rows, budget).map((row) => ({
+    ...row,
+    duration_ms:
+      row.duration.complete ? row.duration.known_sum : null,
+  }));
+}
+
+interface KnownValue {
+  known_sum: number;
+  unknown: number;
+  complete: boolean;
+  coverage_ratio: number;
+}
+
+interface PeriodSummary {
+  prds: number;
+  specs: number;
+  tasks: number;
+  validations: number;
+  evidences: number;
+  runs: number;
+  usage: {
+    total_tokens: KnownValue;
+    cost: KnownValue & { currency: string | null };
+  };
+  duration?: KnownValue;
+  events?: KnownValue;
+}
+
+/** Reconcile the fast summary with the completed-Run calendar used by detail. */
+function finishDayCostPeriods(summary: CostSummarySource): Record<string, PeriodSummary> {
+  const runs = [
+    ...new Map((summary.run_metrics ?? []).map((run) => [run.id, run] as const)).values(),
+  ];
+  if (summary.run_metrics === undefined) return summary.periods.daily;
+
+  const byDay = new Map<string, typeof runs>();
+  for (const run of runs) {
+    // The compact SQLite source has already chosen source session time for
+    // started_at. Do not move token/cost to a later capture/finish day.
+    const day = saoPauloPeriodKey(run.started_at, "day");
+    if (day !== null) byDay.set(day, [...(byDay.get(day) ?? []), run]);
+  }
+  const days = new Set([...Object.keys(summary.periods.daily), ...byDay.keys()]);
+  return Object.fromEntries(
+    [...days].map((day) => {
+      const period = summary.periods.daily[day] ?? emptyPeriodSummary();
+      const dayRuns = byDay.get(day) ?? [];
+      const tokens = knownPeriodValue(dayRuns.map((run) => run.total_tokens));
+      const cost = knownPeriodValue(dayRuns.map((run) => run.cost));
+      const events = knownPeriodValue(dayRuns.map((run) => run.events));
+      return [
+        day,
+        {
+          ...period,
+          runs: dayRuns.length,
+          usage: {
+            total_tokens: tokens,
+            cost: {
+              ...cost,
+              currency:
+                dayRuns.find((run) => run.currency !== null)?.currency ??
+                period.usage.cost.currency,
+            },
+          },
+          events,
+        },
+      ];
+    }),
+  );
+}
+
+function knownPeriodValue(values: readonly (number | null)[]): KnownValue {
+  const known = values.filter((value): value is number => value !== null);
+  const unknown = values.length - known.length;
+  return {
+    known_sum: known.reduce((total, value) => total + value, 0),
+    unknown,
+    complete: unknown === 0,
+    coverage_ratio: values.length === 0 ? 1 : known.length / values.length,
+  };
+}
+
+function periodRow(
+  key: string,
+  period: PeriodSummary,
+  fxRate: number | null,
+  duration: DurationSource,
+  factualCosts?: { total_cost_usd: number | null; total_cost_brl: number | null },
+): CostGroupRow {
+  const periodBrl =
+    period.usage.cost.known_sum === 0 && period.usage.cost.unknown > 0
+      ? null
+      : period.usage.cost.known_sum;
+  // Do not derive or relabel a currency when SQLite supplied its factual
+  // value. The legacy manifest path retains its period/FX fallback.
+  const brl = factualCosts === undefined ? periodBrl : factualCosts.total_cost_brl;
+  const usd =
+    factualCosts === undefined
+      ? brl !== null && fxRate !== null && fxRate > 0
+        ? brl / fxRate
+        : null
+      : factualCosts.total_cost_usd;
+  const eventCount = period.events?.known_sum ?? 0;
+  const knownTokens = knownRuns(period.runs, period.usage.total_tokens.unknown);
+  const knownCost = knownRuns(period.runs, period.usage.cost.unknown);
+  return {
+    key,
+    label: key,
+    latest_started_at: `${key}T23:59:59.999-03:00`,
+    run_count: period.runs,
+    task_count: period.tasks,
+    tasksCreated: period.tasks,
+    tasksActive: period.tasks,
+    taskDaysActive: period.tasks,
+    prd_count: period.prds,
+    spec_count: period.specs,
+    evidence_count: period.evidences,
+    test_count: period.validations,
+    event_count: eventCount,
+    total_tokens:
+      period.usage.total_tokens.known_sum === 0 && period.usage.total_tokens.unknown > 0
+        ? null
+        : period.usage.total_tokens.known_sum,
+    estimated_usd: usd,
+    estimated_brl: brl,
+    // Keep the additive factual total visible even if the separate coverage
+    // counters report an incomplete financial population. Hiding it as
+    // unavailable breaks parity with Operations and discards calculable time.
+    // This is never model-inference latency or a token estimate.
+    duration_ms:
+      duration.population.known_runs > 0 ? duration.value.known_sum : null,
+    duration: duration.value,
+    coverage: {
+      events: period.runs,
+      tokens: knownTokens,
+      usd: knownCost,
+      brl: knownCost,
+    },
+    coverage_counts: {
+      source: "period_summary",
+      granularity: period.events === undefined ? "unavailable" : "event",
+      events: period.events?.known_sum ?? null,
+      tokens: null,
+      usd: null,
+      brl: null,
+      metrics: {
+        duration: duration.population,
+        tokens: runPopulation(period.runs, knownTokens),
+        usd: runPopulation(period.runs, knownCost),
+        brl: runPopulation(period.runs, knownCost),
+      },
+    },
+  };
+}
+
+function mergePeriodRows(rows: readonly CostGroupRow[], prefixLength: number): CostGroupRow[] {
+  const groups = new Map<string, CostGroupRow[]>();
+  for (const row of rows) {
+    const key = row.key.slice(0, prefixLength);
+    groups.set(key, [...(groups.get(key) ?? []), row]);
+  }
+  return [...groups]
+    .map(([key, values]) => {
+      const first = values[0]!;
+      const known = values.reduce((total, row) => total + row.duration.known_sum, 0);
+      const unknown = values.reduce((total, row) => total + row.duration.unknown, 0);
+      const durationPopulation = values.reduce(
+        (total, row) => total + (row.coverage_counts?.metrics?.duration?.eligible_runs ?? 0),
+        0,
+      );
+      const durationKnownRuns = values.reduce(
+        (total, row) => total + (row.coverage_counts?.metrics?.duration?.known_runs ?? 0),
+        0,
+      );
+      const runCount = values.reduce((total, row) => total + row.run_count, 0);
+      return {
+        ...first,
+        key,
+        label: key,
+        latest_started_at:
+          values
+            .map((row) => row.latest_started_at)
+            .sort()
+            .at(-1) ?? first.latest_started_at,
+        run_count: runCount,
+        task_count: values.reduce((total, row) => total + (row.task_count ?? 0), 0),
+        tasksCreated: values.reduce((total, row) => total + (row.tasksCreated ?? 0), 0),
+        tasksActive: values.reduce((total, row) => total + (row.tasksActive ?? 0), 0),
+        taskDaysActive: values.reduce((total, row) => total + (row.taskDaysActive ?? 0), 0),
+        prd_count: values.reduce((total, row) => total + row.prd_count, 0),
+        spec_count: values.reduce((total, row) => total + row.spec_count, 0),
+        evidence_count: values.reduce((total, row) => total + row.evidence_count, 0),
+        test_count: values.reduce((total, row) => total + row.test_count, 0),
+        event_count: values.reduce((total, row) => total + row.event_count, 0),
+        total_tokens: mergeNullableMetric(values.map((row) => row.total_tokens)),
+        estimated_usd: mergeNullableMetric(values.map((row) => row.estimated_usd)),
+        estimated_brl: mergeNullableMetric(values.map((row) => row.estimated_brl)),
+        // A period duration is factual only if every financial day in its
+        // population has an observed source interval. Never promote a
+        // partial daily union into a monthly/yearly numeric total.
+        duration_ms: unknown === 0 ? known : null,
+        duration: {
+          known_sum: known,
+          unknown,
+          complete: unknown === 0,
+          coverage_ratio: durationPopulation === 0 ? 1 : durationKnownRuns / durationPopulation,
+        },
+        coverage: {
+          events: values.reduce((total, row) => total + row.coverage.events, 0),
+          tokens: values.reduce((total, row) => total + row.coverage.tokens, 0),
+          usd: values.reduce((total, row) => total + row.coverage.usd, 0),
+          brl: values.reduce((total, row) => total + row.coverage.brl, 0),
+        },
+        ...(first.coverage_counts === undefined
+          ? {}
+          : {
+              coverage_counts: {
+                ...first.coverage_counts,
+                metrics: {
+                  duration: runPopulation(durationPopulation, durationKnownRuns),
+                  tokens: mergeMetricPopulation(values, "tokens"),
+                  usd: mergeMetricPopulation(values, "usd"),
+                  brl: mergeMetricPopulation(values, "brl"),
+                },
+              },
+            }),
+      };
+    })
+    .sort((left, right) => right.key.localeCompare(left.key));
+}
+
+function mergeMetricPopulation(
+  rows: readonly CostGroupRow[],
+  metric: "tokens" | "usd" | "brl",
+): ReturnType<typeof runPopulation> {
+  const populations = rows.map((row) => row.coverage_counts?.metrics?.[metric]);
+  return runPopulation(
+    populations.reduce((total, population) => total + (population?.eligible_runs ?? 0), 0),
+    populations.reduce((total, population) => total + (population?.known_runs ?? 0), 0),
+  );
+}
+
+/**
+ * Cost cards intentionally retain all-invocation count/tokens/cost, but their
+ * duration is the same non-overlapping root-execution population as
+ * Operations.  Missing run metrics stays unavailable rather than borrowing
+ * the legacy aggregate (which mixes conversations and Sub-Runs).
+ */
+interface DurationSource {
+  value: KnownValue;
+  population: ReturnType<typeof runPopulation>;
+}
+
+function durationByRootExecutionDay(
+  runs: readonly NonNullable<CostSummarySource["run_metrics"]>[number][],
+): Map<string, DurationSource> {
+  return sharedRootExecutionDurationByDay(runs) as Map<string, DurationSource>;
+}
+
+function averageObservedPostCutoffRootDuration(
+  runs: readonly NonNullable<CostSummarySource["run_metrics"]>[number][],
+): number | null {
+  const known = runs.filter(
+    (run): run is typeof run & { duration_ms: number } =>
+      run.phase === "execution" &&
+      run.parent_run_id == null &&
+      isAfterLegacyEffortCutoff(run.duration_started_at ?? run.started_at) &&
+      run.duration_ms !== null &&
+      run.duration_ms >= 0,
+  );
+  return known.length === 0
+    ? null
+    : known.reduce((total, run) => total + run.duration_ms, 0) / known.length;
+}
+
+function emptyDuration(): DurationSource {
+  return {
+    value: { known_sum: 0, unknown: 0, complete: true, coverage_ratio: 1 },
+    population: runPopulation(0, 0),
+  };
+}
+
+function inRange(key: string, from: string | null, to: string | null): boolean {
+  const dayForBound = (value: string | null) => {
+    if (value === null) return null;
+    // Direct projection callers can still provide a date-only value. It is a
+    // São Paulo calendar label, whereas timestamp bounds need conversion.
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) return value;
+    return saoPauloPeriodKey(value, "day");
+  };
+  const fromDay = dayForBound(from);
+  const toDay = dayForBound(to);
+  return (fromDay === null || key >= fromDay) && (toDay === null || key <= toDay);
+}
+
+function sumNullable(values: readonly (number | null)[]): number | null {
+  const known = values.filter((value): value is number => value !== null);
+  return known.length === 0 ? null : known.reduce((total, value) => total + value, 0);
+}
+
+function mergeNullableMetric(values: readonly (number | null)[]): number | null {
+  return values.some((value) => value === null)
+    ? null
+    : values.reduce<number>((total, value) => total + (value ?? 0), 0);
+}
+
+function knownRuns(eligibleRuns: number, unknownRuns: number): number {
+  return Math.max(0, eligibleRuns - unknownRuns);
+}
+
+function runPopulation(eligible_runs: number, known_runs: number) {
+  return { eligible_runs, known_runs, unknown_runs: eligible_runs - known_runs };
+}
+
+function emptyMetric(): UsageMetricProjection {
+  return {
+    events: 0,
+    tokens: { input: null, cached_input: null, output: null, reasoning: null, total: null },
+    cost: { usd: null, brl: null },
+    coverage: { events: 0, tokens: 0, usd: 0, brl: 0 },
+  };
+}
+
+function emptyOrigins(): CostMonitorProjection["origins"] {
+  const usage = (): UsageProjection => ({
+    conversation: emptyMetric(),
+    planning: emptyMetric(),
+    execution: emptyMetric(),
+    total: emptyMetric(),
+    new_work: emptyMetric(),
+    rework: emptyMetric(),
+  });
+  return { conversation: usage(), task: usage(), spec: usage(), prd: usage() };
+}