Integration Stability Policy

Purpose

This policy defines stability guarantees for Norynta integration surfaces so developers, bots, and AI agents can manage change safely.

Stability levels

Stable

• Backward compatibility is expected.
• Breaking changes require explicit migration guidance.
• Examples: primary HTTP discovery endpoints, OpenAPI contract publication, stable schema headers.

Supported

• Maintained and production-usable.
• Minor shape changes can occur, but behavior is expected to remain practical.
• Examples: MCP tool servers that map onto stable HTTP contracts.

Experimental

• May change quickly without long deprecation windows.
• Use behind feature flags or only in non-critical automation.

Internal-only

• Not part of the external contract.
• May change without external notice.

Current classification

Surface	Level
Discovery endpoints (/.well-known/agent.json, /api/agent/card, /api/agent/access)	Stable
Market data health/snapshot schema headers (X-Api-Schema)	Stable
OpenAPI (public/openapi.json) and schema (public/api-schema.json) publication	Stable
Public/trading/ops MCP servers	Supported
x402 capability metadata	Supported (optional by integration profile)

Change management expectations

• Prefer additive changes over destructive schema shifts.
• For breaking changes on stable surfaces:
  • update docs and compatibility matrix,
  • update quickstart/examples,
  • provide migration notes in integrator changelog.

Runtime compatibility guidance

• Validate X-Agent-Schema-Version on discovery endpoints.
• Validate X-Api-Schema on health/snapshot endpoints.
• Pin generated clients and validate at startup.
• Use idempotency keys for write retries.

Related docs

• docs/public/INTEGRATION_COMPATIBILITY_MATRIX.md
• docs/public/INTEGRATION_SNIPPETS.md
• docs/public/INTEGRATOR_CHANGELOG.md
• docs/AGENT_INTEGRATION.md