@bevel-software/platform-core-backend 0.32.0 → 0.33.0

package/src/core/public-config.ts

@@ -85,5 +85,15 @@ export function publicConfig(kb: KbContext, { marketplaceGitUrl, mcpUrl }: Publi
      * there.
      */
     catalogRevision: true as const,
+    /**
+     * This deployment serves `GET /api/agent/tool-hints`, the read-only hint
+     * of every platform tool and code-mode meta-tool (see
+     * modules/tool-registry/read-only-hints.ts). The local `hexis-mcp` bridge
+     * reads it on every `tools/list` only when this is advertised — on the
+     * same terms as the two flags above: an older deployment answers the
+     * unknown route with 401, and an OAuth bridge reads a 401 as an expired
+     * token and refreshes its sign-in on every listing.
+     */
+    toolHints: true as const,
   };
 }

package/src/modules/access/__tests__/access-requests.routes.test.ts

@@ -49,7 +49,8 @@ interface HarnessOpts {
   lastClosed?: { number: number; state: 'closed' | 'merged' } | null;
   liveRules?: string | null;
   branchRules?: string | null;
-  detailBody?: string;
+  /** What `getChangeRequestDetail` answers for every request: the body, and the access request's own facts. */
+  detail?: { body?: string; accessRequest?: { level: 'write' | 'owner'; note?: string } };
 }
 
 async function makeHarness(opts: HarnessOpts = {}) {
@@ -62,7 +63,7 @@ async function makeHarness(opts: HarnessOpts = {}) {
     lastClosed = null,
     liveRules = '---\n---\nwrite:\n  - Ed <ed@x.io>\n',
     branchRules = null,
-    detailBody = '',
+    detail = {},
   } = opts;
 
   const absent = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
@@ -92,7 +93,7 @@ async function makeHarness(opts: HarnessOpts = {}) {
     }),
     latestClosedChangeRequest: vi.fn(async () => lastClosed),
     getChangeRequest: vi.fn(async (n: number) => ({ number: n, state: 'open' })),
-    getChangeRequestDetail: vi.fn(async () => ({ body: detailBody })),
+    getChangeRequestDetail: vi.fn(async () => ({ body: '', ...detail })),
   } as unknown as IWorkflowService;
 
   const workspaceService = {
@@ -345,13 +346,14 @@ describe('GET /workspace/:id/access/request — what the requester is told', ()
   it('reports the open request, taking the level off the REQUEST rather than the branch', async () => {
     // The branch is where the proposal lives, but a clone whose refs are
     // seconds stale cannot read a branch cut moments ago. "Requested: Owner"
-    // is a promise about a request, so it is answered from the request — here
-    // the branch is deliberately unreadable and the line is still right.
+    // is a promise about a request, so it is answered from the request's own
+    // row — here the branch is deliberately unreadable and the line is still
+    // right.
     const branch = joinBranchFor(RITA.email, FOLDER);
     const h = await makeHarness({
       openCrs: [{ number: 31, branch, state: 'open' }],
       proposals: null,
-      detailBody: '<!--hexis:access-request-level:owner-->\nRita asked for Owner.',
+      detail: { body: 'Rita asked for Owner.', accessRequest: { level: 'owner' } },
     });
     server = h.server;
     expect(await (await status(h)).json()).toEqual({ state: 'pending', level: 'owner', number: 31 });
@@ -361,7 +363,7 @@ describe('GET /workspace/:id/access/request — what the requester is told', ()
     const branch = joinBranchFor(RITA.email, FOLDER);
     const h = await makeHarness({
       openCrs: [{ number: 31, branch, state: 'open' }],
-      detailBody: 'Opened before the level was recorded.',
+      detail: { body: 'Opened before the level was recorded.' },
     });
     server = h.server;
     expect(await (await status(h)).json()).toMatchObject({ state: 'pending', level: 'write' });
@@ -410,12 +412,14 @@ describe('the editors\' side', () => {
   const listUrl = (base: string) =>
     `${base}/${LIVE_WS}/access/requests?path=${encodeURIComponent(`${KB}/${FOLDER}`)}&kind=folder`;
 
-  it('lists the item\'s open requests for an editor, with the note read back as plain text', async () => {
+  it("lists the item's open requests for an editor, with the note off the request's own row", async () => {
     const h = await makeHarness({
       writable: [`${FOLDER}/access.md`],
       proposals: [proposalFor('owner')],
-      detailBody:
-        'x\n\n<!--hexis:access-request-note-->\n> I maintain these pages now\n<!--/hexis:access-request-note-->\n',
+      detail: {
+        body: 'x\n\nNote from Rita:\n\n> I maintain these pages now',
+        accessRequest: { level: 'owner', note: 'I maintain these pages now' },
+      },
     });
     server = h.server;
     const body = await (await fetch(listUrl(h.base))).json();
@@ -565,19 +569,29 @@ describe('a branch left over from an answered request', () => {
     // request asking for Owner.
     const h = await makeHarness({
       openCrs: [{ number: 31, branch: stale, state: 'open' }],
-      detailBody: '<!--hexis:access-request-level:owner-->',
+      detail: { accessRequest: { level: 'owner' } },
     });
     server = h.server;
     const res = await post(`${h.base}/${LIVE_WS}/access/request`, { ...folderBody, level: 'write' });
     expect(await res.json()).toEqual({ ok: true, state: 'pending', number: 31, level: 'owner' });
   });
 
-  it('records the level on the request itself, so it can be read back', async () => {
+  it('records the level and the note on the request itself, never hidden in its description', async () => {
     const h = await makeHarness();
     server = h.server;
-    await post(`${h.base}/${LIVE_WS}/access/request`, { ...folderBody, level: 'owner' });
-    const { description } = h.opened[0] as { description: string };
-    expect(description).toContain('<!--hexis:access-request-level:owner-->');
+    await post(`${h.base}/${LIVE_WS}/access/request`, { ...folderBody, level: 'owner', note: 'For the Q3 review' });
+    const { description, accessRequest } = h.opened[0] as { description: string; accessRequest: unknown };
+    expect(accessRequest).toEqual({ level: 'owner', note: 'For the Q3 review' });
+    // The description is prose for the people who read it: no marker, no fence.
+    expect(description).not.toMatch(/<!--/);
+    expect(description).toContain('For the Q3 review');
+  });
+
+  it('records no note when none was written', async () => {
+    const h = await makeHarness();
+    server = h.server;
+    await post(`${h.base}/${LIVE_WS}/access/request`, { ...folderBody, level: 'write' });
+    expect((h.opened[0] as { accessRequest: unknown }).accessRequest).toEqual({ level: 'write' });
   });
 });
 

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

@@ -7,9 +7,9 @@ const log = logger('access');
 import { isAbsence, type ITreeWalker, type WalkListener } from '../../shared/fs.contract.js';
 import { assertOneSpecPerLine, isCommitSha, isGitTimeout, type IGitRunner } from '../../shared/git.contract.js';
 import { hashEmail } from '../../shared/email-identity.js';
-import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../workflow/index.js';
 import { readRevSha } from '../kb-fs/index.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type {
   IAccessControl,
   AccessDecision,
@@ -32,14 +32,13 @@ import {
   platformRestoreDestination,
 } from '@bevel-software/platform-shared';
 import type { KbContext } from '../../shared/kb-context.js';
-import { AccessConfigError, AccessUnreadableError } from '../access-model/access-errors.js';
-import { synthesizePluginPrincipals } from '../access-model/plugin-principals.js';
+import { AccessConfigError, AccessUnreadableError, synthesizePluginPrincipals } from '../access-model/index.js';
 import {
   GROUPS_YAML,
   SYNCED_GROUPS_YAML,
   parseGroupsFile,
   type GroupsIndex,
-} from '../access-model/group-files.js';
+} from '../access-model/index.js';
 import {
   ADMIN_CANONICAL,
   EVERYONE_CANONICAL,
@@ -61,7 +60,7 @@ import {
   type ParsedEntry,
   type RolesIndex,
   type Verb,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 import {
   DIRECTORY_SYNC_BOT_EMAIL,
   DIRECTORY_SYNC_BOT_NAME,

package/src/modules/access/access-declarations.ts

@@ -9,7 +9,7 @@ import {
   parseOwnAccessEntries,
   type ParsedEntry,
   type Verb,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 
 /**
  * WHERE access rules are DECLARED inside a folder — a read-only inventory, not

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

@@ -35,10 +35,10 @@
 
 import path from 'node:path';
 
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { IAccessControl } from './access-control.interface.js';
 import { isAbsence } from '../../shared/fs.contract.js';
-import { isTextBytes } from '../workspace/file-readers/text-reader.js';
+import { isTextBytes } from '../workspace/index.js';
 import {
   type Verb,
   ADMIN_CANONICAL,
@@ -46,7 +46,7 @@ import {
   ROLE_TOKEN_PREFIX,
   canonicalRoleName,
   accessFrontmatterExtensionList,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 import {
   spliceRevoke,
   spliceGrant,
@@ -54,7 +54,7 @@ import {
   AccessSpliceError,
   type Principal,
   type TokenMatch,
-} from '../access-model/access-splice.js';
+} from '../access-model/index.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import {
   canCarryFrontmatter,
@@ -610,3 +610,9 @@ export class AccessMutationService {
     return new AccessMutationError(err instanceof Error ? err.message : 'mutation failed', 500);
   }
 }
+
+/**
+ * What another module needs of the mutation service: to grant and to revoke.
+ * Injected by the composition root, which owns the implementation.
+ */
+export type IAccessMutation = Pick<AccessMutationService, 'grant' | 'revoke'>;

package/src/modules/access/access-requests.contract.ts

@@ -1,5 +1,5 @@
 import type { AuthUser, ChangeRequest } from '@bevel-software/platform-shared';
-import type { Verb } from '../access-model/access-grammar.js';
+import type { Verb } from '../access-model/index.js';
 import { accessMdPathForFolder, type TargetKind } from './access-mutation.service.js';
 
 /**

package/src/modules/access/access-requests.routes.ts

@@ -1,11 +1,10 @@
 import express from 'express';
-import type { AuthUser } from '@bevel-software/platform-shared';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
-import type { AuthService } from '../auth/auth.service.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { AuthService } from '../auth/index.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
   AccessMutationError,
@@ -22,12 +21,8 @@ import {
   type AccessRequestTarget,
   type IAccessRequestLifecycle,
 } from './access-requests.contract.js';
-import {
-  AccessRequestsService,
-  extractRequestNote,
-  itemNameOf,
-} from './access-requests.service.js';
-import '../auth/auth.middleware.js'; // Express Request.userId augmentation
+import { AccessRequestsService, itemNameOf } from './access-requests.service.js';
+import '../auth/index.js'; // Express Request.userId augmentation
 
 const log = logger('access.request');
 
@@ -235,16 +230,16 @@ export function createAccessRequestRoutes(deps: {
       }
       const crs = await workflow.listChangeRequests();
       const rows = await lifecycle.list(target.path, target, crs, user);
-      // The note lives in the request's description and nowhere else, so it
-      // is read back per request. Bounded by the open requests on ONE item —
-      // a handful at most — and a detail that cannot be fetched costs the
-      // note, never the line it belongs to.
+      // The note is the request's own column, read back per request.
+      // Bounded by the open requests on ONE item — a handful at most — and a
+      // detail that cannot be fetched costs the note, never the line it
+      // belongs to.
       const withNotes = await Promise.all(
         rows.map(async (row) => {
           const detail = await workflow
             .getChangeRequestDetail(row.number, { patches: false })
             .catch(() => null);
-          const note = extractRequestNote(detail?.body);
+          const note = detail?.accessRequest?.note;
           return note ? { ...row, note } : row;
         }),
       );

package/src/modules/access/access-requests.service.ts

@@ -10,8 +10,8 @@ import {
 } from '../../shared/domain-errors.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import { spliceGrant } from '../access-model/access-splice.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import { spliceGrant } from '../access-model/index.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import { logger } from '../../shared/logging.js';
 import { AccessMutationError } from './access-mutation.service.js';
 import {
@@ -50,7 +50,7 @@ export function itemNameOf(repoRelPath: string): string {
 /**
  * Neutralise every character a markdown renderer would read as structure.
  *
- * The note is somebody's free text and it lands in a change request's
+ * The note is somebody's free text and it is quoted in a change request's
  * description, which IS rendered. Escaping it is what makes "plain text" true:
  * without this a note can carry a heading, a link, or an image pointing at a
  * URL that logs whoever opens the request.
@@ -59,64 +59,6 @@ export function escapeMarkdown(text: string): string {
   return text.replace(/[\\`*_{}[\]()#+\-.!|<>~]/g, (c) => `\\${c}`);
 }
 
-/** The exact inverse of {@link escapeMarkdown} — only our own backslashes go. */
-function unescapeMarkdown(text: string): string {
-  return text.replace(/\\([\\`*_{}[\]()#+\-.!|<>~])/g, '$1');
-}
-
-/**
- * The fence the note sits behind in a request's description.
- *
- * The description is the note's only home — there is no column for it — so the
- * editors' banner has to read it back out of prose. Marking the block means
- * that read is exact rather than a guess at which paragraph was the note, and
- * an HTML comment is invisible in every surface that renders the description.
- */
-const NOTE_OPEN = '<!--hexis:access-request-note-->';
-const NOTE_CLOSE = '<!--/hexis:access-request-note-->';
-
-/**
- * The level, recorded on the change request itself.
- *
- * The branch says what is proposed, but only while it can be read — and a
- * clone whose refs are a few seconds stale cannot read a branch cut moments
- * ago. The request's own row always can. "Requested: <level>" is a promise
- * about a request, so it is answered from the request, not from a file at a
- * ref that may not have arrived yet.
- */
-const LEVEL_MARK = /<!--hexis:access-request-level:(write|owner)-->/;
-
-/**
- * The requester's own words, back out of a request's description, or
- * undefined when they wrote none. Unescaped exactly as they were escaped, so
- * what the banner shows is what was typed.
- */
-/**
- * The level a request asks for, off its own description. Undefined for a
- * request opened before this marker existed — those are the skill route's,
- * and the skill route only ever asked for `write`.
- */
-export function extractRequestLevel(body: string | null | undefined): RequestLevel | undefined {
-  const hit = body ? LEVEL_MARK.exec(body) : null;
-  return hit ? (hit[1] as RequestLevel) : undefined;
-}
-
-export function extractRequestNote(body: string | null | undefined): string | undefined {
-  if (!body) return undefined;
-  const start = body.indexOf(NOTE_OPEN);
-  if (start < 0) return undefined;
-  const end = body.indexOf(NOTE_CLOSE, start);
-  if (end < 0) return undefined;
-  const note = body
-    .slice(start + NOTE_OPEN.length, end)
-    .split(/\r?\n/)
-    .filter((line) => line.startsWith('>'))
-    .map((line) => unescapeMarkdown(line.replace(/^>\s?/, '')))
-    .join('\n')
-    .trim();
-  return note || undefined;
-}
-
 /**
  * Asking for Can edit or Owner on ONE item, and reading back what came of it.
  *
@@ -261,11 +203,15 @@ export class AccessRequestsService {
     }
 
     try {
+      // The level and the note are the request's own columns — what the
+      // dialog and the editors' banner read back. The description is for the
+      // people who read the request, and says the same things in prose.
       const detail = await workflow.openChangeRequest(ws.id, user, {
         sourceBranch: branch,
         targetBranch: kb.defaultBranch,
         title: `Access request: ${itemName}`,
         description: this.describe({ user, target, level, note }),
+        accessRequest: { level, ...(note ? { note } : {}) },
       });
       return { number: detail.number, level };
     } catch (err) {
@@ -331,18 +277,21 @@ export class AccessRequestsService {
   }
 
   /**
-   * The level change request `number` asks for, off its own description.
+   * The level change request `number` asks for, off the request's own row.
    *
-   * `write` when the description does not say: every request that predates the
-   * marker came from the skill page's "Request write access", which asks for
-   * exactly that. A detail that cannot be fetched falls there too — the line
-   * it feeds says which level was asked for, and Can edit is the lesser claim.
+   * The branch says what is proposed, but only while it can be read — and a
+   * clone whose refs are a few seconds stale cannot read a branch cut moments
+   * ago. The request's row always can. `write` when the row does not say:
+   * every request that predates the column came from the skill page's
+   * "Request write access", which asks for exactly that. A detail that cannot
+   * be fetched falls there too — the line it feeds says which level was asked
+   * for, and Can edit is the lesser claim.
    */
   private async levelOf(number: number): Promise<RequestLevel> {
     const detail = await this.deps.workflow
       .getChangeRequestDetail(number, { patches: false })
       .catch(() => null);
-    return extractRequestLevel(detail?.body) ?? 'write';
+    return detail?.accessRequest?.level ?? 'write';
   }
 
   /**
@@ -390,7 +339,12 @@ export class AccessRequestsService {
     }
   }
 
-  /** The description an editor reads: who, what, where, the note, and how to answer. */
+  /**
+   * The description an editor reads: who, what, where, the note, and how to
+   * answer. Prose only — the level and the note the platform reads back are
+   * the request's own columns, so nothing hidden is written here and an edit
+   * of the description loses nothing.
+   */
   private describe(input: {
     user: AuthUser;
     target: AccessRequestTarget;
@@ -400,14 +354,12 @@ export class AccessRequestsService {
     const { user, target, level, note } = input;
     const who = escapeMarkdown(user.name || user.email);
     const lines = [
-      `<!--hexis:access-request-level:${level}-->`,
       `${who} (${escapeMarkdown(user.email)}) asked for **${LEVEL_LABEL[level]}** on ` +
         `${escapeMarkdown(target.path || 'the workspace')}.`,
     ];
     if (note) {
-      lines.push('', `Note from ${who}:`, '', NOTE_OPEN);
+      lines.push('', `Note from ${who}:`, '');
       for (const line of note.split(/\r?\n/)) lines.push(`> ${escapeMarkdown(line)}`);
-      lines.push(NOTE_CLOSE);
     }
     lines.push(
       '',
@@ -418,3 +370,9 @@ export class AccessRequestsService {
     return lines.join('\n');
   }
 }
+
+/**
+ * What another module needs of the access-request service: to open one.
+ * Injected by the composition root, which owns the implementation.
+ */
+export type IAccessRequests = Pick<AccessRequestsService, 'open'>;

package/src/modules/access/access-view.ts

@@ -14,7 +14,7 @@ import {
   KNOWN_VERBS,
   ROLE_TOKEN_PREFIX,
   type Verb,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 
 /**
  * The resolved access view of one target, as the Manage access dialog reads it

package/src/modules/access/access.routes.ts

@@ -17,15 +17,13 @@ import type {
   GrantPrincipal,
   GrantSources,
 } from './access-control.interface.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
-import type { AuthService } from '../auth/auth.service.js';
-import type { IAccountSwitchGuard } from '../auth/account-switch-guard.js';
-import type { WorkflowService } from '../workflow/workflow.service.js';
-import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { AuthService, IAccountSwitchGuard } from '../auth/index.js';
+import type { WorkflowService, WorkflowEventBus } from '../workflow/index.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
-import { AccessDeniedError } from '../access-model/access-errors.js';
+import { AccessDeniedError } from '../access-model/index.js';
 import {
   AccessMutationService,
   AccessMutationError,
@@ -43,17 +41,17 @@ import {
   ROLE_TOKEN_PREFIX,
   type PluginTokenVerb,
   type Verb,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 import { listAccessDeclarationsUnder } from './access-declarations.js';
 import { emailsInView, holderPrincipals, labelAccountHolders, resolveAccessView } from './access-view.js';
 import type { AccessView, LabelledAccessView } from './access-view.js';
 import { toHttpError as sharedToHttpError, requireNonEmptyString as sharedRequireNonEmptyString } from './admin-route-helpers.js';
 import { RolesAdminService } from './roles-admin.service.js';
-import type { Principal } from '../access-model/access-splice.js';
-import type { Database } from '../database/connection.js';
-import { users } from '../database/schema.js';
+import type { Principal } from '../access-model/index.js';
+import type { Database } from '../database/index.js';
+import { users } from '../database/index.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
-import '../auth/auth.middleware.js';
+import '../auth/index.js';
 
 /** Verbs the share UI may grant. Verbs are independent — `download` is grantable on its own. */
 const GRANTABLE_VERBS = new Set<string>(['read', 'write', 'owner', 'download']);

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

@@ -48,8 +48,9 @@
 import path from 'node:path';
 import { logger } from '../../shared/logging.js';
 
-import { LockingFilesystem, type WriteValidator } from '../kb-fs/locking-filesystem.js';
-import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
+import { type WriteValidator, LockingFilesystem } from '../kb-fs/index.js';
+import type { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { PushNeedsAgentResolutionError } from '../../shared/domain-errors.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
 

package/src/modules/access/capability-registry.ts

@@ -18,7 +18,7 @@
  * really a group; the roles admin surface flags it with a convert action.
  */
 
-import { ADMIN_CANONICAL, canonicalRoleName } from '../access-model/access-grammar.js';
+import { ADMIN_CANONICAL, canonicalRoleName } from '../access-model/index.js';
 
 /** A capability an app surface gates on. Grow this union with the gates. */
 export type Capability =

package/src/modules/access/change-read-gate.ts

@@ -18,12 +18,10 @@ import path from 'node:path';
 import { creatableRootDirNames, type KbLayout } from '@bevel-software/platform-shared';
 import type { IFsProbe } from '../../shared/fs.contract.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { IAccessControl } from './access-control.interface.js';
-import { AccessConfigError, AccessDeniedError } from '../access-model/access-errors.js';
-import { SYNCED_GROUPS_YAML } from '../access-model/group-files.js';
-import { toKbRelative } from '../access-model/kb-read-filter.js';
-import type { ChangeReadVerdict, ChangeTargetKind, IChangeReadGate } from '../access-model/change-gate.js';
+import { AccessConfigError, AccessDeniedError, SYNCED_GROUPS_YAML, toKbRelative } from '../access-model/index.js';
+import type { ChangeReadVerdict, ChangeTargetKind, IChangeReadGate } from '../access-model/index.js';
 
 /**
  * Whether `kbRel` (repo-relative) is, or lies inside, a folder directly under

package/src/modules/access/creator-access.ts

@@ -34,17 +34,15 @@ const log = logger('creator-access');
 
 import type { IFsProbe } from '../../shared/fs.contract.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { IAccessControl } from './access-control.interface.js';
-import { spliceGrant, type Principal } from '../access-model/access-splice.js';
-import { isAccessMdPath } from '../access-model/access-grammar.js';
-import { toKbRelative } from '../access-model/kb-read-filter.js';
+import { spliceGrant, type Principal, isAccessMdPath, toKbRelative } from '../access-model/index.js';
 import {
   creatorPrincipal,
   type CreationGrantPlan,
   type Creator,
   type ICreatorAccess,
-} from '../access-model/creator.js';
+} from '../access-model/index.js';
 
 export class CreatorAccessService implements ICreatorAccess {
   constructor(

package/src/modules/access/directory-sync-bot.ts

@@ -3,8 +3,8 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('directory-sync');
 import type { AuthUser } from '@bevel-software/platform-shared';
-import type { Database } from '../database/connection.js';
-import { users } from '../database/core-schema.js';
+import type { Database } from '../database/index.js';
+import { users } from '../database/index.js';
 
 /**
  * Synthetic identity for the synced-groups materializer's commits: every

package/src/modules/access/groups-admin.routes.ts

@@ -1,10 +1,10 @@
 import express from 'express';
 import type { AuthUser } from '@bevel-software/platform-shared';
-import type { IAdminAccessService } from '../admin/admin.interface.js';
-import { canonicalRoleName } from '../access-model/access-grammar.js';
+import type { IAdminAccessService } from '../admin/index.js';
+import { canonicalRoleName } from '../access-model/index.js';
 import { sendError as sharedSendError, requireNonEmptyString as sharedRequireNonEmptyString } from './admin-route-helpers.js';
 import type { GroupsAdminService } from './groups-admin.service.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import '../auth/index.js'; // Express Request augmentation
 
 /**
  * Admin surface for GROUPS — the "who you are" half of the roles/groups

package/src/modules/access/groups-admin.service.ts

@@ -26,7 +26,7 @@
  */
 
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { WorkflowEventBus } from '../workflow/index.js';
 import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { IAccessControl } from './access-control.interface.js';
@@ -34,11 +34,10 @@ import {
   GROUP_REF_PREFIX,
   canonicalRoleName,
   hasAccessFrontmatterExtension,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 import { loadActiveGroups, type GroupsHealth } from './access-control.service.js';
-import { GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile } from '../access-model/group-files.js';
+import { GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile, makeRolesYamlWriteValidator } from '../access-model/index.js';
 import { parseRolesModel, removeGroupRefsEverywhere, renameGroupRefs, isGroupRefMember } from './roles-edit.js';
-import { makeRolesYamlWriteValidator } from '../access-model/roles-yaml-guard.js';
 import {
   GroupsEditError,
   parseGroupsModel,

package/src/modules/access/groups-edit.ts

@@ -20,8 +20,8 @@ import {
   EMAIL_REGEX,
   GROUP_REF_PREFIX,
   RESERVED_ROLE_NAMES,
-} from '../access-model/access-grammar.js';
-import { GROUPS_YAML, parseGroupsFile, unsafeNameReason } from '../access-model/group-files.js';
+} from '../access-model/index.js';
+import { GROUPS_YAML, parseGroupsFile, unsafeNameReason } from '../access-model/index.js';
 
 /** Bad-input failure when editing groups.yaml. */
 export class GroupsEditError extends Error {

package/src/modules/access/index.ts

@@ -0,0 +1,17 @@
+/**
+ * What the access module offers the other modules: the contract of the access
+ * service — who may read, write and own what. The implementation is wired by
+ * the composition root.
+ */
+export type { IAccessControl } from './access-control.interface.js';
+// Reached by other modules; exported here so they stop importing the files.
+export type { AccessDecisionSource, AccessTargetKind } from './access-control.interface.js';
+export { accessMdPathForFolder, fileCarriesAccessRules, governingFolderOf } from './access-mutation.service.js';
+export type { AccessMutationService, IAccessMutation, TargetKind } from './access-mutation.service.js';
+export { folderTarget, rulesFileFor } from './access-requests.contract.js';
+export type { AccessRequestTarget, IAccessRequestLifecycle } from './access-requests.contract.js';
+export type { AccessRequestsService, IAccessRequests } from './access-requests.service.js';
+export { accessRoster, resolveAccessView } from './access-view.js';
+export { sendError } from './admin-route-helpers.js';
+export { DIRECTORY_SYNC_BOT_EMAIL } from './directory-sync-bot.js';
+export type { UserAccessRemovalService } from './user-access-removal.service.js';