effect-dynamodb 1.3.2 → 1.4.0

package/dist/Entity.js

@@ -6,9 +6,9 @@
  * carries derived schemas for 7 type extractors (Model, Record, Input, Update,
  * Key, Item, Marshalled).
  */
-import { DateTime, Duration, Effect, Schema, Stream } from "effect";
+import { Duration, Effect, Schema, Stream } from "effect";
 import { DynamoClient } from "./DynamoClient.js";
-import { getEncoding, getIdentifierField, isConfiguredModel, isHidden, isRef, isRefField, } from "./DynamoModel.js";
+import { getIdentifierField, isConfiguredModel, isHidden, 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";
@@ -17,7 +17,7 @@ import { compileExpr, createConditionOps, isExpr, parseShorthand, parseSimpleSho
 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 { 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";
@@ -25,7 +25,75 @@ import { EntityDeleteImpl, EntityDeleteTypeId, EntityGetImpl, EntityOpTypeId, En
 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";
 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
+// ---------------------------------------------------------------------------
+/**
+ * Compose a unique-constraint sentinel key, returning `undefined` when any
+ * composing field is missing (`undefined` or `null`) on the source record.
+ *
+ * Mirrors GSI sparse semantics (`tryComposeIndexKeys`): a sentinel is only
+ * written/deleted/checked when every composing field is present, so multiple
+ * records can coexist with the field unset and an entity write doesn't synthesize
+ * a literal `"undefined"` collision key.
+ *
+ * `lookup` overrides the field-value reader. The update path passes a lookup that
+ * falls back from the domain field name to the renamed DB column name, since
+ * `currentRaw` (read from DynamoDB) carries DB names rather than domain names.
+ */
+const composeUniqueSentinel = (schema, entityType, constraintName, constraintDef, source, lookup) => {
+    const fields = resolveUniqueFields(constraintDef);
+    const get = lookup ?? ((s, f) => s[f]);
+    const serialized = [];
+    const fieldsRecord = {};
+    for (const f of fields) {
+        const raw = get(source, f);
+        if (raw === undefined || raw === null)
+            return undefined;
+        const s = KeyComposer.serializeValue(raw);
+        serialized.push(s);
+        fieldsRecord[f] = s;
+    }
+    return {
+        key: DynamoSchema.composeUniqueKey(schema, entityType, constraintName, serialized),
+        fieldsRecord,
+    };
+};
+// ---------------------------------------------------------------------------
+// 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)
 // ---------------------------------------------------------------------------
@@ -272,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.
@@ -281,37 +357,10 @@ const makeImpl = (config) => {
     let tableTag;
     const entityType = config.entityType;
     const entityVersion = 1;
-    // ---------------------------------------------------------------------------
-    // DynamoEncoding map: field name → encoding for date-annotated fields
-    // Merges schema annotations with ConfiguredModel storage overrides.
-    // ---------------------------------------------------------------------------
-    const fieldEncodings = {};
-    for (const [fieldName, fieldSchema] of Object.entries(modelFields)) {
-        const encoding = getEncoding(fieldSchema);
-        if (encoding) {
-            fieldEncodings[fieldName] = encoding;
-        }
-        else {
-            // Auto-detect standard Effect date schemas (Pattern B: pure model)
-            const inferred = inferDefaultEncoding(fieldSchema);
-            if (inferred)
-                fieldEncodings[fieldName] = inferred;
-        }
-    }
-    // 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,
-            };
-        }
-    }
-    // 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;
+    // 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.
     // ---------------------------------------------------------------------------
     // Field renaming: domain name → DynamoDB attribute name (from ConfiguredModel)
     // ---------------------------------------------------------------------------
@@ -351,32 +400,6 @@ 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).
-     */
-    const serializeDateFields = (item) => {
-        if (!hasDateFields)
-            return;
-        for (const [field, encoding] of Object.entries(fieldEncodings)) {
-            if (field in item && item[field] != null) {
-                item[field] = serializeDateForDynamo(item[field], encoding);
-            }
-        }
-    };
-    /**
-     * Convert storage primitives back to domain values for DynamoEncoding-annotated fields.
-     * Called after fromAttributeMap (get path).
-     */
-    const deserializeDateFields = (raw) => {
-        if (!hasDateFields)
-            return;
-        for (const [field, encoding] of Object.entries(fieldEncodings)) {
-            if (field in raw && raw[field] != null) {
-                raw[field] = deserializeDateFromDynamo(raw[field], encoding);
-            }
-        }
-    };
     // ---------------------------------------------------------------------------
     // Helpers
     // ---------------------------------------------------------------------------
@@ -392,7 +415,6 @@ const makeImpl = (config) => {
     const attachPrototype = (decoded) => isSchemaClass ? Object.assign(Object.create(rawModel.prototype), decoded) : decoded;
     const decodeRecord = (raw) => {
         renameFromDynamo(raw);
-        deserializeDateFields(raw);
         return Schema.decodeUnknownEffect(schemas.recordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
             entityType,
             operation: "decode",
@@ -403,15 +425,11 @@ const makeImpl = (config) => {
     const decodeAs = (raw, marshalled, mode) => {
         if (mode === "native")
             return Effect.succeed(marshalled);
-        // Rename DynamoDB attributes back to domain field names
+        // 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;
@@ -427,33 +445,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);
         }
     };
     // ---------------------------------------------------------------------------
@@ -743,41 +754,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)
@@ -786,8 +797,6 @@ 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);
         const marshalledItem = toAttributeMap(item);
@@ -813,18 +822,20 @@ const makeImpl = (config) => {
                 }
             }
             transactItems.push({ Put: mainPut });
-            // Unique constraint sentinels
+            // Unique constraint sentinels (sparse — skip when any composing field is missing)
+            const sentinelConstraints = [];
             if (hasUniqueConstraints) {
                 for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                    const fields = resolveUniqueFields(constraintDef);
-                    const fieldValues = fields.map((f) => KeyComposer.serializeValue(decoded[f]));
-                    const uniqueKey = DynamoSchema.composeUniqueKey(schema, entityType, constraintName, fieldValues);
+                    const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, encoded);
+                    if (!sentinel)
+                        continue;
+                    sentinelConstraints.push(constraintName);
                     transactItems.push({
                         Put: {
                             TableName: tableName,
                             Item: toAttributeMap({
-                                [config.indexes.primary.pk.field]: uniqueKey.pk,
-                                [config.indexes.primary.sk.field]: uniqueKey.sk,
+                                [config.indexes.primary.pk.field]: sentinel.key.pk,
+                                [config.indexes.primary.sk.field]: sentinel.key.sk,
                                 __edd_e__: `${entityType}._unique.${constraintName}`,
                                 _entity_pk: keys[config.indexes.primary.pk.field],
                                 _entity_sk: keys[config.indexes.primary.sk.field],
@@ -858,21 +869,24 @@ const makeImpl = (config) => {
                         if (opts.condition && reasons[0]?.Code === "ConditionalCheckFailed") {
                             return new ConditionalCheckFailed({
                                 entityType,
-                                key: decoded,
+                                key: encoded,
                             });
                         }
-                        // Sentinel items start at index 1
+                        // Sentinel items start at index 1, in the order recorded in
+                        // `sentinelConstraints` (skipped sparse entries are absent)
                         for (let i = 1; i < reasons.length; i++) {
                             if (reasons[i]?.Code === "ConditionalCheckFailed") {
-                                const constraintNames = Object.keys(config.unique);
-                                const constraintName = constraintNames[i - 1] ?? "unknown";
-                                const constraintDef = config.unique[constraintName];
+                                const constraintName = sentinelConstraints[i - 1] ?? "unknown";
+                                const constraintDef = config.unique?.[constraintName];
                                 const uniqueFields = constraintDef
                                     ? resolveUniqueFields(constraintDef)
                                     : [];
                                 const fieldsRecord = {};
                                 for (const f of uniqueFields) {
-                                    fieldsRecord[f] = KeyComposer.serializeValue(decoded[f]);
+                                    const v = encoded[f];
+                                    if (v !== undefined && v !== null) {
+                                        fieldsRecord[f] = KeyComposer.serializeValue(v);
+                                    }
                                 }
                                 return new UniqueConstraintViolation({
                                     entityType,
@@ -901,7 +915,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;
             }));
@@ -986,17 +1003,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);
@@ -1044,24 +1057,17 @@ 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)) {
+            renameFromDynamo(currentDomainItem);
+            const newItem = { ...currentDomainItem };
+            for (const [attr, val] of Object.entries(hydratedUpdates)) {
                 if (val !== undefined)
                     newItem[attr] = val;
             }
@@ -1099,45 +1105,42 @@ 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 = [];
             if (touchesUniqueFields) {
                 const currentRawRecord = currentRaw;
                 for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                    const fields = resolveUniqueFields(constraintDef);
-                    const oldFieldValues = fields.map((f) => KeyComposer.serializeValue(currentRawRecord[f] ?? currentRawRecord[resolveDbName(f)]));
-                    const newFieldValues = fields.map((f) => KeyComposer.serializeValue(newItem[f]));
-                    const changed = oldFieldValues.some((v, i) => v !== newFieldValues[i]);
-                    if (!changed)
+                    const oldSentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, currentRawRecord, (s, f) => s[f] ?? s[resolveDbName(f)]);
+                    const newSentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, newItem);
+                    if (!oldSentinel && !newSentinel)
+                        continue;
+                    if (oldSentinel &&
+                        newSentinel &&
+                        oldSentinel.key.pk === newSentinel.key.pk &&
+                        oldSentinel.key.sk === newSentinel.key.sk) {
                         continue;
-                    const newFieldsRecord = {};
-                    for (const f of fields) {
-                        newFieldsRecord[f] = KeyComposer.serializeValue(newItem[f]);
                     }
                     sentinelRotations.push({
                         constraintName,
-                        oldUniqueKey: DynamoSchema.composeUniqueKey(schema, entityType, constraintName, oldFieldValues),
-                        newUniqueKey: DynamoSchema.composeUniqueKey(schema, entityType, constraintName, newFieldValues),
-                        newFieldsRecord,
+                        oldUniqueKey: oldSentinel?.key,
+                        newUniqueKey: newSentinel?.key,
+                        newFieldsRecord: newSentinel?.fieldsRecord,
                     });
                 }
             }
@@ -1185,38 +1188,42 @@ const makeImpl = (config) => {
                     },
                 });
             }
-            // Apply sentinel rotations computed earlier
+            // Apply sentinel rotations computed earlier. Delete and Put are emitted
+            // independently — a sparse field that becomes set emits Put only; a sparse
+            // field that becomes unset emits Delete only.
             const sentinelPutIndices = [];
             for (const rotation of sentinelRotations) {
-                // Delete old sentinel
-                transactItems.push({
-                    Delete: {
-                        TableName: tableName,
-                        Key: toAttributeMap({
-                            [config.indexes.primary.pk.field]: rotation.oldUniqueKey.pk,
-                            [config.indexes.primary.sk.field]: rotation.oldUniqueKey.sk,
-                        }),
-                    },
-                });
-                // Put new sentinel with uniqueness check
-                sentinelPutIndices.push({
-                    index: transactItems.length,
-                    constraintName: rotation.constraintName,
-                    newFieldsRecord: rotation.newFieldsRecord,
-                });
-                transactItems.push({
-                    Put: {
-                        TableName: tableName,
-                        Item: toAttributeMap({
-                            [config.indexes.primary.pk.field]: rotation.newUniqueKey.pk,
-                            [config.indexes.primary.sk.field]: rotation.newUniqueKey.sk,
-                            __edd_e__: `${entityType}._unique.${rotation.constraintName}`,
-                            _entity_pk: primaryKey[config.indexes.primary.pk.field],
-                            _entity_sk: primaryKey[config.indexes.primary.sk.field],
-                        }),
-                        ConditionExpression: "attribute_not_exists(pk)",
-                    },
-                });
+                if (rotation.oldUniqueKey) {
+                    transactItems.push({
+                        Delete: {
+                            TableName: tableName,
+                            Key: toAttributeMap({
+                                [config.indexes.primary.pk.field]: rotation.oldUniqueKey.pk,
+                                [config.indexes.primary.sk.field]: rotation.oldUniqueKey.sk,
+                            }),
+                        },
+                    });
+                }
+                if (rotation.newUniqueKey && rotation.newFieldsRecord) {
+                    sentinelPutIndices.push({
+                        index: transactItems.length,
+                        constraintName: rotation.constraintName,
+                        newFieldsRecord: rotation.newFieldsRecord,
+                    });
+                    transactItems.push({
+                        Put: {
+                            TableName: tableName,
+                            Item: toAttributeMap({
+                                [config.indexes.primary.pk.field]: rotation.newUniqueKey.pk,
+                                [config.indexes.primary.sk.field]: rotation.newUniqueKey.sk,
+                                __edd_e__: `${entityType}._unique.${rotation.constraintName}`,
+                                _entity_pk: primaryKey[config.indexes.primary.pk.field],
+                                _entity_sk: primaryKey[config.indexes.primary.sk.field],
+                            }),
+                            ConditionExpression: "attribute_not_exists(pk)",
+                        },
+                    });
+                }
             }
             yield* checkTransactionLimit(entityType, "update", transactItems);
             yield* client
@@ -1277,18 +1284,17 @@ 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))
@@ -1300,10 +1306,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;
@@ -1630,18 +1637,19 @@ const makeImpl = (config) => {
                     },
                 });
             }
-            // Delete sentinels if not preserving unique
+            // Delete sentinels if not preserving unique. Sparse — fields that were
+            // unset on the live item never had a sentinel, so nothing to delete.
             if (hasUniqueConstraints && !preserveUnique()) {
                 for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                    const fields = resolveUniqueFields(constraintDef);
-                    const fieldValues = fields.map((f) => KeyComposer.serializeValue(raw[f]));
-                    const uniqueKey = DynamoSchema.composeUniqueKey(schema, entityType, constraintName, fieldValues);
+                    const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, raw);
+                    if (!sentinel)
+                        continue;
                     transactItems.push({
                         Delete: {
                             TableName: tableName,
                             Key: toAttributeMap({
-                                [primary.pk.field]: uniqueKey.pk,
-                                [primary.sk.field]: uniqueKey.sk,
+                                [primary.pk.field]: sentinel.key.pk,
+                                [primary.sk.field]: sentinel.key.sk,
                             }),
                         },
                     });
@@ -1668,17 +1676,18 @@ const makeImpl = (config) => {
             transactItems.push({
                 Delete: { TableName: tableName, Key: marshalledKey },
             });
-            // Delete sentinels
+            // Delete sentinels (sparse — skip constraints whose fields were unset
+            // on the live item; no sentinel was ever written for those)
             for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                const fields = resolveUniqueFields(constraintDef);
-                const fieldValues = fields.map((f) => KeyComposer.serializeValue(raw[f]));
-                const uniqueKey = DynamoSchema.composeUniqueKey(schema, entityType, constraintName, fieldValues);
+                const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, raw);
+                if (!sentinel)
+                    continue;
                 transactItems.push({
                     Delete: {
                         TableName: tableName,
                         Key: toAttributeMap({
-                            [primary.pk.field]: uniqueKey.pk,
-                            [primary.sk.field]: uniqueKey.sk,
+                            [primary.pk.field]: sentinel.key.pk,
+                            [primary.sk.field]: sentinel.key.sk,
                         }),
                     },
                 });
@@ -1729,17 +1738,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);
@@ -1759,10 +1764,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))
@@ -1903,26 +1905,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 = {};
@@ -1951,7 +1946,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;
             }
@@ -1986,7 +1981,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}`;
@@ -2046,9 +2041,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)
@@ -2142,7 +2137,6 @@ const makeImpl = (config) => {
         const prefix = KeyComposer.composeEventSkPrefix(currentSk, schema.casing);
         const decodeHistory = (raw) => {
             renameFromDynamo(raw);
-            deserializeDateFields(raw);
             return Schema.decodeUnknownEffect(schemas.historyRecordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
                 entityType,
                 operation: "history.decode",
@@ -2393,18 +2387,21 @@ const makeImpl = (config) => {
                 },
             });
         }
-        // Re-establish unique constraint sentinels
+        // Re-establish unique constraint sentinels (sparse — fields that are
+        // unset on the restored item don't get a sentinel; matches put semantics)
+        const sentinelConstraints = [];
         if (config.unique && Object.keys(config.unique).length > 0) {
             for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                const fields = resolveUniqueFields(constraintDef);
-                const fieldValues = fields.map((f) => KeyComposer.serializeValue(restoredItem[f]));
-                const uniqueKey = DynamoSchema.composeUniqueKey(schema, entityType, constraintName, fieldValues);
+                const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, restoredItem);
+                if (!sentinel)
+                    continue;
+                sentinelConstraints.push(constraintName);
                 transactItems.push({
                     Put: {
                         TableName: tableName,
                         Item: toAttributeMap({
-                            [primary.pk.field]: uniqueKey.pk,
-                            [primary.sk.field]: uniqueKey.sk,
+                            [primary.pk.field]: sentinel.key.pk,
+                            [primary.sk.field]: sentinel.key.sk,
                             __edd_e__: `${entityType}._unique.${constraintName}`,
                             _entity_pk: restoredKeys[primary.pk.field],
                             _entity_sk: restoredKeys[primary.sk.field],
@@ -2424,17 +2421,20 @@ const makeImpl = (config) => {
             if (isAwsTransactionCancelled(err.cause)) {
                 const reasons = err.cause.CancellationReasons;
                 if (reasons && config.unique) {
-                    // Sentinel items are after Delete + Put + optional snapshot
+                    // Sentinel Puts come after Delete + Put + optional snapshot, in the
+                    // order recorded in `sentinelConstraints` (sparse-skipped entries absent)
                     const sentinelStart = isRetainEnabled() ? 3 : 2;
-                    const constraintNames = Object.keys(config.unique);
                     for (let i = sentinelStart; i < reasons.length; i++) {
                         if (reasons[i]?.Code === "ConditionalCheckFailed") {
-                            const constraintName = constraintNames[i - sentinelStart] ?? "unknown";
+                            const constraintName = sentinelConstraints[i - sentinelStart] ?? "unknown";
                             const constraintDef = config.unique[constraintName];
                             const uniqueFields = constraintDef ? resolveUniqueFields(constraintDef) : [];
                             const fieldsRecord = {};
                             for (const f of uniqueFields) {
-                                fieldsRecord[f] = KeyComposer.serializeValue(restoredItem[f]);
+                                const v = restoredItem[f];
+                                if (v !== undefined && v !== null) {
+                                    fieldsRecord[f] = KeyComposer.serializeValue(v);
+                                }
                             }
                             return new UniqueConstraintViolation({
                                 entityType,
@@ -2518,14 +2518,15 @@ const makeImpl = (config) => {
                 }
             }
             if (entityItem) {
-                // Add sentinel keys to delete list
+                // Add sentinel keys to delete list (sparse — fields that were unset
+                // never had a sentinel written, so nothing to enqueue)
                 for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                    const fields = resolveUniqueFields(constraintDef);
-                    const fieldValues = fields.map((f) => KeyComposer.serializeValue(entityItem[f]));
-                    const uniqueKey = DynamoSchema.composeUniqueKey(schema, entityType, constraintName, fieldValues);
+                    const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, entityItem);
+                    if (!sentinel)
+                        continue;
                     allItems.push(toAttributeMap({
-                        [primary.pk.field]: uniqueKey.pk,
-                        [primary.sk.field]: uniqueKey.sk,
+                        [primary.pk.field]: sentinel.key.pk,
+                        [primary.sk.field]: sentinel.key.sk,
                     }));
                 }
             }
@@ -2606,9 +2607,8 @@ 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,
         _attachPrototype: attachPrototype,
         _configure: (injectedSchema, injectedTableTag) => {
             schema = injectedSchema;