D4: decide the caching strategy per public surface — ADR (#234)

[xenodeve]

Part of #234 · PRD: docs/prd/2026-07-26-public-read-latency-and-cache-strategy.md (D4)

This is a decision, not an implementation. It is ready-for-human on the one question that is genuinely not mine to settle.

EN

#238–#240 make /projects sub-second while it stays a dynamic route. What they cannot do is make it CDN-class (/faq serves in 0.07–0.11 s without invoking a function), because HTML is still rendered per request. Getting there requires one of two hard-to-reverse changes, and choosing between them is what this issue is for.

Option A — cacheComponents: true. Next 16 removed experimental.ppr; this is the only opt-in that lets a searchParams page have a prerendered static shell with the dynamic part streamed. It changes caching semantics app-wide, so every page needs auditing, and 'use cache'/'use cache: remote' become meaningful only alongside a cacheHandlers durable store (cacheHandlers.md:24,66).

Option B — per-filter prerendered routes. e.g. /projects/c/[category] with generateStaticParams, keeping /projects prerendered for the unfiltered list, plus redirects so existing ?category=… links keep working. Cannot cover q (free-text search) at all, and category × tag × tech is combinatorial — so it is a partial fix by construction.

Option C — accept dynamic. Sub-second from #238–#240 is enough; spend the effort elsewhere.

The ADR must also settle the surfaces this touches beyond /projects: /blog has the identical searchParams shape and is also uncached (0.65 s measured), and /projects/[slug] reads the DB per request too.

Acceptance criteria

• an ADR records the caching strategy per public surface — which pages are static, which are ISR and with what window, which are deliberately dynamic and why
• the ADR states how the choice interacts with ADR 0004's on-demand revalidation and ADR 0014's three cache layers, including that Cloudflare "Cache Everything" stays rejected
• the decision names its failure mode, not just its benefit
• /blog and /projects/[slug] are each either covered by the decision or explicitly listed as out of scope with a reason
• whichever option wins, the follow-up implementation issues are filed from the ADR — not started before it

TH

ส่วนหนึ่งของ #234 · PRD: docs/prd/2026-07-26-public-read-latency-and-cache-strategy.md (D4)

นี่คือการตัดสินใจ ไม่ใช่การ implement เป็น ready-for-human ในคำถามข้อเดียวที่ไม่ใช่เรื่องที่ผมควรตัดสิน

#238–#240 ทำให้ /projects ต่ำกว่า 1 วินาทีขณะที่มันยังเป็น dynamic route สิ่งที่มันทำไม่ได้คือทำให้เป็นระดับ CDN (/faq เสิร์ฟใน 0.07–0.11 วิ โดยไม่เรียก function) เพราะ HTML ยัง render ต่อ request การไปถึงจุดนั้นต้องใช้การเปลี่ยนแปลงที่ย้อนยากหนึ่งในสองแบบ และการเลือกคือเหตุที่ issue นี้มีอยู่

ทางเลือก A — cacheComponents: true Next 16 ถอด experimental.ppr ออก นี่เป็นทางเปิดใช้เดียวที่ทำให้หน้าที่อ่าน searchParams มี static shell ที่ prerender พร้อมสตรีมส่วน dynamic มันเปลี่ยน semantics การแคช ทั้งแอป ฉะนั้นทุกหน้าต้องถูกตรวจ และ 'use cache'/'use cache: remote' จะมีความหมายเฉพาะเมื่อมี cacheHandlers ที่เก็บแบบ durable ควบคู่ (cacheHandlers.md:24,66)

ทางเลือก B — route ที่ prerender ต่อตัวกรอง เช่น /projects/c/[category] ด้วย generateStaticParams เก็บ /projects ที่ prerender ไว้สำหรับรายการไม่กรอง บวก redirect เพื่อให้ลิงก์ ?category=… เดิมยังทำงาน มันครอบ q (ค้นหาข้อความอิสระ) ไม่ได้เลย และ category × tag × tech เป็น combinatorial จึงเป็นการแก้บางส่วนโดยโครงสร้าง

ทางเลือก C — ยอมรับว่าเป็น dynamic ต่ำกว่า 1 วินาทีจาก #238–#240 พอแล้ว เอาแรงไปทำอย่างอื่น

ADR ต้องตัดสินผิวสัมผัสอื่นที่เกี่ยวด้วย: /blog มีรูปแบบ searchParams เหมือนกันเป๊ะและไม่ถูกแคชเช่นกัน (วัดได้ 0.65 วิ) และ /projects/[slug] ก็อ่าน DB ต่อ request

เกณฑ์รับงาน

• มี ADR บันทึกกลยุทธ์แคช ต่อผิวสาธารณะ — หน้าไหน static, หน้าไหน ISR และ window เท่าไร, หน้าไหน dynamic โดยเจตนาและเพราะอะไร
• ADR ระบุว่าการเลือกนั้นสัมพันธ์กับ on-demand revalidation ของ ADR 0004 และแคชสามชั้นของ ADR 0014 อย่างไร รวมถึงว่า Cloudflare "Cache Everything" ยังถูกปฏิเสธ
• การตัดสินใจระบุ failure mode ของมัน ไม่ใช่แค่ประโยชน์
• /blog และ /projects/[slug] ถูกครอบด้วยการตัดสินใจ หรือถูกระบุชัดว่าอยู่นอกขอบเขตพร้อมเหตุผล
• ทางเลือกไหนชนะ ให้ยื่น issue implement ตามหลัง ADR — ไม่เริ่มก่อนมันเสร็จ

[xenodeve]

Recommendation for the decision — Option C, with a named revisit trigger

Written after #240's production measurements landed, because the numbers change what this choice is
actually about. This is a recommendation, not the decision — the issue stays ready-for-human.

EN

What the measurement changed

The gap this issue was filed to close is no longer 1.4–1.6 s. Measured on production after #239
(f72c872), warm /projects:

• TTFB p95 0.46 s, median 0.332 s · total p95 0.83 s
• 0 Supabase calls across 16 warm requests — the database is out of the request path entirely

So the remaining distance to /faq's 0.07–0.11 s is roughly 0.33 s of function invocation, not
data access. Options A and B are both priced against that 0.33 s now, not against the original
problem.

Why C

Option A is not a flag, it is a project. Per the vendored docs (cacheHandlers.md:24,66),
'use cache' and 'use cache: remote' fall back to a per-process in-memory LRU unless
cacheHandlers is configured — which on serverless is per-instance and mostly unused (ADR 0014, and
measured here: #207's module memo never reached sub-second). So cacheComponents: true also means
selecting, configuring and operating a durable cache handler, plus auditing every page for changed
caching semantics. That is a large, hard-to-reverse change to buy ~0.33 s.

Option B is partial by construction and permanent. It cannot cover q (free-text), category ×
tag × tech is combinatorial, and it leaves a redirect surface to maintain forever so existing
?category=… links keep working — for a subset of the traffic.

Option C keeps the win and spends nothing. Sub-second warm, the DB no longer touched, freshness
verified at 9 s after an invalidation.

The failure mode of C — stated, per the third AC

C bets that the per-request function invocation stays cheap. It stops being true if: a public page
starts doing substantially more work per request than a cached list read; traffic grows enough that
invocation concurrency, not latency, becomes the constraint; or the Data Cache read itself slows.
Concrete revisit trigger: warm p95 for /projects back above 1 s, measured the same way as #240.
Without a trigger, "accept dynamic" quietly becomes "never look again", which is the real risk here.

Two things the ADR should carry regardless of which option wins

1. /blog has the identical shape and has not been fixed — dynamic in the build output, reading
   the DB per request. The D1: cache the unfiltered project list durably — never cache a failure (#234) #238/D2: bust the project cache tag from every writer — backend route and admin actions (#234) #239 pattern (durable cache on the unfiltered read + tag bust from
   every writer) applies to it unchanged and is independent of A/B/C. Worth being an implementation
   issue filed from the ADR.
2. /projects/[slug] is already ● SSG with a 1 m ISR window in the build output and reads via
   the uncached, untagged getProjectBySlug. It is not part of this problem; listing it as
   explicitly out of scope with that reason satisfies the fourth AC without any work.

One measured fact that is independent of this decision

The cache refill still costs 3.45 s because 0032/0033 are unapplied — every miss pays
three failing column-ladder selects before the one that works. Whichever option wins, applying those
migrations removes that cost. It needs the developer's explicit per-action authorization.

TH

สิ่งที่การวัดเปลี่ยนไป

ช่องว่างที่ issue นี้ถูกเปิดเพื่อปิดไม่ใช่ 1.4–1.6 วินาทีอีกต่อไป วัดบน production หลัง #239
(f72c872) สำหรับ /projects ตอน warm:

• TTFB p95 0.46 วิ มัธยฐาน 0.332 วิ · total p95 0.83 วิ
• เรียก Supabase 0 ครั้งใน 16 request ตอน warm — ฐานข้อมูลออกจากเส้นทาง request ไปแล้วทั้งหมด

ฉะนั้นระยะที่เหลือไปถึง 0.07–0.11 วิของ /faq คือประมาณ 0.33 วินาทีของการเรียก function
ไม่ใช่การเข้าถึงข้อมูล ทางเลือก A และ B ถูกตีราคาเทียบกับ 0.33 วินาทีนั้น ไม่ใช่เทียบกับปัญหาเดิม

ทำไมถึงเป็น C

ทางเลือก A ไม่ใช่แค่การเปิด flag แต่เป็นโปรเจกต์ ตาม docs ที่ vendor ไว้ (cacheHandlers.md:24,66)
ทั้ง 'use cache' และ 'use cache: remote' ถอยไปเป็น in-memory LRU ต่อ process ถ้าไม่ได้ตั้ง
cacheHandlers ซึ่งบน serverless คือต่อ instance และแทบไม่ถูกใช้ (ADR 0014 และวัดมาแล้วที่นี่: memo
ระดับ module ของ #207 ไม่เคยถึง sub-second) ฉะนั้น cacheComponents: true ยังหมายถึงการเลือก ตั้งค่า
และดูแล cache handler ที่ durable บวกกับการตรวจทุกหน้าเพราะ semantics การแคชเปลี่ยน นั่นคือการเปลี่ยน
ที่ใหญ่และย้อนยากเพื่อซื้อ ~0.33 วินาที

ทางเลือก B เป็นการแก้บางส่วนโดยโครงสร้างและอยู่ถาวร มันครอบ q (ข้อความอิสระ) ไม่ได้
category × tag × tech เป็น combinatorial และทิ้ง redirect ไว้ให้ดูแลตลอดไปเพื่อให้ลิงก์ ?category=…
เดิมยังทำงาน — เพื่อทราฟฟิกแค่ส่วนหนึ่ง

ทางเลือก C เก็บผลที่ได้ไว้และไม่ต้องจ่ายอะไร warm ต่ำกว่า 1 วินาที ไม่แตะฐานข้อมูลแล้ว และความสด
ยืนยันแล้วที่ 9 วินาทีหลังการ invalidate

โหมดความล้มเหลวของ C — ระบุไว้ ตามเกณฑ์ข้อที่สาม

C เดิมพันว่าการเรียก function ต่อ request จะยังถูก มันจะไม่จริงเมื่อ: หน้าสาธารณะเริ่มทำงานต่อ request
มากกว่าการอ่านรายการที่แคชไว้อย่างมีนัย, ทราฟฟิกโตจนข้อจำกัดกลายเป็น concurrency ของการเรียก ไม่ใช่
เวลา, หรือการอ่าน Data Cache เองช้าลง ทริกเกอร์ให้กลับมาทบทวนที่เป็นรูปธรรม: p95 ตอน warm ของ
/projects กลับขึ้นเกิน 1 วินาที วัดด้วยวิธีเดียวกับ #240 ถ้าไม่มีทริกเกอร์ "ยอมรับว่าเป็น dynamic"
จะกลายเป็น "ไม่กลับมาดูอีกเลย" อย่างเงียบ ๆ ซึ่งคือความเสี่ยงจริงตรงนี้

สองอย่างที่ ADR ควรมี ไม่ว่าทางเลือกไหนจะชนะ

1. /blog มีรูปร่างเหมือนกันเป๊ะและยังไม่ถูกแก้ — เป็น dynamic ในผลลัพธ์ build และอ่านฐานข้อมูล
   ทุก request แพตเทิร์นของ D1: cache the unfiltered project list durably — never cache a failure (#234) #238/D2: bust the project cache tag from every writer — backend route and admin actions (#234) #239 (แคชแบบ durable บนการอ่านที่ไม่กรอง + ล้าง tag จากทุกตัวเขียน)
   ใช้กับมันได้ตรง ๆ และเป็นอิสระจาก A/B/C ควรเป็น issue implementation ที่เปิดจาก ADR
2. /projects/[slug] เป็น ● SSG พร้อมหน้าต่าง ISR 1 นาที อยู่แล้วในผลลัพธ์ build และอ่านผ่าน
   getProjectBySlug ที่ไม่แคชและไม่มี tag มันไม่ใช่ส่วนหนึ่งของปัญหานี้ การระบุว่าอยู่นอกขอบเขต
   พร้อมเหตุผลนั้นทำให้เกณฑ์ข้อที่สี่ครบโดยไม่ต้องทำงานเพิ่ม

ข้อเท็จจริงที่วัดได้หนึ่งข้อซึ่งเป็นอิสระจากการตัดสินใจนี้

การเติมแคช ยังใช้ 3.45 วินาที เพราะ 0032/0033 ยังไม่ถูก apply — ทุก miss จ่าย select ที่ล้ม
สามครั้งของบันไดคอลัมน์ก่อนถึงอันที่ใช้ได้ ไม่ว่าทางเลือกไหนชนะ การ apply migration เหล่านั้นจะเอา
ต้นทุนนั้นออก มันต้องการการอนุญาตเฉพาะการกระทำนั้นจากผู้พัฒนา