@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/src/modules/workflow/__tests__/workflow.service.platform-restore.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { AuthUser } from '@bevel-software/platform-shared';
+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 { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { FileLockService } from '../file-lock.service.js';
+import type { PendingCommitsService } from '../pending-commits.service.js';
+import { WorkflowEventBus } from '../event-bus.js';
+import { WorkflowService } from '../workflow.service.js';
+import type { Database } from '../../database/connection.js';
+import { AccessDeniedError } from '../../access-model/access-errors.js';
+import { openChangeGate } from '../../../__tests__/open-change-gate.js';
+
+/**
+ * The write gate stays the single mechanism; the platform-file restore is an
+ * exception expressed INSIDE it.
+ *
+ * `opts.platformRestore` is a claim the caller makes, not an authorisation it
+ * carries. The gate re-asks both halves: that source→destination is a restore
+ * at all, which it answers itself, and whether this caller may land this exact
+ * path, which the access module answers. Only both yeses let the acquire
+ * through. These cases hold that apart from a general admin write bypass,
+ * which is the thing this rescue must never become — and apart from a flag a
+ * future caller could pass to take the root's own copy OUT.
+ */
+
+const USER: AuthUser = { id: 'user-1', email: 'razvan@bevel.software', name: 'Razvan' };
+const KB = 'knowledge-base';
+// One of the branches the backend test config marks protected — the gate runs
+// on protected branches only.
+const BRANCH = 'target-company-state';
+const WS = 'ws-1';
+
+function makeService(canRestorePlatformFile: IAccessControl['canRestorePlatformFile']) {
+  const acquire = vi.fn(async () => ({ acquired: true, lock: {} as never }));
+  const accessControl = {
+    // Everything is denied at the ref: the broken repository whose root has
+    // no `access.md` answers exactly this, to everyone.
+    canWriteBatchAtRef: vi.fn(async (_w: string, _r: string, _e: string, paths: string[]) =>
+      new Map(paths.map((p) => [p, false])),
+    ),
+    eligibleWritersAtRef: vi.fn(async () => ({ roles: [], users: [] })),
+    canRestorePlatformFile: vi.fn(canRestorePlatformFile),
+  } as unknown as IAccessControl;
+  const svc = new WorkflowService(
+    {} as unknown as Database,
+    {} as GitService,
+    {} as PullRequestService,
+    {} as IReviewWorkflowService,
+    {} as WorkspaceService,
+    accessControl,
+    { acquire, get: vi.fn(async () => null) } as unknown as FileLockService,
+    {} as PendingCommitsService,
+    KB,
+    openChangeGate(),
+    new WorkflowEventBus(),
+  );
+  return { svc, acquire, accessControl };
+}
+
+describe('acquiring the destination lock of a platform-file restore', () => {
+  const MISPLACED = `${KB}/Misplaced/access.md`;
+
+  it('lets the write past a destination that denies it when the access module says this is a restore', async () => {
+    const { svc, acquire, accessControl } = makeService(async () => true);
+
+    const result = await svc.acquireLock(WS, BRANCH, `${KB}/access.md`, USER, {
+      platformRestore: { source: MISPLACED },
+    });
+
+    expect(result.acquired).toBe(true);
+    expect(acquire).toHaveBeenCalledOnce();
+    // Asked repo-relative — the form the access model is keyed by.
+    expect(accessControl.canRestorePlatformFile).toHaveBeenCalledWith(WS, USER.email, 'access.md');
+  });
+
+  it('refuses when the access module says this caller may not restore this path', async () => {
+    const { svc, acquire } = makeService(async () => false);
+
+    await expect(
+      svc.acquireLock(WS, BRANCH, `${KB}/access.md`, USER, { platformRestore: { source: MISPLACED } }),
+    ).rejects.toBeInstanceOf(AccessDeniedError);
+    expect(acquire).not.toHaveBeenCalled();
+  });
+
+  it('a claim whose source is the copy the platform reads is refused without asking anyone', async () => {
+    // The move the whole feature exists to stop, wearing the rescue's clothes:
+    // the ROOT's own access.md carried into a folder that has none. The access
+    // module would say yes — it is only ever asked where the write LANDS — so
+    // the gate answers this one itself rather than passing it on.
+    const { svc, acquire, accessControl } = makeService(async () => true);
+
+    await expect(
+      svc.acquireLock(WS, BRANCH, `${KB}/Sales/access.md`, USER, {
+        platformRestore: { source: `${KB}/access.md` },
+      }),
+    ).rejects.toBeInstanceOf(AccessDeniedError);
+    expect(accessControl.canRestorePlatformFile).not.toHaveBeenCalled();
+    expect(acquire).not.toHaveBeenCalled();
+  });
+
+  it('a claim on any other path buys nothing — it is not a restore and is never asked about', async () => {
+    const { svc, acquire, accessControl } = makeService(async () => true);
+
+    await expect(
+      svc.acquireLock(WS, BRANCH, `${KB}/Sales/deal.md`, USER, {
+        platformRestore: { source: `${KB}/Misplaced/deal.md` },
+      }),
+    ).rejects.toBeInstanceOf(AccessDeniedError);
+    expect(accessControl.canRestorePlatformFile).not.toHaveBeenCalled();
+    expect(acquire).not.toHaveBeenCalled();
+  });
+
+  it('a restore must keep the name: a misplaced access.md may not arrive as roles.yaml', async () => {
+    const { svc, acquire, accessControl } = makeService(async () => true);
+
+    await expect(
+      svc.acquireLock(WS, BRANCH, `${KB}/roles.yaml`, USER, { platformRestore: { source: MISPLACED } }),
+    ).rejects.toBeInstanceOf(AccessDeniedError);
+    expect(accessControl.canRestorePlatformFile).not.toHaveBeenCalled();
+    expect(acquire).not.toHaveBeenCalled();
+  });
+
+  it('without the claim the exception is never even considered', async () => {
+    const { svc, acquire, accessControl } = makeService(async () => true);
+
+    await expect(
+      svc.acquireLock(WS, BRANCH, `${KB}/access.md`, USER),
+    ).rejects.toBeInstanceOf(AccessDeniedError);
+    expect(accessControl.canRestorePlatformFile).not.toHaveBeenCalled();
+    expect(acquire).not.toHaveBeenCalled();
+  });
+});

package/src/modules/workflow/__tests__/workflow.service.read-gate.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { AuthUser } from '@bevel-software/platform-shared';
+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 { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { FileLockService } from '../file-lock.service.js';
+import type { PendingCommitsService } from '../pending-commits.service.js';
+import { WorkflowEventBus } from '../event-bus.js';
+import { WorkflowService } from '../workflow.service.js';
+import type { Database } from '../../database/connection.js';
+import { AccessDeniedError } from '../../access-model/access-errors.js';
+import type { ChangeReadVerdict, IChangeReadGate } from '../../access-model/change-gate.js';
+
+/**
+ * The read-before-write gate sits in `acquireLock` next to the write gate:
+ * every non-coordination acquire asks it, on every branch, and a refusal
+ * means no lock. The gate's own verdicts are tested in
+ * `change-read-gate.test.ts`; here the question is WHEN it is asked and what
+ * its answer does.
+ */
+
+const USER: AuthUser = { id: 'user-1', email: 'alice@example.com', name: 'Alice' };
+const KB = 'knowledge-base';
+// One of the branches the backend test config marks protected.
+const PROTECTED = 'target-company-state';
+const DRAFT = 'alice/propose-plan';
+const WS = 'ws-1';
+
+function gateThat(verdict: ChangeReadVerdict) {
+  const judge = vi.fn(async () => verdict);
+  const assertMayChange = vi.fn(async (workspaceId: string, email: string, wsPath: string, kind: 'file' | 'dir') => {
+    const v = await judge(workspaceId, email, wsPath, kind);
+    if (v.allowed) return;
+    throw new AccessDeniedError({ path: wsPath, eligibleRoles: [], eligibleUsers: [], unreadable: v.unreadable });
+  });
+  const gate: IChangeReadGate = { judge, assertMayChange };
+  return { gate, assertMayChange };
+}
+
+function makeService(opts: {
+  gate?: IChangeReadGate;
+  writable?: boolean;
+  canRestorePlatformFile?: boolean;
+}) {
+  const acquire = vi.fn(async () => ({ acquired: true, lock: {} as never }));
+  const accessControl = {
+    canWriteBatchAtRef: vi.fn(async (_w: string, _r: string, _e: string, paths: string[]) =>
+      new Map(paths.map((p) => [p, opts.writable ?? true])),
+    ),
+    eligibleWritersAtRef: vi.fn(async () => ({ roles: [], users: [] })),
+    canRestorePlatformFile: vi.fn(async () => opts.canRestorePlatformFile ?? false),
+  } as unknown as IAccessControl;
+  const svc = new WorkflowService(
+    {} as unknown as Database,
+    {} as GitService,
+    {} as PullRequestService,
+    {} as IReviewWorkflowService,
+    {} as WorkspaceService,
+    accessControl,
+    { acquire, get: vi.fn(async () => null) } as unknown as FileLockService,
+    {} as PendingCommitsService,
+    KB,
+    opts.gate ?? gateThat({ allowed: true, via: 'readable' }).gate,
+    new WorkflowEventBus(),
+  );
+  return { svc, acquire, accessControl };
+}
+
+describe('WorkflowService cannot exist without the gate', () => {
+  it('refuses construction when none is given, whatever the compiler was told', () => {
+    expect(
+      () =>
+        new WorkflowService(
+          {} as unknown as Database,
+          {} as GitService,
+          {} as PullRequestService,
+          {} as IReviewWorkflowService,
+          {} as WorkspaceService,
+          {} as IAccessControl,
+          {} as FileLockService,
+          {} as PendingCommitsService,
+          KB,
+          undefined as unknown as IChangeReadGate,
+        ),
+    ).toThrow(/requires a read-before-write gate/);
+  });
+});
+
+describe('acquireLock asks the read-before-write gate', () => {
+  const PATH = `${KB}/KnowledgeBase/Sealed/brief.pdf`;
+
+  it('on a DRAFT branch, where no write gate runs: a refusal means no lock', async () => {
+    const { gate, assertMayChange } = gateThat({ allowed: false, unreadable: 'KnowledgeBase/Sealed' });
+    const { svc, acquire, accessControl } = makeService({ gate });
+
+    await expect(svc.acquireLock(WS, DRAFT, PATH, USER)).rejects.toBeInstanceOf(AccessDeniedError);
+    expect(assertMayChange).toHaveBeenCalledWith(WS, USER.email, PATH, 'file');
+    expect(acquire).not.toHaveBeenCalled();
+    // The write gate is still protected-branch only.
+    expect(accessControl.canWriteBatchAtRef).not.toHaveBeenCalled();
+  });
+
+  it('on a draft branch an allowed change takes the lock as before', async () => {
+    const { gate } = gateThat({ allowed: true, via: 'readable' });
+    const { svc, acquire } = makeService({ gate });
+
+    const result = await svc.acquireLock(WS, DRAFT, PATH, USER);
+    expect(result.acquired).toBe(true);
+    expect(acquire).toHaveBeenCalledOnce();
+  });
+
+  it('on a PROTECTED branch, after the write gate: a write grant without read is refused', async () => {
+    const { gate, assertMayChange } = gateThat({ allowed: false, unreadable: 'KnowledgeBase/Sealed' });
+    const { svc, acquire, accessControl } = makeService({ gate, writable: true });
+
+    await expect(svc.acquireLock(WS, PROTECTED, PATH, USER)).rejects.toBeInstanceOf(AccessDeniedError);
+    expect(accessControl.canWriteBatchAtRef).toHaveBeenCalledOnce();
+    expect(assertMayChange).toHaveBeenCalledOnce();
+    expect(acquire).not.toHaveBeenCalled();
+  });
+
+  it('the write gate refuses first, so the read gate is never asked about a path the caller may not write', async () => {
+    const { gate, assertMayChange } = gateThat({ allowed: true, via: 'readable' });
+    const { svc, acquire } = makeService({ gate, writable: false });
+
+    await expect(svc.acquireLock(WS, PROTECTED, PATH, USER)).rejects.toBeInstanceOf(AccessDeniedError);
+    expect(assertMayChange).not.toHaveBeenCalled();
+    expect(acquire).not.toHaveBeenCalled();
+  });
+
+  it('the refusal carries the unreadable place, so the route and the tools can say why', async () => {
+    const { gate } = gateThat({ allowed: false, unreadable: 'KnowledgeBase/Sealed' });
+    const { svc } = makeService({ gate });
+
+    const err = await svc.acquireLock(WS, DRAFT, PATH, USER).then(() => null, (e: unknown) => e);
+    expect((err as AccessDeniedError).access.unreadable).toBe('KnowledgeBase/Sealed');
+    expect((err as AccessDeniedError).message).toContain('You don\'t have read access to "KnowledgeBase/Sealed"');
+  });
+
+  it('a platform-file restore that the write gate let through is not asked — the rescue is for a denying destination', async () => {
+    const { gate, assertMayChange } = gateThat({ allowed: false, unreadable: '' });
+    const { svc, acquire } = makeService({ gate, writable: false, canRestorePlatformFile: true });
+
+    const result = await svc.acquireLock(WS, PROTECTED, `${KB}/access.md`, USER, {
+      platformRestore: { source: `${KB}/Misplaced/access.md` },
+    });
+    expect(result.acquired).toBe(true);
+    expect(assertMayChange).not.toHaveBeenCalled();
+    expect(acquire).toHaveBeenCalledOnce();
+  });
+
+  it('a coordination hold skips both gates: it grants no write and reads nothing', async () => {
+    const { gate, assertMayChange } = gateThat({ allowed: false, unreadable: '' });
+    const { svc, acquire, accessControl } = makeService({ gate });
+
+    const result = await svc.acquireLock(WS, PROTECTED, `${KB}/synced-groups.yaml`, USER, { coordination: true });
+    expect(result.acquired).toBe(true);
+    expect(assertMayChange).not.toHaveBeenCalled();
+    expect(accessControl.canWriteBatchAtRef).not.toHaveBeenCalled();
+    expect(acquire).toHaveBeenCalledOnce();
+  });
+
+  it('is asked with the canonical spelling of the path — the identity the lock is keyed by', async () => {
+    const { gate, assertMayChange } = gateThat({ allowed: true, via: 'readable' });
+    const { svc } = makeService({ gate });
+
+    await svc.acquireLock(WS, DRAFT, `./${KB}//KnowledgeBase/Open/a.md`, USER);
+    expect(assertMayChange).toHaveBeenCalledWith(WS, USER.email, `${KB}/KnowledgeBase/Open/a.md`, 'file');
+  });
+});

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

@@ -9,6 +9,7 @@ import { FileLockService } from '../file-lock.service.js';
 import { PendingCommitsService } from '../pending-commits.service.js';
 import { WorkflowEventBus } from '../event-bus.js';
 import { WorkflowService, syncConflictMessage } from '../workflow.service.js';
+import { openChangeGate } from '../../../__tests__/open-change-gate.js';
 import type { Database } from '../../database/connection.js';
 import {
   PullRebaseConflictError,
@@ -143,6 +144,7 @@ function makeFacade(
     locks,
     pending,
     'knowledge-base',
+    openChangeGate(),
     events,
   );
 }
@@ -181,6 +183,18 @@ describe('WorkflowService.releaseLock — new (enqueue, no synchronous commit)',
     expect(emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind)).toEqual(['lock-released']);
   });
 
+  it('answers hasQueuedCommit under the canonical identity, whatever spelling the caller has', async () => {
+    // `releaseLock` stores the row under the canonical path; a caller that
+    // asks with another spelling of the same file must find it, or it would
+    // re-arm a retry vehicle that already exists.
+    const pending = makePending();
+    (pending.hasLiveRowFor as Mock).mockResolvedValue(true);
+    const svc = makeFacade(makeGit(), makeFileLocks(USER.id), pending, events);
+
+    await expect(svc.hasQueuedCommit('ws-1', 'feat/x', './knowledge-base//x.md')).resolves.toBe(true);
+    expect(pending.hasLiveRowFor).toHaveBeenCalledWith('ws-1', 'feat/x', 'knowledge-base/x.md');
+  });
+
   it('throws lock-not-held when the caller does not hold the lock', async () => {
     const git = makeGit();
     const locks = makeFileLocks('someone-else');

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

@@ -11,6 +11,7 @@ import type { WorkflowEventBus } from '../event-bus.js';
 import type { Database } from '../../database/connection.js';
 import { WorkflowService, syncConflictMessage } from '../workflow.service.js';
 import { PullRebaseConflictError, RemoteBranchGoneError } from '../../../shared/domain-errors.js';
+import { openChangeGate } from '../../../__tests__/open-change-gate.js';
 
 /**
  * `syncWorkspaceFromRemote` — the per-branch step a remote sync drives.
@@ -37,6 +38,7 @@ function build(opts: { sync: () => Promise<RemoteSyncPullResult> }) {
     {} as FileLockService,
     pendingCommits,
     'knowledge-base',
+    openChangeGate(),
     events,
   );
   return { svc, git, prs, pendingCommits, emit: events.emit as ReturnType<typeof vi.fn> };
@@ -258,6 +260,7 @@ describe('WorkflowService.retireRemoteGoneClone', () => {
       {} as Database, git, {} as PullRequestService, {} as IReviewWorkflowService,
       workspaceService, {} as IAccessControl, {} as FileLockService, {} as PendingCommitsService,
       'knowledge-base',
+      openChangeGate(),
     );
     return { svc, git, workspaceService };
   }
@@ -325,6 +328,7 @@ describe('WorkflowService.retireRemoteGoneClone — what can bring the branch ba
       {} as Database, git, {} as PullRequestService, {} as IReviewWorkflowService,
       workspaceService, {} as IAccessControl, {} as FileLockService, {} as PendingCommitsService,
       'knowledge-base',
+      openChangeGate(),
     );
     expect(await svc.retireRemoteGoneClone('ali%2Fx')).toBe(false);
     expect(workspaceService.deleteWorkspace).not.toHaveBeenCalled();
@@ -353,6 +357,7 @@ describe('WorkflowService.retireRemoteGoneClone — what can bring the branch ba
       {} as Database, git, {} as PullRequestService, {} as IReviewWorkflowService,
       workspaceService, {} as IAccessControl, {} as FileLockService, {} as PendingCommitsService,
       'knowledge-base',
+      openChangeGate(),
     );
     // Retirement enters first; a createBranch for the same name arrives while
     // it holds the lock and must wait until the delete has happened — never

package/src/modules/workflow/__tests__/workflow.service.update-from-target.test.ts

@@ -0,0 +1,281 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { AuthUser, PullRequestDetail } from '@bevel-software/platform-shared';
+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 { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { FileLockService } from '../file-lock.service.js';
+import type { PendingCommitsService } from '../pending-commits.service.js';
+import type { Database } from '../../database/connection.js';
+import { WorkflowService } from '../workflow.service.js';
+import { openChangeGate } from '../../../__tests__/open-change-gate.js';
+import {
+  ChangeRequestConflictsError,
+  PullRebaseConflictError,
+  WorkflowDomainError,
+} from '../../../shared/domain-errors.js';
+
+/**
+ * Bringing a change request up to date: merge the target into the proposal
+ * branch on the server and push it. Only the author or someone who may apply
+ * the request may run it, and a conflicting merge must leave nothing behind —
+ * no commit, no push — and report the conflict so the dialog can hand the
+ * author's agent the prompt.
+ *
+ * The dialog now runs this by ITSELF on open, which makes the approval
+ * bookkeeping load-bearing: a merge nobody asked for must not void approvals
+ * over files it never touched. That holds for every caller of the route — the
+ * dialog, an agent, an older client — because it lives here and not in any
+ * of them.
+ */
+
+const USER: AuthUser = { id: 'u1', email: 'alice@example.com', name: 'Alice' };
+/** The proposal's head before the update, and the merge commit after it. */
+const HEAD = 'a'.repeat(40);
+const MERGED_HEAD = 'd'.repeat(40);
+const WS = encodeURIComponent('alice/deal');
+
+function detail(overrides: Partial<PullRequestDetail> = {}): PullRequestDetail {
+  return {
+    number: 7,
+    title: 'Deal terms',
+    state: 'open',
+    branch: 'alice/deal',
+    base: 'current-company-state',
+    behind: true,
+    viewerCanUpdate: true,
+    headSha: HEAD,
+    mergeBaseSha: 'c'.repeat(40),
+    ...overrides,
+  } as PullRequestDetail;
+}
+
+function harness(opts: {
+  first?: PullRequestDetail | null;
+  /** The published head of the proposal branch as resolved just before the merge. */
+  publishedHead?: string;
+  resolveError?: Error;
+  merge?: { kind: 'clean'; alreadyUpToDate: boolean } | { kind: 'conflicts'; paths: string[] };
+  pullError?: Error;
+  /** What the merge commit moved, as git would report it between the heads. */
+  changedPaths?: string[];
+  changedPathsError?: Error;
+  /** How many approval rows the carry-forward wrote. */
+  carried?: number;
+  /** The detail the extra read after a carry-forward answers with. */
+  withApprovals?: PullRequestDetail;
+}) {
+  const git = {
+    pull: opts.pullError
+      ? vi.fn().mockRejectedValue(opts.pullError)
+      : vi.fn().mockResolvedValue({ treeChanged: false }),
+    mergeFromOrigin: vi.fn().mockResolvedValue(opts.merge ?? { kind: 'clean', alreadyUpToDate: false }),
+    push: vi.fn().mockResolvedValue(undefined),
+    pathsChangedBetween: opts.changedPathsError
+      ? vi.fn().mockRejectedValue(opts.changedPathsError)
+      : vi.fn().mockResolvedValue(opts.changedPaths ?? []),
+    resolvePrShas: opts.resolveError
+      ? vi.fn().mockRejectedValue(opts.resolveError)
+      : vi.fn().mockResolvedValue({
+          baseSha: 'b'.repeat(40),
+          headSha: opts.publishedHead ?? HEAD,
+        }),
+  };
+  const refreshed = detail({ behind: false, headSha: MERGED_HEAD });
+  const getPrDetail = vi
+    .fn()
+    .mockResolvedValueOnce(opts.first === undefined ? detail() : opts.first)
+    .mockResolvedValueOnce(refreshed)
+    .mockResolvedValue(opts.withApprovals ?? refreshed);
+  const prs = { getPrDetail, invalidateDetailCache: vi.fn() };
+  const pendingCommits = { enqueueIfAbsent: vi.fn().mockResolvedValue(true) };
+  const reviewWorkflow = {
+    carryApprovalsForward: vi.fn().mockResolvedValue(opts.carried ?? 0),
+  };
+  const svc = new WorkflowService(
+    {} as unknown as Database,
+    git as unknown as GitService,
+    prs as unknown as PullRequestService,
+    reviewWorkflow as unknown as IReviewWorkflowService,
+    {} as unknown as WorkspaceService,
+    {} as unknown as IAccessControl,
+    {} as unknown as FileLockService,
+    pendingCommits as unknown as PendingCommitsService,
+    'knowledge-base',
+    openChangeGate(),
+  );
+  return { svc, git, prs, pendingCommits, reviewWorkflow, refreshed };
+}
+
+describe('WorkflowService.updateFromTarget', () => {
+  it('merges the target into the proposal, pushes, and returns the refreshed detail', async () => {
+    const h = harness({});
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
+
+    // The permission read is computed for THIS caller.
+    expect(h.prs.getPrDetail).toHaveBeenNthCalledWith(1, 7, {
+      fresh: true,
+      workspaceId: WS,
+      viewerEmail: USER.email,
+    });
+    expect(h.git.mergeFromOrigin).toHaveBeenCalledWith(WS, 'alice/deal', 'current-company-state', USER);
+    expect(h.git.push).toHaveBeenCalledWith(WS, USER);
+    expect(h.prs.invalidateDetailCache).toHaveBeenCalledWith(7);
+    expect(h.refreshed.behind).toBe(false);
+  });
+
+  it('refuses a viewer who is neither the author nor able to apply — nothing is merged', async () => {
+    const h = harness({ first: detail({ viewerCanUpdate: false }) });
+    const err = await h.svc.updateFromTarget(WS, USER, 7).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(WorkflowDomainError);
+    expect((err as WorkflowDomainError).status).toBe(403);
+    expect(h.git.mergeFromOrigin).not.toHaveBeenCalled();
+    expect(h.git.push).not.toHaveBeenCalled();
+  });
+
+  it('a conflicting merge reports the conflicted paths and pushes nothing', async () => {
+    const h = harness({ merge: { kind: 'conflicts', paths: ['Sales/Deal.md'] } });
+    const err = await h.svc.updateFromTarget(WS, USER, 7).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(ChangeRequestConflictsError);
+    expect((err as ChangeRequestConflictsError).status).toBe(409);
+    expect((err as ChangeRequestConflictsError).conflictedPaths).toEqual(['Sales/Deal.md']);
+    expect(h.git.push).not.toHaveBeenCalled();
+  });
+
+  it('refuses a request that is not open', async () => {
+    const h = harness({ first: detail({ state: 'merged' }) });
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).rejects.toThrow(/only open requests/);
+    expect(h.git.mergeFromOrigin).not.toHaveBeenCalled();
+  });
+
+  it('refuses a request that does not exist — nothing is merged', async () => {
+    const h = harness({ first: null });
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).rejects.toThrow(/not found/);
+    expect(h.git.mergeFromOrigin).not.toHaveBeenCalled();
+    expect(h.git.push).not.toHaveBeenCalled();
+  });
+
+  it('an already up-to-date merge pushes nothing but still returns the refreshed detail', async () => {
+    const h = harness({ merge: { kind: 'clean', alreadyUpToDate: true } });
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
+    expect(h.git.push).not.toHaveBeenCalled();
+    expect(h.prs.invalidateDetailCache).toHaveBeenCalledWith(7);
+  });
+
+  it('a rebase conflict refreshing the checkout queues recovery for the saves, then refuses', async () => {
+    const conflict = new PullRebaseConflictError('alice/deal', ['Sales/Deal.md'], 'rebase stopped');
+    const h = harness({ pullError: conflict });
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).rejects.toBe(conflict);
+    expect(h.pendingCommits.enqueueIfAbsent).toHaveBeenCalledWith(
+      expect.objectContaining({ workspaceId: WS, branch: 'alice/deal', path: 'Sales/Deal.md', authorEmail: USER.email }),
+    );
+    expect(h.git.mergeFromOrigin).not.toHaveBeenCalled();
+  });
+
+  it('a failed refresh of the proposal checkout stops the Update before any merge', async () => {
+    const h = harness({ pullError: new Error('fetch failed') });
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).rejects.toThrow(/fetch failed/);
+    expect(h.git.mergeFromOrigin).not.toHaveBeenCalled();
+    expect(h.git.push).not.toHaveBeenCalled();
+  });
+});
+
+describe('WorkflowService.updateFromTarget: the approvals the merge did not touch', () => {
+  it('carries them onto the new head, and re-reads the detail so the gate sees them', async () => {
+    const withApprovals = detail({ behind: false, headSha: MERGED_HEAD, mergeableInBevel: true });
+    const h = harness({
+      changedPaths: ['Sales/Deal.md'],
+      carried: 2,
+      withApprovals,
+    });
+
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(withApprovals);
+
+    // What moved is git's answer between the two heads — never a guess, and
+    // never the request's own three-dot diff against the target.
+    expect(h.git.pathsChangedBetween).toHaveBeenCalledWith(WS, HEAD, MERGED_HEAD);
+    expect(h.reviewWorkflow.carryApprovalsForward).toHaveBeenCalledWith(
+      7,
+      HEAD,
+      MERGED_HEAD,
+      ['Sales/Deal.md'],
+    );
+    // The first refreshed detail was assembled before the rows existed, so it
+    // is not the one that goes back.
+    expect(h.prs.getPrDetail).toHaveBeenCalledTimes(3);
+  });
+
+  it('does not re-read the detail when nothing carried', async () => {
+    const h = harness({ changedPaths: ['Sales/Deal.md'], carried: 0 });
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
+    expect(h.reviewWorkflow.carryApprovalsForward).toHaveBeenCalledTimes(1);
+    expect(h.prs.getPrDetail).toHaveBeenCalledTimes(2);
+  });
+
+  it('touches nothing when the merge had nothing to do', async () => {
+    const h = harness({ merge: { kind: 'clean', alreadyUpToDate: true } });
+    await h.svc.updateFromTarget(WS, USER, 7);
+    expect(h.git.pathsChangedBetween).not.toHaveBeenCalled();
+    expect(h.reviewWorkflow.carryApprovalsForward).not.toHaveBeenCalled();
+  });
+
+  it('touches nothing when the merge conflicted — the rows describe a head that still stands', async () => {
+    const h = harness({ merge: { kind: 'conflicts', paths: ['Sales/Deal.md'] } });
+    await h.svc.updateFromTarget(WS, USER, 7).catch(() => undefined);
+    expect(h.git.pathsChangedBetween).not.toHaveBeenCalled();
+    expect(h.reviewWorkflow.carryApprovalsForward).not.toHaveBeenCalled();
+  });
+
+  it('carries them from the head the branch is actually ON, not the one the detail read', async () => {
+    // Somebody pushed to the proposal branch between the detail read and the
+    // pull — an agent, or the author from another client. The approvals a
+    // reviewer made in that window are pinned to THAT head; carrying forward
+    // from the sha the stale detail reported would find no rows and void every
+    // approval the merge never touched.
+    const PUSHED = 'e'.repeat(40);
+    const h = harness({ publishedHead: PUSHED, changedPaths: ['Sales/Deal.md'], carried: 1 });
+
+    await h.svc.updateFromTarget(WS, USER, 7);
+
+    // Resolved after the pull and before the merge, from the branch itself.
+    expect(h.git.resolvePrShas).toHaveBeenCalledWith(WS, 'current-company-state', 'alice/deal');
+    expect(h.git.pathsChangedBetween).toHaveBeenCalledWith(WS, PUSHED, MERGED_HEAD);
+    expect(h.reviewWorkflow.carryApprovalsForward).toHaveBeenCalledWith(7, PUSHED, MERGED_HEAD, [
+      'Sales/Deal.md',
+    ]);
+  });
+
+  it('falls back to the head the detail reported when that head cannot be resolved', async () => {
+    // Bookkeeping never costs the update: an unresolvable ref leaves the
+    // carry-forward working off the detail's head, exactly as it did before.
+    const h = harness({ resolveError: new Error('no such ref'), carried: 1 });
+    await h.svc.updateFromTarget(WS, USER, 7);
+    expect(h.git.push).toHaveBeenCalledWith(WS, USER);
+    expect(h.reviewWorkflow.carryApprovalsForward).toHaveBeenCalledWith(7, HEAD, MERGED_HEAD, []);
+  });
+
+  it('carries nothing when there is no head to compare at all', async () => {
+    // The resolve failed AND the detail carries no head either — a degraded
+    // read, not a merge outcome. There is no pair of shas to diff, so the
+    // bookkeeping is skipped rather than attempted with an empty one (which
+    // `carryApprovalsForward` would refuse outright).
+    const h = harness({
+      first: detail({ headSha: '' }),
+      resolveError: new Error('no such ref'),
+      carried: 1,
+    });
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
+    expect(h.git.push).toHaveBeenCalledWith(WS, USER);
+    expect(h.git.pathsChangedBetween).not.toHaveBeenCalled();
+    expect(h.reviewWorkflow.carryApprovalsForward).not.toHaveBeenCalled();
+  });
+
+  it('still returns the up-to-date request when the bookkeeping itself fails', async () => {
+    // A request that IS up to date is worth more than the carry-forward: the
+    // approvals simply go stale, exactly as they did before this existed.
+    const h = harness({ changedPathsError: new Error('git exploded') });
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
+    expect(h.reviewWorkflow.carryApprovalsForward).not.toHaveBeenCalled();
+  });
+});