[lxsaah]

Description

Stage 4 of #391, into the #392 feature branch.

docs/aimdb-usage-guide.md

• New "Inputs and contracts: conventions" section, after "Links as values":
  • Inputs yield an event, and records are built with From<Event>. A device that sends its own payload is an input over a connection.
  • Device channels are owned, non-Clone values handed out by a board (NucleoInputs { b1 }), so using one twice is use of moved value.
  • Where the From<Event> impls live: the orphan rule, the driver/contract crate convention, and a newtype or .transform() when neither crate can.
  • What is checked where: a table of compile-time errors (E0277, E0382) and build() errors. "One input per record" stays a build() error, and fan-in is allowed.
• MQTT example: builder.connect(..) with a Linkable contract via subscribe / publish, including the needed Cargo.toml lines. It points to the raw builders for non-contract types.
• KNX example: kept on the raw link_from(..).with_deserializer(..).finish() builder, now labelled as the escape hatch.
• Embassy Quick Start: the button is a PushButton input, with ButtonPress: From<ButtonEvent> and .input(button), instead of source_with_context.
• Removed a duplicated "Using Connectors" heading.
• The Tokio examples now compile. aimdb_core::prelude doesn't exist, and the Tokio Quick Start and the KNX example also used APIs that have changed: an awaited produce(), subscribe().unwrap(), a deserializer without the context argument returning a Box, and db.run() on build()'s result. Both now use explicit imports, configure on a mut builder and builder.run(). The Quick Start drops the rand dependency it never declared.
• The versions are current. The Cargo.toml snippets and the version-pinning section move to aimdb-core 2.0, the adapters and MQTT 0.7.

Rustdoc

• Input states both conventions and adds a compile_fail,E0382 doctest for a device channel wired into two records.
• AimDbBuilder::connect shows publish for a contract next to OutboundLink::on with a serializer.

The Tokio Quick Start has no connector, so it doesn't use connect.

Checks

CI doesn't run on PRs into the feature branch, so I ran these locally:

• aimdb-core doctests (the new E0382 case among them)
• cargo doc with -D warnings for core and data-contracts
• cargo clippy on core (std,tracing,observability)
• the guide's Tokio Quick Start, KNX and MQTT examples, each built as a temporary example target in the workspace (tokio-mqtt-connector-demo / tokio-knx-connector-demo), without warnings, and removed again
• not compiled: the Embassy Quick Start, which targets embassy_rp, and that isn't in the workspace

Next

• Stage 5: changelog.

Related Issue

• Part of [FEAT] publish / subscribe for Linkable contracts, migrate the MQTT demos, document input conventions #391 / [FEAT] reg.input / reg.output with connection handles, so a wrong wiring is a compile error #388 (PR feat: reg.input / reg.output, connector handles and publish / subscribe (#388) #392)

🤖 Generated with Claude Code