@bevel-software/platform-core-backend 0.11.0 → 0.11.2

package/dist/modules/access/access-control.service.js

@@ -3,11 +3,9 @@ import path from 'node:path';
 import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import { createHash } from 'node:crypto';
-import { AccessConfigError } from './access-errors.js';
-// NOTE: deliberate module cycle — group-files.ts imports this module's parsing
-// primitives. Benign: both sides only dereference the other's exports inside
-// function bodies, never at module-evaluation time.
-import { GROUPS_YAML, SYNCED_GROUPS_YAML, parseGroupsFile, } from './group-files.js';
+import { AccessConfigError } from '../access-model/access-errors.js';
+import { GROUPS_YAML, SYNCED_GROUPS_YAML, parseGroupsFile, } from '../access-model/group-files.js';
+import { ADMIN_CANONICAL, EVERYONE_CANONICAL, EVERYONE_DISPLAY, KNOWN_VERBS, ROLE_TOKEN_PREFIX, accessMdSelfEntries, canonicalEmail, canonicalRoleName, isAccessMdPath, mergeGroupsIntoRoles, parseAccessFile, parseOwnAccessEntries, parseRolesYaml, sourceVerbsFor, } from '../access-model/access-grammar.js';
 import { DIRECTORY_SYNC_BOT_EMAIL, DIRECTORY_SYNC_BOT_NAME, } from './directory-sync-bot.js';
 const execFileAsync = promisify(execFile);
 /**
@@ -74,475 +72,12 @@ function catFileBatch(repoDir, specs) {
 function sha256Email(email) {
     return createHash('sha256').update(email.trim().toLowerCase()).digest('hex');
 }
-// ---------------------------------------------------------------------------
-// Constants — kept in lockstep with knowledge-base/lib/access-control.js
-// ---------------------------------------------------------------------------
-export const ADMIN_CANONICAL = 'admin';
-/**
- * Verbs the resolver understands in an `access.md` frontmatter. Each verb
- * is a list of grants (role or `Name <email>` references, optionally
- * prefixed with `deny `). Keep `Verb` and `KNOWN_VERBS` in lockstep —
- * `AccessFile.entries` is statically keyed on this union.
- *
- * `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:`.
- *
- * 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.
- */
-export const KNOWN_VERBS = ['read', 'write', 'download', 'owner'];
-const KNOWN_VERBS_SET = new Set(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`.
- *
- * 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.
- */
-export function sourceVerbsFor(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 ';
-/**
- * Member-entry prefix in roles.yaml that references a GROUP instead of an
- * email: `- group:Engineering`. Explicit on purpose — membership kind is
- * never guessed from string shape. Valid on EVERY role including Admin, with
- * one kept invariant (see `parseRolesYaml`): Admin must always retain at
- * least one direct email member, so a misconfigured or unreachable directory
- * can never leave the deployment without a rescuable admin.
- */
-export const GROUP_REF_PREFIX = 'group:';
-/**
- * Explicit ROLE token prefix in access.md entries: `role/<Name>` resolves to
- * the roles.yaml role only, never a group. A BARE name resolves GROUP-FIRST
- * and falls back to the role — so `role/` is the escape hatch when a group
- * shares the role's name. The prefix is reserved in the group name-safety
- * rules (a group may never be named `role/...`), and every role is also
- * registered in the principal index under its `role/<canonical>` alias.
- */
-export const ROLE_TOKEN_PREFIX = 'role/';
-export const USER_REF_REGEX = /^(.+?)\s+<\s*([^<>\s]+@[^<>\s]+)\s*>\s*$/;
-export const EMAIL_REGEX = /^[^<>\s@]+@[^<>\s@]+\.[^<>\s@]+$/;
-function emptyEntries() {
-    const out = {};
-    for (const v of KNOWN_VERBS)
-        out[v] = [];
-    return out;
-}
-export function isAccessMdPath(p) {
-    return p === 'access.md' || p.endsWith('/access.md');
-}
-/**
- * Extensions of node files whose OWN `---` frontmatter can carry access verbs
- * the resolver enforces (`readOwnEntries` → `parseOwnAccessEntries`). The
- * SINGLE source of truth for every surface that enumerates candidate files —
- * the access-declarations scan and the shared `KbReferenceScanner` (which
- * must scan/rewrite the same set, or a rename strands a live `.tool`
- * frontmatter grant). `access.md` is covered by `.md`.
- */
-export const ACCESS_FRONTMATTER_EXTENSIONS = ['.md', '.tool'];
-/** True when `p` is a file the resolver reads access frontmatter from. */
-export function hasAccessFrontmatterExtension(p) {
-    return ACCESS_FRONTMATTER_EXTENSIONS.some((ext) => p.endsWith(ext));
-}
 function isBuiltInRole(canonicalRole) {
     return canonicalRole === EVERYONE_CANONICAL;
 }
 function roleKnown(roles, canonicalRole) {
     return roles.byCanonical.has(canonicalRole) || isBuiltInRole(canonicalRole);
 }
-/**
- * Strip a trailing `# comment` the way the YAML-subset tokeniser reads a
- * line: a `#` at the start (after only whitespace) or preceded by whitespace
- * begins a comment. Exported so the reference scanner matches tokens against
- * the SAME comment rule the resolver parses with (a `- GTM Team  # sales`
- * entry is the token `GTM Team`, never `GTM Team # sales`).
- */
-export function stripComment(line) {
-    let inWs = true;
-    for (let i = 0; i < line.length; i++) {
-        const ch = line[i];
-        if (ch === '#' && (inWs || (i > 0 && /\s/.test(line[i - 1])))) {
-            return line.slice(0, i);
-        }
-        if (!/\s/.test(ch))
-            inWs = false;
-    }
-    return line;
-}
-function tokenise(text, opts) {
-    const lines = text.split(/\r?\n/);
-    const tokens = [];
-    // Tolerated blank keys are uniquified as runs of spaces so a SECOND blank
-    // key doesn't trip the duplicate-key check (which would retire every valid
-    // group after it). All-whitespace keys still canonicalize to '' downstream,
-    // so the entry-level "empty group name — skipped" handling sees them all.
-    let blankKeySeq = 0;
-    for (let i = 0; i < lines.length; i++) {
-        const stripped = stripComment(lines[i]).replace(/\s+$/, '');
-        if (!stripped.trim())
-            continue;
-        const indentMatch = stripped.match(/^( *)/);
-        const indent = indentMatch ? indentMatch[1].length : 0;
-        const content = stripped.slice(indent);
-        const lineNum = i + 1;
-        if (content.startsWith('- ') || content === '-') {
-            const value = content === '-' ? '' : content.slice(2).trim();
-            tokens.push({ lineNum, indent, kind: 'item', value });
-            continue;
-        }
-        const colonIdx = content.indexOf(':');
-        if (colonIdx < 0) {
-            return { ok: false, error: `line ${lineNum}: expected 'key:' or '- value' but got '${content}'` };
-        }
-        let key = content.slice(0, colonIdx).trim();
-        const valuePart = content.slice(colonIdx + 1).trim();
-        // An empty key is normally a hard error (roles.yaml/access.md want loud
-        // failures), but a parser with ENTRY-level forgiveness (the group files:
-        // one bad entry must not retire every other group) keeps it as a
-        // whitespace key for its own skip-with-warning handling.
-        if (!key) {
-            if (!opts?.tolerateEmptyKeys) {
-                return { ok: false, error: `line ${lineNum}: empty mapping key` };
-            }
-            key = ' '.repeat(++blankKeySeq);
-        }
-        tokens.push({ lineNum, indent, kind: 'kv', key, value: valuePart });
-    }
-    return { ok: true, tokens };
-}
-export function parseYamlSubset(text, opts) {
-    const tok = tokenise(text, opts);
-    if (!tok.ok)
-        return tok;
-    if (tok.tokens.length === 0)
-        return { ok: true, value: {} };
-    const root = {};
-    const stack = [{ indent: -1, container: root, kind: 'map' }];
-    for (let t = 0; t < tok.tokens.length; t++) {
-        const cur = tok.tokens[t];
-        while (stack.length > 1 && stack[stack.length - 1].indent >= cur.indent) {
-            stack.pop();
-        }
-        const top = stack[stack.length - 1];
-        if (cur.kind === 'item') {
-            if (top.kind !== 'list') {
-                return {
-                    ok: false,
-                    error: `line ${cur.lineNum}: list item with no enclosing list (indent ${cur.indent})`,
-                };
-            }
-            top.container.push(cur.value);
-            continue;
-        }
-        if (top.kind !== 'map') {
-            return {
-                ok: false,
-                error: `line ${cur.lineNum}: mapping key '${cur.key}' inside a list — not supported`,
-            };
-        }
-        const map = top.container;
-        const key = cur.key;
-        if (Object.prototype.hasOwnProperty.call(map, key)) {
-            return { ok: false, error: `line ${cur.lineNum}: duplicate key '${key}'` };
-        }
-        if (cur.value !== '') {
-            // Inline empty collections are the only flow-style YAML we accept, so
-            // `owner: []` / `download: []` read as an empty list rather than the
-            // scalar string "[]".
-            if (cur.value === '[]') {
-                map[key] = [];
-                continue;
-            }
-            map[key] = cur.value;
-            continue;
-        }
-        const next = tok.tokens[t + 1];
-        if (!next || next.indent <= cur.indent) {
-            map[key] = null;
-            continue;
-        }
-        if (next.kind === 'item') {
-            const list = [];
-            map[key] = list;
-            stack.push({ indent: cur.indent, container: list, kind: 'list' });
-        }
-        else {
-            const sub = {};
-            map[key] = sub;
-            stack.push({ indent: cur.indent, container: sub, kind: 'map' });
-        }
-    }
-    return { ok: true, value: root };
-}
-// ---------------------------------------------------------------------------
-// Frontmatter extraction
-// ---------------------------------------------------------------------------
-export function extractFrontmatter(text) {
-    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') };
-        }
-    }
-    return { ok: false, error: 'unterminated frontmatter — no closing `---` found' };
-}
-/** The text AFTER the closing frontmatter fence ('' when there is no fence). */
-export function bodyAfterFrontmatter(text) {
-    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 '';
-}
-// ---------------------------------------------------------------------------
-// Canonicalisation
-// ---------------------------------------------------------------------------
-export function canonicalRoleName(name) {
-    return name.trim().toLowerCase().replace(/\s+/g, ' ');
-}
-export function canonicalEmail(email) {
-    return email.trim().toLowerCase();
-}
-// ---------------------------------------------------------------------------
-// Entry parser
-// ---------------------------------------------------------------------------
-export function parseAccessEntry(raw) {
-    if (typeof raw !== 'string')
-        return { ok: false, error: 'entry must be a string' };
-    const trimmed = raw.trim();
-    if (!trimmed)
-        return { ok: false, error: 'empty entry' };
-    let deny = false;
-    let body = trimmed;
-    if (trimmed.startsWith(DENY_PREFIX)) {
-        deny = true;
-        body = trimmed.slice(DENY_PREFIX.length).trim();
-        if (!body)
-            return { ok: false, error: `'deny' with no principal` };
-    }
-    const userMatch = body.match(USER_REF_REGEX);
-    if (userMatch) {
-        const displayName = userMatch[1].trim();
-        const email = canonicalEmail(userMatch[2]);
-        if (!displayName)
-            return { ok: false, error: `user reference '${body}' has no name` };
-        if (!EMAIL_REGEX.test(email)) {
-            return { ok: false, error: `user reference '${body}' has malformed email '${email}'` };
-        }
-        return { ok: true, entry: { kind: 'user', email, displayName, deny } };
-    }
-    if (body.includes('<') || body.includes('>')) {
-        return {
-            ok: false,
-            error: `entry '${body}' looks like a user reference but doesn't match 'Name <email>' shape`,
-        };
-    }
-    let role = canonicalRoleName(body);
-    if (!role)
-        return { ok: false, error: `empty role name in entry '${raw}'` };
-    // Explicit role token: normalize `role/ <Name>` spacing so the canonical
-    // form is always `role/<canonicalName>` — the exact alias key the principal
-    // index registers for every role.
-    if (role.startsWith(ROLE_TOKEN_PREFIX)) {
-        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}`;
-    }
-    return { ok: true, entry: { kind: 'role', role, displayRole: body, deny } };
-}
-// ---------------------------------------------------------------------------
-// roles.yaml + access.md parsers
-// ---------------------------------------------------------------------------
-export function parseRolesYaml(text) {
-    const parsed = parseYamlSubset(text);
-    if (!parsed.ok)
-        return { ok: false, errors: [`roles.yaml: ${parsed.error}`] };
-    const errors = [];
-    const root = parsed.value;
-    if (root == null || typeof root !== 'object' || Array.isArray(root)) {
-        return { ok: false, errors: [`roles.yaml: must be a top-level mapping`] };
-    }
-    const rolesNode = root.roles;
-    if (rolesNode == null || typeof rolesNode !== 'object' || Array.isArray(rolesNode)) {
-        return { ok: false, errors: [`roles.yaml: missing top-level 'roles:' mapping`] };
-    }
-    const index = {
-        byCanonical: new Map(),
-        byEmail: new Map(),
-    };
-    for (const [displayName, value] of Object.entries(rolesNode)) {
-        const canonical = canonicalRoleName(displayName);
-        if (!canonical) {
-            errors.push(`roles.yaml: empty role name`);
-            continue;
-        }
-        if (RESERVED_ROLE_NAMES.has(canonical)) {
-            errors.push(`roles.yaml: role '${displayName}' uses reserved name '${canonical}' — this token has special meaning in access entries and cannot be a roles.yaml role`);
-            continue;
-        }
-        if (canonical.startsWith(ROLE_TOKEN_PREFIX)) {
-            errors.push(`roles.yaml: role '${displayName}' starts with the reserved '${ROLE_TOKEN_PREFIX}' prefix — that spelling is the explicit role token in access entries`);
-            continue;
-        }
-        if (index.byCanonical.has(canonical)) {
-            const prev = index.byCanonical.get(canonical).displayName;
-            errors.push(`roles.yaml: role '${displayName}' canonicalises to '${canonical}', which is already declared as '${prev}'`);
-            continue;
-        }
-        if (!Array.isArray(value)) {
-            errors.push(`roles.yaml: role '${displayName}' must be a list of emails`);
-            continue;
-        }
-        const emails = new Set();
-        const groupRefs = new Set();
-        for (const rawEmail of value) {
-            if (typeof rawEmail !== 'string') {
-                errors.push(`roles.yaml: role '${displayName}' has a non-string entry`);
-                continue;
-            }
-            // `- group:<Name>` assigns the role to a whole group (expanded against
-            // the active group source by `mergeGroupsIntoRoles`). Allowed on every
-            // role, Admin included — the Admin invariant below only demands at
-            // least one DIRECT email member so a broken directory can never leave
-            // the deployment adminless.
-            if (rawEmail.trim().toLowerCase().startsWith(GROUP_REF_PREFIX)) {
-                const refName = canonicalRoleName(rawEmail.trim().slice(GROUP_REF_PREFIX.length));
-                if (!refName) {
-                    errors.push(`roles.yaml: role '${displayName}' has an empty group reference '${rawEmail}'`);
-                    continue;
-                }
-                groupRefs.add(refName);
-                continue;
-            }
-            const email = canonicalEmail(rawEmail);
-            if (!EMAIL_REGEX.test(email)) {
-                errors.push(`roles.yaml: role '${displayName}' has malformed email '${rawEmail}'`);
-                continue;
-            }
-            emails.add(email);
-            let set = index.byEmail.get(email);
-            if (!set) {
-                set = new Set();
-                index.byEmail.set(email, set);
-            }
-            set.add(canonical);
-        }
-        index.byCanonical.set(canonical, { displayName: displayName.trim(), emails, groupRefs });
-    }
-    if (!index.byCanonical.has(ADMIN_CANONICAL)) {
-        errors.push(`roles.yaml: must declare at least one 'Admin' role`);
-    }
-    else if (index.byCanonical.get(ADMIN_CANONICAL).emails.size === 0) {
-        // The kept invariant: Admin may reference groups, but must ALWAYS retain
-        // at least one direct email member — the rescue story requires an admin
-        // whose membership does not depend on a reachable, well-configured
-        // directory. A group-only Admin is as hard an error as an adminless one.
-        errors.push(`roles.yaml: 'Admin' role has no direct email members — Admin must keep at least one individual email (group references alone are not enough)`);
-    }
-    if (errors.length)
-        return { ok: false, errors };
-    return { ok: true, index };
-}
-/**
- * Merge the active group source into the principal index and expand role →
- * group assignments. Mutates `index` in place; returns human-readable
- * warnings (callers log them — nothing here ever throws, because group
- * problems must degrade, not brick access resolution).
- *
- * Rules (the grant-grammar precedence):
- *   - Every role is ALSO registered under its explicit `role/<canonical>`
- *     alias — the token that always resolves to the role.
- *   - A BARE name resolves GROUP-FIRST: when a group's canonical name
- *     collides with a role's, the bare key resolves to the GROUP (warned);
- *     the role stays reachable via `role/<canonical>`.
- *   - Role `group:<Name>` refs — Admin's included — expand against the
- *     merged groups; an unknown ref contributes nothing (warned).
- *   - `byEmail` is rebuilt so each member holds exactly the tokens that
- *     resolve to a principal they belong to (bare + `role/` alias for roles,
- *     bare for groups).
- */
-export function mergeGroupsIntoRoles(index, groups, sourceFile) {
-    const warnings = [];
-    // Snapshot before any group lands: at this point the index holds roles only.
-    const roleRecords = new Map(index.byCanonical);
-    // 1. Expand role → group assignments (Admin included — its safety net is
-    //    the parse-time "at least one direct email" invariant, not a merge skip).
-    for (const [, principal] of roleRecords) {
-        if (!principal.groupRefs?.size)
-            continue;
-        for (const ref of principal.groupRefs) {
-            const group = groups.get(ref);
-            if (!group) {
-                warnings.push(`roles.yaml: role '${principal.displayName}' references unknown group '${ref}' — reference ignored`);
-                continue;
-            }
-            for (const email of group.emails)
-                principal.emails.add(email);
-        }
-    }
-    // 2. Bare-name precedence: groups win the bare token; the role keeps its
-    //    `role/<canonical>` alias registered below.
-    for (const [canonical, def] of groups) {
-        if (roleRecords.has(canonical)) {
-            warnings.push(`${sourceFile}: group '${def.displayName}' shares its name with a role — the bare name now resolves to the GROUP; use '${ROLE_TOKEN_PREFIX}${canonical}' to reference the role`);
-        }
-        index.byCanonical.set(canonical, {
-            displayName: def.displayName,
-            emails: new Set(def.emails),
-            kind: 'group',
-        });
-    }
-    // 3. Explicit `role/<canonical>` alias for every role (same record — the
-    //    alias and the bare key, when the role still owns it, stay in lockstep).
-    for (const [canonical, principal] of roleRecords) {
-        principal.kind = 'role';
-        index.byCanonical.set(`${ROLE_TOKEN_PREFIX}${canonical}`, principal);
-    }
-    // 4. Rebuild the email → tokens map from the final index so membership
-    //    reflects the post-precedence keys (a collided role's members no longer
-    //    hold the bare token unless the group also contains them).
-    index.byEmail.clear();
-    for (const [key, principal] of index.byCanonical) {
-        for (const email of principal.emails) {
-            let set = index.byEmail.get(email);
-            if (!set) {
-                set = new Set();
-                index.byEmail.set(email, set);
-            }
-            set.add(key);
-        }
-    }
-    return warnings;
-}
 /** True for the errno codes that mean "the file genuinely is not there". */
 function isAbsenceError(err) {
     const code = err?.code;
@@ -608,170 +143,6 @@ export async function loadActiveGroups(read) {
         return broken(sourceFile, parsed.errors.join('; '));
     return { groups: parsed.groups, sourceFile, warnings: parsed.warnings, health: { ok: true } };
 }
-/**
- * Does an `access.md` body declare access rules — i.e. is the file in the NEW
- * (body-governs-the-folder) format?
- *
- * The two-format story: historically the FRONTMATTER carried the folder's
- * rules and the file could not govern itself. The new format follows the
- * convention every other file uses — frontmatter is about the FILE (who may
- * read/write `access.md` itself), and the content (the body) is the folder's
- * rules. The compat rule, applied per file: **when the body is not parsable as
- * rules, the frontmatter is resolved for the folder as before.**
- *
- * "Parsable as rules" is deliberately shallow — the body YAML-parses to a
- * mapping that names at least one known verb. A prose body (the repo-root
- * README-style file) fails the YAML parse or carries no verb key and stays
- * legacy. A body that DOES name a verb has claimed to be rules: shape errors
- * inside it (a scalar verb, a malformed entry) are then hard parse ERRORS of
- * the file, never a silent fallback to the frontmatter — falling back would
- * let a typo in the body hand the folder to the frontmatter's (possibly
- * `read: everyone`) self-rules.
- */
-export function accessMdDeclaresBodyRules(text) {
-    const body = bodyAfterFrontmatter(text);
-    if (!body.trim())
-        return false;
-    const parsed = parseYamlSubset(body);
-    if (!parsed.ok)
-        return false;
-    const root = parsed.value;
-    if (root == null || typeof root !== 'object' || Array.isArray(root))
-        return false;
-    return Object.keys(root).some((k) => KNOWN_VERBS_SET.has(k));
-}
-/**
- * The access verbs an `access.md` declares FOR ITSELF — its frontmatter, and
- * only in the new format (body-governed). A legacy file cannot govern itself:
- * its frontmatter IS the folder's rules, so returning them as own-entries
- * would double-apply them at the file scope.
- *
- * Parsed forgivingly (like node frontmatter): the new-format frontmatter may
- * carry non-access keys, and a typo there must not make the file unreadable.
- */
-export function accessMdSelfEntries(text) {
-    if (!accessMdDeclaresBodyRules(text))
-        return null;
-    return parseOwnAccessEntries(text);
-}
-/**
- * Parse one `access.md`'s FOLDER rules into its per-verb entry lists.
- *
- * Two formats (see {@link accessMdDeclaresBodyRules}): when the body declares
- * rules, the body is parsed (new format — frontmatter then governs the file
- * itself via {@link accessMdSelfEntries}); otherwise the frontmatter is parsed
- * (legacy format), exactly as before.
- *
- * Exported so read-only surfaces can report WHERE rules are declared without
- * reimplementing the parse (see `access-declarations.ts`). Exporting changes
- * nothing about resolution — this is the same function the resolver builds its
- * model from, so a display of declarations can never drift from the rules that
- * are actually enforced.
- */
-export function parseAccessFile(text, relativePath) {
-    const bodyFormat = accessMdDeclaresBodyRules(text);
-    let ruleSource;
-    if (bodyFormat) {
-        ruleSource = bodyAfterFrontmatter(text);
-    }
-    else {
-        const fm = extractFrontmatter(text);
-        if (!fm.ok)
-            return { ok: false, errors: [`${relativePath}: ${fm.error}`] };
-        ruleSource = fm.frontmatter;
-    }
-    const parsed = parseYamlSubset(ruleSource);
-    if (!parsed.ok)
-        return { ok: false, errors: [`${relativePath}: ${parsed.error}`] };
-    const root = parsed.value;
-    if (root == null || typeof root !== 'object' || Array.isArray(root)) {
-        return {
-            ok: false,
-            errors: [`${relativePath}: ${bodyFormat ? 'body' : 'frontmatter'} must be a mapping`],
-        };
-    }
-    const errors = [];
-    const warnings = [];
-    const entries = emptyEntries();
-    for (const [key, value] of Object.entries(root)) {
-        if (!KNOWN_VERBS_SET.has(key)) {
-            // Forgiving by design: unknown keys (typos, future verbs, custom
-            // metadata an operator chose to colocate) must not break the access
-            // tree. Warn so operators see the typo in logs, then move on as if
-            // the key didn't exist. The verbs we DO understand still parse.
-            warnings.push(`${relativePath}: unknown access key '${key}' — ignored (known: ${[...KNOWN_VERBS].join(', ')})`);
-            continue;
-        }
-        const verb = key;
-        if (!Array.isArray(value)) {
-            errors.push(`${relativePath}: '${key}:' must be a list`);
-            continue;
-        }
-        const list = [];
-        for (const raw of value) {
-            const result = parseAccessEntry(raw);
-            if (!result.ok) {
-                errors.push(`${relativePath}: ${result.error}`);
-                continue;
-            }
-            list.push(result.entry);
-        }
-        entries[verb] = list;
-    }
-    if (errors.length)
-        return { ok: false, errors };
-    const slash = relativePath.lastIndexOf('/');
-    const dir = slash === -1 ? '' : relativePath.slice(0, slash);
-    return { ok: true, file: { path: relativePath, dir, entries }, warnings };
-}
-/**
- * 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
- * or declares no access verb at all.
- *
- * Forgiving by design — a node's frontmatter legitimately carries non-access
- * keys (notably `nodeType:`), so unknown keys are ignored, and a malformed
- * entry is dropped rather than failing the file. A typo in a node's `owner:`
- * must never make the node unreadable; it just doesn't grant anything.
- */
-export function parseOwnAccessEntries(text) {
-    const fm = extractFrontmatter(text);
-    if (!fm.ok)
-        return null;
-    const parsed = parseYamlSubset(fm.frontmatter);
-    if (!parsed.ok)
-        return null;
-    const root = parsed.value;
-    if (root == null || typeof root !== 'object' || Array.isArray(root))
-        return null;
-    const entries = emptyEntries();
-    let sawVerb = false;
-    for (const [key, value] of Object.entries(root)) {
-        if (!KNOWN_VERBS_SET.has(key))
-            continue; // ignore nodeType, etc.
-        // Accept both the list form (`owner:\n  - A\n  - B`) and the convenience
-        // single-value scalar form (`owner: Test <test@test.com>`) — the latter
-        // is the natural way to name one owner in a node's own frontmatter.
-        // Anything else (a mapping, null) is malformed → skip forgivingly.
-        let raws;
-        if (Array.isArray(value))
-            raws = value;
-        else if (typeof value === 'string' && value.trim())
-            raws = [value];
-        else
-            continue;
-        const verb = key;
-        const list = [];
-        for (const raw of raws) {
-            const result = parseAccessEntry(raw);
-            if (result.ok)
-                list.push(result.entry);
-        }
-        entries[verb] = list;
-        sawVerb = true;
-    }
-    return sawVerb ? entries : null;
-}
 /**
  * Resolve the per-scope verdicts for `verb` at `relativePath`, ordered
  * **closest-to-the-file first**: the node's own frontmatter, then its