@cosmicdrift/kumiko-framework 0.165.0 → 0.165.1

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

@@ -1,12 +1,22 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { Queue } from "bullmq";
 import { z } from "zod";
 import { requestContext } from "../../api/request-context";
 import { createRegistry, defineFeature } from "../../engine";
-import type { AppContext, Registry } from "../../engine/types";
+import type {
+  AppContext,
+  ConfigAccessor,
+  ConfigAccessorFactory,
+  NotifyFactory,
+  Registry,
+  TenantId,
+} from "../../engine/types";
+import { createInMemoryFileProvider } from "../../files/in-memory-provider";
 import { createTestRedis, type TestRedis, TestUsers } from "../../stack";
 import { sleep, waitFor } from "../../testing";
 import {
   createJobRunner,
+  type JobLogEntry,
   type JobMeta,
   type JobRunner,
   type JobRunnerOptions,
@@ -167,6 +177,30 @@ const testFeature = defineFeature("test", (r) => {
     log.child({ probe: true }).info("log-probe-child");
     jobLog.push({ name: "test:job:log-probe", payload, timestamp: Date.now() });
   });
+  // job-runner must build ctx.files the same way dispatch-shared.ts does for
+  // write-handlers/MSPs — regression guard for #1520 (ctx.files was never
+  // materialized for jobs, so ctx.files.ref(...).read() threw for every job).
+  r.job("filesProbe", { trigger: { manual: true } }, async (payload, ctx) => {
+    const content = await ctx.files!.ref(payload["key"] as string).read();
+    jobLog.push({
+      name: "test:job:files-probe",
+      payload: { text: new TextDecoder().decode(content) },
+      timestamp: Date.now(),
+    });
+  });
+
+  // job-runner must build ctx.notify/ctx.config the same way dispatch-shared.ts
+  // does for write-handlers — regression guard for #1532 (only ctx.files got
+  // the same fix; ctx.notify/ctx.config stayed undefined for every job).
+  r.job("notifyProbe", { trigger: { manual: true } }, async (payload, ctx) => {
+    await ctx.notify!("test-notification", { to: payload["toUserId"] as string });
+    jobLog.push({ name: "test:job:notify-probe", payload, timestamp: Date.now() });
+  });
+
+  r.job("configProbe", { trigger: { manual: true } }, async (_payload, ctx) => {
+    const value = await ctx.config!("test:config:probe-key");
+    jobLog.push({ name: "test:job:config-probe", payload: { value }, timestamp: Date.now() });
+  });
 });
 
 beforeAll(async () => {
@@ -278,6 +312,75 @@ describe("scenario 3: manual trigger", () => {
   });
 });
 
+describe("scenario 3b: ctx.files resolves through the file provider", () => {
+  test("job handler can read back a file via ctx.files.ref(key)", async () => {
+    clearLog();
+    const provider = createInMemoryFileProvider();
+    await provider.write("probe/hello.txt", new TextEncoder().encode("hello from files probe"));
+
+    await withRunner(
+      async (runner) => {
+        await runner.dispatch("test:job:files-probe", { key: "probe/hello.txt" });
+        await waitFor(() => {
+          const entries = jobLog.filter((e) => e.name === "test:job:files-probe");
+          expect(entries.length).toBe(1);
+          expect(entries[0]?.payload["text"]).toBe("hello from files probe");
+        });
+      },
+      { context: { _fileProviderResolver: () => Promise.resolve(provider) } },
+    );
+  });
+});
+
+describe("scenario 3c: ctx.notify resolves through the notify factory (#1532)", () => {
+  test("job handler can call ctx.notify and the factory is bound to the job's system user + tenant", async () => {
+    clearLog();
+    const calls: Array<{ readonly notifierTenantId: string; readonly notificationType: string }> =
+      [];
+    const notifyFactory: NotifyFactory = (_user, tenantId) => async (notificationType) => {
+      calls.push({ notifierTenantId: tenantId, notificationType });
+    };
+
+    await withRunner(
+      async (runner) => {
+        await runner.dispatch("test:job:notify-probe", { toUserId: "u1" });
+        await waitFor(() => {
+          const entries = jobLog.filter((e) => e.name === "test:job:notify-probe");
+          expect(entries.length).toBe(1);
+        });
+        expect(calls).toHaveLength(1);
+        expect(calls[0]?.notificationType).toBe("test-notification");
+      },
+      { context: { _notifyFactory: notifyFactory } },
+    );
+  });
+});
+
+describe("scenario 3d: ctx.config resolves through the config accessor factory (#1532)", () => {
+  test("job handler can call ctx.config and the factory receives a tenant-scoped db", async () => {
+    clearLog();
+    let receivedDb: unknown;
+    const configAccessorFactory: ConfigAccessorFactory = (deps) => {
+      receivedDb = deps.db;
+      // Stub accessor: only the string-key overload is exercised here.
+      return (async () => "probe-value") as ConfigAccessor;
+    };
+
+    await withRunner(
+      async (runner) => {
+        await runner.dispatch("test:job:config-probe", {});
+        await waitFor(() => {
+          const entries = jobLog.filter((e) => e.name === "test:job:config-probe");
+          expect(entries.length).toBe(1);
+          expect(entries[0]?.payload["value"]).toBe("probe-value");
+        });
+        expect(receivedDb).toBeDefined();
+      },
+      { context: { _configAccessorFactory: configAccessorFactory, db: {} as AppContext["db"] } },
+    );
+  });
+});
+
 // --- Concurrency modes ---
 
 describe("concurrency: parallel", () => {
@@ -464,6 +567,7 @@ 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.
+    const queueNamePrefix = `kumiko-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     await withRunner(
       async (runner) => {
         const id1 = await runner.dispatch("test:job:replace-job", { n: 1 });
@@ -474,8 +578,21 @@ describe("concurrency: replace", () => {
         expect(id3).toBeDefined();
         expect(id1).not.toBe("skipped");
         expect(id3).not.toBe(id1);
+
+        const queue = new Queue(`${queueNamePrefix}-worker`, {
+          connection: { host: testRedis.redis.options.host, port: testRedis.redis.options.port },
+        });
+        try {
+          const waiting = (await queue.getWaiting()).filter(
+            (job) => job.name === "test:job:replace-job",
+          );
+          expect(waiting).toHaveLength(1);
+          expect(waiting[0]?.data.n).toBe(3);
+        } finally {
+          await queue.close();
+        }
       },
-      { consumerLane: undefined },
+      { consumerLane: undefined, queueNamePrefix },
     );
   });
 });
@@ -553,6 +670,36 @@ describe("job logger", () => {
       });
     });
   });
+
+  // Inspects the actual createJobLogger output instead of only asserting the
+  // handler ran — a child() that drops its context or a warn() mapped to
+  // debug would previously stay green.
+  test("info/warn/error land with the right level; debug is dropped; child merges its context", async () => {
+    clearLog();
+    let capturedLogs: JobLogEntry[] = [];
+    await withRunner(
+      async (runner) => {
+        await runner.dispatch("test:job:log-probe", { n: 1 });
+        await waitFor(() => {
+          expect(capturedLogs.length).toBeGreaterThan(0);
+        });
+      },
+      {
+        onJobComplete: (jobName, _id, _duration, logs) => {
+          if (jobName === "test:job:log-probe") capturedLogs = logs;
+        },
+      },
+    );
+
+    // debug() is a no-op by design (JobLogEntry.level has no "debug" slot) —
+    // info/warn/error from the handler body, plus one from child().info(...).
+    expect(capturedLogs).toHaveLength(4);
+    expect(capturedLogs.map((l) => l.level)).toEqual(["info", "warn", "error", "info"]);
+    expect(capturedLogs[0]?.message).toContain("log-probe-info");
+    expect(capturedLogs[3]?.message).toContain("log-probe-child");
+    expect(capturedLogs[3]?.message).toContain("probe");
+    expect(capturedLogs[3]?.message).toContain("true");
+  });
 });
 
 describe("correlation propagation", () => {
@@ -671,7 +818,8 @@ describe("error handling", () => {
 
   test("perTenant with getActiveTenantIds fans out one run per tenant", async () => {
     clearLog();
-    const tenants = [101, 102];
+    // @cast-boundary test fixture: TenantId is a branded string.
+    const tenants = ["per-tenant-fanout-a", "per-tenant-fanout-b"] as TenantId[];
     await withRunner(
       async (runner) => {
         await runner.dispatch("test:job:per-tenant-fanout", { n: 7 });
@@ -693,11 +841,23 @@ describe("handleEvent maxPerTenant", () => {
       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 waitFor(() => {
+        const started = jobLog.filter((e) => e.name === "test:job:per-tenant-limited-event");
+        expect(started.length).toBe(2);
+      });
+      // Third must be skipped by the maxPerTenant guard. handleEvent's cap
+      // check runs synchronously before this call resolves, but a wrongly
+      // enqueued job still needs the worker to pick it up and push its
+      // jobLog entry — polling several times (failing at the first sign of
+      // a 3rd start) is more CI-load-tolerant than a single fixed sleep(200)
+      // racing against the handler's own 500ms sleep, which could land
+      // outside the window on a starved runner and silently pass.
       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);
+      for (const delayMs of [50, 100, 200, 400]) {
+        await sleep(delayMs);
+        const startedNow = jobLog.filter((e) => e.name === "test:job:per-tenant-limited-event");
+        expect(startedNow.length).toBe(2);
+      }
     });
   });
 });

package/src/jobs/job-runner.ts

@@ -1,7 +1,8 @@
 import { type Job, Queue, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context";
-import type { DbRow } from "../db/connection";
+import type { DbConnection, DbRow } from "../db/connection";
+import { createTenantDb } from "../db/tenant-db";
 import { createSystemUser } from "../engine/system-user";
 import {
   type AppContext,
@@ -9,7 +10,9 @@ import {
   type Registry,
   type SessionUser,
   SYSTEM_TENANT_ID,
+  type TenantId,
 } from "../engine/types";
+import { createFileContext } from "../files/file-handle";
 import type { Logger } from "../logging/types";
 import {
   emitJobQueueDepth,
@@ -37,9 +40,10 @@ export type JobLogEntry = {
   timestamp: Temporal.Instant;
 };
 
-function createJobLogger(logs: JobLogEntry[]): Logger {
+function createJobLogger(logs: JobLogEntry[], baseContext: Record<string, unknown> = {}): Logger {
   function push(level: "info" | "warn" | "error", msg: string, data?: Record<string, unknown>) {
-    const message = data ? `${msg} ${JSON.stringify(data)}` : msg;
+    const merged = { ...baseContext, ...data };
+    const message = Object.keys(merged).length > 0 ? `${msg} ${JSON.stringify(merged)}` : msg;
     logs.push({ level, message, timestamp: Temporal.Now.instant() });
   }
   const logger: Logger = {
@@ -52,9 +56,13 @@ function createJobLogger(logs: JobLogEntry[]): Logger {
     error(msg, data) {
       push("error", msg, data);
     },
+    // No-op by design, not missing coverage: JobLogEntry.level (and the
+    // persisted run-completed/-failed event schema in bundled-features/
+    // jobs/events.ts) only has info|warn|error — a job's debug() calls have
+    // nowhere durable to land.
     debug() {},
-    child() {
-      return logger;
+    child(context) {
+      return createJobLogger(logs, { ...baseContext, ...context });
     },
   };
   return logger;
@@ -100,7 +108,7 @@ export type JobRunnerOptions = {
   // Tests set a unique prefix (e.g. `"test-${Date.now()}"`) for isolation —
   // two parallel test-runners never see each other's jobs.
   queueNamePrefix?: string | undefined;
-  getActiveTenantIds?: () => Promise<number[]>;
+  getActiveTenantIds?: () => Promise<TenantId[]>;
   onJobStart?: (jobName: string, jobId: string, meta: JobMeta) => void;
   onJobComplete?: (jobName: string, jobId: string, duration: number, logs: JobLogEntry[]) => void;
   onJobFailed?: (jobName: string, jobId: string, error: string, logs: JobLogEntry[]) => void;
@@ -331,13 +339,35 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       SYSTEM_TENANT_ID;
     const triggeredById = (rawData["_triggeredById"] as string | undefined) ?? null; // @cast-boundary dynamic-key
 
-    // _triggerName aus rawData übernehmen falls gesetzt — handleEvent
-    // packt das beim Multi-Trigger-Dispatch rein (siehe unten). Über
-    // jobContext.triggerName freigegeben damit der Handler nicht selbst
-    // im rohen Payload kramen muss.
+    // Carry `_triggerName` from rawData when set — handleEvent injects it on
+    // multi-trigger dispatch; exposed as jobContext.triggerName so handlers
+    // don't dig through the raw payload themselves.
     const triggerName = rawData["_triggerName"] as string | undefined; // @cast-boundary dynamic-key
+    // Mirror dispatch-shared.ts buildHandlerContext: ctx.files must resolve
+    // through the same _fileProviderResolver for jobs as for write-handlers,
+    // otherwise event-triggered jobs silently get an unresolved ctx.files.
+    const fileResolver = context._fileProviderResolver;
+    const files = fileResolver ? createFileContext(() => fileResolver(tenantId)) : context.files;
+    const jobSystemUser = createSystemUser(tenantId);
+    // Same buildHandlerContext parity as ctx.files above: ctx.notify/ctx.config
+    // must resolve for jobs the same way they do for write-handlers, or an
+    // app-author job calling ctx.notify(...)/ctx.config(...) hits a TypeError
+    // at runtime the write-handler path never would (framework#1532).
+    const notify = context._notifyFactory?.(jobSystemUser, tenantId);
+    const configDb = context.db as DbConnection | undefined; // @cast-boundary db-operator
+    const config =
+      context._configAccessorFactory && configDb
+        ? context._configAccessorFactory({
+            user: { id: jobSystemUser.id, tenantId },
+            db: createTenantDb(configDb, tenantId, "system"),
+            secrets: context.secrets,
+          })
+        : undefined;
     const jobContext: AppContext = {
       ...context,
+      files,
+      ...(notify !== undefined && { notify }),
+      ...(config !== undefined && { config }),
       // The runner owns the registry it resolved this job from — expose it so
       // workers can reach projections/jobs without the app author duplicating
       // it into `context` (the JobContext contract guarantees `registry`).
@@ -345,7 +375,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       // Expose the runner so handlers can chain a follow-up job. Symmetric with
       // how the command-dispatcher hands write-handlers their jobRunner.
       ...(selfRunner !== undefined && { jobRunner: selfRunner }),
-      systemUser: createSystemUser(tenantId),
+      systemUser: jobSystemUser,
       triggeredBy: triggeredById !== null ? { id: triggeredById, tenantId } : null,
       log: createJobLogger(logs),
       ...(triggerName !== undefined && { triggerName }),

package/src/logging/types.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/logger";
+export type * from "@cosmicdrift/kumiko-types/logger";

package/src/observability/index.ts

@@ -50,6 +50,7 @@ export {
   emitDispatcherHandler,
   emitEventConsumerLag,
   emitEventConsumerPassOutcome,
+  emitEventConsumerRearmExhausted,
   emitEventDispatcherListenConnected,
   emitHttpRequest,
   emitJobQueueDepth,

package/src/observability/standard-metrics.ts

@@ -23,7 +23,7 @@ export const STANDARD_METRIC_DEFS: readonly MetricDefinition[] = [
     name: "kumiko_dispatcher_handler_duration_seconds",
     type: "histogram",
     description: "Dispatcher handler latency in seconds.",
-    labels: ["handler", "success"],
+    labels: ["handler", "success", "outcome"],
     buckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5],
   },
   {
@@ -83,6 +83,20 @@ export const STANDARD_METRIC_DEFS: readonly MetricDefinition[] = [
       "Event deliveries that threw. Repeated failures on the same event lead to dead-letter.",
     labels: ["consumer", "instance_id"],
   },
+  // Fires once per (consumer, instance) transition into "stuck dead" —
+  // the rearm-cooldown/rearm-budget in event-dispatcher-delivery.ts gave up
+  // and the consumer now needs an operator (restartConsumer()) to recover.
+  // Without this, "dead + auto-rearm exhausted" is only visible via a
+  // getConsumerState poll — ops has no push signal that a consumer crossed
+  // from "will self-heal" to "needs a human". Deliberately a counter, not a
+  // gauge: emitted once per transition (event-dispatcher.ts tracks which
+  // consumers already fired this), not once per still-dead poll pass.
+  {
+    name: "kumiko_event_consumer_rearm_exhausted_total",
+    type: "counter",
+    description: "Consumer transitioned to dead with its auto-rearm budget exhausted.",
+    labels: ["consumer", "instance_id"],
+  },
   // LISTEN-subscription health. 1 = active, 0 = dropped. Drops to 0 while
   // the dispatcher is running signal that delivery latency has regressed
   // from sub-millisecond (LISTEN) to pollIntervalMs (timer fallback); ops
@@ -141,12 +155,18 @@ export function emitHttpRequest(
 
 export function emitDispatcherHandler(
   meter: Meter,
-  labels: { readonly handler: string; readonly success: boolean },
+  labels: {
+    readonly handler: string;
+    readonly success: boolean;
+    /** completed = drained normally; aborted = consumer walked away (SSE). */
+    readonly outcome?: "completed" | "aborted";
+  },
   durationSeconds: number,
 ): void {
   meter.histogram("kumiko_dispatcher_handler_duration_seconds").observe(durationSeconds, {
     handler: labels.handler,
     success: String(labels.success),
+    outcome: labels.outcome ?? "completed",
   });
 }
 
@@ -203,6 +223,19 @@ export function emitEventConsumerLag(
   });
 }
 
+// Caller (event-dispatcher.ts) is responsible for calling this exactly
+// once per (consumer, instanceId) transition into exhausted-dead — not
+// once per poll pass while it stays dead.
+export function emitEventConsumerRearmExhausted(
+  meter: Meter,
+  labels: { readonly consumer: string; readonly instanceId: string },
+): void {
+  meter.counter("kumiko_event_consumer_rearm_exhausted_total").inc(1, {
+    consumer: labels.consumer,
+    instance_id: labels.instanceId,
+  });
+}
+
 export function emitEventDispatcherListenConnected(meter: Meter, connected: boolean): void {
   meter.gauge("kumiko_event_dispatcher_listen_connected").set(connected ? 1 : 0);
 }

package/src/observability/types/index.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/observability";
+export type * from "@cosmicdrift/kumiko-types/observability";

package/src/observability/types/metric.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/observability/metric";
+export type * from "@cosmicdrift/kumiko-types/observability/metric";

package/src/observability/types/provider.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/observability/provider";
+export type * from "@cosmicdrift/kumiko-types/observability/provider";

package/src/observability/types/span.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/observability/span";
+export type * from "@cosmicdrift/kumiko-types/observability/span";

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

@@ -4,6 +4,7 @@ import { createEntity, createRegistry, createTextField, defineFeature } from "..
 import type { TenantId } from "../../engine/types/identifiers";
 import { createSecret } from "../../secrets/types";
 import { createTestUser } from "../../stack";
+import { createRecordingProvider } from "../../testing";
 import { createDispatcher } from "../dispatcher";
 
 const streamCleanupState = { closed: false };
@@ -324,6 +325,156 @@ describe("dispatcher.stream", () => {
 
     expect(streamCleanupState.closed).toBe(true);
   });
+
+  test("activates the dispatcher span in observabilityContext for every pull, not just the first", async () => {
+    // Regression for #1516: runStreamInstrumented used to start the span but
+    // never run the stream inside observabilityContext.run(...), so a
+    // handler-side startSpan() picked up whatever ALS context happened to be
+    // active at that pull (or none) instead of the stream's dispatcher span.
+    const provider = createRecordingProvider();
+    const nestedFeature = defineFeature("nested", (r) => {
+      r.streamHandler(
+        "tail",
+        z.object({ count: z.number().int().min(0) }),
+        async function* (query, handlerCtx) {
+          for (let i = 0; i < query.payload.count; i++) {
+            const child = handlerCtx.tracer.startSpan("nested.child");
+            child.end();
+            yield { i };
+          }
+        },
+        { access: { openToAll: true } },
+      );
+    });
+    const dispatcher = createDispatcher(createRegistry([nestedFeature]), {
+      tracer: provider.tracer,
+      meter: provider.meter,
+    });
+
+    await collect(dispatcher.stream("nested:stream:tail", { count: 3 }, createTestUser()));
+
+    const dispatcherSpan = provider.spansByName("kumiko.dispatcher.handler")[0]!;
+    const childSpans = provider.spansByName("nested.child");
+    expect(childSpans).toHaveLength(3);
+    for (const child of childSpans) {
+      expect(child.parentSpanId).toBe(dispatcherSpan.spanId);
+    }
+  });
+
+  test("a close-time error on an otherwise-clean stream is reported, not swallowed", async () => {
+    // Regression for #1543: runStreamInstrumented's finally used to
+    // catch+discard any error from generator.return() unconditionally, even
+    // when nothing else had failed — an abandoned stream whose handler's
+    // own cleanup throws (closing a cursor/unsubscribing) was invisible to
+    // both the error-counter and the span status.
+    const provider = createRecordingProvider();
+    const closeFailFeature = defineFeature("closefail", (r) => {
+      r.streamHandler(
+        "tail",
+        z.object({}),
+        async function* () {
+          try {
+            yield { i: 0 };
+            yield { i: 1 };
+          } finally {
+            // biome-ignore lint/correctness/noUnsafeFinally: deliberately simulating a handler whose close-time cleanup fails
+            throw new Error("close-boom");
+          }
+        },
+        { access: { openToAll: true } },
+      );
+    });
+    const dispatcher = createDispatcher(createRegistry([closeFailFeature]), {
+      tracer: provider.tracer,
+      meter: provider.meter,
+    });
+
+    const gen = dispatcher.stream("closefail:stream:tail", {}, createTestUser());
+    for await (const _chunk of gen) {
+      break;
+    }
+
+    const errorCounters = provider.metricEvents.filter(
+      (e) => e.type === "counter.inc" && e.name === "kumiko_dispatcher_handler_errors_total",
+    );
+    expect(errorCounters).toHaveLength(1);
+    const dispatcherSpan = provider.spansByName("kumiko.dispatcher.handler")[0]!;
+    expect(dispatcherSpan.status).toBe("error");
+  });
+
+  test("draining a stream to completion emits outcome:completed", async () => {
+    // completedNormally=true only when the inner generator finishes on its
+    // own — pins the success-path label so a refactor that drops the flag
+    // cannot silently reclassify clean streams as aborted (#1551).
+    const provider = createRecordingProvider();
+    const feature = defineFeature("complete", (r) => {
+      r.streamHandler(
+        "tail",
+        z.object({}),
+        async function* () {
+          yield { i: 0 };
+          yield { i: 1 };
+        },
+        { access: { openToAll: true } },
+      );
+    });
+    const dispatcher = createDispatcher(createRegistry([feature]), {
+      tracer: provider.tracer,
+      meter: provider.meter,
+    });
+
+    await collect(dispatcher.stream("complete:stream:tail", {}, createTestUser()));
+
+    const duration = provider.metricEvents.find(
+      (e) =>
+        e.type === "histogram.observe" && e.name === "kumiko_dispatcher_handler_duration_seconds",
+    );
+    expect(duration).toBeDefined();
+    expect(duration?.labels).toMatchObject({
+      handler: "complete:stream:tail",
+      success: "true",
+      outcome: "completed",
+    });
+  });
+
+  test("generator.return() mid-stream emits outcome:aborted, not completed", async () => {
+    // Consumer walk-away (SSE tab-close) must not count as a clean
+    // completion — completedNormally stays false when return() interrupts
+    // the loop (#1551).
+    const provider = createRecordingProvider();
+    const feature = defineFeature("abort", (r) => {
+      r.streamHandler(
+        "tail",
+        z.object({}),
+        async function* () {
+          yield { i: 0 };
+          yield { i: 1 };
+          yield { i: 2 };
+        },
+        { access: { openToAll: true } },
+      );
+    });
+    const dispatcher = createDispatcher(createRegistry([feature]), {
+      tracer: provider.tracer,
+      meter: provider.meter,
+    });
+
+    const gen = dispatcher.stream("abort:stream:tail", {}, createTestUser());
+    const first = await gen.next();
+    expect(first.value).toEqual({ i: 0 });
+    await gen.return(undefined);
+
+    const duration = provider.metricEvents.find(
+      (e) =>
+        e.type === "histogram.observe" && e.name === "kumiko_dispatcher_handler_duration_seconds",
+    );
+    expect(duration).toBeDefined();
+    expect(duration?.labels).toMatchObject({
+      handler: "abort:stream:tail",
+      success: "true",
+      outcome: "aborted",
+    });
+  });
 });
 
 // --- postQuery hooks on standalone (entity-less) queries ---

package/src/pipeline/__tests__/event-consumer-state.integration.test.ts

@@ -0,0 +1,31 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createTestDb, type TestDb } from "../../stack";
+import { createEventConsumerStateTable } from "../event-consumer-state";
+
+// #1362: two dispatcher instances booting concurrently against the same DB
+// both see kumiko_event_consumers already present but rearm_count missing,
+// and both ALTER TABLE. Without IF NOT EXISTS the loser crashes on boot
+// with "column already exists" — a real TOCTOU since this table is
+// explicitly multi-instance.
+describe("createEventConsumerStateTable — concurrent boot", () => {
+  let testDb: TestDb;
+
+  beforeAll(async () => {
+    testDb = await createTestDb();
+  });
+
+  afterAll(async () => {
+    await testDb.cleanup();
+  });
+
+  test("running it twice concurrently does not throw", async () => {
+    await createEventConsumerStateTable(testDb.db);
+
+    await expect(
+      Promise.all([
+        createEventConsumerStateTable(testDb.db),
+        createEventConsumerStateTable(testDb.db),
+      ]),
+    ).resolves.toBeDefined();
+  });
+});