@bevel-software/platform-core-backend 0.1.0

package/src/modules/workflow/review-workflow/__tests__/cancel-pr.test.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import { ReviewWorkflowService } from '../review-workflow.service.js';
+import type { Database } from '../../../database/connection.js';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import type { GitService } from '../../git/git.service.js';
+import type { IAccessControl } from '../../../access/access-control.interface.js';
+import { hashEmail } from '../../../../shared/hash-email.js';
+import { WorkflowValidationError } from '../../workflow.errors.js';
+
+// Cancel is now a DB state flip (no `gh`): `update(change_requests) … WHERE
+// number = ? AND state = 'open'`. This spy stands in for the update's
+// `.returning()` — a non-empty array means the row was open and got closed.
+const updateReturning = vi.fn(async () => [{ id: 'cr-1' }] as { id: string }[]);
+// The re-read used only when the update matched zero rows (a race). Default to
+// a merged row so that path yields already-applied.
+const reReadState = { current: 'merged' as 'merged' | 'closed' };
+
+function makeDb(): Database {
+  return {
+    update: () => ({ set: () => ({ where: () => ({ returning: updateReturning }) }) }),
+    select: () => ({
+      from: () => ({ where: () => ({ limit: async () => [{ state: reReadState.current }] }) }),
+    }),
+  } as unknown as Database;
+}
+
+const USER: AuthUser = { id: 'u1', email: 'juan@bevel.software', name: 'Juan' };
+const OTHER_AUTHOR_HASH = hashEmail('someone-else@bevel.software');
+
+function makeAccessControl(adminEmails: string[] = []): IAccessControl {
+  const set = new Set(adminEmails.map((e) => e.toLowerCase()));
+  return {
+    canWrite: async () => false,
+    canWriteBatch: async () => new Map(),
+    canRead: async () => true,
+    canReadBatch: async () => new Map(),
+    eligibleReaders: async () => ({ restricted: false, roles: [], users: [] }),
+    canReadAtRef: async () => null,
+    canDownload: async () => false,
+    canOwner: async () => false,
+    eligibleOwners: async () => ({ roles: [], users: [] }),
+    eligibleDownloaders: async () => ({ roles: [], users: [] }),
+    eligibleWriters: async () => ({ roles: [], users: [] }),
+    eligibleWriterEmails: async () => new Map(),
+    eligibleOwnerEmails: async () => new Map(),
+    grantSources: async () => ({}),
+    invalidate: () => {},
+    canWriteAtRef: async (_ws, _ref, email) => {
+      return set.has(email.trim().toLowerCase());
+    },
+    canWriteBatchAtRef: async () => null,
+    eligibleWritersAtRef: async () => null,
+    eligibleWritersForPathsAtRef: async () => null,
+    findEmailByHash: async () => null,
+    kbPrincipals: async () => ({ groups: [], people: [] }),
+    validateRolesYaml: () => ({ ok: true }),
+    referencesToRole: async () => [],
+  };
+}
+
+function makeService(accessControl: IAccessControl): ReviewWorkflowService {
+  // `ensureRemotesFetched` is best-effort (catches errors); the DB stub above
+  // stands in for the state-flip update + the race re-read.
+  const workspace = { ensureRemotesFetched: async () => undefined } as unknown as WorkspaceService;
+  return new ReviewWorkflowService(makeDb(), accessControl, workspace, {} as unknown as GitService);
+}
+
+describe('ReviewWorkflowService.cancelPr', () => {
+  beforeEach(() => {
+    updateReturning.mockClear();
+    updateReturning.mockResolvedValue([{ id: 'cr-1' }]);
+    reReadState.current = 'merged';
+  });
+
+  it('lets the PR author cancel (admin check skipped)', async () => {
+    const svc = makeService(makeAccessControl([]));
+    const result = await svc.cancelPr(
+      42, USER, 'open', hashEmail(USER.email), 'current-company-state', 'ws-1',
+    );
+    expect(result.prNumber).toBe(42);
+    expect(typeof result.cancelledAt).toBe('string');
+    expect(new Date(result.cancelledAt).toString()).not.toBe('Invalid Date');
+    // The row was flipped via the guarded update (state='open' precondition).
+    expect(updateReturning).toHaveBeenCalledTimes(1);
+  });
+
+  it('lets a base-branch admin cancel someone else’s PR', async () => {
+    const svc = makeService(makeAccessControl([USER.email]));
+    const result = await svc.cancelPr(
+      7, USER, 'open', OTHER_AUTHOR_HASH, 'current-company-state', 'ws-1',
+    );
+    expect(result.prNumber).toBe(7);
+  });
+
+  it('refuses when caller is neither author nor admin (403)', async () => {
+    const svc = makeService(makeAccessControl([])); // no admins
+    await expect(
+      svc.cancelPr(7, USER, 'open', OTHER_AUTHOR_HASH, 'current-company-state', 'ws-1'),
+    ).rejects.toMatchObject({
+      name: 'CancelAuthError',
+      status: 403,
+      message: expect.stringMatching(/only the author or an admin/i),
+    });
+    expect(updateReturning).not.toHaveBeenCalled();
+  });
+
+  it('refuses a merged PR with 422 already-applied — no state change', async () => {
+    const svc = makeService(makeAccessControl([USER.email]));
+    await expect(
+      svc.cancelPr(7, USER, 'merged', hashEmail(USER.email), 'current-company-state', 'ws-1'),
+    ).rejects.toMatchObject({
+      name: 'CancelStateError',
+      status: 422,
+      message: 'This change request was already applied.',
+    });
+    expect(updateReturning).not.toHaveBeenCalled();
+  });
+
+  it('refuses an already-closed PR with 422 already-cancelled', async () => {
+    const svc = makeService(makeAccessControl([USER.email]));
+    await expect(
+      svc.cancelPr(7, USER, 'closed', hashEmail(USER.email), 'current-company-state', 'ws-1'),
+    ).rejects.toMatchObject({
+      name: 'CancelStateError',
+      status: 422,
+      message: 'This change request is already cancelled.',
+    });
+    expect(updateReturning).not.toHaveBeenCalled();
+  });
+
+  it('maps a lost race (update matched 0 rows, row now merged) to already-applied', async () => {
+    updateReturning.mockResolvedValue([]); // the guarded update caught nothing
+    reReadState.current = 'merged';
+    const svc = makeService(makeAccessControl([USER.email]));
+    await expect(
+      svc.cancelPr(42, USER, 'open', hashEmail(USER.email), 'current-company-state', 'ws-1'),
+    ).rejects.toMatchObject({ name: 'CancelStateError', message: 'This change request was already applied.' });
+  });
+
+  it('rejects invalid PR numbers', async () => {
+    const svc = makeService(makeAccessControl([USER.email]));
+    for (const bad of [0, -1, 1.5, Number.NaN]) {
+      await expect(
+        svc.cancelPr(bad, USER, 'open', null, 'current-company-state', 'ws-1'),
+      ).rejects.toBeInstanceOf(WorkflowValidationError);
+    }
+  });
+
+  it('rejects empty workspaceId / baseBranch', async () => {
+    const svc = makeService(makeAccessControl([USER.email]));
+    await expect(
+      svc.cancelPr(42, USER, 'open', null, '', 'ws-1'),
+    ).rejects.toBeInstanceOf(WorkflowValidationError);
+    await expect(
+      svc.cancelPr(42, USER, 'open', null, 'current-company-state', ''),
+    ).rejects.toBeInstanceOf(WorkflowValidationError);
+  });
+
+  it('skips the admin lookup when the author check matches', async () => {
+    // canWriteAtRef would throw — if the service calls it for a matching author,
+    // the test fails. Guards against an authz-check ordering regression.
+    const throwingAccess: IAccessControl = {
+      ...makeAccessControl([]),
+      canWriteAtRef: async () => {
+        throw new Error('admin check should not run for matching author');
+      },
+    };
+    const svc = makeService(throwingAccess);
+    await expect(
+      svc.cancelPr(
+        42, USER, 'open', hashEmail(USER.email), 'current-company-state', 'ws-1',
+      ),
+    ).resolves.toMatchObject({ prNumber: 42 });
+  });
+});

package/src/modules/workflow/review-workflow/__tests__/merge-gate.test.ts

@@ -0,0 +1,258 @@
+import { describe, it, expect } from 'vitest';
+import type { FileApprovalEntry, FileApprovalState, PullRequestState } from '@bevel-software/platform-shared';
+import { ReviewWorkflowService } from '../review-workflow.service.js';
+
+function makeService(): ReviewWorkflowService {
+  // evaluateMergeGate is pure — it never touches the DB, access service, or
+  // workspace. Constructing with `undefined as any` for unused deps keeps the
+  // test focused on the gate logic and avoids pulling in fixture scaffolding.
+  return new ReviewWorkflowService(undefined as any, undefined as any, undefined as any, undefined as any);
+}
+
+const ADMIN_ELIGIBLE = {
+  roles: ['Admin'],
+  users: [] as { name: string; email: string }[],
+};
+const EMPTY_ELIGIBLE = {
+  roles: [] as string[],
+  users: [] as { name: string; email: string }[],
+};
+
+// Spread-after-defaults so explicit empty eligibility (e.g. ownerless legacy
+// file) passes through instead of being overwritten by the default.
+function approval(overrides: Partial<FileApprovalState>): FileApprovalState {
+  return {
+    path: 'Knowledge/Foo.md',
+    eligibleApprovers: ADMIN_ELIGIBLE,
+    approvedBy: [],
+    isApproved: false,
+    viewerCanApprove: false,
+    ...overrides,
+  };
+}
+
+function entry(overrides: Partial<FileApprovalEntry>): FileApprovalEntry {
+  return {
+    email: 'alice@bevel.software',
+    name: 'Alice',
+    approvedAt: '2026-04-20T12:00:00Z',
+    isStale: false,
+    isSelfApproval: false,
+    ...overrides,
+  };
+}
+
+describe('evaluateMergeGate', () => {
+  const svc = makeService();
+
+  it('passes cleanly when every gate-relevant file has a non-stale approval', () => {
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'open',
+      approvals: [
+        approval({ path: 'A.md', isApproved: true, approvedBy: [entry({})] }),
+        approval({ path: 'B.md', isApproved: true, approvedBy: [entry({})] }),
+      ],
+    });
+    expect(result).toEqual({ mergeable: true, reasons: [], warnings: [] });
+  });
+
+  it('rejects merged PRs as a hard block', () => {
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'merged' as PullRequestState,
+      approvals: [approval({ isApproved: true })],
+    });
+    expect(result.mergeable).toBe(false);
+    expect(result.reasons[0]).toMatch(/already been merged/i);
+  });
+
+  it('rejects closed PRs as a hard block', () => {
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'closed',
+      approvals: [approval({ isApproved: true })],
+    });
+    expect(result.mergeable).toBe(false);
+    expect(result.reasons[0]).toMatch(/closed/i);
+  });
+
+  it('rejects PRs with no files to approve as a hard block', () => {
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'open',
+      approvals: [],
+    });
+    expect(result.mergeable).toBe(false);
+    expect(result.reasons[0]).toMatch(/no file changes/i);
+  });
+
+  it('ignores md files with no eligible approvers — no warning, no block', () => {
+    // Files outside the access-controlled surface (no roles/users grant
+    // write) are not part of the gate.
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'open',
+      approvals: [
+        approval({ path: 'A.md', isApproved: true, approvedBy: [entry({})] }),
+        approval({ path: 'Legacy.md', eligibleApprovers: EMPTY_ELIGIBLE }),
+      ],
+    });
+    expect(result.mergeable).toBe(true);
+    expect(result.reasons).toEqual([]);
+    expect(result.warnings).toEqual([]);
+  });
+
+  it('ignores non-md files regardless of eligibility', () => {
+    // TypeScript sources, JSON, images etc. don't participate in the gate.
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'open',
+      approvals: [
+        approval({ path: 'src/foo.ts', eligibleApprovers: ADMIN_ELIGIBLE }),
+        approval({ path: 'assets/logo.png', eligibleApprovers: EMPTY_ELIGIBLE }),
+      ],
+    });
+    expect(result.mergeable).toBe(true);
+    expect(result.reasons).toEqual([]);
+    expect(result.warnings).toEqual([]);
+  });
+
+  it('treats unapproved md-with-eligible-approvers as a warning, not a hard block', () => {
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'open',
+      approvals: [
+        approval({
+          path: 'B.md',
+          eligibleApprovers: {
+            roles: ['Product Manager'],
+            users: [{ name: 'Bob', email: 'bob@bevel.software' }],
+          },
+          approvedBy: [],
+        }),
+      ],
+    });
+    expect(result.mergeable).toBe(true);
+    expect(result.reasons).toEqual([]);
+    expect(result.warnings).toEqual([
+      'Waiting on approval for B.md from Product Manager; Bob <bob@bevel.software>.',
+    ]);
+  });
+
+  it('distinguishes stale approvals from never-approved in warnings', () => {
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'open',
+      approvals: [
+        approval({
+          path: 'A.md',
+          eligibleApprovers: ADMIN_ELIGIBLE,
+          approvedBy: [entry({ email: 'alice@bevel.software', isStale: true })],
+        }),
+        approval({
+          path: 'B.md',
+          eligibleApprovers: ADMIN_ELIGIBLE,
+          approvedBy: [],
+        }),
+      ],
+    });
+    expect(result.mergeable).toBe(true);
+    expect(result.warnings).toContain('Admin need to re-approve A.md after the latest push.');
+    expect(result.warnings).toContain('Waiting on approval for B.md from Admin.');
+  });
+
+  it('surfaces only the hard block when the PR is closed, not soft warnings', () => {
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'closed',
+      approvals: [
+        approval({ path: 'A.md', eligibleApprovers: EMPTY_ELIGIBLE }),
+        approval({ path: 'B.md' }),
+      ],
+    });
+    expect(result.mergeable).toBe(false);
+    expect(result.reasons[0]).toMatch(/closed/i);
+  });
+
+  it('is case-insensitive on the .md extension check', () => {
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'open',
+      approvals: [
+        approval({
+          path: 'Knowledge/FOO.MD',
+          eligibleApprovers: ADMIN_ELIGIBLE,
+          approvedBy: [],
+        }),
+      ],
+    });
+    expect(result.warnings).toContain('Waiting on approval for Knowledge/FOO.MD from Admin.');
+  });
+
+  // Regression: roles.yaml is the file that decides Admin membership, but it
+  // isn't a `.md` KB node — so before this gate it slipped through with zero
+  // warnings, and a roles.yaml-only change request could merge into a protected
+  // branch with no approval and no admin check, letting its author self-promote
+  // to Admin. The gate must bind roles.yaml (and access.md) like an md node.
+  it('treats an unapproved roles.yaml change as a warning (privilege-escalation guard)', () => {
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'open',
+      approvals: [
+        approval({ path: 'roles.yaml', eligibleApprovers: ADMIN_ELIGIBLE, approvedBy: [] }),
+      ],
+    });
+    // mergeable stays true (it's a soft warning, bypassable only by an admin in
+    // mergePr) — the point is that the warning EXISTS, so a non-admin merge of a
+    // roles.yaml-only PR is no longer silently waved through.
+    expect(result.warnings).toContain('Waiting on approval for roles.yaml from Admin.');
+    // Pin the non-blocking contract: this PR's guarantee is "warn, don't block".
+    // If evaluateMergeGate ever starts adding blocking reasons or flipping
+    // mergeable to false for an access-config file, these must fail.
+    expect(result.mergeable).toBe(true);
+    expect(result.reasons).toEqual([]);
+  });
+
+  it('treats an unapproved access.md change as a warning, at root and nested', () => {
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'open',
+      approvals: [
+        approval({ path: 'access.md', eligibleApprovers: ADMIN_ELIGIBLE, approvedBy: [] }),
+        approval({ path: 'Knowledge/Sales/access.md', eligibleApprovers: ADMIN_ELIGIBLE, approvedBy: [] }),
+      ],
+    });
+    expect(result.warnings).toContain('Waiting on approval for access.md from Admin.');
+    expect(result.warnings).toContain('Waiting on approval for Knowledge/Sales/access.md from Admin.');
+    // Same non-blocking contract as roles.yaml: warn, never block.
+    expect(result.mergeable).toBe(true);
+    expect(result.reasons).toEqual([]);
+  });
+
+  it('a roles.yaml change WITH a non-stale eligible approval passes cleanly', () => {
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'open',
+      approvals: [
+        approval({ path: 'roles.yaml', isApproved: true, approvedBy: [entry({})] }),
+      ],
+    });
+    expect(result).toEqual({ mergeable: true, reasons: [], warnings: [] });
+  });
+
+  it('does not gate roles.yaml when no one is eligible to approve it', () => {
+    // Mirrors the md path: a config file with no eligible approver can't be
+    // approved, so it neither warns nor blocks (the merge-gate would otherwise
+    // deadlock on an un-approvable file).
+    const result = svc.evaluateMergeGate({
+      prNumber: 1,
+      state: 'open',
+      approvals: [
+        approval({ path: 'roles.yaml', eligibleApprovers: EMPTY_ELIGIBLE }),
+      ],
+    });
+    expect(result.mergeable).toBe(true);
+    expect(result.warnings).toEqual([]);
+  });
+});

package/src/modules/workflow/review-workflow/review-workflow.interface.ts

@@ -0,0 +1,199 @@
+import type {
+  AuthUser,
+  CancelPrResult,
+  FileApprovalState,
+  MergePrResult,
+  PostPrCommentInput,
+  PrReviewComment,
+  PullRequestFile,
+  PullRequestState,
+} from '@bevel-software/platform-shared';
+
+export interface MergeGateInput {
+  prNumber: number;
+  state: PullRequestState;
+  approvals: FileApprovalState[];
+}
+
+export interface MergeGateResult {
+  /** False only on hard blocks (PR closed/merged, zero files). Warnings do NOT flip this false. */
+  mergeable: boolean;
+  /** Hard-block reasons — merge cannot proceed until these resolve. */
+  reasons: string[];
+  /**
+   * Soft warnings — md files with an owner who hasn't approved (or whose
+   * approval is stale). Merge proceeds only when the caller explicitly opts
+   * into bypass; the frontend surfaces these in a confirm dialog.
+   */
+  warnings: string[];
+}
+
+/**
+ * Owns the Bevel-side review state for a PR: comments (phase 2), per-file
+ * approvals (phase 3), and the merge gate (phase 4). GitHub stays authoritative
+ * for the diff + eventual merge; everything in this interface is in-app state
+ * the team uses to decide whether the merge should fire.
+ */
+export interface IReviewWorkflowService {
+  /** List all comments for a PR, oldest first. */
+  listComments(prNumber: number): Promise<PrReviewComment[]>;
+
+  /** Post a new comment. Shape of `input` decides whether it's general, file-level, or inline. */
+  postComment(
+    prNumber: number,
+    user: AuthUser,
+    input: PostPrCommentInput,
+    headSha: string,
+  ): Promise<PrReviewComment>;
+
+  /**
+   * Edit an existing comment. Only the original author may edit — 403 otherwise.
+   * `prNumber` scopes the lookup so a caller can't touch a comment from a
+   * different PR via a guessed id; the comment must belong to this PR.
+   */
+  editComment(
+    commentId: string,
+    prNumber: number,
+    user: AuthUser,
+    body: string,
+  ): Promise<PrReviewComment>;
+
+  /**
+   * Delete a comment. Only the original author may delete — 403 otherwise.
+   * Replies are preserved (orphaned to the thread root). `prNumber` scopes the
+   * lookup so a caller can't cross PRs via a guessed id.
+   */
+  deleteComment(commentId: string, prNumber: number, user: AuthUser): Promise<void>;
+
+  /**
+   * Compose the per-file approval state for a PR detail response. Resolves
+   * the eligible approver set against **the PR's base branch on origin**
+   * (e.g. `origin/current-company-state`), then joins approval rows from
+   * the DB, marking stale approvals and flagging self-approvals.
+   *
+   * Why base, not head: the PR's head can carry arbitrary edits to
+   * `roles.yaml` or `access.md`, so resolving against head would let a PR
+   * author grant themselves approval rights by editing access config in
+   * their own branch. The base is fast-forward-only (protected branches
+   * are gated by their own PR review), so it's the authoritative source
+   * for "who has write access to this path right now."
+   *
+   * `workspaceId` is optional. When omitted (or when the access lookup
+   * fails — e.g. the workspace hasn't fetched `origin/<base>` yet), the
+   * result is still one `FileApprovalState` per input file but with empty
+   * eligibility. Downstream the merge gate treats empty-eligibility entries
+   * as silent (outside the gate), so a missing workspace degrades to
+   * "PR detail renders, approval gating unavailable" rather than a hard
+   * failure.
+   */
+  getApprovalStates(
+    prNumber: number,
+    files: PullRequestFile[],
+    headSha: string,
+    baseBranch: string,
+    prAuthorIdHash: string | null,
+    workspaceId?: string,
+    /**
+     * Email of the user viewing the PR. When provided, each returned state
+     * carries `viewerCanApprove` populated from the access tree at
+     * `origin/<baseBranch>`. Omitted (or absent workspace) → `viewerCanApprove`
+     * defaults to `false` everywhere.
+     */
+    viewerEmail?: string,
+  ): Promise<FileApprovalState[]>;
+
+  /**
+   * Approve one file. Requires the caller to hold `write` on the path per
+   * the access tree on `origin/<baseBranch>` (403 otherwise). Idempotent —
+   * approving twice on the same headSha is a no-op. Returns the fresh
+   * composite state for all files.
+   */
+  approveFile(
+    prNumber: number,
+    path: string,
+    user: AuthUser,
+    files: PullRequestFile[],
+    headSha: string,
+    baseBranch: string,
+    prAuthorIdHash: string | null,
+    workspaceId: string,
+  ): Promise<FileApprovalState[]>;
+
+  /**
+   * Revoke the caller's own approval on one file. Non-author users cannot
+   * revoke someone else's approval (403). Idempotent when no matching
+   * approval exists.
+   */
+  unapproveFile(
+    prNumber: number,
+    path: string,
+    user: AuthUser,
+    files: PullRequestFile[],
+    headSha: string,
+    baseBranch: string,
+    prAuthorIdHash: string | null,
+    workspaceId: string,
+  ): Promise<FileApprovalState[]>;
+
+  /**
+   * Pure derivation of the merge gate from PR state + per-file approvals.
+   * Exposed as a method (not a free function) so the HTTP response and the
+   * merge route re-validate via the same code path.
+   */
+  evaluateMergeGate(input: MergeGateInput): MergeGateResult;
+
+  /**
+   * Execute the merge via a local `git merge --no-ff` on the base branch's
+   * workspace, pushed to origin (provider-agnostic — no PR API). Re-validates
+   * the gate server-side first (don't trust the caller's cached
+   * `mergeableInBevel`), writes a row to `pr_merge_log` bracketing the attempt,
+   * flips the `change_requests` row to `merged`, and tags the merge commit with
+   * the real triggerer so the audit trail lives on the commit. Conflicts throw
+   * `ChangeRequestConflictsError` (409) with the conflicting paths.
+   *
+   * **Merge authority invariant**: this method is the *only* backend code path
+   * that lands a change request on a protected branch.
+   */
+  mergePr(
+    prNumber: number,
+    user: AuthUser,
+    /** Fresh detail fetched within the request — used for the gate and the head SHA. */
+    headSha: string,
+    approvals: FileApprovalState[],
+    state: PullRequestState,
+    prTitle: string,
+    /** The PR's base branch — used to resolve admin status at `origin/<base>` for bypass. */
+    baseBranch: string,
+    /** Workspace clone — used for the access-tree lookup that gates bypass. */
+    workspaceId: string,
+    /**
+     * When true, proceed even if soft warnings (unapproved md-with-owner files)
+     * exist. Hard blocks are refused regardless. The bypassed warnings are
+     * recorded in the merge commit body for audit. Bypass requires admin
+     * write access at `origin/<baseBranch>` (i.e. write on `roles.yaml`) —
+     * non-admins get a 403 even when warnings would otherwise be skippable.
+     */
+    opts?: { bypass?: boolean },
+  ): Promise<MergePrResult>;
+
+  /**
+   * Close a change request without merging — flips the `change_requests` row to
+   * `closed` (guarded on `state = 'open'`). Authorized when the caller is the PR
+   * author (hash-matched against `authorIdHash`) OR an admin on the base branch
+   * (write on `roles.yaml` at `origin/<baseBranch>` — the same predicate
+   * `mergePr`'s bypass uses). Refused with 422 when the CR is already merged or
+   * closed. The source branch is left intact.
+   */
+  cancelPr(
+    prNumber: number,
+    user: AuthUser,
+    /** The PR's current state per a fresh `getPrDetail` fetch. */
+    state: PullRequestState,
+    /** Hash of the PR-author email from the body marker — null when absent. */
+    authorIdHash: string | null,
+    /** The PR's base branch — used to resolve admin authority at `origin/<base>`. */
+    baseBranch: string,
+    /** Workspace clone — used for the access-tree lookup that gates admin authority. */
+    workspaceId: string,
+  ): Promise<CancelPrResult>;
+}