@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/backend/cell-info.js

@@ -0,0 +1,124 @@
+// Cell-info normalization — a decoded ModemManager cell dict → a stable reading.
+//
+// `Modem.GetCellInfo` returns `aa{sv}`: one `a{sv}` dict per visible cell. The keys
+// vary by RAT and MM version, so this module pins EXACTLY the mappings the rest of
+// the stack depends on and ignores everything else:
+//
+//   - `physical-ci` → `pci`      (the real MM key; never guessed from anything else)
+//   - `rsrp`, `rsrq`             pass through as numbers
+//   - `sinr`                     the REAL NR SINR key. A dict carrying `snr` (the
+//                                WRONG name) is IGNORED — `sinr` stays undefined.
+//   - `cell-id`                  the cell identifier (serving-cell tiebreak)
+//   - `band`                     surfaced ONLY when the source supplies it directly;
+//                                never inferred from earfcn / frequency / anything.
+//   - `serving` / `cell-type`    whether this is the serving cell.
+//
+// Every reading also carries `source` + `observedAt` provenance, so a consumer can
+// tell a fresh reading from a cached one and know where it came from. Pure — no I/O.
+import { numberProp, stringProp } from './managed-objects.js';
+/** Read a `serving` flag: an explicit `serving` bool, else a `cell-type` naming it. */
+function readServing(cell) {
+    const flag = cell.find(([key]) => key === 'serving')?.[1]?.value;
+    if (typeof flag === 'boolean') {
+        return flag;
+    }
+    const cellType = stringProp(cell, 'cell-type');
+    return cellType?.toLowerCase().includes('serving') ?? false;
+}
+/** Normalize ONE cell's `a{sv}` dict into a `CellReading`, pinning the known keys. */
+export function normalizeCellReading(cell, provenance) {
+    const cellId = stringProp(cell, 'cell-id');
+    const pci = numberProp(cell, 'physical-ci');
+    const rsrp = numberProp(cell, 'rsrp');
+    const rsrq = numberProp(cell, 'rsrq');
+    // `sinr` ONLY — a dict carrying `snr` must never populate this field.
+    const sinr = numberProp(cell, 'sinr');
+    // `band` ONLY when directly supplied; never inferred.
+    const band = stringProp(cell, 'band');
+    return {
+        serving: readServing(cell),
+        ...(cellId !== undefined ? { cellId } : {}),
+        ...(pci !== undefined ? { pci } : {}),
+        ...(rsrp !== undefined ? { rsrp } : {}),
+        ...(rsrq !== undefined ? { rsrq } : {}),
+        ...(sinr !== undefined ? { sinr } : {}),
+        ...(band !== undefined ? { band } : {}),
+        source: provenance.source,
+        observedAt: provenance.observedAt,
+    };
+}
+/** Normalize a whole `GetCellInfo` reply (`aa{sv}` → cell dicts) into readings. */
+export function normalizeCellInfo(cells, provenance) {
+    return cells.map((cell) => normalizeCellReading(cell, provenance));
+}
+/**
+ * Serving-cell TOTAL order — a strict, permutation-invariant ranking of readings.
+ * Returns < 0 when `a` outranks `b` (should sort first / is the better serving cell):
+ *
+ *   1. a `serving`-marked cell outranks a non-serving one;
+ *   2. then the HIGHER `rsrp` outranks the lower — a cell with NO `rsrp` sorts LAST;
+ *   3. ties break lexicographically by `cell-id` (a cell with none sorts last);
+ *   4. final deterministic tiebreaks (`pci`, then a stable serialization) guarantee
+ *      the order is total even for otherwise-identical distinct cells, so the winner
+ *      never depends on input order.
+ */
+export function compareServing(a, b) {
+    if (a.serving !== b.serving) {
+        return a.serving ? -1 : 1;
+    }
+    const rsrpRank = compareOptionalDesc(a.rsrp, b.rsrp);
+    if (rsrpRank !== 0) {
+        return rsrpRank;
+    }
+    const cellRank = compareOptionalAsc(a.cellId, b.cellId);
+    if (cellRank !== 0) {
+        return cellRank;
+    }
+    const pciRank = compareOptionalAsc(a.pci, b.pci);
+    if (pciRank !== 0) {
+        return pciRank;
+    }
+    return stableTag(a) < stableTag(b) ? -1 : stableTag(a) > stableTag(b) ? 1 : 0;
+}
+/** Higher value first; `undefined` last. */
+function compareOptionalDesc(a, b) {
+    if (a === b)
+        return 0;
+    if (a === undefined)
+        return 1;
+    if (b === undefined)
+        return -1;
+    return b - a;
+}
+/** Lower value first; `undefined` last. Works for numbers and strings. */
+function compareOptionalAsc(a, b) {
+    if (a === b)
+        return 0;
+    if (a === undefined)
+        return 1;
+    if (b === undefined)
+        return -1;
+    return a < b ? -1 : 1;
+}
+/** A stable, order-independent fingerprint used only as the final total-order tiebreak. */
+function stableTag(reading) {
+    return JSON.stringify([
+        reading.serving,
+        reading.cellId ?? null,
+        reading.pci ?? null,
+        reading.rsrp ?? null,
+        reading.rsrq ?? null,
+        reading.sinr ?? null,
+        reading.band ?? null,
+    ]);
+}
+/**
+ * Select the serving cell under the total order above. Permutation-invariant: the
+ * same set of readings always yields the same winner regardless of their order.
+ */
+export function selectServingCell(cells) {
+    if (cells.length === 0) {
+        return undefined;
+    }
+    return cells.reduce((best, cell) => (compareServing(cell, best) < 0 ? cell : best));
+}

package/dist/backend/constants.d.ts

@@ -0,0 +1,24 @@
+/** The well-known bus name ModemManager owns. */
+export declare const MM_BUS_NAME = "org.freedesktop.ModemManager1";
+/** The root ObjectManager object path. */
+export declare const MM_ROOT_PATH = "/org/freedesktop/ModemManager1";
+/** `org.freedesktop.DBus.ObjectManager` — `GetManagedObjects`, `InterfacesAdded/Removed`. */
+export declare const OBJECT_MANAGER_IFACE = "org.freedesktop.DBus.ObjectManager";
+/** `org.freedesktop.DBus.Properties` — `PropertiesChanged`. */
+export declare const PROPERTIES_IFACE = "org.freedesktop.DBus.Properties";
+/** The root manager interface — `InhibitDevice`, `ScanDevices`, `Version`. */
+export declare const MM_MANAGER_IFACE = "org.freedesktop.ModemManager1";
+/** The core `Modem` interface. */
+export declare const MODEM_IFACE = "org.freedesktop.ModemManager1.Modem";
+/** The separate `Modem.Modem3gpp` interface (never merged into `Modem`). */
+export declare const MODEM3GPP_IFACE = "org.freedesktop.ModemManager1.Modem.Modem3gpp";
+/** `Modem.Modem3gpp.Ussd` — a SEPARATE interface a modem may omit entirely. */
+export declare const MODEM3GPP_USSD_IFACE = "org.freedesktop.ModemManager1.Modem.Modem3gpp.Ussd";
+/** The `Modem.Location` interface — GNSS capabilities, `Setup`, `GetLocation`. */
+export declare const MODEM_LOCATION_IFACE = "org.freedesktop.ModemManager1.Modem.Location";
+/** A SIM object's `Sim` interface (SIMs are separate `/SIM/<n>` objects). */
+export declare const SIM_IFACE = "org.freedesktop.ModemManager1.Sim";
+/** The bus daemon itself — `NameOwnerChanged`, `GetNameOwner`. */
+export declare const DBUS_IFACE = "org.freedesktop.DBus";
+export declare const DBUS_PATH = "/org/freedesktop/DBus";
+export declare const DBUS_DESTINATION = "org.freedesktop.DBus";

package/{src/backend/constants.ts → dist/backend/constants.js}

@@ -4,31 +4,26 @@
 // than imported from the A2.3 test fake) on purpose: `control/test-support/` is not
 // published in the npm package, so `src` must never depend on it — the observer that
 // SHIPS owns its own copy of the constants it needs.
-
 /** The well-known bus name ModemManager owns. */
 export const MM_BUS_NAME = 'org.freedesktop.ModemManager1';
-
 /** The root ObjectManager object path. */
 export const MM_ROOT_PATH = '/org/freedesktop/ModemManager1';
-
 /** `org.freedesktop.DBus.ObjectManager` — `GetManagedObjects`, `InterfacesAdded/Removed`. */
 export const OBJECT_MANAGER_IFACE = 'org.freedesktop.DBus.ObjectManager';
-
 /** `org.freedesktop.DBus.Properties` — `PropertiesChanged`. */
 export const PROPERTIES_IFACE = 'org.freedesktop.DBus.Properties';
-
 /** The root manager interface — `InhibitDevice`, `ScanDevices`, `Version`. */
 export const MM_MANAGER_IFACE = 'org.freedesktop.ModemManager1';
-
 /** The core `Modem` interface. */
 export const MODEM_IFACE = 'org.freedesktop.ModemManager1.Modem';
-
 /** The separate `Modem.Modem3gpp` interface (never merged into `Modem`). */
 export const MODEM3GPP_IFACE = 'org.freedesktop.ModemManager1.Modem.Modem3gpp';
-
+/** `Modem.Modem3gpp.Ussd` — a SEPARATE interface a modem may omit entirely. */
+export const MODEM3GPP_USSD_IFACE = `${MODEM3GPP_IFACE}.Ussd`;
+/** The `Modem.Location` interface — GNSS capabilities, `Setup`, `GetLocation`. */
+export const MODEM_LOCATION_IFACE = 'org.freedesktop.ModemManager1.Modem.Location';
 /** A SIM object's `Sim` interface (SIMs are separate `/SIM/<n>` objects). */
 export const SIM_IFACE = 'org.freedesktop.ModemManager1.Sim';
-
 /** The bus daemon itself — `NameOwnerChanged`, `GetNameOwner`. */
 export const DBUS_IFACE = 'org.freedesktop.DBus';
 export const DBUS_PATH = '/org/freedesktop/DBus';

package/dist/backend/device-classifier.d.ts

@@ -0,0 +1,46 @@
+import type { CanonicalUsbMode, ExpectedDescriptors } from '../usb-mode/index.js';
+import type { UsbDeviceSnapshot } from './usb-device-snapshot.js';
+export type { UsbDeviceSnapshot, UsbInterface } from './usb-device-snapshot.js';
+/** The four device classes. `pending-modeswitch` is distinct from `unmanaged`. */
+export type DeviceClass = 'mm-managed' | 'router-mode' | 'unmanaged' | 'pending-modeswitch';
+export type UsbNetClass = 'mm-managed' | 'router-cellular' | 'wired-ethernet' | 'unknown';
+/** A classification plus a human-readable reason (always populated). */
+export interface DeviceClassification {
+    readonly deviceClass: DeviceClass;
+    readonly reason: string;
+}
+export interface UsbNetClassification {
+    readonly deviceClass: UsbNetClass;
+    readonly reason: string;
+}
+export declare const CELLULAR_USB_VENDOR_IDS: ReadonlyMap<string, string>;
+/**
+ * Classify one USB device from its udev/sysfs snapshot. Precedence:
+ *   1. a recognized MM control port (MBIM / QMI / AT) ⇒ `mm-managed`;
+ *   2. a network tether with NO control port (ECM / NCM / RNDIS) ⇒ `router-mode`;
+ *   3. mass storage with a `usb_modeswitch` trigger ⇒ `pending-modeswitch`;
+ *   4. anything else ⇒ `unmanaged`, with an honest reason — NEVER a guessed class.
+ */
+export declare function classifyDevice(snapshot: UsbDeviceSnapshot): DeviceClassification;
+export declare function cellularVendorName(vendorId: string): string | undefined;
+export declare function cellularEvidence(device: UsbDeviceSnapshot): string | undefined;
+export declare function classifyUsbNetDevice(device: UsbDeviceSnapshot): UsbNetClassification;
+export declare function publishesGenericIdentity(device: UsbDeviceSnapshot): boolean;
+export declare function vendorLabel(device: UsbDeviceSnapshot): string;
+export declare function modelLabel(device: UsbDeviceSnapshot): string;
+export declare function unitDiscriminator(device: UsbDeviceSnapshot): string | undefined;
+/**
+ * Derive the USB composition MODE a device is currently in (for a transition's
+ * postcondition). Distinct from `classifyDevice`: this reads the data-plane
+ * composition, MBIM and RNDIS being unambiguous descriptor signatures, an ECM/NCM
+ * data interface being `ecm-ncm` only when a control/vendor port accompanies it
+ * (else it is a dumb `router-ethernet` tether), and a bare vendor interface being
+ * `qmi`. Returns `undefined` when nothing recognizable is present.
+ */
+export declare function detectUsbMode(snapshot: UsbDeviceSnapshot): CanonicalUsbMode | undefined;
+/**
+ * Whether a device presents (at least) the descriptors a catalog transition expects
+ * after re-enumeration — the descriptor half of the postcondition. Every expected
+ * interface triple must be present and `bDeviceClass` must match.
+ */
+export declare function descriptorsMatch(snapshot: UsbDeviceSnapshot, expected: ExpectedDescriptors): boolean;

package/dist/backend/device-classifier.js

@@ -0,0 +1,258 @@
+// Device classification — deciding, from a udev/sysfs snapshot alone, whether a USB
+// device is a ModemManager-manageable modem, a router-ethernet uplink MM cannot
+// control, a modem still in mass-storage installer mode, or something we simply do
+// not recognize.
+//
+// THE HONESTY RULE (draft §gap sweep, matrix §1): the classifier NEVER guesses. An
+// ambiguous descriptor set returns `unmanaged` with a truthful reason, not a
+// confident-sounding wrong class. A control-port presence — not a vendor id — decides
+// `mm-managed`; a bare vendor-specific interface with no recognized driver is NOT a
+// modem. `pending-modeswitch` is a DISTINCT state (a modem installer awaiting
+// `usb_modeswitch`), never conflated with `unmanaged`.
+//
+// SCOPE — USB ONLY: the whole input here is a `UsbDeviceSnapshot`, a udev/sysfs view of a
+// USB device. PCIe modems are out of scope by construction and get NO entry in this model —
+// a PCI `vendor:device` pair is never smuggled in as a pseudo-USB identity. The Fibocom
+// FM350 is the canonical example: it is a PCIe module (PCI `14c3:4d75`, bound by the
+// `mtk_t7xx` driver on the `wwan`/`net` subsystems, with no USB VID:PID), so it is
+// documented-deferred rather than classified here. See `docs/FM350-DECISION.md` for the
+// evidence and the three-gate ledger behind that decision.
+// USB-IF class / subclass / protocol codes used below.
+const CLASS_COMM = 0x02; // CDC communications (control interface)
+const CLASS_CDC_DATA = 0x0a;
+const CLASS_MASS_STORAGE = 0x08;
+const CLASS_WIRELESS = 0xe0; // wireless controller (RNDIS lives here)
+const CLASS_VENDOR = 0xff;
+const SUB_ACM = 0x02; // abstract control model (AT commands)
+const SUB_ECM = 0x06;
+const SUB_NCM = 0x0d;
+const SUB_MBIM = 0x0e;
+const SUB_RNDIS_WIRELESS = 0x01;
+const PROTO_VENDOR = 0xff;
+const PROTO_RNDIS = 0x03;
+const QMI_DRIVERS = new Set(['qmi_wwan']);
+const AT_DRIVERS = new Set(['option', 'qcserial', 'cdc_acm']);
+const ECM_NCM_DRIVERS = new Set(['cdc_ether', 'cdc_ncm']);
+const RNDIS_DRIVERS = new Set(['rndis_host']);
+const STORAGE_DRIVERS = new Set(['usb-storage', 'uas']);
+export const CELLULAR_USB_VENDOR_IDS = new Map([
+    ['05c6', 'Qualcomm'],
+    ['0af0', 'Option'],
+    ['1199', 'Sierra Wireless'],
+    ['12d1', 'Huawei'],
+    ['1546', 'u-blox'],
+    ['19d2', 'ZTE'],
+    ['1bbb', 'TCL/Alcatel'],
+    ['1c9e', 'Longcheer'],
+    ['1e0e', 'SIMCom'],
+    ['2c7c', 'Quectel'],
+    ['2cb7', 'Fibocom'],
+    ['413c', 'Dell'],
+]);
+function isMbimControl(i) {
+    return i.interfaceClass === CLASS_COMM && i.interfaceSubClass === SUB_MBIM;
+}
+function isQmiControl(i) {
+    return i.interfaceClass === CLASS_VENDOR && i.driver !== undefined && QMI_DRIVERS.has(i.driver);
+}
+function isAtControl(i) {
+    // Standard CDC-ACM AT port (protocol 0xff on 0x02/0x02 is RNDIS, not AT).
+    if (i.interfaceClass === CLASS_COMM &&
+        i.interfaceSubClass === SUB_ACM &&
+        i.interfaceProtocol !== PROTO_VENDOR) {
+        return true;
+    }
+    // Vendor-specific serial port bound to a known AT driver.
+    return i.interfaceClass === CLASS_VENDOR && i.driver !== undefined && AT_DRIVERS.has(i.driver);
+}
+function isRndis(i) {
+    if (i.interfaceClass === CLASS_WIRELESS &&
+        i.interfaceSubClass === SUB_RNDIS_WIRELESS &&
+        i.interfaceProtocol === PROTO_RNDIS) {
+        return true;
+    }
+    if (i.interfaceClass === CLASS_COMM &&
+        i.interfaceSubClass === SUB_ACM &&
+        i.interfaceProtocol === PROTO_VENDOR) {
+        return true;
+    }
+    return i.driver !== undefined && RNDIS_DRIVERS.has(i.driver);
+}
+function isEcmNcmData(i) {
+    if (i.interfaceClass === CLASS_COMM &&
+        (i.interfaceSubClass === SUB_ECM || i.interfaceSubClass === SUB_NCM)) {
+        return true;
+    }
+    return i.driver !== undefined && ECM_NCM_DRIVERS.has(i.driver);
+}
+function isMassStorage(i) {
+    if (i.interfaceClass === CLASS_MASS_STORAGE) {
+        return true;
+    }
+    return i.driver !== undefined && STORAGE_DRIVERS.has(i.driver);
+}
+function isVendorSpecific(i) {
+    return i.interfaceClass === CLASS_VENDOR;
+}
+function controlKind(i) {
+    if (isMbimControl(i)) {
+        return 'MBIM';
+    }
+    return isQmiControl(i) ? 'QMI' : 'AT';
+}
+/** Whether a mass-storage device is a modem awaiting `usb_modeswitch` (not a plain disk). */
+function isModeswitchCandidate(snapshot) {
+    const flag = snapshot.udevProperties?.ID_USB_MODESWITCH;
+    if (flag !== undefined && flag !== '' && flag !== '0') {
+        return true;
+    }
+    const model = (snapshot.model ?? '').toLowerCase();
+    return ['cd-rom', 'installer', 'zerocd', 'autoinstall'].some((marker) => model.includes(marker));
+}
+function unmanagedReason(snapshot, hasStorage) {
+    if (hasStorage) {
+        return 'mass-storage device with no usb_modeswitch trigger — not a recognized modem installer';
+    }
+    if (snapshot.interfaces.some(isVendorSpecific)) {
+        return 'vendor-specific interface(s) with no recognized modem driver — cannot confidently classify';
+    }
+    return 'no recognized modem control port, Ethernet tether, or installer interface';
+}
+/**
+ * Classify one USB device from its udev/sysfs snapshot. Precedence:
+ *   1. a recognized MM control port (MBIM / QMI / AT) ⇒ `mm-managed`;
+ *   2. a network tether with NO control port (ECM / NCM / RNDIS) ⇒ `router-mode`;
+ *   3. mass storage with a `usb_modeswitch` trigger ⇒ `pending-modeswitch`;
+ *   4. anything else ⇒ `unmanaged`, with an honest reason — NEVER a guessed class.
+ */
+export function classifyDevice(snapshot) {
+    const ifaces = snapshot.interfaces;
+    const control = ifaces.find((i) => isMbimControl(i) || isQmiControl(i) || isAtControl(i));
+    if (control !== undefined) {
+        return {
+            deviceClass: 'mm-managed',
+            reason: `recognized ${controlKind(control)} control interface — ModemManager-manageable`,
+        };
+    }
+    const tether = ifaces.find((i) => isRndis(i) || isEcmNcmData(i));
+    if (tether !== undefined) {
+        const kind = isRndis(tether) ? 'RNDIS' : 'ECM/NCM';
+        return {
+            deviceClass: 'router-mode',
+            reason: `${kind} Ethernet tether with no modem control port — router-ethernet class, not MM-manageable`,
+        };
+    }
+    const hasStorage = ifaces.some(isMassStorage) || snapshot.bDeviceClass === CLASS_MASS_STORAGE;
+    if (hasStorage && isModeswitchCandidate(snapshot)) {
+        return {
+            deviceClass: 'pending-modeswitch',
+            reason: 'mass-storage installer mode with a usb_modeswitch trigger — awaiting mode switch',
+        };
+    }
+    return { deviceClass: 'unmanaged', reason: unmanagedReason(snapshot, hasStorage) };
+}
+export function cellularVendorName(vendorId) {
+    return CELLULAR_USB_VENDOR_IDS.get(vendorId.toLowerCase());
+}
+export function cellularEvidence(device) {
+    const vendor = cellularVendorName(device.vendorId);
+    if (vendor !== undefined)
+        return `USB vendor ${device.vendorId} is ${vendor}, a cellular-module vendor`;
+    const modeswitch = device.udevProperties?.ID_USB_MODESWITCH;
+    if (modeswitch !== undefined && modeswitch !== '' && modeswitch !== '0')
+        return 'device carries a usb_modeswitch trigger — a mode-switching dongle';
+    return device.interfaces.some(isMassStorage)
+        ? 'device also presents a mass-storage installer interface — the ZeroCD personality of a router-mode dongle'
+        : undefined;
+}
+export function classifyUsbNetDevice(device) {
+    const control = device.interfaces.find((i) => isMbimControl(i) || isQmiControl(i) || isAtControl(i));
+    if (control !== undefined)
+        return {
+            deviceClass: 'mm-managed',
+            reason: `recognized ${controlKind(control)} control interface — ModemManager-manageable`,
+        };
+    const tether = device.interfaces.find((i) => isRndis(i) || isEcmNcmData(i) || i.interfaceClass === CLASS_CDC_DATA);
+    if (tether !== undefined) {
+        const kind = isRndis(tether) ? 'RNDIS' : 'ECM/NCM';
+        const evidence = cellularEvidence(device);
+        return evidence === undefined
+            ? {
+                deviceClass: 'wired-ethernet',
+                reason: `${kind} Ethernet tether with no modem control port and no cellular evidence — a USB network adapter`,
+            }
+            : {
+                deviceClass: 'router-cellular',
+                reason: `${kind} Ethernet tether with no modem control port; ${evidence}`,
+            };
+    }
+    return {
+        deviceClass: 'unknown',
+        reason: unmanagedReason(device, device.interfaces.some(isMassStorage) || device.bDeviceClass === CLASS_MASS_STORAGE),
+    };
+}
+export function publishesGenericIdentity(device) {
+    const manufacturer = device.manufacturer?.trim();
+    const product = device.product?.trim();
+    return Boolean(manufacturer && product && manufacturer.toLowerCase() === product.toLowerCase());
+}
+export function vendorLabel(device) {
+    const published = device.manufacturer?.trim();
+    if (published && !publishesGenericIdentity(device))
+        return published;
+    return cellularVendorName(device.vendorId) ?? device.databaseVendor?.trim() ?? device.vendorId;
+}
+export function modelLabel(device) {
+    const published = device.product?.trim();
+    if (published && !publishesGenericIdentity(device))
+        return published;
+    return device.databaseModel?.trim() ?? device.productId;
+}
+export function unitDiscriminator(device) {
+    const serial = device.serialNumber?.trim();
+    if (!serial)
+        return undefined;
+    const folded = serial.toLowerCase();
+    return folded === device.manufacturer?.trim().toLowerCase() ||
+        folded === device.product?.trim().toLowerCase()
+        ? undefined
+        : serial;
+}
+/**
+ * Derive the USB composition MODE a device is currently in (for a transition's
+ * postcondition). Distinct from `classifyDevice`: this reads the data-plane
+ * composition, MBIM and RNDIS being unambiguous descriptor signatures, an ECM/NCM
+ * data interface being `ecm-ncm` only when a control/vendor port accompanies it
+ * (else it is a dumb `router-ethernet` tether), and a bare vendor interface being
+ * `qmi`. Returns `undefined` when nothing recognizable is present.
+ */
+export function detectUsbMode(snapshot) {
+    const ifaces = snapshot.interfaces;
+    if (ifaces.some(isMbimControl)) {
+        return 'mbim';
+    }
+    if (ifaces.some(isRndis)) {
+        return 'rndis';
+    }
+    if (ifaces.some(isEcmNcmData)) {
+        const hasControl = ifaces.some((i) => isAtControl(i) || isVendorSpecific(i));
+        return hasControl ? 'ecm-ncm' : 'router-ethernet';
+    }
+    if (ifaces.some((i) => isQmiControl(i) || isVendorSpecific(i))) {
+        return 'qmi';
+    }
+    return undefined;
+}
+/**
+ * Whether a device presents (at least) the descriptors a catalog transition expects
+ * after re-enumeration — the descriptor half of the postcondition. Every expected
+ * interface triple must be present and `bDeviceClass` must match.
+ */
+export function descriptorsMatch(snapshot, expected) {
+    if (snapshot.bDeviceClass !== expected.deviceClass) {
+        return false;
+    }
+    return expected.interfaces.every((exp) => snapshot.interfaces.some((i) => i.interfaceClass === exp.interfaceClass &&
+        i.interfaceSubClass === exp.interfaceSubClass &&
+        i.interfaceProtocol === exp.interfaceProtocol));
+}

package/dist/backend/enrichment.d.ts

@@ -0,0 +1,28 @@
+import type { CellReading } from './cell-info.js';
+import type { DecodedManagedObjects } from './managed-objects.js';
+import type { SignalCadence } from './signal-setup.js';
+/** eSIM provisioning type — `Sim.SimType` (MMSimType), 1.20+. */
+export type SimType = 'physical' | 'esim' | 'unknown';
+/** eSIM profile status — `Sim.EsimStatus` (MMSimEsimStatus), 1.20+. */
+export type EsimStatus = 'no-profiles' | 'with-profiles' | 'unknown';
+/** The eSIM facts of a modem's active SIM. */
+export interface EsimInfo {
+    readonly simType: SimType;
+    readonly esimStatus: EsimStatus;
+}
+/** The full read-only enrichment surfaced beside a modem's lifecycle snapshot. */
+export interface ModemEnrichment {
+    /** `Modem.Revision` — firmware/hardware revision string, when present. */
+    readonly revision?: string;
+    readonly esim: EsimInfo;
+    readonly signalCadence: SignalCadence;
+    readonly cellInfo: readonly CellReading[];
+    /** The selected serving cell (total-order winner), when any cell is present. */
+    readonly servingCell?: CellReading;
+}
+/** Read `Modem.Revision`, when present. */
+export declare function readRevision(tree: DecodedManagedObjects, modemPath: string): string | undefined;
+/** Read the eSIM `SimType` / `EsimStatus` off the modem's active SIM object. */
+export declare function readEsimInfo(tree: DecodedManagedObjects, modemPath: string): EsimInfo;
+/** Assemble the full enrichment for one modem from its tree, cadence, and cell info. */
+export declare function buildEnrichment(tree: DecodedManagedObjects, modemPath: string, signalCadence: SignalCadence, cellInfo: readonly CellReading[]): ModemEnrichment;

package/dist/backend/enrichment.js

@@ -0,0 +1,59 @@
+// Read-only status enrichment — firmware revision, eSIM facts, signal cadence,
+// and normalized cell info, assembled for one modem's status surface.
+//
+// These are additive, read-only details layered on top of the lifecycle snapshot
+// (A3.1) — they never gate anything and never fail a backend start. `Modem.Revision`
+// and the eSIM `SimType` / `EsimStatus` (MM 1.20+) are read straight from the decoded
+// `GetManagedObjects` tree; `signalCadence` comes from the Signal.Setup manager; cell
+// info is normalized from a `GetCellInfo` reply by `./cell-info`.
+import { selectServingCell } from './cell-info.js';
+import { MODEM_IFACE, SIM_IFACE } from './constants.js';
+import { findInterface, followObjectPath, numberProp, stringProp } from './managed-objects.js';
+/** MMSimType (`Sim.SimType`) → the domain `SimType`. */
+function mapSimType(value) {
+    switch (value) {
+        case 1:
+            return 'physical';
+        case 2:
+            return 'esim';
+        default:
+            return 'unknown';
+    }
+}
+/** MMSimEsimStatus (`Sim.EsimStatus`) → the domain `EsimStatus`. */
+function mapEsimStatus(value) {
+    switch (value) {
+        case 1:
+            return 'no-profiles';
+        case 2:
+            return 'with-profiles';
+        default:
+            return 'unknown';
+    }
+}
+/** Read `Modem.Revision`, when present. */
+export function readRevision(tree, modemPath) {
+    const revision = stringProp(findInterface(tree, modemPath, MODEM_IFACE), 'Revision');
+    return revision !== undefined && revision.length > 0 ? revision : undefined;
+}
+/** Read the eSIM `SimType` / `EsimStatus` off the modem's active SIM object. */
+export function readEsimInfo(tree, modemPath) {
+    const modem = findInterface(tree, modemPath, MODEM_IFACE);
+    const sim = followObjectPath(tree, modem, 'Sim', SIM_IFACE);
+    return {
+        simType: mapSimType(numberProp(sim, 'SimType')),
+        esimStatus: mapEsimStatus(numberProp(sim, 'EsimStatus')),
+    };
+}
+/** Assemble the full enrichment for one modem from its tree, cadence, and cell info. */
+export function buildEnrichment(tree, modemPath, signalCadence, cellInfo) {
+    const revision = readRevision(tree, modemPath);
+    const serving = selectServingCell(cellInfo);
+    return {
+        ...(revision !== undefined ? { revision } : {}),
+        esim: readEsimInfo(tree, modemPath),
+        signalCadence,
+        cellInfo,
+        ...(serving !== undefined ? { servingCell: serving } : {}),
+    };
+}

package/dist/backend/features.d.ts

@@ -0,0 +1,61 @@
+import { type DecodedManagedObjects } from './managed-objects.js';
+/** The capabilities the D-Bus backend gates its behaviour on. */
+export interface MmFeatures {
+    /** `Modem.Physdev` present (physical topology path, 1.22+). Property-probed. */
+    readonly physdev: boolean;
+    /**
+     * Cell-info tier:
+     *   - `none`  — below 1.20, or the modem advertises no cell-info capability.
+     *   - `basic` — 1.20/1.21 `GetCellInfo`.
+     *   - `rich`  — 1.22+ (serving-type / bandwidth fields).
+     */
+    readonly cellInfo: 'none' | 'basic' | 'rich';
+    /** eSIM read model (`Sim.SimType` / `Sim.EsimStatus`), 1.20+. */
+    readonly esimStatus: boolean;
+    /** Per-modem operation serialization is available (the shared disruptive actor). */
+    readonly opSerialization: boolean;
+}
+/**
+ * What A3.2 observed about ONE modem's property surface.
+ *
+ * `properties` is the union of property NAMES seen across the modem's interfaces
+ * (built by `probeModemProperties` from a decoded `GetManagedObjects` tree). The
+ * two optional fields let a caller feed richer cell-info evidence than the static
+ * object tree carries — MM does not advertise cell-info richness as a Modem
+ * property (it comes back from the `GetCellInfo` method), so a backend that has
+ * probed cell info can pass what it saw; absent that, detection falls back to the
+ * version + `Physdev` co-introduction signal.
+ */
+export interface MmPropertyProbe {
+    /** Property names present on the observed modem (Modem + Modem3gpp + active SIM). */
+    readonly properties: ReadonlySet<string>;
+    /** Explicit "modem advertises cell info": `false` forces `cellInfo: 'none'`. */
+    readonly cellInfoAvailable?: boolean;
+    /** Cell-info field names seen in a probe; `serving-type`/`bandwidth` ⇒ `rich`. */
+    readonly cellInfoFields?: ReadonlySet<string>;
+}
+/** A parsed `major.minor` MM version. `null` when the string is not parseable. */
+export interface MmVersion {
+    readonly major: number;
+    readonly minor: number;
+}
+/**
+ * Parse an MM `Version` string (`1.20.0`, `1.24`, `1.26.0-rc1`, …) to `major.minor`.
+ * Returns `null` on anything unparseable — callers must degrade, never throw.
+ */
+export declare function parseMmVersion(version: string): MmVersion | null;
+/**
+ * Detect what an MM daemon can do from its version string AND the properties
+ * observed on a modem. Pure — no I/O, never throws (an unparseable version yields
+ * the safe floor: property-probed `physdev`, everything else off).
+ */
+export declare function detectMmFeatures(version: string, probe: MmPropertyProbe): MmFeatures;
+/**
+ * Build an `MmPropertyProbe` for one modem from a decoded `GetManagedObjects` tree:
+ * the union of property names on its `Modem`, `Modem.Modem3gpp`, and active `Sim`
+ * interfaces. Cell-info fields are not carried by the static tree, so the returned
+ * probe leaves them unset (detection falls back to version + `Physdev`).
+ */
+export declare function probeModemProperties(tree: DecodedManagedObjects, modemPath: string): MmPropertyProbe;
+/** Convenience: detect features straight off a decoded tree for one modem. */
+export declare function detectModemFeatures(version: string, tree: DecodedManagedObjects, modemPath: string): MmFeatures;