effect-dynamodb 1.4.0 → 1.6.0

package/dist/Entity.js

@@ -6,24 +6,24 @@
  * carries derived schemas for 7 type extractors (Model, Record, Input, Update,
  * Key, Item, Marshalled).
  */
-import { Duration, Effect, Schema, Stream } from "effect";
+import { DateTime, Duration, Effect, Option, Schema, Stream } from "effect";
 import { DynamoClient } from "./DynamoClient.js";
-import { getIdentifierField, isConfiguredModel, isHidden, isRef, isRefField, } from "./DynamoModel.js";
+import { getIdentifierField, getSparseFields, isConfiguredModel, isHidden, isRecordAst, isRecordSchema, isRef, isRefField, } from "./DynamoModel.js";
 import * as DynamoSchema from "./DynamoSchema.js";
-import { CascadePartialFailure, ConditionalCheckFailed, ItemNotFound, isAwsConditionalCheckFailed, isAwsTransactionCancelled, OptimisticLockError, RefNotFound, TransactionOverflow, UniqueConstraintViolation, ValidationError, } from "./Errors.js";
-import { makeBoundDelete, makeBoundPut, makeBoundUpdate } from "./internal/BoundCrud.js";
+import { CascadePartialFailure, CompositeKeyHoleError, ConditionalCheckFailed, ItemNotFound, isAwsConditionalCheckFailed, isAwsTransactionCancelled, OptimisticLockError, RefNotFound, StaleAppend, TransactionOverflow, UniqueConstraintViolation, ValidationError, } from "./Errors.js";
+import { makeBoundAppend, makeBoundDelete, makeBoundPut, makeBoundUpdate, } from "./internal/BoundCrud.js";
 import { BoundQueryImpl } from "./internal/BoundQuery.js";
 import { compileExpr, createConditionOps, isExpr, parseShorthand, parseSimpleShorthand, } from "./internal/Expr.js";
 import { compilePath, createPathBuilder } from "./internal/PathBuilder.js";
 import * as KeyComposer from "./KeyComposer.js";
 import { normalizeGsiConfig } from "./KeyComposer.js";
-import { fromAttributeMap, toAttributeMap, toAttributeValue } from "./Marshaller.js";
+import { decodeSparseFields, encodeSparseFields, fromAttributeMap, toAttributeMap, toAttributeValue, } from "./Marshaller.js";
 import * as Query from "./Query.js";
 import { filterExpr, selectPaths } from "./Query.js";
 export { EntityDeleteImpl, EntityDeleteTypeId, EntityGetImpl, EntityOpTypeId, EntityPutImpl, EntityUpdateImpl, EntityUpdateTypeId, emptyUpdateState, returnValuesMap, } from "./internal/EntityOps.js";
 import { EntityDeleteImpl, EntityDeleteTypeId, EntityGetImpl, EntityOpTypeId, EntityPutImpl, EntityUpdateImpl, emptyUpdateState, returnValuesMap, } from "./internal/EntityOps.js";
 import * as Projection from "./Projection.js";
-export { add, append, asItem, asModel, asNative, asRecord, cascade, consistentRead, deleteFromSet, expectedVersion, pathAdd, pathAppend, pathDelete, pathIfNotExists, pathPrepend, pathRemove, pathSet, pathSubtract, project, remove, returnValues, set, subtract, } from "./internal/EntityCombinators.js";
+export { add, append, asItem, asModel, asNative, asRecord, cascade, clearMap, consistentRead, deleteFromSet, expectedVersion, pathAdd, pathAppend, pathDelete, pathIfNotExists, pathPrepend, pathRemove, pathSet, pathSubtract, project, remove, removeEntries, returnValues, set, subtract, } from "./internal/EntityCombinators.js";
 import { asModel, condition as conditionCombinator, expectedVersion, set, } from "./internal/EntityCombinators.js";
 import { allCompositeAttributes, allKeyFieldNames, buildDerivedSchemas, buildFieldEncodings, getFields, primaryKeyComposites, resolveSystemFields, resolveUniqueFields, validateNoTransformOverride, } from "./internal/EntitySchemas.js";
 // ---------------------------------------------------------------------------
@@ -362,6 +362,64 @@ const makeImpl = (config) => {
     // encodings are NOT in `fieldEncodings`; `generateTimestamp` produces wire
     // primitives directly for non-colliding system fields.
     // ---------------------------------------------------------------------------
+    // Sparse Map fields (storedAs: 'sparse') — validation + resolution
+    // ---------------------------------------------------------------------------
+    const sparseFields = getSparseFields(config.model);
+    const hasSparseFields = Object.keys(sparseFields).length > 0;
+    if (hasSparseFields) {
+        // EDD-9020: storedAs: 'sparse' is only valid on Schema.Record fields.
+        for (const fieldName of Object.keys(sparseFields)) {
+            const fieldSchema = modelFields[fieldName];
+            if (!fieldSchema) {
+                throw new Error(`[EDD-9020] Entity "${config.entityType}": sparse field "${fieldName}" does not exist on the model`);
+            }
+            const recordInfo = isRecordSchema(fieldSchema);
+            if (!recordInfo) {
+                throw new Error(`[EDD-9020] Entity "${config.entityType}": sparse field "${fieldName}" must be a Schema.Record. ` +
+                    `Got a non-Record schema. Sparse storage flattens Record entries into per-key top-level attributes.`);
+            }
+            // EDD-9021: inner value must not be another Record (no nested sparse).
+            if (isRecordAst(recordInfo.valueAst)) {
+                throw new Error(`[EDD-9021] Entity "${config.entityType}": sparse field "${fieldName}" has a Record-typed value schema. ` +
+                    `Nested sparse Records are not supported — use Schema.Struct, Schema.Number, etc. for the inner value.`);
+            }
+        }
+        // EDD-9022: sparse fields cannot participate in primary key, GSI composites,
+        // or unique constraints — keys aren't statically known at make() time.
+        const allComposites = new Set(allCompositeAttributes(allIndexes));
+        for (const fieldName of Object.keys(sparseFields)) {
+            if (allComposites.has(fieldName)) {
+                throw new Error(`[EDD-9022] Entity "${config.entityType}": sparse field "${fieldName}" cannot be a primary-key or GSI composite. ` +
+                    `Composite values must be known at make() time; sparse-map keys are not.`);
+            }
+        }
+        if (config.unique) {
+            const sparseSet = new Set(Object.keys(sparseFields));
+            for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
+                const fields = resolveUniqueFields(constraintDef);
+                for (const f of fields) {
+                    if (sparseSet.has(f)) {
+                        throw new Error(`[EDD-9022] Entity "${config.entityType}": unique constraint "${constraintName}" cannot reference sparse field "${f}".`);
+                    }
+                }
+            }
+        }
+        // EDD-9023: sparse prefixes must be unique among themselves and must not
+        // collide with non-sparse top-level model field names.
+        const seenPrefix = new Map(); // prefix → fieldName
+        for (const [fieldName, sparse] of Object.entries(sparseFields)) {
+            const existing = seenPrefix.get(sparse.prefix);
+            if (existing) {
+                throw new Error(`[EDD-9023] Entity "${config.entityType}": sparse fields "${existing}" and "${fieldName}" share prefix "${sparse.prefix}". Prefixes must be distinct.`);
+            }
+            seenPrefix.set(sparse.prefix, fieldName);
+            // Prefix must not collide with another (non-sparse) model field name.
+            if (sparse.prefix !== fieldName && sparse.prefix in modelFields) {
+                throw new Error(`[EDD-9023] Entity "${config.entityType}": sparse field "${fieldName}" prefix "${sparse.prefix}" collides with non-sparse field "${sparse.prefix}".`);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
     // Field renaming: domain name → DynamoDB attribute name (from ConfiguredModel)
     // ---------------------------------------------------------------------------
     const fieldRenames = {}; // domain → dynamo
@@ -400,6 +458,29 @@ const makeImpl = (config) => {
     };
     /** Resolve a domain field name to its DynamoDB attribute name. */
     const resolveDbName = (domainName) => fieldRenames[domainName] ?? domainName;
+    /**
+     * Flatten sparse Map fields into per-entry top-level attributes.
+     * Called on the write path after rename + date serialization, before
+     * `toAttributeMap`. No-op when the entity has no sparse fields.
+     *
+     * Throws on key validation errors (caught by callers and translated into
+     * tagged `ValidationError` at the entity boundary).
+     */
+    const serializeSparseFields = (item) => {
+        if (!hasSparseFields)
+            return;
+        encodeSparseFields(item, sparseFields);
+    };
+    /**
+     * Rebuild sparse Map fields from flattened top-level attributes.
+     * Called on the read path after `fromAttributeMap`, before rename + date
+     * deserialization. No-op when the entity has no sparse fields.
+     */
+    const deserializeSparseFields = (raw) => {
+        if (!hasSparseFields)
+            return;
+        decodeSparseFields(raw, sparseFields);
+    };
     // ---------------------------------------------------------------------------
     // Helpers
     // ---------------------------------------------------------------------------
@@ -414,6 +495,7 @@ const makeImpl = (config) => {
     /** Attach the model class prototype to a decoded plain object (when model is Schema.Class). */
     const attachPrototype = (decoded) => isSchemaClass ? Object.assign(Object.create(rawModel.prototype), decoded) : decoded;
     const decodeRecord = (raw) => {
+        deserializeSparseFields(raw);
         renameFromDynamo(raw);
         return Schema.decodeUnknownEffect(schemas.recordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
             entityType,
@@ -425,6 +507,10 @@ const makeImpl = (config) => {
     const decodeAs = (raw, marshalled, mode) => {
         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).
+        deserializeSparseFields(raw);
         // Rename DynamoDB attributes back to domain field names. Substituted
         // schemas handle wire→domain conversion (date primitives, Redacted, etc.).
         renameFromDynamo(raw);
@@ -799,6 +885,18 @@ const makeImpl = (config) => {
         Object.assign(item, keys);
         // Rename domain fields to DynamoDB attribute names
         renameToDynamo(item);
+        // Flatten sparse Map fields into per-entry top-level attributes.
+        // Wrapped to surface key-validation errors as ValidationError.
+        try {
+            serializeSparseFields(item);
+        }
+        catch (e) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "put.sparse",
+                cause: e instanceof Error ? e.message : String(e),
+            });
+        }
         const marshalledItem = toAttributeMap(item);
         // Build user condition expression if provided
         const userCondition = opts.condition
@@ -1066,10 +1164,33 @@ const makeImpl = (config) => {
                 ...currentRaw,
             };
             renameFromDynamo(currentDomainItem);
+            // Rebuild sparse Map fields from flattened attrs into domain Records.
+            // Done in-place on the renamed domain item so subsequent merge logic
+            // operates on domain shape and re-flattening happens once at the end.
+            deserializeSparseFields(currentDomainItem);
             const newItem = { ...currentDomainItem };
+            // Apply user updates. For sparse fields, merge bucket-by-bucket
+            // rather than whole-field replace — concurrent writers to disjoint
+            // buckets must coexist (the version CAS protects against same-bucket
+            // races). Non-sparse fields use the existing replace semantics.
+            //
+            // null and undefined collapse: both signal explicit clear under
+            // indexPolicy v2 (DESIGN.md §7). For the in-memory item we DELETE
+            // the attribute (mirrors a DynamoDB REMOVE), so subsequent decode
+            // sees the field as absent rather than as a typed null that the
+            // model schema may not permit.
             for (const [attr, val] of Object.entries(hydratedUpdates)) {
-                if (val !== undefined)
+                if (val === null || val === undefined) {
+                    delete newItem[attr];
+                    continue;
+                }
+                if (hasSparseFields && attr in sparseFields && typeof val === "object") {
+                    const existing = newItem[attr] ?? {};
+                    newItem[attr] = { ...existing, ...val };
+                }
+                else {
                     newItem[attr] = val;
+                }
             }
             // Apply rich operations to in-memory item
             if (uState.remove) {
@@ -1077,6 +1198,29 @@ const makeImpl = (config) => {
                     delete newItem[attr];
                 }
             }
+            // Sparse-map removes: drop named entries from the in-memory Record.
+            if (uState.sparseRemoveEntries) {
+                for (const op of uState.sparseRemoveEntries) {
+                    if (!hasSparseFields || !(op.field in sparseFields))
+                        continue;
+                    const bucket = newItem[op.field];
+                    if (!bucket)
+                        continue;
+                    for (const k of op.keys)
+                        delete bucket[k];
+                }
+            }
+            // Sparse-map clear: blow away the entire bucket Record. The retain
+            // path always reads-then-writes the full item, so the version CAS
+            // already gives clearMap atomic semantics for free — no per-bucket
+            // GET dance needed here.
+            if (uState.sparseClearFields) {
+                for (const field of uState.sparseClearFields) {
+                    if (!hasSparseFields || !(field in sparseFields))
+                        continue;
+                    newItem[field] = {};
+                }
+            }
             if (uState.add) {
                 for (const [attr, val] of Object.entries(uState.add)) {
                     newItem[attr] = (newItem[attr] ?? 0) + val;
@@ -1120,8 +1264,57 @@ const makeImpl = (config) => {
             // `newItem` is already in domain names (the merge built it from
             // `currentDomainItem` + domain-keyed updates) — no rename needed
             // here. Recompose all keys with the updated attributes.
-            const newKeys = composeAllKeys(newItem);
-            Object.assign(newItem, newKeys);
+            //
+            // Primary key always recomposes from `newItem` (Put-style).
+            const primaryKeyMap = composePrimaryKey(newItem);
+            Object.assign(newItem, primaryKeyMap);
+            // GSI keys: route through the policy-aware composer so explicit
+            // clears (`set({ attr: null | undefined })`) and `Entity.remove`
+            // cascades match the v2 semantics applied on the standard update
+            // path. `newItem` carries stored values for any composite the
+            // user did not touch — passing it as `keyRecord` lets the
+            // composer treat omissions as no-ops (the half stays untouched
+            // because the stored value is present), while still firing the
+            // explicit-clear cascade and the SK preserve-truncation rule.
+            // See DESIGN.md §7 + §7.6.
+            const retainRemovedSet = uState.remove ? new Set(uState.remove) : undefined;
+            try {
+                const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, allIndexes, hydratedUpdates, newItem, { removedSet: retainRemovedSet });
+                for (const [field, value] of Object.entries(gsiUpdate.sets)) {
+                    newItem[field] = value;
+                }
+                for (const field of gsiUpdate.removes) {
+                    delete newItem[field];
+                }
+                // Untouched GSIs (no policy + no payload + no cascade): retain
+                // path semantics are Put-style — recompose from `newItem` and
+                // drop both keys when any composite is missing. Matches the
+                // existing `composeAllKeys` behavior for those GSIs.
+                const addressed = new Set([
+                    ...Object.keys(gsiUpdate.sets),
+                    ...gsiUpdate.removes,
+                ]);
+                for (const [indexName, indexDef] of Object.entries(allIndexes)) {
+                    if (indexName === "primary")
+                        continue;
+                    if (addressed.has(indexDef.pk.field) || addressed.has(indexDef.sk.field))
+                        continue;
+                    const keys = KeyComposer.tryComposeIndexKeys(schema, entityType, entityVersion, indexDef, newItem);
+                    if (keys) {
+                        Object.assign(newItem, keys);
+                    }
+                    else {
+                        delete newItem[indexDef.pk.field];
+                        delete newItem[indexDef.sk.field];
+                    }
+                }
+            }
+            catch (e) {
+                if (e instanceof CompositeKeyHoleError) {
+                    return yield* e;
+                }
+                throw e;
+            }
             const sentinelRotations = [];
             if (touchesUniqueFields) {
                 const currentRawRecord = currentRaw;
@@ -1146,6 +1339,17 @@ const makeImpl = (config) => {
             }
             // Convert back to DynamoDB attribute names for storage
             renameToDynamo(newItem);
+            // Flatten sparse Map fields into per-entry top-level attributes.
+            try {
+                serializeSparseFields(newItem);
+            }
+            catch (e) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "update.sparse",
+                    cause: e instanceof Error ? e.message : String(e),
+                });
+            }
             const marshalledNewItem = toAttributeMap(newItem);
             // Build snapshot of the pre-update state (only when retain is enabled)
             const snapshotItem = isRetainEnabled()
@@ -1293,12 +1497,50 @@ const makeImpl = (config) => {
         const updateSystemColliders = new Set();
         if (systemFields.updatedAtCollision && systemFields.updatedAt)
             updateSystemColliders.add(systemFields.updatedAt);
-        // Add user-provided updates
+        // Add user-provided updates. Buffered REMOVE clauses for explicit
+        // clears land in `removeClauses` below — under indexPolicy v2,
+        // `set({ attr: null | undefined })` means "remove this attribute
+        // now" (the same intent as `Entity.remove([attr])`). The two paths
+        // differ only in syntax; both surface in the UpdateExpression as
+        // REMOVE clauses, and both cascade through the policy-aware GSI
+        // composer (clearedSet auto-derived from null/undefined values).
+        // See DESIGN.md §7 for the three-way payload classification.
+        const explicitClears = [];
         for (const [attr, val] of Object.entries(encodedUpdatesMap)) {
-            if (val === undefined)
-                continue;
             if (updateSystemColliders.has(attr))
                 continue;
+            if (val === null || val === undefined) {
+                // Sparse fields: clearing a sparse field with null is a no-op
+                // here — the `.removeEntries` API is the explicit per-key
+                // remove. Skip to avoid REMOVE'ing the whole prefix erroneously.
+                if (hasSparseFields && attr in sparseFields)
+                    continue;
+                explicitClears.push(attr);
+                continue;
+            }
+            // Sparse fields: emit one SET per bucket. Whole-bucket replace
+            // semantics — concurrent writers to disjoint buckets are safe.
+            if (hasSparseFields && attr in sparseFields) {
+                if (typeof val !== "object")
+                    continue;
+                const sparse = sparseFields[attr];
+                for (const [k, v] of Object.entries(val)) {
+                    if (typeof k !== "string" || k.length === 0 || k.includes("#")) {
+                        return yield* new ValidationError({
+                            entityType,
+                            operation: "update.sparse",
+                            cause: `Sparse map "${attr}": invalid key ${JSON.stringify(k)}`,
+                        });
+                    }
+                    const nameKey = `#u${counter}`;
+                    const valKey = `:u${counter}`;
+                    names[nameKey] = `${sparse.prefix}#${k}`;
+                    values[valKey] = toAttributeValue(v);
+                    setClauses.push(`${nameKey} = ${valKey}`);
+                    counter++;
+                }
+                continue;
+            }
             const nameKey = `#u${counter}`;
             const valKey = `:u${counter}`;
             names[nameKey] = resolveDbName(attr);
@@ -1355,6 +1597,16 @@ const makeImpl = (config) => {
             }
         }
         // REMOVE
+        // Two channels feed REMOVE clauses:
+        //  1. `Entity.remove([attr])` cascade — drops the GSI for any
+        //     containing composite. Tracked in `removedSet` so the
+        //     policy-aware composer can apply the cascade rule.
+        //  2. Explicit clears in the user payload (`set({ attr: null })`).
+        //     These also REMOVE the attribute, but they do NOT cascade to
+        //     the whole GSI — instead, the policy-aware composer's
+        //     three-way classification consumes them via the auto-derived
+        //     clearedSet (preserve → truncate, sparse → drop). This
+        //     distinction is what makes hierarchical SK pruning work.
         const removedSet = uState.remove ? new Set(uState.remove) : undefined;
         if (uState.remove) {
             for (const attr of uState.remove) {
@@ -1363,11 +1615,30 @@ const makeImpl = (config) => {
                 removeClauses.push(nameKey);
             }
         }
+        for (const attr of explicitClears) {
+            const nameKey = `#r${removeClauses.length}`;
+            names[nameKey] = resolveDbName(attr);
+            removeClauses.push(nameKey);
+        }
         // Policy-aware GSI key composition. One call covers SETs (full
-        // recompose or half-wise), sparse dropout REMOVEs, and cascade
-        // REMOVEs when an Entity.remove() targets a GSI composite.
-        // See DESIGN.md §7 Policy-Aware GSI Composition.
-        const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, allIndexes, hydratedUpdates, decodedKey, { removedSet });
+        // recompose, half-wise, or SK truncation), sparse dropout REMOVEs,
+        // and cascade REMOVEs when an Entity.remove() targets a GSI
+        // composite. See DESIGN.md §7 Policy-Aware GSI Composition.
+        //
+        // The composer throws CompositeKeyHoleError (EDD-9024) when the
+        // payload describes a hole pattern (a cleared composite at SK
+        // position i with a present composite at j > i). Catch it
+        // synchronously and surface as a typed Effect failure.
+        let gsiUpdate;
+        try {
+            gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, allIndexes, hydratedUpdates, decodedKey, { removedSet });
+        }
+        catch (e) {
+            if (e instanceof CompositeKeyHoleError) {
+                return yield* e;
+            }
+            throw e;
+        }
         for (const [field, value] of Object.entries(gsiUpdate.sets)) {
             const nameKey = `#u${counter}`;
             const valKey = `:u${counter}`;
@@ -1485,6 +1756,73 @@ const makeImpl = (config) => {
                 deleteClauses.push(`${pathExpr} ${valKey}`);
             }
         }
+        // Sparse-map .removeEntries — explicit REMOVE on `<prefix>#<key>`.
+        // Each key emits one REMOVE clause through ExpressionAttributeNames
+        // (the literal "#" survives via compilePath's raw-segment escape).
+        if (uState.sparseRemoveEntries) {
+            for (const op of uState.sparseRemoveEntries) {
+                if (!hasSparseFields || !(op.field in sparseFields)) {
+                    return yield* new ValidationError({
+                        entityType,
+                        operation: "update.removeEntries",
+                        cause: `field "${op.field}" is not configured as a sparse map`,
+                    });
+                }
+                const sparse = sparseFields[op.field];
+                for (const k of op.keys) {
+                    if (typeof k !== "string" || k.length === 0 || k.includes("#")) {
+                        return yield* new ValidationError({
+                            entityType,
+                            operation: "update.removeEntries",
+                            cause: `Sparse map "${op.field}": invalid key ${JSON.stringify(k)}`,
+                        });
+                    }
+                    const nameKey = `#sr${removeClauses.length}`;
+                    names[nameKey] = `${sparse.prefix}#${k}`;
+                    removeClauses.push(nameKey);
+                }
+            }
+        }
+        // Sparse-map .clearMap — Get-then-Update helper. Reads the current
+        // item with a consistent read to discover which `<prefix>#*` attrs
+        // exist, then folds the resulting REMOVEs into this same UpdateItem.
+        // The version CAS (when configured) provides atomicity; non-versioned
+        // entities are best-effort (a concurrent writer can add a new bucket
+        // between the read and the update — that bucket survives).
+        if (uState.sparseClearFields && uState.sparseClearFields.length > 0) {
+            for (const field of uState.sparseClearFields) {
+                if (!hasSparseFields || !(field in sparseFields)) {
+                    return yield* new ValidationError({
+                        entityType,
+                        operation: "update.clearMap",
+                        cause: `field "${field}" is not configured as a sparse map`,
+                    });
+                }
+            }
+            // Read once for all clearMap fields combined.
+            const clearGetResult = yield* client.getItem({
+                TableName: tableName,
+                Key: marshalledKey,
+                ConsistentRead: true,
+            });
+            if (clearGetResult.Item) {
+                const clearItemKeys = Object.keys(clearGetResult.Item);
+                for (const field of uState.sparseClearFields) {
+                    const sparse = sparseFields[field];
+                    const prefixWithDelim = `${sparse.prefix}#`;
+                    for (const attrName of clearItemKeys) {
+                        if (attrName.startsWith(prefixWithDelim)) {
+                            const nameKey = `#sc${removeClauses.length}`;
+                            names[nameKey] = attrName;
+                            removeClauses.push(nameKey);
+                        }
+                    }
+                }
+            }
+            // If the item doesn't exist, clearMap is a no-op — the subsequent
+            // UpdateItem will create the row (with whatever other clauses the
+            // builder accumulated) per DynamoDB UpdateItem semantics.
+        }
         const hasAnyUpdate = setClauses.length > 0 ||
             removeClauses.length > 0 ||
             addClauses.length > 0 ||
@@ -1518,13 +1856,16 @@ const makeImpl = (config) => {
             Object.assign(values, uc.values);
         }
         const conditionExpression = condParts.length > 0 ? condParts.join(" AND ") : undefined;
+        // 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({
             TableName: tableName,
             Key: marshalledKey,
             UpdateExpression: updateExpression,
             ExpressionAttributeNames: names,
-            ExpressionAttributeValues: values,
+            ExpressionAttributeValues: Object.keys(values).length > 0 ? values : undefined,
             ConditionExpression: conditionExpression,
             ReturnValues: returnValuesMap[uState.returnValues ?? "allNew"],
         })
@@ -1773,6 +2114,35 @@ const makeImpl = (config) => {
                 continue;
             if (val === undefined)
                 continue;
+            // Sparse fields: expand into one SET per bucket. Each bucket
+            // attribute is named `<prefix>#<key>` and goes through
+            // ExpressionAttributeNames as a literal (the `#` survives).
+            if (hasSparseFields && attr in sparseFields) {
+                if (val === null || typeof val !== "object")
+                    continue;
+                const sparse = sparseFields[attr];
+                for (const [k, v] of Object.entries(val)) {
+                    try {
+                        if (typeof k !== "string" || k.length === 0 || k.includes("#")) {
+                            throw new Error(`Sparse map "${attr}": invalid key ${JSON.stringify(k)}`);
+                        }
+                    }
+                    catch (e) {
+                        return yield* new ValidationError({
+                            entityType,
+                            operation: "upsert.sparse",
+                            cause: e instanceof Error ? e.message : String(e),
+                        });
+                    }
+                    const nameKey = `#u${counter}`;
+                    const valKey = `:u${counter}`;
+                    names[nameKey] = `${sparse.prefix}#${k}`;
+                    values[valKey] = toAttributeValue(v);
+                    setClauses.push(`${nameKey} = ${valKey}`);
+                    counter++;
+                }
+                continue;
+            }
             const nameKey = `#u${counter}`;
             const valKey = `:u${counter}`;
             names[nameKey] = resolveDbName(attr);
@@ -1876,6 +2246,47 @@ const makeImpl = (config) => {
         const raw = fromAttributeMap(result.Attributes);
         return yield* decodeAs(raw, result.Attributes, mode);
     }), self, input);
+    /**
+     * @internal Compare stored vs attempted `orderBy` to decide whether the CAS
+     * predicate `attribute_not_exists(pk) OR stored < attempted` failed.
+     *
+     * Returns `true` (CAS failed → stale) when `stored >= attempted`.
+     * Returns `false` (CAS held; the user's `.condition()` is the rejecter)
+     * when `stored < attempted` or when `stored` is missing.
+     *
+     * `stored` arrives as a decoded domain value matching the configured schema
+     * for the attribute: a `DateTime.Utc` for `Schema.DateTimeUtc`, a `Date` for
+     * `Schema.Date`, a `number`/`bigint` for numeric schemas, a `string` for
+     * lexicographic comparisons.
+     */
+    const isCasFailure = (stored, attempted) => {
+        if (stored == null)
+            return false;
+        // DateTime.Utc — compare epoch ms.
+        if (DateTime.isDateTime(stored) && DateTime.isDateTime(attempted)) {
+            return DateTime.toEpochMillis(stored) >= DateTime.toEpochMillis(attempted);
+        }
+        // Date — compare epoch ms.
+        if (stored instanceof Date && attempted instanceof Date) {
+            return stored.getTime() >= attempted.getTime();
+        }
+        // Numeric — number or bigint (cast comparable via JS coercion).
+        if (typeof stored === "number" && typeof attempted === "number") {
+            return stored >= attempted;
+        }
+        if (typeof stored === "bigint" && typeof attempted === "bigint") {
+            return stored >= attempted;
+        }
+        // Strings — lexicographic.
+        if (typeof stored === "string" && typeof attempted === "string") {
+            return stored >= attempted;
+        }
+        // Mixed / unknown shapes — fall back to string compare on String(...).
+        // Defensive: return true so we report StaleAppend (the safer default —
+        // never suppress a CAS rejection by mis-classifying it as a user-condition
+        // rejection).
+        return String(stored) >= String(attempted);
+    };
     // ---------------------------------------------------------------------------
     // append operation — time-series primitive (only when `timeSeries` configured)
     //
@@ -1886,13 +2297,25 @@ const makeImpl = (config) => {
     //  - Put of event: full decoded input + __edd_e__ + _ttl (if configured),
     //    GSI keys stripped, SK replaced with `<currentSk>#e#<orderByValue>`.
     //
-    // On TransactionCancelled or ConditionalCheckFailed, we issue a follow-up
-    // GetItem on the primary key and return `{ applied: false, reason: "stale",
-    // current }`. On success, same follow-up GetItem yields the post-append
-    // current. See `docs/designs/timeseries.md` §4.
+    // Concurrency outcome (stale-as-error contract — supersedes
+    // `docs/designs/timeseries.md` §4.7 v1 stale-as-value):
+    //
+    // - Success path (default): on transaction success, issue a follow-up
+    //   GetItem and return `{ current }` (decoded model).
+    // - Stale path (default): on TransactionCancelled, issue a follow-up
+    //   GetItem to disambiguate. If the stored `orderBy >= attempted`, the CAS
+    //   fired → fail with `StaleAppend(current: Option.some)`. Otherwise the
+    //   user-supplied `.condition()` rejected the write → fail with
+    //   `ConditionalCheckFailed(current: Option.some)`.
+    // - skipFollowUp success path: return `void`.
+    // - skipFollowUp stale path: cannot disambiguate (no GetItem), so fail
+    //   with `StaleAppend(current: Option.none)` for both cancellation modes.
+    //   Documented as a deliberate trade-off in `guides/timeseries.mdx`.
+    // - TTL-race / row vanished after success: surface as
+    //   `ValidationError("append.followUp")`. Undetected on skipFollowUp path.
     // ---------------------------------------------------------------------------
     const timeSeriesConfig = config.timeSeries;
-    const append = (input, userCondition) => Effect.gen(function* () {
+    const append = (input, userCondition, skipFollowUp = false) => Effect.gen(function* () {
         if (!timeSeriesConfig) {
             return yield* new ValidationError({
                 entityType,
@@ -1981,7 +2404,18 @@ const makeImpl = (config) => {
                 },
             };
         }
-        const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, policyAwareIndexes, nonPkAppendFields, encoded);
+        // The composer can throw CompositeKeyHoleError (EDD-9024) on a hole
+        // pattern. Surface it as a typed Effect failure.
+        let gsiUpdate;
+        try {
+            gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, policyAwareIndexes, nonPkAppendFields, encoded);
+        }
+        catch (e) {
+            if (e instanceof CompositeKeyHoleError) {
+                return yield* e;
+            }
+            throw e;
+        }
         for (const [field, value] of Object.entries(gsiUpdate.sets)) {
             const nameKey = `#a${counter}`;
             const valKey = `:a${counter}`;
@@ -2061,6 +2495,22 @@ const makeImpl = (config) => {
         for (const field of gsiKeyFields()) {
             delete eventItem[field];
         }
+        // Sparse-map fields are aggregate state, not event state. They live on
+        // the current item only — strip from event items entirely. (Same
+        // treatment as enrichment fields outside `appendInput`. By design,
+        // `appendInput` cannot include sparse fields, so this is defensive.)
+        if (hasSparseFields) {
+            for (const fieldName of Object.keys(sparseFields)) {
+                delete eventItem[fieldName];
+                // Also strip any flattened bucket attrs that might have leaked in
+                // via a future code change — defensive cleanup.
+                const prefixWithDelim = `${sparseFields[fieldName].prefix}#`;
+                for (const k of Object.keys(eventItem)) {
+                    if (k.startsWith(prefixWithDelim))
+                        delete eventItem[k];
+                }
+            }
+        }
         const marshalledEventItem = toAttributeMap(eventItem);
         // ---------- Execute TransactWriteItems ----------
         const transactResult = yield* client
@@ -2088,40 +2538,83 @@ const makeImpl = (config) => {
             onSuccess: () => Effect.succeed({ stale: false }),
             onFailure: (err) => {
                 // TransactionCancelled or ConditionalCheckFailed at the transaction
-                // level both map to "stale" (can't distinguish CAS from user-cond
-                // in v1 — see §12 decision 5).
+                // level both surface here. Disambiguation between CAS and
+                // user-condition happens after the follow-up GetItem (when run).
                 if (isAwsTransactionCancelled(err.cause) || isAwsConditionalCheckFailed(err.cause)) {
                     return Effect.succeed({ stale: true });
                 }
                 return Effect.fail(err);
             },
         }));
-        // Follow-up GetItem to read the current (post-append on success, winning
-        // state on stale). One read is required either way — the contract
-        // returns `Model` which demands the full row including enrichment.
+        // -----------------------------------------------------------------
+        // skipFollowUp branch — no GetItem, cannot decode current, cannot
+        // disambiguate CAS vs user-condition cancellation. Both modes
+        // collapse to StaleAppend(current: Option.none) — documented.
+        // -----------------------------------------------------------------
+        if (skipFollowUp) {
+            if (transactResult.stale) {
+                return yield* new StaleAppend({
+                    entityType,
+                    orderByField,
+                    attemptedOrderBy: newObValue,
+                    current: Option.none(),
+                });
+            }
+            return undefined;
+        }
+        // -----------------------------------------------------------------
+        // Default branch — one follow-up GetItem either way. Carries:
+        //   - Decoded model on success (the post-append current).
+        //   - Disambiguation data on cancellation (stored orderBy vs attempted)
+        //     plus a model snapshot to attach to the error for the caller.
+        // -----------------------------------------------------------------
         const followUp = yield* client.getItem({
             TableName: tableName,
             Key: marshalledKey,
         });
         if (!followUp.Item) {
-            // TTL race or out-of-band delete — surface as a DynamoClientError
-            // (the previous state vanished under us). This is NOT a stale result.
-            return yield* Effect.fail(new ValidationError({
+            // TTL race or out-of-band delete — the previous state vanished
+            // under us. Distinct from a CAS-stale outcome.
+            return yield* new ValidationError({
                 entityType,
                 operation: "append.followUp",
                 cause: "Current item not found after append — possible TTL race or concurrent delete.",
-            }));
+            });
         }
         const rawCurrent = fromAttributeMap(followUp.Item);
         const currentModel = yield* decodeAs(rawCurrent, followUp.Item, "model");
         if (transactResult.stale) {
-            return {
-                applied: false,
-                reason: "stale",
-                current: currentModel,
-            };
+            // Disambiguate CAS-stale from user-condition rejection. We compare
+            // in the WIRE form (what DynamoDB actually evaluated): `newObValue`
+            // is the encoded value passed to the CAS, and `rawCurrent` carries
+            // the encoded values read back. `decodeAs` mutated `rawCurrent` to
+            // rename DB columns to domain field names, so `rawCurrent[orderByField]`
+            // is the wire-form value under its domain name. Wire-form
+            // comparison matches DynamoDB's evaluation: ISO-8601 strings sort
+            // lexicographically (= chronologically), numbers/bigints are
+            // numeric, strings are lexicographic.
+            const storedOrderBy = rawCurrent[orderByField];
+            const attempted = newObValue;
+            const casFired = isCasFailure(storedOrderBy, attempted);
+            if (!casFired && userCondition !== undefined) {
+                // CAS held; the user's `.condition()` is the only thing that
+                // could have rejected.
+                return yield* new ConditionalCheckFailed({
+                    entityType,
+                    key: encoded,
+                    current: Option.some(currentModel),
+                });
+            }
+            // Either CAS fired, or no user condition was supplied (CAS is the
+            // only possibility) — both map to StaleAppend.
+            return yield* new StaleAppend({
+                entityType,
+                orderByField,
+                attemptedOrderBy: attempted,
+                current: Option.some(currentModel),
+            });
         }
-        return { applied: true, current: currentModel };
+        return { current: currentModel };
     });
     // ---------------------------------------------------------------------------
     // history operation — BoundQuery for event items only
@@ -2136,6 +2629,11 @@ const makeImpl = (config) => {
         const currentSk = KeyComposer.composeSk(schema, entityType, entityVersion, primary, decodedKey);
         const prefix = KeyComposer.composeEventSkPrefix(currentSk, schema.casing);
         const decodeHistory = (raw) => {
+            // Sparse fields are aggregate state, not event state — event items DO
+            // 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,
@@ -2280,6 +2778,11 @@ const makeImpl = (config) => {
         // (itemSchema would fail because it expects GSI key fields that aren't present)
         if (mode === "native")
             return result.Items[0];
+        // 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
+        // not).
+        deserializeSparseFields(raw);
         const targetSchema = schemas.deletedRecordSchema;
         return yield* Schema.decodeUnknownEffect(targetSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
             entityType,
@@ -2292,11 +2795,16 @@ const makeImpl = (config) => {
         const primary = config.indexes.primary;
         const pkValue = KeyComposer.composePk(schema, entityType, primary, decodedKey);
         const deletedPrefix = DynamoSchema.composeDeletedKeyPrefix(schema, entityType);
-        const decodeDeleted = (raw) => Schema.decodeUnknownEffect(schemas.deletedRecordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "deleted.list.decode",
-            cause,
-        })));
+        const decodeDeleted = (raw) => {
+            // Sparse fields are domain data and are preserved across soft-delete.
+            // Rebuild Records from flattened attrs before schema decode.
+            deserializeSparseFields(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: "",
             indexName: undefined,
@@ -2551,7 +3059,9 @@ const makeImpl = (config) => {
     // ---------------------------------------------------------------------------
     // Expression combinators: condition, filter, select
     // ---------------------------------------------------------------------------
-    const entityPathBuilder = createPathBuilder([], resolveDbName);
+    // Sparse-field map used by createPathBuilder to wire `.entry(key)` accessors.
+    const sparseFieldsForPath = hasSparseFields ? sparseFields : undefined;
+    const entityPathBuilder = createPathBuilder([], resolveDbName, sparseFieldsForPath);
     const entityConditionOps = createConditionOps();
     /**
      * Build a condition expression combinator from callback or shorthand.
@@ -2609,6 +3119,7 @@ const makeImpl = (config) => {
         _resolvedRefs: resolvedRefs,
         /** @internal Full decode pipeline: rename + schema decode. Used by Batch/Aggregate. */
         _decodeRecord: decodeRecord,
+        _serializeSparseFields: serializeSparseFields,
         _attachPrototype: attachPrototype,
         _configure: (injectedSchema, injectedTableTag) => {
             schema = injectedSchema;
@@ -2676,10 +3187,15 @@ const makeImpl = (config) => {
 export const bind = (entity) => Effect.gen(function* () {
     const ctx = yield* Effect.context();
     const provide = (effect) => Effect.provide(effect, ctx);
+    // Sparse-field map (if any) — extracted from the Entity's configured model
+    // so the PathBuilder used by `.condition((t, ops) => ...)` exposes
+    // `.entry(key)` accessors on sparse-map fields.
+    const boundSparseFields = getSparseFields(entity.model);
+    const boundSparseFieldsForPath = Object.keys(boundSparseFields).length > 0 ? boundSparseFields : undefined;
     // Shared config for the bound-CRUD builders — pre-resolved services plus
     // a typed PathBuilder/ConditionOps so `.condition((t, ops) => ...)` works.
     const boundCrudConfig = {
-        pathBuilder: createPathBuilder(),
+        pathBuilder: createPathBuilder(undefined, undefined, boundSparseFieldsForPath),
         conditionOps: createConditionOps(),
         provide,
     };
@@ -2723,7 +3239,13 @@ export const bind = (entity) => Effect.gen(function* () {
         },
         // Time-series (no-ops when entity is not configured; runtime check in
         // the entity-level `append` returns a ValidationError).
-        append: (input, condition) => provide(entity.append(input, condition)),
+        append: (input) => {
+            const appendCfg = {
+                ...boundCrudConfig,
+                run: (opts) => provide(entity.append(opts.input, opts.condition, opts.skipFollowUp)),
+            };
+            return makeBoundAppend(input, appendCfg);
+        },
         history: (key) => {
             const q = entity.history(key);
             const pathBuilder = createPathBuilder();