@cosmicdrift/kumiko-framework 0.371.1 → 0.373.0

package/dist/db/table-builder.d.ts

@@ -3,6 +3,8 @@ import type { ExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
 import type { TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 import type { EntityDefinition, EntityRelations, FieldDefinition, FieldsMap } from "../engine/types/index.ts";
 import type { Table } from "./event-store-executor-context.ts";
+import type { LocatedTimestampRead } from "./located-timestamp.ts";
+import type { MoneyRead } from "./money.ts";
 export { toSnakeCase } from "../utils/case.ts";
 import { type ColumnBuilder, type ColumnHandle, type SchemaTable, type TableColumns } from "./dialect.ts";
 export declare const SOFT_DELETE_LIVE_ROW_PREDICATE = "\"is_deleted\" = false";
@@ -10,25 +12,23 @@ export declare function physicalColumnName(table: Table, field: string): string;
 export type AnyPgColumn = ColumnHandle;
 export declare const READ_MODEL_PREFIX = "read_";
 export declare function toTableName(entityName: string): string;
-type Col<_T> = ColumnHandle & {
+type Col<T> = ColumnHandle & {
     readonly __notNull: true;
+    readonly __value?: T;
 };
-type NullCol<_T> = ColumnHandle & {
+type NullCol<T> = ColumnHandle & {
     readonly __notNull: false;
+    readonly __value?: T;
 };
-type ColumnsForField<K extends string, F extends FieldDefinition> = F extends {
+type ColumnsForField<K extends string, F extends FieldDefinition> = ValueColumnsForField<K, F> & BlindIndexColumnForField<K, F>;
+type BlindIndexColumnForField<K extends string, F extends FieldDefinition> = F extends {
     type: "text";
     lookupable: true;
-} ? (F extends {
-    required: true;
 } ? {
-    readonly [P in K]: Col<string>;
-} : {
-    readonly [P in K]: NullCol<string>;
-}) & {
     readonly [P in `${K}Bidx`]: NullCol<string>;
-} : F extends {
-    type: "text" | "select" | "tz";
+} : unknown;
+type ValueColumnsForField<K extends string, F extends FieldDefinition> = F extends {
+    type: "text" | "longText" | "select" | "tz";
 } ? F extends {
     required: true;
 } ? {
@@ -160,6 +160,40 @@ type SoftDeleteColumnsType = {
     readonly deletedAt: NullCol<Temporal.Instant>;
     readonly deletedById: NullCol<string>;
 };
+type ColumnValue<C> = C extends {
+    readonly __notNull: true;
+    readonly __value?: infer T;
+} ? T : C extends {
+    readonly __notNull: false;
+    readonly __value?: infer T;
+} ? T | null : unknown;
+type RowOfColumns<C> = {
+    readonly [K in keyof C]: ColumnValue<C[K]>;
+};
+type CompoundRowField<K extends string, V, F> = F extends {
+    required: true;
+} ? {
+    readonly [P in K]: V;
+} : {
+    readonly [P in K]?: V;
+};
+type RowForField<K extends string, F extends FieldDefinition> = F extends {
+    type: "money";
+} ? CompoundRowField<K, MoneyRead, F> : F extends {
+    type: "locatedTimestamp";
+} ? CompoundRowField<K, LocatedTimestampRead, F> : [ValueColumnsForField<K, F>] extends [never] ? {
+    readonly [P in K]: unknown;
+} : RowOfColumns<ValueColumnsForField<K, F>>;
+type RowForFields<F extends FieldsMap> = UnionToIntersection<{
+    [K in keyof F & string]: RowForField<K, F[K]>;
+}[keyof F & string]>;
+type SoftDeleteRow<E extends EntityDefinition> = E["softDelete"] extends true ? RowOfColumns<SoftDeleteColumnsType> : [E["softDelete"]] extends [false | undefined] ? unknown : Partial<RowOfColumns<SoftDeleteColumnsType>>;
+type Flatten<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** The row `executor.list()` / `executor.detail()` return for entity `E`. A wide
+ *  `EntityDefinition` (fields without literal keys) yields `Record<string, unknown>`. */
+export type EntityRow<E extends EntityDefinition = EntityDefinition> = string extends keyof E["fields"] ? Record<string, unknown> : Flatten<RowOfColumns<BaseColumnsType<E>> & SoftDeleteRow<E> & RowForFields<E["fields"]>>;
 export type { ExecutorOnly, NotExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
 export type { EntityTenancy, TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 type EntityTableTenancy<E extends EntityDefinition> = [NonNullable<E["tenancy"]>] extends [never] ? "tenant" : [NonNullable<E["tenancy"]>] extends ["global"] ? "global" : "tenant";

package/dist/db/tenant-db.js

@@ -504,7 +504,9 @@ function buildTenantDb(options) {
                     return Promise.reject(new Error("db.global().deleteMany without where would mass-delete every tenant's rows. Pass at least one where condition."));
                 }
                 report("global-write", globalWriteReason());
-                return withDbSpan("delete", table, async () => bunDeleteMany(db, table, where));
+                return withDbSpan("delete", table, async () => {
+                    await bunDeleteMany(db, table, where);
+                });
             },
             // @cast-boundary phantom-brand — GlobalWrites is only present in the type when TTable is not ExecutorOnly; the object above always carries the methods.
         };

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/entity-handlers.d.ts

@@ -1,6 +1,6 @@
 import * as z from "zod";
 import { type EventStoreExecutor } from "../db/event-store-executor.ts";
-import { type EntityTable } from "../db/table-builder.ts";
+import { type EntityRow, type EntityTable } from "../db/table-builder.ts";
 import type { EntityCrudRegistrar, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions } from "./types/entity-handlers.ts";
 import type { AccessRule, EntityDefinition, EscapeHatchDeclaration, QueryHandlerDef, WriteHandlerDef } from "./types/index.ts";
 export type { EntityCrudHandlerDefaults, EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "./types/entity-handlers.ts";
@@ -53,9 +53,9 @@ export declare function defineEntityDeleteHandler(entityName: string, entity: En
 export declare function defineEntityRestoreHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): WriteHandlerDef;
 export declare function defineEntityListHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
 export declare function defineEntityDetailHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
-export declare function createEntityExecutor(entityName: string, entity: EntityDefinition): {
+export declare function createEntityExecutor<E extends EntityDefinition>(entityName: string, entity: E): {
     readonly table: EntityTable;
-    readonly executor: EventStoreExecutor;
+    readonly executor: EventStoreExecutor<EntityRow<E>>;
 };
 export declare function defineProjectionQueryHandler(name: string, projectionQualifiedName: string, options: {
     access: AccessRule;

package/dist/engine/factories.d.ts

@@ -32,6 +32,7 @@ export declare function createBooleanField<R extends true | false = false>(overr
     required?: R;
 }): BooleanFieldDef & {
     required: R;
+    default: boolean;
 };
 export declare function createSelectField<const TOptions extends readonly string[], R extends true | false = false>(opts: {
     options: TOptions;
@@ -171,7 +172,7 @@ export declare function createFileField(overrides?: Partial<Omit<FileFieldDef, "
 export declare function createImageField(overrides?: Partial<Omit<ImageFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): ImageFieldDef;
 export declare function createFilesField(overrides?: Partial<Omit<FilesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FilesFieldDef;
 export declare function createImagesField(overrides?: Partial<Omit<ImagesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): ImagesFieldDef;
-export declare function createEntity<F, const T extends EntityTenancy = "tenant">(def: {
+export declare function createEntity<const F, const T extends EntityTenancy = "tenant">(def: {
     readonly table?: string;
     readonly fields: F;
     readonly description?: string;

package/dist/engine/factories.js

@@ -378,6 +378,8 @@ export function createImagesField(overrides) {
 // Issue um Constraint-Inferenz auf strukturellen Records. Stattdessen
 // validieren wir die Conformance via conditional return type: wenn F
 // nicht FieldsMap-compat ist, kollabiert der Return zu `never`.
+// `const F`: inline field literals (`{ type: "reference", ... }`) keep their
+// `type` literal without `as const`; otherwise it widens to string → `never`.
 export function createEntity(def) {
     return {
         softDelete: false,

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/membership-roles.d.ts

@@ -2,4 +2,5 @@ export declare const FORBIDDEN_MEMBERSHIP_ROLES: ReadonlySet<string>;
 export declare function isForbiddenMembershipRole(role: string): boolean;
 export declare function findForbiddenMembershipRole(roles: readonly string[]): string | undefined;
 export declare function stripForbiddenMembershipRoles(roles: readonly string[]): readonly string[];
+export declare function stripReservedTokenRoles(roles: readonly string[]): readonly string[];
 export declare function buildSessionRoles(globalRoles: readonly string[], membershipRoles: readonly string[]): readonly string[];

package/dist/engine/membership-roles.js

@@ -38,6 +38,14 @@ const NON_MINTABLE_GLOBAL_ROLES = new Set([
 function stripNonMintableGlobalRoles(roles) {
     return roles.filter((role) => !NON_MINTABLE_GLOBAL_ROLES.has(role));
 }
+// Applied on JWT verify: a token signed with the right key (leaked or foreign)
+// must not carry the in-process System identity or the "all" pseudo-role.
+// "anonymous" stays: it only narrows access (openToAll excludes it), and
+// stripping it would turn the token into an authenticated user with no roles.
+const RESERVED_TOKEN_ROLES = new Set([...access.all, SYSTEM_ROLE]);
+export function stripReservedTokenRoles(roles) {
+    return roles.filter((role) => !RESERVED_TOKEN_ROLES.has(role));
+}
 // Single mint path for session roles: merges globalRoles with the stripped
 // membership portion and dedupes. Every place that builds a session's roles
 // from a membership should go through this instead of repeating

package/dist/engine/strip-disabled-features-from-app-schema.js

@@ -1,11 +1,17 @@
 // Tenant-level counterpart to projectAppSchemaForRoles: removes the UI surface
 // (screens, navs, content collections, workspaces) of features the tenant has
 // switched off via r.toggleable(). Entities and translations stay — enabled
-// features may still reference them. Run BEFORE the role projection: it keeps
+// features may still reference them. Screens that declare a `fallback` (plus
+// the same-feature screens those fallbacks name) are the exception: their
+// visibleWhen probe is rejected by the feature gate for this tenant, which is
+// what makes the renderer show the fallback (e.g. an upgrade notice). Dropping
+// them would also drop every nav of another feature pointing at them, so the
+// fallback could never be reached. Run BEFORE the role projection: it keeps
 // only targets that exist in the schema, so once the disabled screens/navs are
 // gone it also drops every action, redirect, nav and workspace member that
 // pointed at them. The one reference it does not resolve is a nav `parent`
 // pointing at a missing nav; that is pruned here.
+import { resolveScreenTargetQn } from "./boot-validator/screens.js";
 import { isToggleableFeature } from "./effective-features.js";
 import { isValidQn, qualifyEntityName } from "./qualified-name.js";
 // Sorted, so the result doubles as a stable cache key. The trial gate is
@@ -50,6 +56,28 @@ function collectOrphanedNavQns(features, removedNavQns) {
     }
     return orphaned;
 }
+// Fail-closed for the kept screens: the server gate rejects their handlers and
+// queries for the tenant, only the schema entry stays so the fallback can render.
+function screensKeptForFallback(feature) {
+    const qnOf = (screenId) => qualifyEntityName(feature.featureName, "screen", screenId);
+    const byQn = new Map(feature.screens.map((screen) => [qnOf(screen.id), screen]));
+    const kept = new Set();
+    const pending = feature.screens.filter((screen) => screen.fallback !== undefined);
+    for (const screen of pending)
+        kept.add(qnOf(screen.id));
+    while (pending.length > 0) {
+        const fallback = pending.pop()?.fallback;
+        if (fallback === undefined)
+            continue;
+        const targetQn = resolveScreenTargetQn(feature.featureName, fallback);
+        const target = byQn.get(targetQn);
+        if (target === undefined || kept.has(targetQn))
+            continue;
+        kept.add(targetQn);
+        pending.push(target);
+    }
+    return feature.screens.filter((screen) => kept.has(qnOf(screen.id)));
+}
 export function stripDisabledFeaturesFromAppSchema(schema, registry, disabledFeatureNames) {
     if (disabledFeatureNames.length === 0)
         return schema;
@@ -66,7 +94,7 @@ export function stripDisabledFeaturesFromAppSchema(schema, registry, disabledFea
     const features = schema.features.map((feature) => {
         if (disabled.has(feature.featureName)) {
             const { navs: _navs, contentCollections: _collections, workspaces: _ws, ...rest } = feature;
-            return { ...rest, screens: [] };
+            return { ...rest, screens: screensKeptForFallback(feature) };
         }
         if (orphanedNavQns.size === 0 || feature.navs === undefined)
             return feature;