fix(config): negatively cache deterministic hosted config rejections and stop reporting 4xx errors

[kojiwakayama]

Fixes VERYFRONT-SERVER-E (1,682 events / 7 users over 8 days, ongoing).

Root cause

A tenant's hosted veryfront.config uses a construct outside the declarative subset (any property access / new — e.g. routes.mode, process.env.X — maps to forbidden-capability: unsupported-call). The rejection is correct and deterministic (security boundary; no full-JS fallback for hosted tenants by design), but nothing about it was remembered: every request re-read source, re-spawned a permissionless worker, re-parsed with Babel, and re-rejected — 1,682 Sentry events, and a hammered broken config burns the 2-slot evaluator worker pool, pushing other tenants into SERVICE_OVERLOADED.

Fix

• Negative LRU cache (config-failure-cache) for deterministic DeclarativeConfigEvaluationError rejections, keyed by the existing hostedCacheKey (configPath ‖ sourceDigest ‖ policyVersion ‖ fingerprint) — exactly the right key: a source-bound rejection can never become a success without the digest changing. Retryable infra failures (worker-timeout/overloaded) are NOT cached.
• isExpectedApplicationError: 4xx VeryfrontErrors are no longer captured to Sentry (the tenant's 400 is their bug, not ours).

Testing (red-green TDD)

Four new negative-caching tests in loader.test.ts (deterministic rejection served from cache, exact production message asserted, infra failures still retried) + application-errors.test.ts coverage; all fail on pre-fix src (adversarial revert-check), pass at HEAD (109 steps loader, 14 passed observability).

Reviewer notes (from adversarial verification)

• The 4xx suppression applies to every VeryfrontError at every captureApplicationError boundary (proxy, SSR, runtime handler, agent) — genuine server-side bugs surfacing as 4xx (mis-issued internal auth → 401, unexpected 404/429 storms) will no longer reach Sentry. Deliberate, but wider than SERVER-E strictly required; consider keeping some 4xx slugs reportable.
• The cached rejection is a shared error instance; each request wraps it in a fresh VeryfrontError downstream (test-asserted), so the shared stack is harmless.

Note: the stacked PR fix/sentry-tenant-error-capture builds on this branch.

Summary by CodeRabbit

• Bug Fixes

  • Improved hosted configuration handling by reusing deterministic evaluation failures, re-evaluating after configuration changes, and retrying transient infrastructure failures.
  • Prevented expected client-side configuration errors from being reported as application errors, while continuing to report server-side initialization and unexpected errors.

• Documentation

  • Updated observability API reference links to point to the correct source locations.

• Tests

  • Added coverage for hosted configuration failure caching, cache clearing, retries, and application-error classification.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 38364e6d-1526-463b-91fd-c0ccacbc6471

📥 Commits

Reviewing files that changed from the base of the PR and between 4eece1f and 91e0eb2.

📒 Files selected for processing (5)

• docs/api-reference/veryfront/observability.md
• src/config/loader.test.ts
• src/config/loader.ts
• src/observability/application-errors.test.ts
• src/observability/application-errors.ts

---

📝 Walkthrough

Walkthrough

Changes

Hosted configuration negative cache

Layer / File(s)	Summary
Failure cache and eligibility src/config/loader.ts	Adds a monitored LRU cache for deterministic hosted configuration failures and excludes retryable worker-phase errors.
Evaluation and invalidation flow src/config/loader.ts	Reads cached failures before evaluation, stores eligible failures after evaluation, and clears them with clearConfigCache.
Negative-cache behavior tests src/config/loader.test.ts	Tests rejection reuse, source-change re-evaluation, cache clearing, and retryable failure recovery.

Application-error classification

Layer / File(s)	Summary
Expected error filtering and documentation src/observability/application-errors.ts, src/observability/application-errors.test.ts, docs/api-reference/veryfront/observability.md	Excludes client-class VeryfrontError instances with 4xx statuses from reporting, preserves server and ordinary error reporting, and updates observability source links.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🔵 Low · up to 91e0e

The PR adds deterministic rejection caching and stops reporting 4xx application errors; it is otherwise mergeable, but suppressing all 4xx errors could hide genuine server-side failures, so owner awareness or follow-up to narrow reportable cases is warranted.

Sequence Diagram(s)

sequenceDiagram
  participant HostedSourceEvaluation
  participant HostedConfigFailureCache
  participant HostedConfigurationFlight
  HostedSourceEvaluation->>HostedConfigFailureCache: Check project key and revision
  HostedSourceEvaluation->>HostedConfigurationFlight: Evaluate when no cached failure exists
  HostedConfigurationFlight->>HostedConfigFailureCache: Store deterministic failure

Loading

Possibly related PRs

• veryfront/veryfront-code#3363: Both changes refine reporting behavior for VeryfrontError application errors.
• veryfront/veryfront-code#3671: This change extends hosted configuration rejection handling with negative caching.

Suggested reviewers: kwakayama

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes both main changes: negative caching for deterministic hosted config rejections and suppression of Sentry reporting for 4xx errors.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/sentry-veryfront-server-e

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📦 Client bundle boundary

Entrypoint	Modules	Source size	Server leaks
src/index.client.ts	454	3065 KiB	⚠️ 39 known

A server module in a client graph aborts hydration in the browser. New leaks fail CI; known leaks are tracked in scripts/lint/client-bundle-baseline.json to burn down.