fix(runtime): return the declarative job handler's JobRunOutcome (#14256)

AppPlugin's declarative-job wrapper awaited the bundle handler inside a
block-bodied arrow and returned nothing, so it was a `Promise<void>` whatever
the handler resolved. #6617's third outcome was therefore unreachable from
`defineJob`: a job that ran to completion while its work did not happen was
recorded as `success` with `reason` dropped, while all three shipped adapters
map a resolved `{ outcome: 'degraded' }` onto a run status distinct from it.

Also drops the read-refusal capture from the new pin's rig: measured on the red
run, no path in that file provokes the tenancy probe, and a capture nothing
provokes asserts a mute.

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

Author: claude

.changeset/declarative-job-run-outcome.md

@@ -0,0 +1,42 @@
+---
+'@objectstack/runtime': patch
+---
+
+fix(runtime): a declarative job's `JobRunOutcome` reaches the adapter that records it (#14256)
+
+`AppPlugin`'s declarative-job registration block handed `IJobService.schedule` a
+block-bodied arrow that *awaited* the bundle handler and returned nothing, so
+the wrapper was a `Promise<void>` whatever the handler resolved. Measured
+through an `IJobService` typed only at the contract:
+
+```
+HANDLER RESOLVED: {"outcome":"degraded","reason":"STORE_UNAVAILABLE"}
+WRAPPER RESOLVED: undefined
+```
+
+#6617's third outcome was therefore unreachable from `defineJob`. All three
+shipped adapters (`cron-job-adapter`, `interval-job-adapter`, `db-job-adapter`)
+map a resolved `{ outcome: 'degraded', reason }` onto a run status distinct from
+`success` — they simply never got the value on this path, so a declarative job
+that ran to completion while its work did not happen (store unavailable, zero
+rows matched) was recorded as `success` with `reason` dropped. The three-outcome
+table in `content/docs/automation/jobs.mdx` — the page whose whole subject is
+the declarative door — was false on exactly that door. The imperative route (a
+handler registered straight on `IJobService.schedule`) was unaffected
+throughout; the wrapper is the whole defect.
+
+The repair is to return the handler's resolved value. Patch rather than minor:
+no export, type, schema or authoring surface changes, and `JobHandler` has
+declared `Promise<void | JobRunOutcome>` since #6617 — this makes the declared
+contract true on a route where it was not. Additive in the ruling's sense: a
+handler resolving `undefined` (every handler written before #6617) still
+resolves `undefined` through the wrapper and still takes the `success` branch.
+The one visible change for an existing app is the correction itself — a
+declarative handler that *was already* resolving `{ outcome: 'degraded' }` now
+lands `sys_job_run.status: 'degraded'` (reason in `error`, `failure_count` flat,
+still never retried) where it previously landed `success`.
+
+Pinned by `packages/runtime/src/app-plugin.job-degraded-outcome.test.ts`, which
+drives the real `DbJobAdapter` over a real ObjectQL engine carrying the real
+`sys_job` / `sys_job_run` declarations and asserts the persisted cell, not the
+wrapper's return value.

packages/runtime/src/app-plugin.job-degraded-outcome.test.ts

@@ -58,23 +58,10 @@ import { DbJobAdapter } from '@objectstack/service-job';
 import { SysJob, SysJobRun } from '@objectstack/platform-objects/audit';
 import { AppPlugin } from './app-plugin.js';
 import type { JobHandlerContext } from './job-handler-context.js';
-import {
-    captureExpectedReadRefusals,
-    type ExpectedReadRefusalCapture,
-} from './expected-read-refusal-noise.js';
 
 /** The reason a #5529-shaped handler reports when its store is unreachable. */
 const REASON = 'STORE_UNAVAILABLE';
 
-/**
- * [#10629] This fixture provisions the two job tables and nothing else, so the
- * engine's own single-tenant probe (`ObjectQL.probeInstallOrganizations`) reads
- * a `sys_organization` that was never created. The probe is fail-soft by
- * construction, but the driver and the engine each log the fault on the way
- * out. Withheld and ASSERTED rather than muted.
- */
-const ABSENT_TENANCY_TABLE = 'sys_organization';
-
 interface Harness {
     engine: ObjectQL;
     adapter: DbJobAdapter;
@@ -90,61 +77,46 @@ const live: Array<{
     engine?: ObjectQL;
     adapter?: DbJobAdapter;
     driver?: SqlDriver;
-    noise?: ExpectedReadRefusalCapture;
-    /** The channels this test's path MUST have provoked — see `harness()`. */
-    requiredChannels?: readonly string[];
 }> = [];
 
 afterEach(async () => {
     for (const entry of live.splice(0)) {
         try { await entry.adapter?.destroy(); } catch { /* noop */ }
         try { await entry.engine?.destroy(); } catch { /* noop */ }
         try { await entry.driver?.disconnect(); } catch { /* noop */ }
-        // A capture nobody asserts is a mute. The probe is memoised behind the
-        // FIRST data operation, so only the paths that actually touch the store
-        // provoke it — `silentChannels(required)` is the API's own answer to a
-        // table read on some of a file's paths and not others. The withholding
-        // is unconditional either way; only the must-have-fired set narrows.
-        if (entry.noise) {
-            expect(entry.noise.silentChannels(entry.requiredChannels ?? [ABSENT_TENANCY_TABLE])).toEqual([]);
-        }
     }
 });
 
-/** A real engine over the migrated test backend, carrying the REAL `sys_job*`. */
-async function bootEngine(): Promise<{ engine: ObjectQL; driver: SqlDriver; noise: ExpectedReadRefusalCapture }> {
+/**
+ * A real engine over the migrated test backend, carrying the REAL `sys_job*`.
+ *
+ * ⚠️ [#10629] No expected-read-refusal capture here, deliberately and by
+ * MEASUREMENT: every read this file performs carries `isSystem`, so the
+ * engine's single-tenant probe over the unprovisioned `sys_organization` never
+ * fires and neither refusal channel emits a frame (checked on the red run: zero
+ * `refused a read on` and zero `Find operation failed` lines for the whole
+ * file). Installing a capture that nothing provokes would assert a mute.
+ */
+async function bootEngine(): Promise<{ engine: ObjectQL; driver: SqlDriver }> {
     const driver = new SqlDriver({
         client: 'better-sqlite3',
         connection: { filename: ':memory:' },
         useNullAsDefault: true,
     });
-    const noise = captureExpectedReadRefusals([ABSENT_TENANCY_TABLE]);
-    noise.captureDriver(driver);
     await driver.initObjects([SysJob as never, SysJobRun as never]);
     const engine = new ObjectQL();
-    noise.captureEngine(engine);
     engine.registerDriver(driver as never, true);
     await engine.init();
     engine.registry.registerObject(SysJob as never);
     engine.registry.registerObject(SysJobRun as never);
-    return { engine, driver, noise };
+    return { engine, driver };
 }
 
-/**
- * @param opts.touchesStore whether this test's path performs a data operation.
- *   `true` (the default) requires the tenancy probe to have fired and been
- *   withheld; the one case that swaps `DbJobAdapter` out for a recording
- *   `IJobService` never reads or writes and passes `false`, which keeps the
- *   withholding and drops only the must-have-fired requirement.
- */
-async function harness(opts: { touchesStore?: boolean } = {}): Promise<Harness> {
-    const { engine, driver, noise } = await bootEngine();
+async function harness(): Promise<Harness> {
+    const { engine, driver } = await bootEngine();
     // The adapter that RECORDS the outcome — the coordinate the card names.
     const adapter = new DbJobAdapter({ engine: engine as never });
-    live.push({
-        engine, adapter, driver, noise,
-        requiredChannels: opts.touchesStore === false ? [] : [ABSENT_TENANCY_TABLE],
-    });
+    live.push({ engine, adapter, driver });
 
     const readyHooks: Array<() => Promise<void>> = [];
     const ctx = {
@@ -306,7 +278,7 @@ describe('#14256 — the controls that keep the assertion honest', () => {
         // The reporter's probe, kept as corroboration and NOT as the deliverable:
         // it re-states the repair, while the cases above pin its consequence.
         // Typed only at the contract, exactly as a third-party `IJobService` is.
-        const h = await harness({ touchesStore: false });
+        const h = await harness();
         const scheduled: Array<{ name: string; handler: JobHandler }> = [];
         const recording: IJobService = {
             async schedule(name: string, _schedule: JobSchedule, handler: JobHandler) {

packages/runtime/src/app-plugin.ts

@@ -1033,7 +1033,26 @@ export class AppPlugin implements Plugin {
                                         ql,
                                         logger: ctx.logger,
                                     };
-                                    await handler(jobContext);
+                                    // #14256: RETURN the handler's resolved
+                                    // value. `JobHandler` is
+                                    // `(context) => Promise<void | JobRunOutcome>`
+                                    // and all three shipped adapters map a
+                                    // resolved `{ outcome: 'degraded', reason }`
+                                    // onto a `sys_job_run.status` distinct from
+                                    // `success` (#6617/#5548). A block-bodied
+                                    // arrow that only awaited made this wrapper
+                                    // a `Promise<void>`, so the third outcome
+                                    // was unreachable from `defineJob`: a job
+                                    // that ran to completion while its work did
+                                    // not happen was recorded as `success` with
+                                    // `reason` dropped, and the three-outcome
+                                    // table in `content/docs/automation/jobs.mdx`
+                                    // was false on the declarative door.
+                                    // A handler that resolves `undefined` — every
+                                    // handler written before #6617 — still returns
+                                    // `undefined` here, which is the `success`
+                                    // branch exactly as before.
+                                    return await handler(jobContext);
                                 },
                                 // #3494: thread the authored retryPolicy/timeout to the adapter
                                 (job.retryPolicy || job.timeout)