@flow-industries/id 0.24.0 → 0.24.1

package/dist/sdk/db/schema.js

@@ -0,0 +1,782 @@
+import { sql } from "drizzle-orm";
+import { bigint, bigserial, boolean, date, doublePrecision, index, integer, jsonb, pgTable, primaryKey, real, text, timestamp, uniqueIndex, } from "drizzle-orm/pg-core";
+export const user = pgTable("user", {
+    id: text("id").primaryKey(),
+    username: text("username").notNull().unique(),
+    name: text("name"),
+    email: text("email").unique(),
+    emailVerified: boolean("email_verified").notNull().default(false),
+    // A guest user has no passkey, no email and no wallet address yet; the row
+    // exists only so consumer apps can attach data to a stable user.id before
+    // the visitor signs up. Signing up upgrades this row in place (clears the
+    // flag, adds the passkey/email/wallet) rather than creating a second row.
+    isGuest: boolean("is_guest").notNull().default(false),
+    // Global permission tier (user | moderator | admin). Plain text like
+    // room_member.role so future tiers are new values, never a migration;
+    // narrowGlobalRole() collapses unknown text to 'user' so a stray value
+    // can never escalate. Written only by the grant script / admin API.
+    role: text("role").notNull().default("user"),
+    image: text("image"),
+    // The one free-text field a user controls. Canonicalized and length-capped
+    // on write (src/bio.ts); null is "unset", which is also what clearing it
+    // stores — an empty string is never written, so readers test for null only.
+    bio: text("bio"),
+    walletAddress: text("wallet_address").unique(),
+    subscribedToNews: boolean("subscribed_to_news").notNull().default(false),
+    // Per-user session epoch — the per-account sibling of the per-audience
+    // lever in origins.currentEpoch. Refresh lineages record the value in
+    // force at mint (refresh_token.user_epoch); "sign out everywhere" bumps
+    // this and every lineage stamped with an older value fails its next
+    // verify, including rotations already in flight when the bump ran.
+    sessionEpoch: integer("session_epoch").notNull().default(1),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (table) => [
+    // Functional index for the case-insensitive lookups in the OTP/register hot
+    // paths (`where lower(email) = $1`). The unique constraint on `email` is
+    // case-sensitive and Postgres can't use it for a lower() predicate, so
+    // without this every send-otp and register sequentially scans `user`.
+    index("user_lower_email_idx").on(sql `lower(${table.email})`),
+    // Partial index over the guest subset, keyed on the timestamp a future TTL
+    // reaper (DELETE ... WHERE is_guest = true AND created_at < cutoff) ranges
+    // on — so that sweep is an index range scan over guests, not a heap scan of
+    // every guest row.
+    index("user_guest_created_at_idx")
+        .on(table.createdAt)
+        .where(sql `${table.isGuest} = true`),
+]);
+export const account = pgTable("account", {
+    id: text("id").primaryKey(),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    accountId: text("account_id").notNull(),
+    providerId: text("provider_id").notNull(),
+    displayName: text("display_name"),
+    accessToken: text("access_token"),
+    refreshToken: text("refresh_token"),
+    accessTokenExpiresAt: timestamp("access_token_expires_at"),
+    refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
+    scope: text("scope"),
+    idToken: text("id_token"),
+    password: text("password"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (table) => [
+    index("account_userId_idx").on(table.userId),
+    uniqueIndex("account_provider_subject_idx").on(table.providerId, table.accountId),
+]);
+export const session = pgTable("session", {
+    id: text("id").primaryKey(),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    token: text("token").notNull().unique(),
+    expiresAt: timestamp("expires_at").notNull(),
+    ipAddress: text("ip_address"),
+    userAgent: text("user_agent"),
+    audience: text("audience"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (table) => [index("session_userId_idx").on(table.userId)]);
+// First-party session persistence: consumer apps store the opaque token in their
+// OWN origin and mint access JWTs via POST /api/session/refresh — no third-party
+// id.flow.industries cookie, so it survives iOS ITP. Rotated on every use.
+export const refreshToken = pgTable("refresh_token", {
+    id: text("id").primaryKey(),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    // sha256 hex of the opaque 256-bit token; the plaintext is returned to the
+    // client once at mint and never stored, so a DB read can't recover a usable
+    // token. Unique so refresh is a single indexed equality on the hash.
+    tokenHash: text("token_hash").notNull().unique(),
+    // Mints access JWTs only for this audience — an exfiltrated flow.game token
+    // cannot be replayed to mint for another app.
+    audience: text("audience").notNull(),
+    // Snapshot at mint; /refresh re-reads user.isGuest live so a guest->full
+    // upgrade heals even on an outstanding guest-minted token.
+    guest: boolean("guest").notNull(),
+    // Session epoch in force at mint (origins.currentEpoch). /refresh rejects a
+    // token whose epoch is behind its audience's current epoch, so bumping that
+    // epoch retires every past session for the audience on its next refresh.
+    epoch: integer("epoch").notNull().default(1),
+    // Per-user epoch in force at mint (user.session_epoch), same mechanism one
+    // scope down: carried through rotation unchanged, so a lineage minted
+    // before a "sign out everywhere" bump dies at its next verify even if a
+    // rotation raced the bump. Exempted (current-session) lineages are
+    // re-stamped to the new value instead.
+    userEpoch: integer("user_epoch").notNull().default(1),
+    // Rotation family: each /refresh rotates within the lineage. Replaying a
+    // token it rotated past (`replaced_by` set) while the lineage still holds
+    // a live row revokes all of it — two holders imply theft. Revoked any
+    // other way (sign-out, epoch bump, expiry) there is no `replaced_by`, and
+    // the token is merely dead, not replayed.
+    lineageId: text("lineage_id").notNull(),
+    // The better-auth session whose sign-in minted this lineage (carried
+    // through rotation and additional-audience mints). Groups an app's
+    // lineages under the device/browser entry in the account session list and
+    // is the revocation handle for "sign out that device". Plain text, no FK:
+    // the session row is deleted on sign-out/revocation while the lineage
+    // history must survive for reuse detection. Null on lineages minted
+    // before this column existed.
+    sessionId: text("session_id"),
+    replacedBy: text("replaced_by"),
+    // AES-256-GCM ciphertext of the successor's plaintext (key derived from
+    // BETTER_AUTH_SECRET), kept only for REFRESH_GRACE_MS after rotation so
+    // concurrent presenters (multi-tab SSR, multi-replica) converge on one
+    // successor instead of tripping reuse detection into a lineage revocation.
+    // Encrypted so a DB read still can't recover a usable token.
+    graceToken: text("grace_token"),
+    expiresAt: timestamp("expires_at").notNull(),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    revokedAt: timestamp("revoked_at"),
+}, (table) => [
+    index("refresh_token_user_id_idx").on(table.userId),
+    index("refresh_token_lineage_id_idx").on(table.lineageId),
+    index("refresh_token_expires_at_idx").on(table.expiresAt),
+    index("refresh_token_session_id_idx").on(table.sessionId),
+]);
+export const passkey = pgTable("passkey", {
+    id: text("id").primaryKey(),
+    name: text("name"),
+    publicKey: text("public_key").notNull(),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    credentialId: text("credential_id").notNull().unique(),
+    counter: integer("counter").notNull().default(0),
+    deviceType: text("device_type"),
+    backedUp: boolean("backed_up").default(false),
+    transports: text("transports"),
+    aaguid: text("aaguid"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+}, (table) => [index("passkey_userId_idx").on(table.userId)]);
+export const verification = pgTable("verification", {
+    id: text("id").primaryKey(),
+    identifier: text("identifier").notNull(),
+    value: text("value").notNull(),
+    expiresAt: timestamp("expires_at").notNull(),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (table) => [
+    index("verification_identifier_idx").on(table.identifier),
+    // better-auth bulk-deletes expired rows (WHERE expires_at < now) on every
+    // findVerificationValue call; the OTP flow multiplies that traffic.
+    index("verification_expires_at_idx").on(table.expiresAt),
+]);
+// One row per (user, surface) holding that surface's settings in a single jsonb
+// blob. `surface` namespaces independent setting sets (e.g. "game"), so a new
+// surface (site, notifications, …) is new rows here plus a registry entry —
+// never a new table or column. Keyed on user.id (the JWT sub) so rows survive
+// the in-place guest->full upgrade, and cascade on user delete (incl. guest TTL
+// reaping). Storing a surface's settings in one blob means adding/removing/
+// renaming a setting never alters this table's columns — no migration per
+// setting and a user's other saved values are never touched. `version` stamps
+// the registry shape the blob was last normalized to (per surface), so a future
+// rename/retype can upgrade old blobs on read.
+export const userSettings = pgTable("user_settings", {
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    surface: text("surface").notNull(),
+    data: jsonb("data").$type().notNull().default({}),
+    // The handler always writes the surface's current registry version; this
+    // constant is only a fallback for a row inserted without one.
+    version: integer("version").notNull().default(1),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (table) => [primaryKey({ columns: [table.userId, table.surface] })]);
+// Per-user XP state shared by every Flow surface. `total_xp` is a materialized
+// sum maintained transactionally with each xp_ledger insert so profile reads
+// never scan the ledger. `flow_score` is the gentle daily streak (0..10: +1 per
+// visited day, -1 per missed day, decay applied lazily on the next visit — no
+// cron). Keyed on user.id (the JWT sub) so rows survive the in-place
+// guest->full upgrade and cascade with the guest TTL reaper.
+export const userXp = pgTable("user_xp", {
+    userId: text("user_id")
+        .primaryKey()
+        .references(() => user.id, { onDelete: "cascade" }),
+    totalXp: bigint("total_xp", { mode: "number" }).notNull().default(0),
+    flowScore: integer("flow_score").notNull().default(0),
+    lastVisitDate: date("last_visit_date", { mode: "string" }),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+// Append-only record of every XP grant. A new XP source never alters this
+// table — it is a new `source` id in src/xp/registry.ts. `flow_score` is the
+// score at grant time, so the applied multiplier stays derivable (auditable)
+// after the economy is retuned. `idempotency_key` collapses retried reports
+// (game-server HTTP retries, overlapping visit hooks) into exactly one grant.
+export const xpLedger = pgTable("xp_ledger", {
+    id: text("id").primaryKey(),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    source: text("source").notNull(),
+    baseAmount: integer("base_amount").notNull(),
+    flowScore: integer("flow_score").notNull().default(0),
+    amount: integer("amount").notNull(),
+    metadata: jsonb("metadata").$type(),
+    idempotencyKey: text("idempotency_key").unique(),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+}, (table) => [
+    // Serves both a recent-grants view and the per-day source cap sum
+    // (WHERE user_id = ? AND created_at >= start-of-day).
+    index("xp_ledger_user_created_at_idx").on(table.userId, table.createdAt),
+]);
+// One row per discrete player action (meditation, future actions) — the durable
+// authority for the in-game action timer and disconnect crediting. `id` is the
+// game-generated session id (also the XP idempotency key). Duration derives
+// from the lifecycle timestamps and action_event transitions; `xp_granted` is
+// filled once on finish and remains zero when the janitor abandons an orphan.
+export const actionSession = pgTable("action_session", {
+    id: text("id").primaryKey(),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    source: text("source").notNull(),
+    state: text("state").notNull().default("active"),
+    // The study subject a session is attributed to; null for sources without
+    // one and for a Study started where nothing could be chosen. The subject
+    // never enters the XP math — it is what per-subject time sums on. SET NULL
+    // so a hard-deleted subject leaves its history readable as plain Study.
+    subjectId: text("subject_id").references(() => studySubject.id, {
+        onDelete: "set null",
+    }),
+    // Final durations, written once when the session ends (finish, abandon,
+    // or the sweeper's finish-at-cap) from the event log, so per-day and
+    // per-subject stats sum them without replaying action_event. Zero while
+    // active, and on rows that ended before they were materialized.
+    accruedSeconds: doublePrecision("accrued_seconds").notNull().default(0),
+    focusedSeconds: doublePrecision("focused_seconds").notNull().default(0),
+    xpGranted: integer("xp_granted"),
+    metadata: jsonb("metadata").$type(),
+    startedAt: timestamp("started_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+    finishedAt: timestamp("finished_at"),
+}, (table) => [
+    index("action_session_user_started_at_idx").on(table.userId, table.startedAt),
+    // Compatibility index for pre-AUTH-70 pods; the current janitor uses
+    // action_session_active_started_at_idx.
+    index("action_session_open_updated_at_idx")
+        .on(table.updatedAt)
+        .where(sql `${table.state} = 'active'`),
+    index("action_session_active_user_started_at_idx")
+        .on(table.userId, table.startedAt)
+        .where(sql `${table.state} = 'active'`),
+    index("action_session_active_started_at_idx")
+        .on(table.startedAt)
+        .where(sql `${table.state} = 'active'`),
+    // Per-subject range sums, the keyset-paged per-subject session list and
+    // the delete-time reference check all filter on subject_id first; partial
+    // because most sessions (Meditate) carry none.
+    index("action_session_subject_started_at_idx")
+        .on(table.subjectId, table.startedAt)
+        .where(sql `${table.subjectId} is not null`),
+]);
+// Append-only lifecycle transitions for an action session — the history layer
+// for duration and focus stats. `kind` is
+// start|pause|resume|focus_lost|focus_gained|finish|abandon.
+export const actionEvent = pgTable("action_event", {
+    id: text("id").primaryKey(),
+    sessionId: text("session_id")
+        .notNull()
+        .references(() => actionSession.id, { onDelete: "cascade" }),
+    kind: text("kind").notNull(),
+    // Compatibility field for lifecycle rows written by pre-AUTH-70 pods.
+    accruedSeconds: integer("accrued_seconds").notNull().default(0),
+    at: timestamp("at").notNull().defaultNow(),
+}, (table) => [
+    index("action_event_session_at_idx").on(table.sessionId, table.at),
+]);
+// Coarse "record everything" rollup: accumulated seconds per character
+// state-machine state per UTC day (grounded, air, wall_run_left, …, action).
+// The game accumulates in-memory and flushes deltas periodically, so 60Hz state
+// churn never becomes one row per transition — one row per (user, day, state).
+export const characterStateTime = pgTable("character_state_time", {
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    day: date("day", { mode: "string" }).notNull(),
+    state: text("state").notNull(),
+    seconds: integer("seconds").notNull().default(0),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (table) => [primaryKey({ columns: [table.userId, table.day, table.state] })]);
+// The persistent room registry: rooms are the shared social primitive across
+// every Flow surface (game world routing, future text chat, future voice,
+// cross-product presence). `id` is the immutable internal key every FK and
+// service report uses; `slug` is the mutable user-facing URL handle
+// (flow.game/<slug>), lowercase-unique so casing can't mint squattable
+// duplicates. Ownership references a full (non-guest) Flow account; deleting
+// the owner's account intentionally orphans the room (ownerId null) instead of
+// cascading — rooms outlive their creators and a moderator can claim them.
+export const room = pgTable("room", {
+    id: text("id").primaryKey(),
+    slug: text("slug").notNull().unique(),
+    displayName: text("display_name").notNull(),
+    description: text("description"),
+    ownerId: text("owner_id").references(() => user.id, {
+        onDelete: "set null",
+    }),
+    visibility: text("visibility").notNull().default("public"),
+    // The seeded default room ("global"): cannot be deleted, renamed, or made
+    // non-public, so the fleet always has a valid landing destination.
+    isSystem: boolean("is_system").notNull().default(false),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (table) => [
+    index("room_owner_id_idx").on(table.ownerId),
+    // Sized for the public browse listing's keyset scan; unlisted/private rooms
+    // never appear there so the partial keeps it dense.
+    index("room_public_created_at_idx")
+        .on(table.createdAt)
+        .where(sql `${table.visibility} = 'public'`),
+]);
+// Durable membership (my-rooms, roles). Presence (who is connected right now)
+// is deliberately a separate table: public rooms are drop-in joinable without
+// membership. The owner is NOT duplicated here — `room.ownerId` is the single
+// authority, so ownership transfer is one UPDATE; `role` holds moderator|member
+// and future roles are new text values, never a migration.
+export const roomMember = pgTable("room_member", {
+    roomId: text("room_id")
+        .notNull()
+        .references(() => room.id, { onDelete: "cascade" }),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    role: text("role").notNull().default("member"),
+    joinedAt: timestamp("joined_at").notNull().defaultNow(),
+}, (table) => [
+    primaryKey({ columns: [table.roomId, table.userId] }),
+    index("room_member_user_id_idx").on(table.userId),
+]);
+// Per-room moderation state, kind = ban|mute. Active = expires_at is null (permanent)
+// or in the future; lifting a restriction deletes the row, re-issuing upserts
+// it, so there is at most one live row per (room, user, kind). Enforced at
+// join/connect (ban) and by the room's realtime surfaces (mute).
+export const roomRestriction = pgTable("room_restriction", {
+    id: text("id").primaryKey(),
+    roomId: text("room_id")
+        .notNull()
+        .references(() => room.id, { onDelete: "cascade" }),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    kind: text("kind").notNull(),
+    reason: text("reason"),
+    issuedBy: text("issued_by").references(() => user.id, {
+        onDelete: "set null",
+    }),
+    expiresAt: timestamp("expires_at"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+}, (table) => [
+    uniqueIndex("room_restriction_room_user_kind_idx").on(table.roomId, table.userId, table.kind),
+]);
+// Per-room settings, one jsonb blob per surface — the room-scoped sibling of
+// user_settings. "game" is the first surface; text chat, voice, and the
+// Discord bridge attach later as new surfaces (rows + a registry entry in
+// src/rooms/settings-registry.ts), never as columns. Delivered to trusted
+// services via the session-verify room context — a surface blob may hold
+// secret-ish values (webhook URLs), so it is never exposed in public listings.
+export const roomSettings = pgTable("room_settings", {
+    roomId: text("room_id")
+        .notNull()
+        .references(() => room.id, { onDelete: "cascade" }),
+    surface: text("surface").notNull(),
+    data: jsonb("data").$type().notNull().default({}),
+    version: integer("version").notNull().default(1),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (table) => [primaryKey({ columns: [table.roomId, table.surface] })]);
+// Live occupancy, one row per (room, user, channel) with channel = game|voice|
+// text. Written only by trusted services (declarative snapshot reports under a
+// service token); a row is alive while its updated_at is within the staleness
+// cutoff — reads always filter on it and a reaper deletes what the cutoff has
+// already hidden, so a crashed reporter never shows ghosts. The userId index
+// serves the cross-product "where is this user right now" read.
+export const roomPresence = pgTable("room_presence", {
+    roomId: text("room_id")
+        .notNull()
+        .references(() => room.id, { onDelete: "cascade" }),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    channel: text("channel").notNull(),
+    joinedAt: timestamp("joined_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (table) => [
+    primaryKey({ columns: [table.roomId, table.userId, table.channel] }),
+    index("room_presence_updated_at_idx").on(table.updatedAt),
+    index("room_presence_user_id_idx").on(table.userId),
+]);
+// Where a player was standing when they last left a room, so rejoining resumes
+// instead of restarting at the spawn ring. Written only by trusted services
+// (the game server's position relay under the same token presence uses) and
+// read back on the session-verify room context for the room being joined, so
+// it never becomes a cross-room "where is this user" oracle. Accumulate-only:
+// unlike room_presence this must survive the player's absence, which is the
+// whole point, so it is deliberately not a field on the declarative presence
+// snapshot. real (float4) carries ~7 significant digits — sub-millimetre a
+// kilometre from origin, far past what a 2m terrain step needs.
+//
+// No TTL and no reaper. The coordinate is validated against the live world on
+// every restore, so a year-old row is exactly as usable as yesterday's, and
+// ageing rows out would only send the longest-absent player to spawn. Deletion
+// is entirely by cascade: dropping a room, an account or a never-upgraded guest
+// takes its positions with it.
+export const roomPlayerState = pgTable("room_player_state", {
+    roomId: text("room_id")
+        .notNull()
+        .references(() => room.id, { onDelete: "cascade" }),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    x: real("x").notNull(),
+    y: real("y").notNull(),
+    z: real("z").notNull(),
+    yaw: real("yaw").notNull(),
+    worldId: text("world_id").notNull(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (table) => [primaryKey({ columns: [table.roomId, table.userId] })]);
+// A scheduled happening in a room — the series, not the dated instance. One-off
+// events carry a null `recurrence` and materialize exactly one occurrence;
+// recurring ones store the rule and let the expander produce instances.
+// `timezone` is the IANA zone the series was authored in and is load-bearing,
+// not decoration: recurrence expands in local time so a 20:00 weekly race stays
+// at 20:00 across a DST shift, and only the resulting instants are stored UTC.
+// Deleting the author orphans the event (createdBy null) the way a room outlives
+// its owner; deleting the room takes its events with it.
+export const roomEvent = pgTable("room_event", {
+    id: text("id").primaryKey(),
+    roomId: text("room_id")
+        .notNull()
+        .references(() => room.id, { onDelete: "cascade" }),
+    createdBy: text("created_by").references(() => user.id, {
+        onDelete: "set null",
+    }),
+    title: text("title").notNull(),
+    description: text("description"),
+    coverUrl: text("cover_url"),
+    startsAt: timestamp("starts_at").notNull(),
+    endsAt: timestamp("ends_at"),
+    timezone: text("timezone").notNull().default("UTC"),
+    recurrence: jsonb("recurrence").$type(),
+    // The one Discord scheduled event standing for the WHOLE series, set only
+    // when the rule is one Discord can repeat on its own (see
+    // `discordRecurrence`). While it is set the instances below are not
+    // mirrored individually — that is the difference between one repeating
+    // Discord event and ninety identical one-offs.
+    discordEventId: text("discord_event_id"),
+    discordSyncedAt: timestamp("discord_synced_at"),
+    // Minutes before the start at which to remind subscribers; 0 is "at the
+    // start". Per event so a long-planned tournament can warn a day ahead while
+    // a nightly race does not nag.
+    reminderOffsets: jsonb("reminder_offsets").$type(),
+    status: text("status").notNull().default("scheduled"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, 
+// Only the room FK's cascade reads this table by room — every room-scoped
+// event read, including the live-event cap, goes through the occurrence table
+// where the dates live.
+(table) => [index("room_event_room_id_idx").on(table.roomId)]);
+// One concrete dated instance of a series. Everything a player touches attaches
+// here rather than to the series — interest, reminders, attendance history — so
+// a weekly race's third week is addressable on its own. `roomId` is duplicated
+// from the parent so the by-room time-window read and the scheduler's due scan
+// never need the join. `overridden` marks an instance moved or cancelled on its
+// own, so a later series-wide edit leaves it alone.
+//
+// `recurrenceId` is the instant the recurrence rule produced, and it is the
+// row's identity: (eventId, recurrenceId) is what makes rolling
+// re-materialization an idempotent upsert. It is deliberately NOT `startsAt` —
+// a per-instance override moves `startsAt`, and keying on a column the product
+// lets users change would leave the materializer unable to tell "this instant
+// already has a row, relocated" from "this instant has no row yet", so it would
+// resurrect a duplicate at the original time. RFC 5545 splits these for the
+// same reason (RECURRENCE-ID vs DTSTART). A one-off's `recurrenceId` is simply
+// its own start.
+export const roomEventOccurrence = pgTable("room_event_occurrence", {
+    id: text("id").primaryKey(),
+    eventId: text("event_id")
+        .notNull()
+        .references(() => roomEvent.id, { onDelete: "cascade" }),
+    roomId: text("room_id")
+        .notNull()
+        .references(() => room.id, { onDelete: "cascade" }),
+    recurrenceId: timestamp("recurrence_id").notNull(),
+    startsAt: timestamp("starts_at").notNull(),
+    endsAt: timestamp("ends_at"),
+    status: text("status").notNull().default("scheduled"),
+    overridden: boolean("overridden").notNull().default(false),
+    // Attendance summary, written once when the instance completes so the
+    // history view stays durable after raw lifecycle edges expire.
+    attendeeCount: integer("attendee_count"),
+    peakConcurrent: integer("peak_concurrent"),
+    // The mirrored Discord scheduled event, so every later edit updates that
+    // event instead of creating a second one. `discordSyncedAt` is compared
+    // against `updatedAt` to decide whether the mirror has drifted — the worker
+    // reconciles it, so authoring never waits on a Discord round trip.
+    discordEventId: text("discord_event_id"),
+    discordSyncedAt: timestamp("discord_synced_at"),
+    // When players were present, derived from lifecycle edges merged with the
+    // sampled fallback at completion: the FIRST and LAST player seen, not the
+    // run window. An occurrence nobody attended leaves both null, which is
+    // exactly why they cannot stand in for the columns above.
+    actualStartedAt: timestamp("actual_started_at"),
+    actualEndedAt: timestamp("actual_ended_at"),
+    // The authoritative run window, stamped by the scheduler at the instant each
+    // transition happens rather than derived from anything. This is what records
+    // that an occurrence ran at all — the attendance pair above cannot, because a
+    // run with zero attendees produces two nulls, and with attendees it reports
+    // when people were in the room, which is a different question.
+    //
+    // A window the worker slept through goes scheduled -> completed in one step,
+    // so `completedAt` is stamped and `activatedAt` stays null: nobody observed
+    // it start, and inventing a value would be worse than admitting that.
+    activatedAt: timestamp("activated_at"),
+    completedAt: timestamp("completed_at"),
+    cancelledAt: timestamp("cancelled_at"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (table) => [
+    uniqueIndex("room_event_occurrence_event_recurrence_idx").on(table.eventId, table.recurrenceId),
+    index("room_event_occurrence_event_starts_at_idx").on(table.eventId, table.startsAt),
+    index("room_event_occurrence_room_starts_at_idx").on(table.roomId, table.startsAt),
+    // Serves the fleet-wide upcoming listing and the scheduler's "what is due
+    // now" scan, both of which are time-ordered across every room.
+    index("room_event_occurrence_starts_at_idx").on(table.startsAt),
+]);
+// "Interested" on one dated instance — the social proof on the card and the
+// subscriber list a reminder fans out to, which is why it hangs off the
+// occurrence and not the series. Cascades with the occurrence, so pruning a
+// stale instance or deleting a series takes its interest with it. The userId
+// index serves the future "what am I interested in" read.
+export const roomEventRsvp = pgTable("room_event_rsvp", {
+    occurrenceId: text("occurrence_id")
+        .notNull()
+        .references(() => roomEventOccurrence.id, { onDelete: "cascade" }),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+}, (table) => [
+    primaryKey({ columns: [table.occurrenceId, table.userId] }),
+    index("room_event_rsvp_user_id_idx").on(table.userId),
+]);
+// Following a whole series, the opt-in above per-instance interest. Kept as its
+// own row rather than a fan-out of RSVPs so that following a weekly race covers
+// instances that do not exist yet: the horizon materializes week 14 long after
+// the player opted in, and it arrives already subscribed.
+export const roomEventFollow = pgTable("room_event_follow", {
+    eventId: text("event_id")
+        .notNull()
+        .references(() => roomEvent.id, { onDelete: "cascade" }),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+}, (table) => [
+    primaryKey({ columns: [table.eventId, table.userId] }),
+    index("room_event_follow_user_id_idx").on(table.userId),
+]);
+// The exactly-once gate for reminders. A tick claims a row BEFORE delivering,
+// so a crash mid-fan-out re-runs safely: the claim either succeeds (nobody has
+// sent this yet) or conflicts (somebody has). The unique key is what makes that
+// true — never the clock, which can fire the same window twice across a restart
+// or a rolling deploy. `kind` names the reminder (`reminder_60m`, `start`, …)
+// and `channel` the delivery route, so adding Discord in AUTH-163 is a new
+// channel value and not a second ledger.
+export const roomEventDispatch = pgTable("room_event_dispatch", {
+    id: text("id").primaryKey(),
+    occurrenceId: text("occurrence_id")
+        .notNull()
+        .references(() => roomEventOccurrence.id, { onDelete: "cascade" }),
+    kind: text("kind").notNull(),
+    channel: text("channel").notNull(),
+    outcome: text("outcome").notNull().default("claimed"),
+    recipients: integer("recipients").notNull().default(0),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+}, (table) => [
+    uniqueIndex("room_event_dispatch_occurrence_kind_channel_idx").on(table.occurrenceId, table.kind, table.channel),
+]);
+// The fallback record of who was in the room while an instance ran.
+// `room_presence` is a live snapshot with no history, so the scheduler still
+// samples it for servers or batches that produce no lifecycle edges. These rows
+// merge with exact game_event intervals when the occurrence completes.
+export const roomEventAttendance = pgTable("room_event_attendance", {
+    occurrenceId: text("occurrence_id")
+        .notNull()
+        .references(() => roomEventOccurrence.id, { onDelete: "cascade" }),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    firstSeenAt: timestamp("first_seen_at").notNull().defaultNow(),
+    lastSeenAt: timestamp("last_seen_at").notNull().defaultNow(),
+}, (table) => [primaryKey({ columns: [table.occurrenceId, table.userId] })]);
+// Append-only game-server lifecycle history: server boot/shutdown, room
+// open/close, and the join/leave edges of every play session. Nothing here is a
+// `room_event` — that table is a *scheduled* happening, this one is what the
+// dedicated server actually did.
+//
+// It exists because the ops copy cannot answer product questions: the
+// OpenObserve `game_events` stream this mirrors has a retention window, is
+// absent in dev, and is ingest-only, exactly as `security_event` exists beside
+// `auth_events`. And `room_presence` cannot either — a declarative snapshot
+// deletes a player's row the moment they leave, taking their `joined_at` with
+// it, which is why the attendance fallback still samples every 30s.
+//
+// `session_id` is minted by the game server per admitted player and carried on
+// BOTH edges, so time-present is a self-join on it rather than a heuristic
+// pairing over ephemeral peer ids that restart and get reused. `id` is the
+// reporter's idempotency key, which is what makes a retried batch safe.
+// Server-scoped events (boot/shutdown, room open/close) carry no user and no
+// session, so both FKs are nullable; every player-scoped row cascades with the
+// account and with the room, because this is per-player history and must not
+// outlive either.
+export const gameEvent = pgTable("game_event", {
+    id: text("id").primaryKey(),
+    event: text("event").notNull(),
+    occurredAt: timestamp("occurred_at").notNull(),
+    recordedAt: timestamp("recorded_at").notNull().defaultNow(),
+    serverId: text("server_id").notNull(),
+    sessionId: text("session_id"),
+    roomId: text("room_id").references(() => room.id, { onDelete: "cascade" }),
+    roomSlug: text("room_slug"),
+    userId: text("user_id").references(() => user.id, { onDelete: "cascade" }),
+    reason: text("reason"),
+    detail: jsonb("detail").$type(),
+}, (table) => [
+    // The session self-join that pairs a join with its leave.
+    index("game_event_session_id_idx").on(table.sessionId),
+    index("game_event_room_occurred_at_idx").on(table.roomId, table.occurredAt),
+    index("game_event_user_occurred_at_idx").on(table.userId, table.occurredAt),
+    // Sized for the retention sweep's range delete.
+    index("game_event_occurred_at_idx").on(table.occurredAt),
+    index("game_event_recorded_id_idx").on(table.recordedAt, table.id),
+]);
+// Serializes product-feed boundaries independently of application clocks.
+// Writers advance this row inside the same transaction as their event batch;
+// tail bootstrap requests lock it before recording their immutable boundary.
+export const gameEventFeedClock = pgTable("game_event_feed_clock", {
+    id: text("id").primaryKey(),
+    recordedAt: timestamp("recorded_at").notNull(),
+});
+// `acknowledgedAt` is proof that the consumer durably committed the cursor.
+// Unacknowledged boundaries never expire: future-dated retained events may
+// still depend on them even after the ordinary retention interval passes.
+export const gameEventFeedTail = pgTable("game_event_feed_tail", {
+    id: text("id").primaryKey(),
+    recordedAt: timestamp("recorded_at").notNull(),
+    eventId: text("event_id").notNull(),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    acknowledgedAt: timestamp("acknowledged_at"),
+});
+// User-visible security activity — the durable feed behind the dialog's
+// Security view. Written from emit() for the small allow-set in
+// src/security-events.ts; the OpenObserve auth_events stream can't back a
+// product surface (ops-facing, ingest-only, absent in dev), so the feed keeps
+// its own owner-scoped table. `ip` is stored for future "was this you?" flows
+// but never exposed by the read endpoint (country + coarse device only). Rows
+// cascade with the user and are pruned past the retention window on read —
+// the index serves both that range delete and the recency listing.
+export const securityEvent = pgTable("security_event", {
+    id: text("id").primaryKey(),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    event: text("event").notNull(),
+    audience: text("audience"),
+    ip: text("ip"),
+    country: text("country"),
+    userAgent: text("user_agent"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+}, (table) => [
+    index("security_event_user_created_at_idx").on(table.userId, table.createdAt),
+]);
+// The erasure ledger: one row per deleted account, appended in the same
+// transaction that deletes the user row (src/account-erasure.ts). `user_id` is
+// the sub every downstream service keyed its data on and is deliberately NOT a
+// foreign key — the row exists precisely because the user row no longer does.
+// Served ascending by `seq` to trusted consumers (talk) that poll
+// GET /api/account/erasures with their own cursor and purge what they hold;
+// Unacknowledged rows survive consumer outages; acknowledged rows retain a
+// minimum replay window before reaping.
+export const accountErasure = pgTable("account_erasure", {
+    seq: bigserial("seq", { mode: "number" }).primaryKey(),
+    userId: text("user_id").notNull(),
+    deletedRoomIds: jsonb("deleted_room_ids")
+        .$type()
+        .notNull()
+        .default([]),
+    avatarUrl: text("avatar_url"),
+    talkAcknowledgedAt: timestamp("talk_acknowledged_at", {
+        withTimezone: true,
+    }),
+    erasedAt: timestamp("erased_at", { withTimezone: true })
+        .notNull()
+        .defaultNow(),
+}, (table) => [index("account_erasure_erased_at_idx").on(table.erasedAt)]);
+export const jwks = pgTable("jwks", {
+    id: text("id").primaryKey(),
+    publicKey: text("public_key").notNull(),
+    privateKey: text("private_key").notNull(),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    expiresAt: timestamp("expires_at"),
+});
+// Backing store for better-auth's rate limiter (rateLimit.storage: "database").
+// The export key, and the `key`/`count`/`lastRequest` JS field names, must match
+// better-auth's `rateLimit` model exactly — the drizzle adapter resolves the
+// model by export key and columns by field name. SQL names follow the repo's
+// snake_case convention. lastRequest holds an epoch-millis timestamp, so it
+// needs bigint, not int4. Persisting to Postgres (not memory) keeps the limiter
+// correct across pod restarts/deploys and any future multi-replica scale-out.
+export const rateLimit = pgTable("rate_limit", {
+    id: text("id").primaryKey(),
+    key: text("key").notNull(),
+    count: integer("count").notNull().default(0),
+    lastRequest: bigint("last_request", { mode: "number" }).notNull().default(0),
+});
+// What a user studies, in their own words: "Math for my test", "Chinese",
+// "Beekeeping". `field` anchors a row to the study catalog (src/study/catalog.ts)
+// — a `category/field` slug, a bare category slug for a custom subject that
+// still rolls up under one, or null when the catalog has no home for it. The
+// catalog is a code registry, not a table, so this is a plain text slug with no
+// FK; renaming a label never touches these rows. Keyed on user.id (the JWT sub)
+// so rows survive the in-place guest->full upgrade and cascade with the
+// account, including the guest TTL reaper.
+//
+// A subject is never renamed away from its history: archiving (archived_at set)
+// hides it from the picker while any session that referenced it keeps
+// resolving. The live-name uniqueness is therefore partial — an archived
+// "Chinese" must not block a fresh one — and case-insensitive, so "chinese" and
+// "Chinese" are one subject. The last-used index serves the picker's
+// recent-first listing and the "most recently studied" fallback a game start
+// carries no subject for.
+export const studySubject = pgTable("study_subject", {
+    id: text("id").primaryKey(),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    field: text("field"),
+    name: text("name").notNull(),
+    archivedAt: timestamp("archived_at"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    lastUsedAt: timestamp("last_used_at").notNull().defaultNow(),
+}, (table) => [
+    uniqueIndex("study_subject_user_live_name_idx")
+        .on(table.userId, sql `lower(${table.name})`)
+        .where(sql `${table.archivedAt} is null`),
+    index("study_subject_user_last_used_at_idx").on(table.userId, table.lastUsedAt.desc()),
+]);
+export const oauthSession = pgTable("oauth_session", {
+    providerId: text("provider_id").notNull(),
+    accountId: text("account_id").notNull(),
+    data: text("data").notNull(),
+    formatVersion: integer("format_version").notNull().default(2),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (table) => [primaryKey({ columns: [table.providerId, table.accountId] })]);
+export const oauthState = pgTable("oauth_state", {
+    providerId: text("provider_id").notNull(),
+    id: text("id").notNull(),
+    data: text("data").notNull(),
+    expiresAt: timestamp("expires_at").notNull(),
+}, (table) => [primaryKey({ columns: [table.providerId, table.id] })]);