alchemy 2.0.0-beta.75 → 2.0.0-beta.77

package/src/AWS/Batch/JobDefinition.ts

@@ -170,12 +170,10 @@ export interface JobDefinitionProps extends PlatformProps {
    */
   propagateTags?: boolean;
   /**
-   * Bundler configuration for the Effect-native entrypoint: rolldown
-   * `input`/`output` overrides plus pure-annotation options (`pure`).
-   * `effect`, `@effect/*`, `alchemy`, `@alchemy.run/*`, and
-   * `@distilled.cloud/*` are annotated as pure by default so unused code
-   * from those packages is tree-shaken; list additional packages via
-   * `pure.packages`, or disable with `pure: false`.
+   * Bundler configuration for the Effect-native entrypoint. Unused
+   * code is tree-shaken. `effect`, alchemy, and `@distilled.cloud` are
+   * marked pure so unused parts prune more aggressively. List extra
+   * packages with `pure.packages`, or disable with `pure: false`.
    */
   build?: Bundle.BundleConfig;
   /**
@@ -358,16 +356,13 @@ const createJobDefinitionRuntimeContext = (
  * ```
  *
  * ### Bundling & Tree-shaking
- * `main` is bundled with rolldown at deploy time. Top-level calls in the
- * `effect`, `@effect/*`, `alchemy`, `@alchemy.run/*`, and
- * `@distilled.cloud/*` packages receive `#__PURE__` annotations by
- * default, so anything the job doesn't use from those packages is
- * tree-shaken out of the bundle. Any other package — including your own
- * app — is left untouched unless you list it explicitly.
+ * `main` is bundled with rolldown at deploy time. Unused code is
+ * tree-shaken. `effect`, alchemy, and `@distilled.cloud` are marked
+ * pure so unused parts prune more aggressively. Your app is not
+ * marked pure.
  *
- * **Example:** Treat additional packages as pure
- * Pass package names (or picomatch globs) via `build.pure.packages` to
- * annotate them in addition to the defaults.
+ * **Example:** Mark additional packages as pure
+ * Only list packages with no top-level side effects.
  * ```typescript
  * {
  *   main: import.meta.url,
@@ -377,18 +372,7 @@ const createJobDefinitionRuntimeContext = (
  * }
  * ```
  *
- * Listing a package annotates calls whose result is bound (variable
- * initializers, exports) — safe anywhere. If a listed package also
- * declares `"sideEffects": false` (or `[]`) in its `package.json`, that
- * combination opts it into full annotation: top-level calls whose result
- * is discarded (e.g. `router.on("/path", handler)` registrations) are
- * also marked pure and deleted under minification when unused. Only list
- * a `sideEffects: false` package if its modules really are free of
- * meaningful top-level side effects. The `effect`, `alchemy`, and
- * `@distilled.cloud` defaults declare exactly that, on purpose — their
- * modules are designed to be fully tree-shakeable.
- *
- * **Example:** Disable pure annotations
+ * **Example:** Turn it off
  * ```typescript
  * {
  *   main: import.meta.url,

package/src/AWS/Cognito/ManagedLoginBranding.ts

@@ -0,0 +1,339 @@
+import * as cip from "@distilled.cloud/aws/cognito-identity-provider";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import { isResolved } from "../../Diff.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import type { Providers } from "../Providers.ts";
+
+/**
+ * An image asset (logo, favicon, background, …) attached to a managed login
+ * branding style, per color mode.
+ */
+export interface ManagedLoginBrandingAsset {
+  /** Which slot of the managed login pages the asset fills. */
+  category:
+    | "FAVICON_ICO"
+    | "FAVICON_SVG"
+    | "EMAIL_GRAPHIC"
+    | "SMS_GRAPHIC"
+    | "AUTH_APP_GRAPHIC"
+    | "PASSWORD_GRAPHIC"
+    | "PASSKEY_GRAPHIC"
+    | "PAGE_HEADER_LOGO"
+    | "PAGE_HEADER_BACKGROUND"
+    | "PAGE_FOOTER_LOGO"
+    | "PAGE_FOOTER_BACKGROUND"
+    | "PAGE_BACKGROUND"
+    | "FORM_BACKGROUND"
+    | "FORM_LOGO"
+    | "IDP_BUTTON_ICON";
+  /** The color scheme the asset applies to. */
+  colorMode: "LIGHT" | "DARK" | "DYNAMIC";
+  /** The file type of the asset. */
+  extension: "ICO" | "JPEG" | "PNG" | "SVG" | "WEBP";
+  /** The image file, as bytes (max 2 MB). */
+  bytes?: Uint8Array;
+  /** For `IDP_BUTTON_ICON` assets, the identity provider the icon is for. */
+  resourceId?: string;
+}
+
+export interface ManagedLoginBrandingProps {
+  /**
+   * The ID of the user pool the branding style belongs to. Changing this
+   * triggers a replacement.
+   */
+  userPoolId: string;
+  /**
+   * The ID of the app client the branding style is assigned to. Each app
+   * client can have exactly one style. Changing this triggers a
+   * replacement.
+   */
+  clientId: string;
+  /**
+   * Apply Cognito's default branding instead of custom `settings` /
+   * `assets`. This is what makes a fresh pool's managed login pages render
+   * without a one-time console step.
+   * @default true when neither `settings` nor `assets` is provided
+   */
+  useCognitoProvidedValues?: boolean;
+  /**
+   * The branding settings JSON document (colors, component styles, …) in
+   * the shape produced by the managed login branding designer / returned by
+   * `DescribeManagedLoginBranding`.
+   */
+  settings?: Record<string, unknown>;
+  /**
+   * Image assets for the branding style (logos, favicons, backgrounds),
+   * one per category + color mode.
+   */
+  assets?: ManagedLoginBrandingAsset[];
+}
+
+export interface ManagedLoginBranding extends Resource<
+  "AWS.Cognito.ManagedLoginBranding",
+  ManagedLoginBrandingProps,
+  {
+    /** The generated ID of the branding style. */
+    managedLoginBrandingId: string;
+    /** The ID of the user pool the style belongs to. */
+    userPoolId: string;
+    /** The ID of the app client the style is assigned to. */
+    clientId: string;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * A managed login branding style for an Amazon Cognito user pool app
+ * client. Assigning a style (even just Cognito's provided defaults) is what
+ * activates the hosted managed login pages — a `UserPoolDomain` with
+ * `managedLoginVersion: 2` serves them end-to-end without any console step.
+ * ### Activating Managed Login
+ * **Example:** Default Branding for a Hosted Login Domain
+ * ```typescript
+ * import * as Cognito from "alchemy/AWS/Cognito";
+ *
+ * const pool = yield* Cognito.UserPool("Users", {});
+ * const client = yield* Cognito.UserPoolClient("Web", {
+ *   userPoolId: pool.userPoolId,
+ *   callbackUrls: ["https://example.com/callback"],
+ *   allowedOAuthFlowsUserPoolClient: true,
+ *   allowedOAuthFlows: ["code"],
+ *   allowedOAuthScopes: ["openid", "email"],
+ * });
+ * const domain = yield* Cognito.UserPoolDomain("AuthDomain", {
+ *   userPoolId: pool.userPoolId,
+ *   managedLoginVersion: 2,
+ * });
+ * yield* Cognito.ManagedLoginBranding("Branding", {
+ *   userPoolId: pool.userPoolId,
+ *   clientId: client.clientId,
+ * });
+ * ```
+ *
+ * ### Custom Branding
+ * **Example:** Custom Settings and a Logo Asset
+ * ```typescript
+ * yield* Cognito.ManagedLoginBranding("Branding", {
+ *   userPoolId: pool.userPoolId,
+ *   clientId: client.clientId,
+ *   settings: brandingSettings, // designer-exported JSON document
+ *   assets: [{
+ *     category: "FORM_LOGO",
+ *     colorMode: "LIGHT",
+ *     extension: "PNG",
+ *     bytes: logoBytes,
+ *   }],
+ * });
+ * ```
+ *
+ * @resource
+ */
+export const ManagedLoginBranding = Resource<ManagedLoginBranding>(
+  "AWS.Cognito.ManagedLoginBranding",
+);
+
+const toWireAssets = (
+  assets: ManagedLoginBrandingAsset[] | undefined,
+): cip.AssetType[] | undefined =>
+  assets?.map((asset) => ({
+    Category: asset.category,
+    ColorMode: asset.colorMode,
+    Extension: asset.extension,
+    Bytes: asset.bytes,
+    ResourceId: asset.resourceId,
+  }));
+
+/** Canonicalize an asset list for order-insensitive comparison; bytes are
+ * folded to base64. */
+const canonicalAssets = (assets: cip.AssetType[] | undefined) =>
+  (assets ?? [])
+    .map((asset) =>
+      [
+        asset.Category,
+        asset.ColorMode,
+        asset.Extension,
+        asset.ResourceId ?? "",
+        asset.Bytes === undefined
+          ? ""
+          : Buffer.from(asset.Bytes).toString("base64"),
+      ].join(":"),
+    )
+    .sort()
+    .join(",");
+
+/**
+ * Whether the style should carry Cognito's provided default values: an
+ * explicit prop wins, otherwise defaults to `true` exactly when no custom
+ * settings/assets are declared.
+ */
+const desiredUseProvidedValues = (news: ManagedLoginBrandingProps) =>
+  news.useCognitoProvidedValues ??
+  (news.settings === undefined && news.assets === undefined);
+
+/**
+ * Bounded retry over the concurrent-modification window (branding updates
+ * can race domain/pool operations). Explicitly typed so the conditional
+ * `Retry.Return` type never leaks into declaration emit.
+ */
+const retryWhileConcurrent = <A, E extends { _tag: string }, R>(
+  self: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R> =>
+  Effect.retry(self, {
+    while: (e) => e._tag === "ConcurrentModificationException",
+    schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(10)]),
+  });
+
+export const ManagedLoginBrandingProvider = () =>
+  Provider.effect(
+    ManagedLoginBranding,
+    Effect.gen(function* () {
+      const describeById = Effect.fn(function* (
+        userPoolId: string,
+        managedLoginBrandingId: string,
+      ) {
+        return yield* cip
+          .describeManagedLoginBranding({
+            UserPoolId: userPoolId,
+            ManagedLoginBrandingId: managedLoginBrandingId,
+          })
+          .pipe(
+            Effect.map((r) => r.ManagedLoginBranding),
+            Effect.catchTag("ResourceNotFoundException", () =>
+              Effect.succeed(undefined),
+            ),
+          );
+      });
+
+      const describeByClient = Effect.fn(function* (
+        userPoolId: string,
+        clientId: string,
+      ) {
+        return yield* cip
+          .describeManagedLoginBrandingByClient({
+            UserPoolId: userPoolId,
+            ClientId: clientId,
+          })
+          .pipe(
+            Effect.map((r) => r.ManagedLoginBranding),
+            Effect.catchTag("ResourceNotFoundException", () =>
+              Effect.succeed(undefined),
+            ),
+          );
+      });
+
+      return ManagedLoginBranding.Provider.of({
+        stables: ["managedLoginBrandingId", "userPoolId", "clientId"],
+
+        // Sub-resource keyed entirely by its user pool (userPoolId) with no
+        // global enumeration API of its own — nuke reaches it through the
+        // parent's deletion, so enumeration returns empty per the
+        // ProviderService doctrine.
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds, output }) {
+          const userPoolId = output?.userPoolId ?? olds?.userPoolId;
+          const clientId = output?.clientId ?? olds?.clientId;
+          if (userPoolId === undefined) return undefined;
+          const observed =
+            output?.managedLoginBrandingId !== undefined
+              ? yield* describeById(userPoolId, output.managedLoginBrandingId)
+              : clientId !== undefined
+                ? yield* describeByClient(userPoolId, clientId)
+                : undefined;
+          if (observed?.ManagedLoginBrandingId === undefined) return undefined;
+          return {
+            managedLoginBrandingId: observed.ManagedLoginBrandingId,
+            userPoolId,
+            clientId: clientId!,
+          };
+        }),
+
+        diff: Effect.fn(function* ({ news, olds }) {
+          if (!isResolved(news)) return undefined;
+          if (
+            olds?.userPoolId !== news?.userPoolId ||
+            olds?.clientId !== news?.clientId
+          ) {
+            return { action: "replace" } as const;
+          }
+        }),
+
+        reconcile: Effect.fn(function* ({ news, output, session }) {
+          const { userPoolId, clientId } = news;
+          const useProvided = desiredUseProvidedValues(news);
+
+          // 1. OBSERVE — output.managedLoginBrandingId is only a cache;
+          //    fall back to the by-client lookup so state loss converges.
+          let observed =
+            output?.managedLoginBrandingId !== undefined
+              ? yield* describeById(userPoolId, output.managedLoginBrandingId)
+              : undefined;
+          if (observed === undefined) {
+            observed = yield* describeByClient(userPoolId, clientId);
+          }
+
+          // 2. ENSURE — create when missing; a branding created out-of-band
+          //    (or by a concurrent run) for the same client surfaces as
+          //    ManagedLoginBrandingExistsException and is taken over.
+          if (observed === undefined) {
+            observed = yield* cip
+              .createManagedLoginBranding({
+                UserPoolId: userPoolId,
+                ClientId: clientId,
+                UseCognitoProvidedValues: useProvided,
+                Settings: news.settings,
+                Assets: toWireAssets(news.assets),
+              })
+              .pipe(
+                Effect.map((r) => r.ManagedLoginBranding),
+                Effect.catchTag("ManagedLoginBrandingExistsException", () =>
+                  describeByClient(userPoolId, clientId),
+                ),
+              );
+          }
+
+          const managedLoginBrandingId = observed?.ManagedLoginBrandingId!;
+
+          // 3. SYNC — diff observed style against desired; skip the update
+          //    entirely on no-op.
+          const drift =
+            (observed?.UseCognitoProvidedValues ?? false) !== useProvided ||
+            (news.settings !== undefined &&
+              JSON.stringify(news.settings) !==
+                JSON.stringify(observed?.Settings)) ||
+            (news.assets !== undefined &&
+              canonicalAssets(toWireAssets(news.assets)) !==
+                canonicalAssets(observed?.Assets));
+          if (drift) {
+            yield* cip
+              .updateManagedLoginBranding({
+                UserPoolId: userPoolId,
+                ManagedLoginBrandingId: managedLoginBrandingId,
+                UseCognitoProvidedValues: useProvided,
+                Settings: news.settings,
+                Assets: toWireAssets(news.assets),
+              })
+              .pipe(retryWhileConcurrent);
+          }
+
+          yield* session.note(managedLoginBrandingId);
+          return { managedLoginBrandingId, userPoolId, clientId };
+        }),
+
+        delete: Effect.fn(function* ({ output }) {
+          yield* cip
+            .deleteManagedLoginBranding({
+              UserPoolId: output.userPoolId,
+              ManagedLoginBrandingId: output.managedLoginBrandingId,
+            })
+            .pipe(
+              Effect.catchTag("ResourceNotFoundException", () => Effect.void),
+              retryWhileConcurrent,
+            );
+        }),
+      });
+    }),
+  );

package/src/AWS/Cognito/UserPool.ts

@@ -218,6 +218,47 @@ export interface UserPoolCustomEmailSender {
   lambdaVersion?: "V1_0";
 }
 
+/**
+ * How the user pool delivers its email messages (verification codes, OTPs,
+ * invitations): either Cognito's built-in, rate-limited delivery
+ * (`COGNITO_DEFAULT`) or your own verified Amazon SES identity
+ * (`DEVELOPER`). With `DEVELOPER`, the SES identity's policy must grant
+ * `cognito-idp.amazonaws.com` permission to send
+ * (`SES.EmailIdentityPolicy`).
+ */
+export interface UserPoolEmailConfiguration {
+  /**
+   * Which sending account delivers the pool's email. `COGNITO_DEFAULT`
+   * uses Cognito's built-in delivery (limited daily volume);
+   * `DEVELOPER` sends through your own SES identity (`sourceArn`
+   * required) at your SES quota.
+   * @default "COGNITO_DEFAULT"
+   */
+  emailSendingAccount?: "COGNITO_DEFAULT" | "DEVELOPER";
+  /**
+   * ARN of a verified SES email identity (address or domain) in a
+   * supported region. Required when `emailSendingAccount` is `DEVELOPER`;
+   * with `COGNITO_DEFAULT` it customizes the FROM address while Cognito
+   * still handles delivery.
+   */
+  sourceArn?: string;
+  /**
+   * The FROM address, either bare (`no-reply@example.com`) or with a
+   * friendly display name (`"My App <no-reply@example.com>"`). Must be
+   * covered by the `sourceArn` identity.
+   */
+  from?: string;
+  /**
+   * The destination for replies to the pool's messages.
+   */
+  replyToEmailAddress?: string;
+  /**
+   * Name of an SES configuration set applied to email sent by the pool
+   * (event publishing, IP pool selection). `DEVELOPER` only.
+   */
+  configurationSet?: string;
+}
+
 /**
  * An account recovery mechanism with its priority (1 is highest).
  */
@@ -322,6 +363,14 @@ export interface UserPoolProps {
    * never affected by adding or removing it.
    */
   customEmailSender?: UserPoolCustomEmailSender;
+  /**
+   * How the pool delivers its email messages: Cognito's built-in delivery
+   * (`COGNITO_DEFAULT`, the service default) or a verified SES identity
+   * (`DEVELOPER`) — no custom sender Lambda required. When omitted, an
+   * observed email configuration is preserved rather than reset to the
+   * service default.
+   */
+  emailConfiguration?: UserPoolEmailConfiguration;
   /**
    * ARN of the symmetric KMS key Cognito uses to encrypt the codes it
    * passes to the custom sender function(s) (`LambdaConfig.KMSKeyID`).
@@ -394,6 +443,38 @@ export interface UserPool extends Resource<
  * });
  * ```
  *
+ * ### Sending Email Through SES
+ * **Example:** OTP and Verification Email from a Verified SES Identity
+ * ```typescript
+ * const identity = yield* SES.EmailIdentity("Sender", {
+ *   emailIdentity: "mail.example.com",
+ * });
+ * // allow Cognito to send through the identity
+ * yield* SES.EmailIdentityPolicy("CognitoSend", {
+ *   emailIdentity: identity.emailIdentity,
+ *   policyName: "cognito",
+ *   policy: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Allow",
+ *       Principal: { Service: "cognito-idp.amazonaws.com" },
+ *       Action: ["ses:SendEmail", "ses:SendRawEmail"],
+ *       Resource: identity.identityArn,
+ *     }],
+ *   },
+ * });
+ * const pool = yield* Cognito.UserPool("Users", {
+ *   usernameAttributes: ["email"],
+ *   autoVerifiedAttributes: ["email"],
+ *   emailConfiguration: {
+ *     emailSendingAccount: "DEVELOPER",
+ *     sourceArn: identity.identityArn,
+ *     from: "My App <no-reply@mail.example.com>",
+ *     replyToEmailAddress: "support@example.com",
+ *   },
+ * });
+ * ```
+ *
  * ### Email OTP with a Custom Email Sender
  * **Example:** Passwordless Email OTP Delivered by Your Own Lambda
  * ```typescript
@@ -485,6 +566,32 @@ const toWireSignInPolicy = (policy: UserPoolSignInPolicy | undefined) =>
     ? undefined
     : { AllowedFirstAuthFactors: policy.allowedFirstAuthFactors };
 
+const toWireEmailConfiguration = (
+  config: UserPoolEmailConfiguration | undefined,
+): cip.EmailConfigurationType | undefined =>
+  config === undefined
+    ? undefined
+    : {
+        EmailSendingAccount: config.emailSendingAccount ?? "COGNITO_DEFAULT",
+        SourceArn: config.sourceArn,
+        From: config.from,
+        ReplyToEmailAddress: config.replyToEmailAddress,
+        ConfigurationSet: config.configurationSet,
+      };
+
+/** Observed/desired email configuration with the service default filled in,
+ * for order- and absence-insensitive comparison (`JSON.stringify` drops the
+ * `undefined` members on both sides). */
+const normalizedEmailConfiguration = (
+  config: cip.EmailConfigurationType | undefined,
+) => ({
+  emailSendingAccount: config?.EmailSendingAccount ?? "COGNITO_DEFAULT",
+  sourceArn: config?.SourceArn,
+  from: config?.From,
+  replyToEmailAddress: config?.ReplyToEmailAddress,
+  configurationSet: config?.ConfigurationSet,
+});
+
 const toWireCustomEmailSender = (
   sender: UserPoolCustomEmailSender | undefined,
 ): cip.CustomEmailLambdaVersionConfigType | undefined =>
@@ -513,17 +620,25 @@ const validateProps = (props: UserPoolProps) =>
             "customEmailSender requires kmsKeyId — Cognito encrypts the codes it passes to the custom sender with that KMS key",
         }),
       )
-    : props.tier === "LITE" &&
-        (props.signInPolicy?.allowedFirstAuthFactors ?? []).some((factor) =>
-          PASSWORDLESS_AUTH_FACTORS.includes(factor),
-        )
+    : props.emailConfiguration?.emailSendingAccount === "DEVELOPER" &&
+        props.emailConfiguration.sourceArn === undefined
       ? Effect.fail(
           new InvalidUserPoolConfiguration({
             reason:
-              "passwordless first-auth factors (EMAIL_OTP / SMS_OTP / WEB_AUTHN) require the ESSENTIALS or PLUS tier, not LITE",
+              "emailConfiguration with emailSendingAccount DEVELOPER requires sourceArn — the ARN of the verified SES identity Cognito sends from",
           }),
         )
-      : Effect.void;
+      : props.tier === "LITE" &&
+          (props.signInPolicy?.allowedFirstAuthFactors ?? []).some((factor) =>
+            PASSWORDLESS_AUTH_FACTORS.includes(factor),
+          )
+        ? Effect.fail(
+            new InvalidUserPoolConfiguration({
+              reason:
+                "passwordless first-auth factors (EMAIL_OTP / SMS_OTP / WEB_AUTHN) require the ESSENTIALS or PLUS tier, not LITE",
+            }),
+          )
+        : Effect.void;
 
 const tagRecordOf = (
   tags: { [key: string]: string | undefined } | undefined,
@@ -709,6 +824,13 @@ export const UserPoolProvider = () =>
             : toWireSignInPolicy(news.signInPolicy);
         return {
           LambdaConfig: lambdaConfig,
+          // updateUserPool resets an omitted EmailConfiguration to the
+          // service default — echo the OBSERVED configuration back when the
+          // prop is undefined so unrelated updates never clear it.
+          EmailConfiguration:
+            news.emailConfiguration === undefined
+              ? observed.EmailConfiguration
+              : toWireEmailConfiguration(news.emailConfiguration),
           Policies:
             PasswordPolicy === undefined && SignInPolicy === undefined
               ? undefined
@@ -844,6 +966,19 @@ export const UserPoolProvider = () =>
         ) {
           return true;
         }
+        if (
+          news.emailConfiguration !== undefined &&
+          JSON.stringify(
+            normalizedEmailConfiguration(
+              toWireEmailConfiguration(news.emailConfiguration),
+            ),
+          ) !==
+            JSON.stringify(
+              normalizedEmailConfiguration(observed.EmailConfiguration),
+            )
+        ) {
+          return true;
+        }
         if (
           news.adminCreateUserOnly !== undefined &&
           news.adminCreateUserOnly !==
@@ -988,6 +1123,9 @@ export const UserPoolProvider = () =>
                 DeletionProtection: news.deletionProtection
                   ? "ACTIVE"
                   : "INACTIVE",
+                EmailConfiguration: toWireEmailConfiguration(
+                  news.emailConfiguration,
+                ),
                 UsernameAttributes: news.usernameAttributes,
                 AliasAttributes: news.aliasAttributes,
                 AutoVerifiedAttributes: news.autoVerifiedAttributes,

package/src/AWS/Cognito/index.ts

@@ -6,6 +6,7 @@ export * from "./IdentityPoolAuth.ts";
 export * from "./IdentityPoolAuthHttp.ts";
 export * from "./IdentityPoolRoleAttachment.ts";
 export * from "./IdentityProvider.ts";
+export * from "./ManagedLoginBranding.ts";
 export * from "./ResourceServer.ts";
 export * from "./User.ts";
 export * from "./UserPool.ts";

package/src/AWS/EC2/Instance.ts

@@ -7,7 +7,7 @@ import * as FileSystem from "effect/FileSystem";
 import * as Schedule from "effect/Schedule";
 import * as Stream from "effect/Stream";
 import * as Bundle from "../../Bundle/Bundle.ts";
-import type { ScopedPlanStatusSession } from "../../Cli/Cli.ts";
+import type { ScopedPlanStatusSession } from "../../Report.ts";
 import { deepEqual, isResolved } from "../../Diff.ts";
 import type { Input } from "../../Input.ts";
 import { Platform, type Main, type PlatformProps } from "../../Platform.ts";
@@ -123,12 +123,10 @@ export interface InstanceProps extends PlatformProps {
    */
   env?: Record<string, any>;
   /**
-   * Bundler configuration for the hosted process entrypoint: rolldown
-   * `input`/`output` overrides plus pure-annotation options (`pure`).
-   * `effect`, `@effect/*`, `alchemy`, `@alchemy.run/*`, and
-   * `@distilled.cloud/*` are annotated as pure by default so unused code
-   * from those packages is tree-shaken; list additional packages via
-   * `pure.packages`, or disable with `pure: false`.
+   * Bundler configuration for the hosted process entrypoint. Unused
+   * code is tree-shaken. `effect`, alchemy, and `@distilled.cloud` are
+   * marked pure so unused parts prune more aggressively. List extra
+   * packages with `pure.packages`, or disable with `pure: false`.
    */
   build?: Bundle.BundleConfig;
   /**
@@ -309,16 +307,13 @@ export type InstanceRuntimeContext = Ec2HostRuntimeContext;
  * ```
  *
  * ### Bundling & Tree-shaking
- * `main` is bundled with rolldown at deploy time. Top-level calls in the
- * `effect`, `@effect/*`, `alchemy`, `@alchemy.run/*`, and
- * `@distilled.cloud/*` packages receive `#__PURE__` annotations by
- * default, so anything the hosted program doesn't use from those packages is
- * tree-shaken out of the bundle. Any other package — including your own
- * app — is left untouched unless you list it explicitly.
+ * `main` is bundled with rolldown at deploy time. Unused code is
+ * tree-shaken. `effect`, alchemy, and `@distilled.cloud` are marked
+ * pure so unused parts prune more aggressively. Your app is not
+ * marked pure.
  *
- * **Example:** Treat additional packages as pure
- * Pass package names (or picomatch globs) via `build.pure.packages` to
- * annotate them in addition to the defaults.
+ * **Example:** Mark additional packages as pure
+ * Only list packages with no top-level side effects.
  * ```typescript
  * {
  *   main: import.meta.url,
@@ -328,18 +323,7 @@ export type InstanceRuntimeContext = Ec2HostRuntimeContext;
  * }
  * ```
  *
- * Listing a package annotates calls whose result is bound (variable
- * initializers, exports) — safe anywhere. If a listed package also
- * declares `"sideEffects": false` (or `[]`) in its `package.json`, that
- * combination opts it into full annotation: top-level calls whose result
- * is discarded (e.g. `router.on("/path", handler)` registrations) are
- * also marked pure and deleted under minification when unused. Only list
- * a `sideEffects: false` package if its modules really are free of
- * meaningful top-level side effects. The `effect`, `alchemy`, and
- * `@distilled.cloud` defaults declare exactly that, on purpose — their
- * modules are designed to be fully tree-shakeable.
- *
- * **Example:** Disable pure annotations
+ * **Example:** Turn it off
  * ```typescript
  * {
  *   main: import.meta.url,