@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/modules/access-model/access-grammar.ts

@@ -12,6 +12,17 @@
  */
 
 import { parse as parseFullYaml } from 'yaml';
+import {
+  KNOWN_VERBS,
+  VERB_REQUIRES,
+  VERBS_BROADEST_FIRST,
+  pluginManifestName,
+  requiredVerbsFor,
+  sourceVerbsFor,
+  type Verb,
+} from '@bevel-software/platform-shared';
+import { canonicalEmail } from '../../shared/email-identity.js';
+import { scanFrontmatter } from './frontmatter-lines.js';
 import type { GroupsIndex } from './group-files.js';
 
 // ---------------------------------------------------------------------------
@@ -27,44 +38,47 @@ export const ADMIN_CANONICAL = 'admin';
  *
  * `read` controls who may VIEW a path (the file viewer, embed surface, and
  * the agent's read tools). It is **default-deny**: a path with no effective
- * `read:` or `owner:` grant is not readable. To make content public, list the
- * built-in role `everyone` under `read:`.
+ * `read:`, `write:`, `download:` or `owner:` grant is not readable. To make
+ * content public, list the built-in role `everyone` under `read:`.
  *
  * The verbs nest: `owner` is a superset of `read` + `write` + `download`, and
- * `write` is itself a superset of `read` (anyone who can edit can view). An
- * `owner` grant therefore confers all three lower verbs, a `write` grant
- * additionally confers `read`, and `owner` also marks the principal as a
- * contact point for the node (surfaced in the UI so users know who to ask).
- * See `sourceVerbsFor` for how these implications fold into resolution.
+ * `write` and `download` are each a superset of `read` (anyone who can edit, or
+ * who may save a copy, can view). An `owner` grant therefore confers all three
+ * lower verbs, and a `write` or `download` grant additionally confers `read`;
+ * `owner` also marks the principal as a contact point for the node (surfaced in
+ * the UI so users know who to ask). `write` and `download` stay independent of
+ * each other — neither confers the other. Denials run the other way: a verb
+ * denied at a scope takes every verb that presupposes it down with it there.
+ *
+ * The verbs, the dependency graph between them (`VERB_REQUIRES`) and the two
+ * lists derived from it (`sourceVerbsFor`, `requiredVerbsFor`) live in
+ * `@bevel-software/platform-shared` (`workspace/access-verbs.ts`), because the
+ * share dialog folds the same verbs on the client and must never do it by a
+ * second table. They are re-exported here so the grammar remains the one
+ * import for everything on the server side.
  */
-export const KNOWN_VERBS = ['read', 'write', 'download', 'owner'] as const;
-export type Verb = (typeof KNOWN_VERBS)[number];
+export { KNOWN_VERBS, VERB_REQUIRES, VERBS_BROADEST_FIRST, requiredVerbsFor, sourceVerbsFor };
+export type { Verb };
 const KNOWN_VERBS_SET: ReadonlySet<string> = new Set<string>(KNOWN_VERBS);
 export const EVERYONE_CANONICAL = 'everyone';
 /** Display name for the built-in `everyone` role in the share UI. */
 export const EVERYONE_DISPLAY = 'Everyone';
 
-/**
- * Verbs whose entries contribute to resolving `verb`, target verb first.
- * `owner` implies `read`, `write`, and `download`; `write` additionally
- * implies `read`. So resolving `read` folds in `write` and `owner`, resolving
- * `write`/`download` folds in `owner`, and resolving `owner` uses only `owner`.
+/*
+ * How the graph is applied on the server (the table itself is in shared):
+ *
+ *   - `resolveScopes` reads `sourceVerbsFor` for the grants that confer the
+ *     target verb and `requiredVerbsFor` for the denials that strip it. Within
+ *     ONE scope a grant of the verb, or of one that confers it, beats a denial
+ *     of the verb or of one it presupposes.
+ *   - `plugin-principals.ts` reads `sourceVerbsFor` to decide who lands in
+ *     `plugin/<slug>/read`; `personal-spaces.step.ts` reads it to ask whether
+ *     a space is already open.
  *
- * The implication is **grant-only** (see `resolveAtPath`): a superset grant
- * confers the lower verb, but a superset *denial* does not — `deny write` says
- * nothing about `read`, so it never strips a separate read grant. The target
- * verb itself contributes both its grants and its denials.
+ * `download` presupposes `read` because the pair is otherwise a DEAD
+ * combination: the raw-file route read-gates before it download-gates, so a
+ * download-only grant let its holder neither open the file nor save it.
  */
-export function sourceVerbsFor(verb: Verb): Verb[] {
-  switch (verb) {
-    case 'owner':
-      return ['owner'];
-    case 'read':
-      return ['read', 'write', 'owner'];
-    default:
-      return [verb, 'owner'];
-  }
-}
 export const RESERVED_ROLE_NAMES = new Set(['deny', EVERYONE_CANONICAL]);
 export const DENY_PREFIX = 'deny ';
 /**
@@ -86,6 +100,73 @@ export const GROUP_REF_PREFIX = 'group:';
  */
 export const ROLE_TOKEN_PREFIX = 'role/';
 
+/**
+ * PLUGIN-principal token prefix in access.md entries: `plugin/<Name>/<verb>`
+ * names everyone who holds `<verb>` on the plugin folder `Plugins/<Name>` —
+ * `plugin/GTM/read` is the GTM plugin's members, `plugin/GTM/write` its
+ * managers. Membership is DERIVED at model-load time from the plugin's own
+ * `access.md` (see `plugin-principals.ts`), so a grant naming one follows the
+ * plugin's roster with no copying. This is how a shared skill under `Skills/`
+ * is made visible to a plugin: `read: plugin/GTM/read` on the skill folder.
+ *
+ * The name half is canonicalised with the plugin's MANIFEST slug, so
+ * `plugin/Sales Team/read` and `plugin/sales-team/read` are one principal —
+ * the same identity a conformant client keys the plugin on. Reserved in the
+ * group name-safety rules like `role/`.
+ */
+export const PLUGIN_TOKEN_PREFIX = 'plugin/';
+
+/** The verbs a plugin token may name — each is a distinct principal. */
+export const PLUGIN_TOKEN_VERBS = ['read', 'write', 'owner'] as const;
+export type PluginTokenVerb = (typeof PLUGIN_TOKEN_VERBS)[number];
+
+/** The canonical key of a plugin principal, from the plugin's manifest slug. */
+export function pluginPrincipalKey(slug: string, verb: PluginTokenVerb): string {
+  return `${PLUGIN_TOKEN_PREFIX}${slug}/${verb}`;
+}
+
+/**
+ * The parts of a CANONICAL plugin key, or null when the text is not one:
+ * exactly one separator after the prefix, a slug that is its own manifest
+ * slug, one of the three verbs. A generated key never carries a nested
+ * name, so `plugin/a/b/read` is a typo, not a principal.
+ */
+export function parsePluginPrincipalKey(
+  canonical: string,
+): { slug: string; verb: PluginTokenVerb } | null {
+  if (!canonical.startsWith(PLUGIN_TOKEN_PREFIX)) return null;
+  const rest = canonical.slice(PLUGIN_TOKEN_PREFIX.length);
+  const cut = rest.indexOf('/');
+  if (cut <= 0 || rest.indexOf('/', cut + 1) !== -1) return null;
+  const slug = rest.slice(0, cut);
+  if (pluginManifestName(slug) !== slug) return null;
+  const verb = rest.slice(cut + 1);
+  if (!(PLUGIN_TOKEN_VERBS as readonly string[]).includes(verb)) return null;
+  return { slug, verb: verb as PluginTokenVerb };
+}
+
+/**
+ * The canonical key for ANY spelling of a plugin token — `plugin/Sales Team/read`,
+ * `Plugin/sales-team/READ` — or null when the text is not one: a name must be
+ * present and hold no further `/`, the verb must be one of the three. The ONE
+ * place a plugin's spelling folds to its slug: the access-file parser, the
+ * role canonicaliser (which grant and revoke compare through) and the link
+ * service all go through it, so a grant written one way is found again
+ * however it was spelled.
+ */
+export function canonicalPluginToken(token: string): string | null {
+  const body = token.trim();
+  if (!body.toLowerCase().startsWith(PLUGIN_TOKEN_PREFIX)) return null;
+  const rest = body.slice(PLUGIN_TOKEN_PREFIX.length).trim();
+  const cut = rest.lastIndexOf('/');
+  const name = cut > 0 ? rest.slice(0, cut).trim() : '';
+  const verb = cut > 0 ? rest.slice(cut + 1).trim().toLowerCase() : '';
+  if (!name || name.includes('/') || !(PLUGIN_TOKEN_VERBS as readonly string[]).includes(verb)) return null;
+  const slug = pluginManifestName(name);
+  if (!slug) return null;
+  return pluginPrincipalKey(slug, verb as PluginTokenVerb);
+}
+
 export const USER_REF_REGEX = /^(.+?)\s+<\s*([^<>\s]+@[^<>\s]+)\s*>\s*$/;
 export const EMAIL_REGEX = /^[^<>\s@]+@[^<>\s@]+\.[^<>\s@]+$/;
 
@@ -224,9 +305,33 @@ export function hasAccessFrontmatterExtension(p: string): boolean {
 export interface RolesIndex {
   byCanonical: Map<
     string,
-    { displayName: string; emails: Set<string>; groupRefs?: Set<string>; kind?: 'role' | 'group' }
+    {
+      displayName: string;
+      emails: Set<string>;
+      groupRefs?: Set<string>;
+      kind?: 'role' | 'group' | 'plugin';
+      /** For `kind: 'plugin'`: the plugin's identity (its manifest name) the principal derives from. */
+      pluginName?: string;
+      /** For `kind: 'plugin'`: the repo-relative plugin directory, e.g. `Plugins/GTM`. */
+      pluginDir?: string;
+      /**
+       * For `kind: 'plugin'`: the role and group keys whose members the
+       * principal was expanded FROM — the non-user entries of the plugin's
+       * own rules, as `byCanonical` keys. `emails` is the flattened roster;
+       * this is its provenance, kept so a question asked of a PRINCIPAL
+       * rather than a person ("what can this team read?") can follow the
+       * team into the plugins that admit it, the way a member's key set does.
+       */
+      sourceKeys?: Set<string>;
+    }
   >;
   byEmail: Map<string, Set<string>>;
+  /**
+   * Principal keys EVERY caller holds, known or not — a plugin whose own
+   * rules grant `everyone` yields a plugin principal no email list can
+   * enumerate. The resolver unions these into every caller's key set.
+   */
+  publicKeys?: Set<string>;
 }
 // ---------------------------------------------------------------------------
 // Tiny YAML subset parser — handles only block mappings + block sequences
@@ -402,26 +507,18 @@ export function parseYamlSubset(
 export function extractFrontmatter(
   text: string,
 ): { ok: true; frontmatter: string } | { ok: false; error: string } {
-  const lines = text.split(/\r?\n/);
-  if (lines.length === 0 || lines[0].trim() !== '---') {
-    return { ok: false, error: 'expected `---` on the first line' };
-  }
-  for (let i = 1; i < lines.length; i++) {
-    if (lines[i].trim() === '---') {
-      return { ok: true, frontmatter: lines.slice(1, i).join('\n') };
-    }
+  const scan = scanFrontmatter(text);
+  if (scan.kind === 'none') return { ok: false, error: 'expected `---` on the first line' };
+  if (scan.kind === 'unterminated') {
+    return { ok: false, error: 'unterminated frontmatter — no closing `---` found' };
   }
-  return { ok: false, error: 'unterminated frontmatter — no closing `---` found' };
+  return { ok: true, frontmatter: scan.fm.join('\n') };
 }
 
-/** The text AFTER the closing frontmatter fence ('' when there is no fence). */
+/** The text AFTER the closing frontmatter fence ('' when there is no closed block). */
 export function bodyAfterFrontmatter(text: string): string {
-  const lines = text.split(/\r?\n/);
-  if (lines.length === 0 || lines[0].trim() !== '---') return '';
-  for (let i = 1; i < lines.length; i++) {
-    if (lines[i].trim() === '---') return lines.slice(i + 1).join('\n');
-  }
-  return '';
+  const scan = scanFrontmatter(text);
+  return scan.kind === 'frontmatter' ? scan.post.slice(1).join('\n') : '';
 }
 
 // ---------------------------------------------------------------------------
@@ -429,12 +526,18 @@ export function bodyAfterFrontmatter(text: string): string {
 // ---------------------------------------------------------------------------
 
 export function canonicalRoleName(name: string): string {
-  return name.trim().toLowerCase().replace(/\s+/g, ' ');
+  // A plugin token canonicalises to its KEY (slugged name), not to its
+  // lowercased spelling — see `canonicalPluginToken`.
+  return canonicalPluginToken(name) ?? name.trim().toLowerCase().replace(/\s+/g, ' ');
 }
 
-export function canonicalEmail(email: string): string {
-  return email.trim().toLowerCase();
-}
+/**
+ * Re-exported from `shared/email-identity.ts`, where it lives beside the
+ * identity HASH that must normalise identically. The grammar keeps the name
+ * because its parsers and splices read as prose with it, and its own callers
+ * keep importing it from here.
+ */
+export { canonicalEmail };
 
 // ---------------------------------------------------------------------------
 // Entry parser
@@ -482,6 +585,23 @@ export function parseAccessEntry(
     const suffix = canonicalRoleName(role.slice(ROLE_TOKEN_PREFIX.length));
     if (!suffix) return { ok: false, error: `entry '${body}' names no role after '${ROLE_TOKEN_PREFIX}'` };
     role = `${ROLE_TOKEN_PREFIX}${suffix}`;
+  } else if (role.startsWith(PLUGIN_TOKEN_PREFIX)) {
+    // `plugin/<Name>/<verb>`: the name is canonicalised to the plugin's
+    // manifest slug, the verb must be one of the three. Anything else is a
+    // parse error naming the valid shapes — a token that silently resolved to
+    // nothing would be a grant nobody gets and nobody is told about.
+    const key = canonicalPluginToken(body);
+    // Exactly one separator: `plugin/GTM/foo/read` is a typo, not a grant to
+    // some plugin whose slug happens to fold `GTM/foo` into `gtm-foo`.
+    if (key === null) {
+      return {
+        ok: false,
+        error:
+          `entry '${body}' is not a plugin principal — write it as ` +
+          `${PLUGIN_TOKEN_PREFIX}<plugin>/read, ${PLUGIN_TOKEN_PREFIX}<plugin>/write or ${PLUGIN_TOKEN_PREFIX}<plugin>/owner`,
+      };
+    }
+    role = key;
   }
   return { ok: true, entry: { kind: 'role', role, displayRole: body, deny } };
 }
@@ -529,6 +649,16 @@ export function parseRolesYaml(
       );
       continue;
     }
+    // A role spelled `plugin/…` would be overwritten by the synthesised plugin
+    // principal of the same key while its members kept the token — plugin
+    // access for people who are not plugin members. Refused at parse time,
+    // like the group name-safety rule.
+    if (canonical.startsWith(PLUGIN_TOKEN_PREFIX)) {
+      errors.push(
+        `roles.yaml: role '${displayName}' starts with the reserved '${PLUGIN_TOKEN_PREFIX}' prefix — that spelling is the plugin-principal token in access entries`,
+      );
+      continue;
+    }
     if (index.byCanonical.has(canonical)) {
       const prev = index.byCanonical.get(canonical)!.displayName;
       errors.push(
@@ -854,6 +984,25 @@ function verbValuesNeedFullYaml(root: unknown): boolean {
   return false;
 }
 
+/**
+ * Whether an access.md's FRONTMATTER says the file is private: its `read`
+ * denies `everyone` and names nobody but people — the shape the personal
+ * template seeds (`deny everyone` and the owner), and what a person writes
+ * to keep a plugin to a few named colleagues. A role or group beside the
+ * denial is a roster, not a private list; no frontmatter, or a `read` that
+ * never mentions `everyone`, is not a statement of privacy at all (what such
+ * a file admits is whatever the folder above it says). The frontmatter
+ * alone is read on purpose: it is the block a reader sees first and the one
+ * the Library's "Private" mark reflects, so the mark and the file agree.
+ */
+export function isPrivateAccessMd(text: string): boolean {
+  const own = parseOwnAccessEntries(text);
+  if (!own) return false;
+  const deniesEveryone = (e: ParsedEntry) => e.kind === 'role' && e.deny && e.role === EVERYONE_CANONICAL;
+  if (!own.read.some(deniesEveryone)) return false;
+  return own.read.every((e) => deniesEveryone(e) || (e.kind === 'user' && !e.deny));
+}
+
 /**
  * Parse the access verbs a node file declares in its own YAML frontmatter.
  * Returns the per-verb entry lists, or null when the file has no frontmatter

package/src/modules/access-model/access-splice.ts

@@ -34,6 +34,8 @@ import {
   canonicalRoleName,
   accessMdDeclaresBodyRules,
 } from './access-grammar.js';
+import { freshAccessMd } from './access-template.js';
+import { scanFrontmatter } from './frontmatter-lines.js';
 
 /**
  * Which rule block a mutation edits.
@@ -195,24 +197,14 @@ interface Frontmatter {
  * grant into a fresh file synthesise one.
  */
 function splitFrontmatter(text: string): Frontmatter & { hasFrontmatter: boolean } {
-  const eol = text.includes('\r\n') ? '\r\n' : '\n';
-  const lines = text.split(/\r?\n/);
-  // Opening fence must be the very first line.
-  if (lines[0]?.trim() !== '---') {
-    return { pre: [], fm: [], post: lines, eol, hasFrontmatter: false };
+  const scan = scanFrontmatter(text);
+  if (scan.kind === 'unterminated') {
+    throw new AccessSpliceError('unterminated frontmatter — no closing `---`');
   }
-  for (let i = 1; i < lines.length; i++) {
-    if (lines[i].trim() === '---') {
-      return {
-        pre: lines.slice(0, 1), // the opening ---
-        fm: lines.slice(1, i),
-        post: lines.slice(i), // closing --- onward (body preserved)
-        eol,
-        hasFrontmatter: true,
-      };
-    }
+  if (scan.kind === 'none') {
+    return { pre: [], fm: [], post: scan.lines, eol: scan.eol, hasFrontmatter: false };
   }
-  throw new AccessSpliceError('unterminated frontmatter — no closing `---`');
+  return { pre: scan.open, fm: scan.fm, post: scan.post, eol: scan.eol, hasFrontmatter: true };
 }
 
 function joinFrontmatter(f: Frontmatter): string {
@@ -383,8 +375,16 @@ export function spliceGrant(
   const f = splitFrontmatter(text);
 
   if (!f.hasFrontmatter) {
-    // Fresh file — synthesise a minimal frontmatter block, keep any body lines
-    // the caller passed (usually none for a new access.md).
+    // A fresh FOLDER access.md gets the platform's two-block shape, the grant
+    // in the body and the explanation of both blocks in place — the same
+    // file a person would find beside a plugin, so every generated
+    // access.md teaches the same rules. (Only for an EMPTY file: text
+    // without a frontmatter is the legacy single-block format, kept as it is.)
+    if (opts.target === 'folder' && text.trim() === '') {
+      return { text: freshAccessMd(`${verb}:${f.eol}  - ${renderEntry(principal, deny)}`, f.eol), changed: true };
+    }
+    // Fresh node frontmatter — synthesise a minimal block, keep any body
+    // lines the caller passed.
     const itemLine = opts.allowScalar
       ? `${verb}: ${renderEntry(principal, deny)}`
       : `${verb}:${f.eol}  - ${renderEntry(principal, deny)}`;

package/src/modules/access-model/access-template.ts

@@ -0,0 +1,44 @@
+/**
+ * The shape of an `access.md` the platform writes on its own — THE one
+ * explanation of how the file works, carried inside every file it generates
+ * so a person (or an agent) reading it in place learns the rules from the
+ * file itself, rather than from a document they have not opened.
+ *
+ * Two blocks, two scopes: the frontmatter governs the FILE, the body governs
+ * the FOLDER. The wording here is what a fresh folder `access.md` carries
+ * (`spliceGrant` on an empty file with `target: 'folder'`); the plugin and
+ * personal-space templates in the provisioning service say the same thing in
+ * their own words, tailored to what those folders are.
+ */
+
+/** The frontmatter block of a fresh access.md — comments only, no verbs. */
+export const ACCESS_MD_FRONTMATTER_NOTE: readonly string[] = [
+  '# THIS BLOCK (the frontmatter) governs this access.md FILE only: who may see',
+  '# and change these rules. Left empty, the file follows the folder rules below.',
+];
+
+/** The comment block that opens a fresh access.md body, before its verbs. */
+export const ACCESS_MD_BODY_NOTE: readonly string[] = [
+  '# THIS BLOCK (the body) governs the FOLDER this file sits in, and everything',
+  '# beneath it until a nearer access.md says otherwise. Verbs: read, write,',
+  '# download, owner (owner implies the rest; write and download each imply read).',
+  '# An entry is a role from roles.yaml, a group from groups.yaml, a person as',
+  '# `Name <email>`, or `everyone` — every signed-in person, the whole organisation.',
+  '# `deny X` takes away that verb ALONE: grants imply the lower verbs, denials',
+  '# never do — `deny download` says nothing about read, and leaves a separate',
+  '# read grant standing. Keep this block pure YAML; explanations go in `#` lines.',
+];
+
+/**
+ * A fresh access.md around `bodyYaml` (the folder's verbs, already rendered)
+ * — the two blocks, each opened by its note.
+ */
+export function freshAccessMd(bodyYaml: string, eol = '\n'): string {
+  return [
+    '---',
+    ...ACCESS_MD_FRONTMATTER_NOTE,
+    '---',
+    ...ACCESS_MD_BODY_NOTE,
+    bodyYaml,
+  ].join(eol) + eol;
+}

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

@@ -0,0 +1,80 @@
+/**
+ * The contract of the READ-BEFORE-WRITE gate: nothing is created, changed or
+ * removed at a place its author cannot read. The service that answers
+ * (filesystem stats, access checks) is `modules/access/change-read-gate.ts`;
+ * this file carries only the types, so the workflow, kb-fs and tool modules
+ * depend on the contract and never on the access module.
+ *
+ * Why `read`, when every write already needs `write`: on a draft branch no
+ * write grant is needed at all — anyone may propose anything, and the change
+ * request is where the real boundary lives. Without this gate a proposal
+ * could land in a folder its author cannot see, where it would vanish from
+ * them the moment it was added. And a write grant only IMPLIES read; a
+ * nearer `deny read` can take the read away while the write stands. The gate
+ * makes the one rule hold everywhere: you can only change what you can see.
+ *
+ * The one exception is a NEW FOLDER directly under one of the three roots
+ * (knowledge, skills, plugins — `creatableRootDirNames`). Those roots grant
+ * read to nobody by default, and a person's own space or a new plugin or
+ * skill has to start somewhere. The new folder carries its creator's own
+ * grant in its `access.md` (see `ICreatorAccess`), so what they create there
+ * is visible to them from the first byte. A loose FILE directly at a root
+ * cannot carry such a grant, so it is not excepted.
+ */
+
+/**
+ * Where a change is asked about. `'file'` is what every lock acquire is (the
+ * path being written, moved, or deleted — a `.gitkeep` included); `'dir'` is
+ * for a caller asking about a folder itself before it fills it, such as the
+ * destination of an archive extraction.
+ */
+export type ChangeTargetKind = 'file' | 'dir';
+
+export type ChangeReadVerdict =
+  | {
+      allowed: true;
+      via:
+        /** The caller reads the path (or, for a new path, where it lands). */
+        | 'readable'
+        /** A new folder directly under one of the three roots — the exception. */
+        | 'new-top-level-folder'
+        /** Outside the knowledge-base repository: no read rules apply. */
+        | 'outside-kb'
+        /** A machine-owned file whose writer the write rule already names. */
+        | 'machine-owned'
+        /** An admin on a file directly in the repository root — the rescue path. */
+        | 'admin-rescue'
+        /**
+         * No `roles.yaml` on this tree at all — a repository before its first
+         * one: nothing to decide against. A `roles.yaml` that is THERE but
+         * unusable is not this: a broken rule set is an error, never an open
+         * door.
+         */
+        | 'no-rules';
+    }
+  | {
+      allowed: false;
+      /**
+       * The repo-relative path the caller cannot read: the target itself when
+       * it exists, otherwise the folder it would land in (`''` = the root).
+       */
+      unreadable: string;
+    };
+
+export interface IChangeReadGate {
+  /** The verdict for `wsPath` (workspace-relative), with why it holds. */
+  judge(
+    workspaceId: string,
+    userEmail: string,
+    wsPath: string,
+    kind: ChangeTargetKind,
+  ): Promise<ChangeReadVerdict>;
+
+  /** `judge`, throwing `AccessDeniedError` (with `unreadable` set) on a refusal. */
+  assertMayChange(
+    workspaceId: string,
+    userEmail: string,
+    wsPath: string,
+    kind: ChangeTargetKind,
+  ): Promise<void>;
+}

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

@@ -10,22 +10,25 @@
 import type { Principal } from './access-splice.js';
 
 /**
- * How a pending creation gets its creator read grant.
- *   - `seed-access-md`: merge the grant into `wsRelPath` (a new directory's
- *     own `access.md`, workspace-relative) — BEFORE or alongside the creation,
- *     via the caller's own lock+commit machinery. The caller MUST re-read the
- *     file's CURRENT text under its lock and write `apply(current)` ('' when
- *     absent), never a precomputed fresh file: two concurrent creators can
- *     both plan a seed for the same new directory, and a blind overwrite
- *     would silently revoke whichever grant landed first. Skip the write when
- *     `apply` returns the input unchanged, and call `noteAccessFileWritten`
- *     after a write so the resolver cache drops.
- *   - `frontmatter`: run the new file's content through `apply` before
- *     writing it, so the grant lands atomically inside the created file.
+ * How a pending creation gets its creator read grant — there is one way:
+ * `seed-access-md` merges the grant into `wsRelPath` (the new top-level
+ * folder's own `access.md`, workspace-relative) BEFORE or alongside the
+ * creation, via the caller's own lock+commit machinery. The caller MUST
+ * re-read the file's CURRENT text under its lock and write `apply(current)`
+ * ('' when absent), never a precomputed fresh file: two concurrent creators
+ * can both plan a seed for the same new directory, and a blind overwrite
+ * would silently revoke whichever grant landed first. Skip the write when
+ * `apply` returns the input unchanged, and call `noteAccessFileWritten`
+ * after a write so the resolver cache drops.
+ *
+ * Kept a union of one so a second plan kind can return without touching the
+ * consumers' `plan?.kind === 'seed-access-md'` reads.
  */
-export type CreationGrantPlan =
-  | { kind: 'seed-access-md'; wsRelPath: string; apply: (current: string) => string }
-  | { kind: 'frontmatter'; apply: (content: string) => string };
+export type CreationGrantPlan = {
+  kind: 'seed-access-md';
+  wsRelPath: string;
+  apply: (current: string) => string;
+};
 
 /** The creator identity a grant is written for. */
 export interface Creator {
@@ -46,12 +49,6 @@ export interface ICreatorAccess {
     kind: 'file' | 'dir',
   ): Promise<CreationGrantPlan | null>;
 
-  grantInExtractedFile(
-    workspaceId: string,
-    creator: Creator,
-    wsRelPath: string,
-  ): Promise<string | null>;
-
   noteAccessFileWritten(workspaceId: string): void;
 }
 

package/src/modules/access-model/frontmatter-lines.ts

@@ -0,0 +1,98 @@
+/**
+ * THE line-based scan of a `---` frontmatter block, for the access model.
+ *
+ * The access model deliberately does NOT use the two-string splitter in
+ * `@bevel-software/platform-shared`: a splice has to put bytes back exactly
+ * as it found them — comments, blank lines, the file's own line endings —
+ * and that needs the LINES, not two captured strings. Two readers here
+ * scanned for the fences separately (the grammar's `extractFrontmatter` and
+ * `bodyAfterFrontmatter`, and the splice's `splitFrontmatter`), each with its
+ * own copy of the same loop. This is that loop, once.
+ *
+ * What it decides, and what it leaves to the caller:
+ *
+ *   - THE FENCE RULE is NOT decided here: it is `isFrontmatterFence` from the
+ *     shared package, the same function the splitter asks, so the access
+ *     model and the catalog can never again disagree about whether a file
+ *     has frontmatter (`frontmatter-fences.test.ts` asserts they agree).
+ *   - WHAT AN UNTERMINATED BLOCK MEANS is the caller's: the grammar reads it
+ *     as a parse error, the body reader as no body, the splice as a refusal.
+ *     One scan, three answers, none of them re-deriving the fences.
+ */
+import { isFrontmatterFence } from '@bevel-software/platform-shared';
+
+/** An opening fence with no closing one — the caller decides what that means. */
+export interface UnterminatedFrontmatter {
+  kind: 'unterminated';
+}
+
+/** No opening fence: the whole text is body. */
+export interface NoFrontmatter {
+  kind: 'none';
+  /** Every line of the text, so a splice can put it back untouched. */
+  lines: string[];
+  eol: string;
+}
+
+/** A closed `---` block. */
+export interface ScannedFrontmatter {
+  kind: 'frontmatter';
+  /** The opening fence line, on its own — a splice writes it back verbatim. */
+  open: string[];
+  /** The lines BETWEEN the fences. */
+  fm: string[];
+  /** The closing fence line and everything after it. */
+  post: string[];
+  /** The text's own line ending, so a rewrite does not dirty every line. */
+  eol: string;
+}
+
+export type FrontmatterScan = ScannedFrontmatter | NoFrontmatter | UnterminatedFrontmatter;
+
+/** Whether a line IS a fence — the platform's one rule, shared with the catalog's splitter. */
+const isFence = isFrontmatterFence;
+
+/**
+ * The line ending a rewrite of `text` should use: the one MOST of its lines
+ * already use.
+ *
+ * A splice re-joins the whole file with a single separator — the frontmatter
+ * array is edited by index, so there is no surviving per-line ending to put
+ * back — which makes "which ending?" purely a question of whose lines get
+ * rewritten. The majority answers it with the fewest: a consistent file (all
+ * LF, or all CRLF, which is every file git checks out) comes back byte for
+ * byte, and a MIXED file is normalised towards whatever it mostly already is.
+ *
+ * The rule this replaces was "CRLF if the text contains one anywhere", which
+ * let a single stray CRLF — in the body, in a comment — rewrite every line of
+ * a knowledge base's access rules as churn in somebody's change request. Ties
+ * (and a file with no line breaks at all) go to the file's FIRST ending, so
+ * the answer is always the file's own.
+ */
+function dominantEol(text: string): string {
+  let crlf = 0;
+  let lf = 0;
+  let firstIsCrlf = false;
+  for (let i = text.indexOf('\n'); i !== -1; i = text.indexOf('\n', i + 1)) {
+    const isCrlf = i > 0 && text[i - 1] === '\r';
+    if (crlf + lf === 0) firstIsCrlf = isCrlf;
+    if (isCrlf) crlf++;
+    else lf++;
+  }
+  if (crlf > lf) return '\r\n';
+  if (lf > crlf) return '\n';
+  return firstIsCrlf ? '\r\n' : '\n';
+}
+
+/** Scan `text` for a leading `---` block. Decides nothing beyond the fences. */
+export function scanFrontmatter(text: string): FrontmatterScan {
+  const eol = dominantEol(text);
+  const lines = text.split(/\r?\n/);
+  if (!isFence(lines[0])) return { kind: 'none', lines, eol };
+  for (let i = 1; i < lines.length; i++) {
+    if (isFence(lines[i])) {
+      return { kind: 'frontmatter', open: lines.slice(0, 1), fm: lines.slice(1, i), post: lines.slice(i), eol };
+    }
+  }
+  return { kind: 'unterminated' };
+}