fix(runtime): two packages declaring the same job name both run, and uninstalling one stops only its own job

[objectstack-fleet]

Fixes #21602
Clause-②: no

What changes

The metadata registry keys a packaged item by package and name (PACKAGE_ID:JOB_NAME), so two packages may each declare a job called shared_tick. IJobService keys a job by one string and replaces any job with the same name. Before this change, scheduleAppArtifactJobs passed the bare authored name, so the second package's install silently replaced the first package's job.

scheduleAppArtifactJobs (packages/runtime/src/app-artifact-handlers.ts) now asks jobKeyFor for the job service's name for each job. The answers are checked in this order:

1. The key this app already holds the job under. A reinstall replaces its own job and keeps its catalogue row and run history.
2. Otherwise, the authored name, when no other package holds it on this job service.
3. Otherwise, the registry's package-scoped key PACKAGE_ID:JOB_NAME. No authored name can equal it, because JobSchema.name is snake_case and never contains a :. When this branch applies, an info line names the package that holds the authored name and the key used.

The ownership record from the job-half PR (#21584) now maps each authored job name to the key it was scheduled under, per app. retireAppJobs (replace) and the runtime.package-jobs uninstall cleanup cancel by that key, so neither path ever cancels another package's job.

There is no IJobService contract change, no packages/spec change and no packages/services/** change. Function-name resolution for hooks belongs to the maintainer's #21604 decision and is not touched here.

A1: reach, at the public door, on origin/main 045b946256

The new pin packages/cli/test/package-install-local-jobs-shared-name.integration.test.ts was run against the base dist/, before the change. Three packages each declare a body job shared_tick, and each writes rows with its own marker into the host's object. Result: 4 failed, 5 passed.

• ALPHA's job stopped once BETA and GAMMA installed: expected 8 to be greater than 8. ALPHA wrote no new row after the later installs.
• The sys_job catalogue read [ 'shared_tick' ]: one row for three declared jobs.
• ALPHA's job stopped at BETA's uninstall (it had already stopped).
• ALPHA's job did not run after the restart: the rehydrate displaced it again.

A2: census of every reader of the scheduled identity

Found by symbol walk: every IJobService implementation, every caller of schedule / cancel / trigger / replay / getExecutions / listJobs / listExecutionsByStatus outside service-job, and every sys_job / sys_job_run reader.

Reader	Keys by the scheduled name?	What the package-scoped key does to it
IntervalJobAdapter (jobs map; schedule/register/cancel/trigger/getExecutions/listJobs)	yes	An opaque string, used consistently by every verb. No shape check.
CronJobAdapter (jobs map; croner registry name NAMESPACE::NAME)	yes	Same. The registry name already contains ::, so a : in the key is inert.
DbJobAdapter: sys_job row (upsertJobRow / setActive / bumpJob, all where: { name })	yes	The row is named by the key. sys_job.name is unique: 'global', so two coexisting jobs need two strings there.
Run history: sys_job_run.job_name (startRun), in-memory executions, listExecutionsByStatus (jobId: r.job_name)	yes	Run rows carry the key.
core fallback memory-job.ts	yes	Same as the interval adapter.
Handler context { jobId } the adapters pass to a run	yes	Not visible to job code. A handler job's context overrides jobId with the authored name (unchanged line, pinned for a scoped job). A body's ctx carries no job name (jobBodyRunnerFactory logs and tags origin with the authored job.name).
Admin listings	not directly	No REST route or MCP tool in this repo lists, triggers, cancels or replays a package job. The Setup "Background Jobs" grid reads sys_job / sys_job_run through the generic data API (apiMethods: ['get','list']).
Cancel paths: retireAppJobs, the runtime.package-jobs uninstall cleanup	yes	Now cancel by the recorded key, so only the uninstalling or replacing package's job stops.
Other schedulers on the same service (flow-schedule:*, flow-time-relative:*, flow-wait:*, approvals-sla-escalation)	their own names	They never read a package job's name. A snake_case authored name cannot equal theirs, because theirs contain -.
Trigger / replay paths	n/a	No caller for a package job in this repo.
Metrics (jobScheduleFailuresTotal label job), log lines, the binder's own return arrays	authored name	Unchanged. Logs add scheduledAs meta.

What the readers show, measured at the door after the change:

• Single package: sys_job names [shared_tick] and sys_job_run.job_name [shared_tick], the authored name. This matches the pre-change reading of the same phase.
• After two more packages declared the same name: sys_job and sys_job_run both read [com.example.sharedbeta:shared_tick, com.example.sharedgamma:shared_tick, shared_tick]. The first package keeps the authored name, its row and its history. Only the later colliding packages read the scoped identity.

A3: the carrier

JobScheduleOptions (packages/spec/src/contracts/job-service.ts) holds only retryPolicy and timeoutMs, so no existing field can carry the package. The scope rides on the name argument, and only when another package already holds the name. A runtime in which no two packages share a job name schedules every job under its authored name, so its visible names and run history are unchanged. That is pinned in the unit suite and at the door. No reader outside domain:cli needed an edit.

A4: pins

Unit (packages/runtime/src/app-artifact-handlers.jobs.test.ts, new describe block):

• A single package's jobs keep their authored names across a reinstall (control).
• The second package gets PACKAGE_ID:shared_tick, nothing is cancelled, and each key runs its own package's body. The info line names the holder.
• A reinstall of either package replaces only its own job.
• Uninstalling the scoped holder cancels only its scoped key, and uninstalling the bare-name holder cancels only the bare name.
• When the scoped holder's next version drops the job, only its scoped key is cancelled.
• A third package is also scoped. Once the bare-name holder is gone, a newcomer takes the bare name and the scoped holder keeps its key.
• A handler job under a scoped key still receives the authored jobId.
• A failed uninstall cancel names shared_tick (scheduled as PACKAGE_ID:shared_tick).

The #21489 test that pinned last-scheduler-wins (another app's jobs are never cancelled — not even one that took over a name…) pinned exactly the branch this change removes. It is replaced: this app's empty version now cancels its own shared_name and mine_only, and the other app's com.example.other:shared_name and theirs_only keep running.

Install-local, real built packages (package-install-local-jobs-shared-name.integration.test.ts, 9 cases):

• Single-package catalogue reads the authored name.
• ALPHA keeps running after BETA and GAMMA install, and both later jobs run.
• The catalogue shows the scoped identities.
• Uninstalling BETA (a scoped holder) stops BETA only.
• ALPHA and GAMMA run after a restart.
• Uninstalling ALPHA (the bare-name holder) stops ALPHA only.

A5: reverse verification (ablation), run at 07d4deb5fb

• Mutation, through scripts/ablation-replace.mjs in WRAP mode. Anchor { key: `${appId}:${jobName}`, heldBy } (x1 to x0), replaced by { key: jobName, heldBy } (x0 to x1). Blob dc88fbdf0207 changed to e523712b60f5.
• Unit, mutated: 9 failed / 26 passed. Every [finding] Two install-local packages that declare the same job name: the second install silently replaces the first package's job, which stops running, and the door says nothing #21602 collision pin and the rewritten [Decision] install-local: a package's declared jobs are never scheduled — refuse the install, name them in the install answer, or make job handlers declarable bodies (the jobs half of #21322) #21489 cross-app pin went red. The single-package control (a single package: every job is scheduled under its AUTHORED name…) stayed green.
• Dist: pnpm --filter @objectstack/runtime build, then ablation-dist-preflight.mjs @objectstack/runtime 'key: jobName, heldBy' reported the marker present in 2 built files (index.js, index.cjs).
• Install-local, mutated: 4 failed / 5 passed. The same four that were red on base went red again. The single-package catalogue case stayed green.
• Restore: blob after restore dc88fbdf0207 equals blob at HEAD, and git diff HEAD is empty. The restore-leg rebuild was checked with ablation-dist-preflight.mjs … --absent: the marker is absent from all 6 built files and the tree is clean against HEAD. Then unit 35/35 and install-local 9/9.

Tests

Final head 2279c378f6. Its only change from 2f9097c7c2 is a one-line doc comment in app-artifact-handlers.ts.

• Gates. node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 62 commands. All 62 were run on 2279c378f6, each exit 0. --ran reports: 62 derived, 62 run, 0 NOT-MEASURED, 0 UNRUN. I also ran the 5 roster gates whose roster sits under a touched directory (check-changeset-fixed, check:authz-resolver, check:error-code-casing, check:filter-alias-parity, check:route-ledger-census): all exit 0.
• Lint. pnpm lint (full repo, eslint . --no-inline-config) exit 0 on 2279c378f6.
• Runtime unit pins and typecheck on 2279c378f6: app-artifact-handlers.jobs.test.ts 35/35. pnpm --filter @objectstack/runtime typecheck OK.
• Full suites, run on 2f9097c7c2, which has the same source apart from the comment:
  • @objectstack/runtime: 318 files, 4530 passed, 19 skipped.
  • @objectstack/cloud-connection: 36 files, 437 passed.
  • @objectstack/cli --project unit: 255 files, 3745 passed. This includes the tier-partition pin, which classifies the new file as integration.
  • @objectstack/cli typecheck OK. The new test file is in tsconfig.test.json's program (counted with --listFilesOnly).
• Install-local pins on built dist/:
  • package-install-local-jobs.integration.test.ts and …-jobs-shared-name.integration.test.ts: 20/20.
  • package-install-local-uninstall-cleanups.integration.test.ts: 16/16.
• Liveness evidence. pnpm --filter @objectstack/spec exec vitest run --project repo scripts/liveness/evidence.test.ts: 42/42. No exported symbol was renamed. The internal claimJobName became claimJobKey, and no ledger names it.

Acceptance notes

• Collision case only: the later package's job is visible under its scoped key. In sys_job / sys_job_run it reads PACKAGE_ID:JOB_NAME. This is forced by sys_job.name being unique: 'global': two jobs that both run need two strings there. No reader shows a moved name in a runtime where names do not collide, and that is pinned. Clause-②: no is copied from the claim and not re-declared.
• Restart order, read from code, not measured. On a restart, the bare name goes to the first package the boot schedules. Install-local rehydrates in ledger file-name order (readdirSync), while hot installs schedule in install order. Suppose a colliding package that was installed later sorts first. The two then swap names at the restart, and the JOB_NAME row's run history continues with the other package's runs. Both jobs still run. The pin's package ids sort in install order. Carrier: none.
• sys_job.active is not reconciled on boot, read from code, not measured. DbJobAdapter never resets the flag at startup, so a key that nothing schedules after a restart keeps active: true. This already applies to any job dropped between boots. Carrier: none.
• Liveness ledger wording. packages/spec/liveness/job.json's name evidence says the name "is the scheduling key passed to svc.schedule". That is still true except in the collision case. The quoted anchor still resolves (evidence test green). packages/spec is outside this card's lane. Carrier: none.
• [Decision] security(objectql): may a hook's handler name bind to a function another package registered (the engine-wide fallback HookSchema.handler declares), or does name resolution stay inside the hook's own package (#21585 option B) #21604 is not addressed here (hook function-name resolution).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

10 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 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 — 26 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 045b946256d988653fdca185c7fd33d6d86bd78d → packageMentionDocs.

Which tree this was computed on

This run read content/docs from f9574370cabdf7524caefb6ddfea986caf81b0a2 — the merge of head 2279c378f6355f7852a9b8ff54e4a050e171bf68 into base 045b946256d988653fdca185c7fd33d6d86bd78d, 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 f9574370cabdf7524caefb6ddfea986caf81b0a2 && git checkout f9574370cabdf7524caefb6ddfea986caf81b0a2
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 045b946256d988653fdca185c7fd33d6d86bd78d 2279c378f6355f7852a9b8ff54e4a050e171bf68 && git checkout -B drift-repro 045b946256d988653fdca185c7fd33d6d86bd78d && git merge --no-ff 2279c378f6355f7852a9b8ff54e4a050e171bf68

node scripts/docs-audit/affected-docs.mjs --json 045b946256d988653fdca185c7fd33d6d86bd78d

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