@cosmicdrift/kumiko-bundled-features 0.357.0 → 0.359.0

package/dist/cap-counter/book-cap-usage.d.ts

@@ -1,5 +1,5 @@
 import { type TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import { type HandlerContext, type SessionUser, type TenantId, type WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import { type HandlerContext, type JobContext, type SessionUser, type TenantId, type WriteResult } from "@cosmicdrift/kumiko-framework/engine";
 export declare function retryCounterWriteOnVersionConflict(writeAttempt: () => Promise<WriteResult>): Promise<WriteResult>;
 export declare function retryOnStreamVersionConflict<T>(attempt: () => Promise<T>): Promise<T>;
 export type BookCapUsageOptions = {
@@ -9,16 +9,22 @@ export type BookCapUsageOptions = {
     readonly outsideTransaction?: boolean;
     readonly guardCurrentValue?: (currentValue: number) => void;
 };
-export declare function requireOutsideTransactionDb(ctx: HandlerContext): TenantDb;
-export declare function bookCapUsage(ctx: HandlerContext, options: BookCapUsageOptions): Promise<WriteResult>;
-export declare function releaseCapUsage(ctx: HandlerContext, options: Omit<BookCapUsageOptions, "guardCurrentValue">): Promise<WriteResult>;
+export type CapCounterContext = HandlerContext | JobContext;
+export type CapCounterScope = {
+    readonly user: SessionUser;
+    readonly readDb: TenantDb;
+    readonly writeDb: TenantDb;
+};
+export declare function resolveCapCounterScope(ctx: CapCounterContext, outsideTransaction: boolean): CapCounterScope;
+export declare function bookCapUsage(ctx: CapCounterContext, options: BookCapUsageOptions): Promise<WriteResult>;
+export declare function releaseCapUsage(ctx: CapCounterContext, options: Omit<BookCapUsageOptions, "guardCurrentValue">): Promise<WriteResult>;
 export declare function applyCapDeltaOn(db: TenantDb, user: SessionUser, options: BookCapUsageOptions, direction: "add" | "subtract"): Promise<WriteResult>;
 export type MarkCapSoftWarnedOptions = {
     readonly capName: string;
     readonly periodStartIso: string;
     readonly outsideTransaction?: boolean;
 };
-export declare function markCapSoftWarned(ctx: HandlerContext, options: MarkCapSoftWarnedOptions): Promise<WriteResult>;
+export declare function markCapSoftWarned(ctx: CapCounterContext, options: MarkCapSoftWarnedOptions): Promise<WriteResult>;
 export type ReadRollingCapUsageOptions = {
     readonly capName: string;
     readonly windowDays: number;

package/dist/cap-counter/book-cap-usage.js

@@ -1,6 +1,7 @@
 // In-process cap booking for the caller's own tenant; no SystemAdmin dispatch needed.
 import { runInOwnTransaction } from "@cosmicdrift/kumiko-framework/db";
 import { createEntityExecutor, } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
 import { eventsTable, VersionConflictError } from "@cosmicdrift/kumiko-framework/event-store";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
@@ -48,11 +49,51 @@ export async function retryOnStreamVersionConflict(attempt) {
         }
     }
 }
-export function requireOutsideTransactionDb(ctx) {
-    if (!ctx.dbOutsideTransaction) {
-        throw new Error("cap-counter.bookCapUsage: outsideTransaction requested but ctx.dbOutsideTransaction is undefined");
+// A tenant-mode db pins every row it writes to its own tenant; counter and reservation row would
+// silently land on different tenants if that is not the user's.
+function assertDbServesUser(db, user) {
+    if (db.mode === "tenant" && db.tenantId !== user.tenantId) {
+        throw new AccessDeniedError({
+            message: "cap-counter: the context's database belongs to a different tenant than its user",
+        });
     }
-    return ctx.dbOutsideTransaction;
+    return db;
+}
+// Jobs write in place (their db is not transaction-bound); systemScope handlers reach both dbs via
+// systemDb, because their ctx.db / ctx.dbOutsideTransaction are fail-closed proxies.
+export function resolveCapCounterScope(ctx, outsideTransaction) {
+    // A job context spread into a handler-shaped one (user set) is a handler context: its user, not
+    // the job's systemUser, names the metered tenant.
+    if (!("user" in ctx) || !ctx.user) {
+        const jobUser = "systemUser" in ctx ? ctx.systemUser : undefined;
+        if (!jobUser) {
+            throw new Error("cap-counter: ctx.user.tenantId missing — required to resolve the counter");
+        }
+        const db = assertDbServesUser(ctx.db, jobUser);
+        return { user: jobUser, readDb: db, writeDb: db };
+    }
+    const { user } = ctx;
+    if (!user.tenantId) {
+        throw new Error("cap-counter: ctx.user.tenantId missing — required to resolve the counter");
+    }
+    if (ctx.systemDb) {
+        const readDb = ctx.systemDb.assertTenantMatch(user.tenantId);
+        const writeDb = outsideTransaction
+            ? ctx.systemDb.outsideTransaction.assertTenantMatch(user.tenantId)
+            : readDb;
+        return { user, readDb, writeDb };
+    }
+    const writeDb = outsideTransaction ? ctx.dbOutsideTransaction : ctx.db;
+    if (!writeDb) {
+        throw new Error(outsideTransaction
+            ? "cap-counter: outsideTransaction requested but ctx.dbOutsideTransaction is undefined"
+            : "cap-counter: ctx.db missing — run inside a handler context");
+    }
+    return {
+        user,
+        readDb: assertDbServesUser(ctx.db, user),
+        writeDb: assertDbServesUser(writeDb, user),
+    };
 }
 export async function bookCapUsage(ctx, options) {
     return applyCapDelta(ctx, options, "add");
@@ -96,19 +137,20 @@ export async function applyCapDeltaOn(db, user, options, direction) {
     }, user, db);
 }
 async function applyCapDelta(ctx, options, direction) {
+    const { user, writeDb } = resolveCapCounterScope(ctx, options.outsideTransaction === true);
     if (options.outsideTransaction) {
-        const outsideDb = requireOutsideTransactionDb(ctx);
-        return retryCounterWriteOnVersionConflict(() => runInOwnTransaction(outsideDb, (txDb) => applyCapDeltaOn(txDb, ctx.user, options, direction)));
+        return retryCounterWriteOnVersionConflict(() => runInOwnTransaction(writeDb, (txDb) => applyCapDeltaOn(txDb, user, options, direction)));
     }
-    return retryCounterWriteOnVersionConflict(() => applyCapDeltaOn(ctx.db, ctx.user, options, direction));
+    return retryCounterWriteOnVersionConflict(() => applyCapDeltaOn(writeDb, user, options, direction));
 }
 export async function markCapSoftWarned(ctx, options) {
     const parsed = capPeriodSchema.parse(options);
-    const aggregateId = capCounterAggregateId(ctx.user.tenantId, parsed.capName, parsed.periodStartIso);
+    const { user, writeDb } = resolveCapCounterScope(ctx, options.outsideTransaction === true);
+    const aggregateId = capCounterAggregateId(user.tenantId, parsed.capName, parsed.periodStartIso);
     async function attemptMark(db) {
         const existing = await db.selectMany(table, { id: aggregateId }, { limit: 1 });
         if (existing.length === 0) {
-            throw new Error(`cap-counter: cannot mark-soft-warned, no counter found for tenant=${ctx.user.tenantId} cap=${parsed.capName} period=${parsed.periodStartIso}`);
+            throw new Error(`cap-counter: cannot mark-soft-warned, no counter found for tenant=${user.tenantId} cap=${parsed.capName} period=${parsed.periodStartIso}`);
         }
         const row = existing[0];
         if (!row) {
@@ -124,13 +166,12 @@ export async function markCapSoftWarned(ctx, options) {
             id: aggregateId,
             version: currentVersion,
             changes: { lastSoftWarnedAt: Temporal.Now.instant() },
-        }, ctx.user, db);
+        }, user, db);
     }
     if (options.outsideTransaction) {
-        const outsideDb = requireOutsideTransactionDb(ctx);
-        return retryCounterWriteOnVersionConflict(() => runInOwnTransaction(outsideDb, attemptMark));
+        return retryCounterWriteOnVersionConflict(() => runInOwnTransaction(writeDb, attemptMark));
     }
-    return retryCounterWriteOnVersionConflict(() => attemptMark(ctx.db));
+    return retryCounterWriteOnVersionConflict(() => attemptMark(writeDb));
 }
 async function sumRollingEventAmounts(db, tenantId, options, type) {
     const aggregateId = rollingCapAggregateId(tenantId, options.capName);

package/dist/cap-counter/calendar-cap-usage-reservation.d.ts

@@ -0,0 +1,17 @@
+import type { CapCounterContext } from "./book-cap-usage.js";
+import { type CalendarCapReservation } from "./cap-reservation.js";
+import { type SoftHitNotifier } from "./enforce-cap.js";
+import type { CalendarCapDef } from "./with-cap-enforcement.js";
+export type CalendarCapUsageReservationSpec = Omit<CalendarCapDef, "amount" | "notify"> & {
+    readonly amount: number;
+    readonly notify?: SoftHitNotifier;
+    readonly outsideTransaction?: boolean;
+};
+export type CalendarCapUsageReservation = {
+    readonly amount: number;
+    readonly counterValue: number;
+    settle(actualAmount: number): Promise<void>;
+    release(): Promise<void>;
+};
+export declare function reserveEnforcedCalendarCap(ctx: CapCounterContext, cap: CalendarCapUsageReservationSpec): Promise<CalendarCapReservation>;
+export declare function reserveCalendarCapUsage(ctx: CapCounterContext, spec: CalendarCapUsageReservationSpec): Promise<CalendarCapUsageReservation>;

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

@@ -0,0 +1,53 @@
+import { releaseExpiredCapReservations, reserveCalendarCap, settleCalendarCapReservation, } from "./cap-reservation.js";
+import { assertBelowHardCap, enforceCapAndMaybeNotify, } from "./enforce-cap.js";
+// Shared by withCapEnforcement and the public reservation API so both enforce identically.
+export async function reserveEnforcedCalendarCap(ctx, cap) {
+    const outsideTransaction = cap.outsideTransaction ?? true;
+    await releaseExpiredCapReservations(ctx, cap.capName, outsideTransaction);
+    if (cap.notify) {
+        await enforceCapAndMaybeNotify(ctx, {
+            capName: cap.capName,
+            periodStartIso: cap.periodStartIso,
+            limit: cap.limit,
+            profile: cap.profile,
+            notify: cap.notify,
+            amount: cap.amount,
+            markSoftWarnedOutsideTransaction: outsideTransaction,
+        });
+    }
+    return reserveCalendarCap(ctx, {
+        capName: cap.capName,
+        amount: cap.amount,
+        periodStartIso: cap.periodStartIso,
+        guardCurrentValue: (currentValue) => assertBelowHardCap(currentValue + cap.amount - 1, cap),
+    }, outsideTransaction);
+}
+export async function reserveCalendarCapUsage(ctx, spec) {
+    const outsideTransaction = spec.outsideTransaction ?? true;
+    const reservation = await reserveEnforcedCalendarCap(ctx, spec);
+    let state = "open";
+    return {
+        amount: spec.amount,
+        counterValue: reservation.counterValue,
+        async settle(actualAmount) {
+            if (state !== "open") {
+                throw new Error(`cap-counter: reservation for "${spec.capName}" is already ${state}`);
+            }
+            state = "settled";
+            try {
+                await settleCalendarCapReservation(ctx, reservation.reservationId, { capName: spec.capName, periodStartIso: spec.periodStartIso, actualAmount }, outsideTransaction);
+            }
+            catch (error) {
+                state = "open";
+                throw error;
+            }
+        },
+        async release() {
+            // skip: release after settle, or a second release, is a no-op by contract.
+            if (state !== "open")
+                return;
+            await reservation.release();
+            state = "released";
+        },
+    };
+}

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

@@ -1,12 +1,21 @@
-import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import type { ReservationHandle } from "@cosmicdrift/kumiko-types/handlers";
-import { type BookCapUsageOptions, type ReadRollingCapUsageOptions } from "./book-cap-usage.js";
+import { type BookCapUsageOptions, type CapCounterContext, type ReadRollingCapUsageOptions } from "./book-cap-usage.js";
+export type CalendarCapReservation = ReservationHandle & {
+    readonly reservationId: string;
+    readonly counterValue: number;
+};
 export type ReserveCalendarCapOptions = Required<Pick<BookCapUsageOptions, "capName" | "periodStartIso" | "amount">> & Pick<BookCapUsageOptions, "guardCurrentValue">;
-export declare function reserveCalendarCap(ctx: HandlerContext, options: ReserveCalendarCapOptions): Promise<ReservationHandle>;
+export declare function reserveCalendarCap(ctx: CapCounterContext, options: ReserveCalendarCapOptions, outsideTransaction?: boolean): Promise<CalendarCapReservation>;
 export type ReserveRollingCapOptions = ReadRollingCapUsageOptions & {
     readonly amount: number;
     readonly guardCurrentValue?: (currentValue: number) => void;
 };
-export declare function reserveRollingCap(ctx: HandlerContext, options: ReserveRollingCapOptions): Promise<ReservationHandle>;
-export declare function releaseCapReservation(ctx: HandlerContext, id: string): Promise<void>;
-export declare function releaseExpiredCapReservations(ctx: HandlerContext, capName: string): Promise<void>;
+export declare function reserveRollingCap(ctx: CapCounterContext, options: ReserveRollingCapOptions, outsideTransaction?: boolean): Promise<ReservationHandle>;
+export declare function releaseCapReservation(ctx: CapCounterContext, id: string, outsideTransaction?: boolean): Promise<void>;
+export type SettleCalendarCapOptions = {
+    readonly capName: string;
+    readonly periodStartIso: string;
+    readonly actualAmount: number;
+};
+export declare function settleCalendarCapReservation(ctx: CapCounterContext, id: string, options: SettleCalendarCapOptions, outsideTransaction?: boolean): Promise<void>;
+export declare function releaseExpiredCapReservations(ctx: CapCounterContext, capName: string, outsideTransaction?: boolean): Promise<void>;

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

@@ -4,14 +4,15 @@ import { appendEventInTenantDb, getStreamVersionInTenantDb, } from "@cosmicdrift
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { rollingCapAggregateId } from "./aggregate-id.js";
-import { applyCapDeltaOn, readRollingCapUsage, requireOutsideTransactionDb, retryCounterWriteOnVersionConflict, retryOnStreamVersionConflict, } from "./book-cap-usage.js";
+import { applyCapDeltaOn, readRollingCapUsage, resolveCapCounterScope, retryCounterWriteOnVersionConflict, retryOnStreamVersionConflict, } from "./book-cap-usage.js";
 import { CAP_COUNTER_ROLLING_AGGREGATE_TYPE, CAP_RESERVATION_TTL_MINUTES, ROLLING_INCREMENTED_EVENT_QN, ROLLING_RELEASED_EVENT_QN, } from "./constants.js";
 import { capReservationsTable } from "./tables.js";
 const NOTHING_TO_RELEASE = { isSuccess: true, data: {} };
-async function insertReservationRow(txDb, id, draft) {
+async function insertReservationRow(txDb, user, id, draft) {
     const now = Temporal.Now.instant();
     await txDb.insertOne(capReservationsTable, {
         id,
+        tenantId: user.tenantId,
         capName: draft.capName,
         kind: draft.kind,
         periodStartIso: draft.periodStartIso ?? null,
@@ -20,22 +21,31 @@ async function insertReservationRow(txDb, id, draft) {
         createdAt: now,
     });
 }
-function toHandle(ctx, id) {
+function toHandle(ctx, id, outsideTransaction) {
     return {
-        release: () => releaseCapReservation(ctx, id),
+        release: () => releaseCapReservation(ctx, id, outsideTransaction),
         confirmInTransaction: (confirm) => confirmCapReservation(confirm, id),
     };
 }
 // The counter increment and the reservation row commit together, so a booked amount never exists
 // without a row that can give it back.
-export async function reserveCalendarCap(ctx, options) {
-    const outsideDb = requireOutsideTransactionDb(ctx);
+export async function reserveCalendarCap(ctx, options, outsideTransaction = true) {
+    const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
     const id = generateId();
-    const reserved = await retryCounterWriteOnVersionConflict(() => runInOwnTransaction(outsideDb, async (txDb) => {
-        const booked = await applyCapDeltaOn(txDb, ctx.user, options, "add");
+    // The last attempt is the one that committed, so this holds the value its increment started from.
+    let valueBeforeBooking = 0;
+    const observedOptions = {
+        ...options,
+        guardCurrentValue: (currentValue) => {
+            options.guardCurrentValue?.(currentValue);
+            valueBeforeBooking = currentValue;
+        },
+    };
+    const reserved = await retryCounterWriteOnVersionConflict(() => runInOwnTransaction(writeDb, async (txDb) => {
+        const booked = await applyCapDeltaOn(txDb, user, observedOptions, "add");
         if (!booked.isSuccess)
             return booked;
-        await insertReservationRow(txDb, id, {
+        await insertReservationRow(txDb, user, id, {
             capName: options.capName,
             kind: "calendar",
             periodStartIso: options.periodStartIso,
@@ -45,7 +55,11 @@ export async function reserveCalendarCap(ctx, options) {
     }));
     if (!reserved.isSuccess)
         throw reraiseAsKumikoError(reserved.error);
-    return toHandle(ctx, id);
+    return {
+        ...toHandle(ctx, id, outsideTransaction),
+        reservationId: id,
+        counterValue: valueBeforeBooking + options.amount,
+    };
 }
 function rollingEvent(user, capName, amount, expectedVersion, type) {
     return {
@@ -59,23 +73,23 @@ function rollingEvent(user, capName, amount, expectedVersion, type) {
 }
 // The append is version-guarded: a booker that read the usage before another one appended loses the
 // race and repeats the whole attempt, so the hard-cap check always sees the stream it appends to.
-export async function reserveRollingCap(ctx, options) {
-    const outsideDb = requireOutsideTransactionDb(ctx);
+export async function reserveRollingCap(ctx, options, outsideTransaction = true) {
+    const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
     const id = generateId();
-    const aggregateId = rollingCapAggregateId(ctx.user.tenantId, options.capName);
-    await retryOnStreamVersionConflict(() => runInOwnTransaction(outsideDb, async (txDb) => {
+    const aggregateId = rollingCapAggregateId(user.tenantId, options.capName);
+    await retryOnStreamVersionConflict(() => runInOwnTransaction(writeDb, async (txDb) => {
         const version = await getStreamVersionInTenantDb(txDb, aggregateId);
-        const usage = await readRollingCapUsage(txDb, ctx.user.tenantId, options);
+        const usage = await readRollingCapUsage(txDb, user.tenantId, options);
         options.guardCurrentValue?.(usage);
-        await appendEventInTenantDb(txDb, rollingEvent(ctx.user, options.capName, options.amount, version, ROLLING_INCREMENTED_EVENT_QN));
-        await insertReservationRow(txDb, id, {
+        await appendEventInTenantDb(txDb, rollingEvent(user, options.capName, options.amount, version, ROLLING_INCREMENTED_EVENT_QN));
+        await insertReservationRow(txDb, user, id, {
             capName: options.capName,
             kind: "rolling",
             amount: options.amount,
         });
         return NOTHING_TO_RELEASE;
     }));
-    return toHandle(ctx, id);
+    return toHandle(ctx, id, outsideTransaction);
 }
 // Deleting the row takes its row lock inside the handler transaction, so a release started after a
 // failed COMMIT waits for the real outcome and finds the row gone when the commit went through.
@@ -94,39 +108,74 @@ async function giveBackRolling(txDb, user, row) {
     return NOTHING_TO_RELEASE;
 }
 async function giveBackReservation(txDb, user, id) {
-    const row = await txDb.fetchOne(capReservationsTable, { id });
+    const ownRow = { id, tenantId: user.tenantId };
+    const row = await txDb.fetchOne(capReservationsTable, ownRow);
     if (!row)
         return NOTHING_TO_RELEASE;
-    // Waits for a confirm still holding the row; zero rows back means that confirm committed.
-    const claimed = await txDb.updateMany(capReservationsTable, { expiresAt: row.expiresAt }, { id });
-    if (claimed.length === 0)
+    const claimed = await claimReservationRow(txDb, user, row);
+    if (!claimed)
         return NOTHING_TO_RELEASE;
     const given = row.kind === "rolling"
         ? await giveBackRolling(txDb, user, row)
         : await giveBackCalendar(txDb, user, row);
     if (!given.isSuccess)
         return given;
-    await txDb.deleteMany(capReservationsTable, { id });
+    await txDb.deleteMany(capReservationsTable, ownRow);
     return given;
 }
-export async function releaseCapReservation(ctx, id) {
-    const outsideDb = requireOutsideTransactionDb(ctx);
-    const released = await retryOnStreamVersionConflict(() => retryCounterWriteOnVersionConflict(() => runInOwnTransaction(outsideDb, (txDb) => giveBackReservation(txDb, ctx.user, id))));
+// Waits for a confirm still holding the row; false means that confirm (or another release) won.
+async function claimReservationRow(txDb, user, row) {
+    const claimed = await txDb.updateMany(capReservationsTable, { expiresAt: row.expiresAt }, { id: row.id, tenantId: user.tenantId });
+    return claimed.length > 0;
+}
+export async function releaseCapReservation(ctx, id, outsideTransaction = true) {
+    const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
+    const released = await retryOnStreamVersionConflict(() => retryCounterWriteOnVersionConflict(() => runInOwnTransaction(writeDb, (txDb) => giveBackReservation(txDb, user, id))));
     if (!released.isSuccess)
         throw reraiseAsKumikoError(released.error);
 }
+function bookCalendarDelta(txDb, user, period, delta) {
+    if (delta === 0)
+        return Promise.resolve({ isSuccess: true, data: {} });
+    return applyCapDeltaOn(txDb, user, { ...period, amount: Math.abs(delta) }, delta > 0 ? "add" : "subtract");
+}
+// Replaces the reserved amount by the actual one in a single transaction. When the row is already
+// gone (swept or released), the reserved amount was given back, so the full actual amount is booked.
+export async function settleCalendarCapReservation(ctx, id, options, outsideTransaction = true) {
+    if (!Number.isInteger(options.actualAmount) || options.actualAmount < 0) {
+        throw new Error(`cap-counter: settle amount must be a non-negative integer, got ${options.actualAmount}`);
+    }
+    const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
+    const settled = await retryCounterWriteOnVersionConflict(() => runInOwnTransaction(writeDb, async (txDb) => {
+        const row = await txDb.fetchOne(capReservationsTable, {
+            id,
+            tenantId: user.tenantId,
+        });
+        const claimed = row ? await claimReservationRow(txDb, user, row) : false;
+        if (!row || !claimed) {
+            return bookCalendarDelta(txDb, user, options, options.actualAmount);
+        }
+        const booked = await bookCalendarDelta(txDb, user, options, options.actualAmount - row.amount);
+        if (!booked.isSuccess)
+            return booked;
+        await txDb.deleteMany(capReservationsTable, { id, tenantId: user.tenantId });
+        return booked;
+    }));
+    if (!settled.isSuccess)
+        throw reraiseAsKumikoError(settled.error);
+}
 // A failed release leaves its row behind; giving it back once the TTL passed bounds how long that
 // capacity stays counted.
-export async function releaseExpiredCapReservations(ctx, capName) {
-    const outsideDb = requireOutsideTransactionDb(ctx);
-    const expired = await outsideDb.selectMany(capReservationsTable, {
-        tenantId: ctx.user.tenantId,
+export async function releaseExpiredCapReservations(ctx, capName, outsideTransaction = true) {
+    const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
+    const expired = await writeDb.selectMany(capReservationsTable, {
+        tenantId: user.tenantId,
         capName,
         expiresAt: { lt: Temporal.Now.instant() },
     });
     for (const { id } of expired) {
         try {
-            await releaseCapReservation(ctx, id);
+            await releaseCapReservation(ctx, id, outsideTransaction);
         }
         catch (error) {
             ctx.log?.error("releasing an expired cap reservation failed", { id, capName, error });

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

@@ -1,6 +1,6 @@
-import { type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { KumikoError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { type CapCounterContext } from "./book-cap-usage.js";
 /**
  * Cap-Toleranz-Profile — pro Cap-Typ asymmetrisch. Quelle: Memory
  * `project_pricing_byok_caps` §3 + `docs/plans/marketing/produkt/
@@ -79,7 +79,7 @@ export declare function assertBelowHardCap(valueSeenByLastUnit: number, cap: {
  * (apps-count) need stricter serialization at the create-handler
  * level (e.g. uniqueness-index on apps.tenantId+slot-number).
  */
-export declare function enforceCap(ctx: HandlerContext, options: {
+export declare function enforceCap(ctx: CapCounterContext, options: {
     readonly capName: string;
     readonly periodStartIso: string;
     readonly limit: number;
@@ -110,7 +110,7 @@ export declare function enforceCap(ctx: HandlerContext, options: {
  * Projection mit pre-aggregierten daily-buckets. Heute nicht
  * vorgezogen.
  */
-export declare function enforceRollingCap(ctx: HandlerContext, options: {
+export declare function enforceRollingCap(ctx: CapCounterContext, options: {
     readonly capName: string;
     readonly windowDays: number;
     readonly limit: number;
@@ -162,7 +162,7 @@ export type SoftHitNotifier = (info: {
  * verzweigen (z.B. UI-Toast bei soft-hit zusätzlich zur
  * Email-Notification).
  */
-export declare function enforceCapAndMaybeNotify(ctx: HandlerContext, options: {
+export declare function enforceCapAndMaybeNotify(ctx: CapCounterContext, options: {
     readonly capName: string;
     readonly periodStartIso: string;
     readonly limit: number;
@@ -181,7 +181,7 @@ export declare function enforceCapAndMaybeNotify(ctx: HandlerContext, options: {
  * oder er ruft `enforceRollingCapAndMaybeNotify` nur einmal pro
  * Tag/Stunde auf (Hourly-Cron statt pro Request).
  */
-export declare function enforceRollingCapAndMaybeNotify(ctx: HandlerContext, options: {
+export declare function enforceRollingCapAndMaybeNotify(ctx: CapCounterContext, options: {
     readonly capName: string;
     readonly windowDays: number;
     readonly limit: number;

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

@@ -1,7 +1,7 @@
 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 { markCapSoftWarned, readRollingCapUsage, resolveCapCounterScope, } from "./book-cap-usage.js";
 import { capCounterEntity } from "./entity.js";
 const { table } = createEntityExecutor("cap-counter", capCounterEntity);
 export const CAP_TOLERANCES = {
@@ -45,16 +45,14 @@ export function assertBelowHardCap(valueSeenByLastUnit, cap) {
  * level (e.g. uniqueness-index on apps.tenantId+slot-number).
  */
 export async function enforceCap(ctx, options) {
-    if (!ctx.db) {
-        throw new Error("cap-counter.enforceCap: ctx.db missing — run inside a handler context");
-    }
+    const { user, readDb } = resolveCapCounterScope(ctx, false);
     const amount = options.amount ?? 1;
     if (!Number.isInteger(amount) || amount < 1) {
         throw new Error(`cap-counter.enforceCap: amount must be a positive integer, got ${options.amount}`);
     }
     const tolerance = CAP_TOLERANCES[options.profile];
     const softThreshold = options.limit * tolerance.soft;
-    const rows = await ctx.db.selectMany(table, { capName: options.capName, periodStart: options.periodStartIso }, { limit: 1 });
+    const rows = await readDb.selectMany(table, { tenantId: user.tenantId, capName: options.capName, periodStart: options.periodStartIso }, { limit: 1 });
     const row = rows[0];
     const storedValue = row ? row["value"] : 0; // @cast-boundary db-row
     // The last of `amount` units sees this value before its own increment.
@@ -94,16 +92,11 @@ export async function enforceCap(ctx, options) {
  * vorgezogen.
  */
 export async function enforceRollingCap(ctx, options) {
-    if (!ctx.db) {
-        throw new Error("cap-counter.enforceRollingCap: ctx.db missing — run inside a handler context");
-    }
-    if (!ctx.user?.tenantId) {
-        throw new Error("cap-counter.enforceRollingCap: ctx.user.tenantId missing — required to compute aggregate-id");
-    }
+    const { user, readDb } = resolveCapCounterScope(ctx, false);
     const tolerance = CAP_TOLERANCES[options.profile];
     const softThreshold = options.limit * tolerance.soft;
     const hardThreshold = options.limit * tolerance.hard;
-    const value = await readRollingCapUsage(ctx.db, ctx.user.tenantId, {
+    const value = await readRollingCapUsage(readDb, user.tenantId, {
         capName: options.capName,
         windowDays: options.windowDays,
     });
@@ -184,14 +177,11 @@ export async function enforceCapAndMaybeNotify(ctx, options) {
         ...(options.amount !== undefined && { amount: options.amount }),
     });
     if (result.state === "soft-hit" && result.crossed) {
-        if (!ctx.user?.tenantId) {
-            throw new Error("cap-counter.enforceCapAndMaybeNotify: ctx.user.tenantId missing — required for notification");
-        }
         await options.notify({
             capName: options.capName,
             value: result.value,
             limit: options.limit,
-            tenantId: ctx.user.tenantId,
+            tenantId: resolveCapCounterScope(ctx, false).user.tenantId,
         });
         // Flip the soft-warned flag so the same period doesn't re-notify.
         const marked = await markCapSoftWarned(ctx, {
@@ -222,14 +212,11 @@ export async function enforceRollingCapAndMaybeNotify(ctx, options) {
         profile: options.profile,
     });
     if (result.state === "soft-hit") {
-        if (!ctx.user?.tenantId) {
-            throw new Error("cap-counter.enforceRollingCapAndMaybeNotify: ctx.user.tenantId missing — required for notification");
-        }
         await options.notify({
             capName: options.capName,
             value: result.value,
             limit: options.limit,
-            tenantId: ctx.user.tenantId,
+            tenantId: resolveCapCounterScope(ctx, false).user.tenantId,
         });
     }
     return result;

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

@@ -1,5 +1,6 @@
 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 { 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";

package/dist/cap-counter/index.js

@@ -1,6 +1,7 @@
 // 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 { 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";

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

@@ -23,8 +23,9 @@
 //
 // No automatic markSoftWarned here — that's inside enforceCapAndMaybeNotify
 // (enforce-cap.ts).
-import { releaseExpiredCapReservations, reserveCalendarCap, reserveRollingCap, } from "./cap-reservation.js";
-import { assertBelowHardCap, enforceCapAndMaybeNotify, enforceRollingCapAndMaybeNotify, } from "./enforce-cap.js";
+import { reserveEnforcedCalendarCap } from "./calendar-cap-usage-reservation.js";
+import { releaseExpiredCapReservations, reserveRollingCap } from "./cap-reservation.js";
+import { assertBelowHardCap, enforceRollingCapAndMaybeNotify, } from "./enforce-cap.js";
 import { chainReservations } from "./reservation-chain.js";
 /**
  * Wrap a write-handler with calendar-period cap-enforcement.
@@ -41,23 +42,7 @@ export function withCapEnforcement(handler, capResolver) {
         ...handler,
         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,
-                limit: cap.limit,
-                profile: cap.profile,
-                notify: cap.notify,
-                markSoftWarnedOutsideTransaction: true,
-                ...(cap.amount !== undefined && { amount: cap.amount }),
-            });
-            const amount = cap.amount ?? 1;
-            return reserveCalendarCap(ctx, {
-                capName: cap.capName,
-                amount,
-                periodStartIso: cap.periodStartIso,
-                guardCurrentValue: (currentValue) => assertBelowHardCap(currentValue + amount - 1, cap),
-            });
+            return reserveEnforcedCalendarCap(ctx, { ...cap, amount: cap.amount ?? 1 });
         }),
     };
 }

package/dist/crypto-shredding/handlers/forget-subject.write.js

@@ -229,7 +229,6 @@ async function sweepDerivedSubjectData(ctx, subject, subjectKey, crossTenantRunn
             if (ctx.registry.features.has("notes-history")) {
                 await eraseNoteBodiesReachingSubject({
                     db: crossTenantSubjectRunner,
-                    registry: ctx.registry,
                     subject,
                     erasedBy: audit.erasedBy,
                     requestId: audit.requestId,

package/dist/custom-fields/handlers/update-tenant-field.write.js

@@ -4,13 +4,14 @@ import { fieldDefinitionAggregateId } from "../aggregate-id.js";
 import { DEFAULT_FIELD_DEFINITION_WRITE_ROLES } from "../constants.js";
 import { fieldDefinitionExecutor } from "../executor.js";
 import { buildFieldDefinitionColumns } from "../lib/field-definition-row.js";
-import { updateFieldPayloadSchema } from "../schemas.js";
+import { fieldTypeSchema, updateFieldPayloadSchema } from "../schemas.js";
 export function createUpdateTenantFieldHandler(opts = {}) {
     return {
         name: "update-tenant-field",
         schema: updateFieldPayloadSchema,
         access: { roles: opts.roles ?? DEFAULT_FIELD_DEFINITION_WRITE_ROLES },
-        description: "Replaces a tenant-owned custom-field definition with a complete new spec while refusing any change to the field's type; use it to relabel or re-constrain an existing field rather than to create or remove one.",
+        description: "Replaces a tenant-owned custom-field definition with a complete new spec; serializedField.type may be omitted, in which case the stored type applies, and a different type is refused. Use it to relabel or re-constrain an existing field rather than to create or remove one.",
+        excludedFields: ["type"],
         handler: async (event, ctx) => {
             const payload = event.payload; // @cast-boundary engine-payload
             const tenantId = event.user.tenantId;
@@ -22,16 +23,24 @@ export function createUpdateTenantFieldHandler(opts = {}) {
             if (!existing) {
                 return failNotFound("field-definition", aggregateId);
             }
-            if (existing["type"] !== payload.serializedField.type) {
+            const storedType = fieldTypeSchema.safeParse(existing["type"]);
+            if (!storedType.success) {
+                throw new Error(`update-tenant-field: stored definition ${aggregateId} has an invalid type`);
+            }
+            const requestedType = payload.serializedField.type;
+            if (requestedType !== undefined && requestedType !== storedType.data) {
                 return failUnprocessable("field_type_immutable", {
                     entityName: payload.entityName,
                     fieldKey: payload.fieldKey,
-                    currentType: existing["type"],
-                    requestedType: payload.serializedField.type,
+                    currentType: storedType.data,
+                    requestedType,
                 });
             }
             // entityName/fieldKey sind die Identität — nicht Teil der changes.
-            const { entityName: _entityName, fieldKey: _fieldKey, ...changes } = buildFieldDefinitionColumns(payload);
+            const { entityName: _entityName, fieldKey: _fieldKey, ...changes } = buildFieldDefinitionColumns({
+                ...payload,
+                serializedField: { ...payload.serializedField, type: storedType.data },
+            });
             return fieldDefinitionExecutor.update({ id: aggregateId, changes }, event.user, ctx.db, {
                 skipOptimisticLock: true,
             });

package/dist/custom-fields/schemas.d.ts

@@ -1,4 +1,13 @@
 import * as z from "zod";
+export declare const fieldTypeSchema: z.ZodEnum<{
+    boolean: "boolean";
+    date: "date";
+    embedded: "embedded";
+    enum: "enum";
+    money: "money";
+    number: "number";
+    text: "text";
+}>;
 export declare const customFieldAccessSchema: z.ZodOptional<z.ZodObject<{
     read: z.ZodOptional<z.ZodArray<z.ZodString>>;
     write: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -8,15 +17,6 @@ export declare const defineFieldPayloadSchema: z.ZodObject<{
     entityName: z.ZodString;
     fieldKey: z.ZodString;
     serializedField: z.ZodObject<{
-        type: z.ZodEnum<{
-            boolean: "boolean";
-            date: "date";
-            embedded: "embedded";
-            enum: "enum";
-            money: "money";
-            number: "number";
-            text: "text";
-        }>;
         fieldAccess: z.ZodOptional<z.ZodObject<{
             read: z.ZodOptional<z.ZodArray<z.ZodString>>;
             write: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -28,6 +28,15 @@ export declare const defineFieldPayloadSchema: z.ZodObject<{
                 delete: "delete";
             }>;
         }, z.core.$strip>>;
+        type: z.ZodEnum<{
+            boolean: "boolean";
+            date: "date";
+            embedded: "embedded";
+            enum: "enum";
+            money: "money";
+            number: "number";
+            text: "text";
+        }>;
     }, z.core.$loose>;
     required: z.ZodDefault<z.ZodBoolean>;
     searchable: z.ZodDefault<z.ZodBoolean>;
@@ -38,16 +47,11 @@ export type DefineFieldPayload = z.infer<typeof defineFieldPayloadSchema>;
 export declare const updateFieldPayloadSchema: z.ZodObject<{
     entityName: z.ZodString;
     fieldKey: z.ZodString;
+    required: z.ZodDefault<z.ZodBoolean>;
+    searchable: z.ZodDefault<z.ZodBoolean>;
+    displayOrder: z.ZodDefault<z.ZodNumber>;
+    label: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     serializedField: z.ZodObject<{
-        type: z.ZodEnum<{
-            boolean: "boolean";
-            date: "date";
-            embedded: "embedded";
-            enum: "enum";
-            money: "money";
-            number: "number";
-            text: "text";
-        }>;
         fieldAccess: z.ZodOptional<z.ZodObject<{
             read: z.ZodOptional<z.ZodArray<z.ZodString>>;
             write: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -59,13 +63,18 @@ export declare const updateFieldPayloadSchema: z.ZodObject<{
                 delete: "delete";
             }>;
         }, z.core.$strip>>;
+        type: z.ZodOptional<z.ZodEnum<{
+            boolean: "boolean";
+            date: "date";
+            embedded: "embedded";
+            enum: "enum";
+            money: "money";
+            number: "number";
+            text: "text";
+        }>>;
     }, z.core.$loose>;
-    required: z.ZodDefault<z.ZodBoolean>;
-    searchable: z.ZodDefault<z.ZodBoolean>;
-    displayOrder: z.ZodDefault<z.ZodNumber>;
-    label: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
-export type UpdateFieldPayload = DefineFieldPayload;
+export type UpdateFieldPayload = z.infer<typeof updateFieldPayloadSchema>;
 export declare const deleteFieldPayloadSchema: z.ZodObject<{
     entityName: z.ZodString;
     fieldKey: z.ZodString;

package/dist/custom-fields/schemas.js

@@ -1,7 +1,7 @@
 import * as z from "zod";
 import { SUPPORTED_FIELD_TYPES } from "./constants.js";
 // Field-Type-Validator — pinnt valid type-Werte für fieldDefinition.
-const fieldTypeSchema = z.enum(SUPPORTED_FIELD_TYPES);
+export const fieldTypeSchema = z.enum(SUPPORTED_FIELD_TYPES);
 // Per-field access-control. When set, `set/clear-custom-field` handlers
 // require the calling user to hold at least one of the listed roles —
 // in addition to the handler-level RBAC. Absent or empty `write` means
@@ -33,9 +33,7 @@ export const customFieldAccessSchema = z
 // Everything else stays loose pending B2's per-type discriminated-union —
 // EXCEPT `sensitive`, which is explicitly rejected below: custom fields
 // carry supplemental business data only, PII support was removed (#972).
-const serializedFieldSchema = z
-    .looseObject({
-    type: fieldTypeSchema,
+const serializedFieldBaseShape = {
     fieldAccess: customFieldAccessSchema,
     // `retention` (T1.5d): per-field expiry. The retention-cron strips
     // values whose host-row `modified_at` is older than `keepFor`. Strategy
@@ -50,9 +48,19 @@ const serializedFieldSchema = z
         strategy: z.enum(["delete", "anonymize"]),
     })
         .optional(),
-})
+};
+const rejectSensitive = [
+    (v) => !("sensitive" in v),
+    "custom fields don't support PII — `sensitive` was removed (#972). Model personal data as a schema entity field with a pii/userOwned/tenantOwned annotation instead.",
+];
+const serializedFieldSchema = z
+    .looseObject({ type: fieldTypeSchema, ...serializedFieldBaseShape })
     .refine((v) => typeof v["type"] === "string", "serializedField must have a string `type`")
-    .refine((v) => !("sensitive" in v), "custom fields don't support PII — `sensitive` was removed (#972). Model personal data as a schema entity field with a pii/userOwned/tenantOwned annotation instead.");
+    .refine(...rejectSensitive);
+// Update may omit `type`: it is immutable, so the handler takes it from the stored definition.
+const updateSerializedFieldSchema = z
+    .looseObject({ type: fieldTypeSchema.optional(), ...serializedFieldBaseShape })
+    .refine(...rejectSensitive);
 // i18n-labels — `{ de: "...", en: "...", ... }`. Mindestens ein Eintrag.
 const labelSchema = z.record(z.string().min(2).max(8), z.string().min(1));
 // Payload für `define-tenant-field` und `define-system-field` write-handler.
@@ -69,11 +77,13 @@ export const defineFieldPayloadSchema = z.object({
     displayOrder: z.number().int().min(0).default(0),
     label: labelSchema.optional(),
 });
-// Payload für `update-tenant-field` — bewusst dieselbe Shape wie define
-// (Vollersatz-Semantik: der Edit-Screen schickt den kompletten neuen Stand;
-// entityName+fieldKey sind die Identität, type ist immutable und wird im
-// Handler gegen den Bestand geprüft).
-export const updateFieldPayloadSchema = defineFieldPayloadSchema;
+// Payload for `update-tenant-field`: full replacement like define (the edit
+// screen sends the complete new state; entityName+fieldKey are the identity),
+// except that `serializedField.type` may be omitted. type is immutable; a
+// differing value is refused in the handler.
+export const updateFieldPayloadSchema = defineFieldPayloadSchema.extend({
+    serializedField: updateSerializedFieldSchema,
+});
 // Payload für `delete-tenant-field` / `delete-system-field`.
 export const deleteFieldPayloadSchema = z.object({
     entityName: z.string().min(1).max(64),

package/dist/jobs/job-run-logger.js

@@ -25,6 +25,14 @@ const DEFAULT_CACHE_MAX_ENTRIES = 10_000;
 // complete/failed; either way the cache entry has no value. Falls back
 // to DB-lookup if actually needed.
 const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+// Run rows hang on SYSTEM_TENANT_ID and a null trigger is a cron/system run;
+// job-run-table.ts declares whenAbsent: "tenant" for exactly that case, so the
+// logger must resolve the same subject the entity chain would (fw#3654).
+function jobRunSubject(triggeredById) {
+    return triggeredById === null
+        ? { kind: "tenant", tenantId: SYSTEM_TENANT_ID }
+        : { kind: "user", userId: triggeredById };
+}
 // Same per-subject encryption as encryptFailureError/encryptStartedPayload,
 // applied to a single value — shared so payload/message/error all go
 // through the identical erased-key fallback. A key erased right before (or
@@ -33,9 +41,9 @@ const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 // sentinel like decryptPiiValueForSubject does on the read side, instead of
 // throwing and dropping the rest of the batch — or, for onJobStart, the
 // whole run row.
-async function encryptOrSentinel(kms, subjectUserId, value, field) {
+async function encryptOrSentinel(kms, subject, value, field) {
     try {
-        return await encryptPiiValueForSubject(kms, { kind: "user", userId: subjectUserId }, value, { requestId: "jobs:job-run-logger" }, field);
+        return await encryptPiiValueForSubject(kms, subject, value, { requestId: "jobs:job-run-logger" }, field);
     }
     catch (e) {
         if (!(e instanceof KeyErasedError))
@@ -48,19 +56,18 @@ async function encryptOrSentinel(kms, subjectUserId, value, field) {
 // jobRunLogsTable — that table is unmanaged/direct-write, so there is no
 // event-piiFields catalog to lean on here either. "message" is the AAD
 // field name and must match the field passed to decryptStoredPii on read
-// (detail.query.ts) or decrypt fails loud. Same skip rules as the payload:
-// null subject (system/cron runs) and absent KMS (rollout mode) both stay
-// plaintext. Bounded concurrency (#2307) — unbounded Promise.all would fire
-// one getOrCreateDek per log line at once against the KMS adapter's pool.
+// (detail.query.ts) or decrypt fails loud. Same skip rule as the payload:
+// absent KMS (rollout mode) stays plaintext. Bounded concurrency (#2307) —
+// unbounded Promise.all would fire one getOrCreateDek per log line at once
+// against the KMS adapter's pool.
 async function encryptLogMessages(logs, triggeredById) {
-    if (triggeredById === null)
-        return [...logs];
     const kms = configuredPiiSubjectKms();
     if (!kms)
         return [...logs];
+    const subject = jobRunSubject(triggeredById);
     return mapWithConcurrency(logs, KMS_POOL_CONCURRENCY, async (log) => ({
         ...log,
-        message: await encryptOrSentinel(kms, triggeredById, log.message, "message"),
+        message: await encryptOrSentinel(kms, subject, log.message, "message"),
     }));
 }
 // Mirrors encryptFailureError for the failure-path `error` column (#2307):
@@ -70,29 +77,26 @@ async function encryptLogMessages(logs, triggeredById) {
 // separate, per-row batch path outside onJobFailed) applies the identical
 // per-subject encryption instead of writing `error` in the clear.
 export async function encryptFailureError(error, triggeredById) {
-    if (triggeredById === null)
-        return error;
     const kms = configuredPiiSubjectKms();
     if (!kms)
         return error;
-    return encryptOrSentinel(kms, triggeredById, error, "error");
+    return encryptOrSentinel(kms, jobRunSubject(triggeredById), error, "error");
 }
 // The run-started payload can carry arbitrary user data; triggeredById
 // names its owning user. No event-PII catalog involved (#2243 removed the
 // jobRun r.defineEvent registrations, so there is nothing to catalog) —
 // the subject is known statically, so we encrypt directly. A null subject
-// (system cron runs, recipient-less triggers) stays plaintext: there is no
-// user key to shred, mirroring the previous event-pii catalog's own skip
-// rule. Absent KMS adapter stays plaintext too (rollout mode, unchanged).
+// (system cron runs, recipient-less triggers) encrypts under the system
+// tenant key. Absent KMS adapter stays plaintext (rollout mode, unchanged).
 // A key already erased by the time the trigger lands (#2307) must not fail
 // the whole run-start write — sentinel like the log/error paths.
 async function encryptStartedPayload(payload, triggeredById) {
-    if (payload === null || triggeredById === null)
+    if (payload === null)
         return payload;
     const kms = configuredPiiSubjectKms();
     if (!kms)
         return payload;
-    return encryptOrSentinel(kms, triggeredById, payload, "payload");
+    return encryptOrSentinel(kms, jobRunSubject(triggeredById), payload, "payload");
 }
 // pg_advisory_xact_lock namespace (int4): 'tjfl' as ASCII, disjoint from the
 // framework's other fixed advisory-lock keys.

package/dist/jobs/job-run-table.js

@@ -29,11 +29,18 @@ export const jobRunEntity = createEntity({
         status: createTextField({ required: true, personal: false, reason: "system_metadata" }),
         // The run-started payload can carry arbitrary caller-supplied data,
         // encrypted by job-run-logger.ts under the triggering user's DEK (see
-        // jobs-pii-kms.integration.test.ts) — same subject as `triggeredById`.
-        payload: createTextField({ personal: { of: "triggeredById" }, find: "none" }),
+        // jobs-pii-kms.integration.test.ts) — same subject as `triggeredById`;
+        // cron runs have none and use the system tenant key (whenAbsent).
+        payload: createTextField({
+            personal: { of: "triggeredById", whenAbsent: "tenant" },
+            find: "none",
+        }),
         // Failure messages can echo payload content back — same subject/DEK as
         // `payload` (job-run-logger.ts encryptFailureError).
-        error: createTextField({ personal: { of: "triggeredById" }, find: "none" }),
+        error: createTextField({
+            personal: { of: "triggeredById", whenAbsent: "tenant" },
+            find: "none",
+        }),
         attempt: createNumberField({ required: true, default: 1, integer: true }),
         startedAt: createTimestampField({ required: true }),
         finishedAt: createTimestampField(),

package/dist/notes-history/entity.js

@@ -67,9 +67,10 @@ export function createNoteEntryEntity(access, parents) {
             }),
             // Stamped once at write time, never re-resolved later — the history
             // needs the name as it was then, not whatever the account is called now.
+            // whenAbsent: authorless notes (system-written) encrypt under the tenant key.
             authorName: createTextField({
                 maxLength: 200,
-                personal: { of: "authorId" },
+                personal: { of: "authorId", whenAbsent: "tenant" },
                 find: "none",
             }),
             body: createLongTextField({

package/dist/notes-history-user-data/hooks.d.ts

@@ -1,10 +1,9 @@
 import { type SubjectId } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import type { Registry, UserDataDeleteHook, UserDataExportHook } from "@cosmicdrift/kumiko-framework/engine";
+import type { UserDataDeleteHook, UserDataExportHook } from "@cosmicdrift/kumiko-framework/engine";
 export declare const noteEntryExportHook: UserDataExportHook;
 export declare function eraseNoteBodiesReachingSubject(args: {
     readonly db: DbRunner | TenantDb;
-    readonly registry: Registry;
     readonly subject: SubjectId;
     readonly erasedBy: string;
     readonly requestId: string;

package/dist/notes-history-user-data/hooks.js

@@ -5,9 +5,7 @@
 // export-only, erasure via crypto-shredding.
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { configuredPiiSubjectKms } from "@cosmicdrift/kumiko-framework/crypto";
-import { resolveRetentionPolicyForTenant, resolveTenantRetentionPreset, } from "../data-retention/index.js";
 import { noteEntryTable, noteMentionTable } from "../notes-history/index.js";
-import { policyToStrategy } from "../user-data-rights/index.js";
 // note-entry has no per-tenant scope quirk (unlike folders) — it's genuinely
 // per-user content, so the export filters by authorId directly.
 export const noteEntryExportHook = async (ctx) => {
@@ -56,10 +54,9 @@ async function selectNotesReachingSubject(db, subject) {
 // @-mentions the subject (`note-mention`, fw#2787) or hangs on it as host.
 // Free-text mentions are NOT detected — the documented gap in entity.ts.
 //
-// Per reached note the HOST entity's retention strategy (entityType, resolved
-// for the note's own tenant — the manual forget-subject path runs cross-tenant)
-// is consulted first: anonymize/blockDelete win over erasure, same rule the
-// automated forget-cleanup applies to every other entity.
+// Reached bodies are shredded regardless of the host entity's retention strategy:
+// the note text is free-form PII, and a host's anonymize/blockDelete protects the
+// row, not its content, just like the host's own PII fields get anonymized.
 //
 // Without a mounted KMS this erases nothing: record-owned fields fall back to
 // plaintext framework-wide (see pii-field-encryption.ts), so apps that need
@@ -70,36 +67,7 @@ export async function eraseNoteBodiesReachingSubject(args) {
     if (!kms)
         return;
     const notes = await selectNotesReachingSubject(args.db, args.subject);
-    const dataRetentionMounted = args.registry.features.has("data-retention");
-    const presetByTenant = new Map();
-    const strategyByTenantAndEntityType = new Map();
     for (const note of notes) {
-        const strategyKey = `${note.tenantId}:${note.entityType}`;
-        let strategy = strategyByTenantAndEntityType.get(strategyKey);
-        if (strategy === undefined) {
-            let tenantPreset = presetByTenant.get(note.tenantId);
-            if (tenantPreset === undefined) {
-                tenantPreset = await resolveTenantRetentionPreset({
-                    db: args.db,
-                    registry: args.registry,
-                    tenantId: note.tenantId,
-                });
-                presetByTenant.set(note.tenantId, tenantPreset);
-            }
-            const hostPolicy = await resolveRetentionPolicyForTenant({
-                db: args.db,
-                registry: args.registry,
-                tenantId: note.tenantId,
-                entityName: note.entityType,
-                preloadedTenantPreset: tenantPreset,
-                // Without data-retention there is no override table to read.
-                ...(!dataRetentionMounted && { preloadedOverride: null }),
-            });
-            strategy = policyToStrategy(hostPolicy.policy?.strategy ?? null);
-            strategyByTenantAndEntityType.set(strategyKey, strategy);
-        }
-        if (strategy === "anonymize")
-            continue;
         await kms.eraseKey({ kind: "record", entity: "note-entry", id: note.id }, {
             requestId: args.requestId,
             userId: args.erasedBy,
@@ -110,7 +78,6 @@ export async function eraseNoteBodiesReachingSubject(args) {
 export const noteEntryDeleteHook = async (ctx) => {
     await eraseNoteBodiesReachingSubject({
         db: ctx.db,
-        registry: ctx.registry,
         subject: { kind: "user", userId: ctx.userId },
         erasedBy: ctx.userId,
         requestId: "notes-history-user-data:forget-reached-notes",

package/dist/notes-history-user-data/index.js

@@ -8,7 +8,7 @@ import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engi
 import { noteEntryDeleteHook, noteEntryExportHook, noteMentionDeleteHook, noteMentionExportHook, } from "./hooks.js";
 export { eraseNoteBodiesReachingSubject } from "./hooks.js";
 export const notesHistoryUserDataFeature = defineFeature("notes-history-user-data", (r) => {
-    r.describe("GDPR (Art. 20 export / Art. 17 erasure) coverage for the `notes-history` feature's `note-entry` and `note-mention` entities. Mounts the export hook so a user's authored notes are included in the user-data export bundle; the note-entry delete hook crypto-shreds the row-subject key of each note that structurally @-mentions the forgotten user (`note-mention`) or hangs on the user as host entity (after consulting that note's host entity's retention strategy — blockDelete/anonymize win over erasure), keeping the append-only history intact for all other notes. The manual `crypto-shredding` forget-subject command reaches the same notes for user and record subjects through the exported `eraseNoteBodiesReachingSubject`, and the export lists them under `note-mention`. `note-mention`'s own hooks are a no-op — it is a plain FK pointer, not separately exportable content. Kept separate from `notes-history` so notes consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `notes-history`.");
+    r.describe("GDPR (Art. 20 export / Art. 17 erasure) coverage for the `notes-history` feature's `note-entry` and `note-mention` entities. Mounts the export hook so a user's authored notes are included in the user-data export bundle; the note-entry delete hook crypto-shreds the row-subject key of each note that structurally @-mentions the forgotten user (`note-mention`) or hangs on the user as host entity (regardless of the host entity's retention strategy: the note text is free PII, the host's anonymize/blockDelete protects the row, not the content), keeping the append-only history intact for all other notes. The manual `crypto-shredding` forget-subject command reaches the same notes for user and record subjects through the exported `eraseNoteBodiesReachingSubject`, and the export lists them under `note-mention`. `note-mention`'s own hooks are a no-op — it is a plain FK pointer, not separately exportable content. Kept separate from `notes-history` so notes consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `notes-history`.");
     // user-data-rights is the hard dependency (EXT_USER_DATA host). notes-history
     // is OPTIONAL: if it's mounted toggleable(default=false), a hard r.requires
     // would throw an "effectively disabled" boot warning even though the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.357.0",
+  "version": "0.359.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -516,12 +516,12 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.357.0",
-    "@cosmicdrift/kumiko-framework": "0.357.0",
-    "@cosmicdrift/kumiko-headless": "0.357.0",
-    "@cosmicdrift/kumiko-renderer": "0.357.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.357.0",
-    "@cosmicdrift/kumiko-types": "0.357.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.359.0",
+    "@cosmicdrift/kumiko-framework": "0.359.0",
+    "@cosmicdrift/kumiko-headless": "0.359.0",
+    "@cosmicdrift/kumiko-renderer": "0.359.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.359.0",
+    "@cosmicdrift/kumiko-types": "0.359.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -1050,8 +1050,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.357.0",
-    "@cosmicdrift/kumiko-locale-es": "0.357.0",
+    "@cosmicdrift/kumiko-locale-de": "0.359.0",
+    "@cosmicdrift/kumiko-locale-es": "0.359.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/cap-counter/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.358.0",
+    "type": "improvement",
+    "title": "Reserve and settle cap usage outside the dispatcher",
+    "detail": "reserveCalendarCapUsage(ctx, { capName, periodStartIso, limit, profile, amount, notify? }) runs the same sweep, soft-hit notification and guarded hard-cap reservation as withCapEnforcement and returns a handle. settle(actualAmount) replaces the reserved amount by the actual one in one transaction (and books the full actual amount if the reservation was swept or released meanwhile); release() gives it back. Parallel callers cannot exceed the hard cap. It works with a HandlerContext (also r.systemScope() handlers) and a JobContext. Pattern: `const r = await reserveCalendarCapUsage(ctx, {...}); try { ...; await r.settle(actual) } catch (e) { await r.release(); throw e }`. bookCapUsage, markCapSoftWarned, releaseCapUsage and the enforceCap family accept a JobContext as well.",
+    "migration": "withCapEnforcement and bookCapUsage now work on r.systemScope() handlers; before, they failed on the fail-closed ctx.db. Reservation rows carry the tenant of ctx.user explicitly, and a context whose tenant-mode db belongs to another tenant than ctx.user is rejected with access_denied. enforceCap now filters the counter by ctx.user.tenantId, so a system-mode db no longer reads another tenant's counter."
+  },
   {
     "version": "0.352.0",
     "type": "breaking",

package/src/custom-fields/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.359.0",
+    "type": "improvement",
+    "title": "update-tenant-field keeps the stored type when serializedField.type is omitted",
+    "detail": "custom-fields: update-tenant-field accepts serializedField without type and keeps the stored type; a different type is still refused with 422 field_type_immutable. The handler declares excludedFields [\"type\"]."
+  },
   {
     "version": "0.338.0",
     "type": "fix",

package/src/notes-history/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.358.0",
+    "type": "fix",
+    "title": "forget-subject shreds note bodies even when the host entity has anonymize or blockDelete retention",
+    "detail": "Note bodies that @-mention the forgotten subject or hang on it as host entity were skipped when the host entity's retention strategy was anonymize or blockDelete, so the note text stayed readable while the host's own PII fields were anonymized. The note text is free-form PII, and a retention strategy protects the row, not its content, so these bodies are now always crypto-shredded. This applies to the manual `forget-subject` command and to the automated Art. 17 delete hook."
+  },
   {
     "version": "0.354.0",
     "type": "breaking",