@cosmicdrift/kumiko-framework 0.164.0 → 0.165.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.164.0",
+  "version": "0.165.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>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.164.0",
+    "@cosmicdrift/kumiko-types": "0.165.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.18",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.164.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.165.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/consumer-cli.integration.test.ts

@@ -84,6 +84,36 @@ describe("runConsumerCli status", () => {
     expect(code).toBe(1);
     expect(lines.join("\n")).toContain("DATABASE_URL not set");
   });
+
+  test("--instance-id flag → status looks up the per-instance consumer, not shared", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:inst", "inst-1");
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(
+      ["status", "test:consumer:inst", "--instance-id", "inst-1"],
+      out,
+    );
+    expect(code).toBe(0);
+    const joined = lines.join("\n");
+    expect(joined).toContain('instance_id="inst-1"');
+  });
+});
+
+describe("runConsumerCli — unknown/empty subcommand exit codes", () => {
+  test("no subcommand at all → exit 0 (usage, not an error)", async () => {
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli([], out);
+    expect(code).toBe(0);
+    expect(lines.join("\n")).toContain("Subcommands:");
+  });
+
+  test("an unrecognized subcommand → exit 1", async () => {
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["bogus"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("Subcommands:");
+  });
 });
 
 describe("runConsumerCli restart", () => {

package/src/api/__tests__/api.test.ts

@@ -8,6 +8,7 @@ import {
   type TenantId,
 } from "../../engine";
 import { createTestUser, TestUsers } from "../../stack";
+import { pumpStream } from "../routes";
 import { buildServer } from "../server";
 
 const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
@@ -210,6 +211,65 @@ describe("POST /api/command", () => {
   });
 });
 
+// --- pumpStream (SSE pull loop) ---
+
+function fakeSseWriter() {
+  const frames: Array<{ event: string; data: string }> = [];
+  return {
+    frames,
+    async writeSSE(message: { event: string; data: string }) {
+      frames.push(message);
+    },
+  };
+}
+
+async function* delayedGenerator(values: readonly unknown[], delayMsByIndex: readonly number[]) {
+  for (let i = 0; i < values.length; i++) {
+    const delay = delayMsByIndex[i] ?? 0;
+    if (delay > 0) await Bun.sleep(delay);
+    yield values[i];
+  }
+}
+
+describe("pumpStream", () => {
+  test("emits a ping when the handler is slow, then still delivers the pending chunk (no loss)", async () => {
+    const writer = fakeSseWriter();
+    // heartbeatMs (10) fires before the 40ms-delayed second chunk resolves.
+    const gen = delayedGenerator([{ i: 0 }, { i: 1 }], [0, 40]);
+
+    await pumpStream(writer, gen, 10);
+
+    const events = writer.frames.map((f) => f.event);
+    expect(events[0]).toBe("chunk");
+    expect(events).toContain("ping");
+    expect(events.at(-1)).toBe("done");
+    // Both chunks arrive despite the ping in between — no chunk dropped.
+    const chunkData = writer.frames.filter((f) => f.event === "chunk").map((f) => f.data);
+    expect(chunkData).toEqual([JSON.stringify({ i: 0 }), JSON.stringify({ i: 1 })]);
+  });
+
+  test("no heartbeat fires when the handler is faster than heartbeatMs — chunks then done", async () => {
+    const writer = fakeSseWriter();
+    const gen = delayedGenerator([{ i: 0 }, { i: 1 }, { i: 2 }], [0, 0, 0]);
+
+    await pumpStream(writer, gen, 1000);
+
+    expect(writer.frames.map((f) => f.event)).toEqual(["chunk", "chunk", "chunk", "done"]);
+  });
+
+  test("a handler generator that throws propagates the error instead of swallowing it", async () => {
+    const writer = fakeSseWriter();
+    async function* throwing() {
+      yield { i: 0 };
+      throw new Error("handler-boom");
+    }
+
+    await expect(pumpStream(writer, throwing(), 1000)).rejects.toThrow("handler-boom");
+    // The chunk before the throw still made it out.
+    expect(writer.frames.map((f) => f.event)).toEqual(["chunk"]);
+  });
+});
+
 // --- SSE ---
 
 describe("GET /api/sse", () => {

package/src/api/__tests__/auth-routes-mfa-preauth-confirm.test.ts

@@ -80,7 +80,11 @@ function preauthConfirmRequest(body: unknown): Request {
 
 describe("POST /auth/mfa/preauth-confirm", () => {
   test("is public — reachable without a JWT", async () => {
-    expect(PUBLIC_API_PATHS.has("/api/auth/mfa/preauth-confirm")).toBe(true);
+    const { app } = await buildApp();
+    const res = await app.request(preauthConfirmRequest({ setupToken: "t", code: "123456" }));
+    // No Authorization header sent at all — if the route required a JWT,
+    // authMiddleware would reject with 401 before the handler ever runs.
+    expect(res.status).not.toBe(401);
   });
 
   test("not mounted when mfaPreauthConfirmHandler is unset", async () => {
@@ -100,12 +104,24 @@ describe("POST /auth/mfa/preauth-confirm", () => {
         };
       },
     });
-    const { app } = await buildApp({}, dispatcher);
+    // An active limiter, not null — "before rate-limit" is only checkable
+    // when there's a rate-limit to (not) consume.
+    const { app } = await buildApp(
+      { mfaPreauthConfirmRateLimit: createInMemoryLoginRateLimiter(2, 60_000) },
+      dispatcher,
+    );
     const res = await app.request(preauthConfirmRequest({ setupToken: "t" }));
     expect(res.status).toBe(400);
     const body = (await res.json()) as { isSuccess: boolean; error: string };
     expect(body.error).toBe("invalid_body");
     expect(dispatched).toBe(false);
+
+    // The limiter's cap (2) must still be fully available — a malformed
+    // body must not have consumed an attempt.
+    for (let i = 0; i < 5; i++) {
+      const retry = await app.request(preauthConfirmRequest({ setupToken: "t" }));
+      expect(retry.status).toBe(400);
+    }
   });
 
   test("on success: dispatches to mfaPreauthConfirmHandler, mints a JWT + cookies", async () => {

package/src/api/__tests__/login-rate-limiter-sweep.test.ts

@@ -2,25 +2,33 @@ import { describe, expect, test } from "bun:test";
 import { createInMemoryLoginRateLimiter } from "../auth-routes";
 
 describe("createInMemoryLoginRateLimiter — sweep + cap", () => {
-  test("sweepExpired drops windows that already reset before accepting a new key", async () => {
-    // Tiny thresholds so the Map hits the sweep path without flooding.
-    const limiter = createInMemoryLoginRateLimiter(10, 50, {
-      maxEntries: 100,
+  test("sweepExpired removes expired entries before enforceCap can evict a fresh key", async () => {
+    // maxAttempts=1 makes every entry a single-shot probe: a second `check`
+    // on the same key only returns true if the entry was actually removed
+    // from the map (either by expiry+sweep or by enforceCap).
+    const limiter = createInMemoryLoginRateLimiter(1, 50, {
+      maxEntries: 2,
       sweepThreshold: 2,
     });
 
-    expect(await limiter.check("a")).toBe(true);
-    expect(await limiter.check("b")).toBe(true);
-    // Wait for both windows to expire, then a third check must sweep a+b
-    // (hits.size >= sweepThreshold) before inserting "c".
+    expect(await limiter.check("old1")).toBe(true);
+    expect(await limiter.check("old2")).toBe(true);
+    // Let both windows expire.
     await Bun.sleep(60);
-    expect(await limiter.check("c")).toBe(true);
-    // Fresh window for "a" after sweep — not rate-limited.
-    expect(await limiter.check("a")).toBe(true);
+
+    // hits.size (2) >= sweepThreshold (2) → sweepExpired runs first and
+    // clears old1/old2 before "new1" is inserted, so enforceCap never fires.
+    expect(await limiter.check("new1")).toBe(true);
+    expect(await limiter.check("new2")).toBe(true);
+
+    // If enforceCap had run instead of (or before) the sweep, it would have
+    // evicted "new1" as the oldest live entry, and this check would return
+    // true (fresh window) rather than false (still rate-limited).
+    expect(await limiter.check("new1")).toBe(false);
   });
 
-  test("enforceCap drops oldest entries when the map exceeds maxEntries", async () => {
-    const limiter = createInMemoryLoginRateLimiter(100, 60_000, {
+  test("enforceCap drops the oldest entry when the map exceeds maxEntries", async () => {
+    const limiter = createInMemoryLoginRateLimiter(1, 60_000, {
       maxEntries: 3,
       sweepThreshold: 10_000, // never sweep — only the hard cap matters
     });
@@ -28,14 +36,15 @@ describe("createInMemoryLoginRateLimiter — sweep + cap", () => {
     expect(await limiter.check("k1")).toBe(true);
     expect(await limiter.check("k2")).toBe(true);
     expect(await limiter.check("k3")).toBe(true);
-    // 4th insert trips enforceCap → drops oldest (k1).
+    // 4th insert trips enforceCap → drops the oldest entry (k1).
     expect(await limiter.check("k4")).toBe(true);
 
     // k1 was dropped — a fresh check starts a new window (allowed).
     expect(await limiter.check("k1")).toBe(true);
-    // k2/k3/k4 still live in the map (cap=3 after k1 drop + k1 reinsert may
-    // drop another). Reset proves the API still works for survivors.
-    await limiter.reset("k4");
-    expect(await limiter.check("k4")).toBe(true);
+
+    // k4 must still be alive in the map: a check within its still-open
+    // window is rate-limited (count >= maxAttempts), proving enforceCap
+    // dropped k1 and not k4.
+    expect(await limiter.check("k4")).toBe(false);
   });
 });

package/src/api/routes.ts

@@ -147,28 +147,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
       });
 
       try {
-        let pending = generator.next();
-        while (true) {
-          let heartbeatTimer: ReturnType<typeof setTimeout> | undefined;
-          const heartbeat = new Promise<"heartbeat">((resolve) => {
-            heartbeatTimer = setTimeout(() => resolve("heartbeat"), SSE_HEARTBEAT_INTERVAL_MS);
-          });
-          let outcome: Awaited<typeof pending> | "heartbeat";
-          try {
-            outcome = await Promise.race([pending, heartbeat]);
-          } finally {
-            clearTimeout(heartbeatTimer);
-          }
-
-          if (outcome === "heartbeat") {
-            await stream.writeSSE({ event: "ping", data: "" });
-            continue;
-          }
-          if (outcome.done) break;
-          await stream.writeSSE({ event: "chunk", data: stringifyJson(outcome.value) });
-          pending = generator.next();
-        }
-        await stream.writeSSE({ event: "done", data: "" });
+        await pumpStream(stream, generator, SSE_HEARTBEAT_INTERVAL_MS);
       } catch (e) {
         const err = toKumiko(e);
         logServerFault(err, requestId, body.type);
@@ -181,6 +160,46 @@ export function createApiRoutes(dispatcher: Dispatcher) {
   return api;
 }
 
+export type SseWriter = {
+  readonly writeSSE: (message: { readonly event: string; readonly data: string }) => Promise<void>;
+};
+
+// Pull loop for /api/stream: races each generator.next() against a
+// heartbeat timer so a slow/idle handler still keeps the connection alive
+// ("ping" frames), forwards yielded chunks as "chunk" frames, and emits
+// "done" once the generator completes. Factored out of the route handler
+// so the heartbeat/ping and abort/cleanup paths are unit-testable with a
+// fast heartbeatMs instead of only reachable through SSE_HEARTBEAT_INTERVAL_MS
+// (15s) in a full HTTP round-trip.
+export async function pumpStream(
+  stream: SseWriter,
+  generator: AsyncGenerator<unknown>,
+  heartbeatMs: number,
+): Promise<void> {
+  let pending = generator.next();
+  while (true) {
+    let heartbeatTimer: ReturnType<typeof setTimeout> | undefined;
+    const heartbeat = new Promise<"heartbeat">((resolve) => {
+      heartbeatTimer = setTimeout(() => resolve("heartbeat"), heartbeatMs);
+    });
+    let outcome: Awaited<typeof pending> | "heartbeat";
+    try {
+      outcome = await Promise.race([pending, heartbeat]);
+    } finally {
+      clearTimeout(heartbeatTimer);
+    }
+
+    if (outcome === "heartbeat") {
+      await stream.writeSSE({ event: "ping", data: "" });
+      continue;
+    }
+    if (outcome.done) break;
+    await stream.writeSSE({ event: "chunk", data: stringifyJson(outcome.value) });
+    pending = generator.next();
+  }
+  await stream.writeSSE({ event: "done", data: "" });
+}
+
 function jsonResponse(c: Context, body: unknown, status: ContentfulStatusCode = 200) {
   return c.body(stringifyJson(body), status, { "Content-Type": "application/json" });
 }

package/src/api/server.ts

@@ -34,6 +34,7 @@ import { createEventDispatcher } from "../pipeline/event-dispatcher";
 import { createLifecycleHooks, type SystemHooks } from "../pipeline/lifecycle-pipeline";
 import { createMultiStreamApplyContext } from "../pipeline/multi-stream-apply-context";
 import {
+  createJobTriggerEventConsumer,
   createSearchEventConsumer,
   createSseBroadcastEventConsumer,
 } from "../pipeline/system-hooks";
@@ -105,12 +106,14 @@ export type ServerOptions = {
     // runs a dedicated dispatcher process, or a test needs to control the
     // consumer lifecycle manually.
     disabled?: boolean;
-    // Opt out of the auto-built system consumers (SSE, Search) while still
-    // running feature r.multiStreamProjection consumers. Useful for tests
-    // that assert only on subscriber behaviour, or for a deployment that
-    // routes SSE via a different transport. Default: both enabled when the
-    // respective dependency (sseBroker / context.searchAdapter) is available.
-    systemConsumers?: { sse?: boolean; search?: boolean };
+    // Opt out of the auto-built system consumers (SSE, Search, Job-Trigger)
+    // while still running feature r.multiStreamProjection consumers. Useful
+    // for tests that assert only on subscriber behaviour, or for a
+    // deployment that routes SSE via a different transport. Default: sse/
+    // search enabled when the respective dependency (sseBroker /
+    // context.searchAdapter) is available; jobTrigger enabled when a
+    // jobRunner is wired via dispatcherOptions.
+    systemConsumers?: { sse?: boolean; search?: boolean; jobTrigger?: boolean };
     // Raw postgres.js client for LISTEN/NOTIFY wake-up (Sprint E.4). When
     // present, `.start()` subscribes to EVENTS_PUBSUB_CHANNEL — delivery
     // latency drops from pollIntervalMs to TCP-round-trip. The poll timer
@@ -398,6 +401,8 @@ export function buildServer(options: ServerOptions): KumikoServer {
 
   const sseConsumerEnabled = options.eventDispatcher?.systemConsumers?.sse ?? true;
   const searchConsumerEnabled = options.eventDispatcher?.systemConsumers?.search ?? true;
+  const jobTriggerConsumerEnabled = options.eventDispatcher?.systemConsumers?.jobTrigger ?? true;
+  const jobRunnerForTriggers = options.dispatcherOptions?.jobRunner;
 
   const systemConsumers: EventConsumer[] = [];
   if (sseConsumerEnabled) {
@@ -406,6 +411,9 @@ export function buildServer(options: ServerOptions): KumikoServer {
   if (searchConsumerEnabled && searchAdapter) {
     systemConsumers.push(createSearchEventConsumer(searchAdapter, options.registry));
   }
+  if (jobTriggerConsumerEnabled && jobRunnerForTriggers) {
+    systemConsumers.push(createJobTriggerEventConsumer(jobRunnerForTriggers, options.registry));
+  }
 
   // MultiStreamProjections: one EventConsumer per MSP. Handler routes by
   // event.type into the MSP's apply map. MSPs aggregate cross-aggregate but

package/src/bun-db/connection.ts

@@ -6,9 +6,12 @@
 // event-dispatcher.ts. Bun.sql 1.2.20 hat kein listen() (PR oven-sh/bun#25511
 // pending). Nach Landung des Bun-LISTEN-Supports: peer raus.
 
+import type { PgListenClient } from "@cosmicdrift/kumiko-types/db-connection";
 import postgres from "postgres";
 import { readPositiveIntEnv } from "../utils/env-parse";
 
+export type { PgListenClient };
+
 // Bun.SQL ist callable als tagged template `sql\`...\`` PLUS hat methods
 // (.begin / .unsafe / .end / .file / .reserve etc.). DbConnection-Type
 // reflektiert die Instance-Shape.
@@ -21,9 +24,6 @@ export type BunDbTx = BunDbConnection;
 // Beide austauschbar im normalen call-path.
 export type BunDbRunner = BunDbConnection | BunDbTx;
 
-// Postgres-js peer NUR für event-dispatcher LISTEN.
-export type PgListenClient = ReturnType<typeof postgres>;
-
 export type BunDbConnectionOptions = {
   readonly maxConnections?: number;
   readonly idleTimeoutSeconds?: number;

package/src/db/__tests__/event-store-executor-write-verbs.integration.test.ts

@@ -50,7 +50,7 @@ describe("event-store-executor write-verbs — entity-level ownership_denied", (
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(restrictedEntity, "esWriteRestricted");
+    await unsafeCreateEntityTable(testDb.db, restrictedEntity, "esWriteRestricted");
   });
 
   beforeEach(async () => {
@@ -158,7 +158,7 @@ describe("event-store-executor write-verbs — restore without softDelete", () =
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(hardDeleteEntity, "esWriteHard");
+    await unsafeCreateEntityTable(testDb.db, hardDeleteEntity, "esWriteHard");
   });
 
   beforeEach(async () => {
@@ -199,7 +199,7 @@ describe("event-store-executor write-verbs — field-level ownership_denied", ()
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(ownedFieldEntity, "esWriteOwnedField");
+    await unsafeCreateEntityTable(testDb.db, ownedFieldEntity, "esWriteOwnedField");
   });
 
   beforeEach(async () => {
@@ -264,7 +264,7 @@ describe("event-store-executor write-verbs — version_conflict edge cases", ()
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(versionEntity, "esWriteVersion");
+    await unsafeCreateEntityTable(testDb.db, versionEntity, "esWriteVersion");
   });
 
   beforeEach(async () => {
@@ -298,13 +298,6 @@ describe("event-store-executor write-verbs — version_conflict edge cases", ()
   });
 });
 
-async function unsafeCreateEntityTableFor(
-  entity: Parameters<typeof buildEntityTable>[1],
-  name: string,
-): Promise<void> {
-  await unsafeCreateEntityTable(testDb.db, entity, name);
-}
-
 // =============================================================================
 // Concurrent update race → EventStoreVersionConflict catch + entityCache.del
 // on forget/restore (create/update/delete already exercise cache in the
@@ -341,7 +334,7 @@ describe("event-store-executor write-verbs — concurrent version race + cache",
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(raceEntity, "esWriteRace");
+    await unsafeCreateEntityTable(testDb.db, raceEntity, "esWriteRace");
   });
 
   beforeEach(async () => {

package/src/db/index.ts

@@ -35,8 +35,6 @@ export {
   enrichRowWithReferences,
   enrichWithReferences,
 } from "./eagerload";
-export type { EncryptionProvider } from "./encryption";
-export { createEncryptionProvider } from "./encryption";
 export {
   collectEncryptedFieldNames,
   configuredEntityFieldEncryption,

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

@@ -99,22 +99,6 @@ export async function selectAggregateMaxVersion(db: AnyDb, aggregateId: string):
   return rows[0]?.v ?? 0;
 }
 
-/** tenant_id the aggregate's events were written under — no membership/tenant
- *  filter. A r.systemScope() aggregate (e.g. user) lives in whichever tenant
- *  its creating executor used, which need not be a tenant the subject holds a
- *  membership in. Returns null for unknown streams. */
-export async function selectAggregateStreamTenant(
-  db: AnyDb,
-  aggregateId: string,
-  aggregateType: string,
-): Promise<string | null> {
-  const rows = (await asRawClient(db).unsafe(
-    `SELECT "tenant_id" AS t FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = $2 ORDER BY "version" LIMIT 1`,
-    [aggregateId, aggregateType],
-  )) as ReadonlyArray<{ t: string | null }>;
-  return rows[0]?.t ?? null;
-}
-
 export async function selectEventsHighWaterMark(db: AnyDb): Promise<bigint> {
   const rows = (await asRawClient(db).unsafe(
     `SELECT COALESCE(MAX("id"), 0)::bigint AS max FROM "kumiko_events"`,

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

@@ -599,6 +599,20 @@ describe("boot-validator", () => {
     expect(() => validateBoot(features)).toThrow(/a:stream:chat:complete.*missing an access rule/i);
   });
 
+  test("object-form streamHandler with access rule passes boot", () => {
+    const features = [
+      defineFeature("a", (r) => {
+        r.streamHandler({
+          name: "chat:complete",
+          schema: z.object({}),
+          handler: async function* () {},
+          access: { roles: ["User"] },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
   test("accepts openToAll access rule on a stream handler", () => {
     const features = [
       defineFeature("a", (r) => {

package/src/engine/__tests__/registry.test.ts

@@ -139,6 +139,42 @@ describe("getAllStreamHandlers", () => {
     });
     expect(() => createRegistry([aiFeature, otherFeature])).not.toThrow();
   });
+
+  test("two distinct feature names that kebab-collide throw on the qualified stream-handler clash", () => {
+    // "registry-test-kebab-dup" and "registryTestKebabDup" are different raw
+    // feature.name values (so the earlier Duplicate-feature guard doesn't
+    // fire) but toKebab() collapses both to the same qualified name.
+    const featureA = defineFeature("registry-test-kebab-dup", (r) => {
+      r.streamHandler("chat:complete", z.object({}), async function* () {});
+    });
+    const featureB = defineFeature("registryTestKebabDup", (r) => {
+      r.streamHandler("chat:complete", z.object({}), async function* () {});
+    });
+    expect(() => createRegistry([featureA, featureB])).toThrow(/Duplicate stream handler/);
+  });
+
+  test("object-form streamHandler registration preserves schema/access/rateLimit", () => {
+    const schema = z.object({ prompt: z.string() });
+    const handlerFn = async function* () {};
+    const feature = defineFeature("registry-test-object-form", (r) => {
+      r.streamHandler({
+        name: "chat:complete",
+        schema,
+        handler: handlerFn,
+        access: { openToAll: true },
+        rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 60 },
+      });
+    });
+
+    const registry = createRegistry([feature]);
+    const registered = registry.getStreamHandler("registry-test-object-form:stream:chat:complete");
+
+    expect(registered).toBeDefined();
+    expect(registered?.schema).toBe(schema);
+    expect(registered?.handler).toBe(handlerFn);
+    expect(registered?.access).toEqual({ openToAll: true });
+    expect(registered?.rateLimit).toEqual({ per: "ip+handler", limit: 5, windowSeconds: 60 });
+  });
 });
 
 describe("extensionSelector boot-validation", () => {

package/src/engine/boot-validator/entity-handler.ts

@@ -101,32 +101,21 @@ const USER_BUCKETED_RATE_LIMIT_PER: ReadonlySet<string> = new Set(["user", "user
 // at runtime, but we fail at boot to turn an easy-to-miss security regression
 // into a loud configuration error.
 export function validateHandlerAccess(feature: FeatureDefinition): void {
-  for (const [name, handler] of Object.entries(feature.writeHandlers)) {
-    if (!handler.access) {
-      throw new Error(
-        `Write handler "${feature.name}:write:${name}" is missing an access rule. ` +
-          `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
-      );
-    }
-    validateAnonymousRateLimit(feature.name, "write", name, handler.access, handler.rateLimit);
-  }
-  for (const [name, handler] of Object.entries(feature.queryHandlers)) {
-    if (!handler.access) {
-      throw new Error(
-        `Query handler "${feature.name}:query:${name}" is missing an access rule. ` +
-          `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
-      );
-    }
-    validateAnonymousRateLimit(feature.name, "query", name, handler.access, handler.rateLimit);
-  }
-  for (const [name, handler] of Object.entries(feature.streamHandlers)) {
-    if (!handler.access) {
-      throw new Error(
-        `Stream handler "${feature.name}:stream:${name}" is missing an access rule. ` +
-          `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
-      );
+  const kinds = [
+    { kind: "write" as const, label: "Write", handlers: feature.writeHandlers },
+    { kind: "query" as const, label: "Query", handlers: feature.queryHandlers },
+    { kind: "stream" as const, label: "Stream", handlers: feature.streamHandlers },
+  ];
+  for (const { kind, label, handlers } of kinds) {
+    for (const [name, handler] of Object.entries(handlers)) {
+      if (!handler.access) {
+        throw new Error(
+          `${label} handler "${feature.name}:${kind}:${name}" is missing an access rule. ` +
+            `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
+        );
+      }
+      validateAnonymousRateLimit(feature.name, kind, name, handler.access, handler.rateLimit);
     }
-    validateAnonymousRateLimit(feature.name, "stream", name, handler.access, handler.rateLimit);
   }
 }
 

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -258,6 +258,7 @@ describe("render → parse roundtrip — mixed patterns (header data + opaque bo
 // from the parsed FeaturePattern shape alone.
 const RAW_REF_FEATURE = `
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { chatCompleteHandler } from "./handlers";
 
 const eventEntity = {
   fields: { name: { type: "text", required: true } },
@@ -284,6 +285,7 @@ defineFeature("refs", (r) => {
   r.entity("event", eventEntity);
   r.entity("task", { fields: buildFields() });
   r.writeHandler(makeHandler());
+  r.streamHandler(chatCompleteHandler);
   r.screen(eventListScreen);
 });
 `;
@@ -297,6 +299,7 @@ describe("render → parse roundtrip — unresolved references (raw-ref sentinel
       { kind: "entity", entityName: "event", definition: { __raw: "eventEntity" } },
       { kind: "entity", entityName: "task", definition: { fields: { __raw: "buildFields()" } } },
       { kind: "writeHandler", handlerName: undefined },
+      { kind: "streamHandler", handlerName: undefined },
       { kind: "screen", definition: { __raw: "eventListScreen" } },
     ]);
   });
@@ -310,6 +313,7 @@ describe("render → parse roundtrip — unresolved references (raw-ref sentinel
     expect(rendered).toContain("eventEntity");
     expect(rendered).toContain("buildFields()");
     expect(rendered).toContain("r.writeHandler(makeHandler())");
+    expect(rendered).toContain("r.streamHandler(chatCompleteHandler)");
     expect(rendered).toContain("r.screen(eventListScreen);");
     // Would only appear if buildFields()'s return value got inlined.
     expect(rendered).not.toContain("title:");

package/src/engine/feature-ast/extractors/handlers.ts

@@ -204,21 +204,24 @@ export function extractWriteHandler(
   });
 }
 
-export function extractQueryHandler(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<QueryHandlerPattern> {
-  const parsed = parseHandlerCall(call, sourceFile, "queryHandler");
-  if (parsed.kind === "error") return parsed;
-  return ok({
-    kind: "queryHandler",
+function readHandlerFields(parsed: Extract<ExtractOutput<ParsedHandlerCall>, { kind: "pattern" }>) {
+  return {
     source: parsed.pattern.source,
     handlerName: parsed.pattern.handlerName,
     schemaSource: parsed.pattern.schemaSource,
     handlerBody: parsed.pattern.handlerBody,
     ...(parsed.pattern.access !== undefined && { access: parsed.pattern.access }),
     ...(parsed.pattern.rateLimit !== undefined && { rateLimit: parsed.pattern.rateLimit }),
-  });
+  };
+}
+
+export function extractQueryHandler(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<QueryHandlerPattern> {
+  const parsed = parseHandlerCall(call, sourceFile, "queryHandler");
+  if (parsed.kind === "error") return parsed;
+  return ok({ kind: "queryHandler", ...readHandlerFields(parsed) });
 }
 
 export function extractStreamHandler(
@@ -227,13 +230,5 @@ export function extractStreamHandler(
 ): ExtractOutput<StreamHandlerPattern> {
   const parsed = parseHandlerCall(call, sourceFile, "streamHandler");
   if (parsed.kind === "error") return parsed;
-  return ok({
-    kind: "streamHandler",
-    source: parsed.pattern.source,
-    handlerName: parsed.pattern.handlerName,
-    schemaSource: parsed.pattern.schemaSource,
-    handlerBody: parsed.pattern.handlerBody,
-    ...(parsed.pattern.access !== undefined && { access: parsed.pattern.access }),
-    ...(parsed.pattern.rateLimit !== undefined && { rateLimit: parsed.pattern.rateLimit }),
-  });
+  return ok({ kind: "streamHandler", ...readHandlerFields(parsed) });
 }

package/src/engine/registry-validate.ts

@@ -564,7 +564,11 @@ export function validateEntityHookTargets(
 }
 
 export function validateJobTriggers(state: RegistryState): void {
-  // Validate: job event triggers must reference existing handlers.
+  // Validate: job event triggers must reference an existing write/query
+  // handler OR an existing r.defineEvent registration. The latter is
+  // delivered async via the job-trigger event-consumer (server.ts), not
+  // the synchronous write-handler dispatch path — see
+  // createJobTriggerEventConsumer in pipeline/system-hooks.ts.
   // Multi-Trigger-Form: jeden Eintrag im Array gegen allHandlers prüfen,
   // auch wenn nur einer fehlt fail-fast.
   const allHandlers = allHandlerQns(state);
@@ -575,8 +579,9 @@ export function validateJobTriggers(state: RegistryState): void {
     for (const t of triggers) {
       const rawName = resolveName(t);
       if (allHandlers.has(rawName)) continue;
+      if (state.eventMap.has(rawName)) continue;
       throw new Error(
-        `Job "${jobName}" triggers on "${rawName}" but no handler with that name exists`,
+        `Job "${jobName}" triggers on "${rawName}" but no handler or event with that name exists`,
       );
     }
   }

package/src/engine/types/index.ts

@@ -1,7 +1,5 @@
 // Barrel: re-exports all types from @cosmicdrift/kumiko-types, plus the
 // runtime helpers below that stay framework-side.
-// Duplicate types (OnDeleteStrategy, ConfigScope, ConcurrencyMode, LifecycleHookType)
-// are defined ONLY in constants.ts — re-exported here for backwards compatibility.
 
 export type {
   ConfigAccessor,

package/src/event-store/__tests__/event-store.integration.test.ts

@@ -200,20 +200,34 @@ describe("event-store: idempotency-key conflict", () => {
   });
 
   test("omitting idempotencyKey allows unlimited appends, unchanged from before", async () => {
-    const events = await Promise.all(
-      Array.from({ length: 3 }, () =>
-        append(testDb.db, {
-          aggregateId: uuid(),
-          aggregateType: "task",
-          tenantId: tenantA,
-          expectedVersion: 0,
-          type: "task.created",
-          payload: {},
-          metadata: { userId: userA },
-        }),
-      ),
-    );
-    expect(events).toHaveLength(3);
+    // Same tenant for both, unlike the different-aggregateId version this
+    // replaces — Postgres treats every NULL as distinct even in a plain
+    // unique index, so this does NOT exercise the partial index's `WHERE
+    // ... IS NOT NULL` clause specifically (that's provable only by a
+    // duplicate NON-null key, covered above). What this does pin: a fully-
+    // omitted key and an explicit `idempotencyKey: undefined` both serialize
+    // to a JSON-absent key (JSON.stringify drops undefined) and must behave
+    // identically, rather than one silently colliding on `"idempotencyKey":null`.
+    const omitted = await append(testDb.db, {
+      aggregateId: uuid(),
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: {},
+      metadata: { userId: userA },
+    });
+    const explicitUndefined = await append(testDb.db, {
+      aggregateId: uuid(),
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: {},
+      metadata: { userId: userA, idempotencyKey: undefined },
+    });
+    expect(omitted.version).toBe(1);
+    expect(explicitUndefined.version).toBe(1);
   });
 });
 

package/src/event-store/__tests__/unscoped-stream-primitives.guard.test.ts

@@ -1,14 +1,11 @@
 import { describe, expect, test } from "bun:test";
 import { Glob } from "bun";
 
-// getUnscopedAggregateStreamMaxVersion / getUnscopedAggregateStreamTenant have
-// no tenant filter — a caller can use them to probe whether a foreign tenant's
-// aggregate exists (see event-store.ts SECURITY doc). Restricted to known
-// seed/system-internal callers; extend only for genuine new ones.
-const RESTRICTED_SYMBOLS = [
-  "getUnscopedAggregateStreamMaxVersion",
-  "getUnscopedAggregateStreamTenant",
-];
+// getUnscopedAggregateStreamMaxVersion has no tenant filter — a caller can use
+// it to probe whether a foreign tenant's aggregate exists (see event-store.ts
+// SECURITY doc). Restricted to known seed/system-internal callers; extend
+// only for genuine new ones.
+const RESTRICTED_SYMBOLS = ["getUnscopedAggregateStreamMaxVersion"];
 
 const ALLOWED_FILES = new Set([
   "packages/framework/src/event-store/event-store.ts",

package/src/event-store/event-store.ts

@@ -6,7 +6,6 @@ import {
   insertSubsequentEventRow,
   notifyPgChannel,
   selectAggregateMaxVersion,
-  selectAggregateStreamTenant,
   selectEventsHighWaterMark,
   selectStreamMaxVersion,
 } from "../db/queries/event-store";
@@ -260,21 +259,6 @@ export async function getUnscopedAggregateStreamMaxVersion(
   return selectAggregateMaxVersion(db, aggregateId);
 }
 
-/** Stream tenant of an aggregate (the tenant_id its events live under), with no
- *  membership/tenant filter. SECURITY: existence-oracle, same caveat as
- *  getUnscopedAggregateStreamMaxVersion — seed/system-internal use only. Recovers
- *  the write target for a systemScope aggregate whose stream tenant isn't one of
- *  the subject's memberships. Returns null for unknown streams. */
-export async function getUnscopedAggregateStreamTenant(
-  db: DbRunner,
-  aggregateId: string,
-  aggregateType: string,
-): Promise<TenantId | null> {
-  const tenantId = await selectAggregateStreamTenant(db, aggregateId, aggregateType);
-  // DB-boundary: kumiko_events.tenant_id is a TenantId-shaped uuid column.
-  return tenantId as TenantId | null;
-}
-
 // Global high-water-mark = MAX(events.id). Marten/Wolverine standard for
 // projection/consumer lag math: lag = HWM - cursor. Single-row aggregate over
 // the bigserial PK index — sub-millisecond cost. Returns 0n on an empty log
@@ -312,7 +296,7 @@ export async function loadEventsAfterVersion(
 // prevent.
 export const LOAD_ALL_EVENTS_ROW_LIMIT = 100_000;
 
-/** @deprecated buffers ALL matching events in memory — a memory cliff for large stores. Use `streamAllEventsByType` (yields batchwise) instead. */
+/** Buffers ALL matching events in memory — a memory cliff for large stores. Use `streamAllEventsByType` (yields batchwise) for production reads; this is test-only in practice. */
 export async function loadAllEventsByType(
   db: DbRunner,
   aggregateType: string,

package/src/event-store/index.ts

@@ -21,7 +21,6 @@ export {
   getEventsHighWaterMark,
   getStreamVersion,
   getUnscopedAggregateStreamMaxVersion,
-  getUnscopedAggregateStreamTenant,
   LOAD_ALL_EVENTS_ROW_LIMIT,
   loadAggregate,
   loadAggregateAsOf,

package/src/pipeline/__tests__/dispatcher.test.ts

@@ -2,9 +2,12 @@ import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
 import type { TenantId } from "../../engine/types/identifiers";
+import { createSecret } from "../../secrets/types";
 import { createTestUser } from "../../stack";
 import { createDispatcher } from "../dispatcher";
 
+const streamCleanupState = { closed: false };
+
 const echoFeature = defineFeature("echo", (r) => {
   r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
 
@@ -36,6 +39,29 @@ const echoFeature = defineFeature("echo", (r) => {
     { access: { roles: ["Admin"] } },
   );
 
+  r.streamHandler(
+    "item:tail-leak",
+    z.object({}),
+    async function* () {
+      yield { apiKey: createSecret("leak-me") };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.streamHandler(
+    "item:tail-cleanup",
+    z.object({}),
+    async function* () {
+      try {
+        yield { i: 0 };
+        yield { i: 1 };
+      } finally {
+        streamCleanupState.closed = true;
+      }
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
   r.hook("validation", "item:create", (data) => {
     if (data["name"] === "forbidden") return [{ field: "name", error: "forbidden_name" }];
     return null;
@@ -272,6 +298,32 @@ describe("dispatcher.stream", () => {
       collect(dispatcher.stream("nonexistent", {}, createTestUser({ roles: ["Admin"] }))),
     ).rejects.toMatchObject({ code: "not_found", httpStatus: 404 });
   });
+
+  test("a chunk containing a Secret<> value aborts the stream instead of leaking it", async () => {
+    const dispatcher = createTestDispatcher();
+
+    await expect(
+      collect(
+        dispatcher.stream("echo:stream:item:tail-leak", {}, createTestUser({ roles: ["Admin"] })),
+      ),
+    ).rejects.toMatchObject({ message: expect.stringContaining("Secret<> leaked") });
+  });
+
+  test("consumer breaking out of for-await runs the handler generator's finally block", async () => {
+    streamCleanupState.closed = false;
+    const dispatcher = createTestDispatcher();
+    const gen = dispatcher.stream(
+      "echo:stream:item:tail-cleanup",
+      {},
+      createTestUser({ roles: ["Admin"] }),
+    );
+
+    for await (const _chunk of gen) {
+      break;
+    }
+
+    expect(streamCleanupState.closed).toBe(true);
+  });
 });
 
 // --- postQuery hooks on standalone (entity-less) queries ---

package/src/pipeline/__tests__/job-trigger-consumer.integration.test.ts

@@ -0,0 +1,106 @@
+// createJobTriggerEventConsumer — proves r.job's trigger.on can fire on an
+// r.defineEvent QN appended by a multiStreamProjection's unsafeAppendEvent
+// (kumiko-framework#1505). Mirrors document-ingest-foundation's actual
+// request-ingest MSP (upload → fileRef.created → an owned defineEvent),
+// the motivating case for this fix — fileRef.created itself never reaches
+// jobRunner.handleEvent because the upload route appends it via the raw
+// event-store executor, not a write-handler dispatch (see #1505).
+//
+// Not covered here: a job triggered on a write/query-handler QN still
+// firing exactly once (unaffected by the new consumer). The full suite
+// stays green (e.g. the lane-routing sample), but that's not a positive
+// test of the partition guard — no stored event's `type` is ever a
+// handler QN in practice (entity events are "entity.verb"; custom
+// write-handlers like lane-routing's don't append to the store at all),
+// so `getWriteHandler`/`getQueryHandler` in the new consumer's handler is
+// defense-in-depth for an input shape the framework doesn't currently
+// produce, not something exercised end-to-end by any test today.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { entityEventName } from "../../db";
+import { defineFeature } from "../../engine";
+import { createInMemoryFileProvider, type InMemoryFileProvider } from "../../files";
+import { setupTestStack, type TestStack, TestUsers } from "../../stack";
+import { waitFor } from "../../testing";
+
+const ITEM_REQUESTED_EVENT_QN = "job-trigger-fixture:event:item-requested";
+const FILE_REF_CREATED = entityEventName("fileRef", "created");
+
+const processedItems: Array<{ readonly fileRefId: string }> = [];
+
+const jobTriggerFixtureFeature = defineFeature("job-trigger-fixture", (r) => {
+  r.defineEvent("item-requested", z.object({ fileRefId: z.string().min(1) }));
+
+  // Mirrors document-ingest-foundation's request-ingest MSP exactly: reacts
+  // to fileRef.created, appends a NEW event via unsafeAppendEvent — no
+  // write-handler behind the appended event itself.
+  r.multiStreamProjection({
+    name: "request-item",
+    apply: {
+      [FILE_REF_CREATED]: async (event, _tx, ctx) => {
+        await ctx.unsafeAppendEvent({
+          aggregateId: event.aggregateId,
+          aggregateType: "job-trigger-fixture-request",
+          type: ITEM_REQUESTED_EVENT_QN,
+          payload: { fileRefId: event.aggregateId },
+        });
+      },
+    },
+  });
+
+  // Under test: only reachable via createJobTriggerEventConsumer, since
+  // ITEM_REQUESTED_EVENT_QN is an r.defineEvent QN, not a handler QN.
+  r.job(
+    "process-item",
+    { trigger: { on: ITEM_REQUESTED_EVENT_QN }, runIn: "worker" },
+    async (payload) => {
+      processedItems.push({ fileRefId: payload["fileRefId"] as string });
+    },
+  );
+});
+
+let stack: TestStack;
+let provider: InMemoryFileProvider;
+
+beforeAll(async () => {
+  provider = createInMemoryFileProvider();
+  stack = await setupTestStack({
+    features: [jobTriggerFixtureFeature],
+    files: { storageProvider: provider },
+    jobs: { consumerLane: "worker" },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  processedItems.length = 0;
+  provider.clear();
+});
+
+describe("job-trigger event consumer", () => {
+  test("a job triggers on an r.defineEvent QN appended by an MSP's unsafeAppendEvent", async () => {
+    const token = await stack.jwt.sign(TestUsers.admin);
+    const formData = new FormData();
+    formData.append("file", new File([Buffer.from("hello")], "note.txt", { type: "text/plain" }));
+    const res = await stack.app.request("/api/files", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+      body: formData,
+    });
+    expect(res.status).toBe(201);
+
+    await waitFor(async () => {
+      // Drives both the MSP (appends item-requested off fileRef.created)
+      // and the new job-trigger consumer (reacts to it) — may need more
+      // than one pass since the MSP's append happens mid-drain.
+      await stack.eventDispatcher?.runOnce();
+      expect(processedItems).toHaveLength(1);
+    });
+
+    expect(processedItems[0]?.fileRefId).toBeTruthy();
+  });
+});

package/src/pipeline/__tests__/lifecycle-pipeline.test.ts

@@ -707,30 +707,43 @@ describe("runPostSaveBatch / runPostDeleteBatch", () => {
     expect(seen).toEqual([[deletectx]]);
   });
 
-  test("one batch hook throwing doesn't stop the others (Promise.allSettled) — logged, never thrown", async () => {
+  test.each([
+    [
+      "postSaveBatch",
+      (hooks: { name: string; priority: number; fn: () => Promise<void> }[]) =>
+        ({ postSaveBatch: hooks }) satisfies SystemHooks,
+      (pipeline: ReturnType<typeof createLifecycleHooks>) =>
+        pipeline.runPostSaveBatch([savectx], {}),
+    ],
+    [
+      "postDeleteBatch",
+      (hooks: { name: string; priority: number; fn: () => Promise<void> }[]) =>
+        ({ postDeleteBatch: hooks }) satisfies SystemHooks,
+      (pipeline: ReturnType<typeof createLifecycleHooks>) =>
+        pipeline.runPostDeleteBatch([deletectx], {}),
+    ],
+  ])("one %s hook throwing doesn't stop the others (Promise.allSettled) — logged, never thrown", async (_name, buildHooks, run) => {
     const consoleSpy = spyOn(console, "error").mockImplementation(() => {});
     const calls: string[] = [];
-    const systemHooks: SystemHooks = {
-      postSaveBatch: [
-        {
-          name: "failing",
-          priority: 1000,
-          fn: async () => {
-            throw new Error("batch-hook-boom");
-          },
+    const systemHooks = buildHooks([
+      {
+        name: "failing",
+        priority: 1000,
+        fn: async () => {
+          throw new Error("batch-hook-boom");
         },
-        {
-          name: "ok",
-          priority: 1001,
-          fn: async () => {
-            calls.push("ok-ran");
-          },
+      },
+      {
+        name: "ok",
+        priority: 1001,
+        fn: async () => {
+          calls.push("ok-ran");
         },
-      ],
-    };
+      },
+    ]);
     const pipeline = createLifecycleHooks(makeRegistry(), systemHooks);
     // Must not throw.
-    await pipeline.runPostSaveBatch([savectx], {});
+    await run(pipeline);
     expect(calls).toEqual(["ok-ran"]);
     expect(consoleSpy).toHaveBeenCalled();
     consoleSpy.mockRestore();

package/src/pipeline/dispatch-stream.ts

@@ -1,4 +1,3 @@
-import type { DbTx } from "../db/connection";
 import { hasAccess } from "../engine/access";
 import type { SessionUser } from "../engine/types";
 import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors";
@@ -22,11 +21,8 @@ export async function* executeStream(
   type: string,
   payload: unknown,
   user: SessionUser,
-  tx?: DbTx,
 ): AsyncGenerator<unknown> {
-  yield* runStreamInstrumented(ctx, type, user, () =>
-    executeStreamInner(ctx, type, payload, user, tx),
-  );
+  yield* runStreamInstrumented(ctx, type, user, () => executeStreamInner(ctx, type, payload, user));
 }
 
 async function* executeStreamInner(
@@ -34,7 +30,6 @@ async function* executeStreamInner(
   type: string,
   payload: unknown,
   user: SessionUser,
-  tx?: DbTx,
 ): AsyncGenerator<unknown> {
   const { registry } = ctx;
   const handler = registry.getStreamHandler(type);
@@ -58,7 +53,7 @@ async function* executeStreamInner(
     throw validationErrorFromZod(parsed.error);
   }
 
-  const handlerContext = buildHandlerContext(ctx, type, user, tx);
+  const handlerContext = buildHandlerContext(ctx, type, user);
   const chunks = handler.handler({ type, payload: parsed.data, user }, handlerContext);
 
   // Consumer-driven pull (for await) is the backpressure mechanism — the

package/src/pipeline/event-dispatcher-delivery.ts

@@ -194,7 +194,8 @@ export type DeliveryOutcome = {
 
 // Deliver events to the consumer's handler in events.id order. Halt-on-
 // poison: a throw breaks the loop, the cursor stays at the last successful
-// event, and attempts climb. At maxAttempts the caller persists status=
+// event, and attempts climb. At the consumer's effectiveMaxAttempts
+// (errorPolicy.maxAttempts ?? maxAttempts) the caller persists status=
 // "dead" and the consumer is parked until ops intervenes (see
 // restartConsumer / skipPoisonEvent).
 export async function deliverEvents(

package/src/pipeline/system-hooks.ts

@@ -1,7 +1,7 @@
 import type { SseBroker } from "../api/sse-broker";
 import type { DbRow } from "../db/connection";
 import { tenantChannel } from "../engine/constants";
-import type { EntityId, Registry } from "../engine/types";
+import type { EntityId, JobRunnerRef, Registry, SessionUser } from "../engine/types";
 import type { SearchAdapter, SearchDocument } from "../search/types";
 import type { EventConsumer } from "./event-dispatcher";
 
@@ -249,3 +249,52 @@ export function createSseBroadcastEventConsumer(sseBroker: SseBroker): EventCons
     },
   };
 }
+
+// --- Job-Trigger Consumer (async, via event-dispatcher) ---
+//
+// r.job's `trigger.on` historically only fired via the synchronous
+// write-handler dispatch path (dispatch-write.ts's afterCommitHooks calling
+// jobRunner.handleEvent). Events appended any other way — an
+// r.multiStreamProjection's ctx.unsafeAppendEvent, or a raw
+// event-store-executor write (e.g. `files`' fileRef.created) — never
+// reached it, so a job could never trigger on an r.defineEvent-registered
+// event (kumiko-framework#1505).
+//
+// This consumer closes that gap the same way search/SSE do: read every
+// committed event off the shared cursor and re-check job triggers. It is
+// scoped EXACTLY to the gap — the write/query-handler-QN skip below is
+// defense-in-depth: no stored event's `type` is a handler QN today (entity
+// events are "entity.verb"; ctx.appendEvent enforces defineEvent-only
+// ownership), but if that ever changes, this consumer must not re-fire a
+// trigger the synchronous dispatch-write.ts path already handled.
+//
+// Delivery is at-least-once (cursor semantics) where the synchronous path
+// is effectively once — job handlers reached via an r.defineEvent trigger
+// must be idempotent (same expectation r.multiStreamProjection applies
+// already carry).
+export const JOB_TRIGGER_CONSUMER_NAME = "system:consumer:job-trigger";
+
+export function createJobTriggerEventConsumer(
+  jobRunner: JobRunnerRef,
+  registry: Registry,
+): EventConsumer {
+  return {
+    name: JOB_TRIGGER_CONSUMER_NAME,
+    handler: async (event) => {
+      // skip: write/query-handler QN — already dispatched synchronously by
+      // dispatch-write.ts's afterCommitHooks. Re-firing here would
+      // double-enqueue every existing handler-triggered job.
+      if (registry.getWriteHandler(event.type) || registry.getQueryHandler(event.type)) return;
+      // skip: no r.defineEvent registered under this type — nothing this
+      // consumer is responsible for.
+      if (!registry.getEvent(event.type)) return;
+
+      const user: SessionUser = {
+        id: event.metadata.userId,
+        tenantId: event.tenantId,
+        roles: [],
+      };
+      await jobRunner.handleEvent(event.type, event.payload, user);
+    },
+  };
+}

package/src/db/__tests__/encryption.test.ts

@@ -1,39 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { createEncryptionProvider } from "../encryption";
-
-// 32 bytes base64-encoded for AES-256
-const TEST_KEY = Buffer.from("a]bJm#kP9xQ2@wN!vL$hR5yT8eU0iO3f").toString("base64");
-
-describe("EncryptionProvider", () => {
-  test("encrypt + decrypt roundtrip returns original", () => {
-    const provider = createEncryptionProvider(TEST_KEY);
-    const ciphertext = provider.encrypt("hello world");
-    expect(provider.decrypt(ciphertext)).toBe("hello world");
-  });
-
-  test("same plaintext produces different ciphertexts (random IV)", () => {
-    const provider = createEncryptionProvider(TEST_KEY);
-    const a = provider.encrypt("same");
-    const b = provider.encrypt("same");
-    expect(a).not.toBe(b);
-  });
-
-  test("decrypt with different key throws", () => {
-    const key2 = Buffer.from("x]bJm#kP9xQ2@wN!vL$hR5yT8eU0iO3f").toString("base64");
-    const p1 = createEncryptionProvider(TEST_KEY);
-    const p2 = createEncryptionProvider(key2);
-    const ciphertext = p1.encrypt("secret");
-    expect(() => p2.decrypt(ciphertext)).toThrow();
-  });
-
-  test("handles unicode and emoji", () => {
-    const provider = createEncryptionProvider(TEST_KEY);
-    const ciphertext = provider.encrypt("Ünïcödé 🔐");
-    expect(provider.decrypt(ciphertext)).toBe("Ünïcödé 🔐");
-  });
-
-  test("throws on invalid key length", () => {
-    const shortKey = Buffer.from("too-short").toString("base64");
-    expect(() => createEncryptionProvider(shortKey)).toThrow(/32 bytes/);
-  });
-});

package/src/db/encryption.ts

@@ -1,45 +0,0 @@
-import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
-
-const ALGORITHM = "aes-256-gcm";
-const IV_LENGTH = 12;
-const TAG_LENGTH = 16;
-
-export type EncryptionProvider = {
-  encrypt(plaintext: string): string;
-  decrypt(ciphertext: string): string;
-};
-
-/**
- * @deprecated Legacy single-key format: base64(iv+tag+ct) with NO key id —
- * a key change makes existing ciphertexts permanently undecryptable. Use
- * `createEnvelopeCipher` (@cosmicdrift/kumiko-framework/secrets) for new code;
- * this provider has no consumers left in the framework.
- */
-export function createEncryptionProvider(key: string): EncryptionProvider {
-  // Key must be 32 bytes for AES-256
-  const keyBuffer = Buffer.from(key, "base64");
-  if (keyBuffer.length !== 32) {
-    throw new Error("ENCRYPTION_KEY must be 32 bytes (base64 encoded)");
-  }
-
-  return {
-    encrypt(plaintext: string): string {
-      const iv = randomBytes(IV_LENGTH);
-      const cipher = createCipheriv(ALGORITHM, keyBuffer, iv);
-      const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
-      const tag = cipher.getAuthTag();
-      // Format: base64(iv + tag + ciphertext)
-      return Buffer.concat([iv, tag, encrypted]).toString("base64");
-    },
-
-    decrypt(ciphertext: string): string {
-      const data = Buffer.from(ciphertext, "base64");
-      const iv = data.subarray(0, IV_LENGTH);
-      const tag = data.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
-      const encrypted = data.subarray(IV_LENGTH + TAG_LENGTH);
-      const decipher = createDecipheriv(ALGORITHM, keyBuffer, iv);
-      decipher.setAuthTag(tag);
-      return decipher.update(encrypted) + decipher.final("utf8");
-    },
-  };
-}