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

package/dist/esm/shared/validation/ttl.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Hides how a `ttl` option becomes an expiry.
+ *
+ * A caller gives days or seconds. The one-unit rule, the five-year cap, the
+ * epoch second DynamoDB's TTL attribute takes, and the S3 lifecycle days that
+ * keep an offloaded object from expiring before its row are all derived
+ * here, so the two spellings of the `ttl` option are accepted or rejected
+ * alike and no reader re-derives one unit from the other itself. A stored
+ * row's own epoch-second `ttl` is converted to milliseconds for `Date` where
+ * that row is read, not here.
+ */
+/** Maximum TTL expressed in days (5 years). */
+export declare const MAX_TTL_DAYS: number;
+/** Maximum TTL expressed in seconds: the same five years as {@link MAX_TTL_DAYS}. */
+export declare const MAX_TTL_SECONDS: number;
+/**
+ * Extra days an S3 lifecycle rule adds over the TTL it backs, so the offloaded
+ * object is never removed before the row that names it expires, never the
+ * other way round. The rule expires an object by age, at or after creation +
+ * ceil(ttl) + this margin, which is at or after the `ttl` of any row naming
+ * it, so DynamoDB's physical-deletion lag (typically within a few days of the
+ * `ttl`, with no fixed bound:
+ * https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html)
+ * does not matter. The margin is headroom, not a bound on that lag.
+ */
+export declare const S3_LIFECYCLE_SWEEP_MARGIN_DAYS = 2;
+/** Time-to-live expressed in whole days or whole seconds. */
+export type TtlOption = {
+    days: number;
+} | {
+    seconds: number;
+};
+/**
+ * A {@link TtlOption} resolved to a positive number of seconds.
+ *
+ * Accepts: `ttl` — declared as the two-shape union; a JavaScript caller, or a
+ * config built from JSON, can also reach `undefined`, a non-object, `{}`, an
+ * object carrying both keys and one carrying any other key, and each is
+ * rejected. Within a shape the value must be an integer of at least 1.
+ *
+ * Returns: whole seconds, `days × 86400` for the days form.
+ *
+ * Throws: `VALIDATION`, in this order, naming `ttl` for a value that is not
+ * an object, `ttl.<key>` for a key other than `days` or `seconds`, `ttl` for
+ * an object naming neither unit or both, and `ttl.days` or `ttl.seconds` for a
+ * value outside 1..five years. Both forms share that cap, so the two spellings
+ * of one duration are accepted or rejected alike.
+ */
+export declare function resolveTtlSeconds(ttl: TtlOption): number;
+/**
+ * The value DynamoDB's TTL attribute takes for an item written now: the Unix
+ * epoch second at which it expires.
+ *
+ * Accepts: `ttl` — as {@link resolveTtlSeconds}. `now` — a clock returning
+ * epoch **milliseconds**, defaulting to `Date.now`; supplied by tests and by
+ * the adapters' clock seam.
+ *
+ * Returns: `floor(now() / 1000) + resolveTtlSeconds(ttl)`. Whole seconds,
+ * because DynamoDB reads the attribute as an epoch-second Number
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/time-to-live-ttl-before-you-start.html).
+ *
+ * Throws: whatever {@link resolveTtlSeconds} throws.
+ */
+export declare function calculateTtlTimestamp(ttl: TtlOption, now?: () => number): number;
+/**
+ * The `Days` of the S3 lifecycle expiration rule that backs a TTL.
+ *
+ * Accepts: `ttl` — as {@link resolveTtlSeconds}.
+ *
+ * Returns: the TTL rounded **up** to whole days plus
+ * {@link S3_LIFECYCLE_SWEEP_MARGIN_DAYS}, so always at least
+ * `1 + margin`.
+ *
+ * Throws: whatever {@link resolveTtlSeconds} throws.
+ *
+ * Guarantees: the object outlives the row that points at it, for every row
+ * written under the `ttl` this rule was computed from. S3 expires an object at
+ * the first midnight UTC at least `Days` after creation, while DynamoDB
+ * deletes an expired item typically within a few days of its `ttl`, with no
+ * fixed bound
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html).
+ * Every row naming the object carries a `ttl` no later than its creation plus
+ * `ttl`, so the object, expiring at or after that, is not removed before its
+ * row expires; readers hide a metadata, store or history row by its own `ttl`,
+ * and serve a checkpoint's payload and pending-write rows only while its
+ * metadata row is live. The margin is headroom, not a bound on the lag.
+ *
+ * The rule expires by age every object under its prefix, including objects
+ * named by rows written under an earlier `ttl`. After a rule is rewritten for
+ * a smaller `ttl`, the guarantee therefore holds only once every row written
+ * under the old, longer value has expired; until then such a row can outlive
+ * its object. Rewriting it for a larger `ttl` keeps the guarantee.
+ */
+export declare function lifecycleExpirationDays(ttl: TtlOption): number;

package/dist/esm/shared/validation/ttl.js

@@ -0,0 +1,46 @@
+import { validationError } from '../errors/errors.js';
+import { allKeysOf, assertShape } from './option-shape.js';
+import { assertInteger } from './primitives.js';
+const SECONDS_PER_DAY = 24 * 60 * 60;
+export const MAX_TTL_DAYS = 365 * 5;
+export const MAX_TTL_SECONDS = MAX_TTL_DAYS * 24 * 60 * 60;
+export const S3_LIFECYCLE_SWEEP_MARGIN_DAYS = 2;
+const TTL_KEYS = allKeysOf({
+    days: 'days',
+    seconds: 'seconds',
+});
+function assertWithinCap(value, field, max) {
+    assertInteger(value, field, { min: 1 });
+    if (value > max) {
+        throw validationError(`${field} must be <= ${max} (five years)`, field);
+    }
+}
+function assertOneUnit(ttl) {
+    if (typeof ttl !== 'object' || ttl === null) {
+        throw validationError('ttl must be an object: { days } or { seconds }', 'ttl');
+    }
+    assertShape(ttl, TTL_KEYS, 'ttl');
+    const days = 'days' in ttl;
+    const seconds = 'seconds' in ttl;
+    if (days && seconds) {
+        throw validationError('ttl must specify either ttl.days or ttl.seconds, not both', 'ttl');
+    }
+    if (!days && !seconds) {
+        throw validationError('ttl must specify either ttl.days or ttl.seconds', 'ttl');
+    }
+}
+export function resolveTtlSeconds(ttl) {
+    assertOneUnit(ttl);
+    if ('days' in ttl) {
+        assertWithinCap(ttl.days, 'ttl.days', MAX_TTL_DAYS);
+        return ttl.days * SECONDS_PER_DAY;
+    }
+    assertWithinCap(ttl.seconds, 'ttl.seconds', MAX_TTL_SECONDS);
+    return ttl.seconds;
+}
+export function calculateTtlTimestamp(ttl, now = Date.now) {
+    return Math.floor(now() / 1000) + resolveTtlSeconds(ttl);
+}
+export function lifecycleExpirationDays(ttl) {
+    return Math.ceil(resolveTtlSeconds(ttl) / SECONDS_PER_DAY) + S3_LIFECYCLE_SWEEP_MARGIN_DAYS;
+}

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

@@ -0,0 +1,79 @@
+/**
+ * Hides how the distinct namespaces are found and held in one order.
+ *
+ * A listing reads every live row it can reach — one partition when its first
+ * prefix condition opens with concrete labels, the whole table otherwise —
+ * keeps the namespaces every condition matches, truncates and deduplicates
+ * them, and sorts them by one pinned collation with its ties settled. A caller
+ * paging by `offset` gets the same order on every call and every host.
+ */
+import type { MatchCondition } from '@langchain/langgraph-checkpoint';
+import type { ParsedList } from '../internal/parse.js';
+import type { StoreContext } from '../internal/setup.js';
+/**
+ * Whether `namespace` satisfies one match condition. `condition.matchType` is
+ * `'prefix'` or `'suffix'`, already refused otherwise by the parser that built
+ * `condition` (`parseMatchCondition` in `parse.ts`).
+ *
+ * Accepts: `condition.path` — elements, where `'*'` matches any one element;
+ * longer than the namespace never matches, and empty matches every namespace.
+ *
+ * Returns: whether the condition holds.
+ *
+ * Throws: nothing.
+ */
+export declare function matchNamespace(namespace: string[], condition: MatchCondition): boolean;
+/**
+ * Cap a namespace to at most `maxDepth` elements.
+ *
+ * Accepts: `maxDepth` — absent returns the namespace unchanged; otherwise a
+ * parsed positive integer (see `parseListOperation` for what a negative or
+ * zero value did here).
+ *
+ * Returns: the namespace, truncated from the end; shorter than `maxDepth` is
+ * returned whole.
+ *
+ * Throws: nothing.
+ */
+export declare function truncateDepth(namespace: string[], maxDepth?: number): string[];
+/**
+ * Leading concrete (non-wildcard) elements of the first prefix condition.
+ *
+ * Accepts: `conditions` — absent, empty, suffix-only, or a prefix condition
+ * starting with `'*'` all yield nothing to scope by.
+ *
+ * Returns: the concrete leading elements, which name a partition and a sort-key
+ * prefix the listing can be read from. An empty result means the listing cannot
+ * be scoped to one partition and falls back to a Scan.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: the root is only ever a *superset* of what the conditions select
+ * — every condition is still applied to each namespace read — so scoping can
+ * never drop a namespace that belongs in the answer.
+ */
+export declare function prefixRoot(conditions?: MatchCondition[]): string[];
+/**
+ * The distinct namespaces satisfying every match condition.
+ *
+ * Accepts: `op` — parsed; every match condition must hold, absent or empty
+ * matches every namespace. A concrete prefix root scopes the read to one
+ * partition's Query, and anything else — a suffix condition, a leading `*`, no
+ * conditions — spans the table and is one of the four reads allowed to Scan
+ * (`test/static/guards/scan-sites.ts`).
+ * `op.maxDepth` — namespaces are truncated to it and then
+ * deduplicated, so `['a','b']` and `['a','c']` list once as `['a']`.
+ * `op.offset` and `op.limit` — a `limit` of 0 returns an empty listing without reading.
+ *
+ * Returns: the namespaces, sorted, then `limit` of them from `offset`.
+ *
+ * Throws: `RESULT_TRUNCATED` when `maxScanItems` or `maxIterations` is
+ * reached while rows remain, so a partial listing is never returned as a
+ * complete one; `FORMAT_UNSUPPORTED` for a store item a newer release wrote.
+ *
+ * Guarantees: every live row is read — the answer is about which namespaces
+ * exist, and paging over it must not depend on which rows were read first. That
+ * is also why the sort is total (see {@link compareNamespaces}), and why a
+ * `limit` of 0 is answered ahead of the read rather than by slicing one.
+ */
+export declare function listNamespaces(context: StoreContext, op: ParsedList): Promise<string[][]>;

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

@@ -0,0 +1,86 @@
+import { nowSeconds } from '../../shared/clock.js';
+import { paginateQuery, paginateScan } from '../../shared/dynamodb/paginate.js';
+import { isExpiredRow, KEY_SEPARATOR, withoutExpired } from '../../shared/dynamodb/table-schema.js';
+import { parseStoreRow, projectKeys, scopedQuery, storeScan } from '../internal/rows.js';
+const WILDCARD = '*';
+function segmentMatches(actual, path) {
+    return path.every((element, index) => element === WILDCARD || element === actual[index]);
+}
+export function matchNamespace(namespace, condition) {
+    const { matchType, path } = condition;
+    if (path.length > namespace.length)
+        return false;
+    const slice = matchType === 'prefix'
+        ? namespace.slice(0, path.length)
+        : namespace.slice(namespace.length - path.length);
+    return segmentMatches(slice, path);
+}
+export function truncateDepth(namespace, maxDepth) {
+    return maxDepth === undefined ? namespace : namespace.slice(0, maxDepth);
+}
+export function prefixRoot(conditions) {
+    const prefixCondition = conditions?.find((condition) => condition.matchType === 'prefix');
+    if (!prefixCondition)
+        return [];
+    const root = [];
+    for (const element of prefixCondition.path) {
+        if (element === WILDCARD)
+            break;
+        root.push(element);
+    }
+    return root;
+}
+function namespaceSource(context, op, now) {
+    const root = prefixRoot(op.matchConditions);
+    if (root.length > 0) {
+        return paginateQuery({
+            retry: context.retry,
+            client: context.client,
+            params: withoutExpired(projectKeys(scopedQuery(context.tableName, root)), now),
+            maxItems: context.maxScanItems,
+            maxIterations: context.maxIterations,
+        });
+    }
+    return paginateScan({
+        retry: context.retry,
+        client: context.client,
+        params: withoutExpired(projectKeys(storeScan(context.tableName)), now),
+        maxItems: context.maxScanItems,
+        maxIterations: context.maxIterations,
+    });
+}
+const NAMESPACE_COLLATOR = new Intl.Collator('en');
+const REFERENCE_JOIN = ':';
+function compareNamespaces(a, b) {
+    const collated = NAMESPACE_COLLATOR.compare(a.join(REFERENCE_JOIN), b.join(REFERENCE_JOIN));
+    if (collated !== 0)
+        return collated;
+    const left = a.join(KEY_SEPARATOR);
+    const right = b.join(KEY_SEPARATOR);
+    return left < right ? -1 : Number(left > right);
+}
+export async function listNamespaces(context, op) {
+    if (op.limit === 0)
+        return [];
+    const now = nowSeconds();
+    const seen = new Set();
+    const namespaces = [];
+    for await (const raw of namespaceSource(context, op, now)) {
+        const record = parseStoreRow(raw);
+        if (!record || isExpiredRow(record, now))
+            continue;
+        const namespace = record.namespace;
+        if (op.matchConditions &&
+            !op.matchConditions.every((condition) => matchNamespace(namespace, condition))) {
+            continue;
+        }
+        const truncated = truncateDepth(namespace, op.maxDepth);
+        const dedupeKey = truncated.join(KEY_SEPARATOR);
+        if (seen.has(dedupeKey))
+            continue;
+        seen.add(dedupeKey);
+        namespaces.push(truncated);
+    }
+    namespaces.sort(compareNamespaces);
+    return namespaces.slice(op.offset, op.offset + op.limit);
+}

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

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+import type { ParsedDelete, ParsedPut } from '../internal/parse.js';
+import type { StoreContext } from '../internal/setup.js';
+/**
+ * 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 — or naming `payload` for one too large to store inline without `s3`,
+ * or, once offloaded, larger than `s3.maxDownloadBytes`; `VALIDATION` again,
+ * naming `index` or `value`, for the built row — payload plus its inline
+ * vectors — over DynamoDB's 400 KB item limit, naming `index` when the
+ * vectors are what pushed it over, checked before anything is written;
+ * `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 of a live item; a put
+ * over a row that has expired but not yet been swept is a creation, since no
+ * reader could still see that item. 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.
+ */
+export declare function putItem(context: StoreContext, op: ParsedPut | ParsedDelete): Promise<void>;

package/dist/esm/store/actions/put.js

@@ -0,0 +1,46 @@
+import { randomUUID } from 'node:crypto';
+import { nowIso } from '../../shared/clock.js';
+import { calculateTtlTimestamp } from '../../shared/validation/ttl.js';
+import { deleteStoreItem, persistRow, verifyWriteLanded } from '../internal/item-write.js';
+import { buildStoreRow, isLiveRow, itemRowKey, readExisting, } from '../internal/rows.js';
+import { embedPassages } from '../internal/semantic-search.js';
+import { itemVector, syncItemVector } from '../internal/vector-index.js';
+async function resolvePassages(context, op, value) {
+    if (op.index === false)
+        return undefined;
+    return embedPassages(context, value, op.index);
+}
+export async function putItem(context, op) {
+    if (op.kind === 'delete') {
+        await deleteStoreItem(context, op.address);
+        return;
+    }
+    const { namespace, key } = op.address;
+    const value = op.value;
+    const timestamp = nowIso();
+    const existing = await readExisting(context, itemRowKey(op.address));
+    const embedding = await itemVector(context, op);
+    const embeddings = context.vectorBackend ? undefined : await resolvePassages(context, op, value);
+    const ttlTimestamp = context.ttl ? calculateTtlTimestamp(context.ttl) : undefined;
+    const record = await buildStoreRow(context, { namespace, key }, value, {
+        createdAt: isLiveRow(existing) ? (existing.createdAt ?? timestamp) : timestamp,
+        updatedAt: timestamp,
+        embeddings,
+        ttlTimestamp,
+        rev: randomUUID(),
+    });
+    await persistRow(context, record, existing);
+    await syncVectorWhileCurrent(context, op.address, record, embedding);
+}
+async function syncVectorWhileCurrent(context, address, record, embedding) {
+    if (context.vectorBackend === undefined)
+        return;
+    if ((await verifyWriteLanded(context, record)) !== 'landed') {
+        context.logger.info('store.put: left the vector index to the write that superseded this put', {
+            namespace: address.namespace,
+            key: address.key,
+        });
+        return;
+    }
+    await syncItemVector(context, address, embedding);
+}

package/dist/{store/actions/reconcile-vector-index.js → esm/store/actions/reconcile-vector-index.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides what a reconcile refuses before it touches the backend.
  *
@@ -8,11 +7,8 @@
  * 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 parse_1 = require("../internal/parse");
-const vector_index_1 = require("../internal/vector-index");
+import type { StoreContext } from '../internal/setup.js';
+import type { VectorReconcileResult } from '../types.js';
 /**
  * Repair the vector backend against the canonical DynamoDB items under
  * `namespacePrefix`: re-push every live embedding, and — when the backend
@@ -28,19 +24,15 @@ const vector_index_1 = require("../internal/vector-index");
  * 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.
+ * `RESULT_TRUNCATED` past `maxScanItems` or `maxIterations`, 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 = {}) {
-    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');
-    }
-    return (0, vector_index_1.reconcileVectors)(context, prefix, options.signal);
-}
+export declare function reconcileVectorIndex(context: StoreContext, namespacePrefix: string[], options?: {
+    signal?: AbortSignal;
+}): Promise<VectorReconcileResult>;

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

@@ -0,0 +1,10 @@
+import { validationError } from '../../shared/errors/errors.js';
+import { parseNamespace } from '../internal/parse.js';
+import { hasVectorBackend, reconcileVectors } from '../internal/vector-index.js';
+export async function reconcileVectorIndex(context, namespacePrefix, options = {}) {
+    const prefix = parseNamespace(namespacePrefix, 'namespacePrefix');
+    if (!hasVectorBackend(context)) {
+        throw validationError('reconcileVectorIndex requires a configured index and vectorBackend', 'vectorBackend');
+    }
+    return reconcileVectors(context, prefix, options.signal);
+}

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

@@ -0,0 +1,38 @@
+/**
+ * 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.js';
+import type { StoreContext } from '../internal/setup.js';
+/**
+ * Search items under a namespace prefix: metadata filtering plus optional
+ * 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, search: ParsedSearch, signal?: AbortSignal): Promise<SearchItem[]>;

package/dist/esm/store/actions/search.js

@@ -0,0 +1,23 @@
+import { truncateLabelsForLog } from '../../shared/logging/truncate.js';
+import { assertVectorDims } from '../internal/semantic-search.js';
+import { collectCandidates, rankInMemory } from '../internal/table-search.js';
+import { hasVectorBackend, searchViaBackend } from '../internal/vector-index.js';
+export async function searchItems(context, search, signal) {
+    const { offset, limit } = search;
+    if (limit === 0)
+        return [];
+    if (search.query && hasVectorBackend(context)) {
+        const ranked = await searchViaBackend(context, search, signal);
+        return ranked.slice(offset, offset + limit);
+    }
+    if (!search.query || !context.index) {
+        const page = await collectCandidates(context, search, { kind: 'page', need: offset + limit }, signal);
+        return page.map(({ item }) => ({ ...item, score: undefined })).slice(offset, offset + limit);
+    }
+    const candidates = await collectCandidates(context, search, { kind: 'semantic', cap: context.maxSearchCandidates }, signal);
+    const queryVector = await context.index.embeddings.embedQuery(search.query);
+    assertVectorDims(context.index, queryVector, 'query');
+    const ranked = 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: truncateLabelsForLog(search.namespacePrefix), count }));
+    return ranked.slice(offset, offset + limit);
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Hides how a batch runs: every read first, against the state the batch found,
+ * then one write per item, concurrently within each phase.
+ *
+ * That is how the reference store evaluates a batch — a get, a search or a
+ * listing is answered as the batch found things, and the puts are applied
+ * afterwards, the last one per item winning — so a graph developed against it
+ * gets the same answers here, and two tasks of one superstep that touch the
+ * same item get answers that do not depend on which of them was enqueued
+ * first. The operations of one phase share the call's one decode budget,
+ * divided between them, so a batch of concurrent searches costs no more memory
+ * than a single one.
+ */
+import type { ParsedOperation } from './parse.js';
+/** The two phases of a batch: the indices of its reads, and of the one write kept per item. */
+export interface BatchPlan {
+    readonly reads: number[];
+    readonly writes: number[];
+}
+/**
+ * Split a batch into the reads it answers first and the writes it applies
+ * afterwards.
+ *
+ * Accepts: `operations` — in caller order.
+ *
+ * Returns: the indices of every get, search and listing, in caller order, and
+ * the index of the last put or delete addressing each item, in caller order.
+ * An earlier write to the same item is superseded before it is sent: the
+ * reference applies only the last put per key, and sending both would race
+ * two compare-and-swaps for an outcome the batch has already decided.
+ *
+ * Throws: nothing.
+ */
+export declare function planBatch(operations: readonly ParsedOperation[]): BatchPlan;
+/**
+ * Run a batch: its reads concurrently, at most `limit` in flight, then its
+ * writes the same way. Results come back in operation order.
+ *
+ * Accepts: `operations` — in caller order. `dispatch` — handed each operation
+ * and its share of the budget: `limit` divided by the operations its phase
+ * keeps in flight, and never less than one. `limit` — operations in flight
+ * within one phase.
+ *
+ * Returns: the results in operation order, not completion order; a write
+ * superseded by a later one to the same item answers `null`, as the write
+ * that was sent does, without having been sent.
+ *
+ * Throws: the first failure. Any failure rejects the whole batch: no operation
+ * in a later phase starts, the ones already in flight settle, and that first
+ * error is the one thrown.
+ *
+ * Guarantees: every read sees the state before any of the batch's writes, and
+ * the operations of one call decode at most `limit` payloads at once between
+ * them, which is what `readConcurrency`'s documented memory ceiling assumes.
+ */
+export declare function runBatch<R>(operations: readonly ParsedOperation[], dispatch: (operation: ParsedOperation, readConcurrency: number) => Promise<R>, limit?: number): Promise<(R | null)[]>;

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

@@ -0,0 +1,28 @@
+import { DEFAULT_READ_CONCURRENCY, mapWithConcurrency } from '../../shared/concurrency.js';
+function itemOf(address) {
+    return JSON.stringify([address.namespace, address.key]);
+}
+export function planBatch(operations) {
+    const reads = [];
+    const lastWrite = new Map();
+    operations.forEach((op, index) => {
+        if (op.kind === 'put' || op.kind === 'delete')
+            lastWrite.set(itemOf(op.address), index);
+        else
+            reads.push(index);
+    });
+    return { reads, writes: [...lastWrite.values()].sort((a, b) => a - b) };
+}
+export async function runBatch(operations, dispatch, limit = DEFAULT_READ_CONCURRENCY) {
+    const results = operations.map(() => null);
+    const { reads, writes } = planBatch(operations);
+    for (const phase of [reads, writes]) {
+        if (phase.length === 0)
+            continue;
+        const share = Math.max(1, Math.floor(limit / Math.min(limit, phase.length)));
+        await mapWithConcurrency(phase, limit, async (index) => {
+            results[index] = await dispatch(operations[index], share);
+        });
+    }
+    return results;
+}

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

@@ -0,0 +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
+ * satisfying only `$ne` and `$nin` — 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;
+};
+/**
+ * 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;