@cosmicdrift/kumiko-bundled-features 0.1.0

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

@@ -0,0 +1,422 @@
+// Pure unit tests for the enforce-cap helpers. Mocks ctx.db's
+// select-chains via tiny in-memory stubs so we hit every branch
+// without spinning up the test-stack — the real event-store +
+// dispatcher integration is exercised in cap-counter.integration.ts.
+
+import { describe, expect, test, vi } from "vitest";
+
+// Temporal: rely on the global ambient declaration from temporal-spec.
+// The framework polyfill is loaded by setupTestStack, but pure unit
+// tests (no stack) need a manual polyfill — vitest.setup.ts does that.
+import {
+  CAP_TOLERANCES,
+  CapExceededError,
+  currentCalendarMonthStartIso,
+  enforceCap,
+  enforceCapAndMaybeNotify,
+  enforceRollingCap,
+  enforceRollingCapAndMaybeNotify,
+} from "../enforce-cap";
+
+// --- Calendar-Period stub: db.select().from(...).where(...).limit(1) ---
+
+function stubCalendarCtx(rows: { value: number; lastSoftWarnedAt: unknown }[]) {
+  const ctx = {
+    db: {
+      select: () => ({
+        from: () => ({
+          where: () => ({
+            limit: async () => rows,
+          }),
+        }),
+      }),
+    },
+    user: { tenantId: "tenant-test" },
+  };
+  return ctx as unknown as Parameters<typeof enforceCap>[0];
+}
+
+// --- Rolling-Window stub: db.select(...).from(...).where(...) returns rows ---
+
+function stubRollingCtx(eventPayloads: { amount: number }[]) {
+  const ctx = {
+    db: {
+      select: () => ({
+        from: () => ({
+          where: async () => eventPayloads.map((p) => ({ payload: p })),
+        }),
+      }),
+    },
+    user: { tenantId: "tenant-test" },
+  };
+  return ctx as unknown as Parameters<typeof enforceRollingCap>[0];
+}
+
+const PERIOD = "2026-05-01T00:00:00Z";
+
+// =============================================================================
+// enforceCap — calendar-period
+// =============================================================================
+
+describe("enforceCap — burstable profile (mails / tokens)", () => {
+  const opts = {
+    capName: "mails-per-month",
+    periodStartIso: PERIOD,
+    limit: 1000,
+    profile: "burstable" as const,
+  };
+
+  test("value below soft-threshold → ok", async () => {
+    const ctx = stubCalendarCtx([{ value: 500, lastSoftWarnedAt: null }]);
+    const result = await enforceCap(ctx, opts);
+    expect(result.state).toBe("ok");
+    if (result.state === "ok") {
+      expect(result.value).toBe(500);
+    }
+  });
+
+  test("no row exists yet → value=0, ok", async () => {
+    const ctx = stubCalendarCtx([]);
+    const result = await enforceCap(ctx, opts);
+    expect(result.state).toBe("ok");
+    if (result.state === "ok") {
+      expect(result.value).toBe(0);
+    }
+  });
+
+  test("value at soft-threshold (1100, soft=1.1) → soft-hit, crossed=true on first warn", async () => {
+    const ctx = stubCalendarCtx([{ value: 1100, lastSoftWarnedAt: null }]);
+    const result = await enforceCap(ctx, opts);
+    expect(result.state).toBe("soft-hit");
+    if (result.state === "soft-hit") {
+      expect(result.value).toBe(1100);
+      expect(result.crossed).toBe(true);
+    }
+  });
+
+  test("value past soft, already warned → soft-hit, crossed=false (no re-notification)", async () => {
+    const ctx = stubCalendarCtx([{ value: 1150, lastSoftWarnedAt: "2026-05-15T12:00:00Z" }]);
+    const result = await enforceCap(ctx, opts);
+    expect(result.state).toBe("soft-hit");
+    if (result.state === "soft-hit") {
+      expect(result.crossed).toBe(false);
+    }
+  });
+
+  test("value at hard-threshold (1200, hard=1.2) → throws CapExceededError", async () => {
+    const ctx = stubCalendarCtx([{ value: 1200, lastSoftWarnedAt: null }]);
+    await expect(enforceCap(ctx, opts)).rejects.toThrow(CapExceededError);
+  });
+
+  test("CapExceededError carries cap-name + limit + currentValue", async () => {
+    const ctx = stubCalendarCtx([{ value: 1500, lastSoftWarnedAt: null }]);
+    try {
+      await enforceCap(ctx, opts);
+      throw new Error("expected throw");
+    } catch (e) {
+      expect(e).toBeInstanceOf(CapExceededError);
+      const err = e as CapExceededError;
+      expect(err.code).toBe("cap_exceeded");
+      expect(err.capName).toBe("mails-per-month");
+      expect(err.limit).toBe(1000);
+      expect(err.currentValue).toBe(1500);
+    }
+  });
+});
+
+describe("enforceCap — storage profile (DB / files)", () => {
+  test("storage profile is stricter — soft@100% hard@105%", async () => {
+    expect(CAP_TOLERANCES.storage.soft).toBe(1.0);
+    expect(CAP_TOLERANCES.storage.hard).toBe(1.05);
+  });
+
+  test("at exactly limit (storage soft=1.0) → soft-hit", async () => {
+    const ctx = stubCalendarCtx([{ value: 10240, lastSoftWarnedAt: null }]);
+    const result = await enforceCap(ctx, {
+      capName: "db-storage-mb",
+      periodStartIso: PERIOD,
+      limit: 10240,
+      profile: "storage",
+    });
+    expect(result.state).toBe("soft-hit");
+  });
+
+  test("at 1.05× limit (storage hard) → throws", async () => {
+    const ctx = stubCalendarCtx([{ value: 10752, lastSoftWarnedAt: null }]);
+    await expect(
+      enforceCap(ctx, {
+        capName: "db-storage-mb",
+        periodStartIso: PERIOD,
+        limit: 10240,
+        profile: "storage",
+      }),
+    ).rejects.toThrow(CapExceededError);
+  });
+});
+
+describe("enforceCap — hardSlot profile (apps-count)", () => {
+  test("hardSlot has zero buffer — hard@100%", async () => {
+    expect(CAP_TOLERANCES.hardSlot.hard).toBe(1.0);
+  });
+
+  test("at exactly limit → throws (hardSlot is hard)", async () => {
+    const ctx = stubCalendarCtx([{ value: 5, lastSoftWarnedAt: null }]);
+    await expect(
+      enforceCap(ctx, {
+        capName: "apps-count",
+        periodStartIso: PERIOD,
+        limit: 5,
+        profile: "hardSlot",
+      }),
+    ).rejects.toThrow(CapExceededError);
+  });
+});
+
+describe("enforceCap — egress profile", () => {
+  test("egress has the largest hard-buffer (130%) — bursty traffic legitimate", async () => {
+    expect(CAP_TOLERANCES.egress.hard).toBe(1.3);
+  });
+});
+
+// =============================================================================
+// enforceRollingCap — Sprint 4: window-based read über Increment-Events
+// =============================================================================
+
+describe("enforceRollingCap — burstable profile (KI-tokens-7d)", () => {
+  // limit=10000 chosen weil 10000 × 1.1 = 11000 und × 1.2 = 12000 als
+  // exact integer floating-point bleiben (50000 × 1.1 wäre 55000.00000000001).
+  const opts = {
+    capName: "ai-tokens-7d",
+    windowDays: 7,
+    limit: 10000,
+    profile: "burstable" as const,
+  };
+
+  test("no events in window → value=0, ok", async () => {
+    const ctx = stubRollingCtx([]);
+    const result = await enforceRollingCap(ctx, opts);
+    expect(result.state).toBe("ok");
+    if (result.state === "ok") {
+      expect(result.value).toBe(0);
+    }
+  });
+
+  test("sums amounts across multiple events", async () => {
+    const ctx = stubRollingCtx([{ amount: 1000 }, { amount: 2500 }, { amount: 500 }]);
+    const result = await enforceRollingCap(ctx, opts);
+    expect(result.state).toBe("ok");
+    if (result.state === "ok") {
+      expect(result.value).toBe(4000);
+    }
+  });
+
+  test("sum at soft-threshold (11000, soft=1.1×10000) → soft-hit, crossed=false", async () => {
+    const ctx = stubRollingCtx([{ amount: 6000 }, { amount: 5000 }]);
+    const result = await enforceRollingCap(ctx, opts);
+    expect(result.state).toBe("soft-hit");
+    if (result.state === "soft-hit") {
+      expect(result.value).toBe(11000);
+      // Rolling-counter trackt kein lastSoftWarnedAt — crossed ist immer false.
+      expect(result.crossed).toBe(false);
+    }
+  });
+
+  test("sum at hard-threshold (12000, hard=1.2×10000) → throws CapExceededError", async () => {
+    const ctx = stubRollingCtx([{ amount: 6000 }, { amount: 6000 }]);
+    await expect(enforceRollingCap(ctx, opts)).rejects.toThrow(CapExceededError);
+  });
+
+  test("ignores malformed payloads (no `amount` field) — defensive against schema-drift", async () => {
+    // Sums only the well-formed events. If a future event-shape lands
+    // with a different field name, we don't blow up — just under-count.
+    const ctx = stubRollingCtx([
+      { amount: 1000 },
+      // @ts-expect-error — testing defensive read
+      { other: 9999 },
+      { amount: 2000 },
+    ]);
+    const result = await enforceRollingCap(ctx, opts);
+    expect(result.state).toBe("ok");
+    if (result.state === "ok") {
+      expect(result.value).toBe(3000);
+    }
+  });
+});
+
+describe("enforceRollingCap — input validation", () => {
+  test("missing ctx.db → throws clear error", async () => {
+    const ctx = { user: { tenantId: "t" } } as unknown as Parameters<typeof enforceRollingCap>[0];
+    await expect(
+      enforceRollingCap(ctx, {
+        capName: "x",
+        windowDays: 7,
+        limit: 1,
+        profile: "burstable",
+      }),
+    ).rejects.toThrow(/ctx\.db missing/);
+  });
+
+  test("missing ctx.user.tenantId → throws clear error", async () => {
+    const ctx = stubRollingCtx([]);
+    delete (ctx as { user?: unknown }).user;
+    await expect(
+      enforceRollingCap(ctx, {
+        capName: "x",
+        windowDays: 7,
+        limit: 1,
+        profile: "burstable",
+      }),
+    ).rejects.toThrow(/tenantId missing/);
+  });
+});
+
+// =============================================================================
+// enforceCapAndMaybeNotify — Calendar + Notification-Wiring
+// =============================================================================
+
+describe("enforceCapAndMaybeNotify — calendar", () => {
+  const baseOpts = {
+    capName: "mails-per-month",
+    periodStartIso: PERIOD,
+    limit: 1000,
+    profile: "burstable" as const,
+  };
+
+  test("ok → notifier NICHT aufgerufen", async () => {
+    const ctx = stubCalendarCtx([{ value: 100, lastSoftWarnedAt: null }]);
+    const notify = vi.fn();
+    const result = await enforceCapAndMaybeNotify(ctx, { ...baseOpts, notify });
+    expect(result.state).toBe("ok");
+    expect(notify).not.toHaveBeenCalled();
+  });
+
+  test("soft-hit, crossed=true → notifier mit info-payload + ctx.write markSoftWarned", async () => {
+    const ctx = stubCalendarCtx([{ value: 1100, lastSoftWarnedAt: null }]);
+    const write = vi.fn(async () => ({ isSuccess: true, data: {} }));
+    (ctx as unknown as { write: typeof write }).write = write;
+    const notify = vi.fn();
+
+    const result = await enforceCapAndMaybeNotify(ctx, { ...baseOpts, notify });
+    expect(result.state).toBe("soft-hit");
+    expect(notify).toHaveBeenCalledExactlyOnceWith({
+      capName: "mails-per-month",
+      value: 1100,
+      limit: 1000,
+      tenantId: "tenant-test",
+    });
+    expect(write).toHaveBeenCalledExactlyOnceWith("cap-counter:write:mark-soft-warned", {
+      capName: "mails-per-month",
+      periodStartIso: PERIOD,
+    });
+  });
+
+  test("soft-hit, crossed=false (already warned) → notifier NICHT erneut aufgerufen", async () => {
+    const ctx = stubCalendarCtx([{ value: 1150, lastSoftWarnedAt: "2026-05-15T12:00:00Z" }]);
+    const notify = vi.fn();
+    const result = await enforceCapAndMaybeNotify(ctx, { ...baseOpts, notify });
+    expect(result.state).toBe("soft-hit");
+    expect(notify).not.toHaveBeenCalled();
+  });
+
+  test("hard-hit → throws CapExceededError BEVOR notifier feuert", async () => {
+    const ctx = stubCalendarCtx([{ value: 1500, lastSoftWarnedAt: null }]);
+    const notify = vi.fn();
+    await expect(enforceCapAndMaybeNotify(ctx, { ...baseOpts, notify })).rejects.toThrow(
+      CapExceededError,
+    );
+    expect(notify).not.toHaveBeenCalled();
+  });
+});
+
+// =============================================================================
+// enforceRollingCapAndMaybeNotify — Rolling + Notification (no dedup)
+// =============================================================================
+
+describe("enforceRollingCapAndMaybeNotify — rolling", () => {
+  const baseOpts = {
+    capName: "ai-tokens-7d",
+    windowDays: 7,
+    limit: 10000,
+    profile: "burstable" as const,
+  };
+
+  test("ok → notifier NICHT aufgerufen", async () => {
+    const ctx = stubRollingCtx([{ amount: 100 }]);
+    const notify = vi.fn();
+    const result = await enforceRollingCapAndMaybeNotify(ctx, { ...baseOpts, notify });
+    expect(result.state).toBe("ok");
+    expect(notify).not.toHaveBeenCalled();
+  });
+
+  test("soft-hit → notifier feuert (ohne dedup, Caller-Verantwortung)", async () => {
+    const ctx = stubRollingCtx([{ amount: 6000 }, { amount: 5000 }]);
+    const notify = vi.fn();
+    const result = await enforceRollingCapAndMaybeNotify(ctx, { ...baseOpts, notify });
+    expect(result.state).toBe("soft-hit");
+    expect(notify).toHaveBeenCalledExactlyOnceWith({
+      capName: "ai-tokens-7d",
+      value: 11000,
+      limit: 10000,
+      tenantId: "tenant-test",
+    });
+  });
+
+  test("zwei aufeinanderfolgende soft-hit-Calls → notifier 2× (kein Dedup)", async () => {
+    // Drift-Pin: rolling-counter trackt KEIN lastSoftWarnedAt; Caller
+    // muss selbst dedup'en (Cache-Eintrag, Hourly-Cron etc.). Wenn
+    // ein Refactor heimlich Dedup einbaut ohne projection-row, fällt
+    // das hier auf.
+    const ctx = stubRollingCtx([{ amount: 11000 }]);
+    const notify = vi.fn();
+    await enforceRollingCapAndMaybeNotify(ctx, { ...baseOpts, notify });
+    await enforceRollingCapAndMaybeNotify(ctx, { ...baseOpts, notify });
+    expect(notify).toHaveBeenCalledTimes(2);
+  });
+});
+
+// =============================================================================
+// Period-Helpers
+// =============================================================================
+
+describe("currentCalendarMonthStartIso", () => {
+  test("returns 1st of month at 00:00 UTC, ISO format", () => {
+    const midMay = Temporal.Instant.from("2026-05-15T14:32:11Z");
+    const result = currentCalendarMonthStartIso(midMay);
+    expect(result).toBe("2026-05-01T00:00:00Z");
+  });
+});
+
+// =============================================================================
+// Aggregate-ID drift-pins — Namespace-Wechsel würde tenant-stored
+// Counter-History komplett re-keyen. Pinning der UUIDs.
+// =============================================================================
+
+describe("aggregate-id namespaces — drift-pin", () => {
+  test("calendar capCounterAggregateId stable für (tenant, capName, period)", async () => {
+    const { capCounterAggregateId } = await import("../aggregate-id");
+    expect(capCounterAggregateId("tenant-1", "cap-x", "2026-05-01T00:00:00Z")).toBe(
+      "2e74a706-7cc1-51ca-a1a7-89e5c5bccb7e",
+    );
+  });
+
+  test("rolling rollingCapAggregateId stable für (tenant, capName)", async () => {
+    const { rollingCapAggregateId } = await import("../aggregate-id");
+    // Pinne den exakten UUID-output. Wenn jemand den Namespace-uuid in
+    // aggregate-id.ts ändert, kollabiert die ganze rolling-counter-
+    // history des Tenants — Test fängt's vor dem Deploy.
+    expect(rollingCapAggregateId("tenant-1", "ai-tokens-7d")).toBe(
+      "7d3dc5df-561f-555f-96d7-e9542d0de679",
+    );
+  });
+
+  test("calendar und rolling produzieren UNTERSCHIEDLICHE UUIDs für gleiches Tupel", async () => {
+    const { capCounterAggregateId, rollingCapAggregateId } = await import("../aggregate-id");
+    // Selbst wenn jemand "1970-01-01..." als periodStart in den
+    // calendar-Pfad reinpasst, soll die UUID NICHT mit dem rolling-
+    // aggregate kollidieren — sonst würden sich die beiden Streams
+    // vermischen und Counter wären falsch.
+    const calendarId = capCounterAggregateId("tenant-1", "ai-tokens-7d", "1970-01-01T00:00:00Z");
+    const rollingId = rollingCapAggregateId("tenant-1", "ai-tokens-7d");
+    expect(calendarId).not.toBe(rollingId);
+  });
+});

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

@@ -0,0 +1,265 @@
+// Integration-test for withCapEnforcement / withRollingCapEnforcement.
+// Beweist die Wrapper-Verdrahtung end-to-end:
+//   1. Pre-call: enforceCapAndMaybeNotify dispatched (notifier feuert,
+//      mark-soft-warned-handler kippt das DB-Flag)
+//   2. Handler runs — only when below hard-cap
+//   3. Post-success: ctx.write(increment) — counter steigt um `amount`
+//   4. Hard-hit: handler runs NICHT, counter NICHT inkrementiert
+//   5. Failed handler: counter NICHT inkrementiert (cap-quota nicht
+//      verbrannt für gescheiterte writes)
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createEntityTable,
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { CapCounterQueries } from "../constants";
+import type { SoftHitNotifier } from "../enforce-cap";
+import { capCounterEntity } from "../entity";
+import { capCounterFeature } from "../feature";
+import { withCapEnforcement, withRollingCapEnforcement } from "../with-cap-enforcement";
+
+// =============================================================================
+// Test-Probe — newsletter-send-Handler with cap-enforcement
+// =============================================================================
+//
+// Module-level state für die Tests:
+//   - sendCallCount: wie oft der gewrappte Handler tatsächlich gerufen wurde
+//     (Drift-Pin: bei hard-hit darf das NICHT inkrementieren)
+//   - recordedNotifications: Notifier-callback firings
+//   - failNextSend: simuliert handler-Fehler — Drift-Pin: Counter darf
+//     bei failure nicht inkrementieren
+let sendCallCount = 0;
+let failNextSend = false;
+const recordedNotifications: Array<{ capName: string; value: number }> = [];
+const recordingNotifier: SoftHitNotifier = (info) => {
+  recordedNotifications.push({ capName: info.capName, value: info.value });
+};
+
+const innerSendHandler: WriteHandlerDef = {
+  name: "send-newsletter",
+  schema: z.object({ to: z.string() }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  handler: async (_event, _ctx) => {
+    sendCallCount += 1;
+    if (failNextSend) {
+      failNextSend = false;
+      throw new Error("send-failed-on-purpose");
+    }
+    return { isSuccess: true as const, data: { sent: true } };
+  },
+};
+
+const PERIOD = "2026-07-01T00:00:00Z";
+
+const wrappedCalendar = withCapEnforcement(innerSendHandler, () => ({
+  capName: "newsletter-cap",
+  periodStartIso: PERIOD,
+  limit: 5,
+  profile: "burstable",
+  notify: recordingNotifier,
+}));
+
+const wrappedRolling = withRollingCapEnforcement(
+  { ...innerSendHandler, name: "send-rolling" },
+  () => ({
+    capName: "newsletter-rolling-cap",
+    windowDays: 7,
+    limit: 5,
+    profile: "burstable",
+    notify: recordingNotifier,
+  }),
+);
+
+const NEWSLETTER_QN = "newsletter:write:send-newsletter";
+const NEWSLETTER_ROLLING_QN = "newsletter:write:send-rolling";
+const newsletterFeature = defineFeature("newsletter", (r) => {
+  r.writeHandler(wrappedCalendar);
+  r.writeHandler(wrappedRolling);
+});
+
+// =============================================================================
+// Setup
+// =============================================================================
+
+let stack: TestStack;
+let db: DbConnection;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [capCounterFeature, newsletterFeature] });
+  db = stack.db;
+  await createEntityTable(db, capCounterEntity);
+  await createEventsTable(db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function adminFor(tenantNumber: number) {
+  return createTestUser({
+    id: tenantNumber,
+    tenantId: testTenantId(tenantNumber),
+    roles: ["TenantAdmin", "SystemAdmin"],
+  });
+}
+
+async function readCounter(user: ReturnType<typeof adminFor>, capName: string, period: string) {
+  return (await stack.http.queryOk(
+    CapCounterQueries.getCounter,
+    { capName, periodStartIso: period },
+    user,
+  )) as Record<string, unknown> | null;
+}
+
+function resetState() {
+  sendCallCount = 0;
+  failNextSend = false;
+  recordedNotifications.length = 0;
+}
+
+// =============================================================================
+// Calendar-wrapper scenarios
+// =============================================================================
+
+describe("withCapEnforcement — calendar", () => {
+  test("under-cap: handler läuft, counter inkrementiert um 1 pro success", async () => {
+    resetState();
+    const admin = adminFor(1201);
+
+    await stack.http.writeOk(NEWSLETTER_QN, { to: "a@x.de" }, admin);
+    await stack.http.writeOk(NEWSLETTER_QN, { to: "b@x.de" }, admin);
+    await stack.http.writeOk(NEWSLETTER_QN, { to: "c@x.de" }, admin);
+
+    expect(sendCallCount).toBe(3);
+    const row = await readCounter(admin, "newsletter-cap", PERIOD);
+    expect(row).not.toBeNull();
+    expect(row!["value"]).toBe(3);
+    expect(recordedNotifications).toHaveLength(0);
+  });
+
+  test("hard-hit: handler läuft NICHT, counter NICHT weiter inkrementiert", async () => {
+    resetState();
+    const admin = adminFor(1203);
+    // limit=5, soft=1.1×5=5.5, hard=1.2×5=6. Da Counter int ist, springt
+    // value(5)→6 direkt in den hard-Bereich (keine intermediate soft-zone
+    // bei limit=5). Soft-hit-Verhalten ist im enforce-cap-Integration-Test
+    // mit limit=1000 schon gepinnt; hier liegt der Fokus auf hard-block.
+    for (let i = 0; i < 6; i++) {
+      await stack.http.writeOk(NEWSLETTER_QN, { to: `${i}@x.de` }, admin);
+    }
+    expect(sendCallCount).toBe(6);
+    const beforeBlocked = await readCounter(admin, "newsletter-cap", PERIOD);
+    expect(beforeBlocked!["value"]).toBe(6);
+
+    // 7. send: pre-call sieht value=6 ≥ hard=6 → CapExceededError, der
+    // dispatcher wickelt's als internal_error mit causeName=CapExceededError.
+    const error = await stack.http.writeErr(NEWSLETTER_QN, { to: "blocked@x.de" }, admin);
+    expect(JSON.stringify(error)).toMatch(/CapExceededError/);
+
+    // Drift-Pin: handler darf NICHT gelaufen sein (sendCallCount unverändert)
+    expect(sendCallCount).toBe(6);
+    // Drift-Pin: counter NICHT weiter inkrementiert (immer noch 6)
+    const afterBlocked = await readCounter(admin, "newsletter-cap", PERIOD);
+    expect(afterBlocked!["value"]).toBe(6);
+  });
+
+  test("failed handler: counter NICHT inkrementiert (cap-quota nicht verbrannt)", async () => {
+    resetState();
+    const admin = adminFor(1204);
+
+    // Erster send: success, counter → 1
+    await stack.http.writeOk(NEWSLETTER_QN, { to: "first@x.de" }, admin);
+    expect(sendCallCount).toBe(1);
+
+    // Zweiter send schlägt fehl im inner-handler (failNextSend=true).
+    // Wrapper soll NICHT inkrementieren.
+    failNextSend = true;
+    await stack.http.writeErr(NEWSLETTER_QN, { to: "fail@x.de" }, admin);
+    expect(sendCallCount).toBe(2);
+
+    // Counter bleibt bei 1 — der gescheiterte send hat keine quota verbrannt.
+    const row = await readCounter(admin, "newsletter-cap", PERIOD);
+    expect(row!["value"]).toBe(1);
+  });
+});
+
+// =============================================================================
+// Rolling-wrapper scenarios — kürzer, weil Notification-Wiring + base-flow
+// schon vom calendar-Test abgedeckt sind.
+// =============================================================================
+
+describe("withRollingCapEnforcement — rolling", () => {
+  test("under-cap: handler läuft, increment-rolling-events accumulieren", async () => {
+    resetState();
+    const admin = adminFor(1301);
+
+    await stack.http.writeOk(NEWSLETTER_ROLLING_QN, { to: "a@x.de" }, admin);
+    await stack.http.writeOk(NEWSLETTER_ROLLING_QN, { to: "b@x.de" }, admin);
+    expect(sendCallCount).toBe(2);
+    // Read via enforceRollingCap — kein direct-getter, aber wir können
+    // einen weiteren write absetzen und das Ergebnis prüfen ist
+    // upstream. Wichtig: handler ist aufgerufen.
+  });
+
+  test("hard-hit: rolling-counter blockiert weitere sends", async () => {
+    resetState();
+    const admin = adminFor(1302);
+
+    // limit=5, soft=5.5, hard=6. 6 sends bringen value=6 → 7. send blockiert.
+    for (let i = 0; i < 6; i++) {
+      await stack.http.writeOk(NEWSLETTER_ROLLING_QN, { to: `${i}@x.de` }, admin);
+    }
+    expect(sendCallCount).toBe(6);
+
+    const error = await stack.http.writeErr(NEWSLETTER_ROLLING_QN, { to: "blocked@x.de" }, admin);
+    expect(JSON.stringify(error)).toMatch(/CapExceededError/);
+    expect(sendCallCount).toBe(6); // handler wurde NICHT erneut aufgerufen
+  });
+
+  test("failed handler: kein increment-rolling-event hinzugefügt (cap-quota nicht verbrannt)", async () => {
+    // Symmetrisch zum calendar-Test "failed handler: counter NICHT
+    // inkrementiert". Beweist dass der rolling-Wrapper denselben
+    // Atomicity-Vertrag erfüllt: nur erfolgreiche handler verbrennen
+    // quota.
+    resetState();
+    const admin = adminFor(1303);
+
+    // 1. send: success → increment-rolling-event #1
+    await stack.http.writeOk(NEWSLETTER_ROLLING_QN, { to: "first@x.de" }, admin);
+    expect(sendCallCount).toBe(1);
+
+    // 2. send: handler wirft → kein increment-rolling-event
+    failNextSend = true;
+    await stack.http.writeErr(NEWSLETTER_ROLLING_QN, { to: "fail@x.de" }, admin);
+    expect(sendCallCount).toBe(2);
+
+    // 3. send: success → increment-rolling-event #2 (Drift-Pin: counter
+    // steht bei 2, NICHT bei 3 — der gescheiterte send #2 hat keine
+    // quota verbrannt). Wir treiben den counter bis genau hard-1, das
+    // funktioniert NUR wenn #2 nicht gezählt wurde.
+    for (let i = 0; i < 4; i++) {
+      await stack.http.writeOk(NEWSLETTER_ROLLING_QN, { to: `s-${i}@x.de` }, admin);
+    }
+    expect(sendCallCount).toBe(6);
+
+    // 7. send (= hard@6): blockiert. counter steht bei 5 (1 + 4),
+    // pre-call sieht 5 < hard@6 → handler läuft + increment, counter
+    // steigt auf 6. Direkt danach blockiert der nächste send.
+    // Wenn der gescheiterte send fälschlich gezählt hätte, wäre der
+    // counter schon bei 6 und der jetzt-erlaubte send würde blockieren.
+    await stack.http.writeOk(NEWSLETTER_ROLLING_QN, { to: "last-allowed@x.de" }, admin);
+    expect(sendCallCount).toBe(7);
+
+    const blocked = await stack.http.writeErr(NEWSLETTER_ROLLING_QN, { to: "blocked@x.de" }, admin);
+    expect(JSON.stringify(blocked)).toMatch(/CapExceededError/);
+    expect(sendCallCount).toBe(7); // wrapper hat den blockierten handler NICHT gerufen
+  });
+});