@axiom-lattice/protocols 4.11.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/protocols",
-  "version": "4.11.0",
+  "version": "5.0.0",
   "description": "Unified protocol type definitions for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/AgentInterruptProtocol.ts

@@ -0,0 +1,15 @@
+/**
+ * Normalized human-in-the-loop interrupt exposed by the Agent Server surface.
+ */
+export interface AgentInterrupt {
+  /** Stable id derived from the LangGraph interrupt id or task/index. */
+  interruptId: string;
+  /** Normalized interrupt kind. */
+  type: "clarify" | "task_review" | "custom";
+  /** Thread whose graph is interrupted. */
+  threadId: string;
+  /** Task id that owns the interrupt, when available. */
+  taskId?: string;
+  /** Raw or normalized interrupt payload. */
+  payload: unknown;
+}

package/src/AgentLatticeProtocol.ts

@@ -14,7 +14,6 @@ import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
 export enum AgentType {
   REACT = "react",
   DEEP_AGENT = "deep_agent",
-  TEAM = "team",
   PROCESSING = "processing",
   /** Remote A2A agent — delegates to an external A2A-compatible server */
   A2A_REMOTE = "a2a_remote",
@@ -203,52 +202,6 @@ export interface ProcessingAgentConfig extends BaseAgentConfig {
   internalSubAgents?: AgentConfig[];
 }
 
-/**
- * Team teammate configuration -- describes an available teammate.
- */
-export interface TeamTeammateConfig {
-  /** Unique name for this teammate (used as agent ID) */
-  name: string;
-  /** Role category (e.g. "research", "writing", "review") */
-  role: string;
-  /** Human-readable description of what this teammate does */
-  description: string;
-  /** Tool keys this teammate has access to */
-  tools?: string[];
-  /** Custom system prompt for this teammate */
-  prompt?: string;
-  /** Model key override for this teammate */
-  modelKey?: string;
-}
-
-/**
- * TEAM agent configuration -- a team lead that dynamically creates teammates.
- * Teammates are created on-the-fly from create_team tool input (name, role, description).
- */
-export interface TeamAgentConfig extends BaseAgentConfig {
-  type: AgentType.TEAM;
-  /** Tool keys available to the team lead */
-  tools?: string[];
-  /** Maximum number of teammates running concurrently */
-  maxConcurrency?: number;
-  /**
-   * Schedule lattice key for polling task list / mailbox.
-   * When set, teammates use ScheduleLattice for periodic polling instead of event-driven wait.
-   */
-  scheduleLatticeKey?: string;
-  /** Poll interval in ms when using schedule lattice (default: 5000) */
-  pollIntervalMs?: number;
-}
-
-/**
- * Type guard to check if config is TeamAgentConfig
- */
-export function isTeamAgentConfig(
-  config: AgentConfig
-): config is TeamAgentConfig {
-  return config.type === AgentType.TEAM;
-}
-
 // ─── A2A_REMOTE Agent ──────────────────────────────────────────────────────
 
 export interface LocalRuntimeConfig {
@@ -361,7 +314,6 @@ export function isWorkflowAgentConfig(
 export type AgentConfig =
   | ReactAgentConfig
   | DeepAgentConfig
-  | TeamAgentConfig
   | ProcessingAgentConfig
   | A2ARemoteAgentConfig
   | WorkflowAgentConfig
@@ -372,7 +324,6 @@ export type AgentConfig =
 export type AgentConfigWithTools =
   | ReactAgentConfig
   | DeepAgentConfig
-  | TeamAgentConfig
   | ProcessingAgentConfig
   | A2ARemoteAgentConfig
   | WorkflowAgentConfig

package/src/AgentWebAppRuntimeProtocol.ts

@@ -104,6 +104,8 @@ export type AgentWebAppErrorCode =
   | "THREAD_NOT_FOUND"
   | "STREAM_CONFLICT"
   | "STREAM_FAILED"
+  | "RUN_CANCEL_UNAVAILABLE"
+  | "RUN_CANCEL_STORE_UNAVAILABLE"
   | "INVALID_REQUEST"
   | "INTERNAL_ERROR";
 

package/src/ChannelAdapterProtocol.ts

@@ -87,6 +87,16 @@ export type MessageMiddleware = (
 export interface ChannelAdapter<TConfig = unknown> {
   readonly channel: string;
   readonly configSchema: z.ZodSchema<TConfig>;
+  /**
+   * Whether `sendReply` is safe to call from any Gateway replica.
+   *
+   * @remarks
+   * Only adapters whose reply transport is stateless/HTTP (for example Lark)
+   * may set this. Connection-bound adapters (WeCom/WeChat/Room) leave it
+   * undefined: their replies depend on process-local sockets or context tokens,
+   * so the durable cross-replica reply path must not claim their jobs.
+   */
+  readonly durableReply?: boolean;
   receive(
     rawPayload: unknown,
     installation: ChannelInstallation,

package/src/ChannelReplyJobProtocol.ts

@@ -0,0 +1,184 @@
+/** Lifecycle of one durable channel reply delivery attempt. */
+export type ChannelReplyJobStatus = "pending" | "delivered" | "failed";
+
+/**
+ * A durable, cross-replica channel reply job.
+ *
+ * @remarks
+ * The row is keyed by `runId` but always read/written inside a tenant scope.
+ * Claiming is a lease-based CAS: only a pending, due row with no live lease can
+ * be claimed, and terminal writes must present the current lease owner.
+ */
+export interface ChannelReplyJob {
+  runId: string;
+  tenantId: string;
+  assistantId: string;
+  threadId: string;
+  adapterChannel: string;
+  channelInstallationId: string;
+  replyTarget: Record<string, unknown>;
+  inputMessageId: string;
+  /**
+   * Legacy chunk-buffer cursor captured before the run was created.
+   *
+   * @remarks Retained for schema compatibility. The durable dispatcher now
+   * reads final text from the thread checkpoint and does not use this field.
+   */
+  streamCursor?: string | null;
+  status: ChannelReplyJobStatus;
+  attempts: number;
+  /** Epoch milliseconds. */
+  availableAt: number;
+  leaseOwner: string | null;
+  /** Epoch milliseconds. */
+  leaseExpiresAt: number | null;
+  lastError: string | null;
+  outputMessageId: string | null;
+  /** Epoch milliseconds. */
+  createdAt: number;
+  /** Epoch milliseconds. */
+  updatedAt: number;
+  /** Epoch milliseconds. */
+  deliveredAt: number | null;
+}
+
+/** Fields accepted when enqueuing a reply job. Status/lease/output fields are assigned by the store. */
+export interface CreateChannelReplyJobInput {
+  runId: string;
+  tenantId: string;
+  assistantId: string;
+  threadId: string;
+  adapterChannel: string;
+  channelInstallationId: string;
+  replyTarget: Record<string, unknown>;
+  inputMessageId: string;
+  /**
+   * Legacy chunk-buffer cursor captured before the run was created.
+   *
+   * @remarks Retained for schema compatibility. The durable dispatcher now
+   * reads final text from the thread checkpoint and does not use this field.
+   */
+  streamCursor?: string | null;
+  /** Earliest epoch-ms time the job may be claimed. */
+  availableAt: number;
+}
+
+/** Persistence boundary for durable channel reply jobs. */
+export interface ChannelReplyJobStore {
+  /** Creates a pending job. */
+  create(input: CreateChannelReplyJobInput): Promise<ChannelReplyJob>;
+  /** Reads one job within a tenant scope. */
+  get(tenantId: string, runId: string): Promise<ChannelReplyJob | null>;
+  /** Lists claimable pending jobs that are due at `now`, oldest first. */
+  listPending(now: number, limit?: number): Promise<ChannelReplyJob[]>;
+  /**
+   * Atomically leases a pending, due job that is unleased or has an expired
+   * lease. Returns the claimed job, or `null` when another owner won.
+   */
+  claim(
+    tenantId: string,
+    runId: string,
+    owner: string,
+    leaseMs: number,
+    now?: number,
+  ): Promise<ChannelReplyJob | null>;
+  /** Marks a job delivered when `owner` still holds the lease. */
+  markDelivered(
+    tenantId: string,
+    runId: string,
+    owner: string,
+    outputMessageId?: string | null,
+    now?: number,
+  ): Promise<ChannelReplyJob | null>;
+  /** Returns a job to pending with an incremented attempt count. */
+  reschedule(
+    tenantId: string,
+    runId: string,
+    owner: string,
+    error: string,
+    availableAt: number,
+    now?: number,
+  ): Promise<ChannelReplyJob | null>;
+  /** Marks a job terminally failed. */
+  markFailed(
+    tenantId: string,
+    runId: string,
+    owner: string,
+    error: string,
+    now?: number,
+  ): Promise<ChannelReplyJob | null>;
+  /** Deletes one job. Returns whether a row was removed. */
+  delete(tenantId: string, runId: string): Promise<boolean>;
+  /**
+   * Deletes up to `limit` terminal (`delivered`/`failed`) jobs whose last update
+   * is strictly older than `before`.
+   *
+   * @param before Epoch milliseconds retention cutoff.
+   * @param limit Maximum rows to prune in this batch (normalized 1..200).
+   * @returns Number of rows removed.
+   */
+  deleteTerminalBefore(before: number, limit?: number): Promise<number>;
+}
+
+/** Smallest accepted page size for {@link ChannelReplyJobStore.listPending}. */
+export const CHANNEL_REPLY_JOB_LIST_LIMIT_MIN = 1;
+/** Largest accepted page size for {@link ChannelReplyJobStore.listPending}. */
+export const CHANNEL_REPLY_JOB_LIST_LIMIT_MAX = 200;
+/** Default page size for {@link ChannelReplyJobStore.listPending}. */
+export const CHANNEL_REPLY_JOB_LIST_LIMIT_DEFAULT = 100;
+
+/**
+ * Normalizes a caller-supplied page size into the shared 1..200 range.
+ *
+ * @remarks Zero and negative values clamp to 1; non-finite values fall back to
+ * the default. Stores must use this helper so InMemory and PostgreSQL agree.
+ */
+export function normalizeChannelReplyJobListLimit(limit?: number): number {
+  if (limit === undefined || !Number.isFinite(limit)) {
+    return CHANNEL_REPLY_JOB_LIST_LIMIT_DEFAULT;
+  }
+  return Math.min(
+    CHANNEL_REPLY_JOB_LIST_LIMIT_MAX,
+    Math.max(CHANNEL_REPLY_JOB_LIST_LIMIT_MIN, Math.trunc(limit)),
+  );
+}
+
+/** Rejects missing/blank required fields and malformed create payloads at runtime. */
+export function assertValidCreateChannelReplyJobInput(
+  input: CreateChannelReplyJobInput,
+): void {
+  if (input === null || typeof input !== "object") {
+    throw new Error("ChannelReplyJob create input is required");
+  }
+  const required: Array<[string, unknown]> = [
+    ["runId", input.runId],
+    ["tenantId", input.tenantId],
+    ["assistantId", input.assistantId],
+    ["threadId", input.threadId],
+    ["adapterChannel", input.adapterChannel],
+    ["channelInstallationId", input.channelInstallationId],
+    ["inputMessageId", input.inputMessageId],
+  ];
+  for (const [field, value] of required) {
+    if (typeof value !== "string" || value.trim() === "") {
+      throw new Error(`ChannelReplyJob requires a non-empty ${field}`);
+    }
+  }
+  if (
+    typeof input.replyTarget !== "object" ||
+    input.replyTarget === null ||
+    Array.isArray(input.replyTarget)
+  ) {
+    throw new Error("ChannelReplyJob requires a replyTarget object");
+  }
+  if (typeof input.availableAt !== "number" || !Number.isFinite(input.availableAt)) {
+    throw new Error("ChannelReplyJob requires a finite availableAt");
+  }
+  if (
+    input.streamCursor !== undefined &&
+    input.streamCursor !== null &&
+    typeof input.streamCursor !== "string"
+  ) {
+    throw new Error("ChannelReplyJob streamCursor must be a string");
+  }
+}

package/src/CheckpointStorageProtocol.ts

@@ -0,0 +1,98 @@
+/**
+ * Checkpoint storage usage for a single thread.
+ *
+ * This is a read-only accounting view over the checkpointer's persisted rows.
+ */
+export interface ThreadCheckpointStorage {
+  /** Thread whose checkpoint rows were measured. */
+  threadId: string;
+  /** Sum of checkpoint, channel-value, and pending-write bytes. */
+  totalBytes: number;
+  /** Persisted checkpoint rows (`checkpoints` table). */
+  checkpoints: { count: number; bytes: number };
+  /** Persisted channel values (`checkpoint_blobs` table). */
+  channelValues: { count: number; bytes: number };
+  /** Persisted pending writes (`checkpoint_writes` table). */
+  pendingWrites: { count: number; bytes: number };
+}
+
+/**
+ * Read-only checkpoint storage accounting.
+ *
+ * Implementations must not create, copy, prune, or mutate checkpoint rows.
+ */
+export interface CheckpointStorage {
+  /**
+   * Measure the checkpoint storage used by one thread.
+   *
+   * @param threadId - Thread id whose checkpoint rows should be measured.
+   * @returns Counts and byte sizes grouped by checkpoint storage category.
+   */
+  get(threadId: string): Promise<ThreadCheckpointStorage>;
+}
+
+/**
+ * Checkpoint maintenance operations over persisted thread checkpoints.
+ *
+ * Implementations copy, delete, and prune raw checkpoint rows for a thread.
+ * Callers must verify thread ownership and refuse to run while the thread is
+ * active.
+ */
+export interface CheckpointMaintenance {
+  /**
+   * Copy every checkpoint row from a source thread to an empty target thread.
+   *
+   * @param sourceThreadId - Thread whose rows are copied.
+   * @param targetThreadId - Empty thread that receives the rows.
+   * @returns Resolves when the copy commits; an empty source is a no-op.
+   * @throws When the target already has checkpoint rows.
+   */
+  copyThread(sourceThreadId: string, targetThreadId: string): Promise<void>;
+
+  /**
+   * Delete every checkpoint row for a thread.
+   *
+   * @param threadId - Thread whose checkpoint rows are deleted.
+   * @returns Resolves when the deletion commits.
+   */
+  deleteThread(threadId: string): Promise<void>;
+
+  /**
+   * Delete the checkpoints that descend from a base checkpoint.
+   *
+   * Preserves the base checkpoint and every checkpoint that is not descended
+   * from it. Descendants are discovered by following both same-namespace
+   * `parent_checkpoint_id` edges and cross-namespace `metadata.parents` edges
+   * (the `{ "<parent checkpoint_ns>": "<parent checkpoint id>" }` map that
+   * LangGraph writes for subgraph checkpoints), recursively across all
+   * namespaces. Checkpoint-id ordering is not used. LangGraph keys the first
+   * superstep's writes of a resumed execution to the parent/base checkpoint, so
+   * writes keyed to the base itself belong to the rolled-back run and are
+   * deleted with descendant writes. Channel blobs are removed only when no
+   * retained checkpoint references them.
+   *
+   * @param threadId - Thread whose later checkpoint history is deleted.
+   * @param baseCheckpointId - Checkpoint to retain as the new tip, or `null` to
+   * delete every checkpoint for the thread. An empty string is invalid and must
+   * never be treated as the `null` wildcard.
+   * @returns Resolves when the deletion commits; no descendants is a no-op.
+   * @throws When the base checkpoint does not exist on the thread. Callers must
+   * fail closed rather than deleting an unknown range.
+   * @remarks The operation is transactional and idempotent so rollback recovery
+   * can retry it.
+   */
+  deleteAfter(threadId: string, baseCheckpointId: string | null): Promise<void>;
+
+  /**
+   * Retain only the latest N checkpoints per checkpoint namespace.
+   *
+   * @param threadId - Thread whose checkpoint history is pruned.
+   * @param options - Retention options.
+   * @param options.keepLatest - Number of latest checkpoints to retain per namespace.
+   * @returns Counts of deleted checkpoint, blob, and write rows.
+   */
+  pruneThread(
+    threadId: string,
+    options: { keepLatest: number },
+  ): Promise<{ checkpoints: number; blobs: number; writes: number }>;
+}

package/src/MessageProtocol.ts

@@ -114,6 +114,14 @@ export type MessageChunkType = typeof MessageChunkTypes[keyof typeof MessageChun
 
 export interface MessageChunk {
   type: MessageChunkType;
+  /**
+   * Shared append-log cursor for this chunk.
+   *
+   * Set by streaming transports when the chunk is read from a cursor-addressable
+   * log (for example Redis Streams) so reconnects can resume via SSE
+   * `Last-Event-ID`. Omitted by in-memory buffers configured without a log.
+   */
+  cursor?: string;
   data: {
     id: string;
     content?: string;

package/src/RunCancelProtocol.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+
+/**
+ * Upper bound for every contract string. These payloads travel between
+ * replicas and are persisted with A2A tasks, so unbounded input is rejected
+ * at the shared boundary instead of relying on transport limits.
+ */
+const MAX_FIELD_LENGTH = 64 * 1024;
+
+const boundedString = z.string().min(1).max(MAX_FIELD_LENGTH);
+
+/** Terminal cancellation commands delivered to the replica that currently owns a run. */
+const RUN_CANCEL_REASONS = ["abort", "a2a.cancel", "shutdown"] as const;
+
+/**
+ * A cancellation signal routed to the current owner of a run.
+ *
+ * `runId` is mandatory: a signal without it cannot unambiguously identify the
+ * execution to stop, so it is rejected rather than applied to the thread.
+ */
+export interface RunCancelSignal {
+  commandId: string;
+  tenantId: string;
+  assistantId: string;
+  threadId: string;
+  runId: string;
+  reason: "abort" | "a2a.cancel" | "shutdown";
+  createdAt: string;
+}
+
+/**
+ * Identity of a human-in-the-loop interrupt answer, used for distributed
+ * dedupe so multiple replicas settle the same answer at most once.
+ */
+export interface InterruptAnswerKey {
+  tenantId: string;
+  assistantId: string;
+  threadId: string;
+  interruptId: string;
+}
+
+/**
+ * Durable A2A event delivery cursor stored with the shared A2A task.
+ * `lastEventId` is the last event already handed to the client.
+ */
+export interface A2AEventCursor {
+  taskId: string;
+  lastEventId: string;
+  updatedAt: string;
+}
+
+/** Strict validator for {@link RunCancelSignal}. */
+export const runCancelSignalSchema: z.ZodType<RunCancelSignal> = z.object({
+  commandId: boundedString,
+  tenantId: boundedString,
+  assistantId: boundedString,
+  threadId: boundedString,
+  runId: boundedString,
+  reason: z.enum(RUN_CANCEL_REASONS),
+  createdAt: boundedString,
+}).strict();
+
+/** Strict validator for {@link InterruptAnswerKey}. */
+export const interruptAnswerKeySchema: z.ZodType<InterruptAnswerKey> = z.object({
+  tenantId: boundedString,
+  assistantId: boundedString,
+  threadId: boundedString,
+  interruptId: boundedString,
+}).strict();
+
+/** Strict validator for {@link A2AEventCursor}. */
+export const a2aEventCursorSchema: z.ZodType<A2AEventCursor> = z.object({
+  taskId: boundedString,
+  lastEventId: boundedString,
+  updatedAt: boundedString,
+}).strict();

package/src/StoreProtocol.ts

@@ -0,0 +1,181 @@
+/**
+ * A tenant-scoped namespaced key-value item.
+ */
+export interface StoreItem {
+  /** Hierarchical namespace path. */
+  namespace: string[];
+  /** Item key, unique within `(tenantId, namespace)`. */
+  key: string;
+  /** Arbitrary JSON object stored under the key. */
+  value: Record<string, unknown>;
+  /** Creation timestamp. */
+  createdAt: Date;
+  /** Last write timestamp. */
+  updatedAt: Date;
+  /** Optional expiry timestamp; expired items are invisible. */
+  expiresAt?: Date;
+}
+
+/** Input for {@link StoreProtocol.put}. */
+export interface StorePutInput {
+  /** Non-empty namespace path. */
+  namespace: string[];
+  /** Non-empty item key. */
+  key: string;
+  /** JSON object value. */
+  value: Record<string, unknown>;
+  /**
+   * Optional time-to-live in minutes.
+   *
+   * @remarks Positive finite numbers are accepted; stores compute `expiresAt`.
+   */
+  ttlMinutes?: number;
+  /**
+   * Optional index hint accepted for future indexing.
+   *
+   * @remarks No vector index is created in this slice.
+   */
+  index?: boolean | string[];
+}
+
+/** Input for {@link StoreProtocol.search}. */
+export interface StoreSearchInput {
+  /** Only return items whose namespace starts with this path. */
+  namespacePrefix?: string[];
+  /** Deep partial-equality filter over `value`. */
+  filter?: Record<string, unknown>;
+  /** Case-insensitive substring over the serialized value. */
+  query?: string;
+  /** Maximum items to return. */
+  limit?: number;
+  /** Pagination offset. */
+  offset?: number;
+}
+
+/**
+ * Tenant-scoped namespaced key-value store with TTL and simple search.
+ *
+ * @remarks
+ * - Unique identity is `(tenantId, namespace, key)`.
+ * - Expired items are invisible to {@link get} and {@link search}.
+ * - `filter` is deep partial equality over `value`; `query` is a
+ *   case-insensitive substring over the serialized value. Semantic/embedding
+ *   search is deferred.
+ */
+export interface StoreProtocol {
+  /** Create or replace an item. */
+  put(tenantId: string, input: StorePutInput): Promise<StoreItem>;
+  /** Read an unexpired item. */
+  get(tenantId: string, namespace: string[], key: string): Promise<StoreItem | null>;
+  /** Delete an item regardless of expiry. */
+  delete(tenantId: string, namespace: string[], key: string): Promise<boolean>;
+  /** Search unexpired items. */
+  search(tenantId: string, input: StoreSearchInput): Promise<StoreItem[]>;
+  /** List distinct namespace paths under a prefix. */
+  listNamespaces(tenantId: string, prefix?: string[], limit?: number): Promise<string[][]>;
+  /** Hard-delete expired items across all tenants. */
+  deleteExpired(now: Date, limit: number): Promise<number>;
+}
+
+
+/** Separator reserved for encoded namespace paths. */
+export const STORE_IDENTITY_SEPARATOR = "\u001f";
+
+/** Raised when a store namespace/key identity is malformed. */
+export class StoreValidationError extends Error {
+  readonly code = "STORE_IDENTITY_INVALID" as const;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "StoreValidationError";
+  }
+}
+
+function validStoreSegment(value: unknown): value is string {
+  return typeof value === "string"
+    && value.length > 0
+    && !value.includes(STORE_IDENTITY_SEPARATOR);
+}
+
+/**
+ * Assert a non-empty namespace array of non-empty segments without the
+ * reserved separator.
+ *
+ * @param namespace - Candidate namespace path.
+ * @throws {StoreValidationError} When the namespace is malformed.
+ */
+export function assertStoreIdentity(namespace: unknown, key: unknown): asserts namespace is string[] {
+  if (!Array.isArray(namespace) || namespace.length === 0) {
+    throw new StoreValidationError("namespace must be a non-empty string array");
+  }
+  for (const segment of namespace) {
+    if (!validStoreSegment(segment)) {
+      throw new StoreValidationError(
+        "namespace segments must be non-empty strings without the reserved separator",
+      );
+    }
+  }
+  if (!validStoreSegment(key)) {
+    throw new StoreValidationError(
+      "key must be a non-empty string without the reserved separator",
+    );
+  }
+}
+
+/**
+ * Assert a namespace prefix (which may be empty for "all namespaces").
+ *
+ * @param prefix - Candidate prefix path.
+ * @throws {StoreValidationError} When any segment is malformed.
+ */
+export function assertStoreNamespacePrefix(prefix: unknown): asserts prefix is string[] {
+  if (!Array.isArray(prefix)) {
+    throw new StoreValidationError("namespace prefix must be a string array");
+  }
+  for (const segment of prefix) {
+    if (!validStoreSegment(segment)) {
+      throw new StoreValidationError(
+        "namespace segments must be non-empty strings without the reserved separator",
+      );
+    }
+  }
+}
+
+/**
+ * Validate and compute an expiry date from `ttlMinutes`.
+ *
+ * @param ttlMinutes - Optional positive finite TTL in minutes.
+ * @param now - Base time (default current time).
+ * @returns The expiry date, or `undefined` when no TTL was supplied.
+ * @throws {StoreValidationError} When the TTL is invalid or out of range.
+ */
+export function storeExpiresAt(
+  ttlMinutes: number | undefined,
+  now: Date = new Date(),
+): Date | undefined {
+  if (ttlMinutes === undefined) return undefined;
+  if (typeof ttlMinutes !== "number" || !Number.isFinite(ttlMinutes) || ttlMinutes <= 0) {
+    throw new StoreValidationError("ttlMinutes must be a positive number");
+  }
+  const expiresAt = new Date(now.getTime() + ttlMinutes * 60_000);
+  if (!Number.isFinite(expiresAt.getTime()) || expiresAt.getUTCFullYear() > 9999) {
+    throw new StoreValidationError("ttlMinutes is out of range");
+  }
+  return expiresAt;
+}
+
+/**
+ * Validate a non-negative safe-integer pagination value.
+ *
+ * @param value - Candidate limit/offset.
+ * @param fallback - Value used when omitted.
+ * @returns The validated number.
+ * @throws {StoreValidationError} When the value is not a non-negative safe integer.
+ */
+export function storePaginationValue(value: number | undefined, fallback: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new StoreValidationError("limit/offset must be a non-negative safe integer");
+  }
+  return value;
+}