Protocol upgrade guide

Generated at docs build from the ADR-0087 registries on main (@objectstack/spec conversions/ + migrations/): an entry shows here once it merges, before the release that ships it. What a given release shipped is its own copy: every @objectstack/spec release after 17.7.0 carries protocol-upgrade-guide.md in the package and attached to its @objectstack/spec@VERSION GitHub Release; 17.7.0 and earlier carry none.

How to upgrade — from protocol 16 onward

objectstack migrate meta --from <your-major>   # replays every hop from your major to 18, in order
objectstack migrate meta --from 16 --step      # checkpoint after each major (bisect a failure)
objectstack validate && tsc --noEmit && <your tests>   # your own verify loop is the acceptance test

Mechanical rewrites are applied for you and reported as a diff; semantic TODOs are printed with acceptance criteria and are yours to resolve — the chain never auto-applies a change that requires judgment.

The chain's support floor is protocol 16 — 2 majors behind the current protocol 18, and no earlier. A consumer further behind must reach protocol 16 by another path first (an older @objectstack/cli still carries the retired steps) before this command will run. From protocol 16 forward, replaying every remaining hop in one command is the designed-for case — that part of timeliness is never load-bearing (ADR-0087); arriving from before the floor is not supported at all.

Machine-readable equivalents: spec-changes.json (shipped in @objectstack/spec and attached to each GitHub Release) and the structured output of objectstack migrate meta --json.