@bevel-software/platform-core-backend 0.32.0 → 0.34.0

package/src/modules/database/__tests__/legacy-change-request-body.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+import { parseLegacyChangeRequestBody } from '@bevel-software/platform-shared';
+
+/**
+ * The grammar bodies carried before a request's body became its description:
+ * the generated `## Affected owners` block, an access request's level and
+ * note in hidden markers, and identity markers. `moveLegacyRequestBodies`
+ * reads every stored body through this once; what it keeps and what it moves
+ * is pinned here.
+ */
+const GENERATED = [
+  '## Affected owners',
+  '',
+  '- `KnowledgeBase/Engineering/Knowledge/Avi-Checkin.md` — Admin',
+  '- `KnowledgeBase/GTM/Notes.md` — GTM Team',
+].join('\n');
+
+describe('parseLegacyChangeRequestBody', () => {
+  it('drops the generated owners block and keeps what the author typed', () => {
+    expect(parseLegacyChangeRequestBody(`Please take a look.\n\n${GENERATED}`)).toEqual({
+      description: 'Please take a look.',
+      changed: true,
+    });
+    expect(parseLegacyChangeRequestBody(GENERATED)).toEqual({ description: '', changed: true });
+  });
+
+  it("keeps the author's own headings, cutting only the LAST owners heading", () => {
+    const out = parseLegacyChangeRequestBody(`Lead.\n\n## Why now\n\nBecause.\n\n## Affected owners\n\nI mean the GTM ones.\n\n${GENERATED}`);
+    expect(out.description).toBe('Lead.\n\n## Why now\n\nBecause.\n\n## Affected owners\n\nI mean the GTM ones.');
+    expect(out.description).not.toContain('Avi-Checkin');
+  });
+
+  it("keeps a heading the author wrote with prose under it: the cut takes only the block openChangeRequest wrote", () => {
+    const prose = 'Lead.\n\n## Affected owners\n\nThe GTM ones, I think.';
+    expect(parseLegacyChangeRequestBody(prose)).toEqual({ description: prose, changed: false });
+    const mixed = 'Lead.\n\n## Affected owners\n\nSee below.\n\n- `KnowledgeBase/GTM/Notes.md` — GTM Team';
+    expect(parseLegacyChangeRequestBody(mixed)).toEqual({ description: mixed, changed: false });
+  });
+
+  it('cuts a block that ends in the summary line a request with many paths got', () => {
+    const long = `${GENERATED}\n\n…and 3 more changed path(s). All eligible approvers across this change: Admin; GTM Team`;
+    expect(parseLegacyChangeRequestBody(`Lead.\n\n${long}`)).toEqual({ description: 'Lead.', changed: true });
+  });
+
+
+  it("moves an access request's level and note out of the prose, keeping the quoted lines as prose", () => {
+    const body = [
+      '<!--hexis:access-request-level:owner-->',
+      'Rita \\(rita@x\\.io\\) asked for **Owner** on Research\\.',
+      '',
+      'Note from Rita:',
+      '',
+      '<!--hexis:access-request-note-->',
+      '> I maintain these pages \\*now\\*',
+      '> and the index',
+      '<!--/hexis:access-request-note-->',
+      '',
+      "Anyone who can edit this folder's access answers it.",
+      '',
+      GENERATED,
+    ].join('\n');
+    expect(parseLegacyChangeRequestBody(body)).toEqual({
+      description: [
+        'Rita \\(rita@x\\.io\\) asked for **Owner** on Research\\.',
+        '',
+        'Note from Rita:',
+        '',
+        '> I maintain these pages \\*now\\*',
+        '> and the index',
+        '',
+        "Anyone who can edit this folder's access answers it.",
+      ].join('\n'),
+      accessRequestLevel: 'owner',
+      accessRequestNote: 'I maintain these pages *now*\nand the index',
+      changed: true,
+    });
+  });
+
+  it('reads a level with no note, and a level alone', () => {
+    expect(parseLegacyChangeRequestBody('<!--hexis:access-request-level:write-->\nAna asked for **Can edit**.')).toEqual({
+      description: 'Ana asked for **Can edit**.',
+      accessRequestLevel: 'write',
+      changed: true,
+    });
+    expect(parseLegacyChangeRequestBody('<!--hexis:access-request-level:owner-->')).toEqual({
+      description: '',
+      accessRequestLevel: 'owner',
+      changed: true,
+    });
+  });
+
+  it("strips the identity markers older bodies carry, and only those — an author's own comment is prose", () => {
+    expect(parseLegacyChangeRequestBody('<!-- bevel:author:abc123 -->\nMy reason.')).toEqual({
+      description: 'My reason.',
+      changed: true,
+    });
+    expect(parseLegacyChangeRequestBody('My reason.\n<!-- TODO: ask Mia about the title -->')).toEqual({
+      description: 'My reason.\n<!-- TODO: ask Mia about the title -->',
+      changed: false,
+    });
+  });
+
+  it('leaves a body of the new shape alone', () => {
+    expect(parseLegacyChangeRequestBody('P2 - Planned\n\nA multi-line\nreason.')).toEqual({
+      description: 'P2 - Planned\n\nA multi-line\nreason.',
+      changed: false,
+    });
+    expect(parseLegacyChangeRequestBody('')).toEqual({ description: '', changed: false });
+  });
+
+  it('counts a body it only trims as changed, so the stored text ends up exactly what is shown', () => {
+    // The ends and runs of blank lines go; spaces inside a line are the author's.
+    expect(parseLegacyChangeRequestBody('  Lead.  \n\n\n\nMore.\n')).toEqual({
+      description: 'Lead.  \n\nMore.',
+      changed: true,
+    });
+  });
+});

package/src/modules/database/__tests__/legacy-request-bodies.pg.test.ts

@@ -0,0 +1,258 @@
+import { afterAll, describe, expect, it } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import { eq, sql } from 'drizzle-orm';
+import { closeDb, createDb, type Database } from '../connection.js';
+import { changeRequests, dataMigrations } from '../core-schema.js';
+import { runCoreMigrations, runPiiEncryptionBackfill } from '../migrate.js';
+import { coreMigrationsDir } from '../../../assets.js';
+import { IndexOnWrite, SealOnWrite } from '../../../shared/column-crypto.js';
+import { PG_ADMIN_URL, PG_TEST_TIMEOUT, dropScratchDatabases, scratchDatabaseUrl } from '../../../__tests__/pg-scratch.js';
+
+/**
+ * The data half of migration 0020, on a real Postgres: a deployment whose
+ * bodies still carry the generated owners block and an access request's
+ * level and note starts on this release, and comes out with the level and
+ * the note on their columns and the prose alone in the body. Pinned through
+ * the one entry point a start uses, `runCoreMigrations`, so the test fails if
+ * the pass is ever not wired to the start that applies 0020 — and shows that
+ * the next start writes nothing.
+ *
+ * Runs where `TEST_DATABASE_URL` names a server this role may create
+ * databases on, each test in a scratch database of its own.
+ */
+const KEY = randomBytes(32).toString('base64');
+const open: Database[] = [];
+const folders: string[] = [];
+
+/** The `data_migrations` row the move leaves behind — the pass's one public trace besides the rows. */
+const LEDGER_ROW = '0020_change_request_body_is_the_description';
+
+const GENERATED = ['## Affected owners', '', '- `Docs/a.md` — Admin', '- `Docs/b.md` — Jane <jane@x.io>'].join('\n');
+
+const ACCESS_REQUEST_BODY = [
+  '<!--hexis:access-request-level:owner-->',
+  'Rita \\(rita@x\\.io\\) asked for **Owner** on Research\\.',
+  '',
+  'Note from Rita:',
+  '',
+  '<!--hexis:access-request-note-->',
+  '> I maintain these pages now',
+  '<!--/hexis:access-request-note-->',
+  '',
+  "Anyone who can edit this folder's access answers it.",
+  '',
+  GENERATED,
+].join('\n');
+
+/** The core history as it stood BEFORE 0020: the packaged folder minus 0020 and its ledger table (0021), in a folder of this test's own. */
+function historyBefore0020(): string {
+  const folder = mkdtempSync(path.join(tmpdir(), 'hexis-core-before-0020-'));
+  folders.push(folder);
+  cpSync(coreMigrationsDir(), folder, { recursive: true });
+  rmSync(path.join(folder, '0020_change_request_body_is_the_description.sql'));
+  rmSync(path.join(folder, 'meta', '0020_snapshot.json'));
+  rmSync(path.join(folder, '0021_data_migrations_ledger.sql'));
+  rmSync(path.join(folder, 'meta', '0021_snapshot.json'));
+  const journalPath = path.join(folder, 'meta', '_journal.json');
+  const journal = JSON.parse(readFileSync(journalPath, 'utf8')) as { entries: { idx: number }[] };
+  journal.entries = journal.entries.filter((e) => e.idx < 20);
+  writeFileSync(journalPath, JSON.stringify(journal, null, 2));
+  return folder;
+}
+
+async function handle(): Promise<Database> {
+  const db = createDb(await scratchDatabaseUrl('hexis_legacy_bodies'), { piiKey: KEY });
+  open.push(db);
+  return db;
+}
+
+/**
+ * A database an older version left: started on the history to 0019 (so its
+ * personal-data backfill has run and sealed columns are trusted as sealed),
+ * holding the rows that version wrote — sealed as it sealed them, through SQL
+ * that names only the columns that existed then (the schema module already
+ * knows the two new ones).
+ */
+async function olderDeployment(): Promise<Database> {
+  const db = await handle();
+  // As that version's start did it: its SQL history, then its PII backfill.
+  await migrate(db, { migrationsFolder: historyBefore0020(), migrationsTable: '__drizzle_migrations_core' });
+  await runPiiEncryptionBackfill(db);
+  // Sealed by the handle's own connection, as every write through it is —
+  // the marks the column codecs hand it — so what the pass reads back is
+  // exactly what the older version wrote.
+  const seal = (plain: string) => new SealOnWrite(plain) as unknown as string;
+  const index = (plain: string) => new IndexOnWrite(plain) as unknown as string;
+  const row = (branch: string, title: string, body: string, email: string, name: string, state = 'open') =>
+    sql`(${branch}, 'main', ${seal(title)}, ${seal(body)}, ${seal(email)}, ${index(email)}, ${seal(name)}, ${state})`;
+  await db.execute(sql`
+    insert into change_requests (source_branch, target_branch, title, body, author_email, author_email_bidx, author_name, state) values
+      ${row('ada/draft', 'Ordinary', `Please take a look.\n\n## Why now\n\nBecause.\n\n${GENERATED}`, 'ada@example.com', 'Ada')},
+      ${row('rita/join-research', 'Access request: Research', ACCESS_REQUEST_BODY, 'rita@x.io', 'Rita')},
+      ${row('bo/clean', 'Already clean', 'P2 - Planned\n\nJust prose.', 'bo@example.com', 'Bo', 'merged')}
+  `);
+  return db;
+}
+
+const ledgerRows = async (db: Database) =>
+  (await db.select({ name: dataMigrations.name, note: dataMigrations.note }).from(dataMigrations)).map((r) => ({ name: r.name, note: r.note }));
+
+/** The ledger with its timestamps: what a second start must leave exactly as it found. */
+const ledger = async (db: Database) =>
+  (await db.select().from(dataMigrations)).map((r) => ({ name: r.name, note: r.note, appliedAt: r.appliedAt.toISOString() }));
+
+const rowsOf = async (db: Database) =>
+  (await db.select().from(changeRequests).orderBy(changeRequests.sourceBranch)).map((r) => ({
+    branch: r.sourceBranch,
+    body: r.body,
+    level: r.accessRequestLevel,
+    note: r.accessRequestNote,
+    updatedAt: r.updatedAt,
+  }));
+
+describe.skipIf(!PG_ADMIN_URL)('migration 0020 — a request body becomes its description', () => {
+  afterAll(async () => {
+    for (const db of open) await closeDb(db);
+    await dropScratchDatabases();
+    for (const folder of folders) rmSync(folder, { recursive: true, force: true });
+  }, PG_TEST_TIMEOUT);
+
+  it(
+    'the start that applies it moves the level and the note onto the columns and leaves the prose, open and closed rows alike',
+    async () => {
+      const db = await olderDeployment();
+      await runCoreMigrations(db, coreMigrationsDir());
+
+      expect(await rowsOf(db)).toEqual([
+        { branch: 'ada/draft', body: 'Please take a look.\n\n## Why now\n\nBecause.', level: null, note: null, updatedAt: null },
+        { branch: 'bo/clean', body: 'P2 - Planned\n\nJust prose.', level: null, note: null, updatedAt: null },
+        {
+          branch: 'rita/join-research',
+          body: [
+            'Rita \\(rita@x\\.io\\) asked for **Owner** on Research\\.',
+            '',
+            'Note from Rita:',
+            '',
+            '> I maintain these pages now',
+            '',
+            "Anyone who can edit this folder's access answers it.",
+          ].join('\n'),
+          level: 'owner',
+          note: 'I maintain these pages now',
+          updatedAt: null,
+        },
+      ]);
+    },
+    PG_TEST_TIMEOUT,
+  );
+
+  it(
+    'the next start writes nothing: the pass belongs to the start that applied 0020',
+    async () => {
+      const db = await olderDeployment();
+      await runCoreMigrations(db, coreMigrationsDir());
+      // A body written AFTER the release that happens to use the old words is
+      // the author's own, and a second start must not cut it.
+      await db
+        .update(changeRequests)
+        .set({ body: 'Lead.\n\n## Affected owners\n\nI mean the GTM ones.' })
+        .where(eq(changeRequests.sourceBranch, 'bo/clean'));
+
+      await runCoreMigrations(db, coreMigrationsDir());
+
+      const bo = (await rowsOf(db)).find((r) => r.branch === 'bo/clean');
+      expect(bo?.body).toBe('Lead.\n\n## Affected owners\n\nI mean the GTM ones.');
+    },
+    PG_TEST_TIMEOUT,
+  );
+
+  it(
+    'a start that died between the SQL history and the pass is finished by the next start',
+    async () => {
+      // The SQL history applied (drizzle's ledger has 0020 and 0021) but no
+      // `data_migrations` row: exactly what a crash in between leaves behind.
+      const db = await olderDeployment();
+      await migrate(db, { migrationsFolder: coreMigrationsDir(), migrationsTable: '__drizzle_migrations_core' });
+      expect(await ledgerRows(db)).toEqual([]);
+
+      await runCoreMigrations(db, coreMigrationsDir());
+
+      const rita = (await rowsOf(db)).find((r) => r.branch === 'rita/join-research');
+      expect(rita).toMatchObject({ level: 'owner', note: 'I maintain these pages now' });
+      expect(rita?.body).not.toContain('<!--');
+      expect(await ledgerRows(db)).toEqual([
+        { name: LEDGER_ROW, note: '2 of 3 change-request bodies moved to the description-only shape' },
+      ]);
+    },
+    PG_TEST_TIMEOUT,
+  );
+
+  it(
+    'a pass that fails midway leaves no body moved and no ledger row, and the next start does the whole of it',
+    async () => {
+      const db = await olderDeployment();
+      await migrate(db, { migrationsFolder: coreMigrationsDir(), migrationsTable: '__drizzle_migrations_core' });
+      // The second body the pass rewrites (in id order) is refused, after the
+      // first one was written.
+      await db.execute(sql`
+        create function refuse_rita() returns trigger language plpgsql as $refuse$
+        begin raise exception 'the start died here'; end $refuse$
+      `);
+      await db.execute(sql`
+        create trigger refuse_rita before update on change_requests
+        for each row when (old.source_branch = 'rita/join-research') execute function refuse_rita()
+      `);
+      const before = await rowsOf(db);
+
+      // The start dies in the pass: the SQL history was already applied, so
+      // the refusal can only come from the move's own UPDATE.
+      await expect(runCoreMigrations(db, coreMigrationsDir())).rejects.toThrow(/Failed query: update "change_requests"/);
+      expect(await rowsOf(db)).toEqual(before);
+      expect(await ledgerRows(db)).toEqual([]);
+
+      await db.execute(sql`drop trigger refuse_rita on change_requests`);
+      await runCoreMigrations(db, coreMigrationsDir());
+      const rows = await rowsOf(db);
+      expect(rows.find((r) => r.branch === 'ada/draft')?.body).toBe('Please take a look.\n\n## Why now\n\nBecause.');
+      expect(rows.find((r) => r.branch === 'rita/join-research')).toMatchObject({ level: 'owner', note: 'I maintain these pages now' });
+      expect((await ledgerRows(db)).map((r) => r.name)).toEqual([LEDGER_ROW]);
+    },
+    PG_TEST_TIMEOUT,
+  );
+
+  it(
+    'a start that finds the ledger row leaves the rows and the ledger exactly as they are',
+    async () => {
+      const db = await olderDeployment();
+      await runCoreMigrations(db, coreMigrationsDir());
+      const rowsAfterFirst = await rowsOf(db);
+      const ledgerAfterFirst = await ledger(db);
+      expect(ledgerAfterFirst.map((r) => r.name)).toEqual([LEDGER_ROW]);
+
+      await runCoreMigrations(db, coreMigrationsDir());
+
+      expect(await rowsOf(db)).toEqual(rowsAfterFirst);
+      expect(await ledger(db)).toEqual(ledgerAfterFirst);
+    },
+    PG_TEST_TIMEOUT,
+  );
+
+  it(
+    'a fresh database has nothing to move, and records that too',
+    async () => {
+      const db = await handle();
+      await runCoreMigrations(db, coreMigrationsDir());
+      expect(await ledgerRows(db)).toEqual([
+        { name: LEDGER_ROW, note: '0 of 0 change-request bodies moved to the description-only shape' },
+      ]);
+      const once = await ledger(db);
+      await runCoreMigrations(db, coreMigrationsDir());
+      expect(await ledger(db)).toEqual(once);
+    },
+    PG_TEST_TIMEOUT,
+  );
+});

package/src/modules/database/__tests__/pii-backfill.pg.test.ts

@@ -34,7 +34,6 @@ const TABLES = [
   'users',
   'pr_file_approvals',
   'pr_merge_log',
-  'pr_comments',
   'change_requests',
   'pending_commits',
   'file_locks',
@@ -98,8 +97,6 @@ async function plantLegacyRows(q: Query): Promise<void> {
   await q(`insert into pr_merge_log (pr_number, triggered_by_email, triggered_by_name, head_sha_at_merge, merge_method, succeeded, error)
     values (1, 'ada@example.com', 'Ada', 'abc', 'merge', true, null),
            (1, 'bo@example.com', 'Bo', 'abc', 'merge', false, 'Bo has no push right')`);
-  await q(`insert into pr_comments (pr_number, author_email, author_name, head_sha, body)
-    values (1, 'bo@example.com', 'Bo', 'abc', 'Looks right to me')`);
   await q(`insert into pending_commits (workspace_id, branch, path, author_email, author_name, last_error)
     values ('w', 'main', 'a.md', 'ada@example.com', 'Ada', 'rejected for Ada')`);
   await q(`insert into file_locks (workspace_id, branch, path, holder_user_id, holder_name, expires_at)
@@ -302,10 +299,6 @@ describe.skipIf(!ADMIN_URL)('personal data, on a real Postgres', () => {
         expect(log.every((r) => r.error === null || sealed(r.error))).toBe(true);
         expect(log.every((r) => r.triggered_by_email_bidx === keys.index(opened(r.triggered_by_email)))).toBe(true);
 
-        const [comment] = await q(`select * from pr_comments`);
-        expect([comment!.author_email, comment!.author_name, comment!.body].every(sealed)).toBe(true);
-        expect(comment!.author_email_bidx).toBe(keys.index('bo@example.com'));
-
         const [queued] = await q(`select * from pending_commits`);
         expect([queued!.author_email, queued!.author_name, queued!.last_error].every(sealed)).toBe(true);
         expect(queued!.author_email_bidx).toBe(keys.index('ada@example.com'));
@@ -347,6 +340,10 @@ describe.skipIf(!ADMIN_URL)('personal data, on a real Postgres', () => {
         ).rejects.toThrow();
         await expect(q(`insert into users (email, name) values ('x', 'x')`)).rejects.toThrow();
 
+        // Change-request comments are gone, storage and all (migration 0018).
+        const [comments] = await q(`select to_regclass('pr_comments')::text as t`);
+        expect(comments!.t).toBeNull();
+
         // And the application reads it back as it was written.
         const [read] = await db.select().from(users).where(eq(users.emailBidx, 'ADA@EXAMPLE.COM '));
         expect(read).toMatchObject({ email: 'Ada@Example.com', name: 'Ada', avatarUrl: null });
@@ -371,7 +368,7 @@ describe.skipIf(!ADMIN_URL)('personal data, on a real Postgres', () => {
         const exact = `pii:v1:${'A'.repeat(16)}:${'B'.repeat(22)}==:Q2xlYXI=`;
         const unpadded = `pii:v1:${'A'.repeat(16)}:${'B'.repeat(22)}:Q2xlYXI=`;
         await q(`update users set name = '${exact}' where email = 'bo@example.com'`);
-        await q(`update pr_comments set body = '${unpadded}'`);
+        await q(`update change_requests set title = '${unpadded}'`);
         await q(`update file_locks set holder_name = '${exact}'`);
 
         await runCoreMigrations(db, coreMigrationsDir());
@@ -379,9 +376,9 @@ describe.skipIf(!ADMIN_URL)('personal data, on a real Postgres', () => {
         const [bo] = await q(`select name from users where email_bidx = '${keys.index('bo@example.com')}'`);
         expect(bo!.name).not.toBe(exact);
         expect(opened(bo!.name)).toBe(exact);
-        const [comment] = await q(`select body from pr_comments`);
-        expect(comment!.body).not.toBe(unpadded);
-        expect(opened(comment!.body)).toBe(unpadded);
+        const [cr] = await q(`select title from change_requests`);
+        expect(cr!.title).not.toBe(unpadded);
+        expect(opened(cr!.title)).toBe(unpadded);
         const [lock] = await q(`select holder_name from file_locks`);
         expect(opened(lock!.holder_name)).toBe(exact);
         // And what the application reads back is what was typed.
@@ -400,17 +397,17 @@ describe.skipIf(!ADMIN_URL)('personal data, on a real Postgres', () => {
       async () => {
         const { db, q } = await beforeTheBackfill(await scratchDatabase());
         await plantLegacyRows(q);
-        await q(`insert into pr_comments (pr_number, author_email, author_name, head_sha, body)
-          select n, 'ada@example.com', 'Ada', 'abc', 'comment ' || n from generate_series(2, 1300) n`);
+        await q(`insert into pr_merge_log (pr_number, triggered_by_email, triggered_by_name, head_sha_at_merge, merge_method, succeeded, error)
+          select n, 'ada@example.com', 'Ada', 'abc', 'merge', false, 'refusal ' || n from generate_series(2, 1300) n`);
 
         await runCoreMigrations(db, coreMigrationsDir());
 
-        const [left] = await q(`select count(*)::int as n from pr_comments where body not like 'pii:v1:%' or author_email_bidx is null`);
+        const [left] = await q(`select count(*)::int as n from pr_merge_log where triggered_by_name not like 'pii:v1:%' or triggered_by_email_bidx is null`);
         expect(left!.n).toBe(0);
-        const [all] = await q(`select count(*)::int as n from pr_comments`);
-        expect(all!.n).toBe(1300);
-        const [one] = await q(`select body from pr_comments where pr_number = 1300`);
-        expect(opened(one!.body)).toBe('comment 1300');
+        const [all] = await q(`select count(*)::int as n from pr_merge_log`);
+        expect(all!.n).toBe(1301);
+        const [one] = await q(`select error from pr_merge_log where pr_number = 1300`);
+        expect(opened(one!.error)).toBe('refusal 1300');
       },
       TIMEOUT,
     );

package/src/modules/database/__tests__/session-version-migration.pg.test.ts

@@ -0,0 +1,133 @@
+import { afterAll, describe, expect, it } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import { sql } from 'drizzle-orm';
+import { closeDb, createDb, type Database } from '../connection.js';
+import { runCoreMigrations, runPiiEncryptionBackfill } from '../migrate.js';
+import { coreMigrationsDir } from '../../../assets.js';
+import { IndexOnWrite, SealOnWrite } from '../../../shared/column-crypto.js';
+import { PG_ADMIN_URL, PG_TEST_TIMEOUT, dropScratchDatabases, scratchDatabaseUrl } from '../../../__tests__/pg-scratch.js';
+
+/**
+ * Migration 0022 on a real Postgres, from both states a deployment can be in
+ * when it starts on this release: without `users.session_version` (every
+ * account starts at 0, so nobody is signed out by the upgrade), and with the
+ * column already there (the guarded `ADD COLUMN` changes nothing, so the
+ * generations it holds, and the sessions they honour, survive the start).
+ *
+ * Runs where `TEST_DATABASE_URL` names a server this role may create
+ * databases on, each test in a scratch database of its own.
+ */
+const KEY = randomBytes(32).toString('base64');
+const open: Database[] = [];
+const folders: string[] = [];
+
+/** The core history as it stood BEFORE 0022: the packaged folder minus 0022, in a folder of this test's own. */
+function historyBefore0022(): string {
+  const folder = mkdtempSync(path.join(tmpdir(), 'hexis-core-before-0022-'));
+  folders.push(folder);
+  cpSync(coreMigrationsDir(), folder, { recursive: true });
+  rmSync(path.join(folder, '0022_session_version.sql'));
+  rmSync(path.join(folder, 'meta', '0022_snapshot.json'));
+  const journalPath = path.join(folder, 'meta', '_journal.json');
+  const journal = JSON.parse(readFileSync(journalPath, 'utf8')) as { entries: { idx: number }[] };
+  journal.entries = journal.entries.filter((e) => e.idx < 22);
+  writeFileSync(journalPath, JSON.stringify(journal, null, 2));
+  return folder;
+}
+
+/**
+ * A database an older version left: started on the history to 0021, holding
+ * the accounts that version wrote, through SQL that names only the columns
+ * it knew. `withColumn` adds `session_version` by hand first, as a database
+ * that already has it would, and gives each account a generation of its own.
+ */
+async function olderDeployment(withColumn: boolean): Promise<Database> {
+  const db = createDb(await scratchDatabaseUrl('hexis_session_version'), { piiKey: KEY });
+  open.push(db);
+  await migrate(db, { migrationsFolder: historyBefore0022(), migrationsTable: '__drizzle_migrations_core' });
+  await runPiiEncryptionBackfill(db);
+  if (withColumn) await db.execute(sql`alter table users add column session_version integer default 0 not null`);
+  const seal = (plain: string) => new SealOnWrite(plain) as unknown as string;
+  const index = (plain: string) => new IndexOnWrite(plain) as unknown as string;
+  const account = (email: string, name: string) => sql`(${seal(email)}, ${index(email)}, ${seal(name)})`;
+  await db.execute(sql`
+    insert into users (email, email_bidx, name) values
+      ${account('ada@example.com', 'Ada')},
+      ${account('bo@example.com', 'Bo')}
+  `);
+  if (withColumn) {
+    await db.execute(sql`update users set session_version = 3 where email_bidx = ${index('ada@example.com')}`);
+    await db.execute(sql`update users set session_version = 7 where email_bidx = ${index('bo@example.com')}`);
+  }
+  return db;
+}
+
+/** How many migrations the packaged history holds — what a fresh start records as applied. */
+function packagedHistoryLength(): number {
+  const journal = JSON.parse(readFileSync(path.join(coreMigrationsDir(), 'meta', '_journal.json'), 'utf8')) as {
+    entries: unknown[];
+  };
+  return journal.entries.length;
+}
+
+/** Each account's generation, in a fixed order. */
+const generations = async (db: Database) =>
+  (await db.execute(sql`select session_version from users order by session_version`)).rows.map(
+    (r) => (r as { session_version: number }).session_version,
+  );
+
+/** What the column is: its type, default and nullability, as Postgres reports them. */
+const columnShape = async (db: Database) =>
+  (
+    await db.execute(sql`
+      select data_type, column_default, is_nullable from information_schema.columns
+      where table_schema = 'public' and table_name = 'users' and column_name = 'session_version'
+    `)
+  ).rows;
+
+const EXPECTED_SHAPE = [{ data_type: 'integer', column_default: '0', is_nullable: 'NO' }];
+
+describe.skipIf(!PG_ADMIN_URL)('migration 0022 (users.session_version), on a real Postgres', () => {
+  afterAll(async () => {
+    for (const db of open.splice(0)) await closeDb(db);
+    for (const folder of folders.splice(0)) rmSync(folder, { recursive: true, force: true });
+    await dropScratchDatabases();
+  }, PG_TEST_TIMEOUT);
+
+  it(
+    'adds the column at 0 for every existing account, so no session is ended by the upgrade',
+    async () => {
+      const db = await olderDeployment(false);
+      expect(await columnShape(db)).toEqual([]);
+
+      await runCoreMigrations(db, coreMigrationsDir());
+
+      expect(await columnShape(db)).toEqual(EXPECTED_SHAPE);
+      expect(await generations(db)).toEqual([0, 0]);
+    },
+    PG_TEST_TIMEOUT,
+  );
+
+  it(
+    'finds the column already there and changes nothing, keeping every generation it holds',
+    async () => {
+      const db = await olderDeployment(true);
+      expect(await columnShape(db)).toEqual(EXPECTED_SHAPE);
+
+      await runCoreMigrations(db, coreMigrationsDir());
+
+      expect(await columnShape(db)).toEqual(EXPECTED_SHAPE);
+      expect(await generations(db)).toEqual([3, 7]);
+      // And 0022 is recorded as applied, so the next start does not try it
+      // again — judged against the packaged history's own length, so a later
+      // migration does not make this count stale.
+      const applied = await db.execute(sql`select count(*)::int as n from drizzle.__drizzle_migrations_core`);
+      expect((applied.rows[0] as { n: number }).n).toBe(packagedHistoryLength());
+    },
+    PG_TEST_TIMEOUT,
+  );
+});