@iann29/rastro 0.1.0-alpha.8 → 0.1.0

package/src/component/rollupStore.ts

@@ -0,0 +1,799 @@
+import { v } from "convex/values";
+import { internal } from "./_generated/api.js";
+import type { Doc, Id } from "./_generated/dataModel.js";
+import type { MutationCtx } from "./_generated/server.js";
+import {
+  addVisitor,
+  createVisitorSketch,
+  unionVisitorSketches,
+  type VisitorSketch,
+} from "./cardinality.js";
+import {
+  DAY_MS,
+  MAX_FUNNEL_STEPS,
+  MAX_SITE_MAP_ROUTES_PER_DAY,
+  REPORT_ROLLUP_SHARDS,
+  ROLLUP_FOLD_LEASE_MS,
+  ROUTE_TRANSITION_SLOTS,
+  SITE_MAP_OTHER_ROUTE,
+  VITAL_PAGE_SLOTS,
+} from "./constants.js";
+import { fail } from "./errors.js";
+import { stableHash } from "./sanitize.js";
+import { vitalMetricValidator } from "./validators.js";
+import {
+  mergeVitalHistograms,
+  VITAL_ALL,
+  VITAL_OTHER_PAGES,
+  type VitalMetric,
+} from "./vitals.js";
+
+/**
+ * Report rollups (goal, funnel, affiliate, route and Web Vitals daily rows)
+ * are the hottest documents in the store: a goal on the home page or one
+ * affiliate carrying a campaign means every batch read-modify-writes the same
+ * two rows, and under concurrent load Convex's optimistic retries run out and
+ * whole batches are lost (#52). Ingestion therefore never touches a rollup
+ * row. It appends the batch's deltas to `reportRollupQueue` — an insert
+ * conflicts with nothing — and one leased fold job per site merges the queue
+ * into the rows a few hundred milliseconds later, so every rollup row has a
+ * single writer.
+ */
+
+export type GoalRollupDelta = {
+  siteId: Id<"sites">;
+  goalId: Id<"goals">;
+  bucketStart: number;
+  shard: number;
+  goalKey: string;
+  completions: number;
+  valueCents: number;
+};
+export type FunnelRollupDelta = {
+  siteId: Id<"sites">;
+  funnelId: Id<"funnels">;
+  bucketStart: number;
+  shard: number;
+  steps: Map<number, { step: number; entrants: number; completions: number }>;
+};
+export type FunnelStepDelta = {
+  siteId: Id<"sites">;
+  funnelId: Id<"funnels">;
+  bucketStart: number;
+  step: number;
+  shard: number;
+  entrants: number;
+  completions: number;
+};
+export type AffiliateRollupDelta = {
+  siteId: Id<"sites">;
+  affiliateId: Id<"affiliates">;
+  bucketStart: number;
+  shard: number;
+  affiliateSlug: string;
+  visits: number;
+  visitorKeys: Set<string>;
+  conversions: number;
+  revenueCents: number;
+  commissionCents: number;
+};
+export type VitalRollupDelta = {
+  siteId: Id<"sites">;
+  bucketStart: number;
+  device: string;
+  page: string;
+  shard: number;
+  metrics: Map<
+    VitalMetric,
+    { count: number; sum: number; histogram: number[] }
+  >;
+};
+export type RouteRollupDelta = {
+  siteId: Id<"sites">;
+  bucketStart: number;
+  shard: number;
+  route: string;
+  pageviews: number;
+  entries: number;
+  continued: number;
+  dwellMs: number;
+  dwellSamples: number;
+  visitorKeys: Set<string>;
+  outgoing: Map<string, number>;
+};
+export type ReportRollupDeltas = {
+  goals: Map<string, GoalRollupDelta>;
+  funnels: Map<string, FunnelRollupDelta>;
+  funnelSteps: Map<string, FunnelStepDelta>;
+  affiliates: Map<string, AffiliateRollupDelta>;
+  vitals: Map<string, VitalRollupDelta>;
+  routes: Map<string, RouteRollupDelta>;
+};
+
+export function createReportRollupDeltas(): ReportRollupDeltas {
+  return {
+    goals: new Map(),
+    funnels: new Map(),
+    funnelSteps: new Map(),
+    affiliates: new Map(),
+    vitals: new Map(),
+    routes: new Map(),
+  };
+}
+
+export function reportRollupCoordinates(
+  siteId: Id<"sites">,
+  definitionId: string,
+  timestamp: number,
+  visitorId: string,
+) {
+  const bucketStart = Math.floor(timestamp / DAY_MS) * DAY_MS;
+  const shard = stableHash(visitorId) % REPORT_ROLLUP_SHARDS;
+  return {
+    bucketStart,
+    shard,
+    key: `${siteId}:${definitionId}:${bucketStart}:${shard}`,
+  };
+}
+
+export function countReportRollupRows(deltas: ReportRollupDeltas): number {
+  return (
+    deltas.goals.size +
+    deltas.funnels.size +
+    deltas.funnelSteps.size +
+    deltas.affiliates.size +
+    deltas.vitals.size +
+    deltas.routes.size
+  );
+}
+
+// ---------------------------------------------------------------------------
+// The queue document: the same deltas, serialized. Visitor identity travels as
+// the bounded list of keys a batch saw (a batch is one browser, so usually
+// one) and only becomes a sketch when it is folded into the row.
+
+const queuedGoalValidator = v.object({
+  goalId: v.id("goals"),
+  bucketStart: v.number(),
+  shard: v.number(),
+  goalKey: v.string(),
+  completions: v.number(),
+  valueCents: v.number(),
+});
+const queuedFunnelValidator = v.object({
+  funnelId: v.id("funnels"),
+  bucketStart: v.number(),
+  shard: v.number(),
+  steps: v.array(
+    v.object({
+      step: v.number(),
+      entrants: v.number(),
+      completions: v.number(),
+    }),
+  ),
+});
+const queuedFunnelStepValidator = v.object({
+  funnelId: v.id("funnels"),
+  bucketStart: v.number(),
+  step: v.number(),
+  shard: v.number(),
+  entrants: v.number(),
+  completions: v.number(),
+});
+const queuedAffiliateValidator = v.object({
+  affiliateId: v.id("affiliates"),
+  bucketStart: v.number(),
+  shard: v.number(),
+  affiliateSlug: v.string(),
+  visits: v.number(),
+  visitorKeys: v.array(v.string()),
+  conversions: v.number(),
+  revenueCents: v.number(),
+  commissionCents: v.number(),
+});
+const queuedRouteValidator = v.object({
+  route: v.string(),
+  bucketStart: v.number(),
+  shard: v.number(),
+  pageviews: v.number(),
+  entries: v.number(),
+  continued: v.number(),
+  dwellMs: v.number(),
+  dwellSamples: v.number(),
+  visitorKeys: v.array(v.string()),
+  outgoing: v.array(v.object({ route: v.string(), count: v.number() })),
+});
+const queuedVitalValidator = v.object({
+  bucketStart: v.number(),
+  device: v.string(),
+  page: v.string(),
+  shard: v.number(),
+  metrics: v.array(
+    v.object({
+      metric: vitalMetricValidator,
+      count: v.number(),
+      sum: v.number(),
+      histogram: v.array(v.number()),
+    }),
+  ),
+});
+
+export const reportRollupQueueFields = {
+  siteId: v.id("sites"),
+  createdAt: v.number(),
+  goals: v.array(queuedGoalValidator),
+  funnels: v.array(queuedFunnelValidator),
+  funnelSteps: v.array(queuedFunnelStepValidator),
+  affiliates: v.array(queuedAffiliateValidator),
+  routes: v.array(queuedRouteValidator),
+  vitals: v.array(queuedVitalValidator),
+};
+
+export const rollupFoldStateFields = {
+  siteId: v.id("sites"),
+  leaseUntil: v.number(),
+  token: v.string(),
+};
+
+type QueuedRollups = Omit<Doc<"reportRollupQueue">, "_id" | "_creationTime">;
+
+function serializeReportRollupDeltas(
+  siteId: Id<"sites">,
+  deltas: ReportRollupDeltas,
+  createdAt: number,
+): QueuedRollups {
+  return {
+    siteId,
+    createdAt,
+    goals: [...deltas.goals.values()].map(
+      ({ goalId, bucketStart, shard, goalKey, completions, valueCents }) => ({
+        goalId,
+        bucketStart,
+        shard,
+        goalKey,
+        completions,
+        valueCents,
+      }),
+    ),
+    funnels: [...deltas.funnels.values()].map(
+      ({ funnelId, bucketStart, shard, steps }) => ({
+        funnelId,
+        bucketStart,
+        shard,
+        steps: [...steps.values()].map((step) => ({ ...step })),
+      }),
+    ),
+    funnelSteps: [...deltas.funnelSteps.values()].map(
+      ({ funnelId, bucketStart, step, shard, entrants, completions }) => ({
+        funnelId,
+        bucketStart,
+        step,
+        shard,
+        entrants,
+        completions,
+      }),
+    ),
+    affiliates: [...deltas.affiliates.values()].map(
+      ({ siteId: _siteId, visitorKeys, ...rest }) => ({
+        ...rest,
+        visitorKeys: [...visitorKeys],
+      }),
+    ),
+    routes: [...deltas.routes.values()].map(
+      ({ siteId: _siteId, visitorKeys, outgoing, ...rest }) => ({
+        ...rest,
+        visitorKeys: [...visitorKeys],
+        outgoing: [...outgoing].map(([route, count]) => ({ route, count })),
+      }),
+    ),
+    vitals: [...deltas.vitals.values()].map(
+      ({ siteId: _siteId, metrics, ...rest }) => ({
+        ...rest,
+        metrics: [...metrics].map(([metric, entry]) => ({
+          metric,
+          count: entry.count,
+          sum: entry.sum,
+          histogram: [...entry.histogram],
+        })),
+      }),
+    ),
+  };
+}
+
+/** Accumulates one queued document into the deltas the fold will write. */
+export function mergeQueuedRollups(
+  deltas: ReportRollupDeltas,
+  queued: Doc<"reportRollupQueue">,
+) {
+  const siteId = queued.siteId;
+  for (const goal of queued.goals) {
+    const key = `${siteId}:${goal.goalId}:${goal.bucketStart}:${goal.shard}`;
+    const current = deltas.goals.get(key) ?? {
+      siteId,
+      goalId: goal.goalId,
+      bucketStart: goal.bucketStart,
+      shard: goal.shard,
+      goalKey: goal.goalKey,
+      completions: 0,
+      valueCents: 0,
+    };
+    current.completions += goal.completions;
+    current.valueCents += goal.valueCents;
+    current.goalKey = goal.goalKey;
+    deltas.goals.set(key, current);
+  }
+  for (const funnel of queued.funnels) {
+    const key = `${siteId}:${funnel.funnelId}:${funnel.bucketStart}:${funnel.shard}`;
+    const current = deltas.funnels.get(key) ?? {
+      siteId,
+      funnelId: funnel.funnelId,
+      bucketStart: funnel.bucketStart,
+      shard: funnel.shard,
+      steps: new Map(),
+    };
+    for (const step of funnel.steps) {
+      const entry = current.steps.get(step.step) ?? {
+        step: step.step,
+        entrants: 0,
+        completions: 0,
+      };
+      entry.entrants += step.entrants;
+      entry.completions += step.completions;
+      current.steps.set(step.step, entry);
+    }
+    deltas.funnels.set(key, current);
+  }
+  for (const step of queued.funnelSteps) {
+    const key = `${siteId}:${step.funnelId}:${step.bucketStart}:${step.step}:${step.shard}`;
+    const current = deltas.funnelSteps.get(key) ?? {
+      siteId,
+      funnelId: step.funnelId,
+      bucketStart: step.bucketStart,
+      step: step.step,
+      shard: step.shard,
+      entrants: 0,
+      completions: 0,
+    };
+    current.entrants += step.entrants;
+    current.completions += step.completions;
+    deltas.funnelSteps.set(key, current);
+  }
+  for (const affiliate of queued.affiliates) {
+    const key = `${siteId}:${affiliate.affiliateId}:${affiliate.bucketStart}:${affiliate.shard}`;
+    const current = deltas.affiliates.get(key) ?? {
+      siteId,
+      affiliateId: affiliate.affiliateId,
+      bucketStart: affiliate.bucketStart,
+      shard: affiliate.shard,
+      affiliateSlug: affiliate.affiliateSlug,
+      visits: 0,
+      visitorKeys: new Set<string>(),
+      conversions: 0,
+      revenueCents: 0,
+      commissionCents: 0,
+    };
+    current.affiliateSlug = affiliate.affiliateSlug;
+    current.visits += affiliate.visits;
+    current.conversions += affiliate.conversions;
+    current.revenueCents += affiliate.revenueCents;
+    current.commissionCents += affiliate.commissionCents;
+    for (const visitorKey of affiliate.visitorKeys) {
+      current.visitorKeys.add(visitorKey);
+    }
+    deltas.affiliates.set(key, current);
+  }
+  for (const route of queued.routes) {
+    const key = `${siteId}:route:${route.route}:${route.bucketStart}:${route.shard}`;
+    const current = deltas.routes.get(key) ?? {
+      siteId,
+      bucketStart: route.bucketStart,
+      shard: route.shard,
+      route: route.route,
+      pageviews: 0,
+      entries: 0,
+      continued: 0,
+      dwellMs: 0,
+      dwellSamples: 0,
+      visitorKeys: new Set<string>(),
+      outgoing: new Map<string, number>(),
+    };
+    current.pageviews += route.pageviews;
+    current.entries += route.entries;
+    current.continued += route.continued;
+    current.dwellMs += route.dwellMs;
+    current.dwellSamples += route.dwellSamples;
+    for (const visitorKey of route.visitorKeys) {
+      current.visitorKeys.add(visitorKey);
+    }
+    for (const transition of route.outgoing) {
+      current.outgoing.set(
+        transition.route,
+        (current.outgoing.get(transition.route) ?? 0) + transition.count,
+      );
+    }
+    deltas.routes.set(key, current);
+  }
+  for (const vital of queued.vitals) {
+    const key = JSON.stringify([
+      siteId,
+      vital.bucketStart,
+      vital.device,
+      vital.page,
+      vital.shard,
+    ]);
+    const current = deltas.vitals.get(key) ?? {
+      siteId,
+      bucketStart: vital.bucketStart,
+      device: vital.device,
+      page: vital.page,
+      shard: vital.shard,
+      metrics: new Map<
+        VitalMetric,
+        { count: number; sum: number; histogram: number[] }
+      >(),
+    };
+    for (const metric of vital.metrics) {
+      const entry = current.metrics.get(metric.metric);
+      if (entry) {
+        entry.count += metric.count;
+        entry.sum += metric.sum;
+        entry.histogram = mergeVitalHistograms(
+          entry.histogram,
+          metric.histogram,
+        );
+      } else {
+        current.metrics.set(metric.metric, {
+          count: metric.count,
+          sum: metric.sum,
+          histogram: [...metric.histogram],
+        });
+      }
+    }
+    deltas.vitals.set(key, current);
+  }
+}
+
+/**
+ * Appends a batch's rollup deltas to the site's queue and makes sure a fold
+ * job will pick them up. The only document this reads is the site's fold
+ * state, which the fold job rewrites about twice a minute under load, so
+ * concurrent ingests almost never retry because of it.
+ */
+export async function enqueueReportRollups(
+  ctx: MutationCtx,
+  siteId: Id<"sites">,
+  deltas: ReportRollupDeltas,
+  now: number,
+) {
+  if (countReportRollupRows(deltas) === 0) return;
+  await ctx.db.insert(
+    "reportRollupQueue",
+    serializeReportRollupDeltas(siteId, deltas, now),
+  );
+  await ensureRollupFold(ctx, siteId, now);
+}
+
+export async function ensureRollupFold(
+  ctx: MutationCtx,
+  siteId: Id<"sites">,
+  now: number,
+) {
+  const state = await ctx.db
+    .query("rollupFoldStates")
+    .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
+    .unique();
+  if (state && state.leaseUntil > now) return;
+  const token = crypto.randomUUID();
+  const leaseUntil = now + ROLLUP_FOLD_LEASE_MS;
+  if (state) {
+    await ctx.db.patch("rollupFoldStates", state._id, { leaseUntil, token });
+  } else {
+    await ctx.db.insert("rollupFoldStates", { siteId, leaseUntil, token });
+  }
+  await ctx.scheduler.runAfter(0, internal.rollups.fold, { siteId, token });
+}
+
+// ---------------------------------------------------------------------------
+// Writing the rows. Only the fold job calls this, one site at a time.
+
+export async function flushReportRollups(
+  ctx: MutationCtx,
+  deltas: ReportRollupDeltas,
+) {
+  for (const delta of deltas.goals.values()) {
+    const existing = await ctx.db
+      .query("goalDailyRollups")
+      .withIndex("by_siteId_and_goalId_and_bucketStart_and_shard", (range) =>
+        range
+          .eq("siteId", delta.siteId)
+          .eq("goalId", delta.goalId)
+          .eq("bucketStart", delta.bucketStart)
+          .eq("shard", delta.shard),
+      )
+      .unique();
+    const fields = {
+      siteId: delta.siteId,
+      goalId: delta.goalId,
+      bucketStart: delta.bucketStart,
+      shard: delta.shard,
+      generation: 1 as const,
+      goalKey: delta.goalKey,
+      completions: (existing?.completions ?? 0) + delta.completions,
+      valueCents: (existing?.valueCents ?? 0) + delta.valueCents,
+    };
+    if (existing) {
+      await ctx.db.replace("goalDailyRollups", existing._id, fields);
+    } else {
+      await ctx.db.insert("goalDailyRollups", fields);
+    }
+  }
+  for (const delta of deltas.funnels.values()) {
+    const existing = await ctx.db
+      .query("funnelDailyRollups")
+      .withIndex("by_siteId_and_funnelId_and_bucketStart_and_shard", (range) =>
+        range
+          .eq("siteId", delta.siteId)
+          .eq("funnelId", delta.funnelId)
+          .eq("bucketStart", delta.bucketStart)
+          .eq("shard", delta.shard),
+      )
+      .unique();
+    const steps = existing?.steps.map((step) => ({ ...step })) ?? [];
+    for (const addition of delta.steps.values()) {
+      const current = steps.find((step) => step.step === addition.step);
+      if (current) {
+        current.entrants += addition.entrants;
+        current.completions += addition.completions;
+      } else {
+        if (steps.length >= MAX_FUNNEL_STEPS) {
+          fail("LIMIT_EXCEEDED", "daily funnel rollup step limit exceeded");
+        }
+        steps.push({ ...addition });
+      }
+    }
+    const fields = {
+      siteId: delta.siteId,
+      funnelId: delta.funnelId,
+      bucketStart: delta.bucketStart,
+      shard: delta.shard,
+      generation: 1 as const,
+      steps,
+    };
+    if (existing) {
+      await ctx.db.replace("funnelDailyRollups", existing._id, fields);
+    } else {
+      await ctx.db.insert("funnelDailyRollups", fields);
+    }
+  }
+  for (const delta of deltas.funnelSteps.values()) {
+    const bucket = await ctx.db
+      .query("funnelStepBuckets")
+      .withIndex(
+        "by_siteId_and_funnelId_and_bucketStart_and_step_and_shard",
+        (range) =>
+          range
+            .eq("siteId", delta.siteId)
+            .eq("funnelId", delta.funnelId)
+            .eq("bucketStart", delta.bucketStart)
+            .eq("step", delta.step)
+            .eq("shard", delta.shard),
+      )
+      .unique();
+    if (bucket) {
+      await ctx.db.patch("funnelStepBuckets", bucket._id, {
+        entrants: bucket.entrants + delta.entrants,
+        completions: bucket.completions + delta.completions,
+      });
+    } else {
+      await ctx.db.insert("funnelStepBuckets", {
+        siteId: delta.siteId,
+        funnelId: delta.funnelId,
+        bucketStart: delta.bucketStart,
+        step: delta.step,
+        shard: delta.shard,
+        entrants: delta.entrants,
+        completions: delta.completions,
+      });
+    }
+  }
+  for (const delta of deltas.affiliates.values()) {
+    const existing = await ctx.db
+      .query("affiliateDailyRollups")
+      .withIndex(
+        "by_siteId_and_affiliateId_and_bucketStart_and_shard",
+        (range) =>
+          range
+            .eq("siteId", delta.siteId)
+            .eq("affiliateId", delta.affiliateId)
+            .eq("bucketStart", delta.bucketStart)
+            .eq("shard", delta.shard),
+      )
+      .unique();
+    const fields = {
+      siteId: delta.siteId,
+      affiliateId: delta.affiliateId,
+      bucketStart: delta.bucketStart,
+      shard: delta.shard,
+      generation: 1 as const,
+      affiliateSlug: delta.affiliateSlug,
+      visits: (existing?.visits ?? 0) + delta.visits,
+      visitorSketch: sketchWithKeys(existing?.visitorSketch, delta.visitorKeys),
+      conversions: (existing?.conversions ?? 0) + delta.conversions,
+      revenueCents: (existing?.revenueCents ?? 0) + delta.revenueCents,
+      commissionCents: (existing?.commissionCents ?? 0) + delta.commissionCents,
+    };
+    if (existing) {
+      await ctx.db.replace("affiliateDailyRollups", existing._id, fields);
+    } else {
+      await ctx.db.insert("affiliateDailyRollups", fields);
+    }
+  }
+  const routeDayRowCounts = new Map<string, number>();
+  for (const delta of deltas.routes.values()) {
+    await upsertRouteRollup(ctx, delta, routeDayRowCounts);
+  }
+  for (const delta of deltas.vitals.values()) {
+    await upsertVitalRollup(ctx, delta);
+  }
+}
+
+function sketchWithKeys(
+  existing: VisitorSketch | undefined,
+  visitorKeys: Set<string>,
+): VisitorSketch {
+  let sketch = createVisitorSketch();
+  for (const visitorKey of visitorKeys) {
+    sketch = addVisitor(sketch, visitorKey);
+  }
+  return existing ? unionVisitorSketches(existing, sketch) : sketch;
+}
+
+async function upsertRouteRollup(
+  ctx: MutationCtx,
+  delta: RouteRollupDelta,
+  dayRowCounts: Map<string, number>,
+) {
+  const existing = await ctx.db
+    .query("routeDailyRollups")
+    .withIndex("by_siteId_and_route_and_bucketStart_and_shard", (range) =>
+      range
+        .eq("siteId", delta.siteId)
+        .eq("route", delta.route)
+        .eq("bucketStart", delta.bucketStart)
+        .eq("shard", delta.shard),
+    )
+    .unique();
+  if (!existing && delta.route !== SITE_MAP_OTHER_ROUTE) {
+    // A new route row spends one bounded read per fold to respect the daily
+    // cap; past it, the day's remaining routes fold into "(other)".
+    const capRows = MAX_SITE_MAP_ROUTES_PER_DAY * REPORT_ROLLUP_SHARDS;
+    const dayKey = `${delta.siteId}:${delta.bucketStart}`;
+    let dayRows = dayRowCounts.get(dayKey);
+    if (dayRows === undefined) {
+      dayRows = (
+        await ctx.db
+          .query("routeDailyRollups")
+          .withIndex("by_siteId_and_bucketStart", (range) =>
+            range
+              .eq("siteId", delta.siteId)
+              .eq("bucketStart", delta.bucketStart),
+          )
+          .take(capRows + 1)
+      ).length;
+    }
+    if (dayRows >= capRows) {
+      await upsertRouteRollup(
+        ctx,
+        { ...delta, route: SITE_MAP_OTHER_ROUTE },
+        dayRowCounts,
+      );
+      return;
+    }
+    dayRowCounts.set(dayKey, dayRows + 1);
+  }
+  const outgoing = existing?.outgoing.map((entry) => ({ ...entry })) ?? [];
+  for (const [target, count] of delta.outgoing) {
+    let entry = outgoing.find((candidate) => candidate.route === target);
+    if (!entry) {
+      const named = outgoing.filter(
+        (candidate) => candidate.route !== SITE_MAP_OTHER_ROUTE,
+      ).length;
+      const route =
+        target !== SITE_MAP_OTHER_ROUTE && named >= ROUTE_TRANSITION_SLOTS
+          ? SITE_MAP_OTHER_ROUTE
+          : target;
+      entry = outgoing.find((candidate) => candidate.route === route);
+      if (!entry) {
+        entry = { route, count: 0 };
+        outgoing.push(entry);
+      }
+    }
+    entry.count += count;
+  }
+  const fields = {
+    siteId: delta.siteId,
+    bucketStart: delta.bucketStart,
+    shard: delta.shard,
+    generation: 1 as const,
+    route: delta.route,
+    pageviews: (existing?.pageviews ?? 0) + delta.pageviews,
+    entries: (existing?.entries ?? 0) + delta.entries,
+    continued: (existing?.continued ?? 0) + delta.continued,
+    dwellMs: (existing?.dwellMs ?? 0) + delta.dwellMs,
+    dwellSamples: (existing?.dwellSamples ?? 0) + delta.dwellSamples,
+    visitorSketch: sketchWithKeys(existing?.visitorSketch, delta.visitorKeys),
+    outgoing,
+  };
+  if (existing) {
+    await ctx.db.replace("routeDailyRollups", existing._id, fields);
+  } else {
+    await ctx.db.insert("routeDailyRollups", fields);
+  }
+}
+
+async function upsertVitalRollup(ctx: MutationCtx, delta: VitalRollupDelta) {
+  const existing = await ctx.db
+    .query("vitalRollups")
+    .withIndex("by_key", (range) =>
+      range
+        .eq("siteId", delta.siteId)
+        .eq("bucketStart", delta.bucketStart)
+        .eq("device", delta.device)
+        .eq("page", delta.page)
+        .eq("shard", delta.shard),
+    )
+    .unique();
+  if (
+    !existing &&
+    delta.device === VITAL_ALL &&
+    delta.page !== VITAL_OTHER_PAGES
+  ) {
+    // A new page row spends one bounded read to respect the daily page slots;
+    // past the cap, the day's remaining pages fold into "(other)".
+    const pageRows = await ctx.db
+      .query("vitalRollups")
+      .withIndex("by_key", (range) =>
+        range
+          .eq("siteId", delta.siteId)
+          .eq("bucketStart", delta.bucketStart)
+          .eq("device", VITAL_ALL),
+      )
+      .take(VITAL_PAGE_SLOTS * REPORT_ROLLUP_SHARDS + 1);
+    if (pageRows.length > VITAL_PAGE_SLOTS * REPORT_ROLLUP_SHARDS) {
+      await upsertVitalRollup(ctx, { ...delta, page: VITAL_OTHER_PAGES });
+      return;
+    }
+  }
+  const metrics = existing?.metrics.map((entry) => ({ ...entry })) ?? [];
+  for (const [metric, addition] of delta.metrics) {
+    const entry = metrics.find((candidate) => candidate.metric === metric);
+    if (entry) {
+      entry.count += addition.count;
+      entry.sum += addition.sum;
+      entry.histogram = mergeVitalHistograms(
+        entry.histogram,
+        addition.histogram,
+      );
+    } else {
+      metrics.push({
+        metric,
+        count: addition.count,
+        sum: addition.sum,
+        histogram: [...addition.histogram],
+      });
+    }
+  }
+  const fields = {
+    siteId: delta.siteId,
+    bucketStart: delta.bucketStart,
+    device: delta.device,
+    page: delta.page,
+    shard: delta.shard,
+    metrics,
+  };
+  if (existing) {
+    await ctx.db.replace("vitalRollups", existing._id, fields);
+  } else {
+    await ctx.db.insert("vitalRollups", fields);
+  }
+}