@bevel-software/platform-core-backend 0.15.1 → 0.20.0

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

@@ -46,11 +46,12 @@
  */
 
 import path from 'node:path';
+import { logger } from '../../shared/logging.js';
 
-import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
+import { LockingFilesystem, type WriteValidator } from '../kb-fs/locking-filesystem.js';
 import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
+import { isAbsence } from '../../shared/fs.contract.js';
 import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
-import type { FileContent } from '@mastra/core/workspace';
 
 export interface LockedCommitDeps {
   workspaceService: IWorkspaceService;
@@ -65,7 +66,7 @@ export interface LockedCommitDeps {
   /** Contention wording: what is "being edited by <holder>". */
   contendedSubject: string;
   /** Pre-disk write validator handed to LockingFilesystem writes. */
-  validateWrite?: (path: string, content: FileContent) => void;
+  validateWrite?: WriteValidator;
 }
 
 export interface LockedWrite {
@@ -114,8 +115,7 @@ export class AdminLockedCommits {
         path.posix.join(this.deps.kbDirName, repoRel),
       );
     } catch (err) {
-      const code = (err as NodeJS.ErrnoException | null)?.code;
-      if (code === 'ENOENT' || code === 'ENOTDIR') return null;
+      if (isAbsence(err)) return null;
       throw err;
     }
   }
@@ -256,10 +256,10 @@ export class AdminLockedCommits {
             await this.deps.workflowService.releaseLock(workspaceId, this.defaultBranch, h, actor);
           }
         } catch (releaseErr) {
-          console.warn(
-            `[${this.deps.logTag}] could not release lock on ${h}${pushRetry ? ' (push-retry release)' : ''}; ` +
+          logger(this.deps.logTag).warn(
+            `could not release lock on ${h}${pushRetry ? ' (push-retry release)' : ''}; ` +
               'it frees on TTL — continuing with the remaining locks:',
-            releaseErr instanceof Error ? releaseErr.message : releaseErr,
+            { err: releaseErr },
           );
         }
       }
@@ -286,7 +286,7 @@ export class AdminLockedCommits {
           try {
             await workspaceService.deleteFile(workspaceId, this.wsRel(f.repoRel));
           } catch (err) {
-            if ((err as NodeJS.ErrnoException | null)?.code !== 'ENOENT') throw err;
+            if (!isAbsence(err)) throw err;
           }
         } else {
           await workspaceService.writeFile(workspaceId, this.wsRel(f.repoRel), f.content);
@@ -306,9 +306,7 @@ export class AdminLockedCommits {
       // normally; the error itself tells the caller "saved locally, sharing
       // will be resolved" and the pending-commit ladder retries the push.
       if (err instanceof PushNeedsAgentResolutionError) {
-        console.warn(
-          `[${logTag}] commit landed but the push needs resolution — edit saved; publishing will be retried`,
-        );
+        logger(logTag).warn('commit landed but the push needs resolution — edit saved; publishing will be retried');
         throw err;
       }
       const unrestored = new Set<string>();
@@ -318,9 +316,9 @@ export class AdminLockedCommits {
           else await workspaceService.writeFile(workspaceId, this.wsRel(f.repoRel), f.original);
         } catch (restoreErr) {
           // Deleting an already-absent file IS the original state.
-          if (f.original === null && (restoreErr as NodeJS.ErrnoException | null)?.code === 'ENOENT') continue;
+          if (f.original === null && isAbsence(restoreErr)) continue;
           unrestored.add(this.wsRel(f.repoRel));
-          console.warn(`[${logTag}] could not restore ${f.repoRel} after a failed commit`);
+          logger(logTag).warn(`could not restore ${f.repoRel} after a failed commit`);
         }
       }
       if (unrestored.size > 0 && typeof err === 'object' && err !== null) {

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

@@ -13,7 +13,9 @@
  */
 
 import type express from 'express';
+import { logger } from '../../shared/logging.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { domainErrorBody } from '../../shared/http-errors.js';
 
 /** One error shape for every access-family route. */
 export function toHttpError(
@@ -21,11 +23,9 @@ export function toHttpError(
   logTag: string,
 ): { status: number; body: Record<string, unknown> } {
   if (err instanceof WorkflowDomainError && err.status < 500) {
-    // Spread the payload FIRST and assign `error` LAST — a payload key named
-    // `error` must never overwrite the message the client renders.
-    return { status: err.status, body: { ...(err.payload ?? {}), error: err.message } };
+    return { status: err.status, body: domainErrorBody(err) };
   }
-  console.error(`[${logTag}] route failure:`, err instanceof Error ? err.stack ?? err.message : err);
+  logger(logTag).error('route failure:', { err });
   const status = err instanceof WorkflowDomainError ? err.status : 500;
   return { status, body: { error: 'Internal error.' } };
 }

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

@@ -0,0 +1,148 @@
+/**
+ * Read-before-write: the gate every change passes on its way to the lock
+ * (`WorkflowService.acquireLock`), on every branch. Contract and rationale in
+ * `access-model/change-gate.ts`; this is the service that answers.
+ *
+ * The verdict is taken against the WORKING TREE, not `HEAD` as the write gate
+ * does. That is deliberate. The creator grant a new top-level folder gets is
+ * seeded into its `access.md` in a lock+commit cycle of its own and the
+ * commit lands from a background queue, so the first file written into that
+ * folder would find `HEAD` without the grant and be refused. The working
+ * tree has it at once. The self-grant a `HEAD` reading guards against does
+ * not open here: a person can only edit an `access.md` they may write, that
+ * write is itself gated, and on a draft the edit reaches a shared branch
+ * only through a change request that shows it.
+ */
+
+import path from 'node:path';
+import { creatableRootDirNames } from '@bevel-software/platform-shared';
+import type { IFsProbe } from '../../shared/fs.contract.js';
+import type { WorkspaceService } from '../workspace/workspace.service.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';
+
+/**
+ * Whether `kbRel` (repo-relative) is, or lies inside, a folder directly under
+ * one of the three roots that does not exist yet — the read-before-write
+ * exception. Pure over `exists`, so the rule can be read and tested on its
+ * own; the service supplies the disk.
+ *
+ * A `'dir'` target is the folder itself (`Skills/new-skill`); a `'file'`
+ * target must lie INSIDE the new folder (`Skills/new-skill/SKILL.md`,
+ * `Plugins/team/access.md`): a loose file directly at a root has no folder
+ * to carry a creator grant and is not excepted.
+ */
+export async function isNewTopLevelFolderPath(
+  kbRel: string,
+  kind: ChangeTargetKind,
+  exists: (kbRel: string) => Promise<boolean>,
+): Promise<boolean> {
+  const segments = kbRel.split('/');
+  const root = segments[0];
+  if (root === undefined || !creatableRootDirNames().has(root)) return false;
+  if (segments.length < (kind === 'dir' ? 2 : 3)) return false;
+  return !(await exists(`${root}/${segments[1]}`));
+}
+
+export class ChangeReadGate implements IChangeReadGate {
+  constructor(
+    private readonly workspaceService: Pick<WorkspaceService, 'getWorkspacePath'>,
+    private readonly accessControl: Pick<IAccessControl, 'canRead' | 'holdsAdminRootWrite'>,
+    private readonly kbDirName: string,
+    private readonly disk: IFsProbe,
+  ) {}
+
+  async judge(
+    workspaceId: string,
+    userEmail: string,
+    wsPath: string,
+    kind: ChangeTargetKind,
+  ): Promise<ChangeReadVerdict> {
+    // A FOLDER target may be the repository root itself (the KB clone's own
+    // folder, which `toKbRelative` reads as "outside": no file lives there
+    // without rules). As a folder it is the root scope, `''`, and is judged
+    // like any other folder — an extraction into it is an extraction into
+    // whatever the root grants.
+    const norm = wsPath.replace(/^\.?\/+/, '').replace(/\/+$/, '');
+    const rel = kind === 'dir' && norm === this.kbDirName ? '' : toKbRelative(wsPath, this.kbDirName);
+    if (rel === null) return { allowed: true, via: 'outside-kb' };
+
+    const exists = (p: string) => this.exists(workspaceId, p);
+    try {
+      // The two rescues the write rule already has, for FILE targets only —
+      // both name files, and a folder target is never one of them.
+      if (kind === 'file') {
+        // The directory-sync bot's file: its writer is named by the write
+        // rule (`machineOwnedWriteRule`), and read rules never name a machine.
+        if (rel === SYNCED_GROUPS_YAML) return { allowed: true, via: 'machine-owned' };
+        // The admin rescue, in the same shape the write floor has it: an
+        // admin holds write on the repository root's own files (`roles.yaml`,
+        // `access.md`, `groups.yaml`, the agent guide, …) whatever the root rules
+        // say, so that a tree whose root grants nobody can still be repaired
+        // from inside the app. A subfolder's `access.md` is an ordinary path:
+        // an admin who cannot read the folder cannot change it either.
+        if (!rel.includes('/') && (await this.accessControl.holdsAdminRootWrite(workspaceId, userEmail))) {
+          return { allowed: true, via: 'admin-rescue' };
+        }
+      }
+      if (await isNewTopLevelFolderPath(rel, kind, exists)) {
+        return { allowed: true, via: 'new-top-level-folder' };
+      }
+      if (await this.accessControl.canRead(workspaceId, userEmail, rel)) {
+        return { allowed: true, via: 'readable' };
+      }
+    } catch (err) {
+      // No config on this tree at all (a repository before its first
+      // `roles.yaml`): the write gate treats the same state as "nothing to
+      // decide against" and so does this one. A `roles.yaml` that is THERE
+      // but unusable is a different thing — a broken rule set must not read
+      // as an open door — and propagates, as does any other failure: a
+      // verdict from a half-read tree is not a verdict.
+      if (err instanceof AccessConfigError && !(await exists('roles.yaml'))) {
+        return { allowed: true, via: 'no-rules' };
+      }
+      throw err;
+    }
+    return { allowed: false, unreadable: await this.unreadablePlace(rel, exists) };
+  }
+
+  async assertMayChange(
+    workspaceId: string,
+    userEmail: string,
+    wsPath: string,
+    kind: ChangeTargetKind,
+  ): Promise<void> {
+    const verdict = await this.judge(workspaceId, userEmail, wsPath, kind);
+    if (verdict.allowed) return;
+    throw new AccessDeniedError({
+      path: wsPath,
+      eligibleRoles: [],
+      eligibleUsers: [],
+      unreadable: verdict.unreadable,
+    });
+  }
+
+  /**
+   * What to name in the refusal: the target when it is there (a change to
+   * something the caller cannot see), otherwise the folder the new thing
+   * would land in — the place whose rules decided.
+   */
+  private async unreadablePlace(rel: string, exists: (p: string) => Promise<boolean>): Promise<string> {
+    if (await exists(rel)) return rel;
+    const parent = path.posix.dirname(rel);
+    return parent === '.' ? '' : parent;
+  }
+
+  /**
+   * Whether something is at the repo-relative `rel` on this workspace's disk.
+   * Links are NOT followed: a link, dangling or not, is something there — a
+   * folder it stands in for is not "new", and no exception is read through it.
+   */
+  private async exists(workspaceId: string, rel: string): Promise<boolean> {
+    const wsDir = await this.workspaceService.getWorkspacePath(workspaceId);
+    return (await this.disk.lstatOrNull(path.join(wsDir, this.kbDirName, rel))) !== null;
+  }
+}

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

@@ -1,40 +1,38 @@
 /**
- * Creator read-grant on creation.
+ * Creator read-grant on creation — for the one place a creation may land
+ * where its creator cannot read: a NEW FOLDER directly under one of the three
+ * roots (knowledge, skills, plugins).
  *
- * `read` is default-deny (see `IAccessControl.canRead`), so a brand-new file
- * or folder created at a spot whose `access.md` chain never names the creator
- * would instantly vanish from the creator's own explorer and be unreadable to
- * them. This service decides — BEFORE the bytes land — whether a creation
- * needs an automatic `read:` grant for the creator, and where that grant must
- * live so the thing stays visible:
+ * `read` is default-deny (see `IAccessControl.canRead`), and the roots grant
+ * read to nobody by default, so a folder started there by someone the root
+ * does not name would vanish from their own explorer the moment it appeared.
+ * This service decides — BEFORE the bytes land — whether a creation is that
+ * case, and plans the grant: a `read:` line for the creator, seeded into the
+ * new folder's own `access.md`. Chain inheritance carries it to the whole new
+ * subtree, the explorer's dir-chain check sees it, and it can never widen
+ * access to pre-existing content — everything under a brand-new folder was
+ * created by this very operation.
  *
- *   - When the creation brings a NEW directory into existence (a new folder,
- *     or a file whose path mkdirs ancestors), the grant is seeded into the
- *     TOPMOST new directory's own `access.md`. That covers the entire new
- *     subtree via chain inheritance, is visible to the explorer's shallow
- *     (dir-chain-only) check, and can never widen access to pre-existing
- *     content — everything under a brand-new directory was created by this
- *     very operation.
- *   - When a loose `.md` file is created directly inside a PRE-EXISTING
- *     folder, the grant is spliced into the file's own frontmatter (the
- *     per-file scope; granting on the existing folder's `access.md` would
- *     leak read on all its siblings). Frontmatter is invisible to the
- *     explorer's shallow check by design (read-filter plan D5); the tree
- *     route compensates with a bounded full check for entries directly under
- *     the structural roots — the only place a loose file can sit inside a
- *     visible folder without sharing its chain verdict.
- *   - Non-markdown files in a pre-existing unreadable folder can't carry
- *     frontmatter, so no per-file grant is possible; the creation proceeds
- *     ungranted (logged).
+ * Everywhere else the read-before-write gate (`ChangeReadGate`) refuses a
+ * creation the creator could not see, so no other grant is needed: a file or
+ * folder made inside a readable folder inherits that folder's rules, and the
+ * creator reads it as they read its parent. The per-file frontmatter grant
+ * that used to cover loose markdown files in unreadable folders is gone with
+ * the case it covered.
  *
  * The grant is best-effort UX, not an authorization gate: any failure here
  * (unreadable access config, splice error) must never fail the creation
  * itself, so every decision path degrades to "no grant" with a warning.
  */
 
-import fs from 'node:fs/promises';
 import path from 'node:path';
+import { creatableRootDirNames } from '@bevel-software/platform-shared';
+import { logger } from '../../shared/logging.js';
+import { printable } from '../../shared/printable.js';
 
+const log = logger('creator-access');
+
+import type { IFsProbe } from '../../shared/fs.contract.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { IAccessControl } from './access-control.interface.js';
 import { spliceGrant, type Principal } from '../access-model/access-splice.js';
@@ -52,17 +50,29 @@ export class CreatorAccessService implements ICreatorAccess {
     private readonly workspaceService: WorkspaceService,
     private readonly accessControl: IAccessControl,
     private readonly kbDirName: string,
+    private readonly disk: IFsProbe,
   ) {}
 
+  /**
+   * Whether something is at `abs`. Links are NOT followed: a link, dangling
+   * or not, is something there — never a "new" folder to seed a grant under,
+   * so no seed is ever planned through one. (The write itself refuses a path
+   * behind a link regardless; this keeps the plan honest one step earlier.)
+   */
+  private async exists(abs: string): Promise<boolean> {
+    return (await this.disk.lstatOrNull(abs)) !== null;
+  }
+
   /**
    * Decide whether creating `wsRelPath` (workspace-relative) needs a creator
    * read grant, and compute it. Returns null when no grant is needed or none
    * is possible: the path is outside the KB repo, is itself access config
    * (`access.md` / `roles.yaml`) or a `.gitkeep` placeholder, already exists
-   * on disk (not a create), is already readable by the creator, or is a
-   * non-markdown file in a pre-existing folder. Must be called BEFORE the
-   * creation mutates the disk — the topmost-new-directory detection stats the
-   * current tree.
+   * on disk (not a create), is already readable by the creator, or does not
+   * bring a new folder directly under one of the three roots into existence
+   * — the only creation the read-before-write gate lets past an unreadable
+   * spot. Must be called BEFORE the creation mutates the disk — the
+   * new-folder detection stats the current tree.
    */
   async planForCreate(
     workspaceId: string,
@@ -77,7 +87,7 @@ export class CreatorAccessService implements ICreatorAccess {
     try {
       const wsDir = await this.workspaceService.getWorkspacePath(workspaceId);
       repoDir = path.join(wsDir, this.kbDirName);
-      if (await exists(path.join(repoDir, rel))) return null; // not a create
+      if (await this.exists(path.join(repoDir, rel))) return null; // not a create
       if (await this.accessControl.canRead(workspaceId, creator.email, rel)) return null;
     } catch (err) {
       // Unusable access config (e.g. missing roles.yaml) or workspace lookup
@@ -87,101 +97,64 @@ export class CreatorAccessService implements ICreatorAccess {
       return null;
     }
 
-    const principal = this.principalFor(creator);
-
-    // Topmost path segment that does not exist yet: for a dir target that is
-    // at worst the dir itself (its absence was established above), for a file
-    // target only the ancestor directories are candidates.
+    // The folder the creation would bring into existence directly under a
+    // root: for a dir target that may be the dir itself, for a file target
+    // only its ancestors are candidates. Anything else — a loose file at a
+    // root, a create inside an existing folder — is not this service's case:
+    // the gate refuses what the creator cannot read, and what they can read
+    // needs no grant.
     const segments = rel.split('/');
     if (kind === 'file') segments.pop();
-    let acc = '';
-    for (const seg of segments) {
-      acc = acc ? `${acc}/${seg}` : seg;
-      if (!(await exists(path.join(repoDir, acc)))) {
-        try {
-          // Validate the principal now (a bad one throws), so a doomed plan
-          // is dropped here instead of surfacing at every write site.
-          spliceGrant('', 'read', principal, { allowScalar: false });
-        } catch (err) {
-          warnSkipped(rel, err);
-          return null;
-        }
-        // NOTE: a direct plugin folder (`Plugins/<Name>`) is no longer special
-        // here. Plugins — and personal folders — are made by the dedicated
-        // provisioning endpoint (`PluginProvisionService`), which writes the
-        // full ownership template itself; this generic read-grant only covers
-        // ad-hoc folder creation elsewhere in the tree.
-        return {
-          kind: 'seed-access-md',
-          wsRelPath: `${this.kbDirName}/${acc}/access.md`,
-          apply: (current: string) => {
-            try {
-              // Idempotent merge into whatever is on disk by write time — a
-              // concurrent creator's grant survives; ours lands next to it.
-              // `target: 'folder'` so a new-format access.md (body-governed)
-              // gets the grant in its FOLDER rules, never its self-frontmatter.
-              return spliceGrant(current, 'read', principal, {
-                allowScalar: false,
-                target: 'folder',
-              }).text;
-            } catch (err) {
-              warnSkipped(rel, err);
-              return current;
-            }
-          },
-        };
-      }
+    const root = segments[0];
+    if (root === undefined || segments.length < 2 || !creatableRootDirNames().has(root)) return null;
+    const top = `${root}/${segments[1]}`;
+    try {
+      if (await this.exists(path.join(repoDir, top))) return null;
+    } catch (err) {
+      // A probe that failed (a permission error, an I/O error) is not "not
+      // there": planning on that would seed a grant into a folder that may
+      // exist. Best-effort, as above — no plan. The read gate probes the same
+      // place next and fails the request outright rather than judge a tree
+      // it could not read, so nothing is created on a guess either.
+      warnSkipped(rel, err);
+      return null;
     }
 
-    // No new directory — a file created directly inside an existing folder.
-    // Only markdown can carry a per-file frontmatter grant.
-    if (!rel.endsWith('.md')) {
-      console.warn(
-        `[creator-access] cannot grant creator read on "${rel}" — a non-markdown file in a folder without a read grant carries no frontmatter`,
-      );
+    const principal = this.principalFor(creator);
+    try {
+      // Validate the principal now (a bad one throws), so a doomed plan is
+      // dropped here instead of surfacing at every write site.
+      spliceGrant('', 'read', principal, { allowScalar: false });
+    } catch (err) {
+      warnSkipped(rel, err);
       return null;
     }
+    // NOTE: a direct plugin folder (`Plugins/<Name>`) is not special here.
+    // Plugins — and personal folders — are made by the dedicated provisioning
+    // endpoint (`PluginProvisionService`), which writes the full ownership
+    // template itself; this generic read-grant covers the ad-hoc folder a
+    // person starts at a root by any other route.
     return {
-      kind: 'frontmatter',
-      apply: (content: string) => {
+      kind: 'seed-access-md',
+      wsRelPath: `${this.kbDirName}/${top}/access.md`,
+      apply: (current: string) => {
         try {
-          return spliceGrant(content, 'read', principal, { allowScalar: true }).text;
+          // Idempotent merge into whatever is on disk by write time — a
+          // concurrent creator's grant survives; ours lands next to it.
+          // `target: 'folder'` so a new-format access.md (body-governed)
+          // gets the grant in its FOLDER rules, never its self-frontmatter.
+          return spliceGrant(current, 'read', principal, {
+            allowScalar: false,
+            target: 'folder',
+          }).text;
         } catch (err) {
           warnSkipped(rel, err);
-          return content;
+          return current;
         }
       },
     };
   }
 
-  /**
-   * The after-the-fact variant for files that are ALREADY on disk when we
-   * first see them (zip extraction writes straight to the working tree).
-   * Returns the file's content with the creator's read grant spliced into its
-   * frontmatter — for the caller to write back under its lock — or null when
-   * no grant is needed/possible (non-KB path, non-markdown, already readable,
-   * unreadable config, no-op splice).
-   */
-  async grantInExtractedFile(
-    workspaceId: string,
-    creator: Creator,
-    wsRelPath: string,
-  ): Promise<string | null> {
-    const rel = this.grantablePath(wsRelPath);
-    if (rel === null || !rel.endsWith('.md')) return null;
-    try {
-      if (await this.accessControl.canRead(workspaceId, creator.email, rel)) return null;
-      const content = await this.workspaceService.readFile(workspaceId, wsRelPath);
-      const result = spliceGrant(content, 'read', this.principalFor(creator), {
-        allowScalar: true,
-      });
-      return result.changed ? result.text : null;
-    } catch (err) {
-      warnSkipped(rel, err);
-      return null;
-    }
-  }
-
   /**
    * Drop the resolver's cached model after a seeded `access.md` lands, so the
    * very next tree build / read check sees the new grant instead of waiting
@@ -210,18 +183,10 @@ export class CreatorAccessService implements ICreatorAccess {
   }
 }
 
-async function exists(absolutePath: string): Promise<boolean> {
-  try {
-    await fs.stat(absolutePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
+/**
+ * `rel` is the caller's own text and is quoted as one token; the error goes
+ * as an error, which every sink of the logger port escapes on its own.
+ */
 function warnSkipped(rel: string, err: unknown): void {
-  console.warn(
-    `[creator-access] skipped creator read grant for "${rel}":`,
-    err instanceof Error ? err.message : err,
-  );
+  log.warn(`skipped creator read grant for ${printable(rel)}:`, { err });
 }

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

@@ -1,4 +1,7 @@
 import { eq } from 'drizzle-orm';
+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';
@@ -28,7 +31,7 @@ export async function ensureDirectorySyncBot(db: Database): Promise<AuthUser> {
     .returning();
   if (inserted.length > 0) {
     const row = inserted[0];
-    console.log(`[directory-sync] created sync-bot user id=${row.id} email=${row.email}`);
+    log.info(`created sync-bot user id=${row.id} email=${row.email}`);
     return { id: row.id, email: row.email, name: row.name, avatarUrl: row.avatarUrl ?? undefined };
   }
   const [row] = await db

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

@@ -18,10 +18,10 @@
  *     precedence then resolves (group first, `role/<name>` for the role).
  *   - DEGRADE LOUDLY: a broken groups source never fails access resolution
  *     closed — groups contribute nothing and the model carries a
- *     `groupsHealth` marker, which the roster exposes so the Groups page can
+ *     `groupsHealth` marker, which the roster exposes so the Groups & Members page can
  *     banner it. A broken MANUAL groups.yaml additionally makes the roster
  *     answer 422 with the parse message (the operator must see what to fix —
- *     never a dead Groups page, never a silent empty roster they might
+ *     never a dead Groups & Members page, never a silent empty roster they might
  *     "repair" by re-creating groups over live bytes).
  */
 
@@ -87,7 +87,7 @@ export interface GroupsRoster {
   /**
    * Health of the active groups source — `ok: false` when the source exists
    * but is unreadable/unparseable (resolution degrades: groups contribute
-   * nothing). Shipped for the Groups page banner (frontend increment).
+   * nothing). Shipped for the Groups & Members page banner (frontend increment).
    */
   groupsHealth: GroupsHealth;
 }

package/src/modules/access/reference-scan.ts

@@ -23,7 +23,7 @@
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 
-import type { FileTreeEntry, IWorkspaceService } from '@bevel-software/platform-shared';
+import { isFrontmatterFence, type FileTreeEntry, type IWorkspaceService } from '@bevel-software/platform-shared';
 import {
   KNOWN_VERBS,
   accessMdDeclaresBodyRules,
@@ -46,9 +46,9 @@ import {
  *     nothing is rewritten.
  */
 function configLineRange(lines: string[], isMarkdown: boolean): { start: number; end: number } {
-  if (lines.length > 0 && lines[0].trim() === '---') {
+  if (lines.length > 0 && isFrontmatterFence(lines[0])) {
     for (let i = 1; i < lines.length; i++) {
-      if (lines[i].trim() === '---') return { start: 1, end: i };
+      if (isFrontmatterFence(lines[i])) return { start: 1, end: i };
     }
     // Unterminated frontmatter — treat nothing as eligible (don't risk the body).
     return { start: 0, end: 0 };
@@ -63,9 +63,9 @@ function configLineRange(lines: string[], isMarkdown: boolean): { start: number;
  *  fence-less access.md is a hard parse error to the resolver, so it is not
  *  a rule source and must not be rewritten). */
 function bodyLineRange(lines: string[]): { start: number; end: number } {
-  if (lines.length > 0 && lines[0].trim() === '---') {
+  if (lines.length > 0 && isFrontmatterFence(lines[0])) {
     for (let i = 1; i < lines.length; i++) {
-      if (lines[i].trim() === '---') return { start: i + 1, end: lines.length };
+      if (isFrontmatterFence(lines[i])) return { start: i + 1, end: lines.length };
     }
   }
   return { start: 0, end: 0 };