Use ordered SQLite migrations (Refs #75)

src/lib/server/activity.ts

@@ -9,7 +9,6 @@ import {
 } from '../activity.js';
 import { serverTitle } from '../ui/server-labels.js';
 import { db } from './db/index.js';
-import { ensureHostSchema } from './hosts/schema.js';
 import { importantOperationSql } from './hosts/observations.js';
 
 const initialized = new WeakSet<Database.Database>();
@@ -190,7 +189,6 @@ function present(row: SqlRow): ActivityRow {
 export function activityHistory(input: ActivityQuery = {}, now = Date.now()): ActivityPage {
     const query = normalizeActivityQuery(input);
     const handle = db();
-    ensureHostSchema(handle);
     if (!initialized.has(handle)) {
         handle.function('activity_server_title', { deterministic: true }, (name: unknown) =>
             typeof name === 'string' ? serverTitle(name) : ''

src/lib/server/auth/index.ts

@@ -1,6 +1,5 @@
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { db } from '../db/index.js';
-import { ensureAuthSchema } from './schema.js';
 import { hashPassword, verifyPassword } from './passwords.js';
 import { systemUsername, type AuthUser, type UserRole } from '../../auth.js';
 
@@ -9,9 +8,7 @@ export const SESSION_LIFETIME_MS = 12 * 60 * 60_000;
 export const SESSION_IDLE_MS = 30 * 60_000;
 const digest = (value: string) => createHash('sha256').update(value).digest('hex');
 function database() {
-    const handle = db();
-    ensureAuthSchema(handle);
-    return handle;
+    return db();
 }
 type UserRow = {
     id: string;

src/lib/server/auth/schema.ts

@@ -1,7 +1,5 @@
 import type Database from 'better-sqlite3';
-const initialized = new WeakSet<Database.Database>();
-export function ensureAuthSchema(handle: Database.Database): void {
-    if (initialized.has(handle)) return;
+export function migrateAuthSchema(handle: Database.Database): void {
     handle.exec(`
         CREATE TABLE IF NOT EXISTS auth_users (
             id TEXT PRIMARY KEY, username TEXT NOT NULL COLLATE NOCASE UNIQUE,
@@ -24,5 +22,4 @@ export function ensureAuthSchema(handle: Database.Database): void {
         );
         CREATE INDEX IF NOT EXISTS auth_audit_created_at ON auth_audit(created_at);
     `);
-    initialized.add(handle);
 }

src/lib/server/db/index.ts

@@ -1,417 +1,15 @@
 import Database from 'better-sqlite3';
-import { installReportRevisions } from '../reports/revisions.js';
 import { mkdirSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { config } from '../config.js';
-import schemaSql from './schema.sql?raw';
-import { requirement, type BetaPlan, type BetaRequirement } from '../../beta-plan.js';
-import { emptyMetrics } from '../fleet/beta-evaluation.js';
-import { backfillLeaderboard } from '../fleet/leaderboard-ingest.js';
-import { initializeFleetSettings } from './fleet-settings.js';
-import { migrateServerHistory } from './server-history.js';
-import { migrateNativeInstances } from '../backends/schema.js';
-import { migrateServerKeys } from './server-keys.js';
-import { ensureAutoscalingSchema } from '../autoscaling/schema.js';
-import { ensureRebalancingSchema } from '../rebalancing/schema.js';
-import { installPerformanceIndexes } from './performance-indexes.js';
-import { migrateFileBlobs } from './file-blobs.js';
-import { enableIncrementalVacuum, retentionClocks } from './retention-clocks.js';
-import { migrationStep, tuneConnection, tuneMigrationConnection } from './connection.js';
+import { migrations } from './migrations.js';
+import { runMigrations } from './migration-runner.js';
+import { tuneConnection, tuneMigrationConnection } from './connection.js';
 import { timeStatement } from './slow-statements.js';
 
 let _db: Database.Database | null = null;
 let optimizeTimer: NodeJS.Timeout | undefined;
 
-// Desired shape of the `servers` table. Every column here is added to the
-// table on boot if missing — introspection via PRAGMA table_info handles
-// both fresh DBs and legacy DBs that predate any given column. CREATE TABLE
-// IF NOT EXISTS in schema.sql is a no-op on existing tables, so it can't
-// backfill columns; this can.
-const SERVERS_COLUMNS: Array<{ name: string; ddl: string }> = [
-    {
-        name: 'container_checked_at',
-        ddl: 'ALTER TABLE servers ADD COLUMN container_checked_at TEXT'
-    },
-    { name: 'container_state', ddl: 'ALTER TABLE servers ADD COLUMN container_state TEXT' },
-    {
-        name: 'desired_state',
-        ddl: "ALTER TABLE servers ADD COLUMN desired_state TEXT NOT NULL DEFAULT 'running' CHECK (desired_state IN ('running','stopped'))"
-    },
-    // Base columns that shipped in the very first schema stay here for parity
-    // with fresh installs — no ALTER is issued if they're already present.
-    { name: 'game_port', ddl: 'ALTER TABLE servers ADD COLUMN game_port INTEGER' },
-    { name: 'rcon_host', ddl: 'ALTER TABLE servers ADD COLUMN rcon_host TEXT' },
-    { name: 'last_players', ddl: 'ALTER TABLE servers ADD COLUMN last_players INTEGER' },
-    { name: 'last_checked_at', ddl: 'ALTER TABLE servers ADD COLUMN last_checked_at TEXT' },
-    // Post-v0.1 additions from the perk-a-cola/diagnostics work
-    { name: 'last_map', ddl: 'ALTER TABLE servers ADD COLUMN last_map TEXT' },
-    { name: 'last_gametype', ddl: 'ALTER TABLE servers ADD COLUMN last_gametype TEXT' },
-    { name: 'last_roster', ddl: 'ALTER TABLE servers ADD COLUMN last_roster TEXT' },
-    { name: 'last_seen_at', ddl: 'ALTER TABLE servers ADD COLUMN last_seen_at TEXT' },
-    { name: 'last_error', ddl: 'ALTER TABLE servers ADD COLUMN last_error TEXT' },
-    {
-        name: 'rcon_failures',
-        ddl: 'ALTER TABLE servers ADD COLUMN rcon_failures INTEGER NOT NULL DEFAULT 0'
-    },
-    { name: 'last_reply_snippet', ddl: 'ALTER TABLE servers ADD COLUMN last_reply_snippet TEXT' },
-    // Script-scope columns — static per server, populated via server-edit UI.
-    { name: 'game', ddl: 'ALTER TABLE servers ADD COLUMN game TEXT' },
-    { name: 'map', ddl: 'ALTER TABLE servers ADD COLUMN map TEXT' },
-    // Provisioning columns — populated when EC creates the deployment.
-    { name: 'game_mode', ddl: 'ALTER TABLE servers ADD COLUMN game_mode TEXT' },
-    { name: 'map_slug', ddl: 'ALTER TABLE servers ADD COLUMN map_slug TEXT' },
-    { name: 'host_dir', ddl: 'ALTER TABLE servers ADD COLUMN host_dir TEXT' },
-    { name: 'config_file', ddl: 'ALTER TABLE servers ADD COLUMN config_file TEXT' },
-    { name: 'game_id', ddl: 'ALTER TABLE servers ADD COLUMN game_id TEXT' },
-    { name: 'image', ddl: 'ALTER TABLE servers ADD COLUMN image TEXT' },
-    { name: 'created_by', ddl: 'ALTER TABLE servers ADD COLUMN created_by TEXT' },
-    { name: 'destroyed_at', ddl: 'ALTER TABLE servers ADD COLUMN destroyed_at TEXT' },
-    // Occupancy + match timers — see schema.sql for semantics.
-    { name: 'active_since', ddl: 'ALTER TABLE servers ADD COLUMN active_since TEXT' },
-    { name: 'inactive_since', ddl: 'ALTER TABLE servers ADD COLUMN inactive_since TEXT' },
-    { name: 'game_started_at', ddl: 'ALTER TABLE servers ADD COLUMN game_started_at TEXT' },
-    { name: 'game_ended_at', ddl: 'ALTER TABLE servers ADD COLUMN game_ended_at TEXT' },
-    { name: 'game_cycle_key', ddl: 'ALTER TABLE servers ADD COLUMN game_cycle_key TEXT' }
-];
-
-function migrateServers(handle: Database.Database): void {
-    const rows = handle.prepare('PRAGMA table_info(servers)').all() as Array<{ name: string }>;
-    const existing = new Set(rows.map((r) => r.name));
-    for (const col of SERVERS_COLUMNS) {
-        if (!existing.has(col.name)) {
-            handle.exec(col.ddl);
-        }
-    }
-    // Retire external-backend registry fields, including required fields that
-    // would otherwise prevent native inserts into an upgraded database.
-    const retired = new Set(['komodo_type', 'komodo_name', 'komodo_server']);
-    handle.transaction(() => {
-        for (const column of rows) {
-            if (retired.has(column.name))
-                handle.exec(
-                    `ALTER TABLE servers DROP COLUMN "${column.name.replaceAll('"', '""')}"`
-                );
-        }
-    })();
-}
-
-// Additive columns on tables the script model owns. Same pattern as
-// migrateServers — CREATE TABLE IF NOT EXISTS won't backfill columns onto
-// pre-existing tables, so we introspect and ALTER as needed.
-const SCRIPTS_COLUMNS: Array<{ name: string; ddl: string }> = [
-    { name: 'kind', ddl: "ALTER TABLE scripts ADD COLUMN kind TEXT NOT NULL DEFAULT 'script'" }
-];
-
-const SCRIPT_VERSIONS_COLUMNS: Array<{ name: string; ddl: string }> = [
-    { name: 'release_version', ddl: 'ALTER TABLE script_versions ADD COLUMN release_version TEXT' },
-    // state was added post-launch to make untested/tested/test-failed visible
-    // in the UI. Existing rows default to 'untested' — this is safe because
-    // any real promoted version's script has current_version_id set (which is
-    // the authoritative "promoted" signal), and any version already gated
-    // through a ready-promote beta will be re-marked next time that state
-    // machine fires.
-    {
-        name: 'state',
-        ddl: "ALTER TABLE script_versions ADD COLUMN state TEXT NOT NULL DEFAULT 'untested'"
-    },
-    {
-        name: 'kind',
-        ddl: "ALTER TABLE script_versions ADD COLUMN kind TEXT NOT NULL DEFAULT 'script'"
-    }
-];
-
-const BETA_SCRIPTS_COLUMNS: Array<{ name: string; ddl: string }> = [
-    { name: 'kind', ddl: "ALTER TABLE beta_scripts ADD COLUMN kind TEXT NOT NULL DEFAULT 'script'" }
-];
-
-const DEPLOYMENT_SCRIPTS_COLUMNS: Array<{ name: string; ddl: string }> = [
-    {
-        name: 'kind',
-        ddl: "ALTER TABLE deployment_scripts ADD COLUMN kind TEXT NOT NULL DEFAULT 'script'"
-    }
-];
-
-const DEPLOYMENTS_COLUMNS: Array<{ name: string; ddl: string }> = [
-    {
-        name: 'script_id',
-        ddl: 'ALTER TABLE deployments ADD COLUMN script_id INTEGER REFERENCES scripts(id)'
-    },
-    {
-        name: 'script_version_id',
-        ddl: 'ALTER TABLE deployments ADD COLUMN script_version_id INTEGER REFERENCES script_versions(id)'
-    },
-    {
-        name: 'prior_version_id',
-        ddl: 'ALTER TABLE deployments ADD COLUMN prior_version_id INTEGER REFERENCES script_versions(id)'
-    },
-    {
-        name: 'beta_id',
-        ddl: 'ALTER TABLE deployments ADD COLUMN beta_id INTEGER REFERENCES betas(id)'
-    },
-    {
-        name: 'rolled_back_by',
-        ddl: 'ALTER TABLE deployments ADD COLUMN rolled_back_by TEXT REFERENCES deployments(id)'
-    }
-];
-
-function migrateTable(
-    handle: Database.Database,
-    table: string,
-    cols: Array<{ name: string; ddl: string }>
-): void {
-    const rows = handle.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
-    const existing = new Set(rows.map((r) => r.name));
-    for (const col of cols) {
-        if (!existing.has(col.name)) handle.exec(col.ddl);
-    }
-}
-
-// Backfill the multi-script join tables from the legacy single-script columns.
-// Existing bundle membership is authoritative. Only single-script betas can
-// inherit server membership from the deprecated primary-script columns.
-function backfillMultiScriptJoins(handle: Database.Database): void {
-    handle.exec(
-        `INSERT INTO beta_scripts (beta_id, script_id, script_version_id)
-         SELECT b.id, b.script_id, b.script_version_id
-         FROM betas b
-         WHERE b.script_id IS NOT NULL
-           AND NOT EXISTS (SELECT 1 FROM beta_scripts bs WHERE bs.beta_id = b.id)`
-    );
-    handle.exec(
-        `INSERT INTO beta_server_scripts (beta_id, server, script_id, had_original, prior_version_id)
-         SELECT bs.beta_id, bs.server, b.script_id, bs.had_original, bs.prior_version_id
-         FROM beta_servers bs
-         JOIN betas b ON b.id = bs.beta_id
-         WHERE b.script_id IS NOT NULL
-           AND bs.server_deleted_at IS NULL
-           AND EXISTS (SELECT 1 FROM servers WHERE name = bs.server)
-           AND (SELECT COUNT(*) FROM beta_scripts x WHERE x.beta_id = b.id) = 1
-           AND EXISTS (SELECT 1 FROM beta_scripts x WHERE x.beta_id = b.id AND x.script_id = b.script_id)
-           AND NOT EXISTS (
-             SELECT 1 FROM beta_server_scripts x
-             WHERE x.beta_id = bs.beta_id AND x.server = bs.server
-           )`
-    );
-    handle.exec(
-        `INSERT INTO deployment_scripts (deployment_id, script_id, script_version_id, prior_version_id)
-         SELECT d.id, d.script_id, d.script_version_id, d.prior_version_id
-         FROM deployments d
-         WHERE d.script_id IS NOT NULL
-           AND d.script_version_id IS NOT NULL
-           AND NOT EXISTS (SELECT 1 FROM deployment_scripts ds WHERE ds.deployment_id = d.id)`
-    );
-}
-
-// The pre-script-model beta tables had entirely different shapes (slug PK,
-// beta_scripts, beta_deploys). schema.sql defines the new shape; CREATE TABLE
-// IF NOT EXISTS is a no-op if the old tables already exist, so we have to
-// detect and drop them first. Any outstanding rows abort the boot so the
-// operator can promote/rollback in the old app before upgrading.
-function dropLegacyBetaTables(handle: Database.Database): void {
-    const legacy = handle
-        .prepare(
-            "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('betas','beta_scripts','beta_deploys')"
-        )
-        .all() as Array<{ name: string }>;
-    if (legacy.length === 0) return;
-
-    const legacyNames = legacy.map((r) => r.name);
-    // The old `betas` table had a `slug` column; the new one has `id` + `script_id`.
-    // If we see `slug`, we know it's the old shape.
-    const betasCols = handle.prepare('PRAGMA table_info(betas)').all() as Array<{ name: string }>;
-    const isLegacyShape = betasCols.some((c) => c.name === 'slug');
-    if (!isLegacyShape) return;
-
-    for (const table of ['beta_deploys', 'beta_scripts', 'betas']) {
-        if (!legacyNames.includes(table)) continue;
-        const row = handle.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get() as { n: number };
-        if (row.n > 0) {
-            throw new Error(
-                `legacy ${table} still has ${row.n} rows — promote or rollback outstanding betas in the previous version before upgrading`
-            );
-        }
-    }
-    // Drop in FK-safe order.
-    for (const table of ['beta_deploys', 'beta_scripts', 'betas']) {
-        if (legacyNames.includes(table)) handle.exec(`DROP TABLE ${table}`);
-    }
-}
-
-// One-shot guard for the -beta/.OLD → DB-snapshot cutover. Legacy running/
-// ready-promote betas from the old code have -beta.<ext> and .OLD files on
-// disk with no corresponding beta_file_snapshots rows — restoring them under
-// the new rollback path would delete-instead-of-restore. If a legacy active
-// beta is detected on the first boot after upgrade, refuse to start so the
-// operator can rollback/promote under the old code. A settings sentinel marks
-// the cutover complete so subsequent boots with (legitimately new-scheme)
-// active betas aren't blocked.
-function assertSnapshotSchemeSafe(handle: Database.Database): void {
-    const done = handle.prepare("SELECT value FROM settings WHERE key = 'snapshots_v1'").get() as
-        { value: string } | undefined;
-    if (done) return;
-    const active = handle
-        .prepare("SELECT id FROM betas WHERE state IN ('running','ready-promote') LIMIT 1")
-        .get() as { id: number } | undefined;
-    if (active) {
-        throw new Error(
-            `close active beta ${active.id} before upgrading — snapshot scheme is incompatible with legacy -beta/.OLD state`
-        );
-    }
-    handle.prepare("INSERT INTO settings (key, value) VALUES ('snapshots_v1', '1')").run();
-}
-
-// Preserve old plans as reviewable checklists instead of silently passing checks
-// that the three-event protocol can no longer perform. Existing evidence stays
-// in history; active progress starts fresh under the new gameplay contract.
-function migrateGameTelemetry(handle: Database.Database): void {
-    if (handle.prepare("SELECT 1 FROM settings WHERE key = 'game_telemetry_v2'").get()) return;
-    handle.transaction(() => {
-        const convert = (raw: string): string => {
-            const plan = JSON.parse(raw) as BetaPlan;
-            plan.requirements = plan.requirements.map((r) => {
-                const { event: _event, ...rest } = r as BetaRequirement & { event?: string };
-                return ['feature', 'restart-budget', 'clean-logs'].includes(r.kind)
-                    ? { ...requirement('manual', r.id), label: `Review: ${r.label}`.slice(0, 200) }
-                    : rest;
-            });
-            return JSON.stringify(plan);
-        };
-        const plans = handle.prepare('SELECT beta_id, plan FROM beta_test_plans').all() as Array<{
-            beta_id: number;
-            plan: string;
-        }>;
-        for (const row of plans)
-            handle
-                .prepare('UPDATE beta_test_plans SET plan = ? WHERE beta_id = ?')
-                .run(convert(row.plan), row.beta_id);
-        const presets = handle.prepare('SELECT name, plan FROM beta_test_presets').all() as Array<{
-            name: string;
-            plan: string;
-        }>;
-        for (const row of presets)
-            handle
-                .prepare('UPDATE beta_test_presets SET plan = ? WHERE name = ?')
-                .run(convert(row.plan), row.name);
-        handle
-            .prepare(
-                `UPDATE beta_test_runs SET metrics = ?, cursors = '{}' WHERE retired_at IS NULL
-            AND beta_id IN (SELECT id FROM betas WHERE state IN ('running','ready-promote'))`
-            )
-            .run(JSON.stringify(emptyMetrics()));
-        handle.exec(`UPDATE beta_test_plans SET outcome = 'active', reason = 'Gameplay telemetry updated; collecting fresh script events'
-            WHERE outcome IN ('active','passed') AND beta_id IN (SELECT id FROM betas WHERE state IN ('running','ready-promote'));
-            UPDATE script_versions SET state = 'untested' WHERE state = 'tested'
-                AND id IN (SELECT bs.script_version_id FROM beta_scripts bs JOIN beta_test_plans p ON p.beta_id = bs.beta_id WHERE p.outcome = 'active')
-                AND id NOT IN (SELECT current_version_id FROM scripts WHERE current_version_id IS NOT NULL)
-                AND NOT EXISTS (SELECT 1 FROM beta_scripts bs JOIN betas b ON b.id = bs.beta_id
-                    WHERE bs.script_version_id = script_versions.id AND b.state = 'promoted');
-            UPDATE betas SET state = 'running' WHERE state = 'ready-promote' AND id IN (SELECT beta_id FROM beta_test_plans WHERE outcome = 'active');
-            UPDATE beta_servers SET stage = 'observing' WHERE stage = 'ready' AND beta_id IN (SELECT beta_id FROM beta_test_plans WHERE outcome = 'active');
-            INSERT INTO settings (key, value) VALUES ('game_telemetry_v2', '1');`);
-    })();
-}
-
-function migrateProvisioningActions(handle: Database.Database): void {
-    const table = handle
-        .prepare(
-            "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'server_deployments'"
-        )
-        .get() as { sql: string };
-    if (table.sql.includes("'rebuild'")) return;
-    // Rebuild the CHECK constraint without cascading into events, recipes, or
-    // collection members. Preserve rowids: they order same-server operations.
-    handle.pragma('foreign_keys = OFF');
-    try {
-        handle.transaction(() => {
-            handle.exec(
-                table.sql
-                    .replace('server_deployments', 'server_deployments_new')
-                    .replace(
-                        "'create', 'destroy'",
-                        "'create', 'start', 'restart', 'rebuild', 'stop', 'destroy'"
-                    )
-            );
-            const columns = (
-                handle.prepare('PRAGMA table_info(server_deployments)').all() as { name: string }[]
-            )
-                .map((column) => `"${column.name.replaceAll('"', '""')}"`)
-                .join(', ');
-            handle.exec(`INSERT INTO server_deployments_new (rowid, ${columns})
-                SELECT rowid, ${columns} FROM server_deployments;
-                DROP TABLE server_deployments;
-                ALTER TABLE server_deployments_new RENAME TO server_deployments;`);
-            if ((handle.pragma('foreign_key_check') as unknown[]).length)
-                throw new Error('Provisioning migration found broken references');
-        })();
-    } finally {
-        handle.pragma('foreign_keys = ON');
-    }
-}
-
-/** Rebuild constrained tables while preserving links, indexes, triggers, and row order. */
-function migrateWatchdogConstraints(handle: Database.Database): void {
-    for (const name of ['provisioning_sources', 'deployment_servers']) {
-        const { sql } = handle
-            .prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?")
-            .get(name) as { sql: string };
-        const replacement =
-            name === 'provisioning_sources'
-                ? sql.includes("'autoscaling'")
-                    ? sql
-                    : sql.replace(
-                          /'campaign','beta','maintenance'(?:,'watchdog')?/,
-                          "'campaign','beta','maintenance','watchdog','autoscaling'"
-                      )
-                : sql.replace(
-                      /server\s+TEXT NOT NULL REFERENCES servers\(name\)/,
-                      'server TEXT NOT NULL'
-                  );
-        if (sql === replacement) continue;
-        const dependent = handle
-            .prepare(
-                "SELECT sql FROM sqlite_master WHERE tbl_name = ? AND type IN ('index','trigger') AND sql IS NOT NULL"
-            )
-            .all(name) as { sql: string }[];
-        handle.pragma('foreign_keys = OFF');
-        try {
-            handle.transaction(() => {
-                handle.exec(replacement.replace(name, name + '_watchdog_new'));
-                handle.exec(
-                    `INSERT INTO ${name}_watchdog_new (rowid, ${(
-                        handle.prepare(`PRAGMA table_info(${name})`).all() as { name: string }[]
-                    )
-                        .map((col) => col.name)
-                        .join(', ')}) SELECT rowid, ${(
-                        handle.prepare(`PRAGMA table_info(${name})`).all() as { name: string }[]
-                    )
-                        .map((col) => col.name)
-                        .join(
-                            ', '
-                        )} FROM ${name}; DROP TABLE ${name}; ALTER TABLE ${name}_watchdog_new RENAME TO ${name};`
-                );
-                for (const object of dependent) handle.exec(object.sql);
-                if ((handle.pragma('foreign_key_check') as unknown[]).length)
-                    throw new Error('Watchdog migration found broken references');
-            })();
-        } finally {
-            handle.pragma('foreign_keys = ON');
-        }
-    }
-}
-
-function backfillDesiredState(handle: Database.Database): void {
-    if (handle.prepare("SELECT 1 FROM settings WHERE key = 'watchdog_desired_state_v1'").get())
-        return;
-    handle.transaction(() => {
-        // A failed stop may have reached the host agent. Preserve that explicit intent.
-        handle.exec(`UPDATE servers SET desired_state = 'stopped' WHERE 'stop' = (
-            SELECT action FROM server_deployments d WHERE d.server = servers.name AND d.state != 'cancelled'
-            AND d.action IN ('create','start','restart','rebuild','stop')
-            ORDER BY d.rowid DESC LIMIT 1);
-            INSERT INTO settings (key, value) VALUES ('watchdog_desired_state_v1', '1');`);
-    })();
-}
-
 export function db(): Database.Database {
     if (_db) return _db;
 
@@ -426,215 +24,7 @@ export function db(): Database.Database {
         handle.pragma('auto_vacuum = INCREMENTAL');
         handle.pragma('foreign_keys = ON');
         tuneMigrationConnection(handle);
-        dropLegacyBetaTables(handle);
-        handle.exec(schemaSql);
-        migrateProvisioningActions(handle);
-        migrateWatchdogConstraints(handle);
-        migrateTable(handle, 'deployment_files', [
-            {
-                name: 'snapshot_pending',
-                ddl: 'ALTER TABLE deployment_files ADD COLUMN snapshot_pending INTEGER NOT NULL DEFAULT 0'
-            }
-        ]);
-        migrateTable(handle, 'restart_rollout', [
-            {
-                name: 'operation_id',
-                ddl: 'ALTER TABLE restart_rollout ADD COLUMN operation_id TEXT'
-            }
-        ]);
-        migrateTable(handle, 'server_deployments', [
-            {
-                name: 'requested_by',
-                ddl: 'ALTER TABLE server_deployments ADD COLUMN requested_by TEXT'
-            },
-            {
-                name: 'submitted_at',
-                ddl: 'ALTER TABLE server_deployments ADD COLUMN submitted_at TEXT'
-            },
-            {
-                name: 'checked_at',
-                ddl: 'ALTER TABLE server_deployments ADD COLUMN checked_at TEXT'
-            },
-            { name: 'players', ddl: 'ALTER TABLE server_deployments ADD COLUMN players INTEGER' },
-            { name: 'phase_key', ddl: 'ALTER TABLE server_deployments ADD COLUMN phase_key TEXT' },
-            {
-                name: 'phase_started_at',
-                ddl: 'ALTER TABLE server_deployments ADD COLUMN phase_started_at TEXT'
-            },
-            {
-                name: 'observed_at',
-                ddl: 'ALTER TABLE server_deployments ADD COLUMN observed_at TEXT'
-            },
-            {
-                name: 'observation_json',
-                ddl: 'ALTER TABLE server_deployments ADD COLUMN observation_json TEXT'
-            }
-        ]);
-        migrateTable(handle, 'server_deployment_events', [
-            { name: 'kind', ddl: 'ALTER TABLE server_deployment_events ADD COLUMN kind TEXT' },
-            {
-                name: 'phase_key',
-                ddl: 'ALTER TABLE server_deployment_events ADD COLUMN phase_key TEXT'
-            },
-            {
-                name: 'details_json',
-                ddl: 'ALTER TABLE server_deployment_events ADD COLUMN details_json TEXT'
-            }
-        ]);
-        for (const table of ['deployment_servers', 'beta_servers', 'maintenance_jobs']) {
-            migrateTable(handle, table, [
-                {
-                    name: 'provisioning_id',
-                    ddl: `ALTER TABLE ${table} ADD COLUMN provisioning_id TEXT`
-                }
-            ]);
-        }
-        migrateTable(handle, 'maintenance_jobs', [
-            {
-                name: 'kind',
-                ddl: "ALTER TABLE maintenance_jobs ADD COLUMN kind TEXT NOT NULL DEFAULT 'legacy'"
-            },
-            {
-                name: 'origin',
-                ddl: "ALTER TABLE maintenance_jobs ADD COLUMN origin TEXT NOT NULL DEFAULT 'manual'"
-            }
-        ]);
-        migrateServers(handle);
-        // Old snippets may contain player addresses, including hex-encoded bytes.
-        // Discard them once; newly retained diagnostics are sanitized failure replies only.
-        if (
-            !handle.prepare("SELECT 1 FROM settings WHERE key='rcon_private_diagnostics_v1'").get()
-        ) {
-            handle.transaction(() => {
-                handle.exec(`UPDATE servers SET last_reply_snippet=NULL;
-                    UPDATE servers SET last_error='bad-reply:unparseable print reply'
-                        WHERE last_error LIKE 'bad-reply:print reply not recognized:%';
-                    INSERT INTO settings(key,value) VALUES('rcon_private_diagnostics_v1','1');`);
-            })();
-        }
-        backfillDesiredState(handle);
-        // Column additions must run BEFORE any statement that references the
-        // new columns. schema.sql cannot include those references — see the
-        // comment there.
-        migrateTable(handle, 'scripts', SCRIPTS_COLUMNS);
-        migrateTable(handle, 'script_versions', SCRIPT_VERSIONS_COLUMNS);
-        migrateTable(handle, 'beta_scripts', BETA_SCRIPTS_COLUMNS);
-        migrateTable(handle, 'beta_test_runs', [
-            {
-                name: 'revision',
-                ddl: 'ALTER TABLE beta_test_runs ADD COLUMN revision INTEGER NOT NULL DEFAULT 1'
-            }
-        ]);
-        migrateTable(handle, 'deployment_scripts', DEPLOYMENT_SCRIPTS_COLUMNS);
-        migrateTable(handle, 'deployments', DEPLOYMENTS_COLUMNS);
-        // Older databases gain rolled_back_by above, after schema.sql runs.
-        handle.exec(
-            'CREATE INDEX IF NOT EXISTS idx_deployments_rolled_back_by ON deployments(rolled_back_by)'
-        );
-        migrateTable(handle, 'server_launch_collections', [
-            {
-                name: 'cancelled_at',
-                ddl: 'ALTER TABLE server_launch_collections ADD COLUMN cancelled_at TEXT'
-            },
-            {
-                name: 'mode',
-                ddl: "ALTER TABLE server_launch_collections ADD COLUMN mode TEXT NOT NULL DEFAULT 'fill'"
-            },
-            {
-                name: 'retained_servers',
-                ddl: "ALTER TABLE server_launch_collections ADD COLUMN retained_servers TEXT NOT NULL DEFAULT '[]'"
-            }
-        ]);
-        migrateTable(handle, 'server_launch_recipes', [
-            {
-                name: 'recipe_summary',
-                ddl: 'ALTER TABLE server_launch_recipes ADD COLUMN recipe_summary TEXT'
-            }
-        ]);
-        migrateServerHistory(handle);
-        migrateTable(handle, 'server_collection_previews', [
-            {
-                name: 'mode',
-                ddl: "ALTER TABLE server_collection_previews ADD COLUMN mode TEXT NOT NULL DEFAULT 'fill'"
-            },
-            {
-                name: 'fleet_snapshot',
-                ddl: 'ALTER TABLE server_collection_previews ADD COLUMN fleet_snapshot TEXT'
-            }
-        ]);
-        migrateTable(handle, 'server_telemetry', [
-            { name: 'payload', ddl: 'ALTER TABLE server_telemetry ADD COLUMN payload TEXT' }
-        ]);
-        // Kind-referencing indexes: safe here because migrateTable above just
-        // ALTER'd the column into existence if it was missing.
-        handle.exec(
-            `CREATE UNIQUE INDEX IF NOT EXISTS idx_scripts_one_baseline_per_scope
-                 ON scripts(scope_type, scope_value) WHERE kind = 'baseline'`
-        );
-        handle.exec(`CREATE INDEX IF NOT EXISTS idx_scripts_kind ON scripts(kind)`);
-        backfillMultiScriptJoins(handle);
-        assertSnapshotSchemeSafe(handle);
-        migrateGameTelemetry(handle);
-        migrateTable(handle, 'leaderboard_matches', [
-            {
-                name: 'start_players',
-                ddl: 'ALTER TABLE leaderboard_matches ADD COLUMN start_players INTEGER'
-            }
-        ]);
-        migrateTable(handle, 'leaderboard_match_players', [
-            {
-                name: 'first_observed_round',
-                ddl: 'ALTER TABLE leaderboard_match_players ADD COLUMN first_observed_round INTEGER'
-            },
-            {
-                name: 'present_at_start',
-                ddl: 'ALTER TABLE leaderboard_match_players ADD COLUMN present_at_start INTEGER'
-            }
-        ]);
-        backfillLeaderboard(handle);
-        initializeFleetSettings(handle);
-        migrationStep('native instance schema and file plans', () =>
-            migrateNativeInstances(handle)
-        );
-        migrationStep('per-game server key pools', () => migrateServerKeys(handle));
-        migrationStep('autoscaling schema', () => ensureAutoscalingSchema(handle));
-        migrationStep('rebalancing schema', () => ensureRebalancingSchema(handle));
-        // File-blob migration removes the legacy content column altogether.
-        // Reordering it first would unnecessarily copy every artifact twice.
-        migrateFileBlobs(handle);
-        // Lifecycle history is retained indefinitely. Admission and status reads
-        // must narrow by server or active state instead of scanning that history.
-        // Install after migrations that rebuild this table or add server_deleted_at.
-        handle.exec(`CREATE INDEX IF NOT EXISTS idx_server_deployments_server
-            ON server_deployments(server, server_deleted_at);
-            CREATE INDEX IF NOT EXISTS idx_server_deployments_state
-            ON server_deployments(state, action, server_deleted_at);
-            CREATE INDEX IF NOT EXISTS idx_server_deployments_server_state
-            ON server_deployments(server, server_deleted_at, state, action);
-            CREATE INDEX IF NOT EXISTS idx_server_deployments_started_at
-            ON server_deployments(started_at);
-            CREATE INDEX IF NOT EXISTS idx_server_deployments_submission
-            ON server_deployments(server, server_deleted_at, action, submitted_at);
-            CREATE INDEX IF NOT EXISTS idx_server_deployments_finished_at
-            ON server_deployments(finished_at) WHERE server_deleted_at IS NULL;
-            CREATE INDEX IF NOT EXISTS idx_server_deployments_unsettled
-            ON server_deployments(id) WHERE state NOT IN ('done','warning','cancelled');`);
-        installPerformanceIndexes(handle);
-        installReportRevisions(handle);
-        migrationStep('retention clocks and indexes', () =>
-            retentionClocks(handle, {
-                deployments: ['started_at', 'finished_at'],
-                server_deployments: ['started_at', 'finished_at'],
-                maintenance_jobs: ['requested_at', 'finished_at'],
-                watchdog_incidents: ['first_seen_at', 'finished_at'],
-                leaderboard_matches: ['started_at', 'last_received_at', 'ended_at'],
-                betas: ['opened_at', 'closed_at'],
-                script_versions: ['uploaded_at'],
-                retention_controls: ['resolved_at']
-            })
-        );
-        // Existing databases require one rebuild to gain the incremental-vacuum page map.
-        enableIncrementalVacuum(handle);
+        runMigrations(handle, migrations);
         handle.pragma('optimize = 0x10002');
         handle.pragma('shrink_memory');
         tuneConnection(handle);

src/lib/server/db/legacy.ts

@@ -0,0 +1,586 @@
+import type Database from 'better-sqlite3';
+import schemaSql from './schema.sql?raw';
+import { requirement, type BetaPlan, type BetaRequirement } from '../../beta-plan.js';
+import { emptyMetrics } from '../fleet/beta-evaluation.js';
+import { backfillLeaderboard } from '../fleet/leaderboard-ingest.js';
+import { initializeFleetSettings } from './fleet-settings.js';
+import { migrateServerHistory } from './server-history.js';
+
+// Compatibility bridge for unversioned databases. Historical column checks and
+// sentinels distinguish releases that already applied destructive backfills.
+// Freeze this bridge; add future upgrades to the ordered list in migrations.ts.
+
+// Desired shape of the `servers` table. Every column here is added to the
+// legacy table if missing — introspection via PRAGMA table_info handles
+// both fresh DBs and legacy DBs that predate any given column. CREATE TABLE
+// IF NOT EXISTS in schema.sql is a no-op on existing tables, so it can't
+// backfill columns; this can.
+const SERVERS_COLUMNS: Array<{ name: string; ddl: string }> = [
+    {
+        name: 'container_checked_at',
+        ddl: 'ALTER TABLE servers ADD COLUMN container_checked_at TEXT'
+    },
+    { name: 'container_state', ddl: 'ALTER TABLE servers ADD COLUMN container_state TEXT' },
+    {
+        name: 'desired_state',
+        ddl: "ALTER TABLE servers ADD COLUMN desired_state TEXT NOT NULL DEFAULT 'running' CHECK (desired_state IN ('running','stopped'))"
+    },
+    // Base columns that shipped in the very first schema stay here for parity
+    // with fresh installs — no ALTER is issued if they're already present.
+    { name: 'game_port', ddl: 'ALTER TABLE servers ADD COLUMN game_port INTEGER' },
+    { name: 'rcon_host', ddl: 'ALTER TABLE servers ADD COLUMN rcon_host TEXT' },
+    { name: 'last_players', ddl: 'ALTER TABLE servers ADD COLUMN last_players INTEGER' },
+    { name: 'last_checked_at', ddl: 'ALTER TABLE servers ADD COLUMN last_checked_at TEXT' },
+    // Post-v0.1 additions from the perk-a-cola/diagnostics work
+    { name: 'last_map', ddl: 'ALTER TABLE servers ADD COLUMN last_map TEXT' },
+    { name: 'last_gametype', ddl: 'ALTER TABLE servers ADD COLUMN last_gametype TEXT' },
+    { name: 'last_roster', ddl: 'ALTER TABLE servers ADD COLUMN last_roster TEXT' },
+    { name: 'last_seen_at', ddl: 'ALTER TABLE servers ADD COLUMN last_seen_at TEXT' },
+    { name: 'last_error', ddl: 'ALTER TABLE servers ADD COLUMN last_error TEXT' },
+    {
+        name: 'rcon_failures',
+        ddl: 'ALTER TABLE servers ADD COLUMN rcon_failures INTEGER NOT NULL DEFAULT 0'
+    },
+    { name: 'last_reply_snippet', ddl: 'ALTER TABLE servers ADD COLUMN last_reply_snippet TEXT' },
+    // Script-scope columns — static per server, populated via server-edit UI.
+    { name: 'game', ddl: 'ALTER TABLE servers ADD COLUMN game TEXT' },
+    { name: 'map', ddl: 'ALTER TABLE servers ADD COLUMN map TEXT' },
+    // Provisioning columns — populated when EC creates the deployment.
+    { name: 'game_mode', ddl: 'ALTER TABLE servers ADD COLUMN game_mode TEXT' },
+    { name: 'map_slug', ddl: 'ALTER TABLE servers ADD COLUMN map_slug TEXT' },
+    { name: 'host_dir', ddl: 'ALTER TABLE servers ADD COLUMN host_dir TEXT' },
+    { name: 'config_file', ddl: 'ALTER TABLE servers ADD COLUMN config_file TEXT' },
+    { name: 'game_id', ddl: 'ALTER TABLE servers ADD COLUMN game_id TEXT' },
+    { name: 'image', ddl: 'ALTER TABLE servers ADD COLUMN image TEXT' },
+    { name: 'created_by', ddl: 'ALTER TABLE servers ADD COLUMN created_by TEXT' },
+    { name: 'destroyed_at', ddl: 'ALTER TABLE servers ADD COLUMN destroyed_at TEXT' },
+    // Occupancy + match timers — see schema.sql for semantics.
+    { name: 'active_since', ddl: 'ALTER TABLE servers ADD COLUMN active_since TEXT' },
+    { name: 'inactive_since', ddl: 'ALTER TABLE servers ADD COLUMN inactive_since TEXT' },
+    { name: 'game_started_at', ddl: 'ALTER TABLE servers ADD COLUMN game_started_at TEXT' },
+    { name: 'game_ended_at', ddl: 'ALTER TABLE servers ADD COLUMN game_ended_at TEXT' },
+    { name: 'game_cycle_key', ddl: 'ALTER TABLE servers ADD COLUMN game_cycle_key TEXT' }
+];
+
+function migrateServers(handle: Database.Database): void {
+    const rows = handle.prepare('PRAGMA table_info(servers)').all() as Array<{ name: string }>;
+    const existing = new Set(rows.map((r) => r.name));
+    for (const col of SERVERS_COLUMNS) {
+        if (!existing.has(col.name)) {
+            handle.exec(col.ddl);
+        }
+    }
+    // Retire external-backend registry fields, including required fields that
+    // would otherwise prevent native inserts into an upgraded database.
+    const retired = new Set(['komodo_type', 'komodo_name', 'komodo_server']);
+    handle.transaction(() => {
+        for (const column of rows) {
+            if (retired.has(column.name))
+                handle.exec(
+                    `ALTER TABLE servers DROP COLUMN "${column.name.replaceAll('"', '""')}"`
+                );
+        }
+    })();
+}
+
+// Additive columns on tables the script model owns. Same pattern as
+// migrateServers — CREATE TABLE IF NOT EXISTS won't backfill columns onto
+// pre-existing tables, so we introspect and ALTER as needed.
+const SCRIPTS_COLUMNS: Array<{ name: string; ddl: string }> = [
+    { name: 'kind', ddl: "ALTER TABLE scripts ADD COLUMN kind TEXT NOT NULL DEFAULT 'script'" }
+];
+
+const SCRIPT_VERSIONS_COLUMNS: Array<{ name: string; ddl: string }> = [
+    { name: 'release_version', ddl: 'ALTER TABLE script_versions ADD COLUMN release_version TEXT' },
+    // state was added post-launch to make untested/tested/test-failed visible
+    // in the UI. Existing rows default to 'untested' — this is safe because
+    // any real promoted version's script has current_version_id set (which is
+    // the authoritative "promoted" signal), and any version already gated
+    // through a ready-promote beta will be re-marked next time that state
+    // machine fires.
+    {
+        name: 'state',
+        ddl: "ALTER TABLE script_versions ADD COLUMN state TEXT NOT NULL DEFAULT 'untested'"
+    },
+    {
+        name: 'kind',
+        ddl: "ALTER TABLE script_versions ADD COLUMN kind TEXT NOT NULL DEFAULT 'script'"
+    }
+];
+
+const BETA_SCRIPTS_COLUMNS: Array<{ name: string; ddl: string }> = [
+    { name: 'kind', ddl: "ALTER TABLE beta_scripts ADD COLUMN kind TEXT NOT NULL DEFAULT 'script'" }
+];
+
+const DEPLOYMENT_SCRIPTS_COLUMNS: Array<{ name: string; ddl: string }> = [
+    {
+        name: 'kind',
+        ddl: "ALTER TABLE deployment_scripts ADD COLUMN kind TEXT NOT NULL DEFAULT 'script'"
+    }
+];
+
+const DEPLOYMENTS_COLUMNS: Array<{ name: string; ddl: string }> = [
+    {
+        name: 'script_id',
+        ddl: 'ALTER TABLE deployments ADD COLUMN script_id INTEGER REFERENCES scripts(id)'
+    },
+    {
+        name: 'script_version_id',
+        ddl: 'ALTER TABLE deployments ADD COLUMN script_version_id INTEGER REFERENCES script_versions(id)'
+    },
+    {
+        name: 'prior_version_id',
+        ddl: 'ALTER TABLE deployments ADD COLUMN prior_version_id INTEGER REFERENCES script_versions(id)'
+    },
+    {
+        name: 'beta_id',
+        ddl: 'ALTER TABLE deployments ADD COLUMN beta_id INTEGER REFERENCES betas(id)'
+    },
+    {
+        name: 'rolled_back_by',
+        ddl: 'ALTER TABLE deployments ADD COLUMN rolled_back_by TEXT REFERENCES deployments(id)'
+    }
+];
+
+function migrateTable(
+    handle: Database.Database,
+    table: string,
+    cols: Array<{ name: string; ddl: string }>
+): void {
+    const rows = handle.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+    const existing = new Set(rows.map((r) => r.name));
+    for (const col of cols) {
+        if (!existing.has(col.name)) handle.exec(col.ddl);
+    }
+}
+
+// Backfill the multi-script join tables from the legacy single-script columns.
+// Existing bundle membership is authoritative. Only single-script betas can
+// inherit server membership from the deprecated primary-script columns.
+function backfillMultiScriptJoins(handle: Database.Database): void {
+    handle.exec(
+        `INSERT INTO beta_scripts (beta_id, script_id, script_version_id)
+         SELECT b.id, b.script_id, b.script_version_id
+         FROM betas b
+         WHERE b.script_id IS NOT NULL
+           AND NOT EXISTS (SELECT 1 FROM beta_scripts bs WHERE bs.beta_id = b.id)`
+    );
+    handle.exec(
+        `INSERT INTO beta_server_scripts (beta_id, server, script_id, had_original, prior_version_id)
+         SELECT bs.beta_id, bs.server, b.script_id, bs.had_original, bs.prior_version_id
+         FROM beta_servers bs
+         JOIN betas b ON b.id = bs.beta_id
+         WHERE b.script_id IS NOT NULL
+           AND bs.server_deleted_at IS NULL
+           AND EXISTS (SELECT 1 FROM servers WHERE name = bs.server)
+           AND (SELECT COUNT(*) FROM beta_scripts x WHERE x.beta_id = b.id) = 1
+           AND EXISTS (SELECT 1 FROM beta_scripts x WHERE x.beta_id = b.id AND x.script_id = b.script_id)
+           AND NOT EXISTS (
+             SELECT 1 FROM beta_server_scripts x
+             WHERE x.beta_id = bs.beta_id AND x.server = bs.server
+           )`
+    );
+    handle.exec(
+        `INSERT INTO deployment_scripts (deployment_id, script_id, script_version_id, prior_version_id)
+         SELECT d.id, d.script_id, d.script_version_id, d.prior_version_id
+         FROM deployments d
+         WHERE d.script_id IS NOT NULL
+           AND d.script_version_id IS NOT NULL
+           AND NOT EXISTS (SELECT 1 FROM deployment_scripts ds WHERE ds.deployment_id = d.id)`
+    );
+}
+
+// The pre-script-model beta tables had entirely different shapes (slug PK,
+// beta_scripts, beta_deploys). schema.sql defines the new shape; CREATE TABLE
+// IF NOT EXISTS is a no-op if the old tables already exist, so we have to
+// detect and drop them first. Any outstanding rows abort the boot so the
+// operator can promote/rollback in the old app before upgrading.
+function dropLegacyBetaTables(handle: Database.Database): void {
+    const legacy = handle
+        .prepare(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('betas','beta_scripts','beta_deploys')"
+        )
+        .all() as Array<{ name: string }>;
+    if (legacy.length === 0) return;
+
+    const legacyNames = legacy.map((r) => r.name);
+    // The old `betas` table had a `slug` column; the new one has `id` + `script_id`.
+    // If we see `slug`, we know it's the old shape.
+    const betasCols = handle.prepare('PRAGMA table_info(betas)').all() as Array<{ name: string }>;
+    const isLegacyShape = betasCols.some((c) => c.name === 'slug');
+    if (!isLegacyShape) return;
+
+    for (const table of ['beta_deploys', 'beta_scripts', 'betas']) {
+        if (!legacyNames.includes(table)) continue;
+        const row = handle.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get() as { n: number };
+        if (row.n > 0) {
+            throw new Error(
+                `legacy ${table} still has ${row.n} rows — promote or rollback outstanding betas in the previous version before upgrading`
+            );
+        }
+    }
+    // Drop in FK-safe order.
+    for (const table of ['beta_deploys', 'beta_scripts', 'betas']) {
+        if (legacyNames.includes(table)) handle.exec(`DROP TABLE ${table}`);
+    }
+}
+
+// One-shot guard for the -beta/.OLD → DB-snapshot cutover. Legacy running/
+// ready-promote betas from the old code have -beta.<ext> and .OLD files on
+// disk with no corresponding beta_file_snapshots rows — restoring them under
+// the new rollback path would delete-instead-of-restore. If a legacy active
+// beta is detected on the first boot after upgrade, refuse to start so the
+// operator can rollback/promote under the old code. A settings sentinel marks
+// the cutover complete so subsequent boots with (legitimately new-scheme)
+// active betas aren't blocked.
+function assertSnapshotSchemeSafe(handle: Database.Database): void {
+    const done = handle.prepare("SELECT value FROM settings WHERE key = 'snapshots_v1'").get() as
+        { value: string } | undefined;
+    if (done) return;
+    const active = handle
+        .prepare("SELECT id FROM betas WHERE state IN ('running','ready-promote') LIMIT 1")
+        .get() as { id: number } | undefined;
+    if (active) {
+        throw new Error(
+            `close active beta ${active.id} before upgrading — snapshot scheme is incompatible with legacy -beta/.OLD state`
+        );
+    }
+    handle.prepare("INSERT INTO settings (key, value) VALUES ('snapshots_v1', '1')").run();
+}
+
+// Preserve old plans as reviewable checklists instead of silently passing checks
+// that the three-event protocol can no longer perform. Existing evidence stays
+// in history; active progress starts fresh under the new gameplay contract.
+function migrateGameTelemetry(handle: Database.Database): void {
+    if (handle.prepare("SELECT 1 FROM settings WHERE key = 'game_telemetry_v2'").get()) return;
+    handle.transaction(() => {
+        const convert = (raw: string): string => {
+            const plan = JSON.parse(raw) as BetaPlan;
+            plan.requirements = plan.requirements.map((r) => {
+                const { event: _event, ...rest } = r as BetaRequirement & { event?: string };
+                return ['feature', 'restart-budget', 'clean-logs'].includes(r.kind)
+                    ? { ...requirement('manual', r.id), label: `Review: ${r.label}`.slice(0, 200) }
+                    : rest;
+            });
+            return JSON.stringify(plan);
+        };
+        const plans = handle.prepare('SELECT beta_id, plan FROM beta_test_plans').all() as Array<{
+            beta_id: number;
+            plan: string;
+        }>;
+        for (const row of plans)
+            handle
+                .prepare('UPDATE beta_test_plans SET plan = ? WHERE beta_id = ?')
+                .run(convert(row.plan), row.beta_id);
+        const presets = handle.prepare('SELECT name, plan FROM beta_test_presets').all() as Array<{
+            name: string;
+            plan: string;
+        }>;
+        for (const row of presets)
+            handle
+                .prepare('UPDATE beta_test_presets SET plan = ? WHERE name = ?')
+                .run(convert(row.plan), row.name);
+        handle
+            .prepare(
+                `UPDATE beta_test_runs SET metrics = ?, cursors = '{}' WHERE retired_at IS NULL
+            AND beta_id IN (SELECT id FROM betas WHERE state IN ('running','ready-promote'))`
+            )
+            .run(JSON.stringify(emptyMetrics()));
+        handle.exec(`UPDATE beta_test_plans SET outcome = 'active', reason = 'Gameplay telemetry updated; collecting fresh script events'
+            WHERE outcome IN ('active','passed') AND beta_id IN (SELECT id FROM betas WHERE state IN ('running','ready-promote'));
+            UPDATE script_versions SET state = 'untested' WHERE state = 'tested'
+                AND id IN (SELECT bs.script_version_id FROM beta_scripts bs JOIN beta_test_plans p ON p.beta_id = bs.beta_id WHERE p.outcome = 'active')
+                AND id NOT IN (SELECT current_version_id FROM scripts WHERE current_version_id IS NOT NULL)
+                AND NOT EXISTS (SELECT 1 FROM beta_scripts bs JOIN betas b ON b.id = bs.beta_id
+                    WHERE bs.script_version_id = script_versions.id AND b.state = 'promoted');
+            UPDATE betas SET state = 'running' WHERE state = 'ready-promote' AND id IN (SELECT beta_id FROM beta_test_plans WHERE outcome = 'active');
+            UPDATE beta_servers SET stage = 'observing' WHERE stage = 'ready' AND beta_id IN (SELECT beta_id FROM beta_test_plans WHERE outcome = 'active');
+            INSERT INTO settings (key, value) VALUES ('game_telemetry_v2', '1');`);
+    })();
+}
+
+function migrateProvisioningActions(handle: Database.Database): void {
+    const table = handle
+        .prepare(
+            "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'server_deployments'"
+        )
+        .get() as { sql: string };
+    if (table.sql.includes("'rebuild'")) return;
+    // Rebuild the CHECK constraint without cascading into events, recipes, or
+    // collection members. Preserve rowids: they order same-server operations.
+    handle.pragma('foreign_keys = OFF');
+    try {
+        handle.transaction(() => {
+            handle.exec(
+                table.sql
+                    .replace('server_deployments', 'server_deployments_new')
+                    .replace(
+                        "'create', 'destroy'",
+                        "'create', 'start', 'restart', 'rebuild', 'stop', 'destroy'"
+                    )
+            );
+            const columns = (
+                handle.prepare('PRAGMA table_info(server_deployments)').all() as { name: string }[]
+            )
+                .map((column) => `"${column.name.replaceAll('"', '""')}"`)
+                .join(', ');
+            handle.exec(`INSERT INTO server_deployments_new (rowid, ${columns})
+                SELECT rowid, ${columns} FROM server_deployments;
+                DROP TABLE server_deployments;
+                ALTER TABLE server_deployments_new RENAME TO server_deployments;`);
+            if ((handle.pragma('foreign_key_check') as unknown[]).length)
+                throw new Error('Provisioning migration found broken references');
+        })();
+    } finally {
+        handle.pragma('foreign_keys = ON');
+    }
+}
+
+/** Rebuild constrained tables while preserving links, indexes, triggers, and row order. */
+function migrateWatchdogConstraints(handle: Database.Database): void {
+    for (const name of ['provisioning_sources', 'deployment_servers']) {
+        const { sql } = handle
+            .prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?")
+            .get(name) as { sql: string };
+        const replacement =
+            name === 'provisioning_sources'
+                ? sql.includes("'autoscaling'")
+                    ? sql
+                    : sql.replace(
+                          /'campaign','beta','maintenance'(?:,'watchdog')?/,
+                          "'campaign','beta','maintenance','watchdog','autoscaling'"
+                      )
+                : sql.replace(
+                      /server\s+TEXT NOT NULL REFERENCES servers\(name\)/,
+                      'server TEXT NOT NULL'
+                  );
+        if (sql === replacement) continue;
+        const dependent = handle
+            .prepare(
+                "SELECT sql FROM sqlite_master WHERE tbl_name = ? AND type IN ('index','trigger') AND sql IS NOT NULL"
+            )
+            .all(name) as { sql: string }[];
+        handle.pragma('foreign_keys = OFF');
+        try {
+            handle.transaction(() => {
+                handle.exec(replacement.replace(name, name + '_watchdog_new'));
+                handle.exec(
+                    `INSERT INTO ${name}_watchdog_new (rowid, ${(
+                        handle.prepare(`PRAGMA table_info(${name})`).all() as { name: string }[]
+                    )
+                        .map((col) => col.name)
+                        .join(', ')}) SELECT rowid, ${(
+                        handle.prepare(`PRAGMA table_info(${name})`).all() as { name: string }[]
+                    )
+                        .map((col) => col.name)
+                        .join(
+                            ', '
+                        )} FROM ${name}; DROP TABLE ${name}; ALTER TABLE ${name}_watchdog_new RENAME TO ${name};`
+                );
+                for (const object of dependent) handle.exec(object.sql);
+                if ((handle.pragma('foreign_key_check') as unknown[]).length)
+                    throw new Error('Watchdog migration found broken references');
+            })();
+        } finally {
+            handle.pragma('foreign_keys = ON');
+        }
+    }
+}
+
+function backfillDesiredState(handle: Database.Database): void {
+    if (handle.prepare("SELECT 1 FROM settings WHERE key = 'watchdog_desired_state_v1'").get())
+        return;
+    handle.transaction(() => {
+        // A failed stop may have reached the host agent. Preserve that explicit intent.
+        handle.exec(`UPDATE servers SET desired_state = 'stopped' WHERE 'stop' = (
+            SELECT action FROM server_deployments d WHERE d.server = servers.name AND d.state != 'cancelled'
+            AND d.action IN ('create','start','restart','rebuild','stop')
+            ORDER BY d.rowid DESC LIMIT 1);
+            INSERT INTO settings (key, value) VALUES ('watchdog_desired_state_v1', '1');`);
+    })();
+}
+
+export function migrateLegacySchema(handle: Database.Database): void {
+    dropLegacyBetaTables(handle);
+    handle.exec(schemaSql);
+    migrateProvisioningActions(handle);
+    migrateWatchdogConstraints(handle);
+    migrateTable(handle, 'deployment_files', [
+        {
+            name: 'snapshot_pending',
+            ddl: 'ALTER TABLE deployment_files ADD COLUMN snapshot_pending INTEGER NOT NULL DEFAULT 0'
+        }
+    ]);
+    migrateTable(handle, 'restart_rollout', [
+        {
+            name: 'operation_id',
+            ddl: 'ALTER TABLE restart_rollout ADD COLUMN operation_id TEXT'
+        }
+    ]);
+    migrateTable(handle, 'server_deployments', [
+        {
+            name: 'requested_by',
+            ddl: 'ALTER TABLE server_deployments ADD COLUMN requested_by TEXT'
+        },
+        {
+            name: 'submitted_at',
+            ddl: 'ALTER TABLE server_deployments ADD COLUMN submitted_at TEXT'
+        },
+        {
+            name: 'checked_at',
+            ddl: 'ALTER TABLE server_deployments ADD COLUMN checked_at TEXT'
+        },
+        { name: 'players', ddl: 'ALTER TABLE server_deployments ADD COLUMN players INTEGER' },
+        { name: 'phase_key', ddl: 'ALTER TABLE server_deployments ADD COLUMN phase_key TEXT' },
+        {
+            name: 'phase_started_at',
+            ddl: 'ALTER TABLE server_deployments ADD COLUMN phase_started_at TEXT'
+        },
+        {
+            name: 'observed_at',
+            ddl: 'ALTER TABLE server_deployments ADD COLUMN observed_at TEXT'
+        },
+        {
+            name: 'observation_json',
+            ddl: 'ALTER TABLE server_deployments ADD COLUMN observation_json TEXT'
+        }
+    ]);
+    migrateTable(handle, 'server_deployment_events', [
+        { name: 'kind', ddl: 'ALTER TABLE server_deployment_events ADD COLUMN kind TEXT' },
+        {
+            name: 'phase_key',
+            ddl: 'ALTER TABLE server_deployment_events ADD COLUMN phase_key TEXT'
+        },
+        {
+            name: 'details_json',
+            ddl: 'ALTER TABLE server_deployment_events ADD COLUMN details_json TEXT'
+        }
+    ]);
+    for (const table of ['deployment_servers', 'beta_servers', 'maintenance_jobs']) {
+        migrateTable(handle, table, [
+            {
+                name: 'provisioning_id',
+                ddl: `ALTER TABLE ${table} ADD COLUMN provisioning_id TEXT`
+            }
+        ]);
+    }
+    migrateTable(handle, 'maintenance_jobs', [
+        {
+            name: 'kind',
+            ddl: "ALTER TABLE maintenance_jobs ADD COLUMN kind TEXT NOT NULL DEFAULT 'legacy'"
+        },
+        {
+            name: 'origin',
+            ddl: "ALTER TABLE maintenance_jobs ADD COLUMN origin TEXT NOT NULL DEFAULT 'manual'"
+        }
+    ]);
+    migrateServers(handle);
+    // Old snippets may contain player addresses, including hex-encoded bytes.
+    // Discard them once; newly retained diagnostics are sanitized failure replies only.
+    if (!handle.prepare("SELECT 1 FROM settings WHERE key='rcon_private_diagnostics_v1'").get()) {
+        handle.transaction(() => {
+            handle.exec(`UPDATE servers SET last_reply_snippet=NULL;
+                    UPDATE servers SET last_error='bad-reply:unparseable print reply'
+                        WHERE last_error LIKE 'bad-reply:print reply not recognized:%';
+                    INSERT INTO settings(key,value) VALUES('rcon_private_diagnostics_v1','1');`);
+        })();
+    }
+    backfillDesiredState(handle);
+    migrateTable(handle, 'scripts', SCRIPTS_COLUMNS);
+    migrateTable(handle, 'script_versions', SCRIPT_VERSIONS_COLUMNS);
+    migrateTable(handle, 'beta_scripts', BETA_SCRIPTS_COLUMNS);
+    migrateTable(handle, 'beta_test_runs', [
+        {
+            name: 'revision',
+            ddl: 'ALTER TABLE beta_test_runs ADD COLUMN revision INTEGER NOT NULL DEFAULT 1'
+        }
+    ]);
+    migrateTable(handle, 'deployment_scripts', DEPLOYMENT_SCRIPTS_COLUMNS);
+    migrateTable(handle, 'deployments', DEPLOYMENTS_COLUMNS);
+    // Older databases gain rolled_back_by above, after schema.sql runs.
+    handle.exec(
+        'CREATE INDEX IF NOT EXISTS idx_deployments_rolled_back_by ON deployments(rolled_back_by)'
+    );
+    migrateTable(handle, 'server_launch_collections', [
+        {
+            name: 'cancelled_at',
+            ddl: 'ALTER TABLE server_launch_collections ADD COLUMN cancelled_at TEXT'
+        },
+        {
+            name: 'mode',
+            ddl: "ALTER TABLE server_launch_collections ADD COLUMN mode TEXT NOT NULL DEFAULT 'fill'"
+        },
+        {
+            name: 'retained_servers',
+            ddl: "ALTER TABLE server_launch_collections ADD COLUMN retained_servers TEXT NOT NULL DEFAULT '[]'"
+        }
+    ]);
+    migrateTable(handle, 'server_launch_recipes', [
+        {
+            name: 'recipe_summary',
+            ddl: 'ALTER TABLE server_launch_recipes ADD COLUMN recipe_summary TEXT'
+        }
+    ]);
+    migrateServerHistory(handle);
+    migrateTable(handle, 'server_collection_previews', [
+        {
+            name: 'mode',
+            ddl: "ALTER TABLE server_collection_previews ADD COLUMN mode TEXT NOT NULL DEFAULT 'fill'"
+        },
+        {
+            name: 'fleet_snapshot',
+            ddl: 'ALTER TABLE server_collection_previews ADD COLUMN fleet_snapshot TEXT'
+        }
+    ]);
+    migrateTable(handle, 'server_telemetry', [
+        { name: 'payload', ddl: 'ALTER TABLE server_telemetry ADD COLUMN payload TEXT' }
+    ]);
+    // Kind-referencing indexes: safe here because migrateTable above just
+    // ALTER'd the column into existence if it was missing.
+    handle.exec(
+        `CREATE UNIQUE INDEX IF NOT EXISTS idx_scripts_one_baseline_per_scope
+                 ON scripts(scope_type, scope_value) WHERE kind = 'baseline'`
+    );
+    handle.exec(`CREATE INDEX IF NOT EXISTS idx_scripts_kind ON scripts(kind)`);
+    backfillMultiScriptJoins(handle);
+    assertSnapshotSchemeSafe(handle);
+    migrateGameTelemetry(handle);
+    migrateTable(handle, 'leaderboard_matches', [
+        {
+            name: 'start_players',
+            ddl: 'ALTER TABLE leaderboard_matches ADD COLUMN start_players INTEGER'
+        }
+    ]);
+    migrateTable(handle, 'leaderboard_match_players', [
+        {
+            name: 'first_observed_round',
+            ddl: 'ALTER TABLE leaderboard_match_players ADD COLUMN first_observed_round INTEGER'
+        },
+        {
+            name: 'present_at_start',
+            ddl: 'ALTER TABLE leaderboard_match_players ADD COLUMN present_at_start INTEGER'
+        }
+    ]);
+    backfillLeaderboard(handle);
+    initializeFleetSettings(handle);
+}
+
+export function installLifecycleIndexes(handle: Database.Database): void {
+    // Lifecycle history is retained indefinitely. Admission and status reads
+    // must narrow by server or active state instead of scanning that history.
+    // Install after migrations that rebuild this table or add server_deleted_at.
+    handle.exec(`CREATE INDEX IF NOT EXISTS idx_server_deployments_server
+            ON server_deployments(server, server_deleted_at);
+            CREATE INDEX IF NOT EXISTS idx_server_deployments_state
+            ON server_deployments(state, action, server_deleted_at);
+            CREATE INDEX IF NOT EXISTS idx_server_deployments_server_state
+            ON server_deployments(server, server_deleted_at, state, action);
+            CREATE INDEX IF NOT EXISTS idx_server_deployments_started_at
+            ON server_deployments(started_at);
+            CREATE INDEX IF NOT EXISTS idx_server_deployments_submission
+            ON server_deployments(server, server_deleted_at, action, submitted_at);
+            CREATE INDEX IF NOT EXISTS idx_server_deployments_finished_at
+            ON server_deployments(finished_at) WHERE server_deleted_at IS NULL;
+            CREATE INDEX IF NOT EXISTS idx_server_deployments_unsettled
+            ON server_deployments(id) WHERE state NOT IN ('done','warning','cancelled');`);
+}

src/lib/server/db/migrate.ts

@@ -1,9 +1,7 @@
 import { db } from './index.js';
 
-// The heavy lifting is idempotent DDL inside schema.sql, which db() runs on
-// first handle. This module exists as an explicit hook for future migrations
-// (numbered .sql files applied via a schema_version row) and to be called
-// from hooks.server.ts so boot-time failures surface early.
+// Called from hooks.server.ts so startup fails before workers or requests run.
+// db() applies the ordered migrations.ts list using PRAGMA user_version.
 export function migrate(): void {
-    db().prepare('SELECT 1').get();
+    db();
 }

src/lib/server/db/migration-runner.ts

@@ -0,0 +1,60 @@
+import type Database from 'better-sqlite3';
+import { migrationStep } from './connection.js';
+
+export interface Migration {
+    version: number;
+    name: string;
+    run: (handle: Database.Database) => void;
+    // Table rebuilds must disable foreign keys before opening the transaction.
+    // VACUUM cannot run in one; autocommit steps must be safe to resume.
+    mode?: 'foreign-keys-off' | 'autocommit';
+}
+
+export function runMigrations(handle: Database.Database, migrations: readonly Migration[]): void {
+    for (const [index, migration] of migrations.entries()) {
+        if (migration.version !== index + 1)
+            throw new Error('Database migrations must have consecutive versions starting at 1');
+    }
+    const version = () => handle.pragma('user_version', { simple: true }) as number;
+    const assertSupported = (current: number) => {
+        if (current < 0 || current > migrations.length)
+            throw new Error(
+                `Database version ${current} is not supported by this application (latest: ${migrations.length})`
+            );
+    };
+    const initialVersion = version();
+    assertSupported(initialVersion);
+    if (handle.inTransaction) throw new Error('Database migrations require their own transaction');
+
+    for (const migration of migrations) {
+        if (initialVersion >= migration.version) continue;
+        migrationStep(`${migration.version}: ${migration.name}`, () => {
+            const foreignKeys = handle.pragma('foreign_keys', { simple: true });
+            if (migration.mode === 'foreign-keys-off') handle.pragma('foreign_keys = OFF');
+            try {
+                const apply = () => {
+                    // Recheck after acquiring the write lock in case another opener migrated.
+                    const current = version();
+                    assertSupported(current);
+                    if (current >= migration.version) return;
+                    if (current !== migration.version - 1)
+                        throw new Error(`Missing database migration before ${migration.version}`);
+                    migration.run(handle);
+                    if (
+                        migration.mode === 'foreign-keys-off' &&
+                        (handle.pragma('foreign_key_check') as unknown[]).length
+                    )
+                        throw new Error(
+                            `Database migration ${migration.version} left broken references`
+                        );
+                    handle.pragma(`user_version = ${migration.version}`);
+                };
+                if (migration.mode === 'autocommit') apply();
+                else handle.transaction(apply).immediate();
+            } finally {
+                if (migration.mode === 'foreign-keys-off')
+                    handle.pragma(`foreign_keys = ${foreignKeys ? 'ON' : 'OFF'}`);
+            }
+        });
+    }
+}

src/lib/server/db/migrations.ts

@@ -0,0 +1,71 @@
+import { migrateLegacySchema, installLifecycleIndexes } from './legacy.js';
+import { migrateNativeInstances } from '../backends/schema.js';
+import { migrateServerKeys } from './server-keys.js';
+import { ensureAutoscalingSchema } from '../autoscaling/schema.js';
+import { ensureRebalancingSchema } from '../rebalancing/schema.js';
+import { migrateFileBlobs } from './file-blobs.js';
+import { installPerformanceIndexes } from './performance-indexes.js';
+import { installReportRevisions } from '../reports/revisions.js';
+import { enableIncrementalVacuum, retentionClocks } from './retention-clocks.js';
+import { migrateHostSchema } from '../hosts/schema.js';
+import { migrateAuthSchema } from '../auth/schema.js';
+import { migrateGameFileSchema } from '../game-files/schema.js';
+import type { Migration } from './migration-runner.js';
+
+// Append only: never renumber entries or change an applied migration to add an
+// upgrade. These initial steps bridge every historical, unversioned database;
+// their old sentinels are compatibility inputs, not the migration ledger.
+export const migrations: readonly Migration[] = [
+    {
+        version: 1,
+        name: 'legacy controller schema and backfills',
+        mode: 'foreign-keys-off',
+        run: migrateLegacySchema
+    },
+    {
+        version: 2,
+        name: 'native instances and file plans',
+        mode: 'foreign-keys-off',
+        run: migrateNativeInstances
+    },
+    { version: 3, name: 'per-game server key pools', run: migrateServerKeys },
+    { version: 4, name: 'autoscaling', run: ensureAutoscalingSchema },
+    { version: 5, name: 'rebalancing', run: ensureRebalancingSchema },
+    // Native file plans are stripped before artifact bodies are moved to blobs.
+    { version: 6, name: 'shared file blobs', run: migrateFileBlobs },
+    {
+        version: 7,
+        name: 'query indexes and report revisions',
+        run: (handle) => {
+            installLifecycleIndexes(handle);
+            installPerformanceIndexes(handle);
+            installReportRevisions(handle);
+        }
+    },
+    {
+        version: 8,
+        name: 'retention clocks and indexes',
+        run: (handle) =>
+            retentionClocks(handle, {
+                deployments: ['started_at', 'finished_at'],
+                server_deployments: ['started_at', 'finished_at'],
+                maintenance_jobs: ['requested_at', 'finished_at'],
+                watchdog_incidents: ['first_seen_at', 'finished_at'],
+                leaderboard_matches: ['started_at', 'last_received_at', 'ended_at'],
+                betas: ['opened_at', 'closed_at'],
+                script_versions: ['uploaded_at'],
+                retention_controls: ['resolved_at']
+            })
+    },
+    { version: 9, name: 'hosts and saved command files', run: migrateHostSchema },
+    { version: 10, name: 'authentication', run: migrateAuthSchema },
+    { version: 11, name: 'game-file libraries', run: migrateGameFileSchema },
+    {
+        version: 12,
+        name: 'incremental vacuum page map',
+        mode: 'autocommit',
+        run: enableIncrementalVacuum
+    }
+];
+
+export const databaseVersion = migrations.length;

src/lib/server/db/schema.sql

@@ -8,12 +8,12 @@ CREATE TABLE IF NOT EXISTS file_blob_references (
 );
 CREATE INDEX IF NOT EXISTS idx_file_blob_references_hash ON file_blob_references(sha256);
 
--- Electric Cherry schema. Idempotent — safe to run at every boot via migrate.ts.
+-- Base schema for the version-0 compatibility bridge in migrations.ts.
+-- Future schema changes belong in new numbered migrations.
 -- The old betas/beta_scripts/beta_deploys tables are dropped in-code before this
--- runs (see dropLegacyBetaTables in db/index.ts); the new script-centric model
+-- runs (see dropLegacyBetaTables in db/legacy.ts); the new script-centric model
 -- lives here.
 
-PRAGMA journal_mode = WAL;
 PRAGMA foreign_keys = ON;
 
 -- Historical gameplay deliberately has no FK to servers: destroying a server
@@ -138,7 +138,7 @@ CREATE TABLE IF NOT EXISTS scripts (
     created_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
 );
 CREATE INDEX IF NOT EXISTS idx_scripts_scope ON scripts(scope_type, scope_value);
--- kind-referencing indexes are created in db/index.ts AFTER migrateTable adds
+-- kind-referencing indexes are created in db/legacy.ts after migrateTable adds
 -- the column to legacy DBs. Putting them here would fail with "no such column:
 -- kind" on an existing pre-kind DB, breaking boot.
 

src/lib/server/fleet/beta.ts

@@ -22,7 +22,6 @@ async function exclusive<T>(id: number, action: () => Promise<T>): Promise<T> {
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { readFile, exists } from '../backends/files.js';
 import { getHostOperation } from '../hosts/index.js';
-import { ensureHostSchema } from '../hosts/schema.js';
 
 import { join, posix } from 'node:path';
 import { betaArchiveOf, configFileOf, destOfKind, type ArtifactKind } from '../config.js';
@@ -668,7 +667,6 @@ export async function reviseBeta(
                 'invalid-state'
             );
         }
-        ensureHostSchema(db());
         assertNativeActivationSettled(betaId);
         if (stagedFileChanges('beta', String(betaId)).some((row) => row.state === 'applying')) {
             throw new BetaError(
@@ -961,7 +959,6 @@ async function rollbackBetaInternal(
         versionId: br.script_version_id
     }));
 
-    ensureHostSchema(db());
     db().transaction(() => {
         const jobs = db()
             .prepare(

src/lib/server/fleet/monitoring-snapshot.ts

@@ -1,5 +1,4 @@
 import { db } from '../db/index.js';
-import { ensureHostSchema } from '../hosts/schema.js';
 import { HEARTBEAT_MAX_AGE_MS } from '../hosts/index.js';
 import { parseHostInventory } from '../hosts/request-context.js';
 import type { Host } from '../../hosts.js';
@@ -70,7 +69,6 @@ interface Record {
 export class MonitoringSnapshot {
     private records = new Map<string, Record>();
     constructor(serverName?: string) {
-        ensureHostSchema(db());
         this.refresh(serverName);
     }
     refresh(server?: string): void {

src/lib/server/game-files/index.ts

@@ -5,8 +5,6 @@ import { dirname, join, resolve } from 'node:path';
 import { db } from '../db/index.js';
 import { config } from '../config.js';
 import { getHost, getHostOperation, listHosts, queueHostOperation } from '../hosts/index.js';
-import { ensureGameFileSchema } from './schema.js';
-import { ensureHostSchema } from '../hosts/schema.js';
 import {
     manifestChecksum,
     receiveGameFile,
@@ -35,10 +33,7 @@ import type {
 } from '../../game-files.js';
 
 function database() {
-    const handle = db();
-    ensureGameFileSchema(handle);
-    ensureHostSchema(handle);
-    return handle;
+    return db();
 }
 export const gameFilesRoot = () =>
     resolve(process.env.GAME_FILES_ROOT ?? join(dirname(config.dbPath), 'game-files'));

src/lib/server/game-files/schema.ts

@@ -1,13 +1,6 @@
 import type Database from 'better-sqlite3';
 
-const initialized = new WeakSet<Database.Database>();
-export function ensureGameFileSchema(handle: Database.Database): void {
-    if (initialized.has(handle)) return;
-    // Worker readers open only after the controller has initialized the schema.
-    if (handle.readonly) {
-        initialized.add(handle);
-        return;
-    }
+export function migrateGameFileSchema(handle: Database.Database): void {
     handle.exec(`
         CREATE TABLE IF NOT EXISTS game_file_libraries (
             id TEXT PRIMARY KEY, name TEXT NOT NULL COLLATE NOCASE UNIQUE,
@@ -62,5 +55,4 @@ export function ensureGameFileSchema(handle: Database.Database): void {
         handle.exec('ALTER TABLE host_library_caches ADD COLUMN bytes_verified INTEGER');
     if (!cacheColumns.some((column) => column.name === 'transfer_progress'))
         handle.exec('ALTER TABLE host_library_caches ADD COLUMN transfer_progress TEXT');
-    initialized.add(handle);
 }

src/lib/server/hosts/calibration.ts

@@ -1,6 +1,5 @@
 import { fleetSettings } from '../settings.js';
 import { db } from '../db/index.js';
-import { ensureHostSchema } from './schema.js';
 import type {
     CapacityCalibration,
     CapacitySample,
@@ -25,9 +24,7 @@ interface AllowanceRow {
     computed_at: string;
 }
 function database() {
-    const handle = db();
-    ensureHostSchema(handle);
-    return handle;
+    return db();
 }
 
 /** Read retained minute peaks without contacting agents or recalculating allowances. */

src/lib/server/hosts/capacity-history.ts

@@ -1,5 +1,4 @@
 import { db } from '../db/index.js';
-import { ensureHostSchema } from './schema.js';
 import type { CapacityHistory, CapacityQuery, CapacityRange } from '../../capacity.js';
 
 const windows: Record<CapacityRange, { duration: number; bucketMs: number }> = {
@@ -11,7 +10,6 @@ const windows: Record<CapacityRange, { duration: number; bucketMs: number }> = {
 /** Read on the report worker: heartbeat history can contain millions of rows. */
 export function readCapacityHistory(query: CapacityQuery, now = Date.now()): CapacityHistory {
     const handle = db();
-    ensureHostSchema(handle);
     const { duration, bucketMs } = windows[query.range];
     const startAt = now - duration;
     const count = duration / bucketMs;

src/lib/server/hosts/index.ts

@@ -5,7 +5,6 @@ import { EventEmitter } from 'node:events';
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { isIP } from 'node:net';
 import { db } from '../db/index.js';
-import { ensureHostSchema } from './schema.js';
 import {
     successfulObservation,
     routineObservationSql,
@@ -60,9 +59,7 @@ export function waitForHostWork(
 }
 const digest = (token: string) => createHash('sha256').update(token).digest('hex');
 function database() {
-    const handle = db();
-    ensureHostSchema(handle);
-    return handle;
+    return db();
 }
 type HostRow = {
     id: string;

src/lib/server/hosts/schema.ts

@@ -7,7 +7,6 @@ import {
 } from '../db/file-blobs.js';
 import { retentionClocks } from '../db/retention-clocks.js';
 import { installHistoryCounts } from './history-counts.js';
-import { migrationStep } from '../db/connection.js';
 import type Database from 'better-sqlite3';
 import {
     successfulObservationSql,
@@ -16,19 +15,7 @@ import {
     importantOperationSql
 } from './observations.js';
 
-const initialized = new WeakSet<Database.Database>();
-export function ensureHostSchema(handle: Database.Database): void {
-    if (initialized.has(handle)) return;
-    // Background readers open only after controller migrations have completed.
-    if (handle.readonly) {
-        initialized.add(handle);
-        return;
-    }
-    migrationStep('host schema and saved command files', () => migrateHostSchema(handle));
-    initialized.add(handle);
-}
-
-function migrateHostSchema(handle: Database.Database): void {
+export function migrateHostSchema(handle: Database.Database): void {
     ensureFileBlobSchema(handle);
     handle.exec(`
         CREATE TABLE IF NOT EXISTS ec_hosts (

src/lib/server/provisioning/cancellation.ts

@@ -1,6 +1,5 @@
 import { pauseScalingForOperation } from '../autoscaling/ownership.js';
 import { db } from '../db/index.js';
-import { ensureHostSchema } from '../hosts/schema.js';
 import { recordProgress } from './progress.js';
 import { requestRebalanceStopForOperation } from '../rebalancing/admission.js';
 
@@ -42,7 +41,6 @@ export function cancelProvisioningJob(
     reason = 'Cancelled by operator',
     options: { preserveRebalanceRun?: boolean } = {}
 ): boolean {
-    ensureHostSchema(db());
     return db().transaction(() => {
         if (provisioningCancelled(id)) return true;
         if (!canCancelProvisioningJob(id)) return false;

src/lib/server/provisioning/concurrency.ts

@@ -1,4 +1,3 @@
-import { ensureHostSchema } from '../hosts/schema.js';
 import { db } from '../db/index.js';
 import { fleetSettings } from '../settings.js';
 
@@ -16,7 +15,6 @@ interface Holder {
 }
 
 export function lifecycleHolders(): Holder[] {
-    ensureHostSchema(db());
     // Find capacity owners through their active state or outstanding command.
     // A correlated OR over d used to walk every retained job and fetch its agent
     // receipt on every admission, even when all that history was completed.

src/lib/server/provisioning/history.ts

@@ -23,7 +23,6 @@ import {
 } from './cancellation.js';
 import { committedRebalanceStartup } from './concurrency.js';
 import { nativeDeployment } from '../backends/native.js';
-import { ensureHostSchema } from '../hosts/schema.js';
 import { safetyOverride, safetyOverrideAvailability } from './safety-override.js';
 import { serverTitle } from '../../ui/server-labels.js';
 import { provisioningQueueStatus } from '../../ui/provisioning-queue.js';
@@ -420,7 +419,6 @@ export function resumeCleanup(id: string): boolean {
 }
 
 export function canResumeVerification(id: string): boolean {
-    ensureHostSchema(db());
     return !!db()
         .prepare(
             `SELECT d.id FROM server_deployments d
@@ -444,7 +442,6 @@ export function canResumeVerification(id: string): boolean {
 
 /** A conclusively failed initial create can enter the normal rebuild flow. */
 export function canRetryWithRebuild(id: string): boolean {
-    ensureHostSchema(db());
     return !!db()
         .prepare(
             `SELECT d.id FROM server_deployments d

src/lib/server/provisioning/native.ts

@@ -14,7 +14,6 @@ import { choosePlacement, availableHostPort, type PlacementOptions } from '../ho
 import { randomBytes, randomUUID } from 'node:crypto';
 import { posix } from 'node:path';
 import { db } from '../db/index.js';
-import { ensureHostSchema } from '../hosts/schema.js';
 import { unsettledCancelledCommand } from './cancellation.js';
 import { config, relDestForKind, serverDir } from '../config.js';
 import {
@@ -1014,7 +1013,6 @@ export async function processNativeProvisioning(
     }) => string | null,
     options: { wait?: boolean } = {}
 ): Promise<void> {
-    ensureHostSchema(db());
     const cancelled = db()
         .prepare(
             `SELECT d.id FROM server_deployments d

src/lib/server/reports/index.ts

@@ -10,7 +10,6 @@ import type {
     LeaderboardEntry
 } from '../../leaderboard.js';
 import type { CapacityHistory, CapacityQuery } from '../../capacity.js';
-import { ensureHostSchema } from '../hosts/schema.js';
 
 class ReportWorker {
     private worker: Worker | null = null;
@@ -116,7 +115,6 @@ export const playerReport = (guid: string, offset: number, options: LeaderboardO
         options
     });
 export const capacityHistoryReport = (query: CapacityQuery) => {
-    ensureHostSchema(db());
     // Game changes current placement estimates, not measured host resources.
     return capacity.run<CapacityHistory>('capacity', {
         query: { ...query, game: 'all' },

src/lib/server/retention.ts

@@ -3,9 +3,6 @@ import { createHash } from 'node:crypto';
 import { db } from './db/index.js';
 import { fleetSettings } from './settings.js';
 import { runtimeLaunchSql } from './fleet/runtime-config.js';
-import { ensureHostSchema } from './hosts/schema.js';
-import { ensureGameFileSchema } from './game-files/schema.js';
-import { ensureAuthSchema } from './auth/schema.js';
 import { logResultMetadata } from './hosts/log-results.js';
 import type { FleetSettings } from '../fleet-settings.js';
 
@@ -266,10 +263,6 @@ function versionReferences(): string {
     }
     return clauses.join(' AND ') || '1';
 }
-function initialize() {
-    ensureHostSchema(db());
-    ensureAuthSchema(db());
-}
 
 function withoutFileBodies(value: unknown): unknown {
     if (Array.isArray(value)) return value.map(withoutFileBodies);
@@ -364,7 +357,6 @@ function selection(policy: Policy, settings = fleetSettings()) {
 }
 // better-sqlite3 accepts unused named bindings, keeping selection reusable.
 export function retentionPreview(settings = fleetSettings()) {
-    initialize();
     return policies().map((policy) => {
         const query = selection(policy, settings);
         const summary = db()
@@ -393,8 +385,6 @@ export function setRetentionControl(input: {
     protected?: boolean;
     resolve?: boolean;
 }) {
-    initialize();
-    ensureGameFileSchema(db());
     const policy =
         policies().find((policy) => policy.category === input.category) ??
         (['game-file', 'upload'].includes(input.category)
@@ -449,7 +439,6 @@ export function setRetentionControl(input: {
 
 /** Each policy removes at most 500 eligible records per pass; dependencies are checked again under the transaction. */
 export function pruneHistory(only?: string): number {
-    initialize();
     if (only === 'observation') return pruneRoutineObservations();
     let removed = only ? 0 : pruneRoutineObservations();
     for (const policy of policies().filter(
@@ -594,7 +583,6 @@ function samplePolicies(s = fleetSettings()) {
     ];
 }
 export function sampleRetentionPreview(settings = fleetSettings()) {
-    initialize();
     const result = samplePolicies(settings)
         .filter((p) => p.category !== 'telemetry')
         .map((p) => ({
@@ -634,7 +622,6 @@ export function sampleRetentionPreview(settings = fleetSettings()) {
     return result;
 }
 export function pruneSampleHistory() {
-    initialize();
     let removed = 0;
     for (const p of samplePolicies().filter((p) => p.enabled))
         removed += db()
@@ -663,7 +650,6 @@ export function pruneSampleHistory() {
 export async function drainRetention(): Promise<number> {
     let total = 0,
         logCursor = 0;
-    initialize();
     while (true) {
         const removed = pruneHistory() + pruneSampleHistory();
         total += removed;