Solution strategy

arc42 §4.

The framework’s shape is the consequence of ten architectural decisions made during brainstorming. Each decision is captured here as an ADR that :refines: the requirement or feature it answers.

Architecture Decision: Spec scope — framework core + MQTT reference ADR_0001

status: open refines: FEAT_0030 links incoming: RISK_0001

Context. Four protocol connectors (MQTT, OPC UA, gRPC, ADS) and three codecs (JSON, Protobuf, MessagePack) were on the table. Each protocol introduces its own design quirks; specifying all four in one round risks the spec drifting into protocol-specific minutiae. Decision. This spec covers the framework core plus MQTT as the reference connector. OPC UA / gRPC / ADS get follow-on specs reusing the same five contracts. Consequences. ✅ Spec stays focused on the framework’s contracts. ✅ MQTT exercises every contract (codec, routing, health, reconnect) end-to-end. ❌ Other connector specs are blocked on this one landing.

Architecture Decision: Umbrella feature is a peer of FEAT_0010 ADR_0002

status: open refines: FEAT_0030

Context. PLC runtime heart on iceoryx2 (FEAT_0010) “PLC runtime heart” is the existing top-level umbrella, with Fieldbus integration interface (FEAT_0023) “Fieldbus integration interface” as a sub-feature. The connector framework is broader than fieldbus (MQTT and gRPC are application-protocol level). Decision. Add Connector framework (FEAT_0030) “Connector framework” as a peer top-level feature, not under PLC runtime heart on iceoryx2 (FEAT_0010). Fieldbus integration interface (FEAT_0023) later :refines: Connector framework (FEAT_0030) when an ADS connector spec lands. Consequences. ✅ Honest semantics — the framework is general purpose, not PLC-bound. ❌ The spec now has two top-level umbrellas, which the overview page should explicitly explain.

Architecture Decision: Both deployment shapes supported ADR_0003

status: open refines: FEAT_0035

Context. Gateway-as-separate-process gives fault isolation (Fault isolation between pro... (QG_0001)); gateway-as-tokio-task is operationally simpler (one binary, one signal handler). Different consumers want different trade-offs. Decision. Define the framework so the same envelope/iceoryx2 contract works in either deployment. The host wires the gateway as a tokio task or a separate binary using identical code; only process-startup differs. Consequences. ✅ Fault-isolation-conscious deployments and single-binary deployments share one framework. ❌ Both paths must be tested; shutdown coordination is specified twice (in-process, out-of-process), but the SHM mechanics are unchanged.

Architecture Decision: Per-channel envelope size, declared in descriptor ADR_0004

status: open refines: REQ_0201 links incoming: RISK_0003

Context. A universal 64 KB envelope (the C# Apex.Ida pattern) wastes shared memory for small messages and refuses large ones. iceoryx2’s typed services support per-service payload sizes. Decision. ChannelDescriptor carries a per-channel max payload size (via const generic N); each iceoryx2 service is typed on ConnectorEnvelope<N> for its compile-time-chosen N. Consequences. ✅ Memory sized to the workload. ✅ Type system prevents publishers and subscribers from disagreeing on size. ❌ Different channels are different types; const-generic monomorphisation could grow code size if many channel sizes are used (see Const-generic monomorphisat... (RISK_0003)).

Architecture Decision: Codec is a generic parameter on the connector ADR_0005

status: open refines: REQ_0211 is refined by: ARCH_0030

Context. Two clean alternatives existed: type-erased Box<dyn PayloadCodec> (runtime-swappable, erased_serde indirection) or generic-on-connector (MqttConnector<C>, compile-time-monomorphised). Decision. Generic-on-connector. Concrete connector types are MqttConnector<JsonCodec>, MqttConnector<MsgPackCodec>, etc. Consequences. ✅ Zero dynamic dispatch on the hot path. ✅ Codec errors carry a static format_name. ❌ Cannot swap codec at runtime; code must rebuild to change codec for a connector.

Architecture Decision: Explicit-builder plugin discovery ADR_0006

status: open refines: REQ_0270

Context. Two alternatives: inventory-crate compile-time registration (link-time globals collect ConnectorRegistration entries) versus an explicit builder (ConnectorHost::builder() .with(MqttConnector::<JsonCodec>::new(...)).build()). Decision. Explicit builder. Matches taktora-executor’s existing Executor::builder() idiom. Consequences. ✅ One file you can grep for the wiring; no link-time global state alongside the compile-time generics. ❌ Adding a connector requires rebuilding the host (already true given Codec is a generic paramete... (ADR_0005)).

Architecture Decision: Plugin and gateway are both taktora-executor consumers ADR_0007

status: open refines: CON_0001 links incoming: RISK_0004

Context. Three options: tokio-only gateway (separate world from plugin), taktora-executor on both sides with tokio bridged in, or raw-iceoryx2 gateway emitting unified observability. Decision. Both halves are ExecutableItem-based. Tokio runs as a sidecar inside connector crates; taktora-executor’s Channel<T> bridges the two. One programming model, one observability surface, one shutdown story. Consequences. ✅ Observer and ExecutionMonitor cover the gateway for free. ✅ SIGINT-clean-exit story propagates without extra plumbing. ❌ The bridge is the place latency can be introduced; bridge-channel sizing matters.

Architecture Decision: Routing carried as a typed struct ADR_0008

status: open refines: REQ_0221

Context. Three positions: opaque channel name + side-channel YAML config; channel name + typed routing struct; channel name + key-value attribute bag. Decision. Typed routing struct (MqttRouting, OpcUaRouting, …) implementing the Routing marker trait, embedded in ChannelDescriptor. Consequences. ✅ Routing is part of the public, type-checked API. ✅ Catches misspelled / missing fields at compile time. ❌ Plugin code is connector-aware (no protocol-portable channels — see NO protocol-portable Channe... (REQ_0294)).

Architecture Decision: Lifecycle = ReconnectPolicy + ConnectorHealth ADR_0009

status: open refines: FEAT_0034

Context. Different protocol stacks own reconnect differently — rumqttc exposes raw connect events (fits a policy trait); tonic manages reconnect inside the channel (no hooks); OPC UA sessions sit in between. Decision. Provide both a ReconnectPolicy trait + default ExponentialBackoff (used by stacks that surface raw events) AND a ConnectorHealth state machine emitted via HealthEvent (uniform observability regardless of who owns reconnect). Consequences. ✅ Stacks that fit a uniform policy aren’t reinventing backoff; stacks that handle reconnect internally aren’t forced into a foreign mechanism. ❌ Two ways to get reconnect means new connector authors must pick the right one for their protocol.

Architecture Decision: MQTT scope — realistic but bounded ADR_0010

status: open refines: FEAT_0036

Context. “Reference connector” must exercise enough of the framework’s contracts to validate them, without ballooning into MQTT-protocol-minutiae territory. Decision. Pub+sub, QoS 0+1, retained messages, wildcard subscriptions, username/password auth, optional TLS, MQTT 3.1.1. Defer: QoS 2, MQTT 5, LWT, persistent sessions, client-cert TLS. Consequences. ✅ Each deferred feature exercises framework contracts — adding them later doesn’t reshape the framework. ❌ MQTT 5 user-properties / shared-subscriptions adoption is blocked on a follow-on spec.

Architecture Decision: ethercrab as the EtherCAT MainDevice library ADR_0020

status: open refines: FEAT_0041

Context. EtherCAT MainDevice options in Rust are ethercrab (pure Rust, std + no_std, actively maintained), soem-rs (FFI wrapper around the C SOEM stack), or hand-rolled. SOEM is the industry-standard C implementation, but pulling C dependencies and their build complexity into the workspace conflicts with the no-C-deps posture the rest of taktora adopts. Decision. Use ethercrab from the workspace. It is pure Rust, supports both std (tokio TX/RX task on Linux raw socket) and no_std (deferred), and exposes a typestate bring-up API (init_single_group → into_op) that maps cleanly onto the four EtherCAT bus states. Consequences. ✅ No C build dependencies; one cargo build gets everything. ✅ no_std deployment becomes possible without a second EtherCAT stack. ❌ ethercrab is pre-1.0, so API churn is a tracked risk. ❌ SOEM conformance test coverage is broader; ethercrab is validated against EK1100 / EL-series modules but uncommon vendor extensions may surface gaps.

Architecture Decision: Single MainDevice per gateway ADR_0021

status: open refines: REQ_0312

Context. An EtherCAT network is physically one segment per network interface; the MainDevice owns that segment’s TX/RX cycle. Multi-NIC support would require multiple MainDevices arbitrating shared cycle timing and working-counter state. Decision. Each EthercatGateway instance owns exactly one ethercrab::MainDevice bound to one network interface. Multi-NIC deployments instantiate multiple gateways with disjoint SHM service names. Consequences. ✅ Cycle timing, working-counter ownership, and Distributed Clocks bring-up have a single source of truth. ✅ Mirrors NO multi-broker / multi-ten... (REQ_0295) (one broker per MQTT gateway). ❌ Operators wanting one process to own two EtherCAT segments must instantiate two gateways (acceptable — rare configuration).

Architecture Decision: Static PDO mapping declared at build time ADR_0022

status: open refines: REQ_0314, REQ_0315

Context. EtherCAT SubDevice PDO mappings can be sourced two ways: (1) parsing an ESI / EEPROM XML descriptor per SubDevice at startup, or (2) declaring the mapping in application code at build time. ESI parsing is what TwinCAT and similar engineering tools do; it handles arbitrary vendor modules. Static declaration trades generality for compile-time type safety on the routing struct. Decision. The application declares each SubDevice’s PDO mapping as a static description in EthercatConnectorOptions; the gateway applies it during the PRE-OP → SAFE-OP transition via SDO writes to the sync-manager assignment indices 0x1C12 (RxPDO) and 0x1C13 (TxPDO). ESI parsing is out of scope. Consequences. ✅ EthercatRouting (EthercatRouting carries Sub... (REQ_0311)) becomes a compile-time-checked struct — bit offset, bit length, and PDO direction match the static map. ✅ No runtime XML parsing. ❌ Adding a new SubDevice model requires a code change, not a config-file swap. ❌ Out-of-tree SubDevices with unusual PDO assignments need manual mapping (acceptable — matches the rest of taktora’s compile-time-config posture).

Architecture Decision: Distributed Clocks bring-up is opt-in ADR_0023

status: open refines: REQ_0318

Context. DC sub-microsecond synchronisation matters for motion control and time-stamped sampling; many EtherCAT deployments (digital I/O, ramped analog, slow process control) don’t need it. DC bring-up adds a multi-pass register dance (BWR 0x0900, per-slave offset write to 0x0920, FRMW from 0x0910) and requires every SubDevice on the segment to declare 64-bit DC support. Decision. The gateway performs DC bring-up only when EthercatConnectorOptions::distributed_clocks is explicitly enabled by the application. Default is off. Consequences. ✅ Buses without DC-capable SubDevices work out of the box. ✅ Bring-up latency is lower when DC is unused. ❌ Motion-control applications must remember to enable DC. ❌ Two bring-up paths to test (with and without DC).

Architecture Decision: Linux raw socket only in first cut ADR_0024

status: open refines: REQ_0325

Context. ethercrab supports Linux raw sockets, NPCAP / WinPcap on Windows, and no_std direct-MAC drivers. Each adds porting work. EtherCAT in industrial deployments is overwhelmingly Linux; the production target is Linux. Decision. The first cut uses ethercrab’s std::tx_rx_task helper, which opens an AF_PACKET raw socket. Linux is the only supported host OS; the gateway process requires CAP_NET_RAW. Windows and no_std MCU deployments are deferred. Consequences. ✅ One bring-up path to test in the first cut. ✅ Deployment recipe is “install the binary, grant CAP_NET_RAW”. ❌ Windows-based engineering desks cannot run the gateway natively (they can run plugins; the gateway must live on Linux). ❌ Embedded MCU EtherCAT mainboards await a follow-on spec.

Architecture Decision: ``taktora-connector-ethercat`` module decomposition ADR_0025

status: open refines: FEAT_0041

Context. taktora-connector-ethercat (BB_0030) decomposes into plugin (EthercatConnector (sub-bloc... (BB_0031)), gateway (EthercatGateway (sub-block ... (BB_0032)), PDO mapping (PDO mapping (sub-block of B... (BB_0033)), and the tokio bridge (Tokio bridge for ethercrab ... (BB_0034)). An implementing crate can either place everything in one lib.rs (faster initial build, harder to navigate) or mirror the BB decomposition in module structure (one-to-one mapping to specs, slightly more setup). Decision. taktora-connector-ethercat mirrors the BB tree as sibling modules: plugin, gateway, pdo, bridge, options, and health. The public surface re-exports EthercatConnector from plugin, EthercatGateway from gateway, and EthercatConnectorOptions / EthercatRouting from options. Internal modules are pub(crate). Consequences. ✅ Each module maps to one BB, so the IMPL_ directive can refine its REQs at module granularity if future work needs finer-grained traceability. ✅ Test files under tests/ align with module names. ❌ One more layer of directory nesting than the smaller framework crates currently adopt; acceptable because the connector crate is the largest.

Architecture Decision: Tokio runtime owned by ``EthercatGateway``, joined on Drop ADR_0026

status: open refines: REQ_0321

Context. Tokio sidecar contained ins... (REQ_0321) requires the ethercrab TX/RX task to run on a tokio runtime contained inside the connector crate, with no tokio leakage into taktora-executor’s WaitSet thread. Three shapes are possible: (1) a global OnceCell<Runtime> shared across gateway instances, (2) a runtime owned per-EthercatGateway instance, joined on Drop, (3) a runtime spawned externally and handed to the gateway via a builder. Decision. Each EthercatGateway instance owns its own tokio::runtime::Runtime (multi-threaded, defaulting to one worker thread, configurable via EthercatConnectorOptions::tokio_worker_threads). The runtime is constructed in EthercatGateway::new and shut down via Runtime::shutdown_timeout in Drop with a 5-second budget (mirroring REQ_0244’s SIGINT clean-exit budget). Consequences. ✅ Lifecycle is one-to-one with the gateway — no global state, multiple gateways on one host are independent. ✅ Mirrors Single MainDevice per gateway (ADR_0021) (one MainDevice per gateway). ❌ Spawning two gateways doubles the tokio worker-thread count; operators wanting a shared pool must consolidate gateways or wait for a follow-on spec.

Architecture Decision: ``EthercatConnectorOptions`` is a typed builder; PDO map declared as ``&'static [SubDeviceMap]`` ADR_0027

status: open refines: REQ_0314, REQ_0315

Context. Static PDO mapping per SubD... (REQ_0314) requires the PDO mapping be declared by the application at build time via EthercatConnectorOptions. Two builder shapes are common in Rust: (1) Default + public mutable fields, (2) a fluent typed builder with with_* methods returning Self. The PDO map itself can be a heap Vec<SubDeviceMap> or a &'static [SubDeviceMap] declared in application code. Decision. EthercatConnectorOptions is a typed builder (EthercatConnectorOptions::builder()...with_subdevice(...).build()) matching ConnectorHost builder API (REQ_0270)’s ConnectorHost::builder() idiom. The PDO map is declared as &'static [SubDeviceMap] — held by reference so the application can place it in .rodata and the gateway needs no per-instance heap allocation for it. Individual SubDeviceMap entries reference &'static [PdoEntry] for the same reason. Consequences. ✅ No heap allocation for the PDO map after gateway construction (consistent with taktora-executor’s REQ_0060 posture for the steady-state hot path). ✅ Builder API parallel to the framework’s other connector options. ❌ Applications that need runtime-discovered PDO maps (e.g. EEPROM-parsed) must roll their own &'static storage or wait for a runtime-PDO follow-on spec.

Architecture Decision: Verification harness — pure-logic unit tests + env-gated bus tests ADR_0028

status: open refines: FEAT_0041

Context. EtherCAT reference connector (FEAT_0041) ships 16 TEST artefacts (TEST_0200..TEST_0215) verifying REQ_0310..REQ_0325. Six of those tests (TEST_0203, TEST_0205, TEST_0208, TEST_0209, TEST_0210, TEST_0215) exercise real bus state transitions, PDO mapping application, working-counter accounting, DC bring-up, or raw socket access — operations that need either an ethercrab MainDevice driving a real NIC or a mock that simulates SubDevice responses. An earlier draft of this ADR assumed ethercrab shipped a MockMainDevice; it does not (as of ethercrab 0.7), so the verification strategy below is the actual approach taken. Decision. The connector’s testable logic is factored into pure-Rust modules — taktora-connector-ethercat ... (IMPL_0050)’s sdo (SDO write sequence generation), scheduler (cycle-time pacing with skip-not-catch-up semantics), wkc (working-counter health policy), bridge (bounded outbound / inbound bridges), health (health monitor + broadcast), options (typed builder with default-clamp), and routing — and unit-tested deterministically without ethercrab on the wire (TEST_0201, TEST_0204, TEST_0205-partial, TEST_0206, TEST_0207, TEST_0209, TEST_0210, TEST_0211-partial, TEST_0212, TEST_0213, TEST_0214 all land via this path). The remaining bus-driven tests (TEST_0202, TEST_0203, TEST_0205-full, TEST_0208 wire-side, TEST_0211-full, TEST_0215) live in crates/taktora-connector-ethercat/tests and are gated on the ETHERCAT_TEST_NIC environment variable; absent the variable they skip! rather than failing. CI runs the pure-logic tests on every push; the bus suite runs only on the gateway host (Linux + CAP_NET_RAW) as a manual workflow. Consequences. ✅ Every PR build is green on every developer machine and CI runner — no flaky “missing NIC” failures. ✅ The factored pure-logic modules (sdo / scheduler / wkc) carry the gateway’s load-bearing decision logic and are exhaustively tested. ✅ The bus suite still exists in-tree and is one ETHERCAT_TEST_NIC=eth0 away from running. ❌ The bus tests are not on the CI gate; a regression that only surfaces on real hardware will only be caught when the gateway host runs the suite — documented as an accepted risk. ❌ Without a mock, the bridge between ethercrab’s MainDevice API and the pure-logic helpers is itself untested at unit level; a follow-on may introduce a trait abstraction (BusDriver with a MockBusDriver impl in dev-dependencies) once the integration surface is stable enough for the abstraction not to churn.

Architecture Decision: Zenoh queries live on a concrete handle type, not the Connector trait ADR_0040

status: open refines: FEAT_0044

Context. The framework explicitly rejected protocol-portable channels (NO protocol-portable Channe... (REQ_0294)) and framework-level request/response matching (NO request/response matchin... (REQ_0290)). Three options for surfacing Zenoh queries existed: (a) concrete methods on ZenohConnector only; (b) extend the Connector trait with default-noop query methods; (c) re-use pub/sub plus app-level correlation. Decision. Option (a). ZenohConnector::create_querier and ZenohConnector::create_queryable are concrete methods that return Zenoh-specific handle types (ZenohQuerier, ZenohQueryable). The shared Connector trait remains unchanged. Consequences. ✅ Honors NO request/response matchin... (REQ_0290) / NO protocol-portable Channe... (REQ_0294). ✅ MQTT and EtherCAT connectors are not forced to invent no-op query plumbing. ❌ Plugin code wanting queries depends on the concrete ZenohConnector type, not the abstract trait — but that is exactly the framework’s existing posture for protocol-specific affordances (Connector ships its own rou... (REQ_0224)).

Architecture Decision: Stack-internal reconnect for Zenoh — no ReconnectPolicy ADR_0041

status: open refines: FEAT_0045

Context. Zenoh’s own session machinery handles scout and reconnect (peer mode) and reconnect-to-router (client mode). The framework provides ReconnectPolicy trait (REQ_0232) ReconnectPolicy and a default ExponentialBackoff, but also explicitly allows stack-internal-reconnect connectors to skip it (Stack-internal-reconnect co... (REQ_0235)). Decision. The Zenoh connector follows the stack-internal-reconnect path. ReconnectPolicy is not used; the gateway observes the Zenoh session’s alive/closed state and emits HealthEvent on every transition. An anti-req NO ReconnectPolicy on Zenoh... (REQ_0441) records the decision in the requirements page. Consequences. ✅ No duplicate retry policy contending with Zenoh’s own. ✅ Health emission stays uniform across all connectors (HealthEvent emitted on ever... (REQ_0234)). ❌ If a future user wants zenoh::open itself retried with backoff on initial config failure, that becomes a follow-on req — current behavior is to return Down and rely on application-level restart.

Architecture Decision: One ZenohRouting struct carries pub/sub QoS; query knobs on options ADR_0042

status: open refines: FEAT_0043

Context. Connector ships its own rou... (REQ_0224) already declares that each connector ships a single routing struct (MqttRouting, EthercatRouting, ZenohRouting) implementing the Routing marker. Zenoh has both pub/sub QoS knobs (congestion control, priority, reliability, express) and query-specific knobs (target, consolidation, timeout). Two options: (a) one routing struct carrying pub/sub QoS, with query knobs on ZenohConnectorOptions; (b) two distinct routing structs. Decision. Option (a). ZenohRouting carries { key_expr, congestion_control, priority, reliability, express }. Query-specific knobs (target, consolidation, timeout) live on ZenohConnectorOptions as session-wide defaults; ZenohQuerier exposes a builder to override the timeout per-call. Consequences. ✅ Preserves Connector ships its own rou... (REQ_0224)’s single-routing- struct rule. ✅ Mirrors MqttRouting carries topic, ... (REQ_0251) (MQTT carries QoS in routing). ❌ Per-channel query target / consolidation overrides require a builder method instead of a routing field — accepted tradeoff for type-system simplicity.

Architecture Decision: Startup SDOs as a typed SubDeviceMap field ADR_0103

status: accepted refines: REQ_0853 links incoming: REQ_0853

Context. Device configuration that must precede PDO assignment (motor current, operation-mode selection) has to be written before the 0x1C12/0x1C13 PDO assignment, while the SubDevice is still in PRE-OP. Decision. Such configuration is declared as a static startup_sdos slice on SubDeviceMap, applied in PRE-OP before the 0x1C12/0x1C13 assignment writes, rather than exposed via a runtime SDO escape hatch. Consequences. ✅ Bring-up stays fully declarative and reproducible from the checkout (consistent with with_sm_watchdog and explicit WKC). ✅ The same data drives the planned master-side motion runtime. ❌ Only SdoValue types (U8/U16) are expressible today; wider types land when a device needs them.

Architecture Decision: Reply framing uses a Zenoh-private 1-byte payload prefix ADR_0043

status: open refines: FEAT_0044

Context. Multi-reply Zenoh queries need an end-of-stream signal in addition to data chunks. Two options: (a) allocate one bit of ConnectorEnvelope’s reserved word (ConnectorEnvelope is a POD ... (REQ_0200)) — but that turns the reserved word into Zenoh-specific framework metadata; (b) carry a one-byte frame discriminator inside envelope.payload[0] — Zenoh-private, the framework remains agnostic. Decision. Option (b). Every envelope on the two reply-side iceoryx2 services ({name}.reply.in / {name}.reply.out) begins payload with a 1-byte discriminator: 0x01 = data chunk (followed by codec-encoded R), 0x02 = end of stream (empty body), 0x03 = gateway-synthetic timeout (empty body). The framework’s reserved word stays untouched. Consequences. ✅ Framework anti-goal (no inspection of envelope payload, no protocol-portable semantics in the reserved word) preserved. ✅ Future connectors can re-use the pattern without coordinating with the framework. ❌ Plugin-side ZenohQuerier::try_recv and ZenohQueryable::reply add a single-byte skip / write step relative to pub/sub channels.

Architecture Decision: UI connector is a passive, MVVM-shaped, language-neutral transport ADR_0107

status: accepted refines: FEAT_0092

Context. A local human-machine interface needs to observe and command a taktora-executor application without binding taktora to any one UI toolkit or runtime. The grill that produced UI connector (MVVM) (FEAT_0092) resolved five tightly-coupled forks, each with a rejected alternative: (1) the boundary’s reach — Rust-GUI-only vs language/runtime-agnostic; (2) who builds the ViewModel — a passive transport the app pushes into vs an active aggregator that reaches into executor/stats/other connectors; (3) the substrate — desugar onto the existing Connector trait vs a parallel ViewModelHost abstraction; (4) the publish granularity and RT posture — struct-per-ViewModel over a telemetry-export-style seqlock+pump split vs service-per-property or publishing from the RT task; (5) command semantics — acceptance-ack request/response vs fire-and-forget or a held-open completion future. These are not independent: the language-neutral choice forces a self-describing wire contract, which (with RT-safety) forces fixed-layout POD fields, which makes struct-per-ViewModel and a seqlock cell the natural fit. Decision. Adopt the following bundled posture for the UI connector, captured as the requirements cited: Language/runtime-agnostic, manifest-normative (:need:`REQ_0872`–:need:`REQ_0878`). The normative boundary is a self-describing manifest plus a closed, fixed-layout POD field type system (ViewModel fields restricted... (REQ_0858) / Closed self-describing sche... (REQ_0875)) carried as JSON over iceoryx2, with a contract hash (Manifest carries a contract... (REQ_0874)). Any language with an iceoryx2 binding binds dynamically; a Rust reference client is the v1 ergonomic consumer; per-language typed codegen is deferred. Passive transport, not an aggregator (:need:`FEAT_0093`). The connector knows nothing of taktora’s internal types; the application owns the ViewModel binding glue. Standard-source bridges (executor Observer telemetry, connector health) are reserved for optional -adapters crates, keeping the core decoupled — consistent with telemetry-export reaching the executor through a separate Observer seam rather than a connector. Desugared onto the ``Connector`` trait (:need:`REQ_0855`). UiConnector implements the shared trait (Routing = UiRouting, Codec = C, JsonCodec default); Property / Command / CanExecute are additive ergonomics over create_writer / create_reader. The trait is not modified — mirroring Zenoh queries live on a con... (ADR_0040)’s posture for Zenoh queries. Struct-per-ViewModel over a seqlock + non-RT pump (:need:`REQ_0856`, :need:`REQ_0860`, :need:`REQ_0861`). A ViewModel is one iceoryx2 service publishing one POD struct with latest-value (history-depth-1) semantics. The producer writes a seqlock cell on the (possibly RT) hot path with no allocation; a non-RT pump snapshots, JSON-encodes off-RT, and publishes at a configurable UI cadence with coalescing — the taktora-telemetry-export discipline (Connector cycle telemetry (FEAT_0038)) applied to bidirectional UI state. Acceptance-ack commands, at-most-once (:need:`REQ_0865`, :need:`REQ_0867`, :need:`REQ_0868`). Commands are request/response keyed by correlation_id returning Accepted / Rejected; progress and outcome are observed through properties, not a held-open call. Delivery is at-most-once via dedupe, with opt-in auto-retry only for commands flagged idempotent. Consequences. ✅ A WPF/.NET, web, C++, or Python UI can bind off the manifest on day one — the stated goal — without taktora shipping N language generators. ✅ The deterministic executor is never encoded on, blocked, or back-pressured by a UI consumer (Producer writes a seqlock l... (REQ_0860) / Command handler runs off th... (REQ_0870)). ✅ Health, lifecycle, ConnectorHost registration, envelope, and codec are inherited, not re-solved, by being a first-class Connector. ✅ The POD-only constraint makes each ViewModel’s envelope N derivable by the derive macro (Derive macro computes the e... (REQ_0859)) and the wire layout trivial for every language. ❌ Property loses per-field independence — a “property” is a field of a published struct, so per-field change is reconstructed by client-side diff (Client reconstructs per-fie... (REQ_0864)) and per-field metadata (timestamps, staleness) must be modeled inside the struct. ❌ POD-only fields exclude heap/variable-length state and data-carrying tagged unions in v1 (ViewModel fields restricted... (REQ_0858)); enums that carry data become an authoring pattern, not a language feature. ❌ Lossy coalescing suits state but not alarms/audit, so a lossless Event primitive is deferred to v2 with a reserved kind slot (UiRouting carries ViewModel... (REQ_0857)). ❌ Trust is OS/iceoryx2-mediated only in v1 (OS-mediated trust for v1 (REQ_0884)).

Architecture Decision: Reuse the CAN driver layer; own a userspace J1939 dispatcher ADR_0108

status: draft refines: FEAT_0098

Context. J1939 sits on top of CAN. Three ways to realise it: (A) depend on taktora-connector-can and reuse its CanInterfaceLike driver layer while adding a new PGN-aware dispatcher; (B) a standalone connector owning its own raw SocketCAN socket, duplicating the driver and mock; (C) a standalone connector over the Linux CAN_J1939 kernel socket family, letting the kernel do transport protocol, addressing, and address claiming. Decision. Take (A). taktora-connector-j1939 depends on taktora-connector-can at the crate level — reusing CanInterfaceLike, MockCanInterface / RealCanInterface, CanData / CanFrame, and CanGateway — and adds its own dispatcher with a userspace transport-protocol state machine (J1939 transport-protocol st... (BB_0101)) and address-claim state machine (J1939 address-claim state m... (BB_0102)). The kernel CAN_J1939 family is explicitly rejected (NO kernel CAN_J1939 socket ... (REQ_0901)). Consequences. ✅ The framework’s deterministic layer-1 mock story survives — MockJ1939Interface (MockJ1939Interface (sub-blo... (BB_0103)) wraps MockCanInterface, so TP reassembly and address claiming are tested without a kernel CAN module, on any host OS. ✅ No duplication of the CAN driver / FD handling / error classification. ❌ The connector carries its own TP and AC implementations rather than delegating to the kernel — more code to verify, justified by testability and portability. ❌ A hard dependency on taktora-connector-can’s public driver surface couples the two crates.

Architecture Decision: Two-tier delivery; ETP over a bounded growable slice channel ADR_0109

status: draft refines: FEAT_0098

Context. Every payload normally crosses iceoryx2 as a fixed-N ConnectorEnvelope<N> POD, and the project leans on bounded allocation (Bounded global allocator (FEAT_0040)). BAM and RTS/CTS top out at 1785 bytes and fit a fixed N; ETP can reach ~117 MB, which cannot live in a single fixed-N inline buffer. iceoryx2 0.8.1, however, supports slice ([u8]) payloads with runtime-sized loan_slice and a growable data segment (AllocationStrategy). Decision. Deliver J1939 in two tiers. Tier 1 — single-frame PGNs and BAM/RTS-CTS (≤ 1785 B) — rides the existing ConnectorEnvelope<N> typed channels, with N derived from the declared transport class (J1939Routing declares trans... (REQ_0891)). Tier 2 — ETP — rides the new large-payload slice channel (Large / variable-payload sl... (FEAT_0097) / Large-payload slice channel... (BB_0097)), zero-copy, the segment sized to the reassembled message and grown by AllocationStrategy::PowerOfTwo, bounded by a configurable max_etp_bytes; a session exceeding the cap is TP-aborted with a HealthEvent (ETP over the slice channel,... (REQ_0894), NO unbounded ETP reassembly (REQ_0903)). Consequences. ✅ ETP is genuinely supported without inlining a worst-case buffer into every sample, and the common hot path keeps its fixed-size POD envelope. ✅ The bounded-allocation invariant stays auditable — growth is capped and explicit, not open-ended. ❌ The connector has two delivery paths and the slice channel is new framework surface in taktora-connector-transport-iox (Large-payload slice channel... (BB_0097)), carrying its own requirements cluster (Large / variable-payload sl... (FEAT_0097)). ❌ ETP payloads are raw blobs on the slice path — no per-message typed codec.

Architecture Decision: Full J1939-81 address claiming in the first cut ADR_0110

status: draft refines: FEAT_0098

Context. A node on a shared J1939 bus needs a valid source address. The minimum is a configured static SA; J1939-81 defines the full claim/cannot-claim protocol (NAME-priority contention, null address 254, Request-for-AC, Address-Commanded). Decision. Implement the full J1939-81 claim state machine (J1939 address-claim state m... (BB_0102) / Full J1939-81 address claiming (REQ_0897)), not just a static SA. Claim state maps onto ConnectorHealth and gates transmission until Claimed (Claim state maps onto healt... (REQ_0898)). Consequences. ✅ The connector is well-behaved on a real shared bus — it arbitrates, cedes to higher-priority NAMEs, and honours commanded addresses. ✅ Claim state reuses the existing ConnectorHealth machinery rather than a parallel API. ❌ Larger first cut: a 64-bit NAME configuration, an arbitration state machine, and a TX interlock, each needing mock-backed tests — accepted over deferring claim to a follow-on.

Architecture Decision: rumqttc EventLoop owns MQTT reconnection ADR_0128

status: draft refines: FEAT_0036 links outgoing: REQ_0260

Context. An MQTT connection drops and must be re-established. The Zenoh reference connector (Zenoh queries live on a con... (ADR_0040) cluster) does not repair connections at all — it surfaces liveness as ConnectorHealth and delegates recovery to the underlying runtime. rumqttc already ships a reconnecting poll loop: its EventLoop re-establishes the TCP+MQTT session on its own schedule when polled, with configurable backoff. Decision. The gateway task pumps rumqttc::EventLoop and does not implement its own reconnect. Poll outcomes map onto the ConnectorHealth state machine (connection error → Connecting, ConnAck → Up). Reconnect/backoff knobs are surfaced through MqttConnectorOptions rather than a bespoke loop. Considered and rejected: driving reconnection ourselves via the core ReconnectPolicy / ExponentialBackoff seam — it duplicates logic rumqttc already owns and adds a second, separately-tested recovery path for no behavioural gain. Open end. rumqttc retries indefinitely, even on an auth-rejected ConnAck, so it never surfaces a terminal failure on its own. What drives the Down transition — a reconnect-attempt threshold versus mapping a rejected ConnAck directly to Down — is left unresolved here and must be settled when the reconnect requirements are authored. Down is contractually load-bearing: outbound sends return ConnectorError::Down and the framework persists no envelopes while down. Consequences. ✅ Least code on the recovery path, reusing the library’s battle-tested reconnect. ✅ Mirrors the connector framework’s “observe liveness as health, don’t repair in the connector” stance (Zenoh queries live on a con... (ADR_0040)). ❌ Backoff policy is bounded by what rumqttc exposes, not the core ReconnectPolicy seam — unified cross-connector backoff is forgone. ❌ The terminal-Down trigger is unspecified until the open end above is closed.

Architecture Decision: Wildcard inbound demux via a gateway-local matcher ADR_0129

status: draft refines: FEAT_0036 links outgoing: REQ_0254

Context. MQTT subscriptions may use wildcards (+ single-level, # multi-level). rumqttc delivers each inbound PUBLISH tagged with the concrete topic, not with the subscription that matched, so the connector must decide for itself which ChannelReader instances a message belongs to. Wildcard subscriptions supp... (REQ_0254) requires delivery to the matching instance(s) — plural — so one PUBLISH can fan out to several channels. The Zenoh connector offers no template: its inbound path is one callback per subscription, with no local topic matching. Decision. The gateway keeps a subscription table (filter → gateway-side writer) and registers each distinct filter with the broker exactly once (deduplicating overlapping filters so the broker never multi-delivers). On each inbound PUBLISH the gateway runs MQTT topic-matching locally against every registered filter and fans the message out to all matching channels. The table is reference-counted: an UNSUBSCRIBE is sent only when the last channel using a filter is dropped. Considered and rejected: (a) subscribing every channel’s filter verbatim and relying on the broker’s under-specified multi-delivery behaviour — risks duplicate wire deliveries that then fan out again, undedupable for QoS 0 which has no packet identity; (b) first-match-only delivery — violates Wildcard subscriptions supp... (REQ_0254)’s plural contract and silently drops messages for overlapping subscribers. Consequences. ✅ A single source of truth for fan-out that does not depend on broker-specific behaviour. ✅ Ref-counting keeps broker subscription state minimal and correct across channel teardown. ❌ The connector carries its own MQTT topic-matcher and a rewritten filter validator (+/# position legality, # terminal-only, leading-/ permitted) — the Zenoh KeyExprOwned validator does not transfer. ❌ A wildcard filter matching a high-traffic topic space fans out to every matching channel (see Wildcard demux pathological... (RISK_0005)).

Architecture Decision: Clean session with SUBSCRIBE replay on reconnect ADR_0130

status: draft refines: FEAT_0036

Context. MQTT CONNECT carries a clean-session flag. With a clean session the broker holds no state across a disconnect; with a persistent session (clean_session=false + a stable client-id) the broker retains subscriptions and queues QoS-1 messages across reconnects. This choice interacts directly with rumqttc EventLoop owns MQTT... (ADR_0128): under a clean session rumqttc will not restore subscriptions after a reconnect, so something must replay them. Decision. v1 connects with clean_session=true (configurable via MqttConnectorOptions). On every reconnect ConnAck the gateway replays all active SUBSCRIBEs from its reference-counted subscription table (Wildcard inbound demux via ... (ADR_0129)). QoS-1 messages arriving while disconnected are lost — accepted for v1. Considered and rejected: a persistent session — it removes the replay step and reduces message loss, but makes correctness depend on client-id uniqueness/stability and broker session-expiry configuration, adding failure modes that are hard to test deterministically with the mock session. Consequences. ✅ Deterministic, self-contained recovery with no dependence on broker-side session storage or client-id stability. ✅ The replay loop is straightforward to test against the mock session. ❌ Messages published to subscribed topics during a disconnect window are not recovered — persistent-session semantics are deferred to a follow-on. ❌ Every reconnect pays a re-subscribe round-trip.

Architecture Decision: JSON default codec; MsgPackCodec built as a prerequisite ADR_0131

status: draft refines: FEAT_0036 links outgoing: REQ_0250

Context. MqttConnector<C: PayloadCodec> is generic over the codec (Codec is a generic paramete... (ADR_0005)), so any PayloadCodec works without changing the connector. Today taktora-connector-codec ships JsonCodec and BinaryCodec; the original FEAT_0036 prose name-drops a MsgPackCodec that does not exist. Decision. JsonCodec is the documented default for MQTT examples and tests — human-readable, the MQTT-ecosystem norm, debuggable with mosquitto_sub. BinaryCodec remains available. A real MsgPackCodec (rmp-serde) is built behind a feature in taktora-connector-codec so the reference becomes true, sequenced as its own change that must land and publish before the MQTT connector cites it (the release-ordering rule that has bitten examples before). Considered and rejected: dropping the MsgPack mention entirely and leaving only JSON/Binary — simplest and matches current reality, but the maintainer chose to make the spec reference real rather than delete it. Consequences. ✅ The MQTT connector documents a sensible default and the MsgPack reference stops being a dangling promise. ✅ The new codec benefits every connector, not just MQTT, since codecs are generic. ❌ A prerequisite codec-crate change plus an rmp-serde dependency must be released ahead of MQTT — extra sequencing before the connector can land. ❌ Three codecs to keep working instead of two.

On this page

• Solution strategy