Repository navigation
Commit f2abd47
fix(runtime): key a packaged job by its package coordinate and keep its catalogue key across a restart (ADR-0150 E7) (#31730)
<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9Uhq1xiHH6Kj5gV173xtyBM)_
Fixes #31679
Clause-②: no
Metadata-protocol: none
ADR-0150 child E7 (epic #31527). Seat: `domain:server#3`.
## 维护者速读
- 改了什么:定时任务在任务服务上的键改由「软件包坐标(包 id + 任务名)」决定;重启时先读任务目录(`sys_job`)里本包自己的
`包id:任务名` 行,仍处于启用状态就沿用它。
-
为什么改:以前裸任务名归「本次启动最先调度的包」,重启时包的加载顺序和安装顺序不同,第一个包的目录行和运行历史就会被第二个包的任务接走(实测见下表
S8/S9)。
- 风险与回滚:只影响两个包声明同名任务、且用数据库任务服务的环境;没有任何请求被拒绝。回滚即还原本 PR,键回到按启动顺序分配。
- 先看:`packages/runtime/src/app-artifact-handlers.ts` 的 `jobKeyFor` 与
`catalogueHoldsScopedKey`;再看 `app-artifact-handlers.jobs.test.ts` 新增的
`ADR-0150 E7` 一组。
- 两分钟验证:`pnpm --filter @objectstack/runtime exec vitest run
src/app-artifact-handlers.jobs.test.ts`,预期 41 个用例全绿。
- 需要你做的:无,席位落地。
## What changes
`jobKeyFor` (`packages/runtime/src/app-artifact-handlers.ts`) now takes
the job's package coordinate, `{ packageId, name }` (ADR-0150 D2/D4),
and answers in this order:
1. the key this package already holds the job under in this process
(unchanged);
2. **new:** the package-scoped key `PACKAGE_ID:NAME`, when the job
catalogue holds it **active**. The reading is `DbJobAdapter.readArming`,
the optional, adapter-local method the schedule trigger already reads.
It is not part of `IJobService`, so a job service without it keeps no
catalogue and gets no reading. Only the asking package's own scoped key
is read: that key names its package, so the reading is about this job
only. The bare row names no package and is never read as anyone's;
3. the authored name, when no other package holds it in this process
(unchanged);
4. the package-scoped key, naming the package that holds the authored
name (unchanged).
So the first holder keeps the bare key and a second keeps its
`PACKAGE_ID:NAME`, as the card and the ADR-0150 execution plan row E7
state. What step 2 adds is that this stays true across a restart that
schedules the packages in another order than they were installed in.
Before, the bare key went to whichever package the boot scheduled first,
so the first package's catalogue row and run history moved to the second
package's job (rows S8 and S9 below).
A cancel clears `active` (a replace that drops the job, or the package's
uninstall), and a runtime that stops does not. So a package that was
uninstalled and later installed alone takes its authored name again
(S10), exactly as before.
A catalogue read that throws is no reading: the job is keyed by this
run's order, as on a job service without a catalogue, and that is said
once at `warn` per job. The job still runs, so this is a functional
degradation, not a durability one.
The catalogue read is awaited before the in-process holder is asked, so
the window between that answer and `claimJobKey` is no wider than
before.
No other file changes. service-job is not edited: `readArming` already
exists there.
### Step 0: the keys today, and on this head (same inputs)
The same scratch harness (never committed) ran on base `b126c130` and
head `fc99b124`. It has one catalogue that outlives a process and one
job service per process. Packages are `a`, `b` and `c`, each declaring
job `t`.
| # | Inputs | Base keys | Head keys |
|:--|:--|:--|:--|
| S1 | one package `a` | `t` | `t` |
| S2 | `a`, then `b` | `b:t`, `t` | `b:t`, `t` |
| S3 | `a`, `b`, `c` | `b:t`, `c:t`, `t` | `b:t`, `c:t`, `t` |
| S4 | `a`, `b`, reinstall `b`, reinstall `a` | `b:t`, `t` | `b:t`, `t`
|
| S5 | `a`, `b`, uninstall `a`, then `c` | `b:t`, `t` | `b:t`, `t` |
| S6 | restart, `a` alone with its stored bare key | `t` | `t` |
| S7 | `a`, `b`; restart in the same order | `b:t`, `t` | `b:t`, `t` |
| S8 | `a`, `b`; restart scheduling `b` first | **`a:t`, `t` (`t` now
runs `b`)** | `b:t`, `t` (`t` runs `a`) |
| S9 | `a`, `b`, uninstall `a`; restart `b` | **`t`** (`b` leaves `b:t`)
| `b:t` |
| S10 | `a`, `b`, uninstall `b`; restart, `b` alone | `t` | `t` |
The keys are byte-identical on base and head for 8 of the 10 inputs:
every input whose keys base keeps stable. S8 and S9 differ. They are the
restarts where base moves a key that the catalogue holds for one package
to another package or another name. Keeping those keys is what the card
asks: "the old bare key and `APPID:jobName` keys stay readable for
stored jobs". Nothing is refused in either case. **Seat 3 ruled option
A:** keeping the catalogue key across a restart falls inside the card's
"stored keys stay readable". S8 and S9 are the base defects this closes.
In S8, base hands the first package's bare key, with its catalogue row
and run history, to the second package's job, and moves the first job to
a new name. In S9, base moves the surviving scoped holder off its
catalogued `b:t` onto the bare `t`, which leaves its run history behind.
## Tests
New top-level `describe` in the existing harness file
`packages/runtime/src/app-artifact-handlers.jobs.test.ts`, called
`ADR-0150 E7: a job's package coordinate keeps the key the job catalogue
holds for it, across a restart`. It has six cases:
- a job stored under its bare key before the upgrade is scheduled under
it again, and fires (the card's pin);
- a restart in the install order keeps every key (control);
- a restart that schedules the second package first hands it its own
scoped key, and each key runs its own package's body;
- a scoped holder whose bare holder was uninstalled keeps its scoped key
across a restart;
- a scoped key the catalogue holds cancelled keeps nothing: the package,
alone after a restart, takes its authored name;
- a catalogue read that fails still schedules the job and warns once.
No existing case was changed: the nine `#21602` cases pass unmodified.
One forced edit to the file: `check:test-source-alias` judges an edited
test file, and this one imports `AppPlugin`, whose source loads
`@objectstack/metadata` dynamically. So the file now carries the gate's
prescribed module-top `import '@objectstack/metadata';`, which pays that
load at collection instead of inside a timed case.
<details><summary>Ablation: put back "the first scheduler takes the bare
key"</summary>
Through `node scripts/ablation-replace.mjs`. The anchor `const
catalogued = await catalogueHoldsScopedKey(svc, coordinate, logger,
tag);` was replaced by `const catalogued = false as boolean;`. The
anchor went from 1 hit to 0, and the blob from `1fb1fd13059d` to
`e0c1c52e8cc3`. The test imports the source, so there is no dist leg.
```
× a restart that schedules the second package FIRST still hands it its own scoped key — never the first package's bare one
× a scoped holder whose bare holder was uninstalled keeps its scoped key across a restart, as it does in-process
× a catalogue read that fails schedules the job anyway, by this run's order, and says so at warn
Tests 3 failed | 38 passed (41)
```
The restore matched the blob at HEAD (`1fb1fd13059d`), and `git diff
HEAD` came back empty.
</details>
## Acceptance notes
ADR-0150 readings:
- **(a)** The phase-1 one-holder tests stay green. Job is not a phase-1
covered type, and `bare-name-one-holder.ts` is untouched. The runtime
suite: 563 files, 9045 passed, 19 skipped.
- **(b)** Bare-name behaviour is unchanged for every name with one
holder: S1, S6 and S10 give the same keys on base and head. No door
addresses a job by bare name. The only readers are the catalogue
(`sys_job.name`) and run history (`sys_job_run`), and they read the key
this card keeps stable.
- **(c)** There is no migration. The catalogue read is read-only and
re-runnable. It reads only the asking package's own scoped key, and
never guesses who holds a bare one.
- **(d)** `Clause-②: no`. No protocol, spec or metadata change, so no
ADR-0087 entry.
Red lines:
1. **Resolution never loosens.** No first-registered fallback is added.
The first-holder-keeps-the-bare-key rule is the ADR row's own reading,
and E7 keeps it as it is. Step 2 removes the case where the order of
first scheduling overrode a stored identity. This card resolves no bare
name to a package: a job is scheduled by its own package, so its
coordinate is known. R's `resolvePackageScopedName` therefore has no
call site here, and no second resolver is written.
2. **Ambiguity is reported, never guessed.** The bare catalogue row
names no package and is never attributed to one.
3. **Independently releasable.** The change is additive and needs no
migration. A job service without `readArming` (the interval and cron
adapters) behaves exactly as before.
Also noted, not filed:
- The `#21602` integration test
(`package-install-local-jobs-shared-name.integration.test.ts`) chose
package ids that sort in install order "so the holder of the bare name
is the same package on both boots". That workaround is no longer
load-bearing.
- S3 #31684 (R14 `sys_job.name` "follows the aligned `jobKeyFor` key")
can rely on the key being stable across restarts.
## Verification
Suites on `fc99b124` (the implementation commit). The final head
`ffa24bd0` adds only the module-top import in the test file, and the
edited file was re-run there (41 passed):
- `pnpm --filter @objectstack/runtime test`: 563 files, 9045 passed, 19
skipped. Exit 0.
- `pnpm --filter @objectstack/runtime typecheck`: exit 0.
- `pnpm --filter @objectstack/service-job test`: 11 files, 121 passed.
Exit 0.
- `pnpm --filter @objectstack/service-job typecheck`: exit 0.
- `npx eslint --no-inline-config packages/runtime`: exit 0.
- `pnpm --filter @objectstack/dogfood test` (full battery, closure built
first): 440 files passed, 3 skipped; 3652 tests passed, 41 skipped. Lock
VERDICT command-exit 0.
- Derived gates (`dispatch-gates --commands` on the final head
`ffa24bd0`): 64 of 64 exit 0. `--ran` reconciliation: 64 derived, 64
run, 0 NOT-MEASURED, 0 UNRUN. (A first round on `fc99b124` caught
`check:test-source-alias` on the edited test file, fixed in `ffa24bd0`.
It also had two prerequisite exit-3s that cleared once the fixture
commit was fetched and the packages were built.)
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` passes.
- [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.
<!-- signed: domain:server#3 · os-steve ·
session_01ADHkmNp8ARUNvemy119dY1 -->
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 1a2361c commit f2abd47
3 files changed
Lines changed: 289 additions & 31 deletions
File tree
- .changeset
- packages/runtime/src
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
30 | 30 | | |
31 | 31 | | |
32 | 32 | | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
33 | 36 | | |
34 | 37 | | |
35 | 38 | | |
| |||
538 | 541 | | |
539 | 542 | | |
540 | 543 | | |
| 544 | + | |
| 545 | + | |
| 546 | + | |
| 547 | + | |
| 548 | + | |
| 549 | + | |
| 550 | + | |
| 551 | + | |
| 552 | + | |
| 553 | + | |
| 554 | + | |
| 555 | + | |
| 556 | + | |
| 557 | + | |
| 558 | + | |
| 559 | + | |
| 560 | + | |
| 561 | + | |
| 562 | + | |
| 563 | + | |
| 564 | + | |
| 565 | + | |
| 566 | + | |
| 567 | + | |
| 568 | + | |
| 569 | + | |
| 570 | + | |
| 571 | + | |
| 572 | + | |
| 573 | + | |
| 574 | + | |
| 575 | + | |
| 576 | + | |
| 577 | + | |
| 578 | + | |
| 579 | + | |
| 580 | + | |
| 581 | + | |
| 582 | + | |
| 583 | + | |
| 584 | + | |
| 585 | + | |
| 586 | + | |
| 587 | + | |
| 588 | + | |
| 589 | + | |
| 590 | + | |
| 591 | + | |
| 592 | + | |
| 593 | + | |
| 594 | + | |
| 595 | + | |
| 596 | + | |
| 597 | + | |
| 598 | + | |
| 599 | + | |
| 600 | + | |
| 601 | + | |
| 602 | + | |
| 603 | + | |
| 604 | + | |
| 605 | + | |
| 606 | + | |
| 607 | + | |
| 608 | + | |
| 609 | + | |
| 610 | + | |
| 611 | + | |
| 612 | + | |
| 613 | + | |
| 614 | + | |
| 615 | + | |
| 616 | + | |
| 617 | + | |
| 618 | + | |
| 619 | + | |
| 620 | + | |
| 621 | + | |
| 622 | + | |
| 623 | + | |
| 624 | + | |
| 625 | + | |
| 626 | + | |
| 627 | + | |
| 628 | + | |
| 629 | + | |
| 630 | + | |
| 631 | + | |
| 632 | + | |
| 633 | + | |
| 634 | + | |
| 635 | + | |
| 636 | + | |
| 637 | + | |
| 638 | + | |
| 639 | + | |
| 640 | + | |
| 641 | + | |
| 642 | + | |
| 643 | + | |
| 644 | + | |
| 645 | + | |
| 646 | + | |
| 647 | + | |
| 648 | + | |
| 649 | + | |
| 650 | + | |
| 651 | + | |
| 652 | + | |
| 653 | + | |
| 654 | + | |
| 655 | + | |
| 656 | + | |
| 657 | + | |
| 658 | + | |
| 659 | + | |
| 660 | + | |
| 661 | + | |
| 662 | + | |
| 663 | + | |
| 664 | + | |
| 665 | + | |
| 666 | + | |
| 667 | + | |
| 668 | + | |
| 669 | + | |
| 670 | + | |
| 671 | + | |
| 672 | + | |
| 673 | + | |
| 674 | + | |
| 675 | + | |
| 676 | + | |
| 677 | + | |
| 678 | + | |
| 679 | + | |
| 680 | + | |
| 681 | + | |
| 682 | + | |
| 683 | + | |
| 684 | + | |
| 685 | + | |
| 686 | + | |
| 687 | + | |
| 688 | + | |
| 689 | + | |
| 690 | + | |
| 691 | + | |
| 692 | + | |
| 693 | + | |
| 694 | + | |
| 695 | + | |
| 696 | + | |
| 697 | + | |
| 698 | + | |
| 699 | + | |
| 700 | + | |
541 | 701 | | |
542 | 702 | | |
543 | 703 | | |
| |||
0 commit comments