@farukada/aws-langgraph-dynamodb-ts 0.2.2 → 0.3.1

package/dist/shared/codec/codec.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PayloadLocation = void 0;
+exports.encodePayload = encodePayload;
+exports.decodePayload = decodePayload;
+const compression_1 = require("./compression");
+/** Where an encoded payload lives. */
+var PayloadLocation;
+(function (PayloadLocation) {
+    PayloadLocation["INLINE"] = "INLINE";
+    PayloadLocation["S3"] = "S3";
+})(PayloadLocation || (exports.PayloadLocation = PayloadLocation = {}));
+function requireOffloader(deps) {
+    if (!deps.offloader) {
+        throw new Error('Cannot decode an S3 payload without an offloader');
+    }
+    return deps.offloader;
+}
+/**
+ * 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.
+ */
+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 };
+    }
+    return { location: PayloadLocation.INLINE, serdeType, compressed, bytes };
+}
+/** 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);
+}
+//# sourceMappingURL=codec.js.map

package/dist/shared/codec/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../../src/shared/codec/codec.ts"],"names":[],"mappings":";;;AAsDA,sCAeC;AAGD,sCAWC;AAjFD,+CAA2F;AAG3F,sCAAsC;AACtC,IAAY,eAGX;AAHD,WAAY,eAAe;IACzB,oCAAiB,CAAA;IACjB,4BAAS,CAAA;AACX,CAAC,EAHW,eAAe,+BAAf,eAAe,QAG1B;AAiCD,SAAS,gBAAgB,CAAC,IAAe;IACvC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,aAAa,CACjC,KAAQ,EACR,IAAe,EACf,OAAsB;IAEtB,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAC5D,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAsB,IAAI,CAAC,WAAW;QAC/D,CAAC,CAAC,MAAM,IAAA,sBAAQ,EAAC,GAAG,EAAE,IAAI,CAAC,WAAW,CAAC;QACvC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACtC,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxD,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC1C,OAAO,EAAE,QAAQ,EAAE,eAAe,CAAC,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACxE,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAC5E,CAAC;AAED,4EAA4E;AACrE,KAAK,UAAU,aAAa,CAAI,UAA6B,EAAE,IAAe;IACnF,MAAM,GAAG,GACP,UAAU,CAAC,QAAQ,KAAK,eAAe,CAAC,EAAE;QACxC,CAAC,CAAC,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC;QACzD,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC;IACvB,MAAM,KAAK,GAAG,MAAM,IAAA,wBAAU,EAC5B,GAAG,EACH,UAAU,CAAC,UAAU,EACrB,IAAI,CAAC,WAAW,EAAE,oBAAoB,CACvC,CAAC;IACF,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;AAC5D,CAAC"}

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

@@ -0,0 +1,25 @@
+/** Configuration for payload compression. */
+export interface CompressionConfig {
+    enabled: boolean;
+    minSizeBytes?: number;
+    level?: number;
+    maxDecompressedBytes?: number;
+}
+/** The bytes to store plus whether they were gzip-compressed. */
+export interface CompressionResult {
+    bytes: Uint8Array;
+    compressed: boolean;
+}
+/**
+ * Gzip `data` when it is at least `minSizeBytes` and compression actually saves
+ * space. Returns the bytes to store and a `compressed` flag the caller records
+ * in the payload descriptor; compression is never inferred from the bytes.
+ */
+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
+ * 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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../../src/shared/codec/compression.ts"],"names":[],"mappings":"AAiBA,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAS5B;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,OAAO,EACnB,QAAQ,GAAE,MAAuC,GAChD,OAAO,CAAC,UAAU,CAAC,CAgBrB"}

package/dist/shared/codec/compression.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compress = compress;
+exports.decompress = decompress;
+const node_util_1 = require("node:util");
+const node_zlib_1 = require("node:zlib");
+const constants_1 = require("../constants");
+const base_error_1 = require("../errors/base-error");
+const error_code_1 = require("../errors/error-code");
+const gzipAsync = (0, node_util_1.promisify)(node_zlib_1.gzip);
+const gunzipAsync = (0, node_util_1.promisify)(node_zlib_1.gunzip);
+/** Minimum fraction of the original size the gzip output must beat to be kept. */
+const COMPRESSION_GAIN_RATIO = 0.9;
+/**
+ * Gzip `data` when it is at least `minSizeBytes` and compression actually saves
+ * space. Returns the bytes to store and a `compressed` flag the caller records
+ * in the payload descriptor; compression is never inferred from the bytes.
+ */
+async function compress(data, config) {
+    const minSize = config.minSizeBytes ?? constants_1.DEFAULT_COMPRESSION_MIN_BYTES;
+    if (!config.enabled || data.length < minSize)
+        return { bytes: data, compressed: false };
+    const level = config.level ?? constants_1.DEFAULT_COMPRESSION_LEVEL;
+    const gzipped = new Uint8Array(await gzipAsync(data, { level }));
+    if (gzipped.length >= data.length * COMPRESSION_GAIN_RATIO) {
+        return { bytes: data, compressed: false };
+    }
+    return { bytes: gzipped, compressed: true };
+}
+/**
+ * Gunzip `data` when `compressed` is true; otherwise return it unchanged. Throws
+ * 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) {
+    if (!compressed)
+        return data;
+    try {
+        return new Uint8Array(await gunzipAsync(data, { maxOutputLength: maxBytes }));
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ERR_BUFFER_TOO_LARGE') {
+            throw new base_error_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/compression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.js","sourceRoot":"","sources":["../../../src/shared/codec/compression.ts"],"names":[],"mappings":";;AAoCA,4BAYC;AAOD,gCAoBC;AA3ED,yCAAsC;AACtC,yCAAyC;AAEzC,4CAIsB;AACtB,qDAA8D;AAC9D,qDAAiD;AAEjD,MAAM,SAAS,GAAG,IAAA,qBAAS,EAAC,gBAAI,CAAC,CAAC;AAClC,MAAM,WAAW,GAAG,IAAA,qBAAS,EAAC,kBAAM,CAAC,CAAC;AAEtC,kFAAkF;AAClF,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAgBnC;;;;GAIG;AACI,KAAK,UAAU,QAAQ,CAC5B,IAAgB,EAChB,MAAyB;IAEzB,MAAM,OAAO,GAAG,MAAM,CAAC,YAAY,IAAI,yCAA6B,CAAC;IACrE,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,GAAG,OAAO;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACxF,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,qCAAyB,CAAC;IACxD,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,MAAM,SAAS,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACjE,IAAI,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,GAAG,sBAAsB,EAAE,CAAC;QAC3D,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAC5C,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,UAAU,CAC9B,IAAgB,EAChB,UAAmB,EACnB,WAAmB,0CAA8B;IAEjD,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,IAAI,CAAC;QACH,OAAO,IAAI,UAAU,CAAC,MAAM,WAAW,CAAC,IAAI,EAAE,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IAChF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,KAA0B,CAAC;QACvC,IAAI,GAAG,CAAC,IAAI,KAAK,sBAAsB,EAAE,CAAC;YACxC,MAAM,IAAI,mCAAsB,CAC9B,+CAA+C,QAAQ,QAAQ,EAC/D,sBAAS,CAAC,iBAAiB,EAC3B,EAAE,EACF,KAAc,CACf,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,4 @@
+import { type PayloadDescriptor } from './codec';
+/** 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

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

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor-keys.d.ts","sourceRoot":"","sources":["../../../src/shared/codec/descriptor-keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAmB,MAAM,SAAS,CAAC;AAElE,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAMjF"}

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

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectS3Keys = collectS3Keys;
+const codec_1 = require("./codec");
+/** Collect the S3 keys of any offloaded descriptors, for orphan cleanup. */
+function collectS3Keys(descriptors) {
+    const keys = [];
+    for (const descriptor of descriptors) {
+        if (descriptor.location === codec_1.PayloadLocation.S3)
+            keys.push(descriptor.s3Key);
+    }
+    return keys;
+}
+//# sourceMappingURL=descriptor-keys.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor-keys.js","sourceRoot":"","sources":["../../../src/shared/codec/descriptor-keys.ts"],"names":[],"mappings":";;AAGA,sCAMC;AATD,mCAAkE;AAElE,4EAA4E;AAC5E,SAAgB,aAAa,CAAC,WAAyC;IACrE,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,IAAI,UAAU,CAAC,QAAQ,KAAK,uBAAe,CAAC,EAAE;YAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

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

@@ -0,0 +1,8 @@
+import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
+/**
+ * A minimal JSON serializer implementing LangGraph's {@link SerializerProtocol},
+ * used by adapters (the store, history) that persist plain JSON values through
+ * the shared payload codec.
+ */
+export declare const JSON_SERDE: SerializerProtocol;
+//# sourceMappingURL=json-serde.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json-serde.d.ts","sourceRoot":"","sources":["../../../src/shared/codec/json-serde.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,kBAQxB,CAAC"}

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

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSON_SERDE = void 0;
+/**
+ * A minimal JSON serializer implementing LangGraph's {@link SerializerProtocol},
+ * used by adapters (the store, history) that persist plain JSON values through
+ * the shared payload codec.
+ */
+exports.JSON_SERDE = {
+    async dumpsTyped(value) {
+        return ['json', new TextEncoder().encode(JSON.stringify(value))];
+    },
+    async loadsTyped(_type, data) {
+        const text = typeof data === 'string' ? data : new TextDecoder().decode(data);
+        return JSON.parse(text);
+    },
+};
+//# sourceMappingURL=json-serde.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json-serde.js","sourceRoot":"","sources":["../../../src/shared/codec/json-serde.ts"],"names":[],"mappings":";;;AAEA;;;;GAIG;AACU,QAAA,UAAU,GAAuB;IAC5C,KAAK,CAAC,UAAU,CAAC,KAAK;QACpB,OAAO,CAAC,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,KAAK,CAAC,UAAU,CAAC,KAAK,EAAE,IAAI;QAC1B,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACF,CAAC"}

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

@@ -0,0 +1,6 @@
+import type { S3Client, S3ClientConfig } from '@aws-sdk/client-s3';
+/** Lazily import the optional `@aws-sdk/client-s3` peer, caching the module. */
+export declare function loadS3Sdk(): Promise<typeof import('@aws-sdk/client-s3')>;
+/** Construct an `S3Client` from `config` using the lazily-loaded SDK. */
+export declare function createDefaultS3Client(config: S3ClientConfig): Promise<S3Client>;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/shared/codec/s3/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAInE,gFAAgF;AAChF,wBAAsB,SAAS,IAAI,OAAO,CAAC,cAAc,oBAAoB,CAAC,CAAC,CAK9E;AAED,yEAAyE;AACzE,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAGrF"}

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

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadS3Sdk = loadS3Sdk;
+exports.createDefaultS3Client = createDefaultS3Client;
+let sdkPromise;
+/** Lazily import the optional `@aws-sdk/client-s3` peer, caching the module. */
+async function loadS3Sdk() {
+    if (!sdkPromise) {
+        sdkPromise = import('@aws-sdk/client-s3');
+    }
+    return sdkPromise;
+}
+/** Construct an `S3Client` from `config` using the lazily-loaded SDK. */
+async function createDefaultS3Client(config) {
+    const { S3Client: S3ClientCtor } = await loadS3Sdk();
+    return new S3ClientCtor(config);
+}
+//# sourceMappingURL=client.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../../src/shared/codec/s3/client.ts"],"names":[],"mappings":";;AAKA,8BAKC;AAGD,sDAGC;AAdD,IAAI,UAAoE,CAAC;AAEzE,gFAAgF;AACzE,KAAK,UAAU,SAAS;IAC7B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,UAAU,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,yEAAyE;AAClE,KAAK,UAAU,qBAAqB,CAAC,MAAsB;IAChE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM,SAAS,EAAE,CAAC;IACrD,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC"}

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

@@ -0,0 +1,16 @@
+import type { S3Client, S3ClientConfig } from '@aws-sdk/client-s3';
+/** Configuration for offloading large payloads to S3. */
+export interface S3OffloadConfig {
+    bucketName: string;
+    keyPrefix?: string;
+    thresholdBytes?: number;
+    serverSideEncryption?: string;
+    sseKmsKeyId?: string;
+    clientConfig?: S3ClientConfig;
+    createS3Client?: (config: S3ClientConfig) => S3Client;
+}
+/** Build a fully-qualified S3 key: `${prefix}${parts.join('/')}.bin`. */
+export declare function buildS3Key(prefix: string, parts: readonly string[]): string;
+/** Build a deterministic, TTL-independent lifecycle rule id from the prefix. */
+export declare function buildLifecycleRuleId(prefix: string): string;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/shared/codec/s3/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEnE,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,QAAQ,CAAC;CACvD;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE3E;AAED,gFAAgF;AAChF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAG3D"}

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

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildS3Key = buildS3Key;
+exports.buildLifecycleRuleId = buildLifecycleRuleId;
+/** Build a fully-qualified S3 key: `${prefix}${parts.join('/')}.bin`. */
+function buildS3Key(prefix, parts) {
+    return `${prefix}${parts.join('/')}.bin`;
+}
+/** Build a deterministic, TTL-independent lifecycle rule id from the prefix. */
+function buildLifecycleRuleId(prefix) {
+    const slug = prefix.replace(/\/+$/, '').replace(/[^a-zA-Z0-9-]/g, '-') || 'default';
+    return `langgraph-ttl-${slug}`;
+}
+//# sourceMappingURL=config.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../src/shared/codec/s3/config.ts"],"names":[],"mappings":";;AAcA,gCAEC;AAGD,oDAGC;AATD,yEAAyE;AACzE,SAAgB,UAAU,CAAC,MAAc,EAAE,KAAwB;IACjE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;AAC3C,CAAC;AAED,gFAAgF;AAChF,SAAgB,oBAAoB,CAAC,MAAc;IACjD,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,IAAI,SAAS,CAAC;IACpF,OAAO,iBAAiB,IAAI,EAAE,CAAC;AACjC,CAAC"}

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

@@ -0,0 +1,8 @@
+import type { S3Client } from '@aws-sdk/client-s3';
+/**
+ * Delete `keys` from `bucket` in chunks of 1000 (the DeleteObjects limit).
+ * Returns the keys S3 reported as failed — never throws on per-key errors so
+ * callers (orphan cleanup) can decide how loudly to react.
+ */
+export declare function deleteObjects(client: S3Client, bucket: string, keys: string[]): Promise<string[]>;
+//# sourceMappingURL=delete.d.ts.map

package/dist/shared/codec/s3/delete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../../../src/shared/codec/s3/delete.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAKnD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBnB"}

package/dist/shared/codec/s3/delete.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteObjects = deleteObjects;
+const constants_1 = require("../../constants");
+const client_1 = require("./client");
+/**
+ * Delete `keys` from `bucket` in chunks of 1000 (the DeleteObjects limit).
+ * Returns the keys S3 reported as failed — never throws on per-key errors so
+ * callers (orphan cleanup) can decide how loudly to react.
+ */
+async function deleteObjects(client, bucket, keys) {
+    if (keys.length === 0)
+        return [];
+    const { DeleteObjectsCommand } = await (0, client_1.loadS3Sdk)();
+    const failed = [];
+    for (let offset = 0; offset < keys.length; offset += constants_1.S3_DELETE_BATCH_MAX) {
+        const chunk = keys.slice(offset, offset + constants_1.S3_DELETE_BATCH_MAX);
+        const response = await client.send(new DeleteObjectsCommand({
+            Bucket: bucket,
+            Delete: { Objects: chunk.map((key) => ({ Key: key })), Quiet: true },
+        }));
+        for (const error of response.Errors ?? []) {
+            if (error.Key)
+                failed.push(error.Key);
+        }
+    }
+    return failed;
+}
+//# sourceMappingURL=delete.js.map

package/dist/shared/codec/s3/delete.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete.js","sourceRoot":"","sources":["../../../../src/shared/codec/s3/delete.ts"],"names":[],"mappings":";;AAUA,sCAqBC;AA7BD,+CAAsD;AACtD,qCAAqC;AAErC;;;;GAIG;AACI,KAAK,UAAU,aAAa,CACjC,MAAgB,EAChB,MAAc,EACd,IAAc;IAEd,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,EAAE,oBAAoB,EAAE,GAAG,MAAM,IAAA,kBAAS,GAAE,CAAC;IACnD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,IAAI,+BAAmB,EAAE,CAAC;QACzE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,+BAAmB,CAAC,CAAC;QAC/D,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAChC,IAAI,oBAAoB,CAAC;YACvB,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE;SACrE,CAAC,CACH,CAAC;QACF,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;YAC1C,IAAI,KAAK,CAAC,GAAG;gBAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,8 @@
+import type { S3Client } from '@aws-sdk/client-s3';
+/**
+ * Idempotently ensure a `${ttlDays}`-day expiration lifecycle rule exists for
+ * `prefix`. Reads existing rules, preserves user-defined ones, and only
+ * adds/updates the library's prefix-scoped rule.
+ */
+export declare function ensureLifecycleRule(client: S3Client, bucket: string, prefix: string, ttlDays: number): Promise<void>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/shared/codec/s3/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../src/shared/codec/s3/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAsBlE;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/shared/codec/s3/lifecycle.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureLifecycleRule = ensureLifecycleRule;
+const client_1 = require("./client");
+const config_1 = require("./config");
+async function readRules(client, bucket) {
+    const { GetBucketLifecycleConfigurationCommand } = await (0, client_1.loadS3Sdk)();
+    try {
+        const existing = await client.send(new GetBucketLifecycleConfigurationCommand({ Bucket: bucket }));
+        return existing.Rules ?? [];
+    }
+    catch (error) {
+        if (error.name === 'NoSuchLifecycleConfiguration')
+            return [];
+        throw error;
+    }
+}
+function alreadyCorrect(rule, ttlDays) {
+    return rule?.Status === 'Enabled' && rule.Expiration?.Days === ttlDays;
+}
+/**
+ * Idempotently ensure a `${ttlDays}`-day expiration lifecycle rule exists for
+ * `prefix`. Reads existing rules, preserves user-defined ones, and only
+ * adds/updates the library's prefix-scoped rule.
+ */
+async function ensureLifecycleRule(client, bucket, prefix, ttlDays) {
+    const ruleId = (0, config_1.buildLifecycleRuleId)(prefix);
+    const rules = await readRules(client, bucket);
+    const existing = rules.find((rule) => rule.ID === ruleId);
+    if (alreadyCorrect(existing, ttlDays))
+        return;
+    const newRule = {
+        ID: ruleId,
+        Filter: { Prefix: prefix },
+        Status: 'Enabled',
+        Expiration: { Days: ttlDays },
+    };
+    const merged = existing
+        ? rules.map((rule) => (rule.ID === ruleId ? newRule : rule))
+        : [...rules, newRule];
+    const { PutBucketLifecycleConfigurationCommand } = await (0, client_1.loadS3Sdk)();
+    await client.send(new PutBucketLifecycleConfigurationCommand({
+        Bucket: bucket,
+        LifecycleConfiguration: { Rules: merged },
+    }));
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/shared/codec/s3/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../../../src/shared/codec/s3/lifecycle.ts"],"names":[],"mappings":";;AA2BA,kDA0BC;AAnDD,qCAAqC;AACrC,qCAAgD;AAEhD,KAAK,UAAU,SAAS,CAAC,MAAgB,EAAE,MAAc;IACvD,MAAM,EAAE,sCAAsC,EAAE,GAAG,MAAM,IAAA,kBAAS,GAAE,CAAC;IACrE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAChC,IAAI,sCAAsC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAC/D,CAAC;QACF,OAAO,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA2B,CAAC,IAAI,KAAK,8BAA8B;YAAE,OAAO,EAAE,CAAC;QACpF,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,IAA+B,EAAE,OAAe;IACtE,OAAO,IAAI,EAAE,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,EAAE,IAAI,KAAK,OAAO,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,mBAAmB,CACvC,MAAgB,EAChB,MAAc,EACd,MAAc,EACd,OAAe;IAEf,MAAM,MAAM,GAAG,IAAA,6BAAoB,EAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;IAC1D,IAAI,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC;QAAE,OAAO;IAC9C,MAAM,OAAO,GAAkB;QAC7B,EAAE,EAAE,MAAM;QACV,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;QAC1B,MAAM,EAAE,SAAS;QACjB,UAAU,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;KAC9B,CAAC;IACF,MAAM,MAAM,GAAG,QAAQ;QACrB,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC5D,CAAC,CAAC,CAAC,GAAG,KAAK,EAAE,OAAO,CAAC,CAAC;IACxB,MAAM,EAAE,sCAAsC,EAAE,GAAG,MAAM,IAAA,kBAAS,GAAE,CAAC;IACrE,MAAM,MAAM,CAAC,IAAI,CACf,IAAI,sCAAsC,CAAC;QACzC,MAAM,EAAE,MAAM;QACd,sBAAsB,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;KAC1C,CAAC,CACH,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,33 @@
+import { S3OffloadConfig } from './config';
+/**
+ * Thin holder composing the pure S3 functions. Owns config + the lazily-built
+ * S3 client and delegates all real work; every method is a small delegation.
+ */
+export declare class S3Offloader {
+    private client;
+    private readonly bucketName;
+    private readonly keyPrefix;
+    private readonly thresholdBytes;
+    private readonly sse;
+    private readonly sseKmsKeyId?;
+    private readonly config;
+    constructor(config: S3OffloadConfig);
+    private getClient;
+    /** True when `data` is large enough to warrant S3 offload. */
+    shouldOffload(data: Uint8Array): boolean;
+    /** Build the S3 key for the given key parts. */
+    buildKey(parts: readonly string[]): string;
+    /** The configured key prefix. */
+    getKeyPrefix(): string;
+    /** Upload `data` under `key`, returning the key. */
+    upload(key: string, data: Uint8Array): Promise<string>;
+    /** Download the bytes stored under `key`. */
+    download(key: string): Promise<Uint8Array>;
+    /** Delete `keys`, returning the keys S3 reported as failed. */
+    deleteBatch(keys: string[]): Promise<string[]>;
+    /** Ensure a `${ttlDays}`-day expiration lifecycle rule exists for the prefix. */
+    ensureLifecycleRule(ttlDays: number): Promise<void>;
+    /** Release the underlying S3 client, if one was created. */
+    destroy(): void;
+}
+//# sourceMappingURL=offloader.d.ts.map

package/dist/shared/codec/s3/offloader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offloader.d.ts","sourceRoot":"","sources":["../../../../src/shared/codec/s3/offloader.ts"],"names":[],"mappings":"AAIA,OAAO,EAAc,eAAe,EAAE,MAAM,UAAU,CAAC;AAKvD;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;gBAE7B,MAAM,EAAE,eAAe;YASrB,SAAS;IAUvB,8DAA8D;IAC9D,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO;IAIxC,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM;IAI1C,iCAAiC;IACjC,YAAY,IAAI,MAAM;IAItB,oDAAoD;IAC9C,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAW5D,6CAA6C;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAIhD,+DAA+D;IACzD,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAIpD,iFAAiF;IAC3E,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,4DAA4D;IAC5D,OAAO,IAAI,IAAI;CAGhB"}

package/dist/shared/codec/s3/offloader.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3Offloader = void 0;
+const constants_1 = require("../../constants");
+const client_1 = require("./client");
+const config_1 = require("./config");
+const delete_1 = require("./delete");
+const lifecycle_1 = require("./lifecycle");
+const read_write_1 = require("./read-write");
+/**
+ * Thin holder composing the pure S3 functions. Owns config + the lazily-built
+ * S3 client and delegates all real work; every method is a small delegation.
+ */
+class S3Offloader {
+    client;
+    bucketName;
+    keyPrefix;
+    thresholdBytes;
+    sse;
+    sseKmsKeyId;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.bucketName = config.bucketName;
+        this.keyPrefix = config.keyPrefix ?? constants_1.DEFAULT_S3_KEY_PREFIX;
+        this.thresholdBytes = config.thresholdBytes ?? constants_1.DEFAULT_S3_THRESHOLD_BYTES;
+        this.sse = config.serverSideEncryption ?? constants_1.DEFAULT_S3_SSE;
+        this.sseKmsKeyId = config.sseKmsKeyId;
+    }
+    async getClient() {
+        if (!this.client) {
+            const cfg = this.config.clientConfig ?? {};
+            this.client = this.config.createS3Client
+                ? this.config.createS3Client(cfg)
+                : await (0, client_1.createDefaultS3Client)(cfg);
+        }
+        return this.client;
+    }
+    /** True when `data` is large enough to warrant S3 offload. */
+    shouldOffload(data) {
+        return data.length >= this.thresholdBytes;
+    }
+    /** Build the S3 key for the given key parts. */
+    buildKey(parts) {
+        return (0, config_1.buildS3Key)(this.keyPrefix, parts);
+    }
+    /** The configured key prefix. */
+    getKeyPrefix() {
+        return this.keyPrefix;
+    }
+    /** Upload `data` under `key`, returning the key. */
+    async upload(key, data) {
+        await (0, read_write_1.uploadObject)(await this.getClient(), {
+            bucket: this.bucketName,
+            key,
+            data,
+            serverSideEncryption: this.sse,
+            sseKmsKeyId: this.sseKmsKeyId,
+        });
+        return key;
+    }
+    /** Download the bytes stored under `key`. */
+    async download(key) {
+        return (0, read_write_1.downloadObject)(await this.getClient(), this.bucketName, key);
+    }
+    /** Delete `keys`, returning the keys S3 reported as failed. */
+    async deleteBatch(keys) {
+        return (0, delete_1.deleteObjects)(await this.getClient(), this.bucketName, keys);
+    }
+    /** Ensure a `${ttlDays}`-day expiration lifecycle rule exists for the prefix. */
+    async ensureLifecycleRule(ttlDays) {
+        return (0, lifecycle_1.ensureLifecycleRule)(await this.getClient(), this.bucketName, this.keyPrefix, ttlDays);
+    }
+    /** Release the underlying S3 client, if one was created. */
+    destroy() {
+        this.client?.destroy();
+    }
+}
+exports.S3Offloader = S3Offloader;
+//# sourceMappingURL=offloader.js.map

package/dist/shared/codec/s3/offloader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offloader.js","sourceRoot":"","sources":["../../../../src/shared/codec/s3/offloader.ts"],"names":[],"mappings":";;;AAEA,+CAAoG;AACpG,qCAAiD;AACjD,qCAAuD;AACvD,qCAAyC;AACzC,2CAAkD;AAClD,6CAA4D;AAE5D;;;GAGG;AACH,MAAa,WAAW;IACd,MAAM,CAAuB;IACpB,UAAU,CAAS;IACnB,SAAS,CAAS;IAClB,cAAc,CAAS;IACvB,GAAG,CAAS;IACZ,WAAW,CAAU;IACrB,MAAM,CAAkB;IAEzC,YAAY,MAAuB;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QACpC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,iCAAqB,CAAC;QAC3D,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC,cAAc,IAAI,sCAA0B,CAAC;QAC1E,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,oBAAoB,IAAI,0BAAc,CAAC;QACzD,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;IACxC,CAAC;IAEO,KAAK,CAAC,SAAS;QACrB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC;YAC3C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc;gBACtC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC;gBACjC,CAAC,CAAC,MAAM,IAAA,8BAAqB,EAAC,GAAG,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,8DAA8D;IAC9D,aAAa,CAAC,IAAgB;QAC5B,OAAO,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,cAAc,CAAC;IAC5C,CAAC;IAED,gDAAgD;IAChD,QAAQ,CAAC,KAAwB;QAC/B,OAAO,IAAA,mBAAU,EAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,iCAAiC;IACjC,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,oDAAoD;IACpD,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,IAAgB;QACxC,MAAM,IAAA,yBAAY,EAAC,MAAM,IAAI,CAAC,SAAS,EAAE,EAAE;YACzC,MAAM,EAAE,IAAI,CAAC,UAAU;YACvB,GAAG;YACH,IAAI;YACJ,oBAAoB,EAAE,IAAI,CAAC,GAAG;YAC9B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC;QACH,OAAO,GAAG,CAAC;IACb,CAAC;IAED,6CAA6C;IAC7C,KAAK,CAAC,QAAQ,CAAC,GAAW;QACxB,OAAO,IAAA,2BAAc,EAAC,MAAM,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IACtE,CAAC;IAED,+DAA+D;IAC/D,KAAK,CAAC,WAAW,CAAC,IAAc;QAC9B,OAAO,IAAA,sBAAa,EAAC,MAAM,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;IAED,iFAAiF;IACjF,KAAK,CAAC,mBAAmB,CAAC,OAAe;QACvC,OAAO,IAAA,+BAAmB,EAAC,MAAM,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC/F,CAAC;IAED,4DAA4D;IAC5D,OAAO;QACL,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IACzB,CAAC;CACF;AA1ED,kCA0EC"}

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

@@ -0,0 +1,16 @@
+import type { Logger } from '../../logging/logger';
+import type { S3Offloader } from './offloader';
+/** Options for {@link cleanUpS3Orphans}. */
+export interface OrphanCleanupOptions {
+    rng?: () => number;
+    maxAttempts?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Best-effort delete of S3 objects orphaned by a failed DynamoDB write. Retries
+ * transient errors with full-jitter backoff; on persistent failure or when S3
+ * reports keys it could not delete, it logs at `warn` (the lifecycle rule is the
+ * backstop) and never throws — the sole non-throwing path in the library.
+ */
+export declare function cleanUpS3Orphans(offloader: S3Offloader, keys: ReadonlyArray<string | undefined>, context: string, logger: Logger, options?: OrphanCleanupOptions): Promise<void>;
+//# sourceMappingURL=orphans.d.ts.map

package/dist/shared/codec/s3/orphans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphans.d.ts","sourceRoot":"","sources":["../../../../src/shared/codec/s3/orphans.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA6B/C,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAgBD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,WAAW,EACtB,IAAI,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,CAAC,EACvC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CA4Bf"}

package/dist/shared/codec/s3/orphans.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanUpS3Orphans = cleanUpS3Orphans;
+const backoff_1 = require("../../dynamodb/backoff");
+const DEFAULT_MAX_ATTEMPTS = 3;
+const BASE_DELAY_MS = 100;
+const RETRYABLE_S3_SIGNALS = [
+    'SlowDown',
+    'InternalError',
+    'ServiceUnavailable',
+    'RequestTimeout',
+    'ThrottlingException',
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'NetworkingError',
+];
+function isTransientS3Error(error) {
+    const fields = error;
+    const status = fields.$metadata?.httpStatusCode;
+    if (typeof status === 'number' && (status === 429 || (status >= 500 && status < 600)))
+        return true;
+    const signals = [fields.name, fields.code].filter((value) => typeof value === 'string');
+    return signals.some((signal) => RETRYABLE_S3_SIGNALS.some((retryable) => signal.includes(retryable)));
+}
+/**
+ * Wait out one backoff window, cancellable via `options.signal`. Resolves `true`
+ * when the signal aborts the wait (so the caller stops retrying) and `false`
+ * otherwise — never rejects, preserving the best-effort, non-throwing contract.
+ */
+async function backoffSleep(delayMs, options) {
+    try {
+        await (0, backoff_1.sleep)((0, backoff_1.fullJitter)(delayMs, options.rng), options.signal);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Best-effort delete of S3 objects orphaned by a failed DynamoDB write. Retries
+ * transient errors with full-jitter backoff; on persistent failure or when S3
+ * reports keys it could not delete, it logs at `warn` (the lifecycle rule is the
+ * backstop) and never throws — the sole non-throwing path in the library.
+ */
+async function cleanUpS3Orphans(offloader, keys, context, logger, options = {}) {
+    const orphans = keys.filter((key) => typeof key === 'string' && key.length > 0);
+    if (orphans.length === 0)
+        return;
+    const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    let delay = BASE_DELAY_MS;
+    let lastError = new Error('S3 orphan cleanup did not run');
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const failed = await offloader.deleteBatch(orphans);
+            if (failed.length === 0)
+                return;
+            logger.warn(`Some orphaned S3 objects could not be deleted after ${context}; lifecycle rule will sweep`, { failedCount: failed.length });
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= maxAttempts || !isTransientS3Error(lastError))
+                break;
+            if (await backoffSleep(delay, options))
+                break;
+            delay = (0, backoff_1.nextBackoffDelay)(delay);
+        }
+    }
+    logger.warn(`Failed to clean up orphaned S3 objects after ${context}; lifecycle rule will sweep`, {
+        message: lastError.message,
+    });
+}
+//# sourceMappingURL=orphans.js.map

package/dist/shared/codec/s3/orphans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphans.js","sourceRoot":"","sources":["../../../../src/shared/codec/s3/orphans.ts"],"names":[],"mappings":"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"}