@wtfalch/reporting 0.1.0

package/dist/housekeeping/index.js

@@ -0,0 +1,198 @@
+import { eq, sql } from 'drizzle-orm';
+import { KIND_PATTERN } from '../schema.js';
+import { reportingTasks } from '../tables.js';
+import { describe } from '../writer.js';
+export function createHousekeeping(options) {
+    const { reporting } = options;
+    const db = options.db ?? reporting.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;
+    let rowsEnsured = false;
+    function register(task) {
+        if (!KIND_PATTERN.test(task.name)) {
+            throw new Error(`housekeeping: task name "${task.name}" is not namespace.name`);
+        }
+        registry.set(task.name, task);
+        rowsEnsured = false;
+    }
+    async function ensureRows() {
+        if (rowsEnsured || registry.size === 0)
+            return;
+        await db
+            .insert(reportingTasks)
+            .values([...registry.keys()].map((task) => ({ task })))
+            .onConflictDoNothing({ target: reportingTasks.task });
+        rowsEnsured = true;
+    }
+    /** The one transaction that decides. Returns the token when this process now holds the task. */
+    async function claim(task) {
+        return db.transaction(async (tx) => {
+            const held = await tx
+                .select({ task: reportingTasks.task })
+                .from(reportingTasks)
+                .where(eq(reportingTasks.task, task.name))
+                .for('update', { skipLocked: true });
+            if (held.length === 0)
+                return null;
+            const claimed = await tx
+                .update(reportingTasks)
+                .set({
+                claimToken: sql `gen_random_uuid()`,
+                lastStartedAt: sql `now()`,
+                leaseExpiresAt: sql `now() + make_interval(secs => ${task.lease / 1000}::double precision)`,
+                lastOutcome: null,
+                lastError: null,
+            })
+                .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;
+        });
+    }
+    async function renew(task, token) {
+        const rows = await db
+            .update(reportingTasks)
+            .set({
+            leaseExpiresAt: sql `now() + make_interval(secs => ${task.lease / 1000}::double precision)`,
+        })
+            .where(sql `${reportingTasks.task} = ${task.name} and ${reportingTasks.claimToken} = ${token}`)
+            .returning({ task: reportingTasks.task });
+        return rows.length === 1;
+    }
+    async function complete(task, token, outcome, error) {
+        const delay = (outcome === 'error' ? task.retry : task.every) / 1000;
+        await db
+            .update(reportingTasks)
+            .set({
+            lastFinishedAt: sql `now()`,
+            leaseExpiresAt: null,
+            nextDueAt: sql `now() + make_interval(secs => ${delay}::double precision)`,
+            lastOutcome: outcome,
+            lastError: error ? error.slice(0, 512) : null,
+        })
+            .where(sql `${reportingTasks.task} = ${task.name} and ${reportingTasks.claimToken} = ${token}`);
+    }
+    async function runClaimed(task, token, settings) {
+        const started = now();
+        const deadline = new Date(started.getTime() + task.lease);
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`timed out after ${task.lease} ms`)), task.lease);
+            timer.unref?.();
+        });
+        try {
+            await Promise.race([
+                task.run({
+                    reporting,
+                    db,
+                    settings,
+                    now,
+                    renew: () => renew(task, token),
+                    deadline,
+                }),
+                timeout,
+            ]);
+            await complete(task, token, 'ok', null);
+            reporting.event({
+                kind: 'housekeeping.task_ran',
+                message: `${task.name} ran in ${now().getTime() - started.getTime()} ms`,
+                data: { task: task.name, ms: now().getTime() - started.getTime() },
+            });
+            return 'ok';
+        }
+        catch (error) {
+            const text = describe(error);
+            await complete(task, token, 'error', text).catch(() => undefined);
+            reporting.event({
+                kind: 'housekeeping.task_failed',
+                level: 'error',
+                message: `${task.name} failed: ${text}`.slice(0, 512),
+                data: { task: task.name, error: text.slice(0, 200) },
+            });
+            return 'error';
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async function runOne(task, settings) {
+        const token = await claim(task);
+        if (!token)
+            return 'skipped';
+        return runClaimed(task, token, 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 () => {
+            for (let task = queue.shift(); task; task = queue.shift()) {
+                try {
+                    const outcome = await runOne(task, settings);
+                    if (outcome === 'skipped')
+                        counts.skipped += 1;
+                    else {
+                        counts.claimed += 1;
+                        if (outcome === 'ok')
+                            counts.ran += 1;
+                        else
+                            counts.failed += 1;
+                    }
+                }
+                catch (error) {
+                    // The claim itself failed (the database was away). Nothing to
+                    // complete; the row is untouched and the next tick tries again.
+                    counts.skipped += 1;
+                    reporting.log.error({ err: describe(error), task: task.name }, 'housekeeping: claim failed');
+                }
+            }
+        });
+        await Promise.all(workers);
+        if (counts.claimed > 0) {
+            reporting.event({
+                kind: 'housekeeping.tick',
+                message: `tick: ${counts.ran} ran, ${counts.failed} failed, ${counts.skipped} skipped`,
+                data: counts,
+            });
+        }
+        await reporting.flush({ deadlineMs: 5000 });
+    }
+    return {
+        register,
+        tasks: () => [...registry.values()],
+        async tick() {
+            const t = Date.now();
+            if (ticking)
+                return ticking;
+            if (t - lastTick < debounceMs)
+                return;
+            lastTick = t;
+            ticking = tickNow()
+                .catch((error) => {
+                reporting.log.error({ err: describe(error) }, 'housekeeping: tick failed');
+            })
+                .finally(() => {
+                ticking = null;
+            });
+            return ticking;
+        },
+        async runNow(name) {
+            const task = registry.get(name);
+            if (!task)
+                throw new Error(`housekeeping: no task "${name}"`);
+            await ensureRows();
+            const settings = await reporting.settings.get();
+            const outcome = await runOne(task, settings);
+            await reporting.flush({ deadlineMs: 5000 });
+            return outcome === 'ok' ? 'ran' : outcome === 'skipped' ? 'skipped' : 'failed';
+        },
+    };
+}
+export { pruneEvents, retentionLag } from './tasks.js';

package/dist/housekeeping/tasks.d.ts

@@ -0,0 +1,20 @@
+import type { Db } from '../types.js';
+import type { Task } from './index.js';
+/** `db.execute` returns an array on postgres-js and `{ rows }` on PGlite; this reads either. */
+export declare function rowsOf(result: unknown): Record<string, unknown>[];
+/**
+ * Deletes rows older than the operator's window, up to twenty batches of
+ * 5,000 per run, each in its own statement with a bounded timeout, renewing
+ * the lease between batches. The function clamps the window itself, so a
+ * setting of one day still keeps a week.
+ */
+export declare const pruneEvents: Task;
+export declare function pruneBatch(db: Db, days: number, batch: number): Promise<number>;
+/**
+ * The watchdog on the promise prune makes: if the oldest row is older than
+ * one and a half windows, prune has not been running and somebody should
+ * know. It shares the tick's failure domain and cannot report a tick that
+ * is entirely down; it catches the case where the tick runs and prune
+ * keeps failing or never gets claimed.
+ */
+export declare const retentionLag: Task;

package/dist/housekeeping/tasks.js

@@ -0,0 +1,82 @@
+import { sql } from 'drizzle-orm';
+import { reportingEvents } from '../tables.js';
+/** `db.execute` returns an array on postgres-js and `{ rows }` on PGlite; this reads either. */
+export function rowsOf(result) {
+    if (Array.isArray(result))
+        return result;
+    const r = result;
+    return Array.isArray(r?.rows) ? r.rows : [];
+}
+const HOUR = 60 * 60 * 1000;
+const DAY = 24 * HOUR;
+/**
+ * Deletes rows older than the operator's window, up to twenty batches of
+ * 5,000 per run, each in its own statement with a bounded timeout, renewing
+ * the lease between batches. The function clamps the window itself, so a
+ * setting of one day still keeps a week.
+ */
+export const pruneEvents = {
+    name: 'reporting.prune_events',
+    every: HOUR,
+    lease: 10 * 60 * 1000,
+    retry: 15 * 60 * 1000,
+    async run(ctx) {
+        const days = ctx.settings['events.retention_days'];
+        let total = 0;
+        for (let i = 0; i < 20; i += 1) {
+            if (ctx.now().getTime() > ctx.deadline.getTime() - 30_000)
+                break;
+            const n = await pruneBatch(ctx.db, days, 5000);
+            total += n;
+            if (n < 5000)
+                break;
+            if (!(await ctx.renew()))
+                break;
+        }
+        if (total > 0) {
+            ctx.reporting.event({
+                kind: 'reporting.pruned',
+                message: `pruned ${total} event(s) older than ${days} days`,
+                data: { rows: total, days },
+            });
+        }
+    },
+};
+export async function pruneBatch(db, days, batch) {
+    return db.transaction(async (tx) => {
+        await tx.execute(sql `set local statement_timeout = '30s'`);
+        const result = await tx.execute(sql `select reporting_prune_events(make_interval(days => ${days}::int), ${batch}::int) as n`);
+        const [row] = rowsOf(result);
+        return Number(row?.n ?? 0);
+    });
+}
+/**
+ * The watchdog on the promise prune makes: if the oldest row is older than
+ * one and a half windows, prune has not been running and somebody should
+ * know. It shares the tick's failure domain and cannot report a tick that
+ * is entirely down; it catches the case where the tick runs and prune
+ * keeps failing or never gets claimed.
+ */
+export const retentionLag = {
+    name: 'reporting.retention_lag',
+    every: DAY,
+    lease: 60 * 1000,
+    retry: HOUR,
+    async run(ctx) {
+        const days = ctx.settings['events.retention_days'];
+        const [row] = await ctx.db
+            .select({ oldest: sql `min(${reportingEvents.occurredAt})` })
+            .from(reportingEvents);
+        const oldest = row?.oldest ? new Date(row.oldest) : null;
+        if (!oldest)
+            return;
+        const lagDays = (ctx.now().getTime() - oldest.getTime()) / DAY;
+        if (lagDays > days * 1.5) {
+            ctx.reporting.alert({
+                check: 'retention_lag',
+                message: `the oldest event is ${Math.floor(lagDays)} days old against a ${days}-day window; prune is not keeping up`,
+                detail: { oldestDays: Math.floor(lagDays), windowDays: days },
+            });
+        }
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { Reporting, ReportingOptions } from './types.js';
+export * from './schema.js';
+export * from './tables.js';
+export * from './types.js';
+export { alertKind, projectDetail } from './alerts.js';
+export { DEFAULT_SETTINGS, RETENTION_BOUNDS, SETTING_KEYS } from './settings.js';
+/**
+ * The host's one instance, built once over its drizzle handle and its
+ * logger. Framework-neutral: `defer` is how the host says "after this unit of
+ * work" (the `./next` entry passes `after()`), and nothing here reads a
+ * request, a session or an environment variable other than NODE_ENV.
+ */
+export declare function createReporting(options: ReportingOptions): Reporting;

package/dist/index.js

@@ -0,0 +1,82 @@
+import { alertRow } from './alerts.js';
+import { eventsPage } from './reader.js';
+import { siteSchema } from './schema.js';
+import { getSettings, setSettings } from './settings.js';
+import { tables } from './tables.js';
+import { Writer, describe } from './writer.js';
+export * from './schema.js';
+export * from './tables.js';
+export * from './types.js';
+export { alertKind, projectDetail } from './alerts.js';
+export { DEFAULT_SETTINGS, RETENTION_BOUNDS, SETTING_KEYS } from './settings.js';
+function modeFromEnv() {
+    const env = process.env.NODE_ENV;
+    return env === 'development' || env === 'test' ? env : 'production';
+}
+/**
+ * The host's one instance, built once over its drizzle handle and its
+ * logger. Framework-neutral: `defer` is how the host says "after this unit of
+ * work" (the `./next` entry passes `after()`), and nothing here reads a
+ * request, a session or an environment variable other than NODE_ENV.
+ */
+export function createReporting(options) {
+    const site = siteSchema.parse(options.site);
+    const now = options.now ?? (() => new Date());
+    const mode = options.mode ?? modeFromEnv();
+    const writer = new Writer({
+        db: options.db,
+        log: options.log,
+        site,
+        mode,
+        now,
+        defer: options.defer ??
+            ((fn) => {
+                setTimeout(() => void fn(), 0);
+            }),
+        queueLimit: options.queueLimit ?? 1000,
+        batchSize: options.batchSize ?? 500,
+        flushEveryMs: options.flushEveryMs ?? 1000,
+    });
+    const reporting = {
+        site,
+        db: options.db,
+        log: options.log,
+        tables,
+        event: (input) => writer.event(input),
+        alert(finding) {
+            writer.event(alertRow(finding));
+            if (!options.onAlert)
+                return;
+            try {
+                options.onAlert(finding);
+            }
+            catch (error) {
+                options.log.error({ err: describe(error) }, 'reporting: onAlert threw');
+            }
+        },
+        flush: (opts) => writer.flush(opts),
+        events: { page: (opts) => eventsPage(options.db, opts) },
+        settings: {
+            get: () => getSettings(options.db),
+            async set(patch, by) {
+                const change = await setSettings(options.db, patch, by);
+                if (change.changed.length > 0) {
+                    writer.event({
+                        kind: 'reporting.settings_changed',
+                        message: `settings changed: ${change.changed.join(', ')}`,
+                        actor: by,
+                        data: Object.fromEntries(change.changed.flatMap((k) => [
+                            [`${k}.before`, change.before[k]],
+                            [`${k}.after`, change.after[k]],
+                        ])),
+                    });
+                    if (options.audit)
+                        await options.audit(change);
+                }
+                return change;
+            },
+        },
+        stats: () => writer.stats(),
+    };
+    return reporting;
+}

package/dist/migrations/0001_reporting.sql

@@ -0,0 +1,154 @@
+-- @wtfalch/reporting: the operational event log, the housekeeping task rows
+-- and the settings the housekeeping reads. Mirrors src/tables.ts.
+--
+-- Every statement is idempotent. Applied by the host's own migrate script
+-- after the host copies this file into its drizzle/ directory as the next
+-- number (reporting-migrations); never edited there.
+--
+-- Estate-shaped: the DO block at the end assumes the runtime-role convention
+-- (a role named <database>_rt that owns nothing and serves the app). A host
+-- without that role gets the tables and the function and no revokes take
+-- effect, which the package README says plainly.
+
+create table if not exists reporting_events (
+  id              bigint generated always as identity primary key,
+  occurred_at     timestamptz not null default now(),
+  level           text not null,
+  kind            text not null,
+  kind_ns         text generated always as (split_part(kind, '.', 1)) stored,
+  site            text not null,
+  tenant_id       uuid,
+  actor_class     text,
+  -- An issuer or credential id. No foreign key and no cascade on purpose:
+  -- rows leave this table by age through reporting_prune_events, never by
+  -- erasure. That is a deliberate retention exception for a linkable
+  -- identifier, written down in the host's tenancy notes, not a claim that
+  -- the id is anonymous.
+  actor_id        text,
+  request_id      text,
+  target_type     text,
+  target_id       text,
+  message         text not null,
+  data            jsonb not null default '{}'::jsonb,
+  schema_version  smallint not null default 1,
+  constraint reporting_events_level_check check (level in ('info', 'warn', 'error', 'alert')),
+  constraint reporting_events_kind_check check (kind ~ '^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$'),
+  constraint reporting_events_site_check check (site ~ '^[a-z][a-z0-9-]{0,63}$'),
+  constraint reporting_events_actor_class_check check (actor_class is null or actor_class in ('human', 'api_key', 'agent', 'service')),
+  constraint reporting_events_actor_pair_check check ((actor_id is null) = (actor_class is null)),
+  constraint reporting_events_actor_id_check check (actor_id is null or length(actor_id) between 1 and 256),
+  constraint reporting_events_request_id_check check (request_id is null or length(request_id) between 1 and 128),
+  constraint reporting_events_target_type_check check (target_type is null or length(target_type) between 1 and 64),
+  constraint reporting_events_target_id_check check (target_id is null or length(target_id) between 1 and 256),
+  constraint reporting_events_target_pair_check check ((target_id is null) = (target_type is null)),
+  constraint reporting_events_message_check check (length(message) between 1 and 512),
+  constraint reporting_events_data_object_check check (jsonb_typeof(data) = 'object'),
+  constraint reporting_events_data_size_check check (octet_length(data::text) <= 16384),
+  -- Flat: no value is an object or an array. A nested payload is where a
+  -- provider response or a request body sneaks in whole. `strict`, because
+  -- lax mode unwraps an array before the filter sees it and would never
+  -- call one an array.
+  constraint reporting_events_data_flat_check check (not jsonb_path_exists(data, 'strict $.* ? (@.type() == "object" || @.type() == "array")')),
+  -- The keys that carry a person or a secret by name. A guardrail, not a
+  -- proof: src/schema.ts refuses the same list before a row is queued, and
+  -- schema.test.ts pins the two lists equal.
+  constraint reporting_events_data_keys_check check (not (data ?| array['email', 'name', 'display_name', 'displayName', 'password', 'secret', 'token', 'authorization']))
+);
+
+comment on column reporting_events.actor_id is
+  'An issuer or credential id. No foreign key and no cascade on purpose: rows leave by age, not by erasure.';
+
+-- Newest first is every reader's order; the partial indexes serve the
+-- filters the operator page offers without indexing what nobody asks for.
+create index if not exists reporting_events_time_idx
+  on reporting_events (occurred_at desc, id desc);
+create index if not exists reporting_events_tenant_time_idx
+  on reporting_events (tenant_id, occurred_at desc, id desc) where tenant_id is not null;
+create index if not exists reporting_events_ns_time_idx
+  on reporting_events (kind_ns, occurred_at desc, id desc);
+create index if not exists reporting_events_problem_time_idx
+  on reporting_events (occurred_at desc, id desc) where level in ('error', 'alert');
+create index if not exists reporting_events_request_idx
+  on reporting_events (request_id, occurred_at desc) where request_id is not null;
+-- Hourly bulk deletes are the pattern the default scale factor handles badly.
+alter table reporting_events set (autovacuum_vacuum_scale_factor = 0.02);
+
+-- One row per registered housekeeping task: when it is next due, who holds
+-- it now (a claim token and a lease), and how its last run ended. Claimed
+-- with FOR UPDATE SKIP LOCKED in a short transaction; never with an advisory
+-- lock, which is session state on whichever pooled connection served it.
+create table if not exists reporting_tasks (
+  task              text primary key,
+  next_due_at       timestamptz not null default now(),
+  last_started_at   timestamptz,
+  last_finished_at  timestamptz,
+  lease_expires_at  timestamptz,
+  claim_token       uuid,
+  last_outcome      text,
+  last_error        text,
+  -- Free for a task's own bookkeeping: the analytics rollup keeps its
+  -- completed-day watermark here.
+  watermark         text,
+  constraint reporting_tasks_task_check check (task ~ '^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$'),
+  constraint reporting_tasks_outcome_check check (last_outcome is null or last_outcome in ('ok', 'error', 'skipped')),
+  constraint reporting_tasks_error_check check (last_error is null or length(last_error) <= 512)
+);
+
+-- Operator-edited settings, one row per key. `events.*` is this release's;
+-- `analytics.*` is reserved for the next.
+create table if not exists reporting_settings (
+  key         text primary key,
+  value       jsonb not null,
+  updated_at  timestamptz not null default now(),
+  updated_by  text,
+  constraint reporting_settings_key_check check (key ~ '^(events|analytics)\.[a-z][a-z0-9_]*$')
+);
+
+-- The one way rows leave reporting_events. The window is clamped to between
+-- seven and four hundred days inside the function, so a caller (the app,
+-- through a setting an operator edits) can shorten history to a week and no
+-- further, and can never empty the table. Eligibility is by occurred_at,
+-- never by an id boundary: ids do not order occurrence when two containers
+-- buffer and flush independently, and a delayed insert must not make newer
+-- rows eligible. Batched so no statement holds a lock for long.
+create or replace function reporting_prune_events(retention interval, batch integer)
+returns integer
+language plpgsql
+security definer
+set search_path = pg_catalog, public
+as $$
+declare
+  w interval := greatest(interval '7 days', least(coalesce(retention, interval '30 days'), interval '400 days'));
+  b integer := greatest(1, least(coalesce(batch, 5000), 5000));
+  n integer;
+begin
+  with victims as (
+    select id from reporting_events
+     where occurred_at < now() - w
+     order by occurred_at, id
+     limit b
+  )
+  delete from reporting_events e using victims v where e.id = v.id;
+  get diagnostics n = row_count;
+  return n;
+end
+$$;
+revoke all on function reporting_prune_events(interval, integer) from public;
+
+-- The runtime role keeps SELECT and INSERT on all three tables, UPDATE on
+-- tasks and settings because the claim protocol and the settings page write
+-- them, and nothing that deletes. The host's default privileges granted the
+-- rest at create time; the revokes here win because they run later in the
+-- same file.
+do $$
+declare
+  rt text := current_database() || '_rt';
+begin
+  if exists (select 1 from pg_roles where rolname = rt) then
+    execute format('revoke update, delete, truncate on reporting_events from %I', rt);
+    execute format('revoke delete, truncate on reporting_tasks from %I', rt);
+    execute format('revoke delete, truncate on reporting_settings from %I', rt);
+    execute format('grant execute on function reporting_prune_events(interval, integer) to %I', rt);
+  end if;
+end
+$$;

package/dist/next/index.d.ts

@@ -0,0 +1,40 @@
+import type { Reporting } from '../types.js';
+/**
+ * The Next bindings: everything in the package that knows what a request is.
+ * Peer on `next`; a host without Next never imports this entry.
+ */
+/**
+ * The health route, and the heartbeat behind it. `connection()` first,
+ * because under `cacheComponents` a route with no dynamic read is
+ * prerendered, and the tick would otherwise run at build time with no
+ * database. The tick runs after the response and never throws.
+ */
+export declare function healthHandler(housekeeping: {
+    tick(): Promise<void>;
+}): () => Promise<Response>;
+export interface RequestContext {
+    /** Cloudflare's `cf-ray` when the request came through the tunnel, else a uuid. */
+    readonly id: string;
+    readonly ip: string | null;
+    readonly userAgent: string | null;
+    /** Two letters from `cf-ipcountry`, or null. */
+    readonly country: string | null;
+}
+/**
+ * Read once where a request enters (a Server Action, a route handler, a
+ * page's data component) and handed down. Outside a request scope it returns
+ * a fresh id and nulls, but only after `unstable_rethrow`: under
+ * `cacheComponents`, `headers()` in a prerender throws the signal Next uses
+ * to bail out, and swallowing that would poison the render.
+ */
+export declare function requestContext(): Promise<RequestContext>;
+/** `after()` inside a request; a timer outside one (boot, a script), so a row queued there still flushes. */
+export declare const deferWithAfter: (fn: () => Promise<void>) => void;
+/**
+ * One best-effort drain on SIGTERM, bounded so a rolling deploy's drain
+ * window is respected. Not a durable queue: a forced kill or a slow database
+ * loses what is queued, and the logger already has every row.
+ */
+export declare function registerShutdownFlush(reporting: Reporting, opts?: {
+    deadlineMs?: number;
+}): void;

package/dist/next/index.js

@@ -0,0 +1,67 @@
+import { randomUUID } from 'node:crypto';
+import { headers } from 'next/headers';
+import { unstable_rethrow } from 'next/navigation';
+import { after, connection } from 'next/server';
+/**
+ * The Next bindings: everything in the package that knows what a request is.
+ * Peer on `next`; a host without Next never imports this entry.
+ */
+/**
+ * The health route, and the heartbeat behind it. `connection()` first,
+ * because under `cacheComponents` a route with no dynamic read is
+ * prerendered, and the tick would otherwise run at build time with no
+ * database. The tick runs after the response and never throws.
+ */
+export function healthHandler(housekeeping) {
+    return async () => {
+        await connection();
+        after(() => housekeeping.tick());
+        return Response.json({ ok: true, ts: new Date().toISOString() });
+    };
+}
+/**
+ * Read once where a request enters (a Server Action, a route handler, a
+ * page's data component) and handed down. Outside a request scope it returns
+ * a fresh id and nulls, but only after `unstable_rethrow`: under
+ * `cacheComponents`, `headers()` in a prerender throws the signal Next uses
+ * to bail out, and swallowing that would poison the render.
+ */
+export async function requestContext() {
+    try {
+        const h = await headers();
+        const country = h.get('cf-ipcountry');
+        return {
+            id: (h.get('cf-ray') ?? randomUUID()).slice(0, 128),
+            ip: h.get('cf-connecting-ip'),
+            userAgent: h.get('user-agent'),
+            country: country && /^[A-Z]{2}$/.test(country) ? country : null,
+        };
+    }
+    catch (error) {
+        unstable_rethrow(error);
+        return { id: randomUUID(), ip: null, userAgent: null, country: null };
+    }
+}
+/** `after()` inside a request; a timer outside one (boot, a script), so a row queued there still flushes. */
+export const deferWithAfter = (fn) => {
+    try {
+        after(fn);
+    }
+    catch {
+        setTimeout(() => void fn(), 0);
+    }
+};
+let shutdownRegistered = false;
+/**
+ * One best-effort drain on SIGTERM, bounded so a rolling deploy's drain
+ * window is respected. Not a durable queue: a forced kill or a slow database
+ * loses what is queued, and the logger already has every row.
+ */
+export function registerShutdownFlush(reporting, opts = {}) {
+    if (shutdownRegistered)
+        return;
+    shutdownRegistered = true;
+    process.once('SIGTERM', () => {
+        void reporting.flush({ deadlineMs: opts.deadlineMs ?? 2000 });
+    });
+}

package/dist/reader.d.ts

@@ -0,0 +1,8 @@
+import type { Db, EventsPage, EventsPageOptions } from './types.js';
+/**
+ * Newest first, keyset-paged on `(occurred_at, id)`, which is the table's
+ * first index. Every filter is an equality on an indexed column. No
+ * permission is applied here: the host gates, and this returns rows as
+ * stored.
+ */
+export declare function eventsPage(db: Db, opts?: EventsPageOptions): Promise<EventsPage>;