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

package/dist/{shared → cjs/shared}/validation/options.d.ts

@@ -6,10 +6,10 @@
  * their bounds, before an adapter builds anything, so a misconfiguration
  * surfaces at construction rather than on the first call.
  */
-import type { CompressionConfig } from '../codec/compression';
-import { type S3OffloadConfig } from '../codec/s3/config';
-import type { RetryPolicy } from '../dynamodb/retry';
-import type { BaseAdapterOptions, CodecOptions } from '../options';
+import type { CompressionConfig } from '../codec/compression.js';
+import { type S3OffloadConfig } from '../codec/s3/config.js';
+import type { RetryPolicy } from '../dynamodb/retry.js';
+import type { BaseAdapterOptions, CodecOptions } from '../options.js';
 /**
  * Largest `s3.maxDownloadBytes`/`compression.maxDecompressedBytes` an adapter
  * accepts (512 MiB): both hold one buffer fully resident while it is read or

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

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_READ_CONCURRENCY = exports.MAX_RETRY_DELAY_MS = exports.MAX_RETRY_ATTEMPTS = exports.MAX_PAYLOAD_BUFFER_BYTES = void 0;
+exports.assertTableName = assertTableName;
+exports.assertClientChoice = assertClientChoice;
+exports.assertRetryBounds = assertRetryBounds;
+exports.assertRetryPolicy = assertRetryPolicy;
+exports.assertBaseAdapterOptions = assertBaseAdapterOptions;
+exports.assertCompression = assertCompression;
+exports.assertS3 = assertS3;
+const codec_js_1 = require("../codec/codec.js");
+const config_js_1 = require("../codec/s3/config.js");
+const offloader_js_1 = require("../codec/s3/offloader.js");
+const recency_index_js_1 = require("../dynamodb/recency-index.js");
+const errors_js_1 = require("../errors/errors.js");
+const option_shape_js_1 = require("./option-shape.js");
+const primitives_js_1 = require("./primitives.js");
+const ttl_js_1 = require("./ttl.js");
+const TABLE_NAME_PATTERN = /^[A-Za-z0-9_.-]{3,255}$/;
+exports.MAX_PAYLOAD_BUFFER_BYTES = 512 * 1024 * 1024;
+exports.MAX_RETRY_ATTEMPTS = 100;
+exports.MAX_RETRY_DELAY_MS = 60_000;
+exports.MAX_READ_CONCURRENCY = 128;
+const RETRY_KEYS = (0, option_shape_js_1.allKeysOf)({
+    maxAttempts: 'maxAttempts',
+    baseDelayMs: 'baseDelayMs',
+    maxDelayMs: 'maxDelayMs',
+});
+function assertTableName(tableName) {
+    if (typeof tableName !== 'string' || !TABLE_NAME_PATTERN.test(tableName)) {
+        throw (0, errors_js_1.validationError)('tableName must be 3-255 characters from [A-Za-z0-9_.-], as DynamoDB requires', 'tableName');
+    }
+}
+function assertClientChoice(options) {
+    if (options.client &&
+        (options.clientConfig !== undefined || options.createClient !== undefined)) {
+        throw (0, errors_js_1.validationError)('provide either `client` or `clientConfig`/`createClient`, not both: an injected client ' +
+            'is used as-is and the configuration would be silently ignored', 'client');
+    }
+    if (options.clientConfig !== undefined)
+        (0, option_shape_js_1.assertObjectShape)(options.clientConfig, 'clientConfig');
+}
+function assertRetryBounds(policy) {
+    if (policy.maxAttempts !== undefined) {
+        (0, primitives_js_1.assertInteger)(policy.maxAttempts, 'retry.maxAttempts', { min: 1, max: exports.MAX_RETRY_ATTEMPTS });
+    }
+    if (policy.baseDelayMs !== undefined) {
+        (0, primitives_js_1.assertInteger)(policy.baseDelayMs, 'retry.baseDelayMs', { min: 1, max: exports.MAX_RETRY_DELAY_MS });
+    }
+    if (policy.maxDelayMs !== undefined) {
+        (0, primitives_js_1.assertInteger)(policy.maxDelayMs, 'retry.maxDelayMs', {
+            min: policy.baseDelayMs ?? 1,
+            max: exports.MAX_RETRY_DELAY_MS,
+        });
+    }
+}
+function assertRetryPolicy(policy) {
+    (0, option_shape_js_1.assertShape)(policy, RETRY_KEYS, 'retry');
+    assertRetryBounds(policy);
+}
+function assertRecencyIndex(options) {
+    if (options.indexShards !== undefined) {
+        (0, primitives_js_1.assertInteger)(options.indexShards, 'indexShards', { min: 1, max: recency_index_js_1.MAX_INDEX_SHARDS });
+    }
+    if (options.indexName !== undefined)
+        (0, primitives_js_1.assertNonEmptyString)(options.indexName, 'indexName');
+}
+function assertBaseAdapterOptions(options) {
+    if (typeof options !== 'object' || options === null) {
+        throw (0, errors_js_1.validationError)('options must be an object naming at least a tableName', 'options');
+    }
+    assertTableName(options.tableName);
+    assertClientChoice(options);
+    if (options.ttl !== undefined)
+        (0, ttl_js_1.resolveTtlSeconds)(options.ttl);
+    if (options.retry !== undefined)
+        assertRetryPolicy(options.retry);
+    if (options.compression !== undefined)
+        assertCompression(options.compression);
+    if (options.s3 !== undefined)
+        assertS3(options.s3);
+    if (options.readConcurrency !== undefined) {
+        (0, primitives_js_1.assertInteger)(options.readConcurrency, 'readConcurrency', {
+            min: 1,
+            max: exports.MAX_READ_CONCURRENCY,
+        });
+    }
+    assertRecencyIndex(options);
+}
+const SSE_ALGORITHMS = ['AES256', 'aws:kms', 'aws:kms:dsse'];
+const COMPRESSION_KEYS = (0, option_shape_js_1.allKeysOf)({
+    enabled: 'enabled',
+    level: 'level',
+    minSizeBytes: 'minSizeBytes',
+    maxDecompressedBytes: 'maxDecompressedBytes',
+});
+const S3_KEYS = (0, option_shape_js_1.allKeysOf)({
+    bucketName: 'bucketName',
+    keyPrefix: 'keyPrefix',
+    thresholdBytes: 'thresholdBytes',
+    serverSideEncryption: 'serverSideEncryption',
+    sseKmsKeyId: 'sseKmsKeyId',
+    maxDownloadBytes: 'maxDownloadBytes',
+    clientConfig: 'clientConfig',
+    createS3Client: 'createS3Client',
+});
+function assertCompression(config) {
+    (0, option_shape_js_1.assertShape)(config, COMPRESSION_KEYS, 'compression');
+    if (typeof config.enabled !== 'boolean') {
+        throw (0, errors_js_1.validationError)('compression.enabled must be a boolean', 'compression.enabled');
+    }
+    if (config.level !== undefined) {
+        (0, primitives_js_1.assertInteger)(config.level, 'compression.level', { min: 0, max: 9 });
+    }
+    if (config.minSizeBytes !== undefined) {
+        (0, primitives_js_1.assertInteger)(config.minSizeBytes, 'compression.minSizeBytes', {
+            min: 0,
+            max: exports.MAX_PAYLOAD_BUFFER_BYTES,
+        });
+    }
+    if (config.maxDecompressedBytes !== undefined) {
+        (0, primitives_js_1.assertInteger)(config.maxDecompressedBytes, 'compression.maxDecompressedBytes', {
+            min: 1,
+            max: exports.MAX_PAYLOAD_BUFFER_BYTES,
+        });
+    }
+}
+function assertS3Encryption(config) {
+    if (config.serverSideEncryption !== undefined &&
+        !SSE_ALGORITHMS.includes(config.serverSideEncryption)) {
+        throw (0, errors_js_1.validationError)(`s3.serverSideEncryption must be one of ${SSE_ALGORITHMS.join(', ')}`, 's3.serverSideEncryption');
+    }
+    if (config.sseKmsKeyId !== undefined) {
+        (0, primitives_js_1.assertNonEmptyString)(config.sseKmsKeyId, 's3.sseKmsKeyId');
+    }
+}
+function assertS3(config) {
+    (0, option_shape_js_1.assertShape)(config, S3_KEYS, 's3');
+    (0, primitives_js_1.assertNonEmptyString)(config.bucketName, 's3.bucketName');
+    if (config.clientConfig !== undefined)
+        (0, option_shape_js_1.assertObjectShape)(config.clientConfig, 's3.clientConfig');
+    if (config.thresholdBytes !== undefined) {
+        (0, primitives_js_1.assertInteger)(config.thresholdBytes, 's3.thresholdBytes', {
+            min: 1,
+            max: codec_js_1.MAX_INLINE_PAYLOAD_BYTES,
+        });
+    }
+    if (config.keyPrefix !== undefined)
+        (0, config_js_1.assertScopedKeyPrefix)(config.keyPrefix);
+    if (config.maxDownloadBytes !== undefined) {
+        (0, primitives_js_1.assertInteger)(config.maxDownloadBytes, 's3.maxDownloadBytes', {
+            min: 1,
+            max: exports.MAX_PAYLOAD_BUFFER_BYTES,
+        });
+    }
+    const threshold = config.thresholdBytes ?? offloader_js_1.DEFAULT_S3_THRESHOLD_BYTES;
+    const downloadable = config.maxDownloadBytes ?? offloader_js_1.DEFAULT_MAX_S3_DOWNLOAD_BYTES;
+    if (downloadable < threshold) {
+        throw (0, errors_js_1.validationError)(`s3.maxDownloadBytes (${downloadable}) must be at least s3.thresholdBytes (${threshold}): ` +
+            'every offloaded payload is at least the threshold, so none could be read back', 's3.maxDownloadBytes');
+    }
+    assertS3Encryption(config);
+    if (config.createS3Client !== undefined && typeof config.createS3Client !== 'function') {
+        throw (0, errors_js_1.validationError)('s3.createS3Client must be a function', 's3.createS3Client');
+    }
+}

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

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

package/dist/{shared → cjs/shared}/validation/ttl.d.ts

@@ -3,7 +3,7 @@
  *
  * A caller gives days or seconds. The one-unit rule, the five-year cap, the
  * epoch second DynamoDB's TTL attribute takes, and the S3 lifecycle days that
- * keep an offloaded object alive past its row's sweep lag are all derived
+ * keep an offloaded object from expiring before its row are all derived
  * here, so the two spellings of the `ttl` option are accepted or rejected
  * alike and no reader re-derives one unit from the other itself. A stored
  * row's own epoch-second `ttl` is converted to milliseconds for `Date` where
@@ -14,9 +14,14 @@ export declare const MAX_TTL_DAYS: number;
 /** Maximum TTL expressed in seconds: the same five years as {@link MAX_TTL_DAYS}. */
 export declare const MAX_TTL_SECONDS: number;
 /**
- * Extra days an S3 lifecycle rule adds over the TTL it backs. DynamoDB's TTL
- * sweep can lag up to ~48 h past the `ttl` timestamp; the offloaded object
- * must outlive its row, never the other way round.
+ * Extra days an S3 lifecycle rule adds over the TTL it backs, so the offloaded
+ * object is never removed before the row that names it expires, never the
+ * other way round. The rule expires an object by age, at or after creation +
+ * ceil(ttl) + this margin, which is at or after the `ttl` of any row naming
+ * it, so DynamoDB's physical-deletion lag (typically within a few days of the
+ * `ttl`, with no fixed bound:
+ * https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html)
+ * does not matter. The margin is headroom, not a bound on that lag.
  */
 export declare const S3_LIFECYCLE_SWEEP_MARGIN_DAYS = 2;
 /** Time-to-live expressed in whole days or whole seconds. */
@@ -68,10 +73,22 @@ export declare function calculateTtlTimestamp(ttl: TtlOption, now?: () => number
  *
  * Throws: whatever {@link resolveTtlSeconds} throws.
  *
- * Guarantees: the object outlives the row that points at it. S3 expires an
- * object at the first midnight UTC at least `Days` after creation, while
- * DynamoDB may keep an expired item for up to 48 hours past its `ttl`
- * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/howitworks-ttl.html);
- * the margin covers that lag, which a bare `{ days: N }` did not.
+ * Guarantees: the object outlives the row that points at it, for every row
+ * written under the `ttl` this rule was computed from. S3 expires an object at
+ * the first midnight UTC at least `Days` after creation, while DynamoDB
+ * deletes an expired item typically within a few days of its `ttl`, with no
+ * fixed bound
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html).
+ * Every row naming the object carries a `ttl` no later than its creation plus
+ * `ttl`, so the object, expiring at or after that, is not removed before its
+ * row expires; readers hide a metadata, store or history row by its own `ttl`,
+ * and serve a checkpoint's payload and pending-write rows only while its
+ * metadata row is live. The margin is headroom, not a bound on the lag.
+ *
+ * The rule expires by age every object under its prefix, including objects
+ * named by rows written under an earlier `ttl`. After a rule is rewritten for
+ * a smaller `ttl`, the guarantee therefore holds only once every row written
+ * under the old, longer value has expired; until then such a row can outlive
+ * its object. Rewriting it for a larger `ttl` keeps the guarantee.
  */
 export declare function lifecycleExpirationDays(ttl: TtlOption): number;

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

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

package/dist/{store → cjs/store}/actions/list-namespaces.d.ts

@@ -8,8 +8,8 @@
  * paging by `offset` gets the same order on every call and every host.
  */
 import type { MatchCondition } from '@langchain/langgraph-checkpoint';
-import type { ParsedList } from '../internal/parse';
-import type { StoreContext } from '../internal/setup';
+import type { ParsedList } from '../internal/parse.js';
+import type { StoreContext } from '../internal/setup.js';
 /**
  * Whether `namespace` satisfies one match condition. `condition.matchType` is
  * `'prefix'` or `'suffix'`, already refused otherwise by the parser that built
@@ -67,9 +67,9 @@ export declare function prefixRoot(conditions?: MatchCondition[]): string[];
  *
  * Returns: the namespaces, sorted, then `limit` of them from `offset`.
  *
- * Throws: `RESULT_TRUNCATED` when `maxScanItems` is reached while rows
- * remain, so a partial listing is never returned as a complete one;
- * `FORMAT_UNSUPPORTED` for a store item a newer release wrote.
+ * Throws: `RESULT_TRUNCATED` when `maxScanItems` or `maxIterations` is
+ * reached while rows remain, so a partial listing is never returned as a
+ * complete one; `FORMAT_UNSUPPORTED` for a store item a newer release wrote.
  *
  * Guarantees: every live row is read — the answer is about which namespaces
  * exist, and paging over it must not depend on which rows were read first. That

package/dist/cjs/store/actions/list-namespaces.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchNamespace = matchNamespace;
+exports.truncateDepth = truncateDepth;
+exports.prefixRoot = prefixRoot;
+exports.listNamespaces = listNamespaces;
+const clock_js_1 = require("../../shared/clock.js");
+const paginate_js_1 = require("../../shared/dynamodb/paginate.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const rows_js_1 = require("../internal/rows.js");
+const WILDCARD = '*';
+function segmentMatches(actual, path) {
+    return path.every((element, index) => element === WILDCARD || element === actual[index]);
+}
+function matchNamespace(namespace, condition) {
+    const { matchType, path } = condition;
+    if (path.length > namespace.length)
+        return false;
+    const slice = matchType === 'prefix'
+        ? namespace.slice(0, path.length)
+        : namespace.slice(namespace.length - path.length);
+    return segmentMatches(slice, path);
+}
+function truncateDepth(namespace, maxDepth) {
+    return maxDepth === undefined ? namespace : namespace.slice(0, maxDepth);
+}
+function prefixRoot(conditions) {
+    const prefixCondition = conditions?.find((condition) => condition.matchType === 'prefix');
+    if (!prefixCondition)
+        return [];
+    const root = [];
+    for (const element of prefixCondition.path) {
+        if (element === WILDCARD)
+            break;
+        root.push(element);
+    }
+    return root;
+}
+function namespaceSource(context, op, now) {
+    const root = prefixRoot(op.matchConditions);
+    if (root.length > 0) {
+        return (0, paginate_js_1.paginateQuery)({
+            retry: context.retry,
+            client: context.client,
+            params: (0, table_schema_js_1.withoutExpired)((0, rows_js_1.projectKeys)((0, rows_js_1.scopedQuery)(context.tableName, root)), now),
+            maxItems: context.maxScanItems,
+            maxIterations: context.maxIterations,
+        });
+    }
+    return (0, paginate_js_1.paginateScan)({
+        retry: context.retry,
+        client: context.client,
+        params: (0, table_schema_js_1.withoutExpired)((0, rows_js_1.projectKeys)((0, rows_js_1.storeScan)(context.tableName)), now),
+        maxItems: context.maxScanItems,
+        maxIterations: context.maxIterations,
+    });
+}
+const NAMESPACE_COLLATOR = new Intl.Collator('en');
+const REFERENCE_JOIN = ':';
+function compareNamespaces(a, b) {
+    const collated = NAMESPACE_COLLATOR.compare(a.join(REFERENCE_JOIN), b.join(REFERENCE_JOIN));
+    if (collated !== 0)
+        return collated;
+    const left = a.join(table_schema_js_1.KEY_SEPARATOR);
+    const right = b.join(table_schema_js_1.KEY_SEPARATOR);
+    return left < right ? -1 : Number(left > right);
+}
+async function listNamespaces(context, op) {
+    if (op.limit === 0)
+        return [];
+    const now = (0, clock_js_1.nowSeconds)();
+    const seen = new Set();
+    const namespaces = [];
+    for await (const raw of namespaceSource(context, op, now)) {
+        const record = (0, rows_js_1.parseStoreRow)(raw);
+        if (!record || (0, table_schema_js_1.isExpiredRow)(record, now))
+            continue;
+        const namespace = record.namespace;
+        if (op.matchConditions &&
+            !op.matchConditions.every((condition) => matchNamespace(namespace, condition))) {
+            continue;
+        }
+        const truncated = truncateDepth(namespace, op.maxDepth);
+        const dedupeKey = truncated.join(table_schema_js_1.KEY_SEPARATOR);
+        if (seen.has(dedupeKey))
+            continue;
+        seen.add(dedupeKey);
+        namespaces.push(truncated);
+    }
+    namespaces.sort(compareNamespaces);
+    return namespaces.slice(op.offset, op.offset + op.limit);
+}

package/dist/{store → cjs/store}/actions/put.d.ts

@@ -7,8 +7,8 @@
  * A `null` value takes the delete path instead. A caller hands over an item;
  * that the table commits first and the vector copy follows is decided here.
  */
-import type { ParsedDelete, ParsedPut } from '../internal/parse';
-import type { StoreContext } from '../internal/setup';
+import type { ParsedDelete, ParsedPut } from '../internal/parse.js';
+import type { StoreContext } from '../internal/setup.js';
 /**
  * Store, update or delete an item.
  *
@@ -22,12 +22,19 @@ import type { StoreContext } from '../internal/setup';
  * Returns: nothing. Deleting an item that is not there is not an error.
  *
  * Throws: `VALIDATION` naming `value` for a value that JSON cannot represent —
- * refused at the write rather than stored as a row that can never be read back;
+ * refused at the write rather than stored as a row that can never be read
+ * back — or naming `payload` for one too large to store inline without `s3`,
+ * or, once offloaded, larger than `s3.maxDownloadBytes`; `VALIDATION` again,
+ * naming `index` or `value`, for the built row — payload plus its inline
+ * vectors — over DynamoDB's 400 KB item limit, naming `index` when the
+ * vectors are what pushed it over, checked before anything is written;
  * `S3_OFFLOAD_FAILED`; whatever the write throws.
  *
  * Guarantees: DynamoDB holds the canonical item — the vector index is synced
  * afterwards and best-effort, so a backend outage never fails a put or leaves a
- * half-written item. `createdAt` survives every update. The superseded payload
+ * half-written item. `createdAt` survives every update of a live item; a put
+ * over a row that has expired but not yet been swept is a creation, since no
+ * reader could still see that item. The superseded payload
  * is deleted only once the new row is committed, and this put's own upload
  * only once a read proves its write did not land. Neither release reads the
  * row first: each put uploads under a key ending in an id of its own, so the

package/dist/cjs/store/actions/put.js

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

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

@@ -7,8 +7,8 @@
  * is then made to agree with the table belongs to the vector index, so the
  * store's method knows neither half.
  */
-import type { StoreContext } from '../internal/setup';
-import type { VectorReconcileResult } from '../types';
+import type { StoreContext } from '../internal/setup.js';
+import type { VectorReconcileResult } from '../types.js';
 /**
  * Repair the vector backend against the canonical DynamoDB items under
  * `namespacePrefix`: re-push every live embedding, and — when the backend
@@ -24,9 +24,9 @@ import type { VectorReconcileResult } from '../types';
  * Throws: `VALIDATION` naming `namespacePrefix` or `namespacePrefix element`
  * for an empty or malformed prefix, as `search` names it, and `vectorBackend`
  * when the store has no index or backend to reconcile;
- * `RESULT_TRUNCATED` past `maxScanItems`, since repairing from a
- * partial view would prune live vectors; whatever the reads, the embeddings
- * model and the backend throw.
+ * `RESULT_TRUNCATED` past `maxScanItems` or `maxIterations`, since repairing
+ * from a partial view would prune live vectors; whatever the reads, the
+ * embeddings model and the backend throw.
  *
  * Guarantees: re-embeds with the store's configured fields, so a per-put
  * `index` field override is not reproduced — a reconcile makes the backend

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

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

package/dist/{store → cjs/store}/actions/search.d.ts

@@ -8,8 +8,8 @@
  * of page whichever path ran, scored exactly when a query could be ranked.
  */
 import type { SearchItem } from '@langchain/langgraph-checkpoint';
-import type { ParsedSearch } from '../internal/parse';
-import type { StoreContext } from '../internal/setup';
+import type { ParsedSearch } from '../internal/parse.js';
+import type { StoreContext } from '../internal/setup.js';
 /**
  * Search items under a namespace prefix: metadata filtering plus optional
  * semantic ranking.