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

package/src/modules/access/__tests__/access-control.preview-relocation.test.ts

@@ -0,0 +1,385 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { AccessControlService } from '../access-control.service.js';
+
+/**
+ * `previewAccessAfterRelocation`: the caller's OWN verbs at a destination as
+ * they will be once a move or a copy has landed there.
+ *
+ * The question the four gates cannot answer, because the `access.md` files a
+ * folder carries are not at the destination yet — which is how a rename came
+ * to warn about losing owner access the folder's own rules were about to hand
+ * straight back. Driven over a real on-disk tree, and every answer checked
+ * against the ordinary gates once the tree really says what the preview said
+ * it would.
+ */
+
+const KB_DIR = 'knowledge-base';
+const MOVER = 'mover@x.io';
+
+function stubWorkspaceService(workspaceId: string, workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+    ensureRemotesFetched: async () => undefined,
+  } as unknown as WorkspaceService;
+}
+
+const rules = (body: string) => `---\n${body}---\n`;
+
+describe('AccessControlService.previewAccessAfterRelocation', () => {
+  let root: string;
+  let repo: string;
+  const workspaceId = 'ws-preview-relocation';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-preview-reloc-'));
+    repo = path.join(root, workspaceId, KB_DIR);
+  });
+  afterEach(async () => {
+    if (root) await fs.rm(root, { recursive: true, force: true });
+  });
+
+  async function write(files: Record<string, string>): Promise<void> {
+    for (const [rel, contents] of Object.entries(files)) {
+      const abs = path.join(repo, rel);
+      await fs.mkdir(path.dirname(abs), { recursive: true });
+      await fs.writeFile(abs, contents);
+    }
+  }
+
+  /**
+   * A service reading the tree as it is NOW. Built fresh after every change
+   * on purpose: in production the file-change notifier invalidates the model,
+   * and a test that leaned on the five-second cache would be asserting the
+   * cache rather than the resolver.
+   */
+  const service = () =>
+    new AccessControlService(
+      stubWorkspaceService(workspaceId, path.join(root, workspaceId)),
+      KB_DIR,
+      new NodeFs(),
+    );
+
+  /** The caller's four verbs at a path, through the ordinary gates. */
+  async function verbsAt(svc: AccessControlService, rel: string) {
+    const [read, write, download, owner] = await Promise.all([
+      svc.canRead(workspaceId, MOVER, rel),
+      svc.canWrite(workspaceId, MOVER, rel),
+      svc.canDownload(workspaceId, MOVER, rel),
+      svc.canOwner(workspaceId, MOVER, rel),
+    ]);
+    return { read, write, download, owner };
+  }
+
+  /** Move `from` to `to` on disk, as the move itself does. */
+  async function reallyMove(from: string, to: string): Promise<void> {
+    const dest = path.join(repo, to);
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    await fs.rename(path.join(repo, from), dest);
+  }
+
+  /** Copy `from` to `to` on disk, leaving the source where it is. */
+  async function reallyCopy(from: string, to: string): Promise<void> {
+    const dest = path.join(repo, to);
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    await fs.cp(path.join(repo, from), dest, { recursive: true });
+  }
+
+  const BASE = {
+    'roles.yaml': 'roles:\n  Admin:\n    - admin@x.io\n',
+    'access.md': rules('read:\n  - everyone\n'),
+  };
+
+  it('a folder keeps the access its own access.md gives it when it is renamed', async () => {
+    await write({
+      ...BASE,
+      'Sales/access.md': rules(`write:\n  - Mover <${MOVER}>\nowner:\n  - Mover <${MOVER}>\n`),
+      'Sales/deal.md': '# Deal\n',
+    });
+
+    const svc = service();
+    const before = await verbsAt(svc, 'Sales');
+    const after = await svc.previewAccessAfterRelocation(workspaceId, MOVER, 'Sales', 'Revenue');
+
+    expect(before.owner).toBe(true);
+    expect(after).toEqual(before);
+
+    // The root grants read and nothing else, so the destination AS IT STANDS
+    // says the opposite — which is the warning people were shown.
+    expect(await verbsAt(svc, 'Revenue')).toMatchObject({ write: false, owner: false });
+
+    await reallyMove('Sales', 'Revenue');
+    expect(await verbsAt(service(), 'Revenue')).toEqual(after);
+  });
+
+  it('a folder with no access.md of its own takes the new parent\'s rules, as it always did', async () => {
+    await write({
+      ...BASE,
+      'Work/access.md': rules(`write:\n  - Mover <${MOVER}>\n`),
+      'Work/Notes/note.md': '# Note\n',
+      'Legal/access.md': rules('read:\n  - everyone\n'),
+    });
+
+    const svc = service();
+    const before = await verbsAt(svc, 'Work/Notes');
+    const after = await svc.previewAccessAfterRelocation(workspaceId, MOVER, 'Work/Notes', 'Legal/Notes');
+
+    expect(before.write).toBe(true);
+    expect(after.write).toBe(false);
+    // Nothing travels, so the preview is exactly what the gates say today.
+    expect(after).toEqual(await verbsAt(svc, 'Legal/Notes'));
+
+    await reallyMove('Work/Notes', 'Legal/Notes');
+    expect(await verbsAt(service(), 'Legal/Notes')).toEqual(after);
+  });
+
+  it('what the folder inherited is left behind; what it carries comes along', async () => {
+    await write({
+      ...BASE,
+      'Work/access.md': rules(`write:\n  - Mover <${MOVER}>\nowner:\n  - Mover <${MOVER}>\n`),
+      'Work/Team/access.md': rules(`write:\n  - Mover <${MOVER}>\n`),
+      'Work/Team/plan.md': '# Plan\n',
+      'Legal/access.md': rules('read:\n  - everyone\n'),
+    });
+
+    const svc = service();
+    expect(await verbsAt(svc, 'Work/Team')).toMatchObject({ write: true, owner: true });
+
+    const after = await svc.previewAccessAfterRelocation(workspaceId, MOVER, 'Work/Team', 'Legal/Team');
+
+    // Write is the folder's own and travels; owner came from `Work/` and
+    // does not.
+    expect(after).toMatchObject({ write: true, owner: false });
+
+    await reallyMove('Work/Team', 'Legal/Team');
+    expect(await verbsAt(service(), 'Legal/Team')).toEqual(after);
+  });
+
+  it('a nested access.md does not change the answer at the folder itself', async () => {
+    const tree = {
+      ...BASE,
+      'Work/access.md': rules(`write:\n  - Mover <${MOVER}>\nowner:\n  - Mover <${MOVER}>\n`),
+      'Work/Team/access.md': rules(`write:\n  - Mover <${MOVER}>\n`),
+      'Work/Team/plan.md': '# Plan\n',
+      'Legal/access.md': rules('read:\n  - everyone\n'),
+    };
+    await write(tree);
+    const withoutNested = await service().previewAccessAfterRelocation(
+      workspaceId, MOVER, 'Work/Team', 'Legal/Team',
+    );
+
+    // `Sub/` shuts the caller out entirely, and it moves too — but it governs
+    // `Legal/Team/Sub`, not `Legal/Team`.
+    await write({ 'Work/Team/Sub/access.md': rules(`read:\n  - deny Mover <${MOVER}>\n`) });
+    const svc = service();
+    expect(await svc.previewAccessAfterRelocation(workspaceId, MOVER, 'Work/Team', 'Legal/Team'))
+      .toEqual(withoutNested);
+    // It is counted, though — at the path it lands on.
+    expect(
+      await svc.previewAccessAfterRelocation(workspaceId, MOVER, 'Work/Team', 'Legal/Team'),
+    ).not.toEqual(
+      await svc.previewAccessAfterRelocation(workspaceId, MOVER, 'Work/Team/Sub', 'Legal/Team/Sub'),
+    );
+
+    await reallyMove('Work/Team', 'Legal/Team');
+    const after = service();
+    expect(await verbsAt(after, 'Legal/Team')).toEqual(withoutNested);
+    expect(await verbsAt(after, 'Legal/Team/Sub')).toMatchObject({ read: false });
+  });
+
+  it('a copy leaves the source rules where they are and lands a second set', async () => {
+    await write({
+      ...BASE,
+      'Sales/access.md': rules(`write:\n  - Mover <${MOVER}>\nowner:\n  - Mover <${MOVER}>\n`),
+      'Sales/deal.md': '# Deal\n',
+      // A destination governed DIFFERENTLY from the source, so the answer can
+      // only come from the rules the copy carries: Legal grants read and
+      // nothing else, as the root does.
+      'Legal/access.md': rules('read:\n  - everyone\n'),
+    });
+
+    const svc = service();
+    const after = await svc.previewAccessAfterRelocation(
+      workspaceId, MOVER, 'Sales', 'Legal/Sales-Copy', { sourceRemains: true },
+    );
+
+    // The copied `access.md` governs the copy, which is the opposite of what
+    // the destination says today.
+    expect(after).toMatchObject({ write: true, owner: true });
+    expect(await verbsAt(svc, 'Legal')).toMatchObject({ write: false, owner: false });
+
+    await reallyCopy('Sales', 'Legal/Sales-Copy');
+    const done = service();
+    expect(await verbsAt(done, 'Legal/Sales-Copy')).toEqual(after);
+    // `sourceRemains`: both sets of rules are real afterwards, and the source
+    // keeps the access it always had.
+    expect(await verbsAt(done, 'Sales')).toMatchObject({ owner: true });
+  });
+
+  /**
+   * A lone `access.md` is a single FILE whose rules are a whole folder's.
+   * Keyed by the directory it sits in, it is not a path "under" the source,
+   * so the folder walk cannot see it — and `copy_file` will copy one, which
+   * is how a preview came to answer the destination's old rules about a
+   * directory that was about to be governed by the file landing in it.
+   */
+  it('a lone access.md governs the folder it is copied into', async () => {
+    await write({
+      ...BASE,
+      'Sales/access.md': rules(`write:\n  - Mover <${MOVER}>\nowner:\n  - Mover <${MOVER}>\n`),
+      'Legal/note.md': '# Note\n',
+    });
+
+    const svc = service();
+    // `Legal/` has no rules of its own; the root grants read and nothing else.
+    expect(await verbsAt(svc, 'Legal')).toMatchObject({ write: false, owner: false });
+
+    const after = await svc.previewAccessAfterRelocation(
+      workspaceId, MOVER, 'Sales/access.md', 'Legal/access.md', { sourceRemains: true },
+    );
+    expect(after).toMatchObject({ write: true, owner: true });
+
+    await fs.copyFile(path.join(repo, 'Sales/access.md'), path.join(repo, 'Legal/access.md'));
+    const done = service();
+    expect(await verbsAt(done, 'Legal/access.md')).toEqual(after);
+    // What landed governs the folder, not only itself.
+    expect(await verbsAt(done, 'Legal')).toMatchObject({ write: true, owner: true });
+  });
+
+  /**
+   * The name the bytes land under decides what they GOVERN, and it decides
+   * how they are PARSED: the same frontmatter is a folder's rules in an
+   * `access.md` and the file's own rules anywhere else. So these bytes
+   * govern no folder at `Legal/rules-copy.md` — and still grant the caller
+   * write and owner, on that one file. Reading them as the source's name said
+   * `write: false, owner: false`, and the copy then handed over both: a
+   * preview contradicting the operation it was previewing, which is the
+   * entire fault this ticket exists to kill.
+   */
+  it('a file copied under any other name governs no folder, but keeps its own grants', async () => {
+    await write({
+      ...BASE,
+      'Sales/access.md': rules(`write:\n  - Mover <${MOVER}>\nowner:\n  - Mover <${MOVER}>\n`),
+      'Legal/note.md': '# Note\n',
+    });
+
+    const svc = service();
+    const after = await svc.previewAccessAfterRelocation(
+      workspaceId, MOVER, 'Sales/access.md', 'Legal/rules-copy.md', { sourceRemains: true },
+    );
+    // Pinned, not merely equal to the outcome: both sides reading `false`
+    // would satisfy the comparison below and be wrong together.
+    expect(after).toMatchObject({ write: true, owner: true });
+
+    await reallyCopy('Sales/access.md', 'Legal/rules-copy.md');
+    const done = service();
+    expect(await verbsAt(done, 'Legal/rules-copy.md')).toEqual(after);
+    // The folder it landed in is untouched: an ordinary note governs nothing
+    // but itself, whatever its frontmatter says.
+    expect(await verbsAt(done, 'Legal')).toMatchObject({ write: false, owner: false });
+    expect(await verbsAt(done, 'Legal/note.md')).toMatchObject({ write: false, owner: false });
+  });
+
+  /**
+   * And the mirror, which `copy_file` also allows: ordinary bytes landing as
+   * a directory's `access.md` become that directory's rules the moment they
+   * land. The preview reads them as the destination will.
+   */
+  it('a file copied TO an access.md gives the destination folder its rules', async () => {
+    await write({
+      ...BASE,
+      'Draft/proposed-rules.md': rules(`write:\n  - Mover <${MOVER}>\nowner:\n  - Mover <${MOVER}>\n`),
+      'Legal/note.md': '# Note\n',
+    });
+
+    const svc = service();
+    expect(await verbsAt(svc, 'Legal')).toMatchObject({ write: false, owner: false });
+
+    const after = await svc.previewAccessAfterRelocation(
+      workspaceId, MOVER, 'Draft/proposed-rules.md', 'Legal/access.md', { sourceRemains: true },
+    );
+    expect(after).toMatchObject({ write: true, owner: true });
+
+    await reallyCopy('Draft/proposed-rules.md', 'Legal/access.md');
+    const done = service();
+    expect(await verbsAt(done, 'Legal/access.md')).toEqual(after);
+    // It governs the folder now, which is the whole difference the name makes.
+    expect(await verbsAt(done, 'Legal')).toMatchObject({ write: true, owner: true });
+    expect(await verbsAt(done, 'Legal/note.md')).toMatchObject({ write: true, owner: true });
+  });
+
+  /**
+   * The same rule for the other thing that travels with a file: its own
+   * frontmatter. Asking the DESTINATION for it always answered null — nothing
+   * is there yet — so a rename of a self-governing file previewed a loss the
+   * move hands straight back, and the preview contradicted the access the
+   * caller really has afterwards (Specification requirement 6).
+   */
+  it("a file's own frontmatter travels with its bytes, so a rename costs nothing", async () => {
+    await write({
+      ...BASE,
+      'Work/access.md': rules('read:\n  - everyone\n'),
+      'Work/plan.md': rules(`owner:\n  - Mover <${MOVER}>\n`) + '# Plan\n',
+    });
+
+    const svc = service();
+    const before = await verbsAt(svc, 'Work/plan.md');
+    expect(before.owner).toBe(true);
+
+    const after = await svc.previewAccessAfterRelocation(
+      workspaceId, MOVER, 'Work/plan.md', 'Work/roadmap.md',
+    );
+    expect(after).toEqual(before);
+
+    await reallyMove('Work/plan.md', 'Work/roadmap.md');
+    expect(await verbsAt(service(), 'Work/roadmap.md')).toEqual(after);
+  });
+
+  it('a single file answers exactly as the gates at the destination do', async () => {
+    await write({
+      ...BASE,
+      'Work/access.md': rules(`write:\n  - Mover <${MOVER}>\n`),
+      'Work/note.md': '# Note\n',
+      'Legal/access.md': rules('read:\n  - everyone\n'),
+    });
+
+    const svc = service();
+    const after = await svc.previewAccessAfterRelocation(workspaceId, MOVER, 'Work/note.md', 'Legal/note.md');
+
+    expect(after).toEqual(await verbsAt(svc, 'Legal/note.md'));
+
+    await reallyMove('Work/note.md', 'Legal/note.md');
+    expect(await verbsAt(service(), 'Legal/note.md')).toEqual(after);
+  });
+
+  it('answers the caller\'s own verbs and nothing else, and writes nothing', async () => {
+    await write({
+      ...BASE,
+      'Sales/access.md': rules(`read:\n  - deny everyone\n  - Mover <${MOVER}>\nowner:\n  - Mover <${MOVER}>\n`),
+      'Sales/deal.md': '# Deal\n',
+    });
+
+    const svc = service();
+    const after = await svc.previewAccessAfterRelocation(workspaceId, MOVER, 'Sales', 'Revenue');
+
+    // Four booleans. Nothing about who else holds what, and nothing out of
+    // an `access.md` the caller may not read.
+    expect(Object.keys(after).sort()).toEqual(['download', 'owner', 'read', 'write']);
+    for (const v of Object.values(after)) expect(typeof v).toBe('boolean');
+
+    // A stranger gets their own answer, not the caller's.
+    expect(await svc.previewAccessAfterRelocation(workspaceId, 'stranger@x.io', 'Sales', 'Revenue'))
+      .toMatchObject({ read: false, owner: false });
+
+    expect(await fs.readFile(path.join(repo, 'Sales/access.md'), 'utf-8')).toContain('owner:');
+    await expect(fs.access(path.join(repo, 'Revenue'))).rejects.toThrow();
+  });
+});

package/src/modules/access/__tests__/access-control.prospective.test.ts

@@ -9,11 +9,12 @@ import { AccessControlService } from '../access-control.service.js';
 import { holderPrincipals } from '../access-view.js';
 
 /**
- * `prospectiveHolders`: who can open and edit a file where it sits, and who
- * could once a move puts it somewhere else. Driven over a real on-disk tree
- * through the public resolver, because the whole point is that the "after"
- * side must be the SAME resolution as a real one — the destination's folder
- * chain with the file's own frontmatter on top — for a path that does not
+ * `prospectiveHolders`: who can open and edit a file or folder where it
+ * sits, and who could once a move puts it somewhere else. Driven over a real
+ * on-disk tree through the public resolver, because the whole point is that
+ * the "after" side must be the SAME resolution as a real one — the
+ * destination's folder chain with whatever travels laid over it, a file's own
+ * frontmatter or a folder's `access.md` files — for a path that does not
  * exist yet and therefore cannot be asked for in the ordinary way.
  */
 
@@ -136,25 +137,100 @@ describe('AccessControlService.prospectiveHolders', () => {
     expect(holderPrincipals(before.read)).toContainEqual({ kind: 'group', name: 'Engineering' });
   });
 
-  it('refuses a folder source rather than resolving it as a file', async () => {
+  /**
+   * A folder carries its own `access.md`, and that file MOVES WITH IT. The
+   * resolver used to refuse the question rather than answer it as if the
+   * folder were a file — the right refusal for the wrong reason, since the
+   * answer it could not give is the one a folder move actually needs.
+   */
+  it('answers a folder source with the rules it carries, at the path they land on', async () => {
     const svc = await makeService(TREE);
 
-    // `Knowledge/Legal` carries its own access.md and governs everything under
-    // it. Resolved as a file it would report the rules of the folder ABOVE it
-    // and none of its own — a confident, wrong answer.
-    await expect(
-      svc.prospectiveHolders(workspaceId, 'Knowledge/Legal', 'Knowledge/Sales/Legal'),
-    ).rejects.toThrow(/folder/i);
+    const { before, after } = await svc.prospectiveHolders(
+      workspaceId,
+      'Knowledge/Legal',
+      'Knowledge/Sales/Legal',
+    );
+
+    // `Knowledge/Legal/access.md` travels, so Engineering keeps both verbs at
+    // the new path — the rules the folder brings, not the ones it is landing
+    // among. Read as a FILE the answer would have been Product's, from
+    // `Knowledge/Sales/access.md` alone.
+    expect(names(before.read)).toContain('Engineering');
+    expect(names(before.write)).toContain('Engineering');
+    expect(names(after.read)).toContain('Engineering');
+    expect(names(after.write)).toContain('Engineering');
+  });
+
+  it('leaves the old parent behind and picks the new one up', async () => {
+    const svc = await makeService({
+      ...TREE,
+      // Engineering's write on Team comes from Legal above it, not from Team.
+      'Knowledge/Legal/Team/access.md': rules('read:\n  - Product\n'),
+      'Knowledge/Legal/Team/plan.md': '# Plan\n',
+    });
+
+    const { before, after } = await svc.prospectiveHolders(
+      workspaceId,
+      'Knowledge/Legal/Team',
+      'Knowledge/Sales/Team',
+    );
+
+    expect(names(before.write)).toContain('Engineering');
+    // Sales grants nobody write, and Team's own file grants only read — so
+    // the write Team held by inheritance does not come along.
+    expect(names(after.write)).not.toContain('Engineering');
+    expect(names(after.read)).toContain('Product');
+  });
+
+  it('a rename of a folder that grants its own access changes nothing', async () => {
+    const svc = await makeService(TREE);
+
+    const { before, after } = await svc.prospectiveHolders(
+      workspaceId,
+      'Knowledge/Legal',
+      'Knowledge/Revenue',
+    );
+
+    expect(names(after.read)).toEqual(names(before.read));
+    expect(names(after.write)).toEqual(names(before.write));
+  });
+
+  /**
+   * A SYMLINK is neither of the two shapes the preview knows. `move_file`
+   * refuses a symlink source outright (`assertNoSymlinkOnPath`), so a link to
+   * a directory must not be described as a folder taking its `access.md`
+   * files along — that would promise the target's rules at a path nothing is
+   * ever going to arrive at. Nothing is read through the link either.
+   */
+  it('a symlink to a folder is not previewed as the folder it points at', async () => {
+    const svc = await makeService(TREE);
+    const repo = path.join(root, workspaceId, KB_DIR);
+    await fs.symlink(path.join(repo, 'Knowledge/Legal'), path.join(repo, 'Knowledge/Sales/alias'));
+
+    const { after } = await svc.prospectiveHolders(
+      workspaceId,
+      'Knowledge/Sales/alias',
+      'Knowledge/alias',
+    );
+
+    // Legal's own rules stayed behind the link: `Knowledge/` has no
+    // `access.md`, so nobody holds anything at the destination.
+    expect(names(after.read)).not.toContain('Engineering');
+    expect(names(after.write)).not.toContain('Engineering');
   });
 
   it('a probe that fails for any reason but absence throws, never a silent "file"', async () => {
     const svc = await makeService(TREE);
-    // A disk fault (EACCES here) must never read as "not a directory": that is
-    // exactly how a folder source would slip past the refusal above, and the
-    // answer it slips into names the wrong principals. Spied rather than
-    // staged with mode bits, so the property holds as root and on Windows too.
-    const real = fs.stat;
-    const spy = vi.spyOn(fs, 'stat').mockImplementation(((p: string) =>
+    // A disk fault (EACCES here) must never read as "not a directory": the
+    // probe is what chooses between the two resolutions, so a folder read as
+    // a file would be answered with frontmatter it does not have and without
+    // the `access.md` files it carries — the wrong principals, named with
+    // the same confidence as the right ones. Spied rather than staged with
+    // mode bits, so the property holds as root and on Windows too. `lstat`,
+    // because that is the probe: a symlink is classified by what it IS.
+    const real = fs.lstat;
+    const spy = vi.spyOn(fs, 'lstat').mockImplementation(((p: string) =>
       String(p).endsWith('contract.md')
         ? Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }))
         : (real as (p: string) => Promise<unknown>).call(fs, p)) as never);

package/src/modules/access/__tests__/access.routes.prospective.test.ts

@@ -10,7 +10,6 @@ import type { WorkflowService } from '../../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { Database } from '../../database/connection.js';
 import { createAccessRoutes } from '../access.routes.js';
-import { WorkflowDomainError } from '../../../shared/domain-errors.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
@@ -192,15 +191,15 @@ describe('GET /access/prospective', () => {
     expect(await res.json()).toEqual({ error: 'Internal error.' });
   });
 
-  it('refuses a folder source the way the resolver does, without guessing', async () => {
+  it('asks about a folder source the same way, keeping its name at the destination', async () => {
     h = await makeHarness();
-    h.prospectiveHolders.mockRejectedValueOnce(
-      new WorkflowDomainError('prospective access answers for a file, not a folder', 400),
-    );
 
-    const res = await get(`from=${encodeURIComponent('Knowledge/Legal')}&toDir=Knowledge`);
+    const res = await get(`from=${encodeURIComponent('Knowledge/Legal')}&toDir=${encodeURIComponent('Knowledge/Sales')}`);
 
-    expect(res.status).toBe(400);
+    expect(res.status).toBe(200);
+    // The route derives the destination from the name, folder or file alike;
+    // which of the two it is, and what travels with it, is the resolver's.
+    expect(h.prospectiveHolders).toHaveBeenCalledWith(WS, 'Knowledge/Legal', 'Knowledge/Sales/Legal');
   });
 
   it('falls back to the name-only roles list when the resolver omits kinds', async () => {

package/src/modules/access/access-control.interface.ts

@@ -84,11 +84,14 @@ export type HolderList = {
 export type PathHolders = { read: HolderList; write: HolderList };
 
 /**
- * One file's holders where it is now and where a move would put it — see
- * {@link IAccessControl.prospectiveHolders}.
+ * One file's or folder's holders where it is now and where a move would put
+ * it — see {@link IAccessControl.prospectiveHolders}.
  */
 export type ProspectiveHolders = { before: PathHolders; after: PathHolders };
 
+/** One caller's own verdict per access verb on one path. */
+export type PathVerbs = { read: boolean; write: boolean; download: boolean; owner: boolean };
+
 /**
  * Per-verb sources of a principal's access on a target. Only verbs the principal
  * actually holds (via a named file entry) appear; each maps to the closest-first
@@ -358,19 +361,17 @@ export interface IAccessControl {
   }>;
 
   /**
-   * Who can open and who can edit one file where it IS, and where a move
-   * would put it. `toPath` names a path that does not exist yet — the point
-   * of the call is to answer before the move happens — so the resolution
-   * layers the file's OWN rules (its frontmatter, read from `fromPath`,
-   * which travels with the bytes) over the destination's folder chain.
+   * Who can open and who can edit one file or folder where it IS, and where a
+   * move would put it. `toPath` names a path that does not exist yet — the
+   * point of the call is to answer before the move happens — so the
+   * resolution is over what travels with the bytes: a file's OWN rules (its
+   * frontmatter, read from `fromPath`) layered over the destination's folder
+   * chain, or a folder's `access.md` files keyed at the directories they
+   * land in. Either way the rules the source inherited from its old parent
+   * are left behind and the new parent's apply.
    *
    * Writes nothing and moves nothing. The move confirmation diffs the two
    * sides to name who loses and who gains access.
-   *
-   * A FILE question only: a `fromPath` that is a directory is refused with a
-   * 400. A folder's access is its own `access.md` — which moves with it and
-   * governs everything beneath it — so resolving it as a file would name the
-   * wrong principals with the same confidence as the right ones.
    */
   prospectiveHolders(
     workspaceId: string,
@@ -378,6 +379,36 @@ export interface IAccessControl {
     toPath: string,
   ): Promise<ProspectiveHolders>;
 
+  /**
+   * The CALLER'S OWN `{ read, write, download, owner }` at `toPath` as they
+   * will be once `fromPath` has been moved (`sourceRemains: false`, the
+   * default) or copied (`sourceRemains: true`) there — the question a move's
+   * or copy's dry run asks, which the same four gates at `toPath` cannot
+   * answer because what travels with the bytes is not at the destination yet:
+   * the `access.md` files inside a folder, keyed at the directories they land
+   * in, and a file's own frontmatter.
+   *
+   * What a single file's rules GOVERN follows the name it lands under, not the
+   * one it leaves: landing as a directory's `access.md` they are that
+   * directory's rules (so copying `Sales/access.md` to `Legal/access.md`
+   * previews the access `Legal/` is about to have), and landing under any
+   * other name they are the file's own and govern nothing but it. Either way
+   * the answer is the one the gates will give a moment later.
+   *
+   * PREVIEW ONLY. It describes a tree that does not exist, so it must never
+   * decide whether an operation may run: the gates keep resolving against the
+   * tree that does. It writes nothing and moves nothing, and it answers the
+   * caller's own verbs only — never the content of an `access.md` they may
+   * not read.
+   */
+  previewAccessAfterRelocation(
+    workspaceId: string,
+    userEmail: string,
+    fromPath: string,
+    toPath: string,
+    opts?: { sourceRemains?: boolean },
+  ): Promise<PathVerbs>;
+
   /**
    * Finite expanded email set for configured users who could approve this path
    * — role members + direct user grants, minus anyone denied. The built-in