effect-dynamodb 1.3.2 → 1.4.0

package/dist/internal/EntitySchemas.js

@@ -3,7 +3,7 @@
  *
  * Extracted from Entity.ts for decomposition. Not part of the public API.
  */
-import { Schema, SchemaAST } from "effect";
+import { DateTime, Effect, Option, Redacted, Schema, SchemaAST, SchemaGetter, SchemaIssue, } from "effect";
 import { getEncoding, isHidden } from "../DynamoModel.js";
 /**
  * Resolve the effective DynamoEncoding for a model-declared field, applying
@@ -213,62 +213,382 @@ export const inferDefaultEncoding = (schema) => {
         return { storage: "string", domain: "Date" };
     return undefined;
 };
+// ---------------------------------------------------------------------------
+// Self vs. transform schema detection
+// ---------------------------------------------------------------------------
+/**
+ * Returns true when the schema is a "self" schema — i.e. it carries no
+ * encoding transformation. Self schemas have `ast.encoding === undefined`.
+ *
+ * - `Schema.DateTimeUtc` — self
+ * - `Schema.DateTimeUtcFromString` — transform (encodes to string)
+ * - `Schema.RedactedFromValue(...)` — transform
+ * - any `.pipe(Schema.decodeTo(...))` chain — transform
+ */
+export const isSelfSchema = (schema) => schema.ast.encoding === undefined;
+/**
+ * True if the schema is a self DateTime/Date schema that can have its storage
+ * configured via a DynamoEncoding annotation. Distinguished from a transform
+ * by `ast.encoding === undefined`.
+ */
+export const isSelfDateSchema = (schema) => {
+    if (!isSelfSchema(schema))
+        return false;
+    // The self-schema check is necessary but not sufficient — also confirm the
+    // type constructor matches one of the supported date domains.
+    return inferDefaultEncoding(schema) !== undefined;
+};
+/**
+ * Returns true when the schema is a transform schema with a date typeConstructor
+ * (e.g. `Schema.DateTimeUtcFromString`, `DynamoModel.DateEpochSeconds`).
+ * Used to enforce the "transform owns the wire format" policy at Entity.make().
+ */
+export const isDateTransform = (schema) => {
+    if (isSelfSchema(schema))
+        return false;
+    return inferDefaultEncoding(schema) !== undefined;
+};
+// ---------------------------------------------------------------------------
+// Self-date schema substitution
+// ---------------------------------------------------------------------------
 /**
- * Map a DynamoEncoding domain type to its "from self" Schema.
- * Used in record/item schemas so Schema.decode accepts domain values
- * directly (after deserializeDateFields has converted storage→domain).
+ * Convert any input value (string / number / DateTime / Date) to the wire
+ * primitive for a given encoding. Used by date substitutes' `encode` path.
+ *
+ * Wire format precisely matches the legacy `serializeDateForDynamo` output:
+ * - `string` storage → ISO 8601 string (UTC for DateTime.Utc / Date; extended
+ *   format for DateTime.Zoned)
+ * - `epochMs` storage → integer milliseconds since the Unix epoch
+ * - `epochSeconds` storage → integer seconds since the Unix epoch (TTL format)
  */
-const dateFromSelfSchema = (encoding) => {
-    switch (encoding.domain) {
-        case "DateTime.Utc":
-            return Schema.DateTimeUtc;
-        case "DateTime.Zoned":
-            return Schema.DateTimeZoned;
-        case "Date":
-            return Schema.DateValid;
+const toWirePrimitive = (value, encoding) => {
+    let epochMs;
+    let zoned;
+    if (DateTime.isDateTime(value)) {
+        if (DateTime.isZoned(value))
+            zoned = value;
+        epochMs = DateTime.toEpochMillis(value);
+    }
+    else if (value instanceof Date) {
+        epochMs = value.getTime();
+    }
+    else if (typeof value === "string") {
+        epochMs = new Date(value).getTime();
+    }
+    else if (typeof value === "number") {
+        // Numeric inputs are interpreted in the encoding's storage scale already.
+        if (encoding.storage === "epochSeconds")
+            epochMs = value * 1000;
+        else
+            epochMs = value;
+    }
+    else {
+        throw new Error(`[effect-dynamodb] toWirePrimitive: unsupported input ${typeof value} for ${encoding.domain}/${encoding.storage}`);
+    }
+    switch (encoding.storage) {
+        case "string":
+            if (encoding.domain === "DateTime.Zoned" && zoned)
+                return DateTime.formatIsoZoned(zoned);
+            return new Date(epochMs).toISOString();
+        case "epochMs":
+            return epochMs;
+        case "epochSeconds":
+            return Math.floor(epochMs / 1000);
     }
 };
-export const buildDerivedSchemas = (modelFields, indexes, systemFields, resolvedRefs = [], immutableFields = new Set(), identifierField = undefined, timeSeries = undefined) => {
-    // --- Build fromSelf field map for date fields ---
-    // These replace transform schemas with their "from self" variants so
-    // Schema.decode accepts domain values after storage→domain conversion.
-    // Checks both explicit DynamoEncoding annotations AND inferred defaults
-    // from standard Effect date schemas (Pattern B: pure model).
-    const fromSelfFields = {};
-    for (const [fieldName, fieldSchema] of Object.entries(modelFields)) {
-        const encoding = getEncoding(fieldSchema) ?? inferDefaultEncoding(fieldSchema);
-        if (encoding) {
-            fromSelfFields[fieldName] = dateFromSelfSchema(encoding);
+/**
+ * Build a bidirectional Schema for a given DynamoEncoding.
+ *
+ * The encoded side is `Schema.Any` so `decode` tolerates either:
+ * - the wire primitive (string / number) — the storage-shape input, OR
+ * - a domain value (`DateTime.Utc`, `Date`, etc.) — what users typically pass
+ *   into `entity.put({...})` and `.set({...})`.
+ *
+ * The `decode` direction always lifts to the domain type (DateTime.Utc /
+ * DateTime.Zoned / Date). The `encode` direction always produces the wire
+ * primitive. This makes both `Schema.encode(substituted)` and
+ * `Schema.decode(substituted)` work end-to-end regardless of whether the
+ * caller passed wire-form or domain-form.
+ *
+ * @internal
+ */
+export const buildDateTransform = (encoding) => {
+    const targetSchema = (() => {
+        switch (encoding.domain) {
+            case "DateTime.Utc":
+                return Schema.DateTimeUtc;
+            case "DateTime.Zoned":
+                return Schema.DateTimeZoned;
+            case "Date":
+                return Schema.DateValid;
+        }
+    })();
+    const liftToDomain = (value) => {
+        if (DateTime.isDateTime(value))
+            return value;
+        if (value instanceof Date) {
+            switch (encoding.domain) {
+                case "DateTime.Utc":
+                    return DateTime.makeUnsafe(value);
+                case "DateTime.Zoned":
+                    return DateTime.makeZonedUnsafe(value, { timeZone: "UTC" });
+                case "Date":
+                    return value;
+            }
+        }
+        if (typeof value === "string") {
+            switch (encoding.domain) {
+                case "DateTime.Utc":
+                    return DateTime.makeUnsafe(value);
+                case "DateTime.Zoned": {
+                    const match = value.match(/^(.+)\[(.+)\]$/);
+                    if (match) {
+                        const utc = DateTime.makeUnsafe(match[1]);
+                        return DateTime.makeZonedUnsafe(utc, { timeZone: match[2] });
+                    }
+                    const utc = DateTime.makeUnsafe(value);
+                    return DateTime.makeZonedUnsafe(utc, { timeZone: "UTC" });
+                }
+                case "Date":
+                    return new Date(value);
+            }
+        }
+        if (typeof value === "number") {
+            const ms = encoding.storage === "epochSeconds" ? value * 1000 : value;
+            switch (encoding.domain) {
+                case "DateTime.Utc":
+                    return DateTime.makeUnsafe(ms);
+                case "DateTime.Zoned":
+                    return DateTime.makeZonedUnsafe(new Date(ms), { timeZone: "UTC" });
+                case "Date":
+                    return new Date(ms);
+            }
+        }
+        return value;
+    };
+    return Schema.Any.pipe(Schema.decodeTo(targetSchema, {
+        decode: SchemaGetter.transformOrFail((value) => {
+            try {
+                return Effect.succeed(liftToDomain(value));
+            }
+            catch {
+                return Effect.fail(new SchemaIssue.InvalidType(Schema.Any.ast, Option.some(value)));
+            }
+        }),
+        encode: SchemaGetter.transformOrFail((value) => {
+            try {
+                return Effect.succeed(toWirePrimitive(value, encoding));
+            }
+            catch {
+                return Effect.fail(new SchemaIssue.InvalidType(Schema.Any.ast, Option.some(value)));
+            }
+        }),
+    }));
+};
+/**
+ * Detects `Schema.RedactedFromValue(inner)` fields (and `Schema.Redacted`).
+ * The encoded form of these schemas is "Forbidden" by Effect v4 design —
+ * encoding bails out to prevent accidental leaks. To make the round-trip work
+ * for our use case (write to DynamoDB, read back with Redacted on the domain
+ * side), we substitute with a custom transform that explicitly extracts the
+ * inner value via `Redacted.value` on encode and rewraps via `Redacted.make`
+ * on decode.
+ *
+ * Returns the inner schema (the wire-format schema) when the field is a
+ * Redacted-typed schema, otherwise undefined.
+ */
+const tryGetRedactedInner = (schema) => {
+    const resolved = SchemaAST.resolve(schema.ast);
+    if (resolved?.typeConstructor?._tag !== "effect/Redacted")
+        return undefined;
+    // The decoded type is `Redacted<T>` where the inner schema is at
+    // `ast.typeParameters[0]`. Walk the AST and rebuild the Schema via
+    // `Schema.make` so we get a fully-functional Schema (with `.pipe`).
+    const ast = schema.ast;
+    const params = ast.typeParameters;
+    if (!params || params.length === 0)
+        return undefined;
+    const innerAst = params[0];
+    return Schema.make(innerAst);
+};
+/**
+ * Build a substitute Schema for a `Schema.RedactedFromValue(inner)` field.
+ *
+ * The substitute round-trips: produces `Redacted<T>` on the domain side and
+ * the inner wire primitive on the encoded side. Both directions tolerate
+ * either form on input — a user passing a plain inner value is wrapped via
+ * `Redacted.make`; a user passing a `Redacted<T>` instance is unwrapped on
+ * encode via `Redacted.value`. This permissive shape lets the put/update
+ * paths handle the mixed wire/domain payloads users typically construct
+ * (e.g. `.put({ secret: Redacted.make(...) })`).
+ *
+ * The encoded side is `Schema.Any` so decode tolerates either form; the
+ * branch logic in `decode`/`encode` then steers the value to the right
+ * representation.
+ */
+const buildRedactedSubstitute = (inner) => {
+    return Schema.Any.pipe(Schema.decodeTo(Schema.Redacted(inner), {
+        decode: SchemaGetter.transform((value) => Redacted.isRedacted(value) ? value : Redacted.make(value)),
+        encode: SchemaGetter.transform((r) => Redacted.isRedacted(r) ? Redacted.value(r) : r),
+    }));
+};
+/**
+ * Substitute model fields with bidirectional transforms where needed:
+ *
+ *  - Self date schemas with an effective encoding (annotation or override)
+ *    → tolerant date transform that accepts either wire form (string/number)
+ *    or domain form (DateTime / Date) on decode, and always produces the
+ *    configured wire primitive on encode.
+ *  - `Schema.RedactedFromValue(inner)` fields → tolerant Redacted transform
+ *    that accepts either form on decode and unwraps to wire primitive on
+ *    encode (Effect v4's `RedactedFromValue` forbids encoding by default;
+ *    our substitution makes the round-trip work for storage).
+ *
+ * Existing transform schemas (other than `RedactedFromValue`) are passed
+ * through unchanged — the user-declared transform IS the wire format.
+ *
+ * Schema.Class fields (and Schema.Class fields nested inside Schema.Array,
+ * Schema.optional, etc.) are NOT substituted here. Instead, callers run
+ * `decode → encode` against the substituted schema: `Schema.decode` is
+ * forgiving for Schema.Class (lifts plain objects to instances), and the
+ * tolerant date / Redacted substitutes make the decode pass accept both
+ * wire and domain values. The subsequent `Schema.encode` produces the
+ * canonical wire shape.
+ *
+ * @internal
+ */
+export const substituteSchemas = (modelFields, fieldEncodings) => {
+    const out = {};
+    for (const [name, schema] of Object.entries(modelFields)) {
+        // 1. Self-date substitution. Pattern A: user declared `Schema.DateTimeUtc`
+        //    and chose a wire format via annotation. We substitute with the
+        //    tolerant date transform so the encode pipeline produces the right
+        //    wire primitive.
+        if (isSelfDateSchema(schema)) {
+            const enc = fieldEncodings[name];
+            if (enc) {
+                out[name] = buildDateTransform(enc);
+                continue;
+            }
+        }
+        // 2. RedactedFromValue substitution. Effect v4's `RedactedFromValue`
+        //    forbids encoding by design; substitute with a tolerant Redacted
+        //    transform so the round-trip works for storage.
+        const redactedInner = tryGetRedactedInner(schema);
+        if (redactedInner !== undefined) {
+            out[name] = buildRedactedSubstitute(redactedInner);
+            continue;
         }
+        // Default: pass through unchanged. Pattern B transforms (DynamoModel.*,
+        // Schema.DateTimeUtcFromString, Schema.NumberFromString, …) own their
+        // wire format directly — `Schema.encode` handles the conversion.
+        out[name] = schema;
     }
-    // --- Model Schema: pure model fields (accepts wire format for input decode) ---
-    const modelSchema = Schema.Struct(modelFields);
-    // --- Model Decode Schema: model fields with fromSelf for date-annotated fields ---
-    // Used in decodeAs after deserializeDateFields has converted storage→domain.
-    const modelDecodeSchema = Object.keys(fromSelfFields).length > 0
-        ? Schema.Struct({ ...modelFields, ...fromSelfFields })
-        : modelSchema;
+    return out;
+};
+/**
+ * Validate that no model field combines a transform schema with a storage
+ * override. The two configuration paths are mutually exclusive: either declare
+ * a self schema (`Schema.DateTimeUtc`) and let the annotation drive storage,
+ * OR declare a transform and own the wire format yourself — not both.
+ *
+ * Two override sources are checked:
+ *
+ *  1. `ConfiguredModel.storedAs` (configured attributes) — surfaces the
+ *     override via `configuredAttributes[name].encoding`.
+ *
+ *  2. `DynamoModel.storedAs(...)` modifier piped onto the field schema —
+ *     adds a `DynamoEncoding` annotation directly to the AST. We detect this
+ *     by checking whether the field-level annotation disagrees with the
+ *     transform's actual wire format (the `inferDefaultEncoding` of the
+ *     transform). For an unmodified transform (e.g. `DynamoModel.DateString`
+ *     with a matching ISO-string annotation), the two agree and the field is
+ *     accepted.
+ *
+ * Throws at `Entity.make()` time if the conflict is detected.
+ *
+ * @internal
+ */
+export const validateNoTransformOverride = (modelFields, configuredAttributes) => {
+    const conflictMessage = (name) => `[effect-dynamodb] Field "${name}": cannot apply DynamoEncoding storage override to a transform schema. ` +
+        `Either declare a self schema (Schema.DateTimeUtc) and let the annotation drive storage, OR declare a transform and own the wire format — not both.`;
+    for (const [name, schema] of Object.entries(modelFields)) {
+        if (!isDateTransform(schema))
+            continue;
+        // 1. ConfiguredModel.storedAs override?
+        const configOverride = configuredAttributes[name]?.encoding;
+        if (configOverride !== undefined) {
+            throw new Error(conflictMessage(name));
+        }
+        // 2. DynamoModel.storedAs() modifier on the schema itself? The modifier
+        //    applies a `DynamoEncoding` annotation to the AST. Detect a conflict
+        //    by comparing the annotation's storage with the transform's actual
+        //    wire format (read from `ast.encoding[last].to._tag`). Granularity:
+        //    we can distinguish "string" vs "number" wire forms; we cannot
+        //    distinguish epochMs vs epochSeconds at this layer. The string-vs-
+        //    number mismatch covers the most common breaking case.
+        const annotated = getEncoding(schema);
+        if (annotated === undefined)
+            continue;
+        const transformWire = transformWireKind(schema);
+        if (transformWire === undefined)
+            continue;
+        const annotatedKind = annotated.storage === "string" ? "string" : "number";
+        if (transformWire !== annotatedKind) {
+            throw new Error(conflictMessage(name));
+        }
+    }
+};
+/**
+ * Read the wire form ("string" or "number") that a transform schema actually
+ * encodes to, by walking the encoding chain. Returns undefined when the chain
+ * is missing or the leaf isn't a String / Number node.
+ */
+const transformWireKind = (schema) => {
+    const enc = schema.ast.encoding;
+    if (!enc || enc.length === 0)
+        return undefined;
+    const leaf = enc[enc.length - 1];
+    if (!leaf)
+        return undefined;
+    const tag = leaf.to._tag;
+    if (tag === "String")
+        return "string";
+    if (tag === "Number")
+        return "number";
+    return undefined;
+};
+export const buildDerivedSchemas = (modelFields, indexes, systemFields, resolvedRefs = [], immutableFields = new Set(), identifierField = undefined, timeSeries = undefined, fieldEncodings = {}) => {
+    // --- Substitute model fields ---
+    // Self date schemas (with effective encoding) are replaced with bidirectional
+    // transforms that produce the configured wire primitive. RedactedFromValue
+    // fields are replaced with a custom bidirectional transform so encoding
+    // round-trips. All other transform schemas are passed through — the user's
+    // transform IS the wire format and we never override it.
+    const fields = substituteSchemas(modelFields, fieldEncodings);
+    // --- Model Schema: pure model fields (for input decode/encode) ---
+    const modelSchema = Schema.Struct(fields);
     // --- Record Schema: model + system fields ---
-    // For date-annotated fields, use "from self" schemas (accept domain values directly)
+    // System timestamp fields use Schema.DateTimeUtcFromString as the canonical
+    // wire ↔ domain transform when they're library-managed. When the field
+    // collides with a model-declared field, the model's substituted schema is
+    // already in `fields` and we don't add a system-schema entry.
     const systemSchemaFields = {};
-    if (systemFields.createdAt) {
-        // Custom encoding → use fromSelf (deserializeDateFields handles storage→domain)
-        // Default → use DateTimeUtcFromString (ISO string → DateTime.Utc)
+    if (systemFields.createdAt && !systemFields.createdAtCollision) {
         systemSchemaFields[systemFields.createdAt] = systemFields.createdAtEncoding
-            ? Schema.DateTimeUtc
+            ? buildDateTransform(systemFields.createdAtEncoding)
             : Schema.DateTimeUtcFromString;
     }
-    if (systemFields.updatedAt) {
+    if (systemFields.updatedAt && !systemFields.updatedAtCollision) {
         systemSchemaFields[systemFields.updatedAt] = systemFields.updatedAtEncoding
-            ? Schema.DateTimeUtc
+            ? buildDateTransform(systemFields.updatedAtEncoding)
             : Schema.DateTimeUtcFromString;
     }
-    if (systemFields.version) {
+    if (systemFields.version && !systemFields.versionCollision) {
         systemSchemaFields[systemFields.version] = Schema.Number;
     }
     const recordSchema = Schema.Struct({
-        ...modelFields,
-        ...fromSelfFields,
+        ...fields,
         ...systemSchemaFields,
     });
     // --- System-collision handling for input/update schemas ---
@@ -300,13 +620,12 @@ export const buildDerivedSchemas = (modelFields, indexes, systemFields, resolved
     };
     // --- Input Schema: ref-aware (swap ref fields for ID fields when refs present) ---
     const refFieldSet = new Set(resolvedRefs.map((r) => r.fieldName));
-    const buildInputFieldsAcc = (dateVariant) => {
+    const buildInputFieldsAcc = () => {
         const acc = {};
-        for (const [key, field] of Object.entries(modelFields)) {
+        for (const [key, field] of Object.entries(fields)) {
             if (refFieldSet.has(key))
                 continue;
-            const base = dateVariant === "fromSelf" && fromSelfFields[key] ? fromSelfFields[key] : field;
-            const adjusted = applySystemCollisionAdjustments(key, base, "input");
+            const adjusted = applySystemCollisionAdjustments(key, field, "input");
             if (adjusted !== null)
                 acc[key] = adjusted;
         }
@@ -315,13 +634,12 @@ export const buildDerivedSchemas = (modelFields, indexes, systemFields, resolved
         }
         return acc;
     };
-    const inputSchema = Schema.Struct(buildInputFieldsAcc("transform"));
-    const inputDecodeSchema = Schema.Struct(buildInputFieldsAcc("fromSelf"));
+    const inputSchema = Schema.Struct(buildInputFieldsAcc());
     // --- Create Schema: input fields minus identifier (or PK composites as fallback) ---
     const pkComposites = new Set(primaryKeyComposites(indexes));
     const createOmitFields = identifierField ? new Set([identifierField]) : pkComposites;
     const createFieldsAcc = {};
-    for (const [key, field] of Object.entries(modelFields)) {
+    for (const [key, field] of Object.entries(fields)) {
         if (createOmitFields.has(key))
             continue; // skip identifier/PK composites (auto-generated)
         if (refFieldSet.has(key))
@@ -338,9 +656,9 @@ export const buildDerivedSchemas = (modelFields, indexes, systemFields, resolved
     }
     const createSchema = Schema.Struct(createFieldsAcc);
     // --- Update Schema: optional model fields minus key composites & immutable ---
-    const buildUpdateFieldsAcc = (dateVariant) => {
+    const buildUpdateFieldsAcc = () => {
         const acc = {};
-        for (const [key, field] of Object.entries(modelFields)) {
+        for (const [key, field] of Object.entries(fields)) {
             if (pkComposites.has(key))
                 continue;
             if (immutableFields.has(key))
@@ -349,8 +667,7 @@ export const buildDerivedSchemas = (modelFields, indexes, systemFields, resolved
                 continue;
             if (strippedFromUpdate.has(key))
                 continue;
-            const base = dateVariant === "fromSelf" && fromSelfFields[key] ? fromSelfFields[key] : field;
-            acc[key] = Schema.optional(base);
+            acc[key] = Schema.optional(field);
         }
         for (const ref of resolvedRefs) {
             if (pkComposites.has(ref.fieldName))
@@ -361,13 +678,12 @@ export const buildDerivedSchemas = (modelFields, indexes, systemFields, resolved
         }
         return acc;
     };
-    const updateSchema = Schema.Struct(buildUpdateFieldsAcc("transform"));
-    const updateDecodeSchema = Schema.Struct(buildUpdateFieldsAcc("fromSelf"));
+    const updateSchema = Schema.Struct(buildUpdateFieldsAcc());
     // --- Key Schema: primary key composite attributes only ---
     const keyCompositeNames = primaryKeyComposites(indexes);
     const keyFields = {};
     for (const name of keyCompositeNames) {
-        const field = modelFields[name];
+        const field = fields[name];
         if (field)
             keyFields[name] = field;
     }
@@ -391,16 +707,14 @@ export const buildDerivedSchemas = (modelFields, indexes, systemFields, resolved
             : Schema.optional(Schema.String);
     }
     const itemSchema = Schema.Struct({
-        ...modelFields,
-        ...fromSelfFields,
+        ...fields,
         ...systemSchemaFields,
         ...keyAttrFields,
         __edd_e__: Schema.String,
     });
     // --- Deleted Record Schema: record + deletedAt ---
     const deletedRecordSchema = Schema.Struct({
-        ...modelFields,
-        ...fromSelfFields,
+        ...fields,
         ...systemSchemaFields,
         deletedAt: Schema.String,
     });
@@ -413,47 +727,50 @@ export const buildDerivedSchemas = (modelFields, indexes, systemFields, resolved
             hiddenFieldNames.add(fieldName);
     }
     const hasHiddenFields = hiddenFieldNames.size > 0;
-    const modelDecodeVisibleSchema = hasHiddenFields
-        ? Schema.Struct(Object.fromEntries(Object.entries({ ...modelFields, ...fromSelfFields }).filter(([k]) => !hiddenFieldNames.has(k))))
-        : modelDecodeSchema;
+    const modelVisibleSchema = hasHiddenFields
+        ? Schema.Struct(Object.fromEntries(Object.entries(fields).filter(([k]) => !hiddenFieldNames.has(k))))
+        : modelSchema;
     const recordVisibleSchema = hasHiddenFields
         ? Schema.Struct(Object.fromEntries(Object.entries({
-            ...modelFields,
-            ...fromSelfFields,
+            ...fields,
             ...systemSchemaFields,
         }).filter(([k]) => !hiddenFieldNames.has(k))))
         : recordSchema;
     // --- Time-series derived schemas ---
-    // `appendInputSchema`: the user-supplied schema directly. `Entity.make()`
+    // `appendInputSchema`: the user-supplied schema, with the same substitution
+    //    rules applied as the model fields (self date schemas → tolerant
+    //    transforms, RedactedFromValue → tolerant Redacted). `Entity.make()`
     //    enforces that every PK/SK composite + `orderBy` appears in its fields.
-    // `historyRecordSchema`: event-item shape. Model fields (with fromSelf for
-    //    date-annotated) + createdAt (when configured, no updatedAt ever since
-    //    timeSeries auto-suppresses). No GSI key attrs — events strip GSI keys.
+    // `historyRecordSchema`: event-item shape. Substituted model fields + no
+    //    system fields (events are point-in-time facts keyed by `orderBy`).
     const timeSeriesEnabled = timeSeries !== undefined && timeSeries !== null;
-    const appendInputSchema = timeSeriesEnabled ? timeSeries.appendInput : null;
-    // Events are point-in-time facts keyed by `orderBy`. They do NOT carry
-    // `createdAt` or `updatedAt` (§4.5 — events already carry `orderBy` as the
-    // temporal anchor). Schema is just model fields with fromSelf for dates.
+    const appendInputSchema = timeSeriesEnabled
+        ? (() => {
+            const userSchema = timeSeries.appendInput;
+            const userFields = userSchema.fields;
+            if (!userFields)
+                return userSchema;
+            // Compute encodings for the appendInput fields (annotation +
+            // inferred from typeConstructor for self schemas).
+            const appendEncodings = buildFieldEncodings(userFields, {});
+            const subbedFields = substituteSchemas(userFields, appendEncodings);
+            return Schema.Struct(subbedFields);
+        })()
+        : null;
     const historyRecordSchema = timeSeriesEnabled
         ? (() => {
             const hiddenFilter = (record) => hasHiddenFields
                 ? Object.fromEntries(Object.entries(record).filter(([k]) => !hiddenFieldNames.has(k)))
                 : record;
-            return Schema.Struct(hiddenFilter({
-                ...modelFields,
-                ...fromSelfFields,
-            }));
+            return Schema.Struct(hiddenFilter({ ...fields }));
         })()
         : null;
     return {
-        modelSchema: modelSchema,
-        modelDecodeSchema: modelDecodeVisibleSchema,
+        modelSchema: modelVisibleSchema,
         recordSchema: recordVisibleSchema,
         inputSchema: inputSchema,
-        inputDecodeSchema: inputDecodeSchema,
         createSchema: createSchema,
         updateSchema: updateSchema,
-        updateDecodeSchema: updateDecodeSchema,
         keySchema: keySchema,
         itemSchema: itemSchema,
         deletedRecordSchema: deletedRecordSchema,