@cosmicdrift/kumiko-bundled-features 0.367.0 → 0.369.0

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

@@ -1,5 +1,5 @@
 import { deleteMany, isUniqueViolation, runInOwnTransaction, } from "@cosmicdrift/kumiko-framework/db";
-import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
+import { reraiseAsKumikoError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import { appendEventInTenantDb, getStreamVersionInTenantDb, } from "@cosmicdrift/kumiko-framework/event-store";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
@@ -20,6 +20,8 @@ async function insertReservationRow(txDb, user, id, draft) {
         expiresAt: now.add({ minutes: CAP_RESERVATION_TTL_MINUTES }),
         createdAt: now,
         settledAt: null,
+        consumedAmount: 0,
+        releasedAt: null,
     });
 }
 function toHandle(ctx, id, outsideTransaction) {
@@ -99,12 +101,16 @@ async function confirmCapReservation(confirm, id) {
         id,
         tenantId: confirm.tenantId,
         settledAt: null,
+        releasedAt: null,
     });
 }
 async function giveBackCalendar(txDb, user, row) {
     if (row.periodStartIso === null) {
         throw new Error(`cap-counter: calendar reservation ${row.id} has no period to release against`);
     }
+    // Fully consumed by consumeCalendarCapReservation: nothing left to give back.
+    if (row.amount === 0)
+        return NOTHING_TO_RELEASE;
     return applyCapDeltaOn(txDb, user, { capName: row.capName, periodStartIso: row.periodStartIso, amount: row.amount }, "subtract");
 }
 async function giveBackRolling(txDb, user, row) {
@@ -125,21 +131,33 @@ async function giveBackReservation(txDb, user, id) {
     if (!row)
         return NOTHING_TO_RELEASE;
     const claimed = await claimReservationRow(txDb, user, row);
-    if (!claimed)
+    if (!claimed || claimed.releasedAt !== null)
         return NOTHING_TO_RELEASE;
-    const given = row.kind === "rolling"
-        ? await giveBackRolling(txDb, user, row)
-        : await giveBackCalendar(txDb, user, row);
+    const given = claimed.kind === "rolling"
+        ? await giveBackRolling(txDb, user, claimed)
+        : await giveBackCalendar(txDb, user, claimed);
     if (!given.isSuccess)
         return given;
-    await txDb.deleteMany(capReservationsTable, ownRow);
+    // Only consumed units need remembering: a later settle or consume must not count them twice.
+    if (claimed.kind === "rolling" || claimed.consumedAmount === 0) {
+        await txDb.deleteMany(capReservationsTable, ownRow);
+        return given;
+    }
+    const now = Temporal.Now.instant();
+    await txDb.updateMany(capReservationsTable, {
+        amount: 0,
+        releasedAt: now,
+        expiresAt: now.add({ minutes: CAP_SETTLED_TOMBSTONE_TTL_MINUTES }),
+    }, ownRow);
     return given;
 }
-// Waits for a confirm still holding the row; false means that confirm, a settle or another release
-// won (Postgres re-checks settled_at after the lock wait).
+// Waits for a confirm still holding the row; undefined means that confirm or a settle won (Postgres
+// re-checks settled_at after the lock wait). A released row is claimed too: callers branch on
+// releasedAt. The returned row is read after the lock wait, so it already includes a concurrent
+// consume.
 async function claimReservationRow(txDb, user, row) {
-    const claimed = await txDb.updateMany(capReservationsTable, { expiresAt: row.expiresAt }, { id: row.id, tenantId: user.tenantId, settledAt: null });
-    return claimed.length > 0;
+    const [claimed] = await txDb.updateMany(capReservationsTable, { expiresAt: row.expiresAt }, { id: row.id, tenantId: user.tenantId, settledAt: null });
+    return claimed;
 }
 export async function releaseCapReservation(ctx, id, outsideTransaction = true) {
     const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
@@ -147,6 +165,22 @@ export async function releaseCapReservation(ctx, id, outsideTransaction = true)
     if (!released.isSuccess)
         throw reraiseAsKumikoError(released.error);
 }
+export class CapSettleBelowConsumedError extends UnprocessableError {
+    constructor(capName, consumed, actualAmount) {
+        super("cap_settle_below_consumed", {
+            message: `Cap "${capName}": cannot settle ${actualAmount}, ${consumed} units were already consumed.`,
+            details: { capName, consumed, actualAmount },
+        });
+    }
+}
+export class CapReservationSettledError extends UnprocessableError {
+    constructor(capName) {
+        super("cap_reservation_settled", {
+            message: `Cap "${capName}": the reservation is already settled, consume is no longer possible.`,
+            details: { capName },
+        });
+    }
+}
 function bookCalendarDelta(txDb, user, period, delta) {
     if (delta === 0)
         return Promise.resolve({ isSuccess: true, data: {} });
@@ -158,8 +192,13 @@ async function settleInTransaction(txDb, user, id, options) {
         ...ownRow,
         settledAt: null,
     });
-    if (open && (await claimReservationRow(txDb, user, open))) {
-        const booked = await bookCalendarDelta(txDb, user, options, options.actualAmount - open.amount);
+    const claimed = open && (await claimReservationRow(txDb, user, open));
+    if (claimed) {
+        if (options.actualAmount < claimed.consumedAmount) {
+            throw new CapSettleBelowConsumedError(options.capName, claimed.consumedAmount, options.actualAmount);
+        }
+        const alreadyBooked = claimed.amount + claimed.consumedAmount;
+        const booked = await bookCalendarDelta(txDb, user, options, options.actualAmount - alreadyBooked);
         if (!booked.isSuccess)
             return booked;
         const now = Temporal.Now.instant();
@@ -172,6 +211,11 @@ async function settleInTransaction(txDb, user, id, options) {
     }
     // Row swept or released: its amount was given back, so the full actual amount is booked and a
     // tombstone makes a repeated settle a no-op. A parallel settle inserting first fails this insert.
+    // Booking first: a lost counter race returns a result instead of throwing, so the transaction
+    // commits and a tombstone written before it would turn the retry into a no-op.
+    const booked = await bookCalendarDelta(txDb, user, options, options.actualAmount);
+    if (!booked.isSuccess)
+        return booked;
     const now = Temporal.Now.instant();
     await txDb.insertOne(capReservationsTable, {
         ...ownRow,
@@ -182,8 +226,10 @@ async function settleInTransaction(txDb, user, id, options) {
         expiresAt: now.add({ minutes: CAP_SETTLED_TOMBSTONE_TTL_MINUTES }),
         createdAt: now,
         settledAt: now,
+        consumedAmount: 0,
+        releasedAt: null,
     });
-    return bookCalendarDelta(txDb, user, options, options.actualAmount);
+    return booked;
 }
 // The failed tombstone insert aborts the whole attempt, so nothing was booked; the repeat sees the
 // winner's tombstone.
@@ -208,8 +254,87 @@ export async function settleCalendarCapReservation(ctx, id, options, outsideTran
     if (!settled.isSuccess)
         throw reraiseAsKumikoError(settled.error);
 }
+export class CapReservationOverConsumedError extends UnprocessableError {
+    constructor(capName, remaining, requested) {
+        super("cap_reservation_over_consumed", {
+            message: `Cap "${capName}": cannot consume ${requested} units, only ${remaining} still reserved.`,
+            details: { capName, remaining, requested },
+        });
+    }
+}
+async function consumeClaimedRow(txDb, user, claimed, options) {
+    const ownRow = { id: claimed.id, tenantId: user.tenantId };
+    if (claimed.releasedAt !== null) {
+        // The reserved rest was given back, so each unit is booked on top of what is still counted.
+        const booked = await bookCalendarDelta(txDb, user, options, options.units);
+        if (!booked.isSuccess)
+            return booked;
+        await txDb.updateMany(capReservationsTable, { consumedAmount: claimed.consumedAmount + options.units }, ownRow);
+        return booked;
+    }
+    if (options.units > claimed.amount) {
+        throw new CapReservationOverConsumedError(options.capName, claimed.amount, options.units);
+    }
+    await txDb.updateMany(capReservationsTable, {
+        amount: claimed.amount - options.units,
+        consumedAmount: claimed.consumedAmount + options.units,
+    }, ownRow);
+    return NOTHING_TO_RELEASE;
+}
+// Row already expired away: the units are booked directly and a released tombstone remembers them
+// so a later settle subtracts them. A parallel consume inserting first fails this insert.
+async function consumeWithoutRow(txDb, user, id, options) {
+    // Booking first, for the same reason as settle's missing-row path.
+    const booked = await bookCalendarDelta(txDb, user, options, options.units);
+    if (!booked.isSuccess)
+        return booked;
+    const now = Temporal.Now.instant();
+    await txDb.insertOne(capReservationsTable, {
+        id,
+        tenantId: user.tenantId,
+        capName: options.capName,
+        kind: "calendar",
+        periodStartIso: options.periodStartIso,
+        amount: 0,
+        expiresAt: now.add({ minutes: CAP_SETTLED_TOMBSTONE_TTL_MINUTES }),
+        createdAt: now,
+        settledAt: null,
+        consumedAmount: options.units,
+        releasedAt: now,
+    });
+    return booked;
+}
+async function consumeInTransaction(txDb, user, id, options) {
+    const ownRow = { id, tenantId: user.tenantId };
+    const open = await txDb.fetchOne(capReservationsTable, {
+        ...ownRow,
+        settledAt: null,
+    });
+    if (open && open.capName !== options.capName) {
+        throw new Error(`cap-counter: reservation ${id} belongs to cap "${open.capName}", not "${options.capName}"`);
+    }
+    const claimed = open && (await claimReservationRow(txDb, user, open));
+    if (claimed)
+        return consumeClaimedRow(txDb, user, claimed, options);
+    if (await txDb.fetchOne(capReservationsTable, ownRow)) {
+        throw new CapReservationSettledError(options.capName);
+    }
+    return consumeWithoutRow(txDb, user, id, options);
+}
+// Turns reserved units into booked ones without touching the counter; the row keeps the unconsumed
+// rest so a release gives back exactly that. After a release or sweep the units are booked directly.
+export async function consumeCalendarCapReservation(ctx, id, options, outsideTransaction = true) {
+    if (!Number.isInteger(options.units) || options.units < 1) {
+        throw new Error(`cap-counter: consume units must be a positive integer, got ${options.units}`);
+    }
+    const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
+    const consumed = await retryCounterWriteOnVersionConflict(() => retryOnceOnTombstoneRace(() => runInOwnTransaction(writeDb, (txDb) => consumeInTransaction(txDb, user, id, options))));
+    if (!consumed.isSuccess)
+        throw reraiseAsKumikoError(consumed.error);
+}
 // A failed release leaves its row behind; giving it back once the TTL passed bounds how long that
-// capacity stays counted. Expired settled tombstones are only deleted: their amount stays booked.
+// capacity stays counted. Expired settled and released tombstones are only deleted: what they
+// stand for stays booked.
 export async function releaseExpiredCapReservations(ctx, capName, outsideTransaction = true) {
     const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
     const expiredWhere = {
@@ -221,9 +346,14 @@ export async function releaseExpiredCapReservations(ctx, capName, outsideTransac
         ...expiredWhere,
         settledAt: { ne: null },
     });
+    await writeDb.deleteMany(capReservationsTable, {
+        ...expiredWhere,
+        releasedAt: { ne: null },
+    });
     const expired = await writeDb.selectMany(capReservationsTable, {
         ...expiredWhere,
         settledAt: null,
+        releasedAt: null,
     });
     for (const { id } of expired) {
         try {

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

@@ -1,3 +1,7 @@
+export declare function createCapCounterFeature(): import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: void;
+};
+/** @deprecated Use createCapCounterFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
 export declare const capCounterFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
     readonly exports: void;
 };

package/dist/cap-counter/feature.js

@@ -53,71 +53,77 @@ import { incrementRollingCapHandler, rollingIncrementedSchema, rollingReleasedSc
 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({
-        displayLabel: "Cap Counter · Usage Limits",
-        category: "operations",
-        recommended: false,
-    });
-    r.entity({ name: "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).
-    // - mark-soft-warned: Anti-Notification-Storm-Flag (nur Calendar).
-    r.writeHandler(incrementCapHandler);
-    r.writeHandler(incrementRollingCapHandler);
-    r.writeHandler(markSoftWarnedHandler);
-    // Custom + standard reads. Sysadmin-cross-tenant via list, per-tenant
-    // single-row via get-counter. Detail-by-id-handler bewusst weggelassen
-    // (kein Use-Case; der natürliche Lookup ist über capName + period, nicht
-    // über aggregate-id).
-    r.queryHandler(defineEntityListHandler("cap-counter", capCounterEntity, {
-        access: { roles: access.systemAdmin },
-        escapeHatch: {
-            reason: "SystemAdmin quota operator view lists usage counters of every tenant to see who consumes which cap",
-        },
-        description: "Lists usage-counter rows across all tenants with cap name, current value, period start and soft-warn timestamp; use it as the operator view of who is consuming which quota.",
-    }));
-    r.queryHandler(getCounterQuery);
-    r.screen({
-        id: CAP_COUNTER_LIST_SCREEN_ID,
-        type: "entityList",
-        entity: "cap-counter",
-        columns: [
-            "tenantId",
-            "capName",
-            "value",
-            "periodStart",
-            { field: "lastSoftWarnedAt", hideOnNarrow: true },
-        ],
-        defaultSort: { field: "capName", dir: "asc" },
-        // Search resolves against the caller's own tenant stream, so on this
-        // cross-tenant operator list it would only ever hit the SystemAdmin's tenant.
-        searchable: false,
-        access: { roles: ["SystemAdmin"] },
-    });
-    r.nav({
-        id: "cap-list",
-        label: "cap-counter:nav.cap-list",
-        screen: "cap-counter:screen:cap-list",
-        icon: "gauge",
-        order: 60,
-    });
-    r.translations({
-        keys: {
-            ...CAP_COUNTER_I18N,
-            "cap-counter:nav.cap-list": { de: "Limits", en: "Caps" },
-        },
-    });
-});
+export function createCapCounterFeature() {
+    return 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({
+            displayLabel: "Cap Counter · Usage Limits",
+            category: "operations",
+            recommended: false,
+        });
+        r.entity({ name: "cap-counter", ...capCounterEntity });
+        r.storeTable(capReservationsTableMeta, {
+            reason: "coordination.cap_reservation_ledger",
+        });
+        // Custom domain event for the rolling counter. r.defineEvent registers the
+        // schema with the registry; ctx.unsafeAppendEvent in the handler reuses the
+        // same schema for append-time validation. QN after prefixing:
+        // "cap-counter:event:rolling-incremented" (see
+        // 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).
+        // - mark-soft-warned: anti-notification-storm flag (calendar only).
+        r.writeHandler(incrementCapHandler);
+        r.writeHandler(incrementRollingCapHandler);
+        r.writeHandler(markSoftWarnedHandler);
+        // Custom + standard reads. Sysadmin cross-tenant via list, per-tenant
+        // single row via get-counter. Detail-by-id handler left out on purpose
+        // (no use case; the natural lookup is capName + period, not the
+        // aggregate id).
+        r.queryHandler(defineEntityListHandler("cap-counter", capCounterEntity, {
+            access: { roles: access.systemAdmin },
+            escapeHatch: {
+                reason: "SystemAdmin quota operator view lists usage counters of every tenant to see who consumes which cap",
+            },
+            description: "Lists usage-counter rows across all tenants with cap name, current value, period start and soft-warn timestamp; use it as the operator view of who is consuming which quota.",
+        }));
+        r.queryHandler(getCounterQuery);
+        r.screen({
+            id: CAP_COUNTER_LIST_SCREEN_ID,
+            type: "entityList",
+            entity: "cap-counter",
+            columns: [
+                "tenantId",
+                "capName",
+                "value",
+                "periodStart",
+                { field: "lastSoftWarnedAt", hideOnNarrow: true },
+            ],
+            defaultSort: { field: "capName", dir: "asc" },
+            // Search resolves against the caller's own tenant stream, so on this
+            // cross-tenant operator list it would only ever hit the SystemAdmin's tenant.
+            searchable: false,
+            access: { roles: ["SystemAdmin"] },
+        });
+        r.nav({
+            id: "cap-list",
+            label: "cap-counter:nav.cap-list",
+            screen: "cap-counter:screen:cap-list",
+            icon: "gauge",
+            order: 60,
+        });
+        r.translations({
+            keys: {
+                ...CAP_COUNTER_I18N,
+                "cap-counter:nav.cap-list": { de: "Limits", en: "Caps" },
+            },
+        });
+    }, { dedupeOptions: {} });
+}
+/** @deprecated Use createCapCounterFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const capCounterFeature = createCapCounterFeature();

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

@@ -60,10 +60,9 @@ export const incrementRollingCapHandler = {
         // existing increment.write.ts-Cast — gleiche dispatcher-boundary.
         const payload = event.payload;
         const aggregateId = rollingCapAggregateId(event.user.tenantId, payload.capName);
-        // unsafeAppendEvent — bundled-features-Pfad (apps mit bun kumiko
-        // codegen kriegen den strict-typed appendEvent-Wrapper). Schema-
-        // Validation läuft trotzdem, weil r.defineEvent das Schema
-        // registriert hat.
+        // unsafeAppendEvent: the strict appendEvent is bound to an app's own event map, which
+        // bundled-features cannot see. Schema validation still runs because r.defineEvent
+        // registered the schema.
         await ctx.unsafeAppendEvent({
             aggregateId,
             aggregateType: CAP_COUNTER_ROLLING_AGGREGATE_TYPE,

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

@@ -1,10 +1,11 @@
 export { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id.js";
 export { type BookCapUsageOptions, bookCapUsage, type MarkCapSoftWarnedOptions, markCapSoftWarned, type ReadRollingCapUsageOptions, readRollingCapUsage, } from "./book-cap-usage.js";
-export { type CalendarCapUsageReservation, type CalendarCapUsageReservationSpec, reserveCalendarCapUsage, } from "./calendar-cap-usage-reservation.js";
+export { type CalendarCapReservationHandle, type CalendarCapReservationHandleSpec, type CalendarCapUsageReservation, type CalendarCapUsageReservationSpec, calendarCapReservationHandle, reserveCalendarCapUsage, } from "./calendar-cap-usage-reservation.js";
+export { CapReservationOverConsumedError, CapReservationSettledError, CapSettleBelowConsumedError, } from "./cap-reservation.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, calendarMonthPeriodEndIso, 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 { capCounterFeature, createCapCounterFeature } from "./feature.js";
 export { readPayloadField } from "./payload-field.js";
 export { type CapGuardContext, type CapLimitContext, createStockCapGuard, type StockCapGuard, type StockCapSpec, } from "./stock-cap-guard.js";
 export { capReservationsTable, capReservationsTableMeta } from "./tables.js";

package/dist/cap-counter/index.js

@@ -1,11 +1,12 @@
 // 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 { reserveCalendarCapUsage, } from "./calendar-cap-usage-reservation.js";
+export { calendarCapReservationHandle, reserveCalendarCapUsage, } from "./calendar-cap-usage-reservation.js";
+export { CapReservationOverConsumedError, CapReservationSettledError, CapSettleBelowConsumedError, } from "./cap-reservation.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, calendarMonthPeriodEndIso, currentCalendarMonthStartIso, enforceCap, enforceCapAndMaybeNotify, enforceRollingCap, enforceRollingCapAndMaybeNotify, enforceStockCap, } from "./enforce-cap.js";
 export { capCounterEntity } from "./entity.js";
-export { capCounterFeature } from "./feature.js";
+export { capCounterFeature, createCapCounterFeature } from "./feature.js";
 export { readPayloadField } from "./payload-field.js";
 export { createStockCapGuard, } from "./stock-cap-guard.js";
 export { capReservationsTable, capReservationsTableMeta } from "./tables.js";

package/dist/cap-counter/tables.js

@@ -1,9 +1,12 @@
 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. A settle keeps the row as a tombstone (settled_at set) until
-// its shortened TTL passes, so a repeated settle or a late release finds it and does nothing.
+// handler transaction deletes it on its own commit (confirm). While a calendar row is open the
+// counter holds amount + consumed_amount for it. A release or the TTL sweep gives back amount and
+// keeps the row as a released tombstone (released_at set, amount 0, consumed_amount still booked)
+// until its shortened TTL passes, so a later consume or settle accounts for the consumed units.
+// A settle keeps the row as a settled tombstone (settled_at set) the same way, so a repeated settle
+// or a late release finds it and does nothing.
 // Unmanaged: the rows are a coordination aid, not state with an event history.
 export const capReservationsTable = pgTable("store_cap_reservations", {
     id: uuid("id").primaryKey(),
@@ -16,6 +19,8 @@ export const capReservationsTable = pgTable("store_cap_reservations", {
     expiresAt: instant("expires_at").notNull(),
     createdAt: instant("created_at").notNull(),
     settledAt: instant("settled_at"),
+    consumedAmount: integer("consumed_amount").notNull().default(0),
+    releasedAt: instant("released_at"),
 }, (t) => [index(CAP_RESERVATIONS_TENANT_CAP_EXPIRES_INDEX).on(t.tenantId, t.capName, t.expiresAt)]);
 export const capReservationsTableMeta = defineUnmanagedTable({
     tableName: "store_cap_reservations",
@@ -35,5 +40,7 @@ export const capReservationsTableMeta = defineUnmanagedTable({
         { name: "expires_at", pgType: "timestamptz", notNull: true },
         { name: "created_at", pgType: "timestamptz", notNull: true },
         { name: "settled_at", pgType: "timestamptz", notNull: false },
+        { name: "consumed_amount", pgType: "integer", notNull: true, defaultSql: "0" },
+        { name: "released_at", pgType: "timestamptz", notNull: false },
     ],
 });

package/dist/cap-overview/handlers/caps-usage.query.js

@@ -1,5 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import { buildEntityTable, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler, mayOverrideTenant, } from "@cosmicdrift/kumiko-framework/engine";
 import { AccessDeniedError, FrameworkReasons, InternalError, } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";

package/dist/cap-overview/handlers/tenant-caps-list.query.js

@@ -1,5 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { buildEntityTable, decodeCursor, encodeCursor } from "@cosmicdrift/kumiko-framework/db";
+import { buildEntityTable, decodeCursor, encodeCursor, selectMany, } from "@cosmicdrift/kumiko-framework/db";
 import { definePagedQueryHandler, MAX_LIST_LIMIT, } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";

package/dist/cap-overview/handlers/tenant-options.query.js

@@ -1,4 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";

package/dist/channel-email/email-channel.d.ts

@@ -2,15 +2,23 @@ import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { type ChannelContext, type DeliveryChannel, type EmailAttachmentRef } from "../delivery/index.js";
 import type { EmailTransport } from "./types.js";
 export declare function fileAttachmentsFrom(data: Readonly<Record<string, unknown>> | undefined, messageLocale?: string): readonly EmailAttachmentRef[];
-export type EmailChannelOptions = {
-    /** The app-wide transport, used for every tenant `tenantTransport` returns null for. */
+/** Resolves the sending tenant's own transport, null when it has none. Built per send and
+ *  never cached, so a provider change applies to the next mail; a throw fails the send. */
+export type TenantTransportResolver = (ctx: ChannelContext) => Promise<EmailTransport | null>;
+type EmailChannelTransports = {
+    /** The app-wide transport for every mail that does not go through a tenant transport. */
     readonly transport: EmailTransport;
-    /** Resolves the sending tenant's own transport, null when it has none. Built per send and
-     *  never cached, so a provider change applies to the next mail; a throw fails the send. */
-    readonly tenantTransport?: (ctx: ChannelContext) => Promise<EmailTransport | null>;
+    /** Used only for notifications declared with `tenantTransport: true`. */
+    readonly tenantTransport?: TenantTransportResolver;
+} | {
+    readonly transport?: undefined;
+    readonly tenantTransport: TenantTransportResolver;
+};
+export type EmailChannelOptions = EmailChannelTransports & {
     readonly resolveEmail: (userId: string, ctx: {
         db: unknown;
         tenantId: TenantId;
     }) => Promise<string | null>;
 };
 export declare function createEmailChannel(options: EmailChannelOptions): DeliveryChannel;
+export {};

package/dist/channel-email/email-channel.js

@@ -1,7 +1,7 @@
 import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-framework/crypto";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import * as z from "zod";
-import { DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, DELIVERY_UNSUBSCRIBE_PATH, EMAIL_CHANNEL_NAME, fileAttachmentRefSchema, MAX_EMAIL_ATTACHMENTS, renderedPdfAttachmentRefSchema, } from "../delivery/index.js";
+import { currentNotificationType, DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, DELIVERY_UNSUBSCRIBE_PATH, EMAIL_CHANNEL_NAME, fileAttachmentRefSchema, MAX_EMAIL_ATTACHMENTS, renderedPdfAttachmentRefSchema, } from "../delivery/index.js";
 import { decryptStoredPii, extensionForResourceContentType } from "../shared/index.js";
 import { guardEmailMessage } from "./pii-guard.js";
 // Envelope (From / Reply-To / threading headers) rides on the channel data —
@@ -121,6 +121,10 @@ async function resolveAttachments(sources, ctx) {
     }
     return { kind: "resolved", attachments: resolved };
 }
+function isTenantTransportNotification(ctx, notificationType) {
+    const current = currentNotificationType(ctx.registry, notificationType);
+    return ctx.registry.getAllNotifications().get(current)?.tenantTransport === true;
+}
 export function createEmailChannel(options) {
     const { transport, resolveEmail, tenantTransport } = options;
     // Render runs in the delivery.render job, decoupled from the SMTP send so
@@ -150,9 +154,11 @@ export function createEmailChannel(options) {
             ...(attachments !== undefined && { attachments }),
         };
     }
-    async function transportFor(ctx) {
+    async function transportFor(message, ctx) {
         if (tenantTransport === undefined)
             return transport;
+        if (!isTenantTransportNotification(ctx, message.notificationType))
+            return transport;
         return (await tenantTransport(ctx)) ?? transport;
     }
     return {
@@ -189,7 +195,15 @@ export function createEmailChannel(options) {
                 return { status: "failed", error: "send_failed", address };
             }
             const resolvedAttachments = resolution.attachments;
-            const sendTransport = await transportFor(ctx);
+            const sendTransport = await transportFor(message, ctx);
+            if (sendTransport === undefined) {
+                // Configuration, not a transient error: a retry cannot conjure a transport.
+                createFallbackLogger("delivery").warn("no mail transport for this mail, send failed", {
+                    tenantId: ctx.tenantId,
+                    notificationType: message.notificationType,
+                });
+                return { status: "failed", error: "missing_credentials", address };
+            }
             await sendTransport.send(guardEmailMessage({
                 to: address,
                 subject,

package/dist/channel-email/feature.js

@@ -4,7 +4,7 @@ import { createEmailChannel } from "./email-channel.js";
 export function createChannelEmailFeature(options) {
     const channel = createEmailChannel(options);
     return defineFeature("channel-email", (r) => {
-        r.describe("Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send each tenant's mail through its own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.");
+        r.describe("Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send the notifications declared with `tenantTransport: true` through the sending tenant's own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`; every other notification (password reset, sign-in) always goes through the app `transport`. `transport` may be left out when `tenantTransport` is set; a mail that then has no transport fails with `missing_credentials`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.");
         r.uiHints({
             displayLabel: "Email Channel",
             category: "notifications",

package/dist/channel-email/index.d.ts

@@ -1,4 +1,4 @@
-export { createEmailChannel, type EmailChannelOptions } from "./email-channel.js";
+export { createEmailChannel, type EmailChannelOptions, type TenantTransportResolver, } from "./email-channel.js";
 export { createChannelEmailFeature } from "./feature.js";
 export { guardEmailMessage, withPiiCiphertextGuard } from "./pii-guard.js";
 export { createSmtpTransport, createSmtpTransportFromEnv, type SmtpEnv, type SmtpTransportOptions, } from "./smtp-transport.js";

package/dist/channel-email/index.js

@@ -1,4 +1,4 @@
-export { createEmailChannel } from "./email-channel.js";
+export { createEmailChannel, } from "./email-channel.js";
 export { createChannelEmailFeature } from "./feature.js";
 export { guardEmailMessage, withPiiCiphertextGuard } from "./pii-guard.js";
 export { createSmtpTransport, createSmtpTransportFromEnv, } from "./smtp-transport.js";

package/dist/channel-in-app/handlers/inbox.query.js

@@ -1,4 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { inAppMessagesTable } from "../tables.js";

package/dist/channel-in-app/handlers/mark-all-read.write.js

@@ -1,4 +1,4 @@
-import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { updateMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { inAppMessagesTable } from "../tables.js";