Link.hs

module Kiroku.Store.Link (
    linkToStream,
) where

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

{- | Link existing events into a target stream.

__Provisional API.__ No known consumer uses this function (audited
2026-06-11: zero usage in keiro, the only downstream framework). It is the
only public feature that requires the @stream_events@ junction-table layout,
which a future global-position migration may replace with a single-table event
layout (global position as a column on @events@); in that case this function
will be removed or redesigned (e.g. rehomed to a dedicated @stream_links@ side
table). If you have a real use case, surface it before depending on this. See
docs/architecture/global-position-migration-path.md.

Creates the target stream if it does not exist; otherwise appends
links to the existing target. Linking does not duplicate the event
payload — the @events@ row is shared, and only a new junction row in
@stream_events@ is created. Linked events keep their original
'Kiroku.Store.Types.GlobalPosition' and 'Kiroku.Store.Types.RecordedEvent.originalStreamId' /
'originalVersion' fields; the target's 'Kiroku.Store.Types.RecordedEvent.streamVersion'
reflects the link's position in the target.

Preconditions:

* Every supplied 'Kiroku.Store.Types.EventId' must reference an event
  that currently exists. Linking an unknown id (a typo, or an id that
  was hard-deleted) rejects the entire batch atomically — the target
  stream is left in its pre-call state — with
  'Kiroku.Store.Error.LinkSourceEventMissing'. (See EP-1 F3.)
* The target must not be soft-deleted. Linking to a soft-deleted target
  fails with 'Kiroku.Store.Error.StreamNotFound'. (See EP-1 F5.)
* The target must not be @$all@. @$all@ is the global read stream, and
  linking into it would bypass the append-only global ordering contract;
  the interpreter rejects this with
  'Kiroku.Store.Error.ReservedStreamName'.
* Linking the same event into the same target stream twice fails with
  'Kiroku.Store.Error.EventAlreadyLinked'.

Returns the target's 'Kiroku.Store.Types.LinkResult' — its id and the
position of the /last/ linked event in the target.

Empty input @[]@ is a no-op programming mistake; do not call.
-}
linkToStream ::
    (HasCallStack, Store :> es) =>
    StreamName ->
    [EventId] ->
    Eff es LinkResult
linkToStream targetStream eventIds = send (LinkToStream targetStream eventIds)