@cosmicdrift/kumiko-framework 0.328.1 → 0.330.0

package/dist/api/index.d.ts

@@ -29,4 +29,4 @@ export { createSseBroker } from "./sse-broker.js";
 export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route.js";
 export { generateToken } from "./tokens.js";
 export type { KumikoServeEnv, KumikoServerWebSocket, KumikoWebSocketData, WebSocketUpgradeServer, } from "./websocket-route.js";
-export { createKumikoWebSocketHandler, isWebSocketUpgradeRequest, kumikoWebSocketHandler, WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_HEARTBEAT_INTERVAL_MS, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_REVALIDATION_FAILURE_LIMIT, WEBSOCKET_ROUTE_PATH_PREFIX, } from "./websocket-route.js";
+export { createKumikoWebSocketHandler, isWebSocketUpgradeRequest, kumikoWebSocketHandler, WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_HEARTBEAT_INTERVAL_MS, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES, WEBSOCKET_REVALIDATION_FAILURE_LIMIT, WEBSOCKET_ROUTE_PATH_PREFIX, } from "./websocket-route.js";

package/dist/api/index.js

@@ -17,4 +17,4 @@ export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from ".
 export { createSseBroker } from "./sse-broker.js";
 export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route.js";
 export { generateToken } from "./tokens.js";
-export { createKumikoWebSocketHandler, isWebSocketUpgradeRequest, kumikoWebSocketHandler, WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_HEARTBEAT_INTERVAL_MS, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_REVALIDATION_FAILURE_LIMIT, WEBSOCKET_ROUTE_PATH_PREFIX, } from "./websocket-route.js";
+export { createKumikoWebSocketHandler, isWebSocketUpgradeRequest, kumikoWebSocketHandler, WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_HEARTBEAT_INTERVAL_MS, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES, WEBSOCKET_REVALIDATION_FAILURE_LIMIT, WEBSOCKET_ROUTE_PATH_PREFIX, } from "./websocket-route.js";

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

@@ -4,6 +4,7 @@ import { type AuthSessionChecker, type TenantLifecycleStatusResolver } from "./a
 import { type RequestContextData } from "./request-context.js";
 export { WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_DEFAULT_MAX_MESSAGE_BYTES, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_ROUTE_PATH_PREFIX, };
 export declare const WEBSOCKET_HEARTBEAT_INTERVAL_MS = 25000;
+export declare const WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES: number;
 export declare const WEBSOCKET_REVALIDATION_FAILURE_LIMIT = 3;
 export type KumikoWebSocketData = {
     readonly handlers: WebSocketSessionHandlers;

package/dist/api/websocket-route.js

@@ -9,6 +9,9 @@ const CLOSE_POLICY_VIOLATION = 1008;
 const CLOSE_MESSAGE_TOO_BIG = 1009;
 const CLOSE_INTERNAL_ERROR = 1011;
 const CLOSE_TRY_AGAIN_LATER = 1013;
+// Frames queue behind a slow onOpen or onMessage; without a byte cap a client
+// could grow that queue unbounded.
+export const WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES = 1024 * 1024;
 // Consecutive failed session-store checks before a socket is closed: rides out a
 // short store blip, but a socket must not stay unverified forever.
 export const WEBSOCKET_REVALIDATION_FAILURE_LIMIT = 3;
@@ -87,6 +90,7 @@ function stateOf(ws) {
             revalidating: false,
             chain: Promise.resolve(),
             closed: false,
+            pendingMessageBytes: 0,
             controller: new AbortController(),
         };
         connectionStates.set(ws.data, state);
@@ -112,22 +116,25 @@ function runInRequestContext(ws, run) {
     const { requestContextData } = ws.data;
     return requestContextData ? requestContext.run(requestContextData, run) : run();
 }
-function enqueue(ws, run) {
+function enqueue(ws, run, onSettled) {
     const state = stateOf(ws);
     // skip: the socket is gone, nothing may start after close
     if (state.closed)
         return;
     const step = async () => {
-        // skip: queued behind a slower handler and the socket closed meanwhile
-        if (state.closed)
-            return;
         try {
+            // skip: queued behind a slower handler and the socket closed meanwhile
+            if (state.closed)
+                return;
             await run();
         }
         catch (error) {
             reportHandlerFailure(error);
             ws.close(CLOSE_INTERNAL_ERROR, "internal error");
         }
+        finally {
+            onSettled?.();
+        }
     };
     state.chain = state.chain.then(() => runInRequestContext(ws, step));
 }
@@ -208,9 +215,33 @@ export function createKumikoWebSocketHandler(options = {}) {
                 });
                 return;
             }
+            const state = stateOf(ws);
+            // skip: overflowed or closed socket, late frames are dropped
+            if (state.closed)
+                return;
+            state.pendingMessageBytes += byteLength;
+            const pendingLimit = Math.max(WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES, ws.data.maxMessageBytes);
+            if (state.pendingMessageBytes > pendingLimit) {
+                // Marks the socket closed right away so already-queued frames never start.
+                state.closed = true;
+                ws.close(CLOSE_TRY_AGAIN_LATER, "try again later");
+                log.warn("websocket pending buffer over cap", {
+                    pendingBytes: state.pendingMessageBytes,
+                    limitBytes: pendingLimit,
+                });
+                return;
+            }
             const { onMessage } = ws.data.handlers;
-            if (onMessage)
-                enqueue(ws, () => onMessage(toMessageData(message), toConnection(ws)));
+            if (onMessage) {
+                // Copy now: queued behind a slow handler, Bun may have reused the buffer by then.
+                const data = toMessageData(message);
+                enqueue(ws, () => onMessage(data, toConnection(ws)), () => {
+                    state.pendingMessageBytes -= byteLength;
+                });
+            }
+            else {
+                state.pendingMessageBytes -= byteLength;
+            }
         },
         close(ws, code, reason) {
             const state = stateOf(ws);

package/dist/bun-db/connection.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="bun-types" preserve="true" />
 import type { PgListenClient } from "@cosmicdrift/kumiko-types/db-connection";
 export type { PgListenClient };
 export type BunDbConnection = InstanceType<typeof Bun.SQL>;

package/dist/bun-db/connection.js

@@ -1,3 +1,4 @@
+/// <reference types="bun-types" preserve="true" />
 // Bun.SQL-basierter Connection-Layer (KEIN drizzle). Production-Pfad
 // nach drizzle-removal. Erstellt parallel zum legacy `db/connection.ts`
 // — apps migrieren schritt-für-schritt, alte Datei weg sobald 0 Konsumenten.

package/dist/bun-db/index.d.ts

@@ -1,4 +1,4 @@
 export type { BunDbConnection, BunDbConnectionOptions, BunDbRunner, BunDbTx, PgListenClient, } from "./connection.js";
 export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection.js";
 export type { SelectOptions, TableInfo, WhereObject, WhereOperator, WhereValue } from "./query.js";
-export { asEntityTableMeta, asRawClient, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, runInSavepoint, runInSavepointIfSupported, selectMany, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";
+export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, isTimestamptzType, runInSavepoint, runInSavepointIfSupported, selectMany, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";

package/dist/bun-db/index.js

@@ -1,4 +1,4 @@
 // bun-db: Bun.sql-basierte DB-API ohne drizzle.
 // Production-Pfad nach drizzle-removal.
 export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection.js";
-export { asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOne, runInSavepoint, runInSavepointIfSupported, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";
+export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOne, isTimestamptzType, runInSavepoint, runInSavepointIfSupported, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";

package/dist/bun-db/query.d.ts

@@ -1,3 +1,4 @@
+import type { AggregateRow, AggregateSpec } from "@cosmicdrift/kumiko-types/aggregate-types";
 import type { SelectOptions, WhereObject } from "@cosmicdrift/kumiko-types/where-clause-types";
 import type { EntityTableMeta } from "../db/entity-table-meta.js";
 import { type NotExecutorOnly } from "../db/table-builder.js";
@@ -51,6 +52,8 @@ export type DeleteManyBatchedResult = {
     readonly batches: number;
 };
 export declare function countWhere(db: AnyDb, table: TableLike, where?: WhereObject): Promise<number>;
+export declare function isTimestamptzType(pgType: string | undefined): boolean;
+export declare function aggregateWhere(db: AnyDb, table: TableLike, spec: AggregateSpec, where?: WhereObject): Promise<readonly AggregateRow[]>;
 export declare function upsertOnConflict<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
 export declare function upsertByPk<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, updateOnConflict?: Record<string, unknown>): Promise<TRow | undefined>;
 export type IncrementCounterOptions = {

package/dist/bun-db/query.js

@@ -989,6 +989,105 @@ export async function countWhere(db, table, where = {}) {
     const rows = (await unsafeReadRetrying(db, sqlText, values));
     return rows[0]?.count ?? 0;
 }
+const AGGREGATE_BUCKET_UNITS = ["hour", "day"];
+const AGGREGATE_ORDER_DIRECTIONS = ["asc", "desc"];
+function requireAggregateColumn(info, field, role) {
+    if (!info.hasColumn(field)) {
+        throw new Error(`aggregateWhere: ${role} "${field}" is not a column of ${info.name}`);
+    }
+    return quoteIdent(info.columnOf(field));
+}
+export function isTimestamptzType(pgType) {
+    return pgType === "timestamptz" || pgType === "timestamptz(3)";
+}
+function aggregateKeyOf(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean")
+        return raw;
+    if (typeof raw === "bigint")
+        return Number(raw);
+    if (raw instanceof Date)
+        return raw.toISOString();
+    return String(raw);
+}
+function aggregateMeasureSql(info, measure) {
+    switch (measure.fn) {
+        case "count":
+            return "COUNT(*)";
+        case "countDistinct":
+            return `COUNT(DISTINCT ${requireAggregateColumn(info, measure.field, "measure field")})`;
+        case "sum":
+            return `COALESCE(SUM(${requireAggregateColumn(info, measure.field, "measure field")}), 0)`;
+        case "avg":
+            return `AVG(${requireAggregateColumn(info, measure.field, "measure field")})`;
+        default:
+            throw new Error(`aggregateWhere: unknown measure fn "${String(measure.fn)}"`);
+    }
+}
+function aggregateDimensionSql(info, dimension, index, params) {
+    const column = requireAggregateColumn(info, dimension.field, "groupBy field");
+    if (!("bucket" in dimension))
+        return `${column} AS k${index}`;
+    if (!AGGREGATE_BUCKET_UNITS.includes(dimension.bucket)) {
+        throw new Error(`aggregateWhere: unknown bucket "${String(dimension.bucket)}"`);
+    }
+    if (!isTimestamptzType(info.pgTypeOf(info.columnOf(dimension.field)))) {
+        throw new Error(`aggregateWhere: bucket on "${dimension.field}" requires a timestamptz column`);
+    }
+    params.push(dimension.timeZone);
+    return `(EXTRACT(EPOCH FROM date_trunc('${dimension.bucket}', ${column}, $${params.length}::text)) * 1000)::float8 AS k${index}`;
+}
+function assertValidAggregateLimits(spec) {
+    if (spec.limit !== undefined && (!Number.isInteger(spec.limit) || spec.limit < 0)) {
+        throw new Error(`aggregateWhere: limit must be a non-negative integer, got ${spec.limit}`);
+    }
+    if (spec.orderByValue !== undefined && !AGGREGATE_ORDER_DIRECTIONS.includes(spec.orderByValue)) {
+        throw new Error(`aggregateWhere: unknown orderByValue "${String(spec.orderByValue)}"`);
+    }
+}
+function aggregateGroupOrderLimitSql(spec, dimensionCount) {
+    let sqlText = "";
+    if (dimensionCount > 0) {
+        const positions = Array.from({ length: dimensionCount }, (_, index) => String(index + 1));
+        sqlText += ` GROUP BY ${positions.join(", ")}`;
+        const orderParts = spec.orderByValue === undefined
+            ? positions
+            : [`${dimensionCount + 1} ${spec.orderByValue === "desc" ? "DESC" : "ASC"}`, ...positions];
+        sqlText += ` ORDER BY ${orderParts.join(", ")}`;
+    }
+    if (spec.limit !== undefined)
+        sqlText += ` LIMIT ${spec.limit}`;
+    return sqlText;
+}
+export async function aggregateWhere(db, table, spec, where = {}) {
+    const scoped = tenantDbDelegate(db);
+    if (scoped) {
+        return scoped.aggregate(table, spec, where);
+    }
+    const info = extractTableInfo(table);
+    const params = [];
+    const measureSql = aggregateMeasureSql(info, spec.measure);
+    const dimensions = spec.groupBy ?? [];
+    const dimensionSql = dimensions.map((dimension, index) => aggregateDimensionSql(info, dimension, index, params));
+    assertValidAggregateLimits(spec);
+    const selectList = [...dimensionSql, `(${measureSql})::float8 AS value`].join(", ");
+    let sqlText = `SELECT ${selectList} FROM ${quoteIdent(info.name)}`;
+    if (Object.keys(where).length > 0) {
+        const w = buildWhereClause(info, where, params.length + 1);
+        sqlText += ` WHERE ${w.sqlText}`;
+        params.push(...w.values);
+    }
+    sqlText += aggregateGroupOrderLimitSql(spec, dimensions.length);
+    const raw = (await unsafeReadRetrying(db, sqlText, params));
+    return raw.map((row) => {
+        const value = row["value"];
+        return {
+            keys: dimensions.map((_, index) => aggregateKeyOf(row[`k${index}`])),
+            value: value === null || value === undefined ? null : Number(value),
+        };
+    });
+}
 // biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function upsertOnConflict(db, table, values, options) {
     assertNotTenantScoped(db, "upsertOnConflict");

package/dist/db/index.d.ts

@@ -26,7 +26,7 @@ export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation,
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
 export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.js";
 export type { SelectOptions, WhereObject, WhereValue } from "./query-api.js";
-export { asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "./query-api.js";
+export { aggregateWhere, asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "./query-api.js";
 export { readRebuildMarker, rebuildTablesFromDiff, writeRebuildMarker, } from "./rebuild-marker.js";
 export { seedReferenceData } from "./reference-data.js";
 export { renderTableDdl, renderTablesDdl } from "./render-ddl.js";

package/dist/db/index.js

@@ -19,7 +19,7 @@ export { flattenMoney, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.
 export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation, } from "./pg-error.js";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
 export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.js";
-export { asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "./query-api.js";
+export { aggregateWhere, asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "./query-api.js";
 export { readRebuildMarker, rebuildTablesFromDiff, writeRebuildMarker, } from "./rebuild-marker.js";
 export { seedReferenceData } from "./reference-data.js";
 export { renderTableDdl, renderTablesDdl } from "./render-ddl.js";

package/dist/db/query-api.d.ts

@@ -1,2 +1,2 @@
 export type { SelectOptions, WhereObject, WhereOperator, WhereValue, } from "../db/query.js";
-export { asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "../db/query.js";
+export { aggregateWhere, asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "../db/query.js";

package/dist/db/query-api.js

@@ -3,4 +3,4 @@
 // damit existing imports `@cosmicdrift/kumiko-framework/db` weiterhin
 // funktionieren während wir die Callers schrittweise auf den direkten
 // bun-db-Import migrieren.
-export { asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "../db/query.js";
+export { aggregateWhere, asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "../db/query.js";

package/dist/db/query.d.ts

@@ -1 +1 @@
-export { type AnyDb, asEntityTableMeta, asRawClient, coerceRow, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, type OrderByClause, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, type SelectOptions, selectMany, type TableInfo, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, type WhereObject, type WhereOperator, type WhereValue, } from "../bun-db/query.js";
+export { type AnyDb, aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, type OrderByClause, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, type SelectOptions, selectMany, type TableInfo, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, type WhereObject, type WhereOperator, type WhereValue, } from "../bun-db/query.js";

package/dist/db/query.js

@@ -1,3 +1,3 @@
 // Provider-neutrale Query-API. Re-exported aus bun-db/query.
 // Alle Consumer importieren von hier, nicht direkt aus bun-db/.
-export { asEntityTableMeta, asRawClient, coerceRow, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOne, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "../bun-db/query.js";
+export { aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOne, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "../bun-db/query.js";

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

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 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.js";

package/dist/db/tenant-db.js

@@ -1,6 +1,6 @@
 import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
-import { asEntityTableMeta, asRawClient, countWhere as bunCountWhere, deleteMany as bunDeleteMany, fetchOne as bunFetchOne, insertOne as bunInsertOne, selectMany as bunSelectMany, updateMany as bunUpdateMany, runInNewTransaction, } from "../db/query.js";
+import { asEntityTableMeta, asRawClient, aggregateWhere as bunAggregateWhere, countWhere as bunCountWhere, deleteMany as bunDeleteMany, fetchOne as bunFetchOne, insertOne as bunInsertOne, selectMany as bunSelectMany, updateMany as bunUpdateMany, runInNewTransaction, } from "../db/query.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
 import { fallbackEscapeHatchReporter } from "../observability/escape-hatch-report.js";
@@ -443,6 +443,10 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             const filter = readWhere(table, where);
             return withDbSpan("select", table, async () => bunCountWhere(db, table, filter));
         },
+        aggregate(table, spec, where) {
+            const filter = readWhere(table, where);
+            return withDbSpan("select", table, async () => bunAggregateWhere(db, table, spec, filter));
+        },
         insertOne(table, values) {
             if (mode === "tenant" &&
                 hasTenantColumn(table) &&

package/dist/engine/boot-validator/screens.js

@@ -1210,6 +1210,12 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                         `is not sortable. Set sortable: true on the field definition or pick another field.`);
                 }
             }
+            if (screen.createScreen !== undefined &&
+                !Object.hasOwn(feature.screens, screen.createScreen)) {
+                throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityList) createScreen ` +
+                    `"${screen.createScreen}" does not resolve to a registered screen in this feature. ` +
+                    `Known screens in this feature: ${Object.keys(feature.screens).sort().join(", ") || "(none)"}.`);
+            }
             // Screen-Filter (Tier 2.7c) — drei Layer Author-Code-Check:
             //   1) Field existiert auf der Entity (Tippfehler = leere Liste
             //      statt Crash; Boot-Fail ist deutlich besser).
@@ -1402,6 +1408,11 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     }
                 }
             }
+            if (screen.recordTitleField !== undefined && !fieldNames.has(screen.recordTitleField)) {
+                throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityEdit) recordTitleField ` +
+                    `"${screen.recordTitleField}" is not a field of entity "${screen.entity}" ` +
+                    `(known: ${[...fieldNames].sort().join(", ")}).`);
+            }
             if (screen.redirect !== undefined) {
                 validateRedirectTarget(feature, screenId, "entityEdit", screen.redirect, allScreenQns);
             }
@@ -1441,6 +1452,33 @@ function validateDashboardScreen(featureName, screenId, screen, featureMap) {
     if (screen.filter !== undefined) {
         validateDashboardFilterDefinition(featureName, screenId, screen.filter);
     }
+    if (screen.timeRange !== undefined) {
+        validateDashboardTimeRange(featureName, screenId, screen.timeRange, screen.filter?.id);
+    }
+}
+function validateDashboardTimeRange(featureName, screenId, timeRange, filterId) {
+    const prefix = `[Feature ${featureName}] Screen "${screenId}" (dashboard) timeRange`;
+    if (timeRange.id.length === 0)
+        throw new Error(`${prefix} has an empty id.`);
+    if (timeRange.id === filterId) {
+        throw new Error(`${prefix} id "${timeRange.id}" collides with the filter id — both live in the URL search params.`);
+    }
+    if (timeRange.options.length === 0) {
+        throw new Error(`${prefix}.options is empty — declare at least one option.`);
+    }
+    const values = new Set();
+    for (const option of timeRange.options) {
+        if (option.value.length === 0 || option.label.length === 0) {
+            throw new Error(`${prefix} option needs a non-empty value and label.`);
+        }
+        if (values.has(option.value)) {
+            throw new Error(`${prefix}.options has duplicate value "${option.value}".`);
+        }
+        values.add(option.value);
+    }
+    if (!values.has(timeRange.default)) {
+        throw new Error(`${prefix}.default "${timeRange.default}" is not among the options (${[...values].join(", ")}).`);
+    }
 }
 const EMBEDDABLE_SCREEN_TYPES = new Set([
     "projectionList",
@@ -1491,6 +1529,12 @@ function validateDashboardQueryPanel(featureName, screenId, panel) {
     if (!panel.query || typeof panel.query !== "string") {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has empty or non-string query.`);
     }
+    if ("span" in panel &&
+        panel.span !== undefined &&
+        panel.span !== "half" &&
+        panel.span !== "full") {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has span "${String(panel.span)}" — expected "half" or "full".`);
+    }
     if (panel.kind === "stat" && panel.valueField.length === 0) {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-panel "${panel.id}" has empty valueField.`);
     }

package/dist/engine/build-app-schema.js

@@ -426,6 +426,9 @@ function projectField(fieldDef) {
     const unit = def["unit"];
     if (typeof unit === "string" || (isPlainObject(unit) && typeof unit["field"] === "string"))
         out["unit"] = unit;
+    // number/decimal/bigInt: `false` drops thousands separators (e.g. a year).
+    if (typeof def["grouping"] === "boolean")
+        out["grouping"] = def["grouping"];
     // text: "password" masks the input and blocks URL prefill in the renderer.
     if (typeof def["format"] === "string")
         out["format"] = def["format"];

package/dist/event-store/admin-api.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import type { DbRunner } from "../db/index.js";
 import type { TenantId } from "../engine/types/index.js";
 import type { EventMetadata } from "./event-store.js";

package/dist/event-store/admin-api.js

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 // Event-Store Admin-API — Marten-Bypass für Legacy-Daten-Importe.
 // Spec + Verhalten: docs/plans/features/event-store-admin-api.md
 //

package/dist/event-store/event-store.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import { type EventMetadata, type StoredEvent } from "@cosmicdrift/kumiko-types/event-store-types";
 import type { DbRunner } from "../db/index.js";
 import type { TenantId } from "../engine/types/index.js";

package/dist/event-store/event-store.js

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import { isPersonalDataGated, UNATTRIBUTED_ORIGIN, } from "@cosmicdrift/kumiko-types/event-store-types";
 // Value-only import, aliased to avoid shadowing the ambient global
 // `Temporal` TYPE this file's other Temporal.Instant annotations resolve

package/dist/event-store/row-to-stored-event.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import type { TenantId } from "../engine/types/index.js";
 import type { EventMetadata, StoredEvent } from "./event-store.js";
 type EventRow = {

package/dist/event-store/snapshot.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import type { LoadAggregateWithSnapshotOptions, LoadAggregateWithSnapshotResult, SnapshotReducer } from "@cosmicdrift/kumiko-types/snapshot-types";
 import type { DbConnection, DbRunner } from "../db/connection.js";
 import type { TenantId } from "../engine/types/index.js";

package/dist/event-store/snapshot.js

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 // sql now comes from native dialect
 import { index, instant, integer, jsonb, table as pgTable, primaryKey, sql, text, uuid, } from "../db/dialect.js";
 import { ensureSnapshotVersionColumn, upsertSnapshot } from "../db/queries/event-store.js";

package/dist/i18n/required-surface-keys.js

@@ -57,12 +57,25 @@ function pushDashboardScreenKeys(out, dashboard) {
         pushDashboardPanelKeys(out, panel);
     if (dashboard.filter !== undefined)
         pushDashboardFilterKeys(out, dashboard.filter);
+    for (const option of dashboard.timeRange?.options ?? [])
+        pushKey(out, option.label);
+    pushKey(out, dashboard.scope?.badge);
+    pushKey(out, dashboard.scope?.notice);
 }
 function pushDashboardPanelKeys(out, panel) {
     // skip: custom-Panel übersetzt sich selbst, kein Key hier
     if (panel.kind === "custom")
         return;
     pushKey(out, panel.label);
+    if (panel.kind === "chart")
+        pushKey(out, panel.subtitle);
+    if (panel.kind === "chart" ||
+        panel.kind === "list" ||
+        panel.kind === "feed" ||
+        panel.kind === "progress-list") {
+        pushKey(out, panel.emptyLabel);
+        pushKey(out, panel.emptyHint);
+    }
     if (panel.kind === "stat-group") {
         for (const stat of panel.stats)
             pushKey(out, stat.label);
@@ -74,8 +87,6 @@ function pushDashboardPanelKeys(out, panel) {
                 pushKey(out, normalized.label);
         }
     }
-    if (panel.kind === "feed" && panel.emptyLabel !== undefined)
-        pushKey(out, panel.emptyLabel);
 }
 function pushDashboardFilterKeys(out, filter) {
     pushKey(out, filter.label);

package/dist/jobs/job-runner.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import { type AppContext, type DispatchWriteRef, type JobRunIn, type JobTriggerEvent, type Registry, type SessionUser, type TenantId } from "../engine/types/index.js";
 /**
  * BullMQ job ids are `repeat:<schedulerId>:<millis>`. Colons inside the

package/dist/pipeline/event-dispatcher-admin.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import type { DbConnection } from "../db/connection.js";
 export type ConsumerRecoveryState = {
     readonly name: string;

package/dist/pipeline/event-dispatcher-delivery.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import type { DbConnection, DbRunner, DbTx } from "../db/connection.js";
 import { type PendingIdRange } from "../db/queries/event-store.js";
 import type { AppContext } from "../engine/types/index.js";

package/dist/pipeline/event-dispatcher-delivery.js

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 // Value-only import, aliased to avoid shadowing the ambient global
 // `Temporal` TYPE that ConsumerStateRow.updatedAt/StoredEventRow.createdAt
 // resolve against (same #1438 dual-package-hazard pattern as event-store.ts).

package/dist/pipeline/event-retention.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import type { DbConnection } from "../db/connection.js";
 export type PruneEventsOptions = {
     readonly olderThan?: Temporal.Instant;

package/dist/pipeline/projection-rebuild.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import type { DbConnection } from "../db/connection.js";
 import type { Registry } from "../engine/types/index.js";
 import type { Meter } from "../observability/types/metric.js";

package/dist/time/polyfill.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 /**
  * Ensure `globalThis.Temporal` is available. Idempotent.
  */

package/dist/time/polyfill.js

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 // Temporal polyfill bootstrap.
 //
 // Temporal is native in Chromium 144+ / Firefox 139+, but missing in Safari,

package/dist/ui-types/index.d.ts

@@ -9,7 +9,7 @@ export type { BooleanFieldDef, DateFieldDef, EmbeddedDerivedCellDef, EntityDefin
 export type { AccessRule, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, RoleAccessPersonalData, RoleAccessRule, } from "../engine/types/handlers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.js";
-export type { ActionFormRedirect, ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, EntityListScreenDefinition, FieldCondition, FieldIconKey, FieldRenderer, FormWidth, ListColumnSpec, ListFacetSpec, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RelatedListToolbarAction, RowAction, RowActionDrawer, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.js";
+export type { ActionFormRedirect, ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartKind, DashboardChartPanel, DashboardChartTone, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardTimeRangeDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, EntityListScreenDefinition, FieldCondition, FieldIconKey, FieldRenderer, FormWidth, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListFacetSpec, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RelatedListToolbarAction, RowAction, RowActionDrawer, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.js";
 export { metricField } from "../engine/types/screen.js";
 export type { TargetRef } from "../engine/types/target-ref.js";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node.js";

package/package.json

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

package/src/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.330.0",
+    "type": "improvement",
+    "title": "TenantDb.aggregate and aggregateWhere: grouped count, countDistinct, sum and avg with time buckets (fw#3396)",
+    "detail": "`tenantDb.aggregate(table, { measure, groupBy?, orderByValue?, limit? }, where?)` and the standalone `aggregateWhere(db, table, spec, where?)` run one grouped aggregate with the same tenant scoping as `read`/`count`. A dimension can be a plain column or a time bucket (`{ field, bucket: 'hour' | 'day' | ..., timeZone }`) on a timestamptz column; bucket keys come back as epoch milliseconds. Types live in `@cosmicdrift/kumiko-types/aggregate-types`. Unknown fields, non-timestamptz bucket columns and bad limits throw before any SQL runs.",
+    "migration": "Only code that implements the `TenantDb` interface itself (for example a hand-written mock) must add an `aggregate` method; `createTenantDb` already provides it."
+  },
+  {
+    "version": "0.329.0",
+    "type": "improvement",
+    "title": "WebSocket routes cap the bytes queued behind slow handlers",
+    "detail": "Frames that arrive while `onOpen` or an earlier `onMessage` is still running are queued in order. Their summed size is now limited to 1 MiB (`WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES`, or the route's `maxMessageBytes` if larger); beyond that the socket closes with code 1013 and the queued frames are dropped."
+  },
   {
     "version": "0.328.1",
     "type": "improvement",