@cosmicdrift/kumiko-framework 0.371.1 → 0.373.0

package/dist/engine/types/index.d.ts

@@ -7,8 +7,8 @@ export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsM
 export type { BootCheckContext, BootCheckFn, BootOptionName, EntityObjectDefinition, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, HookDefinition, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StackBootRequirement, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
 export type { FieldIconKey } from "@cosmicdrift/kumiko-types/field-icon";
 export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityEventMigration, EntityIndexDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
-export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadBucketNormalization, PayloadRateLimitOption, PreparedWriteEvent, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TenantWriteTarget, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
-export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
+export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadBucketNormalization, PayloadRateLimitOption, PreparedWriteEvent, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitOptions, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TenantWriteTarget, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
+export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, declaredRateLimitOptions, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isRateLimitOption, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export type { DeleteContext, EntityHookMap, HookMap, HookOwner, HookPhase, LifecycleHookFn, LifecycleResult, OwnedFn, PhasedHook, PostDeleteBatchHookFn, PostDeleteHookFn, PostQueryHookFn, PostSaveBatchHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SaveContext, SearchPayloadContributorFn, ValidationError, ValidationHookFn, } from "@cosmicdrift/kumiko-types/hooks";
 export type { HttpRouteDefinition, HttpRouteHandler, HttpRouteHandlerDeps, HttpRouteMethod, } from "@cosmicdrift/kumiko-types/http-route";
 export type { EntityId, TenantId } from "@cosmicdrift/kumiko-types/identifiers";

package/dist/engine/types/index.js

@@ -1,7 +1,7 @@
 // Barrel: re-exports all types from @cosmicdrift/kumiko-types, plus the
 // runtime helpers below that stay framework-side.
 export { isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-types/agent-exposure";
-export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
+export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, declaredRateLimitOptions, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isRateLimitOption, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-types/identifiers";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, isFileField } from "../field-helpers.js";

package/dist/entrypoint/index.d.ts

@@ -17,6 +17,7 @@ export type BaseEntrypointOptions = {
     readonly jwtSecret: string | JwtKeyring;
     readonly jwtIssuer?: string;
     readonly observability?: ObservabilityProvider;
+    /** @deprecated No effect: the HTTP route label carries no query string anymore, so there is nothing left to configure. */
     readonly observabilityOptions?: ObservabilityOptions;
     readonly dispatcherOptions?: Omit<DispatcherOptions, "lifecycle">;
     readonly systemHooks?: SystemHooks;

package/dist/entrypoint/index.js

@@ -127,7 +127,6 @@ function buildApiServer(opts, lifecycle, dispatcherOverride, jobRunner, processL
         metrics: opts.metrics,
         extraRoutes: opts.extraRoutes,
         observability: opts.observability,
-        observabilityOptions: opts.observabilityOptions,
         dispatcherOptions,
         systemHooks: opts.systemHooks,
         eventDedup: opts.eventDedup,
@@ -147,7 +146,6 @@ function buildWorkerServer(opts, lifecycle, jobRunner) {
         lifecycle,
         processLane: "worker",
         observability: opts.observability,
-        observabilityOptions: opts.observabilityOptions,
         dispatcherOptions,
         systemHooks: opts.systemHooks,
         eventDedup: opts.eventDedup,

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

@@ -10,6 +10,19 @@ import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
 // 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.
+//
+// Within the tenant, a newly named id must not be bound to a different record:
+// the file routes authorize through the record a file is bound to, so naming
+// record A's file in record B would hand B's readers A's file (and a later
+// removal from B would not touch it). Pending uploads (no entityId), ids the
+// record already holds in any file field (checked first, even if their row is gone)
+// and moves between its own fields stay allowed. The error is the same as above so the owning record is not revealed.
+function isBoundToOtherRecord(row, entityName, recordId) {
+    const boundId = row["entityId"];
+    if (boundId === null || boundId === undefined)
+        return false;
+    return row["entityType"] !== entityName || boundId !== recordId;
+}
 export function assertFileRefsBelongToTenant(args) {
     const { registry, result, fileRefRows } = args;
     // skip: saves of unregistered aggregates (custom executors) declare no file fields
@@ -22,11 +35,24 @@ export 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 recordId = String(result.id);
+    const alreadyHeld = new Set();
+    for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
+        if (!isFileField(fieldDef))
+            continue;
+        for (const fileRefId of fileRefIdsOf(result.previous[fieldName]))
+            alreadyHeld.add(fileRefId);
+    }
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
         if (!isFileField(fieldDef))
             continue;
         for (const fileRefId of fileRefIdsOf(result.changes[fieldName])) {
-            if (fileRefRows.has(fileRefId))
+            // A value the record already holds is no new binding; its file_refs row may be gone
+            // (forget purged the file), and sending the unchanged field back must still save.
+            if (alreadyHeld.has(fileRefId))
+                continue;
+            const row = fileRefRows.get(fileRefId);
+            if (row !== undefined && !isBoundToOtherRecord(row, result.entityName, recordId))
                 continue;
             throw new ValidationError({
                 fields: [

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

@@ -1,6 +1,6 @@
 import type { TenantDb } from "../db/tenant-db.ts";
 import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.ts";
-import type { FileRefRows } from "./load-save-file-refs.ts";
+import { type FileRefRows } from "./load-save-file-refs.ts";
 export declare function fileRefIdsOf(value: unknown): readonly string[];
 export declare function bindPendingFileRefs(args: {
     readonly registry: Registry;
@@ -9,3 +9,33 @@ export declare function bindPendingFileRefs(args: {
     readonly db: TenantDb;
     readonly fileRefRows: FileRefRows;
 }): Promise<void>;
+export type PendingFileRef = {
+    readonly id: string;
+    readonly storageKey: string;
+    readonly mimeType: string;
+    readonly size: number;
+    readonly version: number;
+};
+type PendingFileRefLookup = {
+    readonly fileRefId: string;
+    readonly entityName: string;
+    readonly fieldName: string;
+    readonly user: SessionUser;
+    readonly db: TenantDb;
+};
+export declare function loadPendingFileRef(lookup: PendingFileRefLookup): Promise<PendingFileRef | undefined>;
+export type BindPendingFileRefOutcome = "bound" | "not-pending" | "version-conflict";
+/**
+ * Binds one of the caller's own pending uploads to a record from a custom handler, with the
+ * same ownership predicate as the save pipeline. Anonymous callers never own an upload.
+ *
+ * The helper checks the upload, not the target: the caller must already be authorized to write
+ * `entityId` itself (for example a record the handler just wrote); `canWriteRecord` is not checked.
+ *
+ * A parallel bind of the same fileRef loses with "version-conflict" (or "not-pending" once the
+ * winner has committed); anything else throws.
+ */
+export declare function bindPendingFileRef(args: PendingFileRefLookup & {
+    readonly entityId: string;
+}): Promise<BindPendingFileRefOutcome>;
+export {};

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

@@ -1,7 +1,9 @@
+import { isAnonymousSessionUser } from "../engine/system-user.js";
 import { isFileField, isUuid, } from "../engine/types/index.js";
 import { reraiseAsKumikoError } from "../errors/index.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";
 export function fileRefIdsOf(value) {
     if (typeof value === "string")
         return isUuid(value) ? [value] : [];
@@ -15,6 +17,16 @@ function isPendingUploadFor(row, entityName, fieldName, user) {
         row["fieldName"] === fieldName &&
         row["insertedById"] === user.id);
 }
+function streamVersionOf(row) {
+    return typeof row["version"] === "number" ? row["version"] : undefined;
+}
+async function bindPendingRow(args) {
+    const { row, fileRefId, entityName, fieldName, entityId, user, db } = args;
+    if (!isPendingUploadFor(row, entityName, fieldName, user))
+        return { kind: "not-pending" };
+    const bound = await getFileRefExecutor().update({ id: fileRefId, version: streamVersionOf(row), changes: { entityId } }, user, db);
+    return bound.isSuccess ? { kind: "bound" } : { kind: "failed", error: bound.error };
+}
 // A form (or a server handler via createFileRefFromBytes) uploads before the
 // record references the file, so its fileRefs carry entityType + fieldName but
 // no entityId. Binding them in the save's own transaction makes record-bound
@@ -35,7 +47,6 @@ export async function bindPendingFileRefs(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;
@@ -43,12 +54,75 @@ export async function bindPendingFileRefs(args) {
         // ones bound earlier; only the ids this save names can be pending uploads.
         for (const fileRefId of fileRefIdsOf(result.changes[fieldName])) {
             const row = fileRefRows.get(fileRefId);
-            if (row === undefined || !isPendingUploadFor(row, entityName, fieldName, user))
+            if (row === undefined)
                 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);
-            if (!bound.isSuccess)
-                throw reraiseAsKumikoError(bound.error);
+            const outcome = await bindPendingRow({
+                row,
+                fileRefId,
+                entityName,
+                fieldName,
+                entityId: String(result.id),
+                user,
+                db,
+            });
+            if (outcome.kind === "failed")
+                throw reraiseAsKumikoError(outcome.error);
         }
     }
 }
+async function loadPendingRow(lookup) {
+    const { fileRefId, entityName, fieldName, user, db } = lookup;
+    // Every anonymous visitor shares one user id, so insertedById cannot tell their uploads apart.
+    if (isAnonymousSessionUser(user))
+        return undefined;
+    if (!isUuid(fileRefId))
+        return undefined;
+    const row = (await loadFileRefRows(db, [fileRefId], user.tenantId)).get(fileRefId);
+    return row !== undefined && isPendingUploadFor(row, entityName, fieldName, user)
+        ? row
+        : undefined;
+}
+// fileName is left out on purpose: it is personal data and may be encrypted; read it through
+// the fileRef executor's detail when it is needed.
+export async function loadPendingFileRef(lookup) {
+    const row = await loadPendingRow(lookup);
+    if (row === undefined)
+        return undefined;
+    const { storageKey, mimeType, size } = row;
+    const version = streamVersionOf(row);
+    if (typeof storageKey !== "string" ||
+        typeof mimeType !== "string" ||
+        typeof size !== "number" ||
+        version === undefined) {
+        return undefined;
+    }
+    return { id: lookup.fileRefId, storageKey, mimeType, size, version };
+}
+const CONCURRENT_BIND_ERROR_CODES = ["version_conflict", "unique_violation"];
+/**
+ * Binds one of the caller's own pending uploads to a record from a custom handler, with the
+ * same ownership predicate as the save pipeline. Anonymous callers never own an upload.
+ *
+ * The helper checks the upload, not the target: the caller must already be authorized to write
+ * `entityId` itself (for example a record the handler just wrote); `canWriteRecord` is not checked.
+ *
+ * A parallel bind of the same fileRef loses with "version-conflict" (or "not-pending" once the
+ * winner has committed); anything else throws.
+ */
+export async function bindPendingFileRef(args) {
+    const row = await loadPendingRow(args);
+    // Without a stream version the update would run unversioned and could overwrite a concurrent bind.
+    if (row === undefined || streamVersionOf(row) === undefined)
+        return "not-pending";
+    const outcome = await bindPendingRow({ ...args, row });
+    switch (outcome.kind) {
+        case "bound":
+            return "bound";
+        case "not-pending":
+            return "not-pending";
+        case "failed":
+            if (CONCURRENT_BIND_ERROR_CODES.includes(outcome.error.code))
+                return "version-conflict";
+            throw reraiseAsKumikoError(outcome.error);
+    }
+}

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

@@ -1,4 +1,5 @@
-import { fetchOne } from "../db/query.js";
+import { fetchOne, runnerCanBeginTransaction } from "../db/query.js";
+import { tenantDbRunner } from "../db/tenant-db-runner.js";
 import { FrameworkReasons, InternalError, UnprocessableError, writeFailure, } from "../errors/index.js";
 import { createFileRefRow, DEFAULT_MAX_UPLOAD_SIZE, storeFileAsFileRef, writeAcceptedFileBytes, } from "./create-file-ref.js";
 import { fileRefsTable } from "./file-ref-table.js";
@@ -22,9 +23,10 @@ export async function createFileRefFromBytes(ctx, input) {
     const outcome = await storeFileAsFileRef({
         user: ctx.user,
         tenantDb: ctx.db,
+        rowInOwnTransaction: runnerCanBeginTransaction(tenantDbRunner(ctx.db)),
         registry: ctx.registry,
         defaultMaxUploadSize: readFilesRouteOptions(ctx.registry).maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
-        writeBytes: (key, data, mimeType) => files.ref(key).write(data, mimeType),
+        writeBytes: (key, data, mimeType) => files.writeUploadBytes(key, data, mimeType),
         deleteBytes: (key) => files.ref(key).delete(),
     }, {
         fileName: input.fileName,
@@ -48,7 +50,8 @@ function fileRejectedFailure(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.
+// A crash between this phase and the commit leaves the bytes in storage; the upload ledger sweep
+// removes them after its grace period.
 export async function uploadFileBytesBeforeTransaction(ctx, input) {
     const { files } = ctx;
     if (!files) {
@@ -60,7 +63,7 @@ export async function uploadFileBytesBeforeTransaction(ctx, input) {
         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),
+        writeBytes: (key, data, mimeType) => files.writeUploadBytes(key, data, mimeType),
     }, {
         fileName: input.fileName,
         declaredMimeType: input.mimeType,
@@ -80,8 +83,11 @@ export async function uploadFileBytesBeforeTransaction(ctx, input) {
             const committedRow = await fetchOne(ctx.db, fileRefsTable, {
                 storageKey: uploaded.storageKey,
             });
-            if (!committedRow)
-                await files.ref(uploaded.storageKey).delete();
+            // skip: a committed row owns the bytes, the commit already took the ledger entry
+            if (committedRow)
+                return;
+            await files.ref(uploaded.storageKey).delete();
+            await files.forgetUploadBytes(uploaded.storageKey);
         },
     };
 }

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

@@ -1,8 +1,26 @@
 import { type TenantDb } from "../db/tenant-db.ts";
 import { type AnyFileFieldDef, type Registry, type SessionUser } from "../engine/types/index.ts";
-import type { WriteFailure } from "../errors/index.ts";
+import { type WriteFailure } from "../errors/index.ts";
 export declare const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
-declare function buildFileRefExecutor(): import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor;
+declare function buildFileRefExecutor(): 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 entityId: string | null;
+    readonly entityType: string | null;
+    readonly fieldName: string | null;
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly size: unknown;
+    readonly storageKey: string;
+}>;
 export declare function getFileRefExecutor(): ReturnType<typeof buildFileRefExecutor>;
 type AttachedFieldResolution = {
     readonly kind: "unattached";

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

@@ -1,11 +1,13 @@
 import { createEventStoreExecutor } from "../db/event-store-executor.js";
 import { runInOwnTransaction } from "../db/tenant-db.js";
 import { isFileField, } from "../engine/types/index.js";
+import { InternalError } from "../errors/index.js";
 import { generateId } from "../utils/index.js";
 import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
 import { resolveContentType } from "./resolve-content-type.js";
 import { buildStorageKey, resolveUploadMimeType, validateFile, validateFileContent, } from "./types.js";
+import { takeUploadLedgerEntry } from "./upload-ledger.js";
 export const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
 // Standard entity executor for fileRef: create/delete emit fileRef.created /
 // fileRef.deleted and write file_refs via applyEntityEvent in one tx
@@ -132,6 +134,13 @@ export async function createFileRefRow(deps, uploaded) {
     }, deps.user, deps.tenantDb);
     if (!result.isSuccess)
         return { failure: result };
+    // Throws instead of returning a failure: a returned failure would still commit in the
+    // own-transaction path, leaving a fileRef row whose bytes the sweep already deleted.
+    if (!(await takeUploadLedgerEntry(deps.tenantDb, uploaded.storageKey))) {
+        throw new InternalError({
+            message: "upload expired: the bytes were swept before the fileRef row was created, upload again",
+        });
+    }
     return {
         fileRef: {
             id: fileRefId,
@@ -148,7 +157,7 @@ export async function storeFileAsFileRef(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).
+    // crash cannot, so the upload ledger sweep removes those bytes after its grace period.
     // 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 () => {

package/dist/files/feature.d.ts

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

package/dist/files/feature.js

@@ -1,6 +1,8 @@
 import { defineFeature } from "../engine/index.js";
 import { bindReferencedFilesWrite } from "./bind-referenced-files.write.js";
 import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
+import { DEFAULT_UPLOAD_SWEEP_GRACE_HOURS, MIN_UPLOAD_SWEEP_GRACE_HOURS, sweepOrphanedUploads, } from "./sweep-orphaned-uploads.js";
+import { fileUploadLedgerTable } from "./upload-ledger.js";
 export { fileRefEntity } from "./file-ref-entity.js";
 // files — `fileRef` als ganz normales ES-Entity. Upload/Delete laufen über
 // den Standard-Entity-Executor (file-routes.ts: executor.create/delete →
@@ -14,7 +16,14 @@ export { fileRefEntity } from "./file-ref-entity.js";
 // Entity-Projektion (für rebuildProjection). Liegt im Framework neben
 // file-routes + fileRefsTable; bundled-features/files re-exportiert nur.
 export const FILES_FEATURE = "files";
+function assertValidSweepGraceHours(hours) {
+    if (!Number.isInteger(hours) || hours < MIN_UPLOAD_SWEEP_GRACE_HOURS) {
+        throw new Error(`createFilesFeature: uploadSweepGraceHours must be a whole number of hours >= ${MIN_UPLOAD_SWEEP_GRACE_HOURS}, got ${String(hours)}`);
+    }
+}
 export function createFilesFeature(options = {}) {
+    const uploadSweepGraceHours = options.uploadSweepGraceHours ?? DEFAULT_UPLOAD_SWEEP_GRACE_HOURS;
+    assertValidSweepGraceHours(uploadSweepGraceHours);
     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({
@@ -24,6 +33,22 @@ export function createFilesFeature(options = {}) {
         });
         r.entity({ name: FILE_REF_ENTITY_NAME, ...fileRefEntity });
         r.writeHandler(bindReferencedFilesWrite);
+        r.storeTable(fileUploadLedgerTable, { reason: "coordination.file_upload_ledger" });
+        r.job({
+            name: "sweep-orphaned-uploads",
+            trigger: { cron: "0 * * * *" },
+            perTenant: true,
+            concurrency: "skip",
+            handler: async (_payload, ctx) => {
+                await sweepOrphanedUploads({
+                    db: ctx.db,
+                    files: ctx.files,
+                    now: ctx.tz.now(),
+                    graceHours: uploadSweepGraceHours,
+                    log: ctx.log,
+                });
+            },
+        });
         return { routeOptions: options };
     });
 }

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

@@ -1,7 +1,10 @@
 import type { FileContext, FileHandle } from "@cosmicdrift/kumiko-types/file-handle-types";
+import type { FileProviderResolver, FileUploadLedger } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
+import type { TenantId } from "../engine/types/identifiers.ts";
 import { type FileStorageProvider } from "./types.ts";
 export type { FileContext, FileHandle };
 export declare function createFileHandle(key: string, getProvider: () => Promise<FileStorageProvider>): FileHandle;
-export declare function createFileContext(resolve: () => Promise<FileStorageProvider>, tenantId?: string): FileContext;
+export declare function createFileContext(resolve: () => Promise<FileStorageProvider>, tenantId?: string, uploadLedger?: FileUploadLedger): FileContext;
+export declare function createTenantFileContext(resolver: FileProviderResolver, tenantId: TenantId): FileContext;
 export declare function deriveKey(key: string, suffix: string): string;
 export declare function storageKeyStemPrefix(key: string): string;

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 { InternalError } from "../errors/index.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
@@ -42,19 +43,39 @@ export function createFileHandle(key, getProvider) {
 // With `tenantId`, `ref` and `list` only accept keys/prefixes inside `${tenantId}/` —
 // the key space is the isolation boundary in a store shared by several tenants, and
 // a request-derived key or prefix (or "") would otherwise reach every tenant's keys.
-export function createFileContext(resolve, tenantId) {
+export function createFileContext(resolve, tenantId, uploadLedger) {
     let cached;
     const getProvider = () => {
         cached ??= resolve();
         return cached;
     };
+    const requireUploadLedger = () => {
+        if (uploadLedger === undefined) {
+            throw new InternalError({
+                message: "FileContext: no upload ledger is wired, so upload bytes would be unrecoverable after a crash. Build the context from a resolver made by withFileProviderResolver (or withUploadLedger)",
+            });
+        }
+        return uploadLedger;
+    };
+    const assertOwnKey = (method, key) => {
+        if (tenantId !== undefined && !key.startsWith(`${tenantId}/`)) {
+            throw new Error(`FileContext.${method}: key must start with "${tenantId}/"`);
+        }
+    };
     return {
         ref: (key) => {
-            if (tenantId !== undefined && !key.startsWith(`${tenantId}/`)) {
-                throw new Error(`FileContext.ref: key must start with "${tenantId}/"`);
-            }
+            assertOwnKey("ref", key);
             return createFileHandle(key, getProvider);
         },
+        writeUploadBytes: async (key, data, mimeType) => {
+            assertOwnKey("writeUploadBytes", key);
+            await requireUploadLedger().record(key);
+            await (await getProvider()).write(key, data, mimeType);
+        },
+        forgetUploadBytes: async (key) => {
+            assertOwnKey("forgetUploadBytes", key);
+            await requireUploadLedger().forget(key);
+        },
         /** 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. */
@@ -74,6 +95,11 @@ export function createFileContext(resolve, tenantId) {
         },
     };
 }
+// The one way to build a tenant's FileContext from a resolver: carries the resolver's upload
+// ledger, so every context agrees on where upload bytes are tracked.
+export function createTenantFileContext(resolver, tenantId) {
+    return createFileContext(() => resolver(tenantId), tenantId, resolver.uploadLedgerFor?.(tenantId));
+}
 // Splits a key into the part before the last dot of its last path segment
 // (the "stem") and the extension including the dot. No dot in the last
 // segment: the whole key is the stem, extension is empty.

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

@@ -1,6 +1,6 @@
 export { FILE_REF_ENTITY_NAME } from "./types.ts";
 export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
-    storageKey: {
+    readonly storageKey: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -23,7 +23,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    fileName: {
+    readonly fileName: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -46,7 +46,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    mimeType: {
+    readonly mimeType: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -69,7 +69,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    size: {
+    readonly size: {
         readonly type: "bigInt";
         readonly description?: string;
         readonly required?: boolean;
@@ -81,7 +81,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    entityType: {
+    readonly entityType: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -104,7 +104,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    entityId: {
+    readonly entityId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -127,7 +127,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    fieldName: {
+    readonly fieldName: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;

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

@@ -1,5 +1,5 @@
 export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable<import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
-    storageKey: {
+    readonly storageKey: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -22,7 +22,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    fileName: {
+    readonly fileName: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -45,7 +45,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    mimeType: {
+    readonly mimeType: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -68,7 +68,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    size: {
+    readonly size: {
         readonly type: "bigInt";
         readonly description?: string;
         readonly required?: boolean;
@@ -80,7 +80,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    entityType: {
+    readonly entityType: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -103,7 +103,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    entityId: {
+    readonly entityId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -126,7 +126,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    fieldName: {
+    readonly fieldName: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;