# `Lotus.Preflight.Relations`
[🔗](https://github.com/elixir-lotus/lotus/blob/v1.1.0/lib/lotus/preflight/relations.ex#L1)

The preflight outcome: what Lotus knows about the relations a statement
touches.

The outcome is one of:

  * a list of `{schema, table}` relations preflight proved the statement
    touches — an empty list means it touches none;
  * `{:unrestricted, reason}` for an adapter that cannot name the relations
    a statement touches, when the host opted in;
  * `{:skipped, reason}` for a statement the adapter does not preflight.

The two tuples both mean "unknown". A consumer that gates on the list
matches `when is_list/1` and refuses any tuple rather than reading it as an
empty set.

`Lotus.Preflight.analyze/4` returns the outcome as a value, and
`Lotus.Runner` carries it down the pipeline explicitly. The process
dictionary functions below are kept for callers that still store an outcome
themselves; the runner neither writes nor reads them.

# `outcome`

```elixir
@type outcome() :: [relation()] | {:unrestricted, String.t()} | {:skipped, String.t()}
```

# `relation`

```elixir
@type relation() :: {String.t() | nil, String.t()}
```

# `clear`

```elixir
@spec clear() :: :ok
```

Clears the stored preflight outcome.

# `get`

```elixir
@spec get() :: outcome()
```

Retrieves the stored preflight outcome, or an empty list.

# `put`

```elixir
@spec put(outcome()) :: :ok
```

Stores a preflight outcome in the process dictionary.

# `take`

```elixir
@spec take() :: outcome()
```

Retrieves and clears the stored preflight outcome.

# `to_list`

```elixir
@spec to_list(outcome()) :: [relation()]
```

Narrows a preflight outcome to the list of relations it names.

An unknown outcome names none, so it narrows to `[]`. Column visibility
policies use this: a relation Lotus cannot name is a relation it cannot
write a policy for.

---

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