Skip to content

Commit f2abd47

Browse files
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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
'@objectstack/runtime': patch
3+
---
4+
5+
fix(runtime): a packaged job keeps the job-service key its catalogue holds for it across a restart (ADR-0150 D4)
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
Who is affected: a runtime where two installed packages declare a job of the same name, on the database-backed job service (`sys_job` / `sys_job_run`). Nothing else moves: a runtime where no two packages share a job name schedules every job under its authored name, as before.
11+
12+
A job's identity is its package coordinate, the package id and the job name. The first package to hold a job name keeps the authored name on the job service, and a second package keeps the package-scoped `<packageId>:<name>`, as before. What changes is a restart. Before, the bare name went to whichever package the boot scheduled first, so a restart that rehydrated the packages in another order than they were installed in handed the first package's catalogue row and run history to the second package's job, and moved the first job under a new name. Now a package whose `<packageId>:<name>` the job catalogue still holds active (scheduled by an earlier run and never cancelled) is scheduled under it again, whatever the order. A job stored under its bare name before this release is scheduled under it again and fires as before. Nothing is refused and no author action is needed.

‎packages/runtime/src/app-artifact-handlers.jobs.test.ts‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,9 @@
3030
*/
3131

3232
import { describe, it, expect, vi } from 'vitest';
33+
// Paid at collection, not inside a clocked case: `AppPlugin` (imported below)
34+
// loads `@objectstack/metadata` dynamically (check:test-source-alias).
35+
import '@objectstack/metadata';
3336
import type { PluginContext } from '@objectstack/core';
3437
import { scheduleAppArtifactJobs, collectJobsWithoutBody, PACKAGE_JOBS_UNINSTALL_CLEANUP } from './app-artifact-handlers.js';
3538
import { jobBodyRunnerFactory } from './sandbox/body-runner.js';
@@ -538,6 +541,163 @@ describe('#21602: two packages declaring the same job name — each job keeps it
538541
});
539542
});
540543

544+
describe('ADR-0150 E7: a job\'s package coordinate keeps the key the job catalogue holds for it, across a restart', () => {
545+
const OTHER = 'com.example.other';
546+
const markedJob = (name: string, marker: string) => ({
547+
name,
548+
schedule: INTERVAL,
549+
body: { ...WRITE_BODY, source: `await ctx.api.object('${TICK}').insert({ name: '${marker}' });` },
550+
});
551+
552+
/**
553+
* One `sys_job` catalogue that outlives a process, read the way
554+
* `DbJobAdapter.readArming` reads it — `schedule` writes the row active,
555+
* `cancel` clears `active`, and a process that stops leaves every row as it
556+
* was — and one job service per process (a restart is a new kernel, so
557+
* nothing of the previous process's in-memory record survives).
558+
*/
559+
function catalogue(opts: { readFails?: boolean } = {}) {
560+
const rows = new Map<string, { active: boolean }>();
561+
const engine = recordingEngine();
562+
const boot = () => {
563+
const scheduled = new Map<string, (c: any) => Promise<unknown>>();
564+
const cleanups = new Map<string, (args: { packageId: string }) => Promise<unknown>>();
565+
const svc = {
566+
schedule: async (name: string, _schedule: unknown, run: (c: any) => Promise<unknown>) => {
567+
scheduled.set(name, run);
568+
rows.set(name, { active: true });
569+
},
570+
cancel: async (name: string) => {
571+
scheduled.delete(name);
572+
const row = rows.get(name);
573+
if (row) row.active = false;
574+
},
575+
trigger: async () => undefined,
576+
readArming: async (name: string) => {
577+
if (opts.readFails) throw new Error('sys_job unreadable');
578+
const row = rows.get(name);
579+
return row ? { active: row.active, schedule: null, lastAliveAt: null } : null;
580+
},
581+
};
582+
const logger = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
583+
const ctx = {
584+
logger,
585+
getService: (name: string) => {
586+
if (name === 'job') return svc;
587+
if (name === 'protocol') return { registerUninstallCleanup: (n: string, f: any) => cleanups.set(n, f) };
588+
throw new Error(`no ${name}`);
589+
},
590+
} as unknown as PluginContext;
591+
return {
592+
logger,
593+
keys: () => [...scheduled.keys()].sort(),
594+
schedule: (packageId: string, marker: string) =>
595+
scheduleAppArtifactJobs(ctx, { ...pkg([markedJob('shared_tick', marker)]), id: packageId }, { appId: packageId, ql: engine.ql as any, source: 'Test' }),
596+
uninstall: (packageId: string) => cleanups.get(PACKAGE_JOBS_UNINSTALL_CLEANUP)!({ packageId }),
597+
/** Fire whatever this process holds under `key` once; the marker its body wrote. */
598+
fire: async (key: string) => {
599+
const before = engine.writes.length;
600+
await scheduled.get(key)!({ jobId: key });
601+
return engine.writes.slice(before).map((w) => (w.data as { name: string }).name);
602+
},
603+
};
604+
};
605+
return { rows, boot };
606+
}
607+
608+
it('a job stored under its bare key before the upgrade is scheduled under it again, and fires', async () => {
609+
const store = catalogue();
610+
// The catalogue as an earlier release left it: the job's row under its authored name.
611+
store.rows.set('shared_tick', { active: true });
612+
613+
const after = store.boot();
614+
const out = await after.schedule(APP_ID, 'mine');
615+
616+
expect(out.bodies).toEqual(['shared_tick']);
617+
expect(after.keys()).toEqual(['shared_tick']);
618+
expect(await after.fire('shared_tick')).toEqual(['mine']);
619+
});
620+
621+
it('a restart in the install order schedules every job under the key it had (control)', async () => {
622+
const store = catalogue();
623+
const first = store.boot();
624+
await first.schedule(APP_ID, 'mine');
625+
await first.schedule(OTHER, 'theirs');
626+
627+
const second = store.boot();
628+
await second.schedule(APP_ID, 'mine');
629+
await second.schedule(OTHER, 'theirs');
630+
631+
expect(second.keys()).toEqual([`${OTHER}:shared_tick`, 'shared_tick']);
632+
expect(await second.fire('shared_tick')).toEqual(['mine']);
633+
expect(await second.fire(`${OTHER}:shared_tick`)).toEqual(['theirs']);
634+
});
635+
636+
it('a restart that schedules the second package FIRST still hands it its own scoped key — never the first package\'s bare one', async () => {
637+
const store = catalogue();
638+
const first = store.boot();
639+
await first.schedule(APP_ID, 'mine');
640+
await first.schedule(OTHER, 'theirs');
641+
642+
const second = store.boot();
643+
await second.schedule(OTHER, 'theirs');
644+
await second.schedule(APP_ID, 'mine');
645+
646+
expect(second.keys()).toEqual([`${OTHER}:shared_tick`, 'shared_tick']);
647+
// Each catalogue row keeps running its OWN package's body.
648+
expect(await second.fire('shared_tick')).toEqual(['mine']);
649+
expect(await second.fire(`${OTHER}:shared_tick`)).toEqual(['theirs']);
650+
// Said once, naming the key and where it came from.
651+
const said = second.logger.info.mock.calls.filter((c) => String(c[0]).includes('keeps its package-scoped identity'));
652+
expect(said).toHaveLength(1);
653+
expect(said[0][1]).toEqual({ appId: OTHER, job: 'shared_tick', scheduledAs: `${OTHER}:shared_tick` });
654+
});
655+
656+
it('a scoped holder whose bare holder was uninstalled keeps its scoped key across a restart, as it does in-process', async () => {
657+
const store = catalogue();
658+
const first = store.boot();
659+
await first.schedule(APP_ID, 'mine');
660+
await first.schedule(OTHER, 'theirs');
661+
await first.uninstall(APP_ID);
662+
expect(first.keys()).toEqual([`${OTHER}:shared_tick`]);
663+
664+
const second = store.boot();
665+
await second.schedule(OTHER, 'theirs');
666+
667+
expect(second.keys()).toEqual([`${OTHER}:shared_tick`]);
668+
expect(await second.fire(`${OTHER}:shared_tick`)).toEqual(['theirs']);
669+
});
670+
671+
it('a scoped key the catalogue holds CANCELLED keeps nothing: the package, alone after a restart, takes its authored name', async () => {
672+
const store = catalogue();
673+
const first = store.boot();
674+
await first.schedule(APP_ID, 'mine');
675+
await first.schedule(OTHER, 'theirs');
676+
await first.uninstall(OTHER);
677+
await first.uninstall(APP_ID);
678+
679+
const second = store.boot();
680+
await second.schedule(OTHER, 'theirs');
681+
682+
expect(second.keys()).toEqual(['shared_tick']);
683+
expect(second.logger.info.mock.calls.some((c) => String(c[0]).includes('keeps its package-scoped identity'))).toBe(false);
684+
});
685+
686+
it('a catalogue read that fails schedules the job anyway, by this run\'s order, and says so at warn', async () => {
687+
const store = catalogue({ readFails: true });
688+
const boot = store.boot();
689+
690+
const out = await boot.schedule(OTHER, 'theirs');
691+
692+
expect(out.bodies).toEqual(['shared_tick']);
693+
expect(out.failed).toEqual([]);
694+
expect(boot.keys()).toEqual(['shared_tick']);
695+
const warned = boot.logger.warn.mock.calls.filter((c) => String(c[0]).includes('could not read the job catalogue'));
696+
expect(warned).toHaveLength(1);
697+
expect(warned[0][1]).toMatchObject({ appId: OTHER, job: 'shared_tick' });
698+
});
699+
});
700+
541701
describe('#21489: the sandbox job origin', () => {
542702
it("a job body with no timeoutMs gets the runner's JOB default — not the hook's, not the action's", async () => {
543703
const runner = new QuickJSScriptRunner({ jobTimeoutMs: 30, hookTimeoutMs: 5_000, actionTimeoutMs: 5_000 });

0 commit comments

Comments
 (0)