@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.387.0

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

@@ -2,23 +2,21 @@ import { KumikoError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { type CapCounterContext } from "./book-cap-usage.ts";
 /**
- * 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;
     readonly hard: number;
 };
 export declare 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. */
     readonly burstable: {
         readonly soft: 1.1;
         readonly hard: 1.2;
@@ -28,12 +26,12 @@ export declare const CAP_TOLERANCES: {
         readonly soft: 1;
         readonly hard: 1.05;
     };
-    /** Apps-Count, Plattform-Slots — gebuchte Kapazität, kein Buffer. */
+    /** App count and platform slots — purchased capacity, with no buffer. */
     readonly hardSlot: {
         readonly soft: 1;
         readonly hard: 1;
     };
-    /** Egress — Bursty-Traffic legitim, nur extreme Spikes blockieren. */
+    /** Egress — bursty traffic is legitimate; only extreme spikes are blocked. */
     readonly egress: {
         readonly soft: 1.1;
         readonly hard: 1.3;
@@ -92,28 +90,26 @@ export declare function enforceCap(ctx: CapCounterContext, options: {
     readonly i18nKey?: string;
 }): Promise<EnforceCapResult>;
 /**
- * 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 declare function enforceRollingCap(ctx: CapCounterContext, options: {
     readonly capName: string;
@@ -153,13 +149,13 @@ export declare class CapExceededError extends KumikoError {
 export declare function currentCalendarMonthStartIso(now?: Temporal.Instant): string;
 export declare function calendarMonthPeriodEndIso(periodStartIso: string): string;
 /**
- * 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;
@@ -168,14 +164,14 @@ export type SoftHitNotifier = (info: {
     readonly tenantId: string;
 }) => 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 declare function enforceCapAndMaybeNotify(ctx: CapCounterContext, options: {
     readonly capName: string;
@@ -189,14 +185,14 @@ export declare function enforceCapAndMaybeNotify(ctx: CapCounterContext, options
     readonly markSoftWarnedOutsideTransaction?: boolean;
 }): Promise<EnforceCapResult>;
 /**
- * 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 declare function enforceRollingCapAndMaybeNotify(ctx: CapCounterContext, options: {
     readonly capName: string;
@@ -215,24 +211,25 @@ export type StockCapResult = {
     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 declare function enforceStockCap(options: {
     readonly current: number;

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

@@ -5,13 +5,13 @@ import { markCapSoftWarned, readRollingCapUsage, resolveCapCounterScope, } from
 import { capCounterEntity } from "./entity.js";
 const { table } = createEntityExecutor("cap-counter", capCounterEntity);
 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 },
 };
 export function assertBelowHardCap(valueSeenByLastUnit, cap) {
@@ -84,28 +84,26 @@ export async function enforceCap(ctx, options) {
 // Enforce-Rolling-Cap helper
 // =============================================================================
 /**
- * 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, options) {
     const { user, readDb } = resolveCapCounterScope(ctx, false);
@@ -200,14 +198,14 @@ export function calendarMonthPeriodEndIso(periodStartIso) {
         .toString();
 }
 /**
- * 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, options) {
     const result = await enforceCap(ctx, {
@@ -238,14 +236,14 @@ export async function enforceCapAndMaybeNotify(ctx, options) {
     return result;
 }
 /**
- * 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, options) {
     const result = await enforceRollingCap(ctx, {
@@ -265,24 +263,25 @@ export async function enforceRollingCapAndMaybeNotify(ctx, options) {
     return result;
 }
 /**
- * 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) {
     const hardThreshold = options.limit * CAP_TOLERANCES[options.profile].hard;

package/dist/cap-counter/entity.js

@@ -1,36 +1,36 @@
 import { createBigIntField, createEntity, createTextField, 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: "One usage counter per tenant, cap name and calendar period, holding the accumulated value and the timestamp of the last soft-limit warning.",

package/dist/cap-counter/feature.js

@@ -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, defineEntityListHandler, defineFeature, } from "@cosmicdrift/kumiko-framework/engine";
 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";

package/dist/cap-counter/handlers/increment-rolling.write.d.ts

@@ -1,7 +1,7 @@
 import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-/** 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 declare const rollingIncrementedSchema: z.ZodObject<{
     capName: z.ZodString;
     amount: z.ZodDefault<z.ZodNumber>;