@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/modules/agent-instructions/compose.ts

@@ -0,0 +1,271 @@
+/**
+ * What a connected agent is told at the start of an MCP session, composed
+ * from two layers: a platform header the code owns, and the deployment
+ * preamble an admin writes in `mcp-description.md` at the repository root.
+ *
+ * Two channels carry the result. The full text goes out as `instructions` on
+ * the initialize handshake, which Claude Code, Claude Desktop and Cursor place
+ * in the model's system prompt. claude.ai on the web, the Agent SDK and Cline
+ * drop that field, so a short prefix is also prepended to the descriptions of
+ * the four knowledge-base tools (the one pre-call channel every client shows
+ * the model). Both are capped, because both land in every conversation.
+ *
+ * Pure: no IO, no clock. The reader beside it (`read-preamble.ts`) does the
+ * file access; the hosted proxy, the agent-facing route and the local bridge
+ * all read this one composer's output.
+ */
+
+// The file, the caps and the comment rule are shared with the frontend
+// editor: it shows what these strip and writes back what they allow, so a
+// hand-mirrored copy would let the admin's view and the agent's text drift
+// apart. Re-exported here because this module is where the backend reads them
+// from.
+import {
+  PREAMBLE_CAP,
+  PREAMBLE_FILE,
+  TOOL_PREFIX_CAP,
+  stripHtmlComments,
+} from '@bevel-software/platform-shared';
+
+export { PREAMBLE_CAP, PREAMBLE_FILE, TOOL_PREFIX_CAP };
+
+/** The tools whose descriptions carry the prefix. Every other tool is untouched. */
+export const PREFIXED_TOOLS: ReadonlySet<string> = new Set(['start_session', 'grep', 'list_files', 'read_file']);
+
+/**
+ * The platform header, owned by the code. What Hexis is, that its content is
+ * not in the model's training data, the order in which to search it, and that
+ * skills are reachable as prompts and through the two skill tools.
+ */
+export const PLATFORM_HEADER =
+  "Hexis is this organisation's knowledge base, together with the skills and tools its teams have approved. " +
+  'Its content is specific to the organisation and is not in your training data. ' +
+  'Before answering a question about the organisation, its people, customers, products, processes, projects or internal terms, ' +
+  'search the knowledge base: call `start_session` once, then `grep` for the key terms, `list_files` to orient, and `read_file` what matches. ' +
+  'Prefer what you find there over memory or the web, and say so when the knowledge base is silent on something the organisation should have documented. ' +
+  'Skills are available as prompts and through `list_skills` and `get_skill`.';
+
+/**
+ * The fixed first line of the tool prefix. It always leads, so an admin's
+ * first edit never removes the instruction from the clients that only see
+ * tool descriptions, and a preamble that opens with a heading still yields a
+ * sensible purpose line.
+ */
+export const TOOL_PREFIX_LINE = "This organisation's knowledge base. Search it before answering from memory.";
+
+/** The one-line marker that replaces everything past the preamble cap. */
+export const PREAMBLE_TRUNCATION_MARKER = `[preamble truncated at ${PREAMBLE_CAP.toLocaleString('en-US')} characters; shorten ${PREAMBLE_FILE}]`;
+
+export interface ComposedAgentInstructions {
+  /** The header, then the preamble body when there is one. Sent on the initialize handshake. */
+  instructions: string;
+  /** The platform header alone, so a card can show the fixed part apart from the admin's. */
+  header: string;
+  /** The preamble body as sent (cut and marked when over the cap); empty when there is none. */
+  preamble: string;
+  /** The fixed first line of the prefix, so a card can show which part of it the admin owns. */
+  toolPrefixLine: string;
+  /** The fixed line, then the preamble's first non-heading paragraph. Prepended to the four tools' descriptions. */
+  toolPrefix: string;
+  /** The preamble exceeded {@link PREAMBLE_CAP} and was cut, marker appended. */
+  truncated: boolean;
+  /** Length of the stripped preamble BEFORE the cut, so a card can show `N / 6,000`. */
+  preambleChars: number;
+  /** The prefix exceeded {@link TOOL_PREFIX_CAP} and was cut. */
+  toolPrefixTruncated: boolean;
+  /** Length of the prefix BEFORE the cut, so a card can show `N / 300`. */
+  toolPrefixChars: number;
+  /** The file has a `<!--` with no `-->`: everything from it to the end was withheld. */
+  unterminatedComment: boolean;
+}
+
+/**
+ * Compose the two texts from the raw file content (`null` when the file is
+ * absent). HTML comments are private notes and never leave the file; an
+ * unterminated `<!--` strips everything after it, so the most likely editing
+ * slip withholds text rather than leaking it.
+ */
+export function composeAgentInstructions(preamble: string | null): ComposedAgentInstructions {
+  const { text, unterminated } = stripHtmlComments(preamble ?? '');
+  const normalized = text.replace(/\r\n?/g, '\n');
+  const stripped = normalized.trim();
+  const preambleChars = stripped.length;
+  const truncated = preambleChars > PREAMBLE_CAP;
+  const body = truncated ? `${cutAtCodePoint(stripped, PREAMBLE_CAP)}\n${PREAMBLE_TRUNCATION_MARKER}` : stripped;
+  const instructions = body ? `${PLATFORM_HEADER}\n\n${body}` : PLATFORM_HEADER;
+
+  // Classified UNTRIMMED: the leading indentation of a first line is what
+  // makes it an indented code block, and the trim above would turn that
+  // code into prose. The paragraph itself comes back trimmed.
+  const paragraph = firstNonHeadingParagraph(normalized);
+  const fullPrefix = paragraph ? `${TOOL_PREFIX_LINE} ${paragraph}` : TOOL_PREFIX_LINE;
+  const toolPrefixChars = fullPrefix.length;
+  const toolPrefixTruncated = toolPrefixChars > TOOL_PREFIX_CAP;
+  const toolPrefix = toolPrefixTruncated ? cutAtCodePoint(fullPrefix, TOOL_PREFIX_CAP) : fullPrefix;
+
+  return {
+    instructions,
+    header: PLATFORM_HEADER,
+    preamble: body,
+    toolPrefix,
+    toolPrefixLine: TOOL_PREFIX_LINE,
+    truncated,
+    preambleChars,
+    toolPrefixTruncated,
+    toolPrefixChars,
+    unterminatedComment: unterminated,
+  };
+}
+
+/**
+ * A tool description with the prefix ahead of it: the prefix, a blank line,
+ * then the original. Purpose line first, because claude.ai cuts descriptions
+ * near 500 characters.
+ */
+export function prefixToolDescription(toolPrefix: string, description: string | undefined): string {
+  return description ? `${toolPrefix}\n\n${description}` : toolPrefix;
+}
+
+/** An ATX heading line: `#` to `######`, then a space or the end. */
+const ATX_HEADING = /^#{1,6}(\s|$)/;
+/** The underline of a setext heading: a run of `=` or `-` on its own line. */
+const SETEXT_UNDERLINE = /^(=+|-+)$/;
+/** A thematic break: three or more `-`, `*` or `_`, optionally spaced. */
+const THEMATIC_BREAK = /^([-*_])(\s*\1){2,}$/;
+/** The opener of a fenced code block: three or more backticks or tildes, then an optional info string. */
+const CODE_FENCE = /^(`{3,}|~{3,})/;
+/** A list item or a blockquote line: a setext underline cannot be a lazy continuation of either. */
+const LIST_ITEM_OR_QUOTE = /^([-*+]|\d{1,9}[.)])(\s|$)|^>/;
+
+/**
+ * The first paragraph that is not a markdown heading, collapsed to one line.
+ * Blocks are separated by blank lines and by code, fenced or indented; code
+ * is never a paragraph, so a fence and everything inside it (blank lines
+ * and rules included) are skipped, a fence that never closes runs to the
+ * end of the text, and an indented block is skipped line by line — all as
+ * in CommonMark (see `paragraphBlocks`). Inside a block, ATX heading lines and
+ * rules (a thematic break, or a bare `===` or `---` line) are never content,
+ * and a setext heading (paragraph text with a `===` or `---` underline
+ * directly beneath it) is dropped together with its underline, so
+ * `Title\n===\nText` and `## Title\nText` both yield `Text`. A rule beneath
+ * a list item or a blockquote, or beneath the lines that continue one, is
+ * not an underline (it cannot lazily continue either), so `- Item\n---`
+ * keeps the item and drops the rule. Empty when the text has no such
+ * paragraph (absent, empty, code-only or heading-only preamble).
+ */
+function firstNonHeadingParagraph(text: string): string {
+  for (const block of paragraphBlocks(text)) {
+    const kinds = block.map((l) => l.kind);
+    // A list item or blockquote owns every line beneath it until the block
+    // ends (a lazy continuation is trimmed to look like paragraph text), so
+    // once one opens, no rule further down the block is an underline.
+    let container = false;
+    let underline = -1;
+    kinds.forEach((kind, i) => {
+      if (kind === 'container') container = true;
+      else if (kind === 'rule' && i > 0 && !container && kinds[i - 1] === 'text' && SETEXT_UNDERLINE.test(block[i].text))
+        underline = i;
+    });
+    const content = block.filter((l, i) => i > underline && (l.kind === 'text' || l.kind === 'container'));
+    if (content.length > 0) return content.map((l) => l.text).join(' ').replace(/\s+/g, ' ');
+  }
+  return '';
+}
+
+type LineKind = 'heading' | 'rule' | 'container' | 'text';
+
+/** A block's line: its trimmed text and what it is, decided where it was read (see `paragraphBlocks`). */
+interface BlockLine {
+  text: string;
+  kind: LineKind;
+}
+
+/**
+ * What a line is on its own, in CommonMark's order of precedence: a rule is
+ * tested before a list item because `- - -` and `* * *` are breaks, not
+ * items. Whether a rule underlines the text above it depends on its
+ * neighbours and is decided by the caller.
+ */
+function lineKind(line: string): LineKind {
+  if (ATX_HEADING.test(line)) return 'heading';
+  if (THEMATIC_BREAK.test(line) || SETEXT_UNDERLINE.test(line)) return 'rule';
+  if (LIST_ITEM_OR_QUOTE.test(line)) return 'container';
+  return 'text';
+}
+
+/**
+ * The text's blocks outside code, each a list of trimmed non-blank lines.
+ *
+ * Indentation decides what is code, as in CommonMark: a fence opens or
+ * closes only when indented at most three columns, and a line indented
+ * four or more where no paragraph is open — at the start of a block, or
+ * right after a heading or a rule, which end whatever came before them —
+ * is an indented code block: literal text, so a ``` in it is content, not
+ * a fence that would swallow the rest of the file. Under paragraph text
+ * (a list item or blockquote included) the same indentation is a
+ * continuation, since indented code cannot interrupt a paragraph — and a
+ * continuation is paragraph TEXT whatever it says once trimmed: `    # x`
+ * under a line of prose is not a heading and `    ---` is not a rule, so
+ * each line's kind is decided here, with its indentation in hand, and
+ * carried with it.
+ */
+function paragraphBlocks(text: string): BlockLine[][] {
+  const blocks: BlockLine[][] = [];
+  let block: BlockLine[] = [];
+  let fence: string | null = null; // the opener of the fenced code block being skipped
+  const flush = () => {
+    if (block.length > 0) blocks.push(block);
+    block = [];
+  };
+  const paragraphOpen = () => {
+    const last = block[block.length - 1];
+    return last !== undefined && (last.kind === 'text' || last.kind === 'container');
+  };
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    const indent = indentColumns(raw);
+    if (fence !== null) {
+      // The closer: the opener's character only, at least as many of it, nothing else.
+      if (indent <= 3 && line.startsWith(fence) && /^(`+|~+)$/.test(line)) fence = null;
+      continue;
+    }
+    const opener = indent <= 3 ? CODE_FENCE.exec(line) : null;
+    if (opener) {
+      flush();
+      fence = opener[1];
+    } else if (line.length === 0) {
+      flush();
+    } else if (indent >= 4) {
+      // Indented code, skipped line by line (blank lines between flush
+      // nothing) — or, under an open paragraph, a continuation of it.
+      if (paragraphOpen()) block.push({ text: line, kind: 'text' });
+    } else {
+      block.push({ text: line, kind: lineKind(line) });
+    }
+  }
+  flush();
+  return blocks;
+}
+
+/** Leading indentation in columns, a tab reaching the next multiple of four. */
+function indentColumns(raw: string): number {
+  let columns = 0;
+  for (const ch of raw) {
+    if (ch === ' ') columns += 1;
+    else if (ch === '\t') columns += 4 - (columns % 4);
+    else break;
+  }
+  return columns;
+}
+
+/**
+ * `text` cut to at most `max` UTF-16 units, never inside a surrogate pair: a
+ * high surrogate at the cut moves the cut before it, so no broken character
+ * is ever sent and the count in the card matches what the server sends.
+ */
+function cutAtCodePoint(text: string, max: number): string {
+  if (text.length <= max) return text;
+  const last = text.charCodeAt(max - 1);
+  const end = last >= 0xd800 && last <= 0xdbff ? max - 1 : max;
+  return text.slice(0, end);
+}

package/src/modules/agent-instructions/index.ts

@@ -0,0 +1,14 @@
+export {
+  composeAgentInstructions,
+  prefixToolDescription,
+  PLATFORM_HEADER,
+  TOOL_PREFIX_LINE,
+  PREAMBLE_CAP,
+  TOOL_PREFIX_CAP,
+  PREAMBLE_FILE,
+  PREFIXED_TOOLS,
+  PREAMBLE_TRUNCATION_MARKER,
+  type ComposedAgentInstructions,
+} from './compose.js';
+export { readAgentPreamble, type AgentPreambleReader, type PreambleWorkspace } from './read-preamble.js';
+export { createAgentInstructionsRoutes } from './agent-instructions.routes.js';

package/src/modules/agent-instructions/read-preamble.ts

@@ -0,0 +1,88 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { isAbsence, type IFsProbe } from '../../shared/fs.contract.js';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import { PREAMBLE_FILE } from './compose.js';
+
+/** The one reader both the hosted proxy and the agent-facing route call. */
+export type AgentPreambleReader = () => Promise<string | null>;
+
+/** The two workspace operations the reader needs, so a test can stand in for the service. */
+export type PreambleWorkspace = Pick<WorkspaceService, 'getOrCreateForBranch' | 'getWorkspacePath'>;
+
+/**
+ * The raw content of `mcp-description.md` on the default branch, read with
+ * PLATFORM privileges: the root is default-deny for reads, and the preamble is
+ * a broadcast the admin writes for every connected agent, so it is never read
+ * as the caller. `null` only for an ABSENT file (the disk's own definition of
+ * absence); any other failure throws, so a disk fault never masquerades as
+ * "no preamble". The workspace is
+ * created first when it does not exist yet, exactly as the plugin archive
+ * route does.
+ *
+ * SYMLINKS ARE REFUSED, the same rule the plugin archive applies. This file is
+ * read as the platform and sent to every agent, so a link at this name (they
+ * only arrive by direct git push; the platform's own write paths never create
+ * one) would broadcast whatever the server process can read. `lstat` rejects a
+ * link or any non-regular entry before the open, and the open itself uses
+ * `O_NOFOLLOW` and reads through the handle it checked, so the bytes sent come
+ * from the inode the check passed rather than from a path swapped in between.
+ * The rule covers the WHOLE path below the workspace, not only the final
+ * component: the repository folder resolved through a link would put a
+ * regular file at the name with the link a level up, so the path's realpath
+ * must equal the spelled path under the workspace's own — identity, as the
+ * archive demands it, not mere containment. (The workspace root may itself
+ * sit behind a link — a mounted volume — which is the operator's, not the
+ * repository's, and is allowed.)
+ *
+ * Inside the workspace the repository is the `<kbDirName>/` folder, so the
+ * path is `<kbDirName>/mcp-description.md`, the same shape `SkillService` and
+ * the archive route use.
+ */
+export async function readAgentPreamble(
+  workspace: PreambleWorkspace,
+  kbDirName: string,
+  disk: IFsProbe,
+): Promise<string | null> {
+  await workspace.getOrCreateForBranch(DEFAULT_BRANCH);
+  const wsDir = await workspace.getWorkspacePath(workspaceIdForBranch(DEFAULT_BRANCH));
+  const abs = path.join(wsDir, kbDirName, PREAMBLE_FILE);
+
+  const found = await disk.lstatOrNull(abs);
+  if (found === null) return null;
+  if (!found.isFile()) throw notRegular(found.isSymbolicLink() ? 'symlink' : found.isDirectory() ? 'directory' : 'special file');
+
+  const [realWorkspace, realFile] = await Promise.all([
+    fs.realpath(wsDir),
+    fs.realpath(abs).catch((err: unknown) => {
+      if (isAbsence(err)) return null; // deleted since the lstat: an absence, not a failure
+      throw err;
+    }),
+  ]);
+  if (realFile === null) return null;
+  if (realFile !== path.join(realWorkspace, kbDirName, PREAMBLE_FILE)) throw notRegular('path through a symlink');
+
+  const handle = await fs
+    .open(abs, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0))
+    .catch((err: NodeJS.ErrnoException) => {
+      if (isAbsence(err)) return null; // deleted since the lstat: an absence, not a failure
+      if (err.code === 'ELOOP') throw notRegular('symlink'); // O_NOFOLLOW's spelling of "the final component is a link"
+      throw err;
+    });
+  if (handle === null) return null;
+  try {
+    if (!(await handle.stat()).isFile()) throw notRegular('special file');
+    return await handle.readFile('utf8');
+  } finally {
+    await handle.close();
+  }
+}
+
+function notRegular(kind: string): Error {
+  return new Error(
+    `${PREAMBLE_FILE} on branch "${DEFAULT_BRANCH}" is a ${kind}, not a regular file at its own place; ` +
+      'refusing to read it. Replace it with a plain markdown file in the repository folder.',
+  );
+}

package/src/modules/auth/__tests__/account-erasure.approval-gate.test.ts

@@ -0,0 +1,209 @@
+import { describe, it, expect } from 'vitest';
+import type { SQL } from 'drizzle-orm';
+import { PgDialect } from 'drizzle-orm/pg-core';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { AccountErasureService, type IErasureParticipant } from '../account-erasure.service.js';
+import type { Database } from '../../database/connection.js';
+import { ReviewWorkflowService } from '../../workflow/review-workflow/review-workflow.service.js';
+
+/**
+ * Erasing an account rewrites the person's name and address out of every
+ * approval they ever made. One other writer COPIES those rows — a change
+ * request that brings itself up to date re-pins the approvals its merge did
+ * not disturb onto the new head — so a copy that read the row a moment before
+ * the rewrite would insert the real address back afterwards, onto a row
+ * created after the last trace of them was supposed to be gone.
+ *
+ * What stops it is the lock both sides take: shared per request on the copy's
+ * side, exclusive on every request here. This pins that the erasure takes it,
+ * that it takes it BEFORE the statement it has to cover, and that it keeps
+ * holding it (a transaction-scoped lock) through the rest of the erasure.
+ */
+
+/** The table a statement names, as far as this stub needs to know. */
+function tableOf(target: unknown): string {
+  const t = target as Record<symbol | string, unknown>;
+  for (const sym of Object.getOwnPropertySymbols(t)) {
+    const name = String(t[sym]);
+    if (name && name !== 'undefined' && !name.startsWith('[object')) return name;
+  }
+  return 'unknown';
+}
+
+/**
+ * A `where` clause as the SQL it renders to.
+ *
+ * The sweeps' guard is a `notExists` over `users`, and it is the whole reason
+ * they are safe to run at all: without it they would anonymize the approvals
+ * and change requests of whoever signed in again at that address since the
+ * commit. A stub that ignored its condition would pass just as happily with
+ * the guard deleted — so the marker below is recorded only for a clause whose
+ * SQL actually names `users`, and the assertions are on that.
+ */
+function whereSql(clause: unknown): string {
+  return new PgDialect().sqlToQuery(clause as SQL).sql;
+}
+
+function statementText(statement: { queryChunks?: unknown[] }): string {
+  return (statement.queryChunks ?? [])
+    .flatMap((c) => (c as { value?: unknown }).value ?? [])
+    .filter((v): v is string => typeof v === 'string')
+    .join(' ');
+}
+
+function harness(opts: { participants?: IErasureParticipant[] } = {}) {
+  /** Everything the erasure did, in order, as `<verb>:<table>` / lock labels. */
+  const order: string[] = [];
+  const locked: unknown[][] = [];
+  /** The lock statements as written, so the FUNCTION is pinned, not just its keys. */
+  const lockSql: string[] = [];
+  const done = Promise.resolve([]);
+  const tx = {
+    execute: async (statement: { queryChunks?: unknown[] }) => {
+      const text = statementText(statement);
+      if (text.includes('lock_timeout')) {
+        order.push('timeout');
+        return { rows: [] };
+      }
+      order.push(text.includes('_shared') ? 'gate:shared' : 'gate:exclusive');
+      lockSql.push(text);
+      locked.push((statement.queryChunks ?? []).filter((c) => typeof c === 'number'));
+      return { rows: [] };
+    },
+    delete: (table: unknown) => ({
+      where: () => {
+        order.push(`delete:${tableOf(table)}`);
+        return done;
+      },
+    }),
+    update: (table: unknown) => ({
+      set: () => ({
+        where: () => {
+          order.push(`update:${tableOf(table)}`);
+          return done;
+        },
+      }),
+    }),
+  };
+  // A client-less drizzle instance, purely to BUILD queries. Two callers share
+  // this `select`: the read that finds the user, which awaits `.limit(1)`, and
+  // the sweeps' `notExists` subquery, which is handed to drizzle as a query and
+  // has to render as one — a hand-rolled stand-in renders as nothing, and the
+  // guard these tests are about would be invisible.
+  const builder = drizzle({} as never);
+  const db = {
+    select: (fields?: unknown) => ({
+      from: (table: unknown) => ({
+        where: (condition: unknown) =>
+          Object.assign(
+            builder
+              .select(fields as never)
+              .from(table as never)
+              .where(condition as never),
+            { limit: async () => [{ id: 'u1', email: 'Bob@Bevel.software', name: 'Bob' }] },
+          ),
+      }),
+    }),
+    // Outside the transaction: the second passes, once it has committed. The
+    // marker is recorded ONLY for a clause guarded on `users` — a sweep that
+    // lost that guard is a sweep that rewrites a new account's rows, so it must
+    // not be able to satisfy these tests.
+    update: (table: unknown) => ({
+      set: () => ({
+        where: async (clause: unknown) => {
+          const guarded = /not exists .*"users"/s.test(whereSql(clause));
+          order.push(`${guarded ? 'after-commit' : 'unguarded'}:${tableOf(table)}`);
+        },
+      }),
+    }),
+    transaction: async <T,>(fn: (t: typeof tx) => Promise<T>) => fn(tx),
+  } as unknown as Database;
+  return {
+    // The REAL review workflow, so what is pinned below is the contract as
+    // wired: erasure asks it to rewrite the approvals inside the erasure's
+    // transaction, and it is the workflow that takes the lock. Its other
+    // collaborators are never reached by `eraseApprover`.
+    svc: new AccountErasureService(
+      db,
+      new ReviewWorkflowService(db, {} as never, {} as never, {} as never),
+      opts.participants ?? [],
+    ),
+    order,
+    locked,
+    lockSql,
+  };
+}
+
+describe('AccountErasureService: approvals are rewritten under the approval lock', () => {
+  it('takes the every-request lock exclusively, right before it anonymizes them', async () => {
+    const h = harness();
+    await expect(h.svc.eraseUser('u1')).resolves.toBe(true);
+
+    const gate = h.order.indexOf('gate:exclusive');
+    const approvals = h.order.indexOf('update:pr_file_approvals');
+    expect(gate).toBeGreaterThan(-1);
+    expect(approvals).toBeGreaterThan(-1);
+    // Before the rewrite — a lock taken after it would leave the very window
+    // it exists to close wide open.
+    expect(gate).toBeLessThan(approvals);
+    // And bounded, so a wedged writer fails the erasure loudly (its
+    // transaction is atomic, so nothing is half-erased) instead of hanging.
+    expect(h.order[gate - 1]).toBe('timeout');
+    // Exclusive on the every-request key (0) of the approval lock's class —
+    // the shared form is the per-request writers', not this.
+    expect(h.locked).toEqual([[4207, 0]]);
+    expect(h.order).not.toContain('gate:shared');
+    // And TRANSACTION-scoped. The session-scoped `pg_advisory_lock` would
+    // satisfy every assertion above and then keep an exclusive lock on a
+    // pooled connection after this transaction ends — held by whatever request
+    // borrows that connection next, released by nobody.
+    expect(h.lockSql).toHaveLength(1);
+    expect(h.lockSql[0]).toContain('pg_advisory_xact_lock');
+    expect(h.lockSql[0]).not.toMatch(/pg_advisory_lock\b/);
+    // Still inside the same transaction as the user row's deletion, which is
+    // what keeps the lock held for the whole rewrite.
+    expect(h.order.indexOf('delete:users')).toBeGreaterThan(gate);
+  });
+
+  it('sweeps the approvals once more after the commit, for anything the lock did not order', async () => {
+    // The lock covers every writer that takes it, and `approveFile` re-reads
+    // the account under it before writing. This is the belt to those braces:
+    // one idempotent statement so the guarantee does not rest on every future
+    // writer of this table remembering the lock.
+    const h = harness();
+    await h.svc.eraseUser('u1');
+
+    const committed = h.order.indexOf('delete:users');
+    const sweep = h.order.indexOf('after-commit:pr_file_approvals');
+    expect(sweep).toBeGreaterThan(committed);
+    // The change requests get the same treatment, and did before this.
+    expect(h.order).toContain('after-commit:change_requests');
+    // Both guarded on `users`: the marker is only recorded for a clause that
+    // names it, so a sweep that dropped the `notExists` lands here instead.
+    expect(h.order.filter((step) => step.startsWith('unguarded:'))).toEqual([]);
+  });
+
+  it('sweeps before the post-commit callbacks, so one that rejects cannot skip them', async () => {
+    // The erasure is committed by now and `eraseUser` cannot be retried into
+    // it, so a pass sequenced behind a failing callback is one that may never
+    // run at all. Nothing in the sweeps depends on a callback having succeeded.
+    const h = harness({
+      participants: [
+        {
+          inTransaction: async () => async () => {
+            h.order.push('callback');
+            throw new Error('the external store is down');
+          },
+        },
+      ],
+    });
+
+    await expect(h.svc.eraseUser('u1')).rejects.toThrow(/external store/);
+
+    expect(h.order).toContain('after-commit:pr_file_approvals');
+    expect(h.order).toContain('after-commit:change_requests');
+    expect(h.order.indexOf('after-commit:pr_file_approvals')).toBeLessThan(
+      h.order.indexOf('callback'),
+    );
+  });
+});