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

package/dist/cjs/shared/dynamodb/table-schema.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Hides the conventions every row of the shared table follows, whichever
+ * adapter wrote it.
+ *
+ * The three adapters share one table (record 2), so a few things are decided
+ * once for all of them: the two key attributes every row has, the format
+ * version every row is stamped with and refused above (record 7), the `ttl`
+ * attribute that makes a row absent before DynamoDB's sweep removes it, and the
+ * order the server gives string keys. Which segments a feature's keys carry is
+ * that feature's `rows` module's decision; that they are written into these
+ * attributes and read back in this order is this module's.
+ */
+import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
+import type { AttributeMap } from './client.js';
+/** The attribute every row is partitioned by. */
+export declare const PARTITION_KEY_ATTRIBUTE = "PK";
+/** The attribute every row is sorted by within its partition. */
+export declare const SORT_KEY_ATTRIBUTE = "SK";
+/**
+ * Byte caps on caller-supplied identifiers, measured as UTF-8. DynamoDB caps a
+ * partition key at 2048 bytes and a sort key at 1024; S3 caps an object key at
+ * 1024. These leave room for the adapter prefixes and separators that compose
+ * the stored keys, so a value that passes validation fails as a typed error
+ * here rather than as a raw AWS ValidationException on the write.
+ *
+ * Partition-key identifiers: `thread_id` and `sessionId`.
+ */
+export declare const MAX_PARTITION_ID_BYTES = 1024;
+/**
+ * Sort-key segments other than the checkpoint namespace and a pending-write
+ * channel: `checkpoint_id`, `taskId`, a store namespace element and a store
+ * `key`.
+ */
+export declare const MAX_KEY_SEGMENT_BYTES = 256;
+/**
+ * A pending-write channel's own cap. Every other segment is one identifier,
+ * but LangGraph names the channel behind a static fan-in after every source
+ * node — `join:<a>+<b>+…:<end>` — so a channel is as long as a graph's node
+ * names together, and nine sources with ordinary names pass 256 bytes. The
+ * channel is the last segment of the WRITE sort key, so DynamoDB's cap on the
+ * whole key is the bound that matters, and the composed-key check enforces it
+ * against the namespace, checkpoint id and task id the channel sits behind.
+ */
+export declare const MAX_WRITE_CHANNEL_BYTES = 1024;
+/**
+ * The checkpoint namespace's own cap. LangGraph names a subgraph's namespace
+ * after its parent's, a separator, the node's name and a 36-character task id
+ * (`${parent}|${node}:${taskId}`), so each level of nesting adds roughly forty
+ * bytes plus the node name; 256 bytes stopped a graph at its fifth or sixth
+ * level. Twice that keeps the rows a namespace composes inside DynamoDB's
+ * sort-key cap, which the composed-key checks enforce either way.
+ */
+export declare const MAX_CHECKPOINT_NS_BYTES = 512;
+/**
+ * DynamoDB cap on a whole sort key; composed keys are checked against it too.
+ *
+ * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html
+ */
+export declare const MAX_SORT_KEY_BYTES = 1024;
+/**
+ * The separator between the segments of every key this package composes. No
+ * caller-supplied identifier may contain it (the parsers refuse it), which is
+ * what lets a key be read back into its parts and matched by prefix (record 2).
+ */
+export declare const KEY_SEPARATOR = "#";
+/**
+ * The tag each adapter's partition keys open with. The three differ in their
+ * first character, so no two adapters' partitions can collide on a shared
+ * table, whatever identifiers their callers reuse (record 2).
+ */
+export declare const ADAPTER_TAGS: {
+    readonly checkpointer: 'CHKPT';
+    readonly store: 'STORE';
+    readonly history: 'HIST';
+};
+/** A row's primary key, as a `Key` document and as the key half of an item. */
+export interface RowKey {
+    PK: string;
+    SK: string;
+}
+/**
+ * The key of a row already in hand.
+ *
+ * Accepts: `row` — an item read from, or about to be written to, the table.
+ *
+ * Returns: its `PK` and `SK`, and nothing else, so it can be sent as a `Key`
+ * without the rest of the item.
+ *
+ * Throws: nothing.
+ */
+export declare function rowKeyOf(row: AttributeMap): RowKey;
+/** The only attribute this module reads: a row's own format version. */
+export interface VersionedRow {
+    v?: number;
+}
+/**
+ * The format version this package stamps on every row it writes.
+ *
+ * Before it existed, "written by an older version" was inferred from a missing
+ * attribute — `rev`, `occurrence`, `writeGroup`, `storedChannels`. That
+ * inference is unreadable to a maintainer and it is not even expressible: a
+ * lookup cannot tell an attribute that is *absent* from one that is *present
+ * and undefined*, which reversed first-write-wins for pending writes across an
+ * upgrade. A row states its own version instead.
+ */
+export declare const ROW_FORMAT_VERSION = 1;
+/** The highest version this package knows how to read. */
+export declare const SUPPORTED_ROW_FORMAT_VERSION = 1;
+/**
+ * A row's format version.
+ *
+ * Accepts: `row` — any row. One carrying no numeric `v` predates the attribute.
+ *
+ * Returns: the stamped version, or `0` for a row without one — the version
+ * whose rules applied when it was written.
+ *
+ * Throws: nothing.
+ */
+export declare function rowVersionOf(row: VersionedRow): number;
+/**
+ * Refuse a row written by a newer version of this package.
+ *
+ * Accepts: `row` — any row; one at or below
+ * {@link SUPPORTED_ROW_FORMAT_VERSION} is accepted, which includes every row
+ * written before the attribute existed. `what` — the row kind, named in the
+ * message.
+ *
+ * Returns: nothing: `row` is kept under its declared type, and this checks
+ * it.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` naming the field `v`. Guessing at a shape this
+ * version does not know is how a reader returns a checkpoint with silently
+ * missing state, so the caller is told to upgrade instead.
+ */
+export declare function assertReadableRow(row: VersionedRow, what: string): void;
+/**
+ * Whether a row has reached its TTL.
+ *
+ * Accepts: `row` — any row; one without a `ttl` attribute never expires.
+ * `nowSeconds` — the current epoch **second**, the unit the attribute uses.
+ *
+ * Returns: true when `ttl <= nowSeconds`, so the expiry instant itself counts
+ * as expired.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: a caller that applies this hides an expired row even while
+ * DynamoDB's own sweep lags, which AWS documents as typically within a few days of the
+ * `ttl`, with no fixed bound
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html).
+ */
+export declare function isExpiredRow(row: {
+    ttl?: number;
+}, nowSeconds: number): boolean;
+/**
+ * The same query with expired rows filtered out server-side.
+ *
+ * Accepts: `params` — a Query or Scan input, with or without a
+ * `FilterExpression`; an existing one is ANDed rather than replaced.
+ * `nowSeconds` — the epoch second to compare against.
+ *
+ * Returns: a copy carrying the added filter and the `#ttl` / `:now` aliases. No
+ * other call site in this package uses those two names, so the merge cannot
+ * shadow a caller's own alias.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: this trims transfer only. It never replaces the in-process
+ * {@link isExpiredRow} check, because the query is built and its rows are read
+ * at two different instants, and DynamoDB applies a filter *after* `Limit`.
+ */
+export declare function withoutExpired<T extends QueryCommandInput | ScanCommandInput>(params: T, nowSeconds: number): T;
+/**
+ * Order two DynamoDB string sort keys the way the server orders them.
+ *
+ * DynamoDB compares a string key by the bytes of its UTF-8 encoding.
+ * JavaScript's `<` and `>` compare UTF-16 code units, and the two disagree
+ * wherever an astral character meets one in U+E000-U+FFFF: an astral character
+ * is a surrogate pair starting at U+D800, so `'A\u{1F600}' < 'A！'` in
+ * JavaScript and the reverse on the server. Any listing that merges or bounds
+ * rows in memory and then resumes with a key condition has to use this order,
+ * or the boundary it draws is not the boundary the next query reads from, and
+ * a row is skipped or handed out twice.
+ *
+ * The comparison is written on the bytes rather than on code points. The two
+ * agree — UTF-8 was designed so that byte order is code-point order — but the
+ * bytes are what DynamoDB documents itself as comparing, so the code states the
+ * server's rule instead of a property that happens to coincide with it.
+ *
+ * Accepts: `left`, `right` — any two strings; well-formedness is not required,
+ * since an unpaired surrogate encodes to the replacement character's bytes and
+ * so still compares deterministically.
+ *
+ * Returns: a negative number when `left` sorts before `right`, a positive one
+ * when it sorts after, and `0` when the two encode to the same bytes.
+ *
+ * Throws: nothing.
+ */
+export declare function compareSortKeys(left: string, right: string): number;

package/dist/cjs/shared/dynamodb/table-schema.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_ROW_FORMAT_VERSION = exports.ROW_FORMAT_VERSION = exports.ADAPTER_TAGS = exports.KEY_SEPARATOR = exports.MAX_SORT_KEY_BYTES = exports.MAX_CHECKPOINT_NS_BYTES = exports.MAX_WRITE_CHANNEL_BYTES = exports.MAX_KEY_SEGMENT_BYTES = exports.MAX_PARTITION_ID_BYTES = exports.SORT_KEY_ATTRIBUTE = exports.PARTITION_KEY_ATTRIBUTE = void 0;
+exports.rowKeyOf = rowKeyOf;
+exports.rowVersionOf = rowVersionOf;
+exports.assertReadableRow = assertReadableRow;
+exports.isExpiredRow = isExpiredRow;
+exports.withoutExpired = withoutExpired;
+exports.compareSortKeys = compareSortKeys;
+const base_error_js_1 = require("../errors/base-error.js");
+const error_code_js_1 = require("../errors/error-code.js");
+exports.PARTITION_KEY_ATTRIBUTE = 'PK';
+exports.SORT_KEY_ATTRIBUTE = 'SK';
+exports.MAX_PARTITION_ID_BYTES = 1024;
+exports.MAX_KEY_SEGMENT_BYTES = 256;
+exports.MAX_WRITE_CHANNEL_BYTES = 1024;
+exports.MAX_CHECKPOINT_NS_BYTES = 512;
+exports.MAX_SORT_KEY_BYTES = 1024;
+exports.KEY_SEPARATOR = '#';
+exports.ADAPTER_TAGS = { checkpointer: 'CHKPT', store: 'STORE', history: 'HIST' };
+function rowKeyOf(row) {
+    return { PK: row.PK, SK: row.SK };
+}
+exports.ROW_FORMAT_VERSION = 1;
+exports.SUPPORTED_ROW_FORMAT_VERSION = 1;
+function rowVersionOf(row) {
+    return typeof row.v === 'number' ? row.v : 0;
+}
+function assertReadableRow(row, what) {
+    const version = rowVersionOf(row);
+    if (version <= exports.SUPPORTED_ROW_FORMAT_VERSION)
+        return;
+    throw new base_error_js_1.DynamoDBLangGraphError(`this ${what} row was written in format version ${version}; this version of the library ` +
+        `reads up to ${exports.SUPPORTED_ROW_FORMAT_VERSION} — upgrade to read it`, error_code_js_1.ErrorCode.FORMAT_UNSUPPORTED, { field: 'v' });
+}
+function isExpiredRow(row, nowSeconds) {
+    return row.ttl !== undefined && row.ttl <= nowSeconds;
+}
+const TTL_FILTER = 'attribute_not_exists(#ttl) OR #ttl > :now';
+function withoutExpired(params, nowSeconds) {
+    return {
+        ...params,
+        FilterExpression: params.FilterExpression
+            ? `(${params.FilterExpression}) AND (${TTL_FILTER})`
+            : TTL_FILTER,
+        ExpressionAttributeNames: { ...params.ExpressionAttributeNames, '#ttl': 'ttl' },
+        ExpressionAttributeValues: { ...params.ExpressionAttributeValues, ':now': nowSeconds },
+    };
+}
+function compareSortKeys(left, right) {
+    return Buffer.compare(Buffer.from(left, 'utf8'), Buffer.from(right, 'utf8'));
+}

package/dist/cjs/shared/errors/base-error.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Hides the one error class and what counts as an error at all.
+ *
+ * Every failure this package raises is a `DynamoDBLangGraphError` told apart by
+ * its code (record 19), recognisable across copies of the package by a brand
+ * rather than by `instanceof`; and whatever a caller's code or a dependency
+ * throws — a string, `undefined`, an object — is turned into an `Error` before
+ * anything reads it.
+ */
+import type { WriteRequest } from '../dynamodb/client.js';
+import { ErrorCode } from './error-code.js';
+/**
+ * Structured, log-safe context attached to every library error. Identifiers
+ * and counts only — never a payload or a credential.
+ */
+export interface ErrorContext {
+    /** The DynamoDB table the operation targeted, when known. */
+    tableName?: string;
+    /** The public operation (`saver.put`, `store.batch`, …) or internal step that failed. */
+    operation?: string;
+    /** The option, argument or cap that failed validation or was exceeded. */
+    field?: string;
+    /** The S3 object key involved, for offload failures. */
+    key?: string;
+    /** Attempts made before a retry budget was exhausted. */
+    attempts?: number;
+    /** The thread a checkpointer failure belongs to. */
+    threadId?: string;
+    /** The checkpoint a checkpointer failure names. */
+    checkpointId?: string;
+    /**
+     * The AWS exception name of the failure underneath, when that failure was
+     * AWS-shaped (it carried the SDK's `$metadata`, or a name the classifier
+     * knows or that ends in `Exception`). Lifted off `cause.name` so a log line
+     * or an alert can branch on it without walking `cause`.
+     */
+    awsErrorName?: string;
+    /** The AWS request id (`cause.$metadata.requestId`), which AWS Support asks for. */
+    requestId?: string;
+    /** The HTTP status of the failed AWS response (`cause.$metadata.httpStatusCode`). */
+    httpStatusCode?: number;
+}
+/** What one `BatchWriteItem` drain left behind when it ran out of rounds. */
+export interface BatchDrainDetails {
+    readonly kind: 'drain';
+    /** Writes DynamoDB acknowledged; they persist, since there is no rollback. */
+    readonly succeededCount: number;
+    /** The requests DynamoDB did not acknowledge, verbatim, so they can be re-submitted. */
+    readonly unprocessed: readonly WriteRequest[];
+    /** `UnprocessedItems` rounds spent. */
+    readonly retries: number;
+}
+/**
+ * The tally of a pass that attempted every chunk (`unit: 'chunk'`, 25-row
+ * `BatchWriteItem` chunks) or every row (`unit: 'row'`, one conditional delete
+ * per row) before reporting.
+ */
+export interface BatchPassDetails {
+    readonly kind: 'pass';
+    readonly unit: 'chunk' | 'row';
+    readonly succeededChunks: number;
+    readonly totalChunks: number;
+    /** Each failing chunk's or row's own error. */
+    readonly failedChunks: readonly Error[];
+    /** Individual writes confirmed persisted across the whole pass. */
+    readonly succeededCount: number;
+}
+/** What a `BATCH_WRITE_INCOMPLETE` error reports: one drain, or a whole pass. */
+export type BatchWriteIncompleteDetails = BatchDrainDetails | BatchPassDetails;
+/** What a `COMPENSATION_FAILED` error reports besides its trigger, which is `cause`. */
+export interface CompensationFailedDetails {
+    /**
+     * Why the append could not be undone or settled: the rollback's own
+     * failure (itself often a `BATCH_WRITE_INCOMPLETE`), the read-back's
+     * failure, or the write's own failure when some attempt of it may still
+     * be applied.
+     */
+    readonly rollbackError: Error;
+}
+/** The codes that carry details, and the shape each one carries. */
+export interface ErrorDetailsByCode {
+    [ErrorCode.BATCH_WRITE_INCOMPLETE]: BatchWriteIncompleteDetails;
+    [ErrorCode.COMPENSATION_FAILED]: CompensationFailedDetails;
+}
+/** The details a code carries; `undefined` for every code not in {@link ErrorDetailsByCode}. */
+export type ErrorDetailsFor<C extends ErrorCode> = C extends keyof ErrorDetailsByCode ? ErrorDetailsByCode[C] : undefined;
+/**
+ * Base class for every error this library throws. Carries a branchable
+ * {@link ErrorCode}, structured {@link ErrorContext}, code-specific
+ * {@link details}, and a native `cause` chain. Detected via
+ * {@link isDynamoDBLangGraphError} (a symbol brand) rather than `instanceof`,
+ * which is banned repo-wide.
+ */
+export declare class DynamoDBLangGraphError<C extends ErrorCode = ErrorCode> extends Error {
+    readonly code: C;
+    readonly context: ErrorContext;
+    /** Declared, not emitted: a code without details leaves no `undefined`-valued own property. */
+    readonly details: ErrorDetailsFor<C>;
+    /**
+     * Accepts: `message` — already redacted by whoever composed it, since it reaches
+     * `err.message`, which an application may print without a redacting logger.
+     * `code` — the code this error branches on. `context` — identifiers and counts
+     * only, never a payload or a credential. It is **copied**, so a caller that
+     * reuses one builder object cannot rewrite the context of an error already in
+     * flight; `null` reads as an absent one. `cause` — the failure below this one,
+     * kept as the native `cause` chain. `details` — the code-specific record
+     * {@link ErrorDetailsByCode} names, copied like `context`. The parameter is
+     * optional for every code, including the two whose `details` property is
+     * typed as always present (`BATCH_WRITE_INCOMPLETE`, `COMPENSATION_FAILED`):
+     * nothing at compile time stops a direct `new` from leaving it out, and an
+     * error built that way has no `details` at runtime whatever its type says.
+     * Inside this package those two codes are only ever built by the factories
+     * that always pass them.
+     *
+     * Returns: the error, branded so {@link isDynamoDBLangGraphError} recognises it
+     * across realms and across two copies of this package. The brand is
+     * non-enumerable, so it never reaches a log or a JSON serialization.
+     *
+     * Throws: nothing; building an error may not fail.
+     */
+    constructor(message: string, code: C, context?: ErrorContext, cause?: Error, details?: ErrorDetailsFor<C>);
+}
+/**
+ * Every library error, as a union discriminated by `code`: comparing `code`
+ * narrows `details` to the shape that code carries.
+ */
+export type AnyDynamoDBLangGraphError = {
+    [C in ErrorCode]: DynamoDBLangGraphError<C>;
+}[ErrorCode];
+/**
+ * Whether `value` is one of this library's errors.
+ *
+ * Accepts: whatever a `catch` clause binds, as it is — an error from any realm
+ * or any copy of this package, and any other value a `throw` can produce:
+ * `null`, `undefined`, a string, a number, a symbol. Declared `unknown`
+ * because that is what `strict` types a `catch` binding, and the documented
+ * place to call this is the first line inside one.
+ *
+ * Returns: whether it carries the brand, narrowed to the union discriminated by
+ * `code`. A symbol registered by name, not `instanceof`: two copies of this
+ * package in one dependency tree produce two classes but one symbol, and an
+ * error crossing a realm boundary keeps its properties while losing its
+ * prototype. Anything that cannot carry a property answers `false`. Earlier
+ * releases set the same brand, so an older copy of this package installed
+ * beside this one has its errors recognised too — in that release's shape: no
+ * `details`, the counts as flat properties, and possibly a code this union
+ * does not list (`UPSTREAM`).
+ *
+ * Throws: nothing. The `in` operator raises a `TypeError` on a non-object, and
+ * a guard that throws inside the `catch` it was called from would replace the
+ * failure the caller is reporting with one of its own.
+ */
+export declare function isDynamoDBLangGraphError(value: unknown): value is AnyDynamoDBLangGraphError;
+/**
+ * Whether `value` is one of this library's errors carrying `code`.
+ *
+ * Accepts: anything a `catch` can bind. `code` — the code to test for.
+ *
+ * Returns: `true` only for a branded error whose `code` is `code`, narrowed so
+ * its `details` are typed. An unbranded object that merely carries a `code`
+ * property is not one: recognition is by brand and code together, never by a
+ * name or a shape.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function hasErrorCode<C extends ErrorCode>(value: Error, code: C): value is DynamoDBLangGraphError<C>;
+/**
+ * A caller's own copy of a branded error that several concurrent callers would
+ * otherwise share — a cached rejected import, a cached rejected client build.
+ * Sharing the one instance is safe while nothing on the path back to a public
+ * method writes to it, but the public boundary does: it stamps
+ * `context.operation` and `context.tableName`, each independently when the
+ * error does not already carry it, in place, and a second caller reaching the
+ * same shared instance through a *different* public method would then find
+ * the first caller's operation and table already sitting in its own context,
+ * unable to write its own. Giving each
+ * caller its own instance up front — same `message`, `code`, `context` and
+ * `cause` — keeps the two from ever writing to one object. Not a general
+ * clone: an *unbranded* failure needs none, since `wrapForeignError`
+ * (`shared/errors/boundary.ts`) already builds a fresh wrapper for it at
+ * every boundary crossing, unlike a branded error, which crosses unwrapped.
+ *
+ * Accepts: `error` — anything a `catch` can bind.
+ *
+ * Returns: a new `DynamoDBLangGraphError` carrying the same `message`, `code`,
+ * `context`, `cause` and `details` as `error`, when `error` already was one;
+ * `error` itself, unchanged, for anything else. The copy does not carry
+ * `RETRY_EXHAUSTED`'s non-enumerable record of whether a write's retry budget
+ * may still land, so it is not for a budget error: a caller judging one asks
+ * the original.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function copyForCaller(error: Error): Error;
+/**
+ * What a log line calls a failure.
+ *
+ * Accepts: any error a `catch` bound.
+ *
+ * Returns: the `code` of one of this library's errors, and the `name` of any
+ * other. Every library error shares one name, so the name alone would log
+ * `DynamoDBLangGraphError` for a refused input and a spent retry budget alike;
+ * the code is what tells them apart, and like a name it is an identifier, never
+ * a payload.
+ *
+ * Throws: nothing for an error. A value that cannot carry a property raises
+ * the `TypeError` reading its `name` raises, as reading it directly would.
+ */
+export declare function failureLabel(error: Error): string;
+/**
+ * A caught value as an `Error`.
+ *
+ * Kept in this module rather than in `boundary.ts`, which otherwise reads as
+ * its natural home: `shared/logging/secret-patterns.ts` calls this to
+ * normalise whatever a `catch` bound before redacting it, and `boundary.ts`
+ * itself calls `redactedMessage` while building the error it wraps a foreign
+ * failure into. Both edges are real, so the two modules cannot import each
+ * other without a cycle; this module depends on neither.
+ *
+ * Accepts: `value` — declared `Error` because callers narrow a catch clause
+ * with `toError(error as Error)`, but anything can be thrown in JavaScript:
+ * a string, `undefined`, a plain object, a `BigInt`, a symbol.
+ *
+ * Returns: the value itself when it is error-shaped — an object carrying a
+ * string `message`, which keeps an SDK error's own fields and `cause` intact;
+ * otherwise a fresh `Error` describing what was thrown.
+ *
+ * Throws: **nothing**. This runs inside `catch` blocks, so a throw here would
+ * discard the failure being reported and replace it with its own.
+ */
+export declare function toError(value: Error): Error;

package/dist/cjs/shared/errors/base-error.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamoDBLangGraphError = void 0;
+exports.isDynamoDBLangGraphError = isDynamoDBLangGraphError;
+exports.hasErrorCode = hasErrorCode;
+exports.copyForCaller = copyForCaller;
+exports.failureLabel = failureLabel;
+exports.toError = toError;
+const error_code_js_1 = require("./error-code.js");
+const ERROR_BRAND = Symbol.for('@farukada/aws-langgraph-dynamodb-ts/error');
+function isList(field) {
+    return Array.isArray(field);
+}
+function copyDetails(details) {
+    if (details === null || typeof details !== 'object')
+        return details;
+    const fields = Object.entries(details);
+    return Object.fromEntries(fields.map(([key, value]) => [key, isList(value) ? [...value] : value]));
+}
+class DynamoDBLangGraphError extends Error {
+    code;
+    context;
+    constructor(message, code, context = {}, cause, details) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'DynamoDBLangGraphError';
+        this.code = code;
+        this.context = { ...context };
+        if (details !== undefined)
+            this.details = copyDetails(details);
+        Object.defineProperty(this, ERROR_BRAND, { value: true, enumerable: false });
+    }
+}
+exports.DynamoDBLangGraphError = DynamoDBLangGraphError;
+function isDynamoDBLangGraphError(value) {
+    return typeof value === 'object' && value !== null && ERROR_BRAND in value;
+}
+function hasErrorCode(value, code) {
+    return isDynamoDBLangGraphError(value) && value.code === code;
+}
+function copyForCaller(error) {
+    if (!isDynamoDBLangGraphError(error))
+        return error;
+    return new DynamoDBLangGraphError(error.message, error.code, error.context, error.cause, error.details);
+}
+function failureLabel(error) {
+    return isDynamoDBLangGraphError(error) ? error.code : error.name;
+}
+function describeThrown(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === undefined || value === null)
+        return `${String(value)} was thrown`;
+    try {
+        return JSON.stringify(value) ?? `a ${typeof value} value was thrown`;
+    }
+    catch {
+        return `an unserializable ${typeof value} value was thrown`;
+    }
+}
+function toError(value) {
+    if (value !== null && typeof value === 'object' && messageOf(value) !== undefined)
+        return value;
+    return new Error(describeThrown(value));
+}
+function messageOf(value) {
+    try {
+        const { message } = value;
+        return typeof message === 'string' ? message : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cjs/shared/errors/boundary.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Hides what crosses the public boundary.
+ *
+ * Only this package's own error leaves a public method (record 13): an error of
+ * its own passes through, given the public operation and the table it surfaced
+ * through for whichever of the two it does not already name, and anything
+ * else — an SDK failure, a caller's thrown value — is classified and wrapped
+ * with its cause attached and its text redacted.
+ */
+import { type AnyDynamoDBLangGraphError, DynamoDBLangGraphError } from './base-error.js';
+/**
+ * Normalise anything escaping a public method into the library's error model.
+ *
+ * Accepts: anything a `catch` produced — an `Error`, or a value that is not one
+ * (`toError` settles that first). `operation` — the public method's name.
+ * `tableName` — the adapter's table, when the method has one.
+ *
+ * Returns: a branded library error — the same one, when it already was one,
+ * with whichever of `context.operation` and `context.tableName` it does not
+ * already carry filled in — or anything else wrapped by {@link wrapForeignError}
+ * with the code the classifier assigns, stamped the same way.
+ *
+ * Throws: nothing. It runs inside a `catch`, where throwing would discard the
+ * failure being reported and replace it with its own.
+ */
+export declare function toPublicError(error: Error, operation: string, tableName?: string): AnyDynamoDBLangGraphError;
+/**
+ * Run a public operation so that every rejection is a library error.
+ *
+ * Accepts: `operation` — the public method's name, which the error carries.
+ * `fn` — the work. `tableName` — the adapter's table, which the error carries.
+ *
+ * Returns: whatever `fn` resolves to, untouched.
+ *
+ * Throws: a library error, always. Applied once, at each adapter class method,
+ * so internal code can keep rethrowing SDK errors verbatim — the retry
+ * classifier depends on their shape, and wrapping them early would blind it.
+ */
+export declare function guardPublic<T>(operation: string, fn: () => Promise<T>, tableName?: string): Promise<T>;
+/**
+ * The same guard for a streaming result.
+ *
+ * Accepts: `operation` — the public method's name. `source` — the generator to
+ * relay. `tableName` — the adapter's table.
+ *
+ * Returns: a generator yielding the source's items untouched. A consumer that
+ * stops early still closes the source, so an abandoned listing stops reading
+ * rather than paging on in the background.
+ *
+ * Throws: a library error, always — including for a failure raised
+ * mid-iteration, which is the case a `try` around the loop body would miss.
+ */
+export declare function guardPublicIterable<T>(operation: string, source: AsyncGenerator<T>, tableName?: string): AsyncGenerator<T>;
+/**
+ * The same guard for a synchronous public method.
+ *
+ * Accepts: `operation` — the public method's name. `fn` — the work.
+ * `tableName` — the adapter's table.
+ *
+ * Returns: whatever `fn` returns.
+ *
+ * Throws: a library error, always — what a client's own `destroy` threw
+ * included, classified like any other foreign failure and kept as `cause`.
+ */
+export declare function guardPublicSync<T>(operation: string, fn: () => T, tableName?: string): T;
+/**
+ * A failure from below this library, as one of its errors.
+ *
+ * Accepts: `cause` — whatever a `catch` bound: an AWS SDK error, a transport
+ * error, or what a `VectorBackend`, `Embeddings`, `serde` or `MultiSessionHistory`
+ * threw. `operation` — the public method it surfaced through.
+ *
+ * Returns: an error whose code is {@link classifyAwsError}'s answer for
+ * {@link classifiableCause} of the normalised `cause` — so an AWS or network
+ * failure found down the cause chain still earns its own code rather than
+ * `UNEXPECTED_ERROR`. Its context names `operation` and — for whichever node
+ * was classified — `awsErrorName`, `requestId` and `httpStatusCode`. Its
+ * `cause` is the original, normalised through {@link toError}, kept whole
+ * regardless of which node down the chain supplied the code. The message
+ * quotes the cause's own name cut at the log cap and its own text redacted
+ * and cut at the relay cap, because `err.message` reaches applications that
+ * print it without a redacting logger.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function wrapForeignError(cause: Error, operation: string): DynamoDBLangGraphError;