Epic: implement ADR-0087 — metadata protocol upgrade contract (handshake · conversion · migration chain)

[os-zhuang]

Tracking epic for landing ADR-0087 (accepted in #2582). The ADR designs how externally developed, AI-agent-maintained metadata apps upgrade stably across protocol majors — arriving from any past version — instead of crashing on a deliberate, gated, documented break.

Why (the problem the ADR closes)

ADR-0059 already guarantees a breaking change cannot leave this repo silently (frozen witnesses + pre-publish hotcrm smoke). What is missing is the consumer side: a package built against protocol N loaded by an N+2 runtime is never told "incompatible — here is the migration"; it runs until some deep .parse() or renderer contract fails. And PluginEnginesSchema.protocol (packages/spec/src/kernel/manifest.zod.ts) — the field that should gate this — is declared, documented, and checked nowhere, an ADR-0078 "declarable-but-inert" violation.

The preference ladder (design, not restated here — see the ADR)

• L0 — don't break: ADR-0059's gates, unchanged.
• L1 — break invisibly: a versioned load-time conversion layer (most breaks need zero consumer action). → P1
• L2 — break executably: a permanent, fixture-tested migration chain, migrate meta --from N replays any past major → current. → P2
• L3 — break loudly & structurally: enforce the engines.protocol handshake with a machine-actionable diagnostic. → P0
• verify: the consumer's own validate && typecheck && test loop is the acceptance test.

Governing constraint: timeliness is never load-bearing (a cross-major consumer was never present for any warning window), and the consumer's maintainer is an AI agent (machine-executability + structure beat human notification).

Phases (independently shippable, evidence-gated)

• P0 — enforce the protocol handshake (D1) · ADR-0087 P0: enforce the protocol handshake (make engines.protocol real) #2644 · install seam in feat(protocol): enforce the engines.protocol handshake (ADR-0087 P0) #2650; load seams (boot rehydration + AppPlugin) / lint nudge / scaffold stamping in feat(protocol): complete ADR-0087 — load-seam handshake, chain backfill 12–15, release artifacts #2972
• P1 — the conversion layer (D2) · ADR-0087 P1: the conversion layer — most breaks require zero consumer action #2645 · shipped in feat(spec,cli): ADR-0087 P1+P2 — conversion layer, migration chain & change manifest #2897; window retirement (retiredFromLoadPath) in feat(protocol): complete ADR-0087 — load-seam handshake, chain backfill 12–15, release artifacts #2972
• P2 — change manifest + migration chain + generated guide (D3, D4 artifacts) · ADR-0087 P2: replayable migration chain + machine-readable change manifest + generated guide #2647 · chain + composeSpecChanges in feat(spec,cli): ADR-0087 P1+P2 — conversion layer, migration chain & change manifest #2897; spec-changes.json release artifact + generated guide (both CI drift-checked) in feat(protocol): complete ADR-0087 — load-seam handshake, chain backfill 12–15, release artifacts #2972; chain backfilled for majors 12–15 in feat(protocol): complete ADR-0087 — load-seam handshake, chain backfill 12–15, release artifacts #2972
• P3 — MCP upgrade surface + RC discipline (D4 tools, D6) · ADR-0087 P3: MCP upgrade surface + RC rehearsal discipline #2648 · deferred, evidence-gated per ADR Boundaries (closed as not planned; reopen when external-consumer demand justifies the surface)

Do not parallelize: P1 depends on P0's PROTOCOL_VERSION + handshake seam; P2/P3 depend on P1. The ADR gates each phase on evidence from the previous.

Boundaries

• Nothing in ADR-0059 changes; the conversion layer converts at load and never rewrites consumer source (that is P2's explicit migrate meta only).
• The consumer-side autonomous-upgrade agent is out of scope (belongs to consumers / ADR-0033 toolchain); this epic makes it possible.

Existing momentum (already in the ADR-0087 direction)

• 11.10.0 (feat(spec): retired-key tombstones + ship CHANGELOG in the npm artifact #2543) shipped retired-key tombstones ("the error IS the guide") + CHANGELOG inside the npm artifact + an llms.txt "Upgrading Across Spec Versions" section — a partial D3/D4 down payment.
• docs(changelog): backfill protocol releases 10.0.0–11.10.0 in the root protocol changelog #2590 backfilled the root protocol CHANGELOG (10.0.0 → 11.10.0), making the deprecation → retirement windows visible end-to-end — the traceability seed for the D4 spec-changes history.

Live deprecation windows to route through the new pipeline (not the old hand-migration path)

These are the first real test subjects for P1/P2 — retire them via a conversion-table entry + chain step, not a bespoke tombstone:

• titleFormat → nameField (deprecated 11.3.0) — ✅ step-11 semantic entry (feat(spec,cli): ADR-0087 P1+P2 — conversion layer, migration chain & change manifest #2897)
• kind: 'jsx' → kind: 'html' (aliased 11.4.0) — ✅ conversion + chain step (feat(spec,cli): ADR-0087 P1+P2 — conversion layer, migration chain & change manifest #2897)
• sqlPredicateToCel SQL-ish RLS predicates → canonical CEL (deprecated 10.0.0) — ✅ step-11 semantic entry (feat(spec,cli): ADR-0087 P1+P2 — conversion layer, migration chain & change manifest #2897)

Refs: ADR-0087, ADR-0059, ADR-0078, ADR-0025 §3.2/§3.10.