cursedbelt-server 1.0.0

package/dist/server/media-bun/streaming.js

@@ -0,0 +1,237 @@
+// Pure ffmpeg/ffprobe argument builders + parsers for the STREAMING pipeline: faststart
+// remux, the HLS adaptive-bitrate ladder, scrub-preview sprite sheets + WebVTT, poster
+// frames, and a codec-aware probe. No Bun.spawn, no I/O — every argv + parser here is unit
+// tested without ffmpeg present; `video.ts` is the thin spawn shell that runs them
+// (probeVideoStream / runFfmpegProgress / extractFrameJpeg).
+//
+// Companion to `ffmpeg.ts` (which owns the trim/thumbnail builders + basic probe): these
+// are the additional pieces a streaming server (cursedalchemy's media pipeline, the
+// binary-server) needs to turn an upload into web-seekable, adaptively-streamable output.
+//
+// ffmpeg/ffprobe are expected on PATH (or via FFMPEG_PATH/FFPROBE_PATH) — never an npm dep.
+import path from 'node:path';
+// ── Web-safe encode primitives (one source of truth for "decodes everywhere") ──────────
+// libx264 defaults to HIGH profile, whose CABAC/8x8-transform features some hardware
+// decoders mis-handle (solid GREEN frame); Main profile drops those at negligible cost and
+// is universally supported. yuv420p is the only chroma layout browsers decode reliably.
+export const h264WebVideoArgs = (crf) => [
+    '-c:v',
+    'libx264',
+    '-preset',
+    'veryfast',
+    '-crf',
+    crf,
+    '-profile:v',
+    'main',
+    '-pix_fmt',
+    'yuv420p',
+];
+export const aacWebAudioArgs = (bitrate) => ['-c:a', 'aac', '-b:a', bitrate];
+/** Move the moov atom to the front so playback can start before the full download. */
+export const FASTSTART = ['-movflags', '+faststart'];
+/** Cap the long edge at ~1080p, keep aspect, force even dimensions (yuv420p needs even). */
+export const LIBRARY_SCALE = "scale='min(1920,iw)':'-2'";
+/** Higher quality than ephemeral Moments (28) — this output is retained. */
+export const LIBRARY_CRF = '23';
+export const EMPTY_PROBE = {
+    duration: 0,
+    width: 0,
+    height: 0,
+    vcodec: '',
+    acodec: '',
+    pixfmt: '',
+    hasAudio: false,
+};
+/** ffprobe argv: one call for everything the pipeline decides on (codecs + dims + duration). */
+export const buildStreamProbeArgs = (filePath) => [
+    '-v',
+    'error',
+    '-show_entries',
+    'format=duration:stream=index,codec_type,codec_name,width,height,pix_fmt',
+    '-of',
+    'json',
+    filePath,
+];
+/** Parse the `buildStreamProbeArgs` JSON into a {@link VideoProbe}. */
+export const parseStreamProbe = (json) => {
+    const streams = Array.isArray(json?.streams) ? json.streams : [];
+    const v = streams.find((s) => s.codec_type === 'video') ?? {};
+    const a = streams.find((s) => s.codec_type === 'audio');
+    return {
+        duration: Number(json?.format?.duration) || 0,
+        width: Number(v.width) || 0,
+        height: Number(v.height) || 0,
+        vcodec: String(v.codec_name ?? ''),
+        acodec: String(a?.codec_name ?? ''),
+        pixfmt: String(v.pix_fmt ?? ''),
+        hasAudio: Boolean(a),
+    };
+};
+// ── Faststart: stream-copy a source that's already web-safe (fast, lossless — just move the
+//    moov atom), else re-encode to the web-safe ladder. ─────────────────────────────────
+export const canStreamCopy = (p, maxWidth = 1920) => p.vcodec === 'h264' &&
+    p.pixfmt === 'yuv420p' &&
+    (p.acodec === '' || p.acodec === 'aac') &&
+    p.width > 0 &&
+    p.width <= maxWidth;
+export const faststartArgs = (inPath, outPath, opts) => {
+    if (opts.copy)
+        return ['-i', inPath, '-c', 'copy', ...FASTSTART, outPath];
+    const crf = String(opts.crf ?? Number(LIBRARY_CRF));
+    return [
+        '-i',
+        inPath,
+        '-vf',
+        LIBRARY_SCALE,
+        ...h264WebVideoArgs(crf),
+        ...aacWebAudioArgs('160k'),
+        ...FASTSTART,
+        outPath,
+    ];
+};
+/**
+ * Parse one ffmpeg `-progress pipe:1` line into elapsed microseconds, or null if the line
+ * carries no out_time. `runFfmpegProgress` turns a stream of these into a 0..99 percent.
+ */
+export const parseProgressMicros = (line) => {
+    const m = /^out_time_us=(\d+)/.exec(line) ?? /^out_time_ms=(\d+)/.exec(line);
+    if (!m)
+        return null;
+    return line.startsWith('out_time_ms') ? Number(m[1]) * 1000 : Number(m[1]);
+};
+// ── HLS adaptive-bitrate ladder ─────────────────────────────────────────────────────────
+// Per-rung video bitrate cap + buffer + audio rate. One source of truth for rung tuning.
+const LADDER_PRESETS = {
+    360: { maxrate: '856k', bufsize: '1200k', abr: '96k' },
+    480: { maxrate: '1400k', bufsize: '2100k', abr: '128k' },
+    720: { maxrate: '2800k', bufsize: '4200k', abr: '128k' },
+    1080: { maxrate: '5000k', bufsize: '7500k', abr: '192k' },
+    1440: { maxrate: '8000k', bufsize: '12000k', abr: '192k' },
+    2160: { maxrate: '16000k', bufsize: '24000k', abr: '192k' },
+};
+/** Drop unknown/too-tall rungs (never upscale); always keep at least the source-or-720 rung. */
+export const resolveLadder = (heights, sourceHeight) => {
+    const valid = heights
+        .filter((h) => LADDER_PRESETS[h])
+        .filter((h) => sourceHeight <= 0 || h <= sourceHeight);
+    const ladder = valid.length ? valid : [Math.min(720, sourceHeight || 720)];
+    return [...new Set(ladder)].sort((a, b) => a - b);
+};
+/**
+ * Build the HLS multi-rendition transcode. `outDir/<height>/` subdirs must already exist.
+ * Emits master.m3u8 + per-rung playlist.m3u8 + mpegts segments, variants NAMED by height
+ * so storage keys read `…/720/seg_00001.ts` rather than an opaque index.
+ */
+export const hlsLadderArgs = (inPath, outDir, opts) => {
+    const hs = opts.heights.length ? opts.heights : [720];
+    const n = hs.length;
+    const filter = `[0:v]split=${n}${hs.map((_, i) => `[v${i}]`).join('')};` +
+        hs.map((h, i) => `[v${i}]scale=-2:${h}[vo${i}]`).join(';');
+    const args = ['-i', inPath, '-filter_complex', filter];
+    hs.forEach((h, i) => {
+        const p = LADDER_PRESETS[h] ?? LADDER_PRESETS[720];
+        args.push('-map', `[vo${i}]`, `-c:v:${i}`, 'libx264', '-preset', 'veryfast', `-crf:v:${i}`, String(opts.crf), `-profile:v:${i}`, 'main', `-maxrate:v:${i}`, p.maxrate, `-bufsize:v:${i}`, p.bufsize);
+    });
+    args.push('-pix_fmt', 'yuv420p');
+    if (opts.hasAudio) {
+        hs.forEach((h, i) => {
+            const p = LADDER_PRESETS[h] ?? LADDER_PRESETS[720];
+            args.push('-map', 'a:0', `-c:a:${i}`, 'aac', `-b:a:${i}`, p.abr, '-ac', '2');
+        });
+    }
+    const varMap = hs
+        .map((h, i) => (opts.hasAudio ? `v:${i},a:${i},name:${h}` : `v:${i},name:${h}`))
+        .join(' ');
+    args.push('-f', 'hls', '-hls_time', '4', '-hls_playlist_type', 'vod', '-hls_segment_type', 'mpegts', ...(opts.keyInfoFile ? ['-hls_key_info_file', opts.keyInfoFile] : []), '-master_pl_name', 'master.m3u8', '-hls_segment_filename', path.join(outDir, '%v', 'seg_%05d.ts'), '-var_stream_map', varMap, path.join(outDir, '%v', 'playlist.m3u8'));
+    return args;
+};
+/** Poster: a frame `atSeconds` in (default ~1s, to skip black intros), scaled to the library
+ *  width, as JPEG. Pass a smaller seek (or 0) for very short clips — seeking past EOF yields no
+ *  frame and the extract fails, so callers that know the duration should clamp `atSeconds`. */
+export const posterArgs = (inPath, outPath, atSeconds = 1) => [
+    '-ss',
+    String(Math.max(0, atSeconds)),
+    '-i',
+    inPath,
+    '-vframes',
+    '1',
+    '-vf',
+    LIBRARY_SCALE,
+    outPath,
+];
+/** Decode a still image to a width-capped JPEG thumbnail. The fallback for formats sharp's
+ *  prebuilt binary can't decode — notably HEIC/HEVC (iPhone photos), which the licensed-out
+ *  libheif build rejects but ffmpeg's hevc decoder handles. `-update 1` writes the single frame
+ *  to a fixed filename (no image-sequence pattern); height rounds to even (`-2`) for the encoder. */
+export const imageThumbnailArgs = (inPath, outPath, maxWidth = 512) => [
+    '-i',
+    inPath,
+    '-vf',
+    `scale='min(${maxWidth},iw)':-2`,
+    '-frames:v',
+    '1',
+    '-update',
+    '1',
+    outPath,
+];
+/** ffmpeg argv to grab one scaled JPEG frame at `atSeconds` on stdout (`-ss` before `-i`
+ *  fast-seeks — instant on a faststart file). The spawn runner reads pipe:1. */
+export const buildFrameJpegArgs = (filePath, atSeconds, maxWidth = 240) => [
+    '-ss',
+    String(Math.max(0, atSeconds)),
+    '-i',
+    filePath,
+    '-frames:v',
+    '1',
+    '-vf',
+    `scale=${maxWidth}:-2`,
+    '-f',
+    'mjpeg',
+    'pipe:1',
+];
+// ── Scrub-preview sprite sheet + WebVTT (YouTube-style hover/drag thumbnails) ───────────
+const SPRITE_THUMB_WIDTH = 160;
+const SPRITE_MAX_TILES = 144; // a single ~12×12 sheet; widen the interval past this
+/** Sheet geometry: sample every `interval`s, widening it so a long video still fits one sheet. */
+export const planSprite = (duration, interval, srcW, srcH) => {
+    const dur = Math.max(1, duration);
+    const effInterval = Math.max(1, interval, Math.ceil(dur / SPRITE_MAX_TILES));
+    const count = Math.max(1, Math.min(SPRITE_MAX_TILES, Math.ceil(dur / effInterval)));
+    const cols = Math.ceil(Math.sqrt(count));
+    const rows = Math.ceil(count / cols);
+    const thumbW = SPRITE_THUMB_WIDTH;
+    const thumbH = srcW > 0 ? Math.max(2, Math.round((thumbW * srcH) / srcW / 2) * 2) : 90;
+    return { effInterval, count, cols, rows, thumbW, thumbH };
+};
+export const spriteArgs = (inPath, outPath, plan) => [
+    '-i',
+    inPath,
+    '-vf',
+    `fps=1/${plan.effInterval},scale=${plan.thumbW}:-2,tile=${plan.cols}x${plan.rows}`,
+    '-frames:v',
+    '1',
+    '-q:v',
+    '5',
+    outPath,
+];
+const vttTime = (s) => {
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const sec = s % 60;
+    return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}:${sec.toFixed(3).padStart(6, '0')}`;
+};
+/**
+ * WebVTT thumbnail track: one cue per tile pointing at a `#xywh` media fragment of the sheet.
+ * The sprite URL is relative (default "sprites.jpg") so it resolves against the VTT's own route.
+ */
+export const buildSpriteVtt = (plan, spriteName = 'sprites.jpg') => {
+    let out = 'WEBVTT\n\n';
+    for (let i = 0; i < plan.count; i++) {
+        const start = i * plan.effInterval;
+        const end = (i + 1) * plan.effInterval;
+        const x = (i % plan.cols) * plan.thumbW;
+        const y = Math.floor(i / plan.cols) * plan.thumbH;
+        out += `${vttTime(start)} --> ${vttTime(end)}\n${spriteName}#xywh=${x},${y},${plan.thumbW},${plan.thumbH}\n\n`;
+    }
+    return out;
+};

package/dist/server/media-bun/video.d.ts

@@ -0,0 +1,35 @@
+import { type VideoProgressEvent, type VideoTrimSpec } from 'cursedbelt-core/media';
+import { type ProbeResult } from 'cursedbelt-core/media/ffmpeg';
+import { type VideoProbe } from './streaming';
+/** Is ffmpeg runnable? Cheap probe used to skip server media ops / tests cleanly. */
+export declare function isFfmpegAvailable(bin?: string): Promise<boolean>;
+/** Is ffprobe runnable? */
+export declare function isFfprobeAvailable(): Promise<boolean>;
+/**
+ * Trim `[startSeconds, endSeconds]` from `inputPath` into `outputPath`, re-encoding to
+ * the requested format/quality. `onProgress` receives `encode` events (parsed from
+ * ffmpeg stderr) and a final `done`; on a non-zero exit it emits `error` and throws.
+ */
+export declare function trimVideo(spec: VideoTrimSpec, onProgress?: (event: VideoProgressEvent) => void): Promise<void>;
+/** Probe a media file's primary video dimensions + duration + container format. */
+export declare function probeMedia(inputPath: string): Promise<ProbeResult>;
+/** Extract a single frame at `atSeconds` from `inputPath` and write it to `output`. */
+export declare function extractThumbnail(inputPath: string, atSeconds: number, output: string): Promise<void>;
+/**
+ * Codec-aware probe for the streaming pipeline (codecs + pixfmt + audio, so a caller can
+ * decide whether to stream-copy). Best-effort: returns {@link EMPTY_PROBE} on any failure —
+ * the pipeline stays usable (a node is always playable as raw range meanwhile).
+ */
+export declare function probeVideoStream(inputPath: string): Promise<VideoProbe>;
+/**
+ * Run an ffmpeg transcode while parsing its `-progress pipe:1` stream into a 0..99 percent
+ * (so a slow re-encode reports live progress). `durationSec` is the source duration; 0 ⇒ no
+ * percent. `args` should NOT include the leading `ffmpeg`/`-y`. Resolves true on success;
+ * on failure it passes the trailing stderr to `onError` (the app logs) and resolves false.
+ */
+export declare function runFfmpegProgress(args: string[], durationSec: number, onProgress?: (pct: number) => void, onError?: (stderrTail: string) => void): Promise<boolean>;
+/**
+ * On-demand single JPEG frame at `atSeconds` (scaled to `maxWidth`) as bytes, or null on
+ * failure. `-ss` before `-i` fast-seeks — instant on a faststart file.
+ */
+export declare function extractFrameJpeg(filePath: string, atSeconds: number, maxWidth?: number): Promise<Uint8Array | null>;

package/dist/server/media-bun/video.js

@@ -0,0 +1,181 @@
+// Video trim / probe / thumbnail via native ffmpeg + ffprobe, spawned with Bun.spawn.
+// All argv construction + output parsing lives in the pure `ffmpeg.ts` (tested without
+// ffmpeg); this file is the thin process shell. The binaries must be on PATH, or set
+// `FFMPEG_PATH` / `FFPROBE_PATH`. Replaces ca's hand-rolled spawn boilerplate.
+import { assertValidVideoTrimSpec, } from 'cursedbelt-core/media';
+import { buildProbeArgs, buildThumbnailArgs, buildTrimArgs, parseFfmpegProgress, parseFfprobe, } from 'cursedbelt-core/media/ffmpeg';
+import { buildFrameJpegArgs, buildStreamProbeArgs, EMPTY_PROBE, parseProgressMicros, parseStreamProbe, } from './streaming';
+const FFMPEG = process.env.FFMPEG_PATH || 'ffmpeg';
+const FFPROBE = process.env.FFPROBE_PATH || 'ffprobe';
+/** Is ffmpeg runnable? Cheap probe used to skip server media ops / tests cleanly. */
+export async function isFfmpegAvailable(bin = FFMPEG) {
+    try {
+        const proc = Bun.spawn([bin, '-version'], { stdout: 'ignore', stderr: 'ignore' });
+        await proc.exited;
+        return proc.exitCode === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Is ffprobe runnable? */
+export function isFfprobeAvailable() {
+    return isFfmpegAvailable(FFPROBE);
+}
+/** Drain a stderr stream line-by-line (ffmpeg uses \r to update progress in place). */
+async function readProgress(stream, totalSeconds, onProgress) {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let tail = '';
+    for await (const chunk of stream) {
+        const text = decoder.decode(chunk, { stream: true });
+        buffer += text;
+        tail = (tail + text).slice(-4000); // keep a bounded tail for an error message
+        const segments = buffer.split(/[\r\n]/);
+        buffer = segments.pop() ?? '';
+        if (onProgress) {
+            for (const seg of segments) {
+                const ev = parseFfmpegProgress(seg, totalSeconds);
+                if (ev)
+                    onProgress(ev);
+            }
+        }
+    }
+    return tail;
+}
+/**
+ * Trim `[startSeconds, endSeconds]` from `inputPath` into `outputPath`, re-encoding to
+ * the requested format/quality. `onProgress` receives `encode` events (parsed from
+ * ffmpeg stderr) and a final `done`; on a non-zero exit it emits `error` and throws.
+ */
+export async function trimVideo(spec, onProgress) {
+    assertValidVideoTrimSpec(spec);
+    const total = spec.endSeconds - spec.startSeconds;
+    onProgress?.({ phase: 'encode', progressPercent: 0 });
+    const proc = Bun.spawn([FFMPEG, ...buildTrimArgs(spec)], { stdout: 'ignore', stderr: 'pipe' });
+    const tail = await readProgress(proc.stderr, total, onProgress);
+    await proc.exited;
+    if (proc.exitCode !== 0) {
+        const message = `ffmpeg trim failed (exit ${proc.exitCode}): ${tail
+            .trim()
+            .split(/[\r\n]/)
+            .pop() ?? ''}`;
+        onProgress?.({ phase: 'error', error: message });
+        throw new Error(message);
+    }
+    onProgress?.({ phase: 'done', progressPercent: 100 });
+}
+/** Probe a media file's primary video dimensions + duration + container format. */
+export async function probeMedia(inputPath) {
+    const proc = Bun.spawn([FFPROBE, ...buildProbeArgs(inputPath)], {
+        stdout: 'pipe',
+        stderr: 'pipe',
+    });
+    const stdout = await new Response(proc.stdout).text();
+    await proc.exited;
+    if (proc.exitCode !== 0) {
+        throw new Error(`ffprobe failed (exit ${proc.exitCode}) for ${inputPath}`);
+    }
+    try {
+        return parseFfprobe(JSON.parse(stdout));
+    }
+    catch (err) {
+        throw new Error(`ffprobe returned unparseable JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Extract a single frame at `atSeconds` from `inputPath` and write it to `output`. */
+export async function extractThumbnail(inputPath, atSeconds, output) {
+    const proc = Bun.spawn([FFMPEG, ...buildThumbnailArgs(inputPath, atSeconds, output)], {
+        stdout: 'ignore',
+        stderr: 'pipe',
+    });
+    const tail = await new Response(proc.stderr).text();
+    await proc.exited;
+    if (proc.exitCode !== 0) {
+        throw new Error(`ffmpeg thumbnail failed (exit ${proc.exitCode}): ${tail
+            .trim()
+            .split(/[\r\n]/)
+            .pop() ?? ''}`);
+    }
+}
+// ── Streaming-pipeline spawn runners (companions to streaming.ts's pure builders) ───────
+/**
+ * Codec-aware probe for the streaming pipeline (codecs + pixfmt + audio, so a caller can
+ * decide whether to stream-copy). Best-effort: returns {@link EMPTY_PROBE} on any failure —
+ * the pipeline stays usable (a node is always playable as raw range meanwhile).
+ */
+export async function probeVideoStream(inputPath) {
+    try {
+        const proc = Bun.spawn([FFPROBE, ...buildStreamProbeArgs(inputPath)], {
+            stdout: 'pipe',
+            stderr: 'ignore',
+        });
+        const stdout = await new Response(proc.stdout).text();
+        await proc.exited;
+        if (proc.exitCode !== 0)
+            return EMPTY_PROBE;
+        return parseStreamProbe(JSON.parse(stdout));
+    }
+    catch {
+        return EMPTY_PROBE;
+    }
+}
+/**
+ * Run an ffmpeg transcode while parsing its `-progress pipe:1` stream into a 0..99 percent
+ * (so a slow re-encode reports live progress). `durationSec` is the source duration; 0 ⇒ no
+ * percent. `args` should NOT include the leading `ffmpeg`/`-y`. Resolves true on success;
+ * on failure it passes the trailing stderr to `onError` (the app logs) and resolves false.
+ */
+export async function runFfmpegProgress(args, durationSec, onProgress, onError) {
+    const proc = Bun.spawn([FFMPEG, '-y', '-progress', 'pipe:1', '-nostats', ...args], {
+        stdout: 'pipe',
+        stderr: 'pipe',
+    });
+    if (durationSec > 0 && onProgress && proc.stdout) {
+        void (async () => {
+            const decoder = new TextDecoder();
+            let buf = '';
+            try {
+                for await (const chunk of proc.stdout) {
+                    buf += decoder.decode(chunk, { stream: true });
+                    const lines = buf.split('\n');
+                    buf = lines.pop() ?? '';
+                    for (const line of lines) {
+                        const us = parseProgressMicros(line);
+                        if (us === null)
+                            continue;
+                        onProgress(Math.max(0, Math.min(99, Math.round((us / 1e6 / durationSec) * 100))));
+                    }
+                }
+            }
+            catch {
+                /* progress is best-effort */
+            }
+        })();
+    }
+    await proc.exited;
+    if (proc.exitCode !== 0) {
+        if (onError)
+            onError((await new Response(proc.stderr).text()).slice(-600));
+        return false;
+    }
+    return true;
+}
+/**
+ * On-demand single JPEG frame at `atSeconds` (scaled to `maxWidth`) as bytes, or null on
+ * failure. `-ss` before `-i` fast-seeks — instant on a faststart file.
+ */
+export async function extractFrameJpeg(filePath, atSeconds, maxWidth = 240) {
+    try {
+        const proc = Bun.spawn([FFMPEG, '-y', ...buildFrameJpegArgs(filePath, atSeconds, maxWidth)], {
+            stdout: 'pipe',
+            stderr: 'ignore',
+        });
+        const bytes = new Uint8Array(await new Response(proc.stdout).arrayBuffer());
+        await proc.exited;
+        return proc.exitCode === 0 && bytes.length > 0 ? bytes : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server/metrics/metricsBuffer.d.ts

@@ -0,0 +1,39 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * In-memory, batched writer for `request_metrics`. To keep request latency
+ * untouched we never write per request: rows land in a buffer and a single batched
+ * transaction flushes them on an interval (and eagerly when the buffer is large).
+ *
+ * This is the reusable successor to ca's `metricsBuffer` module, retargeted at the
+ * task-22 `request_metrics` schema (no `created_at` column — `ts` is the epoch-ms
+ * timestamp). The flush timer is `unref()`'d so it never keeps the process alive.
+ */
+export interface MetricRow {
+    /** Epoch ms. */
+    ts: number;
+    method: string | null;
+    /** Normalized route label (see `normalizeRoute`). */
+    route: string | null;
+    status: number | null;
+    durationMs: number | null;
+    bytesOut: number | null;
+    userId: string | null;
+}
+export interface MetricsBufferOptions {
+    db: Database;
+    /** Flush cadence in ms. Default: 1500. */
+    flushIntervalMs?: number;
+    /** Eager-flush threshold — caps memory if a flush stalls. Default: 5000. */
+    maxSize?: number;
+}
+export interface MetricsBuffer {
+    /** Enqueue one request's metrics (non-blocking; flushed in batches). */
+    record(row: MetricRow): void;
+    /** Force-flush the buffer now (also used on shutdown + in tests). */
+    flush(): void;
+    /** Stop the flush timer and drain whatever remains. */
+    stop(): void;
+    /** Rows currently buffered (not yet flushed). */
+    readonly size: number;
+}
+export declare function createMetricsBuffer(opts: MetricsBufferOptions): MetricsBuffer;

package/dist/server/metrics/metricsBuffer.js

@@ -0,0 +1,36 @@
+export function createMetricsBuffer(opts) {
+    const { db, flushIntervalMs = 1500, maxSize = 5000 } = opts;
+    let buffer = [];
+    const insert = db.prepare(`INSERT INTO request_metrics (id, ts, method, route, status, duration_ms, bytes_out, user_id)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+    const insertMany = db.transaction((rows) => {
+        for (const r of rows) {
+            insert.run(crypto.randomUUID(), r.ts, r.method, r.route, r.status, r.durationMs, r.bytesOut, r.userId);
+        }
+    });
+    const flush = () => {
+        if (buffer.length === 0)
+            return;
+        const batch = buffer;
+        buffer = [];
+        insertMany(batch);
+    };
+    const timer = setInterval(flush, flushIntervalMs);
+    // Never let the metrics flusher hold the event loop / process open.
+    timer.unref?.();
+    return {
+        record(row) {
+            buffer.push(row);
+            if (buffer.length >= maxSize)
+                flush();
+        },
+        flush,
+        stop() {
+            clearInterval(timer);
+            flush();
+        },
+        get size() {
+            return buffer.length;
+        },
+    };
+}

package/dist/server/metrics/normalizeRoute.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from 'hono';
+export declare function normalizeRoute(c: Context): {
+    method: string;
+    route: string;
+};

package/dist/server/metrics/normalizeRoute.js

@@ -0,0 +1,58 @@
+/**
+ * Turn a request into a stable, low-cardinality route label for metric aggregation
+ * (e.g. `/api/v1/notes/:id`). The method is tracked separately.
+ *
+ * Two wrinkles, same as the old Express normalizer:
+ *   1. ctgr GET-tunnelled mutations match the `/ctgr<xx>` twin route — we map them
+ *      back to the real verb + path so a POST and its ctgr twin aggregate together.
+ *   2. Unmatched requests (404s, static, the SPA fallback) have no matched route
+ *      pattern, so we collapse dynamic-looking segments to avoid unbounded
+ *      cardinality blowing up the metrics table.
+ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const LONG_HEX_RE = /^[0-9a-f]{16,}$/i;
+// The ctgr twin URL is `/ctgr<last-2-of-method><url>`, so the two-letter suffix
+// recovers the original verb (POST→st, PUT→ut, PATCH→ch, DELETE→te).
+const CTGR_METHOD = { st: 'POST', ut: 'PUT', ch: 'PATCH', te: 'DELETE' };
+function collapseSegment(seg) {
+    if (!seg)
+        return seg;
+    if (/^\d+$/.test(seg))
+        return ':id';
+    if (UUID_RE.test(seg))
+        return ':id';
+    if (LONG_HEX_RE.test(seg))
+        return ':id';
+    // Long opaque tokens (encoded paths, blobs) collapse so they don't explode route
+    // cardinality. Plain words stay as-is.
+    if (seg.length >= 24)
+        return ':id';
+    return seg;
+}
+function collapsePath(path) {
+    const parts = path.split('/').filter(Boolean).map(collapseSegment);
+    return `/${parts.join('/')}`;
+}
+export function normalizeRoute(c) {
+    let method = c.req.method;
+    // Hono's matched route pattern (with :params) is the ideal label. A wildcard
+    // (`/*`, `*`) or empty pattern means "no real match" → collapse the raw path.
+    // `c.req.routePath` THROWS when nothing matched (e.g. a 404 / the SPA fallback),
+    // so guard it — an unmatched request must still produce a metrics label.
+    let matched;
+    try {
+        matched = c.req.routePath;
+    }
+    catch {
+        matched = undefined;
+    }
+    let route = matched && !matched.includes('*') ? matched : collapsePath(c.req.path.split('?')[0]) || '/';
+    // Map a ctgr GET-twin back to its real verb + url:
+    //   /api/ctgrch/notes/:id → PATCH /api/notes/:id
+    const ctgr = route.match(/\/ctgr([a-z]{2})(?=\/|$)/i);
+    if (ctgr) {
+        method = CTGR_METHOD[ctgr[1].toLowerCase()] ?? method;
+        route = route.replace(/\/ctgr[a-z]{2}/i, '') || '/';
+    }
+    return { method, route };
+}

package/dist/server/middleware/correlationId.d.ts

@@ -0,0 +1,9 @@
+import type { MiddlewareHandler } from 'hono';
+import type { CursedbeltEnv } from '../context';
+/**
+ * Assign every request a correlation id: reuse a safe inbound `x-correlation-id`
+ * (so a trace survives the proxy hop), else mint a `crypto.randomUUID()`. Stored on
+ * `c.set('correlationId', id)` for downstream middleware (request logger, error
+ * envelope) and echoed on the response header. Mount this FIRST.
+ */
+export declare function correlationId(): MiddlewareHandler<CursedbeltEnv>;

package/dist/server/middleware/correlationId.js

@@ -0,0 +1,20 @@
+const HEADER = 'x-correlation-id';
+// Accept a client-supplied id only if it is a sane, header-safe token (no CRLF /
+// control chars / unbounded length) — otherwise mint a fresh one. This both
+// preserves trace ids across a proxy hop and blocks response-header injection.
+const SAFE_ID = /^[A-Za-z0-9._:-]{1,200}$/;
+/**
+ * Assign every request a correlation id: reuse a safe inbound `x-correlation-id`
+ * (so a trace survives the proxy hop), else mint a `crypto.randomUUID()`. Stored on
+ * `c.set('correlationId', id)` for downstream middleware (request logger, error
+ * envelope) and echoed on the response header. Mount this FIRST.
+ */
+export function correlationId() {
+    return async (c, next) => {
+        const inbound = c.req.header(HEADER);
+        const id = inbound && SAFE_ID.test(inbound) ? inbound : crypto.randomUUID();
+        c.set('correlationId', id);
+        c.header(HEADER, id);
+        await next();
+    };
+}

package/dist/server/middleware/corsAllowlist.d.ts

@@ -0,0 +1,38 @@
+import { type OriginRule } from 'cwip/http';
+import type { MiddlewareHandler } from 'hono';
+/**
+ * Cross-app CORS for the split deploy shape every cursedbelt app shares (SPA on
+ * one origin, API on another — e.g. `example.com` → `api.example.com`), built on
+ * Hono's `cors` + cwip's `compileOriginMatcher` rather than a per-app allow-list
+ * reimplementation.
+ *
+ * The one-line configuration is `siteDomain`: it allows the https apex AND every
+ * subdomain (`siteOriginRules`), so standing up a new subdomain can never break
+ * CORS again. `origins` adds exact origins / `*.domain` wildcards / RegExps on
+ * top (dev Vite ports, a partner origin). Responses to allowed origins echo the
+ * origin with `Access-Control-Allow-Credentials: true` (cookie-auth apps);
+ * disallowed origins get NO CORS headers, which is the browser-visible rejection.
+ */
+export interface CorsOpts {
+    /**
+     * The site's apex domain (`'example.com'`) — allows `https://example.com` and
+     * `https://<any-subdomain>.example.com` in one rule.
+     */
+    siteDomain?: string;
+    /** Additional origin rules: exact, `*.domain.tld` wildcard, or RegExp. */
+    origins?: OriginRule[];
+    /** Send `Access-Control-Allow-Credentials: true` (default `true` — cookie auth). */
+    credentials?: boolean;
+    /** Called with each rejected `Origin` (for logging/metrics). */
+    onReject?: (origin: string) => void;
+}
+/** Build the Hono middleware from {@link CorsOpts}. Compiles the matcher once. */
+export declare const corsAllowlist: (opts: CorsOpts) => MiddlewareHandler;
+/**
+ * Resolve {@link CorsOpts} from the conventional env vars, `undefined` when
+ * neither is set (same-origin deploy — no CORS middleware needed):
+ *  - `CORS_SITE_DOMAIN=example.com` — the systemic knob: apex + every subdomain.
+ *  - `CORS_ORIGINS=https://a.com,*.b.com` — exact/wildcard extras (or the whole
+ *    list, for apps that predate `CORS_SITE_DOMAIN`).
+ */
+export declare const corsOptsFromEnv: (env?: Record<string, string | undefined>) => CorsOpts | undefined;