@decaf-ts/integrations 0.11.0 → 0.12.0

package/lib/esm/shared/http/hermeticBoot.js

@@ -0,0 +1,146 @@
+/**
+ * @module integrations/shared/http/hermetic-boot
+ * @summary Environment-hermetic boot path for undecorated services used from graph nodes.
+ * @description Restores the Environment-hermeticity guarantee that was lost when
+ * the `nonEnvironmentService` wrappers were removed (SAA-1293 / DECAF-809): node
+ * execution must never inherit configuration from a service's Environment slice
+ * (SAA-1305 finding F1). {@link bootWithoutEnvironment} boots a service with an
+ * explicit config while temporarily shadowing the service's own
+ * `configFromEnvironment()` hook, so keys absent from the explicit config stay
+ * unset instead of silently picking up Environment-derived values (e.g. a
+ * `comms.email.allowPlaintextAuth` opt-in or an Environment `timeout` reaching an
+ * {@link HttpApiService} node boot).
+ */
+import { ValidationError } from "@decaf-ts/db-decorators";
+/**
+ * @description Name of the instance property shadowed for the hermetic boot
+ * @summary Matches the `configFromEnvironment()` hook base services use to read
+ * their Environment slice.
+ */
+const CONFIG_FROM_ENVIRONMENT = "configFromEnvironment";
+/**
+ * @description Per-instance scope registry for the hermetic boot shadow
+ * @summary WeakMap keyed by the service instance. Each entry records the
+ * service's original own `configFromEnvironment` property descriptor (`own`)
+ * together with a call depth (`depth`) counting the in-flight
+ * `bootWithoutEnvironment` calls on that instance. The first call on an
+ * instance creates the entry and installs the shadow; nested calls on the
+ * same instance only increment `depth` and never restore early; the entry is
+ * deleted and the original descriptor restored (or removed) when the outermost
+ * call completes, so overlapping calls on the same instance share a single
+ * shadow while the prototype is never touched.
+ */
+const shadowScopes = new WeakMap();
+/**
+ * @description Boots a service with Environment-derived configuration disabled
+ * @summary Node-side replacement for the removed `nonEnvironmentService`
+ * wrappers (SAA-1293): the service's own `configFromEnvironment()` property
+ * descriptor is shadowed with `() => undefined` for the duration of the
+ * `boot()` call and restored (or removed, when the service had no own
+ * descriptor) in `finally`, so configuration keys absent from
+ * the explicit config cannot inherit the service's Environment slice. The
+ * shadowing is per-instance (the prototype is never touched): a module-level
+ * `WeakMap` (`shadowScopes`) tracks each service's original
+ * `configFromEnvironment` descriptor together with a call depth, so
+ * overlapping or nested `bootWithoutEnvironment` calls on the same instance
+ * share a single shadow; a nested call only increments that depth and never
+ * restores the descriptor early, and the original descriptor is restored (or
+ * deleted) only when the outermost call completes. The helper fails closed:
+ * an explicit config object is mandatory, so a node boot can never silently
+ * fall back to Environment configuration. The SAA-1293 undecorated-service
+ * contract stands — no decoration, no wrapper classes, no `Injectables`
+ * registration.
+ * @template CONF The explicit configuration object type passed to `boot()`.
+ * @template S The undecorated service type being booted.
+ * @param {S} service - The undecorated service instance to boot.
+ * @param {CONF} config - Explicit configuration object for the boot; Environment-derived config is disabled for this call.
+ * @param {...unknown} rest - Remaining `boot()` arguments (e.g. a decaf `Context`), forwarded unchanged.
+ * @returns {Promise<S>} The same service instance, booted with only the explicit configuration.
+ * @throws {ValidationError} When `config` is missing or not an object.
+ * @example
+ * ```ts
+ * import { EmailService } from "@decaf-ts/integrations/comms/email";
+ * import { bootWithoutEnvironment } from "@decaf-ts/integrations/shared/http";
+ *
+ * const service = new EmailService();
+ * // The comms.email environment slice is ignored even when configured:
+ * // allowPlaintextAuth stays false unless the explicit config sets it.
+ * await bootWithoutEnvironment(service, {
+ *   provider: "smtp",
+ *   host: "smtp.example",
+ *   port: 587,
+ *   username: "user@example.com",
+ *   password: "secret",
+ * });
+ * ```
+ * @category Shared
+ * @memberOf module:integrations/shared/http/hermetic-boot
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Helper as bootWithoutEnvironment
+ *   participant Service as service
+ *   Caller->>Helper: bootWithoutEnvironment(service, config, ...rest)
+ *   activate Helper
+ *   alt config missing or not an object
+ *     Helper-->>Caller: ValidationError
+ *   else explicit config present
+ *     alt instance not yet shadowed
+ *       Helper->>Service: capture own configFromEnvironment descriptor
+ *       Helper->>Service: shadow own configFromEnvironment with () => undefined
+ *     else re-entrant call on the same instance
+ *       Helper->>Helper: increment shared scope depth
+ *     end
+ *     Helper->>Service: boot(config, ...rest)
+ *     activate Service
+ *     Service-->>Helper: boot completes
+ *     deactivate Service
+ *     alt outermost call (depth reaches 0)
+ *       Helper->>Service: restore or remove own configFromEnvironment descriptor
+ *     else nested call
+ *       Note over Helper,Service: shared shadow stays in place
+ *     end
+ *     Helper-->>Caller: service
+ *   end
+ *   deactivate Helper
+ */
+export async function bootWithoutEnvironment(service, config, ...rest) {
+    if (!config || typeof config !== "object") {
+        throw new ValidationError("Node service boot requires an explicit configuration object; Environment configuration is disabled for node services");
+    }
+    const target = service;
+    let scope = shadowScopes.get(target);
+    if (scope) {
+        scope.depth += 1;
+    }
+    else {
+        scope = {
+            own: Object.getOwnPropertyDescriptor(target, CONFIG_FROM_ENVIRONMENT),
+            depth: 1,
+        };
+        Object.defineProperty(target, CONFIG_FROM_ENVIRONMENT, {
+            configurable: true,
+            writable: true,
+            value: () => undefined,
+        });
+        shadowScopes.set(target, scope);
+    }
+    try {
+        await target.boot(config, ...rest);
+    }
+    finally {
+        scope.depth -= 1;
+        if (scope.depth === 0) {
+            shadowScopes.delete(target);
+            if (scope.own) {
+                Object.defineProperty(target, CONFIG_FROM_ENVIRONMENT, scope.own);
+            }
+            else {
+                delete target[CONFIG_FROM_ENVIRONMENT];
+            }
+        }
+    }
+    return service;
+}
+//# sourceMappingURL=hermeticBoot.js.map

package/lib/esm/shared/http/hermeticBoot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hermeticBoot.js","sourceRoot":"","sources":["../../../../src/shared/http/hermeticBoot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAW1D;;;;GAIG;AACH,MAAM,uBAAuB,GAAG,uBAAuB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,YAAY,GAAG,IAAI,OAAO,EAG7B,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAG1C,OAAU,EAAE,MAAY,EAAE,GAAG,IAAe;IAC5C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1C,MAAM,IAAI,eAAe,CACvB,sHAAsH,CACvH,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,OAAsC,CAAC;IACtD,IAAI,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACrC,IAAI,KAAK,EAAE,CAAC;QACV,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;IACnB,CAAC;SAAM,CAAC;QACN,KAAK,GAAG;YACN,GAAG,EAAE,MAAM,CAAC,wBAAwB,CAAC,MAAM,EAAE,uBAAuB,CAAC;YACrE,KAAK,EAAE,CAAC;SACT,CAAC;QACF,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,uBAAuB,EAAE;YACrD,YAAY,EAAE,IAAI;YAClB,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS;SACvB,CAAC,CAAC;QACH,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IACrC,CAAC;YAAS,CAAC;QACT,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;QACjB,IAAI,KAAK,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;YACtB,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC5B,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;gBACd,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,uBAAuB,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;YACpE,CAAC;iBAAM,CAAC;gBACN,OAAO,MAAM,CAAC,uBAAuB,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/lib/esm/shared/http/index.js

@@ -0,0 +1,11 @@
+/**
+ * @module integrations/shared/http
+ * @summary Shared HTTP plumbing for client-based API services.
+ * @description Re-exports {@link HttpApiService} (Axios-backed base class with
+ * environment-driven config), {@link httpError} (the failure-to-decaf-error
+ * mapper used by every API service), and {@link bootWithoutEnvironment} (the
+ * Environment-hermetic boot path used by as-graph node consumers).
+ */
+export * from "./HttpApiService.js";
+export * from "./hermeticBoot.js";
+//# sourceMappingURL=index.js.map

package/lib/esm/shared/http/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/shared/http/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,oCAAiC;AACjC,kCAA+B"}

package/lib/types/blob/azure/AzureBlobStoreService.d.cts

@@ -8,7 +8,7 @@ import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
 import { BlobStoreService } from "../core/BlobStoreService.d.cts";
 import type { AzureBlobStoreServiceConfig, BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListResult, BlobMetadata, BlobPutOptions, BlobPutResult, BlobUrlOptions, BlobUrlResult, BlobValue } from "../core/BlobTypes.d.cts";
 /**
- * @description Azure Blob storage service registered as `blob-azure`
+ * @description Undecorated Azure Blob storage service
  * @summary Stores blobs in an Azure Blob Storage container via
  * `@azure/storage-blob`, authenticating either with a connection string or
  * `DefaultAzureCredential`, and signing URLs with SAS tokens.
@@ -27,18 +27,18 @@ export declare class AzureBlobStoreService extends BlobStoreService<ContainerCli
     /**
      * @description Builds the Azure blob config from the environment
      * @summary Reads the `blobs.azure` environment slice; considered
-     * unconfigured when no `container` is set, which keeps the auto-boot
-     * fallback (see `getConfigFromArgs`) resolving to `undefined`.
+     * unconfigured when no `container` is set, in which case this returns
+     * `undefined` (see `getConfigFromArgs`).
      * @return {AzureBlobStoreServiceConfig | undefined} The environment-derived config, or `undefined` when unconfigured
      */
     protected configFromEnvironment(): AzureBlobStoreServiceConfig | undefined;
     /**
      * @description Initializes the Azure Blob container client
      * @summary Resolves the config via `getConfigFromArgs` (explicit config,
-     * then the `blobs.azure` environment slice). When no config resolves during
-     * a context-bearing auto-boot of an unconfigured provider, returns
-     * `skipInitialization()` so `Service.boot` does not throw; an explicit
-     * `initialize()` with no resolvable config still throws a
+     * then the `blobs.azure` environment slice). When no config resolves and
+     * the arguments carry a decaf `Context`, returns
+     * `skipInitialization()` so the context-bearing boot does not throw; an
+     * explicit `initialize()` with no resolvable config still throws a
      * `ValidationError`. Requires a `container`, builds the
      * `BlobServiceClient` from the connection string when present or from the
      * endpoint (defaulting to `https://<accountName>.blob.core.windows.net`)

package/lib/types/blob/azure/AzureBlobStoreService.d.mts

@@ -8,7 +8,7 @@ import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
 import { BlobStoreService } from "../core/BlobStoreService.d.mts";
 import type { AzureBlobStoreServiceConfig, BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListResult, BlobMetadata, BlobPutOptions, BlobPutResult, BlobUrlOptions, BlobUrlResult, BlobValue } from "../core/BlobTypes.d.mts";
 /**
- * @description Azure Blob storage service registered as `blob-azure`
+ * @description Undecorated Azure Blob storage service
  * @summary Stores blobs in an Azure Blob Storage container via
  * `@azure/storage-blob`, authenticating either with a connection string or
  * `DefaultAzureCredential`, and signing URLs with SAS tokens.
@@ -27,18 +27,18 @@ export declare class AzureBlobStoreService extends BlobStoreService<ContainerCli
     /**
      * @description Builds the Azure blob config from the environment
      * @summary Reads the `blobs.azure` environment slice; considered
-     * unconfigured when no `container` is set, which keeps the auto-boot
-     * fallback (see `getConfigFromArgs`) resolving to `undefined`.
+     * unconfigured when no `container` is set, in which case this returns
+     * `undefined` (see `getConfigFromArgs`).
      * @return {AzureBlobStoreServiceConfig | undefined} The environment-derived config, or `undefined` when unconfigured
      */
     protected configFromEnvironment(): AzureBlobStoreServiceConfig | undefined;
     /**
      * @description Initializes the Azure Blob container client
      * @summary Resolves the config via `getConfigFromArgs` (explicit config,
-     * then the `blobs.azure` environment slice). When no config resolves during
-     * a context-bearing auto-boot of an unconfigured provider, returns
-     * `skipInitialization()` so `Service.boot` does not throw; an explicit
-     * `initialize()` with no resolvable config still throws a
+     * then the `blobs.azure` environment slice). When no config resolves and
+     * the arguments carry a decaf `Context`, returns
+     * `skipInitialization()` so the context-bearing boot does not throw; an
+     * explicit `initialize()` with no resolvable config still throws a
      * `ValidationError`. Requires a `container`, builds the
      * `BlobServiceClient` from the connection string when present or from the
      * endpoint (defaulting to `https://<accountName>.blob.core.windows.net`)

package/lib/types/blob/core/BlobStoreService.d.cts

@@ -8,20 +8,21 @@ import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListR
 /**
  * @description Base abstraction for blob store client services
  * @summary Provides the shared key handling, URI composition, and
- * auto-boot-aware config resolution used by every provider backend
+ * boot-aware config resolution used by every provider backend
  * (memory, local filesystem, S3-compatible, Azure Blob, GCS, IPFS).
  *
- * Extends {@link ClientBasedService} so concrete providers are registered as
- * injectable services and auto-booted by `Service.boot`. During auto-boot the
- * framework passes a decaf `Context` instead of a blob config, so
- * {@link BlobStoreService.getConfigFromArgs} must distinguish the two: a real
- * config always carries a non-empty string `provider`, while a `Context` does
- * not. When neither an explicit config nor the provider's environment slice
- * resolves a config, a context-bearing auto-boot is skipped via
+ * Extends {@link ClientBasedService}. Decorated providers are registered as
+ * injectable services and auto-booted by `Service.boot`; undecorated providers
+ * are plain classes that consumers construct and boot explicitly. In a
+ * context-bearing boot the framework passes a decaf `Context` instead of a
+ * blob config, so {@link BlobStoreService.getConfigFromArgs} must distinguish
+ * the two: a real config always carries a non-empty string `provider`, while a
+ * `Context` does not. When neither an explicit config nor the provider's
+ * environment slice resolves a config, a context-bearing boot is skipped via
  * {@link BlobStoreService.skipInitialization} instead of throwing, so optional
- * providers (e.g. `blob-minio`/`blob-r2` registered alongside `blob-s3`) do not
- * block the rest of the service graph. An explicit `initialize()` call with no
- * resolvable config still fails loudly with a {@link ValidationError}.
+ * providers (e.g. an unconfigured `blob-minio`/`blob-r2` next to `blob-s3`) do
+ * not block the rest of the service graph. An explicit `initialize()` call
+ * with no resolvable config still fails loudly with a {@link ValidationError}.
  *
  * @template TClient - The provider-specific client type created by `initialize`
  * @template TConfig - The provider-specific config extending {@link BlobStoreServiceConfig}
@@ -32,7 +33,7 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
     /**
      * @description Initializes the base service
      * @summary Delegates to {@link ClientBasedService}; config and client are
-     * only set by a successful `initialize()` (or skipped on auto-boot).
+     * only set by a successful `initialize()` (or skipped on a context-bearing boot).
      */
     constructor();
     /**
@@ -54,9 +55,9 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
      * @summary Concrete providers resolve their config via
      * {@link BlobStoreService.getConfigFromArgs}, build the provider client, and
      * store both on `_config`/`_client`. When no config can be resolved during a
-     * context-bearing auto-boot, providers return
+     * context-bearing boot, providers return
      * {@link BlobStoreService.skipInitialization} instead of throwing.
-     * @param {...ContextualArg<any>} args - An optional blob config, optionally followed by a decaf `Context` (auto-boot always appends a `Context`)
+     * @param {...ContextualArg<any>} args - An optional blob config, optionally followed by a decaf `Context` (a context-bearing boot appends a `Context`)
      * @return {Promise<{config: TConfig, client: TClient}>} The resolved config and constructed client
      */
     abstract initialize(...args: ContextualArgs<any>): Promise<{
@@ -154,25 +155,25 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
     protected cleanKey(key: BlobKey): string;
     /**
      * @description Resolves the provider config from the initialize arguments or the provider's environment slice
-     * @summary `Service.boot` passes a decaf `Context` (not a blob config) to
-     * every registered `ClientBasedService`, so an object-shaped argument must
+     * @summary A context-bearing boot passes a decaf `Context` (not a blob
+     * config) to the service, so an object-shaped argument must
      * not blindly be treated as config. A real blob config always carries a
      * non-empty string `provider` (see {@link BlobStoreService.isConfigLike}).
      * Resolution order: explicit config argument, then the provider's
      * `configFromEnvironment()` slice. When neither resolves, `undefined` is
-     * returned only for a context-bearing auto-boot so an unconfigured provider
-     * (e.g. an optional `blob-minio`/`blob-r2` registered alongside `blob-s3`)
+     * returned only for a context-bearing boot so an unconfigured provider
+     * (e.g. an optional unconfigured `blob-minio`/`blob-r2` next to `blob-s3`)
      * does not block the whole service graph from booting; an explicit
      * `initialize()` with neither config nor environment still throws.
      *
      * @template TExpected - The provider-specific config type expected by the caller
      * @param {...MaybeContextualArg<any>} args - Initialize arguments: an optional blob config and/or a decaf `Context`
-     * @return {TExpected | undefined} The resolved config, or `undefined` when a context-bearing auto-boot has no resolvable config
+     * @return {TExpected | undefined} The resolved config, or `undefined` when a context-bearing boot has no resolvable config
      * @throws {ValidationError} When called explicitly (no `Context` in `args`) and no config argument or environment config is available
      *
      * @mermaid
      * sequenceDiagram
-     *   participant Caller as Service.boot / initialize()
+     *   participant Caller as boot() / initialize()
      *   participant Service as BlobStoreService
      *   participant Env as configFromEnvironment()
      *
@@ -190,7 +191,7 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
      *       Service-->>Caller: config
      *     else no env config
      *       Service->>Service: hasContext(args)
-     *       alt Context present (auto-boot)
+     *       alt Context present (context-bearing boot)
      *         Service-->>Caller: undefined (skip initialization)
      *       else explicit initialize()
      *         Service--xCaller: ValidationError
@@ -204,7 +205,7 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
      * @description Determines whether a value is a blob config object
      * @summary True only for an object that carries a non-empty string
      * `provider` and is not a decaf `Context`. Avoids mistaking a contextual
-     * argument (e.g. the `Context` that `Service.boot` passes) for the config.
+     * argument (e.g. the `Context` a context-bearing boot passes) for the config.
      * @param {unknown} value - The value to test
      * @return {boolean} `true` when the value is config-like
      */
@@ -221,8 +222,8 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
     protected isContextLike(value: unknown): boolean;
     /**
      * @description Determines whether the initialize arguments carry a decaf `Context`
-     * @summary A `Context` in the arguments marks a background auto-boot of an
-     * unconfigured provider (resolved to a skip by
+     * @summary A `Context` in the arguments marks a context-bearing background
+     * boot of an unconfigured provider (resolved to a skip by
      * {@link BlobStoreService.getConfigFromArgs}), as opposed to an explicit
      * `initialize()` that must fail loudly when no config is available.
      * @param {MaybeContextualArg<any>[]} args - The initialize arguments to inspect
@@ -230,17 +231,17 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
      */
     protected hasContext(args: MaybeContextualArg<any>): boolean;
     /**
-     * @description Skips initialization for an unconfigured provider during auto-boot
+     * @description Skips initialization for an unconfigured provider during a context-bearing boot
      * @summary Clears `_config`/`_client` and returns a `{ config, client }`
      * result compatible with the `ClientBasedService.initialize` signature so
-     * `Service.boot` completes without throwing. Leaves the service
+     * the boot completes without throwing. Leaves the service
      * deterministic: the `config`/`client` getters still throw if accessed until
      * the service is explicitly initialized with a resolvable config, and the
      * rest of the service graph is not blocked by this provider's absence.
      * Concrete providers invoke this from `initialize()` when
      * `getConfigFromArgs` resolves no config and cast the result to the
      * declared return type.
-     * @return {{config: undefined, client: undefined}} An unset config/client pair for the auto-boot path
+     * @return {{config: undefined, client: undefined}} An unset config/client pair for the skip path
      */
     protected skipInitialization(): {
         config: undefined;

package/lib/types/blob/core/BlobStoreService.d.mts

@@ -8,20 +8,21 @@ import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListR
 /**
  * @description Base abstraction for blob store client services
  * @summary Provides the shared key handling, URI composition, and
- * auto-boot-aware config resolution used by every provider backend
+ * boot-aware config resolution used by every provider backend
  * (memory, local filesystem, S3-compatible, Azure Blob, GCS, IPFS).
  *
- * Extends {@link ClientBasedService} so concrete providers are registered as
- * injectable services and auto-booted by `Service.boot`. During auto-boot the
- * framework passes a decaf `Context` instead of a blob config, so
- * {@link BlobStoreService.getConfigFromArgs} must distinguish the two: a real
- * config always carries a non-empty string `provider`, while a `Context` does
- * not. When neither an explicit config nor the provider's environment slice
- * resolves a config, a context-bearing auto-boot is skipped via
+ * Extends {@link ClientBasedService}. Decorated providers are registered as
+ * injectable services and auto-booted by `Service.boot`; undecorated providers
+ * are plain classes that consumers construct and boot explicitly. In a
+ * context-bearing boot the framework passes a decaf `Context` instead of a
+ * blob config, so {@link BlobStoreService.getConfigFromArgs} must distinguish
+ * the two: a real config always carries a non-empty string `provider`, while a
+ * `Context` does not. When neither an explicit config nor the provider's
+ * environment slice resolves a config, a context-bearing boot is skipped via
  * {@link BlobStoreService.skipInitialization} instead of throwing, so optional
- * providers (e.g. `blob-minio`/`blob-r2` registered alongside `blob-s3`) do not
- * block the rest of the service graph. An explicit `initialize()` call with no
- * resolvable config still fails loudly with a {@link ValidationError}.
+ * providers (e.g. an unconfigured `blob-minio`/`blob-r2` next to `blob-s3`) do
+ * not block the rest of the service graph. An explicit `initialize()` call
+ * with no resolvable config still fails loudly with a {@link ValidationError}.
  *
  * @template TClient - The provider-specific client type created by `initialize`
  * @template TConfig - The provider-specific config extending {@link BlobStoreServiceConfig}
@@ -32,7 +33,7 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
     /**
      * @description Initializes the base service
      * @summary Delegates to {@link ClientBasedService}; config and client are
-     * only set by a successful `initialize()` (or skipped on auto-boot).
+     * only set by a successful `initialize()` (or skipped on a context-bearing boot).
      */
     constructor();
     /**
@@ -54,9 +55,9 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
      * @summary Concrete providers resolve their config via
      * {@link BlobStoreService.getConfigFromArgs}, build the provider client, and
      * store both on `_config`/`_client`. When no config can be resolved during a
-     * context-bearing auto-boot, providers return
+     * context-bearing boot, providers return
      * {@link BlobStoreService.skipInitialization} instead of throwing.
-     * @param {...ContextualArg<any>} args - An optional blob config, optionally followed by a decaf `Context` (auto-boot always appends a `Context`)
+     * @param {...ContextualArg<any>} args - An optional blob config, optionally followed by a decaf `Context` (a context-bearing boot appends a `Context`)
      * @return {Promise<{config: TConfig, client: TClient}>} The resolved config and constructed client
      */
     abstract initialize(...args: ContextualArgs<any>): Promise<{
@@ -154,25 +155,25 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
     protected cleanKey(key: BlobKey): string;
     /**
      * @description Resolves the provider config from the initialize arguments or the provider's environment slice
-     * @summary `Service.boot` passes a decaf `Context` (not a blob config) to
-     * every registered `ClientBasedService`, so an object-shaped argument must
+     * @summary A context-bearing boot passes a decaf `Context` (not a blob
+     * config) to the service, so an object-shaped argument must
      * not blindly be treated as config. A real blob config always carries a
      * non-empty string `provider` (see {@link BlobStoreService.isConfigLike}).
      * Resolution order: explicit config argument, then the provider's
      * `configFromEnvironment()` slice. When neither resolves, `undefined` is
-     * returned only for a context-bearing auto-boot so an unconfigured provider
-     * (e.g. an optional `blob-minio`/`blob-r2` registered alongside `blob-s3`)
+     * returned only for a context-bearing boot so an unconfigured provider
+     * (e.g. an optional unconfigured `blob-minio`/`blob-r2` next to `blob-s3`)
      * does not block the whole service graph from booting; an explicit
      * `initialize()` with neither config nor environment still throws.
      *
      * @template TExpected - The provider-specific config type expected by the caller
      * @param {...MaybeContextualArg<any>} args - Initialize arguments: an optional blob config and/or a decaf `Context`
-     * @return {TExpected | undefined} The resolved config, or `undefined` when a context-bearing auto-boot has no resolvable config
+     * @return {TExpected | undefined} The resolved config, or `undefined` when a context-bearing boot has no resolvable config
      * @throws {ValidationError} When called explicitly (no `Context` in `args`) and no config argument or environment config is available
      *
      * @mermaid
      * sequenceDiagram
-     *   participant Caller as Service.boot / initialize()
+     *   participant Caller as boot() / initialize()
      *   participant Service as BlobStoreService
      *   participant Env as configFromEnvironment()
      *
@@ -190,7 +191,7 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
      *       Service-->>Caller: config
      *     else no env config
      *       Service->>Service: hasContext(args)
-     *       alt Context present (auto-boot)
+     *       alt Context present (context-bearing boot)
      *         Service-->>Caller: undefined (skip initialization)
      *       else explicit initialize()
      *         Service--xCaller: ValidationError
@@ -204,7 +205,7 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
      * @description Determines whether a value is a blob config object
      * @summary True only for an object that carries a non-empty string
      * `provider` and is not a decaf `Context`. Avoids mistaking a contextual
-     * argument (e.g. the `Context` that `Service.boot` passes) for the config.
+     * argument (e.g. the `Context` a context-bearing boot passes) for the config.
      * @param {unknown} value - The value to test
      * @return {boolean} `true` when the value is config-like
      */
@@ -221,8 +222,8 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
     protected isContextLike(value: unknown): boolean;
     /**
      * @description Determines whether the initialize arguments carry a decaf `Context`
-     * @summary A `Context` in the arguments marks a background auto-boot of an
-     * unconfigured provider (resolved to a skip by
+     * @summary A `Context` in the arguments marks a context-bearing background
+     * boot of an unconfigured provider (resolved to a skip by
      * {@link BlobStoreService.getConfigFromArgs}), as opposed to an explicit
      * `initialize()` that must fail loudly when no config is available.
      * @param {MaybeContextualArg<any>[]} args - The initialize arguments to inspect
@@ -230,17 +231,17 @@ export declare abstract class BlobStoreService<TClient = unknown, TConfig extend
      */
     protected hasContext(args: MaybeContextualArg<any>): boolean;
     /**
-     * @description Skips initialization for an unconfigured provider during auto-boot
+     * @description Skips initialization for an unconfigured provider during a context-bearing boot
      * @summary Clears `_config`/`_client` and returns a `{ config, client }`
      * result compatible with the `ClientBasedService.initialize` signature so
-     * `Service.boot` completes without throwing. Leaves the service
+     * the boot completes without throwing. Leaves the service
      * deterministic: the `config`/`client` getters still throw if accessed until
      * the service is explicitly initialized with a resolvable config, and the
      * rest of the service graph is not blocked by this provider's absence.
      * Concrete providers invoke this from `initialize()` when
      * `getConfigFromArgs` resolves no config and cast the result to the
      * declared return type.
-     * @return {{config: undefined, client: undefined}} An unset config/client pair for the auto-boot path
+     * @return {{config: undefined, client: undefined}} An unset config/client pair for the skip path
      */
     protected skipInitialization(): {
         config: undefined;

package/lib/types/blob/gcp/GcsBlobStoreService.d.cts

@@ -8,7 +8,7 @@ import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
 import { BlobStoreService } from "../core/BlobStoreService.d.cts";
 import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListResult, BlobMetadata, BlobPutOptions, BlobPutResult, BlobUrlOptions, BlobUrlResult, BlobValue, GcsBlobStoreServiceConfig } from "../core/BlobTypes.d.cts";
 /**
- * @description Google Cloud Storage blob store service registered as `blob-gcs`
+ * @description Undecorated Google Cloud Storage blob store service
  * @summary Stores blobs in a GCS bucket via `@google-cloud/storage`,
  * authenticating with optional explicit credentials or the environment's
  * application default credentials.
@@ -26,18 +26,18 @@ export declare class GcsBlobStoreService extends BlobStoreService<Bucket, GcsBlo
     /**
      * @description Builds the GCS blob config from the environment
      * @summary Reads the `blobs.gcs` environment slice; considered
-     * unconfigured when no `bucket` is set, which keeps the auto-boot
-     * fallback (see `getConfigFromArgs`) resolving to `undefined`.
+     * unconfigured when no `bucket` is set, in which case this returns
+     * `undefined` (see `getConfigFromArgs`).
      * @return {GcsBlobStoreServiceConfig | undefined} The environment-derived config, or `undefined` when unconfigured
      */
     protected configFromEnvironment(): GcsBlobStoreServiceConfig | undefined;
     /**
      * @description Initializes the GCS bucket client
      * @summary Resolves the config via `getConfigFromArgs` (explicit config,
-     * then the `blobs.gcs` environment slice). When no config resolves during a
-     * context-bearing auto-boot of an unconfigured provider, returns
-     * `skipInitialization()` so `Service.boot` does not throw; an explicit
-     * `initialize()` with no resolvable config still throws a
+     * then the `blobs.gcs` environment slice). When no config resolves and the
+     * arguments carry a decaf `Context`, returns
+     * `skipInitialization()` so the context-bearing boot does not throw; an
+     * explicit `initialize()` with no resolvable config still throws a
      * `ValidationError`. Requires a `bucket`, builds the `Storage` client with
      * the configured project ID, credentials, and API endpoint, and stores the
      * bucket client.

package/lib/types/blob/gcp/GcsBlobStoreService.d.mts

@@ -8,7 +8,7 @@ import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
 import { BlobStoreService } from "../core/BlobStoreService.d.mts";
 import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListResult, BlobMetadata, BlobPutOptions, BlobPutResult, BlobUrlOptions, BlobUrlResult, BlobValue, GcsBlobStoreServiceConfig } from "../core/BlobTypes.d.mts";
 /**
- * @description Google Cloud Storage blob store service registered as `blob-gcs`
+ * @description Undecorated Google Cloud Storage blob store service
  * @summary Stores blobs in a GCS bucket via `@google-cloud/storage`,
  * authenticating with optional explicit credentials or the environment's
  * application default credentials.
@@ -26,18 +26,18 @@ export declare class GcsBlobStoreService extends BlobStoreService<Bucket, GcsBlo
     /**
      * @description Builds the GCS blob config from the environment
      * @summary Reads the `blobs.gcs` environment slice; considered
-     * unconfigured when no `bucket` is set, which keeps the auto-boot
-     * fallback (see `getConfigFromArgs`) resolving to `undefined`.
+     * unconfigured when no `bucket` is set, in which case this returns
+     * `undefined` (see `getConfigFromArgs`).
      * @return {GcsBlobStoreServiceConfig | undefined} The environment-derived config, or `undefined` when unconfigured
      */
     protected configFromEnvironment(): GcsBlobStoreServiceConfig | undefined;
     /**
      * @description Initializes the GCS bucket client
      * @summary Resolves the config via `getConfigFromArgs` (explicit config,
-     * then the `blobs.gcs` environment slice). When no config resolves during a
-     * context-bearing auto-boot of an unconfigured provider, returns
-     * `skipInitialization()` so `Service.boot` does not throw; an explicit
-     * `initialize()` with no resolvable config still throws a
+     * then the `blobs.gcs` environment slice). When no config resolves and the
+     * arguments carry a decaf `Context`, returns
+     * `skipInitialization()` so the context-bearing boot does not throw; an
+     * explicit `initialize()` with no resolvable config still throws a
      * `ValidationError`. Requires a `bucket`, builds the `Storage` client with
      * the configured project ID, credentials, and API endpoint, and stores the
      * bucket client.

package/lib/types/blob/s3/S3BlobStoreService.d.cts

@@ -1,12 +1,20 @@
 /**
  * @module integrations/blob/s3/service
  * @summary AWS S3 blob store service.
- * @description Thin `@service`-decorated provider on top of {@link S3CompatibleBlobStoreService}.
+ * @description Thin undecorated AWS S3 provider service on top of {@link S3CompatibleBlobStoreService}.
  */
 import { ContextualArgs } from "@decaf-ts/core";
 import { S3CompatibleBlobStoreService } from "./S3CompatibleBlobStoreService.d.cts";
 import type { S3BlobStoreServiceConfig } from "../core/BlobTypes.d.cts";
 import { S3Client } from "@aws-sdk/client-s3";
+/**
+ * @description AWS S3 blob store service
+ * @summary Undecorated provider service storing blobs in an AWS S3 bucket
+ * through {@link S3CompatibleBlobStoreService}. Falls back to the `blobs.s3`
+ * environment slice when `initialize()` is called without an explicit config.
+ * @class S3BlobStoreService
+ * @memberOf module:integrations/blob/s3/service
+ */
 export declare class S3BlobStoreService extends S3CompatibleBlobStoreService {
     protected configFromEnvironment(): S3BlobStoreServiceConfig | undefined;
     initialize(...args: ContextualArgs<any>): Promise<{

package/lib/types/blob/s3/S3BlobStoreService.d.mts

@@ -1,12 +1,20 @@
 /**
  * @module integrations/blob/s3/service
  * @summary AWS S3 blob store service.
- * @description Thin `@service`-decorated provider on top of {@link S3CompatibleBlobStoreService}.
+ * @description Thin undecorated AWS S3 provider service on top of {@link S3CompatibleBlobStoreService}.
  */
 import { ContextualArgs } from "@decaf-ts/core";
 import { S3CompatibleBlobStoreService } from "./S3CompatibleBlobStoreService.d.mts";
 import type { S3BlobStoreServiceConfig } from "../core/BlobTypes.d.mts";
 import { S3Client } from "@aws-sdk/client-s3";
+/**
+ * @description AWS S3 blob store service
+ * @summary Undecorated provider service storing blobs in an AWS S3 bucket
+ * through {@link S3CompatibleBlobStoreService}. Falls back to the `blobs.s3`
+ * environment slice when `initialize()` is called without an explicit config.
+ * @class S3BlobStoreService
+ * @memberOf module:integrations/blob/s3/service
+ */
 export declare class S3BlobStoreService extends S3CompatibleBlobStoreService {
     protected configFromEnvironment(): S3BlobStoreServiceConfig | undefined;
     initialize(...args: ContextualArgs<any>): Promise<{