@bevel-software/platform-core-backend 0.31.0 → 0.33.0

package/src/modules/auth/account-hooks.ts

@@ -1,5 +1,6 @@
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
+import { ListenerSeam, type NotifyingListener } from '../../shared/listener-seam.js';
 
 const log = logger('accounts');
 
@@ -24,13 +25,10 @@ export interface AccountInvitedEvent {
 
 /**
  * A listener answers how it reached the person — a non-empty channel name,
- * `'email'` say — or null when it did not (nothing configured, the send
- * failed). It is awaited: the admin's answer says who was notified,
- * truthfully, so a listener bounds its own wait. A throw is logged and
- * counts as null; it never fails the invite. An empty name is no channel and
- * counts as null too.
+ * `'email'` say — or null when it did not; the rule is {@link NotifyingListener}'s:
+ * awaited, a throw logged and counted as null, never failing the invite.
  */
-export type AccountInvitedHook = (event: AccountInvitedEvent) => Promise<string | null>;
+export type AccountInvitedHook = NotifyingListener<AccountInvitedEvent>;
 
 /**
  * Core's seam for "an account was invited": a deployment (the cloud with its
@@ -46,24 +44,18 @@ export interface IAccountHooks {
 }
 
 export class AccountHooks implements IAccountHooks {
-  private readonly invited: AccountInvitedHook[] = [];
+  // The account exists whether or not the person was told: the admin's
+  // answer says they were not, and the admin sends the link themselves.
+  private readonly invited = new ListenerSeam<AccountInvitedEvent>(
+    log,
+    'an account-invited listener failed; the person was not notified by it:',
+  );
 
   onAccountInvited(hook: AccountInvitedHook): void {
-    this.invited.push(hook);
+    this.invited.add(hook);
   }
 
-  async runAccountInvited(event: AccountInvitedEvent): Promise<string[]> {
-    const notified: string[] = [];
-    for (const hook of this.invited) {
-      try {
-        const channel = await hook(event);
-        if (channel !== null && channel !== '') notified.push(channel);
-      } catch (err) {
-        // The account exists whether or not the person was told: the admin's
-        // answer says they were not, and the admin sends the link themselves.
-        log.error('an account-invited listener failed; the person was not notified by it:', { err });
-      }
-    }
-    return notified;
+  runAccountInvited(event: AccountInvitedEvent): Promise<string[]> {
+    return this.invited.run(event);
   }
 }

package/src/modules/auth/account-switch-lock.ts

@@ -1,8 +1,8 @@
 import { sql } from 'drizzle-orm';
-import type { Database } from '../database/connection.js';
+import type { Database } from '../database/index.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
-import { pgErrorCode } from '../database/pg-error.js';
+import { pgErrorCode } from '../database/index.js';
 
 /** The handle `db.transaction` hands its callback. */
 type Tx = Parameters<Parameters<Database['transaction']>[0]>[0];

package/src/modules/auth/account.routes.ts

@@ -9,9 +9,9 @@ import type { AuthService } from './auth.service.js';
 import type { IAccountHooks } from './account-hooks.js';
 import { AccountAdmissionRefusedError, AccountChangeRefusedError } from './account-admission.js';
 import { erasedAccountId, type IAccountErasureService } from './account-erasure.service.js';
-import type { IAdminAccessService } from '../admin/admin.interface.js';
-import type { UserAccessRemovalService } from '../access/user-access-removal.service.js';
-import { sendError } from '../access/admin-route-helpers.js';
+import type { IAdminAccessService } from '../admin/index.js';
+import type { UserAccessRemovalService } from '../access/index.js';
+import { sendError } from '../access/index.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
 import './auth.middleware.js'; // Express Request augmentation

package/src/modules/auth/auth.service.ts

@@ -1,9 +1,9 @@
 import jwt from 'jsonwebtoken';
-import { and, eq, getTableColumns, isNotNull, isNull, sql } from 'drizzle-orm';
-import type { Database } from '../database/connection.js';
-import { users } from '../database/schema.js';
+import { and, eq, getTableColumns, inArray, isNotNull, isNull, sql } from 'drizzle-orm';
+import type { Database } from '../database/index.js';
+import { users } from '../database/index.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
-import { canonicalEmail, hashEmail } from '../../shared/email-identity.js';
+import { canonicalEmail } from '../../shared/email-identity.js';
 import {
   AccountAdmissionRefusedError,
   AccountChangeRefusedError,
@@ -19,8 +19,8 @@ import {
   timingSafeStringEqual,
   MIN_PASSWORD_LENGTH,
 } from './password-hash.js';
-import { RECOVERY_BOT_EMAIL } from '../workflow/recovery-bot.js';
-import { DIRECTORY_SYNC_BOT_EMAIL } from '../access/directory-sync-bot.js';
+import { RECOVERY_BOT_EMAIL } from '../workflow/index.js';
+import { DIRECTORY_SYNC_BOT_EMAIL } from '../access/index.js';
 import { takeAccountSwitchLock } from './account-switch-lock.js';
 import type { IAccountSwitchGuard } from './account-switch-guard.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
@@ -863,26 +863,27 @@ export class AuthService implements IAccountSwitchGuard {
   }
 
   /**
-   * Resolve a set of `authorId` hashes back to the app users that produced
-   * them. Used by the PR list to display the human who triggered each PR
-   * instead of the shared GitHub service account.
+   * The live accounts behind a set of addresses — the approvers of a change
+   * request just opened, which the workflow module hands to the deployment's
+   * notification listeners as people with accounts (`ApproverAccounts`).
    *
-   * Loads all users and hashes them in-process rather than indexing on a
-   * stored hash column — the user table is small (one row per team member)
-   * and refreshes are infrequent (PR list polls at 60s), so the cost is
-   * negligible and we avoid carrying a denormalised hash column.
+   * One indexed read through the email's blind index, never a scan of every
+   * account: this is asked on every change request opened, and a deployment
+   * is as large as it is. Switched-off accounts are left out — a person who
+   * cannot act on a request is not told of it — so a caller that needs them
+   * asks another way. Keyed by the canonical address asked for.
    */
-  async findUsersByEmailHash(
-    hashes: Set<string>,
+  async findActiveAccountsByEmail(
+    emails: readonly string[],
   ): Promise<Map<string, { id: string; email: string; name: string }>> {
     const result = new Map<string, { id: string; email: string; name: string }>();
-    if (hashes.size === 0) return result;
-    const rows = await this.db.select().from(users);
-    for (const row of rows) {
-      const h = hashEmail(row.email);
-      if (!hashes.has(h)) continue;
-      result.set(h, { id: row.id, email: row.email, name: row.name });
-    }
+    const canonical = [...new Set(emails.map((e) => canonicalEmail(e)).filter(Boolean))];
+    if (canonical.length === 0) return result;
+    const rows = await this.db
+      .select({ id: users.id, email: users.email, name: users.name })
+      .from(users)
+      .where(and(inArray(users.emailBidx, canonical), isNull(users.deactivatedAt)));
+    for (const row of rows) result.set(canonicalEmail(row.email), { id: row.id, email: row.email, name: row.name });
     return result;
   }
 

package/src/modules/auth/index.ts

@@ -27,3 +27,6 @@ export { timingSafeStringEqual } from './password-hash.js';
 // The Express `Request` augmentation (`req.userId`, …): a module whose routes
 // read it imports this entry, never the middleware file.
 import './auth.middleware.js';
+// Reached by other modules; exported here so they stop importing the files.
+export type { IAccountSwitchGuard } from './account-switch-guard.js';
+export type { AuthService } from './auth.service.js';

package/src/modules/auth/oidc-auth-provider.ts

@@ -8,7 +8,7 @@ import { AUTH_COOKIE_MAX_AGE_S } from './auth.routes.js';
 import { AUTH_COOKIE_NAME } from './auth.middleware.js';
 import type { AuthService } from './auth.service.js';
 import { AccountAdmissionRefusedError, AccountDeactivatedError } from './account-admission.js';
-import { normalizeIssuerUrl } from '../settings/oidc-check.js';
+import { normalizeIssuerUrl } from '../settings/index.js';
 
 // Short-lived CSRF state + PKCE verifier for the OAuth round-trip: set before
 // redirecting to the provider, verified/consumed on callback.

package/src/modules/code-mode/code-mode.tool.ts

@@ -13,7 +13,7 @@ import {
   runToolChain,
   withCallExample,
 } from '@bevel-software/platform-mcp-core';
-import type { SpillStore } from '../workspace/spill-store.js';
+import type { SpillStore } from '../workspace/index.js';
 import { utcpNameToTsInterfaceName, findToolByName, AmbiguousToolNameError } from './code-mode-names.js';
 
 /**

package/src/modules/connection-probe/connection-probe.service.ts

@@ -7,12 +7,9 @@ import '@utcp/mcp'; // side effect: registers the 'mcp' protocol (remote MCP `.t
 import { CommunicationProtocol, UtcpClientConfigSerializer, type CallTemplate } from '@utcp/sdk';
 import { CodeModeUtcpClient } from '@utcp/code-mode';
 import { registerManual } from '@bevel-software/platform-mcp-core';
-import type { IToolManualService, ToolHealthCheck, ToolProbeTarget } from '../tool-manuals/tool-manuals.contract.js';
-import type { ISecretsVaultService } from '../secrets-vault/secrets-vault.contract.js';
-// The concrete module, NOT the `secrets-vault` barrel: that barrel re-exports
-// the routes, and the routes import this module's contract — so going through
-// it would close an import cycle between the two modules.
-import { bevelSecretsLoaderConfig } from '../secrets-vault/secrets-variable-loader.js';
+import type { IToolManualService, ToolHealthCheck, ToolProbeTarget } from '../tool-manuals/index.js';
+import type { ISecretsVaultService } from '../secrets-vault/index.js';
+import { bevelSecretsLoaderConfig } from '../secrets-vault/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
 import type { IConnectionProbeService, ProbeStatus, ProbeVerdict } from './connection-probe.contract.js';

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,
+  );
+});