@cosmicdrift/kumiko-framework 0.159.1 → 0.160.0

package/src/files/types.ts

@@ -6,60 +6,11 @@ export type FileMetadata = {
   readonly size: number;
 };
 
-// Options for `getSignedUrl`. `contentDisposition` lets the caller hint the
-// browser to download-with-name vs inline-display (maps to ResponseContent-
-// Disposition on S3). Keep the option-bag small and additive; provider impls
-// that don't support a given hint should ignore it rather than error.
-export type SignedUrlOptions = {
-  readonly contentDisposition?: string;
-};
-
-// Options fuer `writeStream`. `mimeType` ist Content-Type-Hint analog zu
-// `write`. `contentLength` ist optional fuer Provider die einen Length-
-// Header brauchen (S3 multipart hat einen TransferManager, kann auch ohne
-// length); local-Provider ignoriert beides.
-export type WriteStreamOptions = {
-  readonly mimeType?: string;
-  readonly contentLength?: number;
-};
-
-// Primitive storage contract: key+bytes in, bytes out. Metadata (fileName,
-// mimeType, size) lives on the FileRef row — the provider only needs to
-// shuttle bytes. `mimeType` on write() is a hint for providers that need a
-// Content-Type header (S3/R2/…); local filesystems can ignore it.
-//
-// **Streaming (`writeStream` + `readStream`) ist PFLICHT** — beide
-// Methoden sind required, kein optional-feature. Begruendung:
-//   - User-Data-Export (Atom 3c) braucht beide, sonst silent fail bei
-//     erstem Job mit fileRefs in Production.
-//   - Apps die nur kleine Files (Avatar-Uploads, Profile-Pics) handeln,
-//     koennen trivial via `oneShot`-Pattern den Stream-Contract erfuellen
-//     (single-chunk yield von write/read-Bytes). 5 Zeilen pro Provider.
-//   - Optional-Type wuerde TypeScript-Lying erlauben: Type sagt "kann
-//     fehlen", Worker throws zur Runtime → App-Authors sehen den Bug
-//     erst in Production. Required + TS-enforced ist ehrlich.
-//
-// `getSignedUrl` BLEIBT optional: object-store backends (S3/R2/GCS)
-// implement it so clients can download directly from the provider after
-// the server has checked access — offloads bandwidth and enables browser-
-// native caching. Filesystem providers leave it undefined; the route then
-// returns 501 and the client falls back to streaming via GET /files/:id.
-// Callers must feature-detect via `typeof provider.getSignedUrl === "function"`.
-// Hier ist Optional korrekt weil die Fallback-Pfad existiert — kein
-// silent-fail, sondern 501 + alternativer download.
-export type FileStorageProvider = {
-  write(key: string, data: Uint8Array, mimeType?: string): Promise<void>;
-  writeStream(
-    key: string,
-    source: AsyncIterable<Uint8Array>,
-    options?: WriteStreamOptions,
-  ): Promise<void>;
-  read(key: string): Promise<Uint8Array>;
-  readStream(key: string): AsyncIterable<Uint8Array>;
-  delete(key: string): Promise<void>;
-  exists(key: string): Promise<boolean>;
-  getSignedUrl?(key: string, expiresInSeconds: number, options?: SignedUrlOptions): Promise<string>;
-};
+export type {
+  FileStorageProvider,
+  SignedUrlOptions,
+  WriteStreamOptions,
+} from "@cosmicdrift/kumiko-types/file-storage-provider-types";
 
 export type FileValidationOptions = {
   readonly maxSize?: string | undefined;

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

@@ -1,8 +1,9 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
 import { requestContext } from "../../api/request-context";
 import { createRegistry, defineFeature } from "../../engine";
 import type { AppContext, Registry } from "../../engine/types";
-import { createTestRedis, type TestRedis } from "../../stack";
+import { createTestRedis, type TestRedis, TestUsers } from "../../stack";
 import { sleep, waitFor } from "../../testing";
 import {
   createJobRunner,
@@ -103,6 +104,30 @@ const testFeature = defineFeature("test", (r) => {
       await sleep(500);
     },
   );
+  r.writeHandler(
+    "capped-event",
+    z.object({ n: z.number() }),
+    async (event) => ({ isSuccess: true, data: { n: event.payload.n } }),
+    { access: { openToAll: true } },
+  );
+  // Event-triggered twin — exercises handleEvent's maxPerTenant guard
+  // (dispatch and handleEvent share isOverPerTenantLimit).
+  r.job(
+    "perTenantLimitedEvent",
+    {
+      trigger: { on: "test:write:capped-event" },
+      concurrency: "parallel",
+      maxPerTenant: 2,
+    },
+    async (payload) => {
+      jobLog.push({
+        name: "test:job:per-tenant-limited-event",
+        payload,
+        timestamp: Date.now(),
+      });
+      await sleep(500);
+    },
+  );
 
   // Job that fails
   r.job("failingJob", { trigger: { manual: true }, retries: 1 }, async () => {
@@ -130,6 +155,18 @@ const testFeature = defineFeature("test", (r) => {
       timestamp: Date.now(),
     });
   });
+  // Exercises createJobLogger (info/warn/error/debug/child) — otherwise those
+  // one-liners stay uncovered even though every job builds a logger.
+  r.job("logProbe", { trigger: { manual: true } }, async (payload, ctx) => {
+    expect(ctx.log).toBeDefined();
+    const log = ctx.log!;
+    log.info("log-probe-info", { n: payload["n"] });
+    log.warn("log-probe-warn");
+    log.error("log-probe-error", { ok: false });
+    log.debug("log-probe-debug");
+    log.child({ probe: true }).info("log-probe-child");
+    jobLog.push({ name: "test:job:log-probe", payload, timestamp: Date.now() });
+  });
 });
 
 beforeAll(async () => {
@@ -423,6 +460,26 @@ describe("concurrency: debounce", () => {
   });
 });
 
+describe("concurrency: replace", () => {
+  test("enqueuer-only: each dispatch removes prior waiting peers", async () => {
+    // No consumer → jobs stay waiting. The replace branch walks getWaiting()
+    // and removes same-name peers before add — so three dispatches leave one.
+    await withRunner(
+      async (runner) => {
+        const id1 = await runner.dispatch("test:job:replace-job", { n: 1 });
+        const id2 = await runner.dispatch("test:job:replace-job", { n: 2 });
+        const id3 = await runner.dispatch("test:job:replace-job", { n: 3 });
+        expect(id1).toBeDefined();
+        expect(id2).toBeDefined();
+        expect(id3).toBeDefined();
+        expect(id1).not.toBe("skipped");
+        expect(id3).not.toBe(id1);
+      },
+      { consumerLane: undefined },
+    );
+  });
+});
+
 describe("concurrency: maxPerTenant", () => {
   test("max=2: third dispatch for same tenant returns skipped, other tenant unaffected", async () => {
     clearLog();
@@ -486,6 +543,18 @@ describe("concurrency: maxPerTenant", () => {
 
 // --- Correlation propagation ---
 
+describe("job logger", () => {
+  test("handler can call info/warn/error/debug/child without throw", async () => {
+    clearLog();
+    await withRunner(async (runner) => {
+      await runner.dispatch("test:job:log-probe", { n: 1 });
+      await waitFor(() => {
+        expect(jobLog.some((e) => e.name === "test:job:log-probe")).toBe(true);
+      });
+    });
+  });
+});
+
 describe("correlation propagation", () => {
   test("dispatch inside requestContext.run passes correlationId into the job", async () => {
     clearLog();
@@ -599,6 +668,38 @@ describe("error handling", () => {
       });
     });
   });
+
+  test("perTenant with getActiveTenantIds fans out one run per tenant", async () => {
+    clearLog();
+    const tenants = [101, 102];
+    await withRunner(
+      async (runner) => {
+        await runner.dispatch("test:job:per-tenant-fanout", { n: 7 });
+        await waitFor(() => {
+          const runs = jobLog.filter((e) => e.name === "test:job:per-tenant-fanout");
+          expect(runs.length).toBe(2);
+          expect(runs.every((e) => e.payload["n"] === 7)).toBe(true);
+        });
+      },
+      { getActiveTenantIds: async () => tenants },
+    );
+  });
+});
+
+describe("handleEvent maxPerTenant", () => {
+  test("skips enqueue when tenant is already at the cap", async () => {
+    clearLog();
+    await withRunner(async (runner) => {
+      const user = { ...TestUsers.admin, tenantId: "cap-tenant-evt" };
+      await runner.handleEvent("test:write:capped-event", { n: 1 }, user);
+      await runner.handleEvent("test:write:capped-event", { n: 2 }, user);
+      // Third must be skipped by the maxPerTenant guard.
+      await runner.handleEvent("test:write:capped-event", { n: 3 }, user);
+      await sleep(200);
+      const started = jobLog.filter((e) => e.name === "test:job:per-tenant-limited-event");
+      expect(started.length).toBeLessThanOrEqual(2);
+    });
+  });
 });
 
 // --- Registry ---

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

@@ -25,6 +25,17 @@ const echoFeature = defineFeature("echo", (r) => {
     { access: { openToAll: true } },
   );
 
+  r.streamHandler(
+    "item:tail",
+    z.object({ count: z.number().int().min(0) }),
+    async function* (query) {
+      for (let i = 0; i < query.payload.count; i++) {
+        yield { i };
+      }
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
   r.hook("validation", "item:create", (data) => {
     if (data["name"] === "forbidden") return [{ field: "name", error: "forbidden_name" }];
     return null;
@@ -214,6 +225,55 @@ describe("dispatcher.query", () => {
   });
 });
 
+async function collect<T>(gen: AsyncGenerator<T>): Promise<T[]> {
+  const out: T[] = [];
+  for await (const chunk of gen) out.push(chunk);
+  return out;
+}
+
+describe("dispatcher.stream", () => {
+  test("validates and calls stream handler, yielding chunks in order", async () => {
+    const dispatcher = createTestDispatcher();
+    const chunks = await collect(
+      dispatcher.stream(
+        "echo:stream:item:tail",
+        { count: 3 },
+        createTestUser({ roles: ["Admin"] }),
+      ),
+    );
+
+    expect(chunks).toEqual([{ i: 0 }, { i: 1 }, { i: 2 }]);
+  });
+
+  test("gates fire on first pull, not on the stream() call itself", async () => {
+    const dispatcher = createTestDispatcher();
+    const gen = dispatcher.stream(
+      "echo:stream:item:tail",
+      { count: -1 },
+      createTestUser({ roles: ["Admin"] }),
+    );
+
+    await expect(collect(gen)).rejects.toMatchObject({ code: "validation_error", httpStatus: 400 });
+  });
+
+  test("rejects unauthorized user", async () => {
+    const dispatcher = createTestDispatcher();
+    const guest = createTestUser({ roles: ["Guest"] });
+
+    await expect(
+      collect(dispatcher.stream("echo:stream:item:tail", { count: 1 }, guest)),
+    ).rejects.toMatchObject({ code: "access_denied" });
+  });
+
+  test("throws for unknown stream handler", async () => {
+    const dispatcher = createTestDispatcher();
+
+    await expect(
+      collect(dispatcher.stream("nonexistent", {}, createTestUser({ roles: ["Admin"] }))),
+    ).rejects.toMatchObject({ code: "not_found", httpStatus: 404 });
+  });
+});
+
 // --- postQuery hooks on standalone (entity-less) queries ---
 
 describe("dispatcher.query postQuery hooks", () => {
@@ -362,6 +422,20 @@ describe("dispatcher feature-gate", () => {
         async (event) => ({ isSuccess: true, data: { name: event.payload.name } }),
         { access: { roles: ["Admin"] } },
       );
+      r.streamHandler(
+        "widget:tail",
+        z.object({}).passthrough(),
+        async function* () {
+          // Never completes on its own — the mid-stream toggle-off test
+          // relies on the generator staying open past the first yield.
+          let i = 0;
+          while (true) {
+            yield { i };
+            i++;
+          }
+        },
+        { access: { openToAll: true } },
+      );
     });
   }
 
@@ -397,6 +471,28 @@ describe("dispatcher feature-gate", () => {
     });
   });
 
+  test("disabling the feature mid-stream aborts an already-open stream", async () => {
+    const registry = createRegistry([toggled()]);
+    const disabled = new Set<string>();
+    const dispatcher = createDispatcher(
+      registry,
+      {},
+      {
+        effectiveFeatures: () => {
+          const all = new Set(registry.features.keys());
+          for (const d of disabled) all.delete(d);
+          return all;
+        },
+      },
+    );
+
+    const gen = dispatcher.stream("toggled:stream:widget:tail", {}, user);
+    expect((await gen.next()).value).toEqual({ i: 0 });
+
+    disabled.add("toggled");
+    await expect(gen.next()).rejects.toThrow(/feature toggled is disabled/);
+  });
+
   test("write of disabled feature returns WriteFailure with feature_disabled reason", async () => {
     const registry = createRegistry([toggled()]);
     const disabled = new Set<string>(["toggled"]);

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

@@ -4,6 +4,7 @@ import {
   createEntity,
   createRegistry,
   createTextField,
+  type DeleteContext,
   defineFeature,
   type PostSaveHookFn,
   type PreSaveHookFn,
@@ -528,3 +529,210 @@ describe("buildEventId — dedup key construction", () => {
     expect(buildEventId("handler", { id: 0 }, "phase")).toBeNull();
   });
 });
+
+// --- PreDelete / PostDelete pipeline ---
+
+const deletectx: DeleteContext = {
+  kind: "delete",
+  id: 1,
+  data: { email: "test@test.de" },
+  entityName: "user",
+};
+
+describe("runPreDelete", () => {
+  test("runs feature + entity + system hooks, all inTransaction (throw on error)", async () => {
+    const calls: string[] = [];
+    const feature = defineFeature("test", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: { email: createTextField() } }));
+      r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook("preDelete", "user", async () => {
+        calls.push("handler");
+      });
+      r.hook("preDelete", { allOf: "user" }, async () => {
+        calls.push("entity");
+      });
+    });
+    const registry = createRegistry([feature]);
+    const systemHooks: SystemHooks = {
+      preDelete: [
+        {
+          name: "sys",
+          priority: 1000,
+          fn: async () => {
+            calls.push("system");
+          },
+        },
+      ],
+    };
+    const pipeline = createLifecycleHooks(registry, systemHooks);
+    await pipeline.runPreDelete("test:write:user", deletectx, {});
+    expect(calls).toEqual(["handler", "entity", "system"]);
+  });
+
+  test("a hook throwing aborts the delete (rejects, not swallowed)", async () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: { email: createTextField() } }));
+      r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook("preDelete", "user", async () => {
+        throw new Error("blocked-delete");
+      });
+    });
+    const registry = createRegistry([feature]);
+    const pipeline = createLifecycleHooks(registry);
+    await expect(pipeline.runPreDelete("test:write:user", deletectx, {})).rejects.toThrow(
+      "blocked-delete",
+    );
+  });
+
+  test("system hook with a non-inTransaction phase is skipped", async () => {
+    const registry = makeRegistry();
+    const calls: string[] = [];
+    const systemHooks: SystemHooks = {
+      preDelete: [
+        {
+          name: "sys",
+          priority: 1000,
+          phase: "afterCommit",
+          fn: async () => {
+            calls.push("system");
+          },
+        },
+      ],
+    };
+    const pipeline = createLifecycleHooks(registry, systemHooks);
+    await pipeline.runPreDelete("test:write:user", deletectx, {});
+    expect(calls).toEqual([]);
+  });
+});
+
+describe("runPostDelete", () => {
+  test("runs feature then system hooks (best-effort by default phase)", async () => {
+    const calls: string[] = [];
+    const feature = defineFeature("test", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: { email: createTextField() } }));
+      r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook("postDelete", "user", async () => {
+        calls.push("feature");
+      });
+    });
+    const registry = createRegistry([feature]);
+    const systemHooks: SystemHooks = {
+      postDelete: [
+        {
+          name: "sys",
+          priority: 1000,
+          fn: async () => {
+            calls.push("system");
+          },
+        },
+      ],
+    };
+    const pipeline = createLifecycleHooks(registry, systemHooks);
+    await pipeline.runPostDelete("test:write:user", deletectx, {});
+    expect(calls).toEqual(["feature", "system"]);
+  });
+
+  test("inTransaction phase: hook errors throw", async () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: { email: createTextField() } }));
+      r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook(
+        "postDelete",
+        "user",
+        async () => {
+          throw new Error("postDelete-inTx-boom");
+        },
+        { phase: "inTransaction" },
+      );
+    });
+    const registry = createRegistry([feature]);
+    const pipeline = createLifecycleHooks(registry);
+    await expect(
+      pipeline.runPostDelete("test:write:user", deletectx, {}, "inTransaction"),
+    ).rejects.toThrow("postDelete-inTx-boom");
+  });
+});
+
+// --- Batch hooks ---
+
+describe("runPostSaveBatch / runPostDeleteBatch", () => {
+  test("no batch hooks registered → resolves without throwing", async () => {
+    const pipeline = createLifecycleHooks(makeRegistry());
+    await expect(pipeline.runPostSaveBatch([savectx], {})).resolves.toBeUndefined();
+    await expect(pipeline.runPostDeleteBatch([deletectx], {})).resolves.toBeUndefined();
+    // Should not throw — nothing registered.
+  });
+
+  test("runPostSaveBatch runs all system hooks concurrently with the batch payload", async () => {
+    const seen: (readonly SaveContext[])[] = [];
+    const systemHooks: SystemHooks = {
+      postSaveBatch: [
+        {
+          name: "a",
+          priority: 1000,
+          fn: async (results) => {
+            seen.push(results);
+          },
+        },
+      ],
+    };
+    const pipeline = createLifecycleHooks(makeRegistry(), systemHooks);
+    await pipeline.runPostSaveBatch([savectx], {});
+    expect(seen).toEqual([[savectx]]);
+  });
+
+  test("runPostDeleteBatch runs all system hooks with the batch payload", async () => {
+    const seen: (readonly DeleteContext[])[] = [];
+    const systemHooks: SystemHooks = {
+      postDeleteBatch: [
+        {
+          name: "a",
+          priority: 1000,
+          fn: async (payloads) => {
+            seen.push(payloads);
+          },
+        },
+      ],
+    };
+    const pipeline = createLifecycleHooks(makeRegistry(), systemHooks);
+    await pipeline.runPostDeleteBatch([deletectx], {});
+    expect(seen).toEqual([[deletectx]]);
+  });
+
+  test("one batch hook throwing doesn't stop the others (Promise.allSettled) — logged, never thrown", async () => {
+    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");
+          },
+        },
+        {
+          name: "ok",
+          priority: 1001,
+          fn: async () => {
+            calls.push("ok-ran");
+          },
+        },
+      ],
+    };
+    const pipeline = createLifecycleHooks(makeRegistry(), systemHooks);
+    // Must not throw.
+    await pipeline.runPostSaveBatch([savectx], {});
+    expect(calls).toEqual(["ok-ran"]);
+    expect(consoleSpy).toHaveBeenCalled();
+    consoleSpy.mockRestore();
+  });
+});

package/src/pipeline/dispatch-shared.ts

@@ -559,7 +559,7 @@ export function buildHandlerContext(
 export async function runHandlerInstrumented<T>(
   ctx: DispatchContext,
   type: string,
-  operation: "query" | "write",
+  operation: "query" | "write" | "stream",
   user: SessionUser,
   inner: () => Promise<T>,
 ): Promise<T> {
@@ -609,6 +609,44 @@ export async function runHandlerInstrumented<T>(
   }
 }
 
+// Generator-native counterpart to runHandlerInstrumented — a stream's
+// lifetime spans every `for await` pull the caller makes, so the span
+// can't be scoped via withSpan's single-callback shape. startSpan/end
+// bracket the whole yield* instead; metrics land in the same finally
+// path so success/failure/throw all hit one emit, like the Promise path.
+export async function* runStreamInstrumented<T>(
+  ctx: DispatchContext,
+  type: string,
+  user: SessionUser,
+  inner: () => AsyncGenerator<T>,
+): AsyncGenerator<T> {
+  const { tracer: dispatcherTracer, meter: dispatcherMeter, registry } = ctx;
+  const start = performance.now();
+  let success = true;
+  let errorClass: string | undefined;
+  const span = dispatcherTracer.startSpan("kumiko.dispatcher.handler", {
+    attributes: dispatcherSpanAttributes(type, "stream", user, registry.getHandlerFeature(type)),
+  });
+  try {
+    yield* inner();
+  } catch (error) {
+    success = false;
+    errorClass = error instanceof Error && error.name ? error.name : "UnknownError";
+    span.setStatus("error", errorClass);
+    throw error;
+  } finally {
+    span.end();
+    if (!success && errorClass) {
+      emitDispatcherError(dispatcherMeter, { handler: type, errorClass });
+    }
+    emitDispatcherHandler(
+      dispatcherMeter,
+      { handler: type, success },
+      (performance.now() - start) / 1000,
+    );
+  }
+}
+
 // Feature-toggle gate. Returns the error to fold into a WriteFailure in the
 // write path, or throws for the query path (where throws flow through the
 // same outer instrumentation wrapper as other dispatcher errors).

package/src/pipeline/dispatch-stream.ts

@@ -0,0 +1,74 @@
+import type { DbTx } from "../db/connection";
+import { hasAccess } from "../engine/access";
+import type { SessionUser } from "../engine/types";
+import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors";
+import { assertNoSecretLeak } from "../secrets";
+import {
+  buildHandlerContext,
+  type DispatchContext,
+  enforceRateLimit,
+  ensureFeatureEnabled,
+  runStreamInstrumented,
+} from "./dispatch-shared";
+
+// Standalone stream execution — used by the public dispatcher.stream().
+// Chunk-by-chunk analog of executeQuery: same gate order (feature → rate-
+// limit → access → validation → handler), but yields incrementally instead
+// of returning a single response. streamHandler never entity-maps (unlike
+// write/queryHandler — see feature-entity-handlers.ts), so there's no
+// field-access filter or postQuery-hook stage to run here.
+export async function* executeStream(
+  ctx: DispatchContext,
+  type: string,
+  payload: unknown,
+  user: SessionUser,
+  tx?: DbTx,
+): AsyncGenerator<unknown> {
+  yield* runStreamInstrumented(ctx, type, user, () =>
+    executeStreamInner(ctx, type, payload, user, tx),
+  );
+}
+
+async function* executeStreamInner(
+  ctx: DispatchContext,
+  type: string,
+  payload: unknown,
+  user: SessionUser,
+  tx?: DbTx,
+): AsyncGenerator<unknown> {
+  const { registry } = ctx;
+  const handler = registry.getStreamHandler(type);
+  if (!handler) throw new NotFoundError("handler", type);
+
+  await ensureFeatureEnabled(ctx, type, user.tenantId);
+
+  if (handler.rateLimit !== undefined) {
+    await enforceRateLimit(ctx, handler.rateLimit, type, user);
+  }
+
+  if (!hasAccess(user, handler.access)) {
+    throw new AccessDeniedError({
+      message: `access denied for ${type}`,
+      details: { handler: type },
+    });
+  }
+
+  const parsed = handler.schema.safeParse(payload);
+  if (!parsed.success) {
+    throw validationErrorFromZod(parsed.error);
+  }
+
+  const handlerContext = buildHandlerContext(ctx, type, user, tx);
+  const chunks = handler.handler({ type, payload: parsed.data, user }, handlerContext);
+
+  // Consumer-driven pull (for await) is the backpressure mechanism — the
+  // handler generator only advances once the caller reads the previous
+  // chunk, no explicit buffering/throttling needed on either side.
+  for await (const chunk of chunks) {
+    // Re-checked per chunk, not just at stream-start: a feature disabled
+    // mid-stream must cut an already-open stream, not just block new ones.
+    await ensureFeatureEnabled(ctx, type, user.tenantId);
+    assertNoSecretLeak(chunk);
+    yield chunk;
+  }
+}

package/src/pipeline/dispatcher-utils.ts

@@ -38,7 +38,7 @@ export function describeShape(result: unknown): string {
 
 export function dispatcherSpanAttributes(
   type: string,
-  operation: "query" | "write",
+  operation: "query" | "write" | "stream",
   user: SessionUser,
   feature: string | undefined,
 ) {