feat: add DSL markers to codegenned structure builders

.changes/19208b1c-8c36-452b-a6e3-e0bef345776a.json

@@ -0,0 +1,8 @@
+{
+    "id": "19208b1c-8c36-452b-a6e3-e0bef345776a",
+    "type": "feature",
+    "description": "⚠️ **IMPORTANT**: Add new @SdkDsl DSL marker to all generated structure builders, clarifying DSL scopes when building complex types. See the [**Scope control applied to DSL builders** breaking change announcement](https://github.com/awslabs/aws-sdk-kotlin/discussions/1280) for more details.",
+    "issues": [
+        "awslabs/smithy-kotlin#428"
+    ]
+}

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/core/RuntimeTypes.kt

@@ -98,6 +98,7 @@ object RuntimeTypes {
         val fromEpochMilliseconds = symbol("fromEpochMilliseconds", "time")
         val TimestampFormat = symbol("TimestampFormat", "time")
         val ClientException = symbol("ClientException")
+        val SdkDsl = symbol("SdkDsl")
 
         object Collections : RuntimeTypePackage(KotlinDependency.CORE, "collections") {
             val Attributes = symbol("Attributes")

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/rendering/StructureGenerator.kt

@@ -223,6 +223,7 @@ class StructureGenerator(
 
     private fun renderBuilder() {
         writer.write("")
+            .write("@#T", RuntimeTypes.Core.SdkDsl)
             .withBlock("public class Builder {", "}") {
                 for (member in sortedMembers) {
                     val (memberName, memberSymbol) = memberNameSymbolIndex[member]!!

codegen/smithy-kotlin-codegen/src/test/kotlin/software/amazon/smithy/kotlin/codegen/rendering/StructureGeneratorTest.kt

@@ -184,6 +184,7 @@ class StructureGeneratorTest {
     @Test
     fun `it renders a builder impl`() {
         val expected = """
+            @SdkDsl
             public class Builder {
                 /**
                  * This *is* documentation about the member.

runtime/runtime-core/api/runtime-core.api

@@ -36,6 +36,9 @@ public class aws/smithy/kotlin/runtime/SdkBaseException : java/lang/RuntimeExcep
 	public fun getSdkErrorMetadata ()Laws/smithy/kotlin/runtime/ErrorMetadata;
 }
 
+public abstract interface annotation class aws/smithy/kotlin/runtime/SdkDsl : java/lang/annotation/Annotation {
+}
+
 public class aws/smithy/kotlin/runtime/ServiceErrorMetadata : aws/smithy/kotlin/runtime/ErrorMetadata {
 	public static final field Companion Laws/smithy/kotlin/runtime/ServiceErrorMetadata$Companion;
 	public fun <init> ()V

runtime/runtime-core/common/src/aws/smithy/kotlin/runtime/Annotations.kt

@@ -52,3 +52,9 @@ public annotation class InternalApi
     AnnotationTarget.CONSTRUCTOR,
 )
 public annotation class ExperimentalApi
+
+/**
+ * Signifies that a type is considered part of an SDK DSL for the purposes of scope control
+ */
+@DslMarker
+public annotation class SdkDsl