@cosmicdrift/kumiko-framework 0.371.1 → 0.372.0

package/dist/engine/entity-handlers.d.ts

@@ -1,6 +1,6 @@
 import * as z from "zod";
 import { type EventStoreExecutor } from "../db/event-store-executor.ts";
-import { type EntityTable } from "../db/table-builder.ts";
+import { type EntityRow, type EntityTable } from "../db/table-builder.ts";
 import type { EntityCrudRegistrar, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions } from "./types/entity-handlers.ts";
 import type { AccessRule, EntityDefinition, EscapeHatchDeclaration, QueryHandlerDef, WriteHandlerDef } from "./types/index.ts";
 export type { EntityCrudHandlerDefaults, EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "./types/entity-handlers.ts";
@@ -53,9 +53,9 @@ export declare function defineEntityDeleteHandler(entityName: string, entity: En
 export declare function defineEntityRestoreHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): WriteHandlerDef;
 export declare function defineEntityListHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
 export declare function defineEntityDetailHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
-export declare function createEntityExecutor(entityName: string, entity: EntityDefinition): {
+export declare function createEntityExecutor<E extends EntityDefinition>(entityName: string, entity: E): {
     readonly table: EntityTable;
-    readonly executor: EventStoreExecutor;
+    readonly executor: EventStoreExecutor<EntityRow<E>>;
 };
 export declare function defineProjectionQueryHandler(name: string, projectionQualifiedName: string, options: {
     access: AccessRule;

package/dist/engine/factories.d.ts

@@ -32,6 +32,7 @@ export declare function createBooleanField<R extends true | false = false>(overr
     required?: R;
 }): BooleanFieldDef & {
     required: R;
+    default: boolean;
 };
 export declare function createSelectField<const TOptions extends readonly string[], R extends true | false = false>(opts: {
     options: TOptions;
@@ -171,7 +172,7 @@ export declare function createFileField(overrides?: Partial<Omit<FileFieldDef, "
 export declare function createImageField(overrides?: Partial<Omit<ImageFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): ImageFieldDef;
 export declare function createFilesField(overrides?: Partial<Omit<FilesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FilesFieldDef;
 export declare function createImagesField(overrides?: Partial<Omit<ImagesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): ImagesFieldDef;
-export declare function createEntity<F, const T extends EntityTenancy = "tenant">(def: {
+export declare function createEntity<const F, const T extends EntityTenancy = "tenant">(def: {
     readonly table?: string;
     readonly fields: F;
     readonly description?: string;

package/dist/engine/factories.js

@@ -378,6 +378,8 @@ export function createImagesField(overrides) {
 // Issue um Constraint-Inferenz auf strukturellen Records. Stattdessen
 // validieren wir die Conformance via conditional return type: wenn F
 // nicht FieldsMap-compat ist, kollabiert der Return zu `never`.
+// `const F`: inline field literals (`{ type: "reference", ... }`) keep their
+// `type` literal without `as const`; otherwise it widens to string → `never`.
 export function createEntity(def) {
     return {
         softDelete: false,

package/dist/engine/membership-roles.d.ts

@@ -2,4 +2,5 @@ export declare const FORBIDDEN_MEMBERSHIP_ROLES: ReadonlySet<string>;
 export declare function isForbiddenMembershipRole(role: string): boolean;
 export declare function findForbiddenMembershipRole(roles: readonly string[]): string | undefined;
 export declare function stripForbiddenMembershipRoles(roles: readonly string[]): readonly string[];
+export declare function stripReservedTokenRoles(roles: readonly string[]): readonly string[];
 export declare function buildSessionRoles(globalRoles: readonly string[], membershipRoles: readonly string[]): readonly string[];

package/dist/engine/membership-roles.js

@@ -38,6 +38,14 @@ const NON_MINTABLE_GLOBAL_ROLES = new Set([
 function stripNonMintableGlobalRoles(roles) {
     return roles.filter((role) => !NON_MINTABLE_GLOBAL_ROLES.has(role));
 }
+// Applied on JWT verify: a token signed with the right key (leaked or foreign)
+// must not carry the in-process System identity or the "all" pseudo-role.
+// "anonymous" stays: it only narrows access (openToAll excludes it), and
+// stripping it would turn the token into an authenticated user with no roles.
+const RESERVED_TOKEN_ROLES = new Set([...access.all, SYSTEM_ROLE]);
+export function stripReservedTokenRoles(roles) {
+    return roles.filter((role) => !RESERVED_TOKEN_ROLES.has(role));
+}
 // Single mint path for session roles: merges globalRoles with the stripped
 // membership portion and dedupes. Every place that builds a session's roles
 // from a membership should go through this instead of repeating

package/dist/engine/strip-disabled-features-from-app-schema.js

@@ -1,11 +1,17 @@
 // Tenant-level counterpart to projectAppSchemaForRoles: removes the UI surface
 // (screens, navs, content collections, workspaces) of features the tenant has
 // switched off via r.toggleable(). Entities and translations stay — enabled
-// features may still reference them. Run BEFORE the role projection: it keeps
+// features may still reference them. Screens that declare a `fallback` (plus
+// the same-feature screens those fallbacks name) are the exception: their
+// visibleWhen probe is rejected by the feature gate for this tenant, which is
+// what makes the renderer show the fallback (e.g. an upgrade notice). Dropping
+// them would also drop every nav of another feature pointing at them, so the
+// fallback could never be reached. Run BEFORE the role projection: it keeps
 // only targets that exist in the schema, so once the disabled screens/navs are
 // gone it also drops every action, redirect, nav and workspace member that
 // pointed at them. The one reference it does not resolve is a nav `parent`
 // pointing at a missing nav; that is pruned here.
+import { resolveScreenTargetQn } from "./boot-validator/screens.js";
 import { isToggleableFeature } from "./effective-features.js";
 import { isValidQn, qualifyEntityName } from "./qualified-name.js";
 // Sorted, so the result doubles as a stable cache key. The trial gate is
@@ -50,6 +56,28 @@ function collectOrphanedNavQns(features, removedNavQns) {
     }
     return orphaned;
 }
+// Fail-closed for the kept screens: the server gate rejects their handlers and
+// queries for the tenant, only the schema entry stays so the fallback can render.
+function screensKeptForFallback(feature) {
+    const qnOf = (screenId) => qualifyEntityName(feature.featureName, "screen", screenId);
+    const byQn = new Map(feature.screens.map((screen) => [qnOf(screen.id), screen]));
+    const kept = new Set();
+    const pending = feature.screens.filter((screen) => screen.fallback !== undefined);
+    for (const screen of pending)
+        kept.add(qnOf(screen.id));
+    while (pending.length > 0) {
+        const fallback = pending.pop()?.fallback;
+        if (fallback === undefined)
+            continue;
+        const targetQn = resolveScreenTargetQn(feature.featureName, fallback);
+        const target = byQn.get(targetQn);
+        if (target === undefined || kept.has(targetQn))
+            continue;
+        kept.add(targetQn);
+        pending.push(target);
+    }
+    return feature.screens.filter((screen) => kept.has(qnOf(screen.id)));
+}
 export function stripDisabledFeaturesFromAppSchema(schema, registry, disabledFeatureNames) {
     if (disabledFeatureNames.length === 0)
         return schema;
@@ -66,7 +94,7 @@ export function stripDisabledFeaturesFromAppSchema(schema, registry, disabledFea
     const features = schema.features.map((feature) => {
         if (disabled.has(feature.featureName)) {
             const { navs: _navs, contentCollections: _collections, workspaces: _ws, ...rest } = feature;
-            return { ...rest, screens: [] };
+            return { ...rest, screens: screensKeptForFallback(feature) };
         }
         if (orphanedNavQns.size === 0 || feature.navs === undefined)
             return feature;

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/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;

package/dist/files/file-routes.js

@@ -16,6 +16,7 @@ import { fileRefsTable } from "./file-ref-table.js";
 import { RecordWriteDecisions } from "./record-write-check.js";
 import { neutralFileNameForMimeType } from "./resolve-content-type.js";
 import { parseMaxSize, resolveServedContentType } from "./types.js";
+import { createFileUploadLedger } from "./upload-ledger.js";
 const DEFAULT_PRIVILEGED_ROLES = ["Admin", "SystemAdmin"];
 // 15 minutes — long enough for a download to start, short enough that a
 // leaked URL (e.g. from a browser history screenshot) isn't a long-lived
@@ -171,13 +172,17 @@ export function createFileRoutes(options) {
         }
         const data = new Uint8Array(await file.arrayBuffer());
         const storageProvider = await options.resolveProvider(user.tenantId);
+        const uploadLedger = createFileUploadLedger(db, user.tenantId);
         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),
+            writeBytes: async (key, bytes, mimeType) => {
+                await uploadLedger.record(key);
+                await storageProvider.write(key, bytes, mimeType);
+            },
             deleteBytes: (key) => storageProvider.delete(key),
         }, { fileName: file.name, declaredMimeType: file.type, data, entityType, entityId, fieldName });
         if (outcome.kind === "rejected")

package/dist/files/index.d.ts

@@ -2,7 +2,7 @@ export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, Uploaded
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.ts";
 export { createFilesFeature, FILES_FEATURE } from "./feature.ts";
 export type { FileContext, FileHandle } from "./file-handle.ts";
-export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle.ts";
+export { createFileContext, createTenantFileContext, deriveKey, storageKeyStemPrefix, } from "./file-handle.ts";
 export { fileRefEntity } from "./file-ref-entity.ts";
 export { fileRefsTable } from "./file-ref-table.ts";
 export type { FileAccessDecision, FileAccessGuard, FileRef, FileRoutesOptions, } from "./file-routes.ts";
@@ -14,7 +14,9 @@ export type { FileProviderContext, FileProviderPlugin, FileProviderResolver, Fil
 export { createFileProviderForTenant, isFileProviderPlugin, makeFileProviderResolver, } from "./provider-resolver.ts";
 export { resolveContentType } from "./resolve-content-type.ts";
 export { fileRefStorageDelta, filesStorageTrackingFeature, tenantStorageUsageTable, transferTenantStorageUsage, } from "./storage-tracking.ts";
+export { DEFAULT_UPLOAD_SWEEP_GRACE_HOURS, MIN_UPLOAD_SWEEP_GRACE_HOURS, sweepOrphanedUploads, } from "./sweep-orphaned-uploads.ts";
 export type { FileContentValidationResult, FileMetadata, FileStorageProvider, FileValidationOptions, SignedUrlOptions, UploadMimeTypeResolution, WriteStreamOptions, } from "./types.ts";
 export { assertSafeStorageKey, buildStorageKey, normalizeMimeType, parseMaxSize, resolveUploadMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, validateFileContent, } from "./types.ts";
+export { createFileUploadLedger, fileUploadLedgerTable, withUploadLedger, } from "./upload-ledger.ts";
 export type { ZipEntry } from "./zip-stream.ts";
 export { createZipStream } from "./zip-stream.ts";

package/dist/files/index.js

@@ -2,7 +2,7 @@ export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytes
 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";
+export { createFileContext, createTenantFileContext, deriveKey, storageKeyStemPrefix, } from "./file-handle.js";
 export { fileRefEntity } from "./file-ref-entity.js";
 export { fileRefsTable } from "./file-ref-table.js";
 export { createFileRoutes, readFilesRouteOptions, resolveMaxUploadBodyBytes, } from "./file-routes.js";
@@ -11,5 +11,7 @@ export { createLocalProvider } from "./local-provider.js";
 export { createFileProviderForTenant, isFileProviderPlugin, makeFileProviderResolver, } from "./provider-resolver.js";
 export { resolveContentType } from "./resolve-content-type.js";
 export { fileRefStorageDelta, filesStorageTrackingFeature, tenantStorageUsageTable, transferTenantStorageUsage, } from "./storage-tracking.js";
+export { DEFAULT_UPLOAD_SWEEP_GRACE_HOURS, MIN_UPLOAD_SWEEP_GRACE_HOURS, sweepOrphanedUploads, } from "./sweep-orphaned-uploads.js";
 export { assertSafeStorageKey, buildStorageKey, normalizeMimeType, parseMaxSize, resolveUploadMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, validateFileContent, } from "./types.js";
+export { createFileUploadLedger, fileUploadLedgerTable, withUploadLedger, } from "./upload-ledger.js";
 export { createZipStream } from "./zip-stream.js";