effect-dynamodb 1.10.0 → 1.12.0

package/dist/Entity.js

@@ -8,10 +8,12 @@
  */
 import { getIdentifierField, getSparseFields, isRefField, } from "@effect-dynamodb/schema/DynamoModel.js";
 import * as DynamoSchema from "@effect-dynamodb/schema/DynamoSchema.js";
-import { CascadePartialFailure, ConditionalCheckFailed, ItemNotFound, isAwsConditionalCheckFailed, isAwsTransactionCancelled, OptimisticLockError, RefNotFound, StaleAppend, TransactionOverflow, UniqueConstraintViolation, ValidationError, } from "@effect-dynamodb/schema/Errors.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 { makeDefaultCrypto } from "@effect-dynamodb/schema/internal/DefaultCrypto.js";
 import * as KeyComposer from "@effect-dynamodb/schema/KeyComposer.js";
 import { normalizeGsiConfig } from "@effect-dynamodb/schema/KeyComposer.js";
+import { deriveSourceText } from "@effect-dynamodb/schema/VectorIndex.js";
 import { Context, Crypto, DateTime, Effect, Option, Schema, Stream } from "effect";
 import { DynamoClient } from "./DynamoClient.js";
 import { makeBoundAppend, makeBoundDelete, makeBoundPut, makeBoundUpdate, } from "./internal/BoundCrud.js";
@@ -400,6 +402,258 @@ const makeImpl = (config, precomputedData) => {
         }
         return fields;
     };
+    // ---------------------------------------------------------------------------
+    // Vector search — write-path helpers (see `DESIGN.md §14`)
+    // ---------------------------------------------------------------------------
+    const vectorIndexes = data.vectorIndexes;
+    const hasVectorIndexes = data.hasVectorIndexes;
+    const vectorIndexEntries = Object.entries(vectorIndexes);
+    /**
+     * Library-managed vector attribute names (embedding + composed partition).
+     *
+     * These join `gsiKeyFields()` in every strip set — version snapshots,
+     * soft-delete tombstones, and time-series event items. DynamoDB's sparse
+     * vector index semantics do the rest: an item without the vector attribute
+     * (or without the HASH attribute) is simply not in the index, so stripping IS
+     * the delete. See `DESIGN.md §14 Lifecycle integration`.
+     */
+    const vectorKeyFields = () => {
+        const fields = [];
+        for (const [, definition] of vectorIndexEntries) {
+            fields.push(definition.vectorField, definition.partitionField);
+        }
+        return fields;
+    };
+    /**
+     * Resolve the `Embedder` service from context.
+     *
+     * Deliberately resolved with `Effect.serviceOption` rather than a plain
+     * `yield* Embedder`: only entities that declare `vectorIndexes` need one, and
+     * widening every entity operation's `R` to include `Embedder` would force the
+     * service on consumers who will never call it. A missing embedder surfaces as
+     * a tagged {@link EmbeddingError} naming the index, not a type error at the
+     * far end of the program.
+     */
+    const resolveEmbedder = (indexName) => Effect.flatMap(Effect.serviceOption(Embedder), (maybe) => Option.isSome(maybe)
+        ? Effect.succeed(maybe.value)
+        : Effect.fail(new EmbeddingError({
+            entityType,
+            index: indexName,
+            reason: `No Embedder service is available. Provide one via ` +
+                `DynamoClient.make({ embedder }) or Effect.provide(Embedder.layerTest(...)), ` +
+                `or supply a pre-computed vector with .withVector("${indexName}", [...]).`,
+        })));
+    /**
+     * Reject `.withVector("typo", ...)` before it silently does nothing.
+     *
+     * The combinator takes a plain string at runtime, and an unknown logical name
+     * would otherwise be dropped by the declared-name lookup — the Embedder would
+     * run anyway and the caller's supplied vector would vanish without a trace.
+     * Fails fast with the list of declared names instead.
+     */
+    const checkWithVectorNames = (withVectors, operation) => {
+        if (withVectors === undefined)
+            return Effect.void;
+        for (const name of Object.keys(withVectors)) {
+            if (name in vectorIndexes)
+                continue;
+            const declared = Object.keys(vectorIndexes).sort().join(", ");
+            return Effect.fail(new ValidationError({
+                entityType,
+                operation: `${operation}.withVector`,
+                cause: `Unknown vector index "${name}". Declared vector indexes: ` +
+                    `${declared.length > 0 ? declared : "(none)"}. ` +
+                    `\`.withVector()\` takes the LOGICAL name from Entity.make({ vectorIndexes }).`,
+            }));
+        }
+        return Effect.void;
+    };
+    /** @internal Validate an embedding against the index's declared dimensionality. */
+    const checkDimensions = (indexName, definition, vector) => vector.length === definition.dimensions
+        ? Effect.succeed(vector)
+        : Effect.fail(new EmbeddingError({
+            entityType,
+            index: indexName,
+            reason: `Embedding has ${vector.length} dimensions but vector index "${definition.index}" ` +
+                `declares ${definition.dimensions}. Dimensions are immutable on a DynamoDB vector index.`,
+        }));
+    /**
+     * Compute the vector + partition attributes for a full (put-style) record.
+     *
+     * Each index is independent and sparse: an index whose partition composites
+     * or source fields are absent from the record contributes nothing, and the
+     * item is simply not in that index.
+     *
+     * `embedFor` restricts which indexes are (re-)embedded — `"all"` on the put
+     * path, a gated subset on the update path. The partition value is always
+     * recomposed when it can be: it is idempotent, and writing it is what keeps
+     * an item in the index.
+     */
+    const computeVectorAttributes = (record, withVectors, embedFor) => Effect.gen(function* () {
+        const sets = {};
+        const removes = [];
+        for (const [logicalName, definition] of vectorIndexEntries) {
+            const shouldEmbed = embedFor === "all" || embedFor.has(logicalName);
+            const partition = KeyComposer.tryComposeVectorPartition(schema, entityType, definition, record);
+            if (partition === undefined) {
+                // No partition value ⇒ the item cannot be in the index at all. Drop
+                // both attributes so a previously-indexed item leaves the index
+                // rather than lingering under a stale partition.
+                removes.push(definition.partitionField, definition.vectorField);
+                continue;
+            }
+            sets[definition.partitionField] = partition;
+            if (!shouldEmbed)
+                continue;
+            const explicit = withVectors?.[logicalName];
+            if (explicit !== undefined) {
+                sets[definition.vectorField] = yield* checkDimensions(logicalName, definition, explicit);
+                continue;
+            }
+            const text = deriveSourceText(definition, record);
+            if (text === undefined) {
+                // Every source field is gone. Sparse semantics say the item should
+                // leave the index — keeping the previous embedding would make it
+                // findable by a description it no longer has.
+                removes.push(definition.vectorField, definition.partitionField);
+                delete sets[definition.partitionField];
+                continue;
+            }
+            const embedder = yield* resolveEmbedder(logicalName);
+            const embedded = yield* embedder.embed(text);
+            sets[definition.vectorField] = yield* checkDimensions(logicalName, definition, embedded);
+        }
+        return { sets, removes };
+    });
+    /**
+     * Which vector indexes does this update require work for?
+     *
+     * Re-embedding fires when the write touches a `source.fields` member by ANY
+     * channel — a `set()` payload entry, an `Entity.remove([...])` clearing it, or
+     * a path-based operation whose root segment names it — or when the caller
+     * supplied an explicit vector.
+     *
+     * Enumerating every channel (rather than only the SET payload) is the same
+     * discipline the policy-aware GSI composer applies to `removedSet` (§7): a
+     * clear is a change, and a writer that clears the source must not leave the
+     * old embedding behind. Writers that touch none of it neither pay for an
+     * embedding call nor clobber a vector another writer owns.
+     */
+    const vectorIndexesNeedingUpdate = (touchedFields, withVectors) => vectorIndexEntries.filter(([logicalName, definition]) => withVectors?.[logicalName] !== undefined ||
+        definition.sourceFields.some((field) => touchedFields.has(field)));
+    /**
+     * Every top-level attribute this update touches, by any channel.
+     *
+     * `touchesSource` alone only sees the SET payload; `remove([...])`, null
+     * clears and path-based operations are just as capable of invalidating an
+     * embedding, so they all feed the same set.
+     */
+    const collectTouchedFields = (updatePayload, uState) => {
+        const touched = new Set(Object.keys(updatePayload));
+        for (const attr of uState.remove ?? [])
+            touched.add(attr);
+        const pathOps = [
+            uState.pathSets ?? [],
+            uState.pathAdds ?? [],
+            uState.pathSubtracts ?? [],
+            uState.pathAppends ?? [],
+            uState.pathPrepends ?? [],
+            uState.pathIfNotExists ?? [],
+            uState.pathDeletes ?? [],
+        ];
+        for (const ops of pathOps) {
+            for (const op of ops) {
+                const root = op.segments[0];
+                if (typeof root === "string")
+                    touched.add(root);
+            }
+        }
+        for (const segments of uState.pathRemoves ?? []) {
+            const root = segments[0];
+            if (typeof root === "string")
+                touched.add(root);
+        }
+        return touched;
+    };
+    /**
+     * Compute vector-related SET / REMOVE attributes for the standard
+     * (UpdateItem) path.
+     *
+     * When re-embedding is required and the payload does not carry every source
+     * field, the current item is read once so the embedding is derived from the
+     * complete post-update source text rather than the fragment that happened to
+     * be in this payload. Attributes the update clears (via `remove([...])` or a
+     * null payload entry) are subtracted from that merged record, so "clear the
+     * description" produces the embedding of what actually remains — or drops the
+     * item out of the index when nothing does.
+     */
+    const computeVectorUpdateAttributes = (decodedKey, marshalledKey, tableName, updatePayload, uState) => Effect.gen(function* () {
+        if (!hasVectorIndexes)
+            return { sets: {}, removes: [] };
+        const withVectors = uState.withVectors;
+        const touchedFields = collectTouchedFields(updatePayload, uState);
+        const needing = vectorIndexesNeedingUpdate(touchedFields, withVectors);
+        const clearedFields = new Set(uState.remove ?? []);
+        for (const [attr, value] of Object.entries(updatePayload)) {
+            if (value === null || value === undefined)
+                clearedFields.add(attr);
+        }
+        // Base record: key composites plus whatever the payload supplies. Enough
+        // to compose partition values (their composites are normally primary-key
+        // members) without any extra read.
+        let merged = { ...decodedKey, ...updatePayload };
+        const needsFullSource = needing.some(([logicalName, definition]) => withVectors?.[logicalName] === undefined &&
+            definition.sourceFields.some((field) => !(field in merged)));
+        if (needsFullSource) {
+            const client = yield* DynamoClient;
+            const current = yield* client.getItem({ TableName: tableName, Key: marshalledKey });
+            if (current.Item) {
+                const currentDomain = fromAttributeMap(current.Item);
+                renameFromDynamo(currentDomain);
+                merged = { ...currentDomain, ...merged };
+            }
+        }
+        // Cleared attributes are absent post-update, whichever channel cleared
+        // them — the same two-way classification the GSI composer uses (§7).
+        for (const attr of clearedFields)
+            delete merged[attr];
+        const sets = {};
+        const removes = [];
+        for (const [logicalName, definition] of vectorIndexEntries) {
+            const isNeeded = needing.some(([name]) => name === logicalName);
+            // Partition value: idempotent and cheap, so recompose whenever the
+            // merged record can supply it (same reasoning as the PK-composites-only
+            // GSI shape in §7).
+            const partition = KeyComposer.tryComposeVectorPartition(schema, entityType, definition, merged);
+            if (partition === undefined) {
+                // Only drop the partition when THIS writer invalidated it. Otherwise
+                // the composite simply wasn't in scope for this call and dropping it
+                // would be the multi-writer clobber the §7 gate exists to prevent.
+                if (definition.partition.some((attr) => clearedFields.has(attr))) {
+                    removes.push(definition.partitionField, definition.vectorField);
+                }
+                continue;
+            }
+            sets[definition.partitionField] = partition;
+            if (!isNeeded)
+                continue;
+            const explicit = withVectors?.[logicalName];
+            if (explicit !== undefined) {
+                sets[definition.vectorField] = yield* checkDimensions(logicalName, definition, explicit);
+                continue;
+            }
+            const text = deriveSourceText(definition, merged);
+            if (text === undefined) {
+                removes.push(definition.vectorField, definition.partitionField);
+                delete sets[definition.partitionField];
+                continue;
+            }
+            const embedder = yield* resolveEmbedder(logicalName);
+            const embedded = yield* embedder.embed(text);
+            sets[definition.vectorField] = yield* checkDimensions(logicalName, definition, embedded);
+        }
+        return { sets, removes };
+    });
     /**
      * Build a version snapshot item: same PK, version SK, stripped GSI keys,
      * keeps __edd_e__ for entity type filtering.
@@ -414,6 +668,10 @@ const makeImpl = (config, precomputedData) => {
         for (const field of gsiKeyFields()) {
             delete snapshot[field];
         }
+        // Same for vector + partition attributes — a snapshot is never an ANN hit.
+        for (const field of vectorKeyFields()) {
+            delete snapshot[field];
+        }
         // Replace SK with version SK
         snapshot[tableSkField] = DynamoSchema.composeVersionKey(schema, entityType, version);
         // Add optional TTL
@@ -674,6 +932,7 @@ const makeImpl = (config, precomputedData) => {
         const tc = yield* tableTag;
         const tableName = tc.name;
         const ttlAttrName = resolveTtlAttributeName(tc);
+        yield* checkWithVectorNames(opts.withVectors, "put");
         // 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
@@ -729,6 +988,16 @@ const makeImpl = (config, precomputedData) => {
         item.__edd_e__ = entityType;
         // Apply composed keys
         Object.assign(item, keys);
+        // Vector search: embed the source text and compose the partition
+        // value. Sparse — an index whose source or partition composites are
+        // absent contributes nothing. See `DESIGN.md §14`.
+        if (hasVectorIndexes) {
+            const vectorWrite = yield* computeVectorAttributes(encoded, opts.withVectors, "all");
+            Object.assign(item, vectorWrite.sets);
+            // `put` writes a whole item, so a REMOVE is just an omission.
+            for (const field of vectorWrite.removes)
+                delete item[field];
+        }
         // Rename domain fields to DynamoDB attribute names
         renameToDynamo(item);
         // Flatten sparse Map fields into per-entry top-level attributes.
@@ -886,9 +1155,7 @@ const makeImpl = (config, precomputedData) => {
         const pkField = config.indexes.primary.pk.field;
         const skField = config.indexes.primary.sk.field;
         const op = put(input);
-        return new EntityPutImpl(op._builder, op._entity, op._input, {
-            attributeNotExists: [pkField, skField],
-        });
+        return new EntityPutImpl(op._builder, op._entity, op._input, { attributeNotExists: [pkField, skField] }, op._withVectors);
     };
     // ---------------------------------------------------------------------------
     // patch operation — update + attribute_exists condition
@@ -954,6 +1221,7 @@ const makeImpl = (config, precomputedData) => {
         const ttlAttrName = resolveTtlAttributeName(tc);
         // Clock-backed time source for the updatedAt timestamp + retain snapshot TTL.
         const now = yield* DateTime.now;
+        yield* checkWithVectorNames(uState.withVectors, "update");
         // Decode key
         const decodedKey = yield* Schema.decodeUnknownEffect(schemas.keySchema)(key).pipe(Effect.mapError((cause) => new ValidationError({
             entityType,
@@ -1195,6 +1463,20 @@ const makeImpl = (config, precomputedData) => {
                     });
                 }
             }
+            // Vector search: the retain path already holds the full merged
+            // item, so a put-style recompute is exact — no extra read needed.
+            // Re-embedding is still gated on the payload touching a source
+            // field (`DESIGN.md §14`); untouched indexes keep their stored
+            // vector, which the merge above already carried onto `newItem`.
+            if (hasVectorIndexes) {
+                const embedFor = new Set(vectorIndexesNeedingUpdate(collectTouchedFields(hydratedUpdates, uState), uState.withVectors).map(([logicalName]) => logicalName));
+                // `newItem` is the fully merged post-update item (removals already
+                // applied above), so a put-style recompute is exact.
+                const vectorWrite = yield* computeVectorAttributes(newItem, uState.withVectors, embedFor);
+                Object.assign(newItem, vectorWrite.sets);
+                for (const field of vectorWrite.removes)
+                    delete newItem[field];
+            }
             // Convert back to DynamoDB attribute names for storage
             renameToDynamo(newItem);
             // Flatten sparse Map fields into per-entry top-level attributes.
@@ -1504,6 +1786,28 @@ const makeImpl = (config, precomputedData) => {
             names[nameKey] = keyField;
             removeClauses.push(nameKey);
         }
+        // Vector search: partition value is recomposed whenever it can be
+        // (idempotent); the embedding is regenerated only when the payload
+        // touched a `source.fields` member or supplied `.withVector(...)`.
+        // See `DESIGN.md §14 Write path`.
+        if (hasVectorIndexes) {
+            const vectorWrite = yield* computeVectorUpdateAttributes(decodedKey, marshalledKey, tableName, hydratedUpdates, uState);
+            for (const [field, value] of Object.entries(vectorWrite.sets)) {
+                const nameKey = `#u${counter}`;
+                const valKey = `:u${counter}`;
+                names[nameKey] = field;
+                values[valKey] = toAttributeValue(value);
+                setClauses.push(`${nameKey} = ${valKey}`);
+                counter++;
+            }
+            // Clearing every source field takes the item out of the index —
+            // there is no other way to delete a vector index entry.
+            for (const field of new Set(vectorWrite.removes)) {
+                const nameKey = `#r${removeClauses.length}`;
+                names[nameKey] = field;
+                removeClauses.push(nameKey);
+            }
+        }
         // ADD (atomic numeric increment / set addition)
         if (uState.add) {
             for (const [attr, val] of Object.entries(uState.add)) {
@@ -1801,6 +2105,17 @@ const makeImpl = (config, precomputedData) => {
             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
@@ -1938,6 +2253,7 @@ const makeImpl = (config, precomputedData) => {
         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).
         const encodedInput = yield* encodeOrDecodeEncode(schemas.inputSchema, input, entityType, "upsert");
         // Hydrate refs: replace ID fields with full entity domain data
@@ -1950,11 +2266,21 @@ const makeImpl = (config, precomputedData) => {
         const marshalledKey = toAttributeMap(primaryKey);
         // Build UpdateExpression with if_not_exists for immutable fields + createdAt
         const setClauses = [];
+        const upsertRemoveClauses = [];
         const names = {};
         const values = {};
         let counter = 0;
-        // Determine primary key composite attribute names
-        const pkComposites = new Set(primaryKeyComposites(config.indexes));
+        // The physical key attributes (`pk` / `sk`) live in `Key` and cannot
+        // appear in an UpdateExpression. The COMPOSITE SOURCE fields are
+        // ordinary attributes and must be written like any other model field —
+        // skipping them (as this path used to) left the stored item without
+        // e.g. `productId`, so every read of an upserted item failed to decode
+        // with `Missing key`. Their values are fixed by the key, so a plain
+        // SET is idempotent.
+        const keyAttributeFields = new Set([
+            config.indexes.primary.pk.field,
+            config.indexes.primary.sk.field,
+        ]);
         // System-colliding fields are written below in the system-field block
         // (so their semantics — if_not_exists / always-set — stay consistent).
         const systemColliders = new Set();
@@ -1965,9 +2291,9 @@ const makeImpl = (config, precomputedData) => {
         if (systemFields.versionCollision && systemFields.version)
             systemColliders.add(systemFields.version);
         // `item` is already in wire-form via `Schema.encode(inputSchema)`.
-        // All model fields (excluding PK composites, which are in the Key)
+        // All model fields (excluding the physical key attributes themselves)
         for (const [attr, val] of Object.entries(item)) {
-            if (pkComposites.has(attr))
+            if (keyAttributeFields.has(resolveDbName(attr)))
                 continue;
             if (systemColliders.has(attr))
                 continue;
@@ -2029,6 +2355,30 @@ const makeImpl = (config, precomputedData) => {
             setClauses.push(`${nameKey} = ${valKey}`);
             counter++;
         }
+        // Vector search: upsert writes the full item, so it always re-embeds
+        // (same contract as `put` — see `DESIGN.md §14 Write path`). Emitted
+        // as plain SETs, never `if_not_exists`: an upsert that overwrites the
+        // source fields must overwrite the vector derived from them, or the
+        // item would stay searchable under its previous description forever.
+        if (hasVectorIndexes) {
+            const vectorWrite = yield* computeVectorAttributes(item, opts.withVectors, "all");
+            for (const [field, value] of Object.entries(vectorWrite.sets)) {
+                const nameKey = `#u${counter}`;
+                const valKey = `:u${counter}`;
+                names[nameKey] = field;
+                values[valKey] = toAttributeValue(value);
+                setClauses.push(`${nameKey} = ${valKey}`);
+                counter++;
+            }
+            // An upsert whose input carries no source text takes the item out
+            // of the index, exactly as a `put` of the same input would.
+            for (const field of new Set(vectorWrite.removes)) {
+                const nameKey = `#vr${counter}`;
+                names[nameKey] = field;
+                upsertRemoveClauses.push(nameKey);
+                counter++;
+            }
+        }
         // Add entity type discriminator
         {
             const nameKey = `#u${counter}`;
@@ -2074,7 +2424,9 @@ const makeImpl = (config, precomputedData) => {
             setClauses.push(`${nameKey} = if_not_exists(${nameKey}, ${zeroKey}) + :vinc`);
             counter++;
         }
-        const updateExpression = `SET ${setClauses.join(", ")}`;
+        const updateExpression = upsertRemoveClauses.length > 0
+            ? `SET ${setClauses.join(", ")} REMOVE ${upsertRemoveClauses.join(", ")}`
+            : `SET ${setClauses.join(", ")}`;
         // Optional user condition
         const condParts = [];
         if (opts.condition) {
@@ -2401,6 +2753,10 @@ const makeImpl = (config, precomputedData) => {
         for (const field of gsiKeyFields()) {
             delete eventItem[field];
         }
+        // Only the current item is searchable — event items carry no embedding.
+        for (const field of vectorKeyFields()) {
+            delete eventItem[field];
+        }
         // Sparse-map fields are aggregate state, not event state. They live on
         // the current item only — strip from event items entirely. (Same
         // treatment as enrichment fields outside `appendInput`. By design,
@@ -2782,6 +3138,20 @@ const makeImpl = (config, precomputedData) => {
         // Recompose all keys (original SK, GSI keys)
         const restoredKeys = composeAllKeys(restoredItem);
         Object.assign(restoredItem, restoredKeys);
+        // Un-stash the embedding and recompose the vector partition value —
+        // restoring never costs an Embedder call. See `DESIGN.md §14`.
+        for (const [, definition] of vectorIndexEntries) {
+            const stashed = restoredItem[definition.stashField];
+            if (stashed !== undefined) {
+                restoredItem[definition.vectorField] = stashed;
+                delete restoredItem[definition.stashField];
+            }
+            if (restoredItem[definition.vectorField] === undefined)
+                continue;
+            const partition = KeyComposer.tryComposeVectorPartition(schema, entityType, definition, restoredItem);
+            if (partition !== undefined)
+                restoredItem[definition.partitionField] = partition;
+        }
         const marshalledRestoredItem = toAttributeMap(restoredItem);
         const transactItems = [];
         // Delete the soft-deleted item
@@ -3027,9 +3397,15 @@ const makeImpl = (config, precomputedData) => {
         identifier: resolvedIdentifier,
         timeSeries: config.timeSeries,
         generatedId: config.generatedId,
+        vectorIndexes: config.vectorIndexes,
+        _vectorIndexes: vectorIndexes,
         _resolvedRefs: resolvedRefs,
         /** @internal Full decode pipeline: rename + schema decode. Used by Batch/Aggregate. */
         _decodeRecord: decodeRecord,
+        /** @internal Domain field name → stored attribute name (`storedAs` renames). */
+        _resolveDbName: resolveDbName,
+        /** @internal Entity schema version baked into composed keys. */
+        _entityVersion: entityVersion,
         _serializeSparseFields: serializeSparseFields,
         _attachPrototype: attachPrototype,
         _configure: (injectedSchema, injectedTableTag) => {
@@ -3140,8 +3516,122 @@ export const bind = (entity) => Effect.gen(function* () {
         };
         return new BoundQueryImpl(q, bqConfig);
     };
+    /**
+     * Out-of-band embedding refresh.
+     *
+     * DynamoDB never recomputes a vector, so changing the embedding model (or
+     * the declared `source.fields`) leaves every stored vector stale until
+     * something rewrites it. `reembed` is that something: scan the entity's
+     * items, re-derive the source text, embed, and write the vector +
+     * partition attributes back.
+     *
+     * Version snapshots and soft-delete tombstones carry the same `__edd_e__`
+     * discriminator as live items, so they are filtered out by recomposing the
+     * primary sort key from the decoded record and comparing it with what is
+     * stored — a snapshot's SK never round-trips.
+     *
+     * See `DESIGN.md §14 Write path`.
+     */
+    const reembed = (options) => {
+        const vectorDefs = Object.entries(entity._vectorIndexes);
+        const boundSchema = entity._schema;
+        const primary = entity.indexes.primary;
+        const boundEntityVersion = entity._entityVersion;
+        const concurrency = options?.concurrency ?? 4;
+        return provide(Effect.gen(function* () {
+            if (vectorDefs.length === 0)
+                return 0;
+            const client = yield* DynamoClient;
+            const { name: tableName } = yield* entity._tableTag;
+            const reembedItem = (marshalled) => Effect.gen(function* () {
+                const raw = fromAttributeMap(marshalled);
+                const storedSk = raw[primary.sk.field];
+                const decoded = (yield* entity._decodeRecord(raw));
+                // Snapshots / tombstones live in the same partition under a
+                // rewritten SK — their SK cannot be recomposed from the record.
+                const liveSk = KeyComposer.composeSk(boundSchema, entity.entityType, boundEntityVersion, primary, decoded);
+                if (storedSk !== liveSk)
+                    return false;
+                const attributes = {};
+                for (const [logicalName, definition] of vectorDefs) {
+                    const partition = KeyComposer.tryComposeVectorPartition(boundSchema, entity.entityType, definition, decoded);
+                    if (partition === undefined)
+                        continue;
+                    const text = deriveSourceText(definition, decoded);
+                    if (text === undefined)
+                        continue;
+                    const maybeEmbedder = yield* Effect.serviceOption(Embedder);
+                    if (Option.isNone(maybeEmbedder)) {
+                        return yield* new EmbeddingError({
+                            entityType: entity.entityType,
+                            index: logicalName,
+                            reason: "No Embedder service is available. Provide one via " +
+                                "DynamoClient.make({ embedder }) before calling reembed().",
+                        });
+                    }
+                    const vector = yield* maybeEmbedder.value.embed(text);
+                    if (vector.length !== definition.dimensions) {
+                        return yield* new EmbeddingError({
+                            entityType: entity.entityType,
+                            index: logicalName,
+                            reason: `Embedder produced ${vector.length} dimensions but vector index ` +
+                                `"${definition.index}" declares ${definition.dimensions}.`,
+                        });
+                    }
+                    attributes[definition.partitionField] = partition;
+                    attributes[definition.vectorField] = vector;
+                }
+                if (Object.keys(attributes).length === 0)
+                    return false;
+                const names = { "#pk": primary.pk.field };
+                const values = {};
+                const sets = [];
+                let i = 0;
+                for (const [field, value] of Object.entries(attributes)) {
+                    names[`#v${i}`] = field;
+                    values[`:v${i}`] = toAttributeValue(value);
+                    sets.push(`#v${i} = :v${i}`);
+                    i++;
+                }
+                // Scan → embed → update is not atomic: an item can be hard-deleted
+                // between the scan page and this write, and an unconditional
+                // UpdateItem would resurrect it as a key-plus-vector fragment that
+                // decodes to nothing but still answers searches. Guard on the item
+                // still existing and treat the rejection as "skipped".
+                return yield* client
+                    .updateItem({
+                    TableName: tableName,
+                    Key: {
+                        [primary.pk.field]: marshalled[primary.pk.field],
+                        [primary.sk.field]: marshalled[primary.sk.field],
+                    },
+                    UpdateExpression: `SET ${sets.join(", ")}`,
+                    ConditionExpression: "attribute_exists(#pk)",
+                    ExpressionAttributeNames: names,
+                    ExpressionAttributeValues: values,
+                })
+                    .pipe(Effect.as(true), Effect.catchIf((err) => isAwsConditionalCheckFailed(err.cause), () => Effect.succeed(false)));
+            });
+            let updated = 0;
+            let exclusiveStartKey;
+            do {
+                const page = yield* client.scan({
+                    TableName: tableName,
+                    FilterExpression: "#et = :et",
+                    ExpressionAttributeNames: { "#et": "__edd_e__" },
+                    ExpressionAttributeValues: { ":et": { S: entity.entityType } },
+                    ExclusiveStartKey: exclusiveStartKey,
+                });
+                const results = yield* Effect.all((page.Items ?? []).map((item) => reembedItem(item)), { concurrency });
+                updated += results.filter((applied) => applied).length;
+                exclusiveStartKey = page.LastEvaluatedKey;
+            } while (exclusiveStartKey !== undefined);
+            return updated;
+        }));
+    };
     return {
         // CRUD — fluent bound builders (yieldable, no .run() terminal)
+        reembed,
         get: (key) => provide(entity.get(key)._run("record")),
         put: (input) => makeBoundPut(entity.put(input), boundCrudConfig),
         create: (input) => makeBoundPut(entity.create(input), boundCrudConfig),