@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

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

@@ -1,10 +1,26 @@
 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 { createTestRedis, type TestRedis } from "../../stack";
+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 JobRunner } from "../job-runner";
+import {
+  createJobRunner,
+  type JobLogEntry,
+  type JobMeta,
+  type JobRunner,
+  type JobRunnerOptions,
+} from "../job-runner";
 
 // --- Shared state ---
 
@@ -98,12 +114,42 @@ 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 () => {
     throw new Error("intentional failure");
   });
 
+  // perTenant fan-out — used to assert missing getActiveTenantIds fails
+  // the wrapper job without killing the worker.
+  r.job("perTenantFanout", { trigger: { manual: true }, perTenant: true }, async (payload) => {
+    jobLog.push({ name: "test:job:per-tenant-fanout", payload, timestamp: Date.now() });
+  });
+
   // Correlation propagation probe — records the requestContext it sees at
   // handler-time so tests can assert the scheduling request's correlationId
   // made it through BullMQ into the worker process.
@@ -119,6 +165,42 @@ 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() });
+  });
+  // 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 () => {
@@ -133,6 +215,7 @@ afterAll(async () => {
 // Helper to create a runner, run tests, then stop
 async function withRunner(
   fn: (runner: JobRunner, registry: Registry) => Promise<void>,
+  opts?: Partial<JobRunnerOptions>,
 ): Promise<void> {
   const registry = createRegistry([testFeature]);
   const context: AppContext = {};
@@ -145,6 +228,7 @@ async function withRunner(
     redisUrl,
     consumerLane: "worker",
     queueNamePrefix,
+    ...opts,
   });
 
   try {
@@ -228,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", () => {
@@ -410,6 +563,40 @@ 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.
+    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 });
+        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);
+
+        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, queueNamePrefix },
+    );
+  });
+});
+
 describe("concurrency: maxPerTenant", () => {
   test("max=2: third dispatch for same tenant returns skipped, other tenant unaffected", async () => {
     clearLog();
@@ -473,6 +660,48 @@ 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);
+      });
+    });
+  });
+
+  // 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", () => {
   test("dispatch inside requestContext.run passes correlationId into the job", async () => {
     clearLog();
@@ -534,6 +763,103 @@ describe("error handling", () => {
       });
     });
   });
+
+  test("onJobFailed receives the handler error on each attempt", async () => {
+    clearLog();
+    const failures: Array<{ jobName: string; error: string }> = [];
+    const starts: JobMeta[] = [];
+    await withRunner(
+      async (runner) => {
+        await runner.dispatch("test:job:failing-job");
+        // retries: 1 → attempts = 2 (initial + one retry)
+        await waitFor(() => {
+          expect(failures.length).toBeGreaterThanOrEqual(2);
+        });
+        expect(failures.every((f) => f.jobName === "test:job:failing-job")).toBe(true);
+        expect(failures.every((f) => f.error === "intentional failure")).toBe(true);
+        expect(starts.map((s) => s.attempt)).toEqual([1, 2]);
+
+        // Worker still alive after exhausted retries
+        await runner.dispatch("test:job:manual-report", { after: "retries" });
+        await waitFor(() => {
+          expect(
+            jobLog.some(
+              (e) => e.name === "test:job:manual-report" && e.payload["after"] === "retries",
+            ),
+          ).toBe(true);
+        });
+      },
+      {
+        onJobStart: (name, _id, meta) => {
+          if (name === "test:job:failing-job") starts.push(meta);
+        },
+        onJobFailed: (jobName, _id, error) => {
+          if (jobName === "test:job:failing-job") failures.push({ jobName, error });
+        },
+      },
+    );
+  });
+
+  test("perTenant without getActiveTenantIds fails wrapper; worker stays alive", async () => {
+    clearLog();
+    await withRunner(async (runner) => {
+      await runner.dispatch("test:job:per-tenant-fanout", { n: 1 });
+      // Wrapper throws before fan-out (and before onJobFailed) — settle, then
+      // prove the worker still consumes.
+      await sleep(300);
+      expect(jobLog.filter((e) => e.name === "test:job:per-tenant-fanout")).toHaveLength(0);
+
+      await runner.dispatch("test:job:manual-report", { after: "perTenant-miss" });
+      await waitFor(() => {
+        expect(jobLog.some((e) => e.name === "test:job:manual-report")).toBe(true);
+      });
+    });
+  });
+
+  test("perTenant with getActiveTenantIds fans out one run per tenant", async () => {
+    clearLog();
+    // @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 });
+        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);
+      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);
+      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);
+      }
+    });
+  });
 });
 
 // --- Registry ---

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,9 +10,17 @@ 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 { getFallbackTracer, type SerializedTraceContext, type Tracer } from "../observability";
+import {
+  emitJobQueueDepth,
+  getFallbackTracer,
+  type Meter,
+  type SerializedTraceContext,
+  type Tracer,
+} from "../observability";
 import { createDistributedLock, type DistributedLock } from "../pipeline/distributed-lock";
 import { RedisKeys } from "../pipeline/redis-keys";
 
@@ -31,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 = {
@@ -46,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;
@@ -94,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;
@@ -119,6 +133,29 @@ function captureTraceContext(tracer: Tracer): SerializedTraceContext | undefined
   return { traceId: span.traceId, spanId: span.spanId };
 }
 
+const QUEUE_DEPTH_POLL_INTERVAL_MS = 15_000;
+
+// kumiko_job_queue_depth: only the lane's own consumer polls — the count is
+// a global Redis-backed value (BullMQ, not per-process), so one reporter per
+// lane is enough. Fires once immediately (metrics exist before the first
+// poll tick) then on an interval; the caller stores + clears the handle.
+async function startQueueDepthPolling(
+  queue: Queue,
+  lane: JobRunIn,
+  meter: Meter,
+): Promise<ReturnType<typeof setInterval>> {
+  const pollQueueDepth = async (): Promise<void> => {
+    try {
+      const counts = await queue.getJobCounts("waiting", "active", "delayed", "failed", "paused");
+      emitJobQueueDepth(meter, lane, counts);
+    } catch {
+      // skip: transient Redis hiccup — next poll retries
+    }
+  };
+  await pollQueueDepth();
+  return setInterval(() => void pollQueueDepth(), QUEUE_DEPTH_POLL_INTERVAL_MS);
+}
+
 function parseRedisOpts(url: string): { host: string; port: number; db?: number | undefined } {
   const parsed = new URL(url);
   const result: { host: string; port: number; db?: number | undefined } = {
@@ -181,6 +218,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     worker: new Queue(queueNameFor(queueNamePrefix, "worker"), { connection: redisOpts }),
   };
   let worker: Worker | null = null;
+  let queueDepthTimer: ReturnType<typeof setInterval> | null = null;
   // Forward reference to the runner's own API, exposed on the job-handler ctx
   // so a handler can dispatch a follow-up job (job→job chaining, e.g.
   // delivery.render → delivery.send). Assigned just before return; reads happen
@@ -301,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`).
@@ -315,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 }),
@@ -431,9 +491,19 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
           await consumerQueue.add(bootName, {}, { jobId: `boot-${name.replace(/\./g, "-")}` });
         }
       }
+
+      // Skipped when no meter is wired (context.meter is optional, e.g. in
+      // tests without an observability provider).
+      if (context.meter) {
+        queueDepthTimer = await startQueueDepthPolling(consumerQueue, consumerLane, context.meter);
+      }
     },
 
     async stop(): Promise<void> {
+      if (queueDepthTimer) {
+        clearInterval(queueDepthTimer);
+        queueDepthTimer = null;
+      }
       if (worker) {
         await worker.close();
         worker = null;

package/src/logging/types.ts

@@ -1,7 +1 @@
-export type Logger = {
-  info(msg: string, data?: Record<string, unknown>): void;
-  warn(msg: string, data?: Record<string, unknown>): void;
-  error(msg: string, data?: Record<string, unknown>): void;
-  debug(msg: string, data?: Record<string, unknown>): void;
-  child(context: Record<string, unknown>): Logger;
-};
+export type * from "@cosmicdrift/kumiko-types/logger";

package/src/migrations/pending-rebuilds.ts

@@ -200,7 +200,7 @@ export type EnqueueProjectionRebuildDeps = {
   readonly db: DbConnection;
   readonly registry: Registry;
   // Present + projection-rebuild job registered (jobs composed) → tracked,
-  // retryable job (read_job_runs + read_job_run_logs). Absent → inline rebuild.
+  // retryable job (read_job_runs + store_job_run_logs). Absent → inline rebuild.
   readonly jobRunner?: JobRunner;
 };
 

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

@@ -1,5 +1,6 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "bun:test";
 import { z } from "zod";
+import type { TableColumns } from "../../db/dialect";
 import { buildEntityTable } from "../../db/table-builder";
 import { createRegistry, defineFeature } from "../../engine";
 import type { AppContext, SaveContext } from "../../engine/types";
@@ -65,7 +66,9 @@ const todoEntity = {
 
 let postSaveInvocations = 0;
 const todoFeature = defineFeature("todo", (r) => {
-  const todoTable = buildEntityTable("todo", todoEntity);
+  // Brand (#742) is compile-time-only; the unbranded TableColumns view keeps the
+  // method-form insert (and its observability span) working — runtime shape is identical.
+  const todoTable: TableColumns = buildEntityTable("todo", todoEntity);
   r.entity("todo", todoEntity);
 
   r.writeHandler(

package/src/observability/__tests__/recording-tracer.test.ts

@@ -87,11 +87,13 @@ describe("RecordingTracer", () => {
     expect(recorded).toHaveLength(1);
   });
 
-  it("startSpanFromContext continues an upstream trace", () => {
+  it("startSpan with parent context continues an upstream trace", () => {
     const { tracer, recorded } = makeTracer();
-    const span = tracer.startSpanFromContext("child", {
-      traceId: "aabbccddeeff00112233445566778899",
-      spanId: "1122334455667788",
+    const span = tracer.startSpan("child", {
+      parent: {
+        traceId: "aabbccddeeff00112233445566778899",
+        spanId: "1122334455667788",
+      },
     });
     span.end();
     expect(recorded[0]?.traceId).toBe("aabbccddeeff00112233445566778899");

package/src/observability/index.ts

@@ -50,8 +50,10 @@ export {
   emitDispatcherHandler,
   emitEventConsumerLag,
   emitEventConsumerPassOutcome,
+  emitEventConsumerRearmExhausted,
   emitEventDispatcherListenConnected,
   emitHttpRequest,
+  emitJobQueueDepth,
   registerStandardMetrics,
   STANDARD_METRIC_DEFS,
 } from "./standard-metrics";

package/src/observability/noop-provider.ts

@@ -5,7 +5,6 @@ import type {
   Meter,
   MetricDefinition,
   ObservabilityProvider,
-  SerializedTraceContext,
   Span,
   SpanStatus,
   StartSpanOptions,
@@ -68,14 +67,6 @@ class NoopTracer implements Tracer {
   getActiveSpan(): Span | undefined {
     return undefined;
   }
-
-  startSpanFromContext(
-    name: string,
-    _context: SerializedTraceContext,
-    _options?: StartSpanOptions,
-  ): Span {
-    return new NoopSpan(name, undefined);
-  }
 }
 
 class NoopCounter implements Counter {

package/src/observability/recording-tracer.ts

@@ -175,18 +175,6 @@ export class RecordingTracer implements Tracer {
   getActiveSpan(): Span | undefined {
     return observabilityContext.getActiveSpan();
   }
-
-  /**
-   * @deprecated Prefer `startSpan(name, { parent: context })`. Retained as a
-   *   thin alias for call-sites that pre-date the unified StartSpanOptions.
-   */
-  startSpanFromContext(
-    name: string,
-    context: SerializedTraceContext,
-    options?: StartSpanOptions,
-  ): Span {
-    return this.startSpan(name, { ...options, parent: context });
-  }
 }
 
 // Helper to serialize an active Span into the cross-process format.