@cosmicdrift/kumiko-framework 0.311.0 → 0.313.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.311.0",
+  "version": "0.313.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>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.311.0",
-    "@cosmicdrift/kumiko-types": "0.311.0",
+    "@cosmicdrift/kumiko-http": "0.313.0",
+    "@cosmicdrift/kumiko-types": "0.313.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.311.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.313.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/auth-routes.ts

@@ -148,6 +148,20 @@ const SignupConfirmBody = z.object({
   password: z.string().min(8).max(200),
 });
 
+// Cross-device try-first handover (kumiko-framework#3035 follow-up,
+// offlot-app#454): an optional tenant-handover grant the signup-request
+// route forwards to the handler for server-side verification and binding —
+// the grant itself never appears anywhere else (URL, mail, log, response).
+const SignupRequestBody = z.object({
+  email: z.email(),
+  handover: z
+    .object({
+      entityType: z.string().min(1).max(200),
+      token: z.string().min(1).max(4096),
+    })
+    .optional(),
+});
+
 const InviteAcceptBody = z.object({
   token: z.string().min(1),
 });
@@ -1122,6 +1136,7 @@ export function createAuthRoutes(
       dispatcher,
       path: Routes.authSignupRequest,
       requestHandler: sg.requestHandler,
+      schema: SignupRequestBody,
     });
 
     api.post(Routes.authSignupConfirm, async (c) => {
@@ -1149,6 +1164,7 @@ export function createAuthRoutes(
         kind: "auth-session";
         session: SessionUser;
         tenantKey: string;
+        handover?: { entityType: string; id: string };
       };
 
       // Session creation + JWT sign + cookies — see mintSessionAndRespond.
@@ -1168,6 +1184,11 @@ export function createAuthRoutes(
         // membership — die Frontend-UI nimmt das direkt als Redirect-
         // Target.
         tenantKey: data.tenantKey,
+        // Cross-device try-first handover (kumiko-framework#3035 follow-up):
+        // present only when signup-confirm actually claimed a bound grant —
+        // absent, not null, so a client that doesn't know the field sees
+        // nothing unusual.
+        ...(data.handover !== undefined && { handover: data.handover }),
       });
     });
   }
@@ -1462,8 +1483,12 @@ function registerTokenRequestRoute(opts: {
   dispatcher: Dispatcher;
   path: string;
   requestHandler: string;
+  // reset/verify/unlock keep the plain RequestTokenBody; signup passes its
+  // own schema (adds an optional `handover`, see SignupRequestBody above)
+  // so the extra field reaches the handler instead of being parsed away.
+  schema?: typeof RequestTokenBody | typeof SignupRequestBody;
 }): void {
-  const body = RequestTokenBody;
+  const body = opts.schema ?? RequestTokenBody;
   opts.api.post(opts.path, async (c) => {
     const raw = await c.req.json().catch(() => null);
     const parsed = body.safeParse(raw);
@@ -1478,7 +1503,7 @@ function registerTokenRequestRoute(opts: {
     // the log line (PII).
     const result = await opts.dispatcher.write(
       opts.requestHandler,
-      { email: parsed.data.email },
+      parsed.data,
       createAnonymousUser(SYSTEM_TENANT_ID),
     );
     if (!result.isSuccess) {

package/src/changes.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "DB pool close() no longer hangs forever during an outage",
+    "detail": "createDbConnection/createConnection's close() and PgKmsAdapter.close()\ncalled client.end() with no timeout, which postgres.js waits on\nindefinitely if a query is still referenced on a dead connection — a DB\noutage during process shutdown could hang forever. close() now bounds\nthe wait via a new closeTimeoutSeconds option on DbConnectionOptions\n(default 5s, DEFAULT_DB_CLOSE_TIMEOUT_SECONDS). No migration needed."
+  },
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "event-dispatcher stop() waits for a pass still in its idle pre-check",
+    "detail": "Since 0.308.0 a pass started by the timer or a NOTIFY wake-up shortly\nbefore stop() could still be inside its idle pre-check, which stop()\nnever waited for. That pass kept running after stop() returned and\nqueried the DB pool the caller was closing, which could make\npostgres.js' end() hang. stop() now also drains in-flight passes.\nNo migration needed."
+  },
+  {
+    "version": "0.313.0",
+    "type": "improvement",
+    "title": "Event-triggered jobs get the triggering event's id and headers via ctx.triggerEvent",
+    "detail": "r.job's `trigger.on` reached via an r.defineEvent QN (async, at-least-once\ndelivery through the job-trigger event consumer) had no way to key an\nidempotency check on the stored event that fired it. JobContext now\ncarries `triggerEvent?: { id, headers }` — the stored event's id and\nmetadata.headers — when the job was reached this way. Undefined for\ncron/manual jobs and for jobs triggered synchronously off a write/query\nhandler (no stored event to hand over). No migration needed."
+  },
+  {
+    "version": "0.312.0",
+    "type": "improvement",
+    "title": "files: doc/docx accepted, with magic-byte content verification",
+    "detail": "EXTENSION_MIME_WHITELIST and MAGIC_BYTE_SIGNATURES now cover .doc (application/msword, OLE signature) and .docx (application/vnd.openxmlformats-officedocument.wordprocessingml.document, ZIP signature). New exported validateFileContent(mimeType, content) checks, for doc/docx only, the declared mimeType against the file's magic bytes independent of options.accept — validateFile's own signature is unchanged (metadata-only); file-routes.ts calls validateFile first, then validateFileContent once after reading the upload body. normalizeMimeType is exported from files/types.ts as the single case/parameter-normalization helper (derivatives-context.ts's local copy was removed in favor of it)."
+  },
+  {
+    "version": "0.312.0",
+    "type": "breaking",
+    "title": "MultiStreamApplyContext gains a required registry field",
+    "migration": "Any hand-built MultiStreamApplyContext (e.g. in an MSP test that constructs the context object literal instead of using createMultiStreamApplyContext/setupTestStack) must add registry: <the app Registry instance>, the same instance HandlerContext/JobContext already expose. Lets an apply resolve extension-point usages (registry.getExtensionUsages) to pick behavior by payload discriminant, e.g. a provider-routed MSP."
+  },
+  {
+    "version": "0.312.0",
+    "type": "improvement",
+    "title": "r.job triggers can filter on payload fields via JobTrigger.where",
+    "detail": "A job's {on} trigger can now carry an optional where: equality filter on top-level event-payload fields, checked in job-runner's handleEvent before the job is enqueued (both the sync write-handler dispatch path and the async event-consumer path share this check). Lets N jobs share one broad event QN, partitioned by a payload discriminant, instead of each needing its own narrow event type."
+  },
   {
     "version": "0.310.0",
     "type": "improvement",

package/src/crypto/pg-kms-adapter.ts

@@ -1,5 +1,6 @@
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import postgres from "postgres";
+import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS } from "../db/api";
 import {
   KeyAlreadyExistsError,
   KeyErasedError,
@@ -172,7 +173,7 @@ export class PgKmsAdapter implements LocalKeyKmsAdapter {
   }
 
   async close(): Promise<void> {
-    await this.sql.end();
+    await this.sql.end({ timeout: DEFAULT_DB_CLOSE_TIMEOUT_SECONDS });
   }
 
   private ensureSchema(): Promise<void> {

package/src/db/__tests__/connection-close-outage.integration.test.ts

@@ -0,0 +1,110 @@
+// A DB outage must not turn process shutdown into a hang: postgres.js keeps
+// an in-flight query referenced on a dead socket, so a plain end() (no
+// timeout = wait for queries to finish) never resolves once the DB is gone.
+// close() has to bound that wait (db/api.ts's closeTimeoutSeconds). Routes
+// createDbConnection through a TCP proxy that stops forwarding bytes after
+// connect ("blackhole") — same simulated-outage approach as
+// pipeline/__tests__/event-dispatcher-db-outage.integration.test.ts, but
+// without touching the shared test DB's actual availability.
+
+import { afterAll, describe, expect, test } from "bun:test";
+import net from "node:net";
+import { waitFor } from "../../testing";
+import { testDatabaseUrl } from "../../testing/closed-connection-error";
+import { createDbConnection } from "../connection";
+
+function startBlackholeProxy(dbUrl: URL): {
+  readonly server: net.Server;
+  blackhole: () => void;
+  swallowedBytes: () => number;
+  destroy: () => void;
+} {
+  let blackholed = false;
+  let swallowed = 0;
+  const sockets = new Set<net.Socket>();
+  const server = net.createServer((downstream) => {
+    sockets.add(downstream);
+    const upstream = net.connect(Number(dbUrl.port), dbUrl.hostname);
+    sockets.add(upstream);
+    downstream.on("data", (chunk: Buffer) => {
+      if (blackholed) {
+        swallowed += chunk.length;
+        return;
+      }
+      upstream.write(chunk);
+    });
+    upstream.on("data", (chunk: Buffer) => {
+      if (!blackholed) downstream.write(chunk);
+    });
+    downstream.on("error", () => {});
+    upstream.on("error", () => {});
+    downstream.on("close", () => sockets.delete(downstream));
+    upstream.on("close", () => sockets.delete(upstream));
+  });
+  return {
+    server,
+    blackhole: () => {
+      blackholed = true;
+    },
+    swallowedBytes: () => swallowed,
+    destroy: () => {
+      for (const socket of sockets) socket.destroy();
+      server.close();
+    },
+  };
+}
+
+async function listenOn(server: net.Server, port: number): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, resolve);
+  });
+}
+
+let proxy: ReturnType<typeof startBlackholeProxy>;
+
+afterAll(() => {
+  proxy?.destroy();
+});
+
+describe("createDbConnection close() bounds shutdown during a DB outage", () => {
+  test("close() resolves within the bounded timeout even with in-flight queries on a dead socket", async () => {
+    const dbUrl = new URL(testDatabaseUrl());
+    proxy = startBlackholeProxy(dbUrl);
+    await listenOn(proxy.server, 0);
+    const address = proxy.server.address();
+    if (address === null || typeof address === "string") {
+      throw new Error("proxy did not bind to a TCP port");
+    }
+
+    const proxiedUrl = new URL(dbUrl.toString());
+    proxiedUrl.hostname = "127.0.0.1";
+    proxiedUrl.port = String(address.port);
+
+    const conn = createDbConnection(proxiedUrl.toString(), {
+      maxConnections: 1,
+      closeTimeoutSeconds: 1,
+    });
+
+    // Establish the connection while the proxy still forwards normally —
+    // isolates the assertion to close()'s own timeout, not connect_timeout.
+    await conn.client.unsafe("select 1");
+
+    // Fired without awaiting: once the socket goes dead, end() has to
+    // reject these instead of waiting on them forever. .catch prevents an
+    // unhandled rejection when end() tears the connection down.
+    const inFlightBeforeBlackhole = conn.client.unsafe("select 1").catch(() => undefined);
+    proxy.blackhole();
+    const inFlightAfterBlackhole = conn.client.unsafe("select 1").catch(() => undefined);
+
+    await waitFor(() => proxy.swallowedBytes() > 0);
+
+    const start = Date.now();
+    await conn.close();
+    const elapsed = Date.now() - start;
+
+    expect(elapsed).toBeLessThan(3000);
+
+    await Promise.all([inFlightBeforeBlackhole, inFlightAfterBlackhole]);
+  });
+});

package/src/db/api.ts

@@ -11,8 +11,14 @@ export type DbConnectionOptions = {
   readonly maxConnections?: number;
   readonly idleTimeoutSeconds?: number;
   readonly connectTimeoutSeconds?: number;
+  readonly closeTimeoutSeconds?: number;
 };
 
+// A DB outage can leave an in-flight query referenced on a dead connection,
+// so a plain end() (no timeout = wait for queries to finish) hangs forever —
+// close() must always bound how long shutdown waits.
+export const DEFAULT_DB_CLOSE_TIMEOUT_SECONDS = 5;
+
 // Connection-Handle: db für Queries, client für Legacy-Zugriff (LISTEN/NOTIFY-Peer
 // bei Bun.SQL), close für Pool-Shutdown.
 export type DbPoolHandle = {

package/src/db/bun-provider.ts

@@ -8,7 +8,11 @@
 // Bun.SQL hat kein LISTEN — postgres-js-Peer für event-dispatcher.
 
 import postgres from "postgres";
-import type { DbConnectionOptions, DbPoolHandle } from "./api";
+import {
+  type DbConnectionOptions,
+  type DbPoolHandle,
+  DEFAULT_DB_CLOSE_TIMEOUT_SECONDS,
+} from "./api";
 
 export function createBunConnection(url: string, options: DbConnectionOptions = {}): DbPoolHandle {
   const bunOpts: { max?: number; idleTimeout?: number; connectionTimeout?: number } = {};
@@ -25,13 +29,14 @@ export function createBunConnection(url: string, options: DbConnectionOptions =
     pgOpts.connect_timeout = options.connectTimeoutSeconds;
   const listenClient = postgres(url, pgOpts);
 
+  const closeTimeout = options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS;
   return {
     db,
     client: listenClient,
     listenClient,
     close: async () => {
-      await db.end();
-      await listenClient.end();
+      await db.end({ timeout: closeTimeout });
+      await listenClient.end({ timeout: closeTimeout });
     },
   };
 }

package/src/db/connection.ts

@@ -3,6 +3,7 @@
 import type { DbConnection, PgClient } from "@cosmicdrift/kumiko-types/db-connection";
 import postgres from "postgres";
 import { readPositiveIntEnv } from "../utils/env-parse";
+import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS } from "./api";
 
 // Raw client types (postgres-js | Bun.SQL) — the name used across query/
 // event-store/pipeline call sites. The structural pool handle from ./api is
@@ -33,9 +34,8 @@ export function createDbConnection(
   return {
     db: client,
     client,
-    close: async () => {
-      await client.end();
-    },
+    close: () =>
+      client.end({ timeout: options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS }),
   };
 }
 

package/src/db/eagerload.ts

@@ -26,6 +26,7 @@
 import { requestContext } from "../api/request-context";
 import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues } from "../crypto";
 import { selectMany } from "../db/query";
+import { parseRefTargetEntityName } from "../engine/parse-ref-target";
 import type { EntityDefinition, FieldDefinition, ReferenceFieldDef } from "../engine/types";
 import {
   collectEncryptedFieldNames,
@@ -67,21 +68,13 @@ function isReferenceField(field: FieldDefinition): field is ReferenceFieldDef {
   return field.type === "reference";
 }
 
-function parseRefEntity(raw: string): string {
-  // Same-feature ("user") oder cross-feature ("users:user") — wir
-  // brauchen nur den entity-name (Names sind global eindeutig in
-  // entityMap). Der feature-prefix dient nur der Author-Klarheit.
-  const idx = raw.indexOf(":");
-  return idx < 0 ? raw : raw.slice(idx + 1);
-}
-
 export function collectReferenceFields(entity: EntityDefinition): readonly ReferenceFieldEntry[] {
   const out: ReferenceFieldEntry[] = [];
   for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
     if (!isReferenceField(fieldDef)) continue;
     out.push({
       fieldName,
-      refEntityName: parseRefEntity(fieldDef.entity),
+      refEntityName: parseRefTargetEntityName(fieldDef.entity),
       multiple: fieldDef.multiple === true,
     });
   }

package/src/db/index.ts

@@ -114,7 +114,7 @@ export {
   type PgErrorInfo,
 } from "./pg-error";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock";
-export { executeRawQuery } from "./queries/raw-sql";
+export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql";
 export type { SelectOptions, WhereObject, WhereValue } from "./query-api";
 export {
   asRawClient,

package/src/db/postgres-provider.ts

@@ -3,7 +3,11 @@
 // `asRawClient(db)` wrappt .unsafe und .begin transparent.
 
 import postgres from "postgres";
-import type { DbConnectionOptions, DbPoolHandle } from "./api";
+import {
+  type DbConnectionOptions,
+  type DbPoolHandle,
+  DEFAULT_DB_CLOSE_TIMEOUT_SECONDS,
+} from "./api";
 
 export function createPgConnection(url: string, options: DbConnectionOptions = {}): DbPoolHandle {
   const pgOptions: Parameters<typeof postgres>[1] = {};
@@ -18,8 +22,7 @@ export function createPgConnection(url: string, options: DbConnectionOptions = {
   return {
     db: client,
     client,
-    close: async () => {
-      await client.end();
-    },
+    close: () =>
+      client.end({ timeout: options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS }),
   };
 }

package/src/db/queries/event-consumer.ts

@@ -326,11 +326,12 @@ export async function selectConsumerForUpdate(
   db: AnyDb,
   name: string,
   instanceId: string,
-): Promise<void> {
-  await asRawClient(db).unsafe(
+): Promise<Record<string, unknown> | undefined> {
+  const rows = (await asRawClient(db).unsafe(
     `SELECT * FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2 FOR UPDATE`,
     [name, instanceId],
-  );
+  )) as ReadonlyArray<Record<string, unknown>>;
+  return rows[0];
 }
 
 export async function updateConsumerRebuildCursor(

package/src/derivatives/derivatives-context.ts

@@ -14,7 +14,7 @@ import type { Registry, TenantId } from "../engine/types";
 import { InternalError, NotFoundError } from "../errors";
 import type { FileContext } from "../files/file-handle";
 import { fileRefsTable } from "../files/file-ref-table";
-import { assertSafeStorageKey } from "../files/types";
+import { assertSafeStorageKey, normalizeMimeType } from "../files/types";
 import { variantSuffix } from "./variant-key";
 
 export type DerivativesContextDeps = {
@@ -30,13 +30,6 @@ function isDerivativeRendererPlugin(o: unknown): o is DerivativeRendererPlugin {
   return typeof o === "object" && o !== null && "render" in o && typeof o.render === "function";
 }
 
-// Mirrors validateFile's mime-normalization: strip a `; charset=…` suffix,
-// trim, lowercase — so a provider-supplied `image/jpeg; charset=binary`
-// still resolves.
-function normalizeMimeType(mimeType: string): string {
-  return mimeType.toLowerCase().split(";")[0]?.trim() ?? "";
-}
-
 export function resolveRenderer(
   registry: Registry,
   mimeType: string,

package/src/engine/boot-validator/__tests__/transfer-graph.test.ts

@@ -115,6 +115,18 @@ describe("validateTransferGraph", () => {
     expect(() => validate(chain)).not.toThrow();
   });
 
+  // A feature-prefixed reference target ("<feature>:<entity>") must resolve
+  // to the same entity name as an unprefixed one, or a chain built entirely
+  // out of prefixed refs would silently never trip the depth limit.
+  test("counts a chain of feature-prefixed reference targets into the depth limit", () => {
+    const chain: Record<string, EntityDefinition> = { e0: entity({}) };
+    for (let i = 1; i <= MAX_TRANSFER_DEPTH + 1; i++) {
+      chain[`e${i}`] = entity({ references: { parentId: { entity: `graph:e${i - 1}` } } });
+    }
+
+    expect(() => validate(chain)).toThrow(/deeper than the 5-level limit.*e0 -> e1/s);
+  });
+
   test("terminates on a reference cycle instead of reporting false depth", () => {
     expect(() =>
       validate({

package/src/engine/boot-validator/transfer-graph.ts

@@ -1,3 +1,4 @@
+import { parseRefTargetEntityName } from "../parse-ref-target";
 import type { EntityDefinition, FeatureDefinition } from "../types";
 
 // --- Transfer-graph boot validation (fw#3088) ---
@@ -39,7 +40,7 @@ function referenceTargets(entity: EntityDefinition): readonly string[] {
   for (const field of Object.values(entity.fields)) {
     if (field.type !== "reference") continue;
     if (field.multiple === true) continue;
-    targets.push(field.entity);
+    targets.push(parseRefTargetEntityName(field.entity));
   }
   return targets;
 }

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

@@ -222,6 +222,9 @@ export function buildConfigEventsJobsMethods<TName extends string>(
               on: Array.isArray(jobOptions.trigger.on)
                 ? jobOptions.trigger.on.map(resolveName)
                 : resolveName(jobOptions.trigger.on as NameOrRef), // @cast-boundary engine-bridge
+              ...(jobOptions.trigger.where !== undefined
+                ? { where: jobOptions.trigger.where }
+                : {}),
             }
           : jobOptions.trigger;
       state.jobs[jobName] = { ...jobOptions, trigger, name: jobName, handler: jobHandler };

package/src/engine/index.ts

@@ -264,6 +264,8 @@ export {
   userCanReadFieldRow,
   userCanWriteFieldRow,
 } from "./ownership";
+export type { ParsedRefTarget } from "./parse-ref-target";
+export { parseRefTarget, parseRefTargetEntityName } from "./parse-ref-target";
 export { buildPipelineSteps, stepsPipeline } from "./pipeline";
 export { defineApply, defineMspApply, setFields } from "./projection-helpers";
 export type { BuiltinQnType, ParsedQn, QnType } from "./qualified-name";
@@ -431,6 +433,7 @@ export type {
   JobDefinition,
   JobHandlerFn,
   JobTrigger,
+  JobTriggerEvent,
   JsonbFieldDef,
   KumikoEntityTypeMap,
   KumikoEventTypeMap,

package/src/engine/parse-ref-target.ts

@@ -20,3 +20,9 @@ export function parseRefTarget(raw: string, currentFeature: string): ParsedRefTa
   }
   return { featureName: raw.slice(0, idx), entityName: raw.slice(idx + 1) };
 }
+
+// Entity names are globally unique in the registry, so callers that only
+// need the entity (not its owning feature) can drop the currentFeature arg.
+export function parseRefTargetEntityName(raw: string): string {
+  return parseRefTarget(raw, "").entityName;
+}

package/src/engine/registry-validate.ts

@@ -2,6 +2,7 @@ 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 { parseRefTargetEntityName } from "./parse-ref-target";
 import type {
   RegistryState,
   SearchableReferenceField,
@@ -192,16 +193,6 @@ export function applyExtensionUsages(state: RegistryState): void {
   }
 }
 
-// "customer" (same-feature) or "users:customer" (cross-feature,
-// "<featureName>:<entityName>") — only the entity name matters here, names
-// are globally unique in entityMap. Local duplicate of the same parse done
-// in db/eagerload.ts's parseRefEntity — this loop has no feature context to
-// hand to engine/parse-ref-target.ts's parseRefTarget.
-function parseReferenceTargetEntityName(raw: string): string {
-  const idx = raw.indexOf(":");
-  return idx < 0 ? raw : raw.slice(idx + 1);
-}
-
 // fw#2660: labelField defaults to "id" (a UUID column) elsewhere, but a
 // searchable reference ILIKEs the label column — an implicit or explicit
 // "id" default would 500 on every search request. Fail at boot.
@@ -224,7 +215,7 @@ function buildSearchableReferenceField(
         `(array) reference fields — remove "multiple" or "searchable".`,
     );
   }
-  const targetEntityName = parseReferenceTargetEntityName(field.entity);
+  const targetEntityName = parseRefTargetEntityName(field.entity);
   const targetEntity = entityMap.get(targetEntityName);
   if (targetEntity !== undefined) {
     if (
@@ -273,7 +264,7 @@ function buildSortableReferenceField(
   }
   return {
     fieldName,
-    targetEntityName: parseReferenceTargetEntityName(field.entity),
+    targetEntityName: parseRefTargetEntityName(field.entity),
     labelField: field.labelField,
   };
 }

package/src/engine/types/index.ts

@@ -185,6 +185,7 @@ export type {
   HandlerRef,
   JobContext,
   JobRunnerRef,
+  JobTriggerEvent,
   MemberReader,
   NameOrRef,
   NotifyFactory,