@cosmicdrift/kumiko-bundled-features 0.27.0 → 0.31.0

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

@@ -26,6 +26,7 @@ import { createS3Provider } from "@cosmicdrift/kumiko-bundled-features/files-pro
 import {
   requireDefined,
   requireNonEmpty,
+  requireSecretSet,
 } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
@@ -38,6 +39,9 @@ const FEATURE_NAME = "file-provider-s3";
 // =============================================================================
 
 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.requires("config");
   r.requires("secrets");
   r.requires("file-foundation");
@@ -53,16 +57,21 @@ export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
       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"),
@@ -77,6 +86,7 @@ export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
         write: access.roles("TenantAdmin", "SystemAdmin"),
       }),
       accessKeyId: createTenantConfig("text", {
+        required: true,
         default: "",
         write: access.roles("TenantAdmin", "SystemAdmin"),
         read: access.roles("TenantAdmin", "SystemAdmin"),
@@ -158,10 +168,5 @@ async function buildS3Provider(
 async function readSecretAccessKey(ctx: FileProviderContext, tenantId: string): Promise<string> {
   const secrets = requireSecretsContext(ctx, FEATURE_NAME);
   const branded = await secrets.get(tenantId, S3_SECRET_ACCESS_KEY);
-  if (!branded) {
-    throw new Error(
-      `${FEATURE_NAME}: ${S3_SECRET_ACCESS_KEY.name} not set for tenant ${tenantId} — Tenant-Admin must set it via /api/write/secrets:write:set`,
-    );
-  }
-  return branded.reveal();
+  return requireSecretSet(branded, FEATURE_NAME, S3_SECRET_ACCESS_KEY.name).reveal();
 }

package/src/foundation-shared/__tests__/config-helpers.test.ts

@@ -7,6 +7,7 @@
 // unterschieden werden.
 
 import { describe, expect, test } from "bun:test";
+import { InternalError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
 import { requireDefined, requireNonEmpty } from "../config-helpers";
 
 describe("requireDefined", () => {
@@ -16,6 +17,10 @@ describe("requireDefined", () => {
     );
   });
 
+  test("undefined → wirft InternalError (500): Dev-Bug, kein Tenant-Gap", () => {
+    expect(() => requireDefined(undefined, "ai-foundation", "apiKey")).toThrow(InternalError);
+  });
+
   test("defined Wert → unverändert zurück", () => {
     expect(requireDefined("sk-123", "ai-foundation", "apiKey")).toBe("sk-123");
   });
@@ -48,6 +53,18 @@ describe("requireNonEmpty", () => {
     );
   });
 
+  test("leerer String → wirft UnconfiguredError (422, code unconfigured, typed details)", () => {
+    try {
+      requireNonEmpty("", "file-foundation", "bucket");
+      throw new Error("expected requireNonEmpty to throw");
+    } catch (err) {
+      if (!(err instanceof UnconfiguredError)) throw err;
+      expect(err.code).toBe("unconfigured");
+      expect(err.httpStatus).toBe(422);
+      expect(err.details).toMatchObject({ feature: "file-foundation", key: "bucket" });
+    }
+  });
+
   test("leerer String mit custom uiHint → Hint landet in der Message", () => {
     expect(() =>
       requireNonEmpty("", "ai-foundation", "model", "Choose a model in Settings → AI."),

package/src/foundation-shared/config-helpers.ts

@@ -19,11 +19,16 @@
 //     across foundations live here. Per-foundation transport/provider-
 //     factories stay in their own package.
 
+import { InternalError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
+
 /**
  * Narrow `value | undefined` → `value` with a clear message that names
  * which config key resolved to nothing. Use for keys whose `undefined`
  * means a registry misconfiguration (no value + no default).
  *
+ * Throws InternalError (500): `undefined` here is a developer bug, not a
+ * tenant-configuration gap — contrast requireNonEmpty.
+ *
  * Foundation-Pattern: this is the wrap-helper around `await ctx.config(
  * featureFoundationFeature.exports.configKeys.someKey)` — the call-site
  * stays a single line per key.
@@ -34,9 +39,9 @@
  */
 export function requireDefined<T>(value: T | undefined, featureName: string, label: string): T {
   if (value === undefined) {
-    throw new Error(
-      `${featureName}: '${label}' config key resolved to undefined — registry misconfigured (no value + no default)`,
-    );
+    throw new InternalError({
+      message: `${featureName}: '${label}' config key resolved to undefined — registry misconfigured (no value + no default)`,
+    });
   }
   return value;
 }
@@ -54,6 +59,9 @@ export function requireDefined<T>(value: T | undefined, featureName: string, lab
  * Whitespace is trimmed: a whitespace-only value counts as empty, and the
  * returned string has surrounding whitespace removed — so a stray " host "
  * never reaches the SDK as-is.
+ *
+ * Throws UnconfiguredError (422, code "unconfigured") so clients can route
+ * the user to the settings screen instead of a generic 500.
  */
 export function requireNonEmpty(
   value: string | undefined,
@@ -63,9 +71,27 @@ export function requireNonEmpty(
 ): string {
   const trimmed = requireDefined(value, featureName, label).trim();
   if (trimmed.length === 0) {
-    throw new Error(
-      `${featureName}: '${label}' is empty — tenant must configure it before use. ${uiHint}`,
-    );
+    throw new UnconfiguredError({ feature: featureName, key: label, hint: uiHint });
   }
   return trimmed;
 }
+
+/**
+ * Narrow a `ctx.secrets.get()` result → set secret. The secrets-counterpart
+ * to requireNonEmpty: a missing secret is a tenant-configuration gap, not a
+ * crash — same 422 contract, so clients route to the settings screen.
+ *
+ * `key` is the secret's qualified name (`HANDLE.name`) so the error names
+ * exactly what `secrets:write:set` expects.
+ */
+export function requireSecretSet<T>(
+  value: T | undefined,
+  featureName: string,
+  key: string,
+  uiHint = "Set via secrets:write:set or the tenant-admin UI.",
+): T {
+  if (value === undefined) {
+    throw new UnconfiguredError({ feature: featureName, key, hint: uiHint });
+  }
+  return value;
+}

package/src/foundation-shared/index.ts

@@ -1,4 +1,4 @@
 // Public API of foundation-shared — utilities consumed by the per-tenant
 // Foundation packages (ai-foundation, mail-foundation, file-foundation).
 
-export { requireDefined, requireNonEmpty } from "./config-helpers";
+export { requireDefined, requireNonEmpty, requireSecretSet } from "./config-helpers";

package/src/jobs/feature.ts

@@ -23,6 +23,9 @@ import { jobRunLogsTable, jobRunLogsTableMeta, jobRunsTable } from "./job-run-ta
 
 export function createJobsFeature(): FeatureDefinition {
   return defineFeature("jobs", (r) => {
+    r.describe(
+      "Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution appends `run-started`, `run-completed`, and `run-failed` events to the `jobRun` aggregate stream, which two inline projections materialize into `read_job_runs` (current status + duration) and `read_job_run_logs` (per-line log rows). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list` and `jobs:query:details` for the operator UI.",
+    );
     r.systemScope();
     r.unmanagedTable(jobRunLogsTableMeta, {
       reason: "read_side.job_run_logs",

package/src/legal-pages/feature.ts

@@ -60,6 +60,9 @@ export type LegalPagesOptions = {
 export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDefinition {
   const wrapLayout = opts.wrapLayout ?? wrapInLayout;
   return defineFeature("legal-pages", (r) => {
+    r.describe(
+      "Opt-in wrapper around `text-content` that registers four public HTML routes (`/legal/impressum`, `/legal/datenschutz`, `/legal/imprint`, `/legal/privacy`) with Markdown-to-HTML rendering and a boot-time job that hard-fails in production when the required DE blocks (`imprint/de`, `privacy/de`) are not seeded in `SYSTEM_TENANT`. Requires `anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID }` and `extraContext.textContent` to be wired at app bootstrap; for per-tenant imprints or a custom layout call `text-content:query:by-slug` directly.",
+    );
     r.requires("text-content");
 
     // 4 Public-HTML-Routes

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

@@ -188,7 +188,7 @@ describe("scenario 2: validation errors", () => {
     expect(JSON.stringify(error)).toMatch(/'host' is empty/);
   });
 
-  test("missing password secret → factory throws naming the secret", async () => {
+  test("missing password secret → 422 unconfigured naming the secret", async () => {
     const admin = adminFor(403);
 
     await selectSmtpProvider(admin);
@@ -201,6 +201,12 @@ describe("scenario 2: validation errors", () => {
 
     const error = await stack.http.writeErr(TEST_HANDLER_QN, {}, admin);
     expect(JSON.stringify(error)).toMatch(/smtp-password/);
+    expect(error.httpStatus).toBe(422);
+    expect(error.code).toBe("unconfigured");
+    expect(error.details).toMatchObject({
+      feature: "mail-transport-smtp",
+      key: SMTP_PASSWORD.name,
+    });
   });
 });
 

package/src/mail-foundation/feature.ts

@@ -65,6 +65,9 @@ export type MailTransportPlugin = {
 // =============================================================================
 
 export const mailFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    "Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending \u2014 use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences.",
+  );
   r.requires("config");
 
   // Plugin extension-point. Provider-features register here. The
@@ -93,6 +96,9 @@ export const mailFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
       }),
     },
   });
+  // Readiness gating: transport-plugins' required keys/secrets count only
+  // while their plugin is the one this key selects.
+  r.extensionSelector("mailTransport", configKeys.provider);
 
   return {
     /** Config-key-handle for the provider-selector. */

package/src/mail-transport-inmemory/feature.ts

@@ -73,6 +73,9 @@ export function clearInbox(tenantId: string): void {
 // =============================================================================
 
 export const mailTransportInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    'Registers an in-process `"inmemory"` provider for `mail-foundation` that buffers sent mails per tenant instead of contacting an SMTP server. Use `getInbox(tenantId)` and `clearInbox(tenantId)` in demo apps and tests; not for production (buffer is process-memory, lost on restart).',
+  );
   // Kein r.requires("config") + kein r.requires("secrets") — der
   // In-Memory-Transport hat keine Config (nichts zu konfigurieren) und
   // kein Secret. Der einzige hard-require ist mail-foundation, das den

package/src/mail-transport-smtp/feature.ts

@@ -32,6 +32,7 @@ import {
 import {
   requireDefined,
   requireNonEmpty,
+  requireSecretSet,
 } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import type { MailTransportPlugin } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
@@ -49,6 +50,9 @@ const FEATURE_NAME = "mail-transport-smtp";
 // =============================================================================
 
 export const mailTransportSmtpFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    'Registers itself as the `"smtp"` provider for `mail-foundation` and owns the per-tenant config keys (`host`, `port`, `secure`, `from`, `authUser`) and the encrypted `smtp.password` secret. Tenants set `mail-foundation`\'s `provider` config key to `"smtp"` to activate it; set the SMTP credentials via the admin UI or a seed handler before sending the first mail.',
+  );
   r.requires("config");
   r.requires("secrets");
   r.requires("mail-foundation");
@@ -65,11 +69,15 @@ export const mailTransportSmtpFeature = defineFeature(FEATURE_NAME, (r) => {
       return `${plaintext.slice(0, 3)}...${plaintext.slice(-2)}`;
     },
     scope: "tenant",
+    // required: true ↔ the missing-secret throw in readPassword — keep in sync.
+    required: true,
   });
 
+  // required: true ↔ the requireNonEmpty calls in buildSmtpTransport — keep in sync.
   const configKeys = r.config({
     keys: {
       host: createTenantConfig("text", {
+        required: true,
         default: "",
         write: access.roles("TenantAdmin", "SystemAdmin"),
         read: access.roles("TenantAdmin", "SystemAdmin"),
@@ -84,11 +92,13 @@ export const mailTransportSmtpFeature = defineFeature(FEATURE_NAME, (r) => {
         write: access.roles("TenantAdmin", "SystemAdmin"),
       }),
       from: createTenantConfig("text", {
+        required: true,
         default: "",
         write: access.roles("TenantAdmin", "SystemAdmin"),
         read: access.roles("TenantAdmin", "SystemAdmin"),
       }),
       authUser: createTenantConfig("text", {
+        required: true,
         default: "",
         write: access.roles("TenantAdmin", "SystemAdmin"),
         read: access.roles("TenantAdmin", "SystemAdmin"),
@@ -173,10 +183,5 @@ async function buildSmtpTransport(ctx: HandlerContext, tenantId: string): Promis
 async function readPassword(ctx: HandlerContext, tenantId: string): Promise<string> {
   const secrets = requireSecretsContext(ctx, FEATURE_NAME);
   const branded = await secrets.get(tenantId, SMTP_PASSWORD);
-  if (!branded) {
-    throw new Error(
-      `${FEATURE_NAME}: ${SMTP_PASSWORD.name} not set for tenant ${tenantId} — Tenant-Admin must set it via /api/write/secrets:write:set`,
-    );
-  }
-  return branded.reveal();
+  return requireSecretSet(branded, FEATURE_NAME, SMTP_PASSWORD.name).reveal();
 }

package/src/rate-limiting/feature.ts

@@ -11,6 +11,9 @@ import { rateLimitStatus } from "./handlers/status.query";
 // skip this feature entirely — the resolver still runs.
 export function createRateLimitingFeature() {
   return defineFeature("rate-limiting", (r) => {
+    r.describe(
+      "Adds an ops-side `rate-limiting:query:status` query handler for inspecting current bucket state; the actual request throttling is wired automatically by the dispatcher when any handler declares a `rateLimit` option (e.g. `{ per: 'user', limit: 3, windowSeconds: 60 }`) or when you pass `context.rateLimit` to `buildServer`. Loading this feature is optional if you only need L3 per-handler rate limits and have no need for ops introspection.",
+    );
     r.queryHandler(rateLimitStatus);
   });
 }

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

@@ -0,0 +1,338 @@
+// Full-stack integration test for the readiness rollup. Drives
+// readiness:query:status through the dispatcher so the real config-cascade
+// + secrets-metadata-lookup are exercised — including the no-read-audit
+// guarantee of the has() probe.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEncryptionProvider, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createConfigFeature } from "../../config";
+import { createConfigAccessorFactory } from "../../config/feature";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import {
+  createSecretsContext,
+  createSecretsFeature,
+  TENANT_SECRET_READ_EVENT,
+  tenantSecretsTable,
+} from "../../secrets";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { ReadinessQueries } from "../constants";
+import { readinessFeature } from "../feature";
+
+// Probe-feature: one required + one optional config key, one required +
+// one optional secret — the rollup must list exactly the required gaps.
+const probeFeature = defineFeature("readiness-probe", (r) => {
+  r.requires("config");
+  r.requires("secrets");
+
+  r.config({
+    keys: {
+      apiUrl: createTenantConfig("text", {
+        required: true,
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+      timeout: createTenantConfig("number", {
+        default: 30,
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+    },
+  });
+
+  r.secret("probe.apiToken", {
+    label: { de: "API-Token", en: "API token" },
+    scope: "tenant",
+    required: true,
+  });
+  r.secret("probe.optionalToken", {
+    label: { de: "Optionales Token", en: "Optional token" },
+    scope: "tenant",
+  });
+});
+
+// Provider-gating fixture: foundation declares the selector, two providers
+// register under the point. The smtp-ish one carries required key + secret —
+// they must count ONLY while "smtp" is the selected provider.
+const probeMailFoundation = defineFeature("probe-mail-foundation", (r) => {
+  r.requires("config");
+  r.extendsRegistrar("probeMailTransport", { onRegister: () => undefined });
+  const configKeys = r.config({
+    keys: {
+      provider: createTenantConfig("text", {
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+    },
+  });
+  r.extensionSelector("probeMailTransport", configKeys.provider);
+  return { configKeys };
+});
+
+const probeSmtpProvider = defineFeature("probe-smtp", (r) => {
+  r.requires("config");
+  r.requires("secrets");
+  r.useExtension("probeMailTransport", "smtp");
+  r.config({
+    keys: {
+      host: createTenantConfig("text", {
+        required: true,
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+    },
+  });
+  r.secret("smtp.password", {
+    label: { de: "SMTP-Passwort", en: "SMTP password" },
+    scope: "tenant",
+    required: true,
+  });
+});
+
+const probeInMemoryProvider = defineFeature("probe-inmemory", (r) => {
+  r.useExtension("probeMailTransport", "inmemory");
+});
+
+const REQUIRED_CONFIG_KEY = "readiness-probe:config:api-url";
+const REQUIRED_SECRET_KEY = "readiness-probe:secret:probe-api-token";
+const PROVIDER_SELECTOR_KEY = "probe-mail-foundation:config:provider";
+const GATED_CONFIG_KEY = "probe-smtp:config:host";
+const GATED_SECRET_KEY = "probe-smtp:secret:smtp-password";
+
+type StatusResult = {
+  missingConfig: ReadonlyArray<{ key: string; scope: string; type: string }>;
+  missingSecrets: ReadonlyArray<{ key: string }>;
+  ready: boolean;
+};
+
+let stack: TestStack;
+let db: DbConnection;
+
+beforeAll(async () => {
+  const encryption = createEncryptionProvider(randomBytes(32).toString("base64"));
+  const resolver = createConfigResolver({ encryption });
+  const masterKeyProvider = createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+    },
+  });
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createSecretsFeature(),
+      readinessFeature,
+      probeFeature,
+      probeMailFoundation,
+      probeSmtpProvider,
+      probeInMemoryProvider,
+    ],
+    extraContext: ({ db, registry }) => ({
+      configResolver: resolver,
+      configEncryption: encryption,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+      secrets: createSecretsContext({ db, masterKeyProvider }),
+    }),
+  });
+  db = stack.db;
+  await unsafeCreateEntityTable(db, tenantEntity);
+  await unsafePushTables(db, { configValuesTable, tenant_secrets: tenantSecretsTable });
+  await createEventsTable(db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function adminFor(tenantNumber: number) {
+  return createTestUser({
+    id: tenantNumber,
+    tenantId: testTenantId(tenantNumber),
+    roles: ["TenantAdmin"],
+  });
+}
+
+async function statusFor(admin: ReturnType<typeof adminFor>): Promise<StatusResult> {
+  return stack.http.queryOk<StatusResult>(ReadinessQueries.status, {}, admin);
+}
+
+describe("readiness:query:status", () => {
+  test("fresh tenant → required config + secret listed as missing, ready false", async () => {
+    const admin = adminFor(601);
+
+    const status = await statusFor(admin);
+
+    expect(status.ready).toBe(false);
+    expect(status.missingConfig).toContainEqual({
+      key: REQUIRED_CONFIG_KEY,
+      scope: "tenant",
+      type: "text",
+    });
+    expect(status.missingSecrets).toContainEqual({ key: REQUIRED_SECRET_KEY });
+    // Optional keys must not appear — they have usable defaults / aren't required.
+    expect(status.missingConfig.map((k) => k.key)).not.toContain("readiness-probe:config:timeout");
+    expect(status.missingSecrets.map((s) => s.key)).not.toContain(
+      "readiness-probe:secret:probe-optional-token",
+    );
+  });
+
+  test("setting required config + secret flips ready to true", async () => {
+    const admin = adminFor(602);
+
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: REQUIRED_CONFIG_KEY, value: "https://api.example.test" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: REQUIRED_SECRET_KEY, value: "token-xyz" },
+      admin,
+    );
+
+    const status = await statusFor(admin);
+    expect(status.missingConfig.map((k) => k.key)).not.toContain(REQUIRED_CONFIG_KEY);
+    expect(status.missingSecrets).toEqual([]);
+    expect(status.ready).toBe(true);
+  });
+
+  test("tenant isolation: tenant A's values don't make tenant B ready", async () => {
+    const adminA = adminFor(603);
+    const adminB = adminFor(604);
+
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: REQUIRED_CONFIG_KEY, value: "https://a.example.test" },
+      adminA,
+    );
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: REQUIRED_SECRET_KEY, value: "token-a" },
+      adminA,
+    );
+
+    expect((await statusFor(adminA)).ready).toBe(true);
+    const statusB = await statusFor(adminB);
+    expect(statusB.ready).toBe(false);
+    expect(statusB.missingSecrets).toContainEqual({ key: REQUIRED_SECRET_KEY });
+  });
+
+  test("non-TenantAdmin → access denied (same gate as secrets:query:list)", async () => {
+    const member = createTestUser({
+      id: 605,
+      tenantId: testTenantId(605),
+      roles: ["Member"],
+    });
+
+    const res = await stack.http.query(ReadinessQueries.status, {}, member);
+    expect(res.status).toBe(403);
+  });
+
+  test("provider-gated keys don't count while no provider is selected", async () => {
+    const admin = adminFor(607);
+
+    const status = await statusFor(admin);
+    expect(status.missingConfig.map((k) => k.key)).not.toContain(GATED_CONFIG_KEY);
+    expect(status.missingSecrets.map((s) => s.key)).not.toContain(GATED_SECRET_KEY);
+  });
+
+  test("selecting the provider pulls its required key + secret into missing", async () => {
+    const admin = adminFor(608);
+
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: PROVIDER_SELECTOR_KEY, value: "smtp" },
+      admin,
+    );
+
+    const status = await statusFor(admin);
+    expect(status.missingConfig.map((k) => k.key)).toContain(GATED_CONFIG_KEY);
+    expect(status.missingSecrets).toContainEqual({ key: GATED_SECRET_KEY });
+    expect(status.ready).toBe(false);
+  });
+
+  test("tenant on the inmemory provider is ready despite unset smtp keys", async () => {
+    const admin = adminFor(609);
+
+    // The advisor scenario: smtp + inmemory both mounted, tenant runs
+    // inmemory — unset smtp keys must not block ready.
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: PROVIDER_SELECTOR_KEY, value: "inmemory" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: REQUIRED_CONFIG_KEY, value: "https://api.example.test" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: REQUIRED_SECRET_KEY, value: "token-609" },
+      admin,
+    );
+
+    const status = await statusFor(admin);
+    expect(status.missingConfig).toEqual([]);
+    expect(status.missingSecrets).toEqual([]);
+    expect(status.ready).toBe(true);
+  });
+
+  test("config:query:readiness applies the same provider gating", async () => {
+    const admin = adminFor(610);
+
+    const before = await stack.http.queryOk<{ missing: ReadonlyArray<{ key: string }> }>(
+      "config:query:readiness",
+      {},
+      admin,
+    );
+    expect(before.missing.map((k) => k.key)).not.toContain(GATED_CONFIG_KEY);
+
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: PROVIDER_SELECTOR_KEY, value: "smtp" },
+      admin,
+    );
+    const after = await stack.http.queryOk<{ missing: ReadonlyArray<{ key: string }> }>(
+      "config:query:readiness",
+      {},
+      admin,
+    );
+    expect(after.missing.map((k) => k.key)).toContain(GATED_CONFIG_KEY);
+  });
+
+  test("status probe writes NO secret-read audit events", async () => {
+    const admin = adminFor(606);
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: REQUIRED_SECRET_KEY, value: "token-606" },
+      admin,
+    );
+    await asRawClient(db).unsafe(
+      `DELETE FROM "${eventsTable.tableName}" WHERE type = '${TENANT_SECRET_READ_EVENT}'`,
+    );
+
+    // Probes both branches: set secret (has → true) + missing optional.
+    await statusFor(admin);
+
+    const readEvents = await selectMany(db, eventsTable, { type: TENANT_SECRET_READ_EVENT });
+    expect(readEvents).toEqual([]);
+  });
+});

package/src/readiness/constants.ts

@@ -0,0 +1,7 @@
+// Feature name
+export const READINESS_FEATURE = "readiness" as const;
+
+// Qualified query handler names (QN format: scope:type:name)
+export const ReadinessQueries = {
+  status: "readiness:query:status",
+} as const;