@callback append_events(stream_id(), events :: [stored_event()], expected_revision()) ::
  {:ok, revision()} | {:error, :wrong_expected_version} | {:error, term()}

Appends events to a stream with optimistic concurrency. Returns {:ok, new_revision} or {:error, :wrong_expected_version}.

@callback load_events(stream_id()) ::
  {:ok, [stored_event()], revision()} | {:error, term()}

Loads all events from a stream. Returns {:ok, events, current_revision} or {:error, reason}.

The returned revision is the stream's current head revision. For a genuinely empty (non-existent) stream the returned revision is -1 and the event list is empty (WR-02).

@callback load_events(stream_id(), from_revision :: non_neg_integer()) ::
  {:ok, [stored_event()], revision()} | {:error, term()}

Loads events from a stream starting after from_revision.

The third tuple element is always the stream's current head revision, independent of the filter: when from_revision is at or beyond the head the event list is empty but the returned revision is still the head revision (not -1). The -1 empty revision is reserved for a genuinely empty stream, as in load_events/1 (WR-02).

@callback subscribe_from_position(
  stream_id :: stream_id() | :all,
  from_position :: integer(),
  subscriber :: pid()
) :: {:ok, reference()} | {:error, term()}

Asynchronously subscribes subscriber to receive events starting after from_position (exclusive). Use :all as stream_id to subscribe across all streams.

Pushes messages of type stored_event_with_position() to subscriber — a stored_event() map extended with a :global_position key (D-01).

Position semantics are exclusive: from_position: N delivers events with global_position > N. This matches Spear's from: semantics for EventStoreDB subscriptions. Starting from -1 replays all events from the beginning.

Returns {:ok, subscription_ref} on success, or {:error, reason} on failure.