# 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.

## 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.

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