effect-dynamodb 1.3.3 → 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,7 @@ 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
 // ---------------------------------------------------------------------------
@@ -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,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)
     // ---------------------------------------------------------------------------
@@ -385,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
     // ---------------------------------------------------------------------------
@@ -426,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",
@@ -437,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;
@@ -461,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);
         }
     };
     // ---------------------------------------------------------------------------
@@ -777,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)
@@ -820,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);
@@ -851,7 +826,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 +869,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 +883,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 +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;
             }));
@@ -1025,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);
@@ -1083,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;
             }
@@ -1138,24 +1105,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 = [];
@@ -1320,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))
@@ -1343,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;
@@ -1774,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);
@@ -1804,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))
@@ -1948,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 = {};
@@ -1996,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;
             }
@@ -2031,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}`;
@@ -2091,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)
@@ -2187,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",
@@ -2658,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;