What was measured
Every Open Graph card URL this site emits ends in a marker segment — /og/docs/<slug...>/image.png — produced by getPageImage() in apps/docs/lib/source.ts:
constsegments=[...page.slugs,'image.png'];
That marker is load-bearing in two independent ways, and only the first is discoverable from the code:
app/og/docs/[...slug]/route.tsx resolves the page with source.getPage(slug.slice(0, -1)) — the marker is the sacrificial segment that slice discards.- Its dot is what keeps the URL out of the locale rewriter.
apps/docs/proxy.ts's matcher is '/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)' — it excludes any path containing a dot. A marker without one is rewritten to /en/og/docs/..., which is not a route.
Measured against next dev on main + PR #12325:
/og/docs/ai/agents -> 404 text/html (no dot anywhere in the path)
/en/og/docs/ai/agents -> 404 text/html (where proxy.ts rewrites it to)
/og/docs/ai/agents/x.png -> 200 image/png (marker name is irrelevant)
/og/docs/ai/agents/image.png -> 200 image/png
So the marker's name does not matter, but the presence of a final segment containing a dot does. Nothing in lib/source.ts, proxy.ts or the OG route records this. grep -rn 'image.png' apps/docs reaches only the one line that writes it.
Why it matters now and did not before
Until PR #12325 the cards were generated and referenced by nobody (#12235), so a broken card URL was invisible by construction. That PR makes all 403 of them the og:image of a real page. A change to either side of this coupling — renaming the marker to something without a dot, or widening proxy.ts's matcher — now takes the whole card surface to 404 at once, and a 404ing og:image is worse than none: crawlers fall back to scraping whatever else the page offers. Neither side's tests or gates would notice; the failure is a 404 on an asset no test fetches.
Note that proxy.ts has already been ruled not a legitimate surface to widen (recorded on #12233, because widening it would 404 /llms.txt, /llms-full.txt, /og/** and /docs/**.mdx). This finding is the same invariant seen from the other end, and it is currently protected only by that ruling living in an issue comment.
Shape of a fix (not proposed, just scoped)
Cheapest honest option is a comment on both sides naming the other. A mechanical option is a gate asserting that the URL getPageImage() builds has a final segment containing a dot, and that proxy.ts's matcher still excludes dotted paths — the existing check:docs-locale-catch-all already asserts the second half (dotted paths bypass proxy.ts: true), so the missing half is the link between the two.
Source
Fallout of a reverse verification run while implementing #12235 (PR #12325), under epic #12243. Filed unassigned and observation-class: this is a missing guard around a currently-correct invariant, not a live defect.
What was measured
Every Open Graph card URL this site emits ends in a marker segment —
/og/docs/<slug...>/image.png— produced bygetPageImage()inapps/docs/lib/source.ts:That marker is load-bearing in two independent ways, and only the first is discoverable from the code:
app/og/docs/[...slug]/route.tsxresolves the page withsource.getPage(slug.slice(0, -1))— the marker is the sacrificial segment that slice discards.apps/docs/proxy.ts's matcher is'/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)'— it excludes any path containing a dot. A marker without one is rewritten to/en/og/docs/..., which is not a route.Measured against
next devonmain+ PR #12325:So the marker's name does not matter, but the presence of a final segment containing a dot does. Nothing in
lib/source.ts,proxy.tsor the OG route records this.grep -rn 'image.png' apps/docsreaches only the one line that writes it.Why it matters now and did not before
Until PR #12325 the cards were generated and referenced by nobody (#12235), so a broken card URL was invisible by construction. That PR makes all 403 of them the
og:imageof a real page. A change to either side of this coupling — renaming the marker to something without a dot, or wideningproxy.ts's matcher — now takes the whole card surface to 404 at once, and a 404ingog:imageis worse than none: crawlers fall back to scraping whatever else the page offers. Neither side's tests or gates would notice; the failure is a 404 on an asset no test fetches.Note that
proxy.tshas already been ruled not a legitimate surface to widen (recorded on #12233, because widening it would 404/llms.txt,/llms-full.txt,/og/**and/docs/**.mdx). This finding is the same invariant seen from the other end, and it is currently protected only by that ruling living in an issue comment.Shape of a fix (not proposed, just scoped)
Cheapest honest option is a comment on both sides naming the other. A mechanical option is a gate asserting that the URL
getPageImage()builds has a final segment containing a dot, and thatproxy.ts's matcher still excludes dotted paths — the existingcheck:docs-locale-catch-allalready asserts the second half (dotted paths bypass proxy.ts: true), so the missing half is the link between the two.Source
Fallout of a reverse verification run while implementing #12235 (PR #12325), under epic #12243. Filed unassigned and observation-class: this is a missing guard around a currently-correct invariant, not a live defect.