effect-dynamodb 1.3.3 → 1.5.0

package/dist/Entity.js

@@ -6,26 +6,26 @@
  * carries derived schemas for 7 type extractors (Model, Record, Input, Update,
  * Key, Item, Marshalled).
  */
-import { DateTime, Duration, Effect, Schema, Stream } from "effect";
+import { DateTime, Duration, Effect, Option, Schema, Stream } from "effect";
 import { DynamoClient } from "./DynamoClient.js";
-import { getEncoding, 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 { deserializeDateFromDynamo, fromAttributeMap, serializeDateForDynamo, 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, getFields, inferDefaultEncoding, primaryKeyComposites, resolveSystemFields, resolveUniqueFields, } from "./internal/EntitySchemas.js";
+import { allCompositeAttributes, allKeyFieldNames, buildDerivedSchemas, buildFieldEncodings, getFields, primaryKeyComposites, resolveSystemFields, resolveUniqueFields, validateNoTransformOverride, } from "./internal/EntitySchemas.js";
 // ---------------------------------------------------------------------------
 // Sparse-aware unique sentinel composition
 // ---------------------------------------------------------------------------
@@ -61,6 +61,40 @@ const composeUniqueSentinel = (schema, entityType, constraintName, constraintDef
     };
 };
 // ---------------------------------------------------------------------------
+// Encode-or-decode-encode helper
+// ---------------------------------------------------------------------------
+/**
+ * Validate user input and produce wire-form output, accepting both Type and
+ * Encoded shapes. Strategy:
+ *
+ *   1. Try `Schema.encode(input)`. This is the canonical Type → Encoded
+ *      conversion and works when the user passes Type values for transforms
+ *      (e.g. a `DateTime.Utc` for `Schema.DateTimeUtcFromString`, a `number`
+ *      for `Schema.NumberFromString`, a `Redacted<string>` for our
+ *      RedactedFromValue substitute).
+ *
+ *   2. On encode failure, fall back to `Schema.decode → Schema.encode`. This
+ *      lifts plain inputs to the Type shape first (`Schema.Class` decode is
+ *      forgiving — it constructs a class instance from a plain object), then
+ *      re-encodes back to wire form. Required for nested `Schema.Class`
+ *      fields whose Type is a class instance but whose Encoded is a plain
+ *      object — users typically construct the plain object directly.
+ *
+ * Returns the Encoded shape (a plain object whose values are wire
+ * primitives), ready for `toAttributeMap`.
+ *
+ * @internal
+ */
+const encodeOrDecodeEncode = (schema, input, entityType, operation) => Schema.encodeUnknownEffect(schema)(input).pipe(Effect.catch((primaryCause) => Schema.decodeUnknownEffect(schema)(input).pipe(Effect.flatMap((decoded) => Schema.encodeUnknownEffect(schema)(decoded)), 
+// On fallback failure, surface the original encode error — its
+// message is keyed on the caller's input shape, which is what the
+// user expects to see.
+Effect.catch(() => Effect.fail(new ValidationError({
+    entityType,
+    operation: `${operation}.decode`,
+    cause: primaryCause,
+}))))));
+// ---------------------------------------------------------------------------
 // Transaction limit pre-check (100-item DynamoDB limit)
 // ---------------------------------------------------------------------------
 /**
@@ -306,7 +340,15 @@ const makeImpl = (config) => {
     }
     // Resolve identifier field name from model annotation
     const resolvedIdentifier = getIdentifierField(config.model)?.name;
-    const schemas = buildDerivedSchemas(modelFields, allIndexes, systemFields, resolvedRefs, immutableFields, resolvedIdentifier, config.timeSeries);
+    // Validate: no model field combines a transform schema with a ConfiguredModel
+    // storage override. The two configuration paths are mutually exclusive.
+    validateNoTransformOverride(modelFields, configuredAttributes);
+    // Resolve effective field encodings (annotation + ConfiguredModel override).
+    // Used by buildDerivedSchemas to substitute self date schemas with bidirectional
+    // transforms, and (below) by system-field generation to produce the right
+    // wire primitive when the field is library-managed.
+    const fieldEncodings = buildFieldEncodings(modelFields, configuredAttributes);
+    const schemas = buildDerivedSchemas(modelFields, allIndexes, systemFields, resolvedRefs, immutableFields, resolvedIdentifier, config.timeSeries, fieldEncodings);
     // schema and tableTag are injected via _configure() when the entity is registered
     // on a Table and bound through DynamoClient.make(). They are captured by operation
     // closures and resolved at runtime (inside Effects), not at definition time.
@@ -315,37 +357,68 @@ const makeImpl = (config) => {
     let tableTag;
     const entityType = config.entityType;
     const entityVersion = 1;
+    // Note: `fieldEncodings` is resolved earlier (above buildDerivedSchemas) and
+    // used to substitute self date schemas in derived schemas. System timestamp
+    // encodings are NOT in `fieldEncodings`; `generateTimestamp` produces wire
+    // primitives directly for non-colliding system fields.
     // ---------------------------------------------------------------------------
-    // DynamoEncoding map: field name → encoding for date-annotated fields
-    // Merges schema annotations with ConfiguredModel storage overrides.
+    // Sparse Map fields (storedAs: 'sparse') — validation + resolution
     // ---------------------------------------------------------------------------
-    const fieldEncodings = {};
-    for (const [fieldName, fieldSchema] of Object.entries(modelFields)) {
-        const encoding = getEncoding(fieldSchema);
-        if (encoding) {
-            fieldEncodings[fieldName] = encoding;
+    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.`);
+            }
         }
-        else {
-            // Auto-detect standard Effect date schemas (Pattern B: pure model)
-            const inferred = inferDefaultEncoding(fieldSchema);
-            if (inferred)
-                fieldEncodings[fieldName] = inferred;
+        // 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.`);
+            }
         }
-    }
-    // Apply ConfiguredModel storage overrides (takes precedence over schema annotations)
-    for (const [fieldName, attrConfig] of Object.entries(configuredAttributes)) {
-        if (attrConfig.encoding) {
-            const existing = fieldEncodings[fieldName];
-            fieldEncodings[fieldName] = {
-                storage: attrConfig.encoding.storage,
-                domain: existing?.domain ?? attrConfig.encoding.domain,
-            };
+        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}".`);
+            }
         }
     }
-    // Note: System timestamp encodings are NOT added to fieldEncodings.
-    // generateTimestamp() handles serialization directly for timestamps.
-    // This avoids double-serialization in serializeDateFields.
-    const hasDateFields = Object.keys(fieldEncodings).length > 0;
     // ---------------------------------------------------------------------------
     // Field renaming: domain name → DynamoDB attribute name (from ConfiguredModel)
     // ---------------------------------------------------------------------------
@@ -386,30 +459,27 @@ const makeImpl = (config) => {
     /** Resolve a domain field name to its DynamoDB attribute name. */
     const resolveDbName = (domainName) => fieldRenames[domainName] ?? domainName;
     /**
-     * Convert domain date values to storage primitives for DynamoEncoding-annotated fields.
-     * Called before toAttributeMap (put path).
+     * 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 serializeDateFields = (item) => {
-        if (!hasDateFields)
+    const serializeSparseFields = (item) => {
+        if (!hasSparseFields)
             return;
-        for (const [field, encoding] of Object.entries(fieldEncodings)) {
-            if (field in item && item[field] != null) {
-                item[field] = serializeDateForDynamo(item[field], encoding);
-            }
-        }
+        encodeSparseFields(item, sparseFields);
     };
     /**
-     * Convert storage primitives back to domain values for DynamoEncoding-annotated fields.
-     * Called after fromAttributeMap (get path).
+     * 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 deserializeDateFields = (raw) => {
-        if (!hasDateFields)
+    const deserializeSparseFields = (raw) => {
+        if (!hasSparseFields)
             return;
-        for (const [field, encoding] of Object.entries(fieldEncodings)) {
-            if (field in raw && raw[field] != null) {
-                raw[field] = deserializeDateFromDynamo(raw[field], encoding);
-            }
-        }
+        decodeSparseFields(raw, sparseFields);
     };
     // ---------------------------------------------------------------------------
     // Helpers
@@ -425,8 +495,8 @@ 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);
-        deserializeDateFields(raw);
         return Schema.decodeUnknownEffect(schemas.recordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
             entityType,
             operation: "decode",
@@ -437,15 +507,15 @@ const makeImpl = (config) => {
     const decodeAs = (raw, marshalled, mode) => {
         if (mode === "native")
             return Effect.succeed(marshalled);
-        // Rename DynamoDB attributes back to domain field names
+        // 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);
-        // Convert date storage primitives to domain values before Schema decode.
-        // recordSchema/itemSchema use fromSelf variants for annotated fields,
-        // so they accept domain values directly. modelSchema also uses fromSelf
-        // for the decode path after deserialization.
-        deserializeDateFields(raw);
         const targetSchema = mode === "model"
-            ? schemas.modelDecodeSchema
+            ? schemas.modelSchema
             : mode === "record"
                 ? schemas.recordSchema
                 : schemas.itemSchema;
@@ -461,33 +531,26 @@ const makeImpl = (config) => {
     };
     const nowIso = () => new Date().toISOString();
     /**
-     * Generate a timestamp value appropriate for the field's encoding.
+     * Generate a timestamp value as a wire primitive ready for marshalling.
      * Default (no encoding): ISO string. Custom encoding: serialized primitive.
      *
-     * Used for non-colliding system fields (field not declared in model) — the
-     * value is written straight into the DynamoDB item and is NOT routed through
-     * `serializeDateFields` (because the field is absent from `fieldEncodings`).
+     * Used for system fields whether colliding or not — the value is always a
+     * wire primitive (string or number) ready for `toAttributeMap`.
      */
     const generateTimestamp = (encoding) => {
         if (!encoding)
             return nowIso();
-        const now = new Date();
-        return serializeDateForDynamo(now, encoding);
-    };
-    /**
-     * Generate a timestamp as a domain value (DateTime.Utc / DateTime.Zoned / Date),
-     * matching the field's declared domain. Used for system fields that COLLIDE
-     * with a model-declared field — the value flows through `serializeDateFields`
-     * (which requires a domain value) alongside any user-supplied override.
-     */
-    const generateDomainTimestamp = (encoding) => {
-        switch (encoding.domain) {
-            case "DateTime.Utc":
-                return DateTime.makeUnsafe(new Date());
-            case "DateTime.Zoned":
-                return DateTime.makeZonedUnsafe(new Date(), { timeZone: "UTC" });
-            case "Date":
-                return new Date();
+        const now = Date.now();
+        switch (encoding.storage) {
+            case "string":
+                // For DateTime.Zoned this would need the extended ISO format, but
+                // system timestamps generated here are UTC — DateTime.Zoned-typed
+                // collision fields are rare and not previously special-cased either.
+                return new Date(now).toISOString();
+            case "epochMs":
+                return now;
+            case "epochSeconds":
+                return Math.floor(now / 1000);
         }
     };
     // ---------------------------------------------------------------------------
@@ -777,41 +840,41 @@ const makeImpl = (config) => {
     const put = (input) => new EntityPutImpl((mode, opts) => Effect.gen(function* () {
         const client = yield* DynamoClient;
         const { name: tableName } = yield* tableTag;
-        // Decode input
-        const decodedInput = yield* Schema.decodeUnknownEffect(schemas.inputDecodeSchema)(input).pipe(Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "put.decode",
-            cause,
-        })));
-        // Compose all keys BEFORE ref hydration (ID fields are still present)
-        const keys = composeAllKeys(decodedInput);
+        // Encode user input → wire form. Users typically construct domain
+        // values for transforms (DateTime, Redacted, Number) and plain
+        // objects for Schema.Class fields. To handle both:
+        //   1. Try `encode` directly — the canonical Type → Encoded
+        //      conversion. Works when the input is fully Type-shaped
+        //      (which is the case for the transforms that issue #29
+        //      surfaced: RedactedFromValue, NumberFromString, etc.).
+        //   2. On failure, fall back to `decode → encode` — `decode` is
+        //      forgiving for Schema.Class (lifts plain objects to
+        //      instances) and the substituted date/Redacted transforms
+        //      tolerate either form. The subsequent `encode` produces
+        //      the canonical wire shape.
+        const encodedInput = yield* encodeOrDecodeEncode(schemas.inputSchema, input, entityType, "put");
+        // Compose all keys from the encoded input (ID fields still present
+        // and key composites are wire-format strings/numbers).
+        const keys = composeAllKeys(encodedInput);
         // Hydrate refs: replace ID fields with full entity domain data
-        const decoded = hasRefs
-            ? yield* hydrateRefs(decodedInput)
-            : decodedInput;
-        // Build the DynamoDB item
-        const item = { ...decoded };
+        const encoded = hasRefs
+            ? yield* hydrateRefs(encodedInput)
+            : encodedInput;
+        // Build the DynamoDB item — already in wire-format after encode
+        const item = { ...encoded };
         // Add system fields. When a timestamp field collides with a
         // model-declared field, the user may have supplied their own value
-        // (see `inputDecodeSchema` — optional on collision). Respect their
-        // value if present; otherwise generate. In the collision path the
-        // value is a DOMAIN value (DateTime.Utc / Date / ...) so it flows
-        // through `serializeDateFields` downstream. Non-colliding fields
-        // get a storage primitive directly (no `serializeDateFields` pass).
+        // (optional on collision in `inputSchema`). Respect their value if
+        // present (already encoded to wire); otherwise generate a wire
+        // primitive directly.
         if (systemFields.createdAt) {
             if (item[systemFields.createdAt] === undefined) {
-                item[systemFields.createdAt] =
-                    systemFields.createdAtCollision && systemFields.createdAtEncoding
-                        ? generateDomainTimestamp(systemFields.createdAtEncoding)
-                        : generateTimestamp(systemFields.createdAtEncoding);
+                item[systemFields.createdAt] = generateTimestamp(systemFields.createdAtEncoding);
             }
         }
         if (systemFields.updatedAt) {
             if (item[systemFields.updatedAt] === undefined) {
-                item[systemFields.updatedAt] =
-                    systemFields.updatedAtCollision && systemFields.updatedAtEncoding
-                        ? generateDomainTimestamp(systemFields.updatedAtEncoding)
-                        : generateTimestamp(systemFields.updatedAtEncoding);
+                item[systemFields.updatedAt] = generateTimestamp(systemFields.updatedAtEncoding);
             }
         }
         if (systemFields.version)
@@ -820,10 +883,20 @@ const makeImpl = (config) => {
         item.__edd_e__ = entityType;
         // Apply composed keys
         Object.assign(item, keys);
-        // Convert date fields from domain values to storage primitives
-        serializeDateFields(item);
         // 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
@@ -851,7 +924,7 @@ const makeImpl = (config) => {
             const sentinelConstraints = [];
             if (hasUniqueConstraints) {
                 for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                    const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, decoded);
+                    const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, encoded);
                     if (!sentinel)
                         continue;
                     sentinelConstraints.push(constraintName);
@@ -894,7 +967,7 @@ const makeImpl = (config) => {
                         if (opts.condition && reasons[0]?.Code === "ConditionalCheckFailed") {
                             return new ConditionalCheckFailed({
                                 entityType,
-                                key: decoded,
+                                key: encoded,
                             });
                         }
                         // Sentinel items start at index 1, in the order recorded in
@@ -908,7 +981,7 @@ const makeImpl = (config) => {
                                     : [];
                                 const fieldsRecord = {};
                                 for (const f of uniqueFields) {
-                                    const v = decoded[f];
+                                    const v = encoded[f];
                                     if (v !== undefined && v !== null) {
                                         fieldsRecord[f] = KeyComposer.serializeValue(v);
                                     }
@@ -940,7 +1013,10 @@ const makeImpl = (config) => {
             }
             yield* client.putItem(putInput).pipe(Effect.mapError((err) => {
                 if (opts.condition && isAwsConditionalCheckFailed(err.cause)) {
-                    return new ConditionalCheckFailed({ entityType, key: decoded });
+                    return new ConditionalCheckFailed({
+                        entityType,
+                        key: encoded,
+                    });
                 }
                 return err;
             }));
@@ -1025,17 +1101,13 @@ const makeImpl = (config) => {
             operation: "update.decodeKey",
             cause,
         })));
-        // Decode updates
-        const decodedUpdates = yield* Schema.decodeUnknownEffect(schemas.updateDecodeSchema)(updates ?? {}).pipe(Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "update.decodeUpdates",
-            cause,
-        })));
+        // Encode update payload → wire form (see `put` for the strategy).
+        const encodedUpdates = yield* encodeOrDecodeEncode(schemas.updateSchema, updates ?? {}, entityType, "update");
         // Hydrate refs in updates: for any ${field}Id present, fetch and embed
-        let hydratedUpdates = decodedUpdates;
+        let hydratedUpdates = encodedUpdates;
         if (hasRefs) {
-            const refsToHydrate = resolvedRefs.filter((ref) => ref.idFieldName in decodedUpdates &&
-                decodedUpdates[ref.idFieldName] !==
+            const refsToHydrate = resolvedRefs.filter((ref) => ref.idFieldName in encodedUpdates &&
+                encodedUpdates[ref.idFieldName] !==
                     undefined);
             if (refsToHydrate.length > 0) {
                 hydratedUpdates = yield* hydrateRefs(hydratedUpdates, refsToHydrate);
@@ -1083,26 +1155,37 @@ const makeImpl = (config) => {
                 });
             }
             // Build new item: merge current + updates + rich ops + recompose keys.
-            //
-            // Pre-serialize domain date values from `hydratedUpdates` (decoded
-            // via `fromSelf`, so DateTime.Utc / Date instances) into storage
-            // primitives BEFORE merging into `newItem`. `currentRaw` is already
-            // storage-primitive (it came straight from `fromAttributeMap`), so
-            // we need both halves in the same shape — otherwise the final
-            // `toAttributeMap(newItem)` marshals the DateTime class instances
-            // as DynamoDB Maps (via AWS SDK's `convertClassInstanceToMap`),
-            // which corrupts the write and makes subsequent reads fail to
-            // decode.
-            const serializedRetainUpdates = {
-                ...hydratedUpdates,
-            };
-            serializeDateFields(serializedRetainUpdates);
-            const newItem = {
+            // `currentRaw` uses DynamoDB attribute names (e.g. `dn`, `hd`);
+            // `hydratedUpdates` uses domain names. To avoid the merge leaving
+            // both names (which would later have the rename clobber the user's
+            // value), translate the current item's keys to domain names first
+            // so the spread + assign overlay cleanly.
+            const currentDomainItem = {
                 ...currentRaw,
             };
-            for (const [attr, val] of Object.entries(serializedRetainUpdates)) {
-                if (val !== undefined)
+            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)
+                    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) {
@@ -1110,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;
@@ -1138,24 +1244,21 @@ const makeImpl = (config) => {
             }
             // Increment version and update timestamp. If the caller supplied a
             // value for `updatedAt` (allowed when the field collides with a
-            // model-declared field), respect it; else generate. Read from the
-            // pre-serialized map so both branches produce a storage primitive
-            // (ISO string / epoch number) — not a domain DateTime instance.
+            // model-declared field), respect it (already wire-form via encode);
+            // else generate a fresh wire primitive.
             const newVersion = currentVersion + 1;
             if (systemFields.version)
                 newItem[systemFields.version] = newVersion;
             if (systemFields.updatedAt) {
-                const userSupplied = serializedRetainUpdates[systemFields.updatedAt];
+                const userSupplied = hydratedUpdates[systemFields.updatedAt];
                 newItem[systemFields.updatedAt] =
                     userSupplied !== undefined
                         ? userSupplied
                         : generateTimestamp(systemFields.updatedAtEncoding);
             }
-            // Convert DynamoDB attribute names to domain names for key composition
-            // and sentinel value comparison (newItem was built from currentRaw which
-            // uses DynamoDB names; composites and unique fields use domain names)
-            renameFromDynamo(newItem);
-            // Recompose all keys with updated attributes
+            // `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);
             const sentinelRotations = [];
@@ -1182,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()
@@ -1320,22 +1434,46 @@ const makeImpl = (config) => {
         const names = {};
         const values = {};
         let counter = 0;
-        // Serialize any domain-value date fields in updates to storage primitives.
-        // Without this, a `.set({ occurredAt: DateTime.Utc })` would marshal as a
-        // class-instance map.
-        const serializedUpdates = { ...hydratedUpdates };
-        serializeDateFields(serializedUpdates);
+        // `hydratedUpdates` was produced by `Schema.encode(updateSchema)` and
+        // is already in wire-format (ISO string / epoch number / etc.). Use
+        // it directly — no `serializeDateFields` pass required.
+        const encodedUpdatesMap = hydratedUpdates;
         // System-colliding updatedAt is handled by the system-field block below.
-        // createdAt and version are already excluded by `updateDecodeSchema`.
+        // createdAt and version are already excluded by `updateSchema`.
         const updateSystemColliders = new Set();
         if (systemFields.updatedAtCollision && systemFields.updatedAt)
             updateSystemColliders.add(systemFields.updatedAt);
         // Add user-provided updates
-        for (const [attr, val] of Object.entries(serializedUpdates)) {
+        for (const [attr, val] of Object.entries(encodedUpdatesMap)) {
             if (val === undefined)
                 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);
@@ -1343,10 +1481,11 @@ const makeImpl = (config) => {
             setClauses.push(`${nameKey} = ${valKey}`);
             counter++;
         }
-        // Add updatedAt timestamp. User-supplied value wins (pre-serialized
-        // above); else fall back to a freshly generated storage primitive.
+        // Add updatedAt timestamp. User-supplied value wins (already in wire
+        // form via encode); else fall back to a freshly generated wire
+        // primitive.
         if (systemFields.updatedAt) {
-            const userSupplied = serializedUpdates[systemFields.updatedAt];
+            const userSupplied = encodedUpdatesMap[systemFields.updatedAt];
             const nameKey = `#u${counter}`;
             const valKey = `:u${counter}`;
             names[nameKey] = systemFields.updatedAt;
@@ -1521,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 ||
@@ -1554,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"],
         })
@@ -1774,17 +1983,13 @@ const makeImpl = (config) => {
     const upsert = (input) => new EntityPutImpl((mode, opts) => Effect.gen(function* () {
         const client = yield* DynamoClient;
         const { name: tableName } = yield* tableTag;
-        // Decode input
-        const decodedInput = yield* Schema.decodeUnknownEffect(schemas.inputDecodeSchema)(input).pipe(Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "upsert.decode",
-            cause,
-        })));
+        // Encode user input → wire form (see `put` for strategy).
+        const encodedInput = yield* encodeOrDecodeEncode(schemas.inputSchema, input, entityType, "upsert");
         // Hydrate refs: replace ID fields with full entity domain data
-        const decoded = hasRefs
-            ? yield* hydrateRefs(decodedInput)
-            : decodedInput;
-        const item = decoded;
+        const encoded = hasRefs
+            ? yield* hydrateRefs(encodedInput)
+            : encodedInput;
+        const item = encoded;
         // Compose primary key
         const primaryKey = composePrimaryKey(item);
         const marshalledKey = toAttributeMap(primaryKey);
@@ -1804,10 +2009,7 @@ const makeImpl = (config) => {
             systemColliders.add(systemFields.updatedAt);
         if (systemFields.versionCollision && systemFields.version)
             systemColliders.add(systemFields.version);
-        // Serialize date fields on the decoded item
-        if (hasDateFields) {
-            serializeDateFields(item);
-        }
+        // `item` is already in wire-form via `Schema.encode(inputSchema)`.
         // All model fields (excluding PK composites, which are in the Key)
         for (const [attr, val] of Object.entries(item)) {
             if (pkComposites.has(attr))
@@ -1816,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);
@@ -1919,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)
     //
@@ -1929,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,
@@ -1948,26 +2232,19 @@ const makeImpl = (config) => {
         const orderByField = timeSeriesConfig.orderBy;
         const ttlDuration = timeSeriesConfig.ttl;
         const appendInputSchema = schemas.appendInputSchema;
-        // Decode input via appendInputSchema
-        const decodedInput = yield* Schema.decodeUnknownEffect(appendInputSchema)(input).pipe(Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "append.decode",
-            cause,
-        })));
-        const decoded = decodedInput;
-        // Compose current-item primary key (pk + sk derived from PK/SK composites in decoded)
+        // Encode user input via appendInputSchema (see `put` for strategy).
+        const encodedInput = yield* encodeOrDecodeEncode(appendInputSchema, input, entityType, "append");
+        const encoded = encodedInput;
+        // Compose current-item primary key (pk + sk derived from PK/SK composites)
         const primary = config.indexes.primary;
-        const pkValue = KeyComposer.composePk(schema, entityType, primary, decoded);
-        const currentSk = KeyComposer.composeSk(schema, entityType, entityVersion, primary, decoded);
+        const pkValue = KeyComposer.composePk(schema, entityType, primary, encoded);
+        const currentSk = KeyComposer.composeSk(schema, entityType, entityVersion, primary, encoded);
         const marshalledKey = toAttributeMap({
             [primary.pk.field]: pkValue,
             [primary.sk.field]: currentSk,
         });
-        // Prepare domain-serialised values for the item build.
-        // Build a shallow copy and apply date serialization (per fieldEncodings)
-        // before marshalling. This mirrors the put path.
-        const serialisedInput = { ...decoded };
-        serializeDateFields(serialisedInput);
+        // `encoded` is already in wire-form via Schema.encode — used directly.
+        const serialisedInput = { ...encoded };
         // ---------- Build UpdateItem (scoped SET + CAS) ----------
         const setClauses = [];
         const names = {};
@@ -1996,7 +2273,7 @@ const makeImpl = (config) => {
         // never change during an append. Non-PK composites in appendInput that
         // overlap a GSI's composites trigger per-GSI resolution via indexPolicy.
         const nonPkAppendFields = {};
-        for (const [attr, val] of Object.entries(decoded)) {
+        for (const [attr, val] of Object.entries(encoded)) {
             if (!pkCompositeSet.has(attr)) {
                 nonPkAppendFields[attr] = val;
             }
@@ -2031,7 +2308,7 @@ const makeImpl = (config) => {
                 },
             };
         }
-        const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, policyAwareIndexes, nonPkAppendFields, decoded);
+        const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, policyAwareIndexes, nonPkAppendFields, encoded);
         for (const [field, value] of Object.entries(gsiUpdate.sets)) {
             const nameKey = `#a${counter}`;
             const valKey = `:a${counter}`;
@@ -2091,9 +2368,9 @@ const makeImpl = (config) => {
         const updateExpression = exprParts.join(" ");
         // ---------- Build Put of event item ----------
         const eventSk = KeyComposer.composeEventSk(currentSk, newObValue, schema.casing);
-        const eventItem = { ...decoded };
-        // Serialise date fields to storage format for the Put
-        serializeDateFields(eventItem);
+        // `encoded` is already in wire-form via Schema.encode; no extra
+        // serialisation step is required for the Put.
+        const eventItem = { ...encoded };
         // Rename domain → DB names for the Put (matches put path)
         renameToDynamo(eventItem);
         // pk + sk (event)
@@ -2111,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
@@ -2138,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
@@ -2186,8 +2522,12 @@ 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);
-            deserializeDateFields(raw);
             return Schema.decodeUnknownEffect(schemas.historyRecordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
                 entityType,
                 operation: "history.decode",
@@ -2331,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,
@@ -2343,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,
@@ -2602,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.
@@ -2658,9 +3010,9 @@ const makeImpl = (config) => {
         identifier: resolvedIdentifier,
         timeSeries: config.timeSeries,
         _resolvedRefs: resolvedRefs,
-        /** @internal Full decode pipeline: rename + date deser + schema decode. Used by Batch/Aggregate. */
+        /** @internal Full decode pipeline: rename + schema decode. Used by Batch/Aggregate. */
         _decodeRecord: decodeRecord,
-        _serializeDateFields: serializeDateFields,
+        _serializeSparseFields: serializeSparseFields,
         _attachPrototype: attachPrototype,
         _configure: (injectedSchema, injectedTableTag) => {
             schema = injectedSchema;
@@ -2728,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,
     };
@@ -2775,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();