reckon_db_stream_path (reckon_db v5.0.0)
View SourceThe single source of truth for the Khepri stream layout.
reckon-db stores events under a **structural aggregate-type subtree** (DESIGN_STREAM_NAMESPACE.md, Model C):
USER: [streams, <<"ride">>, <<"abc…hex">>, PaddedVersion] -> #event{}
SYSTEM: [streams, <<"$link">>, <<"name">>, PaddedVersion] -> #event{}
DCB: [streams, <<"_dcb">>, SeqKey] -> #event{}The aggregate **type** (the user-id prefix, or the $-namespace for system streams) is a real Khepri path level rather than a leading substring of an opaque id. This makes type-scoped operations (list_streams, replay, links) navigate a subtree instead of scanning the whole store.
This module is the ONLY place that knows the 4-level shape. Every other module builds stream paths through these functions, so the layout lives in exactly one file. The opaque round-trip — a stream id written under event_path/2 must reconstruct byte-identical via stream_id_from_path/1 — is the load-bearing correctness property and is exercised directly by reckon_db_stream_path_tests.
The DCB pseudo-stream (_dcb) keeps its existing 2-level [streams, _dcb, SeqKey] shape (a flat seq-keyed log, not an aggregate); its paths are built by reckon_db_dcb_paths, but the readers here (stream_id_from_path/1) tolerate it because global reads span both depths.
Summary
Functions
Pattern matching every regular (user/system) event leaf across the store: [streams, *, *, leaf-with-data]. This is the 4-level regular shape ONLY — the 2-level DCB log is at a different depth and must be queried separately (see reckon_db_streams global readers).
Khepri path of a single event: [streams, Type, Id, PaddedVersion].
Reconstruct the opaque stream id from a Khepri path. The inverse of event_path/2 / stream_path/1. Tolerates the 2-level DCB node (returns the reserved _dcb id) so global readers spanning both depths can label every result.
Khepri path of the aggregate node (all versions live beneath it): [streams, Type, Id]. Used by exists/delete and version counting.
The aggregate-type node for a stream id (<<"ride">>, <<"$link">>). Raises for ids that don't decompose.
Pattern matching every aggregate-id node of one type: [streams, Type, *]. Used by links to navigate a type subtree (order-*) instead of scanning the whole store.
Pattern matching every version node of one stream: [streams, Type, Id, *]. Used by get_version (count).
Functions
-spec all_events_pattern() -> khepri_path:native_pattern().
Pattern matching every regular (user/system) event leaf across the store: [streams, *, *, leaf-with-data]. This is the 4-level regular shape ONLY — the 2-level DCB log is at a different depth and must be queried separately (see reckon_db_streams global readers).
-spec event_path(binary(), binary()) -> khepri_path:native_path().
Khepri path of a single event: [streams, Type, Id, PaddedVersion].
Raises {invalid_stream_id, StreamId} for ids that don't decompose (including the DCB pseudo-stream, whose paths are built elsewhere).
-spec stream_id_from_path(khepri_path:native_path()) -> binary().
Reconstruct the opaque stream id from a Khepri path. The inverse of event_path/2 / stream_path/1. Tolerates the 2-level DCB node (returns the reserved _dcb id) so global readers spanning both depths can label every result.
-spec stream_path(binary()) -> khepri_path:native_path().
Khepri path of the aggregate node (all versions live beneath it): [streams, Type, Id]. Used by exists/delete and version counting.
The aggregate-type node for a stream id (<<"ride">>, <<"$link">>). Raises for ids that don't decompose.
-spec type_streams_pattern(binary()) -> khepri_path:native_pattern().
Pattern matching every aggregate-id node of one type: [streams, Type, *]. Used by links to navigate a type subtree (order-*) instead of scanning the whole store.
-spec versions_pattern(binary()) -> khepri_path:native_pattern().
Pattern matching every version node of one stream: [streams, Type, Id, *]. Used by get_version (count).