effect-dynamodb 1.19.1 → 1.20.1

package/dist/Entity.js

@@ -44,9 +44,11 @@ import { asModel, condition as conditionCombinator, expectedVersion, set, } from
  * records can coexist with the field unset and an entity write doesn't synthesize
  * a literal `"undefined"` collision key.
  *
- * `lookup` overrides the field-value reader. The update path passes a lookup that
- * falls back from the domain field name to the renamed DB column name, since
- * `currentRaw` (read from DynamoDB) carries DB names rather than domain names.
+ * `source` is read by **domain** field name — a constraint declares domain
+ * fields, so a row that came off the wire (keyed by stored attribute name) MUST
+ * be passed through `toDomainView` first. Reading a renamed field off a raw row
+ * yields `undefined`, which the sparse rule then reads as "constraint unset" and
+ * silently skips the sentinel — the delete/purge/restore leak behind #127.
  */
 /**
  * TTL helpers — pure implementations live in `@effect-dynamodb/schema/Entity`,
@@ -55,13 +57,12 @@ import { asModel, condition as conditionCombinator, expectedVersion, set, } from
  */
 import { buildEntityDefinition, normalizeTtlSeconds, resolveUniqueTtl, } from "@effect-dynamodb/schema/Entity.js";
 export { normalizeTtlSeconds };
-const composeUniqueSentinel = (schema, entityType, constraintName, constraintDef, source, lookup) => {
+const composeUniqueSentinel = (schema, entityType, constraintName, constraintDef, source) => {
     const fields = resolveUniqueFields(constraintDef);
-    const get = lookup ?? ((s, f) => s[f]);
     const serialized = [];
     const fieldsRecord = {};
     for (const f of fields) {
-        const raw = get(source, f);
+        const raw = source[f];
         if (raw === undefined || raw === null)
             return undefined;
         const s = KeyComposer.serializeValue(raw);
@@ -298,6 +299,27 @@ const makeImpl = (config, precomputedData) => {
             return;
         decodeSparseFields(raw, sparseFields);
     };
+    /**
+     * A DOMAIN-keyed VIEW of a row that came off the wire.
+     *
+     * Stored rows are keyed by ATTRIBUTE name, but everything that reads a row by
+     * field name — key composition (`composeAllKeys`, `keyForm`), vector-partition
+     * recomposition, unique-sentinel composition — is written against DOMAIN
+     * names. Under a `DynamoModel.configure(model, { id: { field: "widgetId" } })`
+     * rename the two differ, and reading the wrong one yields `undefined`: key
+     * composition throws (`Missing composite attribute "id" in record`) and
+     * sentinel composition silently treats the constraint as unset (#127).
+     *
+     * Returns a shallow COPY — the caller's row stays attribute-keyed, so the item
+     * actually written back (tombstone, restored item, snapshot) is unaffected and
+     * `decodeAs` can still do its own in-place rename on it. Callers that decode
+     * the row and discard it rename in place instead (see `decodeRecord`).
+     */
+    const toDomainView = (raw) => {
+        const view = { ...raw };
+        renameFromDynamo(view);
+        return view;
+    };
     // ---------------------------------------------------------------------------
     // Helpers
     // ---------------------------------------------------------------------------
@@ -495,6 +517,43 @@ const makeImpl = (config, precomputedData) => {
         ConditionExpression: "attribute_not_exists(#sentinel_pk)",
         ExpressionAttributeNames: { "#sentinel_pk": config.indexes.primary.pk.field },
     });
+    /**
+     * The RESTORE-time sentinel guard.
+     *
+     * `restore` re-establishes one sentinel per satisfiable constraint. With
+     * `preserveUnique` off the delete released them, so `attribute_not_exists` is
+     * exactly right: the row is gone and anyone may have taken the value since.
+     *
+     * With `softDelete: { preserveUnique: true }` the delete deliberately KEPT the
+     * reservation, so `attribute_not_exists` can never hold and every restore of a
+     * constrained entity was cancelled and reported as a `UniqueConstraintViolation`
+     * against its own reservation — `preserveUnique` made `restore` impossible.
+     * The guard must instead let the row re-claim the sentinel it still owns while
+     * still refusing one somebody else holds, which is what the stored
+     * `_entity_pk`/`_entity_sk` back-pointer is for: they name the item the
+     * reservation belongs to, and they are the same values this Put writes.
+     */
+    const restoreSentinelGuard = (entityPk, entitySk) => {
+        const pkField = config.indexes.primary.pk.field;
+        if (!preserveUnique()) {
+            return {
+                ConditionExpression: "attribute_not_exists(#pk)",
+                ExpressionAttributeNames: { "#pk": pkField },
+            };
+        }
+        return {
+            ConditionExpression: "attribute_not_exists(#pk) OR (#epk = :epk AND #esk = :esk)",
+            ExpressionAttributeNames: {
+                "#pk": pkField,
+                "#epk": "_entity_pk",
+                "#esk": "_entity_sk",
+            },
+            ExpressionAttributeValues: {
+                ":epk": toAttributeValue(entityPk),
+                ":esk": toAttributeValue(entitySk),
+            },
+        };
+    };
     /** Collect all key field names (pk, sk, gsi*pk, gsi*sk) */
     const gsiKeyFields = () => {
         const fields = [];
@@ -775,6 +834,15 @@ const makeImpl = (config, precomputedData) => {
         for (const field of vectorKeyFields()) {
             delete snapshot[field];
         }
+        // And the soft-delete STASH. It is not an indexed attribute, so nothing
+        // above touches it, but `restore` builds its snapshot from the tombstone —
+        // which is exactly where the stash lives — so without this the `#v#N` row
+        // ends up carrying the full embedding blob that the delete-time snapshot at
+        // the same SK never had. A snapshot never re-enters the index, so it has no
+        // use for a stashed embedding either.
+        for (const [, definition] of vectorIndexEntries) {
+            delete snapshot[definition.stashField];
+        }
         // Replace SK with version SK
         snapshot[tableSkField] = DynamoSchema.composeVersionKey(schema, entityType, version);
         // Add optional TTL
@@ -809,14 +877,21 @@ const makeImpl = (config, precomputedData) => {
      * Mirrors the emission in `put`'s own transact path so the two cannot drift:
      * one sentinel per satisfiable constraint (sparse — a constraint whose fields
      * are unset produces none), then the v1 snapshot.
+     *
+     * `item` arrives ALREADY renamed to stored attribute names (`_renameToDynamo`
+     * runs inside `validateAndBuildPutItem`, so the snapshot inherits the shape
+     * that was written), hence the `toDomainView` for sentinel composition — the
+     * constraint names domain fields. `put`'s own path composes from `encoded`,
+     * which is domain-keyed before the rename.
      */
     const buildPutSideItems = (item, now, ttlAttrName) => {
         const out = [];
         const pkField = config.indexes.primary.pk.field;
         const skField = config.indexes.primary.sk.field;
+        const itemDomain = toDomainView(item);
         if (config.unique != null) {
             for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, item);
+                const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, itemDomain);
                 // Sparse: a constraint whose composing fields are unset never had a
                 // sentinel, so writing one would reserve `undefined` for everybody.
                 if (!sentinel)
@@ -1605,9 +1680,9 @@ const makeImpl = (config, precomputedData) => {
             }
             const sentinelRotations = [];
             if (touchesUniqueFields) {
-                const currentRawRecord = currentRaw;
+                const currentRawDomain = toDomainView(currentRaw);
                 for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                    const oldSentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, currentRawRecord, (s, f) => s[f] ?? s[resolveDbName(f)]);
+                    const oldSentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, currentRawDomain);
                     const newSentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, newItem);
                     if (!oldSentinel && !newSentinel)
                         continue;
@@ -2352,9 +2427,13 @@ const makeImpl = (config, precomputedData) => {
             }
             // Delete sentinels if not preserving unique. Sparse — fields that were
             // unset on the live item never had a sentinel, so nothing to delete.
+            // The stored row is attribute-keyed; the constraint names domain
+            // fields, so compose from the domain view — otherwise a renamed
+            // field reads `undefined` and the sentinel is orphaned (#127).
             if (hasUniqueConstraints && !preserveUnique()) {
+                const rawDomain = toDomainView(raw);
                 for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                    const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, raw);
+                    const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, rawDomain);
                     if (!sentinel)
                         continue;
                     transactItems.push({
@@ -2403,9 +2482,11 @@ const makeImpl = (config, precomputedData) => {
             }
             transactItems.push({ Delete: entityDelete });
             // Delete sentinels (sparse — skip constraints whose fields were unset
-            // on the live item; no sentinel was ever written for those)
+            // on the live item; no sentinel was ever written for those). Domain
+            // view: the stored row is attribute-keyed, the constraint is not (#127).
+            const rawDomain = toDomainView(raw);
             for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, raw);
+                const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, rawDomain);
                 if (!sentinel)
                     continue;
                 transactItems.push({
@@ -3264,6 +3345,11 @@ const makeImpl = (config, precomputedData) => {
         // verbatim across soft-delete (GSI keys are stripped, sparse data is
         // not).
         deserializeSparseFields(raw);
+        // `deletedRecordSchema` is keyed by DOMAIN field name, exactly like
+        // `recordSchema` — so the same rename `decodeRecord` does applies here
+        // (#127). Without it a `field:`-renamed attribute decodes as a missing
+        // key and every soft-deleted row of such an entity is unreadable.
+        renameFromDynamo(raw);
         const targetSchema = schemas.deletedRecordSchema;
         return yield* Schema.decodeUnknownEffect(targetSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
             entityType,
@@ -3280,6 +3366,8 @@ const makeImpl = (config, precomputedData) => {
             // Sparse fields are domain data and are preserved across soft-delete.
             // Rebuild Records from flattened attrs before schema decode.
             deserializeSparseFields(raw);
+            // Then attribute → domain names, same order as `decodeRecord` (#127).
+            renameFromDynamo(raw);
             return Schema.decodeUnknownEffect(schemas.deletedRecordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
                 entityType,
                 operation: "deleted.list.decode",
@@ -3351,8 +3439,14 @@ const makeImpl = (config, precomputedData) => {
             restoredItem[systemFields.version] = newVersion;
         if (systemFields.updatedAt)
             restoredItem[systemFields.updatedAt] = generateTimestamp(systemFields.updatedAtEncoding, now);
+        // Domain-keyed VIEW of the tombstone, taken once and used for every
+        // read-by-field-name below: key composition, vector-partition
+        // recomposition and unique-sentinel composition. `restoredItem` itself
+        // stays attribute-keyed — it is the row being written back, and
+        // `decodeAs` renames it in place at the end (#127).
+        const restoredDomain = toDomainView(restoredItem);
         // Recompose all keys (original SK, GSI keys)
-        const restoredKeys = composeAllKeys(restoredItem);
+        const restoredKeys = composeAllKeys(restoredDomain);
         Object.assign(restoredItem, restoredKeys);
         // Un-stash the embedding and recompose the vector partition value —
         // restoring never costs an Embedder call. See `DESIGN.md §14`.
@@ -3364,7 +3458,7 @@ const makeImpl = (config, precomputedData) => {
             }
             if (restoredItem[definition.vectorField] === undefined)
                 continue;
-            const partition = KeyComposer.tryComposeVectorPartition(schema, entityType, definition, keyForm(restoredItem));
+            const partition = KeyComposer.tryComposeVectorPartition(schema, entityType, definition, keyForm(restoredDomain));
             if (partition !== undefined)
                 restoredItem[definition.partitionField] = partition;
         }
@@ -3381,9 +3475,20 @@ const makeImpl = (config, precomputedData) => {
                 Item: marshalledRestoredItem,
             },
         });
-        // Version snapshot if retain enabled
+        // Version snapshot if retain enabled. The source is the TOMBSTONE, so
+        // the soft-delete markers have to come off first: `buildSnapshotItem`
+        // only ever overrides the TTL attribute when `versioned.ttl` is set, so
+        // a `softDelete: { ttl }` expiry rode along and the snapshot of a
+        // version that is very much still live expired an hour later — while
+        // `deletedAt` made it look like a tombstone. This Put lands on the same
+        // `#v#<version>` SK the delete-time snapshot used (same version — the
+        // restored item is version + 1), so a dirty item here REPLACED the
+        // clean snapshot the delete wrote.
         if (isRetainEnabled()) {
-            const snapshotItem = buildSnapshotItem(deletedRaw, currentVersion, primary.pk.field, primary.sk.field, ttlAttrName, now);
+            const snapshotSource = { ...deletedRaw };
+            delete snapshotSource.deletedAt;
+            delete snapshotSource[ttlAttrName];
+            const snapshotItem = buildSnapshotItem(snapshotSource, currentVersion, primary.pk.field, primary.sk.field, ttlAttrName, now);
             transactItems.push({
                 Put: {
                     TableName: tableName,
@@ -3396,10 +3501,11 @@ const makeImpl = (config, precomputedData) => {
         const sentinelConstraints = [];
         if (config.unique && Object.keys(config.unique).length > 0) {
             for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, restoredItem);
+                const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, restoredDomain);
                 if (!sentinel)
                     continue;
                 sentinelConstraints.push(constraintName);
+                const guard = restoreSentinelGuard(restoredKeys[primary.pk.field], restoredKeys[primary.sk.field]);
                 transactItems.push({
                     Put: {
                         TableName: tableName,
@@ -3410,8 +3516,11 @@ const makeImpl = (config, precomputedData) => {
                             _entity_pk: restoredKeys[primary.pk.field],
                             _entity_sk: restoredKeys[primary.sk.field],
                         }),
-                        ConditionExpression: "attribute_not_exists(#pk)",
-                        ExpressionAttributeNames: { "#pk": primary.pk.field },
+                        ConditionExpression: guard.ConditionExpression,
+                        ExpressionAttributeNames: guard.ExpressionAttributeNames,
+                        ...(guard.ExpressionAttributeValues
+                            ? { ExpressionAttributeValues: guard.ExpressionAttributeValues }
+                            : {}),
                     },
                 });
             }
@@ -3435,7 +3544,7 @@ const makeImpl = (config, precomputedData) => {
                             const uniqueFields = constraintDef ? resolveUniqueFields(constraintDef) : [];
                             const fieldsRecord = {};
                             for (const f of uniqueFields) {
-                                const v = restoredItem[f];
+                                const v = restoredDomain[f];
                                 if (v !== undefined && v !== null) {
                                     fieldsRecord[f] = KeyComposer.serializeValue(v);
                                 }
@@ -3535,9 +3644,11 @@ const makeImpl = (config, precomputedData) => {
             }
             if (entityItem) {
                 // Add sentinel keys to delete list (sparse — fields that were unset
-                // never had a sentinel written, so nothing to enqueue)
+                // never had a sentinel written, so nothing to enqueue). The stored
+                // row is attribute-keyed, the constraint is not (#127).
+                const entityItemDomain = toDomainView(entityItem);
                 for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                    const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, entityItem);
+                    const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, entityItemDomain);
                     if (!sentinel)
                         continue;
                     allItems.push(toAttributeMap({