69fef7c00e
- how-to: author a host-plugin (external-author guide against the SDK surface) - tutorial: embed GSD in a new host (end-to-end programmatic-cli example) - reference: the Host-Integration Interface (axes, adapters, handshake, profiles) - explanation: interface versioning + deprecation policy (additive vs breaking, PROTOCOL_VERSION bumps, deprecation window) - ADR-1239 Status: Proposed → Accepted (Phases B–E shipped)
60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
# Interface versioning and deprecation policy
|
|
|
|
This explains how the GSD Host-Integration Interface (ADR-1239) evolves over
|
|
time — what is an additive change, what is breaking, how `PROTOCOL_VERSION`
|
|
bumps, and what deprecation window host-plugin authors can rely on. The policy
|
|
exists because a published SDK is a long-term compatibility commitment (Hyrum's
|
|
Law: once external hosts depend on it, the observable behavior is the contract).
|
|
|
|
---
|
|
|
|
## The version knob: `PROTOCOL_VERSION`
|
|
|
|
`PROTOCOL_VERSION` is a positive integer carried by the engine and exchanged in
|
|
every negotiation (in-process and serialized). It governs the negotiated
|
|
capability **set** — which axes, values, and adapter shapes exist. A host
|
|
declares the version it targets; the engine negotiates down to
|
|
`min(host, engine)` and warns when a host declares a newer version than the
|
|
engine (capabilities beyond the engine's version are not trusted).
|
|
|
|
## Additive vs. breaking
|
|
|
|
- **Additive (no version bump required):** adding a new *optional* axis value, a
|
|
new adapter option, or a new reference profile. Existing host-plugins keep
|
|
working — the engine negotiates to their declared version and ignores
|
|
unknowns. Additive changes are the default; the interface prefers growing the
|
|
vocabulary over changing it.
|
|
|
|
- **Breaking (requires a `PROTOCOL_VERSION` bump):** removing or renaming an
|
|
axis, changing an adapter's call/return shape, changing the negotiation result
|
|
shape, or narrowing a value set. A breaking change is never silent — it lands
|
|
behind a version bump so a host that declares the old version negotiates down
|
|
and gets a warning, not a crash.
|
|
|
|
## Deprecation window
|
|
|
|
A value or adapter shape is **deprecated**, not removed, for at least **one
|
|
minor release cycle**. During the window:
|
|
|
|
1. The old form still works at its declared version.
|
|
2. The reference docs mark it deprecated with the successor + the removal version.
|
|
3. The negotiation emits a `warnings` entry when a host uses a deprecated value.
|
|
|
|
Removal is a breaking change and follows the version-bump rule above. The
|
|
`undocumented` sentinel is never deprecated — it is the permanent fail-closed
|
|
fallback for a host that omits an axis.
|
|
|
|
## What this means for host-plugin authors
|
|
|
|
- Pin to a `PROTOCOL_VERSION` and assert on it in your host-plugin's test.
|
|
- Treat unknown axis values / adapter options as additive (ignore, don't crash).
|
|
- Watch negotiation `warnings` — they surface both "host declared a newer
|
|
version" and "host used a deprecated value."
|
|
- The serialized handshake's consistency with the in-process negotiation is
|
|
itself part of the contract: a change that breaks that consistency is breaking.
|
|
|
|
## See also
|
|
|
|
- [Reference: the Host-Integration Interface](../reference/host-integration-interface.md)
|
|
- ADR-1239 (Status: Accepted)
|