@farukada/aws-langgraph-dynamodb-ts 0.8.0 → 1.0.0-rc.1

package/dist/store/internal/filter.js

@@ -2,6 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.matchesStoreFilter = matchesStoreFilter;
 const node_util_1 = require("node:util");
+/**
+ * Three-way order for a like-typed pair, or `undefined` when the pair is
+ * *unordered*. `NaN` compares `false` against everything including itself, so a
+ * bare `===`/`>` ternary silently reports it as "less than" — which let a
+ * stored `NaN` satisfy `$lt`/`$lte` against any number, contradicting
+ * {@link compareOrdered}'s own contract.
+ */
+function orderOf(actual, expected) {
+    if (actual < expected)
+        return -1;
+    if (actual > expected)
+        return 1;
+    return actual === expected ? 0 : undefined;
+}
+/** Apply `test` to a resolved order; an unordered pair never matches. */
+function testOrder(order, test) {
+    return order !== undefined && test(order);
+}
 /**
  * Ordered comparison over like-typed values only: numbers compare numerically,
  * strings lexicographically, and a mismatched or unordered pair never matches.
@@ -14,11 +32,13 @@ const node_util_1 = require("node:util");
  * directly is well-defined in both cases.
  */
 function compareOrdered(actual, expected, test) {
-    const comparable = (typeof actual === 'number' && typeof expected === 'number') ||
-        (typeof actual === 'string' && typeof expected === 'string');
-    if (!comparable)
-        return false;
-    return test(actual === expected ? 0 : actual > expected ? 1 : -1);
+    if (typeof actual === 'number' && typeof expected === 'number') {
+        return testOrder(orderOf(actual, expected), test);
+    }
+    if (typeof actual === 'string' && typeof expected === 'string') {
+        return testOrder(orderOf(actual, expected), test);
+    }
+    return false;
 }
 const COMPARATORS = {
     $eq: (actual, expected) => (0, node_util_1.isDeepStrictEqual)(actual, expected),
@@ -63,4 +83,3 @@ function matchesStoreFilter(value, filter) {
      *  prototype chain and be compared as if it were stored data. */
     matchesCondition(Object.hasOwn(value, field) ? value[field] : undefined, condition));
 }
-//# sourceMappingURL=filter.js.map

package/dist/store/internal/index-reconcile.d.ts

@@ -7,16 +7,15 @@ export interface ReconcileTarget {
     embedding: number[] | undefined;
 }
 /**
- * Enumerate canonical items under `prefix`, recomputing each embedding. A failed
- * embedding rejects the whole reconcile by design: silently skipping an item
- * would drop it from the live set, after which {@link selectOrphans} would prune
- * its still-valid backend vector. Fail-fast keeps the backend from losing data.
+ * Enumerate the live (unexpired) items under `prefix`, then recompute their
+ * embeddings in batches. A failed embedding rejects the whole reconcile: a
+ * skipped item would leave the live set and {@link selectOrphans} would prune
+ * its still-valid vector.
  */
-export declare function collectReconcileTargets(context: StoreContext, prefix: string[]): Promise<ReconcileTarget[]>;
+export declare function collectReconcileTargets(context: StoreContext, prefix: string[], signal?: AbortSignal): Promise<ReconcileTarget[]>;
 /** Re-push every live embedding to the backend; returns the upsert count. */
 export declare function pushEmbeddings(backend: VectorBackend, targets: ReconcileTarget[]): Promise<number>;
 /** Refs present in the backend but absent from `live` — orphans to prune. */
 export declare function selectOrphans(backendRefs: VectorRef[], live: ReconcileTarget[]): VectorRef[];
 /** Delete backend vectors with no canonical item; returns the prune count. */
 export declare function pruneOrphans(context: StoreContext, backend: VectorBackend, prefix: string[], live: ReconcileTarget[]): Promise<number>;
-//# sourceMappingURL=index-reconcile.d.ts.map

package/dist/store/internal/index-reconcile.js

@@ -4,7 +4,10 @@ exports.collectReconcileTargets = collectReconcileTargets;
 exports.pushEmbeddings = pushEmbeddings;
 exports.selectOrphans = selectOrphans;
 exports.pruneOrphans = pruneOrphans;
+const clock_1 = require("../../shared/clock");
+const expiry_1 = require("../../shared/dynamodb/expiry");
 const paginate_1 = require("../../shared/dynamodb/paginate");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
 const item_mapper_1 = require("./item-mapper");
 const keys_1 = require("./keys");
 const query_1 = require("./query");
@@ -15,27 +18,44 @@ function refIdentity(namespace, key) {
     return JSON.stringify([...namespace, key]);
 }
 /**
- * Enumerate canonical items under `prefix`, recomputing each embedding. A failed
- * embedding rejects the whole reconcile by design: silently skipping an item
- * would drop it from the live set, after which {@link selectOrphans} would prune
- * its still-valid backend vector. Fail-fast keeps the backend from losing data.
+ * Enumerate the live (unexpired) items under `prefix`, then recompute their
+ * embeddings in batches. A failed embedding rejects the whole reconcile: a
+ * skipped item would leave the live set and {@link selectOrphans} would prune
+ * its still-valid vector.
  */
-async function collectReconcileTargets(context, prefix) {
-    const targets = [];
+async function collectReconcileTargets(context, prefix, signal) {
+    const now = (0, clock_1.nowSeconds)();
+    const live = [];
     const source = (0, paginate_1.paginateQuery)({
+        retry: (0, retry_policy_1.retryFor)(context, signal),
+        signal,
         client: context.client,
-        params: (0, query_1.scopedQuery)(context.tableName, prefix),
+        params: (0, expiry_1.withoutExpired)((0, query_1.scopedQuery)(context.tableName, prefix), now),
         maxItems: context.maxScanItems,
     });
     for await (const raw of source) {
-        const record = raw;
-        if (!record.namespace || !(0, keys_1.namespaceMatchesPrefix)(record.namespace, prefix))
+        const record = (0, item_mapper_1.narrowStoreRecord)(raw);
+        if (!record) {
+            context.logger.warn('reconcileVectorIndex: skipped a row that is not a store item', {
+                sortKey: raw.SK,
+            });
+            continue;
+        }
+        if ((0, expiry_1.isExpiredRow)(record, now) || !(0, keys_1.namespaceMatchesPrefix)(record.namespace, prefix))
             continue;
         const item = await (0, item_mapper_1.readStoreItem)(context, record);
-        const embedding = await (0, semantic_search_1.embedValue)(context, item.value);
-        targets.push({ namespace: record.namespace, key: record.key, embedding });
+        live.push({
+            namespace: record.namespace,
+            key: record.key,
+            value: item.value,
+        });
     }
-    return targets;
+    const embeddings = await (0, semantic_search_1.embedValues)(context, live.map((entry) => entry.value));
+    return live.map((entry, i) => ({
+        namespace: entry.namespace,
+        key: entry.key,
+        embedding: embeddings[i],
+    }));
 }
 /** Re-push every live embedding to the backend; returns the upsert count. */
 async function pushEmbeddings(backend, targets) {
@@ -96,4 +116,3 @@ async function pruneOrphans(context, backend, prefix, live) {
     }
     return pruned;
 }
-//# sourceMappingURL=index-reconcile.js.map

package/dist/store/internal/index-sync.d.ts

@@ -8,4 +8,3 @@ import type { VectorBackend } from '../vector-backend';
  * drift — so a backend hiccup never fails an otherwise-successful put.
  */
 export declare function syncVectorIndex(backend: VectorBackend, namespace: string[], key: string, embedding: number[] | undefined, logger: Logger): Promise<void>;
-//# sourceMappingURL=index-sync.d.ts.map

package/dist/store/internal/index-sync.js

@@ -23,4 +23,3 @@ async function syncVectorIndex(backend, namespace, key, embedding, logger) {
         });
     }
 }
-//# sourceMappingURL=index-sync.js.map

package/dist/store/internal/item-mapper.d.ts

@@ -5,8 +5,11 @@ import type { JsonValue } from './filter';
 import type { StoreContext } from './setup';
 /**
  * Narrow a raw scanned row to a {@link StoreItemRecord}, or `undefined` for a
- * foreign row on a shared table (no `namespace`). Replaces an unchecked cast at
- * the scan boundary, the one place rows are not written by this library.
+ * foreign row on a shared table (no `namespace`) — and for a row whose
+ * `namespace`/`key` attributes disagree with the DynamoDB key it was found at.
+ * The attributes name the S3 path the row may reference, so they must be bound
+ * to the partition the row actually lives in: a writer confined to its own
+ * partition can then never make a row speak for another tenant's objects.
  */
 export declare function narrowStoreRecord(raw: DocItem): StoreItemRecord | undefined;
 /** Fields controlling a stored item's timestamps, embedding, ttl, and S3 key nonce. */
@@ -15,10 +18,10 @@ export interface BuildItemOptions {
     updatedAt: string;
     embedding?: number[];
     ttlTimestamp?: number;
+    /** Per-call nonce: uniquifies the S3 key and becomes the row's revision token. */
     nonce?: string;
 }
 /** Encode a value into the DynamoDB record for a stored item. */
 export declare function buildStoreItem(context: StoreContext, namespace: string[], key: string, value: Record<string, JsonValue>, options: BuildItemOptions): Promise<StoreItemRecord>;
 /** Decode a DynamoDB record back into a store {@link Item}. */
 export declare function readStoreItem(context: StoreContext, record: StoreItemRecord): Promise<Item>;
-//# sourceMappingURL=item-mapper.d.ts.map

package/dist/store/internal/item-mapper.js

@@ -4,14 +4,23 @@ exports.narrowStoreRecord = narrowStoreRecord;
 exports.buildStoreItem = buildStoreItem;
 exports.readStoreItem = readStoreItem;
 const codec_1 = require("../../shared/codec/codec");
+const encode_1 = require("../../shared/codec/encode");
 const keys_1 = require("./keys");
 /**
  * Narrow a raw scanned row to a {@link StoreItemRecord}, or `undefined` for a
- * foreign row on a shared table (no `namespace`). Replaces an unchecked cast at
- * the scan boundary, the one place rows are not written by this library.
+ * foreign row on a shared table (no `namespace`) — and for a row whose
+ * `namespace`/`key` attributes disagree with the DynamoDB key it was found at.
+ * The attributes name the S3 path the row may reference, so they must be bound
+ * to the partition the row actually lives in: a writer confined to its own
+ * partition can then never make a row speak for another tenant's objects.
  */
 function narrowStoreRecord(raw) {
-    return Array.isArray(raw.namespace) ? raw : undefined;
+    if (!Array.isArray(raw.namespace) || typeof raw.key !== 'string')
+        return undefined;
+    const record = raw;
+    const consistent = record.PK === (0, keys_1.partitionKey)(record.namespace) &&
+        record.SK === (0, keys_1.sortKey)(record.namespace, record.key);
+    return consistent ? record : undefined;
 }
 /** Map a store context to the codec collaborators. */
 function storeCodecDeps(context) {
@@ -19,7 +28,7 @@ function storeCodecDeps(context) {
 }
 /** Encode a value into the DynamoDB record for a stored item. */
 async function buildStoreItem(context, namespace, key, value, options) {
-    const descriptor = await (0, codec_1.encodePayload)(value, storeCodecDeps(context), {
+    const descriptor = await (0, encode_1.encodePayload)(value, storeCodecDeps(context), {
         keyParts: options.nonce === undefined ? [...namespace, key] : [...namespace, key, options.nonce],
     });
     const record = {
@@ -35,11 +44,13 @@ async function buildStoreItem(context, namespace, key, value, options) {
         record.embedding = options.embedding;
     if (options.ttlTimestamp !== undefined)
         record.ttl = options.ttlTimestamp;
+    if (options.nonce !== undefined)
+        record.rev = options.nonce;
     return record;
 }
 /** Decode a DynamoDB record back into a store {@link Item}. */
 async function readStoreItem(context, record) {
-    const value = await (0, codec_1.decodePayload)(record.value, storeCodecDeps(context));
+    const value = await (0, codec_1.decodePayload)(record.value, storeCodecDeps(context), [...record.namespace, record.key]);
     return {
         namespace: record.namespace,
         key: record.key,
@@ -48,4 +59,3 @@ async function readStoreItem(context, record) {
         updatedAt: new Date(record.updatedAt),
     };
 }
-//# sourceMappingURL=item-mapper.js.map

package/dist/store/internal/keys.d.ts

@@ -15,4 +15,3 @@ export declare function sortKeyPrefix(prefix: string[]): string;
  * as a string prefix, so ["userspace"] does not match prefix ["users"]).
  */
 export declare function namespaceMatchesPrefix(namespace: string[], prefix: string[]): boolean;
-//# sourceMappingURL=keys.d.ts.map

package/dist/store/internal/keys.js

@@ -39,4 +39,3 @@ function namespaceMatchesPrefix(namespace, prefix) {
         return false;
     return prefix.every((element, index) => namespace[index] === element);
 }
-//# sourceMappingURL=keys.js.map

package/dist/store/internal/namespace-match.d.ts

@@ -9,4 +9,3 @@ export declare function truncateDepth(namespace: string[], maxDepth?: number): s
  * must fall back to a Scan.
  */
 export declare function prefixRoot(conditions?: MatchCondition[]): string[];
-//# sourceMappingURL=namespace-match.d.ts.map

package/dist/store/internal/namespace-match.js

@@ -38,4 +38,3 @@ function prefixRoot(conditions) {
     }
     return root;
 }
-//# sourceMappingURL=namespace-match.js.map

package/dist/store/internal/option-validation.d.ts

@@ -0,0 +1,13 @@
+import type { DynamoDBStoreOptions } from '../types';
+/**
+ * Validate every store option at construction, shared options first.
+ *
+ * A `vectorBackend` without an `index` is rejected outright rather than
+ * silently degrading: with no embeddings configured, every `put` would compute
+ * no vector and instruct the backend to *delete* the item's entry instead of
+ * indexing it, and `search()` would fall through to an unranked scan-order
+ * listing with no `.score` field and no error — a semantic query returning a
+ * normal-looking but meaningless response. `reconcileVectorIndex` already
+ * refused this exact misconfiguration.
+ */
+export declare function validateStoreOptions(options: DynamoDBStoreOptions): void;

package/dist/store/internal/option-validation.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateStoreOptions = validateStoreOptions;
+const errors_1 = require("../../shared/errors/errors");
+const options_1 = require("../../shared/validation/options");
+const primitives_1 = require("../../shared/validation/primitives");
+const score_direction_1 = require("./score-direction");
+/**
+ * Reject an `index` that cannot actually embed. `IndexConfig` mandates
+ * `embeddings`, but a JavaScript caller can omit it or pass the wrong shape,
+ * and the failure then surfaced as a raw `TypeError` deep inside the first
+ * `put()`/`search()` rather than this library's typed error at construction.
+ *
+ * Both methods are required: documents are embedded with `embedDocuments()`
+ * on `put()` and queries with `embedQuery()` on `search()`. `dims` is only
+ * compared against returned vectors when it is a positive integer, so a
+ * configuration that omits it keeps working.
+ */
+function assertUsableIndex(index) {
+    if (!index)
+        return;
+    const embeddings = index.embeddings;
+    const missing = ['embedQuery', 'embedDocuments'].find((method) => typeof embeddings?.[method] !== 'function');
+    if (missing === undefined)
+        return;
+    throw new errors_1.ValidationError(`\`index.embeddings\` must be an Embeddings implementation exposing ${missing}(); ` +
+        'documents are embedded with embedDocuments() on put() and queries with embedQuery() ' +
+        'on search()', 'index');
+}
+/**
+ * Reject a `vectorScoreDirection` outside the declared union.
+ *
+ * {@link toRelevanceScores} treats anything it does not recognise as a no-op —
+ * the only safe default, since guessing would invert a ranking — so a mistyped
+ * or config-file-sourced value would otherwise leave a distance backend ranked
+ * backwards with no error and no warning anywhere. Same premise as
+ * {@link assertUsableIndex}: a JavaScript caller can pass a string the type
+ * never admits.
+ */
+function assertScoreDirection(direction) {
+    if (direction === undefined || score_direction_1.VECTOR_SCORE_DIRECTIONS.includes(direction))
+        return;
+    throw new errors_1.ValidationError(`vectorScoreDirection must be one of ${score_direction_1.VECTOR_SCORE_DIRECTIONS.join(' | ')}; received ` +
+        `${JSON.stringify(direction)}, which would be left in the backend's own direction and ` +
+        'could rank a distance backend backwards', 'vectorScoreDirection');
+}
+/** Both in-memory caps must be positive integers; 0 would silently return nothing. */
+function validateLimits(options) {
+    if (options.maxScanItems !== undefined) {
+        (0, primitives_1.validateInteger)(options.maxScanItems, 'maxScanItems', { min: 1 });
+    }
+    if (options.maxSearchCandidates !== undefined) {
+        (0, primitives_1.validateInteger)(options.maxSearchCandidates, 'maxSearchCandidates', { min: 1 });
+    }
+}
+/**
+ * Validate every store option at construction, shared options first.
+ *
+ * A `vectorBackend` without an `index` is rejected outright rather than
+ * silently degrading: with no embeddings configured, every `put` would compute
+ * no vector and instruct the backend to *delete* the item's entry instead of
+ * indexing it, and `search()` would fall through to an unranked scan-order
+ * listing with no `.score` field and no error — a semantic query returning a
+ * normal-looking but meaningless response. `reconcileVectorIndex` already
+ * refused this exact misconfiguration.
+ */
+function validateStoreOptions(options) {
+    (0, options_1.validateBaseAdapterOptions)(options);
+    validateLimits(options);
+    if (options.vectorBackend && !options.index) {
+        throw new errors_1.ValidationError('vectorBackend requires a configured `index` (embeddings); without one no embedding ' +
+            'is computed, every put would clear the item vector, and search would silently return ' +
+            'unranked, score-less results', 'vectorBackend');
+    }
+    assertUsableIndex(options.index);
+    assertScoreDirection(options.vectorScoreDirection);
+}

package/dist/store/internal/overwrite-swap.d.ts

@@ -0,0 +1,32 @@
+import type { StoreItemRecord } from '../types';
+import { type ExistingRecordMeta } from './read-existing';
+import type { StoreContext } from './setup';
+/**
+ * Commit `record`, re-reading and retrying while another writer holds the row,
+ * and return the state this write actually superseded — the only descriptor
+ * safe to delete afterwards.
+ *
+ * Without the swap both racers read the same previous descriptor, both commit,
+ * and both delete it, orphaning the loser's own upload. Retrying against the
+ * *re-read* state is what makes each writer supersede exactly one payload.
+ *
+ * A rejection is not proof a competitor won: `withDynamoDBRetry` retries
+ * transient errors, so an attempt can commit server-side, its response can be
+ * lost, and the retried put can hit the row it just wrote and fail the same
+ * guard — indistinguishable from a competitor's win by the rejection alone.
+ * Each attempt's pinned observation is captured in `attempted` before the
+ * put, so that when a re-read finds the row already holding *this call's
+ * own* `rev`, the swap returns whatever `attempted` held — never this
+ * record's own just-committed value, which would strand the live row
+ * pointing at a deleted object. That comparison is guarded on `rev` being
+ * set: `rev` is optional on the record type, and an unnonced record against a
+ * pre-0.9.0 revision-less row would otherwise match `undefined === undefined`
+ * and claim a race it never entered.
+ *
+ * On exhaustion the write proceeds unconditionally and warns. That is
+ * deliberate: the fallback is precisely the pre-0.9.0 behaviour — one possible
+ * orphan, reclaimed by a lifecycle rule — so pathological contention degrades
+ * instead of turning a working put into an error. `createdAt` is refreshed from
+ * each re-read so a row created by whoever won keeps its true creation time.
+ */
+export declare function putWithRevisionSwap(context: StoreContext, record: StoreItemRecord, existing: ExistingRecordMeta): Promise<ExistingRecordMeta>;

package/dist/store/internal/overwrite-swap.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.putWithRevisionSwap = putWithRevisionSwap;
+const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
+const retry_1 = require("../../shared/dynamodb/retry");
+const read_existing_1 = require("./read-existing");
+/** Put the record, optionally pinned to the revision the caller observed. */
+async function put(context, record, observed) {
+    const guard = observed ? (0, conditional_put_1.revisionGuard)(conditional_put_1.REVISION_ATTRIBUTE, observed) : {};
+    await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: record, ...guard }), context.retry);
+}
+/**
+ * Commit `record`, re-reading and retrying while another writer holds the row,
+ * and return the state this write actually superseded — the only descriptor
+ * safe to delete afterwards.
+ *
+ * Without the swap both racers read the same previous descriptor, both commit,
+ * and both delete it, orphaning the loser's own upload. Retrying against the
+ * *re-read* state is what makes each writer supersede exactly one payload.
+ *
+ * A rejection is not proof a competitor won: `withDynamoDBRetry` retries
+ * transient errors, so an attempt can commit server-side, its response can be
+ * lost, and the retried put can hit the row it just wrote and fail the same
+ * guard — indistinguishable from a competitor's win by the rejection alone.
+ * Each attempt's pinned observation is captured in `attempted` before the
+ * put, so that when a re-read finds the row already holding *this call's
+ * own* `rev`, the swap returns whatever `attempted` held — never this
+ * record's own just-committed value, which would strand the live row
+ * pointing at a deleted object. That comparison is guarded on `rev` being
+ * set: `rev` is optional on the record type, and an unnonced record against a
+ * pre-0.9.0 revision-less row would otherwise match `undefined === undefined`
+ * and claim a race it never entered.
+ *
+ * On exhaustion the write proceeds unconditionally and warns. That is
+ * deliberate: the fallback is precisely the pre-0.9.0 behaviour — one possible
+ * orphan, reclaimed by a lifecycle rule — so pathological contention degrades
+ * instead of turning a working put into an error. `createdAt` is refreshed from
+ * each re-read so a row created by whoever won keeps its true creation time.
+ */
+async function putWithRevisionSwap(context, record, existing) {
+    let observed = existing;
+    for (let attempt = 1; attempt <= conditional_put_1.OVERWRITE_CAS_MAX_ATTEMPTS; attempt++) {
+        const attempted = observed;
+        try {
+            await put(context, record, attempted);
+            return attempted;
+        }
+        catch (error) {
+            if (!(0, conditional_put_1.isConditionalCheckFailed)(error))
+                throw error;
+            /** The rejection carries the row that turned it away; the read is spent only when it does not. */
+            const rejected = (0, conditional_put_1.rejectedItem)(error);
+            observed = rejected
+                ? (0, read_existing_1.existingFrom)(rejected)
+                : await (0, read_existing_1.readExisting)(context, record.PK, record.SK);
+            if (record.rev !== undefined && observed.revision === record.rev)
+                return attempted;
+            /** A row that vanished between attempts (a concurrent delete) makes this a fresh creation. */
+            record.createdAt = observed.exists
+                ? (observed.createdAt ?? record.createdAt)
+                : record.updatedAt;
+        }
+    }
+    context.logger.warn('store.put: compare-and-swap exhausted; overwriting unconditionally, which can orphan one ' +
+        'S3 object under a concurrent put (reclaimed by ensureS3LifecycleRule)', { namespace: record.namespace, key: record.key, attempts: conditional_put_1.OVERWRITE_CAS_MAX_ATTEMPTS });
+    await put(context, record);
+    return observed;
+}

package/dist/store/internal/persist.d.ts

@@ -1,11 +1,28 @@
-import { type PayloadDescriptor } from '../../shared/codec/codec';
 import type { StoreItemRecord } from '../types';
+import type { ExistingRecordMeta } from './read-existing';
 import type { StoreContext } from './setup';
 /**
- * Put the record: on a definite failure, clean up *this* record's nonced S3
- * object; on an ambiguous retry-exhaustion failure, verify via
- * `writeLandedAt` before deleting anything — if it landed, clean up the
- * *previous* row's object instead, like the ordinary success path.
+ * Put the record and clean up whichever side is now dead.
+ *
+ * The compare-and-swap path runs **only when an offloader is configured**:
+ * without one there is no S3 object to orphan, so a plain last-write-wins put
+ * stays correct and costs no extra write capacity (DynamoDB charges for a
+ * failed conditional write too). With one, the swap is what lets this call
+ * delete exactly the payload it superseded rather than a descriptor a racer may
+ * already have replaced.
+ *
+ * Every failure reaching the catch arrives after at least one put was issued —
+ * `putWithRevisionSwap` only re-reads from inside its own catch — so none of
+ * them proves a non-commit on its own: a put can commit server-side and lose
+ * its response, and a `ConditionalCheckFailedException` is as consistent with
+ * hitting the row this call just wrote as with a competitor's win. The row is
+ * therefore read back (`verifyWriteLanded`) before anything is deleted. Only a
+ * confirmed `'not-landed'` deletes this record's own nonced object; a confirmed
+ * `'landed'` cleans up the previous object like the success path and swallows
+ * the error, and an `'unverified'` read deletes nothing and rethrows — leaking
+ * one object at worst rather than stranding a live row pointing at a deleted
+ * one. The verification compares the per-call `rev`, so an inline record is
+ * verified too: a lost acknowledgement of an inline overwrite used to be
+ * reported as a failure while the previous offloaded object was never cleaned.
  */
-export declare function persistRecord(context: StoreContext, record: StoreItemRecord, previousValue: PayloadDescriptor | undefined): Promise<void>;
-//# sourceMappingURL=persist.d.ts.map
+export declare function persistRecord(context: StoreContext, record: StoreItemRecord, existing: ExistingRecordMeta): Promise<void>;

package/dist/store/internal/persist.js

@@ -1,34 +1,64 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.persistRecord = persistRecord;
-const codec_1 = require("../../shared/codec/codec");
 const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
 const orphans_1 = require("../../shared/codec/s3/orphans");
 const retry_1 = require("../../shared/dynamodb/retry");
+const overwrite_swap_1 = require("./overwrite-swap");
 const write_verify_1 = require("./write-verify");
 /**
- * Put the record: on a definite failure, clean up *this* record's nonced S3
- * object; on an ambiguous retry-exhaustion failure, verify via
- * `writeLandedAt` before deleting anything — if it landed, clean up the
- * *previous* row's object instead, like the ordinary success path.
+ * Best-effort delete of one descriptor's S3 object. `scope` is passed for a
+ * descriptor read back from the row (the superseded value) and omitted for
+ * this call's own upload.
  */
-async function persistRecord(context, record, previousValue) {
+async function cleanUp(context, descriptor, label, scope) {
+    if (!context.offloader || !descriptor)
+        return;
+    await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([descriptor]), label, context.logger, scope === undefined ? {} : { scope });
+}
+/**
+ * Put the record and clean up whichever side is now dead.
+ *
+ * The compare-and-swap path runs **only when an offloader is configured**:
+ * without one there is no S3 object to orphan, so a plain last-write-wins put
+ * stays correct and costs no extra write capacity (DynamoDB charges for a
+ * failed conditional write too). With one, the swap is what lets this call
+ * delete exactly the payload it superseded rather than a descriptor a racer may
+ * already have replaced.
+ *
+ * Every failure reaching the catch arrives after at least one put was issued —
+ * `putWithRevisionSwap` only re-reads from inside its own catch — so none of
+ * them proves a non-commit on its own: a put can commit server-side and lose
+ * its response, and a `ConditionalCheckFailedException` is as consistent with
+ * hitting the row this call just wrote as with a competitor's win. The row is
+ * therefore read back (`verifyWriteLanded`) before anything is deleted. Only a
+ * confirmed `'not-landed'` deletes this record's own nonced object; a confirmed
+ * `'landed'` cleans up the previous object like the success path and swallows
+ * the error, and an `'unverified'` read deletes nothing and rethrows — leaking
+ * one object at worst rather than stranding a live row pointing at a deleted
+ * one. The verification compares the per-call `rev`, so an inline record is
+ * verified too: a lost acknowledgement of an inline overwrite used to be
+ * reported as a failure while the previous offloaded object was never cleaned.
+ */
+async function persistRecord(context, record, existing) {
+    let superseded = existing;
     try {
-        await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: record }));
+        if (context.offloader) {
+            superseded = await (0, overwrite_swap_1.putWithRevisionSwap)(context, record, existing);
+        }
+        else {
+            await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: record }), context.retry);
+        }
     }
     catch (error) {
-        const landed = (0, write_verify_1.isRetryExhausted)(error) &&
-            record.value.location === codec_1.PayloadLocation.S3 &&
-            (await (0, write_verify_1.writeLandedAt)(context, record, record.value.s3Key));
-        if (!landed) {
-            if (context.offloader) {
-                await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([record.value]), 'store.put', context.logger);
-            }
+        const verdict = await (0, write_verify_1.verifyWriteLanded)(context, record);
+        if (verdict === 'not-landed')
+            await cleanUp(context, record.value, 'store.put');
+        if (verdict !== 'landed')
             throw error;
-        }
-    }
-    if (context.offloader && previousValue) {
-        await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([previousValue]), 'store.put.overwrite', context.logger);
     }
+    await cleanUp(context, superseded.value, 'store.put.overwrite', [
+        ...record.namespace,
+        record.key,
+    ]);
 }
-//# sourceMappingURL=persist.js.map

package/dist/store/internal/query.d.ts

@@ -3,4 +3,9 @@ import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb'
 export declare function scopedQuery(tableName: string, prefix: string[]): QueryCommandInput;
 /** Scan input for the rootless case, filtered to store items only. */
 export declare function storeScan(tableName: string): ScanCommandInput;
-//# sourceMappingURL=query.d.ts.map
+/**
+ * Restrict a Query/Scan to the attributes `narrowStoreRecord` needs, leaving the
+ * payload behind: a namespace listing never reads a value. RCU is billed on
+ * the stored size regardless, so the saving is transfer and unmarshalling.
+ */
+export declare function projectKeys<T extends QueryCommandInput | ScanCommandInput>(params: T): T;

package/dist/store/internal/query.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scopedQuery = scopedQuery;
 exports.storeScan = storeScan;
+exports.projectKeys = projectKeys;
 const keys_1 = require("./keys");
 /** Query input for a scoped prefix (PK = prefix[0], optional SK begins_with). */
 function scopedQuery(tableName, prefix) {
@@ -29,4 +30,19 @@ function storeScan(tableName) {
         ExpressionAttributeNames: { '#ns': 'namespace' },
     };
 }
-//# sourceMappingURL=query.js.map
+/**
+ * Restrict a Query/Scan to the attributes `narrowStoreRecord` needs, leaving the
+ * payload behind: a namespace listing never reads a value. RCU is billed on
+ * the stored size regardless, so the saving is transfer and unmarshalling.
+ */
+function projectKeys(params) {
+    return {
+        ...params,
+        ProjectionExpression: 'PK, SK, #ns, #key',
+        ExpressionAttributeNames: {
+            ...params.ExpressionAttributeNames,
+            '#ns': 'namespace',
+            '#key': 'key',
+        },
+    };
+}

package/dist/store/internal/ranker.d.ts

@@ -8,6 +8,11 @@ export interface RankCandidate {
  * Rank candidates by cosine similarity to `queryVector`, descending. Throws a
  * {@link ValidationError} when the candidate count exceeds `maxCandidates`
  * (steer large corpora to an external VectorBackend).
+ *
+ * A stored embedding whose length differs from the query vector's cannot be
+ * scored — it was written by a different embeddings model — and is ranked
+ * last with an undefined score. `onDimensionMismatch` is invoked once with
+ * how many candidates that affected, so the caller can say so instead of
+ * silently returning a ranking that quietly omits them.
  */
-export declare function rankInMemory(candidates: RankCandidate[], queryVector: number[], maxCandidates: number): SearchItem[];
-//# sourceMappingURL=ranker.d.ts.map
+export declare function rankInMemory(candidates: RankCandidate[], queryVector: number[], maxCandidates: number, onDimensionMismatch?: (count: number) => void): SearchItem[];