@cosmicdrift/kumiko-framework 0.197.1 → 0.199.0

package/src/jobs/job-runner.ts

@@ -2,11 +2,13 @@ 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 {
   type AppContext,
+  type DispatchWriteRef,
+  type JobContext,
   type JobRunIn,
   type Registry,
   type SessionUser,
@@ -114,6 +116,10 @@ export type JobRunner = {
     payload: Record<string, unknown>,
     user?: SessionUser,
   ): Promise<void>;
+  // Wires JobContext.write/queryAs to the real dispatcher — called once at
+  // boot, after the dispatcher exists (job-runner construction happens
+  // before it). Before this runs, JobContext.write/queryAs throw.
+  attachDispatcher(ref: DispatchWriteRef): void;
 };
 
 export type JobRunnerOptions = {
@@ -285,6 +291,9 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
   // delivery.render → delivery.send). Assigned just before return; reads happen
   // at job-execution time (after start()), so it is always defined by then.
   let selfRunner: JobRunner | undefined;
+  // Set by attachDispatcher() once the boot-level dispatcher exists.
+  // JobContext.write/queryAs throw until this is set — see JobContext doc.
+  let dispatchWriteRef: DispatchWriteRef | undefined;
 
   // Counts active + waiting jobs with this name for this tenant across
   // BOTH lane queues. Jobs with the same name should only live in one
@@ -418,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({
@@ -439,12 +455,16 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             tenantId,
           })
         : context.derivatives;
-    const jobContext: AppContext = {
+    const jobContext: JobContext = {
       ...context,
+      // Same union as configDb above — job runners are always constructed
+      // with a real DbConnection; JobContext requires it non-optional.
+      db: configDb as DbConnection, // @cast-boundary db-operator
       files,
       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`).
@@ -456,6 +476,22 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       triggeredBy: triggeredById !== null ? { id: triggeredById, tenantId } : null,
       log: createJobLogger(logs),
       ...(triggerName !== undefined && { triggerName }),
+      write: (qn: string, payload: unknown) => {
+        if (!dispatchWriteRef) {
+          throw new Error(
+            "JobContext.write called before dispatcher attached — call attachDispatcher() first",
+          );
+        }
+        return dispatchWriteRef.write(jobSystemUser, qn, payload);
+      },
+      queryAs: (user: SessionUser, qn: string, payload: unknown) => {
+        if (!dispatchWriteRef) {
+          throw new Error(
+            "JobContext.queryAs called before dispatcher attached — call attachDispatcher() first",
+          );
+        }
+        return dispatchWriteRef.queryAs(user, qn, payload);
+      },
     };
 
     await options.onJobStart?.(jobName, jobId, meta);
@@ -769,6 +805,9 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
         await queues[laneForJob(jobDef)].add(name, data);
       }
     },
+    attachDispatcher(ref: DispatchWriteRef): void {
+      dispatchWriteRef = ref;
+    },
   };
 
   selfRunner = runnerApi;

package/src/migrations/__tests__/pending-rebuilds.integration.test.ts

@@ -318,6 +318,7 @@ describe("enqueueProjectionRebuild — inline fallback (jobRunner without the jo
         dispatchCalls++;
         return "should-not-happen";
       },
+      attachDispatcher: () => {},
     };
 
     const outcome = await enqueueProjectionRebuild("pendingtest:projection:pending-counts", {

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/__tests__/dispatcher.test.ts

@@ -1021,11 +1021,11 @@ describe("dispatcher context.geoTzProvider (680/1)", () => {
 function createMockIdempotencyGuard() {
   const cache = new Map<string, string>();
   return {
-    async check(requestId: string) {
-      return cache.get(requestId) ?? null;
+    async check(tenantId: string, userId: string, requestId: string) {
+      return cache.get(`${tenantId}:${userId}:${requestId}`) ?? null;
     },
-    async store(requestId: string, result: unknown) {
-      cache.set(requestId, JSON.stringify(result));
+    async store(tenantId: string, userId: string, requestId: string, result: unknown) {
+      cache.set(`${tenantId}:${userId}:${requestId}`, JSON.stringify(result));
     },
   };
 }

package/src/pipeline/__tests__/redis-pipeline.integration.test.ts

@@ -19,9 +19,12 @@ afterAll(async () => {
 // --- Idempotency ---
 
 describe("idempotency guard", () => {
+  const tenantA = "00000000-0000-4000-8000-00000000000a";
+  const userA = "00000000-0000-4000-8000-0000000000a1";
+
   test("returns null for new request", async () => {
     const guard = createIdempotencyGuard(testRedis.redis);
-    const result = await guard.check("req-new-123");
+    const result = await guard.check(tenantA, userA, "req-new-123");
     expect(result).toBeNull();
   });
 
@@ -29,8 +32,8 @@ describe("idempotency guard", () => {
     const guard = createIdempotencyGuard(testRedis.redis);
     const requestId = "req-dup-456";
 
-    await guard.store(requestId, { isSuccess: true, data: { id: 1 } });
-    const cached = await guard.check(requestId);
+    await guard.store(tenantA, userA, requestId, { isSuccess: true, data: { id: 1 } });
+    const cached = await guard.check(tenantA, userA, requestId);
 
     expect(cached).not.toBeNull();
     if (!cached) throw new Error("expected cached value");
@@ -41,15 +44,15 @@ describe("idempotency guard", () => {
     const guard = createIdempotencyGuard(testRedis.redis, { ttlSeconds: 1 });
     const requestId = "req-ttl-789";
 
-    await guard.store(requestId, { done: true });
+    await guard.store(tenantA, userA, requestId, { done: true });
 
     // Should exist immediately
-    expect(await guard.check(requestId)).not.toBeNull();
+    expect(await guard.check(tenantA, userA, requestId)).not.toBeNull();
 
     // Wait for expiry
     await new Promise((r) => setTimeout(r, 1100));
 
-    expect(await guard.check(requestId)).toBeNull();
+    expect(await guard.check(tenantA, userA, requestId)).toBeNull();
   });
 
   test("parallel check(): second caller waits for the first's store() instead of racing", async () => {
@@ -61,11 +64,11 @@ describe("idempotency guard", () => {
     const requestId = "req-race-1";
 
     // Request #1 starts — claims the in-progress lock.
-    const first = await guard.check(requestId);
+    const first = await guard.check(tenantA, userA, requestId);
     expect(first).toBeNull(); // got the lock
 
     // Request #2 runs concurrently — must block until #1 stores a result.
-    const secondPromise = guard.check(requestId);
+    const secondPromise = guard.check(tenantA, userA, requestId);
 
     // After a tick the second must still be pending: no result yet.
     await new Promise((r) => setTimeout(r, 80));
@@ -77,7 +80,7 @@ describe("idempotency guard", () => {
     expect(quickResult.done).toBe(false);
 
     // Request #1 finishes.
-    await guard.store(requestId, { isSuccess: true, data: { id: 99 } });
+    await guard.store(tenantA, userA, requestId, { isSuccess: true, data: { id: 99 } });
 
     // Request #2 should now see the stored result, not null — no duplicate work.
     const second = await secondPromise;
@@ -93,13 +96,39 @@ describe("idempotency guard", () => {
     });
     const requestId = "req-crashed";
 
-    const first = await guard.check(requestId);
+    const first = await guard.check(tenantA, userA, requestId);
     expect(first).toBeNull(); // we acquired the lock, then "crash" — never call store()
 
     // After the pending-TTL lapses, a retry should be allowed to take over.
-    const second = await guard.check(requestId);
+    const second = await guard.check(tenantA, userA, requestId);
     expect(second).toBeNull(); // reclaimed
   });
+
+  test("same requestId from different tenant/user does not hit the same cache entry", async () => {
+    const guard = createIdempotencyGuard(testRedis.redis);
+    const requestId = "req-shared-across-tenants";
+    const tenantB = "00000000-0000-4000-8000-00000000000b";
+    const userB = "00000000-0000-4000-8000-0000000000b1";
+
+    // Tenant A / user A owns the request and stores its result.
+    const firstCheck = await guard.check(tenantA, userA, requestId);
+    expect(firstCheck).toBeNull();
+    await guard.store(tenantA, userA, requestId, { isSuccess: true, data: { tenant: "A" } });
+
+    // Same requestId, different tenant+user: must be treated as a fresh
+    // request, not see tenant A's cached/pending state.
+    const otherTenantCheck = await guard.check(tenantB, userB, requestId);
+    expect(otherTenantCheck).toBeNull();
+
+    // Different user, same tenant: also isolated.
+    const otherUserCheck = await guard.check(tenantA, userB, requestId);
+    expect(otherUserCheck).toBeNull();
+
+    // Tenant A's own result is still retrievable and unaffected.
+    const ownResult = await guard.check(tenantA, userA, requestId);
+    expect(ownResult).not.toBeNull();
+    expect(JSON.parse(ownResult as string)).toEqual({ isSuccess: true, data: { tenant: "A" } });
+  });
 });
 
 // --- Event Dedup ---

package/src/pipeline/dispatch-batch.ts

@@ -30,7 +30,7 @@ export async function runBatch(
   // Idempotency: if the same requestId has already been processed, return the
   // cached result without re-executing. The cache holds the full BatchResult.
   if (requestId && idempotency) {
-    const cached = await idempotency.check(requestId);
+    const cached = await idempotency.check(user.tenantId, user.id, requestId);
     if (cached) {
       const parsed = parseJsonSafe<BatchResult | null>(cached, null);
       if (parsed) return parsed;
@@ -42,7 +42,7 @@ export async function runBatch(
   // the same answer (both success and failure results are cached).
   const finalize = async (result: BatchResult): Promise<BatchResult> => {
     if (requestId && idempotency) {
-      await idempotency.store(requestId, result);
+      await idempotency.store(user.tenantId, user.id, requestId, result);
     }
     return result;
   };

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/pipeline/idempotency.ts

@@ -2,8 +2,8 @@ import type Redis from "ioredis";
 import { RedisKeys } from "./redis-keys";
 
 export type IdempotencyGuard = {
-  check(requestId: string): Promise<string | null>;
-  store(requestId: string, result: unknown): Promise<void>;
+  check(tenantId: string, userId: string, requestId: string): Promise<string | null>;
+  store(tenantId: string, userId: string, requestId: string, result: unknown): Promise<void>;
 };
 
 // Sentinel stored under the key while the handler is running. A second
@@ -39,8 +39,8 @@ export function createIdempotencyGuard(
     // both see a cache miss, both execute side-effects, and only one persist
     // the result. This version uses a pending-marker lock so the second caller
     // waits for the first to finish and reuses its result.
-    async check(requestId) {
-      const key = `${prefix}${requestId}`;
+    async check(tenantId, userId, requestId) {
+      const key = `${prefix}${tenantId}:${userId}:${requestId}`;
 
       // Try to acquire the in-progress lock.
       const acquired = await redis.set(key, PENDING_MARKER, "EX", pendingTtl, "NX");
@@ -67,10 +67,15 @@ export function createIdempotencyGuard(
       return null;
     },
 
-    async store(requestId, result) {
+    async store(tenantId, userId, requestId, result) {
       // Overwrite the pending marker with the real result. Plain SET (no NX)
       // on purpose: we own the lock; writing the result is the final step.
-      await redis.set(`${prefix}${requestId}`, JSON.stringify(result), "EX", ttl);
+      await redis.set(
+        `${prefix}${tenantId}:${userId}:${requestId}`,
+        JSON.stringify(result),
+        "EX",
+        ttl,
+      );
     },
   };
 }

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

package/src/ui-types/index.ts

@@ -51,7 +51,7 @@ export type {
   TextFieldDef,
 } from "../engine/types/fields";
 export type { AccessRule } from "../engine/types/handlers";
-export type { NavDefinition } from "../engine/types/nav";
+export type { NavDefinition, NavIconKey } from "../engine/types/nav";
 export type {
   ActionFormScreenDefinition,
   ConfigEditScreenDefinition,