@farukada/aws-langgraph-dynamodb-ts 0.2.2 → 0.3.1

package/dist/store/actions/search.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchItems = searchItems;
+const paginate_1 = require("../../shared/dynamodb/paginate");
+const scan_1 = require("../../shared/dynamodb/scan");
+const filter_1 = require("../internal/filter");
+const item_mapper_1 = require("../internal/item-mapper");
+const keys_1 = require("../internal/keys");
+const query_1 = require("../internal/query");
+const ranker_1 = require("../internal/ranker");
+const validation_1 = require("../internal/validation");
+const get_1 = require("./get");
+const DEFAULT_LIMIT = 10;
+function passesFilter(item, op) {
+    if (!op.filter)
+        return true;
+    return (0, filter_1.matchesStoreFilter)(item.value, op.filter);
+}
+async function collectCandidates(context, op) {
+    const source = op.namespacePrefix.length > 0
+        ? (0, paginate_1.paginateQuery)({
+            client: context.client,
+            params: (0, query_1.scopedQuery)(context.tableName, op.namespacePrefix),
+        })
+        : (0, scan_1.paginateScan)({ client: context.client, params: (0, query_1.storeScan)(context.tableName) });
+    const candidates = [];
+    for await (const raw of source) {
+        const record = (0, item_mapper_1.narrowStoreRecord)(raw);
+        if (!record)
+            continue;
+        if (!(0, keys_1.namespaceMatchesPrefix)(record.namespace, op.namespacePrefix))
+            continue;
+        const item = await (0, item_mapper_1.readStoreItem)(context, record);
+        if (!passesFilter(item, op))
+            continue;
+        candidates.push({ item, embedding: record.embedding });
+    }
+    return candidates;
+}
+async function searchViaBackend(context, backend, index, op, topK) {
+    const queryVector = await index.embeddings.embedQuery(op.query);
+    const matches = await backend.query(op.namespacePrefix, queryVector, topK);
+    const results = [];
+    for (const match of matches) {
+        const item = await (0, get_1.getItem)(context, match.namespace, match.key);
+        if (item && passesFilter(item, op))
+            results.push({ ...item, score: match.score });
+    }
+    return results;
+}
+/**
+ * Search items under a namespace prefix: metadata filtering plus optional
+ * semantic ranking. A non-empty prefix uses a native Query; an empty prefix
+ * falls back to a (filtered) Scan. Semantic ranking uses the configured
+ * VectorBackend when present, else an in-memory cosine ranking (capped).
+ */
+async function searchItems(context, op) {
+    const offset = op.offset ?? 0;
+    const limit = op.limit ?? DEFAULT_LIMIT;
+    (0, validation_1.validatePaging)(offset, limit);
+    if (op.query && context.index && context.vectorBackend) {
+        const ranked = await searchViaBackend(context, context.vectorBackend, context.index, op, offset + limit);
+        return ranked.slice(offset, offset + limit);
+    }
+    const candidates = await collectCandidates(context, op);
+    if (!op.query || !context.index) {
+        return candidates.map(({ item }) => ({ ...item })).slice(offset, offset + limit);
+    }
+    const queryVector = await context.index.embeddings.embedQuery(op.query);
+    return (0, ranker_1.rankInMemory)(candidates, queryVector, context.maxSearchCandidates).slice(offset, offset + limit);
+}
+//# sourceMappingURL=search.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../src/store/actions/search.ts"],"names":[],"mappings":";;AA2EA,kCA0BC;AA9FD,6DAA+D;AAC/D,qDAA0D;AAC1D,+CAAwE;AACxE,yDAA2E;AAC3E,2CAA0D;AAC1D,6CAA2D;AAC3D,+CAAsE;AAEtE,uDAAwD;AAExD,+BAAgC;AAEhC,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB,SAAS,YAAY,CAAC,IAAU,EAAE,EAAmB;IACnD,IAAI,CAAC,EAAE,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO,IAAA,2BAAkB,EACvB,IAAI,CAAC,KAAkC,EACvC,EAAE,CAAC,MAAmC,CACvC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,iBAAiB,CAC9B,OAAqB,EACrB,EAAmB;IAEnB,MAAM,MAAM,GACV,EAAE,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC;QAC3B,CAAC,CAAC,IAAA,wBAAa,EAAC;YACZ,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,MAAM,EAAE,IAAA,mBAAW,EAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,eAAe,CAAC;SAC3D,CAAC;QACJ,CAAC,CAAC,IAAA,mBAAY,EAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAA,iBAAS,EAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACrF,MAAM,UAAU,GAAoB,EAAE,CAAC;IACvC,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAA,+BAAiB,EAAC,GAAG,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,IAAI,CAAC,IAAA,6BAAsB,EAAC,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC,eAAe,CAAC;YAAE,SAAS;QAC5E,MAAM,IAAI,GAAG,MAAM,IAAA,2BAAa,EAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAClD,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC;YAAE,SAAS;QACtC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,KAAK,UAAU,gBAAgB,CAC7B,OAAqB,EACrB,OAAsB,EACtB,KAAkB,EAClB,EAAmB,EACnB,IAAY;IAEZ,MAAM,WAAW,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC,KAAe,CAAC,CAAC;IAC1E,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,eAAe,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;IAC3E,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,MAAM,IAAA,aAAO,EAAC,OAAO,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAChE,IAAI,IAAI,IAAI,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,WAAW,CAC/B,OAAqB,EACrB,EAAmB;IAEnB,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,IAAI,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,IAAI,aAAa,CAAC;IACxC,IAAA,2BAAc,EAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC9B,IAAI,EAAE,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;QACvD,MAAM,MAAM,GAAG,MAAM,gBAAgB,CACnC,OAAO,EACP,OAAO,CAAC,aAAa,EACrB,OAAO,CAAC,KAAK,EACb,EAAE,EACF,MAAM,GAAG,KAAK,CACf,CAAC;QACF,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC;IAC9C,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,iBAAiB,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACxD,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAChC,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IACxE,OAAO,IAAA,qBAAY,EAAC,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC,KAAK,CAC7E,MAAM,EACN,MAAM,GAAG,KAAK,CACf,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,10 @@
+/** A JSON value stored in an item or supplied in a filter. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * True when `value` satisfies every field condition in `filter`. A plain value
+ * is exact-match ($eq); an operator object ({ $gt: 4 }) applies comparisons.
+ */
+export declare function matchesStoreFilter(value: Record<string, JsonValue>, filter: Record<string, JsonValue>): boolean;
+//# sourceMappingURL=filter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/store/internal/filter.ts"],"names":[],"mappings":"AAIA,8DAA8D;AAC9D,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AA6BjC;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAChC,OAAO,CAIT"}

package/dist/store/internal/filter.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchesStoreFilter = matchesStoreFilter;
+const node_util_1 = require("node:util");
+const errors_1 = require("../../shared/errors/errors");
+const COMPARATORS = {
+    $eq: (actual, expected) => (0, node_util_1.isDeepStrictEqual)(actual, expected),
+    $ne: (actual, expected) => !(0, node_util_1.isDeepStrictEqual)(actual, expected),
+    $gt: (actual, expected) => actual > expected,
+    $gte: (actual, expected) => actual >= expected,
+    $lt: (actual, expected) => actual < expected,
+    $lte: (actual, expected) => actual <= expected,
+};
+function isOperatorObject(condition) {
+    return (typeof condition === 'object' &&
+        condition !== null &&
+        !Array.isArray(condition) &&
+        Object.keys(condition).every((key) => key.startsWith('$')));
+}
+function matchesCondition(actual, condition) {
+    if (!isOperatorObject(condition))
+        return (0, node_util_1.isDeepStrictEqual)(actual, condition);
+    return Object.entries(condition).every(([operator, expected]) => {
+        const comparator = COMPARATORS[operator];
+        if (!comparator)
+            throw new errors_1.ValidationError(`Unknown filter operator "${operator}"`, 'filter');
+        return comparator(actual, expected);
+    });
+}
+/**
+ * True when `value` satisfies every field condition in `filter`. A plain value
+ * is exact-match ($eq); an operator object ({ $gt: 4 }) applies comparisons.
+ */
+function matchesStoreFilter(value, filter) {
+    return Object.entries(filter).every(([field, condition]) => matchesCondition(value[field], condition));
+}
+//# sourceMappingURL=filter.js.map

package/dist/store/internal/filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../../src/store/internal/filter.ts"],"names":[],"mappings":";;AA4CA,gDAOC;AAnDD,yCAA8C;AAE9C,uDAA6D;AAW7D,MAAM,WAAW,GAAwE;IACvF,GAAG,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,IAAA,6BAAiB,EAAC,MAAM,EAAE,QAAQ,CAAC;IAC9D,GAAG,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAA,6BAAiB,EAAC,MAAM,EAAE,QAAQ,CAAC;IAC/D,GAAG,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAE,MAAiB,GAAI,QAAmB;IACpE,IAAI,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAE,MAAiB,IAAK,QAAmB;IACtE,GAAG,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAE,MAAiB,GAAI,QAAmB;IACpE,IAAI,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAE,MAAiB,IAAK,QAAmB;CACvE,CAAC;AAEF,SAAS,gBAAgB,CAAC,SAAoB;IAC5C,OAAO,CACL,OAAO,SAAS,KAAK,QAAQ;QAC7B,SAAS,KAAK,IAAI;QAClB,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;QACzB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAC3D,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAiB,EAAE,SAAoB;IAC/D,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC;QAAE,OAAO,IAAA,6BAAiB,EAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC9E,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE;QAC9D,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QACzC,IAAI,CAAC,UAAU;YAAE,MAAM,IAAI,wBAAe,CAAC,4BAA4B,QAAQ,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC9F,OAAO,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,SAAgB,kBAAkB,CAChC,KAAgC,EAChC,MAAiC;IAEjC,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,CACzD,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAC1C,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,22 @@
+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 canonical items under `prefix`, recomputing each embedding. A failed
+ * embedding rejects the whole reconcile by design: silently skipping an item
+ * would drop it from the live set, after which {@link selectOrphans} would prune
+ * its still-valid backend vector. Fail-fast keeps the backend from losing data.
+ */
+export declare function collectReconcileTargets(context: StoreContext, prefix: string[]): 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>;
+//# sourceMappingURL=index-reconcile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-reconcile.d.ts","sourceRoot":"","sources":["../../../src/store/internal/index-reconcile.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAMlE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAK5C,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACjC;AAOD;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,eAAe,EAAE,CAAC,CAc5B;AAED,6EAA6E;AAC7E,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,eAAe,EAAE,GACzB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,SAAS,EAAE,CAG5F;AAED,8EAA8E;AAC9E,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,EAAE,EAChB,IAAI,EAAE,eAAe,EAAE,GACtB,OAAO,CAAC,MAAM,CAAC,CAUjB"}

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

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectReconcileTargets = collectReconcileTargets;
+exports.pushEmbeddings = pushEmbeddings;
+exports.selectOrphans = selectOrphans;
+exports.pruneOrphans = pruneOrphans;
+const paginate_1 = require("../../shared/dynamodb/paginate");
+const item_mapper_1 = require("./item-mapper");
+const keys_1 = require("./keys");
+const query_1 = require("./query");
+const semantic_search_1 = require("./semantic-search");
+/** Separator joining namespace elements into a collision-free identity. */
+const REF_KEY_SEPARATOR = ' ';
+/** Stable identity for a (namespace, key) pair. */
+function refIdentity(namespace, key) {
+    return `${namespace.join(REF_KEY_SEPARATOR)}${REF_KEY_SEPARATOR}${key}`;
+}
+/**
+ * Enumerate canonical items under `prefix`, recomputing each embedding. A failed
+ * embedding rejects the whole reconcile by design: silently skipping an item
+ * would drop it from the live set, after which {@link selectOrphans} would prune
+ * its still-valid backend vector. Fail-fast keeps the backend from losing data.
+ */
+async function collectReconcileTargets(context, prefix) {
+    const targets = [];
+    const source = (0, paginate_1.paginateQuery)({
+        client: context.client,
+        params: (0, query_1.scopedQuery)(context.tableName, prefix),
+    });
+    for await (const raw of source) {
+        const record = raw;
+        if (!record.namespace || !(0, keys_1.namespaceMatchesPrefix)(record.namespace, prefix))
+            continue;
+        const item = await (0, item_mapper_1.readStoreItem)(context, record);
+        const embedding = await (0, semantic_search_1.embedValue)(context, item.value);
+        targets.push({ namespace: record.namespace, key: record.key, embedding });
+    }
+    return targets;
+}
+/** 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.map((target) => refIdentity(target.namespace, target.key)));
+    return backendRefs.filter((ref) => !liveKeys.has(refIdentity(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 orphans = selectOrphans(await backend.listKeys(prefix), live);
+    for (const ref of orphans) {
+        await backend.delete(ref.namespace, ref.key);
+    }
+    return orphans.length;
+}
+//# sourceMappingURL=index-reconcile.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-reconcile.js","sourceRoot":"","sources":["../../../src/store/internal/index-reconcile.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,11 @@
+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>;
+//# sourceMappingURL=index-sync.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-sync.d.ts","sourceRoot":"","sources":["../../../src/store/internal/index-sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,MAAM,EAAE,EACnB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,EAC/B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAWf"}

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

@@ -0,0 +1,26 @@
+"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,
+        });
+    }
+}
+//# sourceMappingURL=index-sync.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-sync.js","sourceRoot":"","sources":["../../../src/store/internal/index-sync.ts"],"names":[],"mappings":";;AAUA,0CAiBC;AAxBD;;;;;;GAMG;AACI,KAAK,UAAU,eAAe,CACnC,OAAsB,EACtB,SAAmB,EACnB,GAAW,EACX,SAA+B,EAC/B,MAAc;IAEd,IAAI,CAAC;QACH,IAAI,SAAS;YAAE,MAAM,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;;YAC1D,MAAM,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,sEAAsE,EAAE;YAClF,SAAS;YACT,GAAG;YACH,OAAO,EAAG,KAAe,CAAC,OAAO;SAClC,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,23 @@
+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`). Replaces an unchecked cast at
+ * the scan boundary, the one place rows are not written by this library.
+ */
+export declare function narrowStoreRecord(raw: DocItem): StoreItemRecord | undefined;
+/** Fields controlling a stored item's timestamps, embedding, and ttl. */
+export interface BuildItemOptions {
+    createdAt: string;
+    updatedAt: string;
+    embedding?: number[];
+    ttlTimestamp?: number;
+}
+/** 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>;
+//# sourceMappingURL=item-mapper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"item-mapper.d.ts","sourceRoot":"","sources":["../../../src/store/internal/item-mapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iCAAiC,CAAC;AAG5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAE3E;AAOD,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,iEAAiE;AACjE,wBAAsB,cAAc,CAClC,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,MAAM,EAAE,EACnB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAChC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAgB1B;AAED,+DAA+D;AAC/D,wBAAsB,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAYjG"}

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

@@ -0,0 +1,51 @@
+"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 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`). Replaces an unchecked cast at
+ * the scan boundary, the one place rows are not written by this library.
+ */
+function narrowStoreRecord(raw) {
+    return Array.isArray(raw.namespace) ? raw : 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, codec_1.encodePayload)(value, storeCodecDeps(context), {
+        keyParts: [...namespace, key],
+    });
+    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;
+    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));
+    return {
+        namespace: record.namespace,
+        key: record.key,
+        value,
+        createdAt: new Date(record.createdAt),
+        updatedAt: new Date(record.updatedAt),
+    };
+}
+//# sourceMappingURL=item-mapper.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"item-mapper.js","sourceRoot":"","sources":["../../../src/store/internal/item-mapper.ts"],"names":[],"mappings":";;AAcA,8CAEC;AAgBD,wCAsBC;AAGD,sCAYC;AAnED,oDAAwF;AAIxF,iCAA+C;AAG/C;;;;GAIG;AACH,SAAgB,iBAAiB,CAAC,GAAY;IAC5C,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAE,GAAuB,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7E,CAAC;AAED,sDAAsD;AACtD,SAAS,cAAc,CAAC,OAAqB;IAC3C,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;AAClG,CAAC;AAUD,iEAAiE;AAC1D,KAAK,UAAU,cAAc,CAClC,OAAqB,EACrB,SAAmB,EACnB,GAAW,EACX,KAAgC,EAChC,OAAyB;IAEzB,MAAM,UAAU,GAAG,MAAM,IAAA,qBAAa,EAAC,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE;QACrE,QAAQ,EAAE,CAAC,GAAG,SAAS,EAAE,GAAG,CAAC;KAC9B,CAAC,CAAC;IACH,MAAM,MAAM,GAAoB;QAC9B,EAAE,EAAE,IAAA,mBAAY,EAAC,SAAS,CAAC;QAC3B,EAAE,EAAE,IAAA,cAAO,EAAC,SAAS,EAAE,GAAG,CAAC;QAC3B,SAAS;QACT,GAAG;QACH,KAAK,EAAE,UAAU;QACjB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC;IACF,IAAI,OAAO,CAAC,SAAS;QAAE,MAAM,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAC5D,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,GAAG,OAAO,CAAC,YAAY,CAAC;IAC1E,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+DAA+D;AACxD,KAAK,UAAU,aAAa,CAAC,OAAqB,EAAE,MAAuB;IAChF,MAAM,KAAK,GAAG,MAAM,IAAA,qBAAa,EAC/B,MAAM,CAAC,KAAK,EACZ,cAAc,CAAC,OAAO,CAAC,CACxB,CAAC;IACF,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,KAAK;QACL,SAAS,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;QACrC,SAAS,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;KACtC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,18 @@
+/** Separator joining namespace elements (and the trailing key) in the sort key. */
+export declare const NAMESPACE_SEPARATOR = "#";
+/** Partition key for an item: the scope-root namespace 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;
+//# sourceMappingURL=keys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../src/store/internal/keys.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAExD;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAGtD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAGrF"}

package/dist/store/internal/keys.js

@@ -0,0 +1,36 @@
+"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 = '#';
+/** Partition key for an item: the scope-root namespace element. */
+function partitionKey(namespace) {
+    return 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);
+}
+//# sourceMappingURL=keys.js.map

package/dist/store/internal/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../src/store/internal/keys.ts"],"names":[],"mappings":";;;AAIA,oCAEC;AAGD,0BAEC;AAOD,sCAGC;AAMD,wDAGC;AA9BD,mFAAmF;AACtE,QAAA,mBAAmB,GAAG,GAAG,CAAC;AAEvC,mEAAmE;AACnE,SAAgB,YAAY,CAAC,SAAmB;IAC9C,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC;AAED,0EAA0E;AAC1E,SAAgB,OAAO,CAAC,SAAmB,EAAE,GAAW;IACtD,OAAO,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,2BAAmB,CAAC,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,SAAgB,aAAa,CAAC,MAAgB;IAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,2BAAmB,CAAC,GAAG,2BAAmB,EAAE,CAAC;AAC5F,CAAC;AAED;;;GAGG;AACH,SAAgB,sBAAsB,CAAC,SAAmB,EAAE,MAAgB;IAC1E,IAAI,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACnD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,OAAO,CAAC,CAAC;AACxE,CAAC"}

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

@@ -0,0 +1,12 @@
+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[];
+//# sourceMappingURL=namespace-match.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"namespace-match.d.ts","sourceRoot":"","sources":["../../../src/store/internal/namespace-match.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAQtE,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,cAAc,GAAG,OAAO,CAQtF;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAE9E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,cAAc,EAAE,GAAG,MAAM,EAAE,CASlE"}

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

@@ -0,0 +1,41 @@
+"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;
+}
+//# sourceMappingURL=namespace-match.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"namespace-match.js","sourceRoot":"","sources":["../../../src/store/internal/namespace-match.ts"],"names":[],"mappings":";;AASA,wCAQC;AAGD,sCAEC;AAOD,gCASC;AApCD,MAAM,QAAQ,GAAG,GAAG,CAAC;AAErB,SAAS,cAAc,CAAC,MAAgB,EAAE,IAAsB;IAC9D,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED,kFAAkF;AAClF,SAAgB,cAAc,CAAC,SAAmB,EAAE,SAAyB;IAC3E,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC;IACtC,IAAI,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACjD,MAAM,KAAK,GACT,SAAS,KAAK,QAAQ;QACpB,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC;QACjC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IACtD,OAAO,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,6EAA6E;AAC7E,SAAgB,aAAa,CAAC,SAAmB,EAAE,QAAiB;IAClE,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;AAC3E,CAAC;AAED;;;;GAIG;AACH,SAAgB,UAAU,CAAC,UAA6B;IACtD,MAAM,eAAe,GAAG,UAAU,EAAE,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC;IAC1F,IAAI,CAAC,eAAe;QAAE,OAAO,EAAE,CAAC;IAChC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,OAAO,IAAI,eAAe,CAAC,IAAI,EAAE,CAAC;QAC3C,IAAI,OAAO,KAAK,QAAQ;YAAE,MAAM;QAChC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

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

@@ -0,0 +1,6 @@
+import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
+/** Query input for a scoped prefix (PK = prefix[0], optional SK begins_with). */
+export declare function scopedQuery(tableName: string, prefix: string[]): QueryCommandInput;
+/** Scan input for the rootless case, filtered to store items only. */
+export declare function storeScan(tableName: string): ScanCommandInput;
+//# sourceMappingURL=query.d.ts.map

package/dist/store/internal/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/store/internal/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAIjF,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAgBlF;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAM7D"}

package/dist/store/internal/query.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scopedQuery = scopedQuery;
+exports.storeScan = storeScan;
+const keys_1 = require("./keys");
+/** Query input for a scoped prefix (PK = prefix[0], optional SK begins_with). */
+function scopedQuery(tableName, prefix) {
+    const skPrefix = (0, keys_1.sortKeyPrefix)(prefix);
+    if (skPrefix.length === 0) {
+        return {
+            TableName: tableName,
+            KeyConditionExpression: '#pk = :pk',
+            ExpressionAttributeNames: { '#pk': 'PK' },
+            ExpressionAttributeValues: { ':pk': (0, keys_1.partitionKey)(prefix) },
+        };
+    }
+    return {
+        TableName: tableName,
+        KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :skp)',
+        ExpressionAttributeNames: { '#pk': 'PK', '#sk': 'SK' },
+        ExpressionAttributeValues: { ':pk': (0, keys_1.partitionKey)(prefix), ':skp': skPrefix },
+    };
+}
+/** Scan input for the rootless case, filtered to store items only. */
+function storeScan(tableName) {
+    return {
+        TableName: tableName,
+        FilterExpression: 'attribute_exists(#ns)',
+        ExpressionAttributeNames: { '#ns': 'namespace' },
+    };
+}
+//# sourceMappingURL=query.js.map

package/dist/store/internal/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../../src/store/internal/query.ts"],"names":[],"mappings":";;AAKA,kCAgBC;AAGD,8BAMC;AA5BD,iCAAqD;AAErD,iFAAiF;AACjF,SAAgB,WAAW,CAAC,SAAiB,EAAE,MAAgB;IAC7D,MAAM,QAAQ,GAAG,IAAA,oBAAa,EAAC,MAAM,CAAC,CAAC;IACvC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,SAAS,EAAE,SAAS;YACpB,sBAAsB,EAAE,WAAW;YACnC,wBAAwB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;YACzC,yBAAyB,EAAE,EAAE,KAAK,EAAE,IAAA,mBAAY,EAAC,MAAM,CAAC,EAAE;SAC3D,CAAC;IACJ,CAAC;IACD,OAAO;QACL,SAAS,EAAE,SAAS;QACpB,sBAAsB,EAAE,sCAAsC;QAC9D,wBAAwB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE;QACtD,yBAAyB,EAAE,EAAE,KAAK,EAAE,IAAA,mBAAY,EAAC,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE;KAC7E,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,SAAgB,SAAS,CAAC,SAAiB;IACzC,OAAO;QACL,SAAS,EAAE,SAAS;QACpB,gBAAgB,EAAE,uBAAuB;QACzC,wBAAwB,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE;KACjD,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,13 @@
+import type { Item, SearchItem } from '@langchain/langgraph-checkpoint';
+/** A decoded item plus its stored embedding, awaiting ranking. */
+export interface RankCandidate {
+    item: Item;
+    embedding?: number[];
+}
+/**
+ * Rank candidates by cosine similarity to `queryVector`, descending. Throws a
+ * {@link ValidationError} when the candidate count exceeds `maxCandidates`
+ * (steer large corpora to an external VectorBackend).
+ */
+export declare function rankInMemory(candidates: RankCandidate[], queryVector: number[], maxCandidates: number): SearchItem[];
+//# sourceMappingURL=ranker.d.ts.map

package/dist/store/internal/ranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranker.d.ts","sourceRoot":"","sources":["../../../src/store/internal/ranker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAQxE,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,EAAE,EAC3B,WAAW,EAAE,MAAM,EAAE,EACrB,aAAa,EAAE,MAAM,GACpB,UAAU,EAAE,CAcd"}

package/dist/store/internal/ranker.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rankInMemory = rankInMemory;
+const errors_1 = require("../../shared/errors/errors");
+const semantic_search_1 = require("./semantic-search");
+/** Sort weight for an item without an embedding; below the −1 cosine minimum. */
+const UNSCORED_RANK = -2;
+/**
+ * Rank candidates by cosine similarity to `queryVector`, descending. Throws a
+ * {@link ValidationError} when the candidate count exceeds `maxCandidates`
+ * (steer large corpora to an external VectorBackend).
+ */
+function rankInMemory(candidates, queryVector, maxCandidates) {
+    if (candidates.length > maxCandidates) {
+        throw new errors_1.ValidationError(`Semantic search candidate set (${candidates.length}) exceeds maxSearchCandidates ` +
+            `(${maxCandidates}); use a dedicated VectorBackend for large corpora`, 'maxSearchCandidates');
+    }
+    return candidates
+        .map(({ item, embedding }) => ({
+        ...item,
+        score: embedding ? (0, semantic_search_1.cosineSimilarity)(queryVector, embedding) : undefined,
+    }))
+        .sort((a, b) => rankValue(b) - rankValue(a));
+}
+/** Sort weight: real cosine score, or a value below the cosine minimum for unscored items. */
+function rankValue(item) {
+    return item.score ?? UNSCORED_RANK;
+}
+//# sourceMappingURL=ranker.js.map

package/dist/store/internal/ranker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranker.js","sourceRoot":"","sources":["../../../src/store/internal/ranker.ts"],"names":[],"mappings":";;AAmBA,oCAkBC;AAnCD,uDAA6D;AAC7D,uDAAqD;AAErD,iFAAiF;AACjF,MAAM,aAAa,GAAG,CAAC,CAAC,CAAC;AAQzB;;;;GAIG;AACH,SAAgB,YAAY,CAC1B,UAA2B,EAC3B,WAAqB,EACrB,aAAqB;IAErB,IAAI,UAAU,CAAC,MAAM,GAAG,aAAa,EAAE,CAAC;QACtC,MAAM,IAAI,wBAAe,CACvB,kCAAkC,UAAU,CAAC,MAAM,gCAAgC;YACjF,IAAI,aAAa,oDAAoD,EACvE,qBAAqB,CACtB,CAAC;IACJ,CAAC;IACD,OAAO,UAAU;SACd,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;QAC7B,GAAG,IAAI;QACP,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,IAAA,kCAAgB,EAAC,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS;KACxE,CAAC,CAAC;SACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,8FAA8F;AAC9F,SAAS,SAAS,CAAC,IAAgB;IACjC,OAAO,IAAI,CAAC,KAAK,IAAI,aAAa,CAAC;AACrC,CAAC"}

package/dist/store/internal/semantic-search.d.ts

@@ -0,0 +1,13 @@
+import type { JsonValue } from './filter';
+import type { StoreContext } from './setup';
+/** Cosine similarity of two equal-length vectors; 0 for zero/mismatched vectors. */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/** Extract and join the indexable text of a value for the configured fields. */
+export declare function extractText(value: Record<string, JsonValue>, fields: string[]): string;
+/**
+ * Embed a value for indexing, or undefined when indexing is off or the text is
+ * empty. `fieldsOverride` (from a put's `index` option) takes precedence over
+ * the store's configured fields.
+ */
+export declare function embedValue(context: StoreContext, value: Record<string, JsonValue>, fieldsOverride?: string[]): Promise<number[] | undefined>;
+//# sourceMappingURL=semantic-search.d.ts.map