cursedbelt-server 1.0.0

package/src/server/incidents/store.ts

@@ -0,0 +1,329 @@
+/**
+ * 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 { runMigrations } from "../migration/runner";
+import { INCIDENT_MIGRATIONS, INCIDENTS_TABLE } from "./migrations";
+import {
+	fingerprint,
+	type Incident,
+	type IncidentFact,
+	type IncidentReport,
+	type IncidentTransitions,
+} from "./types";
+
+interface Row {
+	fingerprint: string;
+	source: string;
+	kind: string;
+	subject: string;
+	severity: string;
+	state: string;
+	title: string;
+	what_broke: string;
+	what_it_blocks: string;
+	what_to_do: string;
+	facts_json: string | null;
+	first_seen: number;
+	last_seen: number;
+	seen_count: number;
+	episodes: number;
+	acknowledged_at: number | null;
+	resolved_at: number | null;
+	notified_at: number | null;
+	notify_result: string | null;
+	resolved_notified_at: number | null;
+}
+
+const toIncident = (r: Row): Incident => ({
+	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) as Record<string, IncidentFact>) : 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: IncidentReport): void {
+	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.",
+		);
+	}
+}
+
+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 function createIncidentStore(db: Database): IncidentStore {
+	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: IncidentStore = {
+		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) as Row[]
+				).map(toIncident);
+			}
+			if (opts.state) {
+				return (
+					db
+						.prepare(
+							`SELECT * FROM ${INCIDENTS_TABLE} WHERE state = ? ORDER BY last_seen DESC LIMIT ?`,
+						)
+						.all(opts.state, limit) as Row[]
+				).map(toIncident);
+			}
+			return (
+				db
+					.prepare(`SELECT * FROM ${INCIDENTS_TABLE} ORDER BY last_seen DESC LIMIT ?`)
+					.all(limit) as Row[]
+			).map(toIncident);
+		},
+
+		get(fp) {
+			const row = selectOne.get(fp) as Row | null;
+			return row ? toIncident(row) : null;
+		},
+
+		reconcile(checkKey, reports, opts = {}) {
+			const now = opts.now ?? Date.now();
+			const out: IncidentTransitions = { opened: [], escalated: [], resolved: [], unchanged: [] };
+			const seen = new Set<string>();
+
+			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) as Row | null;
+
+				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) as Row[];
+			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) as Row | null;
+			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/src/server/incidents/types.ts

@@ -0,0 +1,116 @@
+/**
+ * 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 function fingerprint(report: Pick<IncidentReport, "source" | "kind" | "subject">): string {
+	return `${report.source}:${report.kind}:${report.subject}`;
+}

package/src/server/index.ts

@@ -0,0 +1,248 @@
+// cursedbelt server toolkit — native Hono on Bun.serve. Consumed by ca + ru.
+//
+// HTTP app + middleware + the canonical error envelope + a versioned SQLite
+// migration runner + Kysely-typed access for the plumbing tables. Business routes,
+// auth model, sharing, jobs, and `data JSON` tables stay in the apps; cursedbelt
+// owns the plumbing.
+
+// ── ctgr (isomorphic codec re-exports + the Hono GET-tunnel transport) ───────
+export {
+  ChunkStore,
+  type ChunkStoreOpts,
+  CTGR_WIRE_VERSION,
+  type CtgrDecoded,
+  type CtgrMethod,
+  decodeRequest,
+  type EncodedRequest,
+  type EncodeOpts,
+  encodeRequest,
+  type UploadedFile,
+} from 'cursedbelt-core/ctgr';
+// ── HTTP app ────────────────────────────────────────────────────────────────
+export { type CreateAppOpts, createApp, type ServeBunOpts, serveBun } from './app';
+// ── Auth toolkit (task 26): jose JWT, cookies, CSRF, getOnly, session store, ──
+//    login throttle, argon2id passwords, TOTP, vault crypto, the composed middleware.
+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';
+// ── Kysely-typed plumbing tables ────────────────────────────────────────────
+export { createKysely, type PlumbingDb } from './db/kysely';
+export type {
+  AppConfigRow,
+  AuthSessionRow,
+  EmailFailureRow,
+  EventLogRow,
+  JobRunRow,
+  JobStateRow,
+  MigrationRow,
+  PlumbingSchema,
+  RequestMetricRow,
+  SystemSampleRow,
+} from './db/plumbingTypes';
+// ── Errors ──────────────────────────────────────────────────────────────────
+export {
+  ApiError,
+  type ApiErrorOptions,
+  type ErrorEnvelope,
+  isApiError,
+  toErrorEnvelope,
+  toValidationIssues,
+  VALIDATION_ERROR_CODE,
+  type ValidationIssue,
+  validationEnvelope,
+} from './errors';
+// ── Jobs & scheduler (task 29): plainjob-backed cron runner + restart-aware ───
+//    pollers + the due-row fire queue. App job *definitions* stay business.
+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';
+// ── Media adapter (task 19): image rendering via sharp (lazy/optional peer) + ──
+//    video trim / probe / thumbnail via native ffmpeg. Also at the dedicated
+//    media-bun entry below; sharp is imported lazily inside renderImage,
+//    so importing this barrel never loads the native binary.
+export {
+  buildProbeArgs,
+  buildThumbnailArgs,
+  buildTrimArgs,
+  extractThumbnail,
+  ffmpegTimeToSeconds,
+  isFfmpegAvailable,
+  isFfprobeAvailable,
+  type ProbeResult,
+  parseFfmpegProgress,
+  parseFfprobe,
+  probeMedia,
+  renderImage,
+  trimVideo,
+  type VideoCodecPlan,
+  videoCodecPlan,
+} from './media-bun';
+// ── Metrics ───────────────────────────────────────────────────────────────────
+export {
+  createMetricsBuffer,
+  type MetricRow,
+  type MetricsBuffer,
+  type MetricsBufferOptions,
+} from './metrics/metricsBuffer';
+export { normalizeRoute } from './metrics/normalizeRoute';
+// ── Middleware ────────────────────────────────────────────────────────────────
+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';
+// ── zod validation toolkit ────────────────────────────────────────────────────
+//    (the `validationEnvelope`/`toValidationIssues`/`ValidationIssue` builders now
+//     live with the canonical envelope in `./errors`, re-exported above.)
+export { type ZValidatorTarget, zValidator } from './middleware/zValidator';
+// ── Migration runner ──────────────────────────────────────────────────────────
+export { addColumnIfMissing, applyRecommendedPragmas, columnExists, runMigrations } from './migration/runner';
+export type { Migration } from './migration/types';
+// ── Audit log: the SQLite-backed AuditSink cursedshell's service dispatch ─────
+//    writes to (see `cwip/audit` for the storage-agnostic contract + the
+//    zero-config in-memory default).
+export {
+  AUDIT_LOG_MIGRATIONS,
+  auditStateAt,
+  auditStateAtVersion,
+  auditStep,
+  createSqliteAuditSink,
+} from './audit';
+// ── SQLite toolkit extras (task 30): FTS5 ranked search + DDL generator, the ───
+//    read-only DB viewer middleware, the VACUUM-INTO backup service, DB health probes.
+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';
+// ── WebSocket hub (task 28): Bun-native upgrade, channel registry, heartbeat, ──
+//    presence-as-a-view, room helpers, and the push-only event-bus subset (ru).
+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';