effect-dynamodb 1.21.0 → 1.23.0

package/dist/Aggregate.js

@@ -11,16 +11,16 @@
 import { TypeId as SchemaAggregateTypeId } from "@effect-dynamodb/schema/Aggregate.js";
 import * as DynamoModel from "@effect-dynamodb/schema/DynamoModel.js";
 import { composeCollectionKey, composeKey } from "@effect-dynamodb/schema/DynamoSchema.js";
-import { AggregateAssemblyError, AggregateDecompositionError, AggregateTransactionOverflow, RefNotFound, TransactionCancelled, ValidationError, } from "@effect-dynamodb/schema/Errors.js";
+import { AggregateAssemblyError, AggregateDecompositionError, AggregateTransactionOverflow, ConditionalCheckFailed, DynamoError, RefNotFound, TransactionCancelled, ValidationError, } from "@effect-dynamodb/schema/Errors.js";
 import { makeCompositeKeyForm, toCompositeKeyRecord, } from "@effect-dynamodb/schema/internal/CompositeCodec.js";
-import { buildDateTransform, matchDateRepresentation, resolveSystemFields, substituteSchemaDeep, validateNoTransformOverride, } from "@effect-dynamodb/schema/internal/EntitySchemas.js";
-import { hasEncodingTransformation } from "@effect-dynamodb/schema/internal/SchemaAccessors.js";
+import { buildDateTransform, containsWireTransform, matchDateRepresentation, optionalField, resolveSystemFields, substituteSchemaDeep, validateNoTransformOverride, } from "@effect-dynamodb/schema/internal/EntitySchemas.js";
+import { extractArrayElement, getSchemaFields, hasEncodingTransformation, } from "@effect-dynamodb/schema/internal/SchemaAccessors.js";
 import * as KeyComposer from "@effect-dynamodb/schema/KeyComposer.js";
-import { DateTime, Effect, Option, Schema, SchemaAST } from "effect";
+import { DateTime, Effect, Equal, Option, Schema, SchemaAST, } from "effect";
 import * as Batch from "./Batch.js";
 import { DynamoClient } from "./DynamoClient.js";
 import { fromDefinition as entityFromDefinition } from "./Entity.js";
-import { compileExpr, createConditionOps, parseSimpleShorthand, } from "./internal/Expr.js";
+import { compileExpr, createConditionOps, emptyPartProblem, isEmptyExpr, parseSimpleShorthand, } from "./internal/Expr.js";
 import { createPathBuilder } from "./internal/PathBuilder.js";
 import { generateTimestampPrimitive } from "./internal/TransactableOps.js";
 import { fromAttributeMap, toAttributeMap, toAttributeValue } from "./Marshaller.js";
@@ -99,6 +99,64 @@ const inferDateEncoding = (ast) => {
     }
     return undefined;
 };
+/**
+ * A union that holds a date member alongside a member that is neither a date
+ * nor `Undefined` / `Null` — `Union([DateTimeUtcFromString, Number])`.
+ * `inferDateEncoding` looks through unions to find the date in `optional(date)`,
+ * so it reports such a field as a date, and encoding a `5` through a date
+ * transform throws. Its stored form is the union's own business: it is encoded
+ * member by member through the substituted union instead.
+ */
+const isMixedDateUnion = (ast) => {
+    if (!SchemaAST.isUnion(ast))
+        return false;
+    const isDate = (member) => matchDateRepresentation(SchemaAST.resolve(member)) !==
+        undefined ||
+        matchDateRepresentation(member.annotations) !== undefined;
+    return ast.types.some((member) => !SchemaAST.isUndefined(member) && !SchemaAST.isNull(member) && !isDate(member));
+};
+/**
+ * The date branch shared by both encoder builders: an explicit
+ * `DynamoModel.storedAs` annotation, or the inferred default for a standard
+ * Effect date schema. It wins over the field's own encode because `storedAs` is
+ * precisely an override of it (a `Schema.DateTimeUtc` field marked
+ * `storedAs(DateEpochMs)` must store the epoch, not the ISO string its own schema
+ * would produce).
+ */
+const dateAttrEncoder = (fieldSchema, options) => {
+    if (options?.mixedUnions !== true && isMixedDateUnion(fieldSchema.ast))
+        return undefined;
+    const encoding = DynamoModel.getEncoding(fieldSchema) ?? inferDateEncoding(fieldSchema.ast);
+    if (!encoding)
+        return undefined;
+    const encode = Schema.encodeUnknownSync(buildDateTransform(encoding));
+    return (value) => encode(value);
+};
+/**
+ * The field's own encode, with `decode -> encode` as the fallback so a caller
+ * who already supplied wire form round-trips to itself (the same strategy
+ * `Entity.put` uses). Neither working means the value is neither Type nor
+ * Encoded for this field; it is stored unchanged rather than introducing a
+ * write-time failure mode — that shape is already unreadable, and the tolerant
+ * read path reports it.
+ */
+const ownAttrEncoder = (fieldSchema) => {
+    const codec = fieldSchema;
+    const encode = Schema.encodeUnknownOption(codec);
+    const decode = Schema.decodeUnknownOption(codec);
+    return (value) => {
+        const direct = encode(value);
+        if (Option.isSome(direct))
+            return direct.value;
+        const decoded = decode(value);
+        if (Option.isSome(decoded)) {
+            const reencoded = encode(decoded.value);
+            if (Option.isSome(reencoded))
+                return reencoded.value;
+        }
+        return value;
+    };
+};
 /**
  * Build per-field ATTRIBUTE encoders for a schema's own fields — the write-side
  * equivalent of what `Entity.put` gets for free by encoding its whole input
@@ -106,70 +164,106 @@ const inferDateEncoding = (ast) => {
  *
  * Decomposition works from the schema-DECODED domain object, so every attribute
  * it produces is a Type-side value. Marshalling those directly stores a shape
- * the read path cannot decode: a `Schema.BigIntFromString` field lands as
- * `{N:"5"}` and assembly's decode (which expects the encoded string) rejects it,
- * so the aggregate cannot round-trip at all. Dates were noticed first (#72) and
- * got a date-only pass; the same argument applies to every transformed field.
+ * the read path cannot decode: a `DateTime` lands as a marshalled
+ * `{ epochMilliseconds, "~effect/DateTime", _tag }` map, a `Date` as `{M:{}}`,
+ * a `bigint` as `{N:"5"}`.
  *
  * Exactly ONE encoder per field, so nothing is ever encoded twice:
  *
- * 1. **A date encoding** — an explicit `DynamoModel.storedAs` annotation, or the
- *    inferred default for a standard Effect date schema. This wins over the
- *    field's own encode because `storedAs` is precisely an override of it
- *    (a `Schema.DateTimeUtc` field marked `storedAs(DateEpochMs)` must store the
- *    epoch, not the ISO string its own schema would produce). This branch is the
- *    former `buildAttrEncoders`, unchanged.
- * 2. **Any other encoding transformation** — the field's own `encode`. A ref
- *    field's schema is the referenced entity's, so a hydrated ref is encoded
- *    with the entity it came from, not with the aggregate's schema.
- * 3. **No transformation** — no encoder at all, so the stored bytes are
+ * 1. **A date encoding** — see {@link dateAttrEncoder}.
+ * 2. **Anything that holds a wire transform AT ANY DEPTH** — a leaf transform, a
+ *    `Schema.Class`, and also an `Array` / `Struct` / `Union` containing one, or
+ *    a self date or `Redacted` nested anywhere ({@link containsWireTransform}).
+ *    The attribute is encoded through the SAME substituted, tolerant schema the
+ *    read path decodes it with (`substituteSchemaDeep` under
+ *    `tolerantTransforms`, with the aggregate's ref resolver), so the stored
+ *    form is exactly what assembly reads back — nested date leaves included —
+ *    and a `DynamoModel.ref`-annotated field is encoded through the ref
+ *    target's model. The field's own encode is the fallback.
+ *
+ *    Gating on the TOP-LEVEL node instead (as before #133) skipped every
+ *    container, because an `Arrays` / `Objects` node carries no encoding of its
+ *    own: `Schema.Array(DateTimeUtcFromString)` and `Schema.Array(SomeClass)`
+ *    attributes stored their `DateTime`s as maps.
+ * 3. **Nothing to encode** — no encoder at all, so the stored bytes are
  *    identical to before this existed.
  *
- * The READ path is handled entirely by the aggregate's tolerant `decodeSchema`
- * (see `makeAggregate`), so no separate decoders are needed.
+ * Encoding stays PER ATTRIBUTE: decomposition and key composition need the
+ * Type-side values (`numericTypeWithStringEncoding`), so the aggregate is never
+ * encoded as a whole before it is decomposed.
  */
-const buildAttrEncoders = (fields) => {
+const buildAttrEncoders = (fields, resolveRef) => {
     const encoders = {};
     if (!fields)
         return encoders;
     for (const field of Object.keys(fields)) {
         const fieldSchema = fields[field];
-        // 1. Date encoding — `storedAs` override, else the inferred date default.
-        const encoding = DynamoModel.getEncoding(fieldSchema) ?? inferDateEncoding(fieldSchema.ast);
-        if (encoding) {
-            const encode = Schema.encodeUnknownSync(buildDateTransform(encoding));
-            encoders[field] = (value) => encode(value);
+        // 1. Date encoding.
+        const date = dateAttrEncoder(fieldSchema);
+        if (date) {
+            encoders[field] = date;
             continue;
         }
-        // 3. Identity by construction — `SchemaAST` documents `encoding === undefined`
-        //    as "type and encoded forms are identical". Adding an encoder here could
-        //    only change bytes that are already correct.
-        if (!hasEncodingTransformation(fieldSchema))
+        // 3. Nothing anywhere in the value has a wire form distinct from its domain form.
+        if (!containsWireTransform(fieldSchema))
             continue;
-        // 2. The field's own encode, with `decode -> encode` as the fallback so a
-        //    caller who already supplied wire form round-trips to itself (the same
-        //    strategy `Entity.put` uses). Neither working means the value is neither
-        //    Type nor Encoded for this field; store it unchanged rather than
-        //    introduce a new write-time failure mode mid-release — that shape is
-        //    already unreadable, and the tolerant read path reports it.
-        const codec = fieldSchema;
-        const encode = Schema.encodeUnknownOption(codec);
-        const decode = Schema.decodeUnknownOption(codec);
+        // 2. Encode through the read path's own (substituted, tolerant) schema. A
+        //    one-field struct carries the field's optionality and lets `resolveRef`
+        //    re-point the field itself, exactly as it does inside `decodeSchema`.
+        const substituted = substituteSchemaDeep(Schema.Struct({ [field]: fieldSchema }), {
+            tolerantTransforms: true,
+            resolveRef,
+        });
+        const encodeSubstituted = Schema.encodeUnknownOption(substituted);
+        const own = ownAttrEncoder(fieldSchema);
         encoders[field] = (value) => {
-            const direct = encode(value);
-            if (Option.isSome(direct))
-                return direct.value;
-            const decoded = decode(value);
-            if (Option.isSome(decoded)) {
-                const reencoded = encode(decoded.value);
-                if (Option.isSome(reencoded))
-                    return reencoded.value;
-            }
-            return value;
+            const encoded = encodeSubstituted({ [field]: value });
+            if (Option.isSome(encoded))
+                return encoded.value[field];
+            return own(value);
         };
     }
     return encoders;
 };
+/**
+ * The encoders sort-key composites are READ from — the encoders as they stood
+ * before #133, gated on the field's TOP-LEVEL encoding.
+ *
+ * A `many` edge's declared `sk.composite` (and a root list index's composites)
+ * are read off the item's attributes. Those attributes used to be encoded by
+ * these encoders only, so the stored keys were composed from their output: a
+ * top-level transformed field from its encoded form, anything nested (a
+ * `DateTime` or `NumberFromString` reached through `"umpire.dateOfBirth"`) from
+ * its domain form. Composing keys from the new, deeper encoders instead would
+ * re-spell those keys — orphaning every stored row and making `update` diff
+ * against keys that do not exist. Keys therefore keep this exact behaviour,
+ * and only the STORED attribute values gain the deeper encoding.
+ */
+const buildKeyAttrEncoders = (fields) => {
+    const encoders = {};
+    if (!fields)
+        return encoders;
+    for (const field of Object.keys(fields)) {
+        const fieldSchema = fields[field];
+        const date = dateAttrEncoder(fieldSchema, { mixedUnions: true });
+        if (date) {
+            // Before, a value this encoder rejects (the `5` of a mixed date union)
+            // threw and failed the write, so there is no stored key to stay
+            // byte-identical with: compose from the value as it is.
+            encoders[field] = (value) => {
+                try {
+                    return date(value);
+                }
+                catch {
+                    return value;
+                }
+            };
+        }
+        else if (hasEncodingTransformation(fieldSchema))
+            encoders[field] = ownAttrEncoder(fieldSchema);
+    }
+    return encoders;
+};
 /**
  * A schema's declared fields, if it exposes them (Schema.Struct / Schema.Class).
  *
@@ -185,11 +279,156 @@ const fieldsOf = (schema) => {
     const source = DynamoModel.isConfiguredModel(schema) ? schema.model : schema;
     return source?.fields;
 };
+/** The value schema of a struct field, with any `optionalKey` / `optional` wrapper removed. */
+const unwrapOptionalField = (field) => optionalField(field)?.inner ?? field;
+/**
+ * Whether a field is a class-like value whose fields the schema walker cannot
+ * see. `DynamoModel.ref` annotates with `Schema.annotate`, which drops a
+ * `Schema.Class`'s `.fields`, so `substituteSchemaDeep` cannot recurse into it
+ * and the target's transformed fields keep their strict decoders. A plain class
+ * is introspectable and is left to the walker.
+ */
+const isOpaqueRefField = (field) => {
+    const inner = unwrapOptionalField(field);
+    return getSchemaFields(inner) === undefined && SchemaAST.isDeclaration(inner.ast);
+};
+/**
+ * The fields of a `many` edge's ELEMENT, read off the parent model's array
+ * field (`players: Schema.Array(PlayerSheet)` → `PlayerSheet`'s fields).
+ * `undefined` when the field is not array-shaped (a custom `decompose`) or its
+ * element exposes no fields (a scalar, or an opaque ref).
+ */
+const manyElementFields = (parentFields, edgeName) => {
+    const field = parentFields?.[edgeName];
+    const element = field === undefined ? undefined : extractArrayElement(field);
+    return element === undefined ? undefined : getSchemaFields(element);
+};
 /**
- * Apply a node's date encoders in place — converts the node entity's own domain
- * date fields to their wire primitives before the decomposed item is marshalled
- * (issue #72: without this, an edge's `DateTime` field marshals to `{M:{}}` and
- * the subsequent `get`/assemble fails decoding it as a string).
+ * A sub-aggregate nested in another inherits its parent's discriminator, and
+ * its rows carry both (#133). Re-using an inherited attribute name would
+ * overwrite the parent's value on the inner rows: the two bindings of the
+ * parent would then key and assemble the inner sub-aggregate identically.
+ * Refused at `make()` time, naming the edge, rather than surfacing as a
+ * key collision or a mis-assembly at runtime.
+ */
+const validateNestedDiscriminators = (aggregateName, edges, inherited = new Map(), path = []) => {
+    for (const [edgeName, edge] of Object.entries(edges)) {
+        if (!("_tag" in edge) || edge._tag !== "BoundSubAggregate")
+            continue;
+        const bound = edge;
+        const here = [...path, edgeName];
+        const own = Object.keys(bound.discriminator ?? {});
+        for (const attr of own) {
+            const owner = inherited.get(attr);
+            if (owner !== undefined) {
+                throw new Error(`[EDD-9056] Aggregate "${aggregateName}": the sub-aggregate at "${here.join(".")}" ` +
+                    `declares discriminator "${attr}", which it already inherits from "${owner}". ` +
+                    `A nested sub-aggregate's rows carry every enclosing discriminator, so the inner ` +
+                    `value would overwrite the outer one. Give the nested binding a distinct attribute ` +
+                    `name (e.g. { squadNo: 1 } inside { clubNo: 1 }).`);
+            }
+        }
+        const next = new Map(inherited);
+        for (const attr of own)
+            next.set(attr, here.join("."));
+        validateNestedDiscriminators(aggregateName, bound.aggregate.edges, next, here);
+    }
+};
+const unwrapEntityModel = (model) => DynamoModel.isConfiguredModel(model) ? model.model : model;
+/**
+ * Map each ref FIELD SCHEMA the aggregate's schema walker cannot see into to the
+ * model it should be decoded (and encoded) as.
+ *
+ * `substituteSchemaDeep` recurses into plain classes / structs / arrays on its
+ * own. It cannot recurse into a `DynamoModel.ref`-annotated class (the
+ * annotation drops `.fields`), so that field's transformed leaves keep their
+ * strict decoders: a re-decoded domain `DateTime` is rejected as "Expected
+ * string", and a legacy marshalled one is never lifted. Registered here:
+ *
+ * - **root `one` / `ref` edge fields** — unconditionally, re-pointed at the
+ *   edge entity's model (the behaviour since #72);
+ * - **sub-aggregate `one` / `ref` edge fields** and **the ref field inside a
+ *   `many` element** (`PlayerSheet.player`, found by
+ *   `deriveEntityFieldName(entity)` as hydration finds it), at root or in a
+ *   sub-aggregate — only when OPAQUE. A plain class there is already walked,
+ *   and swapping it for the entity's model could only make its decode stricter
+ *   or change its class (#133);
+ * - **a `many` edge field whose ELEMENT is an opaque ref**
+ *   (`Schema.Array(Player.pipe(DynamoModel.ref))`) — the array field itself,
+ *   re-pointed at `Schema.Array(<entity model>)`, since the walker can only
+ *   re-point fields, not array elements;
+ * - **refs nested inside an edge entity's own model** (`maker` on a `supplier`
+ *   edge entity, #116).
+ *
+ * Keyed by schema IDENTITY. The resolver is consulted at every depth of the
+ * walk, so the former name-keyed table re-pointed every same-named field
+ * anywhere in the model — a `coach` field three levels down was decoded as the
+ * root `coach` edge's entity.
+ */
+const collectRefTargets = (rootFields, rootEdges) => {
+    const targets = new Map();
+    const register = (field, model) => {
+        if (field !== undefined && model !== undefined && !targets.has(field)) {
+            targets.set(field, unwrapEntityModel(model));
+        }
+    };
+    const registerNested = (entity) => {
+        if (entity?.model === undefined)
+            return;
+        const entityFields = getSchemaFields(unwrapEntityModel(entity.model));
+        for (const nested of entity._data?.resolvedRefs ?? []) {
+            register(entityFields?.[nested.fieldName], nested.refEntity?.model);
+        }
+    };
+    const walk = (fields, edges, isRoot) => {
+        for (const [edgeName, edge] of Object.entries(edges)) {
+            if (!("_tag" in edge))
+                continue;
+            if (edge._tag === "RefEdge" || edge._tag === "OneEdge") {
+                const entity = edge.entity;
+                const field = fields?.[edgeName];
+                if (field !== undefined && (isRoot || isOpaqueRefField(field))) {
+                    register(field, entity?.model);
+                }
+                registerNested(entity);
+            }
+            else if (edge._tag === "ManyEdge") {
+                const entity = edge.entity;
+                const arrayField = fields?.[edgeName];
+                const element = arrayField === undefined ? undefined : extractArrayElement(arrayField);
+                if (arrayField !== undefined && element !== undefined && isOpaqueRefField(element)) {
+                    // The element IS an opaque ref (`Schema.Array(Player.pipe(DynamoModel.ref))`):
+                    // re-point the whole array field at an array of the entity's model. The
+                    // walker re-applies the field's optionality around the target.
+                    const model = entity?.model;
+                    if (model !== undefined && !targets.has(arrayField)) {
+                        targets.set(arrayField, Schema.Array(unwrapEntityModel(model)));
+                    }
+                }
+                else if (edge.entity !== undefined) {
+                    // The element WRAPS the ref (`PlayerSheet { player }`), found by name as
+                    // hydration finds it.
+                    const refField = manyElementFields(fields, edgeName)?.[deriveEntityFieldName(edge.entity)];
+                    if (refField !== undefined && isOpaqueRefField(refField)) {
+                        register(refField, entity?.model);
+                    }
+                }
+                registerNested(entity);
+            }
+            else if (edge._tag === "BoundSubAggregate") {
+                const bound = edge;
+                walk(fieldsOf(bound.aggregate.schema), bound.aggregate.edges, false);
+            }
+        }
+    };
+    walk(rootFields, rootEdges, true);
+    return targets;
+};
+/**
+ * Apply a node's attribute encoders in place — puts each attribute into its
+ * stored form before the decomposed item is marshalled (#72, #133: without
+ * this, a `DateTime` marshals to a `{ epochMilliseconds, … }` map that the
+ * read path cannot decode as the wire form).
  */
 const applyNodeAttrEncoders = (attrs, encoders) => {
     if (!encoders)
@@ -203,26 +442,8 @@ const applyNodeAttrEncoders = (attrs, encoders) => {
 // Top-level aggregate construction
 // ---------------------------------------------------------------------------
 const makeAggregate = (schema, config) => {
-    // Build resolved graph by walking edges recursively
-    const rootNode = resolveNode({
-        fieldName: null,
-        entityType: config.root.entityType,
-        cardinality: "root",
-        edges: config.edges,
-    });
     const aggregateName = config.root.entityType;
     const contextFields = config.context ?? [];
-    // Detect date encodings for all root schema fields (once, at make() time)
-    // and build a per-field bidirectional substitute schema.
-    //
-    // Aggregates decompose/assemble at the root-attribute level — each date
-    // field is converted in isolation (write: domain → wire primitive; read:
-    // wire primitive → domain). To stay schema-driven (issue #29), we route
-    // the conversion through the same `buildDateTransform` substitute used by
-    // Entity. `Schema.encodeUnknownSync` produces the wire form on writes and
-    // `Schema.decodeUnknownSync` lifts the wire form back on reads — wire
-    // format is byte-identical to the legacy per-field helpers.
-    //
     // Policy: aggregate fields that already carry a date transform schema
     // (e.g. `Schema.DateTimeUtcFromString`) cannot be combined with a
     // `DynamoModel.storedAs(...)` annotation that conflicts with the
@@ -235,58 +456,57 @@ const makeAggregate = (schema, config) => {
         // annotation conflict is checked.
         validateNoTransformOverride(schemaFields, {});
     }
-    // Date ENCODERS for the write path: decompose works from the schema-decoded
-    // domain object, so every root date field (Pattern A self-date AND Pattern B
-    // transform) is serialized to its wire primitive for storage.
-    const attrEncoders = buildAttrEncoders(schemaFields);
+    validateNestedDiscriminators(aggregateName, config.edges);
+    // Ref fields whose target the schema walker must be told about (see
+    // `collectRefTargets`). Keyed by the field SCHEMA, not its name: the resolver
+    // is consulted at every depth, so a name-keyed table re-pointed any
+    // same-named field anywhere in the model.
+    const refTargets = collectRefTargets(schemaFields, config.edges);
+    const resolveRef = (_name, field) => refTargets.get(field);
+    // Build resolved graph by walking edges recursively. Each node's attribute
+    // encoders come from the schema its decomposed values actually have — for a
+    // `many` edge that is the aggregate model's array ELEMENT (#133).
+    const rootNode = resolveNode({
+        fieldName: null,
+        entityType: config.root.entityType,
+        cardinality: "root",
+        edges: config.edges,
+        parentFields: schemaFields,
+        resolveRef,
+    });
+    // Attribute ENCODERS for the root item: decompose works from the
+    // schema-decoded domain object, so every root attribute holding a wire
+    // transform — a date, a transformed scalar, or a container of either — is
+    // put into its stored form. The key encoders are the pre-#133 ones, which the
+    // root's list-index composites are still read from (see `buildKeyAttrEncoders`).
+    const attrEncoders = buildAttrEncoders(schemaFields, resolveRef);
+    const keyAttrEncoders = buildKeyAttrEncoders(schemaFields);
+    const rootEncoders = { stored: attrEncoders, key: keyAttrEncoders };
     // Decode schema for read/assemble + input validation. Mirrors the raw `schema`
-    // but recursively substitutes EVERY date / Redacted leaf — root and nested,
-    // Pattern A and Pattern B — with a TOLERANT transform. This is the single
-    // decode path for get / create / update:
+    // but recursively substitutes EVERY date / Redacted / transformed leaf — root
+    // and nested — with a TOLERANT transform. This is the single decode path for
+    // get / create / update:
     //   - reads supply the stored wire form (string/number) → lifted to domain;
+    //     a legacy marshalled `DateTime` map is rebuilt into a real one (#133);
     //   - update re-decodes the mutated state, which carries domain `DateTime`
     //     values → accepted as-is (a strict `*FromString` decoder would reject
     //     them). It is decode-only, so making transforms tolerant is safe — the
-    //     stored wire format is still produced by `attrEncoders` / node encoders.
+    //     stored wire format is still produced by the attribute encoders.
     // Nested edge / ref classes round-trip with their class instance identity
     // preserved (Option A). Returns the raw `schema` unchanged when it carries no
-    // date / Redacted leaf at all (zero overhead).
-    //
-    // SINGLE ref/one edge fields carry the opaque `DynamoModel.ref` annotation, so
-    // the substitution can't introspect them — `resolveRef` re-points each to its
-    // edge target model (unwrapping `DynamoModel.configure`). MANY edges are
-    // excluded: their model field is a `Schema.Array(...)` (or a wrapper class) that
-    // `substituteSchemaDeep` introspects directly — re-pointing it at the element
-    // model would drop the `Array` and yield "Expected object, got []" on assemble.
-    const edgeRefModels = new Map();
-    const unwrapModel = (model) => DynamoModel.isConfiguredModel(model) ? model.model : model;
-    for (const [edgeName, edge] of Object.entries(config.edges)) {
-        if (!("_tag" in edge))
-            continue;
-        if (edge._tag !== "RefEdge" && edge._tag !== "OneEdge")
-            continue;
-        const entity = edge.entity;
-        const model = entity?.model;
-        if (!model)
-            continue;
-        edgeRefModels.set(edgeName, unwrapModel(model));
-        // A ref nested INSIDE an edge's model needs the same treatment. `maker` on
-        // an edge entity is annotated with `DynamoModel.ref`, and `Schema.annotate`
-        // drops a `Schema.Class`'s `.fields`, so the substitution cannot introspect
-        // it and the target's own transformed fields keep their strict schemas —
-        // which is what made `update` reject a `bigint` at
-        // `["supplier"]["maker"]["founded"]` (#116). Registering the target by field
-        // name re-points it exactly as a top-level edge is re-pointed.
-        for (const nested of entity?._data?.resolvedRefs ?? []) {
-            const nestedModel = nested.refEntity?.model;
-            if (nestedModel && !edgeRefModels.has(nested.fieldName)) {
-                edgeRefModels.set(nested.fieldName, unwrapModel(nestedModel));
-            }
-        }
-    }
+    // such leaf at all (zero overhead).
     const decodeSchema = substituteSchemaDeep(schema, {
         tolerantTransforms: true,
-        resolveRef: (name) => edgeRefModels.get(name),
+        resolveRef,
+    });
+    // The same schema for WRITES — `create` input and `update`'s mutated state —
+    // with the container `.check()` refinements the substitution rebuilds kept, so
+    // a write that breaks one is rejected (#133). Assembly keeps `decodeSchema`:
+    // a row written while those checks were not enforced must stay readable.
+    const writeSchema = substituteSchemaDeep(schema, {
+        tolerantTransforms: true,
+        resolveRef,
+        enforceChecks: true,
     });
     // Validate the collection index / consistency combination against the table's
     // primary key. Best effort: a table registering only aggregates has no primary key
@@ -360,6 +580,19 @@ const makeAggregate = (schema, config) => {
     // Build optics at construction time (once per aggregate definition)
     const classToPlain = Schema.toIso(schema);
     const opticRoot = Schema.toIsoFocus(schema);
+    // The same conversion through the READ schema. `toIso(schema)` re-checks the
+    // model's `.check()` refinements, so a stored row written while a container
+    // check was not enforced (#133) would make every `update` throw before the
+    // mutation could repair it. Reads accept such a row; so does this.
+    const readToPlain = Schema.toIso(decodeSchema);
+    const toPlainState = (value) => {
+        try {
+            return classToPlain.get(value);
+        }
+        catch {
+            return readToPlain.get(value);
+        }
+    };
     // Composite key form — the SAME rule and the SAME function the entity path
     // uses (`internal/CompositeCodec.ts`). Aggregates compose from assembled
     // domain objects, so without this a `DateEpochMs` composite would key on its
@@ -371,7 +604,24 @@ const makeAggregate = (schema, config) => {
             `${JSON.stringify(String(value))} resolves under neither encode nor decode->encode. ` +
             `Supply a value of the attribute's own type.`);
     });
-    const keyRecord = (record) => toCompositeKeyRecord(compositeKeyForm, record);
+    // Only the attributes a key is ever composed from are put into key form. The
+    // rest of the record is never read off the result, and normalising it could
+    // only fail: a stored value that breaks a field's `.check()` (#133) made
+    // every `update` throw EDD-9050 over an attribute no key uses.
+    const compositeAttrs = new Set([
+        ...config.pk.composite,
+        ...(config.collection.sk?.composite ?? []),
+        ...(config.list?.pk.composite ?? []),
+        ...(config.list?.sk.composite ?? []),
+    ]);
+    const keyRecord = (record) => {
+        const composites = {};
+        for (const attr of compositeAttrs) {
+            if (attr in record)
+                composites[attr] = record[attr];
+        }
+        return toCompositeKeyRecord(compositeKeyForm, composites);
+    };
     /** Shared: compose PK and query all items */
     const fetchPartition = (key) => Effect.gen(function* () {
         const client = yield* DynamoClient;
@@ -423,7 +673,7 @@ const makeAggregate = (schema, config) => {
             // 2. Validate via schema decode (decodeSchema substitutes nested edge
             //    self-date/Redacted leaves — Option A — and is identical to `schema`
             //    when no edge needs it).
-            const decoded = yield* Schema.decodeUnknownEffect(decodeSchema)(hydrated).pipe(Effect.mapError((cause) => new ValidationError({
+            const decoded = yield* Schema.decodeUnknownEffect(writeSchema)(hydrated).pipe(Effect.mapError((cause) => new ValidationError({
                 entityType: aggregateName,
                 operation: "aggregate.create",
                 cause,
@@ -433,7 +683,7 @@ const makeAggregate = (schema, config) => {
             const composites = KeyComposer.extractComposites(config.pk.composite, keyRecord(assembled));
             const pkValue = composeCollectionKey(config.schema, config.collection.name, composites);
             // 4. Decompose into items grouped by sub-aggregate transaction boundaries
-            const groups = yield* decomposeAggregate(assembled, rootNode, contextFields, attrEncoders, aggregateName, config.schema);
+            const groups = yield* decomposeAggregate(assembled, rootNode, contextFields, rootEncoders, aggregateName, config.schema);
             // 5. Compose collection SK composites for root item. Through the key
             // form — `update` already did (see `newDynamo` / `oldDynamo` below), so
             // leaving `create` raw made the two write paths mirror the collection SK
@@ -443,8 +693,25 @@ const makeAggregate = (schema, config) => {
             //    Every row is new, so `created` has nothing to carry forward.
             const now = yield* DateTime.now;
             const dynamoGroups = buildDynamoItems(groups, config, pkValue, collectionSkComposites, keyRecord, stampFor(now, EMPTY_CREATED));
-            // 7. Write via sub-aggregate transactions
-            yield* writeTransactionGroups(client, tableConfig.name, dynamoGroups.map((g) => ({ group: g.group, puts: g.items, deletes: [] })), aggregateName);
+            // 7. Write via sub-aggregate transactions. The root item goes first in
+            //    the first transaction, guarded by `attribute_not_exists` (#134):
+            //    an existing aggregate cancels it before any edge or sub-aggregate
+            //    row is written. Rows below the root need no guard of their own —
+            //    they are only ever written after the root's transaction commits.
+            const rootSk = composeKey(config.schema, config.root.entityType, []);
+            const isRoot = (item) => item.sk?.S === rootSk;
+            const ordered = [...dynamoGroups]
+                .sort((a, b) => Number(b.items.some(isRoot)) - Number(a.items.some(isRoot)))
+                .map((g) => ({
+                group: g.group,
+                puts: [...g.items].sort((a, b) => Number(isRoot(b)) - Number(isRoot(a))),
+                deletes: [],
+            }));
+            yield* writeTransactionGroups(client, tableConfig.name, ordered, aggregateName, {
+                pkField: config.pk.field,
+                entityType: config.root.entityType,
+                key: { [config.pk.field]: pkValue, sk: rootSk },
+            });
             return decoded;
         }),
         update: (key, mutationFn) => Effect.gen(function* () {
@@ -459,7 +726,7 @@ const makeAggregate = (schema, config) => {
             // 1. Assemble current state
             const current = yield* assembleAggregate(decodeSchema, rootNode, allItems, contextFields, key, aggregateName, systemAttrs);
             // 2. Apply mutation — provide optics context for composable updates
-            const state = classToPlain.get(current);
+            const state = toPlainState(current);
             const updated = mutationFn({
                 state,
                 cursor: makeCursor(state, opticRoot),
@@ -471,7 +738,7 @@ const makeAggregate = (schema, config) => {
             //    for every date field (root + nested edges, Pattern A and Pattern B),
             //    so update no longer trips the "Expected string, got DateTime" decode
             //    that a strict `*FromString` schema would raise (#72 update path).
-            const decoded = yield* Schema.decodeUnknownEffect(decodeSchema)(updated).pipe(Effect.mapError((cause) => new ValidationError({
+            const decoded = yield* Schema.decodeUnknownEffect(writeSchema)(updated).pipe(Effect.mapError((cause) => new ValidationError({
                 entityType: aggregateName,
                 operation: "aggregate.update",
                 cause,
@@ -479,8 +746,8 @@ const makeAggregate = (schema, config) => {
             const assembledOld = { ...current };
             const assembledNew = { ...decoded };
             // 4. Decompose both old and new
-            const oldGroups = yield* decomposeAggregate(assembledOld, rootNode, contextFields, attrEncoders, aggregateName, config.schema);
-            const newGroups = yield* decomposeAggregate(assembledNew, rootNode, contextFields, attrEncoders, aggregateName, config.schema);
+            const oldGroups = yield* decomposeAggregate(assembledOld, rootNode, contextFields, rootEncoders, aggregateName, config.schema);
+            const newGroups = yield* decomposeAggregate(assembledNew, rootNode, contextFields, rootEncoders, aggregateName, config.schema);
             // 5. Diff at the ITEM (primary-key) level, not just the group level.
             //    A `many`-edge element — and a cleared `one` edge — lives in its PARENT's
             //    transaction group, so removing it SHRINKS a group rather than dropping a
@@ -576,7 +843,7 @@ const makeAggregate = (schema, config) => {
             // Root-item FilterExpression. Compiled once — the same two forms
             // `BoundQuery.filter()` takes, through the same `Expr` compiler, so
             // there is one filter vocabulary rather than a second dialect here.
-            const rootFilter = compileListFilter(options?.filter);
+            const rootFilter = yield* compileListFilter(options?.filter, aggregateName);
             // Attribute names that make up a resume key on the list index: the index
             // key plus the table key. A `LastEvaluatedKey` supplies them when there
             // is one; this is the fallback for the case a filtered request over-reads
@@ -754,7 +1021,7 @@ const deepEqualGroups = (a, b) => {
     });
 };
 const resolveNode = (args) => {
-    const { assemble, cardinality, attrEncoders, decompose, discriminator, edges, entityType, fieldName, ownDiscriminator, refIdentifierField, skComposite, } = args;
+    const { assemble, cardinality, attrEncoders, decompose, discriminator, edges, entityType, fieldName, keyAttrEncoders, ownDiscriminator, parentFields, refIdentifierField, resolveRef, skComposite, } = args;
     const children = [];
     for (const [field, edge] of Object.entries(edges)) {
         if ("_tag" in edge) {
@@ -763,6 +1030,14 @@ const resolveNode = (args) => {
                 const mergedDisc = edge.discriminator
                     ? { ...(discriminator ?? {}), ...edge.discriminator }
                     : discriminator;
+                // The item is the edge value flattened: encode it field by field with
+                // the edge entity's model (#72), or — for an edge without an entity —
+                // with the model field's own class.
+                const parentField = parentFields?.[field];
+                const valueFields = fieldsOf(edge.entity?.model) ??
+                    (parentField === undefined
+                        ? undefined
+                        : getSchemaFields(unwrapOptionalField(parentField)));
                 children.push(resolveNode({
                     fieldName: field,
                     entityType: edge.entityType,
@@ -770,11 +1045,19 @@ const resolveNode = (args) => {
                     edges: {},
                     discriminator: mergedDisc,
                     ownDiscriminator: edge.discriminator,
-                    // Encode this edge entity's own date fields on write (issue #72).
-                    attrEncoders: buildAttrEncoders(fieldsOf(edge.entity?.model)),
+                    attrEncoders: buildAttrEncoders(valueFields, resolveRef),
                 }));
             }
             else if (edge._tag === "ManyEdge") {
+                // The item is one decomposed ELEMENT. Its encoders must come from the
+                // element's schema — `PlayerSheet { player, isCaptain }` — not from the
+                // edge entity's model (`Player { id, name, dateOfBirth }`), whose field
+                // names never match a wrapper element's, so a hydrated ref inside the
+                // element was never encoded (#133). An element that exposes no fields
+                // (a custom `decompose`, an opaque ref element) falls back to the
+                // entity's model, which is what such an element IS.
+                const entityFields = fieldsOf(edge.entity?.model);
+                const elementFields = manyElementFields(parentFields, field) ?? entityFields;
                 children.push(resolveNode({
                     fieldName: field,
                     entityType: edge.entityType,
@@ -783,7 +1066,10 @@ const resolveNode = (args) => {
                     discriminator,
                     assemble: edge.assemble,
                     decompose: edge.decompose,
-                    attrEncoders: buildAttrEncoders(fieldsOf(edge.entity?.model)),
+                    attrEncoders: buildAttrEncoders(elementFields, resolveRef),
+                    // Sort-key composites keep reading the pre-#133 encoding (the entity
+                    // model's top-level transforms), so no stored key is re-spelled.
+                    keyAttrEncoders: buildKeyAttrEncoders(entityFields),
                     // Declared sort-key composites, authoritative when present (#103).
                     skComposite: edge.sk?.composite,
                     refIdentifierField: edge.entity
@@ -793,16 +1079,28 @@ const resolveNode = (args) => {
             }
             else if (edge._tag === "BoundSubAggregate") {
                 const bound = edge;
+                const subFields = fieldsOf(bound.aggregate.schema);
+                // A sub-aggregate nested in another inherits its parent's discriminator,
+                // exactly as a `one` edge does: its rows carry the parent's attributes
+                // (`clubNo`) as well as their own (`squadNo`), so assembly — which
+                // matches on the merged set — can tell the two bindings of the parent
+                // apart. At the top level there is no parent discriminator and this is
+                // `bound.discriminator`, as before.
+                const inherited = discriminator === undefined
+                    ? bound.discriminator
+                    : { ...discriminator, ...bound.discriminator };
                 const subChildren = resolveNode({
                     fieldName: field,
                     entityType: bound.aggregate.root.entityType,
                     cardinality: "one",
                     edges: bound.aggregate.edges,
-                    discriminator: bound.discriminator,
+                    parentFields: subFields,
+                    resolveRef,
+                    discriminator: inherited,
                     ownDiscriminator: bound.discriminator,
                     // The sub-aggregate root item carries the sub-schema's own (non-edge)
-                    // date fields; its child edges get their own encoders via recursion.
-                    attrEncoders: buildAttrEncoders(fieldsOf(bound.aggregate.schema)),
+                    // fields; its child edges get their own encoders via recursion.
+                    attrEncoders: buildAttrEncoders(subFields, resolveRef),
                 });
                 children.push(subChildren);
             }
@@ -821,6 +1119,7 @@ const resolveNode = (args) => {
         ...(skComposite !== undefined && { skComposite }),
         ...(refIdentifierField !== undefined && { refIdentifierField }),
         attrEncoders,
+        ...(keyAttrEncoders !== undefined && { keyAttrEncoders }),
     };
 };
 // ---------------------------------------------------------------------------
@@ -1203,12 +1502,62 @@ const collectRefIdsFromEdges = (result, input, edges, path) => {
         }
     }
 };
+/**
+ * Deep-copy a create input so ref replacement can mutate it — like
+ * `structuredClone`, which this replaces, except that DOMAIN VALUES survive.
+ *
+ * `structuredClone` copies only own enumerable properties, so it reduced every
+ * Effect data type to a bare object: a `DateTime` became `{ epochMilliseconds }`
+ * with no prototype or tag, a `Redacted` became `{}`, an `Option` lost its
+ * variant. No schema accepts those, so any aggregate with a ref edge rejected
+ * such a value in its create input (#133).
+ *
+ * - Values implementing `Equal` — `DateTime`, `Redacted`, `Option`, `Duration`,
+ *   `Chunk`, `HashMap`, … — are immutable, so they are kept by reference.
+ * - Built-ins `structuredClone` knows (`Date`, `Map`, `Set`, `RegExp`, binary
+ *   data) still go through it.
+ * - Plain objects, arrays and other class instances (a `Schema.Class` value
+ *   among them) are walked and copied to plain objects, as `structuredClone`
+ *   copied them — so ref replacement never mutates the caller's objects.
+ * - Cycles are preserved, as `structuredClone` preserved them.
+ */
+const cloneInput = (value, seen = new WeakMap()) => {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Equal.isEqual(value))
+        return value;
+    const prior = seen.get(value);
+    if (prior !== undefined)
+        return prior;
+    if (Array.isArray(value)) {
+        const copy = [];
+        seen.set(value, copy);
+        for (const entry of value)
+            copy.push(cloneInput(entry, seen));
+        return copy;
+    }
+    if (value instanceof Date ||
+        value instanceof Map ||
+        value instanceof Set ||
+        value instanceof RegExp ||
+        ArrayBuffer.isView(value) ||
+        value instanceof ArrayBuffer) {
+        const copy = structuredClone(value);
+        seen.set(value, copy);
+        return copy;
+    }
+    const copy = {};
+    seen.set(value, copy);
+    for (const [key, entry] of Object.entries(value))
+        copy[key] = cloneInput(entry, seen);
+    return copy;
+};
 /**
  * Replace ref ID fields in the input with hydrated domain data.
  */
 const replaceRefIds = (input, refRequests, lookup) => {
     // Deep clone the input for mutation
-    const result = structuredClone(input);
+    const result = cloneInput(input);
     for (const req of refRequests) {
         const lookupKey = `${req.entity.entityType}:${req.id}`;
         const data = lookup.get(lookupKey);
@@ -1239,31 +1588,35 @@ const replaceRefIds = (input, refRequests, lookup) => {
  * Decompose an assembled domain object into DynamoDB items grouped by
  * sub-aggregate transaction boundaries.
  */
-const decomposeAggregate = (assembled, rootNode, contextFields, attrEncoders, aggregateName, schema) => Effect.gen(function* () {
+const decomposeAggregate = (assembled, rootNode, contextFields, encoders, aggregateName, schema) => Effect.gen(function* () {
     const items = [];
-    // Extract context values from the root, serializing date fields for DynamoDB storage.
+    const encodeWith = (set, field, value) => {
+        const encode = set[field];
+        return encode && value != null ? encode(value) : value;
+    };
+    // Extract context values from the root, encoded for DynamoDB storage.
     // Domain Date/DateTime objects must be encoded before toAttributeMap() marshalling,
     // otherwise Date objects become { M: {} } (no enumerable properties).
-    // The encoder is the substituted bidirectional date schema built at make() time.
-    const contextValues = {};
+    const contextValues = { stored: {}, key: {} };
     for (const field of contextFields) {
         const value = assembled[field];
-        const encode = attrEncoders[field];
-        contextValues[field] = encode && value != null ? encode(value) : value;
+        contextValues.stored[field] = encodeWith(encoders.stored, field, value);
+        contextValues.key[field] = encodeWith(encoders.key, field, value);
     }
     // Root item: fields not claimed by edges
     const edgeFieldNames = new Set(rootNode.children.map((c) => c.fieldName).filter(Boolean));
     const rootAttrs = {};
+    const rootKeyAttrs = {};
     for (const [key, value] of Object.entries(assembled)) {
         if (edgeFieldNames.has(key))
             continue;
-        // Serialize date fields in root attributes (same as context values)
-        const encode = attrEncoders[key];
-        rootAttrs[key] = encode && value != null ? encode(value) : value;
+        rootAttrs[key] = encodeWith(encoders.stored, key, value);
+        rootKeyAttrs[key] = encodeWith(encoders.key, key, value);
     }
     items.push({
         entityType: rootNode.entityType,
         attributes: rootAttrs,
+        keyAttributes: rootKeyAttrs,
         transactionGroup: "root",
         skComposites: [],
         member: rootNode.entityType,
@@ -1326,13 +1679,21 @@ const decomposeNode = (items, node, value, contextValues, parentGroup, parentDis
     if (node.cardinality === "one" && node.children.length > 0) {
         // Sub-aggregate — becomes its own transaction group
         const subValue = value;
-        const txGroup = node.fieldName ?? node.entityType;
-        // Discriminator values for SK composition (name#value pairs from own discriminator)
-        const discValues = node.ownDiscriminator
-            ? Object.entries(node.ownDiscriminator)
-                .filter(([, v]) => typeof v !== "function")
-                .flatMap(([k, v]) => [k, KeyComposer.serializeValue(v)])
-            : [];
+        // A nested sub-aggregate is its own transaction group, named by its path
+        // (`club2.squad`) so the two bindings of its parent stay distinct groups.
+        const ownName = node.fieldName ?? node.entityType;
+        const txGroup = parentGroup === "root" ? ownName : `${parentGroup}.${ownName}`;
+        // Discriminator values for SK composition: the parent sub-aggregate's
+        // (name#value pairs, empty at the top level) then this node's own, so a
+        // nested sub-aggregate's rows are keyed apart per binding of its parent.
+        const discValues = [
+            ...parentDiscriminatorValues,
+            ...(node.ownDiscriminator
+                ? Object.entries(node.ownDiscriminator)
+                    .filter(([, v]) => typeof v !== "function")
+                    .flatMap(([k, v]) => [k, KeyComposer.serializeValue(v)])
+                : []),
+        ];
         // Sub-aggregate root item: fields not claimed by child edges
         const childEdgeNames = new Set(node.children.map((c) => c.fieldName).filter(Boolean));
         const subRootAttrs = {};
@@ -1344,7 +1705,7 @@ const decomposeNode = (items, node, value, contextValues, parentGroup, parentDis
         // Serialize this node's own date fields to their wire primitive (#72).
         applyNodeAttrEncoders(subRootAttrs, node.attrEncoders);
         // Inject context and discriminator
-        mergeContextValues(subRootAttrs, contextValues);
+        mergeContextValues(subRootAttrs, contextValues.stored);
         if (node.discriminator) {
             for (const [k, v] of Object.entries(node.discriminator)) {
                 if (typeof v !== "function")
@@ -1369,7 +1730,7 @@ const decomposeNode = (items, node, value, contextValues, parentGroup, parentDis
         const attrs = { ...value };
         // Serialize this edge entity's own date fields to their wire primitive (#72).
         applyNodeAttrEncoders(attrs, node.attrEncoders);
-        mergeContextValues(attrs, contextValues);
+        mergeContextValues(attrs, contextValues.stored);
         if (node.discriminator) {
             for (const [k, v] of Object.entries(node.discriminator)) {
                 if (typeof v !== "function")
@@ -1397,18 +1758,30 @@ const decomposeNode = (items, node, value, contextValues, parentGroup, parentDis
             : Array.isArray(value)
                 ? value
                 : [];
-        for (const elem of arrayItems) {
-            const attrs = { ...elem };
-            // Serialize this edge entity's own date fields to their wire primitive (#72).
-            applyNodeAttrEncoders(attrs, node.attrEncoders);
-            mergeContextValues(attrs, contextValues);
+        const withContext = (attrs, context) => {
+            mergeContextValues(attrs, context);
             if (node.discriminator) {
                 for (const [k, v] of Object.entries(node.discriminator)) {
                     if (typeof v !== "function")
                         attrs[k] = v;
                 }
             }
-            const itemComposites = yield* manyEdgeSkComposites(node, attrs, aggregateName);
+            return attrs;
+        };
+        for (const elem of arrayItems) {
+            // The element's attributes in their STORED form — every nested date,
+            // transformed scalar and hydrated ref encoded (#72, #133).
+            const attrs = { ...elem };
+            applyNodeAttrEncoders(attrs, node.attrEncoders);
+            withContext(attrs, contextValues.stored);
+            // The sort key is read from the element as the pre-#133 encoders left
+            // it, NOT from `attrs`: encoding a ref's nested `NumberFromString` turns
+            // a padded `0000000000000005` key segment into `5`, so composing from
+            // the stored form would re-spell (and orphan) existing rows.
+            const keyAttrs = { ...elem };
+            applyNodeAttrEncoders(keyAttrs, node.keyAttrEncoders);
+            withContext(keyAttrs, contextValues.key);
+            const itemComposites = yield* manyEdgeSkComposites(node, keyAttrs, aggregateName);
             items.push({
                 entityType: node.entityType,
                 attributes: attrs,
@@ -1593,7 +1966,7 @@ keyRecord, stamp) => groups.map((group) => ({
         }
         // List collection GSI keys (root items only)
         if (isRootItem && config.list) {
-            const listPkComposites = KeyComposer.extractComposites(config.list.pk.composite, keyRecord(item.attributes));
+            const listPkComposites = KeyComposer.extractComposites(config.list.pk.composite, keyRecord(item.keyAttributes ?? item.attributes));
             if (config.list.cardinality) {
                 const shard = hashToShard(pkValue, config.list.cardinality);
                 attrs[config.list.pk.field] = composeCollectionKey(config.schema, config.list.name, [
@@ -1604,7 +1977,7 @@ keyRecord, stamp) => groups.map((group) => ({
             else {
                 attrs[config.list.pk.field] = composeCollectionKey(config.schema, config.list.name, listPkComposites);
             }
-            const listSkComposites = KeyComposer.extractComposites(config.list.sk.composite, keyRecord(item.attributes));
+            const listSkComposites = KeyComposer.extractComposites(config.list.sk.composite, keyRecord(item.keyAttributes ?? item.attributes));
             attrs[config.list.sk.field] = composeCollectionKey(config.schema, config.list.name, listSkComposites);
         }
         // System timestamps — last, so a generated value wins over the same-named
@@ -1623,56 +1996,78 @@ keyRecord, stamp) => groups.map((group) => ({
         return toAttributeMap(attrs);
     }),
 }));
-// ---------------------------------------------------------------------------
-// Internal: Write transaction groups to DynamoDB
-// ---------------------------------------------------------------------------
-const writeTransactionGroups = (client, tableName, groups, aggregateName) => Effect.gen(function* () {
-    // Validate ALL group sizes BEFORE writing any group. Each group is its own
-    // transaction (DynamoDB: 100 items per TransactWriteItems), and the per-group
-    // count now spans Puts AND Deletes together — so an `update` that both adds and
-    // removes many edges roughly doubles the count. Checking up front means an
-    // oversized later group fails fast instead of partially committing earlier ones.
-    for (const group of groups) {
-        const itemCount = group.puts.length + group.deletes.length;
-        if (itemCount > 100) {
-            return yield* new AggregateTransactionOverflow({
-                aggregate: aggregateName,
-                subgraph: group.group,
-                itemCount,
-                limit: 100,
-            });
-        }
-    }
-    for (const group of groups) {
-        // Each group is one transaction — Puts AND Deletes applied atomically, so an
-        // edge add and a sibling edge removal in the same sub-aggregate commit together.
-        const itemCount = group.puts.length + group.deletes.length;
-        if (itemCount === 0)
-            continue;
-        // Build TransactWriteItems request — Puts first, then Deletes for orphans.
-        const transactItems = [
-            ...group.puts.map((item) => ({ Put: { TableName: tableName, Item: item } })),
-            ...group.deletes.map((key) => ({ Delete: { TableName: tableName, Key: key } })),
-        ];
-        yield* client.transactWriteItems({ TransactItems: transactItems }).pipe(Effect.mapError((error) => {
-            if (error.cause != null &&
-                typeof error.cause === "object" &&
-                "name" in error.cause &&
-                error.cause.name === "TransactionCanceledException") {
-                const cancelled = error.cause;
-                return new TransactionCancelled({
-                    operation: "TransactWriteItems",
-                    reasons: (cancelled.CancellationReasons ?? []).map((r) => ({
-                        code: r?.Code,
-                        message: r?.Message,
-                    })),
-                    cause: error.cause,
+function writeTransactionGroups(client, tableName, groups, aggregateName, rootGuard) {
+    return Effect.gen(function* () {
+        // Validate ALL group sizes BEFORE writing any group. Each group is its own
+        // transaction (DynamoDB: 100 items per TransactWriteItems), and the per-group
+        // count now spans Puts AND Deletes together — so an `update` that both adds and
+        // removes many edges roughly doubles the count. Checking up front means an
+        // oversized later group fails fast instead of partially committing earlier ones.
+        for (const group of groups) {
+            const itemCount = group.puts.length + group.deletes.length;
+            if (itemCount > 100) {
+                return yield* new AggregateTransactionOverflow({
+                    aggregate: aggregateName,
+                    subgraph: group.group,
+                    itemCount,
+                    limit: 100,
                 });
             }
-            return error;
-        }));
-    }
-});
+        }
+        for (const [groupIndex, group] of groups.entries()) {
+            // Each group is one transaction — Puts AND Deletes applied atomically, so an
+            // edge add and a sibling edge removal in the same sub-aggregate commit together.
+            const itemCount = group.puts.length + group.deletes.length;
+            if (itemCount === 0)
+                continue;
+            // The root item, in the first transaction only.
+            const rootIndex = rootGuard !== undefined && groupIndex === 0
+                ? group.puts.findIndex((item) => item.sk?.S === rootGuard.key.sk)
+                : -1;
+            // Build TransactWriteItems request — Puts first, then Deletes for orphans.
+            const transactItems = [
+                ...group.puts.map((item, i) => ({
+                    Put: {
+                        TableName: tableName,
+                        Item: item,
+                        ...(rootGuard !== undefined && i === rootIndex
+                            ? {
+                                ConditionExpression: "attribute_not_exists(#pk)",
+                                ExpressionAttributeNames: { "#pk": rootGuard.pkField },
+                            }
+                            : {}),
+                    },
+                })),
+                ...group.deletes.map((key) => ({ Delete: { TableName: tableName, Key: key } })),
+            ];
+            yield* client.transactWriteItems({ TransactItems: transactItems }).pipe(Effect.mapError((error) => {
+                if (error.cause != null &&
+                    typeof error.cause === "object" &&
+                    "name" in error.cause &&
+                    error.cause.name === "TransactionCanceledException") {
+                    const cancelled = error.cause;
+                    if (rootGuard !== undefined &&
+                        rootIndex >= 0 &&
+                        cancelled.CancellationReasons?.[rootIndex]?.Code === "ConditionalCheckFailed") {
+                        return new ConditionalCheckFailed({
+                            entityType: rootGuard.entityType,
+                            key: rootGuard.key,
+                        });
+                    }
+                    return new TransactionCancelled({
+                        operation: "TransactWriteItems",
+                        reasons: (cancelled.CancellationReasons ?? []).map((r) => ({
+                            code: r?.Code,
+                            message: r?.Message,
+                        })),
+                        cause: error.cause,
+                    });
+                }
+                return error;
+            }));
+        }
+    });
+}
 // ---------------------------------------------------------------------------
 // Internal: Delete all items in an aggregate partition
 // ---------------------------------------------------------------------------
@@ -1686,14 +2081,35 @@ const deleteAllItems = (client, tableName, allItems, pkField) => Effect.gen(func
             }),
         },
     }));
-    // Chunk into batches of 25 (DynamoDB batchWriteItem limit)
+    // Chunk into batches of 25 (DynamoDB batchWriteItem limit). Items DynamoDB
+    // leaves unprocessed (throttling) are retried with exponential backoff, as
+    // `Batch.write` retries them; a bounded number of retries, then a clear
+    // failure — never a silent partial delete (#134).
     for (let i = 0; i < deleteRequests.length; i += 25) {
-        const chunk = deleteRequests.slice(i, i + 25);
-        yield* client.batchWriteItem({
-            RequestItems: { [tableName]: chunk },
-        });
+        let pending = deleteRequests.slice(i, i + 25);
+        let retries = 0;
+        while (pending.length > 0) {
+            const response = yield* client.batchWriteItem({
+                RequestItems: { [tableName]: pending },
+            });
+            pending = (response.UnprocessedItems?.[tableName] ?? []);
+            if (pending.length === 0)
+                break;
+            retries++;
+            if (retries > DELETE_MAX_RETRIES) {
+                return yield* new DynamoError({
+                    operation: "BatchWriteItem",
+                    cause: new Error(`Aggregate delete: ${pending.length} unprocessed item(s) remain after ` +
+                        `${DELETE_MAX_RETRIES} retries; the partition is partly deleted.`),
+                });
+            }
+            yield* Effect.sleep(`${DELETE_BASE_DELAY_MS * 2 ** (retries - 1)} millis`);
+        }
     }
 });
+/** `Batch.write`'s bound and backoff, for `deleteAllItems`' unprocessed items. */
+const DELETE_MAX_RETRIES = 5;
+const DELETE_BASE_DELAY_MS = 100;
 // ---------------------------------------------------------------------------
 // Internal: list filter compilation
 // ---------------------------------------------------------------------------
@@ -1702,18 +2118,27 @@ const deleteAllItems = (client, tableName, allItems, pkField) => Effect.gen(func
  *
  * Both forms route through the same `Expr` compiler `BoundQuery.filter()` uses,
  * so `{ status: "shipped" }` and `(t, { eq }) => eq(t.status, "shipped")` mean
- * the same thing here as they do on an entity query. A shorthand with no
- * entries compiles to the empty string — that is a no-op, not `FilterExpression: ""`,
- * which DynamoDB rejects.
+ * the same thing here as they do on an entity query, under the same empty-part
+ * rules (#134): a filter that asserts nothing (`{}`, `and()`) is no filter, an
+ * empty part directly under `and` is left out, and one anywhere else — or an
+ * `or()` with no parts, or an `isIn` with no values — is refused with a
+ * `ValidationError` before anything is sent.
  */
-const compileListFilter = (filter) => {
+const compileListFilter = (filter, aggregateName) => {
     if (filter === undefined)
-        return undefined;
+        return Effect.succeed(undefined);
     const expr = typeof filter === "function"
         ? filter(createPathBuilder(), createConditionOps())
         : parseSimpleShorthand(filter);
-    const compiled = compileExpr(expr);
-    return compiled.expression === "" ? undefined : compiled;
+    const problem = emptyPartProblem(expr);
+    if (problem !== undefined) {
+        return Effect.fail(new ValidationError({
+            entityType: aggregateName,
+            operation: "list.filter",
+            cause: `list filter: ${problem} Nothing was sent.`,
+        }));
+    }
+    return Effect.succeed(isEmptyExpr(expr) ? undefined : compileExpr(expr));
 };
 /**
  * @internal DynamoDB `Limit` for the next request — the same rule `Query.ts`