Compatibility and Deprecation Policy

Goal: keep artifacts, schemas, and plugins stable without freezing progress.

Support window

Runtime (CLI + Studio): we support the current minor and the previous minor (N, N-1) with security fixes. Patch releases may continue beyond that for critical issues only.
Schemas/specs: any v1.* schema stays readable/writable for 18 months or 3 minor releases, whichever is longer. Older schemas remain readable (with warnings) but may be verified read-only.
Plugin API: major versioned via plugin_api. v1 is stable; breaking host API changes land only with a new major and clear migration notes.

Removing/renaming a field, changing its type/units/meaning, altering deterministic defaults, or changing file layout in bundle manifests.
Changing policy/profile defaults in a way that widens attack surface (e.g., disabling taint checks) without an explicit opt-in.
Dropping support for a backend or manifest kind without a documented replacement.

Non-breaking: adding optional fields, adding new file kinds gated by manifest version, adding stricter validation that surfaces clear remediation.

Announce: note in CHANGELOG.md and docs/whats-new.md plus CLI/Studio warning with the planned removal version (e.g., "deprecated in 1.4, removed in 1.6").
Warn: runtime emits a single deprecation warning per session/run; verifiers annotate outputs with taint = deprecated.
Remove: not earlier than two minors after announcement or 6 months (whichever is later). Removals must include migration steps or a compatibility shim.

Older bundles stay verifiable for at least 24 months after publication; verifiers must refuse to mutate them and fail closed on missing hashes.
Bundle schema versions are pinned in manifest.json; verification shims must remain deterministic and tested in the conformance pack.
Viz/spec bundles publish their spec version; each spec version remains supported for two Helix releases after its successor ships.

Schema-breaking PRs require an explicit compatibility review and diff (use helix schema diff) plus targeted tests.
Deprecations must add coverage in the conformance runner so we do not regress support accidentally.
When in doubt, bump the spec version and keep the old reader/writer path intact.