# Runtime Error, Logging, And Debug Policy

## Scope
This document defines runtime behavior for error handling, error logging, and debug mode.

## How To Use This File
1. Use this policy when implementing runtime configuration.
2. Use this policy during release readiness checks.
3. Keep implementation and this document aligned.

## Runtime Modes
1. Development mode:
   - Debug mode can be ON.
   - Verbose diagnostics may be visible to developers.
2. Production mode:
   - Debug mode must be OFF.
   - User-facing errors must be sanitized.
   - Detailed errors must go to server logs, not browser output.

## Must (Runtime Gate)
- [ ] Define a single debug switch, for example APP_DEBUG.
- [ ] Ensure production default is debug OFF.
- [ ] Ensure display_errors is disabled in production runtime.
- [ ] Ensure exceptions and errors are logged server-side.
- [ ] Ensure user-facing error responses avoid sensitive internals.
- [ ] Ensure AJAX error responses are safe and sanitized.

## Should (Expected Practices)
- [ ] Use structured logs with timestamp, severity, component, and request context.
- [ ] Include request correlation id in logs where practical.
- [ ] Separate operational logs from application error logs.
- [ ] Document log retention and rotation policy.
- [ ] Show footer render timing automatically when APP_DEBUG is on.
- [ ] Allow footer render timing to be enabled independently with APP_SHOW_RENDER_TIME.

## Could (Optional Maturity)
- [ ] Add centralized log aggregation.
- [ ] Add alerting for repeated high-severity runtime errors.
- [ ] Add error budget and incident response targets.

## Recommended Implementation Pattern
1. Read APP_DEBUG from environment or config.
2. Set PHP error display based on mode.
3. Route detailed exception data to logs.
4. Return minimal, safe error payloads to users.
5. Use APP_SHOW_RENDER_TIME for non-debug render timing visibility when needed.

## Sign-Off Record
- [ ] Must items complete.
- [ ] Any Should exceptions documented and approved.
- [ ] Runtime policy verified in release checklist.