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

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 {
@@ -48,7 +48,7 @@ export interface GroupsEditResult {
 
 /** Thin assert wrapper over the SHARED name-safety predicate (`group-files.ts`
  *  `unsafeNameReason`) — one namespace, one set of rules, including the
- *  reserved `role/` prefix. */
+ *  reserved `role/` and `group/` prefixes. */
 export function assertSafeGroupDisplayName(displayName: string): void {
   const reason = unsafeNameReason(displayName);
   if (reason) {

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';

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

@@ -3,9 +3,15 @@
  * services (roles + groups) drive for "which access rules name this
  * principal" and "rewrite every reference atomically":
  *
- *   - `findRoleRefsInText` / `rewriteRoleTokensInText`: the config-region
- *     parse that decides what IS a principal reference. One source of truth,
- *     so the delete/rename warning and the rename rewrite can never disagree.
+ *   - `resolverRoleRefs`: what IS a principal reference — the resolver's own
+ *     parse of each file, so the reports name every enforced rule.
+ *   - `findRoleRefsInText` / `rewriteRoleTokensInText`: the line-level walk
+ *     the rename edits text with. It handles block lists and `key: value`
+ *     entries; quoted and flow-YAML own frontmatter is rewritten by the
+ *     full parser's own tree (`rewriteOwnFrontmatterStructurally`). The
+ *     rewrite re-checks its result with `resolverRoleRefs` and refuses
+ *     when a reference survives, so the warning and the rename can never
+ *     disagree.
  *   - `KbReferenceScanner`: candidate collection (every KB file with an
  *     access-frontmatter extension — `.md` and `.tool`, the resolver's own
  *     set), the advisory reference scan (cached — roster mutations must not
@@ -14,24 +20,37 @@
  *     file's ORIGINAL text too, so rollback snapshots reuse the read the
  *     rewrite already did instead of a second full-KB pass).
  *
- * Tokens here are the ENTRY-GRAMMAR canonical tokens: a bare name (group
- * first, then role) or an explicit `role/<name>`. Callers translate: a ROLE's
- * references are its bare token plus its `role/` token; a GROUP's are its
- * bare token only.
+ * Tokens here are the ENTRY-GRAMMAR canonical tokens: a bare name (the role
+ * when one exists, else the group) or an explicit `role/<name>` /
+ * `group/<name>`. Callers translate: a ROLE's references are its bare token
+ * plus its `role/` token; a GROUP's are its `group/` token, plus the bare
+ * token while no role shares the name.
  */
 
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 
-import { isFrontmatterFence, type FileTreeEntry, type IWorkspaceService } from '@bevel-software/platform-shared';
+import { Scalar, YAMLSeq, isAlias, isMap, isNode, isScalar, isSeq, parseDocument, type Document } from 'yaml';
+import { isFrontmatterFence, type IWorkspaceService } from '@bevel-software/platform-shared';
+import type { ITreeWalker } from '../../shared/fs.contract.js';
+import { logger } from '../../shared/logging.js';
+import { printable, sanitizedPath } from '../../shared/printable.js';
 import {
+  AccessDeniedError,
   KNOWN_VERBS,
   accessMdDeclaresBodyRules,
+  accessMdSelfEntries,
+  canonicalRoleName,
   hasAccessFrontmatterExtension,
   isAccessMdPath,
   parseAccessEntry,
+  parseAccessFile,
+  parseOwnAccessEntries,
   stripComment,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
+import type { ParsedEntry, Verb } from '../access-model/index.js';
+
+const log = logger('access');
 
 /**
  * Resolve the [start, end) line range that role rewrites may touch — the YAML
@@ -237,8 +256,8 @@ function walkRoleRefs(
 
 /**
  * Every genuine role/group reference in `text`'s rule regions, as
- * {role, verb} where `role` is the canonical ENTRY TOKEN (bare name or
- * `role/<name>`). `isAccessMd` marks an `access.md` file, whose BODY is a
+ * {role, verb} where `role` is the canonical ENTRY TOKEN (bare name,
+ * `role/<name>` or `group/<name>`). `isAccessMd` marks an `access.md` file, whose BODY is a
  * rule source in the body-governed format — see {@link ruleLineRanges}.
  */
 export function findRoleRefsInText(
@@ -291,6 +310,115 @@ export function rewriteRoleTokensInText(
   return changed ? lines.join('\n') : text;
 }
 
+/**
+ * The structural rewrite, for the references the line walk cannot edit:
+ * a file's OWN frontmatter is read by the full YAML parser whenever it holds
+ * flow sequences, quoted scalars or other real YAML (`ownEntriesRoot` in the
+ * grammar), and the line walk only knows block lists and `key: value`. So
+ * this edits the same document the resolver reads — the frontmatter's
+ * top-level verb keys, by the full parser's own node tree with the same
+ * FAILSAFE schema — and replaces each scalar entry whose token is in
+ * `oldTokens`, keeping its quoting, its comments and every other node. An
+ * alias the resolver reads as a verb's entries is never edited through: one
+ * that names an old token is replaced by a plain scalar, and one that is the
+ * verb's whole list (`read: *team`, `&team` a list) by a rewritten copy of
+ * that list, so the anchor it points at (which may sit under any other key)
+ * is left alone.
+ *
+ * The other rule sources — a legacy `access.md`'s frontmatter and a
+ * body-governed one's body — are read by the YAML-subset parser only, which
+ * the line walk mirrors, so they never need this.
+ */
+function rewriteOwnFrontmatterStructurally(
+  text: string,
+  oldTokens: ReadonlySet<string>,
+  newDisplayName: string,
+): string {
+  const lines = text.split('\n');
+  const { start, end } = configLineRange(lines, true);
+  if (start >= end) return text;
+  // Typed as an editable document: the rewrite puts new, unparsed scalars in it.
+  const doc: Document = parseDocument(lines.slice(start, end).join('\n'), { schema: 'failsafe' });
+  // A document the full parser rejects is not what the resolver read: it fell
+  // back to the subset parser, whose reading the line walk already covers.
+  if (doc.errors.length > 0 || !isMap(doc.contents)) return text;
+  let changed = false;
+  const rewritten = (node: unknown): Scalar | null => {
+    const target = isAlias(node) ? node.resolve(doc) : node;
+    if (!isScalar(target) || typeof target.value !== 'string') return null;
+    const parsed = parseAccessEntry(target.value);
+    if (!parsed.ok || parsed.entry.kind !== 'role' || !oldTokens.has(parsed.entry.role)) return null;
+    const value = `${parsed.entry.deny ? 'deny ' : ''}${newDisplayName}`;
+    changed = true;
+    if (isAlias(node)) return new Scalar(value);
+    target.value = value;
+    return target;
+  };
+  // The anchored list an alias names, as a rewritten copy — or null when
+  // none of its entries changes, so the alias stays. Each item is cloned
+  // before it is rewritten (the anchor's own items stay as they are) and
+  // loses any anchor of its own (YAML allows one definition of a name).
+  const rewrittenCopy = (seq: YAMLSeq): YAMLSeq | null => {
+    let hit = false;
+    const copy = new YAMLSeq(doc.schema);
+    copy.flow = seq.flow;
+    copy.items = seq.items.map((item) => {
+      const clone = isNode(item) ? item.clone() : item;
+      if (isScalar(clone)) clone.anchor = undefined;
+      const r = rewritten(clone);
+      if (r) hit = true;
+      return r ?? clone;
+    });
+    return hit ? copy : null;
+  };
+  for (const pair of doc.contents.items) {
+    const key = isScalar(pair.key) ? pair.key.value : pair.key;
+    if (typeof key !== 'string' || !VERB_KEYS.has(key)) continue;
+    const aliased = isAlias(pair.value) ? pair.value.resolve(doc) : null;
+    if (isSeq(aliased)) {
+      const copy = rewrittenCopy(aliased);
+      if (copy) pair.value = copy;
+    } else if (isSeq(pair.value)) {
+      pair.value.items = pair.value.items.map((item) => rewritten(item) ?? item);
+    } else {
+      const scalar = rewritten(pair.value);
+      if (scalar) pair.value = scalar;
+    }
+  }
+  if (!changed) return text;
+  // Never fold a long value onto a second line, nor pad a flow list.
+  const frontmatter = doc.toString({ lineWidth: 0, flowCollectionPadding: false }).replace(/\n$/, '');
+  return [...lines.slice(0, start), frontmatter, ...lines.slice(end)].join('\n');
+}
+
+/**
+ * The principal references the RESOLVER reads from one candidate file, by
+ * the resolver's own parsers: an `access.md`'s folder rules
+ * (`parseAccessFile`) and its self-rules (`accessMdSelfEntries`), any other
+ * file's own frontmatter (`parseOwnAccessEntries`). Those parsers read
+ * quoted scalars and flow sequences (`read: ["Admin"]`) the line walker
+ * above does not, so the reports built on this name every rule that is
+ * actually enforced — and nothing the resolver ignores (a broken
+ * `access.md` is dropped from the model, so it references nothing).
+ */
+export function resolverRoleRefs(text: string, repoRel: string): { role: string; verb: string }[] {
+  const out: { role: string; verb: string }[] = [];
+  const add = (entries: Record<Verb, ParsedEntry[]> | null): void => {
+    if (!entries) return;
+    for (const verb of KNOWN_VERBS) {
+      for (const e of entries[verb]) if (e.kind === 'role') out.push({ role: e.role, verb });
+    }
+  };
+  if (isAccessMdPath(repoRel)) {
+    const folder = parseAccessFile(text, repoRel);
+    if (folder.ok) add(folder.file.entries);
+    add(accessMdSelfEntries(text));
+  } else {
+    add(parseOwnAccessEntries(text));
+  }
+  return out;
+}
+
 export interface ReferenceHit {
   path: string;
   verb: string;
@@ -304,6 +432,75 @@ export interface ReferenceRewrite {
   original: string;
 }
 
+/**
+ * Which of the given repo-relative paths the person a refusal is for may
+ * read — `canReadBatch` bound to that person. A path is itself a disclosure,
+ * so a refusal names only these and says nothing of the rest.
+ */
+export type PathVisibility = (repoRelPaths: string[]) => Promise<ReadonlyMap<string, boolean>>;
+
+/**
+ * The one refusal for a rename blocked by a place the renaming person may
+ * not be shown — a folder the walk cannot list, a file it cannot read, or a
+ * file the person may not read that still names the old principal after the
+ * rewrite (a backstop: every form the resolver reads is rewritten). The same
+ * words whatever the cause: no path, no count, no hint of a reference, since
+ * Admin status does not grant read and each of those is a disclosure. The
+ * log names the place.
+ */
+export const UNSHOWN_REFERENCE_REFUSAL =
+  'This rename rewrites access rules across the knowledge base, and part of the knowledge base could not be rewritten, so it may still reference the old principal; rename aborted with no changes. The server log names where.';
+
+/**
+ * The commit's own write gate refusing a rename's rewrite, translated for the
+ * person who asked. The gate judges every file the rewrite touches against the
+ * actor's WRITE rules (a rename's references reach files private to others,
+ * which an Admin may be unable to write), and its refusal names the file. A
+ * file its person may read keeps that refusal: the path and its eligible
+ * writers say whom to ask. A file they may not read gets
+ * `UNSHOWN_REFERENCE_REFUSAL` instead, so the hidden path stays unnamed; the
+ * log names it. Anything else comes back unchanged.
+ *
+ * The one bit left (some file the person cannot see names the old principal)
+ * is the hidden-blocker exception of "A Guard's Answer Is a Disclosure": an
+ * Admin's refused rename of a principal they manage says only that an unshown
+ * place blocks it.
+ */
+export async function translateRewriteWriteRefusal(
+  err: unknown,
+  visible: PathVisibility,
+  makeError: (message: string) => Error,
+): Promise<unknown> {
+  if (!(err instanceof AccessDeniedError)) return err;
+  const p = err.access.path;
+  let shown = false;
+  try {
+    shown = (await visible([p])).get(p) === true;
+  } catch {
+    // Cannot tell whether the person may see it: say nothing of it.
+  }
+  if (shown) return err;
+  log.warn(`reference rewrite: the acting person may not write ${printable(p)}`);
+  const translated = makeError(UNSHOWN_REFERENCE_REFUSAL);
+  // withFileLocks reads the paths whose restore failed off the error it
+  // catches, to discard their partial bytes; the translation must carry them.
+  const unrestored = (err as { unrestoredPaths?: Set<string> }).unrestoredPaths;
+  if (unrestored) (translated as { unrestoredPaths?: Set<string> }).unrestoredPaths = unrestored;
+  return translated;
+}
+
+/**
+ * The rows of `refs` whose file `readable` allows. The rest are dropped
+ * outright, not counted: Admin status does not grant read, so even a count of
+ * rules in content the viewer cannot read is a disclosure.
+ */
+export function readableReferences(
+  refs: readonly ReferenceHit[],
+  readable: ReadonlyMap<string, boolean>,
+): ReferenceHit[] {
+  return refs.filter((r) => readable.get(r.path) === true);
+}
+
 /** How long a cached reference scan may serve after its load. Backstop only —
  *  reference-changing writes invalidate explicitly (the admin services after
  *  their own rewrites, and the event-bus tap below for everyone else's). */
@@ -354,6 +551,8 @@ export class KbReferenceScanner {
 
   constructor(
     private readonly workspaceService: IWorkspaceService,
+    /** The resolver's walk (see `collectCandidateFiles`), injected by the composition root. */
+    private readonly disk: ITreeWalker,
     private readonly kbDirName: string,
     eventBus?: ReferenceScanInvalidationBus,
   ) {
@@ -381,37 +580,40 @@ export class KbReferenceScanner {
    * resolver reads access verbs from — the shared
    * `ACCESS_FRONTMATTER_EXTENSIONS` set (`.md` AND `.tool`; a rename that
    * skipped `.tool` would strand a live frontmatter grant there). Sourced
-   * from the workspace file tree (which already skips `.git` and honours
-   * `.bevelignore`), filtered under the KB dir and returned bare
-   * repo-relative. (`roles.yaml` matches no scanned extension, so it's
-   * excluded; callers commit it separately.) Under save=share the working
-   * tree matches the committed set, so this is the same candidate list
-   * git-tracking would give.
+   * from the RESOLVER'S OWN walk (`walkKb`: dot-entries and vendored
+   * dependencies skipped, `.bevelignore` NOT honoured) — the resolver
+   * enforces an `access.md` the explorer hides, so a scan that honoured the
+   * ignore file would leave its rules out of the roster's reports and a
+   * rename would strand them. Paths are relative to the KB dir. (`roles.yaml`
+   * matches no scanned extension, so it's excluded; callers commit it
+   * separately.)
+   *
+   * `holes` names every folder the walk could not list: the candidate set
+   * is INCOMPLETE when it is non-empty, and each caller decides what that
+   * means — the rewrite refuses, the advisory scan says so and does not cache.
    */
-  async collectCandidateFiles(workspaceId: string): Promise<string[]> {
-    const tree = await this.workspaceService.listFiles(workspaceId);
-    const prefix = `${this.kbDirName}/`;
+  async collectCandidateFiles(workspaceId: string): Promise<{ files: string[]; holes: string[] }> {
     const out: string[] = [];
-    const visit = (node: FileTreeEntry): void => {
-      if (node.type === 'file') {
-        if (node.relativePath.startsWith(prefix) && hasAccessFrontmatterExtension(node.relativePath)) {
-          out.push(node.relativePath.slice(prefix.length));
-        }
-        return;
-      }
-      for (const child of node.children ?? []) visit(child);
-    };
-    visit(tree);
-    return out;
+    const { holes } = await this.disk.walkKb(await this.repoDir(workspaceId), [
+      {
+        onFile(dir, name) {
+          const rel = dir ? `${dir}/${name}` : name;
+          if (hasAccessFrontmatterExtension(rel)) out.push(rel);
+        },
+      },
+    ]);
+    return { files: out, holes };
   }
 
   /**
    * Sound scan of EVERY candidate file (folder `access.md` + `.md`/`.tool`
    * node frontmatter) for genuine principal references, indexed by canonical
-   * entry TOKEN. Shares the
-   * candidate set and the config-region parse with the rename rewrite, so the
-   * delete warning and the rewrite see the SAME references. A file we cannot
-   * read is skipped (this is an advisory read, not the atomic write path).
+   * entry TOKEN, read by the resolver's own parse ({@link resolverRoleRefs}).
+   * Shares the candidate set with the rename rewrite, and the rewrite checks
+   * its result against the same parse, so the delete warning and the rewrite
+   * cannot disagree on what references a principal. A file we cannot
+   * read is skipped (this is an advisory read, not the atomic write path),
+   * and the scan that skipped it is not cached.
    * Cached per workspace (see class doc); reads are batched with Promise.all
    * rather than serial per-file awaits.
    */
@@ -428,7 +630,12 @@ export class KbReferenceScanner {
     const startedUnder = flight.gen;
     try {
       const repoDir = await this.repoDir(workspaceId);
-      const candidates = await this.collectCandidateFiles(workspaceId);
+      const { files: candidates, holes } = await this.collectCandidateFiles(workspaceId);
+      if (holes.length > 0) {
+        log.warn(
+          `reference scan: cannot list ${holes.map((h) => printable(h || '.')).join(', ')} — references there are not reported`,
+        );
+      }
       const texts = await Promise.all(
         candidates.map(async (repoRel) => {
           try {
@@ -442,7 +649,7 @@ export class KbReferenceScanner {
       candidates.forEach((repoRel, i) => {
         const text = texts[i];
         if (text === null) return;
-        for (const ref of findRoleRefsInText(text, true, isAccessMdPath(repoRel))) {
+        for (const ref of resolverRoleRefs(text, repoRel)) {
           const list = byToken.get(ref.role);
           if (list) list.push({ path: repoRel, verb: ref.verb });
           else byToken.set(ref.role, [{ path: repoRel, verb: ref.verb }]);
@@ -451,7 +658,10 @@ export class KbReferenceScanner {
       // Cache only when no invalidation landed mid-scan; the caller still gets
       // this snapshot (at worst one write stale — same as the pre-scan world),
       // but a stale snapshot must never STICK for a TTL. The next call re-scans.
-      if (flight.gen === startedUnder) {
+      // An incomplete scan (a folder could not be listed, or a candidate file
+      // could not be read) is never cached either: the next call retries it.
+      const unread = texts.some((t) => t === null);
+      if (flight.gen === startedUnder && holes.length === 0 && !unread) {
         this.cache.set(workspaceId, { loadedAt: Date.now(), byToken });
       }
       return byToken;
@@ -462,22 +672,50 @@ export class KbReferenceScanner {
   }
 
   /**
-   * Find every genuine reference to `oldToken` and rewrite it to
-   * `newDisplayName`. FAIL-CLOSED: a candidate we cannot read might reference
+   * Find every genuine reference to `oldToken` (or any of several spellings
+   * of one principal) and rewrite it to `newDisplayName`. FAIL-CLOSED: a candidate we cannot read might reference
    * the old token, and skipping it would commit a partial rewrite (a
    * half-renamed principal still pointed at by stragglers = silent access
    * drop) — so any read failure aborts via `makeError` with nothing written.
    * Returns the writes WITH each file's original text (rollback snapshots).
+   *
+   * The rename keeps the KB's references to a principal whole, so it rewrites
+   * every candidate, files its person may not read included: a file private
+   * to others blocks nothing here, and no answer of this method depends on
+   * what such a file holds. Whether the person may WRITE each rewritten file
+   * is the commit's gate to decide, not this method's (see
+   * `translateRewriteWriteRefusal`). Every form the resolver reads
+   * is rewritten — block lists and `key: value` by the line walk, quoted and
+   * flow-YAML own frontmatter by the structural rewrite — so there is no
+   * "cannot rewrite" answer for hidden content to give. The writes reach a
+   * caller only through surfaces gated on read (the roster, the event
+   * delivery), never through this method's answer.
+   *
+   * A reference the resolver still sees after both rewrites is refused: named
+   * with how to fix it when `visible` says its person may read the file, with
+   * `UNSHOWN_REFERENCE_REFUSAL` otherwise (no path, no count). Nothing the
+   * resolver reads should reach that, so the refusal is a backstop, not an
+   * answer the content of a hidden file can choose.
    */
   async rewriteReferences(
     workspaceId: string,
-    oldToken: string,
+    oldToken: string | readonly string[],
     newDisplayName: string,
     makeError: (message: string, cause?: string) => Error,
+    visible: PathVisibility,
   ): Promise<ReferenceRewrite[]> {
+    const oldTokens = typeof oldToken === 'string' ? [oldToken] : oldToken;
     const repoDir = await this.repoDir(workspaceId);
     const writes: ReferenceRewrite[] = [];
-    const candidates = await this.collectCandidateFiles(workspaceId);
+    const { files: candidates, holes } = await this.collectCandidateFiles(workspaceId);
+    // A folder we cannot list might hold references to the old token — same
+    // fail-closed rule as an unreadable file below, and never named nor
+    // counted, for the same reason: its own access.md may be just as
+    // unreadable, so `visible` could not see the rules that close it.
+    if (holes.length > 0) {
+      log.warn(`reference rewrite: cannot list ${holes.map((h) => printable(h || '.')).join(', ')}`);
+      throw makeError(UNSHOWN_REFERENCE_REFUSAL);
+    }
     const texts = await Promise.all(
       candidates.map(async (repoRel) => {
         try {
@@ -489,20 +727,55 @@ export class KbReferenceScanner {
     );
     for (const t of texts) {
       if (!t.ok) {
-        throw makeError(
-          `Cannot read ${t.repoRel} while rewriting references; rename aborted with no changes`,
-          t.cause,
-        );
+        // Never named, not even to a reader: `visible` decides from the
+        // file's own rules, and a file we cannot read has none it can see —
+        // an inherited grant would then disclose a path its own rules may
+        // close. The fs cause carries the path too, so it stays in the log.
+        log.warn(`reference rewrite: cannot read ${printable(t.repoRel)}`, { cause: t.cause });
+        throw makeError(UNSHOWN_REFERENCE_REFUSAL);
       }
     }
+    // Old tokens the rename must leave no reference to (the new name's own
+    // token is exempt: it IS the rewrite's result).
+    const newToken = canonicalRoleName(newDisplayName);
+    const gone = new Set(oldTokens.filter((t) => t !== newToken));
+    const stranded: string[] = [];
     candidates.forEach((repoRel, i) => {
       const entry = texts[i];
       if (!entry.ok) return; // unreachable — the loop above threw
-      const rewritten = rewriteRoleTokensInText(entry.text, oldToken, newDisplayName, true, isAccessMdPath(repoRel));
+      let rewritten = entry.text;
+      for (const token of oldTokens) {
+        rewritten = rewriteRoleTokensInText(rewritten, token, newDisplayName, true, isAccessMdPath(repoRel));
+      }
+      // The line rewrite edits block-list and `key: value` entries; the
+      // resolver also reads quoted and flow-YAML own frontmatter, which the
+      // structural rewrite edits by the full parser's own tree.
+      const stillNamed = (t: string) => resolverRoleRefs(t, repoRel).some((r) => gone.has(r.role));
+      if (stillNamed(rewritten)) {
+        rewritten = rewriteOwnFrontmatterStructurally(rewritten, new Set(oldTokens), newDisplayName);
+      }
+      // A reference the resolver still sees would be stranded by the rename.
+      if (stillNamed(rewritten)) {
+        stranded.push(repoRel);
+        return;
+      }
       if (rewritten !== entry.text) {
         writes.push({ repoRelativePath: repoRel, content: rewritten, original: entry.text });
       }
     });
+    if (stranded.length > 0) {
+      const verdicts = await visible(stranded);
+      const shown = stranded.filter((p) => verdicts.get(p) === true);
+      if (shown.length < stranded.length) {
+        log.warn(
+          `reference rewrite: cannot rewrite ${stranded.map((p) => printable(p || '.')).join(', ')}`,
+        );
+        throw makeError(UNSHOWN_REFERENCE_REFUSAL);
+      }
+      throw makeError(
+        `${shown.map((p) => sanitizedPath(p || '.')).join(', ')} name the old principal in a form the rename cannot rewrite; rewrite it as a \`- Name\` list item, then rename again. Rename aborted with no changes`,
+      );
+    }
     return writes;
   }