Persistence contract for Omni.Session.

Defines the adapter behaviour that storage backends implement, and the dispatch functions that Omni.Session (and applications) call.

A store is a {module, keyword()} tuple pairing the adapter module with its config. This is the canonical shape everywhere: users write it at Session.start_link(store: ...) time, Session threads it through internally, and applications stash it wherever they like.

store = {Omni.Session.Store.FileSystem, base_path: "/data/sessions"}

Omni.Session.start_link(store: store, new: "abc", agent: [...])
Omni.Session.Store.delete(store, "abc")

Configuring a store once in an application

The recommended path is to use Omni.Session.Manager with otp_app:, which reads the store from Application.get_env/3 for you:

defmodule MyApp.Sessions do
  use Omni.Session.Manager, otp_app: :my_app
end

# config/config.exs
config :my_app, MyApp.Sessions,
  store: {Omni.Session.Store.FileSystem, base_path: "priv/sessions", otp_app: :my_app}

# everywhere a session is needed
MyApp.Sessions.create(agent: [...])
MyApp.Sessions.delete("abc-123")

When configuration varies per environment, override in config/test.exs (etc.) using the same key.

Direct (non-Manager) usage

When sessions are started outside a Manager, the application owns the store tuple. A module attribute is enough for static configuration:

defmodule MyApp.Storage do
  @store {Omni.Session.Store.FileSystem, base_path: "/var/data/sessions"}
  def store, do: @store
end

Omni.Session.start_link(store: MyApp.Storage.store(), new: id, agent: [...])
Omni.Session.Store.delete(MyApp.Storage.store(), id)

For environment-specific configuration without a Manager, read the tuple from Application.get_env/3 inside the wrapper.

State categories

Persisted state falls into two categories, owned by different write paths:

The two write paths operate on disjoint keys. Adapters that persist both in a single file or row (the FileSystem reference does) can safely read-modify-write each side — it is key-splatting, not a semantic merge.

Error model

Store callbacks return {:error, term()} on failure; Session never halts on store errors. POSIX atoms (e.g. :enoent, :eacces) bubble up unwrapped from filesystem backends. Error reasons are adapter-specific.

Implementing an adapter

Implement @behaviour Omni.Session.Store and the six callbacks:

• save_tree/4
• save_state/4
• load/3
• list/2
• delete/3
• exists?/2

Configuration arrives as a keyword() (the second element of the store tuple). Adapters are free to validate or destructure it as they prefer.