cursedbelt-server 1.0.0

package/dist/server/incidents/routes.js

@@ -0,0 +1,202 @@
+import { assertNoContent } from "./store";
+const noStore = { "cache-control": "no-store" };
+/** Long enough for three real sentences, short enough that nobody pastes a log in. */
+const MAX_FIELD = 600;
+const MAX_REPORTS = 100;
+const str = (v, fallback = "") => typeof v === "string" ? v.slice(0, MAX_FIELD) : fallback;
+/** Parse one posted report defensively. Throws with a usable message. */
+function parseReport(raw) {
+    if (!raw || typeof raw !== "object")
+        throw new Error("each report must be an object");
+    const r = raw;
+    const severity = r.severity === "blocking" ? "blocking" : "warning";
+    const report = {
+        source: str(r.source),
+        kind: str(r.kind),
+        subject: str(r.subject),
+        severity,
+        title: str(r.title),
+        whatBroke: str(r.whatBroke),
+        whatItBlocks: str(r.whatItBlocks),
+        whatToDo: str(r.whatToDo),
+        ...(r.facts && typeof r.facts === "object"
+            ? { facts: r.facts }
+            : {}),
+    };
+    for (const field of ["source", "kind", "subject", "title", "whatBroke"]) {
+        if (!report[field])
+            throw new Error(`report is missing "${field}"`);
+    }
+    // The privacy gate, applied to off-box input before it can reach a phone.
+    assertNoContent(report);
+    return report;
+}
+/**
+ * The OWNER's surface: the list, the acks, the health strip, the manual sweep,
+ * the channel test. Mount it INSIDE the app's session gate.
+ */
+export function mountIncidentOwnerRoutes(app, options, basePath = "/incidents") {
+    const { store } = options;
+    const guard = async (c) => (await options.authorize(c)) ? null : c.json({ error: "forbidden" }, 403);
+    app.get(`${basePath}`, async (c) => {
+        const denied = await guard(c);
+        if (denied)
+            return denied;
+        const state = c.req.query("state");
+        const incidents = store.list({
+            state: state === "all"
+                ? undefined
+                : state === "resolved"
+                    ? "resolved"
+                    : state === "open"
+                        ? "open"
+                        : "active",
+            limit: Number(c.req.query("limit") ?? 200),
+        });
+        return c.json({ incidents }, 200, noStore);
+    });
+    app.post(`${basePath}/:fingerprint/ack`, async (c) => {
+        const denied = await guard(c);
+        if (denied)
+            return denied;
+        const ok = store.acknowledge(decodeURIComponent(c.req.param("fingerprint")));
+        return c.json({ ok }, ok ? 200 : 404, noStore);
+    });
+    app.get(`${basePath}/health`, async (c) => {
+        const denied = await guard(c);
+        if (denied)
+            return denied;
+        return c.json({
+            channels: (options.channelsOf?.() ?? options.notifier?.channels ?? []).map((ch) => ({
+                key: ch.key,
+                label: ch.label,
+            })),
+            lastSweep: options.lastSweep?.() ?? null,
+            sweepable: Boolean(options.sweep),
+        }, 200, noStore);
+    });
+    if (options.sweep) {
+        app.post(`${basePath}/sweep`, async (c) => {
+            const denied = await guard(c);
+            if (denied)
+                return denied;
+            const result = await options.sweep?.();
+            if (!result)
+                return c.json({ error: "no detectors on this host" }, 400, noStore);
+            const announced = options.notifier ? await options.notifier.announce(result.transitions) : [];
+            return c.json({ result, announced }, 200, noStore);
+        });
+    }
+    if (options.channelsOf) {
+        app.post(`${basePath}/test/:channel`, async (c) => {
+            const denied = await guard(c);
+            if (denied)
+                return denied;
+            const key = c.req.param("channel");
+            const channel = options.channelsOf?.().find((ch) => ch.key === key);
+            if (!channel)
+                return c.json({ error: `no channel "${key}" on this host` }, 404, noStore);
+            // Sent at `blocking` because that is the severity whose delivery matters —
+            // a test that exercises the in-app path and skips the phone proves nothing.
+            const result = await channel.send({
+                severity: "blocking",
+                subject: "[test] fleet incident alerts",
+                text: "This is the console proving the channel works. Nothing is wrong. No action needed.",
+            });
+            return c.json({ result }, 200, noStore);
+        });
+    }
+}
+/**
+ * The MACHINE doors: `POST /report`, which another service beats its findings
+ * into, and `POST /relay-email`, which a host that cannot send mail hands a
+ * message to. Both carry a shared bearer.
+ *
+ * 🔴 **Mount this BEFORE the session gate, and never call it with `authorize`
+ * expecting it to matter — it registers no route a browser should reach.**
+ * Mounting the two together inside a cookie gate is the trap this split exists
+ * to make impossible: every beat from binary-server and orch came back
+ * `{"error":"unauthorized"}` from the gate, so no log line in this module said
+ * anything was wrong and the console rendered a perfectly calm, empty board.
+ * A reporter cannot report the failure to reach the reporting door.
+ *
+ * Keeping them in one function also risked the opposite mistake — registering
+ * the owner's `GET /incidents` outside the gate, where Hono's first-match would
+ * have shadowed the real one for ever.
+ */
+export function mountIncidentMachineRoutes(app, options, basePath = "/incidents") {
+    const { store } = options;
+    if (options.reporterToken) {
+        app.post(`${basePath}/report`, async (c) => {
+            const header = c.req.header("authorization") ?? "";
+            const presented = header.startsWith("Bearer ") ? header.slice(7) : "";
+            // Length-first compare then constant-time-ish equality; the token is a
+            // shared secret between our own daemons, not a user credential.
+            if (presented.length !== options.reporterToken?.length ||
+                presented !== options.reporterToken) {
+                return c.json({ error: "forbidden" }, 403, noStore);
+            }
+            const body = (await c.req.json().catch(() => null));
+            const checkKey = str(body?.checkKey);
+            const source = str(body?.source);
+            const rawReports = Array.isArray(body?.reports) ? body.reports : null;
+            if (!checkKey || !source || !rawReports) {
+                return c.json({ error: "checkKey, source and reports[] are required" }, 400, noStore);
+            }
+            if (rawReports.length > MAX_REPORTS) {
+                return c.json({ error: `at most ${MAX_REPORTS} reports per call` }, 400, noStore);
+            }
+            let reports;
+            try {
+                reports = rawReports.map(parseReport);
+            }
+            catch (err) {
+                return c.json({ error: err instanceof Error ? err.message : "bad report" }, 400, noStore);
+            }
+            // A reporter declares the kinds it is authoritative for, exactly as a
+            // local check does — without them a remote service could never clear its
+            // own incidents, and every transient blip would stay red forever.
+            const kinds = Array.isArray(body?.kinds)
+                ? body.kinds.filter((k) => typeof k === "string")
+                : [...new Set(reports.map((r) => r.kind))];
+            const transitions = store.reconcile(checkKey, reports, {
+                namespaces: kinds.map((k) => `${source}:${k}:`),
+            });
+            const announced = options.notifier ? await options.notifier.announce(transitions) : [];
+            return c.json({
+                opened: transitions.opened.length,
+                escalated: transitions.escalated.length,
+                resolved: transitions.resolved.length,
+                unchanged: transitions.unchanged.length,
+                announced,
+            }, 200, noStore);
+        });
+    }
+    if (options.relayEmail) {
+        app.post(`${basePath}/relay-email`, async (c) => {
+            const header = c.req.header("authorization") ?? "";
+            const presented = header.startsWith("Bearer ") ? header.slice(7) : "";
+            if (!options.reporterToken ||
+                presented.length !== options.reporterToken.length ||
+                presented !== options.reporterToken) {
+                return c.json({ error: "forbidden" }, 403, noStore);
+            }
+            const body = (await c.req.json().catch(() => null));
+            const subject = str(body?.subject);
+            const text = typeof body?.text === "string" ? body.text.slice(0, 4000) : "";
+            if (!subject || !text)
+                return c.json({ error: "subject and text required" }, 400, noStore);
+            // 🔴 The REASON crosses the wire, not just the boolean. `{sent:false}`
+            // alone made the local console report "the prod console accepted the
+            // request but its mailer declined" — true, useless, and indistinguishable
+            // between "mail is off on that host" and "SES refused the address". The
+            // relay is the only place that knows.
+            const outcome = await options.relayEmail?.({
+                subject,
+                text,
+                ...(typeof body?.html === "string" ? { html: body.html.slice(0, 20_000) } : {}),
+            });
+            return c.json({ sent: Boolean(outcome?.sent), ...(outcome?.reason ? { reason: outcome.reason } : {}) }, 200, noStore);
+        });
+    }
+}

package/dist/server/incidents/store.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The incident store, and the reconcile step that is the whole dedupe promise.
+ *
+ * ── The one rule ────────────────────────────────────────────────────────────
+ * `reconcile()` is the ONLY way an incident changes state, and it is what
+ * decides whether anything is notified. A detector hands it the complete set of
+ * conditions that are true RIGHT NOW; the store diffs that against what it
+ * already holds. Three things can come out of the diff — opened, escalated,
+ * resolved — and everything else is a counter bump that notifies nobody.
+ * Because the diff is set-shaped rather than event-shaped, a poller running
+ * every five minutes for a week produces exactly two messages about one broken
+ * thing: one when it broke, one when it was fixed.
+ *
+ * 🔴 The subtle half is the RESOLVE, and it is where a naive version of this
+ * lies to its owner. A detector that throws, times out, or is not registered on
+ * this host reports nothing — and "reported nothing" must never be read as
+ * "everything it watches is fixed", or a crashed detector cheerfully announces
+ * that an outage is over. Two things prevent that: `reconcile` only ever
+ * resolves fingerprints belonging to the check it was called for AND inside the
+ * namespaces that check declares it is authoritative for, and `runIncidentSweep`
+ * (`checks.ts`) does not call `reconcile` at all for a check that threw.
+ *
+ * ── Where the file lives ────────────────────────────────────────────────────
+ * Whatever `Database` the caller opens. The console keeps it in an incidents
+ * database of its own under the host's app-data root, deliberately NOT in the
+ * metrics database: metrics are capped, regenerable telemetry that trims on write, and
+ * an incident is a governed record whose whole value is that it survives — most
+ * of all across the restart a deploy of the console itself performs.
+ */
+import type { Database } from "bun:sqlite";
+import { type Incident, type IncidentReport, type IncidentTransitions } from "./types";
+/**
+ * The privacy gate, enforced rather than reviewed. `facts` is for numbers —
+ * bytes free, items failed, commits behind — and a string slipping in there is
+ * how a file name reaches an SMS. See the header of `types.ts`.
+ *
+ * It throws rather than sanitising, because a detector author meets the failure
+ * in their own test run, which is the only moment the mistake is cheap.
+ */
+export declare function assertNoContent(report: IncidentReport): void;
+export interface ReconcileOptions {
+    /**
+     * The `source:kind:` prefixes this check is authoritative for on this run.
+     * Resolving is confined to them, so one detector can never resolve another's
+     * incidents — and a check that RAN and found nothing can still clear its own,
+     * which a report list alone cannot express (an empty array is
+     * indistinguishable from "did not run"). `runIncidentSweep` derives these
+     * from the check's declared `kinds`; omitted, they fall back to whatever the
+     * reports mention, which is the safe direction to be wrong in.
+     */
+    namespaces?: string[];
+    now?: number;
+}
+export interface IncidentStore {
+    readonly db: Database;
+    /** Newest activity first. `state: "active"` means open + acknowledged. */
+    list: (opts?: {
+        state?: Incident["state"] | "active";
+        limit?: number;
+    }) => Incident[];
+    get: (fp: string) => Incident | null;
+    /** The dedupe engine. See the module header. */
+    reconcile: (checkKey: string, reports: IncidentReport[], opts?: ReconcileOptions) => IncidentTransitions;
+    /** Record that the OPEN notification for these fingerprints went out. */
+    markNotified: (fps: string[], result: string, now?: number) => void;
+    /** Record that the RESOLVED notification went out. */
+    markResolvedNotified: (fps: string[], now?: number) => void;
+    /** The owner has seen it: stop counting it as needing attention, keep it listed. */
+    acknowledge: (fp: string, now?: number) => boolean;
+}
+/**
+ * Open the store over an existing database. The caller owns the `Database` (and
+ * its lifetime) — this primitive owns one table in it.
+ */
+export declare function createIncidentStore(db: Database): IncidentStore;

package/dist/server/incidents/store.js

@@ -0,0 +1,176 @@
+import { runMigrations } from "../migration/runner";
+import { INCIDENT_MIGRATIONS, INCIDENTS_TABLE } from "./migrations";
+import { fingerprint, } from "./types";
+const toIncident = (r) => ({
+    fingerprint: r.fingerprint,
+    source: r.source,
+    kind: r.kind,
+    subject: r.subject,
+    severity: r.severity === "blocking" ? "blocking" : "warning",
+    state: r.state === "open" ? "open" : r.state === "acknowledged" ? "acknowledged" : "resolved",
+    title: r.title,
+    whatBroke: r.what_broke,
+    whatItBlocks: r.what_it_blocks,
+    whatToDo: r.what_to_do,
+    facts: r.facts_json ? JSON.parse(r.facts_json) : undefined,
+    firstSeen: r.first_seen,
+    lastSeen: r.last_seen,
+    seenCount: r.seen_count,
+    episodes: r.episodes,
+    acknowledgedAt: r.acknowledged_at,
+    resolvedAt: r.resolved_at,
+    notifiedAt: r.notified_at,
+    notifyResult: r.notify_result,
+    resolvedNotifiedAt: r.resolved_notified_at,
+});
+/**
+ * The privacy gate, enforced rather than reviewed. `facts` is for numbers —
+ * bytes free, items failed, commits behind — and a string slipping in there is
+ * how a file name reaches an SMS. See the header of `types.ts`.
+ *
+ * It throws rather than sanitising, because a detector author meets the failure
+ * in their own test run, which is the only moment the mistake is cheap.
+ */
+export function assertNoContent(report) {
+    for (const [key, value] of Object.entries(report.facts ?? {})) {
+        if (typeof value === "number" || typeof value === "boolean" || value === null)
+            continue;
+        throw new Error(`incident ${fingerprint(report)}: fact "${key}" is a ${typeof value}. ` +
+            "facts take numbers, booleans and null only — a string here is how private " +
+            "content reaches a text message. Put the words in whatBroke / whatItBlocks / " +
+            "whatToDo, which a detector's author writes and reviews.");
+    }
+}
+/**
+ * Open the store over an existing database. The caller owns the `Database` (and
+ * its lifetime) — this primitive owns one table in it.
+ */
+export function createIncidentStore(db) {
+    runMigrations(db, INCIDENT_MIGRATIONS);
+    const selectOne = db.prepare(`SELECT * FROM ${INCIDENTS_TABLE} WHERE fingerprint = ?`);
+    const insert = db.prepare(`INSERT INTO ${INCIDENTS_TABLE} (
+			fingerprint, source, check_key, kind, subject, severity, state, title,
+			what_broke, what_it_blocks, what_to_do, facts_json,
+			first_seen, last_seen, seen_count, episodes
+		) VALUES (?, ?, ?, ?, ?, ?, 'open', ?, ?, ?, ?, ?, ?, ?, 1, 1)`);
+    /** A NEW episode of a fingerprint that had resolved. Counters restart; `episodes` does not. */
+    const reopen = db.prepare(`UPDATE ${INCIDENTS_TABLE} SET
+			state = 'open', severity = ?, title = ?, what_broke = ?, what_it_blocks = ?,
+			what_to_do = ?, facts_json = ?, first_seen = ?, last_seen = ?, seen_count = 1,
+			episodes = episodes + 1, acknowledged_at = NULL, resolved_at = NULL,
+			notified_at = NULL, notify_result = NULL, resolved_notified_at = NULL
+		WHERE fingerprint = ?`);
+    /**
+     * Observed again. The words and the facts are REFRESHED — the numbers move,
+     * and "17 GB free" must not stay frozen at whatever it was on Tuesday — but
+     * nothing about the lifecycle moves, so no transition is emitted and nothing
+     * is sent. This statement is the dedupe, in one place.
+     */
+    const touch = db.prepare(`UPDATE ${INCIDENTS_TABLE} SET
+			last_seen = ?, seen_count = seen_count + 1, title = ?, what_broke = ?,
+			what_it_blocks = ?, what_to_do = ?, facts_json = ?, severity = ?
+		WHERE fingerprint = ?`);
+    const resolveStmt = db.prepare(`UPDATE ${INCIDENTS_TABLE} SET state = 'resolved', resolved_at = ? WHERE fingerprint = ?`);
+    const store = {
+        db,
+        list(opts = {}) {
+            const limit = opts.limit ?? 200;
+            if (opts.state === "active") {
+                return db
+                    .prepare(`SELECT * FROM ${INCIDENTS_TABLE} WHERE state IN ('open','acknowledged')
+								ORDER BY last_seen DESC LIMIT ?`)
+                    .all(limit).map(toIncident);
+            }
+            if (opts.state) {
+                return db
+                    .prepare(`SELECT * FROM ${INCIDENTS_TABLE} WHERE state = ? ORDER BY last_seen DESC LIMIT ?`)
+                    .all(opts.state, limit).map(toIncident);
+            }
+            return db
+                .prepare(`SELECT * FROM ${INCIDENTS_TABLE} ORDER BY last_seen DESC LIMIT ?`)
+                .all(limit).map(toIncident);
+        },
+        get(fp) {
+            const row = selectOne.get(fp);
+            return row ? toIncident(row) : null;
+        },
+        reconcile(checkKey, reports, opts = {}) {
+            const now = opts.now ?? Date.now();
+            const out = { opened: [], escalated: [], resolved: [], unchanged: [] };
+            const seen = new Set();
+            for (const report of reports) {
+                assertNoContent(report);
+                const fp = fingerprint(report);
+                seen.add(fp);
+                const facts = report.facts ? JSON.stringify(report.facts) : null;
+                const existing = selectOne.get(fp);
+                if (!existing) {
+                    insert.run(fp, report.source, checkKey, report.kind, report.subject, report.severity, report.title, report.whatBroke, report.whatItBlocks, report.whatToDo, facts, now, now);
+                    const opened = store.get(fp);
+                    if (opened)
+                        out.opened.push(opened);
+                    continue;
+                }
+                if (existing.state === "resolved") {
+                    reopen.run(report.severity, report.title, report.whatBroke, report.whatItBlocks, report.whatToDo, facts, now, now, fp);
+                    const reopened = store.get(fp);
+                    if (reopened)
+                        out.opened.push(reopened);
+                    continue;
+                }
+                // Still open, or acknowledged. The one thing left that can be worth a
+                // message is a WARNING that has become BLOCKING, because that changes
+                // which channels the incident is entitled to. Everything else is noise.
+                const escalating = existing.severity !== "blocking" && report.severity === "blocking";
+                touch.run(now, report.title, report.whatBroke, report.whatItBlocks, report.whatToDo, facts, report.severity, fp);
+                const current = store.get(fp);
+                if (!current)
+                    continue;
+                if (escalating)
+                    out.escalated.push(current);
+                else
+                    out.unchanged.push(current);
+            }
+            const prefixes = opts.namespaces ?? [
+                ...new Set(reports.map((r) => `${r.source}:${r.kind}:`)),
+            ];
+            const candidates = db
+                .prepare(`SELECT * FROM ${INCIDENTS_TABLE} WHERE check_key = ? AND state IN ('open','acknowledged')`)
+                .all(checkKey);
+            for (const row of candidates) {
+                if (seen.has(row.fingerprint))
+                    continue;
+                // Outside the namespaces this run is authoritative for — leave it alone.
+                // With no namespaces at all (a check that declared none and reported
+                // none) nothing resolves, which is the correct reading of "I have no
+                // idea" rather than "everything is fine".
+                if (!prefixes.some((p) => row.fingerprint.startsWith(p)))
+                    continue;
+                resolveStmt.run(now, row.fingerprint);
+                const resolved = store.get(row.fingerprint);
+                if (resolved)
+                    out.resolved.push(resolved);
+            }
+            return out;
+        },
+        markNotified(fps, result, now = Date.now()) {
+            const stmt = db.prepare(`UPDATE ${INCIDENTS_TABLE} SET notified_at = ?, notify_result = ? WHERE fingerprint = ?`);
+            for (const fp of fps)
+                stmt.run(now, result, fp);
+        },
+        markResolvedNotified(fps, now = Date.now()) {
+            const stmt = db.prepare(`UPDATE ${INCIDENTS_TABLE} SET resolved_notified_at = ? WHERE fingerprint = ?`);
+            for (const fp of fps)
+                stmt.run(now, fp);
+        },
+        acknowledge(fp, now = Date.now()) {
+            const row = selectOne.get(fp);
+            if (!row || row.state !== "open")
+                return false;
+            db.prepare(`UPDATE ${INCIDENTS_TABLE} SET state = 'acknowledged', acknowledged_at = ?
+					WHERE fingerprint = ?`).run(now, fp);
+            return true;
+        },
+    };
+    return store;
+}

package/dist/server/incidents/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The incident contract — what a detector reports, and what the store keeps.
+ *
+ * ── Why an INCIDENT and not an event (2026-08-13, the owner) ────────────────
+ * "auto notifying me once per incident (it needs to avoid sending me the same
+ * problem over and over in duplicated notifications if it's polling for
+ * problems)". A poller that re-sends every five minutes is the failure mode
+ * that gets the whole feature muted, which puts him back where he started but
+ * with more noise. So the unit of this module is a *condition that is true for
+ * a while*, identified by a stable {@link fingerprint}, with a lifecycle —
+ * and a notification is attached to a TRANSITION of that lifecycle, never to
+ * an observation. Observing the same broken thing for the ninth hour running
+ * bumps a counter and sends nothing.
+ *
+ * ── 🔴 An incident carries WHAT failed, never the content ───────────────────
+ * These messages go to a phone and to an inbox, and several apps on this fleet
+ * are private (notes) or zero-knowledge by construction (vault). A file name,
+ * a note title or a vault key in an SMS is a leak by a different door. So the
+ * shape below has no free-form payload: `subject` is a stable IDENTIFIER (an
+ * app key, a launchd label, a queue name), the three human fields are written
+ * by the detector's own author, and {@link IncidentReport.facts} takes NUMBERS
+ * and enum-ish strings only. `assertNoContent` in `store.ts` enforces the last
+ * one at write time rather than trusting a reviewer.
+ */
+/** How loud an incident is. There are only two, on purpose — see `notifier.ts`. */
+export type IncidentSeverity = 
+/** The owner's own examples: "can't deploy, can't ingest files". Email AND text. */
+"blocking"
+/** Worth knowing, in-app only. A warning that texts him is a warning that mutes the channel. */
+ | "warning";
+/** Where an incident is in its life. */
+export type IncidentState = 
+/** Still true, not yet dealt with. */
+"open"
+/** Still true; the owner has seen it and does not want to be told again. */
+ | "acknowledged"
+/** No longer reported by its detector. */
+ | "resolved";
+/** A fact attached to an incident. Numbers and enum-ish strings only — see the header. */
+export type IncidentFact = number | boolean | null;
+/**
+ * One condition, as a detector reports it. The detector does NOT decide whether
+ * this is new, whether to notify, or what the current state is — that is the
+ * store's job, and keeping it there is the whole dedupe guarantee.
+ */
+export interface IncidentReport {
+    /** Which app or service noticed it: `binary-server`, `station`, `orch`. */
+    source: string;
+    /** The detector that produced it, e.g. `disk-below-reserve`. Stable across runs. */
+    kind: string;
+    /**
+     * WHAT the condition is about, as a stable identifier — an app key, a launchd
+     * label, a queue name. Never a file name, a title, or anything a person typed.
+     */
+    subject: string;
+    severity: IncidentSeverity;
+    /** One line, for a notification subject and a table row. Names the app. */
+    title: string;
+    /** ELI5: what actually broke. Assume he does not know what your daemon is. */
+    whatBroke: string;
+    /** ELI5: what it stops him doing. This is the sentence that earns the text message. */
+    whatItBlocks: string;
+    /** ELI5: what to do about it. A runnable command carries its own `cd` (fleet rule). */
+    whatToDo: string;
+    /** Numbers only — bytes free, items failed, commits behind. See the header. */
+    facts?: Record<string, IncidentFact>;
+}
+/** A stored incident: a report, plus everything the store knows about its life. */
+export interface Incident extends IncidentReport {
+    fingerprint: string;
+    state: IncidentState;
+    /** Epoch ms of the first observation of this episode. */
+    firstSeen: number;
+    /** Epoch ms of the most recent observation. */
+    lastSeen: number;
+    /** How many sweeps have observed it in this episode. */
+    seenCount: number;
+    /** How many times this fingerprint has opened, ever. A flapper is visible. */
+    episodes: number;
+    acknowledgedAt: number | null;
+    resolvedAt: number | null;
+    /** When the OPEN notification went out, and what happened to each channel. */
+    notifiedAt: number | null;
+    notifyResult: string | null;
+    /** When the RESOLVED notification went out. */
+    resolvedNotifiedAt: number | null;
+}
+/**
+ * What one sweep changed. Only these three lists produce notifications — an
+ * incident merely observed again appears in none of them.
+ */
+export interface IncidentTransitions {
+    /** Newly true, or true again after a resolve. Notify. */
+    opened: Incident[];
+    /** Was a warning, is now blocking. Notify — the channel set changed. */
+    escalated: Incident[];
+    /** No longer reported. Notify once, so "is it fixed?" is answered without asking. */
+    resolved: Incident[];
+    /** Observed again while already open. **Never notified.** Here so a test can see it. */
+    unchanged: Incident[];
+}
+/**
+ * A stable identity for a condition. Deliberately NOT a hash of the message:
+ * an author who improves the wording of `whatToDo` must not thereby re-alert
+ * the owner about a problem he already knows about.
+ */
+export declare function fingerprint(report: Pick<IncidentReport, "source" | "kind" | "subject">): string;

package/dist/server/incidents/types.js

@@ -0,0 +1,32 @@
+/**
+ * The incident contract — what a detector reports, and what the store keeps.
+ *
+ * ── Why an INCIDENT and not an event (2026-08-13, the owner) ────────────────
+ * "auto notifying me once per incident (it needs to avoid sending me the same
+ * problem over and over in duplicated notifications if it's polling for
+ * problems)". A poller that re-sends every five minutes is the failure mode
+ * that gets the whole feature muted, which puts him back where he started but
+ * with more noise. So the unit of this module is a *condition that is true for
+ * a while*, identified by a stable {@link fingerprint}, with a lifecycle —
+ * and a notification is attached to a TRANSITION of that lifecycle, never to
+ * an observation. Observing the same broken thing for the ninth hour running
+ * bumps a counter and sends nothing.
+ *
+ * ── 🔴 An incident carries WHAT failed, never the content ───────────────────
+ * These messages go to a phone and to an inbox, and several apps on this fleet
+ * are private (notes) or zero-knowledge by construction (vault). A file name,
+ * a note title or a vault key in an SMS is a leak by a different door. So the
+ * shape below has no free-form payload: `subject` is a stable IDENTIFIER (an
+ * app key, a launchd label, a queue name), the three human fields are written
+ * by the detector's own author, and {@link IncidentReport.facts} takes NUMBERS
+ * and enum-ish strings only. `assertNoContent` in `store.ts` enforces the last
+ * one at write time rather than trusting a reviewer.
+ */
+/**
+ * A stable identity for a condition. Deliberately NOT a hash of the message:
+ * an author who improves the wording of `whatToDo` must not thereby re-alert
+ * the owner about a problem he already knows about.
+ */
+export function fingerprint(report) {
+    return `${report.source}:${report.kind}:${report.subject}`;
+}

package/dist/server/index.d.ts

@@ -0,0 +1,25 @@
+export { ChunkStore, type ChunkStoreOpts, CTGR_WIRE_VERSION, type CtgrDecoded, type CtgrMethod, decodeRequest, type EncodedRequest, type EncodeOpts, encodeRequest, type UploadedFile, } from 'cursedbelt-core/ctgr';
+export { type CreateAppOpts, createApp, type ServeBunOpts, serveBun } from './app';
+export { type AppJwtPayload, AUTH_COOKIE_NAME, type AuthEnv, type AuthUser, type AuthVariables, type CreateSessionInput, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, type CsrfOptions, clearAuthCookie, createAuthMiddleware, createCsrfMiddleware, clientKeyOf, clientKeyOfContext, createLoginThrottle, createSessionStore, createRs256FileTokenSigner, DEFAULT_TOTP_ISSUER, decryptVaultItem, deriveVaultKey, encryptVaultItem, generateRecoveryCodes, generateTotpSecret, getOnlyEnforcement, getTotpUri, hashPassword, isGetOnlyViolation, type LoginThrottle, type LoginThrottleOptions, type ThrottleVerdict, needsRehash, type Rs256FileTokenSignerOptions, type Session, type SessionStore, type SessionStoreOptions, signToken, type TokenPurpose, verifyPassword, verifyPurposeToken, verifyRecoveryCode, verifyToken, verifyTotpCode, } from './auth';
+export type { CursedbeltEnv, CursedbeltVariables } from './context';
+export { buildRoutes, CTGR_ROUTE_PATTERN, getCtgrDecoded, unGETify } from './ctgr';
+export { createKysely, type PlumbingDb } from './db/kysely';
+export type { AppConfigRow, AuthSessionRow, EmailFailureRow, EventLogRow, JobRunRow, JobStateRow, MigrationRow, PlumbingSchema, RequestMetricRow, SystemSampleRow, } from './db/plumbingTypes';
+export { ApiError, type ApiErrorOptions, type ErrorEnvelope, isApiError, toErrorEnvelope, toValidationIssues, VALIDATION_ERROR_CODE, type ValidationIssue, validationEnvelope, } from './errors';
+export { type CreateJobRunnerOptions, createFireQueue, createJobRunner, createPollingJob, DEFAULT_FIRE_INTERVAL_MS, DEFAULT_JOB_TIMEOUT_MS, defaultJobLogger, type FireQueue, type FireQueueOpts, type JobContext, type JobDef, type JobLogger, type JobRunner, type JobRunRecord, JobTimeoutError, type PollingJob, type PollingJobOpts, } from './jobs';
+export { buildProbeArgs, buildThumbnailArgs, buildTrimArgs, extractThumbnail, ffmpegTimeToSeconds, isFfmpegAvailable, isFfprobeAvailable, type ProbeResult, parseFfmpegProgress, parseFfprobe, probeMedia, renderImage, trimVideo, type VideoCodecPlan, videoCodecPlan, } from './media-bun';
+export { createMetricsBuffer, type MetricRow, type MetricsBuffer, type MetricsBufferOptions, } from './metrics/metricsBuffer';
+export { normalizeRoute } from './metrics/normalizeRoute';
+export { correlationId } from './middleware/correlationId';
+export { type CorsOpts, corsAllowlist, corsOptsFromEnv } from './middleware/corsAllowlist';
+export { errorEnvelope } from './middleware/errorEnvelope';
+export { crossOriginRefusal } from './middleware/localOrigin';
+export { clientIp, createRateLimiter, type RateLimitOpts } from './middleware/rateLimit';
+export { type RequestLoggerOpts, requestLogger } from './middleware/requestLogger';
+export { type CspDirectives, type SecurityHeadersOpts, securityHeaders, } from './middleware/securityHeaders';
+export { type ZValidatorTarget, zValidator } from './middleware/zValidator';
+export { addColumnIfMissing, applyRecommendedPragmas, columnExists, runMigrations } from './migration/runner';
+export type { Migration } from './migration/types';
+export { AUDIT_LOG_MIGRATIONS, auditStateAt, auditStateAtVersion, auditStep, createSqliteAuditSink, } from './audit';
+export { applyFtsSchema, type BackupInfo, buildFtsSchema, clampLimit, clampOffset, collectSqliteStats, createFts5Search, createSqliteBackupService, createSqliteHealthChecks, createSqliteViewerMiddleware, type DbStats, exportSqliteSnapshot, exportSqliteTable, type Fts5Search, type FtsHighlightOpts, type FtsResult, type FtsSearchOpts, type FtsSnippetOpts, type FtsTableSpec, type ImportMode, type ImportResult, importRowsIntoSqliteTable, isKnownTable, isReadOnlySql, listSqliteTables, NotReadOnlyError, quoteIdent, type RestoreResult, readSqliteTable, restoreSqliteSnapshot, runReadonlySqlite, type SnapshotExport, type SqliteBackupOpts, type SqliteBackupS3Opts, type SqliteBackupService, type SqliteHealthCheck, type SqliteHealthOpts, type SqliteHealthResult, type SqliteHealthStatus, type SqliteTableInfo, type SqliteTablePage, sanitizeFtsQuery, snapshotSqlite, type TableExport, type TableExportFormat, type TableStat, UnknownTableError, } from './sqlite';
+export { computePresence, createEventBus, createWsHub, type EventBus, type EventBusData, joinRoom, leaveRoom, type PresenceEntry, type PresenceState, ROOM_META_KEY, roomOf, type WsChannel, type WsClient, type WsData, type WsHandshake, type WsHub, type WsHubOpts, type WsMessage, } from './ws';