@iann29/rastro 0.1.0-alpha.0 → 0.1.0-alpha.10

package/src/component/constants.ts

@@ -1,13 +1,19 @@
-export const MAX_BATCH_EVENTS = 20;
+export const MAX_BATCH_EVENTS = 50;
+export const MAX_BATCH_EVENT_GROUPS = 4;
 export const MAX_BATCH_BYTES = 64 * 1024;
 export const MAX_EVENTS_PER_SESSION_WINDOW = 120;
 export const RATE_LIMIT_WINDOW_MS = 60_000;
 export const MAX_BYTES_PER_SESSION_WINDOW = 256 * 1024;
-export const SITE_INGEST_SHARDS = 8;
-export const MAX_SITE_EVENTS_PER_SHARD_WINDOW = 120;
+export const SITE_INGEST_SHARDS = 4_096;
+export const MAX_SITE_EVENTS_PER_SHARD_WINDOW = 300;
 export const MAX_SITE_BYTES_PER_SHARD_WINDOW = 512 * 1024;
-export const LIVE_SESSION_TTL_MS = 60_000;
-export const AGGREGATE_SHARDS = 16;
+export const LIVE_SESSION_TTL_MS = 90_000;
+export const LIVE_LEAVE_GRACE_MS = 10_000;
+export const LIVE_SWEEP_INTERVAL_MS = 5_000;
+export const CLOCK_SKEW_TOLERANCE_MS = 30_000;
+export const AGGREGATE_SHARDS = 128;
+export const HOURLY_AGGREGATE_SHARDS = 256;
+export const SECONDARY_AGGREGATE_SHARDS = 16;
 export const DIMENSION_SLOTS = 16;
 export const MAX_SITE_DOMAINS = 32;
 export const MAX_SITES_PER_OWNER = 100;
@@ -20,9 +26,43 @@ export const MAX_REPORT_SITES = 10;
 export const MAX_REPORT_RANGE_DAYS = 366;
 export const MAX_LIVE_VISITORS = 500;
 export const MAX_JOURNEY_EVENTS = 500;
+export const JOURNEY_READ_BYTE_RESERVE = 4 * 1024 * 1024;
+export const JOURNEY_READ_DOCUMENT_RESERVE = 1_000;
 export const MAX_RETENTION_BATCH = 500;
-export const MAX_OVERVIEW_AGGREGATE_ROWS = 12_000;
+export const MAX_OVERVIEW_AGGREGATE_ROWS = 13_000;
+export const MAX_REPORT_BUCKETS = 5_000;
+export const MAX_FEATURE_ROLLUP_DAYS = 90;
+export const MAX_FEATURE_ROLLUP_ROWS = 5_000;
+export const FEATURE_REPORT_BYTE_RESERVE = 2 * 1024 * 1024;
+export const FEATURE_REPORT_DOCUMENT_RESERVE = 500;
+export const REPORT_ROLLUP_SHARDS = 2;
+export const ROLLUP_SAFETY_DELAY_MS = 5 * 60_000;
+export const RETENTION_LEASE_MS = 60_000;
+// Shared Web Vitals histogram edges. Every Google rating threshold (LCP
+// 2500/4000, CLS×1000 100/250, INP 200/500, FCP 1800/3000, TTFB 800/1800) is
+// an edge, so rating counts stay exact while one layout serves all metrics.
+export const VITAL_HISTOGRAM_EDGES = [
+  100, 200, 250, 300, 500, 800, 1_000, 1_200, 1_800, 2_500, 3_000, 4_000, 5_000,
+  7_500, 10_000,
+];
+export const MAX_VITAL_VALUE = 600_000;
+export const VITAL_PAGE_SLOTS = 48;
+export const MAX_VITALS_REPORT_ROWS = 5_000;
+export const VITALS_REPORT_PAGE_LIMIT = 12;
 
 export const DAY_MS = 86_400_000;
 export const HOUR_MS = 3_600_000;
-export const MAX_MANUAL_PAGINATION_OFFSET = 1_000;
+export const MINUTE_MS = 60_000;
+export const RETENTION_POLICY_INTERVAL_MS = DAY_MS;
+export const MAX_VISITOR_ALIASES = 10;
+// Site map rollups: one row per (site, route, UTC day, shard). A day keeps at
+// most this many route rows per shard before new routes fold into "(other)";
+// each row keeps this many outgoing targets before they fold the same way. A
+// report reads at most MAX_SITE_MAP_ROWS rows, newest day first — about
+// 5 MiB of rows, under the 8 MiB a function may read once the feature-report
+// byte reserve is kept — and declares the older days it could not read as
+// partial coverage: 20 days at the daily cap, 40 for a 100-route site.
+export const MAX_SITE_MAP_ROUTES_PER_DAY = 200;
+export const ROUTE_TRANSITION_SLOTS = 24;
+export const MAX_SITE_MAP_ROWS = 8_000;
+export const SITE_MAP_OTHER_ROUTE = "(other)";

package/src/component/convex.config.ts

@@ -1,3 +1,13 @@
 import { defineComponent } from "convex/server";
+import { v } from "convex/values";
 
-export default defineComponent("rastroAnalytics");
+export default defineComponent("rastroAnalytics", {
+  env: {
+    RASTRO_GEOIP_PROVIDER: v.optional(
+      v.union(v.literal("ipinfo"), v.literal("ipwhois")),
+    ),
+    RASTRO_GEOIP_TOKEN: v.optional(v.string()),
+    RASTRO_GEOIP_DAILY_LIMIT: v.optional(v.string()),
+    RASTRO_TRUST_PROXY: v.optional(v.literal("true")),
+  },
+});

package/src/component/coverage.ts

@@ -0,0 +1,36 @@
+import type { Id } from "./_generated/dataModel.js";
+import type { MutationCtx } from "./_generated/server.js";
+import { ROLLUP_SAFETY_DELAY_MS } from "./constants.js";
+
+export async function ensureAnalyticsControl(
+  ctx: MutationCtx,
+  siteId: Id<"sites">,
+  now: number,
+  retained: Array<{ dataset: string; before: number }> = [],
+) {
+  const existing = await ctx.db
+    .query("analyticsCoverage")
+    .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
+    .unique();
+  if (existing) {
+    if (existing.siteMapSince !== undefined) return existing;
+    // A site that predates the site map starts its map coverage at the first
+    // ingest after the upgrade; the same safety delay applies as for rollups.
+    const siteMapSince = now + ROLLUP_SAFETY_DELAY_MS;
+    await ctx.db.patch("analyticsCoverage", existing._id, {
+      siteMapSince,
+      updatedAt: now,
+    });
+    return { ...existing, siteMapSince, updatedAt: now };
+  }
+  const fields = {
+    siteId,
+    generation: 1 as const,
+    rollupCompleteFrom: now + ROLLUP_SAFETY_DELAY_MS,
+    siteMapSince: now + ROLLUP_SAFETY_DELAY_MS,
+    retained,
+    updatedAt: now,
+  };
+  const _id = await ctx.db.insert("analyticsCoverage", fields);
+  return { ...fields, _id, _creationTime: now };
+}

package/src/component/diagnostics.ts

@@ -0,0 +1,65 @@
+import { v } from "convex/values";
+import { query } from "./_generated/server.js";
+import { fail } from "./errors.js";
+import { sanitizeOpaqueId } from "./sanitize.js";
+
+const MAX_SESSION_TOTAL_IDS = 100;
+
+export const sessionEventTotals = query({
+  args: {
+    siteId: v.id("sites"),
+    sessionIds: v.array(v.string()),
+  },
+  returns: v.object({
+    requestedSessions: v.number(),
+    foundSessions: v.number(),
+    storedEvents: v.number(),
+  }),
+  handler: async (ctx, args) => {
+    if (
+      args.sessionIds.length < 1 ||
+      args.sessionIds.length > MAX_SESSION_TOTAL_IDS
+    ) {
+      fail(
+        "INVALID_ARGUMENT",
+        `sessionIds must contain between 1 and ${MAX_SESSION_TOTAL_IDS} IDs`,
+      );
+    }
+    let sessionIds: string[];
+    try {
+      sessionIds = args.sessionIds.map((sessionId) => {
+        const sanitized = sanitizeOpaqueId(sessionId, "sessionId");
+        if (sanitized !== sessionId)
+          throw new Error("sessionId is not canonical");
+        return sanitized;
+      });
+    } catch (error) {
+      fail(
+        "INVALID_ARGUMENT",
+        error instanceof Error ? error.message : "invalid sessionId",
+      );
+    }
+    if (new Set(sessionIds).size !== sessionIds.length) {
+      fail("INVALID_ARGUMENT", "sessionIds must be unique");
+    }
+
+    const sessions = await Promise.all(
+      sessionIds.map((sessionId) =>
+        ctx.db
+          .query("sessions")
+          .withIndex("by_siteId_and_sessionId", (range) =>
+            range.eq("siteId", args.siteId).eq("sessionId", sessionId),
+          )
+          .unique(),
+      ),
+    );
+    return {
+      requestedSessions: sessionIds.length,
+      foundSessions: sessions.filter((session) => session !== null).length,
+      storedEvents: sessions.reduce(
+        (total, session) => total + (session?.eventCount ?? 0),
+        0,
+      ),
+    };
+  },
+});

package/src/component/errors.ts

@@ -9,7 +9,8 @@ export type RastroErrorCode =
   | "LIMIT_EXCEEDED"
   | "CONFLICT"
   | "CURRENCY_MISMATCH"
-  | "RATE_LIMITED";
+  | "RATE_LIMITED"
+  | "REPORT_INCOMPLETE";
 
 export function fail(
   code: RastroErrorCode,

package/src/component/eventStore.ts

@@ -0,0 +1,489 @@
+import type { Doc, Id } from "./_generated/dataModel.js";
+import type { MutationCtx, QueryCtx } from "./_generated/server.js";
+import {
+  JOURNEY_READ_BYTE_RESERVE,
+  JOURNEY_READ_DOCUMENT_RESERVE,
+  MAX_EVENTS_PER_SESSION_WINDOW,
+  RATE_LIMIT_WINDOW_MS,
+} from "./constants.js";
+import { fail } from "./errors.js";
+import type { TrackerEvent } from "./validators.js";
+
+export type TelemetryMatch = {
+  sessionId: string;
+  visitorId: string;
+  country?: string;
+  city?: string;
+  latitude?: number;
+  longitude?: number;
+  browser?: string;
+  os?: string;
+  device?: string;
+};
+
+type BufferedEventBatch = {
+  siteId: Id<"sites">;
+  sessionId: string;
+  visitorId: string;
+  bucketStart: number;
+  events: TrackerEvent[];
+};
+
+export type EventBatchBuffer = Map<string, BufferedEventBatch>;
+
+export type JourneyCursor = {
+  timestamp: number;
+  creationTime: number;
+  id: string;
+};
+
+export type RawJourneyEvent = Omit<
+  Doc<"eventBatches">["events"][number],
+  "aggregateCountry"
+> & {
+  _id: string;
+  _creationTime: number;
+  siteId: Id<"sites">;
+  sessionId: string;
+  visitorId: string;
+};
+
+export function eventBucketStart(timestamp: number): number {
+  return Math.floor(timestamp / RATE_LIMIT_WINDOW_MS) * RATE_LIMIT_WINDOW_MS;
+}
+
+export function eventBatchKey(sessionId: string, bucketStart: number): string {
+  return JSON.stringify([sessionId, bucketStart]);
+}
+
+export async function inspectTelemetryMinute(
+  ctx: MutationCtx,
+  input: {
+    siteId: Id<"sites">;
+    sessionId: string;
+    bucketStart: number;
+  },
+) {
+  const batches = await loadTelemetryMinute(ctx, input);
+  const eventIds = new Set(
+    batches.flatMap((batch) => batch.events.map((event) => event.eventId)),
+  );
+  return {
+    eventIds,
+    persistedCount: telemetryMinuteCount(batches),
+  };
+}
+
+export async function findTelemetry(
+  ctx: MutationCtx,
+  siteId: Id<"sites">,
+  event: TrackerEvent,
+): Promise<{ match: TelemetryMatch | null; saturated: boolean }> {
+  const bucketStart = eventBucketStart(event.timestamp);
+  const batches = await loadTelemetryMinute(ctx, {
+    siteId,
+    sessionId: event.sessionId,
+    bucketStart,
+  });
+  const persistedCount = telemetryMinuteCount(batches);
+  const saturated = persistedCount >= MAX_EVENTS_PER_SESSION_WINDOW;
+  let batch: Doc<"eventBatches"> | undefined;
+  let nestedEvent: Doc<"eventBatches">["events"][number] | undefined;
+  for (const candidate of batches) {
+    nestedEvent = candidate.events.find(
+      (nested) => nested.eventId === event.eventId,
+    );
+    if (nestedEvent) {
+      batch = candidate;
+      break;
+    }
+  }
+  return {
+    match:
+      batch && nestedEvent
+        ? {
+            sessionId: batch.sessionId,
+            visitorId: batch.visitorId,
+            ...eventContext(nestedEvent),
+          }
+        : null,
+    saturated,
+  };
+}
+
+export function bufferEventBatch(
+  siteId: Id<"sites">,
+  event: TrackerEvent,
+  buffer: EventBatchBuffer,
+  country: string,
+) {
+  const bucketStart = eventBucketStart(event.timestamp);
+  const key = eventBatchKey(event.sessionId, bucketStart);
+  const existing = buffer.get(key);
+  if (existing) {
+    if (existing.visitorId !== event.visitorId) {
+      throw new Error("event batch visitor does not match its session");
+    }
+    existing.events.push(eventForBatch(event, country));
+    return;
+  }
+  buffer.set(key, {
+    siteId,
+    sessionId: event.sessionId,
+    visitorId: event.visitorId,
+    bucketStart,
+    events: [eventForBatch(event, country)],
+  });
+}
+
+export async function insertEventBatch(
+  ctx: MutationCtx,
+  siteId: Id<"sites">,
+  event: TrackerEvent,
+  country: string,
+) {
+  await ctx.db.insert("eventBatches", {
+    siteId,
+    sessionId: event.sessionId,
+    visitorId: event.visitorId,
+    bucketStart: eventBucketStart(event.timestamp),
+    events: [eventForBatch(event, country)],
+  });
+}
+
+export async function flushEventBatches(
+  ctx: MutationCtx,
+  buffer: EventBatchBuffer,
+) {
+  for (const batch of buffer.values()) {
+    await ctx.db.insert("eventBatches", batch);
+  }
+}
+
+export async function loadSessionJourneyEvents(
+  ctx: QueryCtx,
+  input: {
+    siteId: Id<"sites">;
+    sessionId: string;
+    from: number;
+    to: number;
+    cursor: JourneyCursor | null;
+    resultLimit: number;
+  },
+): Promise<RawJourneyEvent[]> {
+  const startTimestamp = input.cursor?.timestamp ?? input.from;
+  const firstBucket = eventBucketStart(startTimestamp);
+  const lastBucket = eventBucketStart(input.to);
+  // Nested event tiebreakers are not index fields, so the boundary minute must
+  // be read completely before applying the cursor.
+  const loadBatches = async () => {
+    const batches: Doc<"eventBatches">[] = [];
+    let qualifyingEvents = 0;
+    let completedBucket: number | undefined;
+    const query = ctx.db
+      .query("eventBatches")
+      .withIndex("by_siteId_and_sessionId_and_bucketStart", (range) =>
+        range
+          .eq("siteId", input.siteId)
+          .eq("sessionId", input.sessionId)
+          .gte("bucketStart", firstBucket)
+          .lte("bucketStart", lastBucket),
+      )
+      .order("asc");
+    for await (const batch of query) {
+      if (
+        completedBucket !== undefined &&
+        batch.bucketStart !== completedBucket
+      ) {
+        break;
+      }
+      batches.push(batch);
+      qualifyingEvents += batch.events.reduce((count, _event, index) => {
+        const event = eventFromBatch(batch, index);
+        return (
+          count +
+          Number(
+            event.timestamp >= input.from &&
+              event.timestamp <= input.to &&
+              (!input.cursor ||
+                compareJourneyEventToCursor(event, input.cursor) > 0),
+          )
+        );
+      }, 0);
+      if (qualifyingEvents >= input.resultLimit) {
+        completedBucket = batch.bucketStart;
+      }
+    }
+    return batches;
+  };
+  const batches = await loadBatches();
+  const rows: RawJourneyEvent[] = [];
+  appendBatchEvents(rows, batches);
+  return rows
+    .filter(
+      (event) =>
+        event.timestamp >= input.from &&
+        event.timestamp <= input.to &&
+        (!input.cursor || compareJourneyEventToCursor(event, input.cursor) > 0),
+    )
+    .sort(compareJourneyEvents)
+    .slice(0, input.resultLimit);
+}
+
+export async function loadVisitorJourneyEvents(
+  ctx: QueryCtx,
+  input: {
+    siteId: Id<"sites">;
+    visitorId: string;
+    from: number;
+    to: number;
+    resultLimit: number;
+  },
+): Promise<RawJourneyEvent[]> {
+  const firstBucket = eventBucketStart(input.from);
+  const lastBucket = eventBucketStart(input.to);
+  const loadBatches = async () => {
+    const batches: Doc<"eventBatches">[] = [];
+    let qualifyingEvents = 0;
+    let completedBucket: number | undefined;
+    const query = ctx.db
+      .query("eventBatches")
+      .withIndex("by_siteId_and_visitorId_and_bucketStart", (range) =>
+        range
+          .eq("siteId", input.siteId)
+          .eq("visitorId", input.visitorId)
+          .gte("bucketStart", firstBucket)
+          .lte("bucketStart", lastBucket),
+      )
+      .order("asc");
+    for await (const batch of query) {
+      if (
+        completedBucket !== undefined &&
+        batch.bucketStart !== completedBucket
+      ) {
+        break;
+      }
+      batches.push(batch);
+      await requireJourneyReadHeadroom(ctx);
+      qualifyingEvents += batch.events.filter(
+        (event) => event.timestamp >= input.from && event.timestamp <= input.to,
+      ).length;
+      if (qualifyingEvents >= input.resultLimit) {
+        completedBucket = batch.bucketStart;
+      }
+    }
+    return batches;
+  };
+  const batches = await loadBatches();
+  const rows: RawJourneyEvent[] = [];
+  appendBatchEvents(rows, batches);
+  return rows
+    .filter(
+      (event) => event.timestamp >= input.from && event.timestamp <= input.to,
+    )
+    .sort(compareJourneyEvents)
+    .slice(0, input.resultLimit);
+}
+
+export function compareJourneyEvents(
+  left: Pick<RawJourneyEvent, "timestamp" | "_creationTime" | "_id">,
+  right: Pick<RawJourneyEvent, "timestamp" | "_creationTime" | "_id">,
+): number {
+  return (
+    left.timestamp - right.timestamp ||
+    left._creationTime - right._creationTime ||
+    left._id.localeCompare(right._id)
+  );
+}
+
+export async function hydrateEventContexts(
+  ctx: QueryCtx,
+  rows: RawJourneyEvent[],
+) {
+  const sessionPromises = new Map<string, Promise<Doc<"sessions"> | null>>();
+  for (const row of rows) {
+    const key = `${row.siteId}:${row.sessionId}`;
+    if (!sessionPromises.has(key)) {
+      sessionPromises.set(
+        key,
+        ctx.db
+          .query("sessions")
+          .withIndex("by_siteId_and_sessionId", (range) =>
+            range.eq("siteId", row.siteId).eq("sessionId", row.sessionId),
+          )
+          .unique(),
+      );
+    }
+  }
+  const sessions = new Map(
+    await Promise.all(
+      [...sessionPromises].map(
+        async ([key, session]) => [key, await session] as const,
+      ),
+    ),
+  );
+  return rows.map((row) => {
+    const session = sessions.get(`${row.siteId}:${row.sessionId}`);
+    const country = row.country ?? session?.country;
+    const city = row.city ?? session?.city;
+    const latitude = row.latitude ?? session?.latitude;
+    const longitude = row.longitude ?? session?.longitude;
+    return {
+      ...row,
+      ...(country ? { country } : {}),
+      ...(city ? { city } : {}),
+      ...(latitude !== undefined ? { latitude } : {}),
+      ...(longitude !== undefined ? { longitude } : {}),
+      browser: row.browser ?? session?.browser ?? "Other",
+      os: row.os ?? session?.os ?? "Other",
+      device: row.device ?? session?.device ?? "unknown",
+    };
+  });
+}
+
+export async function deleteTelemetryBefore(
+  ctx: MutationCtx,
+  input: {
+    siteId: Id<"sites">;
+    before: number;
+    batchSize: number;
+  },
+) {
+  const batchCutoff = eventBucketStart(input.before);
+  const limit = input.batchSize + 1;
+  const batches = await ctx.db
+    .query("eventBatches")
+    .withIndex("by_siteId_and_bucketStart", (range) =>
+      range.eq("siteId", input.siteId).lt("bucketStart", batchCutoff),
+    )
+    .take(limit);
+  const rows = batches.slice(0, input.batchSize);
+  for (const row of rows) {
+    await ctx.db.delete("eventBatches", row._id);
+  }
+  return {
+    deleted: rows.length,
+    hasMore: batches.length > input.batchSize,
+  };
+}
+
+async function loadTelemetryMinute(
+  ctx: MutationCtx,
+  input: {
+    siteId: Id<"sites">;
+    sessionId: string;
+    bucketStart: number;
+  },
+) {
+  return ctx.db
+    .query("eventBatches")
+    .withIndex("by_siteId_and_sessionId_and_bucketStart", (range) =>
+      range
+        .eq("siteId", input.siteId)
+        .eq("sessionId", input.sessionId)
+        .eq("bucketStart", input.bucketStart),
+    )
+    .take(MAX_EVENTS_PER_SESSION_WINDOW + 1);
+}
+
+function telemetryMinuteCount(batches: Array<{ events: TrackerEvent[] }>) {
+  return batches.reduce((total, batch) => total + batch.events.length, 0);
+}
+
+function eventForBatch(
+  event: TrackerEvent,
+  country: string,
+): TrackerEvent & { aggregateCountry?: string } {
+  return {
+    eventId: event.eventId,
+    sessionId: event.sessionId,
+    visitorId: event.visitorId,
+    type: event.type,
+    ...(event.name ? { name: event.name } : {}),
+    path: event.path,
+    ...(event.referrer ? { referrer: event.referrer } : {}),
+    timestamp: event.timestamp,
+    sequence: event.sequence,
+    ...(event.target ? { target: event.target } : {}),
+    ...(event.href ? { href: event.href } : {}),
+    ...(event.properties ? { properties: event.properties } : {}),
+    ...(event.revenueCents !== undefined
+      ? { revenueCents: event.revenueCents }
+      : {}),
+    ...(event.currency ? { currency: event.currency } : {}),
+    ...(event.affiliateSlug ? { affiliateSlug: event.affiliateSlug } : {}),
+    aggregateCountry: country,
+  };
+}
+
+function appendBatchEvents(
+  rows: RawJourneyEvent[],
+  batches: Doc<"eventBatches">[],
+) {
+  for (const batch of batches) {
+    for (let index = 0; index < batch.events.length; index += 1) {
+      rows.push(eventFromBatch(batch, index));
+    }
+  }
+}
+
+function eventFromBatch(
+  batch: Doc<"eventBatches">,
+  index: number,
+): RawJourneyEvent {
+  const { aggregateCountry: _aggregateCountry, ...event } =
+    batch.events[index]!;
+  void _aggregateCountry;
+  return {
+    ...event,
+    _id: `eventBatch:${batch._id}:${index.toString().padStart(3, "0")}`,
+    _creationTime: batch._creationTime,
+    siteId: batch.siteId,
+    sessionId: batch.sessionId,
+    visitorId: batch.visitorId,
+  };
+}
+
+function eventContext(event: {
+  country?: string;
+  city?: string;
+  latitude?: number;
+  longitude?: number;
+  browser?: string;
+  os?: string;
+  device?: string;
+}) {
+  return {
+    ...(event.country ? { country: event.country } : {}),
+    ...(event.city ? { city: event.city } : {}),
+    ...(event.latitude !== undefined ? { latitude: event.latitude } : {}),
+    ...(event.longitude !== undefined ? { longitude: event.longitude } : {}),
+    ...(event.browser ? { browser: event.browser } : {}),
+    ...(event.os ? { os: event.os } : {}),
+    ...(event.device ? { device: event.device } : {}),
+  };
+}
+
+async function requireJourneyReadHeadroom(ctx: QueryCtx) {
+  const metrics = await ctx.meta.getTransactionMetrics();
+  if (
+    metrics.bytesRead.remaining < JOURNEY_READ_BYTE_RESERVE ||
+    metrics.documentsRead.remaining < JOURNEY_READ_DOCUMENT_RESERVE
+  ) {
+    fail("LIMIT_EXCEEDED", "visitor journey exceeds the safe read budget", {
+      bytesRead: metrics.bytesRead.used,
+      documentsRead: metrics.documentsRead.used,
+    });
+  }
+}
+
+function compareJourneyEventToCursor(
+  event: Pick<RawJourneyEvent, "timestamp" | "_creationTime" | "_id">,
+  cursor: JourneyCursor,
+) {
+  return (
+    event.timestamp - cursor.timestamp ||
+    event._creationTime - cursor.creationTime ||
+    event._id.localeCompare(cursor.id)
+  );
+}