effect-dynamodb 1.14.0 → 1.16.0

package/dist/Aggregate.js

@@ -11,13 +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, AggregateTransactionOverflow, RefNotFound, TransactionCancelled, ValidationError, } from "@effect-dynamodb/schema/Errors.js";
-import { buildDateTransform, matchDateRepresentation, substituteSchemaDeep, validateNoTransformOverride, } from "@effect-dynamodb/schema/internal/EntitySchemas.js";
+import { AggregateAssemblyError, AggregateDecompositionError, AggregateTransactionOverflow, 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 * as KeyComposer from "@effect-dynamodb/schema/KeyComposer.js";
-import { Effect, Schema, SchemaAST } from "effect";
+import { DateTime, Effect, Option, Schema, SchemaAST } from "effect";
 import * as Batch from "./Batch.js";
 import { DynamoClient } from "./DynamoClient.js";
 import { fromDefinition as entityFromDefinition } from "./Entity.js";
+import { generateTimestampPrimitive } from "./internal/TransactableOps.js";
 import { fromAttributeMap, toAttributeMap, toAttributeValue } from "./Marshaller.js";
 import { resolvePrimaryKey } from "./Table.js";
 // Internal modules (decomposed from Aggregate.ts)
@@ -95,38 +98,98 @@ const inferDateEncoding = (ast) => {
     return undefined;
 };
 /**
- * Build per-field date ENCODERS for a schema's own date fields. Encoders convert
- * a domain date value to its wire primitive on the WRITE path — decompose works
- * from the schema-decoded domain object, so EVERY date field (Pattern A self-date
- * AND Pattern B transform) must serialize for storage. The READ path is handled
- * entirely by the aggregate's tolerant `decodeSchema` (see `makeAggregate`), so
- * no separate decoders are needed.
+ * 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
+ * through `inputSchema`.
+ *
+ * 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.
+ *
+ * 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
+ *    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.
  */
-const buildDateEncoders = (fields) => {
+const buildAttrEncoders = (fields) => {
     const encoders = {};
-    if (fields) {
-        for (const field of Object.keys(fields)) {
-            const fieldSchema = fields[field];
-            // Precedence: explicit `DynamoModel.storedAs` annotation > inferred default
-            // for standard Effect date schemas (handles `Schema.optional()` wrappers).
-            const encoding = DynamoModel.getEncoding(fieldSchema) ?? inferDateEncoding(fieldSchema.ast);
-            if (!encoding)
-                continue;
+    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);
+            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))
+            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);
+        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;
+        };
     }
     return encoders;
 };
-/** A schema's declared fields, if it exposes them (Schema.Struct / Schema.Class). */
-const fieldsOf = (schema) => schema?.fields;
+/**
+ * A schema's declared fields, if it exposes them (Schema.Struct / Schema.Class).
+ *
+ * Unwraps `DynamoModel.configure(...)` first: that returns a `{ model, attributes }`
+ * WRAPPER, not a schema, so reading `.fields` off it yields nothing. An edge
+ * entity declared with a configured model therefore got NO encoders at all —
+ * its dates marshalled as `{M:{...}}` and its transformed fields as their Type
+ * values, on every row of that edge. Configured models are the norm (any
+ * `identifier: true` / `field:` rename produces one), so this blind spot covered
+ * most real edges.
+ */
+const fieldsOf = (schema) => {
+    const source = DynamoModel.isConfiguredModel(schema) ? schema.model : schema;
+    return source?.fields;
+};
 /**
  * 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).
  */
-const applyNodeDateEncoders = (attrs, encoders) => {
+const applyNodeAttrEncoders = (attrs, encoders) => {
     if (!encoders)
         return;
     for (const [field, encode] of Object.entries(encoders)) {
@@ -139,7 +202,12 @@ const applyNodeDateEncoders = (attrs, encoders) => {
 // ---------------------------------------------------------------------------
 const makeAggregate = (schema, config) => {
     // Build resolved graph by walking edges recursively
-    const rootNode = resolveNode(null, config.root.entityType, "root", config.edges);
+    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)
@@ -168,7 +236,7 @@ const makeAggregate = (schema, config) => {
     // 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 dateEncoders = buildDateEncoders(schemaFields);
+    const attrEncoders = buildAttrEncoders(schemaFields);
     // 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
@@ -177,7 +245,7 @@ const makeAggregate = (schema, config) => {
     //   - 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 `dateEncoders` / node encoders.
+    //     stored wire format is still produced by `attrEncoders` / node 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).
@@ -189,6 +257,7 @@ const makeAggregate = (schema, config) => {
     // `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;
@@ -198,7 +267,20 @@ const makeAggregate = (schema, config) => {
         const model = entity?.model;
         if (!model)
             continue;
-        edgeRefModels.set(edgeName, DynamoModel.isConfiguredModel(model) ? model.model : model);
+        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));
+            }
+        }
     }
     const decodeSchema = substituteSchemaDeep(schema, {
         tolerantTransforms: true,
@@ -234,14 +316,65 @@ const makeAggregate = (schema, config) => {
             `eventually consistent only. Drop \`consistentRead\`, or key the aggregate on the ` +
             `table's primary partition key so assembly reads the base table.`);
     }
+    // System timestamps (#98). Aggregates compose their DynamoDB items directly
+    // rather than routing through Entity write ops, so Entity's timestamp
+    // machinery never reached these rows. Resolution goes through the SAME
+    // resolver as Entity, which means field names, `DynamoModel` storage
+    // annotations and the EDD-9044 guard on an un-annotated `schema` all behave
+    // identically here. Passing the root schema's fields also inherits Entity's
+    // collision rule: a date-compatible root field of the same name supplies the
+    // encoding, and a non-date one means the user owns the attribute outright.
+    const timestampFields = resolveSystemFields(config.timestamps, undefined, undefined, schemaFields ?? {}, {}, `Aggregate "${aggregateName}"`);
+    const stampFields = timestampFields.createdAt !== null || timestampFields.updatedAt !== null
+        ? {
+            createdAt: timestampFields.createdAt,
+            createdEncoding: timestampFields.createdAtEncoding,
+            updatedAt: timestampFields.updatedAt,
+            updatedEncoding: timestampFields.updatedAtEncoding,
+        }
+        : undefined;
+    // Attributes the read path must drop before decoding. A field the root model
+    // declares itself is NOT stripped — it belongs to the domain object.
+    const systemAttrs = new Set([
+        timestampFields.createdAtCollision ? null : timestampFields.createdAt,
+        timestampFields.updatedAtCollision ? null : timestampFields.updatedAt,
+    ].filter((name) => name !== null));
+    /** Read stored `created` values back, keyed by sk, so a rewrite preserves them. */
+    const readExistingCreated = (allItems) => {
+        const createdField = stampFields?.createdAt;
+        if (createdField === undefined || createdField === null)
+            return EMPTY_CREATED;
+        const map = new Map();
+        for (const item of allItems) {
+            const sk = item.sk;
+            const prior = item[createdField];
+            if (typeof sk === "string" && prior !== undefined)
+                map.set(sk, prior);
+        }
+        return map;
+    };
+    /** Bind the per-write stamp: config + the Clock-backed instant + carry-forward. */
+    const stampFor = (now, existingCreated) => stampFields === undefined ? undefined : { fields: stampFields, now, existingCreated };
     // Build optics at construction time (once per aggregate definition)
     const classToPlain = Schema.toIso(schema);
     const opticRoot = Schema.toIsoFocus(schema);
+    // 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
+    // ISO form here and its epoch form on the entity path, and a numeric
+    // composite with a string encoding would not be zero-padded on either.
+    const compositeKeyForm = makeCompositeKeyForm(schema, (attr, value) => {
+        throw new Error(`[EDD-9050] Composite "${attr}" on aggregate "${aggregateName}" could not be put into ` +
+            `its key form. The attribute's schema carries an encoding transformation, but ` +
+            `${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);
     /** Shared: compose PK and query all items */
     const fetchPartition = (key) => Effect.gen(function* () {
         const client = yield* DynamoClient;
         const tableConfig = yield* config.table.Tag;
-        const composites = KeyComposer.extractComposites(config.pk.composite, key);
+        const composites = KeyComposer.extractComposites(config.pk.composite, keyRecord(key));
         const pkValue = composeCollectionKey(config.schema, config.collection.name, composites);
         const allItems = yield* queryAllItems(client, tableConfig.name, config.collection.index, config.pk.field, pkValue, consistentRead);
         return { client, tableConfig, pkValue, composites, allItems };
@@ -277,7 +410,7 @@ const makeAggregate = (schema, config) => {
                     key,
                 });
             }
-            const result = yield* assembleAggregate(decodeSchema, rootNode, allItems, contextFields, key, aggregateName);
+            const result = yield* assembleAggregate(decodeSchema, rootNode, allItems, contextFields, key, aggregateName, systemAttrs);
             return result;
         }),
         create: (input) => Effect.gen(function* () {
@@ -295,14 +428,19 @@ const makeAggregate = (schema, config) => {
             })));
             const assembled = { ...decoded };
             // 3. Compose PK
-            const composites = KeyComposer.extractComposites(config.pk.composite, assembled);
+            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, dateEncoders, aggregateName);
-            // 5. Compose collection SK composites for root item
-            const collectionSkComposites = KeyComposer.extractComposites(config.collection.sk?.composite ?? [], assembled);
-            // 6. Build DynamoDB items with composed keys (create only ever PUTs)
-            const dynamoGroups = buildDynamoItems(groups, config, pkValue, collectionSkComposites);
+            const groups = yield* decomposeAggregate(assembled, rootNode, contextFields, attrEncoders, 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
+            // differently for a transformed composite.
+            const collectionSkComposites = KeyComposer.extractComposites(config.collection.sk?.composite ?? [], keyRecord(assembled));
+            // 6. Build DynamoDB items with composed keys (create only ever PUTs).
+            //    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);
             return decoded;
@@ -317,7 +455,7 @@ const makeAggregate = (schema, config) => {
                 });
             }
             // 1. Assemble current state
-            const current = yield* assembleAggregate(decodeSchema, rootNode, allItems, contextFields, key, aggregateName);
+            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 updated = mutationFn({
@@ -339,8 +477,8 @@ const makeAggregate = (schema, config) => {
             const assembledOld = { ...current };
             const assembledNew = { ...decoded };
             // 4. Decompose both old and new
-            const oldGroups = yield* decomposeAggregate(assembledOld, rootNode, contextFields, dateEncoders, aggregateName);
-            const newGroups = yield* decomposeAggregate(assembledNew, rootNode, contextFields, dateEncoders, aggregateName);
+            const oldGroups = yield* decomposeAggregate(assembledOld, rootNode, contextFields, attrEncoders, aggregateName, config.schema);
+            const newGroups = yield* decomposeAggregate(assembledNew, rootNode, contextFields, attrEncoders, 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
@@ -363,8 +501,13 @@ const makeAggregate = (schema, config) => {
             //    collection SK composites only affect the LSI/GSI mirror attributes,
             //    never the (pk, sk) identity used to PUT or DELETE, so the old set's
             //    composites are irrelevant — we read only its (pk, sk) for deletes.
-            const newDynamo = buildDynamoItems(newGroups, config, pkValue, KeyComposer.extractComposites(config.collection.sk?.composite ?? [], assembledNew));
-            const oldDynamo = buildDynamoItems(oldGroups, config, pkValue, KeyComposer.extractComposites(config.collection.sk?.composite ?? [], assembledOld));
+            //    Rewritten rows are stamped `updated`; their stored `created` is read
+            //    back off the fetched partition and re-emitted verbatim, since these are
+            //    PUTs and would otherwise clobber it. The old set is only mined for
+            //    (pk, sk) delete keys, so it is never stamped.
+            const now = yield* DateTime.now;
+            const newDynamo = buildDynamoItems(newGroups, config, pkValue, KeyComposer.extractComposites(config.collection.sk?.composite ?? [], keyRecord(assembledNew)), keyRecord, stampFor(now, readExistingCreated(allItems)));
+            const oldDynamo = buildDynamoItems(oldGroups, config, pkValue, KeyComposer.extractComposites(config.collection.sk?.composite ?? [], keyRecord(assembledOld)), keyRecord);
             const skOf = (item) => item.sk?.S ?? "";
             const newItemsByGroup = new Map(newDynamo.map((g) => [g.group, g.items]));
             const oldItemsByGroup = new Map(oldDynamo.map((g) => [g.group, g.items]));
@@ -430,13 +573,19 @@ const makeAggregate = (schema, config) => {
             const startKey = options?.cursor
                 ? JSON.parse(atob(options.cursor))
                 : undefined;
-            // Compose PK from filter values matching PK composites
-            const listPkComposites = KeyComposer.extractComposites(listConfig.pk.composite, filter ?? {});
-            // Build SK prefix from contiguous filter values matching SK composites
+            // Compose PK from filter values matching PK composites. The filter is a
+            // DOMAIN record, so it goes through the same key form the write side
+            // used — otherwise `list` composes a key `create` never wrote and
+            // silently returns nothing (#111).
+            const listPkComposites = KeyComposer.extractComposites(listConfig.pk.composite, keyRecord(filter ?? {}));
+            // Build SK prefix from contiguous filter values matching SK composites.
+            // `serializeValue`, NOT `String(v)` — the write side pads numerics, so
+            // `String(5)` would look for `5` where `0000000000000005` is stored.
             const skValues = [];
+            const listSkFilter = keyRecord(filter ?? {});
             for (const attr of listConfig.sk.composite) {
-                if (filter?.[attr] !== undefined)
-                    skValues.push(String(filter[attr]));
+                if (listSkFilter[attr] !== undefined)
+                    skValues.push(KeyComposer.serializeValue(listSkFilter[attr]));
                 else
                     break; // Stop at first gap (prefix matching)
             }
@@ -473,7 +622,7 @@ const makeAggregate = (schema, config) => {
                     const { allItems } = yield* fetchPartition(key);
                     if (allItems.length === 0)
                         return undefined;
-                    const result = yield* assembleAggregate(decodeSchema, rootNode, allItems, contextFields, key, aggregateName);
+                    const result = yield* assembleAggregate(decodeSchema, rootNode, allItems, contextFields, key, aggregateName, systemAttrs);
                     return result;
                 });
                 if (assembled !== undefined)
@@ -546,10 +695,8 @@ const deepEqualGroups = (a, b) => {
         return deepEqual(item.attributes, other.attributes);
     });
 };
-// ---------------------------------------------------------------------------
-// Internal: Resolve the graph
-// ---------------------------------------------------------------------------
-const resolveNode = (fieldName, entityType, cardinality, edges, discriminator, assemble, decompose, ownDiscriminator, dateEncoders) => {
+const resolveNode = (args) => {
+    const { assemble, cardinality, attrEncoders, decompose, discriminator, edges, entityType, fieldName, ownDiscriminator, refIdentifierField, skComposite, } = args;
     const children = [];
     for (const [field, edge] of Object.entries(edges)) {
         if ("_tag" in edge) {
@@ -558,19 +705,47 @@ const resolveNode = (fieldName, entityType, cardinality, edges, discriminator, a
                 const mergedDisc = edge.discriminator
                     ? { ...(discriminator ?? {}), ...edge.discriminator }
                     : discriminator;
-                children.push(resolveNode(field, edge.entityType, "one", {}, mergedDisc, undefined, undefined, edge.discriminator, 
-                // Encode this edge entity's own date fields on write (issue #72).
-                buildDateEncoders(fieldsOf(edge.entity?.model))));
+                children.push(resolveNode({
+                    fieldName: field,
+                    entityType: edge.entityType,
+                    cardinality: "one",
+                    edges: {},
+                    discriminator: mergedDisc,
+                    ownDiscriminator: edge.discriminator,
+                    // Encode this edge entity's own date fields on write (issue #72).
+                    attrEncoders: buildAttrEncoders(fieldsOf(edge.entity?.model)),
+                }));
             }
             else if (edge._tag === "ManyEdge") {
-                children.push(resolveNode(field, edge.entityType, "many", {}, discriminator, edge.assemble, edge.decompose, undefined, buildDateEncoders(fieldsOf(edge.entity?.model))));
+                children.push(resolveNode({
+                    fieldName: field,
+                    entityType: edge.entityType,
+                    cardinality: "many",
+                    edges: {},
+                    discriminator,
+                    assemble: edge.assemble,
+                    decompose: edge.decompose,
+                    attrEncoders: buildAttrEncoders(fieldsOf(edge.entity?.model)),
+                    // Declared sort-key composites, authoritative when present (#103).
+                    skComposite: edge.sk?.composite,
+                    refIdentifierField: edge.entity
+                        ? DynamoModel.getIdentifierField(edge.entity.model)?.name
+                        : undefined,
+                }));
             }
             else if (edge._tag === "BoundSubAggregate") {
                 const bound = edge;
-                const subChildren = resolveNode(field, bound.aggregate.root.entityType, "one", bound.aggregate.edges, bound.discriminator, undefined, undefined, 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.
-                buildDateEncoders(fieldsOf(bound.aggregate.schema)));
+                const subChildren = resolveNode({
+                    fieldName: field,
+                    entityType: bound.aggregate.root.entityType,
+                    cardinality: "one",
+                    edges: bound.aggregate.edges,
+                    discriminator: bound.discriminator,
+                    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)),
+                });
                 children.push(subChildren);
             }
         }
@@ -585,7 +760,9 @@ const resolveNode = (fieldName, entityType, cardinality, edges, discriminator, a
         children,
         ...(assemble !== undefined && { assemble }),
         ...(decompose !== undefined && { decompose }),
-        dateEncoders,
+        ...(skComposite !== undefined && { skComposite }),
+        ...(refIdentifierField !== undefined && { refIdentifierField }),
+        attrEncoders,
     };
 };
 // ---------------------------------------------------------------------------
@@ -619,7 +796,9 @@ const queryAllItems = (client, tableName, indexName, pkField, pkValue, consisten
 // ---------------------------------------------------------------------------
 // Internal: Assembly algorithm
 // ---------------------------------------------------------------------------
-const assembleAggregate = (decodeSchema, rootNode, allItems, _contextFields, key, aggregateName) => Effect.gen(function* () {
+const assembleAggregate = (decodeSchema, rootNode, allItems, _contextFields, key, aggregateName, 
+/** Library-managed attribute names (system timestamps) to drop before decode. */
+systemAttrs = EMPTY_ATTRS) => Effect.gen(function* () {
     // Find the root item
     const rootItems = allItems.filter((item) => item.__edd_e__ === rootNode.entityType);
     if (rootItems.length === 0) {
@@ -640,7 +819,7 @@ const assembleAggregate = (decodeSchema, rootNode, allItems, _contextFields, key
     // Assemble edge values from the item collection
     const edgeValues = {};
     for (const child of rootNode.children) {
-        const assembled = yield* assembleNode(child, allItems, key, aggregateName);
+        const assembled = yield* assembleNode(child, allItems, key, aggregateName, systemAttrs);
         if (child.fieldName !== null && assembled !== undefined) {
             edgeValues[child.fieldName] = assembled;
         }
@@ -664,6 +843,7 @@ const assembleAggregate = (decodeSchema, rootNode, allItems, _contextFields, key
         "gsi5sk",
         "lsi1sk",
         "lsi2sk",
+        ...systemAttrs,
     ]);
     for (const [fieldKey, value] of Object.entries(rootItem)) {
         if (metaFields.has(fieldKey))
@@ -684,7 +864,7 @@ const assembleAggregate = (decodeSchema, rootNode, allItems, _contextFields, key
     })));
     return decoded;
 });
-const assembleNode = (node, allItems, key, aggregateName) => Effect.gen(function* () {
+const assembleNode = (node, allItems, key, aggregateName, systemAttrs = EMPTY_ATTRS) => Effect.gen(function* () {
     // Find items matching this node's entity type and discriminator
     const matchingItems = allItems.filter((item) => {
         if (item.__edd_e__ !== node.entityType)
@@ -722,7 +902,7 @@ const assembleNode = (node, allItems, key, aggregateName) => Effect.gen(function
                 const childNode = node.discriminator
                     ? { ...child, discriminator: { ...node.discriminator, ...child.discriminator } }
                     : child;
-                const assembled = yield* assembleNode(childNode, allItems, key, aggregateName);
+                const assembled = yield* assembleNode(childNode, allItems, key, aggregateName, systemAttrs);
                 if (child.fieldName !== null && assembled !== undefined) {
                     edgeValues[child.fieldName] = assembled;
                 }
@@ -738,6 +918,8 @@ const assembleNode = (node, allItems, key, aggregateName) => Effect.gen(function
                     continue;
                 if (fieldKey.startsWith("gsi") || fieldKey.startsWith("lsi"))
                     continue;
+                if (systemAttrs.has(fieldKey))
+                    continue;
                 if (edgeFieldNames.has(fieldKey))
                     continue;
                 // Skip discriminator attributes
@@ -753,10 +935,10 @@ const assembleNode = (node, allItems, key, aggregateName) => Effect.gen(function
             return undefined;
         // Return the item (stripped of DynamoDB metadata)
         const item = matchingItems[0];
-        return stripMetadata(item);
+        return stripMetadata(item, systemAttrs);
     }
     // Many edge: collect all matching items
-    const stripped = matchingItems.map(stripMetadata);
+    const stripped = matchingItems.map((item) => stripMetadata(item, systemAttrs));
     if (node.assemble) {
         return node.assemble(stripped);
     }
@@ -765,7 +947,8 @@ const assembleNode = (node, allItems, key, aggregateName) => Effect.gen(function
 // ---------------------------------------------------------------------------
 // Internal: Strip DynamoDB metadata from items
 // ---------------------------------------------------------------------------
-const stripMetadata = (item) => {
+const EMPTY_ATTRS = new Set();
+const stripMetadata = (item, systemAttrs = EMPTY_ATTRS) => {
     const result = {};
     for (const [key, value] of Object.entries(item)) {
         if (key === "__edd_e__")
@@ -774,6 +957,8 @@ const stripMetadata = (item) => {
             continue;
         if (key.startsWith("gsi") || key.startsWith("lsi"))
             continue;
+        if (systemAttrs.has(key))
+            continue;
         result[key] = value;
     }
     return result;
@@ -996,7 +1181,7 @@ const replaceRefIds = (input, refRequests, lookup) => {
  * Decompose an assembled domain object into DynamoDB items grouped by
  * sub-aggregate transaction boundaries.
  */
-const decomposeAggregate = (assembled, rootNode, contextFields, dateEncoders, aggregateName) => Effect.gen(function* () {
+const decomposeAggregate = (assembled, rootNode, contextFields, attrEncoders, aggregateName, schema) => Effect.gen(function* () {
     const items = [];
     // Extract context values from the root, serializing date fields for DynamoDB storage.
     // Domain Date/DateTime objects must be encoded before toAttributeMap() marshalling,
@@ -1005,7 +1190,7 @@ const decomposeAggregate = (assembled, rootNode, contextFields, dateEncoders, ag
     const contextValues = {};
     for (const field of contextFields) {
         const value = assembled[field];
-        const encode = dateEncoders[field];
+        const encode = attrEncoders[field];
         contextValues[field] = encode && value != null ? encode(value) : value;
     }
     // Root item: fields not claimed by edges
@@ -1015,7 +1200,7 @@ const decomposeAggregate = (assembled, rootNode, contextFields, dateEncoders, ag
         if (edgeFieldNames.has(key))
             continue;
         // Serialize date fields in root attributes (same as context values)
-        const encode = dateEncoders[key];
+        const encode = attrEncoders[key];
         rootAttrs[key] = encode && value != null ? encode(value) : value;
     }
     items.push({
@@ -1023,12 +1208,37 @@ const decomposeAggregate = (assembled, rootNode, contextFields, dateEncoders, ag
         attributes: rootAttrs,
         transactionGroup: "root",
         skComposites: [],
+        member: rootNode.entityType,
     });
     // Decompose each edge
     for (const child of rootNode.children) {
         const fieldValue = assembled[child.fieldName];
         yield* decomposeNode(items, child, fieldValue, contextValues, "root", [], aggregateName);
     }
+    // Two items composing the same sort key are two writes to one row. DynamoDB
+    // rejects the whole TransactWriteItems with a ValidationException ("Transaction
+    // request cannot include multiple operations on one item") that names no edge,
+    // and carries no CancellationReasons — so `writeTransactionGroups` cannot
+    // decode it and the collision reaches the caller as an opaque client error.
+    // Catch it here, where the edge that produced it is still known (#103).
+    const seen = new Map();
+    for (const item of items) {
+        const sk = composeKey(schema, item.entityType, [...item.skComposites]);
+        const prior = seen.get(sk);
+        if (prior !== undefined) {
+            const hint = prior.member === item.member
+                ? ` Give the "${item.member}" edge a declared sort key naming attributes that differ` +
+                    ` between its elements: Aggregate.many("${item.member}", { …, sk: { composite: [...] } }).`
+                : "";
+            return yield* new AggregateDecompositionError({
+                aggregate: aggregateName,
+                member: item.member,
+                reason: `"${prior.member}" and "${item.member}" both compose the sort key "${sk}", ` +
+                    `so one would overwrite the other.${hint}`,
+            });
+        }
+        seen.set(sk, item);
+    }
     // Group by transaction
     const groups = new Map();
     for (const item of items) {
@@ -1074,7 +1284,7 @@ const decomposeNode = (items, node, value, contextValues, parentGroup, parentDis
             subRootAttrs[key] = val;
         }
         // Serialize this node's own date fields to their wire primitive (#72).
-        applyNodeDateEncoders(subRootAttrs, node.dateEncoders);
+        applyNodeAttrEncoders(subRootAttrs, node.attrEncoders);
         // Inject context and discriminator
         mergeContextValues(subRootAttrs, contextValues);
         if (node.discriminator) {
@@ -1088,6 +1298,7 @@ const decomposeNode = (items, node, value, contextValues, parentGroup, parentDis
             attributes: subRootAttrs,
             transactionGroup: txGroup,
             skComposites: discValues,
+            member: node.fieldName ?? node.entityType,
         });
         // Decompose children within this sub-aggregate
         for (const child of node.children) {
@@ -1099,7 +1310,7 @@ const decomposeNode = (items, node, value, contextValues, parentGroup, parentDis
         // Simple one-to-one edge (no children)
         const attrs = { ...value };
         // Serialize this edge entity's own date fields to their wire primitive (#72).
-        applyNodeDateEncoders(attrs, node.dateEncoders);
+        applyNodeAttrEncoders(attrs, node.attrEncoders);
         mergeContextValues(attrs, contextValues);
         if (node.discriminator) {
             for (const [k, v] of Object.entries(node.discriminator)) {
@@ -1118,6 +1329,7 @@ const decomposeNode = (items, node, value, contextValues, parentGroup, parentDis
             attributes: attrs,
             transactionGroup: parentGroup,
             skComposites: [...parentDiscriminatorValues, ...ownDiscValues],
+            member: node.fieldName ?? node.entityType,
         });
     }
     else {
@@ -1130,7 +1342,7 @@ const decomposeNode = (items, node, value, contextValues, parentGroup, parentDis
         for (const elem of arrayItems) {
             const attrs = { ...elem };
             // Serialize this edge entity's own date fields to their wire primitive (#72).
-            applyNodeDateEncoders(attrs, node.dateEncoders);
+            applyNodeAttrEncoders(attrs, node.attrEncoders);
             mergeContextValues(attrs, contextValues);
             if (node.discriminator) {
                 for (const [k, v] of Object.entries(node.discriminator)) {
@@ -1138,22 +1350,109 @@ const decomposeNode = (items, node, value, contextValues, parentGroup, parentDis
                         attrs[k] = v;
                 }
             }
-            // Extract ref identifiers for SK composites
-            const itemComposites = extractRefIdentifiers(attrs);
+            const itemComposites = yield* manyEdgeSkComposites(node, attrs, aggregateName);
             items.push({
                 entityType: node.entityType,
                 attributes: attrs,
                 transactionGroup: parentGroup,
                 skComposites: [...parentDiscriminatorValues, ...itemComposites],
+                member: node.fieldName ?? node.entityType,
             });
         }
     }
 });
+/**
+ * Read one declared sk composite off a decomposed element.
+ *
+ * Dotted paths are supported because ref hydration REPLACES the id field with the
+ * hydrated object — an input element `{ contactId, role }` decomposes to
+ * `{ contact: { contactId, … }, role }`, so the referenced entity's identifier is
+ * only reachable as `"contact.contactId"`.
+ */
+const readCompositePath = (attrs, path) => {
+    if (!path.includes("."))
+        return attrs[path];
+    let current = attrs;
+    for (const segment of path.split(".")) {
+        if (current == null || typeof current !== "object")
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+};
+/**
+ * Whether a resolved composite value can be a sort-key segment.
+ *
+ * `KeyComposer.serializeValue` falls through to `String(value)`, so an object
+ * reaches the key as `[object Object]` or, for a Schema.Class instance, its
+ * whole JSON body. Either is silently wrong and unqueryable — and naming the
+ * ref object (`"umpire"`) instead of a scalar path (`"umpire.id"`) is the easy
+ * mistake to make, precisely because the dotted path is the unfamiliar part.
+ */
+const isScalarComposite = (value) => {
+    switch (typeof value) {
+        case "string":
+        case "number":
+        case "bigint":
+        case "boolean":
+            return true;
+        case "object":
+            return value instanceof Date || DateTime.isDateTime(value);
+        default:
+            return false;
+    }
+};
+/**
+ * Sort-key composites for one element of a `many` edge.
+ *
+ * A declared `sk.composite` is AUTHORITATIVE — it replaces the ref-identifier
+ * heuristic rather than extending it, so both the uniqueness and the ordering of
+ * an edge's elements are the user's to state (#103). Without one, uniqueness is
+ * bounded by the referenced entity's identifier and the same entity cannot appear
+ * twice in one aggregate.
+ *
+ * Resolution never throws: a declared attribute that is missing or null is a
+ * modelling error, reported as an {@link AggregateDecompositionError} naming the
+ * edge and the attributes, not a defect escaping the decompose walk.
+ */
+const manyEdgeSkComposites = (node, attrs, aggregateName) => Effect.gen(function* () {
+    const declared = node.skComposite;
+    if (declared === undefined)
+        return extractRefIdentifiers(attrs, node.refIdentifierField);
+    const values = declared.map((path) => readCompositePath(attrs, path));
+    const missing = declared.filter((_, i) => values[i] == null);
+    if (missing.length > 0) {
+        return yield* new AggregateDecompositionError({
+            aggregate: aggregateName,
+            member: node.fieldName ?? node.entityType,
+            reason: `sk.composite names ${missing.map((m) => `"${m}"`).join(", ")}, ` +
+                `${missing.length === 1 ? "which is" : "which are"} missing from the element. ` +
+                `A referenced entity's identifier is reachable by dotted path after hydration ` +
+                `(e.g. "contact.contactId", not "contactId").`,
+        });
+    }
+    const nonScalar = declared.filter((_, i) => !isScalarComposite(values[i]));
+    if (nonScalar.length > 0) {
+        return yield* new AggregateDecompositionError({
+            aggregate: aggregateName,
+            member: node.fieldName ?? node.entityType,
+            reason: `sk.composite names ${nonScalar.map((m) => `"${m}"`).join(", ")}, ` +
+                `${nonScalar.length === 1 ? "which resolves" : "which resolve"} to a non-scalar value. ` +
+                `A sort key segment must be a string, number, bigint, boolean or date — name the ` +
+                `attribute itself by dotted path (e.g. "umpire.id", not "umpire").`,
+        });
+    }
+    return values.map((value) => KeyComposer.serializeValue(value));
+});
 /**
  * Extract ref identifier values from an item's attributes for use as SK composites.
  * Walks fields looking for embedded objects that have an identifier-annotated field.
+ *
+ * A heuristic, and order-dependent: it takes each nested object's `id` (else its
+ * first `*Id` key) in property order. Declaring `sk.composite` on the edge opts
+ * out of it entirely — see {@link manyEdgeSkComposites}.
  */
-const extractRefIdentifiers = (attrs) => {
+const extractRefIdentifiers = (attrs, refIdentifierField) => {
     const ids = [];
     // Case 1: Element wraps entity — look for nested objects with id-like fields
     for (const [, value] of Object.entries(attrs)) {
@@ -1172,9 +1471,17 @@ const extractRefIdentifiers = (attrs) => {
             }
         }
     }
-    // Case 2: Element IS entity — top-level id field (e.g., Umpire with { id: "ump-1", ... })
-    if (ids.length === 0 && typeof attrs.id === "string") {
-        ids.push(attrs.id);
+    // Case 2: Element IS entity — the entity's own fields are flat, so there is no
+    // nested object for case 1 to find. Prefer the edge entity's declared
+    // `DynamoModel.identifier` field; fall back to a literal `id` for edges with no
+    // entity. Without this an `Array(Player)` edge composes NO composites and every
+    // element collapses onto one row (#103).
+    if (ids.length === 0) {
+        const declared = refIdentifierField !== undefined ? attrs[refIdentifierField] : undefined;
+        if (typeof declared === "string")
+            ids.push(declared);
+        else if (typeof attrs.id === "string")
+            ids.push(attrs.id);
     }
     return ids;
 };
@@ -1188,13 +1495,24 @@ const hashToShard = (value, cardinality) => {
     }
     return Math.abs(hash) % cardinality;
 };
-// ---------------------------------------------------------------------------
-// Internal: Compose DynamoDB items from decomposed data
-// ---------------------------------------------------------------------------
+const EMPTY_CREATED = new Map();
 /**
  * Convert decomposed items into DynamoDB attribute maps with composed keys.
+ *
+ * `stamp` is applied HERE rather than in `decomposeAggregate` on purpose: update
+ * diffs the decomposed groups (`deepEqualGroups`) to decide which sub-aggregate
+ * transactions to rewrite, so a timestamp mixed into decomposition would differ
+ * on every comparison and silently collapse the diff into a full-partition
+ * rewrite on every update (#98).
+ */
+const buildDynamoItems = (groups, config, pkValue, rootCollectionSkComposites, 
+/**
+ * The aggregate's composite key-form normaliser. Required, not optional: the
+ * list-GSI keys composed below have to be spelled exactly as `Aggregate.list`
+ * spells them when it reads, and the only way to guarantee that is for both
+ * to go through the same function (#111).
  */
-const buildDynamoItems = (groups, config, pkValue, rootCollectionSkComposites) => groups.map((group) => ({
+keyRecord, stamp) => groups.map((group) => ({
     group: group.name,
     items: group.items.map((item) => {
         const attrs = { ...item.attributes };
@@ -1217,7 +1535,7 @@ const buildDynamoItems = (groups, config, pkValue, rootCollectionSkComposites) =
         }
         // List collection GSI keys (root items only)
         if (isRootItem && config.list) {
-            const listPkComposites = KeyComposer.extractComposites(config.list.pk.composite, item.attributes);
+            const listPkComposites = KeyComposer.extractComposites(config.list.pk.composite, keyRecord(item.attributes));
             if (config.list.cardinality) {
                 const shard = hashToShard(pkValue, config.list.cardinality);
                 attrs[config.list.pk.field] = composeCollectionKey(config.schema, config.list.name, [
@@ -1228,9 +1546,22 @@ const buildDynamoItems = (groups, config, pkValue, rootCollectionSkComposites) =
             else {
                 attrs[config.list.pk.field] = composeCollectionKey(config.schema, config.list.name, listPkComposites);
             }
-            const listSkComposites = KeyComposer.extractComposites(config.list.sk.composite, item.attributes);
+            const listSkComposites = KeyComposer.extractComposites(config.list.sk.composite, keyRecord(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
+        // field propagated onto edge items via `context`.
+        if (stamp) {
+            const { existingCreated, fields, now } = stamp;
+            const sk = attrs.sk;
+            if (fields.createdAt !== null) {
+                const prior = existingCreated.get(sk);
+                attrs[fields.createdAt] = prior ?? generateTimestampPrimitive(now, fields.createdEncoding);
+            }
+            if (fields.updatedAt !== null) {
+                attrs[fields.updatedAt] = generateTimestampPrimitive(now, fields.updatedEncoding);
+            }
+        }
         return toAttributeMap(attrs);
     }),
 }));