Architecture decisions¶
arc42 §9–§10.
9. Architecture decisions¶
The decisions ADR_0001 through ADR_0010 recorded in
the solution strategy are the
canonical architecture decision log for this framework. This section is a
needtable view for quick browsing.
ID |
Title |
Status |
Refines |
|---|---|---|---|
Spec scope — framework core + MQTT reference |
open |
||
Umbrella feature is a peer of FEAT_0010 |
open |
||
Both deployment shapes supported |
open |
||
Per-channel envelope size, declared in descriptor |
open |
||
Codec is a generic parameter on the connector |
open |
||
Explicit-builder plugin discovery |
open |
||
Plugin and gateway are both taktora-executor consumers |
open |
||
Routing carried as a typed struct |
open |
||
Lifecycle = ReconnectPolicy + ConnectorHealth |
open |
||
MQTT scope — realistic but bounded |
open |
||
Pre-allocate dispatch scratch at Executor::build time |
open |
||
Compile-time caps + hand-rolled fixed-block bitmap |
open |
||
ethercrab as the EtherCAT MainDevice library |
open |
||
Single MainDevice per gateway |
open |
||
Static PDO mapping declared at build time |
open |
||
Distributed Clocks bring-up is opt-in |
open |
||
Linux raw socket only in first cut |
open |
||
``taktora-connector-ethercat`` module decomposition |
open |
||
Tokio runtime owned by ``EthercatGateway``, joined on Drop |
open |
||
``EthercatConnectorOptions`` is a typed builder; PDO map declared as ``&'static [SubDeviceMap]`` |
open |
||
Verification harness — pure-logic unit tests + env-gated bus tests |
open |
||
Zenoh queries live on a concrete handle type, not the Connector trait |
open |
||
Stack-internal reconnect for Zenoh — no ReconnectPolicy |
open |
||
One ZenohRouting struct carries pub/sub QoS; query knobs on options |
open |
||
Reply framing uses a Zenoh-private 1-byte payload prefix |
open |
||
Process boundary as spatial isolation context |
open |
||
Bounded allocator as spatial-determinism anchor |
open |
||
Fixed-bucket histogram for percentile estimation |
open |
||
Harness as xtask, not CI gate |
open |
||
Shared no_std taktora-stats crate |
open |
||
Hybrid two-layer timing measurement |
open |
||
Motion-flavored adapted reference workload |
open |
||
Abort on framework-invariant violation; watchdog drives outputs safe |
open |
||
Parser separated from codegen (strict layering) |
open |
||
Two-trait runtime split (EsiDevice + EsiConfigurable) |
open |
||
PDO assignment alternatives as sum types |
open |
||
Future CANopen support via shared OD IR |
accepted |
||
Vendor extensions captured as opaque blobs |
open |
||
Object dictionary as static table, feature-gated |
open |
||
Use prettyplease, not rustfmt, for emit formatting |
open |
||
cargo subcommand for inspection, not proc-macro |
open |
||
Lift OD IR to fieldbus-od-core now |
open |
||
fieldbus-od-core stays data-only |
open |
||
Re-export from ethercat-esi, do not break it |
open |
||
INI backend choice — serde-derive façade |
open |
||
PDO entry dedup is structural, name-blind |
open |
||
Dummy entries skip into bit offsets, not padding fields |
open |
||
heapless::Vec<u8, 8> for PdoOut payload |
open |
||
Async only on configure, sync on frame path |
open |
||
JSON SDO-dump format with versioned schema |
open |
||
Adopt the log crate as workspace logging facade |
accepted |
||
Pure-Rust DLT via dlt-core; no libdlt FFI |
accepted |
||
Two-crate split (facade vs DLT backend) |
accepted |
||
Bridge existing tracing emitters via tracing-log |
accepted |
||
Console dev fallback when no daemon configured |
accepted |
||
Build-time codegen over runtime parsing |
open |
||
Positional addressing; alias and identity as bring-up assertions |
open |
||
Local-only ESI resolution; URLs are a vendor-and-pin step |
open |
||
Working-counter expectation derived only, never overridden |
open |
||
One file, one bus; multi-bus distribution deferred |
open |
||
std/POSIX baseline for the parser and OD-core crates |
accepted |
||
Object-safe EsiDevice, identity reuse, ethercrab behind SdoWrite |
accepted |
||
f64 + libm in the trajectory core; integer increments at the drive |
accepted |
||
Absolute-grid cyclic dispatch via Linux timerfd; self-computed epoll timeout fails on ms-rounding |
accepted |
||
Lateness grid anchored on scan count plus dispatcher skip signal |
accepted |
||
The ESI parser emits a faithful IR and never resolves configuration |
accepted |
||
Startup SDOs as a typed SubDeviceMap field |
accepted |
||
Joint per-device OpMode enum supersedes per-direction PDO-assignment alternatives |
accepted |
||
Per-phase dispatch dedup via the existing pending_cycle token |
accepted |
||
AttachmentMap — sorted-Vec O(log n) attachment-to-task resolution with lazy-learn dual identity |
accepted |
10. Quality requirements¶
The four quality goals (Fault isolation between pro... (QG_0001)–Uniform observable health a... (QG_0004)) form the root
of the quality tree. Concrete quality scenarios that test them are
authored as test directives in Connector framework — verification —
the verification artefacts are the operational form of the quality
tree. A future spec round may add an explicit quality-tree
architecture element if measurement targets (latency budgets,
throughput) become first-class.