fest-gateway 0.1.0

package/dist/server/store/bootstrap.js

@@ -0,0 +1,53 @@
+/**
+ * First-run bootstrap.
+ *
+ * Fest ships single-org: one row, seeded on first boot. Every table already
+ * carries `org_id` so that stays an implementation detail rather than a
+ * migration later.
+ */
+import { newId } from "./ids.js";
+export const DEFAULT_ORG_SLUG = "default";
+export function ensureOrg(store, slug = DEFAULT_ORG_SLUG, name = "Default") {
+    const existing = store.db
+        .prepare(`SELECT id, slug, name FROM orgs WHERE slug = ?`)
+        .get(slug);
+    if (existing !== undefined)
+        return existing;
+    const org = { id: newId("org"), slug, name };
+    store.db
+        .prepare(`INSERT INTO orgs (id, slug, name, created_at) VALUES (?, ?, ?, ?)`)
+        .run(org.id, org.slug, org.name, Date.now());
+    return org;
+}
+/**
+ * Idempotent by (org, email) so `seed` can be re-run safely — which matters
+ * because migrations and seeding both run on boot in a container.
+ */
+export function ensureUser(store, args) {
+    const existing = store.db
+        .prepare(`SELECT id, org_id, email, role FROM users WHERE org_id = ? AND email = ?`)
+        .get(args.orgId, args.email);
+    if (existing !== undefined) {
+        return { id: existing.id, orgId: existing.org_id, email: existing.email, role: existing.role };
+    }
+    const user = {
+        id: newId("usr"),
+        orgId: args.orgId,
+        email: args.email,
+        role: args.role ?? "member",
+    };
+    store.db
+        .prepare(`INSERT INTO users (id, org_id, email, display_name, role, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`)
+        .run(user.id, user.orgId, user.email, args.displayName ?? "", user.role, Date.now());
+    return user;
+}
+export function findUserByEmail(store, orgId, email) {
+    const row = store.db
+        .prepare(`SELECT id, org_id, email, role FROM users WHERE org_id = ? AND email = ?`)
+        .get(orgId, email);
+    if (row === undefined)
+        return null;
+    return { id: row.id, orgId: row.org_id, email: row.email, role: row.role };
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/server/store/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../../server/store/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEjC,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAe1C,MAAM,UAAU,SAAS,CAAC,KAAY,EAAE,IAAI,GAAG,gBAAgB,EAAE,IAAI,GAAG,SAAS;IAC/E,MAAM,QAAQ,GAAG,KAAK,CAAC,EAAE;SACtB,OAAO,CAAC,gDAAgD,CAAC;SACzD,GAAG,CAAC,IAAI,CAA2D,CAAC;IACvE,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAE5C,MAAM,GAAG,GAAQ,EAAE,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAClD,KAAK,CAAC,EAAE;SACL,OAAO,CAAC,mEAAmE,CAAC;SAC5E,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC/C,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,KAAY,EACZ,IAAiG;IAEjG,MAAM,QAAQ,GAAG,KAAK,CAAC,EAAE;SACtB,OAAO,CAAC,0EAA0E,CAAC;SACnF,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAEhB,CAAC;IACd,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;IACjG,CAAC;IAED,MAAM,IAAI,GAAS;QACjB,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC;QAChB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,QAAQ;KAC5B,CAAC;IACF,KAAK,CAAC,EAAE;SACL,OAAO,CACN;iCAC2B,CAC5B;SACA,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACvF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAY,EAAE,KAAa,EAAE,KAAa;IACxE,MAAM,GAAG,GAAG,KAAK,CAAC,EAAE;SACjB,OAAO,CAAC,0EAA0E,CAAC;SACnF,GAAG,CAAC,KAAK,EAAE,KAAK,CAEN,CAAC;IACd,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;AAC7E,CAAC"}

package/dist/server/store/db.js

@@ -0,0 +1,157 @@
+/**
+ * SQLite handle, pragmas, and forward-only migrations.
+ *
+ * ── The synchronous-API constraint, which is load-bearing ────────────────────
+ *
+ * `node:sqlite`'s `DatabaseSync` is exactly what it says: EVERY statement runs
+ * on the main thread and blocks the event loop for its full duration. In a
+ * process whose day job is relaying long-lived streaming HTTP responses, that
+ * is normally disqualifying — a 40ms dashboard aggregate would stall every
+ * in-flight proxied stream by 40ms, and Claude Code users would see it as
+ * stutter in their terminal.
+ *
+ * It is acceptable here only because of a structural rule: THE REQUEST HOT PATH
+ * NEVER TOUCHES THIS DATABASE. Identity lookups are served from an in-memory
+ * cache, and usage is handed to a queue that batches into one transaction well
+ * off the request path (see server/ingest/sink.ts). The only synchronous
+ * queries are the metering writer's batch and the dashboard's own requests.
+ *
+ * So: if you are about to add a `store.db.prepare(...)` call inside a proxied
+ * request's lifecycle, don't. Move it behind the queue, or move the database to
+ * a worker thread first. This comment is the guardrail.
+ *
+ * ── Pragmas ─────────────────────────────────────────────────────────────────
+ *
+ * WAL is the one that matters. Under the default rollback journal a writer
+ * excludes all readers, so a dashboard query could block the metering writer
+ * (and vice versa) — and because the API is synchronous, "blocked" means the
+ * whole process is parked, streams included. WAL lets readers and the single
+ * writer proceed concurrently, which is precisely the shape of this workload:
+ * one batching writer, several bursty readers.
+ *
+ * Note: depending on Node version, importing `node:sqlite` may print an
+ * ExperimentalWarning. It is expected; we deliberately do not suppress it
+ * process-wide, because doing so would also hide unrelated warnings.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { log } from "../log.js";
+const MIGRATIONS_DIR = join(import.meta.dirname, "migrations");
+export function openStore(path) {
+    const db = new DatabaseSync(path);
+    // Order matters: WAL first so the journal switch happens before anything
+    // else writes, and busy_timeout last so it covers the rest of the session.
+    db.exec("PRAGMA journal_mode = WAL");
+    // NORMAL, not FULL: we fsync at checkpoints rather than every commit. The
+    // exposure is losing the last few hundred milliseconds of metering on an OS
+    // crash, which is an acceptable trade for not fsyncing per batch. Metering is
+    // observability, not ledger.
+    db.exec("PRAGMA synchronous = NORMAL");
+    db.exec("PRAGMA foreign_keys = ON");
+    // Another process (a backup, a CLI) can hold the write lock briefly; wait
+    // rather than throwing SQLITE_BUSY straight into the caller.
+    db.exec("PRAGMA busy_timeout = 5000");
+    /**
+     * NOT RE-ENTRANT. SQLite has no nested transactions without SAVEPOINT, and
+     * silently flattening a nested call would mean an inner "rollback" that
+     * actually discards the outer caller's work. We detect and throw instead:
+     * a loud error at development time beats a partially-applied batch in
+     * production.
+     */
+    let depth = 0;
+    const store = {
+        db,
+        transaction(fn) {
+            if (depth > 0) {
+                throw new Error("Store.transaction is not re-entrant; flatten the call or use SAVEPOINT");
+            }
+            depth = 1;
+            // BEGIN IMMEDIATE, not BEGIN: a deferred transaction takes the write
+            // lock at the first write, so contention surfaces halfway through a
+            // batch where we would have to unwind. IMMEDIATE takes it up front and
+            // lets busy_timeout do the waiting before we have done any work.
+            db.exec("BEGIN IMMEDIATE");
+            try {
+                const result = fn();
+                db.exec("COMMIT");
+                return result;
+            }
+            catch (err) {
+                try {
+                    db.exec("ROLLBACK");
+                }
+                catch (rollbackErr) {
+                    // A failed rollback must not mask the original error.
+                    log.warn("store rollback failed", { err: String(rollbackErr) });
+                }
+                throw err;
+            }
+            finally {
+                depth = 0;
+            }
+        },
+        close() {
+            db.close();
+        },
+    };
+    return store;
+}
+function userVersion(db) {
+    const row = db.prepare("PRAGMA user_version").get();
+    return Number(row?.user_version ?? 0);
+}
+/** Numeric prefix of a migration filename, e.g. "007-add-x.sql" → 7. */
+function migrationVersion(file) {
+    const match = /^(\d+)/.exec(file);
+    return match ? Number(match[1]) : Number.NaN;
+}
+/**
+ * Apply every migration newer than `PRAGMA user_version`.
+ *
+ * Forward-only, by design and with precedent: there are no down migrations
+ * anywhere in Fest. Reversing a schema change correctly requires the old data
+ * to still exist, which a destructive migration by definition destroyed, so a
+ * "down" script gives false confidence. The rollback story is restoring a
+ * volume snapshot, which is also the only story that survives a bad deploy that
+ * corrupted rows rather than columns.
+ *
+ * Idempotent: a second call sees user_version already at the highest prefix and
+ * applies nothing.
+ */
+export function migrate(store) {
+    const current = userVersion(store.db);
+    const files = readdirSync(MIGRATIONS_DIR)
+        .filter((f) => f.endsWith(".sql"))
+        // Sort by filename, not by parsed number: the numeric prefixes are
+        // zero-padded, so lexical order is numeric order, and a filename that
+        // sorts oddly is a naming bug we want to see rather than paper over.
+        .sort();
+    let version = current;
+    let applied = 0;
+    for (const file of files) {
+        const fileVersion = migrationVersion(file);
+        if (!Number.isInteger(fileVersion)) {
+            throw new Error(`migration ${file} has no numeric prefix`);
+        }
+        if (fileVersion <= current)
+            continue;
+        const sql = readFileSync(join(MIGRATIONS_DIR, file), "utf8");
+        // Each file in its own transaction: SQLite applies DDL transactionally, so
+        // a syntax error in migration 3 leaves 1 and 2 committed and the version
+        // at 2 — a retry after fixing the file resumes from exactly there.
+        store.transaction(() => {
+            store.db.exec(sql);
+        });
+        applied += 1;
+        version = fileVersion;
+    }
+    if (version !== current) {
+        // user_version cannot be parameterised, hence the interpolation; the value
+        // came from a filename we just proved is an integer.
+        store.db.exec(`PRAGMA user_version = ${version}`);
+        log.info("store migrated", { from: current, to: version, applied });
+    }
+    return { applied, version };
+}
+//# sourceMappingURL=db.js.map

package/dist/server/store/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../../server/store/db.ts"],"names":[],"mappings":"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"}

package/dist/server/store/ids.js

@@ -0,0 +1,14 @@
+/**
+ * Entity ids: `<kind>_<hex>`.
+ *
+ * Kind-prefixed so an id is self-describing in a log line or a URL, and so a
+ * user id pasted where a token id belongs fails obviously instead of silently
+ * matching nothing.
+ */
+import { randomUUID } from "node:crypto";
+export function newId(prefix) {
+    // Dashes stripped: the id ends up in URLs and CLI args, and 32 hex chars
+    // avoid any question about what is a separator.
+    return `${prefix}_${randomUUID().replaceAll("-", "")}`;
+}
+//# sourceMappingURL=ids.js.map

package/dist/server/store/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../server/store/ids.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,MAAM,UAAU,KAAK,CAAC,MAAgB;IACpC,yEAAyE;IACzE,gDAAgD;IAChD,OAAO,GAAG,MAAM,IAAI,UAAU,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC;AACzD,CAAC"}

package/dist/server/store/migrations/001-init.sql

@@ -0,0 +1,213 @@
+-- Fest schema, migration 001.
+--
+-- Conventions:
+--   * Timestamps are INTEGER epoch milliseconds. No timezone class of bug.
+--   * Booleans are INTEGER 0/1.
+--   * Entity ids are TEXT with a kind prefix (org_, usr_, tok_) so they are
+--     safe in URLs and self-describing in logs.
+--   * `requests` uses the integer rowid as its primary key: monotonic, cheap,
+--     and it gives keyset pagination for free. `id` is the external uuid.
+--   * org_id is on every tenant table from day one even though the spike seeds
+--     a single org. The column costs nothing now; retrofitting it across a
+--     request table and every query later costs a week and a data migration.
+
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE orgs (
+  id            TEXT PRIMARY KEY,
+  slug          TEXT NOT NULL UNIQUE,
+  name          TEXT NOT NULL,
+  created_at    INTEGER NOT NULL,
+  -- retention_days, member_visibility, etc. Kept as JSON so adding a setting
+  -- is not a migration.
+  settings_json TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE TABLE users (
+  id           TEXT PRIMARY KEY,
+  org_id       TEXT NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  email        TEXT NOT NULL,
+  display_name TEXT NOT NULL DEFAULT '',
+  role         TEXT NOT NULL CHECK (role IN ('owner', 'admin', 'member')),
+  disabled_at  INTEGER,
+  created_at   INTEGER NOT NULL,
+  UNIQUE (org_id, email)
+);
+
+-- What a developer's Claude Code presents to Fest so usage can be attributed.
+--
+-- This is NOT an upstream provider credential. It is never forwarded to
+-- Anthropic, and it deliberately cannot live in ANTHROPIC_API_KEY or
+-- ANTHROPIC_AUTH_TOKEN, because setting either makes Claude Code abandon
+-- subscription auth. It travels in the URL path or an X-Fest-Token header.
+CREATE TABLE identity_tokens (
+  id           TEXT PRIMARY KEY,
+  org_id       TEXT NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  user_id      TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  name         TEXT NOT NULL DEFAULT '',
+  -- sha256(raw), hex. The raw token is shown exactly once, at creation.
+  --
+  -- sha256 and not scrypt/bcrypt on purpose: these are 32 bytes of
+  -- randomBytes, so there is no dictionary to attack and nothing for a slow
+  -- KDF to buy — while a slow KDF would add its cost to EVERY proxied request.
+  -- User passwords, when they arrive, do use scrypt. Do not "fix" this.
+  token_hash   TEXT NOT NULL UNIQUE,
+  -- Display-only, e.g. "fest_7Fq2…". Lets the UI and support identify a token
+  -- without ever holding it.
+  token_prefix TEXT NOT NULL,
+  created_at   INTEGER NOT NULL,
+  expires_at   INTEGER,
+  revoked_at   INTEGER,
+  -- Updated coarsely (batched), never per request: it would double the write
+  -- volume for information nobody needs to the second.
+  last_used_at INTEGER
+);
+
+CREATE INDEX identity_tokens_live ON identity_tokens (token_hash) WHERE revoked_at IS NULL;
+CREATE INDEX identity_tokens_user ON identity_tokens (org_id, user_id);
+
+-- One row per completed upstream call. The hot table.
+CREATE TABLE requests (
+  seq                   INTEGER PRIMARY KEY,
+  id                    TEXT NOT NULL UNIQUE,
+  -- Deliberately NOT a foreign key, unlike users/identity_tokens: this is the
+  -- hot insert path and an FK check per row buys nothing here, since org_id is
+  -- supplied by the server rather than a client. Please do not "fix" the
+  -- asymmetry by adding REFERENCES.
+  org_id                TEXT NOT NULL,
+  -- Nullable: a request with no identity token is recorded as unattributed
+  -- rather than dropped. We never guess who it was.
+  user_id               TEXT,
+  token_id              TEXT,
+
+  started_at            INTEGER NOT NULL,
+  ended_at              INTEGER NOT NULL,
+
+  -- Credential dimension. This is the compliance story, so it is first-class:
+  -- an admin must be able to see at a glance which requests ran on a
+  -- developer's own subscription versus a server-held key.
+  posture               TEXT NOT NULL,
+  identity_carrier      TEXT NOT NULL,
+  caller_fingerprint    TEXT,
+  -- Fingerprint only. A bearer is never stored; there is no column for one.
+  credential_fingerprint TEXT,
+  credential_origin     TEXT NOT NULL,
+
+  -- Claude Code supplies this itself, so session grouping is free.
+  session_id            TEXT,
+
+  requested_model       TEXT,
+  served_model          TEXT,
+  upstream              TEXT NOT NULL,
+
+  stream                INTEGER NOT NULL DEFAULT 0,
+  status                TEXT NOT NULL,
+  http_status           INTEGER,
+  error_type            TEXT,
+  error_message         TEXT,
+  partial               INTEGER NOT NULL DEFAULT 0,
+
+  -- DISJOINT billing buckets. input_tokens excludes both cache reads and cache
+  -- writes; context size is the sum of all four. Folding cache reads into
+  -- input is an order-of-magnitude error on a cache-heavy agent workload,
+  -- which Claude Code is.
+  input_tokens          INTEGER NOT NULL DEFAULT 0,
+  cache_read_tokens     INTEGER NOT NULL DEFAULT 0,
+  cache_write_5m_tokens INTEGER NOT NULL DEFAULT 0,
+  cache_write_1h_tokens INTEGER NOT NULL DEFAULT 0,
+  output_tokens         INTEGER NOT NULL DEFAULT 0,
+  web_searches          INTEGER NOT NULL DEFAULT 0,
+  service_tier          TEXT,
+
+  -- NULL means no dollar figure applies or is available. It does NOT mean zero.
+  -- cost_basis says which: 'subscription' (the developer's own plan absorbed
+  -- it, so there is no org spend), 'list' (priced), or 'none' (unknown model).
+  -- A SUM() over this column silently skips NULLs, which is why the rollup
+  -- carries unpriced_requests alongside the priced sum.
+  cost_usd              REAL,
+  cost_basis            TEXT NOT NULL DEFAULT 'none',
+
+  ttfb_ms               INTEGER,
+  duration_ms           INTEGER NOT NULL DEFAULT 0,
+  bytes_in              INTEGER NOT NULL DEFAULT 0,
+  bytes_out             INTEGER NOT NULL DEFAULT 0,
+
+  upstream_request_id   TEXT,
+
+  -- Anthropic's unified quota headers, on every response. For a subscription
+  -- developer THIS is the scarce resource, not dollars, so it is stored as
+  -- queryable columns rather than opaque JSON.
+  rl_status             TEXT,
+  rl_5h_utilization     REAL,
+  rl_5h_status          TEXT,
+  rl_5h_reset_at        INTEGER,
+  rl_7d_utilization     REAL,
+  rl_7d_status          TEXT,
+  rl_7d_reset_at        INTEGER,
+  rl_claim              TEXT,
+  rl_overage_status     TEXT,
+  rl_overage_reason     TEXT,
+
+  client_version        TEXT
+);
+
+-- One index per dashboard query shape. None speculative.
+CREATE INDEX requests_feed      ON requests (org_id, started_at DESC);
+CREATE INDEX requests_user      ON requests (org_id, user_id, started_at DESC);
+CREATE INDEX requests_model     ON requests (org_id, served_model, started_at DESC);
+CREATE INDEX requests_credential ON requests (org_id, credential_origin, started_at DESC);
+CREATE INDEX requests_session   ON requests (org_id, session_id, started_at DESC);
+-- Partial: the errors view then scans ~1% of rows instead of all of them.
+CREATE INDEX requests_errors    ON requests (org_id, started_at DESC) WHERE error_type IS NOT NULL;
+
+-- Hourly rollups. Survive raw-row deletion and serve every chart beyond the
+-- live window, so long-range trends keep working after the PII-bearing rows
+-- have aged out.
+CREATE TABLE usage_hourly (
+  org_id                TEXT NOT NULL,
+  hour_start            INTEGER NOT NULL,
+  -- '' is the "all" bucket for each dimension, so one table serves both
+  -- per-user and org-wide queries.
+  user_id               TEXT NOT NULL DEFAULT '',
+  served_model          TEXT NOT NULL DEFAULT '',
+  credential_origin     TEXT NOT NULL DEFAULT '',
+  cost_basis            TEXT NOT NULL DEFAULT '',
+
+  requests              INTEGER NOT NULL DEFAULT 0,
+  errors                INTEGER NOT NULL DEFAULT 0,
+
+  input_tokens          INTEGER NOT NULL DEFAULT 0,
+  cache_read_tokens     INTEGER NOT NULL DEFAULT 0,
+  cache_write_5m_tokens INTEGER NOT NULL DEFAULT 0,
+  cache_write_1h_tokens INTEGER NOT NULL DEFAULT 0,
+  output_tokens         INTEGER NOT NULL DEFAULT 0,
+  web_searches          INTEGER NOT NULL DEFAULT 0,
+
+  -- Sum of PRICED rows only, plus the count of rows we could not price, so a
+  -- total can be rendered honestly as "$12.3456 (+3 n/a)" rather than being
+  -- quietly short.
+  cost_usd              REAL NOT NULL DEFAULT 0,
+  unpriced_requests     INTEGER NOT NULL DEFAULT 0,
+  -- Requests absorbed by a developer's own subscription: real usage, no org
+  -- spend. Counted separately so it is never added to a dollar total.
+  subscription_requests INTEGER NOT NULL DEFAULT 0,
+
+  duration_ms_sum       INTEGER NOT NULL DEFAULT 0,
+  duration_ms_max       INTEGER NOT NULL DEFAULT 0,
+  ttfb_ms_sum           INTEGER NOT NULL DEFAULT 0,
+  ttfb_count            INTEGER NOT NULL DEFAULT 0,
+
+  -- Fixed latency histogram buckets rather than percentiles: percentiles do
+  -- not merge across rollup rows, but bucket counts add. Boundaries are
+  -- <1s, <3s, <10s, <30s, <60s, >=60s.
+  lat_b0 INTEGER NOT NULL DEFAULT 0,
+  lat_b1 INTEGER NOT NULL DEFAULT 0,
+  lat_b2 INTEGER NOT NULL DEFAULT 0,
+  lat_b3 INTEGER NOT NULL DEFAULT 0,
+  lat_b4 INTEGER NOT NULL DEFAULT 0,
+  lat_b5 INTEGER NOT NULL DEFAULT 0,
+
+  PRIMARY KEY (org_id, hour_start, user_id, served_model, credential_origin, cost_basis)
+) WITHOUT ROWID;
+
+CREATE INDEX usage_hourly_time ON usage_hourly (org_id, hour_start DESC);

package/dist/server/store/migrations/002-feed-and-error-indexes.sql

@@ -0,0 +1,26 @@
+-- Migration 002: fix two indexes that did not match how the code actually
+-- queries. Both were found by building the read layer against 001.
+
+-- 1. The keyset feed had no index.
+--
+-- The feed pages with `WHERE org_id = ? AND seq < ? ORDER BY seq DESC`, but
+-- `requests_feed` is (org_id, started_at DESC) and cannot order by seq. SQLite
+-- fell back to a descending rowid search: technically a SEARCH rather than a
+-- SCAN, so it looked fine in a query plan, but it walks other orgs' rows to
+-- find yours. Harmless at one org, wrong at ten.
+CREATE INDEX requests_feed_seq ON requests (org_id, seq DESC);
+
+-- 2. The errors partial index keyed off the wrong predicate.
+--
+-- 001 defined it as `error_type IS NOT NULL`, but "is an error" everywhere in
+-- the code is `status <> 'ok'` — which is what the writer counts and what the
+-- errors view filters on. The two disagree for exactly the rows that matter
+-- most: `identity_denied` and `client_abort` are non-ok and carry no
+-- error_type, so they were invisible to the index and the errors view could
+-- not use it at all.
+--
+-- Aligning the index to the code rather than the reverse, because `status` is
+-- the authoritative field: it is NOT NULL and always set, while error_type is
+-- incidental detail.
+DROP INDEX IF EXISTS requests_errors;
+CREATE INDEX requests_errors ON requests (org_id, started_at DESC) WHERE status <> 'ok';

package/dist/server/store/migrations/003-routing.sql

@@ -0,0 +1,42 @@
+-- Phase 4: routing and credential visibility.
+--
+-- `pipeline` and `route_id` record WHICH decision served a request;
+-- `credentials_considered` records WHY. The last is stored as JSON rather than
+-- normalised into its own table on purpose: it is an append-only audit note
+-- read whole and never queried across, and a join table would invite exactly
+-- the partial read ("show me the credential" — which one?) that this field
+-- exists to prevent.
+--
+-- The CHECK is the structural half of the never-persist-a-credential rule.
+-- There is no column here a secret belongs in, and this makes that enforceable
+-- rather than customary: anything secret-shaped fails the INSERT instead of
+-- being written and noticed later, if ever.
+--
+-- ── Deliberately NOT added to usage_hourly ──────────────────────────────────
+--
+-- `pipeline` is not a rollup dimension. It would have to join the cube's
+-- primary key, which means rebuilding the cube and revisiting the writer's key
+-- de-duplication — and a mistake there multiplies every token count in the org
+-- totals, which is precisely the bug that shipped and was caught in Phase 2.
+--
+-- The aggregate question is already answered without it: a substituted request
+-- is recorded as `credential_origin = 'fallback_server'`, which IS a rollup
+-- dimension. So "how much of our traffic ran on a server-held key" survives
+-- retention, while per-ROUTE breakdowns read raw rows and therefore go blank
+-- once those age out. That is the same honest limitation the error breakdown
+-- already carries, and the right trade against destabilising every number on
+-- the dashboard.
+
+ALTER TABLE requests ADD COLUMN pipeline TEXT NOT NULL DEFAULT 'passthrough';
+ALTER TABLE requests ADD COLUMN route_id TEXT;
+ALTER TABLE requests ADD COLUMN credentials_considered TEXT NOT NULL DEFAULT '[]'
+  CHECK (
+    credentials_considered NOT LIKE '%sk-ant-%'
+    AND credentials_considered NOT LIKE '%sk-or-%'
+    AND credentials_considered NOT LIKE '%fw_%'
+    AND credentials_considered NOT LIKE '%Bearer %'
+  );
+
+-- "Which requests did not run on the caller's own credential" is the compliance
+-- question this phase exists to answer, so it gets an index rather than a scan.
+CREATE INDEX requests_pipeline ON requests (org_id, pipeline, started_at DESC);

package/dist/server/store/migrations/004-admin-auth.sql

@@ -0,0 +1,72 @@
+-- Fest schema, migration 004: dashboard accounts, sessions, audit log.
+--
+-- Two different authentication systems live in this database and must not be
+-- confused:
+--
+--   identity_tokens  — a developer's Claude Code proving who it is on the
+--                      PROXY path. Hot path. sha256, no KDF (see 001).
+--   users.password_hash + sessions
+--                    — a human signing in to the DASHBOARD. Cold path, human
+--                      chosen secret, so scrypt with a per-password salt.
+--
+-- The proxy path never reads either of the tables below. That is what keeps a
+-- slow KDF and a synchronous session lookup off a request that is relaying a
+-- developer's stream.
+
+-- NULL password_hash means "this user exists as an attribution target but
+-- cannot sign in" — which is every user created by `fest token create`. A
+-- dashboard account is granted deliberately, never as a side effect of a
+-- developer being metered.
+ALTER TABLE users ADD COLUMN password_hash TEXT;
+ALTER TABLE users ADD COLUMN password_set_at INTEGER;
+
+CREATE TABLE sessions (
+  id           TEXT PRIMARY KEY,
+  org_id       TEXT NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  user_id      TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  -- sha256(raw). The raw value exists only in the operator's cookie, so a
+  -- database read — a backup, a support session, a leaked file — cannot be
+  -- turned into a live session.
+  token_hash   TEXT NOT NULL UNIQUE,
+  created_at   INTEGER NOT NULL,
+  -- Absolute cap. A session dies at this instant no matter how active it is,
+  -- so a stolen cookie has a bounded life even under constant use.
+  expires_at   INTEGER NOT NULL,
+  -- Idle timeout, rolled forward as the session is used.
+  last_seen_at INTEGER NOT NULL,
+  revoked_at   INTEGER,
+  -- Recorded for the audit trail, never for authorisation: both are trivially
+  -- forged, so binding a session to them would only lock out real users behind
+  -- a changing IP.
+  user_agent   TEXT NOT NULL DEFAULT '',
+  ip           TEXT NOT NULL DEFAULT ''
+);
+
+CREATE INDEX sessions_user   ON sessions (org_id, user_id, created_at DESC);
+CREATE INDEX sessions_expiry ON sessions (expires_at);
+
+-- Who did what, as an administrative record rather than a debug log.
+--
+-- Deliberately a table and not the application log: logs rotate, are filtered
+-- by level, and are the first thing lost when a container restarts. "When was
+-- this token minted, and by whom" is a question asked months later.
+CREATE TABLE audit_log (
+  seq           INTEGER PRIMARY KEY,
+  org_id        TEXT NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  at            INTEGER NOT NULL,
+  -- NULL for an actor who never authenticated — a failed login has no user.
+  actor_user_id TEXT REFERENCES users(id) ON DELETE SET NULL,
+  -- What the actor called themselves: the email typed at a failed login, or
+  -- "cli" for a command run on the host. Survives the user row being deleted,
+  -- which is exactly when the record matters most.
+  actor_label   TEXT NOT NULL DEFAULT '',
+  action        TEXT NOT NULL,
+  target        TEXT NOT NULL DEFAULT '',
+  outcome       TEXT NOT NULL CHECK (outcome IN ('ok', 'denied', 'error')),
+  -- Never a credential, never a prompt. Enforced by test.
+  detail_json   TEXT NOT NULL DEFAULT '{}',
+  ip            TEXT NOT NULL DEFAULT ''
+);
+
+CREATE INDEX audit_log_recent ON audit_log (org_id, at DESC);
+CREATE INDEX audit_log_actor  ON audit_log (org_id, actor_user_id, at DESC);

package/dist/server/store/migrations/005-notional-cost.sql

@@ -0,0 +1,28 @@
+-- Notional cost: what usage WOULD have cost at published API rates.
+--
+-- The motivating gap: subscription requests are the bulk of Fest's traffic and
+-- carry no dollar figure at all, because `cost_usd` is org spend and a
+-- developer's own plan absorbed them. That is correct for an invoice and
+-- useless for a team lead asking what their Max seats deliver.
+--
+-- So this is a SECOND, PARALLEL figure, never a widening of the first:
+--
+--   * `cost_usd` remains org spend. Subscription rows stay NULL. Every existing
+--     aggregate, guard and UI label is unchanged.
+--   * `notional_cost_usd` is VALUE, populated on every path including
+--     subscription. It is never added to `cost_usd` anywhere — the two live in
+--     separate columns, separate SQL aggregates and separate dashboard stats
+--     precisely so that summing them is never the easy thing to do.
+--
+-- Existing rows keep NULL / 0. They are genuinely unknown: back-filling them at
+-- today's rates would invent a history that never happened, and rates drift.
+
+ALTER TABLE requests ADD COLUMN notional_cost_usd REAL;
+
+ALTER TABLE usage_hourly ADD COLUMN notional_cost_usd REAL NOT NULL DEFAULT 0;
+
+-- The same honesty device as `unpriced_requests`, and needed for the same
+-- reason: SUM() skips NULLs, so without a count the notional total looks
+-- complete while silently omitting every model with no published rate.
+-- Non-zero means `notional_cost_usd` is a lower bound.
+ALTER TABLE usage_hourly ADD COLUMN notional_unpriced_requests INTEGER NOT NULL DEFAULT 0;