docs(player-info): add buffered warm-pool smoke validation runbook

[ChechiDev]

Scope

PR 7 in the player_info buffered warm-pool series. Adds a smoke validation runbook for the buffered+warm_pool execution path integrated in PR #142.

This PR is documentation only. No production code, tests, configuration, CI, schemas, migrations, or dependencies were modified.

Branch

docs/player-info-buffered-warm-pool-smoke-validation → main
Commit: ddf0775

Relationship to PR #142

PR #142 (merged 2026-08-04) integrated WarmBrowserPool into the buffered player_info path. This PR adds the operator runbook for validating that path safely before enabling it at larger scale.

Changed files

File	Change
docs/operations/player_info_buffered_warm_pool_smoke.md	NEW — 674-line smoke validation runbook

Documentation only

• No production runtime file changed
• No tests changed
• No feature-flag defaults changed
• No CI configuration changed
• No schema or migration changed
• No dependency or lockfile changed
• No .claude or CLAUDE.md change
• No direct-mode behavior changed
• No live external test added

Default behavior impact

None. Both feature flags (SCRAPING__PLAYER_INFO_DISPATCH_BUFFER_ENABLED, SCRAPING__PLAYER_INFO_WARM_POOL_ENABLED) remain false by default. Direct mode is unchanged.

Feature flag impact

The runbook documents how to enable each mode for validation only. It does not change how flags are read or applied at runtime.

Smoke stages

Stage	Description	Max workers	Max candidates
0	Static verification — no live DB	—	—
1	Direct mode baseline	1	1–3
2	Buffered mode, no warm pool	2	tiny bounded set
3	Buffered + warm pool smoke	2	tiny bounded set
4	Optional cautious expansion	5	tiny bounded set

This runbook caps at 5 workers. Higher counts are deferred to the existing buffered-mode soak doc and a future warm-pool soak phase.

Rollback procedure

Unset SCRAPING__PLAYER_INFO_DISPATCH_BUFFER_ENABLED and SCRAPING__PLAYER_INFO_WARM_POOL_ENABLED. No code changes, migrations, or destructive SQL required.

Safety notes

• Requires a local and disposable PostgreSQL database — never production or shared
• Candidate population must be bounded before startup
• All included SQL is read-only (BEGIN TRANSACTION READ ONLY; ... ROLLBACK;)
• No UPDATE, DELETE, INSERT, TRUNCATE, FOR UPDATE, or advisory locks
• 16 abort conditions documented; immediate stop required for any trigger
• Sensitive-data exclusion list covers cookies, CDP tokens, WebSocket URLs, raw HTML, credentials, full player URLs, complete DSNs

Sensitive-data exclusions

The runbook explicitly lists what must not be logged, recorded, or committed:

• Cookies or cookie values
• CDP tokens or WebSocket URLs (ws://, wss://)
• Browser session payloads
• Raw HTML responses
• Credentials or secrets
• Full browser profile directory paths
• Raw queue payloads
• Full player URLs
• Complete database connection strings

Tests / gates run

Documentation only — full pytest not required per project policy.

Gate	Result
ruff	CLEAN
flake8	CLEAN
mypy --strict	0 errors, 188 files
lint-imports	4 contracts kept, 0 broken
pip-audit	No known vulnerabilities
git diff --check	CLEAN

Review agents run

• senior-backend-engineer: 2 CRITICALs and 4 WARNINGs identified and resolved before commit
  • CRITICAL: Stage 0.2 mode log line falsely implied direct-mode log was observable (suppressed at WARNING threshold) — fixed
  • CRITICAL: rate_limit_gate: probe EXCEPTION log message entirely absent from observable events table — added
  • WARNINGs: buffered-only log format undocumented, mark_engine_ready in Stage 2 omitted, on_engine_teardown fires always not only on failure, all probes failed level was labeled WARNING but is actually ERROR — all fixed
• security-reviewer: APPROVED — no BLOCKERs or CRITICALs
  • One MEDIUM (informational gap in "what not to capture" about asyncio task names) — acknowledged, low risk for internal ops doc

Unresolved risks

• SCRAPING__PLAYER_INFO_POOL_SIZE is declared in settings but not used to create the pool in main() — --workers drives pool size. Documented as a note in the runbook; the mismatch is a pre-existing issue not in scope for this PR.
• Mode-selection log lines are emitted at INFO level but the script root logger defaults to WARNING — all three mode logs are suppressed at default verbosity. Documented in Stage 0.2; flag inspection via env vars is the recommended verification method.

No live scraping

No live scraping was run to produce this document. Stage 0 (static verification) is the only stage executable without a live database. The runbook does not claim Stage 1, 2, 3, or 4 success.

PR not merged

This PR has not been merged and has not been configured for auto-merge.

Next PR

The next PR has not been started.