Rendering and caching architecture on top of Convex

[vdvman1]

Question

How do pages render and cache, once Convex is the source of truth?

Settled going in: PPR. Article body and inline annotations are static; other annotations and comment threads are live Convex islands. Promoting an annotation invalidates the article's cache entry. /java/changelog keeps its stable URL — no redirect to a concrete version — with cron-driven invalidation keeping it correct. Inline content is never live, so nothing shifts under a reader. Old articles should behave essentially like static pages.

Decide:

• The static/dynamic boundary, concretely, per component. Which parts of src/components/java/patch-notes.tsx and src/app/java/changelog/layout.tsx sit in the static shell and which become dynamic islands.
• Per-article cache lifetimes. A two-year-old article should cache near-permanently; the newest should revalidate fast. Express this with cache components primitives — this is the requirement that motivated the whole map.
• Invalidation from Convex. The cron and the promote-annotation mutation both live outside Next. How do they invalidate a Vercel cache entry — tagged revalidation via a route handler, a webhook, something else? What is the auth on that endpoint, and what is the latency?
• /java/changelog specifically. Retire the force-dynamic hack at src/app/java/changelog/page.tsx:8 and explain why the replacement is correct, in terms of the ISR mis-detection diagnosed in Java Changlogs caching too strongly #4. This is the ticket that closes that loop.
• The version sidebar, which is live (new versions appear without a refresh) but sits in a layout wrapping cached pages.
• The three liveness behaviours from the map: revision-change notice plus annotation write-lock; live sidebar; live comments. Where each one's subscription lives.
• Server vs client Convex access. What is read server-side at render (cached) vs subscribed client-side (live), and how the client knows which article revision the static shell was built from — that comparison is what drives the "new version available" notice.
• What gets deleted. The cache wrapper in src/lib/fetch.ts and request-time fetching in src/server/java/versions.ts, once ingestion is authoritative.

Blocked on the cache components research, the Next 16.3 upgrade, and the article schema.

[vdvman1]

Constraints added from #30 (cache components research). These sharpen this ticket considerably — read the full write-up before deciding: docs/research/cache-components-nextjs-16-3.md

A decision this ticket now has to make that the map didn't anticipate:

• Durability costs money. Plain use cache is ephemeral in-memory, per-instance, and wiped on every deploy — it is a prerender declaration, not a durable cache. Durable caching means use cache: remote, which is billed Vercel Runtime Cache and carries a silent 2 MB per-entry ceiling. For an open-source project with no income this is a real trade-off: pay for the remote tier, accept cold caches after every deploy, or lean on Convex as the durable layer and treat Next's cache as a thin prerender. Decide this explicitly. Note unstable_cache retains one property no use cache variant has — persistence across deploys.

Hard constraints:

• cacheComponents makes export const dynamic, revalidate, fetchCache, dynamicParams and runtime = 'edge' build errors. There are two force-dynamic exports in the repo: src/app/java/changelog/page.tsx:9 (the hack this map removes) and src/app/about/advanced/page.tsx:12 (legitimate — it reads runtime env vars and must not be statically built). Both need a new idiom.
• dynamicParams is gone and generateStaticParams cannot return [], so /java/changelog/[version] must prerender a subset and rely on 16.3's App Shell upgrade — which also needs partialPrefetching: true.
• Bots get no static shell — crawlers render the full page at request time. This is a public reference site, so weigh it.
• Node runtime only. cacheComponents is a top-level flag, not under experimental.

Good news for this ticket's core requirement: per-article cache lifetimes are fully supported via a runtime-computed inline cacheLife object, so "old articles cached near-permanently, newest revalidates fast" is directly expressible. cacheLife('max') is 1 year, not forever.

Invalidation from Convex: the cron should call Vercel's REST API POST /v1/edge-cache/invalidate-by-tags directly — no Next.js code needed, purges CDN + Runtime + Data cache, ~300 ms global propagation, lazy/stale-while-revalidate rather than read-your-writes. A route handler calling revalidateTag(tag, 'max') is the alternative (the one-arg form is deprecated). For annotation promotion, updateTag is the right primitive — but it is Server-Action-only, so it is available to promotion and not to the cron.

Two silent-wrong-answer hazards, verified against shipped source rather than docs:

1. Non-serializable arguments are excluded from the cache key rather than rejected — distinct inputs collide on one entry.
2. Repeated cacheLife calls take the minimum of each field, not the last value.

Serialization across a use cache boundary is RSC/Flight and asymmetric; class instances and URL are unsupported — relevant to #35.

[vdvman1]

Constraints added from #35 (ZodError cache boundary research). Full write-up: docs/research/zoderror-cache-boundary.md

Relevant to this ticket's "What gets deleted" scope:

• The superjson wrapper is load-bearing for Date, not just ZodError. VERSION_MANIFEST_ENTRY_SCHEMA transforms date into a real Date, and version sorting depends on it. Removing superjson while still using unstable_cache would break version ordering silently. Delete the wrapper only together with the request-time fetch path, not before.
• fetchAndParseErrToString (src/lib/fetch.ts:52-73) has zero call sites — dead code, safe to delete outright.
• The ZodError-across-a-boundary problem itself dissolves post-cutover; there is nothing to port or reimplement here.