konokenj.cdk-api-mcp-server 0.31.0__py3-none-any.whl → 0.57.0__py3-none-any.whl

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/aws-dynamodb/README.md

@@ -17,7 +17,9 @@ By default, `TableV2` will create a single table in the main deployment region r
 ```ts
 const table = new dynamodb.TableV2(this, 'Table', {
   partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
-  contributorInsights: true,
+  contributorInsightsSpecification: {
+    enabled: true,
+  },
   tableClass: dynamodb.TableClass.STANDARD_INFREQUENT_ACCESS,
   pointInTimeRecoverySpecification: {
     pointInTimeRecoveryEnabled: true,
@@ -66,12 +68,12 @@ globalTable.addReplica({ region: 'us-east-2', deletionProtection: true });
 ```
 
 The following properties are configurable on a per-replica basis, but will be inherited from the `TableV2` properties if not specified:
-* contributorInsights
+* contributorInsightsSpecification
 * deletionProtection
 * pointInTimeRecoverySpecification
 * tableClass
 * readCapacity (only configurable if the `TableV2` billing mode is `PROVISIONED`)
-* globalSecondaryIndexes (only `contributorInsights` and `readCapacity`)
+* globalSecondaryIndexes (only `contributorInsightsSpecification` and `readCapacity`)
 
 The following example shows how to define properties on a per-replica basis:
 
@@ -83,7 +85,9 @@ const stack = new cdk.Stack(app, 'Stack', { env: { region: 'us-west-2' } });
 
 const globalTable = new dynamodb.TableV2(stack, 'GlobalTable', {
   partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
-  contributorInsights: true,
+  contributorInsightsSpecification: {
+    enabled: true,
+  },
   pointInTimeRecoverySpecification: {
       pointInTimeRecoveryEnabled: true,
   },
@@ -97,7 +101,9 @@ const globalTable = new dynamodb.TableV2(stack, 'GlobalTable', {
     },
     {
       region: 'us-east-2',
-      contributorInsights: false,
+      contributorInsightsSpecification: {
+        enabled: false,
+      },
     },
   ],
 });
@@ -150,6 +156,68 @@ const barStack = new BarStack(app, 'BarStack', {
 
 Note: You can create an instance of the `TableV2` construct with as many `replicas` as needed as long as there is only one replica per region. After table creation you can add or remove `replicas`, but you can only add or remove a single replica in each update.
 
+## Multi-Region Strong Consistency (MRSC)
+
+By default, DynamoDB global tables provide eventual consistency across regions. For applications requiring strong consistency across regions, you can configure Multi-Region Strong Consistency (MRSC) using the `multiRegionConsistency` property.
+
+MRSC global tables can be configured in two ways:
+* **Three replicas**: Deploy your table across three regions within the same region set
+* **Two replicas + one witness**: Deploy your table across two regions with a witness region for consensus
+
+### Region Sets
+
+MRSC global tables must be deployed within the same region set. The supported region sets are:
+
+* **US Region set**: `us-east-1`, `us-east-2`, `us-west-2`
+* **EU Region set**: `eu-west-1`, `eu-west-2`, `eu-west-3`, `eu-central-1`  
+* **AP Region set**: `ap-northeast-1`, `ap-northeast-2`, `ap-northeast-3`
+
+### Three Replicas Configuration
+
+```ts
+import * as cdk from 'aws-cdk-lib';
+
+const app = new cdk.App();
+const stack = new cdk.Stack(app, 'Stack', { env: { region: 'us-west-2' } });
+
+const mrscTable = new dynamodb.TableV2(stack, 'MRSCTable', {
+  partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
+  multiRegionConsistency: dynamodb.MultiRegionConsistency.STRONG,
+  replicas: [
+    { region: 'us-east-1' },
+    { region: 'us-east-2' },
+  ],
+});
+```
+
+### Two Replicas + Witness Configuration
+
+```ts
+import * as cdk from 'aws-cdk-lib';
+
+const app = new cdk.App();
+const stack = new cdk.Stack(app, 'Stack', { env: { region: 'us-west-2' } });
+
+const mrscTable = new dynamodb.TableV2(stack, 'MRSCTable', {
+  partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
+  multiRegionConsistency: dynamodb.MultiRegionConsistency.STRONG,
+  replicas: [
+    { region: 'us-east-1' },
+  ],
+  witnessRegion: 'us-east-2',
+});
+```
+
+### Important Considerations
+
+* **Witness regions** can only be used with `MultiRegionConsistency.STRONG`. Attempting to specify a witness region with eventual consistency will result in a validation error.
+* **Region validation**: All regions (primary, replicas, and witness) must be within the same region set.
+* **Replica count**: When using a witness region, you must have exactly 2 replicas (including the primary). Without a witness region, you must have exactly 3 replicas.
+* **Performance**: MRSC provides strong consistency but may have higher latency compared to eventual consistency.
+
+Further reading:
+https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/V2globaltables_HowItWorks.html#V2globaltables_HowItWorks.consistency-modes-mrsc
+
 ## Billing
 
 The `TableV2` construct can be configured with on-demand or provisioned billing:
@@ -313,7 +381,7 @@ https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-mgmt
 
 Secondary indexes allow efficient access to data with attributes other than the `primaryKey`. DynamoDB supports two types of secondary indexes:
 
-* Global secondary index - An index with a `partitionKey` and a `sortKey` that can be different from those on the base table. A `globalSecondaryIndex` is considered "global" because queries on the index can span all of the data in the base table, across all partitions. A `globalSecondaryIndex` is stored in its own partition space away from the base table and scales separately from the base table.
+* Global secondary index - An index with partition key(s) and optional sort key(s) that can be different from those on the base table. A `globalSecondaryIndex` is considered "global" because queries on the index can span all of the data in the base table, across all partitions. A `globalSecondaryIndex` is stored in its own partition space away from the base table and scales separately from the base table.
 
 * Local secondary index - An index that has the same `partitionKey` as the base table, but a different `sortKey`. A `localSecondaryIndex` is "local" in the sense that every partition of a `localSecondaryIndex` is scoped to a base table partition that has the same `partitionKey` value.
 
@@ -336,7 +404,41 @@ const table = new dynamodb.TableV2(this, 'Table', {
 });
 ```
 
-Alternatively, you can add a `globalSecondaryIndex` using the `addGlobalSecondaryIndex` method:
+#### Compound Keys
+
+Global secondary indexes support compound keys, allowing you to specify multiple partition keys and/or multiple sort keys. This enables more flexible query patterns for complex data models.
+
+**Key Constraints:**
+- You can specify up to **4 partition keys** per global secondary index
+- You can specify up to **4 sort keys** per global secondary index
+- Use **either** `partitionKey` (singular) **or** `partitionKeys` (plural), but not both
+- Use **either** `sortKey` (singular) **or** `sortKeys` (plural), but not both
+- At least one partition key must be specified (either `partitionKey` or `partitionKeys`)
+- For multiple keys, you **must** use the plural parameters (`partitionKeys` and/or `sortKeys`)
+- **Keys cannot be added or modified after index creation** - attempting to add additional keys to an existing index will result in an error
+
+**Example with compound partition and sort keys:**
+
+```ts
+const table = new dynamodb.TableV2(this, 'Table', {
+  partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
+  globalSecondaryIndexes: [
+    {
+      indexName: 'compound-gsi',
+      partitionKeys: [
+        { name: 'gsi_pk1', type: dynamodb.AttributeType.STRING },
+        { name: 'gsi_pk2', type: dynamodb.AttributeType.NUMBER },
+      ],
+      sortKeys: [
+        { name: 'gsi_sk1', type: dynamodb.AttributeType.STRING },
+        { name: 'gsi_sk2', type: dynamodb.AttributeType.BINARY },
+      ],
+    },
+  ],
+});
+```
+
+You can also add a `globalSecondaryIndex` using the `addGlobalSecondaryIndex` method:
 
 ```ts
 const table = new dynamodb.TableV2(this, 'Table', {
@@ -353,6 +455,16 @@ table.addGlobalSecondaryIndex({
   indexName: 'gsi2',
   partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
 });
+
+// Add a GSI with compound keys
+table.addGlobalSecondaryIndex({
+  indexName: 'compound-gsi2',
+  partitionKeys: [
+    { name: 'compound_pk1', type: dynamodb.AttributeType.STRING },
+    { name: 'compound_pk2', type: dynamodb.AttributeType.NUMBER },
+  ],
+  sortKey: { name: 'sk', type: dynamodb.AttributeType.STRING },
+});
 ```
 
 You can configure `readCapacity` and `writeCapacity` on a `globalSecondaryIndex` when an `TableV2` is configured with provisioned `billing`. If `TableV2` is configured with provisioned `billing` but `readCapacity` or `writeCapacity` are not configured on a `globalSecondaryIndex`, then they will be inherited from the capacity settings specified with the `billing` configuration:
@@ -381,7 +493,7 @@ const table = new dynamodb.TableV2(this, 'Table', {
 });
 ```
 
-All `globalSecondaryIndexes` for replica tables are inherited from the primary table. You can configure `contributorInsights` and `readCapacity` for each `globalSecondaryIndex` on a per-replica basis:
+All `globalSecondaryIndexes` for replica tables are inherited from the primary table. You can configure `contributorInsightsSpecification` and `readCapacity` for each `globalSecondaryIndex` on a per-replica basis:
 
 ```ts
 import * as cdk from 'aws-cdk-lib';
@@ -391,7 +503,9 @@ const stack = new cdk.Stack(app, 'Stack', { env: { region: 'us-west-2' } });
 
 const globalTable = new dynamodb.TableV2(stack, 'GlobalTable', {
   partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
-  contributorInsights: true,
+  contributorInsightsSpecification: {
+    enabled: true,
+  },
   billing: dynamodb.Billing.provisioned({
     readCapacity: dynamodb.Capacity.fixed(10),
     writeCapacity: dynamodb.Capacity.autoscaled({ maxCapacity: 10 }),
@@ -422,7 +536,9 @@ const globalTable = new dynamodb.TableV2(stack, 'GlobalTable', {
       region: 'us-east-2',
       globalSecondaryIndexOptions: {
         gsi2: {
-          contributorInsights: false,
+          contributorInsightsSpecification: {
+            enabled: false,
+          },
         },
       },
     },
@@ -543,25 +659,40 @@ const table = new dynamodb.TableV2(this, 'Table', {
 
 ## Contributor Insights
 
-Enabling `contributorInsights` for `TableV2` will provide information about the most accessed and throttled items in a table or `globalSecondaryIndex`. DynamoDB delivers this information to you via CloudWatch Contributor Insights rules, reports, and graphs of report data.
+Enabling `contributorInsightSpecification` for `TableV2` will provide information about the most accessed and throttled or throttled only items in a table or `globalSecondaryIndex`. DynamoDB delivers this information to you via CloudWatch Contributor Insights rules, reports, and graphs of report data.
+
+By default, Contributor Insights for DynamoDB monitors all requests, including both the most accessed and most throttled items.  
+To limit the scope to only the most accessed or only the most throttled items, use the optional `mode` parameter.
+
+- To monitor all traffic on a table or index, set `mode` to `ContributorInsightsMode.ACCESSED_AND_THROTTLED_KEYS`.
+- To monitor only throttled traffic on a table or index, set `mode` to `ContributorInsightsMode.THROTTLED_KEYS`. 
+
 
 ```ts
 const table = new dynamodb.TableV2(this, 'Table', {
   partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
-  contributorInsights: true,
+  contributorInsightsSpecification: {
+    enabled: true,
+    mode: dynamodb.ContributorInsightsMode.ACCESSED_AND_THROTTLED_KEYS,
+  },
 });
 ```
 
-When you use `Table`, you can enable contributor insights for a table or specific global secondary index by setting `contributorInsightsEnabled` to `true`.
+When you use `Table`, you can enable contributor insights for a table or specific global secondary index by setting `contributorInsightsSpecification` parameter `enabled` to `true`.
 
 ```ts
 const table = new dynamodb.Table(this, 'Table', {
   partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
-  contributorInsightsEnabled: true, // for a table
+  contributorInsightsSpecification: { // for a table
+    enabled: true,
+    mode: dynamodb.ContributorInsightsMode.THROTTLED_KEYS, // only emit throttling events
+  },
 });
 
 table.addGlobalSecondaryIndex({
-  contributorInsightsEnabled: true, // for a specific global secondary index
+  contributorInsightsSpecification: { // for a specific global secondary index
+    enabled: true,
+  },
   indexName: 'gsi',
   partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
 });
@@ -729,9 +860,88 @@ Using `resourcePolicy` you can add a [resource policy](https://docs.aws.amazon.c
     });
 ```
 
+### Adding Resource Policy Statements Dynamically
+
+You can also add resource policy statements to a table after it's created using the `addToResourcePolicy` method. Following the same pattern as KMS, resource policies use wildcard resources to avoid circular dependencies:
+
+```ts
+const table = new dynamodb.TableV2(this, 'Table', {
+  partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
+});
+
+// Standard resource policy (recommended approach)
+table.addToResourcePolicy(new iam.PolicyStatement({
+  actions: ['dynamodb:GetItem', 'dynamodb:PutItem', 'dynamodb:Query'],
+  principals: [new iam.AccountRootPrincipal()],
+  resources: ['*'], // Wildcard avoids circular dependency - same pattern as KMS
+}));
+
+// Allow specific service access
+table.addToResourcePolicy(new iam.PolicyStatement({
+  actions: ['dynamodb:Query'],
+  principals: [new iam.ServicePrincipal('lambda.amazonaws.com')],
+  resources: ['*'],
+}));
+```
+
+#### Scoped Resource Policies (Advanced)
+
+For scoped resource policies that reference specific table ARNs, you must specify an explicit table name:
+
+```ts
+import { Fn } from 'aws-cdk-lib';
+
+// Table with explicit name enables scoped resource policies
+const table = new dynamodb.TableV2(this, 'Table', {
+  tableName: 'my-explicit-table-name', // Required for scoped resources
+  partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
+});
+
+// Now you can use scoped resources
+table.addToResourcePolicy(new iam.PolicyStatement({
+  actions: ['dynamodb:GetItem'],
+  principals: [new iam.AccountRootPrincipal()],
+  resources: [
+    Fn.sub('arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/my-explicit-table-name'),
+    Fn.sub('arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/my-explicit-table-name/index/*'),
+  ],
+}));
+```
+
+**Important Limitations:**
+- **Auto-generated table names**: Must use `resources: ['*']` to avoid circular dependencies
+- **Explicit table names**: Enable scoped resources but lose CDK's automatic naming benefits
+- **CloudFormation constraint**: Resource policies cannot reference the resource they're attached to during creation
+
 TableV2 doesn’t support creating a replica and adding a resource-based policy to that replica in the same stack update in Regions other than the Region where you deploy the stack update.
 To incorporate a resource-based policy into a replica, you'll need to initially deploy the replica without the policy, followed by a subsequent update to include the desired policy.
 
+### Grant Methods and Resource Policies
+
+Grant methods like `grantReadData()`, `grantWriteData()`, and `grantReadWriteData()` automatically add permissions to resource policies when used with same-account principals (like `AccountRootPrincipal`). This happens transparently:
+
+```ts
+const table = new dynamodb.TableV2(this, 'Table', {
+  partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
+});
+
+// Automatically adds to table's resource policy (same account)
+table.grantReadData(new iam.AccountRootPrincipal());
+
+// Adds to IAM user's policy (not resource policy)
+declare const user: iam.User;
+table.grantReadData(user);
+```
+
+**How it works:**
+- **Same-account principals** (AccountRootPrincipal, AccountPrincipal): Grant adds statement to table's resource policy
+- **IAM identities** (User, Role, Group): Grant adds statement to the identity's IAM policy
+- **Resource policy statements**: Automatically use wildcard resources (`*`) to avoid circular dependencies
+
+This behavior follows the same pattern as other AWS services like KMS and S3, where grants intelligently choose between resource policies and identity policies based on the principal type.
+
+**To avoid wildcards in resource policies:** If you need scoped resource ARNs instead of wildcards, use `addToResourcePolicy()` directly with an explicit table name instead of grant methods. See the "Scoped Resource Policies (Advanced)" section above for details.
+
 ## Grants
 
 Using any of the `grant*` methods on an instance of the `TableV2` construct will only apply to the primary table, its indexes, and any associated `encryptionKey`. As an example, `grantReadData` used below will only apply the table in `us-west-2`:

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/aws-dynamodb/TABLE_V1_API.md

@@ -210,12 +210,55 @@ To get the partition key and sort key of the table or indexes you have configure
 
 ```ts
 declare const table: dynamodb.Table;
+
+// For single keys, use schema() (deprecated for compound keys)
 const schema = table.schema();
 const partitionKey = schema.partitionKey;
 const sortKey = schema.sortKey;
 
-// In case you want to get schema details for any secondary index
-// const { partitionKey, sortKey } = table.schema(INDEX_NAME);
+// For compound keys, use schemaV2() which returns normalized arrays
+const schemaV2 = table.schemaV2();
+const partitionKeys = schemaV2.partitionKeys; // Attribute[]
+const sortKeys = schemaV2.sortKeys; // Attribute[]
+
+// Get schema for a specific index
+const indexSchema = table.schemaV2('INDEX_NAME');
+```
+
+Note: `schema()` is deprecated for indexes with compound keys and will throw an error. Use `schemaV2()` instead, which always returns normalized arrays.
+
+## Global Secondary Indexes with Compound Keys
+
+Global secondary indexes support compound keys, allowing you to specify multiple partition keys and/or multiple sort keys. This enables more flexible query patterns for complex data models.
+
+**Key Constraints:**
+- You can specify up to **4 partition keys** per global secondary index
+- You can specify up to **4 sort keys** per global secondary index
+- Use **either** `partitionKey` (singular) **or** `partitionKeys` (plural), but not both
+- Use **either** `sortKey` (singular) **or** `sortKeys` (plural), but not both
+- At least one partition key must be specified (either `partitionKey` or `partitionKeys`)
+- For multiple keys, you **must** use the plural parameters (`partitionKeys` and/or `sortKeys`)
+- **Keys cannot be added or modified after index creation** - attempting to add additional keys to an existing index will result in an error
+
+**Example:**
+
+```ts
+const table = new dynamodb.Table(this, 'Table', {
+  partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
+  sortKey: { name: 'sk', type: dynamodb.AttributeType.STRING },
+});
+
+table.addGlobalSecondaryIndex({
+  indexName: 'compound-gsi',
+  partitionKeys: [
+    { name: 'gsi_pk1', type: dynamodb.AttributeType.STRING },
+    { name: 'gsi_pk2', type: dynamodb.AttributeType.NUMBER },
+  ],
+  sortKeys: [
+    { name: 'gsi_sk1', type: dynamodb.AttributeType.STRING },
+    { name: 'gsi_sk2', type: dynamodb.AttributeType.BINARY },
+  ],
+});
 ```
 
 ## Kinesis Stream

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/aws-dynamodb/integ.dynamodb-v2.cci.ts

@@ -0,0 +1,49 @@
+import { App, Stack, StackProps } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
+import { IntegTest } from '@aws-cdk/integ-tests-alpha';
+
+const app = new App();
+
+class TestStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    new dynamodb.TableV2(this, 'TableV2', {
+      partitionKey: { name: 'hashKey', type: dynamodb.AttributeType.STRING },
+      sortKey: { name: 'sortKey', type: dynamodb.AttributeType.NUMBER },
+      globalSecondaryIndexes: [
+        {
+          indexName: 'gsi',
+          partitionKey: { name: 'gsiHashKey', type: dynamodb.AttributeType.STRING },
+        },
+      ],
+      contributorInsightsSpecification: {
+        enabled: true,
+        mode: dynamodb.ContributorInsightsMode.ACCESSED_AND_THROTTLED_KEYS,
+      },
+      replicas: [
+        {
+          region: 'eu-west-2',
+          contributorInsightsSpecification: {
+            enabled: false,
+          },
+          globalSecondaryIndexOptions: {
+            gsi: {
+              contributorInsightsSpecification: {
+                enabled: true,
+                mode: dynamodb.ContributorInsightsMode.THROTTLED_KEYS,
+              },
+            },
+          },
+        },
+      ],
+    });
+  }
+}
+
+const stack = new TestStack(app, 'CCI-Integ-Test', { env: { region: 'eu-west-1' } });
+
+new IntegTest(app, 'table-v2-CCI-test', {
+  testCases: [stack],
+});

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/aws-dynamodb/integ.dynamodb.add-to-resource-policy.ts

@@ -0,0 +1,97 @@
+/**
+ * Integration test for DynamoDB Table.addToResourcePolicy() method
+ *
+ * This test validates the fix for issue #35062: "(aws-dynamodb): `addToResourcePolicy` has no effect"
+ *
+ * WHAT WE'RE TESTING:
+ * - The addToResourcePolicy() method was broken - it had "no effect" when called
+ * - Resource policies weren't being added to the CloudFormation template
+ * - This created a security gap where developers thought they were securing tables but policies weren't applied
+ *
+ * TEST VALIDATION:
+ * 1. Creates DynamoDB tables with different resource policy configurations
+ * 2. Tests both wildcard resources (for auto-generated names) and scoped resources (for explicit names)
+ * 3. Verifies policies get added to CloudFormation templates with correct structure
+ * 4. Ensures both patterns work without circular dependencies
+ *
+ * @see https://github.com/aws/aws-cdk/issues/35062
+ */
+
+import { App, Fn, RemovalPolicy, Stack, StackProps } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import { IntegTest } from '@aws-cdk/integ-tests-alpha';
+
+export class TestStack extends Stack {
+  public readonly wildcardTable: dynamodb.Table;
+  public readonly scopedTable: dynamodb.Table;
+  public readonly grantTable: dynamodb.Table;
+
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    // TEST 1: Table with wildcard resource policy (auto-generated name)
+    // This is the standard pattern to avoid circular dependencies
+    this.wildcardTable = new dynamodb.Table(this, 'WildcardTable', {
+      partitionKey: {
+        name: 'id',
+        type: dynamodb.AttributeType.STRING,
+      },
+      removalPolicy: RemovalPolicy.DESTROY,
+    });
+
+    // Add resource policy with wildcard resources
+    this.wildcardTable.addToResourcePolicy(new iam.PolicyStatement({
+      actions: ['dynamodb:GetItem', 'dynamodb:PutItem', 'dynamodb:Query'],
+      principals: [new iam.AccountRootPrincipal()],
+      resources: ['*'], // Use wildcard to avoid circular dependency - standard pattern for resource policies
+    }));
+
+    // TEST 2: Table with scoped resource policy (explicit table name)
+    // This demonstrates how to use scoped resources when table name is known at synthesis time
+    this.scopedTable = new dynamodb.Table(this, 'ScopedTable', {
+      tableName: 'my-explicit-scoped-table', // Explicit name enables scoped ARN construction
+      partitionKey: {
+        name: 'id',
+        type: dynamodb.AttributeType.STRING,
+      },
+      removalPolicy: RemovalPolicy.DESTROY,
+    });
+
+    // Add resource policy with properly scoped resource using explicit table name
+    // This works because table name is known at synthesis time (no circular dependency)
+    this.scopedTable.addToResourcePolicy(new iam.PolicyStatement({
+      actions: ['dynamodb:GetItem', 'dynamodb:Query'],
+      principals: [new iam.AccountRootPrincipal()],
+      // Use CloudFormation intrinsic function to construct table ARN with known table name
+      resources: [Fn.sub('arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/my-explicit-scoped-table')],
+    }));
+
+    // TEST 3: Table using grant methods with AccountRootPrincipal
+    // This validates the fix for issue #35967: circular dependency when using grant methods
+    // Before fix: grant methods with AccountRootPrincipal caused circular dependency
+    // After fix: grant methods use resourceSelfArns: ['*'] to avoid circular dependency
+    this.grantTable = new dynamodb.Table(this, 'GrantTable', {
+      partitionKey: {
+        name: 'id',
+        type: dynamodb.AttributeType.STRING,
+      },
+      removalPolicy: RemovalPolicy.DESTROY,
+    });
+
+    // This should NOT cause circular dependency - validates fix for #35967
+    // Using grantWriteData because it has simpler actions valid for resource policies
+    this.grantTable.grantWriteData(new iam.AccountRootPrincipal());
+  }
+}
+
+// Test Setup
+const app = new App();
+const stack = new TestStack(app, 'add-to-resource-policy-test-stack');
+
+// Integration Test Configuration
+new IntegTest(app, 'add-to-resource-policy-integ-test', {
+  testCases: [stack],
+});
+

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/aws-dynamodb/integ.dynamodb.cci.ts

@@ -0,0 +1,27 @@
+import { App, Stack, StackProps } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
+import { IntegTest } from '@aws-cdk/integ-tests-alpha';
+
+const app = new App();
+
+class TestStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    new dynamodb.Table(this, 'TableV2', {
+      partitionKey: { name: 'hashKey', type: dynamodb.AttributeType.STRING },
+      sortKey: { name: 'sortKey', type: dynamodb.AttributeType.NUMBER },
+      contributorInsightsSpecification: {
+        enabled: true,
+        mode: dynamodb.ContributorInsightsMode.ACCESSED_AND_THROTTLED_KEYS,
+      },
+    });
+  }
+}
+
+const stack = new TestStack(app, 'CCI-Integ-Test-TableV1', { env: { region: 'eu-west-1' } });
+
+new IntegTest(app, 'table-v1-CCI-test', {
+  testCases: [stack],
+});

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/aws-dynamodb/integ.dynamodb.compound.ts

@@ -0,0 +1,32 @@
+import { App, RemovalPolicy, Stack } from 'aws-cdk-lib';
+import { AttributeType, ProjectionType, Table } from 'aws-cdk-lib/aws-dynamodb';
+import { IntegTest } from '@aws-cdk/integ-tests-alpha';
+
+const app = new App();
+const stack = new Stack(app, 'aws-cdk-dynamodb-compound-keys');
+
+const table = new Table(stack, 'Table', {
+  tableName: 'cdk-test-compound',
+  partitionKey: { name: 'pkey', type: AttributeType.NUMBER },
+  removalPolicy: RemovalPolicy.DESTROY,
+});
+
+table.addGlobalSecondaryIndex({
+  indexName: 'IndexA',
+  partitionKeys: [{ name: 'PK1', type: AttributeType.STRING }, { name: 'PK2', type: AttributeType.NUMBER }],
+  sortKeys: [{ name: 'SK1', type: AttributeType.STRING }, { name: 'SK2', type: AttributeType.NUMBER }],
+  projectionType: ProjectionType.INCLUDE,
+  nonKeyAttributes: ['bar'],
+});
+
+table.addGlobalSecondaryIndex({
+  indexName: 'IndexB',
+  partitionKey: { name: 'baz', type: AttributeType.STRING },
+  sortKeys: [{ name: 'bar', type: AttributeType.STRING }, { name: 'foo', type: AttributeType.NUMBER }],
+  projectionType: ProjectionType.INCLUDE,
+  nonKeyAttributes: ['blah'],
+});
+
+new IntegTest(app, 'aws-cdk-dynamodb-compound-key-gsi', {
+  testCases: [stack],
+});

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/aws-dynamodb/integ.dynamodb.contirubtor-insights-for-gsi.ts

@@ -24,12 +24,16 @@ const table = new Table(stack, TABLE, {
 });
 
 table.addGlobalSecondaryIndex({
-  contributorInsightsEnabled: true,
+  contributorInsightsSpecification: {
+    enabled: true,
+  },
   indexName: GSI_TEST_CASE_1,
   partitionKey: GSI_PARTITION_KEY,
 });
 table.addGlobalSecondaryIndex({
-  contributorInsightsEnabled: false,
+  contributorInsightsSpecification: {
+    enabled: false,
+  },
   indexName: GSI_TEST_CASE_2,
   partitionKey: GSI_PARTITION_KEY,
 });

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/aws-dynamodb/integ.dynamodb.policy.ts

@@ -38,7 +38,27 @@ export class TestStack extends Stack {
       removalPolicy: RemovalPolicy.DESTROY,
     });
 
-    this.tableTwo.grantReadData(new iam.AccountPrincipal('123456789012'));
+    // IMPORTANT: Cross-account grants with auto-generated table names create circular dependencies
+    //
+    // WHY NOT this.tableTwo.grantReadData(new iam.AccountPrincipal('123456789012'))?
+    // - Cross-account principals cannot have policies attached to them
+    // - Grant falls back to adding a resource policy to the table
+    // - Resource policy tries to reference this.tableArn (the table's own ARN)
+    // - This creates a circular dependency: Table → ResourcePolicy → Table ARN → Table
+    // - CloudFormation fails with "Circular dependency between resources"
+    //
+    // SOLUTIONS:
+    // 1. Use addToResourcePolicy with wildcard resources (this approach)
+    // 2. Use explicit table names: tableName: 'my-table-name' (enables scoped resources)
+    // 3. Use same-account principals (grants go to principal policy, not resource policy)
+    //
+    this.tableTwo.addToResourcePolicy(new iam.PolicyStatement({
+      actions: ['dynamodb:*'],
+      // we need a valid account for cross-account principal otherwise it won't deploy
+      // this account is from fact-table.ts
+      principals: [new iam.AccountPrincipal('127311923021')],
+      resources: ['*'], // Wildcard avoids circular dependency - same pattern as KMS
+    }));
   }
 }