@bevel-software/platform-shared 0.15.1 → 0.19.0

package/src/workflow/interface.ts

@@ -18,6 +18,7 @@
  */
 
 import type { AuthUser } from '../auth/types.js';
+import type { ChangeRequestApplyFailureKind } from '../git/pr.types.js';
 import type {
   AcquireLockResult,
   Branch,
@@ -33,6 +34,9 @@ import type {
   ChangedFile,
   FileApproval,
   FileLock,
+  FolderChangeRequest,
+  FolderChangeRequestRemoval,
+  MergeBranchOutcome,
   MergeChangeRequestOutcome,
   OpenChangeRequestInput,
   PostChangeRequestCommentInput,
@@ -222,9 +226,38 @@ export interface IWorkflowService {
     path: string,
     sha: string,
   ): Promise<{ baseline: string | null; current: string | null }>;
+  /**
+   * One file as it stood at a change request's fork point (`sha`, which must
+   * lie on the target branch's history) — the "before" side of the request
+   * dialog's diff. `null` when the path did not exist there. Access is the
+   * caller's to check.
+   */
+  fileAtForkPoint(
+    workspaceId: string,
+    baseBranch: string,
+    sha: string,
+    path: string,
+  ): Promise<string | null>;
+  /**
+   * A change request's current fork point: the merge base of the freshly
+   * fetched target and source branches, or `null` when they share no history.
+   */
+  changeRequestForkPoint(
+    workspaceId: string,
+    baseBranch: string,
+    headBranch: string,
+  ): Promise<string | null>;
 
   // ── File locks (new — currently NotImplementedWorkflowError) ──────────────
 
+  // Every lock method below coordinates on ONE canonical identity per file:
+  // `x/a.md`, `./x/a.md` and `x//a.md` name the same lock, so a lock acquired
+  // under any of them is contended, heartbeated, checkpointed, released and
+  // read under any other. A path that escapes the workspace, or that only
+  // becomes relative by being laundered, is refused with the same status the
+  // file verbs answer for that input: 400 for an unusable path, 403 for one
+  // that resolves outside the workspace.
+
   /**
    * Try to acquire an edit lock on `(branch, path)` for the caller. Returns
    * `{ acquired: true, lock }` on success; `{ acquired: false, lock }` if
@@ -246,13 +279,37 @@ export interface IWorkflowService {
    * `releaseLockUntouched`) — `releaseLock` rejects rather than ever enqueue
    * a commit for a hold that was never allowed to write. Internal callers
    * only; never plumbed from a route.
+   *
+   * Every non-coordination acquire also passes the READ-BEFORE-WRITE gate, on
+   * every branch: the caller must be able to read the path (for a new path,
+   * where it lands), or the path must start a new folder directly under one
+   * of the three roots (knowledge, skills, plugins). Nothing is created,
+   * changed or removed where its author cannot see it, whatever write rules
+   * say; a refusal is an `AccessDeniedError` whose `access.unreadable` names
+   * the place. A write that passed only as a platform-file restore is not
+   * asked — that rescue exists for a destination whose rules deny the admin
+   * making it.
+   *
+   * `opts.platformRestore` CLAIMS that this acquire is the destination side of
+   * an admin putting a misplaced platform file back (`access.md`, `roles.yaml`,
+   * `.bevelignore`, the agent guide), and names the move's `source` — the path the
+   * file is coming FROM, in the same spelling as `path`.
+   *
+   * It is a claim, not an authorisation. The implementation re-asks both
+   * halves of it: that source→path is a restore at all (a misplaced copy
+   * going back under its own name, never the root's own copy coming out —
+   * `isPlatformRestoreShape`), and that the access module
+   * (`canRestorePlatformFile`) lets this caller land this exact path. Only
+   * both yeses let the acquire past the write gate, so a caller that omits or
+   * fakes the source gains nothing: the gate never takes the route's word for
+   * which move this is.
    */
   acquireLock(
     workspaceId: string,
     branch: string,
     path: string,
     user: AuthUser,
-    opts?: { coordination?: boolean },
+    opts?: { coordination?: boolean; platformRestore?: { source: string } },
   ): Promise<AcquireLockResult>;
   /** Heartbeat to keep an acquired lock alive past its current TTL. */
   heartbeatLock(workspaceId: string, branch: string, path: string, user: AuthUser): Promise<FileLock>;
@@ -394,9 +451,12 @@ export interface IWorkflowService {
   ): Promise<ChangeRequestDetail>;
 
   /**
-   * Re-run `targetBranch → sourceBranch` merge on an existing change request.
-   * Used when the target has advanced since the change request was opened.
-   * Throws `NotImplementedWorkflowError` until the backing merge path lands.
+   * Re-run `targetBranch → sourceBranch` merge on an existing change request
+   * and push it — the request dialog's Update, offered when the target has
+   * advanced since the request was opened. Only the request's author or
+   * someone who may apply it (`viewerCanUpdate`) may run it (403 otherwise).
+   * A conflicting merge is aborted, leaving the branch exactly as it was, and
+   * surfaces as `ChangeRequestConflictsError` (409).
    */
   updateFromTarget(workspaceId: string, user: AuthUser, number: number): Promise<ChangeRequestDetail>;
 
@@ -454,6 +514,22 @@ export interface IWorkflowService {
    */
   closeEmptyChangeRequest(number: number, user: AuthUser): Promise<boolean>;
 
+  /**
+   * The open change requests proposing files under a KB-repo-relative
+   * folder, each with whether the caller may take those files out of it
+   * (their own request, they are an admin, or they may write every file it
+   * proposes under the folder).
+   */
+  changeRequestsUnderFolder(folder: string, user: AuthUser): Promise<FolderChangeRequest[]>;
+
+  /**
+   * Take every file under the folder out of every open change request
+   * proposing one; a request left empty is withdrawn. All or nothing: refused
+   * (403), with nothing touched, when the caller may not act on even one of
+   * them.
+   */
+  removeFolderFromChangeRequests(folder: string, user: AuthUser): Promise<FolderChangeRequestRemoval[]>;
+
   /**
    * Close every open change request either of whose branches no longer exists
    * — source or target, since a proposal needs both ends. Such a request
@@ -510,4 +586,51 @@ export interface IWorkflowService {
     workspaceId: string,
     opts?: { bypass?: boolean },
   ): Promise<MergeChangeRequestOutcome>;
+
+  /** Start an apply attempt on a request; the token scopes `recordApplyFailure`. */
+  beginApplyAttempt(number: number): number;
+
+  /** End an attempt `beginApplyAttempt` started, whatever its outcome. */
+  endApplyAttempt(number: number, attempt: number): void;
+
+  /**
+   * Persist why an apply did not land on the (still open) request, and
+   * announce `change-request-apply-failed` to every session so the author and
+   * other viewers re-read it — not only the user who clicked. Resolves false,
+   * recording and announcing nothing, when `attempt` is no longer the latest
+   * or the request is no longer open.
+   */
+  recordApplyFailure(
+    number: number,
+    failure: { reason: string; kind: ChangeRequestApplyFailureKind; at?: Date },
+    user: AuthUser,
+    attempt: number,
+  ): Promise<boolean>;
+
+  /**
+   * Merge `sourceBranch` into `targetBranch` directly, authored as `user`,
+   * and publish the target. The agent path for merging branches — it never
+   * lands a change request:
+   *
+   *   - refused (`OpenChangeRequestBlocksMergeError`, naming the request) when
+   *     a change request from `sourceBranch` into `targetBranch` is open; a
+   *     person merges that one in the app. The reverse direction — the target
+   *     into the source, the sync that keeps a draft current — is allowed.
+   *   - refused (`WorkflowDomainError`, `kind: 'protected-merge-target'`,
+   *     status 403, listing the denied paths) when `targetBranch` is protected
+   *     and `user` could not commit every file the merge changes directly to
+   *     it. Decided against the target commit the merge is built on, not a
+   *     workspace `HEAD` that may be behind it.
+   *   - refused (`WorkflowDomainError`, `kind: 'protected-merge-changes-roles'`,
+   *     status 403) when `targetBranch` is protected and the merge would
+   *     change its `roles.yaml` — whoever the caller is. Roles never change
+   *     through a merge; a change request's merge restores the target's copy
+   *     first, and this path refuses instead. Roles are changed in the app.
+   *   - refused (`WorkflowDomainError`, `kind: 'merge-target-busy'`, status
+   *     409) when `targetBranch`'s workspace still holds unshared edits: the
+   *     merge resets it to the published tip, which would discard them.
+   *
+   * Conflicts write nothing and come back as `conflicts-need-resolution`.
+   */
+  mergeBranch(user: AuthUser, sourceBranch: string, targetBranch: string): Promise<MergeBranchOutcome>;
 }

package/src/workflow/types.ts

@@ -133,6 +133,40 @@ export type CancelChangeRequestResult = CancelPrResult;
 export type ChangeRequestComment = PrReviewComment;
 export type PostChangeRequestCommentInput = PostPrCommentInput;
 
+/**
+ * One open change request proposing files under a folder, as a folder delete
+ * lists it. `mayRemove`: the caller may take those files out of it (their own,
+ * they are an admin, or they may write every file it proposes under the
+ * folder); a refusal always says why.
+ */
+export type FolderChangeRequest = {
+  number: number;
+  title: string;
+  authorName: string | null;
+  /** The caller authored it. */
+  mine: boolean;
+  /** KB-repo-relative paths it proposes under the folder. */
+  paths: string[];
+} & ({ mayRemove: true } | { mayRemove: false; reason: string });
+
+/** What removing a folder's files did to one change request. */
+export interface FolderChangeRequestRemoval {
+  number: number;
+  removedPaths: string[];
+  /** The request proposed nothing else, so it was withdrawn. */
+  withdrawn: boolean;
+  /**
+   * Files under the folder it still proposes: added while the removal ran,
+   * so never judged, and left alone.
+   */
+  stillProposed: string[];
+  /**
+   * It proposes nothing now but was kept open, because a save to its branch
+   * was still landing — withdrawing would have deleted that save.
+   */
+  keptForSaves: boolean;
+}
+
 /**
  * Input for opening a new change request. The workflow auto-merges
  * `targetBranch` into `sourceBranch` as part of opening, so callers don't
@@ -164,6 +198,15 @@ export type MergeChangeRequestOutcome =
   | { kind: 'merged'; result: MergeChangeRequestResult }
   | { kind: 'conflicts-need-resolution'; conflictedPaths: string[] };
 
+/**
+ * What a direct branch-to-branch merge (`mergeBranch`) did: landed as `sha`
+ * on the target (the target's own tip when it already contained the source),
+ * or stopped on conflicts, nothing written.
+ */
+export type MergeBranchOutcome =
+  | { kind: 'merged'; sha: string }
+  | { kind: 'conflicts-need-resolution'; conflictedPaths: string[] };
+
 /**
  * What a remote sync did to one branch's clone. One entry per branch in the
  * `POST /api/sync` response, so a pipeline can read exactly which branch

package/src/workspace/access-verbs.ts

@@ -0,0 +1,124 @@
+/**
+ * The access verbs and the ONE dependency graph between them.
+ *
+ * Shared so that everything that folds verbs — the resolver in core-backend,
+ * the eligible lists it serves, and the share dialog in core-frontend that
+ * renders and edits them — reads the same table. A second fold written out by
+ * hand somewhere else is how the sheet comes to show "Owner" for someone the
+ * resolver refuses, or writes a `read:` line under an `owner:` it just granted.
+ *
+ * `read` controls who may VIEW a path. It is default-deny: a path with no
+ * effective grant of any verb is not readable. `write` is editing (and, with
+ * it, approval rights), `download` is saving a copy, `owner` is the contact
+ * point for the node and the right to manage its access.
+ */
+
+/**
+ * Verbs an `access.md` frontmatter can grant, each a list of principals
+ * optionally prefixed with `deny `. `AccessFile.entries` in the backend is
+ * statically keyed on this union; keep `Verb` and `KNOWN_VERBS` in lockstep.
+ */
+export const KNOWN_VERBS = ['read', 'write', 'download', 'owner'] as const;
+export type Verb = (typeof KNOWN_VERBS)[number];
+
+/**
+ * THE DEPENDENCY GRAPH — what holding each verb presupposes, declared once.
+ * `owner` presupposes `write` and `download`; `write` and `download` each
+ * presuppose `read`; `read` presupposes nothing. Everything about how verbs
+ * fold into one another is DERIVED from this table, in both directions:
+ *
+ *   - a GRANT confers, downwards, every verb the granted one presupposes
+ *     (`sourceVerbsFor`, `effectiveVerbs`): an owner may edit, save and open;
+ *     an editor may open; someone trusted with a copy may open it;
+ *   - a DENIAL strips, upwards, every verb that presupposes the denied one
+ *     (`requiredVerbsFor`): nobody owns what they may not edit, and nobody
+ *     edits or saves what they may not open.
+ *
+ * Neither converse is implied: a `deny write` says nothing about `read`, and a
+ * `read` grant confers no `write`. `write` and `download` are independent of
+ * each other. Add a verb, or change what one presupposes, HERE and nowhere
+ * else; every list and fold below follows.
+ */
+export const VERB_REQUIRES: Readonly<Record<Verb, readonly Verb[]>> = {
+  read: [],
+  write: ['read'],
+  download: ['read'],
+  owner: ['write', 'download'],
+};
+
+/** `verb` and everything it presupposes, transitively. */
+function presupposedBy(verb: Verb): ReadonlySet<Verb> {
+  const out = new Set<Verb>();
+  const visit = (v: Verb) => {
+    if (out.has(v)) return;
+    out.add(v);
+    for (const dep of VERB_REQUIRES[v]) visit(dep);
+  };
+  visit(verb);
+  return out;
+}
+
+/**
+ * Verbs whose GRANT confers `verb`, target verb first: `verb` itself, then
+ * every verb that presupposes it, in `KNOWN_VERBS` order.
+ */
+export function sourceVerbsFor(verb: Verb): Verb[] {
+  return [verb, ...KNOWN_VERBS.filter((v) => v !== verb && presupposedBy(v).has(verb))];
+}
+
+/**
+ * Verbs whose DENIAL strips `verb`, target verb first: `verb` itself, then
+ * every verb it presupposes, in `KNOWN_VERBS` order.
+ */
+export function requiredVerbsFor(verb: Verb): Verb[] {
+  const needs = presupposedBy(verb);
+  return [verb, ...KNOWN_VERBS.filter((v) => v !== verb && needs.has(v))];
+}
+
+/**
+ * The verbs in the order a change to a principal's set has to be APPLIED:
+ * broadest first, so every verb comes before the verbs it presupposes (ties in
+ * `KNOWN_VERBS` order). Lowering must start at the top — denying `write` while
+ * an `owner:` grant still stands in the same file is refused as ineffective,
+ * since owner confers write; stripping owner first removes what was conferring
+ * it. Raising reads the same order for the opposite reason: granting `owner`
+ * first satisfies the rest in one line.
+ */
+export const VERBS_BROADEST_FIRST: readonly Verb[] = [...KNOWN_VERBS].sort(
+  (a, b) =>
+    presupposedBy(b).size - presupposedBy(a).size || KNOWN_VERBS.indexOf(a) - KNOWN_VERBS.indexOf(b),
+);
+
+/** One flag per verb: what a principal holds, or what a form has ticked. */
+export type VerbSet = Record<Verb, boolean>;
+/** A partial set — flags left out read as not held. */
+export type VerbFlags = Partial<Record<Verb, boolean>>;
+
+/**
+ * The grant fold, as a whole set: what a principal EFFECTIVELY holds given the
+ * verbs they are granted. Each verb is held when it, or any verb that
+ * presupposes it, is in `held`. Idempotent on an already-folded set.
+ */
+export function effectiveVerbs(held: VerbFlags): VerbSet {
+  const out = {} as VerbSet;
+  for (const verb of KNOWN_VERBS) out[verb] = sourceVerbsFor(verb).some((w) => held[w] === true);
+  return out;
+}
+
+/**
+ * True when some OTHER verb in `held` confers `verb` — it is implied, not
+ * chosen, which is what a form renders as checked-and-disabled.
+ */
+export function conferredByOthers(held: VerbFlags, verb: Verb): boolean {
+  return sourceVerbsFor(verb).some((w) => w !== verb && held[w] === true);
+}
+
+/**
+ * The fewest grant lines that produce `held`: every held verb that no other
+ * held verb confers, broadest first. `{ owner }` is one line; `{ write, read,
+ * download }` is `write` and `download` (read rides on either); `{ read,
+ * download }` is `download` alone. A flag left out is not granted.
+ */
+export function minimalGrantVerbs(held: VerbFlags): Verb[] {
+  return VERBS_BROADEST_FIRST.filter((verb) => held[verb] === true && !conferredByOthers(held, verb));
+}

package/src/workspace/agent-preamble.ts

@@ -0,0 +1,47 @@
+/**
+ * The rules about the deployment preamble's TEXT that both sides need to
+ * agree on: the file it lives in, the caps it is cut at, and what counts as a
+ * private comment inside it.
+ *
+ * These lived in the backend composer and were mirrored by hand in the
+ * frontend editor, whose own comment said so. The two are not free to differ:
+ * the editor decides what an admin is shown and what it writes back, the
+ * composer decides what agents receive, and a drift between them shows the
+ * admin one description while agents get another.
+ *
+ * Pure: no IO, no clock, no platform assumptions.
+ */
+
+/** The repository-root file an admin edits. */
+export const PREAMBLE_FILE = 'mcp-description.md';
+
+/** UTF-16 units of preamble sent on the handshake before the marker replaces the rest. */
+export const PREAMBLE_CAP = 6_000;
+
+/** UTF-16 units of the whole tool prefix (fixed line included). */
+export const TOOL_PREFIX_CAP = 300;
+
+/**
+ * Remove every `<!-- … -->` block.
+ *
+ * A `<!--` that is never closed takes the rest of the text with it and is
+ * reported, so a caller can warn: that is the fail-closed half of the rule,
+ * and it is why an admin's private note cannot leak through the likeliest
+ * editing slip. The editor strips the same blocks to decide what to show, and
+ * closes an unterminated one when it writes back.
+ */
+export function stripHtmlComments(text: string): { text: string; unterminated: boolean } {
+  let out = '';
+  let from = 0;
+  for (;;) {
+    const open = text.indexOf('<!--', from);
+    if (open === -1) {
+      out += text.slice(from);
+      return { text: out, unterminated: false };
+    }
+    out += text.slice(from, open);
+    const close = text.indexOf('-->', open + 4);
+    if (close === -1) return { text: out, unterminated: true };
+    from = close + 3;
+  }
+}

package/src/workspace/entry-exists.ts

@@ -0,0 +1,36 @@
+/**
+ * THE sentence a rename, a move or a copy answers with when something is
+ * already at the destination.
+ *
+ * A rename is not a way to replace content: renaming a `.docx` onto an
+ * existing `.md` used to hand the markdown file the Word bytes and break the
+ * page. Every surface — the sidebar rename box, a drag onto a folder, the
+ * agent's `move_file` and `copy_file` — refuses with this one sentence, so a
+ * user who meets it in the sidebar and an agent that meets it in a tool
+ * result are told the same thing.
+ *
+ * Kept here, beside `filename.ts`, for the same reason that file is: the
+ * backend throws it and the frontend renders it, and neither should spell it
+ * its own way.
+ */
+
+/** What is already sitting at the destination. */
+export type ExistingEntryKind = 'file' | 'folder';
+
+/**
+ * `A file named <name> already exists in <folder>.` — `name` and `folder` are
+ * read off `destinationPath`, which may be workspace-relative or
+ * repo-relative; only its last two segments are used, so the reader sees the
+ * name they typed and the folder they were aiming at rather than a full path.
+ * A destination directly at the top of the tree has no folder segment to
+ * name, and says `the top level` instead.
+ */
+export function entryExistsMessage(kind: ExistingEntryKind, destinationPath: string): string {
+  const segments = destinationPath
+    .replace(/\\/g, '/')
+    .split('/')
+    .filter((segment) => segment.length > 0 && segment !== '.');
+  const name = segments[segments.length - 1] ?? destinationPath;
+  const folder = segments.length > 1 ? segments[segments.length - 2] : 'the top level';
+  return `A ${kind} named ${name} already exists in ${folder}.`;
+}

package/src/workspace/filename.ts

@@ -96,6 +96,37 @@ export function validateRelativePath(relativePath: string): string | null {
   return null;
 }
 
+/**
+ * ONE identity per file, so everything that coordinates on a path agrees about
+ * what it is coordinating on: an in-process queue, a database lock row, and
+ * the bytes on disk. {@link validateRelativePath} accepts a leading `./` and
+ * repeated slashes as spellings of the same path, and two callers spelling one
+ * file differently would otherwise take two different locks and write over
+ * each other. `.` and `..` segments are refused outright by the validator, so
+ * there is nothing to resolve here beyond the separators.
+ *
+ * Case is deliberately left alone. The deployment target is Linux, where
+ * `Foo.md` and `foo.md` are two different files; folding case to suit a
+ * case-insensitive development machine would merge two real files in
+ * production, which is a worse failure than the race it would close.
+ */
+export function canonicalRelativePath(relativePath: string): string {
+  // Never LAUNDER a path. Dropping empty segments would turn the absolute
+  // `/etc/passwd` into the perfectly ordinary `etc/passwd`, and an absolute
+  // path is exactly what `path.resolve` lets win over the workspace directory
+  // — which is why the workspace-boundary check refuses it today. A path this
+  // cannot canonicalise is returned UNCHANGED, so every gate downstream sees
+  // what the caller actually sent and goes on refusing it.
+  if (relativePath.startsWith('/') || validateRelativePath(relativePath) !== null) {
+    return relativePath;
+  }
+  return relativePath
+    .replace(/^\.\//, '')
+    .split('/')
+    .filter((segment) => segment.length > 0)
+    .join('/');
+}
+
 /**
  * Throwing wrapper for the backend service layer — keeps call sites a single
  * line and produces a clear `Error` the route handler can surface as a 400.

package/src/workspace/frontmatter-carriers.ts

@@ -0,0 +1,57 @@
+/**
+ * Which files can carry their OWN frontmatter — and therefore their own
+ * per-file access rules.
+ *
+ * A file-level grant, revoke or restriction splices a `---` YAML block into
+ * the file itself. That is right for a Markdown note and destructive for
+ * anything else: spliced into a PDF, a presentation or an image it corrupts
+ * the bytes (the preview goes blank), and the grant never even resolves.
+ * Such a file takes its folder's rules instead.
+ *
+ * THE ONE predicate for that question: the access routes refuse a file-level
+ * mutation on a file it rejects, and the Manage access dialog shows the folder
+ * pointer for the same files.
+ *
+ * The carriers are exactly the files the access resolver reads its own
+ * frontmatter from — the backend's core access-frontmatter extension set:
+ * Markdown notes (`.md`) and `.tool` definitions (whole-document YAML whose
+ * access verbs sit beside the definition). Both are served by the file-reader
+ * registry's text-editable text reader. The registry test pins both facts, so
+ * this list cannot drift from the resolver or the registry silently. (Neither
+ * can live here: the registry's document readers carry backend-only extraction
+ * dependencies, and overlays register further extensions at boot — the backend
+ * passes its full registered set as `extensions`.)
+ *
+ * Matching is case-SENSITIVE, as the resolver's is: `Note.MD` carries no
+ * enforced rule, so a grant written there would never resolve. An extensionless
+ * file is NOT a carrier either: its content may be anything, and a path alone
+ * cannot tell a note from a binary.
+ */
+export const FRONTMATTER_CARRIER_EXTENSIONS: readonly string[] = ['.md', '.tool'];
+
+/**
+ * True when the file at `path` can carry its own frontmatter (and so its own
+ * access rules). `extensions` defaults to the core set; the backend passes the
+ * resolver's registered set so an overlay's kinds count too.
+ */
+export function canCarryFrontmatter(
+  path: string,
+  extensions: readonly string[] = FRONTMATTER_CARRIER_EXTENSIONS,
+): boolean {
+  const name = path.slice(path.lastIndexOf('/') + 1);
+  // The resolver's own rule is a plain suffix match, so a file named exactly
+  // `.md` is read for its frontmatter there — and must be a carrier here too,
+  // or a rule the resolver honours could not be managed.
+  return extensions.some((ext) => name.endsWith(ext));
+}
+
+/** The `kind` a refused file-level access mutation answers with. */
+export const FOLDER_GOVERNS_ACCESS_KIND = 'folder-governs-access';
+
+/**
+ * The one sentence both the 422 and the dialog say, naming the folder whose
+ * rules govern the file.
+ */
+export function folderGovernsAccessMessage(folder: string): string {
+  return `This file's access comes from its folder. Manage access on ${folder} instead.`;
+}

package/src/workspace/frontmatter.ts

@@ -1,14 +1,60 @@
+/**
+ * THE fence rule: a line is a frontmatter fence when, whitespace aside, it is
+ * exactly `---`. Forgiving on purpose — an opening fence with a trailing space
+ * or an indented fence is still a fence.
+ *
+ * Every reader in the platform asks this one function. The access model's
+ * line scan always judged fences this way while the splitter below demanded
+ * `---` at column 0, so a file written with a near-miss fence had access
+ * rules that applied while the catalog, the tool manuals and the frontmatter
+ * panel saw no frontmatter at all. One rule, asked everywhere, is what keeps
+ * a file from meaning two things.
+ */
+export function isFrontmatterFence(line: string | undefined): boolean {
+  return line?.trim() === '---';
+}
+
 /**
  * The ONE `---` frontmatter splitter, shared by backend and frontend so no file
- * type grows its own regex. Splits a leading `---`-fenced YAML block from the
- * body; null when the text doesn't open with a fence. Parsing the YAML inside is
- * the caller's concern (the access-control resolver deliberately keeps its own
- * hardened line-based reader — see `modules/access/access-splice.ts`).
+ * type grows its own reader. Splits a leading fenced YAML block from the body;
+ * null when the first line is not a fence or no later line closes it. Fences
+ * are judged by {@link isFrontmatterFence}. Parsing the YAML inside is the
+ * caller's concern (the access model keeps its own line scan, on the same
+ * fence rule, because a splice must put bytes back exactly as it found them).
+ *
+ * `frontmatter` is the raw text between the fence lines and `body` the raw
+ * text after the closing fence's line break, both byte for byte — line
+ * endings included — so a caller that rebuilds the file changes nothing it
+ * did not mean to.
  */
 export function extractFrontmatter(text: string): { frontmatter: string; body: string } | null {
-  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
-  if (!m) return null;
-  return { frontmatter: m[1], body: m[2] };
+  // Walk the lines by offset rather than splitting, so both halves can be
+  // sliced out of the original text with their own line endings intact.
+  let start = 0;
+  let lineIndex = 0;
+  let openEnd = -1; // offset just past the opening fence's line break
+  while (start <= text.length) {
+    const nl = text.indexOf('\n', start);
+    const end = nl === -1 ? text.length : nl;
+    const line = text.slice(start, end).replace(/\r$/, '');
+    const next = nl === -1 ? text.length + 1 : nl + 1;
+    if (lineIndex === 0) {
+      // A lone `---` with nothing after it opens nothing.
+      if (!isFrontmatterFence(line) || nl === -1) return null;
+      openEnd = next;
+    } else if (isFrontmatterFence(line)) {
+      // The frontmatter ends before the line break that precedes this fence.
+      const fmEnd = start - (start >= 2 && text[start - 2] === '\r' ? 2 : 1);
+      return {
+        frontmatter: fmEnd > openEnd ? text.slice(openEnd, fmEnd) : '',
+        body: next > text.length ? '' : text.slice(next),
+      };
+    }
+    if (nl === -1) return null; // never closed
+    start = next;
+    lineIndex += 1;
+  }
+  return null;
 }
 
 /**
@@ -37,7 +83,10 @@ export function setFrontmatterField(text: string, key: string, value: string): s
     // No frontmatter — prepend a fresh block, keeping the original body intact.
     return `---${eol}${line}${eol}---${eol}${text}`;
   }
-  const fmLines = fm.frontmatter.split(/\r?\n/);
+  // An empty block has no lines, not one empty line: splitting '' would give
+  // [''], and the inserted key would be followed by a blank line before the
+  // closing fence.
+  const fmLines = fm.frontmatter === '' ? [] : fm.frontmatter.split(/\r?\n/);
   const idx = fmLines.findIndex((l) => keyRe.test(l));
   if (idx >= 0) fmLines[idx] = line;
   else fmLines.unshift(line);