@venturekit/infra 0.0.0-dev.20260514025219 → 0.0.0-dev.20260515022321

package/dist/cdk/stack.js

@@ -131,26 +131,11 @@ function djb2Hash(input) {
     }
     return h >>> 0;
 }
-/**
- * Smallest power of two that is `>= n`. Used to pick the nested-stack
- * bucket count, so that growing past a threshold doubles the count
- * rather than incrementing it — the doubled-size hash bucketing only
- * relocates ~half the routes, and growth is geometric (rare events)
- * rather than additive (every deploy after a route added).
- */
-export function nextPowerOfTwo(n) {
-    if (n <= 1)
-        return 1;
-    let p = 1;
-    while (p < n)
-        p <<= 1;
-    return p;
-}
 /**
  * Map a route slug to a nested-stack slot index in `[0, numSlots)`.
- * `numSlots` MUST be a power of two so the modulo distributes the
- * hash output evenly. Exported for unit tests asserting bucketing
- * stability across route-set changes.
+ * `numSlots` MUST be a power of two so the bitwise-AND modulo
+ * distributes the hash output evenly. Exported for unit tests
+ * asserting bucketing stability across route-set changes.
  */
 export function stableSlotFor(slug, numSlots) {
     return djb2Hash(slug) & (numSlots - 1);
@@ -833,6 +818,19 @@ export class VentureStack extends cdk.Stack {
             },
             disableExecuteApiEndpoint: false,
         });
+        // Well-Architected: Reliability — RETAIN the HttpApi under strict
+        // dataSafety. The `*.execute-api.{region}.amazonaws.com` URL is unique
+        // to the API ID, so deleting the API invalidates every consumer that
+        // hardcoded that URL (mobile apps shipped with the URL baked in,
+        // partner integrations, webhook subscribers, etc.). Custom-domain
+        // mappings live on this same API ID — losing the API also breaks the
+        // mapping until manually re-attached. RETAIN means a deleted CFN
+        // stack leaves the API in place for `cdk import` recovery.
+        const cfnApi = api.node.defaultChild;
+        if (this.dataSafetyConfig.removalPolicy === 'retain') {
+            cfnApi.cfnOptions.deletionPolicy = cdk.CfnDeletionPolicy.RETAIN;
+            cfnApi.cfnOptions.updateReplacePolicy = cdk.CfnDeletionPolicy.RETAIN;
+        }
         // Well-Architected: Operational Excellence — access logging for API
         const apiLogGroup = new logs.LogGroup(this, 'ApiAccessLog', {
             logGroupName: `/venturekit/${projectName}/${stage}/api-access`,
@@ -1221,35 +1219,58 @@ export class VentureStack extends cdk.Stack {
             // automatically via SSM Parameter passthrough.
             const NESTED_STACK_THRESHOLD = 80;
             const ROUTES_PER_NESTED_STACK = 50;
+            // Fixed, immutable nested-stack slot count.
+            //
+            // The bucketing function `stableSlotFor(slug, numSlots)` is a
+            // pure function of these two inputs. As long as `numSlots`
+            // never changes, every previously-deployed route keeps its
+            // slot — which means CloudFormation never has to migrate a
+            // route's `ApiGatewayV2::Route` resource across nested stack
+            // boundaries between deploys.
+            //
+            // That invariant is load-bearing. `ApiGatewayV2::Route` carries
+            // a unique `(method, path)` key at the API Gateway level, not
+            // just the CloudFormation level. If the same route key lives in
+            // two nested stacks (old + new) at the same moment, the create
+            // call fails with `Route with key <METHOD> <path> already exists
+            // for this API` because CFN updates nested stacks in parallel
+            // and has no cross-stack delete-before-create ordering.
+            //
+            // 16 slots × ~80 routes/slot (the CloudFormation per-stack 500-
+            // resource limit at ~5 CFN resources per route) gives ~1280
+            // routes of headroom — comfortably above anything we've seen
+            // in practice. Raising this number later would force a
+            // one-shot mass migration of every nested-stack route in every
+            // already-deployed project; don't do it casually.
+            const NUM_NESTED_STACK_SLOTS = 16;
             if (discoveredRoutes.length <= NESTED_STACK_THRESHOLD) {
                 for (const route of discoveredRoutes) {
                     this.createRouteFunction(route, projectName, stage, api, lambdaRole, lambdaSg, vpc);
                 }
             }
             else {
-                // Stable hash-based bucketing.
+                // Stable hash-based bucketing into a fixed, never-changing slot
+                // pool.
                 //
-                // The previous index-based scheme (`routes.slice(i, i+50)`) sliced
-                // the discovered-route array into fixed 50-route windows. Adding,
-                // removing, or renaming any single route shifted every later route
-                // by one position, which moved a tail of routes across a 50-route
-                // boundary into a different `RoutesN` nested stack. Combined with
-                // explicit `FunctionName`s on each Lambda this caused
-                // `<name> already exists in stack <other-stack>` deploy failures
-                // — CFN updates nested stacks in parallel, so the new copy tries
-                // to come up before the old one is torn down.
+                // The previous index-based scheme (`routes.slice(i, i+50)`)
+                // sliced the discovered-route array into fixed 50-route windows.
+                // Adding, removing, or renaming any single route shifted every
+                // later route by one position, which moved a tail of routes
+                // across a 50-route boundary into a different `RoutesN` nested
+                // stack. Combined with the unique `(method, path)` key carried
+                // by `ApiGatewayV2::Route`, this caused
+                // `Route with key <METHOD> <path> already exists for this API`
+                // deploy failures — CFN updates nested stacks in parallel, so
+                // the new route resource tries to register at API Gateway
+                // before the old one in the other nested stack is deleted.
                 //
-                // Hashing the slug into a bucket pins each route to a slot that is
-                // independent of its siblings. Adding an unrelated route never
-                // moves an existing one. The bucket count is rounded up to the
-                // next power of two so that, in the rare case where the project
-                // grows enough to require more buckets, the doubling reshuffle is
-                // a one-shot event rather than a continuous churn — and
-                // because nested-stack route Lambdas are auto-named (see
-                // `RoutesNestedStack.createRouteFunction`), CloudFormation can
-                // migrate them across stacks without a name collision.
-                const targetSlots = Math.max(2, Math.ceil(discoveredRoutes.length / ROUTES_PER_NESTED_STACK));
-                const numSlots = nextPowerOfTwo(targetSlots);
+                // Hashing the slug into a fixed slot pool pins each route to a
+                // slot that's determined the first time it's deployed and
+                // never moves. Adding or removing siblings doesn't reshuffle
+                // anything; changing slot count is the only event that would —
+                // which is exactly why `NUM_NESTED_STACK_SLOTS` is a hard-coded
+                // constant rather than something derived from the route count.
+                const numSlots = NUM_NESTED_STACK_SLOTS;
                 const buckets = Array.from({ length: numSlots }, () => []);
                 for (const route of discoveredRoutes) {
                     const slot = stableSlotFor(route.slug, numSlots);
@@ -1626,6 +1647,17 @@ export class VentureStack extends cdk.Stack {
                 enabled: true,
                 ...aliasProps,
             });
+            // Well-Architected: Reliability — RETAIN the distribution under
+            // strict dataSafety. Distributions are slow to create (~15-30 min
+            // for the global edge rollout), have a stable `*.cloudfront.net`
+            // domain that consumers may cache, and re-issuing the ACM cert
+            // requires re-doing DNS validation. RETAIN means an accidental
+            // stack delete leaves the distribution in place for `cdk import`.
+            if (this.dataSafetyConfig.removalPolicy === 'retain') {
+                const cfnDistribution = distribution.node.defaultChild;
+                cfnDistribution.cfnOptions.deletionPolicy = cdk.CfnDeletionPolicy.RETAIN;
+                cfnDistribution.cfnOptions.updateReplacePolicy = cdk.CfnDeletionPolicy.RETAIN;
+            }
             new cdk.CfnOutput(this, `${logicalId}-cdn-domain`, {
                 value: distribution.distributionDomainName,
                 description: `CloudFront domain for ${intent.id}`,
@@ -1713,6 +1745,16 @@ export class VentureStack extends cdk.Stack {
                     : cognito.Mfa.OFF,
             // Well-Architected: Reliability — dataSafety removal policy
             removalPolicy: this.toRemovalPolicy(),
+            // Well-Architected: Reliability — native deletion protection on top of
+            // RETAIN. `DeletionPolicy=Retain` only blocks CFN-driven deletes; the
+            // user pool can still be deleted via console / API / CLI. Cognito's
+            // native deletionProtection flag blocks that path too. Both layers
+            // must be explicitly disabled before the pool can be deleted, and
+            // every flip is CloudTrail-logged. Losing a Cognito User Pool means
+            // losing every user identity + password hash — the most catastrophic
+            // recoverable state in a VentureKit deploy, since users must re-
+            // register via password reset.
+            deletionProtection: this.dataSafetyConfig.removalPolicy === 'retain',
             // Well-Architected: Security — advanced security mode for medium+ presets
             advancedSecurityMode: this.envConfig.lambda.memoryMb >= 512
                 ? cognito.AdvancedSecurityMode.ENFORCED
@@ -1817,6 +1859,14 @@ export class VentureStack extends cdk.Stack {
                     clientId: cdk.SecretValue.unsafePlainText('PLACEHOLDER'),
                     clientSecret: cdk.SecretValue.unsafePlainText('PLACEHOLDER'),
                 },
+                // Well-Architected: Reliability — federated provider credentials
+                // are operator-set values pasted from the third-party developer
+                // console (Google Cloud, Meta for Developers, Apple Developer).
+                // They can be re-generated by the operator but require manually
+                // revisiting that console; we'd rather not force that on every
+                // stack-replace event. Promote to RETAIN under strict dataSafety
+                // so accidental stack deletes don't wipe them.
+                removalPolicy: this.toRemovalPolicy(),
             });
             this.federatedAuthSecrets.push(secret);
             const envVar = `COGNITO_FEDERATED_${provider.toUpperCase()}_SECRET_ARN`;
@@ -1876,6 +1926,18 @@ export class VentureStack extends cdk.Stack {
             // for a topic only consumed by our own
             // Lambda + the operator's SNS console.
         });
+        // Well-Architected: Reliability — RETAIN the events topic under
+        // strict dataSafety. SNS topics carry durable subscriptions (the
+        // bounce-handler Lambda is one; operators may attach additional
+        // subscribers via the console for observability tools or paging).
+        // Deleting the topic silently drops every subscription; re-creating
+        // the topic does NOT restore them. RETAIN means an accidental stack
+        // delete leaves the topic + subscriptions in place for recovery.
+        if (this.dataSafetyConfig.removalPolicy === 'retain') {
+            const cfnEventsTopic = eventsTopic.node.defaultChild;
+            cfnEventsTopic.cfnOptions.deletionPolicy = cdk.CfnDeletionPolicy.RETAIN;
+            cfnEventsTopic.cfnOptions.updateReplacePolicy = cdk.CfnDeletionPolicy.RETAIN;
+        }
         new cdk.CfnOutput(this, `${logicalId}-events-topic-arn`, {
             value: eventsTopic.topicArn,
             description: `SES events SNS topic for notify '${intent.id}'`,
@@ -2120,6 +2182,12 @@ export class VentureStack extends cdk.Stack {
                 queueName: `${projectName}-${stage}-${dispatcherFnId}-dlq`,
                 retentionPeriod: cdk.Duration.days(14),
                 encryption: sqs.QueueEncryption.SQS_MANAGED,
+                // Well-Architected: Reliability — queues hold accepted-but-not-yet-
+                // processed work. CDK's default removalPolicy for sqs.Queue is
+                // DESTROY, which would silently delete the DLQ and all its failed-
+                // message diagnostics on stack delete. Under dataSafety='strict' we
+                // promote to RETAIN so the queue + messages survive any stack churn.
+                removalPolicy: this.toRemovalPolicy(),
             });
             const dispatcherFn = new lambda.Function(this, dispatcherFnId, {
                 functionName: `${projectName}-${stage}-${dispatcherFnId}`,
@@ -2165,6 +2233,10 @@ export class VentureStack extends cdk.Stack {
                 queueName: `${projectName}-${stage}-${bounceFnId}-dlq`,
                 retentionPeriod: cdk.Duration.days(14),
                 encryption: sqs.QueueEncryption.SQS_MANAGED,
+                // Same rationale as the dispatcher DLQ above: bounced/complained
+                // notifications are the canonical record of what failed and why;
+                // dropping them on stack delete loses the audit trail.
+                removalPolicy: this.toRemovalPolicy(),
             });
             const bounceFn = new lambda.Function(this, bounceFnId, {
                 functionName: `${projectName}-${stage}-${bounceFnId}`,
@@ -2213,6 +2285,12 @@ export class VentureStack extends cdk.Stack {
             retentionPeriod: cdk.Duration.days(14),
             // Well-Architected: Security — encryption at rest
             encryption: sqs.QueueEncryption.SQS_MANAGED,
+            // Well-Architected: Reliability — DLQs are the durable record of every
+            // message a consumer Lambda failed to process. Default CDK removalPolicy
+            // for sqs.Queue is DESTROY; under dataSafety='strict' we promote to
+            // RETAIN so investigation of past failures survives any redeploy or
+            // stack-delete event.
+            removalPolicy: this.toRemovalPolicy(),
         });
         const queue = new sqs.Queue(this, logicalId, {
             queueName: `${projectName}-${intent.id}-${stage}${intent.type === 'fifo' ? '.fifo' : ''}`,
@@ -2228,6 +2306,15 @@ export class VentureStack extends cdk.Stack {
                 queue: dlq,
                 maxReceiveCount: intent.maxReceiveCount ?? 3,
             },
+            // Well-Architected: Reliability — primary work queue holds accepted
+            // jobs that have not yet been processed. CDK's default is DESTROY,
+            // which would lose every in-flight message on any stack delete or
+            // logical-ID rename. Under dataSafety='strict' we promote to RETAIN.
+            // Combined with the upcoming multi-stack messaging-tier split, the
+            // queue then survives even an app-stack tear-down — new ESMs in the
+            // redeployed app stack resume consumption from where the old one
+            // stopped.
+            removalPolicy: this.toRemovalPolicy(),
         });
         new cdk.CfnOutput(this, `${logicalId}-queue-url`, {
             value: queue.queueUrl,
@@ -2337,6 +2424,12 @@ export class VentureStack extends cdk.Stack {
             const secret = new secretsmanager.Secret(this, resourceName, {
                 secretName: `${projectName}/${stage}/${intent.id}`,
                 description: intent.description || `Secret for ${intent.id}`,
+                // Well-Architected: Reliability — operator-declared secrets hold
+                // values the operator pasted in manually (API keys, third-party
+                // integration tokens). They cannot be re-generated by VentureKit
+                // and an accidental delete forces a manual rotation of every
+                // downstream credential. RETAIN under strict dataSafety.
+                removalPolicy: this.toRemovalPolicy(),
             });
             new cdk.CfnOutput(this, `${resourceName}-secret-arn`, {
                 value: secret.secretArn,
@@ -2351,6 +2444,13 @@ export class VentureStack extends cdk.Stack {
                 stringValue: 'PLACEHOLDER — set value after deploy',
                 tier: ssm.ParameterTier.STANDARD,
             });
+            // SSM parameters don't carry their own DeletionPolicy attribute
+            // (the resource type doesn't support it in CFN), and AWS doesn't
+            // expose a "deletion protection" flag for them either. Operators
+            // relying on these for production secret-like config should
+            // either move to Secrets Manager via `store: 'secretsmanager'`
+            // (which we now RETAIN above) or accept that an accidental
+            // stack delete loses the value.
             new cdk.CfnOutput(this, `${resourceName}-param-name`, {
                 value: param.parameterName,
                 description: `SSM Parameter name for ${intent.id}`,
@@ -2386,12 +2486,30 @@ export class VentureStack extends cdk.Stack {
             domainName: intent.domain,
             certificate,
         });
+        // Well-Architected: Reliability — RETAIN both the domain name and the
+        // mapping under strict dataSafety. The custom domain is the *public*
+        // contract with the world; deleting it forces DNS reconfiguration on
+        // every client/integration. RETAIN means an accidental stack delete
+        // leaves the domain claimed to this account and ready for `cdk
+        // import`. The ApiMapping rides along — without it the domain points
+        // nowhere, but mappings recreate cleanly so RETAIN is mostly a
+        // convenience for the recovery path.
+        if (this.dataSafetyConfig.removalPolicy === 'retain') {
+            const cfnDomain = domainName.node.defaultChild;
+            cfnDomain.cfnOptions.deletionPolicy = cdk.CfnDeletionPolicy.RETAIN;
+            cfnDomain.cfnOptions.updateReplacePolicy = cdk.CfnDeletionPolicy.RETAIN;
+        }
         // API mapping
-        new apigatewayv2.ApiMapping(this, `${resourceName}-mapping`, {
+        const apiMapping = new apigatewayv2.ApiMapping(this, `${resourceName}-mapping`, {
             api,
             domainName,
             stage: api.defaultStage,
         });
+        if (this.dataSafetyConfig.removalPolicy === 'retain') {
+            const cfnMapping = apiMapping.node.defaultChild;
+            cfnMapping.cfnOptions.deletionPolicy = cdk.CfnDeletionPolicy.RETAIN;
+            cfnMapping.cfnOptions.updateReplacePolicy = cdk.CfnDeletionPolicy.RETAIN;
+        }
         // Route53 A record if hosted zone provided
         if (intent.hostedZoneId) {
             const hostedZone = route53.HostedZone.fromHostedZoneAttributes(this, `${resourceName}-zone-record`, {
@@ -2437,6 +2555,13 @@ export class VentureStack extends cdk.Stack {
             timeToLiveAttribute: 'ttl',
             // Well-Architected: Operational Excellence — contributor insights for medium+
             contributorInsightsEnabled: this.envConfig.lambda.memoryMb >= 512,
+            // Well-Architected: Reliability — native deletion protection on top of
+            // RETAIN. DeletionPolicy=Retain only blocks CFN-driven deletes; turning
+            // on deletionProtectionEnabled also blocks the AWS console / API / CLI
+            // "delete table" path. Together they make accidental data loss require
+            // two explicit operator actions (disable protection AND override the
+            // deletion policy), each loggable in CloudTrail.
+            deletionProtection: this.dataSafetyConfig.removalPolicy === 'retain',
         });
         // Well-Architected: Reliability — prevent accidental replacement
         const cfnTable = table.node.defaultChild;
@@ -2477,10 +2602,28 @@ export class VentureStack extends cdk.Stack {
             tableName,
             partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
             billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
-            removalPolicy: cdk.RemovalPolicy.DESTROY,
+            // Well-Architected: Reliability — rate-limit counters are per-user
+            // state. Hardcoding DESTROY would erase every user's current rate-
+            // limit window on any stack churn, surfacing as a simultaneous
+            // "all users get a fresh quota" event — minor but observable under
+            // load and not what dataSafety='strict' implies. Track dataSafety
+            // the same way every other stateful resource does.
+            removalPolicy: this.toRemovalPolicy(),
             timeToLiveAttribute: 'ttl',
             encryption: dynamodb.TableEncryption.AWS_MANAGED,
+            // Native AWS deletion protection alongside RETAIN. See the
+            // user-declared DDB path above for the two-layer rationale.
+            deletionProtection: this.dataSafetyConfig.removalPolicy === 'retain',
         });
+        // Well-Architected: Reliability — UpdateReplacePolicy=Retain so that a
+        // property change requiring REPLACE (e.g. changing the partition-key
+        // schema, which CFN executes as delete-then-create) preserves the old
+        // table rather than dropping every active rate-limit window. Matches
+        // the user-declared DDB path.
+        const cfnRateLimitTable = table.node.defaultChild;
+        if (this.dataSafetyConfig.removalPolicy === 'retain') {
+            cfnRateLimitTable.cfnOptions.updateReplacePolicy = cdk.CfnDeletionPolicy.RETAIN;
+        }
         this.ventureBaseEnv['VENTURE_RATE_LIMIT_TABLE'] = table.tableName;
         new cdk.CfnOutput(this, `${logicalId}-table-name`, {
             value: table.tableName,