alchemy 2.0.0-beta.4 → 2.0.0-beta.40

package/src/AWS/Providers.ts

@@ -1,10 +1,29 @@
+import {
+  isRetryable,
+  isThrottlingError,
+  isTransientError,
+} from "@distilled.cloud/aws/Category";
+import {
+  capped,
+  jittered,
+  Retry,
+  type Factory as RetryFactory,
+} from "@distilled.cloud/aws/Retry";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import { pipe } from "effect/Function";
 import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
+import * as Schedule from "effect/Schedule";
+import * as HttpClientError from "effect/unstable/http/HttpClientError";
+import { CredentialsStoreLive } from "../Auth/Credentials.ts";
 import { Command, CommandProvider } from "../Build/Command.ts";
 import * as Provider from "../Provider.ts";
 import { Random, RandomProvider } from "../Random.ts";
-import * as Account from "./Account.ts";
 import * as ACM from "./ACM/index.ts";
+import * as ApiGateway from "./ApiGateway/index.ts";
 import * as Assets from "./Assets.ts";
+import { AwsAuth } from "./AuthProvider.ts";
 import * as AutoScaling from "./AutoScaling/index.ts";
 import * as CloudFront from "./CloudFront/index.ts";
 import * as CloudWatch from "./CloudWatch/index.ts";
@@ -16,6 +35,7 @@ import * as ECS from "./ECS/index.ts";
 import * as EKS from "./EKS/index.ts";
 import * as ELBv2 from "./ELBv2/index.ts";
 import * as Endpoint from "./Endpoint.ts";
+import { Default as DefaultEnvironment } from "./Environment.ts";
 import * as EventBridge from "./EventBridge/index.ts";
 import * as IAM from "./IAM/index.ts";
 import * as IdentityCenter from "./IdentityCenter/index.ts";
@@ -32,7 +52,6 @@ import * as Scheduler from "./Scheduler/index.ts";
 import * as SecretsManager from "./SecretsManager/index.ts";
 import * as SNS from "./SNS/index.ts";
 import * as SQS from "./SQS/index.ts";
-import { DefaultStageConfig } from "./StageConfig.ts";
 import * as Website from "./Website/index.ts";
 
 export class Providers extends Provider.ProviderCollection<Providers>()(
@@ -46,16 +65,35 @@ export const providers = () =>
       Command,
       Random,
       ACM.Certificate,
+      ApiGateway.Account,
+      ApiGateway.ApiKey,
+      ApiGateway.Authorizer,
+      ApiGateway.BasePathMapping,
+      ApiGateway.DeploymentResource,
+      ApiGateway.DomainName,
+      ApiGateway.GatewayResponse,
+      ApiGateway.MethodResource,
+      ApiGateway.GatewayResource,
+      ApiGateway.RestApi,
+      ApiGateway.StageResource,
+      ApiGateway.UsagePlan,
+      ApiGateway.UsagePlanKey,
+      ApiGateway.VpcLink,
       AutoScaling.AutoScalingGroup,
       AutoScaling.LaunchTemplate,
       AutoScaling.ScalingPolicy,
+      CloudFront.CachePolicy,
       CloudFront.Distribution,
       CloudFront.Function,
       CloudFront.Invalidation,
+      CloudFront.KeyGroup,
       CloudFront.KeyValueStore,
       CloudFront.KvEntries,
       CloudFront.KvRoutesUpdate,
       CloudFront.OriginAccessControl,
+      CloudFront.OriginRequestPolicy,
+      CloudFront.PublicKey,
+      CloudFront.ResponseHeadersPolicy,
       CloudWatch.Alarm,
       CloudWatch.AlarmMuteRule,
       CloudWatch.AnomalyDetector,
@@ -124,6 +162,7 @@ export const providers = () =>
       EC2.Vpc,
       EC2.VpcEndpoint,
       ECR.Repository,
+      ECS.CapacityProvider,
       ECS.Cluster,
       ECS.DescribeTasksPolicy,
       ECS.ListTasksPolicy,
@@ -279,16 +318,35 @@ export const providers = () =>
     Layer.provide(
       Layer.mergeAll(
         ACM.CertificateProvider(),
+        ApiGateway.AccountProvider(),
+        ApiGateway.ApiKeyProvider(),
+        ApiGateway.AuthorizerProvider(),
+        ApiGateway.BasePathMappingProvider(),
+        ApiGateway.DeploymentProvider(),
+        ApiGateway.DomainNameProvider(),
+        ApiGateway.GatewayResponseProvider(),
+        ApiGateway.MethodProvider(),
+        ApiGateway.ResourceProvider(),
+        ApiGateway.RestApiProvider(),
+        ApiGateway.StageProvider(),
+        ApiGateway.UsagePlanProvider(),
+        ApiGateway.UsagePlanKeyProvider(),
+        ApiGateway.VpcLinkProvider(),
         AutoScaling.AutoScalingGroupProvider(),
         AutoScaling.LaunchTemplateProvider(),
         AutoScaling.ScalingPolicyProvider(),
+        CloudFront.CachePolicyProvider(),
         CloudFront.DistributionProvider(),
         CloudFront.FunctionProvider(),
         CloudFront.InvalidationProvider(),
+        CloudFront.KeyGroupProvider(),
         CloudFront.KeyValueStoreProvider(),
         CloudFront.KvEntriesProvider(),
         CloudFront.KvRoutesUpdateProvider(),
         CloudFront.OriginAccessControlProvider(),
+        CloudFront.OriginRequestPolicyProvider(),
+        CloudFront.PublicKeyProvider(),
+        CloudFront.ResponseHeadersPolicyProvider(),
         CloudWatch.AlarmMuteRuleProvider(),
         CloudWatch.AlarmProvider(),
         CloudWatch.AnomalyDetectorProvider(),
@@ -357,6 +415,7 @@ export const providers = () =>
         EC2.VpcEndpointProvider(),
         EC2.VpcProvider(),
         ECR.RepositoryProvider(),
+        ECS.CapacityProviderProvider(),
         ECS.ClusterProvider(),
         ECS.DescribeTasksPolicyLive,
         ECS.ListTasksPolicyLive,
@@ -516,10 +575,60 @@ export const providers = () =>
         Assets.AssetsProvider(),
       ),
     ),
-    Layer.provideMerge(Account.fromStageConfig()),
-    Layer.provideMerge(Region.fromStageConfig()),
-    Layer.provideMerge(Credentials.fromStageConfig()),
-    Layer.provideMerge(Endpoint.fromStageConfig()),
-    Layer.provideMerge(DefaultStageConfig),
+    Layer.provideMerge(Region.fromEnvironment),
+    Layer.provideMerge(Credentials.fromEnvironment),
+    Layer.provideMerge(Endpoint.fromEnvironment),
+    Layer.provideMerge(DefaultEnvironment),
+    Layer.provideMerge(AwsAuth),
+    Layer.provideMerge(CredentialsStoreLive),
+    // Apply a blanket retry policy to every AWS SDK call. Like distilled's
+    // `makeDefault` it retries throttling, 5xx, and Smithy `@retryable`
+    // errors with exponential backoff + jitter + `RetryAfter` header
+    // awareness, but with a higher attempt cap (10 vs 5) so heavy
+    // parallel deploys ride out S3 `SlowDown` bursts that span more than
+    // a few seconds. Bounded so real rate-limit pressure still surfaces
+    // instead of masking as an indefinite hang.
+    Layer.provideMerge(Layer.succeed(Retry, awsRetryFactory)),
     Layer.orDie,
   );
+
+// TODO(sam): remove this once it's upstreamed to distilled
+const isHttpTransportError = (error: unknown): boolean => {
+  if (!HttpClientError.isHttpClientError(error)) return false;
+  const tag = error.reason._tag;
+  if (tag === "TransportError") return true;
+  if (
+    tag === "StatusCodeError" &&
+    "response" in error.reason &&
+    error.reason.response.status >= 500
+  ) {
+    return true;
+  }
+  return false;
+};
+
+const awsRetryFactory: RetryFactory = (lastError) => ({
+  while: (error) =>
+    isTransientError(error) ||
+    isThrottlingError(error) ||
+    isRetryable(error) ||
+    isHttpTransportError(error),
+  schedule: pipe(
+    Schedule.exponential(Duration.millis(200), 2),
+    Schedule.modifyDelay(
+      Effect.fnUntraced(function* (duration) {
+        const error = yield* Ref.get(lastError);
+        if (isThrottlingError(error)) {
+          // Throttling: floor at 500ms (matches distilled default).
+          if (Duration.toMillis(duration) < 500) {
+            return Duration.toMillis(Duration.millis(500));
+          }
+        }
+        return Duration.toMillis(duration);
+      }),
+    ),
+    capped(Duration.seconds(5)),
+    jittered,
+    Schedule.both(Schedule.recurs(10)),
+  ),
+});

package/src/AWS/RDS/DBCluster.ts

@@ -264,94 +264,102 @@ export const DBClusterProvider = () =>
             tags: toTagRecord(cluster.TagList),
           });
         }),
-        create: Effect.fn(function* ({ id, news, session }) {
-          const identifier = yield* toIdentifier(id, news);
-          const tags = {
-            ...(yield* createInternalTags(id)),
-            ...news.tags,
-          };
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const identifier =
+            output?.dbClusterIdentifier ?? (yield* toIdentifier(id, news));
+          const internalTags = yield* createInternalTags(id);
+          const desiredTags = { ...internalTags, ...news.tags };
           const credentials = yield* resolveMasterCredentials(news);
 
-          yield* rds
-            .createDBCluster({
+          // Observe — fetch live cluster state. We never trust `output`
+          // blindly: the cluster may have been deleted out-of-band, or this
+          // may be a first-time reconcile after adoption.
+          let observed = yield* readCluster(identifier);
+
+          // Ensure — create the cluster if it's missing. Tolerate
+          // `DBClusterAlreadyExistsFault` as a race with a peer reconciler
+          // (e.g. retry after state-persistence failure).
+          if (!observed?.DBClusterArn) {
+            yield* rds
+              .createDBCluster({
+                DBClusterIdentifier: identifier,
+                Engine: news.engine,
+                EngineVersion: news.engineVersion,
+                DatabaseName: news.databaseName,
+                DBSubnetGroupName: news.dbSubnetGroupName,
+                DBClusterParameterGroupName: news.dbClusterParameterGroupName,
+                VpcSecurityGroupIds: news.vpcSecurityGroupIds,
+                Port: news.port,
+                EnableIAMDatabaseAuthentication:
+                  news.enableIAMDatabaseAuthentication,
+                EnableHttpEndpoint: news.enableHttpEndpoint,
+                EngineMode: news.engineMode,
+                ServerlessV2ScalingConfiguration:
+                  news.serverlessV2ScalingConfiguration,
+                CopyTagsToSnapshot: news.copyTagsToSnapshot,
+                DeletionProtection: news.deletionProtection,
+                StorageEncrypted: news.storageEncrypted,
+                KmsKeyId: news.kmsKeyId,
+                ManageMasterUserPassword: news.manageMasterUserPassword,
+                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
+                  Key,
+                  Value,
+                })),
+                ...credentials,
+              })
+              .pipe(
+                Effect.catchTag(
+                  "DBClusterAlreadyExistsFault",
+                  () => Effect.void,
+                ),
+              );
+
+            observed = yield* waitForCluster(identifier);
+          } else {
+            // Sync mutable cluster config — push the desired shape via
+            // `modifyDBCluster`. Many fields land in `PendingModifiedValues`
+            // and apply on next reboot; `ApplyImmediately` shortens that.
+            yield* rds.modifyDBCluster({
               DBClusterIdentifier: identifier,
-              Engine: news.engine,
               EngineVersion: news.engineVersion,
-              DatabaseName: news.databaseName,
-              DBSubnetGroupName: news.dbSubnetGroupName,
               DBClusterParameterGroupName: news.dbClusterParameterGroupName,
               VpcSecurityGroupIds: news.vpcSecurityGroupIds,
               Port: news.port,
               EnableIAMDatabaseAuthentication:
                 news.enableIAMDatabaseAuthentication,
               EnableHttpEndpoint: news.enableHttpEndpoint,
-              EngineMode: news.engineMode,
               ServerlessV2ScalingConfiguration:
                 news.serverlessV2ScalingConfiguration,
               CopyTagsToSnapshot: news.copyTagsToSnapshot,
               DeletionProtection: news.deletionProtection,
-              StorageEncrypted: news.storageEncrypted,
-              KmsKeyId: news.kmsKeyId,
-              ManageMasterUserPassword: news.manageMasterUserPassword,
-              Tags: Object.entries(tags).map(([Key, Value]) => ({
-                Key,
-                Value,
-              })),
-              ...credentials,
-            })
-            .pipe(
-              Effect.catchTag("DBClusterAlreadyExistsFault", () => Effect.void),
-            );
-
-          const cluster = yield* waitForCluster(identifier);
-          yield* session.note(cluster.DBClusterArn ?? identifier);
-          return toAttrs({ cluster, tags });
-        }),
-        update: Effect.fn(function* ({ id, news, olds, output, session }) {
-          const credentials = yield* resolveMasterCredentials(news);
+              MasterUserPassword: credentials.MasterUserPassword,
+              ApplyImmediately: true,
+            });
+            observed = yield* waitForCluster(identifier);
+          }
 
-          yield* rds.modifyDBCluster({
-            DBClusterIdentifier: output.dbClusterIdentifier,
-            EngineVersion: news.engineVersion,
-            DBClusterParameterGroupName: news.dbClusterParameterGroupName,
-            VpcSecurityGroupIds: news.vpcSecurityGroupIds,
-            Port: news.port,
-            EnableIAMDatabaseAuthentication:
-              news.enableIAMDatabaseAuthentication,
-            EnableHttpEndpoint: news.enableHttpEndpoint,
-            ServerlessV2ScalingConfiguration:
-              news.serverlessV2ScalingConfiguration,
-            CopyTagsToSnapshot: news.copyTagsToSnapshot,
-            DeletionProtection: news.deletionProtection,
-            MasterUserPassword: credentials.MasterUserPassword,
-            ApplyImmediately: true,
-          });
+          const dbClusterArn = observed.DBClusterArn ?? "";
 
-          const oldTags = {
-            ...(yield* createInternalTags(id)),
-            ...olds.tags,
-          };
-          const newTags = {
-            ...(yield* createInternalTags(id)),
-            ...news.tags,
-          };
-          const { removed, upsert } = diffTags(oldTags, newTags);
-          if (upsert.length > 0) {
+          // Sync tags — diff observed cloud tags against desired so the
+          // reconciler converges regardless of what was on the resource
+          // before (initial create, adoption, or drift).
+          const observedTags = toTagRecord(observed.TagList);
+          const { removed, upsert } = diffTags(observedTags, desiredTags);
+          if (upsert.length > 0 && dbClusterArn) {
             yield* rds.addTagsToResource({
-              ResourceName: output.dbClusterArn,
+              ResourceName: dbClusterArn,
               Tags: upsert,
             });
           }
-          if (removed.length > 0) {
+          if (removed.length > 0 && dbClusterArn) {
             yield* rds.removeTagsFromResource({
-              ResourceName: output.dbClusterArn,
+              ResourceName: dbClusterArn,
               TagKeys: removed,
             });
           }
 
-          const cluster = yield* waitForCluster(output.dbClusterIdentifier);
-          yield* session.note(output.dbClusterArn);
-          return toAttrs({ cluster, tags: newTags });
+          yield* session.note(dbClusterArn || identifier);
+          return toAttrs({ cluster: observed, tags: desiredTags });
         }),
         delete: Effect.fn(function* ({ output }) {
           yield* rds

package/src/AWS/RDS/DBClusterEndpoint.ts

@@ -134,85 +134,86 @@ export const DBClusterEndpointProvider = () =>
           }
           return toAttrs({ endpoint, tags: output?.tags ?? {} });
         }),
-        create: Effect.fn(function* ({ id, news, session }) {
-          const identifier = yield* toIdentifier(id, news);
-          const tags = {
-            ...(yield* createInternalTags(id)),
-            ...news.tags,
-          };
-          yield* rds
-            .createDBClusterEndpoint({
-              DBClusterIdentifier: news.dbClusterIdentifier,
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const identifier =
+            output?.dbClusterEndpointIdentifier ??
+            (yield* toIdentifier(id, news));
+          const internalTags = yield* createInternalTags(id);
+          const desiredTags = { ...internalTags, ...news.tags };
+
+          // Observe — fetch the endpoint's live state.
+          let observed = yield* readEndpoint(identifier);
+
+          // Ensure — create if missing. Tolerate
+          // `DBClusterEndpointAlreadyExistsFault` as a race with a peer
+          // reconciler.
+          if (!observed?.DBClusterEndpointIdentifier) {
+            yield* rds
+              .createDBClusterEndpoint({
+                DBClusterIdentifier: news.dbClusterIdentifier,
+                DBClusterEndpointIdentifier: identifier,
+                EndpointType: news.endpointType,
+                StaticMembers: news.staticMembers,
+                ExcludedMembers: news.excludedMembers,
+                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
+                  Key,
+                  Value,
+                })),
+              })
+              .pipe(
+                Effect.catchTag(
+                  "DBClusterEndpointAlreadyExistsFault",
+                  () => Effect.void,
+                ),
+              );
+            observed = yield* readEndpoint(identifier);
+            if (!observed?.DBClusterEndpointIdentifier) {
+              return yield* Effect.fail(
+                new Error(
+                  `DB cluster endpoint '${identifier}' not found after create`,
+                ),
+              );
+            }
+          } else {
+            // Sync mutable endpoint config — push desired shape.
+            yield* rds.modifyDBClusterEndpoint({
               DBClusterEndpointIdentifier: identifier,
               EndpointType: news.endpointType,
               StaticMembers: news.staticMembers,
               ExcludedMembers: news.excludedMembers,
-              Tags: Object.entries(tags).map(([Key, Value]) => ({
-                Key,
-                Value,
-              })),
-            })
-            .pipe(
-              Effect.catchTag(
-                "DBClusterEndpointAlreadyExistsFault",
-                () => Effect.void,
-              ),
-            );
-          const endpoint = yield* readEndpoint(identifier);
-          if (!endpoint?.DBClusterEndpointIdentifier) {
-            return yield* Effect.fail(
-              new Error(
-                `DB cluster endpoint '${identifier}' not found after create`,
-              ),
-            );
+            });
+            observed = yield* readEndpoint(identifier);
+            if (!observed?.DBClusterEndpointIdentifier) {
+              return yield* Effect.fail(
+                new Error(
+                  `DB cluster endpoint '${identifier}' not found after update`,
+                ),
+              );
+            }
           }
-          yield* session.note(endpoint.DBClusterEndpointArn ?? identifier);
-          return toAttrs({ endpoint, tags });
-        }),
-        update: Effect.fn(function* ({ id, news, olds, output, session }) {
-          yield* rds.modifyDBClusterEndpoint({
-            DBClusterEndpointIdentifier: output.dbClusterEndpointIdentifier,
-            EndpointType: news.endpointType,
-            StaticMembers: news.staticMembers,
-            ExcludedMembers: news.excludedMembers,
-          });
 
-          const oldTags = {
-            ...(yield* createInternalTags(id)),
-            ...olds.tags,
-          };
-          const newTags = {
-            ...(yield* createInternalTags(id)),
-            ...news.tags,
-          };
-          const { removed, upsert } = diffTags(oldTags, newTags);
-          if (upsert.length > 0 && output.dbClusterEndpointArn) {
+          const dbClusterEndpointArn = observed.DBClusterEndpointArn;
+
+          // Sync tags — diff observed cloud tags against desired. The
+          // describeDBClusterEndpoints response does not include tags, so we
+          // diff against the previously-recorded tag set on `output`.
+          const observedTags = output?.tags ?? {};
+          const { removed, upsert } = diffTags(observedTags, desiredTags);
+          if (upsert.length > 0 && dbClusterEndpointArn) {
             yield* rds.addTagsToResource({
-              ResourceName: output.dbClusterEndpointArn,
+              ResourceName: dbClusterEndpointArn,
               Tags: upsert,
             });
           }
-          if (removed.length > 0 && output.dbClusterEndpointArn) {
+          if (removed.length > 0 && dbClusterEndpointArn) {
             yield* rds.removeTagsFromResource({
-              ResourceName: output.dbClusterEndpointArn,
+              ResourceName: dbClusterEndpointArn,
               TagKeys: removed,
             });
           }
 
-          const endpoint = yield* readEndpoint(
-            output.dbClusterEndpointIdentifier,
-          );
-          if (!endpoint?.DBClusterEndpointIdentifier) {
-            return yield* Effect.fail(
-              new Error(
-                `DB cluster endpoint '${output.dbClusterEndpointIdentifier}' not found after update`,
-              ),
-            );
-          }
-          yield* session.note(
-            output.dbClusterEndpointArn ?? output.dbClusterEndpointIdentifier,
-          );
-          return toAttrs({ endpoint, tags: newTags });
+          yield* session.note(dbClusterEndpointArn ?? identifier);
+          return toAttrs({ endpoint: observed, tags: desiredTags });
         }),
         delete: Effect.fn(function* ({ output }) {
           yield* rds

package/src/AWS/RDS/DBClusterParameterGroup.ts

@@ -107,80 +107,74 @@ export const DBClusterParameterGroupProvider = () =>
             tags: output?.tags ?? {},
           };
         }),
-        create: Effect.fn(function* ({ id, news, session }) {
-          const name = yield* toName(id, news);
-          const tags = {
-            ...(yield* createInternalTags(id)),
-            ...news.tags,
-          };
-          const created = yield* rds
-            .createDBClusterParameterGroup({
-              DBClusterParameterGroupName: name,
-              DBParameterGroupFamily: news.family,
-              Description:
-                news.description ?? `Alchemy parameter group ${name}`,
-              Tags: Object.entries(tags).map(([Key, Value]) => ({
-                Key,
-                Value,
-              })),
-            })
-            .pipe(
-              Effect.catchTag("DBParameterGroupAlreadyExistsFault", () =>
-                rds.describeDBClusterParameterGroups({
-                  DBClusterParameterGroupName: name,
-                }),
-              ),
-            );
-          const group =
-            "DBClusterParameterGroup" in created
-              ? created.DBClusterParameterGroup
-              : (created as rds.DBClusterParameterGroupsMessage)
-                  .DBClusterParameterGroups?.[0];
-          if (!group?.DBClusterParameterGroupName) {
-            return yield* Effect.fail(
-              new Error(
-                `Failed to create DB cluster parameter group '${name}'`,
-              ),
-            );
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const name =
+            output?.dbClusterParameterGroupName ?? (yield* toName(id, news));
+          const internalTags = yield* createInternalTags(id);
+          const desiredTags = { ...internalTags, ...news.tags };
+
+          // Observe — fetch the parameter group's live state.
+          let observed = yield* readGroup(name);
+
+          // Ensure — create if missing. Tolerate
+          // `DBParameterGroupAlreadyExistsFault` as a race with a peer
+          // reconciler by re-reading.
+          if (!observed?.DBClusterParameterGroupName) {
+            yield* rds
+              .createDBClusterParameterGroup({
+                DBClusterParameterGroupName: name,
+                DBParameterGroupFamily: news.family,
+                Description:
+                  news.description ?? `Alchemy parameter group ${name}`,
+                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
+                  Key,
+                  Value,
+                })),
+              })
+              .pipe(
+                Effect.catchTag(
+                  "DBParameterGroupAlreadyExistsFault",
+                  () => Effect.void,
+                ),
+              );
+            observed = yield* readGroup(name);
+            if (!observed?.DBClusterParameterGroupName) {
+              return yield* Effect.fail(
+                new Error(
+                  `Failed to create DB cluster parameter group '${name}'`,
+                ),
+              );
+            }
           }
-          yield* session.note(group.DBClusterParameterGroupArn ?? name);
-          return {
-            dbClusterParameterGroupName: group.DBClusterParameterGroupName,
-            dbClusterParameterGroupArn: group.DBClusterParameterGroupArn,
-            family: group.DBParameterGroupFamily ?? news.family,
-            description: group.Description,
-            tags,
-          };
-        }),
-        update: Effect.fn(function* ({ id, news, olds, output, session }) {
-          const oldTags = {
-            ...(yield* createInternalTags(id)),
-            ...olds.tags,
-          };
-          const newTags = {
-            ...(yield* createInternalTags(id)),
-            ...news.tags,
-          };
-          const { removed, upsert } = diffTags(oldTags, newTags);
-          if (upsert.length > 0 && output.dbClusterParameterGroupArn) {
+
+          const dbClusterParameterGroupArn =
+            observed.DBClusterParameterGroupArn;
+
+          // Sync tags — diff observed (the describe response does not
+          // surface tags, so use prior `output.tags` as the baseline) ↔
+          // desired.
+          const observedTags = output?.tags ?? {};
+          const { removed, upsert } = diffTags(observedTags, desiredTags);
+          if (upsert.length > 0 && dbClusterParameterGroupArn) {
             yield* rds.addTagsToResource({
-              ResourceName: output.dbClusterParameterGroupArn,
+              ResourceName: dbClusterParameterGroupArn,
               Tags: upsert,
             });
           }
-          if (removed.length > 0 && output.dbClusterParameterGroupArn) {
+          if (removed.length > 0 && dbClusterParameterGroupArn) {
             yield* rds.removeTagsFromResource({
-              ResourceName: output.dbClusterParameterGroupArn,
+              ResourceName: dbClusterParameterGroupArn,
               TagKeys: removed,
             });
           }
-          yield* session.note(
-            output.dbClusterParameterGroupArn ??
-              output.dbClusterParameterGroupName,
-          );
+
+          yield* session.note(dbClusterParameterGroupArn ?? name);
           return {
-            ...output,
-            tags: newTags,
+            dbClusterParameterGroupName: observed.DBClusterParameterGroupName,
+            dbClusterParameterGroupArn,
+            family: observed.DBParameterGroupFamily ?? news.family,
+            description: observed.Description,
+            tags: desiredTags,
           };
         }),
         delete: Effect.fn(function* ({ output }) {