feat: add host-provided module object storage

`manifest.storage.buckets` has existed since manifest version 1 and meant
nothing — discovery validated it and no code read it. This turns it into a
real capability, which is what stands between Announcements and the module
system: that product currently fetches a hardcoded LAN S3 endpoint, parses
ListObjectsV2 XML by hand, and hands the browser direct object URLs.

- A module declares a logical bucket and receives a scoped facade at
  `context.storage` — list, head, get, put, delete. The contract names no
  provider: no endpoint, region, credential, or physical bucket is reachable
  from it, which is what lets the same module run under a future standalone
  host over its own or a shared S3-compatible service.
- Core's first provider speaks S3 through the AWS SDK. SeaweedFS is the
  deployment target (ADR 0004), never an API name. Probing the pinned image
  found `CreateBucket` reporting `BucketAlreadyExists` rather than AWS's
  `BucketAlreadyOwnedByYou`; treating only the AWS spelling as success would
  have failed every second boot. A live test pins it.
- Logical → physical mapping is deterministic and collision-safe: an
  installation prefix, the module and bucket ids joined by `--` (which cannot
  occur inside either identifier, so `a-b`+`c` and `a`+`b-c` cannot collide),
  and a digest over the full untruncated identity. Two modules declaring
  `assets` always get separate namespaces; neither can see the physical name.
- Declaring a bucket is now a requirement: with no provider configured the
  module is `blocked · storage_unavailable` through ADR 0028's existing
  resolver, propagating to required dependents. An installation with no object
  storage stays a complete deployment.
- Binding availability is not provider health. Eligibility asks whether
  storage is configured, never whether it answered; bucket creation is lazy on
  first use so a storage outage cannot stop the platform booting; a running
  module whose store blinks stays running and retries. Nothing deletes a
  bucket.
- Credentials are deployment-supplied, never persisted, never routed through
  module configuration, and never visible to modules, module UI, diagnostics,
  or API responses. Provider errors translate to a closed code set carrying no
  endpoint, bucket, request id, or XML.
- Retires ADR 0029's transitional `bucket` configuration key. No manifest
  version change. The template declares no bucket, so it still runs without S3.

See ADR 0030.

Co-Authored-By: Claude Opus 5 <[email protected]>

apps/api/tests/app.test.ts

@@ -22,6 +22,7 @@ import { createApiApp, type CreateApiAppAuthorizationOptions } from "../src/app.
 import { AUTH_REQUEST_MAX_BODY_BYTES } from "../src/body-limits.js";
 import { emptyModuleLifecycle } from "./support/in-memory-module-lifecycle.js";
 import { emptyModuleConfiguration } from "./support/in-memory-module-configuration.js";
+import { emptyModuleStorage } from "./support/in-memory-module-storage.js";
 
 const trustedOrigin = "https://dashboard.example.test";
 const untrustedOrigin = "https://evil.example.test";
@@ -92,6 +93,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -113,6 +115,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -135,6 +138,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -159,6 +163,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -185,6 +190,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -211,6 +217,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -234,6 +241,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -259,6 +267,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -281,6 +290,7 @@ describe("Ekklesia API Hono application", () => {
         moduleUi: emptyModuleUiPublication(),
         moduleLifecycle: emptyModuleLifecycle(),
         moduleConfiguration: emptyModuleConfiguration(),
+        moduleStorage: emptyModuleStorage(),
         dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({}),
@@ -305,6 +315,7 @@ describe("Ekklesia API Hono application", () => {
         moduleUi: emptyModuleUiPublication(),
         moduleLifecycle: emptyModuleLifecycle(),
         moduleConfiguration: emptyModuleConfiguration(),
+        moduleStorage: emptyModuleStorage(),
         dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({}),
@@ -336,6 +347,7 @@ describe("Ekklesia API Hono application", () => {
         moduleUi: emptyModuleUiPublication(),
         moduleLifecycle: emptyModuleLifecycle(),
         moduleConfiguration: emptyModuleConfiguration(),
+        moduleStorage: emptyModuleStorage(),
         dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({}),
@@ -368,6 +380,7 @@ describe("Ekklesia API Hono application", () => {
         moduleUi: emptyModuleUiPublication(),
         moduleLifecycle: emptyModuleLifecycle(),
         moduleConfiguration: emptyModuleConfiguration(),
+        moduleStorage: emptyModuleStorage(),
         dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({}),
@@ -405,6 +418,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -424,6 +438,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -445,6 +460,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -465,6 +481,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -483,6 +500,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -508,6 +526,7 @@ describe("Ekklesia API Hono application", () => {
       moduleUi: emptyModuleUiPublication(),
       moduleLifecycle: emptyModuleLifecycle(),
       moduleConfiguration: emptyModuleConfiguration(),
+      moduleStorage: emptyModuleStorage(),
       dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
@@ -536,6 +555,7 @@ describe("Ekklesia API Hono application", () => {
         moduleUi: emptyModuleUiPublication(),
         moduleLifecycle: emptyModuleLifecycle(),
         moduleConfiguration: emptyModuleConfiguration(),
+        moduleStorage: emptyModuleStorage(),
         dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({ evaluator: { authorize: evaluatorAuthorize } }),
@@ -567,6 +587,7 @@ describe("Ekklesia API Hono application", () => {
         moduleUi: emptyModuleUiPublication(),
         moduleLifecycle: emptyModuleLifecycle(),
         moduleConfiguration: emptyModuleConfiguration(),
+        moduleStorage: emptyModuleStorage(),
         dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({
@@ -589,6 +610,7 @@ describe("Ekklesia API Hono application", () => {
         moduleUi: emptyModuleUiPublication(),
         moduleLifecycle: emptyModuleLifecycle(),
         moduleConfiguration: emptyModuleConfiguration(),
+        moduleStorage: emptyModuleStorage(),
         dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({}),

apps/api/tests/dashboard-routes.test.ts

@@ -31,6 +31,7 @@ import {
   moduleLifecycleSnapshotFor,
 } from "./support/in-memory-module-lifecycle.js";
 import { moduleConfigurationOptionFor } from "./support/in-memory-module-configuration.js";
+import { moduleStorageOptionFor } from "./support/in-memory-module-storage.js";
 
 const trustedOrigin = "https://dashboard.example.test";
 const untrustedOrigin = "https://evil.example.test";
@@ -147,6 +148,7 @@ async function install(options: InstallOptions = {}): Promise<{ app: Hono }> {
       store: createInMemoryModuleLifecycleStore(),
     },
     moduleConfiguration: moduleConfigurationOptionFor(modules),
+    moduleStorage: moduleStorageOptionFor(modules),
     runtime,
     trustedOrigins: [trustedOrigin],
   });

apps/api/tests/module-configuration-routes.test.ts

@@ -39,6 +39,7 @@ import {
   createInMemoryModuleConfigurationStore,
 } from "./support/in-memory-module-configuration.js";
 import { createInMemoryModuleLifecycleStore } from "./support/in-memory-module-lifecycle.js";
+import { moduleStorageOptionFor } from "./support/in-memory-module-storage.js";
 
 const trustedOrigin = "https://dashboard.example.test";
 const untrustedOrigin = "https://evil.example.test";
@@ -194,6 +195,7 @@ async function install(options: InstallOptions = {}): Promise<Installation> {
       snapshots: eligibility.configurations,
       store,
     },
+    moduleStorage: moduleStorageOptionFor(modules),
     moduleLifecycle: {
       snapshot: {
         discoveredModules: modules,

apps/api/tests/module-database.integration.ts

@@ -519,12 +519,18 @@ describe.sequential("live API — module database access through ModuleRuntimeSe
     const readHandlerEvent = [...events]
       .reverse()
       .find((event) => event.type === "handler" && event.route === "GET /records/:id");
+    // The complete handler-context surface, asserted exactly so a new field is a deliberate change
+    // here rather than an unnoticed one: `config` (ADR 0029) and `storage` (ADR 0030) are the two
+    // scoped, per-module additions; everything else a module might want — a Hono Context, the
+    // authorization store, raw PostgreSQL, the storage provider, an endpoint or credential — remains
+    // unreachable.
     expect(readHandlerEvent?.contextKeys).toEqual([
       "config",
       "moduleId",
       "params",
       "principal",
       "services",
+      "storage",
     ]);
     expect(readHandlerEvent?.services).toBeDefined();
     expect(readHandlerEvent?.services?.database).toBe(startEvent?.services?.database);

apps/api/tests/module-http-routes.test.ts

@@ -28,6 +28,7 @@ import {
 } from "../src/module-http-routes.js";
 import { emptyModuleLifecycle } from "./support/in-memory-module-lifecycle.js";
 import { emptyModuleConfiguration } from "./support/in-memory-module-configuration.js";
+import { emptyModuleStorage } from "./support/in-memory-module-storage.js";
 
 const trustedOrigin = "https://dashboard.example.test";
 const untrustedOrigin = "https://evil.example.test";
@@ -113,6 +114,7 @@ function buildModuleApp(options: {
     moduleUi: createModuleUiPublicationRegistry([]),
     moduleLifecycle: emptyModuleLifecycle(),
     moduleConfiguration: emptyModuleConfiguration(),
+    moduleStorage: emptyModuleStorage(),
     dashboard: createInMemoryDashboardStore(),
     runtime,
     trustedOrigins: options.trustedOrigins ?? [trustedOrigin],
@@ -339,17 +341,19 @@ describe("module route handler adaptation", () => {
     expect(body.url).toContain("/api/v1/modules/calendar/events/evt-1/rsvp?notify=true");
     expect(capturedRequest).toBeInstanceOf(Request);
     expect(capturedRequest?.headers.get("x-custom")).toBe("abc");
-    // Exactly config, moduleId, params, principal, services — and nothing else. `config` is this
-    // module's own frozen configuration snapshot, added deliberately by ADR 0029; a Hono Context,
-    // the authorization store or evaluator, raw PostgreSQL, platform configuration, and another
-    // module's configuration all remain unreachable, which is what this exact-shape assertion
-    // exists to keep true.
+    // Exactly config, moduleId, params, principal, services, storage — and nothing else. `config`
+    // is this module's own frozen configuration snapshot (ADR 0029) and `storage` its own scoped
+    // object storage (ADR 0030); a Hono Context, the authorization store or evaluator, raw
+    // PostgreSQL, the storage provider, an S3 endpoint or credential, platform configuration, and
+    // another module's configuration or storage all remain unreachable, which is what this
+    // exact-shape assertion exists to keep true.
     expect(Object.keys(capturedContext ?? {}).sort()).toEqual([
       "config",
       "moduleId",
       "params",
       "principal",
       "services",
+      "storage",
     ]);
     expect(capturedContext).toMatchObject({
       moduleId: "calendar",
@@ -366,6 +370,10 @@ describe("module route handler adaptation", () => {
     // This module declared no configuration, so its snapshot is empty rather than absent — module
     // code never has to branch on whether the platform supplied one.
     expect(capturedContext?.config.keys()).toEqual([]);
+    // Likewise storage: this module declared no buckets, so it gets a frozen facade that refuses
+    // every one rather than `undefined`.
+    expect(Object.isFrozen(capturedContext?.storage)).toBe(true);
+    expect(capturedContext?.storage.buckets()).toEqual([]);
   });
 
   it("gives static and root routes a frozen, empty params object", async () => {

apps/api/tests/module-lifecycle-routes.test.ts

@@ -34,6 +34,7 @@ import { MODULE_UI_INVENTORY_PATH } from "../src/module-ui-inventory.js";
 import { createInMemoryDashboardStore } from "./support/in-memory-dashboard-store.js";
 import { createInMemoryModuleLifecycleStore } from "./support/in-memory-module-lifecycle.js";
 import { moduleConfigurationOptionFor } from "./support/in-memory-module-configuration.js";
+import { moduleStorageOptionFor } from "./support/in-memory-module-storage.js";
 
 const trustedOrigin = "https://dashboard.example.test";
 const untrustedOrigin = "https://evil.example.test";
@@ -170,6 +171,7 @@ async function install(options: InstallOptions = {}): Promise<Installation> {
     },
     dashboard: createInMemoryDashboardStore(),
     moduleConfiguration: moduleConfigurationOptionFor(modules),
+    moduleStorage: moduleStorageOptionFor(modules),
     moduleLifecycle: {
       snapshot: {
         discoveredModules: modules,

apps/api/tests/module-ui-host-e2e.test.ts

@@ -35,6 +35,7 @@ import {
   moduleLifecycleSnapshotFor,
 } from "./support/in-memory-module-lifecycle.js";
 import { moduleConfigurationOptionFor } from "./support/in-memory-module-configuration.js";
+import { moduleStorageOptionFor } from "./support/in-memory-module-storage.js";
 
 /**
  * The whole chain, with nothing between the halves faked:
@@ -223,6 +224,7 @@ async function startHarness(options: HarnessOptions = {}): Promise<Harness> {
       store: createInMemoryModuleLifecycleStore(),
     },
     moduleConfiguration: moduleConfigurationOptionFor(modules),
+    moduleStorage: moduleStorageOptionFor(modules),
     dashboard: createInMemoryDashboardStore(),
     runtime,
     trustedOrigins: ["https://dashboard.example.test"],

apps/api/tests/module-ui-inventory.test.ts

@@ -33,6 +33,7 @@ import {
   moduleLifecycleSnapshotFor,
 } from "./support/in-memory-module-lifecycle.js";
 import { moduleConfigurationOptionFor } from "./support/in-memory-module-configuration.js";
+import { moduleStorageOptionFor } from "./support/in-memory-module-storage.js";
 
 const trustedOrigin = "https://dashboard.example.test";
 const viewerId = parseEkklesiaUserId("11111111-1111-4111-8111-111111111111");
@@ -179,6 +180,7 @@ async function install(options: InstallOptions): Promise<Installation> {
       store: createInMemoryModuleLifecycleStore(),
     },
     moduleConfiguration: moduleConfigurationOptionFor(modules),
+    moduleStorage: moduleStorageOptionFor(modules),
     dashboard: createInMemoryDashboardStore(),
     runtime,
     trustedOrigins: [trustedOrigin],

apps/api/tests/module-ui-routes.test.ts

@@ -33,6 +33,7 @@ import {
   moduleLifecycleSnapshotFor,
 } from "./support/in-memory-module-lifecycle.js";
 import { moduleConfigurationOptionFor } from "./support/in-memory-module-configuration.js";
+import { moduleStorageOptionFor } from "./support/in-memory-module-storage.js";
 
 const trustedOrigin = "https://dashboard.example.test";
 
@@ -179,6 +180,7 @@ async function install(fixtures: readonly ModuleFixture[]): Promise<Installation
       store: createInMemoryModuleLifecycleStore(),
     },
     moduleConfiguration: moduleConfigurationOptionFor(modules),
+    moduleStorage: moduleStorageOptionFor(modules),
     dashboard: createInMemoryDashboardStore(),
     runtime,
     trustedOrigins: [trustedOrigin],

apps/api/tests/support/in-memory-module-storage.ts

@@ -0,0 +1,195 @@
+import {
+  type ModuleStorage,
+  type ModuleStorageBody,
+  ModuleStorageError,
+  type ModuleStorageListOptions,
+  type ModuleStorageListing,
+  type ModuleStorageObject,
+  type ModuleStorageObjectMetadata,
+  type ModuleStoragePutOptions,
+} from "@ekklesia/contracts";
+import type { DiscoveredModule, ModuleStorageLookup } from "@ekklesia/core/modules";
+import { createModuleStorageLookup, type StorageProvider } from "@ekklesia/core/storage";
+
+/** Builds and drains Web streams without depending on DOM-only helper types, which this package's
+ * TypeScript configuration deliberately does not load. */
+function streamOf(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+async function collect(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    chunks.push(value);
+    total += value.byteLength;
+  }
+  const merged = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return merged;
+}
+
+interface StoredObject {
+  readonly bytes: Uint8Array;
+  readonly contentType?: string;
+  readonly lastModified: Date;
+}
+
+/**
+ * An in-memory `StorageProvider` for tests that exercise **wiring, scoping, and routing** rather
+ * than the S3 protocol.
+ *
+ * It implements the same interface the real S3 provider does, so everything above the provider seam
+ * — binding resolution, the scoped facade, lifecycle eligibility, route wiring — is exercised
+ * unchanged. What it deliberately does *not* reproduce is the protocol itself: real SeaweedFS
+ * semantics (non-idempotent `CreateBucket`, `NoSuchKey` vs `NoSuchBucket`, ETag quoting, streaming
+ * bodies) are proven against a live server in `core/tests/module-storage.integration.ts`, so this
+ * double can never quietly stand in for a provider guarantee nobody checked.
+ *
+ * It keys everything by **physical** bucket, exactly as the real provider does, which is what lets a
+ * test assert that two modules declaring the same logical name really did land in different
+ * namespaces.
+ */
+export function createInMemoryStorageProvider(): StorageProvider & {
+  readonly buckets: ReadonlyMap<string, Map<string, StoredObject>>;
+  ensureBucketCalls: number;
+} {
+  const buckets = new Map<string, Map<string, StoredObject>>();
+  const state = { ensureBucketCalls: 0 };
+
+  const objectsIn = (physicalBucket: string): Map<string, StoredObject> => {
+    const bucket = buckets.get(physicalBucket);
+    if (!bucket) {
+      throw new ModuleStorageError("STORAGE_BUCKET_UNAVAILABLE");
+    }
+    return bucket;
+  };
+
+  const metadataFor = (key: string, stored: StoredObject): ModuleStorageObjectMetadata =>
+    Object.freeze({
+      contentLength: stored.bytes.byteLength,
+      key,
+      lastModified: stored.lastModified,
+      ...(stored.contentType === undefined ? {} : { contentType: stored.contentType }),
+    });
+
+  const provider: StorageProvider = {
+    async close(): Promise<void> {
+      // Nothing to release.
+    },
+    async delete(physicalBucket: string, key: string): Promise<void> {
+      objectsIn(physicalBucket).delete(key);
+    },
+    async ensureBucket(physicalBucket: string): Promise<void> {
+      state.ensureBucketCalls += 1;
+      if (!buckets.has(physicalBucket)) {
+        buckets.set(physicalBucket, new Map());
+      }
+    },
+    async get(physicalBucket: string, key: string): Promise<ModuleStorageObject> {
+      const stored = objectsIn(physicalBucket).get(key);
+      if (!stored) {
+        throw new ModuleStorageError("STORAGE_OBJECT_NOT_FOUND", key);
+      }
+      return Object.freeze({
+        ...metadataFor(key, stored),
+        body: streamOf(stored.bytes),
+      });
+    },
+    async head(physicalBucket: string, key: string): Promise<ModuleStorageObjectMetadata> {
+      const stored = objectsIn(physicalBucket).get(key);
+      if (!stored) {
+        throw new ModuleStorageError("STORAGE_OBJECT_NOT_FOUND", key);
+      }
+      return metadataFor(key, stored);
+    },
+    async list(
+      physicalBucket: string,
+      options: ModuleStorageListOptions,
+    ): Promise<ModuleStorageListing> {
+      const entries = [...objectsIn(physicalBucket).entries()]
+        .filter(([key]) => options.prefix === undefined || key.startsWith(options.prefix))
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+      return Object.freeze({
+        objects: Object.freeze(entries.map(([key, stored]) => metadataFor(key, stored))),
+      });
+    },
+    async probe(): Promise<void> {
+      // Always reachable.
+    },
+    async put(
+      physicalBucket: string,
+      key: string,
+      body: ModuleStorageBody,
+      options: ModuleStoragePutOptions,
+    ): Promise<ModuleStorageObjectMetadata> {
+      const bytes =
+        typeof body === "string"
+          ? new TextEncoder().encode(body)
+          : body instanceof Uint8Array
+            ? body
+            : await collect(body as ReadableStream<Uint8Array>);
+      const stored: StoredObject = {
+        bytes,
+        lastModified: new Date(0),
+        ...(options.contentType === undefined ? {} : { contentType: options.contentType }),
+      };
+      objectsIn(physicalBucket).set(key, stored);
+      return metadataFor(key, stored);
+    },
+  };
+
+  return Object.assign(provider, {
+    buckets: buckets as ReadonlyMap<string, Map<string, StoredObject>>,
+    get ensureBucketCalls(): number {
+      return state.ensureBucketCalls;
+    },
+  });
+}
+
+export interface ModuleStorageOption {
+  readonly snapshots: ModuleStorageLookup;
+  readonly providerConfigured: boolean;
+}
+
+/**
+ * Builds the `createApiApp` storage option the same way `startApi` does — resolve every module's
+ * declared buckets against one provider and one prefix — rather than hand-writing a map, so a test
+ * can never assert against a shape the real composition would not produce.
+ */
+export function moduleStorageOptionFor(
+  discoveredModules: readonly DiscoveredModule[],
+  provider?: StorageProvider,
+): ModuleStorageOption {
+  return {
+    providerConfigured: provider !== undefined,
+    snapshots: createModuleStorageLookup(
+      provider,
+      "ekklesia",
+      discoveredModules.map((module) => ({
+        logicalBucketIds: module.manifest.storage.buckets.map((bucket) => bucket.id),
+        moduleId: module.manifest.id,
+      })),
+    ),
+  };
+}
+
+/** The storage option for a `createApiApp` caller that exercises no storage at all — the explicit
+ * "this installation has no object storage" statement the required option asks for. */
+export function emptyModuleStorage(): ModuleStorageOption {
+  return { providerConfigured: false, snapshots: new Map<string, ModuleStorage>() };
+}