# API deprecation policy — 0pt

BACKLOG P6 (API-24). There is exactly one prior breaking-ish change in this
repo's history to learn from: `services/api/orchestrator/main.py` moved from
`src/orchestrator` (docs/09-build-plan.md Phase 0) — internal, pre-contract,
no external consumers yet. This policy is written before it's needed for a
real consumer, on purpose (BACKLOG's own framing: "cheaper to write the
policy than to clean up after breaking someone").

## What counts as breaking

- Removing a path, operation, or required request/response field from
  `contracts/openapi.yaml`.
- Narrowing an accepted value (enum shrink, type tightening) on a request field.
- Changing a response field's meaning without changing its name/type.
- Changing default auth/tenant behavior on an existing route (e.g. what
  BACKLOG P0-4 fixed — the reverse of a break, but the same class of change).

Not breaking: adding an optional field, adding a new path, widening an
accepted value, adding a new enum member a client can ignore.

## Process

1. Mark the field/path `deprecated: true` in `contracts/openapi.yaml` with an
   `x-siax-deprecated-since` date and a one-line replacement pointer.
2. Keep the deprecated shape working for **at least one release cycle**
   after the replacement ships (see `CHANGELOG.md` once real releases/tags
   exist — BACKLOG P1-3).
3. Announce in `CHANGELOG.md`'s `[Unreleased]` section before merge, not
   after.
4. Only remove once nothing in this repo's own consumers (Protosell/FiveCRM,
   VehIQ per `CLAUDE.md`) is verified to depend on the old shape — "verified"
   means checked against those repos, not assumed silent.

## What this repo does NOT have yet

No consumers are known to be live against this contract yet
(`docs/architecture/ARCHITECTURE.md` §2 "Beroenden nedåt": "Inga sådana
anrop finns i det här repot" — unverified downstream). This policy exists
so the first real breaking change has a process to follow, not because one
has happened.