# Contract versioning and lifecycle

## Version surfaces

CleanedWeb publishes independent versions because they change at different rates:

- Capabilities `contract_version` governs the runtime manifest shape.
- Capabilities `api_version` identifies the deployed public API release.
- OpenAPI `info.version` governs documented HTTP operations.
- `property-profile-v2`, `property-profile-field-catalog-v2`, `property-event-v1`, and `error-v1`
  govern their individual data contracts.
- MCP initialization negotiates a protocol revision separately from CleanedWeb schemas.

## Compatibility policy

Within a published major contract, CleanedWeb may:

- add optional object properties;
- add newly ready markets, filters, event types, or limits to runtime capabilities;
- add enum values only where the contract explicitly permits extension;
- add OpenAPI operations and non-required request fields;
- clarify descriptions without changing behavior.

A major version is required when a change removes or renames a field, changes its type or
unit, makes an optional field required, changes canonical identity semantics, or changes a
successful response so existing conforming consumers can no longer accept it.

Consumers must ignore unknown optional object properties where the schema permits them.
They must reject an unknown major schema version and must not guess a replacement mapping.

## Deprecation process

Before removing a published major contract, CleanedWeb will publish:

1. A changelog entry describing the affected operation or schema.
2. A migration guide with old and new examples.
3. The planned support end date once it is contractually established.
4. Runtime or response deprecation signals when the relevant service supports them.

No support duration or sunset date should be inferred when it is absent from the
machine-readable changelog and runtime response.

## Agent behavior

At the start of a workflow, record the capabilities contract version, API version, schema
versions, and `snapshot.dataUpdatedAt`. If a major version is unsupported, stop before a
property search or write. Do not silently rename fields or remove validation.

Machine-readable history: `https://cleanedweb.com/changelog.json`.