@cosmicdrift/kumiko-samples 0.357.0 → 0.358.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.357.0",
+  "version": "0.358.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.357.0",
+  "version": "0.358.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>",

package/packages/bundled-features/src/cap-counter/book-cap-usage.ts

@@ -4,10 +4,12 @@ import { runInOwnTransaction, type TenantDb } from "@cosmicdrift/kumiko-framewor
 import {
   createEntityExecutor,
   type HandlerContext,
+  type JobContext,
   type SessionUser,
   type TenantId,
   type WriteResult,
 } 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";
@@ -82,17 +84,69 @@ export type BookCapUsageOptions = {
   readonly guardCurrentValue?: (currentValue: number) => void;
 };
 
-export function requireOutsideTransactionDb(ctx: HandlerContext): TenantDb {
-  if (!ctx.dbOutsideTransaction) {
+export type CapCounterContext = HandlerContext | JobContext;
+
+export type CapCounterScope = {
+  readonly user: SessionUser;
+  readonly readDb: TenantDb;
+  readonly writeDb: TenantDb;
+};
+
+// 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: TenantDb, user: SessionUser): TenantDb {
+  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 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: CapCounterContext,
+  outsideTransaction: boolean,
+): CapCounterScope {
+  // 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(
-      "cap-counter.bookCapUsage: outsideTransaction requested but ctx.dbOutsideTransaction is undefined",
+      outsideTransaction
+        ? "cap-counter: outsideTransaction requested but ctx.dbOutsideTransaction is undefined"
+        : "cap-counter: ctx.db missing — run inside a handler context",
     );
   }
-  return ctx.dbOutsideTransaction;
+  return {
+    user,
+    readDb: assertDbServesUser(ctx.db, user),
+    writeDb: assertDbServesUser(writeDb, user),
+  };
 }
 
 export async function bookCapUsage(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: BookCapUsageOptions,
 ): Promise<WriteResult> {
   return applyCapDelta(ctx, options, "add");
@@ -100,7 +154,7 @@ export async function bookCapUsage(
 
 // Gives back a reservation whose operation failed afterwards; the counter never drops below 0.
 export async function releaseCapUsage(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: Omit<BookCapUsageOptions, "guardCurrentValue">,
 ): Promise<WriteResult> {
   return applyCapDelta(ctx, options, "subtract");
@@ -157,18 +211,18 @@ export async function applyCapDeltaOn(
 }
 
 async function applyCapDelta(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: BookCapUsageOptions,
   direction: "add" | "subtract",
 ): Promise<WriteResult> {
+  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)),
+      runInOwnTransaction(writeDb, (txDb) => applyCapDeltaOn(txDb, user, options, direction)),
     );
   }
   return retryCounterWriteOnVersionConflict(() =>
-    applyCapDeltaOn(ctx.db, ctx.user, options, direction),
+    applyCapDeltaOn(writeDb, user, options, direction),
   );
 }
 
@@ -179,21 +233,18 @@ export type MarkCapSoftWarnedOptions = {
 };
 
 export async function markCapSoftWarned(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: MarkCapSoftWarnedOptions,
 ): Promise<WriteResult> {
   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: TenantDb): Promise<WriteResult> {
     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}`,
+        `cap-counter: cannot mark-soft-warned, no counter found for tenant=${user.tenantId} cap=${parsed.capName} period=${parsed.periodStartIso}`,
       );
     }
     const row = existing[0];
@@ -213,16 +264,15 @@ export async function markCapSoftWarned(
         version: currentVersion,
         changes: { lastSoftWarnedAt: Temporal.Now.instant() },
       },
-      ctx.user,
+      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));
 }
 
 export type ReadRollingCapUsageOptions = {

package/packages/bundled-features/src/cap-counter/calendar-cap-usage-reservation.ts

@@ -0,0 +1,99 @@
+import type { CapCounterContext } from "./book-cap-usage.js";
+import {
+  type CalendarCapReservation,
+  releaseExpiredCapReservations,
+  reserveCalendarCap,
+  settleCalendarCapReservation,
+} from "./cap-reservation.js";
+import {
+  assertBelowHardCap,
+  enforceCapAndMaybeNotify,
+  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;
+  // Default true: the reservation must commit on its own, not roll back with the caller's transaction.
+  readonly outsideTransaction?: boolean;
+};
+
+export type CalendarCapUsageReservation = {
+  readonly amount: number;
+  // Counter value right after this reservation was booked.
+  readonly counterValue: number;
+  // Replaces the reserved amount with the actual one; rejects a second settle and one after release.
+  settle(actualAmount: number): Promise<void>;
+  // Gives the reserved amount back; a no-op once settled.
+  release(): Promise<void>;
+};
+
+// Shared by withCapEnforcement and the public reservation API so both enforce identically.
+export async function reserveEnforcedCalendarCap(
+  ctx: CapCounterContext,
+  cap: CalendarCapUsageReservationSpec,
+): Promise<CalendarCapReservation> {
+  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,
+  );
+}
+
+type ReservationState = "open" | "settled" | "released";
+
+export async function reserveCalendarCapUsage(
+  ctx: CapCounterContext,
+  spec: CalendarCapUsageReservationSpec,
+): Promise<CalendarCapUsageReservation> {
+  const outsideTransaction = spec.outsideTransaction ?? true;
+  const reservation = await reserveEnforcedCalendarCap(ctx, spec);
+  let state: ReservationState = "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/packages/bundled-features/src/cap-counter/cap-reservation.ts

@@ -1,9 +1,5 @@
 import { deleteMany, runInOwnTransaction, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import type {
-  HandlerContext,
-  SessionUser,
-  WriteResult,
-} from "@cosmicdrift/kumiko-framework/engine";
+import type { SessionUser, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
 import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
 import {
   appendEventInTenantDb,
@@ -19,9 +15,10 @@ import { rollingCapAggregateId } from "./aggregate-id.js";
 import {
   applyCapDeltaOn,
   type BookCapUsageOptions,
+  type CapCounterContext,
   type ReadRollingCapUsageOptions,
   readRollingCapUsage,
-  requireOutsideTransactionDb,
+  resolveCapCounterScope,
   retryCounterWriteOnVersionConflict,
   retryOnStreamVersionConflict,
 } from "./book-cap-usage.js";
@@ -47,10 +44,16 @@ const NOTHING_TO_RELEASE: WriteResult = { isSuccess: true, data: {} };
 type ReservationRowDraft = Pick<CapReservationRow, "capName" | "kind" | "amount"> &
   Pick<Partial<CapReservationRow>, "periodStartIso">;
 
-async function insertReservationRow(txDb: TenantDb, id: string, draft: ReservationRowDraft) {
+async function insertReservationRow(
+  txDb: TenantDb,
+  user: SessionUser,
+  id: string,
+  draft: ReservationRowDraft,
+) {
   const now = Temporal.Now.instant();
   await txDb.insertOne(capReservationsTable, {
     id,
+    tenantId: user.tenantId,
     capName: draft.capName,
     kind: draft.kind,
     periodStartIso: draft.periodStartIso ?? null,
@@ -60,9 +63,19 @@ async function insertReservationRow(txDb: TenantDb, id: string, draft: Reservati
   });
 }
 
-function toHandle(ctx: HandlerContext, id: string): ReservationHandle {
+export type CalendarCapReservation = ReservationHandle & {
+  readonly reservationId: string;
+  // Counter value right after this reservation was booked.
+  readonly counterValue: number;
+};
+
+function toHandle(
+  ctx: CapCounterContext,
+  id: string,
+  outsideTransaction: boolean,
+): ReservationHandle {
   return {
-    release: () => releaseCapReservation(ctx, id),
+    release: () => releaseCapReservation(ctx, id, outsideTransaction),
     confirmInTransaction: (confirm) => confirmCapReservation(confirm, id),
   };
 }
@@ -75,16 +88,26 @@ export type ReserveCalendarCapOptions = Required<
 // 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: HandlerContext,
+  ctx: CapCounterContext,
   options: ReserveCalendarCapOptions,
-): Promise<ReservationHandle> {
-  const outsideDb = requireOutsideTransactionDb(ctx);
+  outsideTransaction = true,
+): Promise<CalendarCapReservation> {
+  const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
   const id = generateId();
+  // The last attempt is the one that committed, so this holds the value its increment started from.
+  let valueBeforeBooking = 0;
+  const observedOptions: ReserveCalendarCapOptions = {
+    ...options,
+    guardCurrentValue: (currentValue) => {
+      options.guardCurrentValue?.(currentValue);
+      valueBeforeBooking = currentValue;
+    },
+  };
   const reserved = await retryCounterWriteOnVersionConflict(() =>
-    runInOwnTransaction(outsideDb, async (txDb) => {
-      const booked = await applyCapDeltaOn(txDb, ctx.user, options, "add");
+    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,
@@ -94,7 +117,11 @@ export async function reserveCalendarCap(
     }),
   );
   if (!reserved.isSuccess) throw reraiseAsKumikoError(reserved.error);
-  return toHandle(ctx, id);
+  return {
+    ...toHandle(ctx, id, outsideTransaction),
+    reservationId: id,
+    counterValue: valueBeforeBooking + options.amount,
+  };
 }
 
 export type ReserveRollingCapOptions = ReadRollingCapUsageOptions & {
@@ -123,28 +150,23 @@ function rollingEvent(
 // 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: HandlerContext,
+  ctx: CapCounterContext,
   options: ReserveRollingCapOptions,
+  outsideTransaction = true,
 ): Promise<ReservationHandle> {
-  const outsideDb = requireOutsideTransactionDb(ctx);
+  const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
   const id = generateId();
-  const aggregateId = rollingCapAggregateId(ctx.user.tenantId, options.capName);
+  const aggregateId = rollingCapAggregateId(user.tenantId, options.capName);
   await retryOnStreamVersionConflict(() =>
-    runInOwnTransaction(outsideDb, async (txDb) => {
+    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,
-        ),
+        rollingEvent(user, options.capName, options.amount, version, ROLLING_INCREMENTED_EVENT_QN),
       );
-      await insertReservationRow(txDb, id, {
+      await insertReservationRow(txDb, user, id, {
         capName: options.capName,
         kind: "rolling",
         amount: options.amount,
@@ -152,7 +174,7 @@ export async function reserveRollingCap(
       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
@@ -201,45 +223,123 @@ async function giveBackReservation(
   user: SessionUser,
   id: string,
 ): Promise<WriteResult> {
-  const row = await txDb.fetchOne<CapReservationRow>(capReservationsTable, { id });
+  const ownRow = { id, tenantId: user.tenantId };
+  const row = await txDb.fetchOne<CapReservationRow>(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) return NOTHING_TO_RELEASE;
+  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: HandlerContext, id: string): Promise<void> {
-  const outsideDb = requireOutsideTransactionDb(ctx);
+// Waits for a confirm still holding the row; false means that confirm (or another release) won.
+async function claimReservationRow(
+  txDb: TenantDb,
+  user: SessionUser,
+  row: CapReservationRow,
+): Promise<boolean> {
+  const claimed = await txDb.updateMany(
+    capReservationsTable,
+    { expiresAt: row.expiresAt },
+    { id: row.id, tenantId: user.tenantId },
+  );
+  return claimed.length > 0;
+}
+
+export async function releaseCapReservation(
+  ctx: CapCounterContext,
+  id: string,
+  outsideTransaction = true,
+): Promise<void> {
+  const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
   const released = await retryOnStreamVersionConflict(() =>
     retryCounterWriteOnVersionConflict(() =>
-      runInOwnTransaction(outsideDb, (txDb) => giveBackReservation(txDb, ctx.user, id)),
+      runInOwnTransaction(writeDb, (txDb) => giveBackReservation(txDb, user, id)),
     ),
   );
   if (!released.isSuccess) throw reraiseAsKumikoError(released.error);
 }
 
+export type SettleCalendarCapOptions = {
+  readonly capName: string;
+  readonly periodStartIso: string;
+  readonly actualAmount: number;
+};
+
+function bookCalendarDelta(
+  txDb: TenantDb,
+  user: SessionUser,
+  period: Pick<SettleCalendarCapOptions, "capName" | "periodStartIso">,
+  delta: number,
+): Promise<WriteResult> {
+  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: CapCounterContext,
+  id: string,
+  options: SettleCalendarCapOptions,
+  outsideTransaction = true,
+): Promise<void> {
+  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<CapReservationRow>(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: HandlerContext,
+  ctx: CapCounterContext,
   capName: string,
+  outsideTransaction = true,
 ): Promise<void> {
-  const outsideDb = requireOutsideTransactionDb(ctx);
-  const expired = await outsideDb.selectMany<Pick<CapReservationRow, "id">>(capReservationsTable, {
-    tenantId: ctx.user.tenantId,
+  const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
+  const expired = await writeDb.selectMany<Pick<CapReservationRow, "id">>(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/packages/bundled-features/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/packages/bundled-features/src/cap-counter/enforce-cap.ts

@@ -1,7 +1,12 @@
-import { createEntityExecutor, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+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 {
+  type CapCounterContext,
+  markCapSoftWarned,
+  readRollingCapUsage,
+  resolveCapCounterScope,
+} from "./book-cap-usage.js";
 import { capCounterEntity } from "./entity.js";
 
 const { table } = createEntityExecutor("cap-counter", capCounterEntity);
@@ -95,7 +100,7 @@ export function assertBelowHardCap(
  * level (e.g. uniqueness-index on apps.tenantId+slot-number).
  */
 export async function enforceCap(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: {
     readonly capName: string;
     readonly periodStartIso: string;
@@ -106,9 +111,7 @@ export async function enforceCap(
     readonly amount?: number;
   },
 ): Promise<EnforceCapResult> {
-  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) {
@@ -120,9 +123,9 @@ export async function enforceCap(
   const tolerance = CAP_TOLERANCES[options.profile];
   const softThreshold = options.limit * tolerance.soft;
 
-  const rows = await ctx.db.selectMany(
+  const rows = await readDb.selectMany(
     table,
-    { capName: options.capName, periodStart: options.periodStartIso },
+    { tenantId: user.tenantId, capName: options.capName, periodStart: options.periodStartIso },
     { limit: 1 },
   );
 
@@ -170,7 +173,7 @@ export async function enforceCap(
  * vorgezogen.
  */
 export async function enforceRollingCap(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: {
     readonly capName: string;
     readonly windowDays: number;
@@ -178,20 +181,13 @@ export async function enforceRollingCap(
     readonly profile: CapToleranceProfileName;
   },
 ): Promise<EnforceCapResult> {
-  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,
   });
@@ -295,7 +291,7 @@ export type SoftHitNotifier = (info: {
  * Email-Notification).
  */
 export async function enforceCapAndMaybeNotify(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: {
     readonly capName: string;
     readonly periodStartIso: string;
@@ -315,16 +311,11 @@ export async function enforceCapAndMaybeNotify(
   });
 
   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, {
@@ -349,7 +340,7 @@ export async function enforceCapAndMaybeNotify(
  * Tag/Stunde auf (Hourly-Cron statt pro Request).
  */
 export async function enforceRollingCapAndMaybeNotify(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: {
     readonly capName: string;
     readonly windowDays: number;
@@ -366,16 +357,11 @@ export async function enforceRollingCapAndMaybeNotify(
   });
 
   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,
     });
   }
 

package/packages/bundled-features/src/cap-counter/index.ts

@@ -9,6 +9,11 @@ export {
   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,

package/packages/bundled-features/src/cap-counter/with-cap-enforcement.ts

@@ -29,15 +29,11 @@ import type {
   WriteEvent,
   WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
-import {
-  releaseExpiredCapReservations,
-  reserveCalendarCap,
-  reserveRollingCap,
-} from "./cap-reservation.js";
+import { reserveEnforcedCalendarCap } from "./calendar-cap-usage-reservation.js";
+import { releaseExpiredCapReservations, reserveRollingCap } from "./cap-reservation.js";
 import {
   assertBelowHardCap,
   type CapToleranceProfileName,
-  enforceCapAndMaybeNotify,
   enforceRollingCapAndMaybeNotify,
   type SoftHitNotifier,
 } from "./enforce-cap.js";
@@ -93,25 +89,7 @@ export function withCapEnforcement(
       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/packages/bundled-features/src/crypto-shredding/handlers/forget-subject.write.ts

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

package/packages/bundled-features/src/jobs/job-run-logger.ts

@@ -14,6 +14,7 @@ import {
   KeyErasedError,
   type LocalKeyKmsAdapter,
   PII_ERASED_SENTINEL,
+  type SubjectId,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import { acquireNamespacedAdvisoryLock, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { type Registry, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
@@ -71,6 +72,15 @@ const DEFAULT_CACHE_MAX_ENTRIES = 10_000;
 // 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: string | null): SubjectId {
+  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
@@ -81,14 +91,14 @@ const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 // whole run row.
 async function encryptOrSentinel(
   kms: LocalKeyKmsAdapter,
-  subjectUserId: string,
+  subject: SubjectId,
   value: string,
   field: string,
 ): Promise<string> {
   try {
     return await encryptPiiValueForSubject(
       kms,
-      { kind: "user", userId: subjectUserId },
+      subject,
       value,
       { requestId: "jobs:job-run-logger" },
       field,
@@ -104,20 +114,20 @@ async function encryptOrSentinel(
 // 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<T extends { readonly message: string }>(
   logs: readonly T[],
   triggeredById: string | null,
 ): Promise<T[]> {
-  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"),
   }));
 }
 
@@ -131,29 +141,27 @@ export async function encryptFailureError(
   error: string,
   triggeredById: string | null,
 ): Promise<string> {
-  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: string | null,
   triggeredById: string | null,
 ): Promise<string | null> {
-  if (payload === null || triggeredById === null) return payload;
+  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

package/packages/bundled-features/src/jobs/job-run-table.ts

@@ -46,11 +46,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/packages/bundled-features/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",

package/packages/bundled-features/src/notes-history/entity.ts

@@ -77,9 +77,10 @@ export function createNoteEntryEntity(
       }),
       // 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/packages/bundled-features/src/notes-history-user-data/hooks.ts

@@ -8,18 +8,11 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { configuredPiiSubjectKms, type SubjectId } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type {
-  Registry,
   TenantId,
   UserDataDeleteHook,
   UserDataExportHook,
 } from "@cosmicdrift/kumiko-framework/engine";
-import {
-  type RetentionPresetKey,
-  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.
@@ -84,17 +77,15 @@ async function selectNotesReachingSubject(
 // @-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
 // Art. 17 coverage must mount one.
 export async function eraseNoteBodiesReachingSubject(args: {
   readonly db: DbRunner | TenantDb;
-  readonly registry: Registry;
   readonly subject: SubjectId;
   readonly erasedBy: string;
   readonly requestId: string;
@@ -104,36 +95,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<string, RetentionPresetKey | null>();
-  const strategyByTenantAndEntityType = new Map<string, ReturnType<typeof policyToStrategy>>();
   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 },
       {
@@ -148,7 +110,6 @@ export async function eraseNoteBodiesReachingSubject(args: {
 export const noteEntryDeleteHook: UserDataDeleteHook = 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/packages/bundled-features/src/notes-history-user-data/index.ts

@@ -17,7 +17,7 @@ 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`.",
+    "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

package/samples/apps/styleguide/src/features/widgets/feature.ts

@@ -153,6 +153,7 @@ export const widgetsFeature = defineFeature("widgets", (r) => {
         legendTotals: false,
         initialWindow: "from-today",
         markerLegend: "legend",
+        markerLabels: true,
         markerKinds: {
           extra: { tone: "active", label: "widgets:dashboard:kind-extra" },
           payoff: { tone: "positive", label: "widgets:dashboard:kind-payoff" },

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -1954,7 +1954,7 @@
     },
     {
       "name": "notes-history-user-data",
-      "description": "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`.",
+      "description": "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`.",
       "toggleableDefault": null,
       "requires": [
         "user-data-rights"