@cosmicdrift/kumiko-framework 0.340.0 → 0.342.0

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

@@ -6,6 +6,7 @@ export declare const PII_USER_REFERENCE_NAME_HINTS: ReadonlySet<string>;
 /** Extensions with preSave must target an entity that has mapped write handlers. */
 export declare function validateExtensionPreSaveWiring(features: readonly FeatureDefinition[]): void;
 export declare function validateHandlerAccess(feature: FeatureDefinition): void;
+export declare function validateAdditionalRateLimits(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 validateNoAllRoleInHandlerAccess(featureName: string, kind: "write" | "query" | "stream", handlerName: string, access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>): void;

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

@@ -1,4 +1,5 @@
 import { 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";
 import { parseRefTarget } from "../parse-ref-target.js";
@@ -136,6 +137,53 @@ export function validateHandlerAccess(feature) {
     }
     for (const [name, handler] of Object.entries(feature.writeHandlers)) {
         validateTenantlessAnonymous(feature.name, name, handler);
+        validateAdditionalRateLimits(feature.name, name, handler);
+    }
+}
+const IP_BUCKETED_RATE_LIMIT_PER = new Set(["ip", "ip+handler"]);
+// Payload buckets only complement the per-IP bucket: an anonymous caller
+// who rotates IPs is what they exist for, and without the IP bucket a single
+// IP could still burn through unlimited distinct addresses.
+export function validateAdditionalRateLimits(featureName, handlerName, handler) {
+    const { additionalRateLimits } = handler;
+    // skip: handler declares no payload buckets
+    if (additionalRateLimits === undefined)
+        return;
+    const where = `write handler "${featureName}:write:${handlerName}" declares additionalRateLimits`;
+    if (additionalRateLimits.length === 0) {
+        throw new Error(`${where} as an empty array — declare at least one bucket or drop the option.`);
+    }
+    validateAnonymousHasIpBucket(where, handler);
+    const shape = handler.schema instanceof ZodObject ? handler.schema.shape : undefined;
+    for (const entry of additionalRateLimits) {
+        validatePayloadBucket(where, shape, entry);
+    }
+}
+function validateAnonymousHasIpBucket(where, handler) {
+    const { access, rateLimit } = handler;
+    const allowsAnonymous = "roles" in access && access.roles.includes("anonymous");
+    // 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);
+    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.`);
+    }
+}
+function validatePayloadBucket(where, shape, entry) {
+    const field = entry.per.payloadField;
+    if (shape === undefined || !Object.hasOwn(shape, field)) {
+        throw new Error(`${where} with payloadField "${field}", which is not a field of the handler's schema ` +
+            `(the schema must be a Zod object containing it).`);
+    }
+    if (!Number.isInteger(entry.limit) || entry.limit <= 0) {
+        throw new Error(`${where} for "${field}" with limit ${entry.limit} — must be a positive integer.`);
+    }
+    if (!Number.isInteger(entry.windowSeconds) || entry.windowSeconds <= 0) {
+        throw new Error(`${where} for "${field}" with windowSeconds ${entry.windowSeconds} — must be a positive integer.`);
     }
 }
 export function validateTenantlessAnonymous(featureName, handlerName, handler) {

package/dist/engine/define-handler.js

@@ -50,6 +50,7 @@ export function defineWriteHandler(def,
             unsafeSkipTransitionGuard: def.unsafeSkipTransitionGuard,
         }),
         ...(def.rateLimit && { rateLimit: def.rateLimit }),
+        ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
         ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
         ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
     };

package/dist/engine/feature-ast/extractors/handlers.d.ts

@@ -1,5 +1,5 @@
 import type { CallExpression, SourceFile } from "ts-morph";
-import type { AccessRule, AgentHandlerHints, AgentRisk, EscapeHatchDeclaration, RateLimitDeclaration } from "../../types/handlers.js";
+import type { AccessRule, AgentHandlerHints, AgentRisk, EscapeHatchDeclaration, PayloadRateLimitOption, RateLimitDeclaration } from "../../types/handlers.js";
 import type { QueryHandlerPattern, StreamHandlerPattern, WriteHandlerPattern } from "../patterns.js";
 import type { SourceLocation } from "../source-location.js";
 import { type ExtractOutput, type RawRefSentinel } from "./shared.js";
@@ -12,6 +12,7 @@ export type ParsedHandlerCall = {
     readonly description?: string;
     readonly agent?: AgentHandlerHints | RawRefSentinel;
     readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
+    readonly additionalRateLimits?: readonly PayloadRateLimitOption[] | RawRefSentinel;
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };

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

@@ -1,7 +1,7 @@
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
 import { SyntaxKind } from "ts-morph";
 import { sourceLocationFromNode } from "../source-location.js";
-import { readHeaderValueOrRaw, readOptionalAccessRule, readOptionalEscapeHatch, readOptionalRateLimit, } from "./hooks.js";
+import { readHeaderValueOrRaw, readOptionalAccessRule, readOptionalAdditionalRateLimits, readOptionalEscapeHatch, readOptionalRateLimit, } from "./hooks.js";
 import { fail, findFunctionLiteral, isPlainObject, isRawRefSentinel, ok, readBooleanProperty, readDataLiteralNode, readNameLiteral, readObjectPropertyInitializer, readPropertyKey, } from "./shared.js";
 export const AGENT_RISK_VALUES = ["low", "mid", "high"];
 function isAgentRisk(value) {
@@ -31,6 +31,7 @@ const WRITE_HANDLER_KEY_KINDS = {
     agent: "modeled",
     unsafeSkipTransitionGuard: "modeled",
     rateLimit: "modeled",
+    additionalRateLimits: "modeled",
     escapeHatch: "modeled",
     tenantlessAnonymous: "opaque",
     perform: "opaque",
@@ -176,6 +177,9 @@ function readHandlerHeaderFields(obj, methodName, sourceFile) {
     const rateLimitResult = readHeaderField(readObjectPropertyInitializer(obj, "rateLimit"), readOptionalRateLimit, methodName, sourceFile, "rateLimit must be { per, limit, windowSeconds } 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");
+    if (additionalRateLimitsResult.kind === "error")
+        return additionalRateLimitsResult;
     const escapeHatchResult = readHeaderField(readObjectPropertyInitializer(obj, "escapeHatch"), readOptionalEscapeHatch, methodName, sourceFile, "escapeHatch must be { reason: string }, or a reference to one");
     if (escapeHatchResult.kind === "error")
         return escapeHatchResult;
@@ -185,6 +189,9 @@ function readHandlerHeaderFields(obj, methodName, sourceFile) {
     return ok({
         ...(accessResult.pattern !== undefined && { access: accessResult.pattern }),
         ...(rateLimitResult.pattern !== undefined && { rateLimit: rateLimitResult.pattern }),
+        ...(additionalRateLimitsResult.pattern !== undefined && {
+            additionalRateLimits: additionalRateLimitsResult.pattern,
+        }),
         ...(escapeHatchResult.pattern !== undefined && { escapeHatch: escapeHatchResult.pattern }),
         ...(agentResult.pattern !== undefined && { agent: agentResult.pattern }),
     });
@@ -307,6 +314,9 @@ export function extractWriteHandler(call, sourceFile) {
         ...(parsed.pattern.description !== undefined && { description: parsed.pattern.description }),
         ...(parsed.pattern.agent !== undefined && { agent: parsed.pattern.agent }),
         ...(parsed.pattern.rateLimit !== undefined && { rateLimit: parsed.pattern.rateLimit }),
+        ...(parsed.pattern.additionalRateLimits !== undefined && {
+            additionalRateLimits: parsed.pattern.additionalRateLimits,
+        }),
         ...(parsed.pattern.unsafeSkipTransitionGuard === true && { unsafeSkipTransitionGuard: true }),
         ...(parsed.pattern.escapeHatch !== undefined && { escapeHatch: parsed.pattern.escapeHatch }),
     });

package/dist/engine/feature-ast/extractors/hooks.d.ts

@@ -1,6 +1,6 @@
 import type { CallExpression, Node, SourceFile } from "ts-morph";
 import type { LifecycleHookType } from "../../constants.js";
-import type { AccessRule, EscapeHatchDeclaration, RateLimitDeclaration } from "../../types/handlers.js";
+import type { AccessRule, EscapeHatchDeclaration, PayloadRateLimitOption, RateLimitDeclaration } from "../../types/handlers.js";
 import type { HookPhase } from "../../types/hooks.js";
 import type { AuthClaimsPattern, HookPattern } from "../patterns.js";
 import { type ExtractOutput, type RawRefSentinel } from "./shared.js";
@@ -18,6 +18,7 @@ export declare function isHookType(value: string): value is LifecycleHookType |
 export declare function readOptionalPhase(node: Node | undefined): HookPhase | undefined;
 export declare function readOptionalAccessRule(value: unknown): AccessRule | undefined;
 export declare function readOptionalRateLimit(value: unknown): RateLimitDeclaration | undefined;
+export declare function readOptionalAdditionalRateLimits(value: unknown): readonly PayloadRateLimitOption[] | undefined;
 export declare function readOptionalEscapeHatch(value: unknown): EscapeHatchDeclaration | undefined;
 export declare function extractHook(call: CallExpression, sourceFile: SourceFile): ExtractOutput<HookPattern>;
 export declare function extractAuthClaims(call: CallExpression, sourceFile: SourceFile): ExtractOutput<AuthClaimsPattern>;

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

@@ -71,6 +71,20 @@ export function readOptionalRateLimit(value) {
         return undefined;
     return value;
 }
+function isPayloadRateLimitOption(value) {
+    if (!isPlainObject(value))
+        return false;
+    const per = value["per"];
+    return (isPlainObject(per) &&
+        typeof per["payloadField"] === "string" &&
+        typeof value["limit"] === "number" &&
+        typeof value["windowSeconds"] === "number");
+}
+export function readOptionalAdditionalRateLimits(value) {
+    if (!Array.isArray(value) || !value.every(isPayloadRateLimitOption))
+        return undefined;
+    return value;
+}
 export function readOptionalEscapeHatch(value) {
     if (!isPlainObject(value))
         return undefined;

package/dist/engine/feature-ast/extractors/index.d.ts

@@ -1,7 +1,7 @@
 export { extractAiClassify, extractAiExtract, extractAiGenerate, } from "./ai-steps.js";
 export { extractDefineEvent, extractNotification, } from "./events.js";
 export { extractQueryHandler, extractStreamHandler, extractWriteHandler, type ParsedHandlerCall, parseHandlerCall, } from "./handlers.js";
-export { extractAuthClaims, extractHook, isHookType, readOptionalAccessRule, readOptionalPhase, readOptionalRateLimit, } from "./hooks.js";
+export { extractAuthClaims, extractHook, isHookType, readOptionalAccessRule, readOptionalAdditionalRateLimits, readOptionalPhase, readOptionalRateLimit, } from "./hooks.js";
 export { extractHttpRoute, extractJob, isHttpRouteMethod, } from "./jobs-routes.js";
 export { collectScreenOpaqueProps, extractMultiStreamProjection, extractProjection, extractScreen, readApplyBodies, readScreenStatic, } from "./projections-screens.js";
 export { findImportBindingForLocalName, resolveModuleFile, } from "./resolve-import.js";

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

@@ -1,7 +1,7 @@
 export { extractAiClassify, extractAiExtract, extractAiGenerate, } from "./ai-steps.js";
 export { extractDefineEvent, extractNotification, } from "./events.js";
 export { extractQueryHandler, extractStreamHandler, extractWriteHandler, parseHandlerCall, } from "./handlers.js";
-export { extractAuthClaims, extractHook, isHookType, readOptionalAccessRule, readOptionalPhase, readOptionalRateLimit, } from "./hooks.js";
+export { extractAuthClaims, extractHook, isHookType, readOptionalAccessRule, readOptionalAdditionalRateLimits, readOptionalPhase, readOptionalRateLimit, } from "./hooks.js";
 export { extractHttpRoute, extractJob, isHttpRouteMethod, } from "./jobs-routes.js";
 export { collectScreenOpaqueProps, extractMultiStreamProjection, extractProjection, extractScreen, readApplyBodies, readScreenStatic, } from "./projections-screens.js";
 export { findImportBindingForLocalName, resolveModuleFile, } from "./resolve-import.js";

package/dist/engine/feature-ast/patch.js

@@ -180,6 +180,7 @@ const WRITE_HANDLER_HEADER_KEY_FLAGS = {
     description: true,
     agent: true,
     rateLimit: true,
+    additionalRateLimits: true,
     unsafeSkipTransitionGuard: true,
     escapeHatch: true,
 };

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

@@ -195,6 +195,16 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
         }, z.core.$strict>]>, z.ZodObject<{
             __raw: z.ZodString;
         }, z.core.$strict>]>>;
+        additionalRateLimits: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
+            per: z.ZodObject<{
+                payloadField: z.ZodString;
+            }, z.core.$strict>;
+            limit: z.ZodNumber;
+            windowSeconds: z.ZodNumber;
+            cost: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>, z.ZodObject<{
+            __raw: z.ZodString;
+        }, z.core.$strict>]>>;
         escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             reason: z.ZodString;
             grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
@@ -707,6 +717,16 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strict>]>, z.ZodObject<{
         __raw: z.ZodString;
     }, z.core.$strict>]>>;
+    additionalRateLimits: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
+        per: z.ZodObject<{
+            payloadField: z.ZodString;
+        }, z.core.$strict>;
+        limit: z.ZodNumber;
+        windowSeconds: z.ZodNumber;
+        cost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>, z.ZodObject<{
+        __raw: z.ZodString;
+    }, z.core.$strict>]>>;
     escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         reason: z.ZodString;
         grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{

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

@@ -157,6 +157,14 @@ const rateLimitOptionSchema = z
     cost: z.number().optional(),
 })
     .strict();
+const additionalRateLimitsSchema = z.array(z
+    .object({
+    per: z.object({ payloadField: z.string() }).strict(),
+    limit: z.number(),
+    windowSeconds: z.number(),
+    cost: z.number().optional(),
+})
+    .strict());
 const agentHandlerHintsSchema = z
     .object({
     expose: z.boolean().optional(),
@@ -192,6 +200,7 @@ const WRITE_HANDLER_HEADER_SHAPE = {
     description: z.string(),
     agent: agentHandlerHintsSchema,
     rateLimit: rateLimitOptionSchema,
+    additionalRateLimits: additionalRateLimitsSchema,
     unsafeSkipTransitionGuard: z.boolean(),
     escapeHatch: escapeHatchSchema,
 };
@@ -238,6 +247,7 @@ const WRITE_HANDLER_PATTERN_HEADER_SHAPE = {
     access: orRawRef(accessRuleSchema),
     agent: orRawRef(agentHandlerHintsSchema),
     rateLimit: orRawRef(z.union([rateLimitOptionSchema, rateLimitDisabledSchema])),
+    additionalRateLimits: orRawRef(additionalRateLimitsSchema),
     escapeHatch: orRawRef(escapeHatchSchema),
 };
 const QUERY_HANDLER_PATTERN_HEADER_SHAPE = {

package/dist/engine/feature-ast/patterns.d.ts

@@ -2,7 +2,7 @@ import type { LifecycleHookType } from "../constants.js";
 import type { ConfigKeyDefinition, ConfigKeyType, JobDefinition, ReferenceDataDef, RunIn, TranslationKeys } from "../types/config.js";
 import type { MetricOptions, SecretNamespaceOptions, SecretOptions } from "../types/feature.js";
 import type { EntityDefinition } from "../types/fields.js";
-import type { AccessRule, AgentHandlerHints, ClaimKeyType, EscapeHatchDeclaration, RateLimitDeclaration } from "../types/handlers.js";
+import type { AccessRule, AgentHandlerHints, ClaimKeyType, EscapeHatchDeclaration, PayloadRateLimitOption, RateLimitDeclaration } from "../types/handlers.js";
 import type { HookPhase } from "../types/hooks.js";
 import type { HttpRouteMethod } from "../types/http-route.js";
 import type { NavDefinition } from "../types/nav.js";
@@ -142,6 +142,7 @@ export type WriteHandlerPattern = {
     readonly description?: string;
     readonly agent?: AgentHandlerHints | RawRefSentinel;
     readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
+    readonly additionalRateLimits?: readonly PayloadRateLimitOption[] | RawRefSentinel;
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };

package/dist/engine/feature-ast/render.js

@@ -358,6 +358,9 @@ function renderWriteHandler(p) {
         lines.push(`  agent: ${renderValue(p.agent)},`);
     if (p.rateLimit !== undefined)
         lines.push(`  rateLimit: ${renderValue(p.rateLimit)},`);
+    if (p.additionalRateLimits !== undefined) {
+        lines.push(`  additionalRateLimits: ${renderValue(p.additionalRateLimits)},`);
+    }
     if (p.unsafeSkipTransitionGuard === true)
         lines.push("  unsafeSkipTransitionGuard: true,");
     if (p.escapeHatch !== undefined)

package/dist/engine/feature-entity-handlers.d.ts

@@ -3,7 +3,7 @@ import type { ZodType } from "zod";
 import { type QueryHandlerDefinition, type StreamHandlerDefinition, type WriteHandlerDefinition } from "./define-handler.js";
 import type { RegisterEntityCrudOptions } from "./entity-handlers.js";
 import type { FeatureBuilderState } from "./feature-builder-state.js";
-import type { AccessRule, AgentHandlerHints, EntityDefinition, EntityRef, EscapeHatchDeclaration, HandlerRef, NameOrRef, QueryHandlerFn, RateLimitDeclaration, RelationDefinition, StreamHandlerFn, WriteHandlerFn } from "./types/index.js";
+import type { AccessRule, AgentHandlerHints, EntityDefinition, EntityRef, EscapeHatchDeclaration, HandlerRef, NameOrRef, PayloadRateLimitOption, QueryHandlerFn, RateLimitDeclaration, RelationDefinition, StreamHandlerFn, WriteHandlerFn } from "./types/index.js";
 export declare function buildEntityHandlerMethods<TName extends string>(state: FeatureBuilderState, name: TName): {
     entity(nameOrDefinition: string | ({
         readonly name: string;
@@ -17,6 +17,7 @@ export declare function buildEntityHandlerMethods<TName extends string>(state: F
     writeHandler<TName_1 extends string, TSchema extends ZodType>(nameOrDef: string | WriteHandlerDefinition<TName_1, TSchema>, schema?: TSchema, handler?: WriteHandlerFn<z.infer<TSchema>>, options?: {
         access: AccessRule;
         rateLimit?: RateLimitDeclaration;
+        additionalRateLimits?: readonly PayloadRateLimitOption[];
         description?: string;
         agent?: AgentHandlerHints;
         escapeHatch?: EscapeHatchDeclaration;

package/dist/engine/feature-entity-handlers.js

@@ -105,6 +105,7 @@ export function buildEntityHandlerMethods(state, name) {
                     ...agentSlots(def),
                     ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
                     ...(def.rateLimit && { rateLimit: def.rateLimit }),
+                    ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
                     ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
                     ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
                     // Forward the pipeline-build closure so boot-validators and
@@ -129,6 +130,9 @@ export function buildEntityHandlerMethods(state, name) {
                 access: inline.options.access,
                 ...agentSlots(inline.options),
                 ...(inline.options.rateLimit && { rateLimit: inline.options.rateLimit }),
+                ...(inline.options.additionalRateLimits && {
+                    additionalRateLimits: inline.options.additionalRateLimits,
+                }),
                 ...(inline.options.escapeHatch && { escapeHatch: inline.options.escapeHatch }),
             };
             tryMapEntity(state, name, nameOrDef);

package/dist/engine/feature-ui-extensions.js

@@ -421,6 +421,15 @@ export function buildUiExtensionsMethods(state, name) {
                 throw new Error(`[Feature ${name}] httpRoute "${definition.method} ${definition.path}" must declare ` +
                     `anonymous: true | false — true mounts it public, false behind the session auth chain.`);
             }
+            const routeLimit = definition.rateLimit;
+            if (routeLimit !== undefined &&
+                (!Number.isInteger(routeLimit.limit) ||
+                    routeLimit.limit < 1 ||
+                    !Number.isInteger(routeLimit.windowSeconds) ||
+                    routeLimit.windowSeconds < 1)) {
+                throw new Error(`[Feature ${name}] httpRoute "${definition.method} ${definition.path}" rateLimit needs ` +
+                    `positive integer limit and windowSeconds.`);
+            }
             const key = `${definition.method} ${definition.path}`;
             if (state.httpRoutes[key]) {
                 throw new Error(`[Feature ${name}] HTTP-Route "${key}" already registered. ` +

package/dist/engine/index.d.ts

@@ -74,7 +74,7 @@ export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
-export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyFactory, NotifyFn, NotifyOptions, NotifyPriority, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
+export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases, isAgentVisibleScreen, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export type { AwaitedEventType, PipelineBuildCtx, PipelineCtx, PipelineDef, StepBuilder, StepDef, StepFailureStrategy, StepInstance, StepKind, StepNamespace, StepResolver, } from "./types/step.js";
 export { runValidation } from "./validation.js";

package/dist/engine/membership-roles.js

@@ -10,6 +10,7 @@
 // matching strip (anonymous/all only) to globalRoles, where SystemAdmin
 // legitimately lives.
 import { access } from "./config-helpers.js";
+import { SYSTEM_ROLE } from "./system-user.js";
 export const FORBIDDEN_MEMBERSHIP_ROLES = new Set([
     ...access.privileged, // system, SystemAdmin
     ...access.all, // all
@@ -26,10 +27,13 @@ export function findForbiddenMembershipRole(roles) {
 export function stripForbiddenMembershipRoles(roles) {
     return roles.filter((role) => !isForbiddenMembershipRole(role));
 }
-// "anonymous"/"all" are never legitimate global roles; system/SystemAdmin stay.
+// "anonymous"/"all" are never legitimate global roles; SystemAdmin stays.
+// "system" is the in-process identity (system-identity-switch treats any user
+// carrying it as System) and must never end up in a session.
 const NON_MINTABLE_GLOBAL_ROLES = new Set([
     ...access.all,
     ...access.anonymous,
+    SYSTEM_ROLE,
 ]);
 function stripNonMintableGlobalRoles(roles) {
     return roles.filter((role) => !NON_MINTABLE_GLOBAL_ROLES.has(role));

package/dist/engine/pattern-library/mixed-schemas.js

@@ -78,6 +78,11 @@ export const writeHandlerSchema = {
             label: { en: "Rate limit", de: "Rate-Limit" },
             input: "json-readonly",
         },
+        {
+            path: "additionalRateLimits",
+            label: { en: "Per-payload rate limits", de: "Payload-Rate-Limits" },
+            input: "json-readonly",
+        },
         {
             path: "unsafeSkipTransitionGuard",
             label: { en: "Skip transition guard", de: "Übergangs-Guard überspringen" },

package/dist/engine/registry-state.js

@@ -43,7 +43,6 @@ export function buildImplicitProjection(featureName, entityName, entity, qualify
     // r.extendEntityProjection: merge extension applies into the rebuild
     // replay. Collisions with lifecycle applies (or another extension) are
     // authoring bugs — fail at boot, not by silently overwriting a handler.
-    const extraSources = [];
     for (const ext of extensions) {
         for (const [eventType, fn] of Object.entries(ext.apply)) {
             if (apply[eventType]) {
@@ -52,20 +51,54 @@ export function buildImplicitProjection(featureName, entityName, entity, qualify
             }
             apply[eventType] = fn;
         }
-        for (const s of ext.sources ?? []) {
-            if (s !== entityName && !extraSources.includes(s))
-                extraSources.push(s);
-        }
     }
+    const { extraSources, extraSourceRowIds } = collectExtensionSources(name, entityName, extensions);
     return {
         name,
         source: entityName,
         ...(extraSources.length > 0 && { extraSources }),
+        ...(Object.keys(extraSourceRowIds).length > 0 && { extraSourceRowIds }),
         table: drizzleTable,
         apply,
         isImplicit: true,
     };
 }
+function assertRowIdOfSources(projectionName, entityName, ext) {
+    // skip: extension maps no rowIdOf, nothing to validate
+    if (ext.rowIdOf === undefined)
+        return;
+    const sources = ext.sources ?? [];
+    if (sources.length === 0) {
+        throw new Error(`Implicit projection "${projectionName}": extendEntityProjection declares rowIdOf without ` +
+            `\`sources\` — rowIdOf maps events of the declared sources to row ids.`);
+    }
+    if (sources.includes(entityName)) {
+        throw new Error(`Implicit projection "${projectionName}": extendEntityProjection rowIdOf cannot apply to the ` +
+            `entity's own stream "${entityName}" — host-stream rows are keyed by the aggregate id.`);
+    }
+}
+function collectExtensionSources(projectionName, entityName, extensions) {
+    const extraSources = [];
+    const extraSourceRowIds = {};
+    const rowIdDeclaredBy = new Map();
+    for (const ext of extensions) {
+        for (const s of ext.sources ?? []) {
+            if (s !== entityName && !extraSources.includes(s))
+                extraSources.push(s);
+        }
+        assertRowIdOfSources(projectionName, entityName, ext);
+        for (const s of ext.sources ?? []) {
+            if (rowIdDeclaredBy.has(s) && rowIdDeclaredBy.get(s) !== ext.rowIdOf) {
+                throw new Error(`Implicit projection "${projectionName}": source "${s}" is declared by several extensions with ` +
+                    `different or missing rowIdOf — the row id for its events is ambiguous.`);
+            }
+            rowIdDeclaredBy.set(s, ext.rowIdOf);
+            if (ext.rowIdOf !== undefined)
+                extraSourceRowIds[s] = ext.rowIdOf;
+        }
+    }
+    return { extraSources, extraSourceRowIds };
+}
 // Validates a r.entity backing table is a superset of the entity's field-
 // derived columns, then hands it back as the projection table. The cast is a
 // system-boundary reconstitution: the table is stored as `unknown` on

package/dist/engine/registry-validate.js

@@ -655,6 +655,8 @@ export function computeHasRateLimitedHandler(state) {
         for (const h of state.writeHandlerMap.values()) {
             if (h.rateLimit !== undefined && !isRateLimitDisabled(h.rateLimit))
                 return true;
+            if (h.additionalRateLimits !== undefined)
+                return true;
         }
         for (const h of state.queryHandlerMap.values()) {
             if (h.rateLimit !== undefined && !isRateLimitDisabled(h.rateLimit))

package/dist/engine/soft-delete-cleanup.d.ts

@@ -1,9 +1,11 @@
 import type { ConfigKeyDefinition, JobDefinition, JobHandlerFn } from "./types/config.js";
+import type { EntityDefinition } from "./types/index.js";
 export declare const SOFT_DELETE_CLEANUP_JOB = "soft-delete:job:cleanup";
 export declare const SOFT_DELETE_CLEANUP_SYSTEM_JOB = "soft-delete:job:cleanup-system";
 export declare const SOFT_DELETE_GRACE_DAYS_KEY = "soft-delete:config:grace-days";
 export declare const DEFAULT_GRACE_DAYS = 30;
 export declare const softDeleteGraceDaysConfig: ConfigKeyDefinition;
+export declare function isSystemScopedSoftDeleteTable(table: unknown, entity: Pick<EntityDefinition, "tenancy">): boolean;
 export declare const softDeleteCleanupJob: JobHandlerFn;
 export declare const softDeleteCleanupSystemJob: JobHandlerFn;
 export declare function buildSoftDeleteCleanupJob(): JobDefinition;

package/dist/engine/soft-delete-cleanup.js

@@ -10,7 +10,7 @@
 // resurrect the row as isDeleted=true. That's acceptable: cleanup bounds LIVE
 // table growth; irreversible event-log purging is data-retention's job
 // (pruneEvents), a separate, consumer-lag-guarded path.
-import { deleteMany } from "../db/query.js";
+import { asEntityTableMeta, deleteMany } from "../db/query.js";
 import { SYSTEM_USER_ID } from "./system-user.js";
 // qualifyEntityName convention (feature:type:kebab-name) with a reserved
 // "soft-delete" owner — no real feature owns these; the framework synthesizes
@@ -31,6 +31,18 @@ export const softDeleteGraceDaysConfig = {
     // existing silent-below-bound / audited-crossing behavior.
     bounds: { min: 1 },
 };
+function hasTenantIdColumn(table) {
+    return table["tenantId"] !== undefined;
+}
+// The entity declaration decides, not the column: a `tenancy: "global"` table
+// (e.g. user) still carries a tenantId column (SYSTEM_TENANT_ID), yet no
+// tenant-mode delete can ever match its rows.
+export function isSystemScopedSoftDeleteTable(table, entity) {
+    return entity.tenancy === "global" || !hasTenantIdColumn(table);
+}
+function isGlobalTenancyTable(table) {
+    return asEntityTableMeta(table)?.tenancy === "global";
+}
 export const softDeleteCleanupJob = async (_payload, ctx) => {
     const { db, registry } = ctx;
     if (!db || !registry) {
@@ -57,21 +69,18 @@ export const softDeleteCleanupJob = async (_payload, ctx) => {
         const entity = registry.getEntity(proj.source);
         if (!entity?.softDelete)
             continue;
-        // @cast-boundary column-presence probe — identical access the executor's
-        // list() does on table["tenantId"] to decide tenant-scoping.
-        const hasTenantColumn = proj.table["tenantId"] !== undefined;
-        // System-global entities (no tenantId column, e.g. `user`) are NOT swept
+        // System-global entities (tenancy "global" or no tenantId column, e.g. `user`) are NOT swept
         // here: this handler runs once PER TENANT, so a tenant-scoped grace value
         // would purge every OTHER tenant's still-within-grace rows too (effective
         // grace = min() across all tenants). softDeleteCleanupSystemJob handles
         // these separately, once, with a fixed grace period.
-        if (!hasTenantColumn)
+        if (isSystemScopedSoftDeleteTable(proj.table, entity))
             continue;
         const where = { isDeleted: true, deletedAt: { lt: cutoff }, tenantId };
         await deleteMany(db, proj.table, where);
     }
 };
-// System-global soft-deleted entities (no tenantId column) can't take a
+// System-global soft-deleted entities (tenancy "global" or no tenantId column) can't take a
 // per-tenant grace period — there's no "this tenant's view" of a row that
 // isn't scoped to any tenant. Runs once (not perTenant) with a fixed grace
 // period; a future system-scope config key could make this configurable
@@ -88,9 +97,15 @@ export const softDeleteCleanupSystemJob = async (_payload, ctx) => {
         const entity = registry.getEntity(proj.source);
         if (!entity?.softDelete)
             continue;
-        if (proj.table["tenantId"] !== undefined)
+        if (!isSystemScopedSoftDeleteTable(proj.table, entity))
             continue;
-        await deleteMany(db, proj.table, { isDeleted: true, deletedAt: { lt: cutoff } });
+        const where = { isDeleted: true, deletedAt: { lt: cutoff } };
+        if (isGlobalTenancyTable(proj.table)) {
+            await db.global(proj.table).deleteMany(where);
+        }
+        else {
+            await deleteMany(db, proj.table, where);
+        }
     }
 };
 export function buildSoftDeleteCleanupJob() {
@@ -110,5 +125,9 @@ export function buildSoftDeleteCleanupSystemJob() {
         trigger: { cron: "15 3 * * *" },
         concurrency: "skip",
         runIn: "worker",
+        escapeHatch: {
+            reason: "hard-deletes expired soft-deleted rows of global entities (e.g. user) once, system-wide",
+            grants: ["globalWrites"],
+        },
     };
 }

package/dist/engine/tier-resolver-extension.d.ts

@@ -1,3 +1,4 @@
+import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
 import type { DbConnection } from "../db/connection.js";
 import type { RegistrarExtensionRegistration } from "./types/config.js";
 import type { FeatureDefinition, Registry } from "./types/feature.js";
@@ -44,6 +45,7 @@ export type TierResolverPlugin = {
     readonly build: (deps: {
         readonly db: DbConnection;
         readonly registry: Registry;
+        readonly cacheSync?: CacheSyncBus;
     }) => Promise<EffectiveFeaturesResolver>;
 };
 /**