effect-dynamodb 1.15.0 → 1.17.0

package/dist/Aggregate.js

@@ -11,13 +11,17 @@
 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 { 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 { DateTime, 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 { compileExpr, createConditionOps, parseSimpleShorthand, } from "./internal/Expr.js";
+import { createPathBuilder } from "./internal/PathBuilder.js";
 import { generateTimestampPrimitive } from "./internal/TransactableOps.js";
 import { fromAttributeMap, toAttributeMap, toAttributeValue } from "./Marshaller.js";
 import { resolvePrimaryKey } from "./Table.js";
@@ -96,38 +100,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)) {
@@ -140,7 +204,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)
@@ -169,7 +238,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
@@ -178,7 +247,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).
@@ -190,6 +259,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;
@@ -199,7 +269,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,
@@ -277,11 +360,23 @@ const makeAggregate = (schema, config) => {
     // 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 };
@@ -335,16 +430,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);
+            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, stampFor(now, EMPTY_CREATED));
+            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;
@@ -381,8 +479,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
@@ -410,8 +508,8 @@ const makeAggregate = (schema, config) => {
             //    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 ?? [], assembledNew), stampFor(now, readExistingCreated(allItems)));
-            const oldDynamo = buildDynamoItems(oldGroups, config, pkValue, KeyComposer.extractComposites(config.collection.sk?.composite ?? [], assembledOld));
+            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]));
@@ -474,38 +572,98 @@ const makeAggregate = (schema, config) => {
             }
             const listConfig = config.list;
             const limit = options?.limit;
-            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
+            const pageSize = options?.pageSize;
+            // 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);
+            // 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
+            // on the LAST page, where the surplus still has to be re-read next time.
+            const listKeyFields = Array.from(new Set([
+                tablePrimary?.pk ?? config.pk.field,
+                tablePrimary?.sk ?? "sk",
+                listConfig.pk.field,
+                listConfig.sk.field,
+            ]));
+            // 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)
             }
             let rootItems;
             let nextKey;
             if (listConfig.cardinality) {
-                // Fan out: query each shard in parallel, merge results
-                // Pagination not supported for sharded lists — returns all results
+                // A sharded list is a fan-out over N independent partitions, and a
+                // DynamoDB cursor addresses a position in ONE of them. Resuming would
+                // need a per-shard cursor set plus a defined global merge order, which
+                // this fan-out does not have (results are concatenated shard by shard).
+                // Rejecting is the honest answer — the previous behaviour accepted the
+                // cursor and restarted from the beginning, silently.
+                if (options?.cursor !== undefined) {
+                    return yield* new ValidationError({
+                        entityType: aggregateName,
+                        operation: "list",
+                        cause: `[EDD-9051] Aggregate "${aggregateName}" has a sharded list ` +
+                            `(list.cardinality = ${listConfig.cardinality}), and a sharded fan-out has no ` +
+                            "resumable cursor: a DynamoDB cursor names a position in one partition, while " +
+                            "this query spans all of them with no defined order across shards. `list` on a " +
+                            "sharded aggregate always returns `cursor: null`; use `limit` to bound the " +
+                            "result, or drop `list.cardinality` if the partition needs paging more than it " +
+                            "needs spreading.",
+                    });
+                }
+                // Fan out across shards and merge. `limit` bounds each shard too — no
+                // single shard can contribute more than the whole page.
                 const shardQueries = Array.from({ length: listConfig.cardinality }, (_, shard) => {
                     const shardPkValue = composeCollectionKey(config.schema, listConfig.name, [
                         ...listPkComposites,
                         String(shard),
                     ]);
-                    return queryListPartition(client, tableConfig, listConfig, config.schema, shardPkValue, skValues);
+                    return queryListPartition(client, tableConfig, listConfig, config.schema, {
+                        pkValue: shardPkValue,
+                        skValues,
+                        limit,
+                        pageSize,
+                        filter: rootFilter,
+                        reverse: options?.reverse === true,
+                        keyFields: listKeyFields,
+                    });
                 });
                 const shardResults = yield* Effect.all(shardQueries);
-                rootItems = shardResults.flatMap((r) => r.items);
+                const merged = shardResults.flatMap((r) => r.items);
+                // Truncate the merged fan-out to `limit`. Previously the option was
+                // accepted and discarded, so a large aggregate set returned everything.
+                rootItems = limit === undefined ? merged : merged.slice(0, limit);
                 nextKey = undefined;
             }
             else {
+                const startKey = options?.cursor
+                    ? JSON.parse(atob(options.cursor))
+                    : undefined;
                 const listPkValue = composeCollectionKey(config.schema, listConfig.name, listPkComposites);
-                const result = yield* queryListPartition(client, tableConfig, listConfig, config.schema, listPkValue, skValues, limit, startKey);
+                const result = yield* queryListPartition(client, tableConfig, listConfig, config.schema, {
+                    pkValue: listPkValue,
+                    skValues,
+                    limit,
+                    pageSize,
+                    startKey,
+                    filter: rootFilter,
+                    reverse: options?.reverse === true,
+                    keyFields: listKeyFields,
+                });
                 rootItems = result.items;
                 nextKey = result.lastKey;
             }
@@ -593,10 +751,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) {
@@ -605,19 +761,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);
             }
         }
@@ -632,7 +816,9 @@ const resolveNode = (fieldName, entityType, cardinality, edges, discriminator, a
         children,
         ...(assemble !== undefined && { assemble }),
         ...(decompose !== undefined && { decompose }),
-        dateEncoders,
+        ...(skComposite !== undefined && { skComposite }),
+        ...(refIdentifierField !== undefined && { refIdentifierField }),
+        attrEncoders,
     };
 };
 // ---------------------------------------------------------------------------
@@ -1051,7 +1237,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,
@@ -1060,7 +1246,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
@@ -1070,7 +1256,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({
@@ -1078,12 +1264,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) {
@@ -1129,7 +1340,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) {
@@ -1143,6 +1354,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) {
@@ -1154,7 +1366,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)) {
@@ -1173,6 +1385,7 @@ const decomposeNode = (items, node, value, contextValues, parentGroup, parentDis
             attributes: attrs,
             transactionGroup: parentGroup,
             skComposites: [...parentDiscriminatorValues, ...ownDiscValues],
+            member: node.fieldName ?? node.entityType,
         });
     }
     else {
@@ -1185,7 +1398,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)) {
@@ -1193,22 +1406,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)) {
@@ -1227,9 +1527,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;
 };
@@ -1253,7 +1561,14 @@ const EMPTY_CREATED = new Map();
  * on every comparison and silently collapse the diff into a full-partition
  * rewrite on every update (#98).
  */
-const buildDynamoItems = (groups, config, pkValue, rootCollectionSkComposites, stamp) => groups.map((group) => ({
+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).
+ */
+keyRecord, stamp) => groups.map((group) => ({
     group: group.name,
     items: group.items.map((item) => {
         const attrs = { ...item.attributes };
@@ -1276,7 +1591,7 @@ const buildDynamoItems = (groups, config, pkValue, rootCollectionSkComposites, s
         }
         // 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, [
@@ -1287,7 +1602,7 @@ const buildDynamoItems = (groups, config, pkValue, rootCollectionSkComposites, s
             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
@@ -1377,7 +1692,60 @@ const deleteAllItems = (client, tableName, allItems, pkField) => Effect.gen(func
         });
     }
 });
-const queryListPartition = (client, tableConfig, listConfig, schema, pkValue, skValues, limit, startKey) => Effect.gen(function* () {
+// ---------------------------------------------------------------------------
+// Internal: list filter compilation
+// ---------------------------------------------------------------------------
+/**
+ * @internal Compile a {@link ListFilter} to a `FilterExpression` fragment.
+ *
+ * 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.
+ */
+const compileListFilter = (filter) => {
+    if (filter === undefined)
+        return undefined;
+    const expr = typeof filter === "function"
+        ? filter(createPathBuilder(), createConditionOps())
+        : parseSimpleShorthand(filter);
+    const compiled = compileExpr(expr);
+    return compiled.expression === "" ? undefined : compiled;
+};
+/**
+ * @internal DynamoDB `Limit` for the next request — the same rule `Query.ts`
+ * applies, and for the same reason: `Limit` bounds rows EXAMINED, and a
+ * `FilterExpression` runs after, so under a filter `limit` cannot be expressed
+ * as `Limit` at all. `pageSize` (or, unset, a natural 1 MB page) is the budget
+ * then, and the loop keeps asking until the page fills.
+ */
+const listRequestLimit = (options, remaining) => {
+    if (remaining === undefined)
+        return options.pageSize;
+    if (options.filter !== undefined)
+        return options.pageSize;
+    return options.pageSize === undefined ? remaining : Math.min(options.pageSize, remaining);
+};
+/**
+ * @internal Rebuild a resume key from an item the query returned. Every item
+ * carries its table key and index key as ordinary attributes, so any item can
+ * address itself. Returns `undefined` if a name is missing.
+ */
+const listKeyFromItem = (item, names) => {
+    if (names.length === 0)
+        return undefined;
+    const key = {};
+    for (const name of names) {
+        const value = item[name];
+        if (value === undefined)
+            return undefined;
+        key[name] = value;
+    }
+    return key;
+};
+const queryListPartition = (client, tableConfig, listConfig, schema, options) => Effect.gen(function* () {
+    const { filter, limit, pkValue, skValues } = options;
     const exprNames = { "#pk": listConfig.pk.field };
     const exprValues = { ":pk": toAttributeValue(pkValue) };
     let keyCondition = "#pk = :pk";
@@ -1387,28 +1755,51 @@ const queryListPartition = (client, tableConfig, listConfig, schema, pkValue, sk
         exprValues[":skPrefix"] = toAttributeValue(skPrefix);
         keyCondition += " AND begins_with(#sk, :skPrefix)";
     }
+    if (filter !== undefined) {
+        Object.assign(exprNames, filter.names);
+        Object.assign(exprValues, filter.values);
+    }
+    if (limit !== undefined && limit <= 0)
+        return { items: [], lastKey: undefined };
     const items = [];
-    let lastKey = startKey;
-    do {
+    let startKey = options.startKey;
+    let lastKey;
+    for (;;) {
+        const remaining = limit === undefined ? undefined : limit - items.length;
+        const requestLimit = listRequestLimit(options, remaining);
         const result = yield* client.query({
             TableName: tableConfig.name,
             IndexName: listConfig.index,
             KeyConditionExpression: keyCondition,
             ExpressionAttributeNames: exprNames,
             ExpressionAttributeValues: exprValues,
-            ExclusiveStartKey: lastKey,
-            ...(limit !== undefined ? { Limit: limit - items.length } : {}),
+            ExclusiveStartKey: startKey,
+            ...(filter !== undefined ? { FilterExpression: filter.expression } : {}),
+            ...(requestLimit !== undefined ? { Limit: requestLimit } : {}),
+            ...(options.reverse === true ? { ScanIndexForward: false } : {}),
         });
-        if (result.Items) {
-            for (const item of result.Items) {
-                items.push(fromAttributeMap(item));
-            }
+        const returned = (result.Items ?? []);
+        const lastEvaluatedKey = result.LastEvaluatedKey;
+        const take = remaining === undefined ? returned.length : Math.min(remaining, returned.length);
+        for (let i = 0; i < take; i++)
+            items.push(fromAttributeMap(returned[i]));
+        // Over-read — a filtered request returns whatever survives the filter, not
+        // `Limit` rows. The surplus is dropped, so `LastEvaluatedKey` (the last row
+        // EXAMINED) would skip past items the caller never saw. Resume from the
+        // last item actually handed back instead.
+        if (take < returned.length) {
+            lastKey =
+                listKeyFromItem(returned[take - 1], lastEvaluatedKey != null ? Object.keys(lastEvaluatedKey) : options.keyFields) ?? lastEvaluatedKey;
+            break;
         }
-        lastKey = result.LastEvaluatedKey;
-        // Stop when we've collected enough items
-        if (limit !== undefined && items.length >= limit)
+        const exhausted = lastEvaluatedKey == null;
+        const limitReached = limit !== undefined && items.length >= limit;
+        if (exhausted || limitReached) {
+            lastKey = lastEvaluatedKey;
             break;
-    } while (lastKey !== undefined);
+        }
+        startKey = lastEvaluatedKey;
+    }
     return { items, lastKey };
 });
 //# sourceMappingURL=Aggregate.js.map