effect-dynamodb 1.4.0 → 1.5.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, 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,28 @@ 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.
             for (const [attr, val] of Object.entries(hydratedUpdates)) {
-                if (val !== undefined)
+                if (val === undefined)
+                    continue;
+                if (hasSparseFields &&
+                    attr in sparseFields &&
+                    val !== null &&
+                    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 +1193,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;
@@ -1146,6 +1285,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()
@@ -1299,6 +1449,31 @@ const makeImpl = (config) => {
                 continue;
             if (updateSystemColliders.has(attr))
                 continue;
+            // Sparse fields: emit one SET per bucket. Whole-bucket replace
+            // semantics — concurrent writers to disjoint buckets are safe.
+            // `null` is NOT REMOVE — that's footgunny; explicit removal goes
+            // through `.removeEntries(field, keys)`.
+            if (hasSparseFields && attr in sparseFields) {
+                if (val === null || 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);
@@ -1485,6 +1660,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 +1760,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 +2018,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 +2150,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 +2201,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,
@@ -2061,6 +2388,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 +2431,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 +2522,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 +2671,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 +2688,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 +2952,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 +3012,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 +3080,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 +3132,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();