@cosmicdrift/kumiko-bundled-features 0.27.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.27.0",
+  "version": "0.31.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -22,6 +22,7 @@
     "./compliance-profiles": "./src/compliance-profiles/index.ts",
     "./config": "./src/config/index.ts",
     "./data-retention": "./src/data-retention/index.ts",
+    "./readiness": "./src/readiness/index.ts",
     "./jobs": "./src/jobs/index.ts",
     "./tier-engine": "./src/tier-engine/index.ts",
     "./cap-counter": "./src/cap-counter/index.ts",

package/src/audit/feature.ts

@@ -15,6 +15,9 @@ import { listQuery } from "./handlers/list.query";
 // the framework).
 export function createAuditFeature(): FeatureDefinition {
   return defineFeature("audit", (r) => {
+    r.describe(
+      "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range.",
+    );
     const queries = {
       list: r.queryHandler(listQuery),
     };

package/src/auth-email-password/feature.ts

@@ -125,6 +125,9 @@ export function createAuthEmailPasswordFeature(
     opts.emailVerification !== undefined && (opts.emailVerification.mode ?? "strict") === "strict";
 
   return defineFeature("auth-email-password", (r) => {
+    r.describe(
+      "Provides email+password authentication: the always-on handlers are `login`, `changePassword`, and `logout`; optional flows \u2014 password reset, email verification, magic-link self-signup, and tenant invite \u2014 are registered only when you pass their respective option objects (`passwordReset`, `emailVerification`, `signup`, `invite`) to `createAuthEmailPasswordFeature(opts)`. Each opt-in flow uses HMAC-signed or opaque-random tokens delivered via callback (e.g. `sendResetEmail`) so the feature stays transport-agnostic. Requires the `user` and `tenant` features, and declares `JWT_SECRET` (\u2265 32 chars) in `authEmailPasswordEnvSchema` so a missing secret surfaces at boot validation rather than on the first login attempt.",
+    );
     r.requires("user");
     r.requires("tenant");
     r.envSchema(authEmailPasswordEnvSchema);

package/src/auth-email-password/web/__tests__/tenant-switcher.test.tsx

@@ -31,6 +31,26 @@ describe("TenantSwitcher", () => {
     // tenantName-Resolver liefert "Tenant tenant-a" als Trigger-Label
     expect(screen.getByText("Tenant tenant-a")).toBeTruthy();
   });
+  test("renders server-provided membership name without tenantName prop", () => {
+    // /auth/tenants liefert name/key mit — der Switcher braucht keinen
+    // App-Resolver mehr. Fallback-Kette: name > key > UUID-Präfix.
+    const session = makeSessionApi({
+      activeTenantId: "00000000-0000-4000-8000-000000000001",
+      tenants: [
+        {
+          tenantId: "00000000-0000-4000-8000-000000000001",
+          roles: ["Admin"],
+          name: "Status",
+          key: "status",
+        },
+        { tenantId: "00000000-0000-4000-8000-000000000002", roles: ["Admin"], key: "demo" },
+      ],
+    });
+    renderWithProviders(<TenantSwitcher />, { session });
+    // Ohne den Fix wären beide Labels das identische UUID-Präfix "00000000".
+    expect(screen.getByText("Status")).toBeTruthy();
+  });
+
   test("opens dropdown showing all memberships with roles", async () => {
     const user = userEvent.setup();
     const session = makeSessionApi({

package/src/auth-email-password/web/auth-client.ts

@@ -14,6 +14,10 @@ import { CSRF_HEADER_NAME, readCsrfToken } from "@cosmicdrift/kumiko-dispatcher-
 export type TenantSummary = {
   readonly tenantId: string;
   readonly roles: readonly string[];
+  /** Display-Name aus /auth/tenants — fehlt nur bei App-eigenen
+   *  membership-Queries ohne tenantName-Anreicherung. */
+  readonly name?: string;
+  readonly key?: string;
 };
 
 export type LoginRequest = {

package/src/auth-email-password/web/tenant-switcher.tsx

@@ -57,8 +57,14 @@ export function TenantSwitcher({ tenantName }: TenantSwitcherProps): ReactNode {
     [activeTenantId, switchTenant],
   );
 
-  const nameOf = (tenantId: string): string =>
-    tenantName !== undefined ? tenantName(tenantId) : tenantId.slice(0, 8);
+  // Label-Priorität: App-eigener Resolver (Prop) > Server-geliefertes
+  // name/key aus /auth/tenants > UUID-Präfix. Letzteres ist nur noch der
+  // Notnagel — bei Seed-Tenants (00000000-…) ist es ununterscheidbar.
+  const nameOf = (tenantId: string): string => {
+    if (tenantName !== undefined) return tenantName(tenantId);
+    const membership = tenants.find((m) => m.tenantId === tenantId);
+    return membership?.name ?? membership?.key ?? tenantId.slice(0, 8);
+  };
 
   // Rendering-Gate: kein User → nix; nur ein Tenant → auch nix
   // (Single-Tenant-Apps brauchen keinen Switcher).

package/src/billing-foundation/feature.ts

@@ -71,6 +71,9 @@ import {
 } from "./projection";
 
 export const billingFoundationFeature = defineFeature(BILLING_FOUNDATION_FEATURE, (r) => {
+  r.describe(
+    "Plugin host for subscription billing \u2014 manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookHandler` factory for the `/api/subscription/webhook/:providerName` route. Low-level building block \u2014 use `subscription-stripe` or `subscription-mollie` unless you are writing a new payment provider.",
+  );
   // 5 fine-grained domain-events. Alle 5 nutzen denselben payload-
   // shape (= subscription-state-snapshot); der event-type taggt was
   // passiert ist. Future-consumer (billing-history, accounting)

package/src/billing-foundation/webhook-handler.ts

@@ -7,12 +7,20 @@
 // `/api/subscription/webhook/paypal`. Eine Hono-Route, alle Plugins
 // gleichzeitig aktiv.
 //
-// Beispiel-Verwendung in bin/server.ts:
+// Beispiel-Verwendung in bin/server.ts (runDevApp wie runProdApp liefern
+// `registry` + `dispatchSystemWrite` in den extraRoutes-deps):
 //
 //   await runDevApp({
 //     features: APP_FEATURES,
 //     extraRoutes: (app, deps) => {
-//       const handler = createSubscriptionWebhookHandler(deps);
+//       const handler = createSubscriptionWebhookHandler({
+//         dispatchWrite: ({ handlerQn, payload, tenantId }) =>
+//           deps.dispatchSystemWrite({ handlerQn, payload, tenantId: tenantId as TenantId }),
+//         resolveProvider: (name) =>
+//           deps.registry.getExtensionUsages("subscriptionProvider")
+//             .find((u) => u.entityName === name)?.options as
+//             SubscriptionProviderPlugin | undefined,
+//       });
 //       app.post("/api/subscription/webhook/:providerName", handler);
 //     },
 //   });
@@ -43,8 +51,9 @@ import {
 import type { SubscriptionProviderPlugin } from "./types";
 
 /**
- * Dependencies the App-Owner gibt dem webhook-handler. Identisch zum
- * `extraRoutes`-Callback-Argument-shape von runDevApp/runProdApp.
+ * Dependencies the App-Owner gibt dem webhook-handler — beide direkt aus
+ * den `extraRoutes`-deps ableitbar (`dispatchSystemWrite` + `registry`),
+ * siehe Beispiel im Header.
  */
 export type SubscriptionWebhookDeps = {
   /** Schreibt durch den Standard-Dispatcher mit einem auto-konstruierten

package/src/cap-counter/feature.ts

@@ -60,6 +60,9 @@ import { markSoftWarnedHandler } from "./handlers/mark-soft-warned.write";
 const sysadminAccess = { access: { roles: ["SystemAdmin"] } } as const;
 
 export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
+  r.describe(
+    "Tracks per-tenant usage against configurable limits using two complementary storage models: calendar-period counters (one projection row per tenant/capName/period, reset implicitly by period rollover) and rolling-window counters (append-only event stream, no projection). Use `enforceCap` / `enforceRollingCap` (or the `withCapEnforcement` / `withRollingCapEnforcement` handler wrappers) in your write-handlers to check limits with soft-warn and hard-block tolerances; call `enforceCapAndMaybeNotify` when you also want to trigger a delivery notification on soft-threshold hits.",
+  );
   r.entity("cap-counter", capCounterEntity);
 
   // Custom Domain-Event für Rolling-Counter. r.defineEvent registriert

package/src/channel-email/feature.ts

@@ -5,6 +5,9 @@ export function createChannelEmailFeature(options: EmailChannelOptions): Feature
   const channel = createEmailChannel(options);
 
   return defineFeature("channel-email", (r) => {
+    r.describe(
+      "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport`, a `renderer: NotificationRenderer` (e.g. backed by `renderer-simple`), and a `resolveEmail` function that maps a user ID to their email address.",
+    );
     r.requires("delivery");
 
     r.useExtension("deliveryChannel", "email", {

package/src/channel-in-app/feature.ts

@@ -7,6 +7,9 @@ import { inAppChannel } from "./in-app-channel";
 
 export function createChannelInAppFeature(): FeatureDefinition {
   return defineFeature("channel-in-app", (r) => {
+    r.describe(
+      "Persists notifications to an in-app inbox table so users can retrieve them via `handlers.inbox` and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. Requires `delivery`; no external service needed \u2014 messages are stored in the app's own database.",
+    );
     r.requires("delivery");
 
     // Register as delivery channel via extension system

package/src/channel-push/feature.ts

@@ -5,6 +5,9 @@ export function createChannelPushFeature(options: PushChannelOptions): FeatureDe
   const channel = createPushChannel(options);
 
   return defineFeature("channel-push", (r) => {
+    r.describe(
+      "Delivers push notifications through a `PushTransport` (bring your own FCM/APNs adapter or use `createInMemoryPushTransport()` for tests) registered as the `push` channel in the delivery system. Requires `delivery`; supply a `PushChannelOptions` with a transport and a resolver that maps a user ID to their device token.",
+    );
     r.requires("delivery");
 
     r.useExtension("deliveryChannel", "push", {

package/src/compliance-profiles/feature.ts

@@ -27,6 +27,9 @@ export {
 // Begruendung in schema/profile-selection.ts.
 export function createComplianceProfilesFeature(): FeatureDefinition {
   return defineFeature("compliance-profiles", (r) => {
+    r.describe(
+      "Lets each tenant select a compliance regime (e.g. `eu-dsgvo`, `swiss-dsg`, `de-hr-dsgvo-hgb`) that bundles user-rights grace periods, breach-disclosure deadlines, sub-processor requirements, and audit-retention rules into a single named profile. Tenant admins call `compliance-profiles:write:set-profile` to choose a profile (with optional JSON override for edge cases); other features resolve the effective profile via the `compliance.forTenant` cross-feature API. Required by `user-data-rights` \u2014 mount this feature before it.",
+    );
     // Standalone — kein r.requires noetig: tenantId kommt aus dem User-
     // Context, Profile-Selection ist eigene Entity, sub-processor-Liste
     // sind Constants. Wenn S1.4+ Cross-Feature-Reads dazukommen, kommt

package/src/config/__tests__/config.integration.test.ts

@@ -196,6 +196,37 @@ const seedFeature = defineFeature("seeddemo", (r) => {
   });
 });
 
+// Readiness-Scenario: required keys — feature is unusable until the tenant
+// sets real values (mirrors mail-transport-smtp / file-provider-s3).
+const transportFeature = defineFeature("transport", (r) => {
+  r.requires("config");
+  return r.config({
+    keys: {
+      smtpHost: createTenantConfig("text", {
+        required: true,
+        default: "",
+        write: access.roles("Admin"),
+        read: access.admin,
+      }),
+      apiUrl: createTenantConfig("text", {
+        required: true,
+        default: "",
+        write: access.roles("Admin"),
+      }),
+      // Stays unset for the whole suite — read-access tests rely on it.
+      webhookUrl: createTenantConfig("text", {
+        required: true,
+        default: "",
+        write: access.roles("Admin"),
+      }),
+      timeout: createTenantConfig("number", {
+        required: true,
+        write: access.roles("Admin"),
+      }),
+    },
+  });
+});
+
 const testEncryptionKey = randomBytes(32).toString("base64");
 
 beforeAll(async () => {
@@ -212,6 +243,7 @@ beforeAll(async () => {
       integrationFeature,
       probeFeature,
       seedFeature,
+      transportFeature,
     ],
     // Wire `ctx.config()` for real handlers: pass the resolver-bound factory
     // so the dispatcher can mint a per-user accessor inside buildHandlerContext.
@@ -690,6 +722,87 @@ describe("config.schema query handler", () => {
   });
 });
 
+// --- config.readiness query ---
+
+describe("config.readiness query handler", () => {
+  type Missing = { missing: Array<{ key: string; scope: string; type: string }> };
+
+  test("lists required keys without a usable value — and only those", async () => {
+    const { missing } = await stack.http.queryOk<Missing>(ConfigQueries.readiness, {}, tenantAdmin);
+
+    const keys = missing.map((m) => m.key);
+    expect(keys).toContain("transport:config:smtp-host");
+    expect(keys).toContain("transport:config:api-url");
+    expect(keys).toContain("transport:config:timeout");
+    // Non-required keys never show up, configured or not.
+    expect(keys).not.toContain("app:config:mail-server");
+    expect(keys).not.toContain("orders:config:max-order-count");
+  });
+
+  test("whitespace-only text value still counts as missing (requireNonEmpty-Parität)", async () => {
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: "transport:config:api-url", value: "   " },
+      tenantAdmin,
+    );
+
+    const { missing } = await stack.http.queryOk<Missing>(ConfigQueries.readiness, {}, tenantAdmin);
+    expect(missing.map((m) => m.key)).toContain("transport:config:api-url");
+  });
+
+  test("a real value clears the key from the missing list", async () => {
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: "transport:config:api-url", value: "https://api.example.com" },
+      tenantAdmin,
+    );
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: "transport:config:timeout", value: 30 },
+      tenantAdmin,
+    );
+
+    const { missing } = await stack.http.queryOk<Missing>(ConfigQueries.readiness, {}, tenantAdmin);
+    const keys = missing.map((m) => m.key);
+    expect(keys).not.toContain("transport:config:api-url");
+    expect(keys).not.toContain("transport:config:timeout");
+    // Untouched required keys stay missing.
+    expect(keys).toContain("transport:config:smtp-host");
+  });
+
+  test("filters by read access", async () => {
+    const { missing } = await stack.http.queryOk<Missing>(ConfigQueries.readiness, {}, normalUser);
+
+    const keys = missing.map((m) => m.key);
+    // read: all (tenant-scope default) → visible to a plain User
+    expect(keys).toContain("transport:config:webhook-url");
+    // read: admin-only → hidden from a plain User even though unset
+    expect(keys).not.toContain("transport:config:smtp-host");
+  });
+
+  test("readiness is per-tenant: another tenant still sees the keys as missing", async () => {
+    const { missing } = await stack.http.queryOk<Missing>(
+      ConfigQueries.readiness,
+      {},
+      otherTenantAdmin,
+    );
+
+    const keys = missing.map((m) => m.key);
+    expect(keys).toContain("transport:config:api-url");
+    expect(keys).toContain("transport:config:timeout");
+  });
+
+  test("schema query exposes the required flag for UI rendering", async () => {
+    const schema = await stack.http.queryOk<Record<string, { required?: boolean }>>(
+      ConfigQueries.schema,
+      {},
+      tenantAdmin,
+    );
+    expect(schema["transport:config:smtp-host"]?.required).toBe(true);
+    expect(schema["app:config:mail-server"]?.required).toBeUndefined();
+  });
+});
+
 // --- Type validation ---
 
 describe("type validation", () => {

package/src/config/constants.ts

@@ -12,6 +12,7 @@ export const ConfigQueries = {
   cascade: "config:query:cascade",
   values: "config:query:values",
   schema: "config:query:schema",
+  readiness: "config:query:readiness",
 } as const;
 
 // Error codes

package/src/config/feature.ts

@@ -13,6 +13,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { cascadeQuery } from "./handlers/cascade.query";
+import { readinessQuery } from "./handlers/readiness.query";
 import { resetWrite } from "./handlers/reset.write";
 import { schemaQuery } from "./handlers/schema.query";
 import { setWrite } from "./handlers/set.write";
@@ -24,6 +25,9 @@ export type ConfigContext = { readonly config: ConfigAccessor };
 
 export function createConfigFeature(): FeatureDefinition {
   return defineFeature("config", (r) => {
+    r.describe(
+      "Stores per-tenant (and optionally per-user) configuration values with a multi-layer cascade: user-row \u2192 tenant-row \u2192 system-row \u2192 app-override (deploy-time `AppConfigOverrides`) \u2192 computed \u2192 feature default. Access a value in handlers via `ctx.config(handle)`, declare keys with `r.config({ keys: { ... } })` inside a feature's registry callback, and optionally mark them `encrypted: true` to route storage through an `EncryptionProvider`. Use this feature whenever a tenant admin needs to customise behaviour at runtime without a code deploy.",
+    );
     r.systemScope();
 
     // One aggregate stream per (key, scope) pair — the executor handles the
@@ -42,6 +46,7 @@ export function createConfigFeature(): FeatureDefinition {
       cascade: r.queryHandler(cascadeQuery),
       values: r.queryHandler(valuesQuery),
       schema: r.queryHandler(schemaQuery),
+      readiness: r.queryHandler(readinessQuery),
     };
 
     return { handlers, queries };

package/src/config/handlers/readiness.query.ts

@@ -0,0 +1,96 @@
+import {
+  type ConfigKeyType,
+  type ConfigScope,
+  defineQueryHandler,
+  type HandlerContext,
+  type SessionUser,
+  toKebab,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { requireConfigResolver } from "../feature";
+import { hasConfigAccess } from "../write-helpers";
+
+export type ReadinessMissingKey = {
+  readonly key: string;
+  readonly scope: ConfigScope;
+  readonly type: ConfigKeyType;
+};
+
+// Mirrors requireNonEmpty in foundation-shared/config-helpers.ts: required
+// text keys ship default "" and count as unset while empty/whitespace.
+function isUnset(value: string | number | boolean | undefined, type: ConfigKeyType): boolean {
+  if (value === undefined) return true;
+  return type === "text" && typeof value === "string" && value.trim().length === 0;
+}
+
+// Whether a required key/secret counts for THIS tenant right now. Keys of
+// provider-features under a selector-declared extension point count only
+// while their provider is the selected one — an SMTP password is no gap
+// for a tenant running the inmemory transport.
+export type RequiredKeyGate = (qualifiedName: string) => boolean;
+
+// Builds the per-tenant gate from r.extensionSelector declarations: resolve
+// each selector through the config cascade, mark every provider-feature
+// registered under that point as counted/uncounted. Features without a
+// selector-gated registration always count.
+export async function buildProviderSelectionGate(
+  ctx: HandlerContext,
+  callerQn: string,
+  user: SessionUser,
+): Promise<RequiredKeyGate> {
+  const resolver = requireConfigResolver(ctx, callerQn);
+  const countsByFeature = new Map<string, boolean>();
+  for (const [extensionName, selectorKey] of ctx.registry.getAllExtensionSelectors()) {
+    const keyDef = ctx.registry.getConfigKey(selectorKey);
+    if (!keyDef) continue; // registry-build already failed this; defensive
+    const value = await resolver.get(selectorKey, keyDef, user.tenantId, user.id, ctx.db);
+    const selected = typeof value === "string" ? value.trim() : "";
+    for (const usage of ctx.registry.getExtensionUsages(extensionName)) {
+      if (usage.featureName === undefined) continue;
+      const owner = toKebab(usage.featureName);
+      const isSelected = usage.entityName === selected;
+      countsByFeature.set(owner, (countsByFeature.get(owner) ?? false) || isSelected);
+    }
+  }
+  return (qualifiedName) => countsByFeature.get(qualifiedName.split(":")[0] ?? "") ?? true;
+}
+
+// Core of config:query:readiness, exported through the config barrel so the
+// readiness rollup-feature reuses the exact same cascade + access filter.
+// Resolved through the same cascade as ctx.config() so readiness can never
+// drift from what the owning feature's build-fn will see. Note:
+// required+encrypted assumes encryption is wired — resolver.get decrypts
+// stored values, same prerequisite as any ctx.config() read of that key.
+export async function collectMissingRequiredConfig(
+  ctx: HandlerContext,
+  callerQn: string,
+  user: SessionUser,
+  gate?: RequiredKeyGate,
+): Promise<ReadinessMissingKey[]> {
+  const resolver = requireConfigResolver(ctx, callerQn);
+  const effectiveGate = gate ?? (await buildProviderSelectionGate(ctx, callerQn, user));
+  const missing: ReadinessMissingKey[] = [];
+  for (const [qualifiedKey, keyDef] of ctx.registry.getAllConfigKeys()) {
+    if (keyDef.required !== true) continue;
+    if (!effectiveGate(qualifiedKey)) continue;
+    if (!hasConfigAccess(keyDef.access.read, user.roles)) continue;
+    const value = await resolver.get(qualifiedKey, keyDef, user.tenantId, user.id, ctx.db);
+    if (isUnset(value, keyDef.type)) {
+      missing.push({ key: qualifiedKey, scope: keyDef.scope, type: keyDef.type });
+    }
+  }
+  return missing;
+}
+
+// No boolean "ready" verdict on purpose — config readiness says nothing
+// about secrets. readiness:query:status (readiness feature) rolls both up.
+export const readinessQuery = defineQueryHandler({
+  name: "readiness",
+  schema: z.object({}),
+  // Per-key read access enforced via hasConfigAccess inside the handler.
+  access: { openToAll: true },
+  handler: async (query, ctx) => {
+    const missing = await collectMissingRequiredConfig(ctx, "config:query:readiness", query.user);
+    return { missing };
+  },
+});

package/src/config/index.ts

@@ -15,6 +15,11 @@ export {
   createConfigAccessorFactory,
   createConfigFeature,
 } from "./feature";
+export type { ReadinessMissingKey, RequiredKeyGate } from "./handlers/readiness.query";
+export {
+  buildProviderSelectionGate,
+  collectMissingRequiredConfig,
+} from "./handlers/readiness.query";
 export type { AppConfigOverrides, ConfigResolver } from "./resolver";
 export { createConfigResolver, validateAppOverrides } from "./resolver";
 export { configValuesTable } from "./table";

package/src/custom-fields/feature.ts

@@ -84,6 +84,9 @@ function registerCustomFields(
   r: FeatureRegistrar<typeof CUSTOM_FIELDS_FEATURE_NAME>,
   defineTenantHandler: WriteHandlerDef,
 ) {
+  r.describe(
+    "Tenant- and system-scoped custom field definitions with generic value storage on any host entity. Registers the `field-definition` entity (event-sourced CRUD via `define-tenant-field`, `define-system-field`, `delete-tenant-field`, `delete-system-field`) and two value write-handlers (`set-custom-field`, `clear-custom-field`) that emit `custom-fields:event:custom-field-set` / `custom-fields:event:custom-field-cleared` events on the host aggregate's stream. To attach custom fields to your own entity, call `wireCustomFieldsFor(r, entityName, entityTable)` in the host feature — this wires the JSONB projection, `postQuery` flattening hook, and search-payload extension. The host entity must declare a `customFieldsField()` JSONB column.",
+  );
   r.entity("field-definition", fieldDefinitionEntity);
 
   // Event-types — qualified als "custom-fields:event:<short-name>".

package/src/data-retention/feature.ts

@@ -44,6 +44,9 @@ export {
 // pflicht. Das Wiring kommt in Sprint 2.U5.
 export function createDataRetentionFeature(): FeatureDefinition {
   return defineFeature("data-retention", (r) => {
+    r.describe(
+      "Resolves the effective retention policy for any entity using a 3-layer stack: entity-level default \u2192 tenant preset (`dsgvo-basic`, `dsgvo-hgb`, `swiss-dsg`) \u2192 per-tenant override stored in `tenantRetentionOverride`. Other features query the resolved policy via the `retention.policyFor` cross-feature API \u2014 most notably `user-data-rights`, which uses it to decide whether to anonymize instead of hard-delete a record that is still within a mandatory retention window.",
+    );
     r.entity("tenant-retention-override", tenantRetentionOverrideEntity);
 
     // S2.D3: Cross-Feature-API fuer Forget-Flow + Cleanup-Job

package/src/delivery/feature.ts

@@ -14,6 +14,9 @@ import {
 
 export function createDeliveryFeature(): FeatureDefinition {
   return defineFeature("delivery", (r) => {
+    r.describe(
+      "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). It stores per-user channel preferences in the `notification-preference` entity, logs every attempt to `read_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything.",
+    );
     r.systemScope();
     r.entity("notification-preference", notificationPreferenceEntity);
     r.unmanagedTable(deliveryAttemptsTableMeta, {

package/src/feature-toggles/feature.ts

@@ -37,6 +37,9 @@ export function createFeatureTogglesFeature(
   options: FeatureTogglesOptions = {},
 ): 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.',
+    );
     r.systemScope();
 
     // Toggle-change domain event. The event ends up in the events-table

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

@@ -167,7 +167,7 @@ describe("scenario 1: happy path", () => {
 // --- Scenario 2: validation errors ---
 
 describe("scenario 2: validation errors", () => {
-  test("missing bucket → factory throws with hint instead of cryptic SDK error", async () => {
+  test("missing bucket → 422 unconfigured naming the key, not a cryptic SDK error", async () => {
     const admin = adminFor(502);
 
     await selectS3Provider(admin);
@@ -183,9 +183,13 @@ describe("scenario 2: validation errors", () => {
 
     const error = await stack.http.writeErr(TEST_HANDLER_QN, {}, admin);
     expect(JSON.stringify(error)).toMatch(/'bucket' is empty/);
+    expect(error.httpStatus).toBe(422);
+    expect(error.code).toBe("unconfigured");
+    expect(error.i18nKey).toBe("errors.unconfigured");
+    expect(error.details).toMatchObject({ feature: "file-provider-s3", key: "bucket" });
   });
 
-  test("missing secret-access-key → factory throws naming the secret", async () => {
+  test("missing secret-access-key → 422 unconfigured naming the secret", async () => {
     const admin = adminFor(503);
 
     await selectS3Provider(admin);
@@ -196,6 +200,12 @@ describe("scenario 2: validation errors", () => {
 
     const error = await stack.http.writeErr(TEST_HANDLER_QN, {}, admin);
     expect(JSON.stringify(error)).toMatch(/s3-secret-access-key/);
+    expect(error.httpStatus).toBe(422);
+    expect(error.code).toBe("unconfigured");
+    expect(error.details).toMatchObject({
+      feature: "file-provider-s3",
+      key: S3_SECRET_ACCESS_KEY.name,
+    });
   });
 });
 

package/src/file-foundation/feature.ts

@@ -90,6 +90,9 @@ export type FileProviderPlugin = {
 // =============================================================================
 
 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` \u2014 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.requires("config");
 
   r.extendsRegistrar("fileProvider", {
@@ -108,6 +111,9 @@ export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
       }),
     },
   });
+  // Readiness gating: provider-plugins' required keys/secrets count only
+  // while their plugin is the one this key selects.
+  r.extensionSelector("fileProvider", configKeys.provider);
 
   return { configKeys };
 });

package/src/file-provider-inmemory/feature.ts

@@ -60,6 +60,9 @@ export function clearStorage(tenantId: string): void {
 // =============================================================================
 
 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).',
+  );
   // Kein r.requires("config") + kein r.requires("secrets") — der
   // In-Memory-Provider hat keine Config + kein Secret. Nur die
   // file-foundation muss da sein (Plugin-extension-point).