fix(core): the pre-injected job fallback must not fake capability — take job off the pre-injection list so scheduled reports actually run on ObjectKernel (#11205)

* fix(core): stop pre-injecting the job fallback — a fallback must not fake capability

On an ObjectKernel without @objectstack/service-job, preInjectCoreFallbacks()
registered createMemoryJob() for the 'job' slot before Phase 2, so
getService('job') always resolved — and that fallback's schedule() records a
job and never fires it. Every 'prefer the platform job service, else own a
timer' consumer took the job-service branch and then silently never ran:
plugin-reports logged 'dispatcher registered with job service' and dispatched
nothing, ever (measured: 0 reads of sys_report_schedule in 5600 ms with the
success line present).

Per the maintainer ruling of 2026-08-22 (issue 10746, Option A — declare only
what you enforce), 'job' comes off the pre-injection list
(CORE_FALLBACK_FACTORIES). getService('job') now throws when no job plugin is
installed; every consumer's documented no-job-service path takes over, and
validateSystemRequirements() says the absence out loud at boot. createMemoryJob
stays exported for deliberate, explicit registration.

Acceptance pin: dispatcher-runs-on-object-kernel.test.ts boots ObjectKernel +
ObjectQLPlugin + ReportsServicePlugin with no job plugin and asserts
sys_report_schedule is actually polled — red before this fix (0 reads), green
after. Discovery-honesty gates keep the memory-job product in their inventory
via the still-exported factory.

Part of #10746

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

* docs(kernel): services-checklist no longer advertises a pre-injected job fallback

The page asserted in four places that the kernel pre-injects an in-memory
job fallback — all four made false by taking job off the pre-injection
list. Corrected: the key-architecture principle's slot list (job now named
beside auth as deliberately without a kernel fallback), Service Overview
row 15 (Plugin Required, with the throw-and-warn behavior), the
Infrastructure Services intro (cache/queue keep the fallback claim; job's
core criticality explicitly unchanged — it is what makes the absence
loud), and the job row of the infrastructure table.

Judged still true and left alone: the Framework legend (generic marker
definition, names no job), the i18n fallback notes (i18n stays
pre-injected), the plugin-layer ASCII diagram (lists job as
plugin-delivered — no fallback claim), and the scheduled-tasks provider
row (names service-job, claims no fallback).

Part of #10746

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

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/job-fallback-must-not-fake-capability.md

@@ -0,0 +1,9 @@
+---
+'@objectstack/core': minor
+---
+
+`ObjectKernel` no longer pre-injects the in-memory `job` fallback for the `job` core-service slot — a fallback must not fake capability (#10746, maintainer ruling 2026-08-22). `createMemoryJob()`'s `schedule()` records a job and never fires it (it owns no timer), so pre-injecting it made every "prefer the platform job service, else own a timer" consumer take the job-service branch on a kernel without `@objectstack/service-job` and then silently never run: `plugin-reports` logged `dispatcher registered with job service` and dispatched nothing, ever.
+
+Behavior change, FROM → TO: on an `ObjectKernel` without a registered `job` service, `getService('job')` FROM resolving a non-scheduling in-memory registry TO throwing `Service 'job' not found`. Consumers' documented no-job-service paths take over (`plugin-reports` falls through to its own `setInterval` and scheduled reports actually dispatch; schedule triggers and declarative jobs warn loudly instead of scheduling into the void), and the kernel says the absence out loud at boot: `Core service missing, functionality may be degraded: job`.
+
+One-line fix if you relied on the old behavior: install `@objectstack/service-job` for real scheduling, or — if you deliberately want the manual-trigger in-memory registry — register it explicitly: `kernel.registerService('job', createMemoryJob())` (the factory is still exported from `@objectstack/core`).

content/docs/kernel/services-checklist.mdx

@@ -16,7 +16,7 @@ package catalog.
 
 The ObjectStack protocol defines **15 kernel services** registered via the `CoreServiceName` enum (v17 removed the never-implemented `graphql` entry and retired the never-filled `workflow` slot, #4451). Each service maps to a set of protocol methods governed by its per-domain contract (`DataProtocol`, `MetadataProtocol`, ...) — the transitional `ObjectStackProtocol` composition alias was dissolved in v17 (ADR-0076 D9); capability availability comes from the runtime discovery `services` registry.
 
-**Key architecture principle**: the kernel guarantees only **data** and **metadata**, and even those are filled by packages (`@objectstack/objectql`, `@objectstack/metadata`) rather than baked in — the kernel's own contribution is an in-memory fallback for the `core` slots that have one (`metadata`, `cache`, `queue`, `job`, `i18n` — **not** `auth`). Everything else — including **auth** and **automation** — is delivered by plugins. `@objectstack/objectql` is an example kernel implementation to get the basic API running; production kernels will be rebuilt as separate plugins.
+**Key architecture principle**: the kernel guarantees only **data** and **metadata**, and even those are filled by packages (`@objectstack/objectql`, `@objectstack/metadata`) rather than baked in — the kernel's own contribution is an in-memory fallback for the `core` slots that have one (`metadata`, `cache`, `queue`, `i18n` — **not** `auth`, and not `job`: an in-memory registry cannot fire a `schedule()`d job on its own, so pre-injecting one advertised a scheduler that never ran, and a fallback must not fake capability — #10746. The `job` slot stays empty, loudly, until `@objectstack/service-job` or an explicitly registered scheduler fills it). Everything else — including **auth** and **automation** — is delivered by plugins. `@objectstack/objectql` is an example kernel implementation to get the basic API running; production kernels will be rebuilt as separate plugins.
 
 <Callout type="info">
 **Legend**
@@ -79,7 +79,7 @@ The ObjectStack protocol defines **15 kernel services** registered via the `Core
 | 12 | **search** | `optional` | — | ❌ Nothing ships | — |
 | 13 | **cache** | `core` | — | ✅ Built-in (in-memory fallback) | `@objectstack/service-cache` |
 | 14 | **queue** | `core` | — | ✅ Built-in (in-memory fallback) | `@objectstack/service-queue` |
-| 15 | **job** | `core` | — | ✅ Built-in (in-memory fallback) | `@objectstack/service-job` |
+| 15 | **job** | `core` | — | ❌ Plugin Required (no pre-injected fallback since #10746 — with no job plugin, `getService('job')` throws and the boot warns) | `@objectstack/service-job` |
 
 <Callout type="info">
 The Provider column mirrors `CORE_SERVICE_PROVIDER` in
@@ -480,15 +480,15 @@ AppPlugin will:
 
 ## 11–15. Infrastructure Services
 
-`cache`, `queue`, and `job` are `core` services: like `i18n`, the kernel auto-injects an in-memory fallback when no plugin registers them (see `CORE_FALLBACK_FACTORIES` in `packages/core/src/fallbacks/`). The `optional` services (`storage`, `search`) stay disabled until a plugin provides them.
+`cache`, `queue`, and `job` are `core` services. For `cache` and `queue` — like `i18n` — the kernel auto-injects an in-memory fallback when no plugin registers them (see `CORE_FALLBACK_FACTORIES` in `packages/core/src/fallbacks/`). `job` is deliberately **not** on that list (#10746): an in-memory registry cannot fire a `schedule()`d job on its own, and a fallback must not fake capability — so with no job plugin installed, `getService('job')` throws, consumers take their documented no-scheduler paths (e.g. the reports dispatcher's own `setInterval`), and the boot warns `Core service missing, functionality may be degraded: job`. The `core` criticality itself is unchanged — it is exactly what makes the absence loud. Fill the slot with `@objectstack/service-job`, or register `createMemoryJob()` explicitly if a manual-`trigger()` registry is genuinely wanted. The `optional` services (`storage`, `search`) stay disabled until a plugin provides them.
 
 | Service | Description |
 |:--------|:------------|
 | **storage** (deprecated v17 alias: `file-storage`, #9683) | Unified upload/download/delete via `@objectstack/service-storage`, which mounts `/api/v1/storage` itself. Adapters: local FS and S3 (the S3 adapter's `endpoint` + path-style options cover S3-compatible services such as MinIO and R2). |
 | **search** | **Nothing ships.** `ISearchService` and the engine enum (`elasticsearch`, `meilisearch`, …) exist in `@objectstack/spec`, but no package implements the contract or registers the `search` slot, so `CORE_SERVICE_PROVIDER.search` is `null`. |
 | **cache** | General-purpose cache. In-memory fallback; memory or Redis adapter via `@objectstack/service-cache`. |
 | **queue** | Message queue. In-memory fallback; durable DB-backed adapter (`sys_job_queue`) via `@objectstack/service-queue` (no BullMQ/Redis adapter is shipped). |
-| **job** | Scheduled task execution via `@objectstack/service-job`. In-memory fallback; interval, cron, and DB-backed adapters with concurrency policy. |
+| **job** | Scheduled task execution via `@objectstack/service-job` — interval, cron, and DB-backed adapters with concurrency policy. No pre-injected fallback (#10746): install the plugin, or the slot stays empty and the boot says so. |
 
 ---
 

packages/core/src/fallbacks/fallbacks.test.ts

@@ -7,8 +7,14 @@ import { CORE_FALLBACK_FACTORIES } from './index';
 import { readServiceSelfInfo } from '@objectstack/spec/api';
 
 describe('CORE_FALLBACK_FACTORIES', () => {
-    it('should have exactly 5 entries: metadata, cache, queue, job, i18n', () => {
-        expect(Object.keys(CORE_FALLBACK_FACTORIES)).toEqual(['metadata', 'cache', 'queue', 'job', 'i18n']);
+    // [#10746] `job` is deliberately OFF this list — a fallback must not fake
+    // capability (maintainer ruling 2026-08-22). `createMemoryJob().schedule()`
+    // records a job and never fires it, so pre-injecting it made consumers
+    // treat "a `job` service resolves" as "a working scheduler" and silently
+    // never run. The factory stays exported for deliberate, explicit use; the
+    // kernel must not hand it out as if it honoured `schedule()`.
+    it('should have exactly 4 entries: metadata, cache, queue, i18n — job deliberately absent (#10746)', () => {
+        expect(Object.keys(CORE_FALLBACK_FACTORIES)).toEqual(['metadata', 'cache', 'queue', 'i18n']);
     });
 
     // [#4058] Every kernel fallback must be readable through the ONE standard

packages/core/src/fallbacks/index.ts

@@ -2,7 +2,6 @@
 
 import { createMemoryCache } from './memory-cache.js';
 import { createMemoryQueue } from './memory-queue.js';
-import { createMemoryJob } from './memory-job.js';
 import { createMemoryI18n } from './memory-i18n.js';
 import { createMemoryMetadata } from './memory-metadata.js';
 
@@ -18,13 +17,30 @@ export {
 
 /**
  * Map of core-criticality service names to their in-memory fallback factories.
- * Used by ObjectKernel.validateSystemRequirements() to auto-inject fallbacks
- * when no real plugin provides the service.
+ * This IS the kernel's pre-injection list: `ObjectKernel.preInjectCoreFallbacks()`
+ * registers an entry for every unprovided `core` service before Phase 2, and
+ * `validateSystemRequirements()` consults the same map as its final check.
+ *
+ * [#10746] `job` is deliberately ABSENT — a fallback must not fake capability
+ * (maintainer ruling 2026-08-22). `createMemoryJob()`'s `schedule()` records a
+ * job and never fires it, so pre-injecting it made every "prefer the platform
+ * job service, else own a timer" consumer take the job-service branch and then
+ * silently never run: `plugin-reports` logged `dispatcher registered with job
+ * service` and dispatched nothing, ever (measured: 0 reads of
+ * `sys_report_schedule` in 5600 ms with the success line present). With no
+ * entry here, `getService('job')` throws when no job plugin is installed,
+ * every consumer's documented no-job-service path becomes reachable (they all
+ * already run on `LiteKernel`, which injects no fallbacks), and the kernel
+ * says the absence out loud at boot: `validateSystemRequirements()` warns
+ * "Core service missing, functionality may be degraded: job". Do NOT re-add
+ * the entry to quiet that warning — install `@objectstack/service-job`, or
+ * register a real scheduler, instead. `createMemoryJob` stays exported below
+ * for embedders who deliberately want a manual-trigger job registry and have
+ * read its docblock.
  */
 export const CORE_FALLBACK_FACTORIES: Record<string, () => Record<string, any>> = {
   metadata: createMemoryMetadata,
   cache: createMemoryCache,
   queue: createMemoryQueue,
-  job:   createMemoryJob,
   i18n:  createMemoryI18n,
 };

packages/core/src/fallbacks/memory-job.ts

@@ -1,11 +1,15 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * In-memory job scheduler fallback.
+ * In-memory job registry — schedule/cancel/trigger bookkeeping with NO timer.
  *
- * Implements the IJobService contract with basic schedule/cancel/trigger
- * operations.  Used by ObjectKernel as an automatic fallback when no real
- * job plugin (e.g. Agenda / BullMQ) is registered.
+ * [#10746] NOT pre-injected by ObjectKernel any more (it used to be, via
+ * `CORE_FALLBACK_FACTORIES`): a fallback must not fake capability (maintainer
+ * ruling 2026-08-22). Advertising a `schedule()` that records and never fires
+ * made every "prefer the platform job service, else own a timer" consumer
+ * take the job-service branch and then silently never run. The export remains
+ * for embedders who deliberately want a manual-trigger job registry — e.g. in
+ * tests that drive handlers via `trigger()` — and have read this docblock.
  *
  * [#4058] `degraded` (ADR-0076 D12), with the missing half named in the
  * message rather than left for a deployer to discover: `trigger()` really runs

packages/core/src/kernel.test.ts

@@ -1155,4 +1155,43 @@ describe('ObjectKernel', () => {
             await kernel.shutdown();
         });
     });
+
+    describe('Core fallback pre-injection (#10746)', () => {
+        // The suite-level kernel sets `skipSystemValidation: true`, which skips
+        // pre-injection entirely — this pin needs the real path, so it boots
+        // its own kernel with validation ON (the production default).
+        it('pre-injects the honest core fallbacks but NOT job — a fallback must not fake capability', async () => {
+            const k = new ObjectKernel({
+                logger: { level: 'error' },
+                gracefulShutdown: false,
+            });
+            // `data` is `required` criticality; provide it so bootstrap
+            // survives validateSystemRequirements().
+            const dataProvider: Plugin = {
+                name: 'test.data-provider',
+                version: '1.0.0',
+                init: async (ctx: PluginContext) => {
+                    ctx.registerService('data', { find: async () => [] });
+                },
+            };
+            await k.use(dataProvider);
+            await k.bootstrap();
+            try {
+                // The remaining core slots still pre-inject before Phase 2.
+                for (const slot of ['metadata', 'cache', 'queue', 'i18n']) {
+                    expect(k.getService(slot), `fallback for '${slot}'`).toBeDefined();
+                }
+                // `job` must NOT resolve: `createMemoryJob()`'s `schedule()`
+                // records a job and never fires it, so handing it out made
+                // every "prefer the platform job service" consumer schedule
+                // into the void while logging success (maintainer ruling
+                // 2026-08-22: declare only what you enforce). Absence is the
+                // honest answer — consumers' documented no-job-service paths
+                // (setInterval fallbacks, loud warns) take over.
+                expect(() => k.getService('job')).toThrow(/Service 'job' not found/);
+            } finally {
+                await k.shutdown();
+            }
+        });
+    });
 });

packages/objectql/src/protocol-discovery.test.ts

@@ -2,7 +2,7 @@
 
 import { describe, it, expect, beforeEach } from 'vitest';
 import { ObjectStackProtocolImplementation } from '@objectstack/metadata-protocol';
-import { createMemoryMetadata, CORE_FALLBACK_FACTORIES } from '@objectstack/core';
+import { createMemoryMetadata, createMemoryJob, CORE_FALLBACK_FACTORIES } from '@objectstack/core';
 import { ObjectQL } from './engine.js';
 
 describe('ObjectStackProtocolImplementation - Dynamic Service Discovery', () => {
@@ -232,7 +232,12 @@ describe('ObjectStackProtocolImplementation - Dynamic Service Discovery', () =>
   it('reports every CORE_FALLBACK_FACTORIES product as degraded, never available (#3898)', async () => {
     expect(Object.keys(CORE_FALLBACK_FACTORIES).length).toBeGreaterThan(0);
 
-    for (const [slot, factory] of Object.entries(CORE_FALLBACK_FACTORIES)) {
+    // [#10746] `job` came OFF the pre-injection list (a fallback must not
+    // fake capability), but `createMemoryJob` stays exported for deliberate
+    // registration — so its product stays in this gate's inventory: however
+    // it reaches a slot, discovery must never call it `available`.
+    const inventory = { ...CORE_FALLBACK_FACTORIES, job: createMemoryJob };
+    for (const [slot, factory] of Object.entries(inventory)) {
       const mockServices = new Map<string, any>();
       mockServices.set(slot, factory());
 
@@ -382,9 +387,13 @@ describe('ObjectStackProtocolImplementation - Dynamic Service Discovery', () =>
   });
 
   it('never advertises a route for a cache/queue/job fallback either (#4318)', async () => {
+    // [#10746] `job` is off the pre-injection map but stays explicitly
+    // registrable, so the slot keeps its fallback-occupant coverage here.
+    const factoryFor = (slot: string) =>
+      slot === 'job' ? createMemoryJob : CORE_FALLBACK_FACTORIES[slot];
     for (const slot of ['cache', 'queue', 'job']) {
       const mockServices = new Map<string, any>();
-      mockServices.set(slot, CORE_FALLBACK_FACTORIES[slot]());
+      mockServices.set(slot, factoryFor(slot)());
 
       protocol = new ObjectStackProtocolImplementation(engine, () => mockServices);
       const reported = (await protocol.getDiscovery()).services[slot];