alchemy 2.0.0-beta.74 → 2.0.0-beta.76

package/lib/AWS/Lambda/Function.js

@@ -4,6 +4,7 @@ import * as Lambda from "@distilled.cloud/aws/lambda";
 import { Region } from "@distilled.cloud/aws/Region";
 import * as Cause from "effect/Cause";
 import * as Context from "effect/Context";
+import * as Data from "effect/Data";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
@@ -33,8 +34,13 @@ import { AWSEnvironment } from "../Environment.js";
 import * as IAM from "../IAM/index.js";
 import { syncEventInvokeConfig, } from "./EventInvokeConfig.js";
 import { makeFunctionBundler } from "./FunctionBundle.js";
+import { decodeFunctionImageSource, makeFunctionImage, } from "./FunctionImage.js";
 import { makeFunctionHttpHandler } from "./HttpServer.js";
 export const FunctionTypeId = "AWS.Lambda.Function";
+class FunctionUpdatePending extends Data.TaggedError("FunctionUpdatePending") {
+}
+class FunctionUpdateFailed extends Data.TaggedError("FunctionUpdateFailed") {
+}
 export class HandlerContext extends Context.Service()("AWS.Lambda.HandlerContext") {
 }
 export const isFunction = (value) => {
@@ -80,6 +86,53 @@ const accessPointArnOf = (config) => typeof config.accessPoint === "string"
         ?.accessPointArn === "string"
         ? config.accessPoint.accessPointArn
         : config.arn;
+const isFunctionImageProps = (props) => props.image !== undefined;
+/**
+ * Validate package-mode exclusivity before any Lambda or ECR mutation.
+ * @internal
+ */
+export const validateFunctionPackageProps = Effect.fn("AWS.Lambda.validateFunctionPackageProps")(function* (id, props) {
+    if (props.image === undefined) {
+        if (props.main === undefined) {
+            return yield* Effect.fail(new Error(`Function(${id}): declare exactly one of main or image`));
+        }
+        return;
+    }
+    const incompatible = [
+        ["main", props.main],
+        ["handler", props.handler],
+        ["runtime", props.runtime],
+        ["layers", props.layers],
+        ["build", props.build],
+        ["uploadSourceMap", props.uploadSourceMap],
+        ["exports", props.exports],
+        ["durableConfig", props.durableConfig],
+    ].flatMap(([name, value]) => (value === undefined ? [] : [name]));
+    if (incompatible.length > 0) {
+        return yield* Effect.fail(new Error(`Function(${id}): image functions cannot use ZIP/runtime options: ${incompatible.join(", ")}`));
+    }
+});
+/**
+ * The Lambda `ImageConfig` for an image source's overrides; `undefined` when
+ * the source declares none, so the image's own instructions apply.
+ */
+const toLambdaImageConfig = (config) => config === undefined ||
+    (config.command === undefined &&
+        config.entryPoint === undefined &&
+        config.workingDirectory === undefined)
+    ? undefined
+    : {
+        Command: config.command === undefined ? undefined : [...config.command],
+        EntryPoint: config.entryPoint === undefined ? undefined : [...config.entryPoint],
+        WorkingDirectory: config.workingDirectory,
+    };
+/**
+ * `UpdateFunctionConfiguration` preserves old image overrides when the field
+ * is omitted. An empty object therefore means "clear overrides" on update.
+ */
+const imageConfigForUpdate = (props) => isFunctionImageProps(props)
+    ? (toLambdaImageConfig(props.image) ?? {})
+    : undefined;
 /**
  * The Lambda `Handler` string for a function's props: `<file>.<export>`.
  * Bundled functions always emit `index.js`; prebuilt directories
@@ -140,12 +193,13 @@ export const normalizeFunctionUrl = (url = true) => {
  * An AWS Lambda host resource that combines code bundling, IAM role
  * provisioning, and runtime binding collection.
  *
- * `Function` is the canonical runtime host for AWS. Alchemy automatically
- * bundles your TypeScript entry module with Rolldown, creates an IAM
- * execution role, and uploads the zip artifact. On subsequent deploys, the
- * function is only updated when the bundle hash changes.
+ * `Function` is the canonical runtime host for AWS. It can either bundle a
+ * TypeScript entry module into a zip artifact or build a user-authored
+ * Dockerfile into a Lambda container image. In both modes Alchemy creates the
+ * execution role and applies bindings; image mode additionally owns the
+ * private ECR repository and Lambda pull policy.
  *
- * There are two ways to define a Lambda Function:
+ * Zip-packaged functions can be defined in two ways:
  *
  * - **Async** — plain handler export, no Effect runtime in the bundle.
  * - **Effect** — Effect implementation with typed bindings and event sources.
@@ -214,6 +268,54 @@ export const normalizeFunctionUrl = (url = true) => {
  * };
  * ```
  *
+ * ### Container Image Functions
+ * Set `image` instead of `main` to deploy an existing private ECR image or to
+ * build and publish a local Docker context. Image sources must be literal
+ * because Lambda's pre-create phase needs the deployable image before normal
+ * Output resolution.
+ *
+ * #### Existing ECR image with runtime overrides
+ * ```typescript
+ * const func = yield* AWS.Lambda.Function("Worker", {
+ *   image: {
+ *     uri: "123456789012.dkr.ecr.us-east-1.amazonaws.com/worker@sha256:...",
+ *     command: ["app.handler"],
+ *     entryPoint: ["/lambda-entrypoint.sh"],
+ *     workingDirectory: "/var/task",
+ *   },
+ *   architecture: "x86_64",
+ * });
+ * ```
+ *
+ * Tagged URIs are resolved through ECR on each plan. If a tag is repointed to
+ * a new digest, Alchemy updates the Lambda function even though the URI string
+ * is unchanged. External repositories are never modified or deleted.
+ *
+ * #### Build a Lambda container image
+ * ```typescript
+ * const func = yield* AWS.Lambda.Function("JavaFunction", {
+ *   image: {
+ *     context: "./lambda",
+ *     dockerfile: "Dockerfile",
+ *     buildArgs: {
+ *       APP_ENV: "production",
+ *     },
+ *   },
+ *   architecture: "arm64",
+ *   functionUrl: false,
+ * });
+ * ```
+ *
+ * The Dockerfile owns the runtime and handler. Alchemy does not generate a
+ * Node.js adapter or otherwise impose a language. For example,
+ * `./lambda/Dockerfile` can use AWS's Java base image:
+ *
+ * ```dockerfile
+ * FROM public.ecr.aws/lambda/java:21
+ * COPY target/function.jar ${LAMBDA_TASK_ROOT}/lib/
+ * CMD ["com.example.Handler::handleRequest"]
+ * ```
+ *
  * ### Effect Functions
  * Pass the Effect implementation as the third argument. Bindings
  * attach IAM permissions and environment variables at deploy time,
@@ -588,6 +690,7 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
     // Code bundling lives in FunctionBundle.ts so the floci local
     // provider's watch loop can rebuild the identical artifact.
     const { bundleCode } = yield* makeFunctionBundler;
+    const functionImage = yield* makeFunctionImage;
     const alchemyEnv = {
         ALCHEMY_STACK_NAME: stack.name,
         ALCHEMY_STAGE: stack.stage,
@@ -768,6 +871,31 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
             Schedule.recurs(30),
         ]),
     });
+    const waitForFunctionUpdate = Effect.fn(function* (functionName, session) {
+        return yield* Effect.gen(function* () {
+            const configuration = (yield* Lambda.getFunction({
+                FunctionName: functionName,
+            })).Configuration;
+            if (configuration?.State === "Failed" ||
+                configuration?.LastUpdateStatus === "Failed") {
+                return yield* new FunctionUpdateFailed({
+                    functionName,
+                    reason: configuration.LastUpdateStatusReason ??
+                        configuration.StateReason,
+                });
+            }
+            if (configuration?.State === "Active" &&
+                (configuration.LastUpdateStatus === undefined ||
+                    configuration.LastUpdateStatus === "Successful")) {
+                return;
+            }
+            return yield* new FunctionUpdatePending({ functionName });
+        }).pipe(Effect.retry({
+            while: (error) => error._tag === "FunctionUpdatePending",
+            schedule: Schedule.spaced("2 seconds").pipe(Schedule.tap(({ attempt }) => session.note(`Waiting for Lambda image update before repository cleanup: ${functionName} (${attempt * 2}s)`))),
+            times: 30,
+        }));
+    });
     const getReservedConcurrentExecutions = Effect.fn(function* (functionName) {
         return yield* Lambda.getFunctionConcurrency({
             FunctionName: functionName,
@@ -790,7 +918,66 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
         }).pipe(retryFunctionMutation);
         return (updated.ReservedConcurrentExecutions ?? reservedConcurrentExecutions);
     });
-    const createOrUpdateFunction = Effect.fn(function* ({ id, news, roleArn, archive, hash, env, functionName, preferUpdate, fileSystemConfigs, vpc, session, }) {
+    const prepareImageFunctionCode = Effect.fn(function* ({ id, props, previousImage, session, }) {
+        const { hash, ...image } = yield* functionImage.resolve({
+            id,
+            source: props.image,
+            architecture: props.architecture,
+            previousImage,
+            session,
+        });
+        return {
+            deployment: {
+                packageType: "Image",
+                imageUri: image.imageUri,
+                hash,
+            },
+            attributes: { hash, image },
+        };
+    });
+    const preparePrecreatedFunctionCode = Effect.fn(function* ({ id, props, session, }) {
+        if (isFunctionImageProps(props)) {
+            return yield* prepareImageFunctionCode({ id, props, session });
+        }
+        // Mock code for the pre-created stub. It responds 503 (rather than a
+        // bare 200) so that, during the brief window where the real code/config
+        // update is still `InProgress`, a Function URL hit serves an honest
+        // "not ready" signal. Downstream readiness probes already retry on
+        // non-200, so they wait for the real handler without blocking the
+        // provider.
+        const code = new TextEncoder().encode(`export default () => ({ statusCode: 503, headers: { "content-type": "application/json" }, body: JSON.stringify({ error: "function initializing" }) })`);
+        const archive = yield* zipCode(code);
+        const hash = yield* hashBundle(code);
+        return {
+            deployment: {
+                packageType: "Zip",
+                archive,
+                hash,
+            },
+            attributes: { hash },
+        };
+    });
+    const prepareFunctionCode = Effect.fn(function* ({ id, props, previousImage, session, }) {
+        if (isFunctionImageProps(props)) {
+            return yield* prepareImageFunctionCode({
+                id,
+                props,
+                previousImage,
+                session,
+            });
+        }
+        const { identityHash, buildArchive } = yield* bundleCode(id, props);
+        const { archive, archiveHash } = yield* buildArchive;
+        return {
+            deployment: {
+                packageType: "Zip",
+                archive,
+                hash: archiveHash,
+            },
+            attributes: { hash: identityHash },
+        };
+    });
+    const createOrUpdateFunction = Effect.fn(function* ({ id, news, roleArn, code, env, functionName, preferUpdate, fileSystemConfigs, vpc, session, }) {
         yield* Effect.logDebug(`creating function ${id}`);
         const waitStartedAt = Date.now();
         const isRolePropagationError = (e) => e._tag === "InvalidParameterValueException" &&
@@ -802,42 +989,54 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
                     e.message?.includes("ARN does not refer to a valid principal")));
         const noteRolePropagationWait = () => session.note(`Waiting for Lambda execution role to become assumable: ${functionName} (${Math.ceil((Date.now() - waitStartedAt) / 1000)}s)`);
         const tags = yield* createInternalTags(id);
-        // Try to use S3 if assets bucket is available, otherwise fall back to inline ZipFile
-        const assets = (yield* Effect.serviceOption(Assets)).pipe(Option.getOrUndefined);
         const codeLocation = yield* Effect.gen(function* () {
-            if (assets) {
-                const key = yield* assets.uploadAsset(hash, archive);
-                yield* Effect.logDebug(`Using S3 for code: s3://${yield* assets.bucketName}/${key}`);
-                return {
-                    S3Bucket: yield* assets.bucketName,
-                    S3Key: key,
-                };
+            if (code.packageType === "Image") {
+                return { ImageUri: code.imageUri };
             }
-            else {
-                return { ZipFile: archive };
+            // Try to use S3 if the assets bucket is available, otherwise fall
+            // back to an inline ZipFile.
+            const assets = (yield* Effect.serviceOption(Assets)).pipe(Option.getOrUndefined);
+            if (!assets) {
+                return { ZipFile: code.archive };
             }
+            const key = yield* assets.uploadAsset(code.hash, code.archive);
+            yield* Effect.logDebug(`Using S3 for code: s3://${yield* assets.bucketName}/${key}`);
+            return {
+                S3Bucket: yield* assets.bucketName,
+                S3Key: key,
+            };
         });
-        const runtimeEnv = withNodeSourceMaps(env, news);
+        const runtimeEnv = isFunctionImageProps(news)
+            ? env
+            : withNodeSourceMaps(env, news);
         const createFunctionRequest = {
             FunctionName: functionName,
-            // Effect-mode functions are wrapped in a generated entry whose ONLY
-            // export is `default` — `handler` names an export of the USER's
-            // module and can only address it when the module is bundled as-is
-            // (isExternal / bundle: false). Honoring it in Effect mode deploys
-            // a Lambda that dies at init with Runtime.HandlerNotFound.
-            // Prebuilt directories keep their own entry filename, so the
-            // handler prefix is `main`'s basename instead of the bundler's
-            // fixed `index`.
-            Handler: handlerStringOf(news),
             Role: roleArn,
             Code: codeLocation,
-            Runtime: news.runtime ?? "nodejs24.x",
+            ...(isFunctionImageProps(news)
+                ? {
+                    PackageType: "Image",
+                    ImageConfig: toLambdaImageConfig(news.image),
+                }
+                : {
+                    // Effect-mode functions are wrapped in a generated entry whose
+                    // ONLY export is `default` — `handler` names an export of the
+                    // USER's module and can only address it when the module is
+                    // bundled as-is (isExternal). Honoring it in Effect mode
+                    // deploys a Lambda that dies at init with
+                    // Runtime.HandlerNotFound.
+                    Handler: handlerStringOf(news),
+                    Runtime: news.runtime ?? "nodejs24.x",
+                    PackageType: "Zip",
+                }),
             Architectures: [news.architecture ?? "x86_64"],
             MemorySize: news.memorySize,
             // Always explicit: `UpdateFunctionConfiguration` treats an omitted
             // `Layers` as "leave as-is", so removing the prop would strand the
             // previously-attached layers.
-            Layers: (news.layers ?? []).map(layerVersionArnOf),
+            Layers: isFunctionImageProps(news)
+                ? undefined
+                : (news.layers ?? []).map(layerVersionArnOf),
             Environment: runtimeEnv
                 ? {
                     Variables: {
@@ -880,13 +1079,7 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
             yield* Lambda.updateFunctionCode({
                 FunctionName: createFunctionRequest.FunctionName,
                 Architectures: createFunctionRequest.Architectures,
-                // Use S3 or ZipFile based on what was used for create
-                ...("S3Bucket" in codeLocation
-                    ? {
-                        S3Bucket: codeLocation.S3Bucket,
-                        S3Key: codeLocation.S3Key,
-                    }
-                    : { ZipFile: codeLocation.ZipFile }),
+                ...codeLocation,
             }).pipe(Effect.tapError((e) => isRolePropagationError(e)
                 ? noteRolePropagationWait()
                 : Effect.void), Effect.retry({
@@ -903,7 +1096,7 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
                 EphemeralStorage: createFunctionRequest.EphemeralStorage,
                 FileSystemConfigs: createFunctionRequest.FileSystemConfigs,
                 Handler: createFunctionRequest.Handler,
-                ImageConfig: createFunctionRequest.ImageConfig,
+                ImageConfig: imageConfigForUpdate(news),
                 KMSKeyArn: createFunctionRequest.KMSKeyArn,
                 Layers: createFunctionRequest.Layers,
                 LoggingConfig: createFunctionRequest.LoggingConfig,
@@ -1016,16 +1209,50 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
         }
         return undefined;
     });
-    const summary = ({ archive }) => `${archive.length >= 1024 * 1024
-        ? `${(archive.length / (1024 * 1024)).toFixed(2)}MB`
-        : archive.length >= 1024
-            ? `${(archive.length / 1024).toFixed(2)}KB`
-            : `${archive.length}B`}`;
+    const summary = (code) => code.packageType === "Image"
+        ? code.imageUri
+        : code.archive.length >= 1024 * 1024
+            ? `${(code.archive.length / (1024 * 1024)).toFixed(2)}MB`
+            : code.archive.length >= 1024
+                ? `${(code.archive.length / 1024).toFixed(2)}KB`
+                : `${code.archive.length}B`;
+    const refreshPersistedFunctionCode = ({ output, packageType, observed, }) => {
+        if (output?.code === undefined) {
+            // Cold adoption has no persisted source hash. Return a complete
+            // Attributes shape and let the forced post-adoption reconcile write
+            // the desired code and replace this placeholder.
+            return { hash: "" };
+        }
+        if (packageType !== "Image" || output.code.image === undefined) {
+            return output.code;
+        }
+        // Lambda can refresh the deployed URI and digest, but it cannot
+        // reconstruct Alchemy's source hash or prove repository ownership.
+        // Preserve that metadata from state instead of inferring a managed
+        // repository from an arbitrary image during adoption.
+        const resolvedImageUri = observed?.ResolvedImageUri;
+        const digest = resolvedImageUri?.split("@").at(-1);
+        return {
+            ...output.code,
+            image: {
+                ...output.code.image,
+                ...(observed?.ImageUri === undefined
+                    ? {}
+                    : { imageUri: observed.ImageUri }),
+                ...(resolvedImageUri === undefined ? {} : { resolvedImageUri }),
+                ...(digest === undefined ? {} : { digest }),
+            },
+        };
+    };
     return {
         stables: ["functionArn", "functionName", "roleName"],
         diff: Effect.fn(function* ({ id, olds, news, output }) {
             if (!isResolved(news))
                 return;
+            yield* validateFunctionPackageProps(id, news);
+            if (isFunctionImageProps(news)) {
+                yield* decodeFunctionImageSource(id, news.image);
+            }
             // If output is undefined (resource in creating state), defer to default diff
             if (!output) {
                 return undefined;
@@ -1036,25 +1263,65 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
             // can force a replace.
             const newFunctionName = news.functionName ?? output.functionName;
             if (output.functionName !== newFunctionName) {
+                // The new physical name differs from the deployed name, so it can
+                // be created before dependents switch over and the old function is
+                // deleted. delete-first is only needed by replacements that reuse
+                // the same explicit name below.
                 return { action: "replace" };
             }
-            if (!!olds.durableConfig !== !!news.durableConfig) {
+            if (isFunctionImageProps(olds) !== isFunctionImageProps(news)) {
+                return {
+                    action: "replace",
+                    deleteFirst: news.functionName !== undefined,
+                };
+            }
+            if (!isFunctionImageProps(olds) &&
+                !isFunctionImageProps(news) &&
+                !!olds.durableConfig !== !!news.durableConfig) {
                 // DurableConfig can only be enabled/disabled at CreateFunction —
                 // switching a logical id between Function and DurableFunction (or
                 // vice versa) must replace the physical function.
-                return { action: "replace" };
+                return {
+                    action: "replace",
+                    deleteFirst: news.functionName !== undefined,
+                };
             }
             if (!deepEqual(normalizeFunctionUrl(olds.functionUrl), normalizeFunctionUrl(news.functionUrl))) {
                 return { action: "update" };
             }
-            if (output.code.hash !== (yield* bundleCode(id, news)).identityHash) {
+            let imageIdentity;
+            let codeHash;
+            if (isFunctionImageProps(news)) {
+                imageIdentity = yield* functionImage.identity(id, news.image, news.architecture);
+                codeHash = imageIdentity.hash;
+            }
+            else {
+                codeHash = (yield* bundleCode(id, news)).identityHash;
+            }
+            if (output.code.hash !== codeHash) {
                 // code changed
                 return { action: "update" };
             }
+            if (isFunctionImageProps(news)) {
+                const image = output.code.image;
+                if (image === undefined ||
+                    image.source !== imageIdentity?.source ||
+                    (imageIdentity?.source === "uri"
+                        ? image.imageUri !== imageIdentity.imageUri ||
+                            image.resolvedImageUri !== imageIdentity.resolvedImageUri
+                        : image.imageUri !== `${image.repositoryUri}:${codeHash}` ||
+                            !(yield* functionImage.isReady(id, image.repositoryName, codeHash)))) {
+                    return { action: "update" };
+                }
+                if (isFunctionImageProps(olds) &&
+                    !deepEqual(toLambdaImageConfig(olds.image), toLambdaImageConfig(news.image))) {
+                    return { action: "update" };
+                }
+            }
             if (toTimeoutSeconds(olds.timeout) !== toTimeoutSeconds(news.timeout)) {
                 return { action: "update" };
             }
-            if ((olds.architecture ?? "x86_64") !== (news.architecture ?? "x86_64")) {
+            if (olds.architecture !== news.architecture) {
                 return { action: "update" };
             }
             if (olds.reservedConcurrentExecutions !==
@@ -1078,9 +1345,10 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
             const functionName = output?.functionName ??
                 (yield* createFunctionName(id, olds?.functionName));
             yield* Effect.logDebug(`reading function ${functionName}`);
-            const fn = yield* Lambda.getFunction({
+            const result = yield* Lambda.getFunction({
                 FunctionName: functionName,
-            }).pipe(Effect.map((r) => r.Configuration), Effect.catchTag("ResourceNotFoundException", () => Effect.succeed(undefined)));
+            }).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.succeed(undefined)));
+            const fn = result?.Configuration;
             if (!fn?.FunctionArn || !fn.FunctionName || !fn.Role) {
                 return undefined;
             }
@@ -1103,6 +1371,11 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
                 functionUrl,
                 roleArn: fn.Role,
                 roleName: output?.roleName ?? fn.Role.split("/").pop(),
+                code: refreshPersistedFunctionCode({
+                    output,
+                    packageType: fn.PackageType,
+                    observed: result?.Code,
+                }),
                 reservedConcurrentExecutions,
             };
             return (yield* hasAlchemyTags(id, tagsResult))
@@ -1145,6 +1418,15 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
             return rows.filter((row) => row !== undefined);
         }),
         precreate: Effect.fn(function* ({ id, news, session }) {
+            yield* validateFunctionPackageProps(id, news);
+            if (isFunctionImageProps(news)) {
+                // Resolve and validate the image before creating the execution
+                // role. External references perform only ECR reads here; local
+                // sources only hash their build inputs. A bad URI, wrong region,
+                // inaccessible image, or invalid build source therefore cannot
+                // strand an IAM role when pre-create fails before persisting state.
+                yield* functionImage.identity(id, news.image, news.architecture);
+            }
             const { accountId, region } = yield* AWSEnvironment.current;
             const { roleName, functionName, roleArn } = yield* createNames(id, news.functionName);
             const role = yield* createRoleIfNotExists({
@@ -1152,21 +1434,16 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
                 roleName,
                 vpc: news.vpc,
             });
-            // Mock code for the pre-created stub. It responds 503 (rather than a
-            // bare 200) so that, during the brief window where the real
-            // code/config update is still `InProgress`, a Function URL hit serves
-            // an honest "not ready" signal instead of a successful-but-empty 200.
-            // Downstream readiness probes already retry on non-200, so they wait
-            // for the real handler to go live without the provider blocking.
-            const code = new TextEncoder().encode(`export default () => ({ statusCode: 503, headers: { "content-type": "application/json" }, body: JSON.stringify({ error: "function initializing" }) })`);
-            const archive = yield* zipCode(code);
-            const hash = yield* hashBundle(code);
+            const prepared = yield* preparePrecreatedFunctionCode({
+                id,
+                props: news,
+                session,
+            });
             yield* createOrUpdateFunction({
                 id,
                 news,
                 roleArn: role.Role.Arn,
-                archive,
-                hash,
+                code: prepared.deployment,
                 functionName,
                 env: alchemyEnv,
                 session,
@@ -1176,13 +1453,15 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
                 functionName,
                 functionUrl: undefined,
                 roleName,
-                code: {
-                    hash,
-                },
+                code: prepared.attributes,
                 roleArn,
             };
         }),
         reconcile: Effect.fn(function* ({ id, news, olds, bindings, output, session, }) {
+            yield* validateFunctionPackageProps(id, news);
+            if (isFunctionImageProps(news)) {
+                yield* decodeFunctionImageSource(id, news.image);
+            }
             const generated = yield* createNames(id, news.functionName);
             // Prefer the deployed identifiers: regenerating would target
             // different physical resources if the generator's output for this
@@ -1276,14 +1555,17 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
                     PolicyArn: "arn:aws:iam::aws:policy/AmazonElasticFileSystemClientReadWriteAccess",
                 });
             }
-            const { identityHash, buildArchive } = yield* bundleCode(id, news);
-            const { archive, archiveHash } = yield* buildArchive;
+            const prepared = yield* prepareFunctionCode({
+                id,
+                props: news,
+                previousImage: output?.code?.image,
+                session,
+            });
             yield* createOrUpdateFunction({
                 id,
                 news,
                 roleArn,
-                archive,
-                hash: archiveHash,
+                code: prepared.deployment,
                 env: {
                     ...env,
                     ...news.env,
@@ -1301,6 +1583,18 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
                         : undefined,
                 session,
             });
+            const previousImage = output?.code.image;
+            const nextImage = "image" in prepared.attributes
+                ? prepared.attributes.image
+                : undefined;
+            if (previousImage?.ownsRepository === true &&
+                previousImage.repositoryUri !== nextImage?.repositoryUri) {
+                // The function has moved from an Alchemy-owned local image to a
+                // different source. Wait until Lambda has adopted the new digest
+                // before deleting the now-unreferenced managed repository.
+                yield* waitForFunctionUpdate(functionName, session);
+                yield* functionImage.deleteRepository(previousImage.repositoryName);
+            }
             const reservedConcurrentExecutions = yield* syncReservedConcurrentExecutions({
                 functionName,
                 reservedConcurrentExecutions: news.reservedConcurrentExecutions,
@@ -1315,7 +1609,7 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
                 oldUrl: olds?.functionUrl,
                 currentFunctionUrl: output?.functionUrl,
             });
-            yield* session.note(summary({ archive }));
+            yield* session.note(summary(prepared.deployment));
             return {
                 ...output,
                 functionArn,
@@ -1323,9 +1617,7 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
                 functionUrl: functionUrl,
                 roleName,
                 roleArn,
-                code: {
-                    hash: identityHash,
-                },
+                code: prepared.attributes,
                 reservedConcurrentExecutions,
             };
         }),
@@ -1355,6 +1647,12 @@ export const FunctionProvider = () => Provider.effect(Function, Effect.gen(funct
             yield* Lambda.deleteFunction({
                 FunctionName: output.functionName,
             }).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
+            if (output.code.image?.ownsRepository) {
+                // Lambda must release its image before the owned repository is
+                // force-deleted. Both operations are idempotent, so an interrupted
+                // destroy converges on the next run.
+                yield* functionImage.deleteRepository(output.code.image.repositoryName);
+            }
             // Release the execution role before the auxiliary CloudWatch Logs
             // reap below. A recently invoked function can keep that reap alive
             // for ~40 seconds while Lambda flushes its final log batches; if the