A local-first multi-agent app development platform, built on PenguinHarness
test(server): pin both web.db upgrade directions (#483)
Yaowei Zhengbd8344c7f65c
diff --git a/changelog/unreleased/2026-08-27-web-db-upgrade-direction-tests.md b/changelog/unreleased/2026-08-27-web-db-upgrade-direction-tests.mdnew file mode 100644index 00000000..a2a225c9--- /dev/null+++ b/changelog/unreleased/2026-08-27-web-db-upgrade-direction-tests.md@@ -0,0 +1,30 @@+# The web.db upgrade directions are pinned by tests++- **Date:** 2026-08-27+- **Type:** process+- **Scope:** `server`+- **PR:** [#483](https://github.com/Prism-Shadow/penguin-harness/pull/483)++[中文版](2026-08-27-web-db-upgrade-direction-tests.zh.md)++`openDatabase` had coverage for one of the three shapes a released build meets on disk: a+`sessions` table formed before a column existed. Two more were added, both derived from the real+`SCHEMA_SQL` rather than a hand-copied DDL replica, in the style the file already used.++## Details++- A database formed before `messaging_bindings` existed — every `web.db` written by 0.2.4 or+ earlier — gets the table and its `idx_messaging_account` uniqueness index on open, keeps the+ Sessions that were already there, and accepts a binding immediately afterwards. Uniqueness is+ asserted on a raw `INSERT` that goes around `MessagingBindingsRepo`'s own pre-check, which is+ the only write that reaches the index rather than the repo's SELECT.+- A database written by a **newer** build, opened by this one: an unknown table, an unknown+ column on `sessions` and an index over that column all survive the open untouched, and this+ build goes on reading and writing the rows it does own. This is the shape a user produces by+ updating, disliking the update and reinstalling the previous release.+- Where that tolerance stops is pinned next to it: two changes that add and remove nothing — a+ `NOT NULL` column with no default on a table this build writes, and a new unique index over+ columns it already writes — leave the open succeeding and the first write failing.++The tests state the condition each direction depends on, at the point a future schema change+would break it.diff --git a/changelog/unreleased/2026-08-27-web-db-upgrade-direction-tests.zh.md b/changelog/unreleased/2026-08-27-web-db-upgrade-direction-tests.zh.mdnew file mode 100644index 00000000..260e1b88--- /dev/null+++ b/changelog/unreleased/2026-08-27-web-db-upgrade-direction-tests.zh.md@@ -0,0 +1,27 @@+# web.db 的升级方向由测试钉住++- **Date:** 2026-08-27+- **Type:** process+- **Scope:** `server`+- **PR:** [#483](https://github.com/Prism-Shadow/penguin-harness/pull/483)++[English](2026-08-27-web-db-upgrade-direction-tests.md)++`openDatabase`此前只覆盖了已发布构建在磁盘上会遇到的三种形态之一:某一列出现之前就已形成的+`sessions` 表。此次补上另外两种,两者都从真实的 `SCHEMA_SQL` 推导而来,而非手抄一份 DDL 副本,+沿用该文件既有的写法。++## 细节++- 在 `messaging_bindings` 出现之前形成的数据库——即 0.2.4 及更早版本写出的每一个 `web.db`——在+ 打开时会拿到该表及其 `idx_messaging_account` 唯一索引,原有的 Session 保持不变,随后即可写入+ binding。唯一性由一条绕过 `MessagingBindingsRepo` 自身预检的裸 `INSERT` 断言:只有这样的写入+ 才会真正落到索引上,而不是停在仓储层的 SELECT。+- 由**更新**的构建写出、再由当前构建打开的数据库:未知的表、`sessions` 上未知的列,以及建立在该+ 列上的索引都原封不动地熬过这次打开,当前构建也照常读写它自己拥有的那些行。用户升级后不喜欢、+ 又装回上一个版本,产生的正是这种形态。+- 这份容忍的边界也钉在了旁边:两种纯追加、什么都没删掉的变更——当前构建会写入的表上多出一个没有+ 默认值的 `NOT NULL` 列,以及建立在它已经在写的列上的新唯一索引——都会让打开照常成功,却在第一次+ 写入时失败。++这些测试把每个方向所依赖的前提,钉在了未来某次 schema 变更会打破它的位置上。diff --git a/packages/server/test/db-upgrade.test.ts b/packages/server/test/db-upgrade.test.tsindex 714d2e0d..e15b3747 100644--- a/packages/server/test/db-upgrade.test.ts+++ b/packages/server/test/db-upgrade.test.ts@@ -3,6 +3,13 @@* existed gets it ALTERed in on open — CREATE TABLE IF NOT EXISTS alone never touches an* existing table, so without the guard, code writing the new columns would break on every* pre-existing database.+ *+ * The last two suites cover the other two directions a released build meets on disk: a table+ * that did not exist when the database was formed, and a database written by a *newer* build+ * than the one opening it (a user who updates, dislikes it, and reinstalls the previous+ * release). Nothing records a schema version, so both properties rest on every schema change+ * staying additive — and the downgrade one on more than that, which the last suite pins next to+ * the tolerance rather than leaving it implied.*/import { afterEach, beforeEach, describe, expect, it } from "vitest";import { mkdtemp, rm } from "node:fs/promises";@@ -11,6 +18,7 @@ import path from "node:path";import type { DatabaseSync } from "node:sqlite";import { openDatabase } from "../src/db/database.js";import { SCHEMA_SQL } from "../src/db/schema.js";+import { MessagingBindingsRepo } from "../src/db/repos/messaging-bindings.js";import { SessionsRepo } from "../src/db/repos/sessions.js";import type { SessionRow } from "../src/db/repos/sessions.js";@@ -281,3 +289,271 @@ describe("SessionsRepo last_active_at writes", () => {expect(repo.findById("s2")!.hasTrace).toBe(false);});});++/**+ * A table added to the schema after a web.db was formed. CREATE TABLE IF NOT EXISTS is the+ * whole mechanism — it creates the missing table and skips every table already there — so the+ * property to hold is that the new table (and its unique index) arrive on open while the rows+ * that were already on disk are untouched. `messaging_bindings` is the real instance: it+ * shipped in 0.2.5, so every database formed by 0.2.4 or earlier meets this path.+ */+describe("openDatabase table upgrade", () => {+ /**+ * Seeds a database in the shape it had **before** messaging_bindings existed, derived from+ * the real SCHEMA_SQL rather than a hand-copied DDL replica: create today's schema, then+ * drop exactly what that change introduced (dropping the table takes its index with it).+ */+ function seedPreMessagingDb(dbPath: string, seed: (db: DatabaseSync) => void): void {+ const db = new sqlite.DatabaseSync(dbPath);+ try {+ db.exec(SCHEMA_SQL);+ db.exec("DROP TABLE messaging_bindings");+ seed(db);+ } finally {+ db.close();+ }+ }++ it("creates messaging_bindings on a database formed before it existed, keeping existing rows", () => {+ const dbPath = path.join(dir, "web.db");+ seedPreMessagingDb(dbPath, (old) => {+ old+ .prepare(+ `INSERT INTO sessions (session_id, project_id, agent_id, provider, model_id, workspace, created_at)+ VALUES ('session-pre-messaging', 'p1', 'a1', 'custom', 'm1', '/w', '2026-01-01T00:00:00.000Z')`,+ )+ .run();+ });+ // Read the pre-state and close before asserting on it: a failed expect between open and+ // close leaks the handle, which is exactly what afterEach's rm cannot survive on Windows.+ const beforeTables = new sqlite.DatabaseSync(dbPath);+ let tablesBefore: unknown[];+ try {+ tablesBefore = beforeTables+ .prepare(+ "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'messaging_bindings'",+ )+ .all();+ } finally {+ beforeTables.close();+ }+ expect(tablesBefore).toEqual([]);++ const db = openDatabase(dbPath);+ try {+ // The table and the account uniqueness index both arrive; the pre-existing Session is+ // still there, which is what makes this an upgrade rather than a reset.+ expect(+ db+ .prepare(+ "SELECT name FROM sqlite_master WHERE type = 'index' AND name = 'idx_messaging_account'",+ )+ .all(),+ ).toHaveLength(1);+ expect(new SessionsRepo(db).findById("session-pre-messaging")).not.toBeNull();+ // And it is immediately writable — a newly created table with no rows would look+ // identical to one the upgrade forgot to create until something tries to use it.+ const repo = new MessagingBindingsRepo(db);+ const saved = repo.upsert({+ sessionId: "session-pre-messaging",+ channel: "telegram",+ accountId: "12345",+ config: { botToken: "t" },+ });+ expect(saved.ok).toBe(true);+ expect(repo.find("session-pre-messaging", "telegram")?.accountId).toBe("12345");+ // A second Session claiming the same account is refused...+ expect(+ repo.upsert({+ sessionId: "other-session",+ channel: "telegram",+ accountId: "12345",+ config: { botToken: "t" },+ }),+ ).toEqual({ ok: false, reason: "account_in_use" });+ // ...but that refusal comes from the repo's own findByAccount pre-check, which answers+ // identically over a non-unique index — so it says nothing about what the upgrade+ // created. Only a write that goes around the pre-check reaches the index, so the+ // uniqueness is asserted on the raw INSERT. (The row differs in session_id, so the+ // (session_id, channel) primary key cannot be what rejects it.)+ expect(() =>+ db+ .prepare(+ `INSERT INTO messaging_bindings+ (session_id, channel, account_id, config_json, created_at, updated_at)+ VALUES ('other-session', 'telegram', '12345', '{}', ?, ?)`,+ )+ .run("2026-01-01T00:00:00.000Z", "2026-01-01T00:00:00.000Z"),+ ).toThrow(/UNIQUE constraint failed/);+ } finally {+ db.close();+ }+ });+});++/**+ * The downgrade direction: a database written by a **newer** build, opened by this one. It is+ * what a user produces by updating, disliking the update and reinstalling the previous+ * release, and it is the direction with no safety net at all — nothing stamps a schema+ * version, so an older build cannot tell it is looking at a newer database and simply proceeds.+ *+ * That is safe only while every schema change is additive, which is the first invariant+ * asserted here: tables and columns this build has never heard of must survive the open+ * untouched, because the only thing standing between them and deletion is that no code path+ * drops what it does not recognize.+ *+ * Additive is necessary but not sufficient, which the second test pins: two changes that add+ * and remove nothing — a NOT NULL column with no default, a new unique index — still land on+ * this build's own writes. Read together the pair states the real rule a future schema change+ * has to obey, and the second half is the half that is easy to miss.+ */+describe("openDatabase tolerates a database from a newer build", () => {+ /**+ * `sessions` as a newer build that FORMED the database would have written it: the real+ * SCHEMA_SQL with one column spliced in, so the fixture cannot fork from the schema it+ * imitates. It throws rather than returning the schema unchanged when the anchor moves — a+ * splice that silently stops splicing leaves a test that passes forever and asserts nothing.+ */+ function schemaWithExtraSessionsColumn(ddl: string): string {+ const anchor = " last_active_at TEXT,";+ if (!SCHEMA_SQL.includes(anchor)) {+ throw new Error(`sessions anchor missing from SCHEMA_SQL: ${anchor}`);+ }+ return SCHEMA_SQL.replace(anchor, `${anchor}\n ${ddl},`);+ }++ it("leaves unknown tables, columns and indexes intact across an open", () => {+ const dbPath = path.join(dir, "web.db");+ const current = openDatabase(dbPath);+ new SessionsRepo(current).insert({+ sessionId: "s1",+ projectId: "p1",+ agentId: "a1",+ provider: "custom",+ modelId: "m1",+ workspace: "/w",+ approvalMode: "allow-all",+ title: null,+ createdAt: "2026-05-01T00:00:00.000Z",+ lastActiveAt: "2026-05-01T00:00:00.000Z",+ });+ // Stand in for a future release: a table this build has never heard of, a column added to+ // one it owns, and an index over that column. The column carries a DEFAULT because that is+ // what SQLite's ALTER TABLE ADD COLUMN requires, so it is what a future ensureColumn entry+ // would carry too — which is why this build's own inserts keep working here. A newer build+ // that FORMS the database is under no such constraint; the next test covers that.+ current.exec(`+ CREATE TABLE future_feature (id TEXT PRIMARY KEY, payload TEXT NOT NULL);+ INSERT INTO future_feature (id, payload) VALUES ('f1', 'written by a newer build');+ ALTER TABLE sessions ADD COLUMN future_flag INTEGER NOT NULL DEFAULT 7;+ CREATE INDEX idx_future_flag ON sessions(future_flag);+ `);+ current.close();++ const reopened = openDatabase(dbPath);+ try {+ // The unknown table and its row are untouched.+ expect(reopened.prepare("SELECT payload FROM future_feature WHERE id = 'f1'").get()).toEqual({+ payload: "written by a newer build",+ });+ // So is the unknown column and the index over it.+ expect(+ reopened.prepare("SELECT future_flag FROM sessions WHERE session_id = 's1'").get(),+ ).toEqual({ future_flag: 7 });+ expect(+ reopened+ .prepare(+ "SELECT name FROM sqlite_master WHERE type = 'index' AND name = 'idx_future_flag'",+ )+ .all(),+ ).toHaveLength(1);+ // And this build still reads and writes the rows it does own, alongside the column it+ // cannot see — the unknown column's DEFAULT is what keeps this insert legal.+ const repo = new SessionsRepo(reopened);+ expect(repo.findById("s1")!.lastActiveAt).toBe("2026-05-01T00:00:00.000Z");+ repo.insert({+ sessionId: "s2",+ projectId: "p1",+ agentId: "a1",+ provider: "custom",+ modelId: "m1",+ workspace: "/w",+ approvalMode: "allow-all",+ title: null,+ createdAt: "2026-05-02T00:00:00.000Z",+ lastActiveAt: "2026-05-02T00:00:00.000Z",+ });+ expect(repo.listByAgent("p1", "a1").map((r) => r.sessionId)).toEqual(["s2", "s1"]);+ } finally {+ reopened.close();+ }+ });++ it("a defaultless NOT NULL column or a new unique index still breaks this build's writes", () => {+ // Neither change removes anything, so both pass an "is it additive?" reading — and both+ // leave this build opening the database happily and then failing on its first write. The+ // open is where a version stamp would be checked, so the failure surfaces at an arbitrary+ // later moment instead; that is the cost of not having one, stated as an assertion.++ // 1. A NOT NULL column with no default. SQLite forbids that shape in ALTER TABLE ADD+ // COLUMN, which is what makes every ensureColumn entry safe — but a newer build that+ // forms the database writes CREATE TABLE, where the shape is perfectly legal.+ const formedByNewer = path.join(dir, "formed-by-newer.db");+ const newer = new sqlite.DatabaseSync(formedByNewer);+ try {+ newer.exec(schemaWithExtraSessionsColumn("future_required TEXT NOT NULL"));+ } finally {+ newer.close();+ }+ const opened = openDatabase(formedByNewer);+ try {+ expect(() =>+ new SessionsRepo(opened).insert({+ sessionId: "s1",+ projectId: "p1",+ agentId: "a1",+ provider: "custom",+ modelId: "m1",+ workspace: "/w",+ approvalMode: "allow-all",+ title: null,+ createdAt: "2026-05-01T00:00:00.000Z",+ lastActiveAt: "2026-05-01T00:00:00.000Z",+ }),+ ).toThrow(/NOT NULL constraint failed: sessions\.future_required/);+ } finally {+ opened.close();+ }++ // 2. A unique index over columns this build already writes. Nothing is added to any row,+ // yet rows this build creates today stop being insertable.+ const withUniqueIndex = path.join(dir, "unique-index.db");+ const newerIndexed = openDatabase(withUniqueIndex);+ try {+ newerIndexed.exec(+ "CREATE UNIQUE INDEX idx_future_one_session_per_agent ON sessions(project_id, agent_id)",+ );+ } finally {+ newerIndexed.close();+ }+ const reopenedIndexed = openDatabase(withUniqueIndex);+ try {+ const repo = new SessionsRepo(reopenedIndexed);+ const row = {+ projectId: "p1",+ agentId: "a1",+ provider: "custom",+ modelId: "m1",+ workspace: "/w",+ approvalMode: "allow-all" as const,+ title: null,+ createdAt: "2026-05-01T00:00:00.000Z",+ lastActiveAt: "2026-05-01T00:00:00.000Z",+ };+ repo.insert({ ...row, sessionId: "s1" });+ expect(() => repo.insert({ ...row, sessionId: "s2" })).toThrow(/UNIQUE constraint failed/);+ } finally {+ reopenedIndexed.close();+ }+ });+});