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

package/dist/cjs/shared/validation/primitives.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PAGE_LIMIT = void 0;
+exports.parseString = parseString;
+exports.assertNonEmptyString = assertNonEmptyString;
+exports.parseInteger = parseInteger;
+exports.assertInteger = assertInteger;
+exports.parseLimit = parseLimit;
+exports.parseStringArray = parseStringArray;
+exports.assertStringArray = assertStringArray;
+exports.assertNoControlChars = assertNoControlChars;
+exports.assertWellFormed = assertWellFormed;
+exports.parseKeySegment = parseKeySegment;
+exports.parseIdentifier = parseIdentifier;
+const errors_js_1 = require("../errors/errors.js");
+exports.MAX_PAGE_LIMIT = 10_000;
+function parseString(value, field) {
+    if (typeof value !== 'string') {
+        throw (0, errors_js_1.validationError)(`${field} must be a string`, field);
+    }
+    return value;
+}
+function parseNonBlankString(value, field) {
+    const text = parseString(value, field);
+    if (text.trim().length === 0) {
+        throw (0, errors_js_1.validationError)(`${field} must be a non-empty string (whitespace-only counts as empty)`, field);
+    }
+    return text;
+}
+function assertNonEmptyString(value, field) {
+    parseNonBlankString(value, field);
+}
+function assertMaxBytes(value, field, maxBytes) {
+    parseString(value, field);
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes > maxBytes) {
+        throw (0, errors_js_1.validationError)(`${field} must be at most ${maxBytes} bytes of UTF-8 (received ${bytes})`, field);
+    }
+}
+function parseInteger(value, field, bounds = {}) {
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw (0, errors_js_1.validationError)(`${field} must be an integer`, field);
+    }
+    if (bounds.min !== undefined && value < bounds.min) {
+        throw (0, errors_js_1.validationError)(`${field} must be >= ${bounds.min}`, field);
+    }
+    if (bounds.max !== undefined && value > bounds.max) {
+        throw (0, errors_js_1.validationError)(`${field} must be <= ${bounds.max}`, field);
+    }
+    return value;
+}
+function assertInteger(value, field, bounds = {}) {
+    parseInteger(value, field, bounds);
+}
+function parseLimit(value, min) {
+    return parseInteger(value, 'limit', { min, max: exports.MAX_PAGE_LIMIT });
+}
+function parseStringElement(item, field, index) {
+    if (typeof item !== 'string') {
+        throw (0, errors_js_1.validationError)(`${field}[${index}] must be a string`, field);
+    }
+    return item;
+}
+function parseStringArray(value, field) {
+    if (!Array.isArray(value)) {
+        throw (0, errors_js_1.validationError)(`${field} must be an array of strings`, field);
+    }
+    const result = [];
+    for (let index = 0; index < value.length; index += 1) {
+        result.push(parseStringElement(value[index], field, index));
+    }
+    return result;
+}
+function assertStringArray(value, field) {
+    parseStringArray(value, field);
+}
+function hasControlChar(value) {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f))
+            return true;
+    }
+    return false;
+}
+function assertNoControlChars(value, field) {
+    parseString(value, field);
+    if (hasControlChar(value)) {
+        throw (0, errors_js_1.validationError)(`${field} must not contain control characters`, field);
+    }
+}
+function assertWellFormed(value, field) {
+    parseString(value, field);
+    if (!value.isWellFormed()) {
+        throw (0, errors_js_1.validationError)(`${field} must be well-formed UTF-16 (it contains an unpaired surrogate, which does not ` +
+            'survive encoding to UTF-8)', field);
+    }
+}
+function assertNoSeparator(value, separator, field) {
+    parseString(value, field);
+    if (value.includes(separator)) {
+        throw (0, errors_js_1.validationError)(`${field} must not contain the reserved "${separator}" separator`, field);
+    }
+}
+function parseKeySegment(value, separator, field, maxBytes) {
+    const text = parseString(value, field);
+    assertMaxBytes(text, field, maxBytes);
+    assertNoSeparator(text, separator, field);
+    assertNoControlChars(text, field);
+    assertWellFormed(text, field);
+    return text;
+}
+function parseIdentifier(value, separator, field, maxBytes) {
+    return parseKeySegment(parseNonBlankString(value, field), separator, field, maxBytes);
+}

package/dist/cjs/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/cjs/shared/validation/ttl.js

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

package/dist/cjs/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/cjs/store/actions/list-namespaces.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchNamespace = matchNamespace;
+exports.truncateDepth = truncateDepth;
+exports.prefixRoot = prefixRoot;
+exports.listNamespaces = listNamespaces;
+const clock_js_1 = require("../../shared/clock.js");
+const paginate_js_1 = require("../../shared/dynamodb/paginate.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const rows_js_1 = require("../internal/rows.js");
+const WILDCARD = '*';
+function segmentMatches(actual, path) {
+    return path.every((element, index) => element === WILDCARD || element === actual[index]);
+}
+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);
+}
+function truncateDepth(namespace, maxDepth) {
+    return maxDepth === undefined ? namespace : namespace.slice(0, maxDepth);
+}
+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 (0, paginate_js_1.paginateQuery)({
+            retry: context.retry,
+            client: context.client,
+            params: (0, table_schema_js_1.withoutExpired)((0, rows_js_1.projectKeys)((0, rows_js_1.scopedQuery)(context.tableName, root)), now),
+            maxItems: context.maxScanItems,
+            maxIterations: context.maxIterations,
+        });
+    }
+    return (0, paginate_js_1.paginateScan)({
+        retry: context.retry,
+        client: context.client,
+        params: (0, table_schema_js_1.withoutExpired)((0, rows_js_1.projectKeys)((0, rows_js_1.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(table_schema_js_1.KEY_SEPARATOR);
+    const right = b.join(table_schema_js_1.KEY_SEPARATOR);
+    return left < right ? -1 : Number(left > right);
+}
+async function listNamespaces(context, op) {
+    if (op.limit === 0)
+        return [];
+    const now = (0, clock_js_1.nowSeconds)();
+    const seen = new Set();
+    const namespaces = [];
+    for await (const raw of namespaceSource(context, op, now)) {
+        const record = (0, rows_js_1.parseStoreRow)(raw);
+        if (!record || (0, table_schema_js_1.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(table_schema_js_1.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/cjs/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/cjs/store/actions/put.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.putItem = putItem;
+const node_crypto_1 = require("node:crypto");
+const clock_js_1 = require("../../shared/clock.js");
+const ttl_js_1 = require("../../shared/validation/ttl.js");
+const item_write_js_1 = require("../internal/item-write.js");
+const rows_js_1 = require("../internal/rows.js");
+const semantic_search_js_1 = require("../internal/semantic-search.js");
+const vector_index_js_1 = require("../internal/vector-index.js");
+async function resolvePassages(context, op, value) {
+    if (op.index === false)
+        return undefined;
+    return (0, semantic_search_js_1.embedPassages)(context, value, op.index);
+}
+async function putItem(context, op) {
+    if (op.kind === 'delete') {
+        await (0, item_write_js_1.deleteStoreItem)(context, op.address);
+        return;
+    }
+    const { namespace, key } = op.address;
+    const value = op.value;
+    const timestamp = (0, clock_js_1.nowIso)();
+    const existing = await (0, rows_js_1.readExisting)(context, (0, rows_js_1.itemRowKey)(op.address));
+    const embedding = await (0, vector_index_js_1.itemVector)(context, op);
+    const embeddings = context.vectorBackend ? undefined : await resolvePassages(context, op, value);
+    const ttlTimestamp = context.ttl ? (0, ttl_js_1.calculateTtlTimestamp)(context.ttl) : undefined;
+    const record = await (0, rows_js_1.buildStoreRow)(context, { namespace, key }, value, {
+        createdAt: (0, rows_js_1.isLiveRow)(existing) ? (existing.createdAt ?? timestamp) : timestamp,
+        updatedAt: timestamp,
+        embeddings,
+        ttlTimestamp,
+        rev: (0, node_crypto_1.randomUUID)(),
+    });
+    await (0, item_write_js_1.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 (0, item_write_js_1.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 (0, vector_index_js_1.syncItemVector)(context, address, embedding);
+}

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

@@ -0,0 +1,38 @@
+/**
+ * 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.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
+ * implements {@link VectorBackend.listKeys} — prune vectors with no canonical
+ * item. A maintenance tool for backend drift; run it when the namespace is
+ * 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` 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.
+ */
+export declare function reconcileVectorIndex(context: StoreContext, namespacePrefix: string[], options?: {
+    signal?: AbortSignal;
+}): Promise<VectorReconcileResult>;

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

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconcileVectorIndex = reconcileVectorIndex;
+const errors_js_1 = require("../../shared/errors/errors.js");
+const parse_js_1 = require("../internal/parse.js");
+const vector_index_js_1 = require("../internal/vector-index.js");
+async function reconcileVectorIndex(context, namespacePrefix, options = {}) {
+    const prefix = (0, parse_js_1.parseNamespace)(namespacePrefix, 'namespacePrefix');
+    if (!(0, vector_index_js_1.hasVectorBackend)(context)) {
+        throw (0, errors_js_1.validationError)('reconcileVectorIndex requires a configured index and vectorBackend', 'vectorBackend');
+    }
+    return (0, vector_index_js_1.reconcileVectors)(context, prefix, options.signal);
+}

package/dist/cjs/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/cjs/store/actions/search.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchItems = searchItems;
+const truncate_js_1 = require("../../shared/logging/truncate.js");
+const semantic_search_js_1 = require("../internal/semantic-search.js");
+const table_search_js_1 = require("../internal/table-search.js");
+const vector_index_js_1 = require("../internal/vector-index.js");
+async function searchItems(context, search, signal) {
+    const { offset, limit } = search;
+    if (limit === 0)
+        return [];
+    if (search.query && (0, vector_index_js_1.hasVectorBackend)(context)) {
+        const ranked = await (0, vector_index_js_1.searchViaBackend)(context, search, signal);
+        return ranked.slice(offset, offset + limit);
+    }
+    if (!search.query || !context.index) {
+        const page = await (0, table_search_js_1.collectCandidates)(context, search, { kind: 'page', need: offset + limit }, signal);
+        return page.map(({ item }) => ({ ...item, score: undefined })).slice(offset, offset + limit);
+    }
+    const candidates = await (0, table_search_js_1.collectCandidates)(context, search, { kind: 'semantic', cap: context.maxSearchCandidates }, signal);
+    const queryVector = await context.index.embeddings.embedQuery(search.query);
+    (0, semantic_search_js_1.assertVectorDims)(context.index, queryVector, 'query');
+    const ranked = (0, table_search_js_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_js_1.truncateLabelsForLog)(search.namespacePrefix), count }));
+    return ranked.slice(offset, offset + limit);
+}