@cosmicdrift/kumiko-framework 0.383.0 → 0.384.0

package/agents/examples/custom-fields-basic.md

@@ -239,7 +239,7 @@ import {
   wireCustomFieldsFor,
 } from "@cosmicdrift/kumiko-bundled-features/custom-fields";
 import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
-import { createEntity, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 
 // --- Entity ---
@@ -254,7 +254,12 @@ import { z } from "zod";
 export const propertyEntity = createEntity({
   table: "read_sample_cf_properties",
   fields: {
-    name: { type: "text", required: true, maxLength: 200 },
+    name: createTextField({
+      required: true,
+      maxLength: 200,
+      personal: false,
+      reason: "property_name_is_business_data",
+    }),
     customFields: customFieldsField(),
   },
 });
@@ -274,7 +279,12 @@ export const propertyFeature = defineFeature("property-management", (r) => {
     name: "property",
     table: "read_sample_cf_properties",
     fields: {
-      name: { type: "text", required: true, maxLength: 200 },
+      name: createTextField({
+        required: true,
+        maxLength: 200,
+        personal: false,
+        reason: "property_name_is_business_data",
+      }),
       customFields: { type: "jsonb" },
     },
   });

package/agents/examples/designer-demo.md

@@ -36,7 +36,7 @@ No dedicated automated tests in this folder yet — use it as a composition samp
 //   - nav         → ID/Label/Screen-Card
 // Plus optionalRequires + metric als JSON-Dump-Fallback.
 
-import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 
 defineFeature("designerDemo", (r) => {
@@ -45,7 +45,11 @@ defineFeature("designerDemo", (r) => {
   r.entity({
     name: "task",
     fields: {
-      title: { type: "text", required: true },
+      title: createTextField({
+        required: true,
+        personal: false,
+        reason: "demo_task_title_is_not_personal_data",
+      }),
       done: { type: "boolean", default: false },
       priority: { type: "select", options: ["low", "medium", "high"], default: "medium" },
     },

package/dist/db/connection.d.ts

@@ -22,7 +22,11 @@ export type DbConnectionHandle = {
     close: () => Promise<void>;
 };
 export declare const DEFAULT_DB_CLOSE_TIMEOUT_SECONDS = 5;
-export declare function openUnboundedSiblingPool(db: unknown): PgClient | undefined;
+export type UnboundedSiblingPool = {
+    readonly client: PgClient;
+    readonly close: (timeoutSeconds: number) => Promise<void>;
+};
+export declare function openUnboundedSiblingPool(db: unknown): UnboundedSiblingPool | undefined;
 export declare function createDbConnection({ url, ...options }: CreateDbConnectionOptions): DbConnectionHandle;
 export declare function dbConnectionOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): DbConnectionOptions;
 export declare const DEFAULT_SERVER_STATEMENT_TIMEOUT_MS = 60000;

package/dist/db/connection.js

@@ -38,18 +38,38 @@ export function createDbConnection({ url, ...options }) {
     if (Object.keys(serverParameters).length > 0)
         pgOptions.connection = serverParameters;
     const client = postgres(url, pgOptions);
-    // Two connections are enough for lock-in-tx plus DDL; the cap keeps parallel rebuilds from exhausting max_connections.
-    unboundedSiblingFactories.set(client, () => postgres(url, {
-        ...pgOptions,
-        max: 4,
-        connection: { ...pgOptions.connection, statement_timeout: 0 },
-    }));
+    // A run that never settles (a caller gave up on it via its own timeout) never reaches the
+    // sibling's own close; close() ends it so shutdown and DROP DATABASE are not blocked by it.
+    const openSiblings = new Set();
+    unboundedSiblingFactories.set(client, () => {
+        // Two connections are enough for lock-in-tx plus DDL; the cap keeps parallel rebuilds from exhausting max_connections.
+        const sibling = postgres(url, {
+            ...pgOptions,
+            max: 4,
+            connection: { ...pgOptions.connection, statement_timeout: 0 },
+        });
+        openSiblings.add(sibling);
+        return {
+            client: sibling,
+            close: async (timeoutSeconds) => {
+                openSiblings.delete(sibling);
+                await sibling.end({ timeout: timeoutSeconds });
+            },
+        };
+    });
     return {
         db: client,
         client,
-        close: () => client.end({
-            timeout: options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS,
-        }),
+        close: async () => {
+            const timeout = options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS;
+            unboundedSiblingFactories.delete(client);
+            const pools = [client, ...openSiblings];
+            openSiblings.clear();
+            const results = await Promise.allSettled(pools.map((pool) => pool.end({ timeout })));
+            const failure = results.find((result) => result.status === "rejected");
+            if (failure !== undefined)
+                throw failure.reason;
+        },
     };
 }
 // DB_PROVIDER=bun selected the removed Bun.SQL driver; ignoring it would boot

package/dist/db/query.js

@@ -147,7 +147,17 @@ function assertNotTenantScoped(db, fnName) {
             "explicit cross-tenant op, or use a scoped TenantDb method.");
     }
 }
-const WHERE_OPERATOR_KEYS = ["gt", "gte", "lt", "lte", "ne", "in", "like", "jsonText"];
+const WHERE_OPERATOR_KEYS = [
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "ne",
+    "in",
+    "notIn",
+    "like",
+    "jsonText",
+];
 const _whereOperatorKeysExhaustive = true;
 void _whereOperatorKeysExhaustive;
 function isJsonTextMatchList(value) {
@@ -664,6 +674,24 @@ function buildWhereClause(info, where, startIndex, qualifier) {
                     conditions.push(`${ref(col)} IN (${parts.join(", ")})`);
                 }
             }
+            const notInVal = value.notIn;
+            if (Array.isArray(notInVal)) {
+                if (pgType === "jsonb") {
+                    throw new Error(`where: notIn is not supported on jsonb column "${col}"`);
+                }
+                const parts = [];
+                for (const v of notInVal) {
+                    const p = prepareValue(v, pgType);
+                    if (p.kind === "literal") {
+                        parts.push(p.literal);
+                    }
+                    else {
+                        parts.push(`$${idx++}${p.sql}`);
+                        values.push(p.bound);
+                    }
+                }
+                conditions.push(parts.length === 0 ? "TRUE" : `${ref(col)} NOT IN (${parts.join(", ")})`);
+            }
         }
         else if (pgType === "jsonb" && isJsonbScalar(value)) {
             conditions.push(jsonbContainsAny(col, [value]));

package/dist/db/statement-timeout.js

@@ -10,9 +10,9 @@ export async function withoutStatementTimeout(db, run) {
     if (unbounded === undefined)
         return run(db);
     try {
-        return await run(unbounded);
+        return await run(unbounded.client);
     }
     finally {
-        await unbounded.end({ timeout: UNBOUNDED_POOL_CLOSE_TIMEOUT_SECONDS });
+        await unbounded.close(UNBOUNDED_POOL_CLOSE_TIMEOUT_SECONDS);
     }
 }

package/dist/engine/boot-validator/i18n-keys.d.ts

@@ -1,2 +1,3 @@
 import type { FeatureDefinition } from "../types/index.ts";
 export declare function validateI18nSurfaceKeys(features: readonly FeatureDefinition[]): void;
+export declare function validateTranslationLocaleConsistency(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/i18n-keys.js

@@ -1,4 +1,4 @@
-import { buildEffectiveTranslationKeys, featureHasI18nSurface, requiredKeysFromFeature, requiredKeysFromNav, requiredKeysFromScreen, requiredKeysFromWorkspace, screenTitleKey, } from "../../i18n/required-surface-keys.js";
+import { buildEffectiveTranslationKeys, featureHasI18nSurface, findTranslationLocaleGaps, requiredKeysFromFeature, requiredKeysFromNav, requiredKeysFromScreen, requiredKeysFromWorkspace, screenTitleKey, } from "../../i18n/required-surface-keys.js";
 import { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, } from "../build-config-feature-schema.js";
 import { EXTENSION_SELECTOR_HINT_KEY } from "../extension-selector-plugins.js";
 import { createRegistry } from "../registry.js";
@@ -86,3 +86,10 @@ export function validateI18nSurfaceKeys(features) {
         }
     }
 }
+export function validateTranslationLocaleConsistency(features) {
+    const gaps = findTranslationLocaleGaps(features);
+    if (gaps.length > 0) {
+        const lines = gaps.map((gap) => `[i18n] Feature "${gap.featureName}": translation key "${gap.key}" is missing locale(s) ${gap.missingLocales.join(", ")}.`);
+        throw new Error(`${lines.join("\n")}\nEvery locale a feature uses must be maintained for every one of its translation keys; otherwise move that locale into a locale package.`);
+    }
+}

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

@@ -15,7 +15,7 @@ import { validateEntityListScreens } from "./entity-list-screens.js";
 import { validateGdprStoragePersistence } from "./gdpr-storage.js";
 import { validateGlobalTenancyEntities } from "./global-tenancy.js";
 import { validateHandlerFieldReferences } from "./handler-field-references.js";
-import { validateI18nSurfaceKeys } from "./i18n-keys.js";
+import { validateI18nSurfaceKeys, validateTranslationLocaleConsistency } from "./i18n-keys.js";
 import { collectKnownRoles, collectNavQns, collectWriteHandlerQns, validateNavCycles, validateNavs, warnOnNavAccessInversion, warnOnUnreachableNavScreens, } from "./nav.js";
 import { collectClaimKeys, validateOwnershipRules } from "./ownership.js";
 import { validateParentRefs } from "./parent-ref.js";
@@ -218,6 +218,7 @@ export function validateBoot(rawFeatures, options) {
     }
     validateDefaultWorkspaceUniqueness(allWorkspaceQns);
     validateI18nSurfaceKeys(features);
+    validateTranslationLocaleConsistency(features);
     validateEntityListScreens(features);
     validateSubmitPrefilledHiddenFields(features);
     validateCardMetaOverflow(features);

package/dist/engine/boot-validator/pii-retention.js

@@ -1,6 +1,4 @@
-import { createFallbackLogger } from "../../logging/utils.js";
 import { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./entity-handler.js";
-const log = createFallbackLogger("kumiko:boot");
 // Framework-managed Timestamp-Spalten — dürfen als retention.reference
 // genutzt werden auch wenn nicht in entity.fields deklariert.
 const FRAMEWORK_TIMESTAMP_FIELDS = new Set([
@@ -146,6 +144,12 @@ export function validatePiiAndRetention(feature) {
             if (annotCount > 1) {
                 throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has multiple subject-key annotations (personal: "self" / "tenant" / { of: "<field>" }). Pick one — each field belongs to exactly one subject.`);
             }
+            if ((field.type === "text" || field.type === "longText") &&
+                annotCount === 0 &&
+                !annot.allowPlaintext &&
+                !annot.subjectRef) {
+                throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" (type "${field.type}") declares no personal stance. Build it with createTextField / createLongTextField and { personal: "self" | "tenant" | "ref" | { of: "<ownerField>" } | false }; false additionally needs { reason: "..." } stating why the value is not personal data.`);
+            }
             // lookupable (#818): nur text + nur MIT Subject-Annotation. Ohne
             // Subject bleibt der Wert eh Klartext — der Blind-Index wäre eine
             // zweite (deterministische!) Kopie ohne Nutzen.
@@ -247,11 +251,6 @@ export function validatePiiAndRetention(feature) {
                     // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
                     console.warn(`[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no personal annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { personal: "ref" } AND register r.useExtension(EXT_USER_DATA, "${entityName}", …) for Art.17 coverage — this warning is the only boot-time check for that, registering the hook is not enforced. Or { personal: { of: "${fieldName}" } } on the field it owns. If business data, set { personal: false, reason: "..." } to silence.`);
                 }
-                else if (!annot.subjectRef && (field.type === "text" || field.type === "longText")) {
-                    // The factories refuse a missing stance, but a raw literal such as
-                    // { type: "text" } still compiles and reaches the entity unchecked.
-                    log.warn(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" (type "${field.type}") declares no personal stance. Declare { personal: "self" | "tenant" | "ref" | { of: "<ownerField>" } | false } via createTextField / createLongTextField; "false" additionally needs { reason: "..." } stating why the value is not personal data.`);
-                }
             }
         }
         // --- Entity-level retention ---

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/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/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,7 +439,11 @@ 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

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

@@ -31,5 +31,9 @@ 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[];

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

@@ -519,7 +519,33 @@ 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;
 }

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

@@ -1,5 +1,10 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
-import type { DbConnection } from "../db/connection.ts";
+import type { DbRunner } from "../db/connection.ts";
+export type ConsumerTransitionRejection = "unknown-consumer" | "wrong-status";
+export declare class ConsumerTransitionError extends Error {
+    readonly rejection: ConsumerTransitionRejection;
+    constructor(rejection: ConsumerTransitionRejection, message: string);
+}
 export type ConsumerRecoveryState = {
     readonly name: string;
     readonly instanceId: string;
@@ -10,13 +15,15 @@ export type ConsumerRecoveryState = {
     readonly lastError: string | null;
     readonly updatedAt: Temporal.Instant;
 };
-export declare function restartConsumer(db: DbConnection, name: string, instanceId?: string): Promise<ConsumerRecoveryState>;
-export declare function disableConsumer(db: DbConnection, name: string, instanceId?: string): Promise<ConsumerRecoveryState>;
-export declare function enableConsumer(db: DbConnection, name: string, instanceId?: string): Promise<ConsumerRecoveryState>;
-export declare function skipPoisonEvent(db: DbConnection, name: string, instanceId?: string): Promise<ConsumerRecoveryState & {
+export declare function restartConsumer(db: DbRunner, name: string, instanceId?: string): Promise<ConsumerRecoveryState>;
+export declare function disableConsumer(db: DbRunner, name: string, instanceId?: string): Promise<ConsumerRecoveryState>;
+export declare function enableConsumer(db: DbRunner, name: string, instanceId?: string): Promise<ConsumerRecoveryState>;
+export declare function skipPoisonEvent(db: DbRunner, name: string, instanceId?: string, options?: {
+    readonly requireStatus?: string;
+}): Promise<ConsumerRecoveryState & {
     readonly skippedEventId: bigint | null;
 }>;
-export declare function getConsumerState(db: DbConnection, name: string, instanceId?: string): Promise<{
+export declare function getConsumerState(db: DbRunner, name: string, instanceId?: string): Promise<{
     readonly name: string;
     readonly instanceId: string;
     readonly status: string;
@@ -26,7 +33,7 @@ export declare function getConsumerState(db: DbConnection, name: string, instanc
     readonly lastError: string | null;
     readonly updatedAt: Temporal.Instant;
 } | null>;
-export declare function listConsumersWithState(db: DbConnection, registeredNames: readonly string[]): Promise<ReadonlyArray<{
+export declare function listConsumersWithState(db: DbRunner, registeredNames: readonly string[]): Promise<ReadonlyArray<{
     readonly name: string;
     readonly instanceId: string;
     readonly status: string;
@@ -44,4 +51,4 @@ export type ConsumerProgress = {
     readonly highWaterMark: bigint;
     readonly lag: bigint;
 };
-export declare function getAllConsumerProgress(db: DbConnection, registeredNames: readonly string[]): Promise<readonly ConsumerProgress[]>;
+export declare function getAllConsumerProgress(db: DbRunner, registeredNames: readonly string[]): Promise<readonly ConsumerProgress[]>;

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

@@ -1,6 +1,6 @@
 import { advanceConsumerPastEventReturning, removePendingGapReturning, selectConsumerForUpdate, selectSnapshotXmax, updateConsumerStatusReturning, } from "../db/queries/event-consumer.js";
 import { selectNextEventIdAfter, selectSmallestVisibleIdInRanges, } from "../db/queries/event-store.js";
-import { coerceRow, extractTableInfo, selectMany } from "../db/query.js";
+import { coerceRow, extractTableInfo, runInNewTransaction, runInSavepointIfSupported, runnerCanBeginTransaction, selectMany, } from "../db/query.js";
 import { getEventsHighWaterMark } from "../event-store/index.js";
 import { eventConsumerStateTable, SHARED_INSTANCE_SENTINEL, } from "./event-consumer-state.js";
 import { mergeContiguousGapRanges, rangeContainsId, splitRangeExcludingIds, toIdRanges, } from "./pending-gap-ranges.js";
@@ -33,6 +33,14 @@ function normalizeConsumerState(row) {
         updatedAt: row.updatedAt,
     };
 }
+export class ConsumerTransitionError extends Error {
+    rejection;
+    constructor(rejection, message) {
+        super(message);
+        this.rejection = rejection;
+        this.name = "ConsumerTransitionError";
+    }
+}
 // Ops calls default to the SHARED_INSTANCE_SENTINEL row — that's the only
 // row shared-delivery consumers have, so legacy CLI invocations without
 // --instance-id keep working. Per-instance consumers require an explicit
@@ -45,7 +53,7 @@ async function requireConsumerRow(db, name, instanceId) {
         instanceId,
     });
     if (!row) {
-        throw new Error(`Consumer "${name}" (instance_id="${instanceId}") has no state row — it hasn't run yet, the name is misspelled, or the instance is misspelled. ` +
+        throw new ConsumerTransitionError("unknown-consumer", `Consumer "${name}" (instance_id="${instanceId}") has no state row — it hasn't run yet, the name is misspelled, or the instance is misspelled. ` +
             `For per-instance consumers pass the instance_id explicitly; shared consumers use the default.`);
     }
     return row;
@@ -53,7 +61,7 @@ async function requireConsumerRow(db, name, instanceId) {
 async function requireConsumerRowForUpdate(tx, name, instanceId) {
     const raw = await selectConsumerForUpdate(tx, name, instanceId);
     if (!raw) {
-        throw new Error(`Consumer "${name}" (instance_id="${instanceId}") has no state row — it hasn't run yet, the name is misspelled, or the instance is misspelled. ` +
+        throw new ConsumerTransitionError("unknown-consumer", `Consumer "${name}" (instance_id="${instanceId}") has no state row — it hasn't run yet, the name is misspelled, or the instance is misspelled. ` +
             `For per-instance consumers pass the instance_id explicitly; shared consumers use the default.`);
     }
     return coerceRow(raw, extractTableInfo(eventConsumerStateTable));
@@ -69,7 +77,7 @@ async function applyConsumerStatusTransition(db, name, instanceId, targetStatus)
 export async function restartConsumer(db, name, instanceId = SHARED_INSTANCE_SENTINEL) {
     const before = await requireConsumerRow(db, name, instanceId);
     if (before.status !== "dead") {
-        throw new Error(`Consumer "${name}" (instance_id="${instanceId}") is not dead (status="${before.status}"). Restart only applies to dead consumers; use "enable" for a disabled one.`);
+        throw new ConsumerTransitionError("wrong-status", `Consumer "${name}" (instance_id="${instanceId}") is not dead (status="${before.status}"). Restart only applies to dead consumers; use "enable" for a disabled one.`);
     }
     return applyConsumerStatusTransition(db, name, instanceId, "idle");
 }
@@ -80,10 +88,17 @@ export async function disableConsumer(db, name, instanceId = SHARED_INSTANCE_SEN
 export async function enableConsumer(db, name, instanceId = SHARED_INSTANCE_SENTINEL) {
     const before = await requireConsumerRow(db, name, instanceId);
     if (before.status !== "disabled") {
-        throw new Error(`Consumer "${name}" (instance_id="${instanceId}") is not disabled (status="${before.status}"). Enable only flips disabled → idle; use "restart" for a dead consumer.`);
+        throw new ConsumerTransitionError("wrong-status", `Consumer "${name}" (instance_id="${instanceId}") is not disabled (status="${before.status}"). Enable only flips disabled → idle; use "restart" for a dead consumer.`);
     }
     return applyConsumerStatusTransition(db, name, instanceId, "idle");
 }
+// A pool connection opens its own transaction; inside a handler transaction the
+// locked read and writes join it, confined to a savepoint.
+function runInOwnTransactionOrSavepoint(db, fn) {
+    return runnerCanBeginTransaction(db)
+        ? runInNewTransaction(db, fn)
+        : runInSavepointIfSupported(db, fn);
+}
 // Delivery stops at the poison event, so ids between the cursor and it were
 // invisible during that pass (in-flight commits); keeping them as a pending gap
 // avoids losing them when the cursor jumps over.
@@ -97,6 +112,11 @@ async function invisibleWindowGap(tx, cursor, poisonId) {
         xmax: await selectSnapshotXmax(tx),
     };
 }
+function assertRequiredStatus(row, name, instanceId, requiredStatus) {
+    if (requiredStatus !== undefined && row.status !== requiredStatus) {
+        throw new ConsumerTransitionError("wrong-status", `Consumer "${name}" (instance_id="${instanceId}") is "${row.status}", not "${requiredStatus}"; nothing skipped.`);
+    }
+}
 // skipPoisonEvent skips the event whose handler failed last
 // (last_failed_event_id, set by the delivery's halt-on-poison branch): inside
 // pending_gaps it is split out of its range, otherwise the cursor moves onto
@@ -104,11 +124,12 @@ async function invisibleWindowGap(tx, cursor, poisonId) {
 // falls back to a guess: the smallest visible pending-gap id, else the next
 // event after the cursor. Single TX so concurrent dispatcher passes can't
 // double-advance. Nothing to skip → idempotent no-op.
-export async function skipPoisonEvent(db, name, instanceId = SHARED_INSTANCE_SENTINEL) {
-    return db.begin(async (tx) => {
+export async function skipPoisonEvent(db, name, instanceId = SHARED_INSTANCE_SENTINEL, options = {}) {
+    return runInOwnTransactionOrSavepoint(db, async (tx) => {
         // Locked read: a dispatcher turn committing new gaps between an unlocked
         // read and the pending_gaps overwrite below would have them dropped.
         const before = await requireConsumerRowForUpdate(tx, name, instanceId);
+        assertRequiredStatus(before, name, instanceId, options.requireStatus);
         const pendingGaps = before.pendingGaps;
         const failedEventId = before.lastFailedEventId;
         const failedIsPending = failedEventId !== null && pendingGaps.some((gap) => rangeContainsId(gap, failedEventId));

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

@@ -49,5 +49,5 @@ export type EventDispatcherOptions = {
     readonly pgClient?: PgListenClient;
 };
 export declare function createEventDispatcher(options: EventDispatcherOptions): EventDispatcher;
-export type { ConsumerProgress, ConsumerRecoveryState } from "./event-dispatcher-admin.ts";
-export { disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher-admin.ts";
+export type { ConsumerProgress, ConsumerRecoveryState, ConsumerTransitionRejection, } from "./event-dispatcher-admin.ts";
+export { ConsumerTransitionError, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher-admin.ts";

package/dist/pipeline/event-dispatcher.js

@@ -573,4 +573,4 @@ export function createEventDispatcher(options) {
         runOnce,
     };
 }
-export { disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher-admin.js";
+export { ConsumerTransitionError, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher-admin.js";

package/dist/pipeline/index.d.ts

@@ -19,8 +19,8 @@ export type { ConsumerStatus, PendingGapEntry } from "./event-consumer-state.ts"
 export { ConsumerStatuses, createEventConsumerStateTable, eventConsumerStateTable, SHARED_INSTANCE_SENTINEL, } from "./event-consumer-state.ts";
 export type { EventDedup } from "./event-dedup.ts";
 export { createEventDedup } from "./event-dedup.ts";
-export type { ConsumerProgress, ConsumerRecoveryState, DispatcherPassResult, EventConsumer, EventConsumerBatchHandler, EventConsumerHandler, EventDispatcher, EventDispatcherOptions, } from "./event-dispatcher.ts";
-export { createEventDispatcher, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher.ts";
+export type { ConsumerProgress, ConsumerRecoveryState, ConsumerTransitionRejection, DispatcherPassResult, EventConsumer, EventConsumerBatchHandler, EventConsumerHandler, EventDispatcher, EventDispatcherOptions, } from "./event-dispatcher.ts";
+export { ConsumerTransitionError, createEventDispatcher, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher.ts";
 export type { ConsumerCursor } from "./event-dispatcher-delivery.ts";
 export { selectConsumerCursorForUpdate } from "./event-dispatcher-delivery.ts";
 export type { PruneEventsOptions, PruneEventsResult } from "./event-retention.ts";

package/dist/pipeline/index.js

@@ -10,7 +10,7 @@ export { createDistributedLock } from "./distributed-lock.js";
 export { createEntityCache } from "./entity-cache.js";
 export { ConsumerStatuses, createEventConsumerStateTable, eventConsumerStateTable, SHARED_INSTANCE_SENTINEL, } from "./event-consumer-state.js";
 export { createEventDedup } from "./event-dedup.js";
-export { createEventDispatcher, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher.js";
+export { ConsumerTransitionError, createEventDispatcher, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher.js";
 export { selectConsumerCursorForUpdate } from "./event-dispatcher-delivery.js";
 export { ConsumerLagError, pruneEvents } from "./event-retention.js";
 export { createIdempotencyGuard } from "./idempotency.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.383.0",
+  "version": "0.384.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>",
@@ -199,7 +199,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.383.0",
+    "@cosmicdrift/kumiko-types": "0.384.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.383.0",
+    "@cosmicdrift/kumiko-testing": "0.384.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,36 @@
 [
+  {
+    "version": "0.384.0",
+    "type": "breaking",
+    "title": "Boot fails when a feature leaves a locale out of some of its translation keys",
+    "detail": "Within one feature, every translation key must carry every locale that any key of the same feature carries. A missing locale or an empty string fails boot with one error listing all gaps. Features with a single locale across all keys are unaffected, as are locale packages. A plural object counts as present.",
+    "migration": "Add the missing locale to each listed key, or move that locale out of the feature into a locale package."
+  },
+  {
+    "version": "0.384.0",
+    "type": "breaking",
+    "title": "Entity text fields must declare a personal stance",
+    "detail": "FieldsMap requires the personal stance of text and longText fields by type, and boot throws for such a field without one. The name heuristic for PII-typical names stays a warning and only applies to other field types.",
+    "migration": "Move raw `{ type: \"text\" }` and `{ type: \"longText\" }` entity fields to createTextField / createLongTextField with `personal` (\"self\", \"tenant\", \"ref\", `{ of }`, or false with a `reason`). tsc shows each place."
+  },
+  {
+    "version": "0.384.0",
+    "type": "improvement",
+    "title": "Consumer admin functions accept a transaction, notIn where operator",
+    "detail": "restartConsumer, skipPoisonEvent, disableConsumer, enableConsumer and the progress readers accept a DbRunner (pool or open transaction); skipPoisonEvent uses its own transaction on a pool and a savepoint inside a handler transaction. skipPoisonEvent takes { requireStatus } and checks it under its row lock; the consumer-skip handler requires \"dead\". Rejected transitions throw ConsumerTransitionError with rejection \"unknown-consumer\" or \"wrong-status\". Where clauses support { notIn: [...] }. Existing callers passing a DbConnection compile unchanged."
+  },
+  {
+    "version": "0.384.0",
+    "type": "improvement",
+    "title": "GET /files/meta?ids= returns file metadata in one request",
+    "detail": "Up to 100 comma-separated file ids per call (more answers 400 too_many_ids). The same tenant and access checks as /files/:id/meta apply per id; unknown, foreign and invalid ids are left out of the answer. The renderer's file thumbnails and file names batch their lookups through it, so a list of N files no longer issues N meta requests."
+  },
+  {
+    "version": "0.383.1",
+    "type": "fix",
+    "title": "close() ends unbounded pools of abandoned long runs",
+    "detail": "withoutStatementTimeout (reindexEntity, PII backfill, projection and multi-stream rebuilds, event-store index builds) runs on its own pool without statement_timeout and closes it when the run settles. A run that never settles, such as a reindex a boot rebuild gave up on via its own timeout, kept that pool connected, so DROP DATABASE in test cleanup failed with \"is being accessed by other users\". The connection handle's close() now ends these pools too. A rebuild that is still running when close() is called is ended after the same close timeout instead of keeping shutdown waiting."
+  },
   {
     "version": "0.383.0",
     "type": "breaking",