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

package/src/modules/workflow/__tests__/workflow.routes.open-change-request.test.ts

@@ -0,0 +1,79 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { WorkflowEventBus } from '../event-bus.js';
+import { createWorkflowRoutes } from '../workflow.routes.js';
+
+/**
+ * `POST /api/workflow/change-requests` answers the opened request as the
+ * service hands it over, `notified` included: the channels the deployment's
+ * change-request listeners said reached the approvers, so the dialog can say
+ * "the reviewers were emailed" — or hand over the link when nobody was.
+ */
+
+const ALICE: AuthUser = { id: '11111111-1111-4111-8111-111111111111', email: 'alice@example.com', name: 'Alice' };
+
+async function serve(workflow: Partial<IWorkflowService>): Promise<{ server: Server; baseUrl: string }> {
+  const authService = { getUserById: vi.fn(async () => ALICE) } as unknown as AuthService;
+  const workspaceService = {
+    getOrCreateForBranch: vi.fn(async (branch: string) => ({ id: encodeURIComponent(branch) })),
+  } as unknown as WorkspaceService;
+  const app = express();
+  app.use(express.json());
+  app.use('/api', (req, _res, next) => {
+    (req as unknown as { userId: string }).userId = ALICE.id;
+    next();
+  });
+  app.use(
+    '/api',
+    createWorkflowRoutes(
+      workflow as IWorkflowService,
+      workspaceService,
+      authService,
+      new WorkflowEventBus(),
+      {} as unknown as IAccessControl,
+      'knowledge-base',
+    ),
+  );
+  const server = await new Promise<Server>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  return { server, baseUrl: `http://127.0.0.1:${(server.address() as AddressInfo).port}` };
+}
+
+describe('POST /workflow/change-requests answers who was notified', () => {
+  let server: Server | undefined;
+  afterEach(async () => {
+    if (server) await new Promise<void>((resolve, reject) => server!.close((e) => (e ? reject(e) : resolve())));
+    server = undefined;
+  });
+
+  it.each([
+    ['the channels that reached the approvers', ['email']],
+    ['nobody, truthfully', []],
+  ])('carries `notified`: %s', async (_what, notified) => {
+    const openChangeRequest = vi.fn(async () => ({ number: 12, branch: 'alice/deal', base: 'main', notified }) as never);
+    let baseUrl: string;
+    ({ server, baseUrl } = await serve({ openChangeRequest }));
+
+    const res = await fetch(`${baseUrl}/api/workflow/change-requests`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ sourceBranch: 'alice/deal', targetBranch: 'main', title: 'Deal' }),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ number: 12, branch: 'alice/deal', base: 'main', notified });
+    // The open runs in the SOURCE branch's workspace, by the caller.
+    expect(openChangeRequest).toHaveBeenCalledTimes(1);
+    expect(openChangeRequest).toHaveBeenCalledWith(
+      encodeURIComponent('alice/deal'),
+      ALICE,
+      { sourceBranch: 'alice/deal', targetBranch: 'main', title: 'Deal', description: undefined },
+    );
+  });
+});

package/src/modules/workflow/__tests__/workflow.service.delete-branch.test.ts

@@ -115,6 +115,7 @@ interface Harness {
   deleted: string[];
   /** What the service announced to connected tabs. */
   emitted: { kind: string; number?: number }[];
+  changeRequestHooks: { onChangeRequestOpened: ReturnType<typeof vi.fn>; runChangeRequestOpened: ReturnType<typeof vi.fn> };
   hasAnyActive: MockInstance<FileLockService['hasAnyActive']>;
 }
 
@@ -142,6 +143,7 @@ function harness(opts: {
 }): Harness {
   const deleted: string[] = [];
   const emitted: { kind: string; number?: number }[] = [];
+  const changeRequestHooks = { onChangeRequestOpened: vi.fn(), runChangeRequestOpened: vi.fn(async () => []) };
   const rows = opts.rows ?? [];
   const branches = { ...(opts.branches ?? {}) };
   const git = {
@@ -212,8 +214,11 @@ function harness(opts: {
     testKbContext(),
     openChangeGate(),
     { emit: (e: { kind: string; number?: number }) => void emitted.push(e) } as unknown as WorkflowEventBus,
+    undefined,
+    undefined,
+    changeRequestHooks,
   );
-  return { svc, git, fetch, deleted, emitted, hasAnyActive };
+  return { svc, git, fetch, deleted, emitted, hasAnyActive, changeRequestHooks };
 }
 
 const merged = (number: number, source: string, sha: string | null): CrRow => ({
@@ -557,6 +562,9 @@ describe('a change request that proposes nothing never blocks a deletion', () =>
       expect.objectContaining({ number: 21, source: 'ali/sync', target: DEFAULT }),
       expect.objectContaining({ number: 22, source: 'ali/feature', target: 'ali/sync' }),
     ]);
+    // A reopened request was opened once already: the deployment's
+    // change-request-opened listeners are not told again.
+    expect(h.changeRequestHooks.runChangeRequestOpened).not.toHaveBeenCalled();
     // The app's path, the same.
     reopens.length = 0;
     await expect(h.svc.deleteBranch(workspaceIdForBranch(DEFAULT), 'ali/sync', ADMIN)).rejects.toThrow(/stale info/);

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

@@ -1,9 +1,12 @@
-import { describe, it, expect, vi } from 'vitest';
+import { afterAll, beforeAll, describe, it, expect, vi } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 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';
@@ -15,10 +18,13 @@ import { PendingCommitsService, type PendingCommit } from '../pending-commits.se
 import { PendingCommitsWorker } from '../pending-commits.worker.js';
 import { HttpCommunicationProtocol } from '@utcp/http';
 import { WorkflowService } from '../workflow.service.js';
+import type { ChangeRequestOpenedEvent, IChangeRequestHooks } from '../change-request-hooks.js';
 import {
+  ChangeRequestConflictsError,
   PullRebaseConflictError,
   PushNeedsAgentResolutionError,
   WorkflowDomainError,
+  WorkflowValidationError,
 } from '../../../shared/domain-errors.js';
 import type { WorkflowEventBus } from '../event-bus.js';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
@@ -225,15 +231,13 @@ function makePrs(): PullRequestService {
     getPrDetail: vi.fn(),
     invalidateDetailCache: vi.fn(),
     setDetailEnricher: vi.fn(),
+    // No public address configured: the in-app path, with its note.
+    linkFor: vi.fn((number: number) => ({ url: `/change-requests/${number}`, urlNote: 'Set PUBLIC_FRONTEND_URL to get absolute links.' })),
   } as unknown as 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(),
@@ -563,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();
@@ -593,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();
@@ -1597,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)',
@@ -1640,6 +1709,257 @@ describe('WorkflowService.openChangeRequest — when the repository host refuses
   });
 });
 
+/**
+ * Opening a request tells the deployment's change-request listeners — once,
+ * here, whether a person or an agent opened it — and answers `notified`: the
+ * channels the listeners said reached the approvers. The approvers are the
+ * people the `## Affected owners` block lists, resolved to accounts and
+ * handed over once each; who could not be is counted.
+ */
+describe('WorkflowService.openChangeRequest — tells the change-request listeners', () => {
+  const INPUT = { sourceBranch: 'ali/x', targetBranch: 'main', title: '  Tidy the glossary  ' };
+  const PATHS = ['KnowledgeBase/Sales/Deal.md', 'KnowledgeBase/Legal/Terms.md'];
+  const ACCOUNTS: Record<string, { id: string; email: string; name: string }> = {
+    'dana@acme.test': { id: 'u-dana', email: 'dana@acme.test', name: 'Dana' },
+    'lena@acme.test': { id: 'u-lena', email: 'Lena@acme.test', name: 'Lena' },
+  };
+
+  function eligibility(
+    perPath: Record<string, { roles?: string[]; emails: string[] }>,
+  ): Map<string, { roles: string[]; users: { name: string; email: string }[]; emails: Set<string> }> {
+    const out = new Map<string, { roles: string[]; users: { name: string; email: string }[]; emails: Set<string> }>();
+    for (const [p, { roles = [], emails }] of Object.entries(perPath)) {
+      out.set(p, { roles, users: emails.map((email) => ({ name: '', email })), emails: new Set(emails) });
+    }
+    return out;
+  }
+
+  // A real repository, so the changed paths come from the `git diff` the
+  // service runs in production and not from a replaced helper: `main` is the
+  // base and the ref `origin/main` the diff is taken against; `ali/x` adds
+  // PATHS. The checkout sits under the knowledge-base folder name the test
+  // context gives, where the service looks for it.
+  let workspace: string;
+  beforeAll(() => {
+    workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'hexis-open-tells-'));
+    const repo = path.join(workspace, testKbContext().kbDirName);
+    fs.mkdirSync(repo);
+    const git = (...args: string[]) =>
+      execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@t.test', '-c', 'commit.gpgsign=false', ...args], { cwd: repo, stdio: 'pipe' });
+    git('init', '-q', '-b', 'main');
+    git('commit', '-q', '--allow-empty', '-m', 'base');
+    git('update-ref', 'refs/remotes/origin/main', 'HEAD');
+    git('checkout', '-q', '-b', 'ali/x');
+    for (const p of PATHS) {
+      fs.mkdirSync(path.dirname(path.join(repo, p)), { recursive: true });
+      fs.writeFileSync(path.join(repo, p), `# ${p}\n`);
+    }
+    git('add', '-A');
+    git('commit', '-q', '-m', 'the change');
+  });
+  afterAll(() => {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  });
+
+  function makeNotifyHarness(opts: {
+    eligible?: ReturnType<typeof eligibility> | null;
+    push?: ReturnType<typeof vi.fn>;
+    merge?: ReturnType<typeof vi.fn>;
+    detail?: ReturnType<typeof vi.fn>;
+    accounts?: { findActiveAccountsByEmail: ReturnType<typeof vi.fn> } | undefined;
+    link?: { url: string; urlNote?: string };
+  } = {}) {
+    const git = Object.assign(makeGit(), {
+      mergeFromOrigin: opts.merge ?? vi.fn().mockResolvedValue({ kind: 'clean', alreadyUpToDate: false }),
+      push: opts.push ?? vi.fn().mockResolvedValue(undefined),
+      pull: vi.fn().mockResolvedValue({ treeChanged: false }),
+    }) as unknown as GitService;
+    const prs = makePrs();
+    (prs.listOpenPrs as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+    if (opts.detail) prs.getPrDetail = opts.detail as unknown as PullRequestService['getPrDetail'];
+    else (prs.getPrDetail as ReturnType<typeof vi.fn>).mockResolvedValue({ number: 12, branch: 'ali/x', base: 'main' });
+    if (opts.link) (prs.linkFor as ReturnType<typeof vi.fn>).mockReturnValue(opts.link);
+    const workspaces = makeWorkspaceService();
+    (workspaces.getWorkspacePath as ReturnType<typeof vi.fn>).mockResolvedValue(workspace);
+    const access = makeAccessControl();
+    (access.eligibleWritersForPathsAtRef as ReturnType<typeof vi.fn>).mockResolvedValue(opts.eligible ?? null);
+    const values = vi.fn(() => ({ returning: vi.fn(async () => [{ number: 12 }]) }));
+    const db = { insert: vi.fn(() => ({ values })) } as unknown as Database;
+    const run = vi.fn<(event: ChangeRequestOpenedEvent) => Promise<string[]>>(async () => ['email']);
+    const hooks: IChangeRequestHooks = { onChangeRequestOpened: vi.fn(), runChangeRequestOpened: run };
+    const accounts =
+      'accounts' in opts
+        ? opts.accounts
+        : {
+            findActiveAccountsByEmail: vi.fn(async (emails: readonly string[]) => {
+              const found = new Map<string, { id: string; email: string; name: string }>();
+              for (const email of emails) {
+                const account = ACCOUNTS[email];
+                if (account) found.set(email, account);
+              }
+              return found;
+            }),
+          };
+    const svc = new WorkflowService(
+      db, git, prs, makeReviewWorkflow(), workspaces, access,
+      makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate(),
+      { emit: vi.fn() } as unknown as WorkflowEventBus, undefined, undefined, hooks, accounts,
+    );
+    return { svc, run, prs, access, accounts, values };
+  }
+
+  it('fires once, after the row exists, with the request, who opened it and the approvers as accounts — once each', async () => {
+    const h = makeNotifyHarness({
+      eligible: eligibility({
+        [PATHS[0]]: { roles: ['Sales'], emails: ['dana@acme.test', 'lena@acme.test'] },
+        // Lena again, by another spelling: one person.
+        [PATHS[1]]: { roles: ['Legal'], emails: ['LENA@acme.test'] },
+      }),
+    });
+    const user = makeUser({ id: 'u-ali', email: 'ali@acme.test', name: 'Ali' });
+    const answer = await h.svc.openChangeRequest('ali%2Fx', user, INPUT);
+
+    expect(h.run).toHaveBeenCalledTimes(1);
+    const [event] = h.run.mock.calls[0]!;
+    expect(event).toEqual({
+      number: 12,
+      title: 'Tidy the glossary',
+      sourceBranch: 'ali/x',
+      targetBranch: 'main',
+      openedBy: { id: 'u-ali', email: 'ali@acme.test', name: 'Ali' },
+      approvers: [
+        { id: 'u-dana', email: 'dana@acme.test', name: 'Dana' },
+        { id: 'u-lena', email: 'Lena@acme.test', name: 'Lena' },
+      ],
+      unresolvedApprovers: 0,
+      pushPending: false,
+    });
+    // No public address: no `url` at all, not a relative one.
+    expect(event).not.toHaveProperty('url');
+    // The accounts were read once, for the distinct canonical addresses.
+    expect(h.accounts!.findActiveAccountsByEmail).toHaveBeenCalledTimes(1);
+    expect(h.accounts!.findActiveAccountsByEmail.mock.calls[0]![0]).toEqual(['dana@acme.test', 'lena@acme.test']);
+    // The eligibility was asked for the paths the request changes — the
+    // `git diff` against the target's published ref, as in production.
+    const eligibleFor = h.access.eligibleWritersForPathsAtRef as ReturnType<typeof vi.fn>;
+    expect(eligibleFor).toHaveBeenCalledTimes(1);
+    expect(eligibleFor.mock.calls[0]!.slice(-1)[0]).toEqual([...PATHS].sort()); // as `git diff --name-only` orders them
+    // 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'] });
+  });
+
+  it('counts a person without an account and the built-in `everyone` as unresolved, and hands neither over', async () => {
+    const h = makeNotifyHarness({
+      eligible: eligibility({
+        [PATHS[0]]: { roles: ['everyone'], emails: ['dana@acme.test', 'nobody@acme.test'] },
+        [PATHS[1]]: { roles: ['everyone', 'Legal'], emails: ['dana@acme.test'] },
+      }),
+    });
+    await h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT);
+    const [event] = h.run.mock.calls[0]!;
+    expect(event.approvers).toEqual([{ id: 'u-dana', email: 'dana@acme.test', name: 'Dana' }]);
+    // `nobody@` once, `everyone` once however many paths grant it.
+    expect(event.unresolvedApprovers).toBe(2);
+  });
+
+  it('hands over the public address when one is configured', async () => {
+    const h = makeNotifyHarness({ link: { url: 'https://kb.acme.test/change-requests/12' } });
+    await h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT);
+    expect(h.run.mock.calls[0]![0]).toMatchObject({ url: 'https://kb.acme.test/change-requests/12', approvers: [], unresolvedApprovers: 0 });
+  });
+
+  it('with no accounts to ask, or a read of them that fails, every approver is unresolved and the open goes on', async () => {
+    const eligible = eligibility({ [PATHS[0]]: { emails: ['dana@acme.test', 'lena@acme.test'] } });
+    const without = makeNotifyHarness({ eligible, accounts: undefined });
+    await without.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT);
+    expect(without.run.mock.calls[0]![0]).toMatchObject({ approvers: [], unresolvedApprovers: 2 });
+
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const failing = makeNotifyHarness({
+        eligible,
+        accounts: { findActiveAccountsByEmail: vi.fn().mockRejectedValue(new Error('db down')) },
+      });
+      await expect(failing.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).resolves.toMatchObject({ notified: ['email'] });
+      expect(failing.run.mock.calls[0]![0]).toMatchObject({ approvers: [], unresolvedApprovers: 2 });
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('answers `notified: []` truthfully when the listeners reached nobody', async () => {
+    const h = makeNotifyHarness();
+    h.run.mockResolvedValue([]);
+    await expect(h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).resolves.toMatchObject({ number: 12, notified: [] });
+  });
+
+  it('tells the listeners even when the host refused the push, and says so: the request exists, its commits are still to land', async () => {
+    const h = makeNotifyHarness({
+      push: vi.fn().mockRejectedValue(new Error('git push failed: remote: Internal Server Error\n ! [remote rejected] ali/x -> ali/x (Internal Server Error)')),
+    });
+    const err = await h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(PushNeedsAgentResolutionError);
+    expect(h.run).toHaveBeenCalledTimes(1);
+    expect(h.run.mock.calls[0]![0]).toMatchObject({ number: 12, sourceBranch: 'ali/x', targetBranch: 'main', pushPending: true });
+  });
+
+  it('tells the listeners once the branches\' lifecycle locks are released: a slow mailer holds up the answer, not a delete or a merge', async () => {
+    const h = makeNotifyHarness();
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => { release = resolve; });
+    h.run.mockImplementation(async () => { await gate; return ['email']; });
+    const opening = h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT);
+    await vi.waitFor(() => { expect(h.run).toHaveBeenCalledTimes(1); });
+    // `createBranch` takes the branch's lifecycle lock — the one `deleteBranch`
+    // and `mergeBranch` take too — so it completing while the listener still
+    // waits shows the lock was released before the listeners were told.
+    const free = await Promise.race([
+      h.svc.createBranch('ali%2Fx', 'ali/x').then(() => 'free'),
+      new Promise<string>((resolve) => setTimeout(() => resolve('held'), 300)),
+    ]);
+    expect(free).toBe('free');
+    release();
+    await expect(opening).resolves.toMatchObject({ number: 12, notified: ['email'] });
+  });
+
+  it('tells the listeners when the detail cannot be read back: the request exists, a retry would be a duplicate', async () => {
+    const failing = makeNotifyHarness({ detail: vi.fn().mockRejectedValue(new Error('detail store down')) });
+    await expect(failing.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).rejects.toThrow('detail store down');
+    expect(failing.run).toHaveBeenCalledTimes(1);
+    expect(failing.run.mock.calls[0]![0]).toMatchObject({ number: 12, pushPending: false });
+
+    const missing = makeNotifyHarness({ detail: vi.fn().mockResolvedValue(null) });
+    await expect(missing.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).rejects.toBeInstanceOf(WorkflowValidationError);
+    expect(missing.run).toHaveBeenCalledTimes(1);
+  });
+
+  it('a refused open tells nobody: a validation failure, a conflicting auto-merge', async () => {
+    const invalid = makeNotifyHarness();
+    await expect(invalid.svc.openChangeRequest('ali%2Fx', makeUser(), { ...INPUT, title: '   ' })).rejects.toBeInstanceOf(WorkflowValidationError);
+    expect(invalid.run).not.toHaveBeenCalled();
+    expect(invalid.values).not.toHaveBeenCalled();
+
+    const conflicting = makeNotifyHarness({
+      merge: vi.fn().mockResolvedValue({ kind: 'conflicts', paths: ['KnowledgeBase/Sales/Deal.md'] }),
+    });
+    await expect(conflicting.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).rejects.toBeInstanceOf(ChangeRequestConflictsError);
+    expect(conflicting.run).not.toHaveBeenCalled();
+    expect(conflicting.values).not.toHaveBeenCalled();
+  });
+
+  it('a refused open (a duplicate, say) tells nobody', async () => {
+    const h = makeNotifyHarness();
+    (h.prs.listOpenPrs as ReturnType<typeof vi.fn>).mockResolvedValue([{ number: 3, branch: 'ali/x', base: 'main' }]);
+    await expect(h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).rejects.toThrow();
+    expect(h.run).not.toHaveBeenCalled();
+  });
+});
+
 /**
  * Writes are committed asynchronously: a write tool answers once the bytes are
  * on disk, and the pending-commits worker commits and pushes them seconds

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