alchemy 2.0.0-beta.81 → 2.0.0-beta.83

package/src/AWS/Lambda/HttpServer.ts

@@ -13,27 +13,39 @@ import * as HttpServerResponse from "effect/http/HttpServerResponse";
 import * as Option from "effect/Option";
 import type { Scope } from "effect/Scope";
 import * as Http from "../../Http.ts";
+import { withInvocationDeadline } from "./InvocationDeadline.ts";
 
-export const isFunctionURLEvent = (event: any): event is LambdaFunctionURLEvent => {
-  return event.requestContext?.http?.method !== undefined;
-};
+export const isFunctionURLEvent = (event: any): event is LambdaFunctionURLEvent =>
+  event.requestContext?.http?.method !== undefined;
 
 /**
  * REST API (v1) AWS_PROXY events have a top-level `httpMethod` and a
  * `requestContext.resourcePath` field. They lack the `requestContext.http.*`
  * shape of Function URL / HTTP API (v2) events.
  */
-export const isApiGatewayProxyEvent = (event: any): event is APIGatewayProxyEvent => {
-  return typeof event?.httpMethod === "string" && event?.requestContext?.resourcePath !== undefined;
-};
+export const isApiGatewayProxyEvent = (event: any): event is APIGatewayProxyEvent =>
+  typeof event?.httpMethod === "string" && event?.requestContext?.resourcePath !== undefined;
 
 /**
  * Application Load Balancer target events carry a `requestContext.elb` marker
  * (the target group ARN) and a top-level `httpMethod` + `path`.
  */
-export const isAlbEvent = (event: any): event is ALBEvent => {
-  return typeof event?.httpMethod === "string" && event?.requestContext?.elb !== undefined;
-};
+export const isAlbEvent = (event: any): event is ALBEvent =>
+  typeof event?.httpMethod === "string" && event?.requestContext?.elb !== undefined;
+
+// `HttpMiddleware.tracer` records the request on the `http.server` span only
+// when the request finishes. A span the deadline flush ends early would ship
+// without it, so record the method and path up front.
+const annotateRequestSpan = <A, E, R>(self: Effect.Effect<A, E, R>) =>
+  Effect.gen(function* () {
+    const request = yield* HttpServerRequest.HttpServerRequest;
+    const span = yield* Effect.option(Effect.currentSpan);
+    if (Option.isSome(span)) {
+      span.value.attribute("http.request.method", request.method);
+      span.value.attribute("url.path", new URL(request.url, "http://localhost").pathname);
+    }
+    return yield* self;
+  });
 
 export const makeFunctionHttpHandler = <Req>(handler: Http.HttpEffect<Req>) => {
   // `HttpMiddleware.tracer` creates the `http.server` root span per request
@@ -41,7 +53,18 @@ export const makeFunctionHttpHandler = <Req>(handler: Http.HttpEffect<Req>) => {
   // fetch path. With the default no-op tracer this is free; with a telemetry
   // exporter installed the span is exported when the invocation scope
   // flushes.
-  const safeHandler = HttpMiddleware.tracer(Http.safeHttpEffect(handler));
+  //
+  // The invocation deadline flush sits INSIDE the span so it can find the
+  // `http.server` root span in context and end it — with
+  // `InvocationTimeoutError` as its status — before draining the exporters.
+  // The dispatcher's outer guard stands down when this one takes the
+  // deadline; see `withInvocationDeadline`.
+  const safeHandler = handler.pipe(
+    Http.safeHttpEffect,
+    withInvocationDeadline,
+    annotateRequestSpan,
+    HttpMiddleware.tracer,
+  );
   return (
     event: any,
   ):
@@ -57,6 +80,7 @@ export const makeFunctionHttpHandler = <Req>(handler: Http.HttpEffect<Req>) => {
         url: webRequest.url,
         remoteAddress: Option.some(event.requestContext.http.sourceIp),
       });
+      // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- safeHandler handles failures; generic Exclude on R can't be proven statically
       return safeHandler.pipe(
         Effect.provideService(HttpServerRequest.HttpServerRequest, request),
         Effect.flatMap(toLambdaFunctionURLResult),
@@ -71,6 +95,7 @@ export const makeFunctionHttpHandler = <Req>(handler: Http.HttpEffect<Req>) => {
       const request = HttpServerRequest.fromWeb(webRequest).modify({
         url: webRequest.url,
       });
+      // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- safeHandler handles failures; generic Exclude on R can't be proven statically
       return safeHandler.pipe(
         Effect.provideService(HttpServerRequest.HttpServerRequest, request),
         // The ALB result shape is the API Gateway v1 result shape (statusCode,
@@ -90,6 +115,7 @@ export const makeFunctionHttpHandler = <Req>(handler: Http.HttpEffect<Req>) => {
         url: webRequest.url,
         remoteAddress: Option.fromNullishOr(event.requestContext?.identity?.sourceIp),
       });
+      // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- safeHandler handles failures; generic Exclude on R can't be proven statically
       return safeHandler.pipe(
         Effect.provideService(HttpServerRequest.HttpServerRequest, request),
         Effect.flatMap(toApiGatewayProxyResult),

package/src/AWS/Lambda/InvocationDeadline.ts

@@ -0,0 +1,240 @@
+import type * as lambda from "aws-lambda";
+import * as Clock from "effect/Clock";
+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";
+import * as Fiber from "effect/Fiber";
+import { Flusher } from "effect/observability/OtlpExporter";
+import * as Option from "effect/Option";
+
+/**
+ * The AWS Lambda invocation context — the `context` argument Lambda passes
+ * to the handler. Provided to every invocation's effect by the Lambda
+ * dispatcher (see `Function.ts`).
+ */
+export class HandlerContext extends Context.Service<HandlerContext, lambda.Context>()(
+  "AWS.Lambda.HandlerContext",
+) {}
+
+/**
+ * Environment variable the deploy side writes from
+ * {@link FunctionCommonProps.timeoutMargin} and the runtime reads per
+ * invocation. Whole milliseconds; `0` disables the deadline flush.
+ */
+export const TIMEOUT_MARGIN_ENV = "ALCHEMY_LAMBDA_TIMEOUT_MARGIN_MS";
+
+/**
+ * Default deadline margin. Wide enough for one OTLP export round-trip to a
+ * remote collector (dd-trace uses 100 ms, but it flushes to a local
+ * extension over localhost).
+ */
+export const DEFAULT_TIMEOUT_MARGIN_MS = 500;
+
+/**
+ * Span attribute set on a root span the deadline flush ended early. Lets a
+ * backend tell "flushed because the invocation was about to time out" from
+ * a handler-reported failure — and, when the handler does finish inside the
+ * margin and re-ends the span successfully, explains the earlier export.
+ */
+export const TIMEOUT_IMMINENT_ATTRIBUTE = "aws.lambda.timeout.imminent";
+
+/**
+ * Recorded on the invocation's root span when the deadline flush fires:
+ * the handler was still running `marginMs` before the function's timeout.
+ *
+ * This is never thrown and never fails the invocation. The handler keeps
+ * running; the error is the span's exit status so the trace of an
+ * invocation Lambda is about to kill exports as an errored span instead
+ * of vanishing. If the handler does finish inside the margin, the span
+ * keeps this status (see {@link withInvocationDeadline}).
+ */
+export class InvocationTimeoutError extends Data.TaggedError("AWS.Lambda.InvocationTimeoutError")<{
+  readonly functionName: string;
+  readonly requestId: string;
+  /** Milliseconds the handler had been running when the flush fired. */
+  readonly budgetMs: number;
+  /** Milliseconds reserved before Lambda's hard timeout. */
+  readonly marginMs: number;
+}> {
+  override get message() {
+    return `Lambda invocation ${this.requestId} of ${this.functionName} was still running after ${this.budgetMs}ms, ${this.marginMs}ms before its timeout; telemetry was flushed early in case Lambda kills the invocation`;
+  }
+}
+
+interface Deadline {
+  /** Tell the enclosing guard an inner guard now owns the deadline. */
+  readonly claim: () => void;
+}
+
+/**
+ * Internal handshake between nested deadline guards. The dispatcher guards
+ * every listener; the HTTP listener guards again *inside* its `http.server`
+ * span so the flush can end that span. The inner guard claims the deadline
+ * and the outer one stands down, so the flush runs exactly once, from the
+ * innermost guard.
+ */
+class InvocationDeadline extends Context.Service<InvocationDeadline, Deadline>()(
+  "AWS.Lambda.InvocationDeadline",
+) {}
+
+/**
+ * Parse the runtime margin from its environment variable. Unset → default;
+ * unparseable/negative → default; `0` → flush disabled.
+ */
+export const readTimeoutMargin = (raw: string | undefined): number => {
+  if (raw === undefined || raw === "") return DEFAULT_TIMEOUT_MARGIN_MS;
+  const ms = Number(raw);
+  return Number.isFinite(ms) && ms >= 0 ? Math.floor(ms) : DEFAULT_TIMEOUT_MARGIN_MS;
+};
+
+/**
+ * Normalize a {@link FunctionCommonProps.timeoutMargin} to whole
+ * milliseconds for the env var. Handles the state-JSON `Duration` shape the
+ * same way `toTimeoutSeconds` does. Infinite → `undefined` (default).
+ */
+export const toTimeoutMarginMillis = (
+  margin: Duration.Duration | undefined,
+): number | undefined => {
+  if (margin === undefined) return undefined;
+  const json = margin as {
+    _id?: unknown;
+    _tag?: "Millis" | "Nanos" | "Infinity" | "NegativeInfinity";
+    millis?: number;
+    nanos?: string;
+  };
+  const input: Duration.Input =
+    json._id === "Duration"
+      ? json._tag === "Millis"
+        ? json.millis!
+        : json._tag === "Nanos"
+          ? BigInt(json.nanos!)
+          : "Infinity"
+      : margin;
+  const millis = Duration.toMillis(input);
+  return Number.isFinite(millis) ? Math.max(0, Math.ceil(millis)) : undefined;
+};
+
+/**
+ * Flush telemetry for an invocation that is still running `margin` before
+ * Lambda's hard timeout — without touching the handler.
+ *
+ * A Lambda that hits its timeout is killed mid-flight: the telemetry
+ * exporter's buffer and the still-open root span die with it — precisely
+ * the invocation you most want a trace for. The deadline is known up front
+ * (`context.getRemainingTimeInMillis()`), and a sandbox only ever handles
+ * one invocation at a time, so a pre-deadline timer is race-free. It parks
+ * for `remaining - margin` and, if the handler is still running by then:
+ *
+ * 1. ends the current span (the `http.server` root span on the HTTP path)
+ *    with {@link InvocationTimeoutError} and marks it
+ *    {@link TIMEOUT_IMMINENT_ATTRIBUTE};
+ * 2. logs a warning through the invocation's logger, so the log record
+ *    carries the trace id;
+ * 3. drains every exporter through the OTLP {@link Flusher}.
+ *
+ * The handler is never interrupted and the invocation's outcome is never
+ * changed. If Lambda kills the invocation, the trace already exists. The
+ * root span is exported exactly once: if the handler finishes inside the
+ * margin, its response goes out as normal but the span keeps the
+ * timeout-imminent status — it did nearly time out. Spans still open at the
+ * flush (other than the root) are not exported; anything already ended,
+ * and every log record, is.
+ *
+ * The margin comes from `ALCHEMY_LAMBDA_TIMEOUT_MARGIN_MS`
+ * ({@link FunctionCommonProps.timeoutMargin} on the deploy side; default
+ * {@link DEFAULT_TIMEOUT_MARGIN_MS}); `0` disables it. Without a
+ * `HandlerContext` (unit tests, non-Lambda hosts) the effect runs
+ * unguarded.
+ *
+ * Guards nest: an inner guard (the HTTP listener's, placed inside the
+ * `http.server` span so the flush can end it) takes the deadline over from
+ * the outer one (the dispatcher's), so the flush runs once, from the
+ * innermost guard, closest to the work.
+ */
+export const withInvocationDeadline = <A, E, R>(
+  self: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R> =>
+  Effect.gen(function* () {
+    const context = Option.getOrUndefined(yield* Effect.serviceOption(HandlerContext));
+    if (context === undefined || typeof context.getRemainingTimeInMillis !== "function") {
+      return yield* self;
+    }
+    const marginMs = readTimeoutMargin(process.env[TIMEOUT_MARGIN_ENV]);
+    if (marginMs <= 0) {
+      return yield* self;
+    }
+    const remainingMs = context.getRemainingTimeInMillis();
+    const budgetMs = remainingMs - marginMs;
+    if (!(budgetMs > 0)) {
+      // A margin at or above the function's timeout would flush at t=0 on
+      // every invocation. Run unguarded and say why.
+      yield* Effect.logWarning(
+        `${TIMEOUT_MARGIN_ENV}=${marginMs} leaves no invocation budget (${remainingMs}ms remaining); the invocation deadline flush is disabled`,
+      );
+      return yield* self;
+    }
+
+    // Take the deadline over from any enclosing guard.
+    const outer = yield* Effect.serviceOption(InvocationDeadline);
+    if (Option.isSome(outer)) {
+      outer.value.claim();
+    }
+    let claimed = false;
+    const deadline: Deadline = {
+      claim: () => {
+        claimed = true;
+      },
+    };
+
+    const flushBeforeDeadline = Effect.gen(function* () {
+      const error = new InvocationTimeoutError({
+        functionName: context.functionName,
+        requestId: context.awsRequestId,
+        budgetMs,
+        marginMs,
+      });
+      // The root span is still open (that is why we are here); end it so
+      // it exports with the timeout as its status. Only `Span`s can be
+      // ended — an external parent (a propagated `traceparent` with no
+      // local span) is skipped.
+      const span = yield* Effect.option(Effect.currentSpan);
+      if (Option.isSome(span) && span.value.status._tag === "Started") {
+        const root = span.value;
+        root.attribute(TIMEOUT_IMMINENT_ATTRIBUTE, true);
+        root.end(yield* Clock.currentTimeNanos, Exit.fail(error));
+        // This export is the span's final record. Tracers export on every
+        // `end`, so if the handler finishes inside the margin the tracer's
+        // own `end` would ship the span a second time; drop it.
+        root.end = () => {};
+      }
+      yield* Effect.logWarning(error.message).pipe(
+        Effect.annotateLogs({
+          requestId: error.requestId,
+          budgetMs: error.budgetMs,
+          marginMs: error.marginMs,
+        }),
+      );
+      const flusher = yield* Effect.serviceOption(Flusher);
+      if (Option.isSome(flusher)) {
+        yield* flusher.value.flush;
+      }
+    });
+
+    // The watcher inherits this fiber's context — the invocation's logger,
+    // exporters and (on the HTTP path) the root span — and is interrupted
+    // when the handler settles. The flush itself is uninterruptible so a
+    // handler finishing mid-flush waits for the export rather than
+    // abandoning an in-flight batch.
+    const watcher = yield* Effect.sleep(Duration.millis(budgetMs)).pipe(
+      Effect.andThen(
+        Effect.suspend(() => (claimed ? Effect.void : Effect.uninterruptible(flushBeforeDeadline))),
+      ),
+      Effect.forkChild,
+    );
+    return yield* self.pipe(
+      Effect.provideService(InvocationDeadline, deadline),
+      Effect.ensuring(Fiber.interrupt(watcher)),
+    );
+  });

package/src/AWS/Lambda/MicrovmProvider.ts

@@ -225,7 +225,7 @@ const artifactContent = (
         const dockerfilePath = path.join(news.context, dockerfileName);
         const content = yield* fs
           .readFile(dockerfilePath)
-          .pipe(Effect.catch(() => Effect.succeed(undefined)));
+          .pipe(Effect.orElseSucceed(() => undefined));
         if (content) files.push({ path: "Dockerfile", content });
       }
       // Hash the BYTES, not `path:byteLength` — a same-length edit (a
@@ -559,7 +559,7 @@ const buildFailureReason = Effect.fn(function* (
   if (!imageVersion) return undefined;
   const version = yield* microvms
     .getMicrovmImageVersion({ imageIdentifier: imageArn, imageVersion })
-    .pipe(Effect.catch(() => Effect.succeed(undefined)));
+    .pipe(Effect.orElseSucceed(() => undefined));
   // A version fans out to one build per architecture/chipset; report the reason
   // from each build that actually FAILED (keyed by architecture so multi-platform
   // failures are distinguishable). `buildState` is the reliable signal — don't
@@ -569,7 +569,7 @@ const buildFailureReason = Effect.fn(function* (
     .pipe(
       Stream.runCollect,
       Effect.map((chunk) => Array.from(chunk)),
-      Effect.catch(() => Effect.succeed([] as microvms.MicrovmImageBuildSummary[])),
+      Effect.orElseSucceed(() => [] as microvms.MicrovmImageBuildSummary[]),
     );
   const failedBuildReasons = builds
     .filter((b) => b.buildState === "FAILED" && b.stateReason)

package/src/AWS/Lambda/MicrovmRuntimeContext.ts

@@ -30,7 +30,7 @@ export const makeMicrovmRuntimeContext = (id: string): Server.ProcessContext =>
           );
           if (httpServer) {
             yield* httpServer.serve(finalHandler);
-            yield* Effect.never;
+            return yield* Effect.never;
           }
         }).pipe(Effect.orDie),
       );

package/src/AWS/Lambda/Version.ts

@@ -411,7 +411,11 @@ export const VersionProvider = () =>
               : Unowned(attrs);
           }
 
-          const functionName = olds ? resolvedProps(olds).function.functionName : undefined;
+          // An interrupted create's first checkpoint strips the Function
+          // reference while the Function is still being created (see
+          // stripUnresolved), so `olds.function` can be missing. With no
+          // function name there is no version to recover.
+          const functionName = olds ? resolvedProps(olds).function?.functionName : undefined;
           if (!functionName) return undefined;
           const latest = yield* waitForLatest(functionName);
           const complete = yield* completeConfiguration(functionName, latest);

package/src/AWS/Lambda/index.ts

@@ -30,6 +30,7 @@ export * from "./GetMicrovmImageHttp.ts";
 export * from "./GetMicrovmImageVersion.ts";
 export * from "./GetMicrovmImageVersionHttp.ts";
 export * from "./HttpServer.ts";
+export * from "./InvocationDeadline.ts";
 export * from "./InvokeFunction.ts";
 export * from "./InvokeFunctionHttp.ts";
 export * from "./InvokeWithResponseStream.ts";

package/src/AWS/LexV2/BotAlias.ts

@@ -198,12 +198,10 @@ const resolveCodeHooks = Effect.fn(function* (
     for (const [localeId, arn] of Object.entries(hooks)) {
       const existing = merged[localeId];
       if (existing !== undefined && existing !== arn) {
-        return yield* Effect.fail(
-          new ConflictingCodeHook({
-            localeId,
-            functionArns: [existing, arn],
-          }),
-        );
+        return yield* new ConflictingCodeHook({
+          localeId,
+          functionArns: [existing, arn],
+        });
       }
       merged[localeId] = arn;
     }

package/src/AWS/LexV2/internal.ts

@@ -79,13 +79,11 @@ export const waitForBotSettled = Effect.fn("AWS.LexV2.waitForBotSettled")(functi
     (b) => !transientBotStatuses.has(b.botStatus ?? ""),
   );
   if (bot.botStatus === "Failed" || transientBotStatuses.has(bot.botStatus ?? "")) {
-    return yield* Effect.fail(
-      new LexOperationFailed({
-        resourceId: botId,
-        status: bot.botStatus ?? "unknown",
-        reasons: bot.failureReasons ?? [],
-      }),
-    );
+    return yield* new LexOperationFailed({
+      resourceId: botId,
+      status: bot.botStatus ?? "unknown",
+      reasons: bot.failureReasons ?? [],
+    });
   }
   return bot;
 });
@@ -109,13 +107,11 @@ export const waitForLocaleSettled = Effect.fn("AWS.LexV2.waitForLocaleSettled")(
     locale.botLocaleStatus === "Failed" ||
     transientLocaleStatuses.has(locale.botLocaleStatus ?? "")
   ) {
-    return yield* Effect.fail(
-      new LexOperationFailed({
-        resourceId: `${botId}/${localeId}`,
-        status: locale.botLocaleStatus ?? "unknown",
-        reasons: locale.failureReasons ?? [],
-      }),
-    );
+    return yield* new LexOperationFailed({
+      resourceId: `${botId}/${localeId}`,
+      status: locale.botLocaleStatus ?? "unknown",
+      reasons: locale.failureReasons ?? [],
+    });
   }
   return locale;
 });
@@ -136,13 +132,11 @@ export const waitForLocaleBuilt = Effect.fn("AWS.LexV2.waitForLocaleBuilt")(func
     { intervalSeconds: 5, times: 18 },
   );
   if (locale.botLocaleStatus !== "Built") {
-    return yield* Effect.fail(
-      new LexOperationFailed({
-        resourceId: `${botId}/${localeId}`,
-        status: locale.botLocaleStatus ?? "unknown",
-        reasons: locale.failureReasons ?? [],
-      }),
-    );
+    return yield* new LexOperationFailed({
+      resourceId: `${botId}/${localeId}`,
+      status: locale.botLocaleStatus ?? "unknown",
+      reasons: locale.failureReasons ?? [],
+    });
   }
   return locale;
 });
@@ -160,13 +154,11 @@ export const waitForAliasSettled = Effect.fn("AWS.LexV2.waitForAliasSettled")(fu
     (a) => a.botAliasStatus !== "Creating",
   );
   if (alias.botAliasStatus === "Failed" || alias.botAliasStatus === "Creating") {
-    return yield* Effect.fail(
-      new LexOperationFailed({
-        resourceId: `${botId}/${botAliasId}`,
-        status: alias.botAliasStatus ?? "unknown",
-        reasons: [],
-      }),
-    );
+    return yield* new LexOperationFailed({
+      resourceId: `${botId}/${botAliasId}`,
+      status: alias.botAliasStatus ?? "unknown",
+      reasons: [],
+    });
   }
   return alias;
 });
@@ -178,7 +170,7 @@ export const waitForAliasSettled = Effect.fn("AWS.LexV2.waitForAliasSettled")(fu
 export const readLexTags = Effect.fn("AWS.LexV2.readLexTags")(function* (arn: string) {
   const response = yield* lexm
     .listTagsForResource({ resourceARN: arn })
-    .pipe(Effect.catch(() => Effect.succeed(undefined)));
+    .pipe(Effect.orElseSucceed(() => undefined));
   return toTagRecord(response?.tags);
 });
 

package/src/AWS/Logs/LogGroup.ts

@@ -338,7 +338,7 @@ export const LogGroupProvider = () =>
                 ),
               ),
             ),
-            Effect.catch(() => Effect.succeed({} as Record<string, string>)),
+            Effect.orElseSucceed(() => ({}) as Record<string, string>),
           );
           const { removed, upsert } = diffTags(observedTags, desiredTags);
           if (upsert.length > 0) {
@@ -410,7 +410,7 @@ export const LogGroupProvider = () =>
             },
           );
           if (remaining) {
-            yield* Effect.die(
+            return yield* Effect.die(
               new Error(
                 `CloudWatch log group ${output.logGroupName} remained observable after delete`,
               ),

package/src/AWS/Logs/LogRetention.ts

@@ -0,0 +1,51 @@
+import * as logs from "@distilled.cloud/aws/cloudwatch-logs";
+import type * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import { toSeconds } from "../../Util/Duration.ts";
+
+/** Retention policy for a CloudWatch log group an Alchemy resource writes to. */
+export interface LogRetentionConfig {
+  /**
+   * How long to retain logs, e.g. `"2 weeks"`, or `"forever"` to clear the
+   * retention policy. Rounded up to the nearest CloudWatch-supported
+   * retention. When omitted the log group's existing retention is left
+   * untouched (new log groups default to never-expire).
+   */
+  retention?: Duration.Input | "forever";
+}
+
+/** CloudWatch Logs' allowed retention values, in days, ascending. */
+const LOG_RETENTION_DAYS = [
+  1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288,
+  3653,
+];
+
+/**
+ * Apply a {@link LogRetentionConfig.retention} to an existing log group:
+ * round the duration UP to the nearest CloudWatch-supported retention, or
+ * clear the policy for `"forever"`. Leaves the group untouched when unset.
+ */
+export const syncLogGroupRetention = Effect.fn(function* ({
+  logGroupName,
+  retention,
+}: {
+  logGroupName: string;
+  retention: Duration.Input | "forever" | undefined;
+}) {
+  if (retention === undefined) {
+    return;
+  }
+  if (retention === "forever") {
+    yield* logs
+      .deleteRetentionPolicy({ logGroupName })
+      .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
+    return;
+  }
+  const days = Math.max(1, Math.ceil((toSeconds(retention) ?? 0) / 86_400));
+  yield* logs.putRetentionPolicy({
+    logGroupName,
+    retentionInDays:
+      LOG_RETENTION_DAYS.find((allowed) => allowed >= days) ??
+      LOG_RETENTION_DAYS[LOG_RETENTION_DAYS.length - 1]!,
+  });
+});

package/src/AWS/Logs/LogStream.ts

@@ -185,7 +185,7 @@ export const LogStreamProvider = () =>
             },
           );
           if (remaining !== undefined) {
-            yield* Effect.die(
+            return yield* Effect.die(
               new Error(
                 `CloudWatch log stream ${output.logGroupName}:${output.logStreamName} remained observable after delete`,
               ),

package/src/AWS/Logs/reapLogGroups.ts

@@ -0,0 +1,50 @@
+import * as logs from "@distilled.cloud/aws/cloudwatch-logs";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
+
+/**
+ * Delete every CloudWatch log group whose name starts with `prefix`.
+ *
+ * For resources whose SERVICE (not alchemy) creates per-resource log groups
+ * on their behalf — RDS log exports (`/aws/rds/instance/<id>/<type>`),
+ * CloudHSM audit logs (`/aws/cloudhsm/<clusterId>`) — and leaves them behind
+ * when the resource is deleted. The owning provider calls this after the
+ * resource is gone so the groups don't leak (cf. Lambda's `/aws/lambda/<fn>`
+ * reap in `Lambda/Function.ts`).
+ *
+ * Callers must pass a prefix that is unique to the resource (end it with `/`
+ * when the id is a path segment) so a sibling's groups are never matched.
+ *
+ * Best-effort and bounded: log cleanup is auxiliary to the already-completed
+ * resource delete, so a missing group is success and any other failure or a
+ * slow API only logs a warning.
+ *
+ * Internal scaffolding — NOT exported from the Logs service `index.ts`.
+ */
+export const reapLogGroupsByPrefix = (prefix: string) =>
+  logs.describeLogGroups.pages({ logGroupNamePrefix: prefix }).pipe(
+    Stream.flatMap((page) => Stream.fromIterable(page.logGroups ?? [])),
+    Stream.mapEffect(
+      (group) =>
+        group.logGroupName === undefined
+          ? Effect.void
+          : logs.deleteLogGroup({ logGroupName: group.logGroupName }).pipe(
+              Effect.retry({
+                while: (e) =>
+                  e._tag === "OperationAbortedException" ||
+                  e._tag === "ServiceUnavailableException",
+                schedule: Schedule.exponential("250 millis"),
+                times: 6,
+              }),
+              Effect.catchTag("ResourceNotFoundException", () => Effect.void),
+            ),
+      { concurrency: 4 },
+    ),
+    Stream.runDrain,
+    Effect.timeoutOrElse({
+      duration: "30 seconds",
+      orElse: () => Effect.logWarning(`Timed out reaping log groups ${prefix}*`),
+    }),
+    Effect.catch((e) => Effect.logWarning(`Failed to reap log groups ${prefix}*: ${e._tag}`)),
+  );