@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/dist/files/local-provider.js

@@ -0,0 +1,128 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { assertSafeStorageKey } from "./types.js";
+// Local-filesystem backend — intended for dev + tests. Production deploys
+// pick an object-store provider (S3/R2/…). mimeType is ignored here; the
+// filesystem tracks no metadata beyond what the caller stores on FileRef.
+export function createLocalProvider(basePath) {
+    const resolvedBase = resolve(basePath);
+    // Callers are expected to only ever pass keys built by buildStorageKey(),
+    // but the storage layer shouldn't rely solely on that — this resolves the
+    // real path and rejects anything that escapes basePath (e.g. a `..`
+    // segment that slipped past an upstream check), regardless of the key's
+    // source.
+    function resolveContainedPath(key) {
+        assertSafeStorageKey(key);
+        // assertSafeStorageKey rejects every literal "."/".." segment, which
+        // covers all string-based traversal a join+resolve can produce; this
+        // startsWith check is a second, independent line of defense in case a
+        // future caller feeds resolveContainedPath something pre-resolved.
+        const filePath = resolve(join(basePath, key));
+        if (filePath !== resolvedBase && !filePath.startsWith(resolvedBase + sep)) {
+            throw new Error(`storage key escapes basePath: "${key}"`);
+        }
+        return filePath;
+    }
+    return {
+        async write(key, data, _mimeType) {
+            const filePath = resolveContainedPath(key);
+            await mkdir(dirname(filePath), { recursive: true });
+            await writeFile(filePath, data);
+        },
+        async writeStream(key, source, _options) {
+            // Atomar via tmp-File + rename: ein Reader der den finalen Pfad
+            // sieht, sieht entweder die alte Version (falls vorhanden) oder
+            // die vollstaendige neue. Niemals einen halb-fertigen Stream.
+            // Falls der Stream mid-write bricht, ist das tmp-Cleanup
+            // best-effort — je nach OS-Race im stream-destroy-Pfad kann
+            // das `.tmp`-File kurz liegen bleiben. Kein Korrektheits-
+            // Problem (kein Reader sucht `*.tmp`-Patterns), nur Operations-
+            // Hygiene; ein periodischer cron-cleanup auf alten `.tmp`-Files
+            // ist die saubere Loesung wenn das in Production realistisch
+            // greift.
+            const filePath = resolveContainedPath(key);
+            const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+            await mkdir(dirname(filePath), { recursive: true });
+            try {
+                await pipeline(source, createWriteStream(tmpPath));
+                await rename(tmpPath, filePath);
+            }
+            catch (e) {
+                // Best-effort tmp-Cleanup; wenn das auch failt, hat der
+                // Filesystem ein Problem das nicht in unserem Scope liegt.
+                await unlink(tmpPath).catch(() => { });
+                throw e;
+            }
+        },
+        async read(key) {
+            const filePath = resolveContainedPath(key);
+            return readFile(filePath);
+        },
+        readStream(key) {
+            // node:fs createReadStream ist ein AsyncIterable<Buffer>; Buffer
+            // extends Uint8Array. Wir bauen einen kleinen Adapter weil
+            // @types/node das asyncIterator als AsyncIterableIterator<any>
+            // typt — Adapter sichert die Surface auf Uint8Array.
+            // Default-highWaterMark = 64KB Chunks, was fuer ZIP-Stream-Konsum
+            // gut ist. Errors landen im for-await-Loop des Konsumenten
+            // (z.B. ENOENT bei Missing-File faellt erst beim ersten chunk-
+            // pull, nicht beim readStream-Aufruf — gleiches Lazy-Verhalten
+            // wie inmemory + S3).
+            const filePath = resolveContainedPath(key);
+            const stream = createReadStream(filePath);
+            return {
+                async *[Symbol.asyncIterator]() {
+                    for await (const chunk of stream) {
+                        // Stream ohne encoding liefert Buffer. Buffer extends Uint8Array,
+                        // aber @types/node typt asyncIterator als string|Buffer. View
+                        // ohne copy auf dasselbe ArrayBuffer; runtime-check schliesst
+                        // den string-Branch aus (Stream wurde nicht mit encoding= gesetzt).
+                        if (typeof chunk === "string") {
+                            throw new Error("local-provider readStream: unexpected string chunk (encoding leaked)");
+                        }
+                        yield new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+                    }
+                },
+            };
+        },
+        async delete(key) {
+            const filePath = resolveContainedPath(key);
+            await rm(filePath, { force: true });
+        },
+        async exists(key) {
+            try {
+                await stat(resolveContainedPath(key));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async list(prefix) {
+            // recursive:true returns POSIX- or OS-sep-joined relative paths for
+            // both files and directories; normalize to "/" (storage keys are
+            // always "/"-joined, matching S3) before the prefix match, then stat
+            // only the (few) matches to drop directory entries.
+            let entries;
+            try {
+                entries = await readdir(resolvedBase, { recursive: true });
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return [];
+                throw err;
+            }
+            const results = [];
+            for (const entry of entries) {
+                const key = entry.split(sep).join("/");
+                if (!key.startsWith(prefix))
+                    continue;
+                if ((await stat(join(resolvedBase, entry))).isFile())
+                    results.push(key);
+            }
+            return results;
+        },
+    };
+}

package/dist/files/provider-resolver.d.ts

@@ -0,0 +1,58 @@
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
+import type { DbConnection } from "../db/connection.js";
+import type { TenantDb } from "../db/tenant-db.js";
+import type { ConfigAccessor, ConfigAccessorFactory, Registry } from "../engine/types/index.js";
+import type { SecretsContext } from "../secrets/index.js";
+import type { FileStorageProvider } from "./types.js";
+/**
+ * Schmaler Surface-Type fuer Provider-Plugins. HandlerContext ist zu fett
+ * (haelt tx, actor, signal etc.) — Provider sollen sich auf die read-Felder
+ * beschraenken die fuer Tenant-Config + Secret-Lookup gebraucht werden.
+ *
+ * **Warum nicht voller HandlerContext?** Im Worker-Pfad (r.job) gibt es keinen
+ * request-bezogenen `tx`/`actor`/`signal`. Wenn ein Provider `ctx.tx` lesen
+ * wuerde, wuerde der ganze Worker-Pfad zur Runtime brechen — und das wuerde NUR
+ * mit S3 und nur in production auffallen. Die schmale Surface zwingt Provider
+ * zur expliziten Erweiterung statt silent ctx-feld-ausnutzen.
+ *
+ * **Felder:**
+ *   config  — fuer tenant-config-reads (bucket/region/endpoint/...)
+ *   registry — fuer extension-Lookup in der Factory (nicht Plugin-intern)
+ *   secrets — fuer tenant-secret-reads (s3.secretAccessKey)
+ *   _userId — Audit-/Authority-Identity fuer secret-reads. Der Framework-
+ *             Resolver setzt das auf SYSTEM_USER_ID — der s3-Provider liest
+ *             `s3.secretAccessKey`, was Nicht-Admin-Request-User nicht duerfen;
+ *             die Request-User-Autorisierung bleibt am Route-accessGuard.
+ */
+export type FileProviderContext = {
+    readonly config?: ConfigAccessor;
+    readonly registry?: Registry;
+    readonly secrets?: SecretsContext;
+    readonly _userId?: string | undefined;
+};
+/**
+ * File-Storage-Plugin contract. Each provider-feature (file-provider-s3,
+ * file-provider-inmemory, ...) registers an implementation via
+ * `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`.
+ *
+ * **Plugin-Author-Warnung:** `ctx` ist EXPLIZIT ein FileProviderContext, nicht
+ * ein voller HandlerContext. Felder ausserhalb der schmalen Surface (z.B.
+ * `ctx.tx`, `ctx.actor`, `ctx.signal`) sind im Worker-Pfad NICHT vorhanden.
+ * Cast `ctx as unknown as HandlerContext` fliegt zur Runtime im Worker — der
+ * Crash kommt erst in production mit dem ersten S3-Tenant. Braucht ein Plugin
+ * Felder ausserhalb FileProviderContext: lieber FileProviderContext explizit
+ * erweitern (sichtbarer breaking change) als ctx-cast.
+ */
+export type FileProviderPlugin = {
+    readonly build: (ctx: FileProviderContext, tenantId: string) => Promise<FileStorageProvider>;
+};
+export declare function isFileProviderPlugin(o: unknown): o is FileProviderPlugin;
+export declare function createFileProviderForTenant(ctx: FileProviderContext, tenantId: string, handlerName?: string): Promise<FileStorageProvider>;
+export type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
+export type FileProviderResolverDeps = {
+    readonly registry?: Registry;
+    readonly _configAccessorFactory?: ConfigAccessorFactory;
+    readonly secrets?: SecretsContext;
+    readonly db?: DbConnection | TenantDb;
+};
+export declare function makeFileProviderResolver(deps: FileProviderResolverDeps): FileProviderResolver;

package/dist/files/provider-resolver.js

@@ -0,0 +1,87 @@
+// File-provider resolution — lives in the framework so the upload routes,
+// `ctx.files`, AND the GDPR export/forget jobs resolve their FileStorageProvider
+// through ONE path. Divergence (uploads writing one store, erasure deleting
+// another) is structurally impossible: there is a single resolver.
+//
+// The framework owns the resolution but NOT the storage backends. The
+// `fileProvider` extension point + the per-tenant `provider` config key are
+// declared by the `file-foundation` bundled feature; the concrete stores live
+// in `file-provider-*` plugins. The framework only consumes what features
+// registered in the registry — it never imports bundled-features upward.
+//
+// file-foundation re-exports `createFileProviderForTenant` + the plugin types
+// (moved here from there) so existing imports keep working.
+import { EXT_FILE_PROVIDER, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT_SENTINEL, } from "../engine/extension-names.js";
+import { SYSTEM_USER_ID } from "../engine/system-user.js";
+const FEATURE_NAME = "file-foundation";
+// extension-usage `options` is engine-payload (unknown) — structurally validate
+// instead of casting blind.
+export function isFileProviderPlugin(o) {
+    return typeof o === "object" && o !== null && "build" in o && typeof o.build === "function";
+}
+// Looks up the per-tenant selected provider plugin + delegates to its build().
+export async function createFileProviderForTenant(ctx, tenantId, handlerName = "file-foundation:provider-factory") {
+    const ctxConfig = ctx.config;
+    if (!ctxConfig) {
+        throw new Error(`${handlerName}: ctx.config is missing — feature requires the config-feature mounted in the registry`);
+    }
+    if (!ctx.registry) {
+        throw new Error(`${handlerName}: ctx.registry is missing — required to look up registered file-provider plugins`);
+    }
+    const raw = await ctxConfig(FILE_PROVIDER_CONFIG_KEY);
+    const provider = typeof raw === "string" ? raw : raw == null ? "" : String(raw);
+    // The boot-gate placeholder names no plugin: treated as a provider name it
+    // would let FILE_STORAGE_PROVIDER=configured fake a selection through the
+    // ENV bridge.
+    if (provider.length === 0 || provider === FILE_STORAGE_PROVIDER_BOOT_SENTINEL) {
+        const usages = ctx.registry.getExtensionUsages(EXT_FILE_PROVIDER);
+        const known = usages.map((u) => u.entityName).join(", ") || "<none>";
+        throw new Error(`${FEATURE_NAME}: no provider selected — set the '${FILE_PROVIDER_CONFIG_KEY}' config-key to one of: ${known}. ` +
+            `Mount a file-provider-* feature first if no plugins are registered.`);
+    }
+    const usages = ctx.registry.getExtensionUsages(EXT_FILE_PROVIDER);
+    const usage = usages.find((u) => u.entityName === provider);
+    if (!usage) {
+        const known = usages.map((u) => u.entityName).join(", ") || "<none>";
+        throw new Error(`${FEATURE_NAME}: provider "${provider}" not registered. Known: ${known}. ` +
+            `Mount the matching file-provider-${provider} feature.`);
+    }
+    if (!isFileProviderPlugin(usage.options)) {
+        throw new Error(`${FEATURE_NAME}: provider "${provider}" registered without a build() — ` +
+            `extension options must be a FileProviderPlugin.`);
+    }
+    return usage.options.build(ctx, tenantId);
+}
+// Builds the resolver from the ambient AppContext fields — the framework-side
+// equivalent of the GDPR `makeTenantStorageProviderResolver`. The config
+// accessor (and therefore the s3.secretAccessKey secret-read) runs under
+// SYSTEM identity: provider construction is an infra read, distinct from the
+// request user's authorization which stays at the route accessGuard.
+export function makeFileProviderResolver(deps) {
+    // Per-tenant cache (698/2) — without it, every resolveProvider(tenantId)
+    // call re-reads config + secrets from the DB, even though the provider is
+    // effectively static per tenant for the process lifetime. A rejected
+    // promise is evicted so a transient failure (or a secret genuinely not
+    // configured yet) doesn't permanently poison this tenant's entry.
+    const cache = new Map();
+    return (tenantId) => {
+        const cached = cache.get(tenantId);
+        if (cached)
+            return cached;
+        const built = (async () => {
+            if (!deps.registry || !deps._configAccessorFactory || !deps.db) {
+                throw new Error("makeFileProviderResolver: registry/_configAccessorFactory/db missing — " +
+                    "mount the config + file-foundation features and wire context.db");
+            }
+            const config = deps._configAccessorFactory({
+                user: { id: SYSTEM_USER_ID, tenantId },
+                db: deps.db,
+                secrets: deps.secrets,
+            });
+            return createFileProviderForTenant({ config, registry: deps.registry, secrets: deps.secrets, _userId: SYSTEM_USER_ID }, tenantId);
+        })();
+        built.catch(() => cache.delete(tenantId));
+        cache.set(tenantId, built);
+        return built;
+    };
+}

package/dist/files/storage-tracking.d.ts

@@ -0,0 +1,20 @@
+import { type DbRunner } from "../db/index.js";
+import { type Registry } from "../engine/index.js";
+export declare function fileRefStorageDelta(event: {
+    readonly type: string;
+    readonly payload: Record<string, unknown>;
+}): {
+    readonly bytes: number;
+    readonly files: number;
+} | null;
+export declare const tenantStorageUsageTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const filesStorageTrackingFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: void;
+};
+export declare function transferTenantStorageUsage(args: {
+    readonly db: DbRunner;
+    readonly registry: Registry;
+    readonly fileRefIds: readonly string[];
+    readonly sourceTenantId: string;
+    readonly destinationTenantId: string;
+}): Promise<void>;

package/dist/files/storage-tracking.js

@@ -0,0 +1,179 @@
+// Tenant storage usage — counts bytes + files per tenant from the event log.
+//
+// Tracking-only for Phase 1: no hard limit, no upload gatekeeping. Apps read
+// the row to decide what to do (show a warning, soft-throttle, bill, …).
+// Enforcement is a conscious deferred call — we want production numbers
+// before picking thresholds (see "Storage tracking: counted now, enforced
+// later" in core-files.md).
+//
+// The MSP is packaged as its own opt-in feature so tests that don't care
+// about storage metrics don't pay for the projection-table push or the
+// consumer-cursor row. Apps that want it pass filesStorageTrackingFeature
+// into createApp / setupTestStack alongside their domain features.
+import { bigint, instant, integer, table as pgTable, sql, uuid } from "../db/dialect.js";
+import { entityEventName, executeRawQueryRead } from "../db/index.js";
+import { incrementCounter } from "../db/query.js";
+import { defineFeature, qn, toKebab } from "../engine/index.js";
+import { SHARED_INSTANCE_SENTINEL, selectConsumerCursorForUpdate, } from "../pipeline/index.js";
+import { parseJsonOrThrow } from "../utils/index.js";
+const FILE_REF_AGGREGATE_TYPE = "fileRef";
+const STORAGE_TRACKING_FEATURE_NAME = "files-storage-tracking";
+const TENANT_STORAGE_USAGE_MSP_NAME = "tenant-storage-usage";
+// fileRef is a standard ES entity, so usage tracking subscribes to its
+// auto-verb events. `fileRef.created` payload carries the entity fields
+// (incl. size); `fileRef.deleted` / `fileRef.restored` carry `{ previous }`
+// (the pre-event row), so the byte count to apply lives at previous.size.
+const FILE_REF_CREATED = entityEventName(FILE_REF_AGGREGATE_TYPE, "created");
+const FILE_REF_DELETED = entityEventName(FILE_REF_AGGREGATE_TYPE, "deleted");
+const FILE_REF_RESTORED = entityEventName(FILE_REF_AGGREGATE_TYPE, "restored");
+function readNumber(value) {
+    return typeof value === "number" ? value : 0;
+}
+function sizeFromPrevious(payload) {
+    const previous = payload["previous"];
+    if (previous && typeof previous === "object" && !Array.isArray(previous)) {
+        return readNumber(previous["size"]); // @cast-boundary engine-payload
+    }
+    return 0;
+}
+// Single source of truth for "how much does this fileRef event move the
+// tenant's storage counters" — shared by the MSP's own apply handlers and by
+// transferTenantStorageUsage's replay of already-applied events during a
+// tenant handover.
+export function fileRefStorageDelta(event) {
+    switch (event.type) {
+        case FILE_REF_CREATED:
+            return { bytes: readNumber(event.payload["size"]), files: 1 };
+        case FILE_REF_DELETED:
+            // `0 - x`, not `-x`: a zero-byte previous size must stay `0`, not `-0`
+            // (toEqual/JSON round-trips treat -0 as distinct from 0).
+            return { bytes: 0 - sizeFromPrevious(event.payload), files: -1 };
+        case FILE_REF_RESTORED:
+            return { bytes: sizeFromPrevious(event.payload), files: 1 };
+        default:
+            return null;
+    }
+}
+// bigint in `mode: "number"` returns a JS number (safe up to 2^53 ≈ 9e15
+// bytes ≈ 8 petabytes per tenant — large enough for any practical storage
+// quota). Default "bigint" mode would hand back a bigint value, which
+// arithmetic on Drizzle's sql`` template would still accept but forces
+// callers to remember the type.
+export const tenantStorageUsageTable = pgTable("read_tenant_storage_usage", {
+    tenantId: uuid("tenant_id").primaryKey(),
+    totalBytes: bigint("total_bytes", { mode: "number" }).notNull().default(0),
+    fileCount: integer("file_count").notNull().default(0),
+    lastUpdatedAt: instant("last_updated_at").default(sql `now()`).notNull(),
+});
+export const filesStorageTrackingFeature = defineFeature(STORAGE_TRACKING_FEATURE_NAME, (r) => {
+    r.multiStreamProjection({
+        name: TENANT_STORAGE_USAGE_MSP_NAME,
+        table: tenantStorageUsageTable,
+        apply: {
+            [FILE_REF_CREATED]: async (event, tx) => {
+                const delta = fileRefStorageDelta(event);
+                // skip: not a tracked fileRef storage change
+                if (!delta)
+                    return;
+                // UPSERT: INSERT on first upload per tenant, otherwise atomic increment.
+                // The SQL increment guarantees correctness under concurrent dispatcher
+                // runs (shouldn't happen with a single consumer, but the invariant is
+                // free and cheap — no reason to rely on serial delivery).
+                await incrementCounter(tx, tenantStorageUsageTable, { tenantId: event.tenantId, totalBytes: delta.bytes, fileCount: delta.files }, { totalBytes: delta.bytes, fileCount: delta.files }, { set: { lastUpdatedAt: sql `now()` } });
+            },
+            [FILE_REF_DELETED]: async (event, tx) => {
+                const delta = fileRefStorageDelta(event);
+                // skip: not a tracked fileRef storage change
+                if (!delta)
+                    return;
+                // Decrement on delete. INSERT values are 0/0 so a delete that somehow
+                // precedes any upload can't create negative usage; the on-conflict
+                // path applies the real negative delta. Async (dispatcher) —
+                // eventually-consistent with the write-tx that emitted fileRef.deleted.
+                await incrementCounter(tx, tenantStorageUsageTable, { tenantId: event.tenantId, totalBytes: 0, fileCount: 0 }, { totalBytes: delta.bytes, fileCount: delta.files }, { set: { lastUpdatedAt: sql `now()` } });
+            },
+            [FILE_REF_RESTORED]: async (event, tx) => {
+                // Restore re-increments by the soft-deleted row's size — symmetric
+                // to delete. Without this handler totalBytes/fileCount drift low
+                // after every delete→restore round-trip.
+                const delta = fileRefStorageDelta(event);
+                // skip: not a tracked fileRef storage change
+                if (!delta)
+                    return;
+                await incrementCounter(tx, tenantStorageUsageTable, { tenantId: event.tenantId, totalBytes: delta.bytes, fileCount: delta.files }, { totalBytes: delta.bytes, fileCount: delta.files }, { set: { lastUpdatedAt: sql `now()` } });
+            },
+        },
+    });
+});
+// Qualified name of the tenant-storage-usage MSP consumer row in
+// kumiko_event_consumers — the same qualification registry-ingest.ts applies
+// to every multiStreamProjection (qualify(featureName, "projection", name)).
+const TENANT_STORAGE_USAGE_MSP_QN = qn(toKebab(STORAGE_TRACKING_FEATURE_NAME), "projection", toKebab(TENANT_STORAGE_USAGE_MSP_NAME));
+const TRACKED_FILE_REF_EVENT_TYPES = [FILE_REF_CREATED, FILE_REF_DELETED, FILE_REF_RESTORED];
+function isWithinPendingGap(eventId, gaps) {
+    return gaps.some((gap) => eventId >= BigInt(gap.from) && eventId <= BigInt(gap.to));
+}
+// Moves the already-applied share of the tenant-storage-usage counters from
+// source to destination tenant when a tenant-handover claim moves fileRef
+// rows. Must run BEFORE moveEventHistory rewrites the events' tenant_id —
+// the query below finds "already applied" events by sourceTenantId, and once
+// the rewrite runs there is no way to tell an already-applied event from a
+// not-yet-applied one by tenant_id alone.
+//
+// Events with id above the cursor (or inside a pending gap) are NOT summed
+// here: the dispatcher hasn't applied them yet, they will carry the
+// destination tenant_id once moveEventHistory runs, and the dispatcher will
+// apply them against the destination counter on its own next pass.
+export async function transferTenantStorageUsage(args) {
+    const { db, registry, fileRefIds, sourceTenantId, destinationTenantId } = args;
+    // skip: no fileRefs moved, nothing to transfer
+    if (fileRefIds.length === 0)
+        return;
+    // skip: storage tracking is not mounted in this app
+    if (!registry.getAllMultiStreamProjections().has(TENANT_STORAGE_USAGE_MSP_QN))
+        return;
+    // Locks the same consumer row the dispatcher's own FOR UPDATE SKIP LOCKED
+    // pass takes before applying a batch — serializing against it here means no
+    // fileRef event for these ids can be applied between reading the cursor
+    // below and the tenant move that follows in the caller.
+    const cursor = await selectConsumerCursorForUpdate(db, TENANT_STORAGE_USAGE_MSP_QN, SHARED_INSTANCE_SENTINEL);
+    // skip: no consumer row means the MSP never applied anything yet
+    if (!cursor)
+        return;
+    const rows = await executeRawQueryRead(db, `SELECT "id"::text AS id, "type", "payload"::text AS payload FROM kumiko_events
+     WHERE "tenant_id" = $1 AND "aggregate_type" = $2 AND "aggregate_id" = ANY($3)
+       AND "type" = ANY($4) AND "id" <= $5`, [
+        sourceTenantId,
+        FILE_REF_AGGREGATE_TYPE,
+        fileRefIds,
+        TRACKED_FILE_REF_EVENT_TYPES,
+        cursor.lastProcessedEventId,
+    ]);
+    let bytes = 0;
+    let files = 0;
+    for (const row of rows) {
+        if (isWithinPendingGap(BigInt(row.id), cursor.pendingGaps))
+            continue;
+        const delta = fileRefStorageDelta({
+            type: row.type,
+            payload: parseJsonOrThrow(row.payload, "transferTenantStorageUsage: kumiko_events.payload"),
+        });
+        if (!delta)
+            continue;
+        bytes += delta.bytes;
+        files += delta.files;
+    }
+    // skip: the moved fileRefs carry no applied storage share
+    if (bytes === 0 && files === 0)
+        return;
+    // Source: insert-values stay 0/0 (same guard as the DELETED handler above)
+    // — the row this subtracts from is expected to already exist (the MSP
+    // already applied the create against it), and if it somehow doesn't, this
+    // must not conjure a negative balance out of thin air.
+    await incrementCounter(db, tenantStorageUsageTable, { tenantId: sourceTenantId, totalBytes: 0, fileCount: 0 }, { totalBytes: -bytes, fileCount: -files }, { set: { lastUpdatedAt: sql `now()` } });
+    // Destination: insert-values ARE the transferred amount (same as CREATED/
+    // RESTORED above) — a tenant claiming its first-ever fileRef must start
+    // its counter row at the transferred total, not at 0 with an increment
+    // that only fires once a row already exists.
+    await incrementCounter(db, tenantStorageUsageTable, { tenantId: destinationTenantId, totalBytes: bytes, fileCount: files }, { totalBytes: bytes, fileCount: files }, { set: { lastUpdatedAt: sql `now()` } });
+}

package/dist/files/types.d.ts

@@ -0,0 +1,59 @@
+import type { TenantId } from "../engine/types/identifiers.js";
+export type FileMetadata = {
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly size: number;
+};
+export type { FileStorageProvider, SignedUrlOptions, WriteStreamOptions, } from "@cosmicdrift/kumiko-types/file-storage-provider-types";
+export type FileValidationOptions = {
+    readonly maxSize?: string | undefined;
+    readonly accept?: readonly string[] | undefined;
+};
+export declare function parseMaxSize(maxSize: string): number;
+/**
+ * Canonical MIME type for a known binary magic-byte signature (png, jpeg,
+ * gif, webp, pdf, OLE, ZIP), or null for everything else — text formats
+ * (csv, txt, json, svg, md) have no signature and always return null. Every
+ * OLE Compound File (.doc/.xls/.ppt) returns "application/msword" and every
+ * ZIP (.docx/.xlsx/.pptx/.zip) returns the docx MIME — callers can't tell
+ * those apart by bytes alone.
+ */
+export declare function sniffMimeType(bytes: Uint8Array): string | null;
+export declare function normalizeMimeType(mimeType: string): string;
+export declare function resolveServedContentType(bytes: Uint8Array, declaredMimeType: string): string;
+export declare function validateFile(metadata: FileMetadata, options: FileValidationOptions): string | null;
+export type FileContentValidationResult = {
+    readonly kind: "ok";
+} | {
+    readonly kind: "normalized";
+    readonly extension: string;
+    readonly mimeType: string;
+} | {
+    readonly kind: "rejected";
+    readonly error: string;
+};
+export declare function validateFileContent(fileName: string, content: Uint8Array, accept?: readonly string[]): FileContentValidationResult;
+export type UploadMimeTypeResolution = {
+    readonly kind: "ok";
+    readonly mimeType: string;
+} | {
+    readonly kind: "rejected";
+    readonly error: string;
+};
+/**
+ * Rewrites an aliased declared mimeType to its canonical form and, in the
+ * same call, sniffs the bytes — a renamed binary (a real .xls/.xlsx saved
+ * as .csv) must fail here rather than through an optional, skippable step.
+ */
+export declare function resolveUploadMimeType(fileName: string, declaredMimeType: string, content: Uint8Array): UploadMimeTypeResolution;
+export declare function assertSafeStorageKey(key: string): void;
+export declare function buildStorageKey(tenantId: TenantId, entityType: string, entityId: number | string, fieldName: string, fileName: string, uniqueId: string, extensionOverride?: string): string;
+/** Fixed leading segment so one S3 lifecycle rule (Prefix: "exports/") can expire export bundles for every tenant without matching a buildStorageKey() upload. */
+export declare function tenantExportPrefix(tenantId: TenantId): string;
+/**
+ * Every storage-key prefix a tenant's binaries can live under. A tenant-destroy
+ * prefix sweep must list ALL of these, not just buildStorageKey()'s
+ * `${tenantId}/` — new key layouts (like tenantExportPrefix) that don't put
+ * the tenant first need adding here too, or a sweep silently stops covering them.
+ */
+export declare function tenantStoragePrefixes(tenantId: TenantId): readonly string[];