sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Batch/ JobDefinition.ts

import { Docker } from "@alchemy.run/docker/Docker";
import * as batch from "@distilled.cloud/aws/batch";
import * as logs from "@distilled.cloud/aws/cloudwatch-logs";
import * as ecr from "@distilled.cloud/aws/ecr";
import * as ecs from "@distilled.cloud/aws/ecs";
import * as iam from "@distilled.cloud/aws/iam";
import type { Region } from "@distilled.cloud/aws/Region";
import { AlchemyContext } from "alchemy/AlchemyContext";
import * as Bundle from "alchemy/Bundle/Bundle";
import { findCwdForBundle, getStableContextDir, resolveMainPath } from "alchemy/Bundle/TempRoot";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import { Platform, type PlatformProps, type PlatformServices } from "alchemy/Platform";
import * as Provider from "alchemy/Provider";
import { Resource, type ResourceBinding } from "alchemy/Resource";
import {
  createHostRuntimeContext,
  type HostRuntimeContext,
  type ServerHost,
} from "alchemy/Runtime/Process";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import { Stack } from "alchemy/Stack";
import { createInternalTags, createTagsList, diffTags, hasTags } from "alchemy/Tags";
import { toWireSeconds } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import type { Scope } from "effect/Scope";
import * as Stream from "effect/Stream";
import type * as rolldown from "rolldown";
import { roleHostBundle } from "../AWSBindings.ts";
import type { Credentials } from "../Credentials.ts";
import { buildAndPushEcrImage } from "../ECR/Image.ts";
import { AWSEnvironment, type AccountID } from "../Environment.ts";
import type { PolicyStatement } from "../IAM/Policy.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";

export class JobDefinitionOperationFailed extends Data.TaggedError("JobDefinitionOperationFailed")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export class JobDefinitionConflict extends Data.TaggedError("JobDefinitionConflict")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export type JobDefinitionName = string;
/** Revision-qualified job definition ARN (`.../job-definition/{name}:{revision}`). */
export type JobDefinitionArn =
  `arn:aws:batch:${RegionID}:${AccountID}:job-definition/${JobDefinitionName}:${number}`;

/**
 * Raised when the props don't select exactly one of the two forms: the
 * low-level container form (`image` + `executionRoleArn`) or the
 * Effect-native form (`main`).
 */
export class JobDefinitionConfigError extends Data.TaggedError("JobDefinitionConfigError")<{
  readonly message: string;
}> {}

class JobDefinitionStillVisible extends Data.TaggedError("JobDefinitionStillVisible")<{
  readonly family: string;
  readonly service: "Batch" | "ECS";
  readonly arns: readonly string[];
}> {}

export interface JobDefinitionProps extends PlatformProps {
  /**
   * Name (family) of the job definition. If omitted, a unique name is
   * generated. Content changes register a new revision under the same name.
   */
  jobDefinitionName?: string;
  /**
   * Container image the job runs (low-level form, e.g.
   * `public.ecr.aws/docker/library/busybox:latest`). Mutually exclusive
   * with `main`.
   */
  image?: string;
  /**
   * Module entrypoint for an Effect-native run-to-completion job (typically
   * `import.meta.url` from an inline Effect program). Alchemy bundles the
   * program, builds a container image, pushes it to a managed ECR
   * repository, and provisions the job/execution IAM roles — mutually
   * exclusive with a caller-supplied `image`.
   */
  main?: string;
  /**
   * Named export to load from `main`.
   * @default "default"
   */
  handler?: string;
  /**
   * Command to run in the container (low-level form). Overridable
   * per-submission via `containerOverrides.command`. The Effect-native form
   * bakes its entrypoint into the image instead.
   */
  command?: string[];
  /**
   * Fargate vCPUs for the job. Must be a valid Fargate size (0.25, 0.5, 1,
   * 2, 4, 8, 16) compatible with `memory`.
   * @default 0.25
   */
  vcpus?: number;
  /**
   * Memory (MiB) for the job. Must be compatible with `vcpus` per the
   * Fargate size matrix.
   * @default 512
   */
  memory?: number;
  /**
   * Environment variables set in the job container.
   */
  environment?: Record<string, string>;
  /**
   * Additional environment variables for the Effect-native container.
   * Non-string values are JSON-encoded. (Capability bindings also inject
   * their variables here automatically.)
   */
  env?: Record<string, any>;
  /**
   * IAM role assumed by the job's application code. For the Effect-native
   * form (`main`), Alchemy provisions and manages this role automatically
   * (binding policy statements attach to it).
   */
  jobRoleArn?: string;
  /**
   * Execution role used by ECS/Fargate to pull the image and write logs.
   * Required for the low-level form; provisioned automatically for the
   * Effect-native form.
   */
  executionRoleArn?: string;
  /**
   * Compute platforms that can run this definition. Use `EC2` for unmanaged
   * ECS compute environments.
   * @default ["FARGATE"]
   */
  platformCapabilities?: ("EC2" | "FARGATE")[];
  /**
   * Whether the Fargate task ENI gets a public IP. Required for image pulls
   * from public registries when running in public subnets.
   * @default "ENABLED"
   */
  assignPublicIp?: "ENABLED" | "DISABLED";
  /**
   * Default parameter substitutions for `Ref::` placeholders in `command`.
   */
  parameters?: Record<string, string>;
  /**
   * Number of times a failed job is retried (1-10).
   * @default 1
   */
  retryAttempts?: number;
  /**
   * Job execution timeout (minimum 60 seconds), e.g. `"15 minutes"` or
   * `Duration.minutes(15)`.
   */
  timeout?: Duration.Input;
  /**
   * Propagate job definition tags to the ECS task.
   * @default false
   */
  propagateTags?: boolean;
  /**
   * 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;
  /**
   * Docker image build for the Effect-native form: optional full
   * `dockerfile`. When omitted, Alchemy generates a Dockerfile for the
   * bundled `index.mjs`.
   */
  docker?: {
    /**
     * Base image when Alchemy generates the Dockerfile.
     * @default public.ecr.aws/docker/library/bun:1
     */
    base?: string;
    /** Full Dockerfile content (replaces generated Dockerfile). */
    dockerfile?: string;
  };
  /**
   * Additional managed policy ARNs for the managed job role
   * (Effect-native form only).
   */
  jobRoleManagedPolicyArns?: string[];
  /**
   * User-defined tags to apply to the job definition.
   */
  tags?: Record<string, string>;
}

export interface JobDefinition extends Resource<
  "AWS.Batch.JobDefinition",
  JobDefinitionProps,
  {
    jobDefinitionName: JobDefinitionName;
    jobDefinitionArn: JobDefinitionArn;
    revision: number;
    status: string;
    tags: Record<string, string>;
    /** The full URI of the built container image (Effect-native form only). */
    imageUri: string | undefined;
    /** The managed ECR repository name (Effect-native form only). */
    repositoryName: string | undefined;
    /** The managed ECR repository URI (Effect-native form only). */
    repositoryUri: string | undefined;
    /** The ARN of the managed job role (Effect-native form only). */
    jobRoleArn: string | undefined;
    /** The name of the managed job role (Effect-native form only). */
    jobRoleName: string | undefined;
    /** The ARN of the execution role the job definition uses. */
    executionRoleArn: string | undefined;
    /** The name of the managed execution role (Effect-native form only). */
    executionRoleName: string | undefined;
    /** Content hash of the bundled program (Effect-native form only). */
    codeHash: string | undefined;
  },
  {
    /** Environment variables injected into the job container. */
    env?: Record<string, any>;
    /** IAM policy statements attached to the managed job role. */
    policyStatements?: PolicyStatement[];
  },
  Providers
> {}

export type JobDefinitionServices = Credentials | Region | ServerHost | AWSEnvironment;

/**
 * The shape an Effect-native job implementation returns: a single `run`
 * Effect that is the run-to-completion body of the job. The container exits
 * 0 when it succeeds (job `SUCCEEDED`) and 1 when it fails (job `FAILED`,
 * subject to the definition's `retryAttempts`).
 */
export type JobDefinitionShape = void | {
  run: Effect.Effect<
    void,
    unknown,
    JobDefinitionServices | PlatformServices | RuntimeContext | Scope
  >;
};

export interface JobDefinitionRuntimeContext extends HostRuntimeContext {
  readonly Type: "AWS.Batch.JobDefinition";
}

const createJobDefinitionRuntimeContext = (id: string): JobDefinitionRuntimeContext => {
  const base = createHostRuntimeContext("AWS.Batch.JobDefinition")(id);
  return {
    ...base,
    // A Batch job is run-to-completion, not a server. `Platform` hands any
    // non-`fetch` impl shape to `serve`; register the shape's `run` Effect
    // as a host runner (collected into `exports.program`, executed by the
    // generated container entrypoint) instead of booting an HTTP server.
    serve: ((_handler, options) => {
      const run = (options?.shape as { run?: unknown } | undefined)?.run;
      // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- untyped impl shape; runner is a host-provided Effect
      return Effect.isEffect(run) ? base.run(run as Effect.Effect<void, never, any>) : Effect.void;
    }) as HostRuntimeContext["serve"],
  } as JobDefinitionRuntimeContext;
};

/**
 * An AWS Batch job definition for Fargate container jobs. Job definitions are
 * immutable revisions — changing the container configuration registers a new
 * revision under the same name (like ECS task definitions); destroying the
 * resource deregisters every active revision.
 *
 * `JobDefinition` is a Platform: alongside the low-level container form
 * (`image` + `executionRoleArn`), it supports Effect-native run-to-completion
 * implementations — an inline Effect program that Alchemy bundles,
 * containerizes as the job container's command, pushes to a managed ECR
 * repository, and registers, provisioning the job and execution roles
 * automatically. Capability bindings (e.g. S3 `GetObject`) attach IAM policy
 * statements to the managed job role and inject their environment variables
 * into the container.
 *
 * ### Creating Job Definitions
 * **Example:** Busybox echo job (low-level container form)
 * ```typescript
 * const jobDef = yield* Batch.JobDefinition("EchoJob", {
 *   image: "public.ecr.aws/docker/library/busybox:latest",
 *   command: ["echo", "hello from batch"],
 *   executionRoleArn: executionRole.roleArn,
 * });
 * ```
 *
 * **Example:** Sized job with environment
 * ```typescript
 * const jobDef = yield* Batch.JobDefinition("EtlJob", {
 *   image: image.imageUri,
 *   vcpus: 1,
 *   memory: 2048,
 *   environment: { STAGE: "prod" },
 *   jobRoleArn: jobRole.roleArn,
 *   executionRoleArn: executionRole.roleArn,
 *   retryAttempts: 3,
 *   timeout: "15 minutes",
 * });
 * ```
 *
 * ### Effect-Native Jobs
 * **Example:** Tagged class with an inline run-to-completion Effect
 * ```typescript
 * export default class Nightly extends Batch.JobDefinition<Nightly>()(
 *   "Nightly",
 *   { main: import.meta.url, vcpus: 1, memory: 2048 },
 *   Effect.gen(function* () {
 *     const getObject = yield* AWS.S3.GetObject(bucket);
 *     return {
 *       run: Effect.gen(function* () {
 *         const data = yield* getObject({ key: "input.csv" });
 *         yield* Effect.log("processed nightly batch");
 *       }),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * **Example:** Eager inline job
 * ```typescript
 * export default Batch.JobDefinition(
 *   "Reindex",
 *   { main: import.meta.url },
 *   Effect.succeed({
 *     run: Effect.log("reindex complete"),
 *   }),
 * );
 * ```
 *
 * **Example:** Plain external script (bundled as-is)
 * ```typescript
 * // ./job.ts runs top-level and exits; Alchemy bundles + containerizes it.
 * const jobDef = yield* Batch.JobDefinition("Script", {
 *   main: path.join(import.meta.dirname, "job.ts"),
 * });
 * ```
 *
 * ### Bundling & Tree-shaking
 * `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:** Mark additional packages as pure
 * Only list packages with no top-level side effects.
 * ```typescript
 * {
 *   main: import.meta.url,
 *   build: {
 *     pure: { packages: ["my-lib", "@my-scope/*"] },
 *   },
 * }
 * ```
 *
 * **Example:** Turn it off
 * ```typescript
 * {
 *   main: import.meta.url,
 *   build: { pure: false },
 * }
 * ```
 *
 * @resource
 */
export const JobDefinition: Platform<
  JobDefinition,
  JobDefinitionServices,
  JobDefinitionShape,
  JobDefinitionRuntimeContext
> = Platform("AWS.Batch.JobDefinition", {
  createRuntimeContext: createJobDefinitionRuntimeContext,
});

const observedTagsOf = (d: { tags?: { [key: string]: string | undefined } }) =>
  Object.fromEntries(
    Object.entries(d.tags ?? {}).filter((e): e is [string, string] => typeof e[1] === "string"),
  );

/** Attributes only produced by the Effect-native (`main`) form. */
interface PlatformAttributes {
  imageUri: string | undefined;
  repositoryName: string | undefined;
  repositoryUri: string | undefined;
  jobRoleArn: string | undefined;
  jobRoleName: string | undefined;
  executionRoleName: string | undefined;
  codeHash: string | undefined;
}

const emptyPlatformAttributes: PlatformAttributes = {
  imageUri: undefined,
  repositoryName: undefined,
  repositoryUri: undefined,
  jobRoleArn: undefined,
  jobRoleName: undefined,
  executionRoleName: undefined,
  codeHash: undefined,
};

const toAttributes = (
  d: batch.JobDefinition,
  tags: Record<string, string>,
  platform: PlatformAttributes = emptyPlatformAttributes,
) => ({
  jobDefinitionName: d.jobDefinitionName!,
  jobDefinitionArn: d.jobDefinitionArn as JobDefinitionArn,
  revision: d.revision ?? 1,
  status: d.status ?? "ACTIVE",
  tags,
  executionRoleArn: d.containerProperties?.executionRoleArn,
  ...platform,
});

/**
 * The effective (resolved) container configuration a reconcile wants
 * registered — identical for both forms once the Effect-native form has
 * built its image and roles.
 */
interface EffectiveContainer {
  image: string;
  command: string[] | undefined;
  vcpus: string;
  memory: string;
  environment: Record<string, string>;
  jobRoleArn: string | undefined;
  executionRoleArn: string;
  assignPublicIp: "ENABLED" | "DISABLED";
  parameters: Record<string, string> | undefined;
  retryAttempts: number | undefined;
  timeoutSeconds: number | undefined;
  propagateTags: boolean | undefined;
}

/**
 * Normalized content fingerprint of a job definition — used to decide whether
 * a new revision must be registered. Only covers the aspects this resource
 * manages.
 */
const fingerprint = (input: {
  image?: string;
  command?: string[];
  vcpus?: string;
  memory?: string;
  environment?: Record<string, string>;
  jobRoleArn?: string;
  executionRoleArn?: string;
  assignPublicIp?: string;
  parameters?: Record<string, string>;
  retryAttempts?: number;
  timeoutSeconds?: number;
  propagateTags?: boolean;
  platformCapabilities?: ("EC2" | "FARGATE")[];
}) =>
  JSON.stringify({
    image: input.image,
    command: input.command ?? [],
    vcpus: input.vcpus,
    memory: input.memory,
    environment: Object.entries(input.environment ?? {}).sort(([a], [b]) => a.localeCompare(b)),
    jobRoleArn: input.jobRoleArn,
    executionRoleArn: input.executionRoleArn,
    assignPublicIp: input.assignPublicIp ?? "ENABLED",
    parameters: Object.entries(input.parameters ?? {}).sort(([a], [b]) => a.localeCompare(b)),
    retryAttempts: input.retryAttempts ?? 1,
    timeoutSeconds: input.timeoutSeconds,
    propagateTags: input.propagateTags ?? false,
    platformCapabilities: [...(input.platformCapabilities ?? ["FARGATE"])].sort(),
  });

const observedFingerprint = (d: batch.JobDefinition) => {
  const c = d.containerProperties ?? {};
  const req = (type: string) => c.resourceRequirements?.find((r) => r.type === type)?.value;
  return fingerprint({
    image: c.image,
    command: [...(c.command ?? [])],
    vcpus: req("VCPU"),
    memory: req("MEMORY"),
    environment: Object.fromEntries(
      (c.environment ?? []).flatMap((kv) =>
        kv.name !== undefined ? [[kv.name, kv.value ?? ""]] : [],
      ),
    ),
    jobRoleArn: c.jobRoleArn,
    executionRoleArn: c.executionRoleArn,
    assignPublicIp: c.networkConfiguration?.assignPublicIp,
    parameters: Object.fromEntries(
      Object.entries(d.parameters ?? {}).flatMap(([k, v]) => (v !== undefined ? [[k, v]] : [])),
    ),
    retryAttempts: d.retryStrategy?.attempts,
    timeoutSeconds: d.timeout?.attemptDurationSeconds,
    propagateTags: d.propagateTags,
    platformCapabilities: d.platformCapabilities as ("EC2" | "FARGATE")[] | undefined,
  });
};

const desiredFingerprint = (effective: EffectiveContainer, news: JobDefinitionProps) =>
  fingerprint({
    image: effective.image,
    command: effective.command,
    vcpus: effective.vcpus,
    memory: effective.memory,
    environment: effective.environment,
    jobRoleArn: effective.jobRoleArn,
    executionRoleArn: effective.executionRoleArn,
    assignPublicIp: news.assignPublicIp,
    parameters: effective.parameters,
    retryAttempts: effective.retryAttempts,
    timeoutSeconds: effective.timeoutSeconds,
    propagateTags: effective.propagateTags,
    platformCapabilities: news.platformCapabilities,
  });

export const JobDefinitionProvider = () =>
  Provider.effect(
    JobDefinition,
    Effect.gen(function* () {
      const stack = yield* Stack;
      const docker = yield* Docker;
      const { dotAlchemy } = yield* AlchemyContext;
      const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;

      const alchemyEnv = {
        ALCHEMY_STACK_NAME: stack.name,
        ALCHEMY_STAGE: stack.stage,
        ALCHEMY_PHASE: "runtime",
      };

      const toName = (id: string, props: { jobDefinitionName?: string } = {}) =>
        props.jobDefinitionName
          ? Effect.succeed(props.jobDefinitionName)
          : createPhysicalName({ id, maxLength: 128 });

      const createRoleName = (id: string, suffix: string) =>
        createPhysicalName({ id: `${id}-${suffix}`, maxLength: 64 });

      // Batch caps `containerProperties.image` at 255 characters, and the
      // image ref is `<account>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag>`
      // — up to 52 characters of registry prefix plus the 16-character
      // content tag — so the repository name (ECR itself allows 256) must
      // stop at 180 to fit in every region.
      const createRepositoryName = (id: string) =>
        createPhysicalName({
          id: `${id}-repo`,
          maxLength: 180,
          lowercase: true,
        });

      /** Every ACTIVE revision of the family, ascending by revision. */
      const activeRevisions = (name: string) =>
        batch.describeJobDefinitions.pages({ jobDefinitionName: name, status: "ACTIVE" }).pipe(
          Stream.runCollect,
          Effect.map((pages) =>
            Array.from(pages)
              .flatMap((page) => page.jobDefinitions ?? [])
              .sort((a, b) => (a.revision ?? 0) - (b.revision ?? 0)),
          ),
        );

      const latestRevision = (name: string) =>
        activeRevisions(name).pipe(Effect.map((defs) => defs.at(-1)));

      const waitUntilNoActiveBatchRevisions = (family: string) =>
        Effect.gen(function* () {
          const active = yield* activeRevisions(family);
          if (active.length > 0) {
            return yield* new JobDefinitionStillVisible({
              family,
              service: "Batch",
              arns: active.flatMap((revision) =>
                revision.jobDefinitionArn ? [revision.jobDefinitionArn] : [],
              ),
            });
          }
        }).pipe(
          Effect.retry({
            while: (error) => error._tag === "JobDefinitionStillVisible",
            schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(15)]),
          }),
        );

      const listBackingTaskDefinitions = (family: string, status: "ACTIVE" | "INACTIVE") =>
        ecs.listTaskDefinitions.items({ familyPrefix: family, status }).pipe(
          Stream.filter((arn) => {
            const suffix = arn.split("/").at(-1);
            return suffix?.slice(0, suffix.lastIndexOf(":")) === family;
          }),
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk)),
        );

      const waitUntilBackingRevisionDeletionStarted = (family: string, arn: string) =>
        Effect.gen(function* () {
          const status = yield* ecs.describeTaskDefinition({ taskDefinition: arn }).pipe(
            Effect.map((response) => response.taskDefinition?.status),
            // Not-found means ECS already completed the asynchronous
            // deletion and is therefore terminal as well.
            Effect.catchTag("ClientException", () => Effect.undefined),
          );
          if (status !== undefined && status !== "DELETE_IN_PROGRESS") {
            return yield* new JobDefinitionStillVisible({
              family,
              service: "ECS",
              arns: [arn],
            });
          }
        }).pipe(
          Effect.retry({
            while: (error) => error._tag === "JobDefinitionStillVisible",
            schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(30)]),
          }),
        );

      /**
       * AWS Batch registers an ECS task definition under the same family when
       * a job first runs. It is not part of Batch's list API or Alchemy state,
       * and Batch can leave it ACTIVE after the Batch definition is gone.
       * Exact-family filtering keeps this cleanup scoped to the resource.
       */
      const reapBackingTaskDefinitions = (family: string) =>
        Effect.gen(function* () {
          const active = yield* listBackingTaskDefinitions(family, "ACTIVE");
          yield* Effect.forEach(
            active,
            (arn) =>
              ecs
                .deregisterTaskDefinition({ taskDefinition: arn })
                .pipe(Effect.catchTag("ClientException", () => Effect.void)),
            { concurrency: 4, discard: true },
          );

          // Observe ACTIVE absence before attempting the hard delete. This is
          // the transition ECS requires before deleteTaskDefinitions.
          yield* Effect.gen(function* () {
            const remaining = yield* listBackingTaskDefinitions(family, "ACTIVE");
            if (remaining.length > 0) {
              return yield* new JobDefinitionStillVisible({
                family,
                service: "ECS",
                arns: remaining,
              });
            }
          }).pipe(
            Effect.retry({
              while: (error) => error._tag === "JobDefinitionStillVisible",
              schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(15)]),
            }),
          );

          const inactive = [
            ...new Set([...active, ...(yield* listBackingTaskDefinitions(family, "INACTIVE"))]),
          ];
          for (let i = 0; i < inactive.length; i += 10) {
            const response = yield* ecs.deleteTaskDefinitions({
              taskDefinitions: inactive.slice(i, i + 10),
            });
            if ((response.failures?.length ?? 0) > 0) {
              return yield* new JobDefinitionOperationFailed({
                message: `ECS failed to delete Batch backing task definitions for ${family}: ${response.failures
                  ?.map(
                    (failure) =>
                      `${failure.arn ?? "unknown"}: ${failure.reason ?? "unknown"} (${failure.detail ?? "no detail"})`,
                  )
                  .join(", ")}`,
              });
            }
          }
          yield* Effect.forEach(
            inactive,
            (arn) => waitUntilBackingRevisionDeletionStarted(family, arn),
            { concurrency: 4, discard: true },
          );
        });

      /**
       * Ensure an IAM role trusted by ECS tasks exists (creates on miss,
       * adopts on race when it carries our tags).
       */
      const ensureRole = Effect.fn(function* ({
        id,
        roleName,
        managedPolicyArns,
      }: {
        id: string;
        roleName: string;
        managedPolicyArns?: string[];
      }) {
        const tags = yield* createInternalTags(id);
        const role = yield* iam
          .createRole({
            RoleName: roleName,
            AssumeRolePolicyDocument: JSON.stringify({
              Version: "2012-10-17",
              Statement: [
                {
                  Effect: "Allow",
                  Principal: { Service: "ecs-tasks.amazonaws.com" },
                  Action: "sts:AssumeRole",
                },
              ],
            }),
            Tags: createTagsList(tags),
          })
          .pipe(
            Effect.catchTag("EntityAlreadyExistsException", () =>
              iam.getRole({ RoleName: roleName }).pipe(
                Effect.filterOrFail(
                  (existing) => hasTags(tags, existing.Role?.Tags),
                  () =>
                    new JobDefinitionConflict({
                      message: `Role '${roleName}' already exists and is not managed by alchemy`,
                    }),
                ),
              ),
            ),
          );
        for (const policyArn of managedPolicyArns ?? []) {
          yield* iam
            .attachRolePolicy({ RoleName: roleName, PolicyArn: policyArn })
            .pipe(Effect.catchTag("LimitExceededException", () => Effect.void));
        }
        return role.Role!.Arn!;
      });

      /** Ensure the managed ECR repository for the built image exists. */
      const ensureRepository = Effect.fn(function* ({
        repositoryName,
        tags,
      }: {
        repositoryName: string;
        tags: Record<string, string>;
      }) {
        const created = yield* ecr
          .createRepository({
            repositoryName,
            imageTagMutability: "MUTABLE",
            imageScanningConfiguration: { scanOnPush: true },
            tags: Object.entries(tags).map(([Key, Value]) => ({ Key, Value })),
          })
          .pipe(
            Effect.catchTag("RepositoryAlreadyExistsException", () =>
              Effect.gen(function* () {
                const existing = yield* ecr.describeRepositories({
                  repositoryNames: [repositoryName],
                });
                return { repository: existing.repositories?.[0] };
              }),
            ),
          );
        const repository = created.repository;
        if (!repository?.repositoryUri) {
          return yield* Effect.die(
            new Error(`Failed to resolve ECR repository '${repositoryName}'`),
          );
        }
        return { repositoryUri: repository.repositoryUri };
      });

      /**
       * Attach binding-declared IAM policy statements to the managed job
       * role and collect binding-declared environment variables.
       */
      const attachBindings = Effect.fn(function* ({
        roleName,
        policyName,
        bindings,
      }: {
        roleName: string;
        policyName: string;
        bindings: ResourceBinding<JobDefinition["Binding"]>[];
      }) {
        const activeBindings = bindings.filter(
          (
            binding: ResourceBinding<JobDefinition["Binding"]> & {
              action?: string;
            },
          ) => binding.action !== "delete",
        );

        const env = activeBindings
          .map((binding) => binding?.data?.env)
          .reduce((acc, value) => ({ ...acc, ...value }), {});

        const policyStatements = activeBindings.flatMap(
          (binding) =>
            binding?.data?.policyStatements?.map((statement) => ({
              ...statement,
              Sid: statement.Sid?.replace(/[^A-Za-z0-9]+/gi, ""),
            })) ?? [],
        );

        if (policyStatements.length > 0) {
          yield* iam.putRolePolicy({
            RoleName: roleName,
            PolicyName: policyName,
            PolicyDocument: JSON.stringify({
              Version: "2012-10-17",
              Statement: policyStatements,
            }),
          });
        } else {
          yield* iam
            .deleteRolePolicy({ RoleName: roleName, PolicyName: policyName })
            .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
        }

        return env;
      });

      /** Bundle the Effect-native program into container-ready files. */
      const bundleProgram = Effect.fn(function* (props: JobDefinitionProps) {
        const handler = props.handler ?? "default";
        const realMain = yield* resolveMainPath(props.main!);
        const cwd = yield* findCwdForBundle(realMain);

        const buildBundle = Effect.fn(function* (
          entry: string,
          plugins?: rolldown.RolldownPluginOption,
        ) {
          return yield* Bundle.build(
            roleHostBundle({
              ...props.build?.input,
              input: entry,
              cwd,
              platform: "node",
              // The container runs on `bun`; keep `bun`/`bun:*` external (the
              // runtime provides them) and resolve the `bun` export condition
              // so `@effect/platform-bun` picks its Bun implementations.
              external: [
                "bun",
                "bun:*",
                ...((props.build?.input?.external as string[] | undefined) ?? []),
              ],
              resolve: {
                conditionNames: [...Bundle.BUN_CONDITION_NAMES],
                ...props.build?.input?.resolve,
              },
              plugins: [props.build?.input?.plugins, plugins],
            }),
            {
              ...props.build?.output,
              format: "esm",
              sourcemap: props.build?.output?.sourcemap ?? false,
              minify: props.build?.output?.minify ?? false,
              entryFileNames: "index.mjs",
            },
            props.build,
          );
        });

        const bundleOutput = props.isExternal
          ? yield* buildBundle(realMain)
          : yield* buildBundle(
              realMain,
              virtualEntryPlugin(
                (importPath) => `
import { bootstrap } from "@alchemy.run/aws/Bootstrap/Batch";
import { ${handler} as entrypoint } from ${JSON.stringify(importPath)};

await bootstrap(entrypoint);
`,
              ),
            );

        // Return every emitted file (entry + shared chunks). Dynamic imports
        // in the AWS SDK split into chunks; dropping any of them crashes the
        // container with `Cannot find module './chunk-X.js'`.
        const files = bundleOutput.files.map((file) => ({
          path: file.path,
          content:
            typeof file.content === "string"
              ? new TextEncoder().encode(file.content)
              : file.content,
        }));

        // 16 hex characters of the content hash, like the ECS/App Runner image
        // sources: the full sha256 as a tag pushed long repository names over
        // Batch's 255-character `image` limit.
        return { files, hash: bundleOutput.hash.slice(0, 16) };
      });

      /** Build + push the container image for the bundled program. */
      const buildAndPushImage = Effect.fn(function* ({
        id,
        repositoryUri,
        hash,
        files,
        props,
      }: {
        id: string;
        repositoryUri: string;
        hash: string;
        files: { path: string; content: Uint8Array<ArrayBufferLike> }[];
        props: JobDefinitionProps;
      }) {
        const realMain = yield* resolveMainPath(props.main!);
        const contextDir = yield* getStableContextDir(realMain, dotAlchemy, `${id}-image`);
        const imageUri = `${repositoryUri}:${hash}`;

        const generatedDockerfile = (() => {
          const base = props.docker?.base ?? "public.ecr.aws/docker/library/bun:1";
          return [
            `FROM ${base}`,
            `WORKDIR /app`,
            `COPY index.mjs /app/index.mjs`,
            // Copy any additional rolldown chunks (`chunk-XXX.js`, ...).
            // Non-trivial bundles always emit at least one; minimal bundles
            // emit none and the COPY no-ops.
            `COPY *.js /app/`,
            `ENTRYPOINT ["bun", "/app/index.mjs"]`,
          ].join("\n");
        })();

        const dockerfile = props.docker?.dockerfile ?? generatedDockerfile;

        yield* docker.materialize({
          context: contextDir,
          dockerfile,
          // Entry chunk becomes `index.mjs`; all other chunks keep their
          // emitted `*.js` names so the entry's relative imports resolve.
          files: files.map((file, index) => ({
            path: index === 0 ? "index.mjs" : file.path,
            content: file.content,
          })),
        });
        // Batch Fargate defaults to X86_64 — always build linux/amd64
        // (cross-built via emulation on ARM64 hosts).
        return yield* buildAndPushEcrImage(docker, {
          imageUri,
          context: contextDir,
          platform: "linux/amd64",
        });
      });

      /**
       * Delete the managed platform resources (ECR repository, job +
       * execution roles). Used by `delete` and by a reconcile that switches
       * an Effect-native definition back to the low-level form. Idempotent.
       */
      const cleanupPlatformResources = Effect.fn(function* (platform: {
        repositoryName?: string | undefined;
        jobRoleName?: string | undefined;
        executionRoleName?: string | undefined;
      }) {
        if (platform.repositoryName) {
          yield* ecr
            .deleteRepository({
              repositoryName: platform.repositoryName,
              force: true,
            })
            .pipe(Effect.catchTag("RepositoryNotFoundException", () => Effect.void));
        }
        for (const roleName of [platform.jobRoleName, platform.executionRoleName]) {
          if (!roleName) continue;
          yield* iam.listRolePolicies.items({ RoleName: roleName }).pipe(
            Stream.mapEffect((policyName) =>
              iam
                .deleteRolePolicy({
                  RoleName: roleName,
                  PolicyName: policyName,
                })
                .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void)),
            ),
            Stream.runDrain,
            Effect.catchTag("NoSuchEntityException", () => Effect.void),
          );
          yield* iam.listAttachedRolePolicies.items({ RoleName: roleName }).pipe(
            Stream.mapEffect((policy) =>
              iam
                .detachRolePolicy({
                  RoleName: roleName,
                  PolicyArn: policy.PolicyArn!,
                })
                .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void)),
            ),
            Stream.runDrain,
            Effect.catchTag("NoSuchEntityException", () => Effect.void),
          );
          yield* iam
            .deleteRole({ RoleName: roleName })
            .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
        }
      });

      return {
        stables: [
          "jobDefinitionName",
          "repositoryName",
          "repositoryUri",
          "jobRoleArn",
          "jobRoleName",
          "executionRoleName",
        ],
        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return;
          if ((yield* toName(id, olds ?? {})) !== (yield* toName(id, news ?? {}))) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.jobDefinitionName ?? (yield* toName(id, olds ?? {}));
          const latest = yield* latestRevision(name);
          if (!latest?.jobDefinitionArn) return undefined;
          // Managed platform resources (repo, roles) are stable identifiers —
          // carry them through from the cached output.
          return toAttributes(latest, observedTagsOf(latest), {
            ...emptyPlatformAttributes,
            ...(output
              ? {
                  imageUri: output.imageUri,
                  repositoryName: output.repositoryName,
                  repositoryUri: output.repositoryUri,
                  jobRoleArn: output.jobRoleArn,
                  jobRoleName: output.jobRoleName,
                  executionRoleName: output.executionRoleName,
                  codeHash: output.codeHash,
                }
              : {}),
          });
        }),
        list: () =>
          Effect.gen(function* () {
            // Enumerate the latest ACTIVE revision of every family.
            const pages = yield* batch.describeJobDefinitions
              .pages({ status: "ACTIVE" })
              .pipe(Stream.runCollect);
            const latest = new Map<string, batch.JobDefinition>();
            for (const page of pages) {
              for (const d of page.jobDefinitions ?? []) {
                if (!d.jobDefinitionName || !d.jobDefinitionArn) continue;
                const prior = latest.get(d.jobDefinitionName);
                if (!prior || (prior.revision ?? 0) < (d.revision ?? 0)) {
                  latest.set(d.jobDefinitionName, d);
                }
              }
            }
            return Array.from(latest.values()).map((d) => toAttributes(d, observedTagsOf(d)));
          }),
        reconcile: Effect.fn(function* ({ id, news, bindings, output, session }) {
          const { region } = yield* AWSEnvironment.current;
          const name = output?.jobDefinitionName ?? (yield* toName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          if (news.main !== undefined && news.image !== undefined) {
            return yield* new JobDefinitionConfigError({
              message:
                "`main` (Effect-native form) and `image` (low-level form) are mutually exclusive",
            });
          }
          if (news.main === undefined && news.image === undefined) {
            return yield* new JobDefinitionConfigError({
              message: "one of `main` (Effect-native form) or `image` (low-level form) is required",
            });
          }
          if (news.main === undefined && news.executionRoleArn === undefined) {
            return yield* new JobDefinitionConfigError({
              message:
                "`executionRoleArn` is required with `image` (Fargate jobs pull the image and write logs through it)",
            });
          }

          // Resolve the effective container configuration. The Effect-native
          // form first ensures its managed roles + repository, bundles the
          // program, and builds + pushes the image; the low-level form uses
          // the caller-supplied image and roles directly. Each ensure step is
          // independently idempotent.
          let platformAttributes = emptyPlatformAttributes;
          let effective: EffectiveContainer;
          if (news.main !== undefined) {
            const jobRoleName = output?.jobRoleName ?? (yield* createRoleName(id, "job-role"));
            const executionRoleName =
              output?.executionRoleName ?? (yield* createRoleName(id, "execution-role"));
            const repositoryName = output?.repositoryName ?? (yield* createRepositoryName(id));
            const jobPolicyName = yield* createPhysicalName({
              id: `${id}-job-policy`,
              maxLength: 128,
            });

            const jobRoleArn = yield* ensureRole({
              id,
              roleName: jobRoleName,
              managedPolicyArns: news.jobRoleManagedPolicyArns,
            });
            const executionRoleArn = yield* ensureRole({
              id,
              roleName: executionRoleName,
              managedPolicyArns: [
                "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy",
              ],
            });

            const bindingEnv = yield* attachBindings({
              roleName: jobRoleName,
              policyName: jobPolicyName,
              bindings,
            });

            const { repositoryUri } =
              output?.repositoryUri && output.repositoryName === repositoryName
                ? { repositoryUri: output.repositoryUri }
                : yield* ensureRepository({
                    repositoryName,
                    tags: desiredTags,
                  });

            const { files, hash } = yield* bundleProgram(news);
            const imageUri = yield* buildAndPushImage({
              id,
              repositoryUri,
              hash,
              files,
              props: news,
            });

            platformAttributes = {
              imageUri,
              repositoryName,
              repositoryUri,
              jobRoleArn,
              jobRoleName,
              executionRoleName,
              codeHash: hash,
            };
            effective = {
              image: imageUri,
              command: undefined,
              vcpus: String(news.vcpus ?? 0.25),
              memory: String(news.memory ?? 512),
              environment: {
                // Bindings + alchemy runtime env first (JSON-encoded), then
                // the caller's `env`, then plain `environment` wins last.
                ...Object.fromEntries(
                  Object.entries({
                    ...bindingEnv,
                    ...alchemyEnv,
                    // Fargate does not inject AWS_REGION — the bundled
                    // program's `Region.fromEnv()` needs it.
                    AWS_REGION: region,
                    ...news.env,
                  }).map(([key, value]) => [
                    key,
                    typeof value === "string" ? value : JSON.stringify(value),
                  ]),
                ),
                ...news.environment,
              },
              jobRoleArn,
              executionRoleArn,
              assignPublicIp: news.assignPublicIp ?? "ENABLED",
              parameters: news.parameters,
              retryAttempts: news.retryAttempts,
              timeoutSeconds: toWireSeconds(news.timeout),
              propagateTags: news.propagateTags,
            };
          } else {
            // Low-level form. If a previous deploy used the Effect-native
            // form, its managed repo/roles are no longer referenced — reap
            // them so nothing leaks.
            if (output?.repositoryName || output?.jobRoleName || output?.executionRoleName) {
              yield* cleanupPlatformResources(output);
            }
            effective = {
              image: news.image!,
              command: news.command,
              vcpus: String(news.vcpus ?? 0.25),
              memory: String(news.memory ?? 512),
              environment: { ...news.environment },
              jobRoleArn: news.jobRoleArn,
              executionRoleArn: news.executionRoleArn!,
              assignPublicIp: news.assignPublicIp ?? "ENABLED",
              parameters: news.parameters,
              retryAttempts: news.retryAttempts,
              timeoutSeconds: toWireSeconds(news.timeout),
              propagateTags: news.propagateTags,
            };
          }

          // Observe — the latest ACTIVE revision is the live state.
          const latest = yield* latestRevision(name);

          // Ensure/Sync — register a new revision only when managed content
          // differs (revisions are immutable; registration IS the update).
          if (!latest || observedFingerprint(latest) !== desiredFingerprint(effective, news)) {
            const platformCapabilities = news.platformCapabilities ?? ["FARGATE"];
            const registered = yield* batch.registerJobDefinition({
              jobDefinitionName: name,
              type: "container",
              platformCapabilities,
              containerProperties: {
                image: effective.image,
                command: effective.command,
                jobRoleArn: effective.jobRoleArn,
                executionRoleArn: effective.executionRoleArn,
                resourceRequirements: [
                  { type: "VCPU", value: effective.vcpus },
                  { type: "MEMORY", value: effective.memory },
                ],
                environment: Object.entries(effective.environment).map(([key, value]) => ({
                  name: key,
                  value,
                })),
                networkConfiguration: platformCapabilities.includes("FARGATE")
                  ? { assignPublicIp: effective.assignPublicIp }
                  : undefined,
              },
              parameters: effective.parameters,
              retryStrategy:
                effective.retryAttempts !== undefined
                  ? { attempts: effective.retryAttempts }
                  : undefined,
              timeout:
                effective.timeoutSeconds !== undefined
                  ? { attemptDurationSeconds: effective.timeoutSeconds }
                  : undefined,
              propagateTags: effective.propagateTags,
              tags: desiredTags,
            });
            yield* session.note(registered.jobDefinitionArn);
            return {
              jobDefinitionName: registered.jobDefinitionName,
              jobDefinitionArn: registered.jobDefinitionArn as JobDefinitionArn,
              revision: registered.revision,
              status: "ACTIVE",
              tags: desiredTags,
              executionRoleArn: effective.executionRoleArn,
              ...platformAttributes,
            };
          }

          // Content unchanged — sync tags in place on the revision ARN.
          const { upsert, removed } = diffTags(observedTagsOf(latest), desiredTags);
          if (upsert.length > 0) {
            yield* batch.tagResource({
              resourceArn: latest.jobDefinitionArn!,
              tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }
          if (removed.length > 0) {
            yield* batch.untagResource({
              resourceArn: latest.jobDefinitionArn!,
              tagKeys: removed,
            });
          }

          yield* session.note(latest.jobDefinitionArn!);
          return toAttributes(latest, desiredTags, platformAttributes);
        }),
        delete: Effect.fn(function* ({ output }) {
          // Deregister EVERY active revision of the family. Deregistration is
          // idempotent (succeeds when the revision is already gone).
          const revisions = yield* activeRevisions(output.jobDefinitionName);
          yield* Effect.forEach(
            revisions,
            (d) =>
              batch.deregisterJobDefinition({
                jobDefinition: `${d.jobDefinitionName}:${d.revision}`,
              }),
            { concurrency: 4 },
          );
          yield* waitUntilNoActiveBatchRevisions(output.jobDefinitionName);

          // A submitted Batch job causes AWSServiceRoleForBatch to create a
          // backing ECS task-definition revision with the exact same family.
          // Batch deregistration does not reliably reclaim it, so delete it
          // explicitly only after the Batch family is observed inactive.
          yield* reapBackingTaskDefinitions(output.jobDefinitionName);

          // Reap the managed platform resources (Effect-native form only).
          yield* cleanupPlatformResources(output);

          // Reap this family's log streams from the shared, service-managed
          // `/aws/batch/job` group. The awslogs driver names streams
          // `{jobDefinitionName}/default/{taskId}`, so the family prefix is
          // exact; the group itself is account-level AWS infrastructure
          // (recreated by the Batch service on the next job) and is left
          // alone.
          const logGroupName = "/aws/batch/job";
          const streams = yield* logs.describeLogStreams
            .pages({
              logGroupName,
              logStreamNamePrefix: `${output.jobDefinitionName}/`,
            })
            .pipe(
              Stream.runCollect,
              Effect.map((pages) => Array.from(pages).flatMap((p) => p.logStreams ?? [])),
              Effect.catchTag("ResourceNotFoundException", () => Effect.succeed([])),
            );
          yield* Effect.forEach(
            streams,
            (s) =>
              s.logStreamName === undefined
                ? Effect.void
                : logs
                    .deleteLogStream({
                      logGroupName,
                      logStreamName: s.logStreamName,
                    })
                    .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void)),
            { concurrency: 4 },
          );
        }),
      };
    }),
  );