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

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

package/src/modules/plugins/__tests__/plugins.routes.test.ts

@@ -830,7 +830,7 @@ describe('/api/plugins routes', () => {
     expect(await res.json()).toEqual({ requests: [] });
     expect(h.joinRequests.list).toHaveBeenCalledWith(
       'GTM',
-      'Plugins/GTM',
+      { path: 'Plugins/GTM', kind: 'folder' },
       expect.anything(),
       expect.objectContaining({ email: ALI }),
     );

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

@@ -1,9 +1,12 @@
 import {
   KNOWN_VERBS,
+  ownAccessReadable,
   parseAccessFile,
+  parseOwnAccessEntries,
   type ParsedEntry,
   type Verb,
 } from '../access-model/access-grammar.js';
+import type { TargetKind } from '../access/access-mutation.service.js';
 
 /**
  * What a join branch is PROPOSING, relative to the default branch.
@@ -50,23 +53,75 @@ function identityOf(entry: ParsedEntry): string {
 }
 
 /**
- * Folder rules from one copy of an `access.md`, per verb, grants only.
+ * The per-verb entries one copy of an item's rules declares, or null when the
+ * text could not be read as rules at all.
  *
- * A file that fails to parse yields NO grants. On the branch side that means
- * a malformed proposal offers nothing to accept (fail-closed). On the default
- * side it means every branch grant looks incoming — which is the safe
- * direction too: the manager is shown proposals to consider rather than
- * having them silently swallowed by an unreadable baseline.
+ * THE GRAMMAR FOLLOWS THE ITEM, because there are two of them and the
+ * resolver picks by item as well:
+ *
+ *   folder   a `access.md`, whose folder rules are a BODY of `verb:` block
+ *            lists — `parseAccessFile`, which fails the whole file if a verb
+ *            is not a list.
+ *   file     the node's OWN frontmatter — `parseOwnAccessEntries`, which also
+ *            accepts the single-value scalar form (`write: Rita <r@x.io>`),
+ *            ignores non-access keys like `nodeType:`, and drops a bad entry
+ *            rather than failing the file.
+ *
+ * Reading a file's frontmatter with the FOLDER grammar is what broke every
+ * request whose target was a file: `spliceGrant` writes one grant into a
+ * node's frontmatter as exactly that scalar — the same bytes the dialog's own
+ * grant writes, which the resolver honours — and the folder grammar rejects it
+ * with "'write:' must be a list", failing the parse, yielding no grants, which
+ * reads as a branch with nothing left to propose. The request was then closed
+ * on the editors' first listing, before anyone had seen it.
+ *
+ * Null is reserved for "could not be read": a folder `access.md` that does
+ * not parse, or a file whose frontmatter is broken (never closed, or not a
+ * mapping). A file with no frontmatter, or with frontmatter naming no verb,
+ * is perfectly readable and simply grants nothing. The file grammar's own
+ * null does not tell those apart, so the question is asked separately: a
+ * broken block read as "grants nothing" would close the request on a
+ * reading that failed, the same mistake by another door.
  */
-function grantsByVerb(text: string | null, path: string): Map<Verb, Map<string, ParsedEntry>> {
-  const out = new Map<Verb, Map<string, ParsedEntry>>();
-  for (const verb of KNOWN_VERBS) out.set(verb, new Map());
-  if (text === null) return out;
+function entriesOf(
+  text: string,
+  path: string,
+  kind: TargetKind,
+): Record<Verb, ParsedEntry[]> | null {
+  if (kind === 'file') {
+    return parseOwnAccessEntries(text) ?? (ownAccessReadable(text) ? emptyGrants() : null);
+  }
   const parsed = parseAccessFile(text, path);
-  if (!parsed.ok) return out;
+  return parsed.ok ? parsed.file.entries : null;
+}
+
+function emptyGrants(): Record<Verb, ParsedEntry[]> {
+  const out = {} as Record<Verb, ParsedEntry[]>;
+  for (const verb of KNOWN_VERBS) out[verb] = [];
+  return out;
+}
+
+/** An index that grants nothing — the baseline a copy nobody could read stands in as. */
+function emptyIndex(): Map<Verb, Map<string, ParsedEntry>> {
+  return new Map(KNOWN_VERBS.map((verb) => [verb, new Map<string, ParsedEntry>()]));
+}
+
+/**
+ * Grants only, indexed by canonical identity, from one copy of the rules.
+ * Null in, null out — an unreadable copy is not an empty one.
+ */
+function grantsByVerb(
+  text: string | null,
+  path: string,
+  kind: TargetKind,
+): Map<Verb, Map<string, ParsedEntry>> | null {
+  if (text === null) return null;
+  const entries = entriesOf(text, path, kind);
+  if (entries === null) return null;
+  const out = emptyIndex();
   for (const verb of KNOWN_VERBS) {
     const byId = out.get(verb)!;
-    for (const entry of parsed.file.entries[verb]) {
+    for (const entry of entries[verb]) {
       if (entry.deny) continue;
       byId.set(identityOf(entry), entry);
     }
@@ -75,19 +130,32 @@ function grantsByVerb(text: string | null, path: string): Map<Verb, Map<string,
 }
 
 /**
- * The grants `branchText` adds over `defaultText` — the proposals a manager
- * can accept. Empty ⇒ the branch's rules are a subset of the default's.
+ * The grants `branchText` adds over `defaultText` — the proposals an editor
+ * can accept. Empty ⇒ the branch's rules are a subset of the default's, which
+ * is the settled state.
+ *
+ * NULL when the branch's own copy is absent or unreadable, which is a
+ * different fact entirely and the one this surface keeps getting wrong: an
+ * empty answer closes somebody's request, so it has to mean "the branch asks
+ * for nothing more", never "the branch would not tell us".
+ *
+ * An unreadable DEFAULT copy stays what it was — every branch grant looks
+ * incoming. That is the safe direction on that side: an editor is shown
+ * proposals to consider rather than having them swallowed by a baseline
+ * nobody could read.
  *
- * `path` is only used to label parse errors; both texts are the same file at
- * two refs.
+ * `path` labels parse errors; both texts are the same file at two refs, and
+ * `kind` says which grammar that file is written in.
  */
 export function pendingProposals(
   branchText: string | null,
   defaultText: string | null,
   path: string,
-): JoinProposal[] {
-  const branch = grantsByVerb(branchText, path);
-  const base = grantsByVerb(defaultText, path);
+  kind: TargetKind,
+): JoinProposal[] | null {
+  const branch = grantsByVerb(branchText, path, kind);
+  if (branch === null) return null;
+  const base = grantsByVerb(defaultText, path, kind) ?? emptyIndex();
   const out: JoinProposal[] = [];
   for (const verb of KNOWN_VERBS) {
     const baseIds = base.get(verb)!;