@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/cap-counter/aggregate-id.ts

@@ -0,0 +1,61 @@
+import { v5 as uuidv5 } from "uuid";
+
+// Fixed UUID-namespace für die cap-counter-aggregate-id-Ableitung.
+// Generiert einmalig (2026-05-02), in Stein gemeißelt: ein Wechsel würde
+// jeden existing aggregate-Stream re-keyen → kaputter event-replay,
+// kaputte counter-history, verlorener Audit-Trail. Drift-Pin in
+// __tests__/drift.test.ts pinnt den UUID-Wert.
+const CAP_COUNTER_NAMESPACE = "9c1bf2a3-6e4d-4f5b-8a9c-2d3e4f5a6b7c";
+
+// Separater Namespace für Rolling-Window-Counter (Sprint 4). Eigener
+// Namespace damit das aggregate-id NIE mit einem Calendar-Counter
+// kollidiert, selbst wenn jemand "1970-01-01..." als periodStart in
+// den Calendar-Pfad reinpasst. Drift-Pin in __tests__/drift.test.ts.
+const CAP_COUNTER_ROLLING_NAMESPACE = "8b2ad0c6-1f3e-4f7c-9b8a-3c4d5e6f7a8b";
+
+/**
+ * Deterministic aggregate-id für ein cap-counter-Aggregate aus dem
+ * Tripel (tenantId, capName, periodStart-as-iso). Pro Tenant + Cap +
+ * Period existiert genau ein Aggregate.
+ *
+ * **Period-Semantik:**
+ *   - Calendar-Month-Reset: neuer periodStart am 1. des Monats →
+ *     neuer Aggregate-Stream. Vorherige Counter-Row bleibt für Audit.
+ *   - Rolling-Window: periodStart wird NIE zurückgesetzt (z.B. fixed
+ *     "1970-01-01" als Sentinel). Der Read filtert via Event-Store-
+ *     Timestamp, nicht via Aggregate-Identity.
+ *
+ * **Aufruf-Pattern:** Caller (incrementCap-Helper) ruft das mit dem
+ * tenantId aus event.user.tenantId, dem capName und dem aktuellen
+ * Period-Start auf. Race-frei: zwei parallele Increments für denselben
+ * (tenant, cap, period) gehen auf denselben aggregate-Stream und werden
+ * vom event-store optimistic-lock serialisiert (version_conflict bei
+ * Race → Caller-side Retry).
+ */
+export function capCounterAggregateId(
+  tenantId: string,
+  capName: string,
+  periodStartIso: string,
+): string {
+  return uuidv5(`${tenantId}|${capName}|${periodStartIso}`, CAP_COUNTER_NAMESPACE);
+}
+
+/**
+ * Deterministic aggregate-id für ein Rolling-Window-Counter-Aggregate
+ * aus dem Paar (tenantId, capName). Pro Tenant + Cap existiert genau
+ * EIN Rolling-Aggregate-Stream — die Window-Semantik kommt rein aus
+ * dem Read-Pfad (Filter via event-store-Timestamp).
+ *
+ * **Eigener Namespace:** kollidiert NICHT mit
+ * `capCounterAggregateId(tenantId, capName, "1970-01-01...")` — selbe
+ * inputs, andere uuidv5-namespace, anderer Output-UUID. Damit ist auch
+ * verhindert dass ein versehentlicher Calendar-Increment auf den
+ * Rolling-Stream trifft.
+ *
+ * **Aufruf-Pattern:** Caller (incrementRollingCap-Helper) ruft mit
+ * tenantId + capName auf, erzeugt Increment-Events am stream. Race-
+ * frei: der event-store hängt mit auto-incrementing version an.
+ */
+export function rollingCapAggregateId(tenantId: string, capName: string): string {
+  return uuidv5(`${tenantId}|${capName}`, CAP_COUNTER_ROLLING_NAMESPACE);
+}

package/src/cap-counter/constants.ts

@@ -0,0 +1,32 @@
+// Feature name
+export const CAP_COUNTER_FEATURE = "cap-counter" as const;
+
+// Aggregate types — calendar-period-Counter benutzt CRUD-Events der
+// projection-row. Rolling-Window-Counter benutzt einen eigenen
+// aggregate-type mit custom increment-events (no projection — der
+// Read summiert über die letzten N Tage Events). Sind getrennt damit
+// die r.entity-projection nicht auch noch rolling-counter-rows tracken
+// muss.
+export const CAP_COUNTER_ROLLING_AGGREGATE_TYPE = "cap-counter-rolling" as const;
+
+// Custom event-type für Rolling-Window-Counter. Symmetrisches Paar:
+//   _SHORT  — passt zu `r.defineEvent(short, schema)` im Registrar
+//             (Framework prefixt automatisch zu QN)
+//   _QN     — qualifizierte Form für `ctx.appendEventUnsafe({type})`
+//             + `events.type`-Spalte + `registry.getEvent(qn)`-Lookup
+// Beide MÜSSEN konsistent sein (drift-pin im feature-test).
+export const ROLLING_INCREMENTED_EVENT_SHORT = "rolling-incremented" as const;
+export const ROLLING_INCREMENTED_EVENT_QN = "cap-counter:event:rolling-incremented" as const;
+
+// Qualified write handler names (QN format: scope:type:name).
+export const CapCounterHandlers = {
+  increment: "cap-counter:write:increment",
+  incrementRolling: "cap-counter:write:increment-rolling",
+  markSoftWarned: "cap-counter:write:mark-soft-warned",
+} as const;
+
+// Qualified query handler names.
+export const CapCounterQueries = {
+  list: "cap-counter:query:cap-counter:list",
+  getCounter: "cap-counter:query:get-counter",
+} as const;

package/src/cap-counter/enforce-cap.ts

@@ -0,0 +1,404 @@
+import { createEntityExecutor, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { and, eq, gte } from "drizzle-orm";
+import { rollingCapAggregateId } from "./aggregate-id";
+import {
+  CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
+  CapCounterHandlers,
+  ROLLING_INCREMENTED_EVENT_QN,
+} from "./constants";
+import { capCounterEntity } from "./entity";
+
+// 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);
+
+// =============================================================================
+// Cap-Toleranz-Multipliers
+// =============================================================================
+
+/**
+ * Cap-Toleranz-Profile — pro Cap-Typ asymmetrisch. Quelle: Memory
+ * `project_pricing_byok_caps` §3 + `docs/plans/marketing/produkt/
+ * pricing.md` Cap-Verhalten-Block.
+ *
+ * **Soft** = Notification-Schwelle (Multiplier × Limit). Bei
+ * Erreichen wird einmalig gewarnt (lastSoftWarnedAt setzt das Flag).
+ * Caller-Code emittiert die echte Notification.
+ *
+ * **Hard** = Schreibe-Block (Multiplier × Limit). enforceCap throwt
+ * mit `cap_exceeded`-Error → Dispatcher mapped 429 + Upgrade-Hint.
+ */
+export type CapToleranceProfile = {
+  readonly soft: number;
+  readonly hard: number;
+};
+
+export const CAP_TOLERANCES = {
+  /** Mails / Tokens — billig, BYOK ab Pro. Burst-Buffer großzügig. */
+  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. */
+  hardSlot: { soft: 1.0, hard: 1.0 },
+  /** Egress — Bursty-Traffic legitim, nur extreme Spikes blockieren. */
+  egress: { soft: 1.1, hard: 1.3 },
+} as const satisfies Readonly<Record<string, CapToleranceProfile>>;
+
+export type CapToleranceProfileName = keyof typeof CAP_TOLERANCES;
+
+// =============================================================================
+// Enforcement-Result
+// =============================================================================
+
+export type EnforceCapResult =
+  /** Counter < softLimit. No action. */
+  | { readonly state: "ok"; readonly value: number }
+  /** softLimit ≤ counter < hardLimit. Warning emitted iff first time. */
+  | {
+      readonly state: "soft-hit";
+      readonly value: number;
+      /** True if this call CROSSED the soft-threshold and notified. */
+      readonly crossed: boolean;
+    };
+
+// =============================================================================
+// Enforce-Cap helper
+// =============================================================================
+
+/**
+ * Synchronous read-and-check of the calling tenant's counter for
+ * (capName, period). Returns:
+ *   - "ok" when value < soft-threshold
+ *   - "soft-hit" when soft ≤ value < hard, with `crossed=true` on the
+ *     first hit per period (caller emits notification, then calls
+ *     mark-soft-warned to flip the flag)
+ *
+ * **Throws** `CapExceededError` when value ≥ hard-threshold. Pre-save
+ * hooks call this BEFORE the actual write — the throw rolls back the
+ * transaction, the dispatcher maps the error to HTTP 429 with the
+ * upgrade-hint shape (see CapExceededError below).
+ *
+ * **Sync read implication:** the counter reflects the state at this
+ * exact transaction. Two parallel writes can each see "value < hard"
+ * and both pass — that's a race. Cap-tolerance-buffers (soft 110% /
+ * hard 120% for burstable caps) cover this; truly hard slots
+ * (apps-count) need stricter serialization at the create-handler
+ * level (e.g. uniqueness-index on apps.tenantId+slot-number).
+ */
+export async function enforceCap(
+  ctx: HandlerContext,
+  options: {
+    readonly capName: string;
+    readonly periodStartIso: string;
+    readonly limit: number;
+    readonly profile: CapToleranceProfileName;
+  },
+): Promise<EnforceCapResult> {
+  if (!ctx.db) {
+    throw new Error("cap-counter.enforceCap: ctx.db missing — run inside a handler context");
+  }
+
+  const tolerance = CAP_TOLERANCES[options.profile];
+  const softThreshold = options.limit * tolerance.soft;
+  const hardThreshold = options.limit * tolerance.hard;
+
+  const rows = await ctx.db
+    .select()
+    .from(table)
+    .where(
+      and(eq(table["capName"], options.capName), eq(table["periodStart"], options.periodStartIso)),
+    )
+    .limit(1);
+
+  const row = rows[0];
+  const value = row ? (row["value"] as number) : 0;
+
+  if (value >= hardThreshold) {
+    throw new CapExceededError(options.capName, options.limit, value, tolerance);
+  }
+
+  if (value >= softThreshold) {
+    const lastSoftWarnedAt = row ? row["lastSoftWarnedAt"] : null;
+    return { state: "soft-hit", value, crossed: lastSoftWarnedAt === null };
+  }
+
+  return { state: "ok", value };
+}
+
+// =============================================================================
+// 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:
+ *   - "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").
+ *
+ * **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.
+ */
+export async function enforceRollingCap(
+  ctx: HandlerContext,
+  options: {
+    readonly capName: string;
+    readonly windowDays: number;
+    readonly limit: number;
+    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 tolerance = CAP_TOLERANCES[options.profile];
+  const softThreshold = options.limit * tolerance.soft;
+  const hardThreshold = options.limit * tolerance.hard;
+
+  const aggregateId = rollingCapAggregateId(ctx.user.tenantId, options.capName);
+  const cutoff = Temporal.Now.instant().subtract({ hours: options.windowDays * 24 });
+
+  // events_tenant_type_idx (tenant_id, aggregate_type, created_at)
+  // covers the prefix; the additional aggregate_id eq narrows to the
+  // single rolling-stream. Postgres can use the index even with the
+  // aggregate_id filter applied as a residual.
+  const rows = await ctx.db
+    .select({ payload: eventsTable.payload })
+    .from(eventsTable)
+    .where(
+      and(
+        eq(eventsTable.tenantId, ctx.user.tenantId),
+        eq(eventsTable.aggregateType, CAP_COUNTER_ROLLING_AGGREGATE_TYPE),
+        eq(eventsTable.aggregateId, aggregateId),
+        eq(eventsTable.type, ROLLING_INCREMENTED_EVENT_QN),
+        gte(eventsTable.createdAt, cutoff),
+      ),
+    );
+
+  let value = 0;
+  for (const row of rows) {
+    // @cast-boundary engine-payload — events.payload is jsonb (typed as
+    // unknown by drizzle's $type<Record<string,unknown>>); narrowing
+    // the shape here is a deliberate read-side contract for the
+    // rolling-incremented-event we authored.
+    const payload = row["payload"] as { amount?: number };
+    if (typeof payload.amount === "number") {
+      value += payload.amount;
+    }
+  }
+
+  if (value >= hardThreshold) {
+    throw new CapExceededError(options.capName, options.limit, value, tolerance);
+  }
+
+  if (value >= softThreshold) {
+    return { state: "soft-hit", value, crossed: false };
+  }
+
+  return { state: "ok", value };
+}
+
+// =============================================================================
+// CapExceededError
+// =============================================================================
+
+/**
+ * Thrown by enforceCap when value ≥ hard-threshold. Includes enough
+ * context for the HTTP layer to render an actionable 429 — `code`
+ * matches the framework's error-contract pattern (kebab + scope).
+ *
+ * Caller-side mapping example (in your dispatcher error-handler):
+ *   if (err instanceof CapExceededError) {
+ *     return c.json(
+ *       { error: { code: err.code, message: err.message, capName: err.capName, ... } },
+ *       429,
+ *     );
+ *   }
+ */
+export class CapExceededError extends Error {
+  readonly code = "cap_exceeded" as const;
+  constructor(
+    readonly capName: string,
+    readonly limit: number,
+    readonly currentValue: number,
+    readonly tolerance: CapToleranceProfile,
+  ) {
+    super(
+      `Cap "${capName}" exceeded: current=${currentValue}, limit=${limit}, hard-threshold=${limit * tolerance.hard}. Upgrade tier or wait for next period reset.`,
+    );
+    this.name = "CapExceededError";
+  }
+}
+
+// =============================================================================
+// Period-Helpers
+// =============================================================================
+
+/**
+ * Calendar-month period start in UTC. Use this for monthly caps
+ * (mails, egress).
+ *
+ * Returns ISO string for the 1st of the current month at 00:00 UTC.
+ */
+export function currentCalendarMonthStartIso(
+  now: Temporal.Instant = Temporal.Now.instant(),
+): string {
+  const zoned = now.toZonedDateTimeISO("UTC");
+  const start = zoned.with({
+    day: 1,
+    hour: 0,
+    minute: 0,
+    second: 0,
+    millisecond: 0,
+    microsecond: 0,
+    nanosecond: 0,
+  });
+  return start.toInstant().toString();
+}
+
+// =============================================================================
+// 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.
+// =============================================================================
+
+/**
+ * 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`).
+ *
+ * Beim Rolling-Counter ist `crossed` immer `false` — der Caller muss
+ * dort selbst dedup'en (oder bewusst pro request feuern lassen).
+ */
+export type SoftHitNotifier = (info: {
+  readonly capName: string;
+  readonly value: number;
+  readonly limit: number;
+  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).
+ *
+ * Returnt das `EnforceCapResult` weiter — Caller kann die Logik
+ * verzweigen (z.B. UI-Toast bei soft-hit zusätzlich zur
+ * Email-Notification).
+ */
+export async function enforceCapAndMaybeNotify(
+  ctx: HandlerContext,
+  options: {
+    readonly capName: string;
+    readonly periodStartIso: string;
+    readonly limit: number;
+    readonly profile: CapToleranceProfileName;
+    readonly notify: SoftHitNotifier;
+  },
+): Promise<EnforceCapResult> {
+  const result = await enforceCap(ctx, {
+    capName: options.capName,
+    periodStartIso: options.periodStartIso,
+    limit: options.limit,
+    profile: options.profile,
+  });
+
+  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,
+    });
+    // Flip the soft-warned flag so the same period doesn't re-notify.
+    // We're already inside a write-handler-context, so dispatching the
+    // mark-soft-warned-handler in-line works via ctx.write (re-uses
+    // the request user; the handler's own access-check enforces the
+    // SystemAdmin role on the caller).
+    await ctx.write(CapCounterHandlers.markSoftWarned, {
+      capName: options.capName,
+      periodStartIso: options.periodStartIso,
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Rolling-Window-enforcement + immer-feuert-Notification beim 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).
+ */
+export async function enforceRollingCapAndMaybeNotify(
+  ctx: HandlerContext,
+  options: {
+    readonly capName: string;
+    readonly windowDays: number;
+    readonly limit: number;
+    readonly profile: CapToleranceProfileName;
+    readonly notify: SoftHitNotifier;
+  },
+): Promise<EnforceCapResult> {
+  const result = await enforceRollingCap(ctx, {
+    capName: options.capName,
+    windowDays: options.windowDays,
+    limit: options.limit,
+    profile: options.profile,
+  });
+
+  if (result.state === "soft-hit") {
+    if (!ctx.user?.tenantId) {
+      throw new Error(
+        "cap-counter.enforceRollingCapAndMaybeNotify: ctx.user.tenantId missing — required for notification",
+      );
+    }
+    await options.notify({
+      capName: options.capName,
+      value: result.value,
+      limit: options.limit,
+      tenantId: ctx.user.tenantId,
+    });
+  }
+
+  return result;
+}

package/src/cap-counter/entity.ts

@@ -0,0 +1,48 @@
+import {
+  createEntity,
+  createNumberField,
+  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).
+//
+// **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
+//
+// **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.
+//
+// **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).
+export const capCounterEntity = createEntity({
+  table: "read_cap_counters",
+  fields: {
+    capName: createTextField({ required: true, maxLength: 100 }),
+    value: createNumberField({ required: true, default: 0 }),
+    periodStart: createTimestampField({ required: true }),
+    lastSoftWarnedAt: createTimestampField(),
+  },
+});

package/src/cap-counter/feature.ts

@@ -0,0 +1,90 @@
+// cap-counter — Counter-Storage + Increment-API + Soft-Warn-State.
+//
+// **Was diese Feature liefert:**
+//   1. r.entity("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.
+//
+// **Calendar vs. Rolling — wann welches:**
+//   - **Calendar-Period** (incrementCap + enforceCap): Cap resettet
+//     sich am Period-Start (1. des Monats etc.). Counter ist 1 Row in
+//     der projection. Schneller Read.
+//   - **Rolling-Window** (incrementRollingCap + enforceRollingCap):
+//     Cap rollt kontinuierlich (z.B. "letzten 7 Tage"). Werte
+//     verfallen Event-für-Event ohne Reset. Kein projection — Read
+//     summiert über die letzten N Tage Events.
+//
+// **Was diese Feature NICHT macht:**
+//   - **Kein Foundation-Wiring.** mail-foundation / file-foundation /
+//     ai-foundation sind heute BYOK-default und haben keinen Plattform-
+//     Pool zum Zählen. Cap-Counter ist generic — wenn ein App-Owner
+//     den Counter nutzen will, ruft er `incrementCap(...)` /
+//     `incrementRollingCap(...)` aus seinem eigenen Handler auf.
+//   - **Kein Reset-Cron für Calendar-Period.** Funktioniert ohne —
+//     der periodStartIso-Bestandteil der aggregate-id rollt am
+//     Period-Tick natürlich auf einen frischen Counter. Alte Rows
+//     bleiben für Audit liegen.
+//   - **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.
+//
+// **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).
+
+import {
+  defineEntityListHandler,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { CAP_COUNTER_FEATURE, ROLLING_INCREMENTED_EVENT_SHORT } from "./constants";
+import { capCounterEntity } from "./entity";
+import { getCounterQuery } from "./handlers/get-counter.query";
+import { incrementCapHandler } from "./handlers/increment.write";
+import {
+  incrementRollingCapHandler,
+  rollingIncrementedSchema,
+} from "./handlers/increment-rolling.write";
+import { markSoftWarnedHandler } from "./handlers/mark-soft-warned.write";
+
+const sysadminAccess = { access: { roles: ["SystemAdmin"] } } as const;
+
+export const capCounterFeature: FeatureDefinition = defineFeature(CAP_COUNTER_FEATURE, (r) => {
+  r.entity("cap-counter", capCounterEntity);
+
+  // Custom Domain-Event für Rolling-Counter. r.defineEvent registriert
+  // das Schema beim Registry; ctx.appendEventUnsafe im Handler nutzt
+  // dasselbe Schema für Append-Time-Validation. QN nach Prefixing:
+  // "cap-counter:event:rolling-incremented" (siehe
+  // ROLLING_INCREMENTED_EVENT_QN).
+  r.defineEvent(ROLLING_INCREMENTED_EVENT_SHORT, rollingIncrementedSchema);
+
+  // Custom write-handlers.
+  // - increment: Calendar-Period (CRUD via projection-row).
+  // - increment-rolling: Rolling-Window (Custom-Event, no projection).
+  // - mark-soft-warned: Anti-Notification-Storm-Flag (nur Calendar).
+  r.writeHandler(incrementCapHandler);
+  r.writeHandler(incrementRollingCapHandler);
+  r.writeHandler(markSoftWarnedHandler);
+
+  // Custom + standard reads. Sysadmin-cross-tenant via list, per-tenant
+  // single-row via get-counter. Detail-by-id-handler bewusst weggelassen
+  // (kein Use-Case; der natürliche Lookup ist über capName + period, nicht
+  // über aggregate-id).
+  r.queryHandler(defineEntityListHandler("cap-counter", capCounterEntity, sysadminAccess));
+  r.queryHandler(getCounterQuery);
+});

package/src/cap-counter/handlers/get-counter.query.ts

@@ -0,0 +1,43 @@
+import { createEntityExecutor, type QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+import { capCounterEntity } from "../entity";
+
+const { table } = createEntityExecutor("cap-counter", capCounterEntity);
+
+// get-counter — return the current counter row for (calling tenant,
+// capName, periodStartIso). Returns null if no increment has happened
+// in this period yet — caller treats that as "value = 0, no warning
+// flagged".
+//
+// **Composition:** enforceCap-helper consumes this. UIs that show
+// remaining-quota call it directly.
+const getCounterSchema = z.object({
+  capName: z.string().min(1).max(100),
+  periodStartIso: z.string().min(1),
+});
+
+export const getCounterQuery: QueryHandlerDef = {
+  name: "get-counter",
+  schema: getCounterSchema,
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  handler: async (query, ctx) => {
+    const { capName, periodStartIso } = query.payload as z.infer<typeof getCounterSchema>;
+
+    // ctx.db is tenant-scoped; filter by capName + periodStart explicitly.
+    const rows = await ctx.db
+      .select()
+      .from(table)
+      .where(
+        and(
+          eq(table["capName"], capName),
+          // periodStart is stored as Temporal.Instant; compare against
+          // the iso string directly (timestamptz-column round-trips).
+          eq(table["periodStart"], periodStartIso),
+        ),
+      )
+      .limit(1);
+
+    return rows[0] ?? null;
+  },
+};