@bevel-software/platform-core-backend 0.11.0 → 0.11.2

package/src/modules/workflow/git/git.service.ts

@@ -15,9 +15,9 @@ import type {
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { WorkflowHooks, CommitValidationContext } from '../workflow-hooks.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
-import { AccessDeniedError } from '../../access/access-errors.js';
-import { WorkspaceMutex } from './mutex.js';
-import { cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS } from './clone-config.js';
+import { AccessDeniedError } from '../../access-model/access-errors.js';
+import { WorkspaceMutex } from '../../kb-fs/mutex.js';
+import { cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS } from '../../kb-fs/clone-config.js';
 import {
   assertValidBranchName,
   assertValidRelativePath,
@@ -25,13 +25,13 @@ import {
   isOwnSuggestionsBranch,
   isProtectedBranch,
   PROTECTED_BRANCHES,
-} from './branch-name.js';
+} from '../../kb-fs/branch-name.js';
 import {
   BranchAuthorshipError,
   WorkflowValidationError,
   ProtectedBranchError,
   PullRebaseConflictError,
-} from '../workflow.errors.js';
+} from '../../../shared/domain-errors.js';
 
 const execFileAsync = promisify(execFile);
 

package/src/modules/workflow/git/pull-request.service.ts

@@ -13,7 +13,7 @@ import { changeRequests } from '../../database/schema.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { GitService } from './git.service.js';
-import { WorkflowValidationError } from '../workflow.errors.js';
+import { WorkflowValidationError } from '../../../shared/domain-errors.js';
 import { hashEmail } from '../../../shared/hash-email.js';
 
 const LIST_PR_CACHE_TTL_MS = 30_000;

package/src/modules/workflow/review-workflow/__tests__/cancel-pr.test.ts

@@ -6,7 +6,7 @@ import type { WorkspaceService } from '../../../workspace/workspace.service.js';
 import type { GitService } from '../../git/git.service.js';
 import type { IAccessControl } from '../../../access/access-control.interface.js';
 import { hashEmail } from '../../../../shared/hash-email.js';
-import { WorkflowValidationError } from '../../workflow.errors.js';
+import { WorkflowValidationError } from '../../../../shared/domain-errors.js';
 
 // Cancel is now a DB state flip (no `gh`): `update(change_requests) … WHERE
 // number = ? AND state = 'open'`. This spy stands in for the update's

package/src/modules/workflow/review-workflow/review-workflow.service.ts

@@ -13,13 +13,13 @@ import type {
 import type { Database } from '../../database/connection.js';
 import { changeRequests, prComments, prFileApprovals, prMergeLog } from '../../database/schema.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
-import { isAccessMdPath } from '../../access/access-control.service.js';
+import { isAccessMdPath } from '../../access-model/access-grammar.js';
 import type { GitService } from '../git/git.service.js';
 import {
   ChangeRequestConflictsError,
   WorkflowDomainError,
   WorkflowValidationError,
-} from '../workflow.errors.js';
+} from '../../../shared/domain-errors.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { hashEmail } from '../../../shared/hash-email.js';
 import type {

package/src/modules/workflow/session-ontology.service.ts

@@ -37,7 +37,7 @@ import { ontologyOf } from '../../shared/kb-layout.js';
 import type { Database } from '../database/connection.js';
 import { sessionOntologyTouches } from '../database/schema.js';
 import { recordTouch, decideWrite, type WriteDecision } from './session-ontology.policy.js';
-import { WorkspaceMutex } from './git/mutex.js';
+import { WorkspaceMutex } from '../kb-fs/mutex.js';
 
 export type OperationDecision =
   | { allow: true; touched: string[] }

package/src/modules/workflow/workflow.routes.ts

@@ -27,9 +27,9 @@ import type {
 } from '@bevel-software/platform-shared';
 import type { AuthService } from '../auth/auth.service.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
-import { branchForWorkspaceId } from '../workspace/workspace.service.js';
+import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { WorkflowEventBus } from './event-bus.js';
-import { WorkflowDomainError } from './workflow.errors.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import '../auth/auth.middleware.js'; // Express Request augmentation
 
 function toHttpError(

package/src/modules/workflow/workflow.service.ts

@@ -49,14 +49,14 @@ import type { GitService } from './git/git.service.js';
 import type { PullRequestService } from './git/pull-request.service.js';
 import type { IReviewWorkflowService } from './review-workflow/review-workflow.interface.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
-import { workspaceIdForBranch } from '../workspace/workspace.service.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { FileLockService } from './file-lock.service.js';
 import { PendingCommitsService } from './pending-commits.service.js';
 import type { WorkflowEventBus } from './event-bus.js';
-import type { FileChangeNotifier } from './file-change-notifier.js';
+import type { FileChangeNotifier } from '../kb-fs/file-change-notifier.js';
 import { WorkflowHooks } from './workflow-hooks.js';
-import { WorkspaceMutex } from './git/mutex.js';
+import { WorkspaceMutex } from '../kb-fs/mutex.js';
 import { hashEmail } from '../../shared/hash-email.js';
 import {
   ChangeRequestConflictsError,
@@ -66,9 +66,9 @@ import {
   PushNeedsAgentResolutionError,
   WorkflowDomainError,
   WorkflowValidationError,
-} from './workflow.errors.js';
+} from '../../shared/domain-errors.js';
 import { RECOVERY_BOT_EMAIL, RECOVERY_BOT_NAME } from './recovery-bot.js';
-import { AccessDeniedError } from '../access/access-errors.js';
+import { AccessDeniedError } from '../access-model/access-errors.js';
 
 const execFileAsync = promisify(execFile);
 

package/src/modules/workspace/__tests__/workspace.routes.create-grant.test.ts

@@ -4,7 +4,7 @@ import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import type { IWorkflowService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
-import type { ICreatorAccess } from '../../access/creator-access.js';
+import type { ICreatorAccess } from '../../access-model/creator.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';

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

@@ -11,7 +11,7 @@ import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
 import { createWorkspaceRoutes } from '../workspace.routes.js';
-import type { ICreatorAccess } from '../../access/creator-access.js';
+import type { ICreatorAccess } from '../../access-model/creator.js';
 import type { WorkspaceService } from '../workspace.service.js';
 
 const stubCreatorAccess: ICreatorAccess = {

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

@@ -6,10 +6,10 @@ import type { IWorkflowService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
-import { AccessConfigError } from '../../access/access-errors.js';
+import { AccessConfigError } from '../../access-model/access-errors.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
 import { createWorkspaceRoutes } from '../workspace.routes.js';
-import type { ICreatorAccess } from '../../access/creator-access.js';
+import type { ICreatorAccess } from '../../access-model/creator.js';
 import { FolderTooLargeError, type WorkspaceService } from '../workspace.service.js';
 
 const stubCreatorAccess: ICreatorAccess = {

package/src/modules/workspace/__tests__/workspace.routes.read-gate.test.ts

@@ -4,7 +4,7 @@ import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import type { IWorkflowService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
-import type { ICreatorAccess } from '../../access/creator-access.js';
+import type { ICreatorAccess } from '../../access-model/creator.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';

package/src/modules/workspace/__tests__/workspace.service.read-filter.test.ts

@@ -2,11 +2,8 @@ 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 {
-  WorkspaceService,
-  workspaceIdForBranch,
-  type ReadTreeFilter,
-} from '../workspace.service.js';
+import { WorkspaceService, type ReadTreeFilter } from '../workspace.service.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 
 const KB = 'knowledge-base';
 

package/src/modules/workspace/__tests__/workspace.service.test.ts

@@ -4,7 +4,8 @@ import { promisify } from 'node:util';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import { WorkspaceService, workspaceIdForBranch } from '../workspace.service.js';
+import { WorkspaceService } from '../workspace.service.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -62,6 +63,17 @@ describe('WorkspaceService — branch-keyed identity', () => {
     expect(workspaceIdForBranch('alice/feature')).toBe('alice%2Ffeature');
   });
 
+  it('a malformed workspace id (bad percent-escape) rejects as a 400 BranchNameError, not a 500', async () => {
+    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base');
+    // `%zz` fails decodeURIComponent, falls back to itself, and `%` never
+    // passes the branch-name rules — the cold-path bootstrap must surface
+    // that as the status-carrying domain error, not a wrapped plain Error.
+    await expect(svc.readFile('%zz', 'roles.yaml')).rejects.toMatchObject({
+      name: 'BranchNameError',
+      status: 400,
+    });
+  });
+
   it('returns workspace info derived from the branch — no .workspace.json on disk', async () => {
     const { workspaceId, workspaceDir } = await seedBranchWorkspace(root, 'target-company-state');
     const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base');

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

@@ -16,7 +16,7 @@ import { RoutineWritePolicyService } from '../routine-write-policy.js';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { SpillStore } from '../spill-store.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
-import { assertValidBranchName } from '../../workflow/git/branch-name.js';
+import { assertValidBranchName } from '../../kb-fs/branch-name.js';
 
 const KB_DIR = 'knowledge-base';
 

package/src/modules/workspace/startup/kb-startup-runner.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { isBranchModelConfigured } from '@bevel-software/platform-shared';
-import { workspaceIdForBranch } from '../workspace.service.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import type { KbBranch, OnServerStart, ServerStartContext } from './on-server-start.js';
 import { git, lsRemoteHeads, redactSecret, stampIdentity, withTempDir } from './kb-git.js';
 

package/src/modules/workspace/startup/steps/__tests__/steps.test.ts

@@ -8,7 +8,7 @@ import { KbStartupRunner } from '../../kb-startup-runner.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../../on-server-start.js';
 import { GroupsToPluginsStep } from '../groups-to-plugins.step.js';
 import { RolesYamlStep } from '../roles-yaml.step.js';
-import { renderRolesYaml } from '../../../../access/render-roles-yaml.js';
+import { renderRolesYaml } from '../../../../access-model/render-roles-yaml.js';
 import { TemplateFilesStep } from '../template-files.step.js';
 import { buildSeedTree } from '../seed-tree.js';
 import { defaultKbTemplateDir } from '../../../../../assets.js';

package/src/modules/workspace/startup/steps/groups-to-plugins.step.ts

@@ -13,7 +13,7 @@ import {
 } from '@bevel-software/platform-shared';
 import type { ToolManualDescriptor } from '../../../tool-manuals/tool-manuals.contract.js';
 import { normalizeToolManual } from '../../../tool-manuals/tool-manuals.service.js';
-import { parseOwnAccessEntries } from '../../../access/access-control.service.js';
+import { parseOwnAccessEntries } from '../../../access-model/access-grammar.js';
 import { containsVariableReference } from '../../../../shared/variable-refs.js';
 import { IGNORE_FILENAME } from '../../bevel-ignore.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';

package/src/modules/workspace/startup/steps/roles-yaml.step.ts

@@ -1,12 +1,12 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { renderRolesYaml } from '../../../access/render-roles-yaml.js';
+import { renderRolesYaml } from '../../../access-model/render-roles-yaml.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
 /**
  * Write `roles.yaml` on any protected branch missing it, generated from the
  * configured seed admins (`ADMIN_EMAIL`) via the shared validated renderer
- * (../../../access/render-roles-yaml.ts — a malformed email stops the boot
+ * (../../../access-model/render-roles-yaml.ts — a malformed email stops the boot
  * with a message naming the fix). Never part of the template: a template copy
  * would seed repos with a stale hard-coded Admin list.
  *

package/src/modules/workspace/startup/steps/seed-tree.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { renderRolesYaml } from '../../../access/render-roles-yaml.js';
+import { renderRolesYaml } from '../../../access-model/render-roles-yaml.js';
 import { TEMPLATE_SOURCE_FALLBACKS, reservedRootDirs, templateSource } from './template-files.step.js';
 
 /**

package/src/modules/workspace/workspace.routes.ts

@@ -13,15 +13,16 @@ import {
   PIPELINES_DIR,
   PLUGINS_DIR,
 } from '@bevel-software/platform-shared';
-import { branchForWorkspaceId, FolderTooLargeError, type ReadTreeFilter } from './workspace.service.js';
+import { FolderTooLargeError, type ReadTreeFilter } from './workspace.service.js';
+import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { WorkspaceService } from './workspace.service.js';
 import type { AuthService } from '../auth/auth.service.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
-import { resolveReadableMap, toKbRelative } from '../access/kb-read-filter.js';
-import type { ICreatorAccess } from '../access/creator-access.js';
-import { isRolesYamlPath, assertRolesYamlParsable } from '../access/roles-yaml-guard.js';
+import { resolveReadableMap, toKbRelative } from '../access-model/kb-read-filter.js';
+import type { ICreatorAccess } from '../access-model/creator.js';
+import { isRolesYamlPath, assertRolesYamlParsable } from '../access-model/roles-yaml-guard.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
-import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import '../auth/auth.middleware.js'; // Express Request augmentation
 
 const MAX_UPLOAD_BYTES = 50 * 1024 * 1024; // 50 MB

package/src/modules/workspace/workspace.service.ts

@@ -6,8 +6,10 @@ import AdmZip from 'adm-zip';
 import type { AuthUser, IWorkspaceService, WorkspaceInfo, FileTreeEntry } from '@bevel-software/platform-shared';
 import { assertValidRelativePath, validateFilename, DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { BevelIgnoreStack } from './bevel-ignore.js';
-import { assertValidBranchName } from '../workflow/git/branch-name.js';
-import { cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS } from '../workflow/git/clone-config.js';
+import { workspaceIdForBranch, branchForWorkspaceId } from '../../shared/workspace-id.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { assertValidBranchName } from '../kb-fs/branch-name.js';
+import { cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS } from '../kb-fs/clone-config.js';
 import type { IDiffService } from '../diff/diff.interface.js';
 
 /**
@@ -85,25 +87,12 @@ function redactError(err: unknown): string {
 
 const FETCH_CACHE_TTL_MS = 30_000;
 
-/**
- * Map a branch name to the directory that contains its workspace clone.
- * `encodeURIComponent` handles `/` in branch names (e.g. `alice/foo`) by
- * encoding it to `%2F` — single-segment-safe on every supported filesystem.
- */
-export function workspaceIdForBranch(branch: string): string {
-  return encodeURIComponent(branch);
-}
-
-export function branchForWorkspaceId(workspaceId: string): string {
-  return decodeURIComponent(workspaceId);
-}
-
 /**
  * Per-directory read filter for the file tree. Given a batch of
  * workspace-relative entry paths (e.g. `staging-repo/Product/Knowledge/x.md`),
  * returns a verdict map keyed by those paths (`path → readable`). Injected by
  * the route from the access service so `WorkspaceService` stays access-agnostic
- * (it gets a function, not the access module). See `modules/access/kb-read-filter.ts`.
+ * (it gets a function, not the access module). See `modules/access-model/kb-read-filter.ts`.
  */
 export type ReadTreeFilter = (wsRelPaths: string[]) => Promise<Map<string, boolean>>;
 
@@ -408,7 +397,7 @@ export class WorkspaceService implements IWorkspaceService {
 
   /**
    * Collapse the clone's tracking config to a single fetch refspec and a single
-   * upstream ref for `branch` (see `workflow/git/clone-config.ts`). A clone that
+   * upstream ref for `branch` (see `kb-fs/clone-config.ts`). A clone that
    * accumulated a second `remote.origin.fetch` refspec or `branch.<b>.merge`
    * value makes git refuse to refresh it — "Cannot rebase onto multiple
    * branches" — which is how a post-merge pull of the target branch fails.
@@ -724,7 +713,7 @@ export class WorkspaceService implements IWorkspaceService {
 
     // This driver runs outside the git layer's per-workspace mutex, so it may
     // only run the safe implicit-fetch shape — see `SAFE_IMPLICIT_FETCH_ARGS`
-    // in `workflow/git/clone-config.ts` for the full rationale.
+    // in `kb-fs/clone-config.ts` for the full rationale.
     const promise = execFileAsync(
       'git',
       ['-C', repoDir, ...SAFE_IMPLICIT_FETCH_ARGS],
@@ -1268,6 +1257,13 @@ export class WorkspaceService implements IWorkspaceService {
       // Bootstrap reported success but didn't register — defensive fallback.
       return workspaceDir;
     } catch (err) {
+      // Domain errors pass through intact: they carry the status the routes
+      // map (BranchNameError → 400), which is how a malformed or bogus
+      // workspace id stays a client error instead of the wrap below erasing
+      // the type and surfacing as a 500. A malformed id (bad percent-escape)
+      // decodes to itself, and `%` never passes the branch-name rules, so it
+      // lands here as a BranchNameError like any other invalid name.
+      if (err instanceof WorkflowDomainError) throw err;
       const reason = err instanceof Error ? err.message : String(err);
       throw new Error(`Invalid workspace ID "${workspaceId}": ${reason}`);
     }

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

@@ -16,13 +16,13 @@ import {
 import type { IRoutineWritePolicy } from './routine-write-policy.js';
 import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
 import { requireInternalSource, requireExternalSource } from '../tool-auth/tool-auth.middleware.js';
-import { workspaceIdForBranch } from './workspace.service.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 // Leaf-level shared primitive (same exception `workspace.service.ts` already
 // relies on) — not a workflow service, so this stays inside the module boundary.
-import { assertValidBranchName } from '../workflow/git/branch-name.js';
+import { assertValidBranchName } from '../kb-fs/branch-name.js';
 import type { ISessionSink } from './session-sink.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
-import { toKbRelative, resolveReadableMap } from '../access/kb-read-filter.js';
+import { toKbRelative, resolveReadableMap } from '../access-model/kb-read-filter.js';
 import type { SpillStore } from './spill-store.js';
 
 /** A directory entry as returned by `LocalFilesystem.readdir`. */

package/src/shared/__tests__/join-request.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { isJoinBranchFor, joinBranchFor, kebabPluginName } from '@bevel-software/platform-shared';
-import { assertValidBranchName } from '../../modules/workflow/git/branch-name.js';
+import { assertValidBranchName } from '../../modules/kb-fs/branch-name.js';
 
 /**
  * The join-branch convention. Two properties matter, and they pull in

package/src/shared/__tests__/workspace-id.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from 'vitest';
+import { branchForWorkspaceId, workspaceIdForBranch } from '../workspace-id.js';
+
+describe('workspace-id mapping', () => {
+  it('round-trips branch names, slashes included', () => {
+    for (const branch of ['current-company-state', 'alice/draft', 'a b', '100%']) {
+      expect(branchForWorkspaceId(workspaceIdForBranch(branch))).toBe(branch);
+    }
+  });
+
+  it('never throws on a malformed id — it names a branch that does not exist', () => {
+    for (const malformed of ['%', '100%', '%2', '%zz', 'a%2Gb']) {
+      expect(() => branchForWorkspaceId(malformed)).not.toThrow();
+      expect(branchForWorkspaceId(malformed)).toBe(malformed);
+    }
+  });
+});

package/src/{modules/workflow/workflow.errors.ts → shared/domain-errors.ts}

@@ -1,9 +1,14 @@
 /**
  * Workflow domain errors. This is the single source of truth — every error
- * raised by the workflow module (branches, changes, change requests, access
+ * raised by the workflow domain (branches, changes, change requests, access
  * control, locks) lives here. Route handlers shape responses via the
  * `.status` + `.payload` contract on the base class.
  *
+ * Lives in `src/shared` (not `modules/workflow`) because the classes are
+ * consumed across module boundaries — access, diff, plugins and workspace all
+ * catch or raise them — and `src/shared` is the layer with no module imports.
+ * Only a type from `@bevel-software/platform-shared` comes in; nothing else.
+ *
  * Naming: classes use workflow vocabulary. `WorkflowDomainError` is the
  * abstract base; specific subclasses describe the workflow concept that
  * went wrong (`BranchNameError`, `ProtectedBranchError`, etc.). Where a

package/src/shared/workspace-id.ts

@@ -0,0 +1,36 @@
+/**
+ * The branch ↔ workspace-directory naming convention. Workspaces are
+ * per-branch (one on-disk clone per branch name), and the workspace id IS the
+ * URL-encoded branch name — deterministic both ways, so every caller
+ * (backend, frontend, agent) can compute one from the other without a DB
+ * round-trip. Consumed by nearly every module that touches a workspace, so it
+ * lives in `backend/src/shared` rather than inside the workspace module.
+ *
+ * Pure string handling — no IO, no DB.
+ */
+
+/**
+ * Map a branch name to the directory that contains its workspace clone.
+ * `encodeURIComponent` handles `/` in branch names (e.g. `alice/foo`) by
+ * encoding it to `%2F` — single-segment-safe on every supported filesystem.
+ */
+export function workspaceIdForBranch(branch: string): string {
+  return encodeURIComponent(branch);
+}
+
+/**
+ * Map a workspace id back to its branch name. Workspace ids come in from
+ * request paths and from directory names on disk, so malformed input (a lone
+ * `%`, `%` without two hex digits) must not throw — `decodeURIComponent`
+ * would raise a `URIError` that surfaces as an unhandled 500 in every route
+ * that resolves an id. A malformed id can never equal a valid encoding, so
+ * returning it unchanged is safe: it simply names a branch that does not
+ * exist, and the caller's own lookup fails with its normal not-found path.
+ */
+export function branchForWorkspaceId(workspaceId: string): string {
+  try {
+    return decodeURIComponent(workspaceId);
+  } catch {
+    return workspaceId;
+  }
+}