effect-dynamodb 0.1.0

package/dist/Aggregate.js

@@ -0,0 +1,1169 @@
+/**
+ * Aggregate — Graph-based composite domain model for DynamoDB.
+ *
+ * An Aggregate binds a Schema.Class hierarchy to a graph of underlying entities
+ * sharing a partition key. The read path queries the collection, discriminates
+ * items by entity type + discriminators, and assembles them leaves-to-root into
+ * a Schema.Class instance.
+ *
+ * Created via {@link make}. Sub-aggregates compose recursively via `.with()`.
+ */
+import { Effect, Schema, SchemaAST } from "effect";
+import * as Batch from "./Batch.js";
+import { DynamoClient } from "./DynamoClient.js";
+import * as DynamoModel from "./DynamoModel.js";
+import { composeCollectionKey, composeKey } from "./DynamoSchema.js";
+import { AggregateAssemblyError, AggregateTransactionOverflow, RefNotFound, TransactionCancelled, ValidationError, } from "./Errors.js";
+import * as KeyComposer from "./KeyComposer.js";
+import { deserializeDateFromDynamo, fromAttributeMap, serializeDateForDynamo, toAttributeMap, toAttributeValue, } from "./Marshaller.js";
+// Internal modules (decomposed from Aggregate.ts)
+export { isManyEdge, isOneEdge, isRefEdge, many, one, ref, } from "./internal/AggregateEdges.js";
+export { deriveAggregateSchemas, deriveElementInputSchema, deriveEntityFieldName, extractArrayElement, getSchemaFields, isFieldOptional, isSchemaMatchingEntity, unwrapModel, } from "./internal/AggregateSchemas.js";
+import { makeCursor, } from "./internal/AggregateCursor.js";
+import { deriveAggregateSchemas, deriveEntityFieldName } from "./internal/AggregateSchemas.js";
+// ---------------------------------------------------------------------------
+// TypeId
+// ---------------------------------------------------------------------------
+export const TypeId = Symbol.for("effect-dynamodb/Aggregate");
+export function make(schema, config) {
+    if (!("table" in config) || config.table === undefined) {
+        // Sub-aggregate form
+        return makeSubAggregate(schema, config);
+    }
+    // Top-level form
+    return makeAggregate(schema, config);
+}
+// ---------------------------------------------------------------------------
+// Sub-aggregate construction
+// ---------------------------------------------------------------------------
+const makeSubAggregate = (schema, config) => {
+    const sub = {
+        _tag: "SubAggregate",
+        schema,
+        root: config.root,
+        edges: config.edges,
+        with: (discConfig) => ({
+            _tag: "BoundSubAggregate",
+            aggregate: sub,
+            discriminator: discConfig.discriminator,
+        }),
+    };
+    return sub;
+};
+/**
+ * Try to match a date encoding from a SchemaAST.resolve() result.
+ * SchemaAST.resolve flattens annotations to the top level (typeConstructor, meta).
+ */
+const matchResolvedDateAST = (resolved) => {
+    const tc = resolved.typeConstructor;
+    if (tc?._tag === "effect/DateTime.Utc")
+        return { storage: "string", domain: "DateTime.Utc" };
+    if (tc?._tag === "effect/DateTime.Zoned")
+        return { storage: "string", domain: "DateTime.Zoned" };
+    if (tc?._tag === "Date")
+        return { storage: "string", domain: "Date" };
+    const meta = resolved.meta;
+    if (meta?._tag === "isDateValid")
+        return { storage: "string", domain: "Date" };
+    return undefined;
+};
+/**
+ * Try to match a date encoding from a raw AST member (Union type member).
+ * Raw AST nodes have annotations nested under .annotations (not flattened).
+ */
+const matchRawDateAST = (node) => {
+    const ann = node.annotations;
+    if (!ann)
+        return undefined;
+    const tc = ann.typeConstructor;
+    if (tc?._tag === "effect/DateTime.Utc")
+        return { storage: "string", domain: "DateTime.Utc" };
+    if (tc?._tag === "effect/DateTime.Zoned")
+        return { storage: "string", domain: "DateTime.Zoned" };
+    if (tc?._tag === "Date")
+        return { storage: "string", domain: "Date" };
+    const meta = ann.meta;
+    if (meta?._tag === "isDateValid")
+        return { storage: "string", domain: "Date" };
+    return undefined;
+};
+/**
+ * Infer date encoding from a schema AST, handling Schema.optional() wrappers.
+ * Optional fields have Union AST with [InnerType, Undefined] — unwrap to find dates.
+ */
+const inferDateEncoding = (ast) => {
+    // Try SchemaAST.resolve first (works for non-optional date fields)
+    const resolved = SchemaAST.resolve(ast);
+    if (resolved) {
+        const direct = matchResolvedDateAST(resolved);
+        if (direct)
+            return direct;
+    }
+    // Handle optional wrapper: Union with Undefined + inner type.
+    // SchemaAST.resolve returns undefined for Union ASTs, so check the raw AST.
+    const rawAst = ast;
+    if (rawAst._tag === "Union" && rawAst.types) {
+        for (const member of rawAst.types) {
+            if (member._tag === "Undefined")
+                continue;
+            // Try SchemaAST.resolve on the inner member (e.g., Declaration for Schema.Date)
+            const memberResolved = SchemaAST.resolve(member);
+            if (memberResolved) {
+                const enc = matchResolvedDateAST(memberResolved);
+                if (enc)
+                    return enc;
+            }
+            // Fallback: check raw member annotations
+            const enc = matchRawDateAST(member);
+            if (enc)
+                return enc;
+        }
+    }
+    return undefined;
+};
+// ---------------------------------------------------------------------------
+// Top-level aggregate construction
+// ---------------------------------------------------------------------------
+const makeAggregate = (schema, config) => {
+    // Build resolved graph by walking edges recursively
+    const rootNode = resolveNode(null, config.root.entityType, "root", config.edges);
+    const aggregateName = config.root.entityType;
+    const contextFields = config.context ?? [];
+    // Detect date encodings for all root schema fields (once, at make() time).
+    // Fields with Date/DateTime types need serialization before DynamoDB
+    // marshalling and deserialization before Schema decode, matching Entity's
+    // serializeDateFields/deserializeDateFields pattern.
+    const dateEncodings = {};
+    const schemaFields = schema.fields;
+    if (schemaFields) {
+        for (const field of Object.keys(schemaFields)) {
+            const fieldSchema = schemaFields[field];
+            const explicit = DynamoModel.getEncoding(fieldSchema);
+            if (explicit) {
+                dateEncodings[field] = explicit;
+            }
+            else {
+                // Infer for standard Effect date schemas (Schema.Date, DateTime, etc.)
+                // For optional fields (Union with Undefined), unwrap to find the inner type.
+                const inferred = inferDateEncoding(fieldSchema.ast);
+                if (inferred)
+                    dateEncodings[field] = inferred;
+            }
+        }
+    }
+    // Build optics at construction time (once per aggregate definition)
+    const classToPlain = Schema.toIso(schema);
+    const opticRoot = Schema.toIsoFocus(schema);
+    /** 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 pkValue = composeCollectionKey(config.schema, config.collection.name, composites);
+        const allItems = yield* queryAllItems(client, tableConfig.name, config.collection.index, config.pk.field, pkValue);
+        return { client, tableConfig, pkValue, composites, allItems };
+    });
+    const derivedSchemas = deriveAggregateSchemas(schema, config.edges, config.pk.composite);
+    return {
+        [TypeId]: TypeId,
+        _tag: "Aggregate",
+        _tableTag: config.table.Tag,
+        schema,
+        pkField: config.pk.field,
+        collection: {
+            index: config.collection.index,
+            sk: { field: config.collection.sk.field },
+        },
+        listIndex: config.list
+            ? {
+                index: config.list.index,
+                pk: { field: config.list.pk.field },
+                sk: { field: config.list.sk.field },
+            }
+            : undefined,
+        inputSchema: derivedSchemas.inputSchema,
+        createSchema: derivedSchemas.inputSchema,
+        updateSchema: derivedSchemas.updateSchema,
+        get: (key) => Effect.gen(function* () {
+            const { allItems } = yield* fetchPartition(key);
+            if (allItems.length === 0) {
+                return yield* new AggregateAssemblyError({
+                    aggregate: aggregateName,
+                    reason: "No items found for aggregate key",
+                    key,
+                });
+            }
+            const result = yield* assembleAggregate(schema, rootNode, allItems, contextFields, dateEncodings, key, aggregateName);
+            return result;
+        }),
+        create: (input) => Effect.gen(function* () {
+            const client = yield* DynamoClient;
+            const tableConfig = yield* config.table.Tag;
+            // 1. Hydrate refs from edges
+            const hydrated = yield* hydrateAggregateRefs(input, config.edges, aggregateName);
+            // 2. Validate via schema decode
+            const decoded = yield* Schema.decodeUnknownEffect(schema)(hydrated).pipe(Effect.mapError((cause) => new ValidationError({
+                entityType: aggregateName,
+                operation: "aggregate.create",
+                cause,
+            })));
+            const assembled = { ...decoded };
+            // 3. Compose PK
+            const composites = KeyComposer.extractComposites(config.pk.composite, 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, dateEncodings, 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
+            const dynamoGroups = buildDynamoItems(groups, config, pkValue, collectionSkComposites);
+            // 7. Write via sub-aggregate transactions
+            yield* writeTransactionGroups(client, tableConfig.name, dynamoGroups, aggregateName);
+            return decoded;
+        }),
+        update: (key, mutationFn) => Effect.gen(function* () {
+            const { client, tableConfig, pkValue, allItems } = yield* fetchPartition(key);
+            if (allItems.length === 0) {
+                return yield* new AggregateAssemblyError({
+                    aggregate: aggregateName,
+                    reason: "No items found for aggregate key",
+                    key,
+                });
+            }
+            // 1. Assemble current state
+            const current = yield* assembleAggregate(schema, rootNode, allItems, contextFields, dateEncodings, key, aggregateName);
+            // 2. Apply mutation — provide optics context for composable updates
+            const state = classToPlain.get(current);
+            const updated = mutationFn({
+                state,
+                cursor: makeCursor(state, opticRoot),
+                optic: opticRoot,
+                current: current,
+            });
+            // 3. Validate updated state via schema decode
+            const decoded = yield* Schema.decodeUnknownEffect(schema)(updated).pipe(Effect.mapError((cause) => new ValidationError({
+                entityType: aggregateName,
+                operation: "aggregate.update",
+                cause,
+            })));
+            const assembledOld = { ...current };
+            const assembledNew = { ...decoded };
+            // 4. Decompose both old and new
+            const oldGroups = yield* decomposeAggregate(assembledOld, rootNode, contextFields, dateEncodings, aggregateName);
+            const newGroups = yield* decomposeAggregate(assembledNew, rootNode, contextFields, dateEncodings, aggregateName);
+            // 5. Diff: determine which transaction groups changed
+            const oldGroupMap = new Map(oldGroups.map((g) => [g.name, g]));
+            const newGroupMap = new Map(newGroups.map((g) => [g.name, g]));
+            // Check if context fields changed — if so, ALL groups must be rewritten
+            let contextChanged = false;
+            for (const field of contextFields) {
+                if (!deepEqual(assembledOld[field], assembledNew[field])) {
+                    contextChanged = true;
+                    break;
+                }
+            }
+            const groupsToWrite = [];
+            for (const [name, newGroup] of newGroupMap) {
+                if (contextChanged) {
+                    groupsToWrite.push(newGroup);
+                    continue;
+                }
+                const oldGroup = oldGroupMap.get(name);
+                if (!oldGroup || !deepEqualGroups(oldGroup, newGroup)) {
+                    groupsToWrite.push(newGroup);
+                }
+            }
+            if (groupsToWrite.length > 0) {
+                // 6. Compose collection SK composites
+                const collectionSkComposites = KeyComposer.extractComposites(config.collection.sk.composite, assembledNew);
+                // 7. Build and write changed groups
+                const dynamoGroups = buildDynamoItems(groupsToWrite, config, pkValue, collectionSkComposites);
+                yield* writeTransactionGroups(client, tableConfig.name, dynamoGroups, aggregateName);
+            }
+            return decoded;
+        }),
+        delete: (key) => Effect.gen(function* () {
+            const { client, tableConfig, allItems } = yield* fetchPartition(key);
+            if (allItems.length === 0) {
+                return yield* new AggregateAssemblyError({
+                    aggregate: aggregateName,
+                    reason: "No items found for aggregate key",
+                    key,
+                });
+            }
+            yield* deleteAllItems(client, tableConfig.name, allItems, config.pk.field);
+        }),
+        list: (filter, options) => Effect.gen(function* () {
+            const client = yield* DynamoClient;
+            const tableConfig = yield* config.table.Tag;
+            if (!config.list) {
+                return yield* new ValidationError({
+                    entityType: aggregateName,
+                    operation: "list",
+                    cause: "Aggregate.list() requires a `list` collection config. " +
+                        "Define `list: { index, name, pk, sk }` in your aggregate 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 skValues = [];
+            for (const attr of listConfig.sk.composite) {
+                if (filter?.[attr] !== undefined)
+                    skValues.push(String(filter[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
+                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);
+                });
+                const shardResults = yield* Effect.all(shardQueries);
+                rootItems = shardResults.flatMap((r) => r.items);
+                nextKey = undefined;
+            }
+            else {
+                const listPkValue = composeCollectionKey(config.schema, listConfig.name, listPkComposites);
+                const result = yield* queryListPartition(client, tableConfig, listConfig, config.schema, listPkValue, skValues, limit, startKey);
+                rootItems = result.items;
+                nextKey = result.lastKey;
+            }
+            // Extract PK composite values from each root item and assemble
+            const aggregates = [];
+            for (const rootItem of rootItems) {
+                const key = {};
+                for (const composite of config.pk.composite) {
+                    key[composite] = rootItem[composite];
+                }
+                const assembled = yield* Effect.gen(function* () {
+                    const { allItems } = yield* fetchPartition(key);
+                    if (allItems.length === 0)
+                        return undefined;
+                    const result = yield* assembleAggregate(schema, rootNode, allItems, contextFields, dateEncodings, key, aggregateName);
+                    return result;
+                });
+                if (assembled !== undefined)
+                    aggregates.push(assembled);
+            }
+            const cursor = nextKey ? btoa(JSON.stringify(nextKey)) : null;
+            return { data: aggregates, cursor };
+        }),
+    };
+};
+// ---------------------------------------------------------------------------
+// Aggregate binding — resolve services, return BoundAggregate with R = never
+// ---------------------------------------------------------------------------
+/**
+ * Bind an Aggregate to resolved `DynamoClient` and `TableConfig` services.
+ * Returns a {@link BoundAggregate} where all operations have `R = never`.
+ *
+ * @internal Used by `DynamoClient.make()` to bind aggregates.
+ */
+export const bind = (aggregate) => Effect.gen(function* () {
+    const ctx = yield* Effect.context();
+    const provide = (effect) => Effect.provide(effect, ctx);
+    return {
+        schema: aggregate.schema,
+        get: (key) => provide(aggregate.get(key)),
+        create: (input) => provide(aggregate.create(input)),
+        update: (key, mutationFn) => provide(aggregate.update(key, mutationFn)),
+        delete: (key) => provide(aggregate.delete(key)),
+        list: (filter, options) => provide(aggregate.list(filter, options)),
+        inputSchema: aggregate.inputSchema,
+        createSchema: aggregate.createSchema,
+        updateSchema: aggregate.updateSchema,
+        provide,
+    };
+});
+// ---------------------------------------------------------------------------
+// Internal: Deep equality helpers for diff-based update
+// ---------------------------------------------------------------------------
+const deepEqual = (a, b) => {
+    if (a === b)
+        return true;
+    if (a == null || b == null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== "object")
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((item, i) => deepEqual(item, b[i]));
+    }
+    if (Array.isArray(a) || Array.isArray(b))
+        return false;
+    const aObj = a;
+    const bObj = b;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((k) => deepEqual(aObj[k], bObj[k]));
+};
+const deepEqualGroups = (a, b) => {
+    if (a.items.length !== b.items.length)
+        return false;
+    return a.items.every((item, i) => {
+        const other = b.items[i];
+        if (item.entityType !== other.entityType)
+            return false;
+        return deepEqual(item.attributes, other.attributes);
+    });
+};
+// ---------------------------------------------------------------------------
+// Internal: Resolve the graph
+// ---------------------------------------------------------------------------
+const resolveNode = (fieldName, entityType, cardinality, edges, discriminator, assemble, decompose, ownDiscriminator) => {
+    const children = [];
+    for (const [field, edge] of Object.entries(edges)) {
+        if ("_tag" in edge) {
+            if (edge._tag === "OneEdge") {
+                // Merge parent discriminator with edge's own discriminator
+                const mergedDisc = edge.discriminator
+                    ? { ...(discriminator ?? {}), ...edge.discriminator }
+                    : discriminator;
+                children.push(resolveNode(field, edge.entityType, "one", {}, mergedDisc, undefined, undefined, edge.discriminator));
+            }
+            else if (edge._tag === "ManyEdge") {
+                children.push(resolveNode(field, edge.entityType, "many", {}, discriminator, edge.assemble, edge.decompose));
+            }
+            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);
+                children.push(subChildren);
+            }
+        }
+    }
+    return {
+        fieldName,
+        entityType,
+        cardinality,
+        discriminator,
+        ownDiscriminator,
+        children,
+        assemble,
+        decompose,
+    };
+};
+// ---------------------------------------------------------------------------
+// Internal: Query all items in the aggregate partition
+// ---------------------------------------------------------------------------
+const queryAllItems = (client, tableName, indexName, pkField, pkValue) => Effect.gen(function* () {
+    const allItems = [];
+    let exclusiveStartKey;
+    // Paginate through all results
+    do {
+        const result = yield* client.query({
+            TableName: tableName,
+            IndexName: indexName,
+            KeyConditionExpression: "#pk = :pk",
+            ExpressionAttributeNames: { "#pk": pkField },
+            ExpressionAttributeValues: { ":pk": toAttributeValue(pkValue) },
+            ExclusiveStartKey: exclusiveStartKey,
+        });
+        if (result.Items) {
+            for (const item of result.Items) {
+                allItems.push(fromAttributeMap(item));
+            }
+        }
+        exclusiveStartKey = result.LastEvaluatedKey;
+    } while (exclusiveStartKey !== undefined);
+    return allItems;
+});
+// ---------------------------------------------------------------------------
+// Internal: Assembly algorithm
+// ---------------------------------------------------------------------------
+const assembleAggregate = (schema, rootNode, allItems, _contextFields, dateEncodings, key, aggregateName) => Effect.gen(function* () {
+    // Find the root item
+    const rootItems = allItems.filter((item) => item.__edd_e__ === rootNode.entityType);
+    if (rootItems.length === 0) {
+        return yield* new AggregateAssemblyError({
+            aggregate: aggregateName,
+            reason: "Missing root item",
+            key,
+        });
+    }
+    if (rootItems.length > 1) {
+        return yield* new AggregateAssemblyError({
+            aggregate: aggregateName,
+            reason: "Multiple root items found",
+            key,
+        });
+    }
+    const rootItem = rootItems[0];
+    // Assemble edge values from the item collection
+    const edgeValues = {};
+    for (const child of rootNode.children) {
+        const assembled = yield* assembleNode(child, allItems, key, aggregateName);
+        if (child.fieldName !== null && assembled !== undefined) {
+            edgeValues[child.fieldName] = assembled;
+        }
+    }
+    // Combine root item fields (minus DynamoDB metadata + context) with assembled edges
+    const rootFields = {};
+    const edgeFieldNames = new Set(rootNode.children.map((c) => c.fieldName).filter(Boolean));
+    const metaFields = new Set([
+        "__edd_e__",
+        "pk",
+        "sk",
+        "gsi1pk",
+        "gsi1sk",
+        "gsi2pk",
+        "gsi2sk",
+        "gsi3pk",
+        "gsi3sk",
+        "gsi4pk",
+        "gsi4sk",
+        "gsi5pk",
+        "gsi5sk",
+        "lsi1sk",
+        "lsi2sk",
+    ]);
+    for (const [fieldKey, value] of Object.entries(rootItem)) {
+        if (metaFields.has(fieldKey))
+            continue;
+        if (edgeFieldNames.has(fieldKey))
+            continue;
+        rootFields[fieldKey] = value;
+    }
+    // Deserialize date context fields from DynamoDB storage primitives to domain values.
+    // Schema.decodeUnknownEffect expects domain types (Date, DateTime), not encoded strings.
+    for (const [field, encoding] of Object.entries(dateEncodings)) {
+        if (field in rootFields && rootFields[field] != null) {
+            rootFields[field] = deserializeDateFromDynamo(rootFields[field], encoding);
+        }
+    }
+    // Merge root fields with assembled edge values
+    const assembled = { ...rootFields, ...edgeValues };
+    // Decode through the aggregate's Schema.Class
+    const decoded = yield* Schema.decodeUnknownEffect(schema)(assembled).pipe(Effect.mapError((cause) => new ValidationError({
+        entityType: aggregateName,
+        operation: "aggregate.assemble",
+        cause,
+    })));
+    return decoded;
+});
+const assembleNode = (node, allItems, key, aggregateName) => Effect.gen(function* () {
+    // Find items matching this node's entity type and discriminator
+    const matchingItems = allItems.filter((item) => {
+        if (item.__edd_e__ !== node.entityType)
+            return false;
+        // If this node has a discriminator, check that item attributes match
+        if (node.discriminator) {
+            for (const [attr, value] of Object.entries(node.discriminator)) {
+                // Skip computed discriminators (functions) — only match on static values
+                if (typeof value === "function")
+                    continue;
+                if (item[attr] !== value)
+                    return false;
+            }
+        }
+        return true;
+    });
+    if (node.cardinality === "one") {
+        // One-to-one: sub-aggregate root or simple one edge
+        if (node.children.length > 0) {
+            // Sub-aggregate — assemble recursively
+            // If no matching items found, return undefined (supports optional sub-aggregates)
+            if (matchingItems.length === 0)
+                return undefined;
+            if (matchingItems.length > 1) {
+                return yield* new AggregateAssemblyError({
+                    aggregate: aggregateName,
+                    reason: `Multiple sub-aggregate root items for "${node.fieldName}" (entityType: ${node.entityType})`,
+                    key,
+                });
+            }
+            const subRootItem = matchingItems[0];
+            const edgeValues = {};
+            for (const child of node.children) {
+                // For children within a sub-aggregate, propagate the parent's discriminator
+                const childNode = node.discriminator
+                    ? { ...child, discriminator: { ...node.discriminator, ...child.discriminator } }
+                    : child;
+                const assembled = yield* assembleNode(childNode, allItems, key, aggregateName);
+                if (child.fieldName !== null && assembled !== undefined) {
+                    edgeValues[child.fieldName] = assembled;
+                }
+            }
+            // Build sub-aggregate result: sub-root fields + assembled edges
+            const subFields = {};
+            const edgeFieldNames = new Set(node.children.map((c) => c.fieldName).filter(Boolean));
+            for (const [fieldKey, value] of Object.entries(subRootItem)) {
+                // Skip DynamoDB metadata, discriminator attributes, and edge fields
+                if (fieldKey === "__edd_e__")
+                    continue;
+                if (fieldKey.startsWith("pk") || fieldKey.startsWith("sk"))
+                    continue;
+                if (fieldKey.startsWith("gsi") || fieldKey.startsWith("lsi"))
+                    continue;
+                if (edgeFieldNames.has(fieldKey))
+                    continue;
+                // Skip discriminator attributes
+                if (node.discriminator && fieldKey in node.discriminator)
+                    continue;
+                subFields[fieldKey] = value;
+            }
+            return { ...subFields, ...edgeValues };
+        }
+        // Simple one-to-one edge — if no matching items, return undefined
+        // (the Schema decode will catch truly required missing fields)
+        if (matchingItems.length === 0)
+            return undefined;
+        // Return the item (stripped of DynamoDB metadata)
+        const item = matchingItems[0];
+        return stripMetadata(item);
+    }
+    // Many edge: collect all matching items
+    const stripped = matchingItems.map(stripMetadata);
+    if (node.assemble) {
+        return node.assemble(stripped);
+    }
+    return stripped;
+});
+// ---------------------------------------------------------------------------
+// Internal: Strip DynamoDB metadata from items
+// ---------------------------------------------------------------------------
+const stripMetadata = (item) => {
+    const result = {};
+    for (const [key, value] of Object.entries(item)) {
+        if (key === "__edd_e__")
+            continue;
+        if (key === "pk" || key === "sk")
+            continue;
+        if (key.startsWith("gsi") || key.startsWith("lsi"))
+            continue;
+        result[key] = value;
+    }
+    return result;
+};
+/**
+ * Walk the input recursively following graph edges, collect ref IDs,
+ * fetch referenced entities, and replace IDs with hydrated domain data.
+ */
+const hydrateAggregateRefs = (input, edges, aggregateName) => Effect.gen(function* () {
+    // Collect all ref IDs from the entire input hierarchy
+    const refRequests = [];
+    collectRefIdsFromEdges(refRequests, input, edges, []);
+    if (refRequests.length === 0)
+        return input;
+    // Group by entity type for efficient fetching
+    const byEntityType = new Map();
+    for (const req of refRequests) {
+        const key = req.entity.entityType;
+        const existing = byEntityType.get(key);
+        if (existing) {
+            existing.reqs.push(req);
+        }
+        else {
+            byEntityType.set(key, { entity: req.entity, reqs: [req] });
+        }
+    }
+    // Batch-fetch all refs — one Batch.get call per entity type
+    const hydratedLookup = new Map();
+    for (const [entityType, { entity, reqs }] of byEntityType) {
+        const idField = DynamoModel.getIdentifierField(entity.model);
+        const identifierName = idField?.name ?? "id";
+        // Deduplicate IDs for this entity type
+        const uniqueIds = [...new Set(reqs.map((r) => r.id))];
+        // Build EntityGet intermediates for batch fetching
+        const getOps = uniqueIds.map((id) => entity.get({ [identifierName]: id }));
+        const results = yield* Batch.get(getOps);
+        // Map results back to lookup, failing on missing refs
+        for (let i = 0; i < uniqueIds.length; i++) {
+            const id = uniqueIds[i];
+            const result = results[i];
+            if (result == null) {
+                return yield* new RefNotFound({
+                    entity: aggregateName,
+                    field: reqs.find((r) => r.id === id)?.fieldName ?? "",
+                    refEntity: entityType,
+                    refId: id,
+                });
+            }
+            hydratedLookup.set(`${entityType}:${id}`, { ...result });
+        }
+    }
+    // Walk the input again and replace IDs with hydrated data
+    const result = replaceRefIds(input, refRequests, hydratedLookup);
+    renameInputFields(result, edges);
+    return result;
+});
+/**
+ * Rename ManyEdge inputField keys back to model field names so the domain
+ * schema can decode correctly. Walks edges recursively through sub-aggregates.
+ */
+const renameInputFields = (data, edges) => {
+    for (const [edgeName, edge] of Object.entries(edges)) {
+        if (!("_tag" in edge))
+            continue;
+        if (edge._tag === "ManyEdge" && edge.inputField && edge.inputField !== edgeName) {
+            if (edge.inputField in data) {
+                data[edgeName] = data[edge.inputField];
+                delete data[edge.inputField];
+            }
+        }
+        else if (edge._tag === "BoundSubAggregate") {
+            const sub = data[edgeName];
+            if (sub != null && typeof sub === "object") {
+                renameInputFields(sub, edge.aggregate.edges);
+            }
+        }
+    }
+};
+/**
+ * Recursively walk input following graph edges to collect ref ID references.
+ * Edge-driven: entity lookup comes from the edge directly, not from a refs bag.
+ */
+const collectRefIdsFromEdges = (result, input, edges, path) => {
+    for (const [edgeName, edge] of Object.entries(edges)) {
+        if (!("_tag" in edge))
+            continue;
+        if (edge._tag === "RefEdge") {
+            // RefEdge → ${field}Id in input
+            const idFieldName = `${edgeName}Id`;
+            const idValue = input[idFieldName];
+            if (typeof idValue === "string") {
+                result.push({
+                    entity: edge.entity,
+                    id: idValue,
+                    path: [...path],
+                    fieldName: edgeName,
+                    idFieldName,
+                });
+            }
+        }
+        else if (edge._tag === "OneEdge" && edge.entity) {
+            // OneEdge with entity → ${field}Id in input
+            const idFieldName = `${edgeName}Id`;
+            const idValue = input[idFieldName];
+            if (typeof idValue === "string") {
+                result.push({
+                    entity: edge.entity,
+                    id: idValue,
+                    path: [...path],
+                    fieldName: edgeName,
+                    idFieldName,
+                });
+            }
+        }
+        else if (edge._tag === "BoundSubAggregate") {
+            const bound = edge;
+            const subInput = input[edgeName];
+            if (subInput != null && typeof subInput === "object") {
+                collectRefIdsFromEdges(result, subInput, bound.aggregate.edges, [
+                    ...path,
+                    edgeName,
+                ]);
+            }
+        }
+        else if (edge._tag === "ManyEdge" && edge.entity) {
+            // ManyEdge with entity → walk array elements for ref IDs
+            const inputKey = edge.inputField ?? edgeName;
+            const arr = input[inputKey];
+            if (Array.isArray(arr)) {
+                const entityFieldName = deriveEntityFieldName(edge.entity);
+                for (let i = 0; i < arr.length; i++) {
+                    const elem = arr[i];
+                    if (typeof elem === "string") {
+                        // Element IS the ref ID (e.g., Array<string> for Array<Umpire>)
+                        result.push({
+                            entity: edge.entity,
+                            id: elem,
+                            path: [...path, inputKey, String(i)],
+                            fieldName: edgeName,
+                            idFieldName: String(i),
+                        });
+                    }
+                    else if (elem != null && typeof elem === "object") {
+                        // Element wraps entity + attributes — find the entityFieldName + "Id"
+                        const elemObj = elem;
+                        const idFieldName = `${entityFieldName}Id`;
+                        const idValue = elemObj[idFieldName];
+                        if (typeof idValue === "string") {
+                            result.push({
+                                entity: edge.entity,
+                                id: idValue,
+                                path: [...path, inputKey, String(i)],
+                                fieldName: entityFieldName,
+                                idFieldName,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+};
+/**
+ * Replace ref ID fields in the input with hydrated domain data.
+ */
+const replaceRefIds = (input, refRequests, lookup) => {
+    // Deep clone the input for mutation
+    const result = structuredClone(input);
+    for (const req of refRequests) {
+        const lookupKey = `${req.entity.entityType}:${req.id}`;
+        const data = lookup.get(lookupKey);
+        if (!data)
+            continue;
+        // Navigate to the target location in the result
+        let target = result;
+        for (const segment of req.path) {
+            const next = target[segment];
+            if (next == null || typeof next !== "object")
+                break;
+            target = next;
+        }
+        // For ManyEdge elements that are direct IDs (element IS the ref),
+        // the target is the array itself — replace the element at the index
+        if (Array.isArray(target) && /^\d+$/.test(req.idFieldName)) {
+            target[Number(req.idFieldName)] = data;
+        }
+        else {
+            // Replace: remove ${field}Id, add ${field}: data
+            delete target[req.idFieldName];
+            target[req.fieldName] = data;
+        }
+    }
+    return result;
+};
+/**
+ * Decompose an assembled domain object into DynamoDB items grouped by
+ * sub-aggregate transaction boundaries.
+ */
+const decomposeAggregate = (assembled, rootNode, contextFields, dateEncodings, aggregateName) => 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,
+    // otherwise Date objects become { M: {} } (no enumerable properties).
+    const contextValues = {};
+    for (const field of contextFields) {
+        const value = assembled[field];
+        const encoding = dateEncodings[field];
+        contextValues[field] =
+            encoding && value != null ? serializeDateForDynamo(value, encoding) : value;
+    }
+    // Root item: fields not claimed by edges
+    const edgeFieldNames = new Set(rootNode.children.map((c) => c.fieldName).filter(Boolean));
+    const rootAttrs = {};
+    for (const [key, value] of Object.entries(assembled)) {
+        if (edgeFieldNames.has(key))
+            continue;
+        // Serialize date fields in root attributes (same as context values)
+        const encoding = dateEncodings[key];
+        rootAttrs[key] = encoding && value != null ? serializeDateForDynamo(value, encoding) : value;
+    }
+    items.push({
+        entityType: rootNode.entityType,
+        attributes: rootAttrs,
+        transactionGroup: "root",
+        skComposites: [],
+    });
+    // Decompose each edge
+    for (const child of rootNode.children) {
+        const fieldValue = assembled[child.fieldName];
+        yield* decomposeNode(items, child, fieldValue, contextValues, "root", [], aggregateName);
+    }
+    // Group by transaction
+    const groups = new Map();
+    for (const item of items) {
+        const list = groups.get(item.transactionGroup) ?? [];
+        list.push(item);
+        groups.set(item.transactionGroup, list);
+    }
+    return [...groups.entries()].map(([name, groupItems]) => ({ name, items: groupItems }));
+});
+/**
+ * Merge context values into decomposed item attributes.
+ * Context values always override entity-specific fields — the aggregate root
+ * defines the authoritative values for context fields like "name" and "gender".
+ */
+const mergeContextValues = (attrs, contextValues) => {
+    for (const [key, value] of Object.entries(contextValues)) {
+        attrs[key] = value;
+    }
+};
+/**
+ * Recursively decompose a node's value into DynamoDB items.
+ */
+const decomposeNode = (items, node, value, contextValues, parentGroup, parentDiscriminatorValues, aggregateName) => Effect.gen(function* () {
+    // Optional edges may have null/undefined values — skip decomposition
+    if (value == null)
+        return;
+    if (node.cardinality === "one" && node.children.length > 0) {
+        // Sub-aggregate — becomes its own transaction group
+        const subValue = value;
+        const txGroup = node.fieldName ?? node.entityType;
+        // Discriminator values for SK composition (name#value pairs from own discriminator)
+        const discValues = node.ownDiscriminator
+            ? Object.entries(node.ownDiscriminator)
+                .filter(([, v]) => typeof v !== "function")
+                .flatMap(([k, v]) => [k, KeyComposer.serializeValue(v)])
+            : [];
+        // Sub-aggregate root item: fields not claimed by child edges
+        const childEdgeNames = new Set(node.children.map((c) => c.fieldName).filter(Boolean));
+        const subRootAttrs = {};
+        for (const [key, val] of Object.entries(subValue)) {
+            if (childEdgeNames.has(key))
+                continue;
+            subRootAttrs[key] = val;
+        }
+        // Inject context and discriminator
+        mergeContextValues(subRootAttrs, contextValues);
+        if (node.discriminator) {
+            for (const [k, v] of Object.entries(node.discriminator)) {
+                if (typeof v !== "function")
+                    subRootAttrs[k] = v;
+            }
+        }
+        items.push({
+            entityType: node.entityType,
+            attributes: subRootAttrs,
+            transactionGroup: txGroup,
+            skComposites: discValues,
+        });
+        // Decompose children within this sub-aggregate
+        for (const child of node.children) {
+            const childValue = subValue[child.fieldName];
+            yield* decomposeNode(items, child, childValue, contextValues, txGroup, discValues, aggregateName);
+        }
+    }
+    else if (node.cardinality === "one") {
+        // Simple one-to-one edge (no children)
+        const attrs = { ...value };
+        mergeContextValues(attrs, contextValues);
+        if (node.discriminator) {
+            for (const [k, v] of Object.entries(node.discriminator)) {
+                if (typeof v !== "function")
+                    attrs[k] = v;
+            }
+        }
+        // Own discriminator values as name#value pairs for SK composition
+        const ownDiscValues = node.ownDiscriminator
+            ? Object.entries(node.ownDiscriminator)
+                .filter(([, v]) => typeof v !== "function")
+                .flatMap(([k, v]) => [k, KeyComposer.serializeValue(v)])
+            : [];
+        items.push({
+            entityType: node.entityType,
+            attributes: attrs,
+            transactionGroup: parentGroup,
+            skComposites: [...parentDiscriminatorValues, ...ownDiscValues],
+        });
+    }
+    else {
+        // Many edge
+        const arrayItems = node.decompose
+            ? node.decompose(value)
+            : Array.isArray(value)
+                ? value
+                : [];
+        for (const elem of arrayItems) {
+            const attrs = { ...elem };
+            mergeContextValues(attrs, contextValues);
+            if (node.discriminator) {
+                for (const [k, v] of Object.entries(node.discriminator)) {
+                    if (typeof v !== "function")
+                        attrs[k] = v;
+                }
+            }
+            // Extract ref identifiers for SK composites
+            const itemComposites = extractRefIdentifiers(attrs);
+            items.push({
+                entityType: node.entityType,
+                attributes: attrs,
+                transactionGroup: parentGroup,
+                skComposites: [...parentDiscriminatorValues, ...itemComposites],
+            });
+        }
+    }
+});
+/**
+ * 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.
+ */
+const extractRefIdentifiers = (attrs) => {
+    const ids = [];
+    // Case 1: Element wraps entity — look for nested objects with id-like fields
+    for (const [, value] of Object.entries(attrs)) {
+        if (value != null && typeof value === "object" && !Array.isArray(value)) {
+            const obj = value;
+            if (typeof obj.id === "string") {
+                ids.push(obj.id);
+            }
+            else {
+                for (const [k, v] of Object.entries(obj)) {
+                    if (k.endsWith("Id") && typeof v === "string") {
+                        ids.push(v);
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    // 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);
+    }
+    return ids;
+};
+// ---------------------------------------------------------------------------
+// Internal: Hash-based shard selection for list collection cardinality
+// ---------------------------------------------------------------------------
+const hashToShard = (value, cardinality) => {
+    let hash = 5381;
+    for (let i = 0; i < value.length; i++) {
+        hash = ((hash << 5) + hash + value.charCodeAt(i)) | 0;
+    }
+    return Math.abs(hash) % cardinality;
+};
+// ---------------------------------------------------------------------------
+// Internal: Compose DynamoDB items from decomposed data
+// ---------------------------------------------------------------------------
+/**
+ * Convert decomposed items into DynamoDB attribute maps with composed keys.
+ */
+const buildDynamoItems = (groups, config, pkValue, rootCollectionSkComposites) => groups.map((group) => ({
+    group: group.name,
+    items: group.items.map((item) => {
+        const attrs = { ...item.attributes };
+        // Add entity type discriminator
+        attrs.__edd_e__ = item.entityType;
+        // PK: shared collection key
+        attrs[config.pk.field] = pkValue;
+        // SK: entity-type specific
+        attrs.sk = composeKey(config.schema, item.entityType, [...item.skComposites]);
+        // Collection SK (LSI): root uses collection composites, others mirror their SK
+        const isRootItem = item.entityType === config.root.entityType && item.skComposites.length === 0;
+        attrs[config.collection.sk.field] = isRootItem
+            ? composeCollectionKey(config.schema, config.collection.name, rootCollectionSkComposites)
+            : composeKey(config.schema, item.entityType, [...item.skComposites]);
+        // List collection GSI keys (root items only)
+        if (isRootItem && config.list) {
+            const listPkComposites = KeyComposer.extractComposites(config.list.pk.composite, item.attributes);
+            if (config.list.cardinality) {
+                const shard = hashToShard(pkValue, config.list.cardinality);
+                attrs[config.list.pk.field] = composeCollectionKey(config.schema, config.list.name, [
+                    ...listPkComposites,
+                    String(shard),
+                ]);
+            }
+            else {
+                attrs[config.list.pk.field] = composeCollectionKey(config.schema, config.list.name, listPkComposites);
+            }
+            const listSkComposites = KeyComposer.extractComposites(config.list.sk.composite, item.attributes);
+            attrs[config.list.sk.field] = composeCollectionKey(config.schema, config.list.name, listSkComposites);
+        }
+        return toAttributeMap(attrs);
+    }),
+}));
+// ---------------------------------------------------------------------------
+// Internal: Write transaction groups to DynamoDB
+// ---------------------------------------------------------------------------
+const writeTransactionGroups = (client, tableName, groups, aggregateName) => Effect.gen(function* () {
+    for (const group of groups) {
+        // Check transaction size limit
+        if (group.items.length > 100) {
+            return yield* new AggregateTransactionOverflow({
+                aggregate: aggregateName,
+                subgraph: group.group,
+                itemCount: group.items.length,
+                limit: 100,
+            });
+        }
+        if (group.items.length === 0)
+            continue;
+        // Build TransactWriteItems request
+        const transactItems = group.items.map((item) => ({
+            Put: { TableName: tableName, Item: item },
+        }));
+        yield* client.transactWriteItems({ TransactItems: transactItems }).pipe(Effect.mapError((error) => {
+            if (error.cause != null &&
+                typeof error.cause === "object" &&
+                "name" in error.cause &&
+                error.cause.name === "TransactionCanceledException") {
+                const cancelled = error.cause;
+                return new TransactionCancelled({
+                    operation: "TransactWriteItems",
+                    reasons: (cancelled.CancellationReasons ?? []).map((r) => ({
+                        code: r?.Code,
+                        message: r?.Message,
+                    })),
+                    cause: error.cause,
+                });
+            }
+            return error;
+        }));
+    }
+});
+// ---------------------------------------------------------------------------
+// Internal: Delete all items in an aggregate partition
+// ---------------------------------------------------------------------------
+const deleteAllItems = (client, tableName, allItems, pkField) => Effect.gen(function* () {
+    // Extract primary keys from items
+    const deleteRequests = allItems.map((item) => ({
+        DeleteRequest: {
+            Key: toAttributeMap({
+                [pkField]: item[pkField],
+                sk: item.sk,
+            }),
+        },
+    }));
+    // Chunk into batches of 25 (DynamoDB batchWriteItem limit)
+    for (let i = 0; i < deleteRequests.length; i += 25) {
+        const chunk = deleteRequests.slice(i, i + 25);
+        yield* client.batchWriteItem({
+            RequestItems: { [tableName]: chunk },
+        });
+    }
+});
+const queryListPartition = (client, tableConfig, listConfig, schema, pkValue, skValues, limit, startKey) => Effect.gen(function* () {
+    const exprNames = { "#pk": listConfig.pk.field };
+    const exprValues = { ":pk": toAttributeValue(pkValue) };
+    let keyCondition = "#pk = :pk";
+    if (skValues.length > 0) {
+        const skPrefix = composeCollectionKey(schema, listConfig.name, skValues);
+        exprNames["#sk"] = listConfig.sk.field;
+        exprValues[":skPrefix"] = toAttributeValue(skPrefix);
+        keyCondition += " AND begins_with(#sk, :skPrefix)";
+    }
+    const items = [];
+    let lastKey = startKey;
+    do {
+        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 } : {}),
+        });
+        if (result.Items) {
+            for (const item of result.Items) {
+                items.push(fromAttributeMap(item));
+            }
+        }
+        lastKey = result.LastEvaluatedKey;
+        // Stop when we've collected enough items
+        if (limit !== undefined && items.length >= limit)
+            break;
+    } while (lastKey !== undefined);
+    return { items, lastKey };
+});
+//# sourceMappingURL=Aggregate.js.map