@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

package/dist/files/bind-referenced-files.write.d.ts

@@ -13,4 +13,4 @@ export declare const bindReferencedFilesWrite: import("@cosmicdrift/kumiko-types
     bound: number;
     skipped: number;
     nextAfterId: string | null;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

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

@@ -5,6 +5,7 @@ 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 { loadFileRefRows } from "./load-save-file-refs.js";
 import { findImplicitEntityTable } from "./record-write-check.js";
 const MAX_PAGE_SIZE = 500;
 const DEFAULT_PAGE_SIZE = 200;
@@ -50,40 +51,48 @@ function loadRecordPage(db, { entity, table }, { entityIds, afterId, limit }) {
             : 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.
+// Unbound and same tenant. The record's creator may bind their own unclaimed or pending upload.
+// A system-generated file carries no owner of its own, so it binds only where it is already
+// pending for exactly this entity field — an unclaimed one could otherwise be pulled into any
+// record that merely names its id.
 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)));
+    if (typeof uploader !== "string" ||
+        fileRef["tenantId"] !== target.tenantId ||
+        fileRef["entityId"] !== null) {
+        return false;
+    }
+    const isPendingForTarget = fileRef["entityType"] === target.entityType && fileRef["fieldName"] === target.fieldName;
+    if (uploader === target.record["insertedById"]) {
+        return fileRef["entityType"] === null || isPendingForTarget;
+    }
+    return uploader === SYSTEM_USER_ID && isPendingForTarget;
 }
 // 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.
+// system generated it for exactly this field), 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.",
+    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 for exactly this field; 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 referencedIds = records.flatMap((record) => fileFieldNames.flatMap((fieldName) => fileRefIdsOf(record[fieldName])));
+        const fileRefRows = await loadFileRefRows(ctx.db, referencedIds, event.user.tenantId);
         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 ||
+                    const row = fileRefRows.get(fileRefId);
+                    if (row === undefined ||
                         !isBindableToRecord(row, {
                             record,
                             entityType,

package/dist/files/create-file-ref-from-bytes.d.ts

@@ -1,8 +1,8 @@
 import type { TenantDb } from "../db/tenant-db.js";
-import type { Registry, SessionUser, WriteResult } from "../engine/types/index.js";
-import { type CreatedFileRef } from "./create-file-ref.js";
+import type { BeforeTransactionResult, Registry, SessionUser, WriteResult } from "../engine/types/index.js";
+import { type CreatedFileRef, type UploadedFileBytes } from "./create-file-ref.js";
 import type { FileContext } from "./file-handle.js";
-export type { CreatedFileRef };
+export type { CreatedFileRef, UploadedFileBytes };
 export type CreateFileRefContext = {
     readonly db: TenantDb;
     readonly files?: FileContext | undefined;
@@ -20,3 +20,6 @@ export type CreateFileRefInput = {
     };
 };
 export declare function createFileRefFromBytes(ctx: CreateFileRefContext, input: CreateFileRefInput): Promise<WriteResult<CreatedFileRef>>;
+export type UploadFileBytesContext = Pick<CreateFileRefContext, "db" | "files" | "registry" | "user">;
+export declare function uploadFileBytesBeforeTransaction(ctx: UploadFileBytesContext, input: CreateFileRefInput): Promise<BeforeTransactionResult<UploadedFileBytes>>;
+export declare function createFileRefFromUploadedBytes(ctx: Pick<CreateFileRefContext, "db" | "user">, uploaded: UploadedFileBytes): Promise<WriteResult<CreatedFileRef>>;

package/dist/files/create-file-ref-from-bytes.js

@@ -1,6 +1,9 @@
+import { fetchOne } from "../bun-db/query.js";
 import { FrameworkReasons, InternalError, UnprocessableError, writeFailure, } from "../errors/index.js";
-import { DEFAULT_MAX_UPLOAD_SIZE, storeFileAsFileRef, } from "./create-file-ref.js";
+import { createFileRefRow, DEFAULT_MAX_UPLOAD_SIZE, storeFileAsFileRef, writeAcceptedFileBytes, } from "./create-file-ref.js";
+import { fileRefsTable } from "./file-ref-table.js";
 import { readFilesRouteOptions } from "./file-routes.js";
+import { assertSafeStorageKey } from "./types.js";
 // Server-side counterpart of POST /files for handlers/jobs that produce bytes
 // themselves (generated PDFs, exports). Same validation, storage layout and
 // fileRef.created event as an upload; the tenant is always ctx.user.tenantId.
@@ -30,10 +33,70 @@ export async function createFileRefFromBytes(ctx, input) {
         case "created":
             return { isSuccess: true, data: outcome.fileRef };
         case "rejected":
-            return writeFailure(new UnprocessableError(FrameworkReasons.fileRejected, {
-                details: { error: outcome.error },
-            }));
+            return fileRejectedFailure(outcome.error);
         case "failed":
             return outcome.failure;
     }
 }
+function fileRejectedFailure(error) {
+    return writeFailure(new UnprocessableError(FrameworkReasons.fileRejected, { details: { error } }));
+}
+// Pre-transaction half of createFileRefFromBytes: validates and writes the binary while no
+// transaction holds a connection. Pair it with createFileRefFromUploadedBytes inside the handler.
+// A crash between this phase and the commit leaves the bytes in storage; nothing sweeps them.
+export async function uploadFileBytesBeforeTransaction(ctx, input) {
+    const { files } = ctx;
+    if (!files) {
+        return writeFailure(new InternalError({
+            message: "uploadFileBytesBeforeTransaction: ctx.files is unavailable — mount a file-provider feature to store files",
+        }));
+    }
+    const outcome = await writeAcceptedFileBytes({
+        user: ctx.user,
+        registry: ctx.registry,
+        defaultMaxUploadSize: readFilesRouteOptions(ctx.registry).maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
+        writeBytes: (key, data, mimeType) => files.ref(key).write(data, mimeType),
+    }, {
+        fileName: input.fileName,
+        declaredMimeType: input.mimeType,
+        data: input.data,
+        entityType: input.attachTo?.entityType,
+        entityId: input.attachTo?.entityId,
+        fieldName: input.attachTo?.fieldName,
+    });
+    if (outcome.kind === "rejected")
+        return fileRejectedFailure(outcome.error);
+    const { uploaded } = outcome;
+    return {
+        isSuccess: true,
+        data: uploaded,
+        // Also runs after a failed COMMIT whose outcome is unknown: a committed row must keep its binary.
+        release: async () => {
+            const committedRow = await fetchOne(ctx.db, fileRefsTable, {
+                storageKey: uploaded.storageKey,
+            });
+            if (!committedRow)
+                await files.ref(uploaded.storageKey).delete();
+        },
+    };
+}
+// Transaction half: creates the fileRef row for bytes uploadFileBytesBeforeTransaction wrote.
+export async function createFileRefFromUploadedBytes(ctx, uploaded) {
+    const ownPrefix = `${ctx.user.tenantId}/`;
+    if (!uploaded.storageKey.startsWith(ownPrefix)) {
+        return writeFailure(new InternalError({
+            message: "createFileRefFromUploadedBytes: storageKey is outside the caller's tenant prefix",
+        }));
+    }
+    try {
+        assertSafeStorageKey(uploaded.storageKey);
+    }
+    catch (error) {
+        return writeFailure(new InternalError({
+            message: "createFileRefFromUploadedBytes: unsafe storageKey",
+            ...(error instanceof Error && { cause: error }),
+        }));
+    }
+    const row = await createFileRefRow({ user: ctx.user, tenantDb: ctx.db }, uploaded);
+    return "failure" in row ? row.failure : { isSuccess: true, data: row.fileRef };
+}

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

@@ -1,4 +1,4 @@
-import type { TenantDb } from "../db/tenant-db.js";
+import { type TenantDb } from "../db/tenant-db.js";
 import { type AnyFileFieldDef, type Registry, type SessionUser } from "../engine/types/index.js";
 import type { WriteFailure } from "../errors/index.js";
 export declare const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
@@ -24,6 +24,7 @@ export type StoreFileInput = {
 export type StoreFileDeps = {
     readonly user: SessionUser;
     readonly tenantDb: TenantDb;
+    readonly rowInOwnTransaction?: boolean;
     readonly registry: Registry | undefined;
     readonly defaultMaxUploadSize: string;
     readonly writeBytes: (storageKey: string, data: Uint8Array, mimeType: string) => Promise<void>;
@@ -36,6 +37,22 @@ export type CreatedFileRef = {
     readonly size: number;
     readonly storageKey: string;
 };
+export type UploadedFileBytes = {
+    readonly storageKey: string;
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly size: number;
+    readonly entityType?: string | undefined;
+    readonly entityId?: string | undefined;
+    readonly fieldName?: string | undefined;
+};
+export type UploadBytesOutcome = {
+    readonly kind: "uploaded";
+    readonly uploaded: UploadedFileBytes;
+} | {
+    readonly kind: "rejected";
+    readonly error: string;
+};
 export type StoreFileOutcome = {
     readonly kind: "created";
     readonly fileRef: CreatedFileRef;
@@ -46,5 +63,11 @@ export type StoreFileOutcome = {
     readonly kind: "failed";
     readonly failure: WriteFailure;
 };
+export declare function writeAcceptedFileBytes(deps: Pick<StoreFileDeps, "user" | "registry" | "defaultMaxUploadSize" | "writeBytes">, input: StoreFileInput): Promise<UploadBytesOutcome>;
+export declare function createFileRefRow(deps: Pick<StoreFileDeps, "user" | "tenantDb">, uploaded: UploadedFileBytes): Promise<{
+    readonly fileRef: CreatedFileRef;
+} | {
+    readonly failure: WriteFailure;
+}>;
 export declare function storeFileAsFileRef(deps: StoreFileDeps, input: StoreFileInput): Promise<StoreFileOutcome>;
 export {};

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

@@ -1,4 +1,5 @@
 import { createEventStoreExecutor } from "../db/event-store-executor.js";
+import { runInOwnTransaction } from "../db/tenant-db.js";
 import { isFileField, } from "../engine/types/index.js";
 import { generateId } from "../utils/index.js";
 import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
@@ -92,44 +93,85 @@ function acceptFile(deps, input) {
         extension: undefined,
     };
 }
-// The one upload pipeline behind POST /files and createFileRefFromBytes.
-export async function storeFileAsFileRef(deps, input) {
+// Upload step: validates and writes the binary. Outside any transaction on purpose — network/disk
+// I/O doesn't belong inside a PG connection's tx window.
+export async function writeAcceptedFileBytes(deps, input) {
     const { fileName, data, entityType, entityId, fieldName } = input;
     const accepted = acceptFile(deps, input);
     if (accepted.kind === "rejected")
         return accepted;
     const { mimeType, extension } = accepted;
-    const fileRefId = generateId();
     const storageKey = buildStorageKey(deps.user.tenantId, entityType ?? "unattached", entityId, fieldName ?? "file", fileName, generateId(), extension);
-    // Write binary FIRST (outside the tx — network/disk I/O doesn't belong
-    // inside a PG connection's tx window). A failed create deletes the bytes
-    // again below; a later rollback of an enclosing transaction cannot, so
-    // those are orphaned for the cleanup-jobs to sweep. Losing a row on
-    // append-failure is acceptable; a committed row with a missing binary is not.
     await deps.writeBytes(storageKey, data, mimeType);
-    // id is explicit so the response + storageKey stay consistent; tenantId,
-    // insertedAt and insertedById are set by applyEntityEvent from the event metadata.
+    return {
+        kind: "uploaded",
+        uploaded: {
+            storageKey,
+            fileName,
+            mimeType,
+            size: data.byteLength,
+            entityType,
+            entityId,
+            fieldName,
+        },
+    };
+}
+// Row step: id is explicit so the response + storageKey stay consistent; tenantId, insertedAt and
+// insertedById are set by applyEntityEvent from the event metadata.
+export async function createFileRefRow(deps, uploaded) {
+    const fileRefId = generateId();
     const result = await getFileRefExecutor().create({
         id: fileRefId,
-        storageKey,
-        fileName,
-        mimeType,
-        size: data.byteLength,
-        entityType: entityType ?? null,
-        entityId: entityId ?? null,
-        fieldName: fieldName ?? null,
+        storageKey: uploaded.storageKey,
+        fileName: uploaded.fileName,
+        mimeType: uploaded.mimeType,
+        size: uploaded.size,
+        entityType: uploaded.entityType ?? null,
+        entityId: uploaded.entityId ?? null,
+        fieldName: uploaded.fieldName ?? null,
     }, deps.user, deps.tenantDb);
-    if (!result.isSuccess) {
+    if (!result.isSuccess)
+        return { failure: result };
+    return {
+        fileRef: {
+            id: fileRefId,
+            fileName: uploaded.fileName,
+            mimeType: uploaded.mimeType,
+            size: uploaded.size,
+            storageKey: uploaded.storageKey,
+        },
+    };
+}
+// The one upload pipeline behind POST /files and createFileRefFromBytes.
+export async function storeFileAsFileRef(deps, input) {
+    const upload = await writeAcceptedFileBytes(deps, input);
+    if (upload.kind === "rejected")
+        return upload;
+    // A failed create deletes the bytes again; a later rollback of an enclosing transaction or a
+    // crash cannot, so those bytes stay in storage (no job sweeps an original without a fileRef row).
+    // Losing a row on append-failure is acceptable; a committed row with a missing binary is not.
+    // A throwing projection on fileRef.created fails the create by exception, not by WriteFailure.
+    const deleteUploadedBytes = async () => {
         try {
-            await deps.deleteBytes(storageKey);
+            await deps.deleteBytes(upload.uploaded.storageKey);
         }
         catch {
-            // skip: the create failure is the error worth reporting; leftover bytes are swept by cleanup-jobs.
+            // skip: the create failure is the error worth reporting; the leftover bytes stay in storage.
         }
-        return { kind: "failed", failure: result };
-    }
-    return {
-        kind: "created",
-        fileRef: { id: fileRefId, fileName, mimeType, size: data.byteLength, storageKey },
     };
+    let row;
+    try {
+        row = deps.rowInOwnTransaction
+            ? await runInOwnTransaction(deps.tenantDb, (txDb) => createFileRefRow({ user: deps.user, tenantDb: txDb }, upload.uploaded))
+            : await createFileRefRow(deps, upload.uploaded);
+    }
+    catch (e) {
+        await deleteUploadedBytes();
+        throw e;
+    }
+    if ("failure" in row) {
+        await deleteUploadedBytes();
+        return { kind: "failed", failure: row.failure };
+    }
+    return { kind: "created", fileRef: row.fileRef };
 }

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

@@ -3,16 +3,31 @@ 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) {
+// The bound fieldName may differ from the field the id was removed from: an id
+// moved A -> B stays bound to A (binding never re-targets).
+function isBoundToRecord(row, entityName, entityId, fileFields) {
+    const boundField = row["fieldName"];
     return (row["entityType"] === entityName &&
         row["entityId"] === entityId &&
-        row["fieldName"] === fieldName);
+        typeof boundField === "string" &&
+        isFileField(fileFields[boundField]));
+}
+// Across all file fields: an id moved from one field to another is still in use.
+function fileRefIdsStoredInAnyField(fields, data) {
+    const ids = new Set();
+    for (const [fieldName, fieldDef] of Object.entries(fields)) {
+        if (!isFileField(fieldDef))
+            continue;
+        for (const fileRefId of fileRefIdsOf(data[fieldName]))
+            ids.add(fileRefId);
+    }
+    return ids;
 }
 // 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
+// record 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) {
@@ -33,15 +48,15 @@ export async function disposeRemovedFileRefs(args) {
         return;
     const entityId = String(result.id);
     const executor = getFileRefExecutor();
+    const keptAnywhere = fileRefIdsStoredInAnyField(entity.fields, result.data);
     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))
+            if (keptAnywhere.has(fileRefId))
                 continue;
             const row = await executor.detail({ id: fileRefId }, user, db);
-            if (row === null || !isBoundTo(row, entityName, entityId, fieldName))
+            if (row === null || !isBoundToRecord(row, entityName, entityId, entity.fields))
                 continue;
             const removed = await executor.delete({ id: fileRefId }, user, db);
             if (!removed.isSuccess)

package/dist/files/feature.d.ts

@@ -7,4 +7,5 @@ export type FilesFeatureOptions = {
     readonly unclaimedUploadReaders?: readonly string[];
     readonly maxUploadSize?: string;
 };
+export declare const FILES_FEATURE: "files";
 export declare function createFilesFeature(options?: FilesFeatureOptions): FeatureDefinition;

package/dist/files/feature.js

@@ -13,8 +13,9 @@ export { fileRefEntity } from "./file-ref-entity.js";
 // userData/tenantData-Extensions sichtbar und registriert die implizite
 // Entity-Projektion (für rebuildProjection). Liegt im Framework neben
 // file-routes + fileRefsTable; bundled-features/files re-exportiert nur.
+export const FILES_FEATURE = "files";
 export function createFilesFeature(options = {}) {
-    return defineFeature("files", (r) => {
+    return defineFeature(FILES_FEATURE, (r) => {
         r.describe("Exposes the `fileRef` entity from the framework core so that uploaded files — tracked in the `file_refs` table by `createFileRoutes` — participate in cross-feature hooks: `user-data-rights-defaults` automatically includes file blobs in GDPR exports and forget flows, and tenant-lifecycle cleanup deletes all refs on tenant destroy. Upload/download routes are registered by the server bootstrap when a `file-provider-*` feature is mounted; this feature carries their access/size policy via `createFilesFeature(opts?)`.");
         r.uiHints({
             displayLabel: "Files · Metadata",

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

@@ -1,5 +1,5 @@
 import type { FileContext, FileHandle } from "@cosmicdrift/kumiko-types/file-handle-types";
-import type { FileStorageProvider } from "./types.js";
+import { type FileStorageProvider } from "./types.js";
 export type { FileContext, FileHandle };
 export declare function createFileHandle(key: string, getProvider: () => Promise<FileStorageProvider>): FileHandle;
 export declare function createFileContext(resolve: () => Promise<FileStorageProvider>, tenantId?: string): FileContext;

package/dist/files/file-handle.js

@@ -11,6 +11,7 @@
 // `foo/bar.medium-<16 hex>.jpg`. The suffix must be a `variantSuffix(...)` so
 // the erasure sweep recognizes it. Stable, reversible, no extra lookup tables.
 import { isDerivativeSuffix } from "../derivatives/variant-key.js";
+import { assertSafeStorageKey } from "./types.js";
 // `getProvider` is a lazily-resolved, memoized accessor — the provider is
 // resolved (config + s3.secretAccessKey secret read) only when a handle method
 // actually does I/O, never on every request that merely builds a ctx.
@@ -54,6 +55,17 @@ export function createFileContext(resolve, tenantId) {
             }
             return createFileHandle(key, getProvider);
         },
+        /** Validates only the storage key shape (assertSafeStorageKey), no tenant prefix: keys
+         *  may outlive a tenant handover. The caller must ensure the fileRef row came from a
+         *  tenant-filtered read. */
+        refFromFileRef: (row) => {
+            assertSafeStorageKey(row.storageKey);
+            return createFileHandle(row.storageKey, getProvider);
+        },
+        listFromFileRef: async (row) => {
+            assertSafeStorageKey(row.storageKey);
+            return (await getProvider()).list(storageKeyStemPrefix(row.storageKey));
+        },
         list: async (prefix) => {
             if (tenantId !== undefined && !prefix.startsWith(`${tenantId}/`)) {
                 throw new Error(`FileContext.list: prefix must start with "${tenantId}/"`);

package/dist/files/file-routes.js

@@ -4,8 +4,9 @@ import { getUser } from "../api/auth-middleware.js";
 import { requestContext } from "../api/request-context.js";
 import { selectMany } from "../bun-db/index.js";
 import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, isPiiCiphertext, PII_ERASED_SENTINEL, } from "../crypto/index.js";
-import { createTenantDb } from "../db/tenant-db.js";
+import { createProjectingTenantDb } from "../db/tenant-db.js";
 import { createDerivativesContext, resolveFieldVariant, resolveRenderer, } from "../derivatives/index.js";
+import { SYSTEM_USER_ID } from "../engine/system-user.js";
 import { isFileField, isUuid, } from "../engine/types/index.js";
 import { buildContentDispositionHeader } from "./content-disposition.js";
 import { DEFAULT_MAX_UPLOAD_SIZE, getFileRefExecutor, storeFileAsFileRef, } from "./create-file-ref.js";
@@ -32,8 +33,11 @@ function createDefaultGuard(privilegedRoles, canReadRecord, unclaimedUploadReade
             return "allow";
         if (privilegedRoles.some((role) => user.roles.includes(role)))
             return "allow";
-        const isUnclaimed = fileRef.entityType === null && fileRef.entityId === null;
-        if (isUnclaimed &&
+        // System-generated documents are created without attachTo too, but belong to a person's data, not to an inbox.
+        const isUnclaimedUpload = fileRef.entityType === null &&
+            fileRef.entityId === null &&
+            fileRef.insertedById !== SYSTEM_USER_ID;
+        if (isUnclaimedUpload &&
             operation === "read" &&
             unclaimedUploadReaders.some((role) => user.roles.includes(role))) {
             return "allow";
@@ -88,8 +92,7 @@ export function createFileRoutes(options) {
     const executor = getFileRefExecutor();
     const piiSubjectFields = collectPiiSubjectFields(fileRefEntity);
     const api = new Hono();
-    const projectionGrants = options.registry ? { projectionRegistry: options.registry } : undefined;
-    const tenantDbFor = (tenantId) => createTenantDb(db, tenantId, "tenant", undefined, undefined, undefined, projectionGrants);
+    const tenantDbFor = (tenantId) => createProjectingTenantDb(db, tenantId, options.registry);
     const fileNameIsPersonal = piiSubjectFields.includes("fileName");
     function kmsContextFor() {
         return { requestId: requestContext.get()?.requestId ?? "file-routes" };
@@ -171,6 +174,7 @@ export function createFileRoutes(options) {
         const outcome = await storeFileAsFileRef({
             user,
             tenantDb: tenantDbFor(user.tenantId),
+            rowInOwnTransaction: true,
             registry: options.registry,
             defaultMaxUploadSize: options.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
             writeBytes: (key, bytes, mimeType) => storageProvider.write(key, bytes, mimeType),
@@ -261,7 +265,7 @@ export function createFileRoutes(options) {
             tenantId: user.tenantId,
         });
         const result = await derivatives.variant(id, spec, name);
-        const data = await files.ref(result.storageKey).read();
+        const data = await files.refFromFileRef(result).read();
         // No Content-Length/Content-Disposition: fileRef.size is the ORIGINAL's
         // size, and a variant is rendered for display, not for download.
         // storageKey embeds specHash(spec), so the URL is content-stable until

package/dist/files/index.d.ts

@@ -1,6 +1,6 @@
-export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, } from "./create-file-ref-from-bytes.js";
-export { createFileRefFromBytes } from "./create-file-ref-from-bytes.js";
-export { createFilesFeature } from "./feature.js";
+export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, UploadedFileBytes, UploadFileBytesContext, } from "./create-file-ref-from-bytes.js";
+export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.js";
+export { createFilesFeature, FILES_FEATURE } from "./feature.js";
 export type { FileContext, FileHandle } from "./file-handle.js";
 export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle.js";
 export { fileRefEntity } from "./file-ref-entity.js";

package/dist/files/index.js

@@ -1,5 +1,5 @@
-export { createFileRefFromBytes } from "./create-file-ref-from-bytes.js";
-export { createFilesFeature } from "./feature.js";
+export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.js";
+export { createFilesFeature, FILES_FEATURE } from "./feature.js";
 // `createFileHandle` is an implementation detail — construct handles via
 // `createFileContext(provider).ref(key)`, which is the AppContext surface.
 export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle.js";

package/dist/files/load-save-file-refs.d.ts

@@ -0,0 +1,10 @@
+import type { TenantDb } from "../db/tenant-db.js";
+import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.js";
+export type FileRefRows = ReadonlyMap<string, Readonly<Record<string, unknown>>>;
+export declare function loadSaveFileRefs(args: {
+    readonly registry: Registry;
+    readonly result: SaveContext;
+    readonly user: SessionUser;
+    readonly db: TenantDb;
+}): Promise<FileRefRows>;
+export declare function loadFileRefRows(db: TenantDb, ids: readonly string[], tenantId: SessionUser["tenantId"]): Promise<FileRefRows>;

package/dist/files/load-save-file-refs.js

@@ -0,0 +1,47 @@
+import { selectMany } from "../db/query.js";
+import { tenantDbRunner } from "../db/tenant-db-runner.js";
+import { isFileField, } from "../engine/types/index.js";
+import { getStreamVersions } from "../event-store/event-store.js";
+import { fileRefIdsOf } from "./bind-pending-file-refs.js";
+import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
+import { fileRefsTable } from "./file-ref-table.js";
+// One query for every fileRef a save names, restricted to the writer's own tenant and live
+// rows: the tenant check and the pending-upload binding both work from this map instead of
+// reading each row again inside the write transaction.
+export async function loadSaveFileRefs(args) {
+    const { registry, result, user, db } = args;
+    const entity = result.entityName === undefined ? undefined : registry.getEntity(result.entityName);
+    // skip: saves of unregistered or unnamed aggregates declare no file fields
+    if (entity === undefined)
+        return new Map();
+    // skip: without the files feature the file_refs table is not part of the schema
+    if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
+        return new Map();
+    const ids = new Set();
+    for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
+        if (!isFileField(fieldDef))
+            continue;
+        for (const id of fileRefIdsOf(result.changes[fieldName]))
+            ids.add(id);
+    }
+    return loadFileRefRows(db, [...ids], user.tenantId);
+}
+// One query for the given live fileRefs of one tenant. Each row carries the stream version as
+// `version`: the binding update needs it as expectedVersion, and events without a projection
+// effect (e.g. ingest requests) advance the stream but not the row's version column.
+export async function loadFileRefRows(db, ids, tenantId) {
+    // skip: nothing referenced, nothing to load
+    if (ids.length === 0)
+        return new Map();
+    const rows = await selectMany(db, fileRefsTable, {
+        id: { in: [...ids] },
+        tenantId,
+        isDeleted: false,
+    });
+    const streamVersions = await getStreamVersions(tenantDbRunner(db), rows.map((row) => String(row["id"])), db.tenantId);
+    return new Map(rows.map((row) => {
+        const id = String(row["id"]);
+        const streamVersion = streamVersions.get(id);
+        return [id, streamVersion === undefined ? row : { ...row, version: streamVersion }];
+    }));
+}

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

@@ -4,11 +4,14 @@ 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;
+type PurgeTable = Parameters<typeof deleteMany>[1];
 export declare function purgeExpiredFileRefsWithBytes(args: {
     readonly db: TenantDb;
-    readonly table: Parameters<typeof deleteMany>[1];
+    readonly table: PurgeTable;
     readonly where: WhereObject;
+    readonly expiredBefore: Temporal.Instant;
     readonly files: FileContext | undefined;
     readonly log: PurgeLog;
+    readonly pageSize?: number;
 }): Promise<void>;
 export {};