@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/src/files/index.ts

@@ -1,57 +0,0 @@
-export { createFilesFeature } from "./feature";
-export type { FileContext, FileHandle } from "./file-handle";
-// `createFileHandle` is an implementation detail — construct handles via
-// `createFileContext(provider).ref(key)`, which is the AppContext surface.
-export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle";
-export { fileRefEntity } from "./file-ref-entity";
-export { fileRefsTable } from "./file-ref-table";
-export type {
-  FileAccessDecision,
-  FileAccessGuard,
-  FileRef,
-  FileRoutesOptions,
-} from "./file-routes";
-export { createFileRoutes, readFilesRouteOptions, resolveMaxUploadBodyBytes } from "./file-routes";
-export type { InMemoryFileProvider } from "./in-memory-provider";
-export { createInMemoryFileProvider } from "./in-memory-provider";
-export { createLocalProvider } from "./local-provider";
-export type {
-  FileProviderContext,
-  FileProviderPlugin,
-  FileProviderResolver,
-  FileProviderResolverDeps,
-} from "./provider-resolver";
-export {
-  createFileProviderForTenant,
-  isFileProviderPlugin,
-  makeFileProviderResolver,
-} from "./provider-resolver";
-export {
-  fileRefStorageDelta,
-  filesStorageTrackingFeature,
-  tenantStorageUsageTable,
-  transferTenantStorageUsage,
-} from "./storage-tracking";
-export type {
-  FileContentValidationResult,
-  FileMetadata,
-  FileStorageProvider,
-  FileValidationOptions,
-  SignedUrlOptions,
-  UploadMimeTypeResolution,
-  WriteStreamOptions,
-} from "./types";
-export {
-  assertSafeStorageKey,
-  buildStorageKey,
-  normalizeMimeType,
-  parseMaxSize,
-  resolveUploadMimeType,
-  sniffMimeType,
-  tenantExportPrefix,
-  tenantStoragePrefixes,
-  validateFile,
-  validateFileContent,
-} from "./types";
-export type { ZipEntry } from "./zip-stream";
-export { createZipStream } from "./zip-stream";

package/src/files/local-provider.ts

@@ -1,132 +0,0 @@
-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, type FileStorageProvider } from "./types";
-
-// 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: string): FileStorageProvider {
-  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: string): string {
-    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: string, data: Uint8Array, _mimeType?: string): Promise<void> {
-      const filePath = resolveContainedPath(key);
-      await mkdir(dirname(filePath), { recursive: true });
-      await writeFile(filePath, data);
-    },
-
-    async writeStream(key, source, _options): Promise<void> {
-      // 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: string): Promise<Uint8Array> {
-      const filePath = resolveContainedPath(key);
-      return readFile(filePath);
-    },
-
-    readStream(key: string): AsyncIterable<Uint8Array> {
-      // 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: string): Promise<void> {
-      const filePath = resolveContainedPath(key);
-      await rm(filePath, { force: true });
-    },
-
-    async exists(key: string): Promise<boolean> {
-      try {
-        await stat(resolveContainedPath(key));
-        return true;
-      } catch {
-        return false;
-      }
-    },
-
-    async list(prefix: string): Promise<readonly string[]> {
-      // 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: string[];
-      try {
-        entries = await readdir(resolvedBase, { recursive: true });
-      } catch (err) {
-        if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
-        throw err;
-      }
-      const results: string[] = [];
-      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/src/files/provider-resolver.ts

@@ -1,176 +0,0 @@
-// 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 type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
-import type { DbConnection } from "../db/connection";
-import type { TenantDb } from "../db/tenant-db";
-import {
-  EXT_FILE_PROVIDER,
-  FILE_PROVIDER_CONFIG_KEY,
-  FILE_STORAGE_PROVIDER_BOOT_SENTINEL,
-} from "../engine/extension-names";
-import { SYSTEM_USER_ID } from "../engine/system-user";
-import type { ConfigAccessor, ConfigAccessorFactory, Registry } from "../engine/types";
-import type { SecretsContext } from "../secrets";
-import type { FileStorageProvider } from "./types";
-
-const FEATURE_NAME = "file-foundation";
-
-/**
- * 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>;
-};
-
-// extension-usage `options` is engine-payload (unknown) — structurally validate
-// instead of casting blind.
-export function isFileProviderPlugin(o: unknown): o is FileProviderPlugin {
-  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: FileProviderContext,
-  tenantId: string,
-  handlerName = "file-foundation:provider-factory",
-): Promise<FileStorageProvider> {
-  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);
-}
-
-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;
-};
-
-// 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: FileProviderResolverDeps): FileProviderResolver {
-  // 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<string, Promise<FileStorageProvider>>();
-  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/src/files/storage-tracking.ts

@@ -1,245 +0,0 @@
-// 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 { type DbRunner, entityEventName, executeRawQueryRead } from "../db";
-import { bigint, instant, integer, table as pgTable, sql, uuid } from "../db/dialect";
-import { incrementCounter } from "../db/query";
-import { defineFeature, qn, type Registry, toKebab } from "../engine";
-import {
-  type PendingGapEntry,
-  SHARED_INSTANCE_SENTINEL,
-  selectConsumerCursorForUpdate,
-} from "../pipeline";
-import { parseJsonOrThrow } from "../utils";
-
-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: unknown): number {
-  return typeof value === "number" ? value : 0;
-}
-
-function sizeFromPrevious(payload: Record<string, unknown>): number {
-  const previous = payload["previous"];
-  if (previous && typeof previous === "object" && !Array.isArray(previous)) {
-    return readNumber((previous as Record<string, unknown>)["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: {
-  readonly type: string;
-  readonly payload: Record<string, unknown>;
-}): { readonly bytes: number; readonly files: number } | null {
-  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: bigint, gaps: readonly PendingGapEntry[]): boolean {
-  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: {
-  readonly db: DbRunner;
-  readonly registry: Registry;
-  readonly fileRefIds: readonly string[];
-  readonly sourceTenantId: string;
-  readonly destinationTenantId: string;
-}): Promise<void> {
-  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<{ id: string; type: string; payload: string }>(
-    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<Record<string, unknown>>(
-        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()` } },
-  );
-}