cursedbelt-server 1.0.0

package/src/server/app.spec.ts

@@ -0,0 +1,243 @@
+import { Database } from 'bun:sqlite';
+import { afterEach, describe, expect, test } from 'bun:test';
+import { Hono } from 'hono';
+import { createApp, serveBun } from './app';
+import type { CursedbeltEnv } from './context';
+import { ApiError } from './errors';
+import { createMetricsBuffer } from './metrics/metricsBuffer';
+import { correlationId } from './middleware/correlationId';
+import { errorEnvelope } from './middleware/errorEnvelope';
+import { createRateLimiter } from './middleware/rateLimit';
+import { requestLogger } from './middleware/requestLogger';
+import { securityHeaders } from './middleware/securityHeaders';
+
+const REQ = (path: string, init?: RequestInit) => new Request(`http://localhost${path}`, init);
+
+describe('createApp', () => {
+  test('GET /health returns 200', async () => {
+    const app = createApp();
+    const res = await app.fetch(REQ('/health'));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ status: 'ok' });
+  });
+
+  test('health route can be disabled', async () => {
+    const app = createApp({ health: false });
+    expect((await app.fetch(REQ('/health'))).status).toBe(404);
+  });
+
+  test('mounts feature routers under a prefix', async () => {
+    const app = createApp();
+    const notes = new Hono().get('/notes', (c) => c.json([{ id: 'n1' }]));
+    app.route('/api/v1', notes);
+    const res = await app.fetch(REQ('/api/v1/notes'));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([{ id: 'n1' }]);
+  });
+
+  test('stamps security + correlation headers on every response', async () => {
+    const app = createApp();
+    const res = await app.fetch(REQ('/health'));
+    expect(res.headers.get('x-content-type-options')).toBe('nosniff');
+    expect(res.headers.get('x-frame-options')).toBe('DENY');
+    expect(res.headers.get('content-security-policy')).toContain("default-src 'self'");
+    expect(res.headers.get('x-correlation-id')).toBeTruthy();
+  });
+});
+
+describe('correlationId()', () => {
+  test('mints an id and echoes it on the response', async () => {
+    const app = new Hono<CursedbeltEnv>().use('*', correlationId());
+    app.get('/x', (c) => c.json({ id: c.get('correlationId') }));
+    const res = await app.fetch(REQ('/x'));
+    const header = res.headers.get('x-correlation-id');
+    expect(header).toBeTruthy();
+    expect((await res.json()).id).toBe(header);
+  });
+
+  test('reuses a safe inbound id, rejects an unsafe one', async () => {
+    const app = new Hono<CursedbeltEnv>().use('*', correlationId());
+    app.get('/x', (c) => c.text('ok'));
+
+    const good = await app.fetch(REQ('/x', { headers: { 'x-correlation-id': 'trace-123' } }));
+    expect(good.headers.get('x-correlation-id')).toBe('trace-123');
+
+    const bad = await app.fetch(REQ('/x', { headers: { 'x-correlation-id': 'has space!' } }));
+    expect(bad.headers.get('x-correlation-id')).not.toBe('has space!');
+    expect(bad.headers.get('x-correlation-id')).toBeTruthy();
+  });
+});
+
+describe('errorEnvelope', () => {
+  const app = new Hono<CursedbeltEnv>().use('*', correlationId());
+  app.get('/notfound', () => {
+    throw new ApiError(404, 'not found');
+  });
+  app.get('/validation', () => {
+    throw new ApiError(422, 'invalid', { code: 'validation_failed', context: { errors: ['x'] } });
+  });
+  app.get('/boom', () => {
+    throw new Error('internal detail that must not leak');
+  });
+  app.onError(errorEnvelope);
+
+  test('ApiError → its status + rich envelope, correlationId echoed', async () => {
+    const res = await app.fetch(REQ('/notfound'));
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: Record<string, unknown>; correlationId?: string };
+    expect(body.error).toMatchObject({ name: 'ApiError', message: 'not found', status: 404, isOperational: true });
+    expect(typeof body.error.timestamp).toBe('string');
+    expect(res.headers.get('x-correlation-id')).toBeTruthy();
+    expect(body.correlationId).toBe(res.headers.get('x-correlation-id') ?? undefined);
+  });
+
+  test('ApiError carries code + context', async () => {
+    const res = await app.fetch(REQ('/validation'));
+    expect(res.status).toBe(422);
+    const body = (await res.json()) as { error: Record<string, unknown> };
+    expect(body.error).toMatchObject({
+      name: 'ApiError',
+      message: 'invalid',
+      code: 'validation_failed',
+      status: 422,
+      context: { errors: ['x'] },
+      isOperational: true,
+    });
+  });
+
+  test('unexpected error → sanitized 500 (no internal detail leaked)', async () => {
+    const res = await app.fetch(REQ('/boom'));
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: Record<string, unknown> };
+    expect(body.error).toMatchObject({ message: 'Internal Server Error', status: 500, isOperational: false });
+    expect(JSON.stringify(body)).not.toContain('internal detail that must not leak');
+  });
+});
+
+describe('securityHeaders()', () => {
+  test('app CSP overrides merge with the strict defaults per directive', async () => {
+    const app = new Hono().use(
+      '*',
+      securityHeaders({ csp: { connectSrc: ["'self'", 'https:', 'wss:'] } }),
+    );
+    app.get('/x', (c) => c.text('ok'));
+    const csp = (await app.fetch(REQ('/x'))).headers.get('content-security-policy') ?? '';
+    expect(csp).toContain("default-src 'self'"); // default kept
+    expect(csp).toContain("connect-src 'self' https: wss:"); // override applied
+    expect(csp).toContain("object-src 'none'");
+  });
+
+  test('csp:false omits the CSP header', async () => {
+    const app = new Hono().use('*', securityHeaders({ csp: false }));
+    app.get('/x', (c) => c.text('ok'));
+    const res = await app.fetch(REQ('/x'));
+    expect(res.headers.get('content-security-policy')).toBeNull();
+    expect(res.headers.get('x-frame-options')).toBe('DENY');
+  });
+});
+
+describe('createRateLimiter()', () => {
+  test('allows up to the limit, then 429 with Retry-After + envelope', async () => {
+    const app = new Hono().use('*', createRateLimiter({ limit: 5, windowMs: 60_000 }));
+    app.get('/x', (c) => c.text('ok'));
+
+    for (let i = 0; i < 5; i++) {
+      expect((await app.fetch(REQ('/x'))).status).toBe(200);
+    }
+    const blocked = await app.fetch(REQ('/x')); // the 6th
+    expect(blocked.status).toBe(429);
+    expect(Number(blocked.headers.get('retry-after'))).toBeGreaterThan(0);
+    const body = (await blocked.json()) as { error: Record<string, unknown> };
+    expect(body.error).toMatchObject({ message: expect.any(String), code: 'rate_limited', status: 429 });
+  });
+
+  test('separate keys have independent budgets', async () => {
+    let n = 0;
+    const app = new Hono().use(
+      '*',
+      createRateLimiter({ limit: 1, windowMs: 60_000, keyFn: () => `k${n}` }),
+    );
+    app.get('/x', (c) => c.text('ok'));
+    n = 0;
+    expect((await app.fetch(REQ('/x'))).status).toBe(200);
+    n = 1; // different key → fresh budget
+    expect((await app.fetch(REQ('/x'))).status).toBe(200);
+  });
+});
+
+describe('requestLogger()', () => {
+  const setup = () => {
+    const db = new Database(':memory:');
+    db.run(
+      `CREATE TABLE request_metrics (id TEXT PRIMARY KEY, ts INTEGER NOT NULL, method TEXT, route TEXT,
+         status INTEGER, duration_ms REAL, bytes_out INTEGER, user_id TEXT)`,
+    );
+    db.run(
+      `CREATE TABLE event_logs (id TEXT PRIMARY KEY, correlation_id TEXT, event_name TEXT NOT NULL,
+         type TEXT NOT NULL DEFAULT 'info', message TEXT, details TEXT, duration_ms REAL, user_id TEXT,
+         created_at TEXT NOT NULL)`,
+    );
+    const buffer = createMetricsBuffer({ db, flushIntervalMs: 1_000_000 });
+    const app = new Hono<CursedbeltEnv>().use('*', correlationId());
+    app.use('*', requestLogger(db, { buffer, slowMs: 1_000_000 }));
+    app.get('/ok', (c) => c.json({ ok: true }));
+    app.get('/missing', () => {
+      throw new ApiError(404, 'nope');
+    });
+    app.onError(errorEnvelope);
+    return { db, buffer, app };
+  };
+
+  const count = (db: Database, table: string) =>
+    (db.query(`SELECT COUNT(*) AS n FROM ${table}`).get() as { n: number }).n;
+
+  test('writes a request_metrics row per request (with the normalized route)', async () => {
+    const { db, buffer, app } = setup();
+    expect((await app.fetch(REQ('/ok'))).status).toBe(200);
+    buffer.flush();
+    expect(count(db, 'request_metrics')).toBe(1);
+    const row = db.query('SELECT method, route, status FROM request_metrics').get() as {
+      method: string;
+      route: string;
+      status: number;
+    };
+    expect(row).toEqual({ method: 'GET', route: '/ok', status: 200 });
+    buffer.stop();
+  });
+
+  test('records metrics + an event_logs row even when the handler throws', async () => {
+    const { db, buffer, app } = setup();
+    expect((await app.fetch(REQ('/missing'))).status).toBe(404);
+    buffer.flush();
+    expect(count(db, 'request_metrics')).toBe(1);
+    const metric = db.query('SELECT status FROM request_metrics').get() as { status: number };
+    expect(metric.status).toBe(404);
+    expect(count(db, 'event_logs')).toBe(1);
+    const evt = db.query('SELECT event_name, type FROM event_logs').get() as {
+      event_name: string;
+      type: string;
+    };
+    expect(evt).toEqual({ event_name: 'http_error', type: 'warn' });
+    buffer.stop();
+  });
+});
+
+describe('serveBun', () => {
+  // `ReturnType<typeof serveBun>`, not a hand-written subset: the subset was
+  // narrower than what `serveBun` actually returns, so it did not typecheck at
+  // all — and a widening of the real return would have gone unnoticed.
+  let server: ReturnType<typeof serveBun> | null = null;
+  afterEach(() => {
+    server?.stop(true);
+    server = null;
+  });
+
+  test('boots on Bun.serve and serves /health over real HTTP', async () => {
+    const app = createApp();
+    const booted = serveBun(app, { port: 0 }); // 0 → an ephemeral free port
+    server = booted;
+    const res = await fetch(`http://localhost:${booted.port}/health`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ status: 'ok' });
+  });
+});

package/src/server/app.ts

@@ -0,0 +1,89 @@
+import type { Database } from 'bun:sqlite';
+import type { Server, TLSOptions, WebSocketHandler } from 'bun';
+import { Hono } from 'hono';
+import type { CursedbeltEnv } from './context';
+import { correlationId } from './middleware/correlationId';
+import { type CorsOpts, corsAllowlist } from './middleware/corsAllowlist';
+import { errorEnvelope } from './middleware/errorEnvelope';
+import { createRateLimiter, type RateLimitOpts } from './middleware/rateLimit';
+import { requestLogger } from './middleware/requestLogger';
+import { type SecurityHeadersOpts, securityHeaders } 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 function createApp(opts: CreateAppOpts = {}): Hono<CursedbeltEnv> {
+  const app = new Hono<CursedbeltEnv>();
+
+  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;
+}
+
+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 function serveBun<T = unknown>(
+  app: Hono<CursedbeltEnv>,
+  opts: ServeBunOpts<T> = {},
+): Server<T> {
+  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 }) as Server<T>;
+}

package/src/server/audit/index.ts

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

package/src/server/audit/migrations.ts

@@ -0,0 +1,88 @@
+import type { Database } from 'bun:sqlite';
+import type { Migration } from '../migration/types';
+
+// ONE shared append-only table backs every namespace's audit trail — not a
+// shadow table per business table. cursedshell's `defineService` mutations
+// are dispatched against host-injected Store interfaces (`NotesStore`,
+// `AliasStore`, …), never raw SQL the host's DB owns, so there is no single
+// business table a `CREATE TRIGGER` could attach to. `(namespace, target_id)`
+// plays the role a per-table shadow table would: history for cursedshell's
+// `todo` plugin and an app's own `todo` table can coexist without collision.
+export const AUDIT_LOG_MIGRATIONS: readonly Migration[] = [
+  {
+    name: '0001_audit_log',
+    up(db: Database): void {
+      db.run(`
+        CREATE TABLE IF NOT EXISTS audit_log (
+          audit_id     INTEGER PRIMARY KEY AUTOINCREMENT,
+          namespace    TEXT NOT NULL,
+          mutation_key TEXT NOT NULL,
+          target_id    TEXT NOT NULL,
+          version_key  INTEGER NOT NULL,
+          operation    TEXT NOT NULL CHECK (operation IN ('insert', 'update', 'delete')),
+          tenant_id    TEXT NOT NULL,
+          changed_by   TEXT,
+          changed_at   TEXT NOT NULL,
+          snapshot_data TEXT,
+          UNIQUE(tenant_id, namespace, target_id, version_key)
+        )
+      `);
+      // Time-travel + timeline() reads key on (tenant_id, namespace, target_id);
+      // changed_at additionally covers the "state as of a timestamp" query.
+      db.run(
+        `CREATE INDEX IF NOT EXISTS idx_audit_log_lookup ON audit_log(tenant_id, namespace, target_id, changed_at)`,
+      );
+    },
+  },
+  {
+    // 05 §A1, the repair half. `0001` above was corrected in place so a fresh
+    // database is right from the start — but `CREATE TABLE IF NOT EXISTS` means
+    // an EXISTING `audit_log` keeps the old `UNIQUE(namespace, target_id,
+    // version_key)`, which is cross-tenant: two tenants whose ids collide
+    // (`target_id` is namespace-scoped, not minted per tenant — a plugin's
+    // `todo` row "5" is "5" for everybody) contend for the same version
+    // sequence, and one tenant's write fails against a row it cannot read.
+    //
+    // A table-level UNIQUE cannot be altered in SQLite, so this rebuilds. It is
+    // ordered AFTER `0001` and guarded on the old constraint actually being
+    // present, so on a fresh database it is a no-op rather than a needless copy
+    // of the whole audit trail.
+    name: '0002_tenant_scoped_version',
+    up(db: Database): void {
+      const schema = (
+        db
+          .query("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'audit_log'")
+          .get() as { sql: string } | null
+      )?.sql;
+      if (!schema || !/UNIQUE\s*\(\s*namespace/i.test(schema)) return;
+
+      db.run(`
+        CREATE TABLE audit_log_0002 (
+          audit_id     INTEGER PRIMARY KEY AUTOINCREMENT,
+          namespace    TEXT NOT NULL,
+          mutation_key TEXT NOT NULL,
+          target_id    TEXT NOT NULL,
+          version_key  INTEGER NOT NULL,
+          operation    TEXT NOT NULL CHECK (operation IN ('insert', 'update', 'delete')),
+          tenant_id    TEXT NOT NULL,
+          changed_by   TEXT,
+          changed_at   TEXT NOT NULL,
+          snapshot_data TEXT,
+          UNIQUE(tenant_id, namespace, target_id, version_key)
+        )
+      `);
+      db.run(`
+        INSERT INTO audit_log_0002
+          (audit_id, namespace, mutation_key, target_id, version_key, operation, tenant_id, changed_by, changed_at, snapshot_data)
+        SELECT audit_id, namespace, mutation_key, target_id, version_key, operation, tenant_id, changed_by, changed_at, snapshot_data
+          FROM audit_log
+      `);
+      db.run('DROP TABLE audit_log');
+      db.run('ALTER TABLE audit_log_0002 RENAME TO audit_log');
+      // The rename does not carry the index — it was dropped with the old table.
+      db.run(
+        `CREATE INDEX IF NOT EXISTS idx_audit_log_lookup ON audit_log(tenant_id, namespace, target_id, changed_at)`,
+      );
+    },
+  },
+];

package/src/server/audit/sqliteSink.test.ts

@@ -0,0 +1,200 @@
+import { Database } from 'bun:sqlite';
+import { beforeEach, describe, expect, it } from 'bun:test';
+import { auditStateAt, auditStateAtVersion, auditStep, createSqliteAuditSink } from './sqliteSink';
+
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(':memory:');
+});
+
+describe('createSqliteAuditSink', () => {
+  it('assigns sequential version keys per (namespace, targetId) and persists snapshots', async () => {
+    const sink = createSqliteAuditSink(db);
+    const v1 = await sink.record({
+      namespace: 'todo',
+      mutationKey: 'add',
+      targetId: '5',
+      operation: 'insert',
+      snapshot: { id: '5', title: 'a' },
+      tenantId: 't1',
+      changedBy: 'u1',
+    });
+    const v2 = await sink.record({
+      namespace: 'todo',
+      mutationKey: 'update',
+      targetId: '5',
+      operation: 'update',
+      snapshot: { id: '5', title: 'b' },
+      tenantId: 't1',
+    });
+    expect(v1.versionKey).toBe(1);
+    expect(v2.versionKey).toBe(2);
+    expect(v1.snapshot).toEqual({ id: '5', title: 'a' });
+  });
+
+  it('stores a null snapshot for delete tombstones', async () => {
+    const sink = createSqliteAuditSink(db);
+    const deleted = await sink.record({
+      namespace: 'todo',
+      mutationKey: 'remove',
+      targetId: '5',
+      operation: 'delete',
+      snapshot: null,
+      tenantId: 't1',
+    });
+    expect(deleted.snapshot).toBeNull();
+  });
+
+  it('is idempotent to construct twice against the same db (migration re-run is a no-op)', () => {
+    createSqliteAuditSink(db);
+    expect(() => createSqliteAuditSink(db)).not.toThrow();
+  });
+
+  it('timeline() returns full history oldest-first', async () => {
+    const sink = createSqliteAuditSink(db);
+    await sink.record({
+      namespace: 'todo',
+      mutationKey: 'add',
+      targetId: '5',
+      operation: 'insert',
+      snapshot: { title: 'a' },
+      tenantId: 't1',
+    });
+    await sink.record({
+      namespace: 'todo',
+      mutationKey: 'remove',
+      targetId: '5',
+      operation: 'delete',
+      snapshot: null,
+      tenantId: 't1',
+    });
+    const timeline = await sink.timeline!('t1', 'todo', '5');
+    expect(timeline.map((r) => r.operation)).toEqual(['insert', 'delete']);
+  });
+
+  // 05 §A1. `targetId` is a namespace-local business key, not a minted id, so
+  // two tenants routinely mutate "5". Before the tenant joined the UNIQUE and
+  // the MAX() that feeds it, tenant B's first write took version 2 — or was
+  // refused outright by tenant A's row — and B's timeline read A's history.
+  it('versions and reads per TENANT, not just per (namespace, targetId)', async () => {
+    const sink = createSqliteAuditSink(db);
+    const entry = (tenantId: string, title: string) => ({
+      namespace: 'todo',
+      mutationKey: 'add',
+      targetId: '5',
+      operation: 'insert' as const,
+      snapshot: { title },
+      tenantId,
+    });
+    const first = await sink.record(entry('t1', 'a'));
+    const second = await sink.record(entry('t2', 'b'));
+
+    expect(first.versionKey).toBe(1);
+    expect(second.versionKey).toBe(1);
+    expect((await sink.timeline!('t2', 'todo', '5')).map((r) => r.snapshot)).toEqual([{ title: 'b' }]);
+    expect(auditStateAtVersion(db, 't1', 'todo', '5', 1)?.snapshot).toEqual({ title: 'a' });
+  });
+
+  // The repair half: a database created before this landing carries
+  // `UNIQUE(namespace, target_id, version_key)` and `CREATE TABLE IF NOT EXISTS`
+  // would never correct it, so `0002` rebuilds — preserving the rows.
+  it('rebuilds a pre-existing audit_log that carries the cross-tenant UNIQUE', () => {
+    db.run(`
+      CREATE TABLE audit_log (
+        audit_id     INTEGER PRIMARY KEY AUTOINCREMENT,
+        namespace    TEXT NOT NULL,
+        mutation_key TEXT NOT NULL,
+        target_id    TEXT NOT NULL,
+        version_key  INTEGER NOT NULL,
+        operation    TEXT NOT NULL CHECK (operation IN ('insert', 'update', 'delete')),
+        tenant_id    TEXT NOT NULL,
+        changed_by   TEXT,
+        changed_at   TEXT NOT NULL,
+        snapshot_data TEXT,
+        UNIQUE(namespace, target_id, version_key)
+      )
+    `);
+    db.run(
+      `INSERT INTO audit_log (namespace, mutation_key, target_id, version_key, operation, tenant_id, changed_at, snapshot_data)
+       VALUES ('todo', 'add', '5', 1, 'insert', 't1', '2026-01-01T00:00:00.000Z', '{"title":"kept"}')`,
+    );
+
+    const sink = createSqliteAuditSink(db);
+
+    const schema = (
+      db.query("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'audit_log'").get() as { sql: string }
+    ).sql;
+    expect(schema).toContain('UNIQUE(tenant_id, namespace, target_id, version_key)');
+    // The history survived the rebuild …
+    expect(auditStateAtVersion(db, 't1', 'todo', '5', 1)?.snapshot).toEqual({ title: 'kept' });
+    // … and the constraint the rebuild exists for now holds.
+    const other = sink.record({
+      namespace: 'todo',
+      mutationKey: 'add',
+      targetId: '5',
+      operation: 'insert',
+      snapshot: { title: 'theirs' },
+      tenantId: 't2',
+    });
+    expect(other.versionKey).toBe(1);
+  });
+});
+
+describe('time-travel queries', () => {
+  const seed = async () => {
+    const sink = createSqliteAuditSink(db);
+    await sink.record({
+      namespace: 'todo',
+      mutationKey: 'add',
+      targetId: '5',
+      operation: 'insert',
+      snapshot: { title: 'v1' },
+      tenantId: 't1',
+      changedAt: '2026-01-01T00:00:00.000Z',
+    });
+    await sink.record({
+      namespace: 'todo',
+      mutationKey: 'update',
+      targetId: '5',
+      operation: 'update',
+      snapshot: { title: 'v2' },
+      tenantId: 't1',
+      changedAt: '2026-01-02T00:00:00.000Z',
+    });
+    await sink.record({
+      namespace: 'todo',
+      mutationKey: 'update',
+      targetId: '5',
+      operation: 'update',
+      snapshot: { title: 'v3' },
+      tenantId: 't1',
+      changedAt: '2026-01-03T00:00:00.000Z',
+    });
+  };
+
+  it('auditStateAt returns the last version at or before the given time', async () => {
+    await seed();
+    const state = auditStateAt(db, 't1', 'todo', '5', '2026-01-02T12:00:00.000Z');
+    expect(state?.snapshot).toEqual({ title: 'v2' });
+  });
+
+  it('auditStateAt returns null before any history exists', async () => {
+    await seed();
+    expect(auditStateAt(db, 't1', 'todo', '5', '2025-12-31T00:00:00.000Z')).toBeNull();
+  });
+
+  it('auditStateAtVersion jumps directly to a version', async () => {
+    await seed();
+    expect(auditStateAtVersion(db, 't1', 'todo', '5', 1)?.snapshot).toEqual({ title: 'v1' });
+    expect(auditStateAtVersion(db, 't1', 'todo', '5', 99)).toBeNull();
+  });
+
+  it('auditStep walks back and forward one version', async () => {
+    await seed();
+    expect(auditStep(db, 't1', 'todo', '5', 2, 'back')?.versionKey).toBe(1);
+    expect(auditStep(db, 't1', 'todo', '5', 2, 'forward')?.versionKey).toBe(3);
+    expect(auditStep(db, 't1', 'todo', '5', 1, 'back')).toBeNull();
+    expect(auditStep(db, 't1', 'todo', '5', 3, 'forward')).toBeNull();
+  });
+});