alchemy 2.0.0-beta.3 → 2.0.0-beta.31

package/src/AWS/DynamoDB/Table.ts

@@ -15,13 +15,14 @@ import { createPhysicalName } from "../../PhysicalName.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import type { Providers } from "../Providers.ts";
+import { Unowned } from "../../AdoptPolicy.ts";
 import {
   createInternalTags,
   createTagsList,
   diffTags,
-  hasTags,
+  hasAlchemyTags,
 } from "../../Tags.ts";
-import type { AccountID } from "../Account.ts";
+import type { AccountID } from "../Environment.ts";
 import type { RegionID } from "../Region.ts";
 
 export type TableName = string;
@@ -115,7 +116,9 @@ export interface Table extends Resource<
  * @section Creating Tables
  * @example Basic Table
  * ```typescript
- * const table = yield* Table("UsersTable", {
+ * import * as DynamoDB from "alchemy/AWS/DynamoDB";
+ *
+ * const table = yield* DynamoDB.Table("UsersTable", {
  *   partitionKey: "pk",
  *   attributes: {
  *     pk: "S",
@@ -125,7 +128,7 @@ export interface Table extends Resource<
  *
  * @example Table with Sort Key and TTL
  * ```typescript
- * const table = yield* Table("SessionsTable", {
+ * const table = yield* DynamoDB.Table("SessionsTable", {
  *   partitionKey: "userId",
  *   sortKey: "sessionId",
  *   attributes: {
@@ -140,18 +143,69 @@ export interface Table extends Resource<
  * });
  * ```
  *
- * @section Runtime Operations
- * @example Read an Item
+ * @example Table with Global Secondary Index
  * ```typescript
- * const getItem = yield* GetItem.bind(table);
- *
- * const response = yield* getItem({
- *   Key: {
- *     pk: { S: "user#123" },
+ * const table = yield* DynamoDB.Table("OrdersTable", {
+ *   partitionKey: "pk",
+ *   sortKey: "sk",
+ *   attributes: {
+ *     pk: "S",
+ *     sk: "S",
+ *     gsi1pk: "S",
+ *     gsi1sk: "S",
  *   },
- *   ConsistentRead: true,
+ *   globalSecondaryIndexes: [{
+ *     IndexName: "GSI1",
+ *     KeySchema: [
+ *       { AttributeName: "gsi1pk", KeyType: "HASH" },
+ *       { AttributeName: "gsi1sk", KeyType: "RANGE" },
+ *     ],
+ *     Projection: { ProjectionType: "ALL" },
+ *   }],
  * });
  * ```
+ *
+ * @section Runtime Operations
+ * Bind DynamoDB operations in the init phase and use them in runtime
+ * handlers. Bindings inject the table name and grant scoped IAM
+ * permissions automatically.
+ *
+ * @example Read and write items
+ * ```typescript
+ * // init
+ * const getItem = yield* DynamoDB.GetItem.bind(table);
+ * const putItem = yield* DynamoDB.PutItem.bind(table);
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     // runtime
+ *     yield* putItem({
+ *       Item: { pk: { S: "user#123" }, name: { S: "Alice" } },
+ *     });
+ *     const result = yield* getItem({
+ *       Key: { pk: { S: "user#123" } },
+ *     });
+ *     return yield* HttpServerResponse.json(result.Item);
+ *   }),
+ * };
+ * ```
+ *
+ * @section DynamoDB Streams
+ * Process change data capture events from a DynamoDB table using a
+ * Lambda event source mapping. The stream is enabled automatically
+ * through the binding contract.
+ *
+ * @example Process table changes
+ * ```typescript
+ * // init
+ * yield* DynamoDB.streams(table, {
+ *   StreamViewType: "NEW_AND_OLD_IMAGES",
+ * }).process(
+ *   Effect.fn(function* (record) {
+ *     yield* Effect.log(`${record.eventName}: ${JSON.stringify(record.dynamodb)}`);
+ *   }),
+ * );
+ * ```
  */
 export const Table = Resource<Table>("AWS.DynamoDB.Table");
 
@@ -199,31 +253,13 @@ export const TableProvider = () =>
           }))
           .sort((a, b) => a.AttributeName.localeCompare(b.AttributeName));
 
-      const resolveTableIfOwned = (id: string, tableName: string) =>
-        // if it already exists, let's see if it contains tags indicating we (this app+stage) owns it
-        // that would indicate we are in a partial state and can safely take control
-        dynamodb.describeTable({ TableName: tableName }).pipe(
-          Effect.flatMap((r) =>
-            dynamodb
-              .listTagsOfResource({
-                // oxlint-disable-next-line no-non-null-asserted-optional-chain
-                ResourceArn: r.Table?.TableArn!,
-              })
-              .pipe(
-                Effect.map((tags) => [r, tags.Tags] as const),
-                Effect.flatMap(
-                  Effect.fn(function* ([r, tags]) {
-                    if (hasTags(yield* createInternalTags(id), tags)) {
-                      return r.Table!;
-                    }
-                    return yield* Effect.fail(
-                      new Error("Table tags do not match expected values"),
-                    );
-                  }),
-                ),
-              ),
-          ),
-        );
+      const adoptExistingTable = (tableName: string) =>
+        // The engine has cleared us via `read` (foreign-tagged tables are
+        // surfaced as `Unowned`). On a race between read and create, just
+        // describe the existing table and continue.
+        dynamodb
+          .describeTable({ TableName: tableName })
+          .pipe(Effect.map((r) => r.Table!));
 
       const createTags = Effect.fn(function* (
         id: string,
@@ -607,6 +643,13 @@ export const TableProvider = () =>
           }
         });
 
+      // For read, we want `ResourceNotFoundException` to propagate immediately
+      // (the table doesn't exist — this is the cold-start adoption "no
+      // resource" signal). Only retry on transient control-plane errors.
+      const isRetryableReadError = (error: { _tag?: string }) =>
+        error._tag === "InternalServerError" ||
+        error._tag === "LimitExceededException";
+
       const readTableState = (tableName: string) =>
         Effect.gen(function* () {
           const response = yield* dynamodb
@@ -615,7 +658,7 @@ export const TableProvider = () =>
             })
             .pipe(
               Effect.retry({
-                while: isRetryableControlPlaneError,
+                while: isRetryableReadError,
                 schedule: Schedule.exponential(250).pipe(
                   Schedule.both(Schedule.recurs(30)),
                 ),
@@ -628,35 +671,51 @@ export const TableProvider = () =>
             );
           }
 
-          const [tagsResult, continuousBackupsResult] = yield* Effect.all([
-            dynamodb
-              .listTagsOfResource({
-                ResourceArn: table.TableArn,
-              })
-              .pipe(
-                Effect.retry({
-                  while: isRetryableControlPlaneError,
-                  schedule: Schedule.exponential(250).pipe(
-                    Schedule.both(Schedule.recurs(30)),
+          const [tagsResult, continuousBackupsResult, ttlResult] =
+            yield* Effect.all([
+              dynamodb
+                .listTagsOfResource({
+                  ResourceArn: table.TableArn,
+                })
+                .pipe(
+                  Effect.retry({
+                    while: isRetryableReadError,
+                    schedule: Schedule.exponential(250).pipe(
+                      Schedule.both(Schedule.recurs(30)),
+                    ),
+                  }),
+                ),
+              dynamodb
+                .describeContinuousBackups({
+                  TableName: tableName,
+                })
+                .pipe(
+                  Effect.retry({
+                    while: (e) => e._tag === "InternalServerError",
+                    schedule: Schedule.exponential(250).pipe(
+                      Schedule.both(Schedule.recurs(30)),
+                    ),
+                  }),
+                  Effect.catchTag("TableNotFoundException", () =>
+                    Effect.succeed({ ContinuousBackupsDescription: undefined }),
                   ),
-                }),
-              ),
-            dynamodb
-              .describeContinuousBackups({
-                TableName: tableName,
-              })
-              .pipe(
-                Effect.retry({
-                  while: (e) => e._tag === "InternalServerError",
-                  schedule: Schedule.exponential(250).pipe(
-                    Schedule.both(Schedule.recurs(30)),
+                ),
+              dynamodb
+                .describeTimeToLive({
+                  TableName: tableName,
+                })
+                .pipe(
+                  Effect.retry({
+                    while: isRetryableReadError,
+                    schedule: Schedule.exponential(250).pipe(
+                      Schedule.both(Schedule.recurs(30)),
+                    ),
+                  }),
+                  Effect.catchTag("ResourceNotFoundException", () =>
+                    Effect.succeed({ TimeToLiveDescription: undefined }),
                   ),
-                }),
-                Effect.catchTag("TableNotFoundException", () =>
-                  Effect.succeed({ ContinuousBackupsDescription: undefined }),
                 ),
-              ),
-          ]);
+            ]);
 
           return {
             table,
@@ -666,6 +725,7 @@ export const TableProvider = () =>
             pointInTimeRecoveryDescription:
               continuousBackupsResult.ContinuousBackupsDescription
                 ?.PointInTimeRecoveryDescription,
+            timeToLiveDescription: ttlResult.TimeToLiveDescription,
           };
         }).pipe(
           Effect.catchTag("ResourceNotFoundException", () =>
@@ -728,6 +788,70 @@ export const TableProvider = () =>
         JSON.stringify(normalizeProjection(left.Projection)) ===
           JSON.stringify(normalizeProjection(right.Projection));
 
+      // The describe response includes server-side bookkeeping fields
+      // (`NumberOfDecreasesToday`, `LastIncreaseDateTime`, etc.) that the
+      // request shape doesn't. For PAY_PER_REQUEST tables it also reports
+      // a zero-throughput object. Normalize both sides to the user-settable
+      // fields so we don't fire a phantom UpdateGlobalSecondaryIndex with
+      // `ProvisionedThroughput: undefined` (which AWS rejects with
+      // ValidationException).
+      const normalizeProvisioned = (
+        pt:
+          | { ReadCapacityUnits?: number; WriteCapacityUnits?: number }
+          | undefined,
+      ) => {
+        if (
+          !pt ||
+          ((pt.ReadCapacityUnits ?? 0) === 0 &&
+            (pt.WriteCapacityUnits ?? 0) === 0)
+        ) {
+          return undefined;
+        }
+        return {
+          ReadCapacityUnits: pt.ReadCapacityUnits,
+          WriteCapacityUnits: pt.WriteCapacityUnits,
+        };
+      };
+
+      const normalizeOnDemand = (
+        od:
+          | {
+              MaxReadRequestUnits?: number;
+              MaxWriteRequestUnits?: number;
+            }
+          | undefined,
+      ) => {
+        if (
+          !od ||
+          ((od.MaxReadRequestUnits ?? -1) < 0 &&
+            (od.MaxWriteRequestUnits ?? -1) < 0)
+        ) {
+          return undefined;
+        }
+        return {
+          MaxReadRequestUnits: od.MaxReadRequestUnits,
+          MaxWriteRequestUnits: od.MaxWriteRequestUnits,
+        };
+      };
+
+      const normalizeWarm = (
+        wt:
+          | { ReadUnitsPerSecond?: number; WriteUnitsPerSecond?: number }
+          | undefined,
+      ) => {
+        if (
+          !wt ||
+          ((wt.ReadUnitsPerSecond ?? 0) === 0 &&
+            (wt.WriteUnitsPerSecond ?? 0) === 0)
+        ) {
+          return undefined;
+        }
+        return {
+          ReadUnitsPerSecond: wt.ReadUnitsPerSecond,
+          WriteUnitsPerSecond: wt.WriteUnitsPerSecond,
+        };
+      };
+
       const diffGlobalSecondaryIndexes = (
         olds: readonly DynamoDB.GlobalSecondaryIndex[] | undefined,
         news: readonly DynamoDB.GlobalSecondaryIndex[] | undefined,
@@ -753,14 +877,28 @@ export const TableProvider = () =>
             continue;
           }
 
-          if (
-            JSON.stringify(oldIndex.ProvisionedThroughput) !==
-              JSON.stringify(newIndex.ProvisionedThroughput) ||
-            JSON.stringify(oldIndex.OnDemandThroughput) !==
-              JSON.stringify(newIndex.OnDemandThroughput) ||
-            JSON.stringify(oldIndex.WarmThroughput) !==
-              JSON.stringify(newIndex.WarmThroughput)
-          ) {
+          // Only emit an Update when the user has explicitly set a
+          // throughput value AND it differs from observed. Cloud-side
+          // defaults (AWS auto-assigns ProvisionedThroughput/WarmThroughput
+          // values for PAY_PER_REQUEST tables) should not trigger phantom
+          // updates against an undefined desired value.
+          const provDiff =
+            newIndex.ProvisionedThroughput !== undefined &&
+            JSON.stringify(
+              normalizeProvisioned(oldIndex.ProvisionedThroughput),
+            ) !==
+              JSON.stringify(
+                normalizeProvisioned(newIndex.ProvisionedThroughput),
+              );
+          const odDiff =
+            newIndex.OnDemandThroughput !== undefined &&
+            JSON.stringify(normalizeOnDemand(oldIndex.OnDemandThroughput)) !==
+              JSON.stringify(normalizeOnDemand(newIndex.OnDemandThroughput));
+          const wtDiff =
+            newIndex.WarmThroughput !== undefined &&
+            JSON.stringify(normalizeWarm(oldIndex.WarmThroughput)) !==
+              JSON.stringify(normalizeWarm(newIndex.WarmThroughput));
+          if (provDiff || odDiff || wtDiff) {
             updates.push({
               Update: {
                 IndexName: indexName,
@@ -795,11 +933,21 @@ export const TableProvider = () =>
 
       return Table.Provider.of({
         stables: ["tableName", "tableId", "tableArn"],
-        read: Effect.fn(function* ({ output }) {
-          if (!output) return undefined;
-          const state = yield* readTableState(output.tableName);
+        read: Effect.fn(function* ({ id, olds, output }) {
+          const tableName =
+            output?.tableName ??
+            (olds ? yield* createTableName(id, olds) : undefined);
+          if (!tableName) return undefined;
+          const state = yield* readTableState(tableName).pipe(
+            Effect.catchTag("ResourceNotFoundException", () =>
+              Effect.succeed(undefined),
+            ),
+          );
           if (!state) return undefined;
-          return toAttrs(state);
+          const attrs = toAttrs(state);
+          return (yield* hasAlchemyTags(id, state.tags as any))
+            ? attrs
+            : Unowned(attrs);
         }),
         diff: Effect.fn(function* ({ news, olds }) {
           if (!isResolved(news)) return undefined;
@@ -836,96 +984,85 @@ export const TableProvider = () =>
           // 1. if you change ImportSourceSpecification
         }),
 
-        create: Effect.fn(function* ({ id, news, session, bindings }) {
-          const tableName = yield* createTableName(id, news);
-          const allTags = yield* createTags(id, news.tags);
-          const streamSpecification =
+        reconcile: Effect.fn(function* ({
+          id,
+          output,
+          news,
+          session,
+          bindings,
+        }) {
+          const tableName =
+            output?.tableName ?? (yield* createTableName(id, news));
+          const desiredTags = yield* createTags(id, news.tags);
+          const desiredStreamSpecification =
             yield* resolveStreamSpecification(bindings);
-          yield* session.note(
-            `Table ${tableName}: resolved stream specification ${JSON.stringify(streamSpecification)}`,
-          );
 
-          yield* dynamodb
-            .createTable({
-              TableName: tableName,
-              TableClass: news.tableClass,
-              KeySchema: toKeySchema(news),
-              AttributeDefinitions: toAttributeDefinitions(news.attributes),
-              LocalSecondaryIndexes: news.localSecondaryIndexes,
-              GlobalSecondaryIndexes: news.globalSecondaryIndexes,
-              BillingMode: news.billingMode ?? "PAY_PER_REQUEST",
-              SSESpecification: news.sseSpecification,
-              StreamSpecification: streamSpecification,
-              WarmThroughput: news.warmThroughput,
-              DeletionProtectionEnabled: news.deletionProtectionEnabled,
-              OnDemandThroughput: news.onDemandThroughput,
-              ProvisionedThroughput: news.provisionedThroughput,
-              Tags: createTagsList(allTags),
-            })
-            .pipe(
-              Effect.retry({
-                while: (e) =>
-                  e._tag === "LimitExceededException" ||
-                  e._tag === "InternalServerError",
-                schedule: Schedule.exponential(100),
-              }),
-              Effect.catchTag("ResourceInUseException", () =>
-                resolveTableIfOwned(id, tableName),
-              ),
-            );
+          // Observe cloud state. `output` is treated as a cache for the table
+          // name; the table's actual existence and configuration are fetched
+          // fresh so the reconciler converges regardless of drift, adoption,
+          // or a partially-completed prior run.
+          let state = yield* readTableState(tableName);
 
-          yield* waitForTableActive(session, tableName);
-
-          if (news.pointInTimeRecoverySpecification) {
-            yield* updateContinuousBackups(
-              tableName,
-              news.pointInTimeRecoverySpecification,
+          if (state === undefined) {
+            yield* session.note(
+              `Table ${tableName}: creating with stream specification ${JSON.stringify(desiredStreamSpecification)}`,
             );
-          }
+            yield* dynamodb
+              .createTable({
+                TableName: tableName,
+                TableClass: news.tableClass,
+                KeySchema: toKeySchema(news),
+                AttributeDefinitions: toAttributeDefinitions(news.attributes),
+                LocalSecondaryIndexes: news.localSecondaryIndexes,
+                GlobalSecondaryIndexes: news.globalSecondaryIndexes,
+                BillingMode: news.billingMode ?? "PAY_PER_REQUEST",
+                SSESpecification: news.sseSpecification,
+                StreamSpecification: desiredStreamSpecification,
+                WarmThroughput: news.warmThroughput,
+                DeletionProtectionEnabled: news.deletionProtectionEnabled,
+                OnDemandThroughput: news.onDemandThroughput,
+                ProvisionedThroughput: news.provisionedThroughput,
+                Tags: createTagsList(desiredTags),
+              })
+              .pipe(
+                Effect.retry({
+                  while: (e) =>
+                    e._tag === "LimitExceededException" ||
+                    e._tag === "InternalServerError",
+                  schedule: Schedule.exponential(100),
+                }),
+                // A peer reconciler created the table between our observe and
+                // create; describe it and continue with the sync path.
+                Effect.catchTag("ResourceInUseException", () =>
+                  adoptExistingTable(tableName),
+                ),
+              );
 
-          if (news.timeToLiveSpecification) {
-            yield* updateTimeToLive(tableName, news.timeToLiveSpecification);
-          }
+            yield* waitForTableActive(session, tableName);
 
-          if ((news.globalSecondaryIndexes?.length ?? 0) > 0) {
-            yield* waitForGlobalSecondaryIndexesStable(
-              session,
-              tableName,
-              news.globalSecondaryIndexes?.map((index) => index.IndexName) ??
-                [],
-            );
-          }
+            if ((news.globalSecondaryIndexes?.length ?? 0) > 0) {
+              yield* waitForGlobalSecondaryIndexesStable(
+                session,
+                tableName,
+                news.globalSecondaryIndexes?.map((index) => index.IndexName) ??
+                  [],
+              );
+            }
 
-          const state = yield* readTableState(tableName);
-          if (!state) {
-            return yield* Effect.fail(
-              new Error(`Failed to read created table ${tableName}`),
-            );
+            state = yield* readTableState(tableName);
+            if (!state) {
+              return yield* Effect.fail(
+                new Error(`Failed to read created table ${tableName}`),
+              );
+            }
           }
 
-          yield* session.note(state.table.TableArn!);
-
-          return {
-            ...toAttrs(state),
-            tags: allTags,
-          };
-        }),
-
-        update: Effect.fn(function* ({
-          id,
-          output,
-          news,
-          olds,
-          session,
-          bindings,
-        }) {
-          const desiredStreamSpecification =
-            yield* resolveStreamSpecification(bindings);
+          // Sync stream specification — observed ↔ desired.
+          //
+          // SQL of stream changes: changing the StreamViewType requires a
+          // disable→enable sequence; AWS rejects an in-place view-type change.
           const currentStreamSpecification = normalizeStreamSpecification(
-            output.streamSpecification,
-          );
-          yield* session.note(
-            `Table ${output.tableName}: current stream=${JSON.stringify(currentStreamSpecification)} desired stream=${JSON.stringify(desiredStreamSpecification)}`,
+            state.table.StreamSpecification,
           );
           const streamViewTypeChanged =
             currentStreamSpecification?.StreamEnabled === true &&
@@ -935,56 +1072,10 @@ export const TableProvider = () =>
 
           if (streamViewTypeChanged) {
             yield* dynamodb.updateTable({
-              TableName: output.tableName,
-              StreamSpecification: {
-                StreamEnabled: false,
-              },
-            });
-            yield* waitForTableActive(session, output.tableName);
-          }
-
-          const { updates: globalSecondaryIndexUpdates } =
-            diffGlobalSecondaryIndexes(
-              olds.globalSecondaryIndexes,
-              news.globalSecondaryIndexes,
-            );
-
-          const hasBaseUpdate = havePropsChanged(
-            {
-              tableClass: olds.tableClass,
-              attributes: olds.attributes,
-              billingMode: olds.billingMode ?? "PAY_PER_REQUEST",
-              sseSpecification: olds.sseSpecification,
-              warmThroughput: olds.warmThroughput,
-              deletionProtectionEnabled: olds.deletionProtectionEnabled,
-              onDemandThroughput: olds.onDemandThroughput,
-              provisionedThroughput: olds.provisionedThroughput,
-            },
-            {
-              tableClass: news.tableClass,
-              attributes: news.attributes,
-              billingMode: news.billingMode ?? "PAY_PER_REQUEST",
-              sseSpecification: news.sseSpecification,
-              warmThroughput: news.warmThroughput,
-              deletionProtectionEnabled: news.deletionProtectionEnabled,
-              onDemandThroughput: news.onDemandThroughput,
-              provisionedThroughput: news.provisionedThroughput,
-            },
-          );
-
-          if (hasBaseUpdate) {
-            yield* dynamodb.updateTable({
-              TableName: output.tableName,
-              TableClass: news.tableClass,
-              AttributeDefinitions: toAttributeDefinitions(news.attributes),
-              BillingMode: news.billingMode ?? "PAY_PER_REQUEST",
-              SSESpecification: news.sseSpecification,
-              WarmThroughput: news.warmThroughput,
-              DeletionProtectionEnabled: news.deletionProtectionEnabled,
-              OnDemandThroughput: news.onDemandThroughput,
-              ProvisionedThroughput: news.provisionedThroughput,
+              TableName: tableName,
+              StreamSpecification: { StreamEnabled: false },
             });
-            yield* waitForTableActive(session, output.tableName);
+            yield* waitForTableActive(session, tableName);
           }
 
           if (
@@ -994,17 +1085,30 @@ export const TableProvider = () =>
             )
           ) {
             yield* session.note(
-              `Table ${output.tableName}: updating stream configuration`,
+              `Table ${tableName}: updating stream configuration`,
             );
             yield* dynamodb.updateTable({
-              TableName: output.tableName,
+              TableName: tableName,
               StreamSpecification: desiredStreamSpecification ?? {
                 StreamEnabled: false,
               },
             });
-            yield* waitForTableActive(session, output.tableName);
+            yield* waitForTableActive(session, tableName);
           }
 
+          // Sync GSIs — diff observed cloud state against desired and apply
+          // each delta serially. AWS only accepts one GSI change per
+          // updateTable call. The diff function only reads fields shared
+          // between `GlobalSecondaryIndex` and `GlobalSecondaryIndexDescription`
+          // (IndexName, KeySchema, Projection, throughputs), so the cast is safe.
+          const { updates: globalSecondaryIndexUpdates } =
+            diffGlobalSecondaryIndexes(
+              state.table.GlobalSecondaryIndexes as
+                | readonly DynamoDB.GlobalSecondaryIndex[]
+                | undefined,
+              news.globalSecondaryIndexes,
+            );
+
           for (const globalSecondaryIndexUpdate of globalSecondaryIndexUpdates) {
             const action = globalSecondaryIndexUpdate.Create
               ? `create ${globalSecondaryIndexUpdate.Create.IndexName}`
@@ -1012,83 +1116,178 @@ export const TableProvider = () =>
                 ? `update ${globalSecondaryIndexUpdate.Update.IndexName}`
                 : `delete ${globalSecondaryIndexUpdate.Delete!.IndexName}`;
             yield* session.note(
-              `Table ${output.tableName}: applying GSI update (${action})`,
+              `Table ${tableName}: applying GSI update (${action})`,
             );
             yield* dynamodb.updateTable({
-              TableName: output.tableName,
+              TableName: tableName,
               AttributeDefinitions: toAttributeDefinitions(news.attributes),
               GlobalSecondaryIndexUpdates: [globalSecondaryIndexUpdate],
             });
-            yield* waitForTableActive(session, output.tableName);
+            yield* waitForTableActive(session, tableName);
           }
 
           if (globalSecondaryIndexUpdates.length > 0) {
+            const expectedNames =
+              news.globalSecondaryIndexes?.map((index) => index.IndexName) ??
+              [];
             yield* session.note(
-              `Table ${output.tableName}: waiting for GSIs to stabilize (${(news.globalSecondaryIndexes?.map((index) => index.IndexName) ?? []).join(", ") || "none"})`,
+              `Table ${tableName}: waiting for GSIs to stabilize (${expectedNames.join(", ") || "none"})`,
             );
             yield* waitForGlobalSecondaryIndexesStable(
               session,
-              output.tableName,
-              news.globalSecondaryIndexes?.map((index) => index.IndexName) ??
-                [],
+              tableName,
+              expectedNames,
             );
-            yield* session.note(`Table ${output.tableName}: GSIs stabilized`);
+            yield* session.note(`Table ${tableName}: GSIs stabilized`);
           }
 
+          // Sync base attributes — observed ↔ desired.
+          const desiredBillingMode = news.billingMode ?? "PAY_PER_REQUEST";
+          const observedBillingMode =
+            state.table.BillingModeSummary?.BillingMode ?? "PAY_PER_REQUEST";
+          const observedProvisionedThroughput = state.table
+            .ProvisionedThroughput
+            ? {
+                ReadCapacityUnits:
+                  state.table.ProvisionedThroughput.ReadCapacityUnits,
+                WriteCapacityUnits:
+                  state.table.ProvisionedThroughput.WriteCapacityUnits,
+              }
+            : undefined;
+          const baseChanged = havePropsChanged(
+            {
+              tableClass: state.table.TableClassSummary?.TableClass,
+              billingMode: observedBillingMode,
+              deletionProtectionEnabled:
+                state.table.DeletionProtectionEnabled ?? false,
+              provisionedThroughput:
+                desiredBillingMode === "PROVISIONED"
+                  ? observedProvisionedThroughput
+                  : undefined,
+            },
+            {
+              tableClass: news.tableClass,
+              billingMode: desiredBillingMode,
+              deletionProtectionEnabled:
+                news.deletionProtectionEnabled ?? false,
+              provisionedThroughput:
+                desiredBillingMode === "PROVISIONED"
+                  ? news.provisionedThroughput
+                  : undefined,
+            },
+          );
+
+          if (baseChanged) {
+            yield* dynamodb.updateTable({
+              TableName: tableName,
+              TableClass: news.tableClass,
+              AttributeDefinitions: toAttributeDefinitions(news.attributes),
+              BillingMode: desiredBillingMode,
+              SSESpecification: news.sseSpecification,
+              WarmThroughput: news.warmThroughput,
+              DeletionProtectionEnabled: news.deletionProtectionEnabled,
+              OnDemandThroughput: news.onDemandThroughput,
+              ProvisionedThroughput: news.provisionedThroughput,
+            });
+            yield* waitForTableActive(session, tableName);
+          }
+
+          // Sync TTL — observed ↔ desired.
+          //
+          // updateTimeToLive rejects calls that would not change anything
+          // (e.g. enabling TTL on the same attribute name), so we have to
+          // diff against the current TimeToLiveDescription before calling.
+          const currentTtl = state.timeToLiveDescription;
+          const currentTtlEnabled =
+            currentTtl?.TimeToLiveStatus === "ENABLED" ||
+            currentTtl?.TimeToLiveStatus === "ENABLING";
+          const currentTtlAttribute = currentTtl?.AttributeName;
+          const desiredTtl = news.timeToLiveSpecification;
+          const desiredTtlEnabled = desiredTtl?.Enabled === true;
+          const desiredTtlAttribute = desiredTtl?.AttributeName;
+
           if (
-            news.timeToLiveSpecification &&
-            (news.timeToLiveSpecification.AttributeName !==
-              olds.timeToLiveSpecification?.AttributeName ||
-              news.timeToLiveSpecification?.Enabled !==
-                olds.timeToLiveSpecification?.Enabled)
+            desiredTtlEnabled !== currentTtlEnabled ||
+            (desiredTtlEnabled && desiredTtlAttribute !== currentTtlAttribute)
           ) {
-            // TODO(sam): can this run in parallel?
-            yield* updateTimeToLive(
-              output.tableName,
-              news.timeToLiveSpecification,
-            );
+            if (desiredTtlEnabled) {
+              if (
+                currentTtlEnabled &&
+                currentTtlAttribute !== desiredTtlAttribute
+              ) {
+                // AWS only allows one TTL attribute. We must disable first
+                // before re-enabling on a different attribute.
+                yield* updateTimeToLive(tableName, {
+                  AttributeName: currentTtlAttribute!,
+                  Enabled: false,
+                });
+              }
+              yield* updateTimeToLive(tableName, {
+                AttributeName: desiredTtlAttribute!,
+                Enabled: true,
+              });
+            } else if (currentTtlEnabled && currentTtlAttribute) {
+              yield* updateTimeToLive(tableName, {
+                AttributeName: currentTtlAttribute,
+                Enabled: false,
+              });
+            }
           }
 
+          // Sync PITR — observed ↔ desired.
+          const currentPitrEnabled =
+            state.pointInTimeRecoveryDescription?.PointInTimeRecoveryStatus ===
+            "ENABLED";
+          const desiredPitrEnabled =
+            news.pointInTimeRecoverySpecification?.PointInTimeRecoveryEnabled ??
+            false;
+          const currentPitrPeriod =
+            state.pointInTimeRecoveryDescription?.RecoveryPeriodInDays;
+          const desiredPitrPeriod =
+            news.pointInTimeRecoverySpecification?.RecoveryPeriodInDays;
           if (
-            JSON.stringify(news.pointInTimeRecoverySpecification) !==
-            JSON.stringify(olds.pointInTimeRecoverySpecification)
+            currentPitrEnabled !== desiredPitrEnabled ||
+            (desiredPitrEnabled && currentPitrPeriod !== desiredPitrPeriod)
           ) {
-            yield* updateContinuousBackups(output.tableName, {
-              PointInTimeRecoveryEnabled:
-                news.pointInTimeRecoverySpecification
-                  ?.PointInTimeRecoveryEnabled ?? false,
-              RecoveryPeriodInDays:
-                news.pointInTimeRecoverySpecification?.RecoveryPeriodInDays,
+            yield* updateContinuousBackups(tableName, {
+              PointInTimeRecoveryEnabled: desiredPitrEnabled,
+              RecoveryPeriodInDays: desiredPitrPeriod,
             });
           }
 
-          const oldTags = yield* createTags(id, olds.tags);
-          const newTags = yield* createTags(id, news.tags);
-          const { removed, upsert } = diffTags(oldTags, newTags);
-
+          // Sync tags — diff observed cloud tags against desired.
+          //
+          // Adoption may bring us a table that already has its own tag set;
+          // diffing against `state.tags` (fetched fresh) lets the reconciler
+          // converge ownership without fighting whatever was there before.
+          const { removed, upsert } = diffTags(state.tags, desiredTags);
           if (removed.length > 0) {
             yield* dynamodb.untagResource({
-              ResourceArn: output.tableArn,
+              ResourceArn: state.table.TableArn!,
               TagKeys: removed,
             });
           }
           if (upsert.length > 0) {
             yield* dynamodb.tagResource({
-              ResourceArn: output.tableArn,
+              ResourceArn: state.table.TableArn!,
               Tags: upsert,
             });
           }
 
-          const state = yield* readTableState(output.tableName);
-          if (!state) {
+          // Re-read final state after all sync steps so the returned
+          // attributes reflect the post-reconcile cloud state.
+          const final = yield* readTableState(tableName);
+          if (!final) {
             return yield* Effect.fail(
-              new Error(`Failed to read updated table ${output.tableName}`),
+              new Error(`Failed to read reconciled table ${tableName}`),
             );
           }
 
+          yield* session.note(final.table.TableArn!);
+
           return {
-            ...toAttrs(state),
-            tags: newTags,
+            ...toAttrs(final),
+            tags: desiredTags,
           };
         }),