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