zeitlich 0.2.45 → 0.2.47

package/dist/cold-store-BDgJpwLI.d.ts

@@ -0,0 +1,114 @@
+import { P as PersistedThreadState } from './types-qQVZfhoT.js';
+import { S3Client } from '@aws-sdk/client-s3';
+
+/**
+ * Pluggable cold-tier interface for thread archives.
+ *
+ * Zeitlich's thread manager is a Redis-backed hot tier optimized for
+ * the duration of a workflow run. A `ColdThreadStore` provides the
+ * durable archive: each thread is serialized to a single
+ * {@link ThreadSnapshot} blob (messages + persisted state slice +
+ * dedup-id ledger) at session-exit time, and restored at session-entry
+ * time when the workflow is resumed or forked.
+ *
+ * The contract is intentionally minimal — one read, one write, one
+ * delete keyed by `(threadKey, threadId)`. Any storage backend that
+ * can satisfy these three calls (S3, R2, GCS, Postgres, the local
+ * filesystem, etc.) can plug into the same tiered manager.
+ *
+ * Concurrency assumption: zeitlich assumes a single active session
+ * per `(threadKey, threadId)` at a time, so cold writes are
+ * last-writer-wins; no compare-and-swap is required.
+ */
+
+/**
+ * Serialized form of a thread that can be written to and read from a
+ * {@link ColdThreadStore}.
+ *
+ * `messages` is the list of raw-serialized message strings exactly as
+ * they were stored in the Redis list — keeping the cold tier opaque
+ * to the adapter-specific message envelope. `state` is the
+ * {@link PersistedThreadState} that the session writes via
+ * `saveThreadState` on every exit path, or `null` if none has been
+ * written yet. `dedupIds` lets the tiered manager re-prime the
+ * idempotent-append dedup markers when restoring, so a rewind retry
+ * after a continue cannot accidentally re-append a message.
+ */
+interface ThreadSnapshot {
+    v: 1;
+    messages: string[];
+    state: PersistedThreadState | null;
+    dedupIds: string[];
+}
+/** Pluggable cold archive for thread snapshots. */
+interface ColdThreadStore {
+    /**
+     * Read the latest snapshot for `(threadKey, threadId)`, or return
+     * `null` if no snapshot has ever been written.
+     */
+    read(threadKey: string, threadId: string): Promise<ThreadSnapshot | null>;
+    /**
+     * Persist `snapshot` as the latest archive for `(threadKey,
+     * threadId)`. Overwrites any prior snapshot in place.
+     */
+    write(threadKey: string, threadId: string, snapshot: ThreadSnapshot): Promise<void>;
+    /**
+     * Permanently remove the archive for `(threadKey, threadId)`.
+     * No-op if no snapshot exists.
+     */
+    delete(threadKey: string, threadId: string): Promise<void>;
+}
+/**
+ * Alias for `@aws-sdk/client-s3`'s `S3Client`. The built-in store
+ * calls `send(...)` and accesses `client.config` (read by
+ * `@aws-sdk/lib-storage`'s `Upload`) — a duck-type with just `send`
+ * is not sufficient.
+ */
+type S3LikeClient = S3Client;
+/** Configuration for the built-in S3 cold store. */
+interface S3ColdStoreConfig {
+    /** An `@aws-sdk/client-s3` `S3Client`. */
+    s3: S3LikeClient;
+    /** S3 bucket that holds the archive. */
+    bucket: string;
+    /**
+     * Optional key prefix applied to every object. The final key layout
+     * is `${prefix}/${threadKey}/${threadId}.json[.gz]` with leading
+     * slashes stripped. Defaults to `"threads"`.
+     */
+    prefix?: string;
+    /**
+     * Gzip the JSON payload before uploading and assume gzip on read.
+     * Defaults to `true` — message lists are highly compressible.
+     */
+    gzip?: boolean;
+    /**
+     * Optional `Content-Type` override. Defaults to
+     * `application/json` (or `application/gzip` when `gzip: true`).
+     */
+    contentType?: string;
+}
+/**
+ * Build an S3-backed {@link ColdThreadStore}.
+ *
+ * One object per thread at
+ * `${prefix}/${threadKey}/${threadId}.json[.gz]`, JSON-encoded and
+ * gzip-compressed by default. The consumer owns the `S3Client`
+ * instance, so credentials, region, and endpoint configuration live
+ * outside zeitlich.
+ *
+ * @example
+ * ```typescript
+ * import { S3Client } from "@aws-sdk/client-s3";
+ * import { createS3ColdStore } from "zeitlich";
+ *
+ * const coldStore = createS3ColdStore({
+ *   s3: new S3Client({ region: "us-east-1" }),
+ *   bucket: "my-threads",
+ *   prefix: "prod/threads",
+ * });
+ * ```
+ */
+declare function createS3ColdStore(config: S3ColdStoreConfig): ColdThreadStore;
+
+export { type ColdThreadStore as C, type S3ColdStoreConfig as S, type ThreadSnapshot as T, type S3LikeClient as a, createS3ColdStore as c };

package/dist/cold-store-Z2wvK2cV.d.cts

@@ -0,0 +1,114 @@
+import { P as PersistedThreadState } from './types-DNEl5uxQ.cjs';
+import { S3Client } from '@aws-sdk/client-s3';
+
+/**
+ * Pluggable cold-tier interface for thread archives.
+ *
+ * Zeitlich's thread manager is a Redis-backed hot tier optimized for
+ * the duration of a workflow run. A `ColdThreadStore` provides the
+ * durable archive: each thread is serialized to a single
+ * {@link ThreadSnapshot} blob (messages + persisted state slice +
+ * dedup-id ledger) at session-exit time, and restored at session-entry
+ * time when the workflow is resumed or forked.
+ *
+ * The contract is intentionally minimal — one read, one write, one
+ * delete keyed by `(threadKey, threadId)`. Any storage backend that
+ * can satisfy these three calls (S3, R2, GCS, Postgres, the local
+ * filesystem, etc.) can plug into the same tiered manager.
+ *
+ * Concurrency assumption: zeitlich assumes a single active session
+ * per `(threadKey, threadId)` at a time, so cold writes are
+ * last-writer-wins; no compare-and-swap is required.
+ */
+
+/**
+ * Serialized form of a thread that can be written to and read from a
+ * {@link ColdThreadStore}.
+ *
+ * `messages` is the list of raw-serialized message strings exactly as
+ * they were stored in the Redis list — keeping the cold tier opaque
+ * to the adapter-specific message envelope. `state` is the
+ * {@link PersistedThreadState} that the session writes via
+ * `saveThreadState` on every exit path, or `null` if none has been
+ * written yet. `dedupIds` lets the tiered manager re-prime the
+ * idempotent-append dedup markers when restoring, so a rewind retry
+ * after a continue cannot accidentally re-append a message.
+ */
+interface ThreadSnapshot {
+    v: 1;
+    messages: string[];
+    state: PersistedThreadState | null;
+    dedupIds: string[];
+}
+/** Pluggable cold archive for thread snapshots. */
+interface ColdThreadStore {
+    /**
+     * Read the latest snapshot for `(threadKey, threadId)`, or return
+     * `null` if no snapshot has ever been written.
+     */
+    read(threadKey: string, threadId: string): Promise<ThreadSnapshot | null>;
+    /**
+     * Persist `snapshot` as the latest archive for `(threadKey,
+     * threadId)`. Overwrites any prior snapshot in place.
+     */
+    write(threadKey: string, threadId: string, snapshot: ThreadSnapshot): Promise<void>;
+    /**
+     * Permanently remove the archive for `(threadKey, threadId)`.
+     * No-op if no snapshot exists.
+     */
+    delete(threadKey: string, threadId: string): Promise<void>;
+}
+/**
+ * Alias for `@aws-sdk/client-s3`'s `S3Client`. The built-in store
+ * calls `send(...)` and accesses `client.config` (read by
+ * `@aws-sdk/lib-storage`'s `Upload`) — a duck-type with just `send`
+ * is not sufficient.
+ */
+type S3LikeClient = S3Client;
+/** Configuration for the built-in S3 cold store. */
+interface S3ColdStoreConfig {
+    /** An `@aws-sdk/client-s3` `S3Client`. */
+    s3: S3LikeClient;
+    /** S3 bucket that holds the archive. */
+    bucket: string;
+    /**
+     * Optional key prefix applied to every object. The final key layout
+     * is `${prefix}/${threadKey}/${threadId}.json[.gz]` with leading
+     * slashes stripped. Defaults to `"threads"`.
+     */
+    prefix?: string;
+    /**
+     * Gzip the JSON payload before uploading and assume gzip on read.
+     * Defaults to `true` — message lists are highly compressible.
+     */
+    gzip?: boolean;
+    /**
+     * Optional `Content-Type` override. Defaults to
+     * `application/json` (or `application/gzip` when `gzip: true`).
+     */
+    contentType?: string;
+}
+/**
+ * Build an S3-backed {@link ColdThreadStore}.
+ *
+ * One object per thread at
+ * `${prefix}/${threadKey}/${threadId}.json[.gz]`, JSON-encoded and
+ * gzip-compressed by default. The consumer owns the `S3Client`
+ * instance, so credentials, region, and endpoint configuration live
+ * outside zeitlich.
+ *
+ * @example
+ * ```typescript
+ * import { S3Client } from "@aws-sdk/client-s3";
+ * import { createS3ColdStore } from "zeitlich";
+ *
+ * const coldStore = createS3ColdStore({
+ *   s3: new S3Client({ region: "us-east-1" }),
+ *   bucket: "my-threads",
+ *   prefix: "prod/threads",
+ * });
+ * ```
+ */
+declare function createS3ColdStore(config: S3ColdStoreConfig): ColdThreadStore;
+
+export { type ColdThreadStore as C, type S3ColdStoreConfig as S, type ThreadSnapshot as T, type S3LikeClient as a, createS3ColdStore as c };