@cosmicdrift/kumiko-bundled-features 0.305.0 → 0.307.0

package/src/billing-foundation/tenant-destroy-hook.ts

@@ -1,5 +1,5 @@
-import { deleteMany, type EntityTableMeta, updateMany } from "@cosmicdrift/kumiko-framework/db";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import { declareEscapeHatch, type TenantDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
 import { archiveStream } from "@cosmicdrift/kumiko-framework/event-store";
 import { resolveProfileForTenant } from "../compliance-profiles";
 import { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id";
@@ -13,30 +13,33 @@ import { paymentsProjectionTable, subscriptionsProjectionTable } from "./project
 // it redacts the projection row directly instead of relying on key erasure.
 const REDACTED_PII_VALUE = "[erased]";
 
+// Compliance-profile lookup and event-stream archive both sit outside TenantDb's own methods — need the escape hatch.
+export const SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON =
+  "tenant-destroy looks up the compliance profile and archives the subscription event-stream before the projection row is redacted/deleted";
+export const PAYMENT_TENANT_DESTROY_ARCHIVE_REASON =
+  "tenant-destroy looks up the compliance profile and archives the payment event-stream before the projection rows are redacted/deleted";
+
 /** Tenant-destroy hook for billing PII (#800). HGB retains the accounting
  *  row but redacts the two provider-subject PII fields; other profiles
  *  hard-delete the row. Either way the subscription stream is archived so a
  *  future projection rebuild can't resurrect what was erased. */
-export async function subscriptionTenantDestroyHook(ctx: {
-  readonly db: import("@cosmicdrift/kumiko-framework/db").DbRunner;
-  readonly tenantId: TenantId;
-}): Promise<void> {
+export async function subscriptionTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void> {
+  declareEscapeHatch({ reason: SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON });
   const { profile } = await resolveProfileForTenant({
-    db: ctx.db,
+    db: ctx.db.unsafeRaw(SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON),
     tenantId: ctx.tenantId,
   });
   const aggregateId = subscriptionAggregateId(ctx.tenantId);
   if (profile.key === "de-hr-dsgvo-hgb") {
-    await updateMany(
-      ctx.db,
+    await ctx.db.updateMany(
       subscriptionsProjectionTable as EntityTableMeta,
       { providerCustomerId: REDACTED_PII_VALUE, providerSubscriptionId: REDACTED_PII_VALUE },
       { id: aggregateId },
     );
   } else {
-    await deleteMany(ctx.db, subscriptionsProjectionTable as EntityTableMeta, { id: aggregateId });
+    await ctx.db.deleteMany(subscriptionsProjectionTable as EntityTableMeta, { id: aggregateId });
   }
-  await archiveStream(ctx.db, {
+  await archiveStream(ctx.db.unsafeRaw(SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON), {
     tenantId: ctx.tenantId,
     aggregateId,
     aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
@@ -50,28 +53,25 @@ export async function subscriptionTenantDestroyHook(ctx: {
  *  rows — the predicate here is `tenantId`, not `id`. The payment-stream
  *  itself is still one stream per tenant (paymentAggregateId), so
  *  archiveStream targets that single aggregateId as usual. */
-export async function paymentTenantDestroyHook(ctx: {
-  readonly db: import("@cosmicdrift/kumiko-framework/db").DbRunner;
-  readonly tenantId: TenantId;
-}): Promise<void> {
+export async function paymentTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void> {
+  declareEscapeHatch({ reason: PAYMENT_TENANT_DESTROY_ARCHIVE_REASON });
   const { profile } = await resolveProfileForTenant({
-    db: ctx.db,
+    db: ctx.db.unsafeRaw(PAYMENT_TENANT_DESTROY_ARCHIVE_REASON),
     tenantId: ctx.tenantId,
   });
   const aggregateId = paymentAggregateId(ctx.tenantId);
   if (profile.key === "de-hr-dsgvo-hgb") {
-    await updateMany(
-      ctx.db,
+    await ctx.db.updateMany(
       paymentsProjectionTable as EntityTableMeta,
       { providerCustomerId: REDACTED_PII_VALUE },
       { tenantId: ctx.tenantId },
     );
   } else {
-    await deleteMany(ctx.db, paymentsProjectionTable as EntityTableMeta, {
+    await ctx.db.deleteMany(paymentsProjectionTable as EntityTableMeta, {
       tenantId: ctx.tenantId,
     });
   }
-  await archiveStream(ctx.db, {
+  await archiveStream(ctx.db.unsafeRaw(PAYMENT_TENANT_DESTROY_ARCHIVE_REASON), {
     tenantId: ctx.tenantId,
     aggregateId,
     aggregateType: PAYMENT_AGGREGATE_TYPE,

package/src/billing-foundation/types.ts

@@ -26,7 +26,12 @@
 
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import type { BillingEventKinds, SubscriptionEventType, SubscriptionStatus } from "./constants";
+import {
+  type BillingEventKinds,
+  SUBSCRIPTION_PROVIDER_EXTENSION,
+  type SubscriptionEventType,
+  type SubscriptionStatus,
+} from "./constants";
 
 // =============================================================================
 // Normalisierter Webhook-Event
@@ -215,3 +220,10 @@ export type SubscriptionProviderPlugin = {
     providerSubscriptionId: string,
   ) => Promise<void>;
 };
+
+// r.useExtension options-shape, co-located since the framework never imports upward.
+declare module "@cosmicdrift/kumiko-framework/engine" {
+  interface KumikoExtensionOptionsMap {
+    [SUBSCRIPTION_PROVIDER_EXTENSION]: SubscriptionProviderPlugin;
+  }
+}

package/src/cap-counter/__tests__/enforce-cap.test.ts

@@ -114,6 +114,13 @@ describe("enforceCap — burstable profile (mails / tokens)", () => {
     await expect(enforceCap(ctx, opts)).rejects.toThrow(CapExceededError);
   });
 
+  test("amount checks the last of the booked units: 1190 + 10 units passes, + 11 throws", async () => {
+    const ctx = stubCalendarCtx([{ value: 1190, lastSoftWarnedAt: null }]);
+    const passing = await enforceCap(ctx, { ...opts, amount: 10 });
+    expect(passing).toEqual({ state: "soft-hit", value: 1199, crossed: true });
+    await expect(enforceCap(ctx, { ...opts, amount: 11 })).rejects.toThrow(CapExceededError);
+  });
+
   test("CapExceededError carries cap-name + limit + currentValue", async () => {
     const ctx = stubCalendarCtx([{ value: 1500, lastSoftWarnedAt: null }]);
     try {

package/src/cap-counter/changes.json

@@ -1,4 +1,9 @@
 [
+  {
+    "version": "0.307.0",
+    "type": "improvement",
+    "title": "enforceCap accepts an amount for multi-unit bookings"
+  },
   {
     "version": "0.278.0",
     "type": "improvement",

package/src/cap-counter/enforce-cap.ts

@@ -93,6 +93,9 @@ export async function enforceCap(
     readonly periodStartIso: string;
     readonly limit: number;
     readonly profile: CapToleranceProfileName;
+    // Units the caller is about to book in one go (default 1), checked with
+    // the same outcome as booking them one by one.
+    readonly amount?: number;
   },
 ): Promise<EnforceCapResult> {
   if (!ctx.db) {
@@ -110,7 +113,9 @@ export async function enforceCap(
   );
 
   const row = rows[0];
-  const value = row ? (row["value"] as number) : 0; // @cast-boundary db-row
+  const storedValue = row ? (row["value"] as number) : 0; // @cast-boundary db-row
+  // The last of `amount` units sees this value before its own increment.
+  const value = storedValue + (options.amount ?? 1) - 1;
 
   if (value >= hardThreshold) {
     throw new CapExceededError(options.capName, options.limit, value, tolerance);
@@ -285,6 +290,7 @@ export async function enforceCapAndMaybeNotify(
     readonly limit: number;
     readonly profile: CapToleranceProfileName;
     readonly notify: SoftHitNotifier;
+    readonly amount?: number;
   },
 ): Promise<EnforceCapResult> {
   const result = await enforceCap(ctx, {
@@ -292,6 +298,7 @@ export async function enforceCapAndMaybeNotify(
     periodStartIso: options.periodStartIso,
     limit: options.limit,
     profile: options.profile,
+    ...(options.amount !== undefined && { amount: options.amount }),
   });
 
   if (result.state === "soft-hit" && result.crossed) {

package/src/channel-email/feature.ts

@@ -1,3 +1,4 @@
+import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { createEmailChannel, type EmailChannelOptions } from "./email-channel";
 
@@ -15,7 +16,7 @@ export function createChannelEmailFeature(options: EmailChannelOptions): Feature
     });
     r.requires("delivery");
 
-    r.useExtension("deliveryChannel", "email", {
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "email", {
       mode: channel.mode,
       resolve: channel.resolve,
       render: channel.render,

package/src/channel-in-app/feature.ts

@@ -1,3 +1,4 @@
+import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { inboxQuery } from "./handlers/inbox.query";
 import { markAllReadWrite } from "./handlers/mark-all-read.write";
@@ -23,7 +24,7 @@ export function createChannelInAppFeature(): FeatureDefinition {
     });
 
     // Register as delivery channel via extension system
-    r.useExtension("deliveryChannel", "inApp", {
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "inApp", {
       mode: inAppChannel.mode,
       resolve: inAppChannel.resolve,
       send: inAppChannel.send,

package/src/channel-push/feature.ts

@@ -1,3 +1,4 @@
+import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { createPushChannel, type PushChannelOptions } from "./push-channel";
 
@@ -15,7 +16,7 @@ export function createChannelPushFeature(options: PushChannelOptions): FeatureDe
     });
     r.requires("delivery");
 
-    r.useExtension("deliveryChannel", "push", {
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "push", {
       mode: channel.mode,
       resolve: channel.resolve,
       send: channel.send,

package/src/config/__tests__/reencrypt-job-concurrent-write-race.integration.test.ts

@@ -19,8 +19,8 @@ import { randomBytes } from "node:crypto";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   createEventStoreExecutor,
+  createSystemDbView,
   createTenantDb,
-  createUncheckedSystemDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
@@ -157,12 +157,23 @@ function racyJobCtx(
   };
   return {
     db: createTenantDb(stack.db, SYSTEM_TENANT_ID),
-    systemDb: createUncheckedSystemDb(createTenantDb(stack.db, SYSTEM_TENANT_ID, "system")),
+    systemDb: createSystemDbView(
+      createTenantDb(stack.db, SYSTEM_TENANT_ID, "system", undefined, undefined, undefined, {
+        unsafeRaw: { reason: "test: job context mirrors systemScope() grant" },
+      }),
+    ),
     registry: stack.registry,
     masterKeyProvider: mutableProvider,
     configEncryption: racyCipher,
     log,
-  } as unknown as Parameters<typeof reencryptJob>[1]; // @cast-boundary test-seam — job only reads db/registry/masterKeyProvider/configEncryption/log
+    // Without a sink, the job's escape-hatch reporter warn-logs through `log` and its
+    // report is deduped by the framework's process-wide window (escape-hatch-report.ts),
+    // so whether the unconditional per-run scan ack reaches `log.warn` here depends on
+    // unrelated sibling tests' order in the same process. A sink (mirrors production,
+    // where the audit feature wires one) routes that report away from `log` entirely,
+    // isolating this test from that shared window.
+    _escapeHatchAuditSink: async () => {},
+  } as unknown as Parameters<typeof reencryptJob>[1]; // @cast-boundary test-seam — job only reads db/registry/masterKeyProvider/configEncryption/log/_escapeHatchAuditSink
 }
 
 beforeAll(async () => {

package/src/config/__tests__/reencrypt-job-kek-rotation.integration.test.ts

@@ -12,8 +12,8 @@ import { randomBytes } from "node:crypto";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   createEventStoreExecutor,
+  createSystemDbView,
   createTenantDb,
-  createUncheckedSystemDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
@@ -138,10 +138,18 @@ function capturingLog(captured: CapturedLog): TestJobLog {
 
 function jobCtx(captured?: CapturedLog): Parameters<typeof reencryptJob>[1] {
   const log = captured ? capturingLog(captured) : noopLog;
-  const systemModeDb = createTenantDb(stack.db, SYSTEM_TENANT_ID, "system");
+  const systemModeDb = createTenantDb(
+    stack.db,
+    SYSTEM_TENANT_ID,
+    "system",
+    undefined,
+    undefined,
+    undefined,
+    { unsafeRaw: { reason: "test: job context mirrors systemScope() grant" } },
+  );
   return {
     db: systemModeDb,
-    systemDb: createUncheckedSystemDb(systemModeDb),
+    systemDb: createSystemDbView(systemModeDb),
     registry: stack.registry,
     masterKeyProvider: mutableProvider,
     configEncryption: cipher,

package/src/config/__tests__/reencrypt-job-tenant-checks.integration.test.ts

@@ -1,5 +1,5 @@
 // Regression guard for kumiko-framework#2072: the KEK-rotation job's
-// systemScope() fail-closed checks — createUncheckedSystemDb().
+// systemScope() fail-closed checks — createSystemDbView().
 // acknowledgeCrossTenant() gating the initial cross-tenant scan,
 // assertRowsTenant() re-verifying each per-tenant slice before it's served
 // to the write loop — must not block legitimate multi-tenant rotation. A
@@ -14,8 +14,8 @@ import { randomBytes } from "node:crypto";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   createEventStoreExecutor,
+  createSystemDbView,
   createTenantDb,
-  createUncheckedSystemDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
@@ -117,7 +117,11 @@ function capturingLog(captured: CapturedLog): TestJobLog {
 function jobCtx(captured: CapturedLog): Parameters<typeof reencryptJob>[1] {
   return {
     db: createTenantDb(stack.db, SYSTEM_TENANT_ID),
-    systemDb: createUncheckedSystemDb(createTenantDb(stack.db, SYSTEM_TENANT_ID, "system")),
+    systemDb: createSystemDbView(
+      createTenantDb(stack.db, SYSTEM_TENANT_ID, "system", undefined, undefined, undefined, {
+        unsafeRaw: { reason: "test: job context mirrors systemScope() grant" },
+      }),
+    ),
     registry: stack.registry,
     masterKeyProvider: mutableProvider,
     configEncryption: cipher,

package/src/config/__tests__/require-system-db.test.ts

@@ -1,12 +1,12 @@
 import { describe, expect, test } from "bun:test";
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import { createUncheckedSystemDb } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemDbView } from "@cosmicdrift/kumiko-framework/db";
 import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
 import { requireSystemDb } from "../feature";
 
 // Minimal TenantDb stub — only .tenantId is read by assertTenantMatch /
-// createUncheckedSystemDb; the real db-query methods are never called by
+// createSystemDbView; the real db-query methods are never called by
 // requireSystemDb itself.
 function fakeTenantDb(tenantId: TenantId): TenantDb {
   return { tenantId, mode: "system" } as unknown as TenantDb;
@@ -16,7 +16,7 @@ function fakeTenantDb(tenantId: TenantId): TenantDb {
 function contextStub(db: TenantDb, withSystemDb: boolean): HandlerContext {
   return {
     db,
-    systemDb: withSystemDb ? createUncheckedSystemDb(db) : undefined,
+    systemDb: withSystemDb ? createSystemDbView(db) : undefined,
     // biome-ignore lint/suspicious/noExplicitAny: rest of HandlerContext isn't touched by requireSystemDb.
   } as any;
 }

package/src/config/handlers/reencrypt.job.ts

@@ -21,12 +21,12 @@
 // UncheckedSystemDb.acknowledgeCrossTenant(). Rows are bucketed by tenant,
 // and assertRowsTenant() re-verifies each row against its bucket's tenant
 // right before the write — both checks are built locally from the exported
-// createUncheckedSystemDb().
+// createSystemDbView().
 
 import {
   createEventStoreExecutor,
+  createSystemDbView,
   createTenantDb,
-  createUncheckedSystemDb,
   type DbConnection,
   type TenantDb,
   type UncheckedSystemDb,
@@ -135,11 +135,7 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
   function sdbFor(tenantId: TenantId): UncheckedSystemDb {
     let existing = sdbCache.get(tenantId);
     if (!existing) {
-      existing = createUncheckedSystemDb(
-        tdbFor(tenantId),
-        undefined,
-        reportEscapeHatchFor(tenantId),
-      );
+      existing = createSystemDbView(tdbFor(tenantId), undefined, reportEscapeHatchFor(tenantId));
       sdbCache.set(tenantId, existing);
     }
     return existing;
@@ -149,7 +145,7 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
   // to acknowledge the cross-tenant scan below, never bound to a real
   // tenant's writes — sharing it with sdbFor(SYSTEM_TENANT_ID) would make a
   // write-path cache entry double as the scan's ack gate.
-  const scanDb = createUncheckedSystemDb(
+  const scanDb = createSystemDbView(
     createTenantDb(db, SYSTEM_TENANT_ID, "system"),
     undefined,
     reportEscapeHatchFor(SYSTEM_TENANT_ID),

package/src/custom-fields/db/queries/__tests__/{unsafe-read-retrying.test.ts → unsafe-read-retrying.integration.test.ts}

@@ -1,32 +1,33 @@
-// #2323: field-access.ts, quota.ts, user-data-rights.ts and retention.ts read
-// custom-field rows via asRawClient(db).unsafe() directly, bypassing the
-// #1163 closed-connection retry that only covered bun-db/query.ts's own
-// selectMany/countWhere. Routed the SELECT-only call sites through
-// unsafeReadRetrying instead — this test mirrors
-// bun-db/__tests__/select-many-retry.test.ts's fake-client pattern to prove
-// the retry now actually fires for each call site. applyRetentionRemovals
-// (an UPDATE) is out of scope per #1358 — writes stay unretried.
+// field-access.ts, quota.ts, user-data-rights.ts and retention.ts read
+// custom-field rows through unsafeReadRetrying; this proves the retry fires
+// per call site using a real captured driver error. applyRetentionRemovals
+// (an UPDATE) stays out of scope — unretried by design.
 
-import { describe, expect, test } from "bun:test";
+import { beforeAll, describe, expect, test } from "bun:test";
+import { captureClosedConnectionError } from "@cosmicdrift/kumiko-framework/testing";
 import { selectSerializedFieldDefinition } from "../field-access";
 import { countTenantFieldDefinitions } from "../quota";
 import { selectHostRowsWithCustomFields } from "../retention";
 import { selectCustomFieldsHostRows, selectFieldDefinitionsForEntity } from "../user-data-rights";
 
-function closedConnectionError(): Error {
-  return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
-}
+let closedConnectionError: unknown;
+
+beforeAll(async () => {
+  closedConnectionError = await captureClosedConnectionError();
+});
 
 type FakeClient = {
   unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
   begin: () => never;
+  options: { max: number };
   calls: number;
 };
 
-function fakeClient(failures: Error[], row: Record<string, unknown>): FakeClient {
+function fakeClient(failures: unknown[], row: Record<string, unknown>): FakeClient {
   const remaining = [...failures];
   const client: FakeClient = {
     calls: 0,
+    options: { max: 1 },
     unsafe: async () => {
       client.calls++;
       const err = remaining.shift();
@@ -40,30 +41,30 @@ function fakeClient(failures: Error[], row: Record<string, unknown>): FakeClient
   return client;
 }
 
-describe("custom-fields db/queries — closed-connection retry (#2323)", () => {
+describe("custom-fields db/queries — closed-connection retry", () => {
   test("selectSerializedFieldDefinition retries once through db.unsafeRaw and returns the row", async () => {
-    const raw = fakeClient([closedConnectionError()], { serialized_field: "sf1" });
+    const raw = fakeClient([closedConnectionError], { serialized_field: "sf1" });
     const result = await selectSerializedFieldDefinition(raw, "t1", "entity", "field");
     expect(result).toBe("sf1");
     expect(raw.calls).toBe(2);
   });
 
   test("countTenantFieldDefinitions retries once through db.unsafeRaw and returns the count", async () => {
-    const raw = fakeClient([closedConnectionError()], { n: 3 });
+    const raw = fakeClient([closedConnectionError], { n: 3 });
     const result = await countTenantFieldDefinitions(raw, "t1");
     expect(result).toBe(3);
     expect(raw.calls).toBe(2);
   });
 
   test("selectCustomFieldsHostRows retries once and returns rows", async () => {
-    const db = fakeClient([closedConnectionError()], { id: "1", custom_fields: {} });
+    const db = fakeClient([closedConnectionError], { id: "1", custom_fields: {} });
     const rows = await selectCustomFieldsHostRows(db as never, "host_table", "user_id", "u1", "t1");
     expect(rows).toHaveLength(1);
     expect(db.calls).toBe(2);
   });
 
   test("selectFieldDefinitionsForEntity retries once and returns rows", async () => {
-    const db = fakeClient([closedConnectionError()], { field_key: "k1", serialized_field: "sf" });
+    const db = fakeClient([closedConnectionError], { field_key: "k1", serialized_field: "sf" });
     const rows = await selectFieldDefinitionsForEntity(db as never, "entity", "t1");
     expect(rows).toHaveLength(1);
     expect(rows[0]?.field_key).toBe("k1");
@@ -71,7 +72,7 @@ describe("custom-fields db/queries — closed-connection retry (#2323)", () => {
   });
 
   test("selectHostRowsWithCustomFields retries once and returns rows", async () => {
-    const db = fakeClient([closedConnectionError()], {
+    const db = fakeClient([closedConnectionError], {
       id: "1",
       modified_at: null,
       custom_fields: {},
@@ -81,13 +82,13 @@ describe("custom-fields db/queries — closed-connection retry (#2323)", () => {
     expect(db.calls).toBe(2);
   });
 
-  test("gives up after the single retry when the connection stays closed", async () => {
-    const raw = fakeClient([closedConnectionError(), closedConnectionError()], {
+  test("gives up after exhausting pool-bounded retries (max: 1 → 3 total calls)", async () => {
+    const raw = fakeClient([closedConnectionError, closedConnectionError, closedConnectionError], {
       serialized_field: "sf1",
     });
-    await expect(selectSerializedFieldDefinition(raw, "t1", "entity", "field")).rejects.toThrow(
-      "connection was closed",
+    await expect(selectSerializedFieldDefinition(raw, "t1", "entity", "field")).rejects.toBe(
+      closedConnectionError,
     );
-    expect(raw.calls).toBe(2);
+    expect(raw.calls).toBe(3);
   });
 });

package/src/delivery/__tests__/delivery-screens.boot.test.ts

@@ -1,9 +1,16 @@
 import { describe, expect, test } from "bun:test";
-import { access, isOpenToAllGranted, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  access,
+  createRegistry,
+  defineFeature,
+  isOpenToAllGranted,
+  validateBoot,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
 import { createConfigFeature } from "../../config/feature";
 import { createTenantFeature } from "../../tenant/feature";
-import { DELIVERY_LOG_SCREEN_ID } from "../constants";
+import { DELIVERY_CHANNEL_EXTENSION, DELIVERY_LOG_SCREEN_ID } from "../constants";
+import { collectChannels } from "../delivery-service";
 import { createDeliveryFeature } from "../feature";
 
 describe("delivery screens + handler access alignment", () => {
@@ -38,6 +45,17 @@ describe("delivery screens + handler access alignment", () => {
     expect(preferencesAccess !== undefined && isOpenToAllGranted(preferencesAccess)).toBe(true);
   });
 
+  test("collectChannels fails loud on a registration with invalid options", () => {
+    const broken = defineFeature("broken-channel", (r) => {
+      // @ts-expect-error resolve/send are required — proves the guard rejects a malformed options bag instead of silently dropping the channel
+      r.useExtension(DELIVERY_CHANNEL_EXTENSION, "bad-entity", { anything: 1 });
+    });
+    const registry = createRegistry([...features, broken]);
+    expect(() => collectChannels(registry)).toThrow(
+      `${DELIVERY_CHANNEL_EXTENSION} registration for "bad-entity" has invalid options`,
+    );
+  });
+
   test("boot-validates with a narrowed access option", () => {
     expect(() =>
       validateBoot([