@cosmicdrift/kumiko-bundled-features 0.371.1 → 0.372.0

package/dist/notes-history/entity.d.ts

@@ -1,6 +1,6 @@
 import { type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
 export declare function createNoteEntryEntity(access?: EntityDefinition["access"], parents?: readonly string[]): EntityDefinition<{
-    entityType: {
+    readonly entityType: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -23,7 +23,7 @@ export declare function createNoteEntryEntity(access?: EntityDefinition["access"
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    entityId: {
+    readonly entityId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -46,7 +46,7 @@ export declare function createNoteEntryEntity(access?: EntityDefinition["access"
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    authorId: {
+    readonly authorId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -69,7 +69,7 @@ export declare function createNoteEntryEntity(access?: EntityDefinition["access"
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    authorName: {
+    readonly authorName: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -92,7 +92,7 @@ export declare function createNoteEntryEntity(access?: EntityDefinition["access"
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    body: {
+    readonly body: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -110,7 +110,7 @@ export declare function createNoteEntryEntity(access?: EntityDefinition["access"
     };
 }, "tenant">;
 export declare const noteEntryEntity: EntityDefinition<{
-    entityType: {
+    readonly entityType: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -133,7 +133,7 @@ export declare const noteEntryEntity: EntityDefinition<{
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    entityId: {
+    readonly entityId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -156,7 +156,7 @@ export declare const noteEntryEntity: EntityDefinition<{
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    authorId: {
+    readonly authorId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -179,7 +179,7 @@ export declare const noteEntryEntity: EntityDefinition<{
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    authorName: {
+    readonly authorName: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -202,7 +202,7 @@ export declare const noteEntryEntity: EntityDefinition<{
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    body: {
+    readonly body: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -220,7 +220,7 @@ export declare const noteEntryEntity: EntityDefinition<{
     };
 }, "tenant">;
 export declare function createNoteMentionEntity(): EntityDefinition<{
-    noteId: {
+    readonly noteId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -243,7 +243,7 @@ export declare function createNoteMentionEntity(): EntityDefinition<{
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    subjectId: {
+    readonly subjectId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -268,7 +268,7 @@ export declare function createNoteMentionEntity(): EntityDefinition<{
     };
 }, "tenant">;
 export declare const noteMentionEntity: EntityDefinition<{
-    noteId: {
+    readonly noteId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -291,7 +291,7 @@ export declare const noteMentionEntity: EntityDefinition<{
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    subjectId: {
+    readonly subjectId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;

package/dist/notes-history/executor.d.ts

@@ -1,4 +1,33 @@
 import { type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
-export declare const noteEntryExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor, noteEntryTable: import("@cosmicdrift/kumiko-framework/db").EntityTable;
+export declare const noteEntryExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor<{
+    readonly id: string;
+    readonly tenantId: string;
+    readonly version: number;
+    readonly insertedAt: Temporal.Instant;
+    readonly modifiedAt: Temporal.Instant | null;
+    readonly insertedById: string | null;
+    readonly modifiedById: string | null;
+    readonly isDeleted?: boolean | undefined;
+    readonly deletedAt?: Temporal.Instant | null | undefined;
+    readonly deletedById?: string | null | undefined;
+    readonly authorId: string | null;
+    readonly authorName: string | null;
+    readonly body: string;
+    readonly entityId: string;
+    readonly entityType: string;
+}>, noteEntryTable: import("@cosmicdrift/kumiko-framework/db").EntityTable;
 export declare function createNoteEntryExecutor(ownership: EntityDefinition["access"] | undefined): typeof noteEntryExecutor;
-export declare const noteMentionExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor, noteMentionTable: import("@cosmicdrift/kumiko-framework/db").EntityTable;
+export declare const noteMentionExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor<{
+    readonly id: string;
+    readonly tenantId: string;
+    readonly version: number;
+    readonly insertedAt: Temporal.Instant;
+    readonly modifiedAt: Temporal.Instant | null;
+    readonly insertedById: string | null;
+    readonly modifiedById: string | null;
+    readonly isDeleted?: boolean | undefined;
+    readonly deletedAt?: Temporal.Instant | null | undefined;
+    readonly deletedById?: string | null | undefined;
+    readonly noteId: string;
+    readonly subjectId: string;
+}>, noteMentionTable: import("@cosmicdrift/kumiko-framework/db").EntityTable;

package/dist/personal-access-tokens/schema/api-token.d.ts

@@ -1,5 +1,5 @@
 export declare const apiTokenEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
-    userId: {
+    readonly userId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -22,7 +22,7 @@ export declare const apiTokenEntity: import("@cosmicdrift/kumiko-types/fields").
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    tenantId: {
+    readonly tenantId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -45,7 +45,7 @@ export declare const apiTokenEntity: import("@cosmicdrift/kumiko-types/fields").
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    name: {
+    readonly name: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -68,7 +68,7 @@ export declare const apiTokenEntity: import("@cosmicdrift/kumiko-types/fields").
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    tokenHash: {
+    readonly tokenHash: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -91,7 +91,7 @@ export declare const apiTokenEntity: import("@cosmicdrift/kumiko-types/fields").
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    prefix: {
+    readonly prefix: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -114,7 +114,7 @@ export declare const apiTokenEntity: import("@cosmicdrift/kumiko-types/fields").
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    scopes: {
+    readonly scopes: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -137,7 +137,7 @@ export declare const apiTokenEntity: import("@cosmicdrift/kumiko-types/fields").
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    createdAt: {
+    readonly createdAt: {
         readonly type: "timestamp";
         readonly description?: string;
         readonly required?: boolean;
@@ -152,7 +152,7 @@ export declare const apiTokenEntity: import("@cosmicdrift/kumiko-types/fields").
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    expiresAt: {
+    readonly expiresAt: {
         readonly type: "timestamp";
         readonly description?: string;
         readonly required?: boolean;
@@ -167,7 +167,7 @@ export declare const apiTokenEntity: import("@cosmicdrift/kumiko-types/fields").
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    revokedAt: {
+    readonly revokedAt: {
         readonly type: "timestamp";
         readonly description?: string;
         readonly required?: boolean;

package/dist/personal-access-tokens/screens.js

@@ -13,6 +13,14 @@ const PAT_SCREEN_VISIBLE_WHEN = {
     field: "enabled",
     eq: true,
 };
+const PAT_CREATE_ACTION = {
+    kind: "navigate",
+    id: "create",
+    label: i18nKey("pat.create.title"),
+    screen: PAT_MINT_SCREEN_ID,
+    style: "primary",
+    icon: "plus",
+};
 export const patListScreen = {
     id: PAT_SCREEN_ID,
     type: "projectionList",
@@ -63,15 +71,12 @@ export const patListScreen = {
             visible: { field: "status", ne: "revoked" },
         },
     ],
-    toolbarActions: [
-        {
-            kind: "navigate",
-            id: "create",
-            label: i18nKey("pat.create.title"),
-            screen: PAT_MINT_SCREEN_ID,
-            style: "primary",
-        },
-    ],
+    toolbarActions: [PAT_CREATE_ACTION],
+    emptyState: {
+        title: i18nKey("kumiko.list.empty.title"),
+        description: i18nKey("kumiko.list.empty.hint"),
+        action: PAT_CREATE_ACTION,
+    },
     access: {
         openToAll: {
             reason: "each signed-in user views only their own personal access tokens, mirroring the list handler",

package/dist/secrets/table.d.ts

@@ -4,7 +4,7 @@ export type StoredMetadata = {
     readonly hint?: string;
 };
 export declare const tenantSecretEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
-    key: {
+    readonly key: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -27,7 +27,7 @@ export declare const tenantSecretEntity: import("@cosmicdrift/kumiko-types/field
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    kekVersion: {
+    readonly kekVersion: {
         readonly type: "number";
         readonly description?: string;
         readonly required?: boolean;

package/dist/sessions/schema/user-session.d.ts

@@ -1,5 +1,5 @@
 export declare const userSessionEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
-    userId: {
+    readonly userId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -22,7 +22,7 @@ export declare const userSessionEntity: import("@cosmicdrift/kumiko-types/fields
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    tenantId: {
+    readonly tenantId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -45,7 +45,7 @@ export declare const userSessionEntity: import("@cosmicdrift/kumiko-types/fields
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    createdAt: {
+    readonly createdAt: {
         readonly type: "timestamp";
         readonly description?: string;
         readonly required?: boolean;
@@ -60,7 +60,7 @@ export declare const userSessionEntity: import("@cosmicdrift/kumiko-types/fields
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    expiresAt: {
+    readonly expiresAt: {
         readonly type: "timestamp";
         readonly description?: string;
         readonly required?: boolean;
@@ -75,7 +75,7 @@ export declare const userSessionEntity: import("@cosmicdrift/kumiko-types/fields
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    revokedAt: {
+    readonly revokedAt: {
         readonly type: "timestamp";
         readonly description?: string;
         readonly required?: boolean;
@@ -90,7 +90,7 @@ export declare const userSessionEntity: import("@cosmicdrift/kumiko-types/fields
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    lastSeenAt: {
+    readonly lastSeenAt: {
         readonly type: "timestamp";
         readonly description?: string;
         readonly required?: boolean;
@@ -105,7 +105,7 @@ export declare const userSessionEntity: import("@cosmicdrift/kumiko-types/fields
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    ip: {
+    readonly ip: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -128,7 +128,7 @@ export declare const userSessionEntity: import("@cosmicdrift/kumiko-types/fields
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    userAgent: {
+    readonly userAgent: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;

package/dist/shared/index.d.ts

@@ -14,6 +14,8 @@ export { mailHeading, mailParagraph, mailRepeatedRows } from "./mail-template-bo
 export { mapWithConcurrency } from "./map-with-concurrency.ts";
 export { denyUnlessJoinRowParentVisible, hostRowIsGone, joinRowParentIsVisible, parentRowIsVisible, } from "./parent-visibility.ts";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing.ts";
+export { type DeleteFileBytes, FileSweepError, type MissingStoragePolicy, purgeFilesReachingSubject, } from "./purge-files-reaching-subject.ts";
+export { collectSingleFileHolders, type FileFieldPlan, type FileRefPurgeOutcome, planFileFields, purgeRowFileRefs, type SingleFileHolder, } from "./purge-row-file-refs.ts";
 export { rateLimitedTextResponse } from "./rate-limited-text-response.ts";
 export { redactBotTokens, redactEmailAddresses, redactErrorText, redactUrls, } from "./redact.ts";
 export { REDACTED_PII_PLACEHOLDER, redactPiiCiphertext } from "./redact-pii-ciphertext.ts";

package/dist/shared/index.js

@@ -14,6 +14,8 @@ export { mailHeading, mailParagraph, mailRepeatedRows } from "./mail-template-bo
 export { mapWithConcurrency } from "./map-with-concurrency.js";
 export { denyUnlessJoinRowParentVisible, hostRowIsGone, joinRowParentIsVisible, parentRowIsVisible, } from "./parent-visibility.js";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing.js";
+export { FileSweepError, purgeFilesReachingSubject, } from "./purge-files-reaching-subject.js";
+export { collectSingleFileHolders, planFileFields, purgeRowFileRefs, } from "./purge-row-file-refs.js";
 export { rateLimitedTextResponse } from "./rate-limited-text-response.js";
 export { redactBotTokens, redactEmailAddresses, redactErrorText, redactUrls, } from "./redact.js";
 export { REDACTED_PII_PLACEHOLDER, redactPiiCiphertext } from "./redact-pii-ciphertext.js";

package/dist/shared/purge-files-reaching-subject.d.ts

@@ -0,0 +1,25 @@
+import { type SubjectId } from "@cosmicdrift/kumiko-framework/crypto";
+import { type DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { type Registry, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { type FileRefPurgeOutcome } from "./purge-row-file-refs.ts";
+export declare class FileSweepError extends Error {
+    readonly code: Exclude<FileRefPurgeOutcome, "purged">;
+    readonly entityName: string;
+    constructor(code: Exclude<FileRefPurgeOutcome, "purged">, entityName: string);
+}
+export type DeleteFileBytes = (storageKey: string) => Promise<readonly string[]>;
+export type MissingStoragePolicy = {
+    readonly mode: "fail";
+} | {
+    readonly mode: "skip";
+    readonly warn: (tenantId: TenantId) => void;
+};
+export declare function purgeFilesReachingSubject(args: {
+    readonly registry: Registry;
+    readonly db: DbRunner;
+    readonly subject: SubjectId;
+    readonly subjectKey: string;
+    readonly recordTenantId?: TenantId;
+    readonly resolveDeleteBytes: (tenantId: TenantId) => Promise<DeleteFileBytes | undefined>;
+    readonly missingStorage: MissingStoragePolicy;
+}): Promise<void>;

package/dist/shared/purge-files-reaching-subject.js

@@ -0,0 +1,146 @@
+import { resolveSubjectForField, SubjectResolutionError, subjectIdToKey, } from "@cosmicdrift/kumiko-framework/crypto";
+import { createEventStoreExecutor, createTenantDb, selectMany, } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemUser, parseTenantId, } from "@cosmicdrift/kumiko-framework/engine";
+import { fileRefEntity, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { collectSingleFileHolders, planFileFields, purgeRowFileRefs, } from "./purge-row-file-refs.js";
+// Callers' error labels read err.code, so audit events name the failure class.
+export class FileSweepError extends Error {
+    code;
+    entityName;
+    constructor(code, entityName) {
+        super(`[files-purge] ${code} while purging files of entity ${entityName}`);
+        this.code = code;
+        this.entityName = entityName;
+        this.name = "FileSweepError";
+    }
+}
+function collectFileEntities(registry) {
+    const found = [];
+    for (const proj of registry.getAllProjections().values()) {
+        if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table)
+            continue;
+        const entity = registry.getEntity(proj.source);
+        if (!entity)
+            continue;
+        const { singleFields, multiFields } = planFileFields(entity.fields);
+        const fileFields = [...singleFields, ...multiFields];
+        if (fileFields.length === 0)
+            continue;
+        found.push({ entityName: proj.source, entity, table: proj.table, fileFields });
+    }
+    return found;
+}
+// Candidate rows only; the exact per-field subject is verified with resolveSubjectForField,
+// the same resolver that encrypted the field.
+function candidateWheres(subject, recordTenantId, { entityName, entity, fileFields }) {
+    if (subject.kind === "record") {
+        // Without the owning tenant the record cannot be told apart from a same-id row elsewhere.
+        return entityName === subject.entity && recordTenantId !== undefined
+            ? [{ id: subject.id, tenantId: recordTenantId }]
+            : [];
+    }
+    if (subject.kind !== "user")
+        return [];
+    const wheres = [];
+    for (const fieldName of fileFields) {
+        const field = entity.fields[fieldName];
+        if (field && "userOwned" in field && field.userOwned !== undefined) {
+            wheres.push({ [field.userOwned.ownerField]: subject.userId });
+        }
+        else if (field && "pii" in field && field.pii === true && entity.idType !== "serial") {
+            wheres.push({ id: subject.userId });
+        }
+    }
+    return wheres;
+}
+function fieldsResolvingToSubject(fileEntity, row, rowTenantId, subjectKey) {
+    return fileEntity.fileFields.filter((fieldName) => {
+        try {
+            const resolved = resolveSubjectForField(fileEntity.entity, fieldName, row, {
+                tenantId: rowTenantId,
+                entityName: fileEntity.entityName,
+            });
+            return resolved !== null && subjectIdToKey(resolved) === subjectKey;
+        }
+        catch (err) {
+            // skip: a field whose owner cannot be resolved on this row never encrypted under this subject
+            if (err instanceof SubjectResolutionError)
+                return false;
+            throw err;
+        }
+    });
+}
+const fileRefExecutor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
+    entityName: "fileRef",
+});
+async function deleteBytesFailingClosed(deleteBytes, storageKey) {
+    try {
+        return await deleteBytes(storageKey);
+    }
+    catch {
+        // skip: an unsafe key or missing list permission fails this file closed, not the whole sweep
+        return [storageKey];
+    }
+}
+// Forgetting a subject erases keys; the files behind a personal file field are not ciphertext,
+// so they need their own purge (bytes, derivatives, fileRef rows). The entity row stays:
+// forgetting is crypto-shredding, not deletion. Tenant subjects are covered by
+// files-tenant-data on tenant destroy. The storage is resolved per owning tenant because a
+// subject's rows can live in any tenant.
+export async function purgeFilesReachingSubject(args) {
+    const { registry, db, subject, subjectKey, recordTenantId, resolveDeleteBytes, missingStorage } = args;
+    // skip: tenant subjects are covered by files-tenant-data on tenant destroy
+    if (subject.kind === "tenant")
+        return;
+    const fileHolders = collectSingleFileHolders(registry);
+    const storageByTenant = new Map();
+    let firstFailure;
+    for (const fileEntity of collectFileEntities(registry)) {
+        const seenRowIds = new Set();
+        for (const where of candidateWheres(subject, recordTenantId, fileEntity)) {
+            const rows = await selectMany(db, fileEntity.table, where);
+            for (const row of rows) {
+                const rowId = String(row["id"]);
+                const tenantId = parseTenantId(row["tenantId"]);
+                // skip: a row without a tenant cannot own tenant-scoped file refs
+                if (seenRowIds.has(rowId) || tenantId === null)
+                    continue;
+                seenRowIds.add(rowId);
+                const fieldNames = fieldsResolvingToSubject(fileEntity, row, tenantId, subjectKey);
+                // skip: none of the row's file fields belongs to this subject
+                if (fieldNames.length === 0)
+                    continue;
+                let storagePromise = storageByTenant.get(tenantId);
+                if (storagePromise === undefined) {
+                    storagePromise = resolveDeleteBytes(tenantId);
+                    storageByTenant.set(tenantId, storagePromise);
+                }
+                const deleteBytes = await storagePromise;
+                const systemUser = createSystemUser(tenantId);
+                const tdb = createTenantDb({ db, tenantId, mode: "system" });
+                const outcome = await purgeRowFileRefs({
+                    db,
+                    tenantId,
+                    entityName: fileEntity.entityName,
+                    entity: fileEntity.entity,
+                    table: fileEntity.table,
+                    fileHolders,
+                    row,
+                    fieldNames,
+                    deleteBytes: deleteBytes
+                        ? (key) => deleteBytesFailingClosed(deleteBytes, key)
+                        : undefined,
+                    fileRefForget: async (fileRefId) => (await fileRefExecutor.forget({ id: fileRefId }, systemUser, tdb)).isSuccess,
+                });
+                if (outcome === "missing_file_storage" && missingStorage.mode === "skip") {
+                    missingStorage.warn(tenantId);
+                }
+                else if (outcome !== "purged") {
+                    firstFailure ??= new FileSweepError(outcome, fileEntity.entityName);
+                }
+            }
+        }
+    }
+    if (firstFailure)
+        throw firstFailure;
+}

package/dist/shared/purge-row-file-refs.d.ts

@@ -0,0 +1,33 @@
+import { type DbRunner, selectMany } from "@cosmicdrift/kumiko-framework/db";
+import type { EntityDefinition, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+type EntityFields = EntityDefinition["fields"];
+type EntityTable = Parameters<typeof selectMany>[1];
+export type FileFieldPlan = {
+    /** type file|image: the fileRef-id lives directly in the entity column. */
+    readonly singleFields: readonly string[];
+    /** type files|images: resolved via file_refs (bound by entityType/entityId/fieldName). */
+    readonly multiFields: readonly string[];
+};
+export type SingleFileHolder = {
+    readonly table: EntityTable;
+    readonly tableHasTenantId: boolean;
+    readonly singleFields: readonly string[];
+};
+export type FileRefPurgeOutcome = "purged" | "missing_file_storage" | "file_delete_failed";
+export declare function planFileFields(fields: EntityFields, fieldNames?: readonly string[]): FileFieldPlan;
+export declare function collectSingleFileHolders(registry: Registry): readonly SingleFileHolder[];
+export declare function purgeRowFileRefs(args: {
+    readonly db: DbRunner;
+    readonly tenantId: TenantId;
+    readonly entityName: string;
+    readonly entity: EntityDefinition;
+    readonly table: EntityTable;
+    readonly fileHolders: readonly SingleFileHolder[];
+    readonly row: Record<string, unknown>;
+    readonly fieldNames?: readonly string[];
+    /** Returns the keys whose delete failed; undefined = no storage reachable. */
+    readonly deleteBytes: ((storageKey: string) => Promise<readonly string[]>) | undefined;
+    readonly fileRefForget: (fileRefId: string) => Promise<boolean>;
+    readonly onBytesDeleteFailed?: (failedKeys: readonly string[]) => void;
+}): Promise<FileRefPurgeOutcome>;
+export {};