@@ -0,0 +1,21 @@
+---
+'@objectstack/metadata-core': patch
+---
+
+fix(metadata-core)!: a package built for a NEWER protocol major than the runtime is told to upgrade the runtime, not to run `migrate meta`
+
+Clause-②: no (narrowing)
+Metadata-protocol: none
+
+<!-- adr-0087: not-required (runtime-interface-only packages/metadata-core/src/protocol-handshake.ts#ProtocolIncompatibleDiagnostic) The one narrowing is an output member of a published runtime TypeScript interface: `migrateCommand` on `ProtocolIncompatibleDiagnostic` becomes optional. No Zod schema, no spec declaration and no stored representation carries it, so there is nothing for the metadata migration to rewrite and no tombstone; a TypeScript reader that dereferences the member is told by its compiler. -->
+
+**BREAKING** public-surface narrowing of `@objectstack/metadata-core`: `ProtocolIncompatibleDiagnostic.migrateCommand` changes from `string` to optional, and the `OS_PROTOCOL_INCOMPATIBLE` answer's `error.details` omits `migrateCommand` for a package ahead of the runtime. Shipped as `patch`: it is not a metadata-protocol change.
+
+The `OS_PROTOCOL_INCOMPATIBLE` refusal (422) used to prescribe `objectstack migrate meta --from N` for every refused range, taking N from the range's floor major. For a package declaring `engines.protocol: '^19'` on a protocol-18 runtime that sent the operator to `migrate meta --from 19`, a command that cannot apply: migration only moves metadata forward from an older major.
+
+Now the handshake compares the declared floor major with the runtime's protocol major:
+
+- **Floor major above the runtime's** (the package is ahead): the message names the two remedies that can apply, upgrading the runtime to the package's protocol or installing a build of the package for this runtime's protocol. The diagnostic carries no `migrateCommand`, so `error.details` on `POST /api/v1/packages` and `POST /api/v1/marketplace/install-local` holds `requiredRange`, `rangeSource`, `protocolVersion` and `targetMajor` only.
+- **Floor major at or below the runtime's**: unchanged, and `details.migrateCommand` is present as before.
+
+The refusal's code and status do not change. A reader of `migrateCommand` (TypeScript, or JSON over the wire) treats an absent member as "no command applies; read `message`". No in-repo code outside tests reads it.
@@ -4147,7 +4147,8 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
      * The GET listing still serves the entry, marked not loaded (#21822), to
      * whoever reads it; this line is what the boot itself says. The line owes
      * the consequence and the fix, and carries the handshake's own message,
-     * which names the replay command (`objectstack migrate meta`).
+     * which names the remedy: the replay command (`objectstack migrate meta`),
+     * or for a package ahead of this runtime, the runtime upgrade (#26480).
      */
     private reportProtocolIncompatibleEntry = (
         ctx: PluginContext,
 
@@ -355,3 +355,39 @@ describe('kernel:ready rehydrate of an already-ledgered incompatible entry', ()
         expect(new LocalManifestSource(dir).read(OLD_ID).entry?.version).toBe('2.0.0');
     });
 });
+
+describe('[#26480] a package AHEAD of this runtime is told to upgrade, never to migrate', () => {
+    /** The card's reproduction: a floor major one above the running protocol. */
+    const NEW_MAJOR = PROTOCOL_MAJOR + 1;
+    const AHEAD_ID = 'com.example.qa-p-future';
+    const AHEAD = { ...INCOMPATIBLE, id: AHEAD_ID, engines: { protocol: `^${NEW_MAJOR}` } };
+
+    it('POST install-local: 422 OS_PROTOCOL_INCOMPATIBLE with no migrateCommand, and nothing is installed', async () => {
+        const h = await mount(dir);
+        const res = await h.install({ manifest: AHEAD });
+        expect(res.status, JSON.stringify(res.payload)).toBe(422);
+        expect(ApiErrorSchema.safeParse(res.payload.error).success).toBe(true);
+        const { error } = res.payload;
+        expect(error.code).toBe('OS_PROTOCOL_INCOMPATIBLE');
+        expect(error.details).toEqual({
+            requiredRange: `^${NEW_MAJOR}`,
+            rangeSource: 'engines.protocol',
+            protocolVersion: PROTOCOL_VERSION,
+            targetMajor: NEW_MAJOR,
+        });
+        expect(error.message).not.toContain('migrate meta');
+        expect(error.message).toMatch(new RegExp(`upgrade the runtime to protocol ${NEW_MAJOR}`, 'i'));
+        expectNothingWritten(h);
+    });
+
+    it('the rehydrate line for an already-ledgered entry names the upgrade, not a migration', async () => {
+        seedEntry(AHEAD);
+        const h = await mount(dir);
+        expect(h.bootRegistrations().map((m) => m.id)).not.toContain(AHEAD_ID);
+        const said = h.logger.error.mock.calls.map(([m]) => String(m));
+        expect(said).toHaveLength(1);
+        expect(said[0]).toContain('OS_PROTOCOL_INCOMPATIBLE');
+        expect(said[0]).not.toContain('migrate meta');
+        expect(said[0]).toMatch(new RegExp(`upgrade the runtime to protocol ${NEW_MAJOR}`, 'i'));
+    });
+});
@@ -397,3 +397,61 @@ describe('[#24029] a `||` union admits a major when any alternative admits it',
     expect((thrown as ProtocolIncompatibleError).status).toBe(422);
   });
 });
+
+describe('[#26480] a package AHEAD of this runtime is told to upgrade, never to migrate', () => {
+  // `migrate meta --from N` replays metadata FORWARD from an older major. A
+  // package whose declared floor major is above this runtime's has nothing to
+  // migrate here, so the refusal names the two remedies that can apply.
+  const refuse = (range: string) => {
+    const r = checkProtocolCompat({ id: 'com.acme.future', engines: { protocol: range } }, RT);
+    expect(r.status).toBe('incompatible');
+    if (r.status !== 'incompatible') throw new Error(`'${range}' was not refused under ${RT}`);
+    return r.diagnostic;
+  };
+
+  it('carries no migrateCommand, and the message names the runtime upgrade and a build for this major', () => {
+    const d = refuse('^12');
+    expect(d.code).toBe('OS_PROTOCOL_INCOMPATIBLE');
+    expect(d.targetMajor).toBe(12);
+    expect(d).not.toHaveProperty('migrateCommand');
+    expect(d.message).not.toContain('migrate meta');
+    expect(d.message).toMatch(/upgrade the runtime to protocol 12/i);
+    expect(d.message).toContain("a build of 'com.acme.future' for protocol 11");
+  });
+
+  it('holds five majors ahead, and for a union whose every alternative is ahead', () => {
+    for (const range of ['^16', '>=13', '^13 || ^12']) {
+      const d = refuse(range);
+      expect(d).not.toHaveProperty('migrateCommand');
+      expect(d.message).not.toContain('migrate meta');
+    }
+  });
+
+  it('the HTTP answer carries the four members that apply, and still declares 422', () => {
+    let thrown: unknown;
+    try {
+      assertProtocolCompat({ id: 'com.acme.future', engines: { protocol: '^12' } }, RT, () => {});
+    } catch (e) {
+      thrown = e;
+    }
+    expect(isProtocolIncompatibleError(thrown)).toBe(true);
+    const answer = protocolIncompatibleAnswer(thrown as ProtocolIncompatibleError);
+    expect(answer.status).toBe(422);
+    expect(answer.code).toBe('OS_PROTOCOL_INCOMPATIBLE');
+    expect(answer.details).toEqual({
+      requiredRange: '^12',
+      rangeSource: 'engines.protocol',
+      protocolVersion: RT,
+      targetMajor: 12,
+    });
+    expect(Object.keys(answer.details)).not.toContain('migrateCommand');
+  });
+
+  it('CONTROL: a package behind this runtime keeps its --from prescription', () => {
+    const d = refuse('^10');
+    expect(d.migrateCommand).toBe('objectstack migrate meta --from 10');
+    expect(d.message.endsWith('Run: objectstack migrate meta --from 10')).toBe(true);
+    // A union that reaches back below this runtime still has metadata to move.
+    expect(refuse('^10 || ^12').migrateCommand).toBe('objectstack migrate meta --from 10');
+  });
+});
@@ -84,8 +84,16 @@ export interface ProtocolIncompatibleDiagnostic {
    * lowest of its alternatives', whatever order they are written in.
    */
   targetMajor: number | null;
-  /** The command that resolves the refusal (wired end-to-end by ADR-0087 P2). */
-  migrateCommand: string;
+  /**
+   * The command that resolves the refusal (wired end-to-end by ADR-0087 P2),
+   * present only when there is metadata to move FORWARD: the declared floor
+   * major is at or below the runtime's, or is not determinable. A package
+   * whose floor major is ABOVE the runtime's is ahead of it, and
+   * `migrate meta` cannot help (#26480): the member is absent and `message`
+   * names the two remedies that apply, upgrading the runtime or installing a
+   * build of the package for this runtime's protocol.
+   */
+  migrateCommand?: string;
   message: string;
 }
 
@@ -107,7 +115,8 @@ const PROTOCOL_INCOMPATIBLE_BRAND = Symbol.for('objectstack.metadata-core.protoc
  *
  * The manifest is well-formed, but it declares a range this runtime can never
  * satisfy, and the remedy is to change the body
- * (`objectstack migrate meta --from N`). That is 422, the status
+ * (`objectstack migrate meta --from N`, or for a package ahead of the runtime,
+ * a build of it for this protocol). That is 422, the status
  * {@link SchemaValidationError} maps to in this same package. It is NOT 409:
  * the error-code ledger keeps 409 for refusals that come from environment
  * state, where resubmitting the same body could succeed later. With no
@@ -163,7 +172,10 @@ export function isProtocolIncompatibleError(e: unknown): e is ProtocolIncompatib
 export interface ProtocolIncompatibleAnswer {
   status: ProtocolIncompatibleError['status'];
   code: ProtocolIncompatibleError['code'];
-  /** The error's own prose, unchanged. Its `Run:` command is `details.migrateCommand`. */
+  /**
+   * The error's own prose, unchanged. Its `Run:` command is
+   * `details.migrateCommand`, when that member is present.
+   */
   message: string;
   details: Pick<
     ProtocolIncompatibleDiagnostic,
@@ -182,7 +194,8 @@ export interface ProtocolIncompatibleAnswer {
  * shared resolver instead, the five fields survive only inside the prose.
  *
  * `details` is a CLOSED shape: exactly these five members of
- * {@link ProtocolIncompatibleDiagnostic}, named one by one. ⛔ It is not a
+ * {@link ProtocolIncompatibleDiagnostic}, named one by one, with
+ * `migrateCommand` left out, never `undefined`, when the diagnostic has none. ⛔ It is not a
  * spread of the diagnostic. `packageId` and `runtimeMajor` stay out (the first
  * is the id the caller sent, the second is derivable from `protocolVersion`),
  * `code` is the answer's own member (an envelope puts it in `error.code`, never
@@ -202,7 +215,7 @@ export function protocolIncompatibleAnswer(err: ProtocolIncompatibleError): Prot
       rangeSource: d.rangeSource,
       protocolVersion: d.protocolVersion,
       targetMajor: d.targetMajor,
-      migrateCommand: d.migrateCommand,
+      ...(d.migrateCommand !== undefined ? { migrateCommand: d.migrateCommand } : {}),
     },
   };
 }
@@ -367,7 +380,8 @@ function alternativeAdmitsMajor(r: string, runtimeMajor: number): boolean | null
  * its floor as the upgrade guidance reads it (`'^10'` → 10, `'>=15 <18'` → 15).
  * A `||` union targets its LOWEST alternative's, in whatever order the
  * alternatives are written: `'^16 || ^17'` and `'^17 || ^16'` are one range and
- * get one `migrate meta --from`.
+ * get one `migrate meta --from`. A floor above the runtime's major means the
+ * package is ahead of the runtime, and gets no `migrate meta` at all.
  */
 function declaredFloorMajor(range: string): number | null {
   let lowest: number | null = null;
@@ -438,14 +452,23 @@ export function checkProtocolCompat(
 
   const packageId = manifest.id ?? '<unknown>';
   const targetMajor = declaredFloorMajor(declared.range);
-  const migrateCommand =
-    targetMajor !== null
+  // [#26480] `migrate meta` replays metadata forward from an OLDER major. A
+  // floor above this runtime's major is a package built for a newer protocol:
+  // nothing here can migrate it, so the refusal names what can apply instead.
+  const ahead = targetMajor !== null && targetMajor > runtimeMajor;
+  const migrateCommand = ahead
+    ? undefined
+    : targetMajor !== null
       ? `objectstack migrate meta --from ${targetMajor}`
       : `objectstack migrate meta`;
+  const remedy = ahead
+    ? `The package is built for a newer protocol than this runtime implements. ` +
+      `Upgrade the runtime to protocol ${targetMajor}, or install a build of '${packageId}' for protocol ${runtimeMajor}`
+    : `Run: ${migrateCommand}`;
   const message =
     `package '${packageId}' targets protocol ${declared.range} ` +
     `(${declared.source}) but this runtime is protocol ${protocolVersion}. ` +
-    `This is a major-version break. Run: ${migrateCommand}`;
+    `This is a major-version break. ${remedy}`;
 
   return {
     status: 'incompatible',
@@ -461,7 +484,7 @@ export function checkProtocolCompat(
       protocolVersion,
       runtimeMajor,
       targetMajor,
-      migrateCommand,
+      ...(migrateCommand !== undefined ? { migrateCommand } : {}),
       message,
     },
   };
 
@@ -572,7 +572,8 @@ export class AppPlugin implements Plugin {
         // BEFORE the manifest is decomposed into the registry. A bundle whose
         // declared `engines.protocol` excludes this runtime's major fails boot
         // fast with the structured OS_PROTOCOL_INCOMPATIBLE diagnostic (naming
-        // the `migrate meta` command) instead of crashing later in a schema
+        // the `migrate meta` command, or for a bundle built for a newer
+        // protocol, the runtime upgrade) instead of crashing later in a schema
         // `.parse()` or renderer contract. Absent/unparsable ranges are admitted
         // with a warning (grandfathering; never a false rejection).
         assertProtocolCompat(sys, undefined, (m) => ctx.logger.warn(`[AppPlugin] ${m}`));
 
@@ -204,3 +204,30 @@ describe('POST /api/v1/packages: the no-protocol-service fallback runs the same
         expect(d.registry.getPackage(COMPATIBLE.id)).toBeDefined();
     });
 });
+
+describe('[#26480] POST /api/v1/packages: a package AHEAD of this runtime is told to upgrade, never to migrate', () => {
+    /** The card's reproduction: a floor major one above the running protocol. */
+    const NEW_MAJOR = PROTOCOL_MAJOR + 1;
+    const AHEAD = { ...INCOMPATIBLE, id: 'com.example.qa-p-future', engines: { protocol: `^${NEW_MAJOR}` } };
+
+    for (const arm of ['protocol service', 'no-protocol-service fallback'] as const) {
+        it(`${arm}: the same 422 OS_PROTOCOL_INCOMPATIBLE, with no migrateCommand and the runtime upgrade named`, async () => {
+            const d = door(arm === 'protocol service' ? {} : { protocol: null });
+            const r: any = await install(d, AHEAD);
+            expect(r.response.status).toBe(422);
+            const error = r.response.body.error;
+            expect(error.code).toBe('OS_PROTOCOL_INCOMPATIBLE');
+            expect(error.httpStatus).toBe(422);
+            expect(ApiErrorSchema.safeParse(error).success).toBe(true);
+            expect(error.details).toEqual({
+                requiredRange: `^${NEW_MAJOR}`,
+                rangeSource: 'engines.protocol',
+                protocolVersion: PROTOCOL_VERSION,
+                targetMajor: NEW_MAJOR,
+            });
+            expect(error.message).not.toContain('migrate meta');
+            expect(error.message).toMatch(new RegExp(`upgrade the runtime to protocol ${NEW_MAJOR}`, 'i'));
+            expect(d.registry.getPackage(AHEAD.id)).toBeUndefined();
+        });
+    }
+});