@cosmicdrift/kumiko-samples 0.346.0 → 0.348.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.346.0",
+  "version": "0.348.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.346.0",
+  "version": "0.348.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>",

package/packages/bundled-features/src/auth-email-password/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.348.0",
+    "type": "fix",
+    "title": "AuthGate accepts a loginUrl function, renders LoginScreen on the login route, and LoginScreen follows a validated next",
+    "detail": "AuthGate accepts a loginUrl function and LoginScreen follows a validated next\n`AuthGateOptions.loginUrl` may now be a function `(locale, returnPath) => string` in addition to a string. When the user is already on the login route, the gate renders the LoginScreen instead of redirecting. After a successful login (and MFA verify or setup), the screen follows the `next` query parameter, but only for relative same-origin paths: no `//`, no scheme, no backslash, no control characters.",
+    "migration": "No action needed. String loginUrl keeps working."
+  },
+  {
+    "version": "0.347.0",
+    "type": "fix",
+    "title": "Signup-confirm under an MFA policy returns the signup landing path and the activation screen forwards it to login as next",
+    "detail": "Signup with an MFA requirement keeps its landing path\nWhen the MFA policy asks for a factor at self-registration, `/auth/signup-confirm` now also returns the `landingPath` that `auth.postAuthLanding` resolves for the signup flow (including a claimed handover). `SignupCompleteScreen` passes it to the login link as `?next=`, so the login that follows can land where a signup without MFA would have."
+  },
   {
     "version": "0.345.0",
     "type": "fix",

package/packages/bundled-features/src/auth-email-password/handlers/signup-confirm.write.ts

@@ -76,7 +76,16 @@ export type SignupConfirmData =
       // actually succeeded (see the handler body below).
       readonly handover?: { readonly entityType: string; readonly id: string };
     }
-  | Exclude<LoginResult, { readonly kind: "auth-session" }>;
+  | (Exclude<LoginResult, { readonly kind: "auth-session" }> & {
+      // What the response needs to resolve the signup landing although no
+      // session is issued yet.
+      readonly signup: {
+        readonly roles: readonly string[];
+        readonly tenantId: TenantId;
+        readonly tenantKey: string;
+        readonly handover?: ClaimedHandover;
+      };
+    });
 
 export type SignupConfirmOptions = Pick<LoginHandlerOptions, "mfaStatusChecker">;
 
@@ -240,7 +249,18 @@ export function createSignupConfirmHandler(opts: SignupConfirmOptions = {}) {
 
         if (mfaGate !== undefined) {
           committed = true;
-          return { isSuccess: true, data: mfaGate };
+          return {
+            isSuccess: true,
+            data: {
+              ...mfaGate,
+              signup: {
+                roles: session.roles,
+                tenantId: provisioned.tenantId,
+                tenantKey,
+                ...(handover !== undefined && { handover }),
+              },
+            },
+          };
         }
 
         committed = true;

package/packages/bundled-features/src/auth-email-password/web/auth-client.ts

@@ -362,9 +362,11 @@ export type SignupConfirmSuccess = {
 
 // mfa-pending: account exists but the server issued no session because the
 // new roles require a second factor — the user must sign in to enroll.
+// landingPath is where the signup would have landed; the login that follows
+// should end there.
 export type SignupConfirmResult =
   | ({ readonly kind: "signed-in" } & SignupConfirmSuccess)
-  | { readonly kind: "mfa-pending" };
+  | { readonly kind: "mfa-pending"; readonly landingPath?: string };
 
 export async function confirmSignup(
   token: string,
@@ -383,7 +385,13 @@ export async function confirmSignup(
       readonly mfaSetupRequired?: boolean;
     };
     if (body.mfaRequired === true || body.mfaSetupRequired === true) {
-      return { ok: true, data: { kind: "mfa-pending" } };
+      return {
+        ok: true,
+        data: {
+          kind: "mfa-pending",
+          ...(typeof body.landingPath === "string" && { landingPath: body.landingPath }),
+        },
+      };
     }
     return { ok: true, data: { kind: "signed-in", ...body } };
   }

package/packages/bundled-features/src/auth-email-password/web/auth-gate.tsx

@@ -9,8 +9,13 @@
 // (nur `{ children }`-Prop). Der Sample kann so einen eigenen Login-
 // Screen rein konfigurieren, ohne den Gate selbst ersetzen zu müssen.
 
+import { useLocale } from "@cosmicdrift/kumiko-renderer";
 import { type ComponentType, type ReactNode, useEffect, useState } from "react";
-import { assertNavigableUrl, buildLoginRedirectUrl } from "./auth-redirect.js";
+import {
+  assertNavigableUrl,
+  buildLoginRedirectUrl,
+  followNextAfterLogin,
+} from "./auth-redirect.js";
 import { LoginScreen, type LoginScreenProps } from "./login-screen.js";
 import { SessionProvider, useSession } from "./session.js";
 import { SessionBootstrapErrorScreen } from "./session-bootstrap-error.js";
@@ -108,7 +113,10 @@ export function createLoginRoute(
       return (
         <MfaVerifyComponent
           challengeToken={challengeToken}
-          onSuccess={() => setChallengeToken(null)}
+          onSuccess={() => {
+            setChallengeToken(null);
+            followNextAfterLogin();
+          }}
           onCancel={() => setChallengeToken(null)}
         />
       );
@@ -126,7 +134,10 @@ export function createLoginRoute(
             // refresh() never rejects: a failed refresh surfaces as status
             // "error" (bootstrap error screen with retry), so only the
             // success path needs to clear setupRequest.
-            void refresh().then(() => setSetupRequest(null));
+            void refresh().then(() => {
+              setSetupRequest(null);
+              followNextAfterLogin();
+            });
           }}
           onCancel={() => setSetupRequest(null)}
         />
@@ -150,11 +161,16 @@ export function createLoginRoute(
   return LoginRoute;
 }
 
+/** Builds the login page URL. `returnPath` is the current path + query + hash;
+ *  append it as `next` yourself (use `NEXT_QUERY_PARAM`) if the login page should return there. */
+export type LoginUrlBuilder = (locale: string, returnPath: string) => string;
+
 export type AuthGateOptions = LoginRouteOptions & {
-  /** Login page outside the SPA (root-relative path or http(s) URL). Unauthenticated
-   *  visitors are sent there with `next=<current path>`; the built-in login screen
-   *  is not rendered. */
-  readonly loginUrl?: string;
+  /** Login page outside the SPA (root-relative path or http(s) URL), or a function
+   *  that builds it per locale. Unauthenticated visitors are sent there with
+   *  `next=<current path>` (a string gets `next` appended; a function decides itself).
+   *  On the login route itself the gate renders the built-in login screen instead. */
+  readonly loginUrl?: string | LoginUrlBuilder;
 };
 
 export type SessionAuthGateOptions = AuthGateOptions & {
@@ -162,30 +178,52 @@ export type SessionAuthGateOptions = AuthGateOptions & {
   readonly postLogoutUrl?: string;
 };
 
-function redirectToLoginUrl(loginUrl: string): void {
-  const { origin, pathname, search, hash } = window.location;
+type LoginRedirect =
+  | { readonly kind: "on-login-route" }
+  | { readonly kind: "redirect"; readonly url: string };
+
+// @internal — exported for unit tests only.
+export function resolveLoginRedirect(
+  loginUrl: string | LoginUrlBuilder,
+  locale: string,
+  { origin, pathname, search, hash }: Pick<Location, "origin" | "pathname" | "search" | "hash">,
+): LoginRedirect {
+  const returnPath = `${pathname}${search}${hash}`;
+  const target = typeof loginUrl === "function" ? loginUrl(locale, returnPath) : loginUrl;
+  if (typeof loginUrl === "function") assertNavigableUrl(target, "loginUrl()");
   // Compared before `next` is appended: the target always differs from the current
   // URL once it carries next, so a gate mounted on the login page itself would loop.
-  const loginLocation = new URL(loginUrl, origin);
-  if (loginLocation.origin === origin && loginLocation.pathname === pathname) return;
-  window.location.replace(buildLoginRedirectUrl(loginUrl, `${pathname}${search}${hash}`, origin));
+  const loginLocation = new URL(target, origin);
+  if (loginLocation.origin === origin && loginLocation.pathname === pathname) {
+    return { kind: "on-login-route" };
+  }
+  return {
+    kind: "redirect",
+    url:
+      typeof loginUrl === "function" ? target : buildLoginRedirectUrl(target, returnPath, origin),
+  };
 }
 
 export function makeAuthGate(opts: AuthGateOptions = {}): ComponentType<{
   children: ReactNode;
 }> {
   const { loginUrl } = opts;
-  if (loginUrl !== undefined) assertNavigableUrl(loginUrl, "loginUrl");
+  if (typeof loginUrl === "string") assertNavigableUrl(loginUrl, "loginUrl");
   const LoginRoute = createLoginRoute(opts);
   function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     const { status } = useSession();
-    const redirectsToLoginUrl = loginUrl !== undefined && status === "unauthenticated";
+    const locale = useLocale().locale();
+    const loginRedirect =
+      loginUrl !== undefined && status === "unauthenticated"
+        ? resolveLoginRedirect(loginUrl, locale, window.location)
+        : null;
+    const redirectUrl = loginRedirect?.kind === "redirect" ? loginRedirect.url : null;
     // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
     useEffect(() => {
-      if (redirectsToLoginUrl) redirectToLoginUrl(loginUrl);
-    }, [redirectsToLoginUrl]);
+      if (redirectUrl !== null) window.location.replace(redirectUrl);
+    }, [redirectUrl]);
     if (status === "authenticated") return <>{children}</>;
-    if (redirectsToLoginUrl) return null;
+    if (redirectUrl !== null) return null;
     return <LoginRoute />;
   }
   return AuthGate;

package/packages/bundled-features/src/auth-email-password/web/auth-redirect.ts

@@ -58,3 +58,17 @@ export function buildLoginRedirectUrl(
   const isSameOrigin = target.origin === currentOrigin;
   return isSameOrigin ? `${target.pathname}${target.search}${target.hash}` : target.href;
 }
+
+// Login screens call this after a successful login. `next` is re-validated
+// here because it is read from the URL, i.e. attacker-controlled. Returns
+// true when it navigated.
+export function followNextAfterLogin(
+  location: Pick<Location, "search" | "pathname" | "replace"> = window.location,
+): boolean {
+  const next = readNextFromSearch(location.search);
+  if (next === null) return false;
+  // Following a next that points at the login page itself would reload it forever.
+  if (new URL(next, "https://next.invalid").pathname === location.pathname) return false;
+  location.replace(next);
+  return true;
+}

package/packages/bundled-features/src/auth-email-password/web/login-screen.tsx

@@ -17,6 +17,7 @@ import {
   requestEmailVerification,
 } from "./auth-client.js";
 import { AuthCard } from "./auth-form-primitives.js";
+import { followNextAfterLogin } from "./auth-redirect.js";
 import { useSession } from "./session.js";
 
 // Resend-Status für den "Bestätigungs-Mail erneut senden"-Flow, der bei
@@ -142,7 +143,10 @@ export function LoginScreen({
     setResendStatus({ kind: "idle" });
     const res = await session.login({ email, password });
     setSubmitting(false);
-    if (res.kind === "success") return;
+    if (res.kind === "success") {
+      followNextAfterLogin();
+      return;
+    }
     if (res.kind === "mfa-challenge") {
       if (onMfaChallenge) {
         onMfaChallenge(res.challengeToken);

package/packages/bundled-features/src/auth-email-password/web/signup-complete-screen.tsx

@@ -22,6 +22,7 @@ import { type FormEvent, type ReactNode, useState } from "react";
 import { confirmSignup, type SignupConfirmSuccess } from "./auth-client.js";
 import { passwordPairIssue, resolvePostAuthHref } from "./auth-form-logic.js";
 import { AuthCard, useUrlToken } from "./auth-form-primitives.js";
+import { buildLoginRedirectUrl } from "./auth-redirect.js";
 
 export type SignupCompleteScreenProps = {
   readonly title?: string;
@@ -76,7 +77,11 @@ export function SignupCompleteScreen({
     if (res.ok) {
       if (res.data.kind === "mfa-pending") {
         setMfaPending(true);
-        setContinueHref(loginHref);
+        setContinueHref(
+          res.data.landingPath === undefined
+            ? loginHref
+            : buildLoginRedirectUrl(loginHref, res.data.landingPath, window.location.origin),
+        );
         return;
       }
       // Cookies are already set (auto-login). Show a confirmation with an

package/packages/bundled-features/src/cap-counter/book-cap-usage.ts

@@ -59,6 +59,8 @@ export type BookCapUsageOptions = {
   readonly periodStartIso: string;
   readonly amount?: number;
   readonly outsideTransaction?: boolean;
+  // Runs on every attempt with the freshly read value, so a throw rejects the booking against the state it would actually be applied to (a version-conflict retry re-reads and re-checks).
+  readonly guardCurrentValue?: (currentValue: number) => void;
 };
 
 function requireOutsideTransactionDb(ctx: HandlerContext): TenantDb {
@@ -73,6 +75,22 @@ function requireOutsideTransactionDb(ctx: HandlerContext): TenantDb {
 export async function bookCapUsage(
   ctx: HandlerContext,
   options: BookCapUsageOptions,
+): Promise<WriteResult> {
+  return applyCapDelta(ctx, options, "add");
+}
+
+// Gives back a reservation whose operation failed afterwards; the counter never drops below 0.
+export async function releaseCapUsage(
+  ctx: HandlerContext,
+  options: Omit<BookCapUsageOptions, "guardCurrentValue">,
+): Promise<WriteResult> {
+  return applyCapDelta(ctx, options, "subtract");
+}
+
+async function applyCapDelta(
+  ctx: HandlerContext,
+  options: BookCapUsageOptions,
+  direction: "add" | "subtract",
 ): Promise<WriteResult> {
   const parsed = capBookingSchema.parse(options);
   const aggregateId = capCounterAggregateId(
@@ -84,6 +102,8 @@ export async function bookCapUsage(
   async function attemptWrite(db: TenantDb): Promise<WriteResult> {
     const existing = await db.selectMany(table, { id: aggregateId }, { limit: 1 });
     if (existing.length === 0) {
+      options.guardCurrentValue?.(0);
+      if (direction === "subtract") return { isSuccess: true, data: {} };
       return executor.create(
         {
           id: aggregateId,
@@ -103,11 +123,17 @@ export async function bookCapUsage(
     }
     const currentValue = currentRow["value"] as number; // @cast-boundary db-row
     const currentVersion = currentRow["version"] as number; // @cast-boundary db-row
+    options.guardCurrentValue?.(currentValue);
     return executor.update(
       {
         id: aggregateId,
         version: currentVersion,
-        changes: { value: currentValue + parsed.amount },
+        changes: {
+          value:
+            direction === "add"
+              ? currentValue + parsed.amount
+              : Math.max(0, currentValue - parsed.amount),
+        },
       },
       ctx.user,
       db,
@@ -124,6 +150,7 @@ export async function bookCapUsage(
 export type MarkCapSoftWarnedOptions = {
   readonly capName: string;
   readonly periodStartIso: string;
+  readonly outsideTransaction?: boolean;
 };
 
 export async function markCapSoftWarned(
@@ -137,8 +164,8 @@ export async function markCapSoftWarned(
     parsed.periodStartIso,
   );
 
-  return retryCounterWriteOnVersionConflict(async () => {
-    const existing = await ctx.db.selectMany(table, { id: aggregateId }, { limit: 1 });
+  async function attemptMark(db: TenantDb): Promise<WriteResult> {
+    const existing = await 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=${parsed.capName} period=${parsed.periodStartIso}`,
@@ -162,9 +189,15 @@ export async function markCapSoftWarned(
         changes: { lastSoftWarnedAt: Temporal.Now.instant() },
       },
       ctx.user,
-      ctx.db,
+      db,
     );
-  });
+  }
+
+  if (options.outsideTransaction) {
+    const outsideDb = requireOutsideTransactionDb(ctx);
+    return retryCounterWriteOnVersionConflict(() => runInOwnTransaction(outsideDb, attemptMark));
+  }
+  return retryCounterWriteOnVersionConflict(() => attemptMark(ctx.db));
 }
 
 export type ReadRollingCapUsageOptions = {

package/packages/bundled-features/src/cap-counter/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.348.0",
+    "type": "fix",
+    "title": "withCapEnforcement reserves cap usage before the handler transaction so parallel calls cannot exceed the hard limit",
+    "detail": "withCapEnforcement reserves cap usage before the handler transaction\n`withCapEnforcement` used to check the cap and book the usage in two separate steps, so parallel calls could all pass the same stale read and exceed the hard limit. The wrapper now only declares the cap through the new `WriteHandlerDef.reserveBeforeTransaction` hook. The dispatcher runs the hook after the access, feature and schema checks and before the handler transaction opens. The hard-cap check and the increment are one short, version-guarded write that commits at once, so no connection is held across the handler and capped calls on the same counter still run in parallel. The returned release gives the amount back (never below 0) after the transaction ended without committing: rollback, failure result, throw or failed commit. Each reservation covers exactly one top-level execution: a capped handler reached through a nested `ctx.write` or run a second time in the same command is rejected. A wrapped handler now keeps its own `rateLimit`, `escapeHatch` and `additionalRateLimits` (the old wrapper dropped them). The reservation runs before the rate-limit gate, so a rate-limited caller can still cause reserve and release writes. If a COMMIT fails with an unknown outcome, the release can under-count. `bookCapUsage` accepts a `guardCurrentValue` callback, `markCapSoftWarned` and `enforceCapAndMaybeNotify` can write outside the handler transaction, and the soft-warning pre-check now honors `amount`. `withRollingCapEnforcement` is unchanged and keeps its check-then-book race.",
+    "migration": "No action needed. Calls above the hard limit are now rejected with cap_exceeded even when they race. A capped handler must not be called through ctx.write from another handler."
+  },
   {
     "version": "0.338.0",
     "type": "improvement",

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

@@ -63,6 +63,20 @@ export type EnforceCapResult =
       readonly crossed: boolean;
     };
 
+export function assertBelowHardCap(
+  valueSeenByLastUnit: number,
+  cap: {
+    readonly capName: string;
+    readonly limit: number;
+    readonly profile: CapToleranceProfileName;
+  },
+): void {
+  const tolerance = CAP_TOLERANCES[cap.profile];
+  if (valueSeenByLastUnit >= cap.limit * tolerance.hard) {
+    throw new CapExceededError(cap.capName, cap.limit, valueSeenByLastUnit, tolerance);
+  }
+}
+
 // =============================================================================
 // Enforce-Cap helper
 // =============================================================================
@@ -82,7 +96,8 @@ export type EnforceCapResult =
  *
  * **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% /
+ * and both pass — that's a race (withCapEnforcement closes it with an atomic reservation;
+ * bare enforceCap stays a read). 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).
@@ -112,7 +127,6 @@ export async function enforceCap(
 
   const tolerance = CAP_TOLERANCES[options.profile];
   const softThreshold = options.limit * tolerance.soft;
-  const hardThreshold = options.limit * tolerance.hard;
 
   const rows = await ctx.db.selectMany(
     table,
@@ -125,9 +139,7 @@ export async function enforceCap(
   // The last of `amount` units sees this value before its own increment.
   const value = storedValue + amount - 1;
 
-  if (value >= hardThreshold) {
-    throw new CapExceededError(options.capName, options.limit, value, tolerance);
-  }
+  assertBelowHardCap(value, options);
 
   if (value >= softThreshold) {
     const lastSoftWarnedAt = row ? row["lastSoftWarnedAt"] : null;
@@ -299,6 +311,7 @@ export async function enforceCapAndMaybeNotify(
     readonly profile: CapToleranceProfileName;
     readonly notify: SoftHitNotifier;
     readonly amount?: number;
+    readonly markSoftWarnedOutsideTransaction?: boolean;
   },
 ): Promise<EnforceCapResult> {
   const result = await enforceCap(ctx, {
@@ -325,6 +338,7 @@ export async function enforceCapAndMaybeNotify(
     const marked = await markCapSoftWarned(ctx, {
       capName: options.capName,
       periodStartIso: options.periodStartIso,
+      ...(options.markSoftWarnedOutsideTransaction && { outsideTransaction: true }),
     });
     if (!marked.isSuccess) throw reraiseAsKumikoError(marked.error);
   }

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

@@ -1,21 +1,24 @@
-// withCapEnforcement / withRollingCapEnforcement — handler-wrapper die
-// pre-call enforceCap-And-Notify + post-call booking um den
-// gewrappten Handler legen.
+// withCapEnforcement / withRollingCapEnforcement: handler wrappers that put the
+// pre-call enforceCapAndMaybeNotify and a reservation around the wrapped handler.
 //
-// **Warum Wrapper statt manuelle Calls im Handler:**
-// Pattern-konsistenz. Wer einen cap-bedingten Handler schreibt,
-// darf nicht vergessen den counter zu incrementen oder den enforce-
-// pre-call zu machen — beides ist atomic-mit-dem-Handler-zusammen.
-// Wrapper macht das Pattern explizit + co-located.
+// **Why a wrapper instead of manual calls in the handler:** a cap-bound handler
+// must not forget the enforce pre-call, the reservation or the release on failure;
+// the wrapper keeps the pattern explicit and co-located.
+//
+// **Calendar reservation:** the wrapper only declares the cap; the dispatcher runs the
+// reservation (reserveBeforeTransaction) before the handler transaction opens, in its own short
+// committed write, and releases it after that transaction ended without committing (rollback,
+// failure result, failed COMMIT). No connection is held across the handler, so capped requests
+// cannot exhaust the pool, and the counter stream is not locked while the handler runs. If a
+// COMMIT fails with an unknown outcome the release can under-count; a wrapped handler must not
+// book the same counter itself. Reached through a nested ctx.write the cap is not reserved, so
+// the dispatcher rejects that call unless the top-level batch reserved the same handler.
 //
-// **Atomicity caveat:** calendar booking runs in-process via bookCapUsage
-// (see book-cap-usage.ts).
 // Rolling booking still dispatches the SystemAdmin-only increment-rolling
-// handler. In-process booking would work today only because the entity
-// executor appends without the event-ownership check (that check runs in
-// appendDomainEventCore alone); relying on that gap would break once the
-// executor path enforces ownership, so rolling callers need a SystemAdmin
-// identity until cap-counter declares an explicit foreign-booking opt-in.
+// handler and has no reservation: it would need a compensating event type,
+// a changed readRollingCapUsage and a version-guarded append behind the
+// SystemAdmin dispatch. Rolling callers need a SystemAdmin identity until
+// cap-counter declares an explicit foreign-booking opt-in.
 //
 // No automatic markSoftWarned here — that's inside enforceCapAndMaybeNotify
 // (enforce-cap.ts).
@@ -26,9 +29,10 @@ import type {
   WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
-import { bookCapUsage } from "./book-cap-usage.js";
+import { bookCapUsage, releaseCapUsage } from "./book-cap-usage.js";
 import { CapCounterHandlers } from "./constants.js";
 import {
+  assertBelowHardCap,
   type CapToleranceProfileName,
   enforceCapAndMaybeNotify,
   enforceRollingCapAndMaybeNotify,
@@ -68,53 +72,51 @@ export type CalendarCapResolver = (
 /**
  * Wrap a write-handler with calendar-period cap-enforcement.
  *
- * Flow:
+ * Flow (all before the handler transaction, in the dispatcher):
  *   1. resolve cap-spec via `capResolver(event, ctx)`
- *   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: 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
- * the same external contract.
+ *   2. `enforceCapAndMaybeNotify` — throws CapExceededError on hard-hit
+ *      (handler never runs), notifies on soft-hit-crossing
+ *   3. reserve `amount` (hard-cap check + increment in one short, immediately committed write)
+ *   4. the returned release gives the amount back if the transaction does not commit
  */
 export function withCapEnforcement(
   handler: WriteHandlerDef,
   capResolver: CalendarCapResolver,
 ): WriteHandlerDef {
   return {
-    name: handler.name,
-    schema: handler.schema,
-    access: handler.access,
-    handler: async (event, ctx) => {
+    ...handler,
+    reserveBeforeTransaction: async (event, ctx) => {
       const cap = await capResolver(event, ctx);
 
-      // Pre-enforce. Hard-hit throws CapExceededError (extends KumikoError,
-      // dispatcher auto-maps to HTTP 429 + cap_exceeded). Soft-hit-crossing
-      // notifies via the supplied notifier + flips lastSoftWarnedAt.
       await enforceCapAndMaybeNotify(ctx, {
         capName: cap.capName,
         periodStartIso: cap.periodStartIso,
         limit: cap.limit,
         profile: cap.profile,
         notify: cap.notify,
+        markSoftWarnedOutsideTransaction: true,
+        ...(cap.amount !== undefined && { amount: cap.amount }),
       });
 
-      const result = await handler.handler(event, ctx);
+      const amount = cap.amount ?? 1;
+      const reserved = await bookCapUsage(ctx, {
+        capName: cap.capName,
+        amount,
+        periodStartIso: cap.periodStartIso,
+        outsideTransaction: true,
+        guardCurrentValue: (currentValue) => assertBelowHardCap(currentValue + amount - 1, cap),
+      });
+      if (!reserved.isSuccess) throw reraiseAsKumikoError(reserved.error);
 
-      // Post-success increment. Skip on failure so a failed write
-      // doesn't burn cap-quota. amount default 1.
-      if (result.isSuccess) {
-        const booked = await bookCapUsage(ctx, {
+      return async () => {
+        const released = await releaseCapUsage(ctx, {
           capName: cap.capName,
-          amount: cap.amount ?? 1,
+          amount,
           periodStartIso: cap.periodStartIso,
+          outsideTransaction: true,
         });
-        if (!booked.isSuccess) throw reraiseAsKumikoError(booked.error);
-      }
-
-      return result;
+        if (!released.isSuccess) throw reraiseAsKumikoError(released.error);
+      };
     },
   };
 }

package/packages/bundled-features/src/personal-access-tokens/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.347.0",
+    "type": "improvement",
+    "title": "API-token screens hide behind the tier gate and can fall back to an upgrade screen via lockedFallbackScreen",
+    "detail": "Token screens follow the tier gate of personal-access-tokens\nThe list and mint screens carry a `visibleWhen` on the new `personal-access-tokens:query:availability` probe. For a tenant whose tier excludes the feature (`toggleable`), the dispatcher already rejected every token handler with `feature_disabled`; now the screens also show the unavailable notice instead of an empty list with a broken Create button. A new option `lockedFallbackScreen` names a screen (for example an upgrade notice) to show in its place. Without `toggleable` nothing changes: the feature stays always on."
+  },
   {
     "version": "0.336.0",
     "type": "fix",

package/packages/bundled-features/src/personal-access-tokens/constants.ts

@@ -32,6 +32,7 @@ export const PatHandlers = {
 export const PatQueries = {
   mine: "personal-access-tokens:query:mine",
   availableScopes: "personal-access-tokens:query:available-scopes",
+  availability: "personal-access-tokens:query:availability",
 } as const;
 
 // Only the first chars of a minted token are stored (alongside the hash) so the

package/packages/bundled-features/src/personal-access-tokens/feature.ts

@@ -11,6 +11,7 @@ import {
   PAT_FEATURE,
   type PatRateLimit,
 } from "./constants.js";
+import { availabilityQuery } from "./handlers/availability.query.js";
 import { buildAvailableScopesQuery } from "./handlers/available-scopes.query.js";
 import { type CreatePatOptions, createPatCreateHandler } from "./handlers/create.write.js";
 import { listPatQuery } from "./handlers/list.query.js";
@@ -65,6 +66,10 @@ export type PersonalAccessTokensOptions = {
    *  { default: false } for fail-closed gating (feature off until a tier grants
    *  it). Omit to keep PAT always-on (default). */
   readonly toggleable?: { readonly default: boolean };
+  /** Screen (same-feature id or `<feature>:screen:<id>`, must not be gated itself)
+   *  shown in place of the token screens when the tenant's tier excludes the
+   *  feature, e.g. an upgrade notice. Default: the standard "unavailable" notice. */
+  readonly lockedFallbackScreen?: string;
   // Opt-in MFA re-auth gate for minting a token — wired via
   // mfaVerifierFromFeature (auth-mfa/feature.ts) at app-composition time. No
   // hard dependency on the optional auth-mfa feature.
@@ -161,13 +166,16 @@ export function createPersonalAccessTokensFeature(
     };
     const queries = {
       mine: r.queryHandler(listPatQuery),
+      availability: r.queryHandler(availabilityQuery),
       availableScopes: r.queryHandler(buildAvailableScopesQuery(scopes)),
     };
 
     // Declarative screens — list-with-revoke + mint-with-reveal. The app
     // places `patListScreen` via r.nav in its logged-in settings area.
-    r.screen(patListScreen);
-    r.screen(createPatMintScreen(scopes));
+    const lockedFallback =
+      options.lockedFallbackScreen === undefined ? {} : { fallback: options.lockedFallbackScreen };
+    r.screen({ ...patListScreen, ...lockedFallback });
+    r.screen({ ...createPatMintScreen(scopes), ...lockedFallback });
     r.translations({ keys: { ...PAT_FEATURE_I18N, ...patScopeOptionTranslations(scopes) } });
 
     // rateLimit flows into feature.exports so run-prod-app builds the

package/packages/bundled-features/src/personal-access-tokens/handlers/availability.query.ts

@@ -0,0 +1,20 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+
+// Screen gate probe: the dispatcher's feature gate rejects every handler of a
+// toggleable feature the tenant's tier does not include, so this query only
+// answers for tenants that may use tokens — a rejection makes the screens'
+// visibleWhen fall back instead of rendering an unusable token list.
+export const availabilityQuery = defineQueryHandler({
+  name: "availability",
+  schema: z.object({}),
+  access: {
+    openToAll: {
+      reason:
+        "constant answer that only exists to be gated by the feature toggle; it carries no user or tenant data",
+    },
+  },
+  description:
+    "Reports that personal access tokens are available to the caller's tenant; fails with feature_disabled when the tenant's tier excludes them. The token screens use it to decide whether to render.",
+  handler: async () => ({ enabled: true }),
+});

package/packages/bundled-features/src/personal-access-tokens/screens.ts

@@ -9,9 +9,18 @@ import type { PatScopeConfig } from "./scopes.js";
 
 const PAT_STATUS_OPTION_KEY_PREFIX = "pat.list.status.";
 
+// Both screens render only for tenants whose tier includes the feature; the
+// availability query is rejected by the feature gate otherwise.
+const PAT_SCREEN_VISIBLE_WHEN = {
+  query: PatQueries.availability,
+  field: "enabled",
+  eq: true,
+} as const;
+
 export const patListScreen: ProjectionListScreenDefinition = {
   id: PAT_SCREEN_ID,
   type: "projectionList",
+  visibleWhen: PAT_SCREEN_VISIBLE_WHEN,
   query: PatQueries.mine,
   // The `mine` handler honours `limit` only (no offset/total), so a pager would
   // show page 1 forever: send one max-size request and render no pager.
@@ -86,6 +95,7 @@ export function createPatMintScreen(scopes: PatScopeConfig): SecretMintScreenDef
   return {
     id: PAT_MINT_SCREEN_ID,
     type: "secretMint",
+    visibleWhen: PAT_SCREEN_VISIBLE_WHEN,
     handler: PatHandlers.create,
     fields: {
       name: { type: "text", required: true, maxLength: 120 },

package/packages/bundled-features/src/step-dispatcher/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.347.0",
+    "type": "fix",
+    "title": "Webhook dispatch cancels the unread response body so a stalling receiver cannot hold the connection",
+    "detail": "Webhook dispatch releases the connection right after the status\nThe step-dispatcher only needs the response status, so it now cancels the unread response body instead of leaving the socket open until the 10 s request timeout fires."
+  },
   {
     "version": "0.346.0",
     "type": "fix",

package/packages/bundled-features/src/step-dispatcher/webhook-runner.ts

@@ -234,6 +234,8 @@ export async function performWebhookDispatch(
       signal: AbortSignal.timeout(deps.requestTimeoutMs ?? WEBHOOK_REQUEST_TIMEOUT_MS),
       body: spec.body !== undefined ? JSON.stringify(spec.body) : undefined,
     });
+    // Only the status is used; an unread body would pin the socket until the timeout fires.
+    await res.body?.cancel().catch(() => {});
     if (!res.ok) {
       return { ok: false, error: `HTTP ${res.status}: ${res.statusText}` };
     }

package/packages/bundled-features/src/tier-engine/feature.ts

@@ -297,6 +297,7 @@ export function createTierEngineFeature<
         ],
       },
       submitLabel: "tier-admin.submit",
+      successMessage: "tier-admin.success",
       cancelTarget: false,
       description: "tier-admin.screen.subtitle",
       access: { roles: ["SystemAdmin"] },

package/packages/bundled-features/src/tier-engine/i18n.ts

@@ -25,6 +25,7 @@ export const TIER_ENGINE_I18N: Readonly<Record<string, LocalizedString>> = {
   "tier-engine:entity:__action-form__:field:tenantId": { en: "Tenant" },
   "tier-engine:entity:__action-form__:field:tier": { en: "New tier" },
   "tier-admin.submit": { en: "Assign tier" },
+  "tier-admin.success": { en: "Tier assigned: {tenantId} → {tier}" },
 };
 
 export const defaultTranslations: TranslationsByLocale =

package/samples/recipes/workflow-engine/README.md

@@ -1,11 +1,12 @@
 # Workflow Engine
 
-Tier-3 `defineWorkflow` vocabulary: wait, branch, mail, webhook, retry.
+Tier-3 `defineWorkflow` vocabulary: wait, branch, mail, webhook.
 
 ## What it shows
 
 - Real runnable pipelines (no empty `build: () => []` stubs)
-- Workflow-run lifecycle across wait / waitForEvent / retry
+- Workflow-run lifecycle across wait / waitForEvent
+- `webhook.send` is delivered once by the step-dispatcher; a failed delivery ends as `step.dispatch-failed`. Wrapping it in `r.step.retry` would not repeat it, because the step only enqueues the request and never throws on a delivery error
 
 ## Source
 

package/samples/recipes/workflow-engine/src/feature.ts

@@ -1,7 +1,7 @@
 // workflow-engine Sample — M.4 Tier-3 step-vocabulary showcase.
 //
-// Demonstrates defineWorkflow with wait, branch, mail.send, webhook.send,
-// retry, and the workflow-run lifecycle. Each workflow below is a real,
+// Demonstrates defineWorkflow with wait, branch, mail.send, webhook.send
+// and the workflow-run lifecycle. Each workflow below is a real,
 // runnable pipeline — no empty `build: () => []` stubs. The
 // integration-tests in __tests__/ exercise the suspension/resume cycle
 // against the in-memory fetcher and (separately) the postgres event-store.
@@ -17,7 +17,7 @@
 //     full HandlerContext surface. `r.step.read.findOne` works (db is
 //     present), `r.step.callFeature` does NOT yet (no `write`/`writeAs`
 //     on apply-ctx). Pipelines should stick to compute / branch / wait /
-//     retry / mail.send / webhook.send for now.
+//     mail.send / webhook.send for now.
 //   - The fetcher reads every suspension row whose wakeAt has expired
 //     (no `workflow_run_pending` read-side projection yet). Concurrency
 //     is safe via the event-store version-conflict path; performance is
@@ -98,28 +98,24 @@ export const userOnboardingWorkflow: WorkflowDefinition<{ email: string; userId:
   });
 
 /**
- * Retry-with-backoff workflow: wraps a deferred webhook in retry(3,
- * exponential). The retry step suspends the run between attempts and
- * the resume-loop re-enters it after the backoff window.
+ * Webhook-delivery workflow: one deferred webhook per `data.processed` event.
+ * `webhook.send` only enqueues a dispatch request; the step-dispatcher
+ * delivers it once and a failed delivery ends as `step.dispatch-failed`. A
+ * `retry` around it would never fire, because the step itself cannot throw
+ * on a delivery error.
  */
-export const resilientWebhookWorkflow: WorkflowDefinition<
+export const webhookDeliveryWorkflow: WorkflowDefinition<
   { data: unknown; webhookUrl: string },
   void
 > = defineWorkflow({
-  name: "resilient-webhook",
+  name: "webhook-delivery",
   trigger: { kind: "event", eventType: "data.processed" },
 
   steps: stepsPipeline<{ data: unknown; webhookUrl: string }, void>(({ r }) => [
-    r.step.retry({
-      times: 3,
-      backoff: "exponential",
-      do: [
-        r.step.webhook.send({
-          url: (ctx: PipelineCtx) => (ctx.event.payload as { webhookUrl: string }).webhookUrl,
-          body: (ctx: PipelineCtx) => (ctx.event.payload as { data: unknown }).data,
-          mode: "deferred",
-        }),
-      ],
+    r.step.webhook.send({
+      url: (ctx: PipelineCtx) => (ctx.event.payload as { webhookUrl: string }).webhookUrl,
+      body: (ctx: PipelineCtx) => (ctx.event.payload as { data: unknown }).data,
+      mode: "deferred",
     }),
     r.step.return({ isSuccess: true, data: undefined }),
   ]),
@@ -155,7 +151,7 @@ export const workflowEngineFeature = defineFeature("workflowEngine", (r) => {
   // The runtime only touches trigger/name/idempotencyKey + executes
   // the closure with the real event payload — payload-agnostic.
   registerEventTrigger(r, userOnboardingWorkflow as unknown as WorkflowDefinition);
-  registerEventTrigger(r, resilientWebhookWorkflow as unknown as WorkflowDefinition);
+  registerEventTrigger(r, webhookDeliveryWorkflow as unknown as WorkflowDefinition);
   // dailyReportWorkflow is cron-triggered — skip MSP registration
 });