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

package/dist/history/internal/session.d.ts

@@ -0,0 +1,331 @@
+/**
+ * Hides the SESSION row: what it carries and how each field changes.
+ *
+ * A session's metadata — `messageCount`, `title`, `createdAt`, `updatedAt`,
+ * `ttl`, the `writeId` of the last append, and the recency-index keys — lives
+ * on one row, and `messageCount` is a copy of a fact the message rows hold.
+ * Keeping the copy in step is this module's job and nobody else's: the append
+ * adds to it in the same transaction that writes the messages, a rolled-back
+ * append subtracts exactly what it added (and never from a later incarnation of
+ * the session), a repair recomputes it under a compare-and-swap, and a listing
+ * reads it back only from a row this release can summarise. The recency-index
+ * keys are the one field this module does not write alone: `sessionIndexTarget`
+ * below tells `src/backfill/backfill.ts` which row is a SESSION row, and
+ * backfill writes the keys onto it directly, for a row that predates the index.
+ */
+import type { StoredMessage } from '@langchain/core/messages';
+import type { AttributeMap, TransactAction } from '../../shared/dynamodb/client';
+import { type IndexTarget } from '../../shared/dynamodb/recency-index';
+import type { SessionMetadata } from '../types';
+import type { SessionId } from './parse';
+import type { HistoryContext } from './setup';
+/**
+ * Subtract a count this append already added from the session, leaving it consistent.
+ * Guarded so a concurrently-deleted SESSION row is never resurrected as a
+ * permanent, ttl-less junk row: if the row is already gone there is nothing
+ * to revert, so that specific condition failure is swallowed rather than
+ * surfaced — this runs only from an already-in-progress rollback, where a
+ * spurious error for a no-op would misrepresent what happened.
+ *
+ * The same condition also pins the *incarnation*: `createdAt <= createdBefore`
+ * (this call's own append timestamp). A session `clear()`-ed and re-created by
+ * another caller between this call's commit and its rollback carries a later
+ * `createdAt`; decrementing it would corrupt the new incarnation's count, and
+ * its rows were never this call's to revert. That rejection is swallowed too,
+ * for the same reason as a vanished row.
+ *
+ * Deliberately does not revert a `forceTtlRefresh`-driven ttl SET from an
+ * earlier committed chunk: the healed anchor is never shorter than what
+ * was there before, so leaving it in place after a rollback only means the
+ * session's metadata row outlives its content a bit longer than ideal —
+ * self-healing (the next successful append, or DynamoDB's own TTL sweep,
+ * resolves it), unlike reverting, which would need to re-check for a
+ * concurrent legitimate extension to avoid regressing it. See README.md's
+ * "TTL expiry" section.
+ *
+ * Accepts: `delta` — how many messages to subtract; `0` is a no-op and spends
+ * no write. `createdBefore` — this call's own append timestamp, which pins the
+ * incarnation.
+ *
+ * Returns: nothing, whether the decrement applied or the guard correctly
+ * refused it.
+ *
+ * Throws: whatever the write throws other than its own condition failure. A
+ * vanished row and a newer incarnation are both "nothing of mine to revert",
+ * not errors — this runs from an in-progress rollback, where a spurious error
+ * for a no-op would misrepresent what happened.
+ *
+ * Guarantees: the decrement is applied at most once, however often the request
+ * is re-sent. `ADD #count :neg` is one of the two writes in this package that
+ * are not naturally idempotent — the append's own `ADD #count :n` is the
+ * other — and applied twice it subtracts twice, with nothing reading the row
+ * back afterwards to notice, so a re-sent attempt must be answered from
+ * DynamoDB's idempotency cache rather than re-evaluated. Two things hold
+ * that together and only together: the `ClientRequestToken`, which makes a
+ * re-send a no-op, and the deadline of `MAX_WRITE_LIFETIME_MS`, which
+ * stops the retrying while that token is still honoured. Nothing in the token
+ * enforces that window — the service honours it for its own ten minutes
+ * whatever a caller's retry policy says — so without the deadline a long
+ * policy could still be retrying after the window closed, and the re-send
+ * would then land as a second subtraction, leaving `messageCount` quietly
+ * wrong. `reconcileMessageCount` is the repair if that happens anyway: it
+ * recounts the live messages and writes the true total back.
+ *
+ * The guard is no second line of defence for it. An attempt the condition
+ * turns away commits nothing, so DynamoDB caches no result for that attempt's
+ * token and a retry is a fresh evaluation rather than a deduplicated one — the
+ * exactly-once promise holds for an attempt that **committed**, which is also
+ * the only attempt whose re-send could subtract twice.
+ */
+export declare function revertSessionCount(context: HistoryContext, sessionId: SessionId, delta: number, createdBefore: string): Promise<void>;
+/** What a rolled-back append had created on the SESSION row, which the revert undoes. */
+export interface CreatedSession {
+    /** Messages the append added to `messageCount`. */
+    readonly total: number;
+    /** The `createdAt` the append stamped, which pins the revert to that incarnation. */
+    readonly createdAt: string;
+    /** The title the append contributed, if it contributed one. */
+    readonly title?: string;
+}
+/**
+ * Undo a rolled-back append's effect on the session row.
+ *
+ * When this call is the one that created the row — `createdAt` still equals
+ * this call's timestamp, and the only messages counted on it are the ones
+ * being reverted — the whole row is deleted. Without that, a failed first
+ * append left a "ghost session": `title`, `createdAt` and `sessionId` are all
+ * written via `if_not_exists`, so they were never reverted and never set
+ * again, leaving `listSessions()` reporting a session with `messageCount: 0`
+ * whose title still held up to 80 characters of a message the caller was told
+ * had not persisted, with no API to clear it.
+ *
+ * Both conditions are load-bearing. `createdAt = :now` establishes that this
+ * call created the row; `messageCount = :total` establishes that nothing else
+ * has added to it since. A concurrent append to the same brand-new session
+ * fails the count check, because deleting the row would destroy that caller's
+ * committed messages — so it falls through to the plain decrement, and then
+ * strips just the title this call contributed, which is the only part of the
+ * row still carrying rolled-back message content.
+ *
+ * Accepts: `created` — what this call contributed to the row. `created.total`
+ * — every message this call counted onto the row; `0` is a no-op.
+ * `created.createdAt` — this call's timestamp, which is what "I created this
+ * row" means here. `created.title` — the title this call may have contributed.
+ *
+ * Returns: nothing. The row is deleted, or decremented and stripped of this
+ * call's title; both are a complete undo of what this call contributed.
+ *
+ * Throws: whatever the writes throw other than their own condition failures.
+ *
+ * Guarantees: the delete is applied at most once, and inside the window its
+ * token is honoured for, a re-send of an attempt that **committed** is
+ * answered from DynamoDB's idempotency cache rather than re-evaluated. The
+ * condition would already stop such a re-send from removing anything it should
+ * not; what the token adds is that it comes back as the success it was.
+ * Re-evaluated instead, it finds the row gone, fails both equalities, and the
+ * cancellation is read below as "a concurrent append has added to this row" —
+ * sending a rollback that already completed down the decrement-and-strip path
+ * meant for the case where the row survived. Both writes on that path are
+ * themselves guarded, and the decrement's incarnation pin refuses a session
+ * re-created in the meantime, so the price is two spurious conditional writes
+ * rather than a wrong count; the token is what keeps them from being spent.
+ *
+ * A rejection carries no idempotency forward — a cancelled attempt commits
+ * nothing, so nothing is cached for its token — and here that is exactly the
+ * wanted behaviour, since the fall-through below is a fresh decision about
+ * what to do instead. The deadline drawn beside the token is what keeps the
+ * retrying inside that window; the token enforces no window of its own.
+ */
+export declare function revertSessionCreation(context: HistoryContext, sessionId: SessionId, created: CreatedSession): Promise<void>;
+/** Fields driving the per-session metadata update inside the append transaction. */
+export interface SessionUpdateFields {
+    sessionId: string;
+    /** Index partitions, from the adapter's context; see `indexKeys`. */
+    indexShards?: number;
+    /**
+     * The id of the append writing this update, drawn per chunk transaction by
+     * {@link writeMessageChunk}. It travels in the fields rather than being
+     * minted inside the builder, so an attempt rebuilt for a retry carries the
+     * id of the write it retries rather than a new one.
+     */
+    writeId: string;
+    count: number;
+    now: string;
+    title?: string;
+    ttlTimestamp?: number;
+    forceTtlRefresh?: boolean;
+}
+/**
+ * Build the metadata `Update` transact-item: `ADD` the message count and `SET`
+ * `updatedAt` and the appending write's id every time, while `createdAt`,
+ * `sessionId`, `title`, and the `ttl` anchor are written once via
+ * `if_not_exists`. Folding the `ttl` anchor in here means the first append
+ * fixes one shared expiry atomically with the count, with no separate
+ * pre-write that could orphan a metadata-only row. When
+ * `forceTtlRefresh` is set (because {@link resolveTtlAnchor} found the persisted
+ * anchor missing or already expired), the `ttl` clause instead does a plain
+ * `SET`, so the SESSION row's own stale attribute actually heals instead of
+ * being permanently blocked by `if_not_exists`. When forceTtlRefresh is set,
+ * the SET is additionally guarded by a ConditionExpression so a concurrent
+ * caller's already-healed anchor can never be regressed backward — see
+ * append.ts for how a lost race is retried without forcing.
+ *
+ * Accepts: `count` — how many messages this append adds, which `ADD` applies to
+ * whatever the row holds, so two concurrent appends both count. `title` —
+ * written once and never overwritten, so a session keeps the title its first
+ * turn produced. `writeId` — the appending write's own id, rewritten on every
+ * append so the row always names the write that last added to it.
+ * `ttlTimestamp` — absent leaves the row without an expiry. `forceTtlRefresh` —
+ * see above.
+ *
+ * Returns: the `Update` transact-item. It creates the row when there is none:
+ * every once-only field is an `if_not_exists`, so the first append and the
+ * thousandth build the same item.
+ *
+ * Throws: nothing. The condition it carries is evaluated by DynamoDB, and a
+ * failed condition surfaces from the transaction, not from here.
+ */
+export declare function buildSessionUpdate(tableName: string, fields: SessionUpdateFields): TransactAction;
+/**
+ * Strip a title this call contributed to a session row it created, when the
+ * row itself could not be deleted because a concurrent append has since added
+ * messages to it.
+ *
+ * Without this, that narrow window reopens exactly the leak C4 closes: the
+ * title is derived from the first human message of an append the caller was
+ * told had failed, and `if_not_exists` means nothing ever overwrites it — so
+ * a row that now belongs to a different caller keeps up to 80 characters of
+ * rolled-back message content.
+ *
+ * Both guards are load-bearing. `createdAt = :now` establishes that this call
+ * created the row, and `title = :title` that the title on it is still the one
+ * this call wrote — so a pre-existing title, or one a concurrent caller won
+ * the `if_not_exists` race for, is never removed. A condition rejection means
+ * exactly that and is not an error; anything else is.
+ *
+ * Accepts: `createdAt` — this call's own timestamp. `title` — the exact string
+ * this call wrote, compared as a value so nothing else's title is removed.
+ *
+ * Returns: nothing, whether the title was removed or the guards correctly
+ * refused.
+ *
+ * Throws: whatever the update throws other than its own condition failure.
+ */
+export declare function removeRolledBackTitle(context: HistoryContext, sessionId: SessionId, createdAt: string, title: string): Promise<void>;
+/** The resolved ttl anchor plus whether the persisted SESSION-row value must be force-refreshed. */
+export interface TtlAnchorResult {
+    ttlTimestamp: number;
+    refresh: boolean;
+}
+/**
+ * Resolve the session's creation-anchored TTL: the value already stored on the
+ * SESSION item, if one exists AND is still in the future; otherwise the
+ * supplied `candidate`, with `refresh: true` so the caller force-overwrites
+ * the stale/missing persisted anchor instead of leaving it stuck (DynamoDB's
+ * `if_not_exists` would otherwise never correct an already-expired anchor).
+ * This is a strongly-consistent read, never a write, so it cannot leave a
+ * metadata-only orphan row when the following append transaction fails.
+ *
+ * When a stale anchor is healed, only the persisted SESSION row's `ttl` is
+ * force-refreshed — the message rows already written under the expired
+ * anchor keep their own (already-expired) `ttl` and get swept independently
+ * by DynamoDB's TTL sweep. Until that sweep runs (and until
+ * `reconcileMessageCount` repairs the count), `messageCount` can therefore be
+ * temporarily overstated relative to what `getMessages` actually returns.
+ * This is expected, not a bug.
+ *
+ * Accepts: `candidate` — the anchor this append would use if the session has
+ * none, already computed from the configured ttl.
+ *
+ * Returns: the anchor to stamp on this append's messages, and whether the
+ * SESSION row's own `ttl` must be force-overwritten rather than left to
+ * `if_not_exists`.
+ *
+ * Throws: whatever the read throws after retries.
+ *
+ * Guarantees: a read, never a write — so a failure of the append that follows
+ * cannot leave a metadata-only orphan row behind. Strongly consistent, so an
+ * anchor an earlier append committed is always seen. Two appends that start
+ * together on a session that has none each propose their own candidate; the
+ * append transaction's own condition is what settles which persists, so this
+ * read never has to be the arbiter (see {@link buildSessionUpdate}).
+ */
+export declare function resolveTtlAnchor(context: HistoryContext, sessionId: SessionId, candidate: number, signal?: AbortSignal): Promise<TtlAnchorResult>;
+/**
+ * Derive a session title from the first human message's text content, at most
+ * {@link MAX_TITLE_LENGTH} characters including the ellipsis. Returns undefined
+ * when there is no usable text.
+ *
+ * Truncation counts *code points*, not UTF-16 code units: slicing by index
+ * could cut a surrogate pair in half, leaving a lone surrogate that no longer
+ * round-trips through UTF-8. The ellipsis is also counted against the maximum
+ * rather than appended past it.
+ *
+ * Accepts: `messages` — one append's messages, in order. The first `human` one
+ * is the title's source; an append of only AI or tool messages has none, and an
+ * append to an existing session produces a title that is then discarded by
+ * `if_not_exists`.
+ *
+ * Returns: the title, or undefined when there is no usable text — no human
+ * message, empty content, or a multimodal message carrying no text block.
+ * Undefined means "do not write a title", not "write an empty one".
+ *
+ * Throws: nothing. A title is a convenience; nothing about it may fail an
+ * append.
+ */
+export declare function deriveTitle(messages: StoredMessage[]): string | undefined;
+/**
+ * Recompute `messageCount` from the stored message rows and write it, pinned to
+ * the count the row held when the recount began.
+ *
+ * Accepts: `sessionId` — parsed. `signal` — cancels the reads, the recount and
+ * the write.
+ *
+ * Returns: the count written.
+ *
+ * Throws: `CONDITION_CONFLICT` when the session does not exist, or when it
+ * changed during every one of the compare-and-swap's attempts;
+ * `FORMAT_UNSUPPORTED` for a message row a newer release wrote; `VALIDATION`
+ * naming `message` for a row in the message key space this package did not
+ * write; whatever the reads and the write throw.
+ */
+export declare function repairMessageCount(context: HistoryContext, sessionId: SessionId, signal?: AbortSignal): Promise<number>;
+/**
+ * The public summary of a SESSION row: the session a row describes, or
+ * undefined for a foreign, malformed or expired row.
+ *
+ * The `sessionId` is bound to the partition the row was found in, as
+ * `parseMetaRow`, `parseStoreRow` and `parseMessageRow` bind theirs.
+ * Both reads that reach here select rows by something other than the partition
+ * — a table scan filtered on the sort key, and a recency-index query — so
+ * without the binding a row planted anywhere in the table under this adapter's
+ * SESSION sort key was summarised under whatever `sessionId` it claimed, and a
+ * caller taking that id to `getMessages` read a partition the row never lived
+ * in.
+ *
+ * Accepts: `raw` — a row a listing read. `atSeconds` — the listing's clock,
+ * against which an expired row is absent.
+ *
+ * Returns: the summary, or `undefined` for a foreign, malformed or expired row.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row a newer release wrote. It is not a
+ * foreign row to skip, and summarising it under this release's rules could
+ * return its attributes with a meaning they no longer have. Checked before the
+ * shape, the binding and the ttl — as every other read of this package's rows
+ * checks it — so a newer row is refused rather than judged against attribute
+ * names it may no longer use, and the answer does not depend on the reading
+ * machine's clock.
+ */
+export declare function summariseSession(raw: AttributeMap, atSeconds: number): SessionMetadata | undefined;
+/**
+ * Where a history row sits in the recency index, for a row written before the
+ * index existed.
+ *
+ * Accepts: `row` — any row of the table.
+ *
+ * Returns: a SESSION row's identity — its session id, at its own `updatedAt` —
+ * or `undefined` for a message row or a row of another adapter.
+ *
+ * Throws: nothing.
+ */
+export declare function sessionIndexTarget(row: AttributeMap): IndexTarget | undefined;