[objectstack-fleet]

Requested by Steve · project thread

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.

Ablation: put back "the first scheduler takes the bare key"

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.

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 automation stored references gain a package column, backfilled (R7–R11, R14, R20) (ADR-0150 child 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

• 1. Schemas start as Zod; packages/spec holds no runtime logic.
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint passes.
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
• 6. packages/spec touched: its generated artifacts are regenerated and committed. (Not touched.)
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English.
• The Before Submitting list in CONTRIBUTING.md is done.

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 15 documentable anchor(s).

17 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 82a3ed2e861d260fdd65517e6b17f03c42eb90c2.

⛔ 8 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• the SDK route bridge reached 65 of 231 client-bound route-ledger rows — the other 166 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 166: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 59 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 107 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 28 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 82a3ed2e861d260fdd65517e6b17f03c42eb90c2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from a8e78dcadfc85da09b203c50ab06202158814768 — the merge of head ffa24bd0eb22f067c8176b70b12f6b2889a929cb into base 82a3ed2e861d260fdd65517e6b17f03c42eb90c2, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin a8e78dcadfc85da09b203c50ab06202158814768 && git checkout a8e78dcadfc85da09b203c50ab06202158814768
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 82a3ed2e861d260fdd65517e6b17f03c42eb90c2 ffa24bd0eb22f067c8176b70b12f6b2889a929cb && git checkout -B drift-repro 82a3ed2e861d260fdd65517e6b17f03c42eb90c2 && git merge --no-ff ffa24bd0eb22f067c8176b70b12f6b2889a929cb

node scripts/docs-audit/affected-docs.mjs --json 82a3ed2e861d260fdd65517e6b17f03c42eb90c2

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 82a3ed2e861d260fdd65517e6b17f03c42eb90c2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

epic:#31527#1 · os-steve · session_01ADHkmP7o3uDTti21wLTfPf

Epic red-line review: E7 #31679, head ffa24bd · 2026-11-09T00:34Z

Verdict: PASS. Option A (keep the catalogue key) is accepted as part of this card, not a separate fix.

Red line	Reading
1. Never loosens	jobKeyFor takes the package coordinate. The order is: own in-process key; else this package's own <packageId>:<name> when the catalogue holds it active (readArming); else the authored name when no other package holds it; else the scoped key. A job's package is its scheduler, so no bare name is resolved, and no resolver call is correct here. Nothing is refused, and no key is opened to another package.
2. Ambiguity reported, never guessed	The catalogue is read only for the asking package's own scoped key, and the bare row is never attributed to anyone. A failed read takes today's in-process answer and warns. Base was the silent pick: on S8/S9 a restart's scheduling order handed one package's bare key and run history to another package. The head removes that pick, so the change is inside the card's "stored keys stay readable" and is ADR-0150 D4 (runtime keys by coordinate).
3. Independently releasable	8 of 10 key-table inputs are byte-identical to base. The 2 that differ are exactly the order-dependent restarts, now stable. A job stored under its bare name before this release keeps it. The changeset is a patch, Clause-②: no, with the affected parties stated. Ablations: 3 red.

Seat 3 accepts and lands this after green CI. It is not a governed surface.

[objectstack-fleet]

domain:server#3 · os-steve · session_01ADHkmQXLfvyB5R53VDm3Ka

席位核对 · ACCEPT · #31730 (Fixes #31679, ADR-0150 E7) · 2026-11-09T00:51Z

Head-sha: ffa24bd0eb22f067c8176b70b12f6b2889a929cb

• Form: draft to main; first body line Fixes #31679, the only closing keyword in the body (read); the whole card lands here.
• Premise measured: jobKeyFor takes { packageId, name }; before the scheduling-order fallback it keeps <packageId>:<name> when the job catalogue (readArming, optional on the job service) holds it active; a catalogue read failure warns once and falls back to today's order, never to a guess on another package's key. No resolver call: E7 resolves no bare name (seat read the diff).
• Gates (check-runs on this head): 54 runs, 37 success, 17 skipped, 0 other; Lint & Repo Gates success, TypeScript Type Check success. check-governed-merges --pr 31730: NOT governed, 320 changed lines. K = 2 first-parent commits on main since the PR base.
• Accepted deviations: two of ten key-table inputs differ from base (S8, S9: restarts where base handed one package's catalogue row and run history to another by scheduling order). Seat ruling A, confirmed by the epic seat as the silent pick D4 removes; stated in the PR body under the key table. One forced test edit (the module-top @objectstack/metadata import check:test-source-alias prescribes), named in the body.
• Epic red-line review: PASS 6729440308 at this head.
• Out of scope: none filed. Skills-docs: not owed (Metadata-protocol: none, no narrowing).
• Landing: ready + auto-merge in this stroke. On merge: landing record on runtime/service-job: jobKeyFor on the package coordinate, keeping the bare key readable (ADR-0150 child E7) #31679, pm:dispatched removed, card closed by Fixes.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 42542605342 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

分类：failure —— 按下面的日志分诊。

失败的 job（日志抽取，best effort）：

• Test Core (1/8) — 失败步骤: Run this shard's tests

  @objectstack/cli:test:  FAIL   integration  test/validate-namespace-name.test.ts > ADR-0150 child N — os validate and os build refuse what the package door refuses, in its words > premise: the package
    ↳ 失败原因: @objectstack/cli:test: AssertionError: expected BareNameConflictError: Bare-name conflict… { …(8) } to be undefined
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

⚠️ 断言这一侧有一类例外，判据是断言在测什么，不是它是不是 AssertionError。 断言的对象是产品行为（一个值、一个形状、一次拒收）⇒ 照上面读：真实的行为改变，去查，⛔ 不要重排掉；
断言的对象是这次实验自身的有效性前提（跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件）⇒ 它跟超时是同一类，同样对负载敏感，重排一次是合法的判别手段。
识别是机械的：断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为（真回归）；
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提：它守护的那条不变式当时是绿的，同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量，仍然是时间测量。（⛔ 这只改「怎么读一次红」，不改「哪些测试可以重排」——后者由别处管。）

跨 PR 相同签名（24h，按失败测试文件聚合）：

• test/validate-namespace-name.test.ts — 24h 内已弹出 4 个 PR（feat(objectql)!: a tool holds one name per package (bare-name one holder, after the AI family) #31661、feat(cli)!: a declared multi-replica os start on the redis cluster driver refuses to boot without OS_AUTH_SECRET, instead of minting its own sign-in secret #31718、feat(service-automation): declared connector instances resolve by (package, name) through the shared resolver #31725、fix(runtime): key a packaged job by its package coordinate and keep its catalogue key across a restart (ADR-0150 E7) #31730），但它们同属 1 条投机栈 ⇒ 1 次独立命中。汇总 issue：Queue-flake anchor: test/validate-namespace-name.test.ts #31736（已刷新）
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 14 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)