# GovOPlaN Compatibility Policy

This document defines the compatibility window that release tooling, module
owners, migration authors, import/export providers, and API maintainers must
preserve. It is the source of truth for deciding whether compatibility code can
be removed.

## Database Upgrades

- A released installation from every tagged `0.1.x` version is a supported
  database upgrade origin.
- The recorded public release-baseline ledger starts at `v0.1.7`; earlier
  `0.1.x` tags predate production installations. If an earlier tagged database
  is encountered, the release must provide or document a compatibility bridge
  instead of silently treating the database as a fresh installation.
- Released migration revision IDs and recorded release heads are immutable.
- Each release must prove an upgrade from every still-supported recorded
  baseline, as well as a fresh installation, before its tag is published.
- Migration-only reconciliation needed by an old database remains available for
  at least one subsequent major release cycle after the corresponding runtime
  compatibility path is removed.

The release-baseline format and commands are documented in
`RELEASE_DEPENDENCIES.md`.

## Configuration And Export Schemas

- Writers emit only the current schema version.
- Readers accept the current schema version and the previous two schema
  versions.
- Older input is rejected with a diagnostic that identifies its version and the
  required staged upgrade or conversion path.
- A module-owned configuration provider must version its input and output
  schema explicitly. It must not infer an old schema from missing fields once a
  versioned schema has shipped.
- Round-trip and upgrade tests must cover all three readable versions before a
  schema change is released.

This window applies to configuration packages, module-owned exports, and other
portable GovOPlaN configuration artifacts. Domain interchange standards with
their own compatibility rules remain governed by the owning module.

## Runtime And API Aliases

- Compatibility aliases must emit an explicit deprecation diagnostic and point
  to the supported replacement.
- New callers must use the canonical contract. In-tree callers may not add new
  uses of a deprecated alias.
- Runtime imports, request fields, response fields, routes, and scope aliases
  carried for the `0.1.x` split line are retired at `0.2`, with migration notes.
- An alias may be removed earlier only when it never shipped in a tag or when a
  security fix requires removal. The release notes must state the exception.
- Database reconciliation code is not a runtime/API alias and follows the
  longer database window above.

## Removal Checklist

Compatibility code can be removed only when all of the following are true:

1. The path is inventoried as a database bridge, portable-schema reader, or
   runtime/API alias.
2. Its minimum retention window has elapsed.
3. In-tree callers and published module manifests use the replacement.
4. Upgrade, import, or API regression tests cover the retained window.
5. Diagnostics and migration notes identify any staged action operators must
   take.

If one condition is not met, version-gate the compatibility path and record its
planned removal release instead of deleting it.
