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

package/dist/history/session-adapter.d.ts

@@ -1,23 +1,29 @@
 import { BaseListChatMessageHistory } from '@langchain/core/chat_history';
 import type { BaseMessage } from '@langchain/core/messages';
+/** The read window an adapter applies to every `getMessages`. */
+export type AdapterWindow = {
+    limit?: number;
+};
 /** The session-scoped operations a single-session adapter delegates to. */
 export interface SessionBackend {
-    getMessages(sessionId: string): Promise<BaseMessage[]>;
+    getMessages(sessionId: string, window?: AdapterWindow): Promise<BaseMessage[]>;
     addMessages(sessionId: string, messages: BaseMessage[]): Promise<void>;
     clear(sessionId: string): Promise<void>;
 }
 /**
  * Single-session view over a {@link SessionBackend}, implementing LangChain's
  * `BaseListChatMessageHistory` so it can drive `RunnableWithMessageHistory`.
+ * A `window` bounds what every read hands the chain — `{ limit: 50 }` feeds it
+ * the newest fifty messages instead of the whole session.
  */
 export declare class DynamoDBSessionChatMessageHistory extends BaseListChatMessageHistory {
     private readonly backend;
     private readonly sessionId;
+    private readonly window?;
     lc_namespace: string[];
-    constructor(backend: SessionBackend, sessionId: string);
+    constructor(backend: SessionBackend, sessionId: string, window?: AdapterWindow | undefined);
     getMessages(): Promise<BaseMessage[]>;
     addMessage(message: BaseMessage): Promise<void>;
     addMessages(messages: BaseMessage[]): Promise<void>;
     clear(): Promise<void>;
 }
-//# sourceMappingURL=session-adapter.d.ts.map

package/dist/history/session-adapter.js

@@ -5,18 +5,22 @@ const chat_history_1 = require("@langchain/core/chat_history");
 /**
  * Single-session view over a {@link SessionBackend}, implementing LangChain's
  * `BaseListChatMessageHistory` so it can drive `RunnableWithMessageHistory`.
+ * A `window` bounds what every read hands the chain — `{ limit: 50 }` feeds it
+ * the newest fifty messages instead of the whole session.
  */
 class DynamoDBSessionChatMessageHistory extends chat_history_1.BaseListChatMessageHistory {
     backend;
     sessionId;
+    window;
     lc_namespace = ['langchain', 'stores', 'message', 'dynamodb'];
-    constructor(backend, sessionId) {
+    constructor(backend, sessionId, window) {
         super();
         this.backend = backend;
         this.sessionId = sessionId;
+        this.window = window;
     }
     getMessages() {
-        return this.backend.getMessages(this.sessionId);
+        return this.backend.getMessages(this.sessionId, this.window);
     }
     addMessage(message) {
         return this.backend.addMessages(this.sessionId, [message]);
@@ -29,4 +33,3 @@ class DynamoDBSessionChatMessageHistory extends chat_history_1.BaseListChatMessa
     }
 }
 exports.DynamoDBSessionChatMessageHistory = DynamoDBSessionChatMessageHistory;
-//# sourceMappingURL=session-adapter.js.map

package/dist/history/types.d.ts

@@ -1,6 +1,6 @@
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
 import type { PayloadDescriptor } from '../shared/codec/codec';
-import type { BaseAdapterOptions, CodecOptions } from '../shared/options';
+import type { BaseAdapterOptions, CancelOptions, CodecOptions } from '../shared/options';
 /** Options for {@link DynamoDBChatMessageHistory}. */
 export type DynamoDBChatMessageHistoryOptions = BaseAdapterOptions & CodecOptions & {
     /** Optional serializer override (defaults to the JSON serializer). */
@@ -18,6 +18,26 @@ export type DynamoDBChatMessageHistoryOptions = BaseAdapterOptions & CodecOption
 };
 /** How `getMessages` handles an item it cannot decode. */
 export type CorruptMessagePolicy = 'skip' | 'throw';
+/**
+ * Which slice of a session `getMessages` returns. Both bounds are optional
+ * and combine: `{ limit: 50, before }` is the fifty messages just before
+ * `before`.
+ */
+export interface MessageWindow {
+    /** Return only the newest `limit` messages — still in chronological order. */
+    limit?: number;
+    /** Return only messages appended before this instant (millisecond precision). */
+    before?: Date;
+}
+/** Options for `getMessages`: the read window plus cancellation. */
+export type GetMessagesOptions = MessageWindow & CancelOptions;
+/** Options for `listSessions`: the scan caps plus cancellation. */
+export interface ListSessionsOptions extends CancelOptions {
+    /** Cap on scan pages before `ResultTruncatedError` (default 1000). */
+    maxIterations?: number;
+    /** Cap on rows read into memory before `ResultTruncatedError` (default 10 000). */
+    maxItems?: number;
+}
 /** Summary of a stored chat session. */
 export interface SessionMetadata {
     sessionId: string;
@@ -25,6 +45,8 @@ export interface SessionMetadata {
     messageCount: number;
     createdAt: string;
     updatedAt: string;
+    /** When the session's TTL expires, as an ISO-8601 instant; absent when no TTL is stored. */
+    expiresAt?: string;
 }
 /** A single stored chat message item (one per message, ordered by its ULID). */
 export interface ChatMessageItem {
@@ -45,4 +67,3 @@ export interface ChatSessionItem {
     updatedAt: string;
     ttl?: number;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/history/types.js

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

package/dist/index.d.ts

@@ -4,19 +4,26 @@ export { DynamoDBStore } from './store/store';
 export type { DynamoDBStoreOptions } from './store/types';
 export type { VectorReconcileResult } from './store/actions/reconcile-vector-index';
 export type { VectorBackend, VectorMatch, VectorRef } from './store/vector-backend';
+export type { VectorScoreDirection } from './store/internal/score-direction';
 export { DynamoDBChatMessageHistory } from './history/chat-message-history';
 export { DynamoDBSessionChatMessageHistory } from './history/session-adapter';
-export type { CorruptMessagePolicy, DynamoDBChatMessageHistoryOptions, SessionMetadata, } from './history/types';
+export type { AdapterWindow, SessionBackend } from './history/session-adapter';
+export type { CorruptMessagePolicy, DynamoDBChatMessageHistoryOptions, GetMessagesOptions, ListSessionsOptions, MessageWindow, SessionMetadata, } from './history/types';
 export { DynamoDBFactory } from './factory/factory';
-export type { CreateAllOptions, CreatedAdapters, FactoryBaseOptions } from './factory/factory';
-export { DynamoDbLangGraphError } from './shared/errors/base-error';
+export type { AdapterSection, CreateAllOptions, CreatedAdapters, FactoryBaseOptions, } from './factory/types';
+export { DynamoDBLangGraphError, isDynamoDBLangGraphError } from './shared/errors/base-error';
 export type { ErrorContext } from './shared/errors/base-error';
 export { ErrorCode } from './shared/errors/error-code';
 export { AbortError, BatchWriteAllIncompleteError, BatchWriteIncompleteError, CompensationFailedError, ConflictError, ResultTruncatedError, RetryExhaustedError, ValidationError, } from './shared/errors/errors';
+export { UpstreamError } from './shared/errors/upstream-error';
 export type { Logger, LogArgument } from './shared/logging/logger';
 export { redactLogger, redactSecrets } from './shared/logging/redaction';
-export type { BaseAdapterOptions, CodecOptions } from './shared/options';
+export type { RedactLoggerOptions } from './shared/logging/redaction';
+export type { Redactable } from './shared/logging/redaction-walk';
+export type { CancelOptions, BaseAdapterOptions, CodecOptions } from './shared/options';
+export type { RetryAttemptInfo, RetryOptions } from './shared/dynamodb/retry';
+export type { RetryPolicy } from './shared/dynamodb/retry-policy';
 export type { TtlOption } from './shared/validation/ttl';
 export type { CompressionConfig } from './shared/codec/compression';
 export type { S3OffloadConfig } from './shared/codec/s3/config';
-//# sourceMappingURL=index.d.ts.map
+export type { S3ClientConfigLike, S3ClientLike, S3ClientOption, S3ClientOptions, S3CommandLike, S3RegionLike, } from './shared/codec/s3/client-types';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.redactSecrets = exports.redactLogger = exports.ValidationError = exports.RetryExhaustedError = exports.ResultTruncatedError = exports.ConflictError = exports.CompensationFailedError = exports.BatchWriteIncompleteError = exports.BatchWriteAllIncompleteError = exports.AbortError = exports.ErrorCode = exports.DynamoDbLangGraphError = exports.DynamoDBFactory = exports.DynamoDBSessionChatMessageHistory = exports.DynamoDBChatMessageHistory = exports.DynamoDBStore = exports.DynamoDBSaver = void 0;
+exports.redactSecrets = exports.redactLogger = exports.UpstreamError = exports.ValidationError = exports.RetryExhaustedError = exports.ResultTruncatedError = exports.ConflictError = exports.CompensationFailedError = exports.BatchWriteIncompleteError = exports.BatchWriteAllIncompleteError = exports.AbortError = exports.ErrorCode = exports.isDynamoDBLangGraphError = exports.DynamoDBLangGraphError = exports.DynamoDBFactory = exports.DynamoDBSessionChatMessageHistory = exports.DynamoDBChatMessageHistory = exports.DynamoDBStore = exports.DynamoDBSaver = void 0;
 var saver_1 = require("./checkpointer/saver");
 Object.defineProperty(exports, "DynamoDBSaver", { enumerable: true, get: function () { return saver_1.DynamoDBSaver; } });
 var store_1 = require("./store/store");
@@ -12,7 +12,8 @@ Object.defineProperty(exports, "DynamoDBSessionChatMessageHistory", { enumerable
 var factory_1 = require("./factory/factory");
 Object.defineProperty(exports, "DynamoDBFactory", { enumerable: true, get: function () { return factory_1.DynamoDBFactory; } });
 var base_error_1 = require("./shared/errors/base-error");
-Object.defineProperty(exports, "DynamoDbLangGraphError", { enumerable: true, get: function () { return base_error_1.DynamoDbLangGraphError; } });
+Object.defineProperty(exports, "DynamoDBLangGraphError", { enumerable: true, get: function () { return base_error_1.DynamoDBLangGraphError; } });
+Object.defineProperty(exports, "isDynamoDBLangGraphError", { enumerable: true, get: function () { return base_error_1.isDynamoDBLangGraphError; } });
 var error_code_1 = require("./shared/errors/error-code");
 Object.defineProperty(exports, "ErrorCode", { enumerable: true, get: function () { return error_code_1.ErrorCode; } });
 var errors_1 = require("./shared/errors/errors");
@@ -24,7 +25,8 @@ Object.defineProperty(exports, "ConflictError", { enumerable: true, get: functio
 Object.defineProperty(exports, "ResultTruncatedError", { enumerable: true, get: function () { return errors_1.ResultTruncatedError; } });
 Object.defineProperty(exports, "RetryExhaustedError", { enumerable: true, get: function () { return errors_1.RetryExhaustedError; } });
 Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+var upstream_error_1 = require("./shared/errors/upstream-error");
+Object.defineProperty(exports, "UpstreamError", { enumerable: true, get: function () { return upstream_error_1.UpstreamError; } });
 var redaction_1 = require("./shared/logging/redaction");
 Object.defineProperty(exports, "redactLogger", { enumerable: true, get: function () { return redaction_1.redactLogger; } });
 Object.defineProperty(exports, "redactSecrets", { enumerable: true, get: function () { return redaction_1.redactSecrets; } });
-//# sourceMappingURL=index.js.map

package/dist/shared/clock.d.ts

@@ -1,3 +1,8 @@
 /** Current time as an ISO-8601 string, derived from the (test-freezable) clock. */
 export declare function nowIso(): string;
-//# sourceMappingURL=clock.d.ts.map
+/**
+ * Current time as whole epoch seconds, the unit DynamoDB TTL uses. Every
+ * expiry stamp, expiry filter and ttl-anchor comparison reads this one seam
+ * so they agree with each other under a frozen or skewed clock.
+ */
+export declare function nowSeconds(): number;

package/dist/shared/clock.js

@@ -1,8 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.nowIso = nowIso;
+exports.nowSeconds = nowSeconds;
 /** Current time as an ISO-8601 string, derived from the (test-freezable) clock. */
 function nowIso() {
     return new Date(Date.now()).toISOString();
 }
-//# sourceMappingURL=clock.js.map
+/**
+ * Current time as whole epoch seconds, the unit DynamoDB TTL uses. Every
+ * expiry stamp, expiry filter and ttl-anchor comparison reads this one seam
+ * so they agree with each other under a frozen or skewed clock.
+ */
+function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}

package/dist/shared/codec/codec.d.ts

@@ -6,18 +6,26 @@ export declare enum PayloadLocation {
     INLINE = "INLINE",
     S3 = "S3"
 }
-/** A payload stored inline as bytes in the DynamoDB item. */
-interface InlinePayloadDescriptor {
-    location: PayloadLocation.INLINE;
+/**
+ * Version of the persisted descriptor shape. Absent on rows written before it
+ * existed, which read as version 1; a higher value marks a row written by a
+ * newer library and is refused rather than misread.
+ */
+export declare const DESCRIPTOR_SCHEMA_VERSION = 1;
+/** Fields every descriptor carries, whatever its location. */
+interface DescriptorBase {
+    schemaVersion?: number;
     serdeType: string;
     compressed: boolean;
+}
+/** A payload stored inline as bytes in the DynamoDB item. */
+interface InlinePayloadDescriptor extends DescriptorBase {
+    location: PayloadLocation.INLINE;
     bytes: Uint8Array;
 }
 /** A payload offloaded to S3, referenced by key. */
-interface S3PayloadDescriptor {
+interface S3PayloadDescriptor extends DescriptorBase {
     location: PayloadLocation.S3;
-    serdeType: string;
-    compressed: boolean;
     s3Key: string;
 }
 /** The result of encoding a payload. */
@@ -28,17 +36,18 @@ export interface CodecDeps {
     compression?: CompressionConfig;
     offloader?: S3Offloader;
 }
-/** Options controlling where an offloaded payload's S3 key is built from. */
-export interface EncodeOptions {
-    keyParts: readonly string[];
-}
 /**
- * Encode `value`: serialize via serde, compress (if configured), then offload
- * to S3 when the compressed bytes exceed the offloader's threshold. Returns a
- * descriptor recording how to read it back.
+ * Fetch a descriptor's bytes — an S3 download when offloaded — and undo
+ * compression. Infrastructure only, no deserialization: a caller that needs to
+ * tell a transport or permission failure from bad data does this step and
+ * `loadsTyped` separately (see `history/actions/get-messages.ts`).
+ *
+ * `scope` is the row's own leading key parts (`[threadId]`, `[...namespace,
+ * key]`, `[sessionId]`): an offloaded key is downloaded only when it lies under
+ * the path those parts produce, so a row can never point this adapter at an
+ * object it does not own.
  */
-export declare function encodePayload<T>(value: T, deps: CodecDeps, options: EncodeOptions): Promise<PayloadDescriptor>;
-/** Decode a {@link PayloadDescriptor} produced by {@link encodePayload}. */
-export declare function decodePayload<T>(descriptor: PayloadDescriptor, deps: CodecDeps): Promise<T>;
+export declare function readPayloadBytes(descriptor: PayloadDescriptor, deps: CodecDeps, scope: readonly string[]): Promise<Uint8Array>;
+/** Decode a {@link PayloadDescriptor} produced by `encodePayload`; see {@link readPayloadBytes} for `scope`. */
+export declare function decodePayload<T>(descriptor: PayloadDescriptor, deps: CodecDeps, scope: readonly string[]): Promise<T>;
 export {};
-//# sourceMappingURL=codec.d.ts.map

package/dist/shared/codec/codec.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PayloadLocation = void 0;
-exports.encodePayload = encodePayload;
+exports.DESCRIPTOR_SCHEMA_VERSION = exports.PayloadLocation = void 0;
+exports.readPayloadBytes = readPayloadBytes;
 exports.decodePayload = decodePayload;
+const errors_1 = require("../errors/errors");
 const compression_1 = require("./compression");
 /** Where an encoded payload lives. */
 var PayloadLocation;
@@ -10,35 +11,56 @@ var PayloadLocation;
     PayloadLocation["INLINE"] = "INLINE";
     PayloadLocation["S3"] = "S3";
 })(PayloadLocation || (exports.PayloadLocation = PayloadLocation = {}));
+/**
+ * Version of the persisted descriptor shape. Absent on rows written before it
+ * existed, which read as version 1; a higher value marks a row written by a
+ * newer library and is refused rather than misread.
+ */
+exports.DESCRIPTOR_SCHEMA_VERSION = 1;
 function requireOffloader(deps) {
     if (!deps.offloader) {
-        throw new Error('Cannot decode an S3 payload without an offloader');
+        throw new errors_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;
 }
+/** Refuse a descriptor this version cannot read: a newer schema, or an unknown location. */
+function assertReadableDescriptor(descriptor) {
+    const version = descriptor.schemaVersion ?? exports.DESCRIPTOR_SCHEMA_VERSION;
+    if (version > exports.DESCRIPTOR_SCHEMA_VERSION) {
+        throw new errors_1.ValidationError(`payload descriptor schemaVersion ${version} was written by a newer version of this ` +
+            'library; upgrade to read it', 'descriptor');
+    }
+    const locations = Object.values(PayloadLocation);
+    if (!locations.includes(descriptor.location)) {
+        throw new errors_1.ValidationError(`payload descriptor has an unknown location ${JSON.stringify(descriptor.location)}`, 'descriptor');
+    }
+}
 /**
- * Encode `value`: serialize via serde, compress (if configured), then offload
- * to S3 when the compressed bytes exceed the offloader's threshold. Returns a
- * descriptor recording how to read it back.
+ * Fetch a descriptor's bytes — an S3 download when offloaded — and undo
+ * compression. Infrastructure only, no deserialization: a caller that needs to
+ * tell a transport or permission failure from bad data does this step and
+ * `loadsTyped` separately (see `history/actions/get-messages.ts`).
+ *
+ * `scope` is the row's own leading key parts (`[threadId]`, `[...namespace,
+ * key]`, `[sessionId]`): an offloaded key is downloaded only when it lies under
+ * the path those parts produce, so a row can never point this adapter at an
+ * object it does not own.
  */
-async function encodePayload(value, deps, options) {
-    const [serdeType, raw] = await deps.serde.dumpsTyped(value);
-    const { bytes, compressed } = deps.compression
-        ? await (0, compression_1.compress)(raw, deps.compression)
-        : { bytes: raw, compressed: false };
-    if (deps.offloader && deps.offloader.shouldOffload(bytes)) {
-        const s3Key = deps.offloader.buildKey(options.keyParts);
-        await deps.offloader.upload(s3Key, bytes);
-        return { location: PayloadLocation.S3, serdeType, compressed, s3Key };
+async function readPayloadBytes(descriptor, deps, scope) {
+    assertReadableDescriptor(descriptor);
+    let raw;
+    if (descriptor.location === PayloadLocation.S3) {
+        const offloader = requireOffloader(deps);
+        offloader.assertOwnedKey(descriptor.s3Key, scope);
+        raw = await offloader.download(descriptor.s3Key);
+    }
+    else {
+        raw = descriptor.bytes;
     }
-    return { location: PayloadLocation.INLINE, serdeType, compressed, bytes };
+    return (0, compression_1.decompress)(raw, descriptor.compressed, deps.compression?.maxDecompressedBytes);
 }
-/** Decode a {@link PayloadDescriptor} produced by {@link encodePayload}. */
-async function decodePayload(descriptor, deps) {
-    const raw = descriptor.location === PayloadLocation.S3
-        ? await requireOffloader(deps).download(descriptor.s3Key)
-        : descriptor.bytes;
-    const bytes = await (0, compression_1.decompress)(raw, descriptor.compressed, deps.compression?.maxDecompressedBytes);
-    return deps.serde.loadsTyped(descriptor.serdeType, bytes);
+/** Decode a {@link PayloadDescriptor} produced by `encodePayload`; see {@link readPayloadBytes} for `scope`. */
+async function decodePayload(descriptor, deps, scope) {
+    return deps.serde.loadsTyped(descriptor.serdeType, await readPayloadBytes(descriptor, deps, scope));
 }
-//# sourceMappingURL=codec.js.map

package/dist/shared/codec/compression.d.ts

@@ -18,8 +18,7 @@ export interface CompressionResult {
 export declare function compress(data: Uint8Array, config: CompressionConfig): Promise<CompressionResult>;
 /**
  * Gunzip `data` when `compressed` is true; otherwise return it unchanged. Throws
- * a {@link DynamoDbLangGraphError} with code `COMPRESSION_LIMIT` if the output
+ * a {@link DynamoDBLangGraphError} with code `COMPRESSION_LIMIT` if the output
  * would exceed `maxBytes` (bomb guard).
  */
 export declare function decompress(data: Uint8Array, compressed: boolean, maxBytes?: number): Promise<Uint8Array>;
-//# sourceMappingURL=compression.d.ts.map

package/dist/shared/codec/compression.js

@@ -29,7 +29,7 @@ async function compress(data, config) {
 }
 /**
  * Gunzip `data` when `compressed` is true; otherwise return it unchanged. Throws
- * a {@link DynamoDbLangGraphError} with code `COMPRESSION_LIMIT` if the output
+ * a {@link DynamoDBLangGraphError} with code `COMPRESSION_LIMIT` if the output
  * would exceed `maxBytes` (bomb guard).
  */
 async function decompress(data, compressed, maxBytes = constants_1.DEFAULT_MAX_DECOMPRESSED_BYTES) {
@@ -41,9 +41,8 @@ async function decompress(data, compressed, maxBytes = constants_1.DEFAULT_MAX_D
     catch (error) {
         const err = error;
         if (err.code === 'ERR_BUFFER_TOO_LARGE') {
-            throw new base_error_1.DynamoDbLangGraphError(`Refusing to decompress: output would exceed ${maxBytes} bytes`, error_code_1.ErrorCode.COMPRESSION_LIMIT, {}, error);
+            throw new base_error_1.DynamoDBLangGraphError(`Refusing to decompress: output would exceed ${maxBytes} bytes`, error_code_1.ErrorCode.COMPRESSION_LIMIT, {}, error);
         }
         throw error;
     }
 }
-//# sourceMappingURL=compression.js.map

package/dist/shared/codec/descriptor-keys.d.ts

@@ -1,4 +1,12 @@
-import { type PayloadDescriptor } from './codec';
+import { PayloadLocation } from './codec';
+/**
+ * The part of a descriptor cleanup needs: where the payload lives and, for S3,
+ * its key. A full `PayloadDescriptor` satisfies it, and so does the projection
+ * a pre-write read returns without the inline bytes.
+ */
+export interface DescriptorRef {
+    location: PayloadLocation;
+    s3Key?: string;
+}
 /** Collect the S3 keys of any offloaded descriptors, for orphan cleanup. */
-export declare function collectS3Keys(descriptors: readonly PayloadDescriptor[]): string[];
-//# sourceMappingURL=descriptor-keys.d.ts.map
+export declare function collectS3Keys(descriptors: readonly DescriptorRef[]): string[];

package/dist/shared/codec/descriptor-keys.js

@@ -6,9 +6,9 @@ const codec_1 = require("./codec");
 function collectS3Keys(descriptors) {
     const keys = [];
     for (const descriptor of descriptors) {
-        if (descriptor.location === codec_1.PayloadLocation.S3)
+        if (descriptor.location === codec_1.PayloadLocation.S3 && descriptor.s3Key !== undefined) {
             keys.push(descriptor.s3Key);
+        }
     }
     return keys;
 }
-//# sourceMappingURL=descriptor-keys.js.map

package/dist/shared/codec/encode.d.ts

@@ -0,0 +1,13 @@
+import { type CodecDeps, type PayloadDescriptor } from './codec';
+/** Options controlling where an offloaded payload's S3 key is built from. */
+export interface EncodeOptions {
+    keyParts: readonly string[];
+}
+/**
+ * Encode `value`: serialize via serde, compress (if configured), then offload
+ * to S3 when the compressed bytes exceed the offloader's threshold. Returns a
+ * descriptor recording how to read it back. Without an offloader, bytes that
+ * cannot fit a DynamoDB item are rejected here (see
+ * {@link assertInlinePayloadFits}).
+ */
+export declare function encodePayload<T>(value: T, deps: CodecDeps, options: EncodeOptions): Promise<PayloadDescriptor>;

package/dist/shared/codec/encode.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodePayload = encodePayload;
+const constants_1 = require("../constants");
+const errors_1 = require("../errors/errors");
+const codec_1 = require("./codec");
+const compression_1 = require("./compression");
+/**
+ * Reject bytes that cannot be stored inline. Without an offloader the only
+ * alternative is a raw `ValidationException` from DynamoDB after the network
+ * round trip, which names neither the cause nor the remedy.
+ */
+function assertInlinePayloadFits(bytes, deps) {
+    if (bytes.length <= constants_1.MAX_INLINE_PAYLOAD_BYTES)
+        return;
+    const hint = deps.compression?.enabled
+        ? ''
+        : ', or enable compression if the data compresses well';
+    throw new errors_1.ValidationError(`payload of ${bytes.length} bytes exceeds the ${constants_1.MAX_INLINE_PAYLOAD_BYTES}-byte inline limit ` +
+        `(DynamoDB items are capped at 400 KB); configure s3 offloading${hint}`, 'payload');
+}
+/**
+ * Encode `value`: serialize via serde, compress (if configured), then offload
+ * to S3 when the compressed bytes exceed the offloader's threshold. Returns a
+ * descriptor recording how to read it back. Without an offloader, bytes that
+ * cannot fit a DynamoDB item are rejected here (see
+ * {@link assertInlinePayloadFits}).
+ */
+async function encodePayload(value, deps, options) {
+    const [serdeType, raw] = await deps.serde.dumpsTyped(value);
+    const { bytes, compressed } = deps.compression
+        ? await (0, compression_1.compress)(raw, deps.compression)
+        : { bytes: raw, compressed: false };
+    const base = { schemaVersion: codec_1.DESCRIPTOR_SCHEMA_VERSION, serdeType, compressed };
+    if (deps.offloader && deps.offloader.shouldOffload(bytes)) {
+        const s3Key = deps.offloader.buildKey(options.keyParts);
+        await deps.offloader.upload(s3Key, bytes);
+        return { ...base, location: codec_1.PayloadLocation.S3, s3Key };
+    }
+    if (!deps.offloader)
+        assertInlinePayloadFits(bytes, deps);
+    return { ...base, location: codec_1.PayloadLocation.INLINE, bytes };
+}

package/dist/shared/codec/json-serde.d.ts

@@ -5,4 +5,3 @@ import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
  * the shared payload codec.
  */
 export declare const JSON_SERDE: SerializerProtocol;
-//# sourceMappingURL=json-serde.d.ts.map

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

@@ -15,4 +15,3 @@ exports.JSON_SERDE = {
         return JSON.parse(text);
     },
 };
-//# sourceMappingURL=json-serde.js.map

package/dist/shared/codec/payload-loss.d.ts

@@ -0,0 +1,12 @@
+/**
+ * True when an offloaded object no longer exists — a lifecycle sweep removed
+ * it, or a competing overwrite deleted it between a row read and the download.
+ */
+export declare function isMissingObjectError(error: Error): boolean;
+/**
+ * True when a payload can never be read again — its object is gone, it trips
+ * the decompression guard, or its key lies outside the row's own path — as
+ * opposed to a failure that may succeed on retry or after a configuration fix
+ * (throttling, network, permissions).
+ */
+export declare function isPermanentPayloadLoss(error: Error): boolean;

package/dist/shared/codec/payload-loss.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMissingObjectError = isMissingObjectError;
+exports.isPermanentPayloadLoss = isPermanentPayloadLoss;
+const error_code_1 = require("../errors/error-code");
+/**
+ * True when an offloaded object no longer exists — a lifecycle sweep removed
+ * it, or a competing overwrite deleted it between a row read and the download.
+ */
+function isMissingObjectError(error) {
+    const coded = error;
+    return coded.code === error_code_1.ErrorCode.S3_OFFLOAD_FAILED && coded.cause?.name === 'NoSuchKey';
+}
+/** Validation fields that condemn the row itself rather than the caller's input. */
+const ROW_REJECTION_FIELDS = ['s3Key', 'descriptor'];
+/**
+ * True when a row's descriptor can never be read by this adapter: its key lies
+ * outside the S3 path its own identifiers allow (see `assertKeyInScope`), or
+ * its shape is one this version does not understand.
+ */
+function isRowRejection(error) {
+    const coded = error;
+    return (coded.code === error_code_1.ErrorCode.VALIDATION &&
+        coded.context?.field !== undefined &&
+        ROW_REJECTION_FIELDS.includes(coded.context.field));
+}
+/**
+ * True when a payload can never be read again — its object is gone, it trips
+ * the decompression guard, or its key lies outside the row's own path — as
+ * opposed to a failure that may succeed on retry or after a configuration fix
+ * (throttling, network, permissions).
+ */
+function isPermanentPayloadLoss(error) {
+    const coded = error;
+    return (coded.code === error_code_1.ErrorCode.COMPRESSION_LIMIT ||
+        isMissingObjectError(error) ||
+        isRowRejection(error));
+}

package/dist/shared/codec/s3/adapter-config.d.ts

@@ -0,0 +1,13 @@
+import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import { type S3OffloadConfig } from './config';
+/** The adapters that share one bucket, each under its own default key prefix. */
+export type AdapterName = 'checkpointer' | 'store' | 'history';
+/**
+ * Resolve an adapter's `s3` option into the offloader's configuration: the
+ * adapter-scoped default key prefix when none is given, and the DynamoDB
+ * client's region when the S3 client config names none. The S3 SDK does not
+ * follow region redirects by default, so a bucket reachable only through the
+ * region the DynamoDB side was configured with used to fail with an opaque
+ * `PermanentRedirect` on the first offload.
+ */
+export declare function offloaderConfigFor(s3: S3OffloadConfig, adapter: AdapterName, clientConfig?: DynamoDBClientConfig): S3OffloadConfig;

package/dist/shared/codec/s3/adapter-config.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.offloaderConfigFor = offloaderConfigFor;
+const constants_1 = require("../../constants");
+const client_types_1 = require("./client-types");
+const config_1 = require("./config");
+/**
+ * Resolve an adapter's `s3` option into the offloader's configuration: the
+ * adapter-scoped default key prefix when none is given, and the DynamoDB
+ * client's region when the S3 client config names none. The S3 SDK does not
+ * follow region redirects by default, so a bucket reachable only through the
+ * region the DynamoDB side was configured with used to fail with an opaque
+ * `PermanentRedirect` on the first offload.
+ */
+function offloaderConfigFor(s3, adapter, clientConfig) {
+    const region = (0, client_types_1.s3ClientOptions)(s3.clientConfig).region ?? clientConfig?.region;
+    return {
+        ...s3,
+        keyPrefix: s3.keyPrefix ?? (0, config_1.defaultAdapterKeyPrefix)(constants_1.DEFAULT_S3_KEY_PREFIX, adapter),
+        ...(region === undefined ? {} : { clientConfig: { ...s3.clientConfig, region } }),
+    };
+}

package/dist/shared/codec/s3/bounded-body.d.ts

@@ -0,0 +1,14 @@
+import { DynamoDBLangGraphError } from '../../errors/base-error';
+/** The part of an S3 `GetObject` body this module relies on. */
+export interface S3Body {
+    transformToByteArray(): Promise<Uint8Array>;
+}
+/** The typed error for an object over the download cap. */
+export declare function oversizedObjectError(key: string, bytes: number, maxBytes: number): DynamoDBLangGraphError;
+/**
+ * Buffer an S3 body without ever holding more than `maxBytes` of it. A
+ * streaming body is consumed chunk by chunk and abandoned the moment the
+ * running total passes the cap; a body that only offers
+ * `transformToByteArray()` is read whole and then checked.
+ */
+export declare function readBodyBounded(body: S3Body, key: string, maxBytes: number): Promise<Uint8Array>;