# Schemeta Operations Runbook

This runbook covers baseline production operation for Schemeta API + UI.

## Runtime

- Node.js 18+ recommended.
- Start command: `npm run start`
- Default bind: `0.0.0.0:8787`

## Environment Variables

- `PORT` (default `8787`)
- `MAX_BODY_BYTES` (default `2097152`)
  - Hard limit for request body size on `POST` endpoints.
- `MAX_REQUESTS_PER_MINUTE` (default `120`)
  - Per-client IP rate limit window for `POST` endpoints.
- `SCHEMETA_AUTH_TOKEN` (optional)
  - When set, all `POST` API routes require either:
    - `Authorization: Bearer <token>`
    - `x-api-key: <token>`
- `CORS_ORIGIN` (optional)
  - If set, CORS is enabled for this origin only.

## Endpoints

- `GET /health`
  - Liveness probe, returns process uptime and status.
- `GET /`
  - Serves workspace UI.
- `POST /compile`
  - Compile + render with ERC/diagnostics and layout metrics.
- `POST /analyze`
  - Topology and diagnostics summary.
- `GET /mcp/ui-bundle`
  - Metadata for MCP UI embedding.

## Request Correlation and Audit Logs

- Every response includes `x-request-id`.
- API envelopes include `request_id` for correlation in clients and logs.
- Server emits one JSON audit log entry per request on response finish with:
  - `request_id`
  - `method`
  - `path`
  - `status`
  - `duration_ms`
  - `client`

## Production Checks

1. Verify process liveness:
   - `curl -s http://localhost:${PORT:-8787}/health`
2. Verify compile endpoint:
   - post `frontend/sample.schemeta.json` to `/compile`.
3. Verify analyze endpoint:
   - post same sample to `/analyze`.
4. Verify rate limiting:
   - exceed `MAX_REQUESTS_PER_MINUTE` with repeated `POST` and confirm `429`.
5. Verify auth (if enabled):
   - request `POST /compile` without token and confirm `401`.
   - request with valid token and confirm `200`.

## Incident Playbook

## High error rate (5xx)

1. Check process logs for stack traces and malformed payload spikes.
2. Validate request body sizes; lower/raise `MAX_BODY_BYTES` as appropriate.
3. Reproduce with `frontend/sample.schemeta.json` to isolate model-driven payload issues.
4. Roll back to previous known-good tag if regression confirmed.

## Elevated 429 responses

1. Confirm traffic source and whether bursts are expected.
2. If trusted internal clients are throttled, tune `MAX_REQUESTS_PER_MINUTE`.
3. Consider fronting with reverse proxy rate limit tiers for external users.

## UI/compile mismatch reports

1. Capture JSON from user (`Copy Repro` in workspace).
2. Re-run through `/compile` and inspect `warnings`, `errors`, and `layout_metrics`.
3. Compare with last release baseline for crossing/overlap regressions.

## Release / Rollback

1. Follow `docs/release-checklist.md`.
2. Tag releases after checklist completion and test pass.
3. Keep previous stable tag ready for fast rollback.

## Observability Recommendations

- Structured request logs are emitted by the app; keep proxy logs for edge-level traces.
- Track latency percentiles for `/compile` and `/analyze`.
- Track per-endpoint status code rates and top warning/error IDs.