effect-dynamodb 1.24.0 → 1.26.0

package/dist/Entity.js

@@ -9,9 +9,10 @@
 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 { packedIndexRefusal } from "@effect-dynamodb/schema/internal/EntityPacked.js";
 import * as KeyComposer from "@effect-dynamodb/schema/KeyComposer.js";
 import { normalizeGsiConfig } from "@effect-dynamodb/schema/KeyComposer.js";
 import { deriveSourceText } from "@effect-dynamodb/schema/VectorIndex.js";
@@ -20,8 +21,12 @@ 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 { decodeImage, imageEntityType, ownRowsRawRow, packAttributeValueSync, packedExprRefusal, packedProjectionRefusal, packItemSync, unpackRow, withRegistry, } from "./internal/Packed.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 +136,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 +225,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 +236,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;
 /**
@@ -673,17 +616,46 @@ const makeImpl = (config, precomputedData) => {
             if (encoded.issue !== undefined) {
                 return `.set() of immutable "${field}": ${String(encoded.issue)}`;
             }
-            out.push({ field, attr: resolveDbName(field), value: toAttributeValue(encoded.encoded) });
+            out.push({
+                field,
+                attr: resolveDbName(field),
+                value: toAttributeValue(encoded.encoded),
+                wire: encoded.encoded,
+                packed: field in packedFields,
+            });
         }
         return out;
     };
+    const immutableChangedMessage = (field) => `.set() of "${field}": "${field}" is immutable and the update's value ` +
+        "differs from the stored one.";
+    /** A restated immutable value that differs from the stored item's (packed fields excepted). */
     const immutableMismatch = (asserted, stored) => {
-        const changed = asserted.find(({ attr, value }) => !attributeValueEquals(stored[attr], value));
-        return changed === undefined
-            ? undefined
-            : `.set() of "${changed.field}": "${changed.field}" is immutable and the update's value ` +
-                "differs from the stored one.";
+        const changed = asserted.find(({ attr, value, packed }) => !packed && !attributeValueEquals(stored[attr], value));
+        return changed === undefined ? undefined : immutableChangedMessage(changed.field);
     };
+    /**
+     * A restated immutable PACKED value that differs from the stored item's,
+     * compared by the stored value's unpacked JSON (#147) — whatever codec or
+     * threshold it was written under.
+     */
+    const packedImmutableMismatch = (asserted, stored) => Effect.gen(function* () {
+        for (const { field, attr, wire, packed } of asserted) {
+            if (!packed)
+                continue;
+            const storedValue = stored[attr];
+            if (storedValue === undefined) {
+                if (wire === undefined || wire === null)
+                    continue;
+                return immutableChangedMessage(field);
+            }
+            const raw = fromAttributeMap({ [attr]: storedValue });
+            yield* unpackFields(raw, "update.decode");
+            if (!attributeValueEquals(toAttributeValue(raw[attr]), toAttributeValue(wire))) {
+                return immutableChangedMessage(field);
+            }
+        }
+        return undefined;
+    });
     /**
      * Whether an update can safely create the item it names (#133): its payload
      * supplies every required model field and every primary-key composite, so
@@ -739,6 +711,136 @@ const makeImpl = (config, precomputedData) => {
             return;
         decodeSparseFields(raw, sparseFields);
     };
+    // ---------------------------------------------------------------------------
+    // Packed fields (`storedAs: DynamoModel.Packed`) — see
+    // `docs/designs/storage-encoding.md` §6. Packing runs after renames and
+    // sparse flattening, before `toAttributeMap`; unpacking after
+    // `fromAttributeMap`, before sparse rebuild and renames — the same points as
+    // the sparse layout, keyed by stored attribute names.
+    // ---------------------------------------------------------------------------
+    const { packedFields, packedAttributes, dispatchAttributes, hasPackedFields } = data;
+    /**
+     * Pack, in place, the packed attributes of a stored-name item. `only`
+     * restricts it to those stored attributes (the read-merge update path packs
+     * only the fields it names: the others still hold their stored value).
+     */
+    const packFields = (item, operation, only) => {
+        if (!hasPackedFields)
+            return Effect.void;
+        const targets = only === undefined
+            ? packedAttributes
+            : Object.fromEntries(Object.entries(packedAttributes).filter(([attr]) => only.has(attr)));
+        if (Object.keys(targets).length === 0)
+            return Effect.void;
+        return withRegistry((registry) => packItemSync(item, targets, registry, { entityType, operation: `${operation}.packed` }));
+    };
+    /** Pack one attribute's wire value straight to its `AttributeValue` (an `UpdateItem` SET). */
+    const packAttribute = (attribute, wire, operation) => withRegistry((registry) => packAttributeValueSync(packedAttributes[attribute], wire, registry, { entityType, operation: `${operation}.packed` }, attribute));
+    /**
+     * Read, in place, the dispatch-eligible attributes of a stored-name row by
+     * their stored form. A row with no string or binary value on any of them
+     * (every native row) costs one `typeof` per attribute.
+     */
+    const unpackFields = (raw, operation = "decode") => dispatchAttributes.length === 0
+        ? Effect.void
+        : unpackRow(raw, dispatchAttributes, { entityType, operation });
+    /**
+     * A domain-named copy of `record` with its packed (or once-packed) attributes
+     * read by their stored form. The update paths derive vector source text from
+     * it: an untouched packed field still holds its stored value there (a JSON
+     * string or compressed bytes), not the value the source `compose` expects.
+     * `record` itself is left as is, so the write still carries the stored bytes.
+     */
+    const unpackedDomainCopy = (record, operation) => {
+        if (dispatchAttributes.length === 0)
+            return Effect.succeed(record);
+        const stored = { ...record };
+        renameToDynamo(stored);
+        return Effect.map(unpackFields(stored, operation), () => {
+            renameFromDynamo(stored);
+            return stored;
+        });
+    };
+    /** The packed attributes an expression or projection may not look inside (EDD-9076). */
+    const packedGuards = Object.entries(packedFields).flatMap(([field, storedAs]) => {
+        const guard = (attribute) => ({
+            attribute,
+            owner: `Entity "${entityType}"`,
+            storedAs,
+            alternative: () => `To filter on it, use .filterBy((item) => ...), which runs on the decoded item; to ` +
+                `condition a write on it, read the item and compare in code, then write the whole ` +
+                `value with .set({ ${field} }).`,
+        });
+        const stored = resolveDbName(field);
+        return stored === field ? [guard(field)] : [guard(field), guard(stored)];
+    });
+    /** Throw `[EDD-9076]` when an expression looks inside a packed field. */
+    const refusePackedExpr = (expr, usage) => {
+        const refused = packedExprRefusal(expr, packedGuards, usage);
+        if (refused !== undefined)
+            throw new Error(refused);
+    };
+    /**
+     * The `Query.make` options of this entity's queries: the packed guards, and
+     * the raw-row hook that reads packed attributes of a projected row of THIS
+     * entity type by their stored form (parsed JSON, not schema-decoded) — rows
+     * of other types (`ignoreOwnership()`) are left untouched.
+     */
+    const packedQueryOptions = {
+        packed: packedGuards,
+        rawRow: ownRowsRawRow(entityType, dispatchAttributes, (raw) => unpackFields(raw)),
+    };
+    /**
+     * `[EDD-9077]`: an update applies anything but a whole-value `.set()` /
+     * `.remove()` to a packed field — DynamoDB cannot compute inside one opaque
+     * value. `undefined` when the update is fine.
+     */
+    const refusedPackedUpdate = (uState) => {
+        if (!hasPackedFields)
+            return undefined;
+        const refuse = (op, field) => `[EDD-9077] Entity "${entityType}": ${op} on "${field}", but "${field}" is stored packed ` +
+            `(format "${packedFields[field].format}"): DynamoDB holds it as one opaque string or ` +
+            `binary value and cannot apply ${op} inside it. Write the whole value with ` +
+            `.set({ ${field} }) (or .remove(["${field}"])).`;
+        const records = [
+            [".add()", uState.add],
+            [".subtract()", uState.subtract],
+            [".append()", uState.append],
+            [".deleteFromSet()", uState.deleteFromSet],
+        ];
+        for (const [op, values] of records) {
+            for (const field of Object.keys(values ?? {})) {
+                if (field in packedFields)
+                    return refuse(op, field);
+            }
+        }
+        const pathOps = [
+            ["pathSet", uState.pathSets ?? []],
+            ["pathRemove", (uState.pathRemoves ?? []).map((segments) => ({ segments }))],
+            ["pathAdd", uState.pathAdds ?? []],
+            ["pathSubtract", uState.pathSubtracts ?? []],
+            ["pathAppend", uState.pathAppends ?? []],
+            ["pathPrepend", uState.pathPrepends ?? []],
+            ["pathIfNotExists", uState.pathIfNotExists ?? []],
+            ["pathDelete", uState.pathDeletes ?? []],
+        ];
+        for (const [op, ops] of pathOps) {
+            for (const { segments } of ops) {
+                const head = segments[0];
+                if (typeof head === "string" && head in packedFields)
+                    return refuse(op, head);
+            }
+        }
+        for (const { field } of uState.sparseRemoveEntries ?? []) {
+            if (field in packedFields)
+                return refuse(".removeEntries()", field);
+        }
+        for (const field of uState.sparseClearFields ?? []) {
+            if (field in packedFields)
+                return refuse(".clearMap()", field);
+        }
+        return undefined;
+    };
     /**
      * A DOMAIN-keyed VIEW of a row that came off the wire.
      *
@@ -833,6 +935,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);
@@ -979,43 +1134,68 @@ const makeImpl = (config, precomputedData) => {
         const corruption = versionCorruption(raw, "decode");
         if (corruption !== undefined)
             return Effect.fail(corruption);
-        deserializeSparseFields(raw);
-        renameFromDynamo(raw);
-        return Schema.decodeUnknownEffect(schemas.recordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "decode",
-            cause,
-        })));
+        return Effect.flatMap(unpackFields(raw), () => {
+            deserializeSparseFields(raw);
+            renameFromDynamo(raw);
+            return Schema.decodeUnknownEffect(schemas.recordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
+                entityType,
+                operation: "decode",
+                cause,
+            })));
+        });
     };
     /** Decode a raw item using the schema selected by mode */
     const decodeAs = (raw, marshalled, mode) => {
         const corruption = versionCorruption(raw, "decode");
         if (corruption !== undefined)
             return Effect.fail(corruption);
+        // Native: the item as stored — packed values stay their `S` / `B`.
         if (mode === "native")
             return Effect.succeed(marshalled);
-        // Collect flattened sparse-map attributes back into the domain Record.
-        // Must happen before rename so the rebuilt Record sits at the domain field
-        // name (sparse field renaming is not supported).
+        return Effect.flatMap(unpackFields(raw), () => {
+            // Collect flattened sparse-map attributes back into the domain Record.
+            // Must happen before rename so the rebuilt Record sits at the domain field
+            // name (sparse field renaming is not supported).
+            deserializeSparseFields(raw);
+            // Rename DynamoDB attributes back to domain field names. Substituted
+            // schemas handle wire→domain conversion (date primitives, Redacted, etc.).
+            renameFromDynamo(raw);
+            const targetSchema = mode === "model"
+                ? schemas.modelSchema
+                : mode === "record"
+                    ? schemas.recordSchema
+                    : schemas.itemSchema;
+            return Schema.decodeUnknownEffect(targetSchema)(raw).pipe(Effect.map((decoded) => mode === "model" && isSchemaClass && !hasHiddenFields
+                ? new rawModel(decoded)
+                : mode !== "item"
+                    ? attachPrototype(decoded)
+                    : decoded), Effect.mapError((cause) => new ValidationError({
+                entityType,
+                operation: "decode",
+                cause,
+            })));
+        });
+    };
+    /**
+     * Decode a DynamoDB Streams image into an item record (`Entity.Item`): the
+     * image normalised (DynamoDB JSON or unmarshalled; `B` as bytes or base64),
+     * its dispatch-eligible attributes read by stored form, then sparse rebuild,
+     * renames and the item-schema decode — exactly what a table read applies.
+     */
+    const decodeImageItem = (image) => Effect.gen(function* () {
+        // An image of another entity type is decoded as 1.25.0 decoded it: its
+        // attributes are never read as packed values (a plain string of that
+        // type is not this entity's JSON). The type is read off the raw image.
+        const owner = imageEntityType(image);
+        const raw = yield* decodeImage(image, owner === undefined || owner === entityType ? dispatchAttributes : [], { entityType, operation: "decodeMarshalledItem" }, { probe: config.indexes.primary.pk.field });
+        const corruption = versionCorruption(raw, "decodeMarshalledItem");
+        if (corruption !== undefined)
+            return yield* corruption;
         deserializeSparseFields(raw);
-        // Rename DynamoDB attributes back to domain field names. Substituted
-        // schemas handle wire→domain conversion (date primitives, Redacted, etc.).
         renameFromDynamo(raw);
-        const targetSchema = mode === "model"
-            ? schemas.modelSchema
-            : mode === "record"
-                ? schemas.recordSchema
-                : schemas.itemSchema;
-        return Schema.decodeUnknownEffect(targetSchema)(raw).pipe(Effect.map((decoded) => mode === "model" && isSchemaClass && !hasHiddenFields
-            ? new rawModel(decoded)
-            : mode !== "item"
-                ? attachPrototype(decoded)
-                : decoded), Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "decode",
-            cause,
-        })));
-    };
+        const decoded = yield* Schema.decodeUnknownEffect(schemas.itemSchema)(raw).pipe(Effect.mapError((cause) => new ValidationError({ entityType, operation: "decodeMarshalledItem", cause })));
+        return attachPrototype(decoded);
+    });
     const nowIso = (now) => DateTime.formatIso(now);
     /**
      * Generate a timestamp value as a wire primitive ready for marshalling.
@@ -1320,6 +1500,9 @@ const makeImpl = (config, precomputedData) => {
             const current = yield* client.getItem({ TableName: tableName, Key: marshalledKey });
             if (current.Item) {
                 const currentDomain = fromAttributeMap(current.Item);
+                // Packed fields are read by their stored form: the source text is
+                // derived from the value, not its JSON string or compressed bytes.
+                yield* unpackFields(currentDomain, "update.vector");
                 renameFromDynamo(currentDomain);
                 merged = { ...currentDomain, ...merged };
             }
@@ -1485,25 +1668,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 +1678,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 +1706,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 +1765,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) => {
@@ -1711,16 +1869,18 @@ const makeImpl = (config, precomputedData) => {
         if (mode === "native")
             return Effect.succeed(projected);
         const raw = fromAttributeMap(projected);
-        deserializeSparseFields(raw);
-        renameFromDynamo(raw);
-        const target = mode === "model"
-            ? schemas.modelSchema
-            : mode === "record"
-                ? schemas.recordSchema
-                : schemas.itemSchema;
-        const fields = target.fields;
-        const present = Object.fromEntries(Object.entries(fields).filter(([name]) => name in raw));
-        return Schema.decodeUnknownEffect(Schema.Struct(present))(raw).pipe(Effect.mapError((cause) => new ValidationError({ entityType, operation: "decode", cause })));
+        return Effect.flatMap(unpackFields(raw), () => {
+            deserializeSparseFields(raw);
+            renameFromDynamo(raw);
+            const target = mode === "model"
+                ? schemas.modelSchema
+                : mode === "record"
+                    ? schemas.recordSchema
+                    : schemas.itemSchema;
+            const fields = target.fields;
+            const present = Object.fromEntries(Object.entries(fields).filter(([name]) => name in raw));
+            return Schema.decodeUnknownEffect(Schema.Struct(present))(raw).pipe(Effect.mapError((cause) => new ValidationError({ entityType, operation: "decode", cause })));
+        });
     };
     /**
      * The value an update returns for its `returnValues` mode, from the item
@@ -2192,15 +2352,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 +2512,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 +2523,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 +2678,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 +2723,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 +2737,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({
@@ -2730,6 +2928,11 @@ const makeImpl = (config, precomputedData) => {
                 cause: e instanceof Error ? e.message : String(e),
             });
         }
+        // Pack `storedAs: DynamoModel.Packed` fields to their stored form
+        // (JSON string, or compressed binary over the threshold) — after
+        // renames and sparse flattening, before marshalling, so every size
+        // measured from here on is the stored size.
+        yield* packFields(item, operation);
         // The caller's condition, ANDed onto `create`'s not-exists guard —
         // a guard no `.condition()` can replace (#133). `upsert`'s create
         // attempt brings its own (`runGuardedPut` requires the item missing).
@@ -2778,7 +2981,7 @@ const makeImpl = (config, precomputedData) => {
                     });
                 }
                 return err;
-            }));
+            }), diagnoseItemWrite("put", { Put: putInput }));
         }
         // Decode and return using selected mode
         return yield* decodeAs(item, marshalledItem, mode);
@@ -2816,6 +3019,14 @@ const makeImpl = (config, precomputedData) => {
         let projectionExpression;
         let projectionNames;
         if (opts.projection && opts.projection.length > 0) {
+            const packedProjection = packedProjectionRefusal(opts.projection.map((attribute) => [attribute]), packedGuards);
+            if (packedProjection !== undefined) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "get.projection",
+                    cause: packedProjection,
+                });
+            }
             const proj = Projection.projection(opts.projection);
             projectionExpression = proj.expression;
             projectionNames = proj.names;
@@ -2832,9 +3043,12 @@ const makeImpl = (config, precomputedData) => {
         if (!result.Item) {
             return yield* new ItemNotFound({ entityType, key: encodedKey });
         }
-        // Raw mode: return unmarshalled record without schema decode
+        // Raw mode: return unmarshalled record without schema decode — a
+        // packed attribute as its parsed JSON (#147).
         if (mode === "raw") {
-            return fromAttributeMap(result.Item);
+            const row = fromAttributeMap(result.Item);
+            yield* unpackFields(row);
+            return row;
         }
         // Unmarshall and decode using selected mode
         const raw = fromAttributeMap(result.Item);
@@ -2849,6 +3063,15 @@ const makeImpl = (config, precomputedData) => {
      * Used instead of reading it again: the write is guarded on it either way.
      */
     preRead) => Effect.gen(function* () {
+        // A packed field takes only a whole-value .set() / .remove() (#147).
+        const packedRefusal = refusedPackedUpdate(requested);
+        if (packedRefusal !== undefined) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "update",
+                cause: packedRefusal,
+            });
+        }
         // Path operations on a field that feeds a key or a unique sentinel
         // become the record operations they are equivalent to, or are
         // refused (#133) — before anything reads the state.
@@ -3241,7 +3464,10 @@ const makeImpl = (config, precomputedData) => {
                 const embedFor = new Set(vectorIndexesNeedingUpdate(collectTouchedFields(hydratedUpdates, uState), uState.withVectors).map(([logicalName]) => logicalName));
                 // `newItem` is the fully merged post-update item (removals already
                 // applied above), so a put-style recompute is exact.
-                const vectorWrite = yield* computeVectorAttributes(newItem, uState.withVectors, embedFor);
+                // Untouched packed fields still hold their stored form on `newItem`
+                // (kept byte-identical for the write diff), so the source text is
+                // derived from an unpacked copy.
+                const vectorWrite = yield* computeVectorAttributes(yield* unpackedDomainCopy(newItem, "update.vector"), uState.withVectors, embedFor);
                 Object.assign(newItem, vectorWrite.sets);
                 for (const field of vectorWrite.removes)
                     delete newItem[field];
@@ -3259,9 +3485,17 @@ const makeImpl = (config, precomputedData) => {
                     cause: e instanceof Error ? e.message : String(e),
                 });
             }
+            // Pack only the packed fields this update names: the others still
+            // hold the stored value read above (a string or bytes), carried
+            // byte-identical so the "write only what differs" diff below leaves
+            // them alone (#147).
+            yield* packFields(newItem, "update", new Set(Object.entries(hydratedUpdates)
+                .filter(([field, value]) => field in packedFields && value != null)
+                .map(([field]) => resolveDbName(field))));
             const currentItem = currentResult.Item;
             yield* checkVersion(currentItem, "update");
-            const immutableChange = immutableMismatch(immutables, currentItem);
+            const immutableChange = immutableMismatch(immutables, currentItem) ??
+                (yield* packedImmutableMismatch(immutables, currentItem));
             if (immutableChange !== undefined) {
                 return yield* new ValidationError({
                     entityType,
@@ -3414,12 +3648,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 +3666,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 +3718,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 +3766,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 +3798,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) {
@@ -3609,7 +3836,8 @@ const makeImpl = (config, precomputedData) => {
                 return yield* missingItem();
             }
             yield* checkVersion(current.Item, "update");
-            const immutableChange = immutableMismatch(immutables, current.Item);
+            const immutableChange = immutableMismatch(immutables, current.Item) ??
+                (yield* packedImmutableMismatch(immutables, current.Item));
             if (immutableChange !== undefined) {
                 return yield* new ValidationError({
                     entityType,
@@ -3662,6 +3890,28 @@ const makeImpl = (config, precomputedData) => {
             [uState.remove, uState.sparseRemoveEntries, uState.sparseClearFields].every((ops) => ops === undefined || ops.length === 0) &&
             [uState.add, uState.subtract, uState.append, uState.deleteFromSet].every((ops) => ops === undefined || Object.keys(ops).length === 0) &&
             !hasPathOps(uState);
+        // A restated packed immutable cannot be asserted by a condition on its
+        // stored bytes (they depend on the codec and threshold it was written
+        // under): an unread write reads it and compares the unpacked JSON
+        // (#147). The write still requires the item (`attribute_exists`), and
+        // no library write changes an immutable value in between.
+        if (plainWrite && immutables.some((asserted) => asserted.packed)) {
+            const stored = yield* client.getItem({
+                TableName: tableName,
+                Key: marshalledKey,
+                ConsistentRead: true,
+            });
+            if (stored.Item !== undefined) {
+                const packedChange = yield* packedImmutableMismatch(immutables, stored.Item);
+                if (packedChange !== undefined) {
+                    return yield* new ValidationError({
+                        entityType,
+                        operation: "update",
+                        cause: packedChange,
+                    });
+                }
+            }
+        }
         // Build UpdateExpression
         const setClauses = [];
         const names = {};
@@ -3723,8 +3973,13 @@ const makeImpl = (config, precomputedData) => {
             }
             const nameKey = `#u${counter}`;
             const valKey = `:u${counter}`;
-            names[nameKey] = resolveDbName(attr);
-            values[valKey] = toAttributeValue(val);
+            const storedName = resolveDbName(attr);
+            names[nameKey] = storedName;
+            // A packed field is written whole, as its stored form (#147).
+            values[valKey] =
+                attr in packedFields
+                    ? (yield* packAttribute(storedName, val, "update"))
+                    : toAttributeValue(val);
             setClauses.push(`${nameKey} = ${valKey}`);
             counter++;
         }
@@ -4123,7 +4378,9 @@ const makeImpl = (config, precomputedData) => {
         }
         if (plainWrite) {
             // Restated immutable values must match the item's.
-            for (const [i, { attr, value }] of immutables.entries()) {
+            for (const [i, { attr, value, packed }] of immutables.entries()) {
+                if (packed)
+                    continue; // read and compared above (#147)
                 names[`#imm${i}`] = attr;
                 values[`:imm${i}`] = value;
                 condParts.push(`#imm${i} = :imm${i}`);
@@ -4137,14 +4394,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 +4424,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 +4440,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 +4457,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 +4480,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 +4491,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 +4521,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 +4720,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 +4788,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 +4811,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 +4821,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 +4839,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 +4868,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 +4908,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);
@@ -4887,8 +5127,13 @@ const makeImpl = (config, precomputedData) => {
             }
             const nameKey = `#u${counter}`;
             const valKey = `:u${counter}`;
-            names[nameKey] = resolveDbName(attr);
-            values[valKey] = toAttributeValue(val);
+            const storedName = resolveDbName(attr);
+            names[nameKey] = storedName;
+            // A packed field is written whole, as its stored form (#147).
+            values[valKey] =
+                attr in packedFields
+                    ? (yield* packAttribute(storedName, val, "upsert"))
+                    : toAttributeValue(val);
             // Immutable fields use if_not_exists — only set on first create
             if (immutableFields.has(attr)) {
                 setClauses.push(`${nameKey} = if_not_exists(${nameKey}, ${valKey})`);
@@ -5005,8 +5250,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 +5262,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 +5272,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 });
@@ -5118,6 +5364,16 @@ const makeImpl = (config, precomputedData) => {
         // `append` takes its condition as an argument — no `condition`
         // combinator — so an empty one becomes none here (#133).
         const userCondition = nonEmptyCondition(givenCondition);
+        if (userCondition !== undefined) {
+            const packedRefusal = packedExprRefusal(toExpr(userCondition), packedGuards, "condition");
+            if (packedRefusal !== undefined) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "append.condition",
+                    cause: packedRefusal,
+                });
+            }
+        }
         const emptyPart = userCondition === undefined ? undefined : emptyPartProblem(toExpr(userCondition));
         if (emptyPart !== undefined) {
             return yield* new ValidationError({
@@ -5215,6 +5471,15 @@ const makeImpl = (config, precomputedData) => {
         });
         // `encoded` is already in wire-form via Schema.encode — used directly.
         const serialisedInput = { ...encoded };
+        // Packed `appendInput` fields (#147), packed ONCE: the same stored value
+        // is SET on the current item and written on the event item.
+        const packedStored = {};
+        for (const field of Object.keys(packedFields)) {
+            if (serialisedInput[field] !== undefined) {
+                packedStored[resolveDbName(field)] = serialisedInput[field];
+            }
+        }
+        yield* packFields(packedStored, "append");
         // ---------- Build UpdateItem (scoped SET + CAS) ----------
         const setClauses = [];
         const names = {};
@@ -5231,8 +5496,9 @@ const makeImpl = (config, precomputedData) => {
                 continue;
             const nameKey = `#a${counter}`;
             const valKey = `:a${counter}`;
-            names[nameKey] = resolveDbName(attr);
-            values[valKey] = toAttributeValue(val);
+            const storedName = resolveDbName(attr);
+            names[nameKey] = storedName;
+            values[valKey] = toAttributeValue(attr in packedFields ? packedStored[storedName] : val);
             setClauses.push(`${nameKey} = ${valKey}`);
             counter++;
         }
@@ -5331,6 +5597,8 @@ const makeImpl = (config, precomputedData) => {
         const eventItem = { ...encoded };
         // Rename domain → DB names for the Put (matches put path)
         renameToDynamo(eventItem);
+        // The packed fields' stored values — the same ones SET above (#147).
+        Object.assign(eventItem, packedStored);
         // pk + sk (event)
         eventItem[primary.pk.field] = pkValue;
         eventItem[primary.sk.field] = eventSk;
@@ -5368,30 +5636,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).
@@ -5488,13 +5768,15 @@ const makeImpl = (config, precomputedData) => {
             // NOT carry `<prefix>#*` attributes. `deserializeSparseFields` populates
             // empty `{}` Records under the domain field names so the historyRecord
             // schema (which still includes the sparse Record fields) decodes.
-            deserializeSparseFields(raw);
-            renameFromDynamo(raw);
-            return Schema.decodeUnknownEffect(schemas.historyRecordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
-                entityType,
-                operation: "history.decode",
-                cause,
-            })));
+            return Effect.flatMap(unpackFields(raw, "history.decode"), () => {
+                deserializeSparseFields(raw);
+                renameFromDynamo(raw);
+                return Schema.decodeUnknownEffect(schemas.historyRecordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
+                    entityType,
+                    operation: "history.decode",
+                    cause,
+                })));
+            });
         };
         return Query.make({
             tableName: "",
@@ -5504,6 +5786,7 @@ const makeImpl = (config, precomputedData) => {
             skField: primary.sk.field,
             entityTypes: [entityType],
             decoder: (raw) => decodeHistory(raw),
+            ...packedQueryOptions,
             resolveTableName: tableTag.useSync((tc) => tc.name),
             keyFields: [primary.pk.field, primary.sk.field],
         }).pipe(Query.where({ beginsWith: prefix }));
@@ -5525,12 +5808,13 @@ 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,
                 entityTypes: [entityType],
                 decoder: (raw) => decodeRecord(raw),
+                ...packedQueryOptions,
+                ...packedQueryOptions,
                 resolveTableName: tableTag.useSync((tc) => tc.name),
                 keyFields: [
                     indexDef.pk.field,
@@ -5538,6 +5822,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
@@ -5558,6 +5844,7 @@ const makeImpl = (config, precomputedData) => {
         indexName: undefined,
         entityTypes: [entityType],
         decoder: (raw) => decodeRecord(raw),
+        ...packedQueryOptions,
         resolveTableName: tableTag.useSync((tc) => tc.name),
         keyFields: [config.indexes.primary.pk.field, config.indexes.primary.sk.field],
         liveRows: liveRows(),
@@ -5661,6 +5948,7 @@ const makeImpl = (config, precomputedData) => {
             skField: primary.sk.field,
             entityTypes: [entityType],
             decoder: (raw) => decodeRecord(raw),
+            ...packedQueryOptions,
             resolveTableName: tableTag.useSync((tc) => tc.name),
             keyFields: [primary.pk.field, primary.sk.field],
             prepare: withLegacy,
@@ -5687,6 +5975,9 @@ const makeImpl = (config, precomputedData) => {
         // (itemSchema would fail because it expects GSI key fields that aren't present)
         if (mode === "native")
             return tombstone;
+        // Packed fields: read by their stored form (copied as-is onto the
+        // tombstone, #147).
+        yield* unpackFields(raw, "deleted.get.decode");
         // Sparse Map fields: rebuild domain Records from flattened attrs so
         // soft-deleted items decode correctly. Sparse data is preserved
         // verbatim across soft-delete (GSI keys are stripped, sparse data is
@@ -5715,16 +6006,18 @@ const makeImpl = (config, precomputedData) => {
             const corruption = versionCorruption(raw, "deleted.list.decode");
             if (corruption !== undefined)
                 return Effect.fail(corruption);
-            // Sparse fields are domain data and are preserved across soft-delete.
-            // Rebuild Records from flattened attrs before schema decode.
-            deserializeSparseFields(raw);
-            // Then attribute → domain names, same order as `decodeRecord` (#127).
-            renameFromDynamo(raw);
-            return Schema.decodeUnknownEffect(schemas.deletedRecordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
-                entityType,
-                operation: "deleted.list.decode",
-                cause,
-            })));
+            return Effect.flatMap(unpackFields(raw, "deleted.list.decode"), () => {
+                // Sparse fields are domain data and are preserved across soft-delete.
+                // Rebuild Records from flattened attrs before schema decode.
+                deserializeSparseFields(raw);
+                // Then attribute → domain names, same order as `decodeRecord` (#127).
+                renameFromDynamo(raw);
+                return Schema.decodeUnknownEffect(schemas.deletedRecordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
+                    entityType,
+                    operation: "deleted.list.decode",
+                    cause,
+                })));
+            });
         };
         return Query.make({
             tableName: "",
@@ -5734,6 +6027,7 @@ const makeImpl = (config, precomputedData) => {
             skField: primary.sk.field,
             entityTypes: [],
             decoder: (raw) => decodeDeleted(raw),
+            ...packedQueryOptions,
             resolveTableName: tableTag.useSync((tc) => tc.name),
             keyFields: [primary.pk.field, primary.sk.field],
         }).pipe(Query.where({ beginsWith: deletedPrefix }));
@@ -5874,7 +6168,6 @@ const makeImpl = (config, precomputedData) => {
                 });
             }
         }
-        yield* checkTransactionLimit(entityType, "restore", transactItems);
         yield* client
             .transactWriteItems({
             TransactItems: transactItems,
@@ -5921,7 +6214,7 @@ const makeImpl = (config, precomputedData) => {
                 }
             }
             return err;
-        }));
+        }), diagnoseTransactionWrite("restore", transactItems));
         return yield* decodeAs(restoredItem, marshalledRestoredItem, mode);
     }), self, key);
     // ---------------------------------------------------------------------------
@@ -6067,24 +6360,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);
     // ---------------------------------------------------------------------------
@@ -6102,6 +6448,7 @@ const makeImpl = (config, precomputedData) => {
         const expr = typeof cbOrShorthand === "function"
             ? cbOrShorthand(entityPathBuilder, entityConditionOps)
             : parseSimpleShorthand(cbOrShorthand);
+        refusePackedExpr(expr, "condition");
         return (self) => conditionCombinator(self, expr);
     };
     /**
@@ -6112,17 +6459,25 @@ const makeImpl = (config, precomputedData) => {
         const expr = typeof cbOrShorthand === "function"
             ? cbOrShorthand(entityPathBuilder, entityConditionOps)
             : parseSimpleShorthand(cbOrShorthand);
+        refusePackedExpr(expr, "filter");
         return (q) => filterExpr(q, expr);
     };
     /**
      * Build a select (projection) combinator from callback or string array.
      */
     const entitySelect = (cbOrAttrs) => {
+        const refuse = (paths) => {
+            const refused = packedProjectionRefusal(paths, packedGuards);
+            if (refused !== undefined)
+                throw new Error(refused);
+        };
         if (typeof cbOrAttrs === "function") {
             const paths = cbOrAttrs(entityPathBuilder);
             const segments = paths.map((p) => p.segments);
+            refuse(segments);
             return (q) => selectPaths(q, segments);
         }
+        refuse(cbOrAttrs.map((attribute) => [attribute]));
         return (q) => Query.select(q, cbOrAttrs);
     };
     // ---------------------------------------------------------------------------
@@ -6150,8 +6505,14 @@ const makeImpl = (config, precomputedData) => {
         generatedId: config.generatedId,
         vectorIndexes: config.vectorIndexes,
         _vectorIndexes: vectorIndexes,
+        _packedFields: Object.keys(packedFields),
+        _packFields: packFields,
+        _unpackFields: unpackFields,
+        _dispatchAttributes: dispatchAttributes,
+        _packedGuards: packedGuards,
+        _decodeImage: decodeImageItem,
         _resolvedRefs: resolvedRefs,
-        /** @internal Full decode pipeline: rename + schema decode. Used by Batch/Aggregate. */
+        /** @internal Full decode pipeline: unpack + sparse + rename + schema decode. Used by Batch/Aggregate. */
         _decodeRecord: decodeRecord,
         /** @internal Domain field name → stored attribute name (`storedAs` renames). */
         _resolveDbName: resolveDbName,
@@ -6173,6 +6534,9 @@ const makeImpl = (config, precomputedData) => {
             tableTag = injectedTableTag;
         },
         _injectIndex: (name, def) => {
+            const refused = packedIndexRefusal(entityType, packedFields, name, def);
+            if (refused !== undefined)
+                throw new Error(refused);
             allIndexes = { ...allIndexes, [name]: def };
         },
         get _schema() {
@@ -6360,8 +6724,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 +6734,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;
@@ -6575,12 +6951,27 @@ export const itemSchema = (entity) => entity.schemas.itemSchema;
 /**
  * Decode a marshalled DynamoDB item (AttributeValue format) into a typed Entity.Record.
  *
- * Unmarshalls the AttributeValue map to plain JS, then decodes via the entity's item schema.
- * Useful for consuming DynamoDB Streams events or raw SDK responses.
+ * Built for DynamoDB Streams records (`NewImage` / `OldImage`) and raw SDK
+ * responses. Applies exactly what a table read applies:
+ *
+ * - **Packed fields** (`storedAs: DynamoModel.Packed`) are read by their
+ *   stored form — a legacy native map, a JSON string (`S`), or compressed
+ *   binary (`B`). Lambda and EventBridge Pipes deliver `B` / `BS` members as
+ *   base64 text; they are decoded at any depth.
+ * - Sparse-map fields are rebuilt and `field:` renames reversed.
+ *
+ * Accepts DynamoDB JSON (`{ pk: { S: "…" }, … }`, `B` as bytes or base64) or
+ * an already-unmarshalled item. Fails with `ValidationError` if the item does
+ * not match the schema, or when a compressed value's codec is not registered —
+ * its `cause` is then a `CompressorNotRegistered` (register the codec with a
+ * `Compression.layer([...])` provided where the decode runs).
  *
- * Returns an Effect that fails with `ValidationError` if the item doesn't match the schema.
+ * Note: {@link itemSchema} is a pure schema over unmarshalled items and does
+ * not unpack — use this for entities with packed fields.
  */
 export const decodeMarshalledItem = (entity, marshalledItem) => {
+    if (entity._decodeImage !== undefined)
+        return entity._decodeImage(marshalledItem);
     const corruption = entity._versionCorruption?.(marshalledItem, "decodeMarshalledItem");
     if (corruption !== undefined)
         return Effect.fail(corruption);