0.3.0 architecture: rs-matter integration model + traceability + skeleton#28
Merged
Conversation
Architecture, traceability, and code-skeleton foundation for the live
rs-matter integration that will ship as v0.3.0. The live wire
integration (mDNS, commissioning, fabric storage, attestation) is
explicitly out of scope and lives behind a follow-up PR.
What's in this PR
spar AADL extension
New spar/wohl_matter.aadl modeling the Matter Bridge thread set
(MdnsResponder, MatterStackEventLoop, CommissioningHandler,
MatterBridgePublisher, FabricPersistor) composed as
MatterBridgeProcess. wohl_nodes.aadl + wohl_home.aadl extended
to wire the bridge into HubNode.{RPi,MiniPC} and the StarterHome
deployment. spar parse + instance + analyze all clean: 0 errors,
120 pre-existing single-point-of-failure warnings on the
single-hub topology.
WIT signatures generated from AADL
spar/generated/ contains the spar codegen output (matter.wit
plus monitors/ota/fw for the existing processes). Per the
spar-generates-wit convention, these are derived artifacts; the
hand-crafted per-crate WIT files predate the convention and
continue to live under crates/wohl-*/wit/ for now. See
spar/generated/README.md for the regeneration recipe.
rivet typed traceability
Eight new artifacts:
- SWREQ-MATTER-002..005 — commissioning, multi-admin,
persistent fabric storage, bridged attribute publishing
- SWARCH-WOHL-007 — rs-matter implementation shape +
version-pin policy (refines SWARCH-WOHL-006)
- SWDD-MATTER-001 — MatterBridgeProcess thread set + cluster
mapping detailed design (refines SWARCH-WOHL-007)
- SWV-MATTER-001 — SW verification approach with explicit
rationale for skipping witness MC/DC and sigil signing in
this scoped PR
- UV-MATTER-001 — unit-verification of the existing crate
tests
rivet validate: PASS (1 pre-existing warning).
Code skeleton: rs-matter-backend feature + RsMatterBridge stub
New Cargo feature `rs-matter-backend` (no transitive deps yet —
rs-matter itself remains a future dep). New
crates/wohl-matter-bridge/src/rs_matter.rs with RsMatterConfig +
RsMatterBridge struct implementing MatterBridge. publish_reading
and publish_alert return unimplemented!() with a docstring
pointing the 0.3.x implementor at LoggingBridge for current use.
Three new unit tests; feature-on test count rises to 22.
PR #27 reviewer recommendations applied
DESIGN.md gains §7.4 "Unit-conversion contract" with a full
table mapping wohl-internal units to Matter wire encoding for
every cluster + attribute the bridge publishes. cluster.rs
StateValue doc now explicitly explains device-type-dependent
polarity (ContactSensor: true=closed; WaterLeakDetector:
true=leak). ActivePower doc explicit on milliwatts.
Verified line untouched
Zero edits to crates/wohl-{leak,temp,air,door,power,alert,ota,
fw-door-bench}/, proofs/verus/, or fuzz/. cargo kani -p wohl-alert
remains at 4/4 harnesses, 0 failures — same as main. The Matter
bridge lives wholly on the hub side, outside the verified
sensor/dispatcher boundary, exactly as SWARCH-WOHL-006 prescribes.
Oracles green
cargo +1.85.0 fmt -p wohl-matter-bridge --check OK
cargo +1.85.0 clippy -p wohl-matter-bridge -D warnings OK (no features)
cargo +1.85.0 clippy ... --features rs-matter-backend OK
cargo +1.85.0 test -p wohl-matter-bridge 19/19
cargo +1.85.0 test ... --features rs-matter-backend 22/22
cargo kani -p wohl-alert 4/4
spar analyze (StarterHome.Deployed) 0 errors
rivet validate PASS
What is NOT in this PR
No rs-matter Cargo dependency. The feature gate exists as a symbol
hook for the next PR; the live wire integration (commissioning,
fabric storage, attestation chain, mDNS responder) is 0.3.x scope.
cargo-deny advisory chain is unchanged; the RUSTSEC-2026-0110
ignore for bare-metal remains the only exception.
No witness MC/DC. The bridge is a regular Rust library, not a
Wasm component; witness operates on Wasm artifacts. Documented in
SWV-MATTER-001.
No new sigil-signed artifact. Architecture + traceability + a
feature-gated skeleton don't ship binaries; existing release.yml
cosign / SLSA chain stays in place for the eventual v0.3.0 tag.
Documented in SWV-MATTER-001.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Automated review for PR #28pulseengine/wohl: Verdict: 💬 Comment Summary: The pull request is approved. The changes are well-documented and follow the project's coding standards. Findings: 0 mechanical (rivet) · 4 from local AI model. Findings (4):
Generated by a local AI model and post-validated against a strict JSON contract. Each finding includes the verbatim line being criticised — verify by reading the file at the cited location. Reviewed at |
avrabe
added a commit
that referenced
this pull request
May 27, 2026
Track B critique round (3 independent cold reviewers — architectural, verification, Matter-domain) surfaced findings between PR #28 merge and the live rs-matter integration. This PR applies the corrections that would compound if left unfixed before extending the bridge. Fixes applied (B1-B8) B1 — cluster.rs: remove WaterLeakDetector category error The MatterCluster::WaterLeakDetector variant claimed cluster id 0x0048 — that id is actually the Smoke/CO Alarm cluster. Matter 1.2's water-leak support is a DEVICE TYPE (DTL 0x0043), not a separate cluster; the mandatory server cluster is BooleanState (0x0045). Variant removed from MatterCluster. `water_leak` alerts continue to map to BooleanState (0x0045) — no functional change. The device-type descriptor on the endpoint disambiguates polarity for the controller. test renamed to `water_leak_maps_to_boolean_state_on_water_leak_detector_device_type`. B2 — concentration MeasuredValue is float32, not int16 SWDD-MATTER-001 and DESIGN.md §7.4 said concentration clusters publish int16. The Matter App Cluster Spec defines ConcentrationMeasurement-family MeasuredValue as IEEE 754 float32 with a separate MeasurementUnit attribute (0x0008) declaring the unit. cluster.rs MeasuredValue doc + SWDD + DESIGN.md §7.4 corrected. TemperatureMeasurement remains int16 in 0.01 °C (unchanged, that part was already right). B3 — VOC unit mismatch acknowledged Wohl's ReadingKind::Voc carries a Sensirion-style index value (0..500 dimensionless), not a concentration. The Matter VOC cluster expects ppm/ppb/μg/m³. Publishing the index as if it were a concentration would mislead controllers. New DESIGN.md §7.5 lays out the three options (omit / vendor cluster / calibrated conversion) with a recommendation to omit until the calibration story is clearer. B4 — SWV-MATTER-001 status: approved → proposed The artifact lists 5 verification methods, none currently wired into CI (no chip-tool runner, no kill-restart test, no multi-fabric ACL test). `approved` overclaims. Status demoted to `proposed`; description gains a STATUS NOTE explaining the artifact is a plan, not evidence, until the live rs-matter PR adds IV-MATTER-001 integration tests. B5 — AADL c_attr direction: push/pull boundary documented The AADL `c_attr` connection (publisher → event_loop.attribute_in) models a push. rs-matter's actual API is pull/callback — when a controller subscribes, rs-matter calls the DataModel handler for the current attribute value. The live impl mediates by keeping a current-value cache; the publisher pushes into the cache and rs-matter pulls from it. The AADL model is correct as a model of the BRIDGE-INTERNAL flow; the wire-side pull happens beyond the AADL boundary inside rs-matter's runtime. Comment added explaining this so a reader doesn't expect the AADL to match rs-matter's wire API. B6 — SWDD-MATTER-001 thread set framed as logical, not 1:1 The artifact said "Each thread is a Rust task in the wohl-hub process when rs-matter-backend is active." That's wrong: some AADL threads collapse into trait impls (FabricPersistor → rs-matter's KvBlobStore callback), others may merge into a single tokio task. SWDD now explicitly frames the thread set as the logical concurrency model the AADL captures, with the AADL-to-Rust mapping deferred to the live integration PR. B7 — MSRV reality corrected DESIGN.md §3 had proposed a "hub-only MSRV override" by setting per-crate `rust-version` keys to 1.87 while the workspace stayed on 1.85. That doesn't isolate the toolchain in a single-Cargo.lock workspace: the resolver picks dependency versions consistently across the workspace, and rustc rejects the whole compile if any compiled crate needs newer rustc than the toolchain. §3 now lays out Option A (raise workspace MSRV to 1.87) vs Option B (move wohl-matter-bridge out of the main workspace). The call happens in the live integration PR. B8 — rs-matter dep plan: git-rev pin, not crates.io crates.io `rs-matter = "0.1.0"` is from July 2023 and predates the current API surface (no DirKvBlobStore, no Matter::init). The integration must use `git = "https://github.com/project-chip/rs-matter" rev = "<sha>"` with the sha pinned in this crate's Cargo.toml. DESIGN.md §3 updated to reflect this. Plus a few smaller fixups surfaced by the critics - DESIGN.md §4: commissioning window default 60 s → 180 s (60 s is within the Matter Core §5.4.2 minimum but tight for typical QR-scan UX). Setup code / QR encoding must use rs-matter's pairing-code encoders (Verhoeff-checksummed manual code, Base38-encoded TLV QR per Matter Core §5.1.3). - DESIGN.md §5: corrected ACL framing — Matter ACL cluster (0x001F) is fabric-scoped natively; rs-matter handles per-fabric subscription state; the bridge doesn't loop over fabrics itself. - DESIGN.md §7.1: endpoint-id allocation — endpoint id is u16, not constrained to 99/100/56 by Matter. Earlier flat-namespace proposal updated to either tagged-high-byte or register-on-demand. - DESIGN.md §7.6: new open question — PASE rate-limit ownership (wohl bridge or rs-matter?). SWREQ-MATTER-002's "rate-limit verified" wording verifies whichever component does it. - DESIGN.md §7.7: new open question — verified-line backpressure. The bridge runs as a trait call on wohl-hub's dispatcher thread. A slow / panicking publish_alert delays the next dispatcher iteration. Either document the liveness coupling or make publish_* non-blocking. Verified line untouched Zero edits under crates/wohl-{leak,temp,air,door,power,alert,ota, fw-door-bench}/, proofs/verus/, fuzz/, .github/. The fixes are documentation + one Rust enum variant removal in the host-side bridge crate. Kani harnesses unchanged. Oracles green cargo +1.85.0 fmt -p wohl-matter-bridge --check OK cargo +1.85.0 clippy -p wohl-matter-bridge -D warnings OK (no features) cargo +1.85.0 clippy ... --features rs-matter-backend OK cargo +1.85.0 test -p wohl-matter-bridge --lib 19/19 cargo +1.85.0 test ... --features rs-matter-backend --lib 22/22 spar parse (7 files) OK spar analyze (StarterHome.Deployed) 0 errors spar codegen wit unchanged rivet validate PASS (1 pre-existing warning) Follow-ups (tracked separately as a single issue) - 5 verified crates missing proptest blocks (air, door, power) - 5 verified crates missing fuzz targets - No mechanical "verified line untouched" CI gate - --locked drift unguarded on cargo test/kani jobs - RUSTSEC-2026-0110 ignore needs expiry/owner - AlertKind string re-parse → typed pass-through from wohl-hub - Bridge backpressure on dispatcher thread - MC/DC waiver pending wasm-componentization Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.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
Architecture + traceability + code-skeleton foundation for the live rs-matter integration that will ship as v0.3.0. The live wire integration (mDNS, commissioning, fabric storage, attestation chain) is explicitly out of scope here and lives behind a follow-up PR.
This PR walked the pulseengine-feature-loop (spar AADL → spar codegen WIT → rivet typed artifacts → oracle-gated code skeleton → clean-room verify), per the methodology. Steps 5 (witness MC/DC) and 6 (sigil) were assessed inapplicable and the rationale is recorded in
SWV-MATTER-001.What's in this PR
spar/wohl_matter.aadl(new): MdnsResponder, MatterStackEventLoop, CommissioningHandler, MatterBridgePublisher, FabricPersistor threads composed as MatterBridgeProcess.wohl_nodes.aadl+wohl_home.aadlextended to wire the bridge intoHubNode.{RPi,MiniPC}andStarterHome.spar/generated/{matter,monitors,ota,fw}.wit+README.mdexplaining the relationship to the hand-crafted per-crate WIT.SWREQ-MATTER-{002..005},SWARCH-WOHL-007,SWDD-MATTER-001,SWV-MATTER-001,UV-MATTER-001.rs-matter-backend(no transitive deps yet);crates/wohl-matter-bridge/src/rs_matter.rswithRsMatterConfig+RsMatterBridgeimplementingMatterBridge(publish methodsunimplemented!()).cluster.rsdevice-type-dependent polarity for BooleanState;ActivePowerdoc explicit on milliwatts.Oracles green
Verified line untouched
Zero edits to
crates/wohl-{leak,temp,air,door,power,alert,ota,fw-door-bench}/,proofs/verus/, orfuzz/. The Matter bridge lives wholly on the hub side, outside the verified sensor/dispatcher boundary, exactly asSWARCH-WOHL-006prescribes.Independent clean-room verification
Spawned a cold reviewer that validated the bundle against 26 falsifiable claims. 25/26 PASS; the one FAIL was that the sigil-skip rationale was missing from disk — added a paragraph to
SWV-MATTER-001's description in this same commit. Re-validated after the fix: PASS.Verdict from the reviewer: approve-with-honest-scope. Foundation is sound and matches every claim. AADL → WIT → rivet → code chain composes coherently (the AADL thread names match what SWDD references, the spar-generated WIT exports the same five symbols, cluster.rs is exhaustive over AlertKind variants).
What is NOT in this PR
rs-matterCargo dependency. The feature gate exists as a symbol hook for the next PR; the live wire integration (commissioning, fabric storage, attestation, mDNS) is 0.3.x scope.SWV-MATTER-001.release.ymlcosign / SLSA chain stays in place for the eventual v0.3.0 tag. Documented inSWV-MATTER-001.Test plan
RsMatterBridge::publish_*fromunimplemented!()into real rs-matter calls, lands the live commissioning/fabric flows, and tags v0.3.0.🤖 Generated with Claude Code