effect-dynamodb 1.22.0 → 1.23.0

package/dist/Entity.js

@@ -6,31 +6,31 @@
  * carries derived schemas for 7 type extractors (Model, Record, Input, Update,
  * Key, Item, Marshalled).
  */
-import { getIdentifierField, getSparseFields, isRefField, } from "@effect-dynamodb/schema/DynamoModel.js";
+import { getIdentifierField, getSparseFields, isConfiguredModel, isRefField, } from "@effect-dynamodb/schema/DynamoModel.js";
 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 { CascadePartialFailure, ConcurrentModification, ConditionalCheckFailed, DeleteAppliedButUnreadable, EmbeddingError, ItemNotDeleted, ItemNotFound, isAwsConditionalCheckFailed, isAwsTransactionCancelled, OptimisticLockError, RefNotFound, StaleAppend, TransactionOverflow, UniqueConstraintViolation, UpdateAppliedButUnreadable, 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 { Cause, Context, Crypto, Data, DateTime, Effect, Equal, Option, Schema, Stream, } from "effect";
 import { DynamoClient } from "./DynamoClient.js";
 import { isBoundOp, makeBoundAppend, makeBoundDelete, makeBoundGet, makeBoundPut, makeBoundUpdate, } from "./internal/BoundCrud.js";
-import { BoundQueryImpl, } from "./internal/BoundQuery.js";
-import { compileExpr, createConditionOps, isExpr, parseShorthand, parseSimpleShorthand, } from "./internal/Expr.js";
+import { BoundQueryImpl, entityNaming, } from "./internal/BoundQuery.js";
+import { compileExpr, createConditionOps, emptyPartProblem, isExpr, nonEmptyCondition, parseShorthand, parseSimpleShorthand, toExpr, } from "./internal/Expr.js";
 import { compilePath, createPathBuilder } from "./internal/PathBuilder.js";
-import { generateTimestampPrimitive } from "./internal/TransactableOps.js";
+import { freshIncarnationToken, generateTimestampPrimitive, INCARNATION_TOKEN, UNSENTINELED_DEFAULTS, } from "./internal/TransactableOps.js";
 import { decodeSparseFields, encodeSparseFields, fromAttributeMap, toAttributeMap, toAttributeValue, } from "./Marshaller.js";
 import * as Query from "./Query.js";
 import { filterExpr, selectPaths } from "./Query.js";
 import { resolveTtlAttributeName } from "./Table.js";
 export { EntityDeleteImpl, EntityDeleteTypeId, EntityGetImpl, EntityOpTypeId, EntityPutImpl, EntityUpdateImpl, EntityUpdateTypeId, emptyUpdateState, returnValuesMap, } from "./internal/EntityOps.js";
 import * as Projection from "@effect-dynamodb/schema/Projection.js";
-import { EntityDeleteImpl, EntityDeleteTypeId, EntityGetImpl, EntityOpTypeId, EntityPutImpl, EntityUpdateImpl, emptyUpdateState, returnValuesMap, } from "./internal/EntityOps.js";
+import { EntityDeleteImpl, EntityDeleteTypeId, EntityGetImpl, EntityOpTypeId, EntityPutImpl, EntityUpdateImpl, emptyUpdateState, withGuard, } from "./internal/EntityOps.js";
 export { add, append, asItem, asModel, asNative, asRecord, cascade, clearMap, consistentRead, deleteFromSet, expectedVersion, pathAdd, pathAppend, pathDelete, pathIfNotExists, pathPrepend, pathRemove, pathSet, pathSubtract, project, remove, removeEntries, returnValues, set, subtract, } from "./internal/EntityCombinators.js";
-import { allCompositeAttributes, allKeyFieldNames, getSchemaFields, primaryKeyComposites, resolveUniqueFields, } from "@effect-dynamodb/schema/internal/EntitySchemas.js";
+import { allCompositeAttributes, allKeyFieldNames, getSchemaFields, makePathValueEncoder, primaryKeyComposites, resolveUniqueFields, } from "@effect-dynamodb/schema/internal/EntitySchemas.js";
 import { asModel, condition as conditionCombinator, expectedVersion, set, } from "./internal/EntityCombinators.js";
 // ---------------------------------------------------------------------------
 // Sparse-aware unique sentinel composition
@@ -59,6 +59,13 @@ import { buildEntityDefinition, normalizeTtlSeconds, resolveUniqueTtl, } from "@
 export { normalizeTtlSeconds };
 const composeUniqueSentinel = (schema, entityType, constraintName, constraintDef, source) => {
     const fields = resolveUniqueFields(constraintDef);
+    // A field holding only a default has no sentinel (#133).
+    const defaulted = source[UNSENTINELED_DEFAULTS];
+    const defaultedFields = defaulted instanceof Set
+        ? defaulted
+        : new Set(Array.isArray(defaulted) ? defaulted : []);
+    if (fields.some((f) => defaultedFields.has(f)))
+        return undefined;
     const serialized = [];
     const fieldsRecord = {};
     for (const f of fields) {
@@ -118,6 +125,142 @@ const keyFormFor = (target, record) => {
     });
     return toCompositeKeyRecord(form, record);
 };
+/**
+ * @internal A plain update of a complete item found no item: the caller
+ * creates it instead (`updateOrCreate`). Never escapes the update operation.
+ */
+class MissingForCreate extends Data.TaggedError("MissingForCreate") {
+}
+/** DynamoDB's limits on one expression: its length, and its operators + functions. */
+const EXPRESSION_LIMIT = 4096;
+const OPERATOR_LIMIT = 300;
+/**
+ * The tokens of a compiled expression. Names and values are placeholders
+ * (`#…`, `:…`), so no operator can hide inside one.
+ */
+const EXPRESSION_TOKEN = /#\w+|:\w+|<>|<=|>=|[=<>()+\-,.[\]]|[A-Za-z_]\w*|\d+/g;
+/**
+ * The operators DynamoDB counts against an expression's 300 (#133), measured
+ * against DynamoDB: in a condition, each comparison (`=`, `<>`, `<`, `<=`,
+ * `>`, `>=`), `AND` / `OR` / `NOT`, `BETWEEN` (whose own `AND` is part of it,
+ * not another operator), `IN`, and each function; in an update, each `+` /
+ * `-` and each function (`if_not_exists`, `list_append`) — a `SET` clause's
+ * `=` is not an operator.
+ */
+/** @internal */
+export const countOperators = (expression, kind) => {
+    const tokens = expression.match(EXPRESSION_TOKEN) ?? [];
+    let count = 0;
+    let betweens = 0;
+    for (const [i, token] of tokens.entries()) {
+        const word = token.toUpperCase();
+        const isFunction = /^[A-Za-z_]\w*$/.test(token) && tokens[i + 1] === "(";
+        if (kind === "update") {
+            if (token === "+" || token === "-" || isFunction)
+                count++;
+            continue;
+        }
+        if (isFunction)
+            count++;
+        else if (["=", "<>", "<", "<=", ">", ">="].includes(token))
+            count++;
+        else if (word === "BETWEEN") {
+            count++;
+            betweens++;
+        }
+        else if (word === "AND" && betweens > 0)
+            betweens--;
+        else if (word === "AND" || word === "OR" || word === "NOT" || word === "IN")
+            count++;
+    }
+    return count;
+};
+/** What DynamoDB counts against an expression's limits. */
+const expressionCost = (expression, kind = "condition") => expression === undefined
+    ? { length: 0, operators: 0 }
+    : { length: expression.length, operators: countOperators(expression, kind) };
+const expressionFits = (expression, kind = "condition") => {
+    const cost = expressionCost(expression, kind);
+    return cost.length <= EXPRESSION_LIMIT && cost.operators <= OPERATOR_LIMIT;
+};
+const bytesKey = (bytes) => Array.from(bytes).join(",");
+/** Structural equality of two marshalled values (sets compare as sets). */
+const attributeValueEquals = (a, b) => {
+    if (a === undefined || b === undefined)
+        return a === b;
+    const [kind] = Object.keys(a);
+    if (kind === undefined || Object.keys(b)[0] !== kind)
+        return false;
+    const x = a[kind];
+    const y = b[kind];
+    switch (kind) {
+        case "L": {
+            const xs = x;
+            const ys = y;
+            return xs.length === ys.length && xs.every((v, i) => attributeValueEquals(v, ys[i]));
+        }
+        case "M": {
+            const xm = x;
+            const ym = y;
+            const keys = Object.keys(xm);
+            return (keys.length === Object.keys(ym).length &&
+                keys.every((k) => attributeValueEquals(xm[k], ym[k])));
+        }
+        case "SS":
+        case "NS": {
+            const xs = new Set(x);
+            const ys = y;
+            return xs.size === new Set(ys).size && ys.every((v) => xs.has(v));
+        }
+        case "B":
+            return bytesKey(x) === bytesKey(y);
+        case "BS": {
+            const xs = new Set(x.map(bytesKey));
+            const ys = y.map(bytesKey);
+            return xs.size === new Set(ys).size && ys.every((v) => xs.has(v));
+        }
+        default:
+            return x === y;
+    }
+};
+/**
+ * The top-level attributes an UpdateExpression writes (SET / REMOVE / ADD /
+ * DELETE targets), resolved through its attribute names.
+ */
+const expressionTargets = (expression, names) => {
+    const targets = new Set();
+    const sections = expression.split(/\b(SET|REMOVE|ADD|DELETE)\b/).slice(1);
+    for (let i = 0; i + 1 < sections.length; i += 2) {
+        const action = sections[i];
+        const body = sections[i + 1];
+        // Split on commas outside parentheses (`list_append(#a, :b)`).
+        const items = [];
+        let depth = 0;
+        let current = "";
+        for (const ch of body) {
+            if (ch === "(")
+                depth++;
+            if (ch === ")")
+                depth--;
+            if (ch === "," && depth === 0) {
+                items.push(current);
+                current = "";
+            }
+            else
+                current += ch;
+        }
+        items.push(current);
+        for (const item of items) {
+            const trimmed = item.trim();
+            if (trimmed === "")
+                continue;
+            const path = action === "SET" ? trimmed.split("=")[0].trim() : trimmed.split(/\s+/)[0];
+            const head = path.split(/[.[]/)[0];
+            targets.add(head.startsWith("#") ? (names[head] ?? head) : head);
+        }
+    }
+    return targets;
+};
 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
@@ -150,6 +293,28 @@ const checkTransactionLimit = (entityType, operation, items) => items.length > T
         limit: TRANSACTION_LIMIT,
     }))
     : Effect.void;
+/** Attempts a guarded put makes before it reports a lost race (#133). */
+const GUARDED_PUT_ATTEMPTS = 3;
+/**
+ * @internal A delete's item was deleted between its read and its write, with
+ * nothing asserted about it: read again, never reported (#133).
+ */
+class DeletedConcurrently extends Data.TaggedError("DeletedConcurrently") {
+}
+/**
+ * The `ConcurrentModification`s that report a sentinel release whose
+ * reservation changed hands between the ownership read and the write (#133),
+ * as opposed to a change of the item itself. Nothing was written, and the
+ * write is still valid against a fresh read — so an `upsert` plans it again,
+ * as a put does. Carried across the copies that fill in `current`.
+ */
+const releaseRaces = new WeakSet();
+/** `next`, a copy of `previous`, marked as a release race if `previous` was. */
+const keepReleaseRace = (previous, next) => {
+    if (releaseRaces.has(previous))
+        releaseRaces.add(next);
+    return next;
+};
 /**
  * Create an Entity definition.
  *
@@ -266,12 +431,287 @@ const makeImpl = (config, precomputedData) => {
     // the runtime Entity carries, so the cast is sound.
     const data = precomputedData ?? buildEntityDefinition(config);
     const { systemFields, schemas, hasRefs, immutableFields, resolvedIdentifier, generatedIdField, generatedIdVersion, entityType, entityVersion, sparseFields, hasSparseFields, renameToDynamo, renameFromDynamo, resolveDbName, rawModel, isSchemaClass, hasHiddenFields, } = data;
+    // Encoders for path-addressed update values (`pathSet`, `pathAppend`, …) and
+    // record-based `append`, which bypass the update schema (#133).
+    const pathValues = makePathValueEncoder(data.modelFields, schemas.writeModelSchema.fields, 
+    // A `DynamoModel.ref` field's own schema is opaque; paths under it follow
+    // the model it is denormalised from.
+    Object.fromEntries(data.resolvedRefs
+        .filter((ref) => ref.refEntity?.model !== undefined)
+        .map((ref) => {
+        const model = ref.refEntity.model;
+        return [
+            ref.fieldName,
+            isConfiguredModel(model) ? model.model : model,
+        ];
+    })));
+    /**
+     * Encode a path-addressed update value and check it against the write schema
+     * at its path — container checks included (#133). `undefined` issue = valid.
+     */
+    const encodePathValue = (segments, value, kind) => {
+        if (kind === "value") {
+            const encoded = pathValues.value(segments, value);
+            return { encoded, issue: pathValues.validate(segments, encoded) };
+        }
+        const encoded = pathValues.elements(segments, value);
+        return { encoded, issue: pathValues.validateElements(segments, encoded) };
+    };
+    const hasPathOps = (uState) => [
+        uState.pathSets,
+        uState.pathRemoves,
+        uState.pathAdds,
+        uState.pathSubtracts,
+        uState.pathAppends,
+        uState.pathPrepends,
+        uState.pathIfNotExists,
+        uState.pathDeletes,
+    ].some((ops) => ops !== undefined && ops.length > 0);
     // resolvedRefs carries the actual ref-target entity objects; at runtime they
     // are operational Entities (for runtime-authored refs) so write-time hydration
     // can call their CRUD ops. The pure bundle widens refEntity to EntityDefinition.
     const resolvedRefs = data.resolvedRefs;
     // allIndexes is mutable: _injectIndex adds collection-owned GSIs after make().
     let allIndexes = { ...data.initialIndexes };
+    /** Composites of the secondary indexes (`allIndexes` grows after make()). */
+    const indexCompositeFields = () => new Set(Object.entries(allIndexes)
+        .filter(([name]) => name !== "primary")
+        .flatMap(([, def]) => [...def.pk.composite, ...def.sk.composite]));
+    /**
+     * Why `field` feeds a key or a unique sentinel — values the library derives
+     * from the field at write time — or `undefined` when it feeds neither.
+     */
+    const derivedFrom = (field) => {
+        const primary = allIndexes.primary;
+        if (primary && [...primary.pk.composite, ...primary.sk.composite].includes(field)) {
+            return "a primary-key composite";
+        }
+        for (const [name, def] of Object.entries(allIndexes)) {
+            if (name === "primary")
+                continue;
+            if (def.pk.composite.includes(field) || def.sk.composite.includes(field)) {
+                return `a composite of index "${name}"`;
+            }
+        }
+        for (const [name, def] of Object.entries((config.unique ?? {}))) {
+            if (resolveUniqueFields(def).includes(field))
+                return `a field of unique constraint "${name}"`;
+        }
+        return undefined;
+    };
+    /**
+     * Path operations on a field that feeds a key or a unique sentinel (#133).
+     *
+     * DynamoDB evaluates a path operation, so compiling one on such a field would
+     * change the attribute while its index keys and sentinel stay as they were.
+     * A top-level `pathSet` of a value / `pathRemove` IS `.set()` / `.remove()`
+     * of that field, and `pathAdd` / `pathSubtract` of a number IS `.add()` /
+     * `.subtract()`: they are rewritten into those record operations, which go
+     * through the key composer and the sentinel rotation. Anything whose result
+     * only DynamoDB knows (a copy from another attribute, `if_not_exists`, list
+     * and set operations) is refused, as is a path below such a field, a
+     * primary-key composite (it identifies the item), an immutable field, and a
+     * field targeted twice. Returns the rewritten state or the refusal.
+     */
+    const normalizeDerivedPathOps = (uState) => {
+        if (!hasPathOps(uState))
+            return uState;
+        const updates = {
+            ...(uState.updates ?? {}),
+        };
+        const remove = [...(uState.remove ?? [])];
+        const add = { ...uState.add };
+        const subtract = { ...uState.subtract };
+        const targeted = new Set([
+            ...Object.keys(updates),
+            ...remove,
+            ...Object.keys(add),
+            ...Object.keys(subtract),
+            ...Object.keys(uState.append ?? {}),
+            ...Object.keys(uState.deleteFromSet ?? {}),
+        ]);
+        let refusal;
+        let rewritten = false;
+        const shown = (segments) => JSON.stringify(segments.map((s, i) => (typeof s === "number" ? `[${s}]` : i === 0 ? s : `.${s}`)).join(""));
+        // The field a path operation addresses when it feeds a key or sentinel,
+        // "free" when it feeds neither, or "refused" (recorded) for the shapes
+        // that can never be rewritten.
+        const claim = (op, segments) => {
+            const first = segments[0];
+            if (typeof first !== "string")
+                return "free";
+            const head = first;
+            const reason = derivedFrom(head);
+            if (reason === undefined)
+                return "free";
+            if (segments.length > 1) {
+                refusal ??=
+                    `${op} on ${shown(segments)}: "${head}" is ${reason}, so a path below it cannot be ` +
+                        `updated. Write the whole value with .set({ ${head} }).`;
+            }
+            else if (reason === "a primary-key composite") {
+                refusal ??=
+                    `${op} on "${head}": "${head}" is a primary-key composite — it identifies the item ` +
+                        "and cannot be changed by an update.";
+            }
+            else if (immutableFields.has(head)) {
+                refusal ??= `${op} on "${head}": "${head}" is immutable and cannot be changed by an update.`;
+            }
+            else if (targeted.has(head)) {
+                refusal ??=
+                    `${op} on "${head}": "${head}" is ${reason} and is already targeted by another ` +
+                        "operation in this update. Give it one operation.";
+            }
+            else {
+                targeted.add(head);
+                return { field: head, reason };
+            }
+            return "refused";
+        };
+        const serverSide = (op, field, reason) => {
+            refusal ??=
+                `${op} on "${field}": "${field}" is ${reason}. DynamoDB computes this operation's ` +
+                    `result at write time, so the key or sentinel derived from "${field}" could not be ` +
+                    `recomposed to match. Read the item and write the new value with .set({ ${field} }).`;
+        };
+        const keep = (ops, segmentsOf, name, rewrite) => {
+            if (ops === undefined)
+                return undefined;
+            const kept = [];
+            for (const op of ops) {
+                const claimed = claim(name, segmentsOf(op));
+                if (claimed === "free")
+                    kept.push(op);
+                if (typeof claimed === "string")
+                    continue;
+                rewritten = true;
+                rewrite(op, claimed.field, claimed.reason);
+            }
+            return kept;
+        };
+        const pathSets = keep(uState.pathSets, (op) => op.segments, "pathSet", (op, field, reason) => {
+            if (op.isPath)
+                serverSide("pathSet (a copy of another attribute)", field, reason);
+            else
+                updates[field] = op.value;
+        });
+        const pathRemoves = keep(uState.pathRemoves, (segments) => segments, "pathRemove", (_, field) => {
+            remove.push(field);
+        });
+        const pathAdds = keep(uState.pathAdds, (op) => op.segments, "pathAdd", (op, field, reason) => {
+            if (typeof op.value === "number")
+                add[field] = op.value;
+            else
+                serverSide("pathAdd (to a set)", field, reason);
+        });
+        const pathSubtracts = keep(uState.pathSubtracts, (op) => op.segments, "pathSubtract", (op, field, reason) => {
+            if (!op.isPath && typeof op.value === "number")
+                subtract[field] = op.value;
+            else
+                serverSide("pathSubtract (of another attribute)", field, reason);
+        });
+        const refuseAll = (name) => (_, field, reason) => serverSide(name, field, reason);
+        const pathAppends = keep(uState.pathAppends, (op) => op.segments, "pathAppend", refuseAll("pathAppend"));
+        const pathPrepends = keep(uState.pathPrepends, (op) => op.segments, "pathPrepend", refuseAll("pathPrepend"));
+        const pathIfNotExists = keep(uState.pathIfNotExists, (op) => op.segments, "pathIfNotExists", refuseAll("pathIfNotExists"));
+        const pathDeletes = keep(uState.pathDeletes, (op) => op.segments, "pathDelete", refuseAll("pathDelete"));
+        if (refusal !== undefined)
+            return refusal;
+        if (!rewritten)
+            return uState;
+        return {
+            ...uState,
+            updates: Object.keys(updates).length > 0 ? updates : uState.updates,
+            remove: remove.length > 0 ? remove : uState.remove,
+            add: Object.keys(add).length > 0 ? add : uState.add,
+            subtract: Object.keys(subtract).length > 0 ? subtract : uState.subtract,
+            pathSets,
+            pathRemoves,
+            pathAdds,
+            pathSubtracts,
+            pathAppends,
+            pathPrepends,
+            pathIfNotExists,
+            pathDeletes,
+        };
+    };
+    /**
+     * A `.set()` of a primary-key composite with a value other than the key's
+     * (#133): it identifies the item and cannot change. It was silently dropped;
+     * the update types already exclude it. The key's own value is a no-op, so a
+     * spread record keeps working.
+     */
+    const refusedRecordSet = (updates, key) => {
+        if (typeof updates !== "object" || updates === null)
+            return undefined;
+        const record = updates;
+        const keyRecord = (key ?? {});
+        const primary = allIndexes.primary;
+        for (const field of primary ? [...primary.pk.composite, ...primary.sk.composite] : []) {
+            if (record[field] === undefined || Equal.equals(record[field], keyRecord[field]))
+                continue;
+            return (`.set() of "${field}": "${field}" is a primary-key composite — it identifies the item ` +
+                "and cannot be changed by an update.");
+        }
+        return undefined;
+    };
+    /**
+     * The immutable fields a `.set()` names, in stored form (#133). An update may
+     * restate an immutable field's value — a spread record does — but never
+     * change it: each one is checked against the item (read, or a condition on
+     * the write) and a different value is refused.
+     */
+    const assertedImmutables = (updates) => {
+        if (typeof updates !== "object" || updates === null)
+            return [];
+        const record = updates;
+        const out = [];
+        for (const field of immutableFields) {
+            if (record[field] === undefined)
+                continue;
+            const encoded = encodePathValue([field], record[field], "value");
+            if (encoded.issue !== undefined) {
+                return `.set() of immutable "${field}": ${String(encoded.issue)}`;
+            }
+            out.push({ field, attr: resolveDbName(field), value: toAttributeValue(encoded.encoded) });
+        }
+        return out;
+    };
+    const immutableMismatch = (asserted, stored) => {
+        const changed = asserted.find(({ attr, value }) => !attributeValueEquals(stored[attr], value));
+        return changed === undefined
+            ? undefined
+            : `.set() of "${changed.field}": "${changed.field}" is immutable and the update's value ` +
+                "differs from the stored one.";
+    };
+    /**
+     * Whether an update can safely create the item it names (#133): its payload
+     * supplies every required model field and every primary-key composite, so
+     * the item it writes decodes. Anything less on a missing item would leave a
+     * partial row behind — those updates require the item to exist.
+     */
+    const completeUpsertPayload = (updates) => {
+        if (typeof updates !== "object" || updates === null)
+            return false;
+        const record = updates;
+        const present = (field) => record[field] !== undefined && record[field] !== null;
+        const primary = allIndexes.primary;
+        if (primary && ![...primary.pk.composite, ...primary.sk.composite].every(present))
+            return false;
+        for (const [field, fieldSchema] of Object.entries(data.modelFields)) {
+            const ast = fieldSchema.ast;
+            if (ast.context?.isOptional === true)
+                continue;
+            // A decoding default (optional on the stored side): `put` may omit it too.
+            if (ast.encoding?.[ast.encoding.length - 1]?.to.context?.isOptional === true)
+                continue;
+            const ref = resolvedRefs.find((r) => r.fieldName === field);
+            if (present(field) || (ref !== undefined && present(ref.idFieldName)))
+                continue;
+            return false;
+        }
+        return true;
+    };
     // schema + tableTag are injected via _configure() when the entity is registered
     // on a Table and bound through DynamoClient.make(); captured by operation closures.
     let schema;
@@ -430,9 +870,115 @@ const makeImpl = (config, precomputedData) => {
         // put error channel.
         Effect.orDie);
     };
+    /**
+     * The model fields with a decoding default (`Schema.withDecodingDefault` and
+     * kin: optional on the stored side, required on the domain side).
+     */
+    const defaultedFields = Object.entries(data.modelFields).filter(([, field]) => {
+        const ast = field.ast;
+        return (ast.context?.isOptional !== true &&
+            ast.encoding?.[ast.encoding.length - 1]?.to.context?.isOptional === true);
+    });
+    /**
+     * Fill each omitted decoding-default field that an INDEX key derives from —
+     * a primary-key, GSI or LSI composite — with its default (#133), so the item
+     * stores it, its keys compose from it, and the item, its keys and its decoded
+     * read all agree. Left out, the item had no index keys while its decoded
+     * record named a value the index is keyed by. A default never creates a
+     * unique sentinel (`unsentineledDefaults`); other defaulted fields keep
+     * their contract: not stored, defaulted on read.
+     */
+    /** The defaulted fields an index key derives from — materialised when omitted. */
+    const indexedDefaultFields = () => {
+        const composites = new Set(Object.values(allIndexes).flatMap((def) => [...def.pk.composite, ...def.sk.composite]));
+        return new Set(defaultedFields.map(([name]) => name).filter((name) => composites.has(name)));
+    };
+    /**
+     * The unique-constraint fields a write's input omits but stores a default
+     * for (an index composite): the item lists them in `__edd_d__`, and no
+     * sentinel is composed from them — a default never creates a sentinel.
+     */
+    const unsentineledDefaults = (input) => {
+        if (config.unique == null || typeof input !== "object" || input === null)
+            return [];
+        const record = input;
+        const unique = new Set(Object.values(config.unique).flatMap((def) => [...resolveUniqueFields(def)]));
+        return [...indexedDefaultFields()].filter((name) => unique.has(name) && record[name] === undefined);
+    };
+    /**
+     * An update's `.remove()` of a defaulted index composite: the field would
+     * read back as its default while its index keys were dropped. It becomes a
+     * `.set()` of the default instead (#133) — stored, keys recomposed from it —
+     * and the fields so defaulted are returned (a unique one then holds only a
+     * default: `__edd_d__`).
+     */
+    const rematerializeRemovedDefaults = (uState) => {
+        const indexed = indexedDefaultFields();
+        const removed = (uState.remove ?? []).filter((field) => indexed.has(field));
+        if (removed.length === 0)
+            return Effect.succeed({ state: uState, defaulted: [] });
+        const fields = defaultedFields.filter(([name]) => removed.includes(name));
+        return Schema.decodeUnknownEffect(Schema.Struct(Object.fromEntries(fields)))({}).pipe(Effect.map((defaults) => ({
+            state: {
+                ...uState,
+                remove: (uState.remove ?? []).filter((field) => !removed.includes(field)),
+                updates: {
+                    ...(uState.updates ?? {}),
+                    ...defaults,
+                },
+            },
+            defaulted: removed,
+        })), Effect.mapError((cause) => new ValidationError({ entityType, operation: "update.default", cause })));
+    };
+    const fillDecodingDefaults = (input) => {
+        if (defaultedFields.length === 0 || typeof input !== "object" || input === null) {
+            return Effect.succeed(input);
+        }
+        const record = input;
+        const keyed = indexedDefaultFields();
+        const missing = defaultedFields.filter(([name]) => keyed.has(name) && record[name] === undefined);
+        if (missing.length === 0)
+            return Effect.succeed(input);
+        return Schema.decodeUnknownEffect(Schema.Struct(Object.fromEntries(missing)))({}).pipe(Effect.map((defaults) => ({ ...record, ...defaults })), Effect.mapError((cause) => new ValidationError({ entityType, operation: "put.default", cause })));
+    };
+    /** Whether `input` omits a defaulted field an index key derives from (see `fillDecodingDefaults`). */
+    const omitsIndexedDefault = (input) => {
+        if (defaultedFields.length === 0 || typeof input !== "object" || input === null)
+            return false;
+        const record = input;
+        return [...indexedDefaultFields()].some((name) => record[name] === undefined);
+    };
     /** Attach the model class prototype to a decoded plain object (when model is Schema.Class). */
     const attachPrototype = (decoded) => isSchemaClass ? Object.assign(Object.create(rawModel.prototype), decoded) : decoded;
+    /**
+     * An item of a versioned entity with an incarnation token but no version
+     * (#133). A versioned entity stamps the token when it creates an item, so
+     * only an item written before the entity was `versioned` may lack a version
+     * — and it lacks the token too. Token without version: the version was
+     * removed outside the library. Reading it as version 0 would let the next
+     * update rewrite the item's history, so every read and write refuses it.
+     */
+    const versionCorruption = (item, operation) => systemFields.version &&
+        item !== undefined &&
+        item[systemFields.version] === undefined &&
+        item[INCARNATION_TOKEN] !== undefined
+        ? new ValidationError({
+            entityType,
+            operation,
+            cause: `The ${entityType} item has an incarnation token (${INCARNATION_TOKEN}) but no ` +
+                `"${systemFields.version}" attribute: its version was removed outside the library. ` +
+                "It is refused rather than read as version 0, which would let an update overwrite " +
+                "its version history. Restore the version attribute.",
+        })
+        : undefined;
+    const checkVersion = (item, operation) => {
+        const corruption = versionCorruption(item, operation);
+        return corruption === undefined ? Effect.void : Effect.fail(corruption);
+    };
     const decodeRecord = (raw) => {
+        const corruption = versionCorruption(raw, "decode");
+        if (corruption !== undefined)
+            return Effect.fail(corruption);
         deserializeSparseFields(raw);
         renameFromDynamo(raw);
         return Schema.decodeUnknownEffect(schemas.recordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
@@ -443,6 +989,9 @@ const makeImpl = (config, precomputedData) => {
     };
     /** Decode a raw item using the schema selected by mode */
     const decodeAs = (raw, marshalled, mode) => {
+        const corruption = versionCorruption(raw, "decode");
+        if (corruption !== undefined)
+            return Effect.fail(corruption);
         if (mode === "native")
             return Effect.succeed(marshalled);
         // Collect flattened sparse-map attributes back into the domain Record.
@@ -816,6 +1365,570 @@ const makeImpl = (config, precomputedData) => {
         }
         return { sets, removes };
     });
+    // ---------------------------------------------------------------------------
+    // Update concurrency and return values (#133)
+    // ---------------------------------------------------------------------------
+    /**
+     * What proves an item is the same INCARNATION as the one read — not a
+     * deleted-and-recreated item at the same version: a hidden per-incarnation
+     * token, `__edd_i__`, a random UUID set when the item is created (put,
+     * create, upsert, batch / transaction put). `createdAt` would not do: two
+     * creates in the same millisecond, or a caller-supplied value, repeat it.
+     * Only versioned entities need it — their version CAS is what it completes.
+     */
+    const incarnationAttr = systemFields.version ? INCARNATION_TOKEN : undefined;
+    const stampsIncarnation = incarnationAttr === INCARNATION_TOKEN;
+    const freshIncarnation = freshIncarnationToken;
+    /**
+     * The condition (and its names / values) proving the stored item is still
+     * the incarnation `read` — `undefined` when the entity needs no proof.
+     */
+    const incarnationGuard = (read, names, values) => {
+        if (incarnationAttr === undefined)
+            return undefined;
+        names["#inc"] = incarnationAttr;
+        const value = read[incarnationAttr];
+        if (value === undefined)
+            return "attribute_not_exists(#inc)";
+        values[":inc"] = value;
+        return "#inc = :inc";
+    };
+    /**
+     * The version an item is stored at: `undefined` for no item, 0 for an item
+     * written before the entity was `versioned` (it has no version attribute;
+     * real versions start at 1).
+     */
+    const storedVersionOf = (item) => {
+        if (item === undefined || !systemFields.version)
+            return undefined;
+        const attr = item[systemFields.version];
+        return attr !== undefined ? Number(attr.N) : 0;
+    };
+    /**
+     * A version-snapshot Put that never overwrites history (#133). The
+     * `v#<version>` row may already exist only as a snapshot of the SAME state —
+     * a retain `put` writes `v#0000001` and the first update snapshots that same
+     * version 1 state again; a restore re-writes the delete-time snapshot — so
+     * the row is replaced only when it holds the same version, the same
+     * incarnation and (with timestamps) the same `updatedAt`. Any other row is a
+     * different history, and the write is refused.
+     */
+    const snapshotPut = (tableName, snapshotItem) => {
+        const names = { "#snap": config.indexes.primary.pk.field };
+        const values = {};
+        const same = [];
+        if (systemFields.version) {
+            const version = snapshotItem[systemFields.version];
+            same.push(versionIs(typeof version === "number" ? version : 0, names, values, "#snapVer", ":snapVer"));
+        }
+        const sameAs = (attr, tag) => {
+            names[`#${tag}`] = attr;
+            const value = snapshotItem[attr];
+            if (value === undefined) {
+                same.push(`attribute_not_exists(#${tag})`);
+            }
+            else {
+                values[`:${tag}`] = toAttributeValue(value);
+                same.push(`#${tag} = :${tag}`);
+            }
+        };
+        sameAs(INCARNATION_TOKEN, "snapInc");
+        if (systemFields.updatedAt)
+            sameAs(systemFields.updatedAt, "snapUpd");
+        return {
+            TableName: tableName,
+            Item: toAttributeMap(snapshotItem),
+            ConditionExpression: `attribute_not_exists(#snap) OR (${same.join(" AND ")})`,
+            ExpressionAttributeNames: names,
+            ...(Object.keys(values).length > 0 && { ExpressionAttributeValues: values }),
+        };
+    };
+    /** A version snapshot Put refused: that version's history row already exists. */
+    const historyConflict = (version, operation) => new ValidationError({
+        entityType,
+        operation,
+        cause: `The ${entityType} version ${version} snapshot already exists: the item's version is ` +
+            "inconsistent with its history, and history is never overwritten. Nothing was written.",
+    });
+    /**
+     * The condition that the stored version is `version` — for version 0 (an
+     * item written before the entity was `versioned`), that it has none (#133).
+     */
+    const versionIs = (version, names, values, name, value) => {
+        names[name] = systemFields.version;
+        if (version === 0)
+            return `attribute_not_exists(${name})`;
+        values[value] = toAttributeValue(version);
+        return `${name} = ${value}`;
+    };
+    /**
+     * Which predicate rejected a version-conditioned (or user-conditioned)
+     * write. The write asked for `ReturnValuesOnConditionCheckFailure: "ALL_OLD"`,
+     * so DynamoDB hands back the item as stored: a version other than the one
+     * the write was conditioned on — or another incarnation at that version — is
+     * a lost race; otherwise the user's `.condition()` rejected it. No item back
+     * means the item is gone — a race when the write was version-conditioned.
+     */
+    const conditionRejection = (key, stored, cas, userCondition) => {
+        const storedVersion = storedVersionOf(stored);
+        const otherIncarnation = cas?.read !== undefined &&
+            incarnationAttr !== undefined &&
+            !attributeValueEquals(stored?.[incarnationAttr], cas.read[incarnationAttr]);
+        if ((cas !== undefined && (storedVersion !== cas.version || otherIncarnation)) ||
+            !userCondition) {
+            return new OptimisticLockError({
+                entityType,
+                key,
+                expectedVersion: cas?.version ?? -1,
+                actualVersion: storedVersion ?? -1,
+            });
+        }
+        return new ConditionalCheckFailed({ entityType, key });
+    };
+    /**
+     * A condition the library sends — its own guard plus the user's
+     * `.condition()` — that exceeds DynamoDB's limits on one expression (4 KB,
+     * 300 operators and functions): refused BEFORE writing (#133).
+     */
+    const oversizedCondition = (operation, condition, user) => {
+        if (condition === undefined || expressionFits(condition))
+            return undefined;
+        const own = expressionCost(user);
+        return new ValidationError({
+            entityType,
+            operation,
+            cause: `The ${operation}'s condition is ${expressionCost(condition).length} characters / ` +
+                `${expressionCost(condition).operators} operators — beyond DynamoDB's limits on one ` +
+                `expression (${EXPRESSION_LIMIT} characters, ${OPERATOR_LIMIT} operators). The ` +
+                `.condition() alone is ${own.length} characters / ${own.operators} operators, and ` +
+                "the library's own guard needs room beside it: simplify the condition.",
+        });
+    };
+    /** The domain field a stored attribute holds (`storedAs` renames reversed). */
+    const domainNameOf = (attr) => Object.keys(data.modelFields).find((field) => resolveDbName(field) === attr) ?? attr;
+    /**
+     * The condition a read-then-write DELETE carries (#133): the item is still
+     * what the tombstone, snapshot and sentinel deletes were derived from.
+     * Versioned: its version and incarnation. Otherwise: it exists and every
+     * attribute in `dependsOn` still holds the value read (absent ones still
+     * absent). `"item"` means the whole item — a tombstone copies all of it —
+     * so every stored attribute is guarded, plus every attribute the entity
+     * knows of that was absent; an item too wide for that falls back to the
+     * strongest guard within DynamoDB's expression limit (never a refusal).
+     */
+    const deleteGuard = (read, dependsOn, 
+    /** The rest of the condition, ANDed with the guard (the user's, …). */
+    others) => {
+        // Whether a guard fits beside `others` within DynamoDB's real limits.
+        const fits = (guard) => expressionFits(others === undefined || others === "" ? guard : `${guard} AND (${others})`);
+        const names = {};
+        const values = {};
+        const parts = [];
+        const pkField = config.indexes.primary.pk.field;
+        const skField = config.indexes.primary.sk.field;
+        if (systemFields.version) {
+            names["#dver"] = systemFields.version;
+            // An item written before the entity was `versioned` has no version.
+            const readVersion = read[systemFields.version];
+            if (readVersion === undefined) {
+                parts.push("attribute_not_exists(#dver)");
+            }
+            else {
+                values[":dver"] = readVersion;
+                parts.push("#dver = :dver");
+            }
+            const incarnation = incarnationGuard(read, names, values);
+            if (incarnation !== undefined)
+                parts.push(incarnation);
+            const expression = parts.join(" AND ");
+            if (!fits(expression))
+                return tooLargeBeside(expression);
+            return { expression, names, values, inputs: [] };
+        }
+        names["#dpk"] = pkField;
+        parts.push("attribute_exists(#dpk)");
+        if (!fits(parts.join(" AND ")))
+            return tooLargeBeside(parts.join(" AND "));
+        const attrs = dependsOn === "item"
+            ? [
+                ...new Set([
+                    ...Object.keys(read),
+                    ...Object.keys(data.modelFields).map(resolveDbName),
+                    ...[systemFields.createdAt, systemFields.updatedAt].filter((f) => typeof f === "string"),
+                    ...gsiKeyFields(),
+                    ...vectorKeyFields(),
+                ]),
+            ].filter((attr) => attr !== pkField && attr !== skField)
+            : dependsOn;
+        const guardOf = (attr, i) => {
+            names[`#dg${i}`] = attr;
+            if (read[attr] === undefined)
+                return `attribute_not_exists(#dg${i})`;
+            values[`:dg${i}`] = read[attr];
+            return `#dg${i} = :dg${i}`;
+        };
+        const full = [...parts, ...attrs.map(guardOf)].join(" AND ");
+        if (fits(full))
+            return { expression: full, names, values, inputs: attrs };
+        // Too wide to guard attribute by attribute (a sparse map with hundreds of
+        // entries): the strongest guard that fits. Every library write sets
+        // `updatedAt`, so with timestamps it alone detects any library update;
+        // then as many attributes as fit, those the sentinels derive from first,
+        // then the model's own fields, then the rest.
+        for (const key of Object.keys(names))
+            if (key.startsWith("#dg"))
+                delete names[key];
+        for (const key of Object.keys(values))
+            if (key.startsWith(":dg"))
+                delete values[key];
+        const uniqueAttrs = Object.values(config.unique ?? {}).flatMap((def) => resolveUniqueFields(def).map(resolveDbName));
+        const modelAttrs = Object.keys(data.modelFields).map(resolveDbName);
+        const ordered = [
+            ...new Set([
+                ...(systemFields.updatedAt ? [systemFields.updatedAt] : []),
+                ...uniqueAttrs,
+                ...modelAttrs,
+                ...attrs.slice().sort(),
+            ]),
+        ].filter((attr) => attrs.includes(attr));
+        const inputs = [];
+        let expression = parts.join(" AND ");
+        for (const attr of ordered) {
+            const clause = guardOf(attr, inputs.length);
+            if (!fits(`${expression} AND ${clause}`)) {
+                delete names[`#dg${inputs.length}`];
+                delete values[`:dg${inputs.length}`];
+                continue;
+            }
+            expression = `${expression} AND ${clause}`;
+            inputs.push(attr);
+        }
+        return { expression, names, values, inputs };
+        function tooLargeBeside(guard) {
+            return (oversizedCondition("write", others === undefined || others === "" ? guard : `${guard} AND (${others})`, others) ?? new ValidationError({ entityType, operation: "write", cause: "condition too large" }));
+        }
+    };
+    /** Which predicate rejected a guarded delete — from the stored item (ALL_OLD). */
+    const deleteRejection = (key, read, inputs, stored, userCondition) => {
+        if (stored === undefined)
+            return new ItemNotFound({ entityType, key });
+        if (systemFields.version) {
+            return conditionRejection(key, stored, { version: storedVersionOf(read), read }, userCondition);
+        }
+        const changed = inputs.filter((attr) => !attributeValueEquals(stored[attr], read[attr]));
+        if (changed.length === 0 && userCondition)
+            return new ConditionalCheckFailed({ entityType, key });
+        return new ConcurrentModification({
+            entityType,
+            key,
+            attributes: changed.map(domainNameOf),
+            current: Option.none(),
+        });
+    };
+    /** Fill a `ConcurrentModification`'s `current` with the stored item, decoded. */
+    const withCurrentItem = (effect, stored) => effect.pipe(Effect.catchIf((e) => e instanceof ConcurrentModification, (e) => Effect.gen(function* () {
+        const item = stored();
+        const current = item === undefined
+            ? Option.none()
+            : yield* Effect.option(decodeAs(fromAttributeMap(item), item, "model"));
+        return yield* keepReleaseRace(e, new ConcurrentModification({ ...e, current }));
+    })));
+    /**
+     * The item a retain path update wrote, read back after its transaction. The
+     * write is proven by version AND incarnation: within one incarnation a
+     * version is written exactly once, so the live item is ours while it holds
+     * our version and incarnation; once a later write replaced it, the
+     * `v#<ourVersion>` snapshot that write took is ours — if it carries our
+     * incarnation (a snapshot left by an earlier incarnation of the item does
+     * not). It is restored to item shape: what a snapshot strips (index and
+     * vector attributes) or adds (its sort key and TTL) comes from the item we
+     * replaced plus this update's own writes. Without a proven post-image the
+     * update still WAS applied: {@link UpdateAppliedButUnreadable}.
+     */
+    const readRetainPostImage = (tableName, marshalledKey, replaced, ourVersion, ourIncarnation, derivedSets, derivedRemoves, ttlAttrName, encodedKey) => Effect.gen(function* () {
+        const client = yield* DynamoClient;
+        const ours = (item) => item !== undefined &&
+            (incarnationAttr === undefined ||
+                attributeValueEquals(item[incarnationAttr], ourIncarnation));
+        const current = (yield* client.getItem({
+            TableName: tableName,
+            Key: marshalledKey,
+            ConsistentRead: true,
+        })).Item;
+        if (storedVersionOf(current) === ourVersion && ours(current))
+            return current;
+        const skField = config.indexes.primary.sk.field;
+        const snapshot = (yield* client.getItem({
+            TableName: tableName,
+            Key: {
+                ...marshalledKey,
+                [skField]: toAttributeValue(DynamoSchema.composeVersionKey(schema, entityType, ourVersion, historyKeyOptions(marshalledKey[skField]?.S))),
+            },
+            ConsistentRead: true,
+        })).Item;
+        if (!ours(snapshot)) {
+            return yield* new UpdateAppliedButUnreadable({
+                entityType,
+                key: encodedKey,
+                version: ourVersion,
+                reason: current === undefined
+                    ? "the item was deleted before it could be read back"
+                    : `the item moved past version ${ourVersion}, and no snapshot of this write ` +
+                        "remains to read it from",
+            });
+        }
+        const post = { ...snapshot };
+        post[skField] = marshalledKey[skField];
+        const restored = [
+            ...gsiKeyFields(),
+            ...vectorKeyFields(),
+            ...vectorIndexEntries.map(([, definition]) => definition.stashField),
+            ...(retainTtl() ? [ttlAttrName] : []),
+        ];
+        for (const field of restored) {
+            delete post[field];
+            if (replaced[field] !== undefined)
+                post[field] = replaced[field];
+        }
+        Object.assign(post, derivedSets);
+        for (const field of derivedRemoves)
+            delete post[field];
+        return post;
+    });
+    /**
+     * Decode only `attributes` of a stored image (`updatedOld` / `updatedNew`):
+     * a partial — the fields present, each through its own schema.
+     */
+    const decodePartial = (image, attributes, mode) => {
+        const corruption = versionCorruption(image, "decode");
+        if (corruption !== undefined)
+            return Effect.fail(corruption);
+        const projected = {};
+        for (const [attr, value] of Object.entries(image ?? {})) {
+            if (attributes.has(attr))
+                projected[attr] = value;
+        }
+        if (mode === "native")
+            return Effect.succeed(projected);
+        const raw = fromAttributeMap(projected);
+        deserializeSparseFields(raw);
+        renameFromDynamo(raw);
+        const target = mode === "model"
+            ? schemas.modelSchema
+            : mode === "record"
+                ? schemas.recordSchema
+                : schemas.itemSchema;
+        const fields = target.fields;
+        const present = Object.fromEntries(Object.entries(fields).filter(([name]) => name in raw));
+        return Schema.decodeUnknownEffect(Schema.Struct(present))(raw).pipe(Effect.mapError((cause) => new ValidationError({ entityType, operation: "decode", cause })));
+    };
+    /**
+     * The value an update returns for its `returnValues` mode, from the item
+     * before (`old`) and after (`next`) it, and the attributes it wrote:
+     * `none` → `undefined`; `allOld` / `allNew` → the whole item; `updatedOld` /
+     * `updatedNew` → just the written attributes, decoded as a partial.
+     */
+    const updateResult = (rv, old, next, written, mode, encodedKey) => {
+        switch (rv) {
+            case "none":
+                return Effect.succeed(undefined);
+            case "updatedOld":
+                return decodePartial(old, written, mode);
+            case "updatedNew":
+                return decodePartial(next, written, mode);
+            default: {
+                const image = rv === "allOld" ? old : next;
+                if (image === undefined)
+                    return Effect.fail(new ItemNotFound({ entityType, key: encodedKey }));
+                return decodeAs(fromAttributeMap(image), image, mode);
+            }
+        }
+    };
+    /**
+     * The history keys (version snapshots, soft-delete tombstones) of the item
+     * whose live sort key is `liveSk` (#133). An entity whose primary sort key
+     * has composites holds several items per partition, so each item's history
+     * keys carry its segment — the composite part of `liveSk` — and items never
+     * share a version sequence, a snapshot or a tombstone. Without sort key
+     * composites there is one item per partition and no segment: the keys are
+     * byte-identical to the partition-wide ones every earlier release wrote.
+     */
+    const historyKeyOptions = (liveSk) => {
+        if (typeof liveSk !== "string")
+            return undefined;
+        const item = KeyComposer.composeHistoryItemSegment(schema, entityType, entityVersion, config.indexes.primary, liveSk);
+        return item === undefined ? undefined : { item };
+    };
+    /**
+     * See {@link Entity._liveRows}. A row is dropped only when it is positively
+     * history: its sort key is not the one its own composites compose (or they
+     * don't compose) AND it has the layout of a snapshot (`#v#…<version>`), a
+     * tombstone (`#deleted#…<timestamp>`) or a time-series event (`#e#` under
+     * the live key). Any other row is kept and decoded as before — including
+     * rows an earlier release keyed differently (an unpadded number composite),
+     * which the current composer can't reproduce.
+     */
+    const liveRows = () => {
+        if (!isRetainEnabled() && !isSoftDeleteEnabled() && config.timeSeries === undefined) {
+            return undefined;
+        }
+        const primary = config.indexes.primary;
+        const skField = primary.sk.field;
+        const compositeAttrs = primary.sk.composite.map(resolveDbName);
+        const versions = DynamoSchema.composeVersionKeyPrefix(schema, entityType);
+        const tombstones = DynamoSchema.composeDeletedKeyPrefix(schema, entityType);
+        const bare = KeyComposer.composeSk(schema, entityType, entityVersion, { ...primary, sk: { ...primary.sk, composite: [] } }, keyForm({}));
+        const eventMarker = KeyComposer.composeEventSkPrefix("", schema.casing);
+        const historyShaped = (sk) => (isRetainEnabled() &&
+            sk.startsWith(versions) &&
+            /^(?:.*#)?\d{7,}$/.test(sk.slice(versions.length))) ||
+            (isSoftDeleteEnabled() &&
+                sk.startsWith(tombstones) &&
+                /^(?:.*#)?\d{4}-\d\d-\d\dT[^#]*$/.test(sk.slice(tombstones.length))) ||
+            (config.timeSeries !== undefined &&
+                sk.startsWith(bare) &&
+                sk.slice(bare.length).includes(eventMarker));
+        return {
+            isLive: (row) => {
+                const sk = row[skField]?.S;
+                if (sk === undefined)
+                    return true;
+                // Only the composites are unmarshalled: the row may be large.
+                const composites = {};
+                for (const attr of compositeAttrs) {
+                    const value = row[attr];
+                    if (value !== undefined)
+                        composites[attr] = value;
+                }
+                try {
+                    if (liveSkOf(toDomainView(fromAttributeMap(composites))) === sk)
+                        return true;
+                }
+                catch {
+                    // Not composable now: judged by its layout alone.
+                }
+                return !historyShaped(sk);
+            },
+            reads: [skField, ...compositeAttrs],
+        };
+    };
+    // ---------------------------------------------------------------------------
+    // History an earlier release wrote without an item segment (#133)
+    // ---------------------------------------------------------------------------
+    /**
+     * Whether the entity's history keys carry an item segment — its primary sort
+     * key has composites. Only then can history an earlier release wrote, under
+     * the partition-wide keys (`#v#0000003`, `#deleted#<ts>`), be in the
+     * partition: every reader of one item's history also reads those rows, and
+     * takes the ones whose stored composites compose the item's live key. A
+     * version held both ways is read from the segmented row.
+     */
+    const hasItemHistory = config.indexes.primary.sk.composite.length > 0;
+    /** Whether a stored (attribute-keyed) row is the history of the item at `liveSk`. */
+    const isItemsRow = (row, liveSk) => {
+        try {
+            return liveSkOf(toDomainView(fromAttributeMap(row))) === liveSk;
+        }
+        catch {
+            return false;
+        }
+    };
+    /**
+     * The item's unsegmented history rows of one kind, in sort key order (latest
+     * first with `descending`), stopping at the first with `first`. Unsegmented
+     * rows sort before every segmented one — a version or timestamp starts with
+     * a digit, a segment with a composite name — so a key range bounds them.
+     */
+    const legacyHistory = (args) => Effect.gen(function* () {
+        const client = yield* DynamoClient;
+        const primary = config.indexes.primary;
+        const prefix = args.kind === "version"
+            ? DynamoSchema.composeVersionKeyPrefix(schema, entityType)
+            : DynamoSchema.composeDeletedKeyPrefix(schema, entityType);
+        const range = {
+            TableName: args.tableName,
+            KeyConditionExpression: "#pk = :pk AND #sk BETWEEN :lo AND :hi",
+            ExpressionAttributeNames: { "#pk": primary.pk.field, "#sk": primary.sk.field },
+            ExpressionAttributeValues: {
+                ":pk": toAttributeValue(args.pk),
+                ":lo": toAttributeValue(`${prefix}0`),
+                ":hi": toAttributeValue(`${prefix}:`),
+            },
+            ConsistentRead: true,
+        };
+        // The common case — a partition no earlier release wrote history into —
+        // costs one `Limit 1` keys-only read. (A row it finds may still be
+        // segmented, if a segment starts with a digit; the read below filters.)
+        const probe = yield* client.query({ ...range, ProjectionExpression: "#sk", Limit: 1 });
+        if ((probe.Items ?? []).length === 0)
+            return [];
+        const rows = [];
+        let start;
+        do {
+            const result = yield* client.query({
+                ...range,
+                ScanIndexForward: !args.descending,
+                ExclusiveStartKey: start,
+            });
+            for (const row of result.Items ?? []) {
+                const sk = row[primary.sk.field]?.S ?? "";
+                if (sk.slice(prefix.length).includes("#") || !isItemsRow(row, args.liveSk))
+                    continue;
+                rows.push(row);
+                if (args.first)
+                    return rows;
+            }
+            start = result.LastEvaluatedKey;
+        } while (start !== undefined);
+        return rows;
+    });
+    /** The version a history sort key ends with. */
+    const versionOfSk = (sk) => {
+        if (sk === undefined)
+            return 0;
+        const version = Number(sk.slice(sk.lastIndexOf("#") + 1));
+        return Number.isInteger(version) ? version : 0;
+    };
+    /**
+     * The item's latest tombstone — its own, or one an earlier release wrote
+     * without a segment, whichever is later (its own on a tie).
+     */
+    const latestTombstone = (tableName, pk, liveSk) => Effect.gen(function* () {
+        const client = yield* DynamoClient;
+        const primary = config.indexes.primary;
+        const own = (yield* client.query({
+            TableName: tableName,
+            KeyConditionExpression: "#pk = :pk AND begins_with(#sk, :skPrefix)",
+            ExpressionAttributeNames: { "#pk": primary.pk.field, "#sk": primary.sk.field },
+            ExpressionAttributeValues: {
+                ":pk": toAttributeValue(pk),
+                ":skPrefix": toAttributeValue(DynamoSchema.composeDeletedKeyPrefix(schema, entityType, historyKeyOptions(liveSk))),
+            },
+            Limit: 1,
+            ScanIndexForward: false,
+        })).Items?.[0];
+        if (!hasItemHistory)
+            return own;
+        const [legacy] = yield* legacyHistory({
+            tableName,
+            pk,
+            liveSk,
+            kind: "deleted",
+            descending: true,
+            first: true,
+        });
+        if (legacy === undefined)
+            return own;
+        if (own === undefined)
+            return legacy;
+        const stamp = (row) => {
+            const sk = row[primary.sk.field]?.S ?? "";
+            return sk.slice(sk.lastIndexOf("#") + 1);
+        };
+        return stamp(legacy) > stamp(own) ? legacy : own;
+    });
+    /** The live sort key of the item at `encodedKey` (the caller's key, encoded). */
+    const liveSkOf = (encodedKey) => KeyComposer.composeSk(schema, entityType, entityVersion, config.indexes.primary, keyForm(encodedKey));
     /**
      * Build a version snapshot item: same PK, version SK, stripped GSI keys,
      * keeps __edd_e__ for entity type filtering.
@@ -824,7 +1937,9 @@ const makeImpl = (config, precomputedData) => {
      * passed in — the snapshot belongs to the same physical table, so it must
      * align with that table's `TimeToLiveSpecification.AttributeName`.
      */
-    const buildSnapshotItem = (item, version, _tablePkField, tableSkField, ttlAttrName, now) => {
+    const buildSnapshotItem = (item, version, _tablePkField, tableSkField, ttlAttrName, now, 
+    /** The item's live sort key, when `item` is not the live item (a tombstone). */
+    liveSk = item[tableSkField]) => {
         const snapshot = { ...item };
         // Strip GSI key fields — snapshots must not appear in index queries
         for (const field of gsiKeyFields()) {
@@ -844,7 +1959,7 @@ const makeImpl = (config, precomputedData) => {
             delete snapshot[definition.stashField];
         }
         // Replace SK with version SK
-        snapshot[tableSkField] = DynamoSchema.composeVersionKey(schema, entityType, version);
+        snapshot[tableSkField] = DynamoSchema.composeVersionKey(schema, entityType, version, historyKeyOptions(liveSk));
         // Add optional TTL
         const ttl = retainTtl();
         if (ttl) {
@@ -869,63 +1984,403 @@ const makeImpl = (config, precomputedData) => {
             features.push("softDelete");
         return features;
     };
+    // ---------------------------------------------------------------------------
+    // Unique sentinels: reservation and release (#133)
+    // ---------------------------------------------------------------------------
+    /**
+     * The sentinel item reserving `key` for the item at `owner`. `_entity_pk` /
+     * `_entity_sk` name the reserving item — the back-pointer a release checks
+     * (see {@link ownedSentinels}).
+     */
+    const sentinelItemFor = (constraintName, constraintDef, key, owner, now, ttlAttrName) => {
+        const sentinel = {
+            [config.indexes.primary.pk.field]: key.pk,
+            [config.indexes.primary.sk.field]: key.sk,
+            __edd_e__: `${entityType}._unique.${constraintName}`,
+            _entity_pk: owner.pk,
+            _entity_sk: owner.sk,
+        };
+        // Optional TTL — when the constraint declares one, the sentinel
+        // auto-expires (time-bounded uniqueness reservation/hold).
+        const uniqueTtl = resolveUniqueTtl(constraintDef);
+        if (uniqueTtl !== undefined) {
+            sentinel[ttlAttrName] = DateTime.toEpochSeconds(now) + normalizeTtlSeconds(uniqueTtl);
+        }
+        return sentinel;
+    };
+    /**
+     * The sentinels among `candidates` that the item at `owner` holds, read
+     * consistently (#133). An item can hold a unique value WITHOUT owning its
+     * sentinel: the constraint was added after the item was written, the item
+     * was written outside the library, or a `ttl`'d reservation expired and
+     * another item then claimed the value. That other item owns the sentinel
+     * now — its `_entity_pk` / `_entity_sk` name it — and releasing the
+     * sentinel by key alone would delete its reservation and let the value be
+     * taken twice. So a write releases only the sentinels this returns, each
+     * under {@link sentinelRelease}.
+     */
+    const ownedSentinels = (tableName, candidates, owner) => Effect.gen(function* () {
+        if (candidates.length === 0)
+            return [];
+        const client = yield* DynamoClient;
+        const pkField = config.indexes.primary.pk.field;
+        const skField = config.indexes.primary.sk.field;
+        const ownerPk = toAttributeValue(owner.pk);
+        const ownerSk = toAttributeValue(owner.sk);
+        const reads = yield* Effect.forEach(candidates, (key) => client.getItem({
+            TableName: tableName,
+            Key: toAttributeMap({ [pkField]: key.pk, [skField]: key.sk }),
+            ConsistentRead: true,
+            ProjectionExpression: "#epk, #esk",
+            ExpressionAttributeNames: { "#epk": "_entity_pk", "#esk": "_entity_sk" },
+        }), { concurrency: "unbounded" });
+        return candidates.filter((_, i) => {
+            const stored = reads[i]?.Item;
+            return (stored !== undefined &&
+                attributeValueEquals(stored._entity_pk, ownerPk) &&
+                attributeValueEquals(stored._entity_sk, ownerSk));
+        });
+    });
+    /**
+     * The Delete releasing a sentinel {@link ownedSentinels} found owned by
+     * `owner` — conditioned on that ownership still holding, so a reservation
+     * that changed hands between the read and the write cancels the write
+     * instead of being deleted.
+     */
+    const sentinelRelease = (tableName, key, owner) => ({
+        Delete: {
+            TableName: tableName,
+            Key: toAttributeMap({
+                [config.indexes.primary.pk.field]: key.pk,
+                [config.indexes.primary.sk.field]: key.sk,
+            }),
+            ConditionExpression: "#epk = :epk AND #esk = :esk",
+            ExpressionAttributeNames: { "#epk": "_entity_pk", "#esk": "_entity_sk" },
+            ExpressionAttributeValues: {
+                ":epk": toAttributeValue(owner.pk),
+                ":esk": toAttributeValue(owner.sk),
+            },
+        },
+    });
+    /**
+     * A sentinel release cancelled: the reservation changed hands between the
+     * read and the write. Nothing was written; the item still holds the value.
+     */
+    const releaseRaced = (key, constraintName) => {
+        const error = new ConcurrentModification({
+            entityType,
+            key,
+            attributes: [...resolveUniqueFields(config.unique[constraintName])],
+            current: Option.none(),
+        });
+        releaseRaces.add(error);
+        return error;
+    };
+    // ---------------------------------------------------------------------------
+    // Guarded puts (#133)
+    // ---------------------------------------------------------------------------
     /**
-     * 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.
+     * The highest version retained for the item at `pk` — 0 with none. A
+     * deleted retain item's version snapshots outlive it, so the item created
+     * again at its key continues the sequence after them rather than
+     * overwriting its earlier incarnation's history.
+     */
+    const highestRetainedVersion = (tableName, pk, liveSk) => Effect.gen(function* () {
+        const client = yield* DynamoClient;
+        const primary = config.indexes.primary;
+        const { Items } = yield* client.query({
+            TableName: tableName,
+            KeyConditionExpression: "#pk = :pk AND begins_with(#sk, :prefix)",
+            ExpressionAttributeNames: { "#pk": primary.pk.field, "#sk": primary.sk.field },
+            ExpressionAttributeValues: {
+                ":pk": toAttributeValue(pk),
+                ":prefix": toAttributeValue(DynamoSchema.composeVersionKeyPrefix(schema, entityType, historyKeyOptions(liveSk))),
+            },
+            ScanIndexForward: false,
+            Limit: 1,
+            ConsistentRead: true,
+        });
+        const own = versionOfSk(Items?.[0]?.[primary.sk.field]?.S);
+        if (!hasItemHistory || typeof liveSk !== "string")
+            return own;
+        // History an earlier release wrote for this item counts too: a version it
+        // holds is never written again.
+        const [legacy] = yield* legacyHistory({
+            tableName,
+            pk,
+            liveSk,
+            kind: "version",
+            descending: true,
+            first: true,
+        });
+        return Math.max(own, versionOfSk(legacy?.[primary.sk.field]?.S));
+    });
+    /**
+     * A guarded put — of a versioned or unique-constrained entity — compiled
+     * against the item as read (#133). Shared by `put` / `create` / `upsert`
+     * and the transaction paths (`Transaction.transactWrite`,
+     * `EventStore.append`'s `additionalItems`), so they write the same items:
      *
-     * 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.
+     * - **The item exists:** its next version, its incarnation and its
+     *   `createdAt` (unless the caller supplies one); the Put is guarded on the
+     *   item read — version and incarnation, or the unique values its sentinels
+     *   derive from. Retain: the replaced item is snapshotted at its version.
+     * - **The item is missing** (or not read: `create`): the Put requires it
+     *   still missing. A retain item continues after the highest version
+     *   retained for its key — a deleted item's history outlives it — with a new
+     *   incarnation, and is snapshotted at that version.
+     * - **Sentinels:** a changed value takes the new reservation and releases the
+     *   old one — only if this item owns it ({@link ownedSentinels}).
      *
-     * `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.
+     * `verdict` reads a cancellation: a lost race or retained history the read
+     * did not see is retried by the caller (re-planned from a fresh read); the
+     * caller's own condition is `Condition`; a taken value or a history conflict
+     * is final.
      */
-    const buildPutSideItems = (item, now, ttlAttrName) => {
-        const out = [];
+    const planPut = (args) => Effect.gen(function* () {
+        const client = yield* DynamoClient;
         const pkField = config.indexes.primary.pk.field;
         const skField = config.indexes.primary.sk.field;
-        const itemDomain = toDomainView(item);
+        const item = { ...args.item };
+        const owner = { pk: item[pkField], sk: item[skField] };
+        const current = args.create
+            ? undefined
+            : (yield* client.getItem({
+                TableName: args.tableName,
+                Key: toAttributeMap({ [pkField]: owner.pk, [skField]: owner.sk }),
+                ConsistentRead: true,
+            })).Item;
+        yield* checkVersion(current, args.operation);
+        const currentRaw = current !== undefined
+            ? fromAttributeMap(current)
+            : undefined;
+        const storedVersion = storedVersionOf(current);
+        if (currentRaw !== undefined) {
+            // The same item, continued: its next version, its incarnation, its
+            // creation time (unless the caller supplies one).
+            if (systemFields.version) {
+                item[systemFields.version] = (storedVersion ?? 0) + 1;
+                if (currentRaw[INCARNATION_TOKEN] !== undefined) {
+                    item[INCARNATION_TOKEN] = currentRaw[INCARNATION_TOKEN];
+                }
+            }
+            if (systemFields.createdAt && !args.createdAtSupplied) {
+                const createdAttr = resolveDbName(systemFields.createdAt);
+                if (currentRaw[createdAttr] !== undefined)
+                    item[createdAttr] = currentRaw[createdAttr];
+            }
+        }
+        else if (systemFields.version && isRetainEnabled()) {
+            item[systemFields.version] =
+                (yield* highestRetainedVersion(args.tableName, owner.pk, owner.sk)) + 1;
+        }
+        const marshalled = toAttributeMap(item);
+        // The main item. Missing: it must still be missing. Present: still the
+        // item read — its version and incarnation, or (unversioned) the unique
+        // values its sentinels are keyed by.
+        const uniqueAttrs = [
+            ...new Set(Object.values((config.unique ?? {}))
+                .flatMap((def) => [...resolveUniqueFields(def)])
+                .map(resolveDbName)),
+        ];
+        const userCondition = args.userCondition;
+        const guard = current === undefined
+            ? {
+                expression: "attribute_not_exists(#pk)",
+                names: { "#pk": pkField },
+                values: {},
+                inputs: [],
+            }
+            : deleteGuard(current, uniqueAttrs, userCondition?.expression);
+        if (guard instanceof ValidationError)
+            return yield* guard;
+        const mainValues = { ...guard.values, ...userCondition?.values };
+        const mainCondition = userCondition
+            ? `${guard.expression} AND (${userCondition.expression})`
+            : guard.expression;
+        const tooLarge = oversizedCondition(args.operation, mainCondition, userCondition?.expression);
+        if (tooLarge !== undefined)
+            return yield* tooLarge;
+        const items = [
+            {
+                Put: {
+                    TableName: args.tableName,
+                    Item: marshalled,
+                    ConditionExpression: mainCondition,
+                    ExpressionAttributeNames: { ...guard.names, ...userCondition?.names },
+                    ...(Object.keys(mainValues).length > 0 && { ExpressionAttributeValues: mainValues }),
+                    ReturnValuesOnConditionCheckFailure: "ALL_OLD",
+                },
+            },
+        ];
+        const roles = [{ kind: "main" }];
+        // Sentinels: a changed value takes the new reservation and releases the
+        // old one this item owns; an unchanged value is left alone. A field
+        // holding only a default has none (`__edd_d__`).
         if (config.unique != null) {
+            const newSource = toDomainView(item);
+            const oldSource = currentRaw !== undefined ? toDomainView(currentRaw) : undefined;
+            const changes = [];
             for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                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)
+                const next = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, newSource);
+                const prior = oldSource !== undefined
+                    ? composeUniqueSentinel(schema, entityType, constraintName, constraintDef, oldSource)
+                    : undefined;
+                if (next !== undefined &&
+                    prior !== undefined &&
+                    next.key.pk === prior.key.pk &&
+                    next.key.sk === prior.key.sk) {
+                    continue;
+                }
+                changes.push({ constraintName, constraintDef, next, prior: prior?.key });
+            }
+            const owned = new Set(yield* ownedSentinels(args.tableName, changes.flatMap((change) => (change.prior !== undefined ? [change.prior] : [])), owner));
+            for (const change of changes) {
+                if (change.prior !== undefined && owned.has(change.prior)) {
+                    items.push(sentinelRelease(args.tableName, change.prior, owner));
+                    roles.push({ kind: "release", constraintName: change.constraintName });
+                }
+                if (change.next === undefined)
+                    continue;
+                items.push({
+                    Put: {
+                        TableName: args.tableName,
+                        Item: toAttributeMap(sentinelItemFor(change.constraintName, change.constraintDef, change.next.key, owner, args.now, args.ttlAttrName)),
+                        ...sentinelGuard(),
+                    },
+                });
+                roles.push({
+                    kind: "sentinel",
+                    constraintName: change.constraintName,
+                    fields: change.next.fieldsRecord,
+                });
+            }
+        }
+        // Retain: the item replaced (at its version), or the new item at its own.
+        if (isRetainEnabled()) {
+            const version = currentRaw !== undefined ? (storedVersion ?? 0) : item[systemFields.version];
+            items.push({
+                Put: snapshotPut(args.tableName, buildSnapshotItem(currentRaw ?? item, version, pkField, skField, args.ttlAttrName, args.now)),
+            });
+            roles.push({ kind: "snapshot", version });
+        }
+        /** The stored attributes that differ from the item read. */
+        const changedFrom = (stored) => guard.inputs.filter((attr) => !attributeValueEquals(stored[attr], current?.[attr]));
+        /** A lost race on the main item: the error once retries run out. */
+        const lostRace = (stored) => ({
+            _tag: "Retry",
+            stored,
+            error: systemFields.version
+                ? new OptimisticLockError({
+                    entityType,
+                    key: args.key,
+                    expectedVersion: storedVersion ?? 0,
+                    actualVersion: storedVersionOf(stored) ?? -1,
+                })
+                : new ConcurrentModification({
+                    entityType,
+                    key: args.key,
+                    attributes: stored !== undefined && current !== undefined
+                        ? changedFrom(stored).map(domainNameOf)
+                        : [],
+                    current: Option.none(),
+                }),
+        });
+        const verdict = (reasons) => {
+            const main = reasons[0];
+            if (main?.Code === "ConditionalCheckFailed") {
+                const stored = main.Item;
+                // `create`: the item exists, or the caller's condition rejected it.
+                if (args.create)
+                    return { _tag: "Condition" };
+                if (current === undefined) {
+                    // Still missing: the caller's condition. Created since: a race.
+                    return stored === undefined && userCondition !== undefined
+                        ? { _tag: "Condition" }
+                        : lostRace(stored);
+                }
+                if (stored === undefined)
+                    return lostRace(stored);
+                const raced = systemFields.version
+                    ? storedVersionOf(stored) !== storedVersion ||
+                        (incarnationAttr !== undefined &&
+                            !attributeValueEquals(stored[incarnationAttr], current[incarnationAttr]))
+                    : changedFrom(stored).length > 0;
+                return raced || userCondition === undefined ? lostRace(stored) : { _tag: "Condition" };
+            }
+            for (let i = 1; i < roles.length; i++) {
+                if (reasons[i]?.Code !== "ConditionalCheckFailed")
                     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);
+                const role = roles[i];
+                switch (role.kind) {
+                    case "sentinel":
+                        return {
+                            _tag: "Fail",
+                            error: new UniqueConstraintViolation({
+                                entityType,
+                                constraint: role.constraintName,
+                                fields: role.fields,
+                            }),
+                        };
+                    case "snapshot":
+                        // A missing item's snapshot: history the read did not see — retried
+                        // past it. A present item's: its version disagrees with its history.
+                        return current === undefined
+                            ? lostRace(undefined)
+                            : { _tag: "Fail", error: historyConflict(role.version, args.operation) };
+                    case "release":
+                        // The reservation changed hands since it was read.
+                        return {
+                            _tag: "Retry",
+                            stored: current,
+                            error: releaseRaced(args.key, role.constraintName),
+                        };
                 }
-                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(),
-                });
+            }
+            return undefined;
+        };
+        return { items, item, marshalled, verdict };
+    });
+    /**
+     * Run a guarded put to completion (#133): plan it from a fresh read, write
+     * it, and on a lost race — a concurrent create, replace or delete of the
+     * item, or retained history the read did not see — plan and write it again.
+     * A put replaces the whole item, so the last writer wins, as a plain
+     * `PutItem` would. Only the caller's own condition, a taken unique value or
+     * a history conflict fail it; a race lost on every attempt fails with the
+     * concurrency error.
+     */
+    const runGuardedPut = (args) => Effect.gen(function* () {
+        const client = yield* DynamoClient;
+        let lost;
+        for (let attempt = 0; attempt < GUARDED_PUT_ATTEMPTS; attempt++) {
+            const plan = yield* planPut(args);
+            yield* checkTransactionLimit(entityType, args.operation, plan.items);
+            const write = plan.items.length === 1
+                ? client.putItem(plan.items[0].Put)
+                : client.transactWriteItems({ TransactItems: [...plan.items] });
+            const verdict = yield* write.pipe(Effect.as(undefined), Effect.catch((err) => {
+                const reasons = isAwsTransactionCancelled(err.cause)
+                    ? (err.cause.CancellationReasons ?? [])
+                    : isAwsConditionalCheckFailed(err.cause)
+                        ? [{ Code: "ConditionalCheckFailed", Item: err.cause.Item }]
+                        : undefined;
+                const read = reasons !== undefined ? plan.verdict(reasons) : undefined;
+                return read !== undefined ? Effect.succeed(read) : Effect.fail(err);
+            }));
+            if (verdict === undefined)
+                return plan;
+            switch (verdict._tag) {
+                case "Fail":
+                    return yield* verdict.error;
+                case "Condition":
+                    return yield* new ConditionalCheckFailed({ entityType, key: args.key });
+                case "Retry":
+                    lost = verdict;
             }
         }
-        if (isRetainEnabled()) {
-            out.push({
-                kind: "snapshot",
-                item: buildSnapshotItem(item, 1, pkField, skField, ttlAttrName, now),
-            });
-        }
-        return out;
-    };
+        return yield* withCurrentItem(Effect.fail(lost.error), () => lost.stored);
+    });
     // ---------------------------------------------------------------------------
     // Ref hydration
     // ---------------------------------------------------------------------------
@@ -1177,7 +2632,9 @@ const makeImpl = (config, precomputedData) => {
         const tc = yield* tableTag;
         const tableName = tc.name;
         const ttlAttrName = resolveTtlAttributeName(tc);
-        yield* checkWithVectorNames(opts.withVectors, "put");
+        // `upsert` creates through this path: its errors name it.
+        const operation = opts.operation ?? "put";
+        yield* checkWithVectorNames(opts.withVectors, operation);
         // Auto-generated id: fill the configured primary-key field with a
         // fresh UUID BEFORE the encode, but only when the caller omitted it —
         // a caller-supplied value is always respected. The id is sourced from
@@ -1185,7 +2642,9 @@ const makeImpl = (config, precomputedData) => {
         // so this keeps the bound `put` at `R = never`. The filled id then
         // flows through input validation → key composition → stored item →
         // returned record in this same pass.
-        const inputWithGeneratedId = yield* fillGeneratedId(input);
+        const withGeneratedId = yield* fillGeneratedId(input);
+        const unsentineled = unsentineledDefaults(withGeneratedId);
+        const inputWithGeneratedId = yield* fillDecodingDefaults(withGeneratedId);
         // Encode user input → wire form. Users typically construct domain
         // values for transforms (DateTime, Redacted, Number) and plain
         // objects for Schema.Class fields. To handle both:
@@ -1198,7 +2657,7 @@ const makeImpl = (config, precomputedData) => {
         //      instances) and the substituted date/Redacted transforms
         //      tolerate either form. The subsequent `encode` produces
         //      the canonical wire shape.
-        const encodedInput = yield* encodeOrDecodeEncode(schemas.inputSchema, inputWithGeneratedId, entityType, "put");
+        const encodedInput = yield* encodeOrDecodeEncode(schemas.inputSchema, inputWithGeneratedId, entityType, operation);
         // Compose all keys from the encoded input (ID fields still present
         // and key composites are wire-format strings/numbers).
         const keys = composeAllKeys(encodedInput);
@@ -1229,8 +2688,13 @@ const makeImpl = (config, precomputedData) => {
         }
         if (systemFields.version)
             item[systemFields.version] = 1;
+        if (stampsIncarnation)
+            item[INCARNATION_TOKEN] = yield* freshIncarnation;
         // Add entity type discriminator
         item.__edd_e__ = entityType;
+        // Unique fields holding only a default: no sentinel for them (#133).
+        if (unsentineled.length > 0)
+            item[UNSENTINELED_DEFAULTS] = new Set(unsentineled);
         // Apply composed keys
         Object.assign(item, keys);
         // Vector search: embed the source text and compose the partition
@@ -1243,6 +2707,15 @@ const makeImpl = (config, precomputedData) => {
             for (const field of vectorWrite.removes)
                 delete item[field];
         }
+        const hasUniqueConstraints = config.unique != null && Object.keys(config.unique).length > 0;
+        // A versioned or unique-constrained entity's put is guarded (#133):
+        // a put over an existing item continues its version sequence,
+        // incarnation and `createdAt`, snapshots the replaced item (retain)
+        // and rotates its unique sentinels — never resetting history or
+        // orphaning one. See `runGuardedPut`.
+        const guarded = hasUniqueConstraints || Boolean(systemFields.version);
+        const createdAtSupplied = systemFields.createdAt !== null &&
+            encoded[systemFields.createdAt] !== undefined;
         // Rename domain fields to DynamoDB attribute names
         renameToDynamo(item);
         // Flatten sparse Map fields into per-entry top-level attributes.
@@ -1253,122 +2726,39 @@ const makeImpl = (config, precomputedData) => {
         catch (e) {
             return yield* new ValidationError({
                 entityType,
-                operation: "put.sparse",
+                operation: `${operation}.sparse`,
                 cause: e instanceof Error ? e.message : String(e),
             });
         }
-        const marshalledItem = toAttributeMap(item);
-        // Build user condition expression if provided
-        const userCondition = opts.condition
-            ? compileCondition(opts.condition, resolveDbName)
-            : undefined;
-        const hasUniqueConstraints = config.unique != null && Object.keys(config.unique).length > 0;
-        const needsTransaction = hasUniqueConstraints || isRetainEnabled();
-        if (needsTransaction) {
-            // Use transactWriteItems for atomic put + sentinel creation + snapshot
-            const transactItems = [];
-            // Main entity item (with optional user condition)
-            const mainPut = {
-                TableName: tableName,
-                Item: marshalledItem,
-            };
-            if (userCondition) {
-                mainPut.ConditionExpression = userCondition.expression;
-                mainPut.ExpressionAttributeNames = userCondition.names;
-                if (Object.keys(userCondition.values).length > 0) {
-                    mainPut.ExpressionAttributeValues = userCondition.values;
-                }
-            }
-            transactItems.push({ Put: mainPut });
-            // Unique constraint sentinels (sparse — skip when any composing field is missing)
-            const sentinelConstraints = [];
-            if (hasUniqueConstraints) {
-                for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                    const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, encoded);
-                    if (!sentinel)
-                        continue;
-                    sentinelConstraints.push(constraintName);
-                    // Optional TTL — when the constraint declares one, the sentinel
-                    // auto-expires (time-bounded uniqueness reservation/hold). Uses
-                    // the table's resolved TTL attribute name + Clock-backed `now`.
-                    const sentinelItem = {
-                        [config.indexes.primary.pk.field]: sentinel.key.pk,
-                        [config.indexes.primary.sk.field]: sentinel.key.sk,
-                        __edd_e__: `${entityType}._unique.${constraintName}`,
-                        _entity_pk: keys[config.indexes.primary.pk.field],
-                        _entity_sk: keys[config.indexes.primary.sk.field],
-                    };
-                    const uniqueTtl = resolveUniqueTtl(constraintDef);
-                    if (uniqueTtl !== undefined) {
-                        sentinelItem[ttlAttrName] =
-                            DateTime.toEpochSeconds(now) + normalizeTtlSeconds(uniqueTtl);
-                    }
-                    transactItems.push({
-                        Put: {
-                            TableName: tableName,
-                            Item: toAttributeMap(sentinelItem),
-                            ...sentinelGuard(),
-                        },
-                    });
-                }
-            }
-            // Version snapshot (v1) when retain is enabled
-            if (isRetainEnabled()) {
-                const snapshotItem = buildSnapshotItem(item, 1, config.indexes.primary.pk.field, config.indexes.primary.sk.field, ttlAttrName, now);
-                transactItems.push({
-                    Put: {
-                        TableName: tableName,
-                        Item: toAttributeMap(snapshotItem),
-                    },
-                });
+        // The caller's condition, ANDed onto `create`'s not-exists guard —
+        // a guard no `.condition()` can replace (#133). `upsert`'s create
+        // attempt brings its own (`runGuardedPut` requires the item missing).
+        const condition = withGuard(opts.putKind === "create" && operation !== "upsert"
+            ? {
+                attributeNotExists: [
+                    config.indexes.primary.pk.field,
+                    config.indexes.primary.sk.field,
+                ],
             }
-            yield* checkTransactionLimit(entityType, "put", transactItems);
-            yield* client
-                .transactWriteItems({
-                TransactItems: transactItems.map((t) => ({ Put: t.Put })),
-            })
-                .pipe(Effect.mapError((err) => {
-                // Check if this is a transaction cancellation
-                if (isAwsTransactionCancelled(err.cause)) {
-                    const reasons = err.cause.CancellationReasons;
-                    if (reasons) {
-                        // Index 0 is the main item — if it failed with user condition, return ConditionalCheckFailed
-                        if (opts.condition && reasons[0]?.Code === "ConditionalCheckFailed") {
-                            return new ConditionalCheckFailed({
-                                entityType,
-                                key: encoded,
-                            });
-                        }
-                        // Sentinel items start at index 1, in the order recorded in
-                        // `sentinelConstraints` (skipped sparse entries are absent)
-                        for (let i = 1; i < reasons.length; i++) {
-                            if (reasons[i]?.Code === "ConditionalCheckFailed") {
-                                const constraintName = sentinelConstraints[i - 1] ?? "unknown";
-                                const constraintDef = config.unique?.[constraintName];
-                                const uniqueFields = constraintDef
-                                    ? resolveUniqueFields(constraintDef)
-                                    : [];
-                                const fieldsRecord = {};
-                                for (const f of uniqueFields) {
-                                    const v = encoded[f];
-                                    if (v !== undefined && v !== null) {
-                                        fieldsRecord[f] = KeyComposer.serializeValue(v);
-                                    }
-                                }
-                                return new UniqueConstraintViolation({
-                                    entityType,
-                                    constraint: constraintName,
-                                    fields: fieldsRecord,
-                                });
-                            }
-                        }
-                    }
-                }
-                return err;
-            }));
+            : undefined, opts.condition);
+        const userCondition = condition ? compileCondition(condition, resolveDbName) : undefined;
+        if (guarded) {
+            const plan = yield* runGuardedPut({
+                tableName,
+                ttlAttrName,
+                now,
+                item,
+                createdAtSupplied,
+                userCondition,
+                create: opts.putKind === "create",
+                operation,
+                key: encoded,
+            });
+            return yield* decodeAs(plan.item, plan.marshalled, mode);
         }
-        else {
-            // Simple put without unique constraints or retain
+        const marshalledItem = toAttributeMap(item);
+        {
+            // Simple put without unique constraints or versioning
             const putInput = {
                 TableName: tableName,
                 Item: marshalledItem,
@@ -1381,7 +2771,7 @@ const makeImpl = (config, precomputedData) => {
                 }
             }
             yield* client.putItem(putInput).pipe(Effect.mapError((err) => {
-                if (opts.condition && isAwsConditionalCheckFailed(err.cause)) {
+                if (condition && isAwsConditionalCheckFailed(err.cause)) {
                     return new ConditionalCheckFailed({
                         entityType,
                         key: encoded,
@@ -1396,19 +2786,20 @@ const makeImpl = (config, precomputedData) => {
     // ---------------------------------------------------------------------------
     // create operation — put + attribute_not_exists condition
     // ---------------------------------------------------------------------------
+    // The not-exists guard is the put builder's, from `putKind: "create"` —
+    // never the op's condition, which `.condition()` replaces (#133).
     const create = (input) => {
-        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, "create");
+        return new EntityPutImpl(op._builder, op._entity, op._input, op._condition, op._withVectors, "create");
     };
     // ---------------------------------------------------------------------------
     // patch operation — update + attribute_exists condition
     // ---------------------------------------------------------------------------
+    // The exists guard is `runUpdate`'s, from `patch: true` — never the op's
+    // condition, which `.condition()` replaces (#133).
     const patch = (key) => {
-        const pkField = config.indexes.primary.pk.field;
         const op = update(key);
-        return new EntityUpdateImpl(op._builder, { ...op._updateState, condition: { attributeExists: [pkField] } }, op._entity, op._key);
+        return new EntityUpdateImpl(op._builder, { ...op._updateState, patch: true }, op._entity, op._key);
     };
     // ---------------------------------------------------------------------------
     // get operation
@@ -1452,10 +2843,63 @@ const makeImpl = (config, precomputedData) => {
     // ---------------------------------------------------------------------------
     // update operation
     // ---------------------------------------------------------------------------
-    const update = (key) => new EntityUpdateImpl((mode, uState) => Effect.gen(function* () {
+    const runUpdate = (key, mode, requested, 
+    /**
+     * The item as already read — consistently — by the caller (`upsert`).
+     * Used instead of reading it again: the write is guarded on it either way.
+     */
+    preRead) => Effect.gen(function* () {
+        // Path operations on a field that feeds a key or a unique sentinel
+        // become the record operations they are equivalent to, or are
+        // refused (#133) — before anything reads the state.
+        const normalized = normalizeDerivedPathOps(requested);
+        if (typeof normalized === "string") {
+            return yield* new ValidationError({
+                entityType,
+                operation: "update",
+                cause: normalized,
+            });
+        }
+        // Removing a defaulted index composite re-materialises its default —
+        // stored, keys recomposed from it — as a put that omits it does (#133).
+        const { state: uState, defaulted: removedToDefault } = yield* rematerializeRemovedDefaults(normalized);
+        const refusedSet = refusedRecordSet(uState.updates, key);
+        if (refusedSet !== undefined) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "update",
+                cause: refusedSet,
+            });
+        }
+        const immutables = assertedImmutables(uState.updates);
+        if (typeof immutables === "string") {
+            return yield* new ValidationError({
+                entityType,
+                operation: "update",
+                cause: immutables,
+            });
+        }
+        const upsertable = completeUpsertPayload(uState.updates);
+        const requestedRv = uState.returnValues ?? "allNew";
+        // A cascade propagates the NEW item; a mode returning the OLD one then
+        // needs both images exactly — the read-then-write branch has both.
+        const needsBothImages = uState.cascade !== undefined && (requestedRv === "allOld" || requestedRv === "updatedOld");
         const updates = uState.updates;
         const evExpected = uState.expectedVersion;
-        const userCond = uState.condition;
+        // An entity without `versioned` has no version to check: an expected
+        // version would be silently skipped — a concurrency check that never
+        // runs — so it is refused before anything is read or sent (#134).
+        if (evExpected !== undefined && !systemFields.version) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "update.expectedVersion",
+                cause: `expectedVersion(${evExpected}): entity "${entityType}" is not versioned, so there ` +
+                    "is no version to check. Add `versioned: true`, or use a `.condition()`. Nothing was sent.",
+            });
+        }
+        // The caller's condition, ANDed onto `patch`'s exists guard — a guard
+        // no `.condition()` can replace (#133).
+        const userCond = withGuard(uState.patch ? { attributeExists: [config.indexes.primary.pk.field] } : undefined, uState.condition);
         const client = yield* DynamoClient;
         const tc = yield* tableTag;
         const tableName = tc.name;
@@ -1465,14 +2909,22 @@ const makeImpl = (config, precomputedData) => {
         yield* checkWithVectorNames(uState.withVectors, "update");
         // Caller key: Type side in, ENCODED out (see `encodeKey`).
         const encodedKey = yield* encodeKey(key, "update.decodeKey");
+        // A missing item: `patch`'s exists guard failed — `ConditionalCheckFailed`,
+        // on every path, including those that read first (#134); for `update`,
+        // `ItemNotFound`.
+        const missingItem = () => uState.patch
+            ? new ConditionalCheckFailed({
+                entityType,
+                key: encodedKey,
+            })
+            : new ItemNotFound({ entityType, key: encodedKey });
         // 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
         let hydratedUpdates = encodedUpdates;
         if (hasRefs) {
             const refsToHydrate = resolvedRefs.filter((ref) => ref.idFieldName in encodedUpdates &&
-                encodedUpdates[ref.idFieldName] !==
-                    undefined);
+                encodedUpdates[ref.idFieldName] !== undefined);
             if (refsToHydrate.length > 0) {
                 hydratedUpdates = yield* hydrateRefs(hydratedUpdates, refsToHydrate);
             }
@@ -1495,19 +2947,69 @@ const makeImpl = (config, precomputedData) => {
             ]);
             touchesUniqueFields = [...uniqueFieldSet].some((f) => allUpdatedFields.has(f));
         }
-        if (isRetainEnabled() || touchesUniqueFields) {
+        // `.add()` / `.subtract()` / `.append()` / `.deleteFromSet()` on an
+        // index composite: DynamoDB would compute the new value, but the
+        // index key is composed from it here — so the item is read, the
+        // value computed and the keys recomposed by the read-then-write
+        // branch below, exactly as for a retain entity (#133).
+        const indexComposites = indexCompositeFields();
+        const computedComposites = [
+            ...Object.keys(uState.add ?? {}),
+            ...Object.keys(uState.subtract ?? {}),
+            ...Object.keys(uState.append ?? {}),
+            ...Object.keys(uState.deleteFromSet ?? {}),
+        ].filter((field) => indexComposites.has(field));
+        // Path operations are never emulated in memory: DynamoDB applies them
+        // (#133). A retain update carrying them takes the standard branch
+        // below, transacted with its version snapshot. An update that also
+        // rotates a unique sentinel or computes an index composite needs this
+        // branch's read-then-put, which cannot carry them — refused rather
+        // than silently dropping them.
+        const pathOpsPresent = hasPathOps(uState);
+        if (pathOpsPresent && (touchesUniqueFields || computedComposites.length > 0)) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "update",
+                cause: touchesUniqueFields
+                    ? "Path operations (pathSet, pathAppend, …) cannot be combined with a change to a " +
+                        "unique-constraint field in one update: the unique sentinels are rotated by a " +
+                        "read-then-put that DynamoDB path expressions cannot join. Split the update in two."
+                    : `Path operations (pathSet, pathAppend, …) cannot be combined with a computed ` +
+                        `change to index composite "${computedComposites[0]}" in one update: its new ` +
+                        "value is computed by a read-then-put that DynamoDB path expressions cannot " +
+                        "join. Split the update in two.",
+            });
+        }
+        if (needsBothImages && pathOpsPresent && !isRetainEnabled() && !systemFields.version) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "update",
+                cause: 'A cascade with returnValues("allOld" | "updatedOld") and path operations ' +
+                    "needs the item before AND after the update exactly, which an entity without " +
+                    "`versioned` cannot prove. Drop the path operations, the cascade, or the mode.",
+            });
+        }
+        if ((isRetainEnabled() ||
+            touchesUniqueFields ||
+            computedComposites.length > 0 ||
+            needsBothImages) &&
+            !pathOpsPresent) {
             // --- Retain path: read-then-transact ---
             // Read current item (needed to create snapshot of pre-update state)
-            const currentResult = yield* client.getItem({
-                TableName: tableName,
-                Key: marshalledKey,
-            });
+            const currentResult = preRead !== undefined
+                ? { Item: preRead }
+                : yield* client.getItem({
+                    TableName: tableName,
+                    Key: marshalledKey,
+                    ConsistentRead: true,
+                });
             if (!currentResult.Item) {
-                return yield* new ItemNotFound({ entityType, key: encodedKey });
+                return yield* missingItem();
             }
             const currentRaw = fromAttributeMap(currentResult.Item);
+            // 0: written before the entity was `versioned` (#133).
             const currentVersion = systemFields.version
-                ? currentRaw[systemFields.version]
+                ? (currentRaw[systemFields.version] ?? 0)
                 : 0;
             // Validate optimistic lock if requested
             if (evExpected !== undefined && currentVersion !== evExpected) {
@@ -1600,7 +3102,15 @@ const makeImpl = (config, precomputedData) => {
             if (uState.append) {
                 for (const [attr, val] of Object.entries(uState.append)) {
                     const existing = newItem[attr] ?? [];
-                    newItem[attr] = [...existing, ...val];
+                    const appended = encodePathValue([attr], val, "elements");
+                    if (appended.issue !== undefined) {
+                        return yield* new ValidationError({
+                            entityType,
+                            operation: "update.append",
+                            cause: appended.issue,
+                        });
+                    }
+                    newItem[attr] = [...existing, ...appended.encoded];
                 }
             }
             if (uState.deleteFromSet) {
@@ -1613,6 +3123,31 @@ const makeImpl = (config, precomputedData) => {
                     }
                 }
             }
+            // A unique field that held only a default gets its sentinel once a
+            // write supplies (or removes) its value (#133).
+            const defaultedMarker = newItem[UNSENTINELED_DEFAULTS];
+            if (defaultedMarker instanceof Set) {
+                const supplied = new Set([
+                    ...Object.keys(hydratedUpdates),
+                    ...(uState.remove ?? []),
+                    ...Object.keys(uState.add ?? {}),
+                    ...Object.keys(uState.subtract ?? {}),
+                ]);
+                const still = [...defaultedMarker].filter((f) => !supplied.has(f));
+                if (still.length === 0)
+                    delete newItem[UNSENTINELED_DEFAULTS];
+                else
+                    newItem[UNSENTINELED_DEFAULTS] = new Set(still);
+            }
+            // …and a unique field removed back to its default holds only a default.
+            const uniqueRemovedToDefault = removedToDefault.filter((field) => Object.values(config.unique ?? {}).some((def) => resolveUniqueFields(def).includes(field)));
+            if (uniqueRemovedToDefault.length > 0) {
+                const marker = newItem[UNSENTINELED_DEFAULTS];
+                newItem[UNSENTINELED_DEFAULTS] = new Set([
+                    ...(marker instanceof Set ? marker : []),
+                    ...uniqueRemovedToDefault,
+                ]);
+            }
             // Increment version and update timestamp. If the caller supplied a
             // value for `updatedAt` (allowed when the field collides with a
             // model-declared field), respect it (already wire-form via encode);
@@ -1657,10 +3192,7 @@ const makeImpl = (config, precomputedData) => {
             // `newItem` and drop both keys when any composite is missing.
             // For touched halves, trust the composer's per-half decision
             // (SET / REMOVE / leave-stored-value-on-newItem-alone for noop).
-            const addressed = new Set([
-                ...Object.keys(gsiUpdate.sets),
-                ...gsiUpdate.removes,
-            ]);
+            const addressed = new Set([...Object.keys(gsiUpdate.sets), ...gsiUpdate.removes]);
             for (const [indexName, indexDef] of Object.entries(allIndexes)) {
                 if (indexName === "primary")
                     continue;
@@ -1727,137 +3259,325 @@ const makeImpl = (config, precomputedData) => {
                     cause: e instanceof Error ? e.message : String(e),
                 });
             }
+            const currentItem = currentResult.Item;
+            yield* checkVersion(currentItem, "update");
+            const immutableChange = immutableMismatch(immutables, currentItem);
+            if (immutableChange !== undefined) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "update",
+                    cause: immutableChange,
+                });
+            }
+            const pkField = config.indexes.primary.pk.field;
+            const skField = config.indexes.primary.sk.field;
+            // A legacy item of an entity whose incarnation is proven by a
+            // hidden token gets one now, so the write is provable from here on.
+            if (stampsIncarnation && currentItem[INCARNATION_TOKEN] === undefined) {
+                newItem[INCARNATION_TOKEN] = yield* freshIncarnation;
+            }
             const marshalledNewItem = toAttributeMap(newItem);
-            // Build snapshot of the pre-update state (only when retain is enabled)
-            const snapshotItem = isRetainEnabled()
-                ? buildSnapshotItem(currentRaw, currentVersion, config.indexes.primary.pk.field, config.indexes.primary.sk.field, ttlAttrName, now)
-                : undefined;
-            const transactItems = [];
-            // Put new item with version condition + optional user condition
-            {
-                const retainCondParts = [];
-                const retainNames = {};
-                const retainValues = {};
-                if (systemFields.version) {
-                    retainNames["#ver"] = systemFields.version;
-                    retainValues[":expectedVer"] = toAttributeValue(currentVersion);
-                    retainCondParts.push("#ver = :expectedVer");
-                }
-                if (userCond) {
-                    const uc = compileCondition(userCond, resolveDbName);
-                    retainCondParts.push(`(${uc.expression})`);
-                    Object.assign(retainNames, uc.names);
-                    Object.assign(retainValues, uc.values);
+            // The write is a guarded Update of what changed — never a Put of
+            // the whole item read, which would overwrite whatever another
+            // writer changed in between (#133). Attributes the update names
+            // are written even when unchanged; the rest only when they differ.
+            const named = new Set([
+                ...Object.keys(hydratedUpdates),
+                ...(uState.remove ?? []),
+                ...Object.keys(uState.add ?? {}),
+                ...Object.keys(uState.subtract ?? {}),
+                ...Object.keys(uState.append ?? {}),
+                ...Object.keys(uState.deleteFromSet ?? {}),
+            ].map(resolveDbName));
+            if (systemFields.version)
+                named.add(systemFields.version);
+            if (systemFields.updatedAt)
+                named.add(systemFields.updatedAt);
+            const setAttrs = {};
+            for (const [attr, value] of Object.entries(marshalledNewItem)) {
+                if (attr === pkField || attr === skField)
+                    continue;
+                if (named.has(attr) || !attributeValueEquals(currentItem[attr], value)) {
+                    setAttrs[attr] = value;
                 }
-                const mainPut = {
-                    TableName: tableName,
-                    Item: marshalledNewItem,
+            }
+            const removeAttrs = Object.keys(currentItem).filter((attr) => !(attr in marshalledNewItem));
+            const written = new Set([...Object.keys(setAttrs), ...removeAttrs]);
+            const writeNames = {};
+            const writeValues = {};
+            const setClauses = Object.entries(setAttrs).map(([attr, value], i) => {
+                writeNames[`#w${i}`] = attr;
+                writeValues[`:w${i}`] = value;
+                return `#w${i} = :w${i}`;
+            });
+            const removeClauses = removeAttrs.map((attr, i) => {
+                writeNames[`#x${i}`] = attr;
+                return `#x${i}`;
+            });
+            if (setClauses.length === 0 && removeClauses.length === 0) {
+                // Nothing changed: an idempotent write keeps the condition (and
+                // the transaction's other items) meaningful.
+                writeNames["#we"] = "__edd_e__";
+                writeValues[":we"] = currentItem.__edd_e__ ?? toAttributeValue(entityType);
+                setClauses.push("#we = :we");
+            }
+            const updateExpression = [
+                setClauses.length > 0 ? `SET ${setClauses.join(", ")}` : "",
+                removeClauses.length > 0 ? `REMOVE ${removeClauses.join(", ")}` : "",
+            ]
+                .filter((part) => part !== "")
+                .join(" ");
+            // The condition proves the item is still what the new values were
+            // computed from. Versioned: its version and incarnation. Otherwise:
+            // it exists, and every attribute whose read value fed a computed
+            // value is unchanged — so an unrelated concurrent write survives
+            // and a concurrent change to an input is refused.
+            const condParts = [];
+            const inputs = [];
+            if (systemFields.version) {
+                condParts.push(versionIs(currentVersion, writeNames, writeValues, "#ver", ":expectedVer"));
+                const incarnation = incarnationGuard(currentItem, writeNames, writeValues);
+                if (incarnation !== undefined)
+                    condParts.push(incarnation);
+            }
+            else {
+                writeNames["#pk"] = pkField;
+                condParts.push("attribute_exists(#pk)");
+                const fromPayload = new Set([
+                    ...Object.entries(hydratedUpdates)
+                        .filter(([, value]) => value !== undefined && value !== null)
+                        .map(([field]) => field),
+                ]);
+                const add = (fields, always = false) => {
+                    for (const field of fields) {
+                        if ((always || !fromPayload.has(field)) && !inputs.includes(field)) {
+                            inputs.push(field);
+                        }
+                    }
                 };
-                if (retainCondParts.length > 0) {
-                    mainPut.ConditionExpression = retainCondParts.join(" AND ");
-                    mainPut.ExpressionAttributeNames = retainNames;
-                    mainPut.ExpressionAttributeValues = retainValues;
+                add([
+                    ...Object.keys(uState.add ?? {}),
+                    ...Object.keys(uState.subtract ?? {}),
+                    ...Object.keys(uState.append ?? {}),
+                    ...Object.keys(uState.deleteFromSet ?? {}),
+                ], true);
+                for (const [indexName, indexDef] of Object.entries(allIndexes)) {
+                    if (indexName === "primary")
+                        continue;
+                    if (written.has(indexDef.pk.field))
+                        add(indexDef.pk.composite);
+                    if (written.has(indexDef.sk.field))
+                        add(indexDef.sk.composite);
+                }
+                for (const rotation of sentinelRotations) {
+                    add(resolveUniqueFields(config.unique[rotation.constraintName]), true);
+                }
+                for (const [, definition] of vectorIndexEntries) {
+                    if (written.has(definition.vectorField))
+                        add(definition.sourceFields);
+                    if (written.has(definition.partitionField))
+                        add(definition.partition);
+                }
+                for (const [i, field] of inputs.entries()) {
+                    const attr = resolveDbName(field);
+                    writeNames[`#g${i}`] = attr;
+                    const read = currentItem[attr];
+                    if (read === undefined) {
+                        condParts.push(`attribute_not_exists(#g${i})`);
+                    }
+                    else {
+                        writeValues[`:g${i}`] = read;
+                        condParts.push(`#g${i} = :g${i}`);
+                    }
                 }
-                transactItems.push({ Put: mainPut });
             }
-            // Snapshot of pre-update state (only when retain is enabled)
-            if (snapshotItem) {
-                transactItems.push({
-                    Put: {
-                        TableName: tableName,
-                        Item: toAttributeMap(snapshotItem),
-                    },
-                });
+            const uc = userCond ? compileCondition(userCond, resolveDbName) : undefined;
+            if (uc) {
+                condParts.push(`(${uc.expression})`);
+                Object.assign(writeNames, uc.names);
+                Object.assign(writeValues, uc.values);
             }
-            // Apply sentinel rotations computed earlier. Delete and Put are emitted
-            // independently — a sparse field that becomes set emits Put only; a sparse
-            // field that becomes unset emits Delete only.
-            const sentinelPutIndices = [];
-            for (const rotation of sentinelRotations) {
-                if (rotation.oldUniqueKey) {
-                    transactItems.push({
-                        Delete: {
-                            TableName: tableName,
-                            Key: toAttributeMap({
-                                [config.indexes.primary.pk.field]: rotation.oldUniqueKey.pk,
-                                [config.indexes.primary.sk.field]: rotation.oldUniqueKey.sk,
-                            }),
-                        },
-                    });
+            const mainUpdate = {
+                TableName: tableName,
+                Key: marshalledKey,
+                UpdateExpression: updateExpression,
+                ConditionExpression: condParts.join(" AND "),
+                ExpressionAttributeNames: writeNames,
+                ...(Object.keys(writeValues).length > 0 && {
+                    ExpressionAttributeValues: writeValues,
+                }),
+                ReturnValuesOnConditionCheckFailure: "ALL_OLD",
+            };
+            // An update too wide for one expression (DynamoDB: 4 KB, 300
+            // operators — e.g. hundreds of sparse-map entries) writes the whole
+            // item instead, as before #133: under the version condition when
+            // versioned (exact), otherwise under the strongest guard that fits —
+            // the same fallback a wide soft delete uses.
+            const wide = !expressionFits(updateExpression, "update");
+            const wideGuardOrRefusal = wide && !systemFields.version
+                ? deleteGuard(currentItem, "item", condParts.slice(1).join(" AND "))
+                : undefined;
+            if (wideGuardOrRefusal instanceof ValidationError)
+                return yield* wideGuardOrRefusal;
+            const wideGuard = wideGuardOrRefusal;
+            const putCondition = wideGuard === undefined
+                ? condParts.join(" AND ")
+                : [wideGuard.expression, ...condParts.slice(1)].join(" AND ");
+            // Only the placeholders the condition uses (the Put has no update expression).
+            const putTokens = new Set(putCondition.match(/[#:][A-Za-z0-9_]+/g) ?? []);
+            const used = (entries) => Object.fromEntries(Object.entries(entries).filter(([token]) => putTokens.has(token)));
+            const putValues = used({ ...writeValues, ...wideGuard?.values });
+            const mainPut = {
+                TableName: tableName,
+                Item: marshalledNewItem,
+                ConditionExpression: putCondition,
+                ExpressionAttributeNames: used({ ...writeNames, ...wideGuard?.names }),
+                ...(Object.keys(putValues).length > 0 && { ExpressionAttributeValues: putValues }),
+                ReturnValuesOnConditionCheckFailure: "ALL_OLD",
+            };
+            const tooLarge = oversizedCondition("update", wide ? putCondition : mainUpdate.ConditionExpression, userCond !== undefined
+                ? compileCondition(userCond, resolveDbName)?.expression
+                : undefined);
+            if (tooLarge !== undefined)
+                return yield* tooLarge;
+            // The stored attributes the rejection compares: the guarded inputs,
+            // and on the wide fallback whatever else its guard covered.
+            const guardedAttrs = [
+                ...new Set([...inputs.map(resolveDbName), ...(wideGuard?.inputs ?? [])]),
+            ];
+            // A rejected main write: which predicate, from the stored item.
+            const mainRejection = (stored) => {
+                if (systemFields.version) {
+                    return conditionRejection(encodedKey, stored, { version: currentVersion, read: currentItem }, userCond !== undefined);
                 }
-                if (rotation.newUniqueKey && rotation.newFieldsRecord) {
-                    sentinelPutIndices.push({
-                        index: transactItems.length,
-                        constraintName: rotation.constraintName,
-                        newFieldsRecord: rotation.newFieldsRecord,
-                    });
-                    transactItems.push({
-                        Put: {
-                            TableName: tableName,
-                            Item: toAttributeMap({
-                                [config.indexes.primary.pk.field]: rotation.newUniqueKey.pk,
-                                [config.indexes.primary.sk.field]: rotation.newUniqueKey.sk,
-                                __edd_e__: `${entityType}._unique.${rotation.constraintName}`,
-                                _entity_pk: primaryKey[config.indexes.primary.pk.field],
-                                _entity_sk: primaryKey[config.indexes.primary.sk.field],
-                            }),
-                            ...sentinelGuard(),
-                        },
-                    });
+                if (stored === undefined)
+                    return missingItem();
+                const changed = guardedAttrs.filter((attr) => !attributeValueEquals(stored[attr], currentItem[attr]));
+                if (changed.length === 0 && userCond) {
+                    return new ConditionalCheckFailed({ entityType, key: encodedKey });
                 }
+                return new ConcurrentModification({
+                    entityType,
+                    key: encodedKey,
+                    attributes: changed.map(domainNameOf),
+                    current: Option.none(),
+                });
+            };
+            let rejectedItem;
+            const recordRejected = (stored) => {
+                rejectedItem = stored;
+                return mainRejection(stored);
+            };
+            // `current` of a ConcurrentModification: the stored item, decoded.
+            const withCurrent = (effect) => effect.pipe(Effect.catchIf((e) => e instanceof ConcurrentModification, (e) => Effect.gen(function* () {
+                const current = rejectedItem === undefined
+                    ? Option.none()
+                    : yield* Effect.option(decodeAs(fromAttributeMap(rejectedItem), rejectedItem, "model"));
+                return yield* keepReleaseRace(e, new ConcurrentModification({ ...e, current }));
+            })));
+            // Build snapshot of the pre-update state (only when retain is enabled)
+            const snapshotItem = isRetainEnabled()
+                ? buildSnapshotItem(currentRaw, currentVersion, config.indexes.primary.pk.field, config.indexes.primary.sk.field, ttlAttrName, now)
+                : undefined;
+            const rv = uState.returnValues ?? "allNew";
+            // The item before and after the write. Exact: a versioned write is
+            // CAS-guarded on what was read; an unguarded-for-unrelated-attribute
+            // single UpdateItem returns its own image.
+            let oldImage = currentItem;
+            let newImage = marshalledNewItem;
+            if (snapshotItem === undefined && sentinelRotations.length === 0) {
+                // One item: a plain UpdateItem, whose ALL_OLD image plus this
+                // write's own SET / REMOVE is the exact new image as well.
+                const result = yield* withCurrent((wide
+                    ? client.putItem({ ...mainPut, ReturnValues: "ALL_OLD" })
+                    : client.updateItem({ ...mainUpdate, ReturnValues: "ALL_OLD" })).pipe(Effect.mapError((err) => isAwsConditionalCheckFailed(err.cause) ? recordRejected(err.cause.Item) : err)));
+                oldImage = result.Attributes ?? currentItem;
+                const applied = {
+                    ...oldImage,
+                    ...setAttrs,
+                };
+                for (const attr of removeAttrs)
+                    delete applied[attr];
+                newImage = wide ? marshalledNewItem : applied;
             }
-            yield* checkTransactionLimit(entityType, "update", transactItems);
-            yield* client
-                .transactWriteItems({
-                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 });
+            else {
+                const transactItems = [wide ? { Put: mainPut } : { Update: mainUpdate }];
+                // Snapshot of pre-update state (only when retain is enabled)
+                if (snapshotItem) {
+                    transactItems.push({ Put: snapshotPut(tableName, snapshotItem) });
+                }
+                // Apply sentinel rotations computed earlier. Delete and Put are emitted
+                // independently — a sparse field that becomes set emits Put only; a sparse
+                // field that becomes unset emits Delete only. A Delete releases only a
+                // sentinel this item owns (#133): the item may hold the old value
+                // without its reservation, which another item may hold.
+                const owner = { pk: primaryKey[pkField], sk: primaryKey[skField] };
+                const owned = new Set(yield* ownedSentinels(tableName, sentinelRotations.flatMap((rotation) => rotation.oldUniqueKey !== undefined ? [rotation.oldUniqueKey] : []), owner));
+                const sentinelPutIndices = [];
+                const releaseIndices = [];
+                for (const rotation of sentinelRotations) {
+                    if (rotation.oldUniqueKey && owned.has(rotation.oldUniqueKey)) {
+                        releaseIndices.push({
+                            index: transactItems.length,
+                            constraintName: rotation.constraintName,
+                        });
+                        transactItems.push(sentinelRelease(tableName, rotation.oldUniqueKey, owner));
                     }
-                    return new OptimisticLockError({
-                        entityType,
-                        key: encodedKey,
-                        expectedVersion: currentVersion,
-                        actualVersion: -1,
-                    });
-                };
-                if (isAwsTransactionCancelled(err.cause)) {
-                    const reasons = err.cause.CancellationReasons;
-                    if (reasons) {
-                        // Check sentinel Puts for unique constraint violations
-                        for (const { index, constraintName, newFieldsRecord, } of sentinelPutIndices) {
-                            if (reasons[index]?.Code === "ConditionalCheckFailed") {
-                                return new UniqueConstraintViolation({
-                                    entityType,
-                                    constraint: constraintName,
-                                    fields: newFieldsRecord,
-                                });
+                    if (rotation.newUniqueKey && rotation.newFieldsRecord) {
+                        sentinelPutIndices.push({
+                            index: transactItems.length,
+                            constraintName: rotation.constraintName,
+                            newFieldsRecord: rotation.newFieldsRecord,
+                        });
+                        transactItems.push({
+                            Put: {
+                                TableName: tableName,
+                                Item: toAttributeMap(sentinelItemFor(rotation.constraintName, config.unique[rotation.constraintName], rotation.newUniqueKey, owner, now, ttlAttrName)),
+                                ...sentinelGuard(),
+                            },
+                        });
+                    }
+                }
+                yield* checkTransactionLimit(entityType, "update", transactItems);
+                yield* withCurrent(client.transactWriteItems({ TransactItems: transactItems }).pipe(Effect.mapError((err) => {
+                    if (isAwsTransactionCancelled(err.cause)) {
+                        const reasons = err.cause.CancellationReasons;
+                        if (reasons) {
+                            // The main item first: a sentinel Put rejected because
+                            // the main write was cancelled reports nothing useful.
+                            if (reasons[0]?.Code === "ConditionalCheckFailed") {
+                                return recordRejected(reasons[0].Item);
+                            }
+                            if (snapshotItem && reasons[1]?.Code === "ConditionalCheckFailed") {
+                                return historyConflict(currentVersion, "update");
+                            }
+                            for (const { index, constraintName, newFieldsRecord } of sentinelPutIndices) {
+                                if (reasons[index]?.Code === "ConditionalCheckFailed") {
+                                    return new UniqueConstraintViolation({
+                                        entityType,
+                                        constraint: constraintName,
+                                        fields: newFieldsRecord,
+                                    });
+                                }
+                            }
+                            for (const { index, constraintName } of releaseIndices) {
+                                if (reasons[index]?.Code === "ConditionalCheckFailed") {
+                                    return releaseRaced(encodedKey, constraintName);
+                                }
                             }
-                        }
-                        // Index 0 is the main item — version conflict or user condition
-                        if (reasons[0]?.Code === "ConditionalCheckFailed") {
-                            return mainItemRejection();
                         }
                     }
-                }
-                if (isAwsConditionalCheckFailed(err.cause)) {
-                    return mainItemRejection();
-                }
-                return err;
-            }));
-            const retainDecoded = yield* decodeAs(newItem, marshalledNewItem, mode);
-            // Execute cascade if configured (retain path)
+                    if (isAwsConditionalCheckFailed(err.cause)) {
+                        return recordRejected(err.cause.Item);
+                    }
+                    return err;
+                })));
+            }
+            // Execute cascade if configured (retain path) — from the new item.
             if (uState.cascade) {
-                const domainData = { ...retainDecoded };
+                const domainData = {
+                    ...(yield* decodeAs(fromAttributeMap(newImage), newImage, "model")),
+                };
                 const sourceId = sourceIdentifierField != null
                     ? encodedKey[sourceIdentifierField]
                     : undefined;
@@ -1865,9 +3585,83 @@ const makeImpl = (config, precomputedData) => {
                     yield* executeCascade(uState.cascade, domainData, String(sourceId));
                 }
             }
-            return retainDecoded;
+            return yield* updateResult(rv, oldImage, newImage, written, mode, encodedKey);
         }
         // --- Standard path: updateItem ---
+        // A retain entity reaching this branch carries path operations. Read
+        // the item first: its version snapshot is built from it, and the
+        // update below is conditioned on that version, so the snapshot is
+        // exactly the item the update replaces (#133).
+        let retainSnapshot;
+        // A cascade that also returns the OLD item, with path operations on a
+        // versioned entity: read first, condition the write on that version
+        // and incarnation, so the read IS the old item and ALL_NEW the new.
+        let casRead;
+        if (isRetainEnabled() || needsBothImages) {
+            const current = preRead !== undefined
+                ? { Item: preRead }
+                : yield* client.getItem({
+                    TableName: tableName,
+                    Key: marshalledKey,
+                    ConsistentRead: true,
+                });
+            if (!current.Item) {
+                return yield* missingItem();
+            }
+            yield* checkVersion(current.Item, "update");
+            const immutableChange = immutableMismatch(immutables, current.Item);
+            if (immutableChange !== undefined) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "update",
+                    cause: immutableChange,
+                });
+            }
+            const currentRaw = fromAttributeMap(current.Item);
+            const version = systemFields.version
+                ? (currentRaw[systemFields.version] ?? 0)
+                : 0;
+            if (evExpected !== undefined && version !== evExpected) {
+                return yield* new OptimisticLockError({
+                    entityType,
+                    key: encodedKey,
+                    expectedVersion: evExpected,
+                    actualVersion: version,
+                });
+            }
+            if (!isRetainEnabled()) {
+                casRead = { raw: current.Item, version };
+            }
+            else {
+                retainSnapshot = {
+                    item: buildSnapshotItem(currentRaw, version, config.indexes.primary.pk.field, config.indexes.primary.sk.field, ttlAttrName, now),
+                    raw: current.Item,
+                    version,
+                    ...(stampsIncarnation && current.Item[INCARNATION_TOKEN] === undefined
+                        ? yield* freshIncarnation.pipe(Effect.map((stamp) => ({ stamp, incarnation: toAttributeValue(stamp) })))
+                        : {
+                            stamp: undefined,
+                            incarnation: incarnationAttr !== undefined ? current.Item[incarnationAttr] : undefined,
+                        }),
+                };
+            }
+        }
+        // Plain (unread) updates require the item to exist (#133). One that
+        // could create a complete item — a plain `.set()` of every required
+        // field and key composite — does so on a missing item through `put`
+        // (`createOnMissing`), so the item is exactly the one `put` writes.
+        const plainWrite = retainSnapshot === undefined && casRead === undefined;
+        const createsOnMissing = plainWrite &&
+            upsertable &&
+            !uState.patch &&
+            evExpected === undefined &&
+            userCond === undefined &&
+            uState.cascade === undefined &&
+            uState.withVectors === undefined &&
+            (requestedRv === "allNew" || requestedRv === "none" || requestedRv === "updatedNew") &&
+            [uState.remove, uState.sparseRemoveEntries, uState.sparseClearFields].every((ops) => ops === undefined || ops.length === 0) &&
+            [uState.add, uState.subtract, uState.append, uState.deleteFromSet].every((ops) => ops === undefined || Object.keys(ops).length === 0) &&
+            !hasPathOps(uState);
         // Build UpdateExpression
         const setClauses = [];
         const names = {};
@@ -1952,7 +3746,10 @@ const makeImpl = (config, precomputedData) => {
         if (systemFields.version) {
             const nameKey = `#u${counter}`;
             names[nameKey] = systemFields.version;
-            setClauses.push(`${nameKey} = ${nameKey} + :vinc`);
+            // An item written before the entity was `versioned` has none: its
+            // first versioned write makes it version 1 (#133).
+            values[":vzero"] = toAttributeValue(0);
+            setClauses.push(`${nameKey} = if_not_exists(${nameKey}, :vzero) + :vinc`);
             values[":vinc"] = toAttributeValue(1);
             counter++;
         }
@@ -1977,7 +3774,15 @@ const makeImpl = (config, precomputedData) => {
                 const nameKey = `#u${counter}`;
                 const valKey = `:u${counter}`;
                 names[nameKey] = resolveDbName(attr);
-                values[valKey] = toAttributeValue(val);
+                const appended = encodePathValue([attr], val, "elements");
+                if (appended.issue !== undefined) {
+                    return yield* new ValidationError({
+                        entityType,
+                        operation: "update.append",
+                        cause: appended.issue,
+                    });
+                }
+                values[valKey] = toAttributeValue(appended.encoded);
                 setClauses.push(`${nameKey} = list_append(${nameKey}, ${valKey})`);
                 counter++;
             }
@@ -2018,17 +3823,23 @@ const makeImpl = (config, precomputedData) => {
         // composer no longer throws. Hole patterns collapse into the
         // unified can't-compose rule.
         const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, allIndexes, keyForm(hydratedUpdates), keyForm(encodedKey), removedSet === undefined ? {} : { removedSet });
+        // The key and vector attributes this update writes — a retain
+        // snapshot strips them, so the post-image is rebuilt from these.
+        const derivedSets = {};
+        const derivedRemoves = new Set();
         for (const [field, value] of Object.entries(gsiUpdate.sets)) {
             const nameKey = `#u${counter}`;
             const valKey = `:u${counter}`;
             names[nameKey] = field;
             values[valKey] = toAttributeValue(value);
+            derivedSets[field] = values[valKey];
             setClauses.push(`${nameKey} = ${valKey}`);
             counter++;
         }
         for (const keyField of gsiUpdate.removes) {
             const nameKey = `#r${removeClauses.length}`;
             names[nameKey] = keyField;
+            derivedRemoves.add(keyField);
             removeClauses.push(nameKey);
         }
         // Vector search: partition value is recomposed whenever it can be
@@ -2042,6 +3853,7 @@ const makeImpl = (config, precomputedData) => {
                 const valKey = `:u${counter}`;
                 names[nameKey] = field;
                 values[valKey] = toAttributeValue(value);
+                derivedSets[field] = values[valKey];
                 setClauses.push(`${nameKey} = ${valKey}`);
                 counter++;
             }
@@ -2050,6 +3862,7 @@ const makeImpl = (config, precomputedData) => {
             for (const field of new Set(vectorWrite.removes)) {
                 const nameKey = `#r${removeClauses.length}`;
                 names[nameKey] = field;
+                derivedRemoves.add(field);
                 removeClauses.push(nameKey);
             }
         }
@@ -2085,7 +3898,15 @@ const makeImpl = (config, precomputedData) => {
                 }
                 else {
                     const valKey = `:ps${pathCounter.value++}`;
-                    values[valKey] = toAttributeValue(op.value);
+                    const set = encodePathValue(op.segments, op.value, "value");
+                    if (set.issue !== undefined) {
+                        return yield* new ValidationError({
+                            entityType,
+                            operation: "update.pathSet",
+                            cause: set.issue,
+                        });
+                    }
+                    values[valKey] = toAttributeValue(set.encoded);
                     setClauses.push(`${pathExpr} = ${valKey}`);
                 }
             }
@@ -2110,7 +3931,15 @@ const makeImpl = (config, precomputedData) => {
             for (const op of uState.pathAppends) {
                 const pathExpr = compilePath(op.segments, names, "pa", pathCounter, resolveDbName);
                 const valKey = `:pa${pathCounter.value++}`;
-                values[valKey] = toAttributeValue(op.value);
+                const appended = encodePathValue(op.segments, op.value, "elements");
+                if (appended.issue !== undefined) {
+                    return yield* new ValidationError({
+                        entityType,
+                        operation: "update.pathAppend",
+                        cause: appended.issue,
+                    });
+                }
+                values[valKey] = toAttributeValue(appended.encoded);
                 setClauses.push(`${pathExpr} = list_append(${pathExpr}, ${valKey})`);
             }
         }
@@ -2119,7 +3948,15 @@ const makeImpl = (config, precomputedData) => {
             for (const op of uState.pathPrepends) {
                 const pathExpr = compilePath(op.segments, names, "pp", pathCounter, resolveDbName);
                 const valKey = `:pp${pathCounter.value++}`;
-                values[valKey] = toAttributeValue(op.value);
+                const prepended = encodePathValue(op.segments, op.value, "elements");
+                if (prepended.issue !== undefined) {
+                    return yield* new ValidationError({
+                        entityType,
+                        operation: "update.pathPrepend",
+                        cause: prepended.issue,
+                    });
+                }
+                values[valKey] = toAttributeValue(prepended.encoded);
                 setClauses.push(`${pathExpr} = list_append(${valKey}, ${pathExpr})`);
             }
         }
@@ -2128,7 +3965,15 @@ const makeImpl = (config, precomputedData) => {
             for (const op of uState.pathIfNotExists) {
                 const pathExpr = compilePath(op.segments, names, "pi", pathCounter, resolveDbName);
                 const valKey = `:pi${pathCounter.value++}`;
-                values[valKey] = toAttributeValue(op.value);
+                const ifAbsent = encodePathValue(op.segments, op.value, "value");
+                if (ifAbsent.issue !== undefined) {
+                    return yield* new ValidationError({
+                        entityType,
+                        operation: "update.pathIfNotExists",
+                        cause: ifAbsent.issue,
+                    });
+                }
+                values[valKey] = toAttributeValue(ifAbsent.encoded);
                 setClauses.push(`${pathExpr} = if_not_exists(${pathExpr}, ${valKey})`);
             }
         }
@@ -2220,16 +4065,28 @@ const makeImpl = (config, precomputedData) => {
                     }
                 }
             }
-            // If the item doesn't exist, clearMap is a no-op — the subsequent
-            // UpdateItem will create the row (with whatever other clauses the
-            // builder accumulated) per DynamoDB UpdateItem semantics.
+            // If the item doesn't exist, clearMap is a no-op — and the
+            // subsequent UpdateItem's existence condition reports it.
+        }
+        // A legacy retain item gets its incarnation token with this write.
+        if (retainSnapshot?.stamp !== undefined) {
+            names["#eddInc"] = INCARNATION_TOKEN;
+            values[":eddInc"] = toAttributeValue(retainSnapshot.stamp);
+            setClauses.push("#eddInc = :eddInc");
         }
         const hasAnyUpdate = setClauses.length > 0 ||
             removeClauses.length > 0 ||
             addClauses.length > 0 ||
             deleteClauses.length > 0;
+        const rv = uState.returnValues ?? "allNew";
         if (!hasAnyUpdate) {
-            // Nothing to update — just get the current item
+            // Nothing to update: nothing written, so nothing "updated"; the
+            // whole-item modes are the current item.
+            if (rv === "none")
+                return undefined;
+            if (rv === "updatedOld" || rv === "updatedNew") {
+                return yield* decodePartial(undefined, new Set(), mode);
+            }
             return yield* get(key)._run(mode);
         }
         // Compose UpdateExpression from all clause types
@@ -2246,17 +4103,134 @@ const makeImpl = (config, precomputedData) => {
         // Build condition expression — combine optimistic lock + user condition
         const condParts = [];
         if (evExpected !== undefined && systemFields.version) {
-            names["#condVer"] = systemFields.version;
-            values[":expectedVer"] = toAttributeValue(evExpected);
-            condParts.push("#condVer = :expectedVer");
+            condParts.push(versionIs(evExpected, names, values, "#condVer", ":expectedVer"));
+        }
+        if (plainWrite && systemFields.version) {
+            // Never version an item whose version was removed outside the library
+            // (incarnation token, no version) as if it predated versioning.
+            names["#intVer"] = systemFields.version;
+            names["#intInc"] = INCARNATION_TOKEN;
+            condParts.push("(attribute_exists(#intVer) OR attribute_not_exists(#intInc))");
         }
-        if (userCond) {
-            const uc = compileCondition(userCond, resolveDbName);
+        // A plain write already requires the item (`attribute_exists(#exists)`
+        // below), so `patch`'s own exists guard would only repeat it.
+        const sentCond = plainWrite ? uState.condition : userCond;
+        const uc = sentCond ? compileCondition(sentCond, resolveDbName) : undefined;
+        if (uc) {
             condParts.push(`(${uc.expression})`);
             Object.assign(names, uc.names);
             Object.assign(values, uc.values);
         }
+        if (plainWrite) {
+            // Restated immutable values must match the item's.
+            for (const [i, { attr, value }] of immutables.entries()) {
+                names[`#imm${i}`] = attr;
+                values[`:imm${i}`] = value;
+                condParts.push(`#imm${i} = :imm${i}`);
+            }
+            names["#exists"] = config.indexes.primary.pk.field;
+            condParts.push("attribute_exists(#exists)");
+        }
+        if (casRead !== undefined && systemFields.version) {
+            condParts.push(versionIs(casRead.version, names, values, "#casVer", ":casVer"));
+            const incarnation = incarnationGuard(casRead.raw, names, values);
+            if (incarnation !== undefined)
+                condParts.push(incarnation);
+        }
         const conditionExpression = condParts.length > 0 ? condParts.join(" AND ") : undefined;
+        {
+            const tooLarge = oversizedCondition("update", conditionExpression, sentCond !== undefined
+                ? compileCondition(sentCond, resolveDbName)?.expression
+                : undefined);
+            if (tooLarge !== undefined)
+                return yield* tooLarge;
+        }
+        // The top-level attributes this update writes — what `updatedOld` /
+        // `updatedNew` return.
+        const written = expressionTargets(updateExpression, names);
+        const cascadeFrom = (image) => Effect.gen(function* () {
+            if (!uState.cascade)
+                return;
+            const sourceId = sourceIdentifierField != null
+                ? encodedKey[sourceIdentifierField]
+                : undefined;
+            if (sourceId == null)
+                return;
+            const domainData = yield* decodeAs(fromAttributeMap(image), image, "model");
+            yield* executeCascade(uState.cascade, { ...domainData }, String(sourceId));
+        });
+        if (retainSnapshot !== undefined) {
+            // The SAME UpdateExpression, transacted with the version snapshot of
+            // the item it replaces — DynamoDB applies the path operations, so
+            // their semantics are DynamoDB's own (#133). The version AND the
+            // incarnation prove the snapshot is of the item this replaces.
+            const snapshot = retainSnapshot;
+            const guardParts = [...condParts];
+            if (systemFields.version) {
+                guardParts.push(versionIs(snapshot.version, names, values, "#retainVer", ":retainVer"));
+                const incarnation = incarnationGuard(snapshot.raw, names, values);
+                if (incarnation !== undefined)
+                    guardParts.push(incarnation);
+            }
+            const tooLarge = oversizedCondition("update", guardParts.join(" AND "), sentCond !== undefined
+                ? compileCondition(sentCond, resolveDbName)?.expression
+                : undefined);
+            if (tooLarge !== undefined)
+                return yield* tooLarge;
+            const transactItems = [
+                {
+                    Update: {
+                        TableName: tableName,
+                        Key: marshalledKey,
+                        UpdateExpression: updateExpression,
+                        ExpressionAttributeNames: names,
+                        ExpressionAttributeValues: Object.keys(values).length > 0 ? values : undefined,
+                        ...(guardParts.length > 0 && {
+                            ConditionExpression: guardParts.join(" AND "),
+                            ReturnValuesOnConditionCheckFailure: "ALL_OLD",
+                        }),
+                    },
+                },
+                { Put: snapshotPut(tableName, snapshot.item) },
+            ];
+            yield* checkTransactionLimit(entityType, "update", transactItems);
+            yield* client.transactWriteItems({ TransactItems: transactItems }).pipe(Effect.mapError((err) => {
+                // The update is guarded by the snapshot version AND any user
+                // condition; the stored item (ALL_OLD) says which rejected it.
+                const rejection = (stored) => conditionRejection(encodedKey, stored, systemFields.version
+                    ? { version: snapshot.version, read: snapshot.raw }
+                    : undefined, userCond !== undefined);
+                if (isAwsTransactionCancelled(err.cause)) {
+                    const main = err.cause.CancellationReasons?.[0];
+                    if (main?.Code === "ConditionalCheckFailed")
+                        return rejection(main.Item);
+                    if (err.cause.CancellationReasons?.[1]?.Code === "ConditionalCheckFailed") {
+                        return historyConflict(snapshot.version, "update");
+                    }
+                }
+                if (isAwsConditionalCheckFailed(err.cause))
+                    return rejection(err.cause.Item);
+                return err;
+            }));
+            // A transacted Update returns no attributes. The old item is exact:
+            // the version condition proves `snapshot.raw` is what it replaced.
+            // The new item is read back only when needed, and proven ours.
+            const needsNew = rv === "allNew" || rv === "updatedNew" || uState.cascade !== undefined;
+            const after = needsNew
+                ? yield* readRetainPostImage(tableName, marshalledKey, snapshot.raw, snapshot.version + 1, snapshot.incarnation, derivedSets, derivedRemoves, ttlAttrName, encodedKey)
+                : undefined;
+            if (after !== undefined)
+                yield* cascadeFrom(after);
+            return yield* updateResult(rv, snapshot.raw, after, written, mode, encodedKey);
+        }
+        // The image the mode returns; `none` asks for nothing unless a
+        // cascade needs the new item.
+        const wantsOld = casRead === undefined && (rv === "allOld" || rv === "updatedOld");
+        const returned = wantsOld
+            ? "ALL_OLD"
+            : rv === "none" && !uState.cascade && casRead === undefined
+                ? "NONE"
+                : "ALL_NEW";
         // DynamoDB rejects an empty `ExpressionAttributeValues` map. When
         // the UpdateExpression is REMOVE-only (e.g. clearMap with no other
         // combinators), `values` may be empty — omit the property entirely.
@@ -2268,44 +4242,69 @@ const makeImpl = (config, precomputedData) => {
             ExpressionAttributeNames: names,
             ExpressionAttributeValues: Object.keys(values).length > 0 ? values : undefined,
             ConditionExpression: conditionExpression,
-            ReturnValues: returnValuesMap[uState.returnValues ?? "allNew"],
+            ...(conditionExpression !== undefined && {
+                ReturnValuesOnConditionCheckFailure: "ALL_OLD",
+            }),
+            ReturnValues: returned,
         })
             .pipe(Effect.mapError((err) => {
+            // The stored item (ALL_OLD) says what rejected the update: no
+            // item (it must exist), a restated immutable value, the
+            // version CAS, or the user's condition.
             if (isAwsConditionalCheckFailed(err.cause)) {
-                if (evExpected !== undefined) {
-                    return new OptimisticLockError({
-                        entityType,
-                        key: encodedKey,
-                        expectedVersion: evExpected,
-                        actualVersion: -1,
-                    });
+                const stored = err.cause.Item;
+                if (stored === undefined && !uState.patch) {
+                    return createsOnMissing
+                        ? new MissingForCreate({ input: uState.updates })
+                        : new ItemNotFound({ entityType, key: encodedKey });
                 }
-                if (userCond) {
-                    return new ConditionalCheckFailed({
+                const corrupt = versionCorruption(stored, "update");
+                if (corrupt !== undefined)
+                    return corrupt;
+                const immutableChange = stored !== undefined ? immutableMismatch(immutables, stored) : undefined;
+                if (immutableChange !== undefined) {
+                    return new ValidationError({
                         entityType,
-                        key: encodedKey,
+                        operation: "update",
+                        cause: immutableChange,
                     });
                 }
+                return conditionRejection(encodedKey, stored, casRead !== undefined
+                    ? { version: casRead.version, read: casRead.raw }
+                    : systemFields.version && evExpected !== undefined
+                        ? { version: evExpected }
+                        : undefined, userCond !== undefined);
             }
             return err;
         }));
-        if (!result.Attributes) {
-            return yield* new ItemNotFound({ entityType, key: encodedKey });
-        }
-        const raw = fromAttributeMap(result.Attributes);
-        const decoded = yield* decodeAs(raw, result.Attributes, mode);
-        // Execute cascade if configured
-        if (uState.cascade) {
-            const domainData = { ...decoded };
-            const sourceId = sourceIdentifierField != null
-                ? encodedKey[sourceIdentifierField]
-                : undefined;
-            if (sourceId != null) {
-                yield* executeCascade(uState.cascade, domainData, String(sourceId));
-            }
+        // A cascade never meets an old-image mode here: that combination is
+        // routed to the read-then-write branch, or read first (`casRead`).
+        const newImage = wantsOld ? undefined : result.Attributes;
+        if (uState.cascade && newImage !== undefined)
+            yield* cascadeFrom(newImage);
+        return yield* updateResult(rv, casRead !== undefined ? casRead.raw : wantsOld ? result.Attributes : undefined, newImage, written, mode, encodedKey);
+    });
+    /**
+     * An update; on a missing item, a plain `.set()` of a complete item creates
+     * it through `create` — exactly the item `put` writes (#133). If another
+     * writer creates it first, the update runs once more against that item.
+     */
+    const updateOrCreate = (key, mode, requested) => runUpdate(key, mode, requested).pipe(Effect.catchIf((e) => e instanceof MissingForCreate, (missing) => Effect.gen(function* () {
+        const created = yield* Effect.exit(create(missing.input)._run("native"));
+        if (created._tag === "Failure") {
+            const raced = Cause.findErrorOption(created.cause).pipe(Option.filter((e) => e instanceof ConditionalCheckFailed));
+            if (Option.isNone(raced))
+                return yield* created;
+            // Created concurrently: now an ordinary update of that item.
+            return yield* runUpdate(key, mode, requested).pipe(Effect.catchIf((e) => e instanceof MissingForCreate, () => Effect.fail(new ItemNotFound({
+                entityType,
+                key: key,
+            }))));
         }
-        return decoded;
-    }), emptyUpdateState, self, key);
+        const item = created.value;
+        return yield* updateResult(requested.returnValues ?? "allNew", undefined, item, new Set(Object.keys(item)), mode, key);
+    })));
+    const update = (key) => new EntityUpdateImpl((mode, requested) => updateOrCreate(key, mode, requested), emptyUpdateState, self, key);
     // ---------------------------------------------------------------------------
     // delete operation
     // ---------------------------------------------------------------------------
@@ -2321,10 +4320,52 @@ const makeImpl = (config, precomputedData) => {
         const marshalledKey = toAttributeMap(primaryKey);
         const primary = config.indexes.primary;
         const hasUniqueConstraints = config.unique != null && Object.keys(config.unique).length > 0;
-        // Build user condition expression if provided
-        const userCondition = opts.condition
-            ? compileCondition(opts.condition, resolveDbName)
-            : undefined;
+        // A delete that reads the item first already requires it to exist,
+        // so a condition asserting only that (`deleteIfExists`) adds nothing
+        // to its guard: it is judged against the read instead — a missing
+        // item is `ConditionalCheckFailed` — and the delete is retried after
+        // a race like an unconditioned one.
+        const readsFirst = isSoftDeleteEnabled() || hasUniqueConstraints || isRetainEnabled();
+        // `deleteIfExists` (alone, or ANDed with a `.condition()`): a missing
+        // item fails its condition — a guard no `.condition()` replaces.
+        const mustExist = opts.mustExist;
+        const existenceOnly = readsFirst && mustExist && opts.condition === undefined;
+        if (opts.returnValues !== undefined &&
+            opts.returnValues !== "none" &&
+            opts.returnValues !== "allOld") {
+            return yield* new ValidationError({
+                entityType,
+                operation: "delete",
+                cause: `delete: returnValues("${opts.returnValues}") is not a mode DeleteItem ` +
+                    'supports — only "none" and "allOld". Nothing was sent.',
+            });
+        }
+        // The caller's condition, ANDed onto `deleteIfExists`'s exists guard.
+        const condition = withGuard(mustExist ? { attributeExists: [primary.pk.field] } : undefined, opts.condition);
+        const userCondition = condition && !existenceOnly ? compileCondition(condition, resolveDbName) : undefined;
+        /**
+         * What the delete returns: with `returnValues("allOld")`, the item it
+         * removed — the one read (every read-first delete is guarded on it) or
+         * DynamoDB's `ALL_OLD` — as a model, `undefined` when there was none.
+         */
+        const deletedResult = (old) => {
+            if (opts.returnValues !== "allOld" || old === undefined)
+                return Effect.succeed(undefined);
+            const raw = fromAttributeMap(old);
+            // The delete is applied: a decode failure must not read as a refusal.
+            return decodeAs({ ...raw }, old, "model").pipe(Effect.mapError((cause) => new DeleteAppliedButUnreadable({
+                entityType,
+                key: encodedKey,
+                item: raw,
+                cause,
+            })));
+        };
+        /** The item is missing: what a delete that read it reports. */
+        const missing = (otherwise) => mustExist
+            ? Effect.fail(new ConditionalCheckFailed({ entityType, key: encodedKey }))
+            : otherwise === undefined
+                ? Effect.succeed(undefined)
+                : Effect.fail(otherwise);
         /**
          * Map a rejected user condition on either transaction delete path
          * (soft-delete, unique-constraint) to `ConditionalCheckFailed`.
@@ -2345,166 +4386,271 @@ const makeImpl = (config, precomputedData) => {
             }
             return err;
         };
-        if (isSoftDeleteEnabled()) {
-            // --- Soft delete path ---
-            // Read current item
-            const result = yield* client.getItem({
-                TableName: tableName,
-                Key: marshalledKey,
-            });
-            if (!result.Item) {
-                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
-            // deleted SK + deletedAt, `dtNow` drives the optional TTL + snapshot.
-            const dtNow = yield* DateTime.now;
-            const now = nowIso(dtNow);
-            // Build soft-deleted item: same PK, replace SK with deleted key, strip GSI keys
-            const deletedItem = { ...raw };
-            // Strip GSI key fields — soft-deleted items must not appear in index queries
-            for (const field of gsiKeyFields()) {
-                delete deletedItem[field];
-            }
-            // Vector attributes: stash the embedding under a non-indexed name
-            // before stripping. Sparse semantics drop the tombstone out of the
-            // vector index immediately, and `restore()` un-stashes without
-            // paying for another Embedder call. See `DESIGN.md §14`.
-            for (const [, definition] of vectorIndexEntries) {
-                const stored = deletedItem[definition.vectorField];
-                if (stored !== undefined)
-                    deletedItem[definition.stashField] = stored;
-                delete deletedItem[definition.vectorField];
-                delete deletedItem[definition.partitionField];
-            }
-            // Replace SK with deleted sort key
-            deletedItem[primary.sk.field] = DynamoSchema.composeDeletedKey(schema, entityType, now);
-            // Add deletedAt
-            deletedItem.deletedAt = now;
-            // Add optional TTL
-            const sdTtl = softDeleteTtl();
-            if (sdTtl) {
-                deletedItem[ttlAttrName] = DateTime.toEpochSeconds(dtNow) + normalizeTtlSeconds(sdTtl);
-            }
-            const transactItems = [];
-            // 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,
+        /** The guard ANDed with the user's condition, for the main Delete. */
+        const guardedDeleteCondition = (guard) => {
+            const values = { ...guard.values, ...userCondition?.values };
+            return {
+                ConditionExpression: userCondition
+                    ? `${guard.expression} AND (${userCondition.expression})`
+                    : guard.expression,
+                ExpressionAttributeNames: { ...guard.names, ...userCondition?.names },
+                ...(Object.keys(values).length > 0 && { ExpressionAttributeValues: values }),
+                ReturnValuesOnConditionCheckFailure: "ALL_OLD",
             };
-            if (userCondition) {
-                currentDelete.ConditionExpression = userCondition.expression;
-                currentDelete.ExpressionAttributeNames = userCondition.names;
-                if (Object.keys(userCondition.values).length > 0) {
-                    currentDelete.ExpressionAttributeValues = userCondition.values;
+        };
+        /**
+         * Run a guarded delete transaction: index 0 is the main Delete, the
+         * only conditioned item, so its rejection is read from the stored
+         * item (ALL_OLD) — gone, raced, or the user's condition.
+         */
+        const guardedDelete = (write, read, inputs, snapshotAt, releases) => {
+            let rejected;
+            const reject = (stored) => {
+                rejected = stored;
+                // Deleted since the read: with nothing asserted, read it again —
+                // a delete of a missing item reports what such a delete does.
+                if (stored === undefined && userCondition === undefined) {
+                    return new DeletedConcurrently();
+                }
+                return deleteRejection(encodedKey, read, inputs, stored, userCondition !== undefined);
+            };
+            return withCurrentItem(write.pipe(Effect.mapError((err) => {
+                if (isAwsTransactionCancelled(err.cause)) {
+                    const main = err.cause.CancellationReasons?.[0];
+                    if (main?.Code === "ConditionalCheckFailed")
+                        return reject(main.Item);
+                    if (snapshotAt !== undefined &&
+                        err.cause.CancellationReasons?.[snapshotAt.index]?.Code ===
+                            "ConditionalCheckFailed") {
+                        return historyConflict(snapshotAt.version, "delete");
+                    }
+                    for (const { index, constraintName } of releases) {
+                        if (err.cause.CancellationReasons?.[index]?.Code === "ConditionalCheckFailed") {
+                            return releaseRaced(encodedKey, constraintName);
+                        }
+                    }
                 }
+                if (isAwsConditionalCheckFailed(err.cause))
+                    return reject(err.cause.Item);
+                return err;
+            })), () => rejected);
+        };
+        /**
+         * Append a release for each sentinel the stored item `raw` holds AND
+         * owns (#133) — composed from its domain view, since the stored row is
+         * attribute-keyed and the constraint is not (#127) — returning where
+         * each landed, so a release that lost a race can be reported.
+         */
+        const ownedReleases = (table, raw, into) => Effect.gen(function* () {
+            const rawDomain = toDomainView(raw);
+            const held = [];
+            for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
+                const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, rawDomain);
+                if (sentinel)
+                    held.push({ ...sentinel.key, constraintName });
             }
-            transactItems.push({ Delete: currentDelete });
-            // Put soft-deleted item
-            transactItems.push({
-                Put: {
-                    TableName: tableName,
-                    Item: toAttributeMap(deletedItem),
-                },
-            });
-            // Version snapshot if retain is enabled
-            if (isRetainEnabled()) {
-                const currentVersion = systemFields.version
-                    ? raw[systemFields.version]
-                    : 0;
-                const snapshotItem = buildSnapshotItem(raw, currentVersion, primary.pk.field, primary.sk.field, ttlAttrName, dtNow);
-                transactItems.push({
-                    Put: {
-                        TableName: tableName,
-                        Item: toAttributeMap(snapshotItem),
-                    },
-                });
+            const owner = { pk: primaryKey[primary.pk.field], sk: primaryKey[primary.sk.field] };
+            const releases = [];
+            for (const sentinel of yield* ownedSentinels(table, held, owner)) {
+                releases.push({ index: into.length, constraintName: sentinel.constraintName });
+                into.push(sentinelRelease(table, sentinel, owner));
             }
-            // 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, rawDomain);
-                    if (!sentinel)
-                        continue;
+            return releases;
+        });
+        if (isSoftDeleteEnabled() || hasUniqueConstraints || isRetainEnabled()) {
+            const readFirst = Effect.gen(function* () {
+                if (isSoftDeleteEnabled()) {
+                    // --- Soft delete path ---
+                    // Read current item
+                    const result = yield* client.getItem({
+                        TableName: tableName,
+                        Key: marshalledKey,
+                        ConsistentRead: true,
+                    });
+                    if (!result.Item) {
+                        return yield* missing(new ItemNotFound({ entityType, key: encodedKey }));
+                    }
+                    // The tombstone (and snapshot) copy the item read: the delete is
+                    // conditioned on it being unchanged, so no concurrent update is lost
+                    // into them (#133).
+                    yield* checkVersion(result.Item, "delete");
+                    const softGuard = deleteGuard(result.Item, "item", userCondition?.expression);
+                    if (softGuard instanceof ValidationError)
+                        return yield* softGuard;
+                    const raw = fromAttributeMap(result.Item);
+                    // Clock-backed time source; `now` is the ISO timestamp used for the
+                    // deleted SK + deletedAt, `dtNow` drives the optional TTL + snapshot.
+                    const dtNow = yield* DateTime.now;
+                    const now = nowIso(dtNow);
+                    // Build soft-deleted item: same PK, replace SK with deleted key, strip GSI keys
+                    const deletedItem = { ...raw };
+                    // Strip GSI key fields — soft-deleted items must not appear in index queries
+                    for (const field of gsiKeyFields()) {
+                        delete deletedItem[field];
+                    }
+                    // Vector attributes: stash the embedding under a non-indexed name
+                    // before stripping. Sparse semantics drop the tombstone out of the
+                    // vector index immediately, and `restore()` un-stashes without
+                    // paying for another Embedder call. See `DESIGN.md §14`.
+                    for (const [, definition] of vectorIndexEntries) {
+                        const stored = deletedItem[definition.vectorField];
+                        if (stored !== undefined)
+                            deletedItem[definition.stashField] = stored;
+                        delete deletedItem[definition.vectorField];
+                        delete deletedItem[definition.partitionField];
+                    }
+                    // Replace SK with deleted sort key
+                    deletedItem[primary.sk.field] = DynamoSchema.composeDeletedKey(schema, entityType, now, historyKeyOptions(primaryKey[primary.sk.field]));
+                    // Add deletedAt
+                    deletedItem.deletedAt = now;
+                    // Add optional TTL
+                    const sdTtl = softDeleteTtl();
+                    if (sdTtl) {
+                        deletedItem[ttlAttrName] =
+                            DateTime.toEpochSeconds(dtNow) + normalizeTtlSeconds(sdTtl);
+                    }
+                    const transactItems = [];
+                    // 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,
+                        ...guardedDeleteCondition(softGuard),
+                    };
+                    transactItems.push({ Delete: currentDelete });
+                    // Put soft-deleted item
+                    transactItems.push({
+                        Put: {
+                            TableName: tableName,
+                            Item: toAttributeMap(deletedItem),
+                        },
+                    });
+                    // Version snapshot if retain is enabled — never over existing history.
+                    let snapshotAt;
+                    if (isRetainEnabled()) {
+                        const currentVersion = systemFields.version
+                            ? (raw[systemFields.version] ?? 0)
+                            : 0;
+                        const snapshotItem = buildSnapshotItem(raw, currentVersion, primary.pk.field, primary.sk.field, ttlAttrName, dtNow);
+                        snapshotAt = { index: transactItems.length, version: currentVersion };
+                        transactItems.push({ Put: snapshotPut(tableName, snapshotItem) });
+                    }
+                    // Release sentinels if not preserving unique — only those this item
+                    // owns (#133). Sparse — fields that were unset on the live item
+                    // never had a sentinel, so nothing to release.
+                    const releases = hasUniqueConstraints && !preserveUnique()
+                        ? yield* ownedReleases(tableName, raw, transactItems)
+                        : [];
+                    yield* checkTransactionLimit(entityType, "delete", transactItems);
+                    yield* guardedDelete(client.transactWriteItems({ TransactItems: transactItems }), result.Item, softGuard.inputs, snapshotAt, releases);
+                    return result.Item;
+                }
+                else {
+                    // --- Hard delete with unique constraints and/or retained history ---
+                    // The item is read first: the sentinels to release are keyed by its
+                    // unique values, and a retain entity snapshots its final state.
+                    const result = yield* client.getItem({
+                        TableName: tableName,
+                        Key: marshalledKey,
+                        ConsistentRead: true,
+                    });
+                    if (!result.Item) {
+                        if (hasUniqueConstraints || mustExist) {
+                            return yield* missing(new ItemNotFound({ entityType, key: encodedKey }));
+                        }
+                        // Retain only: deleting a missing item writes nothing, as a plain
+                        // `DeleteItem` would. The caller's condition is still judged
+                        // against no item — and the delete never removes an item created
+                        // since the read, which would leave its final state unsnapshotted.
+                        if (!userCondition)
+                            return undefined;
+                        const values = userCondition.values;
+                        yield* client
+                            .deleteItem({
+                            TableName: tableName,
+                            Key: marshalledKey,
+                            ConditionExpression: `attribute_not_exists(#dpk) AND (${userCondition.expression})`,
+                            ExpressionAttributeNames: {
+                                ...userCondition.names,
+                                "#dpk": primary.pk.field,
+                            },
+                            ...(Object.keys(values).length > 0 && { ExpressionAttributeValues: values }),
+                            ReturnValuesOnConditionCheckFailure: "ALL_OLD",
+                        })
+                            .pipe(Effect.mapError((err) => isAwsConditionalCheckFailed(err.cause)
+                            ? conditionRejection(encodedKey, err.cause.Item, err.cause.Item === undefined ? undefined : { version: 0 }, true)
+                            : err));
+                        return undefined;
+                    }
+                    // The sentinel deletes are keyed by the unique values read, and the
+                    // snapshot copies the item read: the delete is conditioned on it —
+                    // its version and incarnation — so no sentinel is orphaned and no
+                    // concurrent write is lost from the history (#133).
+                    yield* checkVersion(result.Item, "delete");
+                    const hardGuard = deleteGuard(result.Item, hasUniqueConstraints
+                        ? [
+                            ...new Set(Object.values(config.unique).flatMap((def) => resolveUniqueFields(def).map(resolveDbName))),
+                        ]
+                        : [], userCondition?.expression);
+                    if (hardGuard instanceof ValidationError)
+                        return yield* hardGuard;
+                    const raw = fromAttributeMap(result.Item);
+                    const transactItems = [];
+                    // Delete entity item — index 0, and the only item conditioned on the
+                    // item read (the sentinel Deletes are conditioned on ownership, the
+                    // snapshot on history), so an index-0 cancellation is read from it.
                     transactItems.push({
                         Delete: {
                             TableName: tableName,
-                            Key: toAttributeMap({
-                                [primary.pk.field]: sentinel.key.pk,
-                                [primary.sk.field]: sentinel.key.sk,
-                            }),
+                            Key: marshalledKey,
+                            ...guardedDeleteCondition(hardGuard),
                         },
                     });
+                    // Retain: the final state is history too. Snapshotted at its own
+                    // version — under the same never-overwrite guard as every snapshot —
+                    // so an item created again at this key continues PAST it, and a
+                    // writer holding this version can never match the new incarnation.
+                    let snapshotAt;
+                    if (isRetainEnabled()) {
+                        const currentVersion = storedVersionOf(result.Item) ?? 0;
+                        snapshotAt = { index: transactItems.length, version: currentVersion };
+                        transactItems.push({
+                            Put: snapshotPut(tableName, buildSnapshotItem(raw, currentVersion, primary.pk.field, primary.sk.field, ttlAttrName, yield* DateTime.now)),
+                        });
+                    }
+                    // Release sentinels — only those this item owns (#133). Sparse: no
+                    // sentinel was ever written for a constraint whose fields are unset.
+                    const releases = hasUniqueConstraints
+                        ? yield* ownedReleases(tableName, raw, transactItems)
+                        : [];
+                    yield* checkTransactionLimit(entityType, "delete", transactItems);
+                    yield* guardedDelete(client.transactWriteItems({ TransactItems: transactItems }), result.Item, hardGuard.inputs, snapshotAt, releases);
+                    return result.Item;
                 }
-            }
-            yield* checkTransactionLimit(entityType, "delete", transactItems);
-            yield* client
-                .transactWriteItems({
-                TransactItems: transactItems,
-            })
-                .pipe(Effect.mapError(mapDeleteConditionFailure));
-        }
-        else if (hasUniqueConstraints) {
-            // --- Hard delete with unique constraints ---
-            // First get the item to find sentinel key values
-            const result = yield* client.getItem({
-                TableName: tableName,
-                Key: marshalledKey,
             });
-            if (!result.Item) {
-                return yield* Effect.fail(new ItemNotFound({ entityType, key: encodedKey }));
-            }
-            const raw = fromAttributeMap(result.Item);
-            const transactItems = [];
-            // 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). 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, rawDomain);
-                if (!sentinel)
-                    continue;
-                transactItems.push({
-                    Delete: {
-                        TableName: tableName,
-                        Key: toAttributeMap({
-                            [primary.pk.field]: sentinel.key.pk,
-                            [primary.sk.field]: sentinel.key.sk,
-                        }),
-                    },
-                });
-            }
-            yield* checkTransactionLimit(entityType, "delete", transactItems);
-            yield* client
-                .transactWriteItems({
-                TransactItems: transactItems.map((t) => ({ Delete: t.Delete })),
-            })
-                .pipe(Effect.mapError(mapDeleteConditionFailure));
+            // The caller asserted nothing about the item, so a concurrent write
+            // between the read and the transaction — a changed item, or a
+            // sentinel release that changed hands — is not a refusal: the
+            // delete reads the item again and is written again, as a put is.
+            // With a `.condition()` the read is what the condition was judged
+            // against, and a race fails.
+            // Deleted concurrently on every attempt: what a delete that read
+            // it missing reports.
+            const deleted = (yield* userCondition === undefined
+                ? readFirst.pipe(Effect.retry({
+                    times: GUARDED_PUT_ATTEMPTS - 1,
+                    while: (e) => e instanceof OptimisticLockError ||
+                        e instanceof ConcurrentModification ||
+                        e instanceof DeletedConcurrently,
+                }), Effect.catchIf((e) => e instanceof DeletedConcurrently, () => missing(hasUniqueConstraints || isSoftDeleteEnabled()
+                    ? new ItemNotFound({ entityType, key: encodedKey })
+                    : undefined)))
+                : readFirst);
+            return yield* deletedResult(deleted);
         }
         else {
             // Simple delete
@@ -2519,30 +4665,153 @@ const makeImpl = (config, precomputedData) => {
                     deleteInput.ExpressionAttributeValues = userCondition.values;
                 }
             }
-            if (opts.returnValues) {
-                deleteInput.ReturnValues = returnValuesMap[opts.returnValues];
+            if (opts.returnValues !== undefined) {
+                deleteInput.ReturnValues = opts.returnValues === "allOld" ? "ALL_OLD" : "NONE";
             }
-            yield* client.deleteItem(deleteInput).pipe(Effect.mapError(mapDeleteConditionFailure));
+            const output = yield* client
+                .deleteItem(deleteInput)
+                .pipe(Effect.mapError(mapDeleteConditionFailure));
+            return yield* deletedResult(output.Attributes);
         }
     }), self, key);
     // ---------------------------------------------------------------------------
     // deleteIfExists operation — delete + attribute_exists condition
     // ---------------------------------------------------------------------------
     const deleteIfExists = (key) => {
-        const pkField = config.indexes.primary.pk.field;
         const op = del(key);
-        return new EntityDeleteImpl(op._builder, op._entity, op._key, { attributeExists: [pkField] }, op._returnValues);
+        return new EntityDeleteImpl(op._builder, op._entity, op._key, op._condition, op._returnValues, true);
     };
     // ---------------------------------------------------------------------------
     // upsert operation — create-or-update via UpdateItem with if_not_exists()
     // ---------------------------------------------------------------------------
+    /**
+     * `upsert` that reads the item first (#133) — of an entity with unique
+     * constraints or `versioned: { retain: true }`, or an input that omits a
+     * defaulted index composite. A single UpdateItem cannot write, rotate or
+     * check a sentinel, snapshot the replaced item, or tell whether to store a
+     * default or keep the stored value. Missing: a `create` (sentinels guarded
+     * by `attribute_not_exists`, the retain snapshot, omitted defaults stored).
+     * Present: an update of the upserted fields — sentinels rotate for changed
+     * values, unchanged ones are left alone, immutable fields, `createdAt` and
+     * fields the input omits keep their stored values, retain snapshots the
+     * replaced item — under the update's version / incarnation or attribute
+     * guards, from that one read. The whole input is validated either way. A
+     * concurrent create or delete between the read and the write is retried the
+     * other way, and a sentinel release whose reservation changed hands is
+     * planned again from a fresh read (as a put's is); a race lost on every
+     * attempt fails with the concurrency error. A concurrent change of the item
+     * itself fails the upsert, as it fails an update.
+     */
+    const guardedUpsert = (input, mode, opts) => Effect.gen(function* () {
+        const client = yield* DynamoClient;
+        const { name: tableName } = yield* tableTag;
+        yield* checkWithVectorNames(opts.withVectors, "upsert");
+        // Required fields are required whether or not the item exists.
+        yield* encodeOrDecodeEncode(schemas.inputSchema, yield* fillDecodingDefaults(input), entityType, "upsert");
+        const record = (input ?? {});
+        const primary = config.indexes.primary;
+        const keyFields = [...primary.pk.composite, ...primary.sk.composite];
+        const key = Object.fromEntries(keyFields.map((field) => [field, record[field]]));
+        const encodedKey = yield* encodeKey(key, "upsert.decodeKey");
+        const marshalledKey = toAttributeMap(composePrimaryKey(encodedKey));
+        const dropped = new Set([
+            ...keyFields,
+            ...immutableFields,
+            ...(systemFields.createdAt ? [systemFields.createdAt] : []),
+            ...(systemFields.version ? [systemFields.version] : []),
+        ]);
+        const updates = Object.fromEntries(Object.entries(record).filter(([field]) => !dropped.has(field)));
+        const read = () => client
+            .getItem({ TableName: tableName, Key: marshalledKey, ConsistentRead: true })
+            .pipe(Effect.map((result) => result.Item));
+        let current = yield* read();
+        let expected = 0;
+        let lost;
+        for (let attempt = 0; attempt < GUARDED_PUT_ATTEMPTS; attempt++) {
+            yield* checkVersion(current, "upsert");
+            expected = storedVersionOf(current) ?? 0;
+            if (current === undefined) {
+                const created = yield* Effect.exit(put(input)._builder(mode, {
+                    condition: opts.condition,
+                    withVectors: opts.withVectors,
+                    putKind: "create",
+                    operation: "upsert",
+                }));
+                if (created._tag === "Success")
+                    return created.value;
+                const error = Cause.findErrorOption(created.cause);
+                if (Option.isNone(error) || !(error.value instanceof ConditionalCheckFailed)) {
+                    return yield* created;
+                }
+                // Created concurrently: upsert it as the existing item it now is.
+                // Still missing: the caller's condition rejected it.
+                current = yield* read();
+                if (current === undefined)
+                    return yield* created;
+                continue;
+            }
+            const updated = yield* Effect.exit(runUpdate(key, mode, {
+                ...emptyUpdateState,
+                updates,
+                condition: opts.condition,
+                withVectors: opts.withVectors,
+            }, current).pipe(
+            // Its errors name the upsert, not the update it runs.
+            Effect.mapError((e) => e instanceof ValidationError && e.operation.startsWith("update")
+                ? new ValidationError({
+                    entityType: e.entityType,
+                    operation: `upsert${e.operation.slice("update".length)}`,
+                    cause: e.cause,
+                })
+                : e)));
+            if (updated._tag === "Success")
+                return updated.value;
+            const error = Cause.findErrorOption(updated.cause);
+            if (Option.isNone(error))
+                return yield* updated;
+            // A sentinel it would release changed hands since its ownership read:
+            // nothing was written, and the upsert is planned again from a fresh
+            // read, as a put is.
+            if (error.value instanceof ConcurrentModification && releaseRaces.has(error.value)) {
+                lost = error.value;
+            }
+            else if (!(error.value instanceof ItemNotFound)) {
+                return yield* updated;
+            }
+            // Deleted concurrently: upserted as the missing item it now is.
+            current = yield* read();
+        }
+        if (lost !== undefined)
+            return yield* lost;
+        // Every attempt raced a concurrent create or delete.
+        return yield* systemFields.version
+            ? new OptimisticLockError({
+                entityType,
+                key: encodedKey,
+                expectedVersion: expected,
+                actualVersion: storedVersionOf(current) ?? -1,
+            })
+            : new ConcurrentModification({
+                entityType,
+                key: encodedKey,
+                attributes: [],
+                current: Option.none(),
+            });
+    });
     const upsert = (input) => new EntityPutImpl((mode, opts) => Effect.gen(function* () {
+        if ((config.unique != null && Object.keys(config.unique).length > 0) ||
+            isRetainEnabled() ||
+            omitsIndexedDefault(input)) {
+            return yield* guardedUpsert(input, mode, opts);
+        }
         const client = yield* DynamoClient;
         const { name: tableName } = yield* tableTag;
         // Clock-backed time source for createdAt/updatedAt SET clauses.
         const now = yield* DateTime.now;
         yield* checkWithVectorNames(opts.withVectors, "upsert");
-        // Encode user input → wire form (see `put` for strategy).
+        // Encode user input → wire form (see `put` for strategy). An input
+        // that omits a defaulted index composite took the guarded path: the
+        // default is stored on create, the stored value kept on update.
         const encodedInput = yield* encodeOrDecodeEncode(schemas.inputSchema, input, entityType, "upsert");
         // Hydrate refs: replace ID fields with full entity domain data
         const encoded = hasRefs
@@ -2712,13 +4981,26 @@ const makeImpl = (config, precomputedData) => {
             setClauses.push(`${nameKey} = if_not_exists(${nameKey}, ${zeroKey}) + :vinc`);
             counter++;
         }
+        // An upsert that creates the item gives it an incarnation token (#133).
+        if (stampsIncarnation) {
+            names["#eddInc"] = INCARNATION_TOKEN;
+            values[":eddInc"] = toAttributeValue(yield* freshIncarnation);
+            setClauses.push("#eddInc = if_not_exists(#eddInc, :eddInc)");
+        }
         const updateExpression = upsertRemoveClauses.length > 0
             ? `SET ${setClauses.join(", ")} REMOVE ${upsertRemoveClauses.join(", ")}`
             : `SET ${setClauses.join(", ")}`;
         // Optional user condition
         const condParts = [];
-        if (opts.condition) {
-            const uc = compileCondition(opts.condition, resolveDbName);
+        if (systemFields.version) {
+            // Never version an item whose version was removed outside the library
+            // (incarnation token, no version) as if it predated versioning (#133).
+            names["#intVer"] = systemFields.version;
+            names["#intInc"] = INCARNATION_TOKEN;
+            condParts.push("(attribute_exists(#intVer) OR attribute_not_exists(#intInc))");
+        }
+        const uc = opts.condition ? compileCondition(opts.condition, resolveDbName) : undefined;
+        if (uc) {
             condParts.push(`(${uc.expression})`);
             Object.assign(names, uc.names);
             Object.assign(values, uc.values);
@@ -2731,11 +5013,19 @@ const makeImpl = (config, precomputedData) => {
             ExpressionAttributeNames: names,
             ExpressionAttributeValues: values,
             ConditionExpression: condParts.length > 0 ? condParts.join(" AND ") : undefined,
+            // Only the corruption guard needs the stored item.
+            ...(systemFields.version && {
+                ReturnValuesOnConditionCheckFailure: "ALL_OLD",
+            }),
             ReturnValues: "ALL_NEW",
         })
             .pipe(Effect.mapError((err) => {
-            if (opts.condition && isAwsConditionalCheckFailed(err.cause)) {
-                return new ConditionalCheckFailed({ entityType, key: item });
+            if (isAwsConditionalCheckFailed(err.cause)) {
+                const corrupt = versionCorruption(err.cause.Item, "upsert");
+                if (corrupt !== undefined)
+                    return corrupt;
+                if (opts.condition)
+                    return new ConditionalCheckFailed({ entityType, key: item });
             }
             return err;
         }));
@@ -2817,7 +5107,7 @@ const makeImpl = (config, precomputedData) => {
     //   `ValidationError("append.followUp")`. Undetected on skipFollowUp path.
     // ---------------------------------------------------------------------------
     const timeSeriesConfig = config.timeSeries;
-    const append = (input, userCondition, skipFollowUp = false, removeAttrs) => Effect.gen(function* () {
+    const append = (input, givenCondition, skipFollowUp = false, removeAttrs) => Effect.gen(function* () {
         if (!timeSeriesConfig) {
             return yield* new ValidationError({
                 entityType,
@@ -2825,6 +5115,17 @@ const makeImpl = (config, precomputedData) => {
                 cause: "Entity is not configured with timeSeries. .append() requires timeSeries config.",
             });
         }
+        // `append` takes its condition as an argument — no `condition`
+        // combinator — so an empty one becomes none here (#133).
+        const userCondition = nonEmptyCondition(givenCondition);
+        const emptyPart = userCondition === undefined ? undefined : emptyPartProblem(toExpr(userCondition));
+        if (emptyPart !== undefined) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "append.condition",
+                cause: `append: ${emptyPart} Nothing was sent.`,
+            });
+        }
         const client = yield* DynamoClient;
         const tc = yield* tableTag;
         const tableName = tc.name;
@@ -3011,8 +5312,8 @@ const makeImpl = (config, precomputedData) => {
         values[":_tsNewOb"] = toAttributeValue(newObValue);
         const casCondition = "attribute_not_exists(#_tspk) OR #_tsob < :_tsNewOb";
         let finalCondition = casCondition;
-        if (userCondition !== undefined) {
-            const uc = compileCondition(userCondition, resolveDbName);
+        const uc = userCondition !== undefined ? compileCondition(userCondition, resolveDbName) : undefined;
+        if (uc) {
             finalCondition = `(${casCondition}) AND (${uc.expression})`;
             Object.assign(names, uc.names);
             Object.assign(values, uc.values);
@@ -3224,6 +5525,7 @@ const makeImpl = (config, precomputedData) => {
             const query = Query.make({
                 tableName: "",
                 indexName: indexDef.index,
+                globalIndex: indexDef.index !== undefined,
                 pkField: indexDef.pk.field,
                 pkValue,
                 skField: indexDef.sk.field,
@@ -3258,6 +5560,7 @@ const makeImpl = (config, precomputedData) => {
         decoder: (raw) => decodeRecord(raw),
         resolveTableName: tableTag.useSync((tc) => tc.name),
         keyFields: [config.indexes.primary.pk.field, config.indexes.primary.sk.field],
+        liveRows: liveRows(),
     });
     // ---------------------------------------------------------------------------
     // getVersion operation
@@ -3270,21 +5573,30 @@ const makeImpl = (config, precomputedData) => {
         // Compose PK + version SK
         const primary = config.indexes.primary;
         const pkValue = KeyComposer.composePk(schema, entityType, primary, keyForm(encodedKey));
-        const versionSk = DynamoSchema.composeVersionKey(schema, entityType, versionNumber);
-        const marshalledKey = toAttributeMap({
-            [primary.pk.field]: pkValue,
-            [primary.sk.field]: versionSk,
-        });
-        const result = yield* client.getItem({
+        const liveSk = liveSkOf(encodedKey);
+        const read = (versionSk) => client
+            .getItem({
             TableName: tableName,
-            Key: marshalledKey,
+            Key: toAttributeMap({
+                [primary.pk.field]: pkValue,
+                [primary.sk.field]: versionSk,
+            }),
             ConsistentRead: opts.consistentRead || undefined,
-        });
-        if (!result.Item) {
+        })
+            .pipe(Effect.map((result) => result.Item));
+        let item = yield* read(DynamoSchema.composeVersionKey(schema, entityType, versionNumber, historyKeyOptions(liveSk)));
+        // Not under the item's own key: written by an earlier release, under
+        // the partition-wide one — if it is this item's (#133).
+        if (item === undefined && hasItemHistory) {
+            const legacy = yield* read(DynamoSchema.composeVersionKey(schema, entityType, versionNumber));
+            if (legacy !== undefined && isItemsRow(legacy, liveSk))
+                item = legacy;
+        }
+        if (!item) {
             return yield* new ItemNotFound({ entityType, key: encodedKey });
         }
-        const raw = fromAttributeMap(result.Item);
-        return yield* decodeAs(raw, result.Item, mode);
+        const raw = fromAttributeMap(item);
+        return yield* decodeAs(raw, item, mode);
     }), self, key);
     // ---------------------------------------------------------------------------
     // versions operation
@@ -3293,7 +5605,54 @@ const makeImpl = (config, precomputedData) => {
         const encodedKey = keyForm(encodeKeySync(key));
         const primary = config.indexes.primary;
         const pkValue = KeyComposer.composePk(schema, entityType, primary, keyForm(encodedKey));
-        const versionPrefix = DynamoSchema.composeVersionKeyPrefix(schema, entityType);
+        const liveSk = liveSkOf(encodedKey);
+        const versionPrefix = DynamoSchema.composeVersionKeyPrefix(schema, entityType, historyKeyOptions(liveSk));
+        /**
+         * History an earlier release wrote for this item, under the partition-wide
+         * keys (#133): when there is any, the query reads the partition's history
+         * and keeps the item's own rows plus those — a version held both ways is
+         * read from its own row. Without any, it reads only the item's own.
+         */
+        const withLegacy = hasItemHistory
+            ? (tableName) => Effect.gen(function* () {
+                const legacy = yield* legacyHistory({ tableName, pk: pkValue, liveSk, kind: "version" });
+                if (legacy.length === 0)
+                    return {};
+                const client = yield* DynamoClient;
+                const own = new Set();
+                let start;
+                do {
+                    const result = yield* client.query({
+                        TableName: tableName,
+                        KeyConditionExpression: "#pk = :pk AND begins_with(#sk, :prefix)",
+                        ExpressionAttributeNames: { "#pk": primary.pk.field, "#sk": primary.sk.field },
+                        ExpressionAttributeValues: {
+                            ":pk": toAttributeValue(pkValue),
+                            ":prefix": toAttributeValue(versionPrefix),
+                        },
+                        ProjectionExpression: "#sk",
+                        ConsistentRead: true,
+                        ExclusiveStartKey: start,
+                    });
+                    for (const row of result.Items ?? [])
+                        own.add(versionOfSk(row[primary.sk.field]?.S));
+                    start = result.LastEvaluatedKey;
+                } while (start !== undefined);
+                const legacySks = new Set(legacy
+                    .map((row) => row[primary.sk.field]?.S ?? "")
+                    .filter((sk) => !own.has(versionOfSk(sk))));
+                return {
+                    replaceBeginsWith: {
+                        from: versionPrefix,
+                        to: DynamoSchema.composeVersionKeyPrefix(schema, entityType),
+                    },
+                    keep: (row) => {
+                        const sk = row[primary.sk.field]?.S ?? "";
+                        return sk.startsWith(versionPrefix) || legacySks.has(sk);
+                    },
+                };
+            })
+            : undefined;
         return Query.make({
             tableName: "",
             indexName: undefined,
@@ -3304,42 +5663,30 @@ const makeImpl = (config, precomputedData) => {
             decoder: (raw) => decodeRecord(raw),
             resolveTableName: tableTag.useSync((tc) => tc.name),
             keyFields: [primary.pk.field, primary.sk.field],
+            prepare: withLegacy,
         }).pipe(Query.where({ beginsWith: versionPrefix }));
     };
     // ---------------------------------------------------------------------------
     // deleted namespace
     // ---------------------------------------------------------------------------
     const deletedGet = (key) => new EntityGetImpl((mode, _opts) => Effect.gen(function* () {
-        const client = yield* DynamoClient;
         const { name: tableName } = yield* tableTag;
         // 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
+        // The item's latest tombstone — not a sibling's in the same partition,
+        // and one an earlier release wrote counts (#133).
         const primary = config.indexes.primary;
         const pkValue = KeyComposer.composePk(schema, entityType, primary, keyForm(encodedKey));
-        const deletedPrefix = DynamoSchema.composeDeletedKeyPrefix(schema, entityType);
-        const result = yield* client.query({
-            TableName: tableName,
-            KeyConditionExpression: "#pk = :pk AND begins_with(#sk, :skPrefix)",
-            ExpressionAttributeNames: {
-                "#pk": primary.pk.field,
-                "#sk": primary.sk.field,
-            },
-            ExpressionAttributeValues: {
-                ":pk": toAttributeValue(pkValue),
-                ":skPrefix": toAttributeValue(deletedPrefix),
-            },
-            Limit: 1,
-            ScanIndexForward: false,
-        });
-        if (!result.Items || result.Items.length === 0) {
+        const tombstone = yield* latestTombstone(tableName, pkValue, liveSkOf(encodedKey));
+        if (tombstone === undefined) {
             return yield* new ItemNotFound({ entityType, key: encodedKey });
         }
-        const raw = fromAttributeMap(result.Items[0]);
+        const raw = fromAttributeMap(tombstone);
+        yield* checkVersion(raw, "deleted.get.decode");
         // Soft-deleted items have GSI keys stripped — always use deletedRecordSchema
         // (itemSchema would fail because it expects GSI key fields that aren't present)
         if (mode === "native")
-            return result.Items[0];
+            return tombstone;
         // Sparse Map fields: rebuild domain Records from flattened attrs so
         // soft-deleted items decode correctly. Sparse data is preserved
         // verbatim across soft-delete (GSI keys are stripped, sparse data is
@@ -3361,8 +5708,13 @@ const makeImpl = (config, precomputedData) => {
         const encodedKey = keyForm(encodeKeySync(key));
         const primary = config.indexes.primary;
         const pkValue = KeyComposer.composePk(schema, entityType, primary, keyForm(encodedKey));
+        // The whole partition's tombstones — every item's, with sort key
+        // composites (#133): no item segment.
         const deletedPrefix = DynamoSchema.composeDeletedKeyPrefix(schema, entityType);
         const decodeDeleted = (raw) => {
+            const corruption = versionCorruption(raw, "deleted.list.decode");
+            if (corruption !== undefined)
+                return Effect.fail(corruption);
             // Sparse fields are domain data and are preserved across soft-delete.
             // Rebuild Records from flattened attrs before schema decode.
             deserializeSparseFields(raw);
@@ -3398,28 +5750,16 @@ const makeImpl = (config, precomputedData) => {
         const now = yield* DateTime.now;
         // Caller key: Type side in, ENCODED out (see `encodeKey`).
         const encodedKey = yield* encodeKey(key, "restore.decode");
-        // Query for the soft-deleted item
+        // The item's latest tombstone — not a sibling's in the same partition,
+        // and one an earlier release wrote counts (#133).
         const primary = config.indexes.primary;
         const pkValue = KeyComposer.composePk(schema, entityType, primary, keyForm(encodedKey));
-        const deletedPrefix = DynamoSchema.composeDeletedKeyPrefix(schema, entityType);
-        const queryResult = yield* client.query({
-            TableName: tableName,
-            KeyConditionExpression: "#pk = :pk AND begins_with(#sk, :skPrefix)",
-            ExpressionAttributeNames: {
-                "#pk": primary.pk.field,
-                "#sk": primary.sk.field,
-            },
-            ExpressionAttributeValues: {
-                ":pk": toAttributeValue(pkValue),
-                ":skPrefix": toAttributeValue(deletedPrefix),
-            },
-            Limit: 1,
-            ScanIndexForward: false,
-        });
-        if (!queryResult.Items || queryResult.Items.length === 0) {
+        const tombstone = yield* latestTombstone(tableName, pkValue, liveSkOf(encodedKey));
+        if (tombstone === undefined) {
             return yield* new ItemNotFound({ entityType, key: encodedKey });
         }
-        const deletedRaw = fromAttributeMap(queryResult.Items[0]);
+        yield* checkVersion(tombstone, "restore");
+        const deletedRaw = fromAttributeMap(tombstone);
         const deletedMarshalledKey = toAttributeMap({
             [primary.pk.field]: deletedRaw[primary.pk.field],
             [primary.sk.field]: deletedRaw[primary.sk.field],
@@ -3431,8 +5771,9 @@ const makeImpl = (config, precomputedData) => {
         delete restoredItem.deletedAt;
         delete restoredItem[ttlAttrName];
         // Increment version
+        // 0: a tombstone of an item written before the entity was `versioned`.
         const currentVersion = systemFields.version
-            ? restoredItem[systemFields.version]
+            ? (restoredItem[systemFields.version] ?? 0)
             : 0;
         const newVersion = currentVersion + 1;
         if (systemFields.version)
@@ -3464,15 +5805,24 @@ const makeImpl = (config, precomputedData) => {
         }
         const marshalledRestoredItem = toAttributeMap(restoredItem);
         const transactItems = [];
-        // Delete the soft-deleted item
+        // Delete the soft-deleted item — only while it is still there: a
+        // concurrent restore that already consumed it must not restore twice.
         transactItems.push({
-            Delete: { TableName: tableName, Key: deletedMarshalledKey },
+            Delete: {
+                TableName: tableName,
+                Key: deletedMarshalledKey,
+                ConditionExpression: "attribute_exists(#pk)",
+                ExpressionAttributeNames: { "#pk": primary.pk.field },
+            },
         });
-        // Put restored item
+        // Put restored item — never over a live item (a re-created one, or
+        // another restore's): that would lose it and orphan its sentinels.
         transactItems.push({
             Put: {
                 TableName: tableName,
                 Item: marshalledRestoredItem,
+                ConditionExpression: "attribute_not_exists(#pk)",
+                ExpressionAttributeNames: { "#pk": primary.pk.field },
             },
         });
         // Version snapshot if retain enabled. The source is the TOMBSTONE, so
@@ -3488,12 +5838,11 @@ const makeImpl = (config, precomputedData) => {
             const snapshotSource = { ...deletedRaw };
             delete snapshotSource.deletedAt;
             delete snapshotSource[ttlAttrName];
-            const snapshotItem = buildSnapshotItem(snapshotSource, currentVersion, primary.pk.field, primary.sk.field, ttlAttrName, now);
+            const snapshotItem = buildSnapshotItem(snapshotSource, currentVersion, primary.pk.field, primary.sk.field, ttlAttrName, now, restoredKeys[primary.sk.field]);
+            // Replaces only the delete-time snapshot of this same state —
+            // never another version's history.
             transactItems.push({
-                Put: {
-                    TableName: tableName,
-                    Item: toAttributeMap(snapshotItem),
-                },
+                Put: snapshotPut(tableName, snapshotItem),
             });
         }
         // Re-establish unique constraint sentinels (sparse — fields that are
@@ -3533,6 +5882,17 @@ const makeImpl = (config, precomputedData) => {
             .pipe(Effect.mapError((err) => {
             if (isAwsTransactionCancelled(err.cause)) {
                 const reasons = err.cause.CancellationReasons;
+                // The tombstone is gone (restored concurrently), or a live
+                // item already exists under the key.
+                if (reasons?.[0]?.Code === "ConditionalCheckFailed") {
+                    return new ItemNotFound({ entityType, key: encodedKey });
+                }
+                if (reasons?.[1]?.Code === "ConditionalCheckFailed") {
+                    return new ItemNotDeleted({ entityType, key: encodedKey });
+                }
+                if (isRetainEnabled() && reasons?.[2]?.Code === "ConditionalCheckFailed") {
+                    return historyConflict(currentVersion, "restore");
+                }
                 if (reasons && config.unique) {
                     // Sentinel Puts come after Delete + Put + optional snapshot, in the
                     // order recorded in `sentinelConstraints` (sparse-skipped entries absent)
@@ -3541,7 +5901,9 @@ const makeImpl = (config, precomputedData) => {
                         if (reasons[i]?.Code === "ConditionalCheckFailed") {
                             const constraintName = sentinelConstraints[i - sentinelStart] ?? "unknown";
                             const constraintDef = config.unique[constraintName];
-                            const uniqueFields = constraintDef ? resolveUniqueFields(constraintDef) : [];
+                            const uniqueFields = constraintDef
+                                ? resolveUniqueFields(constraintDef)
+                                : [];
                             const fieldsRecord = {};
                             for (const f of uniqueFields) {
                                 const v = restoredDomain[f];
@@ -3566,8 +5928,9 @@ const makeImpl = (config, precomputedData) => {
     // purge operation
     // ---------------------------------------------------------------------------
     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
+        // `purge` queries the partition — every row of it, or with sort key
+        // composites this item's rows in it (#133) — and batch-deletes them
+        // 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
@@ -3588,43 +5951,91 @@ const makeImpl = (config, precomputedData) => {
         const encodedKey = yield* encodeKey(key, "purge.decode");
         const primary = config.indexes.primary;
         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 liveSk = liveSkOf(encodedKey);
+        const history = historyKeyOptions(liveSk);
+        /**
+         * Whether a row of the partition is this item's (#133). Only this
+         * entity's rows (`__edd_e__`): in a single-table design another
+         * entity can share the partition — a collection on the primary key —
+         * and purge never removes its rows. Without sort key composites that
+         * is every row of this entity. With them, the partition holds
+         * siblings, and the item's rows are its live row, the rows nested
+         * under it (time-series events), and its own history. History an
+         * earlier release wrote without an item segment is the item's when
+         * the composites it carries compose the item's live key.
+         */
+        const ownVersions = DynamoSchema.composeVersionKeyPrefix(schema, entityType, history);
+        const ownTombstones = DynamoSchema.composeDeletedKeyPrefix(schema, entityType, history);
+        const sharedHistory = [
+            DynamoSchema.composeVersionKeyPrefix(schema, entityType),
+            DynamoSchema.composeDeletedKeyPrefix(schema, entityType),
+        ];
+        const belongsToItem = (row) => {
+            if (row.__edd_e__?.S !== entityType)
+                return false;
+            if (history === undefined)
+                return true;
+            const sk = row[primary.sk.field]?.S;
+            if (sk === undefined)
+                return false;
+            if (sk === liveSk ||
+                sk.startsWith(`${liveSk}#`) ||
+                sk.startsWith(ownVersions) ||
+                sk.startsWith(ownTombstones)) {
+                return true;
+            }
+            const unsegmented = sharedHistory.some((prefix) => sk.startsWith(prefix) && !sk.slice(prefix.length).includes("#"));
+            return unsegmented && isItemsRow(row, liveSk);
+        };
+        // Query ALL items in this partition (current + versions + deleted).
+        // Keys and entity type only — plus, with sort key composites, the
+        // composites that attribute an unsegmented history row to its item.
+        const projected = { "#ent": "__edd_e__" };
+        if (history !== undefined) {
+            primary.sk.composite.forEach((attr, i) => {
+                projected[`#c${i}`] = resolveDbName(attr);
+            });
+        }
         const allItems = [];
         let exclusiveStartKey;
         do {
             const result = yield* client.query({
                 TableName: tableName,
                 KeyConditionExpression: "#pk = :pk",
-                ExpressionAttributeNames: { "#pk": primary.pk.field },
+                ExpressionAttributeNames: {
+                    "#pk": primary.pk.field,
+                    "#sk": primary.sk.field,
+                    ...projected,
+                },
                 ExpressionAttributeValues: { ":pk": toAttributeValue(pkValue) },
-                ProjectionExpression: `${primary.pk.field}, ${primary.sk.field}`,
+                ProjectionExpression: ["#pk", "#sk", ...Object.keys(projected)].join(", "),
                 ExclusiveStartKey: exclusiveStartKey,
             });
             if (result.Items) {
-                allItems.push(...result.Items);
+                allItems.push(...result.Items.filter(belongsToItem));
             }
             exclusiveStartKey = result.LastEvaluatedKey;
         } while (exclusiveStartKey);
-        // Also get the main/deleted item to find unique sentinel keys
+        // The unique sentinels the item holds — live, or soft-deleted with
+        // `preserveUnique` — and owns (#133): a sentinel of a value the item
+        // holds without owning its reservation belongs to another item.
         if (config.unique && Object.keys(config.unique).length > 0) {
-            // 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, keyForm(encodedKey)),
-            });
+            const owner = {
+                pk: pkValue,
+                sk: KeyComposer.composeSk(schema, entityType, entityVersion, primary, keyForm(encodedKey)),
+            };
+            const holders = [];
             const mainResult = yield* client.getItem({
                 TableName: tableName,
-                Key: marshalledKey,
+                Key: toAttributeMap({ [primary.pk.field]: owner.pk, [primary.sk.field]: owner.sk }),
+                ConsistentRead: true,
             });
-            // Try deleted items if main not found
-            let entityItem;
-            if (mainResult.Item) {
-                entityItem = fromAttributeMap(mainResult.Item);
-            }
-            else {
-                // Check for a soft-deleted item
-                const deletedPrefix = DynamoSchema.composeDeletedKeyPrefix(schema, entityType);
+            if (mainResult.Item)
+                holders.push(mainResult.Item);
+            // Every soft-deleted incarnation (each kept its reservations).
+            const deletedPrefix = DynamoSchema.composeDeletedKeyPrefix(schema, entityType);
+            let deletedStart;
+            do {
                 const deletedResult = yield* client.query({
                     TableName: tableName,
                     KeyConditionExpression: "#pk = :pk AND begins_with(#sk, :skPrefix)",
@@ -3636,27 +6047,28 @@ const makeImpl = (config, precomputedData) => {
                         ":pk": toAttributeValue(pkValue),
                         ":skPrefix": toAttributeValue(deletedPrefix),
                     },
-                    Limit: 1,
+                    ConsistentRead: true,
+                    ExclusiveStartKey: deletedStart,
                 });
-                if (deletedResult.Items && deletedResult.Items.length > 0) {
-                    entityItem = fromAttributeMap(deletedResult.Items[0]);
-                }
-            }
-            if (entityItem) {
-                // Add sentinel keys to delete list (sparse — fields that were unset
-                // never had a sentinel written, so nothing to enqueue). The stored
-                // row is attribute-keyed, the constraint is not (#127).
-                const entityItemDomain = toDomainView(entityItem);
+                holders.push(...(deletedResult.Items ?? []).filter(belongsToItem));
+                deletedStart = deletedResult.LastEvaluatedKey;
+            } while (deletedStart !== undefined);
+            // Sparse — fields that were unset never had a sentinel. The stored
+            // row is attribute-keyed, the constraint is not (#127).
+            const held = new Map();
+            for (const holder of holders) {
+                const holderDomain = toDomainView(fromAttributeMap(holder));
                 for (const [constraintName, constraintDef] of Object.entries(config.unique)) {
-                    const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, entityItemDomain);
-                    if (!sentinel)
-                        continue;
-                    allItems.push(toAttributeMap({
-                        [primary.pk.field]: sentinel.key.pk,
-                        [primary.sk.field]: sentinel.key.sk,
-                    }));
+                    const sentinel = composeUniqueSentinel(schema, entityType, constraintName, constraintDef, holderDomain);
+                    if (sentinel)
+                        held.set(`${sentinel.key.pk}\u0000${sentinel.key.sk}`, sentinel.key);
                 }
             }
+            // Released one by one, each only while still this item's: a batch
+            // delete cannot carry the ownership condition.
+            for (const sentinel of yield* ownedSentinels(tableName, [...held.values()], owner)) {
+                yield* client.deleteItem(sentinelRelease(tableName, sentinel, owner).Delete).pipe(Effect.catchIf((err) => isAwsConditionalCheckFailed(err.cause), () => Effect.void));
+            }
         }
         // Batch delete in chunks of 25
         for (let i = 0; i < allItems.length; i += 25) {
@@ -3748,8 +6160,13 @@ const makeImpl = (config, precomputedData) => {
         _serializeSparseFields: serializeSparseFields,
         _keyForm: keyForm,
         _renameToDynamo: renameToDynamo,
-        _buildPutSideItems: buildPutSideItems,
+        _incarnationToken: stampsIncarnation,
+        _versionCorruption: versionCorruption,
+        _fillDecodingDefaults: fillDecodingDefaults,
+        _unsentineledDefaults: unsentineledDefaults,
+        _planPut: planPut,
         _multiItemWriteFeatures: multiItemWriteFeatures(),
+        _liveRows: liveRows,
         _attachPrototype: attachPrototype,
         _configure: (injectedSchema, injectedTableTag) => {
             schema = injectedSchema;
@@ -3856,6 +6273,7 @@ export const bind = (entity) => Effect.gen(function* () {
             pathBuilder: createPathBuilder(),
             conditionOps: createConditionOps(),
             provide,
+            ...entityNaming(entity._resolveDbName),
         };
         return new BoundQueryImpl(q, bqConfig);
     };
@@ -4049,6 +6467,7 @@ export const bind = (entity) => Effect.gen(function* () {
                 provide,
                 skFields: orderBy ? [orderBy] : [],
                 composeSkCondition,
+                ...entityNaming(entity._resolveDbName),
             };
             return new BoundQueryImpl(q, bqConfig);
         },
@@ -4092,16 +6511,24 @@ export const extractTransactable = (op) => {
         if (target._opType === "get") {
             return { opType: "get", entity: target._entity, key: target._key };
         }
+        // `create`'s own not-exists guard is ANDed with the caller's condition:
+        // no `.condition()` replaces it (#133).
+        const primary = target._entity.indexes.primary;
         if (target._opType === "put") {
+            const putKind = target._putKind ?? "put";
             return {
                 opType: "put",
                 entity: target._entity,
                 input: target._input,
-                condition: target._condition,
-                putKind: target._putKind ?? "put",
+                condition: withGuard(putKind === "create"
+                    ? { attributeNotExists: [primary.pk.field, primary.sk.field] }
+                    : undefined, target._condition),
+                putKind,
             };
         }
         if (target._opType === "update") {
+            // Every multi-item path (transactions, `Batch.write`, `EventStore`
+            // additional items) refuses an update, so no guard is carried here.
             return {
                 opType: "update",
                 entity: target._entity,
@@ -4110,13 +6537,16 @@ export const extractTransactable = (op) => {
             };
         }
     }
-    // Check for EntityDelete intermediate
+    // Check for EntityDelete intermediate — `deleteIfExists`'s exists guard
+    // ANDed with the caller's condition.
     if (isEntityDelete(target)) {
         return {
             opType: "delete",
             entity: target._entity,
             key: target._key,
-            condition: target._condition,
+            condition: withGuard(target._mustExist
+                ? { attributeExists: [target._entity.indexes.primary.pk.field] }
+                : undefined, target._condition),
         };
     }
     return undefined;
@@ -4150,9 +6580,14 @@ export const itemSchema = (entity) => entity.schemas.itemSchema;
  *
  * Returns an Effect that fails with `ValidationError` if the item doesn't match the schema.
  */
-export const decodeMarshalledItem = (entity, marshalledItem) => Schema.decodeUnknownEffect(entity.schemas.itemSchema)(fromAttributeMap(marshalledItem)).pipe(Effect.map((decoded) => (entity._attachPrototype ? entity._attachPrototype(decoded) : decoded)), Effect.mapError((cause) => new ValidationError({
-    entityType: entity.entityType,
-    operation: "decodeMarshalledItem",
-    cause,
-})));
+export const decodeMarshalledItem = (entity, marshalledItem) => {
+    const corruption = entity._versionCorruption?.(marshalledItem, "decodeMarshalledItem");
+    if (corruption !== undefined)
+        return Effect.fail(corruption);
+    return Schema.decodeUnknownEffect(entity.schemas.itemSchema)(fromAttributeMap(marshalledItem)).pipe(Effect.map((decoded) => (entity._attachPrototype ? entity._attachPrototype(decoded) : decoded)), Effect.mapError((cause) => new ValidationError({
+        entityType: entity.entityType,
+        operation: "decodeMarshalledItem",
+        cause,
+    })));
+};
 //# sourceMappingURL=Entity.js.map