@bevel-software/platform-core-backend 0.23.0 → 0.25.0

package/src/modules/agent-instructions/shared-file-rules.ts

@@ -0,0 +1,314 @@
+/**
+ * The rules that apply to MORE THAN ONE file tool, written ONCE.
+ *
+ * They used to be appended, in full, to every tool description that they
+ * covered: the content rule rode on all twelve file tools, the agent-guide
+ * reminder on all of them plus the shell, the write-mode and escape-sequence
+ * paragraphs on two or three apiece. A description then ran to two or three
+ * thousand characters, most of it text the agent had already read on the tool
+ * above — and clients cut long descriptions from the END, which is where the
+ * text specific to the tool sits. Agents saw `file_stat`, `read_file`,
+ * `write_file` and `write_files` arrive ending in "[truncated]".
+ *
+ * So the shared rules are stated in TWO places and in neither description:
+ *
+ *  - the MCP `instructions` of the initialize handshake (see `compose.ts`),
+ *    which Claude Code, Claude Desktop and Cursor put in the system prompt;
+ *  - the platform-managed agent guide at the repository root (`AGENTS.md` by
+ *    default), rendered from `{{sharedFileRules}}` in the template — claude.ai
+ *    on the web, the Agent SDK and Cline drop `instructions`, and a guide the
+ *    agent is told to read before its first action is always available.
+ *
+ * Both places get the SAME string, from {@link sharedFileRulesSection} — not
+ * two hand-mirrored copies. A rule written twice is a rule that drifts, and a
+ * drifted rule is worse than a repeated one, because the agent cannot tell
+ * which copy is current. Each description ends instead with
+ * {@link sharedRulesPointer}, one sentence naming the section and the file.
+ *
+ * Pure text, a function of the layout only: the guide's file name is a
+ * deployment setting, so nothing here may snapshot `AGENTS.md`.
+ */
+
+import {
+  DEFAULT_KB_LAYOUT,
+  agentsFileOf,
+  LEGACY_AGENTS_FILE,
+  platformFilesByDepth,
+  type KbLayout,
+} from '@bevel-software/platform-shared';
+import { CHAIN_FAILURES_RULE, CHAIN_LARGE_RESULTS_RULE } from '@bevel-software/platform-mcp-core';
+
+/** The heading the rules live under, in both places and in the pointer sentence. */
+export const SHARED_RULES_SECTION = 'Working with files';
+
+/**
+ * The guide's name on a knowledge base seeded before it was renamed to
+ * {@link LEGACY_AGENTS_FILE}. Named in the conventions rule because the seeder
+ * never deletes a file it did not expect, so such a knowledge base still
+ * carries one.
+ */
+const PRE_RENAME_AGENTS_FILE = 'CLAUDE.md';
+
+/**
+ * The ceiling on the whole section. Pinned by a test: the section lands in
+ * every conversation through two channels, and a rule moved here to shorten a
+ * description has only moved the cost if the section itself grows without
+ * limit. Measured against {@link sharedFileRulesSection} under the default
+ * layout.
+ *
+ * 7,000 since two rules moved in from descriptions they took past their cap:
+ * the chain's own (what a failed chain and an oversized result answer), true
+ * of every call rather than of how to write one, and why large, escape-heavy
+ * and binary content goes by upload, which three write tools each said in
+ * full.
+ */
+export const SHARED_FILE_RULES_CAP = 7_000;
+
+/** One shared rule: how the guide heads it, and the rule itself. */
+export interface SharedFileRule {
+  /** Stable id, so a test can name the rule that went missing. */
+  id: string;
+  /** The heading this rule gets in the section. */
+  heading: string;
+  /** The rule, as both places state it. Markdown paragraphs, blank-line separated. */
+  body: string;
+}
+
+/**
+ * Every shared rule, in reading order: what to read first, what the content
+ * is, what a write may do, then the two protocols that guard a destructive
+ * call.
+ *
+ * The bodies are the sentences the descriptions used to carry, moved rather
+ * than rewritten wherever the wording still reads outside its old tool — the
+ * ones that said "this tool" or "this call" name the tools instead.
+ */
+export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
+  const agentsFile = agentsFileOf(layout);
+  return [
+    {
+      id: 'agent-guide',
+      heading: "This knowledge base's own conventions",
+      body: conventionsRule(agentsFile),
+    },
+    {
+      id: 'content-kinds',
+      heading: 'Text, documents, images and other binaries',
+      body:
+        'read_file returns text for text files and extracted text for documents ' +
+        '(.docx/.pptx/.xlsx/.odt/.odp/.ods/.pdf, .eml/.msg); write_file, write_files and edit_file accept TEXT only — ' +
+        'they refuse documents, images, archives and other binary files (legacy .doc/.ppt/.xls included) with kind ' +
+        "`binary_not_writable`, naming the file's kind and the tool to use instead; copy_file, move_file and delete_file " +
+        'act on bytes of any kind and unzip extracts the entries of a `.zip`; new binary content arrives by upload ' +
+        '(see below). file_stat reports `contentMode` ' +
+        '(`text` | `document` | `binary`) so you can decide before acting.\n\n' +
+        'Office and OpenDocument files (.docx/.pptx/.xlsx, .odt/.odp/.ods) and PDFs read as EXTRACTED text under an ' +
+        'honest `[extracted text of …]` header, with `[slide N]`/`[sheet: Name]`/`[page N]` markers — the extraction ' +
+        'is READ-ONLY (layout/images omitted; such files cannot be edited as text, only replaced by uploading a new ' +
+        'version). Email files (.eml/.msg) read the same way: a `[from]`/`[to]`/`[subject]`/`[date]` header block, the ' +
+        'body (plain-text part preferred; an HTML-only body is stripped to text), and an `[attachments]` name list — ' +
+        'attachments are listed, never extracted. grep searches inside all of those, through the same extractions.\n\n' +
+        'Images (.png/.jpg/.jpeg/.gif/.webp) read as the IMAGE ITSELF, as native MCP image content with a one-line ' +
+        'text note naming the file, so you can look at the picture — up to 3.5 MB of raw image data; a larger image ' +
+        'gets an honest refusal asking for a locally downscaled copy or a smaller export (`.svg` is text and reads as ' +
+        'text). Images come back only on a DIRECT read_file: inside `call_tool_chain` an image read yields an ' +
+        '`{ image_omitted, note }` stub instead, so read an image outside a chain when you mean to look at it. Any other ' +
+        'binary file reads as a one-line description rather than raw bytes.',
+    },
+    {
+      id: 'write-mode',
+      heading: 'What a write may do at a path',
+      body:
+        'On write_file and write_files, `mode` decides what may happen at a path and DEFAULTS TO `create`: `create` ' +
+        'writes a new file and refuses a path that already exists (`exists`, with the path — pass `mode: overwrite` to ' +
+        'replace it), `overwrite` replaces what is there (creating it if there is nothing), `update` replaces an ' +
+        'existing file and refuses a path that does not exist (`missing`). A refused path is left exactly as it was.',
+    },
+    {
+      id: 'images-in-pages',
+      heading: 'Where the images a page uses go',
+      body:
+        'Keep them in an `assets/` folder next to the page that uses them and link them with a relative path, e.g. ' +
+        '`![Approval screen](./assets/approval-screen.png)`; the page renders them inline.',
+    },
+    {
+      id: 'escape-sequences',
+      heading: 'Escape sequences in content you send',
+      body:
+        'On write_file, write_files and edit_file, which take content as a JSON string: some clients decode escape ' +
+        'sequences in arguments before sending, so content meant to CONTAIN an escape rather than what it stands for ' +
+        '(the six characters backslash, `u`, `0`, `0`, `4`, `1`, say, rather than the letter `A`) can reach the tool ' +
+        'already decoded — what arrives is stored byte for byte, so when that distinction matters, verify what landed ' +
+        '(`read_file`, or a hash) and send such content by upload (see below), which lands it unchanged.',
+    },
+    {
+      // The reason the upload route exists, said once. Each of the three tools
+      // that take content as a JSON string names the route in one sentence of
+      // its own; WHY a file should go that way, and how, is here.
+      id: 'upload-route',
+      heading: 'Large, escape-heavy and binary content goes by upload',
+      body:
+        'write_file, write_files and edit_file take content as a JSON string you have to type out in full, so a long ' +
+        'file is cut off mid-answer, a file full of backslashes or `\\u` escapes fails to parse as a parameter, and ' +
+        'an image, a PDF or a zip cannot be sent at all. For any of those: call `request_file_upload`, POST the file — ' +
+        'or one zip holding many files — to the address it answers with any HTTP client ' +
+        '(`curl -X POST --data-binary @<file> "<uploadUrl>?filename=<name>"`), then `apply_file_upload` to land it on ' +
+        'a branch in one commit. The bytes never pass through the conversation, so nothing is cut or mangled on the ' +
+        'way. A person can also use Upload in the app.',
+    },
+    {
+      id: 'dry-run-confirm',
+      heading: 'Dry-run before a move, a copy or a folder delete',
+      body:
+        'move_file, copy_file and delete_folder take `dryRun: true`: it changes nothing and answers the impact — ' +
+        'what the call would touch, `allowed`, and `reason` when it may not run. A non-empty folder is deleted, and a ' +
+        'move that changes your access runs, only with `confirm: true`; without it the call changes nothing and ' +
+        'returns the same impact with `confirmationRequired: true`. Do NOT set `confirm: true` on your first call — ' +
+        'dry-run, check the impact, then confirm. delete_file takes neither: it removes the one file you named, so ' +
+        'check it first with file_stat (`deletable`) if you are unsure.',
+    },
+    {
+      id: 'managed-items',
+      heading: 'What these tools never move or delete',
+      body:
+        `A platform file (${platformFileList(layout)}) is refused with ` +
+        '"<name> is a platform file and stays in its folder." — a folder that moves ' +
+        'takes its own platform files along, still in their folder, and a folder that is deleted takes them with it in ' +
+        'the same one change, so its files are never left ungoverned part-way. A platform folder (the repository root ' +
+        `or a reserved root folder such as \`${layout.knowledgeBaseDir}/\`) and git metadata are refused, and so is creating a ` +
+        'platform file or folder at a destination (renaming a note to `access.md` is refused). A path that is, or goes ' +
+        'through, a symbolic link is refused: links are never followed or removed. On a protected branch you must be ' +
+        'able to write everything the call touches — for a folder, every file under it, at its old and its new path. ' +
+        'file_stat reports `managed`, `movable` and `deletable` so you can tell before the call.',
+    },
+    {
+      id: 'refused-for-permissions',
+      heading: 'When a write is refused for permissions',
+      body:
+        'A refusal is not necessarily the end of the road: the `write-denied` error says whether you may propose the ' +
+        'change instead (create a branch from this one, repeat the call on it, then `open_change_request` into this ' +
+        'branch) and lists those steps.',
+    },
+    {
+      // What a chain DOES, as opposed to how to write one — which stays in
+      // `call_tool_chain`'s own description. The sentences are `mcp-core`'s,
+      // the same ones a surface with no shared rules puts in the description
+      // itself, so the rule reads the same wherever an agent finds it. What a
+      // chained read does to an image is in the content rule above.
+      id: 'tool-chain',
+      heading: 'When several calls run as one chain',
+      body: `On call_tool_chain: ${CHAIN_FAILURES_RULE}\n\n${CHAIN_LARGE_RESULTS_RULE}`,
+    },
+  ];
+}
+
+/**
+ * The platform files as the rules list them — from the one function that knows
+ * which they are, so the list cannot drift from what actually refuses a move,
+ * and the guide appears under this deployment's name for it.
+ *
+ * WITH THE DEPTH each name counts at, because the name alone is half the rule:
+ * `access.md` governs the folder it sits in and `.bevelignore` layers, so both
+ * are platform files wherever they are; `roles.yaml` and the guide are read
+ * from the repository root only, so a nested copy of either is ordinary
+ * content that moves and deletes like any page. An agent told only the names
+ * refuses a rename it may make, and trusts a nested `access.md` it may not.
+ */
+function platformFileList(layout: KbLayout): string {
+  const { anyDepth, rootOnly } = platformFilesByDepth(layout);
+  const quoted = (names: readonly string[]): string => names.map((name) => `\`${name}\``).join(' or ');
+  return `${quoted(anyDepth)} in any folder, ${quoted(rootOnly)} at the repository root`;
+}
+
+/**
+ * The conventions reminder — which file holds the author's own rules for this
+ * knowledge base, and to read it first.
+ *
+ * `CLAUDE.md` is named as a fallback because knowledge bases seeded before the
+ * rename still carry one. WHEN THE GUIDE HAS BEEN RENAMED the sentence names
+ * two files, ours first: the second is the organisation's OWN `AGENTS.md`,
+ * which on such a deployment is ordinary content the platform never touches —
+ * and which no harness reads for a remote agent, because a remote agent has no
+ * checkout. Under the default name the wording collapses to the one file it
+ * has always named.
+ */
+function conventionsRule(agentsFile: string): string {
+  if (agentsFile === LEGACY_AGENTS_FILE) {
+    return (
+      `Before your first read or change in a workspace, read \`${LEGACY_AGENTS_FILE}\` at the KB root — or ` +
+      `\`${PRE_RENAME_AGENTS_FILE}\` on a knowledge base seeded before it was renamed — if either exists: it holds ` +
+      "the author's conventions for this knowledge base, and you should follow them."
+    );
+  }
+  return (
+    `Before your first read or change in a workspace, read \`${agentsFile}\` at the KB root, then ` +
+    `\`${LEGACY_AGENTS_FILE}\` if it also exists (the organisation's own conventions) — or ` +
+    `\`${PRE_RENAME_AGENTS_FILE}\` on a knowledge base seeded before it was renamed: together they hold the ` +
+    'conventions for this knowledge base, and you should follow them.'
+  );
+}
+
+/**
+ * The shared rules as ONE markdown section — the string both channels carry,
+ * byte for byte. A `##` section so it drops into the managed guide at that
+ * level and still reads as a block in the instructions blob.
+ */
+export function sharedFileRulesSection(layout: KbLayout): string {
+  const body = sharedFileRules(layout)
+    .map((rule) => `### ${rule.heading}\n\n${rule.body}`)
+    .join('\n\n');
+  return `## ${SHARED_RULES_SECTION}\n\n${body}`;
+}
+
+/**
+ * The longest guide file name the pointer sentence spells out. Beyond this it
+ * names the guide by its ROLE instead (see {@link sharedRulesPointer}).
+ *
+ * There has to be a bound somewhere, because the pointer rides on every file
+ * tool and a file name is not a fixed cost: `validateFilename` allows a name
+ * of up to 255 bytes, so an unbounded pointer could reach 318 characters and
+ * push `file_stat` to 1,428 — over the description cap, recreating on a
+ * renamed deployment exactly the truncation this module exists to prevent, and
+ * invisibly, because every measurement is taken under the default layout.
+ *
+ * 40 is well past any name a deployment plausibly picks
+ * (`ENGINEERING-AGENT-CONVENTIONS.md` is 32) and the fallback below is only
+ * reachable past it.
+ */
+export const POINTER_GUIDE_NAME_BUDGET = 40;
+
+/**
+ * The one sentence a tool description ends with, in place of the paragraphs it
+ * used to carry. Short on purpose: it costs every description the same ~100
+ * characters at worst, and its whole job is to name the section and the file
+ * to read.
+ *
+ * BOUNDED BY CONSTRUCTION, which is what lets the description cap mean
+ * something on a deployment that renamed its guide: a name within
+ * {@link POINTER_GUIDE_NAME_BUDGET} is spelled out, and a longer one gets the
+ * generic wording. Naming the file is the better sentence and wins whenever it
+ * fits; a name past the budget is pathological, and there the choice is between
+ * a sentence that says where to look and a catalog entry the client cuts. The
+ * guide's own name is still in the section's first rule either way.
+ *
+ * An absent layout means the default one, as it does in
+ * `composeAgentInstructions`: a caller reading the layout from configuration
+ * gets `undefined` when none is set, and the pointer must still name a file.
+ */
+export function sharedRulesPointer(layout: KbLayout = DEFAULT_KB_LAYOUT): string {
+  const agentsFile = agentsFileOf(layout);
+  const where =
+    agentsFile.length <= POINTER_GUIDE_NAME_BUDGET ? agentsFile : 'the agent guide at the KB root';
+  return ` Shared rules for all file tools: see "${SHARED_RULES_SECTION}" in ${where}.`;
+}
+
+/**
+ * The most the pointer can ever cost a description, over every layout. What the
+ * description cap is measured against, the way the tool prefix is measured at
+ * ITS cap rather than at whatever the current admin wrote: a description that
+ * only fits beside the short default guide name does not really fit.
+ */
+export const SHARED_RULES_POINTER_MAX = Math.max(
+  sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: `${'x'.repeat(POINTER_GUIDE_NAME_BUDGET - 3)}.md` }).length,
+  sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: `${'x'.repeat(POINTER_GUIDE_NAME_BUDGET + 10)}.md` }).length,
+);

package/src/modules/audit/agent-audit.service.ts

@@ -1,4 +1,4 @@
-import { and, asc, count, desc, eq, isNull, lt, or, type SQL } from 'drizzle-orm';
+import { and, count, desc, eq, isNull, lt, or, type SQL } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
 import type { Database } from '../database/connection.js';
 import { agentConnections, agentEvents, oauthTokens, users } from '../database/schema.js';
@@ -101,7 +101,9 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
         .from(agentConnections)
         .innerJoin(users, eq(agentConnections.userId, users.id))
         .where(mine === null ? undefined : eq(agentConnections.userId, mine))
-        .orderBy(asc(users.email), desc(agentConnections.connectedAt)),
+        // Not by email: that column is randomized ciphertext, and ORDER BY
+        // on it is noise. The sort below orders by email in-process.
+        .orderBy(desc(agentConnections.connectedAt)),
       this.db
         .select({ keyId: agentEvents.keyId, connectionId: agentEvents.connectionId, n: count() })
         .from(agentEvents)

package/src/modules/auth/__tests__/account-deactivation.test.ts

@@ -240,7 +240,8 @@ describe('AuthService.createAccount without a password', () => {
     const { db, captured } = makeFakeDb([[{ ...ROW, passwordHash: null }]]);
     const user = await new AuthService(db, makeConfig()).createAccount('Alice@Example.com', '');
     expect(user.email).toBe('alice@example.com');
-    expect(captured.values[0]).toEqual({ email: 'alice@example.com', name: 'alice' });
+    // The index column is written with the address; the handle indexes it.
+    expect(captured.values[0]).toEqual({ email: 'alice@example.com', emailBidx: 'alice@example.com', name: 'alice' });
   });
 
   it('asks the admission port, as any new account does', async () => {

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

@@ -70,6 +70,9 @@ function harness(opts: { participants?: IErasureParticipant[] } = {}) {
       locked.push((statement.queryChunks ?? []).filter((c) => typeof c === 'number'));
       return { rows: [] };
     },
+    // The one read the transaction makes: the refusals recorded before the
+    // encryption release, which it matches by name. None here.
+    select: () => ({ from: () => ({ where: async () => [] }) }),
     delete: (table: unknown) => ({
       where: () => {
         order.push(`delete:${tableOf(table)}`);
@@ -176,8 +179,9 @@ describe('AccountErasureService: approvals are rewritten under the approval lock
     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');
+    // The change requests get the same treatment, twice: once for the
+    // authorship, once for the refusal note of an apply that was in flight.
+    expect(h.order.filter((step) => step === 'after-commit:change_requests')).toHaveLength(2);
     // 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([]);

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

@@ -93,9 +93,11 @@ describe('account routes — admin gate', () => {
       { id: 'u2', email: 'b@example.com', name: 'B', passwordHash, createdAt: new Date() },
     ];
     // A real AuthService over a stub db — the route's body is what the
-    // service produces from full `users` rows, hash column included.
+    // service produces from full `users` rows, hash column included. The
+    // listing is sorted in-process (the email column is ciphertext in the
+    // database), so the read is a bare `select().from()`.
     const db = {
-      select: () => ({ from: () => ({ orderBy: async () => rows }) }),
+      select: () => ({ from: async () => rows }),
     } as unknown as Database;
     const realAuth = new AuthService(db, {
       jwtSecret: 'test-jwt-secret',
@@ -118,9 +120,10 @@ describe('account routes — admin gate', () => {
     const body = JSON.parse(text) as {
       accounts: Array<{ email: string; hasPassword: boolean; isEnvAdmin: boolean }>;
     };
+    // Sorted by email in-process, since the column is ciphertext in the database.
     expect(body.accounts.map((a) => [a.email, a.hasPassword, a.isEnvAdmin])).toEqual([
-      ['root@example.com', false, true],
       ['b@example.com', true, false],
+      ['root@example.com', false, true],
     ]);
     expect(text).not.toContain('scrypt:');
     expect(text).not.toContain('passwordHash');

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

@@ -521,9 +521,11 @@ describe('AuthService.listAccounts', () => {
     const config = makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret' });
 
     const withHash = await new AuthService(makeFakeDb([rows]).db, config).listAccounts();
+    // Sorted by email in-process: the email column is ciphertext in the
+    // database, so the listing orders itself after decrypting.
     expect(withHash.map((a) => [a.email, a.hasPassword, a.isEnvAdmin])).toEqual([
-      ['root@example.com', true, true],
       ['bob@example.com', true, false],
+      ['root@example.com', true, true],
       ['sso@example.com', false, false],
     ]);
 

package/src/modules/auth/account-erasure.service.ts

@@ -3,6 +3,7 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('account-erasure');
 import { and, eq, notExists } from 'drizzle-orm';
+import { isEncryptedBlob } from '../../shared/column-crypto.js';
 import type { Database } from '../database/connection.js';
 import type { IReviewWorkflowService } from '../workflow/review-workflow/review-workflow.interface.js';
 import {
@@ -123,17 +124,34 @@ export class AccountErasureService implements IAccountErasureService {
   ) {}
 
   async listUsers(): Promise<AdminUserView[]> {
+    // Sorted in-process: `email` is ciphertext in the database, so ORDER BY
+    // would sort by IV noise. One row per team member.
     const rows = await this.db
       .select({ id: users.id, email: users.email, name: users.name, createdAt: users.createdAt })
-      .from(users)
-      .orderBy(users.email);
-    return rows.map((r) => ({ ...r, createdAt: r.createdAt.getTime() }));
+      .from(users);
+    return rows
+      .map((r) => ({ ...r, createdAt: r.createdAt.getTime() }))
+      .sort((a, b) => a.email.localeCompare(b.email));
   }
 
   async eraseUser(userId: string, opts: { erasureId?: string } = {}): Promise<boolean> {
     const [user] = await this.db.select().from(users).where(eq(users.id, userId)).limit(1);
     if (!user) return false;
 
+    // Fail CLOSED on an undecryptable email. The encrypted column's read
+    // fallback returns the raw ciphertext when the configured key cannot open
+    // it (a rotated or wrong SECRETS_ENC_KEY); a blind index of that blob
+    // would match zero audit rows while the user delete still committed — an
+    // erasure that silently left the personal data behind. Nothing is
+    // deleted until the key is fixed.
+    if (isEncryptedBlob(user.email)) {
+      throw new Error(
+        `account-erasure: cannot decrypt the stored email for user id=${userId} with the ` +
+          'configured SECRETS_ENC_KEY — refusing to erase, because the email-keyed audit rows ' +
+          'could not be anonymised. Restore the correct key, then retry.',
+      );
+    }
+
     const target: ErasureTarget = {
       userId,
       email: user.email.toLowerCase(),
@@ -149,6 +167,14 @@ export class AccountErasureService implements IAccountErasureService {
       if (p.before) await p.before(target);
     }
 
+    // Every email-keyed row below is matched through its blind index — the
+    // email columns are randomized ciphertext — and the index is rewritten to
+    // the placeholder's too, so no value keyed to the erased address survives.
+    // An index column is compared and written with the address it is the
+    // index of; the handle the statement runs on makes the index.
+    const emailBidx = target.email;
+    const erasedBidx = target.erasedEmail;
+
     const postCommit: Array<() => Promise<void>> = [];
     await this.db.transaction(async (tx) => {
       // Token-shaped rows (all hashed, but they key to the user). Dependents
@@ -180,7 +206,7 @@ export class AccountErasureService implements IAccountErasureService {
       // writing anything back — so no row is resurrected here either.
       await tx
         .delete(pluginJoinRequests)
-        .where(eq(pluginJoinRequests.requesterEmail, target.email));
+        .where(eq(pluginJoinRequests.requesterEmailBidx, emailBidx));
 
       // Audit rows: anonymize in place (no user FK on these; they key by email).
       //
@@ -197,23 +223,34 @@ export class AccountErasureService implements IAccountErasureService {
       });
       await tx
         .update(prMergeLog)
-        .set({ triggeredByEmail: target.erasedEmail, triggeredByName: target.erasedName })
-        .where(eq(prMergeLog.triggeredByEmail, target.email));
+        .set({ triggeredByEmail: target.erasedEmail, triggeredByEmailBidx: erasedBidx, triggeredByName: target.erasedName })
+        .where(eq(prMergeLog.triggeredByEmailBidx, emailBidx));
       await tx
         .update(prComments)
-        .set({ authorEmail: target.erasedEmail, authorName: target.erasedName })
-        .where(eq(prComments.authorEmail, target.email));
+        .set({ authorEmail: target.erasedEmail, authorEmailBidx: erasedBidx, authorName: target.erasedName })
+        .where(eq(prComments.authorEmailBidx, emailBidx));
       await tx
         .update(changeRequests)
-        .set({ authorEmail: target.erasedEmail, authorName: target.erasedName })
-        .where(eq(changeRequests.authorEmail, target.email));
+        .set({ authorEmail: target.erasedEmail, authorEmailBidx: erasedBidx, authorName: target.erasedName })
+        .where(eq(changeRequests.authorEmailBidx, emailBidx));
+      // The refusal a still-open request shows ("<name> could not apply
+      // this"), on requests of any author — found by the index of the address
+      // it was recorded with, like every other row. One recorded before the
+      // encryption release kept no address, and has no name to find either:
+      // the first start on this release took it off (`migrate.ts`,
+      // `clearUnindexedRefusalNames`), because matching such a row by display
+      // name missed a person who had been renamed and hit their namesake.
+      await tx
+        .update(changeRequests)
+        .set({ applyFailedByName: target.erasedName, applyFailedByEmailBidx: erasedBidx })
+        .where(eq(changeRequests.applyFailedByEmailBidx, emailBidx));
       // Queued-but-uncommitted saves: the eventual git commit is authored with
       // the placeholder instead of the erased identity. The file content still
       // lands — erasing an account must not lose other people's KB state.
       await tx
         .update(pendingCommits)
-        .set({ authorEmail: target.erasedEmail, authorName: target.erasedName })
-        .where(eq(pendingCommits.authorEmail, target.email));
+        .set({ authorEmail: target.erasedEmail, authorEmailBidx: erasedBidx, authorName: target.erasedName })
+        .where(eq(pendingCommits.authorEmailBidx, emailBidx));
 
       // Module-owned rows, before the users delete so FKs onto users are
       // still satisfiable — and so a participant that MISSES rows makes the
@@ -251,11 +288,11 @@ export class AccountErasureService implements IAccountErasureService {
     // approvals they make are their own.
     await this.db
       .update(prFileApprovals)
-      .set({ approverEmail: target.erasedEmail, approverName: target.erasedName })
+      .set({ approverEmail: target.erasedEmail, approverEmailBidx: erasedBidx, approverName: target.erasedName })
       .where(
         and(
-          eq(prFileApprovals.approverEmail, target.email),
-          notExists(this.db.select({ id: users.id }).from(users).where(eq(users.email, target.email))),
+          eq(prFileApprovals.approverEmailBidx, emailBidx),
+          notExists(this.db.select({ id: users.id }).from(users).where(eq(users.emailBidx, emailBidx))),
         ),
       );
 
@@ -272,11 +309,25 @@ export class AccountErasureService implements IAccountErasureService {
     // person, and their requests are their own.
     await this.db
       .update(changeRequests)
-      .set({ authorEmail: target.erasedEmail, authorName: target.erasedName })
+      .set({ authorEmail: target.erasedEmail, authorEmailBidx: erasedBidx, authorName: target.erasedName })
+      .where(
+        and(
+          eq(changeRequests.authorEmailBidx, emailBidx),
+          notExists(this.db.select({ id: users.id }).from(users).where(eq(users.emailBidx, emailBidx))),
+        ),
+      );
+
+    // And the refusal note, for the apply this person was inside when the
+    // commit landed: recording it takes no lock and names no user row, so it
+    // can write their name after the rewrite above. Same statement, same
+    // guard, same reason.
+    await this.db
+      .update(changeRequests)
+      .set({ applyFailedByName: target.erasedName, applyFailedByEmailBidx: erasedBidx })
       .where(
         and(
-          eq(changeRequests.authorEmail, target.email),
-          notExists(this.db.select({ id: users.id }).from(users).where(eq(users.email, target.email))),
+          eq(changeRequests.applyFailedByEmailBidx, emailBidx),
+          notExists(this.db.select({ id: users.id }).from(users).where(eq(users.emailBidx, emailBidx))),
         ),
       );