@spec get_log(Skuld.Comp.Types.env()) :: Skuld.Effects.EffectLogger.Log.t() | nil

Get the current log from the environment

@spec handle(term(), Skuld.Comp.Types.env(), Skuld.Comp.Types.k()) ::
  {Skuld.Comp.Types.result(), Skuld.Comp.Types.env()}

Handle EffectLogger operations.

Currently handles:

• MarkLoop - Records loop iteration boundary, returns :ok

@spec mark_loop(atom()) :: Skuld.Comp.Types.computation()

Mark the start of a loop iteration with a loop identifier.

This creates a boundary in the effect log that enables pruning of completed loop iterations. The current env.state is automatically captured for cold resume. Only meaningful when used with with_logging(prune_loops: true).

Parameters

• loop_id - Atom identifying which loop this mark belongs to (module atoms work well)

Example

defcomp conversation_loop(state) do
  # Mark iteration start - env.state captured automatically
  _ <- EffectLogger.mark_loop(ConversationLoop)

  input <- Yield.yield(:await_input)
  state = handle_input(state, input)

  conversation_loop(state)
end

# Run with pruning - only last iteration kept in log
{{result, log}, _env} =
  conversation_loop(initial_state)
  |> EffectLogger.with_logging(prune_loops: true)
  |> Yield.with_handler()
  |> Comp.run()

@spec put_log(Skuld.Comp.Types.env(), Skuld.Effects.EffectLogger.Log.t()) ::
  Skuld.Comp.Types.env()

Put a log into the environment

@spec root_loop_id() :: atom()

Returns the root loop ID used for the implicit root mark.

@spec update_log(Skuld.Comp.Types.env(), (Skuld.Effects.EffectLogger.Log.t() ->
                                      Skuld.Effects.EffectLogger.Log.t())) ::
  Skuld.Comp.Types.env()

Update the log in the environment

@spec with_logging(
  Skuld.Comp.Types.computation(),
  keyword()
) :: Skuld.Comp.Types.computation()

@spec with_logging(Skuld.Comp.Types.computation(), Skuld.Effects.EffectLogger.Log.t()) ::
  Skuld.Comp.Types.computation()

Wrap a computation with effect logging.

Automatically wraps handlers already installed in the env with logging. Initializes the log and extracts it when the computation completes. The result is transformed to {original_result, log}.

This should be the INNERMOST wrapper (immediately after the computation in the pipe), so it can see handlers installed by outer wrappers.

Variants

• with_logging(comp) - Fresh logging, capture all effects
• with_logging(comp, opts) - Fresh logging with options
• with_logging(comp, log) - Replay from existing log
• with_logging(comp, log, opts) - Replay with options

Options

• :effects - List of effect signatures to log. Default is all handlers in env.

• :allow_divergence - (replay only) If true, allow effects that don't match the log.

• :prune_loops - If true (default), prune completed loop segments eagerly after each mark_loop/1 call. This keeps memory bounded during long-running computations. Set to false to preserve all entries (e.g., for debugging).

• :state_keys - List of env.state keys to include in EnvStateSnapshot captures. Default :all includes everything. Use this to filter out constant Reader state:

  state_keys: [{Skuld.Effects.State, MyApp.Counter}]

  This only captures the specified State keys, excluding Reader/other constant state.

• :decorate_suspend - If true (default), attach the current finalized log to Suspend.data[EffectLogger] when yielding. This allows AsyncRunner callers to access the log without needing the full env. Set to false to disable.

Example - Fresh Logging

{{result, log}, _env} =
  my_comp
  |> EffectLogger.with_logging()
  |> State.with_handler(0)
  |> Comp.run()

# Or specify which effects to log:
{{result, log}, _env} =
  my_comp
  |> EffectLogger.with_logging(effects: [State])
  |> State.with_handler(0)
  |> Reader.with_handler(:config)
  |> Comp.run()

Example - Replay

# First run - capture log
{{result1, log}, _} =
  my_comp
  |> EffectLogger.with_logging()
  |> State.with_handler(0)
  |> Comp.run()

# Replay - short-circuit with logged values
{{result2, _}, _} =
  my_comp
  |> EffectLogger.with_logging(log)
  |> State.with_handler(0)
  |> Comp.run()

assert result1 == result2

@spec with_resume(
  Skuld.Comp.Types.computation(),
  Skuld.Effects.EffectLogger.Log.t(),
  term()
) ::
  Skuld.Comp.Types.computation()

Resume a suspended computation from a cold (deserialized) log.

Re-runs the computation from scratch, short-circuiting completed effects with their logged values. When reaching the suspension point (the :started Yield entry), injects resume_value instead of actually suspending, then continues with fresh execution.

Parameters

• comp - The computation to run
• log - The log ending with a :started Yield entry (from suspension)
• resume_value - The value to inject at the suspension point
• opts - Options (same as with_logging/3)

Example

alias Skuld.Effects.EffectLogger.Log

# Original run - suspended
{{%Comp.Suspend{value: yielded}, log}, _} =
  my_comp
  |> EffectLogger.with_logging()
  |> Yield.with_handler()
  |> State.with_handler(0)
  |> Comp.run()

# Serialize and later deserialize
json = Log.to_json(log)
{:ok, cold_log} = Log.from_json(json)

# Cold resume with injected value
{{result, new_log}, _} =
  my_comp
  |> EffectLogger.with_resume(cold_log, :my_input)
  |> Yield.with_handler()
  |> State.with_handler(0)
  |> Comp.run()

@spec wrap_handler(module(), Skuld.Comp.Types.handler()) :: Skuld.Comp.Types.handler()

Wrap an effect handler with logging.

The wrapped handler will log each effect invocation, tracking:

• When the effect starts (creates entry in :started state)
• When the effect completes (marks entry as :executed with value)
• When the continuation is abandoned (marks entry as :discarded)

Parameters

• sig - The effect signature (module) for logging
• handler - The original handler function (args, env, k) -> {result, env}

Returns

A wrapped handler function with the same signature.

Example

logged_handler = EffectLogger.wrap_handler(State, &State.handle/3)

comp
|> Comp.with_handler(State, logged_handler)
|> EffectLogger.with_logging()
|> Comp.run()

@spec wrap_replay_handler(module(), Skuld.Comp.Types.handler()) ::
  Skuld.Comp.Types.handler()

Wrap a handler for replay mode.

During replay, if the next entry in the log queue matches this effect and can be short-circuited, returns the logged value directly. Otherwise, executes the handler normally.

Parameters

• sig - The effect signature (module)
• handler - The original handler function

Example

replay_handler = EffectLogger.wrap_replay_handler(State, &State.handle/3)

{{result, _log}, _env} =
  my_comp
  |> Comp.with_handler(State, replay_handler)
  |> EffectLogger.with_logging(previous_log)
  |> Comp.run()

@spec wrap_resume_handler(module(), Skuld.Comp.Types.handler()) ::
  Skuld.Comp.Types.handler()

Wrap a handler for resume mode.

Like wrap_replay_handler/2, but when encountering a :started Yield entry (the suspension point), injects the stored resume value instead of suspending.

The resume value is stored in env by with_resume/4 and cleared after use.

Parameters

• sig - The effect signature (module)
• handler - The original handler function

Returns

A wrapped handler function.