docs: add external-interop architecture for THEME-K (#125) - #188
Merged
Conversation
New docs/INTEROP-ARCHITECTURE.md, mirroring RCP-ARCHITECTURE.md's role as a coordinating document for a change spanning multiple repos. Precedes any implementation of THEME-K (#125) and its six instances INTEROP-01 through INTEROP-07 (#147-152). Every claim in the current-state inventory was independently re-verified against the real .github/workflows/*.yml in each affected repo (RCP x4, LIN x3, MQTT x2, DDS x3, CAN x3, SOME/IP x1), not taken from the filing audit's own text. This surfaced two things the audit got wrong or missed entirely: - The audit claimed MQTT has no probe-then-skip pattern; both go-mqtt and rust-MQTT actually do gate their live-broker jobs behind a probe step, identical in spirit to the DDS/CAN pattern the audit called out separately as a problem. - go-DDS and rust-DDS's CycloneDDS interop jobs probe `docker pull eclipse-cyclonedds/cyclonedds:latest` -- a tag that, per the repos' own code comments, was never published to any public registry. These jobs plausibly never execute at all, not merely "sometimes skip" as the audit characterized probe-then-skip generally. cpp-DDS already fixed this by building the peer image locally from upstream source instead. Defines four ecosystem-wide conventions that resolve INTEROP-04, -05, -06, -07 as small, independent, low-risk PRs with no new vector set required: naming discipline (*-interop only for a genuine external peer; *-conformance for RELAY's own internal relay interop check; *-loopback/*-multiprocess for same-port self-tests, citing rust-CAN's existing can_two_process_interop/can_thirdparty_interop split as the reference example), exit-code discipline (no more `|| true` + grep-scraping -- rust-RCP and rust-LIN are the two violators), probe hardening sequenced after the DDS image-tag bug fix (harden a probe only once its target can genuinely succeed), and service-container- first applied as a principle rather than literal MQTT YAML (CAN's peer is a kernel device, DDS has no official image). Scopes but does not build INTEROP-01/02 (RCP and LIN external golden-vector harnesses): defines vector location (spec/vectors/external/), citation requirement (every vector traces to a TC18/ISO-17987 section reference or it provides none of the value this exists to add), harness shape (relay interop --external, reusing §20.1's existing equivalence-check machinery), and sequencing (RCP before LIN). Deliberately not authored here -- independently derived vectors are a careful, separately-scoped, multi-session effort on their own, not something to rush inside a coordinating doc. Investigation delegated to a background Explore agent reading every repo's real CI config directly; findings incorporated verbatim with file:line citations preserved in the doc's inventory table. Signed-off-by: Matt <47545907+SoundMatt@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Design document for THEME-K (#125) and its six instances INTEROP-01
through INTEROP-07 (#147-152), requested by the user before touching
any individual repo's CI. Mirrors
RCP-ARCHITECTURE.md's role as acoordinating document for a change spanning multiple repositories.
This PR adds the design doc only — no CI changes in any repo yet.
Individual INTEROP-0x issues remain open, to be implemented as
separate follow-on PRs against this design.
What's in it
real
.github/workflows/*.ymlin every affected repo (RCP ×4, LIN×3, MQTT ×2, DDS ×3, CAN ×3, SOME/IP ×1) via a background
investigation agent — not taken from the filing audit's own text.
re-verification:
rust-MQTT gate their live-broker job behind a probe step.
(
eclipse-cyclonedds/cyclonedds:latest) that was never published— these jobs plausibly never execute at all, a stronger finding
than the audit's general "probe-then-skip" framing. cpp-DDS
already fixed this by building the peer locally instead.
as small, independent PRs requiring no new vector set: naming
discipline, exit-code discipline, sequenced probe-hardening, and
service-container-first-as-a-principle (not literal MQTT YAML
everywhere).
golden-vector harnesses — vector location, citation requirement,
harness shape, and sequencing (RCP before LIN), deliberately left as
a separate, careful, multi-session follow-on rather than rushed here.
Verification
go build/vet/testclean,gofmt -l .clean(no Go source touched, confirming no unintended side effects)
from a background agent that read the real CI YAML directly