Repository navigation
Commit 804a2b0
fix(metadata-core): an exclusive protocol comparator ('>18', '<18') names the major it admits in the refusal (#26595)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"}
-->
_Requested by **Leehom** · [project
thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XCr4VkQzTohFoSHcnQxd1WY)_
Fixes #26546
Clause-②: no
Metadata-protocol: none
## 维护者速读
- **改了什么**:包的 `engines.protocol` 用排他比较符时,`OS_PROTOCOL_INCOMPATIBLE`
拒绝里的目标主版本按比较方向读。在 18 的运行时上,`'>18'` 现在算“包比运行时新”,提示升级运行时到 19,不再给 `migrate
meta`;`'<18'` 现在提示 `migrate meta --from 17`,不再是 `--from 18`。
- **为什么改**:原来把 `>`、`<` 当成 `^` 剥掉,两种写法都得到 `--from
18`,也就是“从运行时自己的主版本迁移”,运维照做没有用。
- **风险与回滚**:低。哪些范围被接受、哪些被拒绝完全不变(新旧读法在 17.8
万组范围与主版本组合上对照,准入结论零差异);只改被拒绝时的目标主版本和提示。附带两处 CLI 读者跟着变对:`objectstack
migrate meta` 迁到 18 时会把 `'<18'` 改写成 `'^18'`(与 `'<=17'`
一致),版本差提示也会为它出声。回滚即 revert 本 PR。
-
**先看**:`packages/metadata-core/src/protocol-handshake.ts`(`alternativeMajorSpan`、`comparatorMajorSpan`、`declaredTargetMajor`);`packages/metadata-core/src/protocol-handshake.test.ts`
末尾的 `[#26546]` 用例。
- **两分钟验证**:`pnpm --filter @objectstack/metadata-core exec vitest run
src/protocol-handshake.test.ts`,预期 46/46 通过,其中 `[#26546]` 九条。
- **需要你做的**:无,席位落地。
## What changes
`checkProtocolCompat` (`@objectstack/metadata-core`) names a refused
range's target major (`diagnostic.targetMajor`, also
`error.details.targetMajor` on both install doors) and, for a package
behind the runtime, `objectstack migrate meta --from N`.
`declaredFloorMajor` found that major by peeling every leading `^ ~ < >
=` and reading the first number, so a comparator's direction was lost.
The single-range grammar is now read once, as a span of admitted majors:
- `comparatorMajorSpan` (was `comparatorAdmitsMajor`) returns the
interval one comparator admits (examples with 18): `'>=18'` is 18 and
up, bare `'>18'` is 19 and up, `'>18.0.0'` is 18 and up, `'<=18'` is 18
and below, `'<18'` / `'<18.0.0'` is 17 and below, `'<18.5'` is 18 and
below. These are exactly the cases the old `switch` encoded.
- `alternativeMajorSpan` (was the body of `alternativeAdmitsMajor`)
returns one `||` alternative's span: compound ranges intersect their
comparators, hyphen ranges are `[lo, hi]`, `^`, `~`, wildcard and exact
pin one major, `*` is open both ways.
- `alternativeAdmitsMajor` asks whether the span holds the runtime
major. `rangeAdmitsMajor` is unchanged.
- `declaredTargetMajor` (was `declaredFloorMajor`) reads the same span:
its floor, or for a range open below, its ceiling. A `||` union still
takes its lowest alternative. A span that holds no major (`'>=19 <15'`,
`'<0'`) names none (`targetMajor: null`, bare `objectstack migrate
meta`).
`checkProtocolCompat`'s ahead/behind split from #26530 is untouched; it
now receives the right major. Answers on an 18 runtime:
| Range | Before | After |
|---|---|---|
| `'>18'` | 18 · `--from 18` | 19 · no `migrateCommand`, "Upgrade the
runtime to protocol 19" |
| `'<18'`, `'<18.0.0'`, `'<18.0'` | 18 · `--from 18` | 17 · `--from 17`
|
| `'<18 >=15'` | 18 · `--from 18` | 15 · `--from 15` |
| `'>15 <18'` | 15 · `--from 15` | 16 · `--from 16` |
| `'<17 \|\| >19'` | 17 · `--from 17` | 16 · `--from 16` |
| `'>18 \|\| ^20'` | 18 · `--from 18` | 19 · no `migrateCommand` |
| `'>=19 <15'` (admits nothing) | 19 · no `migrateCommand` | null ·
`objectstack migrate meta` |
| `'>=19'`, `'<=17'`, `'^17'`, `'~17.2'`, `'17.x'`, `'17'`, `'15 - 17'`,
`'>=15 <18'`, `'^17 \|\| ^16'` | unchanged | unchanged |
On a 17 runtime `'>18'` used to say "Upgrade the runtime to protocol
18", which `'>18'` does not admit; it now says 19. Partial bounds keep
their major: `'<18.5'` on 19 targets 18 and `'>18.1'` on 17 targets 18,
as before.
The comments on `ProtocolIncompatibleDiagnostic.targetMajor` and
`.migrateCommand` now describe the span reading. Changeset:
`@objectstack/metadata-core` patch.
## Why
Card #26546, ruled by triage `6436651479`: on an 18 runtime, `'>18'`
(the package is ahead) and `'<18'` (the package is behind) were both
refused with `migrate meta --from 18`, which cannot apply in either
case. Reading the target from the same span the admit verdict uses means
the verdict and the prescription cannot read one comparator two ways.
## Tests
Red first on `main` at `7dd5a2ffa` (#26530 merged), the new `[#26546]`
block in `protocol-handshake.test.ts`: **7 failed, 38 passed (45)**. The
two inclusive controls (`'>=19'`, `'<=17'`) passed on `main`, as the
ruling expects. The failures were `expected 18 to be 19` (`'>18'`),
`expected 18 to be 17` (`'<18'`), `expected 18 to be 15` (`'<18 >=15'`),
`expected 17 to be 16` (union), and the `'>18'` HTTP answer carrying
`migrateCommand`. After the fix: **46/46** (one more case added after
the red run: a range that admits no major names none).
Ablation (fix committed, `scripts/ablation-replace.mjs`): `const major =
empty ? null : (span.lo ?? span.hi);` in `declaredTargetMajor` replaced
by the old peel, `leadingMajor(alternative.replace(/^[\^~<>=\s]+/,
''))`. Anchor 1 → 0, blob `d918d6077d87` → `10fd32563699`; **8 failed,
38 passed**, every control green. Restored by the tool; `git diff HEAD`
empty afterwards.
Admit verdicts do not move: a one-off differential (scratch script, not
committed) loaded the `main` copy and this copy of
`protocol-handshake.ts` side by side and compared `rangeAdmitsMajor` and
`checkProtocolCompat(...).status` over 8,103 ranges (every operator × 15
version tokens, comma and space compounds of every comparator pair, and
`||` unions) on runtime majors 0 to 21: **178,266 cases, 0
differences**.
Whole package and dependents:
- `@objectstack/metadata-core`: `pnpm test` 836/836 (20 files); `pnpm
typecheck` (`tsc --noEmit` and `-p tsconfig.test.json`) exit 0.
- `@objectstack/cli` (unit): `src/utils/protocol-version-gap.test.ts`
and `test/migrate-meta-protocol-range.test.ts`, 35/35.
- `@objectstack/runtime`:
`src/domains/packages-install-protocol-incompatible.test.ts` and
`src/app-plugin.test.ts`, 44/44.
- `@objectstack/cloud-connection`:
`src/marketplace-install-local-protocol-handshake.test.ts`, 13/13.
- `eslint --no-inline-config` on the two touched `.ts` files: exit 0.
## Acceptance notes
- **Two CLI readers of `targetMajor` change answer for `'<18'`-style
ranges, measured** (throwaway probe in `packages/cli`, not committed;
cli's vitest aliases metadata-core to `src`). `planProtocolRange`
(`objectstack migrate meta`) used to leave `'<18'` alone when migrating
to 18 (target 18 is not below 18, by code reading at `main`); it now
rewrites it to `'^18'` from `--from 17`, and with `--from 18` reports
`behind-from` naming 17, the same answers it gives `'<=17'` and `'^17'`.
`checkProtocolVersionGap` used to stay silent for `'<18'` on an 18
install and now says it "targets protocol v17". `'>18'` stays silent in
both. The runtime's artifact boot refusal (`artifact-reference.ts`)
names `targetMajor` in its "run a runtime image for protocol N" line,
which now reads 19 for `'>18'`. None of these readers' tests moved.
- **Declarations.** `Clause-②: no`: no range moves between admitted and
refused (the differential above), no exported type changes, and
`migrateCommand` was already optional after #26530. `targetMajor`
changes value only on refusals, and for the cases where it was wrong;
the changeset names every changed reading. `Metadata-protocol: none`: no
spec key, schema or stored shape is involved.
- **Spec comment, not this lane.** The `OS_PROTOCOL_INCOMPATIBLE` row
comment in `packages/spec/src/api/error-code-ledger.zod.ts` lists
`migrateCommand` among `error.details` members; it is absent in the
ahead case since #26530, and `'>N'` on an N runtime now reaches that
case. ADR-0087 D1 describes the refusal carrying "the exact replay
command". Both are under the spec seat and are left as they are.
- **No open PR touches `protocol-handshake.ts`**: checked the files of
all 23 open PRs before opening this one.
## Verification
<details><summary>Derived gate families (dispatch-gates.mjs --commands,
run at b17e3c3)</summary>
59 derived, 58 run with exit 0, 1 NOT MEASURED: `pnpm
check:dual-build-cjs-loads` exit 3 (prerequisite not met: it needs a
full workspace build; CI runs it). `node
scripts/check-plugin-teardown-shape.mjs --self-test` first exited 3
because the shallow clone could not read its pinned fixture commit
`621a4876`; after `git fetch origin 621a487…` it exited 0 ("48 cases
pass"). `dispatch-gates.mjs --ran`: "59 derived famil(ies) accounted for
— 58 run, 1 NOT-MEASURED".
The final head `504665209` differs from `b17e3c33` only in one prose
line of the changeset. On the final head, with this body as the event:
`check-adr-0087-registration --base origin/main` exit 0 ("this PR adds
no declared-breaking changeset"); `check-changeset-no-major --base
origin/main --event` exit 0 (`Metadata-protocol: none`, `patch`);
`check-empty-changeset --base origin/main` exit 0; `check:nul-bytes`
exit 0; `check-closing-keyword-parity --body` binds `Fixes #26546` only.
</details>
## Human Minimum
Each item is one rule from
[CONTRIBUTING.md › Human
Minimum](https://github.com/objectstack-ai/objectstack/blob/main/CONTRIBUTING.md#human-minimum),
which links the AGENTS.md text that states it.
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
(No `packages/spec` change.)
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` passes. (Scoped to the touched
files; the repo-wide run is CI's.)
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset.
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed. (Not touched.)
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English.
- [x] The *Before Submitting* list in CONTRIBUTING.md is done.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01FEkQ5p97A4ysuQjSwrSaWT
---
_Generated by [Claude
Code](https://claude.ai/code/session_01FEkQ5p97A4ysuQjSwrSaWT)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent fb91e97 commit 804a2b0
3 files changed
Lines changed: 184 additions & 36 deletions
File tree
- .changeset
- packages/metadata-core/src
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
455 | 455 | | |
456 | 456 | | |
457 | 457 | | |
| 458 | + | |
| 459 | + | |
| 460 | + | |
| 461 | + | |
| 462 | + | |
| 463 | + | |
| 464 | + | |
| 465 | + | |
| 466 | + | |
| 467 | + | |
| 468 | + | |
| 469 | + | |
| 470 | + | |
| 471 | + | |
| 472 | + | |
| 473 | + | |
| 474 | + | |
| 475 | + | |
| 476 | + | |
| 477 | + | |
| 478 | + | |
| 479 | + | |
| 480 | + | |
| 481 | + | |
| 482 | + | |
| 483 | + | |
| 484 | + | |
| 485 | + | |
| 486 | + | |
| 487 | + | |
| 488 | + | |
| 489 | + | |
| 490 | + | |
| 491 | + | |
| 492 | + | |
| 493 | + | |
| 494 | + | |
| 495 | + | |
| 496 | + | |
| 497 | + | |
| 498 | + | |
| 499 | + | |
| 500 | + | |
| 501 | + | |
| 502 | + | |
| 503 | + | |
| 504 | + | |
| 505 | + | |
| 506 | + | |
| 507 | + | |
| 508 | + | |
| 509 | + | |
| 510 | + | |
| 511 | + | |
| 512 | + | |
| 513 | + | |
| 514 | + | |
| 515 | + | |
| 516 | + | |
| 517 | + | |
| 518 | + | |
| 519 | + | |
| 520 | + | |
| 521 | + | |
| 522 | + | |
| 523 | + | |
| 524 | + | |
| 525 | + | |
| 526 | + | |
| 527 | + | |
| 528 | + | |
| 529 | + | |
| 530 | + | |
| 531 | + | |
| 532 | + | |
| 533 | + | |
| 534 | + | |
| 535 | + | |
| 536 | + | |
| 537 | + | |
| 538 | + | |
| 539 | + | |
| 540 | + | |
| 541 | + | |
| 542 | + | |
| 543 | + | |
| 544 | + | |
| 545 | + | |
| 546 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
80 | 80 | | |
81 | 81 | | |
82 | 82 | | |
83 | | - | |
84 | | - | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
85 | 88 | | |
86 | 89 | | |
87 | 90 | | |
88 | 91 | | |
89 | | - | |
90 | | - | |
91 | | - | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
92 | 95 | | |
93 | 96 | | |
94 | 97 | | |
| |||
322 | 325 | | |
323 | 326 | | |
324 | 327 | | |
325 | | - | |
| 328 | + | |
326 | 329 | | |
| 330 | + | |
| 331 | + | |
| 332 | + | |
| 333 | + | |
| 334 | + | |
| 335 | + | |
| 336 | + | |
| 337 | + | |
| 338 | + | |
| 339 | + | |
| 340 | + | |
| 341 | + | |
| 342 | + | |
| 343 | + | |
| 344 | + | |
| 345 | + | |
| 346 | + | |
| 347 | + | |
| 348 | + | |
| 349 | + | |
| 350 | + | |
| 351 | + | |
| 352 | + | |
327 | 353 | | |
328 | | - | |
| 354 | + | |
329 | 355 | | |
330 | | - | |
| 356 | + | |
| 357 | + | |
331 | 358 | | |
332 | 359 | | |
333 | | - | |
| 360 | + | |
| 361 | + | |
334 | 362 | | |
335 | | - | |
336 | | - | |
337 | | - | |
| 363 | + | |
| 364 | + | |
| 365 | + | |
| 366 | + | |
338 | 367 | | |
339 | | - | |
| 368 | + | |
340 | 369 | | |
341 | 370 | | |
342 | 371 | | |
343 | 372 | | |
344 | 373 | | |
345 | 374 | | |
346 | 375 | | |
347 | | - | |
348 | | - | |
| 376 | + | |
349 | 377 | | |
350 | 378 | | |
351 | 379 | | |
352 | | - | |
| 380 | + | |
353 | 381 | | |
354 | 382 | | |
355 | 383 | | |
356 | 384 | | |
357 | 385 | | |
358 | | - | |
| 386 | + | |
359 | 387 | | |
360 | 388 | | |
361 | 389 | | |
362 | 390 | | |
363 | 391 | | |
364 | | - | |
| 392 | + | |
365 | 393 | | |
366 | 394 | | |
367 | 395 | | |
368 | 396 | | |
369 | | - | |
| 397 | + | |
| 398 | + | |
| 399 | + | |
| 400 | + | |
370 | 401 | | |
371 | 402 | | |
372 | 403 | | |
373 | | - | |
| 404 | + | |
374 | 405 | | |
375 | 406 | | |
376 | 407 | | |
377 | 408 | | |
378 | 409 | | |
379 | | - | |
380 | | - | |
381 | | - | |
382 | | - | |
383 | | - | |
384 | | - | |
| 410 | + | |
| 411 | + | |
| 412 | + | |
| 413 | + | |
| 414 | + | |
| 415 | + | |
| 416 | + | |
| 417 | + | |
385 | 418 | | |
386 | | - | |
| 419 | + | |
387 | 420 | | |
388 | 421 | | |
389 | | - | |
390 | | - | |
| 422 | + | |
| 423 | + | |
| 424 | + | |
| 425 | + | |
| 426 | + | |
391 | 427 | | |
392 | 428 | | |
393 | 429 | | |
394 | 430 | | |
395 | 431 | | |
396 | | - | |
| 432 | + | |
| 433 | + | |
397 | 434 | | |
398 | 435 | | |
399 | 436 | | |
| |||
413 | 450 | | |
414 | 451 | | |
415 | 452 | | |
416 | | - | |
| 453 | + | |
417 | 454 | | |
418 | 455 | | |
419 | | - | |
| 456 | + | |
420 | 457 | | |
421 | 458 | | |
422 | | - | |
| 459 | + | |
423 | 460 | | |
424 | 461 | | |
425 | 462 | | |
426 | | - | |
| 463 | + | |
427 | 464 | | |
428 | 465 | | |
429 | 466 | | |
| |||
451 | 488 | | |
452 | 489 | | |
453 | 490 | | |
454 | | - | |
| 491 | + | |
455 | 492 | | |
456 | | - | |
| 493 | + | |
457 | 494 | | |
458 | 495 | | |
459 | 496 | | |
| |||
0 commit comments