@farukada/aws-langgraph-dynamodb-ts 0.7.0 → 0.9.0

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

@@ -0,0 +1,33 @@
+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>;
+//# sourceMappingURL=overwrite-swap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overwrite-swap.d.ts","sourceRoot":"","sources":["../../../src/store/internal/overwrite-swap.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,KAAK,kBAAkB,EAAgB,MAAM,iBAAiB,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAc5C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAqB7B"}

package/dist/store/internal/overwrite-swap.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.putWithRevisionSwap = putWithRevisionSwap;
+const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
+const retry_1 = require("../../shared/dynamodb/retry");
+const read_existing_1 = require("./read-existing");
+/** Put the record, optionally pinned to the revision the caller observed. */
+async function put(context, record, observed) {
+    const guard = observed ? (0, conditional_put_1.revisionGuard)(conditional_put_1.REVISION_ATTRIBUTE, observed) : {};
+    await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: record, ...guard }));
+}
+/**
+ * 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.
+ */
+async function putWithRevisionSwap(context, record, existing) {
+    let observed = existing;
+    for (let attempt = 1; attempt <= conditional_put_1.OVERWRITE_CAS_MAX_ATTEMPTS; attempt++) {
+        const attempted = observed;
+        try {
+            await put(context, record, attempted);
+            return attempted;
+        }
+        catch (error) {
+            if (!(0, conditional_put_1.isConditionalCheckFailed)(error))
+                throw error;
+            observed = await (0, read_existing_1.readExisting)(context, record.PK, record.SK);
+            if (record.rev !== undefined && observed.revision === record.rev)
+                return attempted;
+            record.createdAt = observed.createdAt ?? record.createdAt;
+        }
+    }
+    context.logger.warn('store.put: compare-and-swap exhausted; overwriting unconditionally, which can orphan one ' +
+        'S3 object under a concurrent put (reclaimed by ensureS3LifecycleRule)', { namespace: record.namespace, key: record.key, attempts: conditional_put_1.OVERWRITE_CAS_MAX_ATTEMPTS });
+    await put(context, record);
+    return observed;
+}
+//# sourceMappingURL=overwrite-swap.js.map

package/dist/store/internal/overwrite-swap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overwrite-swap.js","sourceRoot":"","sources":["../../../src/store/internal/overwrite-swap.ts"],"names":[],"mappings":";;;AAAA,2EAK+C;AAC/C,uDAAgE;AAEhE,mDAAwE;AAGxE,6EAA6E;AAC7E,KAAK,UAAU,GAAG,CAChB,OAAqB,EACrB,MAAuB,EACvB,QAA6B;IAE7B,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAA,+BAAa,EAAC,oCAAkB,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1E,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC3B,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC,CAC7E,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACI,KAAK,8BACV,OAAqB,EACrB,MAAuB,EACvB,QAA4B;IAE5B,IAAI,QAAQ,GAAG,QAAQ,CAAC;IACxB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,4CAA0B,EAAE,OAAO,EAAE,EAAE,CAAC;QACvE,MAAM,SAAS,GAAG,QAAQ,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;YACtC,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,IAAA,0CAAwB,EAAC,KAA0B,CAAC;gBAAE,MAAM,KAAK,CAAC;YACvE,QAAQ,GAAG,MAAM,IAAA,4BAAY,EAAC,OAAO,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;YAC7D,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,IAAI,QAAQ,CAAC,QAAQ,KAAK,MAAM,CAAC,GAAG;gBAAE,OAAO,SAAS,CAAC;YACnF,MAAM,CAAC,SAAS,GAAG,QAAQ,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC;QAC5D,CAAC;IACH,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,IAAI,CACjB,2FAA2F;QACzF,uEAAuE,EACzE,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,4CAA0B,EAAE,CACvF,CAAC;IACF,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC3B,OAAO,QAAQ,CAAC;AAClB,CAAC"}

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

@@ -1,11 +1,27 @@
-import { type PayloadDescriptor } from '../../shared/codec/codec';
 import type { StoreItemRecord } from '../types';
+import type { ExistingRecordMeta } from './read-existing';
 import type { StoreContext } from './setup';
 /**
- * Put the record: on a definite failure, clean up *this* record's nonced S3
- * object; on an ambiguous retry-exhaustion failure, verify via
- * `writeLandedAt` before deleting anything — if it landed, clean up the
- * *previous* row's object instead, like the ordinary success path.
+ * Put the record and clean up whichever side is now dead.
+ *
+ * The compare-and-swap path runs **only when an offloader is configured**:
+ * without one there is no S3 object to orphan, so a plain last-write-wins put
+ * stays correct and costs no extra write capacity (DynamoDB charges for a
+ * failed conditional write too). With one, the swap is what lets this call
+ * delete exactly the payload it superseded rather than a descriptor a racer may
+ * already have replaced.
+ *
+ * Every failure reaching the catch arrives after at least one put was issued —
+ * `putWithRevisionSwap` only re-reads from inside its own catch — so none of
+ * them proves a non-commit on its own: a put can commit server-side and lose
+ * its response, and a `ConditionalCheckFailedException` is as consistent with
+ * hitting the row this call just wrote as with a competitor's win. The row is
+ * therefore read back (`verifyWriteLanded`) before anything is deleted. Only a
+ * confirmed `'not-landed'` deletes this record's own nonced object; a confirmed
+ * `'landed'` cleans up the previous object like the success path and swallows
+ * the error, and an `'unverified'` read deletes nothing and rethrows — leaking
+ * one object at worst rather than stranding a live row pointing at a deleted
+ * one. An inline payload has no object to leak, so it needs no read.
  */
-export declare function persistRecord(context: StoreContext, record: StoreItemRecord, previousValue: PayloadDescriptor | undefined): Promise<void>;
+export declare function persistRecord(context: StoreContext, record: StoreItemRecord, existing: ExistingRecordMeta): Promise<void>;
 //# sourceMappingURL=persist.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"persist.d.ts","sourceRoot":"","sources":["../../../src/store/internal/persist.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAmB,MAAM,0BAA0B,CAAC;AAInF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAQ5C;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,aAAa,EAAE,iBAAiB,GAAG,SAAS,GAC3C,OAAO,CAAC,IAAI,CAAC,CA8Bf"}
+{"version":3,"file":"persist.d.ts","sourceRoot":"","sources":["../../../src/store/internal/persist.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAa5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAmBf"}

package/dist/store/internal/persist.js

@@ -5,34 +5,55 @@ const codec_1 = require("../../shared/codec/codec");
 const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
 const orphans_1 = require("../../shared/codec/s3/orphans");
 const retry_1 = require("../../shared/dynamodb/retry");
+const overwrite_swap_1 = require("./overwrite-swap");
 const write_verify_1 = require("./write-verify");
-/** True when `error` is a {@link RetryExhaustedError} — checked by name, not `instanceof` (banned repo-wide). */
-function isRetryExhausted(error) {
-    return error.name === 'RetryExhaustedError';
+/** Best-effort delete of one descriptor's S3 object. */
+async function cleanUp(context, descriptor, label) {
+    if (!context.offloader || !descriptor)
+        return;
+    await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([descriptor]), label, context.logger);
 }
 /**
- * Put the record: on a definite failure, clean up *this* record's nonced S3
- * object; on an ambiguous retry-exhaustion failure, verify via
- * `writeLandedAt` before deleting anything — if it landed, clean up the
- * *previous* row's object instead, like the ordinary success path.
+ * Put the record and clean up whichever side is now dead.
+ *
+ * The compare-and-swap path runs **only when an offloader is configured**:
+ * without one there is no S3 object to orphan, so a plain last-write-wins put
+ * stays correct and costs no extra write capacity (DynamoDB charges for a
+ * failed conditional write too). With one, the swap is what lets this call
+ * delete exactly the payload it superseded rather than a descriptor a racer may
+ * already have replaced.
+ *
+ * Every failure reaching the catch arrives after at least one put was issued —
+ * `putWithRevisionSwap` only re-reads from inside its own catch — so none of
+ * them proves a non-commit on its own: a put can commit server-side and lose
+ * its response, and a `ConditionalCheckFailedException` is as consistent with
+ * hitting the row this call just wrote as with a competitor's win. The row is
+ * therefore read back (`verifyWriteLanded`) before anything is deleted. Only a
+ * confirmed `'not-landed'` deletes this record's own nonced object; a confirmed
+ * `'landed'` cleans up the previous object like the success path and swallows
+ * the error, and an `'unverified'` read deletes nothing and rethrows — leaking
+ * one object at worst rather than stranding a live row pointing at a deleted
+ * one. An inline payload has no object to leak, so it needs no read.
  */
-async function persistRecord(context, record, previousValue) {
+async function persistRecord(context, record, existing) {
+    let superseded = existing;
     try {
-        await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: record }));
+        if (context.offloader) {
+            superseded = await (0, overwrite_swap_1.putWithRevisionSwap)(context, record, existing);
+        }
+        else {
+            await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: record }));
+        }
     }
     catch (error) {
-        const landed = isRetryExhausted(error) &&
-            record.value.location === codec_1.PayloadLocation.S3 &&
-            (await (0, write_verify_1.writeLandedAt)(context, record, record.value.s3Key));
-        if (!landed) {
-            if (context.offloader) {
-                await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([record.value]), 'store.put', context.logger);
-            }
+        const verdict = record.value.location === codec_1.PayloadLocation.S3
+            ? await (0, write_verify_1.verifyWriteLanded)(context, record, record.value.s3Key)
+            : 'not-landed';
+        if (verdict === 'not-landed')
+            await cleanUp(context, record.value, 'store.put');
+        if (verdict !== 'landed')
             throw error;
-        }
-    }
-    if (context.offloader && previousValue) {
-        await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([previousValue]), 'store.put.overwrite', context.logger);
     }
+    await cleanUp(context, superseded.value, 'store.put.overwrite');
 }
 //# sourceMappingURL=persist.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"persist.js","sourceRoot":"","sources":["../../../src/store/internal/persist.ts"],"names":[],"mappings":";;;AAAA,oDAAmF;AACnF,wEAAmE;AACnE,2DAAiE;AACjE,uDAAgE;AAGhE,iDAA+C;AAE/C,iHAAiH;AACjH,SAAS,gBAAgB,CAAC,KAAY;IACpC,OAAO,KAAK,CAAC,IAAI,KAAK,qBAAqB,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACI,KAAK,wBACV,OAAqB,EACrB,MAAuB,EACvB,aAA4C;IAE5C,IAAI,CAAC;QACH,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC3B,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CACnE,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GACV,gBAAgB,CAAC,KAAc,CAAC;YAChC,MAAM,CAAC,KAAK,CAAC,QAAQ,KAAK,uBAAe,CAAC,EAAE;YAC5C,CAAC,MAAM,IAAA,4BAAa,EAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;gBACtB,MAAM,IAAA,0BAAgB,EACpB,OAAO,CAAC,SAAS,EACjB,IAAA,+BAAa,EAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAC7B,WAAW,EACX,OAAO,CAAC,MAAM,CACf,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,IAAI,aAAa,EAAE,CAAC;QACvC,MAAM,IAAA,0BAAgB,EACpB,OAAO,CAAC,SAAS,EACjB,IAAA,+BAAa,EAAC,CAAC,aAAa,CAAC,CAAC,EAC9B,qBAAqB,EACrB,OAAO,CAAC,MAAM,CACf,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"persist.js","sourceRoot":"","sources":["../../../src/store/internal/persist.ts"],"names":[],"mappings":";;;AAAA,oDAAmF;AACnF,wEAAmE;AACnE,2DAAiE;AACjE,uDAAgE;AAEhE,qDAAuD;AAGvD,iDAAsE;AAEtE,wDAAwD;AACxD,KAAK,UAAU,OAAO,CACpB,OAAqB,EACrB,UAAyC,EACzC,KAAa;IAEb,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,UAAU;QAAE,OAAO;IAC9C,MAAM,IAAA,0BAAgB,EAAC,OAAO,CAAC,SAAS,EAAE,IAAA,+BAAa,EAAC,CAAC,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;AAChG,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACI,KAAK,wBACV,OAAqB,EACrB,MAAuB,EACvB,QAA4B;IAE5B,IAAI,UAAU,GAAG,QAAQ,CAAC;IAC1B,IAAI,CAAC;QACH,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,UAAU,GAAG,MAAM,IAAA,oCAAmB,EAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;QACpE,CAAC;aAAM,CAAC;YACN,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC3B,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CACnE,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GACX,MAAM,CAAC,KAAK,CAAC,QAAQ,KAAK,uBAAe,CAAC,EAAE;YAC1C,CAAC,CAAC,MAAM,IAAA,gCAAiB,EAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;YAC9D,CAAC,CAAC,YAAY,CAAC;QACnB,IAAI,OAAO,KAAK,YAAY;YAAE,MAAM,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QAChF,IAAI,OAAO,KAAK,QAAQ;YAAE,MAAM,KAAK,CAAC;IACxC,CAAC;IACD,MAAM,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC;AAClE,CAAC"}

package/dist/store/internal/read-existing.d.ts

@@ -0,0 +1,19 @@
+import type { PayloadDescriptor } from '../../shared/codec/codec';
+import type { StoreContext } from './setup';
+/** The previous row's createdAt, payload descriptor and revision. */
+export interface ExistingRecordMeta {
+    exists: boolean;
+    createdAt?: string;
+    value?: PayloadDescriptor;
+    revision?: string;
+}
+/**
+ * Read the fields a put needs from the row it is about to replace, in one
+ * strongly-consistent projection: `createdAt` to preserve, `value` to clean up
+ * afterwards, and the revision the compare-and-swap pins.
+ *
+ * Lives apart from `actions/put.ts` so `persist.ts` can re-read on a lost swap
+ * without importing its own caller.
+ */
+export declare function readExisting(context: StoreContext, pk: string, sk: string): Promise<ExistingRecordMeta>;
+//# sourceMappingURL=read-existing.d.ts.map

package/dist/store/internal/read-existing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-existing.d.ts","sourceRoot":"","sources":["../../../src/store/internal/read-existing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,EACrB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,kBAAkB,CAAC,CAgB7B"}

package/dist/store/internal/read-existing.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readExisting = readExisting;
+const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
+const retry_1 = require("../../shared/dynamodb/retry");
+/**
+ * Read the fields a put needs from the row it is about to replace, in one
+ * strongly-consistent projection: `createdAt` to preserve, `value` to clean up
+ * afterwards, and the revision the compare-and-swap pins.
+ *
+ * Lives apart from `actions/put.ts` so `persist.ts` can re-read on a lost swap
+ * without importing its own caller.
+ */
+async function readExisting(context, pk, sk) {
+    const existing = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
+        TableName: context.tableName,
+        Key: { PK: pk, SK: sk },
+        ConsistentRead: true,
+        ProjectionExpression: '#c, #v, #r',
+        ExpressionAttributeNames: { '#c': 'createdAt', '#v': 'value', '#r': conditional_put_1.REVISION_ATTRIBUTE },
+    }));
+    return {
+        exists: existing.Item !== undefined,
+        createdAt: existing.Item?.createdAt,
+        value: existing.Item?.value,
+        revision: existing.Item?.[conditional_put_1.REVISION_ATTRIBUTE],
+    };
+}
+//# sourceMappingURL=read-existing.js.map

package/dist/store/internal/read-existing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-existing.js","sourceRoot":"","sources":["../../../src/store/internal/read-existing.ts"],"names":[],"mappings":";;;AACA,2EAA2E;AAC3E,uDAAgE;AAWhE;;;;;;;GAOG;AACI,KAAK,uBACV,OAAqB,EACrB,EAAU,EACV,EAAU;IAEV,MAAM,QAAQ,GAAG,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC5C,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;QACjB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;QACvB,cAAc,EAAE,IAAI;QACpB,oBAAoB,EAAE,YAAY;QAClC,wBAAwB,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,oCAAkB,EAAE;KACzF,CAAC,CACH,CAAC;IACF,OAAO;QACL,MAAM,EAAE,QAAQ,CAAC,IAAI,KAAK,SAAS;QACnC,SAAS,EAAE,QAAQ,CAAC,IAAI,EAAE,SAA+B;QACzD,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,KAAsC;QAC5D,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,oCAAkB,CAAuB;KACpE,CAAC;AACJ,CAAC"}

package/dist/store/internal/score-direction.d.ts

@@ -0,0 +1,32 @@
+import type { VectorMatch } from '../vector-backend';
+/** Which direction a {@link VectorBackend} reports its score in. */
+export type VectorScoreDirection = 'relevance' | 'distance';
+/** Every direction {@link toRelevanceScores} recognises, for validating input. */
+export declare const VECTOR_SCORE_DIRECTIONS: readonly VectorScoreDirection[];
+/**
+ * Normalise a backend's matches to the relevance direction upstream
+ * `SearchItem.score` documents — "higher scores indicate better matches",
+ * typically a cosine similarity between -1 and 1.
+ *
+ * A distance is converted by **negation** rather than `1 / (1 + d)`: negation
+ * is monotone over the whole real line, needs no non-negativity precondition,
+ * and is exactly invertible, so the original distance is simply `-score`. A
+ * reciprocal would silently imply a different `(0, 1]` scale and is undefined
+ * at `d === -1`. Negative scores are already in range for this contract, so
+ * nothing is lost by producing them.
+ *
+ * Results are re-sorted after conversion so a backend that returns its matches
+ * in some other order still ranks correctly. Anything that is not `'distance'`
+ * is returned untouched — its own order stays authoritative, exactly as before.
+ *
+ * The test is for `'distance'` rather than against `'relevance'` on purpose:
+ * converting is the destructive branch, so only the exact value that asks for
+ * it may reach it. Testing the other way round made every unrecognised
+ * string — `'Distance'`, a typo, a value read from a config file — reverse the
+ * ranking silently, with no error and no warning (the ascending-score warning
+ * lives downstream of this conversion, so it could never fire). `setUpStore`
+ * rejects such a value outright; this keeps the failure harmless for any
+ * caller that reaches the function some other way.
+ */
+export declare function toRelevanceScores(matches: VectorMatch[], direction: VectorScoreDirection): VectorMatch[];
+//# sourceMappingURL=score-direction.d.ts.map

package/dist/store/internal/score-direction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-direction.d.ts","sourceRoot":"","sources":["../../../src/store/internal/score-direction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,oEAAoE;AACpE,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,UAAU,CAAC;AAE5D,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,EAAE,SAAS,oBAAoB,EAA8B,CAAC;AAElG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EAAE,EACtB,SAAS,EAAE,oBAAoB,GAC9B,WAAW,EAAE,CAKf"}

package/dist/store/internal/score-direction.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VECTOR_SCORE_DIRECTIONS = void 0;
+exports.toRelevanceScores = toRelevanceScores;
+/** Every direction {@link toRelevanceScores} recognises, for validating input. */
+exports.VECTOR_SCORE_DIRECTIONS = ['relevance', 'distance'];
+/**
+ * Normalise a backend's matches to the relevance direction upstream
+ * `SearchItem.score` documents — "higher scores indicate better matches",
+ * typically a cosine similarity between -1 and 1.
+ *
+ * A distance is converted by **negation** rather than `1 / (1 + d)`: negation
+ * is monotone over the whole real line, needs no non-negativity precondition,
+ * and is exactly invertible, so the original distance is simply `-score`. A
+ * reciprocal would silently imply a different `(0, 1]` scale and is undefined
+ * at `d === -1`. Negative scores are already in range for this contract, so
+ * nothing is lost by producing them.
+ *
+ * Results are re-sorted after conversion so a backend that returns its matches
+ * in some other order still ranks correctly. Anything that is not `'distance'`
+ * is returned untouched — its own order stays authoritative, exactly as before.
+ *
+ * The test is for `'distance'` rather than against `'relevance'` on purpose:
+ * converting is the destructive branch, so only the exact value that asks for
+ * it may reach it. Testing the other way round made every unrecognised
+ * string — `'Distance'`, a typo, a value read from a config file — reverse the
+ * ranking silently, with no error and no warning (the ascending-score warning
+ * lives downstream of this conversion, so it could never fire). `setUpStore`
+ * rejects such a value outright; this keeps the failure harmless for any
+ * caller that reaches the function some other way.
+ */
+function toRelevanceScores(matches, direction) {
+    if (direction !== 'distance')
+        return matches;
+    return matches
+        .map((match) => ({ ...match, score: -match.score }))
+        .sort((left, right) => right.score - left.score);
+}
+//# sourceMappingURL=score-direction.js.map

package/dist/store/internal/score-direction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-direction.js","sourceRoot":"","sources":["../../../src/store/internal/score-direction.ts"],"names":[],"mappings":";;;;AAKA,kFAAkF;AACrE,QAAA,uBAAuB,GAAoC,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;AAElG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,2BACE,OAAsB,EACtB,SAA+B;IAE/B,IAAI,SAAS,KAAK,UAAU;QAAE,OAAO,OAAO,CAAC;IAC7C,OAAO,OAAO;SACX,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;SACnD,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;AACrD,CAAC"}

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

@@ -0,0 +1,4 @@
+import type { Item, SearchOperation } from '@langchain/langgraph-checkpoint';
+/** True when `item` satisfies the search operation's optional metadata filter. */
+export declare function passesFilter(item: Item, op: SearchOperation): boolean;
+//# sourceMappingURL=search-filter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search-filter.d.ts","sourceRoot":"","sources":["../../../src/store/internal/search-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAI7E,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,eAAe,GAAG,OAAO,CAMrE"}

package/dist/store/internal/search-filter.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.passesFilter = passesFilter;
+const filter_1 = require("./filter");
+/** True when `item` satisfies the search operation's optional metadata filter. */
+function passesFilter(item, op) {
+    if (!op.filter)
+        return true;
+    return (0, filter_1.matchesStoreFilter)(item.value, op.filter);
+}
+//# sourceMappingURL=search-filter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search-filter.js","sourceRoot":"","sources":["../../../src/store/internal/search-filter.ts"],"names":[],"mappings":";;;AAEA,qCAA8D;AAE9D,kFAAkF;AAClF,sBAA6B,IAAU,EAAE,EAAmB;IAC1D,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"}

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

@@ -7,6 +7,7 @@ import { type Logger } from '../../shared/logging/logger';
 import type { TtlOption } from '../../shared/validation/ttl';
 import type { DynamoDBStoreOptions } from '../types';
 import type { VectorBackend } from '../vector-backend';
+import { type VectorScoreDirection } from './score-direction';
 /** Resolved collaborators shared by every store action. */
 export interface StoreContext {
     client: DynamoDBDocument;
@@ -18,6 +19,7 @@ export interface StoreContext {
     logger: Logger;
     index?: IndexConfig;
     vectorBackend?: VectorBackend;
+    vectorScoreDirection: VectorScoreDirection;
     maxSearchCandidates: number;
     maxScanItems: number;
 }
@@ -27,6 +29,16 @@ export interface StoreSetup {
     ddbClient: DynamoDBClient | undefined;
     ownsClient: boolean;
 }
-/** Resolve the client, optional S3 offloader, serializer, and index config. */
+/**
+ * Resolve the client, optional S3 offloader, serializer, and index config.
+ *
+ * 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 setUpStore(options: DynamoDBStoreOptions): StoreSetup;
 //# sourceMappingURL=setup.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/store/internal/setup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAEvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGxE,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAO9D,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,6BAA6B,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,cAAc,GAAG,SAAS,CAAC;IACtC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU,CAyBpE"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/store/internal/setup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAEvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGxE,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAQ9D,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,6BAA6B,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAA2B,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEvF,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,oBAAoB,EAAE,oBAAoB,CAAC;IAC3C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,cAAc,GAAG,SAAS,CAAC;IACtC,UAAU,EAAE,OAAO,CAAC;CACrB;AA4CD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU,CAoCpE"}

package/dist/store/internal/setup.js

@@ -6,9 +6,64 @@ const config_1 = require("../../shared/codec/s3/config");
 const offloader_1 = require("../../shared/codec/s3/offloader");
 const constants_1 = require("../../shared/constants");
 const client_1 = require("../../shared/dynamodb/client");
+const errors_1 = require("../../shared/errors/errors");
 const logger_1 = require("../../shared/logging/logger");
-/** Resolve the client, optional S3 offloader, serializer, and index config. */
+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.
+ *
+ * Only `embeddings` is checked. `dims` is part of the upstream type but is
+ * never read anywhere in this package, so rejecting a configuration over it
+ * would break working callers for no benefit.
+ */
+function assertUsableIndex(index) {
+    if (!index)
+        return;
+    const embeddings = index.embeddings;
+    if (typeof embeddings?.embedQuery !== 'function') {
+        throw new errors_1.ValidationError('`index.embeddings` must be an Embeddings implementation exposing embedQuery(); ' +
+            'without one no embedding can be computed for put() or 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');
+}
+/**
+ * Resolve the client, optional S3 offloader, serializer, and index config.
+ *
+ * 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 setUpStore(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);
     const resolved = (0, client_1.resolveDynamoDBClient)(options);
     return {
         context: {
@@ -26,6 +81,7 @@ function setUpStore(options) {
             logger: (0, logger_1.resolveLogger)(options.logger),
             index: options.index,
             vectorBackend: options.vectorBackend,
+            vectorScoreDirection: options.vectorScoreDirection ?? 'relevance',
             maxSearchCandidates: options.maxSearchCandidates ?? constants_1.DEFAULT_MAX_SEARCH_CANDIDATES,
             maxScanItems: options.maxScanItems ?? constants_1.MAX_TOTAL_ITEMS_IN_MEMORY,
         },

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

@@ -1 +1 @@
-{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../src/store/internal/setup.ts"],"names":[],"mappings":";;;AAKA,8DAA2D;AAC3D,yDAAuE;AACvE,+DAA8D;AAC9D,sDAIgC;AAChC,yDAAqE;AACrE,wDAAyE;AA2BzE,+EAA+E;AAC/E,oBAA2B,OAA6B;IACtD,MAAM,QAAQ,GAAG,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;IAChD,OAAO;QACL,OAAO,EAAE;YACP,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,uBAAU;YAClC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,SAAS,EAAE,OAAO,CAAC,EAAE;gBACnB,CAAC,CAAC,IAAI,uBAAW,CAAC;oBACd,GAAG,OAAO,CAAC,EAAE;oBACb,SAAS,EACP,OAAO,CAAC,EAAE,CAAC,SAAS,IAAI,IAAA,gCAAuB,EAAC,iCAAqB,EAAE,OAAO,CAAC;iBAClF,CAAC;gBACJ,CAAC,CAAC,SAAS;YACb,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,MAAM,EAAE,IAAA,sBAAa,EAAC,OAAO,CAAC,MAAM,CAAC;YACrC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,IAAI,yCAA6B;YACjF,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,qCAAyB;SAChE;QACD,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,UAAU,EAAE,QAAQ,CAAC,UAAU;KAChC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../src/store/internal/setup.ts"],"names":[],"mappings":";;;AAMA,8DAA2D;AAC3D,yDAAuE;AACvE,+DAA8D;AAC9D,sDAIgC;AAChC,yDAAqE;AACrE,uDAA6D;AAC7D,wDAAyE;AAIzE,uDAAuF;AAyBvF;;;;;;;;;GASG;AACH,SAAS,iBAAiB,CAAC,KAAmB;IAC5C,IAAI,CAAC,KAAK;QAAE,OAAO;IACnB,MAAM,UAAU,GAAoC,KAAK,CAAC,UAAU,CAAC;IACrE,IAAI,OAAO,UAAU,EAAE,UAAU,KAAK,UAAU,EAAE,CAAC;QACjD,MAAM,IAAI,wBAAe,CACvB,iFAAiF;YAC/E,gEAAgE,EAClE,OAAO,CACR,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,oBAAoB,CAAC,SAAgC;IAC5D,IAAI,SAAS,KAAK,SAAS,IAAI,yCAAuB,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO;IACnF,MAAM,IAAI,wBAAe,CACvB,uCAAuC,yCAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa;QACrF,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,2DAA2D;QACvF,yCAAyC,EAC3C,sBAAsB,CACvB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,oBAA2B,OAA6B;IACtD,IAAI,OAAO,CAAC,aAAa,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAC5C,MAAM,IAAI,wBAAe,CACvB,qFAAqF;YACnF,uFAAuF;YACvF,8BAA8B,EAChC,eAAe,CAChB,CAAC;IACJ,CAAC;IACD,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACjC,oBAAoB,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACnD,MAAM,QAAQ,GAAG,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;IAChD,OAAO;QACL,OAAO,EAAE;YACP,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,uBAAU;YAClC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,SAAS,EAAE,OAAO,CAAC,EAAE;gBACnB,CAAC,CAAC,IAAI,uBAAW,CAAC;oBACd,GAAG,OAAO,CAAC,EAAE;oBACb,SAAS,EACP,OAAO,CAAC,EAAE,CAAC,SAAS,IAAI,IAAA,gCAAuB,EAAC,iCAAqB,EAAE,OAAO,CAAC;iBAClF,CAAC;gBACJ,CAAC,CAAC,SAAS;YACb,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,MAAM,EAAE,IAAA,sBAAa,EAAC,OAAO,CAAC,MAAM,CAAC;YACrC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,IAAI,WAAW;YACjE,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,IAAI,yCAA6B;YACjF,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,qCAAyB;SAChE;QACD,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,UAAU,EAAE,QAAQ,CAAC,UAAU;KAChC,CAAC;AACJ,CAAC"}

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

@@ -1,7 +1,13 @@
 /** Validate search/listNamespaces paging is non-negative integers. */
 export declare function validatePaging(offset: number, limit: number): void;
-/** Validate the namespace is non-empty and each element is separator-free. */
+/** Validate the namespace is non-empty and each element is a valid identifier. */
 export declare function validateNamespace(namespace: string[]): void;
-/** Validate an item key is a non-empty, separator-free string. */
+/** Validate an item key is a non-empty, separator- and control-char-free string. */
 export declare function validateKey(key: string): void;
+/**
+ * Validate an optional namespace depth cap. Left unchecked, a negative value
+ * silently inverted truncation via `Array.prototype.slice(0, -n)`, which drops
+ * the *last* n elements rather than erroring.
+ */
+export declare function validateMaxDepth(maxDepth?: number): void;
 //# sourceMappingURL=validation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/store/internal/validation.ts"],"names":[],"mappings":"AAQA,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAGlE;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAM3D;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAG7C"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/store/internal/validation.ts"],"names":[],"mappings":"AAOA,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAGlE;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAK3D;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAGxD"}

package/dist/store/internal/validation.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validatePaging = validatePaging;
 exports.validateNamespace = validateNamespace;
 exports.validateKey = validateKey;
+exports.validateMaxDepth = validateMaxDepth;
 const primitives_1 = require("../../shared/validation/primitives");
 const keys_1 = require("./keys");
 /** Validate search/listNamespaces paging is non-negative integers. */
@@ -10,17 +11,25 @@ function validatePaging(offset, limit) {
     (0, primitives_1.validateInteger)(offset, 'offset', { min: 0 });
     (0, primitives_1.validateInteger)(limit, 'limit', { min: 0 });
 }
-/** Validate the namespace is non-empty and each element is separator-free. */
+/** Validate the namespace is non-empty and each element is a valid identifier. */
 function validateNamespace(namespace) {
     (0, primitives_1.validateNonEmptyArray)(namespace, 'namespace');
     for (const element of namespace) {
-        (0, primitives_1.validateNonEmptyString)(element, 'namespace element');
-        (0, primitives_1.assertNoSeparator)(element, keys_1.NAMESPACE_SEPARATOR, 'namespace element');
+        (0, primitives_1.validateIdentifier)(element, keys_1.NAMESPACE_SEPARATOR, 'namespace element');
     }
 }
-/** Validate an item key is a non-empty, separator-free string. */
+/** Validate an item key is a non-empty, separator- and control-char-free string. */
 function validateKey(key) {
-    (0, primitives_1.validateNonEmptyString)(key, 'key');
-    (0, primitives_1.assertNoSeparator)(key, keys_1.NAMESPACE_SEPARATOR, 'key');
+    (0, primitives_1.validateIdentifier)(key, keys_1.NAMESPACE_SEPARATOR, 'key');
+}
+/**
+ * Validate an optional namespace depth cap. Left unchecked, a negative value
+ * silently inverted truncation via `Array.prototype.slice(0, -n)`, which drops
+ * the *last* n elements rather than erroring.
+ */
+function validateMaxDepth(maxDepth) {
+    if (maxDepth === undefined)
+        return;
+    (0, primitives_1.validateInteger)(maxDepth, 'maxDepth', { min: 1 });
 }
 //# sourceMappingURL=validation.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/store/internal/validation.ts"],"names":[],"mappings":";;;;;AAAA,mEAK4C;AAC5C,iCAA6C;AAE7C,sEAAsE;AACtE,wBAA+B,MAAc,EAAE,KAAa;IAC1D,IAAA,4BAAe,EAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9C,IAAA,4BAAe,EAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,8EAA8E;AAC9E,2BAAkC,SAAmB;IACnD,IAAA,kCAAqB,EAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC9C,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;QAChC,IAAA,mCAAsB,EAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;QACrD,IAAA,8BAAiB,EAAC,OAAO,EAAE,0BAAmB,EAAE,mBAAmB,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,qBAA4B,GAAW;IACrC,IAAA,mCAAsB,EAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACnC,IAAA,8BAAiB,EAAC,GAAG,EAAE,0BAAmB,EAAE,KAAK,CAAC,CAAC;AACrD,CAAC"}
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/store/internal/validation.ts"],"names":[],"mappings":";;;;;;AAAA,mEAI4C;AAC5C,iCAA6C;AAE7C,sEAAsE;AACtE,wBAA+B,MAAc,EAAE,KAAa;IAC1D,IAAA,4BAAe,EAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9C,IAAA,4BAAe,EAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,kFAAkF;AAClF,2BAAkC,SAAmB;IACnD,IAAA,kCAAqB,EAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC9C,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;QAChC,IAAA,+BAAkB,EAAC,OAAO,EAAE,0BAAmB,EAAE,mBAAmB,CAAC,CAAC;IACxE,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,qBAA4B,GAAW;IACrC,IAAA,+BAAkB,EAAC,GAAG,EAAE,0BAAmB,EAAE,KAAK,CAAC,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,0BAAiC,QAAiB;IAChD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO;IACnC,IAAA,4BAAe,EAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;AACpD,CAAC"}