@bevel-software/platform-core-backend 0.34.0 → 0.36.1

package/src/modules/workspace/workspace.tools.ts

@@ -15,9 +15,9 @@ import type { IRoutineWritePolicy } from './routine-write-policy.js';
 import type { ToolHandlerFactory } from '../tool-helpers/index.js';
 import { requireInternalSource, requireExternalSource } from '../tool-auth/index.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import { GitInternalsError, WorkflowValidationError } from '../../shared/domain-errors.js';
+import { GitInternalsError, VersionControlValidationError } from '../../shared/domain-errors.js';
 // Leaf-level shared primitive (same exception `workspace.service.ts` already
-// relies on) — not a workflow service, so this stays inside the module boundary.
+// relies on) — not a version-control service, so this stays inside the module boundary.
 import {
   assertInsideRepo,
   assertRepoRootNameFree,
@@ -249,6 +249,14 @@ const int = (description: string): JsonSchema => ({ type: 'integer', description
 
 const str = (description: string): JsonSchema => ({ type: 'string', description });
 
+/**
+ * A write to the default branch is live at once, so the agent asks first. Said on the four
+ * tools behind 87 of the 91 writes there in the agent-guide benchmark (2026-10-26); `start-here`
+ * says it for the other write tools.
+ */
+const ASK_BEFORE_DEFAULT_BRANCH =
+  ' On the default branch a write is live for everyone at once: unless the person already said where, ask them first whether to write there or propose it on a draft.';
+
 /**
  * The upload route, named on every tool that takes content as a JSON string.
  *
@@ -661,7 +669,7 @@ function refuseEntry(entry: Record<string, unknown>, err: unknown): void {
     entry.message = err.message;
     return;
   }
-  if (err instanceof GitInternalsError || err instanceof WorkflowValidationError) {
+  if (err instanceof GitInternalsError || err instanceof VersionControlValidationError) {
     entry.error = (err.payload as { kind?: string } | undefined)?.kind ?? 'refused';
     entry.message = err.message;
     return;
@@ -1113,8 +1121,9 @@ export function registerWorkspaceTools(
    */
   uploads?: AgentUploadStore,
   /**
-   * The platform's agent guide (see `modules/agent-guide`), which `read_file`
-   * and `file_stat` answer at the guide's name in the repository root — after
+   * The start of the platform's agent guide and the list of its sections
+   * (`guideStartText` in `modules/agent-guide`), which `read_file` and
+   * `file_stat` answer at the guide's name in the repository root — after
    * the knowledge base's own file of that name, when it has one. Optional for
    * the harnesses that are about the file primitives; without it the two
    * tools read the disk and nothing else.
@@ -1137,7 +1146,8 @@ export function registerWorkspaceTools(
   /**
    * The one tree walk (see `shared/fs.contract.ts`), for the `firstRun`
    * note's look at the knowledge folder. Optional for the harnesses about the
-   * file primitives; without it `start_session` answers the id alone.
+   * file primitives; without it `start_session` answers
+   * `{ sessionId, defaultBranch }` and never `firstRun`.
    */
   disk?: ITreeWalker,
   /**
@@ -1524,7 +1534,7 @@ export function registerWorkspaceTools(
 
   /**
    * The paths among `paths` the caller may NOT write, judged exactly as the
-   * lock gate judges them (`WorkflowService.acquireLock`): on a protected
+   * lock gate judges them (`VersionControlService.acquireLock`): on a protected
    * branch only, against the access tree at HEAD, with no rules at HEAD
    * meaning allow. Empty on a draft branch — changes there reach a protected
    * branch only through a change request.
@@ -2010,18 +2020,21 @@ export function registerWorkspaceTools(
   const startSessionDef = toolDef({
     name: 'start_session',
     description:
-      'Mint this conversation\'s id: the `sessionId` KnowledgeBase tools take. Call this ONCE, at the start of your work — minting a new id mid-run starts a second conversation as far as the server is concerned. The id is also a chat session in the app, so you can hand the SAME id to the `ask` tool: your reads and your questions are then one conversation. Pass the returned id as `sessionId` on every later KnowledgeBase tool call, inside `call_tool_chain` too. RETRYING IS SAFE: a call that fails created nothing, so retry it. If a retry lands after a success you hold two independent ids, which is harmless: keep passing the one you already used and ignore the other. Returns `{ sessionId }`, plus `firstRun` while the knowledge base is still empty: a note to act on.',
+      'Mint this conversation\'s id: the `sessionId` KnowledgeBase tools take. Call this ONCE, at the start of your work — minting a new id mid-run starts a second conversation as far as the server is concerned. Pass the returned id as `sessionId` to every tool whose arguments list it, inside `call_tool_chain` too; the others refuse it. Where the deployment offers an `ask` tool, hand it the SAME id: your reads and your questions are then one conversation. RETRYING IS SAFE: a call that fails created nothing, so retry it. If a retry lands after a success you hold two independent ids, which is harmless: keep passing the one you already used and ignore the other. Returns `{ sessionId, defaultBranch }`, plus `firstRun` while the knowledge base is empty: a note to act on.',
     path: '/api/agent/tools/start_session',
     inputs: { type: 'object', properties: {}, additionalProperties: false },
     outputs: {
       type: 'object',
       properties: {
-        sessionId: str('The minted session id — pass it as `sessionId` on subsequent KnowledgeBase tool calls and to `ask`.'),
+        sessionId: str('The minted session id — pass it as `sessionId` to the tools that take one, and to `ask` where there is one.'),
+        defaultBranch: str(
+          "The deployment's default branch: the branch people read, and the one to pass as `branch` unless you are working on a draft.",
+        ),
         firstRun: str(
           `Present only while the knowledge base holds nothing but its starter guide (and a starter pack's untouched pages): what to offer the person (the guide's \`${FIRST_RUN_SECTION_ID}\` section says how).`,
         ),
       },
-      required: ['sessionId'],
+      required: ['sessionId', 'defaultBranch'],
     },
     tags: ['workspace'],
   });
@@ -2040,8 +2053,11 @@ export function registerWorkspaceTools(
     requireExternalSource,
     toolHandler(async (_args, ctx) => {
       const { sessionId } = await sessionSink.createSession(ctx.user.id, new Date());
+      // Read here, not at registration: the setup save applies a branch model
+      // to the running graph, and the name in effect is the one to give.
+      const defaultBranch = kb.defaultBranch;
       const firstRun = await firstRunFor(ctx);
-      return firstRun ? { sessionId, firstRun } : { sessionId };
+      return firstRun ? { sessionId, defaultBranch, firstRun } : { sessionId, defaultBranch };
     }),
   );
 
@@ -2234,7 +2250,7 @@ export function registerWorkspaceTools(
       'Read a workspace file as text. Returns `{ path, content, canWrite }`. Per the shared content rule: text as ' +
       'text, documents and email as extracted text, an image as the picture, anything else as a one-line ' +
       'description. Also reads a `__tool_chain_spill__/…` ref back from a truncated `call_tool_chain`: it ' +
-      'belongs to no workspace, so `branch` is ignored and no `canWrite` comes back. `offset`/`limit` slice the ' +
+      'belongs to no workspace: any existing `branch` will do, and no `canWrite` comes back. `offset`/`limit` slice the ' +
       'content (characters; bytes for a spill ref; ignored for an image): page through large files and ' +
       'spills, never read multi-MB whole. `canWrite`: may you change this file directly on the default branch. ' +
       CAN_WRITE_CLAUSE,
@@ -2243,8 +2259,8 @@ export function registerWorkspaceTools(
       properties: {
         branch: BRANCH_INPUT,
         path: str(`Path to read, under \`${kbDirName}/\` (e.g. \`${kbDirName}/KnowledgeBase/Foo.md\`), with or without a leading slash — a path without that prefix is placed under \`${kbDirName}/\` — or a \`__tool_chain_spill__/…\` ref from a truncated \`call_tool_chain\`, or a \`__tmp__/…\` ref to a file you staged in the workspace's tmp folder.`),
-        offset: int('Start character index (default 0).'),
-        limit: int('Max characters to return from `offset`.'),
+        offset: int('Start character index (bytes for a spill ref; default 0).'),
+        limit: int('Max characters to return from `offset` (bytes for a spill ref).'),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'path'],
@@ -2919,6 +2935,7 @@ export function registerWorkspaceTools(
     description:
       'Write a workspace TEXT file. The change is committed + pushed as you. Returns `{ path, bytes, outcome }`, where `outcome` is ' +
       '`created`, `replaced` or `updated`.' +
+      ASK_BEFORE_DEFAULT_BRANCH +
       UPLOAD_ROUTE_NOTE,
     inputs: {
       type: 'object',
@@ -3009,6 +3026,7 @@ export function registerWorkspaceTools(
       '`created` / `replaced` / `updated` for a path it wrote, or `refused` with `error` (the code) and `message` (why) for a ' +
       'path it could not. `count` is how many were written. A path it refuses — the mode said no, or the file is not text — ' +
       'does not stop the others; read `files` to see what landed.' +
+      ASK_BEFORE_DEFAULT_BRANCH +
       UPLOAD_ROUTE_NOTE,
     inputs: {
       type: 'object',
@@ -3046,7 +3064,7 @@ export function registerWorkspaceTools(
                 enum: ['created', 'replaced', 'updated', 'refused'],
                 description: 'What happened at this path. `refused` means nothing was written there and the file is untouched.',
               },
-              error: str('Present when `outcome` is `refused`: the refusal code — `exists`, `missing` or `binary_not_writable`.'),
+              error: str('Present when `outcome` is `refused`: the refusal code, such as `exists`, `missing`, `binary_not_writable` or a code of the deployment\'s own write check.'),
               message: str('Present when `outcome` is `refused`: the full refusal, the same one write_file would have given.'),
             },
             required: ['path', 'outcome'],
@@ -3073,7 +3091,7 @@ export function registerWorkspaceTools(
       for (const f of files) writePolicy.assertPathWritable(ctx.sessionId, f.path);
       const fs = await ctx.getFilesystem(a.branch as string);
       // `write: true` guarantees a LockingFilesystem here; `writeFiles` lands the
-      // batch as one commit. Structural cast avoids a workflow-internal import.
+      // batch as one commit. Structural cast avoids a version-control-internal import.
       const batching = fs as unknown as {
         writeFiles(
           writes: { path: string; content: string }[],
@@ -3181,6 +3199,7 @@ export function registerWorkspaceTools(
     gated: true,
     description:
       'Replace an exact string in a workspace TEXT file. `old_string` must appear exactly once unless `replace_all`. Committed + pushed as you.' +
+      ASK_BEFORE_DEFAULT_BRANCH +
       UPLOAD_ROUTE_NOTE,
     inputs: {
       type: 'object',
@@ -3260,7 +3279,8 @@ export function registerWorkspaceTools(
     name: 'delete_file',
     gated: true,
     description:
-      'Delete ONE workspace file. Committed + pushed as you. Its folder stays, even when this was its last file. Files only: a folder is refused with a pointer to `delete_folder`.',
+      'Delete ONE workspace file. Committed + pushed as you. Its folder stays, even when this was its last file. Files only: a folder is refused with a pointer to `delete_folder`.' +
+      ASK_BEFORE_DEFAULT_BRANCH,
     inputs: {
       type: 'object',
       properties: {
@@ -3418,7 +3438,7 @@ export function registerWorkspaceTools(
         // ordering trick to keep the rest governed on the way — nothing lands
         // until all of it does. The placeholders go too: this is the one
         // operation that removes a folder. Structural cast, as `write_files`
-        // does, to avoid importing the workflow-internal class here.
+        // does, to avoid importing the version-control-internal class here.
         if (files.length > 0) {
           const batch = fs as unknown as {
             writeFiles(
@@ -3484,10 +3504,11 @@ export function registerWorkspaceTools(
     description:
       'Move or rename a workspace FILE or FOLDER; a folder moves recursively, with everything under it. `dest` is the full new path, not the folder to move into. Committed + pushed as you. ' +
       'The destination must not exist — a move never overwrites a file or merges into a folder. Access follows the ' +
-      'DESTINATION folder, so a move can change what you (and others) may do with the file: the dry run answers ' +
-      '`{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }`, where `access` is your ' +
-      'own `{ read, write, download, owner }` at the source and at the destination AS IT WILL BE once the move has landed, ' +
-      'with every `access.md` inside a moved folder counted at its new place, and a move whose `accessChanges` is true wants `confirm: true`. ' +
+      'DESTINATION folder, so a move can change who may open or edit the file. You must be able to read what moves and the folder it lands in, ' +
+      'or it is refused as read_file refuses. The dry run answers ' +
+      '`{ src, dest, kind, descendants, access: { before, after }, accessChanges, holderChanges?, allowed, reason? }`: your own ' +
+      'access at both ends, and who else loses or gains it. A move that changes either wants `confirm: true`; tell the person ' +
+      'who loses and who gains before you confirm. ' +
       'Links are rewritten by default, in one commit with the move: those in the moved files and those in other markdown files pointing at them (`links` reports them). `rewriteLinks: false` turns that off. Path mentions in plain prose or code are never changed.',
     inputs: {
       type: 'object',
@@ -3496,7 +3517,7 @@ export function registerWorkspaceTools(
         src: wsPath(kbDirName, 'Source path (file or folder)'),
         dest: wsPath(kbDirName, 'Destination path — the full new path; must not exist yet'),
         dryRun: { type: 'boolean', description: 'Answer with the impact and change nothing.' },
-        confirm: { type: 'boolean', description: 'Required when the move changes your access. Set it only after a dry run.' },
+        confirm: { type: 'boolean', description: 'Required when the move changes your access or anyone else\'s. Set it only after a dry run.' },
         rewriteLinks: { type: 'boolean', description: 'Rewrite the links into, out of and between the moved files (default true). `false` moves without touching any link.' },
         sessionId: SESSION_ID_INPUT,
       },
@@ -3510,8 +3531,14 @@ export function registerWorkspaceTools(
         dest: str('Destination path (echoes the input).'),
         kind: str('`file` or `folder`.'),
         descendants: int('Files that move: 1 for a file, the file count under a folder.'),
-        access: { type: 'object', description: 'Your `{ read, write, download, owner }` at the source (`before`) and at the destination once the move has landed (`after`).' },
+        access: { type: 'object', description: 'Your `{ read, write, download, owner }` at the source (`before`) and at the destination once the move has landed (`after`), with every `access.md` inside a moved folder counted at its new place.' },
         accessChanges: { type: 'boolean', description: 'True when any of your verdicts differs between `before` and `after`.' },
+        holderChanges: {
+          type: 'object',
+          description:
+            'Who loses and who gains opening (`read`) or editing (`write`) it once the move has landed: `{ lose, gain }`, each ' +
+            '`[{ kind, name, email?, verb }]` with `kind` `group`, `role`, `plugin` or `person`. Absent when nobody\'s access changes.',
+        },
         allowed: { type: 'boolean', description: 'Whether the move may run.' },
         reason: str('Why it may not, when `allowed` is false.'),
         dryRun: { type: 'boolean', description: 'True on a dry run.' },
@@ -3541,6 +3568,23 @@ export function registerWorkspaceTools(
       // source already deleted.
       await assertAgentWriteAllowed(agentAccessGate, ctx, branch, src);
       await assertAgentWriteAllowed(agentAccessGate, ctx, branch, dest);
+      // What moves and the folder it lands in must both be readable to the
+      // caller, refused as read_file refuses them, on every branch: a move
+      // preview reads both ends (the caller's own verdicts there, who else is
+      // affected), and the folder's rules are what the names are made of. The
+      // verdict comes BEFORE every other look, so neither end's existence is
+      // told to someone who may not know it. The deployment's read hook is
+      // asked first, as read_file asks it, and its refusal is the answer: a
+      // move the hook would not let read is not previewed at all, since even
+      // "this move asks for confirm" would tell what the comparison found. A
+      // folder the caller may read moves with everything in it, files they
+      // may not read included: those travel, they are not read.
+      const destFolder = dest.slice(0, dest.lastIndexOf('/'));
+      await notifyAgentRead(agentAccessGate, ctx, branch, src);
+      await notifyAgentRead(agentAccessGate, ctx, branch, destFolder);
+      const gate = readGateFor(branch, ctx);
+      await assertCanRead(gate, src);
+      await assertCanRead(gate, destFolder);
       const fs = await ctx.getFilesystem(branch);
       const root = await workspaceRoot(branch, ctx);
       // Before the kind check, which stats THROUGH a link: a dangling link at
@@ -3564,6 +3608,17 @@ export function registerWorkspaceTools(
         accessAfter(branch, ctx, src, dest),
       ]);
       const accessChanges = verbsDiffer(before, after);
+      // Who ELSE gains or loses opening or editing it: the lists the app's move
+      // confirmation shows people. The caller may read both ends (the hook and
+      // the rules, gated above, as the app's route gates), so the names go to
+      // them, and a change asks for `confirm`. Outside the repository no rules
+      // travel.
+      const fromRel = toKbRelative(src, kbDirName);
+      const toRel = toKbRelative(dest, kbDirName);
+      const changes = fromRel !== null && toRel !== null
+        ? await accessControl.prospectiveHolderChanges(workspaceIdForBranch(branch), fromRel, toRel)
+        : undefined;
+      const othersChange = changes !== undefined && (changes.lose.length > 0 || changes.gain.length > 0);
       // The placeholder moves with its folder, but it is never content.
       const descendants = srcFiles.filter((f) => !isFolderPlaceholder(f)).length;
       // Neither end may be the platform's own: a move neither takes a platform
@@ -3671,6 +3726,7 @@ export function registerWorkspaceTools(
         descendants,
         access: { before, after },
         accessChanges,
+        ...(othersChange ? { holderChanges: changes } : {}),
         allowed: moveReason === undefined,
         ...(moveReason !== undefined ? { reason: moveReason } : {}),
         ...(linkPlan ? { links: linkPlan.report } : {}),
@@ -3686,12 +3742,16 @@ export function registerWorkspaceTools(
       }
       if (collision) throw new ToolError(reason!, 409);
       if (linkPlan?.overCap !== undefined) throw new ToolError(linkPlan.overCap, 400);
-      if (accessChanges && a.confirm !== true) {
+      if ((accessChanges || othersChange) && a.confirm !== true) {
+        const why = [
+          ...(accessChanges ? [`your access at "${dest}" differs from "${src}"`] : []),
+          ...(othersChange ? ['it changes who else may open or edit it (`holderChanges`)'] : []),
+        ];
         return {
           ...impact,
           confirmationRequired: true,
           moved: false,
-          message: `Nothing was moved: your access at "${dest}" differs from "${src}", so this move requires confirm: true.`,
+          message: `Nothing was moved: ${why.join(', and ')}, so this move requires confirm: true.`,
         };
       }
       // The look above is what produces the sentence; the filesystem's own
@@ -3741,8 +3801,8 @@ export function registerWorkspaceTools(
     gated: true,
     description:
       'Copy a workspace FILE to a new path. The destination must not exist — like a move, a copy never overwrites a file or a folder; to change what is in a file that already exists, write it. Committed + pushed as you. `src` may be a `__tmp__/<path>` ref to a file you staged in the workspace\'s tmp folder: the copy is how such a file is kept, as a normal repository file. ' +
-      'Preflight first: `dryRun: true` changes nothing and answers `{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }` — `access` is your own `{ read, write, download, owner }` at the source and at the destination AS IT WILL BE once the copy has landed, with every `access.md` inside a copied folder counted at its new place. ' +
-      'One exception to that shape: when the destination is one you may not write, the answer is the refusal alone — `allowed: false` with `reason`, and no `kind` and no `descendants`, because nothing about the source is read before that verdict.',
+      'Preflight first: `dryRun: true` changes nothing and answers `{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }` — `access` is your own `{ read, write, download, owner }` at the source and at the destination AS IT WILL BE once the copy has landed, with the copy\'s own rules counted at its new place. ' +
+      'One exception to that shape: when the destination is one you may not write, the answer is the refusal (`allowed: false` with `reason`, and the access figures) with no `kind` and no `descendants`, because nothing about the source is read before that verdict.',
     inputs: {
       type: 'object',
       properties: {
@@ -4203,7 +4263,7 @@ export function registerWorkspaceTools(
         '`replaced` / `updated`, or `refused` with `error` (the code) and `message` (why). `count` is how many landed and ' +
         '`total` how many paths there were; `files` is cut to the first 25 unless you pass `all: true`. ' +
         'Every path is judged one by one — by your write access, the platform-file rules and what is already there — ' +
-        'exactly as `write_file` judges it, and a refused path does not stop the others. ' +
+        'as `write_file` judges it, except that platform files are refused and binary content is fine; a refused path does not stop the others. ' +
         'The token is single-use: it is spent by the apply that lands it, and refused if you use it twice, let it ' +
         'expire, or present one issued to somebody else. `mode` means what it means on `write_file`.',
       inputs: {
@@ -4287,7 +4347,7 @@ export function registerWorkspaceTools(
         'each one inside a folder too, is included only if you may read AND download that file. Returns ' +
         '`{ expiresAt, expiresInSeconds, files: [{ path, bytes, sha256, downloadUrl }], folders: [{ path, bytes, ' +
         'downloadUrl, files }], refused: [{ path, reason }] }`: a link per file, with its own content type, and per ' +
-        `folder a zip at full repository paths (\`apply_file_upload\` it at \`${kbDirName}/\` to put every file back). ` +
+        `folder a zip at full repository paths (\`apply_file_upload\` it at \`${kbDirName}/\` to put them back). ` +
         'Fetch with any HTTP client (`curl -o <name> "<downloadUrl>"`, or the address without its last segment and an ' +
         '`x-download-token` header). Each link works ONCE, for 15 minutes, and serves the files as they are now. ' +
         'Refused: `not found` (missing or named-but-unreadable; folders omit unreadable files), ' +

package/src/shared/__tests__/canonical-file-identity.test.ts

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { describe, it, expect } from 'vitest';
 import { assertValidRelativePath } from '@bevel-software/platform-shared';
 import { canonicalFileIdentity } from '../canonical-file-identity.js';
-import { PathTraversalError, WorkflowValidationError } from '../domain-errors.js';
+import { PathTraversalError, VersionControlValidationError } from '../domain-errors.js';
 
 /**
  * Two properties, and the second is the one worth the file.
@@ -75,9 +75,9 @@ describe('canonicalFileIdentity', () => {
   });
 
   it('refuses a path that climbs out rather than resolving it away', () => {
-    expect(() => canonicalFileIdentity('../etc/passwd')).toThrow(WorkflowValidationError);
+    expect(() => canonicalFileIdentity('../etc/passwd')).toThrow(VersionControlValidationError);
     expect(() => canonicalFileIdentity('knowledge-base/../../etc/passwd')).toThrow(
-      WorkflowValidationError,
+      VersionControlValidationError,
     );
   });
 
@@ -86,7 +86,7 @@ describe('canonicalFileIdentity', () => {
     // containment check alone would wave it through under a second identity
     // for `knowledge-base/y.md`.
     expect(() => canonicalFileIdentity('knowledge-base/x/../y.md')).toThrow(
-      WorkflowValidationError,
+      VersionControlValidationError,
     );
   });
 
@@ -115,7 +115,7 @@ describe('canonicalFileIdentity', () => {
     // 400 for that same body.
     for (const notAPath of [123, true, {}, [], ['a.md'], null, undefined]) {
       expect(() => canonicalFileIdentity(notAPath as unknown as string)).toThrow(
-        WorkflowValidationError,
+        VersionControlValidationError,
       );
       expect(() => canonicalFileIdentity(notAPath as unknown as string)).toThrow(
         'Invalid path: Path is required',

package/src/shared/__tests__/http-errors.test.ts

@@ -3,8 +3,8 @@ import { domainErrorBody } from '../http-errors.js';
 import {
   PathTraversalError,
   UnreadableArchiveError,
-  WorkflowDomainError,
-  WorkflowValidationError,
+  VersionControlDomainError,
+  VersionControlValidationError,
 } from '../domain-errors.js';
 
 /**
@@ -24,7 +24,7 @@ describe('domainErrorBody', () => {
   });
 
   it('is just the message when the error carries no payload', () => {
-    expect(domainErrorBody(new WorkflowValidationError('Only .zip files can be extracted'))).toEqual({
+    expect(domainErrorBody(new VersionControlValidationError('Only .zip files can be extracted'))).toEqual({
       error: 'Only .zip files can be extracted',
     });
   });
@@ -33,7 +33,7 @@ describe('domainErrorBody', () => {
     // Spread payload-last and the client renders "something else entirely"
     // instead of the refusal. `payload` is a Record<string, unknown>, so this
     // key is expressible and nothing but ordering prevents it.
-    const err = new WorkflowDomainError('The real refusal.', 409, {
+    const err = new VersionControlDomainError('The real refusal.', 409, {
       error: 'something else entirely',
       kind: 'contended',
     });

package/src/shared/__tests__/read-capped.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import { readCapped } from '../read-capped.js';
+
+describe('readCapped', () => {
+  /**
+   * Counting a chunk against the budget after decoding it lets a provider that
+   * answers in one huge chunk put the whole thing through the decoder — the
+   * bound bypassed by exactly the party it exists to bound. Asserted on the
+   * reader directly because a caller's short snippet is identical either way.
+   */
+  it('holds one oversized chunk to the byte budget, not just the loop', async () => {
+    const oneHugeChunk = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode('x'.repeat(5_000_000)));
+        controller.close();
+      },
+    });
+
+    const out = await readCapped(new Response(oneHugeChunk), 8 * 1024);
+
+    expect(out.length).toBe(8 * 1024);
+  });
+
+  it('stops pulling at the budget and cancels a stream that never ends', async () => {
+    // Without the cap this never returns: the stream has no end.
+    let pulls = 0;
+    let cancelled = false;
+    const endless = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        pulls += 1;
+        controller.enqueue(new TextEncoder().encode('z'.repeat(1024)));
+      },
+      cancel() {
+        cancelled = true;
+      },
+    });
+
+    const out = await readCapped(new Response(endless), 2048);
+
+    expect(out).toBe('z'.repeat(2048));
+    expect(pulls).toBe(2);
+    expect(cancelled).toBe(true);
+  });
+
+  it('returns at once on a body of exactly the budget whose stream stays open', async () => {
+    // Asking for one more byte here would wait on a chunk that never comes.
+    let pulls = 0;
+    const openAfterFill = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        pulls += 1;
+        if (pulls === 1) {
+          controller.enqueue(new TextEncoder().encode('a'.repeat(8)));
+          return undefined;
+        }
+        return new Promise<void>(() => {});
+      },
+    });
+    expect(await readCapped(new Response(openAfterFill), 8)).toBe('a'.repeat(8));
+    expect(pulls).toBe(1);
+  });
+
+  it('reads a stream-less response whole, cut to the budget', async () => {
+    const res = new Response('abcdef');
+    // Consume the stream so only `text()` is left, as a mocked response may be.
+    Object.defineProperty(res, 'body', { value: null });
+    expect(await readCapped(res, 4)).toBe('abcd');
+  });
+});

package/src/shared/canonical-file-identity.ts

@@ -23,7 +23,7 @@
  *      the time the validator runs. `WorkspaceService.withPathTurn` runs the
  *      same check first (via the shared `assertValidRelativePath`) and its
  *      `Invalid path: ...` message is what `workspace.routes.sendError` turns
- *      into a 400. Same message here, raised as a 400 `WorkflowValidationError`.
+ *      into a 400. Same message here, raised as a 400 `VersionControlValidationError`.
  *   2. Containment. `withPathTurn` then resolves the path against the
  *      workspace directory and refuses anything landing outside it, which
  *      `sendError` turns into a 403. Step 1 has already rejected every `..`,
@@ -52,13 +52,13 @@
  */
 
 import { canonicalRelativePath, validateRelativePath } from '@bevel-software/platform-shared';
-import { PathTraversalError, WorkflowValidationError } from './domain-errors.js';
+import { PathTraversalError, VersionControlValidationError } from './domain-errors.js';
 
 /**
  * The canonical spelling of `targetPath`, or a throw carrying the status the
  * file verbs answer with for that same input.
  *
- * @throws {WorkflowValidationError} 400, when the path is not a usable
+ * @throws {VersionControlValidationError} 400, when the path is not a usable
  *   workspace-relative path (not a string at all, a `.` or `..` segment, a
  *   backslash, empty).
  * @throws {PathTraversalError} 403, when the path resolves outside the
@@ -74,11 +74,11 @@ export function canonicalFileIdentity(targetPath: string): string {
   // answers. The message is the validator's own for a non-string, so the two
   // 400s read identically as well.
   if (typeof targetPath !== 'string') {
-    throw new WorkflowValidationError('Invalid path: Path is required');
+    throw new VersionControlValidationError('Invalid path: Path is required');
   }
   const canonical = canonicalRelativePath(targetPath);
   const reason = validateRelativePath(canonical);
-  if (reason) throw new WorkflowValidationError(`Invalid path: ${reason}`);
+  if (reason) throw new VersionControlValidationError(`Invalid path: ${reason}`);
   // `validateRelativePath` ACCEPTS `/workspace/a.md` (its leading empty
   // segment is filtered out, leaving two ordinary segments), so absolute is
   // refused here, on its own terms: a workspace-relative path is never