@bevel-software/platform-core-backend 0.26.0 → 0.27.0

package/src/modules/workspace/__tests__/move-links.test.ts

@@ -0,0 +1,261 @@
+import { describe, expect, it, vi } from 'vitest';
+import { MOVE_LINK_EDIT_CAP, UNSEARCHED_SENTENCE, planMoveLinks, type MoveLinksInput } from '../move-links.js';
+
+/**
+ * The plan `move_file` builds for its links: which pages it edits, which it
+ * names and leaves, and what it never discloses.
+ */
+
+const KB = 'knowledge-base';
+
+function inputOf(
+  files: Record<string, string>,
+  over: Partial<MoveLinksInput> = {},
+): MoveLinksInput & { reads: string[] } {
+  const reads: string[] = [];
+  return {
+    src: `${KB}/Old`,
+    dest: `${KB}/New/Old`,
+    branch: 'main',
+    kbDirName: KB,
+    allFiles: Object.keys(files),
+    canRead: async (paths) => new Map(paths.map((p) => [p, true])),
+    writeBlocked: async () => [],
+    readText: async (p) => {
+      reads.push(p);
+      return files[p];
+    },
+    readRefused: async () => false,
+    writeRefusal: async () => null,
+    reads,
+    ...over,
+  };
+}
+
+describe('planMoveLinks', () => {
+  it('edits inbound pages and moved pages, reporting each edit at the file’s new path', async () => {
+    const files = {
+      [`${KB}/Old/One.md`]: '---\nnodeType: "[T](../NodeTypes/Task.md)"\n---\n[two](Two.md)\n',
+      [`${KB}/Old/Two.md`]: 'no links\n',
+      [`${KB}/Index.md`]: '[one](Old/One.md) and [elsewhere](Other.md)\n',
+      [`${KB}/Unrelated.md`]: '[x](Other.md)\n',
+      [`${KB}/Old/pic.png`]: 'binary',
+    };
+    const input = inputOf(files);
+    const plan = await planMoveLinks(input);
+    expect(plan.report).toEqual({
+      filesEdited: 2,
+      linksRewritten: 2,
+      edits: [
+        { path: `${KB}/Index.md`, from: 'Old/One.md', to: 'New/Old/One.md' },
+        { path: `${KB}/New/Old/One.md`, from: '../NodeTypes/Task.md', to: '../../NodeTypes/Task.md' },
+      ],
+      notRewritten: [],
+    });
+    expect(plan.edits.map((e) => [e.lockAt, e.path])).toEqual([
+      [`${KB}/Index.md`, `${KB}/Index.md`],
+      [`${KB}/Old/One.md`, `${KB}/New/Old/One.md`],
+    ]);
+    // Binary files are never read.
+    expect(input.reads).not.toContain(`${KB}/Old/pic.png`);
+  });
+
+  it('a readable page the caller may not change is named with its links, and not edited', async () => {
+    const files = {
+      [`${KB}/Old/One.md`]: 'x\n',
+      [`${KB}/Locked/Page.md`]: '[one](../Old/One.md)\n',
+    };
+    const plan = await planMoveLinks(inputOf(files, { writeBlocked: async (paths) => paths.filter((p) => p.includes('Locked')) }));
+    expect(plan.edits).toEqual([]);
+    expect(plan.report.notRewritten).toEqual([
+      { path: `${KB}/Locked/Page.md`, reason: 'no write access', links: ['../Old/One.md'] },
+    ]);
+  });
+
+  it('a page the caller cannot read is never opened, named or counted — one sentence instead', async () => {
+    const files = {
+      [`${KB}/Old/One.md`]: 'x\n',
+      [`${KB}/Secret/A.md`]: '[one](../Old/One.md)\n',
+      [`${KB}/Secret/B.md`]: '[one](../Old/One.md)\n',
+    };
+    const input = inputOf(files, {
+      canRead: async (paths) => new Map(paths.map((p) => [p, !p.includes('Secret')])),
+    });
+    const plan = await planMoveLinks(input);
+    expect(input.reads.some((p) => p.includes('Secret'))).toBe(false);
+    expect(plan.report.unsearched).toBe(UNSEARCHED_SENTENCE);
+    expect(JSON.stringify(plan.report)).not.toMatch(/Secret|\b2\b/);
+    expect(plan.report.filesEdited).toBe(0);
+  });
+
+  it('transcripts/ and probes/ folders are never searched', async () => {
+    const files = {
+      [`${KB}/Old/One.md`]: 'x\n',
+      [`${KB}/T/transcripts/01.md`]: '[one](../../Old/One.md)\n',
+      [`${KB}/T/probes/p.md`]: '[one](../../Old/One.md)\n',
+    };
+    const input = inputOf(files);
+    const plan = await planMoveLinks(input);
+    expect(plan.report.filesEdited).toBe(0);
+    expect(input.reads.filter((p) => /transcripts|probes/.test(p))).toEqual([]);
+  });
+
+  it('an HTML page is reported, not rewritten', async () => {
+    const files = {
+      [`${KB}/Old/One.md`]: 'x\n',
+      [`${KB}/Board.html`]: '<a href="Old/One.md">one</a>',
+    };
+    const plan = await planMoveLinks(inputOf(files));
+    expect(plan.edits).toEqual([]);
+    expect(plan.report.notRewritten).toEqual([{ path: `${KB}/Board.html`, reason: 'html page', links: ['Old/One.md'] }]);
+  });
+
+  it('raw HTML inside a markdown page is reported, not rewritten — beside the markdown links that are', async () => {
+    const files = {
+      [`${KB}/Old/One.md`]: 'x\n',
+      [`${KB}/Old/pic.png`]: '',
+      // One markdown link, which is rewritten, and one raw `<img>`, which is not.
+      [`${KB}/Gallery.md`]: '[one](Old/One.md)\n\n<img src="Old/pic.png" alt="pic">\n',
+      // A page whose raw HTML points elsewhere is not named.
+      [`${KB}/Other.md`]: '<a href="Elsewhere.md">x</a> mentions Old in prose\n',
+    };
+    const plan = await planMoveLinks(inputOf(files));
+    expect(plan.edits.map((e) => e.path)).toEqual([`${KB}/Gallery.md`]);
+    expect(plan.edits[0].content).toBe('[one](New/Old/One.md)\n\n<img src="Old/pic.png" alt="pic">\n');
+    expect(plan.report.notRewritten).toEqual([
+      { path: `${KB}/Gallery.md`, reason: 'html in markdown', links: ['Old/pic.png'] },
+    ]);
+  });
+
+  it('raw HTML inside code or escaped — a fence, an indented block, a code span, a `\\<` — is an example, not reported', async () => {
+    const files = {
+      [`${KB}/Old/One.md`]: 'x\n',
+      [`${KB}/Howto.md`]:
+        'Write it like `<a href="Old/One.md">` or \\<a href="Old/One.md"> or:\n\n```html\n<a href="Old/One.md">one</a>\n```\n\n' +
+        '    <img src="Old/One.md">\n\nAnd a live one: <a href="Old/One.md">one</a>\n',
+    };
+    const plan = await planMoveLinks(inputOf(files));
+    expect(plan.edits).toEqual([]);
+    expect(plan.report.notRewritten).toEqual([
+      { path: `${KB}/Howto.md`, reason: 'html in markdown', links: ['Old/One.md'] },
+    ]);
+  });
+
+  it(`more than ${MOVE_LINK_EDIT_CAP} edited files is refused, saying how to split or switch off`, async () => {
+    const files: Record<string, string> = { [`${KB}/Old/One.md`]: 'x\n' };
+    for (let i = 0; i <= MOVE_LINK_EDIT_CAP; i++) files[`${KB}/Pages/P${i}.md`] = '[one](../Old/One.md)\n';
+    const writeRefusal = vi.fn(async () => null);
+    const plan = await planMoveLinks(inputOf(files, { writeRefusal }));
+    expect(plan.overCap).toMatch(/201 files.*rewriteLinks: false/s);
+    expect(plan.overCap).toMatch(/subfolder/);
+    expect(plan.edits).toEqual([]);
+    // Nothing is edited, so the write hook hears of nothing.
+    expect(writeRefusal).not.toHaveBeenCalled();
+    // Exactly at the cap is allowed.
+    delete files[`${KB}/Pages/P0.md`];
+    expect((await planMoveLinks(inputOf(files))).overCap).toBeUndefined();
+  });
+
+  it('only edited files reach the hooks; a refusal leaves that file named and unedited', async () => {
+    const files = {
+      [`${KB}/Old/One.md`]: '[t](../T.md)\n',
+      [`${KB}/A.md`]: '[one](Old/One.md)\n',
+      [`${KB}/B.md`]: '[one](Old/One.md)\n',
+      [`${KB}/Searched.md`]: 'mentions Old but links nowhere\n',
+    };
+    const readRefused = vi.fn(async () => false);
+    const writeRefusal = vi.fn(async (_lockAt: string, path: string) =>
+      path.endsWith('B.md') ? 'refused: not in this session' : null);
+    const plan = await planMoveLinks(inputOf(files, { readRefused, writeRefusal }));
+    // The pages the answer names, and not the one merely searched.
+    expect(readRefused.mock.calls.map((c) => c[0]).sort()).toEqual([`${KB}/A.md`, `${KB}/B.md`, `${KB}/Old/One.md`]);
+    expect(writeRefusal.mock.calls.map((c) => c[0]).sort()).toEqual([`${KB}/A.md`, `${KB}/B.md`, `${KB}/Old/One.md`]);
+    expect(plan.edits.map((e) => e.path)).toEqual([`${KB}/A.md`, `${KB}/New/Old/One.md`]);
+    expect(plan.report.notRewritten).toEqual([{ path: `${KB}/B.md`, reason: 'refused: not in this session', links: ['Old/One.md'] }]);
+  });
+
+  it('a page the read hook refuses is treated as unreadable: never named, one sentence instead', async () => {
+    const files = {
+      [`${KB}/Old/One.md`]: 'x\n',
+      [`${KB}/Hidden.md`]: '[one](Old/One.md) [secret](Secret/Target.md)\n',
+    };
+    const plan = await planMoveLinks(inputOf(files, { readRefused: async () => true }));
+    expect(plan.edits).toEqual([]);
+    expect(plan.report.notRewritten).toEqual([]);
+    expect(plan.report.unsearched).toBe(UNSEARCHED_SENTENCE);
+    expect(JSON.stringify(plan.report)).not.toMatch(/Hidden|Secret|read denied/);
+  });
+
+  it('a page the read hook refuses is not named for its raw HTML, nor as one the caller may not change', async () => {
+    // Every way a page gets NAMED passes the same gate: an HTML page, raw
+    // HTML in a markdown page, and a page left unedited for want of write
+    // access are all pages the answer would quote links from.
+    const files = {
+      [`${KB}/Old/One.md`]: 'x\n',
+      [`${KB}/Board.html`]: '<a href="Old/One.md">one</a>',
+      [`${KB}/Gallery.md`]: '<img src="Old/One.md">\n',
+      [`${KB}/Locked.md`]: '[one](Old/One.md)\n',
+      [`${KB}/Shown.md`]: '[one](Old/One.md)\n',
+    };
+    const readRefused = vi.fn(async (path: string) => path !== `${KB}/Shown.md`);
+    const plan = await planMoveLinks(
+      inputOf(files, { readRefused, writeBlocked: async (paths) => paths.filter((p) => p.endsWith('Locked.md')) }),
+    );
+    expect(plan.edits.map((e) => e.path)).toEqual([`${KB}/Shown.md`]);
+    expect(plan.report.notRewritten).toEqual([]);
+    expect(plan.report.unsearched).toBe(UNSEARCHED_SENTENCE);
+    expect(JSON.stringify(plan.report)).not.toMatch(/Board|Gallery|Locked/);
+    // Asked once per page named, never for one merely searched — the moved
+    // file itself links nowhere, so it is not named and not asked about.
+    expect(readRefused.mock.calls.map((c) => c[0]).sort()).toEqual([
+      `${KB}/Board.html`,
+      `${KB}/Gallery.md`,
+      `${KB}/Locked.md`,
+      `${KB}/Shown.md`,
+    ]);
+  });
+
+  it('a link spelling the moved name with percent-encoding or escapes is still found', async () => {
+    const files = {
+      [`${KB}/My Old (1)/One.md`]: 'x\n',
+      [`${KB}/Lower.md`]: '[one](My%20Old%20%281%29/One.md)\n',
+      [`${KB}/Partial.md`]: '[one](My%20Old%20(1)/One.md)\n',
+      [`${KB}/Escaped.md`]: '[one](My%20Old%20\\(1\\)/One.md)\n',
+      [`${KB}/Mixed.md`]: '[one](%4dy%20Old%20%281%29/One.md)\n',
+    };
+    const plan = await planMoveLinks(inputOf(files, { src: `${KB}/My Old (1)`, dest: `${KB}/New/My Old (1)` }));
+    expect(plan.edits.map((e) => e.path).sort()).toEqual([`${KB}/Escaped.md`, `${KB}/Lower.md`, `${KB}/Mixed.md`, `${KB}/Partial.md`]);
+  });
+
+  it('a page gone between the listing and its read is skipped; one that cannot be opened marks the search incomplete', async () => {
+    const files = {
+      [`${KB}/Old/One.md`]: 'x\n',
+      [`${KB}/Gone.md`]: '[one](Old/One.md)\n',
+      [`${KB}/Index.md`]: '[one](Old/One.md)\n',
+    };
+    const failWith = (code: string) => async (p: string) => {
+      if (p.endsWith('Gone.md')) throw Object.assign(new Error(code), { code });
+      return files[p as keyof typeof files];
+    };
+    const gone = await planMoveLinks(inputOf(files, { readText: failWith('ENOENT') }));
+    expect(gone.edits.map((e) => e.path)).toEqual([`${KB}/Index.md`]);
+    expect(gone.report.unsearched).toBeUndefined();
+    // Its folder became a file: gone all the same.
+    const folderGone = await planMoveLinks(inputOf(files, { readText: failWith('ENOTDIR') }));
+    expect(folderGone.edits.map((e) => e.path)).toEqual([`${KB}/Index.md`]);
+    expect(folderGone.report.unsearched).toBeUndefined();
+    const denied = await planMoveLinks(inputOf(files, { readText: failWith('EACCES') }));
+    expect(denied.edits.map((e) => e.path)).toEqual([`${KB}/Index.md`]);
+    expect(denied.report.unsearched).toBe(UNSEARCHED_SENTENCE);
+    expect(JSON.stringify(denied.report)).not.toMatch(/Gone/);
+  });
+
+  it('lists at most 100 edits while counting all of them', async () => {
+    const files: Record<string, string> = { [`${KB}/Old/One.md`]: 'x\n' };
+    for (let i = 0; i < 60; i++) files[`${KB}/Pages/P${i}.md`] = '[a](../Old/One.md) [b](../Old/One.md#x)\n';
+    const plan = await planMoveLinks(inputOf(files));
+    expect(plan.report.filesEdited).toBe(60);
+    expect(plan.report.linksRewritten).toBe(120);
+    expect(plan.report.edits).toHaveLength(100);
+  });
+});

package/src/modules/workspace/__tests__/rest-tool-arguments.test.ts

@@ -0,0 +1,219 @@
+import type { Server as HttpServer } from 'node:http';
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import express from 'express';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { LocalFilesystem } from '@mastra/core/workspace';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import { routeToolSchemas } from '../../tool-helpers/route-tool-schemas.js';
+import type { ToolContext } from '../../tool-helpers/tool.contract.js';
+import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+import { registerWorkspaceTools } from '../workspace.tools.js';
+import { RoutineWritePolicyService } from '../routine-write-policy.js';
+import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { ToolDescriptionNotes } from '../agent-access.gate.js';
+import { SpillStore } from '../spill-store.js';
+import { DocExtractService } from '../file-readers/doc-extract.service.js';
+import { AccessControlService } from '../../access/access-control.service.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { BRANCH_REQUIRED_MESSAGE } from '../../../shared/domain-errors.js';
+import { callLine, compileCheck, exampleArguments } from '@bevel-software/platform-mcp-core';
+
+/**
+ * The REST route a script, a runner or a CI job calls with a connection key —
+ * `POST /api/agent/tools/<name>` — driven against the REAL workspace tools.
+ *
+ * This is the surface the first implementation left unprotected: `write_file`
+ * without `content` answered a 500 `TypeError`, `move_file` without `dest` the
+ * same, and `grep` without `pattern` answered 200 having matched every file in
+ * the knowledge base. The three calls the ticket names are here, with their own
+ * schemas and their own route handlers, so the refusal under test is the one a
+ * caller really gets.
+ */
+
+const KB = 'knowledge-base';
+const BRANCH = 'main';
+
+const TREE: Record<string, string> = {
+  'roles.yaml': 'roles:\n  Admin:\n    - author@x.io\n',
+  'access.md': '---\nread:\n  - everyone\nwrite:\n  - everyone\n---\n',
+  'KnowledgeBase/Note.md': '# Note\n\nthe needle is here\n',
+  'KnowledgeBase/Other.md': '# Other\n\nthe needle is here too\n',
+};
+
+let root = '';
+let docCache = '';
+let base = '';
+let server: HttpServer;
+
+beforeAll(async () => {
+  root = await mkdtemp(join(tmpdir(), 'rest-tool-arguments-'));
+  for (const [rel, text] of Object.entries(TREE)) {
+    const abs = join(root, KB, rel);
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, text);
+  }
+  const workspaceService = {
+    getWorkspacePath: async () => root,
+    ensureRemotesFetched: async () => undefined,
+  } as unknown as Parameters<typeof AccessControlService.prototype.constructor>[0];
+  const access = new AccessControlService(workspaceService as never, KB, new NodeFs());
+  const fs = new LocalFilesystem({ basePath: root, contained: true });
+  const resolve = async (auth: ToolAuth, signal: AbortSignal): Promise<ToolContext> =>
+    ({
+      user: { id: 'u', email: 'author@x.io', name: 'Author' },
+      scope: auth.scope,
+      source: auth.source,
+      abortSignal: signal,
+      workspaceService: workspaceService as never,
+      workflowService: {} as never,
+      events: {} as never,
+      getFilesystem: async () => fs,
+    }) as unknown as ToolContext;
+  const app = express();
+  app.use(express.json());
+  const router = express.Router();
+  docCache = await mkdtemp(join(tmpdir(), 'rest-tool-arguments-doc-'));
+  registerWorkspaceTools(
+    new ToolRegistry(),
+    router,
+    (req, _res, next) => {
+      req.toolAuth = { source: 'external', userId: 'u', scope: 'write' };
+      next();
+    },
+    createToolHandlerFactory(resolve),
+    new SpillStore(join(tmpdir(), 'bevel-test-spills')),
+    new DocExtractService(docCache),
+    access,
+    testKbContext({ kbDirName: KB }),
+    { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
+    new RoutineWritePolicyService(),
+    {} as never,
+  );
+  app.use('/api', router);
+  server = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  base = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+});
+
+afterAll(async () => {
+  await new Promise<void>((r) => server.close(() => r()));
+  await rm(root, { recursive: true, force: true });
+  await rm(docCache, { recursive: true, force: true });
+});
+
+interface Answered {
+  status: number;
+  body: { error?: string; kind?: string; matches?: unknown[]; truncated?: boolean };
+}
+
+/** One call on the REST route, exactly as a script with a connection key makes it. */
+async function callTool(tool: string, body: unknown): Promise<Answered> {
+  const res = await fetch(`${base}/api/agent/tools/${tool}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: 'Bearer connection-key' },
+    body: JSON.stringify(body),
+  });
+  return { status: res.status, body: (await res.json()) as Answered['body'] };
+}
+
+const exists = (rel: string) =>
+  stat(join(root, rel))
+    .then(() => true)
+    .catch(() => false);
+
+describe('POST /api/agent/tools/<name> checks the arguments against the tool', () => {
+  it('refuses write_file without `content` — the 400 with the interface, not a 500, and writes nothing', async () => {
+    const { status, body } = await callTool('write_file', {
+      branch: BRANCH,
+      path: `${KB}/KnowledgeBase/New.md`,
+      sessionId: 's-1',
+    });
+    expect(status).toBe(400);
+    expect(body.kind).toBe('arguments-do-not-match');
+    expect(body.error).toContain('The arguments do not match the "write_file" tool.');
+    expect(body.error).toContain('"content" is required, and was not given.');
+    expect(body.error).toContain('Interface of "write_file":');
+    expect(body.error).toContain('content (string, required)');
+    expect(body.error).toContain('path (string, required)');
+    expect(body.error?.split('\n').pop()).toBe(
+      callLine('KNOWLEDGE_BASE.write_file', routeToolSchemas('write_file')!.wire),
+    );
+    // The call ran nothing: no file was created.
+    expect(await exists(`${KB}/KnowledgeBase/New.md`)).toBe(false);
+  });
+
+  it('refuses move_file without `dest`, and moves nothing', async () => {
+    const { status, body } = await callTool('move_file', {
+      branch: BRANCH,
+      src: `${KB}/KnowledgeBase/Note.md`,
+    });
+    expect(status).toBe(400);
+    expect(body.kind).toBe('arguments-do-not-match');
+    expect(body.error).toContain('"dest" is required, and was not given.');
+    expect(body.error).toContain('dest (string, required)');
+    expect(await readFile(join(root, KB, 'KnowledgeBase/Note.md'), 'utf8')).toContain('the needle is here');
+  });
+
+  it('refuses grep without `pattern`, and searches nothing', async () => {
+    const { status, body } = await callTool('grep', { branch: BRANCH });
+    expect(status).toBe(400);
+    expect(body.kind).toBe('arguments-do-not-match');
+    expect(body.error).toContain('"pattern" is required, and was not given.');
+    expect(body.error).toContain('pattern (string, required) — JavaScript regular expression.');
+    // Not a 200 that matched every file, which is what this surface answered
+    // before the check lived in the route.
+    expect(body.matches).toBeUndefined();
+  });
+
+  it('names an argument of the wrong type, and one the tool does not have', async () => {
+    const wrongType = await callTool('grep', { branch: BRANCH, pattern: 'needle', max_results: 'ten' });
+    expect(wrongType.status).toBe(400);
+    expect(wrongType.body.error).toContain('"max_results" must be integer, but string was given.');
+    const unknown = await callTool('grep', { branch: BRANCH, pattern: 'needle', recursive: true });
+    expect(unknown.status).toBe(400);
+    expect(unknown.body.error).toContain('"recursive" is not an argument of this tool.');
+  });
+
+  it('keeps the refusal that names a missing branch, word for word', async () => {
+    const { status, body } = await callTool('read_file', { path: `${KB}/KnowledgeBase/Note.md` });
+    expect(status).toBe(400);
+    expect(body.kind).toBe('branch-required');
+    expect(body.error).toBe(BRANCH_REQUIRED_MESSAGE);
+  });
+
+  it('passes a matching call on with exactly the arguments that were sent', async () => {
+    const { status, body } = await callTool('grep', {
+      branch: BRANCH,
+      pattern: 'needle',
+      path: `${KB}/KnowledgeBase`,
+      max_results: 1,
+    });
+    expect(status).toBe(200);
+    // `max_results: 1` was honoured, so the argument reached the tool as sent —
+    // the check neither dropped it nor rewrote it.
+    expect(body.matches).toHaveLength(1);
+    expect(body.truncated).toBe(true);
+  });
+
+  it('every mounted tool can be called with its own generated example', async () => {
+    const names = ['read_file', 'write_file', 'move_file', 'grep', 'list_files'];
+    for (const name of names) {
+      const schemas = routeToolSchemas(name);
+      expect(schemas, name).toBeDefined();
+      // The example an agent is told to copy is generated from the WIRE schema;
+      // what its route checks is the FLAT one. Both must accept it, or the
+      // platform publishes an example its own check refuses.
+      const flat = compileCheck(schemas!.flat);
+      expect(flat.checkable, name).toBe(true);
+      if (flat.checkable) expect(flat.check(exampleArguments(schemas!.flat)), name).toEqual([]);
+      const wire = compileCheck(schemas!.wire);
+      expect(wire.checkable, name).toBe(true);
+      if (wire.checkable) expect(wire.check(exampleArguments(schemas!.wire)), name).toEqual([]);
+    }
+  });
+});

package/src/modules/workspace/__tests__/workspace-paths-inside-the-repo.test.ts

@@ -70,6 +70,9 @@ async function makeHarness(): Promise<Harness> {
       asked.push(p);
       return true;
     },
+    // Each file of a zipped folder is judged too; this suite is about where
+    // the FOLDER is placed, so the files all pass.
+    canDownloadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
   } as unknown as IAccessControl;
 
   const locked: string[] = [];

package/src/modules/workspace/__tests__/workspace.routes.delete.test.ts

@@ -15,6 +15,7 @@ import type { IAdminAccessService } from '../../admin/admin.interface.js';
 import { createWorkspaceRoutes } from '../workspace.routes.js';
 import type { ICreatorAccess } from '../../access-model/creator.js';
 import type { WorkspaceService } from '../workspace.service.js';
+import { AccessDeniedError } from '../../access-model/access-errors.js';
 
 const stubCreatorAccess: ICreatorAccess = {
   planForCreate: async () => null,
@@ -46,6 +47,8 @@ interface Harness {
   repoDir: string;
   /** Exposed so a test can assert the PATH the route handed the service. */
   deleteFileMock: ReturnType<typeof vi.fn>;
+  /** Exposed so a test can make the write gate inside it refuse. */
+  acquireLockMock: ReturnType<typeof vi.fn>;
 }
 
 async function makeHarness(): Promise<Harness> {
@@ -125,6 +128,7 @@ async function makeHarness(): Promise<Harness> {
     workspaceDir,
     repoDir: path.join(workspaceDir, KB),
     deleteFileMock: workspaceServiceMock.deleteFile as unknown as ReturnType<typeof vi.fn>,
+    acquireLockMock: workflowServiceMock.acquireLock as unknown as ReturnType<typeof vi.fn>,
   };
 }
 
@@ -218,3 +222,101 @@ describe('DELETE /workspace/:id/file — one file identity', () => {
     }
   });
 });
+
+/**
+ * The root's `access.md` and `roles.yaml` govern the whole repository, so the
+ * app's delete route refuses them — with the sentence `delete_file` and the
+ * explorer use — before a lock is taken. A nested `access.md` is a file like
+ * any other here: the lock gate decides whether the caller may write it.
+ */
+describe('DELETE /workspace/:id/file — the repository\'s own files', () => {
+  let h: Harness | null = null;
+  afterEach(async () => {
+    if (h) {
+      await closeServer(h.server);
+      await fs.rm(h.workspaceDir, { recursive: true, force: true });
+    }
+    h = null;
+  });
+
+  const del = (base: string, p: string) =>
+    fetch(`${base}/api/workspace/${WORKSPACE_ID}/file?path=${encodeURIComponent(p)}`, { method: 'DELETE' });
+
+  it.each(['access.md', 'roles.yaml'])('refuses the root %s with one sentence and leaves it', async (name) => {
+    h = await makeHarness();
+    await fs.mkdir(h.repoDir, { recursive: true });
+    await fs.writeFile(path.join(h.repoDir, name), 'x', 'utf-8');
+
+    const res = await del(h.baseUrl, name);
+
+    expect(res.status).toBe(409);
+    expect(await res.json()).toEqual({ error: `${name} is the repository's own file and cannot be deleted.` });
+    expect(h.deleteFileMock).not.toHaveBeenCalled();
+    expect(await exists(path.join(h.repoDir, name))).toBe(true);
+  });
+
+  it('deletes a nested access.md like any file, and a nested roles.yaml too', async () => {
+    h = await makeHarness();
+    await fs.mkdir(path.join(h.repoDir, 'Team'), { recursive: true });
+    await fs.writeFile(path.join(h.repoDir, 'Team/access.md'), '---\nread: Admin\n---\n', 'utf-8');
+    await fs.writeFile(path.join(h.repoDir, 'Team/roles.yaml'), 'content', 'utf-8');
+    // Not emptied by these deletes, so no placeholder needs keeping.
+    await fs.writeFile(path.join(h.repoDir, 'Team/notes.md'), 'n', 'utf-8');
+
+    for (const p of ['Team/access.md', 'Team/roles.yaml']) {
+      const res = await del(h.baseUrl, p);
+      expect(res.status).toBe(200);
+      expect(h.deleteFileMock).toHaveBeenCalledWith(WORKSPACE_ID, `${KB}/${p}`);
+      expect(await exists(path.join(h.repoDir, p))).toBe(false);
+    }
+  });
+
+  it('refuses a nested access.md with the ordinary write refusal when the caller may not write it', async () => {
+    h = await makeHarness();
+    await fs.mkdir(path.join(h.repoDir, 'Team'), { recursive: true });
+    await fs.writeFile(path.join(h.repoDir, 'Team/access.md'), '---\nwrite: Admin\n---\n', 'utf-8');
+    // The write gate lives inside `acquireLock`; it refuses as it does for any file.
+    const refusal = new AccessDeniedError({ path: 'Team/access.md', eligibleRoles: ['Admin'], eligibleUsers: [] });
+    h.acquireLockMock.mockRejectedValueOnce(refusal);
+
+    const res = await del(h.baseUrl, 'Team/access.md');
+
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe(refusal.message);
+    expect(body.error).not.toContain('platform file');
+    expect(body.error).not.toContain("repository's own file");
+    expect(h.deleteFileMock).not.toHaveBeenCalled();
+    expect(await exists(path.join(h.repoDir, 'Team/access.md'))).toBe(true);
+  });
+
+  it('refuses a reserved top-level folder as delete_folder does, and leaves what it holds', async () => {
+    h = await makeHarness();
+    await fs.mkdir(path.join(h.repoDir, 'KnowledgeBase/Product'), { recursive: true });
+    await fs.writeFile(path.join(h.repoDir, 'KnowledgeBase/Product/Plan.md'), 'p', 'utf-8');
+
+    const res = await del(h.baseUrl, `${KB}/KnowledgeBase`);
+
+    expect(res.status).toBe(409);
+    expect(await res.json()).toEqual({ error: 'KnowledgeBase/ is a platform folder and cannot be moved or deleted.' });
+    expect(h.deleteFileMock).not.toHaveBeenCalled();
+    expect(await exists(path.join(h.repoDir, 'KnowledgeBase/Product/Plan.md'))).toBe(true);
+  });
+
+  it.each([KB, `${KB}/`])('refuses the repository root as a folder (%j) and leaves its own files', async (p) => {
+    h = await makeHarness();
+    await fs.mkdir(path.join(h.repoDir, 'Team'), { recursive: true });
+    await fs.writeFile(path.join(h.repoDir, 'access.md'), 'x', 'utf-8');
+    await fs.writeFile(path.join(h.repoDir, 'roles.yaml'), 'x', 'utf-8');
+    await fs.writeFile(path.join(h.repoDir, 'Team/notes.md'), 'n', 'utf-8');
+
+    const res = await del(h.baseUrl, p);
+
+    expect(res.status).toBe(409);
+    expect(await res.json()).toEqual({ error: 'The repository root is a platform folder and cannot be moved or deleted.' });
+    expect(h.deleteFileMock).not.toHaveBeenCalled();
+    for (const f of ['access.md', 'roles.yaml', 'Team/notes.md']) {
+      expect(await exists(path.join(h.repoDir, f))).toBe(true);
+    }
+  });
+});