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

package/dist/shared/domain-errors.js

@@ -0,0 +1,303 @@
+/**
+ * Workflow domain errors. This is the single source of truth — every error
+ * 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
+ * concept is purely git mechanics with no workflow analogue
+ * (`NoSharedHistoryError`), the name keeps its git flavour because
+ * consumers actually need to discriminate on it.
+ */
+export class WorkflowDomainError extends Error {
+    status;
+    payload;
+    constructor(message, status, payload) {
+        super(message);
+        this.name = 'WorkflowDomainError';
+        this.status = status;
+        this.payload = payload;
+    }
+}
+export class BranchNameError extends WorkflowDomainError {
+    branchName;
+    constructor(reason, branchName) {
+        super(`Invalid branch name "${branchName}": ${reason}`, 400);
+        this.branchName = branchName;
+        this.name = 'BranchNameError';
+    }
+}
+export class ProtectedBranchError extends WorkflowDomainError {
+    branchName;
+    action;
+    constructor(branchName, action) {
+        super(`Branch "${branchName}" is protected — ${action} is not allowed.`, 403);
+        this.branchName = branchName;
+        this.action = action;
+        this.name = 'ProtectedBranchError';
+    }
+}
+/**
+ * The caller tried to delete a branch they don't own. Authorship is inferred
+ * from the `<email-localpart>/<slug>` naming convention used by
+ * `slugifyDraftName` — see `isBranchAuthoredBy` in `@bevel-software/platform-shared`.
+ *
+ * Distinct from `AccessDeniedError` because that error is path-based
+ * (file-level write permission via `roles.yaml`/`access.md`). Branch
+ * authorship is identity-based and has no eligible-roles list to surface —
+ * the only way for someone else to delete a non-author's branch is to push
+ * the delete via git CLI directly.
+ */
+export class BranchAuthorshipError extends WorkflowDomainError {
+    branchName;
+    kind = 'branch-authorship';
+    constructor(branchName) {
+        super(`Only the author of "${branchName}" can delete it.`, 403, { kind: 'branch-authorship', branchName });
+        this.branchName = branchName;
+        this.name = 'BranchAuthorshipError';
+    }
+}
+// `DirtyWorkingTreeError` removed: under save=share + per-branch workspaces
+// no operation in the workflow can legitimately encounter a dirty working
+// tree. The two former callers (`switchBranch` and `mergeFromOrigin`'s
+// pre-flight) are gone / relaxed; if a dirty tree ever shows up it's an
+// internal bug that gets server-side-logged in `statusInternal`, never
+// surfaced as a user-facing 409.
+/**
+ * The local commit landed but pushing it to origin failed because the
+ * remote diverged (a teammate or the agent landed competing commits while
+ * the lock was held). The cooperative recovery — `pull --rebase` + retry
+ * push — also failed, because the divergence touches the same file and the
+ * rebase conflicts.
+ *
+ * Per the "disk is the source of truth" rule we do NOT auto-force-push
+ * from the workflow layer (that's a destructive history rewrite that can
+ * lose teammate work irrecoverably). Instead we surface this structured
+ * error so the frontend can seed an agent prompt — the agent has git + gh
+ * CLI access plus the lock-aware write tool, so it can read both sides,
+ * semantically merge, and save the resolved file through the normal
+ * save=share pipeline. The user sees only a loading indicator; the agent
+ * does the reconciliation.
+ *
+ * State at the moment this fires:
+ *   - The local branch has the user's just-committed change as its HEAD.
+ *   - The lock has already been released (lock release runs BEFORE the
+ *     push attempt). The agent can acquire its own lock.
+ *   - `origin/<branch>` has commits the local clone doesn't reach.
+ *   - The working tree is clean (the commit landed).
+ *
+ * The payload carries enough context that the prompt builder can phrase
+ * the resolution request to the agent without further server round-trips.
+ */
+export class PushNeedsAgentResolutionError extends WorkflowDomainError {
+    branch;
+    path;
+    originalDetail;
+    recoveryDetail;
+    kind = 'push-needs-resolution';
+    constructor(branch, path, originalDetail, recoveryDetail) {
+        super(`Saved locally on "${branch}" but couldn't share with the team automatically — ` +
+            `the remote diverged on "${path}" and the cooperative rebase couldn't reconcile. ` +
+            `The agent will resolve this.`, 409, {
+            kind: 'push-needs-resolution',
+            branch,
+            path,
+            originalDetail,
+            recoveryDetail,
+        });
+        this.branch = branch;
+        this.path = path;
+        this.originalDetail = originalDetail;
+        this.recoveryDetail = recoveryDetail;
+        this.name = 'PushNeedsAgentResolutionError';
+    }
+}
+/**
+ * Refreshing a workspace from origin (`GitService.pull`) hit a rebase
+ * conflict: the workspace carries local commits origin doesn't have, origin
+ * moved ahead with changes that touch the same files, and replaying the
+ * local commits conflicts. The rebase has already been aborted — the
+ * workspace is back in its pre-pull state (diverged, clean tree).
+ *
+ * This state does NOT resolve itself: every subsequent pull hits the same
+ * conflict, and the local commits (someone's saved content, under
+ * save=share) stay unshared until the divergence is reconciled. The service
+ * layer therefore reacts by queueing a background recovery run (see
+ * `WorkflowService.updateFromRemote`); this error tells the caller what
+ * happened and which paths are contested.
+ *
+ * 409 like the other conflict errors — the operation needs the divergence
+ * cleared before it can succeed. `detail` (the raw git failure, already
+ * credential-redacted by `GitService.git`) is kept OFF the payload; it's for
+ * server logs and the recovery pipeline, not the client.
+ */
+export class PullRebaseConflictError extends WorkflowDomainError {
+    branch;
+    conflictedPaths;
+    detail;
+    kind = 'pull-rebase-conflict';
+    constructor(branch, conflictedPaths, detail) {
+        const list = conflictedPaths.join(', ');
+        super(`Updating "${branch}" from origin hit conflicts in ${conflictedPaths.length} file(s): ${list}. ` +
+            `Automatic background recovery has been queued.`, 409, {
+            kind: 'pull-rebase-conflict',
+            branch,
+            conflictedPaths,
+        });
+        this.branch = branch;
+        this.conflictedPaths = conflictedPaths;
+        this.detail = detail;
+        this.name = 'PullRebaseConflictError';
+    }
+}
+/**
+ * Generic 400 for workflow-input validation (malformed branch names, missing
+ * fields, etc.). Carries an optional payload so callers can attach typed
+ * discriminators (`kind: '...'`) when the frontend needs to switch on the
+ * specific failure mode.
+ */
+export class WorkflowValidationError extends WorkflowDomainError {
+    constructor(message, payload) {
+        super(message, 400, payload);
+        this.name = 'WorkflowValidationError';
+    }
+}
+/**
+ * The draft branch doesn't share history with the target branch, so GitHub
+ * would reject the change request with `no history in common`. Surfaced as
+ * a structured payload so the frontend's typed-error parser can route into
+ * the agent recovery flow.
+ */
+export class NoSharedHistoryError extends WorkflowDomainError {
+    head;
+    base;
+    kind = 'no-shared-history';
+    constructor(head, base) {
+        super(`The draft "${head}" doesn't share history with "${base}". ` +
+            `It was likely started outside the app or from an unrelated point.`, 400, { kind: 'no-shared-history', head, base });
+        this.head = head;
+        this.base = base;
+        this.name = 'NoSharedHistoryError';
+    }
+}
+/**
+ * The KB validator reported `mustFix` issues (DANGLING LINK / ASYMMETRY /
+ * ERROR) — the change cannot land until they're resolved. The payload
+ * carries the structured report so the UI / agent can render the items
+ * the user must fix without re-running the validator.
+ */
+export class ValidationFailedError extends WorkflowDomainError {
+    validation;
+    constructor(report) {
+        super(`Cannot commit — knowledge graph has ${report.mustFix.length} unresolved issue(s).`, 422, {
+            validation: {
+                ok: report.ok,
+                mustFix: report.mustFix,
+                warnings: report.warnings,
+            },
+        });
+        this.name = 'ValidationFailedError';
+        this.validation = report;
+    }
+}
+/**
+ * Method exists on the workflow interface but has no backing implementation
+ * yet. 501 so the frontend can light up "coming soon" affordances without
+ * confusing them with 5xx infra failures. `feature` is the workflow method
+ * name; clients switch on it to render targeted copy.
+ */
+export class NotImplementedWorkflowError extends WorkflowDomainError {
+    feature;
+    kind = 'not-implemented';
+    constructor(feature) {
+        super(`Workflow feature "${feature}" is not yet implemented in this build.`, 501, { kind: 'not-implemented', feature });
+        this.feature = feature;
+        this.name = 'NotImplementedWorkflowError';
+    }
+}
+/**
+ * Attempting to reconcile two branches (opening a change request, refreshing
+ * one from target, or executing a merge) hit conflicts that the workflow
+ * cannot auto-resolve. The structured payload carries the list of
+ * conflicting paths so the frontend / agent can route into the resolution
+ * flow without a second round-trip.
+ *
+ * 409 because the conflict is a precondition the caller has to clear (by
+ * resolving + committing on the source branch) before the operation can
+ * succeed — same semantics git itself uses for merge conflicts.
+ */
+export class ChangeRequestConflictsError extends WorkflowDomainError {
+    sourceBranch;
+    targetBranch;
+    conflictedPaths;
+    kind = 'change-request-conflicts';
+    constructor(sourceBranch, targetBranch, conflictedPaths) {
+        const list = conflictedPaths.join(', ');
+        super(`Conflicts merging "${targetBranch}" into "${sourceBranch}". ` +
+            `${conflictedPaths.length} file(s): ${list}. Resolve on "${sourceBranch}" and try again.`, 409, {
+            kind: 'change-request-conflicts',
+            sourceBranch,
+            targetBranch,
+            conflictedPaths,
+        });
+        this.sourceBranch = sourceBranch;
+        this.targetBranch = targetBranch;
+        this.conflictedPaths = conflictedPaths;
+        this.name = 'ChangeRequestConflictsError';
+    }
+}
+/**
+ * Caller tried to open a change request for a `(source, target)` pair that
+ * already has one open. Spec rule: A→B blocks A→B (B→A is allowed). Carries
+ * the existing CR number so the UI / agent can deep-link to it instead of
+ * trying to recover.
+ */
+export class DuplicateChangeRequestError extends WorkflowDomainError {
+    sourceBranch;
+    targetBranch;
+    existingNumber;
+    kind = 'duplicate-change-request';
+    constructor(sourceBranch, targetBranch, existingNumber) {
+        super(`An open change request already exists from "${sourceBranch}" to "${targetBranch}" (#${existingNumber}).`, 409, {
+            kind: 'duplicate-change-request',
+            sourceBranch,
+            targetBranch,
+            existingNumber,
+        });
+        this.sourceBranch = sourceBranch;
+        this.targetBranch = targetBranch;
+        this.existingNumber = existingNumber;
+        this.name = 'DuplicateChangeRequestError';
+    }
+}
+/**
+ * Raised when a merge must neutralise a CR's `roles.yaml` change (restore the
+ * base branch's version on the source branch) but that preservation write fails.
+ * `roles.yaml` decides admin membership and is mutable ONLY via the admin Roles
+ * & Members surface — a CR must never carry a roles.yaml change across a merge,
+ * so if we cannot guarantee the base version is preserved we abort the merge
+ * rather than risk landing the CR's version on a protected branch. 502: the
+ * failure is an internal git/push hiccup, not the caller's fault.
+ */
+export class RolesYamlPreservationError extends WorkflowDomainError {
+    kind = 'roles-yaml-preservation-failed';
+    /**
+     * The underlying git/push failure. Kept OFF the client-facing message (which
+     * stays generic for the 502) so raw git internals / paths don't leak to the
+     * caller — log this server-side for diagnostics instead.
+     */
+    detail;
+    constructor(reason) {
+        super('Could not preserve the official roles.yaml while merging — merge aborted so no roles.yaml change can ride in.', 502, { kind: 'roles-yaml-preservation-failed' });
+        this.name = 'RolesYamlPreservationError';
+        this.detail = reason;
+    }
+}
+//# sourceMappingURL=domain-errors.js.map

package/dist/shared/domain-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-errors.js","sourceRoot":"","sources":["../../src/shared/domain-errors.ts"],"names":[],"mappings":"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"}

package/dist/shared/workspace-id.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 declare function workspaceIdForBranch(branch: string): string;
+/**
+ * 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 declare function branchForWorkspaceId(workspaceId: string): string;
+//# sourceMappingURL=workspace-id.d.ts.map

package/dist/shared/workspace-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-id.d.ts","sourceRoot":"","sources":["../../src/shared/workspace-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAMhE"}

package/dist/shared/workspace-id.js

@@ -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) {
+    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) {
+    try {
+        return decodeURIComponent(workspaceId);
+    }
+    catch {
+        return workspaceId;
+    }
+}
+//# sourceMappingURL=workspace-id.js.map

package/dist/shared/workspace-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-id.js","sourceRoot":"","sources":["../../src/shared/workspace-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,IAAI,CAAC;QACH,OAAO,kBAAkB,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,8 +46,8 @@
     "pg": "^8.20.0",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.11.1",
-    "@bevel-software/platform-shared": "0.11.1"
+    "@bevel-software/platform-mcp-core": "0.11.2",
+    "@bevel-software/platform-shared": "0.11.2"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/core/create-core-services.ts

@@ -47,13 +47,13 @@ import {
 } from '../modules/secrets-vault/index.js';
 import { GitService } from '../modules/workflow/git/git.service.js';
 import { PullRequestService } from '../modules/workflow/git/pull-request.service.js';
-import { WorkspaceMutex } from '../modules/workflow/git/mutex.js';
+import { WorkspaceMutex } from '../modules/kb-fs/mutex.js';
 import { assertGitVersion } from '../modules/workflow/git/git-version.js';
 import { DiffService } from '../modules/diff/diff.service.js';
 import { ReviewWorkflowService } from '../modules/workflow/review-workflow/review-workflow.service.js';
 import { FileLockService } from '../modules/workflow/file-lock.service.js';
 import { WorkflowEventBus } from '../modules/workflow/event-bus.js';
-import { FileChangeNotifier } from '../modules/workflow/file-change-notifier.js';
+import { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
 import { WorkflowService } from '../modules/workflow/workflow.service.js';
 import { WorkflowHooks } from '../modules/workflow/workflow-hooks.js';
 import { SessionOntologyService } from '../modules/workflow/session-ontology.service.js';

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

@@ -5,7 +5,7 @@ import os from 'node:os';
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../access-control.service.js';
-import { AccessConfigError } from '../access-errors.js';
+import { AccessConfigError } from '../../access-model/access-errors.js';
 
 const PROCESS_MAP_DIR = 'knowledge-base';
 

package/src/modules/access/__tests__/access-groups.test.ts

@@ -6,8 +6,9 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import { AccessControlService, parseRolesYaml } from '../access-control.service.js';
-import { AccessConfigError } from '../access-errors.js';
+import { AccessControlService } from '../access-control.service.js';
+import { parseRolesYaml } from '../../access-model/access-grammar.js';
+import { AccessConfigError } from '../../access-model/access-errors.js';
 import { addMember, parseRolesModel, emitRolesModel } from '../roles-edit.js';
 
 const execFileAsync = promisify(execFile);
@@ -102,7 +103,7 @@ describe('group files as access principals', () => {
   });
 
   it('validateGroupsFile (the WRITE gate) still refuses blank keys the reader forgives', async () => {
-    const { validateGroupsFile } = await import('../group-files.js');
+    const { validateGroupsFile } = await import('../../access-model/group-files.js');
     // Inside `groups:` — refused via the entry warning (strict gate).
     expect(validateGroupsFile('groups:\n  :\n    - a@x.io\n', 'groups.yaml').ok).toBe(false);
     // At the ROOT — the tolerant reader silently drops this without any
@@ -114,7 +115,7 @@ describe('group files as access principals', () => {
   });
 
   it('parseGroupsFile applies the shared name-safety predicate (warn-and-skip), and the write gate refuses', async () => {
-    const { parseGroupsFile, validateGroupsFile } = await import('../group-files.js');
+    const { parseGroupsFile, validateGroupsFile } = await import('../../access-model/group-files.js');
     // `<`/`>` and control characters pass the YAML subset as plain keys but
     // fail unsafeNameReason — the parser must skip them (other groups keep
     // resolving) and the strict write gate must refuse the whole candidate.
@@ -133,7 +134,7 @@ describe('group files as access principals', () => {
   });
 
   it("parseGroupsFile skips a 'group:'-prefixed member (shapes like an email, but is the ref token)", async () => {
-    const { parseGroupsFile, validateGroupsFile } = await import('../group-files.js');
+    const { parseGroupsFile, validateGroupsFile } = await import('../../access-model/group-files.js');
     // `group:lee@x.io` PASSES the email regex — without the explicit skip it
     // would land as a member "email" nothing can ever log in as.
     const text = 'groups:\n  Team:\n    - group:lee@x.io\n    - real@x.io\n';

package/src/modules/access/__tests__/access-md-format.test.ts

@@ -4,13 +4,13 @@ import path from 'node:path';
 import os from 'node:os';
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { AccessControlService } from '../access-control.service.js';
 import {
-  AccessControlService,
   accessMdDeclaresBodyRules,
   accessMdSelfEntries,
   parseAccessFile,
-} from '../access-control.service.js';
-import { spliceGrant, spliceRevoke } from '../access-splice.js';
+} from '../../access-model/access-grammar.js';
+import { spliceGrant, spliceRevoke } from '../../access-model/access-splice.js';
 
 /**
  * The two-format `access.md` story:

package/src/modules/access/__tests__/access-mutation.service.test.ts

@@ -6,7 +6,7 @@ import os from 'node:os';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../access-control.service.js';
 import { AccessMutationService, AccessMutationError } from '../access-mutation.service.js';
-import type { Principal } from '../access-splice.js';
+import type { Principal } from '../../access-model/access-splice.js';
 
 const KB = 'knowledge-base';
 const WS = 'ws-mut-1';

package/src/modules/access/__tests__/admin-locked-commit.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 
 import { AdminLockedCommits } from '../admin-locked-commit.js';
-import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../workflow/workflow.errors.js';
+import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../../shared/domain-errors.js';
 import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
 
 const KB = 'knowledge-base';

package/src/modules/access/__tests__/admin-route-helpers.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
 
 import { toHttpError, requireNonEmptyString } from '../admin-route-helpers.js';
-import { WorkflowDomainError } from '../../workflow/workflow.errors.js';
+import { WorkflowDomainError } from '../../../shared/domain-errors.js';
 import { AccessMutationError } from '../access-mutation.service.js';
 
 describe('toHttpError — the shared access-family error shape', () => {

package/src/modules/access/__tests__/roles-admin.service.test.ts

@@ -7,11 +7,11 @@ import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { WorkflowService } from '../../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { FileTreeEntry, WorkflowEventPayload } from '@bevel-software/platform-shared';
-import { workspaceIdForBranch } from '../../workspace/workspace.service.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { AccessControlService } from '../access-control.service.js';
 import { RolesAdminService } from '../roles-admin.service.js';
 import { rewriteRoleTokensInText, findRoleRefsInText } from '../reference-scan.js';
-import { PushNeedsAgentResolutionError } from '../../workflow/workflow.errors.js';
+import { PushNeedsAgentResolutionError } from '../../../shared/domain-errors.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 

package/src/modules/access/__tests__/roles-edit.test.ts

@@ -11,7 +11,7 @@ import {
   renameGroupRefs,
   RolesEditError,
 } from '../roles-edit.js';
-import { parseYamlSubset } from '../access-control.service.js';
+import { parseYamlSubset } from '../../access-model/access-grammar.js';
 
 const BASE = `roles:
   Admin:

package/src/modules/access/__tests__/synced-groups-committer.test.ts

@@ -8,7 +8,7 @@ import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { AccessControlService } from '../access-control.service.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import { createSyncedGroupsCommitter } from '../synced-groups-committer.js';
-import { PushNeedsAgentResolutionError, WorkflowValidationError } from '../../workflow/workflow.errors.js';
+import { PushNeedsAgentResolutionError, WorkflowValidationError } from '../../../shared/domain-errors.js';
 
 const KB = 'knowledge-base';
 const BOT: AuthUser = { id: 'bot-1', email: 'directory-sync@bevel.local', name: 'Directory Sync Bot' };

package/src/modules/access/__tests__/synced-groups-writer.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { parseGroupsFile } from '../group-files.js';
+import { parseGroupsFile } from '../../access-model/group-files.js';
 import {
   SyncedGroupsWriter,
   renderSyncedGroupsYaml,