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

package/src/modules/plugins/__tests__/join-proposals.test.ts

@@ -2,8 +2,13 @@ import { describe, it, expect } from 'vitest';
 import { pendingProposals } from '../join-proposals.js';
 
 /**
- * What a join branch proposes, relative to the default branch. This diff IS
- * the request's lifecycle: non-empty ⇒ open, empty ⇒ settled and closed.
+ * What a request's branch proposes, relative to the default branch. This diff
+ * IS the request's lifecycle: non-empty ⇒ open, empty ⇒ settled and closed,
+ * null ⇒ the branch could not be read and nothing may be concluded.
+ *
+ * Which grammar reads it follows the ITEM, and the second describe below is
+ * why: a folder's rules are block lists in an access.md body, a file's are its
+ * own frontmatter, where a single grant is a scalar.
  */
 const PATH = 'Plugins/GTM/access.md';
 
@@ -17,7 +22,7 @@ describe('pendingProposals', () => {
     const branch = base(
       'read:\n  - GTM Team\n  - Olga Ivanova <olga@bevel.software>\n  - Ali Baba <ali@bevel.software>\n',
     );
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([
       {
         verb: 'read',
         id: 'user:ali@bevel.software',
@@ -31,7 +36,7 @@ describe('pendingProposals', () => {
     // A branch asking for `write` must be visible AS a write request rather
     // than hiding behind "asked to join".
     const branch = base('read:\n  - GTM Team\n  - Olga Ivanova <olga@bevel.software>\nwrite:\n  - Finance Team\n');
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([
       {
         verb: 'write',
         id: 'role:finance team',
@@ -42,12 +47,12 @@ describe('pendingProposals', () => {
   });
 
   it('is EMPTY when the branch is identical — the settled state', () => {
-    expect(pendingProposals(DEFAULT_MD, DEFAULT_MD, PATH)).toEqual([]);
+    expect(pendingProposals(DEFAULT_MD, DEFAULT_MD, PATH, 'folder')).toEqual([]);
   });
 
   it('is EMPTY when the branch grants a SUBSET (its proposal already landed)', () => {
     const branch = base('read:\n  - Olga Ivanova <olga@bevel.software>\n');
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([]);
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([]);
   });
 
   it('ignores a REMOVAL — a branch that drops one grant but keeps the rest proposes nothing', () => {
@@ -55,36 +60,38 @@ describe('pendingProposals', () => {
     // ordinary change request in the review UI. (Distinct from the subset
     // case above: here GTM Team survives and only Olga is dropped.)
     const branch = base('read:\n  - GTM Team\n');
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([]);
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([]);
   });
 
   it('ignores a `deny` entry — a denial is not something to accept', () => {
     const branch = base(
       'read:\n  - GTM Team\n  - Olga Ivanova <olga@bevel.software>\n  - deny Ali Baba <ali@bevel.software>\n',
     );
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([]);
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([]);
   });
 
   it('matches principals canonically (case-insensitive email, canonical role)', () => {
     const branch = base('read:\n  - gtm team\n  - Olga I <OLGA@Bevel.Software>\n');
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([]);
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([]);
   });
 
-  it('treats a MALFORMED branch file as proposing nothing (fail-closed)', () => {
-    // A body naming a verb but shaped wrong is a hard parse error; there is
-    // nothing to offer a manager, and merging is not how this settles anyway.
-    expect(pendingProposals(base('read: GTM Team\n'), DEFAULT_MD, PATH)).toEqual([]);
+  it('says NOTHING about a malformed branch file — not "nothing to propose"', () => {
+    // A body naming a verb but shaped wrong is a hard parse error. The
+    // difference matters because an empty answer CLOSES the request: it has
+    // to mean the branch asks for nothing more, never that it would not say.
+    expect(pendingProposals(base('read: GTM Team\n'), DEFAULT_MD, PATH, 'folder')).toBeNull();
   });
 
-  it('treats a missing branch file as proposing nothing', () => {
-    expect(pendingProposals(null, DEFAULT_MD, PATH)).toEqual([]);
+  it('says NOTHING about a missing branch file either', () => {
+    expect(pendingProposals(null, DEFAULT_MD, PATH, 'folder')).toBeNull();
   });
 
   it('surfaces every branch grant when the DEFAULT file is missing or unreadable', () => {
-    // The safe direction: show the manager proposals to consider rather than
-    // silently swallowing them against an unreadable baseline.
+    // The safe direction on THAT side: show the editor proposals to consider
+    // rather than swallowing them against a baseline nobody could read.
     const branch = base('read:\n  - Ali Baba <ali@bevel.software>\n');
-    expect(pendingProposals(branch, null, PATH)).toHaveLength(1);
+    expect(pendingProposals(branch, null, PATH, 'folder')).toHaveLength(1);
+    expect(pendingProposals(branch, base('read: broken\n'), PATH, 'folder')).toHaveLength(1);
   });
 
   it('does not confuse the SELF-frontmatter with folder rules', () => {
@@ -96,6 +103,80 @@ describe('pendingProposals', () => {
     const branch =
       '---\nread:\n  - everyone\n  - Ali Baba <ali@bevel.software>\n---\n' +
       'read:\n  - GTM Team\n  - Olga Ivanova <olga@bevel.software>\n';
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([]);
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([]);
+  });
+});
+
+/**
+ * A FILE's rules are not an access.md. They live in the node's own
+ * frontmatter, and `spliceGrant` writes one grant there as the scalar form
+ * the resolver accepts — `write: Rita <rita@x.io>`, not a list.
+ *
+ * Read with the FOLDER grammar that is a hard parse error ("'write:' must be
+ * a list"), the whole file yields no grants, and a branch with a perfectly
+ * good proposal on it looks like a branch with nothing left to propose. Every
+ * request whose target was a file was closed on the editors' first listing
+ * because of it — before anyone saw the line, let alone pressed Accept.
+ */
+describe('pendingProposals on a FILE, whose rules are its own frontmatter', () => {
+  const FILE = 'Research/Notes.md';
+  const LIVE = '---\nnodeType: "[Note](../NodeTypes/Note.md)"\n---\n# Notes\n\nbody\n';
+  /** Exactly what `spliceGrant(..., { allowScalar: true, target: 'node' })` writes. */
+  const ASKS_WRITE =
+    '---\nnodeType: "[Note](../NodeTypes/Note.md)"\nwrite: Rita Reader <rita@x.io>\n---\n# Notes\n\nbody\n';
+
+  it('reads the scalar grant the splice actually writes', () => {
+    expect(pendingProposals(ASKS_WRITE, LIVE, FILE, 'file')).toEqual([
+      {
+        verb: 'write',
+        id: 'user:rita@x.io',
+        principal: { kind: 'user', email: 'rita@x.io', displayName: 'Rita Reader' },
+        label: 'Rita Reader',
+      },
+    ]);
+  });
+
+  it('is not fooled by the FOLDER grammar, which cannot read it at all', () => {
+    // The regression guard. Before, this answered `[]` — indistinguishable
+    // from a finished request, which is what closed them.
+    expect(pendingProposals(ASKS_WRITE, LIVE, FILE, 'folder')).toBeNull();
+  });
+
+  it('ignores the non-access keys a node legitimately carries', () => {
+    expect(pendingProposals(LIVE, LIVE, FILE, 'file')).toEqual([]);
+    // `nodeType` is not a grant, and its presence is not a parse failure.
+    expect(pendingProposals(LIVE, null, FILE, 'file')).toEqual([]);
+  });
+
+  it('reads a file with no frontmatter as granting nothing, not as unreadable', () => {
+    // Nothing to say is a real answer here; a node need not declare rules.
+    expect(pendingProposals('# Just a note\n', LIVE, FILE, 'file')).toEqual([]);
+  });
+
+  it('says NOTHING about a file whose frontmatter is broken — not "nothing to propose"', () => {
+    // The same rule the folder side keeps: an empty answer closes somebody's
+    // request, so a block that could not be read must not produce one.
+    const neverClosed = '---\nnodeType: "[Note](x)"\nwrite: Rita Reader <rita@x.io>\n# Notes\n\nbody\n';
+    expect(pendingProposals(neverClosed, LIVE, FILE, 'file')).toBeNull();
+    const notAMapping = '---\n- just\n- a list\n---\n# Notes\n';
+    expect(pendingProposals(notAMapping, LIVE, FILE, 'file')).toBeNull();
+    // An empty block is readable, and says nothing.
+    expect(pendingProposals('---\n---\n# Notes\n', LIVE, FILE, 'file')).toEqual([]);
+    // A broken copy on LIVE stays the safe direction: every grant looks incoming.
+    expect(pendingProposals(ASKS_WRITE, neverClosed, FILE, 'file')).toEqual([
+      expect.objectContaining({ verb: 'write', id: 'user:rita@x.io' }),
+    ]);
+  });
+
+  it('reads the list form too, and an Owner request', () => {
+    const asksOwner =
+      '---\nnodeType: "[Note](x)"\nowner:\n  - Rita Reader <rita@x.io>\n---\n# Notes\n';
+    expect(pendingProposals(asksOwner, LIVE, FILE, 'file')).toEqual([
+      expect.objectContaining({ verb: 'owner', id: 'user:rita@x.io' }),
+    ]);
+  });
+
+  it('still settles a file request once the grant is on live', () => {
+    expect(pendingProposals(ASKS_WRITE, ASKS_WRITE, FILE, 'file')).toEqual([]);
   });
 });

package/src/modules/plugins/__tests__/join-requests.service.test.ts

@@ -7,8 +7,10 @@ import {
   type IWorkflowService,
 } from '@bevel-software/platform-shared';
 import { type WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { JoinRequestsService } from '../join-requests.service.js';
+import { folderTarget } from '../../access/access-requests.contract.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
@@ -44,7 +46,7 @@ function cr(over: Partial<ChangeRequest> = {}): ChangeRequest {
 }
 
 /** `byRef[ref]` is the access.md content at that ref (undefined ⇒ absent). */
-function makeHarness(byRef: Record<string, string>) {
+function makeHarness(byRef: Record<string, string>, holds: Record<string, unknown> = {}) {
   const workspaceService = {
     ensureRemotesFetched: vi.fn(async () => undefined),
     readFileAtRef: vi.fn(async (_ws: string, ref: string, path: string) =>
@@ -55,7 +57,21 @@ function makeHarness(byRef: Record<string, string>) {
     rejectChangeRequest: vi.fn(async () => ({ number: 7, state: 'closed' })),
     deleteBranch: vi.fn(async () => undefined),
   } as unknown as IWorkflowService;
-  return { svc: new JoinRequestsService(workspaceService, workflow, testKbContext()), workflow, workspaceService };
+  // Nobody holds anything by default: every proposal stands on the file diff
+  // alone, which is what these cases are about.
+  const accessControl = {
+    canRead: vi.fn(async () => false),
+    canWrite: vi.fn(async () => false),
+    canOwner: vi.fn(async () => false),
+    canDownload: vi.fn(async () => false),
+    ...holds,
+  } as unknown as IAccessControl;
+  return {
+    svc: new JoinRequestsService(workspaceService, workflow, testKbContext(), accessControl),
+    workflow,
+    workspaceService,
+    accessControl,
+  };
 }
 
 const refs = (branchMd: string | undefined, defaultMd = DEFAULT_MD) => ({
@@ -66,7 +82,7 @@ const refs = (branchMd: string | undefined, defaultMd = DEFAULT_MD) => ({
 describe('JoinRequestsService.list', () => {
   it('reports a request with its pending proposals, and leaves it open', async () => {
     const h = makeHarness(refs(PROPOSING_MD));
-    const out = await h.svc.list('GTM', FOLDER, [cr()], ACTOR);
+    const out = await h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR);
     expect(out).toHaveLength(1);
     expect(out[0]).toMatchObject({ number: 7, requesterName: 'Ali Baba' });
     expect(out[0].proposals.map((p) => p.label)).toEqual(['Ali Baba']);
@@ -76,7 +92,7 @@ describe('JoinRequestsService.list', () => {
   it('SETTLES a request whose proposals have all landed: closes it, deletes the branch, omits it', async () => {
     // The grant is on the default branch now, so the branch adds nothing.
     const h = makeHarness(refs(PROPOSING_MD, PROPOSING_MD));
-    const out = await h.svc.list('GTM', FOLDER, [cr()], ACTOR);
+    const out = await h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR);
     expect(out).toEqual([]);
     expect(h.workflow.rejectChangeRequest).toHaveBeenCalledWith(
       7,
@@ -114,7 +130,7 @@ describe('JoinRequestsService.list', () => {
       new Error('gh down'),
     );
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    await expect(h.svc.list('GTM', FOLDER, [cr()], ACTOR)).resolves.toEqual([]);
+    await expect(h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR)).resolves.toEqual([]);
     expect(warn).toHaveBeenCalled();
     warn.mockRestore();
   });
@@ -125,7 +141,7 @@ describe('JoinRequestsService.list', () => {
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
     // The request still settles (omitted from the list) — the leftover branch
     // is cosmetic, and the failure is logged rather than swallowed.
-    await expect(h.svc.list('GTM', FOLDER, [cr()], ACTOR)).resolves.toEqual([]);
+    await expect(h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR)).resolves.toEqual([]);
     expect(h.workflow.rejectChangeRequest).toHaveBeenCalled();
     expect(warn).toHaveBeenCalledWith(expect.stringContaining('could not delete'));
     warn.mockRestore();
@@ -142,10 +158,10 @@ describe('JoinRequestsService.list', () => {
       [`origin/${DEFAULT_BRANCH}`]: DEFAULT_MD,
       [`origin/${joinBranchFor(ALI, 'Finance!')}`]: DEFAULT_MD,
     });
-    await expect(h.svc.list('finance', 'Plugins/finance', [other], ACTOR)).resolves.toEqual([]);
+    await expect(h.svc.list('finance', folderTarget('Plugins/finance'), [other], ACTOR)).resolves.toEqual([]);
     expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
     expect(h.workflow.deleteBranch).not.toHaveBeenCalled();
-    await expect(h.svc.reconcile('finance', 'Plugins/finance', other, ACTOR)).resolves.toBe(false);
+    await expect(h.svc.reconcile('finance', folderTarget('Plugins/finance'), other, ACTOR)).resolves.toBe(false);
     expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
   });
 });
@@ -153,21 +169,21 @@ describe('JoinRequestsService.list', () => {
 describe('JoinRequestsService.reconcile', () => {
   it('settles and reports true once nothing is pending', async () => {
     const h = makeHarness(refs(PROPOSING_MD, PROPOSING_MD));
-    await expect(h.svc.reconcile('GTM', FOLDER, cr(), ACTOR)).resolves.toBe(true);
+    await expect(h.svc.reconcile('GTM', folderTarget(FOLDER), cr(), ACTOR)).resolves.toBe(true);
     expect(h.workflow.rejectChangeRequest).toHaveBeenCalled();
     expect(h.workflow.deleteBranch).toHaveBeenCalled();
   });
 
   it('leaves a request alone while proposals remain', async () => {
     const h = makeHarness(refs(PROPOSING_MD));
-    await expect(h.svc.reconcile('GTM', FOLDER, cr(), ACTOR)).resolves.toBe(false);
+    await expect(h.svc.reconcile('GTM', folderTarget(FOLDER), cr(), ACTOR)).resolves.toBe(false);
     expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
   });
 
   it('refuses a change request that is not this plugin\'s join branch', async () => {
     const h = makeHarness(refs(PROPOSING_MD, PROPOSING_MD));
     await expect(
-      h.svc.reconcile('GTM', FOLDER, cr({ branch: 'ali/some-draft' }), ACTOR),
+      h.svc.reconcile('GTM', folderTarget(FOLDER), cr({ branch: 'ali/some-draft' }), ACTOR),
     ).resolves.toBe(false);
     expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
   });

package/src/modules/plugins/__tests__/join-requests.settlement.test.ts

@@ -0,0 +1,371 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  DEFAULT_BRANCH,
+  joinBranchFor,
+  type AuthUser,
+  type ChangeRequest,
+  type IWorkflowService,
+} from '@bevel-software/platform-shared';
+import { type WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import { folderTarget } from '../../access/access-requests.contract.js';
+import { JoinRequestsService } from '../join-requests.service.js';
+import { spliceGrant } from '../../access-model/access-splice.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+
+/**
+ * A request ends when the person it names HOLDS what it asked for — however
+ * they came to hold it.
+ *
+ * The file diff alone cannot see that. Owner covers Can edit without putting
+ * a `write:` line anywhere; a role or a group carries access without naming
+ * anybody; a grant on a parent folder never touches this file at all. Each of
+ * those leaves the branch proposing something no editor can usefully accept,
+ * and the request sits open forever. These are the cases that asking the
+ * resolver instead settles — including for the two Library request kinds,
+ * which go through exactly this service.
+ */
+const ALI = 'ali@bevel.software';
+const FOLDER = 'Plugins/GTM';
+const ACCESS_MD = `${FOLDER}/access.md`;
+const ACTOR: AuthUser = { id: 'u-1', email: 'olga@bevel.software', name: 'Olga Ivanova' };
+const BRANCH = joinBranchFor(ALI, 'GTM');
+
+const base = (body: string) => `---\nread:\n  - everyone\n---\n${body}`;
+const DEFAULT_MD = base('read:\n  - GTM Team\n');
+const ASKS_WRITE = base(`read:\n  - GTM Team\nwrite:\n  - Ali Baba <${ALI}>\n`);
+const ASKS_FOR_A_ROLE = base('read:\n  - GTM Team\n  - role/Analysts\n');
+
+function cr(over: Partial<ChangeRequest> = {}): ChangeRequest {
+  return {
+    number: 7,
+    title: 'Access request: GTM',
+    author: { login: 'user-abc' },
+    authorId: 'hash-ali',
+    appAuthor: { name: 'Ali Baba' },
+    branch: BRANCH,
+    base: DEFAULT_BRANCH,
+    state: 'open',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    touchedNodePaths: [ACCESS_MD],
+    review: { approvals: 0, changesRequested: 0, pendingLogins: [] },
+    url: '/change-requests/7',
+    ...over,
+  } as ChangeRequest;
+}
+
+function makeHarness(
+  branchMd: string | undefined,
+  holds: Partial<Record<'canRead' | 'canWrite' | 'canOwner' | 'canDownload', boolean>> = {},
+  /** Refs that only appear once a FORCED fetch has run — a branch just pushed. */
+  arrivesOnForcedFetch: string | undefined = undefined,
+  liveMd: string = DEFAULT_MD,
+) {
+  const byRef: Record<string, string> = {
+    [`origin/${DEFAULT_BRANCH}`]: liveMd,
+    ...(branchMd === undefined ? {} : { [`origin/${BRANCH}`]: branchMd }),
+  };
+  const fetches: { force: boolean }[] = [];
+  const workspaceService = {
+    ensureRemotesFetched: vi.fn(async (_ws: string, opts: { force?: boolean } = {}) => {
+      fetches.push({ force: !!opts.force });
+      if (opts.force && arrivesOnForcedFetch !== undefined) {
+        byRef[`origin/${BRANCH}`] = arrivesOnForcedFetch;
+      }
+    }),
+    readFileAtRef: vi.fn(async (_ws: string, ref: string, p: string) => {
+      if (p !== ACCESS_MD) return null;
+      const text = byRef[ref];
+      // A ref this clone has not heard of is not an empty file — it throws,
+      // exactly as `git show` does for an unknown ref.
+      if (text === undefined) throw new Error(`unknown revision ${ref}`);
+      return text;
+    }),
+  } as unknown as WorkspaceService;
+  const workflow = {
+    rejectChangeRequest: vi.fn(async () => ({ number: 7, state: 'closed' })),
+    deleteBranch: vi.fn(async () => undefined),
+  } as unknown as IWorkflowService;
+  const asked: { verb: string; path: string; email: string }[] = [];
+  const answer = (verb: 'canRead' | 'canWrite' | 'canOwner' | 'canDownload') =>
+    vi.fn(async (_ws: string, email: string, path: string) => {
+      asked.push({ verb, path, email });
+      return holds[verb] ?? false;
+    });
+  const accessControl = {
+    canRead: answer('canRead'),
+    canWrite: answer('canWrite'),
+    canOwner: answer('canOwner'),
+    canDownload: answer('canDownload'),
+  } as unknown as IAccessControl;
+  return {
+    svc: new JoinRequestsService(workspaceService, workflow, testKbContext(), accessControl),
+    workflow,
+    asked,
+    fetches,
+  };
+}
+
+describe('a request settles once the person holds what it asked for', () => {
+  it('settles a write request when Owner already covers it', async () => {
+    // `canWrite` is the resolver's own question, and owner folds into write —
+    // so an owner grant made in the dialog retires the Can edit request.
+    const h = makeHarness(ASKS_WRITE, { canWrite: true });
+    await expect(h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR)).resolves.toEqual([]);
+    expect(h.workflow.rejectChangeRequest).toHaveBeenCalled();
+    expect(h.workflow.deleteBranch).toHaveBeenCalledWith(expect.anything(), BRANCH, ACTOR);
+  });
+
+  it('asks about the ITEM, not its rules file — a folder request is about the folder', async () => {
+    const h = makeHarness(ASKS_WRITE, { canWrite: true });
+    await h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR);
+    expect(h.asked).toContainEqual({ verb: 'canWrite', path: FOLDER, email: ALI });
+  });
+
+  it('settles through a role or group the person has since joined', async () => {
+    // Nothing in the file names Ali, yet the resolver says he writes here:
+    // that is a role, a group, or a grant on a parent folder.
+    const h = makeHarness(ASKS_WRITE, { canWrite: true });
+    await expect(h.svc.reconcile('GTM', folderTarget(FOLDER), cr(), ACTOR)).resolves.toBe(true);
+  });
+
+  it('leaves the request open while the person still holds nothing', async () => {
+    const h = makeHarness(ASKS_WRITE);
+    const out = await h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR);
+    expect(out).toHaveLength(1);
+    expect(out[0].proposals.map((p) => p.verb)).toEqual(['write']);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('keeps today\'s literal rule for a proposal naming a ROLE', async () => {
+    // "Does this role hold read here" is not a question the per-person
+    // resolver answers, so a role proposal is settled by the live rules
+    // carrying it — never by what some person happens to hold.
+    const h = makeHarness(ASKS_FOR_A_ROLE, { canRead: true, canWrite: true, canOwner: true });
+    const out = await h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR);
+    expect(out).toHaveLength(1);
+    expect(out[0].proposals.map((p) => p.label)).toEqual(['role/Analysts']);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('leaves the request open when the resolver cannot answer', async () => {
+    const h = makeHarness(ASKS_WRITE);
+    const svc = h.svc as unknown as { accessControl: { canWrite: () => Promise<boolean> } };
+    svc.accessControl.canWrite = () => Promise.reject(new Error('resolver down'));
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const out = await h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR);
+    expect(out).toHaveLength(1);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});
+
+describe('a branch that cannot be read settles nothing', () => {
+  /**
+   * The failure this guards against, in full: these reads go through
+   * `origin/<branch>` in the DEFAULT branch's clone, and that clone's fetch is
+   * throttled. A request opened seconds ago names a ref the clone has not
+   * heard of. Read as "the branch proposes nothing" — which is what an empty
+   * diff against a missing file looks like — the request is CLOSED, by
+   * nobody, before any editor has seen it, and the person is told their
+   * request was not accepted.
+   *
+   * So: a miss is retried behind a forced fetch, and a miss that survives that
+   * leaves the request exactly where it was.
+   */
+
+  it('retries behind a FORCED fetch before believing a branch says nothing', async () => {
+    // Present on origin, absent from this clone's refs until it fetches.
+    const h = makeHarness(undefined, {}, ASKS_WRITE);
+    const out = await h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR);
+
+    expect(h.fetches.some((f) => f.force)).toBe(true);
+    expect(out).toHaveLength(1);
+    expect(out[0].proposals.map((p) => p.verb)).toEqual(['write']);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('leaves the request open — and unclosed — when the branch still cannot be read', async () => {
+    const h = makeHarness(undefined);
+    await expect(h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR)).resolves.toEqual([]);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+    expect(h.workflow.deleteBranch).not.toHaveBeenCalled();
+  });
+
+  it('reconcile refuses to settle one it could not read', async () => {
+    const h = makeHarness(undefined);
+    await expect(h.svc.reconcile('GTM', folderTarget(FOLDER), cr(), ACTOR)).resolves.toBe(false);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('still settles a branch it DID read that proposes nothing', async () => {
+    // The distinction has to cut both ways, or nothing would ever retire.
+    const h = makeHarness(DEFAULT_MD);
+    await expect(h.svc.reconcile('GTM', folderTarget(FOLDER), cr(), ACTOR)).resolves.toBe(true);
+    expect(h.workflow.rejectChangeRequest).toHaveBeenCalled();
+  });
+});
+
+describe('a person the rules explicitly deny', () => {
+  /**
+   * `ARTest5`-shaped rules: read granted, write DENIED, and the branch
+   * proposing the write anyway. The resolver says that person cannot write
+   * (verified against the real one), so their proposal is unmet and must
+   * survive to reach an editor — "Accept … includes a person the rules
+   * explicitly deny" is unreachable otherwise, and the requester is told a
+   * refusal nobody made.
+   */
+  const DENIED_MD = base(`read:\n  - Ali Baba <${ALI}>\nwrite:\n  - deny Ali Baba <${ALI}>\n`);
+  const ASKS_DESPITE_DENY = base(
+    `read:\n  - Ali Baba <${ALI}>\nwrite:\n  - deny Ali Baba <${ALI}>\n  - Ali Baba <${ALI}>\n`,
+  );
+
+  it('keeps their proposal, so an editor can still accept it', async () => {
+    // Live DENIES the write; the branch adds the grant beside the deny, which
+    // is exactly the text the dialog's own grant writes for this person.
+    const h = makeHarness(ASKS_DESPITE_DENY, { canRead: true, canWrite: false }, undefined, DENIED_MD);
+    const out = await h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR);
+    expect(out).toHaveLength(1);
+    expect(out[0].proposals.map((p) => p.verb)).toEqual(['write']);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('retires it once the grant has landed and the resolver says they write', async () => {
+    // What Accept does: a same-scope grant beats a same-scope deny, so the
+    // resolver then reports write and the request has nothing left to ask.
+    const h = makeHarness(ASKS_DESPITE_DENY, { canWrite: true }, undefined, DENIED_MD);
+    await expect(h.svc.reconcile('GTM', folderTarget(FOLDER), cr(), ACTOR)).resolves.toBe(true);
+  });
+});
+
+describe('a stale ref must not be mistaken for a finished request', () => {
+  /**
+   * The nastier half of the same hazard. Here the branch's ref RESOLVES — it
+   * is simply a few seconds behind, pointing at the commit before the
+   * proposal was pushed. That reads as a file identical to live, which is an
+   * empty diff, which looks exactly like a request whose grants have all
+   * landed. Nothing about it looks like a failure, and the request is closed.
+   */
+
+  /** Stale: the branch answers with live's own text until a forced fetch. */
+  const staleHarness = () => makeHarness(DEFAULT_MD, {}, ASKS_WRITE);
+
+  it('does not settle a request whose proposal only shows after a fresh fetch', async () => {
+    const h = staleHarness();
+    const out = await h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR);
+
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+    expect(h.workflow.deleteBranch).not.toHaveBeenCalled();
+    // And having fetched, it reports the proposal rather than nothing.
+    expect(out).toHaveLength(1);
+    expect(out[0].proposals.map((p) => p.verb)).toEqual(['write']);
+  });
+
+  it('reconcile refuses to settle it either', async () => {
+    const h = staleHarness();
+    await expect(h.svc.reconcile('GTM', folderTarget(FOLDER), cr(), ACTOR)).resolves.toBe(false);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('confirms with a FORCED fetch before closing anything', async () => {
+    const h = makeHarness(DEFAULT_MD);
+    await h.svc.list('GTM', folderTarget(FOLDER), [cr()], ACTOR);
+    expect(h.fetches.some((f) => f.force)).toBe(true);
+    // Genuinely finished — the confirming read agrees, so it closes.
+    expect(h.workflow.rejectChangeRequest).toHaveBeenCalled();
+  });
+});
+
+describe('a request whose target is a FILE', () => {
+  /**
+   * The staging failure, at the level it happened. Every file-target request
+   * self-closed on the editors' FIRST listing: the listing answered
+   * `{"requests":[]}` and closed the change request in the same call, and the
+   * requester's status dropped to "none". Nobody had seen the line.
+   *
+   * A file's rules are its own frontmatter, and `spliceGrant` writes one grant
+   * there as a scalar — the same bytes the dialog's ordinary grant writes, and
+   * the resolver honours them. Read with the folder grammar it is a parse
+   * error, which yielded no grants, which reads as a finished request.
+   *
+   * So this exercises the real splice output against the real reader, with the
+   * target the request was actually made about.
+   */
+  const FILE = 'Plugins/GTM/page.md';
+  const LIVE_FILE = '---\nnodeType: "[Note](../NodeTypes/Note.md)"\n---\n# Page\n\nbody\n';
+  const fileTarget = { path: FILE, kind: 'file' as const };
+
+  /** Exactly what the request opener writes onto the branch for a file. */
+  const asksWrite = spliceGrant(
+    LIVE_FILE,
+    'write',
+    { kind: 'user', email: ALI, displayName: 'Ali Baba' },
+    { allowScalar: true, target: 'node' },
+  ).text;
+
+  /** The harness above is keyed on an access.md; this one answers for a file. */
+  function fileHarness(branchText: string, holds: Record<string, boolean> = {}) {
+    const byRef: Record<string, string> = {
+      [`origin/${DEFAULT_BRANCH}`]: LIVE_FILE,
+      [`origin/${BRANCH}`]: branchText,
+    };
+    const workspaceService = {
+      ensureRemotesFetched: vi.fn(async () => undefined),
+      readFileAtRef: vi.fn(async (_ws: string, ref: string, p: string) => {
+        if (p !== FILE) throw new Error(`unexpected path ${p}`);
+        const text = byRef[ref];
+        if (text === undefined) throw new Error(`unknown revision ${ref}`);
+        return text;
+      }),
+    } as unknown as WorkspaceService;
+    const workflow = {
+      rejectChangeRequest: vi.fn(async () => ({ number: 7, state: 'closed' })),
+      deleteBranch: vi.fn(async () => undefined),
+    } as unknown as IWorkflowService;
+    const answer = (verb: string) => vi.fn(async () => holds[verb] ?? false);
+    const accessControl = {
+      canRead: answer('canRead'),
+      canWrite: answer('canWrite'),
+      canOwner: answer('canOwner'),
+      canDownload: answer('canDownload'),
+    } as unknown as IAccessControl;
+    return {
+      svc: new JoinRequestsService(workspaceService, workflow, testKbContext(), accessControl),
+      workflow,
+      workspaceService,
+    };
+  }
+
+  it('reads the file\'s OWN frontmatter, so the request survives the first listing', async () => {
+    const h = fileHarness(asksWrite);
+    const out = await h.svc.list('GTM', fileTarget, [cr()], ACTOR);
+
+    expect(out).toHaveLength(1);
+    expect(out[0].proposals.map((p) => p.verb)).toEqual(['write']);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+    expect(h.workflow.deleteBranch).not.toHaveBeenCalled();
+  });
+
+  it('reads the FILE itself, never an access.md beside it', async () => {
+    // A request on a file changes only that file's rules, so the only path it
+    // may read is the file. The harness throws on anything else.
+    const h = fileHarness(asksWrite);
+    await h.svc.list('GTM', fileTarget, [cr()], ACTOR);
+    const paths = (h.workspaceService.readFileAtRef as ReturnType<typeof vi.fn>).mock.calls.map(
+      (c) => c[2],
+    );
+    expect(new Set(paths)).toEqual(new Set([FILE]));
+  });
+
+  it('retires it once the person holds the level on the file', async () => {
+    const h = fileHarness(asksWrite, { canWrite: true });
+    await expect(h.svc.reconcile('GTM', fileTarget, cr(), ACTOR)).resolves.toBe(true);
+  });
+
+  it('retires it once the grant has landed on live', async () => {
+    const h = fileHarness(asksWrite);
+    const byRef = h.workspaceService.readFileAtRef as ReturnType<typeof vi.fn>;
+    byRef.mockImplementation(async () => asksWrite); // both refs carry it now
+    await expect(h.svc.reconcile('GTM', fileTarget, cr(), ACTOR)).resolves.toBe(true);
+  });
+});