# `LibTmux.Operation`
[🔗](https://github.com/libtmux/libtmux-elixir/blob/b72452c198917433229bdc266a68c163541b6127/lib/libtmux/operation.ex#L1)

A retained operation handle pinned to its original owner, tables and epoch.

`result/1` and `status/1` read local retained values. `await/2` owns a separate
bounded waiter; its timeout never stops the operation. `stop/1` requests
closure of the operation's entire connection epoch, including siblings.
It does not roll back effects or prove native cleanup.

Canonical results carry `outcome`, `certainty` and `evidence`. Completed,
failed, skipped and unknown outcomes remain values, including in bang APIs.
Bang functions raise only API or metadata errors. A command reply is distinct
from wire retirement and arbitrary program exit.

Normal reconnect preserves retained records until forget or expiry. Owner
replacement loses those tables; a handle never follows a replacement view.

# `command_result`

```elixir
@type command_result() :: %{
  outcome: :completed | :failed,
  certainty: :acknowledged,
  evidence: :command_reply,
  guard: LibTmux.Protocol.guard_id(),
  lines: [binary()]
}
```

A qualified command reply, independently of wire retirement or program completion.

# `option`

```elixir
@type option() :: {:timeout, pos_integer()}
```

A positive millisecond budget for one waiter or record-reclamation call.

# `result`

```elixir
@type result() :: command_result() | skipped_result() | unknown_result()
```

The immutable canonical outcome; failed, skipped and unknown outcomes remain values.

# `skipped_result`

```elixir
@type skipped_result() :: %{
  outcome: :skipped,
  certainty: :no_write,
  evidence: :cancelled | :timeout | :epoch_closed
}
```

A canonical no-write outcome, with the reason it was skipped before dispatch.

# `status`

```elixir
@type status() :: %{wire: wire(), result: result() | nil}
```

Retained wire progress and the canonical result, or nil while no outcome is established.

# `t`

```elixir
@opaque t()
```

A retained owner-bound operation handle; it is not a command result or a reservation.

# `unknown_result`

```elixir
@type unknown_result() :: %{
  outcome: :unknown,
  certainty: :unknown,
  evidence: :epoch_closed
}
```

An epoch closed without enough evidence to classify the operation's effects.

# `wire`

```elixir
@type wire() :: :unpublished | :unsent | :writing | :awaiting | :closing | :retired
```

Wire progress for this operation; retired wire does not prove connection cleanup.

# `await`

```elixir
@spec await(t(), [option()]) :: {:ok, result()} | {:error, LibTmux.Error.t()}
```

Waits for a canonical result under one positive millisecond timeout.

The default is 5000ms. Every call claims an independent bounded waiter slot,
including terminal operations; use `result/1` for immediate inspection.
Completed waiter copies survive record reclamation until this caller reads
them. Timeout, overload and caller death affect only this waiter.

# `await!`

```elixir
@spec await!(t(), [option()]) :: result()
```

Waits or raises API errors; canonical failed, skipped and unknown outcomes remain values.

# `forget`

```elixir
@spec forget(t(), [option()]) :: :ok | {:error, LibTmux.Error.t()}
```

Requests exact-record reclamation with a default 5000ms timeout.

Wire-active records cannot be forgotten. An owner-accepted request remains
owned after caller timeout. Successful reclamation invalidates this record
handle while preserving already-accepted waiter copies.

# `forget!`

```elixir
@spec forget!(t(), [option()]) :: :ok
```

Forgets the retained record or raises the same structured error.

# `result`

```elixir
@spec result(t()) :: :pending | {:ok, result()} | {:error, LibTmux.Error.t()}
```

Returns a canonical result, `:pending`, or a retained-context error.

# `result!`

```elixir
@spec result!(t()) :: :pending | result()
```

Reads a result or `:pending`; raises API errors, preserving all canonical outcomes.

# `status`

```elixir
@spec status(t()) :: {:ok, status()} | {:error, LibTmux.Error.t()}
```

Reads retained wire state and canonical result without contacting tmux.

# `status!`

```elixir
@spec status!(t()) :: status()
```

Reads retained status or raises the same structured error.

# `stop`

```elixir
@spec stop(t()) :: :ok | {:error, LibTmux.Error.t()}
```

Requests closure of the pinned epoch through reserved capacity.

Returns `:ok` for an already wire-retired operation or an accepted closure
request, and `{:error, error}` otherwise. Closure can affect sibling work;
success does not prove retirement or change the canonical result. A stale
handle cannot revoke a replacement epoch.

# `stop!`

```elixir
@spec stop!(t()) :: :ok
```

Requests epoch closure or raises the same structured error.

---

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