feat(core): builtin PropertyMergeStrategys are now compatible with deferred Box values

[mrgrain]

Issue # (if applicable)

N/A

Reason for this change

L2 constructs use Boxes internally to defer property values until synthesis time. When a property mixin tried to merge into a Box-backed value (e.g. TableV2.replicas), the merge strategy would see an opaque IResolvable object instead of the actual array or object, causing incorrect results.

Description of changes

Introduces two new wrapper classes that make merge strategies box-safe without mixing concerns into the core merge logic:

BoxSafeMergeStrategy wraps any IMergeStrategy. For each key, it checks whether the target or source value is a Box. If so, it defers the merge via Box.combine so the delegate strategy operates on resolved values. Non-Box values are passed through to the delegate directly.

BoxSafeArrayStrategy wraps any IArrayMergeStrategy. It checks whether any element in either array is a Box, and if so defers the entire array merge. This is only needed for replaceByKey, which reads element properties to match them — other array strategies just shuffle elements positionally and don't need it.

PropertyMergeStrategy.combine() is now wrapped in BoxSafeMergeStrategy, and ArrayMergeStrategy.replaceByKey() is wrapped in BoxSafeArrayStrategy. The core strategy classes remain pure and unaware of Boxes.

Also documents Box support in the public API JSDoc and adds a "Deferred Values" section to the @aws-cdk/cfn-property-mixins README explaining what is and isn't supported.

Describe any new or updated permissions being added

N/A

Description of how you validated changes

Unit tests in core/test/mixins/property-merge-strategy.box-safety.test.ts covering target-is-Box, source-is-Box, both-are-Boxes, Box elements inside arrays, deferred mutations, and derived boxes. Integration tests in @aws-cdk/cfn-property-mixins using TableV2 with all array merge strategies against Box-backed replicas.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[github-actions]

👋 It looks like your PR description follows the template but is missing a valid issue number in the first section.

PRs without a linked issue will receive lower priority for review and merging. Please update the description to include a reference like Closes #123. If no existing issue matches your change, create one first.

[aws-cdk-automation]

(This review is outdated)

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

[rix0rrr]

The point of the Box refactor is that we can capture stack traces of the "moment of instruction to modify a value". This sounds like it makes Property Mixins behave like Aspects (i.e., run lazily).

Are we retaining the stack trace of where the Mixin got applied?

[mrgrain]

No. Aspects don't magically support deferred values either, since deferred values are resolved after Aspects.

    const table = new dynamodb.TableV2(this, "MinimalAppTable", {
      partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING },
    });

    cdk.Aspects.of(table).add({
      visit: function (node: IConstruct): void {
        if (!dynamodb.CfnGlobalTable.isCfnGlobalTable(node)) {
          return;
        }
        if (isBox(node.replicas)) {
          throw Error("Replicas is a box");
        }
      }
    }, {
      priority: cdk.AspectPriority.MUTATING
    })

Will result in Error: Replicas is a box.

With Aspects, we didn't really allow or encourage construct mutation. It only really supports construct tree mutation. So this wasn't really an issue before, because you only had the choice to either

• inspect table and fail because table.replicas is not a readable value
• remove the table and replace it with something else

In practice, I'd wager that L2s that heavily depend on deferred values didn't get used much with Aspects at all.

---

The Box proposal itself is was made manipulation of deferred values possible in the first place! That's a huge win for everyone concerned. Some of our existing L2 code could be rewritten much better now as well (if we cared enough). This PR just makes something automatically available that users could write themselves today. Also the readme just shows something that ought to have worked already in the first place, if we didn't rely on Lazy's so much.

[mrgrain]

Are we retaining the stack trace of where the Mixin got applied?

No special provisions for that at the moment. But every L1 property assignment already points to the .with call in userland code.

[rix0rrr]

Oof, this declaration 😓

(I know why but it still feels quite heavy)

[mrgrain]

I don't have a better solution just now, but I have a vague idea of introducing a "smart" merge strategy that is aware of resource types and what they need.

The direct alternative to this syntax would be a mutex list of booleans, which I don't think is better. Do you have other suggestions?

In any case, the array change is not new in this PR. It's just documented here.

[rix0rrr]

I don't have a better suggestion. Mutex booleans and judicious choice of defaults is probably the best we've got.

[rix0rrr]

Can we error on this in some way, so at least it doesn't pass unnoticed?

This feels like asking users to check for something they can't really see...

[mrgrain]

Tokens we can probably reverse. For Lazys I was looking to investigate if we can change their internal implementation to be Boxes.

In any case, this is existing behavior. Happy to think about erroring here (though would be breaking), but would prefer to do this on a separate PR. The proposed change makes the situation strictly better by now not opaquely failing anymore in many cases.

[rix0rrr]

Ohhh I see. Clever.

Since this goes through the L1 setter (afaiu), this seems to ultimately desugar to:

oldBox.set(combinedBox);

So: relying on the Box setter allowing a Box to be set into itself. Does that actually work?

[mrgrain]

No, the setter doesn't call oldBox.set(...). We are replacing the whole Box with new one.

The L1 line is

this._replicas = value;

with value being a new ComputedBox.

[rix0rrr]

Oh, so we poke through the L1 setter to directly access the backing field?

[mrgrain]

Not sure what you mean by poking through.

We are transparently using the L1 getter and setter. This part has nothing to do with boxes, and all to do with capturing a stack trace when calling the setter. The original L2 construct Box has stack traces disabled anyway via @noBoxStackTraces.

[mrgrain]

We create a brand new Combined Box from the original target and the new data source. That Combined Box will contain the stack trace of the original box if any was present. The setter call will collect the stack trace of the assignment. Both end up as aws:cdk:propertyAssignment entries.

[otaviomacedo]

In case of tokens, would it make sense to Tokenization.reverse them and, if the obtained value is a box, run with it?

[mrgrain]

Good idea. Will follow-up in a second PR if that's okay.

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-05-13 11:56 UTC · Rule: default-squash
• ✅ Checks passed · in-place
• ✅ Merged — 2026-05-13 14:16 UTC · at a0b548ee8dd25b80c7d1d6dbf753b48b6f801cf4 · squash

This pull request spent 2 hours 20 minutes 11 seconds in the queue, including 47 minutes 25 seconds running CI.

Required conditions to merge

• #approved-reviews-by >= 1 [🛡 GitHub branch protection]
  • feat(core): builtin PropertyMergeStrategys are now compatible with deferred Box values #37844
• #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  • feat(core): builtin PropertyMergeStrategys are now compatible with deferred Box values #37844
• any of [🛡 GitHub branch protection]:
  • check-success = validate-pr
  • check-neutral = validate-pr
  • check-skipped = validate-pr
• any of [🛡 GitHub branch protection]:
  • check-success = build
  • check-neutral = build
  • check-skipped = build

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.