@ceralive/modem-control 0.2.0 → 1.1.0

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;

package/dist/backend/features.js

@@ -0,0 +1,109 @@
+// ModemManager feature detection — what a given MM daemon can actually do.
+//
+// A3.2 must run against MM 1.20 (the bookworm floor), 1.22, 1.24, and versions
+// nobody has shipped yet. The plan is explicit that this is NOT a version-string
+// whitelist: a version we have never seen must degrade gracefully by PROBING the
+// observed property set, never throw. So detection combines two signals:
+//
+//   - the daemon `Version` string (a floor: e.g. eSIM read model is 1.20+), and
+//   - the properties actually present on the observed modem (authoritative for
+//     `physdev` — the plan requires `physdev` be true ONLY when the `Physdev`
+//     property is really there, never merely inferred from a version number).
+//
+// Property facts pinned by the reviewed design (draft §Oracle round-2 #9 / round-4):
+//   - `Modem.Device`  carries the udev slot UID on ALL versions.
+//   - `Modem.Physdev` is the physical topology path, 1.22+ ONLY.
+//   - there is NO `PhysdevUid` property anywhere — do not look for one.
+import { MODEM_IFACE, MODEM3GPP_IFACE, SIM_IFACE } from './constants.js';
+import { findInterface, followObjectPath } from './managed-objects.js';
+const VERSION_PATTERN = /^(\d+)\.(\d+)(?:\.\d+)*/;
+/**
+ * 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 function parseMmVersion(version) {
+    const match = VERSION_PATTERN.exec(version.trim());
+    if (match === null) {
+        return null;
+    }
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    if (!Number.isSafeInteger(major) || !Number.isSafeInteger(minor)) {
+        return null;
+    }
+    return { major, minor };
+}
+/** Whether `version` is at least `major.minor` (false when unparseable). */
+function atLeast(version, major, minor) {
+    if (version === null) {
+        return false;
+    }
+    return version.major > major || (version.major === major && version.minor >= minor);
+}
+/** MM baseline this stack supports — eSIM read model, `GetCellInfo`, Signal.Setup. */
+const MM_MIN = { major: 1, minor: 20 };
+/** Physdev + rich cell-info were co-introduced at 1.22. */
+const MM_RICH = { major: 1, minor: 22 };
+function detectCellInfo(probe, supported, modern, physdev) {
+    // Version floor first: below 1.20 there is no GetCellInfo at all.
+    if (!supported) {
+        return 'none';
+    }
+    // A modem that explicitly advertises no cell-info capability degrades to none,
+    // even on a version that would otherwise support it.
+    if (probe.cellInfoAvailable === false) {
+        return 'none';
+    }
+    const fields = probe.cellInfoFields;
+    if (fields !== undefined && (fields.has('serving-type') || fields.has('bandwidth'))) {
+        return 'rich';
+    }
+    // 1.22 co-introduced `Physdev` and the rich cell-info fields, so either signal
+    // promotes the tier — this is what makes an unseen future version (e.g. 1.26)
+    // resolve to `rich` by probing rather than by matching a whitelist.
+    if (modern || physdev) {
+        return 'rich';
+    }
+    return 'basic';
+}
+/**
+ * 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 function detectMmFeatures(version, probe) {
+    const parsed = parseMmVersion(version);
+    const supported = atLeast(parsed, MM_MIN.major, MM_MIN.minor);
+    const modern = atLeast(parsed, MM_RICH.major, MM_RICH.minor);
+    // `physdev` is property-authoritative: present iff the `Physdev` property is
+    // really in the observed set (never inferred from the version alone).
+    const physdev = probe.properties.has('Physdev');
+    const esimStatus = probe.properties.has('SimType') || probe.properties.has('EsimStatus') || supported;
+    const cellInfo = detectCellInfo(probe, supported, modern, physdev);
+    return { physdev, cellInfo, esimStatus, opSerialization: supported };
+}
+/**
+ * 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 function probeModemProperties(tree, modemPath) {
+    const modem = findInterface(tree, modemPath, MODEM_IFACE);
+    const modem3gpp = findInterface(tree, modemPath, MODEM3GPP_IFACE);
+    const sim = followObjectPath(tree, modem, 'Sim', SIM_IFACE);
+    const properties = new Set();
+    for (const source of [modem, modem3gpp, sim]) {
+        if (source === undefined) {
+            continue;
+        }
+        for (const [name] of source) {
+            properties.add(name);
+        }
+    }
+    return { properties };
+}
+/** Convenience: detect features straight off a decoded tree for one modem. */
+export function detectModemFeatures(version, tree, modemPath) {
+    return detectMmFeatures(version, probeModemProperties(tree, modemPath));
+}