This commit is contained in:
1 parent
e2445980f9
commit
31a47346ea
5 files changed
+158
-30
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user