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

package/dist/cjs/history/internal/setup.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIST_SESSIONS_KEYS = exports.GET_MESSAGES_KEYS = exports.HISTORY_KEYS = exports.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = void 0;
+exports.setUpHistory = setUpHistory;
+const adapter_js_1 = require("../../shared/adapter.js");
+const json_serde_js_1 = require("../../shared/codec/json-serde.js");
+const errors_js_1 = require("../../shared/errors/errors.js");
+const ulid_js_1 = require("../../shared/ulid.js");
+const option_shape_js_1 = require("../../shared/validation/option-shape.js");
+exports.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = 18;
+exports.HISTORY_KEYS = (0, option_shape_js_1.allKeysOf)({
+    tableName: 'tableName',
+    client: 'client',
+    clientConfig: 'clientConfig',
+    createClient: 'createClient',
+    ttl: 'ttl',
+    logger: 'logger',
+    retry: 'retry',
+    indexShards: 'indexShards',
+    indexName: 'indexName',
+    readConcurrency: 'readConcurrency',
+    compression: 'compression',
+    s3: 's3',
+    serde: 'serde',
+    onCorruptMessage: 'onCorruptMessage',
+});
+exports.GET_MESSAGES_KEYS = (0, option_shape_js_1.allKeysOf)({
+    limit: 'limit',
+    before: 'before',
+    signal: 'signal',
+});
+exports.LIST_SESSIONS_KEYS = (0, option_shape_js_1.allKeysOf)({
+    limit: 'limit',
+    cursor: 'cursor',
+    maxIterations: 'maxIterations',
+    maxItems: 'maxItems',
+    signal: 'signal',
+});
+const CORRUPT_MESSAGE_POLICIES = ['skip', 'throw'];
+function assertCorruptMessagePolicy(policy) {
+    if (policy !== undefined && !CORRUPT_MESSAGE_POLICIES.includes(policy)) {
+        throw (0, errors_js_1.validationError)(`onCorruptMessage must be one of ${CORRUPT_MESSAGE_POLICIES.join(' | ')}`, 'onCorruptMessage');
+    }
+}
+function setUpHistory(options) {
+    (0, option_shape_js_1.assertShape)(options, exports.HISTORY_KEYS, 'options');
+    const shell = (0, adapter_js_1.openAdapter)(options, 'history', {
+        options: () => assertCorruptMessagePolicy(options.onCorruptMessage),
+        attemptFloor: exports.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS,
+    });
+    return {
+        shell,
+        context: {
+            ...shell.core,
+            serde: options.serde ?? json_serde_js_1.JSON_SERDE,
+            ulid: (0, ulid_js_1.createUlidFactory)(),
+            onCorruptMessage: options.onCorruptMessage ?? 'skip',
+        },
+    };
+}

package/dist/{history → cjs/history}/session-adapter.d.ts

@@ -22,12 +22,6 @@ export interface MultiSessionHistory {
     addMessages(sessionId: string, messages: BaseMessage[]): Promise<void>;
     clear(sessionId: string): Promise<void>;
 }
-/**
- * The earlier name of {@link MultiSessionHistory}, the same type.
- *
- * @deprecated Use `MultiSessionHistory`. This alias is removed in the next major release.
- */
-export type SessionBackend = MultiSessionHistory;
 /**
  * Single-session view over a {@link MultiSessionHistory}, implementing LangChain's
  * `BaseListChatMessageHistory` so it can drive `RunnableWithMessageHistory`.

package/dist/cjs/history/session-adapter.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamoDBSessionChatMessageHistory = void 0;
+const chat_history_1 = require("@langchain/core/chat_history");
+const boundary_js_1 = require("../shared/errors/boundary.js");
+const collaborators_js_1 = require("../shared/validation/collaborators.js");
+const option_shape_js_1 = require("../shared/validation/option-shape.js");
+const parse_js_1 = require("./internal/parse.js");
+const ADAPTER_WINDOW_KEYS = (0, option_shape_js_1.allKeysOf)({ limit: 'limit' });
+const MULTI_SESSION_HISTORY_MEMBERS = ['getMessages', 'addMessages', 'clear'];
+class DynamoDBSessionChatMessageHistory extends chat_history_1.BaseListChatMessageHistory {
+    backend;
+    lc_namespace = ['langchain', 'stores', 'message', 'dynamodb'];
+    sessionId;
+    window;
+    constructor(backend, sessionId, window) {
+        super();
+        this.backend = backend;
+        (0, collaborators_js_1.assertMembers)(backend, MULTI_SESSION_HISTORY_MEMBERS, 'backend');
+        this.sessionId = (0, parse_js_1.parseSessionId)(sessionId);
+        if (window !== undefined)
+            (0, option_shape_js_1.assertShape)(window, ADAPTER_WINDOW_KEYS, 'window');
+        this.window = window === undefined ? undefined : (0, parse_js_1.parseMessageWindow)(window);
+    }
+    getMessages() {
+        return (0, boundary_js_1.guardPublic)('session.getMessages', () => this.backend.getMessages(this.sessionId, this.window));
+    }
+    addMessage(message) {
+        return (0, boundary_js_1.guardPublic)('session.addMessage', () => this.backend.addMessages(this.sessionId, [message]));
+    }
+    addMessages(messages) {
+        return (0, boundary_js_1.guardPublic)('session.addMessages', () => this.backend.addMessages(this.sessionId, messages));
+    }
+    clear() {
+        return (0, boundary_js_1.guardPublic)('session.clear', () => this.backend.clear(this.sessionId));
+    }
+}
+exports.DynamoDBSessionChatMessageHistory = DynamoDBSessionChatMessageHistory;

package/dist/{history → cjs/history}/types.d.ts

@@ -9,7 +9,7 @@
  * a published type.
  */
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import type { BaseAdapterOptions, CancelOptions, CodecOptions } from '../shared/options';
+import type { BaseAdapterOptions, CancelOptions, CodecOptions } from '../shared/options.js';
 /** Options for {@link DynamoDBChatMessageHistory}. */
 export type DynamoDBChatMessageHistoryOptions = BaseAdapterOptions & CodecOptions & {
     /**
@@ -20,18 +20,21 @@ export type DynamoDBChatMessageHistoryOptions = BaseAdapterOptions & CodecOption
      */
     serde?: SerializerProtocol;
     /**
-     * What `getMessages` does when a stored message cannot be decoded — a
-     * decompression-guard trip, bytes that no longer parse as the form the row
-     * declares, or a decoded message LangChain cannot rebuild. A serializer
-     * declining intact bytes is not one of these and this option does not
-     * govern it: a `serdeType` the configured serializer has no grammar for
-     * after a config change, like an `lc` record naming a class outside its
-     * allow-list, is reported under **both** policies, because a payload this
-     * reader merely may not rebuild is not a payload that is gone. `'skip'`
-     * (the default) drops the item, logs it at `error` with its sort key so an
-     * operator can locate it, and returns the rest; `'throw'` fails the whole
-     * read, which is all-or-nothing but leaves the session unreadable until
-     * the bad row is removed out of band.
+     * What `getMessages` does when a stored message cannot be decoded. It
+     * covers a payload nobody can read — bytes that are no longer the form
+     * the row declares, a gone S3 object, a descriptor that is not one — and
+     * a stored message LangChain cannot rebuild. It does not govern a
+     * payload larger than this reader's `compression.maxDecompressedBytes`
+     * or `s3.maxDownloadBytes` (a limit of this reader's, not a lost
+     * payload), nor a serializer declining intact bytes: a `serdeType` the
+     * configured serializer has no grammar for after a config change, like
+     * an `lc` record naming a class outside its allow-list, is reported
+     * under **both** policies, because a payload this reader merely may not
+     * rebuild is not a payload that is gone. `'skip'` (the default) drops
+     * the item, logs it at `error` with its sort key so an operator can
+     * locate it, and returns the rest; `'throw'` fails the whole read, which
+     * is all-or-nothing but leaves the session unreadable until the bad row
+     * is removed out of band.
      */
     onCorruptMessage?: CorruptMessagePolicy;
 };
@@ -45,7 +48,7 @@ export type CorruptMessagePolicy = 'skip' | 'throw';
 export interface MessageWindow {
     /**
      * Return only the newest `limit` messages — still in chronological order. An
-     * integer from 1 to `MAX_PAGE_LIMIT` (10,000): the page rule every `limit` in
+     * integer from 1 to 10,000: the page rule every `limit` in
      * this package follows, with the one floor of 1 it has. `0` is refused rather
      * than answered with nothing, since for a window into a conversation it is
      * far more likely a bug than a request — and the empty window it would
@@ -61,7 +64,7 @@ export type GetMessagesOptions = MessageWindow & CancelOptions;
 export interface ListSessionsOptions extends CancelOptions {
     /**
      * How many sessions to return, newest-updated first; an integer from 0 to
-     * `MAX_PAGE_LIMIT` (10,000).
+     * 10,000.
      *
      * With a configured `indexName` it is the page size and defaults to 100.
      * Without one the read is a table scan that cannot be paged: an explicit

package/dist/cjs/history/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/{index.d.ts → cjs/index.d.ts}

@@ -12,24 +12,24 @@
  *
  * @packageDocumentation
  */
-export { DynamoDBSaver } from './checkpointer/saver';
-export type { DeltaChannelHistoryOptions, DynamoDBSaverOptions } from './checkpointer/types';
-export { DynamoDBStore } from './store/store';
-export type { DynamoDBStoreOptions, ListNamespacesOptions, SearchOptions, VectorReconcileResult, } from './store/types';
-export type { VectorBackend, VectorMatch, VectorRef, VectorScoreDirection, } from './store/vector-backend';
-export { DynamoDBChatMessageHistory } from './history/chat-message-history';
-export { DynamoDBSessionChatMessageHistory } from './history/session-adapter';
-export type { AdapterWindow, MultiSessionHistory, SessionBackend } from './history/session-adapter';
-export type { CorruptMessagePolicy, DynamoDBChatMessageHistoryOptions, GetMessagesOptions, ListSessionsOptions, SessionPage, MessageWindow, SessionMetadata, } from './history/types';
+export { DynamoDBSaver } from './checkpointer/saver.js';
+export type { DeltaChannelHistoryOptions, DynamoDBSaverOptions } from './checkpointer/types.js';
+export { DynamoDBStore } from './store/store.js';
+export type { DynamoDBStoreOptions, ListNamespacesOptions, SearchOptions, VectorReconcileResult, } from './store/types.js';
+export type { VectorBackend, VectorMatch, VectorRef, VectorScoreDirection, } from './store/vector-backend.js';
+export { DynamoDBChatMessageHistory } from './history/chat-message-history.js';
+export { DynamoDBSessionChatMessageHistory } from './history/session-adapter.js';
+export type { AdapterWindow, MultiSessionHistory } from './history/session-adapter.js';
+export type { CorruptMessagePolicy, DynamoDBChatMessageHistoryOptions, GetMessagesOptions, ListSessionsOptions, SessionPage, MessageWindow, SessionMetadata, } from './history/types.js';
 /**
  * Operator tool: give rows written before the recency index their index keys.
  * Run it before setting `indexName` on any adapter — see its own documentation
  * for why enabling the index first hides pre-existing rows from the listings.
  */
-export { backfillRecencyIndex } from './backfill/backfill';
-export type { BackfillOptions, BackfillResult } from './backfill/backfill';
-export { DynamoDBFactory } from './factory/factory';
-export type { AdapterSection, CreateAllOptions, CreatedAdapters, FactoryBaseOptions, } from './factory/types';
+export { backfillRecencyIndex } from './backfill/backfill.js';
+export type { BackfillOptions, BackfillResult } from './backfill/backfill.js';
+export { DynamoDBFactory } from './factory/factory.js';
+export type { AdapterSection, CreateAllOptions, CreatedAdapters, FactoryBaseOptions, } from './factory/types.js';
 /**
  * The plain JSON serializer the store and chat-history adapters use by
  * default, exported so a checkpointer can be given it in place of LangGraph's
@@ -37,17 +37,17 @@ export type { AdapterSection, CreateAllOptions, CreatedAdapters, FactoryBaseOpti
  * `{"lc": …}` record names. See the README's *Trust boundary* note and
  * `SECURITY.md`.
  */
-export { JSON_SERDE } from './shared/codec/json-serde';
-export { DynamoDBLangGraphError, isDynamoDBLangGraphError } from './shared/errors/base-error';
-export type { AnyDynamoDBLangGraphError, BatchDrainDetails, BatchPassDetails, BatchWriteIncompleteDetails, CompensationFailedDetails, ErrorContext, ErrorDetailsByCode, ErrorDetailsFor, } from './shared/errors/base-error';
-export { ErrorCode } from './shared/errors/error-code';
-export type { Logger, LogArgument } from './shared/logging/logger';
-export { redactLogger, redactSecrets } from './shared/logging/redaction';
-export type { Redactable, RedactLoggerOptions } from './shared/logging/redaction';
-export type { CancelOptions, BaseAdapterOptions, CodecOptions } from './shared/options';
-export type { DynamoDBDocumentLike } from './shared/dynamodb/client';
-export type { RetryAttemptInfo, RetryOptions, RetryPolicy } from './shared/dynamodb/retry';
-export type { TtlOption } from './shared/validation/ttl';
-export type { CompressionConfig } from './shared/codec/compression';
-export type { S3OffloadConfig } from './shared/codec/s3/config';
-export type { S3ClientConfigLike, S3ClientLike, S3ClientOption, S3ClientOptions, S3CommandLike, S3RegionLike, } from './shared/codec/s3/client-types';
+export { JSON_SERDE } from './shared/codec/json-serde.js';
+export { DynamoDBLangGraphError, isDynamoDBLangGraphError } from './shared/errors/base-error.js';
+export type { AnyDynamoDBLangGraphError, BatchDrainDetails, BatchPassDetails, BatchWriteIncompleteDetails, CompensationFailedDetails, ErrorContext, ErrorDetailsByCode, ErrorDetailsFor, } from './shared/errors/base-error.js';
+export { ErrorCode } from './shared/errors/error-code.js';
+export type { Logger, LogArgument } from './shared/logging/logger.js';
+export { redactLogger, redactSecrets } from './shared/logging/redaction.js';
+export type { Redactable, RedactLoggerOptions } from './shared/logging/redaction.js';
+export type { CancelOptions, BaseAdapterOptions, CodecOptions } from './shared/options.js';
+export type { DynamoDBDocumentLike, WriteRequest } from './shared/dynamodb/client.js';
+export type { RetryAttemptInfo, RetryOptions, RetryPolicy } from './shared/dynamodb/retry.js';
+export type { TtlOption } from './shared/validation/ttl.js';
+export type { CompressionConfig } from './shared/codec/compression.js';
+export type { S3OffloadConfig } from './shared/codec/s3/config.js';
+export type { S3ClientConfigLike, S3ClientOption, S3ClientOptions, S3RegionLike, } from './shared/codec/s3/client-types.js';

package/dist/cjs/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactSecrets = exports.redactLogger = exports.ErrorCode = exports.isDynamoDBLangGraphError = exports.DynamoDBLangGraphError = exports.JSON_SERDE = exports.DynamoDBFactory = exports.backfillRecencyIndex = exports.DynamoDBSessionChatMessageHistory = exports.DynamoDBChatMessageHistory = exports.DynamoDBStore = exports.DynamoDBSaver = void 0;
+var saver_js_1 = require("./checkpointer/saver.js");
+Object.defineProperty(exports, "DynamoDBSaver", { enumerable: true, get: function () { return saver_js_1.DynamoDBSaver; } });
+var store_js_1 = require("./store/store.js");
+Object.defineProperty(exports, "DynamoDBStore", { enumerable: true, get: function () { return store_js_1.DynamoDBStore; } });
+var chat_message_history_js_1 = require("./history/chat-message-history.js");
+Object.defineProperty(exports, "DynamoDBChatMessageHistory", { enumerable: true, get: function () { return chat_message_history_js_1.DynamoDBChatMessageHistory; } });
+var session_adapter_js_1 = require("./history/session-adapter.js");
+Object.defineProperty(exports, "DynamoDBSessionChatMessageHistory", { enumerable: true, get: function () { return session_adapter_js_1.DynamoDBSessionChatMessageHistory; } });
+var backfill_js_1 = require("./backfill/backfill.js");
+Object.defineProperty(exports, "backfillRecencyIndex", { enumerable: true, get: function () { return backfill_js_1.backfillRecencyIndex; } });
+var factory_js_1 = require("./factory/factory.js");
+Object.defineProperty(exports, "DynamoDBFactory", { enumerable: true, get: function () { return factory_js_1.DynamoDBFactory; } });
+var json_serde_js_1 = require("./shared/codec/json-serde.js");
+Object.defineProperty(exports, "JSON_SERDE", { enumerable: true, get: function () { return json_serde_js_1.JSON_SERDE; } });
+var base_error_js_1 = require("./shared/errors/base-error.js");
+Object.defineProperty(exports, "DynamoDBLangGraphError", { enumerable: true, get: function () { return base_error_js_1.DynamoDBLangGraphError; } });
+Object.defineProperty(exports, "isDynamoDBLangGraphError", { enumerable: true, get: function () { return base_error_js_1.isDynamoDBLangGraphError; } });
+var error_code_js_1 = require("./shared/errors/error-code.js");
+Object.defineProperty(exports, "ErrorCode", { enumerable: true, get: function () { return error_code_js_1.ErrorCode; } });
+var redaction_js_1 = require("./shared/logging/redaction.js");
+Object.defineProperty(exports, "redactLogger", { enumerable: true, get: function () { return redaction_js_1.redactLogger; } });
+Object.defineProperty(exports, "redactSecrets", { enumerable: true, get: function () { return redaction_js_1.redactSecrets; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/{shared → cjs/shared}/adapter.d.ts

@@ -9,14 +9,14 @@
  * `dynamodb/client.ts`; this module only reads that decision, to release a
  * client it built and leave an injected one alone.
  */
-import type { CompressionConfig } from './codec/compression';
-import { type AdapterName } from './codec/s3/config';
-import { S3Offloader } from './codec/s3/offloader';
-import { type DynamoDBDocumentLike } from './dynamodb/client';
-import { type RetryOptions } from './dynamodb/retry';
-import { type Logger } from './logging/logger';
-import type { BaseAdapterOptions, CodecOptions } from './options';
-import { type TtlOption } from './validation/ttl';
+import type { CompressionConfig } from './codec/compression.js';
+import { type AdapterName } from './codec/s3/config.js';
+import { S3Offloader } from './codec/s3/offloader.js';
+import { type DynamoDBDocumentLike } from './dynamodb/client.js';
+import { type RetryOptions } from './dynamodb/retry.js';
+import { type Logger } from './logging/logger.js';
+import type { BaseAdapterOptions, CodecOptions } from './options.js';
+import { type TtlOption } from './validation/ttl.js';
 /** Anything an adapter holds open and must hand back when it is torn down. */
 export interface Releasable {
     destroy(): void;
@@ -26,10 +26,12 @@ export interface Releasable {
  *
  * The hazard is the one `DynamoDBFactory`'s own `release` names: a teardown
  * written as a sequence of statements stops at the first throw, so everything
- * after it is stranded with no reference left to reach it by. Each adapter's
- * `destroy` was exactly that sequence — the S3 offloader, then the DynamoDB
- * client it built — and an S3 client whose sockets are already gone throws from
- * its own `destroy`, so the DynamoDB client leaked for the life of the process.
+ * after it is stranded with no reference left to reach it by. An adapter's
+ * teardown is such a sequence — the S3 offloader, then the DynamoDB client it
+ * built — and an S3 client whose sockets are already gone throws from its own
+ * `destroy`, which would leave the DynamoDB client open for the life of the
+ * process. Each resource is therefore released whatever the ones before it
+ * threw.
  *
  * Accepts: `resources` — in the order they should be released; an absent one
  * (an adapter with no offloader, a client the caller injected and therefore
@@ -72,7 +74,10 @@ export interface AdapterShell {
     readonly core: AdapterCore;
     /** Provision the S3 lifecycle rule for the configured ttl; see {@link ensureLifecycleFor}. */
     ensureLifecycleRule(): Promise<void>;
-    /** Release the offloader, and the DynamoDB client when the adapter built it; see {@link releaseOwned}. */
+    /**
+     * Release the offloader, and the DynamoDB client when the adapter built it;
+     * see {@link releaseOwned}. `release` runs once; a later call does nothing.
+     */
     release(): void;
 }
 /** The checks an adapter adds to the shared ones, and where they run. */
@@ -102,11 +107,17 @@ export type AdapterOptions = BaseAdapterOptions & CodecOptions & {
  * Returns: nothing. Without an offloader there is nothing to rule over, and
  * without a ttl no item expires, so any rule would delete a payload a live row
  * still needs: either absence does nothing. Installing a rule that is already
- * there is a no-op too, so calling this on every deploy is safe.
+ * there is a no-op too, so calling this on every deploy is safe. When it
+ * writes the rules but cannot confirm within its polling window that a
+ * re-read shows them — S3 documents that a lifecycle configuration can take
+ * minutes to propagate — it logs a `warn` and returns rather than throwing:
+ * the rules were written, and a later call can confirm them.
  *
  * Throws: whatever reading or writing the bucket's lifecycle configuration
- * throws, and `VALIDATION` naming `s3.keyPrefix` when the rule id this
- * prefix would take is already held by a different prefix.
+ * throws, `VALIDATION` naming `s3.keyPrefix` when the rule id this prefix
+ * would take is already held by a different prefix, and `CONTENTION` when
+ * every one of the five rounds this call polls needs a write — a competing
+ * writer replacing the configuration on every single re-read.
  *
  * Guarantees: needs the bucket-level `s3:GetLifecycleConfiguration` /
  * `s3:PutLifecycleConfiguration` permissions, which are broader than the

package/dist/cjs/shared/adapter.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.releaseOwned = releaseOwned;
+exports.ensureLifecycleFor = ensureLifecycleFor;
+exports.openAdapter = openAdapter;
+const config_js_1 = require("./codec/s3/config.js");
+const offloader_js_1 = require("./codec/s3/offloader.js");
+const concurrency_js_1 = require("./concurrency.js");
+const client_js_1 = require("./dynamodb/client.js");
+const recency_index_js_1 = require("./dynamodb/recency-index.js");
+const retry_js_1 = require("./dynamodb/retry.js");
+const base_error_js_1 = require("./errors/base-error.js");
+const logger_js_1 = require("./logging/logger.js");
+const collaborators_js_1 = require("./validation/collaborators.js");
+const options_js_1 = require("./validation/options.js");
+const ttl_js_1 = require("./validation/ttl.js");
+function releaseOwned(resources) {
+    let first;
+    for (const resource of resources) {
+        try {
+            resource?.destroy();
+        }
+        catch (error) {
+            first ??= (0, base_error_js_1.toError)(error);
+        }
+    }
+    if (first !== undefined)
+        throw first;
+}
+async function ensureLifecycleFor(core) {
+    if (!core.offloader || !core.ttl)
+        return;
+    await core.offloader.ensureLifecycleRule((0, ttl_js_1.lifecycleExpirationDays)(core.ttl), core.logger);
+}
+function openAdapter(options, adapter, checks = {}) {
+    (0, options_js_1.assertBaseAdapterOptions)(options);
+    checks.options?.();
+    (0, collaborators_js_1.assertBaseCollaborators)(options);
+    checks.collaborators?.();
+    const logger = (0, logger_js_1.resolveLogger)(options.logger);
+    const resolved = (0, client_js_1.resolveDynamoDBClient)(options);
+    if (!resolved.ownsClient)
+        void (0, client_js_1.warnOnStackedRetries)(resolved.client, logger);
+    const offloader = options.s3
+        ? new offloader_js_1.S3Offloader((0, config_js_1.offloaderConfigFor)(options.s3, adapter, options.clientConfig), logger)
+        : undefined;
+    const core = {
+        client: resolved.client,
+        tableName: options.tableName,
+        compression: options.compression,
+        offloader,
+        ttl: options.ttl,
+        logger,
+        retry: (0, retry_js_1.resolveRetryPolicy)(options.retry, logger, checks.attemptFloor),
+        indexShards: options.indexShards ?? recency_index_js_1.DEFAULT_INDEX_SHARDS,
+        readConcurrency: options.readConcurrency ?? concurrency_js_1.DEFAULT_READ_CONCURRENCY,
+        indexName: options.indexName,
+    };
+    let released = false;
+    return {
+        core,
+        ensureLifecycleRule: () => ensureLifecycleFor(core),
+        release: () => {
+            if (released)
+                return;
+            released = true;
+            releaseOwned([offloader, resolved.ownsClient ? resolved.ddbClient : undefined]);
+        },
+    };
+}

package/dist/cjs/shared/clock.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nowIso = nowIso;
+exports.nowMs = nowMs;
+exports.nowSeconds = nowSeconds;
+function nowIso() {
+    return new Date(Date.now()).toISOString();
+}
+function nowMs() {
+    return Date.now();
+}
+function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}

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

@@ -9,8 +9,8 @@
  * here from one a retry might cure.
  */
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import { type CompressionConfig } from './compression';
-import type { S3Offloader } from './s3/offloader';
+import { type CompressionConfig } from './compression.js';
+import type { S3Offloader } from './s3/offloader.js';
 /**
  * Largest serialized payload stored inline when no S3 offloader is configured:
  * DynamoDB's 400 KB item cap less 8 KB of headroom for the item's keys,
@@ -234,13 +234,14 @@ export interface EncodeOptions {
  *
  * Throws: whatever `serde.dumpsTyped` throws; `ABORTED` when the signal
  * fires during the upload; `S3_OFFLOAD_FAILED` from the upload; and two
- * distinguishable `VALIDATION` errors. One names `payload` — the bytes are too
- * large to store inline — and is raised only when there is **no** offloader
- * and they exceed `MAX_INLINE_PAYLOAD_BYTES`. With an offloader that
- * cell cannot arise: `s3.thresholdBytes` is itself capped at that limit
- * (`src/shared/validation/options.ts`, `assertS3`), so bytes too large
- * to store inline are always at or above the threshold and offload instead.
- * The other names `value` — it serialises to nothing (see
+ * distinguishable `VALIDATION` errors. One names `payload`, raised either
+ * way a payload can turn out unstorable: with **no** offloader, the bytes
+ * exceed `MAX_INLINE_PAYLOAD_BYTES`; with one, `s3.thresholdBytes` is itself
+ * capped at that limit (`src/shared/validation/options.ts`, `assertS3`), so
+ * bytes too large to store inline are always at or above the threshold and
+ * offload instead — where they are refused if they exceed
+ * `s3.maxDownloadBytes`, before the upload ({@link S3Offloader.upload}). The
+ * other names `value` — it serialises to nothing (see
  * {@link assertSerialisedToBytes}) — and is raised for an offloaded payload
  * and an inline one alike, before either is stored.
  */
@@ -290,6 +291,21 @@ export declare function collectS3Keys(descriptors: readonly (DescriptorRef | nul
  * failure this test exists to classify.
  */
 export declare function isMissingObjectError(error: Error): boolean;
+/**
+ * True when S3 refused to answer a download rather than answering it.
+ *
+ * Accepts: `error` — any error; only `S3_OFFLOAD_FAILED` whose cause the
+ * classifier codes `ACCESS_DENIED` matches.
+ *
+ * Returns: whether S3 declined to say anything about the object. Without
+ * `s3:ListBucket` on the bucket, S3 answers a GET of a key that does not exist
+ * with 403 rather than 404, so this is what a released object looks like to
+ * such a role — and equally what a missing `s3:GetObject` looks like. A caller
+ * settles which by other means before treating it as either.
+ *
+ * Throws: **nothing**, for any value.
+ */
+export declare function isRefusedObjectError(error: Error): boolean;
 /**
  * True when a payload can never be read again, as opposed to a failure that may
  * succeed on retry or after a configuration fix (throttling, network,
@@ -297,17 +313,18 @@ export declare function isMissingObjectError(error: Error): boolean;
  *
  * Accepts: `error` — any error. Permanent are: its object is gone
  * ({@link isMissingObjectError}), its bytes are not the form the row declares
- * (`PAYLOAD_CORRUPT`), it trips the decompression guard (`COMPRESSION_LIMIT`),
- * or the row's own descriptor is unreadable ({@link isUnreadableDescriptor}).
- * Everything else is false, including an error that carries no code at all, and
- * including three refusals that look like loss and are not. The `s3Key` scope
- * refusal: a row pointing outside its own path is a configuration or tenancy
- * fault to report, not a payload to write off. The `serde` refusal, on the same
- * reasoning: the bytes are checked against the form the row declares before
- * that code is chosen, so reaching it means they are undamaged and a serializer
- * declining to reconstruct the class they name says what *this* reader may do,
- * not what the payload is (see `loadPayloadValue`). And `FORMAT_UNSUPPORTED`,
- * on a row or on a payload: newer is not lost.
+ * (`PAYLOAD_CORRUPT`), or the row's own descriptor is unreadable
+ * ({@link isUnreadableDescriptor}). Everything else is false, including an
+ * error that carries no code at all, and including four refusals that look
+ * like loss and are not. The `s3Key` scope refusal: a row pointing outside
+ * its own path is a configuration or tenancy fault to report, not a payload
+ * to write off. The `serde` refusal, on the same reasoning (see
+ * `loadPayloadValue`). `FORMAT_UNSUPPORTED`, on a row or on a payload: newer
+ * is not lost. And `COMPRESSION_LIMIT`: a payload larger than this reader
+ * inflates is intact, and a reader with a larger cap reads it. From this
+ * release on, this package never compresses a payload past its writer's own
+ * cap; a payload an earlier release compressed — which did not check it —
+ * can still trip a smaller one here.
  *
  * Returns: whether a caller should report rather than retry.
  *