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

package/dist/store/internal/candidates.js

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

package/dist/store/internal/index-reconcile.d.ts

@@ -1,21 +0,0 @@
-import type { VectorBackend, VectorRef } from '../vector-backend';
-import type { StoreContext } from './setup';
-/** A canonical item's location plus the embedding recomputed for it. */
-export interface ReconcileTarget {
-    namespace: string[];
-    key: string;
-    embedding: number[] | undefined;
-}
-/**
- * Enumerate the live (unexpired) items under `prefix`, then recompute their
- * embeddings in batches. A failed embedding rejects the whole reconcile: a
- * skipped item would leave the live set and {@link selectOrphans} would prune
- * its still-valid vector.
- */
-export declare function collectReconcileTargets(context: StoreContext, prefix: string[], signal?: AbortSignal): Promise<ReconcileTarget[]>;
-/** Re-push every live embedding to the backend; returns the upsert count. */
-export declare function pushEmbeddings(backend: VectorBackend, targets: ReconcileTarget[]): Promise<number>;
-/** Refs present in the backend but absent from `live` — orphans to prune. */
-export declare function selectOrphans(backendRefs: VectorRef[], live: ReconcileTarget[]): VectorRef[];
-/** Delete backend vectors with no canonical item; returns the prune count. */
-export declare function pruneOrphans(context: StoreContext, backend: VectorBackend, prefix: string[], live: ReconcileTarget[]): Promise<number>;

package/dist/store/internal/index-reconcile.js

@@ -1,118 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.collectReconcileTargets = collectReconcileTargets;
-exports.pushEmbeddings = pushEmbeddings;
-exports.selectOrphans = selectOrphans;
-exports.pruneOrphans = pruneOrphans;
-const clock_1 = require("../../shared/clock");
-const expiry_1 = require("../../shared/dynamodb/expiry");
-const paginate_1 = require("../../shared/dynamodb/paginate");
-const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
-const item_mapper_1 = require("./item-mapper");
-const keys_1 = require("./keys");
-const query_1 = require("./query");
-const semantic_search_1 = require("./semantic-search");
-const write_verify_1 = require("./write-verify");
-/** Stable, collision-free identity for a (namespace, key) pair. */
-function refIdentity(namespace, key) {
-    return JSON.stringify([...namespace, key]);
-}
-/**
- * Enumerate the live (unexpired) items under `prefix`, then recompute their
- * embeddings in batches. A failed embedding rejects the whole reconcile: a
- * skipped item would leave the live set and {@link selectOrphans} would prune
- * its still-valid vector.
- */
-async function collectReconcileTargets(context, prefix, signal) {
-    const now = (0, clock_1.nowSeconds)();
-    const live = [];
-    const source = (0, paginate_1.paginateQuery)({
-        retry: (0, retry_policy_1.retryFor)(context, signal),
-        signal,
-        client: context.client,
-        params: (0, expiry_1.withoutExpired)((0, query_1.scopedQuery)(context.tableName, prefix), now),
-        maxItems: context.maxScanItems,
-    });
-    for await (const raw of source) {
-        const record = (0, item_mapper_1.narrowStoreRecord)(raw);
-        if (!record) {
-            context.logger.warn('reconcileVectorIndex: skipped a row that is not a store item', {
-                sortKey: raw.SK,
-            });
-            continue;
-        }
-        if ((0, expiry_1.isExpiredRow)(record, now) || !(0, keys_1.namespaceMatchesPrefix)(record.namespace, prefix))
-            continue;
-        const item = await (0, item_mapper_1.readStoreItem)(context, record);
-        live.push({
-            namespace: record.namespace,
-            key: record.key,
-            value: item.value,
-        });
-    }
-    const embeddings = await (0, semantic_search_1.embedValues)(context, live.map((entry) => entry.value));
-    return live.map((entry, i) => ({
-        namespace: entry.namespace,
-        key: entry.key,
-        embedding: embeddings[i],
-    }));
-}
-/** Re-push every live embedding to the backend; returns the upsert count. */
-async function pushEmbeddings(backend, targets) {
-    let upserted = 0;
-    for (const target of targets) {
-        if (!target.embedding)
-            continue;
-        await backend.upsert(target.namespace, target.key, target.embedding);
-        upserted += 1;
-    }
-    return upserted;
-}
-/** Refs present in the backend but absent from `live` — orphans to prune. */
-function selectOrphans(backendRefs, live) {
-    const liveKeys = new Set(live
-        .filter((target) => target.embedding !== undefined)
-        .map((target) => refIdentity(target.namespace, target.key)));
-    return backendRefs.filter((ref) => !liveKeys.has(refIdentity(ref.namespace, ref.key)));
-}
-/**
- * True when a candidate's canonical item is confirmed absent right now. The
- * live-set snapshot and this read are not one point in time, so an item
- * written between them looks orphaned even though it is live — and deleting
- * its vector would silently drop a just-written item out of semantic search.
- */
-async function confirmedGone(context, ref) {
-    return (0, write_verify_1.rowIsAbsent)(context, {
-        PK: (0, keys_1.partitionKey)(ref.namespace),
-        SK: (0, keys_1.sortKey)(ref.namespace, ref.key),
-    });
-}
-/** Delete backend vectors with no canonical item; returns the prune count. */
-async function pruneOrphans(context, backend, prefix, live) {
-    if (!backend.listKeys) {
-        context.logger.info('reconcileVectorIndex prune skipped: backend has no listKeys', { prefix });
-        return 0;
-    }
-    const candidates = selectOrphans(await backend.listKeys(prefix), live);
-    /**
-     * Every item the snapshot actually saw, embedded or not. A candidate in here
-     * is prunable on the evidence already gathered — its item exists but yields
-     * no embedding (its indexable text became empty), so its vector really is
-     * stale. Only a candidate the snapshot never saw at all is ambiguous.
-     */
-    const observed = new Set(live.map((target) => refIdentity(target.namespace, target.key)));
-    let pruned = 0;
-    for (const ref of candidates) {
-        if (!observed.has(refIdentity(ref.namespace, ref.key)) &&
-            !(await confirmedGone(context, ref))) {
-            context.logger.info('reconcileVectorIndex: kept a vector whose item reappeared', {
-                namespace: ref.namespace,
-                key: ref.key,
-            });
-            continue;
-        }
-        await backend.delete(ref.namespace, ref.key);
-        pruned += 1;
-    }
-    return pruned;
-}

package/dist/store/internal/index-sync.d.ts

@@ -1,10 +0,0 @@
-import type { Logger } from '../../shared/logging/logger';
-import type { VectorBackend } from '../vector-backend';
-/**
- * Best-effort sync of one item's embedding to the vector backend after the
- * canonical DynamoDB write has already succeeded. A present embedding upserts;
- * its absence deletes any stale vector. Failures are logged at `warn` and
- * swallowed — the canonical item stands and `reconcileVectorIndex` repairs any
- * drift — so a backend hiccup never fails an otherwise-successful put.
- */
-export declare function syncVectorIndex(backend: VectorBackend, namespace: string[], key: string, embedding: number[] | undefined, logger: Logger): Promise<void>;

package/dist/store/internal/index-sync.js

@@ -1,25 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.syncVectorIndex = syncVectorIndex;
-/**
- * Best-effort sync of one item's embedding to the vector backend after the
- * canonical DynamoDB write has already succeeded. A present embedding upserts;
- * its absence deletes any stale vector. Failures are logged at `warn` and
- * swallowed — the canonical item stands and `reconcileVectorIndex` repairs any
- * drift — so a backend hiccup never fails an otherwise-successful put.
- */
-async function syncVectorIndex(backend, namespace, key, embedding, logger) {
-    try {
-        if (embedding)
-            await backend.upsert(namespace, key, embedding);
-        else
-            await backend.delete(namespace, key);
-    }
-    catch (error) {
-        logger.warn('store.put vector-index sync failed; reconcileVectorIndex will repair', {
-            namespace,
-            key,
-            message: error.message,
-        });
-    }
-}

package/dist/store/internal/item-mapper.d.ts

@@ -1,27 +0,0 @@
-import type { Item } from '@langchain/langgraph-checkpoint';
-import type { DocItem } from '../../shared/dynamodb/types';
-import type { StoreItemRecord } from '../types';
-import type { JsonValue } from './filter';
-import type { StoreContext } from './setup';
-/**
- * Narrow a raw scanned row to a {@link StoreItemRecord}, or `undefined` for a
- * foreign row on a shared table (no `namespace`) — and for a row whose
- * `namespace`/`key` attributes disagree with the DynamoDB key it was found at.
- * The attributes name the S3 path the row may reference, so they must be bound
- * to the partition the row actually lives in: a writer confined to its own
- * partition can then never make a row speak for another tenant's objects.
- */
-export declare function narrowStoreRecord(raw: DocItem): StoreItemRecord | undefined;
-/** Fields controlling a stored item's timestamps, embedding, ttl, and S3 key nonce. */
-export interface BuildItemOptions {
-    createdAt: string;
-    updatedAt: string;
-    embedding?: number[];
-    ttlTimestamp?: number;
-    /** Per-call nonce: uniquifies the S3 key and becomes the row's revision token. */
-    nonce?: string;
-}
-/** Encode a value into the DynamoDB record for a stored item. */
-export declare function buildStoreItem(context: StoreContext, namespace: string[], key: string, value: Record<string, JsonValue>, options: BuildItemOptions): Promise<StoreItemRecord>;
-/** Decode a DynamoDB record back into a store {@link Item}. */
-export declare function readStoreItem(context: StoreContext, record: StoreItemRecord): Promise<Item>;

package/dist/store/internal/item-mapper.js

@@ -1,61 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.narrowStoreRecord = narrowStoreRecord;
-exports.buildStoreItem = buildStoreItem;
-exports.readStoreItem = readStoreItem;
-const codec_1 = require("../../shared/codec/codec");
-const encode_1 = require("../../shared/codec/encode");
-const keys_1 = require("./keys");
-/**
- * Narrow a raw scanned row to a {@link StoreItemRecord}, or `undefined` for a
- * foreign row on a shared table (no `namespace`) — and for a row whose
- * `namespace`/`key` attributes disagree with the DynamoDB key it was found at.
- * The attributes name the S3 path the row may reference, so they must be bound
- * to the partition the row actually lives in: a writer confined to its own
- * partition can then never make a row speak for another tenant's objects.
- */
-function narrowStoreRecord(raw) {
-    if (!Array.isArray(raw.namespace) || typeof raw.key !== 'string')
-        return undefined;
-    const record = raw;
-    const consistent = record.PK === (0, keys_1.partitionKey)(record.namespace) &&
-        record.SK === (0, keys_1.sortKey)(record.namespace, record.key);
-    return consistent ? record : undefined;
-}
-/** Map a store context to the codec collaborators. */
-function storeCodecDeps(context) {
-    return { serde: context.serde, compression: context.compression, offloader: context.offloader };
-}
-/** Encode a value into the DynamoDB record for a stored item. */
-async function buildStoreItem(context, namespace, key, value, options) {
-    const descriptor = await (0, encode_1.encodePayload)(value, storeCodecDeps(context), {
-        keyParts: options.nonce === undefined ? [...namespace, key] : [...namespace, key, options.nonce],
-    });
-    const record = {
-        PK: (0, keys_1.partitionKey)(namespace),
-        SK: (0, keys_1.sortKey)(namespace, key),
-        namespace,
-        key,
-        value: descriptor,
-        createdAt: options.createdAt,
-        updatedAt: options.updatedAt,
-    };
-    if (options.embedding)
-        record.embedding = options.embedding;
-    if (options.ttlTimestamp !== undefined)
-        record.ttl = options.ttlTimestamp;
-    if (options.nonce !== undefined)
-        record.rev = options.nonce;
-    return record;
-}
-/** Decode a DynamoDB record back into a store {@link Item}. */
-async function readStoreItem(context, record) {
-    const value = await (0, codec_1.decodePayload)(record.value, storeCodecDeps(context), [...record.namespace, record.key]);
-    return {
-        namespace: record.namespace,
-        key: record.key,
-        value,
-        createdAt: new Date(record.createdAt),
-        updatedAt: new Date(record.updatedAt),
-    };
-}

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

@@ -1,17 +0,0 @@
-/** Separator joining namespace elements (and the trailing key) in the sort key. */
-export declare const NAMESPACE_SEPARATOR = "#";
-/** Partition key for an item: the adapter tag plus the scope-root element. */
-export declare function partitionKey(namespace: string[]): string;
-/** Sort key: the rest of the namespace plus the key, separator-joined. */
-export declare function sortKey(namespace: string[], key: string): string;
-/**
- * `begins_with` prefix selecting a scoped subtree within `prefix[0]`'s
- * partition. Terminated with the separator so `['users','u1']` does not match a
- * sibling like `u10`. An empty rest yields '' (matches the whole partition).
- */
-export declare function sortKeyPrefix(prefix: string[]): string;
-/**
- * True when `namespace` starts with `prefix`, compared element-by-element (not
- * as a string prefix, so ["userspace"] does not match prefix ["users"]).
- */
-export declare function namespaceMatchesPrefix(namespace: string[], prefix: string[]): boolean;

package/dist/store/internal/keys.js

@@ -1,41 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.NAMESPACE_SEPARATOR = void 0;
-exports.partitionKey = partitionKey;
-exports.sortKey = sortKey;
-exports.sortKeyPrefix = sortKeyPrefix;
-exports.namespaceMatchesPrefix = namespaceMatchesPrefix;
-/** Separator joining namespace elements (and the trailing key) in the sort key. */
-exports.NAMESPACE_SEPARATOR = '#';
-/**
- * Adapter tag prefixed to every store partition key — see the equivalent in
- * checkpointer/internal/keys.ts for why the three adapters' partitions must
- * not overlap on a shared table.
- */
-const ADAPTER_PARTITION_PREFIX = `STORE${exports.NAMESPACE_SEPARATOR}`;
-/** Partition key for an item: the adapter tag plus the scope-root element. */
-function partitionKey(namespace) {
-    return `${ADAPTER_PARTITION_PREFIX}${namespace[0]}`;
-}
-/** Sort key: the rest of the namespace plus the key, separator-joined. */
-function sortKey(namespace, key) {
-    return [...namespace.slice(1), key].join(exports.NAMESPACE_SEPARATOR);
-}
-/**
- * `begins_with` prefix selecting a scoped subtree within `prefix[0]`'s
- * partition. Terminated with the separator so `['users','u1']` does not match a
- * sibling like `u10`. An empty rest yields '' (matches the whole partition).
- */
-function sortKeyPrefix(prefix) {
-    const rest = prefix.slice(1);
-    return rest.length === 0 ? '' : `${rest.join(exports.NAMESPACE_SEPARATOR)}${exports.NAMESPACE_SEPARATOR}`;
-}
-/**
- * True when `namespace` starts with `prefix`, compared element-by-element (not
- * as a string prefix, so ["userspace"] does not match prefix ["users"]).
- */
-function namespaceMatchesPrefix(namespace, prefix) {
-    if (prefix.length > namespace.length)
-        return false;
-    return prefix.every((element, index) => namespace[index] === element);
-}

package/dist/store/internal/namespace-match.d.ts

@@ -1,11 +0,0 @@
-import type { MatchCondition } from '@langchain/langgraph-checkpoint';
-/** True when `namespace` satisfies a prefix/suffix match condition (with `*`). */
-export declare function matchNamespace(namespace: string[], condition: MatchCondition): boolean;
-/** Cap a namespace to at most `maxDepth` elements (no-op when undefined). */
-export declare function truncateDepth(namespace: string[], maxDepth?: number): string[];
-/**
- * Leading concrete (non-wildcard) elements of the first prefix condition. An
- * empty result means the listing cannot be scoped to a single partition and
- * must fall back to a Scan.
- */
-export declare function prefixRoot(conditions?: MatchCondition[]): string[];

package/dist/store/internal/namespace-match.js

@@ -1,40 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.matchNamespace = matchNamespace;
-exports.truncateDepth = truncateDepth;
-exports.prefixRoot = prefixRoot;
-const WILDCARD = '*';
-function segmentMatches(actual, path) {
-    return path.every((element, index) => element === WILDCARD || element === actual[index]);
-}
-/** True when `namespace` satisfies a prefix/suffix match condition (with `*`). */
-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);
-}
-/** Cap a namespace to at most `maxDepth` elements (no-op when undefined). */
-function truncateDepth(namespace, maxDepth) {
-    return maxDepth === undefined ? namespace : namespace.slice(0, maxDepth);
-}
-/**
- * Leading concrete (non-wildcard) elements of the first prefix condition. An
- * empty result means the listing cannot be scoped to a single partition and
- * must fall back to a Scan.
- */
-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;
-}

package/dist/store/internal/option-validation.d.ts

@@ -1,13 +0,0 @@
-import type { DynamoDBStoreOptions } from '../types';
-/**
- * Validate every store option at construction, shared options first.
- *
- * A `vectorBackend` without an `index` is rejected outright rather than
- * silently degrading: with no embeddings configured, every `put` would compute
- * no vector and instruct the backend to *delete* the item's entry instead of
- * indexing it, and `search()` would fall through to an unranked scan-order
- * listing with no `.score` field and no error — a semantic query returning a
- * normal-looking but meaningless response. `reconcileVectorIndex` already
- * refused this exact misconfiguration.
- */
-export declare function validateStoreOptions(options: DynamoDBStoreOptions): void;

package/dist/store/internal/option-validation.js

@@ -1,77 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateStoreOptions = validateStoreOptions;
-const errors_1 = require("../../shared/errors/errors");
-const options_1 = require("../../shared/validation/options");
-const primitives_1 = require("../../shared/validation/primitives");
-const score_direction_1 = require("./score-direction");
-/**
- * Reject an `index` that cannot actually embed. `IndexConfig` mandates
- * `embeddings`, but a JavaScript caller can omit it or pass the wrong shape,
- * and the failure then surfaced as a raw `TypeError` deep inside the first
- * `put()`/`search()` rather than this library's typed error at construction.
- *
- * Both methods are required: documents are embedded with `embedDocuments()`
- * on `put()` and queries with `embedQuery()` on `search()`. `dims` is only
- * compared against returned vectors when it is a positive integer, so a
- * configuration that omits it keeps working.
- */
-function assertUsableIndex(index) {
-    if (!index)
-        return;
-    const embeddings = index.embeddings;
-    const missing = ['embedQuery', 'embedDocuments'].find((method) => typeof embeddings?.[method] !== 'function');
-    if (missing === undefined)
-        return;
-    throw new errors_1.ValidationError(`\`index.embeddings\` must be an Embeddings implementation exposing ${missing}(); ` +
-        'documents are embedded with embedDocuments() on put() and queries with embedQuery() ' +
-        'on search()', 'index');
-}
-/**
- * Reject a `vectorScoreDirection` outside the declared union.
- *
- * {@link toRelevanceScores} treats anything it does not recognise as a no-op —
- * the only safe default, since guessing would invert a ranking — so a mistyped
- * or config-file-sourced value would otherwise leave a distance backend ranked
- * backwards with no error and no warning anywhere. Same premise as
- * {@link assertUsableIndex}: a JavaScript caller can pass a string the type
- * never admits.
- */
-function assertScoreDirection(direction) {
-    if (direction === undefined || score_direction_1.VECTOR_SCORE_DIRECTIONS.includes(direction))
-        return;
-    throw new errors_1.ValidationError(`vectorScoreDirection must be one of ${score_direction_1.VECTOR_SCORE_DIRECTIONS.join(' | ')}; received ` +
-        `${JSON.stringify(direction)}, which would be left in the backend's own direction and ` +
-        'could rank a distance backend backwards', 'vectorScoreDirection');
-}
-/** Both in-memory caps must be positive integers; 0 would silently return nothing. */
-function validateLimits(options) {
-    if (options.maxScanItems !== undefined) {
-        (0, primitives_1.validateInteger)(options.maxScanItems, 'maxScanItems', { min: 1 });
-    }
-    if (options.maxSearchCandidates !== undefined) {
-        (0, primitives_1.validateInteger)(options.maxSearchCandidates, 'maxSearchCandidates', { min: 1 });
-    }
-}
-/**
- * Validate every store option at construction, shared options first.
- *
- * A `vectorBackend` without an `index` is rejected outright rather than
- * silently degrading: with no embeddings configured, every `put` would compute
- * no vector and instruct the backend to *delete* the item's entry instead of
- * indexing it, and `search()` would fall through to an unranked scan-order
- * listing with no `.score` field and no error — a semantic query returning a
- * normal-looking but meaningless response. `reconcileVectorIndex` already
- * refused this exact misconfiguration.
- */
-function validateStoreOptions(options) {
-    (0, options_1.validateBaseAdapterOptions)(options);
-    validateLimits(options);
-    if (options.vectorBackend && !options.index) {
-        throw new errors_1.ValidationError('vectorBackend requires a configured `index` (embeddings); without one no embedding ' +
-            'is computed, every put would clear the item vector, and search would silently return ' +
-            'unranked, score-less results', 'vectorBackend');
-    }
-    assertUsableIndex(options.index);
-    assertScoreDirection(options.vectorScoreDirection);
-}

package/dist/store/internal/overwrite-swap.d.ts

@@ -1,32 +0,0 @@
-import type { StoreItemRecord } from '../types';
-import { type ExistingRecordMeta } from './read-existing';
-import type { StoreContext } from './setup';
-/**
- * Commit `record`, re-reading and retrying while another writer holds the row,
- * and return the state this write actually superseded — the only descriptor
- * safe to delete afterwards.
- *
- * Without the swap both racers read the same previous descriptor, both commit,
- * and both delete it, orphaning the loser's own upload. Retrying against the
- * *re-read* state is what makes each writer supersede exactly one payload.
- *
- * A rejection is not proof a competitor won: `withDynamoDBRetry` retries
- * transient errors, so an attempt can commit server-side, its response can be
- * lost, and the retried put can hit the row it just wrote and fail the same
- * guard — indistinguishable from a competitor's win by the rejection alone.
- * Each attempt's pinned observation is captured in `attempted` before the
- * put, so that when a re-read finds the row already holding *this call's
- * own* `rev`, the swap returns whatever `attempted` held — never this
- * record's own just-committed value, which would strand the live row
- * pointing at a deleted object. That comparison is guarded on `rev` being
- * set: `rev` is optional on the record type, and an unnonced record against a
- * pre-0.9.0 revision-less row would otherwise match `undefined === undefined`
- * and claim a race it never entered.
- *
- * On exhaustion the write proceeds unconditionally and warns. That is
- * deliberate: the fallback is precisely the pre-0.9.0 behaviour — one possible
- * orphan, reclaimed by a lifecycle rule — so pathological contention degrades
- * instead of turning a working put into an error. `createdAt` is refreshed from
- * each re-read so a row created by whoever won keeps its true creation time.
- */
-export declare function putWithRevisionSwap(context: StoreContext, record: StoreItemRecord, existing: ExistingRecordMeta): Promise<ExistingRecordMeta>;