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

package/dist/cjs/store/internal/rows.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REVISION_ATTRIBUTE = void 0;
+exports.storePartitionPrefix = storePartitionPrefix;
+exports.partitionKey = partitionKey;
+exports.sortKey = sortKey;
+exports.sortKeyPrefix = sortKeyPrefix;
+exports.namespaceMatchesPrefix = namespaceMatchesPrefix;
+exports.itemRowKey = itemRowKey;
+exports.scopedQuery = scopedQuery;
+exports.storeScan = storeScan;
+exports.projectKeys = projectKeys;
+exports.isLiveRow = isLiveRow;
+exports.readExisting = readExisting;
+exports.existingFrom = existingFrom;
+exports.parseStoreRow = parseStoreRow;
+exports.parseWholeStoreRow = parseWholeStoreRow;
+exports.buildStoreRow = buildStoreRow;
+exports.readStoreItem = readStoreItem;
+const node_crypto_1 = require("node:crypto");
+const clock_js_1 = require("../../shared/clock.js");
+const codec_js_1 = require("../../shared/codec/codec.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+exports.REVISION_ATTRIBUTE = 'rev';
+const ADAPTER_PARTITION_PREFIX = `${table_schema_js_1.ADAPTER_TAGS.store}${table_schema_js_1.KEY_SEPARATOR}`;
+function storePartitionPrefix() {
+    return ADAPTER_PARTITION_PREFIX;
+}
+function partitionKey(namespace) {
+    return `${ADAPTER_PARTITION_PREFIX}${namespace[0]}`;
+}
+function sortKey(namespace, key) {
+    return [...namespace.slice(1), key].join(table_schema_js_1.KEY_SEPARATOR);
+}
+function sortKeyPrefix(prefix) {
+    const rest = prefix.slice(1);
+    return rest.length === 0 ? '' : `${rest.join(table_schema_js_1.KEY_SEPARATOR)}${table_schema_js_1.KEY_SEPARATOR}`;
+}
+function namespaceMatchesPrefix(namespace, prefix) {
+    if (prefix.length > namespace.length)
+        return false;
+    return prefix.every((element, index) => namespace[index] === element);
+}
+function itemRowKey(address) {
+    return { PK: partitionKey(address.namespace), SK: sortKey(address.namespace, address.key) };
+}
+function scopedQuery(tableName, prefix) {
+    const skPrefix = sortKeyPrefix(prefix);
+    if (skPrefix.length === 0) {
+        return {
+            TableName: tableName,
+            KeyConditionExpression: '#pk = :pk',
+            ExpressionAttributeNames: { '#pk': table_schema_js_1.PARTITION_KEY_ATTRIBUTE },
+            ExpressionAttributeValues: { ':pk': partitionKey(prefix) },
+        };
+    }
+    return {
+        TableName: tableName,
+        KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :skp)',
+        ExpressionAttributeNames: { '#pk': table_schema_js_1.PARTITION_KEY_ATTRIBUTE, '#sk': table_schema_js_1.SORT_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: { ':pk': partitionKey(prefix), ':skp': skPrefix },
+    };
+}
+function storeScan(tableName) {
+    return {
+        TableName: tableName,
+        FilterExpression: 'begins_with(#pk, :pkp) AND attribute_exists(#ns)',
+        ExpressionAttributeNames: { '#pk': table_schema_js_1.PARTITION_KEY_ATTRIBUTE, '#ns': 'namespace' },
+        ExpressionAttributeValues: { ':pkp': storePartitionPrefix() },
+    };
+}
+function projectKeys(params) {
+    return {
+        ...params,
+        ProjectionExpression: `${table_schema_js_1.PARTITION_KEY_ATTRIBUTE}, ${table_schema_js_1.SORT_KEY_ATTRIBUTE}, #ns, #key, #v`,
+        ExpressionAttributeNames: {
+            ...params.ExpressionAttributeNames,
+            '#ns': 'namespace',
+            '#key': 'key',
+            '#v': 'v',
+        },
+    };
+}
+function isLiveRow(existing) {
+    return existing.exists && !(0, table_schema_js_1.isExpiredRow)(existing, (0, clock_js_1.nowSeconds)());
+}
+async function readExisting(context, key) {
+    const existing = await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.get({
+        TableName: context.tableName,
+        Key: key,
+        ConsistentRead: true,
+        ProjectionExpression: '#c, #r, #ttl, #v.#loc, #v.#s3k',
+        ExpressionAttributeNames: {
+            '#c': 'createdAt',
+            '#r': exports.REVISION_ATTRIBUTE,
+            '#ttl': 'ttl',
+            '#v': 'value',
+            '#loc': 'location',
+            '#s3k': 's3Key',
+        },
+    }, request), context.retry);
+    return existingFrom(existing.Item);
+}
+function existingFrom(item) {
+    return {
+        exists: item !== undefined,
+        createdAt: item?.createdAt,
+        ttl: item?.ttl,
+        value: item?.value,
+        revision: item?.[exports.REVISION_ATTRIBUTE],
+    };
+}
+function parseStoreRow(raw) {
+    (0, table_schema_js_1.assertReadableRow)(raw, 'store item');
+    if (!Array.isArray(raw.namespace) || typeof raw.key !== 'string')
+        return undefined;
+    const record = raw;
+    const consistent = record.PK === partitionKey(record.namespace) &&
+        record.SK === sortKey(record.namespace, record.key);
+    return consistent ? record : undefined;
+}
+function parseWholeStoreRow(raw) {
+    const record = parseStoreRow(raw);
+    if (record === undefined)
+        return undefined;
+    const stamped = typeof record.createdAt === 'string' && typeof record.updatedAt === 'string';
+    return stamped ? record : undefined;
+}
+async function buildStoreRow(context, address, value, options) {
+    const { namespace, key } = address;
+    const pk = partitionKey(namespace);
+    const sk = sortKey(namespace, key);
+    const rev = options.rev ?? (0, node_crypto_1.randomUUID)();
+    const descriptor = await (0, codec_js_1.encodePayload)(value, (0, codec_js_1.codecDepsOf)(context), {
+        keyParts: [...namespace, key],
+        objectId: rev,
+        row: { pk, sk },
+    });
+    const record = {
+        PK: pk,
+        SK: sk,
+        v: table_schema_js_1.ROW_FORMAT_VERSION,
+        namespace,
+        key,
+        value: descriptor,
+        createdAt: options.createdAt,
+        updatedAt: options.updatedAt,
+        rev,
+    };
+    if (options.embeddings)
+        record.embeddings = options.embeddings;
+    if (options.ttlTimestamp !== undefined)
+        record.ttl = options.ttlTimestamp;
+    return record;
+}
+async function readStoreItem(context, record, signal) {
+    const value = await (0, codec_js_1.decodePayload)(record.value, (0, codec_js_1.codecDepsOf)(context, signal), [...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 → cjs/store}/internal/semantic-search.d.ts

@@ -7,8 +7,8 @@
  * model returns is held to the configured dimension.
  */
 import type { IndexConfig } from '@langchain/langgraph-checkpoint';
-import type { JsonValue } from './filter';
-import type { StoreContext } from './setup';
+import type { JsonValue } from './filter.js';
+import type { StoreContext } from './setup.js';
 /**
  * Cosine similarity of two vectors.
  *

package/dist/cjs/store/internal/semantic-search.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cosineSimilarity = cosineSimilarity;
+exports.extractTexts = extractTexts;
+exports.extractText = extractText;
+exports.assertVectorDims = assertVectorDims;
+exports.embedValues = embedValues;
+exports.embedValue = embedValue;
+exports.embedPassages = embedPassages;
+exports.tokenizePath = tokenizePath;
+exports.getTextAtPath = getTextAtPath;
+const errors_js_1 = require("../../shared/errors/errors.js");
+const EMBED_BATCH_SIZE = 100;
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+function extractTexts(value, fields) {
+    return fields.flatMap((field) => getTextAtPath(value, field)).filter((text) => text.length > 0);
+}
+function extractText(value, fields) {
+    return extractTexts(value, fields).join(' ');
+}
+function assertVectorDims(index, vector, what) {
+    const dims = index.dims;
+    if (!Number.isInteger(dims) || dims <= 0 || vector.length === dims)
+        return;
+    throw (0, errors_js_1.validationError)(`index.embeddings returned a ${vector.length}-dimensional ${what} vector but index.dims ` +
+        `is ${dims}; the embeddings model does not match the configured index`, 'index.dims');
+}
+async function embedValues(context, values, fieldsOverride) {
+    const index = context.index;
+    if (!index)
+        return values.map(() => undefined);
+    const fields = fieldsOverride ?? index.fields ?? ['$'];
+    const pending = [];
+    values.forEach((value, position) => {
+        const text = extractText(value, fields);
+        if (text.length > 0)
+            pending.push({ text, position });
+    });
+    const vectors = values.map(() => undefined);
+    for (let start = 0; start < pending.length; start += EMBED_BATCH_SIZE) {
+        const batch = pending.slice(start, start + EMBED_BATCH_SIZE);
+        const embedded = await index.embeddings.embedDocuments(batch.map((entry) => entry.text));
+        batch.forEach((entry, i) => {
+            assertVectorDims(index, embedded[i], 'document');
+            vectors[entry.position] = embedded[i];
+        });
+    }
+    return vectors;
+}
+async function embedValue(context, value, fieldsOverride) {
+    return (await embedValues(context, [value], fieldsOverride))[0];
+}
+async function embedPassages(context, value, fieldsOverride) {
+    const index = context.index;
+    if (!index)
+        return undefined;
+    const texts = extractTexts(value, fieldsOverride ?? index.fields ?? ['$']);
+    if (texts.length === 0)
+        return undefined;
+    const vectors = [];
+    for (let start = 0; start < texts.length; start += EMBED_BATCH_SIZE) {
+        const embedded = await index.embeddings.embedDocuments(texts.slice(start, start + EMBED_BATCH_SIZE));
+        for (const vector of embedded) {
+            assertVectorDims(index, vector, 'document');
+            vectors.push(vector);
+        }
+    }
+    return vectors;
+}
+function prettyText(value) {
+    let text;
+    try {
+        text = JSON.stringify(value, null, 2);
+    }
+    catch {
+        return [];
+    }
+    return text === undefined ? [] : [text];
+}
+function isScalar(value) {
+    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+}
+function leafText(value) {
+    if (isScalar(value))
+        return [String(value)];
+    if (value === null)
+        return [];
+    return prettyText(value);
+}
+function scanGroup(path, start, open, close) {
+    let depth = 1;
+    let i = start;
+    while (i < path.length && depth > 0) {
+        if (path[i] === open)
+            depth += 1;
+        else if (path[i] === close)
+            depth -= 1;
+        i += 1;
+    }
+    return i;
+}
+function tokenizePath(path) {
+    const tokens = [];
+    let current = '';
+    const flush = () => {
+        if (current.length > 0)
+            tokens.push(current);
+        current = '';
+    };
+    let i = 0;
+    while (i < path.length) {
+        const char = path[i];
+        if (char === '[' || char === '{') {
+            flush();
+            const end = scanGroup(path, i + 1, char, char === '[' ? ']' : '}');
+            tokens.push(path.slice(i, end));
+            i = end;
+            continue;
+        }
+        if (char === '.')
+            flush();
+        else
+            current += char;
+        i += 1;
+    }
+    flush();
+    return tokens;
+}
+function groupFieldText(value, field) {
+    let current = value;
+    for (const token of tokenizePath(field)) {
+        if (current !== null && typeof current === 'object' && token in current) {
+            current = current[token];
+        }
+        else {
+            return [];
+        }
+    }
+    return isScalar(current) ? [String(current)] : prettyText(current);
+}
+function indexText(value, token, tokens, pos) {
+    if (!Array.isArray(value))
+        return [];
+    const index = token.slice(1, -1);
+    if (index === '*')
+        return value.flatMap((item) => extract(item, tokens, pos + 1));
+    let idx = Number.parseInt(index, 10);
+    if (Number.isNaN(idx))
+        return [];
+    if (idx < 0)
+        idx = value.length + idx;
+    return idx >= 0 && idx < value.length ? extract(value[idx], tokens, pos + 1) : [];
+}
+function groupText(value, token) {
+    if (typeof value !== 'object' || value === null)
+        return [];
+    const results = [];
+    for (const field of token.slice(1, -1).split(',')) {
+        const trimmed = field.trim();
+        if (tokenizePath(trimmed).length > 0)
+            results.push(...groupFieldText(value, trimmed));
+    }
+    return results;
+}
+function wildcardText(value, tokens, pos) {
+    if (Array.isArray(value))
+        return value.flatMap((item) => extract(item, tokens, pos + 1));
+    if (typeof value === 'object' && value !== null) {
+        return Object.values(value).flatMap((item) => extract(item, tokens, pos + 1));
+    }
+    return [];
+}
+function memberText(value, token, tokens, pos) {
+    if (typeof value !== 'object' || value === null || !(token in value))
+        return [];
+    return extract(value[token], tokens, pos + 1);
+}
+function extract(value, tokens, pos) {
+    if (pos >= tokens.length)
+        return leafText(value);
+    const token = tokens[pos];
+    if (token.startsWith('[') && token.endsWith(']'))
+        return indexText(value, token, tokens, pos);
+    const results = pos === 0 && token === '$' ? prettyText(value) : [];
+    if (token.startsWith('{') && token.endsWith('}'))
+        results.push(...groupText(value, token));
+    else if (token === '*')
+        results.push(...wildcardText(value, tokens, pos));
+    else
+        results.push(...memberText(value, token, tokens, pos));
+    return results;
+}
+function getTextAtPath(value, path) {
+    if (path === '' || path === '$')
+        return prettyText(value);
+    return extract(value, tokenizePath(path), 0);
+}

package/dist/{store → cjs/store}/internal/setup.d.ts

@@ -10,9 +10,9 @@
  * defaults filled in.
  */
 import type { IndexConfig, SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import { type AdapterCore, type AdapterShell } from '../../shared/adapter';
-import type { DynamoDBStoreOptions } from '../types';
-import { type VectorBackend, type VectorScoreDirection } from '../vector-backend';
+import { type AdapterCore, type AdapterShell } from '../../shared/adapter.js';
+import type { DynamoDBStoreOptions } from '../types.js';
+import { type VectorBackend, type VectorScoreDirection } from '../vector-backend.js';
 /** Default cap on candidates the in-DB semantic ranker will score. */
 export declare const DEFAULT_MAX_SEARCH_CANDIDATES = 1000;
 /**
@@ -36,6 +36,7 @@ export interface StoreContext extends AdapterCore {
     vectorScoreDirection: VectorScoreDirection;
     maxSearchCandidates: number;
     maxScanItems: number;
+    maxIterations: number;
 }
 /** Result of wiring up a store from its options. */
 export interface StoreSetup {
@@ -60,20 +61,14 @@ export interface StoreSetup {
  */
 export declare function setUpStore(options: DynamoDBStoreOptions): StoreSetup;
 /**
- * The keys of each store option bag, exhaustive in both directions:
- * `allKeysOf<T>` makes omitting or inventing one a compile error, so a list
- * cannot rot away from the type it guards. They live with the feature because
- * the types they are checked against do; `shared/` knows no feature.
+ * The keys of the store's constructor options, exhaustive in both directions:
+ * `allKeysOf<T>` makes omitting or inventing one a compile error, so the list
+ * cannot rot away from the type it guards. It lives with the feature because
+ * the type it is checked against does; `shared/` knows no feature. `search`'s
+ * and `listNamespaces`' options have no list: LangGraph defines them, so a key
+ * it adds is ignored rather than refused (decision record 28).
  */
 export declare const STORE_KEYS: readonly string[];
-/** See {@link STORE_KEYS}. */
-export declare const STORE_SEARCH_KEYS: readonly string[];
-/**
- * See {@link STORE_KEYS}. `ListNamespacesOptions` is pinned equal to
- * `BaseStore.listNamespaces`' own parameter type, so this list is checked
- * against upstream's options through it.
- */
-export declare const STORE_LIST_NAMESPACES_KEYS: readonly string[];
 /**
  * Validate the store's own options at construction; the shared ones are
  * `openAdapter`'s, which checks them before these.

package/dist/cjs/store/internal/setup.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STORE_KEYS = exports.MAX_SCAN_ITEMS = exports.MAX_SEARCH_CANDIDATES = exports.DEFAULT_MAX_SEARCH_CANDIDATES = void 0;
+exports.setUpStore = setUpStore;
+exports.assertStoreOptions = assertStoreOptions;
+const adapter_js_1 = require("../../shared/adapter.js");
+const json_serde_js_1 = require("../../shared/codec/json-serde.js");
+const paginate_js_1 = require("../../shared/dynamodb/paginate.js");
+const errors_js_1 = require("../../shared/errors/errors.js");
+const collaborators_js_1 = require("../../shared/validation/collaborators.js");
+const option_shape_js_1 = require("../../shared/validation/option-shape.js");
+const primitives_js_1 = require("../../shared/validation/primitives.js");
+const vector_backend_js_1 = require("../vector-backend.js");
+exports.DEFAULT_MAX_SEARCH_CANDIDATES = 1000;
+exports.MAX_SEARCH_CANDIDATES = 100_000;
+exports.MAX_SCAN_ITEMS = 1_000_000;
+function setUpStore(options) {
+    (0, option_shape_js_1.assertShape)(options, exports.STORE_KEYS, 'options');
+    const shell = (0, adapter_js_1.openAdapter)(options, 'store', {
+        options: () => assertStoreOptions(options),
+        collaborators: () => {
+            if (options.vectorBackend !== undefined) {
+                (0, collaborators_js_1.assertMembers)(options.vectorBackend, collaborators_js_1.VECTOR_BACKEND_MEMBERS, 'vectorBackend');
+            }
+        },
+    });
+    return {
+        shell,
+        context: {
+            ...shell.core,
+            serde: options.serde ?? json_serde_js_1.JSON_SERDE,
+            index: options.index,
+            vectorBackend: options.vectorBackend,
+            vectorScoreDirection: options.vectorScoreDirection ?? 'relevance',
+            maxSearchCandidates: options.maxSearchCandidates ?? exports.DEFAULT_MAX_SEARCH_CANDIDATES,
+            maxScanItems: options.maxScanItems ?? paginate_js_1.MAX_TOTAL_ROWS_IN_MEMORY,
+            maxIterations: options.maxIterations ?? paginate_js_1.MAX_LOOP_ITERATIONS,
+        },
+    };
+}
+exports.STORE_KEYS = (0, option_shape_js_1.allKeysOf)({
+    tableName: 'tableName',
+    client: 'client',
+    clientConfig: 'clientConfig',
+    createClient: 'createClient',
+    ttl: 'ttl',
+    logger: 'logger',
+    retry: 'retry',
+    readConcurrency: 'readConcurrency',
+    compression: 'compression',
+    s3: 's3',
+    serde: 'serde',
+    index: 'index',
+    vectorBackend: 'vectorBackend',
+    maxSearchCandidates: 'maxSearchCandidates',
+    maxScanItems: 'maxScanItems',
+    maxIterations: 'maxIterations',
+    vectorScoreDirection: 'vectorScoreDirection',
+});
+const INDEX_KEYS = (0, option_shape_js_1.allKeysOf)({
+    dims: 'dims',
+    embeddings: 'embeddings',
+    fields: 'fields',
+});
+function assertUsableIndex(index) {
+    if (index === undefined)
+        return;
+    (0, option_shape_js_1.assertShape)(index, INDEX_KEYS, 'index');
+    (0, collaborators_js_1.assertMembers)(index.embeddings, collaborators_js_1.EMBEDDINGS_MEMBERS, 'index.embeddings');
+    if (index.fields !== undefined)
+        (0, primitives_js_1.assertStringArray)(index.fields, 'index.fields');
+}
+function assertScoreDirection(direction) {
+    if (direction === undefined || vector_backend_js_1.VECTOR_SCORE_DIRECTIONS.includes(direction))
+        return;
+    throw (0, errors_js_1.validationError)(`vectorScoreDirection must be one of ${vector_backend_js_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');
+}
+function assertLimits(options) {
+    if (options.maxScanItems !== undefined) {
+        (0, primitives_js_1.assertInteger)(options.maxScanItems, 'maxScanItems', { min: 1, max: exports.MAX_SCAN_ITEMS });
+    }
+    if (options.maxSearchCandidates !== undefined) {
+        (0, primitives_js_1.assertInteger)(options.maxSearchCandidates, 'maxSearchCandidates', {
+            min: 1,
+            max: exports.MAX_SEARCH_CANDIDATES,
+        });
+    }
+    if (options.maxIterations !== undefined && options.maxIterations !== Infinity) {
+        (0, primitives_js_1.assertInteger)(options.maxIterations, 'maxIterations', { min: 1 });
+    }
+}
+function assertStoreOptions(options) {
+    assertLimits(options);
+    if (options.vectorBackend && !options.index) {
+        throw (0, errors_js_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 → cjs/store}/internal/table-search.d.ts

@@ -8,8 +8,8 @@
  * last. How far the read goes before it can stop is decided here.
  */
 import type { Item, SearchItem } from '@langchain/langgraph-checkpoint';
-import type { ParsedSearch } from './parse';
-import type { StoreContext } from './setup';
+import type { ParsedSearch } from './parse.js';
+import type { StoreContext } from './setup.js';
 /**
  * How far a collection must go. A plain page is complete once `need`
  * (`offset + limit`) matching items are in hand, so rows past it are never
@@ -40,9 +40,9 @@ export type CollectBound = {
  *
  * Throws: `VALIDATION` naming `maxSearchCandidates` before any decode when a
  * semantic collection exceeds `cap`; `RESULT_TRUNCATED` when
- * `maxScanItems` is reached while rows remain — a search never silently answers
- * from part of the table; `ABORTED` when the signal fires between pages;
- * whatever a decode throws for a corrupt or unreadable row.
+ * `maxScanItems` or `maxIterations` is reached while rows remain — a search
+ * never silently answers from part of the table; `ABORTED` when the signal
+ * fires between pages; whatever a decode throws for a corrupt or unreadable row.
  *
  * Guarantees: a page closes the paginator as soon as it is full, so a namespace
  * far larger than the page costs neither a full decode nor a truncation error.

package/dist/cjs/store/internal/table-search.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectCandidates = collectCandidates;
+exports.rankInMemory = rankInMemory;
+const clock_js_1 = require("../../shared/clock.js");
+const concurrency_js_1 = require("../../shared/concurrency.js");
+const paginate_js_1 = require("../../shared/dynamodb/paginate.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const errors_js_1 = require("../../shared/errors/errors.js");
+const filter_js_1 = require("./filter.js");
+const get_item_js_1 = require("./get-item.js");
+const rows_js_1 = require("./rows.js");
+const semantic_search_js_1 = require("./semantic-search.js");
+function storedVectors(record) {
+    if (record.embeddings)
+        return record.embeddings;
+    return record.embedding ? [record.embedding] : undefined;
+}
+function candidateSource(context, search, signal, now) {
+    return search.namespacePrefix.length > 0
+        ? (0, paginate_js_1.paginateQuery)({
+            retry: (0, retry_js_1.retryFor)(context, signal),
+            signal,
+            client: context.client,
+            params: (0, table_schema_js_1.withoutExpired)((0, rows_js_1.scopedQuery)(context.tableName, search.namespacePrefix), now),
+            maxItems: context.maxScanItems,
+            maxIterations: context.maxIterations,
+        })
+        : (0, paginate_js_1.paginateScan)({
+            retry: (0, retry_js_1.retryFor)(context, signal),
+            signal,
+            client: context.client,
+            params: (0, table_schema_js_1.withoutExpired)((0, rows_js_1.storeScan)(context.tableName), now),
+            maxItems: context.maxScanItems,
+            maxIterations: context.maxIterations,
+        });
+}
+function liveRow(raw, search, now) {
+    const record = (0, rows_js_1.parseWholeStoreRow)(raw);
+    if (!record || (0, table_schema_js_1.isExpiredRow)(record, now))
+        return undefined;
+    return (0, rows_js_1.namespaceMatchesPrefix)(record.namespace, search.namespacePrefix) ? record : undefined;
+}
+async function flush(context, search, state, signal) {
+    if (state.pending.length === 0)
+        return;
+    const batch = state.pending;
+    state.pending = [];
+    const reads = await (0, concurrency_js_1.mapWithConcurrency)(batch, context.readConcurrency ?? concurrency_js_1.DEFAULT_READ_CONCURRENCY, (record) => (0, get_item_js_1.readCandidate)(context, record, signal));
+    for (const read of reads) {
+        if (read !== undefined && (0, filter_js_1.passesFilter)(read.item, search.filter)) {
+            state.collected.push({ item: read.item, embeddings: storedVectors(read.row) });
+        }
+    }
+}
+function batchSize(search, need, collected, limit) {
+    return search.filter === undefined ? Math.min(limit, need - collected) : limit;
+}
+function tooManyCandidates(count, cap) {
+    return (0, errors_js_1.validationError)(`Semantic search candidate set (${count}) exceeds maxSearchCandidates (${cap}); ` +
+        'use a dedicated VectorBackend for large corpora', 'maxSearchCandidates');
+}
+async function collectCandidates(context, search, bound, signal) {
+    const now = (0, clock_js_1.nowSeconds)();
+    const limit = context.readConcurrency ?? concurrency_js_1.DEFAULT_READ_CONCURRENCY;
+    const state = { pending: [], collected: [] };
+    for await (const raw of candidateSource(context, search, signal, now)) {
+        const record = liveRow(raw, search, 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(search, bound.need, state.collected.length, limit)) {
+            continue;
+        }
+        await flush(context, search, state, signal);
+        if (state.collected.length >= bound.need)
+            return state.collected;
+    }
+    await flush(context, search, state, signal);
+    return state.collected;
+}
+const UNSCORED_RANK = -2;
+function bestScore(vectors, queryVector) {
+    let best;
+    for (const vector of vectors) {
+        if (vector.length !== queryVector.length)
+            continue;
+        const score = (0, semantic_search_js_1.cosineSimilarity)(queryVector, vector);
+        if (best === undefined || score > best)
+            best = score;
+    }
+    return best;
+}
+function isDimensionMismatch(candidate, queryVector) {
+    const vectors = candidate.embeddings;
+    return (vectors !== undefined &&
+        vectors.length > 0 &&
+        vectors.every((vector) => vector.length !== queryVector.length));
+}
+function rankInMemory(candidates, queryVector, maxCandidates, onDimensionMismatch) {
+    if (candidates.length > maxCandidates) {
+        throw (0, errors_js_1.validationError)(`Semantic search candidate set (${candidates.length}) exceeds maxSearchCandidates ` +
+            `(${maxCandidates}); use a dedicated VectorBackend for large corpora`, 'maxSearchCandidates');
+    }
+    const mismatched = candidates.filter((candidate) => isDimensionMismatch(candidate, queryVector)).length;
+    if (mismatched > 0)
+        onDimensionMismatch?.(mismatched);
+    return candidates
+        .map(({ item, embeddings }) => ({
+        ...item,
+        score: embeddings ? bestScore(embeddings, queryVector) : undefined,
+    }))
+        .sort((a, b) => rankValue(b) - rankValue(a));
+}
+function rankValue(item) {
+    return item.score ?? UNSCORED_RANK;
+}