@wtfalch/reporting 0.3.1 → 0.4.0

package/dist/analytics/reader.d.ts

@@ -43,6 +43,13 @@ export interface RecentOptions {
     readonly site: string;
     readonly tenantId?: string;
     readonly name?: string;
+    /**
+     * Everything one session did (gap issue #9): the lightest
+     * privacy-consistent equivalent of session replay, since every row
+     * already carries the visitor's per-tab session id and nothing else this
+     * reader would not already show.
+     */
+    readonly sessionId?: string;
     readonly limit?: number;
 }
 export interface RecentEvent {

package/dist/analytics/reader.js

@@ -78,7 +78,7 @@ export async function analyticsRecent(db, opts) {
         signedIn: sql `${t.userId} is not null`,
     })
         .from(t)
-        .where(and(eq(t.site, opts.site), opts.tenantId ? eq(t.tenantId, opts.tenantId) : undefined, opts.name ? eq(t.name, opts.name) : undefined))
+        .where(and(eq(t.site, opts.site), opts.tenantId ? eq(t.tenantId, opts.tenantId) : undefined, opts.name ? eq(t.name, opts.name) : undefined, opts.sessionId ? eq(t.sessionId, opts.sessionId) : undefined))
         .orderBy(desc(t.occurredAt), desc(t.id))
         .limit(limit);
     return rows.map((r) => ({ ...r, signedIn: Boolean(r.signedIn) }));

package/dist/errors/capture.d.ts

@@ -1,4 +1,4 @@
-import type { CaptureContext, Db, EventInput, Logger } from '../types.js';
+import type { AlertFinding, CaptureContext, Db, EventInput, Logger } from '../types.js';
 /**
  * The one path an uncaught exception takes into the estate
  * (docs/plans/errors.md, "Surface" and "Why a second table, not just an
@@ -7,6 +7,14 @@ import type { CaptureContext, Db, EventInput, Logger } from '../types.js';
  * and one upsert into the fingerprint's group — first seen, last seen, how
  * many, and whether an operator has already dealt with it.
  *
+ * A group that is brand new, or that just reopened from resolved or
+ * ignored, also fires `o.alert` once -- never a repeat occurrence of an
+ * error that was already open, which would make this a flood rather than a
+ * page. `o.alert` is the same host-supplied `onAlert` hook `Reporting.alert`
+ * already writes an `alert.<check>` row and calls (index.ts's `fireAlert`);
+ * this package holds no vendor of its own to page through.
+ *
+
  * Two contracts this must never break, both sharpened from the writer's own
  * (writer.ts's header comment) for an error reporter specifically:
  *
@@ -27,6 +35,8 @@ export interface CaptureOptions {
     readonly db: Db;
     readonly log: Logger;
     readonly site: string;
+    /** Stamped on every group the same way `release` is; see `ReportingOptions.environment`. */
+    readonly environment?: string | null;
     readonly now: () => Date;
     /** Runs the group upsert after the current unit of work, same as the writer's flush (writer.ts). */
     readonly defer: (fn: () => Promise<void>) => void;
@@ -34,7 +44,19 @@ export interface CaptureOptions {
     readonly event: (input: EventInput) => void;
     /** Stamped on a fresh group when a capture's own context supplies none. */
     readonly release?: string | null;
+    /**
+     * Fires once when `captureError` creates a fresh group or reopens a
+     * resolved/ignored one -- never on a repeat occurrence of an
+     * already-open error, which would make this a flood rather than a page.
+     * The host's own `onAlert` (docs/plans/errors.md: "a pager is a later
+     * decision now that nothing pages" -- this is that decision). Never
+     * called for a group upsert that fails or is dropped.
+     */
+    readonly alert?: (finding: AlertFinding) => void;
+    /** Extra env var names `heldSecrets` also redacts, beyond the estate's own KEYSTORE_*; see `ReportingOptions.redactEnvVars`. */
+    readonly redactEnvVars?: readonly string[];
 }
+export type UpsertOutcome = 'created' | 'reopened' | 'unchanged';
 /**
  * `captureError(error, context?)`: the class from `errorKind` (or the
  * context's own, when the caller already knows it), the message and stack

package/dist/errors/capture.js

@@ -1,4 +1,4 @@
-import { sql } from 'drizzle-orm';
+import { eq, sql } from 'drizzle-orm';
 import { ERROR_RUNTIMES, KIND_PATTERN, LIMITS } from '../schema.js';
 import { reportingErrors } from '../tables.js';
 import { describe } from '../writer.js';
@@ -71,8 +71,7 @@ function normaliseRuntime(runtime) {
     return runtime && ERROR_RUNTIMES.includes(runtime) ? runtime : 'server';
 }
 /**
- * `insert ... on conflict (fingerprint) do update`, one round trip so two
- * occurrences arriving at once still land as one row: bump `occurrences`,
+ * `insert ... on conflict (fingerprint) do update`: bump `occurrences`,
  * move `last_seen_at`, overwrite the sample fields with the newest
  * occurrence. `first_seen_at` is left out of `set` entirely, so a conflict
  * never moves it.
@@ -81,39 +80,76 @@ function normaliseRuntime(runtime) {
  * enforces (`reporting_errors_resolved_pair_check`, 0003_errors.sql) means
  * `state` can only move back to 'open' by clearing `resolved_at` and
  * `resolved_by` in the same statement, never one alone.
+ *
+ * Telling a brand-new group from a reopened one from a repeat occurrence
+ * needs the state from *before* this upsert touches it, and that read must
+ * not race a concurrent capture of the same fingerprint -- two occurrences
+ * arriving at once must still alert once, the same guarantee the row
+ * itself already had. A plain `select` run alongside the upsert (even in
+ * the same statement, via a CTE) does not give that: under READ COMMITTED
+ * a statement's snapshot is fixed at its start, so two concurrent
+ * transactions' own plain reads can each see "no row yet" even after one
+ * of them has since committed the insert -- there is no re-check the way
+ * an UPDATE's own target row gets. `select ... for update` does get that
+ * re-check (the same special case that makes `occurrences + 1` correct
+ * under conflict): it locks an existing row, so a second transaction's own
+ * `for update` blocks until the first commits, then reads the fresh
+ * value -- and locks nothing when there is no row yet, which is fine,
+ * because "created" is decided separately, from the insert's own `xmax`
+ * (0 exactly when this statement is what created the row, never a race:
+ * it reflects the row this transaction's own write produced). Both reads
+ * share one transaction so the lock from the first is still held for the
+ * second.
  */
 async function upsertGroup(db, site, s) {
-    const reopened = sql `case when ${reportingErrors.state} in ('resolved', 'ignored') then 'open' else ${reportingErrors.state} end`;
-    await db
-        .insert(reportingErrors)
-        .values({
-        fingerprint: s.fingerprint,
-        site,
-        kind: s.kind,
-        message: s.message,
-        stack: s.stack,
-        runtime: s.runtime,
-        release: s.release,
-        firstSeenAt: s.at,
-        lastSeenAt: s.at,
-        occurrences: 1,
-        tenantId: s.tenantId,
-        requestId: s.requestId,
-    })
-        .onConflictDoUpdate({
-        target: reportingErrors.fingerprint,
-        set: {
-            occurrences: sql `${reportingErrors.occurrences} + 1`,
-            lastSeenAt: s.at,
+    return db.transaction(async (tx) => {
+        const prior = await tx
+            .select({ state: reportingErrors.state })
+            .from(reportingErrors)
+            .where(eq(reportingErrors.fingerprint, s.fingerprint))
+            .for('update');
+        const priorState = prior[0]?.state ?? null;
+        const reopened = sql `case when ${reportingErrors.state} in ('resolved', 'ignored') then 'open' else ${reportingErrors.state} end`;
+        const written = await tx
+            .insert(reportingErrors)
+            .values({
+            fingerprint: s.fingerprint,
+            site,
+            kind: s.kind,
             message: s.message,
             stack: s.stack,
+            runtime: s.runtime,
+            release: s.release,
+            environment: s.environment,
+            firstSeenAt: s.at,
+            lastSeenAt: s.at,
+            occurrences: 1,
             tenantId: s.tenantId,
             requestId: s.requestId,
-            release: s.release,
-            state: reopened,
-            resolvedAt: sql `case when ${reportingErrors.state} in ('resolved', 'ignored') then null else ${reportingErrors.resolvedAt} end`,
-            resolvedBy: sql `case when ${reportingErrors.state} in ('resolved', 'ignored') then null else ${reportingErrors.resolvedBy} end`,
-        },
+        })
+            .onConflictDoUpdate({
+            target: reportingErrors.fingerprint,
+            set: {
+                occurrences: sql `${reportingErrors.occurrences} + 1`,
+                lastSeenAt: s.at,
+                message: s.message,
+                stack: s.stack,
+                tenantId: s.tenantId,
+                requestId: s.requestId,
+                release: s.release,
+                environment: s.environment,
+                state: reopened,
+                resolvedAt: sql `case when ${reportingErrors.state} in ('resolved', 'ignored') then null else ${reportingErrors.resolvedAt} end`,
+                resolvedBy: sql `case when ${reportingErrors.state} in ('resolved', 'ignored') then null else ${reportingErrors.resolvedBy} end`,
+            },
+        })
+            // xmax = 0 is true exactly for a row this statement inserted fresh,
+            // false when it took the on-conflict-update path -- the standard,
+            // race-free way to tell the two apart from an upsert's own result.
+            .returning({ created: sql `(xmax = 0)` });
+        if (written[0]?.created)
+            return 'created';
+        return priorState === 'resolved' || priorState === 'ignored' ? 'reopened' : 'unchanged';
     });
 }
 /**
@@ -134,7 +170,7 @@ export function createCapture(o) {
     return function captureError(error, context = {}) {
         try {
             const kind = resolveKind(error, context.kind);
-            const secrets = heldSecrets(process.env);
+            const secrets = heldSecrets(process.env, o.redactEnvVars);
             const message = truncateEnd(redactText(messageOf(error, kind), secrets), LIMITS.message);
             const rawStack = stackOf(error);
             const stack = rawStack === null ? null : truncateEnd(redactText(rawStack, secrets), LIMITS.stack);
@@ -149,6 +185,7 @@ export function createCapture(o) {
             const tenantId = validTenant(context.tenantId);
             const requestId = context.requestId ?? null;
             const release = context.release ?? o.release ?? null;
+            const environment = o.environment ?? null;
             const at = o.now();
             o.event({
                 kind: eventKindFor(kind),
@@ -165,12 +202,33 @@ export function createCapture(o) {
                 stack,
                 runtime,
                 release,
+                environment,
                 tenantId,
                 requestId,
                 at,
             };
             try {
-                o.defer(() => upsertGroup(o.db, o.site, sample).catch((err) => {
+                o.defer(() => upsertGroup(o.db, o.site, sample)
+                    .then((outcome) => {
+                    if (outcome === 'unchanged' || !o.alert)
+                        return;
+                    try {
+                        o.alert({
+                            check: outcome === 'created' ? 'new_error' : 'error_reopened',
+                            message: `${outcome === 'created' ? 'new error' : 'error reopened'}: ${sample.kind}: ${sample.message}`.slice(0, 512),
+                            detail: {
+                                fingerprint: sample.fingerprint,
+                                kind: sample.kind,
+                                runtime: sample.runtime,
+                                site: o.site,
+                            },
+                        });
+                    }
+                    catch (err) {
+                        o.log.error({ err: describe(err) }, 'reporting: error alert threw');
+                    }
+                })
+                    .catch((err) => {
                     o.log.error({ err: describe(err), fingerprint: fp }, 'reporting: error group upsert failed');
                 }));
             }

package/dist/errors/reader.d.ts

@@ -3,8 +3,13 @@ import type { ReportingErrorRow } from '../tables.js';
 import type { Actor, Db, ErrorsPage, ErrorsPageOptions } from '../types.js';
 /**
  * Newest first, keyset-paged on `(last_seen_at, fingerprint)`, the table's
- * index. Every filter is an equality on an indexed column. No permission is
- * applied here: the host gates, and this returns rows as stored.
+ * index. Every filter is an equality on an indexed column, except `search`:
+ * a case-insensitive substring match on `message` or `stack`, for triaging
+ * an incident by grepping the group list rather than raw rows by hand (gap
+ * issue #8). Unindexed by design -- a trigram index would need the
+ * pg_trgm extension, an operational cost this triage tool does not carry
+ * for its scale. No permission is applied here: the host gates, and this
+ * returns rows as stored.
  */
 export declare function errorsPage(db: Db, opts?: ErrorsPageOptions): Promise<ErrorsPage>;
 /** One row by fingerprint, or null when it is unknown. */

package/dist/errors/reader.js

@@ -1,9 +1,18 @@
-import { and, desc, eq, lt, or, sql } from 'drizzle-orm';
+import { and, desc, eq, ilike, lt, or, sql } from 'drizzle-orm';
 import { reportingErrors } from '../tables.js';
+/** Postgres's default LIKE/ILIKE escape is backslash; escaping the pattern's own three special characters is what makes a search term match itself literally rather than as a wildcard pattern. */
+function likePattern(term) {
+    return `%${term.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+}
 /**
  * Newest first, keyset-paged on `(last_seen_at, fingerprint)`, the table's
- * index. Every filter is an equality on an indexed column. No permission is
- * applied here: the host gates, and this returns rows as stored.
+ * index. Every filter is an equality on an indexed column, except `search`:
+ * a case-insensitive substring match on `message` or `stack`, for triaging
+ * an incident by grepping the group list rather than raw rows by hand (gap
+ * issue #8). Unindexed by design -- a trigram index would need the
+ * pg_trgm extension, an operational cost this triage tool does not carry
+ * for its scale. No permission is applied here: the host gates, and this
+ * returns rows as stored.
  */
 export async function errorsPage(db, opts = {}) {
     const limit = Math.max(1, Math.min(opts.limit ?? 50, 200));
@@ -14,6 +23,15 @@ export async function errorsPage(db, opts = {}) {
         conditions.push(eq(reportingErrors.state, opts.state));
     if (opts.runtime)
         conditions.push(eq(reportingErrors.runtime, opts.runtime));
+    const search = opts.search?.trim().slice(0, 200);
+    if (search) {
+        const pattern = likePattern(search);
+        const clause = or(ilike(reportingErrors.message, pattern), ilike(reportingErrors.stack, pattern));
+        if (clause)
+            conditions.push(clause);
+    }
+    if (opts.environment)
+        conditions.push(eq(reportingErrors.environment, opts.environment));
     if (opts.after) {
         const { lastSeenAt, fingerprint } = opts.after;
         const keyset = or(lt(reportingErrors.lastSeenAt, lastSeenAt), and(eq(reportingErrors.lastSeenAt, lastSeenAt), lt(reportingErrors.fingerprint, fingerprint)));

package/dist/errors/redact.d.ts

@@ -28,8 +28,14 @@ export declare const REDACTED = "[redacted: wrapping key]";
  * The exact strings that must never appear in anything sent anywhere: both
  * environment variables in full, and each key's base64 half on its own, since
  * a parser that split on the colon would report only that part.
+ *
+ * `extraEnvVars` is how a host extends the list beyond the estate's own
+ * KEYSTORE_* convention (gap issue #7): each named variable is read the same
+ * way `KEYSTORE_KEK_PREVIOUS` is -- comma-separated values allowed, each
+ * trimmed -- so a host's own rotation scheme is covered the same way the
+ * estate's is, with no new format to learn.
  */
-export declare function heldSecrets(env: Readonly<Record<string, string | undefined>>): string[];
+export declare function heldSecrets(env: Readonly<Record<string, string | undefined>>, extraEnvVars?: readonly string[]): string[];
 /**
  * The string case alone: a captured `message` and `stack` are strings before
  * they are anything else, so the capture path scrubs them directly rather

package/dist/errors/redact.js

@@ -28,9 +28,19 @@ export const REDACTED = '[redacted: wrapping key]';
  * The exact strings that must never appear in anything sent anywhere: both
  * environment variables in full, and each key's base64 half on its own, since
  * a parser that split on the colon would report only that part.
+ *
+ * `extraEnvVars` is how a host extends the list beyond the estate's own
+ * KEYSTORE_* convention (gap issue #7): each named variable is read the same
+ * way `KEYSTORE_KEK_PREVIOUS` is -- comma-separated values allowed, each
+ * trimmed -- so a host's own rotation scheme is covered the same way the
+ * estate's is, with no new format to learn.
  */
-export function heldSecrets(env) {
-    const specs = [env.KEYSTORE_KEK ?? '', ...(env.KEYSTORE_KEK_PREVIOUS ?? '').split(',')]
+export function heldSecrets(env, extraEnvVars = []) {
+    const specs = [
+        env.KEYSTORE_KEK ?? '',
+        ...(env.KEYSTORE_KEK_PREVIOUS ?? '').split(','),
+        ...extraEnvVars.flatMap((name) => (env[name] ?? '').split(',')),
+    ]
         .map((spec) => spec.trim())
         .filter((spec) => spec.length > 0);
     const secrets = new Set();

package/dist/fake/index.d.ts

@@ -17,4 +17,6 @@ export interface FakeReporting extends Reporting {
 export declare function createFakeReporting(opts?: {
     site?: string;
     log?: Logger;
+    redactEnvVars?: readonly string[];
+    environment?: string | null;
 }): FakeReporting;

package/dist/fake/index.js

@@ -6,11 +6,13 @@ import { tables } from '../tables.js';
 const silent = { info() { }, warn() { }, error() { } };
 export function createFakeReporting(opts = {}) {
     const site = opts.site ?? 'test';
+    const environment = opts.environment ?? null;
     const log = opts.log ?? silent;
     const rows = [];
     const alerts = [];
     const tracked = [];
     let settings = { ...DEFAULT_SETTINGS };
+    const tenantRetention = new Map();
     let id = 0;
     // No group table to fake, so the upsert never runs (`defer` is a no-op);
     // the timeline row through `fake.event` is what a host's test asserts on.
@@ -21,6 +23,7 @@ export function createFakeReporting(opts = {}) {
         now: () => new Date(),
         defer: () => { },
         event: (input) => fake.event(input),
+        redactEnvVars: opts.redactEnvVars,
     });
     const fake = {
         site,
@@ -39,6 +42,7 @@ export function createFakeReporting(opts = {}) {
                 kind: v.kind,
                 kindNs: v.kind.split('.')[0] ?? '',
                 site,
+                environment,
                 tenantId: v.tenantId ?? null,
                 actorClass: v.actor?.class ?? null,
                 actorId: v.actor?.id ?? null,
@@ -70,6 +74,8 @@ export function createFakeReporting(opts = {}) {
                     list = list.filter((r) => r.site === o.site);
                 if (o.requestId)
                     list = list.filter((r) => r.requestId === o.requestId);
+                if (o.environment)
+                    list = list.filter((r) => r.environment === o.environment);
                 if (o.after) {
                     const { occurredAt, id: afterId } = o.after;
                     list = list.filter((r) => r.occurredAt.getTime() < occurredAt.getTime() ||
@@ -102,6 +108,28 @@ export function createFakeReporting(opts = {}) {
                 return { before, after: settings, by, changed };
             },
         },
+        tenantSettings: {
+            async get(tenantId) {
+                const out = {};
+                for (const key of ['events.retention_days', 'analytics.retention_days']) {
+                    const value = tenantRetention.get(`${tenantId}:${key}`);
+                    if (value !== undefined)
+                        out[key] = value;
+                }
+                return out;
+            },
+            async set(tenantId, key, days) {
+                const mapKey = `${tenantId}:${key}`;
+                if (days === null) {
+                    tenantRetention.delete(mapKey);
+                    return;
+                }
+                if (!Number.isInteger(days) || days < RETENTION_BOUNDS.min || days > RETENTION_BOUNDS.max) {
+                    throw new Error(`reporting.tenantSettings: ${key} out of bounds`);
+                }
+                tenantRetention.set(mapKey, days);
+            },
+        },
         analytics: {
             async track(input) {
                 tracked.push({ ...input, site });
@@ -121,6 +149,7 @@ export function createFakeReporting(opts = {}) {
             rows.length = 0;
             alerts.length = 0;
             settings = { ...DEFAULT_SETTINGS };
+            tenantRetention.clear();
             id = 0;
         },
     };

package/dist/index.js

@@ -4,8 +4,8 @@ import { ANALYTICS_NAME_PATTERN, normalisePath, propsSchema } from './analytics/
 import { insertAnalytics } from './analytics/write.js';
 import { createCapture } from './errors/capture.js';
 import { eventsPage } from './reader.js';
-import { siteSchema } from './schema.js';
-import { getSettings, setSettings } from './settings.js';
+import { environmentSchema, siteSchema } from './schema.js';
+import { getSettings, getTenantRetention, setSettings, setTenantRetention } from './settings.js';
 import { tables } from './tables.js';
 import { Writer, describe } from './writer.js';
 export * from './schema.js';
@@ -28,6 +28,7 @@ function modeFromEnv() {
  */
 export function createReporting(options) {
     const site = siteSchema.parse(options.site);
+    const environment = options.environment != null ? environmentSchema.parse(options.environment) : null;
     const now = options.now ?? (() => new Date());
     const mode = options.mode ?? modeFromEnv();
     const defer = options.defer ??
@@ -38,6 +39,7 @@ export function createReporting(options) {
         db: options.db,
         log: options.log,
         site,
+        environment,
         mode,
         now,
         defer,
@@ -45,16 +47,35 @@ export function createReporting(options) {
         batchSize: options.batchSize ?? 500,
         flushEveryMs: options.flushEveryMs ?? 1000,
     });
+    // One alerting path, shared by `reporting.alert()` and a new-or-reopened
+    // capture (errors/capture.ts's `alert` option): an `alert.<check>` row,
+    // already indexed and pruned the same as everything else on the
+    // timeline, then the host's own hook -- never a vendor's. A throw from
+    // that hook is the host's, not this package's, to fail on.
+    function fireAlert(finding) {
+        writer.event(alertRow(finding));
+        if (!options.onAlert)
+            return;
+        try {
+            options.onAlert(finding);
+        }
+        catch (error) {
+            options.log.error({ err: describe(error) }, 'reporting: onAlert threw');
+        }
+    }
     // Same db, log, defer, now and site as the writer: one instance, one
     // upsert path, no second connection or timer to keep in sync.
     const capture = createCapture({
         db: options.db,
         log: options.log,
         site,
+        environment,
         now,
         defer,
         event: (input) => writer.event(input),
         release: process.env.REPORTING_RELEASE ?? null,
+        alert: fireAlert,
+        redactEnvVars: options.redactEnvVars,
     });
     const reporting = {
         site,
@@ -62,17 +83,7 @@ export function createReporting(options) {
         tables,
         event: (input) => writer.event(input),
         captureError: (error, context) => capture(error, context),
-        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');
-            }
-        },
+        alert: fireAlert,
         flush: (opts) => writer.flush(opts),
         events: { page: (opts) => eventsPage(options.db, opts) },
         settings: {
@@ -95,6 +106,10 @@ export function createReporting(options) {
                 return change;
             },
         },
+        tenantSettings: {
+            get: (tenantId) => getTenantRetention(options.db, tenantId),
+            set: (tenantId, key, days, by) => setTenantRetention(options.db, tenantId, key, days, by),
+        },
         analytics: {
             async track(input) {
                 try {

package/dist/migrations/0004_environment.sql

@@ -0,0 +1,36 @@
+-- @wtfalch/reporting 0.4.0: an environment dimension on error and event
+-- rows. Mirrors src/tables.ts.
+--
+-- Every factory app deploys prod + stage + one preview per PR, and site is
+-- the app's identity, not its deploy target -- so without a second column,
+-- preview noise and production issues land in the same rows with nothing to
+-- tell them apart (gap issue #6). `environment` is a slug the host stamps
+-- once, the way it already stamps `release`, never claimed per event.
+--
+-- Nullable and not fixed to an enum: unlike `level` or `runtime`, the estate
+-- does not fix the set of environments a host may name, so the CHECK only
+-- keeps it slug-shaped. Every statement is idempotent; the file is applied
+-- by the host's own migrate script after `reporting-migrations` copies it in
+-- as the next number.
+--
+-- `not valid` then a separate `validate constraint`, unlike
+-- reporting_settings_key_check's plain add in 0002: that table is a handful
+-- of rows, reporting_events and reporting_errors are the two tables this
+-- package batches deletes against and tunes autovacuum for, so a CHECK added
+-- the plain way would hold an ACCESS EXCLUSIVE lock for as long as it takes
+-- to scan one of them. `not valid` takes that lock only for the catalog
+-- change; `validate constraint` then scans under SHARE UPDATE EXCLUSIVE,
+-- which blocks other DDL but not the reads and writes this package makes
+-- every request.
+
+alter table reporting_events add column if not exists environment text;
+alter table reporting_events drop constraint if exists reporting_events_environment_check;
+alter table reporting_events add constraint reporting_events_environment_check
+  check (environment is null or environment ~ '^[a-z][a-z0-9_-]{0,31}$') not valid;
+alter table reporting_events validate constraint reporting_events_environment_check;
+
+alter table reporting_errors add column if not exists environment text;
+alter table reporting_errors drop constraint if exists reporting_errors_environment_check;
+alter table reporting_errors add constraint reporting_errors_environment_check
+  check (environment is null or environment ~ '^[a-z][a-z0-9_-]{0,31}$') not valid;
+alter table reporting_errors validate constraint reporting_errors_environment_check;

package/dist/migrations/0005_analytics_session_index.sql

@@ -0,0 +1,14 @@
+-- @wtfalch/reporting 0.4.0: a session-scoped index on reporting_analytics.
+--
+-- Debugging a tenant's user-reported bug means "everything this session
+-- did," and every row already carries a per-tab session id -- the lightest
+-- privacy-consistent equivalent of session replay (gap issue #9;
+-- `analyticsRecent` gained a `sessionId` filter). Without an index shaped
+-- for it, that filter is a sequential scan of the whole raw analytics
+-- window on a busy site. Same shape as `reporting_analytics_tenant_time_idx`
+-- (0002_analytics.sql): the filter column, then the reader's own order.
+-- Idempotent, like every statement in this package's migrations.
+
+create index if not exists reporting_analytics_session_time_idx
+  on reporting_analytics (session_id, occurred_at desc, id desc)
+  where session_id is not null;