@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

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

@@ -16,16 +16,14 @@ const { table } = createEntityExecutor("cap-counter", capCounterEntity);
 // =============================================================================
 
 /**
- * Cap-Toleranz-Profile — pro Cap-Typ asymmetrisch. Quelle: Memory
- * `project_pricing_byok_caps` §3 + `docs/plans/marketing/produkt/
- * pricing.md` Cap-Verhalten-Block.
+ * Cap-tolerance profiles, asymmetric by cap type.
  *
- * **Soft** = Notification-Schwelle (Multiplier × Limit). Bei
- * Erreichen wird einmalig gewarnt (lastSoftWarnedAt setzt das Flag).
- * Caller-Code emittiert die echte Notification.
+ * **Soft** = notification threshold (multiplier × limit). Once reached,
+ * a warning is issued (`lastSoftWarnedAt` sets the flag); caller code emits
+ * the actual notification.
  *
- * **Hard** = Schreibe-Block (Multiplier × Limit). enforceCap throwt
- * mit `cap_exceeded`-Error → Dispatcher mapped 429 + Upgrade-Hint.
+ * **Hard** = write-block threshold (multiplier × limit). `enforceCap` throws
+ * a `cap_exceeded` error, which the dispatcher maps to 429 with an upgrade hint.
  */
 export type CapToleranceProfile = {
   readonly soft: number;
@@ -33,13 +31,13 @@ export type CapToleranceProfile = {
 };
 
 export const CAP_TOLERANCES = {
-  /** Mails / Tokens — billig, BYOK ab Pro. Burst-Buffer großzügig. */
+  /** Mails / tokens — inexpensive, with BYOK available from Pro. Generous burst buffer. */
   burstable: { soft: 1.1, hard: 1.2 },
   /** DB-Storage / File-Storage — teuer + persistent. Strikter Cut. */
   storage: { soft: 1.0, hard: 1.05 },
-  /** Apps-Count, Plattform-Slots — gebuchte Kapazität, kein Buffer. */
+  /** App count and platform slots — purchased capacity, with no buffer. */
   hardSlot: { soft: 1.0, hard: 1.0 },
-  /** Egress — Bursty-Traffic legitim, nur extreme Spikes blockieren. */
+  /** Egress — bursty traffic is legitimate; only extreme spikes are blocked. */
   egress: { soft: 1.1, hard: 1.3 },
 } as const satisfies Readonly<Record<string, CapToleranceProfile>>;
 
@@ -73,8 +71,9 @@ export function assertBelowHardCap(
   },
 ): void {
   const tolerance = CAP_TOLERANCES[cap.profile];
+  // Validated on every call so a misconfigured period fails deterministically, not only at the limit.
+  const resetAt = resolvePeriodEndIso(cap.periodStartIso, cap.periodEndIso);
   if (valueSeenByLastUnit >= cap.limit * tolerance.hard) {
-    const resetAt = resolvePeriodEndIso(cap.periodStartIso, cap.periodEndIso);
     throw new CapExceededError(cap.capName, cap.limit, valueSeenByLastUnit, tolerance, {
       ...(resetAt !== undefined && { resetAt }),
       ...(cap.i18nKey !== undefined && { i18nKey: cap.i18nKey }),
@@ -176,28 +175,26 @@ export async function enforceCap(
 // =============================================================================
 
 /**
- * Synchronous read-and-check of the calling tenant's Rolling-Window-
- * Counter for `capName`. Reads the increment-events of the last
- * `windowDays` from the event-store and sums their `amount`. Returns:
+ * Synchronous read-and-check of the calling tenant's rolling-window
+ * counter for `capName`. Reads increment events from the last
+ * `windowDays` in the event store and sums their `amount`. Returns:
  *   - "ok" when sum < soft-threshold
  *   - "soft-hit" when soft ≤ sum < hard.
  *
  * **Throws** `CapExceededError` when sum ≥ hard-threshold.
  *
- * **`crossed`-flag fehlt absichtlich:** Anders als der Calendar-
- * Counter hat das Rolling-Aggregate keine projection-row mit
- * `lastSoftWarnedAt`-Flag. Dedup gegen Notification-Storm passiert
- * im Caller (eigener key in einer Cache-Tabelle, oder einfache
- * memoization für die Lebensdauer des Request). Der Result-Shape
- * matcht trotzdem `EnforceCapResult` damit der gleiche Caller-Code
- * gegen beide Funktionen funktioniert; `crossed` ist hier immer
- * `false` (= "wir tracken's nicht").
+ * **The `crossed` flag is intentionally absent:** Unlike the calendar
+ * counter, the rolling aggregate has no projection row with a
+ * `lastSoftWarnedAt` flag. The caller must deduplicate notification storms
+ * using its own mechanism, such as a cache-table key or request-lifetime
+ * memoization. The result shape still matches `EnforceCapResult` so the same
+ * caller code works with both functions; `crossed` is always `false` here
+ * (= "not tracked").
  *
- * **Performance-Note:** der Read summiert ALLE Events im Window für
- * (tenant, capName). Bei 10k+ Events/Tenant in der Window könnte
- * das langsam werden — dann Migration auf eine Multi-Stream-
- * Projection mit pre-aggregierten daily-buckets. Heute nicht
- * vorgezogen.
+ * **Performance note:** The read sums ALL events in the window for
+ * (tenant, capName). With 10k+ events per tenant in the window, this could
+ * become slow; migrate to a multi-stream projection with pre-aggregated
+ * daily buckets if needed.
  */
 export async function enforceRollingCap(
   ctx: CapCounterContext,
@@ -324,20 +321,20 @@ export function calendarMonthPeriodEndIso(periodStartIso: string): string {
 }
 
 // =============================================================================
-// Notification-Wiring helpers — convenience-wrapper für enforceCap +
-// enforceRollingCap, die einen Caller-supplied delivery-emit beim
-// soft-hit-crossing ausführen. Cap-counter kennt delivery-feature
-// nicht direkt — der Caller injiziert den emitter.
+// Notification-wiring helpers — convenience wrappers for `enforceCap` and
+// `enforceRollingCap` that execute a caller-supplied delivery emitter when
+// a soft-hit threshold is crossed. The cap counter does not know about the
+// delivery feature directly; the caller injects the emitter.
 // =============================================================================
 
 /**
- * Soft-hit-notifier callback. Caller liefert die Funktion die ein
- * delivery-event emittet (z.B. `delivery.send({to, template, payload})`).
- * Wird genau einmal pro Period beim Calendar-Counter aufgerufen
- * (`crossed === true` deduplicated via `markSoftWarnedHandler`).
+ * Soft-hit notifier callback. The caller supplies the function that emits
+ * a delivery event (for example, `delivery.send({to, template, payload})`).
+ * It is called exactly once per period for the calendar counter
+ * (`crossed === true`, deduplicated via `markSoftWarnedHandler`).
  *
- * Beim Rolling-Counter ist `crossed` immer `false` — der Caller muss
- * dort selbst dedup'en (oder bewusst pro request feuern lassen).
+ * For the rolling counter, `crossed` is always `false`; the caller must
+ * deduplicate notifications itself or intentionally send one per request.
  */
 export type SoftHitNotifier = (info: {
   readonly capName: string;
@@ -347,14 +344,14 @@ export type SoftHitNotifier = (info: {
 }) => Promise<void> | void;
 
 /**
- * Calendar-Period-enforcement + automatische soft-hit-Notification.
- * Ruft `enforceCap`, bei `crossed: true` den Notifier UND
- * `mark-soft-warned`-Handler (flippt `lastSoftWarnedAt` damit der
- * nächste Aufruf in derselben Period nicht erneut feuert).
+ * Calendar-period enforcement with automatic soft-hit notification.
+ * Calls `enforceCap`; when `crossed: true`, it calls the notifier and the
+ * `mark-soft-warned` handler, which flips `lastSoftWarnedAt` so that the
+ * same period does not trigger another notification.
  *
- * Returnt das `EnforceCapResult` weiter — Caller kann die Logik
- * verzweigen (z.B. UI-Toast bei soft-hit zusätzlich zur
- * Email-Notification).
+ * Returns the `EnforceCapResult` unchanged, allowing the caller to branch
+ * on the result, such as showing a UI toast in addition to the email
+ * notification.
  */
 export async function enforceCapAndMaybeNotify(
   ctx: CapCounterContext,
@@ -400,14 +397,14 @@ export async function enforceCapAndMaybeNotify(
 }
 
 /**
- * Rolling-Window-enforcement + immer-feuert-Notification beim soft-hit.
+ * Rolling-window enforcement that always sends a notification on a soft hit.
  *
- * **Achtung Storm-Risk:** Rolling-Counter trackt `lastSoftWarnedAt`
- * NICHT (kein projection-row). Bei jedem Aufruf während der Counter
- * im soft-Bereich ist, feuert der notifier. Der Caller muss
- * dedup'en — z.B. via Cache-Eintrag `lastNotified[capName]` mit TTL,
- * oder er ruft `enforceRollingCapAndMaybeNotify` nur einmal pro
- * Tag/Stunde auf (Hourly-Cron statt pro Request).
+ * **Storm risk:** The rolling counter does NOT track `lastSoftWarnedAt`
+ * (there is no projection row). On every call while the counter is in the
+ * soft range, the notifier fires. The caller must deduplicate, for example
+ * with a cache entry `lastNotified[capName]` and a TTL, or call
+ * `enforceRollingCapAndMaybeNotify` only once per day or hour
+ * (an hourly cron instead of per request).
  */
 export async function enforceRollingCapAndMaybeNotify(
   ctx: CapCounterContext,
@@ -439,7 +436,7 @@ export async function enforceRollingCapAndMaybeNotify(
 }
 
 // =============================================================================
-// Stock-Cap (Bestand) — live-gezählte Kardinalität gegen Tier-Limit
+// Stock cap — live-counted cardinality checked against the tier limit
 // =============================================================================
 
 export type StockCapResult =
@@ -447,24 +444,25 @@ export type StockCapResult =
   | { readonly state: "exceeded"; readonly current: number; readonly limit: number };
 
 /**
- * Stock-Cap: prüft eine vom Caller LIVE gezählte Kardinalität (z.B. Anzahl
- * existierender Components eines Tenants) gegen ein Tier-Limit.
+ * Stock cap: checks a cardinality counted LIVE by the caller (for example,
+ * the number of existing components for a tenant) against a tier limit.
  *
- * Anders als {@link enforceCap}/{@link enforceRollingCap} gibt es KEINEN
- * gespeicherten Counter: der Caller zählt die Projektion selbst
- * (`count(*) WHERE tenant_id = …`) und übergibt `current`. Das ist drift-frei
- * (ein Delete gibt den Slot sofort frei), braucht keine Counter-Tabelle und
- * kein Increment/Decrement-Bookkeeping. Misst einen Bestand, keinen Fluss.
+ * Unlike {@link enforceCap}/{@link enforceRollingCap}, there is NO stored
+ * counter: the caller counts the projection itself
+ * (`count(*) WHERE tenant_id = …`) and passes `current`. This avoids drift
+ * (a delete immediately frees the slot), requires no counter table or
+ * increment/decrement bookkeeping, and measures a stock rather than a flow.
  *
- * **TOCTOU-Caveat:** Zählen und Schreiben sind nicht atomar — zwei parallele
- * Creates können beide `ok` sehen und das Limit um eins überschreiten (gleiche
- * Race wie bei {@link enforceCap}). Exakt harte Slots brauchen zusätzliche
- * Serialisierung im Create-Pfad (z.B. Unique-Index auf tenantId+slot).
+ * **TOCTOU caveat:** Counting and writing are not atomic—two concurrent
+ * creates can both see `ok` and exceed the limit by one (the same race as
+ * with {@link enforceCap}). Strictly hard slots need additional
+ * serialization in the create path, such as a unique index on
+ * tenantId+slot.
  *
- * Reine Funktion — wirft NICHT und mappt KEINEN HTTP-Status. Ein erreichtes
- * Stock-Limit heißt „Upgrade nötig", nicht „retry later" (429): der Caller
- * entscheidet die Reaktion, typisch ein app-eigener 422/`upgrade_required`
- * mit i18n. Mit `hardSlot` (soft=hard=1.0) ist die Grenze exakt `limit`.
+ * Pure function—it does NOT throw or map an HTTP status. Reaching a stock
+ * limit means "upgrade required", not "retry later" (429); the caller
+ * chooses the response, typically an app-specific 422/`upgrade_required`
+ * with i18n. With `hardSlot` (soft=hard=1.0), the boundary is exactly `limit`.
  */
 export function enforceStockCap(options: {
   readonly current: number;

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

@@ -5,38 +5,38 @@ import {
   createTimestampField,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-// cap-counter — eine Row pro (tenantId, capName, periodStart). tenantId
-// kommt automatisch als Base-Column (Kumiko Multi-Tenant-Default).
+// cap-counter — one row per (tenantId, capName, periodStart). tenantId
+// is added automatically as a base column (Kumiko multi-tenant default).
 //
-// **Identity-Modell:**
-//   - aggregate-id: UUID (Kumiko-ES-Pflicht)
-//   - public natural-key: (tenantId, capName, periodStart) — die Counter-
-//     Engine nutzt deterministic uuidv5 daraus, damit Increments gegen
-//     denselben Stream gehen statt zwei Rows pro Tenant+Cap zu erzeugen
+// **Identity model:**
+//   - aggregate-id: UUID (required by Kumiko ES)
+//   - public natural key: (tenantId, capName, periodStart) — the counter
+//     engine derives a deterministic uuidv5 from it so increments use the
+//     same stream instead of creating two rows per tenant and cap
 //
-// **Felder:**
-//   - capName: das Domain-Konzept ("platform-mails", "ai-tokens-7day",
-//     "db-storage-bytes"). Frei-form String — die App definiert ihre
-//     Cap-Names, die Engine kennt sie nicht enumerated.
-//   - value: aktueller Counter-Wert. Tokens, MB, Anzahl etc — Einheit
-//     ist app-Sache, die Engine zählt nur Zahlen.
-//   - periodStart: Timestamp wann das aktuelle Counter-Period begann.
-//     Calendar-Month-Reset setzt einen neuen periodStart (= neue Aggregate-
-//     Identität). Rolling-Window (z.B. KI-Tokens 7-day) setzt periodStart
-//     einfach nicht zurück und filtert beim Read mit `WHERE timestamp >
-//     now() - 7d` über den Event-Store-Stream — das ist Caller-Sache.
-//   - lastSoftWarnedAt: Anti-Notification-Storm. Wenn Soft-Cap @ 110%
-//     einmal erreicht ist, soll nicht jeder Folge-Increment eine Mail an
-//     den Admin schicken. Pro Period maximal eine Soft-Warning, daher
-//     diese Spalte; nullable, wird beim Reset auf null zurückgesetzt.
+// **Fields:**
+//   - capName: the domain concept ("platform-mails", "ai-tokens-7day",
+//     "db-storage-bytes"). Free-form string — the app defines its cap
+//     names; the engine does not enumerate them.
+//   - value: the current counter value. Tokens, MB, count, etc. — the unit
+//     belongs to the app; the engine only counts numbers.
+//   - periodStart: timestamp when the current counter period began.
+//     A calendar-month reset sets a new periodStart (= new aggregate
+//     identity). A rolling window (e.g. AI tokens over 7 days) does not
+//     reset periodStart and filters on read with `WHERE timestamp >
+//     now() - 7d` over the event-store stream — this is the caller's
+//     responsibility.
+//   - lastSoftWarnedAt: prevents notification storms. Once the soft cap at
+//     110% is reached, subsequent increments must not each send an email to
+//     the admin. There is at most one soft warning per period, so this
+//     nullable column is reset to null when the period resets.
 //
-// **Was bewusst NICHT in der Entity steht:**
-//   - softLimit / hardLimit / cap-toleranz-multipliers — die kommen aus
-//     der App-TierMap zur enforceCap-Aufruf-Zeit. Counter weiß nichts
-//     vom Tier, nur von "wie viele zähle ich".
-//   - userId / aggregate-Reference — Counter sind Plattform-Tenant-
-//     scoped, nicht User-scoped (auch wenn ein User den Increment
-//     auslöst).
+// **What is intentionally not in the entity:**
+//   - softLimit / hardLimit / cap-tolerance multipliers — these come from
+//     the app's tier map when enforceCap is called. The counter knows
+//     nothing about the tier, only how much is being counted.
+//   - userId / aggregate reference — counters are scoped to the platform
+//     tenant, not to a user (even when a user triggers the increment).
 export const capCounterEntity = createEntity({
   table: "read_cap_counters",
   description:

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

@@ -1,49 +1,48 @@
-// cap-counter — Counter-Storage + Increment-API + Soft-Warn-State.
+// cap-counter — Counter Storage + Increment API + Soft-Warn State.
 //
-// **Was diese Feature liefert:**
-//   1. r.entity({ name: "cap-counter" }) — Counter-Rows pro (tenant, capName,
-//      period) für Calendar-Period-Caps (Mails/Monat, Egress/Monat).
-//   2. increment-Handler — atomic counter increment via deterministic
-//      aggregate-id (try-create / executor-update). Race-frei via
-//      event-store optimistic-lock.
-//   3. increment-rolling-Handler (Sprint 4) — append-only Custom-Event-
-//      Stream für Rolling-Window-Caps (KI-Tokens-7d, Egress-24h). Kein
-//      projection — der Wert kommt im Read aus dem Event-Stream.
-//   4. mark-soft-warned-Handler — flippt das Anti-Notification-Storm-
-//      Flag (nur Calendar-Period-Counter).
-//   5. get-counter-Query — sync read der aktuellen Counter-Value
-//      (Calendar).
-//   6. enforceCap + enforceRollingCap-Helper (siehe enforce-cap.ts) —
-//      Pre-Save-Wrapper mit asymmetrischen Soft/Hard-Toleranzen pro
-//      Cap-Profile.
+// **What this feature provides:**
+//   1. r.entity({ name: "cap-counter" }) — counter rows per (tenant, capName,
+//      period) for calendar-period caps (mail/month, egress/month).
+//   2. increment handler — atomic counter increment via deterministic
+//      aggregate-id (try-create / executor-update), made race-free by the
+//      event-store optimistic lock.
+//   3. increment-rolling handler — append-only custom-event stream for
+//      rolling-window caps (AI-tokens-7d, egress-24h). No projection; the
+//      value is read from the event stream.
+//   4. mark-soft-warned handler — flips the anti-notification-storm flag
+//      (calendar-period counters only).
+//   5. get-counter query — synchronous read of the current counter value
+//      (calendar period).
+//   6. enforceCap + enforceRollingCap helpers (see enforce-cap.ts) —
+//      pre-save wrappers with asymmetric soft and hard tolerances per
+//      cap profile.
 //
-// **Calendar vs. Rolling — when to use which:**
+// **Calendar vs. rolling — when to use which:**
 //   - **Calendar period** (bookCapUsage + enforceCap): the cap resets at
-//     period start (1st of the month etc.). The counter is one row in the
-//     projection. Fast read.
+//     period start (the first of the month, etc.). The counter is one row in
+//     the projection, enabling fast reads.
 //   - **Rolling window** (CapCounterHandlers.incrementRolling + enforceRollingCap):
-//     the cap rolls continuously (e.g. "last 7 days"). Values expire
-//     event by event without a reset. No projection; the read sums the
-//     events of the last N days.
+//     the cap rolls continuously (e.g. "last 7 days"). Values expire event
+//     by event without a reset. There is no projection; reads sum the events
+//     from the last N days.
 //
 // **What this feature does NOT do:**
 //   - **No foundation wiring.** mail-foundation / file-foundation /
-//     ai-foundation are BYOK by default today and have no platform pool
+//     ai-foundation are BYOK by default and currently have no platform pool
 //     to count. cap-counter is generic: an app owner who wants to use the
 //     counter calls `bookCapUsage(...)` /
 //     `ctx.write(CapCounterHandlers.incrementRolling, ...)` from their own handler.
-//   - **No reset cron for the calendar period.** Works without one: the
-//     periodStartIso part of the aggregate id rolls over to a fresh
-//     counter at the period tick. Old rows stay for audit.
-//   - **Kein Notification-Pfad als Hard-Wiring.** Cap-counter
-//     entkoppelt — `enforceCapAndMaybeNotify` (siehe enforce-cap.ts)
-//     ist ein Convenience-Helper, der einen Caller-supplied
-//     emit-Callback ausführt; cap-counter kennt delivery-feature
-//     nicht direkt.
+//   - **No reset cron for the calendar period.** It works without one: the
+//     periodStartIso part of the aggregate id rolls over to a fresh counter
+//     at the period boundary. Old rows remain for auditing.
+//   - **No notification path is hard-wired.** cap-counter is decoupled —
+//     `enforceCapAndMaybeNotify` (see enforce-cap.ts) is a convenience helper
+//     that invokes a caller-supplied emit callback; cap-counter does not know
+//     the delivery feature directly.
 //
-// **Boot-Dependencies:** keine. cap-counter ist Plain-Vanilla — kein
-// config, kein secrets, kein tenant-feature nötig. Tenant-Scoping kommt
-// vom Framework-Default (Base-Column tenantId).
+// **Boot dependencies:** none. cap-counter is plain vanilla — it needs no
+// config, secrets, or tenant feature. Tenant scoping comes from the framework
+// default (Base-Column tenantId).
 
 import {
   access,

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

@@ -1,22 +1,21 @@
-// increment-rolling — Rolling-Window-Counter-Increment via Custom-
-// Event statt CRUD/projection. Designed für Caps deren Wert sich
-// kontinuierlich erneuern soll (KI-Tokens-7-Tage, Egress pro 24h).
+// increment-rolling — Rolling-window counter increment via a custom
+// event instead of CRUD/projection. Designed for caps whose values
+// continuously renew (AI tokens over 7 days, egress over 24 hours).
 //
-// **Warum kein r.entity / CRUD wie der Calendar-Counter:** Der
-// Calendar-Counter speichert den kumulierten value in seiner
-// projection-row. Beim Period-Rollover wechselt die aggregate-id auf
-// den neuen Period-Start, das ist der "Reset". Bei Rolling-Window
-// gibt es keinen Rollover-Punkt — der Counter "rollt" kontinuierlich
-// raus. Ein einzelner kumulativer value wäre falsch (würde monoton
-// wachsen ohne Expiration). Die korrekte Read-Semantik ist: SUM aller
-// Increment-Amounts der letzten N Tage. Dafür brauchen wir die
-// einzelnen Increments als separate Events mit ihrem eigenen
-// `amount`-Feld; CRUD-Events tragen nur den kumulativen value.
+// **Why not r.entity / CRUD like the calendar counter:** The calendar
+// counter stores the cumulative value in its projection row. At the
+// period rollover, the aggregate ID changes to the new period start;
+// that is the "reset". A rolling window has no rollover point—the
+// counter continuously rolls out. A single cumulative value would be
+// incorrect because it would grow monotonically without expiration.
+// The correct read semantics are SUM of all increment amounts from the
+// last N days. Therefore, each increment must be a separate event with
+// its own `amount` field; CRUD events carry only the cumulative value.
 //
-// **Aggregate-Stream:** ein Stream pro (tenant, capName) — siehe
-// `rollingCapAggregateId`. Alle Increments hängen am selben Stream
-// in monoton-steigender version. enforceRollingCap liest die letzten
-// N Tage aus diesem Stream.
+// **Aggregate stream:** one stream per (tenant, capName)—see
+// `rollingCapAggregateId`. All increments use the same stream in
+// monotonically increasing version order. enforceRollingCap reads the
+// last N days from this stream.
 
 import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
@@ -33,8 +32,8 @@ const incrementRollingSchema = z.object({
 });
 type IncrementRollingPayload = z.infer<typeof incrementRollingSchema>;
 
-/** Schema des emittierten Custom-Events. Identisch zum Input-Schema:
- *  der Caller zahlt amount, wir hängen es 1:1 an den Stream. */
+/** Schema of the emitted custom event. Identical to the input schema:
+ *  the caller supplies amount, which we append unchanged to the stream. */
 export const rollingIncrementedSchema = incrementRollingSchema;
 
 /** Payload of the event that gives a reserved rolling amount back. */
@@ -44,27 +43,28 @@ export const rollingReleasedSchema = incrementRollingSchema.extend({
   incrementedAt: z.string().optional(),
 });
 
-// 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.
+// Rolling-increment handler — append-only. Race-free: two parallel
+// increments for (tenant, cap) attach to the same aggregate stream at
+// different versions, and the event store orders them.
 //
-// **Kein version_conflict-Pfad** wie beim Calendar-Counter: hier
-// liest niemand den projection-state vor dem Schreiben. Der
-// expectedVersion ist implizit "next-after-current", was der event-
-// store atomar ermittelt.
+// **No version_conflict path** as with the calendar counter: nothing
+// reads projection state before writing. The expectedVersion is
+// implicitly "next-after-current", which the event store determines
+// atomically.
 export const incrementRollingCapHandler: WriteHandlerDef = {
   name: "increment-rolling",
   agent: { expose: false },
   schema: incrementRollingSchema,
-  // Internal handler — System-Caller (Plattform-foundations nach
-  // erfolgreichem Side-Effect) ruft das auf. Tenant-end-users niemals
-  // direkt. Audit-row zeigt welche subsystem-call-site zugehängt hat.
+  // Internal handler — a system caller (platform foundations after a
+  // successful side effect) invokes it. Tenant end users must never
+  // call it directly. The audit row shows which subsystem call site
+  // attached the operation.
   access: { roles: ["SystemAdmin"] },
   handler: async (event, ctx) => {
     // @cast-boundary engine-payload — dispatcher hands handler the
     // already-Zod-validated payload as `unknown`; cast to the typed
-    // shape we declared via incrementRollingSchema. Mirror der
-    // existing increment.write.ts-Cast — gleiche dispatcher-boundary.
+    // shape declared via incrementRollingSchema. Mirror the cast in
+    // existing increment.write.ts—the same dispatcher boundary.
     const payload = event.payload as IncrementRollingPayload;
     const aggregateId = rollingCapAggregateId(event.user.tenantId, payload.capName);
 

package/packages/bundled-features/src/cap-counter/handlers/mark-soft-warned.write.ts

@@ -4,12 +4,11 @@ import { markCapSoftWarned } from "../book-cap-usage.ts";
 
 // mark-soft-warned — sets lastSoftWarnedAt on the counter so subsequent
 // soft-cap-hits in the same period don't re-trigger notifications.
-// Anti-Notification-Storm-Schutz aus Memory `project_pricing_byok_caps`.
+// This prevents notification storms.
 //
-// **Caller-Pattern:** enforceCap-Helper checks if value crosses the
-// soft threshold AND lastSoftWarnedAt is null → calls this handler →
-// emits whatever notification (delivery-feature, ops-alert, etc.). The
-// emit-side is app-specific; this handler only sets the flag.
+// **Caller pattern:** enforceCap-Helper checks whether the value crosses the
+// soft threshold while lastSoftWarnedAt is null, then calls this handler and
+// emits the application-specific notification. This handler only sets the flag.
 const markSoftWarnedSchema = z.object({
   capName: z.string().min(1).max(100),
   periodStartIso: z.string().min(1),

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

@@ -1,5 +1,5 @@
 // Generic stock-cap write-guard factory. Extracted from the near-identical
-// cap-guard.ts app copies in show-pony and publicstatus (infra#446) — the
+// cap-guard.ts app copies in show-pony and publicstatus — the
 // only per-app variable was the Caps shape and how to resolve it for a
 // tenant, so both are now factory parameters.
 
@@ -40,6 +40,13 @@ export type StockCapSpec<TCaps> = {
   readonly field: string;
 };
 
+// Lock on the counted set, not on `code`: two handlers capping the same rows under
+// different codes must still serialize against each other.
+function countedSetKey(spec: Pick<StockCapSpec<unknown>, "table" | "where">): string {
+  const where = Object.entries(spec.where ?? {}).sort(([a], [b]) => a.localeCompare(b));
+  return `${spec.table.tableName}:${JSON.stringify(where)}`;
+}
+
 export type StockCapGuard<TCaps> = {
   readonly checkStockCap: (
     db: TenantDb,
@@ -81,7 +88,7 @@ export function createStockCapGuard<TCaps>(
         // ctx.db is the handler's transaction, so the xact lock releases with its commit or
         // rollback. A handler wrapped in several caps must list them in the same order
         // everywhere; Postgres aborts one side of an inverse order with a deadlock error.
-        await ctx.db.advisoryXactLock(STOCK_CAP_LOCK_NAMESPACE, spec.code);
+        await ctx.db.advisoryXactLock(STOCK_CAP_LOCK_NAMESPACE, countedSetKey(spec));
         const failure = await checkStockCap(ctx.db, spec, { config: ctx.config });
         return failure ?? handler.handler(event, ctx);
       },

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

@@ -44,11 +44,9 @@ import { chainReservations } from "./reservation-chain.ts";
 // =============================================================================
 
 /**
- * Pro-call dynamische Cap-Definition. Wird vor jedem Handler-Aufruf
- * neu evaluiert — typischer Caller liest hier den Tenant-Tier aus
- * dem ctx, mappt ihn auf einen Limit-Wert. `amount` default 1 (count-
- * events); für byte/token-cap übergibt der Caller die Größe aus
- * `event.payload`.
+ * Dynamic cap definition resolved for each handler invocation. A typical caller reads the tenant
+ * tier from `ctx` and maps it to a limit. `amount` defaults to 1 (counting events); for byte or
+ * token caps, the caller supplies the size from `event.payload`.
  */
 export type CalendarCapDef = {
   readonly capName: string;

package/packages/bundled-features/src/cap-overview/handlers/caps-usage.query.ts

@@ -3,7 +3,6 @@ import {
   defineQueryHandler,
   mayOverrideTenant,
   type QueryHandlerDefinition,
-  type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
   AccessDeniedError,
@@ -77,8 +76,7 @@ export function createCapsUsageQuery(
 
       // Override path: limits must read the TARGET tenant's config, not the
       // SystemAdmin caller's.
-      const config =
-        override === undefined ? ctx.config : ctx.configFor?.(targetTenantId as TenantId);
+      const config = override === undefined ? ctx.config : ctx.configFor?.(targetTenantId);
 
       const rows: CapUsageWithMeta[] = await Promise.all(
         caps.map(async (cap) => {

package/packages/bundled-features/src/cap-overview/handlers/tenant-caps-list.query.ts

@@ -86,7 +86,7 @@ async function resolveLimitsByTenantAndCap(
 ): Promise<ReadonlyMap<string, number | null>> {
   const entries = await Promise.all(
     tenants.flatMap(({ tenantId, tier }) => {
-      const context: CapLimitContext = { config: configFor?.(tenantId as TenantId) };
+      const context: CapLimitContext = { config: configFor?.(tenantId) };
       return caps.map(
         async (cap) => [tenantCapKey(tenantId, cap.id), await cap.limit(tier, context)] as const,
       );

package/packages/bundled-features/src/channel-email/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Corrected description of an email channel without app transport",
+    "detail": "Without an app transport only notifications declared with tenantTransport true are delivered; all others fail with missing_credentials, so such apps must mark every outgoing notification or keep an app transport."
+  },
   {
     "version": "0.376.0",
     "type": "improvement",

package/packages/bundled-features/src/channel-email/feature.ts

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