@cosmicdrift/kumiko-samples 0.367.0 → 0.369.0

package/packages/bundled-features/src/file-foundation/feature.ts

@@ -37,36 +37,45 @@ export {
 
 const FEATURE_NAME = "file-foundation";
 
-export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
-  r.describe(
-    "Defines the `fileProvider` extension point and a per-tenant `provider` config key that selects which registered storage plugin to use at runtime. Call `createFileProviderForTenant(ctx, tenantId)` to get a `FileStorageProvider` — use this feature together with at least one `file-provider-*` feature; the `files` feature builds on top of it for tracked `FileRef` entities with GDPR hooks.",
-  );
-  r.uiHints({
-    displayLabel: "File Provider Foundation",
-    category: "storage",
-    recommended: false,
-  });
-  r.requires({ features: ["config"] });
+export function createFileFoundationFeature() {
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        "Defines the `fileProvider` extension point and a per-tenant `provider` config key that selects which registered storage plugin to use at runtime. Call `createFileProviderForTenant(ctx, tenantId)` to get a `FileStorageProvider` — use this feature together with at least one `file-provider-*` feature; the `files` feature builds on top of it for tracked `FileRef` entities with GDPR hooks.",
+      );
+      r.uiHints({
+        displayLabel: "File Provider Foundation",
+        category: "storage",
+        recommended: false,
+      });
+      r.requires({ features: ["config"] });
 
-  r.extendsRegistrar(EXT_FILE_PROVIDER, {
-    onRegister: () => {
-      // No side-effects at register-time — registry stores the usage,
-      // factory looks it up at request-time.
-    },
-  });
+      r.extendsRegistrar(EXT_FILE_PROVIDER, {
+        onRegister: () => {
+          // No side-effects at register-time — registry stores the usage,
+          // factory looks it up at request-time.
+        },
+      });
 
-  const providerConfigKey = r.config(
-    "provider",
-    createTenantConfig("text", {
-      default: "",
-      env: FILE_STORAGE_PROVIDER_ENV,
-      write: access.roles("TenantAdmin", "SystemAdmin"),
-      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
-    }),
+      const providerConfigKey = r.config(
+        "provider",
+        createTenantConfig("text", {
+          default: "",
+          env: FILE_STORAGE_PROVIDER_ENV,
+          write: access.roles("TenantAdmin", "SystemAdmin"),
+          read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+        }),
+      );
+      // Readiness gating: provider-plugins' required keys/secrets count only
+      // while their plugin is the one this key selects.
+      r.extensionSelector(EXT_FILE_PROVIDER, providerConfigKey);
+
+      return { providerConfigKey };
+    },
+    { dedupeOptions: {} },
   );
-  // Readiness gating: provider-plugins' required keys/secrets count only
-  // while their plugin is the one this key selects.
-  r.extensionSelector(EXT_FILE_PROVIDER, providerConfigKey);
+}
 
-  return { providerConfigKey };
-});
+/** @deprecated Use createFileFoundationFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const fileFoundationFeature = createFileFoundationFeature();

package/packages/bundled-features/src/file-foundation/index.ts

@@ -1,6 +1,7 @@
 // Public API of the file-foundation bundled-feature.
 
 export {
+  createFileFoundationFeature,
   createFileProviderForTenant,
   type FileProviderContext,
   type FileProviderPlugin,

package/packages/bundled-features/src/file-foundation/read-file-ref-content.ts

@@ -1,5 +1,5 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { isUuid, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createFileContext,

package/packages/bundled-features/src/file-provider-inmemory/feature.ts

@@ -58,27 +58,38 @@ export function clearStorage(tenantId: string): void {
 // =============================================================================
 // Feature-definition
 // =============================================================================
+export function createFileProviderInMemoryFeature() {
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        'Registers an in-process `"inmemory"` provider for `file-foundation` that stores file bytes per tenant in a module-level Map. Use `listKeys(tenantId)` and `clearStorage(tenantId)` in demo apps and tests; not for production (data is lost on restart and grows without bound).',
+      );
+      r.uiHints({
+        displayLabel: "File Provider · In-Memory",
+        category: "storage",
+        recommended: false,
+      });
+      // Kein requires auf "config" oder "secrets" — der
+      // In-Memory-Provider hat keine Config + kein Secret. Nur die
+      // file-foundation muss da sein (Plugin-extension-point).
+      r.requires({ features: ["file-foundation"] });
 
-export const fileProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
-  r.describe(
-    'Registers an in-process `"inmemory"` provider for `file-foundation` that stores file bytes per tenant in a module-level Map. Use `listKeys(tenantId)` and `clearStorage(tenantId)` in demo apps and tests; not for production (data is lost on restart and grows without bound).',
+      const plugin: FileProviderPlugin = {
+        build: async (
+          _ctx: FileProviderContext,
+          tenantId: string,
+        ): Promise<FileStorageProvider> => {
+          // Returns the per-tenant storage. Identity-stable across calls so
+          // accumulated state is kept.
+          return getOrCreateProviderForTenant(tenantId);
+        }, // @wrapper-known semantic-alias
+      };
+      r.useExtension("fileProvider", "inmemory", plugin);
+    },
+    { dedupeOptions: {} },
   );
-  r.uiHints({
-    displayLabel: "File Provider · In-Memory",
-    category: "storage",
-    recommended: false,
-  });
-  // Kein requires auf "config" oder "secrets" — der
-  // In-Memory-Provider hat keine Config + kein Secret. Nur die
-  // file-foundation muss da sein (Plugin-extension-point).
-  r.requires({ features: ["file-foundation"] });
+}
 
-  const plugin: FileProviderPlugin = {
-    build: async (_ctx: FileProviderContext, tenantId: string): Promise<FileStorageProvider> => {
-      // Returnt den per-tenant Storage. Identitätsstabil zwischen calls
-      // damit accumulated state erhalten bleibt.
-      return getOrCreateProviderForTenant(tenantId);
-    }, // @wrapper-known semantic-alias
-  };
-  r.useExtension("fileProvider", "inmemory", plugin);
-});
+/** @deprecated Use createFileProviderInMemoryFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const fileProviderInMemoryFeature = createFileProviderInMemoryFeature();

package/packages/bundled-features/src/file-provider-inmemory/index.ts

@@ -1,3 +1,8 @@
 // Public API of the file-provider-inmemory bundled-feature.
 
-export { clearStorage, fileProviderInMemoryFeature, listKeys } from "./feature.js";
+export {
+  clearStorage,
+  createFileProviderInMemoryFeature,
+  fileProviderInMemoryFeature,
+  listKeys,
+} from "./feature.js";

package/packages/bundled-features/src/file-provider-s3/changes.json

@@ -1 +1,10 @@
-[]
+[
+  {
+    "version": "0.368.0",
+    "type": "breaking",
+    "title": "The S3 file providers merge into createFileProviderS3Feature({ fromEnv })",
+    "detail": "createFileProviderS3Feature() mounts the per-tenant config provider as before. createFileProviderS3Feature({ fromEnv: true }) mounts the env-configured provider (feature name, provider key \"s3-env\" and requires unchanged). The S3 client helpers (createS3Provider, createS3ProviderFromEnv, parseS3EnvConfig, resolveForcePathStyle, S3ProviderConfig) move to the new subpath @cosmicdrift/kumiko-bundled-features/file-provider-s3/lib.\n\nThe subpaths file-provider-s3-env and files-provider-s3 keep working as deprecated re-exports and are removed in the first release after 2026-10-29.\n\nold -> new:\n  fileProviderS3EnvFeature from .../file-provider-s3-env -> createFileProviderS3Feature({ fromEnv: true }) from .../file-provider-s3\n  fileProviderS3Feature -> createFileProviderS3Feature()\n  @cosmicdrift/kumiko-bundled-features/files-provider-s3 -> @cosmicdrift/kumiko-bundled-features/file-provider-s3/lib",
+    "migration": "Run `bun kumiko-upgrade --apply`. It rewrites the imports and the env feature mount, and reports `typeof fileProviderS3EnvFeature` and re-exports of it with file and line.",
+    "codemod": "scripts/codemod/s3-imports.ts"
+  }
+]

package/packages/bundled-features/src/file-provider-s3/env-feature.ts

@@ -0,0 +1,62 @@
+// file-provider-s3-env — S3 file provider configured entirely from
+// process.env. ONE shared bucket for ALL tenants: wire it by setting the
+// `S3_*` env vars + mounting — no per-tenant admin seeding and no
+// `secrets`-feature dependency.
+//
+// **vs the default file-provider-s3:** the config-based `"s3"` provider owns per-tenant
+// config keys + an encrypted `s3.secretAccessKey` secret (per-tenant
+// buckets, admin-seeded). This `"s3-env"` provider reads one credential set
+// from env and serves every tenant from one bucket — the
+// Hetzner-Object-Storage / single-bucket deploy case. Tenant isolation
+// still holds: file keys carry the tenant (export ZIPs:
+// `exports/<tenantId>/<jobId>.zip`) or are globally-unique UUIDs (fileRefs).
+//
+// **Pattern-Vorbild:** mirrors file-provider-inmemory (zero admin seeding,
+// only the file-foundation plugin-point required).
+//
+// **Env vars** (read by createS3ProviderFromEnv, prefix `S3_`):
+//   required — S3_BUCKET, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY
+//   optional — S3_ENDPOINT (S3-compat stores incl. Hetzner Object Storage),
+//              S3_FORCE_PATH_STYLE
+// Missing required vars throw on the FIRST file op (inside the export cron).
+// The user-data-rights boot guard surfaces that at boot instead.
+
+import type {
+  FileProviderContext,
+  FileProviderPlugin,
+} from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
+import { createS3ProviderFromEnv } from "./lib/env-helper.js";
+
+const FEATURE_NAME = "file-provider-s3-env";
+
+export function createFileProviderS3EnvFeature() {
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        'Registers an `"s3-env"` provider for `file-foundation` that reads one S3 credential set from `process.env` (`S3_BUCKET`/`S3_REGION`/`S3_ACCESS_KEY`/`S3_SECRET_KEY`, optional `S3_ENDPOINT`/`S3_FORCE_PATH_STYLE`) and serves every tenant from one shared bucket — no per-tenant config or secret seeding. Use this for single-bucket S3-compatible deploys (e.g. Hetzner Object Storage); use `file-provider-s3` instead when each tenant needs its own bucket/credentials.',
+      );
+      r.uiHints({
+        displayLabel: "File Provider · S3 (env)",
+        category: "storage",
+        recommended: false,
+      });
+      // No requires on "config" or "secrets" — credentials come from
+      // env, not the per-tenant config + secrets store. Only the file-foundation
+      // plugin-extension-point must be mounted.
+      r.requires({ features: ["file-foundation"] });
+
+      const plugin: FileProviderPlugin = {
+        // tenantId ignored: one shared bucket serves all tenants (isolation via
+        // tenant-prefixed / UUID keys). Built fresh per call like file-provider-s3;
+        // the S3 client opens no connection at construction.
+        build: async (_ctx: FileProviderContext, _tenantId: string): Promise<FileStorageProvider> =>
+          createS3ProviderFromEnv(), // @wrapper-known semantic-alias
+      };
+      r.useExtension("fileProvider", "s3-env", plugin);
+    },
+    { dedupeOptions: {} },
+  );
+}

package/packages/bundled-features/src/file-provider-s3/feature.ts

@@ -11,7 +11,7 @@
 //      { build })`. file-foundation's Factory findet den Plugin via
 //      registry.
 //   3. build(ctx, tenantId) liest config + secret, ruft `createS3Provider`
-//      aus files-provider-s3 auf. Der EINZIGE Cross-Feature-Import
+//      aus ./lib auf. Der EINZIGE Cross-Feature-Import
 //      des Plugins — bewusst lokal gehalten.
 //
 // **Pattern-Vorbild:** mirrors mail-transport-smtp.
@@ -22,7 +22,6 @@ import type {
   FileProviderContext,
   FileProviderPlugin,
 } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
-import { createS3Provider } from "@cosmicdrift/kumiko-bundled-features/files-provider-s3";
 import {
   requireDefined,
   requireNonEmpty,
@@ -31,85 +30,120 @@ import {
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
+import { createFileProviderS3EnvFeature } from "./env-feature.js";
+import { createS3Provider } from "./lib/s3-provider.js";
 
 const FEATURE_NAME = "file-provider-s3";
 
 // =============================================================================
 // Feature-definition
 // =============================================================================
+function createTenantConfigFileProviderS3Feature() {
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        'Registers itself as the `"s3"` provider for `file-foundation` and owns the per-tenant config keys (`bucket`, `region`, `endpoint`, `forcePathStyle`, `accessKeyId`) and the encrypted `s3.secretAccessKey` secret. Compatible with any S3-compatible object store (AWS S3, Hetzner Object Storage); set credentials via the admin UI or a seed handler before the first file operation.',
+      );
+      r.uiHints({
+        displayLabel: "File Provider · S3",
+        category: "storage",
+        recommended: false,
+      });
+      r.requires({ features: ["config"] });
+      r.requires({ features: ["secrets"] });
+      r.requires({ features: ["file-foundation"] });
 
-export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
-  r.describe(
-    'Registers itself as the `"s3"` provider for `file-foundation` and owns the per-tenant config keys (`bucket`, `region`, `endpoint`, `forcePathStyle`, `accessKeyId`) and the encrypted `s3.secretAccessKey` secret. Compatible with any S3-compatible object store (AWS S3, Hetzner Object Storage); set credentials via the admin UI or a seed handler before the first file operation.',
-  );
-  r.uiHints({
-    displayLabel: "File Provider · S3",
-    category: "storage",
-    recommended: false,
-  });
-  r.requires({ features: ["config"] });
-  r.requires({ features: ["secrets"] });
-  r.requires({ features: ["file-foundation"] });
-
-  const secretAccessKey = r.secret("s3.secretAccessKey", {
-    label: { en: "S3 secret access key" },
-    hint: {
-      en: "Private half of the S3 key pair. Hetzner calls it 'Secret Key', AWS calls it 'Secret Access Key'.",
-    },
-    redact: (plaintext) => {
-      if (plaintext.length < 8) return "•".repeat(plaintext.length);
-      return `${plaintext.slice(0, 4)}...${plaintext.slice(-4)}`;
-    },
-    scope: "tenant",
-    // required: true ↔ the missing-secret throw in readSecretAccessKey — keep in sync.
-    required: true,
-  });
-
-  // required: true ↔ the requireNonEmpty calls in buildS3Provider — keep in sync.
-  const configKeys = r.config({
-    keys: {
-      bucket: createTenantConfig("text", {
-        required: true,
-        default: "",
-        write: access.roles("TenantAdmin", "SystemAdmin"),
-        read: access.roles("TenantAdmin", "SystemAdmin"),
-      }),
-      region: createTenantConfig("text", {
-        required: true,
-        default: "",
-        write: access.roles("TenantAdmin", "SystemAdmin"),
-        read: access.roles("TenantAdmin", "SystemAdmin"),
-      }),
-      endpoint: createTenantConfig("text", {
-        default: "",
-        write: access.roles("TenantAdmin", "SystemAdmin"),
-        read: access.roles("TenantAdmin", "SystemAdmin"),
-      }),
-      forcePathStyle: createTenantConfig("boolean", {
-        default: false,
-        write: access.roles("TenantAdmin", "SystemAdmin"),
-      }),
-      accessKeyId: createTenantConfig("text", {
+      const secretAccessKey = r.secret("s3.secretAccessKey", {
+        label: { en: "S3 secret access key" },
+        hint: {
+          en: "Private half of the S3 key pair. Hetzner calls it 'Secret Key', AWS calls it 'Secret Access Key'.",
+        },
+        redact: (plaintext) => {
+          if (plaintext.length < 8) return "•".repeat(plaintext.length);
+          return `${plaintext.slice(0, 4)}...${plaintext.slice(-4)}`;
+        },
+        scope: "tenant",
+        // required: true ↔ the missing-secret throw in readSecretAccessKey — keep in sync.
         required: true,
-        default: "",
-        write: access.roles("TenantAdmin", "SystemAdmin"),
-        read: access.roles("TenantAdmin", "SystemAdmin"),
-      }),
+      });
+
+      // required: true ↔ the requireNonEmpty calls in buildS3Provider — keep in sync.
+      const configKeys = r.config({
+        keys: {
+          bucket: createTenantConfig("text", {
+            required: true,
+            default: "",
+            write: access.roles("TenantAdmin", "SystemAdmin"),
+            read: access.roles("TenantAdmin", "SystemAdmin"),
+          }),
+          region: createTenantConfig("text", {
+            required: true,
+            default: "",
+            write: access.roles("TenantAdmin", "SystemAdmin"),
+            read: access.roles("TenantAdmin", "SystemAdmin"),
+          }),
+          endpoint: createTenantConfig("text", {
+            default: "",
+            write: access.roles("TenantAdmin", "SystemAdmin"),
+            read: access.roles("TenantAdmin", "SystemAdmin"),
+          }),
+          forcePathStyle: createTenantConfig("boolean", {
+            default: false,
+            write: access.roles("TenantAdmin", "SystemAdmin"),
+          }),
+          accessKeyId: createTenantConfig("text", {
+            required: true,
+            default: "",
+            write: access.roles("TenantAdmin", "SystemAdmin"),
+            read: access.roles("TenantAdmin", "SystemAdmin"),
+          }),
+        },
+      });
+
+      // Plugin-Registration. entityName "s3" ist was tenants in
+      // file-foundation's `provider` config-key setzen.
+      const plugin: FileProviderPlugin = {
+        build: async (ctx: FileProviderContext, tenantId: string) => buildS3Provider(ctx, tenantId), // @wrapper-known semantic-alias
+      };
+      r.useExtension("fileProvider", "s3", plugin);
+
+      return { configKeys, secretAccessKey };
     },
-  });
+    { dedupeOptions: {} },
+  );
+}
+
+export type FileProviderS3FeatureOptions = {
+  /** Read one shared credential set from the `S3_*` env vars (provider key "s3-env", feature name "file-provider-s3-env") instead of per-tenant config and secret. */
+  readonly fromEnv?: boolean;
+};
+
+export function createFileProviderS3Feature(options: {
+  readonly fromEnv: true;
+}): ReturnType<typeof createFileProviderS3EnvFeature>;
+export function createFileProviderS3Feature(options?: {
+  readonly fromEnv?: false;
+}): ReturnType<typeof createTenantConfigFileProviderS3Feature>;
+export function createFileProviderS3Feature(
+  options: FileProviderS3FeatureOptions,
+):
+  | ReturnType<typeof createFileProviderS3EnvFeature>
+  | ReturnType<typeof createTenantConfigFileProviderS3Feature>;
+export function createFileProviderS3Feature(options: FileProviderS3FeatureOptions = {}) {
+  return options.fromEnv === true
+    ? createFileProviderS3EnvFeature()
+    : createTenantConfigFileProviderS3Feature();
+}
 
-  // Plugin-Registration. entityName "s3" ist was tenants in
-  // file-foundation's `provider` config-key setzen.
-  const plugin: FileProviderPlugin = {
-    build: async (ctx: FileProviderContext, tenantId: string) => buildS3Provider(ctx, tenantId), // @wrapper-known semantic-alias
-  };
-  r.useExtension("fileProvider", "s3", plugin);
+/** @deprecated Use createFileProviderS3Feature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const fileProviderS3Feature = createFileProviderS3Feature();
 
-  return { configKeys, secretAccessKey };
-});
+// Typed config/secret handles are identical across instances, so one module-level instance serves them.
+const tenantConfigFeature = createTenantConfigFileProviderS3Feature();
 
 /** Typed handle for the S3 secret-access-key. */
-export const S3_SECRET_ACCESS_KEY = fileProviderS3Feature.exports.secretAccessKey;
+export const S3_SECRET_ACCESS_KEY = tenantConfigFeature.exports.secretAccessKey;
 
 // =============================================================================
 // Internal: build the FileStorageProvider from tenant config + secret
@@ -128,30 +162,30 @@ async function buildS3Provider(
 
   const FILE_HINT = "Set via tenant-admin UI or seed-handler before reading or writing files.";
   const bucket = requireNonEmpty(
-    await ctxConfig(fileProviderS3Feature.exports.configKeys.bucket),
+    await ctxConfig(tenantConfigFeature.exports.configKeys.bucket),
     FEATURE_NAME,
     "bucket",
     FILE_HINT,
   );
   const region = requireNonEmpty(
-    await ctxConfig(fileProviderS3Feature.exports.configKeys.region),
+    await ctxConfig(tenantConfigFeature.exports.configKeys.region),
     FEATURE_NAME,
     "region",
     FILE_HINT,
   );
   const endpointRaw = requireDefined(
-    await ctxConfig(fileProviderS3Feature.exports.configKeys.endpoint),
+    await ctxConfig(tenantConfigFeature.exports.configKeys.endpoint),
     FEATURE_NAME,
     "endpoint",
   ) as string; // @cast-boundary engine-payload
   const endpoint = endpointRaw.length > 0 ? endpointRaw : undefined;
   const forcePathStyle = requireDefined(
-    await ctxConfig(fileProviderS3Feature.exports.configKeys.forcePathStyle),
+    await ctxConfig(tenantConfigFeature.exports.configKeys.forcePathStyle),
     FEATURE_NAME,
     "forcePathStyle",
   ) as boolean; // @cast-boundary engine-payload
   const accessKeyId = requireNonEmpty(
-    await ctxConfig(fileProviderS3Feature.exports.configKeys.accessKeyId),
+    await ctxConfig(tenantConfigFeature.exports.configKeys.accessKeyId),
     FEATURE_NAME,
     "accessKeyId",
     FILE_HINT,

package/packages/bundled-features/src/file-provider-s3/index.ts

@@ -1,3 +1,8 @@
 // Public API of the file-provider-s3 bundled-feature.
 
-export { fileProviderS3Feature, S3_SECRET_ACCESS_KEY } from "./feature.js";
+export {
+  createFileProviderS3Feature,
+  type FileProviderS3FeatureOptions,
+  fileProviderS3Feature,
+  S3_SECRET_ACCESS_KEY,
+} from "./feature.js";

package/packages/bundled-features/src/file-provider-s3/lib/index.ts

@@ -0,0 +1,3 @@
+export { createS3ProviderFromEnv, parseS3EnvConfig } from "./env-helper.js";
+export type { S3ProviderConfig } from "./s3-provider.js";
+export { createS3Provider, resolveForcePathStyle } from "./s3-provider.js";

package/packages/bundled-features/src/{files-provider-s3 → file-provider-s3/lib}/s3-provider.ts

@@ -8,12 +8,12 @@ import {
 // Operator-Pflicht-Setup (Multipart-Upload-Cleanup)
 // =============================================================================
 //
-// `writeStream` nutzt Bun's S3-Writer fuer echtes multipart-streaming. S3
-// created dabei eine Multipart-Upload-Session mit einer Upload-ID; bei
-// normaler Completion wird sie geschlossen. Wird der Export-Worker mid-write
-// gecancelt (Pod-Restart, K8s-OOM-Kill, Process-Signal), bleibt die Session
-// in S3 OFFEN und berechnet Storage-Kosten fuer die bereits hochgeladenen
-// Parts — bis sie via Lifecycle-Rule abgebrochen werden.
+// `writeStream` uses Bun's S3 writer for real multipart streaming. S3
+// creates a multipart-upload session with an upload ID for it; on normal
+// completion the session is closed. If the export worker is cancelled
+// mid-write (pod restart, K8s OOM kill, process signal), the session stays
+// OPEN in S3 and bills storage for the parts already uploaded — until a
+// lifecycle rule aborts it.
 //
 // **Pflicht-Operator-Setup auf jedem Bucket:**
 //
@@ -26,9 +26,9 @@ import {
 //     }]
 //   }
 //
-// AWS-CLI: `aws s3api put-bucket-lifecycle-configuration --bucket <name>
-// --lifecycle-configuration file://lifecycle.json`. Hetzner Object Storage
-// + R2 + Minio supporten dieselbe Syntax.
+// AWS CLI: `aws s3api put-bucket-lifecycle-configuration --bucket <name>
+// --lifecycle-configuration file://lifecycle.json`. Hetzner Object Storage,
+// R2 and Minio support the same syntax.
 //
 // =============================================================================
 // Operator-Pflicht-Setup (IAM: list permission)
@@ -117,11 +117,11 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
 
     async writeStream(key, source, options): Promise<void> {
       assertSafeStorageKey(key);
-      // Echtes multipart-streaming via Bun's S3-Writer — partSize steuert die
-      // Part-Boundary intern (AWS/R2 verlangen non-final Parts >= 5 MiB,
-      // sonst EntityTooSmall beim CompleteMultipartUpload). Manuelles flush()
-      // hier wuerde genau diese Garantie brechen, sobald die Source-Chunks
-      // nicht auf partSize aufgehen.
+      // Real multipart streaming via Bun's S3 writer — partSize controls the
+      // part boundary internally (AWS/R2 require non-final parts >= 5 MiB,
+      // otherwise EntityTooSmall on CompleteMultipartUpload). A manual flush()
+      // here would break exactly that guarantee as soon as the source chunks
+      // do not line up with partSize.
       const writer = client.file(key).writer({
         ...(options?.mimeType !== undefined && { type: options.mimeType }),
         retry: 3,
@@ -129,8 +129,8 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
         partSize: STREAM_PART_SIZE,
       });
       for await (const chunk of source) {
-        // Await applies Backpressure und bounded die in-flight Queue auf
-        // queueSize, statt unbegrenzt zu puffern.
+        // Await applies backpressure and bounds the in-flight queue to
+        // queueSize instead of buffering without limit.
         await writer.write(chunk);
       }
       await writer.end();
@@ -143,9 +143,9 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
 
     readStream(key): AsyncIterable<Uint8Array> {
       assertSafeStorageKey(key);
-      // Lazy: erst beim ersten chunk-pull wird der GET-Request abgesetzt.
-      // Existiert der Key nicht, faellt der Error genau dort (nicht beim
-      // readStream-Aufruf) — gleiches Lazy-Verhalten wie inmemory + local.
+      // Lazy: the GET request is only sent on the first chunk pull. If the key
+      // does not exist, the error surfaces right there (not on the readStream
+      // call) — same lazy behavior as inmemory + local.
       return {
         async *[Symbol.asyncIterator]() {
           for await (const chunk of client.file(key).stream()) {

package/packages/bundled-features/src/file-provider-s3-env/index.ts

@@ -1,3 +1,8 @@
-// Public API of the file-provider-s3-env bundled-feature.
+import { createFileProviderS3Feature } from "../file-provider-s3/index.js";
 
-export { fileProviderS3EnvFeature } from "./feature.js";
+/**
+ * @deprecated Use createFileProviderS3Feature({ fromEnv: true }) from
+ * `@cosmicdrift/kumiko-bundled-features/file-provider-s3`. Run `bun kumiko-upgrade --apply`.
+ * Removed in the first release after 2026-10-29.
+ */
+export const fileProviderS3EnvFeature = createFileProviderS3Feature({ fromEnv: true });

package/packages/bundled-features/src/files-provider-s3/index.ts

@@ -1,3 +1,11 @@
-export { createS3ProviderFromEnv, parseS3EnvConfig } from "./env-helper.js";
-export type { S3ProviderConfig } from "./s3-provider.js";
-export { createS3Provider, resolveForcePathStyle } from "./s3-provider.js";
+/**
+ * @deprecated Moved to `@cosmicdrift/kumiko-bundled-features/file-provider-s3/lib`. Run `bun kumiko-upgrade --apply`
+ * to rewrite imports. Removed in the first release after 2026-10-29.
+ */
+export {
+  createS3Provider,
+  createS3ProviderFromEnv,
+  parseS3EnvConfig,
+  resolveForcePathStyle,
+  type S3ProviderConfig,
+} from "../file-provider-s3/lib/index.js";

package/packages/bundled-features/src/files-tenant-data/handlers/sweep-orphaned-derivatives.job.ts

@@ -18,8 +18,8 @@
 // candidates into a flat queue so the shared deadline/circuit-breaker/signal
 // handling still applies per-key.
 
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { parseDerivativeKey } from "@cosmicdrift/kumiko-framework/derivatives";
 import type { JobContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {

package/packages/bundled-features/src/files-tenant-data/hooks.ts

@@ -46,8 +46,7 @@
 //     its original. Batched: one existence query per chunk of listed keys,
 //     not one query per key.
 
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
   parseTenantId,