sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ DynamoDB/ Table.ts

import * as cloudwatch from "@distilled.cloud/aws/cloudwatch";
import type * as DynamoDB from "@distilled.cloud/aws/dynamodb";
import type { TimeToLiveSpecification } from "@distilled.cloud/aws/dynamodb";
import * as dynamodb from "@distilled.cloud/aws/dynamodb";
import { unownedUnlessPrevious } from "alchemy/AdoptPolicy";
import { havePropsChanged, isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, createTagsList, diffTags, hasAlchemyTags } from "alchemy/Tags";
import { toWireDays } from "alchemy/Util/Duration";
import type * as lambda from "aws-lambda";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { AccountID } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";

export class TableUnexpectedResponse extends Data.TaggedError("TableUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export type TableName = string;

export type TableArn = `arn:aws:dynamodb:${RegionID}:${AccountID}:table/${TableName}`;

export type TableRecord<Data> = Omit<lambda.DynamoDBRecord, "dynamodb"> & {
  dynamodb: Omit<lambda.StreamRecord, "NewImage" | "OldImage"> & {
    NewImage?: Data;
    OldImage?: Data;
  };
};

export type TableEvent<Data> = Omit<lambda.DynamoDBStreamEvent, "Records"> & {
  Records: TableRecord<Data>[];
};

export type ScalarAttributeType = "S" | "N" | "B";

export interface PointInTimeRecoverySpecification {
  /**
   * Whether point-in-time recovery (continuous backups) is enabled for the
   * table.
   */
  pointInTimeRecoveryEnabled: boolean;
  /**
   * How far back the table can be restored, e.g. `"7 days"` or
   * `Duration.days(7)`. Rounded to whole days on the wire (1–35 days).
   * @default 35 days
   */
  recoveryPeriod?: Duration.Input;
}

export interface KinesisStreamingDestination {
  /**
   * ARN of the destination Kinesis Data Stream. The stream must be ACTIVE
   * when the destination is enabled (deploy the `AWS.Kinesis.Stream`
   * resource in the same stack and pass `stream.streamArn`).
   */
  streamArn: string;
  /**
   * Precision of the approximate creation timestamp stamped on records
   * delivered to the Kinesis stream. Changing this on an ACTIVE destination
   * updates it in place, but the UPDATING→ACTIVE transition can take several
   * minutes.
   * @default "MILLISECOND"
   */
  approximateCreationDateTimePrecision?: DynamoDB.ApproximateCreationDateTimePrecision;
}

/**
 * One or more attribute names forming an index key. DynamoDB's wire format
 * flattens both key segments into a single ordered `KeySchema` list, but
 * semantically a key is two ordered segments — this type captures one of
 * them. Order is significant: partition attributes are hashed together in
 * declaration order, and sort attributes are queried left-to-right.
 */
export type IndexKey = string | string[];

export interface LocalSecondaryIndexProps {
  /**
   * Name of the index, unique within the table.
   */
  indexName: string;
  /**
   * Sort key attribute name. An LSI always shares the table's partition
   * key, so only the sort key is declared; multi-attribute keys are not
   * supported on LSIs.
   */
  sortKey: string;
  /**
   * Attributes projected from the table into the index.
   */
  projection: DynamoDB.Projection;
}

export interface GlobalSecondaryIndexProps {
  /**
   * Name of the index, unique within the table.
   */
  indexName: string;
  /**
   * Partition key attribute name(s). Up to four attributes may be listed;
   * they are hashed together in declaration order and every one must be
   * specified with an equality condition when querying the index.
   */
  partitionKey: IndexKey;
  /**
   * Optional sort key attribute name(s). Up to four attributes may be
   * listed; items sort by each attribute in declaration order and queries
   * narrow them left-to-right (no gaps, inequality last).
   */
  sortKey?: IndexKey;
  /**
   * Attributes projected from the table into the index.
   */
  projection: DynamoDB.Projection;
  provisionedThroughput?: DynamoDB.ProvisionedThroughput;
  onDemandThroughput?: DynamoDB.OnDemandThroughput;
  warmThroughput?: DynamoDB.WarmThroughput;
}

export type TableProps = {
  /**
   * Name of the table. If omitted, Alchemy generates a deterministic physical
   * name from the stack, stage, and logical ID, suffixed with the instance ID
   * so replacements can create the successor table before deleting the old one.
   *
   * Changing this property replaces the table. If the name is hard-coded,
   * replacement-triggering changes (key schema, attribute types, LSIs, GSI
   * key changes) delete the old table first and then recreate it under the
   * same name, since DynamoDB table names are unique per account/region.
   */
  tableName?: string;
  /**
   * Partition key attribute name for the table.
   *
   * Base-table primary keys are always a single partition attribute plus an
   * optional single sort attribute — DynamoDB supports multi-attribute keys
   * only on global secondary indexes (see `globalSecondaryIndexes`).
   */
  partitionKey: string;
  /**
   * Optional sort key attribute name for the table.
   */
  sortKey?: string;
  /**
   * Attribute definitions used by the primary key and any secondary indexes.
   */
  attributes: Record<string, ScalarAttributeType>;
  /**
   * Local secondary indexes, created with the table. An LSI always shares
   * the table's partition key and declares a single sort key. Changing this
   * property replaces the table.
   */
  localSecondaryIndexes?: LocalSecondaryIndexProps[];
  /**
   * Global secondary indexes. GSIs support multi-attribute keys: up to four
   * partition attributes (hashed together as the composite partition key)
   * and up to four sort attributes (sorted and queried left-to-right).
   * Attribute order is significant — reordering defines a different index
   * and replaces the table. Every key attribute must appear in `attributes`.
   */
  globalSecondaryIndexes?: GlobalSecondaryIndexProps[];
  billingMode?: DynamoDB.BillingMode;
  deletionProtectionEnabled?: boolean;
  onDemandThroughput?: DynamoDB.OnDemandThroughput;
  /**
   * Enables point-in-time recovery (continuous backups) and optionally sets
   * the recovery window via `recoveryPeriod` (a `Duration.Input`, rounded to
   * whole days on the wire).
   */
  pointInTimeRecoverySpecification?: PointInTimeRecoverySpecification;
  provisionedThroughput?: DynamoDB.ProvisionedThroughput;
  sseSpecification?: DynamoDB.SSESpecification;
  tags?: Record<string, string>;
  timeToLiveSpecification?: DynamoDB.TimeToLiveSpecification;
  warmThroughput?: DynamoDB.WarmThroughput;
  tableClass?: DynamoDB.TableClass;
  /**
   * Resource-based IAM policy document (JSON string) attached to the table.
   * Grants cross-account or scoped-principal access to the table and its
   * indexes. Removing the property deletes the policy.
   */
  resourcePolicy?: string;
  /**
   * Streams change data capture records to the given Kinesis Data Stream.
   * Changing the stream disables the old destination before enabling the
   * new one; removing the property disables streaming.
   */
  kinesisStreamingDestination?: KinesisStreamingDestination;
  /**
   * Enables CloudWatch Contributor Insights (table-level rule) for the
   * table, surfacing the most-accessed and most-throttled keys.
   * @default false
   */
  contributorInsightsEnabled?: boolean;
};

export type TableBinding = {
  streamSpecification?: DynamoDB.StreamSpecification;
};

export interface Table extends Resource<
  "AWS.DynamoDB.Table",
  TableProps,
  {
    /** The unique ID AWS assigns to the table. */
    tableId: string;
    /** The physical name of the table. */
    tableName: TableName;
    /** The ARN of the table. */
    tableArn: TableArn;
    /** The AWS region the table lives in. */
    region: RegionID;
    /** The partition (hash) key attribute name. */
    partitionKey: string;
    /** The sort (range) key attribute name, if defined. */
    sortKey: string | undefined;
    /** ARN of the most recent DynamoDB stream (when streams are enabled). */
    latestStreamArn: string | undefined;
    /** The current stream configuration (when streams are enabled). */
    streamSpecification: DynamoDB.StreamSpecification | undefined;
    /** Descriptions of the table's local secondary indexes. */
    localSecondaryIndexes: DynamoDB.LocalSecondaryIndexDescription[] | undefined;
    /** Descriptions of the table's global secondary indexes. */
    globalSecondaryIndexes: DynamoDB.GlobalSecondaryIndexDescription[] | undefined;
    /** The point-in-time recovery status of the table. */
    pointInTimeRecoveryDescription: DynamoDB.PointInTimeRecoveryDescription | undefined;
    /** The tags attached to the table. */
    tags: Record<string, string> | undefined;
    /**
     * Billing mode, as observed on the table. Lets `alchemy drift` detect
     * out-of-band changes.
     */
    billingMode?: DynamoDB.BillingMode;
    /**
     * Table-level provisioned capacity (PROVISIONED tables only), as
     * observed. Lets `alchemy drift` detect out-of-band changes.
     */
    provisionedThroughput?: {
      ReadCapacityUnits?: number;
      WriteCapacityUnits?: number;
    };
    /**
     * Table-level on-demand maximums, observed when `onDemandThroughput` is
     * set. Lets `alchemy drift` detect out-of-band changes.
     */
    onDemandThroughput?: DynamoDB.OnDemandThroughput;
    /**
     * Whether deletion protection is enabled, as observed. Lets
     * `alchemy drift` detect out-of-band changes.
     */
    deletionProtectionEnabled?: boolean;
    /**
     * KMS server-side encryption, as observed (`undefined` when the table
     * uses the default AWS owned key). Lets `alchemy drift` detect
     * out-of-band changes.
     */
    sseDescription?: {
      sseType?: string;
      kmsMasterKeyArn?: string;
    };
    /**
     * Table class, as observed. Lets `alchemy drift` detect out-of-band
     * changes.
     */
    tableClass?: DynamoDB.TableClass;
    /**
     * Time-to-live attribute when TTL is enabled, as observed. Lets
     * `alchemy drift` detect out-of-band changes.
     */
    timeToLiveAttributeName?: string;
    /**
     * Resource-based policy document attached to the table (canonical JSON),
     * as observed. Lets `alchemy drift` detect out-of-band changes.
     */
    resourcePolicy?: string;
    /**
     * Active Kinesis streaming destinations, as observed. Lets
     * `alchemy drift` detect out-of-band changes.
     */
    kinesisStreamingDestinations?: {
      streamArn: string;
      approximateCreationDateTimePrecision: string;
    }[];
    /**
     * Whether Contributor Insights is enabled, as observed. Lets
     * `alchemy drift` detect out-of-band changes.
     */
    contributorInsightsEnabled?: boolean;
  },
  TableBinding,
  Providers
> {}

/**
 * An Amazon DynamoDB table with optional indexes, PITR, TTL, and stream-aware
 * binding support.
 *
 * `Table` owns the lifecycle of the physical table while the binding contract
 * allows runtime-specific integrations such as Lambda table event sources to
 * request stream configuration without forcing a circular input prop.
 * ### Creating Tables
 * **Example:** Basic Table
 * ```typescript
 * import * as DynamoDB from "@alchemy.run/aws/DynamoDB";
 *
 * const table = yield* DynamoDB.Table("UsersTable", {
 *   partitionKey: "pk",
 *   attributes: {
 *     pk: "S",
 *   },
 * });
 * ```
 *
 * **Example:** Table with Sort Key and TTL
 * ```typescript
 * const table = yield* DynamoDB.Table("SessionsTable", {
 *   partitionKey: "userId",
 *   sortKey: "sessionId",
 *   attributes: {
 *     userId: "S",
 *     sessionId: "S",
 *     expiresAt: "N",
 *   },
 *   timeToLiveSpecification: {
 *     Enabled: true,
 *     AttributeName: "expiresAt",
 *   },
 * });
 * ```
 *
 * **Example:** Table with Global Secondary Index
 * ```typescript
 * const table = yield* DynamoDB.Table("OrdersTable", {
 *   partitionKey: "pk",
 *   sortKey: "sk",
 *   attributes: {
 *     pk: "S",
 *     sk: "S",
 *     gsi1pk: "S",
 *     gsi1sk: "S",
 *   },
 *   globalSecondaryIndexes: [{
 *     indexName: "GSI1",
 *     partitionKey: "gsi1pk",
 *     sortKey: "gsi1sk",
 *     projection: { ProjectionType: "ALL" },
 *   }],
 * });
 * ```
 *
 * **Example:** Multi-Attribute GSI Keys
 * GSI partition and sort keys may be composed of up to four attributes each,
 * indexing natural domain attributes directly instead of synthetic
 * concatenated keys. Partition attributes are hashed together (queries must
 * specify all of them with equality); sort attributes are queried
 * left-to-right in declaration order.
 * ```typescript
 * const matches = yield* DynamoDB.Table("TournamentMatches", {
 *   partitionKey: "matchId",
 *   attributes: {
 *     matchId: "S",
 *     tournamentId: "S",
 *     region: "S",
 *     round: "S",
 *   },
 *   globalSecondaryIndexes: [{
 *     indexName: "TournamentRegionIndex",
 *     partitionKey: ["tournamentId", "region"],
 *     sortKey: ["round", "matchId"],
 *     projection: { ProjectionType: "ALL" },
 *   }],
 * });
 *
 * // init
 * const query = yield* AWS.DynamoDB.Query(matches);
 *
 * // runtime: query with every partition attribute, then narrow the sort
 * // attributes left-to-right
 * const response = yield* query({
 *   IndexName: "TournamentRegionIndex",
 *   KeyConditionExpression:
 *     "tournamentId = :t AND #r = :r AND round = :round",
 *   ExpressionAttributeNames: { "#r": "region" },
 *   ExpressionAttributeValues: {
 *     ":t": { S: "WINTER2024" },
 *     ":r": { S: "NA-EAST" },
 *     ":round": { S: "SEMIFINALS" },
 *   },
 * });
 * ```
 *
 * ### 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* AWS.DynamoDB.GetItem(table);
 * const putItem = yield* AWS.DynamoDB.PutItem(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);
 *   }),
 * };
 * ```
 *
 * **Example:** Read and write items from a Cloudflare Worker
 *
 * The `*Http` layers also run on a Cloudflare Worker. Alchemy creates an
 * IAM user, access key, and least-privilege role for the Worker, binds the
 * key onto it, and signs each request with the assumed role in the table's
 * region. The Stack needs both provider sets:
 * `Layer.mergeAll(Cloudflare.providers(), AWS.providers())`.
 * ```typescript
 * export default class Api extends Cloudflare.Worker<Api>()(
 *   "Api",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const table = yield* AWS.DynamoDB.Table("Links", {
 *       partitionKey: "id",
 *       attributes: { id: "S" },
 *     });
 *     const getItem = yield* AWS.DynamoDB.GetItem(table);
 *     const putItem = yield* AWS.DynamoDB.PutItem(table);
 *     return {
 *       fetch: Effect.gen(function* () {
 *         yield* putItem({ Item: { id: { S: "a" }, url: { S: "https://alchemy.run" } } });
 *         const { Item } = yield* getItem({ Key: { id: { S: "a" } } });
 *         return yield* HttpServerResponse.json(Item);
 *       }).pipe(Effect.orDie),
 *     };
 *   }).pipe(
 *     Effect.provide(
 *       Layer.mergeAll(AWS.DynamoDB.GetItemHttp, AWS.DynamoDB.PutItemHttp),
 *     ),
 *   ),
 * ) {}
 * ```
 *
 * ### Table Features
 * **Example:** Resource Policy
 * ```typescript
 * const table = yield* DynamoDB.Table("SharedTable", {
 *   partitionKey: "pk",
 *   attributes: { pk: "S" },
 *   resourcePolicy: JSON.stringify({
 *     Version: "2012-10-17",
 *     Statement: [{
 *       Effect: "Allow",
 *       Principal: { AWS: "arn:aws:iam::111122223333:root" },
 *       Action: ["dynamodb:GetItem", "dynamodb:Query"],
 *       Resource: "*",
 *     }],
 *   }),
 * });
 * ```
 *
 * **Example:** Kinesis Streaming Destination
 * ```typescript
 * import * as Kinesis from "@alchemy.run/aws/Kinesis";
 *
 * const stream = yield* Kinesis.Stream("CdcStream", {});
 * const table = yield* DynamoDB.Table("CdcTable", {
 *   partitionKey: "pk",
 *   attributes: { pk: "S" },
 *   kinesisStreamingDestination: {
 *     streamArn: stream.streamArn,
 *     approximateCreationDateTimePrecision: "MICROSECOND",
 *   },
 * });
 * ```
 *
 * **Example:** Contributor Insights
 * ```typescript
 * const table = yield* DynamoDB.Table("HotKeyTable", {
 *   partitionKey: "pk",
 *   attributes: { pk: "S" },
 *   contributorInsightsEnabled: true,
 * });
 * ```
 *
 * ### 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.consumeTableChanges(
 *   table,
 *   { streamViewType: "NEW_AND_OLD_IMAGES" },
 *   Effect.fn(function* (event) {
 *     for (const record of event.Records) {
 *       yield* Effect.log(`${record.eventName}: ${JSON.stringify(record.dynamodb)}`);
 *     }
 *   }),
 * );
 * ```
 *
 * @resource
 */
export const Table = Resource<Table>("AWS.DynamoDB.Table");

export const TableProvider = () =>
  Provider.effect(
    Table,
    Effect.gen(function* () {
      const createTableName = (id: string, props: Input.ResolveProps<TableProps>) =>
        Effect.gen(function* () {
          return (
            props.tableName ??
            (yield* createPhysicalName({
              id,
              // see: https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TableDescription.html#DDB-Type-TableDescription-TableName
              maxLength: 255,
            }))
          );
        });

      const toKeySchema = (props: Input.ResolveProps<TableProps>) => [
        {
          AttributeName: props.partitionKey,
          KeyType: "HASH" as const,
        },
        ...(props.sortKey
          ? [
              {
                AttributeName: props.sortKey,
                KeyType: "RANGE" as const,
              },
            ]
          : []),
      ];

      const toKeyAttributeNames = (key: IndexKey | undefined) =>
        key === undefined ? [] : typeof key === "string" ? [key] : key;

      // AWS's wire format flattens an index key into one ordered KeySchema
      // list and validates that all HASH elements precede all RANGE
      // elements; deriving the list from the two typed segments makes the
      // invalid orderings unrepresentable in props.
      const toIndexKeySchema = (
        partitionKey: IndexKey,
        sortKey: IndexKey | undefined,
      ): DynamoDB.KeySchemaElement[] => [
        ...toKeyAttributeNames(partitionKey).map((name) => ({
          AttributeName: name,
          KeyType: "HASH" as const,
        })),
        ...toKeyAttributeNames(sortKey).map((name) => ({
          AttributeName: name,
          KeyType: "RANGE" as const,
        })),
      ];

      // Pre-typed-props state may persist index props in the legacy wire
      // shape ({ IndexName, KeySchema, ... }). Tolerate it when converting
      // `olds` so upgrading alchemy never plans a spurious table
      // replacement over a shape-only difference.
      const isLegacyWireIndex = (index: unknown): index is DynamoDB.GlobalSecondaryIndex =>
        typeof index === "object" && index !== null && "KeySchema" in index;

      const toWireGlobalSecondaryIndex = (
        index: GlobalSecondaryIndexProps,
      ): DynamoDB.GlobalSecondaryIndex =>
        isLegacyWireIndex(index)
          ? index
          : {
              IndexName: index.indexName,
              KeySchema: toIndexKeySchema(index.partitionKey, index.sortKey),
              Projection: index.projection,
              ProvisionedThroughput: index.provisionedThroughput,
              OnDemandThroughput: index.onDemandThroughput,
              WarmThroughput: index.warmThroughput,
            };

      const toWireLocalSecondaryIndex = (
        tablePartitionKey: string,
        index: LocalSecondaryIndexProps,
      ): DynamoDB.LocalSecondaryIndex =>
        isLegacyWireIndex(index)
          ? index
          : {
              IndexName: index.indexName,
              KeySchema: toIndexKeySchema(tablePartitionKey, index.sortKey),
              Projection: index.projection,
            };

      const toWireGlobalSecondaryIndexes = (
        indexes: readonly GlobalSecondaryIndexProps[] | undefined,
      ) =>
        indexes === undefined || indexes.length === 0
          ? undefined
          : indexes.map(toWireGlobalSecondaryIndex);

      const toWireLocalSecondaryIndexes = (
        tablePartitionKey: string,
        indexes: readonly LocalSecondaryIndexProps[] | undefined,
      ) =>
        indexes === undefined || indexes.length === 0
          ? undefined
          : indexes.map((index) => toWireLocalSecondaryIndex(tablePartitionKey, index));

      const toAttributeDefinitions = (attrs: Record<string, ScalarAttributeType>) =>
        Object.entries(attrs)
          .map(([name, type]) => ({
            AttributeName: name,
            AttributeType: type,
          }))
          .sort((a, b) => a.AttributeName.localeCompare(b.AttributeName));

      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, tags?: Record<string, string>) {
        return {
          ...(yield* createInternalTags(id)),
          ...tags,
        };
      });

      const normalizeStreamSpecification = (
        streamSpecification: DynamoDB.StreamSpecification | undefined,
      ) =>
        streamSpecification?.StreamEnabled === true
          ? ({
              StreamEnabled: true,
              StreamViewType: streamSpecification.StreamViewType,
            } satisfies DynamoDB.StreamSpecification)
          : undefined;

      const resolveStreamSpecification = (
        bindings: ReadonlyArray<TableBinding | { data?: TableBinding }>,
      ) =>
        Effect.gen(function* () {
          const requested = bindings
            .flatMap((binding) =>
              (binding as { data?: TableBinding }).data?.streamSpecification?.StreamEnabled === true
                ? [
                    normalizeStreamSpecification(
                      (binding as { data?: TableBinding }).data?.streamSpecification,
                    ),
                  ]
                : (binding as TableBinding).streamSpecification?.StreamEnabled === true
                  ? [normalizeStreamSpecification((binding as TableBinding).streamSpecification)]
                  : [],
            )
            .filter((spec) => spec !== undefined);

          if (requested.length === 0) {
            return undefined;
          }

          const [first, ...rest] = requested;
          if (!first?.StreamViewType) {
            return yield* new MissingStreamViewType();
          }

          for (const spec of rest) {
            if (spec.StreamViewType !== first.StreamViewType) {
              return yield* new ConflictingStreamViewTypes({
                requested: requested.map((item) => item.StreamViewType),
              });
            }
          }

          return first;
        });

      const isRetryableControlPlaneError = (error: { _tag?: string }) =>
        error._tag === "InternalServerError" ||
        error._tag === "LimitExceededException" ||
        error._tag === "ResourceInUseException" ||
        error._tag === "ResourceNotFoundException" ||
        // Throttling: DynamoDB's control-plane API limits are low and the
        // blanket SDK retry (10 attempts) is easily exhausted when the whole
        // suite hammers create/update/describe concurrently. Give it the
        // provider's much larger budget too.
        error._tag === "ThrottlingException" ||
        error._tag === "ProvisionedThroughputExceededException" ||
        error._tag === "RequestLimitExceeded";

      const waitForControlPlaneConvergence = Schedule.max([
        Schedule.fixed("1 second"),
        Schedule.recurs(120),
      ]);

      const waitForTableActivationConvergence = Schedule.max([
        Schedule.fixed("10 seconds"),
        Schedule.recurs(180),
      ]);

      const waitForGlobalSecondaryIndexesConvergence = Schedule.max([
        Schedule.fixed("10 seconds"),
        Schedule.recurs(180),
      ]);

      const waitForDeletionConvergence = Schedule.max([
        Schedule.fixed("1 second"),
        Schedule.recurs(90),
      ]);

      const formatPollingElapsed = (elapsedSeconds: number) => `${elapsedSeconds}s elapsed`;

      const formatGlobalSecondaryIndexStatuses = (
        indexes: readonly DynamoDB.GlobalSecondaryIndexDescription[] | undefined,
      ) =>
        JSON.stringify(
          (indexes ?? []).map((index) => ({
            name: index.IndexName,
            status: index.IndexStatus,
            backfilling: index.Backfilling,
          })),
        );

      const updateTimeToLive = (
        tableName: string,
        timeToLiveSpecification: TimeToLiveSpecification,
      ) =>
        dynamodb
          .updateTimeToLive({
            TableName: tableName,
            TimeToLiveSpecification: timeToLiveSpecification!,
          })
          .pipe(
            Effect.retry({
              while: isRetryableControlPlaneError,
              schedule: Schedule.max([Schedule.exponential(100), Schedule.recurs(30)]),
            }),
          );

      const updateContinuousBackups = (
        tableName: string,
        pointInTimeRecoverySpecification: DynamoDB.PointInTimeRecoverySpecification,
      ) =>
        dynamodb
          .updateContinuousBackups({
            TableName: tableName,
            PointInTimeRecoverySpecification: pointInTimeRecoverySpecification,
          })
          .pipe(
            Effect.retry({
              while: (e) =>
                e._tag === "ContinuousBackupsUnavailableException" ||
                isRetryableControlPlaneError(e),
              schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(30)]),
            }),
          );

      // Resource policies are compared as canonicalized JSON so formatting
      // differences between what the user wrote and what AWS stores don't
      // cause phantom putResourcePolicy calls on every reconcile.
      const canonicalPolicyDocument = (policy: string | undefined) => {
        if (policy === undefined) return undefined;
        try {
          return JSON.stringify(JSON.parse(policy));
        } catch {
          return policy;
        }
      };

      const readTableResourcePolicy = (tableArn: string) =>
        dynamodb.getResourcePolicy({ ResourceArn: tableArn }).pipe(
          Effect.map((response) => response.Policy),
          Effect.catchTag("PolicyNotFoundException", () => Effect.undefined),
          Effect.retry({
            while: isRetryableControlPlaneError,
            schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
          }),
        );

      const putTableResourcePolicy = (tableArn: string, policy: string) =>
        dynamodb.putResourcePolicy({ ResourceArn: tableArn, Policy: policy }).pipe(
          Effect.retry({
            while: isRetryableControlPlaneError,
            schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
          }),
        );

      const deleteTableResourcePolicy = (tableArn: string) =>
        dynamodb.deleteResourcePolicy({ ResourceArn: tableArn }).pipe(
          Effect.catchTag("PolicyNotFoundException", () => Effect.void),
          Effect.retry({
            while: isRetryableControlPlaneError,
            schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
          }),
        );

      const isKinesisDestinationTransitioning = (
        destination: DynamoDB.KinesisDataStreamDestination,
      ) =>
        destination.DestinationStatus === "ENABLING" ||
        destination.DestinationStatus === "DISABLING" ||
        destination.DestinationStatus === "UPDATING";

      // Kinesis streaming destinations transition ENABLING→ACTIVE and
      // DISABLING→DISABLED within seconds, but a precision change
      // (UPDATING→ACTIVE) takes multiple minutes; poll bounded to 8 minutes.
      const waitForKinesisDestinationsConvergence = Schedule.max([
        Schedule.fixed("5 seconds"),
        Schedule.recurs(96),
      ]);

      const waitForKinesisDestinationsSettled = (
        session: {
          note: (message: string) => Effect.Effect<void, never, never>;
        },
        tableName: string,
      ) => {
        let elapsedSeconds = 0;
        return Effect.gen(function* () {
          const response = yield* dynamodb.describeKinesisStreamingDestination({
            TableName: tableName,
          });
          const destinations = response.KinesisDataStreamDestinations ?? [];
          if (destinations.some(isKinesisDestinationTransitioning)) {
            return yield* new KinesisDestinationNotSettled();
          }
          return destinations;
        }).pipe(
          Effect.retry({
            while: (error) =>
              error._tag === "KinesisDestinationNotSettled" || isRetryableControlPlaneError(error),
            schedule: waitForKinesisDestinationsConvergence.pipe(
              Schedule.tap(({ attempt }) => {
                elapsedSeconds = (attempt + 1) * 5;
                return session.note(
                  `DynamoDB Table provider: waiting for Kinesis streaming destinations on ${tableName} to settle (${formatPollingElapsed(elapsedSeconds)})`,
                );
              }),
            ),
          }),
        );
      };

      const disableKinesisDestination = (tableName: string, streamArn: string) =>
        dynamodb
          .disableKinesisStreamingDestination({
            TableName: tableName,
            StreamArn: streamArn,
          })
          .pipe(
            Effect.retry({
              while: isRetryableControlPlaneError,
              schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
            }),
          );

      const enableKinesisDestination = (
        tableName: string,
        destination: KinesisStreamingDestination,
      ) =>
        dynamodb
          .enableKinesisStreamingDestination({
            TableName: tableName,
            StreamArn: destination.streamArn,
            EnableKinesisStreamingConfiguration:
              destination.approximateCreationDateTimePrecision !== undefined
                ? {
                    ApproximateCreationDateTimePrecision:
                      destination.approximateCreationDateTimePrecision,
                  }
                : undefined,
          })
          .pipe(
            Effect.retry({
              while: isRetryableControlPlaneError,
              schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
            }),
          );

      const updateKinesisDestinationPrecision = (
        tableName: string,
        destination: KinesisStreamingDestination,
      ) =>
        dynamodb
          .updateKinesisStreamingDestination({
            TableName: tableName,
            StreamArn: destination.streamArn,
            UpdateKinesisStreamingConfiguration: {
              ApproximateCreationDateTimePrecision:
                destination.approximateCreationDateTimePrecision,
            },
          })
          .pipe(
            Effect.retry({
              while: isRetryableControlPlaneError,
              schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
            }),
          );

      // Contributor Insights transitions ENABLING→ENABLED / DISABLING→DISABLED
      // within seconds, but UpdateContributorInsights rejects a DISABLE while
      // the status is still ENABLING — wait for a settled status before
      // diffing observed against desired.
      const waitForContributorInsightsSettled = (
        session: {
          note: (message: string) => Effect.Effect<void, never, never>;
        },
        tableName: string,
      ) =>
        Effect.gen(function* () {
          const response = yield* dynamodb.describeContributorInsights({
            TableName: tableName,
          });
          const status = response.ContributorInsightsStatus ?? "DISABLED";
          if (status === "ENABLING" || status === "DISABLING") {
            return yield* new ContributorInsightsNotSettled();
          }
          return status;
        }).pipe(
          Effect.retry({
            while: (error) =>
              error._tag === "ContributorInsightsNotSettled" || isRetryableControlPlaneError(error),
            schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(45)]).pipe(
              Schedule.tap(({ attempt }) =>
                session.note(
                  `DynamoDB Table provider: waiting for Contributor Insights on ${tableName} to settle (${formatPollingElapsed((attempt + 1) * 2)})`,
                ),
              ),
            ),
          }),
        );

      // Enabling Contributor Insights makes DynamoDB create CloudWatch rules
      // named `DynamoDBContributorInsights-{PKC|PKT}-<tableName>-<timestamp>`
      // in the customer's account. Those rules can ONLY be removed by
      // DynamoDB's own asynchronous cleanup, which runs when an
      // UpdateContributorInsights DISABLE completes — CloudWatch's
      // DeleteInsightRules/PutInsightRule reject them with AccessDenied even
      // for account admins, and deleting the table aborts the cleanup and
      // strands the rules forever (recoverable only via AWS support). The
      // delete lifecycle therefore observes the rules and holds off
      // deleteTable until DynamoDB's cleanup has actually removed them.
      const listContributorInsightsRules = (tableName: string) =>
        cloudwatch.describeInsightRules.pages({}).pipe(
          Stream.runFold(
            () => [] as string[],
            (acc, page) => [
              ...acc,
              ...(page.InsightRules ?? [])
                .map((rule) => rule.Name)
                .filter(
                  (name): name is string =>
                    name !== undefined &&
                    name.startsWith("DynamoDBContributorInsights-") &&
                    name.includes(`-${tableName}-`),
                ),
            ],
          ),
        );

      const waitForContributorInsightsRulesDeleted = (
        session: {
          note: (message: string) => Effect.Effect<void, never, never>;
        },
        tableName: string,
      ) =>
        Effect.gen(function* () {
          const remaining = yield* listContributorInsightsRules(tableName);
          if (remaining.length > 0) {
            return yield* new ContributorInsightsNotSettled();
          }
        }).pipe(
          Effect.retry({
            while: (error) =>
              error._tag === "ContributorInsightsNotSettled" || isRetryableControlPlaneError(error),
            schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(20)]).pipe(
              Schedule.tap(({ attempt }) =>
                session.note(
                  `DynamoDB Table provider: waiting for Contributor Insights rules of ${tableName} to be cleaned up (${formatPollingElapsed((attempt + 1) * 2)})`,
                ),
              ),
            ),
          }),
          // Rules from a PREVIOUS enable session whose cleanup was already
          // aborted (e.g. by an out-of-band table deletion) can never be
          // removed by anyone but AWS support — don't wedge the delete on
          // them; surface a note and move on.
          Effect.catchTag("ContributorInsightsNotSettled", () =>
            session.note(
              `DynamoDB Table provider: Contributor Insights rules for ${tableName} were not cleaned up by DynamoDB; they may be stranded from an earlier enable session (deletable only via AWS support)`,
            ),
          ),
        );

      const updateTableContributorInsights = (tableName: string, enabled: boolean) =>
        dynamodb
          .updateContributorInsights({
            TableName: tableName,
            ContributorInsightsAction: enabled ? "ENABLE" : "DISABLE",
          })
          .pipe(
            Effect.retry({
              while: isRetryableControlPlaneError,
              schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
            }),
          );

      const waitForTableActive = (
        session: {
          note: (message: string) => Effect.Effect<void, never, never>;
        },
        tableName: string,
      ) => {
        let elapsedSeconds = 0;
        let progressMessage = `DynamoDB Table provider: waiting for table ${tableName} to become ACTIVE`;

        return Effect.gen(function* () {
          const response = yield* dynamodb.describeTable({
            TableName: tableName,
          });
          if (response.Table?.TableStatus !== "ACTIVE") {
            progressMessage = `DynamoDB Table provider: table ${tableName} not active yet (status=${response.Table?.TableStatus ?? "undefined"} gsiStatuses=${formatGlobalSecondaryIndexStatuses(response.Table?.GlobalSecondaryIndexes)})`;
            return yield* new TableNotActive();
          }
          yield* session.note(
            `DynamoDB Table provider: table ${tableName} is ACTIVE (${formatPollingElapsed(elapsedSeconds)})`,
          );
          return response.Table;
        }).pipe(
          Effect.retry({
            while: (error) =>
              error._tag === "TableNotActive" || isRetryableControlPlaneError(error),
            schedule: waitForTableActivationConvergence.pipe(
              Schedule.tap(({ attempt }) => {
                elapsedSeconds = attempt * 10;
                return session.note(`${progressMessage} (${formatPollingElapsed(elapsedSeconds)})`);
              }),
            ),
          }),
        );
      };

      const waitForGlobalSecondaryIndexesStable = (
        session: {
          note: (message: string) => Effect.Effect<void, never, never>;
        },
        tableName: string,
        expectedIndexNames: readonly string[],
      ) => {
        let elapsedSeconds = 0;
        let progressMessage = `DynamoDB Table provider: waiting for GSIs on ${tableName} to stabilize`;

        return Effect.gen(function* () {
          const response = yield* dynamodb.describeTable({
            TableName: tableName,
          });
          const table = response.Table;
          const actualIndexNames = [...(table?.GlobalSecondaryIndexes ?? [])]
            .map((index) => index.IndexName!)
            .sort();
          const expected = [...expectedIndexNames].sort();
          const allActive = (table?.GlobalSecondaryIndexes ?? []).every(
            (index) => index.IndexStatus === "ACTIVE",
          );

          if (JSON.stringify(actualIndexNames) !== JSON.stringify(expected) || !allActive) {
            progressMessage = `DynamoDB Table provider: GSIs for ${tableName} not stable yet (expected=${JSON.stringify(expected)} actual=${JSON.stringify(actualIndexNames)} statuses=${JSON.stringify((table?.GlobalSecondaryIndexes ?? []).map((index) => ({ name: index.IndexName, status: index.IndexStatus })))} tableStatus=${table?.TableStatus ?? "undefined"})`;
            return yield* new TableIndexesNotStable();
          }

          yield* session.note(
            `DynamoDB Table provider: GSIs for ${tableName} stabilized (${JSON.stringify(actualIndexNames)}) (${formatPollingElapsed(elapsedSeconds)})`,
          );
          return table;
        }).pipe(
          Effect.retry({
            while: (error) =>
              error._tag === "TableIndexesNotStable" || isRetryableControlPlaneError(error),
            schedule: waitForGlobalSecondaryIndexesConvergence.pipe(
              Schedule.tap(({ attempt }) => {
                elapsedSeconds = attempt * 10;
                return session.note(`${progressMessage} (${formatPollingElapsed(elapsedSeconds)})`);
              }),
            ),
          }),
        );
      };

      const waitForTableDeleted = (
        session: {
          note: (message: string) => Effect.Effect<void, never, never>;
        },
        tableName: string,
      ) => {
        let elapsedSeconds = 0;
        let progressMessage = `DynamoDB Table provider: waiting for deletion of ${tableName}`;

        return Effect.gen(function* () {
          const response = yield* dynamodb.describeTable({
            TableName: tableName,
          });
          progressMessage = `DynamoDB Table provider: table ${tableName} still deleting (status=${response.Table?.TableStatus ?? "undefined"})`;
          return yield* new TableStillDeleting();
        }).pipe(
          Effect.catchTag("ResourceNotFoundException", () =>
            session.note(
              `DynamoDB Table provider: table ${tableName} deletion confirmed (${formatPollingElapsed(elapsedSeconds)})`,
            ),
          ),
          Effect.retry({
            while: (error) =>
              error._tag === "TableStillDeleting" || isRetryableControlPlaneError(error),
            schedule: waitForDeletionConvergence.pipe(
              Schedule.tap(({ attempt }) => {
                elapsedSeconds = attempt;
                return session.note(`${progressMessage} (${formatPollingElapsed(elapsedSeconds)})`);
              }),
            ),
          }),
        );
      };

      const deleteGlobalSecondaryIndexes = (
        session: {
          note: (message: string) => Effect.Effect<void, never, never>;
        },
        tableName: string,
      ) =>
        Effect.gen(function* () {
          const response = yield* dynamodb
            .describeTable({
              TableName: tableName,
            })
            .pipe(
              Effect.retry({
                while: isRetryableControlPlaneError,
                schedule: waitForControlPlaneConvergence,
              }),
              Effect.catchTag("ResourceNotFoundException", () =>
                Effect.succeed({ Table: undefined }),
              ),
            );

          const indexNames = [...(response.Table?.GlobalSecondaryIndexes ?? [])]
            .map((index) => index.IndexName!)
            .sort();

          if (indexNames.length === 0) {
            yield* session.note(
              `DynamoDB Table provider: no GSIs remain on ${tableName}; retrying table deletion`,
            );
            return;
          }

          yield* session.note(
            `DynamoDB Table provider: deleting GSIs before deleting table ${tableName} (${indexNames.join(", ")})`,
          );

          yield* waitForGlobalSecondaryIndexesStable(session, tableName, indexNames);

          const remainingIndexNames = [...indexNames];
          for (const indexName of indexNames) {
            let elapsedSeconds = 0;
            let progressMessage = `DynamoDB Table provider: waiting to delete GSI ${indexName} from ${tableName}`;

            yield* session.note(
              `DynamoDB Table provider: deleting GSI ${indexName} from ${tableName}`,
            );

            yield* dynamodb
              .updateTable({
                TableName: tableName,
                GlobalSecondaryIndexUpdates: [
                  {
                    Delete: {
                      IndexName: indexName,
                    },
                  },
                ],
              })
              .pipe(
                Effect.timeout(1000),
                Effect.tap(() =>
                  session.note(
                    `DynamoDB Table provider: delete accepted for GSI ${indexName} on ${tableName} (${formatPollingElapsed(elapsedSeconds)})`,
                  ),
                ),
                Effect.retry({
                  while: (error) => {
                    if (error._tag === "ResourceInUseException") {
                      progressMessage = `DynamoDB Table provider: delete for GSI ${indexName} on ${tableName} is blocked while the table or indexes are still transitioning`;
                      return true;
                    }
                    if (error._tag === "TimeoutError") {
                      progressMessage = `DynamoDB Table provider: delete for GSI ${indexName} on ${tableName} timed out`;
                      return true;
                    }
                    if (
                      error._tag === "InternalServerError" ||
                      error._tag === "LimitExceededException"
                    ) {
                      progressMessage = `DynamoDB Table provider: delete for GSI ${indexName} on ${tableName} hit ${error._tag}`;
                      return true;
                    }
                    return false;
                  },
                  schedule: waitForGlobalSecondaryIndexesConvergence.pipe(
                    Schedule.tap(({ attempt }) => {
                      elapsedSeconds = attempt * 10;
                      return session.note(
                        `${progressMessage} (${formatPollingElapsed(elapsedSeconds)})`,
                      );
                    }),
                  ),
                }),
              );

            remainingIndexNames.splice(remainingIndexNames.indexOf(indexName), 1);

            yield* waitForGlobalSecondaryIndexesStable(session, tableName, remainingIndexNames);
          }
        });

      // 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" ||
        // See `isRetryableControlPlaneError`: read-path describes throttle too
        // under full-suite concurrency, so ride them out generously.
        error._tag === "ThrottlingException" ||
        error._tag === "ProvisionedThroughputExceededException" ||
        error._tag === "RequestLimitExceeded";

      const readTableState = (tableName: string) =>
        Effect.gen(function* () {
          const response = yield* dynamodb
            .describeTable({
              TableName: tableName,
            })
            .pipe(
              Effect.retry({
                while: isRetryableReadError,
                schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(30)]),
              }),
            );
          const table = response.Table;
          if (!table?.TableArn) {
            return yield* new TableUnexpectedResponse({ message: `Table ${tableName} not found` });
          }

          const [tagsResult, continuousBackupsResult, ttlResult] = yield* Effect.all([
            dynamodb
              .listTagsOfResource({
                ResourceArn: table.TableArn,
              })
              .pipe(
                Effect.retry({
                  while: isRetryableReadError,
                  schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(30)]),
                }),
              ),
            dynamodb
              .describeContinuousBackups({
                TableName: tableName,
              })
              .pipe(
                Effect.retry({
                  while: (e) => e._tag === "InternalServerError",
                  schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(30)]),
                }),
                Effect.catchTag("TableNotFoundException", () =>
                  Effect.succeed({ ContinuousBackupsDescription: undefined }),
                ),
              ),
            dynamodb
              .describeTimeToLive({
                TableName: tableName,
              })
              .pipe(
                Effect.retry({
                  while: isRetryableReadError,
                  schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(30)]),
                }),
                Effect.catchTag("ResourceNotFoundException", () =>
                  Effect.succeed({ TimeToLiveDescription: undefined }),
                ),
              ),
          ]);

          return {
            table,
            tags: Object.fromEntries(
              (tagsResult.Tags ?? []).map((tag) => [tag.Key!, tag.Value!]),
            ) as Record<string, string>,
            pointInTimeRecoveryDescription:
              continuousBackupsResult.ContinuousBackupsDescription?.PointInTimeRecoveryDescription,
            timeToLiveDescription: ttlResult.TimeToLiveDescription,
          };
        }).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));

      const toAttrs = (state: {
        table: DynamoDB.TableDescription;
        tags: Record<string, string>;
        pointInTimeRecoveryDescription: DynamoDB.PointInTimeRecoveryDescription | undefined;
      }) => ({
        tableId: state.table.TableId!,
        tableName: state.table.TableName!,
        tableArn: state.table.TableArn! as TableArn,
        region: state.table.TableArn!.split(":")[3] as RegionID,
        partitionKey:
          state.table.KeySchema?.find((key) => key.KeyType === "HASH")?.AttributeName ?? "",
        sortKey: state.table.KeySchema?.find((key) => key.KeyType === "RANGE")?.AttributeName,
        latestStreamArn: state.table.LatestStreamArn,
        streamSpecification: state.table.StreamSpecification,
        // Index descriptions carry item counts, sizes and status that change
        // on their own; keep only the configuration so drift stays quiet.
        localSecondaryIndexes: state.table.LocalSecondaryIndexes?.map((index) => ({
          IndexName: index.IndexName,
          IndexArn: index.IndexArn,
          KeySchema: index.KeySchema,
          Projection: index.Projection,
        })),
        globalSecondaryIndexes: state.table.GlobalSecondaryIndexes?.map((index) => ({
          IndexName: index.IndexName,
          IndexArn: index.IndexArn,
          KeySchema: index.KeySchema,
          Projection: index.Projection,
          ProvisionedThroughput: normalizeProvisioned(index.ProvisionedThroughput),
          OnDemandThroughput: normalizeOnDemand(index.OnDemandThroughput),
        })),
        // The restorable window moves every second; only the setting is state.
        pointInTimeRecoveryDescription: state.pointInTimeRecoveryDescription && {
          PointInTimeRecoveryStatus: state.pointInTimeRecoveryDescription.PointInTimeRecoveryStatus,
          RecoveryPeriodInDays: state.pointInTimeRecoveryDescription.RecoveryPeriodInDays,
        },
        tags: state.tags,
      });

      // DynamoDB omits `BillingModeSummary` for tables that have always been
      // PROVISIONED — fall back to the observed throughput (on-demand tables
      // report 0 read capacity).
      const observedBillingModeOf = (table: DynamoDB.TableDescription): DynamoDB.BillingMode =>
        table.BillingModeSummary?.BillingMode ??
        ((table.ProvisionedThroughput?.ReadCapacityUnits ?? 0) > 0
          ? "PROVISIONED"
          : "PAY_PER_REQUEST");

      // Encrypted with a KMS key (AWS managed or customer managed) rather
      // than the default AWS owned key.
      const isKmsEncrypted = (sse: DynamoDB.SSEDescription | undefined) =>
        sse?.Status === "ENABLED" || sse?.Status === "ENABLING" || sse?.Status === "UPDATING";

      /**
       * The table configuration `alchemy drift` compares: every setting
       * reconcile converges, as observed. `read` and `reconcile` share it so
       * a converged table reads unchanged. Transitional statuses
       * (ENABLING, UPDATING) count as their target so a just-applied change
       * is not reported as drift.
       */
      const observeTableConfiguration = Effect.fn(function* (
        state: {
          table: DynamoDB.TableDescription;
          timeToLiveDescription: DynamoDB.TimeToLiveDescription | undefined;
        },
        props: { onDemandThroughput?: DynamoDB.OnDemandThroughput } | undefined,
      ) {
        const { table } = state;
        const [policy, destinations, insights] = yield* Effect.all(
          [
            readTableResourcePolicy(table.TableArn!),
            dynamodb.describeKinesisStreamingDestination({ TableName: table.TableName! }).pipe(
              Effect.map((response) => response.KinesisDataStreamDestinations ?? []),
              Effect.retry({
                while: isRetryableControlPlaneError,
                schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
              }),
            ),
            dynamodb.describeContributorInsights({ TableName: table.TableName! }).pipe(
              Effect.map((response) => response.ContributorInsightsStatus ?? "DISABLED"),
              Effect.retry({
                while: isRetryableControlPlaneError,
                schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
              }),
            ),
          ],
          { concurrency: "unbounded" },
        );
        const billingMode = observedBillingModeOf(table);
        const sse = table.SSEDescription;
        const ttl = state.timeToLiveDescription;
        const kinesisStreamingDestinations = destinations
          .filter(
            (destination) =>
              destination.StreamArn !== undefined &&
              (destination.DestinationStatus === "ACTIVE" ||
                destination.DestinationStatus === "ENABLING" ||
                destination.DestinationStatus === "UPDATING"),
          )
          .map((destination) => ({
            streamArn: destination.StreamArn!,
            approximateCreationDateTimePrecision:
              destination.ApproximateCreationDateTimePrecision ?? "MILLISECOND",
          }))
          .sort((a, b) => a.streamArn.localeCompare(b.streamArn));
        return {
          billingMode,
          provisionedThroughput:
            billingMode === "PROVISIONED"
              ? normalizeProvisioned(table.ProvisionedThroughput)
              : undefined,
          onDemandThroughput:
            props?.onDemandThroughput === undefined
              ? undefined
              : normalizeOnDemand(table.OnDemandThroughput),
          deletionProtectionEnabled: table.DeletionProtectionEnabled ?? false,
          sseDescription: isKmsEncrypted(sse)
            ? { sseType: sse?.SSEType, kmsMasterKeyArn: sse?.KMSMasterKeyArn }
            : undefined,
          tableClass: table.TableClassSummary?.TableClass ?? "STANDARD",
          timeToLiveAttributeName:
            ttl?.TimeToLiveStatus === "ENABLED" || ttl?.TimeToLiveStatus === "ENABLING"
              ? ttl.AttributeName
              : undefined,
          resourcePolicy: canonicalPolicyDocument(policy),
          kinesisStreamingDestinations:
            kinesisStreamingDestinations.length > 0 ? kinesisStreamingDestinations : undefined,
          contributorInsightsEnabled: insights === "ENABLED" || insights === "ENABLING",
        } satisfies Partial<Table["Attributes"]>;
      });

      const indexesByName = <T extends { IndexName?: string }>(indexes: readonly T[] | undefined) =>
        Object.fromEntries((indexes ?? []).map((index) => [index.IndexName!, index])) as Record<
          string,
          T
        >;

      // KeySchema order is significant with multi-attribute keys: partition
      // attributes are hashed together in declaration order and sort key
      // attributes are queried left-to-right. Only the HASH/RANGE grouping is
      // normalized (DescribeTable reports all HASH elements before all RANGE
      // elements regardless of how the request interleaved them); the relative
      // order within each group must be preserved — reordering attributes
      // defines a different index.
      const normalizeKeySchema = (keySchema: readonly DynamoDB.KeySchemaElement[] | undefined) => {
        const elements = (keySchema ?? []).map((element) => ({
          AttributeName: element.AttributeName,
          KeyType: element.KeyType,
        }));
        return [
          ...elements.filter((element) => element.KeyType === "HASH"),
          ...elements.filter((element) => element.KeyType === "RANGE"),
        ];
      };

      const normalizeProjection = (projection: DynamoDB.Projection | undefined) => ({
        ...projection,
        NonKeyAttributes: [...(projection?.NonKeyAttributes ?? [])].sort(),
      });

      const isSameGsiDefinition = (
        left: DynamoDB.GlobalSecondaryIndex,
        right: DynamoDB.GlobalSecondaryIndex,
      ) =>
        JSON.stringify(normalizeKeySchema(left.KeySchema)) ===
          JSON.stringify(normalizeKeySchema(right.KeySchema)) &&
        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,
      ) => {
        const oldByName = indexesByName(olds);
        const newByName = indexesByName(news);
        const updates: DynamoDB.GlobalSecondaryIndexUpdate[] = [];
        let requiresReplacement = false;

        for (const [indexName, oldIndex] of Object.entries(oldByName)) {
          const newIndex = newByName[indexName];
          if (!newIndex) {
            updates.push({
              Delete: {
                IndexName: indexName,
              },
            });
            continue;
          }

          if (!isSameGsiDefinition(oldIndex, newIndex)) {
            requiresReplacement = true;
            continue;
          }

          // 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,
                ProvisionedThroughput: newIndex.ProvisionedThroughput,
                OnDemandThroughput: newIndex.OnDemandThroughput,
                WarmThroughput: newIndex.WarmThroughput,
              },
            });
          }
        }

        for (const [indexName, newIndex] of Object.entries(newByName)) {
          if (!oldByName[indexName]) {
            updates.push({
              Create: {
                IndexName: indexName,
                KeySchema: newIndex.KeySchema,
                Projection: newIndex.Projection,
                ProvisionedThroughput: newIndex.ProvisionedThroughput,
                OnDemandThroughput: newIndex.OnDemandThroughput,
                WarmThroughput: newIndex.WarmThroughput,
              },
            });
          }
        }

        return {
          updates,
          requiresReplacement,
        };
      };

      return Table.Provider.of({
        stables: ["tableName", "tableId", "tableArn", "region"],
        // Enumerate every table in the ambient account/region. `listTables`
        // returns only names, so each is hydrated to the full Attributes shape
        // via the same multi-API read helper (`readTableState`) `read` uses.
        list: () =>
          Effect.gen(function* () {
            const names = yield* dynamodb.listTables.items({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk)),
            );
            const states = yield* Effect.forEach(
              names,
              (tableName) =>
                readTableState(tableName).pipe(
                  // Hydrating every table fires four describe calls each.
                  // Across a busy account this trips DynamoDB's read throttle,
                  // and a table that isn't ACTIVE yet (a peer mid-create)
                  // transiently rejects the continuous-backups/TTL describes
                  // with ValidationException. Both are transient — retry to
                  // converge so a table that *is* ours still hydrates fully.
                  Effect.retry({
                    while: (e) =>
                      e._tag === "ThrottlingException" || e._tag === "ValidationException",
                    schedule: Schedule.max([
                      Schedule.exponential(250).pipe(Schedule.jittered),
                      Schedule.recurs(12),
                    ]),
                  }),
                  // Last resort: if a foreign table never settles within the
                  // retry budget (e.g. a peer is still mid-create/delete when
                  // we give up), skip it rather than failing the whole
                  // enumeration. Our own table is ACTIVE by the time list()
                  // runs, so it always hydrates via the retry above.
                  //
                  // `AccessDeniedException` is the same case seen from the
                  // other side: enumerating an account walks tables we do not
                  // own, and one can deny the tag read outright (a restrictive
                  // resource policy live; a peer test's table under the local
                  // emulator). A table we cannot read is not ours to return.
                  // `TableNotFoundException` completes the set: a peer can
                  // delete a table between `listTables` and our describes, and
                  // that is what DynamoDB raises for a table that vanished.
                  Effect.catchTag(
                    [
                      "ValidationException",
                      "AccessDeniedException",
                      "TableNotFoundException",
                      "ResourceNotFoundException",
                    ],
                    () => Effect.undefined,
                  ),
                ),
              { concurrency: 8 },
            );