feat: type Controller's mqttc by what the SDK calls on an injected client

[cayossarian]

Closes #8. Two module-level choices are still open at the end, each with a recommendation,
so agreeing is a merge rather than a task.

Updated after review — the rename is in (266e329)

Your split is better than what I proposed, and for a reason I had missed: putting the
general name on the general surface means a Device contract derives from the base, so
unsubscribe is never inherited. The wart doesn't get worn, it stops existing. The docstring
line "a second protocol deriving from this one" is now literally true rather than
aspirational.

• MqttTransport — publish, subscribe. The surface both injection points share.
• MqttControllerTransport(MqttTransport) — adds unsubscribe. What this PR wires.
• Both runtime_checkable, both exported; MqttClient satisfies each unchanged.

A Device-side contract is deliberately absent — it lands with the Device seam.
test_the_controller_contract_derives_from_the_shared_base pins the property that makes the
split worth doing: a two-member client satisfies MqttTransport and is rejected by
MqttControllerTransport.

The failure, reproduced

ebus-mqtt-client ships no py.typed, so MqttClient currently resolves to Any
downstream and Optional[MqttClient] accepts anything. That is the only reason injection
type-checks today. Dropping a py.typed into the installed ebus-mqtt-client simulates the
release #8 anticipates:

# consumer code: a client implementing publish / subscribe / unsubscribe
controller = Controller(mqtt_cfg={}, mqttc=HostOwnedClient())

BEFORE (main @ bd060d9):  error: Argument "mqttc" to "Controller" has incompatible type
                          "HostOwnedClient"; expected "MqttClient | None"  [arg-type]
AFTER:                    Success: no issues found in 1 source file

Re-run after the rename, so it is evidence about the merged shape rather than the first one.

Where the three surfaces come from

I mapped every MQTT-client call site in homie.py and ha/bridge.py to its enclosing class
before choosing. The same table derives your split: publish and subscribe appear on both
paths, unsubscribe only on the Controller path, is_connected / is_running only on the
Device path, start / stop only when the SDK owns the client.

Line numbers below are main @ bd060d9 (0.15.0), not this branch — evidence about
existing code. On the branch head they shift by +2 for Property/Device sites (the added
import) and +13 for Controller sites (that import, plus the _owned_client block and the
_connect_broker rewrite); re-verified after the rename. The start/stop snippets below
are the two lines this diff rewrites.

Member	Controller path (injectable)	Device / Node / Property path
publish	:2742, :2811, bridge.py:295	:787, :834, :1656, :1664, :1730, :1869
subscribe	×8 :2392–:2535, bridge.py:176	:957
unsubscribe	:2609, bridge.py:211	—
is_connected	—	:1473, :1501
is_running	—	:690, :744, :821, :1455
publish_and_flush	—	:1504
start	owned only — :2311	:691, :1456
stop	owned only — :2914	:1510

Under the flush change you described on #7 — _owns_client deciding both "flush?" and
"stop?" — that publish_and_flush row becomes owned-only too, which is what leaves a
Device contract at publish, subscribe, is_connected, is_running.

start and stop are unreachable for an injected client today, and that is enforced rather
than conventional:

2307    if self.mqttc:        # _connect_broker
2308        return            # injected → the start() at :2311 never runs
2913    if self._owns_client: # mqttc is None, fixed at construction
2914        self.mqttc.stop()

0.15.0 corroborates this from your side. Controller.__init__:2281-2284 on the disconnect
hook: "Only effective when the controller OWNS its client (constructed from mqtt_cfg); a
bring-your-own-client caller registers disconnect handling on its own client." The hook is
passed to MqttClient.from_config(...) at :2309, inside the owned branch — so it adds no
member to the injected-client surface.

Typing the parameter with the full client surface would therefore demand five methods the SDK
provably never calls there — including two whose non-invocation is the documented guarantee
of the feature. A consumer supplying a connection whose lifecycle it manages elsewhere would
have to stub them as pure ceremony.

Signatures mirror MqttClient exactly, Any on subscribe's callback included. Returns are
object because every call site discards them.

Correcting something I said in #8

#8 claimed "annotation only, nothing existing has to be edited." That was wrong, and the
gap is small but real: with self.mqttc typed as the protocol, start() and stop() no
longer resolve on it. Two behaviour-preserving edits:

• _connect_broker binds the SDK-built client to a local of the concrete type, so start()
  resolves. Assignment order is unchanged — both references are set before start(), so
  a start() that raises leaves self.mqttc exactly as it did before.
• Controller keeps that client in _owned_client, giving stop() a typed handle.
  _owns_client still decides; _owned_client is None precisely when a client was
  injected, which makes "never stopped" a property of the types rather than a promise in a
  comment.

Tests

Six in TestMqttTransportProtocols: MqttClient satisfies both protocols; both are exported
from the package root (a consumer who cannot name the type gains nothing); the derivation
holds and a two-member client is rejected by the Controller contract; a deliberately
three-member client is accepted and driven through start_discovery() and stop() without
either being called on it; and _owned_client is None when injected, set and cleared when
SDK-built.

pytest: 506 passed, on Python 3.14 and on 3.10 (the declared floor — your CI runs only
3.12, so I checked the boundary explicitly). ruff check . and ruff format --check . clean
on the pinned 0.15.21.

Relationship to the transport-seam discussion

Discussion #7 argues the
same principle from the producer side. This PR is the Controller half and does not depend
on it — every fact above comes from _owns_client, the early return in _connect_broker,
and the guarded stop(), all of which exist on main today. Noting it only so the narrowness
reads as deliberate rather than as an oversight.

Two things you might want to decide, with a recommendation for each

Module placement — recommend keeping transport.py. Only homie.py imports it today, so
homie.py would work. I'd still keep it separate, for one reason beyond the 2,906-line file:
transport.py imports nothing but typing, so it is a leaf any module can import without
cycle risk. Folding it into homie.py means anything wanting to name a transport type has
to import all of homie.py — ha/bridge.py already imports from ..homie (:49) and
currently duck-types its client via getattr/hasattr (:174, :209-210); a leaf module is
what would let it annotate instead. Cheap to move if you disagree — one file, no call sites.

_owned_client vs a narrower fix — recommend keeping it. A cast or an isinstance
assert at the stop() site would be a smaller diff. I'd keep the attribute: assert is
stripped under -O, so an assert there would buy the type checker a guarantee the runtime
does not actually make, and cast checks nothing at any time. _owned_client makes "an
injected client is never stopped" true by construction — it is None precisely when one was
injected — for the cost of one Optional[MqttClient] field. Say the word if you'd rather have
the three-line version.

[dcj]

Requesting one change before merge; full rationale is in discussion #7 (the transport-seam thread). Make MqttTransport the shared base and derive the role-specific contracts from it, rather than typing the consumer surface as MqttTransport directly:

• MqttTransport (base): publish, subscribe
• MqttControllerTransport(MqttTransport): adds unsubscribe — this PR's injection point
• MqttDeviceTransport(MqttTransport): adds is_connected, is_running — lands with the Device seam, not here

Two reasons. The general name goes to the general surface instead of the consumer-specific one. And because the future Device contract derives from the two-member base rather than the three-member consumer type, it never inherits unsubscribe, so the wart you flagged dissolves instead of being worn. MqttClient still satisfies all three structurally, and your docstring line about "a second protocol deriving from this one" becomes literally correct.

Everything else here is good as-is; the self.mqttc / self._owned_client split that makes "never started, never stopped" a property of the types is exactly the right move. Happy to merge as soon as the rename + base land.

[dcj]

This is exactly the split from discussion #7: MqttTransport is now the shared base (publish + subscribe), MqttControllerTransport derives and adds unsubscribe, and the docstring correctly notes a Device-side contract derives from the same base with is_connected/is_running and never inherits unsubscribe. The general name lands on the general surface, and the wart is gone.

Verified locally (this branch predates the 3.10-3.13 matrix, so its CI is ruff-only): full suite passes and ruff check + ruff format --check are clean. Nice split of self.mqttc (the transport) from self._owned_client (the concrete client start/stop resolve on).

Approving. The Device-side MqttDeviceTransport(MqttTransport) follow-up (plus widening Device.mqttc) is mine, on top of this once it lands.

[dcj]

Re-approving after syncing main in and adding the CHANGELOG entry for the transport Protocol typing. Full matrix (3.10-3.13) + ruff green. Merging on Bill's behalf.