Harden API contracts with request IDs and audit telemetry
CI / test (push) Waiting to run

This commit is contained in:
Rbanh committed 2026-02-18 22:19:38 -05:00
1 parent e2445980f9
commit 31a47346ea
5 files changed
+158 -30

No files matched your search

+68
View File
@@ -0,0 +1,68 @@
# API + MCP Contract Policy
This document defines compatibility expectations for Schemeta API and MCP tools.
## Version Fields
All successful API/MCP structured responses include:
- `api_version`
- `schema_version`
HTTP API responses also include:
- `request_id` (response field + `x-request-id` header)
## Compatibility Policy
- Additive changes are allowed within the same `api_version` minor release.
- Breaking shape changes require a new API major version.
- `schema_version` increments when SJM schema semantics or required fields change.
## HTTP API Contracts
Stable endpoints:
- `POST /compile`
- `POST /analyze`
- `POST /layout/auto`
- `POST /layout/tidy`
- `GET /health`
- `GET /mcp/ui-bundle`
Error envelope shape:
```json
{
"ok": false,
"request_id": "uuid-or-forwarded-id",
"error": {
"code": "stable_machine_code",
"message": "human-readable description"
}
}
```
## MCP Tool Contracts
Stable tool names:
- `schemeta_compile`
- `schemeta_analyze`
- `schemeta_ui_bundle`
Contract rules:
- Tool names are stable across minor versions.
- Input schemas may gain optional fields additively.
- Structured response fields are additive-only within a minor.
## Persistence and Restore
UI workspace persistence is expected to support:
- deterministic JSON export/import roundtrip
- local snapshot restore path (`schemeta:snapshots:v2`)
- reset-to-sample baseline recovery for QA loops
These are validated in release checklist + browser regression flow.
+13 -1
View File
@@ -35,6 +35,18 @@ This runbook covers baseline production operation for Schemeta API + UI.
- `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:
@@ -78,6 +90,6 @@ This runbook covers baseline production operation for Schemeta API + UI.
## Observability Recommendations
- Add structured request logs at reverse proxy layer.
- 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.