fix(runtime): a package's jobs stop on uninstall and when a reinstall drops them

The binder's job half records which jobs each app scheduled and cancels the
ones a new version no longer schedules; the runtime.package-jobs uninstall
cleanup, registered on the protocol's registry when a package's jobs are first
scheduled, cancels an uninstalled package's jobs on every uninstall door.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016GiHYRmLSNWTfbX9gVQkpz

Author: claude

packages/cloud-connection/src/marketplace-install-local-jobs.test.ts

@@ -56,9 +56,9 @@ const BODY_JOB = {
 const HANDLER_JOB = { name: 'jobs_app_tick_handler', schedule: INTERVAL, handler: 'tick' };
 
 /** The compiled-artifact shape `os build` writes and `os package install` sends. */
-function artifact(jobs: unknown[] | undefined) {
+function artifact(jobs: unknown[] | undefined, id: string = APP_ID) {
     return {
-        manifest: { id: APP_ID, namespace: 'jobs_app', version: '0.1.0', type: 'app', name: 'Jobs App' },
+        manifest: { id, namespace: 'jobs_app', version: '0.1.0', type: 'app', name: 'Jobs App' },
         objects: [{ name: TICK, label: 'Tick', fields: { name: { type: 'text', label: 'Name' } } }],
         ...(jobs ? { jobs } : {}),
     };
@@ -86,18 +86,53 @@ function recordingEngine() {
 /** `IJobService` as state: what was handed to `schedule`, by job name. */
 function recordingJobService() {
     const scheduled = new Map<string, { run: (c: any) => Promise<unknown>; options: unknown }>();
+    const cancels: string[] = [];
     return {
         scheduled,
+        cancels,
         svc: {
             schedule: vi.fn(async (name: string, _schedule: unknown, run: (c: any) => Promise<unknown>, options?: unknown) => {
                 scheduled.set(name, { run, options });
             }),
-            cancel: async () => undefined,
+            // The adapters' own semantics: `cancel` stops the job and forgets it.
+            cancel: async (name: string) => { cancels.push(name); scheduled.delete(name); },
             trigger: async () => undefined,
         },
     };
 }
 
+/**
+ * The protocol's uninstall-cleanup registry, as its two verbs behave
+ * (`packages/metadata-protocol`, #21490): one cleanup per name, and ONE runner
+ * that calls every registered cleanup with the package id and reports each
+ * outcome. The runner itself is pinned where it lives; this models it so the
+ * door's `DELETE` reaches what the binder registered.
+ */
+function registryProtocol() {
+    const cleanups = new Map<string, (args: { packageId: string }) => Promise<{ success: boolean; removed: number; error?: string }>>();
+    return {
+        registerUninstallCleanup: (name: string, cleanup: any) => { cleanups.set(name, cleanup); },
+        runUninstallCleanups: async (request: { packageId: string }) => {
+            const out: unknown[] = [];
+            for (const [name, cleanup] of cleanups) out.push({ name, ...(await cleanup({ packageId: request.packageId })) });
+            return out;
+        },
+    };
+}
+
+function makeDeleteC(manifestId: string) {
+    const json = vi.fn((payload: any, status?: number) => ({ payload, status: status ?? 200 }));
+    return {
+        req: {
+            url: `http://localhost:3000/api/v1/marketplace/install-local/${manifestId}`,
+            raw: new Request('http://localhost:3000/x'),
+            json: async () => ({}),
+            param: (name: string) => (name === 'manifestId' ? manifestId : undefined),
+        },
+        json,
+    };
+}
+
 /**
  * The package ids handed to `manifest.register` — the plugin also registers its
  * own Setup nav bundle at `kernel:ready`, which is not the package under test.
@@ -158,6 +193,7 @@ async function bootPlugin() {
         auth: installerAuthService(),
         objectql: withInstallerGrants(rec.engine),
         job: jobs.svc,
+        protocol: registryProtocol(),
     };
     const ctx = {
         hook: (e: string, h: any) => hooks.set(e, h),
@@ -174,7 +210,9 @@ async function bootPlugin() {
     await hooks.get('kernel:ready')?.();
     const install = async (bundle: unknown) =>
         rawApp.routes.get('POST /api/v1/marketplace/install-local')!(makeC({ manifest: bundle }));
-    return { install, rec, jobs, register, logger };
+    const uninstall = async (manifestId: string) =>
+        rawApp.routes.get('DELETE /api/v1/marketplace/install-local/:manifestId')!(makeDeleteC(manifestId));
+    return { install, uninstall, rec, jobs, register, logger };
 }
 
 describe('#21489: install-local schedules an installed package’s job bodies', () => {
@@ -215,6 +253,36 @@ describe('#21489: install-local schedules an installed package’s job bodies',
     });
 });
 
+describe('#21489: an uninstalled or replaced package’s jobs STOP', () => {
+    const OTHER_ID = 'com.example.otherjobs';
+    const OTHER_JOB = { ...BODY_JOB, name: 'other_jobs_tick_body' };
+
+    it('DELETE cancels the uninstalled package’s jobs through the uninstall cleanup — and no other package’s', async () => {
+        const { install, uninstall, jobs } = await bootPlugin();
+        expect((await install(artifact([BODY_JOB]))).status).toBe(200);
+        expect((await install(artifact([OTHER_JOB], OTHER_ID))).status).toBe(200);
+
+        const res = await uninstall(APP_ID);
+
+        expect(res.status, JSON.stringify(res.payload)).toBe(200);
+        expect(jobs.cancels).toEqual([BODY_JOB.name]);
+        expect([...jobs.scheduled.keys()], 'the control package’s job keeps running').toEqual([OTHER_JOB.name]);
+        expect(res.payload.data.cleanups).toContainEqual({ name: 'runtime.package-jobs', success: true, removed: 1 });
+    });
+
+    it('a reinstall whose new version DROPS a job cancels it, and keeps the job it still declares', async () => {
+        const { install, jobs } = await bootPlugin();
+        const KEPT = { ...BODY_JOB, name: 'jobs_app_kept' };
+        const GONE = { ...BODY_JOB, name: 'jobs_app_gone' };
+        expect((await install(artifact([KEPT, GONE]))).status).toBe(200);
+
+        expect((await install(artifact([KEPT]))).status).toBe(200);
+
+        expect(jobs.cancels).toEqual([GONE.name]);
+        expect([...jobs.scheduled.keys()]).toEqual([KEPT.name]);
+    });
+});
+
 describe('#21489: install-local refuses an enabled job with no body', () => {
     it('answers 422 VALIDATION_ERROR naming the job, its handler and both remedies — and changes nothing', async () => {
         const { install, rec, jobs, register } = await bootPlugin();

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

@@ -25,7 +25,7 @@
 
 import { describe, it, expect, vi } from 'vitest';
 import type { PluginContext } from '@objectstack/core';
-import { scheduleAppArtifactJobs, collectJobsWithoutBody } from './app-artifact-handlers.js';
+import { scheduleAppArtifactJobs, collectJobsWithoutBody, PACKAGE_JOBS_UNINSTALL_CLEANUP } from './app-artifact-handlers.js';
 import { jobBodyRunnerFactory } from './sandbox/body-runner.js';
 import { QuickJSScriptRunner } from './sandbox/quickjs-runner.js';
 import { AppPlugin } from './app-plugin.js';
@@ -64,36 +64,62 @@ function recordingEngine() {
     };
 }
 
-/** `IJobService` as state: what was handed to `schedule`, by job name. */
-function recordingJobService() {
+/**
+ * `IJobService` as state: what is scheduled right now, by job name — `schedule`
+ * replaces by name and `cancel` removes, the adapters' own semantics — plus
+ * every cancel in order. `failCancel` names a job whose cancel throws.
+ */
+function recordingJobService(opts: { failCancel?: string } = {}) {
     const scheduled = new Map<string, { schedule: unknown; run: (c: any) => Promise<unknown>; options: unknown }>();
+    const cancels: string[] = [];
     return {
         scheduled,
+        cancels,
         svc: {
             schedule: async (name: string, schedule: unknown, run: (c: any) => Promise<unknown>, options?: unknown) => {
                 scheduled.set(name, { schedule, run, options });
             },
-            cancel: async () => undefined,
+            cancel: async (name: string) => {
+                if (name === opts.failCancel) throw new Error(`cannot cancel ${name}`);
+                cancels.push(name);
+                scheduled.delete(name);
+            },
             trigger: async () => undefined,
         },
     };
 }
 
-function harness() {
+/** The protocol's uninstall-cleanup registry as state — the two verbs the binder and the doors use. */
+function recordingProtocol() {
+    const cleanups = new Map<string, (args: { packageId: string }) => Promise<{ success: boolean; removed: number; error?: string }>>();
+    const registrations: string[] = [];
+    return {
+        cleanups,
+        registrations,
+        protocol: {
+            registerUninstallCleanup: (name: string, cleanup: any) => { registrations.push(name); cleanups.set(name, cleanup); },
+        },
+    };
+}
+
+function harness(opts: { failCancel?: string; withProtocol?: boolean } = {}) {
     const engine = recordingEngine();
-    const jobs = recordingJobService();
+    const jobs = recordingJobService({ failCancel: opts.failCancel });
+    const reg = recordingProtocol();
     const logger = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
     const ctx = {
         logger,
         getService: (name: string) => {
             if (name === 'job') return jobs.svc;
+            if (name === 'protocol' && opts.withProtocol) return reg.protocol;
             throw new Error(`no ${name}`);
         },
     } as unknown as PluginContext;
-    const schedule = (bundle: unknown) =>
-        scheduleAppArtifactJobs(ctx, bundle, { appId: APP_ID, ql: engine.ql as any, source: 'Test' });
+    const schedule = (bundle: unknown, appId: string = APP_ID) =>
+        scheduleAppArtifactJobs(ctx, bundle, { appId, ql: engine.ql as any, source: 'Test' });
     const warned = () => logger.warn.mock.calls.map((c) => String(c[0]));
-    return { engine, jobs, logger, ctx, schedule, warned };
+    const errored = () => logger.error.mock.calls.map((c) => String(c[0]));
+    return { engine, jobs, reg, logger, ctx, schedule, warned, errored };
 }
 
 /** A flattened JSON package, as install-local holds it: no `functions`. */
@@ -240,7 +266,7 @@ describe('#21489: scheduleAppArtifactJobs — handler jobs and the door-wide gat
             { name: 'off_handler', schedule: INTERVAL, handler: 'tick', enabled: false },
         ]));
 
-        expect(out).toEqual({ bodies: [], handlers: [], notScheduled: [], failed: [] });
+        expect(out).toEqual({ bodies: [], handlers: [], notScheduled: [], failed: [], cancelled: [] });
         expect(h.jobs.scheduled.size).toBe(0);
     });
 
@@ -258,6 +284,103 @@ describe('#21489: scheduleAppArtifactJobs — handler jobs and the door-wide gat
     });
 });
 
+describe('#21489: re-scheduling replaces — a job the new version does not schedule is CANCELLED', () => {
+    const job = (name: string) => ({ name, schedule: INTERVAL, body: WRITE_BODY });
+
+    it('a reinstall that DROPS a job cancels it, and keeps the one it still declares', async () => {
+        const h = harness();
+        await h.schedule(pkg([job('kept_job'), job('gone_job')]));
+
+        const out = await h.schedule(pkg([job('kept_job')]));
+
+        expect(out.cancelled).toEqual(['gone_job']);
+        expect(h.jobs.cancels).toEqual(['gone_job']);
+        expect([...h.jobs.scheduled.keys()]).toEqual(['kept_job']);
+    });
+
+    it('a version that disables a job, or declares no jobs at all, cancels what it no longer runs', async () => {
+        const h = harness();
+        await h.schedule(pkg([job('a_job'), job('b_job')]));
+
+        const disabled = await h.schedule(pkg([job('a_job'), { ...job('b_job'), enabled: false }]));
+        expect(disabled.cancelled).toEqual(['b_job']);
+
+        const none = await h.schedule(pkg([]));
+        expect(none.cancelled).toEqual(['a_job']);
+        expect(h.jobs.scheduled.size).toBe(0);
+    });
+
+    it("another app's jobs are never cancelled — not even one that took over a name this app once scheduled", async () => {
+        const h = harness();
+        await h.schedule(pkg([job('shared_name'), job('mine_only')]), APP_ID);
+        await h.schedule(pkg([job('shared_name'), job('theirs_only')]), 'com.example.other');
+
+        // This app's next version drops both: only its own remaining job stops.
+        const out = await h.schedule(pkg([]), APP_ID);
+
+        expect(out.cancelled).toEqual(['mine_only']);
+        expect([...h.jobs.scheduled.keys()].sort()).toEqual(['shared_name', 'theirs_only']);
+    });
+
+    it('a cancel that throws is said at error, and the job stays on the record for the next attempt', async () => {
+        const h = harness({ failCancel: 'stuck_job' });
+        await h.schedule(pkg([job('stuck_job')]));
+
+        const first = await h.schedule(pkg([]));
+        expect(first.cancelled).toEqual([]);
+        expect(h.errored().some((m) => m.includes('could NOT be cancelled'))).toBe(true);
+    });
+});
+
+describe('#21489: the uninstall cleanup cancels the uninstalled package\'s jobs', () => {
+    const job = (name: string) => ({ name, schedule: INTERVAL, body: WRITE_BODY });
+
+    it('is registered once per protocol, as runtime.package-jobs, when a package\'s jobs are scheduled', async () => {
+        const h = harness({ withProtocol: true });
+
+        await h.schedule(pkg([job('a_job')]), APP_ID);
+        await h.schedule(pkg([job('b_job')]), 'com.example.other');
+
+        expect(h.reg.registrations).toEqual([PACKAGE_JOBS_UNINSTALL_CLEANUP]);
+        expect(PACKAGE_JOBS_UNINSTALL_CLEANUP).toBe('runtime.package-jobs');
+    });
+
+    it("cancels every job of the uninstalled package and none of another package's", async () => {
+        const h = harness({ withProtocol: true });
+        await h.schedule(pkg([job('a_job'), job('a_other')]), APP_ID);
+        await h.schedule(pkg([job('b_job')]), 'com.example.other');
+        const cleanup = h.reg.cleanups.get(PACKAGE_JOBS_UNINSTALL_CLEANUP)!;
+
+        const result = await cleanup({ packageId: APP_ID });
+
+        expect(result).toEqual({ success: true, removed: 2 });
+        expect(h.jobs.cancels.sort()).toEqual(['a_job', 'a_other']);
+        expect([...h.jobs.scheduled.keys()]).toEqual(['b_job']);
+        // A second uninstall of the same package has nothing left to cancel.
+        await expect(cleanup({ packageId: APP_ID })).resolves.toEqual({ success: true, removed: 0 });
+    });
+
+    it('a package that scheduled nothing is a no-op', async () => {
+        const h = harness({ withProtocol: true });
+        await h.schedule(pkg([job('a_job')]), APP_ID);
+
+        await expect(h.reg.cleanups.get(PACKAGE_JOBS_UNINSTALL_CLEANUP)!({ packageId: 'com.example.never' }))
+            .resolves.toEqual({ success: true, removed: 0 });
+        expect(h.jobs.cancels).toEqual([]);
+    });
+
+    it('a job it could not cancel is an outcome, never a throw — success:false naming the job', async () => {
+        const h = harness({ withProtocol: true, failCancel: 'stuck_job' });
+        await h.schedule(pkg([job('stuck_job'), job('fine_job')]), APP_ID);
+
+        const result = await h.reg.cleanups.get(PACKAGE_JOBS_UNINSTALL_CLEANUP)!({ packageId: APP_ID });
+
+        expect(result.success).toBe(false);
+        expect(result.removed).toBe(1);
+        expect(result.error).toContain('stuck_job');
+    });
+});
+
 describe('#21489: the sandbox job origin', () => {
     it("a job body with no timeoutMs gets the runner's JOB default — not the hook's, not the action's", async () => {
         const runner = new QuickJSScriptRunner({ jobTimeoutMs: 30, hookTimeoutMs: 5_000, actionTimeoutMs: 5_000 });