fix(runtime): return the declarative job handler's JobRunOutcome so a degraded run is recorded

[os-trump]

Fixes #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
resolved undefined whatever the handler resolved. JobHandler has been declared as
resolving either void or a JobRunOutcome since #6617, and 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 received the value on this path. The reporter's probe, driven through an
IJobService typed only at the contract:

HANDLER RESOLVED: {"outcome":"degraded","reason":"STORE_UNAVAILABLE"}
WRAPPER RESOLVED: undefined

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, and 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. Per the card, the page is deliberately left alone: the code is the
honest repair.

The change

packages/runtime/src/app-plugin.ts — return await handler(jobContext); in place of
the discarding await, with a comment naming why the value is load-bearing. That is the
whole production diff.

The deliverable: the regression test

packages/runtime/src/app-plugin.job-degraded-outcome.test.ts (6 cases) pins the
consequence, not the repair. It boots a real ObjectQL engine over the migrated
sqlite :memory: backend carrying the real sys_job / sys_job_run declarations,
registers the job through AppPlugin from a defineStack-shaped bundle, and runs it the
way the scheduler does — DbJobAdapter.trigger, never a direct handler call. Every
primary assertion reads the persisted cell:

• sys_job_run.status asserted not to be success first (the card's own wording, and
  the contract's), then to be degraded, with the reason in error;
• the mirror onto sys_job.last_status / last_error, with failure_count flat —
  degraded is not a failure and never retries;
• the same through the { handler, effect } function form.

Kept in packages/runtime rather than packages/services/service-job: the defect is in
AppPlugin, and @objectstack/service-job is already a devDependency of
@objectstack/runtime and is aliased to source by that package's vitest.config.ts, so
the recording adapter is reachable from the package that owns the bug. Driving the real
engine (rather than a recording double) also proves the status the adapter writes is a
value the enforced sys_job_run.status Field.select vocabulary accepts, and it adds no
engine double to the check:engine-double-contract ledger.

Two in-suite controls keep the assertion honest, plus one corroborating middle term:

• imperative route — the same degraded handler registered straight on
  IJobService.schedule records degraded with no AppPlugin in the path. Green before
  this change and green after, so a red on the declarative cases localises to the wrapper
  rather than to DbJobAdapter or the sys_job_run write;
• additivity — a handler resolving nothing still lands success, which is also what
  rules out the rig writing degraded unconditionally;
• middle term — the wrapper handed to a contract-typed recording IJobService
  resolves the handler's outcome. Corroboration only: on its own it would re-state the
  repair rather than pin its consequence.

The rig deliberately installs no expected-read-refusal capture: measured on the red
run, every read in the file carries isSystem, the tenancy probe never fires, and neither
refusal channel emits a frame — a capture nothing provokes would assert a mute.

Red-first, with the mutation and the restore both proven

Ablation run from the committed state, as one script holding the shared verify lock, with
a trap … EXIT INT TERM on an absolute path:

HEAD blob for packages/runtime/src/app-plugin.ts: 76c425968283051117c01f9cd07e115de8945491
PRECONDITION: packages/runtime/dist absent => the pin's relative './app-plugin.js' import
  resolves to SOURCE; no rebuild leg applies
REMOVED TEXT  'return await handler(jobContext);' : 1 -> 0
INJECTED TEXT bare 'await handler(jobContext);'   : 0 -> 1
blob after mutation: 82098e0cc683fca2864d63aefd1b73c019bce3f6
MUTATION CONFIRMED ON DISK
ABLATION VITEST EXIT: 1
 Test Files  1 failed (1)
      Tests  4 failed | 2 passed (6)
     x lands `sys_job_run.status` distinct from `success`, with the reason in `error`
     x mirrors onto `sys_job.last_status` and leaves `failure_count` flat
     x carries the outcome for the `{ handler, effect }` function form too
     x the middle term: the wrapper AppPlugin hands `schedule` resolves the handler's outcome
blob after restore : 76c425968283051117c01f9cd07e115de8945491
RESTORE CONFIRMED: blob identical to HEAD, git diff HEAD empty, git status clean
ABLATION VERDICT: RED as required

The mutation is proven by content — the removed text counted to zero and the injected
text counted to one, separately — never by an editor's exit code; the restore is proven by
blob identity against the HEAD blob plus an empty git diff HEAD and a clean
git status --porcelain. The split is the part that matters: the four cases that go red
are the declarative ones, while both controls stay green under the same mutation. No
rebuild leg applies — the mutated file is imported relatively by the pin, so vitest reads
source, and packages/runtime/dist was absent at the time (asserted in the run above).

Green after the fix: Test Files 1 passed (1) · Tests 6 passed (6).

Verification

Everything below ran on the final tree, git rev-parse --short HEAD = 0f4a80ee47, after
merging origin/main and re-deriving.

• Gate union derived with
  node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands. The
  first derivation reported a stale tree, so origin/main was merged, the install and the
  dependency closure refreshed, and it was re-derived on the merged tree — 36 commands,
  the same list. Each ran with its exit captured before any pipe
  (cmd > log 2>&1; EXIT=$?): 32 exit 0.
• 4 are NOT MEASURED, quoted in their own words, and reported as neither a pass nor a
  red: check-test-completeness — "There is no local log to hand it, so the local reading
  for this gate is NOT MEASURED"; check-half-states — "Nothing was swept … it is no
  reading at all" (this session's repo-scoped REST reads answer 403);
  check:dual-build-cjs-loads — "PREREQUISITE NOT MET — this gate reads built output, and
  some package has no dist/"; check:type-check-debt — "PREREQUISITE NOT MET … 26
  workspace dependenc(ies) of the ledgered packages have no built type entry point on
  disk". All four want a full-workspace build, which CI performs.
• Package test tier: pnpm --filter @objectstack/runtime test —
  Test Files 210 passed (210) · Tests 3085 passed (3085), VERDICT command-exit 0 from
  the shared verify lock.
• Package typecheck: pnpm --filter @objectstack/runtime typecheck — exit 0. ⚠️ Read
  narrowly: that script is tsc --noEmit over a tsconfig.json that excludes
  **/*.test.ts, so it covers app-plugin.ts and says nothing about the new test
  file. Confirmed with --listFiles: app-plugin.ts present, the test file absent.
  Compiled separately under the package's own options with tests included, the new file
  reports zero errors (the package's pre-existing test-layer errors are the subject of
  the standing finding [finding] packages/runtime type-checks none of its 208 test files — tsconfig excludes **/*.test.ts and no test-typecheck wiring exists #14504 and are untouched here).
• Lint — a DECLARED NARROWING. Whole-repo pnpm lint was attempted through the shared
  verify lock three times and returned exit 99 (queue-timeout, "never acquired") every
  time, holder pid 2524 from another dev's run, held 755s at the last attempt — so it is
  NOT MEASURED locally, and CI's Lint & Repo Gates runs the farm regardless. What was
  measured instead, with the three things a narrowing owes:
  1. the population is read from ESLint's own configuration (calculateConfigForFile
     plus isPathIgnored over every tracked file, no rule executed): 5,749 files, and
     both changed TS files are members;
  2. the narrowed run's file count comes from --format json:
     eslint --no-inline-config --format json on the two changed TS files reports
     2 files, 0 errors, 0 warnings, exit 0;
  3. the config is not type-aware — eslint.config.mjs states it in its own words,
     "no parserOptions.project, no typed @typescript-eslint rules" — so this diff
     cannot move the verdict on any file it does not contain. The changeset .md is
     outside the population by ESLint's own config, not by assumption.

Scope

packages/runtime/src/app-plugin.ts plus its new pin and the changeset — three files,
nothing else. content/docs/automation/jobs.mdx, content/docs/releases/**, docs/adr/**
and the other governed surfaces are untouched, and none of the packages/runtime files
fenced as held by other in-flight branches was edited.

⛔ Draft on purpose: the PM seat lands it. Not flipped ready, no auto-merge.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• 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.

Coarse fallback — 24 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 b474c38c8db0dd64572d0a076d94ade39d594c09 → packageMentionDocs.