feat: node_id callable so one device can carry two instances of a capability

[dcj]

Refs #47. The SDK half of reconciling panel-sim's wire/graph_builder with the DeviceTreeBuilder that shipped in 0.21.0.

The gap

_materialize hardcoded the Homie node id to the capability name:

device.add_node_from_dict(
    {"id": capability, "name": node_name(capability), "type": node_type(capability)}
)

node_type and node_name were already callables, so the id was the one part of a node a caller could not choose. That is fine until one device carries two instances of the same capability (two lugs, two meters), at which point the second silently lands on the first one's node.

The change

node_id: Callable[[str], str] on build_from_declarations and DeviceTreeBuilder, threaded through _materialize, defaulting to identity.

Renaming is all it does:

• the declaration's vocabulary stays capability
• the model group still comes from the spec
• the returned map is still keyed by the declared capability

So a caller who ignores it sees no change, which the 653 pre-existing tests confirm by passing untouched.

It pairs with model_group

node_id separates two instances on the wire; PropertySpec.model_group (0.21.0) separates them in the model. Using one without the other moves the collision rather than removing it, so the docstrings and doc/building-a-proxy.md say that outright rather than leaving it to be discovered.

test_two_instances_of_one_capability_coexist_on_one_device is the shape reduced to essentials: two lugs on one enclosure, one build_from_declarations call per instance, distinct node_id and distinct model_group, then both published and read back independently.

Why this is the whole SDK-side change

The design pass over graph_builder found its two unique capabilities (node-on-parent placement, and per-instance node-id templating) reduce to this one missing seam. With it:

• node-on-parent needs no placement enum in the SDK. It stops being a tree concern and becomes "add more nodes to a device that already exists", which build_from_declarations already does. The front end calls it against the parent with node_id=lambda cap: f"{prefix}-{cap}".
• Templating and single-capability collapse stay in the front end, where the manifest vocabulary lives, so the SDK never learns what an instance_id is.

Everything else graph_builder does is either already covered (topological sort falls out of recursive add(); parent-by-class resolution happens while building specs) or better left where it is (root construction from mqtt_cfg= / mqttc= is connection policy, and belongs to the caller).

Verification

• 658 tests pass (653 before, 5 new)
• ruff check and ruff format --check clean
• markdownlint clean on CHANGELOG.md and doc/building-a-proxy.md
• No README change: node_type and node_name are not documented there either, and that section defers parameter-level detail to the proxy guide

🤖 Generated with Claude Code