Contract & versioning

Contract & versioning

Atlas publishes a single contract endpoint that consumers floor-pin against, the same pattern the rest of the stack uses.

GET /v1/contract

{
  "contract_name": "atlas",
  "version": "x.y.z",
  "deployment_mode": "saas",
  "canonical_schema_version": "…",   // shape of canonical entities
  "envelope_schema_version": "…",    // shape of the ingest event envelope
  "canonical_entities": ["customer", "order", "job", "estimate", "…"],
  "envelope_dialects": ["synergy_sha256", "…"]
}

• version — the Atlas release. SemVer.
• canonical_schema_version — the version of the canonical entity shapes.
• envelope_schema_version — the version of the ingest event envelope.
• canonical_entities — the entity types this deployment serves.
• envelope_dialects — the inbound signature/envelope dialects this deployment accepts.

Floor-pinning

Consumers should floor-pin the Atlas contract (version and the two schema versions) and treat a major bump as a breaking change — the same discipline the rest of the stack uses for codex’s cache-key VERSION scheme. A new entity type or a new envelope dialect is additive; a change to an existing entity’s shape rotates canonical_schema_version.

Backward compatibility

• Additive changes (new entity type, new optional field, new connector) do not rotate existing schema versions.
• Breaking changes to a canonical entity shape rotate canonical_schema_version; breaking changes to the envelope rotate envelope_schema_version.
• Cross-system references and provenance are carried forward across compatible upgrades so a consumer never loses the join key.