Causation.hs

-- | Smart constructors for the causation- and correlation-walking reads.
--
-- These wrap the 'Kiroku.Store.Effect.FindEvents' constructor with a filter
-- suited to a specific question:
--
-- * 'findCausationDescendants' — walk the causation graph forward from a
--   trigger event and return every event that descended from it.
-- * 'findCausationAncestors' — walk the causation graph backward from a
--   leaf event and return every event reachable by following
--   @causation_id@ upward.
-- * 'findByCorrelation' — return every event whose @correlation_id@ equals
--   the input.
--
-- All three reuse the existing partial indexes @ix_events_causation_id@ and
-- @ix_events_correlation_id@ on the @events@ table, so they do not require
-- any schema change.
module Kiroku.Store.Causation
  ( findCausationDescendants,
    findCausationAncestors,
    findByCorrelation,
  )
where

import Data.UUID (UUID)
import Data.Vector (Vector)
import Effectful (Eff, (:>))
import Effectful.Dispatch.Dynamic (send)
import GHC.Stack (HasCallStack)
import Kiroku.Store.Effect (Store (..))
import Kiroku.Store.Types

-- | Return the seed event and every event whose @causation_id@ chain leads
-- back to it, in ascending @global_position@ order. The seed event is
-- included as the depth-0 row when it exists; otherwise the result is
-- empty.
--
-- Uses the @ix_events_causation_id@ partial index. Cost is
-- @O(depth * log n)@ where @depth@ is the length of the longest chain
-- rooted at the seed and @n@ is the total event count.
findCausationDescendants ::
  (HasCallStack, Store :> es) =>
  EventId ->
  Eff es (Vector RecordedEvent)
findCausationDescendants eid = send (FindEvents (FilterCausationDescendants eid))

-- | Return the seed event and every ancestor reachable via @causation_id@,
-- in depth-ascending order (the seed is first, its immediate cause is
-- second, etc.). The seed event is included as the depth-0 row when it
-- exists; otherwise the result is empty.
findCausationAncestors ::
  (HasCallStack, Store :> es) =>
  EventId ->
  Eff es (Vector RecordedEvent)
findCausationAncestors eid = send (FindEvents (FilterCausationAncestors eid))

-- | Return every event whose @correlation_id@ equals the input, in
-- ascending @global_position@ order. Uses the @ix_events_correlation_id@
-- partial index.
findByCorrelation ::
  (HasCallStack, Store :> es) =>
  UUID ->
  Eff es (Vector RecordedEvent)
findByCorrelation cid = send (FindEvents (FilterCorrelation cid))