@sanity/ailf 4.1.0 → 4.3.0

package/dist/sanity/document-renderers.js

@@ -0,0 +1,307 @@
+/**
+ * document-renderers.ts
+ *
+ * Renderer registry that turns a Sanity document into both:
+ *
+ *   - Markdown content for inclusion in a literacy task's grader/candidate
+ *     context (existing surface, used by the doc fetcher).
+ *   - A symbol-reference index for the W0197 grader-context pathway —
+ *     a flat list of identifiers the doc legitimizes, with provenance.
+ *     The grader prefers this over the rendered markdown when available
+ *     (smaller, deterministic, harder for the grader's prior to override).
+ *
+ * Both surfaces dispatch through the same registry. Articles and
+ * typesReference docs have hand-written renderers; everything else falls
+ * through to the default walker. This keeps "what to do with a document
+ * of type X" a single decision point regardless of whether the doc was
+ * looked up by slug, path, perspective, or id.
+ *
+ * Two tiers of fidelity (rendered output):
+ *
+ *   1. Registered renderers (high fidelity) — `article`, `typesReference`.
+ *      Hand-written for the document shapes we care about most.
+ *   2. Default renderer (best effort) — walks the doc, flattens portable-text
+ *      fields, surfaces top-level scalars, follows references one level deep,
+ *      skips framework-internal fields. Lets pinning a `marketingPage`,
+ *      `glossaryEntry`, etc. work without AILF code changes.
+ *
+ * Adding a new high-fidelity renderer: implement a `DocumentRenderer`
+ * (both `render` and `extractSymbols`) and register it in
+ * `BUILT_IN_RENDERERS` keyed by `_type`.
+ */
+import { toMarkdown } from "./portable-text.js";
+import { extractSymbolIndex, extractSymbolsFromTypedoc, mergeSymbolIndexes, } from "./symbol-index.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const DEFAULT_MAX_BYTES = 30_000;
+const SKIP_FIELDS = new Set([
+    "_createdAt",
+    "_id",
+    "_rev",
+    "_system",
+    "_type",
+    "_updatedAt",
+    "_key",
+]);
+function isPortableTextArray(value) {
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        typeof value[0] === "object" &&
+        value[0] !== null &&
+        "_type" in value[0]);
+}
+function truncate(content, max) {
+    if (content.length <= max)
+        return content;
+    return (content.slice(0, max) +
+        `\n\n*[content truncated — ${content.length - max} more bytes omitted]*`);
+}
+function slugForDoc(doc) {
+    const slugField = doc.slug;
+    if (typeof slugField === "object" &&
+        slugField !== null &&
+        "current" in slugField &&
+        typeof slugField.current === "string") {
+        return slugField.current;
+    }
+    if (typeof slugField === "string")
+        return slugField;
+    return `${doc._type}:${doc._id}`;
+}
+function renderArticle(doc) {
+    const title = doc.title ?? "(untitled)";
+    const description = doc.description;
+    const section = doc.section;
+    const content = doc.content;
+    const sectionLabel = section?.title ? `Section: ${section.title}\n` : "";
+    const desc = description ? `${description}\n\n` : "";
+    const markdown = toMarkdown(content ?? []);
+    return {
+        content: `## ${title}\n\n${sectionLabel}${desc}${markdown}`,
+        fidelity: "high",
+        slug: slugForDoc(doc),
+    };
+}
+const articleRenderer = {
+    render: renderArticle,
+    extractSymbols(doc) {
+        const content = doc.content;
+        if (!Array.isArray(content))
+            return { symbols: [] };
+        return extractSymbolIndex(content);
+    },
+};
+async function renderTypesReference(doc, ctx) {
+    const title = doc.title ?? "(untitled)";
+    const slug = slugForDoc(doc);
+    const library = doc.library;
+    const latestVersion = doc.latestVersion;
+    const asset = latestVersion?.attachment?.asset;
+    const max = ctx.maxBytes ?? DEFAULT_MAX_BYTES;
+    const lines = [];
+    lines.push(`## ${title}`, "");
+    lines.push(`Slug: \`${slug}\``);
+    if (library?.npmName)
+        lines.push(`Package: \`${library.npmName}\``);
+    if (latestVersion?.semver)
+        lines.push(`Version: \`${latestVersion.semver}\``);
+    if (latestVersion?.date)
+        lines.push(`Released: ${latestVersion.date}`);
+    lines.push("");
+    if (!asset?.url) {
+        lines.push("*[no attached type definitions found — resolver could not locate `latestVersion.attachment.asset.url`]*");
+        return { content: lines.join("\n"), fidelity: "high", slug };
+    }
+    if (!ctx.fetchUrl) {
+        lines.push(`*[type definitions live at ${asset.url} — fetcher not configured to retrieve attachments]*`);
+        return { content: lines.join("\n"), fidelity: "high", slug };
+    }
+    const body = await ctx.fetchUrl(asset.url);
+    if (body === null) {
+        lines.push(`*[failed to fetch type definitions from ${asset.url}]*`);
+        return { content: lines.join("\n"), fidelity: "high", slug };
+    }
+    const filename = asset.originalFilename ?? "types.json";
+    const lang = filename.endsWith(".json") ? "json" : "";
+    lines.push(`### Type definitions (${filename})`, "");
+    lines.push("```" + lang);
+    // Reserve ~200 bytes for the fence + trailing notice
+    lines.push(truncate(body, Math.max(0, max - 200)));
+    lines.push("```");
+    return { content: lines.join("\n"), fidelity: "high", slug };
+}
+async function extractTypesReferenceSymbols(doc, ctx) {
+    const library = doc.library;
+    const latestVersion = doc.latestVersion;
+    const asset = latestVersion?.attachment?.asset;
+    // Re-fetches the same URL the renderer would; bounded to ≤ a handful of
+    // typesReference docs per eval run, so the duplicate I/O is acceptable.
+    // Fold into a single registry method later if profiling shows it bites.
+    if (!asset?.url || !ctx.fetchUrl)
+        return { symbols: [] };
+    const body = await ctx.fetchUrl(asset.url);
+    if (body === null)
+        return { symbols: [] };
+    return extractSymbolsFromTypedoc(body, library?.npmName);
+}
+const typesReferenceRenderer = {
+    render: renderTypesReference,
+    extractSymbols: extractTypesReferenceSymbols,
+};
+// ---------------------------------------------------------------------------
+// formatDefault — generic walker for any unknown `_type`.
+//
+// Walks top-level fields, renders portable-text arrays as Markdown, surfaces
+// scalars as labeled key/value lines, and follows resolved references one
+// level deep. The output is "best effort" — not as tight as a hand-written
+// renderer, but feeds the LLM grader real content for any pinned doc type.
+// ---------------------------------------------------------------------------
+function renderScalar(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return null;
+}
+function renderField(key, value, depth = 0) {
+    if (value === null || value === undefined)
+        return null;
+    if (SKIP_FIELDS.has(key))
+        return null;
+    const indent = "  ".repeat(depth);
+    if (isPortableTextArray(value)) {
+        const md = toMarkdown(value);
+        if (!md.trim())
+            return null;
+        return `${indent}**${key}:**\n\n${md}`;
+    }
+    // Sanity slug field: { _type: "slug", current: "…" }
+    if (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value._type === "slug") {
+        const current = value.current;
+        if (typeof current === "string")
+            return `${indent}**${key}:** \`${current}\``;
+        return null;
+    }
+    const scalar = renderScalar(value);
+    if (scalar !== null)
+        return `${indent}**${key}:** ${scalar}`;
+    // Single-level deref: a previously-resolved reference shows up as an
+    // object with its own `_id`/`_type` (the projection joined it in). Walk
+    // its fields one level deep.
+    if (typeof value === "object" &&
+        !Array.isArray(value) &&
+        depth === 0 &&
+        value._id !== undefined) {
+        const inner = Object.entries(value)
+            .map(([k, v]) => renderField(k, v, depth + 1))
+            .filter((line) => line !== null);
+        if (inner.length === 0)
+            return null;
+        return `${indent}**${key}:**\n${inner.join("\n")}`;
+    }
+    if (Array.isArray(value)) {
+        const items = value
+            .map((item, i) => renderField(String(i), item, depth + 1))
+            .filter((line) => line !== null);
+        if (items.length === 0)
+            return null;
+        return `${indent}**${key}:**\n${items.join("\n")}`;
+    }
+    return null;
+}
+function renderDefault(doc) {
+    const title = doc.title ?? `(${doc._type})`;
+    const slug = slugForDoc(doc);
+    const lines = [`## ${title}`, "", `Type: \`${doc._type}\``];
+    if (slug !== `${doc._type}:${doc._id}`)
+        lines.push(`Slug: \`${slug}\``);
+    lines.push("");
+    const fieldLines = [];
+    for (const [key, value] of Object.entries(doc)) {
+        if (key === "title")
+            continue;
+        if (key === "slug" && slug !== `${doc._type}:${doc._id}`)
+            continue;
+        const rendered = renderField(key, value);
+        if (rendered !== null)
+            fieldLines.push(rendered);
+    }
+    if (fieldLines.length > 0) {
+        lines.push(...fieldLines);
+    }
+    else {
+        lines.push("*[no renderable content — all fields were null, framework metadata, or unrecognized shapes]*");
+    }
+    return { content: lines.join("\n"), fidelity: "default", slug };
+}
+function extractDefaultSymbols(doc) {
+    // For unknown types we don't know the doc's intent — but if it has any
+    // Portable Text fields, those probably contain prose-with-inline-code
+    // that names symbols. Walk top-level fields, run the PT extractor on
+    // each PT array, and tag each extracted entry with the originating
+    // field name so reviewers can trace which field a symbol came from.
+    // Returns empty for shapes with no PT content (purely scalar docs like
+    // `marketingPage`); caller falls back to the rendered markdown.
+    const indexes = [];
+    for (const [key, value] of Object.entries(doc)) {
+        if (SKIP_FIELDS.has(key))
+            continue;
+        if (isPortableTextArray(value)) {
+            indexes.push(tagWithFieldName(extractSymbolIndex(value), key));
+        }
+    }
+    return mergeSymbolIndexes(indexes);
+}
+function tagWithFieldName(index, fieldName) {
+    return {
+        symbols: index.symbols.map((entry) => ({
+            symbol: entry.symbol,
+            provenance: {
+                ...entry.provenance,
+                snippet: `[${fieldName}] ${entry.provenance.snippet}`,
+            },
+        })),
+    };
+}
+const defaultRenderer = {
+    render: renderDefault,
+    extractSymbols: extractDefaultSymbols,
+};
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+const BUILT_IN_RENDERERS = {
+    article: articleRenderer,
+    typesReference: typesReferenceRenderer,
+};
+function rendererFor(type) {
+    return BUILT_IN_RENDERERS[type] ?? defaultRenderer;
+}
+/**
+ * Render a document using the registered renderer for its `_type`, falling
+ * back to the default walker. The returned `fidelity` flag tells callers
+ * whether to emit the "info: dedicated renderer would help" log.
+ */
+export async function renderDocument(doc, ctx = {}) {
+    return rendererFor(doc._type).render(doc, ctx);
+}
+/**
+ * Extract a symbol-reference index for a document using its registered
+ * renderer (or the default walker for unknown types). Used by the
+ * grader-context pathway (W0197) to feed the LLM judge a compact
+ * deterministic recognition reference instead of the full rendered doc.
+ *
+ * Returns an empty `SymbolIndex` (`{ symbols: [] }`) when extraction
+ * yields nothing — callers interpret this as the signal to fall back to
+ * the rendered markdown.
+ */
+export async function extractSymbolsForDoc(doc, ctx = {}) {
+    return rendererFor(doc._type).extractSymbols(doc, ctx);
+}
+/** Exported for tests and consumers that want the registered set. */
+export const REGISTERED_RENDERER_TYPES = Object.keys(BUILT_IN_RENDERERS).sort();

package/dist/sanity/queries.d.ts

@@ -20,34 +20,34 @@ export declare const FEATURE_AREA_QUERIES: {
     /**
      * Other Frameworks — Nuxt, React Router/Remix, Astro
      */
-    readonly frameworks: "\n    *[_type == \"article\"\n      && !(_id in path(\"drafts.**\"))\n      && (\n        primarySection._ref in [\n          \"b2c937d0-34b3-435e-818b-d0c8520ea9b8\",\n          \"e223241c-e207-41e0-8e12-f80e78203cf1\",\n          \"73bebb61-e508-42b7-b44b-c4703ae42d01\"\n        ]\n        || (primarySection._ref == \"ea6b80fa-d0d2-4daa-8220-eb8abdcc9deb\"\n            && (title match \"Remix*\" || title match \"Nuxt*\"\n                || title match \"Astro*\" || title match \"SvelteKit*\"))\n      )\n    ] {\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n  ";
+    readonly frameworks: "\n    *[_type == \"article\"\n      && !(_id in path(\"drafts.**\"))\n      && (\n        primarySection._ref in [\n          \"b2c937d0-34b3-435e-818b-d0c8520ea9b8\",\n          \"e223241c-e207-41e0-8e12-f80e78203cf1\",\n          \"73bebb61-e508-42b7-b44b-c4703ae42d01\"\n        ]\n        || (primarySection._ref == \"ea6b80fa-d0d2-4daa-8220-eb8abdcc9deb\"\n            && (title match \"Remix*\" || title match \"Nuxt*\"\n                || title match \"Astro*\" || title match \"SvelteKit*\"))\n      )\n    ] {\n  _id,\n  _type,\n  _rev,\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n  ";
     /**
      * Functions / Compute / AI — serverless functions, webhooks
      * Section: "Compute and AI" (12 articles)
      */
-    readonly functions: "\n    *[_type == \"article\"\n      && primarySection._ref == \"3024ce79-c196-49ee-a237-a327d6a6348f\"\n      && !(_id in path(\"drafts.**\"))\n    ] {\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n  ";
+    readonly functions: "\n    *[_type == \"article\"\n      && primarySection._ref == \"3024ce79-c196-49ee-a237-a327d6a6348f\"\n      && !(_id in path(\"drafts.**\"))\n    ] {\n  _id,\n  _type,\n  _rev,\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n  ";
     /**
      * GROQ Query Language — introduction, syntax, joins, filtering, projections
      * Combines: Content Lake section GROQ articles + Developer Guides articles
      * about querying + title-matched GROQ articles across all sections.
      */
-    readonly groq: "\n    *[_type == \"article\"\n      && !(_id in path(\"drafts.**\"))\n      && (\n        primarySection._ref == \"60a6bcb5-9706-4cab-9153-57725e28f4d0\"\n        || primarySection._ref == \"ea6b80fa-d0d2-4daa-8220-eb8abdcc9deb\"\n      )\n      && (\n        title match \"GROQ*\"\n        || title match \"*GROQ*\"\n        || title match \"Query*\"\n        || title match \"How Queries*\"\n        || slug.current match \"groq-*\"\n        || slug.current match \"query-*\"\n        || slug.current match \"how-queries-*\"\n        || slug.current match \"paginating-with-groq\"\n        || slug.current match \"high-performance-groq\"\n      )\n    ] {\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n  ";
+    readonly groq: "\n    *[_type == \"article\"\n      && !(_id in path(\"drafts.**\"))\n      && (\n        primarySection._ref == \"60a6bcb5-9706-4cab-9153-57725e28f4d0\"\n        || primarySection._ref == \"ea6b80fa-d0d2-4daa-8220-eb8abdcc9deb\"\n      )\n      && (\n        title match \"GROQ*\"\n        || title match \"*GROQ*\"\n        || title match \"Query*\"\n        || title match \"How Queries*\"\n        || slug.current match \"groq-*\"\n        || slug.current match \"query-*\"\n        || slug.current match \"how-queries-*\"\n        || slug.current match \"paginating-with-groq\"\n        || slug.current match \"high-performance-groq\"\n      )\n    ] {\n  _id,\n  _type,\n  _rev,\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n  ";
     /**
      * Next.js integration + Live Content API
      * Combines: Next.js quickstart section + developer-guide articles
      * mentioning Next.js or Live Content.
      */
-    readonly "nextjs-live": "\n    *[_type == \"article\"\n      && !(_id in path(\"drafts.**\"))\n      && (\n        primarySection._ref == \"6208dff1-bba7-487a-a6bb-a0ffccb5846c\"\n        || (primarySection._ref == \"ea6b80fa-d0d2-4daa-8220-eb8abdcc9deb\"\n            && (title match \"Next*\" || title match \"*Live*\"))\n      )\n    ] {\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n  ";
+    readonly "nextjs-live": "\n    *[_type == \"article\"\n      && !(_id in path(\"drafts.**\"))\n      && (\n        primarySection._ref == \"6208dff1-bba7-487a-a6bb-a0ffccb5846c\"\n        || (primarySection._ref == \"ea6b80fa-d0d2-4daa-8220-eb8abdcc9deb\"\n            && (title match \"Next*\" || title match \"*Live*\"))\n      )\n    ] {\n  _id,\n  _type,\n  _rev,\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n  ";
     /**
      * Studio Setup & Customization
      * Section: "Studio" (116 articles)
      */
-    readonly "studio-setup": "\n    *[_type == \"article\"\n      && primarySection._ref == \"d67e3879-0342-4a80-8a2d-e35908df35cc\"\n      && !(_id in path(\"drafts.**\"))\n    ] {\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n  ";
+    readonly "studio-setup": "\n    *[_type == \"article\"\n      && primarySection._ref == \"d67e3879-0342-4a80-8a2d-e35908df35cc\"\n      && !(_id in path(\"drafts.**\"))\n    ] {\n  _id,\n  _type,\n  _rev,\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n  ";
     /**
      * Visual Editing — Presentation tool, overlays, live preview
      * Section: "Visual Editing" (24 articles)
      */
-    readonly "visual-editing": "\n    *[_type == \"article\"\n      && primarySection._ref == \"4e0ef463-01e2-48db-9a31-38b3912ececd\"\n      && !(_id in path(\"drafts.**\"))\n    ] {\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n  ";
+    readonly "visual-editing": "\n    *[_type == \"article\"\n      && primarySection._ref == \"4e0ef463-01e2-48db-9a31-38b3912ececd\"\n      && !(_id in path(\"drafts.**\"))\n    ] {\n  _id,\n  _type,\n  _rev,\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n  ";
 };
 export type FeatureArea = keyof typeof FEATURE_AREA_QUERIES;
 export declare const ALL_FEATURE_AREAS: FeatureArea[];
@@ -55,11 +55,11 @@ export declare const ALL_FEATURE_AREAS: FeatureArea[];
  * Fetch a single article by its slug.
  * Returns the same projection shape as the feature-area queries.
  */
-export declare const ARTICLE_BY_SLUG_QUERY = "\n  *[_type == \"article\"\n    && slug.current == $slug\n    && !(_id in path(\"drafts.**\"))\n  ][0] {\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n";
+export declare const ARTICLE_BY_SLUG_QUERY = "\n  *[_type == \"article\"\n    && slug.current == $slug\n    && !(_id in path(\"drafts.**\"))\n  ][0] {\n  _id,\n  _type,\n  _rev,\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n";
 /**
  * Fetch all published articles (for full-corpus generation).
  */
-export declare const ALL_ARTICLES_QUERY = "\n  *[_type == \"article\"\n    && !(_id in path(\"drafts.**\"))\n  ] | order(primarySection->slug.current, title) {\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n";
+export declare const ALL_ARTICLES_QUERY = "\n  *[_type == \"article\"\n    && !(_id in path(\"drafts.**\"))\n  ] | order(primarySection->slug.current, title) {\n  _id,\n  _type,\n  _rev,\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n";
 /**
  * Fetch article metadata for a list of slugs.
  *
@@ -76,7 +76,7 @@ export declare const ARTICLES_METADATA_BY_SLUGS_QUERY = "\n  *[_type == \"articl
  *
  * Returns the full article projection for content comparison.
  */
-export declare const ARTICLE_BY_SLUG_WITH_PERSPECTIVE_QUERY = "\n  *[_type == \"article\"\n    && slug.current == $slug\n  ][0] {\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n";
+export declare const ARTICLE_BY_SLUG_WITH_PERSPECTIVE_QUERY = "\n  *[_type == \"article\"\n    && slug.current == $slug\n  ][0] {\n  _id,\n  _type,\n  _rev,\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n";
 /**
  * Fetch articles by their document IDs.
  *
@@ -86,7 +86,28 @@ export declare const ARTICLE_BY_SLUG_WITH_PERSPECTIVE_QUERY = "\n  *[_type == \"
  *
  * @param $ids — array of document ID strings
  */
-export declare const ARTICLES_BY_IDS_QUERY = "\n  *[_type == \"article\"\n    && _id in $ids\n  ] {\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n";
+export declare const ARTICLES_BY_IDS_QUERY = "\n  *[_type == \"article\"\n    && _id in $ids\n  ] {\n  _id,\n  _type,\n  _rev,\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n";
+/**
+ * Fetch arbitrary documents by their `_id` — no `_type` filter.
+ *
+ * Used by id-ref resolution so authors can pin any document type
+ * (`article`, `typesReference`, `marketingPage`, `glossaryEntry`, …),
+ * not just articles. The projection branches on `_type`:
+ *
+ *   - `article` → reuses ARTICLE_PROJECTION's flatten + card-deref shape.
+ *   - `typesReference` → derefs `library` and `latestVersion`, including
+ *     the resolved file asset URL so the renderer can fetch typedoc JSON
+ *     without a follow-up round-trip.
+ *   - default `{...}` → returns the raw document fields, which the
+ *     default walker in `document-renderers.ts` flattens to Markdown.
+ *
+ * Does NOT include the `!(_id in path("drafts.**"))` filter — id-ref
+ * resolution is intentional, drafts are queryable when perspective is
+ * draft-enabled, and authors are expected to pin published `_id`s.
+ *
+ * @param $ids — array of document ID strings
+ */
+export declare const DOCS_BY_IDS_QUERY = "\n  *[_id in $ids] {\n    _id,\n    _type,\n    _system,\n    _createdAt,\n    _updatedAt,\n    _rev,\n    _type == \"article\" => {\n      title,\n      description,\n      \"slug\": slug.current,\n      \"section\": primarySection->{ \"slug\": slug.current, title },\n      \"content\": content[] {\n        _type != \"docsCardCollection\" => { ... },\n        _type == \"docsCardCollection\" => {\n          ...,\n          cards[] {\n            ...,\n            \"resolvedTitle\": reference->title,\n            \"resolvedSlug\": reference->slug.current\n          }\n        }\n      }\n    },\n    _type == \"typesReference\" => {\n      title,\n      autoPublish,\n      \"slug\": slug,\n      \"library\": library->{ _id, _type, title, npmName },\n      \"latestVersion\": latestVersion->{\n        _id,\n        _type,\n        semver,\n        date,\n        \"attachment\": {\n          \"asset\": attachment.asset->{\n            _id,\n            _type,\n            url,\n            originalFilename,\n            mimeType,\n            size,\n            extension\n          }\n        }\n      }\n    },\n    !(_type in [\"article\", \"typesReference\"]) => { ... }\n  }\n";
 /**
  * Fetch a single article by its document ID.
  *
@@ -96,7 +117,7 @@ export declare const ARTICLES_BY_IDS_QUERY = "\n  *[_type == \"article\"\n    &&
  *
  * @param $id — document ID string
  */
-export declare const ARTICLE_BY_ID_QUERY = "\n  *[_type == \"article\"\n    && _id == $id\n  ][0] {\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n";
+export declare const ARTICLE_BY_ID_QUERY = "\n  *[_type == \"article\"\n    && _id == $id\n  ][0] {\n  _id,\n  _type,\n  _rev,\n  title,\n  description,\n  \"slug\": slug.current,\n  \"section\": primarySection->{ \"slug\": slug.current, title },\n  \"content\": content[] {\n    // Pass through all standard blocks unchanged\n    _type != \"docsCardCollection\" => { ... },\n    // Resolve references inside card collections so we get titles/slugs\n    _type == \"docsCardCollection\" => {\n      ...,\n      cards[] {\n        ...,\n        \"resolvedTitle\": reference->title,\n        \"resolvedSlug\": reference->slug.current\n      }\n    }\n  }\n}\n";
 /**
  * Resolve an article slug from a URL path segment.
  *

package/dist/sanity/queries.js

@@ -43,8 +43,15 @@ const SECTION_IDS = {
  * Returns the raw Portable Text `content` array so that the Node-side
  * converter (@portabletext/markdown) can produce well-structured Markdown
  * with headings, code fences, tables, callouts, etc.
+ *
+ * `_id`, `_type`, and `_rev` are projected so a result satisfies the
+ * `DocumentForRender` shape and can dispatch through the renderer
+ * registry uniformly with id-ref-resolved docs (W0197).
  */
 const ARTICLE_PROJECTION = `{
+  _id,
+  _type,
+  _rev,
   title,
   description,
   "slug": slug.current,
@@ -229,6 +236,77 @@ export const ARTICLES_BY_IDS_QUERY = `
     && _id in $ids
   ] ${ARTICLE_PROJECTION}
 `;
+/**
+ * Fetch arbitrary documents by their `_id` — no `_type` filter.
+ *
+ * Used by id-ref resolution so authors can pin any document type
+ * (`article`, `typesReference`, `marketingPage`, `glossaryEntry`, …),
+ * not just articles. The projection branches on `_type`:
+ *
+ *   - `article` → reuses ARTICLE_PROJECTION's flatten + card-deref shape.
+ *   - `typesReference` → derefs `library` and `latestVersion`, including
+ *     the resolved file asset URL so the renderer can fetch typedoc JSON
+ *     without a follow-up round-trip.
+ *   - default `{...}` → returns the raw document fields, which the
+ *     default walker in `document-renderers.ts` flattens to Markdown.
+ *
+ * Does NOT include the `!(_id in path("drafts.**"))` filter — id-ref
+ * resolution is intentional, drafts are queryable when perspective is
+ * draft-enabled, and authors are expected to pin published `_id`s.
+ *
+ * @param $ids — array of document ID strings
+ */
+export const DOCS_BY_IDS_QUERY = `
+  *[_id in $ids] {
+    _id,
+    _type,
+    _system,
+    _createdAt,
+    _updatedAt,
+    _rev,
+    _type == "article" => {
+      title,
+      description,
+      "slug": slug.current,
+      "section": primarySection->{ "slug": slug.current, title },
+      "content": content[] {
+        _type != "docsCardCollection" => { ... },
+        _type == "docsCardCollection" => {
+          ...,
+          cards[] {
+            ...,
+            "resolvedTitle": reference->title,
+            "resolvedSlug": reference->slug.current
+          }
+        }
+      }
+    },
+    _type == "typesReference" => {
+      title,
+      autoPublish,
+      "slug": slug,
+      "library": library->{ _id, _type, title, npmName },
+      "latestVersion": latestVersion->{
+        _id,
+        _type,
+        semver,
+        date,
+        "attachment": {
+          "asset": attachment.asset->{
+            _id,
+            _type,
+            url,
+            originalFilename,
+            mimeType,
+            size,
+            extension
+          }
+        }
+      }
+    },
+    !(_type in ["article", "typesReference"]) => { ... }
+  }
+`;
 /**
  * Fetch a single article by its document ID.
  *

package/dist/sanity/symbol-index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * symbol-index — Programmatic extractor that produces a flat list of
+ * identifiers the canonical reference legitimizes, each with a one-line
+ * provenance snippet.
+ *
+ * Used by the grader-context pathway (W0196 / W0197) so the LLM judge sees
+ * a compact, deterministic recognition reference instead of the full
+ * narrative doc — addresses the DOC-2117 prior-collision failure mode
+ * where a grader claimed `useEditDocument` did not exist.
+ *
+ * Two upstream sources, both fully programmatic (no LLM in the extractor):
+ *
+ *   - `extractSymbolIndex(blocks)` — walks Sanity Portable Text content
+ *     (article docs).
+ *   - `extractSymbolsFromTypedoc(json, packageName)` — parses typedoc
+ *     JSON (typesReference docs).
+ *
+ * `mergeSymbolIndexes(indexes)` combines indexes from multiple references
+ * into a single deduped index for a task.
+ *
+ * Source precedence (higher wins on dedup):
+ *   1. type-def      — typedoc declarations: literal authoritative type
+ *                      surface, no editorial layer between extracted
+ *                      symbol and the package's actual exports.
+ *   2. heading       — Section headings (`block` style h1..h4), including
+ *                      inline `code` marks within heading spans.
+ *   3. inline-code   — Inline `code` marks within non-heading `block` spans.
+ *   4. code-block    — Identifiers from `import` statements in `codeBlock`
+ *                      bodies. Body identifiers (`const foo = ...`) are
+ *                      intentionally not extracted — those are usage demos.
+ */
+export type SymbolProvenanceKind = "type-def" | "heading" | "inline-code" | "code-block";
+/** Declaration kinds we surface from typedoc JSON for `type-def` provenance. */
+export type TypeDefDeclarationKind = "function" | "class" | "interface" | "type" | "enum" | "variable" | "namespace";
+export interface SymbolProvenance {
+    kind: SymbolProvenanceKind;
+    /** Human-readable line that locates the symbol in the source doc. */
+    snippet: string;
+    /** Heading style when kind === "heading". */
+    style?: "h1" | "h2" | "h3" | "h4";
+    /** Source filename when kind === "code-block" and one is set on the block. */
+    filename?: string;
+    /** Code block language tag when kind === "code-block". */
+    language?: string;
+    /** Declaration kind when kind === "type-def". */
+    declarationKind?: TypeDefDeclarationKind;
+    /** Source package (e.g. `@sanity/sdk-react`) when kind === "type-def". */
+    package?: string;
+}
+export interface SymbolEntry {
+    symbol: string;
+    provenance: SymbolProvenance;
+}
+export interface SymbolIndex {
+    symbols: SymbolEntry[];
+}
+export declare function extractSymbolIndex(blocks: unknown): SymbolIndex;
+/**
+ * Extract a symbol index from a typedoc JSON document (schema 2.x — the
+ * shape produced by `typedoc --json`). Each top-level export becomes a
+ * `type-def` provenance entry with the symbol name, declaration kind
+ * (function / interface / type / etc.), and the JSDoc summary as snippet.
+ *
+ * Type-def is the highest-precedence source: typedoc declarations are
+ * literal authoritative type surface, no editorial layer between them
+ * and the package's actual exports. If a symbol also appears in narrative
+ * docs (heading, inline code, code-block import) the type-def entry wins
+ * on dedup.
+ *
+ * `body` is the raw JSON string fetched from the typesReference's
+ * attachment URL. Returns an empty index for any unparseable input — this
+ * is best-effort recognition material; callers fall back to full-doc
+ * injection when extraction yields nothing.
+ */
+export declare function extractSymbolsFromTypedoc(body: string, packageName?: string): SymbolIndex;
+/**
+ * Compute per-tier counts for a SymbolIndex. Used by the fetcher to
+ * populate the per-task manifest entry's `tierBreakdown` field.
+ */
+export declare function symbolIndexTierBreakdown(index: SymbolIndex): {
+    typeDef: number;
+    heading: number;
+    inlineCode: number;
+    codeBlock: number;
+};
+/**
+ * Combine multiple `SymbolIndex` instances (typically from different
+ * canonical references for the same task) into a single deduped index
+ * preserving precedence.
+ */
+export declare function mergeSymbolIndexes(indexes: readonly SymbolIndex[]): SymbolIndex;
+/**
+ * Render a SymbolIndex as a compact markdown reference suitable for
+ * injection into a grader's `rubricPrompt` as ground-truth recognition
+ * material. Layout intentionally puts headings first so the most
+ * authoritative symbols anchor the top of the list.
+ */
+export declare function renderSymbolIndex(index: SymbolIndex, title?: string): string;