@@ -0,0 +1,12 @@
+---
+"@objectstack/metadata-core": patch
+---
+
+fix(metadata-core): the protocol handshake reads an `engines.protocol` `||` union, so `'^17.7.0 || ^18.0.0'` loads on protocol 18 instead of being refused as incompatible
+
+Clause-②: no
+
+- **What was wrong.** `rangeAdmitsMajor` had no branch for `||`. A union reached the caret branch and was read as a caret on its first alternative, so `'^17.7.0 || ^18.0.0'` answered `OS_PROTOCOL_INCOMPATIBLE` on protocol 18. Every door that runs the ADR-0087 D1 handshake refused it: `sys_packages` boot rehydration, the marketplace install-local POST and rehydrate, and `protocol.installPackage`.
+- **What it does now.** A union admits a major when any alternative admits it. When none does and any alternative is unrecognized (an empty one included, `'^17 ||'`), the union answers `unparsed-range`: the package loads with the existing `[protocol]` warning and is never refused. A union whose every alternative refuses is refused as before. Each alternative is read with the unchanged single-range grammar (caret, tilde, hyphen, comparators, `x`, `*`), so a range without `||` reads exactly as it did.
+- **The refusal's `targetMajor`.** For a refused union it is the lowest alternative's major, whatever order the alternatives are written in, so `'^17 || ^16'` and `'^16 || ^17'` both name `objectstack migrate meta --from 16`. It used to read the first alternative.
+- **The artifact forward-conversion floor.** `parseRangeFloor` reads a union's floor as its lowest alternative's (`'^18.0.0 || ^17.1.0'` → `17.1.0`, as for `'^17.1.0 || ^18.0.0'`), and `null` when an alternative is unreadable. It used to read the first alternative, so a union written high-first opened a narrower conversion window than the same range written low-first.
@@ -1087,4 +1087,23 @@ describe('parseRangeFloor — the range spellings artifacts actually carry', ()
     expect(parseRangeFloor('latest')).toBeNull();
     expect(parseRangeFloor('x'.repeat(200))).toBeNull();
   });
+
+  it('[#24029] a `||` union floors at its lowest alternative, in whatever order it is written', () => {
+    expect(parseRangeFloor('^17.1.0 || ^18.0.0')).toEqual([17, 1, 0]);
+    expect(parseRangeFloor('^18.0.0 || ^17.1.0')).toEqual([17, 1, 0]);
+    expect(parseRangeFloor('>=17.2 <18 || ^17.1.0')).toEqual([17, 1, 0]);
+  });
+
+  it('[#24029] a union with an alternative it cannot read has no known floor: null, like an undeclared range', () => {
+    expect(parseRangeFloor('^17 || workspace:*')).toBeNull();
+    expect(parseRangeFloor('^17 ||')).toBeNull();
+  });
+
+  it('[#24029] the window opens for a descending union exactly as for the same range written ascending', () => {
+    for (const range of ['^17.1.0 || ^18.0.0', '^18.0.0 || ^17.1.0']) {
+      const result = applyArtifactForwardConversions(legacyPermissionDefinition(range), { runtimeSpecVersion: '18.0.0' });
+      expect(result.verdict).toBe('converted-forward');
+      expect(result.authoredFloor).toBe('17.1.0');
+    }
+  });
 });
@@ -30,7 +30,8 @@
  * ## The policy
  *
  * Let `floor` be the lowest version the artifact's declared protocol range
- * admits (the leading version token of `engines.protocol`), and `runtime` the
+ * admits (the leading version token of `engines.protocol`; of a `||` union,
+ * the lowest alternative's — {@link parseRangeFloor}), and `runtime` the
  * `@objectstack/spec` version this process actually runs — its package label.
  * The window is decided PER ENTRY: a registry entry E is replayed when
  *
@@ -326,10 +327,26 @@ export interface ArtifactReplayedRetirement {
  * tooling stamps or the docs teach leads with its floor. A range this cannot
  * read returns `null`, and the caller treats an unreadable floor like an
  * undeclared one — the never-false-reject direction.
+ *
+ * A `||` union admits what any alternative admits (the handshake's reading),
+ * so its floor is the LOWEST alternative's, in whatever order they are written
+ * (`^18.0.0 || ^17.1.0` → 17.1.0, as `^17.1.0 || ^18.0.0`). One alternative
+ * this cannot read, an empty one included, leaves that floor unknown: `null`.
  */
 export function parseRangeFloor(range: string): [number, number, number] | null {
   const r = range.trim();
   if (r === '' || r.length > 128) return null;
+  let lowest: [number, number, number] | null = null;
+  for (const alternative of r.split('||')) {
+    const floor = alternativeFloor(alternative.trim());
+    if (floor === null) return null;
+    if (lowest === null || compareTriples(floor, lowest) < 0) lowest = floor;
+  }
+  return lowest;
+}
+
+/** The floor of one `||` alternative of a range (see {@link parseRangeFloor}). */
+function alternativeFloor(r: string): [number, number, number] | null {
   // Strip a leading range operator (`^`, `~`, `>=`, `>`, `=`, `v`).
   const m = r.match(/^[\^~>=<\s]*v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
   if (!m) return null;
 
@@ -316,3 +316,84 @@ describe('[#21762] protocolIncompatibleAnswer: the one answer every HTTP door gi
     expect(details).not.toHaveProperty('message');
   });
 });
+
+describe('[#24029] a `||` union admits a major when any alternative admits it', () => {
+  const compat = (range: string, major: number) =>
+    checkProtocolCompat({ id: 'p', engines: { protocol: range } }, `${major}.0.0`);
+
+  it('the range bridging 17 to 18 admits both majors and refuses 19', () => {
+    expect(compat('^17.7.0 || ^18.0.0', 18).status).toBe('ok');
+    expect(compat('^17.7.0 || ^18.0.0', 17).status).toBe('ok');
+    expect(compat('^17.7.0 || ^18.0.0', 19).status).toBe('incompatible');
+  });
+
+  it('a union none of whose alternatives admits the major refuses it', () => {
+    expect(rangeAdmitsMajor('^16 || ^17', 18)).toBe(false);
+    expect(compat('^16 || ^17', 18).status).toBe('incompatible');
+  });
+
+  it('an alternative the parser cannot read, beside one that refuses, answers unparsed-range in either order', () => {
+    expect(compat('^16 || workspace:*', 18).status).toBe('unparsed-range');
+    expect(compat('workspace:* || ^16', 18).status).toBe('unparsed-range');
+    // An alternative that admits outranks an unreadable one.
+    expect(compat('workspace:* || ^18', 18).status).toBe('ok');
+  });
+
+  it('each alternative reads with the single-range grammar: hyphen, comparators, x and *', () => {
+    expect(rangeAdmitsMajor('15 - 16 || ^18', 18)).toBe(true);
+    expect(rangeAdmitsMajor('^18 || 15 - 16', 16)).toBe(true);
+    // A hyphen range first: its upper bound is `18`, never the text after it.
+    expect(rangeAdmitsMajor('17 - 18 || ^20', 20)).toBe(true);
+    expect(rangeAdmitsMajor('17 - 18 || ^20', 19)).toBe(false);
+    expect(rangeAdmitsMajor('>=17 <18 || ^19', 19)).toBe(true);
+    expect(rangeAdmitsMajor('>=17 <18 || ^19', 18)).toBe(false);
+    expect(rangeAdmitsMajor('^16 || 18.x', 18)).toBe(true);
+    expect(rangeAdmitsMajor('^16 || *', 18)).toBe(true);
+    expect(rangeAdmitsMajor('^16 || x', 18)).toBe(true);
+    expect(rangeAdmitsMajor('^17||^18', 18)).toBe(true);
+  });
+
+  it('CONTROL: a range with no `||` reads as it always has (caret, hyphen, x and *)', () => {
+    expect(rangeAdmitsMajor('^18', 18)).toBe(true);
+    expect(rangeAdmitsMajor('^18', 17)).toBe(false);
+    expect(rangeAdmitsMajor('17.0.0 - 18.0.0', 18)).toBe(true);
+    expect(rangeAdmitsMajor('16 - 17', 18)).toBe(false);
+    expect(rangeAdmitsMajor('x', 18)).toBe(true);
+    expect(rangeAdmitsMajor('*', 18)).toBe(true);
+    expect(rangeAdmitsMajor('17.x', 18)).toBe(false);
+  });
+
+  it('an empty alternative is unrecognized, never a refusal', () => {
+    expect(rangeAdmitsMajor('^17 ||', 18)).toBeNull();
+    expect(rangeAdmitsMajor('^17 ||', 17)).toBe(true);
+    expect(rangeAdmitsMajor('|| ^18', 18)).toBe(true);
+    expect(rangeAdmitsMajor('|| ^18', 17)).toBeNull();
+    expect(rangeAdmitsMajor('||', 18)).toBeNull();
+  });
+
+  it('a refused union targets its lowest alternative, in whatever order it is written', () => {
+    for (const range of ['^16 || ^17', '^17 || ^16']) {
+      const r = compat(range, 18);
+      expect(r.status).toBe('incompatible');
+      if (r.status !== 'incompatible') continue;
+      expect(r.diagnostic.targetMajor).toBe(16);
+      expect(r.diagnostic.migrateCommand).toBe('objectstack migrate meta --from 16');
+    }
+  });
+
+  it('at the boundary: the bridging range loads silently on 18 and is refused with the 422 envelope on 19', () => {
+    const warn = vi.fn();
+    expect(() => assertProtocolCompat({ id: 'p', engines: { protocol: '^17.7.0 || ^18.0.0' } }, '18.0.0', warn)).not.toThrow();
+    expect(warn).not.toHaveBeenCalled();
+
+    let thrown: unknown;
+    try {
+      assertProtocolCompat({ id: 'p', engines: { protocol: '^17.7.0 || ^18.0.0' } }, '19.0.0', warn);
+    } catch (e) {
+      thrown = e;
+    }
+    expect(isProtocolIncompatibleError(thrown)).toBe(true);
+    expect((thrown as ProtocolIncompatibleError).code).toBe('OS_PROTOCOL_INCOMPATIBLE');
+    expect((thrown as ProtocolIncompatibleError).status).toBe(422);
+  });
+});
@@ -65,7 +65,11 @@ export interface ProtocolIncompatibleDiagnostic {
    */
   protocolVersion: string;
   runtimeMajor: number;
-  /** The declared major the package targets, when a single major is determinable. */
+  /**
+   * The declared major the package targets, when a single major is
+   * determinable: the range's leading version token, and for a `||` union the
+   * 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;
@@ -216,22 +220,49 @@ function leadingMajor(token: string): number | null {
   return m ? Number.parseInt(m[1]!, 10) : null;
 }
 
+/**
+ * The `||` alternatives of a range, each trimmed. A range with no `||` is its
+ * own single alternative, so no single-range reading changes through this.
+ */
+function rangeAlternatives(range: string): string[] {
+  return range.split('||').map((alternative) => alternative.trim());
+}
+
 /**
  * Decide whether a SemVer-ish range admits `runtimeMajor`.
  *
  * Returns `true`/`false` on a positive determination, or `null` when the range
  * shape is not recognized (caller admits with a warning rather than refusing).
  * Protocol compatibility is major-grained by design, so every supported form
  * reduces to "which majors does this admit".
+ *
+ * A `||` union (`'^17.7.0 || ^18.0.0'`, the spelling a package bridging two
+ * protocol majors writes) admits a major when ANY alternative admits it.
+ * When none does and any alternative is unrecognized (an empty one included:
+ * `'^17 ||'`), the union is unrecognized too and answers `null`, because the
+ * alternative this cannot read might be the one that admits. Only a union
+ * whose every alternative refuses answers `false`.
  */
 export function rangeAdmitsMajor(range: string, runtimeMajor: number): boolean | null {
   const r = range.trim();
-  if (r === '' ) return null;
   // A real SemVer range is short. Bounding the length here defuses any
-  // pathological input before it reaches a regex (a manifest's `engines`
-  // string is externally authored, so treat it as untrusted): an overlong
-  // string is simply unrecognized (admit-with-warning), never a slow scan.
+  // pathological input before it reaches a split or a regex (a manifest's
+  // `engines` string is externally authored, so treat it as untrusted): an
+  // overlong string is simply unrecognized (admit-with-warning), never a slow
+  // scan.
   if (r.length > 128) return null;
+  let verdict: boolean | null = false;
+  for (const alternative of rangeAlternatives(r)) {
+    const admits = alternativeAdmitsMajor(alternative, runtimeMajor);
+    if (admits === true) return true;
+    if (admits === null) verdict = null;
+  }
+  return verdict;
+}
+
+/** One `||` alternative: the single-range grammar {@link rangeAdmitsMajor} combines. */
+function alternativeAdmitsMajor(r: string, runtimeMajor: number): boolean | null {
+  if (r === '') return null;
   if (r === '*' || r === 'x' || r === 'latest') return true;
 
   // Compound comparator range, e.g. ">=11.0.0 <13.0.0" (space- or comma-joined).
@@ -284,6 +315,23 @@ export function rangeAdmitsMajor(range: string, runtimeMajor: number): boolean |
   return null;
 }
 
+/**
+ * The major a refused range targets: the major of its leading version token,
+ * 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`.
+ */
+function declaredFloorMajor(range: string): number | null {
+  let lowest: number | null = null;
+  for (const alternative of rangeAlternatives(range)) {
+    const major = leadingMajor(alternative.replace(/^[\^~<>=\s]+/, ''));
+    if (major === null) return null;
+    if (lowest === null || major < lowest) lowest = major;
+  }
+  return lowest;
+}
+
 function comparatorAdmitsMajor(comparator: string, runtimeMajor: number): boolean | null {
   // Peel the operator off by fixed prefix rather than a `\s*(.+)` match, whose
   // whitespace/any-char overlap is a polynomial-ReDoS shape on untrusted input.
@@ -352,7 +400,7 @@ export function checkProtocolCompat(
   }
 
   const packageId = manifest.id ?? '<unknown>';
-  const targetMajor = leadingMajor(declared.range.replace(/^[\^~<>=\s]+/, ''));
+  const targetMajor = declaredFloorMajor(declared.range);
   const migrateCommand =
     targetMajor !== null
       ? `objectstack migrate meta --from ${targetMajor}`