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

package/dist/store/actions/get.d.ts

@@ -1,5 +1,13 @@
 import type { Item } from '@langchain/langgraph-checkpoint';
 import type { StoreContext } from '../internal/setup';
-/** Retrieve a single item by namespace and key (strongly consistent), or null. */
-export declare function getItem(context: StoreContext, namespace: string[], key: string): Promise<Item | null>;
-//# sourceMappingURL=get.d.ts.map
+/**
+ * Retrieve a single item by namespace and key (strongly consistent), or null.
+ *
+ * An offloaded item can lose a race with a concurrent overwrite: between the
+ * row read and the S3 download the writer commits a new descriptor and deletes
+ * the object this read was about to fetch. That surfaces as `NoSuchKey`, and
+ * one strongly-consistent re-read settles it — the row now points at the new
+ * object (return that), is gone (null), or still points at the same missing
+ * object (a genuine loss, rethrown). Any other download failure propagates.
+ */
+export declare function getItem(context: StoreContext, namespace: string[], key: string, signal?: AbortSignal): Promise<Item | null>;

package/dist/store/actions/get.js

@@ -1,35 +1,73 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getItem = getItem;
+const clock_1 = require("../../shared/clock");
+const codec_1 = require("../../shared/codec/codec");
+const payload_loss_1 = require("../../shared/codec/payload-loss");
+const expiry_1 = require("../../shared/dynamodb/expiry");
 const retry_1 = require("../../shared/dynamodb/retry");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
 const item_mapper_1 = require("../internal/item-mapper");
 const keys_1 = require("../internal/keys");
 const validation_1 = require("../internal/validation");
-/** Retrieve a single item by namespace and key (strongly consistent), or null. */
-async function getItem(context, namespace, key) {
-    (0, validation_1.validateNamespace)(namespace);
-    (0, validation_1.validateKey)(key);
+/**
+ * Read the row strongly consistently and narrow it rather than cast. A
+ * foreign row sharing this key has no `namespace`, and one carrying a `value`
+ * PayloadDescriptor in the same shape a store item uses (a checkpointer WRITE
+ * row) would otherwise decode cleanly and be handed back as the caller's own
+ * value.
+ */
+async function readRow(context, namespace, key, signal) {
     const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
         TableName: context.tableName,
         Key: { PK: (0, keys_1.partitionKey)(namespace), SK: (0, keys_1.sortKey)(namespace, key) },
         ConsistentRead: true,
-    }));
+    }), (0, retry_policy_1.retryFor)(context, signal));
     if (!result.Item)
-        return null;
-    /**
-     * Narrow rather than cast. A foreign row sharing this key has no
-     * `namespace`, and one carrying a `value` PayloadDescriptor in the same
-     * shape a store item uses (a checkpointer WRITE row) would otherwise decode
-     * cleanly and be handed back as the caller's own value.
-     */
+        return undefined;
     const record = (0, item_mapper_1.narrowStoreRecord)(result.Item);
     if (!record) {
         context.logger.warn('store.get: ignored a row that is not a store item', {
             partitionKey: (0, keys_1.partitionKey)(namespace),
             sortKey: (0, keys_1.sortKey)(namespace, key),
         });
+        return undefined;
+    }
+    /** A row past its ttl is absent to every reader, however long DynamoDB's sweep lags. */
+    return (0, expiry_1.isExpiredRow)(record, (0, clock_1.nowSeconds)()) ? undefined : record;
+}
+/** True when both records point at the same offloaded object. */
+function sameObject(a, b) {
+    return (a.value.location === codec_1.PayloadLocation.S3 &&
+        b.value.location === codec_1.PayloadLocation.S3 &&
+        a.value.s3Key === b.value.s3Key);
+}
+/**
+ * Retrieve a single item by namespace and key (strongly consistent), or null.
+ *
+ * An offloaded item can lose a race with a concurrent overwrite: between the
+ * row read and the S3 download the writer commits a new descriptor and deletes
+ * the object this read was about to fetch. That surfaces as `NoSuchKey`, and
+ * one strongly-consistent re-read settles it — the row now points at the new
+ * object (return that), is gone (null), or still points at the same missing
+ * object (a genuine loss, rethrown). Any other download failure propagates.
+ */
+async function getItem(context, namespace, key, signal) {
+    (0, validation_1.validateStoreKey)(namespace, key);
+    const record = await readRow(context, namespace, key, signal);
+    if (!record)
         return null;
+    try {
+        return await (0, item_mapper_1.readStoreItem)(context, record);
+    }
+    catch (error) {
+        if (!(0, payload_loss_1.isMissingObjectError)(error))
+            throw error;
+        const fresh = await readRow(context, namespace, key, signal);
+        if (!fresh)
+            return null;
+        if (sameObject(record, fresh))
+            throw error;
+        return (0, item_mapper_1.readStoreItem)(context, fresh);
     }
-    return (0, item_mapper_1.readStoreItem)(context, record);
 }
-//# sourceMappingURL=get.js.map

package/dist/store/actions/list-namespaces.d.ts

@@ -6,4 +6,3 @@ import type { StoreContext } from '../internal/setup';
  * the read to a native Query; otherwise it falls back to a filtered Scan.
  */
 export declare function listNamespaces(context: StoreContext, op: ListNamespacesOperation): Promise<string[][]>;
-//# sourceMappingURL=list-namespaces.d.ts.map

package/dist/store/actions/list-namespaces.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listNamespaces = listNamespaces;
+const clock_1 = require("../../shared/clock");
+const expiry_1 = require("../../shared/dynamodb/expiry");
 const paginate_1 = require("../../shared/dynamodb/paginate");
 const scan_1 = require("../../shared/dynamodb/scan");
 const item_mapper_1 = require("../internal/item-mapper");
@@ -8,18 +10,20 @@ const keys_1 = require("../internal/keys");
 const namespace_match_1 = require("../internal/namespace-match");
 const query_1 = require("../internal/query");
 const validation_1 = require("../internal/validation");
-function namespaceSource(context, op) {
+function namespaceSource(context, op, now) {
     const root = (0, namespace_match_1.prefixRoot)(op.matchConditions);
     if (root.length > 0) {
         return (0, paginate_1.paginateQuery)({
+            retry: context.retry,
             client: context.client,
-            params: (0, query_1.scopedQuery)(context.tableName, root),
+            params: (0, expiry_1.withoutExpired)((0, query_1.projectKeys)((0, query_1.scopedQuery)(context.tableName, root)), now),
             maxItems: context.maxScanItems,
         });
     }
     return (0, scan_1.paginateScan)({
+        retry: context.retry,
         client: context.client,
-        params: (0, query_1.storeScan)(context.tableName),
+        params: (0, expiry_1.withoutExpired)((0, query_1.projectKeys)((0, query_1.storeScan)(context.tableName)), now),
         maxItems: context.maxScanItems,
     });
 }
@@ -31,11 +35,12 @@ function namespaceSource(context, op) {
 async function listNamespaces(context, op) {
     (0, validation_1.validatePaging)(op.offset, op.limit);
     (0, validation_1.validateMaxDepth)(op.maxDepth);
+    const now = (0, clock_1.nowSeconds)();
     const seen = new Set();
     const namespaces = [];
-    for await (const raw of namespaceSource(context, op)) {
+    for await (const raw of namespaceSource(context, op, now)) {
         const record = (0, item_mapper_1.narrowStoreRecord)(raw);
-        if (!record)
+        if (!record || (0, expiry_1.isExpiredRow)(record, now))
             continue;
         const namespace = record.namespace;
         if (op.matchConditions &&
@@ -52,4 +57,3 @@ async function listNamespaces(context, op) {
     namespaces.sort((a, b) => a.join(keys_1.NAMESPACE_SEPARATOR).localeCompare(b.join(keys_1.NAMESPACE_SEPARATOR)));
     return namespaces.slice(op.offset, op.offset + op.limit);
 }
-//# sourceMappingURL=list-namespaces.js.map

package/dist/store/actions/put.d.ts

@@ -8,4 +8,3 @@ import type { StoreContext } from '../internal/setup';
  * stored on the item — DynamoDB always holds the canonical item.
  */
 export declare function putItem(context: StoreContext, op: PutOperation): Promise<void>;
-//# sourceMappingURL=put.d.ts.map

package/dist/store/actions/put.js

@@ -11,45 +11,46 @@ const index_sync_1 = require("../internal/index-sync");
 const item_mapper_1 = require("../internal/item-mapper");
 const keys_1 = require("../internal/keys");
 const persist_1 = require("../internal/persist");
+const read_existing_1 = require("../internal/read-existing");
 const semantic_search_1 = require("../internal/semantic-search");
 const validation_1 = require("../internal/validation");
 const write_verify_1 = require("../internal/write-verify");
-async function readExisting(context, pk, sk) {
-    const existing = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
-        TableName: context.tableName,
-        Key: { PK: pk, SK: sk },
-        ConsistentRead: true,
-        ProjectionExpression: '#c, #v',
-        ExpressionAttributeNames: { '#c': 'createdAt', '#v': 'value' },
-    }));
-    return {
-        createdAt: existing.Item?.createdAt,
-        value: existing.Item?.value,
-    };
-}
 /**
  * Delete the item and, when a vector backend is configured, drop its vector.
  *
+ * The delete asks DynamoDB for the row it removed (`ReturnValues: 'ALL_OLD'`),
+ * so S3 cleanup targets the descriptor that was actually removed rather than
+ * one read a moment earlier — a concurrent put between a pre-read and the
+ * delete used to leave its just-written object orphaned — and the delete costs
+ * one request instead of two.
+ *
  * A retry-exhausted failure is *ambiguous*: the delete may have landed
- * server-side with only its acknowledgement lost. Mirroring `persistRecord`'s
- * treatment of an ambiguous put, that case is resolved with a
- * strongly-consistent read — if the row is genuinely gone the delete
- * succeeded, so the S3-orphan cleanup and the vector-backend delete must still
- * run rather than being skipped for a write that actually happened. Any other
- * failure, or a row still present, propagates unchanged.
+ * server-side with only its acknowledgement lost. Mirroring `persistRecord`,
+ * that case is resolved with a strongly-consistent read — if the row is gone
+ * the delete succeeded and the vector-backend delete must still run. The
+ * removed descriptor travelled with the lost response, so that one object, if
+ * any, is left to the lifecycle rule. Any other failure, or a row still
+ * present, propagates unchanged.
  */
 async function deleteStoreItem(context, op, pk, sk) {
-    const existing = context.offloader ? await readExisting(context, pk, sk) : undefined;
+    let removed;
     try {
-        await (0, retry_1.withDynamoDBRetry)(() => context.client.delete({ TableName: context.tableName, Key: { PK: pk, SK: sk } }));
+        const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.delete({
+            TableName: context.tableName,
+            Key: { PK: pk, SK: sk },
+            ReturnValues: 'ALL_OLD',
+        }), context.retry);
+        removed = result.Attributes?.value;
     }
     catch (error) {
         const landed = (0, write_verify_1.isRetryExhausted)(error) && (await (0, write_verify_1.rowIsAbsent)(context, { PK: pk, SK: sk }));
         if (!landed)
             throw error;
     }
-    if (context.offloader) {
-        await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(existing?.value ? [existing.value] : []), 'store.delete', context.logger);
+    if (context.offloader && removed) {
+        await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([removed]), 'store.delete', context.logger, {
+            scope: [...op.namespace, op.key],
+        });
     }
     if (context.vectorBackend) {
         await (0, index_sync_1.syncVectorIndex)(context.vectorBackend, op.namespace, op.key, undefined, context.logger);
@@ -69,8 +70,7 @@ async function resolveEmbedding(context, op, value) {
  * stored on the item — DynamoDB always holds the canonical item.
  */
 async function putItem(context, op) {
-    (0, validation_1.validateNamespace)(op.namespace);
-    (0, validation_1.validateKey)(op.key);
+    (0, validation_1.validateStoreKey)(op.namespace, op.key);
     const pk = (0, keys_1.partitionKey)(op.namespace);
     const sk = (0, keys_1.sortKey)(op.namespace, op.key);
     if (op.value === null) {
@@ -79,7 +79,7 @@ async function putItem(context, op) {
     }
     const value = op.value;
     const timestamp = (0, clock_1.nowIso)();
-    const existing = await readExisting(context, pk, sk);
+    const existing = await (0, read_existing_1.readExisting)(context, pk, sk);
     const embedding = await resolveEmbedding(context, op, value);
     const ttlTimestamp = context.ttl ? (0, ttl_1.calculateTtlTimestamp)(context.ttl) : undefined;
     const record = await (0, item_mapper_1.buildStoreItem)(context, op.namespace, op.key, value, {
@@ -89,9 +89,8 @@ async function putItem(context, op) {
         ttlTimestamp,
         nonce: (0, node_crypto_1.randomUUID)(),
     });
-    await (0, persist_1.persistRecord)(context, record, existing.value);
+    await (0, persist_1.persistRecord)(context, record, existing);
     if (context.vectorBackend) {
         await (0, index_sync_1.syncVectorIndex)(context.vectorBackend, op.namespace, op.key, embedding, context.logger);
     }
 }
-//# sourceMappingURL=put.js.map

package/dist/store/actions/reconcile-vector-index.d.ts

@@ -13,5 +13,6 @@ export interface VectorReconcileResult {
  * overrides are not reproduced. Requires a configured `index` and
  * `vectorBackend`; the prefix must be a non-empty namespace.
  */
-export declare function reconcileVectorIndex(context: StoreContext, namespacePrefix: string[]): Promise<VectorReconcileResult>;
-//# sourceMappingURL=reconcile-vector-index.d.ts.map
+export declare function reconcileVectorIndex(context: StoreContext, namespacePrefix: string[], options?: {
+    signal?: AbortSignal;
+}): Promise<VectorReconcileResult>;

package/dist/store/actions/reconcile-vector-index.js

@@ -13,15 +13,14 @@ const validation_1 = require("../internal/validation");
  * overrides are not reproduced. Requires a configured `index` and
  * `vectorBackend`; the prefix must be a non-empty namespace.
  */
-async function reconcileVectorIndex(context, namespacePrefix) {
+async function reconcileVectorIndex(context, namespacePrefix, options = {}) {
     (0, validation_1.validateNamespace)(namespacePrefix);
     if (!context.index || !context.vectorBackend) {
         throw new errors_1.ValidationError('reconcileVectorIndex requires a configured index and vectorBackend');
     }
     const backend = context.vectorBackend;
-    const targets = await (0, index_reconcile_1.collectReconcileTargets)(context, namespacePrefix);
+    const targets = await (0, index_reconcile_1.collectReconcileTargets)(context, namespacePrefix, options.signal);
     const upserted = await (0, index_reconcile_1.pushEmbeddings)(backend, targets);
     const pruned = await (0, index_reconcile_1.pruneOrphans)(context, backend, namespacePrefix, targets);
     return { upserted, pruned };
 }
-//# sourceMappingURL=reconcile-vector-index.js.map

package/dist/store/actions/search.d.ts

@@ -6,5 +6,4 @@ import type { StoreContext } from '../internal/setup';
  * falls back to a (filtered) Scan. Semantic ranking uses the configured
  * VectorBackend when present, else an in-memory cosine ranking (capped).
  */
-export declare function searchItems(context: StoreContext, op: SearchOperation): Promise<SearchItem[]>;
-//# sourceMappingURL=search.d.ts.map
+export declare function searchItems(context: StoreContext, op: SearchOperation, signal?: AbortSignal): Promise<SearchItem[]>;

package/dist/store/actions/search.js

@@ -1,61 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.searchItems = searchItems;
-const paginate_1 = require("../../shared/dynamodb/paginate");
-const scan_1 = require("../../shared/dynamodb/scan");
 const backend_search_1 = require("../internal/backend-search");
-const item_mapper_1 = require("../internal/item-mapper");
-const keys_1 = require("../internal/keys");
-const query_1 = require("../internal/query");
+const candidates_1 = require("../internal/candidates");
 const ranker_1 = require("../internal/ranker");
-const search_filter_1 = require("../internal/search-filter");
+const semantic_search_1 = require("../internal/semantic-search");
 const validation_1 = require("../internal/validation");
 const DEFAULT_LIMIT = 10;
-async function collectCandidates(context, op) {
-    const source = op.namespacePrefix.length > 0
-        ? (0, paginate_1.paginateQuery)({
-            client: context.client,
-            params: (0, query_1.scopedQuery)(context.tableName, op.namespacePrefix),
-            maxItems: context.maxScanItems,
-        })
-        : (0, scan_1.paginateScan)({
-            client: context.client,
-            params: (0, query_1.storeScan)(context.tableName),
-            maxItems: context.maxScanItems,
-        });
-    const candidates = [];
-    for await (const raw of source) {
-        const record = (0, item_mapper_1.narrowStoreRecord)(raw);
-        if (!record)
-            continue;
-        if (!(0, keys_1.namespaceMatchesPrefix)(record.namespace, op.namespacePrefix))
-            continue;
-        const item = await (0, item_mapper_1.readStoreItem)(context, record);
-        if (!(0, search_filter_1.passesFilter)(item, op))
-            continue;
-        candidates.push({ item, embedding: record.embedding });
-    }
-    return candidates;
-}
 /**
  * Search items under a namespace prefix: metadata filtering plus optional
  * semantic ranking. A non-empty prefix uses a native Query; an empty prefix
  * falls back to a (filtered) Scan. Semantic ranking uses the configured
  * VectorBackend when present, else an in-memory cosine ranking (capped).
  */
-async function searchItems(context, op) {
+async function searchItems(context, op, signal) {
     const offset = op.offset ?? 0;
     const limit = op.limit ?? DEFAULT_LIMIT;
     (0, validation_1.validatePaging)(offset, limit);
     if (op.query && context.index && context.vectorBackend) {
-        const ranked = await (0, backend_search_1.searchViaBackend)(context, context.vectorBackend, context.index, op, offset, limit);
+        const ranked = await (0, backend_search_1.searchViaBackend)(context, context.vectorBackend, context.index, op, offset, limit, signal);
         return ranked.slice(offset, offset + limit);
     }
-    const candidates = await collectCandidates(context, op);
     if (!op.query || !context.index) {
-        return candidates.map(({ item }) => ({ ...item })).slice(offset, offset + limit);
+        const page = await (0, candidates_1.collectCandidates)(context, op, { kind: 'page', need: offset + limit }, signal);
+        return page.map(({ item }) => ({ ...item })).slice(offset, offset + limit);
     }
+    const candidates = await (0, candidates_1.collectCandidates)(context, op, { kind: 'semantic', cap: context.maxSearchCandidates }, signal);
     const queryVector = await context.index.embeddings.embedQuery(op.query);
-    return (0, ranker_1.rankInMemory)(candidates, queryVector, context.maxSearchCandidates).slice(offset, offset + limit);
+    (0, semantic_search_1.assertVectorDims)(context.index, queryVector, 'query');
+    const ranked = (0, ranker_1.rankInMemory)(candidates, queryVector, context.maxSearchCandidates, (count) => context.logger.warn('search: some candidates carry an embedding of a different dimension than the query and ' +
+        'were ranked unscored; re-embed them with reconcileVectorIndex or a re-put', { namespacePrefix: op.namespacePrefix, count }));
+    return ranked.slice(offset, offset + limit);
 }
-//# sourceMappingURL=search.js.map

package/dist/store/internal/backend-search.d.ts

@@ -1,5 +1,4 @@
 import type { IndexConfig, SearchItem, SearchOperation } from '@langchain/langgraph-checkpoint';
 import type { VectorBackend } from '../vector-backend';
 import type { StoreContext } from './setup';
-export declare function searchViaBackend(context: StoreContext, backend: VectorBackend, index: IndexConfig, op: SearchOperation, offset: number, limit: number): Promise<SearchItem[]>;
-//# sourceMappingURL=backend-search.d.ts.map
+export declare function searchViaBackend(context: StoreContext, backend: VectorBackend, index: IndexConfig, op: SearchOperation, offset: number, limit: number, signal?: AbortSignal): Promise<SearchItem[]>;

package/dist/store/internal/backend-search.js

@@ -4,7 +4,9 @@ exports.searchViaBackend = searchViaBackend;
 const errors_1 = require("../../shared/errors/errors");
 const get_1 = require("../actions/get");
 const keys_1 = require("./keys");
+const score_direction_1 = require("./score-direction");
 const search_filter_1 = require("./search-filter");
+const semantic_search_1 = require("./semantic-search");
 /**
  * Warn when a backend's own ordering disagrees with its scores. A backend
  * returning a raw distance still hands back nearest-first, so the order looks
@@ -25,9 +27,9 @@ function warnOnNonDescendingScores(context, matches, namespacePrefix) {
  * element containing the reserved separator would otherwise turn the whole
  * search into a ValidationError instead of dropping the one bad match.
  */
-async function fetchMatch(context, match) {
+async function fetchMatch(context, match, signal) {
     try {
-        return await (0, get_1.getItem)(context, match.namespace, match.key);
+        return await (0, get_1.getItem)(context, match.namespace, match.key, signal);
     }
     catch (error) {
         context.logger.warn('search: skipped an unusable vectorBackend match', {
@@ -38,8 +40,9 @@ async function fetchMatch(context, match) {
         return null;
     }
 }
-async function searchViaBackend(context, backend, index, op, offset, limit) {
+async function searchViaBackend(context, backend, index, op, offset, limit, signal) {
     const queryVector = await index.embeddings.embedQuery(op.query);
+    (0, semantic_search_1.assertVectorDims)(index, queryVector, 'query');
     const need = offset + limit;
     if (need > context.maxSearchCandidates) {
         throw new errors_1.ValidationError(`Requested page (offset ${offset} + limit ${limit} = ${need}) exceeds maxSearchCandidates ` +
@@ -48,20 +51,24 @@ async function searchViaBackend(context, backend, index, op, offset, limit) {
     let topK = Math.min(need, context.maxSearchCandidates);
     let results;
     for (;;) {
-        const matches = await backend.query(op.namespacePrefix, queryVector, topK);
+        const matches = (0, score_direction_1.toRelevanceScores)(await backend.query(op.namespacePrefix, queryVector, topK), context.vectorScoreDirection);
         warnOnNonDescendingScores(context, matches, op.namespacePrefix);
         results = [];
         for (const match of matches) {
             if (!(0, keys_1.namespaceMatchesPrefix)(match.namespace, op.namespacePrefix))
                 continue;
-            const item = await fetchMatch(context, match);
+            const item = await fetchMatch(context, match, signal);
             if (item && (0, search_filter_1.passesFilter)(item, op))
                 results.push({ ...item, score: match.score });
         }
-        if (results.length >= need || matches.length < topK || topK >= context.maxSearchCandidates)
+        if (results.length >= need || matches.length < topK)
             break;
+        if (topK >= context.maxSearchCandidates) {
+            /** The backend still holds matches, but the filter left the page short at the cap: the same answer the in-DB ranker gives, not a silently short page. */
+            throw new errors_1.ValidationError(`Semantic search collected ${results.length} of ${need} matches within maxSearchCandidates ` +
+                `(${context.maxSearchCandidates}); narrow the filter or raise maxSearchCandidates`, 'maxSearchCandidates');
+        }
         topK = Math.min(topK * 2, context.maxSearchCandidates);
     }
     return results;
 }
-//# sourceMappingURL=backend-search.js.map

package/dist/store/internal/batch-plan.d.ts

@@ -0,0 +1,11 @@
+import type { Operation } from '@langchain/langgraph-checkpoint';
+/**
+ * Run a batch: every write group serially within itself and groups
+ * concurrently with each other, then every read concurrently, at most
+ * {@link DEFAULT_READ_CONCURRENCY} operations in flight at a time. Results
+ * come back in operation order. Writes complete before any read starts, so a
+ * get or search in the same batch observes the puts beside it. Any failure
+ * rejects the whole batch: no further operation is started, the ones already
+ * in flight settle, and the first error propagates.
+ */
+export declare function runBatch<R>(operations: readonly Operation[], dispatch: (operation: Operation) => Promise<R>): Promise<R[]>;

package/dist/store/internal/batch-plan.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBatch = runBatch;
+const concurrency_1 = require("../../shared/concurrency");
+const constants_1 = require("../../shared/constants");
+function itemOf(op) {
+    return JSON.stringify([op.namespace, op.key]);
+}
+/**
+ * Group a batch so that dependent operations stay ordered while independent
+ * ones can run side by side. Two writes to the same item must land in the
+ * order given, since the later one wins; writes to different items and all
+ * reads are independent of each other.
+ */
+function planBatch(operations) {
+    const groups = new Map();
+    const reads = [];
+    operations.forEach((op, index) => {
+        if (!('value' in op)) {
+            reads.push(index);
+            return;
+        }
+        const item = itemOf(op);
+        const group = groups.get(item);
+        if (group)
+            group.push(index);
+        else
+            groups.set(item, [index]);
+    });
+    return { writeGroups: [...groups.values()], reads };
+}
+/**
+ * Run a batch: every write group serially within itself and groups
+ * concurrently with each other, then every read concurrently, at most
+ * {@link DEFAULT_READ_CONCURRENCY} operations in flight at a time. Results
+ * come back in operation order. Writes complete before any read starts, so a
+ * get or search in the same batch observes the puts beside it. Any failure
+ * rejects the whole batch: no further operation is started, the ones already
+ * in flight settle, and the first error propagates.
+ */
+async function runBatch(operations, dispatch) {
+    const plan = planBatch(operations);
+    const results = [];
+    await (0, concurrency_1.mapWithConcurrency)(plan.writeGroups, constants_1.DEFAULT_READ_CONCURRENCY, async (group) => {
+        for (const index of group)
+            results[index] = await dispatch(operations[index]);
+    });
+    await (0, concurrency_1.mapWithConcurrency)(plan.reads, constants_1.DEFAULT_READ_CONCURRENCY, async (index) => {
+        results[index] = await dispatch(operations[index]);
+    });
+    return results;
+}

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

@@ -0,0 +1,23 @@
+import type { SearchOperation } from '@langchain/langgraph-checkpoint';
+import type { RankCandidate } from './ranker';
+import type { StoreContext } from './setup';
+/**
+ * How far a collection must go. A plain page is complete once `need`
+ * (`offset + limit`) matching items are in hand, so rows past it are never
+ * read or decoded; a semantic ranking needs every candidate but is refused as
+ * soon as more than `cap` rows exist, before a single decode or embedding.
+ */
+export type CollectBound = {
+    kind: 'page';
+    need: number;
+} | {
+    kind: 'semantic';
+    cap: number;
+};
+/**
+ * Collect the live rows under the prefix and decode them within `bound`. A
+ * page decodes rows in batches of {@link DEFAULT_READ_CONCURRENCY} and closes
+ * the paginator as soon as the page is full, so a namespace far larger than the
+ * page costs neither a full decode nor a truncation error.
+ */
+export declare function collectCandidates(context: StoreContext, op: SearchOperation, bound: CollectBound, signal?: AbortSignal): Promise<RankCandidate[]>;

package/dist/store/internal/candidates.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectCandidates = collectCandidates;
+const clock_1 = require("../../shared/clock");
+const concurrency_1 = require("../../shared/concurrency");
+const constants_1 = require("../../shared/constants");
+const expiry_1 = require("../../shared/dynamodb/expiry");
+const paginate_1 = require("../../shared/dynamodb/paginate");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
+const scan_1 = require("../../shared/dynamodb/scan");
+const errors_1 = require("../../shared/errors/errors");
+const item_mapper_1 = require("./item-mapper");
+const keys_1 = require("./keys");
+const query_1 = require("./query");
+const search_filter_1 = require("./search-filter");
+function candidateSource(context, op, signal, now) {
+    return op.namespacePrefix.length > 0
+        ? (0, paginate_1.paginateQuery)({
+            retry: (0, retry_policy_1.retryFor)(context, signal),
+            signal,
+            client: context.client,
+            params: (0, expiry_1.withoutExpired)((0, query_1.scopedQuery)(context.tableName, op.namespacePrefix), now),
+            maxItems: context.maxScanItems,
+        })
+        : (0, scan_1.paginateScan)({
+            retry: (0, retry_policy_1.retryFor)(context, signal),
+            signal,
+            client: context.client,
+            params: (0, expiry_1.withoutExpired)((0, query_1.storeScan)(context.tableName), now),
+            maxItems: context.maxScanItems,
+        });
+}
+/** The store record a raw row denotes, or undefined for a foreign, expired or out-of-prefix row. */
+function liveRecord(raw, op, now) {
+    const record = (0, item_mapper_1.narrowStoreRecord)(raw);
+    if (!record || (0, expiry_1.isExpiredRow)(record, now))
+        return undefined;
+    return (0, keys_1.namespaceMatchesPrefix)(record.namespace, op.namespacePrefix) ? record : undefined;
+}
+/** Decode the pending rows concurrently (each offloaded row is one S3 GET) and keep the ones passing the filter. */
+async function flush(context, op, state) {
+    if (state.pending.length === 0)
+        return;
+    const batch = state.pending;
+    state.pending = [];
+    const items = await (0, concurrency_1.mapWithConcurrency)(batch, constants_1.DEFAULT_READ_CONCURRENCY, (record) => (0, item_mapper_1.readStoreItem)(context, record));
+    batch.forEach((record, index) => {
+        if ((0, search_filter_1.passesFilter)(items[index], op)) {
+            state.collected.push({ item: items[index], embedding: record.embedding });
+        }
+    });
+}
+/**
+ * Rows to gather before the next decode. With a filter every batch is a full
+ * one, since any row may be dropped; without one every decoded row is a match,
+ * so the batch never exceeds what the page still needs.
+ */
+function batchSize(op, need, collected) {
+    return op.filter === undefined
+        ? Math.min(constants_1.DEFAULT_READ_CONCURRENCY, need - collected)
+        : constants_1.DEFAULT_READ_CONCURRENCY;
+}
+function tooManyCandidates(count, cap) {
+    return new errors_1.ValidationError(`Semantic search candidate set (${count}) exceeds maxSearchCandidates (${cap}); ` +
+        'use a dedicated VectorBackend for large corpora', 'maxSearchCandidates');
+}
+/**
+ * Collect the live rows under the prefix and decode them within `bound`. A
+ * page decodes rows in batches of {@link DEFAULT_READ_CONCURRENCY} and closes
+ * the paginator as soon as the page is full, so a namespace far larger than the
+ * page costs neither a full decode nor a truncation error.
+ */
+async function collectCandidates(context, op, bound, signal) {
+    const now = (0, clock_1.nowSeconds)();
+    const state = { pending: [], collected: [] };
+    for await (const raw of candidateSource(context, op, signal, now)) {
+        const record = liveRecord(raw, op, now);
+        if (!record)
+            continue;
+        state.pending.push(record);
+        if (bound.kind === 'semantic') {
+            if (state.pending.length > bound.cap)
+                throw tooManyCandidates(state.pending.length, bound.cap);
+            continue;
+        }
+        if (state.pending.length < batchSize(op, bound.need, state.collected.length))
+            continue;
+        await flush(context, op, state);
+        if (state.collected.length >= bound.need)
+            return state.collected;
+    }
+    await flush(context, op, state);
+    return state.collected;
+}

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

@@ -7,4 +7,3 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | {
  * is exact-match ($eq); an operator object ({ $gt: 4 }) applies comparisons.
  */
 export declare function matchesStoreFilter(value: Record<string, JsonValue>, filter: Record<string, JsonValue>): boolean;
-//# sourceMappingURL=filter.d.ts.map