# `Minga.Buffer.EditSource`
[🔗](https://github.com/jsmestad/minga/blob/main/lib/minga/buffer/edit_source.ex#L1)

Identifies who made an edit to a buffer.

The rich source type flows through events, ghost cursors, and the edit
timeline. The undo stack uses a simpler atom-based source (see
`Minga.Buffer.State.edit_source`); use `to_undo_source/1` to bridge.

## Creating sources

Always use the constructor functions instead of building raw tuples:

    EditSource.user()
    EditSource.agent(session_pid, tool_call_id)
    EditSource.lsp(:elixir_ls)
    EditSource.formatter()
    EditSource.unknown()

Constructors validate arguments with guards (e.g. `session_id` must be a
pid, `server_name` must be an atom). Pattern matching on the raw shapes
is fine and encouraged; only construction should go through constructors.

## Source variants

- `:user` — interactive keystroke from the human
- `{:agent, session_id, tool_call_id}` — agent tool applying an edit
- `{:lsp, server_name}` — LSP-initiated edit (code action, rename)
- `:formatter` — format-on-save or explicit format command
- `:unknown` — source not determined (legacy code paths during migration)

# `t`

```elixir
@type t() ::
  :user
  | {:agent, session_id :: pid(), tool_call_id :: String.t()}
  | {:lsp, server_name :: atom()}
  | :formatter
  | :unknown
```

Rich edit source for events, ghost cursors, and edit timeline.

# `agent`

```elixir
@spec agent(pid(), String.t()) :: t()
```

Edit from an agent tool call.

# `formatter`

```elixir
@spec formatter() :: t()
```

Edit from format-on-save or explicit format command.

# `from_undo_source`

```elixir
@spec from_undo_source(Minga.Buffer.State.edit_source()) :: t()
```

Converts a simple undo source atom to the rich event source.

Used when Buffer.Server mutation functions are called without an explicit
source parameter, preserving backward compatibility.

Note: for `:agent`, the returned `session_id` is the Buffer.Server's own PID,
not an agent session PID. The undo stack doesn't preserve the original session
reference. Treat it as a sentinel indicating "some agent edit, origin unknown."

# `lsp`

```elixir
@spec lsp(atom()) :: t()
```

Edit from an LSP server (code action, rename, etc.).

# `to_undo_source`

```elixir
@spec to_undo_source(t()) :: Minga.Buffer.State.edit_source()
```

Maps a rich edit source to the simple atom used by the undo stack.

This bridge exists so the undo system can continue using atom-based
guards until Provenance Undo (#1108) migrates it to the rich type.

# `unknown`

```elixir
@spec unknown() :: t()
```

Source not determined (legacy code paths during migration).

# `user`

```elixir
@spec user() :: t()
```

Interactive edit from the human user.

---

*Consult [api-reference.md](api-reference.md) for complete listing*