@iann29/rastro 0.1.0-alpha.3 → 0.1.0-alpha.4

package/src/component/reports.ts

@@ -3,22 +3,35 @@ import {
   paginationResultValidator,
 } from "convex/server";
 import { v } from "convex/values";
-import type { Doc } from "./_generated/dataModel.js";
+import type { Doc, Id } from "./_generated/dataModel.js";
+import type { QueryCtx } from "./_generated/server.js";
 import { query } from "./_generated/server.js";
 import {
   AGGREGATE_SHARDS,
   DAY_MS,
+  FEATURE_REPORT_BYTE_RESERVE,
+  FEATURE_REPORT_DOCUMENT_RESERVE,
   HOUR_MS,
   HOURLY_AGGREGATE_SHARDS,
   MAX_AFFILIATES_PER_SITE,
   MAX_FUNNELS_PER_SITE,
+  MAX_FEATURE_ROLLUP_DAYS,
+  MAX_FEATURE_ROLLUP_ROWS,
   MAX_GOALS_PER_SITE,
   MAX_JOURNEY_EVENTS,
   MAX_LIVE_VISITORS,
   MAX_OVERVIEW_AGGREGATE_ROWS,
+  MAX_REPORT_BUCKETS,
   MAX_REPORT_RANGE_DAYS,
   MAX_REPORT_SITES,
+  REPORT_ROLLUP_SHARDS,
 } from "./constants.js";
+import {
+  createVisitorSketch,
+  estimateVisitors,
+  unionVisitorSketches,
+  type VisitorSketch,
+} from "./cardinality.js";
 import { fail } from "./errors.js";
 import {
   compareJourneyEvents,
@@ -102,6 +115,30 @@ const topItemValidator = v.object({
   count: v.number(),
   revenueCents: v.number(),
 });
+const coverageStateValidator = v.union(
+  v.literal("complete"),
+  v.literal("partial"),
+  v.literal("retained"),
+  v.literal("unavailable"),
+);
+const resultCoverageValidator = v.object({
+  state: coverageStateValidator,
+  generation: v.union(v.number(), v.null()),
+  availableFrom: v.union(v.number(), v.null()),
+  availableThrough: v.union(v.number(), v.null()),
+  retainedBefore: v.union(v.number(), v.null()),
+});
+const rangeSemanticsValidator = v.object({
+  from: v.number(),
+  to: v.number(),
+  boundary: v.literal("inclusive"),
+  timezone: v.literal("UTC"),
+});
+const reportMetadataValidator = v.object({
+  basis: v.union(v.literal("dailyRollup"), v.literal("boundedLegacy")),
+  coverage: resultCoverageValidator,
+  range: rangeSemanticsValidator,
+});
 
 export const overview = query({
   args: {
@@ -124,6 +161,35 @@ export const overview = query({
     topBrowsers: v.array(topItemValidator),
     topEvents: v.array(topItemValidator),
     topGoals: v.array(topItemValidator),
+    metadata: v.object({
+      visitors: v.object({
+        basis: v.union(
+          v.literal("estimatedUnique"),
+          v.literal("bucketOccurrences"),
+        ),
+        exact: v.boolean(),
+        legacyIncomplete: v.boolean(),
+        sketchVersion: v.union(v.number(), v.null()),
+        precision: v.union(v.number(), v.null()),
+      }),
+      breakdowns: v.object({
+        topSources: v.literal("eventVolume"),
+        topPages: v.literal("eventVolume"),
+        topCountries: v.literal("eventVolume"),
+        topDevices: v.literal("eventVolume"),
+        topBrowsers: v.literal("eventVolume"),
+        topEvents: v.literal("eventVolume"),
+        topGoals: v.literal("goalCompletionVolume"),
+      }),
+      coverage: resultCoverageValidator,
+      range: rangeSemanticsValidator,
+      features: v.object({
+        sessionReplay: v.literal("unsupported"),
+        errorInsights: v.literal("unsupported"),
+        outboundLinks: v.literal("eventVolume"),
+        botDetection: v.literal("unsupported"),
+      }),
+    }),
   }),
   handler: async (ctx, args) => {
     const siteIds = validateSiteIds(args.siteIds);
@@ -145,6 +211,7 @@ export const overview = query({
       fail("INVALID_ARGUMENT", "hourly reports are limited to 24 hours");
     }
     const intervalMs = interval === "hour" ? HOUR_MS : DAY_MS;
+    requireAlignedRange(from, to, intervalMs, `${interval} overview`);
     const firstBucket = Math.floor(from / intervalMs) * intervalMs;
     const lastBucket = Math.floor(to / intervalMs) * intervalMs;
     const bucketCount = Math.floor((lastBucket - firstBucket) / intervalMs) + 1;
@@ -159,7 +226,16 @@ export const overview = query({
     }
     const totals = emptyTotals();
     const points = new Map<number, MetricTotals>();
+    const visitorSketch = createVisitorSketch();
+    let mergedVisitorSketch = visitorSketch;
+    const pointVisitorSketches = new Map<number, VisitorSketch>();
+    let visitorsComplete = true;
     const dimensions = new Map<string, { value: string; count: number; revenueCents: number }>();
+    const overviewDataset = interval === "hour"
+      ? "overviewHour" as const
+      : "overviewDay" as const;
+
+    await assertSourceAvailable(ctx, siteIds, [overviewDataset], from);
 
     for (const siteId of siteIds) {
       const buckets = await ctx.db
@@ -171,12 +247,29 @@ export const overview = query({
             .gte("bucketStart", firstBucket)
             .lte("bucketStart", lastBucket),
         )
-        .take(perSiteLimit);
+        .take(perSiteLimit + 1);
+      failIfIncomplete(buckets, perSiteLimit, "overview aggregate buckets");
       for (const bucket of buckets) {
         addMetrics(totals, bucket);
         const point = points.get(bucket.bucketStart) ?? emptyTotals();
         addMetrics(point, bucket);
         points.set(bucket.bucketStart, point);
+        if (bucket.visitorSketch && bucket.visitorSketchComplete === true) {
+          mergedVisitorSketch = unionVisitorSketches(
+            mergedVisitorSketch,
+            bucket.visitorSketch,
+          );
+          pointVisitorSketches.set(
+            bucket.bucketStart,
+            unionVisitorSketches(
+              pointVisitorSketches.get(bucket.bucketStart) ??
+                createVisitorSketch(bucket.visitorSketch.precision),
+              bucket.visitorSketch,
+            ),
+          );
+        } else if (bucket.events > 0) {
+          visitorsComplete = false;
+        }
         for (const dimension of bucket.dimensions) {
           const key = `${dimension.type}:${dimension.value}`;
           const current = dimensions.get(key) ?? {
@@ -197,6 +290,20 @@ export const overview = query({
         .map(([, value]) => value)
         .sort((left, right) => right.count - left.count || left.value.localeCompare(right.value))
         .slice(0, 10);
+    if (visitorsComplete) {
+      totals.visitors = estimateVisitors(mergedVisitorSketch);
+      for (const [timestamp, point] of points) {
+        point.visitors = estimateVisitors(
+          pointVisitorSketches.get(timestamp) ?? createVisitorSketch(),
+        );
+      }
+    }
+    const coverage = await coverageForRange(ctx, siteIds, from, to, {
+      datasets: [overviewDataset],
+      complete: visitorsComplete,
+    });
+    const visitorBasis: "estimatedUnique" | "bucketOccurrences" =
+      visitorsComplete ? "estimatedUnique" : "bucketOccurrences";
     return {
       from,
       to,
@@ -213,6 +320,32 @@ export const overview = query({
       topBrowsers: top("browser"),
       topEvents: top("event"),
       topGoals: top("goal"),
+      metadata: {
+        visitors: {
+          basis: visitorBasis,
+          exact: false,
+          legacyIncomplete: !visitorsComplete,
+          sketchVersion: visitorsComplete ? 1 : null,
+          precision: visitorsComplete ? 6 : null,
+        },
+        breakdowns: {
+          topSources: "eventVolume" as const,
+          topPages: "eventVolume" as const,
+          topCountries: "eventVolume" as const,
+          topDevices: "eventVolume" as const,
+          topBrowsers: "eventVolume" as const,
+          topEvents: "eventVolume" as const,
+          topGoals: "goalCompletionVolume" as const,
+        },
+        coverage,
+        range: rangeSemantics(from, to),
+        features: {
+          sessionReplay: "unsupported" as const,
+          errorInsights: "unsupported" as const,
+          outboundLinks: "eventVolume" as const,
+          botDetection: "unsupported" as const,
+        },
+      },
     };
   },
 });
@@ -282,6 +415,7 @@ export const listSessions = query({
   returns: paginationResultValidator(sessionDocumentValidator),
   handler: async (ctx, args) => {
     validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    await assertSourceAvailable(ctx, [args.siteId], ["sessions"], args.from);
     const pagination = parseKeysetPagination(args.paginationOpts, {
       kind: "sessions",
       siteId: String(args.siteId),
@@ -352,6 +486,7 @@ export const sessionJourney = query({
   returns: paginationResultValidator(eventDocumentValidator),
   handler: async (ctx, args) => {
     validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    await assertSourceAvailable(ctx, [args.siteId], ["events"], args.from);
     const pagination = parseJourneyPagination(args.paginationOpts, {
       kind: "events",
       siteId: String(args.siteId),
@@ -382,6 +517,7 @@ export const listConversions = query({
   returns: paginationResultValidator(conversionDocumentValidator),
   handler: async (ctx, args) => {
     validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    await assertSourceAvailable(ctx, [args.siteId], ["conversions"], args.from);
     const pagination = parseKeysetPagination(args.paginationOpts, {
       kind: "conversions",
       siteId: String(args.siteId),
@@ -450,6 +586,7 @@ export const visitorJourney = query({
   handler: async (ctx, args) => {
     const siteIds = validateSiteIds(args.siteIds);
     validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    await assertSourceAvailable(ctx, siteIds, ["events"], args.from);
     const limit = args.limit ?? 200;
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_JOURNEY_EVENTS) {
       fail("INVALID_ARGUMENT", `limit must be an integer between 1 and ${MAX_JOURNEY_EVENTS}`);
@@ -485,36 +622,81 @@ export const goalsReport = query({
   returns: v.object({
     goals: v.array(goalReportItemValidator),
     truncated: v.boolean(),
+    metadata: reportMetadataValidator,
   }),
   handler: async (ctx, args) => {
     validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
-    const goals = await ctx.db
+    const goalRows = await ctx.db
       .query("goals")
       .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
-      .take(MAX_GOALS_PER_SITE);
-    const completions = await ctx.db
-      .query("goalCompletions")
-      .withIndex("by_siteId_and_timestamp", (range) =>
-        range
-          .eq("siteId", args.siteId)
-          .gte("timestamp", args.from)
-          .lte("timestamp", args.to),
-      )
-      .take(5_001);
+      .take(MAX_GOALS_PER_SITE + 1);
+    failIfIncomplete(goalRows, MAX_GOALS_PER_SITE, "goal definitions");
+    const goals = goalRows;
     const totals = new Map<string, { completions: number; valueCents: number }>();
-    for (const completion of completions.slice(0, 5_000)) {
-      const key = String(completion.goalId);
-      const total = totals.get(key) ?? { completions: 0, valueCents: 0 };
-      total.completions += 1;
-      total.valueCents += completion.valueCents;
-      totals.set(key, total);
+    const useRollups = await dailyRollupsAvailable(
+      ctx,
+      args.siteId,
+      args.from,
+      args.to,
+      "goalRollups",
+    );
+    const rollups = useRollups
+      ? await loadGoalDailyRollups(
+          ctx,
+          args.siteId,
+          goals.map((goal) => goal._id),
+          args.from,
+          args.to,
+        )
+      : null;
+    if (rollups) {
+      for (const row of rollups) {
+        const key = String(row.goalId);
+        const total = totals.get(key) ?? { completions: 0, valueCents: 0 };
+        total.completions += row.completions;
+        total.valueCents += row.valueCents;
+        totals.set(key, total);
+      }
+    } else {
+      await assertSourceAvailable(
+        ctx,
+        [args.siteId],
+        ["goalCompletions"],
+        args.from,
+      );
+      const completions = await ctx.db
+        .query("goalCompletions")
+        .withIndex("by_siteId_and_timestamp", (range) =>
+          range
+            .eq("siteId", args.siteId)
+            .gte("timestamp", args.from)
+            .lte("timestamp", args.to),
+        )
+        .take(MAX_REPORT_BUCKETS + 1);
+      failIfIncomplete(completions, MAX_REPORT_BUCKETS, "goal completions");
+      for (const completion of completions) {
+        const key = String(completion.goalId);
+        const total = totals.get(key) ?? { completions: 0, valueCents: 0 };
+        total.completions += 1;
+        total.valueCents += completion.valueCents;
+        totals.set(key, total);
+      }
     }
     return {
       goals: goals.map((goal) => ({
         ...goal,
         ...(totals.get(String(goal._id)) ?? { completions: 0, valueCents: 0 }),
       })),
-      truncated: completions.length > 5_000,
+      truncated: false,
+      metadata: {
+        basis: rollups ? "dailyRollup" as const : "boundedLegacy" as const,
+        coverage: await coverageForRange(ctx, [args.siteId], args.from, args.to, {
+          datasets: [rollups ? "goalRollups" : "goalCompletions"],
+          complete: true,
+          generation: rollups ? 1 : null,
+        }),
+        range: rangeSemantics(args.from, args.to),
+      },
     };
   },
 });
@@ -526,6 +708,7 @@ const funnelReportItemValidator = funnelFieldsValidator.extend({
     v.object({ step: v.number(), name: v.string(), entrants: v.number(), completions: v.number() }),
   ),
   truncated: v.boolean(),
+  metadata: reportMetadataValidator,
 });
 
 export const funnelsReport = query({
@@ -533,29 +716,74 @@ export const funnelsReport = query({
   returns: v.array(funnelReportItemValidator),
   handler: async (ctx, args) => {
     validateRange(args.from, args.to, 90);
-    const funnels = await ctx.db
+    requireAlignedRange(args.from, args.to, DAY_MS, "funnel report");
+    const funnelRows = await ctx.db
       .query("funnels")
       .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
-      .take(MAX_FUNNELS_PER_SITE);
+      .take(MAX_FUNNELS_PER_SITE + 1);
+    failIfIncomplete(funnelRows, MAX_FUNNELS_PER_SITE, "funnel definitions");
+    const funnels = funnelRows;
+    const useRollups = await dailyRollupsAvailable(
+      ctx,
+      args.siteId,
+      args.from,
+      args.to,
+      "funnelRollups",
+    );
+    const rollups = useRollups
+      ? await loadFunnelDailyRollups(
+          ctx,
+          args.siteId,
+          funnels.map((funnel) => funnel._id),
+          args.from,
+          args.to,
+        )
+      : null;
+    if (!rollups) {
+      await assertSourceAvailable(
+        ctx,
+        [args.siteId],
+        ["funnelSteps"],
+        args.from,
+      );
+    }
+    const reportCoverage = await coverageForRange(
+      ctx,
+      [args.siteId],
+      args.from,
+      args.to,
+      {
+        datasets: [rollups ? "funnelRollups" : "funnelSteps"],
+        complete: true,
+        generation: rollups ? 1 : null,
+      },
+    );
     const reports = [];
     for (const funnel of funnels) {
-      const buckets = await ctx.db
-        .query("funnelStepBuckets")
-        .withIndex("by_siteId_and_funnelId_and_bucketStart", (range) =>
-          range
-            .eq("siteId", args.siteId)
-            .eq("funnelId", funnel._id)
-            .gte("bucketStart", Math.floor(args.from / DAY_MS) * DAY_MS)
-            .lte("bucketStart", Math.floor(args.to / DAY_MS) * DAY_MS),
-        )
-        .take(601);
       const stepsReport = funnel.steps.map((step, index) => ({
         step: index,
         name: step.name,
         entrants: 0,
         completions: 0,
       }));
-      for (const bucket of buckets.slice(0, 600)) {
+      const buckets = rollups
+        ? rollups
+            .filter((row) => row.funnelId === funnel._id)
+            .flatMap((row) => row.steps)
+        : await ctx.db
+            .query("funnelStepBuckets")
+            .withIndex("by_siteId_and_funnelId_and_bucketStart", (range) =>
+              range
+                .eq("siteId", args.siteId)
+                .eq("funnelId", funnel._id)
+                .gte("bucketStart", Math.floor(args.from / DAY_MS) * DAY_MS)
+                .lte("bucketStart", Math.floor(args.to / DAY_MS) * DAY_MS),
+            )
+            .take(MAX_REPORT_BUCKETS + 1);
+      if (!rollups) {
+        failIfIncomplete(buckets, MAX_REPORT_BUCKETS, "funnel step buckets");
+      }
+      for (const bucket of buckets) {
         const step = stepsReport[bucket.step];
         if (step) {
           step.entrants += bucket.entrants;
@@ -565,7 +793,12 @@ export const funnelsReport = query({
       reports.push({
         ...funnel,
         stepsReport,
-        truncated: buckets.length > 600,
+        truncated: false,
+        metadata: {
+          basis: rollups ? "dailyRollup" as const : "boundedLegacy" as const,
+          coverage: reportCoverage,
+          range: rangeSemantics(args.from, args.to),
+        },
       });
     }
     return reports;
@@ -587,64 +820,124 @@ export const affiliatesReport = query({
   returns: v.object({
     affiliates: v.array(affiliateReportItemValidator),
     truncated: v.boolean(),
+    metadata: reportMetadataValidator.extend({
+      uniqueVisitors: v.object({
+        basis: v.union(v.literal("estimatedUnique"), v.literal("exactLegacy")),
+        exact: v.boolean(),
+      }),
+    }),
   }),
   handler: async (ctx, args) => {
     validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    requireAlignedRange(args.from, args.to, DAY_MS, "affiliate report");
     const affiliateRows = await ctx.db
       .query("affiliates")
       .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
       .order("desc")
       .take(MAX_AFFILIATES_PER_SITE + 1);
-    const affiliates = affiliateRows.slice(0, MAX_AFFILIATES_PER_SITE);
-    const stats = await ctx.db
-      .query("affiliateDailyStats")
-      .withIndex("by_siteId_and_bucketStart", (range) =>
-        range
-          .eq("siteId", args.siteId)
-          .gte("bucketStart", Math.floor(args.from / DAY_MS) * DAY_MS)
-          .lte("bucketStart", Math.floor(args.to / DAY_MS) * DAY_MS),
-      )
-      .take(5_001);
-    const sessions = await ctx.db
-      .query("sessions")
-      .withIndex("by_siteId_and_startedAt", (range) =>
-        range
-          .eq("siteId", args.siteId)
-          .gte("startedAt", args.from)
-          .lte("startedAt", args.to),
-      )
-      .take(5_001);
+    failIfIncomplete(affiliateRows, MAX_AFFILIATES_PER_SITE, "affiliate definitions");
+    const affiliates = affiliateRows;
+    const useRollups = await dailyRollupsAvailable(
+      ctx,
+      args.siteId,
+      args.from,
+      args.to,
+      "affiliateRollups",
+    );
+    const rollups = useRollups
+      ? await loadAffiliateDailyRollups(
+          ctx,
+          args.siteId,
+          affiliates.map((affiliate) => affiliate._id),
+          args.from,
+          args.to,
+        )
+      : null;
     const visits = new Map<string, {
       visits: number;
       visitors: Set<string>;
+      sketch: VisitorSketch;
     }>();
-    for (const session of sessions.slice(0, 5_000)) {
-      if (!session.affiliateId) continue;
-      const key = String(session.affiliateId);
-      const total = visits.get(key) ?? {
-        visits: 0,
-        visitors: new Set<string>(),
-      };
-      total.visits += 1;
-      total.visitors.add(session.visitorId);
-      visits.set(key, total);
-    }
     const totals = new Map<string, {
       conversions: number;
       revenueCents: number;
       commissionCents: number;
     }>();
-    for (const row of stats.slice(0, 5_000)) {
-      const key = String(row.affiliateId);
-      const total = totals.get(key) ?? {
-        conversions: 0,
-        revenueCents: 0,
-        commissionCents: 0,
-      };
-      total.conversions += row.conversions;
-      total.revenueCents += row.revenueCents;
-      total.commissionCents += row.commissionCents;
-      totals.set(key, total);
+    if (rollups) {
+      for (const row of rollups) {
+        const key = String(row.affiliateId);
+        const traffic = visits.get(key) ?? {
+          visits: 0,
+          visitors: new Set<string>(),
+          sketch: createVisitorSketch(),
+        };
+        traffic.visits += row.visits;
+        traffic.sketch = unionVisitorSketches(
+          traffic.sketch,
+          row.visitorSketch,
+        );
+        visits.set(key, traffic);
+        const total = totals.get(key) ?? {
+          conversions: 0,
+          revenueCents: 0,
+          commissionCents: 0,
+        };
+        total.conversions += row.conversions;
+        total.revenueCents += row.revenueCents;
+        total.commissionCents += row.commissionCents;
+        totals.set(key, total);
+      }
+    } else {
+      await assertSourceAvailable(
+        ctx,
+        [args.siteId],
+        ["affiliateStats", "sessions"],
+        args.from,
+      );
+      const stats = await ctx.db
+        .query("affiliateDailyStats")
+        .withIndex("by_siteId_and_bucketStart", (range) =>
+          range
+            .eq("siteId", args.siteId)
+            .gte("bucketStart", Math.floor(args.from / DAY_MS) * DAY_MS)
+            .lte("bucketStart", Math.floor(args.to / DAY_MS) * DAY_MS),
+        )
+        .take(MAX_REPORT_BUCKETS + 1);
+      const sessions = await ctx.db
+        .query("sessions")
+        .withIndex("by_siteId_and_startedAt", (range) =>
+          range
+            .eq("siteId", args.siteId)
+            .gte("startedAt", args.from)
+            .lte("startedAt", args.to),
+        )
+        .take(MAX_REPORT_BUCKETS + 1);
+      failIfIncomplete(stats, MAX_REPORT_BUCKETS, "affiliate stat buckets");
+      failIfIncomplete(sessions, MAX_REPORT_BUCKETS, "affiliate sessions");
+      for (const session of sessions) {
+        if (!session.affiliateId) continue;
+        const key = String(session.affiliateId);
+        const total = visits.get(key) ?? {
+          visits: 0,
+          visitors: new Set<string>(),
+          sketch: createVisitorSketch(),
+        };
+        total.visits += 1;
+        total.visitors.add(session.visitorId);
+        visits.set(key, total);
+      }
+      for (const row of stats) {
+        const key = String(row.affiliateId);
+        const total = totals.get(key) ?? {
+          conversions: 0,
+          revenueCents: 0,
+          commissionCents: 0,
+        };
+        total.conversions += row.conversions;
+        total.revenueCents += row.revenueCents;
+        total.commissionCents += row.commissionCents;
+        totals.set(key, total);
+      }
     }
     return {
       affiliates: affiliates.map((affiliate) => {
@@ -658,17 +951,498 @@ export const affiliatesReport = query({
           ...affiliate,
           ...performance,
           visits: traffic?.visits ?? 0,
-          uniqueVisitors: traffic?.visitors.size ?? 0,
+          uniqueVisitors: rollups
+            ? estimateVisitors(traffic?.sketch ?? createVisitorSketch())
+            : traffic?.visitors.size ?? 0,
         };
       }),
-      truncated:
-        affiliateRows.length > MAX_AFFILIATES_PER_SITE ||
-        stats.length > 5_000 ||
-        sessions.length > 5_000,
+      truncated: false,
+      metadata: {
+        basis: rollups ? "dailyRollup" as const : "boundedLegacy" as const,
+        coverage: await coverageForRange(ctx, [args.siteId], args.from, args.to, {
+          datasets: rollups
+            ? ["affiliateRollups"]
+            : ["affiliateStats", "sessions"],
+          complete: true,
+          generation: rollups ? 1 : null,
+        }),
+        range: rangeSemantics(args.from, args.to),
+        uniqueVisitors: {
+          basis: rollups ? "estimatedUnique" as const : "exactLegacy" as const,
+          exact: !rollups,
+        },
+      },
     };
   },
 });
 
+const coverageDatasetValidator = v.union(
+  v.literal("overviewHour"),
+  v.literal("overviewDay"),
+  v.literal("events"),
+  v.literal("sessions"),
+  v.literal("conversions"),
+  v.literal("goals"),
+  v.literal("funnels"),
+  v.literal("affiliates"),
+);
+
+export const dataCoverage = query({
+  args: {
+    siteId: v.id("sites"),
+    from: v.number(),
+    to: v.number(),
+  },
+  returns: v.object({
+    siteId: v.id("sites"),
+    from: v.number(),
+    to: v.number(),
+    datasets: v.array(v.object({
+      dataset: coverageDatasetValidator,
+      coverage: resultCoverageValidator,
+    })),
+  }),
+  handler: async (ctx, args) => {
+    validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    const datasets = [
+      "overviewHour",
+      "overviewDay",
+      "events",
+      "sessions",
+      "conversions",
+      "goals",
+      "funnels",
+      "affiliates",
+    ] as const;
+    return {
+      siteId: args.siteId,
+      from: args.from,
+      to: args.to,
+      datasets: await Promise.all(datasets.map(async (dataset) => ({
+        dataset,
+        coverage: await datasetCoverageForRange(
+          ctx,
+          args.siteId,
+          dataset,
+          args.from,
+          args.to,
+        ),
+      }))),
+    };
+  },
+});
+
+async function dailyRollupsAvailable(
+  ctx: QueryCtx,
+  siteId: Id<"sites">,
+  from: number,
+  to: number,
+  dataset: "goalRollups" | "funnelRollups" | "affiliateRollups",
+) {
+  if (!isAlignedRange(from, to, DAY_MS)) return false;
+  const coverage = await ctx.db
+    .query("analyticsCoverage")
+    .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
+    .unique();
+  if (!coverage || coverage.rollupCompleteFrom > from) {
+    return false;
+  }
+  const retainedBefore = coverage.retained.find(
+    (item) => item.dataset === dataset,
+  )?.before;
+  return retainedBefore === undefined || from >= retainedBefore;
+}
+
+async function loadGoalDailyRollups(
+  ctx: QueryCtx,
+  siteId: Id<"sites">,
+  goalIds: Id<"goals">[],
+  from: number,
+  to: number,
+) {
+  const days = Math.floor((to - from) / DAY_MS) + 1;
+  requireFeatureRollupBudget(goalIds.length, days, "goal daily rollups");
+  const rows: Doc<"goalDailyRollups">[] = [];
+  for (const goalId of goalIds) {
+    const perGoalLimit = days * REPORT_ROLLUP_SHARDS;
+    const goalRows = await ctx.db
+      .query("goalDailyRollups")
+      .withIndex("by_siteId_and_goalId_and_bucketStart", (range) =>
+        range
+          .eq("siteId", siteId)
+          .eq("goalId", goalId)
+          .gte("bucketStart", from)
+          .lte("bucketStart", to),
+      )
+      .take(perGoalLimit + 1);
+    failIfIncomplete(goalRows, perGoalLimit, "goal daily rollups");
+    rows.push(...goalRows);
+    await requireFeatureReadHeadroom(ctx, "goal daily rollups");
+  }
+  return rows;
+}
+
+async function loadFunnelDailyRollups(
+  ctx: QueryCtx,
+  siteId: Id<"sites">,
+  funnelIds: Id<"funnels">[],
+  from: number,
+  to: number,
+) {
+  const days = Math.floor((to - from) / DAY_MS) + 1;
+  requireFeatureRollupBudget(funnelIds.length, days, "funnel daily rollups");
+  const rows: Doc<"funnelDailyRollups">[] = [];
+  for (const funnelId of funnelIds) {
+    const perFunnelLimit = days * REPORT_ROLLUP_SHARDS;
+    const funnelRows = await ctx.db
+      .query("funnelDailyRollups")
+      .withIndex("by_siteId_and_funnelId_and_bucketStart", (range) =>
+        range
+          .eq("siteId", siteId)
+          .eq("funnelId", funnelId)
+          .gte("bucketStart", from)
+          .lte("bucketStart", to),
+      )
+      .take(perFunnelLimit + 1);
+    failIfIncomplete(funnelRows, perFunnelLimit, "funnel daily rollups");
+    rows.push(...funnelRows);
+    await requireFeatureReadHeadroom(ctx, "funnel daily rollups");
+  }
+  return rows;
+}
+
+async function loadAffiliateDailyRollups(
+  ctx: QueryCtx,
+  siteId: Id<"sites">,
+  affiliateIds: Id<"affiliates">[],
+  from: number,
+  to: number,
+) {
+  const days = Math.floor((to - from) / DAY_MS) + 1;
+  requireFeatureRollupBudget(
+    affiliateIds.length,
+    days,
+    "affiliate daily rollups",
+  );
+  const rows: Doc<"affiliateDailyRollups">[] = [];
+  for (const affiliateId of affiliateIds) {
+    const perAffiliateLimit = days * REPORT_ROLLUP_SHARDS;
+    const affiliateRows = await ctx.db
+      .query("affiliateDailyRollups")
+      .withIndex("by_siteId_and_affiliateId_and_bucketStart", (range) =>
+        range
+          .eq("siteId", siteId)
+          .eq("affiliateId", affiliateId)
+          .gte("bucketStart", from)
+          .lte("bucketStart", to),
+      )
+      .take(perAffiliateLimit + 1);
+    failIfIncomplete(affiliateRows, perAffiliateLimit, "affiliate daily rollups");
+    rows.push(...affiliateRows);
+    await requireFeatureReadHeadroom(ctx, "affiliate daily rollups");
+  }
+  return rows;
+}
+
+function requireFeatureRollupBudget(
+  entities: number,
+  days: number,
+  dataset: string,
+) {
+  const maximumRows = entities * days * REPORT_ROLLUP_SHARDS;
+  if (days > MAX_FEATURE_ROLLUP_DAYS || maximumRows > MAX_FEATURE_ROLLUP_ROWS) {
+    fail("REPORT_INCOMPLETE", `${dataset} exceeds its complete read budget`, {
+      dataset,
+      maximumDays: MAX_FEATURE_ROLLUP_DAYS,
+      maximumRows: MAX_FEATURE_ROLLUP_ROWS,
+    });
+  }
+}
+
+async function requireFeatureReadHeadroom(ctx: QueryCtx, dataset: string) {
+  const metrics = await ctx.meta.getTransactionMetrics();
+  if (
+    metrics.bytesRead.remaining < FEATURE_REPORT_BYTE_RESERVE ||
+    metrics.documentsRead.remaining < FEATURE_REPORT_DOCUMENT_RESERVE
+  ) {
+    fail("REPORT_INCOMPLETE", `${dataset} exceeds its byte or document budget`, {
+      dataset,
+      bytesRead: metrics.bytesRead.used,
+      documentsRead: metrics.documentsRead.used,
+    });
+  }
+}
+
+function failIfIncomplete<T>(rows: T[], maximum: number, dataset: string) {
+  if (rows.length > maximum) {
+    fail("REPORT_INCOMPLETE", `${dataset} exceeds the complete report read budget`, {
+      maximumRows: maximum,
+      dataset,
+    });
+  }
+}
+
+async function coverageForRange(
+  ctx: QueryCtx,
+  siteIds: Id<"sites">[],
+  from: number,
+  to: number,
+  options: {
+    datasets: CoverageSource[];
+    complete?: boolean;
+    generation?: 1 | null;
+  },
+) {
+  const controls = await Promise.all(siteIds.map((siteId) =>
+    ctx.db
+      .query("analyticsCoverage")
+      .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
+      .unique()
+  ));
+  const sourceRanges = await Promise.all(siteIds.map((siteId) =>
+    sourceSetRange(ctx, siteId, options.datasets)
+  ));
+  const retainedBefore = controls.reduce<number | null>((latest, control) => {
+    const before = control?.retained
+      .filter((item) => options.datasets.some((dataset) => dataset === item.dataset))
+      .reduce<number | undefined>(
+        (latest, item) => Math.max(latest ?? 0, item.before),
+        undefined,
+      );
+    return before === undefined ? latest : Math.max(latest ?? 0, before);
+  }, null);
+  const availableFrom = options.generation === 1
+    ? controls.length > 0 && controls.every(Boolean)
+      ? Math.max(...controls.map((control) => control!.rollupCompleteFrom))
+      : null
+    : sourceRanges.length > 0 && sourceRanges.every(Boolean)
+      ? Math.max(...sourceRanges.map((range) => range!.from))
+      : null;
+  const availableThrough = sourceRanges.length > 0 && sourceRanges.every(Boolean)
+    ? Math.min(...sourceRanges.map((range) => range!.through))
+    : null;
+  let state: "complete" | "partial" | "retained" | "unavailable";
+  if (retainedBefore !== null && to < retainedBefore) {
+    state = "unavailable";
+  } else if (retainedBefore !== null && from < retainedBefore) {
+    state = "partial";
+  } else if (options.complete || (
+    availableFrom !== null &&
+    availableThrough !== null &&
+    from >= availableFrom &&
+    to <= availableThrough
+  )) {
+    state = "complete";
+  } else if (sourceRanges.some(Boolean)) {
+    state = "retained";
+  } else {
+    state = "unavailable";
+  }
+  return {
+    state,
+    generation: options.generation ?? null,
+    availableFrom,
+    availableThrough,
+    retainedBefore,
+  };
+}
+
+async function assertSourceAvailable(
+  ctx: QueryCtx,
+  siteIds: Id<"sites">[],
+  sources: CoverageSource[],
+  from: number,
+) {
+  const rows = await Promise.all(siteIds.map((siteId) =>
+    ctx.db
+      .query("analyticsCoverage")
+      .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
+      .unique()
+  ));
+  const cutoff = rows.reduce<number | null>((latest, row) => {
+    for (const retained of row?.retained ?? []) {
+      if (sources.some((source) => source === retained.dataset)) {
+        latest = Math.max(latest ?? 0, retained.before);
+      }
+    }
+    return latest;
+  }, null);
+  if (cutoff !== null && from < cutoff) {
+    fail("REPORT_INCOMPLETE", "requested report range intersects retained data", {
+      retainedBefore: cutoff,
+    });
+  }
+}
+
+async function datasetCoverageForRange(
+  ctx: QueryCtx,
+  siteId: Id<"sites">,
+  dataset: PublicCoverageDataset,
+  from: number,
+  to: number,
+) {
+  const sourceOptions: CoverageSource[][] = dataset === "goals"
+    ? [["goalRollups"], ["goalCompletions"]]
+    : dataset === "funnels"
+      ? [["funnelRollups"], ["funnelSteps"]]
+      : dataset === "affiliates"
+        ? [["affiliateRollups"], ["affiliateStats", "sessions"]]
+        : [[dataset]];
+  const options = (await Promise.all(sourceOptions.map(async (sources) => {
+    const rollupDataset = sources[0] as
+      | "goalRollups"
+      | "funnelRollups"
+      | "affiliateRollups";
+    const isRollup = rollupDataset.endsWith("Rollups");
+    const complete = isRollup
+      ? await dailyRollupsAvailable(ctx, siteId, from, to, rollupDataset)
+      : false;
+    if (isRollup && !complete) return null;
+    return coverageForRange(ctx, [siteId], from, to, {
+      datasets: sources,
+      complete,
+      generation: complete ? 1 : null,
+    });
+  }))).filter((option): option is NonNullable<typeof option> => option !== null);
+  return options.sort((left, right) =>
+    coverageRank(right.state) - coverageRank(left.state)
+  )[0]!;
+}
+
+type PublicCoverageDataset =
+  | "overviewHour"
+  | "overviewDay"
+  | "events"
+  | "sessions"
+  | "conversions"
+  | "goals"
+  | "funnels"
+  | "affiliates";
+
+type CoverageSource =
+  | "overviewHour"
+  | "overviewDay"
+  | "events"
+  | "sessions"
+  | "conversions"
+  | "goalCompletions"
+  | "funnelSteps"
+  | "affiliateStats"
+  | "goalRollups"
+  | "funnelRollups"
+  | "affiliateRollups";
+
+type SourceRange = { from: number; through: number };
+
+async function sourceSetRange(
+  ctx: QueryCtx,
+  siteId: Id<"sites">,
+  sources: CoverageSource[],
+): Promise<SourceRange | null> {
+  const ranges = (await Promise.all(
+    sources.map((source) => sourceRange(ctx, siteId, source)),
+  )).filter((range): range is SourceRange => range !== null);
+  if (ranges.length === 0) return null;
+  return {
+    from: Math.min(...ranges.map((range) => range.from)),
+    through: Math.max(...ranges.map((range) => range.through)),
+  };
+}
+
+async function sourceRange(
+  ctx: QueryCtx,
+  siteId: Id<"sites">,
+  source: CoverageSource,
+): Promise<SourceRange | null> {
+  if (source === "overviewHour" || source === "overviewDay") {
+    const granularity = source === "overviewHour" ? "hour" as const : "day" as const;
+    const [first, last] = await Promise.all([
+      ctx.db.query("aggregateBuckets")
+        .withIndex("by_siteId_and_granularity_and_bucketStart", (range) =>
+          range.eq("siteId", siteId).eq("granularity", granularity),
+        ).order("asc").take(1),
+      ctx.db.query("aggregateBuckets")
+        .withIndex("by_siteId_and_granularity_and_bucketStart", (range) =>
+          range.eq("siteId", siteId).eq("granularity", granularity),
+        ).order("desc").take(1),
+    ]);
+    return bounds(first[0]?.bucketStart, last[0]?.bucketStart);
+  }
+  if (source === "events") {
+    const [first, last] = await Promise.all([
+      ctx.db.query("eventBatches")
+        .withIndex("by_siteId_and_bucketStart", (range) => range.eq("siteId", siteId))
+        .order("asc").take(1),
+      ctx.db.query("eventBatches")
+        .withIndex("by_siteId_and_bucketStart", (range) => range.eq("siteId", siteId))
+        .order("desc").take(1),
+    ]);
+    return bounds(first[0]?.bucketStart, last[0]?.bucketStart);
+  }
+  if (source === "sessions") {
+    const [first, last] = await Promise.all([
+      ctx.db.query("sessions")
+        .withIndex("by_siteId_and_startedAt", (range) => range.eq("siteId", siteId))
+        .order("asc").take(1),
+      ctx.db.query("sessions")
+        .withIndex("by_siteId_and_lastSeenAt", (range) => range.eq("siteId", siteId))
+        .order("desc").take(1),
+    ]);
+    return bounds(first[0]?.startedAt, last[0]?.lastSeenAt);
+  }
+  if (source === "conversions") {
+    const [first, last] = await Promise.all([
+      ctx.db.query("conversions")
+        .withIndex("by_siteId_and_timestamp", (range) => range.eq("siteId", siteId))
+        .order("asc").take(1),
+      ctx.db.query("conversions")
+        .withIndex("by_siteId_and_timestamp", (range) => range.eq("siteId", siteId))
+        .order("desc").take(1),
+    ]);
+    return bounds(first[0]?.timestamp, last[0]?.timestamp);
+  }
+  if (source === "goalCompletions") {
+    const [first, last] = await Promise.all([
+      ctx.db.query("goalCompletions")
+        .withIndex("by_siteId_and_timestamp", (range) => range.eq("siteId", siteId))
+        .order("asc").take(1),
+      ctx.db.query("goalCompletions")
+        .withIndex("by_siteId_and_timestamp", (range) => range.eq("siteId", siteId))
+        .order("desc").take(1),
+    ]);
+    return bounds(first[0]?.timestamp, last[0]?.timestamp);
+  }
+  const table = source === "funnelSteps"
+    ? "funnelStepBuckets" as const
+    : source === "affiliateStats"
+      ? "affiliateDailyStats" as const
+      : source === "goalRollups"
+        ? "goalDailyRollups" as const
+        : source === "funnelRollups"
+          ? "funnelDailyRollups" as const
+          : "affiliateDailyRollups" as const;
+  const [first, last] = await Promise.all([
+    ctx.db.query(table)
+      .withIndex("by_siteId_and_bucketStart", (range) => range.eq("siteId", siteId))
+      .order("asc").take(1),
+    ctx.db.query(table)
+      .withIndex("by_siteId_and_bucketStart", (range) => range.eq("siteId", siteId))
+      .order("desc").take(1),
+  ]);
+  return bounds(first[0]?.bucketStart, last[0]?.bucketStart);
+}
+
+function bounds(from: number | undefined, through: number | undefined) {
+  return from === undefined || through === undefined ? null : { from, through };
+}
+
+function coverageRank(state: "complete" | "partial" | "retained" | "unavailable") {
+  if (state === "complete") return 3;
+  if (state === "retained") return 2;
+  if (state === "partial") return 1;
+  return 0;
+}
+
 
 type MetricTotals = {
   events: number;
@@ -718,15 +1492,46 @@ function validateSiteIds<T>(siteIds: T[]): T[] {
 
 function validateRange(from: number, to: number, maxDays: number) {
   if (
-    !Number.isFinite(from) ||
-    !Number.isFinite(to) ||
+    !Number.isSafeInteger(from) ||
+    !Number.isSafeInteger(to) ||
     from < 0 ||
-    to <= from ||
-    to - from > maxDays * DAY_MS
+    to < from ||
+    to - from >= maxDays * DAY_MS
   ) {
-    fail("INVALID_ARGUMENT", `range must be positive, ordered, and at most ${maxDays} days`);
+    fail(
+      "INVALID_ARGUMENT",
+      `range must use inclusive integer milliseconds and span at most ${maxDays} UTC days`,
+    );
   }
-  return { from: Math.trunc(from), to: Math.trunc(to) };
+  return { from, to };
+}
+
+function isAlignedRange(from: number, to: number, intervalMs: number) {
+  return from % intervalMs === 0 && (to + 1) % intervalMs === 0;
+}
+
+function requireAlignedRange(
+  from: number,
+  to: number,
+  intervalMs: number,
+  report: string,
+) {
+  if (!isAlignedRange(from, to, intervalMs)) {
+    fail(
+      "REPORT_INCOMPLETE",
+      `${report} requires complete inclusive UTC bucket boundaries`,
+      { from, to, intervalMs, timezone: "UTC" },
+    );
+  }
+}
+
+function rangeSemantics(from: number, to: number) {
+  return {
+    from,
+    to,
+    boundary: "inclusive" as const,
+    timezone: "UTC" as const,
+  };
 }
 
 type KeysetPaginationInput = {