@wtfalch/reporting 0.1.1 → 0.2.1

package/dist/analytics/tasks.js

@@ -0,0 +1,199 @@
+import { sql } from 'drizzle-orm';
+import { rowsOf } from '../housekeeping/tasks.js';
+const HOUR = 60 * 60 * 1000;
+const DAY = 24 * HOUR;
+/** Completed days rolled up per run, so a long outage catches up in bounded steps under a renewed lease. */
+const CATCH_UP_DAYS = 14;
+/** The weekly rollup's raw lookback: returning means seen in one of the four weeks before. */
+export const WEEKLY_LOOKBACK_DAYS = 28;
+const iso = (d) => d.toISOString().slice(0, 10);
+const utcDay = (d) => new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+const addDays = (d, n) => new Date(d.getTime() + n * DAY);
+/** The Monday of the ISO week holding `d`, at UTC midnight. */
+export const mondayOf = (d) => {
+    const day = utcDay(d);
+    const dow = (day.getUTCDay() + 6) % 7;
+    return addDays(day, -dow);
+};
+async function rollupDay(db, day) {
+    const result = await db.execute(sql `select reporting_rollup_day(${day}::date) as n`);
+    return Number(rowsOf(result)[0]?.n ?? 0);
+}
+async function rollupWeek(db, monday) {
+    const result = await db.execute(sql `select reporting_rollup_week(${monday}::date) as n`);
+    return Number(rowsOf(result)[0]?.n ?? 0);
+}
+/** The first day worth rolling up when there is no watermark yet: the oldest raw row's day, or nothing. */
+async function firstRawDay(db) {
+    const result = await db.execute(sql `select min((occurred_at at time zone 'UTC')::date)::text as d from reporting_analytics`);
+    const d = rowsOf(result)[0]?.d;
+    return typeof d === 'string' && d.length === 10 ? d : null;
+}
+/**
+ * The daily rollup (addendum A3). Completed days first: from the day after
+ * the watermark up to yesterday, each day's aggregate set and the watermark
+ * move committed together, fenced by the claim token, in bounded batches
+ * with the lease renewed between them. Then the open day (today) is
+ * recomputed without moving the watermark, so the dashboard is current and
+ * history stays contiguous.
+ */
+export const rollupAnalytics = {
+    name: 'reporting.rollup_analytics',
+    every: HOUR,
+    lease: 10 * 60 * 1000,
+    retry: 15 * 60 * 1000,
+    async run(ctx) {
+        const today = utcDay(ctx.now());
+        const yesterday = addDays(today, -1);
+        let cursor = ctx.watermark ? addDays(new Date(`${ctx.watermark}T00:00:00Z`), 1) : null;
+        if (!cursor) {
+            const first = await firstRawDay(ctx.db);
+            cursor = first ? new Date(`${first}T00:00:00Z`) : null;
+        }
+        let completed = 0;
+        while (cursor && cursor.getTime() <= yesterday.getTime() && completed < CATCH_UP_DAYS) {
+            if (ctx.now().getTime() > ctx.deadline.getTime() - 60_000)
+                break;
+            const day = iso(cursor);
+            const moved = await ctx.db.transaction(async (tx) => {
+                await rollupDay(tx, day);
+                return ctx.commitWatermark(day, tx);
+            });
+            if (!moved) {
+                // The lease went to another process; its run owns the watermark now.
+                ctx.reporting.event({
+                    kind: 'reporting.rollup_yielded',
+                    level: 'warn',
+                    message: `rollup of ${day} yielded: the lease was lost before the watermark moved`,
+                    data: { day },
+                });
+                return;
+            }
+            completed += 1;
+            cursor = addDays(cursor, 1);
+            if (!(await ctx.renew()))
+                return;
+        }
+        // The open day, and yesterday if the catch-up has not reached it yet:
+        // recomputed for the dashboard, never vouched for.
+        const openFrom = cursor && cursor.getTime() < today.getTime() ? cursor : today;
+        for (let d = openFrom; d.getTime() <= today.getTime(); d = addDays(d, 1)) {
+            await rollupDay(ctx.db, iso(d));
+        }
+        if (completed > 0) {
+            ctx.reporting.event({
+                kind: 'reporting.rolled_up',
+                message: `rolled up ${completed} completed day(s), watermark ${iso(addDays(cursor ?? today, -1))}`,
+                data: { days: completed, watermark: iso(addDays(cursor ?? today, -1)) },
+            });
+        }
+    },
+};
+/**
+ * The weekly rollup: completed ISO weeks (Monday to Sunday, wholly before
+ * today) from the week after its own watermark, then the open week
+ * recomputed. Its watermark is the Monday of the last completed week.
+ */
+export const rollupAnalyticsWeekly = {
+    name: 'reporting.rollup_analytics_weekly',
+    every: DAY,
+    lease: 10 * 60 * 1000,
+    retry: HOUR,
+    async run(ctx) {
+        const today = utcDay(ctx.now());
+        const thisMonday = mondayOf(today);
+        let cursor = ctx.watermark
+            ? addDays(new Date(`${ctx.watermark}T00:00:00Z`), 7)
+            : null;
+        if (!cursor) {
+            const first = await firstRawDay(ctx.db);
+            cursor = first ? mondayOf(new Date(`${first}T00:00:00Z`)) : null;
+        }
+        let completed = 0;
+        while (cursor && cursor.getTime() < thisMonday.getTime() && completed < 26) {
+            if (ctx.now().getTime() > ctx.deadline.getTime() - 60_000)
+                break;
+            const monday = iso(cursor);
+            const moved = await ctx.db.transaction(async (tx) => {
+                await rollupWeek(tx, monday);
+                return ctx.commitWatermark(monday, tx);
+            });
+            if (!moved)
+                return;
+            completed += 1;
+            cursor = addDays(cursor, 7);
+            if (!(await ctx.renew()))
+                return;
+        }
+        await rollupWeek(ctx.db, iso(thisMonday));
+    },
+};
+/**
+ * Raw rows leave by age, and never past what the rollups still need: the
+ * daily watermark, and the weekly watermark less its lookback, whichever is
+ * earlier. Until both rollups have completed a day there is nothing safe to
+ * prune, and the function says so.
+ */
+export const pruneAnalytics = {
+    name: 'reporting.prune_analytics',
+    every: HOUR,
+    lease: 10 * 60 * 1000,
+    retry: 15 * 60 * 1000,
+    async run(ctx) {
+        const days = ctx.settings['analytics.retention_days'];
+        const safeBefore = await safePruneBoundary(ctx.db);
+        if (!safeBefore)
+            return;
+        // The window's cutoff must fall before what the rollups still need. A
+        // window shorter than that (an operator's edit against a stalled
+        // rollup, or one shorter than the weekly lookback) defers pruning with
+        // a warning rather than failing every hour; the function refuses too.
+        const cutoffDay = iso(addDays(utcDay(ctx.now()), -days));
+        if (cutoffDay >= safeBefore) {
+            ctx.reporting.event({
+                kind: 'reporting.prune_deferred',
+                level: 'warn',
+                message: `analytics pruning deferred: a ${days}-day window would cut at ${cutoffDay}, but the rollups still need raw rows from ${safeBefore}`,
+                data: { days, cutoffDay, safeBefore },
+            });
+            return;
+        }
+        let total = 0;
+        for (let i = 0; i < 20; i += 1) {
+            if (ctx.now().getTime() > ctx.deadline.getTime() - 30_000)
+                break;
+            const n = await pruneAnalyticsBatch(ctx.db, days, 5000, safeBefore);
+            total += n;
+            if (n < 5000)
+                break;
+            if (!(await ctx.renew()))
+                break;
+        }
+        if (total > 0) {
+            ctx.reporting.event({
+                kind: 'reporting.pruned_analytics',
+                message: `pruned ${total} analytics row(s) older than ${days} days`,
+                data: { rows: total, days, safeBefore },
+            });
+        }
+    },
+};
+/** The earliest day the rollups still need, as an ISO date, or null when a rollup has not completed anything yet. */
+export async function safePruneBoundary(db) {
+    const result = await db.execute(sql `select task, watermark from reporting_tasks where task in ('reporting.rollup_analytics', 'reporting.rollup_analytics_weekly')`);
+    const marks = new Map(rowsOf(result).map((r) => [String(r.task), r.watermark]));
+    const daily = marks.get('reporting.rollup_analytics');
+    const weekly = marks.get('reporting.rollup_analytics_weekly');
+    if (typeof daily !== 'string' || typeof weekly !== 'string')
+        return null;
+    const weeklyNeeds = addDays(new Date(`${weekly}T00:00:00Z`), -WEEKLY_LOOKBACK_DAYS);
+    const dailyDate = new Date(`${daily}T00:00:00Z`);
+    return iso(weeklyNeeds.getTime() < dailyDate.getTime() ? weeklyNeeds : dailyDate);
+}
+export async function pruneAnalyticsBatch(db, days, batch, safeBefore) {
+    return db.transaction(async (tx) => {
+        await tx.execute(sql `set local statement_timeout = '30s'`);
+        const result = await tx.execute(sql `select reporting_prune_analytics(make_interval(days => ${days}::int), ${batch}::int, ${safeBefore}::date) as n`);
+        return Number(rowsOf(result)[0]?.n ?? 0);
+    });
+}

package/dist/analytics/write.d.ts

@@ -0,0 +1,19 @@
+import type { Db } from '../types.js';
+import type { Device } from './schema.js';
+/** One raw row as the collector or `track` writes it; every field already validated and normalised. */
+export interface AnalyticsRow {
+    readonly occurredAt: Date;
+    readonly receivedAt: Date;
+    readonly site: string;
+    readonly tenantId: string | null;
+    readonly visitorId: string | null;
+    readonly sessionId: string | null;
+    readonly userId: string | null;
+    readonly name: string;
+    readonly path: string;
+    readonly referrerHost: string | null;
+    readonly device: Device;
+    readonly country: string | null;
+    readonly props: Record<string, string | number | boolean | null>;
+}
+export declare function insertAnalytics(db: Db, rows: readonly AnalyticsRow[]): Promise<void>;

package/dist/analytics/write.js

@@ -0,0 +1,20 @@
+import { reportingAnalytics } from '../tables.js';
+export async function insertAnalytics(db, rows) {
+    if (rows.length === 0)
+        return;
+    await db.insert(reportingAnalytics).values(rows.map((r) => ({
+        occurredAt: r.occurredAt,
+        receivedAt: r.receivedAt,
+        site: r.site,
+        tenantId: r.tenantId,
+        visitorId: r.visitorId,
+        sessionId: r.sessionId,
+        userId: r.userId,
+        name: r.name,
+        path: r.path,
+        referrerHost: r.referrerHost,
+        device: r.device,
+        country: r.country,
+        props: r.props,
+    })));
+}

package/dist/bin/migrations.js

@@ -12,11 +12,5 @@ import { copyMigrations, describeCopy } from './copy.js';
 const here = dirname(fileURLToPath(import.meta.url));
 const from = join(here, '..', 'migrations');
 const to = resolve(process.cwd(), process.argv[2] ?? 'drizzle');
-let version;
-try {
-    version = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf8')).version;
-}
-catch {
-    version = undefined;
-}
+const { version } = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf8'));
 console.log(describeCopy(copyMigrations({ from, to, version })));

package/dist/browser/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The beacon: `page.view` on load and on history changes, `page.leave` with
+ * the seconds on the page, and whatever the host `track`s, batched twenty at
+ * a time or every five seconds and posted with `sendBeacon` (falling back to
+ * `fetch` with `keepalive`). It sends the pathname, never the query string,
+ * and never a user id: the collector knows who is signed in from the session
+ * cookie, and a client-supplied id would be a claim (D14).
+ *
+ * Consent (D15): `none` keeps nothing; `consented` starts as `none` until
+ * `accept()`; `always` sets the first-party cookie without asking. The cookie
+ * `_rp` holds the visitor id and the answer, one year, SameSite=Lax, Secure;
+ * the session id lives in `sessionStorage` under `consented`/`always` and in
+ * memory under `none`. Nothing about the browser is stored beyond that.
+ *
+ * No dependencies, no globals beyond `window`; under 3 KB gzipped.
+ */
+export type ConsentMode = 'none' | 'consented' | 'always';
+export type ConsentAnswer = 'accepted' | 'declined' | null;
+export interface BeaconOptions {
+    /** The collector URL, same-origin (`/api/reporting/collect`) or the hub's. */
+    readonly collector: string;
+    /** This app's site id. */
+    readonly site: string;
+    readonly consent?: ConsentMode;
+    /** Batch size and flush interval; the defaults are the collector's caps. */
+    readonly batch?: number;
+    readonly flushMs?: number;
+    /** For tests: the window to observe and the transport to post with. */
+    readonly window?: Window;
+    readonly send?: (url: string, body: string) => void;
+}
+export interface Beacon {
+    track(name: string, props?: Record<string, string | number | boolean | null>): void;
+    pageView(): void;
+    /** The person's answer under `consented`; sets or clears the cookie and remembers it. */
+    accept(): void;
+    decline(): void;
+    answer(): ConsentAnswer;
+    visitorId(): string | null;
+    flush(): void;
+    destroy(): void;
+}
+export declare function createBeacon(options: BeaconOptions): Beacon;

package/dist/browser/index.js

@@ -0,0 +1,203 @@
+/**
+ * The beacon: `page.view` on load and on history changes, `page.leave` with
+ * the seconds on the page, and whatever the host `track`s, batched twenty at
+ * a time or every five seconds and posted with `sendBeacon` (falling back to
+ * `fetch` with `keepalive`). It sends the pathname, never the query string,
+ * and never a user id: the collector knows who is signed in from the session
+ * cookie, and a client-supplied id would be a claim (D14).
+ *
+ * Consent (D15): `none` keeps nothing; `consented` starts as `none` until
+ * `accept()`; `always` sets the first-party cookie without asking. The cookie
+ * `_rp` holds the visitor id and the answer, one year, SameSite=Lax, Secure;
+ * the session id lives in `sessionStorage` under `consented`/`always` and in
+ * memory under `none`. Nothing about the browser is stored beyond that.
+ *
+ * No dependencies, no globals beyond `window`; under 3 KB gzipped.
+ */
+const COOKIE = '_rp';
+const YEAR = 365 * 24 * 60 * 60;
+const NAME = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)?$/;
+function randomId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    let s = '';
+    for (const b of bytes)
+        s += b.toString(16).padStart(2, '0');
+    return s;
+}
+function readCookie(doc) {
+    const m = doc.cookie.match(new RegExp(`(?:^|; )${COOKIE}=([^;]*)`));
+    if (!m?.[1])
+        return null;
+    const [id, answer] = decodeURIComponent(m[1]).split('.');
+    if (!id || !/^[a-f0-9]{32}$/.test(id))
+        return null;
+    return { id, answer: answer === 'a' ? 'accepted' : answer === 'd' ? 'declined' : null };
+}
+function writeCookie(doc, value) {
+    doc.cookie =
+        value === null
+            ? `${COOKIE}=; Max-Age=0; Path=/; SameSite=Lax; Secure`
+            : `${COOKIE}=${encodeURIComponent(value)}; Max-Age=${YEAR}; Path=/; SameSite=Lax; Secure`;
+}
+export function createBeacon(options) {
+    const win = options.window ?? window;
+    const doc = win.document;
+    const mode = options.consent ?? 'consented';
+    const batchSize = Math.min(20, options.batch ?? 20);
+    const flushMs = options.flushMs ?? 5000;
+    const send = options.send ??
+        ((url, body) => {
+            const blob = new Blob([body], { type: 'application/json' });
+            if (!win.navigator.sendBeacon?.(url, blob)) {
+                void win.fetch(url, { method: 'POST', body, keepalive: true, credentials: 'include' });
+            }
+        });
+    // Identity: a visitor id only with consent; a session id per tab.
+    let cookie = readCookie(doc);
+    let answer = cookie?.answer ?? null;
+    const declined = () => mode === 'none' || (mode === 'consented' && answer !== 'accepted');
+    if (mode === 'always' && !cookie) {
+        cookie = { id: randomId(), answer: 'accepted' };
+        writeCookie(doc, `${cookie.id}.a`);
+    }
+    if (declined()) {
+        if (cookie && answer !== 'declined')
+            cookie = null;
+    }
+    let sessionId = null;
+    function inMemorySession() {
+        if (!sessionId)
+            sessionId = randomId();
+        return sessionId;
+    }
+    function session() {
+        if (declined())
+            return inMemorySession();
+        try {
+            const stored = win.sessionStorage.getItem(`${COOKIE}s`);
+            if (stored && /^[a-f0-9]{32}$/.test(stored))
+                return stored;
+            const fresh = randomId();
+            win.sessionStorage.setItem(`${COOKIE}s`, fresh);
+            return fresh;
+        }
+        catch {
+            return inMemorySession();
+        }
+    }
+    const queue = [];
+    let timer = null;
+    function flush() {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (queue.length === 0)
+            return;
+        const events = queue.splice(0, batchSize);
+        const body = JSON.stringify({
+            site: options.site,
+            visitorId: declined() ? null : (cookie?.id ?? null),
+            sessionId: session(),
+            events,
+        });
+        try {
+            send(options.collector, body);
+        }
+        catch {
+            // A beacon that cannot leave is dropped; nothing here may throw into the page.
+        }
+        if (queue.length > 0)
+            flush();
+    }
+    function push(event) {
+        queue.push(event);
+        if (queue.length >= batchSize)
+            flush();
+        else if (!timer)
+            timer = setTimeout(flush, flushMs);
+    }
+    const pathOf = () => win.location.pathname || '/';
+    let currentPath = pathOf();
+    let enteredAt = Date.now();
+    let lastReferrer = doc.referrer || null;
+    function pageView() {
+        currentPath = pathOf();
+        enteredAt = Date.now();
+        push({
+            name: 'page.view',
+            at: Date.now(),
+            path: currentPath,
+            referrer: lastReferrer,
+            props: {},
+        });
+        lastReferrer = null;
+    }
+    function pageLeave() {
+        const duration = Math.max(0, Math.round((Date.now() - enteredAt) / 1000));
+        push({ name: 'page.leave', at: Date.now(), path: currentPath, props: {}, duration });
+        flush();
+    }
+    function track(name, props = {}) {
+        if (!NAME.test(name) || name.startsWith('page.'))
+            return;
+        push({ name, at: Date.now(), path: pathOf(), props });
+    }
+    // History: a SPA navigation is a page view too.
+    const history = win.history;
+    const pushState = history.pushState.bind(history);
+    const replaceState = history.replaceState.bind(history);
+    const onNavigate = () => {
+        if (pathOf() === currentPath)
+            return;
+        pageLeave();
+        pageView();
+    };
+    history.pushState = (...args) => {
+        pushState(...args);
+        onNavigate();
+    };
+    history.replaceState = (...args) => {
+        replaceState(...args);
+        onNavigate();
+    };
+    const onPop = () => onNavigate();
+    const onHide = () => {
+        if (doc.visibilityState === 'hidden')
+            pageLeave();
+    };
+    win.addEventListener('popstate', onPop);
+    doc.addEventListener('visibilitychange', onHide);
+    win.addEventListener('pagehide', pageLeave);
+    pageView();
+    return {
+        track,
+        pageView,
+        accept() {
+            if (mode !== 'consented')
+                return;
+            answer = 'accepted';
+            cookie = { id: cookie?.id ?? randomId(), answer };
+            writeCookie(doc, `${cookie.id}.a`);
+        },
+        decline() {
+            if (mode !== 'consented')
+                return;
+            answer = 'declined';
+            cookie = null;
+            writeCookie(doc, `${randomId()}.d`);
+        },
+        answer: () => answer,
+        visitorId: () => (declined() ? null : (cookie?.id ?? null)),
+        flush,
+        destroy() {
+            flush();
+            history.pushState = pushState;
+            history.replaceState = replaceState;
+            win.removeEventListener('popstate', onPop);
+            doc.removeEventListener('visibilitychange', onHide);
+            win.removeEventListener('pagehide', pageLeave);
+        },
+    };
+}

package/dist/fake/index.d.ts

@@ -1,5 +1,5 @@
 import type { ReportingEventRow } from '../tables.js';
-import type { AlertFinding, Logger, Reporting } from '../types.js';
+import type { AlertFinding, Logger, Reporting, TrackInput } from '../types.js';
 /**
  * An in-memory `Reporting` for a host's unit tests: same validation, same
  * shape, no database. `rows` is the table; `alerts` is what `onAlert` would
@@ -8,6 +8,10 @@ import type { AlertFinding, Logger, Reporting } from '../types.js';
 export interface FakeReporting extends Reporting {
     readonly rows: ReportingEventRow[];
     readonly alerts: AlertFinding[];
+    /** What `analytics.track` received. */
+    readonly tracked: (TrackInput & {
+        site: string;
+    })[];
     reset(): void;
 }
 export declare function createFakeReporting(opts?: {

package/dist/fake/index.js

@@ -8,6 +8,7 @@ export function createFakeReporting(opts = {}) {
     const log = opts.log ?? silent;
     const rows = [];
     const alerts = [];
+    const tracked = [];
     let settings = { ...DEFAULT_SETTINGS };
     let id = 0;
     const fake = {
@@ -16,11 +17,7 @@ export function createFakeReporting(opts = {}) {
         tables,
         rows,
         alerts,
-        // Not a database; a host's test that reaches `db` through the fake is
-        // testing the wrong thing, and this makes that loud.
-        get db() {
-            throw new Error('createFakeReporting has no database');
-        },
+        tracked,
         event(input) {
             const v = eventInputSchema.parse(input);
             id += 1;
@@ -93,7 +90,21 @@ export function createFakeReporting(opts = {}) {
                 return { before, after: settings, by, changed };
             },
         },
-        stats: () => ({ queued: 0, dropped: 0, invalid: 0, flushed: rows.length, failedFlushes: 0 }),
+        analytics: {
+            async track(input) {
+                tracked.push({ ...input, site });
+            },
+            async series() {
+                return [];
+            },
+            async weekly() {
+                return [];
+            },
+            async recent() {
+                return [];
+            },
+        },
+        stats: () => ({ queued: 0, dropped: 0, invalid: 0, flushed: rows.length }),
         reset() {
             rows.length = 0;
             alerts.length = 0;

package/dist/housekeeping/index.d.ts

@@ -40,15 +40,17 @@ export interface TaskContext {
     renew(): Promise<boolean>;
     /** The run must finish, or stop scheduling work, by this instant. */
     readonly deadline: Date;
+    /** The task's completed-history watermark as claimed, or null. */
+    readonly watermark: string | null;
+    /** Moves the watermark, fenced by the claim token; false when the lease was lost. Pass a transaction to commit it with the work it vouches for. */
+    commitWatermark(value: string, tx?: Db): Promise<boolean>;
 }
 export interface HousekeepingOptions {
     reporting: Reporting;
-    db?: Db;
+    db: Db;
     now?: () => Date;
     /** Per process. Default 60,000 ms. */
     debounceMs?: number;
-    /** Tasks run at once. Default 2. */
-    concurrency?: number;
 }
 export interface Housekeeping {
     /** Idempotent by name. The row is created on the next tick. */
@@ -61,3 +63,4 @@ export interface Housekeeping {
 }
 export declare function createHousekeeping(options: HousekeepingOptions): Housekeeping;
 export { pruneEvents, retentionLag } from './tasks.js';
+export { pruneAnalytics, rollupAnalytics, rollupAnalyticsWeekly } from '../analytics/tasks.js';

package/dist/housekeeping/index.js

@@ -2,12 +2,13 @@ import { eq, sql } from 'drizzle-orm';
 import { KIND_PATTERN } from '../schema.js';
 import { reportingTasks } from '../tables.js';
 import { describe } from '../writer.js';
+/** Tasks run at once: enough that a slow prune does not delay the alerts, few enough to be one connection each. */
+const CONCURRENCY = 2;
 export function createHousekeeping(options) {
     const { reporting } = options;
-    const db = options.db ?? reporting.db;
+    const db = options.db;
     const now = options.now ?? (() => new Date());
     const debounceMs = options.debounceMs ?? 60_000;
-    const concurrency = Math.max(1, options.concurrency ?? 2);
     const registry = new Map();
     let lastTick = 0;
     let ticking = null;
@@ -50,10 +51,19 @@ export function createHousekeeping(options) {
                 .where(sql `${reportingTasks.task} = ${task.name}
             and ${reportingTasks.nextDueAt} <= now()
             and (${reportingTasks.leaseExpiresAt} is null or ${reportingTasks.leaseExpiresAt} < now())`)
-                .returning({ token: reportingTasks.claimToken });
-            return claimed[0]?.token ?? null;
+                .returning({ token: reportingTasks.claimToken, watermark: reportingTasks.watermark });
+            const row = claimed[0];
+            return row?.token ? { token: row.token, watermark: row.watermark ?? null } : null;
         });
     }
+    async function commitWatermark(task, token, value, handle) {
+        const rows = await handle
+            .update(reportingTasks)
+            .set({ watermark: value })
+            .where(sql `${reportingTasks.task} = ${task.name} and ${reportingTasks.claimToken} = ${token}`)
+            .returning({ task: reportingTasks.task });
+        return rows.length === 1;
+    }
     async function renew(task, token) {
         const rows = await db
             .update(reportingTasks)
@@ -77,7 +87,7 @@ export function createHousekeeping(options) {
         })
             .where(sql `${reportingTasks.task} = ${task.name} and ${reportingTasks.claimToken} = ${token}`);
     }
-    async function runClaimed(task, token, settings) {
+    async function runClaimed(task, token, watermark, settings) {
         const started = now();
         const deadline = new Date(started.getTime() + task.lease);
         let timer;
@@ -94,6 +104,8 @@ export function createHousekeeping(options) {
                     now,
                     renew: () => renew(task, token),
                     deadline,
+                    watermark,
+                    commitWatermark: (value, tx) => commitWatermark(task, token, value, tx ?? db),
                 }),
                 timeout,
             ]);
@@ -122,17 +134,17 @@ export function createHousekeeping(options) {
         }
     }
     async function runOne(task, settings) {
-        const token = await claim(task);
-        if (!token)
+        const claimed = await claim(task);
+        if (!claimed)
             return 'skipped';
-        return runClaimed(task, token, settings);
+        return runClaimed(task, claimed.token, claimed.watermark, settings);
     }
     async function tickNow() {
         await ensureRows();
         const settings = await reporting.settings.get();
         const queue = [...registry.values()];
         const counts = { claimed: 0, skipped: 0, ran: 0, failed: 0 };
-        const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+        const workers = Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
             for (let task = queue.shift(); task; task = queue.shift()) {
                 try {
                     const outcome = await runOne(task, settings);
@@ -196,3 +208,4 @@ export function createHousekeeping(options) {
     };
 }
 export { pruneEvents, retentionLag } from './tasks.js';
+export { pruneAnalytics, rollupAnalytics, rollupAnalyticsWeekly } from '../analytics/tasks.js';