@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/billing-foundation/web/billing-plans-panel.js

@@ -0,0 +1,165 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// @runtime client
+import { toInstant } from "@cosmicdrift/kumiko-headless";
+import { useLocale, useMutation, usePrimitives, useQuery, useTranslation, } from "@cosmicdrift/kumiko-renderer";
+import { formatMoney, PlanCard, PlanGrid, } from "@cosmicdrift/kumiko-renderer-web";
+import { useState } from "react";
+import { BillingPlanActions, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, SubscriptionStatuses, } from "../constants.js";
+function intervalKey(price) {
+    if (price === null || price.interval === null)
+        return undefined;
+    return price.intervalCount !== null && price.intervalCount > 1
+        ? `billing-foundation.plans.everyInterval.${price.interval}`
+        : `billing-foundation.plans.perInterval.${price.interval}`;
+}
+function localizedParams(params, locale) {
+    if (params === undefined)
+        return undefined;
+    const localized = {};
+    for (const [key, value] of Object.entries(params)) {
+        localized[key] =
+            typeof value === "number" ? new Intl.NumberFormat(locale).format(value) : value;
+    }
+    return localized;
+}
+/** Which action the plan "would" offer if it weren't blocked — mirrors
+ *  plan-catalog.ts's own decision tree, since `unavailable` collapses both
+ *  "would checkout" and "would switch" into one action and the disabled CTA
+ *  still needs the right label. */
+function impliedAction(plan, subscription) {
+    return subscription !== null && !subscription.terminal && plan.tier !== subscription.tier
+        ? "switch"
+        : "checkout";
+}
+/** Shared manage/reactivate secondaryAction for a current-tier card — used
+ *  by both a catalog plan's own card (`isCurrent`) and the synthetic
+ *  out-of-catalog current-tier card, so the two don't duplicate the
+ *  cancelAt-aware label choice. */
+function manageOrReactivateAction(canManage, subscription, t, onManage, redirecting) {
+    if (!canManage)
+        return undefined;
+    return {
+        label: t(subscription?.cancelAt != null
+            ? "billing-foundation.plans.reactivate"
+            : "billing-foundation.plans.manage"),
+        onClick: onManage,
+        disabled: redirecting,
+    };
+}
+/** `!canPurchase` hides every CTA outright (spec: "keine CTAs, Hinweis
+ *  purchaseNotAllowed") — distinct from the `unavailable` action's disabled
+ *  CTA, which still shows a button (e.g. for a plan whose price failed to
+ *  load) so this check runs before the general unavailable-fallback. */
+function planCta(plan, result, t, onAction, redirecting) {
+    if (plan.action === BillingPlanActions.current)
+        return undefined;
+    if (plan.action === BillingPlanActions.paymentPending)
+        return undefined;
+    if (!result.canPurchase)
+        return undefined;
+    const kind = plan.action === BillingPlanActions.switch ? "switch" : impliedAction(plan, result.subscription);
+    const label = t(kind === "switch" ? "billing-foundation.plans.switch" : "billing-foundation.plans.choose", {
+        plan: t(plan.labelKey),
+    });
+    if (plan.action === BillingPlanActions.unavailable) {
+        return { label, onClick: () => { }, disabled: true };
+    }
+    return {
+        label,
+        onClick: () => onAction(plan.tier, kind),
+        disabled: redirecting,
+    };
+}
+export function BillingPlansPanel(_props) {
+    const t = useTranslation();
+    const locale = useLocale().locale();
+    const { Banner } = usePrimitives();
+    const query = useQuery(SubscriptionFoundationQueries.billingPlans, {});
+    const checkoutMutation = useMutation(SubscriptionFoundationHandlers.startPlanCheckout);
+    const switchMutation = useMutation(SubscriptionFoundationHandlers.switchPlan);
+    const portalMutation = useMutation(SubscriptionFoundationHandlers.createPortalSession);
+    // Single flag for every CTA + the manage-button: set on click, held through
+    // a successful mutation (the tab is about to navigate away), reset only on
+    // failure. Scoping "pending" per-button would leave the just-clicked button
+    // enabled during its own in-flight request — a double-click risk — and
+    // `mutation.pending` alone drops before `window.location.assign` completes.
+    const [redirecting, setRedirecting] = useState(false);
+    async function handleAction(tier, kind) {
+        setRedirecting(true);
+        const mutation = kind === "checkout" ? checkoutMutation : switchMutation;
+        const result = await mutation.mutate({ tier });
+        if (result.isSuccess) {
+            window.location.assign(result.data.url);
+        }
+        else {
+            setRedirecting(false);
+        }
+    }
+    async function handleManage() {
+        setRedirecting(true);
+        const result = await portalMutation.mutate({});
+        if (result.isSuccess) {
+            window.location.assign(result.data.url);
+        }
+        else {
+            setRedirecting(false);
+        }
+    }
+    if (query.error !== null) {
+        return (_jsx(Banner, { variant: "error", testId: "billing-plans-panel-error", children: t(query.error.i18nKey, query.error.i18nParams) }));
+    }
+    if (query.loading && !query.data) {
+        return (_jsx(Banner, { variant: "loading", testId: "billing-plans-panel-loading", children: t("kumiko.widget.loading") }));
+    }
+    if (!query.data)
+        return null;
+    const result = query.data;
+    const mutationError = checkoutMutation.error ?? switchMutation.error ?? portalMutation.error;
+    const canManage = result.subscription !== null && !result.subscription.terminal && result.canPurchase;
+    function toCardProps(plan) {
+        const key = intervalKey(plan.price);
+        return {
+            title: t(plan.labelKey),
+            description: plan.action === BillingPlanActions.paymentPending
+                ? t("billing-foundation.plans.paymentPending")
+                : undefined,
+            current: plan.isCurrent,
+            // Billing off means "no price to show", not "price failed to load" —
+            // undefined drops the price row entirely, distinct from the `null`
+            // price-unavailable state resolvePlanPrices returns for a genuine
+            // provider lookup failure.
+            price: !result.enabled && plan.isCurrent
+                ? undefined
+                : plan.price === null
+                    ? null
+                    : {
+                        amount: formatMoney(plan.price.unitAmount, plan.price.currency, locale),
+                        ...(key !== undefined && {
+                            period: t(key, {
+                                count: new Intl.NumberFormat(locale).format(plan.price.intervalCount ?? 1),
+                            }),
+                        }),
+                    },
+            features: plan.benefits.map((benefit) => t(benefit.labelKey, localizedParams(benefit.params, locale))),
+            cta: planCta(plan, result, t, handleAction, redirecting),
+            secondaryAction: plan.isCurrent
+                ? manageOrReactivateAction(canManage, result.subscription, t, handleManage, redirecting)
+                : undefined,
+        };
+    }
+    // The catalog's plans don't have to cover every tier a tenant can be on
+    // (a legacy/free/pilot tier outside `catalog.plans`) — when none of the
+    // rendered plans is the current one, a synthetic current-tier card (no
+    // price, no cta) keeps it visible regardless of enabled/disabled.
+    const currentTierInPlans = result.plans.some((plan) => plan.isCurrent);
+    const visiblePlans = result.enabled
+        ? result.plans
+        : result.plans.filter((plan) => plan.isCurrent);
+    return (_jsxs("div", { className: "flex flex-col gap-4", "data-testid": "billing-plans-panel", children: [!result.enabled && (_jsx(Banner, { variant: "info", testId: "billing-plans-panel-disabled", children: t("billing-foundation.plans.billingDisabled") })), !result.canPurchase && (_jsx(Banner, { variant: "warning", testId: "billing-plans-panel-readonly", children: t("billing-foundation.plans.purchaseNotAllowed") })), mutationError !== null && (_jsx(Banner, { variant: "error", testId: "billing-plans-panel-mutation-error", children: t(mutationError.i18nKey, mutationError.i18nParams) })), result.subscription?.status === SubscriptionStatuses.pastDue && (_jsx(Banner, { variant: "warning", testId: "billing-plans-panel-past-due", children: t("billing-foundation.plans.pastDue") })), result.subscription !== null &&
+                !result.subscription.terminal &&
+                result.subscription.cancelAt != null && (_jsxs(Banner, { variant: "info", testId: "billing-plans-panel-cancel-scheduled", children: [t("billing-foundation.plans.cancelScheduled", {
+                        date: toInstant(result.subscription.cancelAt).toLocaleString(locale, {
+                            dateStyle: "medium",
+                        }),
+                    }), " ", t("billing-foundation.plans.switchRequiresReactivation")] })), _jsxs(PlanGrid, { testId: "billing-plans-grid", children: [!currentTierInPlans && (_jsx(PlanCard, { title: t(result.currentTier.labelKey), current: true, testId: "billing-plan-card-current", features: result.currentTier.benefits.map((benefit) => t(benefit.labelKey, localizedParams(benefit.params, locale))), secondaryAction: manageOrReactivateAction(canManage, result.subscription, t, handleManage, redirecting) })), visiblePlans.map((plan) => (_jsx(PlanCard, { testId: `billing-plan-card-${plan.tier}`, ...toCardProps(plan) }, plan.tier)))] })] }));
+}

package/dist/billing-foundation/web/client-plugin.d.ts

@@ -0,0 +1,6 @@
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+export type BillingFoundationClientOptions = {
+    readonly translations?: TranslationsByLocale;
+};
+export declare function billingFoundationClient(options?: BillingFoundationClientOptions): ClientFeatureDefinition;

package/dist/billing-foundation/web/client-plugin.js

@@ -0,0 +1,11 @@
+import { BILLING_FOUNDATION_FEATURE, BILLING_PLANS_PANEL_COMPONENT } from "../constants.js";
+import { BillingPlansPanel } from "./billing-plans-panel.js";
+export function billingFoundationClient(options) {
+    return {
+        name: BILLING_FOUNDATION_FEATURE,
+        extensionSectionComponents: {
+            [BILLING_PLANS_PANEL_COMPONENT]: BillingPlansPanel,
+        },
+        ...(options?.translations !== undefined && { translations: options.translations }),
+    };
+}

package/dist/billing-foundation/web/index.d.ts

@@ -0,0 +1,4 @@
+export { BILLING_PLANS_SCREEN_ID, type BillingPlanAction, BillingPlanActions, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, type SubscriptionStatus, SubscriptionStatuses, } from "../constants.js";
+export type { BillingPlanBenefit, BillingPlanCatalog, BillingPlansResult, BillingPlanView, } from "../types.js";
+export { BillingPlansPanel } from "./billing-plans-panel.js";
+export { type BillingFoundationClientOptions, billingFoundationClient } from "./client-plugin.js";

package/dist/billing-foundation/web/index.js

@@ -0,0 +1,8 @@
+// @runtime client
+// Public exports for the browser side of the billing-foundation feature.
+// Consumed via `@cosmicdrift/kumiko-bundled-features/billing-foundation/web` —
+// the server side (createBillingFoundationFeature) lives under
+// `@cosmicdrift/kumiko-bundled-features/billing-foundation` and has no React deps.
+export { BILLING_PLANS_SCREEN_ID, BillingPlanActions, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, SubscriptionStatuses, } from "../constants.js";
+export { BillingPlansPanel } from "./billing-plans-panel.js";
+export { billingFoundationClient } from "./client-plugin.js";

package/dist/billing-foundation/webhook-handler.d.ts

@@ -0,0 +1,16 @@
+export type SubscriptionWebhookRouteOptions = {
+    /** Route path — MUST carry the `:providerName` path-param. Default
+     *  "/api/subscription/webhook/:providerName". */
+    readonly path?: string;
+    /** Runs after a successful dispatchSystemWrite, before the 200 response —
+     *  lets callers (e.g. subscription-tier-sync) chain a side-effect without
+     *  duplicating the provider-resolve/payload-mapping logic above. Returning
+     *  a failed WriteResult turns the response into the same 500 a dispatch
+     *  failure would produce. */
+    readonly afterDispatch?: (dispatched: import("@cosmicdrift/kumiko-framework/engine").WriteResult, tenantId: import("@cosmicdrift/kumiko-framework/engine").TenantId, deps: import("@cosmicdrift/kumiko-framework/api").SignatureExtraRouteDeps) => Promise<import("@cosmicdrift/kumiko-framework/engine").WriteResult>;
+};
+/**
+ * Builds the `entry:"signature"` extraRoute definition. Mount via
+ * `extraRoutes: [createSubscriptionWebhookRoute()]`.
+ */
+export declare function createSubscriptionWebhookRoute(options?: SubscriptionWebhookRouteOptions): import("@cosmicdrift/kumiko-framework/api").ExtraRouteDefinition;

package/dist/billing-foundation/webhook-handler.js

@@ -0,0 +1,100 @@
+// Multi-provider: the plugin is selected via the `:providerName` path-param
+// (Stripe → /stripe, PayPal → /paypal), one route mounts every plugin at once.
+// rawBody is intentionally NOT JSON-parsed before verify() — Stripe's
+// signature check needs the exact bytes. No JWT/cookie auth: the provider's
+// webhook signature in verify() IS the auth, so no c.get("user") here.
+import { ExtraRouteRejection, signatureRoute } from "@cosmicdrift/kumiko-framework/api";
+import { BILLING_FOUNDATION_FEATURE, BillingEventKinds, SUBSCRIPTION_PROVIDER_EXTENSION, SubscriptionFoundationHandlers, } from "./constants.js";
+const DEFAULT_WEBHOOK_PATH = "/api/subscription/webhook/:providerName";
+function resolveProvider(registry, providerName) {
+    return registry
+        .getExtensionUsages(SUBSCRIPTION_PROVIDER_EXTENSION)
+        .find((u) => u.entityName === providerName)?.options;
+}
+/**
+ * Builds the `entry:"signature"` extraRoute definition. Mount via
+ * `extraRoutes: [createSubscriptionWebhookRoute()]`.
+ */
+export function createSubscriptionWebhookRoute(options = {}) {
+    const path = options.path ?? DEFAULT_WEBHOOK_PATH;
+    return signatureRoute({
+        method: "POST",
+        path,
+        entry: "signature",
+        verify: async ({ rawBody, headers, params }, deps) => {
+            const providerName = params["providerName"];
+            if (!providerName) {
+                throw new ExtraRouteRejection(400, {
+                    error: {
+                        code: "subscription_provider_path_missing",
+                        message: `${BILLING_FOUNDATION_FEATURE}: mount the route with a :providerName path-param so each provider has its own URL (Stripe-Dashboard → /stripe, PayPal-Dashboard → /paypal).`,
+                    },
+                }, "subscription webhook route mounted without :providerName");
+            }
+            const plugin = resolveProvider(deps.registry, providerName);
+            if (!plugin) {
+                throw new ExtraRouteRejection(404, {
+                    error: {
+                        code: "subscription_provider_not_registered",
+                        message: `${BILLING_FOUNDATION_FEATURE}: provider "${providerName}" not registered as '${SUBSCRIPTION_PROVIDER_EXTENSION}'-plugin. Mount the matching subscription-${providerName} feature.`,
+                    },
+                }, `subscription provider "${providerName}" not registered`);
+            }
+            // Throws on sig-mismatch — the ExtraRoute wrapper maps any non-
+            // ExtraRouteRejection throw to 401 extra_route_signature_invalid
+            // (= config-bug, retry won't help, provider stop).
+            const event = await plugin.verifyAndParseWebhook(rawBody, headers, deps.secrets);
+            return { providerName, event };
+        },
+        handler: async (c, verified, deps) => {
+            if (verified.event === null) {
+                return c.json({ ignored: true }, 200);
+            }
+            const parsed = verified.event;
+            const tenantId = parsed.tenantId;
+            if (parsed.kind === BillingEventKinds.payment) {
+                const dispatched = await deps.dispatchSystemWrite({
+                    handlerQn: SubscriptionFoundationHandlers.processPaymentEvent,
+                    tenantId,
+                    payload: {
+                        providerEventId: parsed.providerEventId,
+                        providerName: parsed.providerName,
+                        providerCustomerId: parsed.providerCustomerId,
+                        priceId: parsed.priceId,
+                        rawPayload: parsed.rawPayload,
+                    },
+                });
+                return respondFromDispatch(c, dispatched.isSuccess && options.afterDispatch
+                    ? await options.afterDispatch(dispatched, tenantId, deps)
+                    : dispatched, "subscription_payment_webhook_processing_failed", "Internal error processing payment event");
+            }
+            const dispatched = await deps.dispatchSystemWrite({
+                handlerQn: SubscriptionFoundationHandlers.processEvent,
+                tenantId,
+                payload: {
+                    providerEventId: parsed.providerEventId,
+                    providerName: parsed.providerName,
+                    type: parsed.type,
+                    providerCustomerId: parsed.providerCustomerId,
+                    providerSubscriptionId: parsed.providerSubscriptionId,
+                    status: parsed.status,
+                    tier: parsed.tier,
+                    currentPeriodEndIso: parsed.currentPeriodEnd,
+                    ...(parsed.cancelAt !== undefined && { cancelAtIso: parsed.cancelAt }),
+                    rawPayload: parsed.rawPayload,
+                },
+            });
+            return respondFromDispatch(c, dispatched.isSuccess && options.afterDispatch
+                ? await options.afterDispatch(dispatched, tenantId, deps)
+                : dispatched, "subscription_webhook_processing_failed", "Internal error processing subscription event");
+        },
+    });
+}
+/** Shared 500/200-mapping for both dispatch branches above. Internal error →
+ *  provider should retry, hence 500 instead of 401/404 (transient, not a config-bug). */
+function respondFromDispatch(c, dispatched, errorCode, errorMessage) {
+    if (!dispatched.isSuccess) {
+        return c.json({ error: { code: errorCode, message: errorMessage, details: dispatched.error } }, 500);
+    }
+    return c.json({ processed: true, ...(dispatched.data ?? {}) }, 200); // @cast-boundary engine-bridge
+}

package/dist/cap-counter/aggregate-id.d.ts

@@ -0,0 +1,24 @@
+/**
+ * One aggregate per (tenantId, capName, periodStart-as-iso). A new calendar
+ * period yields a new stream, so the previous counter row stays for audit.
+ * Parallel bookings for the same triple share one stream; the event store's
+ * optimistic lock serializes them and bookCapUsage retries the loser.
+ */
+export declare function capCounterAggregateId(tenantId: string, capName: string, periodStartIso: string): string;
+/**
+ * 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 declare function rollingCapAggregateId(tenantId: string, capName: string): string;

package/dist/cap-counter/aggregate-id.js

@@ -0,0 +1,42 @@
+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";
+/**
+ * One aggregate per (tenantId, capName, periodStart-as-iso). A new calendar
+ * period yields a new stream, so the previous counter row stays for audit.
+ * Parallel bookings for the same triple share one stream; the event store's
+ * optimistic lock serializes them and bookCapUsage retries the loser.
+ */
+// @wrapper-known uuid-domain
+export function capCounterAggregateId(tenantId, capName, periodStartIso) {
+    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.
+ */
+// @wrapper-known uuid-domain
+export function rollingCapAggregateId(tenantId, capName) {
+    return uuidv5(`${tenantId}|${capName}`, CAP_COUNTER_ROLLING_NAMESPACE);
+}

package/dist/cap-counter/book-cap-usage.d.ts

@@ -0,0 +1,19 @@
+import { type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { type HandlerContext, type TenantId, type WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+export type BookCapUsageOptions = {
+    readonly capName: string;
+    readonly periodStartIso: string;
+    readonly amount?: number;
+    readonly outsideTransaction?: boolean;
+};
+export declare function bookCapUsage(ctx: HandlerContext, options: BookCapUsageOptions): Promise<WriteResult>;
+export type MarkCapSoftWarnedOptions = {
+    readonly capName: string;
+    readonly periodStartIso: string;
+};
+export declare function markCapSoftWarned(ctx: HandlerContext, options: MarkCapSoftWarnedOptions): Promise<WriteResult>;
+export type ReadRollingCapUsageOptions = {
+    readonly capName: string;
+    readonly windowDays: number;
+};
+export declare function readRollingCapUsage(db: TenantDb, tenantId: TenantId, options: ReadRollingCapUsageOptions): Promise<number>;

package/dist/cap-counter/book-cap-usage.js

@@ -0,0 +1,108 @@
+// In-process cap booking for the caller's own tenant; no SystemAdmin dispatch needed.
+import { runInOwnTransaction } from "@cosmicdrift/kumiko-framework/db";
+import { createEntityExecutor, } from "@cosmicdrift/kumiko-framework/engine";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { Temporal } from "temporal-polyfill";
+import * as z from "zod";
+import { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id.js";
+import { CAP_COUNTER_ROLLING_AGGREGATE_TYPE, ROLLING_INCREMENTED_EVENT_QN } from "./constants.js";
+import { capCounterEntity } from "./entity.js";
+const { table, executor } = createEntityExecutor("cap-counter", capCounterEntity);
+const capBookingSchema = z.object({
+    capName: z.string().min(1).max(100),
+    periodStartIso: z.string().min(1),
+    amount: z.number().int().positive().default(1),
+});
+function isLostCounterRace(result) {
+    return !result.isSuccess && result.error.code === "version_conflict";
+}
+// Each attempt writes event + projection atomically, so a conflict means another booker just committed — bounded by how many bookers run at once (pool max, default 10); this ceiling only guards against non-convergence.
+const MAX_COUNTER_WRITE_ATTEMPTS = 20;
+async function retryCounterWriteOnVersionConflict(writeAttempt) {
+    let result = await writeAttempt();
+    for (let attempt = 1; attempt < MAX_COUNTER_WRITE_ATTEMPTS && isLostCounterRace(result); attempt++) {
+        result = await writeAttempt();
+    }
+    return result;
+}
+function requireOutsideTransactionDb(ctx) {
+    if (!ctx.dbOutsideTransaction) {
+        throw new Error("cap-counter.bookCapUsage: outsideTransaction requested but ctx.dbOutsideTransaction is undefined");
+    }
+    return ctx.dbOutsideTransaction;
+}
+export async function bookCapUsage(ctx, options) {
+    const parsed = capBookingSchema.parse(options);
+    const aggregateId = capCounterAggregateId(ctx.user.tenantId, parsed.capName, parsed.periodStartIso);
+    async function attemptWrite(db) {
+        const existing = await db.selectMany(table, { id: aggregateId }, { limit: 1 });
+        if (existing.length === 0) {
+            return executor.create({
+                id: aggregateId,
+                capName: parsed.capName,
+                value: parsed.amount,
+                periodStart: Temporal.Instant.from(parsed.periodStartIso),
+                lastSoftWarnedAt: null,
+            }, ctx.user, db);
+        }
+        const currentRow = existing[0];
+        if (!currentRow) {
+            throw new Error("cap-counter.bookCapUsage: row vanished between length-check and read");
+        }
+        const currentValue = currentRow["value"]; // @cast-boundary db-row
+        const currentVersion = currentRow["version"]; // @cast-boundary db-row
+        return executor.update({
+            id: aggregateId,
+            version: currentVersion,
+            changes: { value: currentValue + parsed.amount },
+        }, ctx.user, db);
+    }
+    if (options.outsideTransaction) {
+        const outsideDb = requireOutsideTransactionDb(ctx);
+        return retryCounterWriteOnVersionConflict(() => runInOwnTransaction(outsideDb, attemptWrite));
+    }
+    return retryCounterWriteOnVersionConflict(() => attemptWrite(ctx.db));
+}
+export async function markCapSoftWarned(ctx, options) {
+    const aggregateId = capCounterAggregateId(ctx.user.tenantId, options.capName, options.periodStartIso);
+    return retryCounterWriteOnVersionConflict(async () => {
+        const existing = await ctx.db.selectMany(table, { id: aggregateId }, { limit: 1 });
+        if (existing.length === 0) {
+            throw new Error(`cap-counter: cannot mark-soft-warned, no counter found for tenant=${ctx.user.tenantId} cap=${options.capName} period=${options.periodStartIso}`);
+        }
+        const row = existing[0];
+        if (!row) {
+            throw new Error("cap-counter.markCapSoftWarned: row vanished between length-check and read");
+        }
+        const currentVersion = row["version"]; // @cast-boundary db-row
+        return executor.update({
+            id: aggregateId,
+            version: currentVersion,
+            changes: { lastSoftWarnedAt: Temporal.Now.instant() },
+        }, ctx.user, ctx.db);
+    });
+}
+// Sums usage without throwing — for callers that only need the raw number
+// (e.g. a CapSpec.usage callback), not the enforce-and-throw path.
+export async function readRollingCapUsage(db, tenantId, options) {
+    const aggregateId = rollingCapAggregateId(tenantId, options.capName);
+    const cutoff = Temporal.Now.instant().subtract({ hours: options.windowDays * 24 });
+    const rows = await db.selectMany(eventsTable, {
+        tenantId,
+        aggregateType: CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
+        aggregateId,
+        type: ROLLING_INCREMENTED_EVENT_QN,
+        createdAt: { gte: 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 mirrors enforceRollingCap's own read-side contract.
+        const payload = row["payload"];
+        if (typeof payload.amount === "number") {
+            value += payload.amount;
+        }
+    }
+    return value;
+}

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

@@ -0,0 +1,14 @@
+export declare const CAP_COUNTER_FEATURE: "cap-counter";
+export declare const CAP_COUNTER_LIST_SCREEN_ID: "cap-list";
+export declare const CAP_COUNTER_ROLLING_AGGREGATE_TYPE: "cap-counter-rolling";
+export declare const ROLLING_INCREMENTED_EVENT_SHORT: "rolling-incremented";
+export declare const ROLLING_INCREMENTED_EVENT_QN: "cap-counter:event:rolling-incremented";
+export declare const CapCounterHandlers: {
+    readonly increment: "cap-counter:write:increment";
+    readonly incrementRolling: "cap-counter:write:increment-rolling";
+    readonly markSoftWarned: "cap-counter:write:mark-soft-warned";
+};
+export declare const CapCounterQueries: {
+    readonly list: "cap-counter:query:cap-counter:list";
+    readonly getCounter: "cap-counter:query:get-counter";
+};

package/dist/cap-counter/constants.js

@@ -0,0 +1,29 @@
+// Feature name
+export const CAP_COUNTER_FEATURE = "cap-counter";
+export const CAP_COUNTER_LIST_SCREEN_ID = "cap-list";
+// 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";
+// 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.unsafeAppendEvent({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";
+export const ROLLING_INCREMENTED_EVENT_QN = "cap-counter:event:rolling-incremented";
+// 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",
+};
+// Qualified query handler names.
+export const CapCounterQueries = {
+    list: "cap-counter:query:cap-counter:list",
+    getCounter: "cap-counter:query:get-counter",
+};