@cosmicdrift/kumiko-framework 0.340.0 → 0.341.0

package/dist/api/index.d.ts

@@ -21,7 +21,8 @@ export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker.j
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
 export { type RequestContextData, requestContext, runAsDirectCallEntry, } from "./request-context.js";
 export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.js";
-export { DEFAULT_MAX_REQUEST_BYTES } from "./route-registrars.js";
+export type { MetricsRouteOptions } from "./route-registrars.js";
+export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";
 export type { KumikoServer, ServerOptions } from "./server.js";
 export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from "./server.js";

package/dist/api/index.js

@@ -12,7 +12,7 @@ export { isSafeLandingPath } from "./post-auth-landing.js";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
 export { requestContext, runAsDirectCallEntry, } from "./request-context.js";
 export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.js";
-export { DEFAULT_MAX_REQUEST_BYTES } from "./route-registrars.js";
+export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";
 export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from "./server.js";
 export { createSseBroker } from "./sse-broker.js";

package/dist/api/route-registrars.d.ts

@@ -1,7 +1,7 @@
-import type { Hono } from "hono";
+import { Hono } from "hono";
 import type { DbConnection } from "../db/connection.js";
 import type { Lifecycle } from "../lifecycle/index.js";
-import type { Meter } from "../observability/index.js";
+import type { Meter, PrometheusMeter } from "../observability/index.js";
 import type { EventConsumer } from "../pipeline/event-dispatcher.js";
 export declare const DEFAULT_MAX_REQUEST_BYTES = 1048576;
 export declare function registerBodyLimit(app: Hono, maxBytes: number): void;
@@ -9,7 +9,9 @@ export type MetricsRouteOptions = {
     readonly token?: string;
     readonly path?: string;
 };
+export declare function isPrometheusMeter(m: Meter): m is PrometheusMeter;
 export declare function registerMetricsRoute(app: Hono, meter: Meter, options: MetricsRouteOptions): void;
+export declare function createMetricsApp(meter: Meter, options: MetricsRouteOptions): Hono;
 export declare function registerVersionRoute(app: Hono): void;
 export type HealthRoutesOptions = {
     readonly lifecycle?: Lifecycle;

package/dist/api/route-registrars.js

@@ -3,6 +3,7 @@
 // branches. Every registrar takes the Hono app + whatever state it
 // actually reads — no monolithic `options` parameter, because these
 // helpers exist to make each step's dependencies visible at the call-site.
+import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
 import { serializeOpenMetrics } from "../observability/index.js";
 import { BODY_LIMIT_OPT_OUT_PATHS, Routes } from "./api-constants.js";
@@ -45,7 +46,7 @@ function constantTimeEqual(a, b) {
 // Type-guard: duck-types the meter on `snapshot()`. An alternative
 // Prometheus-compatible meter (future OTLP bridge) works without an
 // explicit union — if it exposes `snapshot()` it's serialisable.
-function isPrometheusMeter(m) {
+export function isPrometheusMeter(m) {
     return typeof m.snapshot === "function"; // @cast-boundary schema-walk
 }
 // Mount `/metrics` (or the caller-supplied path). Takes just the Meter —
@@ -73,6 +74,13 @@ export function registerMetricsRoute(app, meter, options) {
         return c.body(body);
     });
 }
+// Standalone fetch-handler serving only the scrape route — for HTTP-less
+// processes (worker pods) that expose /metrics on their own port.
+export function createMetricsApp(meter, options) {
+    const app = new Hono();
+    registerMetricsRoute(app, meter, options);
+    return app;
+}
 // --- /version ---------------------------------------------------------------
 // Anonymous endpoint that returns build-identity. Used by ops tooling
 // (prod-version.sh) and the Telegram deploy notification so nobody needs

package/dist/api/server.d.ts

@@ -1,3 +1,4 @@
+import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
 import { Hono } from "hono";
 import type { PgClient } from "../db/connection.js";
 import { type AppContext, type Registry, type RunIn, type WriteResult } from "../engine/types/index.js";
@@ -75,7 +76,7 @@ export type KumikoServer = {
     lifecycle?: Lifecycle;
     context: AppContext;
 };
-export declare function withFileProviderResolver(registry: Registry, context: AppContext): AppContext;
+export declare function withFileProviderResolver(registry: Registry, context: AppContext, cacheSync?: CacheSyncBus): AppContext;
 export declare function buildServer(options: ServerOptions): KumikoServer;
 export declare function makeDispatchSystemWrite(dispatcher: Dispatcher): (args: SystemDispatchArgs) => Promise<WriteResult>;
 export declare function makeDispatchSystemQuery(dispatcher: Dispatcher): (args: SystemDispatchArgs) => Promise<unknown>;

package/dist/api/server.js

@@ -19,7 +19,8 @@ import { createEventDispatcher } from "../pipeline/event-dispatcher.js";
 import { createLifecycleHooks } from "../pipeline/lifecycle-pipeline.js";
 import { createMultiStreamApplyContext } from "../pipeline/multi-stream-apply-context.js";
 import { createAccessInvalidationEventConsumer, createJobTriggerEventConsumer, createSearchEventConsumer, createSseBroadcastEventConsumer, } from "../pipeline/system-hooks.js";
-import { authEndpointRateLimit, createRateLimitResolver, globalIpRateLimit, } from "../rate-limit/index.js";
+import { authEndpointRateLimit, createPayloadDigest, createRateLimitResolver, globalIpRateLimit, httpRouteRateLimit, } from "../rate-limit/index.js";
+import { resolveCacheSyncBus } from "../redis/cache-sync-bus.js";
 import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-config.js";
 import { assertUnreachable, generateId } from "../utils/index.js";
 import { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
@@ -47,7 +48,7 @@ import { buildWebSocketSessionRevalidator, createWebSocketConnectionLimiter, has
 // per-tenant provider cache). Mirrors buildServer's own resolution exactly —
 // including NOT inventing a resolver when no `file-provider-*` plugin is
 // mounted, which is what keeps buildServer's boot-guard below able to fire.
-export function withFileProviderResolver(registry, context) {
+export function withFileProviderResolver(registry, context, cacheSync) {
     if (context._fileProviderResolver !== undefined)
         return context;
     if (registry.getExtensionUsages(EXT_FILE_PROVIDER).length === 0)
@@ -59,6 +60,7 @@ export function withFileProviderResolver(registry, context) {
             _configAccessorFactory: context._configAccessorFactory,
             secrets: context.secrets,
             db: context.db,
+            ...(cacheSync ? { cacheSync } : {}),
         }),
     };
 }
@@ -127,6 +129,10 @@ export function buildServer(options) {
         sseBroker = defaults.sseBroker;
         ownedRedisSseBroker = defaults.ownedRedisSseBroker;
     }
+    // Same decision as the SSE broker: an explicit dispatcherOptions value
+    // (incl. null = opt out) wins, otherwise REDIS_URL turns on cross-replica
+    // cache invalidation (no REDIS_URL = process-local bus).
+    const { bus: cacheSync, owned: ownedCacheSync } = resolveCacheSyncBus(options.dispatcherOptions?.cacheSync);
     // Resolve the per-process instance identifier. Prefer explicit
     // ServerOptions.instanceId (tests, deliberate wiring), fall back to the
     // deploy-env variable, finally a boot-time UUID. Validator rejects the
@@ -184,7 +190,7 @@ export function buildServer(options) {
     // resolver once (when a provider plugin is mounted) — the dispatcher uses it
     // to materialise `ctx.files`, the upload routes + MSP-applies share it. The
     // resolver reads config + the s3.secretAccessKey secret under SYSTEM identity.
-    const contextWithFiles = withFileProviderResolver(options.registry, options.context);
+    const contextWithFiles = withFileProviderResolver(options.registry, options.context, cacheSync);
     const fileProviderResolver = contextWithFiles._fileProviderResolver;
     // Auto-wire the rate-limit resolver, but ONLY when at least one
     // handler actually declared a rateLimit option. Apps that don't use
@@ -197,13 +203,22 @@ export function buildServer(options) {
     // both share the same instance to avoid duplicate Lua-script registration.
     const wantsL3 = options.registry.hasRateLimitedHandler();
     const wantsL1L2 = options.rateLimit?.global !== undefined || options.rateLimit?.auth !== undefined;
-    const wantsResolver = wantsL3 || wantsL1L2;
+    const wantsHttpRouteLimit = [...options.registry.features.values()].some((feature) => Object.values(feature.httpRoutes).some((route) => route.rateLimit !== undefined));
+    const wantsResolver = wantsL3 || wantsL1L2 || wantsHttpRouteLimit;
+    // Master for the payload-bucket HMAC: the current signing secret (the
+    // keyring's signKid for rotation setups). buildServer always has one, so
+    // the digest is available whenever a handler declares additionalRateLimits.
+    const payloadDigest = createPayloadDigest(typeof options.jwtSecret === "string"
+        ? options.jwtSecret
+        : (options.jwtSecret.keys[options.jwtSecret.signKid] ?? ""));
     const rateLimitResolver = options.context.rateLimit ??
         (wrappedRedis && wantsResolver ? createRateLimitResolver({ redis: wrappedRedis }) : undefined);
     const contextWithObservability = {
         ...contextWithFiles,
         ...(wrappedRedis ? { redis: wrappedRedis } : {}),
         ...(rateLimitResolver ? { rateLimit: rateLimitResolver } : {}),
+        _rateLimitPayloadDigest: payloadDigest,
+        ...(cacheSync ? { cacheSync } : {}),
         // Propagate the feature-toggle resolver to the context so the event-
         // dispatcher (and any future context-reading consumer) sees the same
         // source as the command dispatcher's handler-gate. Options take
@@ -220,6 +235,7 @@ export function buildServer(options) {
         ...options.dispatcherOptions,
         lifecycle,
         sseBroker,
+        cacheSync: cacheSync ?? null,
         ...(options.auth ? { membershipQuery: options.auth.membershipQuery } : {}),
     });
     // Async event-dispatcher — the replacement for the old transactional
@@ -379,6 +395,12 @@ export function buildServer(options) {
             await broker.close();
         });
     }
+    if (options.lifecycle && ownedCacheSync) {
+        const bus = ownedCacheSync;
+        options.lifecycle.registerShutdownHook("cacheSync", async () => {
+            await bus.close();
+        });
+    }
     const app = new Hono();
     // Sub-apps mounted via app.route() without their own handler inherit this one.
     app.onError(handleUncaughtRouteError);
@@ -657,7 +679,23 @@ export function buildServer(options) {
                 systemQuery: makeSystemQuery(c, dispatcher, clientIpResolver),
                 clientIp: clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
             });
-            mountHonoRoute(app, route.method, route.path, honoHandler, route.anonymous ? [] : sessionOnlyHttpRouteGuards);
+            // Without a resolver (no Redis in the context — dev/test stacks) the
+            // declared limit is skipped rather than failing the boot of every app
+            // that mounts a bundled feature whose routes carry a default limit.
+            const routeLimit = route.rateLimit && rateLimitResolver
+                ? [
+                    httpRouteRateLimit({
+                        resolver: rateLimitResolver,
+                        rateLimit: route.rateLimit,
+                        routeKey: `${route.method} ${route.path}`,
+                        clientIpResolver,
+                    }),
+                ]
+                : [];
+            mountHonoRoute(app, route.method, route.path, honoHandler, [
+                ...routeLimit,
+                ...(route.anonymous ? [] : sessionOnlyHttpRouteGuards),
+            ]);
         }
     }
     // r.webSocketRoute — GET routes under /api/ws/*, so the jwt/pat/rate-limit

package/dist/db/queries/shadow-swap.d.ts

@@ -1,3 +1,4 @@
+import type { ProjectionRowIdOf } from "@cosmicdrift/kumiko-types/projection";
 import type { DbConnection, DbTx } from "../connection.js";
 import type { EntityTableMeta } from "../entity-table-meta.js";
 import { type AnyDb } from "../query.js";
@@ -8,7 +9,7 @@ export declare function assertLiveColumnsMatchMeta(db: DbConnection | DbTx, meta
 export declare function assertLiveTableHasNoRowLevelSecurity(tx: AnyDb, tableName: string, projectionName?: string): Promise<void>;
 export declare function buildShadowTable(tx: AnyDb, meta: EntityTableMeta): Promise<void>;
 export declare function fenceLiveTable(tx: AnyDb, tableName: string, lockTimeoutMs: number): Promise<void>;
-export declare function assertNoUnreachableLiveRows(tx: AnyDb, projectionName: string, tableName: string, aggregateTypes: readonly string[]): Promise<void>;
+export declare function assertNoUnreachableLiveRows(tx: AnyDb, projectionName: string, tableName: string, aggregateTypes: readonly string[], derivedRowIds?: Readonly<Record<string, ProjectionRowIdOf>>): Promise<void>;
 export declare function assertNoBlindIndexLoss(tx: AnyDb, tableName: string, meta: EntityTableMeta, projectionName: string): Promise<void>;
 export type ColumnDriftResult = {
     readonly rowCount: number;

package/dist/db/queries/shadow-swap.js

@@ -17,6 +17,7 @@
 // Boundary: the shadow table is rebuilt from EntityTableMeta, so any index NOT
 // expressed in meta (hand-added in a migration) is not reconstructed, and a
 // partial index whose WHERE the renderer can't express is rejected up-front.
+import { isUuid, parseTenantId } from "@cosmicdrift/kumiko-types/identifiers";
 import { configuredBlindIndexKey } from "../../crypto/index.js";
 import { asEntityTableMeta, asRawClient } from "../query.js";
 import { renderTableDdl } from "../render-ddl.js";
@@ -178,19 +179,80 @@ const UNREACHABLE_SAMPLE_LIMIT = 20;
 //
 // Implicit projections only (caller-gated). aggregate_id and the entity id are
 // both uuid, so the anti-join probes the events index without a cast.
-export async function assertNoUnreachableLiveRows(tx, projectionName, tableName, aggregateTypes) {
+//
+// Source streams whose rows are keyed by a DERIVED id (r.extendEntityProjection
+// `rowIdOf`, e.g. tenant-salted) cannot be matched on aggregate_id: their
+// distinct (tenant, aggregate) pairs are mapped through rowIdOf into a temp
+// table, and a live row is backed when its id is in that set. The guard stays
+// strict — a row keyed by the raw aggregate id of a derived stream is a ghost.
+const DERIVED_ROW_ID_BATCH_SIZE = 5000;
+const DERIVED_ROW_ID_TABLE = "pg_temp.kumiko_derived_row_ids";
+async function fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf) {
+    let cursor;
+    for (;;) {
+        const page = await raw.unsafe(`SELECT DISTINCT "tenant_id"::text AS tenant_id, "aggregate_id"::text AS aggregate_id
+         FROM "kumiko_events"
+        WHERE "aggregate_type" = $1
+          ${cursor ? `AND ("tenant_id", "aggregate_id") > ($2::uuid, $3::uuid)` : ""}
+        ORDER BY "tenant_id", "aggregate_id"
+        LIMIT ${DERIVED_ROW_ID_BATCH_SIZE}`, cursor ? [aggregateType, cursor.tenant_id, cursor.aggregate_id] : [aggregateType]);
+        // skip: keyset exhausted — every source event of this type has been mapped
+        if (page.length === 0)
+            return;
+        const derivedIds = page.map((row) => {
+            const tenantId = parseTenantId(row.tenant_id);
+            if (tenantId === null) {
+                throw new Error(`projection-rebuild "${projectionName}": event of aggregate type "${aggregateType}" ` +
+                    `carries a non-uuid tenant_id "${row.tenant_id}".`);
+            }
+            const derived = rowIdOf({ tenantId, aggregateId: row.aggregate_id });
+            if (!isUuid(derived)) {
+                throw new Error(`projection-rebuild "${projectionName}": rowIdOf for aggregate type "${aggregateType}" ` +
+                    `returned "${String(derived)}", which is not a uuid (aggregate ${row.aggregate_id}).`);
+            }
+            return derived;
+        });
+        await raw.unsafe(`INSERT INTO ${DERIVED_ROW_ID_TABLE} ("id") SELECT unnest($1::uuid[]) ON CONFLICT DO NOTHING`, [derivedIds]);
+        // skip: a short page is the last one
+        if (page.length < DERIVED_ROW_ID_BATCH_SIZE)
+            return;
+        cursor = page[page.length - 1];
+    }
+}
+export async function assertNoUnreachableLiveRows(tx, projectionName, tableName, aggregateTypes, derivedRowIds = {}) {
     // skip: no source streams → no events could back any row anyway; a rebuild
     // of a subscription-less projection swaps an empty shadow (handled upstream).
     if (aggregateTypes.length === 0)
         return;
     const raw = asRawClient(tx);
     const t = quoteTableIdent(tableName);
+    const derivedTypes = aggregateTypes.filter((type) => derivedRowIds[type] !== undefined);
+    const directTypes = aggregateTypes.filter((type) => derivedRowIds[type] === undefined);
+    if (derivedTypes.length > 0) {
+        // search_path points at the shadow schema here; pg_temp is addressed explicitly.
+        await raw.unsafe(`CREATE TEMP TABLE IF NOT EXISTS kumiko_derived_row_ids ("id" uuid PRIMARY KEY) ON COMMIT DROP`);
+        await raw.unsafe(`TRUNCATE ${DERIVED_ROW_ID_TABLE}`);
+        for (const aggregateType of derivedTypes) {
+            const rowIdOf = derivedRowIds[aggregateType];
+            // skip: filtered by derivedTypes above, narrows the Record lookup for the compiler
+            if (rowIdOf === undefined)
+                continue;
+            await fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf);
+        }
+    }
+    const unbackedClauses = [];
+    if (directTypes.length > 0) {
+        unbackedClauses.push(`NOT EXISTS (
+         SELECT 1 FROM "kumiko_events" e
+          WHERE e."aggregate_id" = l."id" AND e."aggregate_type" = ANY($1::text[])
+       )`);
+    }
+    if (derivedTypes.length > 0) {
+        unbackedClauses.push(`NOT EXISTS (SELECT 1 FROM ${DERIVED_ROW_ID_TABLE} d WHERE d."id" = l."id")`);
+    }
     const ghosts = await raw.unsafe(`SELECT l."id" FROM public.${t} l
-     WHERE NOT EXISTS (
-       SELECT 1 FROM "kumiko_events" e
-        WHERE e."aggregate_id" = l."id" AND e."aggregate_type" = ANY($1::text[])
-     )
-     LIMIT ${UNREACHABLE_SAMPLE_LIMIT}`, [aggregateTypes]);
+     WHERE ${unbackedClauses.join(" AND ")}
+     LIMIT ${UNREACHABLE_SAMPLE_LIMIT}`, directTypes.length > 0 ? [directTypes] : []);
     // skip: every live row has a backing event — nothing unreachable, swap is safe
     if (ghosts.length === 0)
         return;
@@ -200,7 +262,8 @@ export async function assertNoUnreachableLiveRows(tx, projectionName, tableName,
         `event in the projection's source streams and cannot be reconstructed by replay — the swap ` +
         `would silently drop them (ids: ${ids.join(", ")}). A handler direct-inserted these rows ` +
         `without emitting a .created event. Fix: register the table with r.storeTable(meta, ` +
-        `{ reason }) to opt out of rebuild, or emit the missing events. See ` +
+        `{ reason }) to opt out of rebuild, or emit the missing events. Rows keyed by an id ` +
+        `derived from the source event declare \`rowIdOf\` on r.extendEntityProjection. See ` +
         `docs/reference/entity-write-patterns.md. Rebuild aborted; live table untouched.`);
 }
 // The bidx column is schema-driven, not key-driven: it exists NULL in a

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)