@immediately-run/grove 0.1.3 → 0.1.5

package/src/lib/corpusScan.ts

@@ -38,6 +38,11 @@ export interface ScanFs {
  *  floods the channel the rest of the app shares. A small pool is the honest middle. */
 const READ_CONCURRENCY = 8;
 
+/** How often a running scan publishes a new metadata map. Every consumer of the index
+ *  re-derives on a new identity, so a map per file would re-render the wiki a thousand
+ *  times on a large corpus; a key the entry is waiting on publishes at once instead. */
+const FLUSH_MS = 250;
+
 /** Entry files. `_layout.mdx` is INCLUDED deliberately: `layoutChainForKey` resolves the
  *  chain by looking for layout keys in this very map, so excluding structural files here
  *  would silently drop every layout under dispatch. Reader-facing enumerations filter with
@@ -47,7 +52,8 @@ const ENTRY_RE = /\.mdx?$/;
 /** Directories never worth walking in a content mount. */
 const SKIP_DIRS = new Set(['.git', 'node_modules', '.immediately.run']);
 
-/** Every entry path under `root`, depth-first, absolute. */
+/** Every entry path under `root`, absolute and sorted. Sibling directories are walked
+ *  concurrently: the listing is on the path to first paint, and it reads no file bodies. */
 export async function listCorpusFiles(root: string, fs: ScanFs, maxDepth = 12): Promise<string[]> {
   const out: string[] = [];
   const walk = async (dir: string, depth: number): Promise<void> => {
@@ -66,55 +72,222 @@ export async function listCorpusFiles(root: string, fs: ScanFs, maxDepth = 12):
         out.push(`${dir}${it.name}`);
       }
     }
-    for (const d of dirs) await walk(d, depth + 1);
+    await Promise.all(dirs.map((d) => walk(d, depth + 1)));
   };
   await walk(root.endsWith('/') ? root : `${root}/`, 0);
   return out.sort();
 }
 
-/** Read + parse a list of entries into the metadata map, bounded-concurrently.
- *
- * The additive headings index extension (GROVE_AGENT_SPEC §4): a dispatched row
- * carries its entry's `headings: [{id, text, depth}]`, ids from the same
- * mdx-plugins canon the render path emits (via the SDK's `collectHeadings` — one
- * implementation, shared with the tool that reads the field). The author's own
- * frontmatter `headings` key wins; a row with none of either simply lacks the
- * field (readers degrade to body reads). */
-async function readAll(paths: string[], fs: ScanFs): Promise<CorpusMetadata> {
-  const meta: CorpusMetadata = {};
-  let next = 0;
-  const worker = async (): Promise<void> => {
-    for (;;) {
-      const i = next++;
-      if (i >= paths.length) return;
-      const path = paths[i];
-      try {
-        const raw = await fs.readFile(path, 'utf8');
-        const parsed = parseFrontmatter(raw);
-        const row = parsed.data;
-        const headings = collectHeadings(parsed.body);
-        if (headings.length && !Object.prototype.hasOwnProperty.call(row, 'headings')) {
-          meta[path] = { ...row, headings } as Frontmatter & { headings?: unknown };
-        } else {
-          meta[path] = row;
-        }
-      } catch {
-        // One unreadable entry must not empty the whole corpus. It is simply absent from
-        // the index — the same state it would be in if the author had not written it.
-      }
-    }
-  };
-  await Promise.all(Array.from({ length: Math.min(READ_CONCURRENCY, paths.length) }, worker));
-  return meta;
+/** One entry's index row: its frontmatter, plus the additive headings index extension
+ *  (GROVE_AGENT_SPEC §4). A dispatched row carries its entry's `headings: [{id, text,
+ *  depth}]`, ids from the same mdx-plugins canon the render path emits (via the SDK's
+ *  `collectHeadings` — one implementation, shared with the tool that reads the field). The
+ *  author's own frontmatter `headings` key wins; a row with none of either simply lacks the
+ *  field (readers degrade to body reads). */
+function rowFor(raw: string): Frontmatter {
+  const parsed = parseFrontmatter(raw);
+  const row = parsed.data;
+  const headings = collectHeadings(parsed.body);
+  if (headings.length && !Object.prototype.hasOwnProperty.call(row, 'headings')) {
+    return { ...row, headings } as Frontmatter & { headings?: unknown };
+  }
+  return row;
+}
+
+/** A file that is simply not there is a corpus property, not a failure. */
+function isNotFound(err: unknown): boolean {
+  return typeof err === 'object' && err !== null && (err as { code?: unknown }).code === 'ENOENT';
+}
+
+export type CorpusScanStatus = 'listing' | 'reading' | 'complete';
+
+export interface CorpusScanSnapshot {
+  status: CorpusScanStatus;
+  /** Every listed entry, keyed by absolute path. A row is `{}` until its file is read, so
+   *  existence and link resolution are right from the first render; whether a row has been
+   *  READ is `isSettled`'s question, never the row's. */
+  metadata: CorpusMetadata;
+}
+
+/** The part of a scan the wiki's entry gate needs. The fork packaging's index is complete
+ *  at boot, so its stand-in answers "settled" for every key. */
+export interface CorpusScanGate {
+  /** True once `key` has been read, has failed to read, or the listing has finished
+   *  without it. False while the listing is still running. */
+  isSettled(key: string): boolean;
+  /** Read these keys next, ahead of the rest of the corpus. */
+  prioritize(keys: readonly string[]): void;
+  /** Why a settled key's read failed, when the cause was anything but "not found". */
+  readFailure(key: string): string | null;
+}
+
+export interface CorpusScan extends CorpusScanGate {
+  /** The current published state. Stable identity between publishes. */
+  snapshot(): CorpusScanSnapshot;
+  subscribe(listener: () => void): () => void;
+  /** Resolves when the scan completes or is disposed. */
+  readonly done: Promise<void>;
+  /** Stop reading, cancel the pending publish, drop every listener. */
+  dispose(): void;
+}
+
+export interface CorpusScanOptions {
+  concurrency?: number;
+  flushMs?: number;
 }
 
 /**
- * Build the frontmatter index for a corpus resident at `root`.
+ * Start building the frontmatter index for a corpus resident at `root`.
+ *
+ * The listing comes first and reads no file bodies; every listed path is then in the index
+ * as an empty row, and the rows fill in as the files are read, a bounded pool at a time.
+ * A key passed to `prioritize` jumps the queue, which is how an entry the reader is waiting
+ * for is read before the rest of the corpus.
  *
  * Failure is per-file by design: a corpus is a foreign author's tree, and one malformed or
- * unreadable entry may not take the wiki down with it.
+ * unreadable entry may not take the wiki down with it. An unreadable entry leaves the index
+ * — the same state it would be in if the author had not written it — and counts as settled.
  */
+export function createCorpusScan(root: string, fs: ScanFs, opts: CorpusScanOptions = {}): CorpusScan {
+  const concurrency = Math.max(1, opts.concurrency ?? READ_CONCURRENCY);
+  const flushMs = opts.flushMs ?? FLUSH_MS;
+  const rows: CorpusMetadata = {};
+  // A key is SETTLED only once its row is in a published snapshot — `isSettled` must never
+  // run ahead of the metadata a render can see, or the entry gate would open on an empty
+  // row that reads as `render` unset. `read` holds keys whose row is in `rows` but not yet
+  // published.
+  const settled = new Set<string>();
+  const read = new Set<string>();
+  // Reads that failed for a reason other than "no such file" — a dropped RPC, a rate
+  // limit. The row is gone either way, but the entry gate must not treat a transient
+  // failure of a file it needs as "this file has no frontmatter".
+  const failures = new Map<string, string>();
+  const wanted = new Set<string>();
+  const listeners = new Set<() => void>();
+  let listed: Set<string> | null = null;
+  let queue: string[] = [];
+  let status: CorpusScanStatus = 'listing';
+  let snap: CorpusScanSnapshot = { status, metadata: {} };
+  let active = 0;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let disposed = false;
+  let resolveDone!: () => void;
+  const done = new Promise<void>((resolve) => {
+    resolveDone = resolve;
+  });
+
+  const publish = (): void => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (disposed) return;
+    for (const key of read) settled.add(key);
+    read.clear();
+    snap = { status, metadata: { ...rows } };
+    for (const listener of [...listeners]) listener();
+  };
+  const schedule = (): void => {
+    if (timer === null && !disposed) timer = setTimeout(publish, flushMs);
+  };
+  const finish = (): void => {
+    status = 'complete';
+    publish();
+    resolveDone();
+  };
+
+  const readOne = async (path: string): Promise<void> => {
+    try {
+      rows[path] = rowFor(await fs.readFile(path, 'utf8'));
+    } catch (err) {
+      delete rows[path];
+      if (!isNotFound(err)) {
+        const message = err instanceof Error ? err.message : String(err);
+        failures.set(path, message);
+        console.warn(`[grove] could not read ${path}: ${message}`);
+      }
+    }
+  };
+  const pump = (): void => {
+    while (!disposed && active < concurrency && queue.length) {
+      const path = queue.shift()!;
+      active++;
+      // `readOne` settles every failure itself, so this chain has no rejection to lose.
+      void readOne(path).then(() => {
+        active--;
+        if (disposed) return;
+        read.add(path);
+        if (wanted.delete(path)) publish();
+        else schedule();
+        pump();
+      });
+    }
+    if (!disposed && status === 'reading' && active === 0 && queue.length === 0) finish();
+  };
+
+  void listCorpusFiles(root, fs)
+    .then((paths) => {
+      if (disposed) return;
+      listed = new Set(paths);
+      for (const path of paths) rows[path] = {};
+      const first = [...wanted].filter((k) => listed!.has(k));
+      const firstSet = new Set(first);
+      queue = [...first, ...paths.filter((p) => !firstSet.has(p))];
+      status = 'reading';
+      publish();
+      pump();
+    })
+    .catch((err: unknown) => {
+      // `listCorpusFiles` swallows per-directory failures, so this is a bug, not a corpus
+      // property: say so, and settle as an empty corpus rather than "Opening…" forever.
+      console.error('[grove] corpus listing failed', err);
+      if (disposed) return;
+      listed = new Set();
+      finish();
+    });
+
+  return {
+    snapshot: () => snap,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    isSettled: (key) => settled.has(key) || (listed !== null && !listed.has(key)),
+    readFailure: (key) => (settled.has(key) ? (failures.get(key) ?? null) : null),
+    prioritize(keys) {
+      const front: string[] = [];
+      let readButUnpublished = false;
+      for (const key of keys) {
+        if (read.has(key)) readButUnpublished = true;
+        if (settled.has(key) || read.has(key) || wanted.has(key)) continue;
+        wanted.add(key);
+        const at = queue.indexOf(key);
+        if (at !== -1) {
+          queue.splice(at, 1);
+          front.push(key);
+        }
+      }
+      queue.unshift(...front);
+      // Wanted, and already read before anyone asked: publish now rather than at the timer.
+      if (readButUnpublished) publish();
+    },
+    done,
+    dispose() {
+      disposed = true;
+      if (timer !== null) clearTimeout(timer);
+      timer = null;
+      queue = [];
+      listeners.clear();
+      resolveDone();
+    },
+  };
+}
+
+/** Build the whole index and resolve with it — for callers that want the finished map. */
 export async function scanCorpus(root: string, fs: ScanFs): Promise<CorpusMetadata> {
-  const files = await listCorpusFiles(root, fs);
-  return readAll(files, fs);
+  const scan = createCorpusScan(root, fs);
+  await scan.done;
+  return scan.snapshot().metadata;
 }

package/src/lib/corpusScanContext.ts

@@ -0,0 +1,15 @@
+// How the wiki reaches the running corpus scan (MDX_FROM_MOUNT_SPEC D8).
+//
+// The default is the fork packaging's answer: the bundler's index is complete at boot, so
+// every key is settled and there is nothing to prioritize. Only a dispatched viewer, which
+// builds its index at runtime, provides a live scan here.
+import { createContext } from 'react';
+import type { CorpusScanGate } from './corpusScan';
+
+const COMPLETE: CorpusScanGate = {
+  isSettled: () => true,
+  prioritize: () => undefined,
+  readFailure: () => null,
+};
+
+export const CorpusScanContext = createContext<CorpusScanGate>(COMPLETE);

package/src/lib/criticalKeys.test.ts

@@ -0,0 +1,82 @@
+// The files an entry needs read before it paints (MDX_FROM_MOUNT_SPEC D8). One input is
+// this repo's own corpus, listed by the real `listCorpusFiles` over the real directory —
+// so a layout that exists on disk is proven to be asked for, not assumed.
+import { describe, it, expect } from 'vitest';
+import { promises as nodeFs } from 'node:fs';
+import { join } from 'node:path';
+import { criticalKeys } from './criticalKeys';
+import { listCorpusFiles, type ScanFs } from './corpusScan';
+import { APP_CONTENT_ROOT } from './contentRoot';
+import { folderIndexKey } from './directory';
+
+const DISK_ROOT = join(process.cwd(), 'content') + '/';
+
+/** The real corpus's listing, rebased to the fork's `/app/content/` keys, as an index of
+ *  unread rows — exactly what the scan publishes when its listing finishes. */
+async function listedIndex(): Promise<Record<string, Record<string, unknown>>> {
+  const paths = await listCorpusFiles(DISK_ROOT, nodeFs as unknown as ScanFs);
+  return Object.fromEntries(paths.map((p) => [APP_CONTENT_ROOT + p.slice(DISK_ROOT.length), {}]));
+}
+
+describe('criticalKeys', () => {
+  it('over the real corpus: home, the entry, and every layout on its folder path that exists', async () => {
+    const index = await listedIndex();
+    const entry = Object.keys(index).find((k) => k.startsWith('/app/content/people/') && !k.endsWith('_layout.mdx'))!;
+    expect(entry).toBeDefined();
+    const keys = criticalKeys(entry, index);
+    expect(keys).toEqual([
+      '/app/content/home.mdx',
+      entry,
+      '/app/content/_layout.mdx',
+      '/app/content/people/_layout.mdx',
+    ]);
+    // Every layout named is one the listing found — none is invented.
+    for (const k of keys) expect(index).toHaveProperty([k]);
+  });
+
+  it('asks only for layouts that exist', () => {
+    const index = { '/app/content/home.mdx': {}, '/app/content/a/b/x.mdx': {}, '/app/content/a/_layout.mdx': {} };
+    expect(criticalKeys('/app/content/a/b/x.mdx', index)).toEqual([
+      '/app/content/home.mdx',
+      '/app/content/a/b/x.mdx',
+      '/app/content/a/_layout.mdx',
+    ]);
+  });
+
+  it('adds the `frame:` target once the entry row is read and names one that exists', () => {
+    const index: Record<string, Record<string, unknown>> = {
+      '/app/content/home.mdx': {},
+      '/app/content/x.mdx': {},
+      '/app/content/frames/wide.mdx': {},
+    };
+    expect(criticalKeys('/app/content/x.mdx', index)).not.toContain('/app/content/frames/wide.mdx');
+    index['/app/content/x.mdx'] = { frame: 'frames/wide' };
+    expect(criticalKeys('/app/content/x.mdx', index)).toContain('/app/content/frames/wide.mdx');
+    index['/app/content/x.mdx'] = { frame: 'frames/absent' };
+    expect(criticalKeys('/app/content/x.mdx', index)).toEqual(['/app/content/home.mdx', '/app/content/x.mdx']);
+    index['/app/content/x.mdx'] = { frame: 'none' };
+    expect(criticalKeys('/app/content/x.mdx', index)).toEqual(['/app/content/home.mdx', '/app/content/x.mdx']);
+  });
+
+  it('a folder route: the entry is the folder index the router resolves, wrapped by that folder\'s layout', () => {
+    // GroveWiki hands `folderIndexKey(route, keys) ?? route` to criticalKeys; the real
+    // resolver picks the entry here, so the case follows the router, not a guess at it.
+    const index = {
+      '/app/content/home.mdx': {},
+      '/app/content/guides/index.mdx': {},
+      '/app/content/guides/_layout.mdx': {},
+      '/app/content/guides/first.mdx': {},
+    };
+    const entry = folderIndexKey('/app/content/guides', Object.keys(index));
+    expect(entry).toBe('/app/content/guides/index.mdx');
+    expect(criticalKeys(entry!, index)).toEqual([
+      '/app/content/home.mdx',
+      '/app/content/guides/index.mdx',
+      '/app/content/guides/_layout.mdx',
+    ]);
+  });
+
+  it('home is named once when it is the entry', () => {
+    expect(criticalKeys('/app/content/home.mdx', { '/app/content/home.mdx': {} })).toEqual(['/app/content/home.mdx']);
+  });
+});

package/src/lib/criticalKeys.ts

@@ -0,0 +1,37 @@
+// The files that decide how an entry renders — the ones a dispatched viewer must have READ
+// before it paints the entry (MDX_FROM_MOUNT_SPEC D8).
+//
+// Everything else in the index feeds the surfaces AROUND the entry (nav, sidebar, search,
+// backlinks, index components), which may fill in as the scan continues. These do not: the
+// entry's own row carries `layout`, `view`, `frame` and a per-entry `render: safe`; home
+// carries the wiki-wide `site`, `theme`, `render: safe` and `stylesheets`; the layouts on
+// the entry's folder path are the chrome it renders inside. Painting before any of them is
+// read either shows the wrong page or, for `render: safe`, runs code that must not run.
+import { homeKey } from './content';
+import { explicitFrameKey, layoutKeysOnPath } from './layout';
+import type { CorpusScanGate } from './corpusScan';
+
+/**
+ * The keys to read before `entryKey` paints, given the index as it stands. `metadata` holds
+ * every LISTED key (read or not), so a layout that does not exist is never asked for. The
+ * set grows once the entry's own row is read and turns out to name a `frame:` — the caller
+ * recomputes on every index update, so it converges.
+ *
+ * A file whose read FAILED has left `metadata`, but it exists; it stays in the set so the
+ * gate sees its failure and fails closed, rather than painting the entry without that
+ * layout. `readFailure` is the scan's; the default suits an index with no scan behind it.
+ */
+export function criticalKeys(
+  entryKey: string,
+  metadata: Record<string, unknown>,
+  readFailure: CorpusScanGate['readFailure'] = () => null,
+): string[] {
+  const exists = (key: string) => key in metadata || readFailure(key) !== null;
+  const keys = [homeKey(), entryKey];
+  for (const lk of layoutKeysOnPath(entryKey)) {
+    if (exists(lk)) keys.push(lk);
+  }
+  const frame = explicitFrameKey(metadata[entryKey] as Record<string, unknown> | undefined);
+  if (frame !== null && exists(frame)) keys.push(frame);
+  return [...new Set(keys)];
+}

package/src/lib/entryGate.test.ts

@@ -0,0 +1,136 @@
+// The body gate (MDX_FROM_MOUNT_SPEC D8), driven by a REAL scan rather than a stubbed
+// `isSettled`, so "pending" means what the scan means by it.
+import { describe, it, expect, vi } from 'vitest';
+import { criticalFailure, entryPending } from './entryGate';
+import { createCorpusScan, type ScanFs } from './corpusScan';
+import { criticalKeys } from './criticalKeys';
+
+/** A two-file corpus whose reads wait for `release()`. */
+function corpus(files: Record<string, string>) {
+  const held: Array<() => void> = [];
+  const fs: ScanFs = {
+    async readdir() {
+      return Object.keys(files).map((p) => ({ name: p.slice('/c/'.length), isDirectory: () => false }));
+    },
+    readFile(path) {
+      return new Promise<string>((resolve) => held.push(() => resolve(files[path]!)));
+    },
+  };
+  const release = () => held.splice(0).forEach((r) => r());
+  return { fs, release };
+}
+
+const FILES = { '/c/home.mdx': '---\ntitle: H\n---\n', '/c/x.mdx': '---\ntitle: X\n---\n' };
+
+describe('entryPending', () => {
+  it('pending while a critical key is unread; clear once the scan has read it', async () => {
+    const c = corpus(FILES);
+    const scan = createCorpusScan('/c/', c.fs, { flushMs: 0 });
+    const critical = ['/c/home.mdx', '/c/x.mdx'];
+    expect(entryPending(critical, scan.isSettled, 'ready')).toBe(true); // still listing
+    await new Promise((r) => setTimeout(r, 0));
+    expect(entryPending(critical, scan.isSettled, 'ready')).toBe(true); // listed, unread
+    c.release();
+    await scan.done;
+    expect(entryPending(critical, scan.isSettled, 'ready')).toBe(false);
+  });
+
+  it('a critical key the listing did not find (no home.mdx) does not hold the entry', async () => {
+    const c = corpus({ '/c/x.mdx': FILES['/c/x.mdx'] });
+    const scan = createCorpusScan('/c/', c.fs, { flushMs: 0 });
+    await new Promise((r) => setTimeout(r, 0));
+    c.release();
+    await scan.done;
+    expect(entryPending(['/c/home.mdx', '/c/x.mdx'], scan.isSettled, 'ready')).toBe(false);
+  });
+
+  it('pending while declared stylesheets load, even with every key read', () => {
+    expect(entryPending(['/c/x.mdx'], () => true, 'loading')).toBe(true);
+    expect(entryPending(['/c/x.mdx'], () => true, 'ready')).toBe(false);
+  });
+});
+
+describe('criticalFailure', () => {
+  it('names the first critical key whose read failed, and nothing when none did', () => {
+    const failed: Record<string, string> = { '/c/x.mdx': 'EIO' };
+    expect(criticalFailure(['/c/home.mdx', '/c/x.mdx'], (k) => failed[k] ?? null)).toBe(
+      'Could not read /c/x.mdx (EIO). Reload to try again.',
+    );
+    expect(criticalFailure(['/c/home.mdx'], (k) => failed[k] ?? null)).toBeNull();
+  });
+});
+
+/** A listing-shaped fs over `files`; a read of any path in `failing` throws EIO. */
+function failingFs(files: Record<string, string>, failing: (path: string) => boolean): ScanFs {
+  return {
+    async readdir(dir) {
+      const names = new Map<string, boolean>();
+      for (const p of Object.keys(files)) {
+        if (!p.startsWith(dir)) continue;
+        const rest = p.slice(dir.length);
+        const slash = rest.indexOf('/');
+        names.set(slash === -1 ? rest : rest.slice(0, slash), slash !== -1);
+      }
+      return [...names].map(([name, isDir]) => ({ name, isDirectory: () => isDir }));
+    },
+    async readFile(path) {
+      if (failing(path)) throw new Error('EIO dropped');
+      return files[path]!;
+    },
+  };
+}
+
+describe('fail closed on a failed FRAME read, end to end with a real scan', () => {
+  it('a frame: target whose read failed stays critical and fails the gate', async () => {
+    const files: Record<string, string> = {
+      '/app/content/home.mdx': '---\ntitle: H\n---\n',
+      '/app/content/frames/wide.mdx': '---\n---\n',
+      '/app/content/a.mdx': '---\ntitle: A\nframe: frames/wide\n---\n',
+    };
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const scan = createCorpusScan('/app/content/', failingFs(files, (p) => p.endsWith('wide.mdx')), { flushMs: 0 });
+    await scan.done;
+    const critical = criticalKeys('/app/content/a.mdx', scan.snapshot().metadata, scan.readFailure);
+    expect(critical).toContain('/app/content/frames/wide.mdx');
+    expect(criticalFailure(critical, scan.readFailure)).toBe(
+      'Could not read /app/content/frames/wide.mdx (EIO dropped). Reload to try again.',
+    );
+    warn.mockRestore();
+  });
+});
+
+describe('fail closed on a failed LAYOUT read, end to end with a real scan', () => {
+  it('a layout whose read failed stays critical and fails the gate, instead of painting without it', async () => {
+    const files: Record<string, string> = {
+      '/app/content/home.mdx': '---\ntitle: H\n---\n',
+      '/app/content/guides/_layout.mdx': '---\n---\n',
+      '/app/content/guides/a.mdx': '---\ntitle: A\n---\n',
+    };
+    const fs: ScanFs = {
+      async readdir(dir) {
+        const names = new Map<string, boolean>();
+        for (const p of Object.keys(files)) {
+          if (!p.startsWith(dir)) continue;
+          const rest = p.slice(dir.length);
+          const slash = rest.indexOf('/');
+          names.set(slash === -1 ? rest : rest.slice(0, slash), slash !== -1);
+        }
+        return [...names].map(([name, isDir]) => ({ name, isDirectory: () => isDir }));
+      },
+      async readFile(path) {
+        if (path.endsWith('_layout.mdx')) throw new Error('EIO dropped');
+        return files[path]!;
+      },
+    };
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const scan = createCorpusScan('/app/content/', fs, { flushMs: 0 });
+    await scan.done;
+    const entry = '/app/content/guides/a.mdx';
+    const critical = criticalKeys(entry, scan.snapshot().metadata, scan.readFailure);
+    expect(critical).toContain('/app/content/guides/_layout.mdx');
+    expect(criticalFailure(critical, scan.readFailure)).toBe(
+      'Could not read /app/content/guides/_layout.mdx (EIO dropped). Reload to try again.',
+    );
+    warn.mockRestore();
+  });
+});

package/src/lib/entryGate.ts

@@ -0,0 +1,28 @@
+// Whether the entry body must still wait (MDX_FROM_MOUNT_SPEC D8).
+//
+// Pending while any file that decides how the entry renders is unread, or while the
+// stylesheets home declares are still loading (D7) — the page paints once, styled. And
+// FAILED — not painted — when one of those files could not be read for a reason other than
+// its absence: an unread home or entry reads as `render` unset, which is the executing
+// path, so a transient failure must not quietly become "no frontmatter".
+import type { CorpusScanGate } from './corpusScan';
+
+export function entryPending(
+  critical: readonly string[],
+  isSettled: CorpusScanGate['isSettled'],
+  stylesheets: 'loading' | 'ready',
+): boolean {
+  return stylesheets === 'loading' || critical.some((key) => !isSettled(key));
+}
+
+/** The reader-facing line for the first critical key whose read failed, or null. */
+export function criticalFailure(
+  critical: readonly string[],
+  readFailure: CorpusScanGate['readFailure'],
+): string | null {
+  for (const key of critical) {
+    const reason = readFailure(key);
+    if (reason !== null) return `Could not read ${key} (${reason}). Reload to try again.`;
+  }
+  return null;
+}

package/src/lib/layout.ts

@@ -20,6 +20,26 @@ function layoutKeyForDir(dir: string): string {
   return dir + '_layout.mdx';
 }
 
+/**
+ * The folder-convention layout keys that COULD wrap `entryKey`, outermost first: one per
+ * directory from the content root down to the entry's own. Whether each exists is the
+ * caller's question — the chain asks the index, the entry gate asks it too, and both must
+ * walk the same directories.
+ */
+export function layoutKeysOnPath(entryKey: string): string[] {
+  const root = contentDir();
+  if (!entryKey.startsWith(root)) return [];
+  // Directories from the content root down to (but not including) the entry file.
+  const segs = entryKey.slice(root.length).split('/').slice(0, -1); // "people/ada.mdx" → ["people"]
+  const keys = [layoutKeyForDir(root)];
+  let dir = root;
+  for (const s of segs) {
+    dir = dir + s + '/';
+    keys.push(layoutKeyForDir(dir));
+  }
+  return keys;
+}
+
 /**
  * R3-309 — which nav arrangement the ROOT layout asks for. The root `_layout.mdx`'s
  * frontmatter may carry `nav: top | nav: side`; anything else (absent, misspelled,
@@ -49,6 +69,14 @@ export function resolvePageLayout(
   return v === 'post' || v === 'full' ? v : 'doc';
 }
 
+/** The layout key an entry names with `frame: '<slug>'`, or null when it names none
+ *  (absent, `none`, `false`, or not a string). Whether that layout exists is the caller's
+ *  question. */
+export function explicitFrameKey(entryMeta: Record<string, unknown> | undefined): string | null {
+  const f = entryMeta?.frame;
+  return typeof f === 'string' && f && f !== 'none' ? slugToKey(f) : null;
+}
+
 /** Does an entry/layout opt out of an inherited layout chain? `frame: none`
  *  (or `frame: false`) means "render me bare / stop inheritance above here". */
 function optsOut(meta: Record<string, unknown> | undefined): boolean {
@@ -82,29 +110,12 @@ export function layoutChainForKey(
   const entryMeta = metaOf(entryKey);
   if (optsOut(entryMeta)) return [];
 
-  const explicit = entryMeta?.frame;
-  if (typeof explicit === 'string' && explicit && explicit !== 'none') {
-    const key = slugToKey(explicit);
-    return allKeys.includes(key) ? [key] : [];
-  }
+  const explicit = explicitFrameKey(entryMeta);
+  if (explicit !== null) return allKeys.includes(explicit) ? [explicit] : [];
 
   const present = new Set(allKeys.filter(isLayoutKey));
-  const root = contentDir();
-  if (!entryKey.startsWith(root)) return [];
-
-  // Directories from the content root down to (but not including) the entry file.
-  const rel = entryKey.slice(root.length); // e.g. "people/ada.mdx"
-  const segs = rel.split('/').slice(0, -1); // e.g. ["people"]
-  const dirs = [root];
-  let dir = root;
-  for (const s of segs) {
-    dir = dir + s + '/';
-    dirs.push(dir);
-  }
-
   const chain: string[] = [];
-  for (const d of dirs) {
-    const lk = layoutKeyForDir(d);
+  for (const lk of layoutKeysOnPath(entryKey)) {
     if (!present.has(lk)) continue;
     if (optsOut(metaOf(lk))) chain.length = 0; // this layout is a new root
     chain.push(lk);