relay-dsh-plugin-events 0.2.2 → 0.2.3-rc.2

package/README.md

@@ -1,15 +1,15 @@
 # Relay Events for DeepSeek Harness
 
-> **Now supports DSH `0.1.2-rc.1` while retaining `0.1.2-alpha.3` compatibility.** Plugin `0.2.2` is verified on both releases. [Install it from npm](https://www.npmjs.com/package/relay-dsh-plugin-events) · [Compatibility evidence](https://github.com/yangbobo2021/Relay/tree/codex/relay-foundation/dsh-lab/dsh-0.1.2-rc.1-20260903).
+> **Now supports DSH `0.1.2-rc.1` while retaining `0.1.2-alpha.3` compatibility.** Plugin `0.2.3` is verified on both releases and safely upgrades existing Relay databases. [Install it from npm](https://www.npmjs.com/package/relay-dsh-plugin-events) · [Compatibility evidence](https://github.com/yangbobo2021/Relay/tree/codex/relay-foundation/dsh-lab/dsh-0.1.2-rc.1-20260903).
 
-> **Release channels:** `latest` → `0.2.2`; `next` → `0.2.1-rc.1`.
+> **Release channels:** `latest` → `0.2.3`; `next` → `0.2.3-rc.2`.
 
 ```bash
-npx @deepseek-ai/dsh@0.1.2-rc.1 plugin --profile web add relay-dsh-plugin-events@0.2.2
+npx @deepseek-ai/dsh@0.1.2-rc.1 plugin --profile web add relay-dsh-plugin-events@0.2.3
 npx @deepseek-ai/dsh@0.1.2-rc.1 web
 ```
 
-[![DSH compatibility](https://img.shields.io/badge/DSH-0.1.1--rc.2%20%7C%200.1.2--alpha.2%20%7C%200.1.2--alpha.3-2f7d68)](https://github.com/deepseek-ai/deepseek-harness)
+[![DSH compatibility](https://img.shields.io/badge/DSH-0.1.1--rc.2%20%7C%200.1.2--alpha.2%20%7C%200.1.2--alpha.3%20%7C%200.1.2--rc.1-2f7d68)](https://github.com/deepseek-ai/deepseek-harness)
 
 English | [中文](README.zh.md)
 
@@ -19,8 +19,8 @@ delivery to the owning existing Session, recovery, and a Waiting Events settings
 surface without adding an execution backend.
 
 The older `internal` npm channel remains available for integration testing and
-does not carry this compatibility guarantee. Use the exact `0.2.1`
-versions in the latest-DSH command above; do not substitute `@internal`.
+does not carry this compatibility guarantee. Use the exact `0.2.3`
+version in the latest-DSH command above; do not substitute `@internal`.
 
 ```bash
 dsh plugin --profile web add --save-exact relay-dsh-plugin-events@internal
@@ -31,6 +31,18 @@ Semantic routing and Monitor execution are separate plugins. Without a Router,
 Events uses exact event-type matching. Without Monitors, Wait-only registration
 and external ingress remain fully usable.
 
+## Database lifecycle
+
+The Relay database is persistent and is not removed when the plugin is
+uninstalled. On startup, the plugin initializes a missing or empty database at
+the current schema. A recognized older schema is integrity-checked, backed up to
+`<database>.backup-v<old>-to-v<current>.sqlite`, and upgraded in one transaction
+before dependent indexes are created. The backup is verified and reused on a
+retry. Migration failure rolls back all schema changes and reports the backup
+path. An unknown non-empty schema, a corrupt database, foreign-key violations,
+or a schema newer than the plugin supports is rejected rather than guessed or
+silently modified.
+
 See [SPEC.md](SPEC.md) and
 [delivery scenarios](docs/acceptance-scenarios.md).
 

package/README.zh.md

@@ -1,15 +1,15 @@
 # 面向 DeepSeek Harness 的 Relay Events
 
-> **现已支持 DSH `0.1.2-rc.1`，并保留对 `0.1.2-alpha.3` 的兼容。** 插件 `0.2.2` 已在两个版本上完成验证。[从 npm 安装](https://www.npmjs.com/package/relay-dsh-plugin-events) · [兼容性证据](https://github.com/yangbobo2021/Relay/tree/codex/relay-foundation/dsh-lab/dsh-0.1.2-rc.1-20260903)。
+> **现已支持 DSH `0.1.2-rc.1`，并保留对 `0.1.2-alpha.3` 的兼容。** 插件 `0.2.3` 已在两个版本上完成验证，并可安全升级已有 Relay 数据库。[从 npm 安装](https://www.npmjs.com/package/relay-dsh-plugin-events) · [兼容性证据](https://github.com/yangbobo2021/Relay/tree/codex/relay-foundation/dsh-lab/dsh-0.1.2-rc.1-20260903)。
 
-> **发布通道：** `latest` → `0.2.2`；`next` → `0.2.1-rc.1`。
+> **发布通道：** `latest` → `0.2.3`；`next` → `0.2.3-rc.2`。
 
 ```bash
-npx @deepseek-ai/dsh@0.1.2-rc.1 plugin --profile web add relay-dsh-plugin-events@0.2.2
+npx @deepseek-ai/dsh@0.1.2-rc.1 plugin --profile web add relay-dsh-plugin-events@0.2.3
 npx @deepseek-ai/dsh@0.1.2-rc.1 web
 ```
 
-[![DSH 兼容版本](https://img.shields.io/badge/DSH-0.1.1--rc.2%20%7C%200.1.2--alpha.2%20%7C%200.1.2--alpha.3-2f7d68)](https://github.com/deepseek-ai/deepseek-harness)
+[![DSH 兼容版本](https://img.shields.io/badge/DSH-0.1.1--rc.2%20%7C%200.1.2--alpha.2%20%7C%200.1.2--alpha.3%20%7C%200.1.2--rc.1-2f7d68)](https://github.com/deepseek-ai/deepseek-harness)
 
 [English](README.md) | 中文
 
@@ -18,7 +18,7 @@ Wait/Event/Delivery 核心。它提供 Agent 工具、通用 JSON 事件入口
 Session 投递、故障恢复以及 Waiting Events 设置界面，但不增加执行后端。
 
 旧的 `internal` npm 通道继续用于集成测试，不包含此次兼容保证。请使用上方最新版
-DSH 命令中精确的 `0.2.1` 版本，不要替换为 `@internal`。
+DSH 命令中精确的 `0.2.3` 版本，不要替换为 `@internal`。
 
 ```bash
 dsh plugin --profile web add --save-exact relay-dsh-plugin-events@internal
@@ -28,6 +28,15 @@ dsh web
 语义路由与 Monitor 执行由独立插件提供。未安装 Router 时，Events 使用精确事件类型
 匹配；未安装 Monitors 时，Wait 注册与外部事件入口仍然可以完整使用。
 
+## 数据库生命周期
+
+Relay 数据库是持久化数据，卸载插件时不会被删除。启动时，插件会将不存在或空数据库
+直接初始化为当前 schema。对于可识别的旧 schema，会先校验完整性，再备份到
+`<database>.backup-v<old>-to-v<current>.sqlite`，然后在同一个事务内执行升级，
+最后创建依赖新字段的索引。备份会被校验，重试时会复用。迁移失败会回滚所有 schema 修改，
+并在错误中给出备份路径。未知的非空 schema、损坏的数据库、外键违规，或高于插件所支持版本的
+schema 都会被拒绝，不会猜测结构或静默修改数据。
+
 详见 [SPEC.md](SPEC.md) 与[投递场景](docs/acceptance-scenarios.md)。
 
 将 `DSH_ROOT` 指向准备好的官方 DSH 只读检出，然后执行

package/docs/acceptance-scenarios.md

@@ -29,7 +29,7 @@ Official DSH references: `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`,
 | EVT-021 | Non-exclusive fan-out | Exact non-exclusive matches create one atomic Delivery per Session with complete matched cards. | SQLite integration |
 | EVT-022 | Trusted bound source | Only a registered source capability can submit a binding; public payload ownership fields have no authority. | service + protocol security |
 | EVT-023 | Stale/cross-Session binding | Invalid owner, Wait, version, or Session/Wait pair escalates with no claim or Delivery. | SQLite integration |
-| EVT-024 | Schema upgrade | Existing schema v4/v5/v9 storage upgrades through schema v10, preserving Delivery snapshots and adding notification receipt/attempt evidence. | real file migration |
+| EVT-024 | Safe schema initialization and upgrade | Missing, empty, and metadata-only storage initializes directly at schema v10; every historical schema v1-v9 is integrity-checked, verified-backup protected, transactionally upgraded, structurally validated, and idempotent while preserving data. Failed migration rolls back; unknown non-empty and future schemas fail closed without mutation. | real file migration matrix + official DSH startup |
 | EVT-025 | Router failure terminal state | Repeated Router failure reaches the configured budget, commits one inspectable escalation, creates no Delivery, and omits raw provider errors/secrets. | unit + SQLite |
 | EVT-026 | Incomplete Event recovery | The background scan resumes `received`/`routing` Events and reaches a single terminal decision without redelivery or duplicate attempts. | fake-clock integration + restart |
 | EVT-027 | Conflicting provider identity | Reuse of one source delivery identity with different content fails closed, preserves the original terminal Event, and creates no second record. | SQLite security integration |

package/lib/client.js

@@ -18,58 +18,58 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var WaitingEventsSection_module_css_default = {
-			"error": "bDRFYa_error",
-			"bundlePermissions": "bDRFYa_bundlePermissions",
-			"details": "bDRFYa_details",
-			"eventHeader": "bDRFYa_eventHeader",
-			"pagination": "bDRFYa_pagination",
-			"cadenceAction": "bDRFYa_cadenceAction",
-			"connectorNote": "bDRFYa_connectorNote",
-			"counts": "bDRFYa_counts",
-			"registration": "bDRFYa_registration",
-			"statusBadge": "bDRFYa_statusBadge",
-			"filters": "bDRFYa_filters",
+			"historyHeader": "bDRFYa_historyHeader",
+			"failure": "bDRFYa_failure",
 			"emptyHistory": "bDRFYa_emptyHistory",
-			"monitors": "bDRFYa_monitors",
-			"connectors": "bDRFYa_connectors",
 			"iconButton": "bDRFYa_iconButton",
-			"timerSummary": "bDRFYa_timerSummary",
-			"waitContent": "bDRFYa_waitContent",
-			"emptyCatalog": "bDRFYa_emptyCatalog",
+			"details": "bDRFYa_details",
+			"waitText": "bDRFYa_waitText",
 			"bundleRemediation": "bDRFYa_bundleRemediation",
-			"actions": "bDRFYa_actions",
-			"monitorMain": "bDRFYa_monitorMain",
-			"historyHeader": "bDRFYa_historyHeader",
-			"rowState": "bDRFYa_rowState",
-			"activation": "bDRFYa_activation",
+			"empty": "bDRFYa_empty",
+			"connectors": "bDRFYa_connectors",
 			"connector": "bDRFYa_connector",
-			"confirmation": "bDRFYa_confirmation",
-			"summary": "bDRFYa_summary",
-			"registrationHeader": "bDRFYa_registrationHeader",
-			"registrations": "bDRFYa_registrations",
-			"section": "bDRFYa_section",
-			"secretAction": "bDRFYa_secretAction",
-			"waitText": "bDRFYa_waitText",
-			"sessionButton": "bDRFYa_sessionButton",
+			"bundlePermissions": "bDRFYa_bundlePermissions",
+			"error": "bDRFYa_error",
+			"counts": "bDRFYa_counts",
+			"monitors": "bDRFYa_monitors",
 			"connectorHeader": "bDRFYa_connectorHeader",
-			"total": "bDRFYa_total",
+			"accounts": "bDRFYa_accounts",
 			"monitorTimes": "bDRFYa_monitorTimes",
+			"message": "bDRFYa_message",
 			"catalogHeader": "bDRFYa_catalogHeader",
-			"events": "bDRFYa_events",
-			"bundleTypes": "bDRFYa_bundleTypes",
+			"registrations": "bDRFYa_registrations",
+			"registration": "bDRFYa_registration",
+			"registrationHeader": "bDRFYa_registrationHeader",
 			"bundleHeader": "bDRFYa_bundleHeader",
-			"overdue": "bDRFYa_overdue",
-			"message": "bDRFYa_message",
-			"title": "bDRFYa_title",
+			"rowState": "bDRFYa_rowState",
 			"bundleCatalog": "bDRFYa_bundleCatalog",
-			"stateDot": "bDRFYa_stateDot",
+			"sessionButton": "bDRFYa_sessionButton",
+			"summary": "bDRFYa_summary",
+			"activation": "bDRFYa_activation",
+			"connectorNote": "bDRFYa_connectorNote",
+			"bundleTypes": "bDRFYa_bundleTypes",
+			"eventHeader": "bDRFYa_eventHeader",
+			"filters": "bDRFYa_filters",
+			"statusBadge": "bDRFYa_statusBadge",
+			"actions": "bDRFYa_actions",
+			"waitContent": "bDRFYa_waitContent",
+			"monitorMain": "bDRFYa_monitorMain",
+			"section": "bDRFYa_section",
+			"emptyCatalog": "bDRFYa_emptyCatalog",
+			"pagination": "bDRFYa_pagination",
+			"timerSummary": "bDRFYa_timerSummary",
+			"cadenceAction": "bDRFYa_cadenceAction",
 			"toolbar": "bDRFYa_toolbar",
-			"waits": "bDRFYa_waits",
-			"history": "bDRFYa_history",
-			"accounts": "bDRFYa_accounts",
-			"failure": "bDRFYa_failure",
+			"total": "bDRFYa_total",
 			"eventDetails": "bDRFYa_eventDetails",
-			"empty": "bDRFYa_empty"
+			"confirmation": "bDRFYa_confirmation",
+			"history": "bDRFYa_history",
+			"waits": "bDRFYa_waits",
+			"events": "bDRFYa_events",
+			"secretAction": "bDRFYa_secretAction",
+			"overdue": "bDRFYa_overdue",
+			"title": "bDRFYa_title",
+			"stateDot": "bDRFYa_stateDot"
 		};
 		//#endregion
 		//#region src/client/WaitingEventsSection.tsx

package/lib/host-plugin.js

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { Service } from "@deepseek-ai/cordis";
@@ -443,7 +443,7 @@ function boundRoutingDecision(sessions, binding, providerId) {
 }
 //#endregion
 //#region src/runtime/schema.mjs
-const SCHEMA_SQL = `
+const SCHEMA_TABLES_SQL = `
   CREATE TABLE IF NOT EXISTS relay_schema (
     version INTEGER PRIMARY KEY,
     applied_at TEXT NOT NULL
@@ -489,10 +489,6 @@ const SCHEMA_SQL = `
     updated_at TEXT NOT NULL
   ) STRICT;
 
-  CREATE UNIQUE INDEX IF NOT EXISTS activations_one_active_per_session
-    ON activations(session_id)
-    WHERE state = 'active';
-
   CREATE TABLE IF NOT EXISTS runs (
     id TEXT PRIMARY KEY,
     session_id TEXT NOT NULL REFERENCES sessions(id),
@@ -521,14 +517,6 @@ const SCHEMA_SQL = `
     updated_at TEXT NOT NULL
   ) STRICT;
 
-  CREATE UNIQUE INDEX IF NOT EXISTS waits_live_exclusive_owner
-    ON waits(exclusive_owner_key)
-    WHERE exclusive_owner_key IS NOT NULL
-      AND status IN ('active', 'claimed');
-
-  CREATE INDEX IF NOT EXISTS waits_session_status
-    ON waits(session_id, status);
-
   CREATE TABLE IF NOT EXISTS events (
     id TEXT PRIMARY KEY,
     source TEXT NOT NULL,
@@ -544,17 +532,6 @@ const SCHEMA_SQL = `
     updated_at TEXT NOT NULL
   ) STRICT;
 
-  CREATE UNIQUE INDEX IF NOT EXISTS events_source_identity
-    ON events(source, source_event_id)
-    WHERE source_event_id IS NOT NULL;
-
-  CREATE UNIQUE INDEX IF NOT EXISTS events_source_fingerprint
-    ON events(source, fingerprint);
-
-  CREATE UNIQUE INDEX IF NOT EXISTS events_trusted_correlation
-    ON events(correlation_key)
-    WHERE correlation_key IS NOT NULL;
-
   CREATE TABLE IF NOT EXISTS routing_attempts (
     id TEXT PRIMARY KEY,
     event_id TEXT NOT NULL REFERENCES events(id),
@@ -599,12 +576,6 @@ const SCHEMA_SQL = `
     PRIMARY KEY (delivery_id, wait_id)
   ) STRICT;
 
-  CREATE INDEX IF NOT EXISTS deliveries_session_state
-    ON deliveries(session_id, state, created_at);
-
-  CREATE INDEX IF NOT EXISTS deliveries_event_state
-    ON deliveries(event_id, state);
-
   CREATE TABLE IF NOT EXISTS monitors (
     id TEXT PRIMARY KEY,
     session_id TEXT NOT NULL REFERENCES sessions(id),
@@ -677,15 +648,6 @@ const SCHEMA_SQL = `
     UNIQUE(monitor_id, trigger_key)
   ) STRICT;
 
-  CREATE INDEX IF NOT EXISTS monitors_due
-    ON monitors(state, next_check_at);
-
-  CREATE INDEX IF NOT EXISTS monitors_session_state
-    ON monitors(session_id, state);
-
-  CREATE INDEX IF NOT EXISTS monitor_checks_monitor_time
-    ON monitor_checks(monitor_id, started_at);
-
   CREATE TABLE IF NOT EXISTS notification_outcomes (
     event_id TEXT PRIMARY KEY REFERENCES events(id),
     provider TEXT,
@@ -697,31 +659,119 @@ const SCHEMA_SQL = `
     updated_at TEXT NOT NULL
   ) STRICT;
 `;
+const SCHEMA_INDEXES_SQL = `
+  CREATE UNIQUE INDEX IF NOT EXISTS activations_one_active_per_session
+    ON activations(session_id)
+    WHERE state = 'active';
+
+  CREATE UNIQUE INDEX IF NOT EXISTS waits_live_exclusive_owner
+    ON waits(exclusive_owner_key)
+    WHERE exclusive_owner_key IS NOT NULL
+      AND status IN ('active', 'claimed');
+
+  CREATE INDEX IF NOT EXISTS waits_session_status
+    ON waits(session_id, status);
+
+  CREATE UNIQUE INDEX IF NOT EXISTS events_source_identity
+    ON events(source, source_event_id)
+    WHERE source_event_id IS NOT NULL;
+
+  CREATE UNIQUE INDEX IF NOT EXISTS events_source_fingerprint
+    ON events(source, fingerprint);
+
+  CREATE UNIQUE INDEX IF NOT EXISTS events_trusted_correlation
+    ON events(correlation_key)
+    WHERE correlation_key IS NOT NULL;
+
+  CREATE INDEX IF NOT EXISTS deliveries_session_state
+    ON deliveries(session_id, state, created_at);
+
+  CREATE INDEX IF NOT EXISTS deliveries_event_state
+    ON deliveries(event_id, state);
+
+  CREATE INDEX IF NOT EXISTS monitors_due
+    ON monitors(state, next_check_at);
+
+  CREATE INDEX IF NOT EXISTS monitors_session_state
+    ON monitors(session_id, state);
+
+  CREATE INDEX IF NOT EXISTS monitor_checks_monitor_time
+    ON monitor_checks(monitor_id, started_at);
+`;
+const SCHEMA_SQL = `${SCHEMA_TABLES_SQL}\n${SCHEMA_INDEXES_SQL}`;
 //#endregion
 //#region src/runtime/store.mjs
 var RelayStore = class {
 	constructor(path = ":memory:", { clock = () => /* @__PURE__ */ new Date(), idFactory = randomUUID } = {}) {
 		this.clock = clock;
 		this.idFactory = idFactory;
+		this.migrationBackupPath = null;
 		this.database = new DatabaseSync(path);
-		this.database.exec("PRAGMA foreign_keys = ON");
-		this.database.exec("PRAGMA busy_timeout = 5000");
-		this.database.exec("PRAGMA journal_mode = WAL");
-		this.database.exec(SCHEMA_SQL);
-		const schemaVersion = this.database.prepare("SELECT MAX(version) AS version FROM relay_schema").get().version;
-		if (schemaVersion == null) this.database.prepare("INSERT INTO relay_schema (version, applied_at) VALUES (?, ?)").run(10, this.now());
-		else {
-			assert.ok(schemaVersion <= 10, `unsupported schema version ${schemaVersion}`);
-			if (schemaVersion < 10) {
-				this.migrateSchema(schemaVersion);
+		try {
+			this.database.exec("PRAGMA foreign_keys = ON");
+			this.database.exec("PRAGMA busy_timeout = 5000");
+			this.initializeSchema(path);
+			this.database.prepare("INSERT OR IGNORE INTO runtime_counters (name, value) VALUES ('routing_epoch', 0)").run();
+		} catch (error) {
+			this.database.close();
+			const backup = this.migrationBackupPath ? ` Backup: ${this.migrationBackupPath}.` : "";
+			throw new Error(`Relay database initialization failed: ${error.message}.${backup}`, { cause: error });
+		}
+	}
+	initializeSchema(path) {
+		const tables = this.database.prepare("SELECT name FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all().map((row) => row.name);
+		if (tables.length === 0 || tables.length === 1 && tables[0] === "relay_schema" && this.database.prepare("SELECT COUNT(*) AS count FROM relay_schema").get().count === 0) {
+			this.database.exec("PRAGMA journal_mode = WAL");
+			this.transaction(() => {
+				this.database.exec(SCHEMA_SQL);
 				this.database.prepare("INSERT INTO relay_schema (version, applied_at) VALUES (?, ?)").run(10, this.now());
-			}
+				this.assertCurrentSchema();
+			});
+			return;
+		}
+		assert.ok(tables.includes("relay_schema"), "non-empty Relay database has no relay_schema metadata; refusing an unsafe implicit migration");
+		const schemaVersion = this.database.prepare("SELECT MAX(version) AS version FROM relay_schema").get().version;
+		assert.ok(Number.isSafeInteger(schemaVersion) && schemaVersion > 0, "non-empty Relay database has no valid schema version");
+		assert.ok(schemaVersion <= 10, `database schema version ${schemaVersion} is newer than supported version 10`);
+		this.database.exec("PRAGMA journal_mode = WAL");
+		this.assertDatabaseIntegrity("before schema initialization");
+		if (schemaVersion < 10) this.migrationBackupPath = this.createMigrationBackup(path, schemaVersion);
+		this.transaction(() => {
+			this.database.exec(SCHEMA_TABLES_SQL);
+			if (schemaVersion < 10) this.migrateSchema(schemaVersion);
+			this.assertRequiredTablesAndColumns();
+			this.database.exec(SCHEMA_INDEXES_SQL);
+			this.assertCurrentSchema();
+		});
+	}
+	createMigrationBackup(path, fromVersion) {
+		if (path === ":memory:" || typeof path !== "string") return null;
+		const backupPath = `${path}.backup-v${fromVersion}-to-v10.sqlite`;
+		if (existsSync(backupPath)) {
+			assertDatabaseFileIsHealthy(backupPath, "existing migration backup");
+			return backupPath;
+		}
+		const temporaryPath = `${backupPath}.tmp-${process.pid}-${randomUUID()}`;
+		try {
+			this.database.exec(`VACUUM INTO ${sqlString(temporaryPath)}`);
+			assertDatabaseFileIsHealthy(temporaryPath, "new migration backup");
+			renameSync(temporaryPath, backupPath);
+			return backupPath;
+		} catch (error) {
+			if (existsSync(temporaryPath)) rmSync(temporaryPath);
+			throw new Error(`could not create verified migration backup ${backupPath}: ${error.message}`, { cause: error });
 		}
-		this.database.prepare("INSERT OR IGNORE INTO runtime_counters (name, value) VALUES ('routing_epoch', 0)").run();
 	}
 	migrateSchema(fromVersion) {
-		if (fromVersion < 3) {
-			if (!this.database.prepare("PRAGMA table_info(runs)").all().some((column) => column.name === "activation_id")) this.transaction(() => {
+		for (let targetVersion = fromVersion + 1; targetVersion <= 10; targetVersion += 1) {
+			this.applyMigration(targetVersion);
+			this.database.prepare("INSERT INTO relay_schema (version, applied_at) VALUES (?, ?)").run(targetVersion, this.now());
+		}
+	}
+	applyMigration(targetVersion) {
+		if (targetVersion === 2) return;
+		if (targetVersion === 3) {
+			if (!this.database.prepare("PRAGMA table_info(runs)").all().some((column) => column.name === "activation_id")) {
 				this.database.exec("ALTER TABLE runs ADD COLUMN activation_id TEXT");
 				const runs = this.database.prepare("SELECT * FROM runs ORDER BY started_at, id").all();
 				for (const run of runs) {
@@ -729,17 +779,18 @@ var RelayStore = class {
 					const state = run.state === "running" ? "active" : "committed";
 					const timestamp = run.finished_at ?? run.started_at;
 					this.database.prepare(`
-                INSERT INTO activations (
-                  id, session_id, trigger_type, state, delivery_ids_json,
-                  provisional_outcome_json, provisional_at, committed_at,
-                  created_at, updated_at
-                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-              `).run(activationId, run.session_id, run.trigger_type, state, run.delivery_ids_json, run.outcome_json, run.outcome_json == null ? null : timestamp, state === "committed" ? timestamp : null, run.started_at, timestamp);
+              INSERT INTO activations (
+                id, session_id, trigger_type, state, delivery_ids_json,
+                provisional_outcome_json, provisional_at, committed_at,
+                created_at, updated_at
+              ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            `).run(activationId, run.session_id, run.trigger_type, state, run.delivery_ids_json, run.outcome_json, run.outcome_json == null ? null : timestamp, state === "committed" ? timestamp : null, run.started_at, timestamp);
 					this.database.prepare("UPDATE runs SET activation_id = ? WHERE id = ?").run(activationId, run.id);
 				}
-			});
+			}
+			return;
 		}
-		if (fromVersion < 4) {
+		if (targetVersion === 4) {
 			const columns = this.database.prepare("PRAGMA table_info(activations)").all();
 			const names = new Set(columns.map((column) => column.name));
 			for (const [name, type] of [
@@ -748,8 +799,8 @@ var RelayStore = class {
 				["accepted_at", "TEXT"],
 				["last_error", "TEXT"]
 			]) if (!names.has(name)) this.database.exec(`ALTER TABLE activations ADD COLUMN ${name} ${type}`);
-			this.transaction(() => {
-				this.database.exec(`
+			const routingSql = this.database.prepare("SELECT sql FROM sqlite_schema WHERE type = 'table' AND name = 'routing_decisions'").get()?.sql ?? "";
+			if (/\bspawn\b/u.test(routingSql)) this.database.exec(`
           ALTER TABLE routing_decisions RENAME TO routing_decisions_v3;
           CREATE TABLE routing_decisions (
             id TEXT PRIMARY KEY,
@@ -771,15 +822,16 @@ var RelayStore = class {
           FROM routing_decisions_v3;
           DROP TABLE routing_decisions_v3;
         `);
-			});
+			return;
 		}
-		if (fromVersion < 5) {
+		if (targetVersion === 5) {
 			const columns = this.database.prepare("PRAGMA table_info(delivery_waits)").all();
 			const names = new Set(columns.map((column) => column.name));
 			if (!names.has("ordinal")) this.database.exec("ALTER TABLE delivery_waits ADD COLUMN ordinal INTEGER NOT NULL DEFAULT 0");
 			if (!names.has("wait_snapshot_json")) this.database.exec("ALTER TABLE delivery_waits ADD COLUMN wait_snapshot_json TEXT");
+			return;
 		}
-		if (fromVersion < 6) {
+		if (targetVersion === 6) {
 			const columns = this.database.prepare("PRAGMA table_info(monitors)").all();
 			const names = new Set(columns.map((column) => column.name));
 			for (const [name, type] of [
@@ -789,8 +841,10 @@ var RelayStore = class {
 				["terminal_actor", "TEXT"],
 				["terminal_at", "TEXT"]
 			]) if (!names.has(name)) this.database.exec(`ALTER TABLE monitors ADD COLUMN ${name} ${type}`);
+			return;
 		}
-		if (fromVersion < 7) this.database.exec(`
+		if (targetVersion === 7) {
+			this.database.exec(`
         CREATE TABLE IF NOT EXISTS notification_outcomes (
           event_id TEXT PRIMARY KEY REFERENCES events(id),
           provider TEXT,
@@ -800,11 +854,13 @@ var RelayStore = class {
           updated_at TEXT NOT NULL
         ) STRICT;
       `);
-		if (fromVersion < 8) {
+			return;
+		}
+		if (targetVersion === 8) {
 			if (!this.database.prepare("PRAGMA table_info(events)").all().some((column) => column.name === "correlation_key")) this.database.exec("ALTER TABLE events ADD COLUMN correlation_key TEXT");
-			this.database.exec("CREATE UNIQUE INDEX IF NOT EXISTS events_trusted_correlation ON events(correlation_key) WHERE correlation_key IS NOT NULL");
+			return;
 		}
-		if (fromVersion < 9) {
+		if (targetVersion === 9) {
 			const columns = new Set(this.database.prepare("PRAGMA table_info(activations)").all().map((column) => column.name));
 			for (const [name, type] of [
 				["attempt_count", "INTEGER NOT NULL DEFAULT 0"],
@@ -812,12 +868,36 @@ var RelayStore = class {
 				["terminal_reason_code", "TEXT"],
 				["terminal_at", "TEXT"]
 			]) if (!columns.has(name)) this.database.exec(`ALTER TABLE activations ADD COLUMN ${name} ${type}`);
+			return;
 		}
-		if (fromVersion < 10) {
+		if (targetVersion === 10) {
 			const columns = new Set(this.database.prepare("PRAGMA table_info(notification_outcomes)").all().map((column) => column.name));
 			if (!columns.has("receipt_id")) this.database.exec("ALTER TABLE notification_outcomes ADD COLUMN receipt_id TEXT");
 			if (!columns.has("attempt_count")) this.database.exec("ALTER TABLE notification_outcomes ADD COLUMN attempt_count INTEGER NOT NULL DEFAULT 0");
+			return;
 		}
+		throw new Error(`no Relay database migration is defined for schema version ${targetVersion}`);
+	}
+	assertRequiredTablesAndColumns() {
+		const expected = expectedSchemaShape();
+		for (const [table, expectedColumns] of expected.tables) {
+			const actualColumns = new Set(this.database.prepare(`PRAGMA table_info(${quoteIdentifier(table)})`).all().map((column) => column.name));
+			assert.ok(actualColumns.size > 0, `required table ${table} is missing`);
+			for (const column of expectedColumns) assert.ok(actualColumns.has(column), `required column ${table}.${column} is missing`);
+		}
+	}
+	assertCurrentSchema() {
+		this.assertRequiredTablesAndColumns();
+		const expected = expectedSchemaShape();
+		const actualIndexes = new Map(this.database.prepare("SELECT name, sql FROM sqlite_schema WHERE type = 'index' AND sql IS NOT NULL").all().map((row) => [row.name, normalizeSql(row.sql)]));
+		for (const [name, sql] of expected.indexes) assert.equal(actualIndexes.get(name), sql, `required index ${name} does not match the current schema`);
+		this.assertDatabaseIntegrity("after schema initialization");
+		const foreignKeyFailures = this.database.prepare("PRAGMA foreign_key_check").all();
+		assert.deepEqual(foreignKeyFailures, [], "Relay database contains foreign-key violations");
+	}
+	assertDatabaseIntegrity(stage) {
+		const results = this.database.prepare("PRAGMA quick_check").all();
+		assert.deepEqual(results.map((row) => row.quick_check), ["ok"], `Relay database failed integrity validation ${stage}`);
 	}
 	close() {
 		this.database.close();
@@ -2114,6 +2194,40 @@ var RelayStore = class {
 		this.database.prepare("UPDATE runtime_counters SET value = value + 1 WHERE name = 'routing_epoch'").run();
 	}
 };
+let cachedExpectedSchemaShape;
+function expectedSchemaShape() {
+	if (cachedExpectedSchemaShape) return cachedExpectedSchemaShape;
+	const reference = new DatabaseSync(":memory:");
+	try {
+		reference.exec(SCHEMA_SQL);
+		const tableNames = reference.prepare("SELECT name FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all().map((row) => row.name);
+		cachedExpectedSchemaShape = {
+			tables: new Map(tableNames.map((table) => [table, reference.prepare(`PRAGMA table_info(${quoteIdentifier(table)})`).all().map((column) => column.name)])),
+			indexes: new Map(reference.prepare("SELECT name, sql FROM sqlite_schema WHERE type = 'index' AND sql IS NOT NULL ORDER BY name").all().map((row) => [row.name, normalizeSql(row.sql)]))
+		};
+		return cachedExpectedSchemaShape;
+	} finally {
+		reference.close();
+	}
+}
+function assertDatabaseFileIsHealthy(path, label) {
+	const database = new DatabaseSync(path, { readOnly: true });
+	try {
+		const results = database.prepare("PRAGMA quick_check").all().map((row) => row.quick_check);
+		assert.deepEqual(results, ["ok"], `${label} failed SQLite integrity validation: ${path}`);
+	} finally {
+		database.close();
+	}
+}
+function normalizeSql(value) {
+	return value.replace(/\s+/gu, " ").trim().replace(/;$/u, "");
+}
+function quoteIdentifier(value) {
+	return `"${value.replaceAll("\"", "\"\"")}"`;
+}
+function sqlString(value) {
+	return `'${value.replaceAll("'", "''")}'`;
+}
 function hydrateWaitRegistration(row, waits) {
 	return {
 		session_id: row.id,