effect-dynamodb 1.14.0 → 1.16.0

package/dist/Entity.js

@@ -10,14 +10,15 @@ import { getIdentifierField, getSparseFields, isRefField, } from "@effect-dynamo
 import * as DynamoSchema from "@effect-dynamodb/schema/DynamoSchema.js";
 import { Embedder } from "@effect-dynamodb/schema/Embedder.js";
 import { CascadePartialFailure, ConditionalCheckFailed, EmbeddingError, ItemNotFound, isAwsConditionalCheckFailed, isAwsTransactionCancelled, OptimisticLockError, RefNotFound, StaleAppend, TransactionOverflow, UniqueConstraintViolation, ValidationError, } from "@effect-dynamodb/schema/Errors.js";
+import { makeCompositeKeyForm, toCompositeKeyRecord, } from "@effect-dynamodb/schema/internal/CompositeCodec.js";
 import { makeDefaultCrypto } from "@effect-dynamodb/schema/internal/DefaultCrypto.js";
 import * as KeyComposer from "@effect-dynamodb/schema/KeyComposer.js";
 import { normalizeGsiConfig } from "@effect-dynamodb/schema/KeyComposer.js";
 import { deriveSourceText } from "@effect-dynamodb/schema/VectorIndex.js";
 import { Context, Crypto, DateTime, Effect, Option, Schema, Stream } from "effect";
 import { DynamoClient } from "./DynamoClient.js";
-import { makeBoundAppend, makeBoundDelete, makeBoundPut, makeBoundUpdate, } from "./internal/BoundCrud.js";
-import { BoundQueryImpl } from "./internal/BoundQuery.js";
+import { isBoundOp, makeBoundAppend, makeBoundDelete, makeBoundPut, makeBoundUpdate, } from "./internal/BoundCrud.js";
+import { BoundQueryImpl, } from "./internal/BoundQuery.js";
 import { compileExpr, createConditionOps, isExpr, parseShorthand, parseSimpleShorthand, } from "./internal/Expr.js";
 import { compilePath, createPathBuilder } from "./internal/PathBuilder.js";
 import { generateTimestampPrimitive } from "./internal/TransactableOps.js";
@@ -97,6 +98,25 @@ const composeUniqueSentinel = (schema, entityType, constraintName, constraintDef
  *
  * @internal
  */
+/**
+ * @internal Build a key-form normaliser for an arbitrary entity-like value.
+ *
+ * `makeImpl` closes over its own `keyForm`; this is the escape hatch for the
+ * two places that compose against a DIFFERENT entity's index (`cascade`) or run
+ * outside `makeImpl` entirely (`bind`'s `reembed` / `history`). Same rule, same
+ * `CompositeCodec` — just resolved per target.
+ */
+const keyFormFor = (target, record) => {
+    const t = target;
+    const source = t.schemas?.inputSchema ?? t.model;
+    if (source === undefined)
+        return record;
+    const form = makeCompositeKeyForm(source, (attr, value) => {
+        throw new Error(`[EDD-9050] Composite "${attr}" could not be put into its key form: ` +
+            `${JSON.stringify(String(value))} resolves under neither encode nor decode->encode.`);
+    });
+    return toCompositeKeyRecord(form, record);
+};
 const encodeOrDecodeEncode = (schema, input, entityType, operation) => Schema.encodeUnknownEffect(schema)(input).pipe(Effect.catch((primaryCause) => Schema.decodeUnknownEffect(schema)(input).pipe(Effect.flatMap((decoded) => Schema.encodeUnknownEffect(schema)(decoded)), 
 // On fallback failure, surface the original encode error — its
 // message is keyed on the caller's input shape, which is what the
@@ -281,14 +301,85 @@ const makeImpl = (config, precomputedData) => {
     // ---------------------------------------------------------------------------
     // Helpers
     // ---------------------------------------------------------------------------
+    // Read-path composite encoder — see `internal/CompositeCodec.ts`. The write
+    // path composes keys from the encoded record (`put` encodes, THEN composes);
+    // key and query inputs arrive as decoded model values, so they are encoded
+    // through the model's own field codecs before composition. Encoding is
+    // idempotent via the `decode -> encode` fallback, so callers that already
+    // hold an encoded record are unaffected.
+    // Source: `inputSchema`, the EXACT schema `put` encodes through before
+    // `composeAllKeys`. The raw model is not equivalent — entity derivation
+    // substitutes date/Redacted fields with their wire transforms, so reading
+    // fields off the model would miss encodings the write path applies.
+    const compositeKeyForm = makeCompositeKeyForm(schemas.inputSchema, (attr, value) => {
+        throw new Error(`[EDD-9050] Composite "${attr}" on entity "${entityType}" could not be encoded to its ` +
+            `stored form. The attribute's schema carries an encoding transformation, so the ` +
+            `stored key holds the ENCODED value, but ${JSON.stringify(String(value))} encodes ` +
+            `under neither encode nor decode->encode. Supply a value of the attribute's own type.`);
+    });
+    /**
+     * PUBLIC key boundary. Converts a caller-supplied key record from the model's
+     * **Type** side — the one convention the whole API takes — into the ENCODED
+     * form key composition expects.
+     *
+     * `put` composes keys from the encoded record, so the stored key holds the
+     * wire value. Key-taking operations used to run a plain `decode`, which reads
+     * the Encoded side and then handed the *decoded* result to the composer. On a
+     * transformed composite neither spelling worked: `get({ txn: 420n })` failed
+     * validation and `get({ txn: "420" })` silently returned `ItemNotFound` for a
+     * row that exists. Encoding the Type side fixes the one spelling that should
+     * have worked all along, and matches what the query path takes.
+     *
+     * Encode-ONLY, deliberately: no `decode -> encode` fallback. The Encoded side
+     * is not a public input, so `{ txn: "420" }` fails here — loudly, with the
+     * attribute named by the schema error — rather than composing a key by a
+     * second convention. Internal callers that legitimately hold encoded records
+     * do not come through here; see `composePrimaryKey`.
+     */
+    const encodeKey = (key, operation) => Schema.encodeUnknownEffect(schemas.keySchema)(key).pipe(Effect.map((encoded) => encoded), Effect.mapError((cause) => new ValidationError({ entityType, operation, cause })));
+    /**
+     * Synchronous `encodeKey`, for the query builders (`history`, `versions`,
+     * `deleted.list`) that compose a partition key outside an Effect. Same
+     * Type-side-only rule; throws the schema's own error, which names the
+     * offending attribute — these builders have always thrown on a bad key.
+     */
+    const encodeKeySync = (key) => Schema.encodeUnknownSync(schemas.keySchema)(key);
+    /**
+     * INTERNAL key composition. Takes an **already-encoded** record — either the
+     * output of `encodeKey` on the public path, or an item read back from
+     * DynamoDB on the retain / restore / soft-delete paths, which are wire-shaped
+     * by construction.
+     *
+     * The `encodeCompositeRecord` pass is a normalisation, not a second input
+     * convention: composite encoding is idempotent, so an already-encoded value
+     * round-trips to itself. It exists so that `keySchema` (built from raw model
+     * fields) and `inputSchema` (built from derivation-substituted fields) cannot
+     * disagree for a composite whose wire transform is added by derivation —
+     * `Schema.Date` being the case that matters.
+     */
+    /**
+     * THE key-form normaliser. Every record handed to `KeyComposer` in this
+     * module goes through it, so the write path, the update path, the lifecycle
+     * paths and the read path cannot disagree about how a composite is spelled
+     * in a key.
+     *
+     * Skipping it on ONE site is enough to corrupt data: `composeAllKeys` (put)
+     * normalised while `composeGsiKeysForUpdatePolicyAware` (update) did not, so
+     * an `update()` rewrote a padded `gsi1pk` to its unpadded form and evicted
+     * the row from its own GSI. `test/KeyFormInvariant.test.ts` scans this file
+     * and fails if a `KeyComposer.compose*` call takes a record that did not come
+     * through `keyForm(...)`.
+     */
+    const keyForm = (record) => toCompositeKeyRecord(compositeKeyForm, record);
     const composePrimaryKey = (record) => {
         const primary = config.indexes.primary;
+        const recordKeyForm = keyForm(record);
         return {
-            [primary.pk.field]: KeyComposer.composePk(schema, entityType, primary, record),
-            [primary.sk.field]: KeyComposer.composeSk(schema, entityType, entityVersion, primary, record),
+            [primary.pk.field]: KeyComposer.composePk(schema, entityType, primary, recordKeyForm),
+            [primary.sk.field]: KeyComposer.composeSk(schema, entityType, entityVersion, primary, recordKeyForm),
         };
     };
-    const composeAllKeys = (record) => KeyComposer.composeAllKeys(schema, entityType, entityVersion, allIndexes, record);
+    const composeAllKeys = (record) => KeyComposer.composeAllKeys(schema, entityType, entityVersion, allIndexes, keyForm(record));
     /**
      * Fill the auto-generated id field on the raw `put` input when configured and
      * absent. Sources a UUID from the bundled `Crypto` service. Caller-supplied
@@ -392,6 +483,18 @@ const makeImpl = (config, precomputedData) => {
             return false;
         return config.softDelete.preserveUnique === true;
     };
+    /**
+     * The uniqueness sentinel's guard. `attribute_not_exists` must name the
+     * entity's CONFIGURED partition-key attribute — a literal `pk` is simply
+     * absent from an entity declaring `pk: { field: "PK" }`, so the condition is
+     * vacuously true and the constraint is silently unenforced (#111). Routed
+     * through `ExpressionAttributeNames` because the field name is user-supplied
+     * and may be a reserved word.
+     */
+    const sentinelGuard = () => ({
+        ConditionExpression: "attribute_not_exists(#sentinel_pk)",
+        ExpressionAttributeNames: { "#sentinel_pk": config.indexes.primary.pk.field },
+    });
     /** Collect all key field names (pk, sk, gsi*pk, gsi*sk) */
     const gsiKeyFields = () => {
         const fields = [];
@@ -494,7 +597,7 @@ const makeImpl = (config, precomputedData) => {
         const removes = [];
         for (const [logicalName, definition] of vectorIndexEntries) {
             const shouldEmbed = embedFor === "all" || embedFor.has(logicalName);
-            const partition = KeyComposer.tryComposeVectorPartition(schema, entityType, definition, record);
+            const partition = KeyComposer.tryComposeVectorPartition(schema, entityType, definition, keyForm(record));
             if (partition === undefined) {
                 // No partition value ⇒ the item cannot be in the index at all. Drop
                 // both attributes so a previously-indexed item leaves the index
@@ -587,7 +690,7 @@ const makeImpl = (config, precomputedData) => {
      * description" produces the embedding of what actually remains — or drops the
      * item out of the index when nothing does.
      */
-    const computeVectorUpdateAttributes = (decodedKey, marshalledKey, tableName, updatePayload, uState) => Effect.gen(function* () {
+    const computeVectorUpdateAttributes = (encodedKey, marshalledKey, tableName, updatePayload, uState) => Effect.gen(function* () {
         if (!hasVectorIndexes)
             return { sets: {}, removes: [] };
         const withVectors = uState.withVectors;
@@ -601,7 +704,7 @@ const makeImpl = (config, precomputedData) => {
         // Base record: key composites plus whatever the payload supplies. Enough
         // to compose partition values (their composites are normally primary-key
         // members) without any extra read.
-        let merged = { ...decodedKey, ...updatePayload };
+        let merged = { ...encodedKey, ...updatePayload };
         const needsFullSource = needing.some(([logicalName, definition]) => withVectors?.[logicalName] === undefined &&
             definition.sourceFields.some((field) => !(field in merged)));
         if (needsFullSource) {
@@ -624,7 +727,7 @@ const makeImpl = (config, precomputedData) => {
             // Partition value: idempotent and cheap, so recompose whenever the
             // merged record can supply it (same reasoning as the PK-composites-only
             // GSI shape in §7).
-            const partition = KeyComposer.tryComposeVectorPartition(schema, entityType, definition, merged);
+            const partition = KeyComposer.tryComposeVectorPartition(schema, entityType, definition, keyForm(merged));
             if (partition === undefined) {
                 // Only drop the partition when THIS writer invalidated it. Otherwise
                 // the composite simply wasn't in scope for this call and dropping it
@@ -682,6 +785,73 @@ const makeImpl = (config, precomputedData) => {
         return snapshot;
     };
     // ---------------------------------------------------------------------------
+    // Multi-item write support for the transact compile path (#113)
+    // ---------------------------------------------------------------------------
+    /**
+     * Which parts of this entity's write contract need more than one item.
+     * Drives both the `put` expansion and the `delete` / `Batch.write` rejections.
+     */
+    const multiItemWriteFeatures = () => {
+        const features = [];
+        if (config.unique != null && Object.keys(config.unique).length > 0)
+            features.push("unique");
+        if (isRetainEnabled())
+            features.push("retain");
+        if (isSoftDeleteEnabled())
+            features.push("softDelete");
+        return features;
+    };
+    /**
+     * Side items for a `put`, derived purely from the payload being written —
+     * see the `_buildPutSideItems` doc on the Entity interface for why the delete
+     * side has no counterpart.
+     *
+     * 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.
+     */
+    const buildPutSideItems = (item, now, ttlAttrName) => {
+        const out = [];
+        const pkField = config.indexes.primary.pk.field;
+        const skField = config.indexes.primary.sk.field;
+        if (config.unique != null) {
+            for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
+                const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, item);
+                // Sparse: a constraint whose composing fields are unset never had a
+                // sentinel, so writing one would reserve `undefined` for everybody.
+                if (!sentinel)
+                    continue;
+                const sentinelItem = {
+                    [pkField]: sentinel.key.pk,
+                    [skField]: sentinel.key.sk,
+                    __edd_e__: `${entityType}._unique.${constraintName}`,
+                    _entity_pk: item[pkField],
+                    _entity_sk: item[skField],
+                };
+                const uniqueTtl = resolveUniqueTtl(constraintDef);
+                if (uniqueTtl !== undefined) {
+                    sentinelItem[ttlAttrName] = DateTime.toEpochSeconds(now) + normalizeTtlSeconds(uniqueTtl);
+                }
+                out.push({
+                    kind: "sentinel",
+                    constraintName,
+                    fields: sentinel.fieldsRecord,
+                    item: sentinelItem,
+                    // The guard IS the constraint — without it the sentinel would happily
+                    // overwrite another row's reservation and enforce nothing.
+                    guard: sentinelGuard(),
+                });
+            }
+        }
+        if (isRetainEnabled()) {
+            out.push({
+                kind: "snapshot",
+                item: buildSnapshotItem(item, 1, pkField, skField, ttlAttrName, now),
+            });
+        }
+        return out;
+    };
+    // ---------------------------------------------------------------------------
     // Ref hydration
     // ---------------------------------------------------------------------------
     /**
@@ -820,7 +990,7 @@ const makeImpl = (config, precomputedData) => {
             const { name: targetTableName } = yield* target._tableTag;
             // Compose GSI PK for the source entity's ID
             const targetSchema = target._schema;
-            const gsiPkValue = KeyComposer.composePk(targetSchema, target.entityType, cascadeIdx.indexDef, { [matchingRef.idFieldName]: sourceIdValue });
+            const gsiPkValue = KeyComposer.composePk(targetSchema, target.entityType, cascadeIdx.indexDef, keyFormFor(target, { [matchingRef.idFieldName]: sourceIdValue }));
             // Build query parameters
             const gsiPkField = cascadeIdx.indexDef.pk.field;
             const queryNames = {
@@ -1062,7 +1232,7 @@ const makeImpl = (config, precomputedData) => {
                         Put: {
                             TableName: tableName,
                             Item: toAttributeMap(sentinelItem),
-                            ConditionExpression: "attribute_not_exists(pk)",
+                            ...sentinelGuard(),
                         },
                     });
                 }
@@ -1155,7 +1325,7 @@ const makeImpl = (config, precomputedData) => {
         const pkField = config.indexes.primary.pk.field;
         const skField = config.indexes.primary.sk.field;
         const op = put(input);
-        return new EntityPutImpl(op._builder, op._entity, op._input, { attributeNotExists: [pkField, skField] }, op._withVectors);
+        return new EntityPutImpl(op._builder, op._entity, op._input, { attributeNotExists: [pkField, skField] }, op._withVectors, "create");
     };
     // ---------------------------------------------------------------------------
     // patch operation — update + attribute_exists condition
@@ -1171,14 +1341,10 @@ const makeImpl = (config, precomputedData) => {
     const get = (key) => new EntityGetImpl((mode, opts) => Effect.gen(function* () {
         const client = yield* DynamoClient;
         const { name: tableName } = yield* tableTag;
-        // Decode key
-        const decodedKey = yield* Schema.decodeUnknownEffect(schemas.keySchema)(key).pipe(Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "get.decode",
-            cause,
-        })));
+        // Caller key: Type side in, ENCODED out (see `encodeKey`).
+        const encodedKey = yield* encodeKey(key, "get.decode");
         // Compose primary key
-        const primaryKey = composePrimaryKey(decodedKey);
+        const primaryKey = composePrimaryKey(encodedKey);
         const marshalledKey = toAttributeMap(primaryKey);
         // Build ProjectionExpression if projection attributes provided
         let projectionExpression;
@@ -1198,7 +1364,7 @@ const makeImpl = (config, precomputedData) => {
                 : undefined,
         });
         if (!result.Item) {
-            return yield* new ItemNotFound({ entityType, key: decodedKey });
+            return yield* new ItemNotFound({ entityType, key: encodedKey });
         }
         // Raw mode: return unmarshalled record without schema decode
         if (mode === "raw") {
@@ -1222,12 +1388,8 @@ const makeImpl = (config, precomputedData) => {
         // Clock-backed time source for the updatedAt timestamp + retain snapshot TTL.
         const now = yield* DateTime.now;
         yield* checkWithVectorNames(uState.withVectors, "update");
-        // Decode key
-        const decodedKey = yield* Schema.decodeUnknownEffect(schemas.keySchema)(key).pipe(Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "update.decodeKey",
-            cause,
-        })));
+        // Caller key: Type side in, ENCODED out (see `encodeKey`).
+        const encodedKey = yield* encodeKey(key, "update.decodeKey");
         // Encode update payload → wire form (see `put` for the strategy).
         const encodedUpdates = yield* encodeOrDecodeEncode(schemas.updateSchema, updates ?? {}, entityType, "update");
         // Hydrate refs in updates: for any ${field}Id present, fetch and embed
@@ -1241,7 +1403,7 @@ const makeImpl = (config, precomputedData) => {
             }
         }
         // Compose primary key
-        const primaryKey = composePrimaryKey(decodedKey);
+        const primaryKey = composePrimaryKey(encodedKey);
         const marshalledKey = toAttributeMap(primaryKey);
         // Detect whether the update touches any unique constraint fields
         const hasUniqueConstraints = config.unique != null && Object.keys(config.unique).length > 0;
@@ -1266,7 +1428,7 @@ const makeImpl = (config, precomputedData) => {
                 Key: marshalledKey,
             });
             if (!currentResult.Item) {
-                return yield* new ItemNotFound({ entityType, key: decodedKey });
+                return yield* new ItemNotFound({ entityType, key: encodedKey });
             }
             const currentRaw = fromAttributeMap(currentResult.Item);
             const currentVersion = systemFields.version
@@ -1276,7 +1438,7 @@ const makeImpl = (config, precomputedData) => {
             if (evExpected !== undefined && currentVersion !== evExpected) {
                 return yield* new OptimisticLockError({
                     entityType,
-                    key: decodedKey,
+                    key: encodedKey,
                     expectedVersion: evExpected,
                     actualVersion: currentVersion,
                 });
@@ -1408,7 +1570,7 @@ const makeImpl = (config, precomputedData) => {
             // No try/catch needed — EDD-9024 was deprecated in v1.7.1 and
             // the composer no longer throws.
             const retainRemovedSet = uState.remove ? new Set(uState.remove) : undefined;
-            const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, allIndexes, hydratedUpdates, newItem, retainRemovedSet === undefined ? {} : { removedSet: retainRemovedSet });
+            const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, allIndexes, keyForm(hydratedUpdates), keyForm(newItem), retainRemovedSet === undefined ? {} : { removedSet: retainRemovedSet });
             for (const [field, value] of Object.entries(gsiUpdate.sets)) {
                 newItem[field] = value;
             }
@@ -1432,7 +1594,7 @@ const makeImpl = (config, precomputedData) => {
                 // `newItem` from the read-then-write merge above.
                 if (addressed.has(indexDef.pk.field) || addressed.has(indexDef.sk.field))
                     continue;
-                const keys = KeyComposer.tryComposeIndexKeys(schema, entityType, entityVersion, indexDef, newItem);
+                const keys = KeyComposer.tryComposeIndexKeys(schema, entityType, entityVersion, indexDef, keyForm(newItem));
                 if (keys) {
                     Object.assign(newItem, keys);
                 }
@@ -1564,7 +1726,7 @@ const makeImpl = (config, precomputedData) => {
                                 _entity_pk: primaryKey[config.indexes.primary.pk.field],
                                 _entity_sk: primaryKey[config.indexes.primary.sk.field],
                             }),
-                            ConditionExpression: "attribute_not_exists(pk)",
+                            ...sentinelGuard(),
                         },
                     });
                 }
@@ -1575,6 +1737,24 @@ const makeImpl = (config, precomputedData) => {
                 TransactItems: transactItems.map((t) => "Put" in t ? { Put: t.Put } : { Delete: t.Delete }),
             })
                 .pipe(Effect.mapError((err) => {
+                // The main item's ConditionExpression carries the version CAS
+                // (when the entity is versioned) ANDed with any user condition.
+                // DynamoDB does not say which half rejected, so attribute the
+                // failure to the version CAS whenever one is present, and to
+                // the user condition only when it is the sole predicate —
+                // otherwise an unversioned entity's `.condition()` rejection
+                // would surface as a nonsensical OptimisticLockError.
+                const mainItemRejection = () => {
+                    if (!systemFields.version && userCond) {
+                        return new ConditionalCheckFailed({ entityType, key: encodedKey });
+                    }
+                    return new OptimisticLockError({
+                        entityType,
+                        key: encodedKey,
+                        expectedVersion: currentVersion,
+                        actualVersion: -1,
+                    });
+                };
                 if (isAwsTransactionCancelled(err.cause)) {
                     const reasons = err.cause.CancellationReasons;
                     if (reasons) {
@@ -1590,22 +1770,12 @@ const makeImpl = (config, precomputedData) => {
                         }
                         // Index 0 is the main item — version conflict or user condition
                         if (reasons[0]?.Code === "ConditionalCheckFailed") {
-                            return new OptimisticLockError({
-                                entityType,
-                                key: decodedKey,
-                                expectedVersion: currentVersion,
-                                actualVersion: -1,
-                            });
+                            return mainItemRejection();
                         }
                     }
                 }
                 if (isAwsConditionalCheckFailed(err.cause)) {
-                    return new OptimisticLockError({
-                        entityType,
-                        key: decodedKey,
-                        expectedVersion: currentVersion,
-                        actualVersion: -1,
-                    });
+                    return mainItemRejection();
                 }
                 return err;
             }));
@@ -1614,7 +1784,7 @@ const makeImpl = (config, precomputedData) => {
             if (uState.cascade) {
                 const domainData = { ...retainDecoded };
                 const sourceId = sourceIdentifierField != null
-                    ? decodedKey[sourceIdentifierField]
+                    ? encodedKey[sourceIdentifierField]
                     : undefined;
                 if (sourceId != null) {
                     yield* executeCascade(uState.cascade, domainData, String(sourceId));
@@ -1772,7 +1942,7 @@ const makeImpl = (config, precomputedData) => {
         // No try/catch — EDD-9024 was deprecated in v1.7.1 and the
         // composer no longer throws. Hole patterns collapse into the
         // unified can't-compose rule.
-        const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, allIndexes, hydratedUpdates, decodedKey, removedSet === undefined ? {} : { removedSet });
+        const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, allIndexes, keyForm(hydratedUpdates), keyForm(encodedKey), removedSet === undefined ? {} : { removedSet });
         for (const [field, value] of Object.entries(gsiUpdate.sets)) {
             const nameKey = `#u${counter}`;
             const valKey = `:u${counter}`;
@@ -1791,7 +1961,7 @@ const makeImpl = (config, precomputedData) => {
         // touched a `source.fields` member or supplied `.withVector(...)`.
         // See `DESIGN.md §14 Write path`.
         if (hasVectorIndexes) {
-            const vectorWrite = yield* computeVectorUpdateAttributes(decodedKey, marshalledKey, tableName, hydratedUpdates, uState);
+            const vectorWrite = yield* computeVectorUpdateAttributes(encodedKey, marshalledKey, tableName, hydratedUpdates, uState);
             for (const [field, value] of Object.entries(vectorWrite.sets)) {
                 const nameKey = `#u${counter}`;
                 const valKey = `:u${counter}`;
@@ -2030,7 +2200,7 @@ const makeImpl = (config, precomputedData) => {
                 if (evExpected !== undefined) {
                     return new OptimisticLockError({
                         entityType,
-                        key: decodedKey,
+                        key: encodedKey,
                         expectedVersion: evExpected,
                         actualVersion: -1,
                     });
@@ -2038,14 +2208,14 @@ const makeImpl = (config, precomputedData) => {
                 if (userCond) {
                     return new ConditionalCheckFailed({
                         entityType,
-                        key: decodedKey,
+                        key: encodedKey,
                     });
                 }
             }
             return err;
         }));
         if (!result.Attributes) {
-            return yield* new ItemNotFound({ entityType, key: decodedKey });
+            return yield* new ItemNotFound({ entityType, key: encodedKey });
         }
         const raw = fromAttributeMap(result.Attributes);
         const decoded = yield* decodeAs(raw, result.Attributes, mode);
@@ -2053,7 +2223,7 @@ const makeImpl = (config, precomputedData) => {
         if (uState.cascade) {
             const domainData = { ...decoded };
             const sourceId = sourceIdentifierField != null
-                ? decodedKey[sourceIdentifierField]
+                ? encodedKey[sourceIdentifierField]
                 : undefined;
             if (sourceId != null) {
                 yield* executeCascade(uState.cascade, domainData, String(sourceId));
@@ -2069,14 +2239,10 @@ const makeImpl = (config, precomputedData) => {
         const tc = yield* tableTag;
         const tableName = tc.name;
         const ttlAttrName = resolveTtlAttributeName(tc);
-        // Decode key
-        const decodedKey = yield* Schema.decodeUnknownEffect(schemas.keySchema)(key).pipe(Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "delete.decode",
-            cause,
-        })));
+        // Caller key: Type side in, ENCODED out (see `encodeKey`).
+        const encodedKey = yield* encodeKey(key, "delete.decode");
         // Compose primary key
-        const primaryKey = composePrimaryKey(decodedKey);
+        const primaryKey = composePrimaryKey(encodedKey);
         const marshalledKey = toAttributeMap(primaryKey);
         const primary = config.indexes.primary;
         const hasUniqueConstraints = config.unique != null && Object.keys(config.unique).length > 0;
@@ -2084,6 +2250,26 @@ const makeImpl = (config, precomputedData) => {
         const userCondition = opts.condition
             ? compileCondition(opts.condition, resolveDbName)
             : undefined;
+        /**
+         * Map a rejected user condition on either transaction delete path
+         * (soft-delete, unique-constraint) to `ConditionalCheckFailed`.
+         *
+         * On both paths the current-item Delete sits at index 0 and is the
+         * only item carrying a ConditionExpression — the sentinel Deletes and
+         * the tombstone/snapshot Puts are unconditional — so an index-0
+         * cancellation can only be the user's condition. Every other reason
+         * falls through as the raw `DynamoClientError`.
+         */
+        const mapDeleteConditionFailure = (err) => {
+            if (!userCondition)
+                return err;
+            const cancelledAtMainItem = isAwsTransactionCancelled(err.cause) &&
+                err.cause.CancellationReasons?.[0]?.Code === "ConditionalCheckFailed";
+            if (cancelledAtMainItem || isAwsConditionalCheckFailed(err.cause)) {
+                return new ConditionalCheckFailed({ entityType, key: encodedKey });
+            }
+            return err;
+        };
         if (isSoftDeleteEnabled()) {
             // --- Soft delete path ---
             // Read current item
@@ -2092,7 +2278,7 @@ const makeImpl = (config, precomputedData) => {
                 Key: marshalledKey,
             });
             if (!result.Item) {
-                return yield* Effect.fail(new ItemNotFound({ entityType, key: decodedKey }));
+                return yield* Effect.fail(new ItemNotFound({ entityType, key: encodedKey }));
             }
             const raw = fromAttributeMap(result.Item);
             // Clock-backed time source; `now` is the ISO timestamp used for the
@@ -2126,10 +2312,24 @@ const makeImpl = (config, precomputedData) => {
                 deletedItem[ttlAttrName] = DateTime.toEpochSeconds(dtNow) + normalizeTtlSeconds(sdTtl);
             }
             const transactItems = [];
-            // Delete current entity item
-            transactItems.push({
-                Delete: { TableName: tableName, Key: marshalledKey },
-            });
+            // Delete current entity item — index 0, and the ONLY item in this
+            // transaction carrying a ConditionExpression, so a cancellation
+            // naming index 0 is unambiguously the user's condition. The guard
+            // rides the transaction rather than being pre-checked against the
+            // item read above: a client-side check would leave a race window
+            // between the read and the write.
+            const currentDelete = {
+                TableName: tableName,
+                Key: marshalledKey,
+            };
+            if (userCondition) {
+                currentDelete.ConditionExpression = userCondition.expression;
+                currentDelete.ExpressionAttributeNames = userCondition.names;
+                if (Object.keys(userCondition.values).length > 0) {
+                    currentDelete.ExpressionAttributeValues = userCondition.values;
+                }
+            }
+            transactItems.push({ Delete: currentDelete });
             // Put soft-deleted item
             transactItems.push({
                 Put: {
@@ -2169,9 +2369,11 @@ const makeImpl = (config, precomputedData) => {
                 }
             }
             yield* checkTransactionLimit(entityType, "delete", transactItems);
-            yield* client.transactWriteItems({
+            yield* client
+                .transactWriteItems({
                 TransactItems: transactItems,
-            });
+            })
+                .pipe(Effect.mapError(mapDeleteConditionFailure));
         }
         else if (hasUniqueConstraints) {
             // --- Hard delete with unique constraints ---
@@ -2181,14 +2383,25 @@ const makeImpl = (config, precomputedData) => {
                 Key: marshalledKey,
             });
             if (!result.Item) {
-                return yield* Effect.fail(new ItemNotFound({ entityType, key: decodedKey }));
+                return yield* Effect.fail(new ItemNotFound({ entityType, key: encodedKey }));
             }
             const raw = fromAttributeMap(result.Item);
             const transactItems = [];
-            // Delete entity item
-            transactItems.push({
-                Delete: { TableName: tableName, Key: marshalledKey },
-            });
+            // Delete entity item — index 0, and the only conditioned item (the
+            // sentinel Deletes below are unconditional), so an index-0
+            // cancellation is unambiguously the user's condition.
+            const entityDelete = {
+                TableName: tableName,
+                Key: marshalledKey,
+            };
+            if (userCondition) {
+                entityDelete.ConditionExpression = userCondition.expression;
+                entityDelete.ExpressionAttributeNames = userCondition.names;
+                if (Object.keys(userCondition.values).length > 0) {
+                    entityDelete.ExpressionAttributeValues = userCondition.values;
+                }
+            }
+            transactItems.push({ Delete: entityDelete });
             // Delete sentinels (sparse — skip constraints whose fields were unset
             // on the live item; no sentinel was ever written for those)
             for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
@@ -2206,9 +2419,11 @@ const makeImpl = (config, precomputedData) => {
                 });
             }
             yield* checkTransactionLimit(entityType, "delete", transactItems);
-            yield* client.transactWriteItems({
+            yield* client
+                .transactWriteItems({
                 TransactItems: transactItems.map((t) => ({ Delete: t.Delete })),
-            });
+            })
+                .pipe(Effect.mapError(mapDeleteConditionFailure));
         }
         else {
             // Simple delete
@@ -2226,15 +2441,7 @@ const makeImpl = (config, precomputedData) => {
             if (opts.returnValues) {
                 deleteInput.ReturnValues = returnValuesMap[opts.returnValues];
             }
-            yield* client.deleteItem(deleteInput).pipe(Effect.mapError((err) => {
-                if (opts.condition && isAwsConditionalCheckFailed(err.cause)) {
-                    return new ConditionalCheckFailed({
-                        entityType,
-                        key: decodedKey,
-                    });
-                }
-                return err;
-            }));
+            yield* client.deleteItem(deleteInput).pipe(Effect.mapError(mapDeleteConditionFailure));
         }
     }), self, key);
     // ---------------------------------------------------------------------------
@@ -2456,7 +2663,10 @@ const makeImpl = (config, precomputedData) => {
         }
         const raw = fromAttributeMap(result.Attributes);
         return yield* decodeAs(raw, result.Attributes, mode);
-    }), self, input);
+    }), self, input, undefined, undefined, 
+    // Tagged so the transact/batch compilers can refuse it: this op is an
+    // UpdateItem with `if_not_exists`, not a Put (#100).
+    "upsert");
     /**
      * @internal Compare stored vs attempted `orderBy` to decide whether the CAS
      * predicate `attribute_not_exists(pk) OR stored < attempted` failed.
@@ -2614,8 +2824,9 @@ const makeImpl = (config, precomputedData) => {
         }
         // Compose current-item primary key (pk + sk derived from PK/SK composites)
         const primary = config.indexes.primary;
-        const pkValue = KeyComposer.composePk(schema, entityType, primary, encoded);
-        const currentSk = KeyComposer.composeSk(schema, entityType, entityVersion, primary, encoded);
+        const appendKeyForm = keyForm(encoded);
+        const pkValue = KeyComposer.composePk(schema, entityType, primary, appendKeyForm);
+        const currentSk = KeyComposer.composeSk(schema, entityType, entityVersion, primary, appendKeyForm);
         const marshalledKey = toAttributeMap({
             [primary.pk.field]: pkValue,
             [primary.sk.field]: currentSk,
@@ -2660,7 +2871,7 @@ const makeImpl = (config, precomputedData) => {
         // touched on every write and the structural rule composes them.
         // No try/catch — EDD-9024 was deprecated in v1.7.1 and the composer
         // no longer throws.
-        const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, allIndexes, encoded, encoded, removedSet !== undefined ? { removedSet } : undefined);
+        const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, allIndexes, keyForm(encoded), keyForm(encoded), removedSet !== undefined ? { removedSet } : undefined);
         for (const [field, value] of Object.entries(gsiUpdate.sets)) {
             const nameKey = `#a${counter}`;
             const valKey = `:a${counter}`;
@@ -2885,10 +3096,10 @@ const makeImpl = (config, precomputedData) => {
         if (!timeSeriesConfig) {
             throw new Error(`[EDD-9010] Entity "${entityType}": .history() requires timeSeries config on the entity.`);
         }
-        const decodedKey = Schema.decodeUnknownSync(schemas.keySchema)(key);
+        const encodedKey = keyForm(encodeKeySync(key));
         const primary = config.indexes.primary;
-        const pkValue = KeyComposer.composePk(schema, entityType, primary, decodedKey);
-        const currentSk = KeyComposer.composeSk(schema, entityType, entityVersion, primary, decodedKey);
+        const pkValue = KeyComposer.composePk(schema, entityType, primary, keyForm(encodedKey));
+        const currentSk = KeyComposer.composeSk(schema, entityType, entityVersion, primary, keyForm(encodedKey));
         const prefix = KeyComposer.composeEventSkPrefix(currentSk, schema.casing);
         const decodeHistory = (raw) => {
             // Sparse fields are aggregate state, not event state — event items DO
@@ -2912,6 +3123,7 @@ const makeImpl = (config, precomputedData) => {
             entityTypes: [entityType],
             decoder: (raw) => decodeHistory(raw),
             resolveTableName: tableTag.useSync((tc) => tc.name),
+            keyFields: [primary.pk.field, primary.sk.field],
         }).pipe(Query.where({ beginsWith: prefix }));
     };
     // ---------------------------------------------------------------------------
@@ -2922,9 +3134,12 @@ const makeImpl = (config, precomputedData) => {
         if (indexName === "primary")
             continue;
         const indexDef = config.indexes[indexName];
-        queryNamespace[indexName] = (pk) => {
-            const pkValue = KeyComposer.composePk(schema, entityType, indexDef, pk);
-            const hasSkComposites = indexDef.sk.composite.some((attr) => pk[attr] !== undefined);
+        queryNamespace[indexName] = (rawPk) => {
+            // Normalise composites to their key form before composing — same rule
+            // and same function the write path uses (see `CompositeCodec`).
+            const pkKeyForm = keyForm(rawPk);
+            const pkValue = KeyComposer.composePk(schema, entityType, indexDef, pkKeyForm);
+            const hasSkComposites = indexDef.sk.composite.some((attr) => pkKeyForm[attr] !== undefined);
             const query = Query.make({
                 tableName: "",
                 indexName: indexDef.index,
@@ -2934,9 +3149,19 @@ const makeImpl = (config, precomputedData) => {
                 entityTypes: [entityType],
                 decoder: (raw) => decodeRecord(raw),
                 resolveTableName: tableTag.useSync((tc) => tc.name),
+                keyFields: [
+                    indexDef.pk.field,
+                    indexDef.sk.field,
+                    config.indexes.primary.pk.field,
+                    config.indexes.primary.sk.field,
+                ],
             });
             if (hasSkComposites) {
-                const skPrefix = KeyComposer.composeSortKeyPrefix(schema, entityType, entityVersion, indexDef, pk);
+                // `composeSortKeyBeginsWith`, not `composeSortKeyPrefix` — the operand
+                // must terminate on a segment boundary when composites remain, or it
+                // matches sibling values that merely start with the supplied one
+                // (`status_done` also matching `status_done_archived`, issue #115).
+                const skPrefix = KeyComposer.composeSortKeyBeginsWith(schema, entityType, entityVersion, indexDef, pkKeyForm);
                 return Query.where(query, { beginsWith: skPrefix });
             }
             return query;
@@ -2951,6 +3176,7 @@ const makeImpl = (config, precomputedData) => {
         entityTypes: [entityType],
         decoder: (raw) => decodeRecord(raw),
         resolveTableName: tableTag.useSync((tc) => tc.name),
+        keyFields: [config.indexes.primary.pk.field, config.indexes.primary.sk.field],
     });
     // ---------------------------------------------------------------------------
     // getVersion operation
@@ -2958,15 +3184,11 @@ const makeImpl = (config, precomputedData) => {
     const getVersion = (key, versionNumber) => new EntityGetImpl((mode, opts) => Effect.gen(function* () {
         const client = yield* DynamoClient;
         const { name: tableName } = yield* tableTag;
-        // Decode key
-        const decodedKey = yield* Schema.decodeUnknownEffect(schemas.keySchema)(key).pipe(Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "getVersion.decode",
-            cause,
-        })));
+        // Caller key: Type side in, ENCODED out (see `encodeKey`).
+        const encodedKey = yield* encodeKey(key, "getVersion.decode");
         // Compose PK + version SK
         const primary = config.indexes.primary;
-        const pkValue = KeyComposer.composePk(schema, entityType, primary, decodedKey);
+        const pkValue = KeyComposer.composePk(schema, entityType, primary, keyForm(encodedKey));
         const versionSk = DynamoSchema.composeVersionKey(schema, entityType, versionNumber);
         const marshalledKey = toAttributeMap({
             [primary.pk.field]: pkValue,
@@ -2978,7 +3200,7 @@ const makeImpl = (config, precomputedData) => {
             ConsistentRead: opts.consistentRead || undefined,
         });
         if (!result.Item) {
-            return yield* new ItemNotFound({ entityType, key: decodedKey });
+            return yield* new ItemNotFound({ entityType, key: encodedKey });
         }
         const raw = fromAttributeMap(result.Item);
         return yield* decodeAs(raw, result.Item, mode);
@@ -2987,9 +3209,9 @@ const makeImpl = (config, precomputedData) => {
     // versions operation
     // ---------------------------------------------------------------------------
     const versions = (key) => {
-        const decodedKey = Schema.decodeUnknownSync(schemas.keySchema)(key);
+        const encodedKey = keyForm(encodeKeySync(key));
         const primary = config.indexes.primary;
-        const pkValue = KeyComposer.composePk(schema, entityType, primary, decodedKey);
+        const pkValue = KeyComposer.composePk(schema, entityType, primary, keyForm(encodedKey));
         const versionPrefix = DynamoSchema.composeVersionKeyPrefix(schema, entityType);
         return Query.make({
             tableName: "",
@@ -3000,6 +3222,7 @@ const makeImpl = (config, precomputedData) => {
             entityTypes: [entityType],
             decoder: (raw) => decodeRecord(raw),
             resolveTableName: tableTag.useSync((tc) => tc.name),
+            keyFields: [primary.pk.field, primary.sk.field],
         }).pipe(Query.where({ beginsWith: versionPrefix }));
     };
     // ---------------------------------------------------------------------------
@@ -3008,15 +3231,11 @@ const makeImpl = (config, precomputedData) => {
     const deletedGet = (key) => new EntityGetImpl((mode, _opts) => Effect.gen(function* () {
         const client = yield* DynamoClient;
         const { name: tableName } = yield* tableTag;
-        // Decode key
-        const decodedKey = yield* Schema.decodeUnknownEffect(schemas.keySchema)(key).pipe(Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "deleted.get.decode",
-            cause,
-        })));
+        // Caller key: Type side in, ENCODED out (see `encodeKey`).
+        const encodedKey = yield* encodeKey(key, "deleted.get.decode");
         // Query for soft-deleted item using begins_with on deleted prefix
         const primary = config.indexes.primary;
-        const pkValue = KeyComposer.composePk(schema, entityType, primary, decodedKey);
+        const pkValue = KeyComposer.composePk(schema, entityType, primary, keyForm(encodedKey));
         const deletedPrefix = DynamoSchema.composeDeletedKeyPrefix(schema, entityType);
         const result = yield* client.query({
             TableName: tableName,
@@ -3033,7 +3252,7 @@ const makeImpl = (config, precomputedData) => {
             ScanIndexForward: false,
         });
         if (!result.Items || result.Items.length === 0) {
-            return yield* new ItemNotFound({ entityType, key: decodedKey });
+            return yield* new ItemNotFound({ entityType, key: encodedKey });
         }
         const raw = fromAttributeMap(result.Items[0]);
         // Soft-deleted items have GSI keys stripped — always use deletedRecordSchema
@@ -3053,9 +3272,9 @@ const makeImpl = (config, precomputedData) => {
         })));
     }), self, key);
     const deletedList = (key) => {
-        const decodedKey = Schema.decodeUnknownSync(schemas.keySchema)(key);
+        const encodedKey = keyForm(encodeKeySync(key));
         const primary = config.indexes.primary;
-        const pkValue = KeyComposer.composePk(schema, entityType, primary, decodedKey);
+        const pkValue = KeyComposer.composePk(schema, entityType, primary, keyForm(encodedKey));
         const deletedPrefix = DynamoSchema.composeDeletedKeyPrefix(schema, entityType);
         const decodeDeleted = (raw) => {
             // Sparse fields are domain data and are preserved across soft-delete.
@@ -3076,6 +3295,7 @@ const makeImpl = (config, precomputedData) => {
             entityTypes: [],
             decoder: (raw) => decodeDeleted(raw),
             resolveTableName: tableTag.useSync((tc) => tc.name),
+            keyFields: [primary.pk.field, primary.sk.field],
         }).pipe(Query.where({ beginsWith: deletedPrefix }));
     };
     // ---------------------------------------------------------------------------
@@ -3088,15 +3308,11 @@ const makeImpl = (config, precomputedData) => {
         const ttlAttrName = resolveTtlAttributeName(tc);
         // Clock-backed time source for the restored updatedAt + retain snapshot.
         const now = yield* DateTime.now;
-        // Decode key
-        const decodedKey = yield* Schema.decodeUnknownEffect(schemas.keySchema)(key).pipe(Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "restore.decode",
-            cause,
-        })));
+        // Caller key: Type side in, ENCODED out (see `encodeKey`).
+        const encodedKey = yield* encodeKey(key, "restore.decode");
         // Query for the soft-deleted item
         const primary = config.indexes.primary;
-        const pkValue = KeyComposer.composePk(schema, entityType, primary, decodedKey);
+        const pkValue = KeyComposer.composePk(schema, entityType, primary, keyForm(encodedKey));
         const deletedPrefix = DynamoSchema.composeDeletedKeyPrefix(schema, entityType);
         const queryResult = yield* client.query({
             TableName: tableName,
@@ -3113,7 +3329,7 @@ const makeImpl = (config, precomputedData) => {
             ScanIndexForward: false,
         });
         if (!queryResult.Items || queryResult.Items.length === 0) {
-            return yield* new ItemNotFound({ entityType, key: decodedKey });
+            return yield* new ItemNotFound({ entityType, key: encodedKey });
         }
         const deletedRaw = fromAttributeMap(queryResult.Items[0]);
         const deletedMarshalledKey = toAttributeMap({
@@ -3148,7 +3364,7 @@ const makeImpl = (config, precomputedData) => {
             }
             if (restoredItem[definition.vectorField] === undefined)
                 continue;
-            const partition = KeyComposer.tryComposeVectorPartition(schema, entityType, definition, restoredItem);
+            const partition = KeyComposer.tryComposeVectorPartition(schema, entityType, definition, keyForm(restoredItem));
             if (partition !== undefined)
                 restoredItem[definition.partitionField] = partition;
         }
@@ -3240,17 +3456,29 @@ const makeImpl = (config, precomputedData) => {
     // ---------------------------------------------------------------------------
     // purge operation
     // ---------------------------------------------------------------------------
-    const purge = (key) => new EntityDeleteImpl((_opts) => Effect.gen(function* () {
+    const purge = (key) => new EntityDeleteImpl((opts) => Effect.gen(function* () {
+        // `purge` is partition-wide — it queries every item under the key and
+        // batch-deletes in chunks, so there is no single item for a
+        // ConditionExpression to guard and no way to make one atomic across
+        // the batches. `.condition()` is structurally available because
+        // `purge` returns an `EntityDelete`; refuse it loudly rather than
+        // accept a guard that would never be sent.
+        if (opts.condition) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "purge.condition",
+                cause: "[EDD-9047] .condition() is not supported on purge() — purge deletes every item " +
+                    "in the partition across multiple batched writes, so a per-item ConditionExpression " +
+                    "cannot be applied atomically. Guard the individual delete with " +
+                    "delete(key).condition(...) instead.",
+            });
+        }
         const client = yield* DynamoClient;
         const { name: tableName } = yield* tableTag;
-        // Decode key
-        const decodedKey = yield* Schema.decodeUnknownEffect(schemas.keySchema)(key).pipe(Effect.mapError((cause) => new ValidationError({
-            entityType,
-            operation: "purge.decode",
-            cause,
-        })));
+        // Caller key: Type side in, ENCODED out (see `encodeKey`).
+        const encodedKey = yield* encodeKey(key, "purge.decode");
         const primary = config.indexes.primary;
-        const pkValue = KeyComposer.composePk(schema, entityType, primary, decodedKey);
+        const pkValue = KeyComposer.composePk(schema, entityType, primary, keyForm(encodedKey));
         // Query ALL items in this partition (current + versions + deleted)
         // Use ProjectionExpression to only get keys
         const allItems = [];
@@ -3274,7 +3502,7 @@ const makeImpl = (config, precomputedData) => {
             // Get current or deleted item to extract field values for sentinel cleanup
             const marshalledKey = toAttributeMap({
                 [primary.pk.field]: pkValue,
-                [primary.sk.field]: KeyComposer.composeSk(schema, entityType, entityVersion, primary, decodedKey),
+                [primary.sk.field]: KeyComposer.composeSk(schema, entityType, entityVersion, primary, keyForm(encodedKey)),
             });
             const mainResult = yield* client.getItem({
                 TableName: tableName,
@@ -3407,6 +3635,10 @@ const makeImpl = (config, precomputedData) => {
         /** @internal Entity schema version baked into composed keys. */
         _entityVersion: entityVersion,
         _serializeSparseFields: serializeSparseFields,
+        _keyForm: keyForm,
+        _renameToDynamo: renameToDynamo,
+        _buildPutSideItems: buildPutSideItems,
+        _multiItemWriteFeatures: multiItemWriteFeatures(),
         _attachPrototype: attachPrototype,
         _configure: (injectedSchema, injectedTableTag) => {
             schema = injectedSchema;
@@ -3549,12 +3781,13 @@ export const bind = (entity) => Effect.gen(function* () {
                 const decoded = (yield* entity._decodeRecord(raw));
                 // Snapshots / tombstones live in the same partition under a
                 // rewritten SK — their SK cannot be recomposed from the record.
-                const liveSk = KeyComposer.composeSk(boundSchema, entity.entityType, boundEntityVersion, primary, decoded);
+                const decodedKeyForm = keyFormFor(entity, decoded);
+                const liveSk = KeyComposer.composeSk(boundSchema, entity.entityType, boundEntityVersion, primary, decodedKeyForm);
                 if (storedSk !== liveSk)
                     return false;
                 const attributes = {};
                 for (const [logicalName, definition] of vectorDefs) {
-                    const partition = KeyComposer.tryComposeVectorPartition(boundSchema, entity.entityType, definition, decoded);
+                    const partition = KeyComposer.tryComposeVectorPartition(boundSchema, entity.entityType, definition, decodedKeyForm);
                     if (partition === undefined)
                         continue;
                     const text = deriveSourceText(definition, decoded);
@@ -3674,9 +3907,15 @@ export const bind = (entity) => Effect.gen(function* () {
             const composeSkCondition = (cond) => {
                 // We need the `currentSk` + prefix. The user's `key` lets us derive
                 // `currentSk` via the same primary SK composer used by `history()`.
-                const currentSk = KeyComposer.composeSk(schemaRef, entityTypeRef, 1, primary, key);
+                // `key` is the caller's Type-side key; the stored SK was composed
+                // from the encoded form, so normalise it the same way
+                // `composePrimaryKey` does before recomposing.
+                const currentSk = KeyComposer.composeSk(schemaRef, entityTypeRef, 1, primary, keyFormFor(entityInternals, key));
                 const prefix = KeyComposer.composeEventSkPrefix(currentSk, schemaRef.casing);
-                const rewrite = (v) => `${prefix}${DynamoSchema.applyCasing(KeyComposer.serializeValue(v), schemaRef.casing)}`;
+                // Key form first: the event SK is composed from the key form of the
+                // orderBy value (`Entity.append` composes from `serialisedInput`), so
+                // a transformed orderBy composite must take the same route here.
+                const rewrite = (v) => `${prefix}${DynamoSchema.applyCasing(KeyComposer.serializeValue(orderBy === undefined ? v : keyFormFor(entityInternals, { [orderBy]: v })[orderBy]), schemaRef.casing)}`;
                 if ("eq" in cond)
                     return { eq: rewrite(cond.eq) };
                 if ("lt" in cond)
@@ -3717,25 +3956,55 @@ const isEntityDelete = (op) => EntityDeleteTypeId in op;
 /**
  * Extract transactable metadata from an Entity operation intermediate.
  * Returns undefined if the value is not a recognized entity operation.
+ *
+ * Bound-CRUD builders (`db.entities.X.put(...)`, `.create(...)`,
+ * `.delete(...)`, …) are unwrapped to the `EntityOp` / `EntityDelete` they wrap.
+ * That unwrapping is what lets entities authored with the pure, AWS-free
+ * `@effect-dynamodb/schema` `Entity.make` take part in `Batch.write`,
+ * `Transaction.transactWrite`, and `EventStore.append({ additionalItems })` — a
+ * pure definition carries no operations, so the bound builder is the only write
+ * descriptor its author can ever hold (#100).
  */
 export const extractTransactable = (op) => {
     if (op == null || typeof op !== "object")
         return undefined;
+    // Unwrap a bound-CRUD builder to the intermediate it wraps. Combinators on the
+    // builder (`.condition()`, `.set()`, …) are applied to that inner op, so the
+    // unwrapped value carries the full request.
+    const target = isBoundOp(op) ? op._op : op;
+    if (target == null || typeof target !== "object")
+        return undefined;
     // Check for EntityOp intermediates (get, put, update)
-    if (isEntityOp(op)) {
-        if (op._opType === "get") {
-            return { opType: "get", entity: op._entity, key: op._key };
-        }
-        if (op._opType === "put") {
-            return { opType: "put", entity: op._entity, input: op._input };
+    if (isEntityOp(target)) {
+        if (target._opType === "get") {
+            return { opType: "get", entity: target._entity, key: target._key };
+        }
+        if (target._opType === "put") {
+            return {
+                opType: "put",
+                entity: target._entity,
+                input: target._input,
+                condition: target._condition,
+                putKind: target._putKind ?? "put",
+            };
         }
-        if (op._opType === "update") {
-            return { opType: "update", entity: op._entity, key: op._key };
+        if (target._opType === "update") {
+            return {
+                opType: "update",
+                entity: target._entity,
+                key: target._key,
+                condition: target._updateState?.condition,
+            };
         }
     }
     // Check for EntityDelete intermediate
-    if (isEntityDelete(op)) {
-        return { opType: "delete", entity: op._entity, key: op._key };
+    if (isEntityDelete(target)) {
+        return {
+            opType: "delete",
+            entity: target._entity,
+            key: target._key,
+            condition: target._condition,
+        };
     }
     return undefined;
 };