@cosmicdrift/kumiko-framework 0.371.1 → 0.373.0

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

@@ -1,8 +1,10 @@
+export type { BindPendingFileRefOutcome, PendingFileRef } from "./bind-pending-file-refs.ts";
+export { bindPendingFileRef, loadPendingFileRef } from "./bind-pending-file-refs.ts";
 export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, UploadedFileBytes, UploadFileBytesContext, } from "./create-file-ref-from-bytes.ts";
 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 +16,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

@@ -1,8 +1,9 @@
+export { bindPendingFileRef, loadPendingFileRef } from "./bind-pending-file-refs.js";
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.js";
 export { createFilesFeature, FILES_FEATURE } from "./feature.js";
 // `createFileHandle` is an implementation detail — construct handles via
 // `createFileContext(provider).ref(key)`, which is the AppContext surface.
-export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle.js";
+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 +12,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";

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

@@ -33,12 +33,14 @@ export async function loadFileRefRows(db, ids, tenantId) {
     // skip: nothing referenced, nothing to load
     if (ids.length === 0)
         return new Map();
+    // Versions before rows: a bind committing in between leaves a stale row paired with an older
+    // version, so the binding update conflicts instead of overwriting the winner's entityId.
+    const streamVersions = await getStreamVersions(tenantDbRunner(db), [...ids], db.tenantId);
     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);

package/dist/files/provider-resolver.js

@@ -15,6 +15,7 @@ import { EXT_FILE_PROVIDER, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT
 import { SYSTEM_USER_ID } from "../engine/system-user.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
 import { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage } from "../redis/cache-sync-topics.js";
+import { withUploadLedger } from "./upload-ledger.js";
 const FEATURE_NAME = "file-foundation";
 // extension-usage `options` is engine-payload (unknown) — structurally validate
 // instead of casting blind.
@@ -95,7 +96,7 @@ export function makeFileProviderResolver(deps) {
             cache.delete(message.tenantId);
     });
     deps.cacheSync?.onResync(() => cache.clear());
-    return (tenantId) => {
+    const resolveProvider = (tenantId) => {
         const cached = cache.get(tenantId);
         if (cached)
             return cached;
@@ -118,4 +119,5 @@ export function makeFileProviderResolver(deps) {
         cache.set(tenantId, built);
         return built;
     };
+    return deps.db ? withUploadLedger(resolveProvider, deps.db) : resolveProvider;
 }

package/dist/files/sweep-orphaned-uploads.d.ts

@@ -0,0 +1,16 @@
+import type { FileContext } from "@cosmicdrift/kumiko-types/file-handle-types";
+import type { Logger } from "@cosmicdrift/kumiko-types/logger";
+import { type TenantDb } from "../db/tenant-db.ts";
+export declare const ORPHANED_UPLOAD_SWEEP_BATCH = 500;
+export declare const DEFAULT_UPLOAD_SWEEP_GRACE_HOURS = 24;
+export declare const MIN_UPLOAD_SWEEP_GRACE_HOURS = 1;
+type SweepLog = Pick<Logger, "warn"> | undefined;
+export declare function sweepOrphanedUploads(args: {
+    readonly db: TenantDb;
+    readonly files: FileContext | undefined;
+    readonly now: Temporal.Instant;
+    readonly graceHours: number;
+    readonly log: SweepLog;
+    readonly pageSize?: number;
+}): Promise<void>;
+export {};

package/dist/files/sweep-orphaned-uploads.js

@@ -0,0 +1,53 @@
+import { selectMany } from "../db/query.js";
+import { runInOwnTransaction } from "../db/tenant-db.js";
+import { deleteFileRefBytes } from "../derivatives/delete-stored-file.js";
+import { fileRefsTable } from "./file-ref-table.js";
+import { fileUploadLedgerTable, takeUploadLedgerEntry } from "./upload-ledger.js";
+export const ORPHANED_UPLOAD_SWEEP_BATCH = 500;
+export const DEFAULT_UPLOAD_SWEEP_GRACE_HOURS = 24;
+export const MIN_UPLOAD_SWEEP_GRACE_HOURS = 1;
+// Each candidate gets its own short transaction that takes the ledger row first. A commit that
+// holds the row makes the sweep wait and then find it gone; a sweep that took the row first makes
+// the commit find it gone and fail, so bytes and fileRef row can never end up apart.
+async function sweepOrphanedUpload(txDb, files, storageKey) {
+    const taken = await takeUploadLedgerEntry(txDb, storageKey);
+    // skip: a commit took the row in the meantime and owns the bytes now
+    if (!taken)
+        return;
+    const committedRows = await selectMany(txDb, fileRefsTable, { storageKey }, { limit: 1, fields: ["id"] });
+    // skip: a fileRef row claims the bytes, only the stale ledger row goes
+    if (committedRows.length > 0)
+        return;
+    const failedKeys = await deleteFileRefBytes(files, { storageKey }, "upload-ledger-sweep");
+    if (failedKeys.length > 0)
+        throw new Error("bytes not fully deleted");
+}
+// Deletes the bytes (original and derivatives) of uploads that never got a fileRef row within the
+// grace period. Walks the ledger page by page along storage_key, so rows that keep failing or are
+// locked cannot hide the rows behind them; a failed row rolls back and the next run retries it.
+export async function sweepOrphanedUploads(args) {
+    const { db, files, now, graceHours, log } = args;
+    const pageSize = args.pageSize ?? ORPHANED_UPLOAD_SWEEP_BATCH;
+    if (!files) {
+        log?.warn("[upload-ledger-sweep] no file storage available, orphaned uploads kept");
+        return;
+    }
+    const cutoff = now.subtract({ hours: graceHours });
+    let cursor;
+    for (;;) {
+        const rows = await selectMany(db, fileUploadLedgerTable, { createdAt: { lt: cutoff }, ...(cursor !== undefined && { storageKey: { gt: cursor } }) }, { orderBy: { col: "storageKey", direction: "asc" }, fields: ["storageKey"], limit: pageSize });
+        const lastRow = rows[rows.length - 1];
+        // skip: an empty page means every due row has been visited
+        if (lastRow === undefined)
+            return;
+        cursor = lastRow.storageKey;
+        for (const { storageKey } of rows) {
+            try {
+                await runInOwnTransaction(db, (txDb) => sweepOrphanedUpload(txDb, files, storageKey));
+            }
+            catch (err) {
+                log?.warn(`[upload-ledger-sweep] orphaned upload not deleted, retried next run: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+}

package/dist/files/upload-ledger.d.ts

@@ -0,0 +1,10 @@
+import type { FileProviderResolver, FileUploadLedger } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
+import type { FileStorageProvider } from "@cosmicdrift/kumiko-types/file-storage-provider-types";
+import type { TenantId } from "@cosmicdrift/kumiko-types/identifiers";
+import type { DbConnection } from "../db/connection.ts";
+import { type EntityTableMeta } from "../db/entity-table-meta.ts";
+import { type TenantDb } from "../db/tenant-db.ts";
+export declare const fileUploadLedgerTable: EntityTableMeta;
+export declare function createFileUploadLedger(db: DbConnection | TenantDb, tenantId: TenantId): FileUploadLedger;
+export declare function withUploadLedger(resolver: (tenantId: TenantId) => Promise<FileStorageProvider>, db: DbConnection | TenantDb): FileProviderResolver;
+export declare function takeUploadLedgerEntry(txDb: TenantDb, storageKey: string): Promise<boolean>;

package/dist/files/upload-ledger.js

@@ -0,0 +1,47 @@
+import { defineUnmanagedTable } from "../db/entity-table-meta.js";
+import { createTenantDb } from "../db/tenant-db.js";
+import { tenantDbRunner } from "../db/tenant-db-runner.js";
+const CREATED_AT_INDEX = "store_file_upload_ledger_created_at_idx";
+// One row per upload whose bytes are in storage but whose fileRef row is not committed yet. The
+// commit path deletes it inside the transaction that creates the fileRef; the sweep finds the
+// rows that never got there. Unmanaged: a coordination aid, not state with an event history.
+export const fileUploadLedgerTable = defineUnmanagedTable({
+    tableName: "store_file_upload_ledger",
+    indexes: [{ name: CREATED_AT_INDEX, columns: ["created_at"] }],
+    columns: [
+        { name: "storage_key", pgType: "text", notNull: true, primaryKey: true },
+        { name: "tenant_id", pgType: "uuid", notNull: true },
+        { name: "created_at", pgType: "timestamptz", notNull: true },
+    ],
+});
+function isTenantDb(db) {
+    return "tenantId" in db && "fetchOne" in db && typeof db.fetchOne === "function";
+}
+// The ledger writes on a connection of its own, never on a handler transaction: a rollback of the
+// handler must not take the row with it, or the bytes it uploaded would be unfindable.
+export function createFileUploadLedger(db, tenantId) {
+    const runner = isTenantDb(db) ? tenantDbRunner(db) : db;
+    const ledgerDb = createTenantDb({ db: runner, tenantId });
+    return {
+        record: async (storageKey) => {
+            await ledgerDb.insertOne(fileUploadLedgerTable, {
+                storageKey,
+                tenantId,
+                createdAt: Temporal.Now.instant(),
+            });
+        },
+        forget: async (storageKey) => {
+            await ledgerDb.deleteMany(fileUploadLedgerTable, { storageKey });
+        },
+    };
+}
+export function withUploadLedger(resolver, db) {
+    return Object.assign(resolver, {
+        uploadLedgerFor: (tenantId) => createFileUploadLedger(db, tenantId),
+    });
+}
+// Runs inside the transaction that creates the fileRef row. False means no ledger row was left to
+// take: the sweep already removed the bytes, so the row must not be committed.
+export async function takeUploadLedgerEntry(txDb, storageKey) {
+    return (await txDb.deleteMany(fileUploadLedgerTable, { storageKey })) > 0;
+}

package/dist/i18n/index.d.ts

@@ -1,6 +1,6 @@
 import type { Registry } from "../engine/types/index.ts";
 export { hasMailTranslationKey, hasMailTranslations, listMailLocales, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.ts";
-export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, resolveHeaderLocale, } from "./request-locale.ts";
+export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, rankAcceptLanguage, rankPreferredLocales, resolveHeaderLocale, } from "./request-locale.ts";
 export { SETTINGS_HUB_I18N } from "./settings-hub-keys.ts";
 export type I18nOptions = {
     defaultLocale: string;

package/dist/i18n/index.js

@@ -1,6 +1,6 @@
 import { resolveTranslationValue } from "../ui-types/plural.js";
 export { hasMailTranslationKey, hasMailTranslations, listMailLocales, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.js";
-export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, resolveHeaderLocale, } from "./request-locale.js";
+export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, rankAcceptLanguage, rankPreferredLocales, resolveHeaderLocale, } from "./request-locale.js";
 export { SETTINGS_HUB_I18N } from "./settings-hub-keys.js";
 export function createI18n(registry, options) {
     const translations = registry.getAllTranslations();

package/dist/i18n/request-locale.d.ts

@@ -5,12 +5,23 @@ export declare function isValidLocaleTag(value: string): boolean;
  *  hit registered keys regardless of header casing. */
 export declare function canonicalizeLocaleTag(tag: string): string;
 /**
- * Picks the best well-formed tag from an Accept-Language header (RFC 9110
- * §12.5.4): parses "tag;q=x" pairs, sorts by q descending (header order
- * breaks ties), and returns the first tag that passes isValidLocaleTag.
- * Tags with q=0 (explicitly excluded) are dropped entirely.
+ * Well-formed tags of an Accept-Language header (RFC 9110 §12.5.4) in
+ * preference order: "tag;q=x" pairs sorted by q descending, header order
+ * breaking ties. Tags with q=0 (explicitly excluded) and malformed tags are
+ * dropped. Tags are returned as sent, not canonicalized or deduped.
  */
+export declare function rankAcceptLanguage(header: string | undefined): string[];
+/** Picks the best well-formed tag from an Accept-Language header, see rankAcceptLanguage. */
 export declare function pickAcceptLanguage(header: string | undefined): string | undefined;
+/**
+ * Ordered locale preference of a page request: a valid `?lang=` first, then
+ * every Accept-Language tag by q. Canonicalized and deduped (case-insensitive),
+ * so a resolver can walk the list and take the first locale it has content for.
+ */
+export declare function rankPreferredLocales(options: {
+    readonly queryLang?: string | null | undefined;
+    readonly acceptLanguage?: string | null | undefined;
+}): string[];
 /**
  * Request-layer resolution: an explicit, validated X-Locale header wins;
  * otherwise the best Accept-Language tag; otherwise undefined — no signal

package/dist/i18n/request-locale.js

@@ -33,15 +33,15 @@ export function canonicalizeLocaleTag(tag) {
         .join("-");
 }
 /**
- * Picks the best well-formed tag from an Accept-Language header (RFC 9110
- * §12.5.4): parses "tag;q=x" pairs, sorts by q descending (header order
- * breaks ties), and returns the first tag that passes isValidLocaleTag.
- * Tags with q=0 (explicitly excluded) are dropped entirely.
+ * Well-formed tags of an Accept-Language header (RFC 9110 §12.5.4) in
+ * preference order: "tag;q=x" pairs sorted by q descending, header order
+ * breaking ties. Tags with q=0 (explicitly excluded) and malformed tags are
+ * dropped. Tags are returned as sent, not canonicalized or deduped.
  */
-export function pickAcceptLanguage(header) {
+export function rankAcceptLanguage(header) {
     if (header === undefined || header.length === 0)
-        return undefined;
-    const candidates = header
+        return [];
+    return header
         .split(",")
         .map((part, index) => {
         const [tagRaw, ...params] = part.trim().split(";");
@@ -54,8 +54,25 @@ export function pickAcceptLanguage(header) {
         return { tag, q, index };
     })
         .filter((c) => c !== undefined && c.q > 0)
-        .sort((a, b) => b.q - a.q || a.index - b.index);
-    return candidates[0]?.tag;
+        .sort((a, b) => b.q - a.q || a.index - b.index)
+        .map((c) => c.tag);
+}
+/** Picks the best well-formed tag from an Accept-Language header, see rankAcceptLanguage. */
+export function pickAcceptLanguage(header) {
+    return rankAcceptLanguage(header)[0];
+}
+/**
+ * Ordered locale preference of a page request: a valid `?lang=` first, then
+ * every Accept-Language tag by q. Canonicalized and deduped (case-insensitive),
+ * so a resolver can walk the list and take the first locale it has content for.
+ */
+export function rankPreferredLocales(options) {
+    const ranked = [];
+    if (options.queryLang != null && isValidLocaleTag(options.queryLang)) {
+        ranked.push(options.queryLang);
+    }
+    ranked.push(...rankAcceptLanguage(options.acceptLanguage ?? undefined));
+    return [...new Set(ranked.map(canonicalizeLocaleTag))];
 }
 /**
  * Request-layer resolution: an explicit, validated X-Locale header wins;

package/dist/jobs/job-runner.js

@@ -12,7 +12,7 @@ import { createSystemUser } from "../engine/system-user.js";
 import { SYSTEM_TENANT_ID, } from "../engine/types/index.js";
 import { InternalError } from "../errors/index.js";
 import { isKumikoError } from "../errors/kumiko-error.js";
-import { createFileContext } from "../files/file-handle.js";
+import { createTenantFileContext } from "../files/file-handle.js";
 import { createFallbackLogger } from "../logging/index.js";
 import { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, createMetricsForFactory, emitJobLastSuccess, emitJobQueueDepth, flushEscapeHatchAudits, getFallbackTracer, registerStandardMetrics, withEscapeHatchAuditScope, } from "../observability/index.js";
 import { createDistributedLock } from "../pipeline/distributed-lock.js";
@@ -903,9 +903,7 @@ export function createJobRunner(options) {
         // through the same _fileProviderResolver for jobs as for write-handlers,
         // otherwise event-triggered jobs silently get an unresolved ctx.files.
         const fileResolver = context._fileProviderResolver;
-        const files = fileResolver
-            ? createFileContext(() => fileResolver(tenantId), tenantId)
-            : context.files;
+        const files = fileResolver ? createTenantFileContext(fileResolver, tenantId) : context.files;
         const jobSystemUser = createSystemUser(tenantId);
         // Same buildHandlerContext parity as ctx.files above: ctx.notify/ctx.config
         // must resolve for jobs the same way they do for write-handlers, or an

package/dist/pipeline/dispatch-shared.js

@@ -5,14 +5,14 @@ import { createTenantDb, createUncheckedSystemDb, hasTenantColumn, runInOwnTrans
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
 import { mayOverrideTenant } from "../engine/cross-tenant.js";
 import { createSystemUser } from "../engine/system-user.js";
-import { isRateLimitDisabled, resolveAgentExposure } from "../engine/types/index.js";
+import { declaredRateLimitOptions, isRateLimitDisabled, resolveAgentExposure, } from "../engine/types/index.js";
 import { AccessDeniedError, FeatureDisabledError, FrameworkReasons, InternalError, memberResolutionReadOnlyDenied, RateLimitError, RateLimitUnavailableError, VersionConflictError, writeFailure, } from "../errors/index.js";
 import { archiveStream as archiveStreamHelper, isStreamArchived, restoreStream as restoreStreamHelper, } from "../event-store/archive.js";
 import { IdempotentAppendConflictError as EventStoreIdempotentAppendConflictError, VersionConflictError as EventStoreVersionConflictError, } from "../event-store/errors.js";
 import { loadAggregate, loadAggregateAsOf, loadAggregateForWriting, } from "../event-store/event-store.js";
 import { effectiveSnapshotGeneration, loadAggregateWithSnapshot, saveSnapshot, } from "../event-store/snapshot.js";
 import { upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster.js";
-import { createFileContext } from "../files/file-handle.js";
+import { createTenantFileContext } from "../files/file-handle.js";
 import { DEFAULT_LOCALE, isValidLocaleTag } from "../i18n/request-locale.js";
 import { createFallbackLogger } from "../logging/utils.js";
 import { createEscapeHatchReporter, createMetricsForFactory, createMetricsHandle, createNoopMetricsHandle, emitDispatcherError, emitDispatcherHandler, getFallbackTracer, observabilityContext, } from "../observability/index.js";
@@ -459,9 +459,7 @@ readOnlyForTenant = false) {
     // _fileProviderResolver when a file-provider plugin is mounted; falls back
     // to a statically-injected context.files (tests).
     const fileResolver = context._fileProviderResolver;
-    const files = fileResolver
-        ? createFileContext(() => fileResolver(user.tenantId), user.tenantId)
-        : context.files;
+    const files = fileResolver ? createTenantFileContext(fileResolver, user.tenantId) : context.files;
     // ctx.derivatives builds on ctx.files (needs a FileContext to read the
     // original + write the variant) plus db (to look up the FileRef row) — so
     // it can only be constructed exactly when files+db both resolved; falls
@@ -1109,16 +1107,28 @@ const DEFAULT_SYSTEM_SCOPE_RATE_LIMIT = {
     limit: 600,
     windowSeconds: 60,
 };
-function resolveEffectiveRateLimit(rateLimit, isSystemScope, user, resolver) {
-    if (rateLimit)
-        return rateLimit;
+function resolveEffectiveRateLimits(rateLimit, isSystemScope, user, resolver) {
+    const declared = declaredRateLimitOptions(rateLimit);
+    if (declared.length > 0)
+        return declared;
     if (!isSystemScope)
-        return undefined;
+        return [];
     if (!resolver)
-        return undefined;
+        return [];
     if (isSystemIdentity(user))
-        return undefined;
-    return DEFAULT_SYSTEM_SCOPE_RATE_LIMIT;
+        return [];
+    return [DEFAULT_SYSTEM_SCOPE_RATE_LIMIT];
+}
+// A single bucket keeps the plain enforce path; several go through one atomic
+// all-or-nothing call so a rejection by one bucket never charges the others.
+async function enforceBuckets(resolver, requests) {
+    const [only, ...rest] = requests;
+    // skip: no bucket to charge
+    if (!only)
+        return;
+    await (rest.length === 0
+        ? resolver.enforce(only.bucket, only.config)
+        : resolver.enforceAll(requests));
 }
 // L3 rate limit gate. Called by both query and write paths before
 // access-check. Reasoning:
@@ -1137,42 +1147,48 @@ export async function enforceRateLimit(ctx, rateLimit, handlerName, user, isSyst
     // skip: handler explicitly opts out via rateLimit: { disabled: true }
     if (isRateLimitDisabled(rateLimit))
         return;
-    const effective = resolveEffectiveRateLimit(rateLimit, isSystemScope, user, context.rateLimit);
+    const effective = resolveEffectiveRateLimits(rateLimit, isSystemScope, user, context.rateLimit);
     // skip: no rateLimit declared and not systemScope (or resolved to no-op) — nothing to enforce
-    if (!effective)
+    if (effective.length === 0)
         return;
     const reqCtx = requestContext.get();
-    const bucket = buildBucketKey(effective, {
-        handlerName,
-        user,
-        ip: reqCtx?.ip,
-    });
-    // skip: ip-bucket + no IP (non-HTTP entry point) — pass through before
-    // requiring a resolver; HTTP path always has an IP + L1/L2 middleware.
-    if (bucket.kind === "skip")
-        return;
-    if (!context.rateLimit) {
-        throw new InternalError({
-            message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rate-limiting feature or remove the option.`,
-        });
-    }
     // A nested dispatch re-hitting a bucket its entry dispatch already charged
     // (e.g. a per:"ip" handler delegating via queryAs) must not cost a second token.
     // The mark is set only after a successful enforce and includes the limit
     // parameters: a denied or failed check never lets a later nested call through,
     // and a nested handler with a stricter limit on the same bucket is still checked.
     const charged = reqCtx?.chargedRateLimitBuckets;
-    const chargedKey = `${bucket.key}|${effective.limit}|${effective.windowSeconds}|${effective.cost}`;
-    // skip: this exact bucket, limit and window was already charged by the entry dispatch
-    if (charged?.has(chargedKey))
+    const pending = [];
+    for (const option of effective) {
+        const bucket = buildBucketKey(option, { handlerName, user, ip: reqCtx?.ip });
+        // skip: ip-bucket + no IP (non-HTTP entry point) — pass through before
+        // requiring a resolver; HTTP path always has an IP + L1/L2 middleware.
+        if (bucket.kind === "skip")
+            continue;
+        const chargedKey = `${bucket.key}|${option.limit}|${option.windowSeconds}|${option.cost}`;
+        // skip: this exact bucket, limit and window was already charged by the entry dispatch
+        if (charged?.has(chargedKey))
+            continue;
+        pending.push({
+            request: {
+                bucket: bucket.key,
+                config: { limit: option.limit, windowSeconds: option.windowSeconds, cost: option.cost },
+            },
+            chargedKey,
+        });
+    }
+    // skip: every bucket was skipped or already charged — nothing left to enforce
+    if (pending.length === 0)
         return;
-    try {
-        await context.rateLimit.enforce(bucket.key, {
-            limit: effective.limit,
-            windowSeconds: effective.windowSeconds,
-            cost: effective.cost,
+    if (!context.rateLimit) {
+        throw new InternalError({
+            message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rate-limiting feature or remove the option.`,
         });
-        charged?.add(chargedKey);
+    }
+    try {
+        await enforceBuckets(context.rateLimit, pending.map(({ request }) => request));
+        for (const { chargedKey } of pending)
+            charged?.add(chargedKey);
     }
     catch (error) {
         // Backend failure (Redis down): fail closed as 503, same as L1/L2.
@@ -1205,6 +1221,7 @@ export async function enforcePayloadRateLimits(ctx, limits, handlerName, user, d
             message: `Handler "${handlerName}" declares additionalRateLimits but its payload is not an object.`,
         });
     }
+    const requests = [];
     for (const { per, limit, windowSeconds, cost, normalize } of limits) {
         const value = data[per.payloadField];
         // skip: optional field not sent — nothing to bucket on
@@ -1215,9 +1232,10 @@ export async function enforcePayloadRateLimits(ctx, limits, handlerName, user, d
                 message: `Handler "${handlerName}" additionalRateLimits payloadField "${per.payloadField}" is not a string.`,
             });
         }
-        const key = buildPayloadBucketKey(user.tenantId, handlerName, per.payloadField, digest(normalizePayloadBucketValue(value, normalize)));
-        await context.rateLimit.enforce(key, { limit, windowSeconds, cost });
+        const bucket = buildPayloadBucketKey(user.tenantId, handlerName, per.payloadField, digest(normalizePayloadBucketValue(value, normalize)));
+        requests.push({ bucket, config: { limit, windowSeconds, cost } });
     }
+    await enforceBuckets(context.rateLimit, requests);
 }
 // Build the per-hook context every auth-claims invocation gets. Claims
 // hooks run OUTSIDE any request transaction (login is itself the root

package/dist/pipeline/index.d.ts

@@ -1,6 +1,7 @@
 export type { EscapeHatchReportWindow } from "../observability/escape-hatch-report.ts";
 export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, flushEscapeHatchAudits, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, withEscapeHatchAuditScope, } from "../observability/escape-hatch-report.ts";
 export { normalizePayloadBucketValue } from "../rate-limit/bucket.ts";
+export { createUnlimitedRateLimitResolver } from "../rate-limit/unlimited-resolver.ts";
 export type { AppendDomainEventCoreDeps } from "./append-event-core.ts";
 export { appendDomainEventCore } from "./append-event-core.ts";
 export type { ResolveAuthClaimsArgs } from "./auth-claims-resolver.ts";

package/dist/pipeline/index.js

@@ -1,5 +1,6 @@
 export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, flushEscapeHatchAudits, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, withEscapeHatchAuditScope, } from "../observability/escape-hatch-report.js";
 export { normalizePayloadBucketValue } from "../rate-limit/bucket.js";
+export { createUnlimitedRateLimitResolver } from "../rate-limit/unlimited-resolver.js";
 export { appendDomainEventCore } from "./append-event-core.js";
 export { resolveAuthClaims } from "./auth-claims-resolver.js";
 export { createCascadeDeleteHook } from "./cascade-handler.js";

package/dist/rate-limit/index.d.ts

@@ -1,3 +1,4 @@
 export { type BucketContext, type BucketResult, buildBucketKey, buildPayloadBucketKey, createPayloadDigest, normalizePayloadBucketValue, } from "./bucket.ts";
 export { type AuthEndpointRateLimitOptions, authEndpointRateLimit, type GlobalIpRateLimitOptions, globalIpRateLimit, type HttpRouteRateLimitOptions, httpRouteRateLimit, } from "./middleware.ts";
-export { createRateLimitResolver, type RateLimitConfig, type RateLimitDecision, type RateLimitResolver, type RateLimitResolverOptions, } from "./resolver.ts";
+export { createRateLimitResolver, type RateLimitBucketRequest, type RateLimitConfig, type RateLimitDecision, type RateLimitResolver, type RateLimitResolverOptions, } from "./resolver.ts";
+export { createUnlimitedRateLimitResolver } from "./unlimited-resolver.ts";

package/dist/rate-limit/index.js

@@ -1,3 +1,4 @@
 export { buildBucketKey, buildPayloadBucketKey, createPayloadDigest, normalizePayloadBucketValue, } from "./bucket.js";
 export { authEndpointRateLimit, globalIpRateLimit, httpRouteRateLimit, } from "./middleware.js";
 export { createRateLimitResolver, } from "./resolver.js";
+export { createUnlimitedRateLimitResolver } from "./unlimited-resolver.js";

package/dist/rate-limit/resolver.d.ts

@@ -1,6 +1,6 @@
 import type { RateLimitResolver } from "@cosmicdrift/kumiko-types/rate-limit-types";
 import type { Redis } from "ioredis";
-export type { RateLimitConfig, RateLimitDecision, RateLimitResolver, } from "@cosmicdrift/kumiko-types/rate-limit-types";
+export type { RateLimitBucketRequest, RateLimitConfig, RateLimitDecision, RateLimitResolver, } from "@cosmicdrift/kumiko-types/rate-limit-types";
 export type RateLimitResolverOptions = {
     readonly redis: Redis;
     readonly keyPrefix?: string;