@cosmicdrift/kumiko-framework 0.360.0 → 0.362.0

package/dist/files/bind-referenced-files.write.js

@@ -0,0 +1,109 @@
+import * as z from "zod";
+import { defineWriteHandler, SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/index.js";
+import { isFileField } from "../engine/types/index.js";
+import { ValidationError } from "../errors/index.js";
+import { fileRefIdsOf } from "./bind-pending-file-refs.js";
+import { getFileRefExecutor } from "./create-file-ref.js";
+import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
+import { findImplicitEntityTable } from "./record-write-check.js";
+const MAX_PAGE_SIZE = 500;
+const DEFAULT_PAGE_SIZE = 200;
+const payloadSchema = z.object({
+    entityType: z.string().min(1),
+    entityIds: z.array(z.uuid()).min(1).max(MAX_PAGE_SIZE).optional(),
+    afterId: z.uuid().optional(),
+    limit: z.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE),
+});
+function invalidEntityType() {
+    return new ValidationError({
+        fields: [
+            {
+                path: "entityType",
+                code: "invalid_value",
+                i18nKey: "errors.validation.invalid_value",
+            },
+        ],
+    });
+}
+// The entity must have an implicit table and declared file fields, and the files
+// feature must be mounted; anything else is a caller error, not an empty page.
+function resolveFileBearingEntity(registry, entityType) {
+    const entity = registry.getEntity(entityType);
+    const table = findImplicitEntityTable(registry, entityType);
+    if (entity === undefined || table === undefined)
+        throw invalidEntityType();
+    if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
+        throw invalidEntityType();
+    const fileFieldNames = Object.entries(entity.fields)
+        .filter(([, fieldDef]) => isFileField(fieldDef))
+        .map(([fieldName]) => fieldName);
+    if (fileFieldNames.length === 0)
+        throw invalidEntityType();
+    return { entity, table, fileFieldNames };
+}
+// Either the named records or one id-ordered page after afterId.
+function loadRecordPage(db, { entity, table }, { entityIds, afterId, limit }) {
+    return db.selectMany(table, {
+        ...(entity.softDelete === true && { isDeleted: false }),
+        ...(entityIds !== undefined
+            ? { id: entityIds }
+            : afterId !== undefined && { id: { gt: afterId } }),
+    }, { orderBy: { col: "id", direction: "asc" }, ...(entityIds === undefined && { limit }) });
+}
+// Unbound, same tenant, uploaded by the record's creator (or the system), and either
+// unclaimed or pending for exactly this entity field.
+function isBindableToRecord(fileRef, target) {
+    const uploader = fileRef["insertedById"];
+    return (typeof uploader === "string" &&
+        (uploader === target.record["insertedById"] || uploader === SYSTEM_USER_ID) &&
+        fileRef["tenantId"] === target.tenantId &&
+        fileRef["entityId"] === null &&
+        (fileRef["entityType"] === null ||
+            (fileRef["entityType"] === target.entityType && fileRef["fieldName"] === target.fieldName)));
+}
+// The binding follows only the record's declared file fields; the caller names
+// no file ids. The record's creator must have uploaded the file themselves (or the
+// system generated it), otherwise a foreign reference would pull someone else's
+// private upload into the referencing user's record and make it readable there.
+export const bindReferencedFilesWrite = defineWriteHandler({
+    name: "bindReferencedFiles",
+    schema: payloadSchema,
+    access: { roles: [SYSTEM_ROLE, "SystemAdmin"] },
+    // Maintenance backfill run by ops or system jobs, not a task an assistant performs.
+    agent: { expose: false },
+    description: "Binds the files a record references through its declared file fields to that record, so readers of the record see them through record access. Covers files uploaded before pending-upload binding existed (entityId null) and records created without a save lifecycle (custom handlers, system jobs). Binds only files uploaded by the record's creator or generated by the system; skips files already bound elsewhere, uploaded by someone else, of another tenant or missing; never rebinds.",
+    handler: async (event, ctx) => {
+        const { entityType, entityIds, limit } = event.payload;
+        const { fileFieldNames, ...source } = resolveFileBearingEntity(ctx.registry, entityType);
+        const records = await loadRecordPage(ctx.db, source, event.payload);
+        const executor = getFileRefExecutor();
+        let bound = 0;
+        let skipped = 0;
+        for (const record of records) {
+            for (const fieldName of fileFieldNames) {
+                for (const fileRefId of fileRefIdsOf(record[fieldName])) {
+                    const row = await executor.detail({ id: fileRefId }, event.user, ctx.db);
+                    if (row === null ||
+                        !isBindableToRecord(row, {
+                            record,
+                            entityType,
+                            fieldName,
+                            tenantId: event.user.tenantId,
+                        })) {
+                        skipped += 1;
+                        continue;
+                    }
+                    const version = typeof row["version"] === "number" ? row["version"] : undefined;
+                    const result = await executor.update({ id: fileRefId, version, changes: { entityType, entityId: record.id, fieldName } }, event.user, ctx.db);
+                    if (!result.isSuccess)
+                        return result;
+                    bound += 1;
+                }
+            }
+        }
+        const lastRecord = records[records.length - 1];
+        const pageIsFull = entityIds === undefined && records.length === limit;
+        const nextAfterId = pageIsFull ? (lastRecord?.id ?? null) : null;
+        return { isSuccess: true, data: { bound, skipped, nextAfterId } };
+    },
+});

package/dist/files/dispose-removed-file-refs.d.ts

@@ -0,0 +1,8 @@
+import type { TenantDb } from "../db/tenant-db.js";
+import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.js";
+export declare function disposeRemovedFileRefs(args: {
+    readonly registry: Registry;
+    readonly result: SaveContext;
+    readonly user: SessionUser;
+    readonly db: TenantDb;
+}): Promise<void>;

package/dist/files/dispose-removed-file-refs.js

@@ -0,0 +1,51 @@
+import { isFileField, } from "../engine/types/index.js";
+import { reraiseAsKumikoError } from "../errors/index.js";
+import { fileRefIdsOf } from "./bind-pending-file-refs.js";
+import { getFileRefExecutor } from "./create-file-ref.js";
+import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
+function isBoundTo(row, entityName, entityId, fieldName) {
+    return (row["entityType"] === entityName &&
+        row["entityId"] === entityId &&
+        row["fieldName"] === fieldName);
+}
+// An update that drops or replaces a file id leaves the fileRef readable to
+// everyone who may read the record. Deleting it goes through the same executor
+// path as DELETE /files/:id (soft delete, bytes kept until retention), so
+// record readers get 404 afterwards. Only fileRefs bound to exactly this
+// record and field are touched: an id that is pending, shared or bound
+// elsewhere is not this save's to dispose. The authority is the caller's write
+// right on the record (the fileRef entity declares no write access of its own).
+export async function disposeRemovedFileRefs(args) {
+    const { registry, result, user, db } = args;
+    // skip: a create has no earlier files that could be removed
+    if (result.isNew)
+        return;
+    // skip: saves of unnamed aggregates declare no file fields
+    if (result.entityName === undefined)
+        return;
+    const entityName = result.entityName;
+    const entity = registry.getEntity(entityName);
+    // skip: saves of unregistered aggregates (custom executors) declare no file fields
+    if (entity === undefined)
+        return;
+    // skip: without the files feature the file_refs table is not part of the schema
+    if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
+        return;
+    const entityId = String(result.id);
+    const executor = getFileRefExecutor();
+    for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
+        if (!isFileField(fieldDef) || !(fieldName in result.changes))
+            continue;
+        const kept = new Set(fileRefIdsOf(result.data[fieldName]));
+        for (const fileRefId of fileRefIdsOf(result.previous[fieldName])) {
+            if (kept.has(fileRefId))
+                continue;
+            const row = await executor.detail({ id: fileRefId }, user, db);
+            if (row === null || !isBoundTo(row, entityName, entityId, fieldName))
+                continue;
+            const removed = await executor.delete({ id: fileRefId }, user, db);
+            if (!removed.isSuccess)
+                throw reraiseAsKumikoError(removed.error);
+        }
+    }
+}

package/dist/files/feature.d.ts

@@ -4,6 +4,7 @@ export { fileRefEntity } from "./file-ref-entity.js";
 export type FilesFeatureOptions = {
     readonly accessGuard?: FileAccessGuard;
     readonly privilegedRoles?: readonly string[];
+    readonly unclaimedUploadReaders?: readonly string[];
     readonly maxUploadSize?: string;
 };
 export declare function createFilesFeature(options?: FilesFeatureOptions): FeatureDefinition;

package/dist/files/feature.js

@@ -1,4 +1,5 @@
 import { defineFeature } from "../engine/index.js";
+import { bindReferencedFilesWrite } from "./bind-referenced-files.write.js";
 import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
 export { fileRefEntity } from "./file-ref-entity.js";
 // files — `fileRef` als ganz normales ES-Entity. Upload/Delete laufen über
@@ -21,6 +22,7 @@ export function createFilesFeature(options = {}) {
             recommended: false,
         });
         r.entity(FILE_REF_ENTITY_NAME, fileRefEntity);
+        r.writeHandler(bindReferencedFilesWrite);
         return { routeOptions: options };
     });
 }

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

@@ -1,4 +1,4 @@
-export declare const FILE_REF_ENTITY_NAME = "fileRef";
+export { FILE_REF_ENTITY_NAME } from "./types.js";
 export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
     storageKey: {
         readonly type: "text";

package/dist/files/file-ref-entity.js

@@ -17,7 +17,7 @@ import { createBigIntField, createEntity, createTextField } from "../engine/inde
 //     reference: "Marc-Lebenslauf.pdf", "Krankheitsattest-Mai.pdf"). The other
 //     fields (storageKey, mimeType, entityType, entityId, fieldName) are
 //     technical references or system metadata, not subject content.
-export const FILE_REF_ENTITY_NAME = "fileRef";
+export { FILE_REF_ENTITY_NAME } from "./types.js";
 export const fileRefEntity = createEntity({
     table: "file_refs",
     softDelete: true,

package/dist/files/file-routes.d.ts

@@ -3,6 +3,7 @@ import type { DbConnection } from "../db/connection.js";
 import { type Registry, type SessionUser, type TenantId } from "../engine/types/index.js";
 import type { FileProviderResolver } from "./provider-resolver.js";
 import type { RecordReadCheck } from "./record-read-check.js";
+import { type RecordWriteCheck } from "./record-write-check.js";
 export type FileAccessDecision = "allow" | "deny";
 export type FileRef = {
     id: string;
@@ -27,9 +28,11 @@ export type FileRoutesOptions = {
     readonly registry?: Registry;
     readonly maxUploadSize?: string;
     readonly privilegedRoles?: readonly string[];
+    readonly unclaimedUploadReaders?: readonly string[];
     readonly accessGuard?: FileAccessGuard;
     readonly canReadRecord?: RecordReadCheck;
+    readonly canWriteRecord?: RecordWriteCheck;
 };
 export declare function resolveMaxUploadBodyBytes(options: Pick<FileRoutesOptions, "registry" | "maxUploadSize">): number;
-export declare function readFilesRouteOptions(registry: Registry): Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "maxUploadSize">;
+export declare function readFilesRouteOptions(registry: Registry): Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "unclaimedUploadReaders" | "maxUploadSize">;
 export declare function createFileRoutes(options: FileRoutesOptions): Hono;

package/dist/files/file-routes.js

@@ -12,6 +12,7 @@ import { DEFAULT_MAX_UPLOAD_SIZE, getFileRefExecutor, storeFileAsFileRef, } from
 import { createFileContext } from "./file-handle.js";
 import { fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
+import { RecordWriteDecisions } from "./record-write-check.js";
 import { neutralFileNameForMimeType } from "./resolve-content-type.js";
 import { parseMaxSize, resolveServedContentType } from "./types.js";
 const DEFAULT_PRIVILEGED_ROLES = ["Admin", "SystemAdmin"];
@@ -22,16 +23,23 @@ const SIGNED_URL_DEFAULT_EXPIRY_SECONDS = 15 * 60;
 // 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
-// files. Unattached files are tenant-wide (the tenant boundary is already
-// enforced by the query).
-function createDefaultGuard(privilegedRoles, canReadRecord) {
+// files. Pending uploads (entityType set, record not yet created) are the
+// uploader's own until bound; so are uploads without an entityType, which no
+// record can ever claim.
+function createDefaultGuard(privilegedRoles, canReadRecord, unclaimedUploadReaders) {
     return async ({ fileRef, user, operation }) => {
-        if (fileRef.entityType === null || fileRef.entityId === null)
-            return "allow";
         if (fileRef.insertedById === user.id)
             return "allow";
         if (privilegedRoles.some((role) => user.roles.includes(role)))
             return "allow";
+        const isUnclaimed = fileRef.entityType === null && fileRef.entityId === null;
+        if (isUnclaimed &&
+            operation === "read" &&
+            unclaimedUploadReaders.some((role) => user.roles.includes(role))) {
+            return "allow";
+        }
+        if (fileRef.entityType === null || fileRef.entityId === null)
+            return "deny";
         if (operation !== "read" || canReadRecord === undefined)
             return "deny";
         const recordReadable = await canReadRecord({
@@ -75,7 +83,8 @@ export function readFilesRouteOptions(registry) {
 export function createFileRoutes(options) {
     const { db } = options;
     const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
-    const guard = options.accessGuard ?? createDefaultGuard(privilegedRoles, options.canReadRecord);
+    const guard = options.accessGuard ??
+        createDefaultGuard(privilegedRoles, options.canReadRecord, options.unclaimedUploadReaders ?? []);
     const executor = getFileRefExecutor();
     const piiSubjectFields = collectPiiSubjectFields(fileRefEntity);
     const api = new Hono();
@@ -135,6 +144,28 @@ export function createFileRoutes(options) {
         // store it in the text entityId column.
         const entityId = typeof body["entityId"] === "string" ? body["entityId"] : undefined;
         const fieldName = typeof body["fieldName"] === "string" ? body["fieldName"] : undefined;
+        if (entityId !== undefined) {
+            if (entityType === undefined) {
+                return c.json({ error: "missing_entity_type: entityId requires entityType" }, 400);
+            }
+            // Before any bytes are written: a rejected attach must leave no file behind. An
+            // unregistered entityType attaches to nothing; storeFileAsFileRef rejects it with 400.
+            const decision = options.registry !== undefined && options.registry.getEntity(entityType) === undefined
+                ? RecordWriteDecisions.writable
+                : options.canWriteRecord
+                    ? await options.canWriteRecord({ entityType, entityId, fieldName, user })
+                    : RecordWriteDecisions.forbidden;
+            switch (decision) {
+                case RecordWriteDecisions.writable:
+                    break;
+                case RecordWriteDecisions.notFound:
+                    return c.json({ error: "not_found" }, 404);
+                case RecordWriteDecisions.forbidden:
+                    return c.json({ error: "forbidden: no write access to this record" }, 403);
+                case RecordWriteDecisions.locked:
+                    return c.json({ error: "record_locked: the record is locked" }, 409);
+            }
+        }
         const data = new Uint8Array(await file.arrayBuffer());
         const storageProvider = await options.resolveProvider(user.tenantId);
         const outcome = await storeFileAsFileRef({

package/dist/files/purge-expired-file-ref-bytes.d.ts

@@ -0,0 +1,14 @@
+import type { FileContext } from "@cosmicdrift/kumiko-types/file-handle-types";
+import type { Logger } from "@cosmicdrift/kumiko-types/logger";
+import { deleteMany, type WhereObject } from "../db/query.js";
+import type { TenantDb } from "../db/tenant-db.js";
+export declare const EXPIRED_FILE_REF_PURGE_BATCH = 500;
+type PurgeLog = Pick<Logger, "warn"> | undefined;
+export declare function purgeExpiredFileRefsWithBytes(args: {
+    readonly db: TenantDb;
+    readonly table: Parameters<typeof deleteMany>[1];
+    readonly where: WhereObject;
+    readonly files: FileContext | undefined;
+    readonly log: PurgeLog;
+}): Promise<void>;
+export {};

package/dist/files/purge-expired-file-ref-bytes.js

@@ -0,0 +1,34 @@
+import { deleteMany, selectMany } from "../db/query.js";
+import { deleteStoredFileAndDerivatives } from "../derivatives/delete-stored-file.js";
+export const EXPIRED_FILE_REF_PURGE_BATCH = 500;
+// Deletes the bytes (original + derivatives) of expired soft-deleted fileRef rows, then the
+// rows. Bytes first and fail-closed: once the row is gone nobody knows the storageKey, so a
+// row whose bytes could not be removed stays and the next run retries it.
+export async function purgeExpiredFileRefsWithBytes(args) {
+    const { db, table, where, files, log } = args;
+    if (!files) {
+        log?.warn("[soft-delete-cleanup] no file storage available, expired fileRef rows kept");
+        return;
+    }
+    const rows = await selectMany(db, table, where, {
+        orderBy: [{ col: "deletedAt", direction: "asc" }],
+        limit: EXPIRED_FILE_REF_PURGE_BATCH,
+    });
+    const purgedIds = [];
+    const store = { list: files.list, delete: (key) => files.ref(key).delete() };
+    for (const row of rows) {
+        try {
+            const failedKeys = await deleteStoredFileAndDerivatives(row.storageKey, store, "soft-delete-cleanup:fileRef");
+            if (failedKeys.length === 0) {
+                purgedIds.push(row.id);
+                continue;
+            }
+            log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not fully deleted, row kept`);
+        }
+        catch (err) {
+            log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not deleted, row kept: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (purgedIds.length > 0)
+        await deleteMany(db, table, { ...where, id: { in: purgedIds } });
+}

package/dist/files/record-write-check.d.ts

@@ -0,0 +1,22 @@
+import type { TenantDb } from "../db/tenant-db.js";
+import type { Registry, SessionUser, TenantId } from "../engine/types/index.js";
+import type { RecordReadCheck } from "./record-read-check.js";
+export declare const RecordWriteDecisions: {
+    readonly writable: "writable";
+    readonly notFound: "not_found";
+    readonly forbidden: "forbidden";
+    readonly locked: "locked";
+};
+export type RecordWriteDecision = (typeof RecordWriteDecisions)[keyof typeof RecordWriteDecisions];
+export type RecordWriteCheck = (args: {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly fieldName: string | undefined;
+    readonly user: SessionUser;
+}) => Promise<RecordWriteDecision>;
+export declare function findImplicitEntityTable(registry: Registry, entityType: string): import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable | undefined;
+export declare function createRecordWriteCheck(args: {
+    readonly registry: Registry;
+    readonly canReadRecord: RecordReadCheck;
+    readonly tenantDbFor: (tenantId: TenantId) => TenantDb;
+}): RecordWriteCheck;

package/dist/files/record-write-check.js

@@ -0,0 +1,64 @@
+import { hasAccess } from "../engine/access.js";
+import { normalizeAccessEntry, userCanWriteFieldRow } from "../engine/ownership.js";
+import { toKebab } from "../engine/qualified-name.js";
+import { isRecordLocked } from "../engine/screen-helpers.js";
+export const RecordWriteDecisions = {
+    writable: "writable",
+    notFound: "not_found",
+    forbidden: "forbidden",
+    locked: "locked",
+};
+export function findImplicitEntityTable(registry, entityType) {
+    for (const projection of registry.getAllProjections().values()) {
+        if (projection.isImplicit === true && projection.source === entityType) {
+            return projection.table;
+        }
+    }
+    return undefined;
+}
+function isEntityUpdateWrite(qn, entityName) {
+    return qn.endsWith(`:write:${toKebab(entityName)}:update`);
+}
+// "May this user attach a file to the record?" asks what saving the record would ask: the
+// entity's update handler, the row-level and field-level write rules against the stored row,
+// and the lock. Not-readable, foreign-tenant and missing records answer alike (not_found) so
+// the upload never confirms what exists.
+export function createRecordWriteCheck(args) {
+    const { registry, canReadRecord, tenantDbFor } = args;
+    function findUpdateHandlerAccess(entityType) {
+        for (const [qn, handler] of registry.getAllWriteHandlers()) {
+            if (registry.getHandlerEntity(qn) === entityType && isEntityUpdateWrite(qn, entityType)) {
+                return handler.access;
+            }
+        }
+        return undefined;
+    }
+    return async ({ entityType, entityId, fieldName, user }) => {
+        if (!(await canReadRecord({ entityType, entityId, user }))) {
+            return RecordWriteDecisions.notFound;
+        }
+        const entity = registry.getEntity(entityType);
+        const table = findImplicitEntityTable(registry, entityType);
+        if (!entity || !table)
+            return RecordWriteDecisions.notFound;
+        // The stored row, not the detail output: the detail query can hide ownership fields.
+        const row = await tenantDbFor(user.tenantId).fetchOne(table, {
+            id: entityId,
+            ...(entity.softDelete === true && { isDeleted: false }),
+        });
+        if (!row)
+            return RecordWriteDecisions.notFound;
+        if (!hasAccess(user, findUpdateHandlerAccess(entityType)))
+            return RecordWriteDecisions.forbidden;
+        if (!userCanWriteFieldRow(user, entity.access?.write, row, row)) {
+            return RecordWriteDecisions.forbidden;
+        }
+        const fieldWriteRules = fieldName === undefined ? undefined : entity.fields[fieldName]?.access?.write;
+        if (!userCanWriteFieldRow(user, normalizeAccessEntry(fieldWriteRules), row, row)) {
+            return RecordWriteDecisions.forbidden;
+        }
+        if (isRecordLocked(entity.lockedWhen, row))
+            return RecordWriteDecisions.locked;
+        return RecordWriteDecisions.writable;
+    };
+}

package/dist/files/types.d.ts

@@ -1,4 +1,5 @@
 import type { TenantId } from "../engine/types/identifiers.js";
+export declare const FILE_REF_ENTITY_NAME = "fileRef";
 export type FileMetadata = {
     readonly fileName: string;
     readonly mimeType: string;

package/dist/files/types.js

@@ -1,3 +1,6 @@
+// Lives here (not in file-ref-entity.ts) so engine code can name the entity without importing
+// a module that calls createEntity at load time.
+export const FILE_REF_ENTITY_NAME = "fileRef";
 export function parseMaxSize(maxSize) {
     const match = maxSize.match(/^(\d+)(kb|mb|gb)$/i);
     if (!match)

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

@@ -162,6 +162,12 @@ function pushRelatedListSectionKeys(out, section) {
     for (const label of Object.values(section.groupBy?.labels ?? {}))
         pushKey(out, label);
 }
+function pushListEmptyStateKeys(out, emptyState) {
+    pushKey(out, emptyState?.title);
+    pushKey(out, emptyState?.description);
+    if (emptyState?.action !== undefined)
+        pushRowActionKeys(out, emptyState.action);
+}
 function pushExpandableRowKeys(out, section) {
     pushRelatedListSectionKeys(out, section);
     for (const action of section.actions ?? [])
@@ -192,6 +198,8 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
             }
             pushKey(out, list.createLabel);
             pushKey(out, list.searchPlaceholder);
+            pushKey(out, list.description);
+            pushListEmptyStateKeys(out, list.emptyState);
             for (const action of list.rowActions ?? [])
                 pushRowActionKeys(out, action);
             for (const action of list.toolbarActions ?? [])
@@ -210,6 +218,8 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
             }
             pushKey(out, list.createLabel);
             pushKey(out, list.searchPlaceholder);
+            pushKey(out, list.description);
+            pushListEmptyStateKeys(out, list.emptyState);
             for (const action of list.rowActions ?? [])
                 pushRowActionKeys(out, action);
             for (const action of list.toolbarActions ?? [])

package/dist/migrations/pii-event-backfill.d.ts

@@ -33,6 +33,7 @@ export type PiiEventBackfillResult = {
     readonly updatedEvents: number;
     readonly encryptedFields: number;
     readonly erasedFields: number;
+    readonly rekeyedFields: number;
     readonly failures: readonly PiiBackfillFailure[];
     readonly queuedTables: readonly string[];
     readonly rebuild: PiiRebuildRun | null;

package/dist/migrations/pii-event-backfill.js

@@ -68,8 +68,14 @@ export function piiAnnotationEntries(registry) {
     }
     return entries.sort();
 }
+// Bump when the backfill gains a transform stage: completed states keyed by the
+// old fingerprint must run one more full pass. Kept out of piiAnnotationEntries,
+// whose emptiness gates no_pii.
+const PII_BACKFILL_TRANSFORM_VERSION = "owner-rekey-v1";
 export function piiAnnotationFingerprint(registry) {
-    return createHash("sha256").update(piiAnnotationEntries(registry).join("\n")).digest("hex");
+    return createHash("sha256")
+        .update([...piiAnnotationEntries(registry), PII_BACKFILL_TRANSFORM_VERSION].join("\n"))
+        .digest("hex");
 }
 async function queueRebuildTables(db, tableNames, migrationId) {
     for (const tableName of tableNames) {
@@ -125,6 +131,7 @@ async function runOneBatch(ctx, progress, retryEventIds) {
             ...(retryEventIds && { eventIds: retryEventIds }),
             batchSize: ctx.batchSize,
             resolveOwnerFromProjection: true,
+            rekeyTenantKeyedOwnerFields: true,
             scanCache: progress.scanCache,
         });
         const batchTouchedEventTypes = new Set(batch.touchedEventTypes);
@@ -151,6 +158,7 @@ function recordBatch(progress, step) {
     progress.totals.updatedEvents += batch.updatedEvents;
     progress.totals.encryptedFields += batch.encryptedFields;
     progress.totals.erasedFields += batch.erasedFields;
+    progress.totals.rekeyedFields += batch.rekeyedFields;
     for (const failure of batch.failures) {
         // The catch-up overlap and the per-event retry can hit the same failed event twice in one run.
         if (progress.failedIdsSeen.has(failure.eventId))
@@ -218,7 +226,13 @@ export async function runPiiEventBackfill(db, registry, options = {}) {
     const progress = {
         scanCursor,
         scanCache: {},
-        totals: { scannedEvents: 0, updatedEvents: 0, encryptedFields: 0, erasedFields: 0 },
+        totals: {
+            scannedEvents: 0,
+            updatedEvents: 0,
+            encryptedFields: 0,
+            erasedFields: 0,
+            rekeyedFields: 0,
+        },
         failures: [],
         queuedTables: new Set(),
         failedIdsSeen: new Set(),

package/dist/pipeline/cascade-handler.js

@@ -1,6 +1,7 @@
-import { deleteMany, fetchOne, updateMany } from "../db/query.js";
+import { deleteMany, fetchOne, selectMany, updateMany } from "../db/query.js";
 import { OnDeleteStrategies, SystemHookNames, SystemHookPriorities } from "../engine/constants.js";
-import { ConflictError, FrameworkReasons } from "../errors/index.js";
+import { isRecordLocked } from "../engine/screen-helpers.js";
+import { ConflictError, FrameworkReasons, RecordLockedError } from "../errors/index.js";
 export function createCascadeDeleteHook(registry, tables) {
     return {
         name: SystemHookNames.cascadeDelete,
@@ -47,6 +48,20 @@ export function createCascadeDeleteHook(registry, tables) {
                             });
                         }
                     }
+                    // The raw delete/update below bypasses the executor, so a locked child must
+                    // block the parent delete here instead of changing with it. The error names
+                    // the parent only: the caller may delete the parent without reading the child.
+                    if (strategy === OnDeleteStrategies.cascade || strategy === OnDeleteStrategies.setNull) {
+                        const childLock = registry.getEntity(relation.target)?.lockedWhen;
+                        if (childLock !== undefined) {
+                            const children = await selectMany(db, targetTable, {
+                                [relation.foreignKey]: payload.id,
+                            });
+                            if (children.some((child) => isRecordLocked(childLock, child))) {
+                                throw new RecordLockedError({ entityName, entityId: payload.id });
+                            }
+                        }
+                    }
                     if (strategy === OnDeleteStrategies.cascade) {
                         await deleteMany(db, targetTable, { [relation.foreignKey]: payload.id });
                     }

package/dist/pipeline/dispatch-write.js

@@ -8,7 +8,9 @@ import { checkWriteFieldOwnership, maskWriteOnlyFields } from "../engine/field-a
 import { defineTransitions, guardTransition } from "../engine/state-machine.js";
 import { HookPhases } from "../engine/types/index.js";
 import { AccessDeniedError, FrameworkReasons, InternalError, memberResolutionReadOnlyDenied, NotFoundError, ValidationError, writeFailure, } from "../errors/index.js";
+import { assertFileRefsBelongToTenant } from "../files/assert-file-refs-belong-to-tenant.js";
 import { bindPendingFileRefs } from "../files/bind-pending-file-refs.js";
+import { disposeRemovedFileRefs } from "../files/dispose-removed-file-refs.js";
 import { CACHE_SYNC_TOPICS } from "../redis/cache-sync-topics.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
 import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, isMemberResolutionPrincipal, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
@@ -112,12 +114,10 @@ async function runLifecycle(ctx, type, data, handlerContext, user, origin, after
     // keeps projection state consistent with what the hooks observe.
     await runProjections(result, handlerContext.registry, runner);
     if (result.kind === "save") {
-        await bindPendingFileRefs({
-            registry: handlerContext.registry,
-            result,
-            user,
-            db: handlerContext.db,
-        });
+        const fileRefArgs = { registry: handlerContext.registry, result, user, db: handlerContext.db };
+        await assertFileRefsBelongToTenant(fileRefArgs);
+        await bindPendingFileRefs(fileRefArgs);
+        await disposeRemovedFileRefs(fileRefArgs);
         await lifecycle.runPostSave(type, result, handlerContext, HookPhases.inTransaction);
         afterCommitHooks.push(async () => {
             const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, undefined, undefined, true);

package/dist/pipeline/write-origin.js

@@ -39,11 +39,11 @@ function declaresPublicIntake(access) {
 // Only the public dispatcher entry points compute a root; every nested call inherits
 // it, so switching identity via ctx.writeAs(SYSTEM, ...) cannot shed an anonymous root.
 export function rootWriteOrigin(registry, type, user) {
-    const writeHandler = registry.getWriteHandler(type);
+    const rootHandler = registry.getWriteHandler(type) ?? registry.getQueryHandler(type);
     return {
         rootHandler: type,
         anonymousRoot: user.roles.includes(ANONYMOUS_ROLE),
-        publicIntake: writeHandler !== undefined && declaresPublicIntake(writeHandler.access),
+        publicIntake: rootHandler !== undefined && declaresPublicIntake(rootHandler.access),
     };
 }
 // Owner binding is ignored (honorOwnerBinding=false): all anonymous callers share one