@cosmicdrift/kumiko-framework 0.404.1 → 0.405.0

package/dist/api/auth-routes-mfa.js

@@ -1,5 +1,5 @@
-import { createHash } from "node:crypto";
 import * as z from "zod";
+import { hashOpaqueTokenSync } from "../crypto/opaque-token-hash.js";
 import { createAnonymousUser } from "../engine/system-user.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
 import { Routes } from "./api-constants.js";
@@ -36,7 +36,7 @@ const MfaPreauthConfirmBody = z.object({
 // login.write.ts), so hashing it into a bucket key still caps the replay
 // even when the IP-based bucket is bypassed via header rotation.
 function preauthTokenKeyOf(token) {
-    return `preauth-token:${createHash("sha256").update(token).digest("hex")}`;
+    return `preauth-token:${hashOpaqueTokenSync(token)}`;
 }
 export function registerMfaVerifyRoute(ctx) {
     const { api, dispatcher, config, getClientIp, mintSessionAndRespond, landingPathFragment } = ctx;

package/dist/api/index.d.ts

@@ -1,4 +1,6 @@
 export { DEFAULT_GLOBAL_RATE_LIMIT } from "../rate-limit/middleware.ts";
+export type { TimedRunResult } from "../utils/run-with-timeout.ts";
+export { runWithTimeout } from "../utils/run-with-timeout.ts";
 export { setTenantCookie } from "./anonymous-cookie.ts";
 export { collectAnonymousLiveEntities } from "./anonymous-live-entities.ts";
 export { LOCALE_HEADER_NAME, NO_ROUTE_MATCH_HEADER_NAME } from "./api-constants.ts";
@@ -16,8 +18,6 @@ export type { JwtHelper } from "./jwt.ts";
 export { loadJwtSecretOrKeyring } from "./jwt.ts";
 export { publicOriginOf } from "./origin-middleware.ts";
 export type { PostAuthLandingArgs, PostAuthLandingResolver, } from "./post-auth-landing.ts";
-export type { TimedRunResult } from "./readiness.ts";
-export { runWithTimeout } from "./readiness.ts";
 export type { RedisSseBroker } from "./redis-sse-broker.ts";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.ts";
 export { readonlyRequestContext as requestContext } from "./request-context-scopes.ts";

package/dist/api/index.js

@@ -1,4 +1,5 @@
 export { DEFAULT_GLOBAL_RATE_LIMIT } from "../rate-limit/middleware.js";
+export { runWithTimeout } from "../utils/run-with-timeout.js";
 export { setTenantCookie } from "./anonymous-cookie.js";
 export { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
 export { LOCALE_HEADER_NAME, NO_ROUTE_MATCH_HEADER_NAME } from "./api-constants.js";
@@ -9,7 +10,6 @@ export { ExtraRouteRejection, signatureRoute } from "./extra-route.js";
 export { cacheControlHeader, cachedResponse, computeRevisionEtag, computeStrongEtag, computeWeakEtag, etagMatches, } from "./http-cache.js";
 export { loadJwtSecretOrKeyring } from "./jwt.js";
 export { publicOriginOf } from "./origin-middleware.js";
-export { runWithTimeout } from "./readiness.js";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
 export { readonlyRequestContext as requestContext } from "./request-context-scopes.js";
 export { buildRequestContextDataFromRequest } from "./request-id-middleware.js";

package/dist/api/readiness.d.ts

@@ -18,17 +18,6 @@ export type ReadinessProbeOptions = {
     readonly timeoutMs?: number;
 };
 export declare function createReadinessProbe(checks: readonly ReadinessCheck[], opts?: ReadinessProbeOptions): () => Promise<ReadinessResult>;
-export type TimedRunResult<T> = {
-    readonly ok: true;
-    readonly value: T;
-    readonly latencyMs: number;
-} | {
-    readonly ok: false;
-    readonly error: unknown;
-    readonly timedOut: boolean;
-    readonly latencyMs: number;
-};
-export declare function runWithTimeout<T>(run: () => Promise<T>, timeoutMs: number): Promise<TimedRunResult<T>>;
 export declare function dbPingCheck(db: DbConnection): ReadinessCheck;
 export declare function redisPingCheck(redis: Redis): ReadinessCheck;
 export declare function dispatcherLagCheck(db: DbConnection, consumerNames: readonly string[], maxLagEvents: bigint): ReadinessCheck;

package/dist/api/readiness.js

@@ -12,6 +12,7 @@
 //     so total latency must stay ≈ slowest check, not sum.
 import { pingDatabase } from "../db/queries/raw-sql.js";
 import { getAllConsumerProgress } from "../pipeline/event-dispatcher.js";
+import { runWithTimeout } from "../utils/run-with-timeout.js";
 const DEFAULT_TIMEOUT_MS = 2_000;
 export function createReadinessProbe(checks, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -23,36 +24,6 @@ export function createReadinessProbe(checks, opts = {}) {
         };
     };
 }
-class TimeoutError extends Error {
-}
-export async function runWithTimeout(run, timeoutMs) {
-    const start = performance.now();
-    const elapsedMs = () => Math.round(performance.now() - start);
-    let timer;
-    try {
-        const value = await Promise.race([
-            run(),
-            new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new TimeoutError(`timeout after ${timeoutMs}ms`)), timeoutMs);
-                // Don't keep the event loop alive on a hung probe during shutdown.
-                timer.unref?.();
-            }),
-        ]);
-        return { ok: true, value, latencyMs: elapsedMs() };
-    }
-    catch (error) {
-        return {
-            ok: false,
-            error,
-            timedOut: error instanceof TimeoutError,
-            latencyMs: elapsedMs(),
-        };
-    }
-    finally {
-        if (timer)
-            clearTimeout(timer);
-    }
-}
 async function runOne(check, timeoutMs) {
     const result = await runWithTimeout(check.run, timeoutMs);
     if (result.ok)

package/dist/crypto/index.d.ts

@@ -6,6 +6,7 @@ export { resolvePlatformKeks } from "./kek-source.ts";
 export { KeyAlreadyExistsError, KeyErasedError, type KmsAdapter, type KmsContext, type LocalKeyKmsAdapter, type SubjectId, subjectIdSchema, subjectIdToKey, subjectKeyForRecord, subjectKeyForUser, } from "./kms-adapter.ts";
 export { ENCRYPTION_UNAVAILABLE_CODE, EncryptionUnavailableError } from "./kms-outage.ts";
 export { type KmsWiring, requireKmsWiring, requireKmsWiringAsync, resolveKmsWiring, resolveKmsWiringAsync, } from "./kms-wiring.ts";
+export { hashOpaqueToken, hashOpaqueTokenSync, opaqueTokenHashMatches, } from "./opaque-token-hash.ts";
 export { createPgKmsAdapter, rewrapSubjectKeys, } from "./pg-kms-adapter.ts";
 export { PII_CIPHERTEXT_CORRUPT_CODE, PiiCiphertextCorruptError, } from "./pii-ciphertext-corrupt.ts";
 export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, encryptPiiFieldValues, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_ERASED_SENTINEL, } from "./pii-field-encryption.ts";

package/dist/crypto/index.js

@@ -6,6 +6,7 @@ export { resolvePlatformKeks } from "./kek-source.js";
 export { KeyAlreadyExistsError, KeyErasedError, subjectIdSchema, subjectIdToKey, subjectKeyForRecord, subjectKeyForUser, } from "./kms-adapter.js";
 export { ENCRYPTION_UNAVAILABLE_CODE, EncryptionUnavailableError } from "./kms-outage.js";
 export { requireKmsWiring, requireKmsWiringAsync, resolveKmsWiring, resolveKmsWiringAsync, } from "./kms-wiring.js";
+export { hashOpaqueToken, hashOpaqueTokenSync, opaqueTokenHashMatches, } from "./opaque-token-hash.js";
 export { createPgKmsAdapter, rewrapSubjectKeys, } from "./pg-kms-adapter.js";
 export { PII_CIPHERTEXT_CORRUPT_CODE, PiiCiphertextCorruptError, } from "./pii-ciphertext-corrupt.js";
 export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, encryptPiiFieldValues, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_ERASED_SENTINEL, } from "./pii-field-encryption.js";

package/dist/crypto/opaque-token-hash.d.ts

@@ -0,0 +1,3 @@
+export declare function hashOpaqueToken(token: string): Promise<string>;
+export declare function hashOpaqueTokenSync(token: string): string;
+export declare function opaqueTokenHashMatches(token: string, storedHash: string): boolean;

package/dist/crypto/opaque-token-hash.js

@@ -0,0 +1,14 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { digestHex } from "../utils/hex.js";
+export function hashOpaqueToken(token) {
+    return digestHex("SHA-256", token);
+}
+export function hashOpaqueTokenSync(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+export function opaqueTokenHashMatches(token, storedHash) {
+    const actual = Buffer.from(hashOpaqueTokenSync(token));
+    const expected = Buffer.from(storedHash);
+    // timingSafeEqual throws on a length mismatch, and the throw itself is a timing signal.
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+}

package/dist/crypto/subject-resolver.js

@@ -1,4 +1,5 @@
 import { normalizeEventPiiSubject } from "@cosmicdrift/kumiko-types/handlers";
+import { isFileField } from "../engine/field-helpers.js";
 import { isSelfPiiField } from "./is-self-pii-field.js";
 import { RECORD_ENTITY_PATTERN } from "./kms-adapter.js";
 // Thrown when a field IS pii-annotated but the row can't name its subject —
@@ -157,24 +158,18 @@ export function collectPiiSubjectFields(entity) {
         .filter(([, field]) => hasSubjectAnnotation(field))
         .map(([name]) => name);
 }
-function isFileReferenceField(field) {
-    return (field.type === "file" ||
-        field.type === "image" ||
-        field.type === "files" ||
-        field.type === "images");
-}
 // File columns hold only the fileRef uuid; the binary is erased by the file-ref
 // user-data hook, so these stay annotated (forget) but are never ciphertext.
 export function collectPiiEncryptedFields(entity) {
     return Object.entries(entity.fields)
-        .filter(([, field]) => hasSubjectAnnotation(field) && !isFileReferenceField(field))
+        .filter(([, field]) => hasSubjectAnnotation(field) && !isFileField(field))
         .map(([name]) => name);
 }
 // The annotated file-reference fields: never ciphertext today, but events from the
 // old backfill (which encrypted them) still carry it and must replay.
 export function collectPiiFileReferenceFields(entity) {
     return Object.entries(entity.fields)
-        .filter(([, field]) => hasSubjectAnnotation(field) && isFileReferenceField(field))
+        .filter(([, field]) => hasSubjectAnnotation(field) && isFileField(field))
         .map(([name]) => name);
 }
 /** Subject-annotated fields that may be plaintext in the derived search index. */

package/dist/db/blind-index-cleanup.js

@@ -13,6 +13,7 @@
 import { collectLookupableFields } from "../crypto/blind-index.js";
 import { quoteIdent, subjectCiphertextLikePattern } from "../crypto/ciphertext-pattern.js";
 import { isSelfPiiField } from "../crypto/is-self-pii-field.js";
+import { findEntity } from "../engine/find-entity.js";
 import { toSnakeCase } from "../utils/case.js";
 import { resolveTableName } from "./entity-table-meta.js";
 import { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
@@ -115,14 +116,6 @@ export async function subjectRowExistsInTenant(db, features, subjectId, tenantId
         return false;
     });
 }
-function findEntityByExactName(features, entityName) {
-    for (const feature of features.values()) {
-        const entity = feature.entities?.[entityName];
-        if (entity)
-            return entity;
-    }
-    return undefined;
-}
 // Tighter than subjectRowExistsInTenant: the record subject names its own
 // entity, so this is a single-table lookup instead of a self-PII scan
 // across the whole registry.
@@ -132,7 +125,7 @@ function findEntityByExactName(features, entityName) {
 // at create) — a composite PK or shared table would break this.
 export async function recordRowExistsInTenant(db, features, entityName, recordId, tenantId) {
     return runInSystemRowLevelSecurityScope("record existence check spans tenants", async () => {
-        const entity = findEntityByExactName(features, entityName);
+        const entity = findEntity(features, entityName);
         if (!entity)
             return false;
         const tableName = resolveTableName(entityName, entity, undefined);
@@ -159,7 +152,7 @@ export async function recordEventsOwnedExclusivelyByTenant(db, aggregateType, ag
 // tenant-scoped policy for the row's real owner (not the acting user's tenant).
 export async function recordRowOwningTenantId(db, features, entityName, recordId) {
     return runInSystemRowLevelSecurityScope("record owner lookup spans tenants", async () => {
-        const entity = findEntityByExactName(features, entityName);
+        const entity = findEntity(features, entityName);
         if (!entity)
             return undefined;
         const tableName = resolveTableName(entityName, entity, undefined);

package/dist/db/query.js

@@ -391,26 +391,11 @@ export async function insertOne(db, table, values) {
     if (managedDenied)
         throw managedDenied;
     const info = extractTableInfo(table);
-    const entries = Object.entries(values)
-        .filter(([k]) => info.hasColumn(k))
-        .map(([k, v]) => {
-        const col = info.columnOf(k);
-        const pgType = info.pgTypeOf(col);
-        return { col, prepared: prepareValue(v, pgType) };
-    });
+    const entries = insertEntries(info, values);
     if (entries.length === 0)
         throw new Error("insertOne: empty values object");
-    const cols = entries.map((e) => quoteIdent(e.col)).join(", ");
-    const params = [];
-    const placeholders = entries
-        .map((e) => {
-        if (e.prepared.kind === "literal")
-            return e.prepared.literal;
-        params.push(e.prepared.bound);
-        return `$${params.length}${e.prepared.sql}`;
-    })
-        .join(", ");
-    const sqlText = `INSERT INTO ${quoteIdent(info.name)} (${cols}) VALUES (${placeholders}) RETURNING *`;
+    const { sqlPrefix, params } = buildInsertSql(info, entries);
+    const sqlText = `${sqlPrefix} RETURNING *`;
     const rows = await unsafeLoggingClosedConnection(db, sqlText, params, {
         operation: "insertOne",
         table: info.name,

package/dist/derivatives/variant-key.d.ts

@@ -4,6 +4,10 @@ export declare function specHash(spec: VariantSpec): string;
 export declare const VARIANT_NAME_PATTERN: RegExp;
 export declare function variantSuffix(name: string, spec: VariantSpec): string;
 export declare function isDerivativeSuffix(suffix: string): boolean;
+export declare function splitKey(key: string): {
+    readonly base: string;
+    readonly ext: string;
+};
 export declare function derivativeListPrefix(originalKey: string): string;
 export declare function isDerivativeKeyOf(originalKey: string, candidateKey: string): boolean;
 export declare function parseDerivativeKey(candidateKey: string): {

package/dist/derivatives/variant-key.js

@@ -41,9 +41,10 @@ const DERIVATIVE_SUFFIX_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9-]{0,31}-[0-9a-f]{16}$/
 export function isDerivativeSuffix(suffix) {
     return DERIVATIVE_SUFFIX_PATTERN.test(suffix);
 }
-// Mirrors deriveKey's own split so callers get the exact same base/ext this
-// key's derivatives were built from.
-function splitKey(key) {
+// Splits on the last dot of the last path segment only, so `archive.v2/foo.jpg`
+// yields base `archive.v2/foo`. No dot there: the whole key is the base, ext is
+// empty. deriveKey uses the same split, so derivative keys line up with it.
+export function splitKey(key) {
     const lastSlash = key.lastIndexOf("/");
     const lastSegment = lastSlash === -1 ? key : key.slice(lastSlash + 1);
     const lastDot = lastSegment.lastIndexOf(".");

package/dist/engine/boot-validator/field-conditions.js

@@ -1,5 +1,6 @@
 import { isFileSubField } from "../../files/file-field-slots.js";
 import { parseMaxSize } from "../../files/types.js";
+import { isFileField } from "../field-helpers.js";
 import { conditionComparisonValues, LOCKABLE_FIELD_TYPES } from "./entity-handler.js";
 const STATE_KEYS = ["visibleWhen", "requiredWhen"];
 const SUB_CONDITION_TYPES = new Set([
@@ -178,15 +179,9 @@ function assertField(feature, entityName, entity, fieldName, field) {
     }
     if (field.type === "embedded")
         assertEmbeddedField(where, field);
-    if (isFileAcceptField(field))
+    if (isFileField(field))
         assertAcceptEntries(where, field.accept);
 }
-function isFileAcceptField(field) {
-    return (field.type === "file" ||
-        field.type === "files" ||
-        field.type === "image" ||
-        field.type === "images");
-}
 export function validateFieldConditions(feature) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
         for (const [fieldName, field] of Object.entries(entity.fields)) {

package/dist/engine/boot-validator/list-table-aggregate-query.js

@@ -1,7 +1,7 @@
 import { resolveEntityBehindListQuery } from "../entity-list-searchability.js";
+import { findEntity } from "../find-entity.js";
 import { normalizeListColumn } from "../screen-helpers.js";
 import { entityAggregateFieldLookup, validateListTableAggregateFieldTypes, } from "./list-table-aggregate-options.js";
-import { findEntity } from "./parent-ref.js";
 import { getZodObjectShape } from "./zod-shape.js";
 function columnValueTypeLookup(columns) {
     const valueTypes = new Map(columns

package/dist/engine/boot-validator/parent-ref.d.ts

@@ -1,4 +1,2 @@
-import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
 import type { FeatureDefinition } from "../types/index.ts";
-export declare function findEntity(featureMap: ReadonlyMap<string, FeatureDefinition>, entityName: string): EntityDefinition | undefined;
 export declare function validateParentRefs(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>): void;

package/dist/engine/boot-validator/parent-ref.js

@@ -1,4 +1,5 @@
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
+import { findEntity } from "../find-entity.js";
 // --- Parent-ref boot validation ---
 //
 // Join-row entities (EntityDefinition.parentRef) derive both the write-path
@@ -8,14 +9,6 @@ import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handler
 // was supplied — throwing there would 500 every custom handler and
 // framework-internal detail() call that doesn't wire it, so the enforcement
 // has to happen loudly here instead, once, at boot.
-export function findEntity(featureMap, entityName) {
-    for (const f of featureMap.values()) {
-        const entity = f.entities?.[entityName];
-        if (entity)
-            return entity;
-    }
-    return undefined;
-}
 function findQueryHandler(featureMap, handlerName) {
     for (const f of featureMap.values()) {
         const handler = f.queryHandlers[handlerName];

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

@@ -1,11 +1,11 @@
 import { isListQueryWithoutSearchableFields, resolveEntityBehindListQuery, } from "../entity-list-searchability.js";
+import { findEntity } from "../find-entity.js";
 import { QnTypes, qualifyEntityName } from "../qualified-name.js";
 import { isEditLayoutScreen } from "../screen-helpers.js";
 import { bootRuleError } from "./boot-rule.js";
 import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens.js";
 import { validateListTableAggregateQuery } from "./list-table-aggregate-query.js";
 import { NAMED_FILTER_RULES } from "./named-filter-rules.js";
-import { findEntity } from "./parent-ref.js";
 import { getZodObjectShape } from "./zod-shape.js";
 // Sibling to entity-list-screens.ts rather than an extension of it:
 // validateOneEntityListScreen is typed to EntityListScreenDefinition and

package/dist/engine/boot-validator/read-gate.js

@@ -1,6 +1,6 @@
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
 import { FILE_REF_ENTITY_NAME } from "../../files/types.js";
-import { findEntity } from "./parent-ref.js";
+import { findEntity } from "../find-entity.js";
 function fail(check, message) {
     throw new Error(`[Kumiko ReadGate] entity "${check.entityName}" (feature: "${check.feature.name}"): ${message}`);
 }

package/dist/engine/find-entity.d.ts

@@ -0,0 +1,3 @@
+import type { EntityDefinition } from "./types/fields.ts";
+import type { FeatureDefinition } from "./types/index.ts";
+export declare function findEntity(features: ReadonlyMap<string, FeatureDefinition>, entityName: string): EntityDefinition | undefined;

package/dist/engine/find-entity.js

@@ -0,0 +1,8 @@
+export function findEntity(features, entityName) {
+    for (const feature of features.values()) {
+        const entity = feature.entities?.[entityName];
+        if (entity)
+            return entity;
+    }
+    return undefined;
+}

package/dist/engine/project-app-schema-for-roles.js

@@ -255,62 +255,26 @@ function keepTreeAction(action, keptScreenQns) {
         return true; // target-based dispatch, not a screen navigate
     return keptScreenQns.has(action.screen);
 }
-// --- RowAction / ToolbarAction / RelatedListToolbarAction array projectors ---
-// Each returns the ORIGINAL array reference when nothing was filtered, and
-// `undefined` (never an empty array) when everything was — same JSON-safety
-// convention as buildAppSchema.
-function keepRowAction(action, feature, indices, keptScreenQns) {
+function keepScreenTargetAction(action, feature, indices, keptScreenQns) {
     if (action.kind === "drawer")
         return isDrawerTargetKept(feature, action.screen, keptScreenQns);
     if (action.kind === "navigate")
         return isNavigateTargetKept(action, indices, keptScreenQns);
-    return true; // writeHandler — no screen target
+    return true; // no screen target
 }
-function projectRowActionArray(actions, feature, indices, keptScreenQns) {
+function filterKeptActions(actions, keep) {
     if (actions === undefined)
         return undefined;
-    const kept = actions.filter((a) => keepRowAction(a, feature, indices, keptScreenQns));
+    const kept = actions.filter(keep);
     if (kept.length === actions.length)
         return actions;
     return kept.length > 0 ? kept : undefined;
 }
-function keepToolbarAction(action, feature, indices, keptScreenQns) {
-    if (action.kind === "navigate")
-        return isNavigateTargetKept(action, indices, keptScreenQns);
-    if (action.kind === "drawer")
-        return isDrawerTargetKept(feature, action.screen, keptScreenQns);
-    return true;
-}
-function projectToolbarActionArray(actions, feature, indices, keptScreenQns) {
-    if (actions === undefined)
-        return undefined;
-    const kept = actions.filter((a) => keepToolbarAction(a, feature, indices, keptScreenQns));
-    if (kept.length === actions.length)
-        return actions;
-    return kept.length > 0 ? kept : undefined;
-}
-function keepRelatedListToolbarAction(action, feature, indices, keptScreenQns) {
-    if (action.kind === "navigate")
-        return isNavigateTargetKept(action, indices, keptScreenQns);
-    if (action.kind === "drawer")
-        return isDrawerTargetKept(feature, action.screen, keptScreenQns);
-    return true;
-}
-function projectRelatedListToolbarActionArray(actions, feature, indices, keptScreenQns) {
-    if (actions === undefined)
-        return undefined;
-    const kept = actions.filter((a) => keepRelatedListToolbarAction(a, feature, indices, keptScreenQns));
-    if (kept.length === actions.length)
-        return actions;
-    return kept.length > 0 ? kept : undefined;
+function projectActionArray(actions, feature, indices, keptScreenQns) {
+    return filterKeptActions(actions, (a) => keepScreenTargetAction(a, feature, indices, keptScreenQns));
 }
 function projectTreeActionArray(actions, keptScreenQns) {
-    if (actions === undefined)
-        return undefined;
-    const kept = actions.filter((a) => keepTreeAction(a, keptScreenQns));
-    if (kept.length === actions.length)
-        return actions;
-    return kept.length > 0 ? kept : undefined;
+    return filterKeptActions(actions, (a) => keepTreeAction(a, keptScreenQns));
 }
 function projectTreeAction(action, keptScreenQns) {
     if (action === undefined)
@@ -329,16 +293,16 @@ function projectEmptyState(emptyState, feature, indices, keptScreenQns) {
         return undefined;
     if (emptyState.action === undefined)
         return emptyState;
-    if (keepRowAction(emptyState.action, feature, indices, keptScreenQns))
+    if (keepScreenTargetAction(emptyState.action, feature, indices, keptScreenQns))
         return emptyState;
     const { action, ...rest } = emptyState;
     return rest;
 }
 function projectRelatedListSection(section, feature, indices, keptScreenQns) {
     const { actions, rowActions, toolbarActions, rowClick, emptyState, ...rest } = section;
-    const nextActions = projectRowActionArray(actions, feature, indices, keptScreenQns);
-    const nextRowActions = projectRowActionArray(rowActions, feature, indices, keptScreenQns);
-    const nextToolbarActions = projectRelatedListToolbarActionArray(toolbarActions, feature, indices, keptScreenQns);
+    const nextActions = projectActionArray(actions, feature, indices, keptScreenQns);
+    const nextRowActions = projectActionArray(rowActions, feature, indices, keptScreenQns);
+    const nextToolbarActions = projectActionArray(toolbarActions, feature, indices, keptScreenQns);
     const nextRowClick = rowClick === undefined || isRowClickEntityKept(rowClick.entity, indices, keptScreenQns)
         ? rowClick
         : undefined;
@@ -365,18 +329,18 @@ function projectEditSection(section, feature, indices, keptScreenQns) {
             return projectRelatedListSection(section, feature, indices, keptScreenQns);
         case "extension": {
             const { actions, ...rest } = section;
-            const kept = projectRowActionArray(actions, feature, indices, keptScreenQns);
+            const kept = projectActionArray(actions, feature, indices, keptScreenQns);
             return kept === actions ? section : { ...rest, ...(kept !== undefined && { actions: kept }) };
         }
         case "writeForm": {
             const { actions, ...rest } = section;
-            const kept = projectRowActionArray(actions, feature, indices, keptScreenQns);
+            const kept = projectActionArray(actions, feature, indices, keptScreenQns);
             return kept === actions ? section : { ...rest, ...(kept !== undefined && { actions: kept }) };
         }
         default: {
             // kind undefined or "fields"
             const { actions, ...rest } = section;
-            const kept = projectRowActionArray(actions, feature, indices, keptScreenQns);
+            const kept = projectActionArray(actions, feature, indices, keptScreenQns);
             return kept === actions ? section : { ...rest, ...(kept !== undefined && { actions: kept }) };
         }
     }
@@ -471,8 +435,8 @@ function dropUnreachableCreateScreen(screen, feature, keptScreenQns) {
 function projectListScreen(original, feature, indices, keptScreenQns) {
     const screen = dropUnreachableCreateScreen(original, feature, keptScreenQns);
     const { rowActions, toolbarActions, ...rest } = screen;
-    const nextRowActions = projectRowActionArray(rowActions, feature, indices, keptScreenQns);
-    const nextToolbarActions = projectToolbarActionArray(toolbarActions, feature, indices, keptScreenQns);
+    const nextRowActions = projectActionArray(rowActions, feature, indices, keptScreenQns);
+    const nextToolbarActions = projectActionArray(toolbarActions, feature, indices, keptScreenQns);
     const expandableRow = screen.type === "entityList" ? screen.expandableRow : undefined;
     const nextExpandableRow = expandableRow === undefined
         ? undefined
@@ -493,7 +457,7 @@ function projectProjectionDetailScreen(screen, feature, indices, keptScreenQns)
     const { metrics, header, actions, layout, listScreenId, ...rest } = screen;
     const nextMetrics = projectMetrics(metrics, indices, keptScreenQns);
     const nextHeader = projectHeader(header, indices, keptScreenQns);
-    const nextActions = projectRowActionArray(actions, feature, indices, keptScreenQns);
+    const nextActions = projectActionArray(actions, feature, indices, keptScreenQns);
     const nextLayout = projectEditLayout(layout, feature, indices, keptScreenQns);
     const nextListScreenId = projectListScreenId(listScreenId, indices, keptScreenQns);
     const unchanged = nextMetrics === metrics &&
@@ -515,7 +479,7 @@ function projectProjectionDetailScreen(screen, feature, indices, keptScreenQns)
 function projectEntityEditScreen(screen, feature, indices, keptScreenQns) {
     const { redirect, actions, layout, listScreenId, ...rest } = screen;
     const nextRedirect = projectRedirect(feature.featureName, redirect, keptScreenQns);
-    const nextActions = projectRowActionArray(actions, feature, indices, keptScreenQns);
+    const nextActions = projectActionArray(actions, feature, indices, keptScreenQns);
     const nextLayout = projectEditLayout(layout, feature, indices, keptScreenQns);
     const nextListScreenId = projectListScreenId(listScreenId, indices, keptScreenQns);
     const unchanged = nextRedirect === redirect &&
@@ -592,7 +556,7 @@ function projectScreen(screen, feature, indices, keptScreenQns) {
         case "dashboard": {
             const { actions, ...rest } = screen;
             const nextPanels = projectDashboardPanels(screen.panels, feature, keptScreenQns);
-            const nextActions = projectRowActionArray(actions, feature, indices, keptScreenQns);
+            const nextActions = projectActionArray(actions, feature, indices, keptScreenQns);
             if (nextPanels === screen.panels && nextActions === actions)
                 return screen;
             return {

package/dist/files/file-handle.js

@@ -10,7 +10,7 @@
 // suffix before the file extension — `foo/bar.jpg` + `"medium-<16 hex>"` →
 // `foo/bar.medium-<16 hex>.jpg`. The suffix must be a `variantSuffix(...)` so
 // the erasure sweep recognizes it. Stable, reversible, no extra lookup tables.
-import { derivativeListPrefix, isDerivativeSuffix } from "../derivatives/variant-key.js";
+import { derivativeListPrefix, isDerivativeSuffix, splitKey } from "../derivatives/variant-key.js";
 import { InternalError } from "../errors/index.js";
 import { assertSafeStorageKey } from "./types.js";
 // `getProvider` is a lazily-resolved, memoized accessor — the provider is
@@ -100,26 +100,13 @@ export function createFileContext(resolve, tenantId, uploadLedger) {
 export function createTenantFileContext(resolver, tenantId) {
     return createFileContext(() => resolver(tenantId), tenantId, resolver.uploadLedgerFor?.(tenantId));
 }
-// Splits a key into the part before the last dot of its last path segment
-// (the "stem") and the extension including the dot. No dot in the last
-// segment: the whole key is the stem, extension is empty.
-function splitKeyExtension(key) {
-    const lastSlash = key.lastIndexOf("/");
-    const lastSegment = lastSlash === -1 ? key : key.slice(lastSlash + 1);
-    const lastDot = lastSegment.lastIndexOf(".");
-    if (lastDot === -1)
-        return { stem: key, ext: "" };
-    const stem = key.slice(0, key.length - lastSegment.length + lastDot);
-    const ext = lastSegment.slice(lastDot);
-    return { stem, ext };
-}
 // Inserts a suffix before the file extension. Keys without an extension get
 // the suffix appended with a dot: `foo/bar` + `"small"` → `foo/bar.small`.
 // Keys with a dot earlier in the path (e.g. `archive.v2/foo.jpg`) correctly
 // split on the LAST segment only.
 export function deriveKey(key, suffix) {
-    const { stem, ext } = splitKeyExtension(key);
-    return ext === "" ? `${key}.${suffix}` : `${stem}.${suffix}${ext}`;
+    const { base, ext } = splitKey(key);
+    return ext === "" ? `${key}.${suffix}` : `${base}.${suffix}${ext}`;
 }
 // The prefix that covers a key AND every `derive()`d variant of it — `foo/bar.jpg` → `foo/bar.`,
 // matching `foo/bar.jpg` and `foo/bar.medium.jpg` alike, since derive() only ever inserts a suffix

package/dist/observability/ids.js

@@ -2,14 +2,7 @@
 // collectors and UIs understand what we emit:
 //   - traceId: 16 random bytes, rendered as 32 lowercase hex chars
 //   - spanId:   8 random bytes, rendered as 16 lowercase hex chars
-function bytesToHex(bytes) {
-    let out = "";
-    for (let i = 0; i < bytes.length; i++) {
-        const b = bytes[i] ?? 0;
-        out += b.toString(16).padStart(2, "0");
-    }
-    return out;
-}
+import { bytesToHex } from "../utils/hex.js";
 export function generateTraceId() {
     const bytes = new Uint8Array(16);
     crypto.getRandomValues(bytes);

package/dist/pipeline/projection-rebuild.js

@@ -6,8 +6,9 @@ import { runInSystemRowLevelSecurityScope } from "../db/row-level-security-scope
 import { withoutStatementTimeout } from "../db/statement-timeout.js";
 import { extractTableInfo } from "../db/table-info.js";
 import { withExecutorManagedWrites } from "../db/tenant-db.js";
-import { eventsTable, getEventsHighWaterMark, upcastStoredEvent, } from "../event-store/index.js";
+import { eventsTable, getEventsHighWaterMark, upcastStoredEvent } from "../event-store/index.js";
 import { createRebuildDeadLetterTable, recordRebuildDeadLetters, } from "../event-store/rebuild-dead-letter.js";
+import { toStoredEvent } from "../event-store/row-to-stored-event.js";
 import { createFallbackLogger } from "../logging/utils.js";
 import { emitProjectionRebuild } from "../observability/standard-metrics.js";
 import { projectionStateTable } from "./projection-state.js";
@@ -22,21 +23,6 @@ export const REBUILD_BATCH_SIZE = 1000;
 // live table is held ACCESS EXCLUSIVE).
 const MAX_UNLOCKED_BATCHES = 10_000;
 const DEFAULT_FENCE_LOCK_TIMEOUT_MS = 5_000;
-function rowToStoredEvent(row) {
-    return {
-        id: String(row.id),
-        aggregateId: row.aggregateId,
-        aggregateType: row.aggregateType,
-        tenantId: row.tenantId,
-        version: row.version,
-        type: row.type,
-        eventVersion: row.eventVersion,
-        payload: row.payload,
-        metadata: row.metadata,
-        createdAt: row.createdAt,
-        createdBy: row.createdBy,
-    };
-}
 const TENANT_COLUMN_SUFFIX = ".tenant_id";
 // Ops-facing log line for countColumnDrift's result. No-op when clean.
 function warnOnColumnDrift(projectionName, tableName, drift) {
@@ -93,7 +79,7 @@ async function replayProjectionIntoShadow(projectionName, deps) {
         for (const r of rawEvents) {
             deps.signal?.throwIfAborted();
             const row = coerceRow(r, eventsInfo);
-            const storedEvent = await upcastStoredEvent(rowToStoredEvent(row), upcasters, {
+            const storedEvent = await upcastStoredEvent(toStoredEvent(row), upcasters, {
                 db: tx,
                 tenantId: row.tenantId, // @cast-boundary db-row
             });

package/dist/pipeline/tenant-timezone-cache.js

@@ -8,6 +8,7 @@
 // the write. The TTL below therefore bounds how long OTHER replicas (and
 // writes that bypass that path: migrations, seeds, direct DB edits) keep
 // serving the old value, hence the short default.
+import { createLruCache } from "../utils/lru-cache.js";
 const DEFAULT_TTL_MS = 30 * 1000;
 const DEFAULT_MAX_ENTRIES = 1000;
 export function createTenantTimezoneCache(opts = {}) {
@@ -15,37 +16,17 @@ export function createTenantTimezoneCache(opts = {}) {
     // 0 or negative would never evict (size < max is never true) and grow unbounded.
     const maxEntries = Math.max(1, opts.maxEntries ?? DEFAULT_MAX_ENTRIES);
     const now = opts.now ?? (() => Date.now());
-    // Map insertion order doubles as LRU order: touch = delete+re-insert.
-    const entries = new Map();
+    const entries = createLruCache({
+        maxEntries,
+        ttlMs,
+        now,
+    });
     let generation = 0;
-    function evictOldestIfFull() {
-        // skip: cache has room, nothing to evict
-        if (entries.size < maxEntries)
-            return;
-        const oldestKey = entries.keys().next().value;
-        // skip: defensive — maxEntries >= 1 guarantees a non-empty map here
-        if (oldestKey === undefined)
-            return;
-        entries.delete(oldestKey);
-    }
     function set(tenantId, value) {
-        entries.delete(tenantId);
-        evictOldestIfFull();
-        entries.set(tenantId, { value, expiresAt: now() + ttlMs });
+        entries.set(tenantId, { value });
     }
     return {
-        get(tenantId) {
-            const hit = entries.get(tenantId);
-            if (!hit)
-                return undefined;
-            if (hit.expiresAt <= now()) {
-                entries.delete(tenantId);
-                return undefined;
-            }
-            entries.delete(tenantId);
-            entries.set(tenantId, hit);
-            return { value: hit.value };
-        },
+        get: (tenantId) => entries.get(tenantId),
         set,
         generation() {
             return generation;

package/dist/search/index.d.ts

@@ -1,4 +1,7 @@
+export { collectSearchableFieldNames } from "./configure-tenant-index.ts";
 export { createInMemorySearchAdapter } from "./in-memory-adapter.ts";
+export { isEntitySearchable } from "./is-entity-searchable.ts";
 export { purgeSearchDocumentsForSubject } from "./purge-subject.ts";
 export { reindexEntity } from "./reindex-entity.ts";
+export { type ReindexTenantsSearchOptions, type ReindexTenantsSearchResult, reindexTenantsSearch, } from "./reindex-tenants-search.ts";
 export type { SearchAdapter, SearchAdapterConfig, } from "./types.ts";

package/dist/search/index.js

@@ -2,6 +2,9 @@
 // `@cosmicdrift/kumiko-framework/search/meilisearch`. This keeps the main barrel from loading a
 // Meilisearch client when consumers only use SearchAdapter types, so apps that do not use
 // Meilisearch do not pull in the client code.
+export { collectSearchableFieldNames } from "./configure-tenant-index.js";
 export { createInMemorySearchAdapter } from "./in-memory-adapter.js";
+export { isEntitySearchable } from "./is-entity-searchable.js";
 export { purgeSearchDocumentsForSubject } from "./purge-subject.js";
 export { reindexEntity } from "./reindex-entity.js";
+export { reindexTenantsSearch, } from "./reindex-tenants-search.js";

package/dist/search/is-entity-searchable.d.ts

@@ -0,0 +1,2 @@
+import type { Registry } from "../engine/types/index.ts";
+export declare function isEntitySearchable(registry: Registry, entityName: string): boolean;

package/dist/search/is-entity-searchable.js

@@ -0,0 +1,4 @@
+export function isEntitySearchable(registry, entityName) {
+    return (registry.getSearchableFields(entityName).length > 0 ||
+        registry.getSearchPayloadExtensions(entityName).length > 0);
+}

package/dist/search/reindex-tenants-search.d.ts

@@ -0,0 +1,19 @@
+import type { DbRunner } from "../db/connection.ts";
+import { type Registry, type TenantId } from "../engine/types/index.ts";
+import type { SearchAdapter } from "./types.ts";
+export type ReindexTenantsSearchOptions = {
+    readonly tenantIds: readonly TenantId[];
+    readonly timeoutMs?: number;
+    readonly configureTimeoutMs?: number;
+    readonly dryRun?: boolean;
+    readonly warn?: (message: string) => void;
+};
+export type ReindexTenantsSearchResult = {
+    readonly tenants: number;
+    readonly entities: number;
+    readonly indexedRows: number;
+    readonly failedRows: number;
+    readonly failedReindexes: number;
+    readonly failedConfigures: number;
+};
+export declare function reindexTenantsSearch(db: DbRunner, registry: Registry, searchAdapter: SearchAdapter, options: ReindexTenantsSearchOptions): Promise<ReindexTenantsSearchResult>;

package/dist/search/reindex-tenants-search.js

@@ -0,0 +1,69 @@
+import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
+import { createFallbackLogger } from "../logging/utils.js";
+import { runWithTimeout } from "../utils/run-with-timeout.js";
+import { collectSearchableFieldNames } from "./configure-tenant-index.js";
+import { isEntitySearchable } from "./is-entity-searchable.js";
+import { reindexEntity } from "./reindex-entity.js";
+const defaultLog = createFallbackLogger("search");
+const DEFAULT_CONFIGURE_TIMEOUT_MS = 5_000;
+const DEFAULT_REINDEX_TIMEOUT_MS = 60_000;
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+// Reindexing an unconfigured index falls back to searchableAttributes ["*"],
+// so a tenant whose configure failed is reported and skipped, not fatal.
+async function configureTolerant(tenantIds, registry, searchAdapter, timeoutMs, warn) {
+    const fields = collectSearchableFieldNames(registry);
+    const configured = [];
+    let failedConfigures = 0;
+    for (const tenantId of tenantIds) {
+        const outcome = await runWithTimeout(() => searchAdapter.configure(tenantId, { searchableFields: fields, rankingFields: fields }), timeoutMs);
+        if (outcome.ok) {
+            configured.push(tenantId);
+        }
+        else {
+            failedConfigures += 1;
+            warn(`[search] configure for tenant ${tenantId} failed: ${messageOf(outcome.error)}`);
+        }
+    }
+    return { configured, failedConfigures };
+}
+export async function reindexTenantsSearch(db, registry, searchAdapter, options) {
+    const warn = options.warn ?? ((message) => defaultLog.warn(message));
+    const reindexTimeoutMs = options.timeoutMs ?? DEFAULT_REINDEX_TIMEOUT_MS;
+    const dryRun = options.dryRun === true;
+    const { configured, failedConfigures } = dryRun
+        ? { configured: [...options.tenantIds], failedConfigures: 0 }
+        : await configureTolerant(options.tenantIds, registry, searchAdapter, options.configureTimeoutMs ?? DEFAULT_CONFIGURE_TIMEOUT_MS, warn);
+    let entities = 0;
+    let indexedRows = 0;
+    let failedRows = 0;
+    let failedReindexes = 0;
+    for (const [entityName, entity] of registry.getAllEntities()) {
+        if (!isEntitySearchable(registry, entityName))
+            continue;
+        entities += 1;
+        const targetTenantIds = entity.systemStream === true ? [SYSTEM_TENANT_ID] : configured;
+        for (const tenantId of targetTenantIds) {
+            const outcome = await runWithTimeout(() => reindexEntity(db, registry, searchAdapter, entityName, tenantId, dryRun ? { dryRun } : {}), reindexTimeoutMs);
+            if (!outcome.ok) {
+                failedReindexes += 1;
+                warn(`[search] reindex "${entityName}" tenant=${tenantId} failed: ${messageOf(outcome.error)}`);
+                continue;
+            }
+            indexedRows += outcome.value.indexedRows;
+            if (outcome.value.failures.length > 0) {
+                failedRows += outcome.value.failures.length;
+                warn(`[search] reindex "${entityName}" tenant=${tenantId}: ${outcome.value.failures.length} row(s) failed, first: ${outcome.value.failures[0]?.reason}`);
+            }
+        }
+    }
+    return {
+        tenants: options.tenantIds.length,
+        entities,
+        indexedRows,
+        failedRows,
+        failedReindexes,
+        failedConfigures,
+    };
+}

package/dist/utils/chunk.d.ts

@@ -0,0 +1 @@
+export declare function chunk<T>(items: readonly T[], size: number): T[][];

package/dist/utils/chunk.js

@@ -0,0 +1,7 @@
+export function chunk(items, size) {
+    const chunks = [];
+    for (let start = 0; start < items.length; start += size) {
+        chunks.push(items.slice(start, start + size));
+    }
+    return chunks;
+}

package/dist/utils/hex.d.ts

@@ -0,0 +1,3 @@
+export type DigestAlgorithm = "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512";
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function digestHex(algorithm: DigestAlgorithm, text: string): Promise<string>;

package/dist/utils/hex.js

@@ -0,0 +1,11 @@
+export function bytesToHex(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i++) {
+        out += (bytes[i] ?? 0).toString(16).padStart(2, "0");
+    }
+    return out;
+}
+export async function digestHex(algorithm, text) {
+    const digest = await crypto.subtle.digest(algorithm, new TextEncoder().encode(text));
+    return bytesToHex(new Uint8Array(digest));
+}

package/dist/utils/index.d.ts

@@ -1,6 +1,9 @@
 export { assertUnreachable } from "./assert.ts";
+export { chunk } from "./chunk.ts";
+export { bytesToHex, type DigestAlgorithm, digestHex } from "./hex.ts";
 export { generateDeterministicId, generateId } from "./ids.ts";
 export { isPlainObject } from "./is-plain-object.ts";
+export { createLruCache, type LruCache, type LruCacheOptions } from "./lru-cache.ts";
 export { parseStringArrayJson } from "./parse-string-array-json.ts";
 export { parseJsonOrThrow, parseJsonSafe } from "./safe-json.ts";
 export { parseRoles } from "./serialization.ts";

package/dist/utils/index.js

@@ -1,6 +1,9 @@
 export { assertUnreachable } from "./assert.js";
+export { chunk } from "./chunk.js";
+export { bytesToHex, digestHex } from "./hex.js";
 export { generateDeterministicId, generateId } from "./ids.js";
 export { isPlainObject } from "./is-plain-object.js";
+export { createLruCache } from "./lru-cache.js";
 export { parseStringArrayJson } from "./parse-string-array-json.js";
 export { parseJsonOrThrow, parseJsonSafe } from "./safe-json.js";
 export { parseRoles } from "./serialization.js";

package/dist/utils/lru-cache.d.ts

@@ -0,0 +1,17 @@
+export type LruCacheOptions<V> = {
+    readonly maxEntries: number;
+    /** Entries at least this old count as misses; omitted = no expiry. */
+    readonly ttlMs?: number;
+    readonly now?: () => number;
+    /** Summed `sizeOf` budget; a value larger than the whole budget is never cached. */
+    readonly maxTotalSize?: number;
+    readonly sizeOf?: (value: V) => number;
+};
+export type LruCache<K, V> = {
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    delete(key: K): void;
+    clear(): void;
+    readonly size: number;
+};
+export declare function createLruCache<K, V>(options: LruCacheOptions<V>): LruCache<K, V>;

package/dist/utils/lru-cache.js

@@ -0,0 +1,56 @@
+// Map iteration is insertion order: re-inserting on a hit keeps the most recently used entry last.
+export function createLruCache(options) {
+    const now = options.now ?? Date.now;
+    const sizeOf = options.sizeOf ?? (() => 0);
+    const entries = new Map();
+    let totalSize = 0;
+    function remove(key) {
+        const stored = entries.get(key);
+        // skip: key not cached, nothing to remove
+        if (stored === undefined)
+            return;
+        totalSize -= stored.size;
+        entries.delete(key);
+    }
+    function overBudget() {
+        if (entries.size > options.maxEntries)
+            return true;
+        return options.maxTotalSize !== undefined && totalSize > options.maxTotalSize;
+    }
+    return {
+        get(key) {
+            const hit = entries.get(key);
+            if (hit === undefined)
+                return undefined;
+            remove(key);
+            if (options.ttlMs !== undefined && now() - hit.storedAt >= options.ttlMs)
+                return undefined;
+            entries.set(key, hit);
+            totalSize += hit.size;
+            return hit.value;
+        },
+        set(key, value) {
+            remove(key);
+            const size = sizeOf(value);
+            // skip: a value larger than the whole budget would evict everything and still not fit
+            if (options.maxTotalSize !== undefined && size > options.maxTotalSize)
+                return;
+            entries.set(key, { value, storedAt: now(), size });
+            totalSize += size;
+            while (overBudget()) {
+                const oldest = entries.keys().next();
+                if (oldest.done)
+                    break;
+                remove(oldest.value);
+            }
+        },
+        delete: remove,
+        clear() {
+            entries.clear();
+            totalSize = 0;
+        },
+        get size() {
+            return entries.size;
+        },
+    };
+}

package/dist/utils/run-with-timeout.d.ts

@@ -0,0 +1,11 @@
+export type TimedRunResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly latencyMs: number;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+    readonly timedOut: boolean;
+    readonly latencyMs: number;
+};
+export declare function runWithTimeout<T>(run: () => Promise<T>, timeoutMs: number): Promise<TimedRunResult<T>>;

package/dist/utils/run-with-timeout.js

@@ -0,0 +1,30 @@
+class TimeoutError extends Error {
+}
+export async function runWithTimeout(run, timeoutMs) {
+    const start = performance.now();
+    const elapsedMs = () => Math.round(performance.now() - start);
+    let timer;
+    try {
+        const value = await Promise.race([
+            run(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new TimeoutError(`timeout after ${timeoutMs}ms`)), timeoutMs);
+                // Don't keep the event loop alive on a hung run during shutdown.
+                timer.unref?.();
+            }),
+        ]);
+        return { ok: true, value, latencyMs: elapsedMs() };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error,
+            timedOut: error instanceof TimeoutError,
+            latencyMs: elapsedMs(),
+        };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.404.1",
+  "version": "0.405.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,10 +203,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.404.1",
+    "@cosmicdrift/kumiko-types": "0.405.0",
     "bullmq": "^5.81.5",
     "hono": "^4.13.14",
-    "i18next": "^26.5.11",
+    "i18next": "^26.5.12",
     "ioredis": "^5.11.1",
     "jose": "^6.2.14",
     "pino": "^10.4.0",
@@ -225,7 +225,7 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.404.1",
+    "@cosmicdrift/kumiko-testing": "0.405.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.3",
     "meilisearch": "^0.62.0",

package/src/changes.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "chunk in framework utils",
+    "detail": "@cosmicdrift/kumiko-framework/utils exports chunk(items, size), which splits an array into slices of at most size elements. files-tenant-data, subscription-paddle and template-resolver use it instead of local copies."
+  },
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "Search sweep helpers in framework/search",
+    "detail": "@cosmicdrift/kumiko-framework/search exports collectSearchableFieldNames, isEntitySearchable and reindexTenantsSearch(db, registry, adapter, { tenantIds, timeoutMs?, configureTimeoutMs?, dryRun?, warn? }). The sweep configures each given tenant index, then reindexes every searchable entity for those tenants (system-stream entities once under the system tenant) and returns counts of indexed rows and failures. A failed configure or reindex is reported through warn and does not stop the sweep. Apps no longer need their own configure-on-boot seed: the server's default search config is applied lazily to a missing or factory-default index."
+  },
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "createLruCache in framework utils",
+    "detail": "@cosmicdrift/kumiko-framework/utils exports createLruCache({ maxEntries, ttlMs?, now?, maxTotalSize?, sizeOf? }) with get, set, delete, clear and size. The tenant timezone cache and the managed-pages body cache use it. runWithTimeout moves to the utils module; the api barrel export stays."
+  },
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "Engine and db helpers deduplicated",
+    "detail": "The engine uses one findEntity lookup instead of three copies, the PII subject resolver and the boot validator use isFileField, insertOne builds its SQL through the same insert helpers as insertMany, the projection rebuild maps event rows through the shared toStoredEvent, and the app-schema role projection filters row, toolbar and related-list actions through one helper. No behavior change."
+  },
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "One key split for file variants and derivatives",
+    "detail": "deriveKey and the derivative key helpers split a storage key into base and extension through the same function, so both always agree on where the extension starts. No behavior change."
+  },
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "Opaque-token hash and hex helpers exported",
+    "detail": "@cosmicdrift/kumiko-framework/crypto exports hashOpaqueToken (async, Web Crypto), hashOpaqueTokenSync (node:crypto, for synchronous server paths) and opaqueTokenHashMatches (timing-safe comparison against a stored SHA-256 hex hash). @cosmicdrift/kumiko-framework/utils exports bytesToHex and digestHex(algorithm, text). The framework's own token hashes (personal access tokens, single-use token store, preauth MFA key, export download tokens, termination revocation) use them and produce the same hex as before. Apps that hash share or heartbeat tokens themselves can switch to these helpers without migrating stored hashes."
+  },
   {
     "version": "0.404.0",
     "type": "improvement",