[xameYeoh]

Summary

AirBeamSessionController is gone. In its place is AirBeamLink, a connection-only owner with suspend calls, and a connector seam that finally delivers measurements, so the RecordingEngine has a single stream to save. All of it is on feat/curr in three commits, and both Android and iOS build.

Commit	What
b76101a	SensorReading, V1 ASCII + Mini V2 binary parsers, credentials kept out of SessionConfig.toString()
2d60399	AirBeamLink replaces the controller; connector seam reworked (BLE, classic, composite); foreground service follows LinkState
b0d8d95	/docs/: legacy reconnect rules and live-reading formats recorded

The developer did not hand-copy this code: they asked me to do the work myself. The CLAUDE.md teaching-mode rule was set aside for this task, and the code should get a read-through review.

What was wrong

The nudge was right. The old controller rebuilt the legacy app's EventBus and listener shape on top of Flow, and the connector had real bugs underneath it.

Area	Problem	Effect
Controller API	dispatch(SessionAction): fire-and-forget, wrong-state actions silently ignored	Same contract as EventBus.post; callers couldn't learn the outcome
Controller state	7 mutable fields written from caller thread and Dispatchers.Default jobs	Races: a late Connected could overwrite Idle after disconnect
Reconnect	Invented 5-attempt cap with linear backoff; fired from Connected too; re-ran configure()	Not legacy behavior. Fixed sessions resent Wi-Fi credentials; Mini V2 would reject a second session config
Reconnect	startTimeMs reset on each reconnect	Session start time lost on every drop
Errors	Every ConfigResult became HandshakeFailed	UI could never say "wrong Wi-Fi password"
Logging	Data-class toString() of configs logged	Wi-Fi password and auth token in Logcat
Layering	SessionState.Recording without a session or measurements; live AirBeamConnection inside UI state	A second state machine beside SessionStatus; resource handle leaking to UI
Connector	No measurement stream at all; V2 notifications subscribed and discarded	Nothing for a RecordingEngine to save
Connector	Own CoroutineScopes never tied to the link; Kable Peripheral.close() never called; failed attempts not released	Leaked scopes and GATT clients per reconnect
Connector	No MTU request on Android	V1 ASCII lines (~100 B) don't fit the default 20-byte payload
Connector	V2 reply awaited only after the write	A fast Ready/Nack could be missed
Classic	withTimeout around blocking socket.connect()	The 30 s timeout never fired
Composite	error() for an unsupported transport	AirBeam2 target on iOS would crash
Foreground service	START_STICKY with no state restore; never started	A zombie notification after process death

New design

AirBeamLink owns the one AirBeam connection for the life of the process, and it does connection work only. Sessions, their status and their data stay with the recording side.

[embedded content: AirBeam layers after the refactor]

Arrows show who calls whom. Readings travel up the same path, and AirBeamLink.readings keeps flowing across reconnects.

• Suspend calls with outcomes. connect() returns Connected or Failed(reason). configure() returns the device's own ConfigResult, adding NotConnected when there is no ready link. disconnect() ends the link and any reconnect loop.
• One job per link. Each link runs as a single job in an injected process scope. connect and disconnect are serialized by a Mutex, and each cancels and joins the previous job. Because the job lives in the link's scope, a screen that leaves doesn't cancel its connect.
• No handles in state. LinkState carries the target and the failure reason, nothing else, so it is safe to expose to UI.
• Explicit connector seam. connect returns ConnectResult instead of a fake connection that has already failed. ConnectionStatus covers one live link's life: Ready, Disconnected or DisconnectedUnexpectedly.
• Readings. AirBeamConnection.readings: Flow<SensorReading> is buffered from connect on, so nothing is lost before the engine starts collecting. For Mini V2 it carries the sync backlog too, which gives the engine one save path.
• BLE lifetimes. Per-link work runs in the scope Kable's connect() returns. The drop watcher runs in peripheral.scope, and teardown calls close().

Business rules taken from legacy

Every rule below comes from the legacy app, not from invention. They are now recorded in docs/DOMAIN_KNOWLEDGE.md §2 step 6 and §3.

Rule	Now	Legacy source
Reconnect only for a mobile session, every 2 s, no cap; stops on user disconnect	AirBeamLink.reconnect	AirBeamService.onMessageEvent, AirBeamReconnector
On reconnect, resume — don't reconfigure	resumeMobileSession	reconnectMobileSession()
Mini V2 resume: time sync, then ContinueSession if HasSavedSession, nothing if Running	BleConnection.resumeMobileSession	AirBeamMiniV2Configurator.reconnectMobileSession
V1 reading = 12-field ASCII line; battery text dropped	AirBeamProtocol.Standard.parseReading	ResponseParser, SyncableAirBeamReader
Measurement characteristics: AB3 ffe1 ffe3 ffe4 ffe5 ffe6, Mini V1 ffe4 ffe5	readingSources	AirBeam3Configurator, AirBeamMiniConfigurator
V2 stream names AirBeamMini-PM1 / AirBeamMini-PM2.5, µg/m³, device time	AirBeamProtocol.MiniV2.parseMeasurement	postLiveMeasurementEvents
MTU 517 for V1, 247 for V2 (Android)	requestMtuIfSupported	SyncableAirBeamConfigurator.MAX_MTU, V2 configurator

One deliberate split: "stop" and "standalone mode" are both link.disconnect(). Whether the session becomes FINISHED or stays DISCONNECTED is the RecordingEngine's call.

Verification

The whole shared suite passes, the Android app assembles, and the iOS simulator target compiles. None of this has been run on a real AirBeam yet.

Check	Result
ReadingParserTest (new)	10 / 10
SessionConfigTest (new, credential redaction)	3 / 3
AirBeamLinkTest (new, replaces the controller test)	18 / 18
ScanViewModelTest, CompositeAirBeamConnectorTest (ported)	4 / 4, 5 / 5
Rest of :shared:testAndroidHostTest	green
:androidApp:assembleDebug, :shared:compileKotlinIosSimulatorArm64	build OK
Mutation check: reconfigure instead of resume, and arm reconnect for fixed sessions	3 link tests fail, as they should

The link tests run on virtual time in backgroundScope, so the 2 s interval and the no-cap rule (51 attempts) are checked deterministically.

The BLE and classic connectors have no unit tests. They wrap Kable and Android sockets, so they need hardware to test.