@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/feature-toggles/compose-tier-resolver.ts

@@ -0,0 +1,134 @@
+import {
+  type EffectiveFeaturesResolver,
+  isToggleableFeature,
+  type Registry,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { GlobalFeatureToggleRuntime } from "./toggle-runtime";
+
+// Composes a tenantTierResolver (tier-engine) with a GlobalFeatureToggleRuntime
+// (feature-toggles) into a single resolver an app can pass as
+// runProdApp/runDevApp's `effectiveFeatures`.
+//
+// The framework only auto-wires ONE tenantTierResolver plugin (single-plugin
+// assumption, see tier-resolver-extension.ts) — an app running BOTH
+// tier-engine (per-tenant feature cuts) and feature-toggles (global runtime
+// switches, e.g. an operator kill-switch not tied to any tier) needs to
+// combine them itself. This is that combination, factored out here instead
+// of duplicated per app.
+//
+// Two disjoint classes of toggleable feature exist once both are mounted:
+//   - tier-managed (e.g. a Team-tier perk like personal-access-tokens): the
+//     TIER decides membership, not the feature's own default — a toggleable
+//     feature with no override row must stay governed by its tier, or every
+//     tier-gated toggleable would silently leak/vanish the moment
+//     feature-toggles is composed in. The global layer may only NARROW this
+//     (`enabled: false` removes it; no row / `true` leaves the tier's grant
+//     untouched).
+//   - tier-unaware (e.g. a pure operator kill-switch with no tier
+//     differentiation at all, such as auth-self-registration): no tier's
+//     `features` list ever mentions it, so it would never appear in ANY
+//     tenant's tier-set — narrowing alone can only remove features, never
+//     grant this one. Its membership must come from computeEffectiveFeatures'
+//     normal cascade (override ?? toggleableDefault) instead.
+//
+// `tierResolver(SYSTEM_TENANT_ID)` is tier-engine's documented convention for
+// "union of every tier's features" (operator-tooling/async-dispatch
+// convention) — used here purely to classify which toggleable names are
+// tier-managed, without needing the app's TierMap as a separate parameter.
+export function composeTierResolverWithGlobalToggles(
+  tierResolver: EffectiveFeaturesResolver,
+  toggleRuntime: GlobalFeatureToggleRuntime,
+  // registry needed for toggleability lookups; toggleRuntime keeps its own registry reference private.
+  registry: Registry,
+): EffectiveFeaturesResolver {
+  // Lazy + memoized: computed on first composed(tenantId) call, not at
+  // compose-time. Late-bound holder wiring (e.g. run-dev-app.ts's tier
+  // resolver plugin) may not have its real tierResolver built yet when
+  // composeTierResolverWithGlobalToggles itself runs.
+  let tierManaged: ReadonlySet<string> | undefined;
+
+  const composed: EffectiveFeaturesResolver = (tenantId) => {
+    if (tierManaged === undefined) {
+      const managed = tierResolver(SYSTEM_TENANT_ID);
+      // fail-loud: an empty union means the resolver doesn't implement the SYSTEM_TENANT_ID convention at all.
+      if (managed.size === 0) {
+        throw new Error(
+          "composeTierResolverWithGlobalToggles: tierResolver(SYSTEM_TENANT_ID) " +
+            "returned an empty set. tier-engine's SYSTEM_TENANT_ID convention " +
+            "(union of every tier's features, plus always-on features) must " +
+            "never be empty — an empty result means the tierResolver passed in " +
+            "doesn't implement that convention, which would silently disable " +
+            "all tier-gating (every feature would be treated as tier-unaware).",
+        );
+      }
+      // Structural Rule 1: only the TOGGLEABLE subset of the union is tier-managed.
+      // Non-toggleable (always-on) names must keep reaching `result` through the
+      // globalCascade loop below even if this resolver's SYSTEM_TENANT_ID answer
+      // satisfies the emptiness guard above without also merging always-on into
+      // every per-tenant tierSet (framework#1528).
+      tierManaged = new Set(
+        [...managed].filter((name) => {
+          const feature = registry.getFeature(name);
+          return feature !== undefined && isToggleableFeature(feature);
+        }),
+      );
+    }
+
+    const tierSet = tierResolver(tenantId);
+    const result = new Set<string>();
+    for (const name of tierSet) {
+      // Only a toggleable feature's override can narrow the tier's grant —
+      // computeEffectiveFeatures' Rule 1 ignores overrides for features
+      // without a toggleableDefault, and an override row can otherwise
+      // reach a non-toggleable feature via seed-scripts/ops-SQL/an
+      // r.toggleable() removal after the fact (readOverride/refresh() have
+      // no toggleability gate of their own).
+      const feature = registry.getFeature(name);
+      const isToggleable = feature !== undefined && isToggleableFeature(feature);
+      if (!isToggleable || toggleRuntime.readOverride(name) !== false) {
+        result.add(name);
+      }
+    }
+    // toggleRuntime.effectiveFeatures() already applies computeEffectiveFeatures'
+    // full rule set (toggleableDefault ?? override, THEN the requires() cascade)
+    // — reusing it here instead of calling computeEffectiveFeatures directly
+    // keeps this in lockstep with the runtime's own dispatcher-facing callback.
+    const globalCascade = toggleRuntime.effectiveFeatures();
+    for (const name of globalCascade) {
+      if (!tierManaged.has(name)) result.add(name);
+    }
+
+    // requires() cascade over the combined result: a feature narrowed off by
+    // either loop above (tier-managed override, or absent from both sets)
+    // must also drop anything that itself requires it — computeEffectiveFeatures
+    // enforces this for its own single reader, but tierSet's membership isn't
+    // reader-driven, so the cascade has to be re-applied over the union.
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const name of [...result]) {
+        const feature = registry.getFeature(name);
+        if (!feature) {
+          result.delete(name);
+          changed = true;
+          continue;
+        }
+        for (const dep of feature.requires) {
+          if (!result.has(dep)) {
+            result.delete(name);
+            changed = true;
+            break;
+          }
+        }
+      }
+    }
+
+    return result;
+  };
+
+  if (tierResolver.trialGate) {
+    return Object.assign(composed, { trialGate: tierResolver.trialGate });
+  }
+  return composed;
+}

package/src/feature-toggles/constants.ts

@@ -1,3 +1,6 @@
+// @runtime client
+export const FEATURE_TOGGLES_FEATURE = "feature-toggles" as const;
+
 // Fully-qualified event name for feature-toggle changes. Kept as a constant
 // so write-handler + tests reference one source.
 export const FEATURE_TOGGLE_SET_EVENT_NAME = "feature-toggles:event:toggle-set";
@@ -18,3 +21,14 @@ export const FeatureToggleErrors = {
   // Prevents typos from silently piling up orphan rows.
   unknownFeature: "unknown_feature",
 } as const;
+
+export const FeatureToggleHandlers = {
+  set: "feature-toggles:write:set",
+} as const;
+
+export const FeatureToggleQueries = {
+  list: "feature-toggles:query:list",
+  registered: "feature-toggles:query:registered",
+} as const;
+
+export const TOGGLE_ADMIN_SCREEN_ID = "toggle-admin" as const;

package/src/feature-toggles/feature.ts

@@ -1,9 +1,11 @@
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { FEATURE_TOGGLE_SET_EVENT_NAME } from "./constants";
+import { FEATURE_TOGGLE_SET_EVENT_NAME, TOGGLE_ADMIN_SCREEN_ID } from "./constants";
 import { featureToggleSetSchema } from "./events";
+import { globalFeatureStateTableMeta } from "./global-feature-state-table";
 import { listQuery } from "./handlers/list.query";
 import { registeredQuery } from "./handlers/registered.query";
 import { createSetWriteHandler } from "./handlers/set.write";
+import { FEATURE_TOGGLES_I18N } from "./i18n";
 import type { GlobalFeatureToggleRuntime } from "./toggle-runtime";
 
 // IMPORTANT: feature-toggles itself is NOT r.toggleable. Making it
@@ -38,7 +40,7 @@ export function createFeatureTogglesFeature(
 ): FeatureDefinition {
   return defineFeature("feature-toggles", (r) => {
     r.describe(
-      'Persists per-feature enabled/disabled state in the `read_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: "per-instance"` syncs the snapshot across instances whenever a `toggle-set` event is appended.',
+      'Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: "per-instance"` syncs the snapshot across instances whenever a `toggle-set` event is appended.',
     );
     r.uiHints({
       displayLabel: "Feature Toggles · Operator Switches",
@@ -46,6 +48,9 @@ export function createFeatureTogglesFeature(
       recommended: false,
     });
     r.systemScope();
+    r.storeTable(globalFeatureStateTableMeta, {
+      reason: "feature_toggles.global_override_snapshot",
+    });
 
     // Toggle-change domain event. The event ends up in the events-table
     // alongside every other write — audit.list picks it up automatically,
@@ -62,6 +67,21 @@ export function createFeatureTogglesFeature(
       registered: r.queryHandler(registeredQuery),
     };
 
+    r.screen({
+      id: TOGGLE_ADMIN_SCREEN_ID,
+      type: "custom",
+      renderer: { react: { __component: "ToggleAdminScreen" } },
+      access: { roles: ["SystemAdmin"] },
+    });
+    r.nav({
+      id: "toggle-admin",
+      label: "feature-toggles:nav.toggleAdmin",
+      screen: "feature-toggles:screen:toggle-admin",
+      order: 20,
+    });
+
+    r.translations({ keys: FEATURE_TOGGLES_I18N });
+
     // toggle-cache-sync — multi-instance snapshot propagation. Every
     // API/worker instance runs its own dispatcher cursor on this MSP
     // (delivery: "per-instance") and converges its in-memory snapshot on
@@ -111,7 +131,7 @@ export function createFeatureTogglesFeature(
 }
 
 export { FEATURE_TOGGLE_SET_EVENT_NAME, FeatureToggleErrors } from "./constants";
-export { globalFeatureStateTable } from "./global-feature-state-table";
+export { globalFeatureStateTable, globalFeatureStateTableMeta } from "./global-feature-state-table";
 // Re-export the runtime factory + class so app-boot code has a single
 // import path: "@cosmicdrift/kumiko-bundled-features/feature-toggles".
 export {

package/src/feature-toggles/global-feature-state-table.ts

@@ -1,5 +1,7 @@
+import { asEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   boolean,
+  type EntityTableMeta,
   instant,
   integer,
   table as pgTable,
@@ -15,7 +17,7 @@ import {
 // name IS the identity here. No tenantId: this is a global override that
 // applies across every tenant (per-tenant toggles are intentionally out of
 // scope, see core-feature-toggles.md).
-export const globalFeatureStateTable = pgTable("read_global_feature_state", {
+export const globalFeatureStateTable = pgTable("store_global_feature_state", {
   featureName: text("feature_name").primaryKey(),
   enabled: boolean("enabled").notNull(),
   // Optimistic-lock column. The set-handler reads the existing row, then
@@ -26,3 +28,20 @@ export const globalFeatureStateTable = pgTable("read_global_feature_state", {
   // UserId (text — SessionUser.id is a uuid string post-ES).
   updatedBy: text("updated_by"),
 });
+
+// r.storeTable meta — without this, collectTableMetas(FEATURES) never
+// sees the table, so `kumiko schema generate` reports no changes and no
+// app ever gets a migration for it (framework gap, not app-local). Derived
+// from the pgTable above instead of hand-written a second time — the two
+// used to drift independently (framework#1529): a column added only to
+// the pgTable made queries type-check while the migration generator stayed
+// blind to it, failing in prod with "column ... does not exist" while every
+// mocked-stack test stayed green.
+const derivedMeta = asEntityTableMeta(globalFeatureStateTable);
+if (!derivedMeta) {
+  throw new Error(
+    "global-feature-state-table: asEntityTableMeta(globalFeatureStateTable) returned undefined " +
+      "— the pgTable definition no longer round-trips through the unmanaged-table meta builder.",
+  );
+}
+export const globalFeatureStateTableMeta: EntityTableMeta = derivedMeta;

package/src/feature-toggles/handlers/list.query.ts

@@ -10,7 +10,7 @@ import { globalFeatureStateTable } from "../global-feature-state-table";
 export const listQuery = defineQueryHandler({
   name: "list",
   schema: z.object({}),
-  access: { roles: ["SystemAdmin", "Admin"] },
+  access: { roles: ["SystemAdmin"] },
   handler: async (_event, ctx) => {
     type Row = {
       featureName: string;

package/src/feature-toggles/handlers/registered.query.ts

@@ -14,7 +14,7 @@ import { globalFeatureStateTable } from "../global-feature-state-table";
 export const registeredQuery = defineQueryHandler({
   name: "registered",
   schema: z.object({}),
-  access: { roles: ["SystemAdmin", "Admin"] },
+  access: { roles: ["SystemAdmin"] },
   handler: async (_event, ctx) => {
     type OverrideRow = { featureName: string; enabled: boolean };
     const overrideRows = await selectMany<OverrideRow>(ctx.db.raw, globalFeatureStateTable);

package/src/feature-toggles/i18n.ts

@@ -0,0 +1,6 @@
+type LocalizedString = { readonly de: string; readonly en: string };
+
+export const FEATURE_TOGGLES_I18N: Readonly<Record<string, LocalizedString>> = {
+  "screen:toggle-admin.title": { de: "Feature-Toggles", en: "Feature toggles" },
+  "feature-toggles:nav.toggleAdmin": { de: "Feature-Toggles", en: "Feature toggles" },
+};

package/src/feature-toggles/index.ts

@@ -1,3 +1,10 @@
+export { composeTierResolverWithGlobalToggles } from "./compose-tier-resolver";
+export {
+  FEATURE_TOGGLES_FEATURE,
+  FeatureToggleHandlers,
+  FeatureToggleQueries,
+  TOGGLE_ADMIN_SCREEN_ID,
+} from "./constants";
 export {
   createFeatureToggleRuntime,
   createFeatureTogglesFeature,
@@ -6,4 +13,5 @@ export {
   type FeatureTogglesOptions,
   GlobalFeatureToggleRuntime,
   globalFeatureStateTable,
+  globalFeatureStateTableMeta,
 } from "./feature";

package/src/feature-toggles/toggle-runtime.ts

@@ -47,6 +47,20 @@ export class GlobalFeatureToggleRuntime {
     this.snapshot.set(featureName, enabled);
   }
 
+  // Raw per-feature override, bypassing the requires() cascade —
+  // `undefined` means "no explicit row, inherits toggleableDefault"
+  // (distinct from an explicit `false`). Used by composeTierResolver to
+  // layer a global kill-switch UNDER a tenantTierResolver: the composed
+  // resolver must only ever narrow what the tier already grants, never
+  // fall back to a toggleable feature's declared default the way
+  // effectiveFeatures()/computeEffectiveFeatures do — that default exists
+  // for apps with no tier resolver, and would otherwise turn tier-gated
+  // toggleable features (e.g. a Team-tier feature defaulting off) globally
+  // off the moment feature-toggles is composed in.
+  readOverride(featureName: string): boolean | undefined {
+    return this.snapshot.get(featureName);
+  }
+
   // The callback shape the dispatcher expects. Computes the effective
   // feature set from the current snapshot + the registry's requires()
   // cascade every call. Cheap: the cascade is a DFS over O(features);

package/src/feature-toggles/web/client-plugin.tsx

@@ -0,0 +1,22 @@
+// @runtime client
+import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { FEATURE_TOGGLES_FEATURE, TOGGLE_ADMIN_SCREEN_ID } from "../constants";
+import { defaultTranslations } from "./i18n";
+import { ToggleAdminScreen } from "./toggle-admin-screen";
+
+export type FeatureTogglesClientOptions = {
+  readonly translations?: TranslationsByLocale;
+};
+
+export function featureTogglesClient(
+  options?: FeatureTogglesClientOptions,
+): ClientFeatureDefinition {
+  return {
+    name: FEATURE_TOGGLES_FEATURE,
+    translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
+    components: {
+      [TOGGLE_ADMIN_SCREEN_ID]: ToggleAdminScreen,
+    },
+  };
+}

package/src/feature-toggles/web/i18n.ts

@@ -0,0 +1,29 @@
+// @runtime client
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  de: {
+    "feature-toggles.admin.title": "Feature-Toggles",
+    "feature-toggles.admin.loading": "Lade Feature-Toggles…",
+    "feature-toggles.admin.col.feature": "Feature",
+    "feature-toggles.admin.col.default": "Default",
+    "feature-toggles.admin.col.override": "Override",
+    "feature-toggles.admin.col.effective": "Effektiv",
+    "feature-toggles.admin.toggle": "Umschalten",
+    "feature-toggles.admin.saving": "Speichert…",
+    "feature-toggles.admin.alwaysOn": "immer an",
+    "feature-toggles:nav.toggleAdmin": "Feature-Toggles",
+  },
+  en: {
+    "feature-toggles.admin.title": "Feature toggles",
+    "feature-toggles.admin.loading": "Loading feature toggles…",
+    "feature-toggles.admin.col.feature": "Feature",
+    "feature-toggles.admin.col.default": "Default",
+    "feature-toggles.admin.col.override": "Override",
+    "feature-toggles.admin.col.effective": "Effective",
+    "feature-toggles.admin.toggle": "Toggle",
+    "feature-toggles.admin.saving": "Saving…",
+    "feature-toggles.admin.alwaysOn": "always on",
+    "feature-toggles:nav.toggleAdmin": "Feature toggles",
+  },
+};

package/src/feature-toggles/web/index.ts

@@ -0,0 +1,6 @@
+// @runtime client
+export {
+  type FeatureTogglesClientOptions,
+  featureTogglesClient,
+} from "./client-plugin";
+export { ToggleAdminScreen } from "./toggle-admin-screen";

package/src/feature-toggles/web/toggle-admin-screen.tsx

@@ -0,0 +1,136 @@
+// @runtime client
+import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { FormScreenShell } from "@cosmicdrift/kumiko-renderer-web";
+import { type ReactNode, useCallback, useEffect, useState } from "react";
+import { FeatureToggleHandlers, FeatureToggleQueries } from "../constants";
+
+type ToggleRow = {
+  readonly name: string;
+  readonly toggleable: boolean;
+  readonly default: boolean | null;
+  readonly override: boolean | null;
+  readonly effective: boolean | null;
+};
+
+type RegisteredResponse = {
+  readonly items: readonly ToggleRow[];
+};
+
+type State =
+  | { readonly kind: "loading" }
+  | { readonly kind: "error"; readonly message: string }
+  | { readonly kind: "ready"; readonly items: readonly ToggleRow[] };
+
+export function ToggleAdminScreen(): ReactNode {
+  const t = useTranslation();
+  const { Banner, Card, DataTable, Heading, Text } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const [state, setState] = useState<State>({ kind: "loading" });
+  const [actionError, setActionError] = useState<string | null>(null);
+
+  const load = useCallback(async (): Promise<void> => {
+    setState({ kind: "loading" });
+    const res = await dispatcher.query<RegisteredResponse>(FeatureToggleQueries.registered, {});
+    if (!res.isSuccess) {
+      setState({ kind: "error", message: res.error.message });
+      return;
+    }
+    setState({ kind: "ready", items: res.data.items });
+  }, [dispatcher]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const onSet = async (featureName: string, enabled: boolean): Promise<void> => {
+    setActionError(null);
+    const res = await dispatcher.write(FeatureToggleHandlers.set, { featureName, enabled });
+    if (!res.isSuccess) {
+      setActionError(res.error.message);
+      return;
+    }
+    await load();
+  };
+
+  if (state.kind === "loading") {
+    return (
+      <FormScreenShell testId="toggle-admin-screen">
+        <Text variant="small">{t("feature-toggles.admin.loading")}</Text>
+      </FormScreenShell>
+    );
+  }
+
+  if (state.kind === "error") {
+    return (
+      <FormScreenShell testId="toggle-admin-screen">
+        <Banner variant="error">{state.message}</Banner>
+      </FormScreenShell>
+    );
+  }
+
+  return (
+    <FormScreenShell testId="toggle-admin-screen" maxWidth="4xl" className="flex flex-col gap-6">
+      <Heading variant="page">{t("feature-toggles.admin.title")}</Heading>
+
+      {actionError !== null && <Banner variant="error">{actionError}</Banner>}
+
+      <Card options={{ padded: false }}>
+        <DataTable
+          testId="toggle-admin-table"
+          columns={[
+            {
+              field: "feature",
+              label: t("feature-toggles.admin.col.feature"),
+              type: "string",
+              sortable: false,
+            },
+            {
+              field: "default",
+              label: t("feature-toggles.admin.col.default"),
+              type: "string",
+              sortable: false,
+            },
+            {
+              field: "override",
+              label: t("feature-toggles.admin.col.override"),
+              type: "string",
+              sortable: false,
+            },
+            {
+              field: "effective",
+              label: t("feature-toggles.admin.col.effective"),
+              type: "string",
+              sortable: false,
+            },
+          ]}
+          rows={state.items.map((row) => ({
+            id: row.name,
+            values: {
+              feature: row.name,
+              default: formatFlag(row.default),
+              override: formatFlag(row.override),
+              effective: formatFlag(row.effective),
+              toggleable: row.toggleable,
+              effectiveBool: row.effective ?? row.default ?? false,
+            },
+          }))}
+          rowActions={[
+            {
+              id: "toggle",
+              label: t("feature-toggles.admin.toggle"),
+              style: "secondary",
+              isVisible: (row) => row.values["toggleable"] === true,
+              onTrigger: (row) => void onSet(row.id, !(row.values["effectiveBool"] as boolean)),
+            },
+          ]}
+          rowActionMode="inline"
+        />
+      </Card>
+    </FormScreenShell>
+  );
+}
+
+function formatFlag(value: boolean | null): string {
+  if (value === null) return "inherit";
+  return value ? "on" : "off";
+}

package/src/file-foundation/__tests__/feature.test.ts

@@ -20,11 +20,11 @@ describe("fileFoundationFeature — shape", () => {
 });
 
 describe("fileFoundationFeature.exports — typed handles", () => {
-  test("exposes only the provider-selector config-key", () => {
-    const keys = fileFoundationFeature.exports.configKeys;
-    expect(keys.provider).toBeDefined();
-    expect((keys as Record<string, unknown>)["bucket"]).toBeUndefined();
-    expect((keys as Record<string, unknown>)["region"]).toBeUndefined();
+  test("exposes the provider-selector handle", () => {
+    expect(fileFoundationFeature.exports.providerConfigKey).toBeDefined();
+    expect(fileFoundationFeature.exports.providerConfigKey.name).toBe(
+      "file-foundation:config:provider",
+    );
   });
 });
 

package/src/file-foundation/__tests__/file-foundation.integration.test.ts

@@ -4,7 +4,7 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import { createEncryptionProvider, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
@@ -18,6 +18,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/stack";
 import {
   createMutableMasterKeyProvider,
+  createTestEnvelopeCipher,
   type MutableMasterKeyProvider,
 } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
@@ -73,8 +74,8 @@ let providerRef: MutableMasterKeyProvider;
 const testEncryptionKey = randomBytes(32).toString("base64");
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(testEncryptionKey);
-  resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(testEncryptionKey);
+  resolver = createConfigResolver({ cipher: encryption });
 
   const initialKp = createEnvMasterKeyProvider({
     env: {

package/src/file-foundation/feature.ts

@@ -54,18 +54,17 @@ export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
     },
   });
 
-  const configKeys = r.config({
-    keys: {
-      provider: createTenantConfig("text", {
-        default: "",
-        write: access.roles("TenantAdmin", "SystemAdmin"),
-        read: access.roles("TenantAdmin", "SystemAdmin", "User"),
-      }),
-    },
-  });
+  const providerConfigKey = r.config(
+    "provider",
+    createTenantConfig("text", {
+      default: "",
+      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, configKeys.provider);
+  r.extensionSelector(EXT_FILE_PROVIDER, providerConfigKey);
 
-  return { configKeys };
+  return { providerConfigKey };
 });

package/src/files-provider-s3/__tests__/s3-provider.integration.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
+import { describeFileProviderContract } from "@cosmicdrift/kumiko-framework/testing";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { createS3ProviderFromEnv } from "../env-helper";
 import { createS3Provider } from "../s3-provider";
@@ -28,13 +29,31 @@ function uniqueKey(suffix: string): string {
 
 let provider: FileStorageProvider;
 
-beforeAll(() => {
+beforeAll(async () => {
+  const endpoint = requireEnv("MINIO_ENDPOINT");
+  // Fail loud with an actionable message when Minio is down (otherwise
+  // S3 networking errors look like provider bugs).
+  try {
+    const health = await fetch(`${endpoint.replace(/\/$/, "")}/minio/health/live`, {
+      signal: AbortSignal.timeout(2000),
+    });
+    if (!health.ok) {
+      throw new Error(`HTTP ${health.status}`);
+    }
+  } catch (err) {
+    throw new Error(
+      `MinIO not reachable at ${endpoint} — run: docker compose up -d minio minio-init ` +
+        `(kumiko-framework compose, default port 19000). ` +
+        `Cause: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
   // forcePathStyle is deliberately NOT set — resolveForcePathStyle() must
   // auto-detect path-style from the `endpoint` presence. If auto-detection
   // regressed, Minio would reject virtual-host-style URLs (bucket.host/key)
   // and every round-trip below would fail. That's the proof.
   provider = createS3Provider({
-    endpoint: requireEnv("MINIO_ENDPOINT"),
+    endpoint,
     region: requireEnv("MINIO_REGION"),
     accessKeyId: requireEnv("MINIO_ACCESS_KEY"),
     secretAccessKey: requireEnv("MINIO_SECRET_KEY"),
@@ -201,3 +220,9 @@ describe("createS3ProviderFromEnv", () => {
     expect(() => createS3ProviderFromEnv("NON_EXISTENT_PREFIX_")).toThrow(/missing_env/);
   });
 });
+
+describeFileProviderContract("S3Provider (Minio)", () => provider);
+
+describeFileProviderContract("createS3ProviderFromEnv (Minio)", () =>
+  createS3ProviderFromEnv("MINIO_"),
+);