@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/cap-counter/handlers/increment-rolling.write.ts

@@ -0,0 +1,79 @@
+// increment-rolling — Rolling-Window-Counter-Increment via Custom-
+// Event statt CRUD/projection. Designed für Caps deren Wert sich
+// kontinuierlich erneuern soll (KI-Tokens-7-Tage, Egress pro 24h).
+//
+// **Warum kein r.entity / CRUD wie der Calendar-Counter:** Der
+// Calendar-Counter speichert den kumulierten value in seiner
+// projection-row. Beim Period-Rollover wechselt die aggregate-id auf
+// den neuen Period-Start, das ist der "Reset". Bei Rolling-Window
+// gibt es keinen Rollover-Punkt — der Counter "rollt" kontinuierlich
+// raus. Ein einzelner kumulativer value wäre falsch (würde monoton
+// wachsen ohne Expiration). Die korrekte Read-Semantik ist: SUM aller
+// Increment-Amounts der letzten N Tage. Dafür brauchen wir die
+// einzelnen Increments als separate Events mit ihrem eigenen
+// `amount`-Feld; CRUD-Events tragen nur den kumulativen value.
+//
+// **Aggregate-Stream:** ein Stream pro (tenant, capName) — siehe
+// `rollingCapAggregateId`. Alle Increments hängen am selben Stream
+// in monoton-steigender version. enforceRollingCap liest die letzten
+// N Tage aus diesem Stream.
+
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { rollingCapAggregateId } from "../aggregate-id";
+import { CAP_COUNTER_ROLLING_AGGREGATE_TYPE, ROLLING_INCREMENTED_EVENT_QN } from "../constants";
+
+const incrementRollingSchema = z.object({
+  /** App-defined cap-name. e.g. "ai-tokens-7day", "egress-bytes-24h". */
+  capName: z.string().min(1).max(100),
+  /** Increment-amount. Default 1 (count-events) — pass exact size for
+   *  byte/token-counters. Stored verbatim in the event payload so the
+   *  Window-Sum is exact. */
+  amount: z.number().int().positive().default(1),
+});
+type IncrementRollingPayload = z.infer<typeof incrementRollingSchema>;
+
+/** Schema des emittierten Custom-Events. Identisch zum Input-Schema:
+ *  der Caller zahlt amount, wir hängen es 1:1 an den Stream. */
+export const rollingIncrementedSchema = incrementRollingSchema;
+
+// Rolling-Increment-Handler — append-only. Race-frei: zwei parallele
+// Increments für (tenant, cap) hängen sich am selben aggregate-stream
+// in unterschiedlichen versions auf, das event-store ordert.
+//
+// **Kein version_conflict-Pfad** wie beim Calendar-Counter: hier
+// liest niemand den projection-state vor dem Schreiben. Der
+// expectedVersion ist implizit "next-after-current", was der event-
+// store atomar ermittelt.
+export const incrementRollingCapHandler: WriteHandlerDef = {
+  name: "increment-rolling",
+  schema: incrementRollingSchema,
+  // Internal handler — System-Caller (Plattform-foundations nach
+  // erfolgreichem Side-Effect) ruft das auf. Tenant-end-users niemals
+  // direkt. Audit-row zeigt welche subsystem-call-site zugehängt hat.
+  access: { roles: ["SystemAdmin"] },
+  handler: async (event, ctx) => {
+    // @cast-boundary engine-payload — dispatcher hands handler the
+    // already-Zod-validated payload as `unknown`; cast to the typed
+    // shape we declared via incrementRollingSchema. Mirror der
+    // existing increment.write.ts-Cast — gleiche dispatcher-boundary.
+    const payload = event.payload as IncrementRollingPayload;
+    const aggregateId = rollingCapAggregateId(event.user.tenantId, payload.capName);
+
+    // appendEventUnsafe — bundled-features-Pfad (apps mit yarn kumiko
+    // codegen kriegen den strict-typed appendEvent-Wrapper). Schema-
+    // Validation läuft trotzdem, weil r.defineEvent das Schema
+    // registriert hat.
+    await ctx.appendEventUnsafe({
+      aggregateId,
+      aggregateType: CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
+      type: ROLLING_INCREMENTED_EVENT_QN,
+      payload: {
+        capName: payload.capName,
+        amount: payload.amount,
+      },
+    });
+
+    return { isSuccess: true, data: { aggregateId, amount: payload.amount } };
+  },
+};

package/src/cap-counter/handlers/increment.write.ts

@@ -0,0 +1,92 @@
+import { createEntityExecutor, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import { capCounterAggregateId } from "../aggregate-id";
+import { capCounterEntity } from "../entity";
+
+const { table, executor } = createEntityExecutor("cap-counter", capCounterEntity);
+
+const incrementSchema = z.object({
+  /** App-defined cap-name. e.g. "platform-mails", "ai-tokens-7day". */
+  capName: z.string().min(1).max(100),
+  /** Increment-amount. Default 1 (count-events) — pass exact size for
+   *  byte/token-counters (file-upload size, llm-token-count). */
+  amount: z.number().int().positive().default(1),
+  /** Period-start ISO. Caller is responsible: monthly counters use
+   *  "first-of-current-month" (computed once per request via
+   *  `Temporal.Now.zonedDateTimeISO("UTC").startOfMonth().toString()`),
+   *  rolling-window counters pass a fixed sentinel ("1970-01-01"). */
+  periodStartIso: z.string().min(1),
+});
+type IncrementPayload = z.infer<typeof incrementSchema>;
+
+// increment-cap — atomic counter increment via the event-store's
+// optimistic-lock. Two parallel increments for the same (tenant, cap,
+// period) go to the same aggregate; the second one's append fails with
+// version_conflict — caller retries (the dispatcher already handles
+// that for write-handlers, see version_conflict-retry-policy).
+//
+// **Two paths:**
+//   1. Aggregate doesn't exist yet (first increment of the period) →
+//      executor.create with deterministic id, value = amount.
+//   2. Aggregate exists → executor.update with current value + amount.
+//
+// **Why no `r.systemScope`:** counters are tenant-scoped (one row per
+// tenant per cap per period). The dispatcher's tenant-filter on ctx.db
+// ensures a tenant can only see/increment their own counters. Cross-
+// tenant cap-rebuild for ops uses raw DB-access at the framework layer,
+// not this handler.
+export const incrementCapHandler: WriteHandlerDef = {
+  name: "increment",
+  schema: incrementSchema,
+  // Internal handler — only system-callers (Plattform-foundations after
+  // a successful side-effect) drive this. Tenant-end-users never call
+  // it directly. SystemAdmin-access leaves a clear audit row showing
+  // which subsystem incremented.
+  access: { roles: ["SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const payload = event.payload as IncrementPayload;
+    const aggregateId = capCounterAggregateId(
+      event.user.tenantId,
+      payload.capName,
+      payload.periodStartIso,
+    );
+
+    // Read existing aggregate's projection-row to decide create vs update.
+    // ctx.db is auto-tenant-scoped — id-lookup is unique per tenant.
+    const existing = await ctx.db.select().from(table).where(eq(table["id"], aggregateId)).limit(1);
+
+    if (existing.length === 0) {
+      return executor.create(
+        {
+          id: aggregateId,
+          capName: payload.capName,
+          value: payload.amount,
+          periodStart: Temporal.Instant.from(payload.periodStartIso),
+          lastSoftWarnedAt: null,
+        },
+        event.user,
+        ctx.db,
+      );
+    }
+
+    const currentRow = existing[0];
+    if (!currentRow) {
+      // Defensive — length-check above means this is unreachable. Throws
+      // clearer than a possibly-null deref later.
+      throw new Error("cap-counter:increment: row vanished between length-check and read");
+    }
+    const currentValue = currentRow["value"] as number;
+    const currentVersion = currentRow["version"] as number;
+    return executor.update(
+      {
+        id: aggregateId,
+        version: currentVersion,
+        changes: { value: currentValue + payload.amount },
+      },
+      event.user,
+      ctx.db,
+    );
+  },
+};

package/src/cap-counter/handlers/mark-soft-warned.write.ts

@@ -0,0 +1,57 @@
+import { createEntityExecutor, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import { capCounterAggregateId } from "../aggregate-id";
+import { capCounterEntity } from "../entity";
+
+const { table, executor } = createEntityExecutor("cap-counter", capCounterEntity);
+
+// mark-soft-warned — sets lastSoftWarnedAt on the counter so subsequent
+// soft-cap-hits in the same period don't re-trigger notifications.
+// Anti-Notification-Storm-Schutz aus Memory `project_pricing_byok_caps`.
+//
+// **Caller-Pattern:** enforceCap-Helper checks if value crosses the
+// soft threshold AND lastSoftWarnedAt is null → calls this handler →
+// emits whatever notification (delivery-feature, ops-alert, etc.). The
+// emit-side is app-specific; this handler only sets the flag.
+const markSoftWarnedSchema = z.object({
+  capName: z.string().min(1).max(100),
+  periodStartIso: z.string().min(1),
+});
+
+export const markSoftWarnedHandler: WriteHandlerDef = {
+  name: "mark-soft-warned",
+  schema: markSoftWarnedSchema,
+  access: { roles: ["SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const payload = event.payload as z.infer<typeof markSoftWarnedSchema>;
+    const aggregateId = capCounterAggregateId(
+      event.user.tenantId,
+      payload.capName,
+      payload.periodStartIso,
+    );
+
+    const existing = await ctx.db.select().from(table).where(eq(table["id"], aggregateId)).limit(1);
+    if (existing.length === 0) {
+      throw new Error(
+        `cap-counter: cannot mark-soft-warned, no counter found for tenant=${event.user.tenantId} cap=${payload.capName} period=${payload.periodStartIso}`,
+      );
+    }
+    const row = existing[0];
+    if (!row) {
+      throw new Error("cap-counter:mark-soft-warned: row vanished between length-check and read");
+    }
+    const currentVersion = row["version"] as number;
+
+    return executor.update(
+      {
+        id: aggregateId,
+        version: currentVersion,
+        changes: { lastSoftWarnedAt: Temporal.Now.instant() },
+      },
+      event.user,
+      ctx.db,
+    );
+  },
+};

package/src/cap-counter/index.ts

@@ -0,0 +1,34 @@
+// Public API of the cap-counter bundled-feature.
+
+export { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id";
+export {
+  CAP_COUNTER_FEATURE,
+  CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
+  CapCounterHandlers,
+  CapCounterQueries,
+  ROLLING_INCREMENTED_EVENT_QN,
+  ROLLING_INCREMENTED_EVENT_SHORT,
+} from "./constants";
+export {
+  CAP_TOLERANCES,
+  CapExceededError,
+  type CapToleranceProfile,
+  type CapToleranceProfileName,
+  currentCalendarMonthStartIso,
+  type EnforceCapResult,
+  enforceCap,
+  enforceCapAndMaybeNotify,
+  enforceRollingCap,
+  enforceRollingCapAndMaybeNotify,
+  type SoftHitNotifier,
+} from "./enforce-cap";
+export { capCounterEntity } from "./entity";
+export { capCounterFeature } from "./feature";
+export {
+  type CalendarCapDef,
+  type CalendarCapResolver,
+  type RollingCapDef,
+  type RollingCapResolver,
+  withCapEnforcement,
+  withRollingCapEnforcement,
+} from "./with-cap-enforcement";

package/src/cap-counter/with-cap-enforcement.ts

@@ -0,0 +1,179 @@
+// withCapEnforcement / withRollingCapEnforcement — handler-wrapper die
+// pre-call enforceCap-And-Notify + post-call increment um den
+// gewrappten Handler legen.
+//
+// **Warum Wrapper statt manuelle Calls im Handler:**
+// Pattern-konsistenz. Wer einen cap-bedingten Handler schreibt,
+// darf nicht vergessen den counter zu incrementen oder den enforce-
+// pre-call zu machen — beides ist atomic-mit-dem-Handler-zusammen.
+// Wrapper macht das Pattern explizit + co-located.
+//
+// **Atomicity-Vorbehalt:** Pre-enforce + Handler + Post-Increment
+// laufen in DREI getrennten Transaktionen (Dispatcher öffnet jede
+// ctx.write-call eine eigene). Bei einem Crash zwischen Handler-
+// Success und Post-Increment kommt der Counter unter — Tenant
+// kriegt 1-2 Mails extra. Akzeptabel weil Cap-Toleranzen (110/120%)
+// genau für solche Drift-Fälle gebaut sind.
+//
+// **Kein automatic markSoftWarned:** das passiert in
+// enforceCapAndMaybeNotify drin (siehe enforce-cap.ts). Wrapper ruft
+// nur den Helper, der den write dispatched.
+
+import type {
+  HandlerContext,
+  WriteEvent,
+  WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { CapCounterHandlers } from "./constants";
+import {
+  type CapToleranceProfileName,
+  enforceCapAndMaybeNotify,
+  enforceRollingCapAndMaybeNotify,
+  type SoftHitNotifier,
+} from "./enforce-cap";
+
+// =============================================================================
+// Calendar-Period-Wrapper
+// =============================================================================
+
+/**
+ * Pro-call dynamische Cap-Definition. Wird vor jedem Handler-Aufruf
+ * neu evaluiert — typischer Caller liest hier den Tenant-Tier aus
+ * dem ctx, mappt ihn auf einen Limit-Wert. `amount` default 1 (count-
+ * events); für byte/token-cap übergibt der Caller die Größe aus
+ * `event.payload`.
+ */
+export type CalendarCapDef = {
+  readonly capName: string;
+  readonly periodStartIso: string;
+  readonly limit: number;
+  readonly profile: CapToleranceProfileName;
+  /** Increment-amount post-success. Default 1. */
+  readonly amount?: number;
+  readonly notify: SoftHitNotifier;
+};
+
+/** Resolver-fn that the wrapper calls before each handler invocation
+ *  to compute the cap-spec for THIS request (e.g. limit derived from
+ *  tenant-tier). Sync OR async — async lets the caller fetch the
+ *  tier from DB. */
+export type CalendarCapResolver = (
+  event: WriteEvent,
+  ctx: HandlerContext,
+) => Promise<CalendarCapDef> | CalendarCapDef;
+
+/**
+ * Wrap a write-handler with calendar-period cap-enforcement.
+ *
+ * Flow:
+ *   1. resolve cap-spec via `capResolver(event, ctx)`
+ *   2. pre-call: `enforceCapAndMaybeNotify` — throws CapExceededError
+ *      on hard-hit (handler never runs), notifies on soft-hit-crossing
+ *   3. invoke the wrapped handler
+ *   4. post-success: dispatch `cap-counter:write:increment` with `amount`
+ *
+ * The returned handler-def keeps the original name/schema/access
+ * untouched — only the handler-fn is wrapped. The dispatcher sees
+ * the same external contract.
+ */
+export function withCapEnforcement(
+  handler: WriteHandlerDef,
+  capResolver: CalendarCapResolver,
+): WriteHandlerDef {
+  return {
+    name: handler.name,
+    schema: handler.schema,
+    access: handler.access,
+    handler: async (event, ctx) => {
+      const cap = await capResolver(event, ctx);
+
+      // Pre-enforce. Hard-hit throws CapExceededError; the dispatcher
+      // maps it to HTTP 429 + cap_exceeded code. Soft-hit-crossing
+      // notifies via the supplied notifier + flips lastSoftWarnedAt.
+      await enforceCapAndMaybeNotify(ctx, {
+        capName: cap.capName,
+        periodStartIso: cap.periodStartIso,
+        limit: cap.limit,
+        profile: cap.profile,
+        notify: cap.notify,
+      });
+
+      const result = await handler.handler(event, ctx);
+
+      // Post-success increment. Skip on failure so a failed write
+      // doesn't burn cap-quota. amount default 1.
+      if (result.isSuccess) {
+        await ctx.write(CapCounterHandlers.increment, {
+          capName: cap.capName,
+          amount: cap.amount ?? 1,
+          periodStartIso: cap.periodStartIso,
+        });
+      }
+
+      return result;
+    },
+  };
+}
+
+// =============================================================================
+// Rolling-Window-Wrapper
+// =============================================================================
+
+export type RollingCapDef = {
+  readonly capName: string;
+  readonly windowDays: number;
+  readonly limit: number;
+  readonly profile: CapToleranceProfileName;
+  readonly amount?: number;
+  readonly notify: SoftHitNotifier;
+};
+
+export type RollingCapResolver = (
+  event: WriteEvent,
+  ctx: HandlerContext,
+) => Promise<RollingCapDef> | RollingCapDef;
+
+/**
+ * Wrap a write-handler with rolling-window cap-enforcement.
+ *
+ * Same flow as `withCapEnforcement` but uses
+ * `enforceRollingCapAndMaybeNotify` + dispatches
+ * `cap-counter:write:increment-rolling` post-success.
+ *
+ * **Notification-Storm-Caveat:** rolling-counter trackt KEIN
+ * lastSoftWarnedAt — der Notifier feuert bei JEDEM Call solange
+ * der counter im soft-Bereich ist. Caller sollte einen TTL-Cache
+ * (`Map<capName, lastNotifiedAt>`) im notify-callback einbauen.
+ */
+export function withRollingCapEnforcement(
+  handler: WriteHandlerDef,
+  capResolver: RollingCapResolver,
+): WriteHandlerDef {
+  return {
+    name: handler.name,
+    schema: handler.schema,
+    access: handler.access,
+    handler: async (event, ctx) => {
+      const cap = await capResolver(event, ctx);
+
+      await enforceRollingCapAndMaybeNotify(ctx, {
+        capName: cap.capName,
+        windowDays: cap.windowDays,
+        limit: cap.limit,
+        profile: cap.profile,
+        notify: cap.notify,
+      });
+
+      const result = await handler.handler(event, ctx);
+
+      if (result.isSuccess) {
+        await ctx.write(CapCounterHandlers.incrementRolling, {
+          capName: cap.capName,
+          amount: cap.amount ?? 1,
+        });
+      }
+
+      return result;
+    },
+  };
+}

package/src/channel-email/email-channel.ts

@@ -0,0 +1,48 @@
+import type { DbRow } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { DeliveryChannel, NotificationRenderer } from "../delivery";
+import type { EmailTransport } from "./types";
+
+export type EmailChannelOptions = {
+  readonly transport: EmailTransport;
+  readonly renderer: NotificationRenderer;
+  readonly resolveEmail: (
+    userId: string,
+    ctx: { db: unknown; tenantId: TenantId },
+  ) => Promise<string | null>;
+};
+
+export function createEmailChannel(options: EmailChannelOptions): DeliveryChannel {
+  const { transport, renderer, resolveEmail } = options;
+
+  return {
+    name: "email",
+
+    async resolve(userId, ctx) {
+      return resolveEmail(userId, ctx);
+    },
+
+    async send(address, message, _ctx) {
+      // Build renderer input: per-channel template data (if any) or fall back
+      // to title/body from the message. Renderer handles both cases.
+      const variables = (message.data as DbRow) ?? {
+        title: message.title,
+        body: message.body,
+      };
+
+      const html = await renderer.render({
+        template: message.notificationType,
+        variables,
+      });
+      const subject = (variables["subject"] as string) ?? message.title;
+
+      await transport.send({
+        to: address,
+        subject,
+        html,
+      });
+
+      return { status: "sent", address };
+    },
+  };
+}

package/src/channel-email/feature.ts

@@ -0,0 +1,15 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createEmailChannel, type EmailChannelOptions } from "./email-channel";
+
+export function createChannelEmailFeature(options: EmailChannelOptions): FeatureDefinition {
+  const channel = createEmailChannel(options);
+
+  return defineFeature("channelEmail", (r) => {
+    r.requires("delivery");
+
+    r.useExtension("deliveryChannel", "email", {
+      resolve: channel.resolve,
+      send: channel.send,
+    });
+  });
+}

package/src/channel-email/index.ts

@@ -0,0 +1,4 @@
+export { createEmailChannel, type EmailChannelOptions } from "./email-channel";
+export { createChannelEmailFeature } from "./feature";
+export { createSmtpTransport, type SmtpTransportOptions } from "./smtp-transport";
+export { createInMemoryTransport, type EmailMessage, type EmailTransport } from "./types";

package/src/channel-email/smtp-transport.ts

@@ -0,0 +1,65 @@
+// SMTP-Transport für EmailTransport-Interface. nodemailer-basiert
+// (battle-tested, TLS-AUTH-Pool-Reconnect handled). Universaler default
+// für apps die keinen Vendor-spezifischen Sender wollen — funktioniert
+// gegen jeden SMTP-Server (Gmail, eigener Postfix, Brevo-SMTP-relay,
+// Office 365, Mailhog für lokales testing).
+//
+// Why SMTP statt Vendor-API als default:
+//   1. EU-Story: kein Daten an US-Vendor, App-Owner wählt Server.
+//   2. Self-Hosting: Customer kann eigenen Mailserver nutzen, kein
+//      external account.
+//   3. Universalität: jeder Vendor (Brevo, Resend, Mailgun, Postmark)
+//      bietet auch SMTP — wer Brevo will, setzt Brevos SMTP-Credentials.
+//
+// Transport-Pool: nodemailer.createTransport({pool: true}) hält bis zu
+// 5 Verbindungen offen + reused. Bei kleinen Apps reicht das; für High-
+// Volume-Apps muss der Caller eine eigene Implementation mit
+// dedizierter Queue (BullMQ + retry) drüberlegen.
+
+import { createTransport, type Transporter } from "nodemailer";
+import type { EmailMessage, EmailTransport } from "./types";
+
+export type SmtpTransportOptions = {
+  /** SMTP-Server-Host (z.B. "smtp.gmail.com", "in-v3.mailjet.com",
+   *  "localhost" für Mailhog/MailCatcher in dev). */
+  readonly host: string;
+  /** Default 587 (STARTTLS). 465 für implicit-TLS, 25 für unencrypted
+   *  (nur lokal/intern, nie public). */
+  readonly port?: number;
+  /** TLS-Mode: true = implicit TLS auf port 465, false = STARTTLS auf
+   *  587 (oder plain auf 25). Default false (STARTTLS standard). */
+  readonly secure?: boolean;
+  /** Optional auth — manche internal-relays nehmen IP-whitelisting statt
+   *  Login. Wenn gesetzt, beide felder pflicht. */
+  readonly auth?: {
+    readonly user: string;
+    readonly pass: string;
+  };
+  /** Standard-From-Adresse für jede Mail. EmailMessage hat kein from-
+   *  Feld — die Auswahl gehört zur Transport-Konfig (App-weit, nicht
+   *  pro Mail). Format akzeptiert beides: "noreply@ex.com" oder
+   *  "Name <noreply@ex.com>". */
+  readonly from: string;
+};
+
+export function createSmtpTransport(options: SmtpTransportOptions): EmailTransport {
+  const transporter: Transporter = createTransport({
+    host: options.host,
+    port: options.port ?? 587,
+    secure: options.secure ?? false,
+    ...(options.auth && { auth: options.auth }),
+    pool: true,
+    maxConnections: 5,
+  });
+
+  return {
+    async send(message: EmailMessage): Promise<void> {
+      await transporter.sendMail({
+        from: options.from,
+        to: message.to,
+        subject: message.subject,
+        html: message.html,
+      });
+    },
+  };
+}

package/src/channel-email/types.ts

@@ -0,0 +1,34 @@
+// Transport interface — SMTP in prod, InMemory in tests
+export type EmailMessage = {
+  readonly to: string;
+  readonly subject: string;
+  readonly html: string;
+};
+
+export type EmailTransport = {
+  send(message: EmailMessage): Promise<void>;
+};
+
+// InMemory transport for testing — collects sent emails.
+// `failNext` lets a test simulate a transient SMTP failure without
+// rebuilding the whole stack: set it before a single `notify()` call and
+// the transport throws once, then auto-resets.
+export function createInMemoryTransport(): EmailTransport & {
+  readonly sent: EmailMessage[];
+  failNext: null | { message: string };
+} {
+  const sent: EmailMessage[] = [];
+  const transport = {
+    sent,
+    failNext: null as null | { message: string },
+    async send(message: EmailMessage) {
+      if (transport.failNext) {
+        const err = new Error(transport.failNext.message);
+        transport.failNext = null;
+        throw err;
+      }
+      sent.push(message);
+    },
+  };
+  return transport;
+}

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

@@ -0,0 +1,11 @@
+export const CHANNEL_IN_APP_FEATURE = "channelInApp" as const;
+
+export const InAppHandlers = {
+  markRead: "channel-in-app:write:mark-read",
+  markAllRead: "channel-in-app:write:mark-all-read",
+} as const;
+
+export const InAppQueries = {
+  inbox: "channel-in-app:query:inbox",
+  unreadCount: "channel-in-app:query:unread-count",
+} as const;

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

@@ -0,0 +1,30 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { inboxQuery } from "./handlers/inbox.query";
+import { markAllReadWrite } from "./handlers/mark-all-read.write";
+import { markReadWrite } from "./handlers/mark-read.write";
+import { unreadCountQuery } from "./handlers/unread-count.query";
+import { inAppChannel } from "./in-app-channel";
+
+export function createChannelInAppFeature(): FeatureDefinition {
+  return defineFeature("channelInApp", (r) => {
+    r.requires("delivery");
+
+    // Register as delivery channel via extension system
+    r.useExtension("deliveryChannel", "inApp", {
+      resolve: inAppChannel.resolve,
+      send: inAppChannel.send,
+    });
+
+    const handlers = {
+      markRead: r.writeHandler(markReadWrite),
+      markAllRead: r.writeHandler(markAllReadWrite),
+    };
+
+    const queries = {
+      inbox: r.queryHandler(inboxQuery),
+      unreadCount: r.queryHandler(unreadCountQuery),
+    };
+
+    return { handlers, queries };
+  });
+}