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

package/dist/component/reports.js

@@ -1,7 +1,8 @@
 import { paginationOptsValidator, paginationResultValidator, } from "convex/server";
 import { v } from "convex/values";
 import { query } from "./_generated/server.js";
-import { AGGREGATE_SHARDS, DAY_MS, HOUR_MS, HOURLY_AGGREGATE_SHARDS, MAX_AFFILIATES_PER_SITE, MAX_FUNNELS_PER_SITE, MAX_GOALS_PER_SITE, MAX_JOURNEY_EVENTS, MAX_LIVE_VISITORS, MAX_OVERVIEW_AGGREGATE_ROWS, MAX_REPORT_RANGE_DAYS, MAX_REPORT_SITES, } from "./constants.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, } from "./cardinality.js";
 import { fail } from "./errors.js";
 import { compareJourneyEvents, hydrateEventContexts, loadSessionJourneyEvents, loadVisitorJourneyEvents, } from "./eventStore.js";
 import { isPlainRecord } from "./guards.js";
@@ -71,6 +72,25 @@ 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: {
         siteIds: v.array(v.id("sites")),
@@ -92,6 +112,32 @@ 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);
@@ -114,6 +160,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;
@@ -124,7 +171,15 @@ export const overview = query({
         }
         const totals = emptyTotals();
         const points = new Map();
+        const visitorSketch = createVisitorSketch();
+        let mergedVisitorSketch = visitorSketch;
+        const pointVisitorSketches = new Map();
+        let visitorsComplete = true;
         const dimensions = new Map();
+        const overviewDataset = interval === "hour"
+            ? "overviewHour"
+            : "overviewDay";
+        await assertSourceAvailable(ctx, siteIds, [overviewDataset], from);
         for (const siteId of siteIds) {
             const buckets = await ctx.db
                 .query("aggregateBuckets")
@@ -133,12 +188,21 @@ export const overview = query({
                 .eq("granularity", interval)
                 .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) ?? {
@@ -157,6 +221,17 @@ 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 = visitorsComplete ? "estimatedUnique" : "bucketOccurrences";
         return {
             from,
             to,
@@ -173,6 +248,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",
+                    topPages: "eventVolume",
+                    topCountries: "eventVolume",
+                    topDevices: "eventVolume",
+                    topBrowsers: "eventVolume",
+                    topEvents: "eventVolume",
+                    topGoals: "goalCompletionVolume",
+                },
+                coverage,
+                range: rangeSemantics(from, to),
+                features: {
+                    sessionReplay: "unsupported",
+                    errorInsights: "unsupported",
+                    outboundLinks: "eventVolume",
+                    botDetection: "unsupported",
+                },
+            },
         };
     },
 });
@@ -236,6 +337,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),
@@ -274,7 +376,8 @@ export const listSessions = query({
                 .order("desc")
                 .take(take)));
         }
-        return keysetPaginationResult(rows, pagination, (row) => ({
+        const publicRows = rows.map(({ geoLookupAttemptedAt: _attemptedAt, ...row }) => row);
+        return keysetPaginationResult(publicRows, pagination, (row) => ({
             timestamp: row.lastSeenAt,
             creationTime: row._creationTime,
         }));
@@ -291,6 +394,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),
@@ -320,6 +424,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),
@@ -376,6 +481,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}`);
@@ -410,34 +516,63 @@ 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();
-        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" : "boundedLegacy",
+                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),
+            },
         };
     },
 });
@@ -446,33 +581,56 @@ const funnelReportItemValidator = funnelFieldsValidator.extend({
     _creationTime: v.number(),
     stepsReport: v.array(v.object({ step: v.number(), name: v.string(), entrants: v.number(), completions: v.number() })),
     truncated: v.boolean(),
+    metadata: reportMetadataValidator,
 });
 export const funnelsReport = query({
     args: { siteId: v.id("sites"), from: v.number(), to: v.number() },
     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;
@@ -482,7 +640,12 @@ export const funnelsReport = query({
             reports.push({
                 ...funnel,
                 stepsReport,
-                truncated: buckets.length > 600,
+                truncated: false,
+                metadata: {
+                    basis: rollups ? "dailyRollup" : "boundedLegacy",
+                    coverage: reportCoverage,
+                    range: rangeSemantics(args.from, args.to),
+                },
             });
         }
         return reports;
@@ -502,54 +665,94 @@ 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();
-        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(),
-            };
-            total.visits += 1;
-            total.visitors.add(session.visitorId);
-            visits.set(key, total);
-        }
         const totals = new Map();
-        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(),
+                    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(),
+                    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) => {
@@ -563,15 +766,358 @@ 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" : "boundedLegacy",
+                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" : "exactLegacy",
+                    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",
+        ];
+        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, siteId, from, to, dataset) {
+    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, siteId, goalIds, from, to) {
+    const days = Math.floor((to - from) / DAY_MS) + 1;
+    requireFeatureRollupBudget(goalIds.length, days, "goal daily rollups");
+    const rows = [];
+    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, siteId, funnelIds, from, to) {
+    const days = Math.floor((to - from) / DAY_MS) + 1;
+    requireFeatureRollupBudget(funnelIds.length, days, "funnel daily rollups");
+    const rows = [];
+    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, siteId, affiliateIds, from, to) {
+    const days = Math.floor((to - from) / DAY_MS) + 1;
+    requireFeatureRollupBudget(affiliateIds.length, days, "affiliate daily rollups");
+    const rows = [];
+    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, days, dataset) {
+    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, dataset) {
+    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(rows, maximum, dataset) {
+    if (rows.length > maximum) {
+        fail("REPORT_INCOMPLETE", `${dataset} exceeds the complete report read budget`, {
+            maximumRows: maximum,
+            dataset,
+        });
+    }
+}
+async function coverageForRange(ctx, siteIds, from, to, options) {
+    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((latest, control) => {
+        const before = control?.retained
+            .filter((item) => options.datasets.some((dataset) => dataset === item.dataset))
+            .reduce((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;
+    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, siteIds, sources, from) {
+    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((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, siteId, dataset, from, to) {
+    const sourceOptions = 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];
+        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 !== null);
+    return options.sort((left, right) => coverageRank(right.state) - coverageRank(left.state))[0];
+}
+async function sourceSetRange(ctx, siteId, sources) {
+    const ranges = (await Promise.all(sources.map((source) => sourceRange(ctx, siteId, source)))).filter((range) => 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, siteId, source) {
+    if (source === "overviewHour" || source === "overviewDay") {
+        const granularity = source === "overviewHour" ? "hour" : "day";
+        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"
+        : source === "affiliateStats"
+            ? "affiliateDailyStats"
+            : source === "goalRollups"
+                ? "goalDailyRollups"
+                : source === "funnelRollups"
+                    ? "funnelDailyRollups"
+                    : "affiliateDailyRollups";
+    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, through) {
+    return from === undefined || through === undefined ? null : { from, through };
+}
+function coverageRank(state) {
+    if (state === "complete")
+        return 3;
+    if (state === "retained")
+        return 2;
+    if (state === "partial")
+        return 1;
+    return 0;
+}
 function emptyTotals() {
     return {
         events: 0,
@@ -604,14 +1150,30 @@ function validateSiteIds(siteIds) {
     return unique;
 }
 function validateRange(from, to, maxDays) {
-    if (!Number.isFinite(from) ||
-        !Number.isFinite(to) ||
+    if (!Number.isSafeInteger(from) ||
+        !Number.isSafeInteger(to) ||
         from < 0 ||
-        to <= from ||
-        to - from > maxDays * DAY_MS) {
-        fail("INVALID_ARGUMENT", `range must be positive, ordered, and at most ${maxDays} days`);
+        to < from ||
+        to - from >= maxDays * DAY_MS) {
+        fail("INVALID_ARGUMENT", `range must use inclusive integer milliseconds and span at most ${maxDays} UTC days`);
+    }
+    return { from, to };
+}
+function isAlignedRange(from, to, intervalMs) {
+    return from % intervalMs === 0 && (to + 1) % intervalMs === 0;
+}
+function requireAlignedRange(from, to, intervalMs, report) {
+    if (!isAlignedRange(from, to, intervalMs)) {
+        fail("REPORT_INCOMPLETE", `${report} requires complete inclusive UTC bucket boundaries`, { from, to, intervalMs, timezone: "UTC" });
     }
-    return { from: Math.trunc(from), to: Math.trunc(to) };
+}
+function rangeSemantics(from, to) {
+    return {
+        from,
+        to,
+        boundary: "inclusive",
+        timezone: "UTC",
+    };
 }
 function parseKeysetPagination(options, scope) {
     validatePagination(options);