@bevel-software/platform-core-backend 0.28.1 → 0.30.0

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

@@ -6,21 +6,25 @@ import { isAbsence } from '../../shared/fs.contract.js';
 import { assertOneSpecPerLine, isGitTimeout } from '../../shared/git.contract.js';
 import { hashEmail } from '../../shared/email-identity.js';
 import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+import { readRevSha } from '../kb-fs/index.js';
 import { DEFAULT_KB_LAYOUT, PLUGIN_MANIFEST_FILE, isPersonalPluginDir, pluginIdentityOf, platformRestoreDestination, } from '@bevel-software/platform-shared';
 import { AccessConfigError, AccessUnreadableError } from '../access-model/access-errors.js';
 import { synthesizePluginPrincipals } from '../access-model/plugin-principals.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, requiredVerbsFor, sourceVerbsFor, } from '../access-model/access-grammar.js';
 import { DIRECTORY_SYNC_BOT_EMAIL, DIRECTORY_SYNC_BOT_NAME, } from './directory-sync-bot.js';
+/** A full object id, which is what every at-ref gate resolves its ref to before reading. */
+function isCommitSha(ref) {
+    return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(ref);
+}
 /**
  * Read many objects from a git repo in ONE `git cat-file --batch` process.
  * `specs` are `<ref>:<path>` lines; the result array is index-aligned with
- * them — the blob's text, or null when the spec is missing/ambiguous at the
- * ref or resolves to a non-blob (e.g. a directory). Output protocol per
- * request: `<oid> <type> <size>\n<size bytes>\n`, or `<spec> missing\n`
- * (the spec may itself contain spaces, hence the endsWith checks).
+ * them. Output protocol per request: `<oid> <type> <size>\n<size bytes>\n`,
+ * or `<spec> missing\n` (the spec may itself contain spaces, hence the
+ * endsWith checks).
  */
-async function catFileBatch(runner, repoDir, specs) {
+async function catFileBatchOutcomes(runner, repoDir, specs) {
     // Bytes, not text: every `<size>` in the header counts bytes, and the walk
     // below has to step by that count through content that is not all ASCII.
     // One spec per LINE is the protocol, and this walk depends on getting back
@@ -42,7 +46,7 @@ async function catFileBatch(runner, repoDir, specs) {
         const header = out.subarray(off, nl).toString('utf-8');
         off = nl + 1;
         if (header.endsWith(' missing') || header.endsWith(' ambiguous')) {
-            results.push(null);
+            results.push({ kind: 'missing' });
             continue;
         }
         const parts = header.split(' ');
@@ -50,13 +54,25 @@ async function catFileBatch(runner, repoDir, specs) {
         if (parts.length !== 3 || !Number.isInteger(size) || size < 0) {
             throw new Error(`unexpected git cat-file header: ${header}`);
         }
-        // Non-blob (a directory path resolves to a tree) → null, but the
-        // payload still has to be skipped to stay aligned.
-        results.push(parts[1] === 'blob' ? out.subarray(off, off + size).toString('utf-8') : null);
+        // A non-blob (a directory path resolves to a tree) is reported as such,
+        // and its payload still has to be skipped to stay aligned.
+        results.push(parts[1] === 'blob'
+            ? { kind: 'blob', text: out.subarray(off, off + size).toString('utf-8') }
+            : { kind: 'non-blob', type: parts[1] });
         off += size + 1; // payload + trailing LF
     }
     return results;
 }
+/**
+ * {@link catFileBatchOutcomes} for callers that want text or nothing: the
+ * blob's text, or null when the spec is missing at the ref or resolves to a
+ * non-blob — the own-entries reads, where a directory where a file was
+ * named simply carries no entries.
+ */
+async function catFileBatch(runner, repoDir, specs) {
+    const outcomes = await catFileBatchOutcomes(runner, repoDir, specs);
+    return outcomes.map((o) => (o.kind === 'blob' ? o.text : null));
+}
 function isBuiltInRole(canonicalRole) {
     return canonicalRole === EVERYONE_CANONICAL;
 }
@@ -1107,22 +1123,49 @@ export class AccessControlService {
      *
      * This is what makes the change-request gates affordable. One detail read
      * plus one approval click runs six at-ref gates, and before this cache
-     * every one of them rebuilt the model from git: an `ls-tree -r` plus a
-     * `git show` per `access.md`, ~270ms each on a real knowledge base. Six
-     * builds per click was the lag behind the approve checkmark.
+     * every one of them rebuilt the model from git. A build is two git calls
+     * (`buildModelAtCommit`: one `ls-tree`, one `cat-file --batch` for every
+     * file the model reads), and each call forks the server process, which
+     * costs tens of milliseconds on a server holding a large heap.
      *
-     * Bounded FIFO, so a long-lived server holds the last few tips rather than
-     * one model per commit it ever gated against. A build that found no usable
-     * roles.yaml is deliberately NOT cached, and a build that saw any git read
-     * fail never becomes a model at all: it throws AccessUnreadableError and the
-     * gate fails closed for that call. Both are what a transient failure looks
-     * like, and pinning either to a commit would turn one hiccup into a wrong
-     * verdict, denying or granting, until the base branch moved. Concurrent
-     * misses on the same commit share one build via `atRefInFlight`.
+     * Bounded FIFO. The bound is sized for a listing that resolves access at
+     * every open change request's two refs: one commit per open request plus
+     * the targets, and a knowledge base with a hundred open requests was
+     * evicting in a cycle under the old bound of 64, rebuilding every model on
+     * every listing — thousands of forks, minutes of the main thread, and
+     * every other request waiting behind them. A commit's tree never changes,
+     * so a model is good for as long as it is held; the bound only caps memory.
+     *
+     * A commit with no roles.yaml is remembered too (`atRefNoRoles`): the batch
+     * read answers "missing" for it from git itself, which is as final as the
+     * commit. What is never cached is a build that saw a git read FAIL: it
+     * throws AccessUnreadableError and the gate fails closed for that call, and
+     * pinning that to a commit would turn one hiccup into a wrong verdict until
+     * the branch moved. Concurrent misses on the same commit share one build
+     * via `atRefInFlight`.
      */
     atRefCache = new Map();
+    atRefNoRoles = new Set();
     atRefInFlight = new Map();
-    static AT_REF_CACHE_MAX = 64;
+    static AT_REF_CACHE_MAX = 512;
+    /**
+     * A path's own access entries AT A COMMIT, keyed by commit + path. A blob
+     * at a commit never changes, so neither does what it declares for itself:
+     * no TTL, no invalidation, and no workspace in the key (every clone holds
+     * the same objects). This is the read every at-ref gate makes after the
+     * model: one `cat-file --batch` per call for the paths asked, which a
+     * change-request listing made once per ref per listing for the same paths
+     * at the same commits. Bounded FIFO; the bound only caps memory.
+     */
+    ownEntriesAtCommit = new Map();
+    static OWN_ENTRIES_AT_COMMIT_MAX = 16_384;
+    /** Paths a cached model keeps of its commit's tree, at most; a larger tree is not kept. */
+    static TREE_INDEX_MAX_PATHS = 20_000;
+    /** Paths held across every cached model's tree, at most; past it the oldest models let their tree go. */
+    static TREE_INDEX_BUDGET = 500_000;
+    treeIndexMaxPaths;
+    treeIndexBudget;
+    treePathsHeld = 0;
     /**
      * Canonicalised deployment-owner emails (see `AccessModel.deploymentOwners`).
      * Held on the service rather than read per-model because it comes from the
@@ -1151,13 +1194,22 @@ export class AccessControlService {
      * `deploymentOwners`: the fixtures that construct this service directly
      * run on the default layout.
      */
-    kb = { layout: DEFAULT_KB_LAYOUT }) {
+    kb = { layout: DEFAULT_KB_LAYOUT }, 
+    /**
+     * How much of the commits' trees the at-ref models may hold (see
+     * `TREE_INDEX_MAX_PATHS`, `TREE_INDEX_BUDGET`). The defaults are the
+     * deployment's; a suite lowers them to reach the bounds with a small
+     * repository.
+     */
+    limits = {}) {
         this.workspaceService = workspaceService;
         this.kbDirName = kbDirName;
         this.disk = disk;
         this.gitRunner = gitRunner;
         this.kb = kb;
         this.deploymentOwners = new Set(deploymentOwners.filter(Boolean).map((e) => canonicalEmail(e)));
+        this.treeIndexMaxPaths = limits.treeIndexMaxPaths ?? AccessControlService.TREE_INDEX_MAX_PATHS;
+        this.treeIndexBudget = limits.treeIndexBudget ?? AccessControlService.TREE_INDEX_BUDGET;
     }
     /**
      * Drop a workspace's cached model + frontmatter memo. Call after operations
@@ -1272,6 +1324,24 @@ export class AccessControlService {
         });
         return result;
     }
+    async groupsOfUser(workspaceId, userEmail) {
+        const model = await this.loadModel(workspaceId);
+        const email = canonicalEmail(userEmail);
+        const names = [];
+        for (const principal of model.roles.byCanonical.values()) {
+            if (principal.kind === 'group' && principal.emails.has(email))
+                names.push(principal.displayName);
+        }
+        return names;
+    }
+    async visibleGroups(workspaceId, userEmail, groups) {
+        if (groups.length === 0)
+            return [];
+        if (await this.holdsAdminRootWrite(workspaceId, userEmail))
+            return [...groups];
+        const mine = new Set(await this.groupsOfUser(workspaceId, userEmail));
+        return groups.filter((g) => mine.has(g));
+    }
     async canWriteBatch(workspaceId, userEmail, relativePaths) {
         const model = await this.loadModel(workspaceId);
         const repoDir = await this.repoDir(workspaceId);
@@ -1650,7 +1720,7 @@ export class AccessControlService {
         if (!loaded)
             return null;
         const repoDir = await this.repoDir(workspaceId);
-        const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath);
+        const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath, loaded.tree);
         return hasPermissionResolved(loaded.model, 'write', userEmail, relativePath, own);
     }
     async canReadAtRef(workspaceId, ref, userEmail, relativePath) {
@@ -1658,7 +1728,7 @@ export class AccessControlService {
         if (!loaded)
             return null;
         const repoDir = await this.repoDir(workspaceId);
-        const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath);
+        const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath, loaded.tree);
         return canReadResolved(loaded.model, userEmail, relativePath, own);
     }
     async canWriteBatchAtRef(workspaceId, ref, userEmail, relativePaths) {
@@ -1678,7 +1748,7 @@ export class AccessControlService {
         const repoDir = await this.repoDir(workspaceId);
         // One `git cat-file --batch` for the whole path set — a per-path `git
         // show` spawn made CR owner-routing take minutes on large change sets.
-        const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
+        const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths, loaded.tree);
         const result = new Map();
         for (const p of relativePaths) {
             const machineOwned = machineAnswers.get(p);
@@ -1695,7 +1765,7 @@ export class AccessControlService {
             return null;
         const repoDir = await this.repoDir(workspaceId);
         // One `git cat-file --batch` for the whole set — see canWriteBatchAtRef.
-        const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
+        const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths, loaded.tree);
         const result = new Map();
         for (const p of relativePaths) {
             result.set(p, canReadResolved(loaded.model, userEmail, p, owns.get(p) ?? null));
@@ -1714,7 +1784,7 @@ export class AccessControlService {
         if (!loaded)
             return null;
         const repoDir = await this.repoDir(workspaceId);
-        const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath);
+        const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath, loaded.tree);
         return eligibleHoldersResolved(loaded.model, 'write', relativePath, own);
     }
     async holdsAdminRootWrite(workspaceId, userEmail) {
@@ -1806,7 +1876,7 @@ export class AccessControlService {
             return null;
         const repoDir = await this.repoDir(workspaceId);
         // One `git cat-file --batch` for the whole path set — see canWriteBatchAtRef.
-        const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
+        const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths, loaded.tree);
         for (const p of relativePaths) {
             if (result.has(p))
                 continue;
@@ -2001,9 +2071,14 @@ export class AccessControlService {
      * grant themselves rights by editing a file's frontmatter in a branch the
      * gate isn't reading from.
      */
-    async readOwnEntriesAtRef(repoDir, ref, relativePath) {
+    async readOwnEntriesAtRef(repoDir, ref, relativePath, tree = null) {
         if (relativePath === 'roles.yaml')
             return null;
+        // At a commit (what every gate passes: `resolvedRef`), the batched read
+        // and its memo answer; a single `git show` stays for a symbolic ref.
+        if (isCommitSha(ref)) {
+            return (await this.readOwnEntriesAtRefBatch(repoDir, ref, [relativePath], tree)).get(relativePath) ?? null;
+        }
         const text = await this.showAtRef(repoDir, ref, relativePath);
         if (text === null)
             return null;
@@ -2019,13 +2094,31 @@ export class AccessControlService {
      * `access.md`/`roles.yaml` (which carry no own-entries) resolve to null,
      * mirroring the single-path helper.
      */
-    async readOwnEntriesAtRefBatch(repoDir, ref, relativePaths) {
+    async readOwnEntriesAtRefBatch(repoDir, ref, relativePaths, tree = null) {
         const result = new Map();
         const wanted = [];
+        const memo = isCommitSha(ref) ? this.ownEntriesAtCommit : null;
         for (const p of relativePaths) {
-            if (p === 'roles.yaml')
+            if (p === 'roles.yaml') {
+                result.set(p, null);
+                continue;
+            }
+            const key = `${ref}\0${p}`;
+            if (memo?.has(key)) {
+                result.set(p, memo.get(key) ?? null);
+                continue;
+            }
+            // A path the commit's tree does not carry has no own entries, as a
+            // fact about the commit: remembered, and not read. (A change request
+            // that adds a file asks about it at the base, where it does not exist
+            // yet; one that deletes a file asks at the head.)
+            if (tree && !tree.has(p)) {
                 result.set(p, null);
-            else if (!wanted.includes(p))
+                if (memo)
+                    this.rememberOwnEntriesAtCommit(key, null);
+                continue;
+            }
+            if (!wanted.includes(p))
                 wanted.push(p);
         }
         if (wanted.length === 0)
@@ -2033,13 +2126,30 @@ export class AccessControlService {
         const texts = await catFileBatch(this.gitRunner, repoDir, wanted.map((p) => `${ref}:${p}`));
         wanted.forEach((p, i) => {
             const text = texts[i];
-            if (text === null)
+            if (text === null) {
+                // Absent at the commit (when no tree was there to say so first), or
+                // a blob git could not read: the batch says "missing" for both, and
+                // only the first is a fact about the commit. Answered as no own
+                // entries, as before, but never remembered.
                 result.set(p, null);
-            else
-                result.set(p, isAccessMdPath(p) ? accessMdSelfEntries(text) : parseOwnAccessEntries(text));
+                return;
+            }
+            const own = isAccessMdPath(p) ? accessMdSelfEntries(text) : parseOwnAccessEntries(text);
+            result.set(p, own);
+            // What a blob declares for itself — including nothing — is a fact about the commit.
+            if (memo)
+                this.rememberOwnEntriesAtCommit(`${ref}\0${p}`, own);
         });
         return result;
     }
+    rememberOwnEntriesAtCommit(key, value) {
+        this.ownEntriesAtCommit.set(key, value);
+        if (this.ownEntriesAtCommit.size > AccessControlService.OWN_ENTRIES_AT_COMMIT_MAX) {
+            const oldest = this.ownEntriesAtCommit.keys().next().value;
+            if (oldest !== undefined)
+                this.ownEntriesAtCommit.delete(oldest);
+        }
+    }
     /**
      * Resolve a candidate ref to one git accepts. Falls back to `origin/<ref>`
      * for short branch names, matching the heuristic in
@@ -2083,27 +2193,39 @@ export class AccessControlService {
     /**
      * List every `access.md` path that exists at any depth as of `ref`.
      * The access tree is structure-agnostic: any `access.md` participates
-     * regardless of where it sits. Uses `git ls-tree -r --name-only`.
-     * `'error'` when git failed: a model built without its access files is
-     * not the model, and the caller must not cache it as one.
+     * regardless of where it sits. Uses `git ls-tree -r -z --name-only`: `-z`
+     * puts a NUL between paths and prints them as they are, where the default
+     * output C-quotes a path with a non-ASCII or special character, which would
+     * then name nothing when read back. `'error'` when git failed: a model
+     * built without its access files is not the model, and the caller must not
+     * cache it as one.
      */
     async listAccessFilesAtRef(repoDir, ref) {
         try {
-            const { stdout } = await this.gitRunner.run(repoDir, ['ls-tree', '-r', '--name-only', ref]);
+            const { stdout } = await this.gitRunner.run(repoDir, ['ls-tree', '-r', '-z', '--name-only', ref]);
             const out = [];
             const pluginDirs = [];
+            const all = [];
+            // The fixed-name sources the tree carries (roles.yaml, the groups
+            // files): a read of one of these that comes back empty is "absent"
+            // only when the tree does not name it.
+            const named = new Set();
             const { pluginsDir } = this.kb.layout;
-            for (const line of stdout.split('\n')) {
-                const p = line.trim();
+            for (const p of stdout.split('\0')) {
                 if (!p)
                     continue;
+                // One past the cap is enough to know the tree is not kept.
+                if (all.length <= this.treeIndexMaxPaths)
+                    all.push(p);
                 if (p === 'access.md' || p.endsWith('/access.md'))
                     out.push(p);
+                else if (p === 'roles.yaml' || p === SYNCED_GROUPS_YAML || p === GROUPS_YAML)
+                    named.add(p);
                 else if (p.startsWith(`${pluginsDir}/`) && p.endsWith(`/${PLUGIN_MANIFEST_FILE}`)) {
                     pluginDirs.push(p.slice(0, -(PLUGIN_MANIFEST_FILE.length + 1)));
                 }
             }
-            return { accessFiles: out, pluginDirs };
+            return { accessFiles: out, pluginDirs, named, all };
         }
         catch {
             return 'error';
@@ -2148,6 +2270,10 @@ export class AccessControlService {
             const hit = this.atRefCache.get(key);
             if (hit)
                 return hit;
+            // A commit known to carry no roles.yaml: the next candidate, without a
+            // build (see `atRefNoRoles`).
+            if (this.atRefNoRoles.has(key))
+                continue;
             // Registered BEFORE the first await on the build path, so concurrent
             // misses on one commit share a single build instead of all racing past
             // an empty in-flight check together.
@@ -2157,6 +2283,8 @@ export class AccessControlService {
                     .then((built) => {
                     if (typeof built !== 'string')
                         this.rememberAtRef(key, built);
+                    else if (built === 'no-roles')
+                        this.rememberNoRolesAtRef(key);
                     return built;
                 })
                     .finally(() => {
@@ -2178,6 +2306,16 @@ export class AccessControlService {
     async revParseCommit(repoDir, ref) {
         if (!ref || ref.startsWith('-'))
             return null;
+        // The ref files first (`readRevSha`): the names git would try, in git's
+        // order, read without a process. "Missing" from the files is what
+        // rev-parse answers nothing for; "unreadable" — a spelling the reader
+        // does not resolve, a tag it cannot peel, a file it could not read — is
+        // git's to decide, as the authority.
+        const fromFiles = await readRevSha(repoDir, ref);
+        if (fromFiles === 'missing')
+            return null;
+        if (fromFiles !== 'unreadable')
+            return fromFiles.sha;
         try {
             const { stdout } = await this.gitRunner.run(repoDir, [
                 'rev-parse',
@@ -2199,10 +2337,32 @@ export class AccessControlService {
     }
     rememberAtRef(key, value) {
         this.atRefCache.set(key, value);
+        this.treePathsHeld += value.tree?.size ?? 0;
         if (this.atRefCache.size > AccessControlService.AT_REF_CACHE_MAX) {
             const oldest = this.atRefCache.keys().next().value;
-            if (oldest !== undefined)
+            if (oldest !== undefined) {
+                this.treePathsHeld -= this.atRefCache.get(oldest)?.tree?.size ?? 0;
                 this.atRefCache.delete(oldest);
+            }
+        }
+        // The trees are a budget of their own, across every held model: past
+        // it, the oldest models keep their model and let their tree go — the
+        // gate still answers, absence is just no longer remembered for them.
+        for (const held of this.atRefCache.values()) {
+            if (this.treePathsHeld <= this.treeIndexBudget)
+                break;
+            if (!held.tree)
+                continue;
+            this.treePathsHeld -= held.tree.size;
+            held.tree = null;
+        }
+    }
+    rememberNoRolesAtRef(key) {
+        this.atRefNoRoles.add(key);
+        if (this.atRefNoRoles.size > AccessControlService.AT_REF_CACHE_MAX) {
+            const oldest = this.atRefNoRoles.values().next().value;
+            if (oldest !== undefined)
+                this.atRefNoRoles.delete(oldest);
         }
     }
     /**
@@ -2212,6 +2372,15 @@ export class AccessControlService {
      * means the commit carries no roles.yaml (the caller tries its next
      * candidate); `'malformed'` means it does but it doesn't parse (the caller
      * answers null, as it always has).
+     *
+     * TWO git calls, whatever the tree holds: one `ls-tree` to learn which
+     * files the model is made of, then one `cat-file --batch` that reads all of
+     * them — roles.yaml, the groups sources, every access.md and every plugin
+     * manifest. It used to be one `git show` per file, and each git call forks
+     * the server process, which on a server holding a large heap costs tens of
+     * milliseconds of the main thread per call: a knowledge base with a few
+     * dozen access files paid a second or more per commit, times every ref a
+     * listing resolves.
      */
     async buildModelAtCommit(repoDir, commit, label) {
         // Every read below tells "absent" apart from "git failed". A failure
@@ -2220,20 +2389,76 @@ export class AccessControlService {
         // and the caller fails closed (AccessUnreadableError, a 503) until a
         // retry reads the tree in full.
         const tag = `${label}@${commit.slice(0, 7)}`;
+        const listed = await this.listAccessFilesAtRef(repoDir, commit);
+        if (listed === 'error') {
+            logger(`access@${tag}`).warn('listing access.md files failed; refusing to decide from a partial tree');
+            throw new AccessUnreadableError(label, 'access.md (ls-tree)');
+        }
+        const wanted = [
+            'roles.yaml',
+            SYNCED_GROUPS_YAML,
+            GROUPS_YAML,
+            ...listed.accessFiles,
+            ...listed.pluginDirs.map((dir) => `${dir}/${PLUGIN_MANIFEST_FILE}`),
+        ];
+        let outcomes;
+        try {
+            outcomes = await catFileBatchOutcomes(this.gitRunner, repoDir, wanted.map((p) => `${commit}:${p}`));
+        }
+        catch (err) {
+            // The operational signal: one line per failed build, naming the commit,
+            // so a run of these is visible in the logs.
+            logger(`access@${tag}`).warn(`git read of the access tree failed; refusing to decide from a partial tree: ${err instanceof Error ? err.message : String(err)}`);
+            throw new AccessUnreadableError(label, 'access tree (cat-file)');
+        }
+        const fetched = new Map();
+        wanted.forEach((p, i) => fetched.set(p, outcomes[i] ?? { kind: 'missing' }));
+        const refuse = (relativePath, why) => {
+            logger(`access@${tag}`).warn(`${relativePath} ${why}; refusing to decide from a partial tree`);
+            throw new AccessUnreadableError(label, relativePath);
+        };
+        // What the build reads. "Missing" from the batch is "absent" only for a
+        // groups source the tree does not name. A path the tree names — an
+        // access.md, a plugin manifest, or a groups file the listing carried —
+        // that comes back missing has a blob git could not read (a lost object),
+        // and one that is not a file is a tree the model cannot be read from:
+        // either way the build fails closed rather than drop what that file
+        // would deny. A path the build did not prefetch (none today) is read on
+        // its own, told apart from a git failure as before.
+        const inTree = (relativePath) => listed.named.has(relativePath) || !(relativePath === SYNCED_GROUPS_YAML || relativePath === GROUPS_YAML);
         const read = async (relativePath) => {
-            const outcome = await this.showAtRefOutcome(repoDir, commit, relativePath);
-            if (outcome.kind === 'error') {
-                // The operational signal: one line per failed read, naming the commit
-                // and the path, so a run of these is visible in the logs.
-                logger(`access@${tag}`).warn(`git read of ${relativePath} failed; refusing to decide from a partial tree`);
-                throw new AccessUnreadableError(label, relativePath);
+            const got = fetched.get(relativePath);
+            if (got === undefined) {
+                const outcome = await this.showAtRefOutcome(repoDir, commit, relativePath);
+                if (outcome.kind === 'error')
+                    refuse(relativePath, 'could not be read');
+                return outcome.kind === 'text' ? outcome.text : null;
             }
-            return outcome.kind === 'text' ? outcome.text : null;
+            if (got.kind === 'blob')
+                return got.text;
+            if (got.kind === 'non-blob')
+                return refuse(relativePath, `is a ${got.type}, not a file`);
+            if (!inTree(relativePath))
+                return null;
+            return refuse(relativePath, 'is in the tree but its blob could not be read');
         };
-        const rolesYaml = await read('roles.yaml');
-        if (rolesYaml === null)
+        // roles.yaml decides the build's outcome, so its states are read
+        // directly. Absent from the tree is "no roles here" (the caller tries
+        // its next candidate ref). In the tree but unreadable refuses the build:
+        // answering "no roles" for it would be remembered for the commit and
+        // would send a short ref through to origin, which may grant. A directory
+        // of that name is as malformed as a file that does not parse (the caller
+        // answers null, and never falls through to a ref that might grant what
+        // this one does not).
+        const roles = fetched.get('roles.yaml') ?? { kind: 'missing' };
+        if (roles.kind === 'missing') {
+            if (listed.named.has('roles.yaml'))
+                refuse('roles.yaml', 'is in the tree but its blob could not be read');
             return 'no-roles';
-        const rolesParsed = parseRolesYaml(rolesYaml);
+        }
+        if (roles.kind === 'non-blob')
+            return 'malformed';
+        const rolesParsed = parseRolesYaml(roles.text);
         if (!rolesParsed.ok)
             return 'malformed';
         // Same group loading as the working-tree model, read AT THE COMMIT — the
@@ -2253,11 +2478,6 @@ export class AccessControlService {
         for (const w of mergeWarnings)
             logger(`access@${tag}`).warn(w);
         const accessFiles = new Map();
-        const listed = await this.listAccessFilesAtRef(repoDir, commit);
-        if (listed === 'error') {
-            logger(`access@${tag}`).warn('listing access.md files failed; refusing to decide from a partial tree');
-            throw new AccessUnreadableError(label, 'access.md (ls-tree)');
-        }
         for (const p of listed.accessFiles) {
             const text = await read(p);
             if (text === null)
@@ -2299,6 +2519,10 @@ export class AccessControlService {
                 deploymentOwners: this.deploymentOwners,
             },
             resolvedRef: commit,
+            // The listing already named every path; held so an own-entries read
+            // can tell absence from a lost blob, unless the tree is too large to
+            // hold for every cached commit (then absence is simply not remembered).
+            tree: listed.all.length <= this.treeIndexMaxPaths ? new Set(listed.all) : null,
         };
     }
 }