Behaviour for pluggable storage backends.

A backend provides key-value storage across multiple logical tables. It is the half of LemonCore.Store that persists: the store owns the process and serialises access, the backend owns the bytes. Backends are plain modules — they have no process, no supervision and no lifecycle beyond init/1.

LemonCore.Store.EtsBackend (ephemeral), LemonCore.Store.SqliteBackend (durable) and LemonCore.Store.JsonlBackend (append-only files) are the built-ins.

Contract

Beyond the callback signatures, implementations must hold to the following. LemonPlatformTest.BackendCase turns each rule into a test; run it against your backend rather than re-deriving the rules from the built-ins.

• State is threaded. init/1 returns opaque state and every other callback takes it and returns it — including the read paths, which return {:ok, result, state}. The store always uses the state it was last handed. A backend may keep its real data outside the state (ETS table references, a database connection), but must never require the caller to discard the returned state.

• Tables spring into existence. table is any atom the caller chooses, possibly for the first time and possibly on a read. Reading an unknown table yields nil/[]; writing to one creates it. init/1 cannot know the set of tables in advance.

• Reads are total. get/3 on a missing key is {:ok, nil, state}, never an error. A stored nil is therefore indistinguishable from an absent key through get/3 — list/2 is where the difference shows, and it must show there.

• Writes are idempotent, deletes are forgiving. put/4 overwrites silently; delete/3 on an absent key succeeds. put_new/4 is the only conditional write, and {:exists, state} must leave the stored value untouched — it is the store's compare-and-set primitive, which idempotency keys depend on.

• Terms round-trip. Keys and values are Erlang terms: binaries (including non-ASCII), atoms, numbers, tuples, nested maps and lists must come back equal. Backends that serialise inherit their encoding's limits; pids, references and functions are not required to survive.

Error reasons are backend-specific

Every {:error, reason} in this behaviour types reason as term(), and that is the honest description: the built-in SQLite backend answers with {:error, :sqlite_busy} and {:error, {:sqlite_init_failed, path, reason}}, a Redis backend would answer with something else entirely. Callers must not pattern-match on a reason to decide behaviour — treat any {:error, _} as "this operation did not happen" and log the reason. If a portable classification (retryable vs fatal) is ever needed it has to be added to the behaviour first.

No teardown callback

There is deliberately no close/1/terminate/2: LemonCore.Store never tells a backend it is going away, so a backend holding a connection or file handle must be able to lose it to process exit. SqliteBackend.close/1 exists but is not part of this behaviour and is not called by the store.