D3: prove the cache skips the DB read and keeps freshness — on production (#234)

[xenodeve]

Part of #234 · PRD: docs/prd/2026-07-26-public-read-latency-and-cache-strategy.md (D3) · depends on #238, #239

EN

Prove on production that the cache does what it claims. This slice exists because the previous attempt at this problem (#207, shipped in #233) produced a better number while the underlying work still happened on every request — a per-process memo took /projects from 3.2–3.7 s to 1.4–1.6 s and was mistaken for progress toward sub-second until it was measured properly.

A faster number is not evidence. Two things must be shown separately:

1. The read was skipped, not merely faster. A warm request must demonstrably not reach Supabase.
2. Freshness still holds. A write must appear well inside the ≤10-minute target.

Also worth settling here, because it is currently an assertion rather than a measurement: three independent agents stated that unstable_cache on Vercel is backed by a durable cross-invocation Data Cache rather than per-process memory. That is consistent with the Next docs ("persist the result across requests and deployments") but has not been verified on this deployment. If it turns out not to hold, #238's fallback keeps the page correct and the whole approach collapses back to #234's D4 decision.

Acceptance criteria

• evidence that a warm request does not query Supabase (query log, an added counter, or an equivalent observation) — not a latency figure
• warm p95 for /projects under 1 s, measured on production with the number recorded here
• cache durability across invocations verified explicitly, or its failure recorded as a finding
• a post-write probe: mutate → trigger revalidation → the next request shows the change, well under 10 minutes
• x-vercel-cache is expected to stay MISS — the route is still dynamic. State that plainly so the result is not read as a failure
• the measured numbers are posted on perf(projects): /projects and /blog are dynamic because they read searchParams — and no ADR records the caching strategy #234 and in the ledger, replacing the estimates

TH

ส่วนหนึ่งของ #234 · PRD: docs/prd/2026-07-26-public-read-latency-and-cache-strategy.md (D3) · ขึ้นกับ #238, #239

พิสูจน์บน production ว่าแคชทำสิ่งที่มันอ้าง slice นี้มีอยู่เพราะความพยายามครั้งก่อนกับปัญหานี้ (#207 ship ใน #233) ให้ ตัวเลขที่ดีขึ้น ขณะที่งานเบื้องหลังยังเกิดทุก request — memo ต่อ process ทำ /projects จาก 3.2–3.7 วิ เหลือ 1.4–1.6 วิ และถูกเข้าใจว่าเป็นความคืบหน้าไปสู่ sub-second จนกระทั่งวัดอย่างถูกต้อง

ตัวเลขที่เร็วขึ้นไม่ใช่หลักฐาน ต้องแสดงสองอย่างแยกกัน:

1. การอ่านถูกข้าม ไม่ใช่แค่เร็วขึ้น request ที่ warm ต้องพิสูจน์ได้ว่าไม่ไปถึง Supabase
2. ความสดใหม่ยังอยู่ การเขียนต้องปรากฏภายในเป้า ≤10 นาทีอย่างสบาย

อีกเรื่องที่ควรตัดสินที่นี่ เพราะตอนนี้เป็นการอ้างไม่ใช่การวัด: เอเจนต์อิสระสามตัวระบุว่า unstable_cache บน Vercel อยู่บน Data Cache ที่ durable ข้าม invocation ไม่ใช่ memory ต่อ process ซึ่งสอดคล้องกับ docs ของ Next ("persist the result across requests and deployments") แต่ ยังไม่ถูกยืนยัน บนดีพลอยนี้ ถ้าปรากฏว่าไม่จริง ตัว fallback ของ #238 จะทำให้หน้ายังถูกต้อง และแนวทางทั้งหมดจะยุบกลับไปที่การตัดสินใจ D4 ของ #234

เกณฑ์รับงาน

• หลักฐานว่า request ที่ warm ไม่ query Supabase (query log, counter ที่เพิ่ม หรือการสังเกตที่เทียบเท่า) — ไม่ใช่ตัวเลขเวลา
• p95 ตอน warm ของ /projects ต่ำกว่า 1 วินาที วัดบน production และบันทึกเลขไว้ที่นี่
• ยืนยันความ durable ข้าม invocation อย่างชัดเจน หรือบันทึกความล้มเหลวของมันเป็นข้อค้นพบ
• probe หลังการเขียน: แก้ข้อมูล → สั่ง revalidate → request ถัดไปเห็นการเปลี่ยนแปลง ต่ำกว่า 10 นาทีมาก
• x-vercel-cache คาดว่าจะยังเป็น MISS — route ยังเป็น dynamic ระบุให้ชัดเพื่อไม่ให้อ่านผลว่าล้มเหลว
• เลขที่วัดได้ถูกโพสต์บน perf(projects): /projects and /blog are dynamic because they read searchParams — and no ADR records the caching strategy #234 และใน ledger แทนค่าประมาณ

[xenodeve]

Measured on production — 2026-07-26 17:04–17:10 UTC, deploy carrying f72c872 (#243)

EN

1. The read is skipped — a counter, not a latency figure

pg_stat_statements on the production database, counting the PostgREST list query
(pgrst_source selecting public.projects filtered by status, no slug predicate):

Step	UTC	calls	Δ
snapshot	17:07:04	3381	—
6 warm requests to /projects	17:07:17–23	—	—
snapshot	17:07:34	3381	0
POST /api/revalidate (tag bust)	17:07:56	—	—
3 requests (17:08:05, :12, :12)		—	—
snapshot	17:08:21	3382	+1
10 more warm requests	17:09:4x	—	—
snapshot	17:09:57	3382	0

16 warm requests produced zero database calls. The one call in the middle is the refill the tag
bust forced. This is the check #207 failed: a better number while every request still hit the DB.

2. Durability across invocations — verified, and this is what proves it

The tag bust was issued in a different function invocation (the Route Handler) from the reads,
and it released the entry — one refill served three subsequent reads. A per-process in-memory LRU
cannot be invalidated from another invocation, so the entry lives in a store shared across
invocations. unstable_cache is Data-Cache-backed on this deployment; the three-agent assertion the
issue flagged as unverified now has evidence behind it.

3. Warm p95 — 0.83 s, under the 1 s target

Ten consecutive requests on one reused connection (curl with repeated URLs, so TLS is paid once —
what a real browser does):

• total: p95 0.832 s, median 0.571 s, min 0.488 s
• TTFB: p95 0.460 s, median 0.332 s, min 0.312 s

Measured the naive way instead — a fresh curl process per request, paying DNS + TLS every time —
the same server reports p95 ≈ 1.4 s, median ≈ 0.85 s. Recording both so the number is not quietly
flattering: the server-side figure is the p95 0.83 s above, and the per-request handshake is a
measurement artefact a browser pays once per session.

For scale: pre-#238 was 1.4–1.6 s on every request with a full Supabase round-trip each time, and
pre-#207 3.2–3.7 s. The control pages that skip the function entirely (/faq, /about) remain
0.07–0.11 s — still the explicit non-goal (#241).

4. x-vercel-cache stays MISS — as expected, not a failure

Every request: x-vercel-cache: MISS, cf-cache-status: DYNAMIC, age: 0. The route is still
dynamic by construction (it awaits searchParams for the JS-free filter) so the CDN cannot serve it.
What changed is what happens inside the invocation: the function no longer talks to Supabase.
Making the CDN serve /projects is #241's decision, not a regression here.

5. Correction to what PR #243 said about staleness

The PR stated that on the cron path the first read after a write serves the stale list while fresh
data loads behind it (stale-while-revalidate). Measurement says otherwise: the first read after
the bust took 3.451 s — it blocked on the refill — while the two reads after it were 0.41 s and
0.39 s. A stale-while-revalidate serve would have returned that first read fast. So on this
deployment revalidateTag(tag, 'max') behaves as immediate expiry for an unstable_cache entry,
consistent with the code trace (cacheLife resolves to undefined when the profile does not match a
configured cacheLife, and the tag is expired). The PR's caveat was more pessimistic than reality; a
freshness probe does not need to read twice.

The 3.451 s refill is the column-fallback ladder: 0032/0033 are still unapplied, so every cache
miss pays three failing selects before the one that works. That cost now falls on one request per
invalidation instead of every request — but it is a concrete, measured argument for applying those
migrations. Not applied here: a production DB write requires explicit per-action authorization.

6. What is NOT proven — the post-write probe

The invalidation half is measured above: revalidate → the next read refills from the database →
fresh content, 9 s from the POST (17:07:56) to the served refill (17:08:05). Well inside the ≤10
min target.

The mutation half was not performed. Making a project row change on production is a production DB
write, which CLAUDE.md makes a stop-and-authorize action, and no authorization was given for one.
No natural write landed in the window either — the last generator write was 12:59 UTC, four hours
earlier, and nothing has been generated in the last three hours.

So this AC stays unchecked. It closes on either the next natural sync write (free, just needs
observing) or one authorized mutation. The writer side is already covered by tests — the nestjs
revalidate client is unit-tested to POST after a write — so the only unobserved link is the DB write
itself landing, which is not in doubt.

TH

1. การอ่านถูกข้ามจริง — เป็น counter ไม่ใช่ตัวเลขเวลา

pg_stat_statements บนฐานข้อมูล production นับ query รายการของ PostgREST
(pgrst_source ที่ select public.projects กรองด้วย status และไม่มีเงื่อนไข slug):

ขั้น	UTC	calls	Δ
snapshot	17:07:04	3381	—
6 request ตอน warm ไป /projects	17:07:17–23	—	—
snapshot	17:07:34	3381	0
POST /api/revalidate (ล้าง tag)	17:07:56	—	—
3 request (17:08:05, :12, :12)		—	—
snapshot	17:08:21	3382	+1
อีก 10 request ตอน warm	17:09:4x	—	—
snapshot	17:09:57	3382	0

16 request ตอน warm ทำให้เกิดการเรียกฐานข้อมูลศูนย์ครั้ง การเรียกหนึ่งครั้งตรงกลางคือการเติมแคช
ที่การล้าง tag บังคับให้เกิด นี่คือการตรวจที่ #207 สอบตก: ตัวเลขดีขึ้นขณะที่ทุก request ยังยิงฐานข้อมูล

2. ความ durable ข้าม invocation — ยืนยันแล้ว และนี่คือสิ่งที่พิสูจน์มัน

การล้าง tag ถูกสั่ง ในคนละ function invocation (Route Handler) กับการอ่าน และมันปล่อย entry ได้ —
การเติมครั้งเดียวรองรับการอ่านสามครั้งถัดมา in-memory LRU ต่อ process ถูก invalidate จาก invocation
อื่นไม่ได้ ฉะนั้น entry อยู่ใน store ที่แชร์ข้าม invocation unstable_cache อยู่บน Data Cache บน
ดีพลอยนี้จริง ข้ออ้างจากเอเจนต์สามตัวที่ issue ระบุว่ายังไม่ยืนยัน ตอนนี้มีหลักฐานรองรับแล้ว

3. p95 ตอน warm — 0.83 วินาที ต่ำกว่าเป้า 1 วินาที

10 request ติดกันบน connection เดียวที่ใช้ซ้ำ (curl ที่ใส่ URL ซ้ำ ฉะนั้นจ่าย TLS ครั้งเดียว —
เหมือนที่เบราว์เซอร์จริงทำ):

• total: p95 0.832 วิ มัธยฐาน 0.571 วิ ต่ำสุด 0.488 วิ
• TTFB: p95 0.460 วิ มัธยฐาน 0.332 วิ ต่ำสุด 0.312 วิ

ถ้าวัดแบบตรงไปตรงมา — เปิด curl ใหม่ทุก request จ่าย DNS + TLS ทุกครั้ง — เซิร์ฟเวอร์เดียวกันให้
p95 ≈ 1.4 วิ มัธยฐาน ≈ 0.85 วิ บันทึกไว้ทั้งสองแบบเพื่อไม่ให้ตัวเลขสวยแบบเงียบ ๆ: ตัวเลขฝั่งเซิร์ฟเวอร์
คือ p95 0.83 วิ ข้างบน ส่วน handshake ต่อ request เป็นสิ่งแปลกปลอมจากวิธีวัด ซึ่งเบราว์เซอร์จ่ายครั้งเดียว
ต่อเซสชัน

เทียบสเกล: ก่อน #238 คือ 1.4–1.6 วิ ทุก request พร้อมการวิ่งไป Supabase เต็มรอบทุกครั้ง และ
ก่อน #207 คือ 3.2–3.7 วิ หน้าควบคุมที่ข้าม function ทั้งหมด (/faq, /about) ยังอยู่ที่ 0.07–0.11 วิ
— ยังเป็น non-goal ที่ระบุไว้ชัด (#241)

4. x-vercel-cache ยังเป็น MISS — ตามคาด ไม่ใช่ความล้มเหลว

ทุก request: x-vercel-cache: MISS, cf-cache-status: DYNAMIC, age: 0 route ยังเป็น dynamic
โดยโครงสร้าง (มัน await searchParams สำหรับตัวกรองที่ไม่ใช้ JS) ฉะนั้น CDN เสิร์ฟมันไม่ได้
สิ่งที่เปลี่ยนคือสิ่งที่เกิด ข้างใน invocation: function ไม่คุยกับ Supabase อีกแล้ว การทำให้ CDN เสิร์ฟ
/projects เป็นการตัดสินใจของ #241 ไม่ใช่การถดถอยตรงนี้

5. แก้ข้อความที่ PR #243 พูดเรื่องความเก่าของข้อมูล

PR ระบุว่าบนเส้นทาง cron การอ่านครั้งแรกหลังการเขียนจะได้รายการเก่าขณะที่ข้อมูลใหม่โหลดอยู่ข้างหลัง
(stale-while-revalidate) การวัดบอกตรงกันข้าม: การอ่านครั้งแรกหลังการล้าง tag ใช้ 3.451 วิ —
มันบล็อกรอการเติมแคช ขณะที่สองครั้งถัดมาคือ 0.41 วิ และ 0.39 วิ ถ้าเป็นการเสิร์ฟแบบ
stale-while-revalidate การอ่านครั้งแรกนั้นจะเร็ว ฉะนั้นบนดีพลอยนี้ revalidateTag(tag, 'max')
ทำงานเป็นการหมดอายุทันทีสำหรับ entry ของ unstable_cache ซึ่งสอดคล้องกับการไล่โค้ด (cacheLife
เป็น undefined เมื่อ profile ไม่ตรงกับ cacheLife ที่ตั้งไว้ และ tag ถูกทำให้หมดอายุ) ข้อควรระวังใน PR
มองโลกร้ายกว่าความจริง — probe วัดความสด ไม่จำเป็น ต้องอ่านสองครั้ง

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

6. สิ่งที่ยัง ไม่ ได้พิสูจน์ — probe หลังการเขียน

ครึ่งของการ invalidate ถูกวัดไว้ข้างบน: revalidate → การอ่านถัดไปเติมจากฐานข้อมูล → เนื้อหาใหม่
9 วินาที จาก POST (17:07:56) ถึงการเสิร์ฟที่เติมแล้ว (17:08:05) อยู่ในเป้า ≤10 นาทีอย่างสบาย

ครึ่งของการแก้ข้อมูลไม่ได้ทำ การทำให้แถวโปรเจกต์บน production เปลี่ยนคือการเขียนฐานข้อมูล
production ซึ่ง CLAUDE.md กำหนดให้เป็นการกระทำที่ต้องหยุดขออนุญาต และไม่มีการอนุญาตให้ทำ
และไม่มีการเขียนตามธรรมชาติเกิดขึ้นในช่วงเวลาที่วัดด้วย — การเขียนของ generator ครั้งล่าสุดคือ
12:59 UTC สี่ชั่วโมงก่อนหน้า และไม่มีอะไรถูก generate ในสามชั่วโมงที่ผ่านมา

ฉะนั้นเกณฑ์ข้อนี้ยังไม่ติ๊ก มันจะปิดได้ด้วยการ sync ตามธรรมชาติครั้งถัดไป (ฟรี แค่ต้องเฝ้าดู) หรือการแก้
ข้อมูลหนึ่งครั้งที่ได้รับอนุญาต ฝั่งตัวเขียนมีเทสต์คุมอยู่แล้ว — ไคลเอนต์ revalidate ของ nestjs ถูก
unit-test ว่า POST หลังการเขียน — ฉะนั้นข้อต่อเดียวที่ยังไม่ถูกสังเกตคือการเขียนฐานข้อมูลลงจริง
ซึ่งไม่ใช่เรื่องที่น่าสงสัย