# StateStore

> The pluggable persistence contract for Channel state, callbacks, transcripts, locks, deduplication, and queues.

`StateStore` is the asynchronous persistence boundary used by the Channels
runtime.

## Interface [#interface]

```ts
interface StateStore {
  kv: {
    get<T>(key: string): Promise<T | undefined>;
    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
    consume<T>(key: string): Promise<T | undefined>;
    delete(key: string): Promise<void>;
  };
  list: {
    append<T>(
      key: string,
      value: T,
      options?: { maxLen?: number; ttlMs?: number },
    ): Promise<number>;
    range<T>(key: string, start?: number, stop?: number): Promise<T[]>;
    trim(key: string, maxLen: number): Promise<void>;
    delete(key: string): Promise<void>;
  };
  lock: {
    acquire(
      key: string,
      options?: { ttlMs?: number },
    ): Promise<{ token: string } | null>;
    release(key: string, token: string): Promise<void>;
  };
  dedup: {
    seen(key: string, ttlMs: number): Promise<boolean>;
  };
  queue: {
    enqueue<T>(
      key: string,
      value: T,
      options?: {
        maxSize?: number;
        onFull?: "drop-oldest" | "drop-newest";
      },
    ): Promise<number>;
    dequeue<T>(key: string): Promise<T | undefined>;
    depth(key: string): Promise<number>;
  };
}
```

## Semantics [#semantics]

- `list.range` is oldest-first and uses non-negative, inclusive indices.
- `kv.consume` atomically returns and deletes one value. Concurrent callers
  must observe at most one non-`undefined` result.
- `list.append({ ttlMs })` sets the expiry for the whole list. An append without
  `ttlMs` preserves an existing expiry.
- `lock.acquire` returns `null` while another token holds an unexpired lock.
- `lock.release` must not release a lock owned by another or newer token.
- `dedup.seen` returns `false` for the first observation and `true` for a repeat
  inside the TTL.
- Queues are FIFO. The configured overflow policy must be deterministic.

Remote stores must support JSON-serializable values. `MemoryStore` preserves
objects by reference, but that behavior is not portable.

## Conformance test [#conformance-test]

```ts
import { runStateStoreConformance } from "@copilotkit/channels/testing";

runStateStoreConformance("postgres", () => createPostgresStateStore());
```

KV consumption, locks, deduplication, and queues must be atomic across processes. Use
project/Channel namespacing to prevent key collisions.

Pass the adapter through `createChannel({ store: { adapter } })`. See
[Persistence and scaling](/slack/persistence-and-scaling).
