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

package/dist/shared/logging/secret-patterns.js

@@ -1,26 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_SECRET_VALUE_PATTERNS = exports.DEFAULT_SECRET_KEY_PATTERNS = exports.REDACTED = void 0;
+exports.normaliseKey = normaliseKey;
 exports.isSecretKey = isSecretKey;
+exports.redactedMessage = redactedMessage;
 exports.redactText = redactText;
 exports.binaryLabel = binaryLabel;
 exports.redactErrorText = redactErrorText;
 /** Marker substituted for anything recognised as secret. */
 exports.REDACTED = '[REDACTED]';
-/** Key names (matched case-insensitively as substrings) whose value is a secret. */
+/**
+ * Key names whose value is a secret. Each entry is a *normalised* name — see
+ * {@link normaliseKey} — and matches a key whose normalised form equals it or
+ * ends with it. Suffix matching is what catches `secretAccessKey`, `x-api-key`,
+ * `client_secret` and `AUTH_TOKEN`; requiring the pattern to be a suffix, not a
+ * substring, is what spares `maxTokens`, `total_tokens`, `tokenizer` and
+ * `secretary`, which the old substring rule redacted.
+ */
 exports.DEFAULT_SECRET_KEY_PATTERNS = [
     'accesskey',
-    'secretkey',
+    'accesskeyid',
     'secret',
     'sessiontoken',
     'securitytoken',
     'authorization',
     'password',
+    'passwd',
+    'passphrase',
     'apikey',
     'bearer',
     'token',
     'privatekey',
 ];
+/**
+ * Canonical form of a key name for matching: lower-case with every character
+ * that is not a letter or digit removed, so `api_key`, `x-api-key`, `ApiKey`
+ * and `API KEY` all become `apikey`.
+ */
+function normaliseKey(key) {
+    return key.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
 /**
  * Secret shapes recognisable in free text, where key-name matching cannot
  * reach: an error's `message`/`stack`, or any other string value. Deliberately
@@ -59,10 +78,18 @@ exports.DEFAULT_SECRET_VALUE_PATTERNS = [
     /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
     /((?:aws_)?(?:secret_access_key|secretaccesskey|password|passwd|api_?key|token)["']?\s*[=:]\s*)(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|(?:-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null)(?=\s*[,}\]]|\s*$)|[^\r\n]+)/gi,
 ];
-/** True when `key` matches any secret-key pattern. */
+/** True when `key`'s normalised form equals or ends with any (normalised) pattern. */
 function isSecretKey(key, patterns) {
-    const lower = key.toLowerCase();
-    return patterns.some((pattern) => lower.includes(pattern));
+    const normalised = normaliseKey(key);
+    return patterns.some((pattern) => normalised === pattern || normalised.endsWith(pattern));
+}
+/**
+ * An error's message with recognised credential shapes redacted, for embedding
+ * in another error's message: a wrapper that quotes its cause must not leak a
+ * `password=` or token the cause happened to carry.
+ */
+function redactedMessage(error) {
+    return redactText(error.message, exports.DEFAULT_SECRET_VALUE_PATTERNS);
 }
 /**
  * Replace every recognised secret shape inside `value` with {@link REDACTED},
@@ -104,4 +131,3 @@ function redactErrorText(error, patterns) {
         changed: message !== error.message || stack !== error.stack,
     };
 }
-//# sourceMappingURL=secret-patterns.js.map

package/dist/shared/options.d.ts

@@ -1,7 +1,8 @@
-import type { DynamoDBClient, DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
 import type { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
 import type { CompressionConfig } from './codec/compression';
 import type { S3OffloadConfig } from './codec/s3/config';
+import type { RetryPolicy } from './dynamodb/retry-policy';
 import type { Logger } from './logging/logger';
 import type { TtlOption } from './validation/ttl';
 /**
@@ -15,12 +16,12 @@ export interface BaseAdapterOptions {
     client?: DynamoDBDocument;
     /** Config used to build a client when `client` is not provided. */
     clientConfig?: DynamoDBClientConfig;
-    /** Factory seam for constructing the underlying client (testing). */
-    createClient?: (config: DynamoDBClientConfig) => DynamoDBClient;
     /** Optional time-to-live applied to written items. */
     ttl?: TtlOption;
     /** Optional per-instance logger (defaults to a silent logger). */
     logger?: Logger;
+    /** Retry budget and backoff for every DynamoDB call (see the README "Retries and backoff"). */
+    retry?: RetryPolicy;
 }
 /** Options enabling payload compression and/or S3 offloading. */
 export interface CodecOptions {
@@ -29,4 +30,8 @@ export interface CodecOptions {
     /** S3 offload configuration for payloads over DynamoDB's item limit. */
     s3?: S3OffloadConfig;
 }
-//# sourceMappingURL=options.d.ts.map
+/** Per-call cancellation for the long-running adapter methods. */
+export interface CancelOptions {
+    /** Aborting it rejects the call with `AbortError` (`ABORTED`) at the next wait. */
+    signal?: AbortSignal;
+}

package/dist/shared/options.js

@@ -1,3 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=options.js.map

package/dist/shared/ulid.d.ts

@@ -1,10 +1,23 @@
+/**
+ * A CSPRNG-backed `rng` seam: uniform values in `[0, 1)` from `crypto.randomBytes`,
+ * drawn from a refilled pool so a burst of ids costs one syscall per 256
+ * digits rather than one per digit. `Math.random` is fine for uniqueness and
+ * ordering but is not a cryptographically secure source, which security
+ * baselines flag in identifier generation; the ULID spec recommends a CSPRNG.
+ */
+export declare function secureRng(): () => number;
+/**
+ * The 10 time characters every ULID generated at `timeMs` starts with. Used
+ * as a sort-key bound: every id from that millisecond onwards sorts at or
+ * after it, every earlier id before it.
+ */
+export declare function ulidTimePrefix(timeMs: number): string;
 /**
  * Build a monotonic ULID generator: lexicographically sortable 26-char ids
  * whose first 10 chars encode the millisecond timestamp. Ids strictly increase
  * even when the clock regresses or the same-millisecond random space overflows:
  * any non-advancing clock reuses the last timestamp and increments the random
  * component, carrying into the timestamp on overflow. `now`/`rng` are seams for
- * deterministic tests.
+ * deterministic tests; the default `rng` is {@link secureRng}.
  */
 export declare function createUlidFactory(now?: () => number, rng?: () => number): () => string;
-//# sourceMappingURL=ulid.d.ts.map

package/dist/shared/ulid.js

@@ -1,10 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.secureRng = secureRng;
+exports.ulidTimePrefix = ulidTimePrefix;
 exports.createUlidFactory = createUlidFactory;
+const node_crypto_1 = require("node:crypto");
 const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
 const ENCODING_LEN = 32;
 const TIME_CHARS = 10;
 const RANDOM_CHARS = 16;
+/** Bytes drawn per refill of the {@link secureRng} pool: 16 ids per syscall. */
+const RNG_POOL_BYTES = 256;
+/**
+ * A CSPRNG-backed `rng` seam: uniform values in `[0, 1)` from `crypto.randomBytes`,
+ * drawn from a refilled pool so a burst of ids costs one syscall per 256
+ * digits rather than one per digit. `Math.random` is fine for uniqueness and
+ * ordering but is not a cryptographically secure source, which security
+ * baselines flag in identifier generation; the ULID spec recommends a CSPRNG.
+ */
+function secureRng() {
+    let pool = Buffer.alloc(0);
+    let offset = 0;
+    return () => {
+        if (offset >= pool.length) {
+            pool = (0, node_crypto_1.randomBytes)(RNG_POOL_BYTES);
+            offset = 0;
+        }
+        const byte = pool[offset];
+        offset += 1;
+        return byte / 256;
+    };
+}
 function encodeTime(timeMs) {
     let remaining = Math.floor(timeMs);
     let out = '';
@@ -14,6 +39,14 @@ function encodeTime(timeMs) {
     }
     return out;
 }
+/**
+ * The 10 time characters every ULID generated at `timeMs` starts with. Used
+ * as a sort-key bound: every id from that millisecond onwards sorts at or
+ * after it, every earlier id before it.
+ */
+function ulidTimePrefix(timeMs) {
+    return encodeTime(timeMs);
+}
 function randomDigits(rng) {
     const digits = [];
     for (let i = 0; i < RANDOM_CHARS; i++) {
@@ -38,9 +71,9 @@ function incrementDigits(digits) {
  * even when the clock regresses or the same-millisecond random space overflows:
  * any non-advancing clock reuses the last timestamp and increments the random
  * component, carrying into the timestamp on overflow. `now`/`rng` are seams for
- * deterministic tests.
+ * deterministic tests; the default `rng` is {@link secureRng}.
  */
-function createUlidFactory(now = Date.now, rng = Math.random) {
+function createUlidFactory(now = Date.now, rng = secureRng()) {
     let lastTime = -1;
     let lastRandom = [];
     return () => {
@@ -62,4 +95,3 @@ function createUlidFactory(now = Date.now, rng = Math.random) {
         return encodeTime(lastTime) + lastRandom.map((digit) => ENCODING[digit]).join('');
     };
 }
-//# sourceMappingURL=ulid.js.map

package/dist/shared/validation/options.d.ts

@@ -0,0 +1,8 @@
+import type { BaseAdapterOptions, CodecOptions } from '../options';
+/**
+ * Validate the options every adapter shares, at construction. Each failure is
+ * a {@link ValidationError} whose `context.field` names the offending option,
+ * so a misconfiguration surfaces where it was written instead of as a raw AWS
+ * error on the first request.
+ */
+export declare function validateBaseAdapterOptions(options: BaseAdapterOptions & CodecOptions): void;

package/dist/shared/validation/options.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateBaseAdapterOptions = validateBaseAdapterOptions;
+const config_1 = require("../codec/s3/config");
+const constants_1 = require("../constants");
+const errors_1 = require("../errors/errors");
+const primitives_1 = require("./primitives");
+const ttl_1 = require("./ttl");
+/** DynamoDB's table-name rule: 3–255 characters from `[A-Za-z0-9_.-]`. */
+const TABLE_NAME_PATTERN = /^[A-Za-z0-9_.-]{3,255}$/;
+/** Server-side encryption algorithms S3 accepts for `PutObject`. */
+const SSE_ALGORITHMS = ['AES256', 'aws:kms', 'aws:kms:dsse'];
+function validateTableName(tableName) {
+    if (typeof tableName !== 'string' || !TABLE_NAME_PATTERN.test(tableName)) {
+        throw new errors_1.ValidationError('tableName must be 3-255 characters from [A-Za-z0-9_.-], as DynamoDB requires', 'tableName');
+    }
+}
+/**
+ * An injected `client` is used as-is, so a `clientConfig` or `createClient`
+ * given alongside it would be silently ignored — including a `region` the
+ * caller believes is in effect. Reject the combination instead.
+ */
+function validateClientChoice(options) {
+    if (options.client &&
+        (options.clientConfig !== undefined || options.createClient !== undefined)) {
+        throw new errors_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');
+    }
+}
+function validateRetryPolicy(policy) {
+    if (policy.maxAttempts !== undefined) {
+        (0, primitives_1.validateInteger)(policy.maxAttempts, 'retry.maxAttempts', { min: 1, max: constants_1.MAX_RETRY_ATTEMPTS });
+    }
+    if (policy.baseDelayMs !== undefined) {
+        (0, primitives_1.validateInteger)(policy.baseDelayMs, 'retry.baseDelayMs', { min: 1 });
+    }
+    if (policy.maxDelayMs !== undefined) {
+        (0, primitives_1.validateInteger)(policy.maxDelayMs, 'retry.maxDelayMs', { min: policy.baseDelayMs ?? 1 });
+    }
+}
+function validateCompression(config) {
+    if (typeof config.enabled !== 'boolean') {
+        throw new errors_1.ValidationError('compression.enabled must be a boolean', 'compression.enabled');
+    }
+    if (config.level !== undefined) {
+        (0, primitives_1.validateInteger)(config.level, 'compression.level', { min: 0, max: 9 });
+    }
+    if (config.minSizeBytes !== undefined) {
+        (0, primitives_1.validateInteger)(config.minSizeBytes, 'compression.minSizeBytes', { min: 0 });
+    }
+    if (config.maxDecompressedBytes !== undefined) {
+        (0, primitives_1.validateInteger)(config.maxDecompressedBytes, 'compression.maxDecompressedBytes', { min: 1 });
+    }
+}
+function validateS3(config) {
+    (0, primitives_1.validateNonEmptyString)(config.bucketName, 's3.bucketName');
+    if (config.thresholdBytes !== undefined) {
+        (0, primitives_1.validateInteger)(config.thresholdBytes, 's3.thresholdBytes', {
+            min: 1,
+            max: constants_1.MAX_INLINE_PAYLOAD_BYTES,
+        });
+    }
+    if (config.keyPrefix !== undefined)
+        (0, config_1.assertScopedKeyPrefix)(config.keyPrefix);
+    if (config.maxDownloadBytes !== undefined) {
+        (0, primitives_1.validateInteger)(config.maxDownloadBytes, 's3.maxDownloadBytes', { min: 1 });
+    }
+    if (config.serverSideEncryption !== undefined &&
+        !SSE_ALGORITHMS.includes(config.serverSideEncryption)) {
+        throw new errors_1.ValidationError(`s3.serverSideEncryption must be one of ${SSE_ALGORITHMS.join(', ')}`, 's3.serverSideEncryption');
+    }
+}
+/**
+ * Validate the options every adapter shares, at construction. Each failure is
+ * a {@link ValidationError} whose `context.field` names the offending option,
+ * so a misconfiguration surfaces where it was written instead of as a raw AWS
+ * error on the first request.
+ */
+function validateBaseAdapterOptions(options) {
+    validateTableName(options.tableName);
+    validateClientChoice(options);
+    if (options.ttl !== undefined)
+        (0, ttl_1.resolveTtlSeconds)(options.ttl);
+    if (options.retry !== undefined)
+        validateRetryPolicy(options.retry);
+    if (options.compression !== undefined)
+        validateCompression(options.compression);
+    if (options.s3 !== undefined)
+        validateS3(options.s3);
+}

package/dist/shared/validation/primitives.d.ts

@@ -1,6 +1,11 @@
-import type { Redactable } from '../logging/redaction-walk';
-/** Throw {@link ValidationError} unless `value` is a non-empty string. */
+/**
+ * Throw {@link ValidationError} unless `value` is a string with at least one
+ * non-whitespace character: a blank identifier is never intended and would
+ * otherwise become an invisible, un-greppable DynamoDB key.
+ */
 export declare function validateNonEmptyString(value: string, field: string): void;
+/** Throw {@link ValidationError} if `value` exceeds `maxBytes` when encoded as UTF-8. */
+export declare function assertMaxBytes(value: string, field: string, maxBytes: number): void;
 /** Throw {@link ValidationError} unless `value` is an integer within bounds. */
 export declare function validateInteger(value: number, field: string, bounds?: {
     min?: number;
@@ -14,12 +19,11 @@ export declare function assertNoControlChars(value: string, field: string): void
 export declare function assertNoSeparator(value: string, separator: string, field: string): void;
 /**
  * Validate a caller-supplied identifier that reaches a DynamoDB key: non-empty,
- * free of the reserved `separator`, and free of control characters. The last
- * rule matters even though DynamoDB itself accepts control characters — an
- * identifier is echoed into logs, so an unvalidated ANSI escape is a
- * log/terminal-injection surface for any app that writes these values out.
+ * at most `maxBytes` of UTF-8, free of the reserved `separator`, and free of
+ * control characters. The last rule matters even though DynamoDB itself
+ * accepts control characters — an identifier is echoed into logs, so an
+ * unvalidated ANSI escape is a log/terminal-injection surface for any app that
+ * writes these values out. The length check runs before the character scans so
+ * an oversized value is rejected without being walked.
  */
-export declare function validateIdentifier(value: string, separator: string, field: string): void;
-/** Throw {@link ValidationError} if nested-array depth exceeds `maxDepth`. */
-export declare function validateArrayMaxDepth(value: Redactable[], field: string, maxDepth: number): void;
-//# sourceMappingURL=primitives.d.ts.map
+export declare function validateIdentifier(value: string, separator: string, field: string, maxBytes: number): void;

package/dist/shared/validation/primitives.js

@@ -1,17 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateNonEmptyString = validateNonEmptyString;
+exports.assertMaxBytes = assertMaxBytes;
 exports.validateInteger = validateInteger;
 exports.validateNonEmptyArray = validateNonEmptyArray;
 exports.assertNoControlChars = assertNoControlChars;
 exports.assertNoSeparator = assertNoSeparator;
 exports.validateIdentifier = validateIdentifier;
-exports.validateArrayMaxDepth = validateArrayMaxDepth;
 const errors_1 = require("../errors/errors");
-/** Throw {@link ValidationError} unless `value` is a non-empty string. */
+/**
+ * Throw {@link ValidationError} unless `value` is a string with at least one
+ * non-whitespace character: a blank identifier is never intended and would
+ * otherwise become an invisible, un-greppable DynamoDB key.
+ */
 function validateNonEmptyString(value, field) {
-    if (typeof value !== 'string' || value.length === 0) {
-        throw new errors_1.ValidationError(`${field} must be a non-empty string`, field);
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new errors_1.ValidationError(`${field} must be a non-empty string (whitespace-only counts as empty)`, field);
+    }
+}
+/** Throw {@link ValidationError} if `value` exceeds `maxBytes` when encoded as UTF-8. */
+function assertMaxBytes(value, field, maxBytes) {
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes > maxBytes) {
+        throw new errors_1.ValidationError(`${field} must be at most ${maxBytes} bytes of UTF-8 (received ${bytes})`, field);
     }
 }
 /** Throw {@link ValidationError} unless `value` is an integer within bounds. */
@@ -56,29 +67,16 @@ function assertNoSeparator(value, separator, field) {
 }
 /**
  * Validate a caller-supplied identifier that reaches a DynamoDB key: non-empty,
- * free of the reserved `separator`, and free of control characters. The last
- * rule matters even though DynamoDB itself accepts control characters — an
- * identifier is echoed into logs, so an unvalidated ANSI escape is a
- * log/terminal-injection surface for any app that writes these values out.
+ * at most `maxBytes` of UTF-8, free of the reserved `separator`, and free of
+ * control characters. The last rule matters even though DynamoDB itself
+ * accepts control characters — an identifier is echoed into logs, so an
+ * unvalidated ANSI escape is a log/terminal-injection surface for any app that
+ * writes these values out. The length check runs before the character scans so
+ * an oversized value is rejected without being walked.
  */
-function validateIdentifier(value, separator, field) {
+function validateIdentifier(value, separator, field, maxBytes) {
     validateNonEmptyString(value, field);
+    assertMaxBytes(value, field, maxBytes);
     assertNoSeparator(value, separator, field);
     assertNoControlChars(value, field);
 }
-/** Throw {@link ValidationError} if nested-array depth exceeds `maxDepth`. */
-function validateArrayMaxDepth(value, field, maxDepth) {
-    const depthOf = (node, depth) => {
-        if (!Array.isArray(node)) {
-            return depth;
-        }
-        if (depth > maxDepth) {
-            return depth;
-        }
-        return node.reduce((max, child) => Math.max(max, depthOf(child, depth + 1)), depth);
-    };
-    if (depthOf(value, 0) > maxDepth) {
-        throw new errors_1.ValidationError(`${field} exceeds maximum array depth of ${maxDepth}`, field);
-    }
-}
-//# sourceMappingURL=primitives.js.map

package/dist/shared/validation/ttl.d.ts

@@ -4,7 +4,11 @@ export type TtlOption = {
 } | {
     seconds: number;
 };
-/** Validate a {@link TtlOption} and resolve it to a positive number of seconds. */
+/**
+ * Validate a {@link TtlOption} and resolve it to a positive number of seconds.
+ * Both forms share the same five-year cap, and an object carrying both keys is
+ * rejected instead of being resolved by whichever key happens to be checked first.
+ */
 export declare function resolveTtlSeconds(ttl: TtlOption): number;
 /**
  * Resolve a {@link TtlOption} into a DynamoDB TTL attribute value: the Unix
@@ -13,9 +17,12 @@ export declare function resolveTtlSeconds(ttl: TtlOption): number;
  * @param now - Clock seam returning epoch milliseconds. Defaults to `Date.now`.
  */
 export declare function calculateTtlTimestamp(ttl: TtlOption, now?: () => number): number;
-/** Resolve a {@link TtlOption} to whole days, rounded up so the S3 lifecycle
- * expiration never fires before DynamoDB's own TTL sweep (which can lag up
- * to ~48h past the TTL timestamp) — expiring the S3 object first would leave
- * a live DynamoDB item pointing at a deleted payload. */
-export declare function resolveTtlDaysCeil(ttl: TtlOption): number;
-//# sourceMappingURL=ttl.d.ts.map
+/**
+ * Days for the S3 lifecycle rule that backs a TTL: the TTL rounded up to whole
+ * days plus {@link S3_LIFECYCLE_SWEEP_MARGIN_DAYS}. S3 expires an object at the
+ * first midnight UTC at least that many days after creation, while DynamoDB
+ * can keep the row up to ~48 h past its `ttl`; without the margin an
+ * `{ days: N }` TTL expired the object on day N exactly, stranding a live row
+ * that pointed at a deleted payload until the sweep caught up.
+ */
+export declare function lifecycleExpirationDays(ttl: TtlOption): number;

package/dist/shared/validation/ttl.js

@@ -2,17 +2,32 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveTtlSeconds = resolveTtlSeconds;
 exports.calculateTtlTimestamp = calculateTtlTimestamp;
-exports.resolveTtlDaysCeil = resolveTtlDaysCeil;
+exports.lifecycleExpirationDays = lifecycleExpirationDays;
 const constants_1 = require("../constants");
+const errors_1 = require("../errors/errors");
 const primitives_1 = require("./primitives");
 const SECONDS_PER_DAY = 24 * 60 * 60;
-/** Validate a {@link TtlOption} and resolve it to a positive number of seconds. */
+/** Positive integer no greater than `max`, with a message that names what the cap means. */
+function validateWithinCap(value, field, max) {
+    (0, primitives_1.validateInteger)(value, field, { min: 1 });
+    if (value > max) {
+        throw new errors_1.ValidationError(`${field} must be <= ${max} (five years)`, field);
+    }
+}
+/**
+ * Validate a {@link TtlOption} and resolve it to a positive number of seconds.
+ * Both forms share the same five-year cap, and an object carrying both keys is
+ * rejected instead of being resolved by whichever key happens to be checked first.
+ */
 function resolveTtlSeconds(ttl) {
+    if ('days' in ttl && 'seconds' in ttl) {
+        throw new errors_1.ValidationError('ttl must specify either ttl.days or ttl.seconds, not both', 'ttl');
+    }
     if ('days' in ttl) {
-        (0, primitives_1.validateInteger)(ttl.days, 'ttl.days', { min: 1, max: constants_1.MAX_TTL_DAYS });
+        validateWithinCap(ttl.days, 'ttl.days', constants_1.MAX_TTL_DAYS);
         return ttl.days * SECONDS_PER_DAY;
     }
-    (0, primitives_1.validateInteger)(ttl.seconds, 'ttl.seconds', { min: 1, max: constants_1.MAX_TTL_SECONDS });
+    validateWithinCap(ttl.seconds, 'ttl.seconds', constants_1.MAX_TTL_SECONDS);
     return ttl.seconds;
 }
 /**
@@ -24,11 +39,14 @@ function resolveTtlSeconds(ttl) {
 function calculateTtlTimestamp(ttl, now = Date.now) {
     return Math.floor(now() / 1000) + resolveTtlSeconds(ttl);
 }
-/** Resolve a {@link TtlOption} to whole days, rounded up so the S3 lifecycle
- * expiration never fires before DynamoDB's own TTL sweep (which can lag up
- * to ~48h past the TTL timestamp) — expiring the S3 object first would leave
- * a live DynamoDB item pointing at a deleted payload. */
-function resolveTtlDaysCeil(ttl) {
-    return Math.ceil(resolveTtlSeconds(ttl) / SECONDS_PER_DAY);
+/**
+ * Days for the S3 lifecycle rule that backs a TTL: the TTL rounded up to whole
+ * days plus {@link S3_LIFECYCLE_SWEEP_MARGIN_DAYS}. S3 expires an object at the
+ * first midnight UTC at least that many days after creation, while DynamoDB
+ * can keep the row up to ~48 h past its `ttl`; without the margin an
+ * `{ days: N }` TTL expired the object on day N exactly, stranding a live row
+ * that pointed at a deleted payload until the sweep caught up.
+ */
+function lifecycleExpirationDays(ttl) {
+    return Math.ceil(resolveTtlSeconds(ttl) / SECONDS_PER_DAY) + constants_1.S3_LIFECYCLE_SWEEP_MARGIN_DAYS;
 }
-//# sourceMappingURL=ttl.js.map

package/dist/store/actions/get.d.ts

@@ -1,5 +1,13 @@
 import type { Item } from '@langchain/langgraph-checkpoint';
 import type { StoreContext } from '../internal/setup';
-/** Retrieve a single item by namespace and key (strongly consistent), or null. */
-export declare function getItem(context: StoreContext, namespace: string[], key: string): Promise<Item | null>;
-//# sourceMappingURL=get.d.ts.map
+/**
+ * Retrieve a single item by namespace and key (strongly consistent), or null.
+ *
+ * An offloaded item can lose a race with a concurrent overwrite: between the
+ * row read and the S3 download the writer commits a new descriptor and deletes
+ * the object this read was about to fetch. That surfaces as `NoSuchKey`, and
+ * one strongly-consistent re-read settles it — the row now points at the new
+ * object (return that), is gone (null), or still points at the same missing
+ * object (a genuine loss, rethrown). Any other download failure propagates.
+ */
+export declare function getItem(context: StoreContext, namespace: string[], key: string, signal?: AbortSignal): Promise<Item | null>;

package/dist/store/actions/get.js

@@ -1,35 +1,73 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getItem = getItem;
+const clock_1 = require("../../shared/clock");
+const codec_1 = require("../../shared/codec/codec");
+const payload_loss_1 = require("../../shared/codec/payload-loss");
+const expiry_1 = require("../../shared/dynamodb/expiry");
 const retry_1 = require("../../shared/dynamodb/retry");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
 const item_mapper_1 = require("../internal/item-mapper");
 const keys_1 = require("../internal/keys");
 const validation_1 = require("../internal/validation");
-/** Retrieve a single item by namespace and key (strongly consistent), or null. */
-async function getItem(context, namespace, key) {
-    (0, validation_1.validateNamespace)(namespace);
-    (0, validation_1.validateKey)(key);
+/**
+ * Read the row strongly consistently and narrow it rather than cast. A
+ * foreign row sharing this key has no `namespace`, and one carrying a `value`
+ * PayloadDescriptor in the same shape a store item uses (a checkpointer WRITE
+ * row) would otherwise decode cleanly and be handed back as the caller's own
+ * value.
+ */
+async function readRow(context, namespace, key, signal) {
     const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
         TableName: context.tableName,
         Key: { PK: (0, keys_1.partitionKey)(namespace), SK: (0, keys_1.sortKey)(namespace, key) },
         ConsistentRead: true,
-    }));
+    }), (0, retry_policy_1.retryFor)(context, signal));
     if (!result.Item)
-        return null;
-    /**
-     * Narrow rather than cast. A foreign row sharing this key has no
-     * `namespace`, and one carrying a `value` PayloadDescriptor in the same
-     * shape a store item uses (a checkpointer WRITE row) would otherwise decode
-     * cleanly and be handed back as the caller's own value.
-     */
+        return undefined;
     const record = (0, item_mapper_1.narrowStoreRecord)(result.Item);
     if (!record) {
         context.logger.warn('store.get: ignored a row that is not a store item', {
             partitionKey: (0, keys_1.partitionKey)(namespace),
             sortKey: (0, keys_1.sortKey)(namespace, key),
         });
+        return undefined;
+    }
+    /** A row past its ttl is absent to every reader, however long DynamoDB's sweep lags. */
+    return (0, expiry_1.isExpiredRow)(record, (0, clock_1.nowSeconds)()) ? undefined : record;
+}
+/** True when both records point at the same offloaded object. */
+function sameObject(a, b) {
+    return (a.value.location === codec_1.PayloadLocation.S3 &&
+        b.value.location === codec_1.PayloadLocation.S3 &&
+        a.value.s3Key === b.value.s3Key);
+}
+/**
+ * Retrieve a single item by namespace and key (strongly consistent), or null.
+ *
+ * An offloaded item can lose a race with a concurrent overwrite: between the
+ * row read and the S3 download the writer commits a new descriptor and deletes
+ * the object this read was about to fetch. That surfaces as `NoSuchKey`, and
+ * one strongly-consistent re-read settles it — the row now points at the new
+ * object (return that), is gone (null), or still points at the same missing
+ * object (a genuine loss, rethrown). Any other download failure propagates.
+ */
+async function getItem(context, namespace, key, signal) {
+    (0, validation_1.validateStoreKey)(namespace, key);
+    const record = await readRow(context, namespace, key, signal);
+    if (!record)
         return null;
+    try {
+        return await (0, item_mapper_1.readStoreItem)(context, record);
+    }
+    catch (error) {
+        if (!(0, payload_loss_1.isMissingObjectError)(error))
+            throw error;
+        const fresh = await readRow(context, namespace, key, signal);
+        if (!fresh)
+            return null;
+        if (sameObject(record, fresh))
+            throw error;
+        return (0, item_mapper_1.readStoreItem)(context, fresh);
     }
-    return (0, item_mapper_1.readStoreItem)(context, record);
 }
-//# sourceMappingURL=get.js.map

package/dist/store/actions/list-namespaces.d.ts

@@ -6,4 +6,3 @@ import type { StoreContext } from '../internal/setup';
  * the read to a native Query; otherwise it falls back to a filtered Scan.
  */
 export declare function listNamespaces(context: StoreContext, op: ListNamespacesOperation): Promise<string[][]>;
-//# sourceMappingURL=list-namespaces.d.ts.map