@cosmicdrift/kumiko-bundled-features 0.350.0 → 0.352.0

package/dist/cap-counter/constants.js

@@ -16,6 +16,12 @@ export const CAP_COUNTER_ROLLING_AGGREGATE_TYPE = "cap-counter-rolling";
 // Beide MÜSSEN konsistent sein (drift-pin im feature-test).
 export const ROLLING_INCREMENTED_EVENT_SHORT = "rolling-incremented";
 export const ROLLING_INCREMENTED_EVENT_QN = "cap-counter:event:rolling-incremented";
+// Gives back a reserved rolling amount; the window sum is incremented minus released.
+export const ROLLING_RELEASED_EVENT_SHORT = "rolling-released";
+export const ROLLING_RELEASED_EVENT_QN = "cap-counter:event:rolling-released";
+// A reservation row older than this is treated as a lost release and given back before the next
+// reservation for the same cap, which bounds the over-count a failed release can leave behind.
+export const CAP_RESERVATION_TTL_MINUTES = 60;
 // Qualified write handler names (QN format: scope:type:name).
 export const CapCounterHandlers = {
     increment: "cap-counter:write:increment",

package/dist/cap-counter/enforce-cap.d.ts

@@ -1,6 +1,6 @@
-/// <reference types="temporal-polyfill/global" preserve="true" />
 import { type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { KumikoError } from "@cosmicdrift/kumiko-framework/errors";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 /**
  * Cap-Toleranz-Profile — pro Cap-Typ asymmetrisch. Quelle: Memory
  * `project_pricing_byok_caps` §3 + `docs/plans/marketing/produkt/

package/dist/cap-counter/enforce-cap.js

@@ -1,15 +1,8 @@
-/// <reference types="temporal-polyfill/global" preserve="true" />
 import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
 import { KumikoError, reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { markCapSoftWarned, readRollingCapUsage } from "./book-cap-usage.js";
 import { capCounterEntity } from "./entity.js";
-// Temporal globally provided by the framework's polyfill init
-// (ensureTemporalPolyfill() in time/polyfill.ts, called from
-// setupTestStack/boot). Importing from "temporal-polyfill" gives us
-// the polyfill-package types which don't quite match drizzle's
-// `instant()`-customType (temporal-spec narrowing of `until(...).sign`).
-// Mirror the audit-handler pattern: rely on the global ambient
-// declaration from temporal-spec.
 const { table } = createEntityExecutor("cap-counter", capCounterEntity);
 export const CAP_TOLERANCES = {
     /** Mails / Tokens — billig, BYOK ab Pro. Burst-Buffer großzügig. */

package/dist/cap-counter/feature.js

@@ -45,13 +45,14 @@
 // config, kein secrets, kein tenant-feature nötig. Tenant-Scoping kommt
 // vom Framework-Default (Base-Column tenantId).
 import { access, defineEntityListHandler, defineFeature, } from "@cosmicdrift/kumiko-framework/engine";
-import { CAP_COUNTER_FEATURE, CAP_COUNTER_LIST_SCREEN_ID, ROLLING_INCREMENTED_EVENT_SHORT, } from "./constants.js";
+import { CAP_COUNTER_FEATURE, CAP_COUNTER_LIST_SCREEN_ID, ROLLING_INCREMENTED_EVENT_SHORT, ROLLING_RELEASED_EVENT_SHORT, } from "./constants.js";
 import { capCounterEntity } from "./entity.js";
 import { getCounterQuery } from "./handlers/get-counter.query.js";
 import { incrementCapHandler } from "./handlers/increment.write.js";
-import { incrementRollingCapHandler, rollingIncrementedSchema, } from "./handlers/increment-rolling.write.js";
+import { incrementRollingCapHandler, rollingIncrementedSchema, rollingReleasedSchema, } from "./handlers/increment-rolling.write.js";
 import { markSoftWarnedHandler } from "./handlers/mark-soft-warned.write.js";
 import { CAP_COUNTER_I18N } from "./i18n.js";
+import { capReservationsTableMeta } from "./tables.js";
 export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
     r.describe("Tracks per-tenant usage against configurable limits using two complementary storage models: calendar-period counters (one projection row per tenant/capName/period, reset implicitly by period rollover) and rolling-window counters (append-only event stream, no projection). Use `enforceCap` / `enforceRollingCap` (or the `withCapEnforcement` / `withRollingCapEnforcement` handler wrappers) in your write-handlers to check limits with soft-warn and hard-block tolerances; call `enforceCapAndMaybeNotify` when you also want to trigger a delivery notification on soft-threshold hits.");
     r.uiHints({
@@ -60,12 +61,16 @@ export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
         recommended: false,
     });
     r.entity("cap-counter", capCounterEntity);
+    r.storeTable(capReservationsTableMeta, {
+        reason: "coordination.cap_reservation_ledger",
+    });
     // Custom Domain-Event für Rolling-Counter. r.defineEvent registriert
     // das Schema beim Registry; ctx.unsafeAppendEvent im Handler nutzt
     // dasselbe Schema für Append-Time-Validation. QN nach Prefixing:
     // "cap-counter:event:rolling-incremented" (siehe
     // ROLLING_INCREMENTED_EVENT_QN).
     r.defineEvent(ROLLING_INCREMENTED_EVENT_SHORT, rollingIncrementedSchema, { piiFields: "none" });
+    r.defineEvent(ROLLING_RELEASED_EVENT_SHORT, rollingReleasedSchema, { piiFields: "none" });
     // Custom write-handlers.
     // - increment: Calendar-Period (CRUD via projection-row).
     // - increment-rolling: Rolling-Window (Custom-Event, no projection).

package/dist/cap-counter/handlers/increment-rolling.write.d.ts

@@ -6,4 +6,9 @@ export declare const rollingIncrementedSchema: z.ZodObject<{
     capName: z.ZodString;
     amount: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
+/** Payload of the event that gives a reserved rolling amount back. */
+export declare const rollingReleasedSchema: z.ZodObject<{
+    capName: z.ZodString;
+    amount: z.ZodNumber;
+}, z.core.$strip>;
 export declare const incrementRollingCapHandler: WriteHandlerDef;

package/dist/cap-counter/handlers/increment-rolling.write.js

@@ -31,6 +31,10 @@ const incrementRollingSchema = z.object({
 /** 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;
+/** Payload of the event that gives a reserved rolling amount back. */
+export const rollingReleasedSchema = incrementRollingSchema.extend({
+    amount: z.number().int().positive(),
+});
 // 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.

package/dist/cap-counter/index.d.ts

@@ -1,8 +1,10 @@
 export { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id.js";
 export { type BookCapUsageOptions, bookCapUsage, type MarkCapSoftWarnedOptions, markCapSoftWarned, type ReadRollingCapUsageOptions, readRollingCapUsage, } from "./book-cap-usage.js";
-export { CAP_COUNTER_FEATURE, CAP_COUNTER_ROLLING_AGGREGATE_TYPE, CapCounterHandlers, CapCounterQueries, ROLLING_INCREMENTED_EVENT_QN, ROLLING_INCREMENTED_EVENT_SHORT, } from "./constants.js";
+export { CAP_COUNTER_FEATURE, CAP_COUNTER_ROLLING_AGGREGATE_TYPE, CapCounterHandlers, CapCounterQueries, ROLLING_INCREMENTED_EVENT_QN, ROLLING_INCREMENTED_EVENT_SHORT, ROLLING_RELEASED_EVENT_QN, ROLLING_RELEASED_EVENT_SHORT, } from "./constants.js";
 export { CAP_TOLERANCES, CapExceededError, type CapToleranceProfile, type CapToleranceProfileName, currentCalendarMonthStartIso, type EnforceCapResult, enforceCap, enforceCapAndMaybeNotify, enforceRollingCap, enforceRollingCapAndMaybeNotify, enforceStockCap, type SoftHitNotifier, type StockCapResult, } from "./enforce-cap.js";
 export { capCounterEntity } from "./entity.js";
 export { capCounterFeature } from "./feature.js";
-export { type CapLimitContext, createStockCapGuard, type StockCapGuard, type StockCapSpec, } from "./stock-cap-guard.js";
+export { readPayloadField } from "./payload-field.js";
+export { type CapGuardContext, type CapLimitContext, createStockCapGuard, type StockCapGuard, type StockCapSpec, } from "./stock-cap-guard.js";
+export { createValueCapGuard, type ValueCapGuard, type ValueCapSpec, } from "./value-cap-guard.js";
 export { type CalendarCapDef, type CalendarCapResolver, type RollingCapDef, type RollingCapResolver, withCapEnforcement, withRollingCapEnforcement, } from "./with-cap-enforcement.js";

package/dist/cap-counter/index.js

@@ -1,9 +1,11 @@
 // Public API of the cap-counter bundled-feature.
 export { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id.js";
 export { bookCapUsage, markCapSoftWarned, readRollingCapUsage, } from "./book-cap-usage.js";
-export { CAP_COUNTER_FEATURE, CAP_COUNTER_ROLLING_AGGREGATE_TYPE, CapCounterHandlers, CapCounterQueries, ROLLING_INCREMENTED_EVENT_QN, ROLLING_INCREMENTED_EVENT_SHORT, } from "./constants.js";
+export { CAP_COUNTER_FEATURE, CAP_COUNTER_ROLLING_AGGREGATE_TYPE, CapCounterHandlers, CapCounterQueries, ROLLING_INCREMENTED_EVENT_QN, ROLLING_INCREMENTED_EVENT_SHORT, ROLLING_RELEASED_EVENT_QN, ROLLING_RELEASED_EVENT_SHORT, } from "./constants.js";
 export { CAP_TOLERANCES, CapExceededError, currentCalendarMonthStartIso, enforceCap, enforceCapAndMaybeNotify, enforceRollingCap, enforceRollingCapAndMaybeNotify, enforceStockCap, } from "./enforce-cap.js";
 export { capCounterEntity } from "./entity.js";
 export { capCounterFeature } from "./feature.js";
+export { readPayloadField } from "./payload-field.js";
 export { createStockCapGuard, } from "./stock-cap-guard.js";
+export { createValueCapGuard, } from "./value-cap-guard.js";
 export { withCapEnforcement, withRollingCapEnforcement, } from "./with-cap-enforcement.js";

package/dist/cap-counter/payload-field.d.ts

@@ -0,0 +1 @@
+export declare function readPayloadField(payload: unknown, field: string): unknown;

package/dist/cap-counter/payload-field.js

@@ -0,0 +1,11 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-framework/utils";
+// Create payloads are flat, entity update payloads carry the edited fields under `changes`
+// (`{ id, version, changes }`), so a guard that follows one field has to look at both.
+export function readPayloadField(payload, field) {
+    if (!isPlainObject(payload))
+        return undefined;
+    if (field in payload)
+        return payload[field];
+    const { changes } = payload;
+    return isPlainObject(changes) ? changes[field] : undefined;
+}

package/dist/cap-counter/reservation-chain.d.ts

@@ -0,0 +1,2 @@
+import type { PreTransactionReservation } from "@cosmicdrift/kumiko-types/handlers";
+export declare function chainReservations(inner: PreTransactionReservation | undefined, own: PreTransactionReservation): PreTransactionReservation;

package/dist/cap-counter/reservation-chain.js

@@ -0,0 +1,44 @@
+function toHandle(outcome) {
+    if (outcome === undefined)
+        return { release: async () => { }, confirmInTransaction: async () => { } };
+    if (typeof outcome === "function") {
+        return { release: outcome, confirmInTransaction: async () => { } };
+    }
+    return outcome;
+}
+// Runs `inner` first, then `own`; a failing `own` gives the inner reservation back before it
+// throws. Release goes in reverse order, confirm covers both.
+export function chainReservations(inner, own) {
+    if (!inner)
+        return own;
+    return async (event, ctx) => {
+        const innerHandle = toHandle(await inner(event, ctx));
+        let ownHandle;
+        try {
+            ownHandle = toHandle(await own(event, ctx));
+        }
+        catch (error) {
+            try {
+                await innerHandle.release();
+            }
+            catch (releaseError) {
+                ctx.log?.error("releasing the inner cap reservation failed", { error: releaseError });
+            }
+            throw error;
+        }
+        return {
+            release: async () => {
+                try {
+                    await ownHandle.release();
+                }
+                finally {
+                    await innerHandle.release();
+                }
+            },
+            confirmInTransaction: async (confirm) => {
+                await innerHandle.confirmInTransaction(confirm);
+                await ownHandle.confirmInTransaction(confirm);
+            },
+        };
+    };
+}

package/dist/cap-counter/stock-cap-guard.d.ts

@@ -4,6 +4,9 @@ import { type WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
 export type CapLimitContext = {
     readonly config?: ConfigAccessor;
 };
+export type CapGuardContext = CapLimitContext & {
+    readonly db: TenantDb;
+};
 export type StockCapSpec<TCaps> = {
     readonly table: SchemaTable | EntityTableMeta;
     readonly limit: (caps: TCaps) => number;

package/dist/cap-counter/tables.d.ts

@@ -0,0 +1,3 @@
+import { type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+export declare const capReservationsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const capReservationsTableMeta: EntityTableMeta;

package/dist/cap-counter/tables.js

@@ -0,0 +1,36 @@
+import { defineUnmanagedTable, index, instant, integer, table as pgTable, text, uuid, } from "@cosmicdrift/kumiko-framework/db";
+const CAP_RESERVATIONS_TENANT_CAP_EXPIRES_INDEX = "store_cap_reservations_tenant_id_cap_name_expires_at_idx";
+// One row per capacity that was booked before a handler transaction and is not settled yet. The
+// handler transaction deletes it on its own commit (confirm); a release or the TTL sweep deletes it
+// together with the counter decrement. Unmanaged: the rows are a coordination aid, not state with
+// an event history.
+export const capReservationsTable = pgTable("store_cap_reservations", {
+    id: uuid("id").primaryKey(),
+    tenantId: uuid("tenant_id").notNull(),
+    capName: text("cap_name").notNull(),
+    kind: text("kind").notNull().$type(),
+    // Calendar only: raw string the counter's aggregate id was derived from; a normalized instant could point at another counter.
+    periodStartIso: text("period_start_iso"),
+    amount: integer("amount").notNull(),
+    expiresAt: instant("expires_at").notNull(),
+    createdAt: instant("created_at").notNull(),
+}, (t) => [index(CAP_RESERVATIONS_TENANT_CAP_EXPIRES_INDEX).on(t.tenantId, t.capName, t.expiresAt)]);
+export const capReservationsTableMeta = defineUnmanagedTable({
+    tableName: "store_cap_reservations",
+    indexes: [
+        {
+            name: CAP_RESERVATIONS_TENANT_CAP_EXPIRES_INDEX,
+            columns: ["tenant_id", "cap_name", "expires_at"],
+        },
+    ],
+    columns: [
+        { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+        { name: "tenant_id", pgType: "uuid", notNull: true },
+        { name: "cap_name", pgType: "text", notNull: true },
+        { name: "kind", pgType: "text", notNull: true },
+        { name: "period_start_iso", pgType: "text", notNull: false },
+        { name: "amount", pgType: "integer", notNull: true },
+        { name: "expires_at", pgType: "timestamptz", notNull: true },
+        { name: "created_at", pgType: "timestamptz", notNull: true },
+    ],
+});

package/dist/cap-counter/value-cap-guard.d.ts

@@ -0,0 +1,18 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { type WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
+import type { CapGuardContext, CapLimitContext } from "./stock-cap-guard.js";
+export type ValueCapSpec<TCaps> = {
+    readonly field: string;
+    /** `undefined` = no lower bound for this tier. */
+    readonly min?: (caps: TCaps) => number | undefined;
+    /** `undefined` = no upper bound for this tier. */
+    readonly max?: (caps: TCaps) => number | undefined;
+    readonly code: string;
+    readonly i18nKey: string;
+};
+export type ValueCapGuard<TCaps> = {
+    readonly checkValueCap: (ctx: CapGuardContext, value: unknown, spec: ValueCapSpec<TCaps>) => Promise<WriteFailure | null>;
+    readonly withValueCap: (handler: WriteHandlerDef, spec: ValueCapSpec<TCaps>) => WriteHandlerDef;
+};
+export declare function createValueCapGuard<TCaps>(resolveTierCaps: (db: TenantDb, context: CapLimitContext) => Promise<TCaps>): ValueCapGuard<TCaps>;

package/dist/cap-counter/value-cap-guard.js

@@ -0,0 +1,33 @@
+// Per-tier bounds on a single written number (e.g. a retention period or a page size),
+// next to the stock-cap guard, which bounds how many rows may exist.
+import { UnprocessableError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
+import { readPayloadField } from "./payload-field.js";
+function isOutOfBounds(value, min, max) {
+    return (min !== undefined && value < min) || (max !== undefined && value > max);
+}
+export function createValueCapGuard(resolveTierCaps) {
+    async function checkValueCap(ctx, value, spec) {
+        // skip: an absent or non-numeric value is the schema's business, not a cap violation.
+        if (typeof value !== "number")
+            return null;
+        const caps = await resolveTierCaps(ctx.db, ctx.config ? { config: ctx.config } : {});
+        const min = spec.min?.(caps);
+        const max = spec.max?.(caps);
+        if (!isOutOfBounds(value, min, max))
+            return null;
+        return writeFailure(new UnprocessableError(spec.code, {
+            i18nKey: spec.i18nKey,
+            details: { field: spec.field, value, min, max },
+        }));
+    }
+    function withValueCap(handler, spec) {
+        return {
+            ...handler,
+            handler: async (event, ctx) => {
+                const failure = await checkValueCap(ctx, readPayloadField(event.payload, spec.field), spec);
+                return failure ?? handler.handler(event, ctx);
+            },
+        };
+    }
+    return { checkValueCap, withValueCap };
+}

package/dist/cap-counter/with-cap-enforcement.d.ts

@@ -44,13 +44,11 @@ export type RollingCapResolver = (event: WriteEvent, ctx: HandlerContext) => Pro
 /**
  * Wrap a write-handler with rolling-window cap-enforcement.
  *
- * Same flow as `withCapEnforcement` but uses
- * `enforceRollingCapAndMaybeNotify` + dispatches
- * `cap-counter:write:increment-rolling` post-success.
+ * Same flow as `withCapEnforcement` but uses `enforceRollingCapAndMaybeNotify` and reserves by
+ * appending a `rolling-incremented` event before the handler transaction; a release appends
+ * `rolling-released`.
  *
- * **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.
+ * Rolling counters track no lastSoftWarnedAt, so the notifier fires on every call while usage
+ * sits in the soft range; throttle inside the notify callback (e.g. a per-capName TTL cache).
  */
 export declare function withRollingCapEnforcement(handler: WriteHandlerDef, capResolver: RollingCapResolver): WriteHandlerDef;

package/dist/cap-counter/with-cap-enforcement.js

@@ -6,26 +6,26 @@
 // the wrapper keeps the pattern explicit and co-located.
 //
 // **Calendar reservation:** the wrapper only declares the cap; the dispatcher runs the
-// reservation (reserveBeforeTransaction) before the handler transaction opens, in its own short
-// committed write, and releases it after that transaction ended without committing (rollback,
-// failure result, failed COMMIT). No connection is held across the handler, so capped requests
-// cannot exhaust the pool, and the counter stream is not locked while the handler runs. If a
-// COMMIT fails with an unknown outcome the release can under-count; a wrapped handler must not
-// book the same counter itself. Reached through a nested ctx.write the cap is not reserved, so
-// the dispatcher rejects that call unless the top-level batch reserved the same handler.
+// reservation (reserveBeforeTransaction) after all pre-handler gates and before the handler
+// transaction opens, in its own short committed write (counter increment plus a
+// store_cap_reservations row). The handler transaction deletes the row on its own commit; a release
+// after a rollback, failure result or failed COMMIT only gives back what is still booked, so an
+// unknown COMMIT outcome cannot under-count. No connection is held across the handler. Rows a
+// crashed process left behind expire after CAP_RESERVATION_TTL_MINUTES and are given back before the
+// next reserve of the same cap. Reached through a nested ctx.write the cap is not reserved, so the
+// dispatcher rejects that call unless the top-level batch reserved the same handler.
 //
-// Rolling booking still dispatches the SystemAdmin-only increment-rolling
-// handler and has no reservation: it would need a compensating event type,
-// a changed readRollingCapUsage and a version-guarded append behind the
-// SystemAdmin dispatch. Rolling callers need a SystemAdmin identity until
-// cap-counter declares an explicit foreign-booking opt-in.
+// The wrapper spreads the wrapped handler and chains its reserveBeforeTransaction: inner reserves
+// first, release runs in reverse, and an outer failure gives the inner reservation back.
+//
+// Rolling caps reserve the same way: a version-guarded `rolling-incremented` append plus a
+// reservation row, undone by a `rolling-released` event. The window sum is incremented minus released.
 //
 // No automatic markSoftWarned here — that's inside enforceCapAndMaybeNotify
 // (enforce-cap.ts).
-import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
-import { bookCapUsage, releaseCapUsage } from "./book-cap-usage.js";
-import { CapCounterHandlers } from "./constants.js";
+import { releaseExpiredCapReservations, reserveCalendarCap, reserveRollingCap, } from "./cap-reservation.js";
 import { assertBelowHardCap, enforceCapAndMaybeNotify, enforceRollingCapAndMaybeNotify, } from "./enforce-cap.js";
+import { chainReservations } from "./reservation-chain.js";
 /**
  * Wrap a write-handler with calendar-period cap-enforcement.
  *
@@ -39,8 +39,9 @@ import { assertBelowHardCap, enforceCapAndMaybeNotify, enforceRollingCapAndMaybe
 export function withCapEnforcement(handler, capResolver) {
     return {
         ...handler,
-        reserveBeforeTransaction: async (event, ctx) => {
+        reserveBeforeTransaction: chainReservations(handler.reserveBeforeTransaction, async (event, ctx) => {
             const cap = await capResolver(event, ctx);
+            await releaseExpiredCapReservations(ctx, cap.capName);
             await enforceCapAndMaybeNotify(ctx, {
                 capName: cap.capName,
                 periodStartIso: cap.periodStartIso,
@@ -51,47 +52,31 @@ export function withCapEnforcement(handler, capResolver) {
                 ...(cap.amount !== undefined && { amount: cap.amount }),
             });
             const amount = cap.amount ?? 1;
-            const reserved = await bookCapUsage(ctx, {
+            return reserveCalendarCap(ctx, {
                 capName: cap.capName,
                 amount,
                 periodStartIso: cap.periodStartIso,
-                outsideTransaction: true,
                 guardCurrentValue: (currentValue) => assertBelowHardCap(currentValue + amount - 1, cap),
             });
-            if (!reserved.isSuccess)
-                throw reraiseAsKumikoError(reserved.error);
-            return async () => {
-                const released = await releaseCapUsage(ctx, {
-                    capName: cap.capName,
-                    amount,
-                    periodStartIso: cap.periodStartIso,
-                    outsideTransaction: true,
-                });
-                if (!released.isSuccess)
-                    throw reraiseAsKumikoError(released.error);
-            };
-        },
+        }),
     };
 }
 /**
  * Wrap a write-handler with rolling-window cap-enforcement.
  *
- * Same flow as `withCapEnforcement` but uses
- * `enforceRollingCapAndMaybeNotify` + dispatches
- * `cap-counter:write:increment-rolling` post-success.
+ * Same flow as `withCapEnforcement` but uses `enforceRollingCapAndMaybeNotify` and reserves by
+ * appending a `rolling-incremented` event before the handler transaction; a release appends
+ * `rolling-released`.
  *
- * **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.
+ * Rolling counters track no lastSoftWarnedAt, so the notifier fires on every call while usage
+ * sits in the soft range; throttle inside the notify callback (e.g. a per-capName TTL cache).
  */
 export function withRollingCapEnforcement(handler, capResolver) {
     return {
-        name: handler.name,
-        schema: handler.schema,
-        access: handler.access,
-        handler: async (event, ctx) => {
+        ...handler,
+        reserveBeforeTransaction: chainReservations(handler.reserveBeforeTransaction, async (event, ctx) => {
             const cap = await capResolver(event, ctx);
+            await releaseExpiredCapReservations(ctx, cap.capName);
             await enforceRollingCapAndMaybeNotify(ctx, {
                 capName: cap.capName,
                 windowDays: cap.windowDays,
@@ -99,14 +84,13 @@ export function withRollingCapEnforcement(handler, capResolver) {
                 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;
-        },
+            const amount = cap.amount ?? 1;
+            return reserveRollingCap(ctx, {
+                capName: cap.capName,
+                windowDays: cap.windowDays,
+                amount,
+                guardCurrentValue: (usage) => assertBelowHardCap(usage + amount - 1, cap),
+            });
+        }),
     };
 }

package/dist/channel-discord/feature.js

@@ -30,6 +30,7 @@ export function createChannelDiscordFeature(options = {}) {
         r.translations({ keys: { "delivery.channel.discord": { en: "Discord" } } });
         r.useExtension(DELIVERY_CHANNEL_EXTENSION, "discord", {
             mode: channel.mode,
+            addressKind: "connection-name",
             send: channel.send,
         });
     });

package/dist/channel-slack/feature.js

@@ -27,6 +27,7 @@ export function createChannelSlackFeature(options = {}) {
         r.translations({ keys: { "delivery.channel.slack": { en: "Slack" } } });
         r.useExtension(DELIVERY_CHANNEL_EXTENSION, "slack", {
             mode: channel.mode,
+            addressKind: "connection-name",
             send: channel.send,
         });
     });

package/dist/channel-teams/feature.js

@@ -31,6 +31,7 @@ export function createChannelTeamsFeature(options = {}) {
         r.translations({ keys: { "delivery.channel.teams": { en: "Microsoft Teams" } } });
         r.useExtension(DELIVERY_CHANNEL_EXTENSION, "teams", {
             mode: channel.mode,
+            addressKind: "connection-name",
             send: channel.send,
         });
     });

package/dist/compliance-profiles/schema/profile-selection.d.ts

@@ -18,6 +18,7 @@ export declare const tenantComplianceProfileEntity: import("@cosmicdrift/kumiko-
         } | undefined;
         readonly optionsQuery?: string;
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
+        readonly optionsAvailabilityQuery?: string;
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
@@ -58,6 +59,7 @@ export declare const tenantComplianceProfileTable: import("@cosmicdrift/kumiko-f
         } | undefined;
         readonly optionsQuery?: string;
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
+        readonly optionsAvailabilityQuery?: string;
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };

package/dist/delivery/attempt-log-retention.d.ts

@@ -0,0 +1,9 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type PruneEventsOptions } from "@cosmicdrift/kumiko-framework/pipeline";
+export declare const DEFAULT_ATTEMPT_LOG_RETENTION_DAYS = 90;
+export type AttemptLogRetentionOptions = Pick<PruneEventsOptions, "olderThan" | "olderThanDays">;
+export declare function resolveAttemptLogRetentionDays(option: number | false | undefined): number | undefined;
+export declare function runAttemptLogRetention(db: DbConnection, options: AttemptLogRetentionOptions): Promise<{
+    readonly deletedEvents: number;
+    readonly deletedRows: number;
+}>;

package/dist/delivery/attempt-log-retention.js

@@ -0,0 +1,23 @@
+import { deleteManyBatched } from "@cosmicdrift/kumiko-framework/bun-db";
+import { pruneEvents } from "@cosmicdrift/kumiko-framework/pipeline";
+import { deliveryAttemptsTable } from "./tables.js";
+export const DEFAULT_ATTEMPT_LOG_RETENTION_DAYS = 90;
+const ROW_DELETE_BATCH_SIZE = 1000;
+export function resolveAttemptLogRetentionDays(option) {
+    if (option === false)
+        return undefined;
+    const days = option ?? DEFAULT_ATTEMPT_LOG_RETENTION_DAYS;
+    if (!Number.isInteger(days) || days <= 0) {
+        throw new Error(`delivery: attemptLogRetentionDays must be a positive integer or false, got ${String(option)}`);
+    }
+    return days;
+}
+// Prunes the attempt events first and then the projection rows older than the same cutoff: a
+// rebuild would not recreate rows whose events are gone, so they would otherwise stay forever.
+// A lagging event consumer makes pruneEvents throw ConsumerLagError before anything is deleted;
+// the caller retries on its next run.
+export async function runAttemptLogRetention(db, options) {
+    const pruned = await pruneEvents(db, { ...options, aggregateTypes: ["deliveryAttempt"] });
+    const rows = await deleteManyBatched(db, deliveryAttemptsTable, { createdAt: { lt: pruned.cutoff } }, { limit: ROW_DELETE_BATCH_SIZE });
+    return { deletedEvents: pruned.deletedCount, deletedRows: rows.deleted };
+}

package/dist/delivery/attempt-log.d.ts

@@ -1,5 +1,5 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
-import type { DeliveryLogEntry } from "./types.js";
+import { type DeliveryLogEntry } from "./types.js";
 export declare function appendAttemptEvent(db: DbConnection, registry: Registry, attemptId: string, entry: DeliveryLogEntry): Promise<void>;
 export declare function logAttempt(db: DbConnection, registry: Registry, entry: DeliveryLogEntry): Promise<string>;

package/dist/delivery/attempt-log.js

@@ -5,16 +5,35 @@
 import { append, getStreamVersion } from "@cosmicdrift/kumiko-framework/event-store";
 import { runProjectionsForEvent } from "@cosmicdrift/kumiko-framework/pipeline";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
-import { DELIVERY_ATTEMPT_EVENT } from "./constants.js";
+import { DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_EXTENSION } from "./constants.js";
 import { deliveryAttemptSchema } from "./events.js";
+import { maskRecipientAddress } from "./mask-recipient-address.js";
+import { isDeliveryChannelPlugin } from "./types.js";
+// Unknown channels count as personal: masking is the fail-closed default.
+function addressIsConnectionName(registry, channelName) {
+    return registry
+        .getExtensionUsages(DELIVERY_CHANNEL_EXTENSION)
+        .some((usage) => usage.entityName === channelName &&
+        isDeliveryChannelPlugin(usage.options) &&
+        usage.options.addressKind === "connection-name");
+}
+function loggedAddress(registry, entry) {
+    return addressIsConnectionName(registry, entry.channel)
+        ? entry.recipientAddress
+        : maskRecipientAddress(entry.recipientAddress);
+}
 // Shared append + inline-projection write (low-level append() does not
 // auto-fire projections — only the dispatcher/executor paths do).
 async function writeAttemptEvent(db, registry, attemptId, expectedVersion, entry) {
     const { tenantId, ...rest } = entry;
+    // Masked here, the only place attempt events are written, so no event or projection row ever holds the full address.
     // Schema-parse to match ctx.appendEvent's guarantee: a payload drift between
     // service/job + feature-registration fails loudly here instead of landing on
     // the events-table and crashing a consumer later.
-    const payload = deliveryAttemptSchema.parse(rest);
+    const payload = deliveryAttemptSchema.parse({
+        ...rest,
+        recipientAddress: loggedAddress(registry, entry),
+    });
     const stored = await append(db, {
         aggregateId: attemptId,
         aggregateType: "deliveryAttempt",

package/dist/delivery/constants.d.ts

@@ -1,6 +1,6 @@
 import type { NotifyPriority } from "@cosmicdrift/kumiko-framework/engine";
 export declare const DELIVERY_CHANNEL_EXTENSION: "deliveryChannel";
-export { DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_RESUBSCRIBE_PATH, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobNames, DeliveryQueries, DeliveryStatus, type DeliveryStatusValue, } from "./public-names.js";
+export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_RESUBSCRIBE_PATH, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobNames, DeliveryQueries, DeliveryStatus, type DeliveryStatusValue, } from "./public-names.js";
 export declare const deliveryPriorityRank: Record<NotifyPriority, number>;
 export declare const DeliveryJobs: {
     readonly render: string;

package/dist/delivery/constants.js

@@ -3,7 +3,7 @@ import { DELIVERY_FEATURE, DeliveryJobNames } from "./public-names.js";
 // Extension-point name for delivery-channel plugins (channel-email,
 // channel-in-app, channel-push, ...).
 export const DELIVERY_CHANNEL_EXTENSION = "deliveryChannel";
-export { DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_RESUBSCRIBE_PATH, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobNames, DeliveryQueries, DeliveryStatus, } from "./public-names.js";
+export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_RESUBSCRIBE_PATH, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobNames, DeliveryQueries, DeliveryStatus, } from "./public-names.js";
 // notify() priority → BullMQ job priority. Lower number = processed first; all
 // > 0 so prioritised delivery jobs never mix with BullMQ's "0 = unprioritised
 // FIFO" bucket. critical jobs jump ahead of normal/low in the worker queue.

package/dist/delivery/events.d.ts

@@ -36,3 +36,4 @@ export declare const deliveryAttemptSchema: z.ZodObject<{
     confirmed: z.ZodOptional<z.ZodLiteral<false>>;
 }, z.core.$strip>;
 export type DeliveryAttemptPayload = z.infer<typeof deliveryAttemptSchema>;
+export declare const deliveryAttemptAddressErasedSchema: z.ZodObject<{}, z.core.$strip>;

package/dist/delivery/events.js

@@ -28,3 +28,5 @@ export const deliveryAttemptSchema = z.object({
     // Provider accepted the request but does not confirm delivery (e.g. Teams 202).
     confirmed: z.literal(false).optional(),
 });
+// No payload: the event only marks the attempt row's address as erased.
+export const deliveryAttemptAddressErasedSchema = z.object({});