fix(runtime,cloud-connection)!: install-local refuses an enabled job whose pull does not bind

collectJobsWithoutBody judges a pull job by the binder's own judgeJobPull
and names an unbindable one with its pullRefusal; describeUnrunnable
gains the pull clause. The door answers 422 VALIDATION_ERROR.

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

@@ -24,6 +24,12 @@
  *     it was found — nothing registered, persisted or scheduled;
  *   - #21585: so does an enabled job whose `body` the declaration refuses (an
  *     expression body, a `body.timeoutMs`), naming the refused key;
+ *   - so does an enabled job whose `pull` does not bind (a mapping the package
+ *     does not declare, one with no `connectorSource`), naming the refusal the
+ *     binder's own `judgeJobPull` gives; a pull naming a declared mapping
+ *     installs and is scheduled, a DISABLED unbindable one installs, and an
+ *     entry an earlier build persisted rehydrates with its unbindable pull job
+ *     withheld and warned by name;
  *   - a package without jobs, and one whose handler-only job is DISABLED,
  *     install unchanged.
  *
@@ -190,12 +196,20 @@ async function bootPlugin() {
     const rawApp = makeRawApp();
     const hooks = new Map<string, any>();
     const logger = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() };
+    // The `automation` service a pull job's run calls (`IAutomationService.pullConnectorSource`).
+    const automation = {
+        pullConnectorSource: vi.fn(async (request: { mapping: string }) => ({
+            mapping: request.mapping, targetObject: 'order', connector: 'orders_api', action: 'request', pulled: 0,
+            summary: { total: 0, processed: 0, created: 0, updated: 0, skipped: 0, errors: 0, ok: 0, cancelled: false },
+        })),
+    };
     const services: Record<string, unknown> = {
         manifest: { register },
         auth: installerAuthService(),
         objectql: withInstallerGrants(rec.engine),
         job: jobs.svc,
         protocol: registryProtocol(),
+        automation,
     };
     const ctx = {
         hook: (e: string, h: any) => hooks.set(e, h),
@@ -214,7 +228,7 @@ async function bootPlugin() {
         rawApp.routes.get('POST /api/v1/marketplace/install-local')!(makeC({ manifest: bundle }));
     const uninstall = async (manifestId: string) =>
         rawApp.routes.get('DELETE /api/v1/marketplace/install-local/:manifestId')!(makeDeleteC(manifestId));
-    return { install, uninstall, rec, jobs, register, logger };
+    return { install, uninstall, rec, jobs, register, logger, automation };
 }
 
 describe('#21489: install-local schedules an installed package’s job bodies', () => {
@@ -378,3 +392,109 @@ describe('#21489: install-local refuses an enabled job with no body', () => {
         expect(jobs.svc.schedule).not.toHaveBeenCalled();
     });
 });
+
+describe('install-local refuses an enabled job whose pull does not bind, by the binder\'s own judgeJobPull', () => {
+    const MAPPING = {
+        name: 'orders_pull',
+        targetObject: TICK,
+        fieldMapping: [{ source: 'id', target: 'name' }],
+        mode: 'upsert',
+        upsertKey: ['name'],
+        connectorSource: { connector: 'orders_api', action: 'request' },
+    };
+    const { connectorSource: _dropped, ...IMPORT_ONLY } = MAPPING;
+    const PULL_JOB = { name: 'jobs_app_pull', schedule: INTERVAL, pull: { mapping: 'orders_pull' } };
+    const UNDECLARED = { ...PULL_JOB, name: 'jobs_app_pull_typo', pull: { mapping: 'orders_pul' } };
+
+    /** The compiled-artifact shape, carrying `mappings` beside `jobs`. */
+    const withMappings = (jobs: unknown[], mappings: unknown[] = [MAPPING]) => ({ ...artifact(jobs), mappings });
+
+    it('a pull naming a mapping the package does not declare answers 422 VALIDATION_ERROR naming the job and the refusal — and changes nothing', async () => {
+        const { install, jobs, register, automation } = await bootPlugin();
+
+        const res = await install(withMappings([BODY_JOB, UNDECLARED]));
+
+        expect(res.status).toBe(422);
+        expect(res.payload.success).toBe(false);
+        expect(res.payload.error.code).toBe('VALIDATION_ERROR');
+        const message: string = res.payload.error.message;
+        expect(message).toContain(`its enabled job '${UNDECLARED.name}' (pull.mapping: this artifact declares no mapping 'orders_pul'`);
+        expect(message).toContain('has a `pull` that does not bind');
+        expect(message).toContain('os validate');
+        // The pull's own clause, never the no-`body` one: a `body` beside a `pull` is refused by the declaration.
+        expect(message).not.toMatch(/give the job a `body`/i);
+        // The runtime is left exactly as it was found.
+        expect(registered(register), 'a refused package must not be registered').toEqual([]);
+        expect(new LocalManifestSource(dir).read(APP_ID).entry, 'nor persisted').toBeNull();
+        expect(jobs.svc.schedule, 'nor any of its jobs scheduled — not even its body job').not.toHaveBeenCalled();
+        expect(automation.pullConnectorSource).not.toHaveBeenCalled();
+    });
+
+    it('a pull whose mapping declares no connectorSource is refused the same way', async () => {
+        const { install, jobs, register } = await bootPlugin();
+
+        const res = await install(withMappings([PULL_JOB], [IMPORT_ONLY]));
+
+        expect(res.status).toBe(422);
+        expect(res.payload.error.code).toBe('VALIDATION_ERROR');
+        expect(res.payload.error.message).toContain(`its enabled job '${PULL_JOB.name}' (pull.mapping: mapping 'orders_pull' declares no connectorSource`);
+        expect(registered(register)).toEqual([]);
+        expect(jobs.svc.schedule).not.toHaveBeenCalled();
+    });
+
+    it('one answer names every kind the door cannot run — the unbindable pull beside a job with no body', async () => {
+        const { install } = await bootPlugin();
+
+        const res = await install(withMappings([HANDLER_JOB, UNDECLARED]));
+
+        expect(res.status).toBe(422);
+        const message: string = res.payload.error.message;
+        expect(message).toContain(`'${HANDLER_JOB.name}' (handler 'tick') has no \`body\``);
+        expect(message).toContain(`'${UNDECLARED.name}' (pull.mapping: `);
+    });
+
+    it('a DISABLED pull job naming an undeclared mapping does not block the install, and is not scheduled', async () => {
+        const { install, jobs, register } = await bootPlugin();
+
+        const res = await install(withMappings([{ ...UNDECLARED, enabled: false }]));
+
+        expect(res.status, JSON.stringify(res.payload)).toBe(200);
+        expect(registered(register)).toEqual([APP_ID]);
+        expect(jobs.svc.schedule).not.toHaveBeenCalled();
+    });
+
+    it('control: a pull naming a declared mapping with a connectorSource installs, is scheduled, and a run pulls that mapping', async () => {
+        const { install, jobs, automation } = await bootPlugin();
+
+        const res = await install(withMappings([PULL_JOB]));
+
+        expect(res.status, JSON.stringify(res.payload)).toBe(200);
+        expect([...jobs.scheduled.keys()]).toEqual([PULL_JOB.name]);
+        await jobs.scheduled.get(PULL_JOB.name)!.run({ jobId: PULL_JOB.name });
+        expect(automation.pullConnectorSource).toHaveBeenCalledTimes(1);
+        expect(automation.pullConnectorSource.mock.calls[0][0]).toMatchObject({ mapping: 'orders_pull' });
+    });
+
+    it('rehydrate — an entry an earlier build persisted with an unbindable pull job: the job is withheld and warned by name, the bindable one scheduled', async () => {
+        const { manifest: meta, ...sections } = withMappings([PULL_JOB, UNDECLARED]);
+        new LocalManifestSource(dir).write({
+            packageId: APP_ID,
+            versionId: 'local',
+            manifestId: APP_ID,
+            version: '0.1.0',
+            manifest: { ...meta, ...sections },
+            installedAt: '2026-01-01T00:00:00.000Z',
+            installedBy: 'admin',
+            withSampleData: false,
+        });
+
+        const { jobs, logger, register } = await bootPlugin();
+
+        expect(registered(register), 'the entry still rehydrates').toEqual([APP_ID]);
+        expect([...jobs.scheduled.keys()]).toEqual([PULL_JOB.name]);
+        const warned = logger.warn.mock.calls.find(([message, meta]) =>
+            String(message).includes('NOT scheduled') && (meta as { job?: string } | undefined)?.job === UNDECLARED.name);
+        expect(warned, 'no warn names the withheld pull job').toBeDefined();
+        expect(String(warned![0])).toContain("pull.mapping: this artifact declares no mapping 'orders_pul'");
+    });
+});

packages/cloud-connection/src/marketplace-install-local-plugin.ts

@@ -166,21 +166,22 @@ const INSTALL_LOCAL_CAPABILITY = 'manage_metadata';
 
 /**
  * [#21489, #21585] The refusal of a package that declares code this door cannot
- * run — an enabled job with no `body` or with a `body` the declaration refuses,
- * a hook with no `body`: `VALIDATION_ERROR` / 422.
+ * run — an enabled job with no `body`, with a `body` the declaration refuses or
+ * with a `pull` that does not bind, a hook with no `body`: `VALIDATION_ERROR` /
+ * 422.
  *
  * The code is the standard catalog's input-validation member. The condition is
  * that the install payload fails this door's acceptance rule — every enabled
- * job carries a `body` that binds, and every hook carries a `body` — and the
- * ledger's admission rule sends a generic validation condition to the standard
- * member rather than to a registered synonym (`error-code-ledger.zod.ts`,
+ * job carries a `body` or a `pull` that binds, and every hook carries a `body`
+ * — and the ledger's admission rule sends a generic validation condition to the
+ * standard member rather than to a registered synonym (`error-code-ledger.zod.ts`,
  * "Registering a new code"). What the author does instead is the prescription
  * the message carries. `PLUGIN_MANIFEST_INVALID` is deliberately not it: that
  * code answers the manifest's identity at this door, and a handler-form job or
  * hook is a valid manifest — `os validate` passes it and `os start --artifact`
- * runs it. One acceptance rule answers one code, so the off-spec job `body`
- * (which `os validate` does refuse) is answered by the same refusal as the rest
- * of the rule rather than splitting it.
+ * runs it. One acceptance rule answers one code, so the off-spec job `body` and
+ * the unbindable `pull` (which `os validate` does refuse) are answered by the
+ * same refusal as the rest of the rule rather than splitting it.
  *
  * The status is 422, not the 400 / 502 split this door uses for an invalid
  * manifest id: the package is well-formed JSON this door cannot process, which
@@ -193,7 +194,7 @@ const UNRUNNABLE_REFUSAL_STATUS = 422;
 
 /** What this door cannot run in a package, as the runtime binder judges it. */
 interface UnrunnableCode {
-    jobs: ReadonlyArray<{ name: string; handler?: string; bodyRefusal?: string }>;
+    jobs: ReadonlyArray<{ name: string; handler?: string; bodyRefusal?: string; pullRefusal?: string }>;
     hooks: ReadonlyArray<{ name: string; handler?: string }>;
 }
 
@@ -207,14 +208,16 @@ const capitalize = (text: string) => text.charAt(0).toUpperCase() + text.slice(1
 /**
  * The refusal sentence: everything the door cannot run, why, and the remedies,
  * one clause per kind — a job with no `body`, a job whose `body` the
- * declaration refuses, a hook with no `body` — in one answer, so the author
- * fixes them all in one pass. Each names the item and the function its
- * `handler` declares (or the declaration's refusal of its `body`).
+ * declaration refuses, a job whose `pull` does not bind, a hook with no `body`
+ * — in one answer, so the author fixes them all in one pass. Each names the
+ * item and the function its `handler` declares (or the refusal of its `body` or
+ * its `pull`).
  */
 function describeUnrunnable(manifestId: string, what: UnrunnableCode): string {
     const clauses: string[] = [];
-    const jobsWithoutBody = what.jobs.filter((j) => j.bodyRefusal === undefined);
-    const jobsWithBadBody = what.jobs.filter((j) => j.bodyRefusal !== undefined);
+    const jobsWithBadPull = what.jobs.filter((j) => j.pullRefusal !== undefined);
+    const jobsWithoutBody = what.jobs.filter((j) => j.pullRefusal === undefined && j.bodyRefusal === undefined);
+    const jobsWithBadBody = what.jobs.filter((j) => j.pullRefusal === undefined && j.bodyRefusal !== undefined);
     if (jobsWithoutBody.length > 0) {
         const one = jobsWithoutBody.length === 1;
         clauses.push(
@@ -236,6 +239,16 @@ function describeUnrunnable(manifestId: string, what: UnrunnableCode): string {
             + "body; the job's time limit is the job's own `timeoutMs`) — `os validate` reports the same refusal.",
         );
     }
+    if (jobsWithBadPull.length > 0) {
+        const one = jobsWithBadPull.length === 1;
+        const list = jobsWithBadPull.map((j) => `'${j.name}' (${j.pullRefusal})`).join('; ');
+        clauses.push(
+            `${one ? 'its enabled job' : `${jobsWithBadPull.length} of its enabled jobs`} ${list} `
+            + `${one ? 'has' : 'have'} a \`pull\` that does not bind, so this install door cannot run ${one ? 'it' : 'them'}: `
+            + 'the job would be installed and never scheduled. Declare the mapping the `pull` names in the package, with '
+            + 'a `connectorSource`, or correct the `pull` as the refusal says — `os validate` refuses the same `pull`.',
+        );
+    }
     if (what.hooks.length > 0) {
         const one = what.hooks.length === 1;
         clauses.push(
@@ -971,7 +984,11 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
         //       - a hook with no `body`: its function-name `handler` can never
         //         name the package's own code on this door, so it installed and
         //         either never fired or bound by name to code the package does
-        //         not ship.
+        //         not ship;
+        //       - a job whose `pull` does not bind (a mapping the package does
+        //         not declare, one with no `connectorSource`): judged by the
+        //         binder's own `judgeJobPull` — it used to install and never be
+        //         scheduled.
         //     The judgements are the runtime binder's own, so the door and the
         //     binder cannot disagree about what this door can run.
         //
@@ -982,8 +999,9 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
         //     a disabled one is never scheduled on any door; every hook is
         //     judged, since a hook has no on/off switch. ⛔ Rehydrate is not
         //     gated, for the id gate's reason: an entry an older build installed
-        //     still rehydrates — its unrunnable job is reported, not run, and its
-        //     hook with no `body` is warned and NOT bound
+        //     still rehydrates — its unrunnable job is reported, not run (an
+        //     unbindable `pull` is warned by the binder and NOT scheduled), and
+        //     its hook with no `body` is warned and NOT bound
         //     ({@link bindArtifactHandlers}).
         const unrunnable = await this.unrunnableCode(ctx, manifest, manifestId);
         if (unrunnable.jobs.length > 0 || unrunnable.hooks.length > 0) {
@@ -1834,9 +1852,11 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
      * [#21489, #21585] The code in `manifest` this door cannot run, which the
      * install route refuses:
      *
-     *   - the enabled jobs with no `body`, or with a `body` the declaration
-     *     refuses (`collectJobsWithoutBody`, which reads the jobs the
-     *     binder schedules and judges a body by the parse the binder binds by);
+     *   - the enabled jobs with no `body`, with a `body` the declaration
+     *     refuses, or with a `pull` that does not bind
+     *     (`collectJobsWithoutBody`, which reads the jobs the binder schedules,
+     *     judges a body by the parse the binder binds by and a pull by the
+     *     binder's own `judgeJobPull`);
      *   - the hooks with no `body` (`collectHooksWithoutBody`, the judgement the
      *     binder withholds by on this door's rehydrate).
      *
@@ -1860,7 +1880,7 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
         if (!collectJobs) {
             ctx.logger?.warn?.(
                 `[MarketplaceInstallLocal] this runtime has no collectJobsWithoutBody — the jobs of ${manifestId} are not judged, `
-                + 'so a job with no runnable `body` installs and is never run. Upgrade @objectstack/runtime alongside @objectstack/cloud-connection.',
+                + 'so a job with no runnable `body` or `pull` installs and is never run. Upgrade @objectstack/runtime alongside @objectstack/cloud-connection.',
             );
         }
         if (!collectHooks) {