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

package/src/modules/workflow/__tests__/workflow.service.facade.test.ts

@@ -7,7 +7,6 @@ import { testKbContext } from '../../../__tests__/kb-context.js';
 import type {
   AuthUser,
   ChangeInput,
-  PostChangeRequestCommentInput,
 } from '@bevel-software/platform-shared';
 import type { GitService } from '../git/git.service.js';
 import type { PullRequestService } from '../git/pull-request.service.js';
@@ -239,10 +238,6 @@ function makePrs(): PullRequestService {
 
 function makeReviewWorkflow(): IReviewWorkflowService {
   return {
-    listComments: vi.fn(),
-    postComment: vi.fn(),
-    editComment: vi.fn(),
-    deleteComment: vi.fn(),
     getApprovalStates: vi.fn(),
     approveFile: vi.fn(),
     unapproveFile: vi.fn(),
@@ -572,21 +567,6 @@ describe('WorkflowService — change request delegation + cache invalidation', (
     expect(prs.listOpenPrs).toHaveBeenCalledWith({ fresh: true });
   });
 
-  it('postComment delegates AND invalidates the PR detail cache', async () => {
-    const prs = makePrs();
-    const reviewWorkflow = makeReviewWorkflow();
-    const comment = { id: 'c1' };
-    const input: PostChangeRequestCommentInput = { body: 'hi' };
-    (reviewWorkflow.postComment as ReturnType<typeof vi.fn>).mockResolvedValue(comment);
-
-    const svc = new WorkflowService(makeDb(), makeGit(), prs, reviewWorkflow, makeWorkspaceService(), makeAccessControl(), makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate());
-    const user = makeUser();
-    await expect(svc.postComment(42, user, input, 'sha1')).resolves.toBe(comment);
-    expect(reviewWorkflow.postComment).toHaveBeenCalledWith(42, user, input, 'sha1');
-    expect(prs.invalidateDetailCache).toHaveBeenCalledWith(42);
-    expect(prs.invalidateDetailCache).toHaveBeenCalledTimes(1);
-  });
-
   it('approveFile invalidates the PR detail cache exactly once', async () => {
     const prs = makePrs();
     const reviewWorkflow = makeReviewWorkflow();
@@ -602,14 +582,65 @@ describe('WorkflowService — change request delegation + cache invalidation', (
     const prs = makePrs();
     const reviewWorkflow = makeReviewWorkflow();
     (reviewWorkflow.cancelPr as ReturnType<typeof vi.fn>).mockResolvedValue({ prNumber: 9, cancelledAt: 't' });
+    // A caller holding no grant: not the author, not an admin, no files to own.
+    const access = makeAccessControl();
+    (access.canWriteAtRef as ReturnType<typeof vi.fn>).mockResolvedValue(false);
 
-    const svc = new WorkflowService(makeDb(), makeGit(), prs, reviewWorkflow, makeWorkspaceService(), makeAccessControl(), makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate());
+    const svc = new WorkflowService(makeDb(), makeGit(), prs, reviewWorkflow, makeWorkspaceService(), access, makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate());
     const user = makeUser();
     await svc.rejectChangeRequest(9, user, 'open', null, 'main', 'w1');
+    // Passed through unchanged: `cancelPr` is the one that refuses it.
     expect(reviewWorkflow.cancelPr).toHaveBeenCalledWith(9, user, 'open', null, 'main', 'w1');
     expect(prs.invalidateDetailCache).toHaveBeenCalledWith(9);
   });
 
+  // Reject and the title/description edit share ONE rule for who may decide a
+  // request (`changeRequestDecisionGrant`); these pin reject's side of it.
+  it('rejectChangeRequest lets the holder of write on every changed file close it as the author would', async () => {
+    const prs = makePrs();
+    (prs.getPrDetail as ReturnType<typeof vi.fn>).mockResolvedValue({ files: [{ path: 'a.md' }, { path: 'b.md' }] });
+    const reviewWorkflow = makeReviewWorkflow();
+    (reviewWorkflow.cancelPr as ReturnType<typeof vi.fn>).mockResolvedValue({ prNumber: 9, cancelledAt: 't' });
+    const access = makeAccessControl();
+    (access.canWriteAtRef as ReturnType<typeof vi.fn>).mockResolvedValue(false);
+    (access.canWriteBatchAtRef as ReturnType<typeof vi.fn>).mockResolvedValue(
+      new Map([['a.md', true], ['b.md', true]]),
+    );
+    const workspaceService = makeWorkspaceService();
+
+    const svc = new WorkflowService(makeDb(), makeGit(), prs, reviewWorkflow, workspaceService, access, makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate());
+    const user = makeUser();
+    await svc.rejectChangeRequest(9, user, 'open', 'someone-else', 'main', 'w1');
+    expect(workspaceService.ensureRemotesFetched).toHaveBeenCalledWith('w1', { strict: true, force: true });
+    expect(access.canWriteBatchAtRef).toHaveBeenCalledWith('w1', 'origin/main', user.email, ['a.md', 'b.md']);
+    expect(reviewWorkflow.cancelPr).toHaveBeenCalledWith(9, user, 'open', hashEmail(user.email), 'main', 'w1');
+  });
+
+  it('rejectChangeRequest refuses with a worded 409 when origin cannot be fetched, never against a stale tree', async () => {
+    const reviewWorkflow = makeReviewWorkflow();
+    const workspaceService = makeWorkspaceService();
+    (workspaceService.ensureRemotesFetched as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('offline'));
+    const access = makeAccessControl();
+
+    const svc = new WorkflowService(makeDb(), makeGit(), makePrs(), reviewWorkflow, workspaceService, access, makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate());
+    await expect(svc.rejectChangeRequest(9, makeUser(), 'open', 'someone-else', 'main', 'w1')).rejects.toMatchObject({
+      status: 409,
+      message: expect.stringContaining('origin was unreachable'),
+    });
+    expect(access.canWriteAtRef).not.toHaveBeenCalled();
+    expect(reviewWorkflow.cancelPr).not.toHaveBeenCalled();
+  });
+
+  it("rejectChangeRequest reads no grant for a request that is no longer open — cancelPr answers it", async () => {
+    const reviewWorkflow = makeReviewWorkflow();
+    (reviewWorkflow.cancelPr as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('already-applied'));
+    const workspaceService = makeWorkspaceService();
+
+    const svc = new WorkflowService(makeDb(), makeGit(), makePrs(), reviewWorkflow, workspaceService, makeAccessControl(), makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate());
+    await expect(svc.rejectChangeRequest(9, makeUser(), 'merged', null, 'main', 'w1')).rejects.toThrow('already-applied');
+    expect(workspaceService.ensureRemotesFetched).not.toHaveBeenCalled();
+  });
+
   it('mergeChangeRequest wraps the underlying merge result in a "merged" outcome', async () => {
     const prs = makePrs();
     const reviewWorkflow = makeReviewWorkflow();
@@ -1606,6 +1637,35 @@ describe('WorkflowService.openChangeRequest — when the repository host refuses
     return { svc, git, prs, values, emit };
   }
 
+  it('stores the description as the whole body, and an access request\'s level and note on their own columns', async () => {
+    const h = makeOpenHarness(vi.fn().mockResolvedValue(undefined));
+    await h.svc.openChangeRequest('ali%2Fx', makeUser(), { ...INPUT, description: '  Why this.  ' });
+    expect(h.values).toHaveBeenLastCalledWith(
+      expect.objectContaining({ body: 'Why this.', accessRequestLevel: null, accessRequestNote: null }),
+    );
+    // Nothing of Hexis's own is appended: the stored body is exactly the description.
+    expect((h.values.mock.calls[0] as [Record<string, unknown>])[0].body).not.toContain('Affected owners');
+
+    await h.svc.openChangeRequest('ali%2Fx', makeUser(), {
+      ...INPUT,
+      description: 'Rita asked for **Owner** on Research.',
+      accessRequest: { level: 'owner', note: '  I maintain these pages now  ' },
+    });
+    expect(h.values).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        body: 'Rita asked for **Owner** on Research.',
+        accessRequestLevel: 'owner',
+        accessRequestNote: 'I maintain these pages now',
+      }),
+    );
+
+    // A level with a blank note stores no note.
+    await h.svc.openChangeRequest('ali%2Fx', makeUser(), { ...INPUT, accessRequest: { level: 'write', note: '   ' } });
+    expect(h.values).toHaveBeenLastCalledWith(
+      expect.objectContaining({ body: '', accessRequestLevel: 'write', accessRequestNote: null }),
+    );
+  });
+
   it('creates the request, then answers 409 with the saved-locally sentence and raises the banner', async () => {
     const refused = new Error(
       'git push failed: remote: Internal Server Error\n ! [remote rejected] ali/x -> ali/x (Internal Server Error)',
@@ -1787,6 +1847,9 @@ describe('WorkflowService.openChangeRequest — tells the change-request listene
     // The row landed before anyone was told, and the answer says who was.
     expect(h.values).toHaveBeenCalledTimes(1);
     expect(h.values.mock.invocationCallOrder[0]).toBeLessThan(h.run.mock.invocationCallOrder[0]!);
+    // The approvers the listeners hear of are never written into the request:
+    // with no description, the stored body is empty.
+    expect((h.values.mock.calls[0] as unknown as [Record<string, unknown>])[0].body).toBe('');
     expect(answer).toMatchObject({ number: 12, notified: ['email'] });
   });
 

package/src/modules/workflow/__tests__/workflow.service.update-change-request.pg.test.ts

@@ -0,0 +1,120 @@
+import { afterAll, describe, expect, it, vi } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import { closeDb, createDb, type Database } from '../../database/connection.js';
+import { runCoreMigrations } from '../../database/migrate.js';
+import { changeRequests } from '../../database/core-schema.js';
+import { coreMigrationsDir } from '../../../assets.js';
+import { PG_ADMIN_URL, PG_TEST_TIMEOUT, dropScratchDatabases, scratchDatabaseUrl } from '../../../__tests__/pg-scratch.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import { openChangeGate } from '../../../__tests__/open-change-gate.js';
+import { hashEmail } from '../../../shared/email-identity.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { GitService } from '../git/git.service.js';
+import type { PullRequestService } from '../git/pull-request.service.js';
+import type { IReviewWorkflowService } from '../review-workflow/review-workflow.interface.js';
+import type { FileLockService } from '../file-lock.service.js';
+import type { PendingCommitsService } from '../pending-commits.service.js';
+import { WorkflowService } from '../workflow.service.js';
+
+/**
+ * An edit against a real Postgres with column encryption ON. `title` and
+ * `body` are sealed with a fresh IV on every write, so no stub of the driver
+ * shows what a guard comparing the stored body would do: never match, and
+ * refuse every permitted edit with 409. Here the row is real and encrypted.
+ */
+const KEY = randomBytes(32).toString('base64');
+const AUTHOR = 'alice@example.com';
+const alice: AuthUser = { id: 'u-alice', email: AUTHOR, name: 'Alice' };
+const open: Database[] = [];
+
+async function seeded(): Promise<{ svc: WorkflowService; db: Database; number: number }> {
+  const db = createDb(await scratchDatabaseUrl('hexis_cr_edit'), { piiKey: KEY });
+  open.push(db);
+  await runCoreMigrations(db, coreMigrationsDir());
+  const [row] = await db
+    .insert(changeRequests)
+    .values({
+      sourceBranch: 'alice/draft',
+      targetBranch: 'main',
+      title: 'Old title',
+      body: 'Old reason.',
+      authorEmail: AUTHOR,
+      authorEmailBidx: AUTHOR,
+      authorName: 'Alice',
+    })
+    .returning({ number: changeRequests.number });
+  const number = row.number!;
+  const readRow = async () =>
+    (await db.select().from(changeRequests).where(eq(changeRequests.number, number)))[0];
+  const prs = {
+    getPr: vi.fn(async () => {
+      const r = await readRow();
+      return { number, title: r.title, base: 'main', branch: 'alice/draft', state: r.state, authorId: hashEmail(AUTHOR) };
+    }),
+    invalidateDetailCache: vi.fn(),
+  } as unknown as PullRequestService;
+  const svc = new WorkflowService(
+    db,
+    {} as GitService,
+    prs,
+    {} as IReviewWorkflowService,
+    {} as WorkspaceService,
+    {} as IAccessControl,
+    {} as FileLockService,
+    {} as PendingCommitsService,
+    testKbContext(),
+    openChangeGate(),
+  );
+  return { svc, db, number };
+}
+
+describe.skipIf(!PG_ADMIN_URL)('WorkflowService.updateChangeRequest on a real, encrypted Postgres', () => {
+  afterAll(async () => {
+    for (const db of open) await closeDb(db);
+    await dropScratchDatabases();
+  }, PG_TEST_TIMEOUT);
+
+  it(
+    'lets the author change the title and description, and reads the new text back',
+    async () => {
+      const { svc, db, number } = await seeded();
+      await svc.updateChangeRequest(number, alice, { title: 'New title', description: 'New reason.' });
+      const [row] = await db.select().from(changeRequests).where(eq(changeRequests.number, number));
+      expect(row.title).toBe('New title');
+      expect(row.body).toBe('New reason.');
+    },
+    PG_TEST_TIMEOUT,
+  );
+
+  it(
+    'lands two appends racing each other, neither lost',
+    async () => {
+      const { svc, db, number } = await seeded();
+      await Promise.all([
+        svc.updateChangeRequest(number, alice, { appendDescription: 'Note one.' }),
+        svc.updateChangeRequest(number, alice, { appendDescription: 'Note two.' }),
+      ]);
+      const [row] = await db.select().from(changeRequests).where(eq(changeRequests.number, number));
+      expect(row.body).toMatch(/^Old reason\.\n\nNote (one|two)\.\n\nNote (one|two)\.$/);
+      expect(row.body).toContain('Note one.');
+      expect(row.body).toContain('Note two.');
+    },
+    PG_TEST_TIMEOUT,
+  );
+
+  it(
+    'refuses a closed request with the worded 409',
+    async () => {
+      const { svc, db, number } = await seeded();
+      await db.update(changeRequests).set({ state: 'closed' }).where(eq(changeRequests.number, number));
+      await expect(svc.updateChangeRequest(number, alice, { title: 'Nope' })).rejects.toMatchObject({
+        status: 409,
+        message: expect.stringContaining('closed'),
+      });
+    },
+    PG_TEST_TIMEOUT,
+  );
+});

package/src/modules/workflow/__tests__/workflow.service.update-change-request.test.ts

@@ -0,0 +1,346 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { AuthUser, WorkflowEventPayload } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import { openChangeGate } from '../../../__tests__/open-change-gate.js';
+import { hashEmail } from '../../../shared/email-identity.js';
+import type { Database } from '../../database/connection.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { GitService } from '../git/git.service.js';
+import type { PullRequestService } from '../git/pull-request.service.js';
+import type { IReviewWorkflowService } from '../review-workflow/review-workflow.interface.js';
+import type { FileLockService } from '../file-lock.service.js';
+import type { PendingCommitsService } from '../pending-commits.service.js';
+import type { WorkflowEventBus } from '../event-bus.js';
+import { WorkflowService } from '../workflow.service.js';
+
+/**
+ * Who may change an open request's title and description: its author, or
+ * anyone who may merge it — an admin (write on `roles.yaml` at the base), or
+ * the holder of write on every file it changes. Everyone else is refused in
+ * words (403), and so is a request that is no longer open (409). These pin
+ * that rule and what an allowed edit writes.
+ */
+
+const AUTHOR = 'alice@example.com';
+const OTHER = 'mallory@example.com';
+
+const user = (email: string, name = 'Caller'): AuthUser => ({ id: `u-${email}`, email, name });
+
+function harness(
+  opts: {
+    state?: string;
+    authorEmail?: string;
+    isAdmin?: boolean | null;
+    writes?: Record<string, boolean> | null;
+    files?: string[];
+    body?: string;
+  } = {},
+) {
+  const state = opts.state ?? 'open';
+  const summary = {
+    number: 9,
+    title: 'Old title',
+    base: 'main',
+    branch: 'mallory/draft',
+    state,
+    authorId: hashEmail(opts.authorEmail ?? OTHER),
+    url: '/change-requests/9',
+  };
+  const prs = {
+    getPr: vi.fn(async () => summary),
+    getPrDetail: vi.fn(async () => ({
+      ...summary,
+      files: (opts.files ?? ['Docs/a.md', 'Docs/b.md']).map((path) => ({ path })),
+    })),
+    invalidateDetailCache: vi.fn(),
+  } as unknown as PullRequestService;
+
+  const written: Record<string, unknown>[] = [];
+  // The transaction hands its callback a client of its OWN: every read and
+  // write of the row must go through it, so a read that slipped outside the
+  // transaction (and so outside the row lock) lands on `db` instead.
+  const tx = {
+    select: vi.fn(() => tx),
+    from: vi.fn(() => tx),
+    where: vi.fn(() => tx),
+    limit: vi.fn(() => tx),
+    for: vi.fn(async () => (state === 'open' ? [{ body: opts.body ?? 'Old reason.' }] : [])),
+    update: vi.fn(() => tx),
+    set: vi.fn((values: Record<string, unknown>) => {
+      written.push(values);
+      return tx;
+    }),
+    returning: vi.fn(async () => [{ id: 'row-9' }]),
+  };
+  // The outer client answers every query with no rows: only background
+  // housekeeping (the deleted-branch sweep) may read through it.
+  const outer: Record<string, unknown> = {
+    then: (resolve: (rows: unknown[]) => unknown) => resolve([]),
+  };
+  for (const step of ['from', 'where', 'limit', 'orderBy', 'innerJoin', 'set']) outer[step] = () => outer;
+  const db = {
+    select: vi.fn(() => outer),
+    update: vi.fn(() => outer),
+    transaction: vi.fn(async (fn: (client: unknown) => Promise<unknown>) => fn(tx)),
+  };
+
+  const writes = opts.writes === undefined ? {} : opts.writes;
+  const access = {
+    canWriteAtRef: vi.fn(async () => (opts.isAdmin === undefined ? false : opts.isAdmin)),
+    canWriteBatchAtRef: vi.fn(async (_ws: string, _ref: string, _email: string, paths: string[]) =>
+      writes === null ? null : new Map(paths.map((p) => [p, writes[p] === true])),
+    ),
+  } as unknown as IAccessControl;
+  const workspaces = {
+    getOrCreateForBranch: vi.fn(async (b: string) => ({ id: encodeURIComponent(b) })),
+    ensureRemotesFetched: vi.fn(async () => undefined),
+  } as unknown as WorkspaceService;
+  const emitted: WorkflowEventPayload[] = [];
+  const events = { emit: (e: WorkflowEventPayload) => emitted.push(e) } as unknown as WorkflowEventBus;
+
+  const svc = new WorkflowService(
+    db as unknown as Database,
+    {} as GitService,
+    prs,
+    {} as IReviewWorkflowService,
+    workspaces,
+    access,
+    {} as FileLockService,
+    {} as PendingCommitsService,
+    testKbContext(),
+    openChangeGate(),
+    events,
+  );
+  return { svc, db, tx, written, prs, access, workspaces, emitted };
+}
+
+describe('WorkflowService.updateChangeRequest — who may edit', () => {
+  it('lets the AUTHOR edit without any further grant, and resolves no workspace and reads no access tree', async () => {
+    const h = harness({ authorEmail: AUTHOR });
+    await h.svc.updateChangeRequest(9, user(AUTHOR), { description: 'P2 - Planned\n\nNew reason.' });
+    expect(h.written).toHaveLength(1);
+    expect(h.access.canWriteAtRef).not.toHaveBeenCalled();
+    expect(h.workspaces.getOrCreateForBranch).not.toHaveBeenCalled();
+  });
+
+  it('matches the author case-insensitively, as authorship is stored', async () => {
+    const h = harness({ authorEmail: AUTHOR });
+    await h.svc.updateChangeRequest(9, user('  Alice@Example.com '), { title: 'New' });
+    expect(h.written).toHaveLength(1);
+  });
+
+  it('lets an ADMIN edit someone else’s request', async () => {
+    const h = harness({ isAdmin: true });
+    await h.svc.updateChangeRequest(9, user('admin@example.com'), { title: 'New' });
+    expect(h.written).toHaveLength(1);
+    expect(h.access.canWriteAtRef).toHaveBeenCalledWith('main', 'origin/main', 'admin@example.com', 'roles.yaml');
+  });
+
+  it('lets someone who may approve EVERY changed file edit it', async () => {
+    const h = harness({ writes: { 'Docs/a.md': true, 'Docs/b.md': true } });
+    await h.svc.updateChangeRequest(9, user('owner@example.com'), { title: 'New' });
+    expect(h.written).toHaveLength(1);
+    // Read at the base, behind a strict fetch — never a stale local ref.
+    expect(h.workspaces.ensureRemotesFetched).toHaveBeenCalledWith('main', { strict: true, force: true });
+    expect(h.access.canWriteBatchAtRef).toHaveBeenCalledWith('main', 'origin/main', 'owner@example.com', [
+      'Docs/a.md',
+      'Docs/b.md',
+    ]);
+  });
+
+  it('refuses someone who may approve only SOME of the files, in words, and writes nothing', async () => {
+    const h = harness({ writes: { 'Docs/a.md': true } });
+    await expect(h.svc.updateChangeRequest(9, user('half@example.com'), { title: 'New' })).rejects.toMatchObject({
+      status: 403,
+      message:
+        "Only the request's author, an admin, or someone who may approve every file it changes can edit its title and description.",
+    });
+    expect(h.tx.update).not.toHaveBeenCalled();
+    expect(h.emitted).toEqual([]);
+  });
+
+  it('refuses a stranger with the same 403', async () => {
+    const h = harness();
+    await expect(h.svc.updateChangeRequest(9, user('stranger@example.com'), { description: 'x' })).rejects.toMatchObject({
+      status: 403,
+    });
+    expect(h.tx.update).not.toHaveBeenCalled();
+  });
+
+  it('an empty file list grants nobody but the author and admins', async () => {
+    const h = harness({ files: [] });
+    await expect(h.svc.updateChangeRequest(9, user('stranger@example.com'), { title: 'New' })).rejects.toMatchObject({
+      status: 403,
+    });
+  });
+
+  it('answers 409 rather than 403 when the base branch cannot be resolved', async () => {
+    const h = harness({ isAdmin: null });
+    await expect(h.svc.updateChangeRequest(9, user('admin@example.com'), { title: 'New' })).rejects.toMatchObject({
+      status: 409,
+      message: expect.stringContaining('could not be resolved'),
+    });
+    expect(h.tx.update).not.toHaveBeenCalled();
+  });
+
+  it('refuses a MERGED request with a worded 409, even to its author', async () => {
+    const h = harness({ state: 'merged', authorEmail: AUTHOR });
+    await expect(h.svc.updateChangeRequest(9, user(AUTHOR), { title: 'New' })).rejects.toMatchObject({
+      status: 409,
+      message: 'This change request has already been applied; its title and description can no longer be changed.',
+    });
+    expect(h.tx.update).not.toHaveBeenCalled();
+  });
+
+  it('refuses a CLOSED request with a worded 409, even to an admin', async () => {
+    const h = harness({ state: 'closed', isAdmin: true });
+    await expect(h.svc.updateChangeRequest(9, user('admin@example.com'), { title: 'New' })).rejects.toMatchObject({
+      status: 409,
+      message: 'This change request is closed; its title and description can no longer be changed.',
+    });
+    expect(h.tx.update).not.toHaveBeenCalled();
+  });
+
+  it('refuses a request that does not exist with 404', async () => {
+    const h = harness();
+    (h.prs.getPr as ReturnType<typeof vi.fn>).mockResolvedValue(null);
+    await expect(h.svc.updateChangeRequest(9, user(AUTHOR), { title: 'New' })).rejects.toMatchObject({ status: 404 });
+  });
+
+  it('refuses an edit that changes nothing, or empties the title, with 400', async () => {
+    const h = harness({ authorEmail: AUTHOR });
+    await expect(h.svc.updateChangeRequest(9, user(AUTHOR), {})).rejects.toMatchObject({ status: 400 });
+    await expect(h.svc.updateChangeRequest(9, user(AUTHOR), { title: '   ' })).rejects.toMatchObject({ status: 400 });
+    expect(h.tx.update).not.toHaveBeenCalled();
+  });
+
+  it('refuses a title past 256 characters with 400 — the agent tool’s limit, for the route too', async () => {
+    const h = harness({ authorEmail: AUTHOR });
+    await h.svc.updateChangeRequest(9, user(AUTHOR), { title: 'x'.repeat(256) });
+    await expect(h.svc.updateChangeRequest(9, user(AUTHOR), { title: 'x'.repeat(257) })).rejects.toMatchObject({
+      status: 400,
+      message: expect.stringContaining('at most 256 characters'),
+    });
+    expect(h.written).toHaveLength(1);
+  });
+
+  it('refuses a description past 64,000 characters with 400, on a replacement and on what an append would leave', async () => {
+    const h = harness({ authorEmail: AUTHOR, body: 'x'.repeat(63_990) });
+    await h.svc.updateChangeRequest(9, user(AUTHOR), { description: 'y'.repeat(64_000) });
+    await expect(h.svc.updateChangeRequest(9, user(AUTHOR), { description: 'y'.repeat(64_001) })).rejects.toMatchObject({
+      status: 400,
+      message: expect.stringContaining('at most 64000 characters'),
+    });
+    // 63,990 stored + the two newlines + 9 = 64,001: measured on what the
+    // append leaves, inside the transaction, and nothing is written.
+    await expect(h.svc.updateChangeRequest(9, user(AUTHOR), { appendDescription: 'z'.repeat(9) })).rejects.toMatchObject({
+      status: 400,
+      message: expect.stringContaining('at most 64000 characters'),
+    });
+    expect(h.written).toHaveLength(1);
+  });
+
+  it('refuses a replacement and an append together with 400', async () => {
+    const h = harness({ authorEmail: AUTHOR });
+    await expect(
+      h.svc.updateChangeRequest(9, user(AUTHOR), { description: 'a', appendDescription: 'b' }),
+    ).rejects.toMatchObject({ status: 400 });
+    expect(h.tx.update).not.toHaveBeenCalled();
+  });
+});
+
+describe('WorkflowService.openChangeRequest — the same ceiling on the description', () => {
+  it('refuses a description past 64,000 characters with 400 before touching a workspace', async () => {
+    const h = harness({ authorEmail: AUTHOR });
+    await expect(
+      h.svc.openChangeRequest('ws', user(AUTHOR), {
+        sourceBranch: 'mallory/draft',
+        targetBranch: 'main',
+        title: 'Too long',
+        description: 'y'.repeat(64_001),
+      }),
+    ).rejects.toMatchObject({ status: 400, message: expect.stringContaining('at most 64000 characters') });
+    expect(h.workspaces.getOrCreateForBranch).not.toHaveBeenCalled();
+  });
+});
+
+describe('WorkflowService.updateChangeRequest — what an edit writes', () => {
+  it('replaces the body whole — the body is the description and nothing else', async () => {
+    const h = harness({ authorEmail: AUTHOR });
+    const before = Date.now();
+    await h.svc.updateChangeRequest(9, user(AUTHOR, 'Alice'), { description: '  P2 - Planned\n\nNew reason.  ' });
+    const [set] = h.written;
+    expect(set.body).toBe('P2 - Planned\n\nNew reason.');
+    expect(set).not.toHaveProperty('title');
+    expect((set.updatedAt as Date).getTime()).toBeGreaterThanOrEqual(before);
+  });
+
+  it("keeps the author's own headings: nothing in a body is Hexis's to cut", async () => {
+    const h = harness({ authorEmail: AUTHOR });
+    await h.svc.updateChangeRequest(9, user(AUTHOR), { description: 'Lead.\n\n## Affected owners\n\nI mean the GTM ones.' });
+    expect(h.written[0].body).toBe('Lead.\n\n## Affected owners\n\nI mean the GTM ones.');
+  });
+
+  it('changes the title alone without touching the body', async () => {
+    const h = harness({ authorEmail: AUTHOR });
+    await h.svc.updateChangeRequest(9, user(AUTHOR), { title: '  New title ' });
+    const [set] = h.written;
+    expect(set.title).toBe('New title');
+    expect(set).not.toHaveProperty('body');
+  });
+
+  it("never touches an access request's level or note — they are columns, not prose", async () => {
+    const h = harness({ authorEmail: AUTHOR, body: 'Alice asked for **Owner** on Docs.' });
+    await h.svc.updateChangeRequest(9, user(AUTHOR), { description: 'Please, for the Q3 review.' });
+    const [set] = h.written;
+    expect(set.body).toBe('Please, for the Q3 review.');
+    expect(set).not.toHaveProperty('accessRequestLevel');
+    expect(set).not.toHaveProperty('accessRequestNote');
+  });
+
+  it('appends to the description as stored', async () => {
+    const h = harness({ authorEmail: AUTHOR });
+    await h.svc.updateChangeRequest(9, user(AUTHOR), { appendDescription: '  Round two.  ' });
+    expect(h.written[0].body).toBe('Old reason.\n\nRound two.');
+  });
+
+  it('an append to an empty description is the description', async () => {
+    const h = harness({ authorEmail: AUTHOR, body: '' });
+    await h.svc.updateChangeRequest(9, user(AUTHOR), { appendDescription: 'P1 - High' });
+    expect(h.written[0].body).toBe('P1 - High');
+  });
+
+  it('reads the body under the row’s lock, in the transaction that writes it, so racing edits serialise', async () => {
+    const h = harness({ authorEmail: AUTHOR });
+    await h.svc.updateChangeRequest(9, user(AUTHOR), { appendDescription: 'Round two.' });
+    expect(h.db.transaction).toHaveBeenCalledTimes(1);
+    expect(h.db.select).not.toHaveBeenCalled();
+    expect(h.db.update).not.toHaveBeenCalled();
+    expect(h.tx.select).toHaveBeenCalledTimes(1);
+    expect(h.tx.for).toHaveBeenCalledWith('update');
+    expect(h.tx.update).toHaveBeenCalledTimes(1);
+    expect(h.written).toHaveLength(1);
+    expect(h.emitted).toEqual([{ kind: 'change-request-edited', number: 9 }]);
+  });
+
+  it('drops the cached reads and tells every session, so readers see the new text at once', async () => {
+    const h = harness({ authorEmail: AUTHOR });
+    await h.svc.updateChangeRequest(9, user(AUTHOR), { title: 'New' });
+    expect(h.prs.invalidateDetailCache).toHaveBeenCalledWith(9);
+    expect(h.emitted).toEqual([{ kind: 'change-request-edited', number: 9 }]);
+  });
+
+  it('a merge that won the race refuses the edit with the merged 409', async () => {
+    const h = harness({ authorEmail: AUTHOR });
+    (h.tx.returning as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+    (h.prs.getPr as ReturnType<typeof vi.fn>)
+      .mockResolvedValueOnce({ state: 'open', authorId: hashEmail(AUTHOR), base: 'main' })
+      .mockResolvedValueOnce({ state: 'merged' });
+    await expect(h.svc.updateChangeRequest(9, user(AUTHOR), { title: 'New' })).rejects.toMatchObject({
+      status: 409,
+      message: expect.stringContaining('already been applied'),
+    });
+    expect(h.emitted).toEqual([]);
+  });
+});