@cosmicdrift/kumiko-framework 0.158.2 → 0.160.0

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

@@ -0,0 +1,43 @@
+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",
+];
+
+const ALLOWED_FILES = new Set([
+  "packages/framework/src/event-store/event-store.ts",
+  "packages/framework/src/event-store/index.ts",
+  "packages/bundled-features/src/tenant/seeding.ts",
+  "packages/bundled-features/src/tier-engine/feature.ts",
+  "packages/bundled-features/src/auth-email-password/__tests__/email-verification.integration.test.ts",
+  "packages/bundled-features/src/auth-email-password/__tests__/password-reset.integration.test.ts",
+  "packages/framework/src/event-store/__tests__/unscoped-stream-primitives.guard.test.ts",
+]);
+
+const REPO_ROOT = `${import.meta.dir}/../../../../..`;
+
+describe("unscoped stream primitives — caller allowlist", () => {
+  test("only seed/system-internal paths reference the existence-oracle primitives", async () => {
+    const glob = new Glob("packages/{framework,bundled-features}/src/**/*.ts");
+    const matches = new Set<string>();
+    for await (const relPath of glob.scan({ cwd: REPO_ROOT })) {
+      const content = await Bun.file(`${REPO_ROOT}/${relPath}`).text();
+      if (RESTRICTED_SYMBOLS.some((symbol) => content.includes(symbol))) {
+        matches.add(relPath);
+      }
+    }
+
+    // Positive control — proves the scan actually ran and found the known
+    // caller, not just that it (silently) found nothing.
+    expect(matches.has("packages/bundled-features/src/tenant/seeding.ts")).toBe(true);
+
+    const offenders = [...matches].filter((relPath) => !ALLOWED_FILES.has(relPath));
+    expect(offenders).toEqual([]);
+  });
+});

package/src/event-store/errors.ts

@@ -1,35 +1,2 @@
-// Failure modes of the event-store's append() path. Surfaced as typed
-// errors so the executor layer can map them to the framework's
-// WriteResult error contract (version_conflict).
-
-export class VersionConflictError extends Error {
-  public readonly aggregateId: string;
-  public readonly expectedVersion: number;
-  constructor(aggregateId: string, expectedVersion: number) {
-    super(
-      `Version conflict on aggregate ${aggregateId}: expected predecessor version ${expectedVersion}`,
-    );
-    this.name = "VersionConflictError";
-    this.aggregateId = aggregateId;
-    this.expectedVersion = expectedVersion;
-  }
-}
-
-// Thrown when ctx.appendEvent targets an archived stream. Archived aggregates
-// are read-only — restoreStream() makes them writable again. The archive
-// state is not carried on the events themselves; it lives on the sparse
-// kumiko_archived_streams table. Handlers that need to branch on archive
-// state should call ctx.isStreamArchived(id) first.
-export class ArchivedStreamError extends Error {
-  public readonly tenantId: string;
-  public readonly aggregateId: string;
-  constructor(tenantId: string, aggregateId: string) {
-    super(
-      `Aggregate ${aggregateId} on tenant ${tenantId} is archived — appendEvent is blocked. ` +
-        `Call restoreStream() to re-open the stream before writing.`,
-    );
-    this.name = "ArchivedStreamError";
-    this.tenantId = tenantId;
-    this.aggregateId = aggregateId;
-  }
-}
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/event-store-errors";

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

@@ -1,3 +1,4 @@
+import type { EventMetadata, StoredEvent } from "@cosmicdrift/kumiko-types/event-store-types";
 import { encryptEventPayloadPii } from "../crypto/event-pii";
 import type { DbRunner } from "../db";
 import { isUniqueViolation } from "../db/pg-error";
@@ -16,28 +17,7 @@ import { VersionConflictError } from "./errors";
 import { eventsTable } from "./events-schema";
 import { toStoredEvent } from "./row-to-stored-event";
 
-export type EventMetadata = {
-  readonly userId: string;
-  readonly requestId?: string;
-  // End-to-end business-operation id. Root HTTP requests get it from the
-  // x-correlation-id header (default: requestId). MSP-applies inherit it
-  // from the triggering event. Lets you trace "which user click caused
-  // this email 3 streams later?".
-  readonly correlationId?: string;
-  // Stored event id that triggered this write. Null for root commands;
-  // set to event.id when an MSP-apply runs ctx.appendEvent. Together with
-  // correlationId forms a causation DAG across aggregate streams.
-  readonly causationId?: string;
-  // Marten-conform free key/value space for app-specific metadata that
-  // doesn't deserve its own EventMetadata field. Examples: A/B-test bucket,
-  // feature-flag snapshot, geo-region, client SDK version. Persisted into
-  // events.metadata jsonb (no schema change — it's already a free-form
-  // jsonb column), survives upcasters untouched, available on every
-  // StoredEvent.metadata.headers. Framework does not interpret values; the
-  // app reads them when filtering/auditing. Keep values JSON-primitive
-  // (string|number|boolean) so JSON serialization stays bulletproof.
-  readonly headers?: Readonly<Record<string, string | number | boolean>>;
-};
+export type { EventMetadata, StoredEvent } from "@cosmicdrift/kumiko-types/event-store-types";
 
 export type EventToAppend = {
   readonly aggregateId: string;
@@ -51,25 +31,6 @@ export type EventToAppend = {
   readonly metadata: EventMetadata;
 };
 
-// Generic über payload-shape. Default = Record<string, unknown> macht
-// alle existierenden Konsumenten backwards-compatible. Konkrete Apply-
-// Handler / Tests können `StoredEvent<MyEventPayload>` annotieren um
-// payload typed zu lesen. Type-Propagation kommt durch r.defineEvent +
-// SingleStreamApplyFn<T> in apply-Maps.
-export type StoredEvent<TPayload = Record<string, unknown>> = {
-  readonly id: string;
-  readonly aggregateId: string;
-  readonly aggregateType: string;
-  readonly tenantId: TenantId;
-  readonly version: number;
-  readonly type: string;
-  readonly eventVersion: number;
-  readonly payload: TPayload;
-  readonly metadata: EventMetadata;
-  readonly createdAt: Temporal.Instant;
-  readonly createdBy: string;
-};
-
 type SelectedEvent = {
   readonly id: bigint;
   readonly aggregateId: string;
@@ -281,9 +242,13 @@ export async function getStreamVersion(
   return selectStreamMaxVersion(db, aggregateId, tenantId);
 }
 
-/** MAX(version) for one aggregate — no tenant filter. Used by seed idempotency. */
+/** MAX(version) for one aggregate — no tenant filter. SECURITY: existence-oracle,
+ *  a caller can probe whether an aggregateId has any events regardless of tenant
+ *  membership. Only call from seed/system-internal paths (idempotency checks
+ *  against a known aggregateId) — never from a handler reachable with
+ *  caller-controlled input. */
 // @wrapper-known semantic-alias
-export async function getAggregateStreamMaxVersion(
+export async function getUnscopedAggregateStreamMaxVersion(
   db: DbRunner,
   aggregateId: string,
 ): Promise<number> {
@@ -291,10 +256,11 @@ export async function getAggregateStreamMaxVersion(
 }
 
 /** Stream tenant of an aggregate (the tenant_id its events live under), with no
- *  membership/tenant filter. 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 getAggregateStreamTenant(
+ *  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,
@@ -333,15 +299,19 @@ export async function loadEventsAfterVersion(
 
 // Load every event for an aggregate_type across all tenants. Ordered by
 // (created_at, id) — chronological replay order for projection rebuilds.
-//
-// CAUTION — buffers ALL matching events in memory. Safe for smaller
-// aggregate-types (≤ 100k events), a memory cliff for large stores.
-// For >100k events use `streamAllEventsByType` (yields batchwise).
 // Mostly called from tests today — production rebuild goes through
 // projection-rebuild's own streaming path.
+//
+// Fails loud past LOAD_ALL_EVENTS_ROW_LIMIT rather than silently buffering
+// an unbounded result set — that's the memory cliff this guard exists to
+// 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. */
 export async function loadAllEventsByType(
   db: DbRunner,
   aggregateType: string,
+  rowLimit: number = LOAD_ALL_EVENTS_ROW_LIMIT,
 ): Promise<readonly StoredEvent[]> {
   const rows = await selectMany<SelectedEvent>(
     db,
@@ -352,8 +322,15 @@ export async function loadAllEventsByType(
         { col: "createdAt", direction: "asc" },
         { col: "id", direction: "asc" },
       ],
+      limit: rowLimit + 1,
     },
   );
+  if (rows.length > rowLimit) {
+    throw new Error(
+      `loadAllEventsByType("${aggregateType}") exceeds ${rowLimit} rows — ` +
+        "use streamAllEventsByType instead of buffering the full result set in memory.",
+    );
+  }
   return rows.map(toStoredEvent);
 }
 

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

@@ -15,6 +15,7 @@ import {
 import { unsafePushTables } from "../stack";
 import { createArchivedStreamsTable } from "./archive";
 import { createSnapshotsTable } from "./snapshot";
+import type { EventMetadata } from "./types";
 
 // Event-store schema as a Drizzle table. The typed select/insert path handles
 // most operations; append() for subsequent versions uses raw SQL because
@@ -24,16 +25,6 @@ import { createSnapshotsTable } from "./snapshot";
 // (Redis-backed check + cached-response replay). The event-store itself
 // imposes no idempotency index — a single HTTP request may write N events
 // freely, metadata.requestId is purely a trace marker.
-export type EventMetadata = {
-  readonly userId: string;
-  readonly requestId?: string;
-  readonly correlationId?: string;
-  readonly causationId?: string;
-  // App-specific free key/value (Marten "headers"). Mirror of the canonical
-  // type in event-store.ts — kept duplicate because events-schema must stay
-  // import-cycle-free vs the event-store module.
-  readonly headers?: Readonly<Record<string, string | number | boolean>>;
-};
 
 export const eventsTable = pgTable(
   "kumiko_events",

package/src/event-store/index.ts

@@ -18,10 +18,11 @@ export {
   EVENTS_PUBSUB_CHANNEL,
   type EventMetadata,
   type EventToAppend,
-  getAggregateStreamMaxVersion,
-  getAggregateStreamTenant,
   getEventsHighWaterMark,
   getStreamVersion,
+  getUnscopedAggregateStreamMaxVersion,
+  getUnscopedAggregateStreamTenant,
+  LOAD_ALL_EVENTS_ROW_LIMIT,
   loadAggregate,
   loadAggregateAsOf,
   loadAllEventsByType,

package/src/event-store/snapshot.ts

@@ -1,5 +1,10 @@
 // sql now comes from native dialect
 
+import type {
+  LoadAggregateWithSnapshotOptions,
+  LoadAggregateWithSnapshotResult,
+  SnapshotReducer,
+} from "@cosmicdrift/kumiko-types/snapshot-types";
 import type { DbConnection, DbRunner } from "../db/connection";
 import {
   index,
@@ -18,7 +23,7 @@ import { tableExists } from "../db/schema-inspection";
 import type { TenantId } from "../engine/types";
 import { unsafePushTables } from "../stack";
 import { isStreamArchived } from "./archive";
-import { loadEventsAfterVersion, type StoredEvent } from "./event-store";
+import { loadEventsAfterVersion } from "./event-store";
 
 // Marten-aligned snapshot store. A snapshot is a point-in-time materialised
 // state of an aggregate at a specific version, cached so rehydrating the
@@ -157,40 +162,11 @@ export async function loadLatestSnapshot<
   };
 }
 
-// Reducer used to fold events onto a state. Kept narrow and pure — the
-// caller supplies the shape and update rules. Mirrors the reducer shape
-// feature authors already write for r.projection.apply.
-export type SnapshotReducer<TState extends Record<string, unknown>> = (
-  state: TState,
-  event: StoredEvent,
-) => TState;
-
-export type LoadAggregateWithSnapshotResult<TState extends Record<string, unknown>> = {
-  readonly state: TState;
-  readonly version: number;
-  readonly snapshotHit: boolean;
-};
-
-export type LoadAggregateWithSnapshotOptions = {
-  // Opt-in: include archived streams in the rehydrate. Default false — same
-  // semantics as loadAggregate / loadAggregateAsOf. Archive check is a
-  // single indexed lookup, so the cost stays negligible on the hot path.
-  readonly includeArchived?: boolean;
-  // Optional upcaster step: every delta event goes through this transform
-  // BEFORE the reducer sees it. The dispatcher wires this up with
-  // r.eventMigration so feature code always sees current-version payloads.
-  // Async to support Marten-style AsyncOnlyEventUpcaster (DB lookups).
-  readonly upcastEvent?: (event: StoredEvent) => Promise<StoredEvent>;
-  // Auto-snapshot policy: when the fold applied at least this many delta
-  // events, persist a fresh snapshot at the folded version (best-effort —
-  // a failed save never fails the load). Omit to keep snapshotting manual.
-  readonly snapshotEvery?: number;
-  // Reducer-shape generation stamped onto saved snapshots (default 1). A
-  // stored snapshot with a different generation is ignored — full replay
-  // through the upcaster chain — and restamped on the next auto-save. Bump
-  // whenever the reducer's state shape changes.
-  readonly snapshotVersion?: number;
-};
+export type {
+  LoadAggregateWithSnapshotOptions,
+  LoadAggregateWithSnapshotResult,
+  SnapshotReducer,
+} from "@cosmicdrift/kumiko-types/snapshot-types";
 
 // Snapshot-aware rehydrate. Loads the latest snapshot (if any), applies
 // events strictly newer than snapshot.version, and returns the fold.

package/src/event-store/types.ts

@@ -0,0 +1,2 @@
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/event-store-types";

package/src/files/__tests__/in-memory-provider.contract.test.ts

@@ -0,0 +1,4 @@
+import { describeFileProviderContract } from "../../testing/file-provider-contract";
+import { createInMemoryFileProvider } from "../in-memory-provider";
+
+describeFileProviderContract("InMemoryFileProvider", () => createInMemoryFileProvider());

package/src/files/file-handle.ts

@@ -10,27 +10,10 @@
 // suffix before the file extension — `foo/bar.jpg` + `"medium"` →
 // `foo/bar.medium.jpg`. Stable, reversible, no extra lookup tables.
 
+import type { FileContext, FileHandle } from "@cosmicdrift/kumiko-types/file-handle-types";
 import type { FileStorageProvider } from "./types";
 
-export type FileHandle = {
-  readonly key: string;
-  read(): Promise<Uint8Array>;
-  write(data: Uint8Array, mimeType?: string): Promise<void>;
-  delete(): Promise<void>;
-  exists(): Promise<boolean>;
-  // Produce a handle for a derived key (e.g. a thumbnail). Does not touch
-  // storage; only computes the key. Writing to the derived handle is the
-  // caller's job.
-  derive(suffix: string): FileHandle;
-};
-
-// The `ctx.files` service — a factory that materialises a FileHandle for a
-// storage key. One per request/event, bound to a single tenant: the provider
-// is resolved per-tenant through file-foundation, so uploads, ctx.files and the
-// GDPR jobs all hit the same store by construction.
-export type FileContext = {
-  ref(key: string): FileHandle;
-};
+export type { FileContext, FileHandle };
 
 // `getProvider` is a lazily-resolved, memoized accessor — the provider is
 // resolved (config + s3.secretAccessKey secret read) only when a handle method

package/src/files/provider-resolver.ts

@@ -12,11 +12,12 @@
 // file-foundation re-exports `createFileProviderForTenant` + the plugin types
 // (moved here from there) so existing imports keep working.
 
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 import type { DbConnection } from "../db/connection";
 import type { TenantDb } from "../db/tenant-db";
 import { EXT_FILE_PROVIDER, FILE_PROVIDER_CONFIG_KEY } from "../engine/extension-names";
 import { SYSTEM_USER_ID } from "../engine/system-user";
-import type { ConfigAccessor, ConfigAccessorFactory, Registry, TenantId } from "../engine/types";
+import type { ConfigAccessor, ConfigAccessorFactory, Registry } from "../engine/types";
 import type { SecretsContext } from "../secrets";
 import type { FileStorageProvider } from "./types";
 
@@ -120,10 +121,7 @@ export async function createFileProviderForTenant(
   return usage.options.build(ctx, tenantId);
 }
 
-// A bound, per-tenant provider resolver. One instance serves all tenants
-// (tenantId is the call argument) — the single spine shared by upload routes,
-// ctx.files and the GDPR jobs.
-export type FileProviderResolver = (tenantId: TenantId) => Promise<FileStorageProvider>;
+export type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 
 export type FileProviderResolverDeps = {
   readonly registry?: Registry;

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/i18n/required-surface-keys.ts

@@ -1,3 +1,4 @@
+import { isExtensionEditSection, normalizeListColumn } from "../engine/screen-helpers";
 import type {
   ActionFormScreenDefinition,
   ConfigEditScreenDefinition,
@@ -15,7 +16,6 @@ import type {
   ToolbarAction,
   WorkspaceDefinition,
 } from "../engine/types";
-import { isExtensionEditSection, normalizeListColumn } from "../engine/types/screen";
 
 /** Pseudo-entity for actionForm field labels (renderer action-form-shim). */
 export const ACTION_FORM_ENTITY = "__action-form__";

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/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 * from "@cosmicdrift/kumiko-types/logger";

package/src/observability/types/index.ts

@@ -1,29 +1 @@
-// Barrel for observability types. Split into span/metric/provider files so
-// each module stays focused; consumers still import from "./types".
-
-export type {
-  Counter,
-  Gauge,
-  Histogram,
-  Meter,
-  MetricDefinition,
-  MetricLabels,
-  MetricsHandle,
-  MetricType,
-} from "./metric";
-export type {
-  ObservabilityOptions,
-  ObservabilityProvider,
-  SamplingConfig,
-  SensitiveFilterConfig,
-} from "./provider";
-export type {
-  SerializedTraceContext,
-  Span,
-  SpanAttributes,
-  SpanAttributeValue,
-  SpanKind,
-  SpanStatus,
-  StartSpanOptions,
-  Tracer,
-} from "./span";
+export * from "@cosmicdrift/kumiko-types/observability";