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

package/dist/shared/logging/truncate.js

@@ -0,0 +1,231 @@
+"use strict";
+/**
+ * Hides how much of an unchecked string a line may quote.
+ *
+ * A log line or public error message that quotes a string this package did
+ * not length-check passes it through here. The caps for an identifier, for a
+ * relayed cause's prose and for a list of labels, and the mark that states a
+ * cut value's real length, are chosen here, so a call site says what kind of
+ * value it quotes and never how many characters it keeps.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RELAYED_MESSAGE_CHARS = exports.MAX_LOGGED_LABELS = exports.MAX_LOGGED_VALUE_CHARS = void 0;
+exports.truncateForLog = truncateForLog;
+exports.truncateRelayedText = truncateRelayedText;
+exports.truncateLabelsForLog = truncateLabelsForLog;
+/**
+ * Characters of an unchecked string one log line or one public error message
+ * carries, past which it is cut and marked with its real length.
+ *
+ * Most of what these lines quote is a row's sort key or an offloaded object's
+ * S3 key, so the service already caps each at 1024 bytes — the cost is not one
+ * long line but many. `list: skipped a row that is not a checkpoint meta item`
+ * and `left a foreign row in place` fire once per row, and those passes walk a
+ * whole partition, up to `MAX_TOTAL_ROWS_IN_MEMORY`
+ * (`src/shared/dynamodb/paginate.ts`) rows: one call on a shared table could
+ * write megabytes of log. A consumer's `VectorBackend` carries no such service
+ * cap at all.
+ *
+ * 256 is `MAX_KEY_SEGMENT_BYTES` (`src/shared/dynamodb/table-schema.ts`), this
+ * package's own budget for one identifier inside a key, so any key composed
+ * from identifiers it validated is quoted whole in the common case and only a
+ * foreign row, a hand-written one or a backend's own answer — exactly the
+ * cases these lines report — is cut. Nothing is lost by cutting: the line's
+ * job is to say which row to go and look at, and the row holds the rest.
+ */
+exports.MAX_LOGGED_VALUE_CHARS = 256;
+/**
+ * Labels of an unchecked `string[]` one log line or one public error message
+ * carries, past which the rest are dropped and the real depth is stated.
+ *
+ * An array is two unbounded things — how many labels there are and how long
+ * each one is — so a bound on the labels alone is not a bound: a backend
+ * answering with one label of a megabyte and one answering with a million
+ * labels of a character cost the same line. {@link MAX_LOGGED_VALUE_CHARS}
+ * covers the first, this covers the second.
+ *
+ * 8 is a budget rather than a rule about namespaces: a store namespace is a
+ * path, what identifies which path is its leading labels, and every namespace
+ * this package's own documentation forms is two or three deep. The marker
+ * states the depth it really had, so a deeper one is cut without being
+ * misreported.
+ *
+ * A `namespace` and `key` pair that passed `parseStoreAddress` needs none of
+ * this and goes in whole: that check measures the sort key they *compose*, so
+ * it bounds how many labels there are as well as how long each one is. A
+ * search or listing **prefix** passes no such check — nothing composes it into
+ * a key — so its depth is unchecked however carefully each label was checked,
+ * and a backend's own answer is unchecked in both.
+ */
+exports.MAX_LOGGED_LABELS = 8;
+/**
+ * Characters of a relayed *cause's* text one public error message or one log
+ * line carries, past which it is cut and marked with its real length.
+ *
+ * Its own cap rather than {@link MAX_LOGGED_VALUE_CHARS} because the two bound
+ * different things. That one bounds an **identifier** — a sort key, an S3
+ * object key, a namespace label — and 256 is this package's own budget for one
+ * identifier inside a key, so a value past it is already abnormal and the line
+ * only has to say which row to go and look at. This one bounds **prose**: the
+ * sentence an AWS SDK error, a consumer's `VectorBackend` or a caller's own
+ * `serde` wrote to explain a failure, which `redactedMessage` relays into
+ * `err.message`. Cutting that at an identifier's budget would throw away the
+ * half of a diagnostic that says what to do about it, and a diagnostic is the
+ * entire value of relaying it at all.
+ *
+ * 1024 is measured against the longest text this package actually relays: an
+ * IAM `AccessDenied`, which names the calling principal's ARN, the action and
+ * the resource ARN and then says why no policy allows it, runs to the mid
+ * hundreds of characters, and a role ARN with a long path and a session name
+ * pushes it further. 1024 clears that whole, so the case an operator most
+ * needs to read arrives intact.
+ *
+ * What it is *for* is the other direction. `redactedMessage` also relays a
+ * **caller's own** thrown error — a `serde` refusing a value, a `vectorBackend`
+ * rejecting a query — whose length the caller controls entirely, and those
+ * messages are quoted once per row on paths that walk a whole prefix or table.
+ * Unbounded, one such error fills a log; at 1024 a thousand of them are a
+ * megabyte rather than an unbounded amount.
+ *
+ * Its own literal at the same value as `MAX_SORT_KEY_BYTES`
+ * (`src/shared/dynamodb/table-schema.ts`) and `MAX_S3_KEY_BYTES`
+ * (`src/shared/codec/s3/config.ts`) rather than an alias of either, for the
+ * reason `LIST_SCAN_WARN_THRESHOLD` (`src/shared/dynamodb/paginate.ts`)
+ * records: aliasing two caps would move one whenever the other is retuned,
+ * and these three answer unrelated questions.
+ */
+exports.MAX_RELAYED_MESSAGE_CHARS = 1024;
+/** True for the high half of a surrogate pair, whose low half follows it. */
+function isHighSurrogate(unit) {
+    return unit >= 0xd800 && unit <= 0xdbff;
+}
+/**
+ * The cut itself, shared by both caps so one value can never be marked twice
+ * with two different lengths.
+ *
+ * `max` is a character count. A value at or under it comes back identical; a
+ * longer one comes back as `max` characters — one fewer when that would split
+ * a surrogate pair — followed by `…(len N)` giving the length it really had.
+ */
+function cutTo(value, max) {
+    if (typeof value !== 'string' || value.length <= max)
+        return value;
+    const last = value.charCodeAt(max - 1);
+    const kept = isHighSurrogate(last) ? max - 1 : max;
+    return `${value.slice(0, kept)}…(len ${value.length})`;
+}
+/**
+ * Bound a string this package did not length-check.
+ *
+ * **The rule, in one sentence:** a string goes through here before a log line
+ * or a public error message quotes it, unless this package composed it from
+ * identifiers it length-checked. Where the string came from does not decide
+ * it — a row, a bucket's own configuration, a consumer's `VectorBackend` and
+ * an object the caller handed in are the same thing here, which is that
+ * nothing bounded them. A caller's `sessionId`, `threadId`, `namespace` and
+ * `key`, and every key built from them, are capped by
+ * `MAX_PARTITION_ID_BYTES`, `MAX_KEY_SEGMENT_BYTES` and `MAX_SORT_KEY_BYTES`
+ * before a request is made, so those go in as they are; a row's own `SK`, an
+ * offloaded object's key, a descriptor's `location`, a backend's `namespace`
+ * and `key`, a lifecycle rule's scope and a stored message's `type` are
+ * bounded by nothing this package ran.
+ *
+ * **It says "or a public error message" for one reason:** one value must not
+ * get two answers. An `s3Key` off a row was cut for the `warn` that reports
+ * refusing to delete the object and quoted whole by the error that refuses to
+ * read it — one package, one value, two answers. An error's text is not the
+ * compatibility surface (the README tells callers to branch on `code`, `name`
+ * and the structured fields, never on text) and the `context` those errors
+ * carry keeps the value whole, so what reads an error as data loses nothing
+ * by this.
+ *
+ * Accepts: `value` — the string as whatever produced it carried it. Declared
+ * `string` because a table's own key attributes always are, and because the
+ * interfaces a consumer implements say so; anything else is returned
+ * untouched rather than coerced or refused, since a report of a value that is
+ * already wrong is the last place to raise a `TypeError` of its own.
+ *
+ * Returns: the value unchanged at or under {@link MAX_LOGGED_VALUE_CHARS}
+ * characters, otherwise that many characters followed by `…(len N)` giving the
+ * length it really had. The mark is what keeps a cut value honest: without it
+ * a truncated key reads as a key that simply ends there.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: a cut never falls between the halves of a surrogate pair, so a
+ * well-formed value stays well-formed. A lone surrogate is what
+ * `assertWellFormed` exists to keep out of this package's strings, and a JSON
+ * log transport rewrites one to U+FFFD without saying so.
+ */
+function truncateForLog(value) {
+    return cutTo(value, exports.MAX_LOGGED_VALUE_CHARS);
+}
+/**
+ * Bound the **prose** of a relayed cause, which takes its own cap.
+ *
+ * {@link truncateForLog} bounds an identifier, where 256 characters is this
+ * package's own budget for one and anything past it is already abnormal. The
+ * text an AWS SDK error, a consumer's `VectorBackend` or a caller's own
+ * `serde` wrote is a sentence rather than a name: cut at an identifier's
+ * budget it loses the half that says what to do, which is the only reason to
+ * relay it. {@link MAX_RELAYED_MESSAGE_CHARS} records what the larger number
+ * is measured against, and why the two differ.
+ *
+ * It has exactly one caller — `redactedMessage`, the funnel every `catch` in
+ * this package goes through — so no call site can get the cap wrong and no
+ * future one has to remember it. That also means a site must not cut the
+ * result again: a second cut marks the length of the first cut's output rather
+ * than of the original, which is the one thing the mark exists to prevent.
+ *
+ * Accepts: `value` — the redacted text. Redaction runs first, so a credential
+ * shape can never be half-cut past the pattern that would have caught it.
+ *
+ * Returns: the value unchanged at or under the cap, otherwise that many
+ * characters followed by `…(len N)`.
+ *
+ * Throws: nothing.
+ */
+function truncateRelayedText(value) {
+    return cutTo(value, exports.MAX_RELAYED_MESSAGE_CHARS);
+}
+/**
+ * Bound a list of labels — a store `namespace`, a list of channel names — the
+ * same rule reaches.
+ *
+ * An array is two unbounded things, how many labels it holds and how long each
+ * one is, so a bound on one of them is not a bound. {@link truncateForLog}
+ * covers the labels; the count is covered here.
+ *
+ * A `namespace` and `key` pair that passed `parseStoreAddress` is already
+ * bounded in both — that check measures the sort key they compose — and goes
+ * in whole. A search or listing prefix is not: nothing composes it into a key,
+ * so however carefully each label was checked, how many there are was not.
+ *
+ * The labels stay a list rather than being joined into one string, for two
+ * reasons. A structured transport already carries the field as a list and the
+ * README's Logging table documents it as one, so joining would change the
+ * shape of a line rather than only its size. And a label nothing validated may
+ * hold the `#` a join would put between labels, so a joined line cannot say
+ * whether the backend answered with one label or with two — which is the very
+ * thing these lines report.
+ *
+ * Accepts: `labels` — as the row, the backend or the caller gave it. Declared
+ * `string[]` because that is what the interfaces say; anything else is
+ * returned untouched, for the reason {@link truncateForLog} gives, and that
+ * case is reached rather than defensive — a `namespace` that is not an array
+ * is one of the things `parseStoreAddress` refuses, and the line reporting the
+ * refusal quotes what was refused.
+ *
+ * Returns: at most {@link MAX_LOGGED_LABELS} labels, each bounded by
+ * {@link truncateForLog}, with one further label reading `…(len N)` when some
+ * were dropped, giving the depth the list really had. A list within both
+ * bounds comes back as an equal list.
+ *
+ * Throws: nothing.
+ */
+function truncateLabelsForLog(labels) {
+    if (!Array.isArray(labels))
+        return labels;
+    const kept = labels.slice(0, exports.MAX_LOGGED_LABELS).map((label) => truncateForLog(label));
+    return labels.length > exports.MAX_LOGGED_LABELS ? [...kept, `…(len ${labels.length})`] : kept;
+}

package/dist/shared/options.d.ts

@@ -1,7 +1,17 @@
-import type { DynamoDBClient, DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
-import type { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
+/**
+ * Hides which options every adapter shares.
+ *
+ * The table, the client, the ttl, the logger, the retry policy, the recency
+ * index, the read concurrency, the codec options and per-call cancellation are
+ * declared once here, so the checkpointer, the store and the history accept
+ * the same keys with the same meaning, and an adapter-wide option is added in
+ * one place. This module holds their types only; checking them is elsewhere.
+ */
+import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
 import type { CompressionConfig } from './codec/compression';
 import type { S3OffloadConfig } from './codec/s3/config';
+import type { DynamoDBDocumentLike } from './dynamodb/client';
+import type { RetryPolicy } from './dynamodb/retry';
 import type { Logger } from './logging/logger';
 import type { TtlOption } from './validation/ttl';
 /**
@@ -12,15 +22,53 @@ export interface BaseAdapterOptions {
     /** DynamoDB table name. */
     tableName: string;
     /** Pre-built DocumentClient to reuse; when set, the adapter does not own it. */
-    client?: DynamoDBDocument;
-    /** Config used to build a client when `client` is not provided. */
+    client?: DynamoDBDocumentLike;
+    /** The config a client is built from when `client` is not provided. */
     clientConfig?: DynamoDBClientConfig;
-    /** Factory seam for constructing the underlying client (testing). */
-    createClient?: (config: DynamoDBClientConfig) => DynamoDBClient;
     /** Optional time-to-live applied to written items. */
     ttl?: TtlOption;
     /** Optional per-instance logger (defaults to a silent logger). */
     logger?: Logger;
+    /** Retry budget and backoff for every DynamoDB call (see the README "Retries and backoff"). */
+    retry?: RetryPolicy;
+    /**
+     * Index partitions per adapter in the recency index (GSI1), default 8.
+     *
+     * Rows carry the index attributes whether or not the table defines the
+     * index, so enabling it later needs no rewrite of new rows — only a backfill
+     * of the old ones. The value is fixed at table creation: changing it changes
+     * every row's shard, so an existing index must be backfilled again.
+     *
+     * A single index partition per adapter would concentrate every listing on
+     * one partition, which is worse than the table scan it replaces.
+     */
+    indexShards?: number;
+    /**
+     * Name of the recency index (a GSI on `gsi1pk`/`gsi1sk`) on this table.
+     *
+     * Opt-in on purpose: whether the table carries the index is deployment
+     * configuration the operator knows, and probing for it would spend a failed
+     * request per process to find out. Naming it switches two listings that
+     * would otherwise scan the whole table onto a read of the index, newest
+     * first: `history.listSessions`, which pages it by cursor, and a
+     * `saver.list` without a `thread_id`, which streams it and takes no cursor.
+     * Leaving it unset keeps both on the table scan, so the index can be created
+     * and backfilled before any adapter reads it.
+     */
+    indexName?: string;
+    /**
+     * How many payloads a single call decodes at once, default 8.
+     *
+     * It is the multiplier on this package's memory ceiling, which is
+     * `readConcurrency × (s3.maxDownloadBytes + compression.maxDecompressedBytes)`
+     * — a downloaded object and its decompressed form are both resident while a
+     * payload is decoded, and that much can be in flight for each concurrent
+     * decode. Lower it on a small container; raising it trades memory for
+     * latency on reads that fetch many offloaded payloads.
+     *
+     * It also bounds how many recency-index shards one listing queries at once.
+     */
+    readConcurrency?: number;
 }
 /** Options enabling payload compression and/or S3 offloading. */
 export interface CodecOptions {
@@ -29,4 +77,8 @@ export interface CodecOptions {
     /** S3 offload configuration for payloads over DynamoDB's item limit. */
     s3?: S3OffloadConfig;
 }
-//# sourceMappingURL=options.d.ts.map
+/** Per-call cancellation for the long-running adapter methods. */
+export interface CancelOptions {
+    /** Aborting it rejects the call with an `ABORTED` error at the next wait. */
+    signal?: AbortSignal;
+}

package/dist/shared/options.js

@@ -1,3 +1,11 @@
 "use strict";
+/**
+ * Hides which options every adapter shares.
+ *
+ * The table, the client, the ttl, the logger, the retry policy, the recency
+ * index, the read concurrency, the codec options and per-call cancellation are
+ * declared once here, so the checkpointer, the store and the history accept
+ * the same keys with the same meaning, and an adapter-wide option is added in
+ * one place. This module holds their types only; checking them is elsewhere.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=options.js.map

package/dist/shared/ulid.d.ts

@@ -1,10 +1,80 @@
 /**
- * Build a monotonic ULID generator: lexicographically sortable 26-char ids
- * whose first 10 chars encode the millisecond timestamp. Ids strictly increase
- * even when the clock regresses or the same-millisecond random space overflows:
- * any non-advancing clock reuses the last timestamp and increments the random
- * component, carrying into the timestamp on overflow. `now`/`rng` are seams for
- * deterministic tests.
+ * Hides how a sortable, unique id is made from the clock and random bytes.
+ *
+ * A caller gets ids whose byte order is their creation order, and a prefix
+ * that bounds every id from a given millisecond, without knowing the alphabet,
+ * the width of the time field or where the randomness comes from. One
+ * generator's ids strictly increase whatever the clock does, and
+ * `ulidTimePrefix` refuses a millisecond the encoding cannot hold rather than
+ * wrapping it, so a caller building a bound from a raw millisecond cannot be
+ * handed a silently wrong one.
+ */
+/**
+ * One past the last millisecond ten base-32 characters can hold: `32^10`,
+ * which is `2^50`, and lands in the year 37648. Derived rather than written
+ * down, so widening {@link TIME_CHARS} moves the rule with it.
+ */
+export declare const ULID_TIME_RANGE_MS: number;
+/**
+ * A CSPRNG-backed `rng` seam.
+ *
+ * Accepts: nothing. Each returned generator owns its own pool.
+ *
+ * Returns: a function yielding uniform values in `[0, 1)`, one byte per call,
+ * refilling from `crypto.randomBytes` every {@link RNG_POOL_BYTES} — so a burst
+ * of ids costs one syscall per 256 digits rather than one per digit.
+ *
+ * Throws: whatever `crypto.randomBytes` throws when the platform has no entropy.
+ *
+ * Guarantees: a digit drawn as `floor(rng() * 32)` is uniform over 0..31 —
+ * 256 is a whole multiple of 32, so there is no modulo bias. `Math.random`
+ * would order and disambiguate just as well but is not a cryptographically
+ * secure source, which the ULID spec asks for in identifier generation.
+ */
+export declare function secureRng(): () => number;
+/**
+ * The 10 time characters every ULID generated at `timeMs` starts with.
+ *
+ * Accepts: `timeMs` — epoch milliseconds inside `[0, {@link
+ * ULID_TIME_RANGE_MS})`, which is every instant the ten characters can encode.
+ *
+ * Returns: the prefix, usable as a sort-key bound — every id from that
+ * millisecond onward sorts at or after it, every earlier id before it.
+ *
+ * Throws: `VALIDATION` for a millisecond outside the range, naming no field:
+ * no caller-supplied option is at fault here, and the rule a caller meets is
+ * `parseMessageWindow`'s, which names `before`. This guard is the invariant
+ * underneath it, so no second caller can rebuild the bound that broke.
+ *
+ * Guarantees: exactly ten characters, all of them from the ULID alphabet.
+ * Neither held before. A negative millisecond took a negative remainder into
+ * the alphabet and yielded `undefined` per character, so the bound read
+ * `undefinedundefined…` — which sorts *above* every real id, since `u` and `d`
+ * are both above `Z` — and a window asking for messages before 1969 matched
+ * the whole conversation instead of none of it. A millisecond at or past the
+ * range wrapped to `0000000000` and matched nothing at all. Both are garbage
+ * indistinguishable from a real answer, so both are refused rather than
+ * clamped: clamping would hand back the same wrong page under a different
+ * name.
+ */
+export declare function ulidTimePrefix(timeMs: number): string;
+/**
+ * A monotonic ULID generator.
+ *
+ * Accepts: `now` — epoch milliseconds, default `Date.now`. `rng` — values in
+ * `[0, 1)`, default {@link secureRng}. Both are seams for deterministic tests.
+ *
+ * Returns: a function yielding lexicographically sortable 26-character ids
+ * whose first 10 characters encode the millisecond.
+ *
+ * Throws: whatever `rng` throws.
+ *
+ * Guarantees: ids from **one** generator strictly increase, whatever the clock
+ * does. A clock that advances starts a fresh random component; a clock that
+ * stalls or regresses reuses the last timestamp and increments that component;
+ * an increment that exhausts all 16 digits carries into the timestamp and draws
+ * fresh digits. Two generators — two processes, or two adapter instances —
+ * order only by their wall clocks at millisecond precision, so a lagging clock
+ * can sort a later id before an earlier one.
  */
 export declare function createUlidFactory(now?: () => number, rng?: () => number): () => string;
-//# sourceMappingURL=ulid.d.ts.map

package/dist/shared/ulid.js

@@ -1,10 +1,63 @@
 "use strict";
+/**
+ * Hides how a sortable, unique id is made from the clock and random bytes.
+ *
+ * A caller gets ids whose byte order is their creation order, and a prefix
+ * that bounds every id from a given millisecond, without knowing the alphabet,
+ * the width of the time field or where the randomness comes from. One
+ * generator's ids strictly increase whatever the clock does, and
+ * `ulidTimePrefix` refuses a millisecond the encoding cannot hold rather than
+ * wrapping it, so a caller building a bound from a raw millisecond cannot be
+ * handed a silently wrong one.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ULID_TIME_RANGE_MS = void 0;
+exports.secureRng = secureRng;
+exports.ulidTimePrefix = ulidTimePrefix;
 exports.createUlidFactory = createUlidFactory;
+const node_crypto_1 = require("node:crypto");
+const errors_1 = require("./errors/errors");
 const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
 const ENCODING_LEN = 32;
 const TIME_CHARS = 10;
 const RANDOM_CHARS = 16;
+/**
+ * One past the last millisecond ten base-32 characters can hold: `32^10`,
+ * which is `2^50`, and lands in the year 37648. Derived rather than written
+ * down, so widening {@link TIME_CHARS} moves the rule with it.
+ */
+exports.ULID_TIME_RANGE_MS = ENCODING_LEN ** TIME_CHARS;
+/** Bytes drawn per refill of the {@link secureRng} pool: 16 ids per syscall. */
+const RNG_POOL_BYTES = 256;
+/**
+ * A CSPRNG-backed `rng` seam.
+ *
+ * Accepts: nothing. Each returned generator owns its own pool.
+ *
+ * Returns: a function yielding uniform values in `[0, 1)`, one byte per call,
+ * refilling from `crypto.randomBytes` every {@link RNG_POOL_BYTES} — so a burst
+ * of ids costs one syscall per 256 digits rather than one per digit.
+ *
+ * Throws: whatever `crypto.randomBytes` throws when the platform has no entropy.
+ *
+ * Guarantees: a digit drawn as `floor(rng() * 32)` is uniform over 0..31 —
+ * 256 is a whole multiple of 32, so there is no modulo bias. `Math.random`
+ * would order and disambiguate just as well but is not a cryptographically
+ * secure source, which the ULID spec asks for in identifier generation.
+ */
+function secureRng() {
+    let pool = Buffer.alloc(0);
+    let offset = 0;
+    return () => {
+        if (offset >= pool.length) {
+            pool = (0, node_crypto_1.randomBytes)(RNG_POOL_BYTES);
+            offset = 0;
+        }
+        const byte = pool[offset];
+        offset += 1;
+        return byte / 256;
+    };
+}
 function encodeTime(timeMs) {
     let remaining = Math.floor(timeMs);
     let out = '';
@@ -14,6 +67,38 @@ function encodeTime(timeMs) {
     }
     return out;
 }
+/**
+ * The 10 time characters every ULID generated at `timeMs` starts with.
+ *
+ * Accepts: `timeMs` — epoch milliseconds inside `[0, {@link
+ * ULID_TIME_RANGE_MS})`, which is every instant the ten characters can encode.
+ *
+ * Returns: the prefix, usable as a sort-key bound — every id from that
+ * millisecond onward sorts at or after it, every earlier id before it.
+ *
+ * Throws: `VALIDATION` for a millisecond outside the range, naming no field:
+ * no caller-supplied option is at fault here, and the rule a caller meets is
+ * `parseMessageWindow`'s, which names `before`. This guard is the invariant
+ * underneath it, so no second caller can rebuild the bound that broke.
+ *
+ * Guarantees: exactly ten characters, all of them from the ULID alphabet.
+ * Neither held before. A negative millisecond took a negative remainder into
+ * the alphabet and yielded `undefined` per character, so the bound read
+ * `undefinedundefined…` — which sorts *above* every real id, since `u` and `d`
+ * are both above `Z` — and a window asking for messages before 1969 matched
+ * the whole conversation instead of none of it. A millisecond at or past the
+ * range wrapped to `0000000000` and matched nothing at all. Both are garbage
+ * indistinguishable from a real answer, so both are refused rather than
+ * clamped: clamping would hand back the same wrong page under a different
+ * name.
+ */
+function ulidTimePrefix(timeMs) {
+    if (!(timeMs >= 0 && timeMs < exports.ULID_TIME_RANGE_MS)) {
+        throw (0, errors_1.validationError)(`a ULID time prefix covers epoch milliseconds 0 to ${exports.ULID_TIME_RANGE_MS - 1} (the year ` +
+            `37648); ${timeMs} is outside it and has no ten-character encoding`);
+    }
+    return encodeTime(timeMs);
+}
 function randomDigits(rng) {
     const digits = [];
     for (let i = 0; i < RANDOM_CHARS; i++) {
@@ -33,14 +118,25 @@ function incrementDigits(digits) {
     return { digits: next, overflowed: true };
 }
 /**
- * Build a monotonic ULID generator: lexicographically sortable 26-char ids
- * whose first 10 chars encode the millisecond timestamp. Ids strictly increase
- * even when the clock regresses or the same-millisecond random space overflows:
- * any non-advancing clock reuses the last timestamp and increments the random
- * component, carrying into the timestamp on overflow. `now`/`rng` are seams for
- * deterministic tests.
+ * A monotonic ULID generator.
+ *
+ * Accepts: `now` — epoch milliseconds, default `Date.now`. `rng` — values in
+ * `[0, 1)`, default {@link secureRng}. Both are seams for deterministic tests.
+ *
+ * Returns: a function yielding lexicographically sortable 26-character ids
+ * whose first 10 characters encode the millisecond.
+ *
+ * Throws: whatever `rng` throws.
+ *
+ * Guarantees: ids from **one** generator strictly increase, whatever the clock
+ * does. A clock that advances starts a fresh random component; a clock that
+ * stalls or regresses reuses the last timestamp and increments that component;
+ * an increment that exhausts all 16 digits carries into the timestamp and draws
+ * fresh digits. Two generators — two processes, or two adapter instances —
+ * order only by their wall clocks at millisecond precision, so a lagging clock
+ * can sort a later id before an earlier one.
  */
-function createUlidFactory(now = Date.now, rng = Math.random) {
+function createUlidFactory(now = Date.now, rng = secureRng()) {
     let lastTime = -1;
     let lastRandom = [];
     return () => {
@@ -62,4 +158,3 @@ function createUlidFactory(now = Date.now, rng = Math.random) {
         return encodeTime(lastTime) + lastRandom.map((digit) => ENCODING[digit]).join('');
     };
 }
-//# sourceMappingURL=ulid.js.map