@aws/nx-plugin 1.0.0-rc.7 → 1.0.0-rc.70

package/src/py/dynamodb/__snapshots__/generator.spec.ts.snap

@@ -0,0 +1,1520 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`py#dynamodb generator > should generate scripts for finch engine 1`] = `
+"{
+  "runtimeConfigKey": "MyTable",
+  "localDev": {
+    "port": 8000,
+    "tableName": "proj-my-table",
+    "image": "public.ecr.aws/aws-dynamodb-local/aws-dynamodb-local:latest",
+    "containerName": "proj-dynamodb",
+    "containerEngine": "finch"
+  },
+  "tableConfig": {
+    "globalSecondaryIndexes": [
+      {
+        "indexName": "gsi1pk-gsi1sk-index",
+        "partitionKey": "gsi1pk",
+        "sortKey": "gsi1sk"
+      },
+      {
+        "indexName": "gsi2pk-gsi2sk-index",
+        "partitionKey": "gsi2pk",
+        "sortKey": "gsi2sk"
+      }
+    ]
+  }
+}
+"
+`;
+
+exports[`py#dynamodb generator > should generate terraform modules when iac is terraform 1`] = `
+"terraform {
+  required_version = ">= 1.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "6.58.0"
+    }
+  }
+}
+
+variable "name" {
+  description = "Name for the DynamoDB table."
+  type        = string
+}
+
+variable "billing_mode" {
+  description = "Controls how you are charged for read and write throughput."
+  type        = string
+  default     = "PAY_PER_REQUEST"
+}
+
+variable "point_in_time_recovery_enabled" {
+  description = "Whether to enable point-in-time recovery for the table."
+  type        = bool
+  default     = true
+}
+
+variable "deletion_protection_enabled" {
+  description = "Whether to enable deletion protection on the table."
+  type        = bool
+  default     = true
+}
+
+variable "enable_key_rotation" {
+  description = "Whether to enable automatic key rotation on the KMS key used to encrypt the table."
+  type        = bool
+  default     = true
+}
+
+variable "global_secondary_indexes" {
+  description = "Global secondary indexes to create on the table. All key attributes must be of type string."
+  type = list(object({
+    name            = string
+    hash_key        = string
+    range_key       = string
+    projection_type = string
+  }))
+  default = []
+}
+
+locals {
+  gsi_attribute_names = distinct(flatten([
+    for gsi in var.global_secondary_indexes : [gsi.hash_key, gsi.range_key]
+  ]))
+}
+
+data "aws_caller_identity" "current" {}
+data "aws_partition" "current" {}
+
+resource "aws_kms_key" "table" {
+  description         = "KMS key for DynamoDB table \${var.name}"
+  enable_key_rotation = var.enable_key_rotation
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Sid    = "EnableRootAccess"
+        Effect = "Allow"
+        Principal = {
+          AWS = "arn:\${data.aws_partition.current.partition}:iam::\${data.aws_caller_identity.current.account_id}:root"
+        }
+        Action   = "kms:*"
+        Resource = "*"
+      },
+      {
+        Sid    = "AllowDynamoDBService"
+        Effect = "Allow"
+        Principal = {
+          Service = "dynamodb.amazonaws.com"
+        }
+        Action = [
+          "kms:Encrypt",
+          "kms:Decrypt",
+          "kms:ReEncrypt*",
+          "kms:GenerateDataKey*",
+          "kms:DescribeKey",
+          "kms:CreateGrant"
+        ]
+        Resource = "*"
+      }
+    ]
+  })
+}
+
+resource "aws_dynamodb_table" "table" {
+  name                        = var.name
+  billing_mode                = var.billing_mode
+  hash_key                    = "pk"
+  range_key                   = "sk"
+  deletion_protection_enabled = var.deletion_protection_enabled
+
+  attribute {
+    name = "pk"
+    type = "S"
+  }
+
+  attribute {
+    name = "sk"
+    type = "S"
+  }
+
+  dynamic "attribute" {
+    for_each = toset(local.gsi_attribute_names)
+    content {
+      name = attribute.value
+      type = "S"
+    }
+  }
+
+  dynamic "global_secondary_index" {
+    for_each = var.global_secondary_indexes
+    content {
+      name            = global_secondary_index.value.name
+      hash_key        = global_secondary_index.value.hash_key
+      range_key       = global_secondary_index.value.range_key
+      projection_type = global_secondary_index.value.projection_type
+    }
+  }
+
+  point_in_time_recovery {
+    enabled = var.point_in_time_recovery_enabled
+  }
+
+  server_side_encryption {
+    enabled     = true
+    kms_key_arn = aws_kms_key.table.arn
+  }
+}
+
+output "table_name" {
+  description = "Name of the DynamoDB table."
+  value       = aws_dynamodb_table.table.name
+}
+
+output "table_arn" {
+  description = "ARN of the DynamoDB table."
+  value       = aws_dynamodb_table.table.arn
+}
+
+output "kms_key_arn" {
+  description = "ARN of the KMS key used to encrypt the DynamoDB table."
+  value       = aws_kms_key.table.arn
+}
+"
+`;
+
+exports[`py#dynamodb generator > should generate terraform modules when iac is terraform 2`] = `
+"terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "6.58.0"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = "3.9.0"
+    }
+  }
+}
+
+variable "billing_mode" {
+  description = "Controls how you are charged for read and write throughput."
+  type        = string
+  default     = "PAY_PER_REQUEST"
+}
+
+variable "point_in_time_recovery_enabled" {
+  description = "Whether to enable point-in-time recovery for the table."
+  type        = bool
+  default     = true
+}
+
+variable "deletion_protection_enabled" {
+  description = "Whether to enable deletion protection on the table."
+  type        = bool
+  default     = true
+}
+
+variable "enable_key_rotation" {
+  description = "Whether to enable automatic key rotation on the KMS key used to encrypt the table."
+  type        = bool
+  default     = true
+}
+
+resource "random_string" "suffix" {
+  length  = 8
+  special = false
+  upper   = false
+}
+
+locals {
+  dynamodb_config = jsondecode(file("\${path.module}/../../../../../../../packages/my_table/config.json"))
+  global_secondary_indexes = [for gsi in local.dynamodb_config.tableConfig.globalSecondaryIndexes : {
+    name            = gsi.indexName
+    hash_key        = gsi.partitionKey
+    range_key       = try(gsi.sortKey, null)
+    projection_type = "ALL"
+  }]
+}
+
+module "dynamodb_table" {
+  source                         = "../../../core/dynamodb"
+  name                           = "proj-my-table-\${random_string.suffix.result}"
+  billing_mode                   = var.billing_mode
+  point_in_time_recovery_enabled = var.point_in_time_recovery_enabled
+  deletion_protection_enabled    = var.deletion_protection_enabled
+  enable_key_rotation            = var.enable_key_rotation
+  global_secondary_indexes       = local.global_secondary_indexes
+}
+
+module "add_to_runtime_config" {
+  source = "../../../core/runtime-config/entry"
+
+  namespace = "dynamodb"
+  key       = local.dynamodb_config.runtimeConfigKey
+  value = {
+    tableName = module.dynamodb_table.table_name
+  }
+}
+"
+`;
+
+exports[`py#dynamodb generator > should generate the dynamodb project > packages/common/scripts/src/dynamodb/create-local-table.ts 1`] = `
+"import {
+  BillingMode,
+  CreateTableCommand,
+  DescribeTableCommand,
+  DynamoDBClient,
+  GlobalSecondaryIndexDescription,
+  IndexStatus,
+  KeyType,
+  ProjectionType,
+  ResourceInUseException,
+  ScalarAttributeType,
+  TableStatus,
+  UpdateTableCommand,
+} from '@aws-sdk/client-dynamodb';
+import { readFileSync } from 'fs';
+
+const {
+  localDev: { port, tableName },
+  tableConfig: { globalSecondaryIndexes },
+} = JSON.parse(readFileSync('config.json', 'utf-8')) as {
+  localDev: { port: number; tableName: string };
+  tableConfig: {
+    globalSecondaryIndexes: {
+      indexName: string;
+      partitionKey: string;
+      sortKey?: string;
+    }[];
+  };
+};
+
+const timeoutSignal = () => AbortSignal.timeout(10000);
+
+const client = new DynamoDBClient({
+  endpoint: \`http://localhost:\${port}\`,
+  region: 'us-east-1',
+  credentials: { accessKeyId: 'UNUSED', secretAccessKey: 'UNUSED' },
+});
+
+const waitForTableActive = async (
+  waitClient: DynamoDBClient,
+  waitTableName: string,
+): Promise<void> => {
+  for (;;) {
+    const { Table } = await waitClient.send(
+      new DescribeTableCommand({ TableName: waitTableName }),
+      { abortSignal: timeoutSignal() },
+    );
+    const allActive =
+      Table?.TableStatus === TableStatus.ACTIVE &&
+      (Table?.GlobalSecondaryIndexes ?? []).every(
+        (g: GlobalSecondaryIndexDescription) =>
+          g.IndexStatus === IndexStatus.ACTIVE,
+      );
+    if (allActive) return;
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+};
+
+const ensureTable = async (
+  tblClient: DynamoDBClient,
+  tblName: string,
+  gsIs: { indexName: string; partitionKey: string; sortKey?: string }[],
+): Promise<void> => {
+  const gsiAttributeDefinitions = gsIs.flatMap((gsi) => [
+    { AttributeName: gsi.partitionKey, AttributeType: ScalarAttributeType.S },
+    ...(gsi.sortKey
+      ? [{ AttributeName: gsi.sortKey, AttributeType: ScalarAttributeType.S }]
+      : []),
+  ]);
+  const attributeDefinitions = [
+    { AttributeName: 'pk', AttributeType: ScalarAttributeType.S },
+    { AttributeName: 'sk', AttributeType: ScalarAttributeType.S },
+    ...gsiAttributeDefinitions.filter(
+      (a, i, arr) =>
+        arr.findIndex((b) => b.AttributeName === a.AttributeName) === i,
+    ),
+  ];
+  const globalSecondaryIndexes = gsIs.map((gsi) => ({
+    IndexName: gsi.indexName,
+    KeySchema: [
+      { AttributeName: gsi.partitionKey, KeyType: KeyType.HASH },
+      ...(gsi.sortKey
+        ? [{ AttributeName: gsi.sortKey, KeyType: KeyType.RANGE }]
+        : []),
+    ],
+    Projection: { ProjectionType: ProjectionType.ALL },
+  }));
+
+  for (let attempt = 0; attempt < 30; attempt++) {
+    try {
+      // New table: create with all GSIs in one shot.
+      await tblClient.send(
+        new CreateTableCommand({
+          TableName: tblName,
+          AttributeDefinitions: attributeDefinitions,
+          KeySchema: [
+            { AttributeName: 'pk', KeyType: KeyType.HASH },
+            { AttributeName: 'sk', KeyType: KeyType.RANGE },
+          ],
+          BillingMode: BillingMode.PAY_PER_REQUEST,
+          ...(globalSecondaryIndexes.length > 0 && {
+            GlobalSecondaryIndexes: globalSecondaryIndexes,
+          }),
+        }),
+        { abortSignal: timeoutSignal() },
+      );
+      console.log(\`Created table: \${tblName}\`);
+      for (const gsi of globalSecondaryIndexes) {
+        console.log(\`Created GSI: \${gsi.IndexName}\`);
+      }
+      return;
+    } catch (e) {
+      // Table already exists: sync GSIs to match desired state.
+      if (e instanceof ResourceInUseException) {
+        const { Table } = await tblClient.send(
+          new DescribeTableCommand({ TableName: tblName }),
+          { abortSignal: timeoutSignal() },
+        );
+        const existingGSIs = Table?.GlobalSecondaryIndexes ?? [];
+        const existingNames = new Set(
+          existingGSIs.map(
+            (g: GlobalSecondaryIndexDescription) => g.IndexName ?? '',
+          ),
+        );
+        const desiredNames = new Set(gsIs.map((g) => g.indexName));
+
+        // DynamoDB Local only allows one GSI to be created or deleted at a time.
+        for (const existing of existingGSIs) {
+          if (!existing.IndexName || desiredNames.has(existing.IndexName))
+            continue;
+          await tblClient.send(
+            new UpdateTableCommand({
+              TableName: tblName,
+              GlobalSecondaryIndexUpdates: [
+                { Delete: { IndexName: existing.IndexName } },
+              ],
+            }),
+            { abortSignal: timeoutSignal() },
+          );
+          console.log(\`Deleted GSI: \${existing.IndexName}\`);
+          await waitForTableActive(tblClient, tblName);
+        }
+
+        for (const gsi of gsIs) {
+          if (existingNames.has(gsi.indexName)) continue;
+          await tblClient.send(
+            new UpdateTableCommand({
+              TableName: tblName,
+              AttributeDefinitions: [
+                {
+                  AttributeName: gsi.partitionKey,
+                  AttributeType: ScalarAttributeType.S,
+                },
+                ...(gsi.sortKey
+                  ? [
+                      {
+                        AttributeName: gsi.sortKey,
+                        AttributeType: ScalarAttributeType.S,
+                      },
+                    ]
+                  : []),
+              ],
+              GlobalSecondaryIndexUpdates: [
+                {
+                  Create: {
+                    IndexName: gsi.indexName,
+                    KeySchema: [
+                      {
+                        AttributeName: gsi.partitionKey,
+                        KeyType: KeyType.HASH,
+                      },
+                      ...(gsi.sortKey
+                        ? [
+                            {
+                              AttributeName: gsi.sortKey,
+                              KeyType: KeyType.RANGE,
+                            },
+                          ]
+                        : []),
+                    ],
+                    Projection: { ProjectionType: ProjectionType.ALL },
+                  },
+                },
+              ],
+            }),
+            { abortSignal: timeoutSignal() },
+          );
+          console.log(\`Created GSI: \${gsi.indexName}\`);
+          await waitForTableActive(tblClient, tblName);
+        }
+        return;
+      }
+      if (attempt === 29) throw e;
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+  }
+};
+
+await ensureTable(client, tableName, globalSecondaryIndexes);
+"
+`;
+
+exports[`py#dynamodb generator > should generate the dynamodb project > packages/common/scripts/src/dynamodb/pull-image.ts 1`] = `
+"import { spawnSync } from 'child_process';
+import { readFileSync } from 'fs';
+
+const { containerEngine, image } = JSON.parse(
+  readFileSync('config.json', 'utf-8'),
+).localDev;
+
+const inspect = spawnSync(containerEngine, ['image', 'inspect', image], {
+  stdio: 'ignore',
+});
+if (inspect.status !== 0) {
+  const pull = spawnSync(containerEngine, ['pull', image], {
+    stdio: 'inherit',
+  });
+  if (pull.status !== 0) {
+    process.exit(pull.status ?? 1);
+  }
+}
+"
+`;
+
+exports[`py#dynamodb generator > should generate the dynamodb project > packages/common/scripts/src/dynamodb/start-container.ts 1`] = `
+"import { spawn, spawnSync } from 'child_process';
+import { readFileSync } from 'fs';
+
+const { containerEngine, containerName, image, port } = JSON.parse(
+  readFileSync('config.json', 'utf-8'),
+).localDev;
+
+const containerExists = (): boolean =>
+  spawnSync(containerEngine, ['container', 'inspect', containerName], {
+    stdio: 'ignore',
+  }).status === 0;
+
+const isRunning = (): boolean => {
+  const result = spawnSync(
+    containerEngine,
+    ['container', 'inspect', '-f', '{{.State.Running}}', containerName],
+    { encoding: 'utf-8' },
+  );
+  return result.status === 0 && result.stdout.trim() === 'true';
+};
+
+// Ensure the image is available locally before starting the container.
+const ensureImage = (): void => {
+  const inspect = spawnSync(containerEngine, ['image', 'inspect', image], {
+    stdio: 'ignore',
+  });
+  if (inspect.status !== 0) {
+    const pull = spawnSync(containerEngine, ['pull', image], {
+      stdio: 'inherit',
+    });
+    if (pull.status !== 0) process.exit(pull.status ?? 1);
+  }
+};
+
+// Multiple dynamo table packages run dev in parallel sharing the same
+// container. All processes stream logs, but only the one that created the
+// container stops it on exit — others just detach.
+let created = false;
+let runRetries = 0;
+
+ensureImage();
+
+for (;;) {
+  if (containerExists()) {
+    if (!isRunning()) {
+      // Another process may have started it between our inspect and start — container engine start
+      // exits 0 even if the container is already running, so no special-casing needed.
+      const start = spawnSync(containerEngine, ['start', containerName], {
+        stdio: 'inherit',
+      });
+      if (start.status !== 0) process.exit(start.status ?? 1);
+    }
+    break;
+  }
+  const runArgs = [
+    'run',
+    ...(containerEngine === 'docker' ? ['--rm'] : []),
+    '--name',
+    containerName,
+    '-u',
+    'root',
+    '-w',
+    '/home/dynamodblocal',
+    \`-p\`,
+    \`\${port}:\${port}\`,
+    '-v',
+    \`\${containerName}-data:/home/dynamodblocal/data\`,
+    '-d',
+    image,
+    '-jar',
+    'DynamoDBLocal.jar',
+    '-sharedDb',
+    '-dbPath',
+    './data',
+    '-port',
+    \`\${port}\`,
+  ];
+  const create = spawnSync(containerEngine, runArgs, { stdio: 'pipe' });
+  if (create.status === 0) {
+    created = true;
+    break;
+  }
+  if (!containerExists() && ++runRetries > 3) {
+    process.stderr.write(create.stderr);
+    process.exit(create.status ?? 1);
+  }
+}
+
+const logs = spawn(containerEngine, ['logs', '-f', containerName], {
+  stdio: ['ignore', 'inherit', 'inherit'],
+});
+
+let exiting = false;
+
+const cleanup = () => {
+  if (exiting) return;
+  exiting = true;
+  if (created) {
+    if (containerEngine === 'docker') {
+      spawnSync(containerEngine, ['stop', containerName], { stdio: 'ignore' });
+    } else {
+      spawnSync(containerEngine, ['rm', '-f', containerName], {
+        stdio: 'ignore',
+      });
+    }
+  }
+  logs.kill();
+  process.exit(0);
+};
+
+process.on('SIGTERM', cleanup);
+process.on('SIGINT', cleanup);
+process.on('SIGHUP', cleanup);
+
+logs.on('exit', cleanup);
+"
+`;
+
+exports[`py#dynamodb generator > should generate the dynamodb project > packages/my_table/proj_my_table/__init__.py 1`] = `
+"from .entities import BaseModel, ExampleModel
+
+__all__ = [
+    "BaseModel",
+    "ExampleModel",
+]
+"
+`;
+
+exports[`py#dynamodb generator > should generate the dynamodb project > packages/my_table/proj_my_table/client.py 1`] = `
+"import json
+import os
+from typing import Any, cast
+
+# Generated: must match runtimeConfigKey in config.json
+runtime_config_key = "MyTable"
+
+
+# config.json is only present in local dev (not in the deployed bundle),
+# so calls to _local_dev must be guarded by is_local().
+def _local_dev() -> dict:
+    config_path = os.path.join(os.path.dirname(__file__), "..", "config.json")
+    with open(config_path) as f:
+        return json.load(f)["localDev"]
+
+
+def is_local() -> bool:
+    return os.environ.get("LOCAL_DEV") == "true"
+
+
+_table_name: str | None = None
+
+
+def get_table_name() -> str:
+    global _table_name
+    if is_local():
+        return _local_dev()["tableName"]
+    if _table_name is None:
+        from aws_lambda_powertools.utilities.parameters import AppConfigProvider
+
+        app_id = os.environ.get("RUNTIME_CONFIG_APP_ID")
+        if not app_id:
+            raise ValueError("RUNTIME_CONFIG_APP_ID environment variable is not set")
+        provider = AppConfigProvider(application=app_id, environment="default")
+        config = cast(dict[str, Any], provider.get("dynamodb", transform="json") or {})
+        table_name = (config.get(runtime_config_key) or {}).get("tableName")
+        if not table_name:
+            raise ValueError("Could not resolve table name from runtime config")
+        _table_name = table_name
+    return _table_name
+"
+`;
+
+exports[`py#dynamodb generator > should generate the dynamodb project > packages/my_table/proj_my_table/entities/__init__.py 1`] = `
+"from .base import BaseModel
+from .example import ExampleModel
+
+__all__ = ["BaseModel", "ExampleModel"]
+"
+`;
+
+exports[`py#dynamodb generator > should generate the dynamodb project > packages/my_table/proj_my_table/entities/base.py 1`] = `
+"import os
+
+from pynamodb.attributes import DiscriminatorAttribute, UnicodeAttribute
+from pynamodb.indexes import AllProjection, GlobalSecondaryIndex
+from pynamodb.models import Model
+
+from ..client import _local_dev, get_table_name, is_local
+
+
+class Gsi1Index(GlobalSecondaryIndex):
+    class Meta:
+        index_name = "gsi1pk-gsi1sk-index"
+        projection = AllProjection()
+
+    gsi1pk = UnicodeAttribute(hash_key=True)
+    gsi1sk = UnicodeAttribute(range_key=True)
+
+
+class Gsi2Index(GlobalSecondaryIndex):
+    class Meta:
+        index_name = "gsi2pk-gsi2sk-index"
+        projection = AllProjection()
+
+    gsi2pk = UnicodeAttribute(hash_key=True)
+    gsi2sk = UnicodeAttribute(range_key=True)
+
+
+class BaseModel(Model):
+    """Base model for all DynamoDB entities in this table.
+
+    All entity models MUST extend this class. It wires up the correct DynamoDB
+    table name at runtime — resolving from AWS AppConfig when deployed, or from
+    config.json when running locally via DynamoDB Local — by overriding
+    _get_connection(). Without this, PynamoDB will not know which table to use.
+
+    Also uses PynamoDB polymorphism to support multiple entity types in a single
+    table via DiscriminatorAttribute.
+    See https://pynamodb.readthedocs.io/en/stable/polymorphism.html
+    """
+
+    class Meta:
+        table_name: str
+        region = os.environ.get("AWS_REGION", "us-east-1")
+        host = f"http://localhost:{_local_dev()['port']}" if is_local() else None
+        aws_access_key_id = "UNUSED" if is_local() else None
+        aws_secret_access_key = "UNUSED" if is_local() else None
+
+    entity_type = DiscriminatorAttribute()
+
+    pk = UnicodeAttribute(hash_key=True)
+    sk = UnicodeAttribute(range_key=True)
+    gsi1pk = UnicodeAttribute(null=True)
+    gsi1sk = UnicodeAttribute(null=True)
+    gsi2pk = UnicodeAttribute(null=True)
+    gsi2sk = UnicodeAttribute(null=True)
+
+    gsi1_index = Gsi1Index()
+    gsi2_index = Gsi2Index()
+
+    @classmethod
+    def _get_connection(cls):
+        cls.Meta.table_name = get_table_name()
+        return super()._get_connection()
+"
+`;
+
+exports[`py#dynamodb generator > should generate the dynamodb project > packages/my_table/proj_my_table/entities/example.py 1`] = `
+"from collections.abc import Iterator
+from datetime import UTC, datetime
+
+from pynamodb.attributes import UnicodeAttribute
+
+from .base import BaseModel
+
+
+# Example entity using PynamoDB - replace with your own entities
+# See https://pynamodb.readthedocs.io/en/stable/tutorial.html for documentation
+class ExampleModel(BaseModel, discriminator="ExampleModel"):
+    """Example entity demonstrating single-table design with GSI access patterns.
+
+    Key design:
+      pk=EXAMPLE#{id}, sk=EXAMPLE#{id}
+      gsi1pk=CATEGORY#{category}, gsi1sk=EXAMPLE#{id}
+      gsi2pk=EXAMPLE, gsi2sk={created_at ISO-8601}
+    """
+
+    name = UnicodeAttribute()
+    category = UnicodeAttribute()
+    created_at = UnicodeAttribute()
+    updated_at = UnicodeAttribute()
+
+    @classmethod
+    def make_pk(cls, id: str) -> str:
+        return f"EXAMPLE#{id}"
+
+    # ── Writes ────────────────────────────────────────────────────────────────
+    @classmethod
+    def create(cls, id: str, name: str, category: str) -> ExampleModel:
+        now = datetime.now(UTC).isoformat()
+        item = cls(
+            pk=cls.make_pk(id),
+            sk=cls.make_pk(id),
+            gsi1pk=f"CATEGORY#{category}",
+            gsi1sk=cls.make_pk(id),
+            gsi2pk="EXAMPLE",
+            gsi2sk=now,
+            name=name,
+            category=category,
+            created_at=now,
+            updated_at=now,
+        )
+        item.save()
+        return item
+
+    # ── Primary index ─────────────────────────────────────────────────────────
+    @classmethod
+    def get_by_id(cls, id: str) -> ExampleModel:
+        """Exact lookup by pk + sk."""
+        return cls.get(cls.make_pk(id), cls.make_pk(id))
+
+    # ── gsi1_index: partition=category, sort=id ───────────────────────────────
+    @classmethod
+    def list_by_category(cls, category: str) -> Iterator[ExampleModel]:
+        """All items in a category."""
+        return cls.gsi1_index.query(f"CATEGORY#{category}")
+
+    # ── gsi2_index: partition=type, sort=created_at ───────────────────────────
+    @classmethod
+    def list_by_date(cls, limit: int | None = None) -> Iterator[ExampleModel]:
+        """All examples, newest first."""
+        return cls.gsi2_index.query("EXAMPLE", limit=limit, scan_index_forward=False)
+"
+`;
+
+exports[`py#dynamodb generator > should generate the dynamodb project 1`] = `
+"import { Construct } from 'constructs';
+import {
+  AttributeType,
+  BillingMode,
+  Table,
+  TableEncryption,
+  TableProps,
+} from 'aws-cdk-lib/aws-dynamodb';
+import { RemovalPolicy } from 'aws-cdk-lib';
+import { Grant, IGrantable } from 'aws-cdk-lib/aws-iam';
+import { Key } from 'aws-cdk-lib/aws-kms';
+import { RuntimeConfig } from './runtime-config.js';
+
+type _DynamoDBTableProps = Omit<
+  TableProps,
+  'tableName' | 'partitionKey' | 'sortKey' | 'encryption' | 'encryptionKey'
+>;
+
+export interface DynamoDBTableProps extends _DynamoDBTableProps {
+  /**
+   * The DynamoDB table name. If omitted, CDK auto-generates a unique name
+   * from the stack name and construct path.
+   */
+  readonly tableName?: string;
+
+  /**
+   * RuntimeConfig key used under the \`dynamodb\` namespace.
+   */
+  readonly runtimeConfigKey: string;
+
+  /**
+   * Whether to enable automatic key rotation on the KMS key used to encrypt the table.
+   *
+   * @default true
+   */
+  readonly enableKeyRotation?: boolean;
+}
+
+export abstract class DynamoDBTable extends Construct {
+  public readonly table: Table;
+
+  constructor(
+    scope: Construct,
+    id: string,
+    {
+      tableName,
+      runtimeConfigKey,
+      billingMode = BillingMode.PAY_PER_REQUEST,
+      pointInTimeRecoverySpecification = { pointInTimeRecoveryEnabled: true },
+      deletionProtection = true,
+      removalPolicy = RemovalPolicy.RETAIN,
+      enableKeyRotation = true,
+      ...rest
+    }: DynamoDBTableProps,
+  ) {
+    super(scope, id);
+
+    const key = new Key(this, 'EncryptionKey', { enableKeyRotation });
+
+    this.table = new Table(this, runtimeConfigKey, {
+      ...rest,
+      ...(tableName !== undefined && { tableName }),
+      partitionKey: { name: 'pk', type: AttributeType.STRING },
+      sortKey: { name: 'sk', type: AttributeType.STRING },
+      billingMode,
+      pointInTimeRecoverySpecification,
+      deletionProtection,
+      encryptionKey: key,
+      encryption: TableEncryption.CUSTOMER_MANAGED,
+      removalPolicy,
+    });
+
+    const rc = RuntimeConfig.ensure(this);
+    rc.set('dynamodb', runtimeConfigKey, { tableName: this.table.tableName });
+  }
+
+  public grantReadData(grantee: IGrantable): Grant {
+    return this.table.grantReadData(grantee);
+  }
+
+  public grantWriteData(grantee: IGrantable): Grant {
+    return this.table.grantWriteData(grantee);
+  }
+
+  public grantReadWriteData(grantee: IGrantable): Grant {
+    return this.table.grantReadWriteData(grantee);
+  }
+
+  public grantFullAccess(grantee: IGrantable): Grant {
+    return this.table.grantFullAccess(grantee);
+  }
+
+  public grantStreamRead(grantee: IGrantable): Grant {
+    return this.table.grantStreamRead(grantee);
+  }
+
+  public grantTableListStreams(grantee: IGrantable): Grant {
+    return this.table.grantTableListStreams(grantee);
+  }
+
+  public grant(grantee: IGrantable, ...actions: string[]): Grant {
+    return this.table.grant(grantee, ...actions);
+  }
+
+  public grantStream(grantee: IGrantable, ...actions: string[]): Grant {
+    return this.table.grantStream(grantee, ...actions);
+  }
+}
+"
+`;
+
+exports[`py#dynamodb generator > should generate the dynamodb project 2`] = `
+"import { Construct } from 'constructs';
+import { AttributeType, ProjectionType } from 'aws-cdk-lib/aws-dynamodb';
+import { DynamoDBTable, DynamoDBTableProps } from '../../core/dynamodb.js';
+import { findWorkspaceRoot } from '../../core/workspace.js';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+
+const { runtimeConfigKey, tableConfig } = JSON.parse(
+  readFileSync(
+    join(
+      findWorkspaceRoot(fileURLToPath(new URL(import.meta.url))),
+      'packages/my_table/config.json',
+    ),
+    'utf-8',
+  ),
+) as {
+  runtimeConfigKey: string;
+  tableConfig: {
+    globalSecondaryIndexes: {
+      indexName: string;
+      partitionKey: string;
+      sortKey?: string;
+    }[];
+  };
+};
+
+export type MyTableProps = Omit<DynamoDBTableProps, 'runtimeConfigKey'>;
+
+export class MyTable extends DynamoDBTable {
+  constructor(scope: Construct, id: string, props?: MyTableProps) {
+    super(scope, id, {
+      ...props,
+      runtimeConfigKey,
+    });
+
+    for (const gsi of tableConfig.globalSecondaryIndexes) {
+      this.table.addGlobalSecondaryIndex({
+        indexName: gsi.indexName,
+        partitionKey: { name: gsi.partitionKey, type: AttributeType.STRING },
+        ...(gsi.sortKey && {
+          sortKey: { name: gsi.sortKey, type: AttributeType.STRING },
+        }),
+        projectionType: ProjectionType.ALL,
+      });
+    }
+  }
+}
+"
+`;
+
+exports[`py#dynamodb generator > should generate the dynamodb project 3`] = `
+"export * from './my-table.js';
+"
+`;
+
+exports[`py#dynamodb generator > should generate the dynamodb project 4`] = `
+"export * from './dynamodb/index.js';
+"
+`;
+
+exports[`py#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/common/scripts/src/dynamodb/create-local-table.ts 1`] = `
+"import {
+  BillingMode,
+  CreateTableCommand,
+  DescribeTableCommand,
+  DynamoDBClient,
+  GlobalSecondaryIndexDescription,
+  IndexStatus,
+  KeyType,
+  ProjectionType,
+  ResourceInUseException,
+  ScalarAttributeType,
+  TableStatus,
+  UpdateTableCommand,
+} from '@aws-sdk/client-dynamodb';
+import { readFileSync } from 'fs';
+
+const {
+  localDev: { port, tableName },
+  tableConfig: { globalSecondaryIndexes },
+} = JSON.parse(readFileSync('config.json', 'utf-8')) as {
+  localDev: { port: number; tableName: string };
+  tableConfig: {
+    globalSecondaryIndexes: {
+      indexName: string;
+      partitionKey: string;
+      sortKey?: string;
+    }[];
+  };
+};
+
+const timeoutSignal = () => AbortSignal.timeout(10000);
+
+const client = new DynamoDBClient({
+  endpoint: \`http://localhost:\${port}\`,
+  region: 'us-east-1',
+  credentials: { accessKeyId: 'UNUSED', secretAccessKey: 'UNUSED' },
+});
+
+const waitForTableActive = async (
+  waitClient: DynamoDBClient,
+  waitTableName: string,
+): Promise<void> => {
+  for (;;) {
+    const { Table } = await waitClient.send(
+      new DescribeTableCommand({ TableName: waitTableName }),
+      { abortSignal: timeoutSignal() },
+    );
+    const allActive =
+      Table?.TableStatus === TableStatus.ACTIVE &&
+      (Table?.GlobalSecondaryIndexes ?? []).every(
+        (g: GlobalSecondaryIndexDescription) =>
+          g.IndexStatus === IndexStatus.ACTIVE,
+      );
+    if (allActive) return;
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+};
+
+const ensureTable = async (
+  tblClient: DynamoDBClient,
+  tblName: string,
+  gsIs: { indexName: string; partitionKey: string; sortKey?: string }[],
+): Promise<void> => {
+  const gsiAttributeDefinitions = gsIs.flatMap((gsi) => [
+    { AttributeName: gsi.partitionKey, AttributeType: ScalarAttributeType.S },
+    ...(gsi.sortKey
+      ? [{ AttributeName: gsi.sortKey, AttributeType: ScalarAttributeType.S }]
+      : []),
+  ]);
+  const attributeDefinitions = [
+    { AttributeName: 'pk', AttributeType: ScalarAttributeType.S },
+    { AttributeName: 'sk', AttributeType: ScalarAttributeType.S },
+    ...gsiAttributeDefinitions.filter(
+      (a, i, arr) =>
+        arr.findIndex((b) => b.AttributeName === a.AttributeName) === i,
+    ),
+  ];
+  const globalSecondaryIndexes = gsIs.map((gsi) => ({
+    IndexName: gsi.indexName,
+    KeySchema: [
+      { AttributeName: gsi.partitionKey, KeyType: KeyType.HASH },
+      ...(gsi.sortKey
+        ? [{ AttributeName: gsi.sortKey, KeyType: KeyType.RANGE }]
+        : []),
+    ],
+    Projection: { ProjectionType: ProjectionType.ALL },
+  }));
+
+  for (let attempt = 0; attempt < 30; attempt++) {
+    try {
+      // New table: create with all GSIs in one shot.
+      await tblClient.send(
+        new CreateTableCommand({
+          TableName: tblName,
+          AttributeDefinitions: attributeDefinitions,
+          KeySchema: [
+            { AttributeName: 'pk', KeyType: KeyType.HASH },
+            { AttributeName: 'sk', KeyType: KeyType.RANGE },
+          ],
+          BillingMode: BillingMode.PAY_PER_REQUEST,
+          ...(globalSecondaryIndexes.length > 0 && {
+            GlobalSecondaryIndexes: globalSecondaryIndexes,
+          }),
+        }),
+        { abortSignal: timeoutSignal() },
+      );
+      console.log(\`Created table: \${tblName}\`);
+      for (const gsi of globalSecondaryIndexes) {
+        console.log(\`Created GSI: \${gsi.IndexName}\`);
+      }
+      return;
+    } catch (e) {
+      // Table already exists: sync GSIs to match desired state.
+      if (e instanceof ResourceInUseException) {
+        const { Table } = await tblClient.send(
+          new DescribeTableCommand({ TableName: tblName }),
+          { abortSignal: timeoutSignal() },
+        );
+        const existingGSIs = Table?.GlobalSecondaryIndexes ?? [];
+        const existingNames = new Set(
+          existingGSIs.map(
+            (g: GlobalSecondaryIndexDescription) => g.IndexName ?? '',
+          ),
+        );
+        const desiredNames = new Set(gsIs.map((g) => g.indexName));
+
+        // DynamoDB Local only allows one GSI to be created or deleted at a time.
+        for (const existing of existingGSIs) {
+          if (!existing.IndexName || desiredNames.has(existing.IndexName))
+            continue;
+          await tblClient.send(
+            new UpdateTableCommand({
+              TableName: tblName,
+              GlobalSecondaryIndexUpdates: [
+                { Delete: { IndexName: existing.IndexName } },
+              ],
+            }),
+            { abortSignal: timeoutSignal() },
+          );
+          console.log(\`Deleted GSI: \${existing.IndexName}\`);
+          await waitForTableActive(tblClient, tblName);
+        }
+
+        for (const gsi of gsIs) {
+          if (existingNames.has(gsi.indexName)) continue;
+          await tblClient.send(
+            new UpdateTableCommand({
+              TableName: tblName,
+              AttributeDefinitions: [
+                {
+                  AttributeName: gsi.partitionKey,
+                  AttributeType: ScalarAttributeType.S,
+                },
+                ...(gsi.sortKey
+                  ? [
+                      {
+                        AttributeName: gsi.sortKey,
+                        AttributeType: ScalarAttributeType.S,
+                      },
+                    ]
+                  : []),
+              ],
+              GlobalSecondaryIndexUpdates: [
+                {
+                  Create: {
+                    IndexName: gsi.indexName,
+                    KeySchema: [
+                      {
+                        AttributeName: gsi.partitionKey,
+                        KeyType: KeyType.HASH,
+                      },
+                      ...(gsi.sortKey
+                        ? [
+                            {
+                              AttributeName: gsi.sortKey,
+                              KeyType: KeyType.RANGE,
+                            },
+                          ]
+                        : []),
+                    ],
+                    Projection: { ProjectionType: ProjectionType.ALL },
+                  },
+                },
+              ],
+            }),
+            { abortSignal: timeoutSignal() },
+          );
+          console.log(\`Created GSI: \${gsi.indexName}\`);
+          await waitForTableActive(tblClient, tblName);
+        }
+        return;
+      }
+      if (attempt === 29) throw e;
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+  }
+};
+
+await ensureTable(client, tableName, globalSecondaryIndexes);
+"
+`;
+
+exports[`py#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/common/scripts/src/dynamodb/pull-image.ts 1`] = `
+"import { spawnSync } from 'child_process';
+import { readFileSync } from 'fs';
+
+const { containerEngine, image } = JSON.parse(
+  readFileSync('config.json', 'utf-8'),
+).localDev;
+
+const inspect = spawnSync(containerEngine, ['image', 'inspect', image], {
+  stdio: 'ignore',
+});
+if (inspect.status !== 0) {
+  const pull = spawnSync(containerEngine, ['pull', image], {
+    stdio: 'inherit',
+  });
+  if (pull.status !== 0) {
+    process.exit(pull.status ?? 1);
+  }
+}
+"
+`;
+
+exports[`py#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/common/scripts/src/dynamodb/start-container.ts 1`] = `
+"import { spawn, spawnSync } from 'child_process';
+import { readFileSync } from 'fs';
+
+const { containerEngine, containerName, image, port } = JSON.parse(
+  readFileSync('config.json', 'utf-8'),
+).localDev;
+
+const containerExists = (): boolean =>
+  spawnSync(containerEngine, ['container', 'inspect', containerName], {
+    stdio: 'ignore',
+  }).status === 0;
+
+const isRunning = (): boolean => {
+  const result = spawnSync(
+    containerEngine,
+    ['container', 'inspect', '-f', '{{.State.Running}}', containerName],
+    { encoding: 'utf-8' },
+  );
+  return result.status === 0 && result.stdout.trim() === 'true';
+};
+
+// Ensure the image is available locally before starting the container.
+const ensureImage = (): void => {
+  const inspect = spawnSync(containerEngine, ['image', 'inspect', image], {
+    stdio: 'ignore',
+  });
+  if (inspect.status !== 0) {
+    const pull = spawnSync(containerEngine, ['pull', image], {
+      stdio: 'inherit',
+    });
+    if (pull.status !== 0) process.exit(pull.status ?? 1);
+  }
+};
+
+// Multiple dynamo table packages run dev in parallel sharing the same
+// container. All processes stream logs, but only the one that created the
+// container stops it on exit — others just detach.
+let created = false;
+let runRetries = 0;
+
+ensureImage();
+
+for (;;) {
+  if (containerExists()) {
+    if (!isRunning()) {
+      // Another process may have started it between our inspect and start — container engine start
+      // exits 0 even if the container is already running, so no special-casing needed.
+      const start = spawnSync(containerEngine, ['start', containerName], {
+        stdio: 'inherit',
+      });
+      if (start.status !== 0) process.exit(start.status ?? 1);
+    }
+    break;
+  }
+  const runArgs = [
+    'run',
+    ...(containerEngine === 'docker' ? ['--rm'] : []),
+    '--name',
+    containerName,
+    '-u',
+    'root',
+    '-w',
+    '/home/dynamodblocal',
+    \`-p\`,
+    \`\${port}:\${port}\`,
+    '-v',
+    \`\${containerName}-data:/home/dynamodblocal/data\`,
+    '-d',
+    image,
+    '-jar',
+    'DynamoDBLocal.jar',
+    '-sharedDb',
+    '-dbPath',
+    './data',
+    '-port',
+    \`\${port}\`,
+  ];
+  const create = spawnSync(containerEngine, runArgs, { stdio: 'pipe' });
+  if (create.status === 0) {
+    created = true;
+    break;
+  }
+  if (!containerExists() && ++runRetries > 3) {
+    process.stderr.write(create.stderr);
+    process.exit(create.status ?? 1);
+  }
+}
+
+const logs = spawn(containerEngine, ['logs', '-f', containerName], {
+  stdio: ['ignore', 'inherit', 'inherit'],
+});
+
+let exiting = false;
+
+const cleanup = () => {
+  if (exiting) return;
+  exiting = true;
+  if (created) {
+    if (containerEngine === 'docker') {
+      spawnSync(containerEngine, ['stop', containerName], { stdio: 'ignore' });
+    } else {
+      spawnSync(containerEngine, ['rm', '-f', containerName], {
+        stdio: 'ignore',
+      });
+    }
+  }
+  logs.kill();
+  process.exit(0);
+};
+
+process.on('SIGTERM', cleanup);
+process.on('SIGINT', cleanup);
+process.on('SIGHUP', cleanup);
+
+logs.on('exit', cleanup);
+"
+`;
+
+exports[`py#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/my_table/proj_my_table/__init__.py 1`] = `
+"from .entities import BaseModel, ExampleModel
+
+__all__ = [
+    "BaseModel",
+    "ExampleModel",
+]
+"
+`;
+
+exports[`py#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/my_table/proj_my_table/client.py 1`] = `
+"import json
+import os
+from typing import Any, cast
+
+# Generated: must match runtimeConfigKey in config.json
+runtime_config_key = "MyTable"
+
+
+# config.json is only present in local dev (not in the deployed bundle),
+# so calls to _local_dev must be guarded by is_local().
+def _local_dev() -> dict:
+    config_path = os.path.join(os.path.dirname(__file__), "..", "config.json")
+    with open(config_path) as f:
+        return json.load(f)["localDev"]
+
+
+def is_local() -> bool:
+    return os.environ.get("LOCAL_DEV") == "true"
+
+
+_table_name: str | None = None
+
+
+def get_table_name() -> str:
+    global _table_name
+    if is_local():
+        return _local_dev()["tableName"]
+    if _table_name is None:
+        from aws_lambda_powertools.utilities.parameters import AppConfigProvider
+
+        app_id = os.environ.get("RUNTIME_CONFIG_APP_ID")
+        if not app_id:
+            raise ValueError("RUNTIME_CONFIG_APP_ID environment variable is not set")
+        provider = AppConfigProvider(application=app_id, environment="default")
+        config = cast(dict[str, Any], provider.get("dynamodb", transform="json") or {})
+        table_name = (config.get(runtime_config_key) or {}).get("tableName")
+        if not table_name:
+            raise ValueError("Could not resolve table name from runtime config")
+        _table_name = table_name
+    return _table_name
+"
+`;
+
+exports[`py#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/my_table/proj_my_table/entities/__init__.py 1`] = `
+"from .base import BaseModel
+from .example import ExampleModel
+
+__all__ = ["BaseModel", "ExampleModel"]
+"
+`;
+
+exports[`py#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/my_table/proj_my_table/entities/base.py 1`] = `
+"import os
+
+from pynamodb.attributes import DiscriminatorAttribute, UnicodeAttribute
+from pynamodb.indexes import AllProjection, GlobalSecondaryIndex
+from pynamodb.models import Model
+
+from ..client import _local_dev, get_table_name, is_local
+
+
+class Gsi1Index(GlobalSecondaryIndex):
+    class Meta:
+        index_name = "gsi1pk-gsi1sk-index"
+        projection = AllProjection()
+
+    gsi1pk = UnicodeAttribute(hash_key=True)
+    gsi1sk = UnicodeAttribute(range_key=True)
+
+
+class Gsi2Index(GlobalSecondaryIndex):
+    class Meta:
+        index_name = "gsi2pk-gsi2sk-index"
+        projection = AllProjection()
+
+    gsi2pk = UnicodeAttribute(hash_key=True)
+    gsi2sk = UnicodeAttribute(range_key=True)
+
+
+class BaseModel(Model):
+    """Base model for all DynamoDB entities in this table.
+
+    All entity models MUST extend this class. It wires up the correct DynamoDB
+    table name at runtime — resolving from AWS AppConfig when deployed, or from
+    config.json when running locally via DynamoDB Local — by overriding
+    _get_connection(). Without this, PynamoDB will not know which table to use.
+
+    Also uses PynamoDB polymorphism to support multiple entity types in a single
+    table via DiscriminatorAttribute.
+    See https://pynamodb.readthedocs.io/en/stable/polymorphism.html
+    """
+
+    class Meta:
+        table_name: str
+        region = os.environ.get("AWS_REGION", "us-east-1")
+        host = f"http://localhost:{_local_dev()['port']}" if is_local() else None
+        aws_access_key_id = "UNUSED" if is_local() else None
+        aws_secret_access_key = "UNUSED" if is_local() else None
+
+    entity_type = DiscriminatorAttribute()
+
+    pk = UnicodeAttribute(hash_key=True)
+    sk = UnicodeAttribute(range_key=True)
+    gsi1pk = UnicodeAttribute(null=True)
+    gsi1sk = UnicodeAttribute(null=True)
+    gsi2pk = UnicodeAttribute(null=True)
+    gsi2sk = UnicodeAttribute(null=True)
+
+    gsi1_index = Gsi1Index()
+    gsi2_index = Gsi2Index()
+
+    @classmethod
+    def _get_connection(cls):
+        cls.Meta.table_name = get_table_name()
+        return super()._get_connection()
+"
+`;
+
+exports[`py#dynamodb generator > should generate with infra=none then upgrade to infra=dynamodb > packages/my_table/proj_my_table/entities/example.py 1`] = `
+"from collections.abc import Iterator
+from datetime import UTC, datetime
+
+from pynamodb.attributes import UnicodeAttribute
+
+from .base import BaseModel
+
+
+# Example entity using PynamoDB - replace with your own entities
+# See https://pynamodb.readthedocs.io/en/stable/tutorial.html for documentation
+class ExampleModel(BaseModel, discriminator="ExampleModel"):
+    """Example entity demonstrating single-table design with GSI access patterns.
+
+    Key design:
+      pk=EXAMPLE#{id}, sk=EXAMPLE#{id}
+      gsi1pk=CATEGORY#{category}, gsi1sk=EXAMPLE#{id}
+      gsi2pk=EXAMPLE, gsi2sk={created_at ISO-8601}
+    """
+
+    name = UnicodeAttribute()
+    category = UnicodeAttribute()
+    created_at = UnicodeAttribute()
+    updated_at = UnicodeAttribute()
+
+    @classmethod
+    def make_pk(cls, id: str) -> str:
+        return f"EXAMPLE#{id}"
+
+    # ── Writes ────────────────────────────────────────────────────────────────
+    @classmethod
+    def create(cls, id: str, name: str, category: str) -> ExampleModel:
+        now = datetime.now(UTC).isoformat()
+        item = cls(
+            pk=cls.make_pk(id),
+            sk=cls.make_pk(id),
+            gsi1pk=f"CATEGORY#{category}",
+            gsi1sk=cls.make_pk(id),
+            gsi2pk="EXAMPLE",
+            gsi2sk=now,
+            name=name,
+            category=category,
+            created_at=now,
+            updated_at=now,
+        )
+        item.save()
+        return item
+
+    # ── Primary index ─────────────────────────────────────────────────────────
+    @classmethod
+    def get_by_id(cls, id: str) -> ExampleModel:
+        """Exact lookup by pk + sk."""
+        return cls.get(cls.make_pk(id), cls.make_pk(id))
+
+    # ── gsi1_index: partition=category, sort=id ───────────────────────────────
+    @classmethod
+    def list_by_category(cls, category: str) -> Iterator[ExampleModel]:
+        """All items in a category."""
+        return cls.gsi1_index.query(f"CATEGORY#{category}")
+
+    # ── gsi2_index: partition=type, sort=created_at ───────────────────────────
+    @classmethod
+    def list_by_date(cls, limit: int | None = None) -> Iterator[ExampleModel]:
+        """All examples, newest first."""
+        return cls.gsi2_index.query("EXAMPLE", limit=limit, scan_index_forward=False)
+"
+`;