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

package/dist/cjs/shared/codec/codec.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESCRIPTOR_SCHEMA_VERSION = exports.PayloadLocation = exports.MAX_INLINE_PAYLOAD_BYTES = void 0;
+exports.codecDepsOf = codecDepsOf;
+exports.readPayloadBytes = readPayloadBytes;
+exports.loadPayloadValue = loadPayloadValue;
+exports.decodePayload = decodePayload;
+exports.encodePayload = encodePayload;
+exports.collectS3Keys = collectS3Keys;
+exports.isMissingObjectError = isMissingObjectError;
+exports.isRefusedObjectError = isRefusedObjectError;
+exports.isPermanentPayloadLoss = isPermanentPayloadLoss;
+const base_error_js_1 = require("../errors/base-error.js");
+const classify_js_1 = require("../errors/classify.js");
+const error_code_js_1 = require("../errors/error-code.js");
+const errors_js_1 = require("../errors/errors.js");
+const truncate_js_1 = require("../logging/truncate.js");
+const compression_js_1 = require("./compression.js");
+const json_serde_js_1 = require("./json-serde.js");
+exports.MAX_INLINE_PAYLOAD_BYTES = 400 * 1024 - 8 * 1024;
+var PayloadLocation;
+(function (PayloadLocation) {
+    PayloadLocation["INLINE"] = "INLINE";
+    PayloadLocation["S3"] = "S3";
+})(PayloadLocation || (exports.PayloadLocation = PayloadLocation = {}));
+exports.DESCRIPTOR_SCHEMA_VERSION = 1;
+function codecDepsOf(source, signal) {
+    return {
+        serde: source.serde,
+        compression: source.compression,
+        offloader: source.offloader,
+        signal,
+    };
+}
+function configuredOffloader(deps) {
+    if (!deps.offloader) {
+        throw (0, errors_js_1.validationError)("this row's payload is offloaded to S3 but the adapter has no `s3` configuration; " +
+            'configure the bucket the writer used', 's3');
+    }
+    return deps.offloader;
+}
+function assertReadableDescriptor(descriptor) {
+    if (descriptor === null || typeof descriptor !== 'object') {
+        throw (0, errors_js_1.validationError)(`payload descriptor is ${descriptor === null ? 'null' : typeof descriptor}, not a descriptor ` +
+            'this library wrote', 'descriptor');
+    }
+    const version = descriptor.schemaVersion ?? exports.DESCRIPTOR_SCHEMA_VERSION;
+    if (version > exports.DESCRIPTOR_SCHEMA_VERSION) {
+        const written = (0, truncate_js_1.truncateForLog)(String(version));
+        throw new base_error_js_1.DynamoDBLangGraphError(`this payload was written in descriptor schema version ${written}; this version of the ` +
+            `library reads up to ${exports.DESCRIPTOR_SCHEMA_VERSION} — upgrade to read it`, error_code_js_1.ErrorCode.FORMAT_UNSUPPORTED, { field: 'schemaVersion' });
+    }
+    const locations = Object.values(PayloadLocation);
+    if (!locations.includes(descriptor.location)) {
+        const location = (0, truncate_js_1.truncateForLog)(String(JSON.stringify(descriptor.location)));
+        throw (0, errors_js_1.validationError)(`payload descriptor has an unknown location ${location}`, 'descriptor');
+    }
+    if (descriptor.location === PayloadLocation.S3 && typeof descriptor.s3Key !== 'string') {
+        throw (0, errors_js_1.validationError)('payload descriptor is offloaded but names no object key', 'descriptor');
+    }
+    if (descriptor.location === PayloadLocation.INLINE && !ArrayBuffer.isView(descriptor.bytes)) {
+        throw (0, errors_js_1.validationError)('payload descriptor is inline but carries no bytes', 'descriptor');
+    }
+}
+async function readPayloadBytes(descriptor, deps, scope) {
+    assertReadableDescriptor(descriptor);
+    let raw;
+    if (descriptor.location === PayloadLocation.S3) {
+        const offloader = configuredOffloader(deps);
+        offloader.assertOwnedKey(descriptor.s3Key, scope);
+        raw = await offloader.download(descriptor.s3Key, deps.signal);
+    }
+    else {
+        raw = descriptor.bytes;
+    }
+    return (0, compression_js_1.decompress)(raw, descriptor.compressed, deps.compression?.maxDecompressedBytes);
+}
+async function loadPayloadValue(serdeType, bytes, deps) {
+    try {
+        return (await deps.serde.loadsTyped(serdeType, bytes));
+    }
+    catch (error) {
+        const refusal = (0, base_error_js_1.toError)(error);
+        if ((0, base_error_js_1.isDynamoDBLangGraphError)(refusal))
+            throw refusal;
+        if (!(0, json_serde_js_1.bytesHoldDeclaredForm)(serdeType, bytes)) {
+            throw new base_error_js_1.DynamoDBLangGraphError('the stored payload is no longer the form this row declares, so no serde could decode ' +
+                'it; the refusal that proved it is attached as `cause`', error_code_js_1.ErrorCode.PAYLOAD_CORRUPT, {}, refusal);
+        }
+        throw (0, errors_js_1.validationError)('the configured serde refused the payload stored in this row: the bytes parse, but the ' +
+            'serializer would not reconstruct the value they name — a stored `lc` constructor record ' +
+            'naming a class outside its allow-list reads this way, as does a serde that did not ' +
+            'write these bytes. The refusal itself is attached as `cause`', 'serde', refusal);
+    }
+}
+async function decodePayload(descriptor, deps, scope) {
+    const bytes = await readPayloadBytes(descriptor, deps, scope);
+    return loadPayloadValue(descriptor.serdeType, bytes, deps);
+}
+function assertInlinePayloadFits(bytes, deps) {
+    if (bytes.length <= exports.MAX_INLINE_PAYLOAD_BYTES)
+        return;
+    const hint = deps.compression?.enabled
+        ? ''
+        : ', or enable compression if the data compresses well';
+    throw (0, errors_js_1.validationError)(`payload of ${bytes.length} bytes exceeds the ${exports.MAX_INLINE_PAYLOAD_BYTES}-byte inline limit ` +
+        `(DynamoDB items are capped at 400 KB); configure s3 offloading${hint}`, 'payload');
+}
+function assertSerialisedToBytes(raw) {
+    if (raw.length > 0)
+        return;
+    throw (0, errors_js_1.validationError)('value serialises to zero bytes, which no reader can parse back: a function, a symbol ' +
+        'or any value the configured serde drops encodes to nothing. Store a value the serde ' +
+        'can represent, or configure one that refuses it.', 'value');
+}
+async function encodePayload(value, deps, options) {
+    const [serdeType, raw] = await deps.serde.dumpsTyped(value);
+    assertSerialisedToBytes(raw);
+    const { bytes, compressed } = deps.compression
+        ? await (0, compression_js_1.compress)(raw, deps.compression)
+        : { bytes: raw, compressed: false };
+    const base = {
+        schemaVersion: exports.DESCRIPTOR_SCHEMA_VERSION,
+        serdeType,
+        compressed,
+        writeId: options.objectId,
+    };
+    if (deps.offloader && deps.offloader.shouldOffload(bytes)) {
+        const s3Key = deps.offloader.buildKey(options.keyParts, options.objectId);
+        await deps.offloader.upload(s3Key, bytes, options.row, deps.signal);
+        return { ...base, location: PayloadLocation.S3, s3Key };
+    }
+    if (!deps.offloader)
+        assertInlinePayloadFits(bytes, deps);
+    return { ...base, location: PayloadLocation.INLINE, bytes };
+}
+function collectS3Keys(descriptors) {
+    const keys = [];
+    for (const descriptor of descriptors) {
+        if (descriptor?.location === PayloadLocation.S3 && descriptor.s3Key !== undefined) {
+            keys.push(descriptor.s3Key);
+        }
+    }
+    return keys;
+}
+function isMissingObjectError(error) {
+    return ((0, base_error_js_1.hasErrorCode)(error, error_code_js_1.ErrorCode.S3_OFFLOAD_FAILED) &&
+        error.cause !== undefined &&
+        (0, classify_js_1.isMissingObject)(error.cause));
+}
+function isRefusedObjectError(error) {
+    return ((0, base_error_js_1.hasErrorCode)(error, error_code_js_1.ErrorCode.S3_OFFLOAD_FAILED) &&
+        (0, classify_js_1.classifyAwsError)(error.cause) === error_code_js_1.ErrorCode.ACCESS_DENIED);
+}
+function isUnreadableDescriptor(error) {
+    return (0, base_error_js_1.hasErrorCode)(error, error_code_js_1.ErrorCode.VALIDATION) && error.context.field === 'descriptor';
+}
+function isPermanentPayloadLoss(error) {
+    return ((0, base_error_js_1.hasErrorCode)(error, error_code_js_1.ErrorCode.PAYLOAD_CORRUPT) ||
+        isMissingObjectError(error) ||
+        isUnreadableDescriptor(error));
+}

package/dist/{shared → cjs/shared}/codec/compression.d.ts

@@ -32,7 +32,8 @@ export interface CompressionResult {
  * returns the input untouched. `config.minSizeBytes` — the size below which
  * gzip is not attempted, default {@link DEFAULT_COMPRESSION_MIN_BYTES}.
  * `config.level` — zlib level 0–9, default {@link DEFAULT_COMPRESSION_LEVEL}.
- * `config.maxDecompressedBytes` is read on the way back, not here.
+ * `config.maxDecompressedBytes` — a payload larger than it is stored
+ * uncompressed, since no reader configured like this writer would inflate it.
  *
  * Returns: `compressed: true` only when gzip beat the input by more than 10%;
  * otherwise the input bytes and `compressed: false`. The flag is recorded in
@@ -54,8 +55,12 @@ export declare function compress(data: Uint8Array, config: CompressionConfig): P
  * Returns: the decoded bytes.
  *
  * Throws: `COMPRESSION_LIMIT` when the output would exceed `maxBytes`, and
- * `PAYLOAD_CORRUPT` when `compressed` is true but the bytes are not gzip. Both
- * are permanent for that payload ({@link isPermanentPayloadLoss}), so a caller
- * reports rather than retries.
+ * `PAYLOAD_CORRUPT` when `compressed` is true but the bytes are not gzip.
+ * `PAYLOAD_CORRUPT` is permanent for that payload
+ * ({@link isPermanentPayloadLoss}). `COMPRESSION_LIMIT` is this reader's
+ * limit, not the payload's loss: a reader with a larger cap reads it. From
+ * this release on, `compress` never produces a payload past its writer's own
+ * cap; a payload an earlier release compressed — which did not check it —
+ * can still exceed a smaller `maxBytes` here.
  */
 export declare function decompress(data: Uint8Array, compressed: boolean, maxBytes?: number): Promise<Uint8Array>;

package/dist/cjs/shared/codec/compression.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_DECOMPRESSED_BYTES = exports.DEFAULT_COMPRESSION_LEVEL = exports.DEFAULT_COMPRESSION_MIN_BYTES = void 0;
+exports.compress = compress;
+exports.decompress = decompress;
+const node_util_1 = require("node:util");
+const node_zlib_1 = require("node:zlib");
+const base_error_js_1 = require("../errors/base-error.js");
+const error_code_js_1 = require("../errors/error-code.js");
+const gzipAsync = (0, node_util_1.promisify)(node_zlib_1.gzip);
+const gunzipAsync = (0, node_util_1.promisify)(node_zlib_1.gunzip);
+const COMPRESSION_GAIN_RATIO = 0.9;
+exports.DEFAULT_COMPRESSION_MIN_BYTES = 1024;
+exports.DEFAULT_COMPRESSION_LEVEL = 6;
+exports.DEFAULT_MAX_DECOMPRESSED_BYTES = 50 * 1024 * 1024;
+async function compress(data, config) {
+    const minSize = config.minSizeBytes ?? exports.DEFAULT_COMPRESSION_MIN_BYTES;
+    const readable = config.maxDecompressedBytes ?? exports.DEFAULT_MAX_DECOMPRESSED_BYTES;
+    if (!config.enabled || data.length < minSize || data.length > readable) {
+        return { bytes: data, compressed: false };
+    }
+    const level = config.level ?? exports.DEFAULT_COMPRESSION_LEVEL;
+    const gzipped = new Uint8Array(await gzipAsync(data, { level }));
+    if (gzipped.length >= data.length * COMPRESSION_GAIN_RATIO) {
+        return { bytes: data, compressed: false };
+    }
+    return { bytes: gzipped, compressed: true };
+}
+function corruptPayload(cause) {
+    return new base_error_js_1.DynamoDBLangGraphError('the stored payload is marked compressed but is not valid gzip, so it cannot be decoded', error_code_js_1.ErrorCode.PAYLOAD_CORRUPT, {}, cause);
+}
+async function decompress(data, compressed, maxBytes = exports.DEFAULT_MAX_DECOMPRESSED_BYTES) {
+    if (!compressed)
+        return data;
+    try {
+        return new Uint8Array(await gunzipAsync(data, { maxOutputLength: maxBytes }));
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ERR_BUFFER_TOO_LARGE') {
+            throw new base_error_js_1.DynamoDBLangGraphError(`Refusing to decompress: output would exceed ${maxBytes} bytes`, error_code_js_1.ErrorCode.COMPRESSION_LIMIT, {}, error);
+        }
+        throw corruptPayload(error);
+    }
+}

package/dist/cjs/shared/codec/json-serde.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSON_SERDE = void 0;
+exports.bytesHoldDeclaredForm = bytesHoldDeclaredForm;
+const base_error_js_1 = require("../errors/base-error.js");
+const error_code_js_1 = require("../errors/error-code.js");
+const errors_js_1 = require("../errors/errors.js");
+const truncate_js_1 = require("../logging/truncate.js");
+exports.JSON_SERDE = {
+    async dumpsTyped(value) {
+        let text;
+        try {
+            text = JSON.stringify(value);
+        }
+        catch (error) {
+            throw (0, errors_js_1.validationError)('value cannot be serialized as JSON — a circular structure, or a value JSON has no ' +
+                'encoding for such as a BigInt; the refusal itself is attached as `cause`', 'value', (0, base_error_js_1.toError)(error));
+        }
+        if (text === undefined) {
+            throw (0, errors_js_1.validationError)('value has no JSON representation (undefined, a function or a symbol), so it cannot be ' +
+                'stored; store null instead to record an absent value', 'value');
+        }
+        return Promise.resolve([JSON_SERDE_TYPE, new TextEncoder().encode(text)]);
+    },
+    async loadsTyped(type, data) {
+        if (type !== JSON_SERDE_TYPE) {
+            throw (0, errors_js_1.validationError)(`this serializer reads only the \`${JSON_SERDE_TYPE}\` form it writes, and this payload ` +
+                `declares ${(0, truncate_js_1.truncateForLog)(String(JSON.stringify(type)))}; read the row with the ` +
+                'serializer that wrote it, or rewrite the row', 'serde');
+        }
+        let text;
+        try {
+            text = typeof data === 'string' ? data : new TextDecoder().decode(data);
+        }
+        catch (error) {
+            throw (0, errors_js_1.validationError)('data must be the bytes or text this serializer wrote, as a Uint8Array or a string', 'data', error);
+        }
+        try {
+            return Promise.resolve(JSON.parse(text));
+        }
+        catch (error) {
+            throw new base_error_js_1.DynamoDBLangGraphError('the stored payload is not the JSON this serializer wrote, so it cannot be decoded', error_code_js_1.ErrorCode.PAYLOAD_CORRUPT, {}, error);
+        }
+    },
+};
+Object.freeze(exports.JSON_SERDE);
+const JSON_SERDE_TYPE = 'json';
+function bytesHoldDeclaredForm(serdeType, bytes) {
+    if (serdeType !== JSON_SERDE_TYPE)
+        return true;
+    try {
+        JSON.parse(new TextDecoder().decode(bytes));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/{shared → cjs/shared}/codec/s3/client-types.d.ts

@@ -40,7 +40,7 @@ export type S3ClientConfigLike = S3ClientOptions | object;
  */
 export declare function s3ClientOptions(config: S3ClientConfigLike | undefined): S3ClientOptions;
 /** What every SDK command object carries: its `input`. */
-export interface S3CommandLike {
+interface S3CommandLike {
     input: object;
 }
 /**
@@ -51,3 +51,4 @@ export interface S3ClientLike {
     send(command: S3CommandLike, options?: object): Promise<object>;
     destroy(): void;
 }
+export {};

package/dist/cjs/shared/codec/s3/client-types.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.s3ClientOptions = s3ClientOptions;
+function s3ClientOptions(config) {
+    return (config ?? {});
+}

package/dist/{shared → cjs/shared}/codec/s3/client.d.ts

@@ -9,7 +9,7 @@
  * bounds a stalled transfer without bounding a slow one.
  */
 import type { S3Client } from '@aws-sdk/client-s3';
-import type { S3ClientConfigLike } from './client-types';
+import { type S3ClientConfigLike, type S3ClientOptions } from './client-types.js';
 type S3Sdk = typeof import('@aws-sdk/client-s3');
 /**
  * The optional `@aws-sdk/client-s3` peer, imported on first use.
@@ -21,18 +21,24 @@ type S3Sdk = typeof import('@aws-sdk/client-s3');
  * Throws: `VALIDATION` naming `s3` when the package is not installed,
  * carrying the install command; any other import failure — a broken build, a
  * syntax error inside the package — passes through unchanged. A failure is not
- * cached, so an install or a fixed bundle succeeds on a later call.
+ * cached, so an install or a fixed bundle succeeds on a later call. Each
+ * concurrent caller of a failed import gets its own error instance
+ * (`copyForCaller`), so the public boundary stamping one's `context.operation`
+ * cannot leave it sitting in another caller's error too.
  */
 export declare function loadS3Sdk(): Promise<S3Sdk>;
 /**
- * An `S3Client` built from `config` with the lazily-loaded SDK.
+ * `config` with the two defaults every S3 client of this library is built
+ * with, whichever constructor builds it.
  *
- * Accepts: `config` — any `S3ClientConfig`; an explicit `maxAttempts` or
- * `requestHandler` wins over the defaults below.
+ * Accepts: `config` — the caller's `s3.clientConfig`, or an empty object.
  *
- * Returns: the client. The caller owns it and destroys it.
+ * Returns: a copy whose `maxAttempts` and `requestHandler` are the caller's
+ * own where it gave one and the default where it did not. A key named with
+ * `undefined` — a config assembled from settings that were not all set — gave
+ * none, and keeps the default.
  *
- * Throws: whatever {@link loadS3Sdk} throws.
+ * Throws: nothing.
  *
  * Guarantees: `maxAttempts` defaults to 1, so the SDK performs no retries of
  * its own and this library's retry, backoff and classification are the only
@@ -41,5 +47,17 @@ export declare function loadS3Sdk(): Promise<S3Sdk>;
  * stalled, which `maxAttempts` alone does not; a `requestHandler` in `config`
  * replaces it whole rather than merging with it.
  */
+export declare function withS3ClientDefaults(config: S3ClientConfigLike): S3ClientOptions;
+/**
+ * An `S3Client` built from `config` with the lazily-loaded SDK.
+ *
+ * Accepts: `config` — any `S3ClientConfig`; an explicit `maxAttempts` or
+ * `requestHandler` wins over the defaults {@link withS3ClientDefaults} fills
+ * in.
+ *
+ * Returns: the client. The caller owns it and destroys it.
+ *
+ * Throws: whatever {@link loadS3Sdk} throws.
+ */
 export declare function createDefaultS3Client(config: S3ClientConfigLike): Promise<S3Client>;
 export {};

package/dist/cjs/shared/codec/s3/client.js

@@ -0,0 +1,78 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadS3Sdk = loadS3Sdk;
+exports.withS3ClientDefaults = withS3ClientDefaults;
+exports.createDefaultS3Client = createDefaultS3Client;
+const client_js_1 = require("../../dynamodb/client.js");
+const base_error_js_1 = require("../../errors/base-error.js");
+const errors_js_1 = require("../../errors/errors.js");
+const client_types_js_1 = require("./client-types.js");
+const MISSING_MODULE_CODES = ['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND'];
+let sdkPromise;
+function wrapMissingPeer(error) {
+    const code = error.code;
+    if (code !== undefined && MISSING_MODULE_CODES.includes(code)) {
+        throw (0, errors_js_1.validationError)('S3 offload requires the optional peer @aws-sdk/client-s3 (npm install @aws-sdk/client-s3); ' +
+            'bundlers must keep it installed or external', 's3', error);
+    }
+    throw error;
+}
+async function loadS3Sdk() {
+    if (!sdkPromise) {
+        sdkPromise = Promise.resolve().then(() => __importStar(require('@aws-sdk/client-s3'))).catch((error) => {
+            sdkPromise = undefined;
+            return wrapMissingPeer(error);
+        });
+    }
+    try {
+        return await sdkPromise;
+    }
+    catch (error) {
+        throw (0, base_error_js_1.copyForCaller)(error);
+    }
+}
+function withS3ClientDefaults(config) {
+    const options = (0, client_types_js_1.s3ClientOptions)(config);
+    return {
+        ...options,
+        maxAttempts: options.maxAttempts ?? 1,
+        requestHandler: options.requestHandler ?? { socketTimeout: client_js_1.DEFAULT_SOCKET_TIMEOUT_MS },
+    };
+}
+async function createDefaultS3Client(config) {
+    const { S3Client: S3ClientCtor } = await loadS3Sdk();
+    return new S3ClientCtor(withS3ClientDefaults(config));
+}

package/dist/{shared → cjs/shared}/codec/s3/config.d.ts

@@ -9,7 +9,7 @@
  * rule ids derived from a prefix are part of the same layout.
  */
 import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
-import { type S3ClientConfigLike } from './client-types';
+import { type S3ClientConfigLike } from './client-types.js';
 /** Default S3 key prefix for offloaded payloads. */
 export declare const DEFAULT_S3_KEY_PREFIX = "langgraph-checkpoints/";
 /** S3 cap on an object key, applied to the produced offload key. */
@@ -21,16 +21,21 @@ export interface S3OffloadConfig {
     /**
      * Serialized payloads at or above this size are offloaded (default 350 KB).
      * Only the payload counts: the store's inline vectors live on the same item
-     * and are not part of it. The store embeds one vector **per configured
-     * field** (`index.fields`, one field by default), each about 10 bytes per
-     * dimension, so three fields at 1024 dims cost roughly 30 KB, not 10 KB.
-     * Keep `thresholdBytes` plus that total under DynamoDB's 400 KB item limit
-     * or the put fails, surfaced as `AWS_REJECTED`.
+     * and are not part of it. The store embeds one vector per text its
+     * `index.fields` extract — a wildcard path yields one per element — each up
+     * to about 10 bytes per dimension, so three texts at 1024 dims cost roughly
+     * 30 KB. A row that payload and those vectors would take past DynamoDB's
+     * 400 KB item limit is refused with `VALIDATION` naming `index`.
      */
     thresholdBytes?: number;
     serverSideEncryption?: string;
     sseKmsKeyId?: string;
-    /** Largest object this adapter will buffer from S3 (default 50 MiB). */
+    /**
+     * Largest object this adapter will buffer from S3 (default 50 MiB). An
+     * offloaded payload larger than it is refused at the write, and a value
+     * below `thresholdBytes` is refused at construction, so an adapter never
+     * stores an object it could not read back.
+     */
     maxDownloadBytes?: number;
     /**
      * S3 client configuration (an `S3ClientConfig`). `region` defaults to the

package/dist/cjs/shared/codec/s3/config.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_S3_KEY_BYTES = exports.DEFAULT_S3_KEY_PREFIX = void 0;
+exports.encodeKeyPart = encodeKeyPart;
+exports.buildS3Key = buildS3Key;
+exports.assertScopedKeyPrefix = assertScopedKeyPrefix;
+exports.buildLifecycleRuleId = buildLifecycleRuleId;
+exports.buildMarkerRuleId = buildMarkerRuleId;
+exports.defaultAdapterKeyPrefix = defaultAdapterKeyPrefix;
+exports.s3KeyScope = s3KeyScope;
+exports.isKeyInScope = isKeyInScope;
+exports.assertKeyInScope = assertKeyInScope;
+exports.offloaderConfigFor = offloaderConfigFor;
+const errors_js_1 = require("../../errors/errors.js");
+const truncate_js_1 = require("../../logging/truncate.js");
+const primitives_js_1 = require("../../validation/primitives.js");
+const client_types_js_1 = require("./client-types.js");
+exports.DEFAULT_S3_KEY_PREFIX = 'langgraph-checkpoints/';
+exports.MAX_S3_KEY_BYTES = 1024;
+function encodeKeyPart(part) {
+    return Buffer.from(part, 'utf8').toString('base64url');
+}
+function buildS3Key(prefix, parts, objectId) {
+    if (parts.length === 0) {
+        throw (0, errors_js_1.validationError)('an offloaded object needs the identity of the row that points at it; parts was empty', 's3Key');
+    }
+    const encoded = [...parts.map(encodeKeyPart), objectId];
+    const key = `${prefix}${encoded.join('/')}.bin`;
+    const bytes = Buffer.byteLength(key, 'utf8');
+    if (bytes > exports.MAX_S3_KEY_BYTES) {
+        throw (0, errors_js_1.validationError)(`the offloaded S3 object key would be ${bytes} bytes; S3 caps keys at ` +
+            `${exports.MAX_S3_KEY_BYTES} — shorten the identifiers or the keyPrefix`, 's3Key');
+    }
+    return key;
+}
+const UNSCOPED_SEGMENTS = new Set(['', '.', '..']);
+function assertScopedKeyPrefix(keyPrefix) {
+    if (typeof keyPrefix !== 'string' ||
+        keyPrefix === '' ||
+        keyPrefix === '/' ||
+        !keyPrefix.endsWith('/')) {
+        throw (0, errors_js_1.validationError)('s3.keyPrefix must be a non-empty path that ends with "/" (for example "langgraph/"): ' +
+            'it scopes both the offloaded objects and the S3 lifecycle rule', 's3.keyPrefix');
+    }
+    (0, primitives_js_1.assertNoControlChars)(keyPrefix, 's3.keyPrefix');
+    (0, primitives_js_1.assertWellFormed)(keyPrefix, 's3.keyPrefix');
+    if (keyPrefix
+        .slice(0, -1)
+        .split('/')
+        .some((segment) => UNSCOPED_SEGMENTS.has(segment))) {
+        throw (0, errors_js_1.validationError)('s3.keyPrefix must name a real path: no empty, "." or ".." segment (for example ' +
+            '"langgraph/", not "../langgraph/" or "/langgraph/"). Such a prefix addresses object ' +
+            'keys outside the path the IAM policy grants and the lifecycle rule sweeps', 's3.keyPrefix');
+    }
+}
+function buildLifecycleRuleId(prefix) {
+    let trimmed = prefix;
+    while (trimmed.endsWith('/'))
+        trimmed = trimmed.slice(0, -1);
+    const slug = trimmed.replace(/[^a-zA-Z0-9-]/g, '-') || 'default';
+    return `langgraph-ttl-${slug}`;
+}
+function buildMarkerRuleId(prefix) {
+    return `${buildLifecycleRuleId(prefix)}-markers`;
+}
+function defaultAdapterKeyPrefix(base, adapter) {
+    return `${base}${adapter}/`;
+}
+function s3KeyScope(prefix, parts) {
+    return `${prefix}${parts.map(encodeKeyPart).join('/')}`;
+}
+function isKeyInScope(key, prefix, parts) {
+    const scope = s3KeyScope(prefix, parts);
+    if (parts.length === 0)
+        return key.startsWith(scope);
+    return key === `${scope}.bin` || key.startsWith(`${scope}/`);
+}
+function assertKeyInScope(key, prefix, parts) {
+    if (isKeyInScope(key, prefix, parts))
+        return;
+    throw (0, errors_js_1.validationError)(`s3Key "${(0, truncate_js_1.truncateForLog)(key)}" lies outside the S3 path this row may reference ` +
+        `("${(0, truncate_js_1.truncateForLog)(s3KeyScope(prefix, parts))}"); refusing to touch an object the row ` +
+        'does not own', 's3Key');
+}
+function offloaderConfigFor(s3, adapter, clientConfig) {
+    const region = (0, client_types_js_1.s3ClientOptions)(s3.clientConfig).region ?? clientConfig?.region;
+    return {
+        ...s3,
+        keyPrefix: s3.keyPrefix ?? defaultAdapterKeyPrefix(exports.DEFAULT_S3_KEY_PREFIX, adapter),
+        ...(region === undefined ? {} : { clientConfig: { ...s3.clientConfig, region } }),
+    };
+}