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

package/dist/shared/codec/codec.js

@@ -1,44 +1,441 @@
 "use strict";
+/**
+ * Hides how a value becomes a stored payload and back.
+ *
+ * A value is serialized by the configured serde, gzipped when that pays, and
+ * kept inline in its row or offloaded to S3 under a key its row can be traced
+ * from, behind a versioned descriptor the row stores. Reading reverses that,
+ * and a failure that means the payload can never be read again — a corrupt
+ * body, a missing object, a descriptor no reader understands — is told apart
+ * here from one a retry might cure.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PayloadLocation = void 0;
-exports.encodePayload = encodePayload;
+exports.DESCRIPTOR_SCHEMA_VERSION = exports.PayloadLocation = exports.MAX_INLINE_PAYLOAD_BYTES = void 0;
+exports.codecDepsOf = codecDepsOf;
+exports.readPayloadBytes = readPayloadBytes;
+exports.loadPayloadValue = loadPayloadValue;
 exports.decodePayload = decodePayload;
+exports.encodePayload = encodePayload;
+exports.collectS3Keys = collectS3Keys;
+exports.isMissingObjectError = isMissingObjectError;
+exports.isPermanentPayloadLoss = isPermanentPayloadLoss;
+const base_error_1 = require("../errors/base-error");
+const classify_1 = require("../errors/classify");
+const error_code_1 = require("../errors/error-code");
+const errors_1 = require("../errors/errors");
+const truncate_1 = require("../logging/truncate");
 const compression_1 = require("./compression");
+const json_serde_1 = require("./json-serde");
+/**
+ * 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,
+ * attribute names and descriptor fields. Exceeding it fails before the write
+ * with a typed error instead of a raw `ValidationException` after it.
+ */
+exports.MAX_INLINE_PAYLOAD_BYTES = 400 * 1024 - 8 * 1024;
 /** Where an encoded payload lives. */
 var PayloadLocation;
 (function (PayloadLocation) {
     PayloadLocation["INLINE"] = "INLINE";
     PayloadLocation["S3"] = "S3";
 })(PayloadLocation || (exports.PayloadLocation = PayloadLocation = {}));
-function requireOffloader(deps) {
+/**
+ * Version of the persisted descriptor shape. Absent on rows written before it
+ * existed, which read as version 1; a higher value marks a row written by a
+ * newer library and is refused rather than misread.
+ */
+exports.DESCRIPTOR_SCHEMA_VERSION = 1;
+/**
+ * The codec collaborators an adapter context carries, with a call's signal.
+ *
+ * Accepts: `source` — the adapter's serde, compression and offloader.
+ * `signal` — the call's cancellation, carried into the S3 request a payload
+ * needs.
+ *
+ * Returns: the collaborators the codec takes.
+ *
+ * Throws: nothing.
+ */
+function codecDepsOf(source, signal) {
+    return {
+        serde: source.serde,
+        compression: source.compression,
+        offloader: source.offloader,
+        signal,
+    };
+}
+function configuredOffloader(deps) {
     if (!deps.offloader) {
-        throw new Error('Cannot decode an S3 payload without an offloader');
+        throw (0, errors_1.validationError)("this row's payload is offloaded to S3 but the adapter has no `s3` configuration; " +
+            'configure the bucket the writer used', 's3');
     }
     return deps.offloader;
 }
 /**
- * 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.
+ * Refuse a descriptor this version cannot read: one that is not an object at
+ * all, one whose schema is newer, or one whose location is unknown. A row can
+ * hold anything its writer stored, and reading `.schemaVersion` off `null`
+ * raised a raw `TypeError` out of a public method.
+ *
+ * The newer schema is the one of the three that is **not** the payload's own
+ * fault, and it is coded apart from the other two for that reason. A descriptor
+ * that is not an object, and one naming a location no release ever wrote at
+ * this schema, condemn themselves: no upgrade and no configuration makes those
+ * bytes readable, so a reader may write them off. A forward `schemaVersion`
+ * says the opposite — the payload is intact and the release that wrote it reads
+ * it perfectly — so it is `FORMAT_UNSUPPORTED`, exactly as a forward `v` on the
+ * row around it is, naming the attribute that carried the version. Sharing the
+ * `descriptor` field put it in the permanent-loss bucket, where history's
+ * default `skip` silently dropped during a rollback or a canary the very turns
+ * the store and the saver refused to serve.
+ *
+ * Both of the values these messages quote come off the row, so both go through
+ * `truncateForLog`. The version is declared a number and the comparison
+ * coerces, so a row carrying a thousand digits as a string passes it and
+ * reaches the message; the location is quoted as JSON, which a row can make
+ * any length at all.
+ */
+function assertReadableDescriptor(descriptor) {
+    if (descriptor === null || typeof descriptor !== 'object') {
+        throw (0, errors_1.validationError)(`payload descriptor is ${descriptor === null ? 'null' : typeof descriptor}, not a descriptor ` +
+            'this library wrote', 'descriptor');
+    }
+    const version = descriptor.schemaVersion ?? exports.DESCRIPTOR_SCHEMA_VERSION;
+    if (version > exports.DESCRIPTOR_SCHEMA_VERSION) {
+        // Declared a number, read off a row, and the comparison coerces a string.
+        const written = (0, truncate_1.truncateForLog)(String(version));
+        throw new base_error_1.DynamoDBLangGraphError(`this payload was written in descriptor schema version ${written}; this version of the ` +
+            `library reads up to ${exports.DESCRIPTOR_SCHEMA_VERSION} — upgrade to read it`, error_code_1.ErrorCode.FORMAT_UNSUPPORTED, { field: 'schemaVersion' });
+    }
+    const locations = Object.values(PayloadLocation);
+    if (!locations.includes(descriptor.location)) {
+        // The location is whatever the row holds, and the row is what this refuses.
+        const location = (0, truncate_1.truncateForLog)(String(JSON.stringify(descriptor.location)));
+        throw (0, errors_1.validationError)(`payload descriptor has an unknown location ${location}`, 'descriptor');
+    }
+}
+/**
+ * The payload bytes a descriptor stands for: downloaded when offloaded, then
+ * decompressed. Infrastructure only, no deserialization — a caller that needs
+ * to tell a transport or permission failure from bad data does this step and
+ * {@link loadPayloadValue} separately (see
+ * `src/history/actions/get-messages.ts`).
+ *
+ * Accepts: `descriptor` — as written by {@link encodePayload}; a
+ * `schemaVersion` above this release's, or a `location` it does not know, is
+ * refused rather than guessed at. `deps.offloader` — required only for an `S3`
+ * descriptor. `scope` — the row's own leading key parts (`[threadId]`,
+ * `[...namespace, key]`, `[sessionId]`); `[]` degrades the check to the
+ * configured prefix. `deps.signal` — cancels the download of an offloaded
+ * payload, request and all; an inline one reads no bytes and ignores it.
+ *
+ * Returns: the decoded bytes.
+ *
+ * Throws: `VALIDATION` naming `descriptor` for a shape no reader could
+ * make sense of and `s3` for an offloaded row with no offloader configured;
+ * `FORMAT_UNSUPPORTED` naming `schemaVersion` for a payload a newer release
+ * wrote, which a newer reader reads fine; `VALIDATION` naming `s3Key` when
+ * the key lies outside `scope`; `ABORTED` when the signal fires during the
+ * download; `S3_OFFLOAD_FAILED` from the download; `COMPRESSION_LIMIT` or
+ * `PAYLOAD_CORRUPT` from decompression.
+ *
+ * Guarantees: an offloaded object is downloaded only when its key lies under
+ * the path `scope` produces, so a row can never point this adapter at an
+ * object it does not own.
+ */
+async function readPayloadBytes(descriptor, deps, scope) {
+    assertReadableDescriptor(descriptor);
+    let raw;
+    if (descriptor.location === PayloadLocation.S3) {
+        const offloader = configuredOffloader(deps);
+        offloader.assertOwnedKey(descriptor.s3Key, scope);
+        raw = await offloader.download(descriptor.s3Key, deps.signal);
+    }
+    else {
+        raw = descriptor.bytes;
+    }
+    return (0, compression_1.decompress)(raw, descriptor.compressed, deps.compression?.maxDecompressedBytes);
+}
+/**
+ * The value stored bytes hold, with a serde that refuses them branded rather
+ * than left bare.
+ *
+ * Accepts: `serdeType` — the row's own, handed to the serde unchanged, and the
+ * declared form {@link bytesHoldDeclaredForm} checks the bytes against.
+ * `bytes` — what {@link readPayloadBytes} returned. `deps.serde` — the
+ * serializer the adapter was configured with, which may be the caller's.
+ *
+ * Returns: whatever the serde reconstructs, typed as the caller declares.
+ *
+ * Throws: the serde's own error whenever it is already one of this library's,
+ * so `PAYLOAD_CORRUPT` from `JSON_SERDE` stays exactly what it was — as does
+ * its refusal of a `serdeType` it has no grammar for, which it brands the same
+ * `VALIDATION` naming `serde` that the classifier below reaches for on the
+ * identical row under any other serde; `PAYLOAD_CORRUPT` when the bytes are no
+ * longer the form the row declares, on whatever serde raised it; anything else
+ * as a `VALIDATION` error naming `serde`, carrying the refusal as `cause`.
+ *
+ * Guarantees: no error leaves a decode unbranded, and which serde the adapter
+ * was configured with never decides *which* brand. A rotted row read through
+ * `JSON_SERDE` reported `PAYLOAD_CORRUPT` while the identical row read through
+ * the checkpointer's own default reported the refusal below, so a caller
+ * quarantining on `PAYLOAD_CORRUPT` never matched and `history.getMessages`
+ * lost a whole conversation where it promises one dropped message. A row
+ * declaring a form neither serde writes ran the same divergence the other way,
+ * and reached further: `JSON_SERDE` ignored the declared type, so its own
+ * `JSON.parse` failure arrived here already branded and the classifier was
+ * never consulted. The serializer honours the declared form now, which is what
+ * keeps this the one place the distinction is drawn.
+ *
+ * The refusal is what remains once the bytes are known to be intact: the
+ * serializer would not reconstruct the value they name. A stored `lc`
+ * constructor record naming a class outside LangChain's allow-list is refused
+ * by `load()` with a plain `Error`, which a public boundary could only rebrand
+ * as an `UNEXPECTED_ERROR` — reporting a row's own content to the caller as an AWS
+ * failure. It is deliberately *not* classified as payload loss, for
+ * `assertKeyInScope`'s reason rather than `PAYLOAD_CORRUPT`'s: the bytes are
+ * undamaged and parse, and which classes revive is a property of **this**
+ * reader — the serde it was given, and what that serde's allow-list carries —
+ * not of the payload. A refusal that says only "this reader may not
+ * reconstruct that" is a misconfigured serde or a planted row, both of which an
+ * operator must see; writing it off would let `history.getMessages` answer with
+ * a silently shorter conversation for the one row shape most worth noticing.
+ */
+async function loadPayloadValue(serdeType, bytes, deps) {
+    try {
+        return await deps.serde.loadsTyped(serdeType, bytes);
+    }
+    catch (error) {
+        const refusal = (0, base_error_1.toError)(error);
+        if ((0, base_error_1.isDynamoDBLangGraphError)(refusal))
+            throw refusal;
+        if (!(0, json_serde_1.bytesHoldDeclaredForm)(serdeType, bytes)) {
+            throw new base_error_1.DynamoDBLangGraphError('the stored payload is no longer the form this row declares, so no serde could decode ' +
+                'it; the refusal that proved it is attached as `cause`', error_code_1.ErrorCode.PAYLOAD_CORRUPT, {}, refusal);
+        }
+        throw (0, errors_1.validationError)('the configured serde refused the payload stored in this row: the bytes parse, but the ' +
+            'serializer would not reconstruct the value they name — a stored `lc` constructor record ' +
+            'naming a class outside its allow-list reads this way, as does a serde that did not ' +
+            'write these bytes. The refusal itself is attached as `cause`', 'serde', refusal);
+    }
+}
+/**
+ * The value a descriptor stands for: {@link readPayloadBytes} followed by
+ * {@link loadPayloadValue}.
+ *
+ * Accepts: as {@link readPayloadBytes}; `scope` has the same meaning.
+ *
+ * Returns: whatever the serde reconstructs, typed as the caller declares.
+ *
+ * Throws: everything {@link readPayloadBytes} throws, plus everything
+ * {@link loadPayloadValue} throws for bytes the serde will not accept —
+ * `PAYLOAD_CORRUPT` for bytes that are no longer the form the row declares,
+ * whichever serde is configured, `VALIDATION` naming `serde` for a refusal
+ * of bytes that are still intact.
+ *
+ * Guarantees: the bytes are read first, in a statement of their own. Passing
+ * `descriptor.serdeType` and the awaited read as two arguments to one call read
+ * the property *before* the guard ran, since arguments evaluate left to right —
+ * so a row whose payload is `null` raised a bare `TypeError` carrying no code,
+ * which a public boundary can only rebrand as an `UNEXPECTED_ERROR`. Every read
+ * path now answers such a row with the `VALIDATION` error naming `descriptor` that
+ * the history adapter, which reads its bytes separately, already produced.
+ */
+async function decodePayload(descriptor, deps, scope) {
+    const bytes = await readPayloadBytes(descriptor, deps, scope);
+    return loadPayloadValue(descriptor.serdeType, bytes, deps);
+}
+/**
+ * Reject bytes that cannot be stored inline. Without an offloader the only
+ * alternative is a raw `ValidationException` from DynamoDB after the network
+ * round trip, which names neither the cause nor the remedy.
+ */
+function assertInlinePayloadFits(bytes, deps) {
+    if (bytes.length <= exports.MAX_INLINE_PAYLOAD_BYTES)
+        return;
+    const hint = deps.compression?.enabled
+        ? ''
+        : ', or enable compression if the data compresses well';
+    throw (0, errors_1.validationError)(`payload of ${bytes.length} bytes exceeds the ${exports.MAX_INLINE_PAYLOAD_BYTES}-byte inline limit ` +
+        `(DynamoDB items are capped at 400 KB); configure s3 offloading${hint}`, 'payload');
+}
+/**
+ * Reject a value the serde turned into no bytes at all. Zero bytes is not a
+ * small payload: it is not a document in any format a reader can parse, so the
+ * row is written happily and every later read of it fails. Checked before
+ * compression, so an inline and an offloaded payload are refused identically
+ * and nothing is uploaded for a payload no reader could ever use.
+ *
+ * What reaches it under the default `JsonPlusSerializer` is a value that is
+ * *itself* a function or a symbol. A bare `undefined` is not one of them — it
+ * encodes to a 27-byte marker — and neither is a function or symbol nested in
+ * an object or an array, which is dropped from the document instead of
+ * emptying it, silently and out of this check's sight.
+ *
+ * The rule binds every serde, not only the defaults. A `serde` whose encoding
+ * of some legitimate value is genuinely empty — a message format whose empty
+ * message is zero bytes — cannot store that value through this package, and
+ * would have to give it a byte of its own.
+ */
+function assertSerialisedToBytes(raw) {
+    if (raw.length > 0)
+        return;
+    throw (0, errors_1.validationError)('value serialises to zero bytes, which no reader can parse back: a function, a symbol ' +
+        'or any value the configured serde drops encodes to nothing. Store a value the serde ' +
+        'can represent, or configure one that refuses it.', 'value');
+}
+/**
+ * The descriptor recording how to read `value` back: serialized, compressed if
+ * configured, and offloaded to S3 if large enough.
+ *
+ * Accepts: `value` — anything the serde can represent as at least one byte;
+ * what it cannot represent is the serde's own error, and what it represents as
+ * nothing is refused here (see {@link assertSerialisedToBytes}), whichever
+ * serde is configured. `deps.compression` — absent or `enabled: false` stores the
+ * serialized bytes as they are. `deps.offloader` — absent stores every payload
+ * inline. `deps.signal` — cancels the upload of an offloaded payload; an
+ * inline one is never sent anywhere and ignores it. `options` — the row's
+ * identity, the write's object id and the row's DynamoDB key (see
+ * {@link EncodeOptions}).
+ *
+ * Returns: an `S3` descriptor when an offloader is configured and
+ * `shouldOffload` accepts the compressed size, otherwise an `INLINE`
+ * descriptor carrying the bytes. Both record `serdeType` and `compressed`, so
+ * neither is ever inferred from the bytes on read.
+ *
+ * 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
+ * {@link assertSerialisedToBytes}) — and is raised for an offloaded payload
+ * and an inline one alike, before either is stored.
  */
 async function encodePayload(value, deps, options) {
     const [serdeType, raw] = await deps.serde.dumpsTyped(value);
+    assertSerialisedToBytes(raw);
     const { bytes, compressed } = deps.compression
         ? await (0, compression_1.compress)(raw, deps.compression)
         : { bytes: raw, compressed: false };
+    // `writeId` is set here rather than at each call site so both descriptor
+    // kinds and every adapter inherit one identity from one statement. It does
+    // not raise `DESCRIPTOR_SCHEMA_VERSION`: the version is refused by a reader
+    // that is older than it, and this field is additive and ignorable, so
+    // announcing it would cost readability of these rows for nothing.
+    const base = {
+        schemaVersion: exports.DESCRIPTOR_SCHEMA_VERSION,
+        serdeType,
+        compressed,
+        writeId: options.objectId,
+    };
     if (deps.offloader && deps.offloader.shouldOffload(bytes)) {
-        const s3Key = deps.offloader.buildKey(options.keyParts);
-        await deps.offloader.upload(s3Key, bytes);
-        return { location: PayloadLocation.S3, serdeType, compressed, s3Key };
+        const s3Key = deps.offloader.buildKey(options.keyParts, options.objectId);
+        await deps.offloader.upload(s3Key, bytes, options.row, deps.signal);
+        return { ...base, location: PayloadLocation.S3, s3Key };
     }
-    return { location: PayloadLocation.INLINE, serdeType, compressed, bytes };
+    if (!deps.offloader)
+        assertInlinePayloadFits(bytes, deps);
+    return { ...base, location: PayloadLocation.INLINE, 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);
+/**
+ * The S3 keys of whichever descriptors are offloaded.
+ *
+ * Accepts: `descriptors` — any mix of inline and offloaded, including a
+ * projection that carries only `location` and `s3Key`, and including none. An
+ * offloaded descriptor missing its key is skipped rather than deleted blindly,
+ * and so is an entry that is not a descriptor at all: several callers read
+ * these straight off a row, and a row this library did not write can hold
+ * `null` where the descriptor belongs, or omit the attribute entirely. Widening
+ * the parameter rather than making each caller filter is what lets the `Throws`
+ * clause below hold for every caller instead of only the careful ones.
+ *
+ * Returns: the keys, in the order given; an inline payload contributes none,
+ * and neither does an absent one.
+ *
+ * Throws: nothing — this feeds cleanup, which must not fail the operation it
+ * follows.
+ */
+function collectS3Keys(descriptors) {
+    const keys = [];
+    for (const descriptor of descriptors) {
+        if (descriptor?.location === PayloadLocation.S3 && descriptor.s3Key !== undefined) {
+            keys.push(descriptor.s3Key);
+        }
+    }
+    return keys;
+}
+/**
+ * True when an offloaded object no longer exists.
+ *
+ * Accepts: `error` — any error; only `S3_OFFLOAD_FAILED` carrying a `NoSuchKey`
+ * cause matches. An error with no `cause`, or one whose cause names another
+ * S3 failure, is not a missing object. Anything else a `throw` can produce —
+ * `null`, `undefined`, a primitive — carries no code and is not one either.
+ *
+ * Returns: whether the object is gone — a lifecycle sweep removed it, or a
+ * competing overwrite deleted it between a row read and the download.
+ *
+ * Throws: **nothing**, for any value. A caught value that cannot carry a
+ * property answers `false`, as `isDynamoDBLangGraphError` does, rather than
+ * raising a `TypeError` inside the `catch` that is reporting the download
+ * failure this test exists to classify.
+ */
+function isMissingObjectError(error) {
+    return ((0, base_error_1.hasErrorCode)(error, error_code_1.ErrorCode.S3_OFFLOAD_FAILED) &&
+        error.cause !== undefined &&
+        (0, classify_1.isMissingObject)(error.cause));
+}
+/**
+ * True when a row's payload descriptor is not one *any* reader could make sense
+ * of: it is absent, it is not an object, or it names a location no release of
+ * this library ever wrote at the schema it declares. The row condemns its own
+ * payload — no retry and no configuration change makes those bytes readable,
+ * and no other reader would fare better.
+ *
+ * Two refusals from the same guard are deliberately *not* matched here, both
+ * because the sentence above would be false of them. A `VALIDATION` error naming
+ * `s3Key` says the reader may not follow the key, not that the payload is
+ * unreadable (see `assertKeyInScope`). A `FORMAT_UNSUPPORTED` naming
+ * `schemaVersion` says the payload was written by a newer release — which reads
+ * it perfectly — so it is the one descriptor refusal a newer reader *does* fare
+ * better on, and writing it off silently dropped turns during a rollback or a
+ * canary (see `assertReadableDescriptor`).
+ */
+function isUnreadableDescriptor(error) {
+    return (0, base_error_1.hasErrorCode)(error, error_code_1.ErrorCode.VALIDATION) && error.context.field === 'descriptor';
+}
+/**
+ * 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,
+ * permissions).
+ *
+ * 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.
+ *
+ * Returns: whether a caller should report rather than retry.
+ *
+ * Throws: **nothing**, for any value a `throw` can produce. One that cannot
+ * carry a code is not permanent loss, which is the same answer an uncoded
+ * `Error` gets.
+ */
+function isPermanentPayloadLoss(error) {
+    return ((0, base_error_1.hasErrorCode)(error, error_code_1.ErrorCode.COMPRESSION_LIMIT) ||
+        (0, base_error_1.hasErrorCode)(error, error_code_1.ErrorCode.PAYLOAD_CORRUPT) ||
+        isMissingObjectError(error) ||
+        isUnreadableDescriptor(error));
 }
-//# sourceMappingURL=codec.js.map

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

@@ -1,3 +1,18 @@
+/**
+ * Hides whether a stored payload's bytes are gzipped.
+ *
+ * When gzip is attempted, when its output is not worth keeping, and how a read
+ * refuses a gzip bomb or a stream that is not gzip are decided here. A caller
+ * carries only the flag this module returns, recorded beside the bytes, so
+ * compression is never guessed from the bytes and the thresholds can change
+ * without touching the codec that stores them.
+ */
+/** Default minimum payload size before gzip compression is attempted. */
+export declare const DEFAULT_COMPRESSION_MIN_BYTES = 1024;
+/** Default gzip compression level (balanced speed/ratio). */
+export declare const DEFAULT_COMPRESSION_LEVEL = 6;
+/** Default gzip-bomb guard: maximum decompressed output (50 MiB). */
+export declare const DEFAULT_MAX_DECOMPRESSED_BYTES: number;
 /** Configuration for payload compression. */
 export interface CompressionConfig {
     enabled: boolean;
@@ -11,15 +26,36 @@ export interface CompressionResult {
     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.
+ * The bytes to store for `data`, gzipped when that is worth doing.
+ *
+ * Accepts: `data` — any length, including empty. `config.enabled` — `false`
+ * returns the input untouched. `config.minSizeBytes` — the size below which
+ * gzip is not attempted, default {@link DEFAULT_COMPRESSION_MIN_BYTES}.
+ * `config.level` — zlib level 0–9, default {@link DEFAULT_COMPRESSION_LEVEL}.
+ * `config.maxDecompressedBytes` is read on the way back, not here.
+ *
+ * Returns: `compressed: true` only when gzip beat the input by more than 10%;
+ * otherwise the input bytes and `compressed: false`. The flag is recorded in
+ * the payload descriptor, so compression is never inferred from the bytes on
+ * read.
+ *
+ * Throws: whatever `zlib.gzip` rejects with.
  */
 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).
+ * The payload bytes `data` stands for, gunzipped when the row says so.
+ *
+ * Accepts: `data` — the bytes as stored. `compressed` — the descriptor's own
+ * flag; `false` returns `data` unchanged and inspects nothing. `maxBytes` — the
+ * decompressed-output cap, default {@link DEFAULT_MAX_DECOMPRESSED_BYTES}; a
+ * reader that configures no compression uses that default whatever the writer
+ * used.
+ *
+ * Returns: the decoded bytes.
+ *
+ * Throws: `COMPRESSION_LIMIT` when the output would exceed `maxBytes`, and
+ * `PAYLOAD_CORRUPT` when `compressed` is true but the bytes are not gzip. Both
+ * are permanent for that payload ({@link isPermanentPayloadLoss}), so a caller
+ * reports rather than retries.
  */
 export declare function decompress(data: Uint8Array, compressed: boolean, maxBytes?: number): Promise<Uint8Array>;
-//# sourceMappingURL=compression.d.ts.map

package/dist/shared/codec/compression.js

@@ -1,38 +1,79 @@
 "use strict";
+/**
+ * Hides whether a stored payload's bytes are gzipped.
+ *
+ * When gzip is attempted, when its output is not worth keeping, and how a read
+ * refuses a gzip bomb or a stream that is not gzip are decided here. A caller
+ * carries only the flag this module returns, recorded beside the bytes, so
+ * compression is never guessed from the bytes and the thresholds can change
+ * without touching the codec that stores them.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_DECOMPRESSED_BYTES = exports.DEFAULT_COMPRESSION_LEVEL = exports.DEFAULT_COMPRESSION_MIN_BYTES = void 0;
 exports.compress = compress;
 exports.decompress = decompress;
 const node_util_1 = require("node:util");
 const node_zlib_1 = require("node:zlib");
-const 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;
+/** Default minimum payload size before gzip compression is attempted. */
+exports.DEFAULT_COMPRESSION_MIN_BYTES = 1024;
+/** Default gzip compression level (balanced speed/ratio). */
+exports.DEFAULT_COMPRESSION_LEVEL = 6;
+/** Default gzip-bomb guard: maximum decompressed output (50 MiB). */
+exports.DEFAULT_MAX_DECOMPRESSED_BYTES = 50 * 1024 * 1024;
 /**
- * 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.
+ * The bytes to store for `data`, gzipped when that is worth doing.
+ *
+ * Accepts: `data` — any length, including empty. `config.enabled` — `false`
+ * returns the input untouched. `config.minSizeBytes` — the size below which
+ * gzip is not attempted, default {@link DEFAULT_COMPRESSION_MIN_BYTES}.
+ * `config.level` — zlib level 0–9, default {@link DEFAULT_COMPRESSION_LEVEL}.
+ * `config.maxDecompressedBytes` is read on the way back, not here.
+ *
+ * Returns: `compressed: true` only when gzip beat the input by more than 10%;
+ * otherwise the input bytes and `compressed: false`. The flag is recorded in
+ * the payload descriptor, so compression is never inferred from the bytes on
+ * read.
+ *
+ * Throws: whatever `zlib.gzip` rejects with.
  */
 async function compress(data, config) {
-    const minSize = config.minSizeBytes ?? constants_1.DEFAULT_COMPRESSION_MIN_BYTES;
+    const minSize = config.minSizeBytes ?? exports.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 level = config.level ?? exports.DEFAULT_COMPRESSION_LEVEL;
     const gzipped = new Uint8Array(await gzipAsync(data, { level }));
     if (gzipped.length >= data.length * COMPRESSION_GAIN_RATIO) {
         return { bytes: data, compressed: false };
     }
     return { bytes: gzipped, compressed: true };
 }
+/** The error a payload raises when its bytes are not the form its row declares. */
+function corruptPayload(cause) {
+    return new base_error_1.DynamoDBLangGraphError('the stored payload is marked compressed but is not valid gzip, so it cannot be decoded', error_code_1.ErrorCode.PAYLOAD_CORRUPT, {}, cause);
+}
 /**
- * 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).
+ * The payload bytes `data` stands for, gunzipped when the row says so.
+ *
+ * Accepts: `data` — the bytes as stored. `compressed` — the descriptor's own
+ * flag; `false` returns `data` unchanged and inspects nothing. `maxBytes` — the
+ * decompressed-output cap, default {@link DEFAULT_MAX_DECOMPRESSED_BYTES}; a
+ * reader that configures no compression uses that default whatever the writer
+ * used.
+ *
+ * Returns: the decoded bytes.
+ *
+ * Throws: `COMPRESSION_LIMIT` when the output would exceed `maxBytes`, and
+ * `PAYLOAD_CORRUPT` when `compressed` is true but the bytes are not gzip. Both
+ * are permanent for that payload ({@link isPermanentPayloadLoss}), so a caller
+ * reports rather than retries.
  */
-async function decompress(data, compressed, maxBytes = constants_1.DEFAULT_MAX_DECOMPRESSED_BYTES) {
+async function decompress(data, compressed, maxBytes = exports.DEFAULT_MAX_DECOMPRESSED_BYTES) {
     if (!compressed)
         return data;
     try {
@@ -41,9 +82,8 @@ async function decompress(data, compressed, maxBytes = constants_1.DEFAULT_MAX_D
     catch (error) {
         const err = error;
         if (err.code === 'ERR_BUFFER_TOO_LARGE') {
-            throw new base_error_1.DynamoDbLangGraphError(`Refusing to decompress: output would exceed ${maxBytes} bytes`, error_code_1.ErrorCode.COMPRESSION_LIMIT, {}, error);
+            throw new base_error_1.DynamoDBLangGraphError(`Refusing to decompress: output would exceed ${maxBytes} bytes`, error_code_1.ErrorCode.COMPRESSION_LIMIT, {}, error);
         }
-        throw error;
+        throw corruptPayload(error);
     }
 }
-//# sourceMappingURL=compression.js.map