@cosmicdrift/kumiko-bundled-features 0.316.0 → 0.317.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.316.0",
+  "version": "0.317.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -133,12 +133,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.316.0",
-    "@cosmicdrift/kumiko-framework": "0.316.0",
-    "@cosmicdrift/kumiko-headless": "0.316.0",
-    "@cosmicdrift/kumiko-renderer": "0.316.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.316.0",
-    "@cosmicdrift/kumiko-types": "0.316.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.317.0",
+    "@cosmicdrift/kumiko-framework": "0.317.0",
+    "@cosmicdrift/kumiko-headless": "0.317.0",
+    "@cosmicdrift/kumiko-renderer": "0.317.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.317.0",
+    "@cosmicdrift/kumiko-types": "0.317.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -167,8 +167,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.316.0",
-    "@cosmicdrift/kumiko-locale-es": "0.316.0",
+    "@cosmicdrift/kumiko-locale-de": "0.317.0",
+    "@cosmicdrift/kumiko-locale-es": "0.317.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/auth-email-password/web/__tests__/use-url-token.test.tsx

@@ -4,7 +4,7 @@ import { useUrlToken } from "../auth-form-primitives";
 
 // #774: magic-link tokens must not linger in browser history / Referer.
 // useUrlToken reads the token once, then scrubs the param via replaceState.
-// (dom.preload resets window.location to http://localhost/ after each test.)
+// (preload/dom resets window.location to http://localhost/ after each test.)
 describe("useUrlToken (magic-link history hygiene)", () => {
   test("reads ?token= and strips it from the URL, keeping other params", () => {
     window.history.replaceState(null, "", "http://localhost/reset?token=secret-abc&keep=1");

package/src/cap-counter/__tests__/with-cap-enforcement.integration.test.ts

@@ -135,11 +135,47 @@ const bookOutsideTxThenFailHandler: WriteHandlerDef = {
 const NEWSLETTER_TENANT_ONLY_QN = "newsletter:write:send-newsletter-tenant-only";
 const BOOK_OUTSIDE_TX_QN = "newsletter:write:book-outside-tx-then-fail";
 
+// =============================================================================
+// Parallel-booking-race probes — return bookCapUsage's result
+// directly so a lost optimistic-lock race surfaces as an HTTP error instead
+// of being swallowed.
+// =============================================================================
+
+const PARALLEL_BOOKING_IN_TX_CAP_NAME = "parallel-booking-in-tx-cap";
+const bookCapUsageInTxHandler: WriteHandlerDef = {
+  name: "book-cap-usage-in-tx",
+  schema: z.object({}),
+  access: { roles: ["TenantAdmin"] },
+  handler: (_event, ctx) =>
+    bookCapUsage(ctx, {
+      capName: PARALLEL_BOOKING_IN_TX_CAP_NAME,
+      periodStartIso: TENANT_ONLY_PERIOD,
+    }),
+};
+
+const PARALLEL_BOOKING_OUTSIDE_TX_CAP_NAME = "parallel-booking-outside-tx-cap";
+const bookCapUsageOutsideTxHandler: WriteHandlerDef = {
+  name: "book-cap-usage-outside-tx",
+  schema: z.object({}),
+  access: { roles: ["TenantAdmin"] },
+  handler: (_event, ctx) =>
+    bookCapUsage(ctx, {
+      capName: PARALLEL_BOOKING_OUTSIDE_TX_CAP_NAME,
+      periodStartIso: TENANT_ONLY_PERIOD,
+      outsideTransaction: true,
+    }),
+};
+
+const BOOK_CAP_USAGE_IN_TX_QN = "newsletter:write:book-cap-usage-in-tx";
+const BOOK_CAP_USAGE_OUTSIDE_TX_QN = "newsletter:write:book-cap-usage-outside-tx";
+
 const newsletterFeature = defineFeature("newsletter", (r) => {
   r.writeHandler(wrappedCalendar);
   r.writeHandler(wrappedRolling);
   r.writeHandler(wrappedCalendarTenantOnly);
   r.writeHandler(bookOutsideTxThenFailHandler);
+  r.writeHandler(bookCapUsageInTxHandler);
+  r.writeHandler(bookCapUsageOutsideTxHandler);
 });
 
 // =============================================================================
@@ -410,3 +446,69 @@ describe("withCapEnforcement — calendar, TenantAdmin-only callers", () => {
     expect(usageB).toBe(0);
   });
 });
+
+// =============================================================================
+// Parallel bookCapUsage calls for the same (tenant, cap, period)
+// =============================================================================
+
+const PARALLEL_BOOKINGS = 6;
+
+describe("bookCapUsage — parallel bookings for the same period", () => {
+  test("in-tx: N concurrent bookings all succeed and the counter sums to N, then 2N", async () => {
+    const user = tenantAdminOnlyFor(2601);
+
+    await Promise.all(
+      Array.from({ length: PARALLEL_BOOKINGS }, () =>
+        stack.http.writeOk(BOOK_CAP_USAGE_IN_TX_QN, {}, user),
+      ),
+    );
+    const afterCreateRace = await readCounter(
+      user,
+      PARALLEL_BOOKING_IN_TX_CAP_NAME,
+      TENANT_ONLY_PERIOD,
+    );
+    expect(afterCreateRace!["value"]).toBe(PARALLEL_BOOKINGS);
+
+    await Promise.all(
+      Array.from({ length: PARALLEL_BOOKINGS }, () =>
+        stack.http.writeOk(BOOK_CAP_USAGE_IN_TX_QN, {}, user),
+      ),
+    );
+    const afterUpdateRace = await readCounter(
+      user,
+      PARALLEL_BOOKING_IN_TX_CAP_NAME,
+      TENANT_ONLY_PERIOD,
+    );
+    expect(afterUpdateRace!["value"]).toBe(PARALLEL_BOOKINGS * 2);
+  });
+
+  // N=6 stays below the default pool max (10): each outside-tx request holds
+  // both a handler-tx connection and a dbOutsideTransaction connection.
+  test("outside-tx: N concurrent bookings all succeed and the counter sums to N, then 2N", async () => {
+    const user = tenantAdminOnlyFor(2602);
+
+    await Promise.all(
+      Array.from({ length: PARALLEL_BOOKINGS }, () =>
+        stack.http.writeOk(BOOK_CAP_USAGE_OUTSIDE_TX_QN, {}, user),
+      ),
+    );
+    const afterCreateRace = await readCounter(
+      user,
+      PARALLEL_BOOKING_OUTSIDE_TX_CAP_NAME,
+      TENANT_ONLY_PERIOD,
+    );
+    expect(afterCreateRace!["value"]).toBe(PARALLEL_BOOKINGS);
+
+    await Promise.all(
+      Array.from({ length: PARALLEL_BOOKINGS }, () =>
+        stack.http.writeOk(BOOK_CAP_USAGE_OUTSIDE_TX_QN, {}, user),
+      ),
+    );
+    const afterUpdateRace = await readCounter(
+      user,
+      PARALLEL_BOOKING_OUTSIDE_TX_CAP_NAME,
+      TENANT_ONLY_PERIOD,
+    );
+    expect(afterUpdateRace!["value"]).toBe(PARALLEL_BOOKINGS * 2);
+  });
+});

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

@@ -14,23 +14,10 @@ const CAP_COUNTER_NAMESPACE = "9c1bf2a3-6e4d-4f5b-8a9c-2d3e4f5a6b7c";
 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).
+ * 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(

package/src/cap-counter/book-cap-usage.ts

@@ -1,6 +1,6 @@
 // In-process cap booking for the caller's own tenant; no SystemAdmin dispatch needed.
 
-import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { runInOwnTransaction, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntityExecutor,
   type HandlerContext,
@@ -22,6 +22,27 @@ const capBookingSchema = z.object({
   amount: z.number().int().positive().default(1),
 });
 
+function isLostCounterRace(result: WriteResult): boolean {
+  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: () => Promise<WriteResult>,
+): Promise<WriteResult> {
+  let result: WriteResult = await writeAttempt();
+  for (
+    let attempt = 1;
+    attempt < MAX_COUNTER_WRITE_ATTEMPTS && isLostCounterRace(result);
+    attempt++
+  ) {
+    result = await writeAttempt();
+  }
+  return result;
+}
+
 export type BookCapUsageOptions = {
   readonly capName: string;
   readonly periodStartIso: string;
@@ -43,43 +64,50 @@ export async function bookCapUsage(
   options: BookCapUsageOptions,
 ): Promise<WriteResult> {
   const parsed = capBookingSchema.parse(options);
-  const db = options.outsideTransaction ? requireOutsideTransactionDb(ctx) : ctx.db;
   const aggregateId = capCounterAggregateId(
     ctx.user.tenantId,
     parsed.capName,
     parsed.periodStartIso,
   );
 
-  const existing = await db.selectMany(table, { id: aggregateId }, { limit: 1 });
-  if (existing.length === 0) {
-    return executor.create(
+  async function attemptWrite(db: TenantDb): Promise<WriteResult> {
+    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"] as number; // @cast-boundary db-row
+    const currentVersion = currentRow["version"] as number; // @cast-boundary db-row
+    return executor.update(
       {
         id: aggregateId,
-        capName: parsed.capName,
-        value: parsed.amount,
-        periodStart: Temporal.Instant.from(parsed.periodStartIso),
-        lastSoftWarnedAt: null,
+        version: currentVersion,
+        changes: { value: currentValue + parsed.amount },
       },
       ctx.user,
       db,
     );
   }
 
-  const currentRow = existing[0];
-  if (!currentRow) {
-    throw new Error("cap-counter.bookCapUsage: row vanished between length-check and read");
+  if (options.outsideTransaction) {
+    const outsideDb = requireOutsideTransactionDb(ctx);
+    return retryCounterWriteOnVersionConflict(() => runInOwnTransaction(outsideDb, attemptWrite));
   }
-  const currentValue = currentRow["value"] as number; // @cast-boundary db-row
-  const currentVersion = currentRow["version"] as number; // @cast-boundary db-row
-  return executor.update(
-    {
-      id: aggregateId,
-      version: currentVersion,
-      changes: { value: currentValue + parsed.amount },
-    },
-    ctx.user,
-    db,
-  );
+  return retryCounterWriteOnVersionConflict(() => attemptWrite(ctx.db));
 }
 
 export type MarkCapSoftWarnedOptions = {
@@ -97,27 +125,29 @@ export async function markCapSoftWarned(
     options.periodStartIso,
   );
 
-  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}`,
+  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"] as number; // @cast-boundary db-row
+
+    return executor.update(
+      {
+        id: aggregateId,
+        version: currentVersion,
+        changes: { lastSoftWarnedAt: Temporal.Now.instant() },
+      },
+      ctx.user,
+      ctx.db,
     );
-  }
-  const row = existing[0];
-  if (!row) {
-    throw new Error("cap-counter.markCapSoftWarned: row vanished between length-check and read");
-  }
-  const currentVersion = row["version"] as number; // @cast-boundary db-row
-
-  return executor.update(
-    {
-      id: aggregateId,
-      version: currentVersion,
-      changes: { lastSoftWarnedAt: Temporal.Now.instant() },
-    },
-    ctx.user,
-    ctx.db,
-  );
+  });
 }
 
 export type ReadRollingCapUsageOptions = {

package/src/cap-counter/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.317.0",
+    "type": "fix",
+    "title": "bookCapUsage/markCapSoftWarned count parallel bookings instead of losing them",
+    "detail": "Both re-read and retry when they lose an optimistic-lock race, so parallel bookings for the same cap period all count instead of failing or getting silently dropped. The outsideTransaction path runs each attempt in its own transaction (runInOwnTransaction), keeping event append and projection update atomic. withCapEnforcement now throws a failed booking instead of discarding it."
+  },
   {
     "version": "0.307.0",
     "type": "improvement",

package/src/cap-counter/handlers/increment.write.ts

@@ -18,9 +18,8 @@ type IncrementPayload = z.infer<typeof incrementSchema>;
 
 // increment-cap — atomic counter increment via the event-store's
 // optimistic-lock. Two parallel increments for the same (tenant, cap,
-// period) go to the same aggregate; the second one's append fails with
-// version_conflict — caller retries (the dispatcher already handles
-// that for write-handlers, see version_conflict-retry-policy).
+// period) go to the same aggregate; parallel-safety comes from the
+// re-read-and-retry loop inside bookCapUsage, not from this handler.
 //
 // **Two paths:**
 //   1. Aggregate doesn't exist yet (first increment of the period) →

package/src/cap-counter/with-cap-enforcement.ts

@@ -21,6 +21,7 @@ import type {
   WriteEvent,
   WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
 import { bookCapUsage } from "./book-cap-usage";
 import { CapCounterHandlers } from "./constants";
 import {
@@ -68,7 +69,7 @@ export type CalendarCapResolver = (
  *   2. pre-call: `enforceCapAndMaybeNotify` — throws CapExceededError
  *      on hard-hit (handler never runs), notifies on soft-hit-crossing
  *   3. invoke the wrapped handler
- *   4. post-success: dispatch `cap-counter:write:increment` with `amount`
+ *   4. post-success: book usage via `bookCapUsage` with `amount`
  *
  * The returned handler-def keeps the original name/schema/access
  * untouched — only the handler-fn is wrapped. The dispatcher sees
@@ -101,11 +102,12 @@ export function withCapEnforcement(
       // Post-success increment. Skip on failure so a failed write
       // doesn't burn cap-quota. amount default 1.
       if (result.isSuccess) {
-        await bookCapUsage(ctx, {
+        const booked = await bookCapUsage(ctx, {
           capName: cap.capName,
           amount: cap.amount ?? 1,
           periodStartIso: cap.periodStartIso,
         });
+        if (!booked.isSuccess) throw reraiseAsKumikoError(booked.error);
       }
 
       return result;

package/src/user-data-rights/web/__tests__/privacy-center-screen.test.tsx

@@ -143,7 +143,7 @@ async function waitForDownloadReady(view: ReturnType<typeof render>): Promise<vo
 
 // CI runs this file in its own `bun test` process (own ci.yml step), NOT in the
 // shared `kumiko check` run — see bunfig.ci.toml pathIgnorePatterns. In the shared
-// single-process happy-dom, the global `afterEach` from `test-setup/dom.preload.ts`
+// single-process happy-dom, the global `afterEach` from the preload/dom module
 // plus accumulated global DOM/event state across ~30 prior DOM test files corrupts
 // these in-flight renders (#457-class). A fresh process has no such accumulation.
 // The QN-Drift-Pins + formatDate describes below are pure-logic and CI-stable.