@wtfalch/reporting 0.2.1 → 0.3.0

package/dist/migrations/0003_errors.sql

@@ -0,0 +1,118 @@
+-- @wtfalch/reporting 0.3.0: the error group table. Mirrors src/tables.ts.
+--
+-- One row per fingerprint (docs/plans/errors.md): an uncaught exception's
+-- stack groups repeats into a count and a last-seen time instead of a
+-- firehose of identical reporting_events rows. 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 table and no revokes take effect, which the
+-- package README says plainly.
+
+create table if not exists reporting_errors (
+  fingerprint     text primary key,
+  site            text not null,
+  kind            text not null,
+  message         text not null,
+  stack           text,
+  runtime         text not null,
+  release         text,
+  first_seen_at   timestamptz not null,
+  last_seen_at    timestamptz not null,
+  occurrences     bigint not null default 1,
+  state           text not null default 'open',
+  resolved_at     timestamptz,
+  resolved_by     text,
+  tenant_id       uuid,
+  request_id      text,
+  -- The digest that groups occurrences (docs/plans/errors.md: sha256 of the
+  -- kind and the top normalised frames, truncated to 32 hex). Lower case
+  -- only: two casings of the same digest must not become two groups.
+  constraint reporting_errors_fingerprint_check check (fingerprint ~ '^[0-9a-f]{32}$'),
+  constraint reporting_errors_site_check check (site ~ '^[a-z][a-z0-9-]{0,63}$'),
+  constraint reporting_errors_message_check check (length(message) between 1 and 512),
+  -- Redacted before it is queued (src/schema.ts); this bound is a second net
+  -- against a pathological stack, not the redaction itself.
+  constraint reporting_errors_stack_check check (stack is null or length(stack) <= 16384),
+  constraint reporting_errors_runtime_check check (runtime in ('server', 'edge', 'browser')),
+  constraint reporting_errors_state_check check (state in ('open', 'resolved', 'ignored')),
+  -- The row exists because one occurrence created it; it can never describe
+  -- zero.
+  constraint reporting_errors_occurrences_check check (occurrences > 0),
+  -- The upsert only ever moves this forward. If it moved backward, the count
+  -- and the window it claims to describe would disagree.
+  constraint reporting_errors_seen_check check (last_seen_at >= first_seen_at),
+  -- Same pairing as reporting_events_actor_pair_check: who resolved it is
+  -- meaningless without when, and vice versa.
+  constraint reporting_errors_resolved_pair_check check ((resolved_at is null) = (resolved_by is null))
+);
+
+comment on column reporting_errors.tenant_id is
+  'From the most recent sample. No foreign key and no cascade, same as reporting_events.actor_id: the group outlives the request, and erasure must not delete the count.';
+comment on column reporting_errors.request_id is
+  'From the most recent sample; overwritten on every occurrence, not a history.';
+
+-- The default operator view: this site, still open, newest first. A partial
+-- index because most errors end up resolved and should not cost this one.
+create index if not exists reporting_errors_site_open_idx
+  on reporting_errors (site, last_seen_at desc) where state = 'open';
+-- The same page's state filter, switched to resolved or ignored.
+create index if not exists reporting_errors_state_idx
+  on reporting_errors (state, last_seen_at desc);
+
+-- The one way rows leave reporting_errors on a timer. Unlike
+-- reporting_prune_events, eligibility is state AND age, not age alone: only
+-- 'resolved' or 'ignored' rows past the window are candidates. A row still
+-- 'open' is NEVER a candidate here, no matter how old — an unresolved error
+-- vanishing on a timer is the failure mode that makes an error tracker
+-- untrustworthy, so the only way one leaves this table is an operator
+-- resolving or ignoring it first, and it ageing out after. Same clamp and
+-- batching shape as reporting_prune_events: the window is clamped to between
+-- seven and four hundred days inside the function, and the batch is capped
+-- at 5,000 so no statement holds a lock for long.
+create or replace function reporting_prune_errors(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 fingerprint from reporting_errors
+     where state in ('resolved', 'ignored')
+       and last_seen_at < now() - w
+     order by last_seen_at, fingerprint
+     limit b
+  )
+  delete from reporting_errors e using victims v where e.fingerprint = v.fingerprint;
+  get diagnostics n = row_count;
+  return n;
+end
+$$;
+revoke all on function reporting_prune_errors(interval, integer) from public;
+
+comment on function reporting_prune_errors(interval, integer) is
+  'Deletes only resolved or ignored rows past the retention window. An open row is never a candidate, regardless of age: an unresolved error disappearing on a timer is the one failure mode that makes an error tracker untrustworthy. It leaves this table only after an operator resolves or ignores it, and then ages out.';
+
+-- The runtime role keeps SELECT, INSERT and UPDATE: the capture path upserts
+-- on repeat occurrences and an operator moves state through this table.
+-- Nothing that deletes, the same as reporting_tasks and reporting_settings;
+-- reporting_prune_errors runs as the function owner, not the runtime role,
+-- so the grant below is execute only, same shape as reporting_prune_events.
+do $$
+declare
+  rt text := current_database() || '_rt';
+begin
+  if exists (select 1 from pg_roles where rolname = rt) then
+    execute format('revoke delete, truncate on reporting_errors from %I', rt);
+    execute format('grant execute on function reporting_prune_errors(interval, integer) to %I', rt);
+  end if;
+end
+$$;

package/dist/next/client-errors.d.ts

@@ -0,0 +1,46 @@
+import type { Reporting } from '../types.js';
+/**
+ * The public ingest route for browser-reported errors
+ * (docs/plans/errors.md, "Surface"): modelled exactly on the analytics
+ * collector (`../analytics/collector.js`) — always 204, the same origin
+ * allowance, the same body-size cap — because that ingest problem is
+ * already solved there and a second set of limits would be a second set to
+ * get wrong.
+ *
+ * Two things differ from the analytics collector, both because a
+ * `Reporting` instance is already bound to one site:
+ * 1. There is no `sites` map to route a foreign origin's claim to a
+ *    different site's table — `origins` below is a flat allow-list, and a
+ *    batch claiming any other site is dropped, same-origin or not.
+ * 2. A capture goes through `reporting.captureError`, not a direct insert,
+ *    so there is no `now`/`db` to take here: capture.ts already has its own.
+ */
+export interface ClientErrorCollectorOptions {
+    readonly reporting: Reporting;
+    /** Foreign origins allowed to post errors for this site, beside same-origin. */
+    readonly origins?: readonly string[];
+    /**
+     * The signed-in person, from the host's session, for a same-origin
+     * request only — a foreign origin never reads it (addendum A5's rule,
+     * same as the analytics collector's `getUserId`).
+     */
+    readonly getUserId?: (request: Request) => Promise<string | null>;
+    /**
+     * The host's tenant lookup for that person. Unlike the analytics
+     * collector's `tenantFor`, there is no pathname to hand over: an error
+     * batch names no single route the way a page view does.
+     */
+    readonly tenantFor?: (userId: string) => Promise<string | null>;
+    /**
+     * Captures allowed per minute per client address. An unauthenticated route
+     * that writes rows needs a ceiling that does not depend on the caller being
+     * our own beacon: the browser's 5-distinct/20-total cap is one line of
+     * client code away from being ignored, and `reporting_errors` never prunes
+     * an open row. Lower than the analytics default because an error is rarer
+     * than a page view by design; a client hitting this is already broken.
+     */
+    readonly ratePerMinute?: number;
+}
+export declare function createClientErrorCollector(options: ClientErrorCollectorOptions): {
+    handle(request: Request): Promise<Response>;
+};

package/dist/next/client-errors.js

@@ -0,0 +1,165 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { ANALYTICS_LIMITS } from '../analytics/schema.js';
+import { Buckets } from '../ingest-limit.js';
+import { SITE_PATTERN } from '../schema.js';
+/** At most this many entries of a batch are ever captured; the rest are dropped silently. */
+const BATCH_MAX = 10;
+/**
+ * Not `z.strictObject`, unlike the analytics beacon schema: a client that
+ * adds `tenantId`, `userId` or `requestId` here must have that field
+ * silently stripped, not the whole batch refused. `handle()` below never
+ * reads such a field either way — identity and the request id come only
+ * from this request itself (`getUserId`/`tenantFor`, and `cf-ray`/a fresh
+ * uuid), never from the body. The browser is not a trusted caller.
+ */
+const entrySchema = z.object({
+    kind: z.string().min(1),
+    message: z.string().min(1),
+    stack: z.string().nullish(),
+    release: z.string().nullish(),
+});
+const batchSchema = z.object({
+    site: z.string().regex(SITE_PATTERN),
+    errors: z.array(entrySchema).min(1),
+});
+const NO_CONTENT = () => new Response(null, { status: 204 });
+/**
+ * The client's address as the tunnel presents it. `cf-connecting-ip` first
+ * because every request to this estate arrives through Cloudflare, then the
+ * first hop of `x-forwarded-for`; a header a client sets itself is no worse
+ * here than no key at all, since the bucket only ever costs that same client.
+ */
+function clientAddress(request) {
+    const cf = request.headers.get('cf-connecting-ip');
+    if (cf)
+        return cf.trim();
+    const xff = request.headers.get('x-forwarded-for');
+    return xff ? (xff.split(',')[0] ?? '').trim() || null : null;
+}
+/** `<16 hex>-<colo>`, as Cloudflare emits it — the same pattern `./index.ts` uses; kept here too, rather than imported, to avoid a circular import between the two files. */
+const RAY_PATTERN = /^[0-9a-f]{16}-[A-Z0-9]{3,6}$/;
+function requestIdOf(request) {
+    const ray = request.headers.get('cf-ray');
+    return ray && RAY_PATTERN.test(ray) ? ray : randomUUID();
+}
+/**
+ * Same shape as the collector's own `originFor` (`../analytics/collector.js`,
+ * private there): duplicated rather than exported, per this task's scope —
+ * it is ~10 lines and the two callers now diverge (no `sites` map here).
+ */
+function originOf(request) {
+    const origin = request.headers.get('origin');
+    const host = request.headers.get('x-forwarded-host') ?? request.headers.get('host');
+    if (!origin)
+        return host ? { kind: 'same', origin: `https://${host}` } : null;
+    let originHost;
+    try {
+        originHost = new URL(origin).host;
+    }
+    catch {
+        return null;
+    }
+    return { kind: originHost === host ? 'same' : 'foreign', origin };
+}
+function corsFor(response, origin) {
+    response.headers.set('access-control-allow-origin', origin);
+    response.headers.set('vary', 'origin');
+    return response;
+}
+/**
+ * An `Error` carrying exactly the client's own message and stack, so
+ * `captureError`'s existing redaction and fingerprinting run unchanged on
+ * it (errors/capture.ts is not this task's to edit). The class name is
+ * never read from this: `context.kind` below overrides it with the
+ * client's own `kind`.
+ */
+function toCapturable(entry) {
+    const err = new Error(entry.message);
+    err.stack = entry.stack ?? undefined;
+    return err;
+}
+export function createClientErrorCollector(options) {
+    const { reporting } = options;
+    const buckets = new Buckets(options.ratePerMinute ?? 60, () => new Date());
+    async function handle(request) {
+        if (request.method !== 'POST')
+            return NO_CONTENT();
+        const where = originOf(request);
+        if (!where)
+            return NO_CONTENT();
+        if (where.kind === 'foreign' && !(options.origins ?? []).includes(where.origin)) {
+            return NO_CONTENT();
+        }
+        const length = Number(request.headers.get('content-length') ?? '0');
+        if (length > ANALYTICS_LIMITS.bodyBytes)
+            return NO_CONTENT();
+        let text;
+        try {
+            text = await request.text();
+        }
+        catch {
+            return NO_CONTENT();
+        }
+        if (text.length > ANALYTICS_LIMITS.bodyBytes)
+            return NO_CONTENT();
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            return NO_CONTENT();
+        }
+        const parsed = batchSchema.safeParse(json);
+        if (!parsed.success) {
+            reporting.log.info({ issues: parsed.error.issues.length }, 'reporting: client error batch refused');
+            return NO_CONTENT();
+        }
+        if (parsed.data.site !== reporting.site)
+            return NO_CONTENT();
+        // After parsing, so the cost of a refused body is not charged to the
+        // address, and before any capture, so the bucket bounds what is written
+        // rather than what was asked. Keyed on the address alone: a visitor id
+        // would be the client's own claim, and this is the route that exists
+        // because the client is not trusted.
+        const entries = parsed.data.errors.slice(0, BATCH_MAX);
+        if (!buckets.take(`ip:${clientAddress(request) ?? 'none'}`, entries.length)) {
+            return NO_CONTENT();
+        }
+        // Identity is the session's, same-origin only, and never the body's
+        // (the entry schema above has no tenantId/userId field to begin with).
+        let userId = null;
+        if (where.kind === 'same' && options.getUserId) {
+            try {
+                userId = await options.getUserId(request);
+            }
+            catch (error) {
+                reporting.log.warn({ err: error instanceof Error ? error.message : String(error) }, 'reporting: client error getUserId failed; capturing without a tenant');
+            }
+        }
+        let tenantId = null;
+        if (userId && options.tenantFor) {
+            try {
+                tenantId = await options.tenantFor(userId);
+            }
+            catch {
+                tenantId = null;
+            }
+        }
+        // This request's own id, cf-ray or a fresh uuid — never the body's;
+        // same rule `errorHandler` (./index.ts) follows for a server capture.
+        const requestId = requestIdOf(request);
+        for (const entry of entries) {
+            reporting.captureError(toCapturable(entry), {
+                kind: entry.kind,
+                runtime: 'browser',
+                release: entry.release ?? null,
+                tenantId,
+                requestId,
+            });
+        }
+        const response = NO_CONTENT();
+        return where.kind === 'foreign' ? corsFor(response, where.origin) : response;
+    }
+    return { handle };
+}

package/dist/next/index.d.ts

@@ -1,6 +1,7 @@
 import { type CollectorOptions } from '../analytics/collector.js';
 import { deviceOf } from '../analytics/schema.js';
 import type { Reporting } from '../types.js';
+import { type ClientErrorCollectorOptions } from './client-errors.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.
@@ -49,6 +50,44 @@ export declare function registerShutdownFlush(reporting: Reporting, opts?: {
 export declare function collectHandler(options: Omit<CollectorOptions, 'log' | 'site'> & {
     readonly reporting: Reporting;
 }): (request: Request) => Promise<Response>;
+/**
+ * `onRequestError` from Next's instrumentation hook
+ * (`next/dist/server/instrumentation/types.d.ts`, `InstrumentationOnRequestError`).
+ * Declared locally: no public `next` subpath exports the type, and this is
+ * the exact shape the compiled server calls it with
+ * (`base-server.js`'s `instrumentationOnRequestError`).
+ */
+export type NextOnRequestError = (error: unknown, request: Readonly<{
+    path: string;
+    method: string;
+    headers: NodeJS.Dict<string | string[]>;
+}>, context: Readonly<{
+    routerKind: string;
+    routePath: string;
+    routeType: string;
+}>) => void | Promise<void>;
+/**
+ * Binds `reporting.captureError` to Next's `onRequestError`
+ * (docs/plans/errors.md, "Surface"). `runtime` is `edge` exactly when
+ * `NEXT_RUNTIME` says so — the same signal Next's own compiled server
+ * branches on (e.g. `dist/server/app-render/action-handler.js`), because
+ * the error context Next hands this hook carries no runtime field of its
+ * own. `requestId` is derived the same way `requestContext()` derives one:
+ * Cloudflare's `cf-ray`, else a fresh uuid.
+ *
+ * Never throws: Next calls this while already handling an error, and a
+ * reporter that throws back is the one failure worse than not reporting —
+ * the same rule `captureError` itself already keeps (errors/capture.ts).
+ * This catch is defence in depth for a `reporting` that violates it.
+ */
+export declare function errorHandler(reporting: Reporting): NextOnRequestError;
+/**
+ * The public ingest route for browser-reported errors: mount as `POST`
+ * (docs/plans/errors.md, "Surface"; `// authz: public`). See
+ * `createClientErrorCollector` (./client-errors.js) for the caps, the
+ * origin allowance and why identity is never the body's.
+ */
+export declare function clientErrorHandler(options: ClientErrorCollectorOptions): (request: Request) => Promise<Response>;
 /** Device and country for a server-side `track`, from the request's headers; nothing else is kept. */
 export declare function trackContext(): Promise<{
     device: ReturnType<typeof deviceOf>;

package/dist/next/index.js

@@ -4,6 +4,7 @@ import { unstable_rethrow } from 'next/navigation';
 import { after, connection } from 'next/server';
 import { createCollector } from '../analytics/collector.js';
 import { countryOf, deviceOf } from '../analytics/schema.js';
+import { createClientErrorCollector } from './client-errors.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.
@@ -84,6 +85,53 @@ export function collectHandler(options) {
     const collector = createCollector({ ...rest, log: reporting.log, site: reporting.site });
     return (request) => collector.handle(request);
 }
+function headerValue(dict, name) {
+    const lower = name.toLowerCase();
+    for (const key of Object.keys(dict)) {
+        if (key.toLowerCase() !== lower)
+            continue;
+        const value = dict[key];
+        return Array.isArray(value) ? (value[0] ?? null) : (value ?? null);
+    }
+    return null;
+}
+/**
+ * Binds `reporting.captureError` to Next's `onRequestError`
+ * (docs/plans/errors.md, "Surface"). `runtime` is `edge` exactly when
+ * `NEXT_RUNTIME` says so — the same signal Next's own compiled server
+ * branches on (e.g. `dist/server/app-render/action-handler.js`), because
+ * the error context Next hands this hook carries no runtime field of its
+ * own. `requestId` is derived the same way `requestContext()` derives one:
+ * Cloudflare's `cf-ray`, else a fresh uuid.
+ *
+ * Never throws: Next calls this while already handling an error, and a
+ * reporter that throws back is the one failure worse than not reporting —
+ * the same rule `captureError` itself already keeps (errors/capture.ts).
+ * This catch is defence in depth for a `reporting` that violates it.
+ */
+export function errorHandler(reporting) {
+    return (error, request) => {
+        try {
+            const runtime = process.env.NEXT_RUNTIME === 'edge' ? 'edge' : 'server';
+            const ray = headerValue(request.headers, 'cf-ray');
+            const requestId = ray && RAY_PATTERN.test(ray) ? ray : randomUUID();
+            reporting.captureError(error, { runtime, requestId });
+        }
+        catch {
+            // See the doc comment above: this must never throw back into Next.
+        }
+    };
+}
+/**
+ * The public ingest route for browser-reported errors: mount as `POST`
+ * (docs/plans/errors.md, "Surface"; `// authz: public`). See
+ * `createClientErrorCollector` (./client-errors.js) for the caps, the
+ * origin allowance and why identity is never the body's.
+ */
+export function clientErrorHandler(options) {
+    const collector = createClientErrorCollector(options);
+    return (request) => collector.handle(request);
+}
 /** Device and country for a server-side `track`, from the request's headers; nothing else is kept. */
 export async function trackContext() {
     try {

package/dist/react/errors.d.ts

@@ -0,0 +1,12 @@
+import type { ReportingErrorRow } from '../tables.js';
+/**
+ * The operator's error list: a plain table over the rows `errorsPage()`
+ * already returned, newest last-seen first — the same props-in split as
+ * `charts.tsx`, no fetching and no client state. The stack and the rest of
+ * one group's detail belong in a detail view, not here; this table only ever
+ * renders the group's summary columns.
+ */
+export declare function ErrorsTable(props: {
+    readonly rows: readonly ReportingErrorRow[];
+    readonly label?: string;
+}): import("react").JSX.Element;

package/dist/react/errors.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The operator's error list: a plain table over the rows `errorsPage()`
+ * already returned, newest last-seen first — the same props-in split as
+ * `charts.tsx`, no fetching and no client state. The stack and the rest of
+ * one group's detail belong in a detail view, not here; this table only ever
+ * renders the group's summary columns.
+ */
+export function ErrorsTable(props) {
+    if (props.rows.length === 0) {
+        return _jsx("p", { "data-reporting-errors-empty": "", children: "No errors captured. All clear." });
+    }
+    return (_jsxs("table", { "data-reporting-errors": "", "aria-label": props.label ?? 'Errors, newest last seen first', children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Kind" }), _jsx("th", { scope: "col", children: "Message" }), _jsx("th", { scope: "col", children: "Occurrences" }), _jsx("th", { scope: "col", children: "First seen" }), _jsx("th", { scope: "col", children: "Last seen" }), _jsx("th", { scope: "col", children: "Runtime" }), _jsx("th", { scope: "col", children: "Release" }), _jsx("th", { scope: "col", children: "State" })] }) }), _jsx("tbody", { children: props.rows.map((row) => (_jsxs("tr", { children: [_jsx("td", { children: row.kind }), _jsx("td", { style: { maxWidth: '32rem', overflowWrap: 'anywhere', wordBreak: 'break-word' }, title: row.message, children: row.message }), _jsx("td", { style: { fontVariantNumeric: 'tabular-nums' }, children: String(row.occurrences) }), _jsx("td", { children: formatTimestamp(row.firstSeenAt) }), _jsx("td", { children: formatTimestamp(row.lastSeenAt) }), _jsx("td", { children: row.runtime }), _jsx("td", { children: row.release ?? '—' }), _jsx("td", { children: row.state })] }, row.fingerprint))) })] }));
+}
+function formatTimestamp(value) {
+    return `${value.toISOString().slice(0, 19).replace('T', ' ')} UTC`;
+}

package/dist/schema.d.ts

@@ -9,9 +9,15 @@ export declare const LEVELS: readonly ["info", "warn", "error", "alert"];
 export type Level = (typeof LEVELS)[number];
 export declare const ACTOR_CLASSES: readonly ["human", "api_key", "agent", "service"];
 export type ActorClass = (typeof ACTOR_CLASSES)[number];
+export declare const ERROR_STATES: readonly ["open", "resolved", "ignored"];
+export type ErrorState = (typeof ERROR_STATES)[number];
+export declare const ERROR_RUNTIMES: readonly ["server", "edge", "browser"];
+export type ErrorRuntime = (typeof ERROR_RUNTIMES)[number];
 /** `namespace.name`: one dot, lower case, digits and underscores. */
 export declare const KIND_PATTERN: RegExp;
 export declare const SITE_PATTERN: RegExp;
+/** sha256 of the kind and the top normalised frames, truncated to 32 hex, lower case. */
+export declare const FINGERPRINT_PATTERN: RegExp;
 /**
  * Keys a `data` object may not carry, because each names a person or a
  * secret. A guardrail against the accidental case, not proof of absence: a
@@ -27,6 +33,7 @@ export declare const LIMITS: {
     readonly targetId: 256;
     readonly dataBytes: 16384;
     readonly site: 64;
+    readonly stack: 16384;
 };
 /** Flat, bounded, banned keys refused, numbers finite. */
 export declare const flatDataSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
@@ -83,3 +90,4 @@ export declare const eventInputSchema: z.ZodObject<{
 export type EventInput = z.input<typeof eventInputSchema>;
 export type ValidEvent = z.output<typeof eventInputSchema>;
 export declare const siteSchema: z.ZodString;
+export declare const fingerprintSchema: z.ZodString;

package/dist/schema.js

@@ -7,9 +7,13 @@ import { z } from 'zod';
  */
 export const LEVELS = ['info', 'warn', 'error', 'alert'];
 export const ACTOR_CLASSES = ['human', 'api_key', 'agent', 'service'];
+export const ERROR_STATES = ['open', 'resolved', 'ignored'];
+export const ERROR_RUNTIMES = ['server', 'edge', 'browser'];
 /** `namespace.name`: one dot, lower case, digits and underscores. */
 export const KIND_PATTERN = /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/;
 export const SITE_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+/** sha256 of the kind and the top normalised frames, truncated to 32 hex, lower case. */
+export const FINGERPRINT_PATTERN = /^[0-9a-f]{32}$/;
 /**
  * Keys a `data` object may not carry, because each names a person or a
  * secret. A guardrail against the accidental case, not proof of absence: a
@@ -34,6 +38,7 @@ export const LIMITS = {
     targetId: 256,
     dataBytes: 16384,
     site: 64,
+    stack: 16384,
 };
 const scalar = z.union([z.string(), z.number(), z.boolean(), z.null()]);
 /** Flat, bounded, banned keys refused, numbers finite. */
@@ -85,3 +90,6 @@ export const eventInputSchema = z.strictObject({
 export const siteSchema = z
     .string()
     .regex(SITE_PATTERN, 'a site id is lower case, digits and dashes');
+export const fingerprintSchema = z
+    .string()
+    .regex(FINGERPRINT_PATTERN, 'a fingerprint is 32 lower-case hex characters');