@farukada/aws-langgraph-dynamodb-ts 0.8.0 → 0.9.0

package/dist/store/internal/score-direction.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VECTOR_SCORE_DIRECTIONS = void 0;
+exports.toRelevanceScores = toRelevanceScores;
+/** Every direction {@link toRelevanceScores} recognises, for validating input. */
+exports.VECTOR_SCORE_DIRECTIONS = ['relevance', 'distance'];
+/**
+ * Normalise a backend's matches to the relevance direction upstream
+ * `SearchItem.score` documents — "higher scores indicate better matches",
+ * typically a cosine similarity between -1 and 1.
+ *
+ * A distance is converted by **negation** rather than `1 / (1 + d)`: negation
+ * is monotone over the whole real line, needs no non-negativity precondition,
+ * and is exactly invertible, so the original distance is simply `-score`. A
+ * reciprocal would silently imply a different `(0, 1]` scale and is undefined
+ * at `d === -1`. Negative scores are already in range for this contract, so
+ * nothing is lost by producing them.
+ *
+ * Results are re-sorted after conversion so a backend that returns its matches
+ * in some other order still ranks correctly. Anything that is not `'distance'`
+ * is returned untouched — its own order stays authoritative, exactly as before.
+ *
+ * The test is for `'distance'` rather than against `'relevance'` on purpose:
+ * converting is the destructive branch, so only the exact value that asks for
+ * it may reach it. Testing the other way round made every unrecognised
+ * string — `'Distance'`, a typo, a value read from a config file — reverse the
+ * ranking silently, with no error and no warning (the ascending-score warning
+ * lives downstream of this conversion, so it could never fire). `setUpStore`
+ * rejects such a value outright; this keeps the failure harmless for any
+ * caller that reaches the function some other way.
+ */
+function toRelevanceScores(matches, direction) {
+    if (direction !== 'distance')
+        return matches;
+    return matches
+        .map((match) => ({ ...match, score: -match.score }))
+        .sort((left, right) => right.score - left.score);
+}
+//# sourceMappingURL=score-direction.js.map

package/dist/store/internal/score-direction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-direction.js","sourceRoot":"","sources":["../../../src/store/internal/score-direction.ts"],"names":[],"mappings":";;;;AAKA,kFAAkF;AACrE,QAAA,uBAAuB,GAAoC,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;AAElG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,2BACE,OAAsB,EACtB,SAA+B;IAE/B,IAAI,SAAS,KAAK,UAAU;QAAE,OAAO,OAAO,CAAC;IAC7C,OAAO,OAAO;SACX,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;SACnD,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;AACrD,CAAC"}

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

@@ -7,6 +7,7 @@ import { type Logger } from '../../shared/logging/logger';
 import type { TtlOption } from '../../shared/validation/ttl';
 import type { DynamoDBStoreOptions } from '../types';
 import type { VectorBackend } from '../vector-backend';
+import { type VectorScoreDirection } from './score-direction';
 /** Resolved collaborators shared by every store action. */
 export interface StoreContext {
     client: DynamoDBDocument;
@@ -18,6 +19,7 @@ export interface StoreContext {
     logger: Logger;
     index?: IndexConfig;
     vectorBackend?: VectorBackend;
+    vectorScoreDirection: VectorScoreDirection;
     maxSearchCandidates: number;
     maxScanItems: number;
 }

package/dist/store/internal/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/store/internal/setup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAEvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGxE,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAQ9D,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,6BAA6B,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,cAAc,GAAG,SAAS,CAAC;IACtC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU,CAiCpE"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/store/internal/setup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAEvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGxE,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAQ9D,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,6BAA6B,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAA2B,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEvF,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,oBAAoB,EAAE,oBAAoB,CAAC;IAC3C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,cAAc,GAAG,SAAS,CAAC;IACtC,UAAU,EAAE,OAAO,CAAC;CACrB;AA4CD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU,CAoCpE"}

package/dist/store/internal/setup.js

@@ -8,6 +8,43 @@ const constants_1 = require("../../shared/constants");
 const client_1 = require("../../shared/dynamodb/client");
 const errors_1 = require("../../shared/errors/errors");
 const logger_1 = require("../../shared/logging/logger");
+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.
+ *
+ * Only `embeddings` is checked. `dims` is part of the upstream type but is
+ * never read anywhere in this package, so rejecting a configuration over it
+ * would break working callers for no benefit.
+ */
+function assertUsableIndex(index) {
+    if (!index)
+        return;
+    const embeddings = index.embeddings;
+    if (typeof embeddings?.embedQuery !== 'function') {
+        throw new errors_1.ValidationError('`index.embeddings` must be an Embeddings implementation exposing embedQuery(); ' +
+            'without one no embedding can be computed for put() or 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');
+}
 /**
  * Resolve the client, optional S3 offloader, serializer, and index config.
  *
@@ -21,10 +58,12 @@ const logger_1 = require("../../shared/logging/logger");
  */
 function setUpStore(options) {
     if (options.vectorBackend && !options.index) {
-        throw new errors_1.ValidationError('vectorBackend requires a configured `index` (dims + embeddings); without one no embedding ' +
+        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);
     const resolved = (0, client_1.resolveDynamoDBClient)(options);
     return {
         context: {
@@ -42,6 +81,7 @@ function setUpStore(options) {
             logger: (0, logger_1.resolveLogger)(options.logger),
             index: options.index,
             vectorBackend: options.vectorBackend,
+            vectorScoreDirection: options.vectorScoreDirection ?? 'relevance',
             maxSearchCandidates: options.maxSearchCandidates ?? constants_1.DEFAULT_MAX_SEARCH_CANDIDATES,
             maxScanItems: options.maxScanItems ?? constants_1.MAX_TOTAL_ITEMS_IN_MEMORY,
         },

package/dist/store/internal/setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../src/store/internal/setup.ts"],"names":[],"mappings":";;;AAKA,8DAA2D;AAC3D,yDAAuE;AACvE,+DAA8D;AAC9D,sDAIgC;AAChC,yDAAqE;AACrE,uDAA6D;AAC7D,wDAAyE;AA2BzE;;;;;;;;;;GAUG;AACH,oBAA2B,OAA6B;IACtD,IAAI,OAAO,CAAC,aAAa,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAC5C,MAAM,IAAI,wBAAe,CACvB,4FAA4F;YAC1F,uFAAuF;YACvF,8BAA8B,EAChC,eAAe,CAChB,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;IAChD,OAAO;QACL,OAAO,EAAE;YACP,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,uBAAU;YAClC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,SAAS,EAAE,OAAO,CAAC,EAAE;gBACnB,CAAC,CAAC,IAAI,uBAAW,CAAC;oBACd,GAAG,OAAO,CAAC,EAAE;oBACb,SAAS,EACP,OAAO,CAAC,EAAE,CAAC,SAAS,IAAI,IAAA,gCAAuB,EAAC,iCAAqB,EAAE,OAAO,CAAC;iBAClF,CAAC;gBACJ,CAAC,CAAC,SAAS;YACb,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,MAAM,EAAE,IAAA,sBAAa,EAAC,OAAO,CAAC,MAAM,CAAC;YACrC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,IAAI,yCAA6B;YACjF,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,qCAAyB;SAChE;QACD,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,UAAU,EAAE,QAAQ,CAAC,UAAU;KAChC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../src/store/internal/setup.ts"],"names":[],"mappings":";;;AAMA,8DAA2D;AAC3D,yDAAuE;AACvE,+DAA8D;AAC9D,sDAIgC;AAChC,yDAAqE;AACrE,uDAA6D;AAC7D,wDAAyE;AAIzE,uDAAuF;AAyBvF;;;;;;;;;GASG;AACH,SAAS,iBAAiB,CAAC,KAAmB;IAC5C,IAAI,CAAC,KAAK;QAAE,OAAO;IACnB,MAAM,UAAU,GAAoC,KAAK,CAAC,UAAU,CAAC;IACrE,IAAI,OAAO,UAAU,EAAE,UAAU,KAAK,UAAU,EAAE,CAAC;QACjD,MAAM,IAAI,wBAAe,CACvB,iFAAiF;YAC/E,gEAAgE,EAClE,OAAO,CACR,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,oBAAoB,CAAC,SAAgC;IAC5D,IAAI,SAAS,KAAK,SAAS,IAAI,yCAAuB,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO;IACnF,MAAM,IAAI,wBAAe,CACvB,uCAAuC,yCAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa;QACrF,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,2DAA2D;QACvF,yCAAyC,EAC3C,sBAAsB,CACvB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,oBAA2B,OAA6B;IACtD,IAAI,OAAO,CAAC,aAAa,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAC5C,MAAM,IAAI,wBAAe,CACvB,qFAAqF;YACnF,uFAAuF;YACvF,8BAA8B,EAChC,eAAe,CAChB,CAAC;IACJ,CAAC;IACD,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACjC,oBAAoB,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACnD,MAAM,QAAQ,GAAG,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;IAChD,OAAO;QACL,OAAO,EAAE;YACP,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,uBAAU;YAClC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,SAAS,EAAE,OAAO,CAAC,EAAE;gBACnB,CAAC,CAAC,IAAI,uBAAW,CAAC;oBACd,GAAG,OAAO,CAAC,EAAE;oBACb,SAAS,EACP,OAAO,CAAC,EAAE,CAAC,SAAS,IAAI,IAAA,gCAAuB,EAAC,iCAAqB,EAAE,OAAO,CAAC;iBAClF,CAAC;gBACJ,CAAC,CAAC,SAAS;YACb,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,MAAM,EAAE,IAAA,sBAAa,EAAC,OAAO,CAAC,MAAM,CAAC;YACrC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,IAAI,WAAW;YACjE,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,IAAI,yCAA6B;YACjF,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,qCAAyB;SAChE;QACD,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,UAAU,EAAE,QAAQ,CAAC,UAAU;KAChC,CAAC;AACJ,CAAC"}

package/dist/store/internal/write-verify.d.ts

@@ -5,20 +5,33 @@ export declare function isRetryExhausted(error: Error): boolean;
  * True when the row is confirmed absent — used to resolve an ambiguous
  * retry-exhausted *delete*, where the delete may well have landed server-side
  * and only its acknowledgement was lost. A failure reading this is not treated
- * as confirmation (fail safe), matching {@link writeLandedAt}.
+ * as confirmation, which is fail-safe here: the caller only rethrows, and
+ * nothing is deleted on the strength of a `false`.
  */
 export declare function rowIsAbsent(context: StoreContext, key: {
     PK: string;
     SK: string;
 }): Promise<boolean>;
+/** What a post-failure verification read could establish about a write. */
+export type WriteVerdict = 'landed' | 'not-landed' | 'unverified';
 /**
- * True when `record`'s row already holds the S3 key `expectedS3Key` — i.e. an
- * ambiguous retry-exhaustion write actually landed server-side and only its
- * acknowledgment was lost. A failure reading this (itself possible) is not
- * treated as confirmation — fail safe, matching the pre-fix behavior.
+ * Read `record`'s row back to establish what an ambiguous write actually did.
+ *
+ * - `'landed'`: the row holds `expectedS3Key`, so the write committed
+ *   server-side and only its acknowledgement was lost.
+ * - `'not-landed'`: the row was read and holds something else, or nothing, so
+ *   this call's own nonced upload is dead and safe to delete.
+ * - `'unverified'`: the read itself failed, so nothing is established.
+ *
+ * The third answer used to be folded into the second as a plain `false`, which
+ * made a partition that blocked both the put and this read delete the object a
+ * possibly-live row points at — permanently breaking every later read of that
+ * item. Only a *confirmed* non-commit may delete the new upload: leaking one
+ * object (reclaimed by `ensureS3LifecycleRule`) is recoverable, stranding a
+ * live row is not.
  */
-export declare function writeLandedAt(context: StoreContext, record: {
+export declare function verifyWriteLanded(context: StoreContext, record: {
     PK: string;
     SK: string;
-}, expectedS3Key: string): Promise<boolean>;
+}, expectedS3Key: string): Promise<WriteVerdict>;
 //# sourceMappingURL=write-verify.d.ts.map

package/dist/store/internal/write-verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-verify.d.ts","sourceRoot":"","sources":["../../../src/store/internal/write-verify.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,yGAAyG;AACzG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAEtD;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9B,OAAO,CAAC,OAAO,CAAC,CAelB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAClC,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,OAAO,CAAC,CAgBlB"}
+{"version":3,"file":"write-verify.d.ts","sourceRoot":"","sources":["../../../src/store/internal/write-verify.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,yGAAyG;AACzG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAEtD;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9B,OAAO,CAAC,OAAO,CAAC,CAelB;AAED,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,YAAY,GAAG,YAAY,CAAC;AAElE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAClC,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,YAAY,CAAC,CAkBvB"}

package/dist/store/internal/write-verify.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isRetryExhausted = isRetryExhausted;
 exports.rowIsAbsent = rowIsAbsent;
-exports.writeLandedAt = writeLandedAt;
+exports.verifyWriteLanded = verifyWriteLanded;
 const codec_1 = require("../../shared/codec/codec");
 const retry_1 = require("../../shared/dynamodb/retry");
 /** True when `error` is a {@link RetryExhaustedError} — by name, not `instanceof` (banned repo-wide). */
@@ -13,7 +13,8 @@ function isRetryExhausted(error) {
  * True when the row is confirmed absent — used to resolve an ambiguous
  * retry-exhausted *delete*, where the delete may well have landed server-side
  * and only its acknowledgement was lost. A failure reading this is not treated
- * as confirmation (fail safe), matching {@link writeLandedAt}.
+ * as confirmation, which is fail-safe here: the caller only rethrows, and
+ * nothing is deleted on the strength of a `false`.
  */
 async function rowIsAbsent(context, key) {
     try {
@@ -31,12 +32,22 @@ async function rowIsAbsent(context, key) {
     }
 }
 /**
- * True when `record`'s row already holds the S3 key `expectedS3Key` — i.e. an
- * ambiguous retry-exhaustion write actually landed server-side and only its
- * acknowledgment was lost. A failure reading this (itself possible) is not
- * treated as confirmation — fail safe, matching the pre-fix behavior.
+ * Read `record`'s row back to establish what an ambiguous write actually did.
+ *
+ * - `'landed'`: the row holds `expectedS3Key`, so the write committed
+ *   server-side and only its acknowledgement was lost.
+ * - `'not-landed'`: the row was read and holds something else, or nothing, so
+ *   this call's own nonced upload is dead and safe to delete.
+ * - `'unverified'`: the read itself failed, so nothing is established.
+ *
+ * The third answer used to be folded into the second as a plain `false`, which
+ * made a partition that blocked both the put and this read delete the object a
+ * possibly-live row points at — permanently breaking every later read of that
+ * item. Only a *confirmed* non-commit may delete the new upload: leaking one
+ * object (reclaimed by `ensureS3LifecycleRule`) is recoverable, stranding a
+ * live row is not.
  */
-async function writeLandedAt(context, record, expectedS3Key) {
+async function verifyWriteLanded(context, record, expectedS3Key) {
     try {
         const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
             TableName: context.tableName,
@@ -46,10 +57,12 @@ async function writeLandedAt(context, record, expectedS3Key) {
             ExpressionAttributeNames: { '#v': 'value' },
         }));
         const value = result.Item?.value;
-        return value?.location === codec_1.PayloadLocation.S3 && value.s3Key === expectedS3Key;
+        return value?.location === codec_1.PayloadLocation.S3 && value.s3Key === expectedS3Key
+            ? 'landed'
+            : 'not-landed';
     }
     catch {
-        return false;
+        return 'unverified';
     }
 }
 //# sourceMappingURL=write-verify.js.map

package/dist/store/internal/write-verify.js.map

@@ -1 +1 @@
-{"version":3,"file":"write-verify.js","sourceRoot":"","sources":["../../../src/store/internal/write-verify.ts"],"names":[],"mappings":";;;;;AAAA,oDAAmF;AACnF,uDAAgE;AAGhE,yGAAyG;AACzG,0BAAiC,KAAY;IAC3C,OAAO,KAAK,CAAC,IAAI,KAAK,qBAAqB,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACI,KAAK,sBACV,OAAqB,EACrB,GAA+B;IAE/B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC1C,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;YACjB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,GAAG,EAAE,GAAG;YACR,cAAc,EAAE,IAAI;YACpB,oBAAoB,EAAE,IAAI;YAC1B,wBAAwB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;SAC5C,CAAC,CACH,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACI,KAAK,wBACV,OAAqB,EACrB,MAAkC,EAClC,aAAqB;IAErB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC1C,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;YACjB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,GAAG,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE;YACrC,cAAc,EAAE,IAAI;YACpB,oBAAoB,EAAE,IAAI;YAC1B,wBAAwB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;SAC5C,CAAC,CACH,CAAC;QACF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,KAAsC,CAAC;QAClE,OAAO,KAAK,EAAE,QAAQ,KAAK,uBAAe,CAAC,EAAE,IAAI,KAAK,CAAC,KAAK,KAAK,aAAa,CAAC;IACjF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"write-verify.js","sourceRoot":"","sources":["../../../src/store/internal/write-verify.ts"],"names":[],"mappings":";;;;;AAAA,oDAAmF;AACnF,uDAAgE;AAGhE,yGAAyG;AACzG,0BAAiC,KAAY;IAC3C,OAAO,KAAK,CAAC,IAAI,KAAK,qBAAqB,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACI,KAAK,sBACV,OAAqB,EACrB,GAA+B;IAE/B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC1C,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;YACjB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,GAAG,EAAE,GAAG;YACR,cAAc,EAAE,IAAI;YACpB,oBAAoB,EAAE,IAAI;YAC1B,wBAAwB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;SAC5C,CAAC,CACH,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAKD;;;;;;;;;;;;;;;GAeG;AACI,KAAK,4BACV,OAAqB,EACrB,MAAkC,EAClC,aAAqB;IAErB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC1C,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;YACjB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,GAAG,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE;YACrC,cAAc,EAAE,IAAI;YACpB,oBAAoB,EAAE,IAAI;YAC1B,wBAAwB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;SAC5C,CAAC,CACH,CAAC;QACF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,KAAsC,CAAC;QAClE,OAAO,KAAK,EAAE,QAAQ,KAAK,uBAAe,CAAC,EAAE,IAAI,KAAK,CAAC,KAAK,KAAK,aAAa;YAC5E,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,YAAY,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,YAAY,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/store/types.d.ts

@@ -1,6 +1,7 @@
 import type { IndexConfig, SerializerProtocol } from '@langchain/langgraph-checkpoint';
 import type { PayloadDescriptor } from '../shared/codec/codec';
 import type { BaseAdapterOptions, CodecOptions } from '../shared/options';
+import type { VectorScoreDirection } from './internal/score-direction';
 import type { VectorBackend } from './vector-backend';
 /** Options for {@link DynamoDBStore}. */
 export type DynamoDBStoreOptions = BaseAdapterOptions & CodecOptions & {
@@ -14,6 +15,15 @@ export type DynamoDBStoreOptions = BaseAdapterOptions & CodecOptions & {
     maxSearchCandidates?: number;
     /** Cap on items scanned into memory during a plain (non-semantic) search before ResultTruncatedError. Defaults to MAX_TOTAL_ITEMS_IN_MEMORY. */
     maxScanItems?: number;
+    /**
+     * Direction of the score a `vectorBackend` returns. `'relevance'` (the
+     * default) forwards it unchanged; `'distance'` negates and re-sorts, so a
+     * distance-native backend (S3 Vectors, FAISS L2, pgvector `<->`) satisfies
+     * the higher-is-better contract without the caller wrapping it. Any other
+     * value is rejected at construction with a `ValidationError` rather than
+     * silently ranking one direction as the other.
+     */
+    vectorScoreDirection?: VectorScoreDirection;
 };
 /** The DynamoDB item backing a single stored value. */
 export interface StoreItemRecord {
@@ -26,5 +36,11 @@ export interface StoreItemRecord {
     updatedAt: string;
     embedding?: number[];
     ttl?: number;
+    /**
+     * Revision token, rewritten on every put. Pins the compare-and-swap that
+     * keeps two concurrent overwrites from both deleting the same superseded S3
+     * object. Optional: rows written before 0.9.0 carry none.
+     */
+    rev?: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/store/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/store/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAEvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,yCAAyC;AACzC,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GACnD,YAAY,GAAG;IACb,0EAA0E;IAC1E,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,sEAAsE;IACtE,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,mFAAmF;IACnF,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gJAAgJ;IAChJ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEJ,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/store/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAEvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,yCAAyC;AACzC,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GACnD,YAAY,GAAG;IACb,0EAA0E;IAC1E,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,sEAAsE;IACtE,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,mFAAmF;IACnF,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gJAAgJ;IAChJ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C,CAAC;AAEJ,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd"}

package/dist/store/vector-backend.d.ts

@@ -7,12 +7,12 @@ export interface VectorMatch {
      * upstream `SearchItem.score`, which this value is forwarded to verbatim.
      *
      * A backend whose native output is a *distance* (S3 Vectors, FAISS L2,
-     * pgvector's `<->`) must convert before returning: a distance ranks the
-     * other way, so forwarding one unconverted yields results that are ordered
-     * correctly but scored backwards, which silently breaks any caller that
-     * thresholds or displays the number. This package cannot tell the two apart
-     * and never reorders what a backend returns; it only warns when the scores
-     * it sees are not non-increasing.
+     * pgvector's `<->`) has two options: convert before returning, or declare
+     * `vectorScoreDirection: 'distance'` on the store, which negates and
+     * re-sorts for you. Forwarding an unconverted distance without declaring it
+     * yields results ordered correctly but scored backwards, which silently
+     * breaks any caller that thresholds or displays the number; that case is
+     * warned about but never reordered.
      */
     score: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farukada/aws-langgraph-dynamodb-ts",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "license": "MIT",
   "description": "AWS DynamoDB implementation for LangGraph Memory Store and Checkpoint Saver in TypeScript",
   "keywords": [