# `BB.Jido.Signal`
[🔗](https://github.com/beam-bots/bb_jido/blob/main/lib/bb/jido/signal.ex#L5)

Canonical mapping from `BB.PubSub` messages to `Jido.Signal` structs.

PubSub subscribers receive `{:bb, source_path, %BB.Message{}}`. This module
converts those into `Jido.Signal` structs with stable, queryable type strings
following the `bb.*` namespace.

## Naming convention

- `bb.state.transition` — robot state machine transitions (payload
  `BB.StateMachine.Transition`).
- `bb.safety.error` — safety hardware errors (payload
  `BB.Safety.HardwareError`).
- `bb.parameter.changed` — parameter updates (payload `BB.Parameter.Changed`).
- `bb.pubsub.<path>` — generic envelope for any other PubSub message, where
  `<path>` is the dotted source path (e.g. `bb.pubsub.sensor.joint_state`).

Source follows the `/bb/<robot_module>` convention for traceability.

# `from_pubsub`

```elixir
@spec from_pubsub(module() | nil, [atom()], BB.Message.t()) :: Jido.Signal.t()
```

Converts a `BB.PubSub` delivery into a `Jido.Signal`.

- `robot` is the robot module that owns the subscription (used to build the
  signal source URI; falls back to the robot recorded on the message itself).
- `source_path` is the publisher's full path as delivered by `BB.PubSub`.
- `message` is the `%BB.Message{}` payload.

# `source`

```elixir
@spec source(module() | nil) :: String.t()
```

Returns the canonical signal source string for a robot module.

# `type_for`

```elixir
@spec type_for([atom()], struct() | nil) :: String.t()
```

Returns the canonical signal type string for a given path/payload pair.

Specialised types are recognised for well-known payload modules so that
agents can subscribe to (for example) `bb.state.transition` regardless of
the path the publisher used.

---

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