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

package/dist/checkpointer/internal/checkpoint-write-verify.d.ts

@@ -1,24 +0,0 @@
-import type { CheckpointMetaItem, CheckpointPayloadItem } from '../types';
-import type { CheckpointerContext } from './setup';
-/** What a post-failure verification read could establish about a put. */
-export type CheckpointWriteVerdict = 'landed' | 'not-landed' | 'unverified';
-/**
- * Read one of the two rows back after the META+PAYLOAD transaction failed and
- * report what that failure actually did — never assuming it did nothing.
- *
- * No rejection is proof of a non-commit: `withDynamoDBRetry` re-issues a
- * transaction whose response was lost, and the re-issues can time out at the
- * transport without reaching DynamoDB, so the budget is spent on a
- * `RetryExhaustedError` while the rows are committed. Deleting the uploads on
- * that basis stranded the head checkpoint of a thread on a `NoSuchKey`.
- *
- * Keys are nonced per call (see `buildCheckpointItems`), so "the row holds
- * this attempt's key" is the same statement as "this attempt's write is
- * live". When neither descriptor is offloaded there is nothing to delete, so
- * the answer is simply "safe to clean up", a no-op for the caller.
- *
- * A read failure establishes nothing; the caller then leaks one object at
- * worst (reclaimed by `ensureS3LifecycleRule`) rather than deleting one a live
- * row may point at — the same trade `store/internal/persist.ts` makes.
- */
-export declare function verifyCheckpointLanded(context: CheckpointerContext, meta: CheckpointMetaItem, payload: CheckpointPayloadItem): Promise<CheckpointWriteVerdict>;

package/dist/checkpointer/internal/checkpoint-write-verify.js

@@ -1,67 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifyCheckpointLanded = verifyCheckpointLanded;
-const codec_1 = require("../../shared/codec/codec");
-const retry_1 = require("../../shared/dynamodb/retry");
-/** The S3 key an offloaded descriptor points at, or undefined for inline/absent. */
-function offloadedKey(descriptor) {
-    return descriptor?.location === codec_1.PayloadLocation.S3 ? descriptor.s3Key : undefined;
-}
-/**
- * Pick the row carrying an offloaded descriptor. The META and PAYLOAD rows
- * commit in one transaction, so one of them is enough; with neither offloaded
- * there is nothing to protect and no read to spend.
- */
-function chooseProbe(meta, payload) {
-    const metaKey = offloadedKey(meta.metadata);
-    if (metaKey !== undefined) {
-        return { key: { PK: meta.PK, SK: meta.SK }, attribute: 'metadata', expected: metaKey };
-    }
-    const payloadKey = offloadedKey(payload.checkpoint);
-    if (payloadKey !== undefined) {
-        return {
-            key: { PK: payload.PK, SK: payload.SK },
-            attribute: 'checkpoint',
-            expected: payloadKey,
-        };
-    }
-    return undefined;
-}
-/**
- * Read one of the two rows back after the META+PAYLOAD transaction failed and
- * report what that failure actually did — never assuming it did nothing.
- *
- * No rejection is proof of a non-commit: `withDynamoDBRetry` re-issues a
- * transaction whose response was lost, and the re-issues can time out at the
- * transport without reaching DynamoDB, so the budget is spent on a
- * `RetryExhaustedError` while the rows are committed. Deleting the uploads on
- * that basis stranded the head checkpoint of a thread on a `NoSuchKey`.
- *
- * Keys are nonced per call (see `buildCheckpointItems`), so "the row holds
- * this attempt's key" is the same statement as "this attempt's write is
- * live". When neither descriptor is offloaded there is nothing to delete, so
- * the answer is simply "safe to clean up", a no-op for the caller.
- *
- * A read failure establishes nothing; the caller then leaks one object at
- * worst (reclaimed by `ensureS3LifecycleRule`) rather than deleting one a live
- * row may point at — the same trade `store/internal/persist.ts` makes.
- */
-async function verifyCheckpointLanded(context, meta, payload) {
-    const probe = chooseProbe(meta, payload);
-    if (!probe)
-        return 'not-landed';
-    try {
-        const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
-            TableName: context.tableName,
-            Key: probe.key,
-            ConsistentRead: true,
-            ProjectionExpression: '#d',
-            ExpressionAttributeNames: { '#d': probe.attribute },
-        }), context.retry);
-        const stored = result.Item?.[probe.attribute];
-        return offloadedKey(stored) === probe.expected ? 'landed' : 'not-landed';
-    }
-    catch {
-        return 'unverified';
-    }
-}

package/dist/checkpointer/internal/configurable.d.ts

@@ -1,12 +0,0 @@
-import type { RunnableConfig } from '@langchain/core/runnables';
-/** The thread/namespace/checkpoint identifiers extracted from a config. */
-export interface ResolvedConfigurable {
-    threadId: string;
-    checkpointNs: string;
-    checkpointId?: string;
-}
-/**
- * Narrow `RunnableConfig.configurable` to the identifiers the saver needs,
- * defaulting the namespace to empty and validating that a thread id is present.
- */
-export declare function readConfigurable(config: RunnableConfig): ResolvedConfigurable;

package/dist/checkpointer/internal/configurable.js

@@ -1,24 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.readConfigurable = readConfigurable;
-const validation_1 = require("./validation");
-/**
- * Narrow `RunnableConfig.configurable` to the identifiers the saver needs,
- * defaulting the namespace to empty and validating that a thread id is present.
- */
-function readConfigurable(config) {
-    const configurable = (config.configurable ?? {});
-    (0, validation_1.validateThreadId)(configurable.thread_id);
-    const checkpointNs = configurable.checkpoint_ns ?? '';
-    (0, validation_1.validateCheckpointNs)(checkpointNs);
-    /**
-     * `null`, `''` and the legacy `thread_ts` alias resolve the way the reference's
-     * `getCheckpointId` does: a falsy id addresses the latest checkpoint rather
-     * than failing a config that was built from JSON or ported from another saver.
-     */
-    const rawId = configurable.checkpoint_id ?? configurable.thread_ts;
-    const checkpointId = rawId ? rawId : undefined;
-    if (checkpointId !== undefined)
-        (0, validation_1.validateCheckpointId)(checkpointId);
-    return { threadId: configurable.thread_id, checkpointNs, checkpointId };
-}

package/dist/checkpointer/internal/fetch.d.ts

@@ -1,19 +0,0 @@
-import type { CheckpointPendingWrite } from '@langchain/langgraph-checkpoint';
-import type { CheckpointMetaItem, CheckpointPayloadItem } from '../types';
-import type { CheckpointerContext } from './setup';
-/** Per-read options for the payload and writes reads. */
-export interface ReadOptions {
-    signal?: AbortSignal;
-    /** `false` for bulk reads (`list`) that trade read-your-writes for half the read cost. */
-    consistent?: boolean;
-}
-/**
- * Fetch the target META item: by id when given, else the newest in the
- * namespace. The newest-first read pages one row at a time past any foreign
- * row until it finds a real checkpoint.
- */
-export declare function fetchTargetMeta(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId?: string, signal?: AbortSignal): Promise<CheckpointMetaItem | undefined>;
-/** Fetch the PAYLOAD item for a checkpoint. */
-export declare function fetchPayload(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId: string, read?: ReadOptions): Promise<CheckpointPayloadItem | undefined>;
-/** Fetch and decode every pending write for a checkpoint, in write order. */
-export declare function fetchPendingWrites(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId: string, read?: ReadOptions): Promise<CheckpointPendingWrite[]>;

package/dist/checkpointer/internal/fetch.js

@@ -1,88 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.fetchTargetMeta = fetchTargetMeta;
-exports.fetchPayload = fetchPayload;
-exports.fetchPendingWrites = fetchPendingWrites;
-const clock_1 = require("../../shared/clock");
-const constants_1 = require("../../shared/constants");
-const expiry_1 = require("../../shared/dynamodb/expiry");
-const paginate_1 = require("../../shared/dynamodb/paginate");
-const retry_1 = require("../../shared/dynamodb/retry");
-const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
-const item_reader_1 = require("./item-reader");
-const keys_1 = require("./keys");
-const query_1 = require("./query");
-/**
- * Fetch the target META item: by id when given, else the newest in the
- * namespace. The newest-first read pages one row at a time past any foreign
- * row until it finds a real checkpoint.
- */
-async function fetchTargetMeta(context, threadId, checkpointNs, checkpointId, signal) {
-    /** Expired rows are absent to every reader, however long DynamoDB's sweep lags. */
-    const now = (0, clock_1.nowSeconds)();
-    if (checkpointId !== undefined) {
-        const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
-            TableName: context.tableName,
-            Key: { PK: (0, keys_1.partitionKey)(threadId), SK: (0, keys_1.metaSortKey)(checkpointNs, checkpointId) },
-            ConsistentRead: true,
-        }), (0, retry_policy_1.retryFor)(context, signal));
-        const meta = (0, item_reader_1.narrowHead)(context, result.Item);
-        return meta && !(0, expiry_1.isExpiredRow)(meta, now) ? meta : undefined;
-    }
-    const params = (0, query_1.beginsWithQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), (0, keys_1.metaSortKeyPrefix)(checkpointNs), {
-        limit: 1,
-        consistent: true,
-    });
-    const rows = (0, paginate_1.paginateQuery)({
-        retry: (0, retry_policy_1.retryFor)(context, signal),
-        signal,
-        client: context.client,
-        params: (0, expiry_1.withoutExpired)(params, now),
-        maxItems: Number.POSITIVE_INFINITY,
-        maxIterations: Number.POSITIVE_INFINITY,
-    });
-    for await (const raw of rows) {
-        const meta = (0, item_reader_1.narrowHead)(context, raw);
-        if (meta && !(0, expiry_1.isExpiredRow)(meta, now))
-            return meta;
-    }
-    return undefined;
-}
-/** Fetch the PAYLOAD item for a checkpoint. */
-async function fetchPayload(context, threadId, checkpointNs, checkpointId, read = {}) {
-    const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
-        TableName: context.tableName,
-        Key: { PK: (0, keys_1.partitionKey)(threadId), SK: (0, keys_1.payloadSortKey)(checkpointNs, checkpointId) },
-        ConsistentRead: read.consistent ?? true,
-    }), (0, retry_policy_1.retryFor)(context, read.signal));
-    return result.Item;
-}
-/** Fetch and decode every pending write for a checkpoint, in write order. */
-async function fetchPendingWrites(context, threadId, checkpointNs, checkpointId, read = {}) {
-    const params = (0, query_1.beginsWithQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), (0, keys_1.writeSortKeyPrefix)(checkpointNs, checkpointId), { ascending: true, consistent: read.consistent ?? true });
-    /**
-     * Unbounded: the read must be complete to be correct, and a Send fan-out
-     * retried with a changed write order leaves superseded rows behind that
-     * count toward any cap. Past the warning threshold the read still succeeds,
-     * but an operator is told the checkpoint is unusually heavy.
-     */
-    const items = [];
-    for await (const item of (0, paginate_1.paginateQuery)({
-        retry: (0, retry_policy_1.retryFor)(context, read.signal),
-        signal: read.signal,
-        client: context.client,
-        params,
-        maxItems: Number.POSITIVE_INFINITY,
-        maxIterations: Number.POSITIVE_INFINITY,
-    })) {
-        items.push(item);
-    }
-    if (items.length >= constants_1.LIST_SCAN_WARN_THRESHOLD) {
-        context.logger.warn('getTuple: a checkpoint carries very many pending-write rows; the read is complete but slow', {
-            threadId,
-            checkpointId,
-            rows: items.length,
-        });
-    }
-    return (0, item_reader_1.toPendingWrites)(context, items, threadId);
-}

package/dist/checkpointer/internal/filter-match.d.ts

@@ -1,13 +0,0 @@
-/** A JSON-comparable value used in metadata filters. */
-export type FilterValue = string | number | boolean | null | FilterValue[] | {
-    [key: string]: FilterValue;
-};
-/**
- * True when every key in `filter` is present in `metadata` with a deeply equal
- * value. Equality is structural and key-order-independent for nested objects,
- * order-significant for arrays, and type-strict (no `3` vs `'3'` coercion). An
- * empty filter matches everything. Only own properties count: a filter on
- * `constructor` or `toString` compares against nothing, not against the
- * prototype's function, the same rule the store's filter applies.
- */
-export declare function matchesFilter(metadata: Record<string, FilterValue>, filter: Record<string, FilterValue>): boolean;

package/dist/checkpointer/internal/filter-match.js

@@ -1,15 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.matchesFilter = matchesFilter;
-const node_util_1 = require("node:util");
-/**
- * True when every key in `filter` is present in `metadata` with a deeply equal
- * value. Equality is structural and key-order-independent for nested objects,
- * order-significant for arrays, and type-strict (no `3` vs `'3'` coercion). An
- * empty filter matches everything. Only own properties count: a filter on
- * `constructor` or `toString` compares against nothing, not against the
- * prototype's function, the same rule the store's filter applies.
- */
-function matchesFilter(metadata, filter) {
-    return Object.entries(filter).every(([key, value]) => (0, node_util_1.isDeepStrictEqual)(Object.hasOwn(metadata, key) ? metadata[key] : undefined, value));
-}

package/dist/checkpointer/internal/item-reader.d.ts

@@ -1,66 +0,0 @@
-import type { Checkpoint, CheckpointMetadata, CheckpointPendingWrite } from '@langchain/langgraph-checkpoint';
-import type { DocItem } from '../../shared/dynamodb/types';
-import type { CheckpointMetaItem, CheckpointPayloadItem, CheckpointWriteItem } from '../types';
-import type { CheckpointerContext } from './setup';
-/**
- * Narrow a raw row to a {@link CheckpointMetaItem}, or `undefined` for a row
- * that merely shares the `META#` sort-key prefix. Replaces an unchecked cast
- * at the one boundary where a row may not have been written by this adapter.
- */
-export declare function narrowMetaItem(raw: DocItem): CheckpointMetaItem | undefined;
-/**
- * Narrow a candidate head row, warning when a row that merely shares the
- * `META#` prefix is not a checkpoint meta item. Returning such a row used to
- * make `assembleTuple` miss its payload and report the thread as empty, so
- * LangGraph started a new run on top of the real history; a foreign row is
- * skipped and logged instead, exactly as `list()` treats it.
- */
-export declare function narrowHead(context: CheckpointerContext, raw: DocItem | undefined): CheckpointMetaItem | undefined;
-/**
- * Decode the checkpoint stored in a PAYLOAD item. `threadId` is the caller's
- * (from the config), never the row's: it scopes which S3 object the row may
- * point at, so it must come from the partition the caller asked for.
- */
-export declare function readCheckpoint(context: CheckpointerContext, item: CheckpointPayloadItem, threadId: string): Promise<Checkpoint>;
-/** Decode the metadata stored in a META item; see {@link readCheckpoint} for `threadId`. */
-export declare function readMetadata(context: CheckpointerContext, item: CheckpointMetaItem, threadId: string): Promise<CheckpointMetadata>;
-/**
- * Drop rows a later `putWrites` call added for a task and channel an earlier
- * call had already committed.
- *
- * A regular write's index is its position in the caller's array, so a retried
- * task whose write mix changed can place an already-committed channel at a
- * second index — a new row, which would replay that channel's value twice. For
- * an accumulating channel (a `messages` add-reducer, a Topic) that
- * double-counts. Every row carries the `writeGroup` of the call that wrote it,
- * which distinguishes that case from a channel a *single* call legitimately
- * wrote more than once (a task emitting two Sends), where both values must
- * survive.
- *
- * Write groups are time-ordered ULIDs, so the smallest one for a `(task,
- * channel)` pair identifies the earliest committed call — first-write-wins,
- * the same rule the write-side guard applies, extended to the case the guard
- * cannot see. Selecting by *order encountered* would not do: rows arrive
- * sorted by index, and a retry emitting fewer writes moves an
- * already-committed channel to a smaller index, where it sorts ahead of the
- * original row and would hand back the later call's value instead. The
- * superseded row stays in DynamoDB and is removed by `deleteThread` or TTL
- * like any other.
- *
- * Identity is `(task, channel, occurrence)`, not `(task, channel)`. Keying on
- * the channel alone treated *any* second row for a channel as a superseding
- * duplicate — including one a retry added at an occurrence no earlier call had
- * ever written, which the write-side guard accepted cleanly. That row was then
- * discarded on read, silently returning fewer values than were written, with
- * `putWrites()` having reported success. For that specific shape — a retry
- * that legitimately emits a channel *more* often than the original call —
- * keeping the occurrence restores the upstream outcome: `MemorySaver` keys
- * first-write-wins on `(taskId, idx)`, so a grown retry keeps both values
- * there too. That is not a claim of parity in general: a retry that reorders
- * or shrinks its writes is still resolved to the earliest call per `(task,
- * channel, occurrence)` as above, which is what keeps an accumulating channel
- * from being double-counted — a case `MemorySaver` does not have to handle.
- */
-export declare function dropSupersededWrites(items: CheckpointWriteItem[]): CheckpointWriteItem[];
-/** Decode WRITE items into `[taskId, channel, value]` pending-write tuples. */
-export declare function toPendingWrites(context: CheckpointerContext, items: CheckpointWriteItem[], threadId: string): Promise<CheckpointPendingWrite[]>;

package/dist/checkpointer/internal/item-reader.js

@@ -1,113 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.narrowMetaItem = narrowMetaItem;
-exports.narrowHead = narrowHead;
-exports.readCheckpoint = readCheckpoint;
-exports.readMetadata = readMetadata;
-exports.dropSupersededWrites = dropSupersededWrites;
-exports.toPendingWrites = toPendingWrites;
-const codec_1 = require("../../shared/codec/codec");
-const concurrency_1 = require("../../shared/concurrency");
-const constants_1 = require("../../shared/constants");
-const item_writer_1 = require("./item-writer");
-/**
- * Narrow a raw row to a {@link CheckpointMetaItem}, or `undefined` for a row
- * that merely shares the `META#` sort-key prefix. Replaces an unchecked cast
- * at the one boundary where a row may not have been written by this adapter.
- */
-function narrowMetaItem(raw) {
-    return typeof raw.checkpointId === 'string' &&
-        typeof raw.checkpointNs === 'string' &&
-        raw.metadata !== undefined
-        ? raw
-        : undefined;
-}
-/**
- * Narrow a candidate head row, warning when a row that merely shares the
- * `META#` prefix is not a checkpoint meta item. Returning such a row used to
- * make `assembleTuple` miss its payload and report the thread as empty, so
- * LangGraph started a new run on top of the real history; a foreign row is
- * skipped and logged instead, exactly as `list()` treats it.
- */
-function narrowHead(context, raw) {
-    if (raw === undefined)
-        return undefined;
-    const meta = narrowMetaItem(raw);
-    if (!meta) {
-        context.logger.warn('getTuple: skipped a row that is not a checkpoint meta item', {
-            sortKey: raw.SK,
-        });
-    }
-    return meta;
-}
-/**
- * Decode the checkpoint stored in a PAYLOAD item. `threadId` is the caller's
- * (from the config), never the row's: it scopes which S3 object the row may
- * point at, so it must come from the partition the caller asked for.
- */
-async function readCheckpoint(context, item, threadId) {
-    return (0, codec_1.decodePayload)(item.checkpoint, (0, item_writer_1.codecDeps)(context), [threadId]);
-}
-/** Decode the metadata stored in a META item; see {@link readCheckpoint} for `threadId`. */
-async function readMetadata(context, item, threadId) {
-    return (0, codec_1.decodePayload)(item.metadata, (0, item_writer_1.codecDeps)(context), [threadId]);
-}
-/**
- * Drop rows a later `putWrites` call added for a task and channel an earlier
- * call had already committed.
- *
- * A regular write's index is its position in the caller's array, so a retried
- * task whose write mix changed can place an already-committed channel at a
- * second index — a new row, which would replay that channel's value twice. For
- * an accumulating channel (a `messages` add-reducer, a Topic) that
- * double-counts. Every row carries the `writeGroup` of the call that wrote it,
- * which distinguishes that case from a channel a *single* call legitimately
- * wrote more than once (a task emitting two Sends), where both values must
- * survive.
- *
- * Write groups are time-ordered ULIDs, so the smallest one for a `(task,
- * channel)` pair identifies the earliest committed call — first-write-wins,
- * the same rule the write-side guard applies, extended to the case the guard
- * cannot see. Selecting by *order encountered* would not do: rows arrive
- * sorted by index, and a retry emitting fewer writes moves an
- * already-committed channel to a smaller index, where it sorts ahead of the
- * original row and would hand back the later call's value instead. The
- * superseded row stays in DynamoDB and is removed by `deleteThread` or TTL
- * like any other.
- *
- * Identity is `(task, channel, occurrence)`, not `(task, channel)`. Keying on
- * the channel alone treated *any* second row for a channel as a superseding
- * duplicate — including one a retry added at an occurrence no earlier call had
- * ever written, which the write-side guard accepted cleanly. That row was then
- * discarded on read, silently returning fewer values than were written, with
- * `putWrites()` having reported success. For that specific shape — a retry
- * that legitimately emits a channel *more* often than the original call —
- * keeping the occurrence restores the upstream outcome: `MemorySaver` keys
- * first-write-wins on `(taskId, idx)`, so a grown retry keeps both values
- * there too. That is not a claim of parity in general: a retry that reorders
- * or shrinks its writes is still resolved to the earliest call per `(task,
- * channel, occurrence)` as above, which is what keeps an accumulating channel
- * from being double-counted — a case `MemorySaver` does not have to handle.
- */
-function dropSupersededWrites(items) {
-    const identity = (item) => JSON.stringify([item.taskId, item.channel, item.occurrence ?? 0]);
-    const earliestGroup = new Map();
-    for (const item of items) {
-        const id = identity(item);
-        const seen = earliestGroup.get(id);
-        if (seen === undefined || item.writeGroup < seen)
-            earliestGroup.set(id, item.writeGroup);
-    }
-    return items.filter((item) => earliestGroup.get(identity(item)) === item.writeGroup);
-}
-/** Decode WRITE items into `[taskId, channel, value]` pending-write tuples. */
-async function toPendingWrites(context, items, threadId) {
-    const deps = (0, item_writer_1.codecDeps)(context);
-    const live = dropSupersededWrites(items);
-    const values = await (0, concurrency_1.mapWithConcurrency)(live, constants_1.DEFAULT_READ_CONCURRENCY, (item) => (0, codec_1.decodePayload)(item.value, deps, [threadId]));
-    return live.map((item, index) => [
-        item.taskId,
-        item.channel,
-        values[index],
-    ]);
-}

package/dist/checkpointer/internal/item-writer.d.ts

@@ -1,35 +0,0 @@
-import type { Checkpoint, CheckpointMetadata, PendingWrite } from '@langchain/langgraph-checkpoint';
-import { type CodecDeps } from '../../shared/codec/codec';
-import type { CheckpointMetaItem, CheckpointPayloadItem, CheckpointWriteItem } from '../types';
-import type { CheckpointerContext } from './setup';
-/** Map a context to the codec collaborators. */
-export declare function codecDeps(context: CheckpointerContext): CodecDeps;
-/**
- * Encode a checkpoint + metadata into its META and PAYLOAD items. `nonce` is
- * unique per `put()` call and is appended to both S3 key part lists, so a
- * second put of the same checkpoint id — a retry after a lost response, or a
- * repair tool re-writing a checkpoint — never shares an object with the first.
- * That is what makes "the row holds my key" equivalent to "my write is live"
- * for the post-failure verification in `put.ts`, and what keeps a failed
- * re-put's cleanup from deleting the object the first, successful put's rows
- * point at. `storedChannels` narrows the stored `channel_values` (see
- * `selectStoredChannels`); by default every value is stored.
- */
-export declare function buildCheckpointItems(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpoint: Checkpoint, metadata: CheckpointMetadata, nonce: string, parentCheckpointId?: string, ttlTimestamp?: number, storedChannels?: readonly string[]): Promise<{
-    meta: CheckpointMetaItem;
-    payload: CheckpointPayloadItem;
-}>;
-/**
- * Encode a task's pending writes into one item per write. `nonce` must be
- * unique per `putWrites` *call* (not per write) and is appended to every
- * write's S3 offload keyParts — regular and special alike — so a repeated
- * write (a retried task re-emitting the same channel, or two calls to the
- * same special channel) never shares an S3 location with any earlier
- * attempt. Special (negative-index) writes still overwrite their DynamoDB
- * row in place (see {@link writeSpecialItemsWithCleanup}), but that
- * overwrite-safety now comes from reading the previous descriptor before
- * writing and only cleaning it up after the new row is confirmed committed —
- * the same pattern store/actions/put.ts uses for the identical "overwrite in
- * place, nonce every upload" shape.
- */
-export declare function buildWriteItems(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId: string, taskId: string, writes: PendingWrite[], nonce: string, ttlTimestamp?: number): Promise<CheckpointWriteItem[]>;

package/dist/checkpointer/internal/item-writer.js

@@ -1,107 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.codecDeps = codecDeps;
-exports.buildCheckpointItems = buildCheckpointItems;
-exports.buildWriteItems = buildWriteItems;
-const encode_1 = require("../../shared/codec/encode");
-const keys_1 = require("./keys");
-const stored_channels_1 = require("./stored-channels");
-const validation_1 = require("./validation");
-const write_index_1 = require("./write-index");
-/** Map a context to the codec collaborators. */
-function codecDeps(context) {
-    return { serde: context.serde, compression: context.compression, offloader: context.offloader };
-}
-function withTtl(item, ttlTimestamp) {
-    if (ttlTimestamp !== undefined)
-        item.ttl = ttlTimestamp;
-    return item;
-}
-/**
- * Encode a checkpoint + metadata into its META and PAYLOAD items. `nonce` is
- * unique per `put()` call and is appended to both S3 key part lists, so a
- * second put of the same checkpoint id — a retry after a lost response, or a
- * repair tool re-writing a checkpoint — never shares an object with the first.
- * That is what makes "the row holds my key" equivalent to "my write is live"
- * for the post-failure verification in `put.ts`, and what keeps a failed
- * re-put's cleanup from deleting the object the first, successful put's rows
- * point at. `storedChannels` narrows the stored `channel_values` (see
- * `selectStoredChannels`); by default every value is stored.
- */
-async function buildCheckpointItems(context, threadId, checkpointNs, checkpoint, metadata, nonce, parentCheckpointId, ttlTimestamp, storedChannels = Object.keys(checkpoint.channel_values)) {
-    const deps = codecDeps(context);
-    const pk = (0, keys_1.partitionKey)(threadId);
-    const checkpointDescriptor = await (0, encode_1.encodePayload)((0, stored_channels_1.withStoredChannels)(checkpoint, storedChannels), deps, {
-        keyParts: [threadId, checkpointNs, checkpoint.id, 'checkpoint', nonce],
-    });
-    const metadataDescriptor = await (0, encode_1.encodePayload)(metadata, deps, {
-        keyParts: [threadId, checkpointNs, checkpoint.id, 'metadata', nonce],
-    });
-    const meta = {
-        PK: pk,
-        SK: (0, keys_1.metaSortKey)(checkpointNs, checkpoint.id),
-        threadId,
-        checkpointNs,
-        checkpointId: checkpoint.id,
-        metadata: metadataDescriptor,
-        storedChannels: [...storedChannels],
-    };
-    if (parentCheckpointId !== undefined)
-        meta.parentCheckpointId = parentCheckpointId;
-    const payload = {
-        PK: pk,
-        SK: (0, keys_1.payloadSortKey)(checkpointNs, checkpoint.id),
-        checkpoint: checkpointDescriptor,
-    };
-    return { meta: withTtl(meta, ttlTimestamp), payload: withTtl(payload, ttlTimestamp) };
-}
-/**
- * Encode a task's pending writes into one item per write. `nonce` must be
- * unique per `putWrites` *call* (not per write) and is appended to every
- * write's S3 offload keyParts — regular and special alike — so a repeated
- * write (a retried task re-emitting the same channel, or two calls to the
- * same special channel) never shares an S3 location with any earlier
- * attempt. Special (negative-index) writes still overwrite their DynamoDB
- * row in place (see {@link writeSpecialItemsWithCleanup}), but that
- * overwrite-safety now comes from reading the previous descriptor before
- * writing and only cleaning it up after the new row is confirmed committed —
- * the same pattern store/actions/put.ts uses for the identical "overwrite in
- * place, nonce every upload" shape.
- */
-async function buildWriteItems(context, threadId, checkpointNs, checkpointId, taskId, writes, nonce, ttlTimestamp) {
-    /** Reject a bad channel before any payload is encoded or uploaded. */
-    for (const [channel] of writes)
-        (0, validation_1.validateChannel)(channel);
-    const deps = codecDeps(context);
-    const pk = (0, keys_1.partitionKey)(threadId);
-    const items = [];
-    for (const { channel, value, index, occurrence } of (0, write_index_1.resolveWriteIndices)(writes)) {
-        /**
-         * `channel` is part of the key as well as the index: two channels can
-         * share an index (each channel's first occurrence is 0), so without it
-         * their uploads would collide on one S3 object within a single call.
-         */
-        const descriptor = await (0, encode_1.encodePayload)(value, deps, {
-            keyParts: [threadId, checkpointNs, checkpointId, taskId, `write-${index}`, channel, nonce],
-        });
-        const item = {
-            PK: pk,
-            SK: (0, keys_1.writeSortKey)(checkpointNs, checkpointId, taskId, index, channel),
-            taskId,
-            index,
-            channel,
-            /**
-             * Shared by every row this call writes. Positions shift when a retried
-             * task's write mix changes, so a channel an earlier call already
-             * committed can land at a second index and be replayed twice; the group
-             * is what lets the read side tell that apart from a channel a single
-             * call legitimately wrote more than once.
-             */
-            writeGroup: nonce,
-            occurrence,
-            value: descriptor,
-        };
-        items.push(withTtl(item, ttlTimestamp));
-    }
-    return items;
-}

package/dist/checkpointer/internal/keys.d.ts

@@ -1,41 +0,0 @@
-/** Reserved separator joining sort-key segments; forbidden inside any segment. */
-export declare const SORT_KEY_SEPARATOR = "#";
-/**
- * The most negative write index the sort key can encode, `-WRITE_INDEX_OFFSET`.
- * A static test pins it against the peer's `WRITES_IDX_MAP`, so a peer bump
- * that adds a more negative special slot fails loudly instead of producing
- * unsortable keys.
- */
-export declare const MIN_ENCODABLE_WRITE_INDEX: number;
-/** The tag every checkpointer partition key starts with, for a table-wide `begins_with`. */
-export declare function checkpointerPartitionPrefix(): string;
-/** Partition key for a thread: the adapter tag plus the thread id. */
-export declare function partitionKey(threadId: string): string;
-/** Sort key for a checkpoint's lightweight metadata item. */
-export declare function metaSortKey(checkpointNs: string, checkpointId: string): string;
-/** `begins_with` prefix selecting every META item in a namespace (for list). */
-export declare function metaSortKeyPrefix(checkpointNs: string): string;
-/** `begins_with` prefix selecting every META item of a thread, whatever its namespace. */
-export declare function metaAnyNamespacePrefix(): string;
-/** Sort key for a checkpoint's heavy payload item. */
-export declare function payloadSortKey(checkpointNs: string, checkpointId: string): string;
-/**
- * Sort key for a single pending write. The trailing `channel` segment is what
- * keeps two *different* channels from ever occupying one row: without it, a
- * retried task whose write mix changed could compute an index another
- * channel already holds, and the first-write-wins guard — which cannot tell a
- * genuine retry from an unrelated write — would silently discard it. The
- * channel is appended verbatim as the final segment, so two sort keys collide
- * only when their channels are byte-identical; `writeSortKeyPrefix` stops at
- * the checkpoint id, ahead of this segment, so `begins_with` reads are
- * unaffected.
- */
-export declare function writeSortKey(checkpointNs: string, checkpointId: string, taskId: string, index: number, channel: string): string;
-/**
- * True when `sortKey` is one this adapter writes. A partition query carries no
- * sort-key condition, so a partition-wide delete uses this to leave any row it
- * does not own in place rather than deleting the whole partition blindly.
- */
-export declare function isCheckpointerSortKey(sortKey: string): boolean;
-/** `begins_with` prefix selecting every WRITE item for one checkpoint. */
-export declare function writeSortKeyPrefix(checkpointNs: string, checkpointId: string): string;