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

package/dist/modules/access-model/access-grammar.js

@@ -0,0 +1,644 @@
+/**
+ * The pure access grammar — every parser, canonicaliser, constant, and type
+ * that defines WHAT the roles/groups/access files mean, with no I/O and no
+ * service state. Extracted from `modules/access/access-control.service.ts`;
+ * the resolver and the `AccessControlService` (filesystem/git model loading,
+ * caching, permission gates) stay there and consume this grammar.
+ *
+ * This module is a LEAF: files here import each other freely, but from the
+ * outside world only node builtins, platform-shared, `@mastra/core/workspace`
+ * types, and `src/shared/*` — never another `modules/*` directory. (The
+ * `./group-files.js` import below is access-model's own file, not a breach.)
+ */
+// ---------------------------------------------------------------------------
+// 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));
+}
+/**
+ * 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: []` reads as an empty list and `groups: {}` as an empty
+            // mapping rather than the scalar strings "[]" / "{}".
+            if (cur.value === '[]') {
+                map[key] = [];
+                continue;
+            }
+            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;
+}
+/**
+ * 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;
+}
+//# sourceMappingURL=access-grammar.js.map