@cosmicdrift/kumiko-framework 0.383.1 → 0.385.0

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

@@ -456,7 +456,7 @@ function assertValidScreenMultilineRows(featureName, shortId, screen) {
 // `derived`, `totals`, `totalsMatch`) — a top-level `Array.isArray`/plain-
 // object check alone would let a function survive one level deep.
 //
-// Cast at the exit `as FieldDefinition`: type-system-wise our out-map only
+// Cast at the exit `as EntityFieldDefinition`: type-system-wise our out-map only
 // satisfies the discriminated union with an unnarrowed `type` string — the
 // cast bridges the variant inference TS can't recompute from a generic
 // Record.

package/dist/engine/factories.d.ts

@@ -1,8 +1,8 @@
 import type { EntityTenancy } from "@cosmicdrift/kumiko-types/tenancy-brand";
-import type { BigIntFieldDef, BooleanFieldDef, DateFieldDef, DecimalFieldDef, DerivedFieldDef, EmbeddedFieldDef, EntityDefinition, EntityIndexDef, FieldsMap, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, ResolvedPiiFlags, RetentionDef, SelectFieldDef, TextFieldDef, TimestampFieldDef, TzFieldDef } from "./types/index.ts";
+import type { BigIntFieldDef, BooleanFieldDef, DateFieldDef, DecimalFieldDef, DerivedFieldDef, EmbeddedFieldDef, EntityDefinition, EntityIndexDef, EntityLongTextFieldDef, EntityTextFieldDef, FieldsMap, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, ResolvedPiiFlags, RetentionDef, SelectFieldDef, TextFieldDef, TimestampFieldDef, TzFieldDef } from "./types/index.ts";
 export declare function createTextField<R extends true | false = false>(overrides: Partial<Omit<TextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotations & {
     required?: R;
-}): TextFieldDef & {
+}): EntityTextFieldDef & {
     required: R;
 };
 /**
@@ -25,7 +25,7 @@ export declare function createTextField<R extends true | false = false>(override
 export declare function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef;
 export declare function createLongTextField<R extends true | false = false>(overrides: Partial<Omit<LongTextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsLongText & {
     required?: R;
-}): LongTextFieldDef & {
+}): EntityLongTextFieldDef & {
     required: R;
 };
 export declare function createBooleanField<R extends true | false = false>(overrides?: Partial<Omit<BooleanFieldDef, "type" | "required">> & {

package/dist/engine/steps/read-find-one.js

@@ -1,6 +1,6 @@
 // r.step.read.findOne — load a single row from a projection table.
 //
-// Thin wrapper on selectMany(db, table, where, { limit: 1 }) (bun-db).
+// Thin wrapper on selectMany(db, table, where, { limit: 1 }) (db/query.ts).
 // Resolves to the first row or null. Tenant-filtered like ctx.db
 // method-form reads (own tenant + SYSTEM_TENANT_ID reference rows); a
 // foreign `where.tenantId` is narrowed to the caller's own scope.

package/dist/engine/types/index.d.ts

@@ -6,7 +6,7 @@ export type { KumikoEntityTypeMap, KumikoEventTypeMap, KumikoHandlerPayloadMap,
 export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsMap, } from "@cosmicdrift/kumiko-types/extension-options-map";
 export type { BootCheckContext, BootCheckFn, BootOptionName, EntityObjectDefinition, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, HookDefinition, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StackBootRequirement, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
 export type { FieldIconKey } from "@cosmicdrift/kumiko-types/field-icon";
-export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityEventMigration, EntityIndexDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
+export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityEventMigration, EntityFieldDefinition, EntityIndexDef, EntityLongTextFieldDef, EntityTextFieldDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, ResolvedPiiStance, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
 export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobDeferral, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadBucketNormalization, PayloadRateLimitOption, PreparedWriteEvent, ProviderPluginContext, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitOptions, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TenantWriteTarget, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
 export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, declaredRateLimitOptions, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isRateLimitOption, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export type { DeleteContext, EntityHookMap, HookMap, HookOwner, HookPhase, LifecycleHookFn, LifecycleResult, OwnedFn, PhasedHook, PostDeleteBatchHookFn, PostDeleteHookFn, PostQueryHookFn, PostSaveBatchHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SaveContext, SearchPayloadContributorFn, ValidationError, ValidationHookFn, } from "@cosmicdrift/kumiko-types/hooks";

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

@@ -32,7 +32,7 @@ export async function appendProvenanceEvent(db, event) {
             message: `appendProvenanceEvent: event tenant "${event.tenantId}" does not match the TenantDb's tenant "${db.tenantId}".`,
         });
     }
-    // Bun.SQL/postgres.js abort the whole surrounding begin() on a statement
+    // postgres-js aborts the whole surrounding begin() on a statement
     // error (25P02) even when the caller's catch swallows it — the savepoint
     // confines that to this scope. Pool connections have no ambient tx to poison.
     await runInSavepointIfSupported(runner, async (sp) => {

package/dist/files/file-ref-entity.d.ts

@@ -1,72 +1,12 @@
 export { FILE_REF_ENTITY_NAME } from "./types.ts";
 export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
-    readonly storageKey: {
-        readonly type: "text";
-        readonly description?: string;
-        readonly maxLength?: number;
-        readonly minLength?: number;
-        readonly autoComplete?: string;
-        readonly required?: boolean;
-        readonly searchable?: boolean;
-        readonly sortable?: boolean;
-        readonly filterable?: boolean;
-        readonly encrypted?: boolean;
-        readonly sensitive?: boolean;
-        readonly writeOnly?: boolean;
-        readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
-        readonly default?: string;
-        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-        readonly multiline?: boolean | {
-            readonly rows?: number;
-        };
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    readonly storageKey: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: true;
     };
-    readonly fileName: {
-        readonly type: "text";
-        readonly description?: string;
-        readonly maxLength?: number;
-        readonly minLength?: number;
-        readonly autoComplete?: string;
-        readonly required?: boolean;
-        readonly searchable?: boolean;
-        readonly sortable?: boolean;
-        readonly filterable?: boolean;
-        readonly encrypted?: boolean;
-        readonly sensitive?: boolean;
-        readonly writeOnly?: boolean;
-        readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
-        readonly default?: string;
-        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-        readonly multiline?: boolean | {
-            readonly rows?: number;
-        };
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    readonly fileName: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: true;
     };
-    readonly mimeType: {
-        readonly type: "text";
-        readonly description?: string;
-        readonly maxLength?: number;
-        readonly minLength?: number;
-        readonly autoComplete?: string;
-        readonly required?: boolean;
-        readonly searchable?: boolean;
-        readonly sortable?: boolean;
-        readonly filterable?: boolean;
-        readonly encrypted?: boolean;
-        readonly sensitive?: boolean;
-        readonly writeOnly?: boolean;
-        readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
-        readonly default?: string;
-        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-        readonly multiline?: boolean | {
-            readonly rows?: number;
-        };
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    readonly mimeType: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: true;
     };
     readonly size: {
@@ -81,73 +21,13 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    readonly entityType: {
-        readonly type: "text";
-        readonly description?: string;
-        readonly maxLength?: number;
-        readonly minLength?: number;
-        readonly autoComplete?: string;
-        readonly required?: boolean;
-        readonly searchable?: boolean;
-        readonly sortable?: boolean;
-        readonly filterable?: boolean;
-        readonly encrypted?: boolean;
-        readonly sensitive?: boolean;
-        readonly writeOnly?: boolean;
-        readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
-        readonly default?: string;
-        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-        readonly multiline?: boolean | {
-            readonly rows?: number;
-        };
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    readonly entityType: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: false;
     };
-    readonly entityId: {
-        readonly type: "text";
-        readonly description?: string;
-        readonly maxLength?: number;
-        readonly minLength?: number;
-        readonly autoComplete?: string;
-        readonly required?: boolean;
-        readonly searchable?: boolean;
-        readonly sortable?: boolean;
-        readonly filterable?: boolean;
-        readonly encrypted?: boolean;
-        readonly sensitive?: boolean;
-        readonly writeOnly?: boolean;
-        readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
-        readonly default?: string;
-        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-        readonly multiline?: boolean | {
-            readonly rows?: number;
-        };
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    readonly entityId: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: false;
     };
-    readonly fieldName: {
-        readonly type: "text";
-        readonly description?: string;
-        readonly maxLength?: number;
-        readonly minLength?: number;
-        readonly autoComplete?: string;
-        readonly required?: boolean;
-        readonly searchable?: boolean;
-        readonly sortable?: boolean;
-        readonly filterable?: boolean;
-        readonly encrypted?: boolean;
-        readonly sensitive?: boolean;
-        readonly writeOnly?: boolean;
-        readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
-        readonly default?: string;
-        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-        readonly multiline?: boolean | {
-            readonly rows?: number;
-        };
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    readonly fieldName: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: false;
     };
 }, "tenant">;

package/dist/files/file-ref-table.d.ts

@@ -1,71 +1,11 @@
 export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable<import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
-    readonly storageKey: {
-        readonly type: "text";
-        readonly description?: string;
-        readonly maxLength?: number;
-        readonly minLength?: number;
-        readonly autoComplete?: string;
-        readonly required?: boolean;
-        readonly searchable?: boolean;
-        readonly sortable?: boolean;
-        readonly filterable?: boolean;
-        readonly encrypted?: boolean;
-        readonly sensitive?: boolean;
-        readonly writeOnly?: boolean;
-        readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
-        readonly default?: string;
-        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-        readonly multiline?: boolean | {
-            readonly rows?: number;
-        };
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    readonly storageKey: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: true;
     };
-    readonly fileName: {
-        readonly type: "text";
-        readonly description?: string;
-        readonly maxLength?: number;
-        readonly minLength?: number;
-        readonly autoComplete?: string;
-        readonly required?: boolean;
-        readonly searchable?: boolean;
-        readonly sortable?: boolean;
-        readonly filterable?: boolean;
-        readonly encrypted?: boolean;
-        readonly sensitive?: boolean;
-        readonly writeOnly?: boolean;
-        readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
-        readonly default?: string;
-        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-        readonly multiline?: boolean | {
-            readonly rows?: number;
-        };
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    readonly fileName: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: true;
     };
-    readonly mimeType: {
-        readonly type: "text";
-        readonly description?: string;
-        readonly maxLength?: number;
-        readonly minLength?: number;
-        readonly autoComplete?: string;
-        readonly required?: boolean;
-        readonly searchable?: boolean;
-        readonly sortable?: boolean;
-        readonly filterable?: boolean;
-        readonly encrypted?: boolean;
-        readonly sensitive?: boolean;
-        readonly writeOnly?: boolean;
-        readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
-        readonly default?: string;
-        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-        readonly multiline?: boolean | {
-            readonly rows?: number;
-        };
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    readonly mimeType: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: true;
     };
     readonly size: {
@@ -80,73 +20,13 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    readonly entityType: {
-        readonly type: "text";
-        readonly description?: string;
-        readonly maxLength?: number;
-        readonly minLength?: number;
-        readonly autoComplete?: string;
-        readonly required?: boolean;
-        readonly searchable?: boolean;
-        readonly sortable?: boolean;
-        readonly filterable?: boolean;
-        readonly encrypted?: boolean;
-        readonly sensitive?: boolean;
-        readonly writeOnly?: boolean;
-        readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
-        readonly default?: string;
-        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-        readonly multiline?: boolean | {
-            readonly rows?: number;
-        };
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    readonly entityType: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: false;
     };
-    readonly entityId: {
-        readonly type: "text";
-        readonly description?: string;
-        readonly maxLength?: number;
-        readonly minLength?: number;
-        readonly autoComplete?: string;
-        readonly required?: boolean;
-        readonly searchable?: boolean;
-        readonly sortable?: boolean;
-        readonly filterable?: boolean;
-        readonly encrypted?: boolean;
-        readonly sensitive?: boolean;
-        readonly writeOnly?: boolean;
-        readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
-        readonly default?: string;
-        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-        readonly multiline?: boolean | {
-            readonly rows?: number;
-        };
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    readonly entityId: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: false;
     };
-    readonly fieldName: {
-        readonly type: "text";
-        readonly description?: string;
-        readonly maxLength?: number;
-        readonly minLength?: number;
-        readonly autoComplete?: string;
-        readonly required?: boolean;
-        readonly searchable?: boolean;
-        readonly sortable?: boolean;
-        readonly filterable?: boolean;
-        readonly encrypted?: boolean;
-        readonly sensitive?: boolean;
-        readonly writeOnly?: boolean;
-        readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
-        readonly default?: string;
-        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-        readonly multiline?: boolean | {
-            readonly rows?: number;
-        };
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    readonly fieldName: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: false;
     };
 }, "tenant">>;

package/dist/files/file-routes.js

@@ -23,6 +23,9 @@ const DEFAULT_PRIVILEGED_ROLES = ["Admin", "SystemAdmin"];
 // leaked URL (e.g. from a browser history screenshot) isn't a long-lived
 // credential (see "Signed-URL default expiry" in core-files.md).
 const SIGNED_URL_DEFAULT_EXPIRY_SECONDS = 15 * 60;
+const MAX_BATCH_META_IDS = 100;
+// Each detail() read decrypts through the KMS pool; a bounded chunk keeps one batch from hogging it.
+const BATCH_META_CONCURRENCY = 10;
 // Default guard: on attached files, allow the uploader or a privileged role,
 // and for reads also everyone who may read the record. Delete stays with the
 // uploader and privileged roles: reading a record is no right to remove its
@@ -218,6 +221,25 @@ export function createFileRoutes(options) {
             return c.json({ error: "upload_failed" }, 500);
         return c.json(outcome.fileRef, 201);
     });
+    // GET /files/meta?ids=a,b,c — meta of many files in one request (list/card
+    // cells otherwise fire one request per row). Unreadable and unknown ids are
+    // left out of the answer, same as /files/:id/meta answering 404 for them.
+    // Registered before /files/:id so "meta" is never taken for an id.
+    api.get("/files/meta", async (c) => {
+        const user = getUser(c);
+        const ids = [...new Set((c.req.query("ids") ?? "").split(",").filter((id) => isUuid(id)))];
+        if (ids.length > MAX_BATCH_META_IDS)
+            return c.json({ error: "too_many_ids" }, 400);
+        const files = [];
+        for (let start = 0; start < ids.length; start += BATCH_META_CONCURRENCY) {
+            const chunk = ids.slice(start, start + BATCH_META_CONCURRENCY);
+            const metas = await Promise.all(chunk.map((id) => loadReadableFileMeta(id, user)));
+            for (const meta of metas)
+                if (meta)
+                    files.push(meta);
+        }
+        return c.json({ files });
+    });
     // GET /files/:id — download.
     //
     // Authorization stack:
@@ -388,31 +410,28 @@ export function createFileRoutes(options) {
         const expiresAt = new Date(Date.now() + expiresInSeconds * 1000).toISOString();
         return c.json({ url, expiresAt });
     });
-    // GET /files/:id/meta — metadata without the bytes. Unlike the byte-serving
-    // routes above, this returns fileName as JSON — and fileName is
-    // `personal: "self"` (fw#2423), so it must go through the entity executor's
-    // detail() to decrypt instead of loadFileForTenant's raw, still-encrypted read.
-    api.get("/files/:id/meta", async (c) => {
-        const user = getUser(c);
-        const id = c.req.param("id");
+    // Metadata without the bytes. Unlike the byte-serving routes, this returns
+    // fileName as JSON — and fileName is `personal: "self"` (fw#2423), so it must
+    // go through the entity executor's detail() to decrypt instead of
+    // loadFileForTenant's raw, still-encrypted read.
+    async function loadReadableFileMeta(id, user) {
         // Same 22P02-avoidance as loadFileForTenant — detail() doesn't validate
         // id shape before it hits the UUID column.
         if (!isUuid(id))
-            return c.json({ error: "not_found" }, 404);
+            return null;
         const row = await executor.detail({ id }, user, tenantDbFor(user.tenantId));
         if (!row)
-            return c.json({ error: "not_found" }, 404);
+            return null;
         const fileRef = row; // @cast-boundary db-row (decrypted via executor.detail)
         // detail()'s "pass"-ownership read widens to tenantId IN (self, SYSTEM),
         // narrower in loadFileForTenant's selectMany. Restore that here so meta
         // doesn't leak reference-tenant rows.
-        if (fileRef.tenantId !== user.tenantId) {
-            return c.json({ error: "not_found" }, 404);
-        }
+        if (fileRef.tenantId !== user.tenantId)
+            return null;
         const decision = await guard({ fileRef, user, operation: "read" });
         if (decision === "deny")
-            return c.json({ error: "not_found" }, 404);
-        return c.json({
+            return null;
+        return {
             id: fileRef.id,
             fileName: fileRef.fileName,
             mimeType: fileRef.mimeType,
@@ -420,11 +439,15 @@ export function createFileRoutes(options) {
             entityType: fileRef.entityType,
             entityId: fileRef.entityId,
             fieldName: fileRef.fieldName,
-        });
+        };
+    }
+    api.get("/files/:id/meta", async (c) => {
+        const meta = await loadReadableFileMeta(c.req.param("id"), getUser(c));
+        return meta ? c.json(meta) : c.json({ error: "not_found" }, 404);
     });
     async function loadFileForTenant(id, tenantId) {
         // fileRefsTable.id is a UUID column — a malformed id must fail here, not
-        // at Postgres (22P02 poisons the pooled Bun.SQL connection). 404, not
+        // at Postgres (22P02 poisons the pooled connection). 404, not
         // 400: an authenticated caller sending a bad id must see the same
         // response as a nonexistent one, no existence-oracle.
         if (!isUuid(id))

package/dist/i18n/required-surface-keys.d.ts

@@ -31,5 +31,25 @@ export type TranslationLocaleGap = {
     readonly key: string;
     readonly missingLocales: readonly string[];
 };
-/** Locale completeness is opt-in via @cosmicdrift/kumiko-locale-* packages. */
-export declare function findTranslationLocaleGaps(_features: readonly FeatureDefinition[]): readonly TranslationLocaleGap[];
+/**
+ * Per feature, every translation key must carry every locale that any key of the
+ * same feature carries. A feature with a single locale across all keys is
+ * consistent by definition (locale packages, en-only framework features).
+ */
+export declare function findTranslationLocaleGaps(features: readonly FeatureDefinition[]): readonly TranslationLocaleGap[];
+export type RequiredLocaleGap = {
+    readonly featureName: string;
+    readonly key: string;
+    readonly missingLocales: readonly string[];
+};
+/**
+ * Per translation key, the union of locales over ALL features must cover
+ * `requiredLocales`. Locale packages translate other features' keys under the
+ * full `feature:key` name, so the lookup unions by effective name. Raw names
+ * only come from locale packages and already-prefixed keys. Entries that only translate another
+ * mounted feature's key are not reported separately; the defining feature is.
+ * Locale packages (`locale-*`) only contribute locales: their keys often belong to
+ * client bundles (e.g. `auth.errors.*`) that no feature defines, so they are never
+ * reported as gap owners.
+ */
+export declare function findRequiredLocaleGaps(features: readonly FeatureDefinition[], requiredLocales: readonly string[]): readonly RequiredLocaleGap[];

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

@@ -519,7 +519,95 @@ export function buildEffectiveTranslationKeys(features) {
     }
     return out;
 }
-/** Locale completeness is opt-in via @cosmicdrift/kumiko-locale-* packages. */
-export function findTranslationLocaleGaps(_features) {
-    return [];
+function hasLocaleValue(value) {
+    if (value === undefined)
+        return false;
+    return typeof value === "string" ? value !== "" : true;
+}
+/**
+ * Per feature, every translation key must carry every locale that any key of the
+ * same feature carries. A feature with a single locale across all keys is
+ * consistent by definition (locale packages, en-only framework features).
+ */
+export function findTranslationLocaleGaps(features) {
+    const gaps = [];
+    for (const feature of features) {
+        const entries = Object.entries(feature.translations ?? {});
+        const featureLocales = new Set();
+        for (const [, byLocale] of entries) {
+            for (const locale of Object.keys(byLocale))
+                featureLocales.add(locale);
+        }
+        if (featureLocales.size < 2)
+            continue;
+        const sortedLocales = [...featureLocales].sort();
+        for (const [key, byLocale] of entries) {
+            const missingLocales = sortedLocales.filter((locale) => !hasLocaleValue(byLocale[locale]));
+            if (missingLocales.length > 0)
+                gaps.push({ featureName: feature.name, key, missingLocales });
+        }
+    }
+    return gaps;
+}
+const LOCALE_PACKAGE_PREFIX = "locale-";
+function collectLocalesByName(features) {
+    // A plain key of a regular feature is only its own; registering it raw would let two
+    // features with the same plain key cover each other's missing locales.
+    const namesOf = (featureName, key) => featureName.startsWith(LOCALE_PACKAGE_PREFIX) || key.includes(":")
+        ? [`${featureName}:${key}`, key]
+        : [`${featureName}:${key}`];
+    const localesByName = new Map();
+    for (const feature of features) {
+        for (const [key, byLocale] of Object.entries(feature.translations ?? {})) {
+            const present = Object.entries(byLocale)
+                .filter(([, value]) => hasLocaleValue(value))
+                .map(([locale]) => locale);
+            for (const name of namesOf(feature.name, key)) {
+                const locales = localesByName.get(name) ?? new Set();
+                for (const locale of present)
+                    locales.add(locale);
+                localesByName.set(name, locales);
+            }
+        }
+    }
+    return localesByName;
+}
+/**
+ * Per translation key, the union of locales over ALL features must cover
+ * `requiredLocales`. Locale packages translate other features' keys under the
+ * full `feature:key` name, so the lookup unions by effective name. Raw names
+ * only come from locale packages and already-prefixed keys. Entries that only translate another
+ * mounted feature's key are not reported separately; the defining feature is.
+ * Locale packages (`locale-*`) only contribute locales: their keys often belong to
+ * client bundles (e.g. `auth.errors.*`) that no feature defines, so they are never
+ * reported as gap owners.
+ */
+export function findRequiredLocaleGaps(features, requiredLocales) {
+    const featureNames = new Set(features.map((feature) => feature.name));
+    const localesByName = collectLocalesByName(features);
+    const gaps = [];
+    const reported = new Set();
+    for (const feature of features) {
+        if (feature.name.startsWith(LOCALE_PACKAGE_PREFIX))
+            continue;
+        for (const key of Object.keys(feature.translations ?? {})) {
+            const prefix = key.includes(":") ? key.slice(0, key.indexOf(":")) : undefined;
+            const translatesOtherFeature = prefix !== undefined && prefix !== feature.name && featureNames.has(prefix);
+            if (translatesOtherFeature)
+                continue;
+            const effective = key.includes(":") ? key : `${feature.name}:${key}`;
+            if (reported.has(effective))
+                continue;
+            // Locale packages spell plurals as flat `.one`/`.other` keys; `other` is the form every locale has.
+            const present = new Set([effective, key, `${effective}.other`, `${key}.other`].flatMap((name) => [
+                ...(localesByName.get(name) ?? []),
+            ]));
+            const missingLocales = requiredLocales.filter((locale) => !present.has(locale));
+            if (missingLocales.length > 0) {
+                reported.add(effective);
+                gaps.push({ featureName: feature.name, key, missingLocales });
+            }
+        }
+    }
+    return gaps;
 }

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

@@ -0,0 +1,45 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+import type { ConfigAccessor } from "@cosmicdrift/kumiko-types/config";
+import type { TzContext } from "@cosmicdrift/kumiko-types/tz-context";
+import type { JobsOptions, Queue } from "bullmq";
+import type { TenantDb } from "../db/tenant-db.ts";
+import type { AppContext, EscapeHatchReporter, JobContext, JobDefinition, JobRunIn, JobTriggerEvent } from "../engine/types/index.ts";
+import type { Logger } from "../logging/types.ts";
+import type { Meter, SerializedTraceContext, Tracer } from "../observability/index.ts";
+import type { JobLogEntry, JobSubjectValue } from "./job-runner-types.ts";
+export declare function isJobTriggerEvent(value: unknown): value is JobTriggerEvent;
+export declare function stampGatedWriteOrigin(data: Record<string, unknown>): void;
+export declare function createJobLogger(logs: JobLogEntry[], baseContext?: Record<string, unknown>): Logger;
+export declare function serializeJobSubject(subject: Readonly<Record<string, JobSubjectValue>>): string;
+export declare function jobSubjectKey(jobName: string, payload: Record<string, unknown>, fields: readonly string[] | undefined, declaration: "tenantVisibleFailure" | "tenantVisibleRun"): string | null;
+export declare function resolveJobTz(config: ConfigAccessor | undefined, context: Pick<AppContext, "geoTzProvider" | "clock">): Promise<TzContext>;
+export declare function missingDbProxy(jobName: string): TenantDb;
+export declare function createCrossTenantReads(systemModeDb: TenantDb, reason: string, report: EscapeHatchReporter): NonNullable<JobContext["crossTenantReads"]>;
+export declare function priorAttemptsOf(data: Record<string, unknown>): number;
+export declare function tenantFailureMessageKey(err: unknown, declaration: JobDefinition["tenantVisibleFailure"]): string | null;
+export declare const TRACE_CONTEXT_KEY = "_traceContext";
+export declare const DEFER_COUNT_KEY = "_deferCount";
+export declare const HANDLER_DEFER_COUNT_KEY = "_handlerDeferCount";
+export declare const DEFAULT_MAX_DEFERS = 100;
+export declare const DEFER_DELAY_CAP_MS = 30000;
+export declare const DEFER_BACKOFF_MAX_DOUBLINGS = 5;
+export declare function readTraceContext(data: Record<string, unknown>): SerializedTraceContext | undefined;
+export declare function captureTraceContext(tracer: Tracer): SerializedTraceContext | undefined;
+export declare function startQueueDepthPolling(queue: Queue, lane: JobRunIn, meter: Meter): Promise<ReturnType<typeof setInterval>>;
+export declare function parseRedisOpts(url: string): {
+    host: string;
+    port: number;
+    db?: number | undefined;
+};
+export declare const BOOT_REDIS_TIMEOUT_MS = 10000;
+export declare const STOP_QUEUE_READY_TIMEOUT_MS = 1000;
+export declare const BOOT_GATE_SLOW_WARN_MS = 60000;
+export declare function timeoutReject(ms: number, message: string): {
+    promise: Promise<never>;
+    cancel: () => void;
+};
+export declare function buildRetryBullOpts(jobDef: JobDefinition, priorAttempts?: number): Pick<JobsOptions, "attempts" | "backoff">;
+export declare function payloadMatchesTriggerFilter(where: Readonly<Record<string, string | number | boolean>> | undefined, payload: Record<string, unknown>): boolean;
+export declare const COMPLETED_JOB_RETENTION_AGE_SEC = 86400;
+export declare const FAILED_JOB_RETENTION_AGE_SEC = 604800;
+export declare function maxRetryWindowMs(jobDef: JobDefinition): number;