alchemy 2.0.0-beta.65 → 2.0.0-beta.67

package/src/AWS/ECS/Service.ts

@@ -11,6 +11,7 @@ import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Schedule from "effect/Schedule";
 import * as Stream from "effect/Stream";
+import type { HttpClient } from "effect/unstable/http/HttpClient";
 import { deepEqual, isResolved } from "../../Diff.ts";
 import * as Namespace from "../../Namespace.ts";
 import * as Output from "../../Output.ts";
@@ -21,7 +22,7 @@ import { Resource } from "../../Resource.ts";
 import type { HostRuntimeContext, ServerHost } from "../../Server/Process.ts";
 import { Stack } from "../../Stack.ts";
 import { createInternalTags, diffTags } from "../../Tags.ts";
-import { toSeconds, toWireSeconds } from "../../Util/Duration.ts";
+import { toMillis, toSeconds, toWireSeconds } from "../../Util/Duration.ts";
 import { Certificate } from "../ACM/Certificate.ts";
 import { ScalableTarget } from "../ApplicationAutoScaling/ScalableTarget.ts";
 import { ScalingPolicy } from "../ApplicationAutoScaling/ScalingPolicy.ts";
@@ -61,6 +62,7 @@ import {
   ensureTaskLogGroup,
   reapSupersededTaskDefinitionRevision,
   registerTaskDefinitionRevision,
+  syncEnvironmentFilesPolicy,
   syncTaskDefinitionTags,
   taskImagePlatform,
   type TaskBindingContract,
@@ -363,6 +365,22 @@ export class RequestCountScalingRequiresLoadBalancer extends Data.TaggedError(
   readonly message: string;
 }> {}
 
+/** An ECS service did not converge to the requested deployment before timeout. */
+export class ServiceDidNotStabilize extends Data.TaggedError(
+  "ServiceDidNotStabilize",
+)<{
+  readonly clusterArn: string;
+  readonly serviceName: string;
+  readonly expectedTaskDefinitionArn: string | undefined;
+  readonly status: string | undefined;
+  readonly desiredCount: number | undefined;
+  readonly runningCount: number | undefined;
+  readonly pendingCount: number | undefined;
+  readonly deploymentCount: number;
+  readonly unhealthyTargetCount: number;
+  readonly message: string;
+}> {}
+
 /**
  * Derive a deterministic listener-rule priority (1–50000) from the rule's
  * namespaced logical id (FNV-1a 32-bit). Stable across deploys for the same
@@ -680,6 +698,14 @@ export interface ServicePropsBase extends PlatformProps {
    */
   deploymentConfiguration?: ecs.DeploymentConfiguration;
 
+  /**
+   * Maximum time to wait for an ECS deployment, old-task drain, and target
+   * health to converge before failing the resource operation. The provider
+   * hard-caps this at 30 minutes so polling always remains bounded.
+   * @default "10 minutes"
+   */
+  deploymentStabilizationTimeout?: Duration.Input;
+
   /**
    * Deployment controller (`ECS`, `CODE_DEPLOY`, `EXTERNAL`). The controller
    * type is immutable — changing it replaces the service.
@@ -2526,6 +2552,219 @@ const resolveServiceVolumes = (
   return { volumes: resolved, mountPoints };
 };
 
+type ServiceConvergenceDependencies = Credentials | HttpClient | Region;
+
+interface ServiceConvergenceSnapshot {
+  readonly service: ecs.Service | undefined;
+  readonly targetGroups: readonly {
+    readonly missing: boolean;
+    readonly states: readonly (string | undefined)[];
+  }[];
+  readonly converged: boolean;
+}
+
+type ServiceConvergenceMode = "stable" | "drained" | "deleted";
+
+/**
+ * Observe the complete service deployment boundary: ECS rollout state,
+ * desired/running/pending counts, superseded deployments, and every target
+ * group's registered target state.
+ */
+const observeServiceConvergence = (input: {
+  clusterArn: string;
+  serviceName: string;
+  expectedTaskDefinitionArn?: string;
+  mode: ServiceConvergenceMode;
+}): Effect.Effect<
+  ServiceConvergenceSnapshot,
+  ecs.DescribeServicesError | elbv2.DescribeTargetHealthError,
+  ServiceConvergenceDependencies
+> =>
+  Effect.gen(function* () {
+    const described = yield* ecs
+      .describeServices({
+        cluster: input.clusterArn,
+        services: [input.serviceName],
+      })
+      .pipe(
+        Effect.catchTag("ClusterNotFoundException", () =>
+          Effect.succeed(undefined),
+        ),
+      );
+    const service = described?.services?.find(
+      (candidate) =>
+        candidate.serviceName === input.serviceName &&
+        candidate.status !== "INACTIVE",
+    );
+
+    if (service === undefined) {
+      return {
+        service,
+        targetGroups: [],
+        converged: input.mode === "drained" || input.mode === "deleted",
+      };
+    }
+
+    const targetGroupArns = [
+      ...new Set(
+        (service.loadBalancers ?? []).flatMap((loadBalancer) =>
+          loadBalancer.targetGroupArn ? [loadBalancer.targetGroupArn] : [],
+        ),
+      ),
+    ];
+    const targetGroups = yield* Effect.forEach(
+      targetGroupArns,
+      (targetGroupArn) =>
+        elbv2.describeTargetHealth({ TargetGroupArn: targetGroupArn }).pipe(
+          Effect.map((health) => ({
+            missing: false,
+            states: (health.TargetHealthDescriptions ?? []).map(
+              (target) => target.TargetHealth?.State,
+            ),
+          })),
+          Effect.catchTag("TargetGroupNotFoundException", () =>
+            Effect.succeed({
+              missing: true,
+              states: [] as (string | undefined)[],
+            }),
+          ),
+        ),
+      { concurrency: 4 },
+    );
+
+    if (input.mode === "deleted") {
+      return { service, targetGroups, converged: false };
+    }
+
+    const runningCount = service.runningCount ?? 0;
+    const pendingCount = service.pendingCount ?? 0;
+    const desiredCount = service.desiredCount ?? 0;
+    const expectedTargetCount =
+      service.schedulingStrategy === "DAEMON" ? runningCount : desiredCount;
+
+    if (input.mode === "drained") {
+      return {
+        service,
+        targetGroups,
+        converged:
+          runningCount === 0 &&
+          pendingCount === 0 &&
+          targetGroups.every(
+            (targetGroup) =>
+              targetGroup.missing || targetGroup.states.length === 0,
+          ),
+      };
+    }
+
+    const deployments = service.deployments ?? [];
+    const primary = deployments.find(
+      (deployment) => deployment.status === "PRIMARY",
+    );
+    const deploymentController = service.deploymentController?.type ?? "ECS";
+    const countsConverged =
+      service.schedulingStrategy === "DAEMON"
+        ? pendingCount === 0
+        : runningCount === desiredCount && pendingCount === 0;
+    const deploymentConverged =
+      deployments.length === 1 &&
+      primary !== undefined &&
+      primary.taskDefinition === input.expectedTaskDefinitionArn &&
+      (deploymentController === "ECS"
+        ? primary.rolloutState === "COMPLETED"
+        : primary.rolloutState === undefined ||
+          primary.rolloutState === "COMPLETED");
+    const targetsConverged = targetGroups.every(
+      (targetGroup) =>
+        !targetGroup.missing &&
+        targetGroup.states.length === expectedTargetCount &&
+        targetGroup.states.every((state) => state === "healthy"),
+    );
+
+    return {
+      service,
+      targetGroups,
+      converged:
+        service.status === "ACTIVE" &&
+        service.taskDefinition === input.expectedTaskDefinitionArn &&
+        countsConverged &&
+        deploymentConverged &&
+        targetsConverged,
+    };
+  });
+
+const waitForServiceConvergence = (input: {
+  clusterArn: string;
+  serviceName: string;
+  expectedTaskDefinitionArn?: string;
+  mode: ServiceConvergenceMode;
+  timeout?: Duration.Input;
+}): Effect.Effect<
+  ServiceConvergenceSnapshot,
+  | ecs.DescribeServicesError
+  | elbv2.DescribeTargetHealthError
+  | ServiceDidNotStabilize,
+  ServiceConvergenceDependencies
+> => {
+  const pollIntervalMillis = 5_000;
+  const timeoutMillis = Math.min(
+    toMillis(input.timeout ?? "10 minutes")!,
+    30 * 60 * 1_000,
+  );
+  const attempts = Math.max(1, Math.ceil(timeoutMillis / pollIntervalMillis));
+
+  return observeServiceConvergence(input).pipe(
+    Effect.repeat({
+      schedule: Schedule.max([
+        Schedule.spaced(pollIntervalMillis),
+        Schedule.recurs(attempts),
+      ]),
+      until: (snapshot) =>
+        snapshot.converged ||
+        snapshot.service?.deployments?.some(
+          (deployment) => deployment.rolloutState === "FAILED",
+        ) === true,
+    }),
+    Effect.flatMap((snapshot) => {
+      if (snapshot.converged) {
+        return Effect.succeed(snapshot);
+      }
+      const service = snapshot.service;
+      const expectedTargetCount =
+        service?.schedulingStrategy === "DAEMON"
+          ? (service.runningCount ?? 0)
+          : (service?.desiredCount ?? 0);
+      const unhealthyTargetCount = snapshot.targetGroups.reduce(
+        (total, targetGroup) =>
+          total +
+          (targetGroup.missing
+            ? Math.max(1, expectedTargetCount)
+            : targetGroup.states.filter((state) => state !== "healthy").length +
+              Math.abs(targetGroup.states.length - expectedTargetCount)),
+        0,
+      );
+      return Effect.fail(
+        new ServiceDidNotStabilize({
+          clusterArn: input.clusterArn,
+          serviceName: input.serviceName,
+          expectedTaskDefinitionArn: input.expectedTaskDefinitionArn,
+          status: service?.status,
+          desiredCount: service?.desiredCount,
+          runningCount: service?.runningCount,
+          pendingCount: service?.pendingCount,
+          deploymentCount: service?.deployments?.length ?? 0,
+          unhealthyTargetCount,
+          message:
+            service?.deployments?.some(
+              (deployment) => deployment.rolloutState === "FAILED",
+            ) === true
+              ? `ECS service ${input.serviceName} reported a failed deployment`
+              : `ECS service ${input.serviceName} did not become ${input.mode} before timeout`,
+        }),
+      );
+    }),
+  );
+};
+
 export const ServiceProvider = () =>
   Provider.effect(
     Service,
@@ -2792,6 +3031,24 @@ export const ServiceProvider = () =>
         const taskRoleArn =
           output?.taskRoleArn ??
           (yield* createTaskRoleIfNotExists({ id, roleName: taskRoleName }));
+
+        // `taskRoleManagedPolicyArns` is part of the inherited
+        // `TaskDefinitionConfig` surface — attach it like the standalone
+        // Task provider does (its sibling `executionRoleManagedPolicyArns`
+        // is already honored below). `attachRolePolicy` is idempotent for
+        // already-attached ARNs; a `LimitExceededException` means the
+        // policy was NOT attached, so it propagates and fails the deploy
+        // rather than silently shipping a role with missing permissions.
+        yield* Effect.all(
+          (news.taskRoleManagedPolicyArns ?? []).map((policyArn) =>
+            iam.attachRolePolicy({
+              RoleName: taskRoleName,
+              PolicyArn: policyArn,
+            }),
+          ),
+          { concurrency: "unbounded" },
+        );
+
         const executionRoleArn =
           output?.executionRoleArn ??
           (yield* ensureTaskExecutionRole({
@@ -2818,6 +3075,13 @@ export const ServiceProvider = () =>
           secretArns: secretEntries.map(([, arn]) => arn),
         });
 
+        // Environment files: the execution role reads the referenced S3
+        // objects at task start.
+        yield* syncEnvironmentFilesPolicy({
+          roleName: executionRoleName,
+          environmentFiles: news.environmentFiles,
+        });
+
         const logGroupArn =
           output?.logGroupArn ??
           (yield* ensureTaskLogGroup({ id, logGroupName }));
@@ -3292,6 +3556,17 @@ export const ServiceProvider = () =>
                 new Error("createService returned no service"),
               );
             }
+            yield* session.note(
+              `Waiting for ECS service ${serviceName} to stabilize`,
+            );
+            const stable = yield* waitForServiceConvergence({
+              clusterArn,
+              serviceName,
+              expectedTaskDefinitionArn: task.taskDefinitionArn,
+              mode: "stable",
+              timeout: news.deploymentStabilizationTimeout,
+            });
+            const stableService = stable.service!;
             // Legacy inline ingress recorded in prior attrs (service itself
             // was missing — e.g. recreated) is stale now: reap it.
             yield* reapLegacyIngress({ output, session });
@@ -3306,11 +3581,11 @@ export const ServiceProvider = () =>
             }
             yield* session.note(service.serviceArn);
             return {
-              serviceArn: service.serviceArn as ServiceArn,
-              serviceName: service.serviceName!,
-              clusterArn: service.clusterArn as ClusterArn,
-              taskDefinitionArn: service.taskDefinition!,
-              status: service.status ?? "ACTIVE",
+              serviceArn: stableService.serviceArn as ServiceArn,
+              serviceName: stableService.serviceName!,
+              clusterArn: stableService.clusterArn as ClusterArn,
+              taskDefinitionArn: stableService.taskDefinition!,
+              status: stableService.status ?? "ACTIVE",
               ...ingressAttrs,
               ...ownedAttributes,
             };
@@ -3319,7 +3594,7 @@ export const ServiceProvider = () =>
           // Sync — apply in-place mutable fields via updateService. Force a new
           // deployment so a changed task definition (same revision-less ARN) or
           // load-balancer wiring rolls out.
-          const updated = yield* ecs
+          yield* ecs
             .updateService({
               ...mutableInput(news, task, network, securityGroups),
               // While autoscaling manages the desired count, leave it
@@ -3359,7 +3634,17 @@ export const ServiceProvider = () =>
                 ]),
               }),
             );
-          const service = updated.service;
+          yield* session.note(
+            `Waiting for ECS service ${serviceName} to stabilize`,
+          );
+          const stable = yield* waitForServiceConvergence({
+            clusterArn,
+            serviceName,
+            expectedTaskDefinitionArn: task.taskDefinitionArn,
+            mode: "stable",
+            timeout: news.deploymentStabilizationTimeout,
+          });
+          const stableService = stable.service!;
 
           // Sync tags — diff observed service tags against desired.
           const observedTags = Object.fromEntries(
@@ -3405,24 +3690,18 @@ export const ServiceProvider = () =>
 
           yield* session.note(observed.serviceArn);
           return {
-            serviceArn: observed.serviceArn as ServiceArn,
-            serviceName: observed.serviceName!,
-            clusterArn: observed.clusterArn as ClusterArn,
-            taskDefinitionArn:
-              service?.taskDefinition ??
-              observed.taskDefinition ??
-              output?.taskDefinitionArn ??
-              "",
-            status: service?.status ?? observed.status ?? "ACTIVE",
+            serviceArn: stableService.serviceArn as ServiceArn,
+            serviceName: stableService.serviceName!,
+            clusterArn: stableService.clusterArn as ClusterArn,
+            taskDefinitionArn: stableService.taskDefinition!,
+            status: stableService.status ?? "ACTIVE",
             ...ingressAttrs,
             ...ownedAttributes,
           };
         }),
         delete: Effect.fn(function* ({ output, session }) {
-          // Scale to zero first so `deleteService` has no running tasks to
-          // drain. If the service is mid-transition (`ServiceNotActiveException`)
-          // we skip the scale-down — `deleteService({ force: true })` below
-          // tears it down regardless.
+          // Scale to zero and prove every task/target has drained before
+          // deleting the service or its dependent task-definition resources.
           yield* ecs
             .updateService({
               cluster: output.clusterArn,
@@ -3430,11 +3709,26 @@ export const ServiceProvider = () =>
               desiredCount: 0,
             })
             .pipe(
+              Effect.retry({
+                while: (error) => error._tag === "ServiceNotActiveException",
+                schedule: Schedule.max([
+                  Schedule.spaced("5 seconds"),
+                  Schedule.recurs(8),
+                ]),
+              }),
               Effect.catchTag("ServiceNotFoundException", () => Effect.void),
               Effect.catchTag("ClusterNotFoundException", () => Effect.void),
-              Effect.catchTag("ServiceNotActiveException", () => Effect.void),
             );
 
+          yield* session.note(
+            `Waiting for ECS service ${output.serviceName} to drain`,
+          );
+          yield* waitForServiceConvergence({
+            clusterArn: output.clusterArn,
+            serviceName: output.serviceName,
+            mode: "drained",
+          });
+
           yield* ecs
             .deleteService({
               cluster: output.clusterArn,
@@ -3446,6 +3740,12 @@ export const ServiceProvider = () =>
               Effect.catchTag("ClusterNotFoundException", () => Effect.void),
             );
 
+          yield* waitForServiceConvergence({
+            clusterArn: output.clusterArn,
+            serviceName: output.serviceName,
+            mode: "deleted",
+          });
+
           // Inline ingress teardown applies ONLY to legacy state rows (no
           // `ingressKind` marker) whose ALB/TG/listener/SG were created
           // inline by the pre-composition provider. Composed ingress is made

package/src/AWS/ECS/Task.ts

@@ -19,7 +19,7 @@ import * as Provider from "../../Provider.ts";
 import { Resource, type ResourceBinding } from "../../Resource.ts";
 import type { RuntimeContext } from "../../RuntimeContext.ts";
 import {
-  createHostRuntimeContext,
+  createContainerRuntimeContext,
   type HostRuntimeContext,
   type ServerHost,
 } from "../../Server/Process.ts";
@@ -104,6 +104,17 @@ export interface TaskDefinitionConfig {
    * Additional environment variables for the container.
    */
   env?: Record<string, any>;
+  /**
+   * Environment files to load into the primary container, e.g. `.env`
+   * objects stored in S3:
+   * `[{ value: "arn:aws:s3:::my-bucket/app.env", type: "s3" }]`.
+   *
+   * Variables from `env` (and the container's own `environment`) take
+   * precedence over values loaded from environment files. The execution
+   * role is automatically granted `s3:GetObject` on the referenced objects
+   * and `s3:GetBucketLocation` on their buckets.
+   */
+  environmentFiles?: ecs.EnvironmentFile[];
   /**
    * Command override for the primary container (Docker `CMD`).
    */
@@ -298,37 +309,8 @@ export interface TaskRuntimeContext extends HostRuntimeContext {
   readonly Type: "AWS.ECS.Task";
 }
 
-/**
- * Host runtime context for ECS container platforms: extends the shared
- * process host context so an impl shape's `run` effect is registered as a
- * one-shot runner (the container exits when it completes) and the HTTP
- * server only boots when the impl actually declares a `fetch` handler.
- */
-export const createContainerRuntimeContext =
-  (type: string) =>
-  (id: string): HostRuntimeContext => {
-    const base = createHostRuntimeContext(type)(id);
-    // Capture the host serve BEFORE Object.assign overwrites `base.serve`
-    // with the wrapper below — calling `base.serve` inside the wrapper would
-    // resolve to the wrapper itself (property lookup happens at call time)
-    // and recurse without bound the moment an impl declares `fetch`.
-    const serveBase = base.serve;
-    const serve: HostRuntimeContext["serve"] = (handler, options) =>
-      Effect.gen(function* () {
-        const shape = options?.shape;
-        const run = shape?.run;
-        if (Effect.isEffect(run)) {
-          yield* base.run(run as Effect.Effect<void, never, any>);
-        }
-        // Boot the HTTP server only for an impl that declared `fetch` — a
-        // pure one-shot `{ run }` program must exit when `run` completes
-        // rather than parking behind the 404 fallback server forever.
-        if (shape === undefined || shape.fetch !== undefined) {
-          yield* serveBase(handler, options);
-        }
-      }) as Effect.Effect<void, never, never>;
-    return Object.assign(base, { serve });
-  };
+// Shared with `Docker.Service`; lives beside the host runtime context.
+export { createContainerRuntimeContext } from "../../Server/Process.ts";
 
 /**
  * A Fargate task definition with a container image from one of three
@@ -426,6 +408,16 @@ export const createContainerRuntimeContext =
  *   },
  * });
  * ```
+ *
+ * @example Environment Files from S3
+ * ```typescript
+ * const task = yield* Task("ApiTask", {
+ *   main: import.meta.url,
+ *   environmentFiles: [
+ *     { value: "arn:aws:s3:::my-config-bucket/app.env", type: "s3" },
+ *   ],
+ * });
+ * ```
  */
 export const Task: Platform<Task, TaskServices, TaskShape, TaskRuntimeContext> =
   Platform("AWS.ECS.Task", {
@@ -518,6 +510,56 @@ export const ensureTaskExecutionRole = Effect.fn(function* ({
   return roleArn;
 });
 
+/** Inline policy granting the execution role read access to `environmentFiles`. */
+const ENVIRONMENT_FILES_POLICY_NAME = "alchemy-environment-files";
+
+/**
+ * Sync the execution role's read access to the S3 `environmentFiles`: put
+ * an inline policy granting `s3:GetObject` on the referenced objects (and
+ * `s3:GetBucketLocation` on their buckets), or delete the policy when no
+ * environment files are configured.
+ */
+export const syncEnvironmentFilesPolicy = Effect.fn(function* ({
+  roleName,
+  environmentFiles,
+}: {
+  roleName: string;
+  environmentFiles: ecs.EnvironmentFile[] | undefined;
+}) {
+  const objectArns = (environmentFiles ?? [])
+    .filter((file) => file.type === "s3")
+    .map((file) => file.value);
+  if (objectArns.length === 0) {
+    yield* iam
+      .deleteRolePolicy({
+        RoleName: roleName,
+        PolicyName: ENVIRONMENT_FILES_POLICY_NAME,
+      })
+      .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
+    return;
+  }
+  const bucketArns = [...new Set(objectArns.map((arn) => arn.split("/")[0]))];
+  yield* iam.putRolePolicy({
+    RoleName: roleName,
+    PolicyName: ENVIRONMENT_FILES_POLICY_NAME,
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: [
+        {
+          Effect: "Allow",
+          Action: ["s3:GetObject"],
+          Resource: objectArns,
+        },
+        {
+          Effect: "Allow",
+          Action: ["s3:GetBucketLocation"],
+          Resource: bucketArns,
+        },
+      ],
+    }),
+  });
+});
+
 /** Ensure the CloudWatch log group the task writes to exists. */
 export const ensureTaskLogGroup = Effect.fn(function* ({
   id,
@@ -655,6 +697,7 @@ export const registerTaskDefinitionRevision = Effect.fn(function* ({
       name,
       value: typeof value === "string" ? value : JSON.stringify(value),
     })),
+    environmentFiles: props.environmentFiles,
     logConfiguration: {
       logDriver: "awslogs",
       options: {
@@ -1137,6 +1180,13 @@ export const TaskProvider = () =>
               );
           }
 
+          // Environment files: the execution role reads the referenced S3
+          // objects at task start.
+          yield* syncEnvironmentFilesPolicy({
+            roleName: executionRoleName,
+            environmentFiles: news.environmentFiles,
+          });
+
           const {
             env: bindingEnv,
             volumes: bindingVolumes,

package/src/AWS/EKS/Deployment.ts

@@ -382,6 +382,7 @@ import { BunServices } from "@effect/platform-bun";
 import { BunHttpServer } from "alchemy/Http";
 import { Stack } from "alchemy/Stack";
 import { makeEntrypointLayer, reifyBoundConfigProvider } from "alchemy/Runtime";
+import { provideProcessTelemetry } from "alchemy/Telemetry";
 import * as Context from "effect/Context";
 import * as Config from "effect/Config";
 import * as ConfigProvider from "effect/ConfigProvider";
@@ -414,8 +415,15 @@ const platform = Layer.mergeAll(
 // chain so EKS Pod Identity's container-credentials endpoint
 // (AWS_CONTAINER_CREDENTIALS_FULL_URI + token file) resolves inside the pod.
 const program = tag.pipe(
-  Effect.flatMap((host) => host.RuntimeContext.exports),
-  Effect.flatMap((exports) => exports.program),
+  // Process-lifetime telemetry: built once into the root scope; exporters
+  // batch on their intervals and flush when the scope closes on graceful
+  // shutdown.
+  Effect.flatMap((host) =>
+    host.RuntimeContext.exports.pipe(
+      Effect.flatMap((exports) => exports.program),
+      provideProcessTelemetry(host.RuntimeContext),
+    ),
+  ),
   Effect.provide(
     layer.pipe(Layer.provideMerge(Layer.effect(
       Stack,

package/src/AWS/EKS/Job.ts

@@ -357,6 +357,7 @@ export const makeEksJobBootstrap =
 import { BunServices } from "@effect/platform-bun";
 import { Stack } from "alchemy/Stack";
 import { makeEntrypointLayer, reifyBoundConfigProvider } from "alchemy/Runtime";
+import { provideProcessTelemetry } from "alchemy/Telemetry";
 import * as Context from "effect/Context";
 import * as Config from "effect/Config";
 import * as ConfigProvider from "effect/ConfigProvider";
@@ -386,8 +387,15 @@ const platform = Layer.mergeAll(
 // Resolve the bundled program's registered one-shot runners (the shape's
 // \`run\` effect and any host.run work) and execute them to completion.
 const program = tag.pipe(
-  Effect.flatMap((host) => host.RuntimeContext.exports),
-  Effect.flatMap((exports) => exports.program),
+  // Process-lifetime telemetry: built once into the root scope; exporters
+  // batch on their intervals and flush when the scope closes as the
+  // one-shot program completes.
+  Effect.flatMap((host) =>
+    host.RuntimeContext.exports.pipe(
+      Effect.flatMap((exports) => exports.program),
+      provideProcessTelemetry(host.RuntimeContext),
+    ),
+  ),
   Effect.provide(
     layer.pipe(Layer.provideMerge(Layer.effect(
       Stack,