@cosmicdrift/kumiko-framework 0.198.0 → 0.199.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.198.0",
+  "version": "0.199.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -186,7 +186,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.198.0",
+    "@cosmicdrift/kumiko-types": "0.199.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -202,7 +202,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.198.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.199.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/server-boot-guards.test.ts

@@ -1,6 +1,6 @@
 // buildServer boot-time guards + httpRoute verb wiring (PUT branch).
 
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 import {
   createEntity,
   createFileField,
@@ -8,10 +8,22 @@ import {
   createTextField,
   defineFeature,
 } from "../../engine";
+import { createInMemorySearchAdapter } from "../../search";
 import { buildServer } from "../server";
 
 const JWT_SECRET = "server-boot-guards-test-secret-min-32-chars";
 
+// Find the "[kumiko:boot] ... SearchAdapter" line among all console.warn calls
+// so the unrelated instanceIdWasRandom warning (fires whenever
+// KUMIKO_INSTANCE_ID is unset, as it is in this test run) can't false-fire
+// or hide the assertion.
+function searchAdapterWarning(calls: unknown[][]): string | undefined {
+  const hit = calls.find(
+    (args) => typeof args[0] === "string" && args[0].includes("SearchAdapter is wired"),
+  );
+  return hit ? String(hit[0]) : undefined;
+}
+
 describe("buildServer — file-storage provider guard", () => {
   const fileFieldFeature = defineFeature("needs-files", (r) => {
     r.entity(
@@ -69,3 +81,118 @@ describe("buildServer — feature httpRoute PUT mounting", () => {
     expect(await res.json()).toEqual({ method: "PUT", ok: true });
   });
 });
+
+describe("buildServer — search-adapter boot warning (#2051)", () => {
+  const searchableFeature = defineFeature("has-search", (r) => {
+    r.entity(
+      "note",
+      createEntity({
+        table: "boot_guard_notes",
+        fields: { title: createTextField({ searchable: true }) },
+      }),
+    );
+    r.screen({ id: "note-list", type: "entityList", entity: "note", columns: ["title"] });
+  });
+
+  const nonSearchableFeature = defineFeature("no-search", (r) => {
+    r.entity(
+      "note",
+      createEntity({
+        table: "boot_guard_plain_notes",
+        fields: { title: createTextField() },
+      }),
+    );
+    r.screen({ id: "note-list", type: "entityList", entity: "note", columns: ["title"] });
+  });
+
+  // Pins the `screen.searchable === false` exclusion specifically: without
+  // it, this would false-positive purely off the entity having a searchable
+  // field, ignoring that the screen (whitelisted per entity-list-screens.ts
+  // SEARCHABLE_FALSE_WHITELIST) never renders the search box.
+  const explicitlyNonSearchableScreenFeature = defineFeature("opted-out-search", (r) => {
+    r.entity(
+      "download-attempt",
+      createEntity({
+        table: "boot_guard_download_attempts",
+        fields: { title: createTextField({ searchable: true }) },
+      }),
+    );
+    r.screen({
+      id: "download-attempt-list",
+      type: "entityList",
+      entity: "download-attempt",
+      columns: ["title"],
+      searchable: false,
+    });
+  });
+
+  test("warns naming the entity when a searchable screen has no context.searchAdapter", () => {
+    const calls: unknown[][] = [];
+    const spy = spyOn(console, "warn").mockImplementation((...args) => {
+      calls.push(args);
+    });
+    try {
+      buildServer({
+        registry: createRegistry([searchableFeature]),
+        context: {},
+        jwtSecret: JWT_SECRET,
+      });
+      const logged = searchAdapterWarning(calls);
+      expect(logged).toBeDefined();
+      expect(logged).toContain("note");
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  test("stays silent when context.searchAdapter is wired", () => {
+    const calls: unknown[][] = [];
+    const spy = spyOn(console, "warn").mockImplementation((...args) => {
+      calls.push(args);
+    });
+    try {
+      buildServer({
+        registry: createRegistry([searchableFeature]),
+        context: { searchAdapter: createInMemorySearchAdapter() },
+        jwtSecret: JWT_SECRET,
+      });
+      expect(searchAdapterWarning(calls)).toBeUndefined();
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  test("stays silent when no screen has a searchable field", () => {
+    const calls: unknown[][] = [];
+    const spy = spyOn(console, "warn").mockImplementation((...args) => {
+      calls.push(args);
+    });
+    try {
+      buildServer({
+        registry: createRegistry([nonSearchableFeature]),
+        context: {},
+        jwtSecret: JWT_SECRET,
+      });
+      expect(searchAdapterWarning(calls)).toBeUndefined();
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  test("stays silent when the entity has a searchable field but the screen opts out (searchable: false)", () => {
+    const calls: unknown[][] = [];
+    const spy = spyOn(console, "warn").mockImplementation((...args) => {
+      calls.push(args);
+    });
+    try {
+      buildServer({
+        registry: createRegistry([explicitlyNonSearchableScreenFeature]),
+        context: {},
+        jwtSecret: JWT_SECRET,
+      });
+      expect(searchAdapterWarning(calls)).toBeUndefined();
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});

package/src/api/server.ts

@@ -286,6 +286,27 @@ export function buildServer(options: ServerOptions): KumikoServer {
     );
   }
 
+  // #2051 — a screen whose search box renders (kumiko-screen.tsx gates it on
+  // `screen.searchable ?? entity-has-searchable-field`, the same condition
+  // used below) sends `payload.search` on every query. Without a
+  // context.searchAdapter that throws UnprocessableError at request time
+  // (#2032) — surface the misconfig at boot instead of on the first search.
+  // Warn, not throw: unlike missing file-storage (uploads always fail),
+  // list screens still work without search: only the search box is broken.
+  // Several deployed apps (offlot-app, publicstatus, kumiko-studio,
+  // kumiko-enterprise) currently run in exactly this state.
+  if (!options.context.searchAdapter) {
+    const unwiredEntities = entitiesWithSearchableScreen(options.registry);
+    if (unwiredEntities.length > 0) {
+      console.warn(
+        `[kumiko:boot] ${unwiredEntities.length} entit${unwiredEntities.length === 1 ? "y" : "ies"} ` +
+          `have a searchable list screen but no SearchAdapter is wired on context.searchAdapter: ` +
+          `${unwiredEntities.join(", ")}. Search requests against ${unwiredEntities.length === 1 ? "it" : "them"} will fail with a 422 (search_adapter_not_wired) at runtime. ` +
+          "Wire a SearchAdapter (e.g. createMeilisearchAdapter) on context.searchAdapter, or remove `searchable: true` from the affected fields.",
+      );
+    }
+  }
+
   // Stateless JWTs (no sessionChecker → no revocation) default to a shorter
   // TTL than session-backed ones, since a leaked stateless token can't be
   // revoked and stays valid until it expires. Explicit jwtTtl always wins.
@@ -841,6 +862,29 @@ function registryDeclaresFileFields(registry: Registry): boolean {
   return false;
 }
 
+// Entities whose entityList screen WOULD render a search box based on
+// screen/field config alone: `screen.searchable` wins when set, otherwise
+// the box shows iff the entity has ≥1 searchable field. `screen.searchable
+// === false` is excluded — the boot-validator (entity-list-screens.ts) only
+// allows that on the whitelisted download-attempt-list-style screens, which
+// never render the box. This is the config-only half of the rule; the
+// client additionally gates on FeatureSchema.searchAdapterMissing (#2062,
+// set from the same `!options.context.searchAdapter` check below) so the
+// box is actually suppressed once this function finds a hit.
+function entitiesWithSearchableScreen(registry: Registry): readonly string[] {
+  const entities = new Set<string>();
+  for (const feature of registry.features.values()) {
+    for (const screen of Object.values(feature.screens)) {
+      if (screen.type !== "entityList") continue;
+      const isSearchable =
+        screen.searchable === true ||
+        (screen.searchable === undefined && registry.getSearchableFields(screen.entity).length > 0);
+      if (isSearchable) entities.add(screen.entity);
+    }
+  }
+  return [...entities];
+}
+
 // Upload-route policy carried by createFilesFeature(opts?) — read from the
 // feature's exports so buildServer applies it without a parallel ServerOptions
 // surface. Absent feature / opts → defaults in createFileRoutes.

package/src/db/__tests__/unchecked-system-db.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import { SYSTEM_TENANT_ID } from "../../engine";
+import { testTenantId } from "../../stack";
+import type { DbRunner } from "../connection";
+import { createTenantDb, createUncheckedSystemDb, SYSTEM_SCOPE_CHECK_BRAND } from "../tenant-db";
+
+// createUncheckedSystemDb wraps a "system"-mode TenantDb (r.systemScope())
+// so a handler must explicitly clear a self-check before using it — none of
+// these checks execute a query, so a runner that always throws is enough to
+// prove the wrapper never falls through to the DB on a mismatch.
+function unusedRunner(): DbRunner {
+  return {
+    unsafe: async () => {
+      throw new Error("unchecked-system-db tests must not reach the DB");
+    },
+    begin: async () => {
+      throw new Error("unchecked-system-db tests must not reach the DB");
+    },
+  } as DbRunner;
+}
+
+const own = testTenantId(1);
+const foreign = testTenantId(2);
+
+describe("createUncheckedSystemDb", () => {
+  test("carries the SYSTEM_SCOPE_CHECK_BRAND", () => {
+    const systemDb = createTenantDb(unusedRunner(), own, "system");
+    const unchecked = createUncheckedSystemDb(systemDb);
+
+    expect(unchecked[SYSTEM_SCOPE_CHECK_BRAND]).toBe(true);
+  });
+
+  describe("assertTenantMatch", () => {
+    test("returns the underlying TenantDb when the tenantId matches", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+
+      expect(unchecked.assertTenantMatch(own)).toBe(systemDb);
+    });
+
+    test("throws AccessDeniedError when the tenantId doesn't match", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+
+      expect(() => unchecked.assertTenantMatch(foreign)).toThrow(/tenant self-check failed/);
+    });
+  });
+
+  describe("assertRowsTenant", () => {
+    test("returns the rows unchanged when every row matches", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+      const rows = [
+        { tenantId: own, name: "a" },
+        { tenantId: own, name: "b" },
+      ];
+
+      expect(unchecked.assertRowsTenant(rows, "tenantId")).toBe(rows);
+    });
+
+    test("throws AccessDeniedError on the first mismatched row instead of filtering", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+      const rows = [
+        { tenantId: own, name: "a" },
+        { tenantId: foreign, name: "b" },
+      ];
+
+      expect(() => unchecked.assertRowsTenant(rows, "tenantId")).toThrow(
+        /row tenant self-check failed/,
+      );
+    });
+
+    test("an empty row array trivially passes", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+
+      expect(unchecked.assertRowsTenant([], "tenantId")).toEqual([]);
+    });
+
+    test("accepts SYSTEM_TENANT_ID rows as reference data, mirroring tenant-mode readWhere", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+      const rows = [
+        { tenantId: own, name: "a" },
+        { tenantId: SYSTEM_TENANT_ID, name: "global-default" },
+      ];
+
+      expect(unchecked.assertRowsTenant(rows, "tenantId")).toBe(rows);
+    });
+  });
+
+  describe("acknowledgeCrossTenant", () => {
+    test("returns the underlying TenantDb without comparing tenants when given a reason", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+
+      expect(unchecked.acknowledgeCrossTenant("user feature is cross-tenant by design")).toBe(
+        systemDb,
+      );
+    });
+
+    test("throws on an empty reason", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+
+      expect(() => unchecked.acknowledgeCrossTenant("")).toThrow(/non-empty reason/);
+    });
+
+    test("throws on a whitespace-only reason", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+
+      expect(() => unchecked.acknowledgeCrossTenant("   ")).toThrow(/non-empty reason/);
+    });
+  });
+});

package/src/db/index.ts

@@ -143,5 +143,10 @@ export {
   toSnakeCase,
   toTableName,
 } from "./table-builder";
-export type { TenantDb, TenantDbMode } from "./tenant-db";
-export { castTenantRows, createTenantDb } from "./tenant-db";
+export type { TenantDb, TenantDbMode, UncheckedSystemDb } from "./tenant-db";
+export {
+  castTenantRows,
+  createTenantDb,
+  createUncheckedSystemDb,
+  SYSTEM_SCOPE_CHECK_BRAND,
+} from "./tenant-db";

package/src/db/tenant-db.ts

@@ -1,5 +1,10 @@
 import { KUMIKO_NAME_SYMBOL, type SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
-import type { TenantDb, TenantDbMode } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import {
+  SYSTEM_SCOPE_CHECK_BRAND,
+  type TenantDb,
+  type TenantDbMode,
+  type UncheckedSystemDb,
+} from "@cosmicdrift/kumiko-types/tenant-db-types";
 import {
   asEntityTableMeta,
   asRawClient,
@@ -12,12 +17,59 @@ import {
   type WhereObject,
 } from "../db/query";
 import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
+import { AccessDeniedError } from "../errors";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
 import type { DbRunner } from "./connection";
 
 type Table = SchemaTable;
 
-export type { TenantDb, TenantDbMode } from "@cosmicdrift/kumiko-types/tenant-db-types";
+export {
+  SYSTEM_SCOPE_CHECK_BRAND,
+  type TenantDb,
+  type TenantDbMode,
+  type UncheckedSystemDb,
+} from "@cosmicdrift/kumiko-types/tenant-db-types";
+
+// buildHandlerContext (pipeline/dispatch-shared.ts) always builds "system"
+// mode from the caller's own tenantId, never a foreign one.
+export function createUncheckedSystemDb(db: TenantDb): UncheckedSystemDb {
+  const allowedTenantIds: readonly TenantId[] = [db.tenantId, SYSTEM_TENANT_ID];
+
+  return {
+    [SYSTEM_SCOPE_CHECK_BRAND]: true,
+
+    assertTenantMatch(tenantId) {
+      if (tenantId !== db.tenantId) {
+        throw new AccessDeniedError({
+          message: `systemScope() tenant self-check failed: expected "${db.tenantId}", got "${tenantId}"`,
+        });
+      }
+      return db;
+    },
+
+    // Fails closed on any mismatch rather than silently dropping rows.
+    // Reference rows (tenantId === SYSTEM_TENANT_ID) are allowed, mirroring
+    // "tenant"-mode readWhere's own [tenantId, SYSTEM_TENANT_ID] allowlist.
+    assertRowsTenant<T>(rows: readonly T[], tenantField: keyof T): readonly T[] {
+      const hasOffender = rows.some(
+        (row) => !allowedTenantIds.includes(row[tenantField] as TenantId),
+      );
+      if (hasOffender) {
+        throw new AccessDeniedError({
+          message: `systemScope() row tenant self-check failed on field "${String(tenantField)}"`,
+        });
+      }
+      return rows;
+    },
+
+    acknowledgeCrossTenant(reason) {
+      if (reason.trim().length === 0) {
+        throw new Error("acknowledgeCrossTenant requires a non-empty reason");
+      }
+      return db;
+    },
+  };
+}
 
 // @cast-boundary tenant-db-row
 export function castTenantRows<T>(rows: readonly Record<string, unknown>[]): readonly T[] {

package/src/engine/__tests__/build-app-schema.test.ts

@@ -99,6 +99,36 @@ describe("buildAppSchema", () => {
     expect(app.features[0]?.translations).toBeUndefined();
   });
 
+  // #2062: buildAppSchema itself has no context, so the boot entrypoint
+  // (createKumikoServer, runProdApp) forwards its own context.searchAdapter
+  // presence check in via options.searchAdapterMissing.
+  test("options.searchAdapterMissing: true landet auf jeder FeatureSchema", () => {
+    const orderFeature = defineFeature("orders", (r) => {
+      r.nav({ id: "list", label: "List" });
+    });
+    const fleetFeature = defineFeature("fleet", (r) => {
+      r.nav({ id: "list", label: "List" });
+    });
+    const app = buildAppSchema(createRegistry([orderFeature, fleetFeature]), {
+      searchAdapterMissing: true,
+    });
+
+    expect(app.features.length).toBeGreaterThan(0);
+    expect(app.features.every((f) => f.searchAdapterMissing === true)).toBe(true);
+  });
+
+  test("options.searchAdapterMissing ohne/false lässt das Feld weg (omit-undefined-Pattern)", () => {
+    const f = defineFeature("bare", (r) => {
+      r.nav({ id: "x", label: "X" });
+    });
+
+    expect(buildAppSchema(createRegistry([f])).features[0]?.searchAdapterMissing).toBeUndefined();
+    expect(
+      buildAppSchema(createRegistry([f]), { searchAdapterMissing: false }).features[0]
+        ?.searchAdapterMissing,
+    ).toBeUndefined();
+  });
+
   test("Workspaces — definition + aufgelöste navMembers landen auf AppSchema-Ebene", () => {
     const ordersFeature = defineFeature("orders", (r) => {
       r.nav({ id: "list", label: "List" });

package/src/engine/build-app-schema.ts

@@ -40,6 +40,11 @@ export type BuildAppSchemaOptions = {
   /** Dev-server authoring hints (Settings-Hub placement). Default off — only
    *  `createKumikoServer` opts in; prod boot + unit tests stay silent. */
   readonly authoringWarnings?: boolean;
+  /** Forwarded onto every FeatureSchema.searchAdapterMissing. Set by the boot
+   *  entrypoint (createKumikoServer, runProdApp) from its own
+   *  context.searchAdapter presence check — buildAppSchema itself has no
+   *  context, only the registry. Omit/false when a SearchAdapter is wired. */
+  readonly searchAdapterMissing?: boolean;
 };
 
 export function buildAppSchema(registry: Registry, options: BuildAppSchemaOptions = {}): AppSchema {
@@ -67,6 +72,7 @@ export function buildAppSchema(registry: Registry, options: BuildAppSchemaOption
       ...(Object.keys(feature.translations ?? {}).length > 0 && {
         translations: feature.translations,
       }),
+      ...(options.searchAdapterMissing === true && { searchAdapterMissing: true }),
     };
     features.push(featureSchema);
   }

package/src/engine/registry-facade.ts

@@ -203,6 +203,12 @@ export function buildRegistryFacade(state: RegistryState): Registry {
       return state.featureMap.get(featureName)?.systemScope ?? false;
     },
 
+    isJobSystemScoped(qualifiedJobName: string): boolean {
+      const featureName = state.jobFeatureMap.get(qualifiedJobName);
+      if (!featureName) return false;
+      return state.featureMap.get(featureName)?.systemScope ?? false;
+    },
+
     getHandlerFeature(qualifiedHandler: string): string | undefined {
       return state.handlerFeatureMap.get(qualifiedHandler);
     },

package/src/engine/registry-ingest.ts

@@ -129,6 +129,7 @@ export function populateJobsAndNotifications(
       );
     }
     state.jobMap.set(qualifiedName, { ...jobDef, name: qualifiedName });
+    state.jobFeatureMap.set(qualifiedName, feature.name);
   }
 
   // Notifications: scope:notify:name

package/src/engine/registry-state.ts

@@ -180,6 +180,7 @@ export type RegistryState = {
   searchPayloadExtensions: Map<string, OwnedFn<SearchPayloadContributorFn>[]>;
   configKeyMap: Map<string, ConfigKeyDefinition>;
   jobMap: Map<string, JobDefinition>;
+  jobFeatureMap: Map<string, string>;
   notificationMap: Map<string, NotificationDefinition>;
   notificationFeatureMap: Map<string, string>;
   eventMap: Map<string, EventDef>;
@@ -248,6 +249,7 @@ export function createInitialState(): RegistryState {
     searchPayloadExtensions: new Map(),
     configKeyMap: new Map(),
     jobMap: new Map(),
+    jobFeatureMap: new Map(),
     notificationMap: new Map(),
     notificationFeatureMap: new Map(),
     eventMap: new Map(),

package/src/jobs/__tests__/job-systemdb.integration.test.ts

@@ -0,0 +1,152 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { createRegistry, defineFeature, type Registry } from "../../engine";
+import { createTestRedis, type TestRedis, testTenantId } from "../../stack";
+import { waitFor } from "../../testing";
+import { createJobRunner, type JobRunner } from "../job-runner";
+
+// r.systemScope() is feature-level (define-feature.ts), not per-job — so two
+// features prove both sides, mirroring pipeline/__tests__/ctx-systemdb.integration.test.ts
+// (the handler-dispatch counterpart from framework#2069/PR#2091).
+
+type JobRunResult = {
+  readonly name: "system" | "tenant" | "system-per-tenant";
+  readonly present: boolean;
+  // assertTenantMatch() must return a TenantDb whose `.raw` is the SAME
+  // underlying DbConnection ctx.db carries — proves systemDb is bound to
+  // the job's own tenant-scoped db, not a separate instance.
+  readonly boundToRawDb: boolean | undefined;
+  // A foreign tenantId must throw fail-closed (AccessDeniedError), same as
+  // the HandlerContext.systemDb self-check.
+  readonly foreignTenantThrew: boolean | undefined;
+};
+
+const results: JobRunResult[] = [];
+const ownTenant = testTenantId(1);
+const foreignTenant = testTenantId(2);
+
+const systemScopedFeature = defineFeature("jobsystemdb-system", (r) => {
+  r.systemScope();
+
+  r.job("check", { trigger: { manual: true } }, async (_payload, ctx) => {
+    if (!ctx.systemDb) {
+      results.push({
+        name: "system",
+        present: false,
+        boundToRawDb: undefined,
+        foreignTenantThrew: undefined,
+      });
+      return;
+    }
+    const checked = ctx.systemDb.assertTenantMatch(ctx.systemUser.tenantId);
+    let foreignTenantThrew = false;
+    try {
+      ctx.systemDb.assertTenantMatch(foreignTenant);
+    } catch {
+      foreignTenantThrew = true;
+    }
+    results.push({
+      name: "system",
+      present: true,
+      boundToRawDb: checked.raw === ctx.db,
+      foreignTenantThrew,
+    });
+  });
+
+  // perTenant jobs go through a separate dispatch path (_perTenant: wrapper
+  // fans out into one child job per tenant, job-runner.ts ~331-352) that
+  // re-enqueues under the bare qualified name before handleJob rebuilds the
+  // context — proves isJobSystemScoped() sees the same jobName fan-out
+  // children get, not the "_perTenant:"-prefixed wrapper name.
+  r.job(
+    "check-per-tenant",
+    { trigger: { manual: true }, perTenant: true },
+    async (_payload, ctx) => {
+      results.push({
+        name: "system-per-tenant",
+        present: ctx.systemDb !== undefined,
+        boundToRawDb: undefined,
+        foreignTenantThrew: undefined,
+      });
+    },
+  );
+});
+
+const tenantScopedFeature = defineFeature("jobsystemdb-tenant", (r) => {
+  r.job("check", { trigger: { manual: true } }, async (_payload, ctx) => {
+    results.push({
+      name: "tenant",
+      present: ctx.systemDb !== undefined,
+      boundToRawDb: undefined,
+      foreignTenantThrew: undefined,
+    });
+  });
+});
+
+let testDb: BunTestDb;
+let testRedis: TestRedis;
+let registry: Registry;
+let jobRunner: JobRunner;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  testRedis = await createTestRedis();
+
+  registry = createRegistry([systemScopedFeature, tenantScopedFeature]);
+
+  const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+
+  jobRunner = createJobRunner({
+    registry,
+    context: { db: testDb.db },
+    redisUrl,
+    consumerLane: "worker",
+    queueNamePrefix: `kumiko-job-systemdb-test-${Date.now()}`,
+    getActiveTenantIds: async () => [ownTenant],
+  });
+
+  await jobRunner.start();
+});
+
+afterAll(async () => {
+  await jobRunner.stop();
+  await testDb.cleanup();
+  await testRedis.cleanup();
+});
+
+describe("JobContext.systemDb", () => {
+  test("is present, tenant-bound and fail-closed for r.systemScope() jobs", async () => {
+    results.length = 0;
+    await jobRunner.dispatch("jobsystemdb-system:job:check", { tenantId: ownTenant });
+
+    await waitFor(() => {
+      const result = results.find((r) => r.name === "system");
+      expect(result).toBeDefined();
+      expect(result?.present).toBe(true);
+      expect(result?.boundToRawDb).toBe(true);
+      expect(result?.foreignTenantThrew).toBe(true);
+    });
+  });
+
+  test("is absent for non-system-scoped jobs", async () => {
+    results.length = 0;
+    await jobRunner.dispatch("jobsystemdb-tenant:job:check", { tenantId: ownTenant });
+
+    await waitFor(() => {
+      const result = results.find((r) => r.name === "tenant");
+      expect(result).toBeDefined();
+      expect(result?.present).toBe(false);
+    });
+  });
+
+  test("is present on the per-tenant fan-out child, not just the direct dispatch path", async () => {
+    results.length = 0;
+    await jobRunner.dispatch("jobsystemdb-system:job:check-per-tenant", {});
+
+    await waitFor(() => {
+      const result = results.find((r) => r.name === "system-per-tenant");
+      expect(result).toBeDefined();
+      expect(result?.present).toBe(true);
+    });
+  });
+});

package/src/jobs/job-runner.ts

@@ -2,7 +2,7 @@ import { type Job, Queue, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context";
 import type { DbConnection, DbRow } from "../db/connection";
-import { createTenantDb } from "../db/tenant-db";
+import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db";
 import { createDerivativesContext } from "../derivatives/derivatives-context";
 import { createSystemUser } from "../engine/system-user";
 import {
@@ -427,8 +427,15 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     const configDb = context.db as DbConnection | undefined; // @cast-boundary db-operator
     // Shared by the config accessor and ctx.derivatives below — both need the
     // same tenant-scoped db, and building it twice would let the two calls
-    // drift apart.
+    // drift apart. Always "system" mode regardless of the job's own
+    // systemScope() status (pre-existing, not something this change alters)
+    // — isSystemJob below is what actually keeps ctx.systemDb off a
+    // non-system job; it is the only thing standing between this db and an
+    // unchecked cross-tenant escape hatch for such a job.
     const tenantScopedDb = configDb ? createTenantDb(configDb, tenantId, "system") : undefined;
+    const isSystemJob = registry.isJobSystemScoped(jobName);
+    const systemDb =
+      isSystemJob && tenantScopedDb ? createUncheckedSystemDb(tenantScopedDb) : undefined;
     const config =
       context._configAccessorFactory && tenantScopedDb
         ? context._configAccessorFactory({
@@ -457,6 +464,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       derivatives,
       ...(notify !== undefined && { notify }),
       ...(config !== undefined && { config }),
+      ...(systemDb && { systemDb }),
       // The runner owns the registry it resolved this job from — expose it so
       // workers can reach projections/jobs without the app author duplicating
       // it into `context` (the JobContext contract guarantees `registry`).

package/src/pipeline/__tests__/ctx-systemdb.integration.test.ts

@@ -0,0 +1,67 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../../engine";
+import { setupTestStack, type TestStack, TestUsers } from "../../stack";
+
+// r.systemScope() is feature-level (define-feature.ts), not per-handler — so
+// two features prove both sides: one system-scoped, one not.
+
+const systemScopedFeature = defineFeature("ctxsystemdb-system", (r) => {
+  r.systemScope();
+
+  r.queryHandler(
+    "check",
+    z.object({}),
+    async (query, ctx) => {
+      if (!ctx.systemDb) return { present: false as const };
+      // assertTenantMatch returns the underlying TenantDb — proves systemDb
+      // is bound to the SAME internally-built TenantDb as ctx.db, not a
+      // separate instance (dispatch-shared.ts builds `as HandlerContext`,
+      // so a mis-wired property wouldn't be caught by tsc).
+      const checked = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+      return { present: true as const, boundToDb: checked === ctx.db };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+const tenantScopedFeature = defineFeature("ctxsystemdb-tenant", (r) => {
+  r.queryHandler(
+    "check",
+    z.object({}),
+    async (_query, ctx) => ({ present: ctx.systemDb !== undefined }),
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [systemScopedFeature, tenantScopedFeature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("ctx.systemDb", () => {
+  test("is present and bound to ctx.db for r.systemScope() handlers", async () => {
+    const result = await stack.http.queryOk<{ present: boolean; boundToDb: boolean }>(
+      "ctxsystemdb-system:query:check",
+      {},
+      admin,
+    );
+    expect(result.present).toBe(true);
+    expect(result.boundToDb).toBe(true);
+  });
+
+  test("is absent for non-system-scoped handlers", async () => {
+    const result = await stack.http.queryOk<{ present: boolean }>(
+      "ctxsystemdb-tenant:query:check",
+      {},
+      admin,
+    );
+    expect(result.present).toBe(false);
+  });
+});

package/src/pipeline/dispatch-shared.ts

@@ -3,7 +3,7 @@ import type { SseBroker } from "../api/sse-broker";
 import type { DbConnection, DbRunner, DbTx } from "../db/connection";
 import { runInSavepoint, selectMany } from "../db/query";
 import type { buildEntityTable } from "../db/table-builder";
-import { createTenantDb } from "../db/tenant-db";
+import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db";
 import { createDerivativesContext } from "../derivatives/derivatives-context";
 import type { defineTransitions } from "../engine/state-machine";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
@@ -183,6 +183,7 @@ export async function buildHandlerContext(
   // the client has disconnected — handlers with many sequential queries skip
   // the rest of the chain instead of burning DB-CPU for results no one reads.
   const db = dbSource ? buildTenantScopedDb(dbSource, reqCtx?.signal) : undefined;
+  const systemDb = isSystem && db ? createUncheckedSystemDb(db) : undefined;
   // Unbound pool, tenant-scoped like `db` but never tx-bound — writes
   // through it survive a rollback of the handler's own transaction. No
   // AbortSignal here: a client disconnect must not abort a durability write
@@ -573,6 +574,7 @@ export async function buildHandlerContext(
     registry,
     db,
     dbOutsideTransaction,
+    ...(systemDb && { systemDb }),
     log,
     notify,
     ...(config && { config }),

package/src/ui-types/app-schema.ts

@@ -43,6 +43,16 @@ export type FeatureSchema = {
   // Fallback erhalten damit alte clientSchema-Files (vor AppSchema)
   // ohne Migration weiter laufen — toAppSchema() hebt die Liste hoch.
   readonly workspaces?: readonly WorkspaceSchema[];
+  // True only when the server confirmed at boot that no SearchAdapter is
+  // wired on context.searchAdapter — mirrors the global (not per-entity)
+  // check behind api/server.ts's boot warning (#2051). Duplicated
+  // identically across every feature purely so it threads through the
+  // existing per-feature prop chain into screen renderers (kumiko-screen.tsx)
+  // without a separate app-level plumbing path. Omitted for schemas that
+  // don't flow through buildAppSchema() (hand-authored fixtures, legacy
+  // toAppSchema()) — treated as "not missing" so search bars keep rendering
+  // exactly as before this flag existed (#2062).
+  readonly searchAdapterMissing?: boolean;
 };
 
 // A content collection as it reaches the client: the declaration plus the