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

package/dist/shared/validation/options.js

@@ -0,0 +1,328 @@
+"use strict";
+/**
+ * Hides which adapter-wide construction options are accepted.
+ *
+ * The table name, the client choice, the ttl, the retry policy, the recency
+ * index, the read concurrency, compression and S3 offload are checked here with
+ * their bounds, before an adapter builds anything, so a misconfiguration
+ * surfaces at construction rather than on the first call.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_READ_CONCURRENCY = exports.MAX_RETRY_DELAY_MS = exports.MAX_RETRY_ATTEMPTS = exports.MAX_PAYLOAD_BUFFER_BYTES = void 0;
+exports.assertTableName = assertTableName;
+exports.assertClientChoice = assertClientChoice;
+exports.assertRetryBounds = assertRetryBounds;
+exports.assertRetryPolicy = assertRetryPolicy;
+exports.assertBaseAdapterOptions = assertBaseAdapterOptions;
+exports.assertCompression = assertCompression;
+exports.assertS3 = assertS3;
+const codec_1 = require("../codec/codec");
+const config_1 = require("../codec/s3/config");
+const recency_index_1 = require("../dynamodb/recency-index");
+const errors_1 = require("../errors/errors");
+const option_shape_1 = require("./option-shape");
+const primitives_1 = require("./primitives");
+const ttl_1 = require("./ttl");
+/** DynamoDB's table-name rule: 3–255 characters from `[A-Za-z0-9_.-]`. */
+const TABLE_NAME_PATTERN = /^[A-Za-z0-9_.-]{3,255}$/;
+/**
+ * Largest `s3.maxDownloadBytes`/`compression.maxDecompressedBytes` an adapter
+ * accepts (512 MiB): both hold one buffer fully resident while it is read or
+ * inflated, and `BaseAdapterOptions.readConcurrency`'s doc multiplies the two
+ * together into the package's memory ceiling, so an unbounded value here is an
+ * unbounded process, not just an unbounded object.
+ */
+exports.MAX_PAYLOAD_BUFFER_BYTES = 512 * 1024 * 1024;
+/** Largest `retry.maxAttempts` an adapter accepts; beyond it a retry loop is a hang, not a policy. */
+exports.MAX_RETRY_ATTEMPTS = 100;
+/**
+ * Largest `retry.baseDelayMs`/`retry.maxDelayMs` an adapter accepts (one
+ * minute): combined with {@link MAX_RETRY_ATTEMPTS}, an unbounded per-attempt
+ * delay turns a bounded attempt count back into an effectively unbounded wait.
+ */
+exports.MAX_RETRY_DELAY_MS = 60_000;
+/**
+ * Largest `readConcurrency` an adapter accepts: it is a multiplier on the
+ * memory-ceiling formula (see the option's own doc) and on requests fired at
+ * once, so an unbounded value turns a typo into an out-of-memory crash or a
+ * request storm against the table/bucket.
+ */
+exports.MAX_READ_CONCURRENCY = 128;
+const RETRY_KEYS = (0, option_shape_1.allKeysOf)({
+    maxAttempts: 'maxAttempts',
+    baseDelayMs: 'baseDelayMs',
+    maxDelayMs: 'maxDelayMs',
+});
+/**
+ * Validate a table name against DynamoDB's own naming rule.
+ *
+ * Accepts: `tableName` — as the caller gave it.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `tableName`.
+ */
+function assertTableName(tableName) {
+    if (typeof tableName !== 'string' || !TABLE_NAME_PATTERN.test(tableName)) {
+        throw (0, errors_1.validationError)('tableName must be 3-255 characters from [A-Za-z0-9_.-], as DynamoDB requires', 'tableName');
+    }
+}
+/**
+ * Reject a client choice that names two ways of getting one, or a
+ * `clientConfig` that is not an object.
+ *
+ * Accepts: the three client options, from an adapter or from the factory that
+ * defaults them. An injected `client` is used as-is, so a `clientConfig` or
+ * `createClient` given alongside it would be silently ignored — including a
+ * `region` the caller believes is in effect. `clientConfig`, when given, must
+ * be an object that is neither `null` nor an array; what it holds is the AWS
+ * SDK's to judge.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `client` for both ways at once, then
+ * `clientConfig` for one that is not an object.
+ */
+function assertClientChoice(options) {
+    if (options.client &&
+        (options.clientConfig !== undefined || options.createClient !== undefined)) {
+        throw (0, errors_1.validationError)('provide either `client` or `clientConfig`/`createClient`, not both: an injected client ' +
+            'is used as-is and the configuration would be silently ignored', 'client');
+    }
+    // The shape only, never the keys, and on purpose: they are the AWS SDK's
+    // `DynamoDBClientConfig`, which gains keys between SDK releases, and an
+    // application may install a newer SDK than the one this package was
+    // compiled against, so a key list compiled in here would refuse valid
+    // configuration. The SDK reads each key itself.
+    if (options.clientConfig !== undefined)
+        (0, option_shape_1.assertObjectShape)(options.clientConfig, 'clientConfig');
+}
+/**
+ * The three numeric bounds every retry policy shares, regardless of which
+ * other keys the caller's own type allows beyond them. Split out so a caller
+ * with a wider surface than {@link RetryPolicy} (`backfillRecencyIndex`'s
+ * `RetryOptions`, which also exposes `onRetry`, `isRetryable` and friends)
+ * can reuse the identical bounds without going through {@link
+ * assertRetryPolicy}'s narrower `assertShape`, which would refuse those
+ * extra keys outright.
+ *
+ * Accepts: `policy` — its `maxAttempts`, `baseDelayMs` and `maxDelayMs`, each
+ * optional.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `retry.maxAttempts`, `retry.baseDelayMs` or
+ * `retry.maxDelayMs`.
+ */
+function assertRetryBounds(policy) {
+    if (policy.maxAttempts !== undefined) {
+        (0, primitives_1.assertInteger)(policy.maxAttempts, 'retry.maxAttempts', { min: 1, max: exports.MAX_RETRY_ATTEMPTS });
+    }
+    if (policy.baseDelayMs !== undefined) {
+        (0, primitives_1.assertInteger)(policy.baseDelayMs, 'retry.baseDelayMs', { min: 1, max: exports.MAX_RETRY_DELAY_MS });
+    }
+    if (policy.maxDelayMs !== undefined) {
+        (0, primitives_1.assertInteger)(policy.maxDelayMs, 'retry.maxDelayMs', {
+            min: policy.baseDelayMs ?? 1,
+            max: exports.MAX_RETRY_DELAY_MS,
+        });
+    }
+}
+/**
+ * Validate a retry policy: shape, then each bound.
+ *
+ * Accepts: `policy` — must be an object naming only `maxAttempts`,
+ * `baseDelayMs` and `maxDelayMs`; each, if given, is a bounded integer.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `retry` or `retry.<key>`.
+ */
+function assertRetryPolicy(policy) {
+    (0, option_shape_1.assertShape)(policy, RETRY_KEYS, 'retry');
+    assertRetryBounds(policy);
+}
+/** The recency index: a named GSI, and the partition count rows are sharded across. */
+function assertRecencyIndex(options) {
+    if (options.indexShards !== undefined) {
+        (0, primitives_1.assertInteger)(options.indexShards, 'indexShards', { min: 1, max: recency_index_1.MAX_INDEX_SHARDS });
+    }
+    if (options.indexName !== undefined)
+        (0, primitives_1.assertNonEmptyString)(options.indexName, 'indexName');
+}
+/**
+ * Validate the options every adapter shares, at construction.
+ *
+ * Accepts: `options` — must be an object. `tableName` is required; every other
+ * option is optional, and `undefined` means "not configured" for each. A
+ * nested `ttl`, `retry`, `compression` or `s3` must be an object whose keys
+ * this package reads: a misspelt key is rejected rather than ignored, because
+ * the caller would otherwise run on a default they believe they overrode.
+ * `clientConfig` and `s3.clientConfig` must be objects, but their keys belong
+ * to the AWS SDK and are not checked. Keys of `options` itself are not checked
+ * here — the adapter types differ and this validator sees only the shared ones.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` whose `context.field` names the offending option,
+ * dotted for a nested one (`s3.bucketName`). The order is `tableName`, client
+ * choice, `ttl`, `retry`, `compression`, `s3`, `readConcurrency`, then the
+ * index options.
+ *
+ * Guarantees: a misconfiguration surfaces at construction, naming the option,
+ * rather than as a raw AWS error on the first request.
+ */
+function assertBaseAdapterOptions(options) {
+    if (typeof options !== 'object' || options === null) {
+        throw (0, errors_1.validationError)('options must be an object naming at least a tableName', 'options');
+    }
+    assertTableName(options.tableName);
+    assertClientChoice(options);
+    if (options.ttl !== undefined)
+        (0, ttl_1.resolveTtlSeconds)(options.ttl);
+    if (options.retry !== undefined)
+        assertRetryPolicy(options.retry);
+    if (options.compression !== undefined)
+        assertCompression(options.compression);
+    if (options.s3 !== undefined)
+        assertS3(options.s3);
+    if (options.readConcurrency !== undefined) {
+        (0, primitives_1.assertInteger)(options.readConcurrency, 'readConcurrency', {
+            min: 1,
+            max: exports.MAX_READ_CONCURRENCY,
+        });
+    }
+    assertRecencyIndex(options);
+}
+/** Server-side encryption algorithms S3 accepts for `PutObject`. */
+const SSE_ALGORITHMS = ['AES256', 'aws:kms', 'aws:kms:dsse'];
+const COMPRESSION_KEYS = (0, option_shape_1.allKeysOf)({
+    enabled: 'enabled',
+    level: 'level',
+    minSizeBytes: 'minSizeBytes',
+    maxDecompressedBytes: 'maxDecompressedBytes',
+});
+const S3_KEYS = (0, option_shape_1.allKeysOf)({
+    bucketName: 'bucketName',
+    keyPrefix: 'keyPrefix',
+    thresholdBytes: 'thresholdBytes',
+    serverSideEncryption: 'serverSideEncryption',
+    sseKmsKeyId: 'sseKmsKeyId',
+    maxDownloadBytes: 'maxDownloadBytes',
+    clientConfig: 'clientConfig',
+    createS3Client: 'createS3Client',
+});
+/**
+ * Validate a `compression` config, honoring its allowed key set.
+ *
+ * Accepts: `config` — an object naming only {@link CompressionConfig}'s keys.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming the offending field, dotted under
+ * `compression`.
+ */
+function assertCompression(config) {
+    (0, option_shape_1.assertShape)(config, COMPRESSION_KEYS, 'compression');
+    if (typeof config.enabled !== 'boolean') {
+        throw (0, errors_1.validationError)('compression.enabled must be a boolean', 'compression.enabled');
+    }
+    if (config.level !== undefined) {
+        (0, primitives_1.assertInteger)(config.level, 'compression.level', { min: 0, max: 9 });
+    }
+    if (config.minSizeBytes !== undefined) {
+        // Bounded by MAX_PAYLOAD_BUFFER_BYTES, not by MAX_INLINE_PAYLOAD_BYTES as
+        // `s3.thresholdBytes` is, because the two differ in kind. `encodePayload`
+        // compresses first and only then decides inline versus offload, on the
+        // compressed size — so `minSizeBytes` above the inline limit, paired with
+        // `s3`, is a meaningful configuration: compress only what will be offloaded
+        // anyway. A `thresholdBytes` above the inline limit is not: a payload
+        // between the two is too large to store inline and too small to offload,
+        // so its write fails. `minSizeBytes` only decides whether gzip runs; the
+        // only value it can never act on is one larger than any payload this
+        // package can read back.
+        (0, primitives_1.assertInteger)(config.minSizeBytes, 'compression.minSizeBytes', {
+            min: 0,
+            max: exports.MAX_PAYLOAD_BUFFER_BYTES,
+        });
+    }
+    if (config.maxDecompressedBytes !== undefined) {
+        (0, primitives_1.assertInteger)(config.maxDecompressedBytes, 'compression.maxDecompressedBytes', {
+            min: 1,
+            max: exports.MAX_PAYLOAD_BUFFER_BYTES,
+        });
+    }
+}
+/**
+ * Validate the two `s3` options `PutObject` receives as they were given.
+ *
+ * Accepts: `config.serverSideEncryption` — absent, or an algorithm S3 accepts.
+ * `config.sseKmsKeyId` — absent, or a non-empty string. Only its type is
+ * checked; whether it names a real key, by id or by ARN, is for S3 to answer.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `s3.serverSideEncryption` or
+ * `s3.sseKmsKeyId`. Unchecked, a truthy key id that is not a string was
+ * handed to `PutObject` at the first offload, and a falsy one (`''`, `null`,
+ * `0`) was dropped, uploading without the key the caller named.
+ */
+function assertS3Encryption(config) {
+    if (config.serverSideEncryption !== undefined &&
+        !SSE_ALGORITHMS.includes(config.serverSideEncryption)) {
+        throw (0, errors_1.validationError)(`s3.serverSideEncryption must be one of ${SSE_ALGORITHMS.join(', ')}`, 's3.serverSideEncryption');
+    }
+    if (config.sseKmsKeyId !== undefined) {
+        (0, primitives_1.assertNonEmptyString)(config.sseKmsKeyId, 's3.sseKmsKeyId');
+    }
+}
+/**
+ * Validate an `s3` offload config, honoring its allowed key set.
+ *
+ * Accepts: `config` — an object naming only {@link S3OffloadConfig}'s keys.
+ * `config.clientConfig`, when given, must be an object that is neither `null`
+ * nor an array; its own keys are not checked. `config.createS3Client`, when
+ * given, must be a function.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming the offending field, dotted under `s3`.
+ */
+function assertS3(config) {
+    (0, option_shape_1.assertShape)(config, S3_KEYS, 's3');
+    (0, primitives_1.assertNonEmptyString)(config.bucketName, 's3.bucketName');
+    // The shape only, never the keys: they are the AWS SDK's `S3ClientConfig`,
+    // which gains keys between SDK releases, and an application may install a
+    // newer SDK than the one this package was compiled against, so a key list
+    // compiled in here would refuse valid configuration.
+    if (config.clientConfig !== undefined)
+        (0, option_shape_1.assertObjectShape)(config.clientConfig, 's3.clientConfig');
+    if (config.thresholdBytes !== undefined) {
+        (0, primitives_1.assertInteger)(config.thresholdBytes, 's3.thresholdBytes', {
+            min: 1,
+            max: codec_1.MAX_INLINE_PAYLOAD_BYTES,
+        });
+    }
+    if (config.keyPrefix !== undefined)
+        (0, config_1.assertScopedKeyPrefix)(config.keyPrefix);
+    if (config.maxDownloadBytes !== undefined) {
+        (0, primitives_1.assertInteger)(config.maxDownloadBytes, 's3.maxDownloadBytes', {
+            min: 1,
+            max: exports.MAX_PAYLOAD_BUFFER_BYTES,
+        });
+    }
+    assertS3Encryption(config);
+    // Called to build the S3 client at the first offload, where a value that is
+    // not a function threw a bare `TypeError`.
+    if (config.createS3Client !== undefined && typeof config.createS3Client !== 'function') {
+        throw (0, errors_1.validationError)('s3.createS3Client must be a function', 's3.createS3Client');
+    }
+}

package/dist/shared/validation/primitives.d.ts

@@ -1,25 +1,292 @@
-import type { Redactable } from '../logging/redaction-walk';
-/** Throw {@link ValidationError} unless `value` is a non-empty string. */
-export declare function validateNonEmptyString(value: string, field: string): void;
-/** Throw {@link ValidationError} unless `value` is an integer within bounds. */
-export declare function validateInteger(value: number, field: string, bounds?: {
+/**
+ * Hides the rules every caller-supplied primitive must pass.
+ *
+ * What makes a string an identifier safe inside a key, an integer a page size
+ * this package serves, and an array a copy holding only strings is decided
+ * once here. Only `parseLimit` returns a branded type of its own —
+ * `PageLimit`, which only it can build (record 21); every other rule's
+ * `parse*` form returns the plain checked value, and a feature parser brands
+ * it into its own type. Feature parsers compose these rules rather than
+ * restate them, so tightening one changes every method at once.
+ */
+/**
+ * Largest `limit` any read accepts, on every method that takes one.
+ *
+ * Chosen from what a page costs, which is linear in `limit` and amortised
+ * nowhere: every row of a page is held decoded and resident until the whole
+ * page is handed back, and an offloaded row is an S3 GET and a decompression
+ * of its own, `readConcurrency` at a time. A page of N rows is therefore N
+ * objects held at once and, in the worst case, N round trips before the caller
+ * sees the first of them.
+ *
+ * Ten thousand is where this package already says a read has stopped being one
+ * and become an export: `MAX_TOTAL_ROWS_IN_MEMORY`
+ * (`src/shared/dynamodb/paginate.ts`) refuses to collect more than that across
+ * a whole paginated query, and `LIST_SCAN_WARN_THRESHOLD`
+ * (`src/shared/dynamodb/paginate.ts`) tells an operator about a listing that
+ * walks that far. A single page allowed past either would hold more than every
+ * other path in the package may. Its own literal at the same value rather than
+ * an alias of them, for the reason `LIST_SCAN_WARN_THRESHOLD`
+ * (`src/shared/dynamodb/paginate.ts`) records.
+ *
+ * What it does *not* do is promise a memory figure: rows are the caller's own
+ * data, so ten thousand session summaries are a few megabytes while a hundred
+ * items at `MAX_INLINE_PAYLOAD_BYTES` (`src/shared/codec/codec.ts`) are forty.
+ * It bounds a typo — a `1e12` that would otherwise resolve — not a working set.
+ *
+ * What a caller loses at the ceiling is one large page, never the rows: every
+ * bounded read has a way to continue — `listSessions` a cursor, `search` an
+ * `offset`, `getMessages` a `before`, and `saver.list` streams and never
+ * accumulates — so an answer larger than this is paid for as pages.
+ */
+export declare const MAX_PAGE_LIMIT = 10000;
+declare const pageLimitBrand: unique symbol;
+/**
+ * A page size checked against the package-wide page rule: an integer from the
+ * call site's floor to {@link MAX_PAGE_LIMIT}. {@link parseLimit} is the only
+ * way to obtain one, so a reader that asks for a `PageLimit` cannot be handed a
+ * size nobody checked, and does not check it again. The brand is phantom: at
+ * run time it is the caller's own number.
+ */
+export type PageLimit = number & {
+    readonly [pageLimitBrand]: true;
+};
+/**
+ * The value as a string, or a refusal.
+ *
+ * Accepts: `value` — anything. A JavaScript caller, or a TypeScript caller
+ * whose input came from JSON, can pass any type where a string is declared, and
+ * every rule after this one reaches a string method.
+ *
+ * Returns: `value`, typed as the string it was checked to be.
+ *
+ * Throws: `VALIDATION` naming `field`, for anything that is not a string.
+ */
+export declare function parseString(value: unknown, field: string): string;
+/**
+ * Throw `VALIDATION` unless `value` is a string holding at least one
+ * non-whitespace character.
+ *
+ * Accepts: `value` — any type; `''` and whitespace-only are rejected alongside
+ * non-strings. `field` — the option or identifier name carried on the error.
+ * The rule is {@link parseNonBlankString}'s; this form is for a value the
+ * caller keeps under its declared type.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field`.
+ */
+export declare function assertNonEmptyString(value: string, field: string): void;
+/**
+ * The value as an integer inside `bounds`.
+ *
+ * Accepts: `value` — anything; a non-number, a fraction, `NaN` and `Infinity`
+ * are all refused by the integer rule. `bounds` — omitted or `{}` bounds
+ * nothing; `min` and `max` are inclusive.
+ *
+ * Returns: `value`, typed as a number.
+ *
+ * Throws: `VALIDATION` naming `field`; the integer rule is reported before
+ * either bound.
+ */
+export declare function parseInteger(value: unknown, field: string, bounds?: {
+    min?: number;
+    max?: number;
+}): number;
+/**
+ * Throw `VALIDATION` unless `value` is an integer inside `bounds`.
+ *
+ * Accepts: `value` — any type; a non-number, a fraction, `NaN` and `Infinity`
+ * are all rejected by the integer rule. `bounds` — omitted or `{}` bounds
+ * nothing, `min` and `max` are inclusive and may be given together or alone.
+ * The rule is {@link parseInteger}'s; this form is for a value the caller
+ * keeps under its declared type.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field`; the integer rule is reported before
+ * either bound.
+ */
+export declare function assertInteger(value: number, field: string, bounds?: {
     min?: number;
     max?: number;
 }): void;
-/** Throw {@link ValidationError} unless `value` is a non-empty array. */
-export declare function validateNonEmptyArray<T>(value: T[], field: string): void;
-/** Throw {@link ValidationError} if `value` contains an ASCII control character. */
+/**
+ * The value as a page size this package will serve: an integer from `min` to
+ * {@link MAX_PAGE_LIMIT}.
+ *
+ * One rule for every `limit` a public method takes. Without it they would
+ * disagree three ways — no minimum on `saver.list`, so `limit: -1` would
+ * resolve; `0` refused by the history reads and accepted by the store — and
+ * none would have a ceiling, so `limit: 1e12` would resolve on five methods.
+ * The same mistake would be answered differently depending on which method a
+ * caller happened to reach for.
+ *
+ * What survives that unification is one message shape, one ceiling and two
+ * floors, because zero does not ask for the same thing on every method. A zero
+ * *page* is answered: the caller asked a listing for nothing, holds the empty
+ * array it returned, and can see that is what it got. A zero *conversation
+ * window* is refused: it feeds a model rather than a caller, an empty
+ * conversation is indistinguishable from one that never happened, and the
+ * answer the model gives is persisted as the transcript. So every call site
+ * passes its floor and says why; `1` is passed from exactly one place,
+ * `parseMessageWindow` in `src/history/internal/parse.ts`, which is the
+ * check behind `history.getMessages` and `history.forSession` alike.
+ *
+ * Accepts: `value` — any type; a non-number, a fraction, `NaN` and `Infinity`
+ * are all rejected by the integer rule. `min` — `0` where an empty result is a
+ * request the call site answers without issuing a read, `1` where an empty
+ * result would be mistaken for an empty conversation. A negative value is
+ * refused at either floor rather than read as zero: it is a page size that was
+ * computed, and the computation went wrong.
+ *
+ * Returns: `value` as a {@link PageLimit}.
+ *
+ * Throws: `VALIDATION` naming `limit`, quoting the bound broken — the floor
+ * or {@link MAX_PAGE_LIMIT} — so the caller is told what the rule is rather
+ * than only that it has one.
+ */
+export declare function parseLimit(value: unknown, min: 0 | 1): PageLimit;
+/**
+ * The value as an array of strings, copied.
+ *
+ * Accepts: `value` — anything; a non-array is refused, as is an array holding
+ * anything but a string. An empty array is valid.
+ *
+ * Returns: a copy of `value`, so a caller changing its own array afterwards
+ * changes nothing this package acts on.
+ *
+ * Throws: `VALIDATION` naming `field`, its message identifying the offending
+ * index. Walked by position rather than `Array.prototype.some`, which skips a
+ * hole in a sparse array instead of visiting it, and copied by position rather
+ * than `Array.prototype.slice`, which carries a hole forward instead of
+ * filling it: unchecked, a hole passed as a string and reached a caller who
+ * declared `string[]`.
+ */
+export declare function parseStringArray(value: unknown, field: string): string[];
+/**
+ * Throw `VALIDATION` unless `value` is an array of strings.
+ *
+ * Accepts: `value` — declared `readonly string[]` for a caller whose types
+ * hold; a non-array is rejected, as is an array holding anything but a
+ * string. An empty array is valid. The rule is {@link parseStringArray}'s;
+ * this form is for a value the caller keeps under its declared type.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field`.
+ */
+export declare function assertStringArray(value: readonly string[], field: string): void;
+/**
+ * Throw `VALIDATION` unless `value` is free of control characters.
+ *
+ * Accepts: `value` — any type, non-strings rejected first by
+ * {@link parseString}. Rejected code points are C0 (`U+0000`–`U+001F`), DEL
+ * (`U+007F`) and C1 (`U+0080`–`U+009F`). The rule is this function's own:
+ * {@link parseKeySegment} applies it to every key segment and identifier by
+ * calling this one, and this form serves a value the caller keeps under its
+ * declared type.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field`.
+ *
+ * Guarantees: an accepted value cannot terminate a log line or open a terminal
+ * escape sequence — neither `ESC` (`U+001B`) nor the single-byte `CSI`
+ * (`U+009B`) survives this rule. Identifiers are written into log lines by this
+ * package, and unneutralised output is CWE-117
+ * (https://cwe.mitre.org/data/definitions/117.html).
+ */
 export declare function assertNoControlChars(value: string, field: string): void;
-/** Throw {@link ValidationError} if `value` contains the reserved `separator`. */
-export declare function assertNoSeparator(value: string, separator: string, field: string): void;
-/**
- * Validate a caller-supplied identifier that reaches a DynamoDB key: non-empty,
- * free of the reserved `separator`, and free of control characters. The last
- * rule matters even though DynamoDB itself accepts control characters — an
- * identifier is echoed into logs, so an unvalidated ANSI escape is a
- * log/terminal-injection surface for any app that writes these values out.
- */
-export declare function validateIdentifier(value: string, separator: string, field: string): void;
-/** Throw {@link ValidationError} if nested-array depth exceeds `maxDepth`. */
-export declare function validateArrayMaxDepth(value: Redactable[], field: string, maxDepth: number): void;
-//# sourceMappingURL=primitives.d.ts.map
+/**
+ * Throw `VALIDATION` unless every surrogate in `value` is part of a
+ * pair.
+ *
+ * Accepts: `value` — any type, non-strings rejected first by
+ * {@link parseString}. The rule is this function's own:
+ * {@link parseKeySegment} applies it to every key segment and identifier by
+ * calling this one, and this form serves a value the caller keeps under its
+ * declared type.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field`.
+ *
+ * Guarantees: the mapping from an accepted value to its UTF-8 encoding is
+ * injective. `Buffer.from(value, 'utf8')` replaces a lone surrogate with
+ * U+FFFD, so two values differing only there would encode identically and,
+ * where that encoding is a storage key, address one object.
+ */
+export declare function assertWellFormed(value: string, field: string): void;
+/**
+ * One segment of a key, which may be empty: every rule of
+ * {@link parseIdentifier} except non-blank. The checkpoint namespace is the one
+ * such value — `''` *is* the root namespace — and it is still a segment of both
+ * the sort key and the offloaded object's key, so a lone surrogate or a control
+ * character in it is as damaging as in any other.
+ *
+ * Accepts: `value` — anything. `separator`, `field`, `maxBytes` — as
+ * {@link parseIdentifier}.
+ *
+ * Returns: `value`, typed as a string.
+ *
+ * Throws: `VALIDATION` naming `field`, in this order: string, at most
+ * `maxBytes` of UTF-8, free of `separator`, free of control characters,
+ * well-formed UTF-16.
+ */
+export declare function parseKeySegment(value: unknown, separator: string, field: string, maxBytes: number): string;
+/**
+ * The value as a caller-supplied identifier that reaches a DynamoDB key or an
+ * S3 object key, checked.
+ *
+ * Accepts: `value` — any type. `separator`, `field`, `maxBytes` — as the rules
+ * below.
+ *
+ * Returns: `value`, typed as a string. The caller's parser brands it.
+ *
+ * Throws: `VALIDATION` naming `field`. The rules apply in this order, and
+ * the order is part of the contract because a caller branches on which one
+ * failed: string, non-blank, at most `maxBytes` of UTF-8, free of `separator`,
+ * free of control characters, well-formed UTF-16.
+ *
+ * Guarantees: every guarantee of {@link assertNoControlChars} and
+ * {@link assertWellFormed} holds for an accepted value, and it composes into a
+ * key segment without escaping.
+ *
+ * Not guaranteed, and deliberately so: an accepted identifier is **not**
+ * normalised, and Unicode format characters (`Cf` — `U+200B` ZERO WIDTH SPACE,
+ * `U+200C`/`U+200D` the zero-width non-joiner and joiner, `U+FEFF`, `U+202E`
+ * RIGHT-TO-LEFT OVERRIDE) and the separators `U+2028`/`U+2029` are all
+ * accepted. Two facts make that safe, and one makes it necessary.
+ *
+ * It is safe because none of them can produce a collision. DynamoDB orders and
+ * compares strings by their UTF-8 bytes, and {@link assertWellFormed} has
+ * already made the mapping from an accepted identifier to those bytes
+ * injective — so two identifiers differing anywhere address two different
+ * rows. An identifier that reaches an S3 key is base64url-encoded on the way
+ * (`encodeKeyPart`), so none of these characters appears in a key at all. What
+ * one actually costs is a log line, a terminal or a console that renders two
+ * distinct identifiers alike: confusion for a reader, not a row either of them
+ * can reach. Terminal escapes and line breaks, which *are* an injection rather
+ * than a rendering, are refused by {@link assertNoControlChars}.
+ *
+ * It is necessary because refusing `Cf` would refuse ordinary text rather than
+ * hostile text. `U+200C` and `U+200D` carry meaning in Persian, Hindi and the
+ * Indic scripts — the Persian for "goes" is spelled with a `U+200C` — and
+ * `U+200D` is what joins the code points of every multi-person emoji. A rule
+ * against `Cf` would reject a `thread_id` or a store `key` taken from ordinary
+ * user text, in a package whose identifiers are the caller's own.
+ *
+ * Normalising would be worse than breaking: `NFC` folds `e` + `U+0301` onto
+ * `U+00E9`, so a row written under one form would afterwards be addressed
+ * under the other and the caller's data would stop being found. That is silent
+ * loss on upgrade, bought with a rendering nicety. A caller who wants either
+ * rule can apply it to its own identifiers before passing them.
+ */
+export declare function parseIdentifier(value: unknown, separator: string, field: string, maxBytes: number): string;
+export {};