Session stores

A session store is the only durable dependency PicoFlow has. It persists whole session documents and enforces optimistic concurrency; it does not interpret flows, steps, or restore policy.

The contract

export interface SessionStore {
  load(sessionId: string): Promise<SessionType | null>;
  create(flow: FlowType): Promise<SessionType>;
  save(sessionDoc: SessionType, expectedRevision: number): Promise<SessionType>;
  delete(sessionId: string, expectedRevision?: number): Promise<void>;
  close(): Promise<void>;
}

FlowSession wraps the store: it asserts the one-flow invariant, stamps saveOn, passes the document’s current revision as the expected value, and copies the returned revision back onto the in-memory document so later checkpoints in the same run use a fresh token.

Choosing a store

The store is selected by the SESSION_STORE environment variable, uppercased, and defaults to MEMORY. An unrecognised value throws No valid session store '<value>'. Use MEMORY, MONGO, COSMO, or SQLITE.

Tests and dependency injection can bypass configuration entirely:

const engine = await FlowEngine.create({
  sessionStore: new MemorySessionStore(),
  flows: [CustomerFlow],
});

The four bundled stores

SQLiteSession writes to a table named session, creates the parent directory if it is missing, and defaults to ignore/session/session.sqlite. The revision column is the compare-and-swap source of truth; older JSON-only rows are migrated by an ALTER TABLE on open. Mongo’s filter includes the flow name, so a store-level attempt to change the flow bound to a session ID also fails.

Deployment scope

SessionConflictError

export class SessionConflictError extends PicoFlowError {
  constructor(sessionId: string);
}

Thrown by a stale save, and by a delete that supplied a revision which no longer matches. FlowEngine returns a failure envelope for it and deliberately does not mark the stored session aborted — the winning document must remain untouched.

The other errors in this family:

All four extend PicoFlowError, so isSessionStoreError(error) recognises them.

Handling a conflict

There is no automatic replay. Blind retry is unsafe, because the losing attempt may already have called a model, sent a message, uploaded a file, or charged a card before it lost the save. Handle a conflict by returning a retryable error to the caller, reloading the latest state, deciding whether the original command is still valid, and retrying only through an idempotent path. See Concurrency and session conflicts.

Custom store conformance

import { SessionStoreConformanceUtil } from "@picoflow/core";

await SessionStoreConformanceUtil.run(() => new MyStore());

run(createStore) exercises only the public contract, so the same suite applies to every backend. It asserts that:

1. create returns revision 0 and load returns the stored revision;
2. save increments the revision;
3. ISO-looking strings inside user data survive a round trip unchanged;
4. a stale save and a stale revision-checked delete both throw SessionConflictError;
5. delete removes the document, after which load returns null;
6. two concurrent saves from one revision produce exactly one winner, and the loser throws SessionConflictError;
7. load returns a document that a Flow could consider stale, because restore policy is not the store’s job; and
8. saving a document whose flow.name is blank throws SessionFlowInvariantError.

A store that passes is safe to register through FlowEngine.create({ sessionStore }). Run it in CI against real infrastructure — the race check in step 6 is the one that matters most and the one an in-process fake will not exercise honestly.

See Persistence and session stores for operational guidance and Environment variables for the full configuration list.