docs(serverless): document timeout tuning

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• TODO: ktichen sink counter latency #5051
• fix(rivetkit): use engine actor stop threshold for shutdown #5049
• DO NOT MERGE: serverless restart race condition #4997
• fix(rivetkit): exit pid1 after signal shutdown #5045
• fix(rivetkit-core): decrement active actor metrics #5044
• fix(envoy-client): dont abort drain after 20s #5043
• temp: patch wasm-pack to point to latest binary #5037
• fix(rivetkit): require engine ping for health #5022
• feat(rivetkit): add current actor metrics #5020
• feat(rivetkit): expose low-cardinality metrics routes #5019
• docs(serverless): document timeout tuning #5018 👈 (View in Graphite)
• feat(kitchen-sink): add load testing harness #5017
• fix(rivetkit): expose client actor metadata #5016
• fix(runtime): avoid bounded dispatch channel stalls #5015
• fix(sqlite): fence remote requests by generation #5014
• feat(rivetkit-core): expose metrics endpoint #5013
• WIP: counter latency monitor #5011
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: docs(serverless): document timeout tuning

Status: Draft | Changes: +11 / -1 across 2 files

---

Overview

This PR improves the serverless production checklist by:

1. Replacing the vague "configure platform max concurrency" bullet with more precise per-instance concurrency guidance.
2. Adding two new actionable bullets for tuning requestLifespan and drainGracePeriod with concrete platform-specific values.
3. Appending internal driver test run results to .agent/notes/driver-test-progress.md.

---

Documentation Changes (production-checklist.mdx)

Positives:

• The rewritten concurrency bullet is clearer and more accurate — it correctly explains the 1-actor-per-in-flight-request model and links concurrency to autoscaling behavior.
• The requestLifespan and drainGracePeriod bullets are genuinely useful and were missing from the checklist. Providing concrete platform-specific example values (295 for Vercel Hobby, 3595 for Vercel Pro) is helpful.

Issues to address:

1. Inconsistent buffer sizes for requestLifespan. Vercel uses a 5-second buffer (300→295, 3600→3595), but Cloud Run uses a 60-second buffer (900→840). The asymmetry is unexplained and could confuse readers. Either use a consistent buffer or add a parenthetical explaining why Cloud Run needs a larger margin.

2. "Cloud Run's 15-min cap" may be inaccurate or misleading. Cloud Run HTTP request timeout defaults to 5 minutes but is configurable up to 60 minutes. There is no fixed 15-minute platform-wide cap for Cloud Run Services. If this refers to a specific tier or a common customer configuration, that context should be stated explicitly (e.g. "Cloud Run configured with a 15-min timeout"). As written it reads like a platform-imposed hard limit, which is incorrect.

3. drainGracePeriod default discrepancy. The bullet says the default is "30 minutes from the engine", but requestLifespan defaults to 60 minutes (3600s). A 30-minute drain out of a 60-minute lifespan is a very large fraction — worth double-checking against the implementation before publishing. If the unit is actually seconds (i.e., 30 seconds), that should be stated clearly.

4. Cross-link to configurePool docs. The /docs/general/registry-configuration link is referenced twice. Confirm that page exists and that it actually documents requestLifespan and drainGracePeriod — if not, readers will land on a page that doesn't help them act on this guidance.

---

Unrelated File: .agent/notes/driver-test-progress.md

The appended driver test run results are internal agent tracking notes with no bearing on this documentation change. This file should be removed from the PR or committed separately on an internal branch.

---

Summary

The intent is solid and the new bullets fill a real gap in the checklist. The main blockers before merging are:

• Verify or correct the Cloud Run timeout claim and the buffer size inconsistency.
• Confirm the drainGracePeriod default value and unit (30 min seems high relative to the 60-min lifespan).
• Remove the unrelated .agent/notes change.