@immediately-run/grove 0.1.4 → 0.1.7

package/src/lib/corpusScan.test.ts

@@ -1,5 +1,5 @@
-import { describe, it, expect } from 'vitest';
-import { scanCorpus, listCorpusFiles, type ScanFs } from './corpusScan';
+import { describe, it, expect, vi } from 'vitest';
+import { createCorpusScan, scanCorpus, listCorpusFiles, type ScanFs } from './corpusScan';
 import { parseFrontmatter } from './frontmatter';
 
 /** An in-memory tree, shaped like the fs slice the scan injects. */
@@ -189,3 +189,183 @@ describe('scanCorpus — the additive headings index (GROVE_AGENT_SPEC §4)', ()
     expect(meta['/mnt/c/a.mdx']).toEqual({ title: 'A' });
   });
 });
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+/** The same tree as `fakeFs`, but every `readFile` waits until the test releases it — so
+ *  a test can observe the scan between the listing and the reads, and see read order. */
+function heldFs(files: Record<string, string>, opts: { unreadable?: string[] } = {}) {
+  const base = fakeFs(files, opts);
+  const calls: string[] = [];
+  const held = new Map<string, () => void>();
+  const fs: ScanFs = {
+    readdir: base.readdir,
+    readFile(path, enc) {
+      calls.push(path);
+      return new Promise<void>((resolve) => held.set(path, resolve)).then(() => base.readFile(path, enc));
+    },
+  };
+  const release = async (path: string) => {
+    held.get(path)!();
+    held.delete(path);
+    await tick(); // let the settle + pump run
+  };
+  return { fs, calls, held, release };
+}
+
+
+describe('createCorpusScan — the progressive index (MDX_FROM_MOUNT_SPEC D8)', () => {
+  const tree = {
+    '/mnt/c/home.mdx': entry('Home'),
+    '/mnt/c/a.mdx': entry('A'),
+    '/mnt/c/z.mdx': entry('Z'),
+  };
+
+  it('seeds EVERY listed key with an empty row before any file is read', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { flushMs: 60_000 });
+    expect(scan.snapshot().status).toBe('listing');
+    await vi.waitFor(() => expect(scan.snapshot().status).toBe('reading'));
+    expect(scan.snapshot().metadata).toEqual({ '/mnt/c/a.mdx': {}, '/mnt/c/home.mdx': {}, '/mnt/c/z.mdx': {} });
+    expect(h.held.size).toBeGreaterThan(0); // reads started, none resolved
+    scan.dispose();
+  });
+
+  it('isSettled: false while listing and for a listed-unread key; true once read, once failed, or never listed', async () => {
+    const h = heldFs(tree, { unreadable: ['/mnt/c/z.mdx'] });
+    const scan = createCorpusScan('/mnt/c', h.fs, { flushMs: 0 }); // settled = read AND published
+    expect(scan.isSettled('/mnt/c/a.mdx')).toBe(false);
+    expect(scan.isSettled('/mnt/c/missing.mdx')).toBe(false); // the listing has not answered yet
+    await vi.waitFor(() => expect(scan.snapshot().status).toBe('reading'));
+    expect(scan.isSettled('/mnt/c/a.mdx')).toBe(false);
+    expect(scan.isSettled('/mnt/c/missing.mdx')).toBe(true);
+    await h.release('/mnt/c/a.mdx');
+    await vi.waitFor(() => expect(scan.isSettled('/mnt/c/a.mdx')).toBe(true));
+    await h.release('/mnt/c/z.mdx');
+    await vi.waitFor(() => expect(scan.isSettled('/mnt/c/z.mdx')).toBe(true));
+    await h.release('/mnt/c/home.mdx');
+    await scan.done;
+    // The unreadable entry leaves the index, exactly as the whole-corpus scan always did.
+    expect(Object.keys(scan.snapshot().metadata).sort()).toEqual(['/mnt/c/a.mdx', '/mnt/c/home.mdx']);
+    expect(scan.snapshot().status).toBe('complete');
+  });
+
+  it('prioritize: a key asked for is the NEXT read, ahead of the rest of the corpus', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { concurrency: 1, flushMs: 60_000 });
+    await vi.waitFor(() => expect(h.calls).toEqual(['/mnt/c/a.mdx'])); // sorted order, one at a time
+    scan.prioritize(['/mnt/c/z.mdx']);
+    await h.release('/mnt/c/a.mdx');
+    await vi.waitFor(() => expect(h.calls).toEqual(['/mnt/c/a.mdx', '/mnt/c/z.mdx']));
+    scan.dispose();
+  });
+
+  it('prioritize before the listing finishes: the wanted key is read first', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { concurrency: 1, flushMs: 60_000 });
+    scan.prioritize(['/mnt/c/z.mdx']);
+    await vi.waitFor(() => expect(h.calls).toEqual(['/mnt/c/z.mdx']));
+    scan.dispose();
+  });
+
+  it('a prioritized key publishes as soon as it settles, without waiting for the flush timer', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { concurrency: 1, flushMs: 60_000 });
+    await vi.waitFor(() => expect(scan.snapshot().status).toBe('reading'));
+    const before = scan.snapshot();
+    const seen = vi.fn();
+    scan.subscribe(seen);
+    scan.prioritize(['/mnt/c/a.mdx']); // already in flight — still wanted
+    await h.release('/mnt/c/a.mdx');
+    await vi.waitFor(() => expect(seen).toHaveBeenCalledTimes(1));
+    expect(scan.snapshot()).not.toBe(before);
+    expect(scan.snapshot().metadata['/mnt/c/a.mdx'].title).toBe('A');
+    scan.dispose();
+  });
+
+  it('a read key is not settled until its row is published — the gate never runs ahead of the index', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { concurrency: 1, flushMs: 60_000 });
+    await vi.waitFor(() => expect(scan.snapshot().status).toBe('reading'));
+    await h.release('/mnt/c/a.mdx'); // read, nobody asked for it: waits for the flush
+    expect(scan.snapshot().metadata['/mnt/c/a.mdx']).toEqual({});
+    expect(scan.isSettled('/mnt/c/a.mdx')).toBe(false);
+    scan.prioritize(['/mnt/c/a.mdx']); // now it is wanted: published at once
+    expect(scan.isSettled('/mnt/c/a.mdx')).toBe(true);
+    expect(scan.snapshot().metadata['/mnt/c/a.mdx'].title).toBe('A');
+    scan.dispose();
+  });
+
+  it('an unprioritized read is batched into the next flush', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { concurrency: 1, flushMs: 20 });
+    await vi.waitFor(() => expect(scan.snapshot().status).toBe('reading'));
+    const seen = vi.fn();
+    scan.subscribe(seen);
+    await h.release('/mnt/c/a.mdx');
+    await tick();
+    expect(seen).not.toHaveBeenCalled(); // not per file
+    await vi.waitFor(() => expect(seen).toHaveBeenCalledTimes(1)); // the timer's flush
+    scan.dispose();
+  });
+
+  it('dispose stops handing out reads and cancels the pending publish', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { concurrency: 1, flushMs: 5 });
+    await vi.waitFor(() => expect(h.calls).toHaveLength(1));
+    const seen = vi.fn();
+    scan.subscribe(seen);
+    scan.dispose();
+    await h.release(h.calls[0]!);
+    await new Promise((r) => setTimeout(r, 20));
+    expect(h.calls).toHaveLength(1);
+    expect(seen).not.toHaveBeenCalled();
+    await scan.done; // resolves on dispose rather than hanging
+  });
+
+  it('unsubscribe removes exactly that listener', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { flushMs: 60_000 });
+    const kept = vi.fn();
+    const dropped = vi.fn();
+    scan.subscribe(kept);
+    const off = scan.subscribe(dropped);
+    off();
+    await vi.waitFor(() => expect(scan.snapshot().status).toBe('reading'));
+    expect(kept).toHaveBeenCalledTimes(1);
+    expect(dropped).not.toHaveBeenCalled();
+    scan.dispose();
+  });
+
+  it('an empty bundle completes straight from the listing', async () => {
+    const scan = createCorpusScan('/mnt/c', fakeFs({ '/mnt/c/notes.txt': 'x' }));
+    await scan.done;
+    expect(scan.snapshot()).toEqual({ status: 'complete', metadata: {} });
+  });
+});
+
+describe('createCorpusScan — read failures', () => {
+  const notFound = () => Object.assign(new Error('no such file'), { code: 'ENOENT' });
+
+  it('a transient failure is reported for the key once settled; a missing file is not a failure', async () => {
+    const files = { '/mnt/c/a.mdx': entry('A'), '/mnt/c/b.mdx': entry('B') };
+    const base = fakeFs(files);
+    const fs: ScanFs = {
+      readdir: base.readdir,
+      async readFile(path) {
+        if (path === '/mnt/c/a.mdx') throw new Error('EIO: the channel dropped the request');
+        if (path === '/mnt/c/b.mdx') throw notFound();
+        return base.readFile(path, 'utf8');
+      },
+    };
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const scan = createCorpusScan('/mnt/c', fs, { flushMs: 0 });
+    expect(scan.readFailure('/mnt/c/a.mdx')).toBeNull(); // nothing is known yet
+    await scan.done;
+    expect(scan.readFailure('/mnt/c/a.mdx')).toBe('EIO: the channel dropped the request');
+    expect(scan.readFailure('/mnt/c/b.mdx')).toBeNull();
+    expect(scan.snapshot().metadata).toEqual({}); // both rows leave the index either way
+    expect(warn).toHaveBeenCalledTimes(1);
+    warn.mockRestore();
+  });
+});

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)];
+}