@aws-blocks/bb-distributed-table 0.1.0

package/dist/errors.js

@@ -0,0 +1,135 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Typed error constants for DistributedTable. Use with `isBlocksError()` in catch blocks.
+ *
+ * @example
+ * ```typescript
+ * import { isBlocksError } from '@aws-blocks/core';
+ * import { DistributedTableErrors } from '@aws-blocks/bb-distributed-table';
+ *
+ * try {
+ *   await table.put(item, { ifNotExists: true });
+ * } catch (e: unknown) {
+ *   if (isBlocksError(e, DistributedTableErrors.ConditionalCheckFailed)) {
+ *     // item already exists
+ *   }
+ *   throw e;
+ * }
+ * ```
+ */
+export const DistributedTableErrors = {
+    ConditionalCheckFailed: 'ConditionalCheckFailedException',
+    ValidationFailed: 'ValidationFailedException',
+    /**
+     * The query or condition shape is invalid and was rejected before reaching
+     * DynamoDB: a missing `where` clause, a partition key not given as
+     * `{ equals: value }`, an unknown index, more than one sort-key condition, or
+     * an empty `ifFieldEquals`. These are all caller bugs — something the caller
+     * can fix by correcting the call. Catchable via
+     * `isBlocksError(e, DistributedTableErrors.InvalidQuery)`.
+     *
+     * Kept distinct from {@link ItemTooLarge} (a runtime data condition) so a
+     * customer can tell "my query is wrong" from "this item is too big" by name
+     * alone rather than string-matching the message.
+     */
+    InvalidQuery: 'InvalidQueryException',
+    /**
+     * An item exceeds DynamoDB's 400 KB per-item size limit. Unlike an invalid
+     * query, this is not necessarily a caller bug — the size of a given item may
+     * be outside the caller's control — so callers may want to branch on it
+     * (skip, split, or store a reference instead). Catchable via
+     * `isBlocksError(e, DistributedTableErrors.ItemTooLarge)`.
+     *
+     * The mock checks serialized byte length client-side and throws this directly.
+     * On AWS, DynamoDB raises a generic `ValidationException` for oversized items;
+     * the runtime detects the size-specific message and re-maps it to this name so
+     * both layers are catchable with the same code. Other `ValidationException`
+     * causes (malformed expressions, type mismatches) propagate as-is.
+     */
+    ItemTooLarge: 'ItemTooLargeException',
+    /**
+     * A batch operation could not complete all entries within the retry budget.
+     * DynamoDB batch APIs return UnprocessedKeys/UnprocessedItems (HTTP 200) under
+     * sustained throttling; when retries are exhausted we surface this so callers
+     * can back off and resubmit rather than silently losing writes or mistaking a
+     * throttled read for a missing item.
+     *
+     * The in-memory mock never throttles, so it never produces this error — the
+     * constant is shared purely so catch-site handling is identical across both.
+     */
+    BatchIncomplete: 'BatchIncompleteException',
+};
+/**
+ * @internal Build an Error whose `name` carries the typed error code (so callers
+ * can match it with `isBlocksError`). Shared by the mock and AWS runtime so both
+ * produce identically shaped errors.
+ */
+export function blocksError(name, message) {
+    const err = new Error(`${name}: ${message}`);
+    err.name = name;
+    return err;
+}
+/**
+ * @internal Normalize a sort-key condition before it drives a query. Shared by
+ * the mock and AWS runtime so both treat the same inputs identically:
+ *
+ * - **Zero defined fields** (`undefined`, or a present-but-empty `{}` /
+ *   `{ createdAt: undefined }`) → returns `undefined`, i.e. "no sort-key filter,
+ *   query the whole partition". A present-but-empty object would otherwise
+ *   diverge: the mock's per-item matcher accepts everything (returns the whole
+ *   partition) while the AWS runtime registers `#sk` in `ExpressionAttributeNames`
+ *   with no clause that uses it, which DynamoDB rejects with `ValidationException`.
+ * - **Exactly one defined field** → returns the condition unchanged.
+ * - **More than one defined field** → throws `InvalidQuery`, because DynamoDB allows
+ *   only one sort-key condition per `KeyConditionExpression` (use `between` for ranges).
+ *
+ * @throws {DistributedTableErrors.InvalidQuery} If more than one sort-key field is defined.
+ */
+export function normalizeSortKeyCondition(condition) {
+    if (!condition)
+        return undefined;
+    const definedKeys = Object.keys(condition).filter(k => condition[k] !== undefined);
+    if (definedKeys.length === 0)
+        return undefined;
+    if (definedKeys.length > 1) {
+        throw blocksError(DistributedTableErrors.InvalidQuery, DistributedTableMessages.multipleSortKeyConditions(definedKeys));
+    }
+    return condition;
+}
+/**
+ * @internal Validation messages shared by the mock and AWS runtime. Centralised
+ * here so the two implementations stay byte-for-byte in lockstep — parity tests
+ * assert the same wording against both.
+ */
+export const DistributedTableMessages = {
+    indexNotFound: (index) => `Index '${index}' not found`,
+    whereRequired: (pkField) => `query() requires a 'where' clause with partition key field '${pkField}'`,
+    partitionKeyEqualsRequired: (pkField) => `query() requires '${pkField}: { equals: value }' in the where clause (partition key must be an exact match)`,
+    multipleSortKeyConditions: (conditionKeys) => `Only one sort key condition is allowed per query (DynamoDB limitation). ` +
+        `Got: ${conditionKeys.join(', ')}. Use "between" for range queries.`,
+    emptyIfFieldEquals: 'ifFieldEquals must contain at least one field with a non-undefined value',
+    itemTooLarge: (bytes) => `Item size has exceeded the maximum allowed size of 400 KB (got ${bytes} bytes)`,
+    batchIncomplete: (operation, remaining, attempts) => `${operation} did not complete: ${remaining} entr${remaining === 1 ? 'y' : 'ies'} still unprocessed ` +
+        `after ${attempts} attempts (DynamoDB throttling or response-size limits). Retry with backoff.`,
+};
+/**
+ * @internal Re-map DynamoDB's generic `ValidationException` to the intent-revealing
+ * `ItemTooLarge` name when (and only when) it was raised for an oversized item.
+ *
+ * DynamoDB raises a single `ValidationException` for many unrelated conditions, so
+ * we narrow on the size-specific message ("size has exceeded") before re-mapping —
+ * other `ValidationException` causes (malformed expressions, type mismatches) are
+ * left untouched and propagate as-is. This mirrors the mock's client-side size
+ * check so both layers are catchable with `isBlocksError(e, ItemTooLarge)`. The
+ * original DynamoDB error is preserved as `cause` (kept server-side per D-003) so
+ * its stack and requestId remain available for debugging.
+ */
+export function remapItemTooLarge(err) {
+    if (err instanceof Error && err.name === 'ValidationException' && /size has exceeded/i.test(err.message)) {
+        const remapped = new Error(err.message, { cause: err });
+        remapped.name = DistributedTableErrors.ItemTooLarge;
+        return remapped;
+    }
+    return err;
+}

package/dist/gsi-manager-lambda/index.js

@@ -0,0 +1,221 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/gsi-manager-lambda.ts
+var gsi_manager_lambda_exports = {};
+__export(gsi_manager_lambda_exports, {
+  handler: () => handler,
+  isCompleteHandler: () => isCompleteHandler
+});
+module.exports = __toCommonJS(gsi_manager_lambda_exports);
+var import_client_dynamodb = require("@aws-sdk/client-dynamodb");
+var dynamodb = new import_client_dynamodb.DynamoDBClient({});
+async function describeTable(tableName) {
+  const result = await dynamodb.send(new import_client_dynamodb.DescribeTableCommand({ TableName: tableName }));
+  return result.Table;
+}
+function getCurrentGSIs(table) {
+  const gsis = {};
+  for (const gsi of table.GlobalSecondaryIndexes ?? []) {
+    const pk = gsi.KeySchema?.find((k) => k.KeyType === "HASH")?.AttributeName;
+    const sk = gsi.KeySchema?.find((k) => k.KeyType === "RANGE")?.AttributeName;
+    if (pk) gsis[gsi.IndexName] = { pk, sk };
+  }
+  return gsis;
+}
+function gsiMatchesDesired(table, desired) {
+  const current = getCurrentGSIs(table);
+  const currentNames = Object.keys(current);
+  const desiredNames = Object.keys(desired);
+  if (currentNames.length !== desiredNames.length) return false;
+  for (const name of desiredNames) {
+    if (!current[name]) return false;
+    if (current[name].pk !== desired[name].partitionKey) return false;
+    if (current[name].sk !== desired[name].sortKey) return false;
+  }
+  return true;
+}
+function isTableBusy(table) {
+  if (table.TableStatus !== "ACTIVE") return true;
+  for (const gsi of table.GlobalSecondaryIndexes ?? []) {
+    if (gsi.IndexStatus !== "ACTIVE") return true;
+  }
+  return false;
+}
+async function recreateTableWithIndexes(tableName, desired) {
+  console.log("\u26A0\uFE0F  SANDBOX MODE: Recreating table with all GSIs (fast path)");
+  const table = await describeTable(tableName);
+  const items = [];
+  let lastKey;
+  do {
+    const result = await dynamodb.send(new import_client_dynamodb.ScanCommand({ TableName: tableName, ExclusiveStartKey: lastKey }));
+    items.push(...result.Items ?? []);
+    lastKey = result.LastEvaluatedKey;
+  } while (lastKey);
+  console.log(`Backed up ${items.length} items`);
+  await dynamodb.send(new import_client_dynamodb.DeleteTableCommand({ TableName: tableName }));
+  while (true) {
+    try {
+      await dynamodb.send(new import_client_dynamodb.DescribeTableCommand({ TableName: tableName }));
+      await new Promise((r) => setTimeout(r, 3e3));
+    } catch (e) {
+      if (e.name === "ResourceNotFoundException") break;
+      throw e;
+    }
+  }
+  const usedAttrs = /* @__PURE__ */ new Set();
+  table.KeySchema.forEach((k) => usedAttrs.add(k.AttributeName));
+  for (const cfg of Object.values(desired)) {
+    usedAttrs.add(cfg.partitionKey);
+    if (cfg.sortKey) usedAttrs.add(cfg.sortKey);
+  }
+  const existingAttrMap = /* @__PURE__ */ new Map();
+  for (const attr of table.AttributeDefinitions ?? []) {
+    existingAttrMap.set(attr.AttributeName, attr.AttributeType);
+  }
+  const attrDefs = [...usedAttrs].map((name) => ({
+    AttributeName: name,
+    AttributeType: existingAttrMap.get(name) ?? Object.values(desired).find((c) => c.partitionKey === name)?.partitionKeyType ?? Object.values(desired).find((c) => c.sortKey === name)?.sortKeyType ?? import_client_dynamodb.ScalarAttributeType.S
+  }));
+  await dynamodb.send(new import_client_dynamodb.CreateTableCommand({
+    TableName: tableName,
+    KeySchema: table.KeySchema,
+    AttributeDefinitions: attrDefs,
+    BillingMode: import_client_dynamodb.BillingMode.PAY_PER_REQUEST,
+    GlobalSecondaryIndexes: Object.entries(desired).map(([name, cfg]) => ({
+      IndexName: name,
+      KeySchema: [
+        { AttributeName: cfg.partitionKey, KeyType: import_client_dynamodb.KeyType.HASH },
+        ...cfg.sortKey ? [{ AttributeName: cfg.sortKey, KeyType: import_client_dynamodb.KeyType.RANGE }] : []
+      ],
+      Projection: { ProjectionType: "ALL" }
+    }))
+  }));
+  while (true) {
+    const t = await describeTable(tableName);
+    if (!isTableBusy(t)) break;
+    await new Promise((r) => setTimeout(r, 3e3));
+  }
+  for (let i = 0; i < items.length; i += 25) {
+    await dynamodb.send(new import_client_dynamodb.BatchWriteItemCommand({
+      RequestItems: { [tableName]: items.slice(i, i + 25).map((item) => ({ PutRequest: { Item: item } })) }
+    }));
+  }
+  console.log(`\u2705 Sandbox: table recreated with ${Object.keys(desired).length} GSIs, ${items.length} items restored`);
+}
+async function handler(event) {
+  console.log("onEvent:", JSON.stringify(event, null, 2));
+  const { TableName, Indexes, SandboxMode } = event.ResourceProperties;
+  const desired = event.RequestType === "Delete" ? {} : Indexes ?? {};
+  const isSandbox = SandboxMode === "true";
+  const physicalId = event.PhysicalResourceId ?? TableName;
+  const table = await describeTable(TableName);
+  if (gsiMatchesDesired(table, desired) && !isTableBusy(table)) {
+    console.log("Already in desired state");
+    return { PhysicalResourceId: physicalId, Data: { Status: "COMPLETE" } };
+  }
+  if (isSandbox && Object.keys(desired).length > 0) {
+    await recreateTableWithIndexes(TableName, desired);
+    return { PhysicalResourceId: physicalId, Data: { Status: "COMPLETE" } };
+  }
+  if (!isTableBusy(table)) {
+    await initiateNextChange(TableName, table, desired);
+  }
+  return { PhysicalResourceId: physicalId, Data: { Status: "IN_PROGRESS" } };
+}
+async function isCompleteHandler(event) {
+  console.log("isComplete:", JSON.stringify(event, null, 2));
+  const { TableName, Indexes, SandboxMode } = event.ResourceProperties;
+  const desired = event.RequestType === "Delete" ? {} : Indexes ?? {};
+  const table = await describeTable(TableName);
+  if (isTableBusy(table)) {
+    console.log("Table busy, waiting...");
+    return { IsComplete: false };
+  }
+  if (gsiMatchesDesired(table, desired)) {
+    console.log("\u2705 All GSIs match desired state");
+    return { IsComplete: true };
+  }
+  await initiateNextChange(TableName, table, desired);
+  return { IsComplete: false };
+}
+async function initiateNextChange(tableName, table, desired) {
+  const current = getCurrentGSIs(table);
+  const existingAttrMap = /* @__PURE__ */ new Map();
+  for (const attr of table.AttributeDefinitions ?? []) {
+    existingAttrMap.set(attr.AttributeName, attr.AttributeType);
+  }
+  for (const [name, cur] of Object.entries(current)) {
+    const des = desired[name];
+    if (des && (cur.pk !== des.partitionKey || cur.sk !== des.sortKey)) {
+      console.log(`Deleting GSI '${name}' (schema mismatch \u2014 must delete before recreating)`);
+      await dynamodb.send(new import_client_dynamodb.UpdateTableCommand({
+        TableName: tableName,
+        GlobalSecondaryIndexUpdates: [{ Delete: { IndexName: name } }]
+      }));
+      return;
+    }
+  }
+  for (const [name, cfg] of Object.entries(desired)) {
+    if (!current[name]) {
+      console.log(`Creating GSI '${name}'`);
+      const attrDefs = [];
+      attrDefs.push({
+        AttributeName: cfg.partitionKey,
+        AttributeType: existingAttrMap.get(cfg.partitionKey) ?? cfg.partitionKeyType ?? import_client_dynamodb.ScalarAttributeType.S
+      });
+      if (cfg.sortKey) {
+        attrDefs.push({
+          AttributeName: cfg.sortKey,
+          AttributeType: existingAttrMap.get(cfg.sortKey) ?? cfg.sortKeyType ?? import_client_dynamodb.ScalarAttributeType.S
+        });
+      }
+      await dynamodb.send(new import_client_dynamodb.UpdateTableCommand({
+        TableName: tableName,
+        AttributeDefinitions: attrDefs,
+        GlobalSecondaryIndexUpdates: [{
+          Create: {
+            IndexName: name,
+            KeySchema: [
+              { AttributeName: cfg.partitionKey, KeyType: import_client_dynamodb.KeyType.HASH },
+              ...cfg.sortKey ? [{ AttributeName: cfg.sortKey, KeyType: import_client_dynamodb.KeyType.RANGE }] : []
+            ],
+            Projection: { ProjectionType: "ALL" }
+          }
+        }]
+      }));
+      return;
+    }
+  }
+  for (const name of Object.keys(current)) {
+    if (!desired[name]) {
+      console.log(`Deleting GSI '${name}' (no longer desired)`);
+      await dynamodb.send(new import_client_dynamodb.UpdateTableCommand({
+        TableName: tableName,
+        GlobalSecondaryIndexUpdates: [{ Delete: { IndexName: name } }]
+      }));
+      return;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  handler,
+  isCompleteHandler
+});

package/dist/gsi-manager-lambda.d.ts

@@ -0,0 +1,26 @@
+interface IndexConfig {
+    partitionKey: string;
+    sortKey?: string;
+    partitionKeyType?: 'S' | 'N' | 'B';
+    sortKeyType?: 'S' | 'N' | 'B';
+}
+interface CfnEvent {
+    RequestType: 'Create' | 'Update' | 'Delete';
+    PhysicalResourceId?: string;
+    ResourceProperties: {
+        TableName: string;
+        Indexes: Record<string, IndexConfig>;
+        SandboxMode?: string;
+    };
+}
+export declare function handler(event: CfnEvent): Promise<{
+    PhysicalResourceId: string;
+    Data: {
+        Status: string;
+    };
+}>;
+export declare function isCompleteHandler(event: any): Promise<{
+    IsComplete: boolean;
+}>;
+export {};
+//# sourceMappingURL=gsi-manager-lambda.d.ts.map

package/dist/gsi-manager-lambda.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gsi-manager-lambda.d.ts","sourceRoot":"","sources":["../src/gsi-manager-lambda.ts"],"names":[],"mappings":"AAkBA,UAAU,WAAW;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACnC,WAAW,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;CAC9B;AAED,UAAU,QAAQ;IACjB,WAAW,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC5C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACrC,WAAW,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACF;AA+HD,wBAAsB,OAAO,CAAC,KAAK,EAAE,QAAQ;;;;;GA+B5C;AAQD,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,GAAG;;GAuBjD"}

package/dist/gsi-manager-lambda.js

@@ -0,0 +1,244 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { DynamoDBClient, DescribeTableCommand, UpdateTableCommand, DeleteTableCommand, CreateTableCommand, ScanCommand, BatchWriteItemCommand, BillingMode, ScalarAttributeType, KeyType, } from '@aws-sdk/client-dynamodb';
+const dynamodb = new DynamoDBClient({});
+// ── Helpers ─────────────────────────────────────────────────────────────────
+async function describeTable(tableName) {
+    const result = await dynamodb.send(new DescribeTableCommand({ TableName: tableName }));
+    return result.Table;
+}
+function getCurrentGSIs(table) {
+    const gsis = {};
+    for (const gsi of table.GlobalSecondaryIndexes ?? []) {
+        const pk = gsi.KeySchema?.find((k) => k.KeyType === 'HASH')?.AttributeName;
+        const sk = gsi.KeySchema?.find((k) => k.KeyType === 'RANGE')?.AttributeName;
+        if (pk)
+            gsis[gsi.IndexName] = { pk, sk };
+    }
+    return gsis;
+}
+function gsiMatchesDesired(table, desired) {
+    const current = getCurrentGSIs(table);
+    const currentNames = Object.keys(current);
+    const desiredNames = Object.keys(desired);
+    if (currentNames.length !== desiredNames.length)
+        return false;
+    for (const name of desiredNames) {
+        if (!current[name])
+            return false;
+        if (current[name].pk !== desired[name].partitionKey)
+            return false;
+        if (current[name].sk !== desired[name].sortKey)
+            return false;
+    }
+    return true;
+}
+function isTableBusy(table) {
+    if (table.TableStatus !== 'ACTIVE')
+        return true;
+    for (const gsi of table.GlobalSecondaryIndexes ?? []) {
+        if (gsi.IndexStatus !== 'ACTIVE')
+            return true;
+    }
+    return false;
+}
+// ── Sandbox fast path ───────────────────────────────────────────────────────
+async function recreateTableWithIndexes(tableName, desired) {
+    console.log('⚠️  SANDBOX MODE: Recreating table with all GSIs (fast path)');
+    const table = await describeTable(tableName);
+    // Backup data
+    const items = [];
+    let lastKey;
+    do {
+        const result = await dynamodb.send(new ScanCommand({ TableName: tableName, ExclusiveStartKey: lastKey }));
+        items.push(...(result.Items ?? []));
+        lastKey = result.LastEvaluatedKey;
+    } while (lastKey);
+    console.log(`Backed up ${items.length} items`);
+    // Delete table
+    await dynamodb.send(new DeleteTableCommand({ TableName: tableName }));
+    while (true) {
+        try {
+            await dynamodb.send(new DescribeTableCommand({ TableName: tableName }));
+            await new Promise(r => setTimeout(r, 3000));
+        }
+        catch (e) {
+            if (e.name === 'ResourceNotFoundException')
+                break;
+            throw e;
+        }
+    }
+    // Collect all attribute definitions needed for keys
+    const usedAttrs = new Set();
+    table.KeySchema.forEach((k) => usedAttrs.add(k.AttributeName));
+    for (const cfg of Object.values(desired)) {
+        usedAttrs.add(cfg.partitionKey);
+        if (cfg.sortKey)
+            usedAttrs.add(cfg.sortKey);
+    }
+    const existingAttrMap = new Map();
+    for (const attr of table.AttributeDefinitions ?? []) {
+        existingAttrMap.set(attr.AttributeName, attr.AttributeType);
+    }
+    const attrDefs = [...usedAttrs].map(name => ({
+        AttributeName: name,
+        AttributeType: (existingAttrMap.get(name) ??
+            Object.values(desired).find(c => c.partitionKey === name)?.partitionKeyType ??
+            Object.values(desired).find(c => c.sortKey === name)?.sortKeyType ??
+            ScalarAttributeType.S),
+    }));
+    // Recreate with all GSIs
+    await dynamodb.send(new CreateTableCommand({
+        TableName: tableName,
+        KeySchema: table.KeySchema,
+        AttributeDefinitions: attrDefs,
+        BillingMode: BillingMode.PAY_PER_REQUEST,
+        GlobalSecondaryIndexes: Object.entries(desired).map(([name, cfg]) => ({
+            IndexName: name,
+            KeySchema: [
+                { AttributeName: cfg.partitionKey, KeyType: KeyType.HASH },
+                ...(cfg.sortKey ? [{ AttributeName: cfg.sortKey, KeyType: KeyType.RANGE }] : []),
+            ],
+            Projection: { ProjectionType: 'ALL' },
+        })),
+    }));
+    // Wait for active
+    while (true) {
+        const t = await describeTable(tableName);
+        if (!isTableBusy(t))
+            break;
+        await new Promise(r => setTimeout(r, 3000));
+    }
+    // Restore data
+    for (let i = 0; i < items.length; i += 25) {
+        await dynamodb.send(new BatchWriteItemCommand({
+            RequestItems: { [tableName]: items.slice(i, i + 25).map(item => ({ PutRequest: { Item: item } })) },
+        }));
+    }
+    console.log(`✅ Sandbox: table recreated with ${Object.keys(desired).length} GSIs, ${items.length} items restored`);
+}
+// ── onEvent handler ─────────────────────────────────────────────────────────
+// Called once per Create/Update/Delete. Kicks off the first GSI change (or
+// the sandbox fast path). Returns immediately — isComplete polls for progress.
+export async function handler(event) {
+    console.log('onEvent:', JSON.stringify(event, null, 2));
+    const { TableName, Indexes, SandboxMode } = event.ResourceProperties;
+    const desired = event.RequestType === 'Delete' ? {} : (Indexes ?? {});
+    const isSandbox = SandboxMode === 'true';
+    // On Create, we set the physical resource ID. On Update/Delete, we must
+    // echo back the original ID — CloudFormation rejects changes to it.
+    const physicalId = event.PhysicalResourceId ?? TableName;
+    // Check if already done
+    const table = await describeTable(TableName);
+    if (gsiMatchesDesired(table, desired) && !isTableBusy(table)) {
+        console.log('Already in desired state');
+        return { PhysicalResourceId: physicalId, Data: { Status: 'COMPLETE' } };
+    }
+    // Sandbox fast path: drop and recreate with all GSIs at once
+    if (isSandbox && Object.keys(desired).length > 0) {
+        await recreateTableWithIndexes(TableName, desired);
+        return { PhysicalResourceId: physicalId, Data: { Status: 'COMPLETE' } };
+    }
+    // Production path: initiate the first GSI change if table is idle.
+    // If table is busy (prior GSI still updating), just return — isComplete will poll.
+    if (!isTableBusy(table)) {
+        await initiateNextChange(TableName, table, desired);
+    }
+    return { PhysicalResourceId: physicalId, Data: { Status: 'IN_PROGRESS' } };
+}
+// ── isComplete handler ──────────────────────────────────────────────────────
+// Called periodically by the Provider framework. Checks if the table matches
+// the desired state. If a GSI update is in progress, returns IsComplete=false.
+// If the table is idle but doesn't match, initiates the next change.
+// Creations are performed before deletions when possible.
+export async function isCompleteHandler(event) {
+    console.log('isComplete:', JSON.stringify(event, null, 2));
+    const { TableName, Indexes, SandboxMode } = event.ResourceProperties;
+    const desired = event.RequestType === 'Delete' ? {} : (Indexes ?? {});
+    const table = await describeTable(TableName);
+    // If a GSI operation is in progress, wait for it
+    if (isTableBusy(table)) {
+        console.log('Table busy, waiting...');
+        return { IsComplete: false };
+    }
+    // If we match the desired state, we're done
+    if (gsiMatchesDesired(table, desired)) {
+        console.log('✅ All GSIs match desired state');
+        return { IsComplete: true };
+    }
+    // Table is idle but doesn't match — initiate the next change
+    await initiateNextChange(TableName, table, desired);
+    return { IsComplete: false };
+}
+// ── Initiate next GSI change ────────────────────────────────────────────────
+// Performs creations before deletions when possible.
+//
+// Edge case where deletion must happen first: if a desired GSI has the same
+// name as an existing GSI but different key schema. DynamoDB doesn't support
+// in-place GSI modification — the old one must be deleted before the new one
+// can be created. We detect this by checking if a current GSI name exists in
+// desired but with a different key schema.
+async function initiateNextChange(tableName, table, desired) {
+    const current = getCurrentGSIs(table);
+    const existingAttrMap = new Map();
+    for (const attr of table.AttributeDefinitions ?? []) {
+        existingAttrMap.set(attr.AttributeName, attr.AttributeType);
+    }
+    // 1. Check for schema-mismatched GSIs that must be deleted before recreation.
+    //    These take priority because the creation of the replacement can't proceed
+    //    until the old one is gone.
+    for (const [name, cur] of Object.entries(current)) {
+        const des = desired[name];
+        if (des && (cur.pk !== des.partitionKey || cur.sk !== des.sortKey)) {
+            console.log(`Deleting GSI '${name}' (schema mismatch — must delete before recreating)`);
+            await dynamodb.send(new UpdateTableCommand({
+                TableName: tableName,
+                GlobalSecondaryIndexUpdates: [{ Delete: { IndexName: name } }],
+            }));
+            return;
+        }
+    }
+    // 2. Create missing GSIs (creations before deletions)
+    for (const [name, cfg] of Object.entries(desired)) {
+        if (!current[name]) {
+            console.log(`Creating GSI '${name}'`);
+            const attrDefs = [];
+            attrDefs.push({
+                AttributeName: cfg.partitionKey,
+                AttributeType: (existingAttrMap.get(cfg.partitionKey) ?? cfg.partitionKeyType ?? ScalarAttributeType.S),
+            });
+            if (cfg.sortKey) {
+                attrDefs.push({
+                    AttributeName: cfg.sortKey,
+                    AttributeType: (existingAttrMap.get(cfg.sortKey) ?? cfg.sortKeyType ?? ScalarAttributeType.S),
+                });
+            }
+            await dynamodb.send(new UpdateTableCommand({
+                TableName: tableName,
+                AttributeDefinitions: attrDefs,
+                GlobalSecondaryIndexUpdates: [{
+                        Create: {
+                            IndexName: name,
+                            KeySchema: [
+                                { AttributeName: cfg.partitionKey, KeyType: KeyType.HASH },
+                                ...(cfg.sortKey ? [{ AttributeName: cfg.sortKey, KeyType: KeyType.RANGE }] : []),
+                            ],
+                            Projection: { ProjectionType: 'ALL' },
+                        },
+                    }],
+            }));
+            return;
+        }
+    }
+    // 3. Delete extra GSIs (only after all creations are done)
+    for (const name of Object.keys(current)) {
+        if (!desired[name]) {
+            console.log(`Deleting GSI '${name}' (no longer desired)`);
+            await dynamodb.send(new UpdateTableCommand({
+                TableName: tableName,
+                GlobalSecondaryIndexUpdates: [{ Delete: { IndexName: name } }],
+            }));
+            return;
+        }
+    }
+}