@cosmicdrift/kumiko-framework 0.273.0 → 0.275.0

package/src/engine/define-feature.ts

@@ -29,9 +29,14 @@ function resolveFeatureNamesArgs(
   return unwrapArrayForm(args, "features");
 }
 
+export type DefineFeatureSettings = {
+  readonly dedupeOptions?: Readonly<Record<string, unknown>>;
+};
+
 export function defineFeature<const TName extends string, TExports = undefined>(
   name: TName,
   setup: (r: FeatureRegistrar<TName>) => TExports,
+  settings?: DefineFeatureSettings,
 ): FeatureDefinition & { readonly exports: TExports } {
   const state = createInitialFeatureBuilderState();
 
@@ -158,5 +163,6 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     storeTables: state.storeTables,
     ...(state.treeActions !== undefined && { treeActions: state.treeActions }),
     ...(state.envSchema !== undefined && { envSchema: state.envSchema }),
+    ...(settings?.dedupeOptions !== undefined && { dedupeOptions: settings.dedupeOptions }),
   };
 }

package/src/engine/entity-handlers.ts

@@ -102,7 +102,7 @@ type ListPayload = {
   // den gleichen Query-Handler.
   filter?: {
     readonly field: string;
-    readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+    readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
     readonly value: unknown;
   };
 };
@@ -157,7 +157,7 @@ export const entityListSchema = z.object({
   filter: z
     .object({
       field: z.string(),
-      op: z.enum(["eq", "ne", "lt", "gt", "in"]),
+      op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
       // Value ist `unknown` zur Compile-Zeit; Server-Side prüft beim
       // Build der WHERE-Clause ob der Type zum Field passt. z.unknown()
       // lässt alles durch; Type-Check kommt im executor.list.
@@ -170,7 +170,7 @@ export const entityListSchema = z.object({
     .array(
       z.object({
         field: z.string(),
-        op: z.enum(["eq", "ne", "lt", "gt", "in"]),
+        op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
         value: z.unknown(),
       }),
     )

package/src/engine/feature-ast/__tests__/parse-real-features.test.ts

@@ -68,8 +68,8 @@ const FEATURES: readonly RealFeature[] = [
   {
     path: "packages/bundled-features/src/sessions/feature.ts",
     expectedFeatureName: "sessions",
-    recognisedKinds: ["hook", "writeHandler", "queryHandler"],
-    errorMethodNames: ["storeTable", "job"],
+    recognisedKinds: ["hook", "writeHandler", "queryHandler", "job"],
+    errorMethodNames: ["storeTable"],
   },
   {
     path: "packages/bundled-features/src/auth-email-password/feature.ts",

package/src/engine/feature-config-events-jobs.ts

@@ -181,9 +181,18 @@ export function buildConfigEventsJobsMethods<TName extends string>(
               handler as JobHandlerFn,
             ]
           : (() => {
-              const { name, handler: h, ...rest } = jobNameOrDefinition;
-              return [name, rest, h] as const;
+              const { name: definedJobName, handler: h, ...rest } = jobNameOrDefinition;
+              return [definedJobName, rest, h] as const;
             })();
+      if (
+        jobOptions.escapeHatch !== undefined &&
+        jobOptions.escapeHatch.reason.trim().length === 0
+      ) {
+        throw new Error(
+          `[Feature ${name}] r.job("${jobName}") declares { escapeHatch: { reason: "" } } — ` +
+            "the reason must be a non-empty string explaining why this job needs unfiltered database access.",
+        );
+      }
       // Resolve NameOrRef(s) in trigger.on. Multi-Trigger-Form: Array
       // wird zu Array von resolved strings, Single bleibt single string —
       // job-runner unterscheidet anhand Array.isArray.

package/src/engine/index.ts

@@ -49,6 +49,7 @@ export {
 export type { App, AppConfig } from "./create-app";
 export { createApp } from "./create-app";
 export { crossTenantOverrideDenied } from "./cross-tenant";
+export { dedupeFeatures } from "./dedupe-features";
 export { defineFeature } from "./define-feature";
 export type {
   PagedQueryHandlerDefinition,

package/src/engine/registry-validate.ts

@@ -1,4 +1,5 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii";
+import { hasSearchablePlaintext, isSensitiveLabelField } from "../db/entity-field-encryption";
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch";
 import { resolveName } from "./handler-helpers";
 import type {
@@ -16,6 +17,7 @@ import {
   softDeleteGraceDaysConfig,
 } from "./soft-delete-cleanup";
 import type {
+  EntityDefinition,
   EventPiiFields,
   EventUpcastFn,
   FeatureDefinition,
@@ -206,6 +208,7 @@ function buildSearchableReferenceField(
   entityName: string,
   fieldName: string,
   field: ReferenceFieldDef,
+  entityMap: ReadonlyMap<string, EntityDefinition>,
 ): SearchableReferenceField {
   if (field.labelField === undefined || field.labelField === "id") {
     throw new Error(
@@ -220,9 +223,26 @@ function buildSearchableReferenceField(
         `(array) reference fields — remove "multiple" or "searchable".`,
     );
   }
+  const targetEntityName = parseReferenceTargetEntityName(field.entity);
+  const targetEntity = entityMap.get(targetEntityName);
+  if (targetEntity !== undefined) {
+    if (
+      isSensitiveLabelField(targetEntity, field.labelField) &&
+      !hasSearchablePlaintext(targetEntity, field.labelField)
+    ) {
+      throw new Error(
+        `[Entity ${entityName}] field "${fieldName}": searchable reference targets ` +
+          `"${targetEntityName}.${field.labelField}", which is encrypted/PII and not itself ` +
+          `searchable — there is no plaintext anywhere to match a search term against. Mark ` +
+          `"${targetEntityName}.${field.labelField}" searchable: true (add find: "fuzzy" if it ` +
+          `also carries a personal annotation, so it lands in the derived search index) or ` +
+          `remove searchable from "${fieldName}".`,
+      );
+    }
+  }
   return {
     fieldName,
-    targetEntityName: parseReferenceTargetEntityName(field.entity),
+    targetEntityName,
     labelField: field.labelField,
   };
 }
@@ -273,7 +293,9 @@ export function buildSearchableSortableCaches(state: RegistryState): void {
         }
       }
       if (field.type === "reference" && field.searchable === true) {
-        searchableReferences.push(buildSearchableReferenceField(name, fieldName, field));
+        searchableReferences.push(
+          buildSearchableReferenceField(name, fieldName, field, state.entityMap),
+        );
       }
       if (field.type === "reference" && field.sortable === true) {
         sortableReferences.push(buildSortableReferenceField(name, fieldName, field));

package/src/engine/registry.ts

@@ -1,4 +1,5 @@
 import { validateExtensionPreSaveWiring } from "./boot-validator/entity-handler";
+import { dedupeFeatures } from "./dedupe-features";
 import { buildRegistryFacade } from "./registry-facade";
 import {
   populateClaimsAndAuth,
@@ -44,7 +45,8 @@ import type { FeatureDefinition, Registry } from "./types";
 // This is where the magic happens. By "magic" I mean: precomputed maps.
 // I build everything once at boot (hooks, relations, searchable fields, ...)
 // so nothing has to iterate over objects at runtime. O(1) instead of O(n*m).
-export function createRegistry(features: readonly FeatureDefinition[]): Registry {
+export function createRegistry(rawFeatures: readonly FeatureDefinition[]): Registry {
+  const features = dedupeFeatures(rawFeatures);
   const state = createInitialState();
 
   for (const feature of features) {

package/src/engine/screen-filter-ops.ts

@@ -6,7 +6,7 @@
 //     compare nutzt der Author selten bewusst); Author kann den
 //     Filter dann einfach nicht setzen.
 //   - boolean: eq, ne (in/lt/gt sinnlos für 2-Werte-Type).
-//   - number/money/decimal/date/timestamp/locatedTimestamp: alle 5
+//   - number/money/decimal/date/timestamp/locatedTimestamp: alle 7
 //     Ops — die Felder sind natürlich vergleichbar.
 //
 // Boot-Validator nutzt diese Map um Author-Fehler früh zu fangen
@@ -17,7 +17,15 @@
 import type { FieldDefinition, ScreenFilterOp } from "./types";
 
 const EQUALITY_ONLY = ["eq", "ne", "in"] as const satisfies readonly ScreenFilterOp[];
-const COMPARABLE = ["eq", "ne", "lt", "gt", "in"] as const satisfies readonly ScreenFilterOp[];
+const COMPARABLE = [
+  "eq",
+  "ne",
+  "lt",
+  "gt",
+  "lte",
+  "gte",
+  "in",
+] as const satisfies readonly ScreenFilterOp[];
 const BOOL_OPS = ["eq", "ne"] as const satisfies readonly ScreenFilterOp[];
 
 export function getAllowedFilterOps(field: FieldDefinition): readonly ScreenFilterOp[] {

package/src/engine/soft-delete-cleanup.ts

@@ -42,9 +42,10 @@ export const softDeleteCleanupJob: JobHandlerFn = async (_payload, ctx) => {
     throw new Error("soft-delete cleanup: ctx.db + ctx.registry required (JobContext incomplete)");
   }
   // perTenant fan-out → one run per active tenant, systemUser scoped to it.
-  // The job's db is the boot DbConnection (NOT tenant-scoped), so every delete
-  // is explicitly tenant-filtered below — otherwise a tenant with a short grace
-  // would purge another tenant's still-within-grace rows.
+  // The job's db is a tenant-filtered TenantDb, but every delete is still
+  // explicitly tenant-filtered below as defense-in-depth — otherwise a
+  // tenant with a short grace would purge another tenant's still-within-grace
+  // rows.
   const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
   if (tenantId === undefined) {
     // skip: cron fired without a perTenant fan-out tenant — nothing scoped to purge

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

@@ -49,7 +49,7 @@ const systemScopedFeature = defineFeature("jobsystemdb-system", (r) => {
     results.push({
       name: "system",
       present: true,
-      boundToRawDb: tenantDbRunner(checked) === ctx.db,
+      boundToRawDb: tenantDbRunner(checked) === tenantDbRunner(ctx.db),
       foreignTenantThrew,
     });
   });

package/src/jobs/__tests__/job-tenant-db.integration.test.ts

@@ -0,0 +1,162 @@
+// fw#2914 — JobContext.db is a tenant-filtered TenantDb; unfiltered access needs r.job({ escapeHatch }).
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import type { DbRunner } from "../../db/connection";
+import { table, text, uuid } from "../../db/dialect";
+import { insertOne, selectMany } from "../../db/query";
+import { createRegistry, defineFeature, type Registry } from "../../engine";
+import type { EscapeHatchUseEvent, JobContext } from "../../engine/types";
+import { AccessDeniedError } from "../../errors";
+import { createTestRedis, type TestRedis, testTenantId, unsafePushTables } from "../../stack";
+import { waitFor } from "../../testing";
+import { createJobRunner, type JobRunner } from "../job-runner";
+
+const itemsTable = table("fw2914_job_items", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  tenantId: uuid("tenant_id").notNull(),
+  label: text("label").notNull(),
+});
+
+const ownTenant = testTenantId(1);
+const foreignTenant = testTenantId(2);
+const DECLARED_REASON = "fw#2914 integration test — job counts items of every tenant";
+
+type Outcome = {
+  readonly job: "undeclared" | "declared";
+  readonly mode?: string;
+  readonly tenantId?: string;
+  readonly labels?: readonly string[];
+  readonly foreignWhereLabels?: readonly string[];
+  readonly unsafeRawDenied?: boolean;
+  readonly rawLabels?: readonly string[];
+};
+
+const outcomes: Outcome[] = [];
+const auditEvents: EscapeHatchUseEvent[] = [];
+
+function labelsOf(rows: readonly { label: string }[]): string[] {
+  return rows.map((row) => row.label).sort();
+}
+
+const jobsFeature = defineFeature("jobtenantdb", (r) => {
+  r.job("undeclared", { trigger: { manual: true } }, async (_payload, ctx) => {
+    const own = await selectMany<{ label: string }>(ctx.db, itemsTable);
+    const foreignWhere = await selectMany<{ label: string }>(ctx.db, itemsTable, {
+      tenantId: foreignTenant,
+    });
+    let unsafeRawDenied = false;
+    try {
+      ctx.db.unsafeRaw("fw#2914 integration test — undeclared job reaching for raw");
+    } catch (err) {
+      unsafeRawDenied = err instanceof AccessDeniedError;
+    }
+    outcomes.push({
+      job: "undeclared",
+      mode: ctx.db.mode,
+      tenantId: ctx.db.tenantId,
+      labels: labelsOf(own),
+      foreignWhereLabels: labelsOf(foreignWhere),
+      unsafeRawDenied,
+    });
+  });
+
+  r.job({
+    name: "declared",
+    trigger: { manual: true },
+    escapeHatch: { reason: DECLARED_REASON },
+    handler: async (_payload, ctx) => {
+      const raw = ctx.db.unsafeRaw(DECLARED_REASON);
+      const rows = await selectMany<{ label: string }>(raw, itemsTable);
+      outcomes.push({ job: "declared", rawLabels: labelsOf(rows) });
+    },
+  });
+});
+
+let testDb: BunTestDb;
+let testRedis: TestRedis;
+let registry: Registry;
+let jobRunner: JobRunner;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  testRedis = await createTestRedis();
+  await unsafePushTables(testDb.db, { fw2914_job_items: itemsTable });
+  await insertOne(testDb.db, itemsTable, { tenantId: ownTenant, label: "own" });
+  await insertOne(testDb.db, itemsTable, { tenantId: foreignTenant, label: "foreign" });
+
+  registry = createRegistry([jobsFeature]);
+  const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+  jobRunner = createJobRunner({
+    registry,
+    context: {
+      db: testDb.db,
+      _escapeHatchAuditSink: async (event) => {
+        auditEvents.push(event);
+      },
+    },
+    redisUrl,
+    consumerLane: "worker",
+    queueNamePrefix: `kumiko-job-tenant-db-test-${Date.now()}`,
+    getActiveTenantIds: async () => [ownTenant],
+  });
+  await jobRunner.start();
+});
+
+afterAll(async () => {
+  await jobRunner.stop();
+  await testDb.cleanup();
+  await testRedis.cleanup();
+});
+
+describe("JobContext.db (fw#2914)", () => {
+  test("is tenant-filtered to the job's tenant and unsafeRaw is denied without escapeHatch", async () => {
+    outcomes.length = 0;
+    auditEvents.length = 0;
+    await jobRunner.dispatch("jobtenantdb:job:undeclared", { tenantId: ownTenant });
+
+    await waitFor(() => {
+      const outcome = outcomes.find((o) => o.job === "undeclared");
+      expect(outcome).toBeDefined();
+      expect(outcome?.mode).toBe("tenant");
+      expect(outcome?.tenantId).toBe(ownTenant);
+      expect(outcome?.labels).toEqual(["own"]);
+      expect(outcome?.foreignWhereLabels).toEqual(["own"]);
+      expect(outcome?.unsafeRawDenied).toBe(true);
+    });
+    expect(auditEvents).toHaveLength(0);
+  });
+
+  test("escapeHatch on r.job grants unfiltered access and reports one unsafe-raw audit event", async () => {
+    outcomes.length = 0;
+    auditEvents.length = 0;
+    await jobRunner.dispatch("jobtenantdb:job:declared", { tenantId: ownTenant });
+
+    await waitFor(() => {
+      const outcome = outcomes.find((o) => o.job === "declared");
+      expect(outcome?.rawLabels).toEqual(["foreign", "own"]);
+      expect(auditEvents).toHaveLength(1);
+    });
+    expect(auditEvents[0]).toMatchObject({
+      handler: "jobtenantdb:job:declared",
+      kind: "unsafe-raw",
+      reason: DECLARED_REASON,
+      tenantId: ownTenant,
+    });
+  });
+
+  test("r.job rejects an escapeHatch with an empty reason at registration", () => {
+    const register = () =>
+      defineFeature("jobtenantdb-empty", (r) => {
+        r.job("bad", { trigger: { manual: true }, escapeHatch: { reason: "   " } }, async () => {});
+      });
+    expect(register).toThrow(/r\.job\("bad"\) declares \{ escapeHatch: \{ reason: "" \} \}/);
+  });
+
+  test("JobContext.db is not assignable to a raw DbRunner", () => {
+    const acceptsRunner = (runner: DbRunner): DbRunner => runner;
+    const ctx = { db: undefined } as unknown as JobContext;
+    // @ts-expect-error — JobContext.db is a TenantDb, not a raw DbRunner (fw#2914)
+    const leaked = () => acceptsRunner(ctx.db);
+    expect(typeof leaked).toBe("function");
+  });
+});

package/src/jobs/__tests__/jobs.integration.test.ts

@@ -2,6 +2,7 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { Queue } from "bullmq";
 import { z } from "zod";
 import { requestContext } from "../../api/request-context";
+import { tenantDbRunner } from "../../db/tenant-db-runner";
 import { createRegistry, defineFeature } from "../../engine";
 import type {
   AppContext,
@@ -910,7 +911,7 @@ describe("perTenant across multiple runner instances", () => {
         async (_payload, ctx) => {
           log.push({
             tenantId: String(ctx.systemUser.tenantId),
-            runnerTag: ctx.db as unknown as string, // @cast-boundary test fixture
+            runnerTag: tenantDbRunner(ctx.db) as unknown as string, // @cast-boundary test fixture — runner context db is a tag string
           });
         },
       );
@@ -1012,7 +1013,7 @@ describe("perTenant across multiple runner instances", () => {
         await sleep(80);
         log.push({
           tenantId: String(ctx.systemUser.tenantId),
-          runnerTag: ctx.db as unknown as string, // @cast-boundary test fixture
+          runnerTag: tenantDbRunner(ctx.db) as unknown as string, // @cast-boundary test fixture — runner context db is a tag string
         });
       });
     });

package/src/jobs/job-runner.ts

@@ -2,7 +2,7 @@ import { Queue, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context";
 import type { DbConnection, DbRow } from "../db/connection";
-import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db";
+import { createTenantDb, createUncheckedSystemDb, type TenantDb } from "../db/tenant-db";
 import { createDerivativesContext } from "../derivatives/derivatives-context";
 import { createSystemUser } from "../engine/system-user";
 import {
@@ -551,20 +551,24 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     // unchecked cross-tenant escape hatch for such a job.
     const tenantScopedDb = configDb ? createTenantDb(configDb, tenantId, "system") : undefined;
     const isSystemJob = registry.isJobSystemScoped(jobName);
+    // One reporter for ctx.systemDb and ctx.db.unsafeRaw() so both dedupe in the same window.
+    const reportEscapeHatch = createEscapeHatchReporter({
+      handler: jobName,
+      tenantId,
+      actor: jobSystemUser.id,
+      sink: context._escapeHatchAuditSink,
+      log: context.log,
+    });
     const systemDb =
       isSystemJob && tenantScopedDb
-        ? createUncheckedSystemDb(
-            tenantScopedDb,
-            undefined,
-            createEscapeHatchReporter({
-              handler: jobName,
-              tenantId,
-              actor: jobSystemUser.id,
-              sink: context._escapeHatchAuditSink,
-              log: context.log,
-            }),
-          )
+        ? createUncheckedSystemDb(tenantScopedDb, undefined, reportEscapeHatch)
         : undefined;
+    const jobDb = configDb
+      ? createTenantDb(configDb, tenantId, "tenant", context.tracer, context.meter, undefined, {
+          unsafeRaw: jobDef.escapeHatch,
+          report: reportEscapeHatch,
+        })
+      : undefined;
     const config =
       context._configAccessorFactory && tenantScopedDb
         ? context._configAccessorFactory({
@@ -589,9 +593,8 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     let memberReader: MemberReader | undefined;
     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
+      // Undefined only for a runner built without a db; JobContext requires db non-optional.
+      db: jobDb as TenantDb, // @cast-boundary db-operator
       files,
       derivatives,
       ...(notify !== undefined && { notify }),