@condorinst/mobile-bridge 0.19.2 → 0.20.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] — 2026-10-13
+
+### Added
+
+- **Address one device by `deviceId` when two share a `serialNo`.** An ActLumus
+  and an ActLumus Plus have separate serial sequences, so one account can hold
+  both with the same `serialNo`. `realTime`, `syncTime`, `deleteMemory` and
+  `deviceConnection` accept an optional `deviceId` next to `serialNo`; keep
+  sending `serialNo` as well, because an older app drops in silence a command
+  that lacks it. Requires `nativeVersion` 0.17.0, which the contract now lists
+  as the `deviceIdAddressing` capability.
+- **`deviceId` in the device events.** `deviceConnection`, `deviceNotification`
+  and `deviceLightSensors` carry an optional `deviceId`, present only when the
+  `serialNo` is shared by more than one device. The acks of `realTime`,
+  `syncTime` and `deleteMemory` echo the `deviceId` you sent and always keep
+  `serialNo`.
+- **`systemStatus.deviceSyncErrorById`**, the same errors keyed by `deviceId`
+  for every device. `deviceSyncError` leaves out a `serialNo` that two devices
+  share, since no single device owns it.
+- The contract and `docs/bridge-contract.md` document the rule in a new section,
+  and list `DEVICE_SERIAL_AMBIGUOUS` among the `sensorLog` error codes: the
+  backend answers it for a shared `serialNo`, and `sensorLog` takes no
+  `deviceId` yet.
+
+### Notes
+
+- Additive and backward-compatible: every new field is optional and older
+  clients ignore it. The model of a device is **not** carried by these events;
+  read `modelId` from the `userDevice` list.
+
 ## [0.19.2] — 2026-09-23
 
 ### Fixed

package/contract/bridge-contract.json

@@ -1,15 +1,15 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "contractVersion": "0.19.2",
+  "contractVersion": "0.20.0",
   "description": "Machine-readable contract of the Condor Canvas JS<->Native bridge. It states what the TypeScript declarations in dist/index.d.ts cannot express: which keys and commands a sandboxed client can actually reach, which ones need human confirmation, where messages are dropped in silence, the hard limits, and which capability each native version carries. The TypeScript types remain canonical for payload shapes.",
   "audience": "Developers and AI agents building the client bundle that renders inside the Canvas Home.",
 
   "versions": {
     "note": "Four independent numbers coexist. Only nativeVersion tells you what the device can do.",
-    "package": "0.19.2",
+    "package": "0.20.0",
     "shellVersion": "0.6.0",
     "clientProtocolVersion": "0.5.0",
-    "nativeVersion": "0.16.0",
+    "nativeVersion": "0.17.0",
     "capabilityDetection": {
       "how": "await BridgeClient.handshake({ clientVersion }) resolves to { shellVersion, nativeVersion, accepted }. Compare ack.nativeVersion against the minNativeVersion in capabilities[].",
       "acceptedIsAlwaysTrue": true,
@@ -101,8 +101,8 @@
     "entries": {
       "ping": { "args": {}, "requiresConfirmation": false, "repliesOn": "pingPong" },
       "userDevice": { "args": { "getFromServer": "boolean, default false" }, "requiresConfirmation": false, "repliesOn": "userDevice" },
-      "realTime": { "args": { "serialNo": "int", "value": "boolean" }, "requiresConfirmation": false, "repliesOn": "realTime", "note": "Off by default. The deviceLightSensors stream only flows while this is on." },
-      "deviceConnection": { "args": { "type": "'add' | 'remove'", "serialNo": "int" }, "requiresConfirmation": false, "repliesOn": "deviceConnection" },
+      "realTime": { "args": { "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0", "value": "boolean" }, "requiresConfirmation": false, "repliesOn": "realTime", "note": "Off by default. The deviceLightSensors stream only flows while this is on. Always send serialNo; add deviceId to address one device when two share a serialNo." },
+      "deviceConnection": { "args": { "type": "'add' | 'remove'", "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": false, "repliesOn": "deviceConnection" },
       "sensorLog": { "args": { "requestId": "string", "serialNo": "int", "bodyPart": "'wrist' | 'necklace', optional", "limit": "1..1000, optional", "startingAfter": "opaque cursor, optional", "endingBefore": "opaque cursor, optional", "startTime": "timestamp, optional, minNativeVersion 0.15.0", "endTime": "timestamp, optional, minNativeVersion 0.15.0" }, "requiresConfirmation": false, "repliesOn": "sensorLog", "prefer": "BridgeClient.fetchSensorLog(query), which correlates requestId and applies a timeout for you." },
       "openSettings": { "args": {}, "requiresConfirmation": false, "repliesOn": null },
       "requestPermission": { "args": { "permission": "string, must match a native AppPermission name" }, "requiresConfirmation": false, "repliesOn": null, "note": "There is no permission-result key. The OS shows its own prompt and the outcome reaches you as a fresh systemStatus emission." },
@@ -110,8 +110,8 @@
       "navigationState": { "args": { "canGoBack": "boolean" }, "requiresConfirmation": false, "repliesOn": null, "prefer": "BridgeClient.reportNavigation(canGoBack)" },
       "language": { "args": {}, "requiresConfirmation": false, "repliesOn": "language", "note": "Pull. The native push happens before window.CondorBridge exists, so a client that mounts later must ask.", "minNativeVersion": "0.14.0" },
       "jsError": { "args": { "message": "string", "stack": "optional", "source": "optional", "lineno": "optional", "colno": "optional" }, "requiresConfirmation": false, "repliesOn": null, "note": "Rate limited: 20 per 10 s, fields truncated at 4 KB." },
-      "syncTime": { "args": { "serialNo": "int" }, "requiresConfirmation": true, "repliesOn": "syncTime" },
-      "deleteMemory": { "args": { "serialNo": "int" }, "requiresConfirmation": true, "repliesOn": "deleteMemory" },
+      "syncTime": { "args": { "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": true, "repliesOn": "syncTime" },
+      "deleteMemory": { "args": { "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": true, "repliesOn": "deleteMemory" },
       "logout": { "args": {}, "requiresConfirmation": true, "repliesOn": null },
       "dfu": { "args": {}, "denied": true, "repliesOn": null }
     },
@@ -130,7 +130,7 @@
       "name": "sensorLog failure",
       "channel": "sensorLog key",
       "shape": { "requestId": "string", "success": false, "error": "string code" },
-      "codes": ["CONFLICTING_CURSORS", "INVALID_BODY_PART", "INVALID_LIMIT", "INVALID_START_TIME", "INVALID_END_TIME", "INVALID_TIME_RANGE", "MISSING_DEVICE_SERIAL_NO", "invalid session", "device not found for this user"],
+      "codes": ["CONFLICTING_CURSORS", "INVALID_BODY_PART", "INVALID_LIMIT", "INVALID_START_TIME", "INVALID_END_TIME", "INVALID_TIME_RANGE", "MISSING_DEVICE_SERIAL_NO", "DEVICE_SERIAL_AMBIGUOUS", "invalid session", "device not found for this user"],
       "visibility": "fetchSensorLog RESOLVES with success false. It only rejects on timeout.",
       "warning": "error is a diagnostic code, never user-facing text. Map it to your own copy."
     },
@@ -155,6 +155,7 @@
     { "feature": "languageKey", "minNativeVersion": "0.14.0", "description": "The language key and the language pull command exist." },
     { "feature": "sensorLogTimeRange", "minNativeVersion": "0.15.0", "description": "sensorLog accepts startTime and endTime." },
     { "feature": "lightSensorRawChannels", "minNativeVersion": "0.16.0", "description": "deviceLightSensors carries the raw light_sensor_* channels and the actlumus2 variant." },
+    { "feature": "deviceIdAddressing", "minNativeVersion": "0.17.0", "description": "realTime, syncTime, deleteMemory and deviceConnection accept an optional deviceId, so one device can be addressed when an ActLumus and a Plus share a serialNo; the acks echo it; deviceConnection, deviceNotification and deviceLightSensors carry it when the serialNo is shared; systemStatus adds deviceSyncErrorById." },
     { "feature": "nativeVersionRelay", "minShellVersion": "0.6.0", "description": "The shell relays nativeVersion into the sandboxed client. Below this, handshake-ack carried only shellVersion and capability detection was impossible from inside the iframe." }
   ],
 
@@ -179,23 +180,23 @@
   "verifiedAgainst": {
     "monorepo": "condorinstprogdev/mobile_applications",
     "branch": "dev_canvas",
-    "commit": "89fe1c792202ca9f066b84a63af44a6f2b993b52",
-    "verifiedOn": "2026-09-23",
+    "commit": "7a40a779d23d1ee49433982d37ebf4979444bf95",
+    "verifiedOn": "2026-10-13",
     "sources": {
-      "nativeVersion": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:32",
-      "jsToNativePayloadBytes": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:88",
-      "jsErrorPerWindow": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:93-94",
-      "jsErrorFieldBytes": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:97",
-      "acceptedIsAlwaysTrue": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:417-425",
-      "silentDropPaths": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:218-238,291-295,452-467,529-536",
+      "nativeVersion": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:38",
+      "jsToNativePayloadBytes": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:94",
+      "jsErrorPerWindow": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:99-100",
+      "jsErrorFieldBytes": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:103",
+      "acceptedIsAlwaysTrue": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:486-494",
+      "silentDropPaths": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:246-266,319-323,521-536,606-613",
       "bundleZipBytes": "apps/canvas/lib/core/config/whitelabel_bundle_limits.dart:14",
       "bundleGuards": "apps/canvas/lib/data/services/whitelabel_bundle_service.dart:227-398",
       "integrity": "apps/canvas/lib/data/services/whitelabel_bundle_service.dart:244-259",
       "sensorLogValidation": "apps/canvas/lib/domain/entities/sensor_log_entity.dart:70-85",
       "csp": "apps/canvas/web-mock-src/shell.template.html:28",
       "shellPolicy": "apps/canvas/web-mock-src/src/shell.ts:48-98",
-      "webViewPermissionDeny": "apps/canvas/lib/ui/pages/home/home_page.dart:260-268",
-      "opaqueOrigin": "apps/canvas/lib/ui/pages/home/home_page.dart:296-298"
+      "webViewPermissionDeny": "apps/canvas/lib/ui/pages/home/home_page.dart:263-271",
+      "opaqueOrigin": "apps/canvas/lib/ui/pages/home/home_page.dart:299-301"
     },
     "maintenance": "Re-verify every entry in sources before cutting a release. A published contract that drifts from the app is worse than no contract."
   }

package/dist/index.d.cts

@@ -341,7 +341,12 @@ type LightSensorsActlumus2Data = LightSensorsRawChannels & {
 };
 /**
  * Real-time light-sensor stream. Shape:
- * `{ serialNo, type, data }`.
+ * `{ serialNo, deviceId?, type, data }`.
+ *
+ * `deviceId` is the server id of the device and is **optional**: the app only
+ * sends it when more than one device on the account shares that `serialNo` (an
+ * ActLumus and an ActLumus Plus can). With a unique `serialNo` it is absent, so
+ * keep matching on `serialNo` in that case. Present from `nativeVersion` 0.17.0.
  *
  * A union discriminated by `type`, which is the `DeviceType.name` on the Dart
  * side. `data` carries **both the derived spectrum and the raw channels it came
@@ -353,27 +358,35 @@ type LightSensorsActlumus2Data = LightSensorsRawChannels & {
  */
 type DeviceLightSensorsPayload = {
     serialNo: number;
+    deviceId?: number;
     type: 'actlumus';
     data: LightSensorsActlumus1Data;
 } | {
     serialNo: number;
+    deviceId?: number;
     type: 'actlumus2';
     data: LightSensorsActlumus2Data;
 };
-/** Ack de comando `syncTime`. */
+/**
+ * Ack de comando `syncTime`. `deviceId` echoes the one you sent (see
+ * `DeviceLightSensorsPayload`); `serialNo` is always present.
+ */
 interface SyncTimeAckPayload {
     serialNo: number;
+    deviceId?: number;
     success: boolean;
 }
-/** Ack/state do toggle `realTime`. */
+/** Ack/state do toggle `realTime`. `deviceId` as in `SyncTimeAckPayload`. */
 interface RealTimeAckPayload {
     serialNo: number;
+    deviceId?: number;
     success: boolean;
     value: boolean;
 }
-/** Ack de comando `deleteMemory`. */
+/** Ack de comando `deleteMemory`. `deviceId` as in `SyncTimeAckPayload`. */
 interface DeleteMemoryAckPayload {
     serialNo: number;
+    deviceId?: number;
     success: boolean;
 }
 /**
@@ -382,6 +395,8 @@ interface DeleteMemoryAckPayload {
  */
 interface DeviceConnectionPayload {
     serialNo: number;
+    /** Only when the `serialNo` is shared by more than one device. */
+    deviceId?: number;
     isConnect: boolean;
 }
 /**
@@ -391,6 +406,8 @@ interface DeviceConnectionPayload {
  */
 interface DeviceNotificationPayload {
     serialNo: number;
+    /** Only when the `serialNo` is shared by more than one device. */
+    deviceId?: number;
     isConnect: boolean;
     message: string | null;
     messageCode: string | null;
@@ -461,7 +478,9 @@ interface SensorLogPayload {
  *
  * Emitted on attach (before your bundle exists), again right after
  * `handshake-ack`, and on every change. `deviceSyncError` maps `serialNo` to an
- * error message the app has already localized.
+ * error message the app has already localized. A `serialNo` shared by two
+ * devices has no single owner, so it is **left out** of `deviceSyncError` and
+ * only appears in `deviceSyncErrorById`.
  */
 interface SystemStatusPayload {
     bluetooth: boolean;
@@ -485,6 +504,11 @@ interface SystemStatusPayload {
      */
     missingEssentialPermissions: string[];
     deviceSyncError: Record<number, string>;
+    /**
+     * Same errors keyed by the server `deviceId`, for **every** device, shared
+     * `serialNo` included. Absent below `nativeVersion` 0.17.0, so guard it.
+     */
+    deviceSyncErrorById?: Record<number, string>;
 }
 /**
  * Arguments of the `requestPermission` command (JS → native).

package/dist/index.d.ts

@@ -341,7 +341,12 @@ type LightSensorsActlumus2Data = LightSensorsRawChannels & {
 };
 /**
  * Real-time light-sensor stream. Shape:
- * `{ serialNo, type, data }`.
+ * `{ serialNo, deviceId?, type, data }`.
+ *
+ * `deviceId` is the server id of the device and is **optional**: the app only
+ * sends it when more than one device on the account shares that `serialNo` (an
+ * ActLumus and an ActLumus Plus can). With a unique `serialNo` it is absent, so
+ * keep matching on `serialNo` in that case. Present from `nativeVersion` 0.17.0.
  *
  * A union discriminated by `type`, which is the `DeviceType.name` on the Dart
  * side. `data` carries **both the derived spectrum and the raw channels it came
@@ -353,27 +358,35 @@ type LightSensorsActlumus2Data = LightSensorsRawChannels & {
  */
 type DeviceLightSensorsPayload = {
     serialNo: number;
+    deviceId?: number;
     type: 'actlumus';
     data: LightSensorsActlumus1Data;
 } | {
     serialNo: number;
+    deviceId?: number;
     type: 'actlumus2';
     data: LightSensorsActlumus2Data;
 };
-/** Ack de comando `syncTime`. */
+/**
+ * Ack de comando `syncTime`. `deviceId` echoes the one you sent (see
+ * `DeviceLightSensorsPayload`); `serialNo` is always present.
+ */
 interface SyncTimeAckPayload {
     serialNo: number;
+    deviceId?: number;
     success: boolean;
 }
-/** Ack/state do toggle `realTime`. */
+/** Ack/state do toggle `realTime`. `deviceId` as in `SyncTimeAckPayload`. */
 interface RealTimeAckPayload {
     serialNo: number;
+    deviceId?: number;
     success: boolean;
     value: boolean;
 }
-/** Ack de comando `deleteMemory`. */
+/** Ack de comando `deleteMemory`. `deviceId` as in `SyncTimeAckPayload`. */
 interface DeleteMemoryAckPayload {
     serialNo: number;
+    deviceId?: number;
     success: boolean;
 }
 /**
@@ -382,6 +395,8 @@ interface DeleteMemoryAckPayload {
  */
 interface DeviceConnectionPayload {
     serialNo: number;
+    /** Only when the `serialNo` is shared by more than one device. */
+    deviceId?: number;
     isConnect: boolean;
 }
 /**
@@ -391,6 +406,8 @@ interface DeviceConnectionPayload {
  */
 interface DeviceNotificationPayload {
     serialNo: number;
+    /** Only when the `serialNo` is shared by more than one device. */
+    deviceId?: number;
     isConnect: boolean;
     message: string | null;
     messageCode: string | null;
@@ -461,7 +478,9 @@ interface SensorLogPayload {
  *
  * Emitted on attach (before your bundle exists), again right after
  * `handshake-ack`, and on every change. `deviceSyncError` maps `serialNo` to an
- * error message the app has already localized.
+ * error message the app has already localized. A `serialNo` shared by two
+ * devices has no single owner, so it is **left out** of `deviceSyncError` and
+ * only appears in `deviceSyncErrorById`.
  */
 interface SystemStatusPayload {
     bluetooth: boolean;
@@ -485,6 +504,11 @@ interface SystemStatusPayload {
      */
     missingEssentialPermissions: string[];
     deviceSyncError: Record<number, string>;
+    /**
+     * Same errors keyed by the server `deviceId`, for **every** device, shared
+     * `serialNo` included. Absent below `nativeVersion` 0.17.0, so guard it.
+     */
+    deviceSyncErrorById?: Record<number, string>;
 }
 /**
  * Arguments of the `requestPermission` command (JS → native).

package/docs/agent-guide.md

@@ -130,6 +130,12 @@ BridgeClient.send('realTime', { serialNo, value: true });
 
 `serialNo` is a **number**. A string is dropped in silence.
 
+Two devices can share a `serialNo` (an ActLumus and an ActLumus Plus). To act on
+one of them, send its `deviceId` **together with** `serialNo`, taken from the
+`userDevice` list: `BridgeClient.send('realTime', { serialNo, deviceId, value })`.
+A command with only the shared `serialNo` is ignored on purpose. Gate this on
+`nativeVersion` ≥ 0.17.0; details in `docs/bridge-contract.md`.
+
 In a raw channel, `null` means the channel does not exist on that hardware
 generation. It does not mean zero — `0.0` is a valid reading. Coercing `null`
 to `0` invents data, and has previously led to a confident, wrong conclusion
@@ -191,7 +197,8 @@ necessary, not sufficient.
       (`syncTime`, `deleteMemory`, `logout`) may never ack, because the person
       can decline.
 - [ ] No `localStorage`, no `fetch`, no `eval`. Not even behind a `try`.
-- [ ] `serialNo` is a number everywhere.
+- [ ] `serialNo` is a number everywhere, and a command for a device whose `serialNo`
+      repeats on the account also carries its `deviceId` (`nativeVersion` ≥ 0.17.0).
 - [ ] Errors are reported through `BridgeClient.send('jsError', …)`, the only
       channel out.
 - [ ] Tested in the browser mock with `nativeVersion === null`.

package/docs/bridge-contract.md

@@ -29,10 +29,10 @@ Four numbers coexist. Only one tells you what the device can do.
 
 | Number | Current | What it means |
 | --- | --- | --- |
-| `nativeVersion` | `0.16.0` | **The capability signal.** The bridge schema the app on this device implements. |
+| `nativeVersion` | `0.17.0` | **The capability signal.** The bridge schema the app on this device implements. |
 | `shellVersion` | `0.6.0` | The Condor shell wrapping your iframe. |
 | client protocol | `0.5.0` | The postMessage protocol `BridgeClient` speaks. |
-| package | `0.19.0` | The npm version you compiled against. |
+| package | `0.20.0` | The npm version you compiled against. |
 
 ```ts
 const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
@@ -58,6 +58,7 @@ the one you see most.
 | `language` key and the `language` pull command | `nativeVersion` ≥ 0.14.0 |
 | `sensorLog` accepts `startTime` / `endTime` | `nativeVersion` ≥ 0.15.0 |
 | `deviceLightSensors` carries raw `light_sensor_*` channels, and the `actlumus2` variant | `nativeVersion` ≥ 0.16.0 |
+| Address one device by `deviceId` when two share a `serialNo` (`realTime`, `syncTime`, `deleteMemory`, `deviceConnection`); `deviceId` in the device events; `systemStatus.deviceSyncErrorById` | `nativeVersion` ≥ 0.17.0 |
 | `nativeVersion` reaches the client at all | `shellVersion` ≥ 0.6.0 |
 
 `CHANGELOG.md` is the precise record of when each of these landed.
@@ -115,7 +116,8 @@ conclusions before.
   bluetooth: boolean; internet: boolean; permission: boolean; hasDevices: boolean;
   missingEssentialPermissions: string[];  // e.g. ["bluetoothScan", "bluetoothConnect"]
   missingOptionalPermissions: string[];   // e.g. ["notification", "backgroundLocation"]
-  deviceSyncError: Record<number, string>; // serialNo → message, already localized
+  deviceSyncError: Record<number, string>; // serialNo → message, already localized; a shared serialNo is left out
+  deviceSyncErrorById?: Record<number, string>; // deviceId → message, every device (nativeVersion ≥ 0.17.0)
 }
 ```
 
@@ -133,8 +135,8 @@ column.
 | --- | --- | --- | --- |
 | `ping` | — | no | `pingPong` |
 | `userDevice` | `{ getFromServer?: boolean }` | no | `userDevice` |
-| `realTime` | `{ serialNo: number, value: boolean }` | no | `realTime` |
-| `deviceConnection` | `{ type: 'add' \| 'remove', serialNo: number }` | no | `deviceConnection` |
+| `realTime` | `{ serialNo: number, deviceId?: number, value: boolean }` | no | `realTime` |
+| `deviceConnection` | `{ type: 'add' \| 'remove', serialNo: number, deviceId?: number }` | no | `deviceConnection` |
 | `sensorLog` | see below | no | `sensorLog` |
 | `openSettings` | — | no | — |
 | `requestPermission` | `{ permission: string }` | no | — (re-emits `systemStatus`) |
@@ -142,14 +144,40 @@ column.
 | `navigationState` | `{ canGoBack: boolean }` | no | — |
 | `language` | — | no | `language` |
 | `jsError` | `{ message, stack?, source?, lineno?, colno? }` | no | — |
-| `syncTime` | `{ serialNo: number }` | **yes** | `syncTime` |
-| `deleteMemory` | `{ serialNo: number }` | **yes** | `deleteMemory` |
+| `syncTime` | `{ serialNo: number, deviceId?: number }` | **yes** | `syncTime` |
+| `deleteMemory` | `{ serialNo: number, deviceId?: number }` | **yes** | `deleteMemory` |
 | `logout` | — | **yes** | — |
 | `dfu` | — | denied | — |
 
 `serialNo` is an integer. Passing a string makes the native side drop the
 message in silence.
 
+### Two devices with the same `serialNo`
+
+An ActLumus and an ActLumus Plus have separate serial sequences, so one account
+can hold both with the **same** `serialNo` (the server `deviceId` is always
+unique). A command that carries only `serialNo` cannot say which one you mean:
+the app **ignores it** instead of guessing, because guessing wrong would act on
+the wrong device (erasing the wrong memory, for instance).
+
+- **Send `deviceId` together with `serialNo`**, taken from the `userDevice`
+  list (`devicesConfig[].deviceId`). Always keep `serialNo` in the message: an
+  app older than 0.17.0 drops in silence a command that lacks it.
+- **Read `deviceId` when it is there.** `deviceConnection`,
+  `deviceNotification` and `deviceLightSensors` carry it **only when the
+  `serialNo` is shared**; with a unique `serialNo` it is absent and `serialNo`
+  alone identifies the device. Never treat a missing `deviceId` as "unknown
+  device".
+- **Acks always carry `serialNo`**, plus the `deviceId` you sent.
+- **`systemStatus.deviceSyncError` leaves a shared `serialNo` out**, because no
+  single device owns it. Read `deviceSyncErrorById` for every device.
+- **Gate on `nativeVersion` ≥ 0.17.0** before relying on any of this, and
+  degrade to `serialNo` only below it (where a shared `serialNo` was already
+  unaddressable).
+- `sensorLog` takes no `deviceId` yet: for a shared `serialNo` the backend
+  answers with the error code `DEVICE_SERIAL_AMBIGUOUS`. Show your own copy for
+  it; do not retry.
+
 ### Commands that need human confirmation
 
 `syncTime`, `deleteMemory` and `logout` open a modal owned by the Condor shell.

package/docs/troubleshooting.md

@@ -30,6 +30,10 @@ in the field can be several versions behind your development device.
 payload natively and drop it on mismatch. `serialNo` is an **integer**, not a
 string; `value` and `canGoBack` are **booleans**, not strings.
 
+**Also check:** if the account holds an ActLumus and an ActLumus Plus with the same
+`serialNo`, a command without `deviceId` is ignored (never guessed). Send both
+(`nativeVersion` ≥ 0.17.0).
+
 **Check:** `typeof` at the call site. `serialNo: "1234"` fails; `serialNo: 1234`
 works.
 

package/llms.txt

@@ -7,7 +7,7 @@
 > pagination, permissions, system status and language.
 
 Every URL below is plain text over HTTPS, pinned to a released version, and
-needs no authentication. Replace `0.19.2` with the version you depend on; the
+needs no authentication. Replace `0.20.0` with the version you depend on; the
 contract changes between minors while the package is below 1.0.0.
 
 The same files ship inside the npm tarball, so if you have run
@@ -16,27 +16,27 @@ The same files ship inside the npm tarball, so if you have run
 
 ## Start here
 
-- [AGENTS.md](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.2/AGENTS.md): The contract in one screen — hard rules, what is unreachable, and the validation loop. Read before writing code.
-- [Agent guide](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.2/docs/agent-guide.md): Step-by-step construction of a client Home, with the checks to run at each stage.
+- [AGENTS.md](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.20.0/AGENTS.md): The contract in one screen — hard rules, what is unreachable, and the validation loop. Read before writing code.
+- [Agent guide](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.20.0/docs/agent-guide.md): Step-by-step construction of a client Home, with the checks to run at each stage.
 
 ## Reference
 
-- [Bridge contract](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.2/docs/bridge-contract.md): Every observable key, every command, the three error shapes, and the capability matrix by native version.
-- [Machine-readable contract](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.2/contract/bridge-contract.json): The same contract as JSON. Also importable as `@condorinst/mobile-bridge/contract`.
-- [Limits](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.2/docs/limits.md): Every hard limit — payload size, rate limits, bundle size, timeouts — with what happens when you cross it.
-- [Troubleshooting](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.2/docs/troubleshooting.md): Why a command did nothing. Silence is the platform's dominant failure mode.
-- [TypeScript declarations](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.2/dist/index.d.ts): Authoritative payload shapes, with documentation on every member.
+- [Bridge contract](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.20.0/docs/bridge-contract.md): Every observable key, every command, the three error shapes, and the capability matrix by native version.
+- [Machine-readable contract](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.20.0/contract/bridge-contract.json): The same contract as JSON. Also importable as `@condorinst/mobile-bridge/contract`.
+- [Limits](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.20.0/docs/limits.md): Every hard limit — payload size, rate limits, bundle size, timeouts — with what happens when you cross it.
+- [Troubleshooting](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.20.0/docs/troubleshooting.md): Why a command did nothing. Silence is the platform's dominant failure mode.
+- [TypeScript declarations](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.20.0/dist/index.d.ts): Authoritative payload shapes, with documentation on every member.
 
 ## Guides
 
-- [Client guide](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.2/docs/client-guide.md): Narrative walkthrough for a developer building the Home by hand.
-- [Pilot onboarding](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.2/docs/pilot-onboarding.md): Checklist from zero to a bundle delivered to Condor.
-- [README](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.2/README.md): Package overview, install, quickstart.
-- [CHANGELOG](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.2/CHANGELOG.md): When each capability was introduced. The most precise record of what a given native version supports.
+- [Client guide](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.20.0/docs/client-guide.md): Narrative walkthrough for a developer building the Home by hand.
+- [Pilot onboarding](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.20.0/docs/pilot-onboarding.md): Checklist from zero to a bundle delivered to Condor.
+- [README](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.20.0/README.md): Package overview, install, quickstart.
+- [CHANGELOG](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.20.0/CHANGELOG.md): When each capability was introduced. The most precise record of what a given native version supports.
 
 ## Examples
 
-- [Minimal home](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.2/examples/minimal-home/src/main.ts): A complete, working client in ~160 lines. Copy this as your starting point.
+- [Minimal home](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.20.0/examples/minimal-home/src/main.ts): A complete, working client in ~160 lines. Copy this as your starting point.
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@condorinst/mobile-bridge",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "TypeScript SDK for the JS↔Native bridge of the Condor white-label mobile app.",
   "license": "SEE LICENSE IN LICENSE",
   "private": false,