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

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

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * 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.
+ */
+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_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.withRowVersion = withRowVersion;
+exports.isExpiredRow = isExpiredRow;
+exports.withoutExpired = withoutExpired;
+exports.compareSortKeys = compareSortKeys;
+const base_error_1 = require("../errors/base-error");
+const error_code_1 = require("../errors/error-code");
+/** The attribute every row is partitioned by. */
+exports.PARTITION_KEY_ATTRIBUTE = 'PK';
+/** The attribute every row is sorted by within its partition. */
+exports.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`.
+ */
+exports.MAX_PARTITION_ID_BYTES = 1024;
+/**
+ * Sort-key segments: `checkpoint_ns`, `checkpoint_id`, `taskId`, a pending-write
+ * channel, a store namespace element and a store `key`.
+ */
+exports.MAX_KEY_SEGMENT_BYTES = 256;
+/**
+ * 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
+ */
+exports.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).
+ */
+exports.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).
+ */
+exports.ADAPTER_TAGS = { checkpointer: 'CHKPT', store: 'STORE', history: 'HIST' };
+/**
+ * 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.
+ */
+function rowKeyOf(row) {
+    return { PK: row.PK, SK: row.SK };
+}
+/**
+ * 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.
+ */
+exports.ROW_FORMAT_VERSION = 1;
+/** The highest version this package knows how to read. */
+exports.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.
+ */
+function rowVersionOf(row) {
+    return typeof row.v === 'number' ? row.v : 0;
+}
+/**
+ * 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.
+ */
+function assertReadableRow(row, what) {
+    const version = rowVersionOf(row);
+    if (version <= exports.SUPPORTED_ROW_FORMAT_VERSION)
+        return;
+    throw new base_error_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_1.ErrorCode.FORMAT_UNSUPPORTED, { field: 'v' });
+}
+/**
+ * The item with this release's format version stamped on it.
+ *
+ * Accepts: `item` — any item about to be written; an existing `v` is replaced.
+ *
+ * Returns: a copy carrying `v`, leaving the input untouched.
+ *
+ * Throws: nothing.
+ */
+function withRowVersion(item) {
+    return { ...item, v: exports.ROW_FORMAT_VERSION };
+}
+/**
+ * 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: an expired row is absent to every reader even while DynamoDB's
+ * own sweep lags, which it may by up to 48 hours
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/howitworks-ttl.html).
+ */
+function isExpiredRow(row, nowSeconds) {
+    return row.ttl !== undefined && row.ttl <= nowSeconds;
+}
+const TTL_FILTER = 'attribute_not_exists(#ttl) OR #ttl > :now';
+/**
+ * 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`.
+ */
+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 },
+    };
+}
+/**
+ * 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.
+ */
+function compareSortKeys(left, right) {
+    return Buffer.compare(Buffer.from(left, 'utf8'), Buffer.from(right, 'utf8'));
+}

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

@@ -1,22 +1,196 @@
+/**
+ * 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';
 import { ErrorCode } from './error-code';
-/** Structured, log-safe context attached to every library error. */
+/**
+ * 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 rollback itself could not finish; itself often a `BATCH_WRITE_INCOMPLETE`. */
+    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}, and a native `cause`
- * chain. Detected via {@link isDynamoDbLangGraphError} (a symbol brand) rather
- * than `instanceof`, which is banned repo-wide.
+ * {@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 extends Error {
-    readonly code: ErrorCode;
+export declare class DynamoDBLangGraphError<C extends ErrorCode = ErrorCode> extends Error {
+    readonly code: C;
     readonly context: ErrorContext;
-    constructor(message: string, code: ErrorCode, context?: ErrorContext, cause?: Error);
+    /** 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>);
 }
-/** True when `value` is a {@link DynamoDbLangGraphError}, detected by brand. */
-export declare function isDynamoDbLangGraphError(value: Error): value is DynamoDbLangGraphError;
-//# sourceMappingURL=base-error.d.ts.map
+/**
+ * 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: any error, from any realm or any copy of this package — and, since
+ * the documented place to call this is inside a `catch`, any other value a
+ * `throw` can produce: `null`, `undefined`, a string, a number, a symbol.
+ *
+ * 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: Error): 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>;
+/**
+ * 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/shared/errors/base-error.js

@@ -1,28 +1,174 @@
 "use strict";
+/**
+ * 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.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DynamoDbLangGraphError = void 0;
-exports.isDynamoDbLangGraphError = isDynamoDbLangGraphError;
+exports.DynamoDBLangGraphError = void 0;
+exports.isDynamoDBLangGraphError = isDynamoDBLangGraphError;
+exports.hasErrorCode = hasErrorCode;
+exports.failureLabel = failureLabel;
+exports.toError = toError;
+const error_code_1 = require("./error-code");
 const ERROR_BRAND = Symbol.for('@farukada/aws-langgraph-dynamodb-ts/error');
+/**
+ * A shallow copy of `details` with every array copied too, so a caller reusing
+ * its request buffer or failure list cannot rewrite what the error reported.
+ * Anything that is not an object is returned as it is: building an error may
+ * not fail.
+ */
+function copyDetails(details) {
+    if (details === null || typeof details !== 'object')
+        return details;
+    return Object.fromEntries(Object.entries(details).map(([key, value]) => [key, Array.isArray(value) ? [...value] : value]));
+}
 /**
  * Base class for every error this library throws. Carries a branchable
- * {@link ErrorCode}, structured {@link ErrorContext}, and a native `cause`
- * chain. Detected via {@link isDynamoDbLangGraphError} (a symbol brand) rather
- * than `instanceof`, which is banned repo-wide.
+ * {@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.
  */
-class DynamoDbLangGraphError extends Error {
+class DynamoDBLangGraphError extends Error {
     code;
     context;
-    constructor(message, code, context = {}, cause) {
+    /**
+     * 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, code, context = {}, cause, details) {
         super(message, cause === undefined ? undefined : { cause });
-        this.name = 'DynamoDbLangGraphError';
+        this.name = 'DynamoDBLangGraphError';
         this.code = code;
-        this.context = context;
+        this.context = { ...context };
+        if (details !== undefined)
+            this.details = copyDetails(details);
         Object.defineProperty(this, ERROR_BRAND, { value: true, enumerable: false });
     }
 }
-exports.DynamoDbLangGraphError = DynamoDbLangGraphError;
-/** True when `value` is a {@link DynamoDbLangGraphError}, detected by brand. */
-function isDynamoDbLangGraphError(value) {
-    return ERROR_BRAND in value;
+exports.DynamoDBLangGraphError = DynamoDBLangGraphError;
+/**
+ * Whether `value` is one of this library's errors.
+ *
+ * Accepts: any error, from any realm or any copy of this package — and, since
+ * the documented place to call this is inside a `catch`, any other value a
+ * `throw` can produce: `null`, `undefined`, a string, a number, a symbol.
+ *
+ * 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.
+ */
+function isDynamoDBLangGraphError(value) {
+    return typeof value === 'object' && value !== null && ERROR_BRAND in value;
+}
+/**
+ * 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.
+ */
+function hasErrorCode(value, code) {
+    return isDynamoDBLangGraphError(value) && value.code === code;
+}
+/**
+ * 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.
+ */
+function failureLabel(error) {
+    return isDynamoDBLangGraphError(error) ? error.code : error.name;
+}
+/**
+ * A description of a thrown value that is not an `Error`, for its message.
+ *
+ * `JSON.stringify` is the best available rendering and it throws on a circular
+ * structure and on a `BigInt`, so it is guarded: this runs inside a `catch`,
+ * where throwing would replace the failure the caller is trying to report.
+ */
+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`;
+    }
+}
+/**
+ * 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.
+ */
+function toError(value) {
+    if (value !== null && typeof value === 'object' && typeof value.message === 'string') {
+        return value;
+    }
+    return new Error(describeThrown(value));
 }
-//# sourceMappingURL=base-error.js.map

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

@@ -0,0 +1,71 @@
+/**
+ * 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 with the operation named, 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';
+/**
+ * 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).
+ *
+ * Returns: a branded library error unchanged, since its code was assigned
+ * closer to the failure and wins; anything else wrapped by
+ * {@link wrapForeignError}, with the code the classifier assigns.
+ *
+ * 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): AnyDynamoDBLangGraphError;
+/**
+ * Run a public operation so that every rejection is a library error.
+ *
+ * Accepts: `operation` — the public method's name, which the wrapped error
+ * carries. `fn` — the work.
+ *
+ * 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>): Promise<T>;
+/**
+ * The same guard for a streaming result.
+ *
+ * Accepts: `operation` — the public method's name. `source` — the generator to
+ * relay.
+ *
+ * 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>): AsyncGenerator<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;