# `Quiddity.Api`
[🔗](https://github.com/d-led/ex.quiddity/blob/main/lib/quiddity/api.ex#L1)

The engine's operations, as data — and the stubs generated from it.

Quiddity's Rust surface is a fixed list of functions, and a hand-written Elixir
stub for each is a place for the two to drift: a Rust operation nobody can call,
an Elixir function that raises `:nif_not_loaded` because the name moved. So the
list is written once here, and `Quiddity.Native` is generated from it at compile
time — the same shape as the Elixir libraries that generate a function per
Unicode property from a table (`:unicode_set`, `:tz`) rather than typing it out.

Two things come out of one table:

  * the stub of every operation (`define_stubs/0`), at the arity the Rust
    function has — a NIF whose arity disagrees with its stub is a call that can
    never succeed, and now cannot be *written*;
  * `operations/0`, which a test walks to prove every listed operation is
    loaded and answers, and which `Quiddity.Mcp` reads so a tool cannot name an
    operation the engine does not have.

What is *not* generated is the typed, documented wrapper in `Quiddity`: an
answer's shape is a fact about the operation (a handle, a JSON document, four
flat binaries) and a caller deserves that in the signature rather than in a
match.

# `answer`

```elixir
@type answer() :: :handle | :json | :binaries
```

What an operation answers.

  * `:handle` — `{handle, summary_json}`, a part opened;
  * `:json` — a JSON string;
  * `:binaries` — flat binaries plus a JSON note (`frame`, `mesh`, `samples`).

# `arg`

```elixir
@type arg() ::
  :path
  | :handle
  | :camera
  | :json
  | :point
  | :direction
  | :number
  | :index
  | :framed
  | :density
  | :part
```

What an argument is, as far as a stub is concerned.

# `operation`

```elixir
@type operation() :: %{
  name: atom(),
  args: [arg()],
  answer: answer(),
  summary: String.t()
}
```

# `arity`

```elixir
@spec arity(atom()) :: non_neg_integer() | nil
```

The arity an operation's stub has.

# `define_stubs`
*macro* 

Generates `Quiddity.Native`'s stubs: one function per operation, at the arity
the operation declares.

A stub that is never replaced by a NIF call raises `:nif_not_loaded`, which is
how Rustler says "this function is not here" — so the generated function is a
real stub, not a placeholder.

# `operation`

```elixir
@spec operation(atom() | String.t()) :: operation() | nil
```

One operation by name, or `nil`.

# `operations`

```elixir
@spec operations() :: [operation()]
```

Every operation this build wraps, in the order the docs read them.

---

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