docs: collision-safe placeholder restoration in markdown protectors

Sequential per-token replace could corrupt output when protected code
literally contained sentinel-looking text. Both protectors now use
PUA-character delimiters lengthened deterministically until absent
from the input, with a single-pass regex restore, and the guard gains
a protector round-trip check with adversarial inputs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: ankur-arch

apps/docs/scripts/lint-agent-ready.ts

@@ -21,6 +21,7 @@ import { fileURLToPath } from "node:url";
 const { source } = await import("@/lib/source");
 const llms = await import("@/lib/llms");
 const { getLLMText } = await import("@/lib/get-llm-text");
+const { protectFencedCodeBlocks, protectInlineCode } = await import("@/lib/llm-markdown");
 const { withDocsBasePath } = await import("@/lib/urls");
 const { agentSkillMarkdown } = await import("@/lib/agent-skill");
 const { mcpDiscoveryDocument } = await import("@/lib/mcp-discovery");
@@ -368,6 +369,74 @@ if (mcpErrors.length > 0) {
   );
 }
 
+// ── Check 10: placeholder protectors are collision-safe ──────────────────────
+// Regression coverage for the protect/restore pipeline shared by llm-markdown.ts
+// and get-llm-text.ts. Adversarial inputs embed text that LOOKS like the internal
+// placeholders inside inline code and fenced blocks, plus a normal body link. A
+// correct implementation restores every input byte-for-byte and rewrites ONLY the
+// body links that sit outside code. This guards against the old sequential-replace
+// corruption (a protected span reintroducing a later token; the fenced restore
+// consuming a sentinel reintroduced by an inline span).
+{
+  // Mirror absolutizeInBodyLinks exactly: fences first, then inline spans, rewrite
+  // the body links in between, then restore inline then fences.
+  const runPipeline = (markdown: string) => {
+    const fences = protectFencedCodeBlocks(markdown);
+    const inline = protectInlineCode(fences.markdown);
+    const rewritten = inline.markdown.replace(/\]\((\/[^)\s]*)\)/g, (full, target: string) => {
+      if (target.startsWith("//")) return full;
+      return `](https://www.prisma.io${target})`;
+    });
+    return fences.restore(inline.restore(rewritten));
+  };
+
+  const fence = "```";
+  const cases: { name: string; input: string; expected: string }[] = [
+    {
+      name: "inline code containing old-format placeholder text is preserved",
+      input: "Use `__LLM_INLINE_CODE_1__` and `__LLM_FENCED_CODE_BLOCK_0__` literally here.",
+      expected: "Use `__LLM_INLINE_CODE_1__` and `__LLM_FENCED_CODE_BLOCK_0__` literally here.",
+    },
+    {
+      name: "fenced block containing inline-sentinel-looking text + body link is preserved",
+      input: `${fence}\n__LLM_INLINE_CODE_0__ and [x](/orm/a)\n${fence}`,
+      expected: `${fence}\n__LLM_INLINE_CODE_0__ and [x](/orm/a)\n${fence}`,
+    },
+    {
+      name: "link inside inline code is NOT rewritten",
+      input: "See `[label](/orm/foo)` inline.",
+      expected: "See `[label](/orm/foo)` inline.",
+    },
+    {
+      name: "body link outside code IS rewritten",
+      input: "See [label](/orm/foo) here.",
+      expected: "See [label](https://www.prisma.io/orm/foo) here.",
+    },
+    {
+      name: "mixed: body link rewrites while placeholder-looking code stays verbatim",
+      input: `Body [a](/x) then \`__LLM_FENCED_CODE_BLOCK_0__\` then\n${fence}\ncode [b](/y)\n${fence}\nend.`,
+      expected: `Body [a](https://www.prisma.io/x) then \`__LLM_FENCED_CODE_BLOCK_0__\` then\n${fence}\ncode [b](/y)\n${fence}\nend.`,
+    },
+  ];
+
+  const protectorFailures = cases.flatMap((testCase) => {
+    const actual = runPipeline(testCase.input);
+    if (actual === testCase.expected) return [];
+    return [
+      `${testCase.name}\n      expected: ${JSON.stringify(testCase.expected)}\n      actual:   ${JSON.stringify(actual)}`,
+    ];
+  });
+
+  if (protectorFailures.length > 0) {
+    fail(
+      "Protector round-trip",
+      `${protectorFailures.length} of ${cases.length} case(s) failed:\n    ${protectorFailures.join("\n    ")}`,
+    );
+  } else {
+    pass("Protector round-trip", `all ${cases.length} adversarial protect/restore cases pass`);
+  }
+}
+
 // ── Report ───────────────────────────────────────────────────────────────────
 const icon: Record<Status, string> = { pass: "✓", warn: "⚠", fail: "✗" };
 console.log("\nAgent-readiness checks\n");

apps/docs/src/lib/llm-markdown.ts

@@ -374,12 +374,50 @@ function replaceComponentBlocks(
   return result;
 }
 
+// Base sentinel delimiter built from Unicode Private Use Area characters, which
+// cannot legitimately appear in MDX source. Real placeholder text a page might
+// discuss (e.g. `__LLM_INLINE_CODE_1__`) can never look like one of these
+// tokens, so protected content is never mistaken for a placeholder.
+const SENTINEL_DELIMITER = "\uE000\uE001";
+
+function escapeRegExp(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Builds a collision-free placeholder scheme for one protector.
+ *
+ * The delimiter starts from PUA characters that cannot appear in MDX source and
+ * is lengthened deterministically until it is guaranteed absent from `input`, so
+ * a token can never collide with real content — including content that literally
+ * spells out one of these placeholders. `label` keeps the two protectors' tokens
+ * distinct so restoring one protector never touches the other's placeholders
+ * (cross-protector safety). `restore` performs a single left-to-right pass and so
+ * never rescans already-substituted content, which removes the corruption that a
+ * sequential per-token replace loop could introduce.
+ */
+function createProtector(input: string, label: string) {
+  let delimiter = SENTINEL_DELIMITER;
+  while (input.includes(delimiter)) delimiter += "\uE000";
+
+  const boundary = escapeRegExp(delimiter);
+  const pattern = new RegExp(`${boundary}${label}_(\\d+)${boundary}`, "g");
+
+  return {
+    token: (index: number) => `${delimiter}${label}_${index}${delimiter}`,
+    restore(value: string, blocks: readonly string[]) {
+      return value.replace(pattern, (match, index: string) => blocks[Number(index)] ?? match);
+    },
+  };
+}
+
 export function protectFencedCodeBlocks(markdown: string) {
   const blocks: string[] = [];
+  const protector = createProtector(markdown, "LLM_FENCED_CODE_BLOCK");
   const protectedMarkdown = markdown.replace(
     /^([ \t]*)([`~]{3,})[^\n]*\n[\s\S]*?^\1\2\s*$/gm,
     (match) => {
-      const token = `__LLM_FENCED_CODE_BLOCK_${blocks.length}__`;
+      const token = protector.token(blocks.length);
       blocks.push(match);
       return token;
     },
@@ -388,10 +426,7 @@ export function protectFencedCodeBlocks(markdown: string) {
   return {
     markdown: protectedMarkdown,
     restore(value: string) {
-      return blocks.reduce(
-        (text, block, index) => text.replace(`__LLM_FENCED_CODE_BLOCK_${index}__`, block),
-        value,
-      );
+      return protector.restore(value, blocks);
     },
   };
 }
@@ -405,19 +440,17 @@ export function protectFencedCodeBlocks(markdown: string) {
  */
 export function protectInlineCode(markdown: string) {
   const spans: string[] = [];
+  const protector = createProtector(markdown, "LLM_INLINE_CODE");
   const protectedMarkdown = markdown.replace(/(`+)[^\n]+?\1/g, (match) => {
-    const token = `__LLM_INLINE_CODE_${spans.length}__`;
+    const token = protector.token(spans.length);
     spans.push(match);
     return token;
   });
 
   return {
     markdown: protectedMarkdown,
     restore(value: string) {
-      return spans.reduce(
-        (text, span, index) => text.replace(`__LLM_INLINE_CODE_${index}__`, span),
-        value,
-      );
+      return protector.restore(value, spans);
     },
   };
 }