feat(core): embed structured design context in synthesized templates (MetadataContext)

[satyakigh]

Reason for this change

CloudFormation templates capture what infrastructure exists but not why — rationale, invariants, change-safety, and operational knowledge live in code comments, wikis, and people's heads, and are lost by the time someone (or an automated tool/agent) modifies the deployed template. A structured, advisory Metadata.Context schema defines where that knowledge belongs in the template, but CDK users have no way to author it. Since most production templates are CDK-synthesized, CDK needs a first-class authoring surface that emits the schema's frozen wire format.

Description of changes

Two composable capabilities, following the feature-placement decision in docs/AGENTS_CONSTRUCT_DESIGN.md (cross-cutting capability → aspect-backed facade + Mixin, not per-service L2 changes):

MetadataContext facade in aws-cdk-lib core (core/lib/metadata-context.ts, shared rendering/validation in core/lib/private/metadata-context-internal.ts) — mirrors the Tags/RemovalPolicies pattern:

• MetadataContext.of(scope).add(props, options?) — resource-level context (why, must, mutable, sparse mutability map, trust, ops, gaps, deps, failureModes). Cascades at synth time to primary resources (the defaultChild chain), skipping incidental helper resources; nearest scope wins scalars, list fields union and de-duplicate. Options: applyToAllResources, includeResourceTypes/excludeResourceTypes, aspect priority. Crosses stack boundaries into NestedStacks, like Tags.
• MetadataContext.of(scope).addToTemplate(props) — template-level context (arch, must, refs, owner) merged into the enclosing stack's top-level Metadata.
• New enums ContextMutability, ContextTrustSource, ContextTrustConfidence; structs ResourceContextProps, TemplateContextProps, ContextTrust, ContextRef. Trust defaults: AUTHORED/MEDIUM. Explicit cfnResource.addMetadata('Context', ...) always wins over cascaded context.

MetadataContextMixin in aws-cdk-lib core (core/lib/mixins/metadata-context-mixin.ts) — imperative application to exactly the constructs you target via .with() or Mixins.of(scope).apply(); delegates to the facade so both forms share one merge model. Exported flat from aws-cdk-lib because jsii forbids a top-level mixins submodule (JSII5011 conflict with the Mixins class); the awslint mixin-namespace rule is excluded for this one class in awslint.json (file-location and extends-base rules pass as-is).

Docs: new "Metadata Context" section in the aws-cdk-lib README, covering both the facade and the Mixin.

Describe any new or updated permissions being added

None. The change writes only to template Metadata sections at synthesis time — no IAM policies, roles, grants, trust relationships, or resource policies are created or modified, and no runtime AWS calls are made.

Description of how you validated changes

• Unit tests: new tests in core/test/metadata-context.test.ts (rendering, cascade/merge semantics, primary-resource targeting incl. L2-style defaultChild trees and grouping constructs, NestedStack template + cascade behavior, filters, validation errors, wire-format conformance incl. a frozen-enum drift check); 6 tests for the mixin in core/test/mixins/metadata-context-mixin.test.ts. All assertions run against synthesized templates (toCloudFormation per core convention).

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

RFC aws/aws-cdk-rfcs#981

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

[github-actions]

⚠️ This pull request description does not follow the correct template structure.

PRs without a linked issue will receive lower priority for review and merging. Please update the description to follow the PR template and include a line like Closes #123 in the Issue section. 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.

[mrgrain]

Hey, since the feature is already stable, the Mixin should go straight into aws-cdk-lib as well. The preview package is being phased out.

Pull request has been modified.

[satyakigh]

Hey, since the feature is already stable, the Mixin should go straight into aws-cdk-lib as well. The preview package is being phased out.

Sounds good, updated

[iliapolo]

Draft until RFC 972: Structured design context in synthesized templates is approved.