@cosmicdrift/kumiko-framework 0.372.0 → 0.373.0

package/agents/examples/rate-limiting.md

@@ -13,8 +13,29 @@ End-to-end rate limiting: L1 global-IP + L2 auth + L3 handler opt-in.
 ## What it shows
 
 - Handler `rateLimit: { per, limit, windowSeconds }`
+- Several buckets on one handler: `rateLimit: [{ per: "user", ... }, { per: "tenant+handler", ... }]`
 - How L1/L2 from `buildServer` stack with L3
 
+## Combined buckets
+
+Pass a list to enforce several budgets on one handler, for example a per-caller and a per-tenant cap:
+
+```ts illustration
+r.writeHandler({
+  // ...
+  rateLimit: [
+    { per: "user", limit: 2, windowSeconds: 3600 },
+    { per: "tenant+handler", limit: 3, windowSeconds: 3600 },
+  ],
+});
+```
+
+Each bucket applies on its own. The check is all-or-nothing: if any bucket is exhausted the call
+answers 429 `rate_limited` for that bucket (the one with the longest wait when several are
+exhausted) and no bucket is charged. Each `per` may appear once; an empty list fails at boot.
+An anonymous handler needs every bucket to be ip-keyed, and `{ disabled: true, reason }`
+stays a single declaration.
+
 ## Per-payload limits
 
 A public write handler that mails an address typed by the caller is also limited per
@@ -67,7 +88,8 @@ bun test
 // in each layer's test.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { createTestUser, TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
 import { createRateLimitShowcaseFeature } from "../feature";
 
@@ -130,6 +152,35 @@ describe("L3 — handler opt-in (per-user budget on expensive-search)", () => {
   });
 });
 
+describe("L3 — combined buckets (per-user and per-tenant budget on submit-report)", () => {
+  const submitReport = "rl-showcase:write:submit-report";
+
+  async function rejectedBucket(user: SessionUser): Promise<string | undefined> {
+    const res = await stack.http.write(submitReport, {}, user);
+    expect(res.status).toBe(429);
+    const body = (await res.json()) as { error: { details?: { bucket?: string } } };
+    return body.error.details?.bucket;
+  }
+
+  test("the user bucket rejects first; the tenant bucket only counts accepted requests", async () => {
+    await stack.http.writeOk(submitReport, {}, admin);
+    await stack.http.writeOk(submitReport, {}, admin);
+    expect(await rejectedBucket(admin)).toBe("user");
+
+    // The rejected third call did not touch the tenant bucket: one of its 3 tokens is left.
+    await stack.http.writeOk(submitReport, {}, TestUsers.user);
+    expect(await rejectedBucket(TestUsers.user)).toBe("tenant+handler");
+  });
+
+  test("a caller without Admin or User role is rejected with access_denied before any bucket is charged", async () => {
+    const outsider = createTestUser({ id: 9, tenantId: admin.tenantId, roles: ["Guest"] });
+    const res = await stack.http.write(submitReport, {}, outsider);
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("access_denied");
+  });
+});
+
 describe("L1 — global IP middleware (covers every /api/* request)", () => {
   test("21st request from same IP returns 429 with l1:ip bucket", async () => {
     // L1 sits ahead of auth + every /api/* route. Target an authless,
@@ -205,6 +256,19 @@ export function createRateLimitShowcaseFeature(): FeatureDefinition {
       access: { roles: ["Admin", "User"] },
       rateLimit: { per: "user", limit: 3, windowSeconds: 60 },
     });
+
+    // Combined budget: each caller gets 2 submits per hour and the tenant 3 per hour in
+    // total. Both buckets are checked together; a request one bucket rejects charges neither.
+    r.writeHandler({
+      name: "submit-report",
+      schema: z.object({}),
+      handler: async () => ({ isSuccess: true as const, data: {} }),
+      access: { roles: ["Admin", "User"] },
+      rateLimit: [
+        { per: "user", limit: 2, windowSeconds: 3600 },
+        { per: "tenant+handler", limit: 3, windowSeconds: 3600 },
+      ],
+    });
   });
 }
 ```

package/dist/engine/boot-validator/entity-handler.d.ts

@@ -10,6 +10,7 @@ export declare function validateAdditionalRateLimits(featureName: string, handle
 export declare function validatePerCommandTransaction(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validateTenantlessAnonymous(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validateRateLimitDisabledReason(featureName: string, kind: "write" | "query" | "stream", handlerName: string, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;
+export declare function validateRateLimitBucketList(featureName: string, kind: "write" | "query" | "stream", handlerName: string, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;
 export declare function validateNoAllRoleInHandlerAccess(featureName: string, kind: "write" | "query" | "stream", handlerName: string, access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>): void;
 export declare function validateAnonymousRateLimit(featureName: string, kind: "write" | "query" | "stream", handlerName: string, access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;
 export declare function validateMultiStreamProjections(feature: FeatureDefinition): void;

package/dist/engine/boot-validator/entity-handler.js

@@ -1,5 +1,5 @@
 import { SELECT_OPTION_TONES } from "@cosmicdrift/kumiko-types/fields";
-import { isRateLimitDisabled } from "@cosmicdrift/kumiko-types/handlers";
+import { declaredRateLimitOptions, isRateLimitDisabled } from "@cosmicdrift/kumiko-types/handlers";
 import { ZodObject } from "zod";
 import { VARIANT_NAME_PATTERN } from "../../derivatives/variant-key.js";
 import { access as accessPresets } from "../config-helpers.js";
@@ -133,6 +133,7 @@ export function validateHandlerAccess(feature) {
                     `Set { roles: [...] } for role-based access, or { openToAll: { reason: "..." } } for any authenticated user.`);
             }
             validateNoAllRoleInHandlerAccess(feature.name, kind, name, handler.access);
+            validateRateLimitBucketList(feature.name, kind, name, handler.rateLimit);
             validateAnonymousRateLimit(feature.name, kind, name, handler.access, handler.rateLimit);
             validateRateLimitDisabledReason(feature.name, kind, name, handler.rateLimit);
         }
@@ -158,8 +159,17 @@ export function validateAdditionalRateLimits(featureName, handlerName, handler)
     }
     validateAnonymousHasIpBucket(where, handler);
     const shape = handler.schema instanceof ZodObject ? handler.schema.shape : undefined;
+    const seenFields = new Set();
     for (const entry of additionalRateLimits) {
         validatePayloadBucket(where, shape, entry);
+        const field = entry.per.payloadField;
+        // Two entries on one field hash the same value into the same Redis key, so enforceAll
+        // would deduct only one of the costs.
+        if (seenFields.has(field)) {
+            throw new Error(`${where} with payloadField "${field}" more than once — both entries would share one ` +
+                `Redis bucket per value. Keep one entry per payloadField.`);
+        }
+        seenFields.add(field);
     }
 }
 function validateAnonymousHasIpBucket(where, handler) {
@@ -168,9 +178,7 @@ function validateAnonymousHasIpBucket(where, handler) {
     // skip: only anonymous callers need an ip bucket
     if (!allowsAnonymous)
         return;
-    const hasIpBucket = rateLimit !== undefined &&
-        !isRateLimitDisabled(rateLimit) &&
-        IP_BUCKETED_RATE_LIMIT_PER.has(rateLimit.per);
+    const hasIpBucket = declaredRateLimitOptions(rateLimit).some((option) => IP_BUCKETED_RATE_LIMIT_PER.has(option.per));
     if (!hasIpBucket) {
         throw new Error(`${where} and allows anonymous callers, but has no ip-keyed rateLimit ` +
             `(per: "ip" or "ip+handler", not disabled). Payload buckets only complement the IP bucket. Set rateLimit: { per: "ip", ... } on the handler.`);
@@ -217,13 +225,16 @@ export function validateTenantlessAnonymous(featureName, handlerName, handler) {
         throw new Error(`${where} but its access is not exactly { roles: ["anonymous"] } — a tenantless request ` +
             `carries no principal beyond the anonymous visitor. Set access to { roles: ["anonymous"] } or remove tenantlessAnonymous.`);
     }
-    if (!handler.rateLimit || isRateLimitDisabled(handler.rateLimit)) {
+    const options = declaredRateLimitOptions(handler.rateLimit);
+    if (options.length === 0) {
         throw new Error(`${where} without a rateLimit — a handler reachable on hosts that resolve no tenant ` +
             `needs a real upper bound (rateLimit: { per: "ip", ... }); { disabled: true } does not count.`);
     }
-    if (!IP_SCOPED_RATE_LIMIT_PER.includes(handler.rateLimit.per)) {
-        throw new Error(`${where} with rateLimit.per "${handler.rateLimit.per}" — every anonymous visitor shares the same ` +
-            `tenant/user bucket, so one caller could exhaust it for all. Use ${IP_SCOPED_RATE_LIMIT_PER.map((per) => `"${per}"`).join(" or ")}.`);
+    for (const { per } of options) {
+        if (IP_SCOPED_RATE_LIMIT_PER.includes(per))
+            continue;
+        throw new Error(`${where} with rateLimit.per "${per}" — every anonymous visitor shares the same ` +
+            `tenant/user bucket, so one caller could exhaust it for all. Use ${IP_SCOPED_RATE_LIMIT_PER.map((allowed) => `"${allowed}"`).join(" or ")}.`);
     }
 }
 export function validateRateLimitDisabledReason(featureName, kind, handlerName, rateLimit) {
@@ -236,6 +247,23 @@ export function validateRateLimitDisabledReason(featureName, kind, handlerName,
             `be rate-limited.`);
     }
 }
+export function validateRateLimitBucketList(featureName, kind, handlerName, rateLimit) {
+    // skip: a single option or a disabled declaration has no bucket list to check
+    if (!Array.isArray(rateLimit))
+        return;
+    const where = `${kind} handler "${featureName}:${kind}:${handlerName}"`;
+    if (rateLimit.length === 0) {
+        throw new Error(`${where} declares rateLimit as an empty array — declare at least one bucket or drop the option.`);
+    }
+    const seen = new Set();
+    for (const { per } of rateLimit) {
+        if (seen.has(per)) {
+            throw new Error(`${where} declares rateLimit with per "${per}" more than once — both entries would share one ` +
+                `Redis bucket with conflicting limits. Keep one entry per "per".`);
+        }
+        seen.add(per);
+    }
+}
 // No session ever carries the role "all" — `roles: ["all"]` is unreachable dead config, not a wildcard.
 export function validateNoAllRoleInHandlerAccess(featureName, kind, handlerName, access) {
     // skip: openToAll has no roles list to check
@@ -260,19 +288,22 @@ export function validateAnonymousRateLimit(featureName, kind, handlerName, acces
     // skip: disabled declarations carry no `.per` to bucket on
     if (isRateLimitDisabled(rateLimit))
         return;
-    if (!rateLimit) {
+    const options = declaredRateLimitOptions(rateLimit);
+    if (options.length === 0) {
         throw new Error(`${kind} handler "${featureName}:${kind}:${handlerName}" allows anonymous callers but declares no ` +
             `rateLimit — an anonymous, internet-facing endpoint needs an upper bound. Set rateLimit: ` +
             `{ per: "ip", limit: ..., windowSeconds: ... }, or the documented exception ` +
             `rateLimit: { disabled: true, reason: "..." }.`);
     }
-    // skip: rate-limit is already keyed on something safe (ip / tenant)
-    if (!USER_BUCKETED_RATE_LIMIT_PER.has(rateLimit.per))
-        return;
-    throw new Error(`${kind} handler "${featureName}:${kind}:${handlerName}" allows anonymous callers but uses ` +
-        `rateLimit.per="${rateLimit.per}" — every anonymous request shares user.id="anonymous", ` +
-        `so this bucket would be a single global tap any caller could drain. ` +
-        `Use rateLimit.per="ip" or "ip+handler" for anonymous endpoints.`);
+    for (const { per } of options) {
+        // skip: this bucket is keyed on something safe (ip / tenant)
+        if (!USER_BUCKETED_RATE_LIMIT_PER.has(per))
+            continue;
+        throw new Error(`${kind} handler "${featureName}:${kind}:${handlerName}" allows anonymous callers but uses ` +
+            `rateLimit.per="${per}" — every anonymous request shares user.id="anonymous", ` +
+            `so this bucket would be a single global tap any caller could drain. ` +
+            `Use rateLimit.per="ip" or "ip+handler" for anonymous endpoints.`);
+    }
 }
 // --- MultiStreamProjection delivery-invariant ---
 //

package/dist/engine/feature-ast/extractors/handlers.js

@@ -178,7 +178,7 @@ function readHandlerHeaderFields(obj, methodName, sourceFile) {
     const accessResult = readHeaderField(readObjectPropertyInitializer(obj, "access"), readOptionalAccessRule, methodName, sourceFile, "access must be a recognized AccessRule ({ roles: [...] } or { openToAll: { reason } }), or a reference to one");
     if (accessResult.kind === "error")
         return accessResult;
-    const rateLimitResult = readHeaderField(readObjectPropertyInitializer(obj, "rateLimit"), readOptionalRateLimit, methodName, sourceFile, "rateLimit must be { per, limit, windowSeconds } or { disabled: true, reason }, or a reference to one");
+    const rateLimitResult = readHeaderField(readObjectPropertyInitializer(obj, "rateLimit"), readOptionalRateLimit, methodName, sourceFile, "rateLimit must be { per, limit, windowSeconds }, a non-empty list of those, or { disabled: true, reason }, or a reference to one");
     if (rateLimitResult.kind === "error")
         return rateLimitResult;
     const additionalRateLimitsResult = readHeaderField(readObjectPropertyInitializer(obj, "additionalRateLimits"), readOptionalAdditionalRateLimits, methodName, sourceFile, "additionalRateLimits must be an array of { per: { payloadField }, limit, windowSeconds }, or a reference to one");

package/dist/engine/feature-ast/extractors/hooks.js

@@ -1,4 +1,4 @@
-import { isEscapeHatchGrant } from "@cosmicdrift/kumiko-types/handlers";
+import { isEscapeHatchGrant, isRateLimitOption } from "@cosmicdrift/kumiko-types/handlers";
 import { SyntaxKind } from "ts-morph";
 import { sourceLocationFromNode } from "../source-location.js";
 import { containsRawRefSentinel, fail, findFunctionLiteral, isPlainObject, ok, readDataLiteralNode, readNameLiteral, readNameOrRef, readNameOrRefOrList, readObjectPropertyInitializer, } from "./shared.js";
@@ -52,6 +52,12 @@ export function readOptionalAccessRule(value) {
     return undefined;
 }
 export function readOptionalRateLimit(value) {
+    if (Array.isArray(value)) {
+        if (!value.every(isRateLimitOption))
+            return undefined;
+        const [first, ...rest] = value;
+        return first === undefined ? undefined : [first, ...rest];
+    }
     if (!isPlainObject(value))
         return undefined;
     if (value["disabled"] === true) {
@@ -63,13 +69,7 @@ export function readOptionalRateLimit(value) {
             return undefined;
         return { disabled: true, reason: value["reason"] };
     }
-    if (typeof value["per"] !== "string")
-        return undefined;
-    if (typeof value["limit"] !== "number")
-        return undefined;
-    if (typeof value["windowSeconds"] !== "number")
-        return undefined;
-    return value;
+    return isRateLimitOption(value) ? value : undefined;
 }
 function isPayloadRateLimitOption(value) {
     if (!isPlainObject(value))

package/dist/engine/feature-ast/pattern-change-schema.d.ts

@@ -189,7 +189,31 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
             limit: z.ZodNumber;
             windowSeconds: z.ZodNumber;
             cost: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>, z.ZodObject<{
+        }, z.core.$strict>, z.ZodTuple<[z.ZodObject<{
+            per: z.ZodEnum<{
+                ip: "ip";
+                "ip+handler": "ip+handler";
+                tenant: "tenant";
+                "tenant+handler": "tenant+handler";
+                user: "user";
+                "user+handler": "user+handler";
+            }>;
+            limit: z.ZodNumber;
+            windowSeconds: z.ZodNumber;
+            cost: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>], z.ZodObject<{
+            per: z.ZodEnum<{
+                ip: "ip";
+                "ip+handler": "ip+handler";
+                tenant: "tenant";
+                "tenant+handler": "tenant+handler";
+                user: "user";
+                "user+handler": "user+handler";
+            }>;
+            limit: z.ZodNumber;
+            windowSeconds: z.ZodNumber;
+            cost: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>, z.ZodObject<{
             disabled: z.ZodLiteral<true>;
             reason: z.ZodString;
         }, z.core.$strict>]>, z.ZodObject<{
@@ -257,7 +281,31 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
             limit: z.ZodNumber;
             windowSeconds: z.ZodNumber;
             cost: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>, z.ZodObject<{
+        }, z.core.$strict>, z.ZodTuple<[z.ZodObject<{
+            per: z.ZodEnum<{
+                ip: "ip";
+                "ip+handler": "ip+handler";
+                tenant: "tenant";
+                "tenant+handler": "tenant+handler";
+                user: "user";
+                "user+handler": "user+handler";
+            }>;
+            limit: z.ZodNumber;
+            windowSeconds: z.ZodNumber;
+            cost: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>], z.ZodObject<{
+            per: z.ZodEnum<{
+                ip: "ip";
+                "ip+handler": "ip+handler";
+                tenant: "tenant";
+                "tenant+handler": "tenant+handler";
+                user: "user";
+                "user+handler": "user+handler";
+            }>;
+            limit: z.ZodNumber;
+            windowSeconds: z.ZodNumber;
+            cost: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>, z.ZodObject<{
             disabled: z.ZodLiteral<true>;
             reason: z.ZodString;
         }, z.core.$strict>]>, z.ZodObject<{
@@ -303,7 +351,31 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
             limit: z.ZodNumber;
             windowSeconds: z.ZodNumber;
             cost: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>, z.ZodObject<{
+        }, z.core.$strict>, z.ZodTuple<[z.ZodObject<{
+            per: z.ZodEnum<{
+                ip: "ip";
+                "ip+handler": "ip+handler";
+                tenant: "tenant";
+                "tenant+handler": "tenant+handler";
+                user: "user";
+                "user+handler": "user+handler";
+            }>;
+            limit: z.ZodNumber;
+            windowSeconds: z.ZodNumber;
+            cost: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>], z.ZodObject<{
+            per: z.ZodEnum<{
+                ip: "ip";
+                "ip+handler": "ip+handler";
+                tenant: "tenant";
+                "tenant+handler": "tenant+handler";
+                user: "user";
+                "user+handler": "user+handler";
+            }>;
+            limit: z.ZodNumber;
+            windowSeconds: z.ZodNumber;
+            cost: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>, z.ZodObject<{
             disabled: z.ZodLiteral<true>;
             reason: z.ZodString;
         }, z.core.$strict>]>, z.ZodObject<{
@@ -712,7 +784,31 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         limit: z.ZodNumber;
         windowSeconds: z.ZodNumber;
         cost: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>, z.ZodObject<{
+    }, z.core.$strict>, z.ZodTuple<[z.ZodObject<{
+        per: z.ZodEnum<{
+            ip: "ip";
+            "ip+handler": "ip+handler";
+            tenant: "tenant";
+            "tenant+handler": "tenant+handler";
+            user: "user";
+            "user+handler": "user+handler";
+        }>;
+        limit: z.ZodNumber;
+        windowSeconds: z.ZodNumber;
+        cost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>], z.ZodObject<{
+        per: z.ZodEnum<{
+            ip: "ip";
+            "ip+handler": "ip+handler";
+            tenant: "tenant";
+            "tenant+handler": "tenant+handler";
+            user: "user";
+            "user+handler": "user+handler";
+        }>;
+        limit: z.ZodNumber;
+        windowSeconds: z.ZodNumber;
+        cost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>, z.ZodObject<{
         disabled: z.ZodLiteral<true>;
         reason: z.ZodString;
     }, z.core.$strict>]>, z.ZodObject<{
@@ -779,7 +875,31 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         limit: z.ZodNumber;
         windowSeconds: z.ZodNumber;
         cost: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>, z.ZodObject<{
+    }, z.core.$strict>, z.ZodTuple<[z.ZodObject<{
+        per: z.ZodEnum<{
+            ip: "ip";
+            "ip+handler": "ip+handler";
+            tenant: "tenant";
+            "tenant+handler": "tenant+handler";
+            user: "user";
+            "user+handler": "user+handler";
+        }>;
+        limit: z.ZodNumber;
+        windowSeconds: z.ZodNumber;
+        cost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>], z.ZodObject<{
+        per: z.ZodEnum<{
+            ip: "ip";
+            "ip+handler": "ip+handler";
+            tenant: "tenant";
+            "tenant+handler": "tenant+handler";
+            user: "user";
+            "user+handler": "user+handler";
+        }>;
+        limit: z.ZodNumber;
+        windowSeconds: z.ZodNumber;
+        cost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>, z.ZodObject<{
         disabled: z.ZodLiteral<true>;
         reason: z.ZodString;
     }, z.core.$strict>]>, z.ZodObject<{
@@ -824,7 +944,31 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         limit: z.ZodNumber;
         windowSeconds: z.ZodNumber;
         cost: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>, z.ZodObject<{
+    }, z.core.$strict>, z.ZodTuple<[z.ZodObject<{
+        per: z.ZodEnum<{
+            ip: "ip";
+            "ip+handler": "ip+handler";
+            tenant: "tenant";
+            "tenant+handler": "tenant+handler";
+            user: "user";
+            "user+handler": "user+handler";
+        }>;
+        limit: z.ZodNumber;
+        windowSeconds: z.ZodNumber;
+        cost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>], z.ZodObject<{
+        per: z.ZodEnum<{
+            ip: "ip";
+            "ip+handler": "ip+handler";
+            tenant: "tenant";
+            "tenant+handler": "tenant+handler";
+            user: "user";
+            "user+handler": "user+handler";
+        }>;
+        limit: z.ZodNumber;
+        windowSeconds: z.ZodNumber;
+        cost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>, z.ZodObject<{
         disabled: z.ZodLiteral<true>;
         reason: z.ZodString;
     }, z.core.$strict>]>, z.ZodObject<{

package/dist/engine/feature-ast/pattern-change-schema.js

@@ -157,6 +157,7 @@ const rateLimitOptionSchema = z
     cost: z.number().optional(),
 })
     .strict();
+const rateLimitOptionListSchema = z.tuple([rateLimitOptionSchema], rateLimitOptionSchema);
 const additionalRateLimitsSchema = z.array(z
     .object({
     per: z.object({ payloadField: z.string() }).strict(),
@@ -247,7 +248,7 @@ const WRITE_HANDLER_PATTERN_HEADER_SHAPE = {
     ...WRITE_HANDLER_HEADER_SHAPE,
     access: orRawRef(accessRuleSchema),
     agent: orRawRef(agentHandlerHintsSchema),
-    rateLimit: orRawRef(z.union([rateLimitOptionSchema, rateLimitDisabledSchema])),
+    rateLimit: orRawRef(z.union([rateLimitOptionSchema, rateLimitOptionListSchema, rateLimitDisabledSchema])),
     additionalRateLimits: orRawRef(additionalRateLimitsSchema),
     escapeHatch: orRawRef(escapeHatchSchema),
 };
@@ -255,13 +256,13 @@ const QUERY_HANDLER_PATTERN_HEADER_SHAPE = {
     ...QUERY_HANDLER_HEADER_SHAPE,
     access: orRawRef(accessRuleSchema),
     agent: orRawRef(agentHandlerHintsSchema),
-    rateLimit: orRawRef(z.union([rateLimitOptionSchema, rateLimitDisabledSchema])),
+    rateLimit: orRawRef(z.union([rateLimitOptionSchema, rateLimitOptionListSchema, rateLimitDisabledSchema])),
     escapeHatch: orRawRef(escapeHatchSchema),
 };
 const STREAM_HANDLER_PATTERN_HEADER_SHAPE = {
     ...STREAM_HANDLER_HEADER_SHAPE,
     access: orRawRef(accessRuleSchema),
-    rateLimit: orRawRef(z.union([rateLimitOptionSchema, rateLimitDisabledSchema])),
+    rateLimit: orRawRef(z.union([rateLimitOptionSchema, rateLimitOptionListSchema, rateLimitDisabledSchema])),
     escapeHatch: orRawRef(escapeHatchSchema),
 };
 function requireHandlerBody(val, ctx, headerKeys) {

package/dist/engine/types/index.d.ts

@@ -7,8 +7,8 @@ export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsM
 export type { BootCheckContext, BootCheckFn, BootOptionName, EntityObjectDefinition, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, HookDefinition, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StackBootRequirement, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
 export type { FieldIconKey } from "@cosmicdrift/kumiko-types/field-icon";
 export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityEventMigration, EntityIndexDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
-export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadBucketNormalization, PayloadRateLimitOption, PreparedWriteEvent, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TenantWriteTarget, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
-export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
+export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadBucketNormalization, PayloadRateLimitOption, PreparedWriteEvent, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitOptions, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TenantWriteTarget, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
+export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, declaredRateLimitOptions, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isRateLimitOption, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export type { DeleteContext, EntityHookMap, HookMap, HookOwner, HookPhase, LifecycleHookFn, LifecycleResult, OwnedFn, PhasedHook, PostDeleteBatchHookFn, PostDeleteHookFn, PostQueryHookFn, PostSaveBatchHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SaveContext, SearchPayloadContributorFn, ValidationError, ValidationHookFn, } from "@cosmicdrift/kumiko-types/hooks";
 export type { HttpRouteDefinition, HttpRouteHandler, HttpRouteHandlerDeps, HttpRouteMethod, } from "@cosmicdrift/kumiko-types/http-route";
 export type { EntityId, TenantId } from "@cosmicdrift/kumiko-types/identifiers";

package/dist/engine/types/index.js

@@ -1,7 +1,7 @@
 // Barrel: re-exports all types from @cosmicdrift/kumiko-types, plus the
 // runtime helpers below that stay framework-side.
 export { isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-types/agent-exposure";
-export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
+export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, declaredRateLimitOptions, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isRateLimitOption, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-types/identifiers";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, isFileField } from "../field-helpers.js";

package/dist/files/bind-pending-file-refs.d.ts

@@ -1,6 +1,6 @@
 import type { TenantDb } from "../db/tenant-db.ts";
 import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.ts";
-import type { FileRefRows } from "./load-save-file-refs.ts";
+import { type FileRefRows } from "./load-save-file-refs.ts";
 export declare function fileRefIdsOf(value: unknown): readonly string[];
 export declare function bindPendingFileRefs(args: {
     readonly registry: Registry;
@@ -9,3 +9,33 @@ export declare function bindPendingFileRefs(args: {
     readonly db: TenantDb;
     readonly fileRefRows: FileRefRows;
 }): Promise<void>;
+export type PendingFileRef = {
+    readonly id: string;
+    readonly storageKey: string;
+    readonly mimeType: string;
+    readonly size: number;
+    readonly version: number;
+};
+type PendingFileRefLookup = {
+    readonly fileRefId: string;
+    readonly entityName: string;
+    readonly fieldName: string;
+    readonly user: SessionUser;
+    readonly db: TenantDb;
+};
+export declare function loadPendingFileRef(lookup: PendingFileRefLookup): Promise<PendingFileRef | undefined>;
+export type BindPendingFileRefOutcome = "bound" | "not-pending" | "version-conflict";
+/**
+ * Binds one of the caller's own pending uploads to a record from a custom handler, with the
+ * same ownership predicate as the save pipeline. Anonymous callers never own an upload.
+ *
+ * The helper checks the upload, not the target: the caller must already be authorized to write
+ * `entityId` itself (for example a record the handler just wrote); `canWriteRecord` is not checked.
+ *
+ * A parallel bind of the same fileRef loses with "version-conflict" (or "not-pending" once the
+ * winner has committed); anything else throws.
+ */
+export declare function bindPendingFileRef(args: PendingFileRefLookup & {
+    readonly entityId: string;
+}): Promise<BindPendingFileRefOutcome>;
+export {};

package/dist/files/bind-pending-file-refs.js

@@ -1,7 +1,9 @@
+import { isAnonymousSessionUser } from "../engine/system-user.js";
 import { isFileField, isUuid, } from "../engine/types/index.js";
 import { reraiseAsKumikoError } from "../errors/index.js";
 import { getFileRefExecutor } from "./create-file-ref.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
+import { loadFileRefRows } from "./load-save-file-refs.js";
 export function fileRefIdsOf(value) {
     if (typeof value === "string")
         return isUuid(value) ? [value] : [];
@@ -15,6 +17,16 @@ function isPendingUploadFor(row, entityName, fieldName, user) {
         row["fieldName"] === fieldName &&
         row["insertedById"] === user.id);
 }
+function streamVersionOf(row) {
+    return typeof row["version"] === "number" ? row["version"] : undefined;
+}
+async function bindPendingRow(args) {
+    const { row, fileRefId, entityName, fieldName, entityId, user, db } = args;
+    if (!isPendingUploadFor(row, entityName, fieldName, user))
+        return { kind: "not-pending" };
+    const bound = await getFileRefExecutor().update({ id: fileRefId, version: streamVersionOf(row), changes: { entityId } }, user, db);
+    return bound.isSuccess ? { kind: "bound" } : { kind: "failed", error: bound.error };
+}
 // A form (or a server handler via createFileRefFromBytes) uploads before the
 // record references the file, so its fileRefs carry entityType + fieldName but
 // no entityId. Binding them in the save's own transaction makes record-bound
@@ -35,7 +47,6 @@ export async function bindPendingFileRefs(args) {
     // skip: without the files feature the file_refs table is not part of the schema
     if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
         return;
-    const executor = getFileRefExecutor();
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
         if (!isFileField(fieldDef))
             continue;
@@ -43,12 +54,75 @@ export async function bindPendingFileRefs(args) {
         // ones bound earlier; only the ids this save names can be pending uploads.
         for (const fileRefId of fileRefIdsOf(result.changes[fieldName])) {
             const row = fileRefRows.get(fileRefId);
-            if (row === undefined || !isPendingUploadFor(row, entityName, fieldName, user))
+            if (row === undefined)
                 continue;
-            const version = typeof row["version"] === "number" ? row["version"] : undefined;
-            const bound = await executor.update({ id: fileRefId, version, changes: { entityId: String(result.id) } }, user, db);
-            if (!bound.isSuccess)
-                throw reraiseAsKumikoError(bound.error);
+            const outcome = await bindPendingRow({
+                row,
+                fileRefId,
+                entityName,
+                fieldName,
+                entityId: String(result.id),
+                user,
+                db,
+            });
+            if (outcome.kind === "failed")
+                throw reraiseAsKumikoError(outcome.error);
         }
     }
 }
+async function loadPendingRow(lookup) {
+    const { fileRefId, entityName, fieldName, user, db } = lookup;
+    // Every anonymous visitor shares one user id, so insertedById cannot tell their uploads apart.
+    if (isAnonymousSessionUser(user))
+        return undefined;
+    if (!isUuid(fileRefId))
+        return undefined;
+    const row = (await loadFileRefRows(db, [fileRefId], user.tenantId)).get(fileRefId);
+    return row !== undefined && isPendingUploadFor(row, entityName, fieldName, user)
+        ? row
+        : undefined;
+}
+// fileName is left out on purpose: it is personal data and may be encrypted; read it through
+// the fileRef executor's detail when it is needed.
+export async function loadPendingFileRef(lookup) {
+    const row = await loadPendingRow(lookup);
+    if (row === undefined)
+        return undefined;
+    const { storageKey, mimeType, size } = row;
+    const version = streamVersionOf(row);
+    if (typeof storageKey !== "string" ||
+        typeof mimeType !== "string" ||
+        typeof size !== "number" ||
+        version === undefined) {
+        return undefined;
+    }
+    return { id: lookup.fileRefId, storageKey, mimeType, size, version };
+}
+const CONCURRENT_BIND_ERROR_CODES = ["version_conflict", "unique_violation"];
+/**
+ * Binds one of the caller's own pending uploads to a record from a custom handler, with the
+ * same ownership predicate as the save pipeline. Anonymous callers never own an upload.
+ *
+ * The helper checks the upload, not the target: the caller must already be authorized to write
+ * `entityId` itself (for example a record the handler just wrote); `canWriteRecord` is not checked.
+ *
+ * A parallel bind of the same fileRef loses with "version-conflict" (or "not-pending" once the
+ * winner has committed); anything else throws.
+ */
+export async function bindPendingFileRef(args) {
+    const row = await loadPendingRow(args);
+    // Without a stream version the update would run unversioned and could overwrite a concurrent bind.
+    if (row === undefined || streamVersionOf(row) === undefined)
+        return "not-pending";
+    const outcome = await bindPendingRow({ ...args, row });
+    switch (outcome.kind) {
+        case "bound":
+            return "bound";
+        case "not-pending":
+            return "not-pending";
+        case "failed":
+            if (CONCURRENT_BIND_ERROR_CODES.includes(outcome.error.code))
+                return "version-conflict";
+            throw reraiseAsKumikoError(outcome.error);
+    }
+}

package/dist/files/index.d.ts

@@ -1,3 +1,5 @@
+export type { BindPendingFileRefOutcome, PendingFileRef } from "./bind-pending-file-refs.ts";
+export { bindPendingFileRef, loadPendingFileRef } from "./bind-pending-file-refs.ts";
 export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, UploadedFileBytes, UploadFileBytesContext, } from "./create-file-ref-from-bytes.ts";
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.ts";
 export { createFilesFeature, FILES_FEATURE } from "./feature.ts";

package/dist/files/index.js

@@ -1,3 +1,4 @@
+export { bindPendingFileRef, loadPendingFileRef } from "./bind-pending-file-refs.js";
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.js";
 export { createFilesFeature, FILES_FEATURE } from "./feature.js";
 // `createFileHandle` is an implementation detail — construct handles via

package/dist/files/load-save-file-refs.js

@@ -33,12 +33,14 @@ export async function loadFileRefRows(db, ids, tenantId) {
     // skip: nothing referenced, nothing to load
     if (ids.length === 0)
         return new Map();
+    // Versions before rows: a bind committing in between leaves a stale row paired with an older
+    // version, so the binding update conflicts instead of overwriting the winner's entityId.
+    const streamVersions = await getStreamVersions(tenantDbRunner(db), [...ids], db.tenantId);
     const rows = await selectMany(db, fileRefsTable, {
         id: { in: [...ids] },
         tenantId,
         isDeleted: false,
     });
-    const streamVersions = await getStreamVersions(tenantDbRunner(db), rows.map((row) => String(row["id"])), db.tenantId);
     return new Map(rows.map((row) => {
         const id = String(row["id"]);
         const streamVersion = streamVersions.get(id);

package/dist/pipeline/dispatch-shared.js

@@ -5,7 +5,7 @@ import { createTenantDb, createUncheckedSystemDb, hasTenantColumn, runInOwnTrans
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
 import { mayOverrideTenant } from "../engine/cross-tenant.js";
 import { createSystemUser } from "../engine/system-user.js";
-import { isRateLimitDisabled, resolveAgentExposure } from "../engine/types/index.js";
+import { declaredRateLimitOptions, isRateLimitDisabled, resolveAgentExposure, } from "../engine/types/index.js";
 import { AccessDeniedError, FeatureDisabledError, FrameworkReasons, InternalError, memberResolutionReadOnlyDenied, RateLimitError, RateLimitUnavailableError, VersionConflictError, writeFailure, } from "../errors/index.js";
 import { archiveStream as archiveStreamHelper, isStreamArchived, restoreStream as restoreStreamHelper, } from "../event-store/archive.js";
 import { IdempotentAppendConflictError as EventStoreIdempotentAppendConflictError, VersionConflictError as EventStoreVersionConflictError, } from "../event-store/errors.js";
@@ -1107,16 +1107,28 @@ const DEFAULT_SYSTEM_SCOPE_RATE_LIMIT = {
     limit: 600,
     windowSeconds: 60,
 };
-function resolveEffectiveRateLimit(rateLimit, isSystemScope, user, resolver) {
-    if (rateLimit)
-        return rateLimit;
+function resolveEffectiveRateLimits(rateLimit, isSystemScope, user, resolver) {
+    const declared = declaredRateLimitOptions(rateLimit);
+    if (declared.length > 0)
+        return declared;
     if (!isSystemScope)
-        return undefined;
+        return [];
     if (!resolver)
-        return undefined;
+        return [];
     if (isSystemIdentity(user))
-        return undefined;
-    return DEFAULT_SYSTEM_SCOPE_RATE_LIMIT;
+        return [];
+    return [DEFAULT_SYSTEM_SCOPE_RATE_LIMIT];
+}
+// A single bucket keeps the plain enforce path; several go through one atomic
+// all-or-nothing call so a rejection by one bucket never charges the others.
+async function enforceBuckets(resolver, requests) {
+    const [only, ...rest] = requests;
+    // skip: no bucket to charge
+    if (!only)
+        return;
+    await (rest.length === 0
+        ? resolver.enforce(only.bucket, only.config)
+        : resolver.enforceAll(requests));
 }
 // L3 rate limit gate. Called by both query and write paths before
 // access-check. Reasoning:
@@ -1135,42 +1147,48 @@ export async function enforceRateLimit(ctx, rateLimit, handlerName, user, isSyst
     // skip: handler explicitly opts out via rateLimit: { disabled: true }
     if (isRateLimitDisabled(rateLimit))
         return;
-    const effective = resolveEffectiveRateLimit(rateLimit, isSystemScope, user, context.rateLimit);
+    const effective = resolveEffectiveRateLimits(rateLimit, isSystemScope, user, context.rateLimit);
     // skip: no rateLimit declared and not systemScope (or resolved to no-op) — nothing to enforce
-    if (!effective)
+    if (effective.length === 0)
         return;
     const reqCtx = requestContext.get();
-    const bucket = buildBucketKey(effective, {
-        handlerName,
-        user,
-        ip: reqCtx?.ip,
-    });
-    // skip: ip-bucket + no IP (non-HTTP entry point) — pass through before
-    // requiring a resolver; HTTP path always has an IP + L1/L2 middleware.
-    if (bucket.kind === "skip")
-        return;
-    if (!context.rateLimit) {
-        throw new InternalError({
-            message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rate-limiting feature or remove the option.`,
-        });
-    }
     // A nested dispatch re-hitting a bucket its entry dispatch already charged
     // (e.g. a per:"ip" handler delegating via queryAs) must not cost a second token.
     // The mark is set only after a successful enforce and includes the limit
     // parameters: a denied or failed check never lets a later nested call through,
     // and a nested handler with a stricter limit on the same bucket is still checked.
     const charged = reqCtx?.chargedRateLimitBuckets;
-    const chargedKey = `${bucket.key}|${effective.limit}|${effective.windowSeconds}|${effective.cost}`;
-    // skip: this exact bucket, limit and window was already charged by the entry dispatch
-    if (charged?.has(chargedKey))
+    const pending = [];
+    for (const option of effective) {
+        const bucket = buildBucketKey(option, { handlerName, user, ip: reqCtx?.ip });
+        // skip: ip-bucket + no IP (non-HTTP entry point) — pass through before
+        // requiring a resolver; HTTP path always has an IP + L1/L2 middleware.
+        if (bucket.kind === "skip")
+            continue;
+        const chargedKey = `${bucket.key}|${option.limit}|${option.windowSeconds}|${option.cost}`;
+        // skip: this exact bucket, limit and window was already charged by the entry dispatch
+        if (charged?.has(chargedKey))
+            continue;
+        pending.push({
+            request: {
+                bucket: bucket.key,
+                config: { limit: option.limit, windowSeconds: option.windowSeconds, cost: option.cost },
+            },
+            chargedKey,
+        });
+    }
+    // skip: every bucket was skipped or already charged — nothing left to enforce
+    if (pending.length === 0)
         return;
-    try {
-        await context.rateLimit.enforce(bucket.key, {
-            limit: effective.limit,
-            windowSeconds: effective.windowSeconds,
-            cost: effective.cost,
+    if (!context.rateLimit) {
+        throw new InternalError({
+            message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rate-limiting feature or remove the option.`,
         });
-        charged?.add(chargedKey);
+    }
+    try {
+        await enforceBuckets(context.rateLimit, pending.map(({ request }) => request));
+        for (const { chargedKey } of pending)
+            charged?.add(chargedKey);
     }
     catch (error) {
         // Backend failure (Redis down): fail closed as 503, same as L1/L2.
@@ -1203,6 +1221,7 @@ export async function enforcePayloadRateLimits(ctx, limits, handlerName, user, d
             message: `Handler "${handlerName}" declares additionalRateLimits but its payload is not an object.`,
         });
     }
+    const requests = [];
     for (const { per, limit, windowSeconds, cost, normalize } of limits) {
         const value = data[per.payloadField];
         // skip: optional field not sent — nothing to bucket on
@@ -1213,9 +1232,10 @@ export async function enforcePayloadRateLimits(ctx, limits, handlerName, user, d
                 message: `Handler "${handlerName}" additionalRateLimits payloadField "${per.payloadField}" is not a string.`,
             });
         }
-        const key = buildPayloadBucketKey(user.tenantId, handlerName, per.payloadField, digest(normalizePayloadBucketValue(value, normalize)));
-        await context.rateLimit.enforce(key, { limit, windowSeconds, cost });
+        const bucket = buildPayloadBucketKey(user.tenantId, handlerName, per.payloadField, digest(normalizePayloadBucketValue(value, normalize)));
+        requests.push({ bucket, config: { limit, windowSeconds, cost } });
     }
+    await enforceBuckets(context.rateLimit, requests);
 }
 // Build the per-hook context every auth-claims invocation gets. Claims
 // hooks run OUTSIDE any request transaction (login is itself the root

package/dist/rate-limit/index.d.ts

@@ -1,4 +1,4 @@
 export { type BucketContext, type BucketResult, buildBucketKey, buildPayloadBucketKey, createPayloadDigest, normalizePayloadBucketValue, } from "./bucket.ts";
 export { type AuthEndpointRateLimitOptions, authEndpointRateLimit, type GlobalIpRateLimitOptions, globalIpRateLimit, type HttpRouteRateLimitOptions, httpRouteRateLimit, } from "./middleware.ts";
-export { createRateLimitResolver, type RateLimitConfig, type RateLimitDecision, type RateLimitResolver, type RateLimitResolverOptions, } from "./resolver.ts";
+export { createRateLimitResolver, type RateLimitBucketRequest, type RateLimitConfig, type RateLimitDecision, type RateLimitResolver, type RateLimitResolverOptions, } from "./resolver.ts";
 export { createUnlimitedRateLimitResolver } from "./unlimited-resolver.ts";

package/dist/rate-limit/resolver.d.ts

@@ -1,6 +1,6 @@
 import type { RateLimitResolver } from "@cosmicdrift/kumiko-types/rate-limit-types";
 import type { Redis } from "ioredis";
-export type { RateLimitConfig, RateLimitDecision, RateLimitResolver, } from "@cosmicdrift/kumiko-types/rate-limit-types";
+export type { RateLimitBucketRequest, RateLimitConfig, RateLimitDecision, RateLimitResolver, } from "@cosmicdrift/kumiko-types/rate-limit-types";
 export type RateLimitResolverOptions = {
     readonly redis: Redis;
     readonly keyPrefix?: string;

package/dist/rate-limit/resolver.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { RateLimitError } from "../errors/index.js";
+import { InternalError, RateLimitError } from "../errors/index.js";
 import { RedisKeys } from "../pipeline/redis-keys.js";
 import { toPublicBucketName } from "./bucket.js";
 // Token-Bucket rate limiter, atomic via Redis Lua. One round-trip per
@@ -105,6 +105,64 @@ end
 
 return { math.floor(tokens), retryAfterMs }
 `;
+// All-or-nothing variant for several buckets. Every bucket is refilled and
+// checked first; tokens are deducted only when each one has enough, so a
+// rejected request charges no bucket. Multi-key EVAL needs all keys in one
+// hash slot on Redis Cluster; the framework uses standalone Redis.
+//
+// KEYS[i]  — bucket keys
+// ARGV[1]  — nowMs
+// ARGV[2 + 4(i-1) .. 5 + 4(i-1)] — limit, refillRatePerMs, cost, ttlSeconds of KEYS[i]
+//
+// Returns the flat list { allAllowed (1|0), remaining_1, retryAfterMs_1, remaining_2, ... }.
+// retryAfterMs_i is 0 for buckets that had enough tokens.
+const TOKEN_BUCKET_ALL_LUA = `
+local nowMs = tonumber(ARGV[1])
+local count = #KEYS
+local tokens = {}
+local costs = {}
+local retries = {}
+local allAllowed = 1
+
+for i = 1, count do
+  local base = 2 + (i - 1) * 4
+  local limit = tonumber(ARGV[base])
+  local refillRatePerMs = tonumber(ARGV[base + 1])
+  costs[i] = tonumber(ARGV[base + 2])
+
+  local data = redis.call('HMGET', KEYS[i], 'tokens', 'ts')
+  local current = tonumber(data[1])
+  local ts = tonumber(data[2])
+  if current == nil then
+    current = limit
+  else
+    local elapsed = math.max(0, nowMs - ts)
+    current = math.min(limit, current + elapsed * refillRatePerMs)
+  end
+  tokens[i] = current
+
+  if current >= costs[i] then
+    retries[i] = 0
+  else
+    retries[i] = math.ceil((costs[i] - current) / refillRatePerMs)
+    allAllowed = 0
+  end
+end
+
+local result = { allAllowed }
+for i = 1, count do
+  if allAllowed == 1 then
+    tokens[i] = tokens[i] - costs[i]
+  end
+  local base = 2 + (i - 1) * 4
+  redis.call('HMSET', KEYS[i], 'tokens', tokens[i], 'ts', nowMs)
+  redis.call('EXPIRE', KEYS[i], tonumber(ARGV[base + 3]))
+  result[#result + 1] = math.floor(tokens[i])
+  result[#result + 1] = retries[i]
+end
+
+return result
+`;
 const REGISTERED = new WeakSet();
 function ensureCommand(redis) {
     if (!REGISTERED.has(redis)) {
@@ -116,6 +174,7 @@ function ensureCommand(redis) {
             numberOfKeys: 1,
             lua: TOKEN_BUCKET_PEEK_LUA,
         });
+        redis.defineCommand("kumikoRateLimitAll", { lua: TOKEN_BUCKET_ALL_LUA });
         REGISTERED.add(redis);
     }
     return redis; // @cast-boundary engine-bridge
@@ -154,6 +213,49 @@ export function createRateLimitResolver(opts) {
             resetAt: decision.resetAt.toString(),
         });
     }
+    async function enforceAll(requests) {
+        if (requests.length === 0)
+            return [];
+        const nowMs = now();
+        const keys = requests.map(({ bucket }) => `${prefix}${bucket}`);
+        // The script writes each key back once, so a repeated key would deduct only one of its costs.
+        const duplicate = keys.find((key, index) => keys.indexOf(key) !== index);
+        if (duplicate !== undefined) {
+            throw new InternalError({
+                message: `enforceAll received the bucket "${duplicate.slice(prefix.length)}" more than once — merge the requests into one.`,
+            });
+        }
+        const perBucketArgs = requests.flatMap(({ config }) => [
+            String(config.limit),
+            String(config.limit / (config.windowSeconds * 1000)),
+            String(config.cost ?? 1),
+            String(Math.max(1, config.windowSeconds * 2)),
+        ]);
+        const [allAllowedFlag, ...flat] = await client.kumikoRateLimitAll(keys.length, ...keys, String(nowMs), ...perBucketArgs);
+        const outcomes = requests.map(({ bucket, config }, index) => {
+            const retryAfterMs = flat[index * 2 + 1] ?? 0;
+            const decision = {
+                allowed: retryAfterMs === 0,
+                limit: config.limit,
+                remaining: flat[index * 2] ?? 0,
+                retryAfterSeconds: Math.ceil(retryAfterMs / 1000),
+                windowSeconds: config.windowSeconds,
+                resetAt: Temporal.Instant.fromEpochMilliseconds(nowMs + retryAfterMs),
+            };
+            return { bucket, retryAfterMs, decision };
+        });
+        if (allAllowedFlag === 1)
+            return outcomes.map(({ decision }) => decision);
+        const rejected = outcomes.reduce((worst, outcome) => outcome.retryAfterMs > worst.retryAfterMs ? outcome : worst);
+        throw new RateLimitError({
+            bucket: toPublicBucketName(rejected.bucket),
+            limit: rejected.decision.limit,
+            windowSeconds: rejected.decision.windowSeconds,
+            remaining: rejected.decision.remaining,
+            retryAfterSeconds: rejected.decision.retryAfterSeconds,
+            resetAt: rejected.decision.resetAt.toString(),
+        });
+    }
     async function peek(bucket, config) {
         const refillRatePerMs = config.limit / (config.windowSeconds * 1000);
         const nowMs = now();
@@ -171,5 +273,5 @@ export function createRateLimitResolver(opts) {
             resetAt,
         };
     }
-    return { check, enforce, peek };
+    return { check, enforce, enforceAll, peek };
 }

package/dist/rate-limit/unlimited-resolver.js

@@ -16,6 +16,7 @@ export function createUnlimitedRateLimitResolver() {
     return {
         check: async (_bucket, config) => fullBucket(config),
         enforce: async (_bucket, config) => fullBucket(config),
+        enforceAll: async (requests) => requests.map(({ config }) => fullBucket(config)),
         peek: async (_bucket, config) => fullBucket(config),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.372.0",
+  "version": "0.373.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -199,8 +199,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.372.0",
-    "@cosmicdrift/kumiko-types": "0.372.0",
+    "@cosmicdrift/kumiko-http": "0.373.0",
+    "@cosmicdrift/kumiko-types": "0.373.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -216,8 +216,8 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.372.0",
-    "@cosmicdrift/kumiko-testing": "0.372.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.373.0",
+    "@cosmicdrift/kumiko-testing": "0.373.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.373.0",
+    "type": "improvement",
+    "title": "loadPendingFileRef and bindPendingFileRef bind a caller's own pending upload from a custom handler",
+    "detail": "Additive. fileName is not part of PendingFileRef because it is personal data; read it via the fileRef executor's detail. Unexpected update errors throw; version_conflict and unique_violation map to \"version-conflict\"."
+  },
+  {
+    "version": "0.373.0",
+    "type": "breaking",
+    "title": "rateLimit accepts a list of buckets that are enforced all-or-nothing",
+    "detail": "RateLimitDeclaration is now a single option, a non-empty list of options or the disabled form. RateLimitResolver gains the required method enforceAll(requests: readonly RateLimitBucketRequest[]); createRateLimitResolver and createUnlimitedRateLimitResolver implement it. Payload buckets in additionalRateLimits are charged through the same call.",
+    "migration": "Custom RateLimitResolver implementations and test fakes need an enforceAll method (check every bucket, then deduct from all or none, and throw RateLimitError for the rejected bucket with the largest retryAfter). Existing rateLimit declarations stay valid. A duplicate payloadField in additionalRateLimits is now a boot error; merge the entries into one."
+  },
   {
     "version": "0.372.0",
     "type": "improvement",