effect-dynamodb 1.24.0 → 1.25.0

package/dist/Entity.js

@@ -9,7 +9,7 @@
 import { getIdentifierField, getSparseFields, isConfiguredModel, isRefField, } from "@effect-dynamodb/schema/DynamoModel.js";
 import * as DynamoSchema from "@effect-dynamodb/schema/DynamoSchema.js";
 import { Embedder } from "@effect-dynamodb/schema/Embedder.js";
-import { CascadePartialFailure, ConcurrentModification, ConditionalCheckFailed, DeleteAppliedButUnreadable, EmbeddingError, ItemNotDeleted, ItemNotFound, isAwsConditionalCheckFailed, isAwsTransactionCancelled, OptimisticLockError, RefNotFound, StaleAppend, TransactionOverflow, UniqueConstraintViolation, UpdateAppliedButUnreadable, ValidationError, } from "@effect-dynamodb/schema/Errors.js";
+import { CascadePartialFailure, ConcurrentModification, ConditionalCheckFailed, DeleteAppliedButUnreadable, DynamoError, EmbeddingError, ItemNotDeleted, ItemNotFound, isAwsConditionalCheckFailed, isAwsTransactionCancelled, OptimisticLockError, RefNotFound, StaleAppend, TransactionOverflow, UniqueConstraintViolation, UpdateAppliedButUnreadable, ValidationError, } from "@effect-dynamodb/schema/Errors.js";
 import { makeCompositeKeyForm, toCompositeKeyRecord, } from "@effect-dynamodb/schema/internal/CompositeCodec.js";
 import { makeDefaultCrypto } from "@effect-dynamodb/schema/internal/DefaultCrypto.js";
 import * as KeyComposer from "@effect-dynamodb/schema/KeyComposer.js";
@@ -20,8 +20,11 @@ import { DynamoClient } from "./DynamoClient.js";
 import { isBoundOp, makeBoundAppend, makeBoundDelete, makeBoundGet, makeBoundPut, makeBoundUpdate, } from "./internal/BoundCrud.js";
 import { BoundQueryImpl, entityNaming, } from "./internal/BoundQuery.js";
 import { compileExpr, createConditionOps, emptyPartProblem, isExpr, nonEmptyCondition, parseShorthand, parseSimpleShorthand, toExpr, } from "./internal/Expr.js";
+import { countOperators, expressionFits } from "./internal/ExpressionLimits.js";
+import { BASE_DELAY_MS, MAX_RETRIES } from "./internal/Hydrate.js";
 import { compilePath, createPathBuilder } from "./internal/PathBuilder.js";
 import { freshIncarnationToken, generateTimestampPrimitive, INCARNATION_TOKEN, UNSENTINELED_DEFAULTS, } from "./internal/TransactableOps.js";
+import { batchEntries, diagnosedValidationError, diagnoseFailure, keyAttributesOf, targetsFor, transactItemTarget, } from "./internal/WriteDiagnosis.js";
 import { decodeSparseFields, encodeSparseFields, fromAttributeMap, toAttributeMap, toAttributeValue, } from "./Marshaller.js";
 import * as Query from "./Query.js";
 import { filterExpr, selectPaths } from "./Query.js";
@@ -131,58 +134,8 @@ const keyFormFor = (target, record) => {
  */
 class MissingForCreate extends Data.TaggedError("MissingForCreate") {
 }
-/** DynamoDB's limits on one expression: its length, and its operators + functions. */
-const EXPRESSION_LIMIT = 4096;
-const OPERATOR_LIMIT = 300;
-/**
- * The tokens of a compiled expression. Names and values are placeholders
- * (`#…`, `:…`), so no operator can hide inside one.
- */
-const EXPRESSION_TOKEN = /#\w+|:\w+|<>|<=|>=|[=<>()+\-,.[\]]|[A-Za-z_]\w*|\d+/g;
-/**
- * The operators DynamoDB counts against an expression's 300 (#133), measured
- * against DynamoDB: in a condition, each comparison (`=`, `<>`, `<`, `<=`,
- * `>`, `>=`), `AND` / `OR` / `NOT`, `BETWEEN` (whose own `AND` is part of it,
- * not another operator), `IN`, and each function; in an update, each `+` /
- * `-` and each function (`if_not_exists`, `list_append`) — a `SET` clause's
- * `=` is not an operator.
- */
-/** @internal */
-export const countOperators = (expression, kind) => {
-    const tokens = expression.match(EXPRESSION_TOKEN) ?? [];
-    let count = 0;
-    let betweens = 0;
-    for (const [i, token] of tokens.entries()) {
-        const word = token.toUpperCase();
-        const isFunction = /^[A-Za-z_]\w*$/.test(token) && tokens[i + 1] === "(";
-        if (kind === "update") {
-            if (token === "+" || token === "-" || isFunction)
-                count++;
-            continue;
-        }
-        if (isFunction)
-            count++;
-        else if (["=", "<>", "<", "<=", ">", ">="].includes(token))
-            count++;
-        else if (word === "BETWEEN") {
-            count++;
-            betweens++;
-        }
-        else if (word === "AND" && betweens > 0)
-            betweens--;
-        else if (word === "AND" || word === "OR" || word === "NOT" || word === "IN")
-            count++;
-    }
-    return count;
-};
-/** What DynamoDB counts against an expression's limits. */
-const expressionCost = (expression, kind = "condition") => expression === undefined
-    ? { length: 0, operators: 0 }
-    : { length: expression.length, operators: countOperators(expression, kind) };
-const expressionFits = (expression, kind = "condition") => {
-    const cost = expressionCost(expression, kind);
-    return cost.length <= EXPRESSION_LIMIT && cost.operators <= OPERATOR_LIMIT;
-};
+/** @internal Re-exported for tests: what DynamoDB counts against an expression's 300 operators. */
+export { countOperators };
 const bytesKey = (bytes) => Array.from(bytes).join(",");
 /** Structural equality of two marshalled values (sets compare as sets). */
 const attributeValueEquals = (a, b) => {
@@ -270,9 +223,6 @@ Effect.catch(() => Effect.fail(new ValidationError({
     operation: `${operation}.decode`,
     cause: primaryCause,
 }))))));
-// ---------------------------------------------------------------------------
-// Transaction limit pre-check (100-item DynamoDB limit)
-// ---------------------------------------------------------------------------
 /**
  * Compile a condition that may be either an Expr ADT node or a ConditionInput object.
  * Routes both paths through the Expr ADT compiler for a single compilation backend.
@@ -284,15 +234,6 @@ const compileCondition = (cond, resolveDbNameFn) => {
     const expr = isExpr(cond) ? cond : parseShorthand(cond);
     return compileExpr(expr, resolveDbNameFn);
 };
-const TRANSACTION_LIMIT = 100;
-const checkTransactionLimit = (entityType, operation, items) => items.length > TRANSACTION_LIMIT
-    ? Effect.fail(new TransactionOverflow({
-        entityType,
-        operation,
-        itemCount: items.length,
-        limit: TRANSACTION_LIMIT,
-    }))
-    : Effect.void;
 /** Attempts a guarded put makes before it reports a lost race (#133). */
 const GUARDED_PUT_ATTEMPTS = 3;
 /**
@@ -833,6 +774,59 @@ const makeImpl = (config, precomputedData) => {
      * through `keyForm(...)`.
      */
     const keyForm = (record) => toCompositeKeyRecord(compositeKeyForm, record);
+    // -------------------------------------------------------------------------
+    // Write-limit diagnosis (#144)
+    //
+    // DynamoDB's limits — 400 KB per item, 100 items and 4 MB per transaction,
+    // 1024-byte sort keys — are not pre-checked. Every write is sent; when
+    // DynamoDB rejects it, `internal/WriteDiagnosis.ts` recognises the
+    // rejection, confirms it against the request and names the item. Applied
+    // after each site's conditional-failure mapping; nothing runs on success.
+    // -------------------------------------------------------------------------
+    const entityKeyFields = () => [
+        config.indexes.primary.pk.field,
+        config.indexes.primary.sk.field,
+    ];
+    const entityKeys = () => keyAttributesOf(config.indexes);
+    /**
+     * Diagnose a rejected single-item write (`PutItem` / `UpdateItem` /
+     * `DeleteItem`). `callerCondition`: the caller's own `.condition()` within
+     * the write's condition, to say how much of an over-long one is theirs.
+     */
+    const diagnoseItemWrite = (operation, item, callerCondition) => diagnoseFailure({
+        sent: () => ({
+            _tag: "Item",
+            item,
+            target: () => targetsFor([item], entityKeyFields(), entityType, () => `the ${entityType} ${operation}`)[0],
+            callerCondition,
+        }),
+        keys: entityKeys,
+        rewrite: (diagnosis, original) => diagnosedValidationError(diagnosis, original, { operation, entityType }),
+    });
+    /**
+     * Diagnose a rejected `TransactWriteItems` of this entity's write: over 100
+     * items is `TransactionOverflow`, every other limit `ValidationError`.
+     */
+    const diagnoseTransactionWrite = (operation, items, 
+    /** The caller's own `.condition()` within the first item's (its main write's) condition. */
+    callerCondition) => diagnoseFailure({
+        sent: () => ({
+            _tag: "Transaction",
+            items,
+            targets: () => targetsFor(items, entityKeyFields(), entityType, (index) => index === 0 ? "the item" : `item ${index} of the ${operation} transaction`),
+            callerCondition: (index) => (index === 0 ? callerCondition?.() : undefined),
+        }),
+        keys: entityKeys,
+        rewrite: (diagnosis, original) => diagnosis._tag === "TooManyItems"
+            ? new TransactionOverflow({
+                entityType,
+                operation,
+                itemCount: diagnosis.count,
+                limit: diagnosis.limit,
+                cause: original,
+            })
+            : diagnosedValidationError(diagnosis, original, { operation, entityType }),
+    });
     const composePrimaryKey = (record) => {
         const primary = config.indexes.primary;
         const recordKeyForm = keyForm(record);
@@ -1485,25 +1479,6 @@ const makeImpl = (config, precomputedData) => {
         }
         return new ConditionalCheckFailed({ entityType, key });
     };
-    /**
-     * A condition the library sends — its own guard plus the user's
-     * `.condition()` — that exceeds DynamoDB's limits on one expression (4 KB,
-     * 300 operators and functions): refused BEFORE writing (#133).
-     */
-    const oversizedCondition = (operation, condition, user) => {
-        if (condition === undefined || expressionFits(condition))
-            return undefined;
-        const own = expressionCost(user);
-        return new ValidationError({
-            entityType,
-            operation,
-            cause: `The ${operation}'s condition is ${expressionCost(condition).length} characters / ` +
-                `${expressionCost(condition).operators} operators — beyond DynamoDB's limits on one ` +
-                `expression (${EXPRESSION_LIMIT} characters, ${OPERATOR_LIMIT} operators). The ` +
-                `.condition() alone is ${own.length} characters / ${own.operators} operators, and ` +
-                "the library's own guard needs room beside it: simplify the condition.",
-        });
-    };
     /** The domain field a stored attribute holds (`storedAs` renames reversed). */
     const domainNameOf = (attr) => Object.keys(data.modelFields).find((field) => resolveDbName(field) === attr) ?? attr;
     /**
@@ -1514,7 +1489,9 @@ const makeImpl = (config, precomputedData) => {
      * absent). `"item"` means the whole item — a tombstone copies all of it —
      * so every stored attribute is guarded, plus every attribute the entity
      * knows of that was absent; an item too wide for that falls back to the
-     * strongest guard within DynamoDB's expression limit (never a refusal).
+     * strongest guard within DynamoDB's expression limit (never a refusal). A
+     * guard that cannot fit beside `others` at all is sent as it is: DynamoDB
+     * rejects the expression, and the rejection is diagnosed (#144).
      */
     const deleteGuard = (read, dependsOn, 
     /** The rest of the condition, ANDed with the guard (the user's, …). */
@@ -1540,15 +1517,10 @@ const makeImpl = (config, precomputedData) => {
             const incarnation = incarnationGuard(read, names, values);
             if (incarnation !== undefined)
                 parts.push(incarnation);
-            const expression = parts.join(" AND ");
-            if (!fits(expression))
-                return tooLargeBeside(expression);
-            return { expression, names, values, inputs: [] };
+            return { expression: parts.join(" AND "), names, values, inputs: [] };
         }
         names["#dpk"] = pkField;
         parts.push("attribute_exists(#dpk)");
-        if (!fits(parts.join(" AND ")))
-            return tooLargeBeside(parts.join(" AND "));
         const attrs = dependsOn === "item"
             ? [
                 ...new Set([
@@ -1604,9 +1576,6 @@ const makeImpl = (config, precomputedData) => {
             inputs.push(attr);
         }
         return { expression, names, values, inputs };
-        function tooLargeBeside(guard) {
-            return (oversizedCondition("write", others === undefined || others === "" ? guard : `${guard} AND (${others})`, others) ?? new ValidationError({ entityType, operation: "write", cause: "condition too large" }));
-        }
     };
     /** Which predicate rejected a guarded delete — from the stored item (ALL_OLD). */
     const deleteRejection = (key, read, inputs, stored, userCondition) => {
@@ -2192,15 +2161,12 @@ const makeImpl = (config, precomputedData) => {
                 inputs: [],
             }
             : deleteGuard(current, uniqueAttrs, userCondition?.expression);
-        if (guard instanceof ValidationError)
-            return yield* guard;
         const mainValues = { ...guard.values, ...userCondition?.values };
+        // Sent as built: a condition over DynamoDB's expression limits is
+        // DynamoDB's to reject, and is diagnosed naming the caller's part (#144).
         const mainCondition = userCondition
             ? `${guard.expression} AND (${userCondition.expression})`
             : guard.expression;
-        const tooLarge = oversizedCondition(args.operation, mainCondition, userCondition?.expression);
-        if (tooLarge !== undefined)
-            return yield* tooLarge;
         const items = [
             {
                 Put: {
@@ -2355,7 +2321,6 @@ const makeImpl = (config, precomputedData) => {
         let lost;
         for (let attempt = 0; attempt < GUARDED_PUT_ATTEMPTS; attempt++) {
             const plan = yield* planPut(args);
-            yield* checkTransactionLimit(entityType, args.operation, plan.items);
             const write = plan.items.length === 1
                 ? client.putItem(plan.items[0].Put)
                 : client.transactWriteItems({ TransactItems: [...plan.items] });
@@ -2367,7 +2332,11 @@ const makeImpl = (config, precomputedData) => {
                         : undefined;
                 const read = reasons !== undefined ? plan.verdict(reasons) : undefined;
                 return read !== undefined ? Effect.succeed(read) : Effect.fail(err);
-            }));
+            }), 
+            // Terminal: a diagnosed limit is never retried as a lost race.
+            plan.items.length === 1
+                ? diagnoseItemWrite(args.operation, plan.items[0], () => args.userCondition?.expression)
+                : diagnoseTransactionWrite(args.operation, plan.items, () => args.userCondition?.expression));
             if (verdict === undefined)
                 return plan;
             switch (verdict._tag) {
@@ -2518,6 +2487,11 @@ const makeImpl = (config, precomputedData) => {
             }
             // Resolve target table name
             const { name: targetTableName } = yield* target._tableTag;
+            // The target's primary-key attributes. A target need not be keyed `pk` /
+            // `sk`, and one cascade can span targets keyed differently, so each
+            // update reads its key — and is diagnosed — by its own target's fields.
+            const targetPrimary = target.indexes.primary;
+            const keyFields = [targetPrimary.pk.field, targetPrimary.sk.field];
             // Compose GSI PK for the source entity's ID
             const targetSchema = target._schema;
             const gsiPkValue = KeyComposer.composePk(targetSchema, target.entityType, cascadeIdx.indexDef, keyFormFor(target, { [matchingRef.idFieldName]: sourceIdValue }));
@@ -2558,8 +2532,10 @@ const makeImpl = (config, precomputedData) => {
                 });
                 for (const item of queryResult.Items ?? []) {
                     allUpdateOps.push({
+                        entityType: target.entityType,
                         tableName: targetTableName,
-                        key: { pk: item.pk, sk: item.sk },
+                        key: { [keyFields[0]]: item[keyFields[0]], [keyFields[1]]: item[keyFields[1]] },
+                        keyFields,
                         refFieldName: matchingRef.fieldName,
                         refData: toAttributeValue(sourceDomainData),
                     });
@@ -2570,45 +2546,76 @@ const makeImpl = (config, precomputedData) => {
         if (allUpdateOps.length === 0)
             return;
         if (mode === "transactional") {
-            // Transactional mode — fail if >100 items
-            if (allUpdateOps.length > 100) {
-                return yield* new CascadePartialFailure({
+            // Transactional mode — one atomic transaction. DynamoDB's limits (100
+            // items, 4 MB, item size, sort keys) are not pre-checked (#144): a
+            // rejection is diagnosed and reported as a cascade that wrote nothing.
+            const cascadeItems = allUpdateOps.map((op) => ({
+                Update: {
+                    TableName: op.tableName,
+                    Key: op.key,
+                    UpdateExpression: "SET #ref = :refData",
+                    ExpressionAttributeNames: { "#ref": op.refFieldName },
+                    ExpressionAttributeValues: { ":refData": op.refData },
+                },
+            }));
+            yield* client.transactWriteItems({ TransactItems: [...cascadeItems] }).pipe(diagnoseFailure({
+                sent: () => ({
+                    _tag: "Transaction",
+                    items: cascadeItems,
+                    targets: () => cascadeItems.map((item, index) => {
+                        const op = allUpdateOps[index];
+                        return transactItemTarget(item, op.tableName, op.keyFields, op.entityType, `the cascade update of ${op.entityType} (item ${index})`);
+                    }),
+                }),
+                keys: () => ({
+                    partition: [...new Set(allUpdateOps.map((op) => op.keyFields[0]))],
+                    sort: [...new Set(allUpdateOps.map((op) => op.keyFields[1]))],
+                }),
+                rewrite: (diagnosis, original) => new CascadePartialFailure({
                     sourceEntity: sourceEntityType,
                     sourceId: sourceIdValue,
                     succeeded: 0,
                     failed: allUpdateOps.length,
-                    errors: [`Transactional cascade exceeded 100-item limit: ${allUpdateOps.length} items`],
-                });
-            }
-            yield* client.transactWriteItems({
-                TransactItems: allUpdateOps.map((op) => ({
-                    Update: {
-                        TableName: op.tableName,
-                        Key: op.key,
-                        UpdateExpression: "SET #ref = :refData",
-                        ExpressionAttributeNames: { "#ref": op.refFieldName },
-                        ExpressionAttributeValues: { ":refData": op.refData },
-                    },
-                })),
-            });
+                    errors: [
+                        diagnosedValidationError(diagnosis, original, {
+                            operation: "cascade",
+                            entityType: sourceEntityType,
+                        }),
+                    ],
+                }),
+            }));
         }
         else {
             // Eventual mode — concurrent updates with partial failure tracking
             let succeeded = 0;
             const errors = [];
-            const updateEffects = allUpdateOps.map((op) => client
-                .updateItem({
-                TableName: op.tableName,
-                Key: op.key,
-                UpdateExpression: "SET #ref = :refData",
-                ExpressionAttributeNames: { "#ref": op.refFieldName },
-                ExpressionAttributeValues: { ":refData": op.refData },
-            })
-                .pipe(Effect.tap(() => Effect.sync(() => {
-                succeeded++;
-            })), Effect.catch((err) => Effect.sync(() => {
-                errors.push(err);
-            }))));
+            const updateEffects = allUpdateOps.map((op) => {
+                const update = {
+                    TableName: op.tableName,
+                    Key: op.key,
+                    UpdateExpression: "SET #ref = :refData",
+                    ExpressionAttributeNames: { "#ref": op.refFieldName },
+                    ExpressionAttributeValues: { ":refData": op.refData },
+                };
+                return client.updateItem(update).pipe(
+                // An item the cascade grows past 400 KB is named in `errors`.
+                diagnoseFailure({
+                    sent: () => ({
+                        _tag: "Item",
+                        item: { Update: update },
+                        target: () => transactItemTarget({ Update: update }, op.tableName, op.keyFields, op.entityType, `the cascade update of ${op.entityType}`),
+                    }),
+                    keys: () => ({ partition: [op.keyFields[0]], sort: [op.keyFields[1]] }),
+                    rewrite: (diagnosis, original) => diagnosedValidationError(diagnosis, original, {
+                        operation: "cascade",
+                        entityType: op.entityType,
+                    }),
+                }), Effect.tap(() => Effect.sync(() => {
+                    succeeded++;
+                })), Effect.catch((err) => Effect.sync(() => {
+                    errors.push(err);
+                })));
+            });
             yield* Effect.all(updateEffects, { concurrency: 10 });
             if (errors.length > 0) {
                 return yield* new CascadePartialFailure({
@@ -2778,7 +2785,7 @@ const makeImpl = (config, precomputedData) => {
                     });
                 }
                 return err;
-            }));
+            }), diagnoseItemWrite("put", { Put: putInput }));
         }
         // Decode and return using selected mode
         return yield* decodeAs(item, marshalledItem, mode);
@@ -3414,12 +3421,9 @@ const makeImpl = (config, precomputedData) => {
             // versioned (exact), otherwise under the strongest guard that fits —
             // the same fallback a wide soft delete uses.
             const wide = !expressionFits(updateExpression, "update");
-            const wideGuardOrRefusal = wide && !systemFields.version
+            const wideGuard = wide && !systemFields.version
                 ? deleteGuard(currentItem, "item", condParts.slice(1).join(" AND "))
                 : undefined;
-            if (wideGuardOrRefusal instanceof ValidationError)
-                return yield* wideGuardOrRefusal;
-            const wideGuard = wideGuardOrRefusal;
             const putCondition = wideGuard === undefined
                 ? condParts.join(" AND ")
                 : [wideGuard.expression, ...condParts.slice(1)].join(" AND ");
@@ -3435,11 +3439,8 @@ const makeImpl = (config, precomputedData) => {
                 ...(Object.keys(putValues).length > 0 && { ExpressionAttributeValues: putValues }),
                 ReturnValuesOnConditionCheckFailure: "ALL_OLD",
             };
-            const tooLarge = oversizedCondition("update", wide ? putCondition : mainUpdate.ConditionExpression, userCond !== undefined
-                ? compileCondition(userCond, resolveDbName)?.expression
-                : undefined);
-            if (tooLarge !== undefined)
-                return yield* tooLarge;
+            // A condition over DynamoDB's expression limits is sent as built:
+            // DynamoDB rejects it, and the rejection is diagnosed (#144).
             // The stored attributes the rejection compares: the guarded inputs,
             // and on the wide fallback whatever else its guard covered.
             const guardedAttrs = [
@@ -3490,7 +3491,7 @@ const makeImpl = (config, precomputedData) => {
                 // write's own SET / REMOVE is the exact new image as well.
                 const result = yield* withCurrent((wide
                     ? client.putItem({ ...mainPut, ReturnValues: "ALL_OLD" })
-                    : client.updateItem({ ...mainUpdate, ReturnValues: "ALL_OLD" })).pipe(Effect.mapError((err) => isAwsConditionalCheckFailed(err.cause) ? recordRejected(err.cause.Item) : err)));
+                    : client.updateItem({ ...mainUpdate, ReturnValues: "ALL_OLD" })).pipe(Effect.mapError((err) => isAwsConditionalCheckFailed(err.cause) ? recordRejected(err.cause.Item) : err), diagnoseItemWrite("update", wide ? { Put: mainPut } : { Update: mainUpdate }, () => uc?.expression)));
                 oldImage = result.Attributes ?? currentItem;
                 const applied = {
                     ...oldImage,
@@ -3538,7 +3539,6 @@ const makeImpl = (config, precomputedData) => {
                         });
                     }
                 }
-                yield* checkTransactionLimit(entityType, "update", transactItems);
                 yield* withCurrent(client.transactWriteItems({ TransactItems: transactItems }).pipe(Effect.mapError((err) => {
                     if (isAwsTransactionCancelled(err.cause)) {
                         const reasons = err.cause.CancellationReasons;
@@ -3571,7 +3571,7 @@ const makeImpl = (config, precomputedData) => {
                         return recordRejected(err.cause.Item);
                     }
                     return err;
-                })));
+                }), diagnoseTransactionWrite("update", transactItems, () => uc?.expression)));
             }
             // Execute cascade if configured (retain path) — from the new item.
             if (uState.cascade) {
@@ -4137,14 +4137,9 @@ const makeImpl = (config, precomputedData) => {
             if (incarnation !== undefined)
                 condParts.push(incarnation);
         }
+        // Sent as built: a condition over DynamoDB's expression limits is
+        // DynamoDB's to reject, and is diagnosed naming the caller's part (#144).
         const conditionExpression = condParts.length > 0 ? condParts.join(" AND ") : undefined;
-        {
-            const tooLarge = oversizedCondition("update", conditionExpression, sentCond !== undefined
-                ? compileCondition(sentCond, resolveDbName)?.expression
-                : undefined);
-            if (tooLarge !== undefined)
-                return yield* tooLarge;
-        }
         // The top-level attributes this update writes — what `updatedOld` /
         // `updatedNew` return.
         const written = expressionTargets(updateExpression, names);
@@ -4172,11 +4167,6 @@ const makeImpl = (config, precomputedData) => {
                 if (incarnation !== undefined)
                     guardParts.push(incarnation);
             }
-            const tooLarge = oversizedCondition("update", guardParts.join(" AND "), sentCond !== undefined
-                ? compileCondition(sentCond, resolveDbName)?.expression
-                : undefined);
-            if (tooLarge !== undefined)
-                return yield* tooLarge;
             const transactItems = [
                 {
                     Update: {
@@ -4193,7 +4183,6 @@ const makeImpl = (config, precomputedData) => {
                 },
                 { Put: snapshotPut(tableName, snapshot.item) },
             ];
-            yield* checkTransactionLimit(entityType, "update", transactItems);
             yield* client.transactWriteItems({ TransactItems: transactItems }).pipe(Effect.mapError((err) => {
                 // The update is guarded by the snapshot version AND any user
                 // condition; the stored item (ALL_OLD) says which rejected it.
@@ -4211,7 +4200,7 @@ const makeImpl = (config, precomputedData) => {
                 if (isAwsConditionalCheckFailed(err.cause))
                     return rejection(err.cause.Item);
                 return err;
-            }));
+            }), diagnoseTransactionWrite("update", transactItems, () => uc?.expression));
             // A transacted Update returns no attributes. The old item is exact:
             // the version condition proves `snapshot.raw` is what it replaced.
             // The new item is read back only when needed, and proven ours.
@@ -4234,8 +4223,7 @@ const makeImpl = (config, precomputedData) => {
         // DynamoDB rejects an empty `ExpressionAttributeValues` map. When
         // the UpdateExpression is REMOVE-only (e.g. clearMap with no other
         // combinators), `values` may be empty — omit the property entirely.
-        const result = yield* client
-            .updateItem({
+        const updateInput = {
             TableName: tableName,
             Key: marshalledKey,
             UpdateExpression: updateExpression,
@@ -4246,8 +4234,8 @@ const makeImpl = (config, precomputedData) => {
                 ReturnValuesOnConditionCheckFailure: "ALL_OLD",
             }),
             ReturnValues: returned,
-        })
-            .pipe(Effect.mapError((err) => {
+        };
+        const result = yield* client.updateItem(updateInput).pipe(Effect.mapError((err) => {
             // The stored item (ALL_OLD) says what rejected the update: no
             // item (it must exist), a restated immutable value, the
             // version CAS, or the user's condition.
@@ -4276,7 +4264,7 @@ const makeImpl = (config, precomputedData) => {
                         : undefined, userCond !== undefined);
             }
             return err;
-        }));
+        }), diagnoseItemWrite("update", { Update: updateInput }, () => uc?.expression));
         // A cascade never meets an old-image mode here: that combination is
         // routed to the read-then-write branch, or read first (`casRead`).
         const newImage = wantsOld ? undefined : result.Attributes;
@@ -4475,8 +4463,6 @@ const makeImpl = (config, precomputedData) => {
                     // into them (#133).
                     yield* checkVersion(result.Item, "delete");
                     const softGuard = deleteGuard(result.Item, "item", userCondition?.expression);
-                    if (softGuard instanceof ValidationError)
-                        return yield* softGuard;
                     const raw = fromAttributeMap(result.Item);
                     // Clock-backed time source; `now` is the ISO timestamp used for the
                     // deleted SK + deletedAt, `dtNow` drives the optional TTL + snapshot.
@@ -4545,8 +4531,7 @@ const makeImpl = (config, precomputedData) => {
                     const releases = hasUniqueConstraints && !preserveUnique()
                         ? yield* ownedReleases(tableName, raw, transactItems)
                         : [];
-                    yield* checkTransactionLimit(entityType, "delete", transactItems);
-                    yield* guardedDelete(client.transactWriteItems({ TransactItems: transactItems }), result.Item, softGuard.inputs, snapshotAt, releases);
+                    yield* guardedDelete(client.transactWriteItems({ TransactItems: transactItems }), result.Item, softGuard.inputs, snapshotAt, releases).pipe(diagnoseTransactionWrite("delete", transactItems, () => userCondition?.expression));
                     return result.Item;
                 }
                 else {
@@ -4569,8 +4554,7 @@ const makeImpl = (config, precomputedData) => {
                         if (!userCondition)
                             return undefined;
                         const values = userCondition.values;
-                        yield* client
-                            .deleteItem({
+                        const missingDelete = {
                             TableName: tableName,
                             Key: marshalledKey,
                             ConditionExpression: `attribute_not_exists(#dpk) AND (${userCondition.expression})`,
@@ -4580,10 +4564,12 @@ const makeImpl = (config, precomputedData) => {
                             },
                             ...(Object.keys(values).length > 0 && { ExpressionAttributeValues: values }),
                             ReturnValuesOnConditionCheckFailure: "ALL_OLD",
-                        })
-                            .pipe(Effect.mapError((err) => isAwsConditionalCheckFailed(err.cause)
+                        };
+                        yield* client.deleteItem(missingDelete).pipe(Effect.mapError((err) => isAwsConditionalCheckFailed(err.cause)
                             ? conditionRejection(encodedKey, err.cause.Item, err.cause.Item === undefined ? undefined : { version: 0 }, true)
-                            : err));
+                            : err), diagnoseItemWrite("delete", {
+                            Delete: missingDelete,
+                        }));
                         return undefined;
                     }
                     // The sentinel deletes are keyed by the unique values read, and the
@@ -4596,8 +4582,6 @@ const makeImpl = (config, precomputedData) => {
                             ...new Set(Object.values(config.unique).flatMap((def) => resolveUniqueFields(def).map(resolveDbName))),
                         ]
                         : [], userCondition?.expression);
-                    if (hardGuard instanceof ValidationError)
-                        return yield* hardGuard;
                     const raw = fromAttributeMap(result.Item);
                     const transactItems = [];
                     // Delete entity item — index 0, and the only item conditioned on the
@@ -4627,8 +4611,7 @@ const makeImpl = (config, precomputedData) => {
                     const releases = hasUniqueConstraints
                         ? yield* ownedReleases(tableName, raw, transactItems)
                         : [];
-                    yield* checkTransactionLimit(entityType, "delete", transactItems);
-                    yield* guardedDelete(client.transactWriteItems({ TransactItems: transactItems }), result.Item, hardGuard.inputs, snapshotAt, releases);
+                    yield* guardedDelete(client.transactWriteItems({ TransactItems: transactItems }), result.Item, hardGuard.inputs, snapshotAt, releases).pipe(diagnoseTransactionWrite("delete", transactItems, () => userCondition?.expression));
                     return result.Item;
                 }
             });
@@ -4668,9 +4651,9 @@ const makeImpl = (config, precomputedData) => {
             if (opts.returnValues !== undefined) {
                 deleteInput.ReturnValues = opts.returnValues === "allOld" ? "ALL_OLD" : "NONE";
             }
-            const output = yield* client
-                .deleteItem(deleteInput)
-                .pipe(Effect.mapError(mapDeleteConditionFailure));
+            const output = yield* client.deleteItem(deleteInput).pipe(Effect.mapError(mapDeleteConditionFailure), diagnoseItemWrite("delete", {
+                Delete: deleteInput,
+            }));
             return yield* deletedResult(output.Attributes);
         }
     }), self, key);
@@ -5005,8 +4988,7 @@ const makeImpl = (config, precomputedData) => {
             Object.assign(names, uc.names);
             Object.assign(values, uc.values);
         }
-        const result = yield* client
-            .updateItem({
+        const upsertInput = {
             TableName: tableName,
             Key: marshalledKey,
             UpdateExpression: updateExpression,
@@ -5018,8 +5000,8 @@ const makeImpl = (config, precomputedData) => {
                 ReturnValuesOnConditionCheckFailure: "ALL_OLD",
             }),
             ReturnValues: "ALL_NEW",
-        })
-            .pipe(Effect.mapError((err) => {
+        };
+        const result = yield* client.updateItem(upsertInput).pipe(Effect.mapError((err) => {
             if (isAwsConditionalCheckFailed(err.cause)) {
                 const corrupt = versionCorruption(err.cause.Item, "upsert");
                 if (corrupt !== undefined)
@@ -5028,6 +5010,8 @@ const makeImpl = (config, precomputedData) => {
                     return new ConditionalCheckFailed({ entityType, key: item });
             }
             return err;
+        }), diagnoseItemWrite("upsert", {
+            Update: upsertInput,
         }));
         if (!result.Attributes) {
             return yield* new ItemNotFound({ entityType, key: item });
@@ -5368,30 +5352,42 @@ const makeImpl = (config, precomputedData) => {
         }
         const marshalledEventItem = toAttributeMap(eventItem);
         // ---------- Execute TransactWriteItems ----------
-        const transactResult = yield* client
-            .transactWriteItems({
-            TransactItems: [
-                {
-                    Update: {
-                        TableName: tableName,
-                        Key: marshalledKey,
-                        UpdateExpression: updateExpression,
-                        ConditionExpression: finalCondition,
-                        ExpressionAttributeNames: names,
-                        ExpressionAttributeValues: values,
-                    },
+        const appendItems = [
+            {
+                Update: {
+                    TableName: tableName,
+                    Key: marshalledKey,
+                    UpdateExpression: updateExpression,
+                    ConditionExpression: finalCondition,
+                    ExpressionAttributeNames: names,
+                    ExpressionAttributeValues: values,
                 },
-                {
-                    Put: {
-                        TableName: tableName,
-                        Item: marshalledEventItem,
-                    },
+            },
+            {
+                Put: {
+                    TableName: tableName,
+                    Item: marshalledEventItem,
                 },
-            ],
-        })
-            .pipe(Effect.matchEffect({
+            },
+        ];
+        const transactResult = yield* client.transactWriteItems({ TransactItems: appendItems }).pipe(
+        // A limit DynamoDB enforced (#144) — the current item grown past
+        // 400 KB, an oversized event item, an over-long sort key — is
+        // diagnosed first: such a cancellation carries no conditional
+        // failure, so it is never a stale append.
+        diagnoseFailure({
+            sent: () => ({
+                _tag: "Transaction",
+                items: appendItems,
+                targets: () => targetsFor(appendItems, entityKeyFields(), entityType, (index) => index === 0 ? "the current item" : "the event item"),
+            }),
+            keys: entityKeys,
+            rewrite: (diagnosis, original) => diagnosedValidationError(diagnosis, original, { operation: "append", entityType }),
+        }), Effect.matchEffect({
             onSuccess: () => Effect.succeed({ stale: false }),
             onFailure: (err) => {
+                if (err._tag === "ValidationError")
+                    return Effect.fail(err);
                 // TransactionCancelled or ConditionalCheckFailed at the transaction
                 // level both surface here. Disambiguation between CAS and
                 // user-condition happens after the follow-up GetItem (when run).
@@ -5525,7 +5521,6 @@ const makeImpl = (config, precomputedData) => {
             const query = Query.make({
                 tableName: "",
                 indexName: indexDef.index,
-                globalIndex: indexDef.index !== undefined,
                 pkField: indexDef.pk.field,
                 pkValue,
                 skField: indexDef.sk.field,
@@ -5538,6 +5533,8 @@ const makeImpl = (config, precomputedData) => {
                     config.indexes.primary.pk.field,
                     config.indexes.primary.sk.field,
                 ],
+                // DynamoDB's rejection of the key condition (#144) names the accessor.
+                keyConditionDiagnosis: { operation: "query", label: `${entityType}.query.${indexName}` },
             });
             if (hasSkComposites) {
                 // `composeSortKeyBeginsWith`, not `composeSortKeyPrefix` — the operand
@@ -5874,7 +5871,6 @@ const makeImpl = (config, precomputedData) => {
                 });
             }
         }
-        yield* checkTransactionLimit(entityType, "restore", transactItems);
         yield* client
             .transactWriteItems({
             TransactItems: transactItems,
@@ -5921,7 +5917,7 @@ const makeImpl = (config, precomputedData) => {
                 }
             }
             return err;
-        }));
+        }), diagnoseTransactionWrite("restore", transactItems));
         return yield* decodeAs(restoredItem, marshalledRestoredItem, mode);
     }), self, key);
     // ---------------------------------------------------------------------------
@@ -6067,24 +6063,77 @@ const makeImpl = (config, precomputedData) => {
             // Released one by one, each only while still this item's: a batch
             // delete cannot carry the ownership condition.
             for (const sentinel of yield* ownedSentinels(tableName, [...held.values()], owner)) {
-                yield* client.deleteItem(sentinelRelease(tableName, sentinel, owner).Delete).pipe(Effect.catchIf((err) => isAwsConditionalCheckFailed(err.cause), () => Effect.void));
-            }
-        }
-        // Batch delete in chunks of 25
+                const release = sentinelRelease(tableName, sentinel, owner);
+                yield* client.deleteItem(release.Delete).pipe(Effect.catchIf((err) => isAwsConditionalCheckFailed(err.cause), () => Effect.void), 
+                // A delete of a stored key cannot meet a size limit; wrapped
+                // for uniformity (#144), so it passes through in practice.
+                diagnoseItemWrite("purge", release));
+            }
+        }
+        // Batch delete in chunks of 25. `UnprocessedItems` are retried with
+        // `Batch.write`'s backoff; what the purge had deleted is always
+        // stated exactly, whether a request is rejected or retries run out.
+        let deleted = 0;
+        const deletedSoFar = () => deleted === 0
+            ? "the purge had deleted none of the partition's items"
+            : `the purge had already deleted ${deleted} of the partition's ${allItems.length} items`;
         for (let i = 0; i < allItems.length; i += 25) {
             const chunk = allItems.slice(i, i + 25);
-            yield* client.batchWriteItem({
-                RequestItems: {
-                    [tableName]: chunk.map((item) => ({
-                        DeleteRequest: {
-                            Key: {
-                                [primary.pk.field]: item[primary.pk.field],
-                                [primary.sk.field]: item[primary.sk.field],
-                            },
+            let requestItems = {
+                [tableName]: chunk.map((item) => ({
+                    DeleteRequest: {
+                        Key: {
+                            [primary.pk.field]: item[primary.pk.field],
+                            [primary.sk.field]: item[primary.sk.field],
                         },
-                    })),
-                },
-            });
+                    },
+                })),
+            };
+            let retries = 0;
+            for (;;) {
+                const sentItems = requestItems;
+                const sentCount = Object.values(sentItems).reduce((sum, requests) => sum + requests.length, 0);
+                const response = yield* client.batchWriteItem({ RequestItems: sentItems }).pipe(
+                // Deletes of stored keys: wrapped for uniformity (#144).
+                diagnoseFailure({
+                    sent: () => {
+                        const items = batchEntries(sentItems);
+                        return {
+                            _tag: "Batch",
+                            items,
+                            targets: () => targetsFor(items, entityKeyFields(), entityType, (index) => `purged item ${deleted + index}`),
+                        };
+                    },
+                    keys: entityKeys,
+                    rewrite: (diagnosis, original) => diagnosedValidationError(diagnosis, original, {
+                        operation: "purge",
+                        entityType,
+                        committed: `${deletedSoFar()} before it`,
+                    }),
+                }));
+                const unprocessed = {};
+                let remaining = 0;
+                for (const [table, requests] of Object.entries(response.UnprocessedItems ?? {})) {
+                    if (requests.length === 0)
+                        continue;
+                    unprocessed[table] = requests;
+                    remaining += requests.length;
+                }
+                deleted += sentCount - remaining;
+                if (remaining === 0)
+                    break;
+                retries++;
+                if (retries > MAX_RETRIES) {
+                    return yield* new DynamoError({
+                        operation: "BatchWriteItem",
+                        cause: new Error(`purge: ${remaining} of the partition's ${allItems.length} items were still ` +
+                            `unprocessed after ${MAX_RETRIES} retries; ${deletedSoFar()}. The rest ` +
+                            "were not deleted: purge again to finish."),
+                    });
+                }
+                yield* Effect.sleep(`${BASE_DELAY_MS * 2 ** (retries - 1)} millis`);
+                requestItems = unprocessed;
+            }
         }
     }), self, key);
     // ---------------------------------------------------------------------------
@@ -6360,8 +6409,7 @@ export const bind = (entity) => Effect.gen(function* () {
                 // UpdateItem would resurrect it as a key-plus-vector fragment that
                 // decodes to nothing but still answers searches. Guard on the item
                 // still existing and treat the rejection as "skipped".
-                return yield* client
-                    .updateItem({
+                const update = {
                     TableName: tableName,
                     Key: {
                         [primary.pk.field]: marshalled[primary.pk.field],
@@ -6371,8 +6419,21 @@ export const bind = (entity) => Effect.gen(function* () {
                     ConditionExpression: "attribute_exists(#pk)",
                     ExpressionAttributeNames: names,
                     ExpressionAttributeValues: values,
-                })
-                    .pipe(Effect.as(true), Effect.catchIf((err) => isAwsConditionalCheckFailed(err.cause), () => Effect.succeed(false)));
+                };
+                return yield* client.updateItem(update).pipe(Effect.as(true), Effect.catchIf((err) => isAwsConditionalCheckFailed(err.cause), () => Effect.succeed(false)), 
+                // An embedding that grows the item past 400 KB, named (#144).
+                diagnoseFailure({
+                    sent: () => ({
+                        _tag: "Item",
+                        item: { Update: update },
+                        target: () => targetsFor([{ Update: update }], [primary.pk.field, primary.sk.field], entity.entityType, () => "the re-embedded item")[0],
+                    }),
+                    keys: () => keyAttributesOf(entity.indexes),
+                    rewrite: (diagnosis, original) => diagnosedValidationError(diagnosis, original, {
+                        operation: "reembed",
+                        entityType: entity.entityType,
+                    }),
+                }));
             });
             let updated = 0;
             let exclusiveStartKey;