cursedbelt-server 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/dist/server/activity/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `cursedbelt-server/activity` — the fleet's ONE append-only activity/audit
+ * stream: who did what, to which record, when, and how it went.
+ *
+ * The vocabulary is `cursedbelt-core/activity` (pure), this is the storage + query
+ * half, and the console's **Event Logs** tab is the fleet-wide reader — it asks
+ * every live deployment through `satellite-kit/metrics`' bearer-gated
+ * `?view=events`, so an app is on the board by writing events, with no
+ * admin-side wiring at all.
+ *
+ * ── Retention ───────────────────────────────────────────────────────────────
+ * This package never deletes an event. An app whose stream is high-volume opts
+ * into the fleet standard (`docs/retention.md` in `cursed-satellites`) by
+ * declaring the table, which puts the number under the owner's control in the
+ * station rather than in a constant here:
+ *
+ * ```ts
+ * createSqliteTableTarget({
+ *   db, table: ACTIVITY_EVENTS_TABLE, timeColumn: "at", timeFormat: "iso",
+ *   declaration: { app: "notes", id: "activity", label: "Activity log",
+ *     category: "event-log", unit: "rows", location: "notes.sqlite · activity_events",
+ *     consequence: "Who did what, for hindsight. Losing it costs no data." },
+ * })
+ * ```
+ *
+ * An app whose stream is a handful of rows a month — an audit of destructive
+ * actions, say — is right to declare NOTHING and say so: the standard is opt-in
+ * by category, and an audit trail of production deletions is precisely the data
+ * a 14-day cutoff must not reach.
+ */
+export { ACTIVITY_EVENTS_TABLE, ACTIVITY_MIGRATIONS } from "./migrations";
+export { shareEventsSource, type ShareEventsSourceOptions } from "./shareSource";
+export { createActivityLog } from "./store";
+export type { ActivityFacet, ActivityFacets, ActivityLog, ActivityLogOptions, ActivityPage, ActivityQuery, ActivitySource, } from "./store";
+export { ACTIVITY_OUTCOMES, activityFromShareEvent, activitySubject, describeActivityEvent, describeActivityResource, isActivityAction, isActivityOutcome, } from "cursedbelt-core/activity/model";
+export type { ActivityEvent, ActivityEventInput, ActivityOutcome, ActivityResource, } from "cursedbelt-core/activity/model";

package/dist/server/activity/index.js

@@ -0,0 +1,36 @@
+/**
+ * `cursedbelt-server/activity` — the fleet's ONE append-only activity/audit
+ * stream: who did what, to which record, when, and how it went.
+ *
+ * The vocabulary is `cursedbelt-core/activity` (pure), this is the storage + query
+ * half, and the console's **Event Logs** tab is the fleet-wide reader — it asks
+ * every live deployment through `satellite-kit/metrics`' bearer-gated
+ * `?view=events`, so an app is on the board by writing events, with no
+ * admin-side wiring at all.
+ *
+ * ── Retention ───────────────────────────────────────────────────────────────
+ * This package never deletes an event. An app whose stream is high-volume opts
+ * into the fleet standard (`docs/retention.md` in `cursed-satellites`) by
+ * declaring the table, which puts the number under the owner's control in the
+ * station rather than in a constant here:
+ *
+ * ```ts
+ * createSqliteTableTarget({
+ *   db, table: ACTIVITY_EVENTS_TABLE, timeColumn: "at", timeFormat: "iso",
+ *   declaration: { app: "notes", id: "activity", label: "Activity log",
+ *     category: "event-log", unit: "rows", location: "notes.sqlite · activity_events",
+ *     consequence: "Who did what, for hindsight. Losing it costs no data." },
+ * })
+ * ```
+ *
+ * An app whose stream is a handful of rows a month — an audit of destructive
+ * actions, say — is right to declare NOTHING and say so: the standard is opt-in
+ * by category, and an audit trail of production deletions is precisely the data
+ * a 14-day cutoff must not reach.
+ */
+export { ACTIVITY_EVENTS_TABLE, ACTIVITY_MIGRATIONS } from "./migrations";
+export { shareEventsSource } from "./shareSource";
+export { createActivityLog } from "./store";
+// Re-exported so a server consumer needs ONE import for the whole contract; the
+// pure entry (`cursedbelt-core/activity`) stays available for a browser or a spec.
+export { ACTIVITY_OUTCOMES, activityFromShareEvent, activitySubject, describeActivityEvent, describeActivityResource, isActivityAction, isActivityOutcome, } from "cursedbelt-core/activity/model";

package/dist/server/activity/migrations.d.ts

@@ -0,0 +1,21 @@
+import type { Migration } from "../migration/types";
+/** The one table this primitive owns. Exported so an app can declare a retention
+ *  target over it (see this module's `index.ts` for the recipe). */
+export declare const ACTIVITY_EVENTS_TABLE = "activity_events";
+/**
+ * ONE append-only table per app, not a shadow table per business table.
+ *
+ * The stream's whole value is being readable as one list — "everything that
+ * happened in `notes` yesterday", "everything `curt@…` did", "everything that
+ * touched person `3f2`" — and a per-table history cannot answer any of those
+ * without a UNION nobody maintains. `(kind, resource_id)` plays the role a
+ * shadow table would, and is a business key the app already has rather than a
+ * migration in `cursedbelt`.
+ *
+ * 🔴 **Append only.** There is no update and no delete verb anywhere in this
+ * package. The one sanctioned deleter is the fleet retention standard
+ * (`satellite-kit/retention`), which an app opts into by declaring this table as
+ * an `event-log`/`audit-log` resource — a control the owner can see and change,
+ * rather than a cutoff buried in a store.
+ */
+export declare const ACTIVITY_MIGRATIONS: readonly Migration[];

package/dist/server/activity/migrations.js

@@ -0,0 +1,55 @@
+/** The one table this primitive owns. Exported so an app can declare a retention
+ *  target over it (see this module's `index.ts` for the recipe). */
+export const ACTIVITY_EVENTS_TABLE = "activity_events";
+/**
+ * ONE append-only table per app, not a shadow table per business table.
+ *
+ * The stream's whole value is being readable as one list — "everything that
+ * happened in `notes` yesterday", "everything `curt@…` did", "everything that
+ * touched person `3f2`" — and a per-table history cannot answer any of those
+ * without a UNION nobody maintains. `(kind, resource_id)` plays the role a
+ * shadow table would, and is a business key the app already has rather than a
+ * migration in `cursedbelt`.
+ *
+ * 🔴 **Append only.** There is no update and no delete verb anywhere in this
+ * package. The one sanctioned deleter is the fleet retention standard
+ * (`satellite-kit/retention`), which an app opts into by declaring this table as
+ * an `event-log`/`audit-log` resource — a control the owner can see and change,
+ * rather than a cutoff buried in a store.
+ */
+export const ACTIVITY_MIGRATIONS = [
+    {
+        name: "0001_activity_events",
+        up(db) {
+            db.run(`
+				CREATE TABLE IF NOT EXISTS ${ACTIVITY_EVENTS_TABLE} (
+					event_id    INTEGER PRIMARY KEY AUTOINCREMENT,
+					at          TEXT NOT NULL,
+					app         TEXT NOT NULL,
+					actor       TEXT NOT NULL,
+					action      TEXT NOT NULL,
+					kind        TEXT,
+					resource_id TEXT,
+					outcome     TEXT NOT NULL DEFAULT 'ok'
+					            CHECK (outcome IN ('ok', 'denied', 'error')),
+					note        TEXT NOT NULL DEFAULT '',
+					data        TEXT
+				)
+			`);
+            // The stream itself, newest first — the read every screen starts from.
+            db.run(`CREATE INDEX IF NOT EXISTS idx_activity_events_at
+				 ON ${ACTIVITY_EVENTS_TABLE} (at DESC, event_id DESC)`);
+            // "Everything this person did" — the offboarding and the who-broke-it
+            // question, and the one a fleet-wide search runs first.
+            db.run(`CREATE INDEX IF NOT EXISTS idx_activity_events_actor
+				 ON ${ACTIVITY_EVENTS_TABLE} (actor, event_id DESC)`);
+            // "Everything that ever happened to this record."
+            db.run(`CREATE INDEX IF NOT EXISTS idx_activity_events_resource
+				 ON ${ACTIVITY_EVENTS_TABLE} (kind, resource_id, event_id DESC)`);
+            // "Everything backups ever did" — an action-prefix filter is a range
+            // scan on this index, which is why the vocabulary is dotted.
+            db.run(`CREATE INDEX IF NOT EXISTS idx_activity_events_action
+				 ON ${ACTIVITY_EVENTS_TABLE} (action, event_id DESC)`);
+        },
+    },
+];

package/dist/server/activity/shareSource.d.ts

@@ -0,0 +1,11 @@
+import type { ActivitySource } from "./store";
+export interface ShareEventsSourceOptions {
+    /** The satellite this log speaks for — the same value passed to
+     *  `createActivityLog`, used where a group event names no resource. */
+    app: string;
+    /** Overridden only by a test hosting the table under another name. */
+    table?: string;
+    /** The contributor name, which prefixes every id it produces. */
+    name?: string;
+}
+export declare function shareEventsSource(options: ShareEventsSourceOptions): ActivitySource;

package/dist/server/activity/shareSource.js

@@ -0,0 +1,45 @@
+/**
+ * The sharing primitive, as a contributor to the activity stream.
+ *
+ * 🔴 This is the whole point of `sources`: `cursedbelt-server/sharing` already
+ * keeps an audit trail nothing ever deletes, in `share_events`, and it is
+ * guaranteed to be complete (no grant can be made without a row — see that
+ * store's property 1). So the activity stream READS it where it lives rather
+ * than asking an app to mirror it. One row, one truth, no drift, and nothing to
+ * reconcile if a mirror write is ever missed.
+ *
+ * ```ts
+ * const activity = createActivityLog({
+ *   db, app: "family", sources: [shareEventsSource({ app: "family" })],
+ * });
+ * ```
+ *
+ * The mapping is field-for-field the one `activityFromShareEvent` performs in
+ * the vocabulary, and `store.spec.ts` asserts the two agree — a SQL projection
+ * and a TypeScript function are two implementations of one shape, so the suite
+ * pins them together rather than trusting that they were written on the same
+ * afternoon.
+ *
+ * `share_events.app` is NULL for a GROUP lifecycle event (creating a group is
+ * about no single resource), so the app is coalesced to the log's own name: a
+ * fleet-wide board merges on that column and an unlabeled row would be
+ * unattributable.
+ */
+import { SHARE_EVENTS_TABLE } from "../sharing/migrations";
+export function shareEventsSource(options) {
+    const table = options.table ?? SHARE_EVENTS_TABLE;
+    const name = options.name ?? "share";
+    return {
+        name,
+        requiresTable: table,
+        // Column contract: source, seq, at, app, actor, action, kind, resource_id,
+        // outcome, note, data — in this order. See `ActivitySource`.
+        sql: `SELECT '${name}' AS source, event_id AS seq, at, COALESCE(app, ?) AS app, actor,
+		             'share.' || action AS action, kind, resource_id,
+		             'ok' AS outcome, note,
+		             json_object('subjectType', subject_type, 'subjectId', subject_id,
+		                         'level', level, 'previousLevel', previous_level) AS data
+		        FROM ${table}`,
+        params: [options.app],
+    };
+}

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

@@ -0,0 +1,123 @@
+/**
+ * The activity store: one append-only table, plus any number of read-only
+ * SOURCES projected into the same shape, queried as one stream.
+ *
+ * ── How an app uses it ──────────────────────────────────────────────────────
+ * ```ts
+ * const activity = createActivityLog({
+ *   db,
+ *   app: "family",
+ *   // The sharing primitive already audits itself. Read those rows where they
+ *   // are instead of copying them — see `shareEventsSource`.
+ *   sources: [shareEventsSource()],
+ * });
+ *
+ * activity.record({ actor: viewer.email, action: "person.delete",
+ *                   resource: { kind: "person", id }, note: "duplicate" });
+ *
+ * activity.query({ since, actor, action: "share.", limit: 100 });
+ * ```
+ *
+ * ── 🔴 Four properties this file exists to guarantee ────────────────────────
+ *  1. **Append only.** No update verb, no delete verb, no `TRUNCATE`. Ageing
+ *     rows out is the fleet retention standard's job, through a declaration the
+ *     owner can see (`satellite-kit/retention`) — never a silent cutoff here.
+ *  2. **A source is READ, never copied.** `share_events` stays the canonical
+ *     sharing trail; this store selects from it. Two tables holding the same
+ *     audit rows is two tables that will one day disagree, and the one people
+ *     would trust is whichever the screen happened to read.
+ *  3. **A missing source table is an empty source, not a 500.** An app may
+ *     register `shareEventsSource()` before it has ever created a grant, and a
+ *     dashboard must not die on the app that has done nothing yet. (The same
+ *     lesson `orch`'s `plainjob_jobs` retention target learned at boot.)
+ *  4. **`action` is validated at the write.** An action vocabulary that drifts
+ *     cannot be filtered, and filtering is the whole point of the column.
+ */
+import type { Database, SQLQueryBindings } from "bun:sqlite";
+import { type ActivityEvent, type ActivityEventInput, type ActivityOutcome } from "cursedbelt-core/activity/model";
+/**
+ * A read-only stream contributor: a SELECT projecting some other table into the
+ * union's eleven columns, in this order and with these names —
+ *
+ *   `source, seq, at, app, actor, action, kind, resource_id, outcome, note, data`
+ *
+ * `seq` is that table's own row id: it breaks ties within one `at`, and it is
+ * what makes the event id (`"<source>:<seq>"`) stable and unique across sources.
+ */
+export interface ActivitySource {
+    /** Short, stable, unique within the log — it prefixes every id it produces. */
+    name: string;
+    /** The projection. See the column contract above. */
+    sql: string;
+    /** Bound in order, before any filter parameter. */
+    params?: readonly SQLQueryBindings[];
+    /**
+     * A table this projection needs. When it does not exist the source is skipped
+     * for that call rather than throwing — see property 3 in the header.
+     */
+    requiresTable?: string;
+}
+/** Everything the stream can be narrowed by. Every field is optional; the empty
+ *  query is "the newest `limit` events". */
+export interface ActivityQuery {
+    /** ISO-8601, inclusive. */
+    since?: string;
+    /** ISO-8601, inclusive. */
+    until?: string;
+    /** Case-insensitive exact match on the account. */
+    actor?: string;
+    /** Exact, or a PREFIX when it ends in a dot: `"share."` matches `share.grant`. */
+    action?: string;
+    kind?: string;
+    resourceId?: string;
+    outcome?: ActivityOutcome;
+    /** Restrict to one contributor (`"log"`, `"share"`). */
+    source?: string;
+    /** Substring, over actor + action + note + resource id. */
+    q?: string;
+    /** Default 100, hard cap 1000. */
+    limit?: number;
+}
+export interface ActivityPage {
+    events: ActivityEvent[];
+    /** The limit actually applied, after defaulting and capping. */
+    limit: number;
+    /** There is at least one more row older than the last one returned. */
+    truncated: boolean;
+}
+/** One dimension of "what is in this result", for the filter UI. */
+export interface ActivityFacet {
+    value: string;
+    count: number;
+}
+export interface ActivityFacets {
+    actions: ActivityFacet[];
+    actors: ActivityFacet[];
+    kinds: ActivityFacet[];
+}
+export interface ActivityLogOptions {
+    db: Database;
+    /** The satellite this log speaks for. Fixed at construction, so a caller
+     *  cannot write an event under another app's name. */
+    app: string;
+    /** Read-only contributors merged into the stream. */
+    sources?: readonly ActivitySource[];
+    /** Injectable clock, ISO-8601. */
+    now?: () => string;
+}
+export interface ActivityLog {
+    /** The app this log speaks for. */
+    readonly app: string;
+    /** Append one event. Returns it as it will be read back. */
+    record(input: ActivityEventInput): ActivityEvent;
+    /** Newest first, bounded. */
+    query(query?: ActivityQuery): ActivityPage;
+    /** How many events match — the unbounded count behind a bounded page. */
+    count(query?: ActivityQuery): number;
+    /** What is in the result, per dimension, for a filter UI. */
+    facets(query?: ActivityQuery, limit?: number): ActivityFacets;
+    /** Which contributors are live right now (a source whose table is missing is
+     *  absent, which is what the read surface reports). */
+    sources(): string[];
+}
+export declare function createActivityLog(options: ActivityLogOptions): ActivityLog;

package/dist/server/activity/store.js

@@ -0,0 +1,178 @@
+import { isActivityAction, isActivityOutcome, } from "cursedbelt-core/activity/model";
+import { runMigrations } from "../migration/runner";
+import { ACTIVITY_EVENTS_TABLE, ACTIVITY_MIGRATIONS } from "./migrations";
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 1000;
+const MAX_FACET = 25;
+/** `%` and `_` are wildcards and `\` is the escape — a note containing any of
+ *  them must still search literally. */
+const likeContains = (value) => `%${value.replace(/[\\%_]/g, (ch) => `\\${ch}`)}%`;
+const toEvent = (row) => ({
+    id: `${row.source}:${row.seq}`,
+    source: row.source,
+    at: row.at,
+    app: row.app,
+    actor: row.actor,
+    action: row.action,
+    resource: row.kind === null || row.resource_id === null
+        ? null
+        : { app: row.app, kind: row.kind, id: row.resource_id },
+    outcome: isActivityOutcome(row.outcome) ? row.outcome : "ok",
+    note: row.note ?? "",
+    data: parseData(row.data),
+});
+/** A row whose `data` is unreadable must not take the page down with it — the
+ *  event still says who did what, which is the part that matters. */
+function parseData(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : { value: parsed };
+    }
+    catch {
+        return { unparsed: raw };
+    }
+}
+export function createActivityLog(options) {
+    const { db, app } = options;
+    const now = options.now ?? (() => new Date().toISOString());
+    const registered = options.sources ?? [];
+    runMigrations(db, ACTIVITY_MIGRATIONS);
+    const insert = db.query(`INSERT INTO ${ACTIVITY_EVENTS_TABLE}
+		   (at, app, actor, action, kind, resource_id, outcome, note, data)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const tableExists = (name) => !!db
+        .query("SELECT 1 AS ok FROM sqlite_master WHERE type = 'table' AND name = ?")
+        .get(name);
+    /** The contributors that can actually answer right now. */
+    const liveSources = () => registered.filter((source) => !source.requiresTable || tableExists(source.requiresTable));
+    const OWN_SELECT = `SELECT 'log' AS source, event_id AS seq, at, app, actor, action,
+	                           kind, resource_id, outcome, note, data
+	                      FROM ${ACTIVITY_EVENTS_TABLE}`;
+    /** The union, plus the WHERE the caller asked for, plus their parameters in
+     *  bind order (sources first — they are inside the FROM). */
+    const stream = (query) => {
+        const params = [];
+        const selects = [OWN_SELECT];
+        for (const source of liveSources()) {
+            if (query.source && query.source !== source.name)
+                continue;
+            selects.push(source.sql);
+            params.push(...(source.params ?? []));
+        }
+        const where = [];
+        if (query.source) {
+            where.push("source = ?");
+            params.push(query.source);
+        }
+        if (query.since) {
+            where.push("at >= ?");
+            params.push(query.since);
+        }
+        if (query.until) {
+            where.push("at <= ?");
+            params.push(query.until);
+        }
+        if (query.actor) {
+            where.push("LOWER(actor) = LOWER(?)");
+            params.push(query.actor);
+        }
+        if (query.action) {
+            if (query.action.endsWith(".")) {
+                where.push("action LIKE ? ESCAPE '\\'");
+                params.push(`${query.action.replace(/[\\%_]/g, (ch) => `\\${ch}`)}%`);
+            }
+            else {
+                where.push("action = ?");
+                params.push(query.action);
+            }
+        }
+        if (query.kind) {
+            where.push("kind = ?");
+            params.push(query.kind);
+        }
+        if (query.resourceId) {
+            where.push("resource_id = ?");
+            params.push(query.resourceId);
+        }
+        if (query.outcome) {
+            where.push("outcome = ?");
+            params.push(query.outcome);
+        }
+        if (query.q) {
+            where.push("(actor LIKE ? ESCAPE '\\' OR action LIKE ? ESCAPE '\\' OR note LIKE ? ESCAPE '\\' OR IFNULL(resource_id, '') LIKE ? ESCAPE '\\')");
+            const like = likeContains(query.q);
+            params.push(like, like, like, like);
+        }
+        // `query.source` naming a contributor that is not live leaves only the own
+        // select, filtered to a source it cannot be — an empty result, which is the
+        // honest answer rather than every row.
+        const sql = `SELECT * FROM (${selects.join("\n UNION ALL\n")}) AS stream${where.length ? ` WHERE ${where.join(" AND ")}` : ""}`;
+        return { sql, params };
+    };
+    return {
+        app,
+        record(input) {
+            if (!isActivityAction(input.action)) {
+                throw new Error(`activity: "${input.action}" is not an action — use lowercase subject.verb, e.g. "backup.delete"`);
+            }
+            const actor = input.actor?.trim();
+            if (!actor) {
+                // An event that cannot say who is a log line, not an audit trail.
+                throw new Error(`activity: ${input.action} has no actor`);
+            }
+            const at = input.at ?? now();
+            const outcome = input.outcome ?? "ok";
+            const data = input.data ? JSON.stringify(input.data) : null;
+            const info = insert.run(at, app, actor, input.action, input.resource?.kind ?? null, input.resource?.id ?? null, outcome, input.note ?? "", data);
+            return {
+                id: `log:${Number(info.lastInsertRowid)}`,
+                source: "log",
+                at,
+                app,
+                actor,
+                action: input.action,
+                resource: input.resource ? { app, ...input.resource } : null,
+                outcome,
+                note: input.note ?? "",
+                data: input.data ?? null,
+            };
+        },
+        query(query = {}) {
+            const limit = Math.min(MAX_LIMIT, Math.max(1, Math.floor(query.limit ?? DEFAULT_LIMIT)));
+            const { sql, params } = stream(query);
+            // One row past the limit, so "there is more" is a fact rather than a
+            // guess made from `rows.length === limit`.
+            const rows = db
+                .query(`${sql} ORDER BY at DESC, seq DESC LIMIT ?`)
+                .all(...params, limit + 1);
+            const truncated = rows.length > limit;
+            return { events: rows.slice(0, limit).map(toEvent), limit, truncated };
+        },
+        count(query = {}) {
+            const { sql, params } = stream(query);
+            const row = db.query(`SELECT COUNT(*) AS n FROM (${sql})`).get(...params);
+            return row?.n ?? 0;
+        },
+        facets(query = {}, limit = MAX_FACET) {
+            const { sql, params } = stream(query);
+            const capped = Math.min(MAX_FACET, Math.max(1, Math.floor(limit)));
+            const dimension = (column) => db
+                .query(`SELECT ${column} AS value, COUNT(*) AS count FROM (${sql})
+							  WHERE ${column} IS NOT NULL AND ${column} <> ''
+							  GROUP BY ${column} ORDER BY count DESC, value ASC LIMIT ?`)
+                .all(...params, capped).map((row) => ({ value: row.value, count: row.count }));
+            return {
+                actions: dimension("action"),
+                actors: dimension("actor"),
+                kinds: dimension("kind"),
+            };
+        },
+        sources() {
+            return ["log", ...liveSources().map((source) => source.name)];
+        },
+    };
+}

package/dist/server/app.d.ts

@@ -0,0 +1,56 @@
+import type { Database } from 'bun:sqlite';
+import type { Server, TLSOptions, WebSocketHandler } from 'bun';
+import { Hono } from 'hono';
+import type { CursedbeltEnv } from './context';
+import { type CorsOpts } from './middleware/corsAllowlist';
+import { type RateLimitOpts } from './middleware/rateLimit';
+import { type SecurityHeadersOpts } from './middleware/securityHeaders';
+export interface CreateAppOpts {
+    /** When provided, the request logger writes metrics/events to this DB. */
+    db?: Database;
+    /**
+     * CORS for a split deploy (SPA origin ≠ API origin). Pass `{ siteDomain }` /
+     * `{ origins }` (see {@link CorsOpts}) or `corsOptsFromEnv()` to read the
+     * conventional `CORS_SITE_DOMAIN` / `CORS_ORIGINS` env vars. Omit for a
+     * same-origin deploy. Mounted FIRST so every response — preflight, rate-limit
+     * 429, error envelope — carries the CORS headers a browser needs to read it.
+     */
+    cors?: CorsOpts;
+    /** Security-header options, or `false` to skip the security-headers middleware. */
+    security?: SecurityHeadersOpts | false;
+    /** Mount a global rate limiter. (Per-route limiters: use `createRateLimiter` directly.) */
+    rateLimit?: RateLimitOpts;
+    /**
+     * How many trusted reverse proxies sit in front of this app, for the client-IP
+     * rate-limit key. Default `0` — `x-forwarded-for` is caller-controlled, so
+     * believing it by default let anyone mint a fresh rate-limit bucket per
+     * request. Set to the real hop count you operate (nginx in front ⇒ `1`).
+     */
+    trustedProxyHops?: number;
+    /** Mount the default `GET /health` liveness route. Default: true. */
+    health?: boolean;
+}
+/**
+ * Build the configured cursedbelt Hono app: correlation id → (optional) CORS →
+ * security headers →
+ * (optional) rate limit → (optional) request logger, a default `/health`, and the
+ * canonical error-envelope `onError`. The caller mounts feature routers on the
+ * returned app (`app.route('/api/v1', notesRouter)`).
+ */
+export declare function createApp(opts?: CreateAppOpts): Hono<CursedbeltEnv>;
+export interface ServeBunOpts<T = unknown> {
+    /** Listen port. Default: 3000. */
+    port?: number;
+    /** Bind hostname (e.g. `'127.0.0.1'`). Default: Bun's default (all interfaces). */
+    hostname?: string;
+    /** WebSocket handler from the WS hub (task 28). Only set when the app upgrades. */
+    websocket?: WebSocketHandler<T>;
+    /** TLS options for HTTPS. */
+    tls?: TLSOptions;
+}
+/**
+ * Serve a Hono app on `Bun.serve` (`fetch: app.fetch`, zero adapter). Pass
+ * `websocket` only when the app actually calls `server.upgrade()` (task 28) — Bun
+ * rejects a `websocket` handler that is never used.
+ */
+export declare function serveBun<T = unknown>(app: Hono<CursedbeltEnv>, opts?: ServeBunOpts<T>): Server<T>;

package/dist/server/app.js

@@ -0,0 +1,45 @@
+import { Hono } from 'hono';
+import { correlationId } from './middleware/correlationId';
+import { corsAllowlist } from './middleware/corsAllowlist';
+import { errorEnvelope } from './middleware/errorEnvelope';
+import { createRateLimiter } from './middleware/rateLimit';
+import { requestLogger } from './middleware/requestLogger';
+import { securityHeaders } from './middleware/securityHeaders';
+/**
+ * Build the configured cursedbelt Hono app: correlation id → (optional) CORS →
+ * security headers →
+ * (optional) rate limit → (optional) request logger, a default `/health`, and the
+ * canonical error-envelope `onError`. The caller mounts feature routers on the
+ * returned app (`app.route('/api/v1', notesRouter)`).
+ */
+export function createApp(opts = {}) {
+    const app = new Hono();
+    app.use('*', correlationId());
+    if (opts.cors)
+        app.use('*', corsAllowlist(opts.cors));
+    if (opts.security !== false)
+        app.use('*', securityHeaders(opts.security ?? {}));
+    if (opts.rateLimit) {
+        app.use('*', createRateLimiter({ trustedProxyHops: opts.trustedProxyHops ?? 0, ...opts.rateLimit }));
+    }
+    if (opts.db)
+        app.use('*', requestLogger(opts.db));
+    if (opts.health !== false)
+        app.get('/health', (c) => c.json({ status: 'ok' }));
+    app.onError(errorEnvelope);
+    return app;
+}
+/**
+ * Serve a Hono app on `Bun.serve` (`fetch: app.fetch`, zero adapter). Pass
+ * `websocket` only when the app actually calls `server.upgrade()` (task 28) — Bun
+ * rejects a `websocket` handler that is never used.
+ */
+export function serveBun(app, opts = {}) {
+    const port = opts.port ?? 3000;
+    const { hostname, tls, websocket } = opts;
+    // Two concrete call shapes (not a spread) so Bun.serve picks the right overload.
+    if (websocket) {
+        return Bun.serve({ port, hostname, fetch: app.fetch, tls, websocket });
+    }
+    return Bun.serve({ port, hostname, fetch: app.fetch, tls });
+}

package/dist/server/audit/index.d.ts

@@ -0,0 +1,2 @@
+export { AUDIT_LOG_MIGRATIONS } from './migrations';
+export { auditStateAt, auditStateAtVersion, auditStep, createSqliteAuditSink } from './sqliteSink';

package/dist/server/audit/index.js

@@ -0,0 +1,2 @@
+export { AUDIT_LOG_MIGRATIONS } from './migrations';
+export { auditStateAt, auditStateAtVersion, auditStep, createSqliteAuditSink } from './sqliteSink';

package/dist/server/audit/migrations.d.ts

@@ -0,0 +1,2 @@
+import type { Migration } from '../migration/types';
+export declare const AUDIT_LOG_MIGRATIONS: readonly Migration[];