Cross-cutting and anti-goals¶
This page collects the framework-wide concerns that span every capability cluster: the deliberately rejected anti-goals, the umbrella-level traceability tables, and the safety refinements.
Anti-goals¶
The following requirements are explicitly rejected — captured for the
record so that future readers see what the framework deliberately does
not do, and why. Each rejected requirement :satisfies: Connector framework (FEAT_0030)
to keep the umbrella’s traceability complete.
The framework shall not match requests to responses using
|
The framework shall not introduce envelopes carrying |
The framework shall not persist outbound envelopes on disk or in
any durable store when the gateway is |
The framework shall not verify that plugin and gateway agree on
the channel’s payload type |
The framework shall not offer a channel type that is portable
between protocols (“write the same plugin code, swap MQTT for OPC UA
without code changes”). Plugin code imports its connector’s
|
A single |
The framework shall not catch panics from the tokio task or any protocol-stack worker. A panic shall propagate and abort the gateway process; restart policy is the host’s responsibility, matching taktora-executor’s existing posture. |
The CAN connector shall not parse Vector DBC files or perform bit-/signal-level extraction from CAN payloads. The connector is a raw-frame transport; typed signal codecs are a separate concern for a future feature layered on top. |
The CAN connector shall not implement ISO-TP (ISO 15765-2)
segmentation or J1939 (PGN, transport protocol, address claim).
Applications needing higher-layer CAN protocols shall either
layer them above |
The CAN connector shall not transport CAN-XL (CiA 610-1)
frames. The first cut targets classical CAN and CAN-FD only;
CAN-XL is deferred to a follow-on spec once the underlying
|
The CAN connector shall not expose CAN error frames as a
plugin-readable |
The CAN connector shall not set the kernel’s
|
Cross-cutting traceability¶
Every requirement in this chapter (excluding rejected anti-goals) carries a
:satisfies: link to its capability-cluster feat; every cluster feat
:satisfies: Connector framework (FEAT_0030). Architectural specifications
(spec directives) refining these requirements are emitted in
Connector framework — architecture (arc42). Verification artefacts (test
directives) are emitted in Connector framework — verification.
ID |
Title |
Status |
Satisfies |
|---|---|---|---|
Connector framework |
open |
||
Envelope transport |
open |
||
Codec abstraction |
open |
||
Connector trait and routing |
open |
||
Connection lifecycle |
open |
||
Process boundary deployments |
open |
||
MQTT reference connector |
open |
||
Host wiring and builder |
open |
||
Connector cycle telemetry |
open |
||
EtherCAT reference connector |
open |
||
Zenoh reference connector |
open |
||
Zenoh pub/sub |
open |
||
Zenoh queries |
open |
||
Zenoh session topology and health |
open |
||
CAN (SocketCAN) reference connector |
open |
||
CAN frame transport (classical + FD) |
open |
||
Multi-interface gateway and per-channel filtering |
open |
||
Bus health, error frames, and reconnect |
open |
ID |
Title |
Status |
Satisfies |
|---|---|---|---|
ConnectorEnvelope is a POD type |
open |
||
Per-channel max payload size |
approved |
||
Sequence number monotonically increasing |
implemented |
||
Timestamp recorded at send |
implemented |
||
Correlation id is a passive carrier |
implemented |
||
Zero-copy publish via iceoryx2 loan |
implemented |
||
One iceoryx2 service per channel direction |
implemented |
||
PayloadCodec trait |
implemented |
||
Codec is a generic parameter on connectors |
open |
||
JsonCodec is the default codec |
implemented |
||
Codec encode error variant |
open |
||
Codec decode error variant |
open |
||
Connector trait |
open |
||
ChannelDescriptor carries typed routing |
implemented |
||
Routing is a marker trait with bounds |
open |
||
create_writer / create_reader return concrete handles |
open |
||
Connector ships its own routing struct |
approved |
||
ConnectorHealth state machine |
approved |
||
subscribe_health returns a Channel of HealthEvent |
approved |
||
ReconnectPolicy trait |
open |
||
ExponentialBackoff default policy |
open |
||
HealthEvent emitted on every transition |
approved |
||
Stack-internal-reconnect connectors emit health uniformly |
approved |
||
Same envelope contract for both deployments |
approved |
||
In-process gateway is a tokio task |
open |
||
Separate-process gateway is a self-contained binary |
open |
||
Clean exit on SIGINT / SIGTERM on both sides |
open |
||
No app↔gateway control-plane envelopes |
approved |
||
MqttConnector implements Connector |
open |
||
MqttRouting carries topic, qos, retained |
open |
||
QoS 0 and 1 supported |
open |
||
Retained-message publish supported |
open |
||
Wildcard subscriptions supported |
open |
||
Username/password authentication |
open |
||
TLS is optional via cargo feature |
open |
||
MQTT 3.1.1 baseline |
open |
||
Tokio sidecar inside the gateway crate |
open |
||
Bridge channels are bounded |
open |
||
Outbound bridge saturation surfaces as BackPressure |
open |
||
Inbound bridge saturation drops frames and signals Degraded |
open |
||
Wire-round duration statistics |
draft |
||
Working-counter quality counter |
draft |
||
Freshness and staleness statistics |
draft |
||
Connector statistics query API |
draft |
||
Cycle-phase wait (slack) statistics |
draft |
||
Connector push fault semantics |
draft |
||
Absolute-grid cyclic dispatch (bounded long-run lateness) |
implemented |
||
Run-loop immunity to spurious wait interruptions |
implemented |
||
ConnectorHost builder API |
approved |
||
ConnectorGateway builder API |
approved |
||
Host registers connector items with the executor |
approved |
||
Optional Observer adapter for tracing |
open |
||
Tight dispatch-thread timer slack |
implemented |
||
NO request/response matching by the framework |
rejected |
||
NO app↔gateway control plane |
rejected |
||
NO persistent outbox or durable buffering |
rejected |
||
NO schema/contract enforcement across the boundary |
rejected |
||
NO protocol-portable Channel<T> |
rejected |
||
NO multi-broker / multi-tenant gateway |
rejected |
||
NO supervision / panic recovery |
rejected |
||
EthercatConnector implements Connector |
approved |
||
EthercatRouting carries SubDevice and PDO addressing |
implemented |
||
Single MainDevice per gateway instance |
approved |
||
Bus reaches OP before serving traffic |
approved |
||
Static PDO mapping per SubDevice |
approved |
||
PDO mapping applied during PRE-OP to SAFE-OP transition |
implemented |
||
Cycle time configurable with millisecond resolution |
implemented |
||
Missed cycle ticks are skipped not queued |
implemented |
||
Distributed Clocks bring-up is opt-in |
approved |
||
Working-counter-based health policy |
implemented |
||
Working-counter mismatch degrades health |
approved |
||
Tokio sidecar contained inside the connector crate |
approved |
||
Bridge channels are bounded |
approved |
||
Outbound bridge saturation surfaces as BackPressure |
approved |
||
Inbound bridge saturation drops PDUs and signals Degraded |
implemented |
||
Linux raw socket required on gateway host |
approved |
||
Outbound payload written to PDI bit slice per routing |
implemented |
||
Inbound payload read from PDI bit slice per routing |
implemented |
||
Per-channel routing registry on the gateway |
approved |
||
Asymmetric working counter declared per SubDevice |
implemented |
||
Distributed Clocks cycle path uses tx_rx_dc |
open |
||
Bus-level recovery on cycle error |
implemented |
||
Reconnect policy factory in connector options |
implemented |
||
Health transitions during recovery |
implemented |
||
ZenohConnector implements Connector |
approved |
||
ZenohRouting carries key_expr and pub/sub QoS fields |
open |
||
JsonCodec is the default codec for Zenoh |
approved |
||
Tokio sidecar contained inside the Zenoh connector crate |
implemented |
||
Zenoh bridge channels are bounded |
approved |
||
Outbound bridge saturation surfaces as BackPressure |
approved |
||
Inbound bridge saturation drops samples and signals Degraded |
open |
||
Zenoh zero-copy publish via iceoryx2 loan |
approved |
||
Zenoh gateway is byte-only on the inbound publish path |
approved |
||
ZenohConnector exposes create_querier and create_queryable |
implemented |
||
ZenohQuerier maps QueryId to envelope correlation_id |
approved |
||
ZenohQueryable correlates replies via correlation_id |
implemented |
||
Multi-reply per query supported |
implemented |
||
Reply stream end-of-stream framed in payload |
approved |
||
Query timeout sourced from options, overridable per-querier |
approved |
||
terminate(id) finalizes the upstream zenoh::Query |
implemented |
||
Codec applied to Q on send and to R on reply |
approved |
||
Reply-side inbound saturation drops chunks and signals Degraded |
open |
||
Zenoh session mode is a config knob |
implemented |
||
NO ReconnectPolicy on Zenoh session loss |
rejected |
||
HealthEvent emitted on every Zenoh session transition |
implemented |
||
Connect and listen locators surfaced to zenoh::Config |
open |
||
zenoh-integration cargo feature gates the real zenoh dep |
implemented |
||
MockZenohSession ships unfeature-gated |
implemented |
||
Linux, macOS, and Windows are supported host operating systems |
implemented |
||
Pure parse function with no I/O |
implemented |
||
no_std + alloc compatible |
rejected |
||
quick-xml + serde backend |
implemented |
||
Parser does not depend on ethercrab or codegen |
implemented |
||
IR carries identity, PDO maps, mailbox, DC, and OD |
implemented |
||
Vendor-specific extensions captured as opaque blobs |
implemented |
||
Parse errors carry line and column |
implemented |
||
CodegenBackend trait shape |
open |
||
Naming policy is owned by codegen, not the backend |
open |
||
Revision collision handled deterministically |
open |
||
Common PDO entry types deduplicated |
open |
||
Emission target is proc_macro2 TokenStream |
open |
||
Backend crate is the sole ethercrab dependency |
open |
||
One device struct per ESI device entry |
open |
||
Identity const emitted per device |
open |
||
Selectable PDO assignments emitted as a joint per-device OpMode enum |
implemented |
||
Each OpMode variant carries a per-mode inputs/outputs data struct |
implemented |
||
Generated module root exposes a registry |
open |
||
Generated code compiles under no_std + alloc |
open |
||
Default PDO assignment derived from Sm/Mandatory, not Fixed |
implemented |
||
Per-active-mode Rx/Tx PDO-index lists exposed for 0x1C12/0x1C13 |
implemented |
||
AlternativeSmMapping captured faithfully, never resolved |
implemented |
||
EsiDevice trait shape |
open |
||
EsiConfigurable trait shape for preop bring-up |
open |
||
Traits live in ethercat-esi-rt, not taktora-connector |
open |
||
Object dictionary emission is a default-off cargo feature |
open |
||
Process image access via bitvec BitSlice |
open |
||
SdoWrite abstraction keeps ethercrab out of the trait crate |
open |
||
Builder API shape |
open |
||
Output written to OUT_DIR |
open |
||
Cargo rerun-if directives emitted per ESI input |
open |
||
Generated output passes through prettyplease |
open |
||
cargo esi expand emits one device's generated code |
open |
||
cargo esi list enumerates devices in a glob |
open |
||
CLI shares the parser and codegen crates |
open |
||
Verifier ingests ESI XML plus SII binary |
open |
||
Diagnostic output names the differing field |
open |
||
Verifier reuses the parser |
open |
||
Verifier exits non-zero on mismatch |
open |
||
NO CAN / CANopen / EDS support in this round |
rejected |
||
NO proc-macro front-end |
rejected |
||
NO unification of EtherCAT and CANopen runtime traits |
rejected |
||
NO runtime XML parsing |
rejected |
||
NO modification of taktora-connector-ethercat runtime |
rejected |
||
NO automatic vendor library scraping |
rejected |
Safety refinements¶
The connector framework carries five TSRs from the SEooC safety concept (see Technical Safety Concept — TSRs):
Compile-time channel direct... (TSR_0005) (compile-time channel directionality) — implemented by taktora-connector-core (BB_0001), taktora-connector-host (BB_0005).
Bounded health-event latency (TSR_0006) (bounded health-event latency) — implemented by Zenoh session mode is a con... (REQ_0440), NO ReconnectPolicy on Zenoh... (REQ_0441), HealthEvent emitted on ever... (REQ_0442), Connect and listen locators... (REQ_0443), zenoh-integration cargo fea... (REQ_0444).
Single-publisher iceoryx2 t... (TSR_0007) (single-publisher iceoryx2 topology for SC channels) — implemented (iceoryx2 default).
Envelope sequence + CRC int... (TSR_0008) (envelope sequence + CRC integrity) — draft; current
ConnectorEnvelope<N>carries aCorrelationIdbut no sequence or CRC.Cross-process hosting mode (TSR_0009) (cross-process hosting mode) — draft; requires per-process iceoryx2 segment capability wiring at the
ConnectorGatewaylayer. See Process boundary as spatial... (ADR_0050).