Files

Jakub Zych a9a7a328e6 refactor: hard-fork GSD -> MSD (Make Software Done)

Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.

2026-10-06 01:47:40 +02:00

2.8 KiB

Raw Blame History

Interface versioning and deprecation policy

This explains how the MSD 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:

The old form still works at its declared version.
The reference docs mark it deprecated with the successor + the removal version.
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.

2.8 KiB Raw Blame History