@cosmicdrift/kumiko-framework 0.360.0 → 0.362.0

package/dist/schema-cli.js

@@ -10,7 +10,7 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join, resolve as resolvePath } from "node:path";
 import { configureBlindIndexKey, configurePiiSubjectKms, resolveKmsWiringAsync, } from "./crypto/index.js";
-import { assertValidMigrationName, baselineMigrations, createDbConnection, diffReplayAgainstSnapshot, fetchAppliedMigrations, findCommentedDropTables, generateMigration, isRetiredFrameworkTable, loadMigrationsFromDir, loadSnapshotJson, readMigrationSqlTexts, rebuildTablesFromDiff, replayMigrationsDir, runMigrationsFromDir, tableExists, writeRebuildMarker, writeSnapshotJson, } from "./db/index.js";
+import { assertUniqueTableNames, assertValidMigrationName, baselineMigrations, createDbConnection, diffReplayAgainstSnapshot, fetchAppliedMigrations, findCommentedDropTables, generateMigration, isRetiredFrameworkTable, loadMigrationsFromDir, loadSnapshotJson, readMigrationSqlTexts, rebuildTablesFromDiff, replayMigrationsDir, runMigrationsFromDir, tableExists, writeRebuildMarker, writeSnapshotJson, } from "./db/index.js";
 import { validateBoot } from "./engine/boot-validator.js";
 import { createRegistry } from "./engine/registry.js";
 import { createEventsTable } from "./event-store/index.js";
@@ -29,10 +29,9 @@ async function loadSchemaModFromApp(schemaFile) {
     if (!Array.isArray(mod.ENTITY_METAS)) {
         throw new Error(`Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`);
     }
-    return {
-        entityMetas: mod.ENTITY_METAS,
-        features: mod.FEATURES,
-    };
+    const entityMetas = mod.ENTITY_METAS;
+    assertUniqueTableNames(entityMetas);
+    return { entityMetas, features: mod.FEATURES };
 }
 function nextSequenceNumber(migrationsDir) {
     if (!existsSync(migrationsDir))
@@ -134,7 +133,14 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                 out.err("    export const ENTITY_METAS: EntityTableMeta[] = [...]");
                 return 1;
             }
-            const { entityMetas: metas } = await loadSchemaModFromApp(schemaFile);
+            let metas;
+            try {
+                ({ entityMetas: metas } = await loadSchemaModFromApp(schemaFile));
+            }
+            catch (e) {
+                out.err(`  ${e instanceof Error ? e.message : String(e)}`);
+                return 1;
+            }
             const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
             const prevSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
             const result = generateMigration({

package/dist/search/reindex-entity.js

@@ -13,10 +13,9 @@ function quoteIdent(name) {
 }
 // Read-table state, forward-mapped from entity.fields (fieldName →
 // toSnakeCase(fieldName)). SELECT * + forward-map instead of building an
-// explicit column list: some field types (files/images) emit no column at
-// all, others (locatedTimestamp, money) emit companion columns under a
-// different name — an explicit alias list breaks on those. Missing columns
-// are just skipped, matching what a `.created` event payload would carry.
+// explicit column list: some field types (locatedTimestamp, money) emit
+// companion columns under a different name — an explicit alias list breaks on
+// those. Missing columns are just skipped, matching what a `.created` event payload would carry.
 function rowToState(row, fieldNames) {
     const state = {};
     for (const fieldName of fieldNames) {

package/dist/stack/test-stack.d.ts

@@ -7,7 +7,7 @@ import type { ErrorDocsConfig } from "../errors/docs-url.js";
 import { type JobRunner, type JobRunnerOptions } from "../jobs/index.js";
 import type { Lifecycle } from "../lifecycle/index.js";
 import { type ObservabilityProvider } from "../observability/index.js";
-import type { Dispatcher, EventDispatcher } from "../pipeline/index.js";
+import type { Dispatcher, EventDispatcher, SystemHooks } from "../pipeline/index.js";
 import { type ClosableCacheSyncBus } from "../redis/cache-sync-bus.js";
 import type { SearchAdapter } from "../search/types.js";
 import { type EventCollector } from "./event-collector.js";
@@ -37,6 +37,8 @@ export type TestStackOptions = {
     features: readonly FeatureDefinition[];
     /** System hooks to wire up. Default: all (sse, search) */
     systemHooks?: ("sse" | "search")[];
+    /** Pipeline system hooks handed to buildServer, e.g. the cascade-delete preDelete hook. None by default. */
+    lifecycleSystemHooks?: SystemHooks;
     /** Search config per tenant — defaults to tenant 1 with all text fields */
     searchConfig?: {
         tenantId: TenantId;

package/dist/stack/test-stack.js

@@ -287,6 +287,7 @@ export async function setupTestStack(options) {
             context: rateLimitFallback ? { ...appContext, rateLimit: rateLimitFallback } : appContext,
             jwtSecret,
             ...(options.observability ? { observability: options.observability } : {}),
+            ...(options.lifecycleSystemHooks && { systemHooks: options.lifecycleSystemHooks }),
             dispatcherOptions: {
                 idempotency,
                 cacheSync,

package/dist/ui-types/card-column-roles.d.ts

@@ -5,10 +5,15 @@ export type CardRoleColumn = {
     readonly type?: string;
     readonly renderer?: unknown;
     readonly hideOnNarrow?: boolean;
+    readonly fileDisplay?: {
+        readonly kind: string;
+    };
 };
 export type CardColumnRoles<C extends CardRoleColumn> = {
+    readonly image: C | undefined;
     readonly title: C | undefined;
     readonly status: C | undefined;
     readonly meta: readonly C[];
 };
+export declare function cardFileDisplayKind(type: string | undefined, renderer: unknown): "image" | "file" | undefined;
 export declare function cardColumnRoles<C extends CardRoleColumn>(columns: readonly C[]): CardColumnRoles<C>;

package/dist/ui-types/card-column-roles.js

@@ -1,9 +1,27 @@
 export const CARD_META_MAX = 3;
+// An explicit `{ format: "image" | "file" }` renderer wins over the field type, the
+// same precedence as the list view model's file display.
+export function cardFileDisplayKind(type, renderer) {
+    if (typeof renderer === "object" && renderer !== null && "format" in renderer) {
+        if (renderer.format === "image")
+            return "image";
+        if (renderer.format === "file")
+            return "file";
+    }
+    if (type === "image" || type === "images")
+        return "image";
+    if (type === "file" || type === "files")
+        return "file";
+    return undefined;
+}
 // One rule for the narrow-layout list card, shared by the renderer and the
 // boot validator so the validator counts exactly what the card would draw.
+// The first image column is the card's leading preview, neither title nor meta.
 export function cardColumnRoles(columns) {
-    const title = columns.find((col) => col.highlighted === true) ?? columns[0];
-    const status = columns.find((col) => col !== title && col.type === "select" && col.renderer === undefined);
-    const meta = columns.filter((col) => col !== title && col !== status && col.hideOnNarrow !== true);
-    return { title, status, meta };
+    const image = columns.find((col) => col.fileDisplay?.kind === "image");
+    const textColumns = columns.filter((col) => col !== image);
+    const title = textColumns.find((col) => col.highlighted === true) ?? textColumns[0];
+    const status = textColumns.find((col) => col !== title && col.type === "select" && col.renderer === undefined);
+    const meta = textColumns.filter((col) => col !== title && col !== status && col.hideOnNarrow !== true);
+    return { image, title, status, meta };
 }

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

@@ -4,12 +4,12 @@ export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedd
 export type { ParsedRefTarget } from "../engine/parse-ref-target.js";
 export { parseRefTarget } from "../engine/parse-ref-target.js";
 export type { FieldsOrGroupsSection, UnavailableSelectOption } from "../engine/screen-helpers.js";
-export { availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
+export { availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
 export type { BooleanFieldDef, DateFieldDef, EmbeddedDerivedCellDef, EntityDefinition, FieldDefinition, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, SelectFieldDef, SelectOptionTone, TextFieldDef, } from "../engine/types/fields.js";
 export type { AccessRule, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, RoleAccessPersonalData, RoleAccessRule, } from "../engine/types/handlers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.js";
-export type { ActionFormFooterAction, ActionFormRedirect, ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartKind, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardChartTone, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelGate, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardTimeRangeDefinition, DashboardValueFormat, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, EntityWriteExcludedFields, FieldCondition, FieldIconKey, FieldRenderer, FormWidth, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListFacetSpec, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.js";
+export type { ActionFormFooterAction, ActionFormRedirect, ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartKind, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardChartTone, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelGate, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardTimeRangeDefinition, DashboardValueFormat, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, EntityWriteExcludedFields, FieldCondition, FieldIconKey, FieldRenderer, FormWidth, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.js";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.js";
 export type { TargetRef } from "../engine/types/target-ref.js";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node.js";
@@ -17,7 +17,7 @@ export type { WorkspaceDefinition } from "../engine/types/workspace.js";
 export { ACTION_FORM_ENTITY, handlerFieldLabelKey, handlerTitleKey, PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";
 export type { AppSchema, FeatureSchema, QualifiedContentCollection, WorkspaceSchema, } from "./app-schema.js";
 export type { CardColumnRoles, CardRoleColumn } from "./card-column-roles.js";
-export { CARD_META_MAX, cardColumnRoles } from "./card-column-roles.js";
+export { CARD_META_MAX, cardColumnRoles, cardFileDisplayKind } from "./card-column-roles.js";
 export { type Formality, formalLocaleTag } from "./formality.js";
 export type { ListRowMetaColumnType, ListRowMetaReference, ReferenceLookupSource, SystemReferenceLabel, } from "./list-row-meta.js";
 export { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, } from "./list-row-meta.js";

package/dist/ui-types/index.js

@@ -22,11 +22,11 @@
 export { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
 export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedded-derived.js";
 export { parseRefTarget } from "../engine/parse-ref-target.js";
-export { availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
+export { availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.js";
 export { ACTION_FORM_ENTITY, handlerFieldLabelKey, handlerTitleKey, PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";
-export { CARD_META_MAX, cardColumnRoles } from "./card-column-roles.js";
+export { CARD_META_MAX, cardColumnRoles, cardFileDisplayKind } from "./card-column-roles.js";
 export { formalLocaleTag } from "./formality.js";
 export { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, } from "./list-row-meta.js";
 export { resolveTranslationValue, translationValueOtherText, } from "./plural.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.360.0",
+  "version": "0.362.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>",
@@ -210,8 +210,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.360.0",
-    "@cosmicdrift/kumiko-types": "0.360.0",
+    "@cosmicdrift/kumiko-http": "0.362.0",
+    "@cosmicdrift/kumiko-types": "0.362.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -227,7 +227,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.360.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.362.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,138 @@
 [
+  {
+    "version": "0.362.0",
+    "type": "fix",
+    "title": "Client schema carries entity lockedWhen",
+    "detail": "buildAppSchema projects lockedWhen, so an entityEdit screen shows a locked record read-only without a screen-level readOnly."
+  },
+  {
+    "version": "0.362.0",
+    "type": "fix",
+    "title": "r.secret options with function values (redact) no longer fail to parse",
+    "detail": "r.secret(...) options that contain arrow or function expressions (for example redact: () => \"••••••••\") were reported as \"options could not be read as a plain object\", which turned the whole feature into a legacy corpus entry. The functions are now kept verbatim as raw references, option keys stay visible and a parse to render round-trip keeps them (multi-line function bodies may be re-indented). Function values in other patterns (entity, nav, metric, job) are still rejected on purpose.",
+    "migration": "Consumers that ship a checked-in few-shot corpus (Enterprise) should regenerate it on the next framework bump; its drift test enforces that."
+  },
+  {
+    "version": "0.362.0",
+    "type": "improvement",
+    "title": "Binding of referenced files only for the record creator's own uploads",
+    "detail": "files:write:bind-referenced-files now binds a file only if the record creator uploaded it (or the system generated it), so foreign references cannot expose private uploads."
+  },
+  {
+    "version": "0.362.0",
+    "type": "improvement",
+    "title": "files:write:bind-referenced-files binds a record's referenced files",
+    "detail": "System-only handler that binds the files a record references through its declared file fields (legacy uploads with entityId null, records created without a save lifecycle) so record readers can open them. Skips files bound elsewhere, of another tenant or missing. Callable from es-ops seeds via ctx.systemWriteAs; pages with limit and nextAfterId."
+  },
+  {
+    "version": "0.362.0",
+    "type": "breaking",
+    "title": "Optional number fields in entity forms start empty instead of 0",
+    "migration": "An optional number field without default no longer starts at 0 in entityEdit create/edit, and an untouched one is not sent. If a screen relied on the implicit 0, declare default: 0 on the field."
+  },
+  {
+    "version": "0.362.0",
+    "type": "improvement",
+    "title": "unclaimedUploadReaders option for createFilesFeature",
+    "detail": "Roles listed in unclaimedUploadReaders may read (not delete) uploads that have no entityType and entityId, for documents referenced without a file field."
+  },
+  {
+    "version": "0.362.0",
+    "type": "fix",
+    "title": "Query handlers may declare personalData public-intake",
+    "detail": "The personal-data write gate computed the public-intake exemption only for write handlers, so an anonymous query handler that wrote personal data (directly or through a nested write) was always rejected, and the boot validator refused access.personalData on query handlers. Query handlers now follow the same rules as write handlers: access.personalData \"public-intake\" requires the anonymous role and an active rateLimit (not disabled). openToAll.personalData stays write-only, stream handlers still cannot declare personalData.",
+    "migration": "No consumer change; anonymous query handlers that write personal data now declare access.personalData: \"public-intake\" instead of failing at the write gate."
+  },
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "Boot check for edit field prefill",
+    "detail": "validateBoot allows today only on date fields, currentUser displayName and email only on text fields and id on text or reference fields."
+  },
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "Boot check for the entityEdit readOnly condition",
+    "detail": "validateBoot rejects a screen readOnly condition whose field is not a field of the screen's entity."
+  },
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "Boot check for embeddedList on edit fields",
+    "detail": "validateBoot requires the field to be an embedded list and every readOnlyCells entry to be a sub-field."
+  },
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "Locked records reject executor writes",
+    "detail": "The event-store executor checks entity.lockedWhen against the loaded row in update and delete and fails with RecordLockedError (409, code record_locked, i18n key errors.recordLocked); a missing condition field counts as locked. Create, restore, forget, framework-system-user writes that name a writePurpose and the write that sets the lock pass. validateBoot rejects a lockedWhen field that is unknown, personal, encrypted or not a plain scalar type."
+  },
+  {
+    "version": "0.361.0",
+    "type": "breaking",
+    "title": "POST /files checks write access to the target record",
+    "detail": "createRecordWriteCheck loads the stored row tenant-scoped and applies update-handler access, entity access.write, field write access and lockedWhen before the upload is stored. Results map to 404, 403 and 409 record_locked. Uploads with an entityId and no check wired are refused.",
+    "migration": "Grant the uploader the entity's update right for records they attach files to, or upload without an entityId and bind the file on save. Entities without a generic :update handler no longer accept uploads with an entityId. Code that used entityId as a free slot without a stored record must create the record first."
+  },
+  {
+    "version": "0.361.0",
+    "type": "breaking",
+    "title": "Unbound uploads are private to the uploader (security)",
+    "detail": "The default file access guard denies every operation on a file with no entityType or no entityId unless the caller is the uploader or has a role in privilegedRoles; the file routes answer 404 as for any denied file. Before, files without entityType were readable by the whole tenant and pending uploads until a record claimed them. bindPendingFileRefs now also runs for updates and binds the file ids named in the update's changes for file, image, files and images fields (same entityType and fieldName, entityId null, insertedById = caller), so createFileRefFromBytes with attachTo but no entityId plus a following update write attaches the file to the record.",
+    "migration": "Code that shows a file without entityType to other users (tenant logo, avatar, mail attachment, import preview, AI-agent output) must upload it with entityType and fieldName of a file field on a record and save the record, so readers of that record can read it; or keep it uploader-only, run the read as a role in privilegedRoles, or set a custom accessGuard in the files feature options. Apps that set accessGuard keep their own decision. Code that reads another user's pending upload before the record is saved must bind the file first or run as the uploader. Known case: solon's document upload (`document/web/upload-file.ts`) posts without entityType and the later document record (created by the ingest job, not the uploader) stores the id in its `fileId` field, so other users no longer read the original; solon must upload with entityType and fieldName of `fileId` and bind the file when the record is created, because a different creator cannot claim the pending upload."
+  },
+  {
+    "version": "0.361.0",
+    "type": "fix",
+    "title": "Personal file/image fields are no longer encrypted",
+    "detail": "collectPiiSubjectFields still lists file, image, files and images fields with a personal annotation (forget and retention use it), but the new collectPiiEncryptedFields leaves them out and every encrypt, decrypt, backfill and store-gate path now uses it. The column holds only the fileRef uuid; the binary is erased by the file-ref user-data hook."
+  },
+  {
+    "version": "0.361.0",
+    "type": "fix",
+    "title": "Personal fields are re-keyed to the new owner on owner change",
+    "detail": "On absent to X and X to Y, the executor writes the personal fields (personal: { of: ownerField }) of the row under the new owner's key into the update event, so the projection, a rebuild and every event from the transition on agree and only the current owner's forget decides erasure. As a result <entity>.updated changes can contain personal fields the caller did not send. X to absent keeps the values under X so the last owner's forget still erases them. The created event from before an owner existed stays tenant-keyed in the immutable log. The new backfill option rekeyTenantKeyedOwnerFields moves such tenant-keyed values under the owner the projection or payload names (never via whenAbsent, a projection row of another tenant is ignored, other tenants' keys are not touched, a forgotten owner yields the erased sentinel). The boot PII backfill passes it, and its fingerprint now includes a transform version, so each deployment runs one full pass and afterwards only catch-up passes near the cursor. A created event whose owner transition happens after that full pass is not rescanned and stays tenant-keyed until someone runs backfillEventPiiEncryption(db, registry, { resolveOwnerFromProjection: true, rekeyTenantKeyedOwnerFields: true }) followed by a projection rebuild, or the transform version is bumped.",
+    "migration": "No consumer code change. The boot backfill runs in the background (startPiiEventBackfillOnBoot, it does not block readiness, KUMIKO_SKIP_PII_BACKFILL=1 turns it off). On the first boot after the bump it does one full scan of kumiko_events and rebuilds the affected projections. Consumers reading updated.changes must not treat a personal field there as a user edit when the owner field changed in the same event."
+  },
+  {
+    "version": "0.361.0",
+    "type": "breaking",
+    "title": "Plural file fields have a projection column",
+    "detail": "files and images fields get a jsonb NOT NULL DEFAULT '[]' column on the entity table (entity-table-meta, buildEntityTable row type readonly string[]) and applyEntityEvent no longer strips them from updated events. Detail and list queries return the ordered id arrays; before, they never carried the field, so an edit form of a saved record showed no files. kumiko schema generate emits an in-place ADD COLUMN for existing tables and no .rebuild.json, so existing rows hold [] until their projection is rebuilt from the events.",
+    "migration": "Run kumiko schema generate and apply the migration. Existing rows keep [] until the entity projection is rebuilt, so add a rebuild marker before applying: create <NNNN_migration-name>.rebuild.json next to the generated SQL with {\"version\":1,\"tables\":[\"<table name from the ALTER TABLE statement>\"]}; kumiko schema apply then rebuilds the projection. Without the marker, call enqueueProjectionRebuild(\"<feature>:projection:<entity>-entity\", { db, registry, jobRunner }) from @cosmicdrift/kumiko-framework/migrations once per entity. Known consumers: solon protocol (attachmentFileIds) and the Wartungs-Demo (photos). Code that read the ids of a plural file field from the event log or from file_refs can read the row field instead."
+  },
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "Files removed from a record are deleted",
+    "detail": "disposeRemovedFileRefs runs next to bindPendingFileRefs for every save that is not a create. For each file field named in changes it soft-deletes the fileRefs present in previous but not in the saved row, when entityType, entityId and fieldName match this record. The binary is removed by the soft-delete cleanup job after retention, or by forget."
+  },
+  {
+    "version": "0.361.0",
+    "type": "breaking",
+    "title": "Schema generate rejects a table listed twice in ENTITY_METAS",
+    "detail": "When ENTITY_METAS contained the same tableName twice, the migration diff kept only the last definition and compared it against the previous snapshot entry, so a new index was written to .snapshot.json but no CREATE INDEX reached the migration SQL. kumiko-schema generate, kumiko-schema validate and programmatic generateMigration now throw (generate and validate exit 1 with a message naming every duplicated table) before any file is written.",
+    "migration": "Remove hand-added metas for tables a feature already registers from kumiko/schema.ts. Known: phronexsis kumiko/schema.ts appends IN_APP_MESSAGES_META next to collectTableMetas(FEATURES); drop it (and its comment), then run kumiko-schema generate — the existing in_app_messages_tenant_user_created_idx comes out as CREATE INDEX IF NOT EXISTS (no-op) and the two legacy indexes as commented review drops. The duplicate in_app_messages entry in .snapshot.json disappears with that generate."
+  },
+  {
+    "version": "0.361.0",
+    "type": "fix",
+    "title": "Soft-delete cleanup removes the bytes of expired fileRefs",
+    "detail": "softDeleteCleanupJob handles the fileRef entity through purgeExpiredFileRefsWithBytes, which deletes the original and its derivatives via the file provider and then only the rows whose bytes are gone. Failures are logged and retried on the next run."
+  },
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "setupTestStack option lifecycleSystemHooks",
+    "detail": "Passes the given SystemHooks to buildServer, so tests can exercise pipeline lifecycle hooks like createCascadeDeleteHook through the real HTTP stack."
+  },
+  {
+    "version": "0.361.0",
+    "type": "breaking",
+    "title": "Writes with file ids from another tenant are rejected",
+    "detail": "A create or update that puts a file id into a file or image field now fails with a ValidationError (code invalid_element, path = field name) when the id is not a UUID, does not exist, or belongs to another tenant. That includes files stored under the SYSTEM tenant. On update only the changed fields are checked. The check runs for every write that returns a save result, inside the transaction, before pending file refs are bound. System users created for a tenant pass with that tenant's own files.",
+    "migration": "Check seeds, imports and handlers that copy file ids across tenants or reference files uploaded as SYSTEM. Upload the file in the target tenant (or copy it there) before writing its id. A custom handler that writes through an executor directly, without returning a save result, is not covered and needs its own check."
+  },
   {
     "version": "0.360.0",
     "type": "breaking",