@cosmicdrift/kumiko-framework 0.363.0 → 0.364.0

package/dist/errors/kumiko-error.d.ts

@@ -11,6 +11,7 @@ export type ErrorCtorInput = {
     readonly i18nParams?: Readonly<Record<string, unknown>>;
     readonly details?: unknown;
     readonly cause?: Error;
+    readonly retryAfterSeconds?: number;
 };
 export declare abstract class KumikoError extends Error {
     abstract readonly code: string;
@@ -18,6 +19,7 @@ export declare abstract class KumikoError extends Error {
     readonly i18nKey: string;
     readonly i18nParams: Readonly<Record<string, unknown>> | undefined;
     readonly details: unknown;
+    readonly retryAfterSeconds: number | undefined;
     constructor(input: ErrorCtorInput);
 }
 export declare function isKumikoError(e: unknown): e is KumikoError;

package/dist/errors/kumiko-error.js

@@ -6,12 +6,14 @@ export class KumikoError extends Error {
     i18nKey;
     i18nParams;
     details;
+    retryAfterSeconds;
     constructor(input) {
         super(input.message, input.cause ? { cause: input.cause } : undefined);
         this.name = new.target.name;
         this.i18nKey = input.i18nKey;
         this.i18nParams = input.i18nParams;
         this.details = input.details;
+        this.retryAfterSeconds = input.retryAfterSeconds;
     }
 }
 export function isKumikoError(e) {

package/dist/errors/write-error-info.js

@@ -69,6 +69,7 @@ export function toWriteErrorInfo(err) {
         message: err.message,
         ...(err.i18nParams && { i18nParams: err.i18nParams }),
         ...(effectiveDetails !== undefined && { details: effectiveDetails }),
+        ...(err.retryAfterSeconds !== undefined && { retryAfterSeconds: err.retryAfterSeconds }),
     };
     if (err.cause instanceof Error)
         causeByWriteErrorInfo.set(info, err.cause);
@@ -91,6 +92,7 @@ class ReraisedError extends KumikoError {
             i18nKey: info.i18nKey,
             ...(info.i18nParams && { i18nParams: info.i18nParams }),
             ...(info.details !== undefined && { details: info.details }),
+            ...(info.retryAfterSeconds !== undefined && { retryAfterSeconds: info.retryAfterSeconds }),
             ...(cause && { cause }),
         });
         this.code = info.code;

package/dist/event-store/tenant-db-append.js

@@ -1,11 +1,11 @@
-import { tenantDbRunner } from "../db/tenant-db-runner.js";
+import { tenantDbRunner, tenantDbWriteRunner } from "../db/tenant-db-runner.js";
 import { runProjectionsForEvent } from "../pipeline/projections-runner.js";
 import { append, getStreamVersion } from "./event-store.js";
 // Appends on the connection or transaction the TenantDb is bound to. The tenant is always the
 // TenantDb's own, so a caller cannot write into another tenant's stream; a TenantDb the framework
 // did not build (or a fail-closed systemScope guard) is rejected by tenantDbRunner.
 export async function appendEventInTenantDb(tenantDb, event, options = {}) {
-    const runner = tenantDbRunner(tenantDb);
+    const runner = tenantDbWriteRunner(tenantDb, "appendEventInTenantDb");
     const stored = await append(runner, { ...event, tenantId: tenantDb.tenantId });
     if (options.registry)
         await runProjectionsForEvent(stored, options.registry, runner);

package/dist/files/assert-file-refs-belong-to-tenant.d.ts

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

package/dist/files/assert-file-refs-belong-to-tenant.js

@@ -1,16 +1,17 @@
-import { isFileField, isUuid, } from "../engine/types/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";
 // A file field only stores an id, and the file routes authorize by tenant at
 // read time: without this check a writer could name another tenant's fileRef
 // and make the record point at it. Only newly written values are checked (all
 // of a create, `changes` of an update), so existing data is left alone. The
 // error is the same for "missing" and "belongs to another tenant" so the id
-// cannot be probed across tenants.
-export async function assertFileRefsBelongToTenant(args) {
-    const { registry, result, user, db } = args;
+// cannot be probed across tenants. `fileRefRows` holds only the writer's own
+// tenant's live rows, so a missing entry is exactly those two cases. Values
+// that are not UUIDs are skipped by fileRefIdsOf and never reach this check.
+export function assertFileRefsBelongToTenant(args) {
+    const { registry, result, fileRefRows } = args;
     // skip: saves of unregistered aggregates (custom executors) declare no file fields
     if (result.entityName === undefined)
         return;
@@ -21,12 +22,11 @@ export async function assertFileRefsBelongToTenant(args) {
     // 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 executor = getFileRefExecutor();
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
         if (!isFileField(fieldDef))
             continue;
         for (const fileRefId of fileRefIdsOf(result.changes[fieldName])) {
-            if (await isFileRefOfTenant(executor, fileRefId, user, db))
+            if (fileRefRows.has(fileRefId))
                 continue;
             throw new ValidationError({
                 fields: [
@@ -40,11 +40,3 @@ export async function assertFileRefsBelongToTenant(args) {
         }
     }
 }
-async function isFileRefOfTenant(executor, fileRefId, user, db) {
-    if (!isUuid(fileRefId))
-        return false;
-    // detail() widens its tenant filter to (self, SYSTEM); only the writer's own
-    // tenant counts here, same as GET /files/:id/meta.
-    const row = await executor.detail({ id: fileRefId }, user, db);
-    return row !== null && row["tenantId"] === user.tenantId;
-}

package/dist/files/bind-pending-file-refs.d.ts

@@ -1,9 +1,11 @@
 import type { TenantDb } from "../db/tenant-db.js";
 import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.js";
+import type { FileRefRows } from "./load-save-file-refs.js";
 export declare function fileRefIdsOf(value: unknown): readonly string[];
 export declare function bindPendingFileRefs(args: {
     readonly registry: Registry;
     readonly result: SaveContext;
     readonly user: SessionUser;
     readonly db: TenantDb;
+    readonly fileRefRows: FileRefRows;
 }): Promise<void>;

package/dist/files/bind-pending-file-refs.js

@@ -23,7 +23,7 @@ function isPendingUploadFor(row, entityName, fieldName, user) {
 // someone else's upload id in a save payload must not pull that file into a
 // record the caller controls.
 export async function bindPendingFileRefs(args) {
-    const { registry, result, user, db } = args;
+    const { registry, result, user, db, fileRefRows } = args;
     // skip: saves of unnamed aggregates declare no file fields
     if (result.entityName === undefined)
         return;
@@ -42,8 +42,8 @@ export async function bindPendingFileRefs(args) {
         // changes, not data: an update's row carries every stored file id, including
         // ones bound earlier; only the ids this save names can be pending uploads.
         for (const fileRefId of fileRefIdsOf(result.changes[fieldName])) {
-            const row = await executor.detail({ id: fileRefId }, user, db);
-            if (row === null || !isPendingUploadFor(row, entityName, fieldName, user))
+            const row = fileRefRows.get(fileRefId);
+            if (row === undefined || !isPendingUploadFor(row, entityName, fieldName, user))
                 continue;
             const version = typeof row["version"] === "number" ? row["version"] : undefined;
             const bound = await executor.update({ id: fileRefId, version, changes: { entityId: String(result.id) } }, user, db);

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

@@ -36,6 +36,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 +62,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

@@ -92,44 +92,72 @@ 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.
+    const row = await createFileRefRow(deps, upload.uploaded);
+    if ("failure" in row) {
         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: "failed", failure: row.failure };
     }
-    return {
-        kind: "created",
-        fileRef: { id: fileRefId, fileName, mimeType, size: data.byteLength, storageKey },
-    };
+    return { kind: "created", fileRef: row.fileRef };
 }

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,13 @@ 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);
+        },
         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

@@ -261,7 +261,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,5 +1,5 @@
-export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, } from "./create-file-ref-from-bytes.js";
-export { createFileRefFromBytes } from "./create-file-ref-from-bytes.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 } from "./feature.js";
 export type { FileContext, FileHandle } from "./file-handle.js";
 export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle.js";

package/dist/files/index.js

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

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 {};