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

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

@@ -0,0 +1,80 @@
+/**
+ * Hides the JSON form: writing it, reading it, and recognising it.
+ *
+ * The default serde writes a value as JSON under the `json` type and reads
+ * back only that type; the codec also asks, when a serde refuses stored bytes,
+ * whether those bytes are still JSON at all, which tells a corrupt payload from
+ * a serde that would not reconstruct it.
+ */
+import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
+/**
+ * A plain JSON serializer implementing LangGraph's `SerializerProtocol`:
+ * the default `serde` of `DynamoDBStore` and `DynamoDBChatMessageHistory`, and
+ * the alternative a `DynamoDBSaver` can be given in place of LangGraph's
+ * `JsonPlusSerializer`.
+ *
+ * It is exported so that choice is available. The checkpointer's default
+ * revives a stored `{"lc": …}` record by instantiating the class the record
+ * names, so the row selects which constructor runs on read; this serializer
+ * runs `JSON.parse` and nothing else, and reconstructs no class at all.
+ * Reading with it is the narrower trust boundary, and the price is stated
+ * below: it stores the JSON projection of a value, not the value.
+ *
+ * `dumpsTyped` accepts any value `JSON.stringify` can represent and refuses the
+ * rest. A value it cannot represent — `undefined`, a function, a symbol —
+ * stringifies to `undefined` and would be stored as **zero bytes**, which reads
+ * back as a parse error; a circular structure or a `BigInt` makes it throw. Both
+ * are reported as `VALIDATION` naming `value`, at the write, rather than
+ * as an unreadable row later — with the refusal attached as `cause` and never
+ * quoted into the message, which for a circular structure names the caller's
+ * own properties and classes.
+ *
+ * What it represents, it represents as JSON, which is lossy in ways nothing
+ * records: a `Map` or `Set` stores as `{}`, an object key whose value is
+ * `undefined` is dropped and an array element is stored as `null`, `NaN` and
+ * `Infinity` store as `null`, `-0` as `0`, a `Uint8Array` as an index-keyed
+ * object and a `Date` as an ISO string. The README's *Table schema* section
+ * holds the whole table, against the checkpointer default column by column.
+ *
+ * `loadsTyped` reads only the `json` form it writes, and says
+ * so before it looks at a byte. Any other declared form is a `VALIDATION` error
+ * naming `serde`, because it says what *this* reader may rebuild and not that
+ * the payload is damaged. Bytes of that form which do not parse are
+ * `PAYLOAD_CORRUPT`, because they can never be read and the caller should
+ * report rather than retry; a `data` that is not bytes at all is a
+ * `VALIDATION` naming `data`, because that is the caller's mistake and
+ * not a row's.
+ *
+ * Frozen for the reason {@link ErrorCode} is: one object, shared by every
+ * adapter in the process that did not pass a `serde` of its own, and
+ * reachable from the package root. An assignment to `dumpsTyped` by any one
+ * consumer would silently change how every other one writes.
+ */
+export declare const JSON_SERDE: SerializerProtocol;
+/**
+ * Whether stored bytes are still the form the row that holds them declares.
+ *
+ * This is the structural question behind the two ways a decode fails —
+ * `PAYLOAD_CORRUPT` for bytes no reader can decode, and the `serde` refusal for
+ * bytes *this* reader will not rebuild a value from — and it is the only one
+ * this package can answer on its own. `SerializerProtocol` offers no way to ask
+ * a serde whether it parsed the bytes before deciding not to reconstruct what
+ * they name, and the refusal it throws is a caller's object: its class, its
+ * fields and its prose are all whatever that caller chose. Classifying a
+ * payload by any of those would make the code mean "a third party said so",
+ * which is exactly what neither code may mean.
+ *
+ * Accepts: `serdeType` — the type stamped on the row, as the descriptor carries
+ * it. `bytes` — what the row stored, already decompressed.
+ *
+ * Returns: whether the bytes still parse as the declared form. A type this
+ * package has no grammar for is taken at its word and answers `true`, so its
+ * serde's refusal is reported rather than written off: dropping a payload this
+ * reader merely cannot check would lose data on nothing but its own ignorance.
+ *
+ * Throws: **nothing**, for any bytes. It is called from inside the `catch` that
+ * is classifying a decode failure, where a throw would replace the failure
+ * being reported — and the value it is handed came off a row, so it may be
+ * anything that row's writer stored.
+ */
+export declare function bytesHoldDeclaredForm(serdeType: string, bytes: Uint8Array): boolean;

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

@@ -0,0 +1,54 @@
+import { DynamoDBLangGraphError, toError } from '../errors/base-error.js';
+import { ErrorCode } from '../errors/error-code.js';
+import { validationError } from '../errors/errors.js';
+import { truncateForLog } from '../logging/truncate.js';
+export const JSON_SERDE = {
+    async dumpsTyped(value) {
+        let text;
+        try {
+            text = JSON.stringify(value);
+        }
+        catch (error) {
+            throw 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', toError(error));
+        }
+        if (text === undefined) {
+            throw 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 validationError(`this serializer reads only the \`${JSON_SERDE_TYPE}\` form it writes, and this payload ` +
+                `declares ${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 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 DynamoDBLangGraphError('the stored payload is not the JSON this serializer wrote, so it cannot be decoded', ErrorCode.PAYLOAD_CORRUPT, {}, error);
+        }
+    },
+};
+Object.freeze(JSON_SERDE);
+const JSON_SERDE_TYPE = 'json';
+export 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/esm/shared/codec/s3/client-types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Hides the S3 SDK's own types from this package's declarations.
+ *
+ * The S3 client, its config and a command are described by the members this
+ * package touches, so no shipped declaration imports the optional
+ * `@aws-sdk/client-s3` peer and a caller without it installed still compiles
+ * (record 1). A real `S3Client` or `S3ClientConfig` satisfies these shapes as
+ * it is, so a caller who has the SDK passes its own values unchanged.
+ */
+/** A region as the SDK accepts it: a string or a provider resolving to one. */
+export type S3RegionLike = string | (() => Promise<string>);
+/** A value an S3 client option can hold. */
+export type S3ClientOption = string | number | boolean | object | null | undefined;
+/**
+ * The S3 client options this library reads (`region`) or sets (`maxAttempts`),
+ * open to every other `S3ClientConfig` key.
+ */
+export interface S3ClientOptions {
+    region?: S3RegionLike;
+    maxAttempts?: number;
+    [option: string]: S3ClientOption;
+}
+/**
+ * Structural stand-in for `S3ClientConfig`, so the shipped declarations compile
+ * without the optional `@aws-sdk/client-s3` peer installed. A literal gets
+ * completion for the options the library uses; a typed `S3ClientConfig`
+ * variable is accepted as it is.
+ */
+export type S3ClientConfigLike = S3ClientOptions | object;
+/**
+ * The options of a config, read through the structural type.
+ *
+ * Accepts: a config as the caller gave it, or nothing.
+ *
+ * Returns: the same object seen as {@link S3ClientOptions} so `region` and
+ * `maxAttempts` can be read; an absent config reads as empty rather than
+ * needing a guard at every call site.
+ *
+ * Throws: nothing.
+ */
+export declare function s3ClientOptions(config: S3ClientConfigLike | undefined): S3ClientOptions;
+/** What every SDK command object carries: its `input`. */
+interface S3CommandLike {
+    input: object;
+}
+/**
+ * The S3 client surface this library calls, typed structurally for the same
+ * reason. `S3Client` from `@aws-sdk/client-s3` satisfies it.
+ */
+export interface S3ClientLike {
+    send(command: S3CommandLike, options?: object): Promise<object>;
+    destroy(): void;
+}
+export {};

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

@@ -0,0 +1,3 @@
+export function s3ClientOptions(config) {
+    return (config ?? {});
+}

package/dist/esm/shared/codec/s3/client.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Hides that the S3 SDK is loaded on first use, and how its client is set up.
+ *
+ * An adapter without offload never imports the optional peer; the first
+ * offload does, once, and a missing install surfaces as `VALIDATION` naming
+ * the remedy (record 1). The client built here defaults to no retries of its
+ * own — `maxAttempts: 1` — so this package's retry is the only layer unless a
+ * caller's own `maxAttempts` overrides it (record 14), and its idle timer
+ * bounds a stalled transfer without bounding a slow one.
+ */
+import type { S3Client } from '@aws-sdk/client-s3';
+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.
+ *
+ * Accepts: nothing. Concurrent callers share one import.
+ *
+ * Returns: the module, cached for every later call.
+ *
+ * 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. 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>;
+/**
+ * `config` with the two defaults every S3 client of this library is built
+ * with, whichever constructor builds it.
+ *
+ * Accepts: `config` — the caller's `s3.clientConfig`, or an empty object.
+ *
+ * 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: 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
+ * retry layer — the same default `resolveDynamoDBClient` applies on the
+ * DynamoDB side. A default request handler bounds a transfer that has
+ * 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/esm/shared/codec/s3/client.js

@@ -0,0 +1,40 @@
+import { DEFAULT_SOCKET_TIMEOUT_MS } from '../../dynamodb/client.js';
+import { copyForCaller } from '../../errors/base-error.js';
+import { validationError } from '../../errors/errors.js';
+import { s3ClientOptions } from './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 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;
+}
+export async function loadS3Sdk() {
+    if (!sdkPromise) {
+        sdkPromise = import('@aws-sdk/client-s3').catch((error) => {
+            sdkPromise = undefined;
+            return wrapMissingPeer(error);
+        });
+    }
+    try {
+        return await sdkPromise;
+    }
+    catch (error) {
+        throw copyForCaller(error);
+    }
+}
+export function withS3ClientDefaults(config) {
+    const options = s3ClientOptions(config);
+    return {
+        ...options,
+        maxAttempts: options.maxAttempts ?? 1,
+        requestHandler: options.requestHandler ?? { socketTimeout: DEFAULT_SOCKET_TIMEOUT_MS },
+    };
+}
+export async function createDefaultS3Client(config) {
+    const { S3Client: S3ClientCtor } = await loadS3Sdk();
+    return new S3ClientCtor(withS3ClientDefaults(config));
+}

package/dist/esm/shared/codec/s3/config.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Hides the S3 key layout: where a row's object lives, and which keys a row may touch.
+ *
+ * An offloaded object's key is the adapter's prefix, then the row's own
+ * identifiers each base64url-encoded, then the id of the write that produced
+ * it, so a key read back from a row can be checked against the path that row
+ * could have produced before anything is read or deleted. The configuration a
+ * caller passes, its checks, the default prefix per adapter and the lifecycle
+ * 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.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. */
+export declare const MAX_S3_KEY_BYTES = 1024;
+/** Configuration for offloading large payloads to S3. */
+export interface S3OffloadConfig {
+    bucketName: string;
+    keyPrefix?: string;
+    /**
+     * 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 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). 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
+     * adapter's DynamoDB region.
+     */
+    clientConfig?: S3ClientConfigLike;
+}
+/**
+ * One key part, base64url-encoded.
+ *
+ * Accepts: `part` — any string, including empty.
+ *
+ * Returns: base64url text, whose alphabet (`A-Z a-z 0-9 - _`) contains neither
+ * `/` nor `.`, so an encoded part can never be mistaken for a path separator
+ * or the `.bin` suffix.
+ *
+ * Throws: nothing.
+ */
+export declare function encodeKeyPart(part: string): string;
+/**
+ * Build a fully-qualified S3 key: `${prefix}${parts, each base64url-encoded,
+ * joined with '/'}/${objectId}.bin`.
+ *
+ * `parts` are the identity of the DynamoDB row that will point at the object,
+ * and they are encoded rather than rejected: a namespace element or key may
+ * contain '/' (only the DynamoDB '#' separator is forbidden at the validation
+ * layer), and base64url's output alphabet never contains '/', so two distinct
+ * `parts` arrays can never compose one key.
+ *
+ * `objectId` names the write that uploads the object and is appended as it
+ * is, not encoded, so it must be safe in an S3 key and hold no `/`, or its
+ * segments would read as parts. The ids this package passes are both: a UUID
+ * (hex digits and `-`) and a ULID (Crockford base-32 digits).
+ *
+ * Accepts: `prefix` — the offloader's, already validated and separator-
+ * terminated. `parts` — at least one; the identity of the row that will point
+ * at the object. `objectId` — the uploading write's id: key-safe, with no `/`.
+ *
+ * Returns: the key. Under one prefix, two distinct `(parts, objectId)` pairs
+ * never compose one key, and the same prefix, parts and id always compose the
+ * same one.
+ *
+ * Throws: `VALIDATION` naming `s3Key` for an empty `parts` — an object with
+ * no row above it is outside every row's scope and could never be read back —
+ * and for a key over the 1024-byte cap. The encoding grows every part by a
+ * third, so identifiers that each pass their own length rule can still compose
+ * a key S3 would reject with a raw error.
+ */
+export declare function buildS3Key(prefix: string, parts: readonly string[], objectId: string): string;
+/**
+ * Refuse a key prefix that does not scope what it is used for.
+ *
+ * Accepts: `keyPrefix` — must be a string, non-empty, not `/`, and end in `/`.
+ * The type is checked here, before any string method is called, so every
+ * caller gets it: a number or `null` escaped as a bare `TypeError` from
+ * `keyPrefix.endsWith`. Every segment before that final `/` must be a real
+ * name: not empty, not `.`, not `..`. The whole prefix must also be free of
+ * control characters and well-formed UTF-16, the rules identifiers already
+ * meet, since it is written into log lines and into a lifecycle rule's filter.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `s3.keyPrefix`. The shape rule is reported
+ * before the segment rule, so a prefix breaking both is named by its shape.
+ *
+ * Guarantees: the prefix scopes both the objects and the lifecycle rule built
+ * from it. An empty or root prefix would make that rule expire the whole
+ * bucket, and one without a trailing `/` (`app/langgraph`) would also match
+ * every sibling starting with the same characters (`app/langgraph-other/`).
+ * An accepted prefix also survives path normalisation unchanged, which is what
+ * the segment rule buys. An S3 key is a byte string rather than a path, so
+ * `a/../b/x.bin` and `b/x.bin` are two different objects — but the IAM
+ * object-key condition a deployment writes, the lifecycle rule's
+ * `Filter.Prefix`, the console and every tool that resolves a path before
+ * matching one disagree about which. A prefix holding `..`, `.` or an empty
+ * segment therefore writes objects outside the path the deployment granted and
+ * outside the path the lifecycle rule sweeps, which is the whole job of a
+ * prefix.
+ */
+export declare function assertScopedKeyPrefix(keyPrefix: string): void;
+/**
+ * The lifecycle rule id for `prefix`: `langgraph-ttl-` plus its slug.
+ *
+ * Accepts: `prefix` — any string; trailing slashes are trimmed, and every
+ * character outside `[A-Za-z0-9-]` becomes `-`.
+ *
+ * Returns: a deterministic id that does not change with the TTL, so raising or
+ * lowering the TTL updates one rule rather than adding another. A prefix with
+ * no usable characters yields `langgraph-ttl-default`.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: the slug is not injective — `a/b/` and `a-b/` produce one id —
+ * and `ensureLifecycleRule` refuses rather than take over a rule that a
+ * different prefix already holds.
+ */
+export declare function buildLifecycleRuleId(prefix: string): string;
+/**
+ * The id of the rule that reclaims this prefix's expired delete markers:
+ * {@link buildLifecycleRuleId}'s id with a suffix of its own.
+ *
+ * Accepts: `prefix` — as {@link buildLifecycleRuleId} takes it.
+ *
+ * Returns: a second deterministic id, distinct from the expiration rule's.
+ * S3 refuses `ExpiredObjectDeleteMarker` inside an `Expiration` that also
+ * carries `Days`, so the reclaim cannot be a field on that rule and needs an
+ * id to be found by.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: it is *less* injective than the first id rather than merely as
+ * injective. On top of the slug collisions that one already has,
+ * `buildMarkerRuleId('app/')` and `buildLifecycleRuleId('app-markers/')` are
+ * one id — a clash between two prefixes whose letters and digits differ, which
+ * the first id alone cannot produce. `ensureLifecycleRule` refuses to take
+ * over either id when a different prefix already holds it, and its refusal
+ * names the suffix so the remedy fits the case.
+ */
+export declare function buildMarkerRuleId(prefix: string): string;
+/**
+ * An adapter's default S3 key prefix.
+ *
+ * Accepts: `base` — the shared prefix, ending in `/`. `adapter` — the adapter's
+ * own segment.
+ *
+ * Returns: `base` + `adapter` + `/`, so three adapters sharing one bucket write
+ * under three paths and one adapter's lifecycle rule never sweeps another's
+ * objects.
+ *
+ * Throws: nothing.
+ */
+export declare function defaultAdapterKeyPrefix(base: string, adapter: string): string;
+/**
+ * The path every key built from `parts` shares.
+ *
+ * Accepts: `prefix` — the configured key prefix, ending in `/`. `parts` —
+ * the row's identifiers; `[]` yields the prefix alone.
+ *
+ * Returns: the prefix plus the encoded parts joined by `/`, carrying neither
+ * `.bin` nor a trailing `/`.
+ *
+ * Throws: nothing.
+ */
+export declare function s3KeyScope(prefix: string, parts: readonly string[]): string;
+/**
+ * Whether `key` lies inside the path `parts` produce.
+ *
+ * Accepts: `key` — a key read back from a row, or one this package built.
+ * `parts` — the row's leading identifiers; `[]` degrades to a prefix-only
+ * check.
+ *
+ * Returns: true when the key continues below the scope (`<scope>/…`, which is
+ * every key this release writes, since the write's object id is one segment
+ * deeper) or equals it (`<scope>.bin`, the key of a store item offloaded by a
+ * release that gave the key no per-write segment).
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: an identifier sharing a leading substring with another (`t` and
+ * `t1`) never matches its scope — the parts are base64url-encoded and joined
+ * by `/`, so the comparison is segment-wise, not textual.
+ */
+export declare function isKeyInScope(key: string, prefix: string, parts: readonly string[]): boolean;
+/**
+ * Refuse a row-sourced `s3Key` outside the path the row's own identifiers
+ * produce.
+ *
+ * Accepts: as {@link isKeyInScope}.
+ *
+ * Returns: nothing: `key` is kept under its declared type, and this checks it
+ * against the scope `prefix` and `parts` compose.
+ *
+ * Throws: `VALIDATION` naming `s3Key`, quoting the key and the path the
+ * row may reference, each bounded by {@link truncateForLog}: the key comes off
+ * the row and the path is composed from an `s3.keyPrefix` checked for shape
+ * and never for length, so neither is bounded by anything this package ran.
+ * The key stays named — a bounded prefix still says which object to go and
+ * look at. It reaches the caller on all three adapters, including
+ * `history.getMessages` under `onCorruptMessage: 'skip'`, because
+ * `isPermanentPayloadLoss` does **not** classify it — an out-of-scope key is
+ * not the same kind of thing as an unreadable descriptor. An unreadable
+ * descriptor condemns the payload itself: nobody can read those bytes, so
+ * skipping the row loses nothing that was ever retrievable. An out-of-scope
+ * key says only that *this* reader may not follow it — the object is very
+ * likely intact, under the prefix that does own it — and what produced it is a
+ * `keyPrefix` pointed at the wrong place, a table shared with another tenant,
+ * or a planted row. Every one of those is a condition an operator must see and
+ * can fix. Classifying it as loss made only `history` answer with a silently
+ * shorter conversation — the one adapter that consults the classifier — which
+ * the chain then re-persisted as the truth, while the store and the saver
+ * raised on the same row. A short answer is the one failure a caller cannot
+ * detect, and one row shape must not mean two things across three adapters.
+ *
+ * Guarantees: a row is trusted for its shape, never for the object it points
+ * at. A writer able to place one row in a partition cannot make this library
+ * download or delete another tenant's object, nor make it quietly return less.
+ */
+export declare function assertKeyInScope(key: string, prefix: string, parts: readonly string[]): void;
+/** The adapters that share one bucket, each under its own default key prefix. */
+export type AdapterName = 'checkpointer' | 'store' | 'history';
+/**
+ * An adapter's `s3` option resolved into the offloader's configuration.
+ *
+ * Accepts: `s3` — as the caller gave it. `adapter` — names the default key
+ * prefix, so three adapters sharing one bucket do not share a path.
+ * `clientConfig` — the adapter's DynamoDB client config, read for its region
+ * only.
+ *
+ * Returns: `s3` with `keyPrefix` defaulted to the adapter's own path, and
+ * `clientConfig.region` filled in from the DynamoDB side when the S3 config
+ * names none. With no region on either side the field is left absent and the
+ * SDK resolves it from the environment.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: a bucket reachable only through the region the DynamoDB side was
+ * configured with is addressed in that region. The S3 SDK does not follow
+ * region redirects, so such a bucket otherwise failed with an opaque
+ * `PermanentRedirect` on the first offload.
+ */
+export declare function offloaderConfigFor(s3: S3OffloadConfig, adapter: AdapterName, clientConfig?: DynamoDBClientConfig): S3OffloadConfig;

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

@@ -0,0 +1,79 @@
+import { validationError } from '../../errors/errors.js';
+import { truncateForLog } from '../../logging/truncate.js';
+import { assertNoControlChars, assertWellFormed } from '../../validation/primitives.js';
+import { s3ClientOptions } from './client-types.js';
+export const DEFAULT_S3_KEY_PREFIX = 'langgraph-checkpoints/';
+export const MAX_S3_KEY_BYTES = 1024;
+export function encodeKeyPart(part) {
+    return Buffer.from(part, 'utf8').toString('base64url');
+}
+export function buildS3Key(prefix, parts, objectId) {
+    if (parts.length === 0) {
+        throw 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 > MAX_S3_KEY_BYTES) {
+        throw validationError(`the offloaded S3 object key would be ${bytes} bytes; S3 caps keys at ` +
+            `${MAX_S3_KEY_BYTES} — shorten the identifiers or the keyPrefix`, 's3Key');
+    }
+    return key;
+}
+const UNSCOPED_SEGMENTS = new Set(['', '.', '..']);
+export function assertScopedKeyPrefix(keyPrefix) {
+    if (typeof keyPrefix !== 'string' ||
+        keyPrefix === '' ||
+        keyPrefix === '/' ||
+        !keyPrefix.endsWith('/')) {
+        throw 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');
+    }
+    assertNoControlChars(keyPrefix, 's3.keyPrefix');
+    assertWellFormed(keyPrefix, 's3.keyPrefix');
+    if (keyPrefix
+        .slice(0, -1)
+        .split('/')
+        .some((segment) => UNSCOPED_SEGMENTS.has(segment))) {
+        throw 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');
+    }
+}
+export 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}`;
+}
+export function buildMarkerRuleId(prefix) {
+    return `${buildLifecycleRuleId(prefix)}-markers`;
+}
+export function defaultAdapterKeyPrefix(base, adapter) {
+    return `${base}${adapter}/`;
+}
+export function s3KeyScope(prefix, parts) {
+    return `${prefix}${parts.map(encodeKeyPart).join('/')}`;
+}
+export 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}/`);
+}
+export function assertKeyInScope(key, prefix, parts) {
+    if (isKeyInScope(key, prefix, parts))
+        return;
+    throw validationError(`s3Key "${truncateForLog(key)}" lies outside the S3 path this row may reference ` +
+        `("${truncateForLog(s3KeyScope(prefix, parts))}"); refusing to touch an object the row ` +
+        'does not own', 's3Key');
+}
+export function offloaderConfigFor(s3, adapter, clientConfig) {
+    const region = s3ClientOptions(s3.clientConfig).region ?? clientConfig?.region;
+    return {
+        ...s3,
+        keyPrefix: s3.keyPrefix ?? defaultAdapterKeyPrefix(DEFAULT_S3_KEY_PREFIX, adapter),
+        ...(region === undefined ? {} : { clientConfig: { ...s3.clientConfig, region } }),
+    };
+}