docs(ai): record the last-working-provider coordination decision

The per-worker in-process "last working provider" hint stays volatile
and is deliberately NOT folded into the durable Postgres health ledger.
The ledger already shares the load-bearing skip signal across workers;
the only uncoordinated piece is a soft reorder whose worst case is one
redundant first-hop per worker per hour. Promoting it to a per-request
ledger write would add hot-path write amplification for a negligible
saving. Documented inline so the trade-off is explicit.
This commit is contained in:
Marc-André Bombeck committed 2026-06-19 21:11:51 +02:00
1 parent 57242b9884
commit e7d14a07e8
1 file changed
+12
+12
View File
@@ -53,6 +53,18 @@ const NEVER_SKIP: ReadonlySet<ProviderChainType> = new Set(["local"]);
* across workers — when scaling out we'd move this to Redis, but for
* v1.4.16 the per-worker cache is enough to absorb the typical
* "polling reload" pattern.
*
* v1.18.7 (LOW-8) — DECISION: the volatile per-worker hint is left
* in-process and NOT folded into the durable Postgres health ledger. The
* ledger already shares the load-bearing signal across workers (the
* skip-hint reorder in `resolveChainOrder` pushes a dead-credential /
* backoff provider to the chain tail for every worker), so the only thing
* uncoordinated is a soft "tried this one last, put it first" reorder whose
* worst case is a single redundant first-hop per worker per hour — exactly
* the bound the v1.18.7 AI audit deemed acceptable at single-maintainer
* scale. Promoting the hint to a per-request ledger write would add write
* amplification on the hot path for a negligible saving; revisit only if a
* multi-worker deploy shows measurable redundant-hop cost.
*/
const LAST_WORKING_TTL_MS = 60 * 60 * 1000; // 1h