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]>

core/src/modules/lifecycle.ts

@@ -62,7 +62,59 @@ export interface ModuleConfigurationBlockedDetail {
   readonly configurationKey: string;
 }
 
-export type ModuleBlockedDetail = ModuleDependencyBlockedDetail | ModuleConfigurationBlockedDetail;
+/** A block caused by unsatisfiable object-storage requirements (ADR 0030), naming the **logical**
+ * bucket the module declared — never an endpoint, a credential, or a physical bucket name. */
+export interface ModuleStorageBlockedDetail {
+  readonly reason: "storage_unavailable";
+  readonly storageBucketId: string;
+}
+
+export type ModuleBlockedDetail =
+  | ModuleDependencyBlockedDetail
+  | ModuleConfigurationBlockedDetail
+  | ModuleStorageBlockedDetail;
+
+/** Narrows a block to the dependency variant. Exported so every consumer discriminates the same
+ * way — a bare `"dependency" in detail` repeated at each call site is how one of them eventually
+ * gets it wrong as variants are added. */
+export function isDependencyBlockedDetail(
+  detail: ModuleBlockedDetail,
+): detail is ModuleDependencyBlockedDetail {
+  return (
+    detail.reason === "required_dependency_disabled" ||
+    detail.reason === "required_dependency_blocked"
+  );
+}
+
+export function isStorageBlockedDetail(
+  detail: ModuleBlockedDetail,
+): detail is ModuleStorageBlockedDetail {
+  return detail.reason === "storage_unavailable";
+}
+
+export function isConfigurationBlockedDetail(
+  detail: ModuleBlockedDetail,
+): detail is ModuleConfigurationBlockedDetail {
+  return (
+    detail.reason === "configuration_missing" ||
+    detail.reason === "configuration_invalid" ||
+    detail.reason === "secret_missing"
+  );
+}
+
+/**
+ * Whether this host can bind the logical object-storage buckets modules declare (ADR 0030).
+ *
+ * A boolean, deliberately, and resolved without touching the network: eligibility must stay a pure,
+ * synchronous function, and it must never depend on whether the storage service happened to answer a
+ * probe during boot. A configured provider that is temporarily unreachable is an operational
+ * condition a module retries through, not an administrative state change — which is the distinction
+ * the real Announcements product already relies on, since its slideshow survives its object store
+ * going away.
+ */
+export interface ModuleStorageAvailability {
+  readonly providerConfigured: boolean;
+}
 
 export interface ModuleEligibilityResolution {
   /**
@@ -108,10 +160,15 @@ function frozenEligibility(entry: MutableEligibility): ModuleEligibility {
                   dependency: Object.freeze({ ...entry.blocked.dependency }),
                   reason: entry.blocked.reason,
                 })
-              : Object.freeze({
-                  configurationKey: entry.blocked.configurationKey,
-                  reason: entry.blocked.reason,
-                }),
+              : "storageBucketId" in entry.blocked
+                ? Object.freeze({
+                    reason: entry.blocked.reason,
+                    storageBucketId: entry.blocked.storageBucketId,
+                  })
+                : Object.freeze({
+                    configurationKey: entry.blocked.configurationKey,
+                    reason: entry.blocked.reason,
+                  }),
         }
       : {}),
   });
@@ -162,6 +219,7 @@ export function resolveModuleEligibility(
   discoveredModules: readonly DiscoveredModule[],
   configuration: ModuleLifecycleConfiguration,
   moduleConfiguration: ModuleConfigurationInput = { settings: { records: [] } },
+  storage: ModuleStorageAvailability = { providerConfigured: false },
 ): ModuleEligibilityResolution {
   const configuredByModuleId = new Map(
     configuration.modules.map((record) => [record.moduleId, record.enabled] as const),
@@ -180,6 +238,26 @@ export function resolveModuleEligibility(
     });
   }
 
+  // A module that declares logical object-storage buckets needs a host provider to bind them to. The
+  // check is deliberately about *binding availability*, not provider health: it asks whether this
+  // deployment has storage configured at all, never whether the service answered just now
+  // (ADR 0030). Runs before the dependency pass so a storage-blocked module propagates to its
+  // required dependents through exactly the existing mechanism rather than a second one.
+  for (const discovered of discoveredModules) {
+    const entry = entries.get(discovered.manifest.id);
+    if (!entry?.eligible) {
+      continue;
+    }
+    const declaredBucket = discovered.manifest.storage.buckets[0];
+    if (declaredBucket !== undefined && !storage.providerConfigured) {
+      entry.eligible = false;
+      entry.blocked = {
+        reason: "storage_unavailable",
+        storageBucketId: declaredBucket.id,
+      };
+    }
+  }
+
   // Validate each enabled module's own configuration before the dependency pass, so a module
   // blocked by its own configuration propagates to its required dependents through exactly the
   // existing mechanism rather than a second one. Runs only for modules that are still eligible: a
@@ -306,6 +384,9 @@ export interface ModuleLifecycleView {
     readonly dependency?: ModuleBlockingDependency;
     /** Present for a configuration reason (ADR 0029) — the offending key, never its value. */
     readonly configurationKey?: string;
+    /** Present for a storage reason (ADR 0030) — the logical bucket the module declared, never an
+     * endpoint, a credential, or a physical bucket name. */
+    readonly storageBucketId?: string;
   };
   /**
    * `true` when applying the *current* configuration would produce a different running set than
@@ -347,6 +428,7 @@ export function resolveModuleLifecycleView(
   snapshot: ModuleLifecycleSnapshot,
   configuration: ModuleLifecycleConfiguration,
   moduleConfiguration: ModuleConfigurationInput = { settings: { records: [] } },
+  storage: ModuleStorageAvailability = { providerConfigured: false },
 ): readonly ModuleLifecycleView[] {
   const started = new Set(snapshot.startedModuleIds);
   const bootEligibility = new Map(
@@ -361,6 +443,7 @@ export function resolveModuleLifecycleView(
     snapshot.discoveredModules,
     configuration,
     moduleConfiguration,
+    storage,
   );
   const wouldRun = new Set(pending.eligibleModules.map((module) => module.manifest.id));
 
@@ -379,11 +462,17 @@ export function resolveModuleLifecycleView(
                   reason: boot.blocked.reason,
                   state: "blocked" as const,
                 }
-              : {
-                  configurationKey: boot.blocked.configurationKey,
-                  reason: boot.blocked.reason,
-                  state: "blocked" as const,
-                }
+              : "storageBucketId" in boot.blocked
+                ? {
+                    reason: boot.blocked.reason,
+                    state: "blocked" as const,
+                    storageBucketId: boot.blocked.storageBucketId,
+                  }
+                : {
+                    configurationKey: boot.blocked.configurationKey,
+                    reason: boot.blocked.reason,
+                    state: "blocked" as const,
+                  }
             : // Enabled and unblocked at boot, yet not started: unreachable while startup stays
               // all-or-nothing, and reported as blocked-by-nothing rather than as `running`, so a
               // future change to startup atomicity can never make this silently claim success.

core/src/modules/runtime.ts

@@ -2,7 +2,9 @@ import { pathToFileURL } from "node:url";
 import {
   type CapabilityId,
   EMPTY_MODULE_CONFIGURATION,
+  EMPTY_MODULE_STORAGE,
   type ModuleConfiguration,
+  type ModuleStorage,
   type CapabilityRegistrar,
   type CapabilityResolver,
   capabilityIdSchema,
@@ -96,6 +98,20 @@ function configurationFor(
   return configurations.get(moduleId) ?? EMPTY_MODULE_CONFIGURATION;
 }
 
+/**
+ * Per-module scoped object storage, keyed by module id (ADR 0030).
+ *
+ * A lookup for the same reason configuration is one, and emphatically **not** a field on
+ * `ModuleRuntimeServices`: `services` is one shared object identity every module receives, while a
+ * storage facade is scoped to exactly the buckets one module declared. Sharing it would hand every
+ * module every other module's storage.
+ */
+export type ModuleStorageLookup = ReadonlyMap<string, ModuleStorage>;
+
+function storageFor(storages: ModuleStorageLookup, moduleId: string): ModuleStorage {
+  return storages.get(moduleId) ?? EMPTY_MODULE_STORAGE;
+}
+
 export interface ModuleRuntimeTimeoutOptions {
   /** Test-only narrowing of `MODULE_STOP_HOOK_TIMEOUT_MS`, applied to both normal stop and startup
    * rollback, so a deadline can be proven in milliseconds instead of ten seconds. Production
@@ -115,6 +131,12 @@ export interface ModuleRuntimeCompositionOptions extends ModuleRuntimeTimeoutOpt
    * `EMPTY_MODULE_CONFIGURATION`.
    */
   readonly configurations?: ModuleConfigurationLookup;
+  /**
+   * The per-module scoped storage facades this runtime hands to each module's `start`, `stop`, and
+   * HTTP handler contexts (ADR 0030). Omitted by a caller exercising no storage; every module then
+   * receives `EMPTY_MODULE_STORAGE`, which refuses every bucket.
+   */
+  readonly storages?: ModuleStorageLookup;
 }
 
 export interface StartModuleRuntimeOptions
@@ -257,6 +279,7 @@ class StagedCapabilityRegistry {
     phase: "rollback" | "start" | "stop",
     services: ModuleRuntimeServices,
     config: ModuleConfiguration,
+    storage: ModuleStorage,
   ): ModuleRuntimeContext {
     const capabilities: CapabilityResolver = Object.freeze({
       resolve: (capabilityId: CapabilityId): RegisteredCapability | undefined => {
@@ -264,7 +287,13 @@ class StagedCapabilityRegistry {
         return this.#registered.get(capabilityId);
       },
     });
-    return Object.freeze({ capabilities, config, moduleId: module.manifest.id, services });
+    return Object.freeze({
+      capabilities,
+      config,
+      moduleId: module.manifest.id,
+      services,
+      storage,
+    });
   }
 
   publish(): CapabilityRegistry {
@@ -599,6 +628,7 @@ async function stopModules(
   phase: "rollback" | "stop",
   services: ModuleRuntimeServices,
   configurations: ModuleConfigurationLookup,
+  storages: ModuleStorageLookup,
   options: StopModulesOptions = {},
 ): Promise<readonly ModuleRuntimeIssue[]> {
   const timeoutMs = options.hookTimeoutMs ?? MODULE_STOP_HOOK_TIMEOUT_MS;
@@ -619,6 +649,7 @@ async function stopModules(
               phase,
               services,
               configurationFor(configurations, moduleId),
+              storageFor(storages, moduleId),
             ),
           ),
         ),
@@ -657,6 +688,7 @@ async function startModules(
   registry: StagedCapabilityRegistry,
   services: ModuleRuntimeServices,
   configurations: ModuleConfigurationLookup,
+  storages: ModuleStorageLookup,
   options: StopModulesOptions = {},
 ): Promise<void> {
   // A module joins the rollback set the moment its `start` hook is *invoked*, not when it
@@ -675,6 +707,7 @@ async function startModules(
           "start",
           services,
           configurationFor(configurations, module.discovered.manifest.id),
+          storageFor(storages, module.discovered.manifest.id),
         ),
       );
     } catch (error) {
@@ -693,6 +726,7 @@ async function startModules(
         "rollback",
         services,
         configurations,
+        storages,
         options,
       );
       throw new ModuleRuntimeError([startIssue, ...rollbackIssues]);
@@ -717,8 +751,9 @@ export async function startDiscoveredModuleRuntime(
   const capabilityRegistry = new StagedCapabilityRegistry();
   const httpRoutes = new StagedModuleHttpRoutes();
   const configurations = timeouts.configurations ?? new Map<string, ModuleConfiguration>();
+  const storages = timeouts.storages ?? new Map<string, ModuleStorage>();
   await registerModules(modules, capabilityRegistry, httpRoutes, configurations);
-  await startModules(modules, capabilityRegistry, services, configurations, timeouts);
+  await startModules(modules, capabilityRegistry, services, configurations, storages, timeouts);
 
   const capabilities = capabilityRegistry.publish();
   const routes = httpRoutes.publish();
@@ -744,6 +779,7 @@ export async function startDiscoveredModuleRuntime(
           "stop",
           services,
           configurations,
+          storages,
           timeouts,
         );
         if (issues.length > 0) {
@@ -761,6 +797,7 @@ export async function startModuleRuntime(
   const discovered = await discoverModules(options);
   return startDiscoveredModuleRuntime(discovered, options.services, {
     ...(options.configurations === undefined ? {} : { configurations: options.configurations }),
+    ...(options.storages === undefined ? {} : { storages: options.storages }),
     ...(options.hookTimeoutMs === undefined ? {} : { hookTimeoutMs: options.hookTimeoutMs }),
   });
 }