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

package/dist/store/actions/put.js

@@ -1,96 +1,78 @@
 "use strict";
+/**
+ * Hides the order a put happens in.
+ *
+ * A put reads the row it replaces for its `createdAt`, embeds once — a vector
+ * per extracted path onto the row, or one vector for the `vectorBackend`,
+ * never both — writes the row, and only then syncs the backend, best-effort.
+ * A `null` value takes the delete path instead. A caller hands over an item;
+ * that the table commits first and the vector copy follows is decided here.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.putItem = putItem;
 const node_crypto_1 = require("node:crypto");
 const clock_1 = require("../../shared/clock");
-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 ttl_1 = require("../../shared/validation/ttl");
-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 item_write_1 = require("../internal/item-write");
+const rows_1 = require("../internal/rows");
 const semantic_search_1 = require("../internal/semantic-search");
-const validation_1 = require("../internal/validation");
-const write_verify_1 = require("../internal/write-verify");
+const vector_index_1 = require("../internal/vector-index");
 /**
- * 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`,
- * 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.
+ * The vectors a put stores on the row: one per extracted path, scored by best
+ * match on read. Not computed when a `vectorBackend` holds the vectors, which
+ * takes a single vector per item instead (see {@link itemVector}).
  */
-async function deleteStoreItem(context, op, pk, sk) {
-    let removed;
-    try {
-        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 && 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);
-    }
-}
-/** Compute the embedding for a put, honoring `op.index` (false disables it). */
-async function resolveEmbedding(context, op, value) {
+async function resolvePassages(context, op, value) {
     if (op.index === false)
         return undefined;
-    return (0, semantic_search_1.embedValue)(context, value, Array.isArray(op.index) ? op.index : undefined);
+    return (0, semantic_search_1.embedPassages)(context, value, op.index);
 }
 /**
- * Store, update, or delete an item (null deletes). The value is encoded
- * (optional compression/S3 offload, nonced per call so a failed write can never
- * delete the previous payload) and `createdAt` is preserved across updates; a
- * computed embedding is sent to a configured `vectorBackend` instead of being
- * stored on the item — DynamoDB always holds the canonical item.
+ * Store, update or delete an item.
+ *
+ * Accepts: `op` — parsed; a `ParsedDelete` removes the item, a `ParsedPut` is
+ * stored, its value encoded with optional compression and S3 offload under
+ * this row's own path, in an object named by this put's own id. `op.index` —
+ * `false` stores the item without indexing it and clears any vector it had, an
+ * array overrides the configured fields for this put, and absent uses the
+ * store's configuration.
+ *
+ * Returns: nothing. Deleting an item that is not there is not an error.
+ *
+ * Throws: `VALIDATION` naming `value` for a value that JSON cannot represent —
+ * refused at the write rather than stored as a row that can never be read back;
+ * `S3_OFFLOAD_FAILED`; whatever the write throws.
+ *
+ * Guarantees: DynamoDB holds the canonical item — the vector index is synced
+ * afterwards and best-effort, so a backend outage never fails a put or leaves a
+ * half-written item. `createdAt` survives every update. The superseded payload
+ * is deleted only once the new row is committed, and this put's own upload
+ * only once a read proves its write did not land. Neither release reads the
+ * row first: each put uploads under a key ending in an id of its own, so the
+ * object a put uploads is named only by that put's own rows.
  */
 async function putItem(context, op) {
-    (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) {
-        await deleteStoreItem(context, op, pk, sk);
+    if (op.kind === 'delete') {
+        await (0, item_write_1.deleteStoreItem)(context, op.address);
         return;
     }
+    const { namespace, key } = op.address;
     const value = op.value;
     const timestamp = (0, clock_1.nowIso)();
-    const existing = await (0, read_existing_1.readExisting)(context, pk, sk);
-    const embedding = await resolveEmbedding(context, op, value);
+    const existing = await (0, rows_1.readExisting)(context, (0, rows_1.itemRowKey)(op.address));
+    // The two indexing modes are exclusive, so only one of them embeds: the row
+    // carries a vector per extracted path, while a configured backend takes one
+    // vector per item because that is what its `upsert` contract addresses.
+    const embedding = await (0, vector_index_1.itemVector)(context, op);
+    const embeddings = context.vectorBackend ? undefined : await resolvePassages(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, {
+    const record = await (0, rows_1.buildStoreRow)(context, { namespace, key }, value, {
         createdAt: existing.createdAt ?? timestamp,
         updatedAt: timestamp,
-        embedding: context.vectorBackend ? undefined : embedding,
+        embeddings,
         ttlTimestamp,
-        nonce: (0, node_crypto_1.randomUUID)(),
+        rev: (0, node_crypto_1.randomUUID)(),
     });
-    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);
-    }
+    await (0, item_write_1.persistRow)(context, record, existing);
+    await (0, vector_index_1.syncItemVector)(context, op.address, embedding);
 }

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

@@ -1,17 +1,37 @@
+/**
+ * Hides what a reconcile refuses before it touches the backend.
+ *
+ * A repair is scoped to one partition's items, so its prefix must be a
+ * non-empty namespace, and without an `index` and a `vectorBackend` there is
+ * nothing to repair; both are refused here, before any read. How the backend
+ * is then made to agree with the table belongs to the vector index, so the
+ * store's method knows neither half.
+ */
 import type { StoreContext } from '../internal/setup';
-/** Counts returned by {@link reconcileVectorIndex}. */
-export interface VectorReconcileResult {
-    upserted: number;
-    pruned: number;
-}
+import type { VectorReconcileResult } from '../types';
 /**
  * Repair the vector backend against the canonical DynamoDB items under
  * `namespacePrefix`: re-push every live embedding, and — when the backend
  * implements {@link VectorBackend.listKeys} — prune vectors with no canonical
  * item. A maintenance tool for backend drift; run it when the namespace is
- * idle. Re-embeds with the store's configured fields, so per-put `index` field
- * overrides are not reproduced. Requires a configured `index` and
- * `vectorBackend`; the prefix must be a non-empty namespace.
+ * idle.
+ *
+ * Accepts: `namespacePrefix` — a non-empty namespace, since the repair is
+ * scoped to one partition's items. `options.signal` — aborts between pages.
+ *
+ * Returns: how many vectors were upserted and how many pruned.
+ *
+ * Throws: `VALIDATION` naming `namespacePrefix` or `namespacePrefix element`
+ * for an empty or malformed prefix, as `search` names it, and `vectorBackend`
+ * when the store has no index or backend to reconcile;
+ * `RESULT_TRUNCATED` past `maxScanItems`, since repairing from a
+ * partial view would prune live vectors; whatever the reads, the embeddings
+ * model and the backend throw.
+ *
+ * Guarantees: re-embeds with the store's configured fields, so a per-put
+ * `index` field override is not reproduced — a reconcile makes the backend
+ * agree with the store's configuration, not with each item's write-time one.
+ * DynamoDB is never written: only the backend is repaired.
  */
 export declare function reconcileVectorIndex(context: StoreContext, namespacePrefix: string[], options?: {
     signal?: AbortSignal;

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

@@ -1,26 +1,46 @@
 "use strict";
+/**
+ * Hides what a reconcile refuses before it touches the backend.
+ *
+ * A repair is scoped to one partition's items, so its prefix must be a
+ * non-empty namespace, and without an `index` and a `vectorBackend` there is
+ * nothing to repair; both are refused here, before any read. How the backend
+ * is then made to agree with the table belongs to the vector index, so the
+ * store's method knows neither half.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reconcileVectorIndex = reconcileVectorIndex;
 const errors_1 = require("../../shared/errors/errors");
-const index_reconcile_1 = require("../internal/index-reconcile");
-const validation_1 = require("../internal/validation");
+const parse_1 = require("../internal/parse");
+const vector_index_1 = require("../internal/vector-index");
 /**
  * Repair the vector backend against the canonical DynamoDB items under
  * `namespacePrefix`: re-push every live embedding, and — when the backend
  * implements {@link VectorBackend.listKeys} — prune vectors with no canonical
  * item. A maintenance tool for backend drift; run it when the namespace is
- * idle. Re-embeds with the store's configured fields, so per-put `index` field
- * overrides are not reproduced. Requires a configured `index` and
- * `vectorBackend`; the prefix must be a non-empty namespace.
+ * idle.
+ *
+ * Accepts: `namespacePrefix` — a non-empty namespace, since the repair is
+ * scoped to one partition's items. `options.signal` — aborts between pages.
+ *
+ * Returns: how many vectors were upserted and how many pruned.
+ *
+ * Throws: `VALIDATION` naming `namespacePrefix` or `namespacePrefix element`
+ * for an empty or malformed prefix, as `search` names it, and `vectorBackend`
+ * when the store has no index or backend to reconcile;
+ * `RESULT_TRUNCATED` past `maxScanItems`, since repairing from a
+ * partial view would prune live vectors; whatever the reads, the embeddings
+ * model and the backend throw.
+ *
+ * Guarantees: re-embeds with the store's configured fields, so a per-put
+ * `index` field override is not reproduced — a reconcile makes the backend
+ * agree with the store's configuration, not with each item's write-time one.
+ * DynamoDB is never written: only the backend is repaired.
  */
 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 prefix = (0, parse_1.parseNamespace)(namespacePrefix, 'namespacePrefix');
+    if (!(0, vector_index_1.hasVectorBackend)(context)) {
+        throw (0, errors_1.validationError)('reconcileVectorIndex requires a configured index and vectorBackend', 'vectorBackend');
     }
-    const backend = context.vectorBackend;
-    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 };
+    return (0, vector_index_1.reconcileVectors)(context, prefix, options.signal);
 }

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

@@ -1,9 +1,38 @@
-import type { SearchItem, SearchOperation } from '@langchain/langgraph-checkpoint';
+/**
+ * Hides which of three paths serves a search.
+ *
+ * A query with a `vectorBackend` is answered by the backend; no query, or no
+ * `index` to embed one with, is a page read from the table that stops once
+ * full; anything else is ranked in memory over at most `maxSearchCandidates`.
+ * A page of zero is answered before any of them. A caller gets the same shape
+ * of page whichever path ran, scored exactly when a query could be ranked.
+ */
+import type { SearchItem } from '@langchain/langgraph-checkpoint';
+import type { ParsedSearch } from '../internal/parse';
 import type { StoreContext } from '../internal/setup';
 /**
  * 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).
+ * semantic ranking.
+ *
+ * Accepts: `search` — already parsed, so `namespacePrefix`, `offset` and
+ * `limit` are resolved; `search.query` absent or empty
+ * (which is absent: there is no query to embed) ranks nothing and returns the
+ * page as read, which is what the reference store does
+ * (`@langchain/langgraph-checkpoint@1.1.5` `dist/store/memory.js:70-80`, where a
+ * falsy query takes the unscored path). A query without a configured `index`
+ * does the same, since there is nothing to embed it with.
+ *
+ * Returns: at most `limit` items from `offset`. With a query and an index every
+ * item carries a `score`; without one none does. Scores rank best-first; an item
+ * that cannot be scored ranks last rather than being dropped.
+ *
+ * Throws: `VALIDATION` naming `maxSearchCandidates` or `index.dims`; whatever
+ * the reads, decodes and the embeddings model throw.
+ *
+ * Guarantees: a page of zero costs no request at all, and otherwise only the
+ * page's own items are decoded on the unranked path — the
+ * read stops as soon as it is full. A semantic search must read every candidate
+ * to rank it, which is why it is capped and why a large corpus belongs in a
+ * `vectorBackend`.
  */
-export declare function searchItems(context: StoreContext, op: SearchOperation, signal?: AbortSignal): Promise<SearchItem[]>;
+export declare function searchItems(context: StoreContext, search: ParsedSearch, signal?: AbortSignal): Promise<SearchItem[]>;

package/dist/store/actions/search.js

@@ -1,34 +1,66 @@
 "use strict";
+/**
+ * Hides which of three paths serves a search.
+ *
+ * A query with a `vectorBackend` is answered by the backend; no query, or no
+ * `index` to embed one with, is a page read from the table that stops once
+ * full; anything else is ranked in memory over at most `maxSearchCandidates`.
+ * A page of zero is answered before any of them. A caller gets the same shape
+ * of page whichever path ran, scored exactly when a query could be ranked.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.searchItems = searchItems;
-const backend_search_1 = require("../internal/backend-search");
-const candidates_1 = require("../internal/candidates");
-const ranker_1 = require("../internal/ranker");
+const truncate_1 = require("../../shared/logging/truncate");
 const semantic_search_1 = require("../internal/semantic-search");
-const validation_1 = require("../internal/validation");
-const DEFAULT_LIMIT = 10;
+const table_search_1 = require("../internal/table-search");
+const vector_index_1 = require("../internal/vector-index");
 /**
  * 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).
+ * semantic ranking.
+ *
+ * Accepts: `search` — already parsed, so `namespacePrefix`, `offset` and
+ * `limit` are resolved; `search.query` absent or empty
+ * (which is absent: there is no query to embed) ranks nothing and returns the
+ * page as read, which is what the reference store does
+ * (`@langchain/langgraph-checkpoint@1.1.5` `dist/store/memory.js:70-80`, where a
+ * falsy query takes the unscored path). A query without a configured `index`
+ * does the same, since there is nothing to embed it with.
+ *
+ * Returns: at most `limit` items from `offset`. With a query and an index every
+ * item carries a `score`; without one none does. Scores rank best-first; an item
+ * that cannot be scored ranks last rather than being dropped.
+ *
+ * Throws: `VALIDATION` naming `maxSearchCandidates` or `index.dims`; whatever
+ * the reads, decodes and the embeddings model throw.
+ *
+ * Guarantees: a page of zero costs no request at all, and otherwise only the
+ * page's own items are decoded on the unranked path — the
+ * read stops as soon as it is full. A semantic search must read every candidate
+ * to rank it, which is why it is capped and why a large corpus belongs in a
+ * `vectorBackend`.
  */
-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, signal);
+async function searchItems(context, search, signal) {
+    const { offset, limit } = search;
+    // A zero page is answered here, ahead of all three paths below, because each
+    // of them pays for it: `collectCandidates` pulls the first row out of the
+    // paginator before it tests its `offset + limit` bound, so even a page that
+    // needs nothing costs one Query or Scan, and the two ranked paths embed the
+    // query as well. Slicing the result to nothing afterwards hid the cost
+    // rather than avoiding it.
+    if (limit === 0)
+        return [];
+    if (search.query && (0, vector_index_1.hasVectorBackend)(context)) {
+        const ranked = await (0, vector_index_1.searchViaBackend)(context, search, signal);
         return ranked.slice(offset, offset + limit);
     }
-    if (!op.query || !context.index) {
-        const page = await (0, candidates_1.collectCandidates)(context, op, { kind: 'page', need: offset + limit }, signal);
+    if (!search.query || !context.index) {
+        const page = await (0, table_search_1.collectCandidates)(context, search, { 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);
+    const candidates = await (0, table_search_1.collectCandidates)(context, search, { kind: 'semantic', cap: context.maxSearchCandidates }, signal);
+    const queryVector = await context.index.embeddings.embedQuery(search.query);
     (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 }));
+    const ranked = (0, table_search_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: (0, truncate_1.truncateLabelsForLog)(search.namespacePrefix), count }));
     return ranked.slice(offset, offset + limit);
 }

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

@@ -1,11 +1,26 @@
-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.
+ * Hides how a batch runs concurrently and still in the order it was written.
+ *
+ * Operations on different items, and reads of the same item, share a run and
+ * go in flight together; anything that could observe or overwrite an earlier
+ * operation's effect starts the next run. A caller sees the order it wrote —
+ * a `get` after a `put` of the same item sees it, a `search` sees every write
+ * before it — and how independence is judged can change without the store.
  */
-export declare function runBatch<R>(operations: readonly Operation[], dispatch: (operation: Operation) => Promise<R>): Promise<R[]>;
+import type { ParsedOperation } from './parse';
+/**
+ * Run a batch: each run of independent operations concurrently, at most
+ * `limit` in flight, and the runs themselves in
+ * order. Results come back in operation order.
+ *
+ * Accepts: `operations` — in caller order, which is the order they are
+ * observed in; empty returns empty. `limit` — operations in flight within one
+ * run.
+ *
+ * Returns: the results in operation order, not completion order.
+ *
+ * Throws: the first failure. Any failure rejects the whole batch: no operation
+ * in a later run starts, the ones already in flight settle, and that first
+ * error is the one thrown.
+ */
+export declare function runBatch<R>(operations: readonly ParsedOperation[], dispatch: (operation: ParsedOperation) => Promise<R>, limit?: number): Promise<R[]>;

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

@@ -1,52 +1,109 @@
 "use strict";
+/**
+ * Hides how a batch runs concurrently and still in the order it was written.
+ *
+ * Operations on different items, and reads of the same item, share a run and
+ * go in flight together; anything that could observe or overwrite an earlier
+ * operation's effect starts the next run. A caller sees the order it wrote —
+ * a `get` after a `put` of the same item sees it, a `search` sees every write
+ * before it — and how independence is judged can change without the store.
+ */
 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]);
+function itemOf(address) {
+    return JSON.stringify([address.namespace, address.key]);
+}
+/** What `op` touches, decided by the kind the parser already assigned — the only place that asks. */
+function touchOf(op) {
+    switch (op.kind) {
+        case 'put':
+        case 'delete':
+            return { kind: 'write', item: itemOf(op.address) };
+        case 'get':
+            return { kind: 'get', item: itemOf(op.address) };
+        default:
+            return { kind: 'broad' };
+    }
+}
+/**
+ * True when `touch` may not join `segment` — because some operation already in
+ * it addresses the same item, or because a write and a whole-store read would
+ * then be unordered with respect to each other.
+ */
+function conflicts(segment, touch) {
+    if (touch.kind === 'broad')
+        return segment.hasWrite;
+    if (touch.kind === 'get')
+        return segment.written.has(touch.item);
+    return segment.written.has(touch.item) || segment.read.has(touch.item) || segment.hasBroad;
+}
+function admit(segment, index, touch) {
+    segment.indices.push(index);
+    if (touch.kind === 'broad')
+        segment.hasBroad = true;
+    if (touch.kind === 'get')
+        segment.read.add(touch.item);
+    if (touch.kind === 'write') {
+        segment.written.add(touch.item);
+        segment.hasWrite = true;
+    }
+}
+function emptySegment() {
+    return { indices: [], written: new Set(), read: new Set(), hasWrite: false, hasBroad: false };
 }
 /**
- * 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.
+ * Split a batch into runs of mutually independent operations, in caller order.
+ *
+ * Operations that address different items, and reads that address the same
+ * item, are independent of each other and share a run. Anything that could
+ * observe or overwrite an earlier operation's effect starts a new one, so the
+ * order the caller wrote is the order the caller observes: a `get` after a
+ * `put` of the same item sees it, a `get` before one does not, and a `search`
+ * sees every write that precedes it and none that follow.
+ *
+ * Running every write before every read — the earlier behaviour — made a
+ * `[delete, get]` batch return nothing where the reference store returns the
+ * value, and a `[get, put]` batch return the new value where the reference
+ * returns null. `AsyncBatchedStore` coalesces everything enqueued in one tick
+ * into a single `batch()`, so that difference is reachable from ordinary code.
  */
 function planBatch(operations) {
-    const groups = new Map();
-    const reads = [];
+    const runs = [];
+    let segment = emptySegment();
     operations.forEach((op, index) => {
-        if (!('value' in op)) {
-            reads.push(index);
-            return;
+        const touch = touchOf(op);
+        if (segment.indices.length > 0 && conflicts(segment, touch)) {
+            runs.push(segment.indices);
+            segment = emptySegment();
         }
-        const item = itemOf(op);
-        const group = groups.get(item);
-        if (group)
-            group.push(index);
-        else
-            groups.set(item, [index]);
+        admit(segment, index, touch);
     });
-    return { writeGroups: [...groups.values()], reads };
+    if (segment.indices.length > 0)
+        runs.push(segment.indices);
+    return runs;
 }
 /**
- * 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.
+ * Run a batch: each run of independent operations concurrently, at most
+ * `limit` in flight, and the runs themselves in
+ * order. Results come back in operation order.
+ *
+ * Accepts: `operations` — in caller order, which is the order they are
+ * observed in; empty returns empty. `limit` — operations in flight within one
+ * run.
+ *
+ * Returns: the results in operation order, not completion order.
+ *
+ * Throws: the first failure. Any failure rejects the whole batch: no operation
+ * in a later run starts, the ones already in flight settle, and that first
+ * error is the one thrown.
  */
-async function runBatch(operations, dispatch) {
-    const plan = planBatch(operations);
+async function runBatch(operations, dispatch, limit = concurrency_1.DEFAULT_READ_CONCURRENCY) {
     const results = [];
-    await (0, concurrency_1.mapWithConcurrency)(plan.writeGroups, constants_1.DEFAULT_READ_CONCURRENCY, async (group) => {
-        for (const index of group)
+    for (const run of planBatch(operations)) {
+        await (0, concurrency_1.mapWithConcurrency)(run, limit, async (index) => {
             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/filter.d.ts

@@ -1,9 +1,43 @@
+/**
+ * Hides the store's filter grammar.
+ *
+ * Which operators a search filter accepts, how each compares a stored field —
+ * ordered comparisons only between like-typed values, an absent field matching
+ * nothing — and whether an item passes a search's optional filter are decided
+ * here, the same way whichever search path runs.
+ */
+import type { Item } from '@langchain/langgraph-checkpoint';
 /** A JSON value stored in an item or supplied in a filter. */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 /**
- * True when `value` satisfies every field condition in `filter`. A plain value
- * is exact-match ($eq); an operator object ({ $gt: 4 }) applies comparisons.
+ * Whether `value` satisfies every field condition in `filter`.
+ *
+ * Accepts: `value` — a stored item's decoded value. Declared as a record, but a
+ * row holds whatever its writer stored, including `null` and a scalar; such a
+ * value has no own properties and so satisfies no condition. `filter` — a plain
+ * value per field is exact match, an operator object (`{ $gt: 4 }`) applies
+ * comparisons, and `{}` constrains nothing.
+ *
+ * Returns: whether every condition holds.
+ *
+ * Throws: nothing. `search` walks every candidate row, so one row whose value
+ * is not an object must not fail the search.
+ *
+ * Guarantees: own properties only — `value['toString']` would otherwise resolve
+ * up the prototype chain and be compared as if it were stored data.
  */
 export declare function matchesStoreFilter(value: Record<string, JsonValue>, filter: Record<string, JsonValue>): boolean;
+/**
+ * Whether `item` satisfies a search's optional metadata filter.
+ *
+ * Accepts: `filter` — a parsed search's filter; absent passes every item.
+ * `item.value` — whatever the item's writer stored; a value that is not
+ * an object satisfies no condition (see `matchesStoreFilter`).
+ *
+ * Returns: whether the item belongs in the result.
+ *
+ * Throws: nothing, so one unusual row cannot fail a search over many.
+ */
+export declare function passesFilter(item: Item, filter: Record<string, JsonValue> | undefined): boolean;