docs(adr): ADR-0087 — metadata protocol upgrades for AI consumers (conversion over notification, replayable migration chain)#2582
Merged
Conversation
…deprecation pipeline, change manifests) Consumer-facing sequel to ADR-0059: how externally developed metadata apps learn about protocol changes in time and upgrade stably across majors. - D1: enforce the currently-inert engines.protocol handshake (ADR-0078 class) so version mismatch fails fast at load instead of crashing downstream - D2: N-1 deprecation rule + machine-readable deprecation registry surfaced by objectstack validate/doctor in the consumer's own CI - D3: per-release machine-readable spec-changes.json derived from the api-surface snapshot diff - D4: upgrading-to-N.md as a release gate + objectstack migrate meta codemods - D5: RC window on the next dist-tag + advisory community smoke ring Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HjDghc79qFSJkJt2zvBxtU
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
…otification, replayable cross-major migration chain Two review corrections reshape the design: 1. The consumer's maintainer is an AI agent, so human attention is not the scarce resource — machine executability and verifiability are. Notification (CI warnings, prose guides) demoted; a load-time conversion layer (most breaks need zero consumer action), executable migrations, structured fail-fast diagnostics, and an MCP upgrade surface promoted. Framework-side smoke ring dropped in favor of consumer agents pulling RCs and verifying themselves. Includes the PD#12 boundary argument for why a centralized, versioned, expiring conversion table is not a consumer-side dialect fallback. 2. A one-major warning window is worthless to a consumer upgrading across multiple majors. Timeliness is now explicitly non-load-bearing: retired conversions graduate into a permanent, ordered, fixture-tested migration chain; 'migrate meta --from N' replays any past major to current in one command, with per-hop verify checkpoints; per-major change manifests compose into a single from->to view. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HjDghc79qFSJkJt2zvBxtU
os-zhuang
changed the title
os-zhuang
marked this pull request as ready for review
July 4, 2026 15:01
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds ADR-0087, the consumer-facing sequel to ADR-0059: how externally developed metadata apps upgrade stably across protocol majors — designed for the actual consumer population: AI-agent-maintained apps, arriving from any past major, not humans marching one release at a time.
The design ladder (best outcome first):
http_request → httpand the client-react alias removals were 100% convertible — most consumers would have needed zero action. Includes the explicit boundary argument for why a centralized, versioned, loud, tested, expiring conversion table does not violate Prime Directive Add comprehensive test suite for Zod schema validation #12 (it's the owned version history of one contract, not scattered consumer-side dialect fallbacks — and it gives the existing executor fallbacks a retirement path).objectstack migrate meta --from Nreplays any past major → current in one command, with per-hop verify checkpoints for bisection. Timeliness is never load-bearing: a consumer that slept through four majors replays four steps on arrival — no warning window to have missed.engines.protocolhandshake (PluginEnginesSchema, declared but checked nowhere — an ADR-0078 violation) so mismatch is a structured, machine-actionable load-time refusal naming the exact replay command, never a downstream crash.spec-changes.json+ an MCP upgrade surface (spec_changes(from,to),spec_deprecations,spec_migrate(dryRun)); the prose guide becomes a generated projection of the registry.validate && typecheck && testloop is the acceptance test of an autonomous upgrade; rehearsal inverts — consumer agents pull RCs from thenextdist-tag and verify themselves (the blocking hotcrm smoke stays; a framework-side community smoke ring is rejected as the wrong direction).Phased P0–P3, independently shippable, evidence-gated; nothing in ADR-0059 changes.
Revision history in this PR
Verification
node scripts/check-doc-authoring.mjspasses (172 files clean).PluginEnginesSchemainpackages/spec/src/kernel/manifest.zod.tsis unenforced (repo-wide grep),api-surface.jsondiff is PR-gate-only,docs/upgrading-to-11.mdexists by convention only.🤖 Generated with Claude Code
https://claude.ai/code/session_01HjDghc79qFSJkJt2zvBxtU