@cosmicdrift/kumiko-samples 0.350.0 → 0.352.0

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

@@ -0,0 +1,247 @@
+import { deleteMany, runInOwnTransaction, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type {
+  HandlerContext,
+  SessionUser,
+  WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  appendEventInTenantDb,
+  getStreamVersionInTenantDb,
+} from "@cosmicdrift/kumiko-framework/event-store";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import type {
+  ReservationConfirmContext,
+  ReservationHandle,
+} from "@cosmicdrift/kumiko-types/handlers";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { rollingCapAggregateId } from "./aggregate-id.js";
+import {
+  applyCapDeltaOn,
+  type BookCapUsageOptions,
+  type ReadRollingCapUsageOptions,
+  readRollingCapUsage,
+  requireOutsideTransactionDb,
+  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";
+
+type CapReservationRow = {
+  readonly id: string;
+  readonly capName: string;
+  readonly kind: "calendar" | "rolling";
+  readonly periodStartIso: string | null;
+  readonly amount: number;
+  readonly expiresAt: Temporal.Instant;
+};
+
+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) {
+  const now = Temporal.Now.instant();
+  await txDb.insertOne(capReservationsTable, {
+    id,
+    capName: draft.capName,
+    kind: draft.kind,
+    periodStartIso: draft.periodStartIso ?? null,
+    amount: draft.amount,
+    expiresAt: now.add({ minutes: CAP_RESERVATION_TTL_MINUTES }),
+    createdAt: now,
+  });
+}
+
+function toHandle(ctx: HandlerContext, id: string): ReservationHandle {
+  return {
+    release: () => releaseCapReservation(ctx, id),
+    confirmInTransaction: (confirm) => confirmCapReservation(confirm, id),
+  };
+}
+
+export type ReserveCalendarCapOptions = Required<
+  Pick<BookCapUsageOptions, "capName" | "periodStartIso" | "amount">
+> &
+  Pick<BookCapUsageOptions, "guardCurrentValue">;
+
+// 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,
+  options: ReserveCalendarCapOptions,
+): Promise<ReservationHandle> {
+  const outsideDb = requireOutsideTransactionDb(ctx);
+  const id = generateId();
+  const reserved = await retryCounterWriteOnVersionConflict(() =>
+    runInOwnTransaction(outsideDb, async (txDb) => {
+      const booked = await applyCapDeltaOn(txDb, ctx.user, options, "add");
+      if (!booked.isSuccess) return booked;
+      await insertReservationRow(txDb, id, {
+        capName: options.capName,
+        kind: "calendar",
+        periodStartIso: options.periodStartIso,
+        amount: options.amount,
+      });
+      return booked;
+    }),
+  );
+  if (!reserved.isSuccess) throw reraiseAsKumikoError(reserved.error);
+  return toHandle(ctx, id);
+}
+
+export type ReserveRollingCapOptions = ReadRollingCapUsageOptions & {
+  readonly amount: number;
+  // Runs on every attempt with the usage seen by that attempt's append.
+  readonly guardCurrentValue?: (currentValue: number) => void;
+};
+
+function rollingEvent(
+  user: SessionUser,
+  capName: string,
+  amount: number,
+  expectedVersion: number,
+  type: string,
+) {
+  return {
+    aggregateId: rollingCapAggregateId(user.tenantId, capName),
+    aggregateType: CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
+    expectedVersion,
+    type,
+    payload: { capName, amount },
+    metadata: { userId: user.id },
+  };
+}
+
+// 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,
+  options: ReserveRollingCapOptions,
+): Promise<ReservationHandle> {
+  const outsideDb = requireOutsideTransactionDb(ctx);
+  const id = generateId();
+  const aggregateId = rollingCapAggregateId(ctx.user.tenantId, options.capName);
+  await retryOnStreamVersionConflict(() =>
+    runInOwnTransaction(outsideDb, async (txDb) => {
+      const version = await getStreamVersionInTenantDb(txDb, aggregateId);
+      const usage = await readRollingCapUsage(txDb, ctx.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, {
+        capName: options.capName,
+        kind: "rolling",
+        amount: options.amount,
+      });
+      return NOTHING_TO_RELEASE;
+    }),
+  );
+  return toHandle(ctx, id);
+}
+
+// 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.
+async function confirmCapReservation(
+  confirm: ReservationConfirmContext,
+  id: string,
+): Promise<void> {
+  await deleteMany(confirm.tx, capReservationsTable, { id, tenantId: confirm.tenantId });
+}
+
+async function giveBackCalendar(
+  txDb: TenantDb,
+  user: SessionUser,
+  row: CapReservationRow,
+): Promise<WriteResult> {
+  if (row.periodStartIso === null) {
+    throw new Error(`cap-counter: calendar reservation ${row.id} has no period to release against`);
+  }
+  return applyCapDeltaOn(
+    txDb,
+    user,
+    { capName: row.capName, periodStartIso: row.periodStartIso, amount: row.amount },
+    "subtract",
+  );
+}
+
+async function giveBackRolling(
+  txDb: TenantDb,
+  user: SessionUser,
+  row: CapReservationRow,
+): Promise<WriteResult> {
+  const version = await getStreamVersionInTenantDb(
+    txDb,
+    rollingCapAggregateId(user.tenantId, row.capName),
+  );
+  await appendEventInTenantDb(
+    txDb,
+    rollingEvent(user, row.capName, row.amount, version, ROLLING_RELEASED_EVENT_QN),
+  );
+  return NOTHING_TO_RELEASE;
+}
+
+async function giveBackReservation(
+  txDb: TenantDb,
+  user: SessionUser,
+  id: string,
+): Promise<WriteResult> {
+  const row = await txDb.fetchOne<CapReservationRow>(capReservationsTable, { id });
+  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 given =
+    row.kind === "rolling"
+      ? await giveBackRolling(txDb, user, row)
+      : await giveBackCalendar(txDb, user, row);
+  if (!given.isSuccess) return given;
+  await txDb.deleteMany(capReservationsTable, { id });
+  return given;
+}
+
+export async function releaseCapReservation(ctx: HandlerContext, id: string): Promise<void> {
+  const outsideDb = requireOutsideTransactionDb(ctx);
+  const released = await retryOnStreamVersionConflict(() =>
+    retryCounterWriteOnVersionConflict(() =>
+      runInOwnTransaction(outsideDb, (txDb) => giveBackReservation(txDb, ctx.user, id)),
+    ),
+  );
+  if (!released.isSuccess) throw reraiseAsKumikoError(released.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,
+  capName: string,
+): Promise<void> {
+  const outsideDb = requireOutsideTransactionDb(ctx);
+  const expired = await outsideDb.selectMany<Pick<CapReservationRow, "id">>(capReservationsTable, {
+    tenantId: ctx.user.tenantId,
+    capName,
+    expiresAt: { lt: Temporal.Now.instant() },
+  });
+  for (const { id } of expired) {
+    try {
+      await releaseCapReservation(ctx, id);
+    } 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,32 @@
 [
+  {
+    "version": "0.352.0",
+    "type": "breaking",
+    "title": "Calendar cap reservations are stored in the new store_cap_reservations table",
+    "detail": "Capped writes now insert and delete rows in store_cap_reservations, so they fail until the table exists.",
+    "migration": "Generate and apply a migration with `kumiko-schema generate` — capped writes fail without the new store_cap_reservations table"
+  },
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "Reservations expire after 60 minutes and are swept before the next reserve of the same cap"
+  },
+  {
+    "version": "0.352.0",
+    "type": "fix",
+    "title": "withCapEnforcement keeps the wrapped handler's settings (rateLimit, additionalRateLimits) and composes with an inner reserveBeforeTransaction"
+  },
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "withRollingCapEnforcement reserves before the handler transaction and releases through the new rolling-released event, so rejected or failed writes no longer consume rolling cap"
+  },
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "createValueCapGuard rejects a written number outside the min and max of the tenant's tier",
+    "detail": "A number written by a handler can be bounded per tier\n`createValueCapGuard(resolveTierCaps)` returns `checkValueCap` and `withValueCap`. The spec names the payload field, optional `min` and `max` functions over the tier caps (`undefined` means unbounded), an error code and an i18n key. The value is read from the payload or, for entity updates, from `changes`; an absent or non-numeric value passes. A value below the minimum or above the maximum is rejected with `UnprocessableError` and `details: { field, value, min, max }`. `withValueCap` spreads the wrapped handler, so it composes with `withCapEnforcement`."
+  },
   {
     "version": "0.348.0",
     "type": "fix",

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

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

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

@@ -1,17 +1,9 @@
-/// <reference types="temporal-polyfill/global" preserve="true" />
 import { createEntityExecutor, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { KumikoError, reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { markCapSoftWarned, readRollingCapUsage } from "./book-cap-usage.js";
 import { capCounterEntity } from "./entity.js";
 
-// Temporal globally provided by the framework's polyfill init
-// (ensureTemporalPolyfill() in time/polyfill.ts, called from
-// setupTestStack/boot). Importing from "temporal-polyfill" gives us
-// the polyfill-package types which don't quite match drizzle's
-// `instant()`-customType (temporal-spec narrowing of `until(...).sign`).
-// Mirror the audit-handler pattern: rely on the global ambient
-// declaration from temporal-spec.
-
 const { table } = createEntityExecutor("cap-counter", capCounterEntity);
 
 // =============================================================================

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

@@ -54,6 +54,7 @@ import {
   CAP_COUNTER_FEATURE,
   CAP_COUNTER_LIST_SCREEN_ID,
   ROLLING_INCREMENTED_EVENT_SHORT,
+  ROLLING_RELEASED_EVENT_SHORT,
 } from "./constants.js";
 import { capCounterEntity } from "./entity.js";
 import { getCounterQuery } from "./handlers/get-counter.query.js";
@@ -61,9 +62,11 @@ import { incrementCapHandler } from "./handlers/increment.write.js";
 import {
   incrementRollingCapHandler,
   rollingIncrementedSchema,
+  rollingReleasedSchema,
 } from "./handlers/increment-rolling.write.js";
 import { markSoftWarnedHandler } from "./handlers/mark-soft-warned.write.js";
 import { CAP_COUNTER_I18N } from "./i18n.js";
+import { capReservationsTableMeta } from "./tables.js";
 
 export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
   r.describe(
@@ -75,6 +78,9 @@ export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
     recommended: false,
   });
   r.entity("cap-counter", capCounterEntity);
+  r.storeTable(capReservationsTableMeta, {
+    reason: "coordination.cap_reservation_ledger",
+  });
 
   // Custom Domain-Event für Rolling-Counter. r.defineEvent registriert
   // das Schema beim Registry; ctx.unsafeAppendEvent im Handler nutzt
@@ -82,6 +88,7 @@ export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
   // "cap-counter:event:rolling-incremented" (siehe
   // ROLLING_INCREMENTED_EVENT_QN).
   r.defineEvent(ROLLING_INCREMENTED_EVENT_SHORT, rollingIncrementedSchema, { piiFields: "none" });
+  r.defineEvent(ROLLING_RELEASED_EVENT_SHORT, rollingReleasedSchema, { piiFields: "none" });
 
   // Custom write-handlers.
   // - increment: Calendar-Period (CRUD via projection-row).

package/packages/bundled-features/src/cap-counter/handlers/increment-rolling.write.ts

@@ -37,6 +37,11 @@ type IncrementRollingPayload = z.infer<typeof incrementRollingSchema>;
  *  der Caller zahlt amount, wir hängen es 1:1 an den Stream. */
 export const rollingIncrementedSchema = incrementRollingSchema;
 
+/** Payload of the event that gives a reserved rolling amount back. */
+export const rollingReleasedSchema = incrementRollingSchema.extend({
+  amount: z.number().int().positive(),
+});
+
 // Rolling-Increment-Handler — append-only. Race-frei: zwei parallele
 // Increments für (tenant, cap) hängen sich am selben aggregate-stream
 // in unterschiedlichen versions auf, das event-store ordert.

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

@@ -16,6 +16,8 @@ export {
   CapCounterQueries,
   ROLLING_INCREMENTED_EVENT_QN,
   ROLLING_INCREMENTED_EVENT_SHORT,
+  ROLLING_RELEASED_EVENT_QN,
+  ROLLING_RELEASED_EVENT_SHORT,
 } from "./constants.js";
 export {
   CAP_TOLERANCES,
@@ -34,12 +36,19 @@ export {
 } from "./enforce-cap.js";
 export { capCounterEntity } from "./entity.js";
 export { capCounterFeature } from "./feature.js";
+export { readPayloadField } from "./payload-field.js";
 export {
+  type CapGuardContext,
   type CapLimitContext,
   createStockCapGuard,
   type StockCapGuard,
   type StockCapSpec,
 } from "./stock-cap-guard.js";
+export {
+  createValueCapGuard,
+  type ValueCapGuard,
+  type ValueCapSpec,
+} from "./value-cap-guard.js";
 export {
   type CalendarCapDef,
   type CalendarCapResolver,

package/packages/bundled-features/src/cap-counter/payload-field.ts

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

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

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

package/packages/bundled-features/src/cap-counter/stock-cap-guard.ts

@@ -24,6 +24,9 @@ export type CapLimitContext = {
   readonly config?: ConfigAccessor;
 };
 
+// What the cap guards need from a write handler's ctx.
+export type CapGuardContext = CapLimitContext & { readonly db: TenantDb };
+
 export type StockCapSpec<TCaps> = {
   readonly table: SchemaTable | EntityTableMeta;
   readonly limit: (caps: TCaps) => number;

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

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

package/packages/bundled-features/src/cap-counter/value-cap-guard.ts

@@ -0,0 +1,70 @@
+// Per-tier bounds on a single written number (e.g. a retention period or a page size),
+// next to the stock-cap guard, which bounds how many rows may exist.
+
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  UnprocessableError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { readPayloadField } from "./payload-field.js";
+import type { CapGuardContext, CapLimitContext } from "./stock-cap-guard.js";
+
+export type ValueCapSpec<TCaps> = {
+  readonly field: string;
+  /** `undefined` = no lower bound for this tier. */
+  readonly min?: (caps: TCaps) => number | undefined;
+  /** `undefined` = no upper bound for this tier. */
+  readonly max?: (caps: TCaps) => number | undefined;
+  readonly code: string;
+  readonly i18nKey: string;
+};
+
+export type ValueCapGuard<TCaps> = {
+  readonly checkValueCap: (
+    ctx: CapGuardContext,
+    value: unknown,
+    spec: ValueCapSpec<TCaps>,
+  ) => Promise<WriteFailure | null>;
+  readonly withValueCap: (handler: WriteHandlerDef, spec: ValueCapSpec<TCaps>) => WriteHandlerDef;
+};
+
+function isOutOfBounds(value: number, min: number | undefined, max: number | undefined): boolean {
+  return (min !== undefined && value < min) || (max !== undefined && value > max);
+}
+
+export function createValueCapGuard<TCaps>(
+  resolveTierCaps: (db: TenantDb, context: CapLimitContext) => Promise<TCaps>,
+): ValueCapGuard<TCaps> {
+  async function checkValueCap(
+    ctx: CapGuardContext,
+    value: unknown,
+    spec: ValueCapSpec<TCaps>,
+  ): Promise<WriteFailure | null> {
+    // skip: an absent or non-numeric value is the schema's business, not a cap violation.
+    if (typeof value !== "number") return null;
+    const caps = await resolveTierCaps(ctx.db, ctx.config ? { config: ctx.config } : {});
+    const min = spec.min?.(caps);
+    const max = spec.max?.(caps);
+    if (!isOutOfBounds(value, min, max)) return null;
+    return writeFailure(
+      new UnprocessableError(spec.code, {
+        i18nKey: spec.i18nKey,
+        details: { field: spec.field, value, min, max },
+      }),
+    );
+  }
+
+  function withValueCap(handler: WriteHandlerDef, spec: ValueCapSpec<TCaps>): WriteHandlerDef {
+    return {
+      ...handler,
+      handler: async (event, ctx) => {
+        const failure = await checkValueCap(ctx, readPayloadField(event.payload, spec.field), spec);
+        return failure ?? handler.handler(event, ctx);
+      },
+    };
+  }
+
+  return { checkValueCap, withValueCap };
+}