chore: plans for error handling middleware and error observability

[kojiwakayama]

Follow-up plans to #246 (error codes refactoring) and #247 (centralize scattered errors).

Execution Order

#246 Slug registry + RFC 9457     ← foundation
  ├── #247 Centralize scattered errors
  ├── This PR: Plan A (error handling middleware)  ← depends on #246
  └── This PR: Plan B (error observability)        ← depends on #246 + Plan A

---

Plan A: Error Handling Middleware

Unified catch → serialize → respond pipeline at all boundaries.

Full plan: plans/error_handling_middleware.md

Tasks

Phase 1: HTTP error boundary

• 1.1 Create http-error-boundary.ts — catch all, serialize RFC 9457
• 1.2 Tests for boundary middleware
• 1.3 Wire into runtime-handler/index.ts (env-aware errorToRFC9457Response)
• 1.4 Wire into routing/api/route-executor.ts

Phase 2: CLI error boundary

• 2.1 Create cli-error-boundary.ts — structured terminal output
• 2.2 Tests
• 2.3 Wire into CLI router (adds error metrics + OTel tracing)

Phase 3: Error wrapping

• 3.1 wrapUnknownError() — wrap plain Error as unknown-error slug
• 3.2 Migrate wrapError() callers to wrapWithContext(), delete wrapper

Phase 4: Delete legacy

• 4.1 Delete routing/api/error-handler.ts (zero imports after dedup)
• 4.2 Delete handleError(), logAndThrow(), wrapError() (zero callers)
• 4.3 Clean up barrel exports

Phase 5: Verify

• 5.1 Ad-hoc { error } responses: only dev-only dashboard API and input-validation remain (breaking change to convert)
• 5.2 CLI errors show slug + suggestion via cliErrorBoundary
• 5.3 All tests pass (1083 passed)

---

Plan B: Error Observability

Structured logging, metrics, tracing, and alerting with slug-based errors.

Full plan: plans/error_observability.md

Tasks

Phase 1: Structured error logging

• 1.1 Create src/errors/logging.ts — JSON in production, human-readable in dev
• 1.2 Tests
• 1.3 handleError deleted; remaining handleErrorWithFallback is a different pattern (catch-and-continue)

Phase 2: Error metrics

• 2.1 Create error-instruments.ts — veryfront.error.count{slug,category,status}
• 2.2 Tests
• 2.3 Wire into error boundary middleware

Phase 3: Error tracing

• 3.1 Create src/errors/tracing.ts — attachErrorToSpan()
• 3.2 Tests
• 3.3 Wire into existing tracing infrastructure

Phase 4: Migrate ErrorCollector

• 4.1 Replace ErrorType enum with registry categories
• 4.2 Update tests
• 4.3 All add*Error() callers use new category system

Phase 5: Verify

• 5.1 Error boundary logs include slug + category
• 5.2 Prometheus metrics endpoint includes veryfront_error_count
• 5.3 All tests pass (1083 passed)

---

Fix Commits (review feedback)

• b071194 — Deduplicate RFC 9457 response logic (handleAPIError → errorToRFC9457Response)
• fb2c5dc — Fix logError context merge (preserve both error.context and caller context)
• 95c445f — Use shared isProduction() in CLI error boundary (remove Node.js fallbacks)
• 0d40b16 — Remove unused errorRate histogram and clean up re-exports
• d532459 — Fix error handling hardening and remove collector compat paths
• 86235af — Strip error details from production responses in runtime-handler (P1 fix)
• ebbf627 — Delete deprecated handleError/logAndThrow, wire cliErrorBoundary into CLI router
• 3332b00 — Replace wrapError with wrapWithContext, delete legacy wrapper

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7403c08fe0

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".