@iann29/rastro 0.2.0 → 0.4.0

package/src/component/live.ts

@@ -1,7 +1,15 @@
 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 { internalMutation } from "./_generated/server.js";
 import { LIVE_SWEEP_INTERVAL_MS } from "./constants.js";
+import {
+  flushAggregates,
+  foldSessionDuration,
+  type AggregateDeltas,
+} from "./ingest.js";
+import { localDayTimezone } from "./localTime.js";
 
 const SWEEP_BATCH_SIZE = 500;
 
@@ -58,7 +66,7 @@ export const expire = internalMutation({
       }
       return { expired: false, rescheduled: false, stale: false };
     }
-    await ctx.db.delete("liveSessions", liveSession._id);
+    await retireLiveSessions(ctx, liveSession.siteId, [liveSession]);
     return { expired: true, rescheduled: false, stale: false };
   },
 });
@@ -89,9 +97,7 @@ export const sweep = internalMutation({
         range.eq("siteId", args.siteId).lte("expiresAt", now),
       )
       .take(SWEEP_BATCH_SIZE);
-    for (const session of expired) {
-      await ctx.db.delete("liveSessions", session._id);
-    }
+    await retireLiveSessions(ctx, args.siteId, expired);
 
     const next = await ctx.db
       .query("liveSessions")
@@ -115,3 +121,44 @@ export const sweep = internalMutation({
     return { expired: expired.length, rescheduled: true, stale: false };
   },
 });
+
+/**
+ * Deletes departed live rows and counts the time their heartbeats proved. A
+ * heartbeat only moves its session's `lastSeenAt`, and `durationMs` is what
+ * the duration counters already hold, so the difference reaches the buckets
+ * here, once, in the hour the visitor was last seen. It lands in one shard
+ * per site, so a sweep rewrites a few buckets however many visitors it
+ * retires.
+ */
+async function retireLiveSessions(
+  ctx: MutationCtx,
+  siteId: Id<"sites">,
+  rows: Doc<"liveSessions">[],
+) {
+  if (rows.length === 0) return;
+  const site = await ctx.db.get("sites", siteId);
+  const timezone = localDayTimezone(site?.timezone);
+  const aggregateDeltas: AggregateDeltas = new Map();
+  for (const row of rows) {
+    await ctx.db.delete("liveSessions", row._id);
+    const session = await ctx.db
+      .query("sessions")
+      .withIndex("by_siteId_and_sessionId", (range) =>
+        range.eq("siteId", siteId).eq("sessionId", row.sessionId),
+      )
+      .unique();
+    if (!session) continue;
+    const durationMs = session.lastSeenAt - session.startedAt;
+    if (durationMs <= session.durationMs) continue;
+    await ctx.db.patch("sessions", session._id, { durationMs });
+    foldSessionDuration(
+      aggregateDeltas,
+      siteId,
+      siteId,
+      session.lastSeenAt,
+      durationMs - session.durationMs,
+      timezone,
+    );
+  }
+  await flushAggregates(ctx, aggregateDeltas);
+}

package/src/component/reports.ts

@@ -346,14 +346,19 @@ export const overview = query({
     const bucketCount = localDays
       ? bucketStarts.length
       : Math.floor((lastBucket - firstBucket) / intervalMs) + 1;
-    const perSiteLimit =
-      bucketCount *
-      (interval === "hour" ? HOURLY_AGGREGATE_SHARDS : AGGREGATE_SHARDS);
+    const shards =
+      interval === "hour" ? HOURLY_AGGREGATE_SHARDS : AGGREGATE_SHARDS;
+    const perSiteLimit = bucketCount * shards;
     if (perSiteLimit * siteIds.length > MAX_OVERVIEW_AGGREGATE_ROWS) {
+      // The row budget, not MAX_REPORT_RANGE_DAYS, bounds the overview: 101
+      // days for one site and 10 for ten; 24 hours for two, 5 for ten.
+      const maximumBuckets = Math.floor(
+        MAX_OVERVIEW_AGGREGATE_ROWS / (shards * siteIds.length),
+      );
       fail(
         "LIMIT_EXCEEDED",
-        "overview range is too wide for the requested number of sites",
-        { maximumAggregateRows: MAX_OVERVIEW_AGGREGATE_ROWS },
+        `overview range is too wide: ${siteIds.length === 1 ? "one site" : `${siteIds.length} sites`} can read at most ${maximumBuckets} ${interval}s`,
+        { maximumAggregateRows: MAX_OVERVIEW_AGGREGATE_ROWS, maximumBuckets },
       );
     }
     const totals = emptyTotals();
@@ -382,7 +387,13 @@ export const overview = query({
     await assertSourceAvailable(ctx, siteIds, [overviewDataset], from);
 
     for (const siteId of siteIds) {
-      const buckets = await ctx.db
+      // Iterated rather than taken whole: within the row budget a busy range
+      // can still cross the bytes a query may read. Values are length-capped,
+      // so sixteen buckets stay far below the reserve, and running out fails
+      // with REPORT_INCOMPLETE, as the feature reports do, instead of a raw
+      // limit error.
+      const buckets: Doc<"aggregateBuckets">[] = [];
+      for await (const bucket of ctx.db
         .query("aggregateBuckets")
         .withIndex("by_siteId_and_granularity_and_bucketStart", (range) =>
           range
@@ -390,8 +401,13 @@ export const overview = query({
             .eq("granularity", granularity)
             .gte("bucketStart", firstBucket)
             .lte("bucketStart", lastBucket),
-        )
-        .take(perSiteLimit + 1);
+        )) {
+        buckets.push(bucket);
+        if (buckets.length > perSiteLimit) break;
+        if (buckets.length % 16 === 0) {
+          await requireFeatureReadHeadroom(ctx, "overview aggregate buckets");
+        }
+      }
       failIfIncomplete(buckets, perSiteLimit, "overview aggregate buckets");
       for (const bucket of buckets) {
         if (
@@ -932,6 +948,102 @@ async function readRouteRollups(
   return { rows, completeFrom: cutAt + DAY_MS };
 }
 
+/** Metadata for a selected session, independent of list pagination. */
+export const getSession = query({
+  args: { siteId: v.id("sites"), sessionId: v.string() },
+  returns: v.union(sessionDocumentValidator, v.null()),
+  handler: async (ctx, args) => {
+    const session = await ctx.db
+      .query("sessions")
+      .withIndex("by_siteId_and_sessionId", (q) =>
+        q.eq("siteId", args.siteId).eq("sessionId", args.sessionId),
+      )
+      .unique();
+    if (!session) return null;
+    const {
+      geoLookupAttemptedAt: _geo,
+      lastPageviewAt: _pageview,
+      ...result
+    } = session;
+    return result;
+  },
+});
+
+/** Exact commissions alongside overview's period revenue/conversion totals. */
+export const revenueSummary = query({
+  args: { siteIds: v.array(v.id("sites")), from: v.number(), to: v.number() },
+  returns: v.object({ commissionCents: v.number() }),
+  handler: async (ctx, args) => {
+    const siteIds = validateSiteIds(args.siteIds);
+    validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    const fullFrom = Math.ceil(args.from / DAY_MS) * DAY_MS;
+    const fullTo = Math.floor((args.to + 1) / DAY_MS) * DAY_MS;
+    let commissionCents = 0;
+    let rowsRead = 0;
+    const currencies = new Set<string>();
+    for (const siteId of siteIds) {
+      const site = await ctx.db.get("sites", siteId);
+      if (!site) fail("NOT_FOUND", "site not found");
+      currencies.add(site.currency ?? "USD");
+      if (currencies.size > 1)
+        fail("CURRENCY_MISMATCH", "revenue sites must use the same currency");
+      if (fullFrom < fullTo) {
+        await assertSourceAvailable(
+          ctx,
+          [siteId],
+          ["affiliateStats"],
+          fullFrom,
+        );
+        const stats = await ctx.db
+          .query("affiliateDailyStats")
+          .withIndex("by_siteId_and_bucketStart", (q) =>
+            q
+              .eq("siteId", siteId)
+              .gte("bucketStart", fullFrom)
+              .lt("bucketStart", fullTo),
+          )
+          .take(MAX_REPORT_BUCKETS - rowsRead + 1);
+        rowsRead += stats.length;
+        failIfIncomplete(
+          stats,
+          MAX_REPORT_BUCKETS - (rowsRead - stats.length),
+          "commission buckets",
+        );
+        for (const row of stats) commissionCents += row.commissionCents;
+      }
+      // ponytail: boundary scans cap at MAX_REPORT_BUCKETS; add hourly commission
+      // rollups if busy partial days exceed this explicit report limit.
+      // Daily stats cannot answer partial days (24h and local-day windows).
+      // Read only those edges from the trusted ledger, never round the period.
+      const edges: Array<[number, number]> =
+        fullFrom < fullTo
+          ? [
+              [args.from, fullFrom - 1],
+              [fullTo, args.to],
+            ]
+          : [[args.from, args.to]];
+      for (const [from, to] of edges) {
+        if (from > to) continue;
+        await assertSourceAvailable(ctx, [siteId], ["conversions"], from);
+        const rows = await ctx.db
+          .query("conversions")
+          .withIndex("by_siteId_and_timestamp", (q) =>
+            q.eq("siteId", siteId).gte("timestamp", from).lte("timestamp", to),
+          )
+          .take(MAX_REPORT_BUCKETS - rowsRead + 1);
+        rowsRead += rows.length;
+        failIfIncomplete(
+          rows,
+          MAX_REPORT_BUCKETS - (rowsRead - rows.length),
+          "commission boundary conversions",
+        );
+        for (const row of rows) commissionCents += row.commissionCents;
+      }
+    }
+    return { commissionCents };
+  },
+});
+
 export const listSessions = query({
   args: {
     siteId: v.id("sites"),

package/src/component/rollupStore.ts

@@ -13,6 +13,7 @@ import {
   MAX_FUNNEL_STEPS,
   MAX_SITE_MAP_ROUTES_PER_DAY,
   REPORT_ROLLUP_SHARDS,
+  ROLLUP_FOLD_DEBOUNCE_MS,
   ROLLUP_FOLD_LEASE_MS,
   ROUTE_TRANSITION_SLOTS,
   SITE_MAP_OTHER_ROUTE,
@@ -36,8 +37,8 @@ import {
  * 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.
+ * into the rows about a second later (see rollups.ts), so every rollup row
+ * has a single writer.
  */
 
 export type GoalRollupDelta = {
@@ -221,6 +222,10 @@ const queuedVitalValidator = v.object({
 export const reportRollupQueueFields = {
   siteId: v.id("sites"),
   createdAt: v.number(),
+  // Failed runs in a row with this batch at the head of the queue, and when
+  // it was set aside after too many (see rollups.ts).
+  foldFailures: v.optional(v.number()),
+  deadLetteredAt: v.optional(v.number()),
   goals: v.array(queuedGoalValidator),
   funnels: v.array(queuedFunnelValidator),
   funnelSteps: v.array(queuedFunnelStepValidator),
@@ -456,8 +461,9 @@ export function mergeQueuedRollups(
 /**
  * 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.
+ * state, which no batch rewrites while a fold is pending and 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,
@@ -482,6 +488,7 @@ export async function ensureRollupFold(
     .query("rollupFoldStates")
     .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
     .unique();
+  // A held lease means a chain is running and will fold this batch.
   if (state && state.leaseUntil > now) return;
   const token = crypto.randomUUID();
   const leaseUntil = now + ROLLUP_FOLD_LEASE_MS;
@@ -490,7 +497,11 @@ export async function ensureRollupFold(
   } else {
     await ctx.db.insert("rollupFoldStates", { siteId, leaseUntil, token });
   }
-  await ctx.scheduler.runAfter(0, internal.rollups.fold, { siteId, token });
+  // Debounced, so every batch of the next second joins this run.
+  await ctx.scheduler.runAfter(ROLLUP_FOLD_DEBOUNCE_MS, internal.rollups.fold, {
+    siteId,
+    token,
+  });
 }
 
 // ---------------------------------------------------------------------------
@@ -632,8 +643,9 @@ export async function flushReportRollups(
   for (const delta of deltas.routes.values()) {
     await upsertRouteRollup(ctx, delta, routeDayRowCounts);
   }
+  const vitalDayPageRows = new Map<string, number>();
   for (const delta of deltas.vitals.values()) {
-    await upsertVitalRollup(ctx, delta);
+    await upsertVitalRollup(ctx, delta, vitalDayPageRows);
   }
 }
 
@@ -731,7 +743,11 @@ async function upsertRouteRollup(
   }
 }
 
-async function upsertVitalRollup(ctx: MutationCtx, delta: VitalRollupDelta) {
+async function upsertVitalRollup(
+  ctx: MutationCtx,
+  delta: VitalRollupDelta,
+  dayPageRows: Map<string, number>,
+) {
   const existing = await ctx.db
     .query("vitalRollups")
     .withIndex("by_key", (range) =>
@@ -748,21 +764,36 @@ async function upsertVitalRollup(ctx: MutationCtx, delta: VitalRollupDelta) {
     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 });
+    // New page rows spend one bounded read per day and fold run to respect
+    // the daily page slots, as routes do: rereading it for every new page let
+    // a fold of many distinct URLs pass the read limit and fail every retry.
+    // Past the cap, the day's remaining pages fold into "(other)".
+    const capRows = VITAL_PAGE_SLOTS * REPORT_ROLLUP_SHARDS;
+    const dayKey = `${delta.siteId}:${delta.bucketStart}`;
+    let pageRows = dayPageRows.get(dayKey);
+    if (pageRows === undefined) {
+      pageRows = (
+        await ctx.db
+          .query("vitalRollups")
+          .withIndex("by_key", (range) =>
+            range
+              .eq("siteId", delta.siteId)
+              .eq("bucketStart", delta.bucketStart)
+              .eq("device", VITAL_ALL),
+          )
+          .take(capRows + 1)
+      ).length;
+      dayPageRows.set(dayKey, pageRows);
+    }
+    if (pageRows > capRows) {
+      await upsertVitalRollup(
+        ctx,
+        { ...delta, page: VITAL_OTHER_PAGES },
+        dayPageRows,
+      );
       return;
     }
+    dayPageRows.set(dayKey, pageRows + 1);
   }
   const metrics = existing?.metrics.map((entry) => ({ ...entry })) ?? [];
   for (const [metric, addition] of delta.metrics) {

package/src/component/rollups.ts

@@ -1,9 +1,14 @@
-import { v } from "convex/values";
+import { v, type Infer } from "convex/values";
 import { internal } from "./_generated/api.js";
+import type { Id } from "./_generated/dataModel.js";
+import type { MutationCtx } from "./_generated/server.js";
 import { internalMutation } from "./_generated/server.js";
 import {
+  ROLLUP_DEAD_LETTER_RETENTION_MS,
   ROLLUP_FOLD_BATCH_DOCS,
+  ROLLUP_FOLD_DEBOUNCE_MS,
   ROLLUP_FOLD_LEASE_MS,
+  ROLLUP_FOLD_MAX_FAILURES,
   ROLLUP_FOLD_MAX_ROWS,
 } from "./constants.js";
 import {
@@ -13,24 +18,65 @@ import {
   mergeQueuedRollups,
 } from "./rollupStore.js";
 
+const foldArgs = { siteId: v.id("sites"), token: v.string() };
+const foldResult = v.object({
+  folded: v.number(),
+  remaining: v.boolean(),
+  stale: v.boolean(),
+});
+type FoldResult = Infer<typeof foldResult>;
+
+// A failed run's reads still count against the transaction that catches it,
+// so a run stops short of the platform's read limits (16 MiB, 32,000
+// documents, 4,096 queries) and leaves room to record the failure.
+const RUN_READ_LIMITS = {
+  bytesRead: 15 * 1024 * 1024,
+  documentsRead: 31_000,
+  databaseQueries: 4_000,
+};
+
 /**
  * Folds a site's queued report rollup deltas into the rollup rows. Exactly
- * one chain runs per site: ingestion starts one when no lease is held, every
- * run carries the token of the lease it belongs to, and a run whose token is
- * no longer current exits without touching anything. A run that finds more
- * queued documents than it could take continues at once; a run that drains
- * the queue releases the lease. A batch that lands while a run is draining
- * is never stranded: the run read the queue range the batch inserted into
- * and the batch read the lease the run released, so one of the two retries
- * and sees the other's work.
+ * one chain runs per site: a batch that finds the lease free takes it and
+ * schedules the first run a debounce away (see ensureRollupFold), every run
+ * carries the token of that lease, and a run whose token is no longer
+ * current exits without touching anything. Batches that land while the
+ * lease is held only append to the queue; they never write the lease or
+ * schedule anything.
+ *
+ * A run folds the batches created before it began and, if it folded any,
+ * schedules the next run a debounce later (at once while a backlog remains),
+ * so a steady stream costs one run per second and batches landing during a
+ * run never conflict with it. Only a run that finds nothing left releases
+ * the lease, and that run reads the whole queue range: a batch landing
+ * concurrently either commits first, and the run retries and folds it, or
+ * reads the released lease and starts a new chain.
+ *
+ * A run executes as a nested transaction, so one that throws is rolled back
+ * whole and its batches stay queued; the oldest is charged the failure and
+ * the next run retries it alone. After ROLLUP_FOLD_MAX_FAILURES runs in a
+ * row it is set aside as a dead letter and the queue moves on.
  */
 export const fold = internalMutation({
-  args: { siteId: v.id("sites"), token: v.string() },
-  returns: v.object({
-    folded: v.number(),
-    remaining: v.boolean(),
-    stale: v.boolean(),
-  }),
+  args: foldArgs,
+  returns: foldResult,
+  handler: async (ctx, args) => {
+    try {
+      const result: FoldResult = await ctx.runMutation(
+        internal.rollups.foldRun,
+        args,
+        { transactionLimits: RUN_READ_LIMITS },
+      );
+      return result;
+    } catch (error) {
+      return await setAsideFailedRun(ctx, args, error);
+    }
+  },
+});
+
+export const foldRun = internalMutation({
+  args: foldArgs,
+  returns: foldResult,
   handler: async (ctx, args) => {
     const state = await ctx.db
       .query("rollupFoldStates")
@@ -42,20 +88,31 @@ export const fold = internalMutation({
     const now = Date.now();
     const queued = await ctx.db
       .query("reportRollupQueue")
-      .withIndex("by_siteId_and_createdAt", (range) =>
-        range.eq("siteId", args.siteId),
+      .withIndex("by_siteId_and_deadLetteredAt_and_createdAt", (range) =>
+        range
+          .eq("siteId", args.siteId)
+          .eq("deadLetteredAt", undefined)
+          .lte("createdAt", now),
       )
-      .order("asc")
       .take(ROLLUP_FOLD_BATCH_DOCS + 1);
     if (queued.length === 0) {
-      if (state.leaseUntil > now) {
+      if (await oldestQueued(ctx, args.siteId)) {
+        await ctx.scheduler.runAfter(
+          ROLLUP_FOLD_DEBOUNCE_MS,
+          internal.rollups.fold,
+          args,
+        );
+      } else if (state.leaseUntil > now) {
         await ctx.db.patch("rollupFoldStates", state._id, { leaseUntil: now });
       }
       return { folded: 0, remaining: false, stale: false };
     }
+    // A batch that already failed a run is retried alone, so the next
+    // failure is charged to the batch that causes it.
+    const batchDocs = queued[0].foldFailures ? 1 : ROLLUP_FOLD_BATCH_DOCS;
     const deltas = createReportRollupDeltas();
     let taken = 0;
-    for (const document of queued.slice(0, ROLLUP_FOLD_BATCH_DOCS)) {
+    for (const document of queued.slice(0, batchDocs)) {
       mergeQueuedRollups(deltas, document);
       taken += 1;
       if (countReportRollupRows(deltas) >= ROLLUP_FOLD_MAX_ROWS) break;
@@ -64,19 +121,71 @@ export const fold = internalMutation({
     for (const document of queued.slice(0, taken)) {
       await ctx.db.delete("reportRollupQueue", document._id);
     }
-    const remaining = queued.length > taken;
-    if (remaining) {
-      // Renew only when the lease is halfway gone, so the state document is
-      // rewritten about twice a minute under load rather than on every run.
-      if (state.leaseUntil - now < ROLLUP_FOLD_LEASE_MS / 2) {
-        await ctx.db.patch("rollupFoldStates", state._id, {
-          leaseUntil: now + ROLLUP_FOLD_LEASE_MS,
-        });
-      }
-      await ctx.scheduler.runAfter(0, internal.rollups.fold, args);
-    } else {
-      await ctx.db.patch("rollupFoldStates", state._id, { leaseUntil: now });
+    // Renew only when the lease is halfway gone, so the state document is
+    // rewritten about twice a minute while batches keep arriving.
+    if (state.leaseUntil - now < ROLLUP_FOLD_LEASE_MS / 2) {
+      await ctx.db.patch("rollupFoldStates", state._id, {
+        leaseUntil: now + ROLLUP_FOLD_LEASE_MS,
+      });
     }
+    const remaining = queued.length > taken;
+    await ctx.scheduler.runAfter(
+      remaining ? 0 : ROLLUP_FOLD_DEBOUNCE_MS,
+      internal.rollups.fold,
+      args,
+    );
     return { folded: taken, remaining, stale: false };
   },
 });
+
+/** The oldest batch still waiting to fold; dead letters are skipped. */
+function oldestQueued(ctx: MutationCtx, siteId: Id<"sites">) {
+  return ctx.db
+    .query("reportRollupQueue")
+    .withIndex("by_siteId_and_deadLetteredAt_and_createdAt", (range) =>
+      range.eq("siteId", siteId).eq("deadLetteredAt", undefined),
+    )
+    .first();
+}
+
+async function setAsideFailedRun(
+  ctx: MutationCtx,
+  args: { siteId: Id<"sites">; token: string },
+  error: unknown,
+): Promise<FoldResult> {
+  const state = await ctx.db
+    .query("rollupFoldStates")
+    .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
+    .unique();
+  const head = await oldestQueued(ctx, args.siteId);
+  if (!head || state?.token !== args.token) throw error;
+  const now = Date.now();
+  const foldFailures = (head.foldFailures ?? 0) + 1;
+  if (foldFailures < ROLLUP_FOLD_MAX_FAILURES) {
+    await ctx.db.patch("reportRollupQueue", head._id, { foldFailures });
+  } else {
+    console.error(
+      `rollup fold set aside queued batch ${head._id} of site ${args.siteId} after ${foldFailures} failed runs`,
+      error,
+    );
+    await ctx.db.patch("reportRollupQueue", head._id, {
+      foldFailures,
+      deadLetteredAt: now,
+    });
+    // Dead letters stay for inspection; each new one retires expired ones.
+    const expired = await ctx.db
+      .query("reportRollupQueue")
+      .withIndex("by_siteId_and_deadLetteredAt_and_createdAt", (range) =>
+        range
+          .eq("siteId", args.siteId)
+          .gte("deadLetteredAt", 0)
+          .lt("deadLetteredAt", now - ROLLUP_DEAD_LETTER_RETENTION_MS),
+      )
+      .take(ROLLUP_FOLD_BATCH_DOCS);
+    for (const document of expired) {
+      await ctx.db.delete("reportRollupQueue", document._id);
+    }
+  }
+  await ctx.scheduler.runAfter(0, internal.rollups.fold, args);
+  return { folded: 0, remaining: true, stale: false };
+}

package/src/component/schema.ts

@@ -248,10 +248,11 @@ export default defineSchema({
     .index("by_siteId_and_bucketStart", ["siteId", "bucketStart"]),
 
   // Rollup deltas wait here between ingestion and the fold job; see
-  // rollupStore.ts. Rows are deleted as they are folded.
+  // rollups.ts. Rows are deleted as they are folded; a batch that keeps
+  // failing is set aside with `deadLetteredAt` and skipped.
   reportRollupQueue: defineTable(reportRollupQueueFields).index(
-    "by_siteId_and_createdAt",
-    ["siteId", "createdAt"],
+    "by_siteId_and_deadLetteredAt_and_createdAt",
+    ["siteId", "deadLetteredAt", "createdAt"],
   ),
 
   rollupFoldStates: defineTable(rollupFoldStateFields).index("by_siteId", [
@@ -441,6 +442,8 @@ export default defineSchema({
 
   ingestWindows: defineTable({
     siteId: v.id("sites"),
+    // A session ID, or `~client:` plus a salted daily client-network key for
+    // the per-client budget; no sanitized session ID starts with `~`.
     sessionId: v.string(),
     windowStart: v.number(),
     eventCount: v.number(),