RFC 972: Structured design context in synthesized templates

[satyakigh]

This is a request for comments about Structured design context in synthesized templates. See #972 for
additional details.

APIs are signed off by @iliapolo

---

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

[dgandhi62]

Is this intended to propagate down the construct tree? For instance, in an L3 construct, would list fields accumulate on every resource within the construct?

A further question is - could this lead to biasing the user's AI agent? If they see a single string in a field repeated for each resource?

[satyakigh]

Applying information to descendants is now explicit rather than automatic. The RFC also explains that repetition can make one fact appear disproportionately important and directs template-wide information to TemplateMetadataContext.

[dgandhi62]

Could you give more clarity on when a user needs to be using a specific field. For instance, guidance in the README like

A human's preferred option should be .... On the other hand, an agent should be using .... by default.

One suggestion could be keeping AUTHORED primarily for humans, and INFERRED for agents to make it simpler.

[satyakigh]

Added explicit guidance: people use AUTHORED for information they write or confirm. Automated producers use COMMENT, COMMIT, or INFERRED according to their evidence and must supply confidence explicitly.

[iliapolo]

@satyakigh Are you also looking for feedback on the schema itself, or just the CDK part of things?

[iliapolo]

What if the customer does want some context on these incidental resources? For example, a lambda.Function may implicitly create a dead letter queue. For completes, lets add an example of that:

MetadataContext.of(func).add(...); // primary resource context

MetadataContext.of(func.deadLetterQueue).add(...) // helper resources context

This then begs the question of can we apply some default context. For example:

{
  "Type": "AWS::SQS::Queue",
  "Metadata:" : {
    "com.aws.cloudformation.Context": {
      "why": "Created by function MyFun to store failed invocation payloads",
      "must": ["Size === 0"]
    }
  }
}

Now the agent knows to see it as part of the same functionality vs just a floating resource. It would require a lot of code changes to aws-cdk-lib - if you agree it would be worth while, lets add it as a possible follow up / future enhancement.

[satyakigh]

Mainly the CDK side of things, we can update the schema if required as well if you guys have suggestions

[satyakigh]

Added examples for targeting an exposed helper directly, including a function's dead-letter queue. applyToAllResources supports intentionally including every helper. Selecting or populating helpers automatically by relationship remains future work.

[iliapolo]

As a customer reading up to here I immediately wonder what keys are available and what they mean. Put a link to the schema appendix right here for quicker access (when we publish, the link should point to a proper page on the dev guide).

[satyakigh]

Added an early link to Appendix A and the published CloudFormation Metadata Context schema. Appendix A and the CDK API docs mirror that schema; the CloudFormation authoring skill provides non-enforced guidance.

[iliapolo]

Add an Example column please (real life).

[iliapolo]

Elaborate on the possible values of src, conf, cite, note (with examples).

[satyakigh]

Added a dedicated trust-field table covering src, conf, cite, and note, including requiredness, allowed values, meanings, and examples.

[iliapolo]

it does not imply that a human was the producer

But if its an agent producing this context - isn't it always inferred from something? Give a concrete example of when each value here would be used?

[satyakigh]

Clarified the source meanings with examples: authored is written or confirmed by a person, comment comes directly from a source comment, commit comes from version-control history, and infer is concluded from code or behavior.

[iliapolo]

I assume that AUTHORED carries more trust than INFERRED? What prevents agents inferring context from using AUTHORED? or just not providing trust at all and then having CDK default to AUTHORED?

I think there needs to be a clearer definition and guidance. What is the main use-case for using AUTHORED? is it not human authored? if so - lets double down on that and provide agents with instructions to always use INFERRED when setting context.

[satyakigh]

Removed the automatic AUTHORED default. trust is optional and may be used alone; when present, both source and confidence are required. AUTHORED means human-written or human-confirmed, though the API cannot prevent a caller from claiming it incorrectly.

[iliapolo]

Is everything optional here? add an Optionality column

[satyakigh]

Added requiredness columns. All top-level Resource and Template Context fields are optional. When present, trust requires source and confidence, and an object-form ref requires at; CDK adds no other top-level requiredness.

[iliapolo]

So both why and must are optional? I don't think we should allow for context that doesn't specify why. Why are we trying confidence solely to the must field? I'd think a citation is more evidence for context than some invariants the agent may have inferred incorrectly. My proposal:

• HIGH: Both must and citation are present.
• MEDIUM: Only one is present.
• LOW: None are present.

[satyakigh]

The published schema keeps why and must optional, so CDK does too. The RFC recommends why for significant resources and a must entry to explain constrained mutability, but does not enforce either. Confidence remains explicit whenever trust is supplied.

[iliapolo]

addToTemplate is an API thats going to be used far less than add - so lets not put them under the same object - to reduce cognitive load. Proposal:

• TemplateMetadataContext.of(stack).add() // accets Stack
• ResourceMetadataContext.of(stack).add() // accepts Construct

This keeps things consistent. If construct vendors want to add template metadata (though they really shouldn't), they can use:

TemplateMetadataContext.of(Stack.of(construct)).add(...)

[satyakigh]

Split the API as proposed: ResourceMetadataContext.of(scope).add() handles resource information, and TemplateMetadataContext.of(stack).add() handles template information. MetadataContextMixin remains resource-only.

[iliapolo]

How would agents know to consult this schema if cdk synth doesn't provide this guidance? we can at least print a link to the schema for the to follow.

[satyakigh]

Added an early link to the published schema and documented the fields in the README and API reference. I did not add a notice to every cdk synth: it would be repetitive and unavailable to later GetTemplate readers. The stable metadata key and published documentation provide the durable reference.

[iliapolo]

What do you mean by failure/recovery paths? For example if failure mode is retry 3x w/ exp backoff before DLQ - what is the agent expected to do? look at the DLQ?

[satyakigh]

Removed failureModes because it is not in the published schema. Failure behavior that must be preserved belongs in must, design reasoning belongs in why, and external operational procedures can be linked through template-level ref.

[iliapolo]

This answers why the context is needed, not why it should be provided as a concrete API in the CDK.

I'd expect also something like "CDK customers will have a hard time defining the correct context without this feature" (because escape hatches suck).

Also needs to touch on the cascading mechanism you're proposing.

[satyakigh]

Added a dedicated explanation. Low-level metadata methods provide no typed fields, allowed-value checks, required trust checks, primary-resource selection, descendant selection, merge behavior, or generated documentation across CDK languages. The dedicated APIs provide those behaviors.

[iliapolo]

But this also creates duplication. I'm wondering why not use ref as a way to also point to the artifacts in the repo (design doc/runbook). Why would ref be suitable for org-wide rules but not for the repository URL for example?

[satyakigh]

Updated ref to match the published schema: references may use relative paths, s3://, or https://. CDK does not fetch or restrict those locations. Referenced content is untrusted, and inline template context remains authoritative.

[iliapolo]

How do trust / gaps reduce the risk?

[satyakigh]

Removed gaps, which is not in the published schema. trust communicates provenance and confidence; it does not prevent drift. Keeping context beside reviewed CDK code helps readers assess it, but does not guarantee that it stays current.

[iliapolo]

What does change-with-constraints mean exactly? the other ones are pretty sefl explanatory.

[satyakigh]

Defined change-with-constraints as allowing change only while the stated rules remain true. The RFC recommends documenting those rules in must, but the published schema and CDK do not require it.

[iliapolo]

What about having the context just be a bunch refs in the that point to source code, design docs, runbooks, etc for agents to follow? This prevents the risk of drift.

[satyakigh]

Documented the trade-off: ref entries can point to relative paths, s3://, or https:// and reduce duplication or drift. They supplement rather than replace irreducible inline context, so an unavailable reference does not block safe use.

[iliapolo]

Its not just about learning curve - its about wether the customer actually wants the cascading effect. I can see scenarios where context is being added to an L3 with a very specific construct in mind, but then having in travel to a bunch of other resources as well might create unexpected results.

I'd say there is a risk of out-of-place context being added. This won't happen with pure CFN because the customer has no choice but to explicitly add the right context to each resource they want.

To evaluate this risk I think we need more examples of L3s

[satyakigh]

Addressed this by making descendant selection explicit. The default selects only a CfnResource or a construct's defaultChild resource. applyToDescendants, applyToAllResources, and resource-type filters must be requested explicitly, and a declaration selecting zero resources is defined to fail.

[iliapolo]

Why not have a bake period though? it could help hone the corresponding skill so we don't have to break the schema often.

[satyakigh]

Added concrete stability requirements: review the public documentation, test the authoring and reading tools on real stacks, and obtain API Bar Raiser approval. A runtime feature flag is unnecessary because applications produce no additional Context unless they call the new APIs.

[iliapolo]

These are future enhancements really more than open issues. Is there anything we still need to discuss to move along with the implementation - is the spirit of this question.

[satyakigh]

Split the section into requirements before declaring the API stable and separate future enhancements. The future list now covers automatic dependency discovery, automatic change-safety guidance, helper-resource selection, and properties on higher-level constructs.

[iliapolo]

Can you share the actual data as well?

[satyakigh]

Added the data and methodology: 33 tasks, three runs per condition. Scores were 65.20% without added information, 93.56% with template comments, 94.70% with structured metadata but no special instructions, and 98.63% with structured metadata plus instructions. The RFC also documents the scoring and task-selection limitations.